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

​
الطبيب

openclaw doctor هي أداة الإصلاح + الترحيل لـ OpenClaw. تقوم بإصلاح التهيئة/الحالة القديمة، والتحقق من الصحة، وتقديم خطوات إصلاح قابلة للتنفيذ.

​
البدء السريع

openclaw doctor

​
رأس / أتمتة

openclaw doctor --yes
قبول القيم الافتراضية دون مطالبة (بما في ذلك خطوات إصلاح إعادة التشغيل/الخدمة/sandbox عند الاقتضاء). 
openclaw doctor --repair
تطبيق الإصلاحات الموصى بها دون مطالبة (إصلاحات + إعادة تشغيل حيثما كان آمنًا). 
openclaw doctor --repair --force
تطبيق الإصلاحات الجذرية أيضًا (يستبدل تهيئات المشرف المخصصة). 
openclaw doctor --non-interactive
التشغيل دون مطالبات وتطبيق الترحيلات الآمنة فقط (توحيد التهيئة + نقل الحالة على القرص). يتخطى إجراءات إعادة التشغيل/الخدمة/sandbox التي تتطلب تأكيدًا بشريًا. تعمل ترحيلات الحالة القديمة تلقائيًا عند اكتشافها. 
openclaw doctor --deep
فحص خدمات النظام بحثًا عن عمليات تثبيت Gateway إضافية (launchd/systemd/schtasks). إذا أردت مراجعة التغييرات قبل الكتابة، افتح ملف التهيئة أولًا: 
cat ~/.openclaw/openclaw.json

​
ما الذي يفعله (ملخص)

  • تحديث اختياري قبل التشغيل لتثبيتات git (تفاعلي فقط).
  • فحص حداثة بروتوكول الواجهة (يعيد بناء واجهة Control UI عندما يكون مخطط البروتوكول أحدث).
  • فحص الصحة + مطالبة بإعادة التشغيل.
  • ملخص حالة Skills (مؤهلة/مفقودة/محجوبة).
  • توحيد التهيئة للقيم القديمة.
  • تحذيرات تجاوز موفّر OpenCode Zen (models.providers.opencode).
  • ترحيل الحالة القديمة على القرص (الجلسات/دليل الوكيل/مصادقة WhatsApp).
  • فحوصات سلامة الحالة والأذونات (الجلسات، النصوص، دليل الحالة).
  • فحوصات أذونات ملف التهيئة (chmod 600) عند التشغيل محليًا.
  • صحة مصادقة النموذج: التحقق من انتهاء OAuth، يمكن تحديث الرموز التي توشك على الانتهاء، والإبلاغ عن حالات التهدئة/التعطيل لملفات تعريف المصادقة.
  • اكتشاف دليل مساحة عمل إضافي (~/openclaw).
  • إصلاح صورة Sandbox عند تمكين sandboxing.
  • ترحيل الخدمات القديمة واكتشاف Gateway إضافية.
  • فحوصات وقت تشغيل Gateway (الخدمة مثبتة لكنها لا تعمل؛ وسم launchd مخزّن).
  • تحذيرات حالة القنوات (مستقصاة من Gateway قيد التشغيل).
  • تدقيق تهيئة المشرف (launchd/systemd/schtasks) مع إصلاح اختياري.
  • فحوصات أفضل ممارسات وقت تشغيل Gateway (Node مقابل Bun، مسارات مديري الإصدارات).
  • تشخيص تعارض المنافذ في Gateway (الافتراضي 18789).
  • تحذيرات أمنية لسياسات الرسائل المباشرة المفتوحة.
  • تحذيرات مصادقة Gateway عند عدم تعيين gateway.auth.token (الوضع المحلي؛ يعرض إنشاء رمز).
  • فحص systemd linger على Linux.
  • فحوصات التثبيت من المصدر (عدم تطابق مساحة عمل pnpm، أصول واجهة مستخدم مفقودة، ملف tsx التنفيذي مفقود).
  • كتابة التهيئة المحدثة + بيانات معالج الإعداد.

​
السلوك التفصيلي والمبررات

​
0. تحديث اختياري (تثبيتات git)

إذا كان هذا مستودع git وكان Doctor يعمل تفاعليًا، فإنه يعرض التحديث (fetch/rebase/build) قبل تشغيل Doctor.

​
1. توحيد التهيئة

إذا احتوت التهيئة على أشكال قيم قديمة (على سبيل المثال messages.ackReaction دون تجاوز خاص بالقناة)، يقوم Doctor بتوحيدها إلى المخطط الحالي.

​
2. ترحيلات مفاتيح التهيئة القديمة

عندما تحتوي التهيئة على مفاتيح مهجورة، ترفض الأوامر الأخرى التشغيل وتطلب تشغيل openclaw doctor. سيقوم Doctor بما يلي:
  • شرح أي مفاتيح قديمة تم العثور عليها.
  • عرض الترحيل الذي طبّقه.
  • إعادة كتابة ~/.openclaw/openclaw.json بالمخطط المحدّث.
كما يقوم Gateway بتشغيل ترحيلات Doctor تلقائيًا عند بدء التشغيل عندما يكتشف تنسيق تهيئة قديم، بحيث تُصلح التهيئات القديمة دون تدخل يدوي. الترحيلات الحالية:
  • routing.allowFrom → channels.whatsapp.allowFrom
  • routing.groupChat.requireMention → channels.whatsapp/telegram/imessage.groups."*".requireMention
  • routing.groupChat.historyLimit → messages.groupChat.historyLimit
  • routing.groupChat.mentionPatterns → messages.groupChat.mentionPatterns
  • routing.queue → messages.queue
  • routing.bindings → المستوى الأعلى bindings
  • routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
  • routing.agentToAgent → tools.agentToAgent
  • routing.transcribeAudio → tools.media.audio.models
  • bindings[].match.accountID → bindings[].match.accountId
  • identity → agents.list[].identity
  • agent.* → agents.defaults + tools.* (tools/elevated/exec/sandbox/subagents)
  • agent.model/allowedModels/modelAliases/modelFallbacks/imageModelFallbacks → agents.defaults.models + agents.defaults.model.primary/fallbacks + agents.defaults.imageModel.primary/fallbacks

​
2b) تجاوزات موفّر OpenCode Zen

إذا أضفت models.providers.opencode (أو opencode-zen) يدويًا، فإنه يتجاوز كتالوج OpenCode Zen المدمج من @mariozechner/pi-ai. قد يؤدي ذلك إلى فرض جميع النماذج على واجهة برمجة تطبيقات واحدة أو تصفير التكاليف. يحذّر Doctor كي تتمكن من إزالة التجاوز واستعادة توجيه واجهات برمجة التطبيقات والتكاليف لكل نموذج.

​
3. ترحيلات الحالة القديمة (تخطيط القرص)

يمكن لـ Doctor ترحيل تخطيطات القرص الأقدم إلى البنية الحالية:
  • مخزن الجلسات + النصوص:
    • من ~/.openclaw/sessions/ إلى ~/.openclaw/agents/<agentId>/sessions/
  • دليل الوكيل:
    • من ~/.openclaw/agent/ إلى ~/.openclaw/agents/<agentId>/agent/
  • حالة مصادقة WhatsApp (Baileys):
    • من ~/.openclaw/credentials/*.json القديمة (باستثناء oauth.json)
    • إلى ~/.openclaw/credentials/whatsapp/<accountId>/... (معرّف الحساب الافتراضي: default)
هذه الترحيلات بأفضل جهد وقابلة للتكرار؛ سيُصدر Doctor تحذيرات عندما يترك أي مجلدات قديمة كنسخ احتياطية. كما يقوم Gateway/CLI بترحيل الجلسات القديمة + دليل الوكيل تلقائيًا عند بدء التشغيل بحيث تنتقل السجلات/المصادقة/النماذج إلى المسار الخاص بكل وكيل دون تشغيل Doctor يدويًا. تُرحّل مصادقة WhatsApp عمدًا فقط عبر openclaw doctor.

​
4. فحوصات سلامة الحالة (استمرارية الجلسة، التوجيه، والسلامة)

دليل الحالة هو العمود الفقري التشغيلي. إذا اختفى، ستفقد الجلسات وبيانات الاعتماد والسجلات والتهيئة (ما لم تكن لديك نسخ احتياطية). يفحص Doctor ما يلي:
  • دليل الحالة مفقود: يحذّر من فقدان كارثي للحالة، ويطلب إعادة إنشاء الدليل، ويذكّرك بأنه لا يمكنه استعادة البيانات المفقودة.
  • أذونات دليل الحالة: يتحقق من قابلية الكتابة؛ ويعرض إصلاح الأذونات (ويصدر تلميح chown عند اكتشاف عدم تطابق المالك/المجموعة).
  • أدلة الجلسات مفقودة: يتطلب sessions/ ودليل مخزن الجلسات للحفاظ على السجل وتجنب أعطال ENOENT.
  • عدم تطابق النصوص: يحذّر عندما تحتوي إدخالات الجلسات الأخيرة على ملفات نصوص مفقودة.
  • الجلسة الرئيسية «JSONL بسطر واحد»: يعلّم عندما يحتوي النص الرئيسي على سطر واحد فقط (السجل لا يتراكم).
  • أدلة حالة متعددة: يحذّر عند وجود عدة مجلدات ~/.openclaw عبر أدلة المنزل أو عندما يشير OPENCLAW_STATE_DIR إلى مكان آخر (قد ينقسم السجل بين عمليات تثبيت).
  • تذكير الوضع البعيد: إذا كان gateway.mode=remote، يذكّرك Doctor بتشغيله على المضيف البعيد (الحالة موجودة هناك).
  • أذونات ملف التهيئة: يحذّر إذا كان ~/.openclaw/openclaw.json قابلًا للقراءة من المجموعة/العالم ويعرض تشديده إلى 600.

​
5. صحة مصادقة النموذج (انتهاء OAuth)

يفحص Doctor ملفات تعريف OAuth في مخزن المصادقة، ويحذّر عند قرب انتهاء الرموز/انتهائها، ويمكنه تحديثها عندما يكون ذلك آمنًا. إذا كان ملف تعريف Anthropic Claude Code قديمًا، يقترح تشغيل claude setup-token (أو لصق رمز إعداد). تظهر مطالبات التحديث فقط عند التشغيل التفاعلي (TTY)؛ ويتخطّى --non-interactive محاولات التحديث. كما يبلّغ Doctor عن ملفات تعريف مصادقة غير قابلة للاستخدام مؤقتًا بسبب:
  • فترات تهدئة قصيرة (قيود المعدّل/انتهاء المهلة/فشل المصادقة)
  • تعطيلات أطول (مشكلات الفوترة/الرصيد)

​
6. التحقق من نموذج Hooks

إذا كان hooks.gmail.model معيّنًا، يتحقق Doctor من مرجع النموذج مقابل الكتالوج وقائمة السماح ويحذّر عندما لا يمكن حله أو يكون غير مسموح به.

​
7. إصلاح صورة Sandbox

عند تمكين sandboxing، يفحص Doctor صور Docker ويعرض البناء أو التبديل إلى الأسماء القديمة إذا كانت الصورة الحالية مفقودة.

​
8. ترحيلات خدمة Gateway وتلميحات التنظيف

يكتشف Doctor خدمات Gateway القديمة (launchd/systemd/schtasks) ويعرض إزالتها وتثبيت خدمة OpenClaw باستخدام منفذ Gateway الحالي. كما يمكنه فحص خدمات إضافية شبيهة بـ Gateway وطباعة تلميحات تنظيف. تُعد خدمات Gateway المسماة حسب الملف الشخصي في OpenClaw من الدرجة الأولى ولا تُعلّم على أنها «إضافية».

​
9. تحذيرات أمنية

يُصدر Doctor تحذيرات عندما يكون موفّر ما مفتوحًا للرسائل المباشرة دون قائمة سماح، أو عندما تُهيّأ سياسة بطريقة خطرة.

​
10. systemd linger (Linux)

إذا كان يعمل كخدمة مستخدم systemd، يضمن Doctor تمكين lingering بحيث يبقى Gateway قيد التشغيل بعد تسجيل الخروج.

​
11. حالة Skills

يطبع Doctor ملخصًا سريعًا لـ Skills المؤهلة/المفقودة/المحجوبة لمساحة العمل الحالية.

​
12. فحوصات مصادقة Gateway (الرمز المحلي)

يحذّر Doctor عند غياب gateway.auth على Gateway محلي ويعرض إنشاء رمز. استخدم openclaw doctor --generate-gateway-token لفرض إنشاء الرمز في الأتمتة.

​
13. فحص صحة Gateway + إعادة التشغيل

يجري Doctor فحص صحة ويعرض إعادة تشغيل Gateway عندما يبدو غير صحي.

​
14. تحذيرات حالة القنوات

إذا كان Gateway سليمًا، يجري Doctor استقصاء حالة القنوات ويبلّغ عن التحذيرات مع إصلاحات مقترحة.

​
15. تدقيق تهيئة المشرف + الإصلاح

يفحص Doctor تهيئة المشرف المثبّتة (launchd/systemd/schtasks) بحثًا عن القيم الافتراضية المفقودة أو القديمة (مثل تبعيات network-online في systemd وتأخير إعادة التشغيل). عند العثور على عدم تطابق، يوصي بتحديث ويمكنه إعادة كتابة ملف الخدمة/المهمة إلى القيم الافتراضية الحالية. ملاحظات:
  • openclaw doctor يطالب قبل إعادة كتابة تهيئة المشرف.
  • openclaw doctor --yes يقبل مطالبات الإصلاح الافتراضية.
  • openclaw doctor --repair يطبّق الإصلاحات الموصى بها دون مطالبات.
  • openclaw doctor --repair --force يستبدل تهيئات المشرف المخصصة.
  • يمكنك دائمًا فرض إعادة كتابة كاملة عبر openclaw gateway install --force.

​
16. تشخيصات وقت تشغيل Gateway + المنفذ

يفحص Doctor وقت تشغيل الخدمة (PID، حالة آخر خروج) ويحذّر عندما تكون الخدمة مثبتة لكنها لا تعمل فعليًا. كما يتحقق من تعارض المنافذ على منفذ Gateway (الافتراضي 18789) ويبلّغ عن الأسباب المحتملة (Gateway يعمل بالفعل، نفق SSH).

​
17. أفضل ممارسات وقت تشغيل Gateway

يحذّر Doctor عندما تعمل خدمة Gateway على Bun أو على مسار Node مُدار بواسطة مدير إصدارات (nvm، fnm، volta، asdf، إلخ). تتطلب قناتا WhatsApp وTelegram Node، وقد تتعطل مسارات مديري الإصدارات بعد الترقيات لأن الخدمة لا تحمّل تهيئة الصدفة. يعرض Doctor الترحيل إلى تثبيت Node على مستوى النظام عند توفره (Homebrew/apt/choco).

​
18. كتابة التهيئة + بيانات معالج الإعداد

يقوم Doctor بحفظ أي تغييرات على التهيئة وختم بيانات معالج الإعداد لتسجيل تشغيل Doctor.

​
19. نصائح مساحة العمل (النسخ الاحتياطي + نظام الذاكرة)

يقترح Doctor نظام ذاكرة لمساحة العمل عند غيابه ويطبع تلميح نسخ احتياطي إذا لم تكن مساحة العمل خاضعة لـ git بالفعل. انظر /concepts/agent-workspace للحصول على دليل كامل لبنية مساحة العمل والنسخ الاحتياطي باستخدام git (موصى به: GitHub أو GitLab خاص).