---
read_when:
    - لديك مشكلات في الاتصال/المصادقة وتريد إصلاحات إرشادية
    - لقد أجريت تحديثًا وتريد التحقق من سلامته
summary: مرجع CLI لـ `openclaw doctor` (فحوصات السلامة + الإصلاحات الموجّهة)
title: الطبيب
x-i18n:
    generated_at: "2026-07-16T13:43:35Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 322af63f52a3d864e46da332353ca921a4462e13fa849986d936524759f80ccc
    source_path: cli/doctor.md
    workflow: 16
---

# `openclaw doctor`

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

ذو صلة:

- استكشاف الأخطاء وإصلاحها: [استكشاف الأخطاء وإصلاحها](/ar/gateway/troubleshooting)
- تدقيق الأمان: [الأمان](/ar/gateway/security)

## الأوضاع

لدى 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 الإعدادات أو الحالة.

## أمثلة

```bash
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`:

```bash
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` للقراءة فقط: بلا مطالبات أو إصلاح أو إعادة كتابة للإعدادات/الحالة.

```bash
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
```

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

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

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

```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 الحديثة عقدًا مقسمًا صغيرًا:

```ts
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.

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

```bash
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 وأنشئ أولًا نسخة احتياطية جرى التحقق منها:

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

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

1. يتطلب ملفًا عاديًا في مسار الحالة المشتركة الأساسي. يُبلّغ عن قاعدة
   البيانات المفقودة بالحالة `skipped` وينتهي بنجاح.
2. يتحقق من إصدار المخطط المدعوم حاليًا ومن
   `schema_meta.role = "global"` قبل إنشاء نقطة تحقق أو تغيير الملف.
3. يتطلب `wal_checkpoint(TRUNCATE)` غير مشغول. أوقف أي عملية OpenClaw
   متبقية وأعد المحاولة إذا كانت نقطة التحقق مشغولة.
4. يضبط `auto_vacuum` على `INCREMENTAL`، ويشغّل `VACUUM` كاملًا، ثم ينشئ نقطة تحقق
   مرة أخرى.
5. يشغّل `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` قديم وصريح واحد.

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

```bash
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 بعد
نقل العناصر، فشغّل الاسترداد:

```bash
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 مدعوم بالملفات، استعد
عناصر النصوص القديمة المؤرشفة:

```bash
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، استخدم [البدء السريع](https://github.com/openclaw/nix-openclaw#quick-start) الذي يضع الوكيل أولًا.
- لا تعمل المطالبات التفاعلية (إصلاحات سلسلة المفاتيح/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" مستمرة.

```bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
```

## ذو صلة

- [مرجع CLI](/ar/cli)
- [أداة doctor الخاصة بـ Gateway](/ar/gateway/doctor)
