الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
الصفحة هذه تبدأ من الشيء الذي تراه، وتدلّك على السبب والحل والصفحة التي تشرحه. شغّل أولًا npx lousho doctor (ماذا يفحص)، وبعدها إذا عندك رمز خطأ (LOUSHO_...) ابحث عنه في الأخطاء.

الإعداد

”No model configured”

  • السبب: استدعيت createAgent() بدون model ولا provider، ولم تجد شيئًا في البيئة (LOUSHO_CONFIG_MISSING_PROVIDER).
  • الحل: مرّر model: 'openai/gpt-4o-mini' (أي <provider>/<model>)، أو اضبط LOUSHO_MODEL أو مفتاح provider مثل OPENAI_API_KEY.
  • للمزيد: Providers، الخطأ.

”The API key is not set”

  • السبب: متغير مفتاح الـ provider (OPENAI_API_KEY أو ANTHROPIC_API_KEY أو OPENROUTER_API_KEY) غير موجود في بيئة العملية التي تشغّل الـ agent (LOUSHO_PROVIDER_MISSING_API_KEY).
  • الحل: اضبطه، أو مرّر instance جاهز من الـ provider. npx lousho doctor يطبع set أو not set لكل مفتاح، ولا يطبع القيمة أبدًا. بادئة vendor/ في اسم الـ model هي التي تختار الـ provider؛ مع OpenRouter استخدم openrouter/<vendor>/<model> (مثال openrouter/openai/gpt-4o-mini) — model: 'openai/gpt-4o-mini' يحتاج OPENAI_API_KEY حتى لو OPENROUTER_API_KEY هو الوحيد المضبوط.
  • للمزيد: الخطأ.

”Cannot find package @ai-sdk/openai” أو “install the optional peer”

  • السبب: كل provider يعتمد على حزمة اختيارية تُحمَّل عند أول استخدام، بإصدار رئيسي يقابل إصدار ai الرئيسي عندك (LOUSHO_PEER_MISSING). نفس الخطأ يغطي باقي الـ peer dependencies الاختيارية، مثل dockerode و@modelcontextprotocol/sdk.
  • الحل: نفّذ أمر npm install الموجود في الرسالة (موجود أيضًا في error.installCommand)، أو ابحث عن إصدار ai الرئيسي عندك في جدول الاقتران.
  • للمزيد: حزم الـ providers، الـ peer dependencies الاختيارية، الخطأ.

”ai 5 is installed”

  • السبب: ai 5 غير مدعوم. الـ SDK يقبل ai ^4.3.19 أو ^6.0.0 أو ^7.0.0.
  • الحل: ثبّت واحد من هذه الإصدارات الرئيسية مع حزمة الـ provider التي تقابله في الجدول.
  • للمزيد: تثبيت الحزمة.

”Top-level await is only available in ES modules”

  • السبب: الـ quickstart يستخدم await على المستوى الأعلى، فالملف يجب أن يكون ES module.
  • الحل: سمِّ الملف .mts، أو اضبط "type": "module" في package.json.
  • للمزيد: الـ quickstart في README.

إصدار Node قديم جدًا

  • السبب: الـ SDK يحتاج Node.js 22.19 أو أحدث (engines.node).
  • الحل: حدّث Node. npx lousho doctor يقارن إصدارك مع المطلوب.
  • للمزيد: المتطلبات.

تعارض إصداري Ollama و zod

  • السبب: ollama-ai-provider-v2 (حزمة Ollama لـ ai 6 و7) تعلن zod 4 كـ peer dependency، و zod 3 لا يفي بهذا.
  • الحل: استخدم zod 4 مع ai 6 أو 7، أو ai@^4.3.19 مع ollama-ai-provider@^1.2.0.
  • للمزيد: حزم الـ providers.

Runs تنتهي بدون جواب

send() رجّعت لكن text فارغ

  • السبب: الـ run الذي يقف مبكرًا يكتمل عادي، لا يرمي خطأ. result.finishReason يقول لك السبب. هذه الحالات التي تترك text فارغ أو ناقص:
    • 'awaiting-approval': في tool call يحتاج إنسان يقرر. حلّه (البند التالي). Approvals.
    • 'max-steps': ميزانية maxSteps (الافتراضي 10) نفدت بينما الـ model كان ما زال يريد المتابعة. ارفع maxSteps أو بسّط المهمة. Finish reasons.
    • 'budget-exceeded': ميزانية في limits مثل maxTokens أو maxCostUsd انضربت؛ result.budget يقول لك أي واحدة. ارفع الحد. الميزانيات.
    • 'guardrail': guardrail على المدخلات أو المخرجات أو الأدوات حجب الـ run؛ result.guardrail يقول أي واحد. Guardrails.
    • 'output-invalid': الرد لم يطابق الـ schema المعرف في output حتى بعد خطوة الـ repair. Structured output.
  • الحل: افحص result.finishReason قبل أن تقرأ result.text.

الـ run يبدو واقف عند tool

  • السبب: هناك approval معلّق. الـ send() الموقوف يُرجع finishReason: 'awaiting-approval' مع approvalId؛ ولا شيء يعمل حتى يقرر أحد.
  • الحل: اعرض الـ calls المعلقة بـ agent.approvals.list()، ثم agent.approvals.resolve({ id, approved }).
  • للمزيد: createAgent() agents.

LOUSHO_SESSION_AWAITING_APPROVAL أو LOUSHO_SESSION_BUSY

  • السبب: الـ session الموقوفة على approval لا تقبل مدخل جديد (LOUSHO_SESSION_AWAITING_APPROVAL)؛ أو أن session.compact() أو session.clear() استُدعيت وفي turn شغّال أو في الطابور (LOUSHO_SESSION_BUSY).
  • الحل: حسم الـ approval ثم أرسل مجددًا؛ أو انتظر send() الخاصة بالـ turn (أو ألغِها)، ثم استدعِ من جديد.
  • للمزيد: بانتظار الـ approval، مشغولة.

Tools

الـ model لا يستدعي الـ tool أبدًا

  • السبب: الـ model يقرر من description الخاص بالـ tool ومن الـ input schema، فالوصف الغامض أو الحقول غير الواضحة لا تعطيه شيئًا يمشي عليه. الـ name يجب أن يطابق ^[a-zA-Z0-9_-]{1,64}$ (من 1 إلى 64 حرف: حروف وأرقام و_ و-).
  • الحل: اكتب في الـ description ما تفعله الـ tool ومتى تُستخدم، واستخدم .describe() على كل حقل إدخال.
  • للمزيد: خيارات defineTool().

الـ tool ترمي خطأ والـ run يكمل

  • السبب: هذا مقصود. الـ tool التي ترمي تعطي الـ model نتيجة خطأ ({ error, toolName, message, kind }) والـ run يكمل، كي يستطيع الـ model التعامل معها.
  • الحل: إذا كان يجب أن يوقف الخطأ الـ run، فارمِ error يمتد من PropagatingToolError؛ فهذا يرفض الـ run بدلًا من أن يكمله.
  • للمزيد: أخطاء الـ tools.

LOUSHO_TOOL_ARGS_INVALID

  • السبب: الـ model أرسل arguments لا تطابق الـ input schema للـ tool. داخل الـ run ترجع له الـ issues كنتيجة ويقدر يعيد المحاولة، فنادرًا ما ينتهي run بسببه.
  • الحل: إذا الـ model يغلط في نفس الحقل، خلّ نص .describe() أوضح. وإذا إنت استدعيت الـ tool بنفسك، صحّح الـ arguments المذكورة في الرسالة.
  • للمزيد: الخطأ.

Providers و models

Rate limits و calls غير مستقرة

  • السبب: الـ provider طبّق rate limit على الاستدعاء (LOUSHO_PROVIDER_RATE_LIMITED) أو فشل فشلًا عابرًا.
  • الحل: createAgent() أصلًا تعيد الاستدعاء الفاشل مرتين — لكن فقط لـ model مُمرّر كسلسلة provider/model أو محلول من البيئة؛ أما provider instance تمرّره إنت فلا تُعاد محاولاته إلا إذا ضبطت retry. ارفعها بـ retry: { maxRetries: 3 }، واضبط fallbackModels للانتقال إلى الـ model التالي إذا الاستدعاء ظل يفشل.
  • للمزيد: إعادة المحاولة و fallback models، الخطأ.

الـ model لا يقرأ ملفاتي

  • السبب: الـ provider المدمج يرسل الـ file part فقط لأنواع media التي يدعمها على إصدار ai الرئيسي لديك: على ai 6/7 يصل application/pdf إلى openai وanthropic (الذي يرسل text/plain أيضًا) وopenrouter. كل media type آخر — وكل ملف على ai 4 أو ollama — يرفض الاستدعاء بالخطأ LOUSHO_UNSUPPORTED_CONTENT (أو، إذا ضبطت unsupportedFiles: 'text-note' في الـ provider، يُرسَل كملاحظة نصية، [file report.pdf (application/pdf) not sent]). الصور تُرسَل.
  • الحل: استخدم ai 6 أو 7 مع media type يرسله الـ provider (راجع الجدول)، أو ضع نص الملف في الرسالة، أو أضف إلى fallbackModels إدخالًا يقبل الملف، أو استخدم subclass من الـ provider يستطيع الـ model فيه استقبال ملفات.
  • للمزيد: Multimodal input.

لا أرى reasoning الخاص بالـ model

  • السبب: الـ reasoning يُبلَّغ عنه منفصل عن الجواب، كأحداث reasoning.* في agent.stream() وكـ result.reasoning؛ وليس في result.text. الخيارات تُرسَل فقط لعائلات الـ models المعروف أنها تقبلها، وreasoning: 'none' لا يرسل شيئًا.
  • الحل: اقرأ result.reasoning أو أحداث reasoning.delta؛ ولـ model خارج العائلات المعروفة مرّر { effort, force: true }.
  • للمزيد: Reasoning.

Sandbox و MCP والنشر

Docker sandbox: “egress is unsupported”

  • السبب: SubprocessSandbox مع network: { allow } وbroker يحتاج أن يكون الـ broker المخرج الوحيد للحاوية. Docker Desktop وrootless Docker وdaemon على جهاز آخر وEngine أقدم من 25.0.5 كلها لا تستطيع أن تعطيك هذا، فلا تبدأ أي حاوية (LOUSHO_SANDBOX_EGRESS_UNSUPPORTED). الرفض مقصود، بدل فتح egress مفتوح.
  • الحل: شغّل الـ agent على Linux host عليه Docker Engine 25.0.5 أو أحدث، أو استخدم network: 'none'.
  • للمزيد: Sandboxed shell، الخطأ.

أدوات سيرفر MCP لا تظهر

  • السبب: السيرفرات تتصل عند await agent.ready() أو عند أول send() / stream()، والسيرفر الذي يفشل اتصاله يُفشِل ذلك الاستدعاء. كل tool اسمه <server>__<tool> (مثال docs__search)، فابحث عن هذا الاسم لا اسم السيرفر نفسه.
  • الحل: await agent.ready() لترى خطأ الاتصال. مع connectMcp() افحص status() التي تعطي كل سيرفر 'idle' أو 'connected' أو 'failed' أو 'needs-auth' (سيرفر oauth تطبيقه لا يزال يحتاج تسجيل دخول — راجع agent.oauth.mcpSignInUrl())؛ وonError: 'skip' يستبعد السيرفر الفاشل ويحذّر عبر logger. MCP يحتاج الـ peer dependency الاختيارية @modelcontextprotocol/sdk.
  • للمزيد: استخدام سيرفرات MCP في agent.

بناء الـ Worker يرفض الـ provider أو الـ tool

  • السبب: هدف cloudflare-worker يدعم الـ providers mock وopenai وanthropic وopenrouter، والـ tools current-date وday-name وhttp (http تصل فقط إلى الـ hosts المدرجة في binding LOUSHO_HTTP_ALLOW). أما ollama والـ tool web-fetch فغير مدعومين هناك، وlousho build يفشل بخطأ يسمي الذي رفضه.
  • الحل: استخدم provider أو tool آخر، أو ابنِ لهدف node-server أو docker.
  • للمزيد: Cloudflare Workers.

طلب مساعدة

افتح issue على https://github.com/LinuxDevil/lousho/issues. أرفق:
  • ناتج npx lousho doctor --json،
  • رمز الخطأ (LOUSHO_...) والرسالة كاملة،
  • إصدار الـ SDK (npm ls lousho) وإصدار ai عندك.
لا تلصق مفتاح API أبدًا.