openclaw doctor

فحوصات السلامة + إصلاحات سريعة للـ Gateway والقنوات.

ذات صلة:

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

لماذا تستخدمه

openclaw doctor هو سطح السلامة في OpenClaw. استخدمه عندما لا يتصرف الـ Gateway أو القنوات أو Plugins أو Skills أو توجيه النماذج أو الحالة المحلية أو ترحيلات الإعدادات كما هو متوقع، وتريد أمرا واحدا يمكنه شرح ما هو الخطأ.

لدى doctor ثلاثة أوضاع:

فضّل --lint عندما تحتاج الأتمتة إلى نتيجة مستقرة. وفضّل --fix عندما يريد المشغل البشري عمدا أن يحرر doctor الإعدادات أو الحالة.

أمثلة

openclaw doctoropenclaw doctor --lintopenclaw doctor --lint --jsonopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --deepopenclaw doctor --fixopenclaw doctor --fix --non-interactiveopenclaw doctor --generate-gateway-tokenopenclaw doctor --post-upgradeopenclaw doctor --post-upgrade --json

بالنسبة للأذونات الخاصة بالقنوات، استخدم فحوصات القنوات بدلا من doctor:

openclaw channels capabilities --channel discord --target channel:<channel-id>openclaw channels status --probe

يبلغ فحص قدرات Discord الموجه عن أذونات القناة الفعلية للبوت؛ ويدقق فحص الحالة قنوات Discord المهيأة وأهداف الانضمام التلقائي للصوت.

الخيارات

• --no-workspace-suggestions: تعطيل اقتراحات ذاكرة مساحة العمل/البحث
• --yes: قبول الافتراضيات دون مطالبة
• --repair: تطبيق إصلاحات غير خدمية موصى بها دون مطالبة؛ لا تزال عمليات تثبيت خدمة Gateway وإعادة كتابتها تتطلب تأكيدا تفاعليا أو أوامر Gateway صريحة
• --fix: اسم بديل لـ --repair
• --force: تطبيق إصلاحات شديدة، بما في ذلك استبدال إعدادات الخدمة المخصصة عند الحاجة
• --non-interactive: التشغيل دون مطالبات؛ للترحيلات الآمنة والإصلاحات غير الخدمية فقط
• --generate-gateway-token: توليد رمز Gateway وتهيئته
• --allow-exec: السماح لـ doctor بتنفيذ SecretRefs المهيأة من نوع exec أثناء التحقق من الأسرار
• --deep: فحص خدمات النظام بحثا عن عمليات تثبيت Gateway إضافية والإبلاغ عن تسليمات إعادة التشغيل الأخيرة لمشرف Gateway
• --lint: تشغيل فحوصات السلامة المحدثة في وضع القراءة فقط وإصدار نتائج تشخيصية
• --post-upgrade: تشغيل فحوصات توافق Plugin بعد الترقية؛ يصدر النتائج إلى stdout؛ ويخرج بالرمز 1 إذا وُجدت أي نتائج بمستوى خطأ
• --json: مع --lint، إصدار نتائج JSON بدلا من الإخراج البشري؛ ومع --post-upgrade، إصدار غلاف JSON قابل للقراءة آليا ({ probesRun, findings })
• --severity-min <level>: مع --lint، إسقاط النتائج الأدنى من info أو warning أو error
• --all: مع --lint، تشغيل جميع الفحوصات المسجلة، بما في ذلك فحوصات الاشتراك الاختياري المستبعدة من مجموعة الأتمتة الافتراضية
• --skip <id>: مع --lint، تخطي معرف فحص؛ كرره لتخطي أكثر من واحد
• --only <id>: مع --lint، تشغيل معرف فحص فقط؛ كرره لتشغيل مجموعة صغيرة محددة

وضع التدقيق

openclaw doctor --lint هو وضع الأتمتة للقراءة فقط لفحوصات doctor. يستخدم مسار فحص السلامة المنظم، ولا يطالب، ولا يصلح أو يعيد كتابة الإعدادات/الحالة. استخدمه في CI، ونصوص التمهيد المسبق، وسير عمل المراجعة عندما تريد نتائج قابلة للقراءة آليا بدلا من مطالبات إصلاح موجهة. لا تُقبل خيارات إخراج التدقيق مثل --json و--severity-min و--all و--only و--skip إلا مع --lint.

openclaw doctor --lintopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --jsonopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --lint --only core/doctor/gateway-config --json

الإخراج البشري موجز:

doctor --lint: ran 6 check(s), 1 finding(s)  [warning] core/doctor/gateway-config gateway.mode - gateway.mode is unset; gateway start will be blocked.    fix: Run `openclaw configure` and set Gateway mode (local/remote), or `openclaw config set gateway.mode local`.

إخراج JSON هو سطح البرمجة النصية لتشغيلات التدقيق:

{  "ok": false,  "checksRun": 5,  "checksSkipped": 0,  "findings": [    {      "checkId": "core/doctor/gateway-config",      "severity": "warning",      "message": "gateway.mode is unset; gateway start will be blocked.",      "path": "gateway.mode",      "fixHint": "Run `openclaw configure` and set Gateway mode (local/remote), or `openclaw config set gateway.mode local`."    }  ]}

سلوك الخروج:

• 0: لا توجد نتائج عند عتبة الشدة المحددة أو فوقها
• 1: توجد نتيجة واحدة على الأقل تطابق العتبة المحددة
• 2: فشل الأمر/وقت التشغيل قبل إنتاج نتائج التدقيق

يتحكم --severity-min في النتائج المرئية وعتبة الخروج معا. على سبيل المثال، يمكن لـ openclaw doctor --lint --severity-min error ألا يطبع أي نتائج وأن يخرج بـ 0 حتى عند وجود نتائج info أو warning ذات شدة أقل.

يتحكم --all في الفحوصات المحددة قبل ترشيح الشدة. تشغيل التدقيق الافتراضي هو بوابة الأتمتة المستقرة، ويستبعد الفحوصات التي تكون اختيارية عمدا لأنها عميقة أو تاريخية أو أكثر احتمالا لإظهار بقايا قديمة قابلة للإصلاح. استخدم --all عندما تريد مخزون التدقيق الكامل دون سرد كل معرف فحص. يبقى --only <id> أداة الاختيار الأكثر دقة ويمكنه تشغيل أي فحص مسجل حسب المعرف.

فحوصات السلامة المنظمة

تستخدم فحوصات doctor الحديثة عقدا منظما صغيرا:

detect(ctx, scope?) -> HealthFinding[]repair?(ctx, findings) -> HealthRepairResult

يشغل detect() الأمر doctor --lint. أما repair() فهو اختياري ولا يُنظر فيه إلا من قبل doctor --fix / doctor --repair. وتستمر الفحوصات التي لم تُرحل إلى هذا الشكل في استخدام تدفق مساهمة doctor القديم.

هذا الفصل مقصود: يملك detect() التشخيص، بينما يملك repair() الإبلاغ عما غيّره أو ما كان سيغيره. يمكن لسياقات الإصلاح حمل طلبات dryRun/diff، ويمكن لنتائج الإصلاح إرجاع diffs منظمة من أجل تعديلات الإعدادات/الملفات إضافة إلى effects للخدمة أو العملية أو الحزمة أو الحالة أو الآثار الجانبية الأخرى. يتيح ذلك للفحوصات المحولة أن تنمو نحو doctor --fix --dry-run وتقارير الفروق دون نقل تخطيط التغيير إلى detect().

يبلغ repair() عما إذا حاول الإصلاح المطلوب باستخدام status: "repaired" | "skipped" | "failed". يعني غياب الحالة repaired، لذا لا تحتاج فحوصات الإصلاح البسيطة إلا إلى إرجاع التغييرات. عندما يرجع الإصلاح skipped أو failed، يبلغ doctor عن السبب ولا يشغل التحقق لذلك الفحص.

بعد إصلاح منظم ناجح، يعيد doctor تشغيل detect() مع النتائج التي أُصلحت كنطاق. يمكن للفحوصات استخدام النتائج أو المسارات أو قيم ocPath المحددة للتحقق المركز. إذا بقيت النتيجة موجودة، يبلغ doctor عن تحذير إصلاح بدلا من التعامل مع التغيير على أنه مكتمل بصمت.

تتضمن النتيجة:

تبقى فحوصات doctor الأساسية المحدثة مرتبطة بمساهمة doctor المرتبة التي تملك سلوكها البشري في doctor / doctor --fix. سجل السلامة المنظم المشترك هو نقطة التوسعة: تعمل الفحوصات المضمنة والمدعومة من Plugins بعد فحوصات doctor الأساسية بمجرد أن تسجلها الحزمة المالكة في مسار الأمر النشط. يعرض المسار الفرعي openclaw/plugin-sdk/health العقد نفسه لمستهلكي التوسعة هؤلاء.

اختيار الفحوصات

استخدم --only و--skip عندما يريد سير العمل بوابة مركزة:

openclaw doctor --lint --only core/doctor/gateway-config --jsonopenclaw doctor --lint --skip core/doctor/skills-readinessopenclaw doctor --lint --all --skip core/doctor/session-locks

يقبل --only و--skip معرفات الفحص الكاملة ويمكن تكرارهما. إذا لم يكن معرف --only مسجلا، فلن يعمل أي فحص لذلك المعرف؛ استخدم حقلي الأمر checksRun وchecksSkipped للتحقق من أن البوابة المركزة تختار الفحوصات التي تتوقعها.

وضع ما بعد الترقية

يشغل openclaw doctor --post-upgrade فحوصات توافق Plugin المخصصة لأن تُسلسل بعد بناء أو ترقية. تُصدر النتائج إلى stdout؛ ويخرج الأمر بالرمز 1 إذا كان لأي نتيجة level: "error". أضف --json لتلقي غلاف قابل للقراءة آليا ({ probesRun, findings }) مناسب لـ CI، وSkill المجتمعي fork-upgrade، وأدوات التحقق السريع الأخرى بعد الترقية. إذا كان فهرس Plugin المثبت مفقودا أو مشوها، فسيظل وضع JSON يصدر ذلك الغلاف مع نتيجة خطأ plugin.index_unavailable.

ملاحظات:

• في وضع Nix (OPENCLAW_NIX_MODE=1)، تظل فحوصات أداة الفحص للقراءة فقط تعمل، لكن doctor --fix وdoctor --repair وdoctor --yes وdoctor --generate-gateway-token تكون معطلة لأن openclaw.json غير قابل للتغيير. عدّل مصدر Nix لهذا التثبيت بدلًا من ذلك؛ وبالنسبة إلى nix-openclaw، استخدم البدء السريع الموجّه أولًا إلى الوكيل.
• لا تعمل المطالبات التفاعلية (مثل إصلاحات keychain/OAuth) إلا عندما يكون stdin هو TTY ولا يكون --non-interactive مضبوطًا. ستتخطى عمليات التشغيل بلا واجهة (cron، Telegram، بلا طرفية) المطالبات.
• الأداء: تتخطى عمليات تشغيل doctor غير التفاعلية تحميل Plugin المسبق حتى تبقى فحوصات السلامة بلا واجهة سريعة. ما زالت جلسات أداة الفحص التفاعلية تحمّل أسطح Plugin التي يحتاجها تدفق السلامة والإصلاح القديم.
• --lint أكثر صرامة من --non-interactive: فهو دائمًا للقراءة فقط، ولا يطالب أبدًا، ولا يطبّق عمليات الترحيل الآمنة أبدًا. شغّل doctor --fix أو doctor --repair عندما تريد من أداة الفحص إجراء تغييرات.
• افتراضيًا، لا تنفّذ أداة الفحص SecretRefs من نوع exec أثناء فحص الأسرار. استخدم openclaw doctor --allow-exec أو openclaw doctor --lint --allow-exec فقط عندما تريد عن قصد أن تشغّل أداة الفحص محللات الأسرار المضبوطة هذه.
• يكتب --fix (اسم مستعار لـ --repair) نسخة احتياطية إلى ~/.openclaw/openclaw.json.bak ويحذف مفاتيح التكوين غير المعروفة، مع سرد كل إزالة.
• يمكن لفحوصات السلامة المحدّثة أن تعرض مسار repair() لـ doctor --fix؛ أما الفحوصات التي لا تعرضه فتتابع عبر تدفق إصلاح أداة الفحص الحالي.
• يبلّغ doctor --fix --non-interactive عن تعريفات خدمة Gateway المفقودة أو القديمة لكنه لا يثبّتها ولا يعيد كتابتها خارج وضع إصلاح التحديث. شغّل openclaw gateway install لخدمة مفقودة، أو openclaw gateway install --force عندما تريد عن قصد استبدال المشغّل.
• تكتشف فحوصات سلامة الحالة الآن ملفات النصوص المعزولة في مجلد الجلسات. تتطلب أرشفتها بصيغة .deleted.<timestamp> تأكيدًا تفاعليًا؛ أما --fix و--yes وعمليات التشغيل بلا واجهة فتتركها في مكانها.
• تفحص أداة الفحص أيضًا ~/.openclaw/cron/jobs.json (أو cron.store) بحثًا عن أشكال مهام Cron القديمة وتعيد كتابتها قبل استيراد الصفوف القياسية إلى SQLite.
• تبلّغ أداة الفحص عن مهام Cron التي تتضمن تجاوزات payload.model صريحة، بما في ذلك أعداد نطاقات المزوّد وعدم التطابق مع agents.defaults.model، حتى تظهر المهام المجدولة التي لا ترث النموذج الافتراضي أثناء تحقيقات المصادقة أو الفوترة.
• على Linux، تحذّر أداة الفحص عندما لا يزال crontab الخاص بالمستخدم يشغّل ~/.openclaw/bin/ensure-whatsapp.sh القديم؛ لم يعد هذا السكربت مُصانًا ويمكنه تسجيل انقطاعات WhatsApp Gateway كاذبة عندما يفتقر Cron إلى بيئة user-bus الخاصة بـ systemd.
• عندما يكون WhatsApp مفعّلًا، تتحقق أداة الفحص من وجود حلقة أحداث Gateway متدهورة مع عملاء openclaw-tui المحليين الذين ما زالوا يعملون. يوقف doctor --fix عملاء TUI المحليين المتحقق منهم فقط حتى لا تصطف ردود WhatsApp خلف حلقات تحديث TUI القديمة.
• تعيد أداة الفحص كتابة مراجع نماذج openai-codex/* القديمة إلى مراجع openai/* القياسية عبر النماذج الأساسية، والبدائل، ونماذج توليد الصور/الفيديو، وتجاوزات Heartbeat/الوكيل الفرعي/Compaction، والخطافات، وتجاوزات نماذج القنوات، ومسامير توجيه الجلسات القديمة. يرحّل --fix أيضًا ملفات تعريف مصادقة openai-codex:* القديمة ومدخلات auth.order.openai-codex إلى openai:*، وينقل نية Codex إلى مدخلات agentRuntime.id: "codex" ذات النطاق المحدد بالمزوّد/النموذج، ويزيل مسامير وقت التشغيل القديمة للوكيل الكامل/الجلسة، ويبقي مراجع وكلاء OpenAI التي تم إصلاحها على توجيه مصادقة Codex بدلًا من مصادقة مفتاح API المباشر لـ OpenAI.
• تنظف أداة الفحص حالة تجهيز تبعيات Plugin القديمة التي أنشأتها إصدارات OpenClaw الأقدم، وتعيد ربط حزمة openclaw المضيفة لملحقات npm المُدارة التي تعلن عنها كتبعية نظيرة. كما تصلح Plugins القابلة للتنزيل المفقودة والمشار إليها في التكوين، مثل plugins.entries أو القنوات المضبوطة أو إعدادات المزوّد/البحث المضبوطة أو أوقات تشغيل الوكلاء المضبوطة. أثناء تحديثات الحزم، تتخطى أداة الفحص إصلاح Plugin الخاص بمدير الحزم إلى أن يكتمل تبديل الحزمة؛ أعد تشغيل openclaw doctor --fix بعد ذلك إذا كان Plugin مضبوط ما زال يحتاج إلى استرداد. إذا فشل التنزيل، تبلّغ أداة الفحص عن خطأ التثبيت وتحافظ على مدخل Plugin المضبوط لمحاولة الإصلاح التالية.
• تصلح أداة الفحص تكوين Plugin القديم عبر إزالة معرّفات Plugin المفقودة من plugins.allow/plugins.deny/plugins.entries، إضافة إلى تكوين القناة المتدلي المطابق، وأهداف Heartbeat، وتجاوزات نماذج القنوات عندما يكون اكتشاف Plugin سليمًا.
• تعزل أداة الفحص تكوين Plugin غير الصالح عبر تعطيل مدخل plugins.entries.<id> المتأثر وإزالة حمولة config غير الصالحة الخاصة به. يتخطى بدء Gateway أصلًا ذلك Plugin السيئ فقط حتى تستمر Plugins والقنوات الأخرى في العمل.
• اضبط OPENCLAW_SERVICE_REPAIR_POLICY=external عندما يكون مشرف آخر مالكًا لدورة حياة Gateway. تظل أداة الفحص تبلّغ عن سلامة Gateway/الخدمة وتطبق الإصلاحات غير الخدمية، لكنها تتخطى تثبيت/بدء/إعادة تشغيل/تهيئة الخدمة وتنظيف الخدمة القديمة.
• على Linux، تتجاهل أداة الفحص وحدات systemd الإضافية غير النشطة الشبيهة بـ Gateway، ولا تعيد كتابة بيانات وصف الأمر/نقطة الدخول لخدمة Gateway systemd قيد التشغيل أثناء الإصلاح. أوقف الخدمة أولًا أو استخدم openclaw gateway install --force عندما تريد عن قصد استبدال المشغّل النشط.
• ترحّل أداة الفحص تلقائيًا تكوين Talk المسطح القديم (talk.voiceId وtalk.modelId وما شابههما) إلى talk.provider + talk.providers.<provider>.
• لم تعد عمليات تشغيل doctor --fix المتكررة تبلّغ/تطبّق تطبيع Talk عندما يكون الفرق الوحيد هو ترتيب مفاتيح الكائن.
• تتضمن أداة الفحص فحص جاهزية بحث الذاكرة ويمكنها التوصية بـ openclaw configure --section model عندما تكون بيانات اعتماد التضمين مفقودة.
• تحذّر أداة الفحص عندما لا يكون هناك مالك أوامر مضبوط. مالك الأوامر هو حساب المشغّل البشري المسموح له بتشغيل أوامر المالك فقط والموافقة على الإجراءات الخطرة. لا يتيح إقران الرسائل المباشرة إلا لشخص ما التحدث إلى الروبوت؛ إذا وافقت على مرسل قبل وجود تهيئة المالك الأول، فاضبط commands.ownerAllowFrom صراحة.
• تبلّغ أداة الفحص عن ملاحظة معلوماتية عندما تكون وكلاء وضع Codex مضبوطة وتوجد أصول Codex CLI شخصية في موطن Codex الخاص بالمشغّل. تستخدم عمليات تشغيل خادم تطبيق Codex المحلية مواطن معزولة لكل وكيل، لذا ثبّت Codex Plugin أولًا إذا لزم، ثم استخدم openclaw migrate plan codex لجرد الأصول التي ينبغي ترقيتها عمدًا.
• تزيل أداة الفحص plugins.entries.codex.config.codexDynamicToolsProfile المتقاعد؛ يحافظ خادم تطبيق Codex دائمًا على أدوات مساحة العمل الأصلية في Codex كأدوات أصلية.
• تحذّر أداة الفحص عندما تكون Skills المسموحة للوكيل الافتراضي غير متاحة في بيئة وقت التشغيل الحالية لأن المتطلبات الخاصة بالثنائيات أو متغيرات البيئة أو التكوين أو نظام التشغيل مفقودة. يمكن لـ doctor --fix تعطيل تلك Skills غير المتاحة باستخدام skills.entries.<skill>.enabled=false؛ ثبّت/اضبط المتطلب المفقود بدلًا من ذلك عندما تريد إبقاء Skill نشطة.
• إذا كان وضع sandbox مفعّلًا لكن Docker غير متاح، تبلّغ أداة الفحص عن تحذير عالي الإشارة مع معالجة (install Docker أو openclaw config set agents.defaults.sandbox.mode off).
• إذا كانت ملفات سجل sandbox القديمة أو مجلدات الشظايا موجودة (~/.openclaw/sandbox/containers.json أو ~/.openclaw/sandbox/browsers.json أو ~/.openclaw/sandbox/containers/ أو ~/.openclaw/sandbox/browsers/)، تبلّغ عنها أداة الفحص؛ يرحّل openclaw doctor --fix المدخلات الصالحة إلى SQLite ويعزل الملفات القديمة غير الصالحة.
• إذا كان gateway.auth.token/gateway.auth.password مُدارين عبر SecretRef وغير متاحين في مسار الأمر الحالي، تبلّغ أداة الفحص عن تحذير للقراءة فقط ولا تكتب بيانات اعتماد بديلة بنص صريح. بالنسبة إلى SecretRefs المدعومة بـ exec، تتخطى أداة الفحص التنفيذ ما لم يكن --allow-exec موجودًا.
• إذا فشل فحص SecretRef الخاص بالقناة في مسار إصلاح، تتابع أداة الفحص وتبلّغ عن تحذير بدلًا من الخروج مبكرًا.
• بعد ترحيلات مجلد الحالة، تحذّر أداة الفحص عندما تعتمد حسابات Telegram أو Discord الافتراضية المفعّلة على بديل متغيرات البيئة ويكون TELEGRAM_BOT_TOKEN أو DISCORD_BOT_TOKEN غير متاح لعملية أداة الفحص.
• يتطلب التحليل التلقائي لأسماء مستخدمي allowFrom في Telegram (doctor --fix) رمز Telegram قابلًا للحل في مسار الأمر الحالي. إذا لم يكن فحص الرمز متاحًا، تبلّغ أداة الفحص عن تحذير وتتخطى التحليل التلقائي في تلك الجولة.

macOS: تجاوزات بيئة launchctl

إذا كنت قد شغّلت سابقًا launchctl setenv OPENCLAW_GATEWAY_TOKEN ... (أو ...PASSWORD)، فإن تلك القيمة تتجاوز ملف التكوين لديك ويمكن أن تسبب أخطاء "غير مصرّح" مستمرة.

launchctl getenv OPENCLAW_GATEWAY_TOKENlaunchctl getenv OPENCLAW_GATEWAY_PASSWORD launchctl unsetenv OPENCLAW_GATEWAY_TOKENlaunchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

ذات صلة

• مرجع CLI
• أداة فحص Gateway