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”
- السبب:
ai5 غير مدعوم. الـ 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 لـai6 و7) تعلن zod 4 كـ peer dependency، و zod 3 لا يفي بهذا. - الحل: استخدم zod 4 مع
ai6 أو 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أو محلول من البيئة؛ أماproviderinstance تمرّره إنت فلا تُعاد محاولاته إلا إذا ضبطتretry. ارفعها بـretry: { maxRetries: 3 }، واضبطfallbackModelsللانتقال إلى الـ model التالي إذا الاستدعاء ظل يفشل. - للمزيد: إعادة المحاولة و fallback models، الخطأ.
الـ model لا يقرأ ملفاتي
- السبب: الـ provider المدمج يرسل الـ file part فقط لأنواع media التي يدعمها على إصدار
aiالرئيسي لديك: علىai6/7 يصلapplication/pdfإلىopenaiوanthropic(الذي يرسلtext/plainأيضًا) وopenrouter. كل media type آخر — وكل ملف علىai4 أوollama— يرفض الاستدعاء بالخطأLOUSHO_UNSUPPORTED_CONTENT(أو، إذا ضبطتunsupportedFiles: 'text-note'في الـ provider، يُرسَل كملاحظة نصية،[file report.pdf (application/pdf) not sent]). الصور تُرسَل. - الحل: استخدم
ai6 أو 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يدعم الـ providersmockوopenaiوanthropicوopenrouter، والـ toolscurrent-dateوday-nameوhttp(httpتصل فقط إلى الـ hosts المدرجة في bindingLOUSHO_HTTP_ALLOW). أماollamaوالـ toolweb-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عندك.