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

هذا هو دليل التشغيل المتعمّق. ابدأ أولًا من /help/troubleshooting لمسار الفرز السريع.

تسلسل الأوامر

شغّل بالترتيب الآتي:

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

مؤشرات الحالة السليمة:

• openclaw gateway status يعرض Runtime: running وConnectivity probe: ok وسطر Capability: ....
• openclaw doctor لا يبلّغ عن أي مشكلات مانعة في الإعدادات أو الخدمة.
• openclaw channels status --probe يعرض حالة النقل المباشرة لكل حساب، وحيثما يكون ذلك مدعومًا، works أو audit ok.

بعد التحديث

استخدم هذا عندما ينتهي التحديث لكن Gateway متوقف، أو تكون القنوات فارغة، أو تفشل استدعاءات النموذج بأخطاء 401.

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

ابحث عن:

• Update restart في openclaw status / openclaw status --all. تتضمن عمليات التسليم المعلّقة أو الفاشلة الأمر التالي المطلوب تشغيله.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix ضمن القنوات: لا يزال إعداد القناة موجودًا، لكن تسجيل Plugin فشل قبل أن تتمكن القناة من التحميل.
• أخطاء 401 من المزوّد بعد إعادة المصادقة: يتحقق openclaw doctor --fix من ظلال مصادقة OAuth القديمة الخاصة بكل وكيل ويزيل النسخ القديمة لكي تحل جميع الوكلاء ملف التعريف المشترك الحالي.

عمليات التثبيت المنقسمة وحارس الإعدادات الأحدث

استخدم هذا عندما تتوقف خدمة Gateway بصورة غير متوقعة بعد تحديث، أو تُظهر السجلات أن أحد ملفات openclaw التنفيذية أقدم من الإصدار الذي كتب openclaw.json آخر مرة.

يضع OpenClaw ختمًا على عمليات كتابة الإعدادات باستخدام meta.lastTouchedVersion. يمكن للأوامر المخصصة للقراءة فقط فحص إعدادات كتبها إصدار أحدث من OpenClaw، لكن تغييرات العمليات والخدمات ترفض التنفيذ من ملف تنفيذي أقدم. تشمل الإجراءات المحظورة: بدء خدمة Gateway وإيقافها وإعادة تشغيلها وإلغاء تثبيتها، وإعادة تثبيت الخدمة إجباريًا، وتشغيل Gateway في وضع الخدمة، وتنظيف منفذ gateway --force.

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

عدم تطابق البروتوكول بعد التراجع

استخدم هذا عندما تستمر السجلات في طباعة protocol mismatch بعد خفض الإصدار أو التراجع. يعمل Gateway أقدم، لكن عملية عميل محلية أحدث لا تزال تعيد الاتصال بنطاق بروتوكول لا يستطيع Gateway الأقدم التعامل معه.

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

ابحث عن:

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> في سجلات Gateway.
• Established clients: في openclaw gateway status --deep أو Gateway clients في openclaw doctor --deep: عملاء TCP نشطون متصلون بمنفذ Gateway، مع معرّفات العمليات وأسطر الأوامر عندما يسمح نظام التشغيل بذلك.
• عملية عميل يشير سطر أوامرها إلى تثبيت OpenClaw الأحدث أو الغلاف الذي تراجعت عنه.

الإصلاح:

1. أوقف عملية عميل OpenClaw القديمة التي يعرضها gateway status --deep أو أعد تشغيلها.
2. أعد تشغيل التطبيقات أو الأغلفة التي تدمج OpenClaw: لوحات المعلومات المحلية، أو المحررات، أو أدوات خادم التطبيقات المساعدة، أو أغلفة openclaw logs --follow طويلة التشغيل.
3. أعد تشغيل openclaw gateway status --deep أو openclaw doctor --deep وتأكد من اختفاء معرّف عملية العميل القديم.

لا تجعل Gateway أقدم يقبل بروتوكولًا أحدث غير متوافق. تحمي ترقيات البروتوكول عقد الاتصال؛ واسترداد التراجع مشكلة تنظيف للعمليات والإصدارات.

تخطي الرابط الرمزي لـ Skill باعتباره خروجًا من المسار

استخدم هذا عندما تتضمن السجلات:

تخطي مسار Skill الخارج من جذره المُعدّ: ... reason=symlink-escape

يمثل كل جذر لـ Skill حدًا للاحتواء. يُتخطى الرابط الرمزي ضمن ~/.agents/skills أو <workspace>/.agents/skills أو <workspace>/skills أو ~/.openclaw/skills عندما يحل هدفه الحقيقي خارج ذلك الجذر، ما لم يكن الهدف موثوقًا به صراحةً.

افحص الرابط:

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

إذا كان الهدف مقصودًا، فاضبط كلاً من جذر Skill المباشر وهدف الرابط الرمزي المسموح به:

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

ثم ابدأ جلسة جديدة أو انتظر حتى يحدّث مراقب Skills حالته. أعد تشغيل Gateway إذا كانت العملية الجارية تسبق تغيير الإعدادات.

لا تستخدم أهدافًا واسعة مثل ~ أو / أو مجلد مشروع متزامن بالكامل. أبقِ allowSymlinkTargets محصورًا في جذر Skill الحقيقي الذي يحتوي أدلة SKILL.md الموثوقة.

إذا كان ينبغي لتطبيق Skill Workshop أن يكتب أيضًا عبر مسارات Skills الموثوقة المرتبطة رمزيًا في مساحة العمل، ففعّل skills.workshop.allowSymlinkTargetWrites. أبقه معطّلًا لجذور Skills المشتركة المخصصة للقراءة فقط.

ذو صلة:

• إعدادات Skills
• أمثلة الإعدادات

يتطلب خطأ Anthropic 429 استخدامًا إضافيًا للسياق الطويل

استخدم هذا عندما تتضمن السجلات أو الأخطاء: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

ابحث عن:

• نموذج Anthropic المحدد هو نموذج Claude 4.x بسياق 1M يدعم التوافر العام (Opus 4.6/4.7/4.8، Sonnet 4.6)، أو لا تزال إعدادات النموذج تحمل params.context1m: true القديم.
• بيانات اعتماد Anthropic الحالية غير مؤهلة لاستخدام السياق الطويل.
• تفشل الطلبات فقط في الجلسات الطويلة أو عمليات تشغيل النموذج التي تحتاج إلى مسار سياق 1M.

خيارات الإصلاح:

ذو صلة:

• Anthropic
• استخدام الرموز المميزة وتكاليفها
• لماذا أرى HTTP 429 من Anthropic؟

استجابات 403 المحظورة من المصدر الأعلى

استخدم هذا عندما يعيد مزوّد LLM في المصدر الأعلى استجابة 403 عامة مثل Your request was blocked.

لا تفترض أن هذه دائمًا مشكلة في إعدادات OpenClaw. قد تأتي الاستجابة من طبقة أمان في المصدر الأعلى، مثل CDN أو WAF أو قاعدة لإدارة الروبوتات أو وكيل عكسي أمام نقطة نهاية متوافقة مع OpenAI.

openclaw statusopenclaw gateway statusopenclaw logs --follow

ابحث عن:

• فشل عدة نماذج ضمن المزوّد نفسه بالطريقة ذاتها.
• نص HTML أو نص أمان عام بدلًا من خطأ API عادي من المزوّد.
• أحداث أمان من جانب المزوّد في وقت الطلب نفسه.
• نجاح اختبار curl مباشر وصغير، بينما تفشل الطلبات العادية المشكلة بأسلوب SDK.

أصلح التصفية من جانب المزوّد أولًا عندما تشير الأدلة إلى حظر من WAF/CDN. يُفضّل استخدام قاعدة سماح أو تخطٍ محدودة النطاق لمسار API الذي يستخدمه OpenClaw، وتجنب تعطيل الحماية للموقع بأكمله.

ذو صلة:

• نقاط النهاية المتوافقة مع OpenAI
• إعداد المزوّد
• السجلات

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

استخدم هذا عندما:

• يعمل curl ... /v1/models.
• تعمل استدعاءات /v1/chat/completions المباشرة الصغيرة.
• تفشل عمليات تشغيل نموذج OpenClaw فقط في أدوار الوكيل العادية.

curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"مرحبًا"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "مرحبًا" --jsonopenclaw logs --follow

ابحث عن:

• نجاح الاستدعاءات المباشرة الصغيرة، لكن عمليات OpenClaw لا تفشل إلا مع المطالبات الأكبر.
• أخطاء model_not_found أو 404 رغم أن /v1/chat/completions المباشر يعمل بمعرّف النموذج المجرد نفسه.
• أخطاء من الجزء الخلفي تفيد بأن messages[].content يتوقع سلسلة نصية.
• تحذيرات incomplete turn detected ... stopReason=stop payloads=0 متقطعة مع جزء خلفي محلي متوافق مع OpenAI.
• أعطال الجزء الخلفي التي لا تظهر إلا مع أعداد أكبر من رموز المطالبة أو مطالبات وقت تشغيل الوكيل الكاملة.

ذو صلة:

• الإعداد
• النماذج المحلية
• نقاط النهاية المتوافقة مع OpenAI

لا توجد ردود

إذا كانت القنوات تعمل ولكن لا يصل أي رد، فتحقق من التوجيه والسياسة قبل إعادة توصيل أي شيء.

openclaw statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw config get channelsopenclaw logs --follow

ابحث عن:

• اقتران معلّق لمرسلي الرسائل المباشرة.
• تقييد الإشارات في المجموعات (requireMention، mentionPatterns).
• حالات عدم التطابق في قوائم السماح للقنوات/المجموعات.

الأنماط الشائعة:

• drop guild message (mention required ← تُتجاهل رسالة المجموعة حتى حدوث إشارة.
• pairing request ← يحتاج المرسل إلى موافقة.
• blocked / allowlist ← تمت تصفية المرسل/القناة بواسطة السياسة.

مواضيع ذات صلة:

• استكشاف أخطاء القنوات وإصلاحها
• المجموعات
• الاقتران

اتصال واجهة التحكم في لوحة المعلومات

عندما يتعذر اتصال لوحة المعلومات/واجهة التحكم، تحقق من عنوان URL ووضع المصادقة وافتراضات السياق الآمن.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

ابحث عن:

• عنوان URL الصحيح للفحص وعنوان URL الصحيح للوحة المعلومات.
• عدم تطابق وضع المصادقة/الرمز المميز بين العميل وGateway.
• استخدام HTTP عندما تكون هوية الجهاز مطلوبة.

إذا تعذر على متصفح محلي الاتصال بـ 127.0.0.1:18789 بعد تحديث، فاستعد أولًا خدمة Gateway المحلية وتأكد من أنها تعرض لوحة المعلومات:

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

إذا أعاد curl محتوى HTML الخاص بـ OpenClaw، فهذا يعني أن Gateway يعمل، وعلى الأرجح أن المشكلة المتبقية هي ذاكرة التخزين المؤقت للمتصفح أو رابط عميق قديم أو حالة علامة تبويب قديمة. افتح http://127.0.0.1:18789 مباشرة وانتقل من لوحة المعلومات. إذا لم تظل الخدمة قيد التشغيل بعد إعادة التشغيل، فنفّذ openclaw gateway start وأعد التحقق من openclaw gateway status.

خريطة سريعة لرموز تفاصيل المصادقة

استخدم error.details.code من استجابة connect الفاشلة لاختيار الإجراء التالي:

فحص ترحيل مصادقة الجهاز v2:

openclaw --versionopenclaw doctoropenclaw gateway status

إذا أظهرت السجلات أخطاء nonce/التوقيع، فحدّث العميل المتصل وتحقق منه:

إذا رُفض openclaw devices rotate / revoke / remove على نحو غير متوقع:

• لا يمكن لجلسات رموز الأجهزة المقترنة إدارة سوى الجهاز الخاص بها ما لم يكن لدى المستدعي أيضًا operator.admin.
• لا يمكن لـ openclaw devices rotate --scope ... طلب سوى نطاقات المشغّل التي تحتفظ بها جلسة المستدعي بالفعل.

مواضيع ذات صلة:

• الإعداد (أوضاع مصادقة Gateway)
• واجهة التحكم
• الأجهزة
• الوصول عن بُعد
• مصادقة الوكيل الموثوق

خدمة Gateway لا تعمل

استخدم هذا عندما تكون الخدمة مثبّتة، لكن العملية لا تظل قيد التشغيل.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # افحص أيضًا الخدمات على مستوى النظام

ابحث عن:

• Runtime: stopped مع تلميحات الخروج.
• عدم تطابق إعداد الخدمة (Config (cli) مقابل Config (service)).
• تعارضات المنفذ/المستمع.
• تثبيتات إضافية لـ launchd/systemd/schtasks عند استخدام --deep.
• تلميحات تنظيف Other gateway-like services detected (best effort).

مواضيع ذات صلة:

• التنفيذ في الخلفية وأداة العمليات
• الإعداد
• Doctor

يتوقف Gateway في macOS بصمت عن الاستجابة، ثم يستأنفها عند التفاعل مع لوحة المعلومات

استخدم هذا عندما تصمت القنوات (Telegram وWhatsApp وما إلى ذلك) على مضيف macOS لمدة تتراوح من دقائق إلى ساعات في كل مرة، ويبدو أن Gateway يعود إلى العمل لحظة فتح واجهة التحكم، أو الاتصال عبر SSH، أو التفاعل مع المضيف بأي طريقة أخرى. لا توجد عادةً أعراض واضحة في openclaw status لأن Gateway يكون قد عاد إلى العمل بحلول وقت التحقق منه.

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

ابحث عن:

• حزمة واحدة أو أكثر من حزم *-uncaught_exception.json في ~/.openclaw/logs/stability/ مع ضبط error.code على رمز شبكة عابر مثل ENETDOWN أو ENETUNREACH أو EHOSTUNREACH أو ECONNREFUSED.
• أسطر pmset -g log مثل Entering Sleep state due to 'Maintenance Sleep' أو en0 driver is slow (msg: WillChangeState to 0) متزامنة مع الطوابع الزمنية للأعطال. يؤدي Power Nap / Maintenance Sleep لفترة وجيزة إلى وضع برنامج تشغيل Wi-Fi في الحالة 0؛ ويمكن أن يفشل أي connect() صادر يقع ضمن تلك النافذة مع ENETDOWN حتى على مضيف يتمتع بخلاف ذلك باتصال كامل بالشبكة.
• مخرجات launchctl print التي تعرض state = not running مع عدة runs حديثة ورمز خروج، خصوصًا عندما تكون الفجوة بين العطل والتشغيل التالي في حدود ساعة بدلًا من ثوانٍ. يطبق launchd في macOS بوابة غير موثقة للحماية من إعادة التشغيل بعد سلسلة من الأعطال، وقد تتوقف عن احترام KeepAlive=true إلى أن يعيد مُشغّل خارجي تفعيلها، مثل تسجيل الدخول التفاعلي أو اتصال لوحة المعلومات أو launchctl kickstart.

الأنماط الشائعة:

• حزمة استقرار تكون فيها error.code هي ENETDOWN أو رمزًا مماثلًا، مع توجيه مكدس الاستدعاءات إلى Node net lookupAndConnect / Socket.connect. يصنّف OpenClaw 2026.5.26 والإصدارات الأحدث هذه الأخطاء على أنها أخطاء شبكة عابرة غير ضارة، ولذلك لم تعد تنتقل إلى معالج الاستثناءات غير الملتقطة ذي المستوى الأعلى؛ إذا كان الإصدار المستخدم أقدم، فقم بالترقية أولًا.
• فترات صمت طويلة تنتهي لحظة الاتصال بواجهة التحكم أو الاتصال بالمضيف عبر SSH: نشاط المستخدم المرئي هو ما يعيد تفعيل بوابة إعادة التشغيل في launchd، وليس أي إجراء تنفذه لوحة المعلومات على Gateway.
• تزايد عدد runs على مدار اليوم دون وجود سطر received SIG*; shutting down مقابل في ~/Library/Logs/openclaw/gateway.log: تسجل عمليات إيقاف التشغيل السليمة إشارة؛ أما الأعطال العابرة فلا تفعل ذلك.

ما يجب فعله:

1. رقِّ Gateway إذا كنت تستخدم إصدارًا يسبق 2026.5.26. بعد الترقية، ستُسجّل أخطاء ENETDOWN المستقبلية على هيئة تحذيرات بدلًا من إنهاء العملية.

2. قلّل نشاط سكون الصيانة على مضيفات Mac mini / سطح المكتب المخصصة للعمل كخوادم دائمة التشغيل:

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   يقلل هذا بدرجة كبيرة من تقلب برنامج التشغيل الأساسي، لكنه لا يزيله بالكامل. قد يظل النظام ينفذ بعض عمليات سكون الصيانة للحفاظ على اتصال TCP وصيانة mDNS بغض النظر عن هذه العلامات.

3. أضف مراقبًا للحيوية حتى تُكتشف بسرعة أي سلسلة أعطال مستقبلية يوقفها launchd:

   # مثال لفحص الحيوية المدرك لـ launchd، مناسب لمهمة cron أو LaunchAgent تعمل كل 5 دقائقstate=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   الهدف هو إعادة تفعيل بوابة إعادة التشغيل خارجيًا؛ لا يكفي KeepAlive=true وحده على macOS بعد سلسلة من الأعطال.

موضوعات ذات صلة:

• ملاحظات منصة macOS
• التسجيل
• Doctor

حلقة مشرف launchd في macOS مع وحدات LaunchAgent مكررة لـ Gateway/node

استخدم هذا عندما تستمر عملية تثبيت على macOS في إعادة التشغيل كل بضع ثوانٍ، وتتقلب فحوصات صحة openclaw بين حالة سليمة وغير متاحة، ويتوقف إرسال القنوات على الرغم من أن الخدمة تبدو قيد التشغيل.

لوحظ هذا في عمليات التثبيت القديمة حيث كان كل من ai.openclaw.gateway و ai.openclaw.node من وحدات LaunchAgent نشطًا، وكان كل منهما يحقن OPENCLAW_LAUNCHD_LABEL. في هذه الحالة، يمكن لـ OpenClaw اكتشاف إشراف launchd ومحاولة إعادة تسليم مسؤولية إعادة التشغيل إلى launchd، ثم الوقوع في حلقة سريعة من EADDRINUSE/إعادة التشغيل بدلًا من تشغيل عملية Gateway مستقرة واحدة.

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

ابحث عن:

• أكثر من معرّف PID واحد لـ Gateway خلال العينة التي مدتها 30 ثانية بدلًا من عملية مستقرة واحدة.
• EADDRINUSE أو another gateway instance is already listening أو أسطر متكررة لإعادة التشغيل/التسليم في gateway.log.
• تحميل كل من ~/Library/LaunchAgents/ai.openclaw.gateway.plist و ~/Library/LaunchAgents/ai.openclaw.node.plist في الوقت نفسه على مضيف يُفترض أن يشغّل خدمة Gateway مُدارة واحدة فقط.

ما يجب فعله:

1. إذا كان يُفترض أن يشغّل هذا المضيف خدمة Gateway فقط، فأزل خدمة node المُدارة من خلال OpenClaw. تخطَّ هذه الخطوة إذا كنت تعتمد فعليًا على خدمة node لميزات node البعيدة؛ إذ يؤدي إلغاء تثبيتها إلى إيقاف تلك الميزات على هذا المضيف:

   openclaw node uninstall

2. ثبّت غلافًا دائمًا لـ Gateway يمسح علامات launchd الموروثة قبل بدء OpenClaw. استخدم خيار --wrapper المدعوم؛ ولا تعدّل الملف المُنشأ ضمن ~/.openclaw/service-env/، لأن إعادة تثبيت الخدمة والتحديث وإصلاح Doctor تعيد إنشاء ذلك الملف:

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   يحافظ gateway install على مسار الغلاف عبر عمليات إعادة التثبيت الإجبارية والتحديثات وإصلاحات Doctor.

3. تحقق من أن Gateway مستقر ويخدم RPC، وليس مجرد الاستماع:

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   يجب أن تعرض عينة PID عملية مستقرة واحدة بدلًا من مجموعة متبدلة من معرّفات PID، ويجب أن يُستأنف إرسال القنوات الواردة.

4. بعد الترقية إلى إصدار أُصلحت فيه حلقة LaunchAgent المزدوجة الأساسية، أزل الحل البديل وأعد تثبيت الخدمة المُدارة العادية:

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

موضوعات ذات صلة:

• ملاحظات منصة macOS
• Doctor
• واجهة CLI لـ Gateway

خروج Gateway أثناء الاستخدام المرتفع للذاكرة

استخدم هذا عندما يختفي Gateway تحت الحمل، أو يُبلغ المشرف عن إعادة تشغيل على نمط OOM، أو تشير السجلات إلى critical memory pressure bundle written.

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

ابحث عن:

• Reason: diagnostic.memory.pressure.critical في أحدث حزمة استقرار.
• Memory pressure: مع critical/rss_threshold أو critical/heap_threshold أو critical/rss_growth.
• قيم V8 heap: قريبة من حد الكومة.
• إدخالات Largest session files: مثل agents/<agent>/sessions/<session>.jsonl أو sessions/<session>.jsonl.
• عدادات ذاكرة cgroup في Linux عندما يعمل Gateway داخل حاوية أو خدمة محدودة الذاكرة.

الأنماط الشائعة:

• يظهر critical memory pressure bundle written قبل إعادة التشغيل بوقت قصير ← التقط OpenClaw حزمة استقرار قبل OOM. افحصها باستخدام openclaw gateway stability --bundle latest.
• يظهر memory pressure: level=critical ... memoryPressureSnapshot=disabled في سجلات Gateway ← اكتشف OpenClaw ضغطًا حرجًا على الذاكرة، لكن لقطة الاستقرار قبل OOM معطلة.
• يشير Largest session files: إلى مسار نص جلسة منقّح كبير جدًا ← قلّل سجل الجلسة المحتفظ به، أو افحص نمو الجلسة، أو انقل النصوص القديمة خارج المخزن النشط قبل إعادة التشغيل.
• البايتات المستخدمة في V8 heap: قريبة من حد الكومة ← خفّض ضغط المطالبات/الجلسات، أو قلّل العمل المتزامن، أو ارفع حد كومة Node فقط بعد التأكد من أن عبء العمل متوقع.
• Memory pressure: critical/rss_growth ← نمت الذاكرة بسرعة ضمن نافذة أخذ عينات واحدة. افحص أحدث السجلات بحثًا عن عملية استيراد كبيرة، أو مخرجات أدوات منفلتة، أو محاولات متكررة، أو دفعة من أعمال الوكلاء الموضوعة في قائمة الانتظار.
• يظهر ضغط حرج على الذاكرة في السجلات لكن لا توجد حزمة ← هذا هو الإعداد الافتراضي. اضبط diagnostics.memoryPressureSnapshot: true لالتقاط حزمة الاستقرار قبل OOM عند أحداث ضغط الذاكرة الحرج المستقبلية.

حزمة الاستقرار خالية من الحمولة. وهي تتضمن أدلة تشغيلية عن الذاكرة ومسارات ملفات نسبية منقّحة، لا نصوص الرسائل أو أجسام Webhook أو بيانات الاعتماد أو الرموز المميزة أو ملفات تعريف الارتباط أو معرّفات الجلسات الأولية. أرفق تصدير التشخيصات بتقارير الأخطاء بدلًا من نسخ السجلات الأولية.

موضوعات ذات صلة:

• صحة Gateway
• تصدير التشخيصات
• الجلسات

رفض Gateway إعدادًا غير صالح

استخدم هذا عندما يفشل بدء تشغيل Gateway مع Invalid config أو عندما تشير سجلات إعادة التحميل الفوري إلى تخطي تعديل غير صالح.

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

ابحث عن:

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• ملف openclaw.json.rejected.* مزوّد بطابع زمني بجوار الإعداد النشط.
• ملف openclaw.json.clobbered.* مزوّد بطابع زمني إذا أصلح doctor --fix تعديلًا مباشرًا معطوبًا.
• يحتفظ OpenClaw بأحدث 32 ملفًا من ملفات .clobbered.* لكل مسار إعداد ويدوّر الملفات الأقدم.

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

مواضيع ذات صلة:

• الإعداد
• الإعداد: إعادة التحميل الفورية
• الإعداد: التحقق الصارم
• Doctor

تحذيرات فحص Gateway

استخدم هذا عندما يصل openclaw gateway probe إلى شيء ما، لكنه يظل يطبع كتلة تحذير.

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

ابحث عن:

• warnings[].code وprimaryTargetId في مخرجات JSON.
• ما إذا كان التحذير متعلقًا بالرجوع إلى SSH، أو تعدد بوابات Gateway، أو النطاقات المفقودة، أو مراجع المصادقة غير المحلولة.

العلامات الشائعة:

• SSH tunnel failed to start; falling back to direct probes. → فشل إعداد SSH، لكن الأمر ظل يحاول الاتصال بالأهداف المباشرة المضبوطة أو أهداف الاسترجاع الحلقي.
• multiple reachable gateway identities detected → استجابت بوابات Gateway مختلفة، أو تعذّر على OpenClaw إثبات أن الأهداف التي يمكن الوصول إليها هي Gateway نفسها. يُعامل نفق SSH أو عنوان URL للوكيل أو عنوان URL بعيد مضبوط يؤدي إلى Gateway نفسها باعتباره Gateway واحدة ذات وسائل نقل متعددة، حتى عندما تختلف منافذ النقل.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → نجح الاتصال، لكن RPC التفصيلي مقيّد بالنطاق؛ أقرن هوية الجهاز أو استخدم بيانات اعتماد تتضمن operator.read.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → نجح الاتصال، لكن انتهت مهلة مجموعة RPC التشخيصية الكاملة أو فشلت. تعامل مع هذا بوصفه Gateway يمكن الوصول إليها لكن تشخيصاتها متدهورة؛ قارن connect.ok وconnect.rpcOk في مخرجات --json.
• Capability: pairing-pending أو gateway closed (1008): pairing required → استجابت Gateway، لكن هذا العميل لا يزال يحتاج إلى الإقران أو الموافقة قبل وصول المشغّل المعتاد.
• نص تحذير SecretRef غير المحلول لـ gateway.auth.* / gateway.remote.* → لم تكن مواد المصادقة متاحة في مسار الأمر هذا للهدف الذي فشل.

مواضيع ذات صلة:

• Gateway
• بوابات Gateway متعددة على المضيف نفسه
• الوصول عن بُعد

القناة متصلة لكن الرسائل لا تتدفق

إذا كانت حالة القناة متصلة لكن تدفق الرسائل متوقف، فركّز على السياسة والأذونات وقواعد التسليم الخاصة بالقناة.

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

ابحث عن:

• سياسة الرسائل المباشرة (pairing وallowlist وopen وdisabled).
• قائمة السماح للمجموعات ومتطلبات الإشارة.
• أذونات أو نطاقات API المفقودة للقناة.

العلامات الشائعة:

• mention required → جرى تجاهل الرسالة بسبب سياسة الإشارة في المجموعة.
• pairing / آثار الموافقة المعلّقة → المرسِل غير معتمد.
• missing_scope وnot_in_channel وForbidden و401/403 → مشكلة في مصادقة القناة أو أذوناتها.

مواضيع ذات صلة:

• استكشاف أخطاء القنوات وإصلاحها
• Discord
• Telegram
• WhatsApp

تسليم Cron وHeartbeat

إذا لم يعمل Cron أو Heartbeat أو لم يسلّم، فتحقق أولًا من حالة المجدول، ثم من هدف التسليم.

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

ابحث عن:

• تمكين Cron ووجود وقت التنبيه التالي.
• حالة سجل تشغيل المهمة (ok وskipped وerror).
• أسباب تخطي Heartbeat (quiet-hours وrequests-in-flight وcron-in-progress وlanes-busy وalerts-disabled وempty-heartbeat-file وno-tasks-due).

مواضيع ذات صلة:

• Heartbeat
• المهام المجدولة
• المهام المجدولة: استكشاف الأخطاء وإصلاحها

Node مقترنة لكن الأداة تفشل

إذا كانت Node مقترنة لكن الأدوات تفشل، فاعزل حالة الواجهة الأمامية والأذونات والموافقة.

openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw status

ابحث عن:

• اتصال Node بالإنترنت مع الإمكانات المتوقعة.
• منح أذونات نظام التشغيل للكاميرا والميكروفون والموقع والشاشة.
• موافقات التنفيذ وحالة قائمة السماح.

العلامات الشائعة:

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

مواضيع ذات صلة:

• موافقات التنفيذ
• استكشاف أخطاء Node وإصلاحها
• عُقد Node

أداة المتصفح تفشل

استخدم هذا عندما تفشل إجراءات أداة المتصفح رغم سلامة Gateway نفسها.

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

ابحث عن:

• ما إذا كان plugins.allow مضبوطًا ويتضمن browser.
• مسار صالح لملف المتصفح التنفيذي.
• إمكانية الوصول إلى ملف تعريف CDP.
• توفر Chrome محليًا لملفات تعريف existing-session / user.

مواضيع ذات صلة:

• المتصفح (تديره OpenClaw)
• استكشاف أخطاء المتصفح وإصلاحها

إذا أجريت ترقية وتعطّل شيء فجأة

تنتج معظم الأعطال بعد الترقية عن انحراف الإعداد أو بدء فرض إعدادات افتراضية أكثر صرامة.

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

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

إذا ظل إعداد الخدمة ووقت التشغيل غير متوافقين بعد عمليات التحقق، فأعد تثبيت بيانات الخدمة الوصفية من دليل الملف الشخصي/الحالة نفسه:

openclaw gateway install --forceopenclaw gateway restart

موضوعات ذات صلة:

• المصادقة
• التنفيذ في الخلفية وأداة العمليات
• اقتران Node

موضوعات ذات صلة

• Doctor
• الأسئلة الشائعة
• دليل تشغيل Gateway