استكشاف أخطاء Gateway وإصلاحها
هذه الصفحة هي دليل التشغيل المتعمق. ابدأ من /help/troubleshooting إذا كنت تريد مسار الفرز السريع أولًا.تسلسل الأوامر
شغّل هذه الأوامر أولًا، بهذا الترتيب:- يعرض
openclaw gateway statusالقيمتينRuntime: runningوRPC probe: ok. - يبلّغ
openclaw doctorعن عدم وجود مشكلات إعداد/خدمة معيقة. - يعرض
openclaw channels status --probeحالة النقل المباشرة لكل حساب، ونتائج الفحص/التدقيق حيثما كان ذلك مدعومًا، مثلworksأوaudit ok.
Anthropic 429 يتطلب استخدامًا إضافيًا للسياق الطويل
استخدم هذا القسم عندما تتضمن السجلات/الأخطاء:HTTP 429: rate_limit_error: Extra usage is required for long context requests.
- أن نموذج Anthropic Opus/Sonnet المحدد يحتوي على
params.context1m: true. - أن بيانات اعتماد Anthropic الحالية غير مؤهلة لاستخدام السياق الطويل.
- أن الطلبات تفشل فقط في الجلسات الطويلة أو تشغيلات النماذج التي تحتاج إلى مسار 1M التجريبي.
- عطّل
context1mلذلك النموذج للرجوع إلى نافذة السياق العادية. - استخدم بيانات اعتماد Anthropic مؤهلة لطلبات السياق الطويل، أو بدّل إلى مفتاح Anthropic API.
- اضبط نماذج احتياطية حتى تستمر التشغيلات عندما تُرفض طلبات Anthropic للسياق الطويل.
- /providers/anthropic
- /reference/token-use
- /help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic
خلفية محلية متوافقة مع OpenAI تجتاز الفحوصات المباشرة لكن تشغيلات الوكيل تفشل
استخدم هذا القسم عندما:- ينجح
curl ... /v1/models - تنجح استدعاءات
/v1/chat/completionsالمباشرة الصغيرة - تفشل تشغيلات نماذج OpenClaw فقط أثناء أدوار الوكيل العادية
- أن الاستدعاءات المباشرة الصغيرة تنجح، لكن تشغيلات OpenClaw تفشل فقط مع المطالبات الأكبر
- أخطاء في الخلفية بشأن توقّع
messages[].contentأن يكون سلسلة نصية - تعطل الخلفية الذي يظهر فقط مع أعداد أكبر من رموز المطالبات أو مطالبات وقت تشغيل الوكيل الكاملة
messages[...].content: invalid type: sequence, expected a string→ الخلفية ترفض أجزاء محتوى Chat Completions المهيكلة. الإصلاح: اضبطmodels.providers.<provider>.models[].compat.requiresStringContent: true.- تنجح الطلبات المباشرة الصغيرة، لكن تشغيلات وكلاء OpenClaw تفشل مع تعطل الخلفية/النموذج (مثل Gemma على بعض إصدارات
inferrs) → من المرجح أن نقل OpenClaw صحيح بالفعل؛ الخلفية هي التي تفشل مع شكل مطالبة وقت تشغيل الوكيل الأكبر. - تتراجع الإخفاقات بعد تعطيل الأدوات لكنها لا تختفي → كانت مخططات الأدوات جزءًا من الضغط، لكن المشكلة المتبقية ما تزال في سعة النموذج/الخادم المصدر أو في خطأ بالخلفية.
- اضبط
compat.requiresStringContent: trueللخلفيات التي لا تدعم إلا محتوى Chat Completions النصي. - اضبط
compat.supportsTools: falseللنماذج/الخلفيات التي لا تستطيع التعامل بشكل موثوق مع سطح مخطط أدوات OpenClaw. - خفّض ضغط المطالبات حيثما أمكن: bootstrap أصغر لمساحة العمل، وسجل جلسة أقصر، ونموذج محلي أخف، أو خلفية ذات دعم أقوى للسياق الطويل.
- إذا استمرت الطلبات المباشرة الصغيرة في النجاح بينما ما تزال أدوار وكيل OpenClaw تتعطل داخل الخلفية، فاعتبر ذلك قيدًا في الخادم/النموذج المصدر وقدّم بلاغ إعادة إنتاج هناك مع شكل الحمولة المقبول.
- /gateway/local-models
- /gateway/configuration
- /gateway/configuration-reference#openai-compatible-endpoints
لا توجد ردود
إذا كانت القنوات تعمل لكن لا يوجد أي رد، فتحقق من التوجيه والسياسة قبل إعادة توصيل أي شيء.- اقتران معلّق لمرسلي الرسائل المباشرة.
- اشتراط الإشارة في المجموعات (
requireMentionوmentionPatterns). - عدم تطابق قائمة السماح للقناة/المجموعة.
drop guild message (mention required→ تم تجاهل رسالة المجموعة حتى تتم الإشارة.pairing request→ يحتاج المرسل إلى الموافقة.blocked/allowlist→ تمت تصفية المرسل/القناة بواسطة السياسة.
اتصال Dashboard وControl UI
عندما يتعذر على dashboard أو Control UI الاتصال، تحقّق من عنوان URL ووضع المصادقة وافتراضات السياق الآمن.- عنوان URL الصحيح للفحص وdashboard.
- عدم تطابق وضع/رمز المصادقة بين العميل وgateway.
- استخدام HTTP حيث تكون هوية الجهاز مطلوبة.
device identity required→ سياق غير آمن أو غياب مصادقة الجهاز.origin not allowed→ قيمةOriginفي المتصفح غير موجودة فيgateway.controlUi.allowedOrigins(أو أنك تتصل من أصل متصفح غير 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الصريح، ثم رمز الجهاز المخزن، ثم رمز bootstrap. - في مسار Control UI غير المتزامن عبر Tailscale Serve، تتم مَسلسلة المحاولات الفاشلة لنفس
{scope, ip}قبل أن يسجل المحدِّد الفشل. لذلك قد تُظهر محاولتا إعادة سيئتان ومتزامنتان من العميل نفسه الرسالةretry laterفي المحاولة الثانية بدلًا من حالتي عدم تطابق عاديتين. too many failed authentication attempts (retry later)من عميل loopback ذي أصل متصفح → يتم حظر الإخفاقات المتكررة مؤقتًا من ذلكOriginالمُطبَّع نفسه؛ ويستخدم أصل localhost آخر حاوية منفصلة.unauthorizedمتكرر بعد تلك إعادة المحاولة → انجراف في الرمز المشترك/رمز الجهاز؛ حدّث إعدادات الرمز وأعِد الموافقة على رمز الجهاز أو دوّره إذا لزم الأمر.gateway connect failed:→ الهدف host/port/url غير صحيح.
خريطة سريعة لتفاصيل رموز المصادقة
استخدمerror.details.code من استجابة connect الفاشلة لاختيار الإجراء التالي:
| رمز التفاصيل | المعنى | الإجراء الموصى به |
|---|---|---|
AUTH_TOKEN_MISSING | لم يرسل العميل رمزًا مشتركًا مطلوبًا. | الصق/اضبط الرمز في العميل ثم أعد المحاولة. لمسارات dashboard: openclaw config get gateway.auth.token ثم الصقه في إعدادات Control UI. |
AUTH_TOKEN_MISMATCH | الرمز المشترك لا يطابق رمز مصادقة gateway. | إذا كانت canRetryWithDeviceToken=true، اسمح بإعادة محاولة موثوقة واحدة. تعيد محاولات الرمز المخزن مؤقتًا استخدام النطاقات المعتمدة المخزنة؛ أما المستدعون الذين يمررون deviceToken أو scopes صريحة فيحتفظون بالنطاقات المطلوبة. إذا استمر الفشل، شغّل قائمة التحقق من استرداد انجراف الرمز. |
AUTH_DEVICE_TOKEN_MISMATCH | رمز كل جهاز المخزن مؤقتًا قديم أو ملغى. | دوّر رمز الجهاز أو أعد الموافقة عليه باستخدام CLI الأجهزة، ثم أعد الاتصال. |
PAIRING_REQUIRED | هوية الجهاز معروفة لكنها غير معتمدة لهذا الدور. | وافق على الطلب المعلّق: openclaw devices list ثم openclaw devices approve <requestId>. |
- ينتظر
connect.challenge - يوقّع الحمولة المرتبطة بالتحدي
- يرسل
connect.params.device.nonceمع nonce التحدي نفسه
openclaw devices rotate / revoke / remove بشكل غير متوقع:
- يمكن لجلسات رمز الجهاز المقترن إدارة أجهزتها فقط ما لم تكن جلسة المستدعي تملك أيضًا
operator.admin - لا يمكن لـ
openclaw devices rotate --scope ...طلب نطاقات المشغّل إلا إذا كانت جلسة المستدعي تملك هذه النطاقات بالفعل
- /web/control-ui
- /gateway/configuration (أوضاع مصادقة gateway)
- /gateway/trusted-proxy-auth
- /gateway/remote
- /cli/devices
خدمة Gateway لا تعمل
استخدم هذا القسم عندما تكون الخدمة مثبّتة لكن العملية لا تظل قيد التشغيل.Runtime: stoppedمع تلميحات الخروج.- عدم تطابق إعدادات الخدمة (
Config (cli)مقابلConfig (service)). - تعارضات المنفذ/المستمع.
- عمليات تثبيت launchd/systemd/schtasks إضافية عند استخدام
--deep. - تلميحات تنظيف
Other gateway-like services detected (best effort).
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 (رمز/كلمة مرور، أو trusted-proxy حيث يكون مضبوطًا).another gateway instance is already listening/EADDRINUSE→ تعارض منفذ.Other gateway-like services detected (best effort)→ توجد وحدات launchd/systemd/schtasks قديمة أو متوازية. ينبغي لمعظم الإعدادات الاحتفاظ بـ gateway واحد لكل جهاز؛ وإذا كنت تحتاج فعلًا إلى أكثر من واحد، فاعزل المنافذ والإعدادات/الحالة/مساحة العمل. راجع /gateway#multiple-gateways-same-host.
تحذيرات فحص Gateway
استخدم هذا القسم عندما يصلopenclaw gateway probe إلى شيء ما، لكنه ما يزال يطبع كتلة تحذير.
warnings[].codeوprimaryTargetIdفي مخرجات JSON.- ما إذا كان التحذير متعلقًا بالرجوع إلى SSH، أو بوجود عدة gateway، أو بنطاقات مفقودة، أو بمراجع مصادقة غير محلولة.
SSH tunnel failed to start; falling back to direct probes.→ فشل إعداد SSH، لكن الأمر ما يزال يحاول الفحص المباشر للأهداف المضبوطة/loopback.multiple reachable gateways detected→ استجاب أكثر من هدف واحد. ويعني هذا عادةً إعدادًا مقصودًا لعدة gateway أو وجود مستمعات قديمة/مكررة.Probe diagnostics are limited by gateway scopes (missing operator.read)→ نجح الاتصال، لكن تفاصيل RPC محدودة بالنطاقات؛ قم بإقران هوية الجهاز أو استخدم بيانات اعتماد تملكoperator.read.- نص تحذير SecretRef غير المحلول في
gateway.auth.*/gateway.remote.*→ لم تكن بيانات المصادقة متاحة في مسار هذا الأمر للهدف الذي فشل.
القناة متصلة لكن الرسائل لا تتدفق
إذا كانت حالة القناة متصلة لكن تدفق الرسائل متوقف، فركّز على السياسة والأذونات وقواعد التسليم الخاصة بالقناة.- سياسة الرسائل المباشرة (
pairingأوallowlistأوopenأوdisabled). - قائمة السماح للمجموعات ومتطلبات الإشارة.
- أذونات/نطاقات API المفقودة الخاصة بالقناة.
mention required→ تم تجاهل الرسالة بسبب سياسة الإشارة في المجموعات.- آثار
pairing/ الموافقة المعلقة → لم تتم الموافقة على المرسل. missing_scope,not_in_channel,Forbidden,401/403→ مشكلة في مصادقة/أذونات القناة.
تسليم Cron وHeartbeat
إذا لم يعمل cron أو heartbeat أو لم يتم التسليم، فتحقق أولًا من حالة المجدول، ثم من هدف التسليم.- أن cron مفعّل وأن وقت الاستيقاظ التالي موجود.
- حالة سجل تشغيل المهمة (
okأوskippedأوerror). - أسباب تخطي heartbeat (
quiet-hoursأوrequests-in-flightأوalerts-disabledأوempty-heartbeat-fileأوno-tasks-due).
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.
أداة العقدة المقترنة تفشل
إذا كانت العقدة مقترنة لكن الأدوات تفشل، فاعزل حالة الواجهة الأمامية والأذونات والموافقة.- أن العقدة متصلة وتملك الإمكانات المتوقعة.
- منح أذونات نظام التشغيل للكاميرا/الميكروفون/الموقع/الشاشة.
- حالة موافقات التنفيذ وقائمة السماح.
NODE_BACKGROUND_UNAVAILABLE→ يجب أن يكون تطبيق العقدة في الواجهة الأمامية.*_PERMISSION_REQUIRED/LOCATION_PERMISSION_REQUIRED→ أذونات نظام التشغيل مفقودة.SYSTEM_RUN_DENIED: approval required→ موافقة التنفيذ معلقة.SYSTEM_RUN_DENIED: allowlist miss→ تم حظر الأمر بواسطة قائمة السماح.
أداة المتصفح تفشل
استخدم هذا القسم عندما تفشل إجراءات أداة المتصفح رغم أن gateway نفسه سليم.- ما إذا كانت
plugins.allowمضبوطة وتتضمنbrowser. - مسار ملف المتصفح التنفيذي صالح.
- إمكانية الوصول إلى ملف تعريف CDP.
- توفر Chrome المحلي لملفات التعريف
existing-session/user.
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 المضبوط على منفذ سيئ أو خارج النطاق.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→ لا يوجد هدف يمكن الوصول إليه لملف التعريف attach-only، أو أن نقطة نهاية HTTP استجابت لكن تعذر مع ذلك فتح CDP WebSocket.Playwright is not available in this gateway build; '<feature>' is unsupported.→ يفتقر تثبيت gateway الحالي إلى حزمة Playwright الكاملة؛ ما يزال من الممكن عمل لقطات ARIA ولقطات الشاشة الأساسية للصفحة، لكن التنقل ولقطات AI ولقطات العناصر بمحددات CSS وتصدير PDF تبقى غير متاحة.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من لقطة، وليس CSS--element.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 تجاوزات المهلة.response body is not supported for existing-session profiles yet.→ ما يزالresponsebodyيتطلب متصفحًا مُدارًا أو ملف تعريف CDP خامًا.- تجاوزات viewport / الوضع الداكن / اللغة / عدم الاتصال القديمة على ملفات التعريف attach-only أو CDP البعيدة → شغّل
openclaw browser stop --browser-profile <name>لإغلاق جلسة التحكم النشطة وتحرير حالة محاكاة Playwright/CDP بدون إعادة تشغيل gateway بالكامل.
إذا قمت بالترقية وتعطل شيء فجأة
تكون معظم الأعطال بعد الترقية بسبب انجراف الإعدادات أو فرض افتراضات أكثر صرامة الآن.1) تغيّر سلوك المصادقة وتجاوز عنوان URL
- إذا كانت
gateway.mode=remote، فقد تستهدف استدعاءات CLI جهة بعيدة بينما خدمتك المحلية تعمل بشكل جيد. - لا تعود استدعاءات
--urlالصريحة إلى بيانات الاعتماد المخزنة.
gateway connect failed:→ هدف URL غير صحيح.unauthorized→ يمكن الوصول إلى نقطة النهاية لكن المصادقة غير صحيحة.
2) أصبحت ضوابط الربط والمصادقة أكثر صرامة
- تحتاج عمليات الربط غير loopback (
lanأوtailnetأوcustom) إلى مسار مصادقة gateway صالح: مصادقة برمز/كلمة مرور مشتركة، أو نشرtrusted-proxyغير loopback مضبوط بشكل صحيح. - لا تستبدل المفاتيح القديمة مثل
gateway.tokenالقيمةgateway.auth.token.
refusing to bind gateway ... without auth→ ربط غير loopback بدون مسار مصادقة gateway صالح.RPC probe: failedبينما وقت التشغيل يعمل → gateway يعمل لكن يتعذر الوصول إليه باستخدام المصادقة/عنوان URL الحاليين.
3) تغيّرت حالة الاقتران وهوية الجهاز
- موافقات الأجهزة المعلقة لـ dashboard/nodes.
- موافقات اقتران الرسائل المباشرة المعلقة بعد تغييرات السياسة أو الهوية.
device identity required→ لم يتم استيفاء مصادقة الجهاز.pairing required→ يجب الموافقة على المرسل/الجهاز.