Doctor

openclaw doctor

openclaw doctor --yes

openclaw doctor --repair

openclaw doctor --repair --force

openclaw doctor --non-interactive

openclaw doctor --deep

cat ~/.openclaw/openclaw.json
## ما الذي يفعله (ملخص)

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

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

### 0) تحديث اختياري (تثبيتات Git)

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

### 1) تطبيع التكوين

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

### 2) ترحيل مفاتيح التكوين القديمة

عندما يحتوي التكوين على مفاتيح قديمة، ترفض الأوامر الأخرى التشغيل وتطلب منك تشغيل `openclaw doctor`. سيقوم doctor بما يلي:

-   شرح مفاتيح التراث التي تم العثور عليها.
-   عرض الترحيل الذي طبقه.
-   إعادة كتابة `~/.openclaw/openclaw.json` بالمخطط المحدث.

تقوم البوابة أيضًا بتشغيل ترحيلات 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`
-   للقنوات التي تحتوي على `accounts` مسماة ولكن `accounts.default` مفقودة، انقل قيم القناة ذات الحساب الواحد على المستوى الأعلى إلى `channels.<channel>.accounts.default` عند وجودها
-   `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`
-   `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`

تتضمن تحذيرات doctor أيضًا إرشادات افتراضية للحساب للقنوات متعددة الحسابات:

-   إذا تم تكوين إدخالين أو أكثر من `channels.<channel>.accounts` بدون `channels.<channel>.defaultAccount` أو `accounts.default`، يحذر doctor من أن التوجيه الاحتياطي يمكنه اختيار حساب غير متوقع.
-   إذا تم تعيين `channels.<channel>.defaultAccount` على معرف حساب غير معروف، يحذر doctor ويعرض معرفات الحسابات المكونة.

### 2ب) تجاوزات موفر 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 تحذيرات عندما يترك أي مجلدات قديمة كنسخ احتياطية. تقوم البوابة/واجهة سطر الأوامر أيضًا بترحيل الجلسات القديمة + دليل الوكيل تلقائيًا عند بدء التشغيل بحيث تنتقل السجل/المصادقة/النماذج إلى المسار لكل وكيل دون تشغيل doctor يدويًا. يتم ترحيل مصادقة WhatsApp عن قصد فقط عبر `openclaw doctor`.

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

دليل الحالة هو جذع الدماغ التشغيلي. إذا اختفى، تفقد الجلسات، بيانات الاعتماد، السجلات، والتكوين (ما لم يكن لديك نسخ احتياطية في مكان آخر). يفحص doctor:

-   **دليل الحالة مفقود**: يحذر من فقدان الحالة الكارثي، يطلب إعادة إنشاء الدليل، ويذكرك بأنه لا يمكنه استعادة البيانات المفقودة.
-   **أذونات دليل الحالة**: يتحقق من قابلية الكتابة؛ يعرض إصلاح الأذونات (ويصدر تلميح `chown` عند اكتشاف عدم تطابق المالك/المجموعة).
-   **دليل الحالة المتزامن مع السحابة على macOS**: يحذر عندما يتم حل الحالة تحت iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) أو `~/Library/CloudStorage/...` لأن المسارات المدعومة بالمزامنة يمكن أن تسبب إدخال/إخراج أبطأ وسباقات قفل/مزامنة.
-   **دليل الحالة على Linux SD أو eMMC**: يحذر عندما يتم حل الحالة إلى مصدر تركيب `mmcblk*`، لأن إدخال/إخراج العشوائية المدعوم بـ SD أو eMMC يمكن أن يكون أبطأ ويتآكل بشكل أسرع تحت كتابات الجلسات وبيانات الاعتماد.
-   **أدلة الجلسات مفقودة**: `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.gmail.model`، يتحقق doctor من مرجع النموذج مقابل الكتالوج وقائمة السماح ويحذر عندما لا يتم حله أو غير مسموح به.

### 7) إصلاح صورة الحاوية الرملية

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

### 8) ترحيل خدمة البوابة وتلميحات التنظيف

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

### 9) تحذيرات أمنية

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

### 10) systemd linger (Linux)

إذا كان يعمل كخدمة مستخدم systemd، يتأكد doctor من تمكين lingering حتى تظل البوابة نشطة بعد تسجيل الخروج.

### 11) حالة المهارات

يطبع doctor ملخصًا سريعًا للمهارات المؤهلة/المفقودة/المحظورة لمساحة العمل الحالية.

### 12) فحوصات مصادقة البوابة (الرمز المحلي)

يفحص doctor جاهزية مصادقة رمز البوابة المحلي.

-   إذا كان وضع الرمز يحتاج إلى رمز ولا يوجد مصدر للرموز، يعرض doctor إنشاء واحد.
-   إذا كان `gateway.auth.token` مُدارًا بواسطة SecretRef وغير متاح، يحذر doctor ولا يستبدله بنص عادي.
-   `openclaw doctor --generate-gateway-token` يجبر الإنشاء فقط عندما لا يتم تكوين SecretRef للرموز.

### 12ب) إصلاحات واعية بـ SecretRef للقراءة فقط

تحتاج بعض تدفقات الإصلاح إلى فحص بيانات الاعتماد المكونة دون إضعاف سلوك الفشل السريع في وقت التشغيل.

-   يستخدم `openclaw doctor --fix` الآن نفس نموذج ملخص SecretRef للقراءة فقط مثل أوامر عائلة status للإصلاحات المستهدفة للتكوين.
-   مثال: يحاول إصلاح `allowFrom` / `groupAllowFrom` `@username` لـ Telegram استخدام بيانات اعتماد البوت المكونة عند توفرها.
-   إذا تم تكوين رمز بوت Telegram عبر SecretRef ولكنه غير متاح في مسار الأمر الحالي، يبلغ doctor أن بيانات الاعتماد مكونة ولكن غير متاحة ويتخطى الحل التلقائي بدلاً من التعطل أو الإبلاغ الخاطئ بأن الرمز مفقود.

### 13) فحص صحة البوابة + إعادة التشغيل

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

### 14) تحذيرات حالة القناة

إذا كانت البوابة صحية، يقوم doctor بتشغيل فحص لحالة القناة ويبلغ عن تحذيرات مع إصلاحات مقترحة.

### 15) مراجعة تكوين المشرف + إصلاح

يفحص doctor تكوين المشرف المثبت (launchd/systemd/schtasks) بحثًا عن إعدادات افتراضية مفقودة أو قديمة (على سبيل المثال، تبعات systemd network-online وتأخير إعادة التشغيل). عندما يجد عدم تطابق، يوصي بتحديث ويمكنه إعادة كتابة ملف/مهمة الخدمة إلى الإعدادات الافتراضية الحالية. ملاحظات:

-   `openclaw doctor` يطلب قبل إعادة كتابة تكوين المشرف.
-   `openclaw doctor --yes` يقبل مطالبات الإصلاح الافتراضية.
-   `openclaw doctor --repair` يطبق الإصلاحات الموصى بها دون مطالبات.
-   `openclaw doctor --repair --force` يستبدل تكوينات المشرف المخصصة.
-   إذا كانت مصادقة الرمز تتطلب رمزًا وكان `gateway.auth.token` مُدارًا بواسطة SecretRef، فإن تثبيت/إصلاح خدمة doctor يتحقق من صحة SecretRef ولكنه لا يحافظ على قيم الرموز العادية المحلولة في بيانات وصفية لبيئة خدمة المشرف.
-   إذا كانت مصادقة الرمز تتطلب رمزًا وكان SecretRef للرموز المكون غير محلول، فإن doctor يحظر مسار التثبيت/الإصلاح بتوجيهات قابلة للتنفيذ.
-   إذا تم تكوين كل من `gateway.auth.token` و `gateway.auth.password` وكان `gateway.auth.mode` غير معين، فإن doctor يحظر التثبيت/الإصلاح حتى يتم تعيين الوضع صراحة.
-   يمكنك دائمًا إجبار إعادة كتابة كاملة عبر `openclaw gateway install --force`.

### 16) وقت تشغيل البوابة + تشخيصات المنفذ

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

### 17) أفضل ممارسات وقت تشغيل البوابة

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

### 18) كتابة التكوين + بيانات وصفية للمساعد

يحافظ doctor على أي تغييرات في التكوين ويختم البيانات الوصفية للمساعد لتسجيل تشغيل doctor.

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

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

[نبض القلب](/gateway/heartbeat)[التسجيل](/gateway/logging)