English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Start here

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

إذا كان لديك دقيقتان فقط، فاستخدم هذه الصفحة كمدخل أولي للفرز.

أول 60 ثانية

شغّل هذا التسلسل الدقيق بالترتيب:

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

المخرجات الجيدة في سطر واحد:

  • openclaw status → يعرض القنوات المضبوطة ولا يُظهر أخطاء مصادقة واضحة.
  • openclaw status --all → التقرير الكامل موجود وقابل للمشاركة.
  • openclaw gateway probe → هدف الـ Gateway المتوقع قابل للوصول (Reachable: yes). يخبرك Capability: ... بمستوى المصادقة الذي استطاع الفحص إثباته، وRead probe: limited - missing scope: operator.read يعني تشخيصات متدهورة، وليس فشل اتصال.
  • openclaw gateway status → Runtime: running وConnectivity probe: ok وسطر Capability: ... معقول. استخدم --require-rpc إذا كنت تحتاج أيضًا إلى إثبات RPC بنطاق القراءة.
  • openclaw doctor → لا توجد أخطاء ضبط/خدمة مانعة.
  • openclaw channels status --probe → يعيد الـ Gateway القابل للوصول حالة النقل الحية لكل حساب إضافة إلى نتائج الفحص/التدقيق مثل works أو audit ok؛ وإذا كان الـ Gateway غير قابل للوصول، يعود الأمر إلى ملخصات الضبط فقط.
  • openclaw logs --follow → نشاط مستقر، ولا توجد أخطاء فادحة متكررة.

خطأ Anthropic 429 في السياق الطويل

إذا رأيت: HTTP 429: rate_limit_error: Extra usage is required for long context requests, فانتقل إلى /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context.

الواجهة الخلفية المحلية المتوافقة مع OpenAI تعمل مباشرة لكنها تفشل في OpenClaw

إذا كانت الواجهة الخلفية المحلية أو ذاتية الاستضافة عند /v1 تجيب على فحوصات /v1/chat/completions المباشرة الصغيرة لكنها تفشل مع openclaw infer model run أو دورات الوكيل العادية:

  1. إذا ذكر الخطأ أن messages[].content يتوقع سلسلة نصية، فاضبط models.providers.<provider>.models[].compat.requiresStringContent: true.
  2. إذا استمرت الواجهة الخلفية في الفشل فقط مع دورات وكيل OpenClaw، فاضبط models.providers.<provider>.models[].compat.supportsTools: false ثم أعد المحاولة.
  3. إذا ظلت الاستدعاءات المباشرة الصغيرة تعمل لكن مطالبات OpenClaw الأكبر تتسبب في تعطل الواجهة الخلفية، فتعامل مع المشكلة المتبقية على أنها قيدًا في نموذج/خادم المنبع وتابع في دليل التشغيل التفصيلي: /gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail

فشل تثبيت Plugin بسبب غياب امتدادات openclaw

إذا فشل التثبيت مع package.json missing openclaw.extensions، فهذا يعني أن حزمة الـ plugin تستخدم بنية قديمة لم يعد OpenClaw يقبلها.

أصلح ذلك في حزمة الـ plugin:

  1. أضف openclaw.extensions إلى package.json.
  2. وجّه الإدخالات إلى ملفات التشغيل المبنية (عادةً ./dist/index.js).
  3. أعد نشر الـ plugin وشغّل openclaw plugins install <package> مرة أخرى.

مثال:

{
  "name": "@openclaw/my-plugin",
  "version": "1.2.3",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

المرجع: بنية الـ Plugin

Plugin موجود لكنه محجوب بسبب ملكية مشبوهة

إذا أظهرت تحذيرات openclaw doctor أو الإعداد أو بدء التشغيل:

blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)
plugin present but blocked

فملفات الـ plugin مملوكة لمستخدم Unix مختلف عن العملية التي تحمّلها. لا تزل ضبط الـ plugin. أصلح ملكية الملفات أو شغّل OpenClaw بالمستخدم نفسه الذي يملك دليل الحالة.

تعمل تثبيتات Docker عادةً باسم node (uid 1000). في إعداد Docker الافتراضي، أصلح عمليات ربط المضيف:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
openclaw doctor --fix

إذا كنت تشغّل OpenClaw كجذر عمدًا، فأصلح جذر الـ plugin المُدار ليصبح بملكية الجذر بدلًا من ذلك:

sudo chown -R root:root /path/to/openclaw-config/npm
openclaw doctor --fix

مستندات أعمق:

شجرة القرار

flowchart TD
  A[OpenClaw is not working] --> B{What breaks first}
  B --> C[No replies]
  B --> D[Dashboard or Control UI will not connect]
  B --> E[Gateway will not start or service not running]
  B --> F[Channel connects but messages do not flow]
  B --> G[Cron or heartbeat did not fire or did not deliver]
  B --> H[Node is paired but camera canvas screen exec fails]
  B --> I[Browser tool fails]

  C --> C1[/No replies section/]
  D --> D1[/Control UI section/]
  E --> E1[/Gateway section/]
  F --> F1[/Channel flow section/]
  G --> G1[/Automation section/]
  H --> H1[/Node tools section/]
  I --> I1[/Browser section/]
لا توجد ردود 
openclaw status
openclaw gateway status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow

تبدو المخرجات الجيدة كما يلي:

  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only أو write-capable أو admin-capable
  • تعرض قناتك أن النقل متصل، وحيثما يكون ذلك مدعومًا، يظهر works أو audit ok في channels status --probe
  • يظهر المرسل معتمدًا (أو سياسة الرسائل المباشرة مفتوحة/قائمة سماح)

بصمات السجل الشائعة:

  • drop guild message (mention required → حجب اشتراط الإشارة الرسالة في Discord.
  • pairing request → المرسل غير معتمد وينتظر موافقة الاقتران عبر الرسائل المباشرة.
  • blocked / allowlist في سجلات القناة → تمت تصفية المرسل أو الغرفة أو المجموعة.

صفحات تفصيلية:

لوحة المعلومات أو واجهة التحكم لا تتصل 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

تبدو المخرجات الجيدة كما يلي:

  • يظهر Dashboard: http://... في openclaw gateway status
  • Connectivity probe: ok
  • Capability: read-only أو write-capable أو admin-capable
  • لا توجد حلقة مصادقة في السجلات

بصمات السجل الشائعة:

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

صفحات تفصيلية:

Gateway لا يبدأ أو الخدمة مثبّتة لكنها لا تعمل 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

تبدو المخرجات الجيدة كما يلي:

  • Service: ... (loaded)
  • Runtime: running
  • Connectivity probe: ok
  • Capability: read-only أو write-capable أو admin-capable

بصمات السجل الشائعة:

  • Gateway start blocked: set gateway.mode=local أو existing config is missing gateway.mode → وضع الـ Gateway بعيد، أو أن ملف الضبط يفتقد علامة الوضع المحلي ويجب إصلاحه.
  • refusing to bind gateway ... without auth → ربط غير local loopback بدون مسار مصادقة Gateway صالح (رمز/كلمة مرور، أو وكيل موثوق حيث يكون مضبوطًا).
  • another gateway instance is already listening أو EADDRINUSE → المنفذ مستخدم بالفعل.

صفحات تفصيلية:

القناة تتصل لكن الرسائل لا تتدفق 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

تبدو المخرجات الجيدة كما يلي:

  • نقل القناة متصل.
  • تنجح فحوصات الاقتران/قائمة السماح.
  • تُكتشف الإشارات حيث تكون مطلوبة.

بصمات السجل الشائعة:

  • mention required → حجب اشتراط الإشارة في المجموعة المعالجة.
  • pairing / pending → مرسل الرسائل المباشرة غير معتمد بعد.
  • not_in_channel أو missing_scope أو Forbidden أو 401/403 → مشكلة في رمز أذونات القناة.

صفحات تفصيلية:

Cron أو Heartbeat لم يعمل أو لم يسلّم 
openclaw status
openclaw gateway status
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw logs --follow

تبدو المخرجات الجيدة كما يلي:

  • يعرض cron.status أنه مفعّل مع الاستيقاظ التالي.
  • يعرض cron runs إدخالات ok حديثة.
  • Heartbeat مفعّل وليس خارج الساعات النشطة.

بصمات السجل الشائعة:

  • cron: scheduler disabled; jobs will not run automatically → Cron معطّل.
  • heartbeat skipped مع reason=quiet-hours → خارج الساعات النشطة المضبوطة.
  • heartbeat skipped مع reason=empty-heartbeat-file → يوجد HEARTBEAT.md لكنه يحتوي فقط على هيكل فارغ/رؤوس فقط.
  • heartbeat skipped مع reason=no-tasks-due → وضع مهام HEARTBEAT.md نشط لكن لم يحِن بعد أي من فواصل المهام.
  • heartbeat skipped مع reason=alerts-disabled → كل ظهور Heartbeat معطّل (showOk وshowAlerts وuseIndicator كلها متوقفة).
  • requests-in-flight → المسار الرئيسي مشغول؛ تم تأجيل استيقاظ Heartbeat.
  • unknown accountId → حساب هدف تسليم Heartbeat غير موجود.

صفحات تفصيلية:

Node مقترن لكن الأداة تفشل في تنفيذ camera canvas screen exec 
openclaw status
openclaw gateway status
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw logs --follow

تبدو المخرجات الجيدة كما يلي:

  • يظهر Node كمتصل ومقترن لدور node.
  • توجد الإمكانية للأمر الذي تستدعيه.
  • حالة الإذن ممنوحة للأداة.

بصمات السجل الشائعة:

  • NODE_BACKGROUND_UNAVAILABLE → أحضر تطبيق Node إلى المقدمة.
  • *_PERMISSION_REQUIRED → تم رفض/فقدان إذن نظام التشغيل.
  • SYSTEM_RUN_DENIED: approval required → موافقة exec معلقة.
  • SYSTEM_RUN_DENIED: allowlist miss → الأمر غير موجود في قائمة السماح لـ exec.

صفحات تفصيلية:

يطلب Exec الموافقة فجأة 
openclaw config get tools.exec.host
openclaw config get tools.exec.security
openclaw config get tools.exec.ask
openclaw gateway restart

ما الذي تغير:

  • إذا لم يتم تعيين tools.exec.host، تكون القيمة الافتراضية auto.
  • يتحول host=auto إلى sandbox عندما يكون وقت تشغيل sandbox نشطا، وإلى gateway خلاف ذلك.
  • host=auto للتوجيه فقط؛ وسلوك "YOLO" بلا مطالبة يأتي من security=full مع ask=off على gateway/node.
  • على gateway وnode، تكون القيمة الافتراضية غير المعينة لـ tools.exec.security هي full.
  • تكون القيمة الافتراضية غير المعينة لـ tools.exec.ask هي off.
  • النتيجة: إذا كنت ترى طلبات موافقة، فهذا يعني أن سياسة محلية للمضيف أو خاصة بالجلسة شددت exec بعيدا عن الإعدادات الافتراضية الحالية.

استعادة السلوك الافتراضي الحالي بلا موافقة:

openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw gateway restart

بدائل أكثر أمانا:

  • عيّن فقط tools.exec.host=gateway إذا كنت تريد توجيها مستقرا للمضيف.
  • استخدم security=allowlist مع ask=on-miss إذا كنت تريد exec على المضيف مع استمرار المراجعة عند غياب الأمر عن قائمة السماح.
  • فعّل وضع sandbox إذا كنت تريد أن يتحول host=auto مرة أخرى إلى sandbox.

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

  • Approval required. → الأمر ينتظر /approve ....
  • SYSTEM_RUN_DENIED: approval required → موافقة exec على مضيف Node معلقة.
  • exec host=sandbox requires a sandbox runtime for this session → اختيار sandbox ضمني/صريح لكن وضع sandbox متوقف.

صفحات تفصيلية:

تفشل أداة المتصفح 
openclaw status
openclaw gateway status
openclaw browser status
openclaw logs --follow
openclaw doctor

يبدو الإخراج الجيد هكذا:

  • تعرض حالة المتصفح running: true ومتصفحا/ملفا شخصيا مختارا.
  • يبدأ openclaw، أو يستطيع user رؤية تبويبات Chrome المحلية.

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

  • unknown command "browser" أو unknown command 'browser' → تم تعيين plugins.allow ولا يتضمن browser.
  • Failed to start Chrome CDP on port → فشل تشغيل المتصفح المحلي.
  • browser.executablePath not found → مسار الملف الثنائي المكوّن خاطئ.
  • browser.cdpUrl must be http(s) or ws(s) → يستخدم عنوان URL المكوّن لـ CDP مخططا غير مدعوم.
  • browser.cdpUrl has invalid port → يحتوي عنوان URL المكوّن لـ CDP على منفذ سيئ أو خارج النطاق.
  • No Chrome tabs found for profile="user" → لا يحتوي ملف إرفاق Chrome MCP الشخصي على تبويبات Chrome محلية مفتوحة.
  • Remote CDP for profile "<name>" is not reachable → لا يمكن الوصول إلى نقطة نهاية CDP البعيدة المكوّنة من هذا المضيف.
  • Browser attachOnly is enabled ... not reachable أو Browser attachOnly is enabled and CDP websocket ... is not reachable → لا يحتوي ملف التعريف attach-only على هدف CDP حي.
  • تجاوزات منفذ العرض / الوضع الداكن / اللغة / عدم الاتصال القديمة على ملفات تعريف attach-only أو CDP البعيدة → شغّل openclaw browser stop --browser-profile <name> لإغلاق جلسة التحكم النشطة وتحرير حالة المحاكاة دون إعادة تشغيل Gateway.

صفحات تفصيلية:

ذات صلة