استكشاف الأخطاء وإصلاحها

• model_not_found مع خادم محلي على نمط MLX/vLLM → تحقق من أن baseUrl يتضمن /v1، وأن api هو "openai-completions" لخلفيات /v1/chat/completions، وأن models.providers.<provider>.models[].id هو المعرّف المحلي المجرد لدى المزود. حدده ببادئة المزود مرة واحدة، مثلا mlx/mlx-community/Qwen3-30B-A3B-6bit؛ وأبق إدخال الفهرس كـ mlx-community/Qwen3-30B-A3B-6bit.
• messages[...].content: invalid type: sequence, expected a string → ترفض الخلفية أجزاء محتوى Chat Completions البنيوية. الإصلاح: عيّن models.providers.<provider>.models[].compat.requiresStringContent: true.
• incomplete turn detected ... stopReason=stop payloads=0 → أكملت الخلفية طلب Chat Completions لكنها لم ترجع نص مساعد مرئيا للمستخدم لذلك الدور. يعيد OpenClaw محاولة أدوار OpenAI المتوافقة الفارغة الآمنة لإعادة التشغيل مرة واحدة؛ غالبا تعني حالات الفشل المستمرة أن الخلفية تصدر محتوى فارغا/غير نصي أو تكبت نص الإجابة النهائية.
• تنجح الطلبات المباشرة الصغيرة، لكن تشغيلات وكيل OpenClaw تفشل بانهيارات في الخلفية/النموذج (مثل Gemma على بعض إصدارات inferrs) → من المرجح أن نقل OpenClaw صحيح بالفعل؛ الخلفية تفشل على شكل مطالبة وقت تشغيل الوكيل الأكبر.
• تتقلص حالات الفشل بعد تعطيل الأدوات لكنها لا تختفي → كانت مخططات الأدوات جزءا من الضغط، لكن المشكلة المتبقية ما زالت في سعة النموذج/الخادم في المنبع أو خطأ في الخلفية.

1. عيّن compat.requiresStringContent: true لخلفيات Chat Completions التي تقبل السلاسل فقط.
2. عيّن compat.supportsTools: false للنماذج/الخلفيات التي لا تستطيع التعامل مع سطح مخطط أدوات OpenClaw بشكل موثوق.
3. خفّض ضغط المطالبة حيثما أمكن: تمهيد مساحة عمل أصغر، سجل جلسة أقصر، نموذج محلي أخف، أو خلفية بدعم أقوى للسياق الطويل.
4. إذا استمرت الطلبات المباشرة الصغيرة في النجاح بينما لا تزال أدوار وكيل OpenClaw تنهار داخل الخلفية، فتعامل معها كقيد في الخادم/النموذج في المنبع وقدّم إعادة إنتاج هناك مع شكل الحمولة المقبول.

• device identity required → سياق غير آمن أو مصادقة جهاز مفقودة.
• origin not allowed → قيمة Origin في المتصفح ليست ضمن gateway.controlUi.allowedOrigins (أو أنك تتصل من أصل متصفح غير local loopback دون قائمة سماح صريحة).
• device nonce required / device nonce mismatch → لا يكمل العميل تدفق مصادقة الجهاز القائم على التحدي (connect.challenge + device.nonce).
• device signature invalid / device signature expired → وقّع العميل الحمولة الخاطئة (أو طابعا زمنيا قديما) للمصافحة الحالية.
• AUTH_TOKEN_MISMATCH مع canRetryWithDeviceToken=true → يمكن للعميل إجراء إعادة محاولة موثوقة واحدة باستخدام رمز جهاز مخزن مؤقتا.
• تعيد محاولة الرمز المخزن مؤقتا تلك استخدام مجموعة النطاقات المخزنة مؤقتا مع رمز الجهاز المقترن. يحافظ مستدعو deviceToken الصريح / scopes الصريحة على مجموعة النطاقات المطلوبة لديهم بدلا من ذلك.
• خارج مسار إعادة المحاولة هذا، تكون أسبقية مصادقة الاتصال هي الرمز المشترك/كلمة المرور الصريحة أولا، ثم deviceToken الصريح، ثم رمز الجهاز المخزن، ثم رمز التمهيد.
• في مسار واجهة تحكم Tailscale Serve غير المتزامن، تُسلسل المحاولات الفاشلة لنفس {scope, ip} قبل أن يسجل المحدد الفشل. لذلك يمكن لمحاولتي إعادة محاولة متزامنتين سيئتين من العميل نفسه أن تُظهرا retry later في المحاولة الثانية بدلا من عدم تطابقين عاديين.
• too many failed authentication attempts (retry later) من عميل local loopback ذي أصل متصفح → تؤدي الإخفاقات المتكررة من Origin المعياري نفسه إلى حظر مؤقت؛ يستخدم أصل localhost آخر حاوية منفصلة.
• تكرار unauthorized بعد إعادة المحاولة تلك → انحراف الرمز المشترك/رمز الجهاز؛ حدّث إعدادات الرمز وأعد الموافقة على رمز الجهاز/دوّره إذا لزم الأمر.
• gateway connect failed: → هدف مضيف/منفذ/عنوان URL خاطئ.

• Gateway start blocked: set gateway.mode=local أو existing config is missing gateway.mode → لم يتم تمكين وضع Gateway المحلي، أو تعرض ملف الإعدادات للاستبدال وفقد gateway.mode. الإصلاح: اضبط gateway.mode="local" في إعداداتك، أو أعد تشغيل openclaw onboard --mode local / openclaw setup لإعادة ختم إعدادات الوضع المحلي المتوقعة. إذا كنت تشغّل OpenClaw عبر Podman، فإن مسار الإعدادات الافتراضي هو ~/.openclaw/openclaw.json.
• refusing to bind gateway ... without auth → ربط بغير loopback دون مسار مصادقة Gateway صالح (رمز/كلمة مرور، أو وكيل موثوق عند تهيئته).
• another gateway instance is already listening / EADDRINUSE → تعارض منفذ.
• Other gateway-like services detected (best effort) → توجد وحدات launchd/systemd/schtasks قديمة أو متوازية. ينبغي لمعظم الإعدادات الاحتفاظ بـ Gateway واحد لكل جهاز؛ وإذا كنت تحتاج فعلا إلى أكثر من واحد، فاعزل المنافذ + الإعدادات/الحالة/مساحة العمل. راجع /gateway#multiple-gateways-same-host.
• System-level OpenClaw gateway service detected من doctor → توجد وحدة systemd على مستوى النظام بينما خدمة مستوى المستخدم مفقودة. أزل النسخة المكررة أو عطّلها قبل السماح لـ doctor بتثبيت خدمة مستخدم، أو اضبط OPENCLAW_SERVICE_REPAIR_POLICY=external إذا كانت وحدة النظام هي المشرف المقصود.
• Gateway service port does not match current gateway config → ما زال المشرف المثبت يثبت --port القديم. شغّل openclaw doctor --fix أو openclaw gateway install --force، ثم أعد تشغيل خدمة Gateway.

• لم تجتز الإعدادات التحقق أثناء بدء التشغيل أو إعادة التحميل الساخنة أو كتابة يملكها OpenClaw.
• يفشل بدء تشغيل Gateway بشكل مغلق بدلا من إعادة كتابة openclaw.json.
• تتخطى إعادة التحميل الساخنة التعديلات الخارجية غير الصالحة وتُبقي إعدادات وقت التشغيل الحالية نشطة.
• ترفض الكتابات التي يملكها OpenClaw الحمولات غير الصالحة/المتلفة قبل الالتزام وتحفظ .rejected.*.
• يملك openclaw doctor --fix الإصلاح. يمكنه إزالة بادئات غير JSON أو استعادة آخر نسخة معروفة سليمة مع الحفاظ على الحمولة المرفوضة بصيغة .clobbered.*.

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

• وجود .clobbered.* → احتفظ doctor بتعديل خارجي معطل أثناء إصلاح الإعدادات النشطة.
• وجود .rejected.* → فشلت كتابة إعدادات يملكها OpenClaw في فحوصات المخطط أو منع الاستبدال قبل الالتزام.
• Config write rejected: → حاولت الكتابة إسقاط البنية المطلوبة، أو تقليص الملف بشدة، أو حفظ إعدادات غير صالحة.
• config reload skipped (invalid config): → فشل تعديل مباشر في التحقق وتم تجاهله بواسطة Gateway قيد التشغيل.
• Invalid config at ... → فشل بدء التشغيل قبل إقلاع خدمات Gateway.
• missing-meta-vs-last-good أو gateway-mode-missing-vs-last-good أو size-drop-vs-last-good:* → رُفضت كتابة يملكها OpenClaw لأنها فقدت حقولا أو حجما مقارنة بآخر نسخة احتياطية معروفة سليمة.
• Config last-known-good promotion skipped → احتوى المرشح على عناصر نائبة لأسرار منقحة مثل ***.

1. شغّل openclaw doctor --fix للسماح لـ doctor بإصلاح الإعدادات ذات البادئة/المستبدلة أو استعادة آخر نسخة معروفة سليمة.
2. انسخ المفاتيح المقصودة فقط من .clobbered.* أو .rejected.*، ثم طبّقها باستخدام openclaw config set أو config.patch.
3. شغّل openclaw config validate قبل إعادة التشغيل.
4. إذا عدّلت يدويا، فاحتفظ بإعدادات JSON5 الكاملة، وليس الكائن الجزئي فقط الذي أردت تغييره.

• cron: scheduler disabled; jobs will not run automatically → Cron معطل.
• cron: timer tick failed → فشلت نبضة المجدول؛ تحقق من أخطاء الملفات/السجلات/وقت التشغيل.
• heartbeat skipped مع reason=quiet-hours → خارج نافذة الساعات النشطة.
• heartbeat skipped مع reason=empty-heartbeat-file → يوجد HEARTBEAT.md لكنه يحتوي فقط على أسطر فارغة / ترويسات Markdown، لذلك يتخطى OpenClaw استدعاء النموذج.
• heartbeat skipped مع reason=no-tasks-due → يحتوي HEARTBEAT.md على كتلة tasks:، لكن لا توجد أي مهام مستحقة في هذه النبضة.
• heartbeat: unknown accountId → معرّف حساب غير صالح لهدف تسليم Heartbeat.
• heartbeat skipped مع reason=dm-blocked → تم حل هدف Heartbeat إلى وجهة بنمط رسالة مباشرة بينما تم تعيين agents.defaults.heartbeat.directPolicy (أو تجاوز لكل وكيل) إلى block.

• unknown command "browser" أو unknown command 'browser' → تم استبعاد Plugin المتصفح المضمن بواسطة plugins.allow.
• أداة المتصفح مفقودة / غير متاحة بينما browser.enabled=true → يستبعد plugins.allow قيمة browser، لذلك لم يتم تحميل Plugin مطلقًا.
• Failed to start Chrome CDP on port → فشل تشغيل عملية المتصفح.
• browser.executablePath not found → المسار المكوّن غير صالح.
• browser.cdpUrl must be http(s) or ws(s) → يستخدم عنوان CDP URL المكوّن مخططًا غير مدعوم مثل file: أو ftp:.
• browser.cdpUrl has invalid port → يحتوي عنوان CDP URL المكوّن على منفذ غير صالح أو خارج النطاق.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → يفتقر تثبيت Gateway الحالي إلى تبعية وقت تشغيل المتصفح الأساسية؛ أعد تثبيت OpenClaw أو حدّثه، ثم أعد تشغيل Gateway. لا تزال لقطات ARIA ولقطات الصفحة الأساسية تعمل، لكن التنقل ولقطات AI ولقطات عناصر محدد CSS وتصدير PDF تبقى غير متاحة.

• Could not find DevToolsActivePort for chrome → تعذر على جلسة Chrome MCP الحالية الاتصال بدليل بيانات المتصفح المحدد بعد. افتح صفحة فحص المتصفح، وفعّل تصحيح الأخطاء عن بُعد، وأبقِ المتصفح مفتوحًا، ووافق على مطالبة الاتصال الأولى، ثم أعد المحاولة. إذا لم تكن حالة تسجيل الدخول مطلوبة، ففضّل ملف التعريف المُدار openclaw.
• No Chrome tabs found for profile="user" → لا يحتوي ملف تعريف اتصال Chrome MCP على أي تبويبات Chrome محلية مفتوحة.
• Remote CDP for profile "<name>" is not reachable → لا يمكن الوصول إلى نقطة نهاية CDP البعيدة المكوّنة من مضيف Gateway.
• Browser attachOnly is enabled ... not reachable أو Browser attachOnly is enabled and CDP websocket ... is not reachable → لا يحتوي ملف التعريف المخصص للاتصال فقط على هدف يمكن الوصول إليه، أو استجابت نقطة نهاية HTTP لكن تعذر فتح CDP WebSocket.

• fullPage is not supported for element screenshots → خلط طلب لقطة الشاشة --full-page مع --ref أو --element.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → يجب أن تستخدم استدعاءات لقطة شاشة Chrome MCP / existing-session التقاط الصفحة أو --ref من لقطة، وليس --element من CSS.
• existing-session file uploads do not support element selectors; use ref/inputRef. → تحتاج خطافات رفع Chrome MCP إلى مراجع لقطات، وليس محددات CSS.
• existing-session file uploads currently support one file at a time. → أرسل عملية رفع واحدة لكل استدعاء على ملفات تعريف Chrome MCP.
• existing-session dialog handling does not support timeoutMs. → لا تدعم خطافات الحوار في ملفات تعريف Chrome MCP تجاوزات المهلة.
• existing-session type does not support timeoutMs overrides. → احذف timeoutMs لـ act:type على ملفات تعريف profile="user" / Chrome MCP الحالية، أو استخدم ملف تعريف متصفح مُدار/CDP عند الحاجة إلى مهلة مخصصة.
• existing-session evaluate does not support timeoutMs overrides. → احذف timeoutMs لـ act:evaluate على ملفات تعريف profile="user" / Chrome MCP الحالية، أو استخدم ملف تعريف متصفح مُدار/CDP عند الحاجة إلى مهلة مخصصة.
• response body is not supported for existing-session profiles yet. → لا يزال responsebody يتطلب متصفحًا مُدارًا أو ملف تعريف CDP خامًا.
• تجاوزات منفذ العرض / الوضع الداكن / اللغة / عدم الاتصال القديمة على ملفات تعريف الاتصال فقط أو CDP البعيدة → شغّل openclaw browser stop --browser-profile <name> لإغلاق جلسة التحكم النشطة وتحرير حالة محاكاة Playwright/CDP دون إعادة تشغيل Gateway بالكامل.

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

ما يجب التحقق منه:

• إذا كان gateway.mode=remote، فقد تستهدف استدعاءات CLI الخدمة البعيدة بينما خدمتك المحلية سليمة.
• استدعاءات --url الصريحة لا تعود إلى بيانات الاعتماد المخزنة.

التواقيع الشائعة:

• gateway connect failed: → هدف URL خاطئ.
• unauthorized → يمكن الوصول إلى نقطة النهاية لكن المصادقة خاطئة.

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

ما يجب التحقق منه:

• تحتاج عمليات الربط خارج loopback (lan، tailnet، custom) إلى مسار مصادقة Gateway صالح: مصادقة رمز/كلمة مرور مشتركة، أو نشر trusted-proxy خارج loopback مكوّن بشكل صحيح.
• المفاتيح القديمة مثل gateway.token لا تحل محل gateway.auth.token.

التواقيع الشائعة:

• refusing to bind gateway ... without auth → ربط خارج loopback دون مسار مصادقة Gateway صالح.
• Connectivity probe: failed بينما وقت التشغيل يعمل → Gateway يعمل لكنه غير قابل للوصول بالمصادقة/عنوان URL الحاليين.

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

ما يجب التحقق منه:

• موافقات الأجهزة المعلقة للوحة التحكم/nodes.
• موافقات اقتران الرسائل المباشرة المعلقة بعد تغييرات السياسة أو الهوية.

التواقيع الشائعة:

• device identity required → لم يتم استيفاء مصادقة الجهاز.
• pairing required → يجب اعتماد المرسل/الجهاز.