الانتقال إلى المحتوى الرئيسي

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

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

​
سلّم الأوامر

شغّل هذه أولًا، وبهذا الترتيب: 
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
الإشارات السليمة المتوقعة:
  • openclaw gateway status يعرض Runtime: running و RPC probe: ok.
  • openclaw doctor يبلّغ عن عدم وجود مشكلات تهيئة/خدمة حاجبة.
  • openclaw channels status --probe يعرض قنوات متصلة/جاهزة.

​
لا توجد ردود

إذا كانت القنوات تعمل ولكن لا يصل أي رد، فتحقّق من التوجيه والسياسات قبل إعادة توصيل أي شيء. 
openclaw status
openclaw channels status --probe
openclaw pairing list <channel>
openclaw config get channels
openclaw logs --follow
ابحث عن:
  • الإقران معلق للمرسلين DM.
  • بوابة الإشارة في المجموعات (requireMention، mentionPatterns).
  • عدم تطابق قوائم السماح للقناة/المجموعة.
التوقيعات المشتركة:
  • drop guild message (mention required → تجاهل رسالة المجموعة حتى تتم الإشارة.
  • pairing request → يحتاج المرسل إلى موافقة.
  • blocked / allowlist → تمّت تصفية المرسل/القناة بواسطة السياسة.
ذات صلة:

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

عندما لا تتصل لوحة المعلومات/واجهة التحكم، تحقّق من عنوان URL، ووضع المصادقة، وافتراضات السياق الآمن. 
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json
ابحث عن:
  • عنوان URL الصحيح للفحص وعنوان URL الصحيح للوحة المعلومات.
  • عدم تطابق وضع/رمز المصادقة بين العميل و Gateway.
  • استخدام HTTP حيث تكون هوية الجهاز مطلوبة.
التوقيعات المشتركة:
  • device identity required → سياق غير آمن أو مصادقة جهاز مفقودة.
  • unauthorized / حلقة إعادة الاتصال → عدم تطابق الرمز/كلمة المرور.
  • gateway connect failed: → هدف مضيف/منفذ/عنوان URL خاطئ.
ذات صلة:

​
خدمة Gateway لا تعمل

استخدم هذا عندما تكون الخدمة مثبّتة لكن العملية لا تبقى قيد التشغيل. 
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep
ابحث عن:
  • Runtime: stopped مع تلميحات الخروج.
  • عدم تطابق تهيئة الخدمة (Config (cli) مقابل Config (service)).
  • تعارضات المنافذ/المستمعين.
التوقيعات المشتركة:
  • Gateway start blocked: set gateway.mode=local → لم يتم تمكين وضع Gateway المحلي. الإصلاح: عيّن gateway.mode="local" في ملف الإعدادات (أو شغّل openclaw configure). إذا كنت تشغّل OpenClaw عبر Podman باستخدام المستخدم المخصص openclaw، فسيكون ملف الإعدادات في ~openclaw/.openclaw/openclaw.json.
  • refusing to bind gateway ... without auth → ربط غير loopback بدون رمز/كلمة مرور.
  • another gateway instance is already listening / EADDRINUSE → تعارض منفذ.
ذات صلة:

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

إذا كانت حالة القناة «متصلة» لكن تدفّق الرسائل متوقف، فركّز على السياسات والأذونات وقواعد التسليم الخاصة بالقناة. 
openclaw channels status --probe
openclaw pairing list <channel>
openclaw status --deep
openclaw logs --follow
openclaw config get channels
ابحث عن:
  • سياسة الرسائل المباشرة (pairing، allowlist، open، disabled).
  • قائمة السماح للمجموعات ومتطلبات الإشارة.
  • أذونات/نطاقات واجهة برمجة التطبيقات الخاصة بالقناة المفقودة.
التوقيعات المشتركة:
  • mention required → تم تجاهل الرسالة بسبب سياسة الإشارة في المجموعة.
  • pairing / آثار موافقة معلّقة → المرسل غير معتمد.
  • missing_scope، not_in_channel، Forbidden، 401/403 → مشكلة مصادقة/أذونات القناة.
ذات صلة:

​
تسليم Cron وHeartbeat

إذا لم يعمل cron أو heartbeat أو لم يتم التسليم، فتحقّق أولًا من حالة المُجَدول ثم من هدف التسليم. 
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
ابحث عن:
  • تمكين Cron ووجود وقت الاستيقاظ التالي.
  • حالة سجل تشغيل المهام (ok، skipped، error).
  • أسباب تخطّي Heartbeat (quiet-hours، requests-in-flight، alerts-disabled).
التوقيعات المشتركة:
  • cron: scheduler disabled; jobs will not run automatically → Cron معطّل.
  • cron: timer tick failed → فشل نبضة المُجَدول؛ تحقّق من أخطاء الملفات/السجلات/وقت التشغيل.
  • heartbeat skipped مع reason=quiet-hours → خارج نافذة الساعات النشطة.
  • heartbeat: unknown accountId → معرّف حساب غير صالح لهدف تسليم Heartbeat.
ذات صلة:

​
فشل أداة عُقدة مقترنة

إذا كانت العُقدة مقترنة لكن الأدوات تفشل، فاعزل حالة المقدّمة، والأذونات، والموافقة. 
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status
ابحث عن:
  • عقد على الإنترنت مع القدرات المتوقعة.
  • منح أذونات نظام التشغيل للكاميرا/الميكروفون/الموقع/الشاشة.
  • موافقات التنفيذ وحالة قائمة السماح.
التوقيعات المشتركة:
  • NODE_BACKGROUND_UNAVAILABLE → يجب أن يكون تطبيق العُقدة في الواجهة الأمامية.
  • *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → إذن نظام تشغيل مفقود.
  • SYSTEM_RUN_DENIED: approval required → موافقة التنفيذ معلّقة.
  • SYSTEM_RUN_DENIED: allowlist miss → تم حظر الأمر بواسطة قائمة السماح.
ذات صلة:

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

استخدم هذا عندما تفشل إجراءات أداة المتصفح رغم أن Gateway نفسه سليم. 
openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor
ابحث عن:
  • مسار صالح لتنفيذ المتصفح.
  • إمكانية الوصول إلى ملف تعريف CDP.
  • إرفاق علامة تبويب ترحيل الامتداد لـ profile="chrome".
التوقيعات المشتركة:
  • Failed to start Chrome CDP on port → فشل تشغيل عملية المتصفح.
  • browser.executablePath not found → المسار المُهيّأ غير صالح.
  • Chrome extension relay is running, but no tab is connected → لم يتم إرفاق ترحيل الامتداد.
  • Browser attachOnly is enabled ... not reachable → ملف تعريف «attach-only» لا يحتوي على هدف قابل للوصول.
ذات صلة:

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

معظم الأعطال بعد الترقية ناتجة عن انجراف التهيئة أو فرض افتراضات افتراضية أكثر صرامة الآن.

​
1. تغيّر سلوك تجاوز المصادقة وعنوان URL

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 → نقطة النهاية قابلة للوصول لكن المصادقة خاطئة.

​
2. أصبحت ضوابط الربط والمصادقة أكثر صرامة

openclaw config get gateway.bind
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow
ما الذي يجب التحقّق منه:
  • الروابط غير loopback (lan، tailnet، custom) تتطلب تهيئة المصادقة.
  • المفاتيح القديمة مثل gateway.token لا تستبدل gateway.auth.token.
التوقيعات المشتركة:
  • refusing to bind gateway ... without auth → عدم تطابق الربط+المصادقة.
  • RPC probe: failed بينما وقت التشغيل يعمل → Gateway حيّ لكنه غير قابل للوصول بالمصادقة/عنوان URL الحاليين.

​
3. تغيّرت حالة الاقتران وهوية الجهاز

openclaw devices list
openclaw pairing list <channel>
openclaw logs --follow
openclaw doctor
ما الذي يجب التحقّق منه:
  • موافقات الأجهزة المعلّقة للوحة المعلومات/العُقد.
  • موافقات اقتران الرسائل المباشرة المعلّقة بعد تغييرات السياسة أو الهوية.
التوقيعات المشتركة:
  • device identity required → لم يتم استيفاء مصادقة الجهاز.
  • pairing required → يجب اعتماد المرسل/الجهاز.
إذا استمر عدم التوافق بين تهيئة الخدمة ووقت التشغيل بعد الفحوصات، فأعد تثبيت بيانات الخدمة الوصفية من نفس دليل الملف الشخصي/الحالة: 
openclaw gateway install --force
openclaw gateway restart
ذات صلة: