`openclaw doctor`

فحوصات السلامة والإصلاحات السريعة لـ Gateway والقنوات وPlugins وSkills وتوجيه النماذج والحالة المحلية وترحيلات الإعدادات. استخدمه كلما لم يعمل شيء كما هو متوقع وأردت أمرًا واحدًا يوضح الخطأ. ذو صلة:

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

الأوضاع

لدى Doctor خمسة أوضاع:

الوضع	الأمر	السلوك
الفحص	`openclaw doctor`	فحوصات موجهة للبشر ومطالبات إرشادية.
الإصلاح	`openclaw doctor --fix`	يطبق الإصلاحات المدعومة، باستخدام المطالبات ما لم يكن الإصلاح غير التفاعلي آمنًا.
التدقيق	`openclaw doctor --lint`	نتائج منظمة للقراءة فقط لأغراض CI والفحص المسبق وبوابات المراجعة.
صيانة SQLite المشتركة	`openclaw doctor --state-sqlite compact`	ينشئ نقاط تحقق صراحةً ويضغط ويتحقق من قاعدة بيانات الحالة المشتركة المعتمدة.
ترحيل SQLite للجلسات	`openclaw doctor --session-sqlite <mode>`	يفحص حالة الجلسات أو يستوردها أو يتحقق منها أو يضغطها أو يستعيدها أو يرجعها.

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

أمثلة

openclaw doctor
openclaw doctor --lint
openclaw doctor --lint --json
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --all
openclaw doctor --lint --allow-exec
openclaw doctor --deep
openclaw doctor --fix
openclaw doctor --fix --non-interactive
openclaw doctor --generate-gateway-token
openclaw doctor --post-upgrade
openclaw doctor --post-upgrade --json
openclaw doctor --state-sqlite compact
openclaw doctor --state-sqlite compact --json
openclaw doctor --session-sqlite inspect --session-sqlite-all-agents
openclaw doctor --session-sqlite dry-run --session-sqlite-agent main --json
openclaw doctor --session-sqlite import --session-sqlite-all-agents
openclaw doctor --session-sqlite validate --session-sqlite-all-agents --json
openclaw doctor --session-sqlite compact --session-sqlite-all-agents
openclaw doctor --session-sqlite recover --github-issue
openclaw doctor --session-sqlite restore --session-sqlite-all-agents

بالنسبة إلى الأذونات الخاصة بالقنوات، استخدم مجسّات القنوات بدلًا من doctor:

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

يُبلغ channels capabilities عن الأذونات الفعلية للبوت لهدف قناة محدد. ويدقق channels status --probe جميع القنوات المُعدّة وأهداف الانضمام التلقائي إلى الصوت.

الخيارات

الخيار	التأثير
`--no-workspace-suggestions`	يعطّل اقتراحات ذاكرة مساحة العمل/البحث.
`--yes`	يقبل القيم الافتراضية دون مطالبة.
`--repair` / `--fix`	يطبق الإصلاحات الموصى بها غير المتعلقة بالخدمات دون مطالبة (`--fix` اسم بديل). لا تزال عمليات تثبيت/إعادة كتابة خدمة Gateway تتطلب تأكيدًا تفاعليًا أو أوامر `gateway` صريحة.
`--force`	يطبق إصلاحات مكثفة، بما في ذلك استبدال إعدادات الخدمة المخصصة.
`--non-interactive`	يعمل دون مطالبات؛ الترحيلات الآمنة والإصلاحات غير المتعلقة بالخدمات فقط.
`--generate-gateway-token`	ينشئ رمز Gateway ويعدّه.
`--allow-exec`	يسمح لـ Doctor بتنفيذ SecretRefs الخاصة بـ `exec` المُعدّة أثناء التحقق من الأسرار.
`--deep`	يفحص خدمات النظام بحثًا عن عمليات تثبيت إضافية لـ Gateway؛ ويبلغ عن عمليات تسليم إعادة التشغيل الأخيرة لمشرف Gateway.
`--lint`	يشغّل فحوصات السلامة المحدّثة في وضع القراءة فقط ويصدر نتائج تشخيصية.
`--post-upgrade`	يشغّل مجسّات توافق Plugins بعد الترقية؛ تُرسل النتائج إلى stdout؛ ويكون رمز الخروج 1 إذا وُجدت أي نتيجة بمستوى خطأ.
`--state-sqlite <mode>`	يشغّل صيانة SQLite صريحة للحالة المشتركة. الوضع الوحيد هو `compact`.
`--session-sqlite <mode>`	يشغّل وضع ترحيل SQLite المستهدف للجلسات: `inspect` أو `dry-run` أو `import` أو `validate` أو `compact` أو `recover` أو `restore`.
`--session-sqlite-store <path>`	مع `--session-sqlite`: يحدد مسار مخزن `sessions.json` قديمًا واحدًا.
`--session-sqlite-agent <id>`	مع `--session-sqlite`: يحدد وكيلًا مُعدًّا واحدًا.
`--session-sqlite-all-agents`	مع `--session-sqlite`: يحدد مخازن الوكلاء المُعدّة والمكتشفة.
`--github-issue`	مع `--session-sqlite recover`: يعدّ تقرير مشكلة منقحًا لـ openclaw/openclaw؛ وينشئه Doctor باستخدام `gh` بعد `--yes` أو التأكيد التفاعلي.
`--json`	مع `--lint`: نتائج JSON. مع `--post-upgrade`: `{ probesRun, findings }`. مع `--state-sqlite` أو `--session-sqlite`: تقرير الصيانة بصيغة JSON.
`--severity-min <level>`	مع `--lint`: يستبعد النتائج الأدنى من `info` أو `warning` أو `error`.
`--all`	مع `--lint`: يشغّل جميع الفحوصات المسجلة، بما فيها الفحوصات الاختيارية المستبعدة من المجموعة الافتراضية.
`--skip <id>`	مع `--lint`: يتخطى معرّف فحص. قابل للتكرار.
`--only <id>`	مع `--lint`: يشغّل معرّفات الفحص المحددة فقط. قابل للتكرار.

لا تُقبل --severity-min و--all و--only و--skip إلا مع --lint؛ وتُقبل --json مع --lint و--post-upgrade و--state-sqlite و--session-sqlite.

وضع التدقيق

openclaw doctor --lint للقراءة فقط: بلا مطالبات أو إصلاح أو إعادة كتابة للإعدادات/الحالة.

openclaw doctor --lint
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --json
openclaw doctor --lint --all
openclaw doctor --lint --allow-exec
openclaw doctor --lint --only core/doctor/gateway-config --json
openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

المخرجات الموجهة للبشر موجزة:

doctor --lint: شغّل 6 فحوصات، ووجد نتيجة واحدة
  [warning] core/doctor/gateway-config gateway.mode - لم تُضبط gateway.mode؛ سيُحظر بدء Gateway.
    الإصلاح: شغّل `openclaw configure` واضبط وضع Gateway (محلي/بعيد)، أو نفّذ `openclaw config set gateway.mode local`.

مخرجات JSON هي واجهة البرمجة النصية:

{
  "ok": false,
  "checksRun": 5,
  "checksSkipped": 0,
  "findings": [
    {
      "checkId": "core/doctor/gateway-config",
      "severity": "warning",
      "message": "لم تُضبط gateway.mode؛ سيُحظر بدء Gateway.",
      "path": "gateway.mode",
      "fixHint": "شغّل `openclaw configure` واضبط وضع Gateway (محلي/بعيد)، أو نفّذ `openclaw config set gateway.mode local`."
    }
  ]
}

رموز الخروج:

الرمز	المعنى
`0`	لا توجد نتائج عند حد الخطورة المحدد أو أعلى منه.
`1`	توجد نتيجة واحدة على الأقل تستوفي الحد المحدد.
`2`	فشل الأمر/وقت التشغيل قبل إمكان إنتاج نتائج التدقيق.

يتحكم --severity-min في النتائج التي تُطبع وفي حد الخروج كليهما: يمكن أن يطبع openclaw doctor --lint --severity-min error لا شيء ويخرج بالرمز 0 حتى عند وجود نتائج info/warning أقل خطورة. يتحكم --all في الفحوصات المحددة قبل تصفية الخطورة. يستبعد تشغيل التدقيق الافتراضي الفحوصات العميقة أو التاريخية أو الأكثر احتمالًا لإظهار بقايا قديمة قابلة للإصلاح؛ استخدم --all للحصول على القائمة الكاملة. يُعد --only <id> أداة التحديد الأدق، ويمكنه تشغيل أي فحص مسجل حسب المعرّف. يُبلغ core/doctor/local-audio-acceleration عن أمر STT المحلي المحدد تلقائيًا، وأدلة منفصلة للواجهات الخلفية القادرة/المطلوبة/المرصودة، وترتيب البدائل دون تحميل نموذج كلام. ويصدر نتيجة معلوماتية، لذا ضمّن --severity-min info لعرضها.

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

تستخدم فحوصات Doctor الحديثة عقدًا مقسمًا صغيرًا:

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

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

الحقل	الغرض
`checkId`	معرّف ثابت لمرشحات التخطي/الحصر وقوائم السماح في CI.
`severity`	`info` أو `warning` أو `error`.
`message`	وصف للمشكلة قابل للقراءة البشرية.
`path`	مسار الإعداد أو الملف أو المسار المنطقي عند توفره.
`line` / `column`	موضع المصدر عند توفره.
`ocPath`	عنوان `oc://` دقيق عندما يمكن للفحص الإشارة إلى واحد.
`fixHint`	إجراء مقترح للمشغّل أو ملخص للإصلاح.

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

تحديد الفحوصات

openclaw doctor --lint --only core/doctor/gateway-config --json
openclaw doctor --lint --skip core/doctor/skills-readiness
openclaw doctor --lint --all --skip core/doctor/session-locks

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

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

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

Compaction لـ SQLite للحالة المشتركة

يمثل openclaw doctor --state-sqlite compact صيانة صريحة دون اتصال لقاعدة بيانات الحالة المشتركة الأساسية الموجودة في <state-dir>/state/openclaw.sqlite. ولا يقبل مسارًا عشوائيًا لقاعدة بيانات، ولا تستدعيه أبدًا عملية Gateway العادية، كما أنه ليس جزءًا من openclaw doctor --fix. يحصل الأمر على قفل ملكية الحالة نفسه المستخدم عند بدء تشغيل Gateway ويحتفظ به طوال التحقق، وإنشاء نقطة التحقق، وVACUUM، وفحوصات التكامل النهائية. ويرفض التشغيل أثناء امتلاك Gateway أو أمر صيانة SQLite آخر لذلك القفل. يظل قفل الحالة نشطًا عندما يتخطى OPENCLAW_ALLOW_MULTI_GATEWAY=1 مثيل Gateway الفردي لكل إعداد، ولذلك لا تحتاج صدفة المشغّل إلى وراثة بيئة خدمة Gateway كي تكتشفها الصيانة. أوقف Gateway وأنشئ أولًا نسخة احتياطية جرى التحقق منها:

openclaw gateway stop
openclaw backup create --verify
openclaw doctor --state-sqlite compact --json
openclaw gateway start

يقوم الأمر بما يلي:

يتطلب ملفًا عاديًا في مسار الحالة المشتركة الأساسي. يُبلّغ عن قاعدة البيانات المفقودة بالحالة skipped وينتهي بنجاح.
يتحقق من إصدار المخطط المدعوم حاليًا ومن schema_meta.role = "global" قبل إنشاء نقطة تحقق أو تغيير الملف.
يتطلب wal_checkpoint(TRUNCATE) غير مشغول. أوقف أي عملية OpenClaw متبقية وأعد المحاولة إذا كانت نقطة التحقق مشغولة.
يضبط auto_vacuum على INCREMENTAL، ويشغّل VACUUM كاملًا، ثم ينشئ نقطة تحقق مرة أخرى.
يشغّل quick_check وintegrity_check وforeign_key_check، ثم يعيد تطبيق أذونات المالك فقط على قاعدة البيانات وملفات SQLite الجانبية.

تُبلّغ مخرجات JSON عن أحجام قاعدة البيانات وWAL، وصفحات القائمة الحرة، وحجم الصفحة، وقيمة auto_vacuum قبل Compaction وبعده، إضافة إلى البايتات المستعادة ونتائج quick_check وintegrity_check. يُفرض foreign_key_check وفق مبدأ الإخفاق المغلق ولا يملك حقل نجاح منفصلًا. يُبلّغ SQLite عن auto_vacuum بالقيمة 0 لعدم وجوده، و1 للكامل، و2 للتزايدي. يفشل Compaction من دون تعديل عندما يكون المخطط قديمًا، أو أحدث من بناء OpenClaw الجاري، أو تابعًا لقاعدة بيانات وكيل. شغّل openclaw doctor --fix أولًا لمخطط حالة مشتركة أقدم. استعد نسخة احتياطية متوافقة أو رقِّ OpenClaw في حالة وجود مخطط أحدث.

ترحيل جلسات SQLite

يستورد OpenClaw صفوف الجلسات القديمة وسجل النصوص إلى قاعدة بيانات SQLite الخاصة بكل وكيل تلقائيًا أثناء بدء تشغيل Gateway وأثناء openclaw doctor --fix. ويُعد openclaw doctor --session-sqlite <mode> أداة الفحص والتحقق الموجهة لذلك الترحيل. توجد صفوف جلسات وقت التشغيل الحالية في ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. وتُعد ملفات sessions.json القديمة مصادر للترحيل. تُستورد ملفات JSONL للنصوص النشطة وتُنقل إلى الأرشيف خارج دليل الجلسات النشطة بعد نجاح الاستيراد؛ وتظل ملفات JSONL ذات طبقة الأرشيف عناصر دعم، لا مسارات احتياطية لوقت التشغيل. الأوضاع:

الوضع	السلوك
`inspect`	يقرأ أعداد العناصر القديمة وعناصر SQLite، إضافة إلى ملفات JSONL غير المشار إليها، من دون استيراد.
`dry-run`	يحلل الإدخالات القديمة وملفات JSONL للنصوص، ويحصي الصفوف القابلة للاستيراد، ويُبلّغ عن المشكلات من دون كتابة صفوف SQLite.
`import`	يستورد الإدخالات القديمة وأحداث النصوص إلى SQLite للأهداف المحددة.
`validate`	يقارن المصادر القديمة المحددة بصفوف SQLite وأعداد أحداث النصوص.
`compact`	ينشئ نقطة تحقق ويشغّل VACUUM لقواعد بيانات SQLite الخاصة بالوكلاء المحددين لاستعادة الصفحات الحرة بعد عمليات الحذف الكبيرة أو تنظيف الأرشيف.
`recover`	يستعيد أحدث تشغيل ترحيل فاشل، ويتحقق من أهدافه، ويُعد تقرير مشكلة GitHub منقّحًا.
`restore`	يستعيد عناصر النصوص المؤرشفة من بيانات الترحيل المسجلة من دون حذف بيانات SQLite.

المحددات:

الافتراضي: مخزن الوكيل الافتراضي المضبوط، عندما يكون ملف المخزن القديم موجودًا.
--session-sqlite-agent <id>: وكيل واحد مضبوط.
--session-sqlite-all-agents: مخازن الوكلاء المضبوطة إضافة إلى مخازن الوكلاء المكتشفة.
--session-sqlite-store <path>: مسار sessions.json قديم وصريح واحد.

تسلسل الفحص اليدوي:

openclaw doctor --session-sqlite inspect --session-sqlite-all-agents
openclaw doctor --session-sqlite dry-run --session-sqlite-all-agents --json
openclaw doctor --session-sqlite import --session-sqlite-all-agents
openclaw doctor --session-sqlite validate --session-sqlite-all-agents --json
openclaw doctor --session-sqlite compact --session-sqlite-all-agents
openclaw doctor --session-sqlite recover --github-issue

أنشئ نسخة احتياطية من دليل حالة OpenClaw قبل تشغيل import على تثبيت ذي سجل مهم. ينتهي validate برمز غير صفري عندما يكون إدخال قديم محدد مفقودًا من SQLite، أو يختلف معرّف جلسة، أو يختلف عدد أحداث النص. عند استخدام --session-sqlite-store <path>، تحقق من احتواء التقرير على عدد الأهداف المتوقع؛ فمسار المخزن الصريح غير الموجود لا يحدد أي أهداف. تستعيد عمليات الحذف في SQLite الصفحات داخل قاعدة البيانات أولًا؛ ولا تؤدي بالضرورة إلى تقليص ملف قاعدة البيانات فورًا. بعد حذف نصوص كبيرة أو أرشفتها، شغّل openclaw doctor --session-sqlite compact --session-sqlite-all-agents لإنشاء نقاط تحقق لملفات WAL، وتشغيل VACUUM، والإبلاغ عن أحجام قاعدة البيانات وWAL قبل العملية وبعدها. يتطلب Compaction ملفًا عاديًا بالمخطط الحالي للوكيل، والبيانات الوصفية الدائمة لمالك الوكيل المحدد، وعدم وجود مقبض مفتوح في عملية doctor. تحتفظ الأوضاع الإتلافية import وcompact وrecover وrestore بقفل ملكية الحالة نفسه المستخدم عند بدء تشغيل Gateway طوال عملياتها؛ وتظل inspect وdry-run وvalidate للقراءة فقط ولا تحصل عليه. أوقف Gateway أولًا. تفشل الأوضاع الإتلافية بدلًا من التسابق مع عمليات الكتابة المباشرة أو مع أمر صيانة آخر. يجب أن يكون هدف --session-sqlite-store الإتلافي داخل دليل الحالة النشط؛ اضبط OPENCLAW_STATE_DIR على دليل الحالة المالك للمخزن قبل صيانة تثبيت آخر. تُرفض الأهداف المرتبطة حاليًا بروابط صلبة لأن مسارًا آخر يمكنه مشاركة عقدة قاعدة البيانات نفسها خارج دليل الحالة المقفل. وتشمل فحوصات الملكية نفسها ملفات WAL والذاكرة المشتركة وسجل التراجع الجانبية في SQLite. يكتب كل استيراد بيانًا ضمن ~/.openclaw/session-sqlite-migration-runs/ قبل نقل عناصر النصوص إلى الأرشيف. إذا أبلغ بدء التشغيل عن فشل ترحيل جلسات SQLite بعد نقل العناصر، فشغّل الاسترداد:

openclaw doctor --session-sqlite recover --github-issue

يحدد الاسترداد أحدث بيان ترحيل فاشل، ويستعيد فقط العناصر المؤرشفة الخاصة بالبيان، ويتحقق من الأهداف المتأثرة، ويحدّث تقريري .failure.md و.failure.json المنقّحين، ويُعد نص مشكلة GitHub يتجنب محتويات النصوص، والبيئة الخام، والأسرار، والإعدادات غير المحدودة. عندما لا يوجد بيان ترحيل فاشل لكن تكون قاعدة بيانات SQLite لوكيل محدد تالفة، أو ليست قاعدة بيانات، أو تحتوي على ملفات سجل جانبية من دون قاعدة بيانات رئيسية، ينسخ الاسترداد مجموعة الملفات الكاملة إلى دليل فحص مؤقت. يستطيع SQLite التراجع عن سجل ساخن صالح في تلك النسخة المؤقتة قبل تشغيل quick_check وintegrity_check وforeign_key_check، بينما تظل ملفات الأدلة الجنائية الأصلية من دون تغيير. تحافظ فحوصات التكامل الفاشلة أو الملفات الجانبية اليتيمة على ملفات DB وWAL وSHM وسجل التراجع عبر إعادة تسمية المجموعة المكتشفة بأكملها باستخدام لاحقة .corrupt-<timestamp> واحدة. يؤدي فشل إعادة تسمية تم اعتراضه إلى إعادة الملفات المنقولة بالفعل إلى مواضعها قبل الإبلاغ عن الفشل، كي لا تنقسم مجموعة ملفات قابلة للاسترداد بصمت. أوقف Gateway قبل الاسترداد؛ فنسخ مجموعة ملفات SQLite تتغير بنشاط أو إعادة تسميتها غير آمن ويتصرف بصورة مختلفة باختلاف أنظمة التشغيل. باستخدام --github-issue --yes، يستخدم doctor واجهة GitHub CLI لإنشاء المشكلة في openclaw/openclaw؛ ومن دون تأكيد، يكتب تقرير الدعم المحلي ويطبع عنوان URL لمشكلة معبأة مسبقًا. يظل restore عملية التراجع منخفضة المستوى. ويستخدم سجلات sourcePath -> archivePath في البيان، ويعيد العناصر المؤرشفة فقط عندما يكون المسار الأصلي مفقودًا، ويُبلّغ عن التعارضات عندما يوجد كلا المسارين، ويترك قاعدة بيانات SQLite في مكانها.

الرجوع إلى إصدار أقدم بعد ترحيل جلسات SQLite

قبل بدء إصدار أقدم من OpenClaw مدعوم بالملفات، استعد عناصر النصوص القديمة المؤرشفة:

openclaw doctor --session-sqlite restore --session-sqlite-all-agents

تقرأ الإصدارات الأقدم إدخالات sessions.json ومسارات sessionFile المسجّلة في تلك الإدخالات. بعد الترحيل إلى SQLite، تنقل عمليات الاستيراد الناجحة نصوص JSONL الساخنة إلى session-sqlite-import-archive/، ولذلك لا يمكن لبيئة التشغيل الأقدم رؤية ذلك السجل حتى تعيد عملية الاستعادة العناصر المسجّلة في البيان إلى مساراتها الأصلية. لا تحذف عملية الاستعادة بيانات SQLite. فالجلسات المنشأة بعد الانتقال إلى SQLite لا توجد إلا في SQLite ولن تظهر لبيئة التشغيل الأقدم. وإذا أجريت ترقية لاحقًا مرة أخرى، فنفّذ تسلسل التحقق المعتاد من الترحيل الوارد أعلاه حتى يتمكن OpenClaw من مقارنة العناصر القديمة المستعادة بصفوف SQLite قبل الاستيراد.

ملاحظات

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

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

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

launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

الطبيب

`openclaw doctor`

الأوضاع

أمثلة

الخيارات

وضع التدقيق

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

تحديد الفحوصات

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

Compaction لـ SQLite للحالة المشتركة

ترحيل جلسات SQLite

الرجوع إلى إصدار أقدم بعد ترحيل جلسات SQLite

ملاحظات

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

ذو صلة

​openclaw doctor

​الأوضاع

​أمثلة

​الخيارات

​وضع التدقيق

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

​تحديد الفحوصات

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

​Compaction لـ SQLite للحالة المشتركة

​ترحيل جلسات SQLite

​الرجوع إلى إصدار أقدم بعد ترحيل جلسات SQLite

​ملاحظات

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

​ذو صلة

`openclaw doctor`

الأوضاع

أمثلة

الخيارات

وضع التدقيق

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

تحديد الفحوصات

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

Compaction لـ SQLite للحالة المشتركة

ترحيل جلسات SQLite

الرجوع إلى إصدار أقدم بعد ترحيل جلسات SQLite

ملاحظات

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

ذو صلة