> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# استكشاف الأخطاء وإصلاحها

مساعدات تصحيح الأخطاء لمخرجات البث، خصوصا عندما يخلط مزود ما الاستدلال داخل النص العادي.

## تجاوزات التصحيح في وقت التشغيل

استخدم `/debug` في الدردشة لتعيين تجاوزات إعدادات **وقت التشغيل فقط** (في الذاكرة، لا على القرص).
يكون `/debug` معطلا افتراضيا؛ فعله باستخدام `commands.debug: true`.
هذا مفيد عندما تحتاج إلى تبديل إعدادات غامضة دون تعديل `openclaw.json`.

أمثلة:

```
/debug show
/debug set messages.responsePrefix="[openclaw]"
/debug unset messages.responsePrefix
/debug reset
```

يمسح `/debug reset` كل التجاوزات ويعود إلى الإعدادات الموجودة على القرص.

## مخرجات تتبع الجلسة

استخدم `/trace` عندما تريد رؤية أسطر التتبع/التصحيح التي يملكها Plugin في جلسة واحدة
دون تشغيل وضع الإسهاب الكامل.

أمثلة:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/trace
/trace on
/trace off
```

استخدم `/trace` لتشخيصات Plugin مثل ملخصات تصحيح Active Memory.
استمر في استخدام `/verbose` لمخرجات الحالة/الأدوات المسهبة العادية، واستمر في استخدام
`/debug` لتجاوزات إعدادات وقت التشغيل فقط.

## تتبع دورة حياة Plugin

استخدم `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1` عندما تبدو أوامر دورة حياة Plugin بطيئة
وتحتاج إلى تفصيل مراحل مدمج لبيانات Plugin الوصفية، والاكتشاف، والسجل،
ومرآة وقت التشغيل، وتعديل الإعدادات، وأعمال التحديث. التتبع اختياري ويكتب
إلى stderr، لذلك تبقى مخرجات أوامر JSON قابلة للتحليل.

مثال:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
```

مثال على المخرجات:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"
[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"
```

استخدم هذا للتحقيق في دورة حياة Plugin قبل اللجوء إلى محلل CPU.
إذا كان الأمر يعمل من نسخة مصدرية، ففضل قياس وقت التشغيل المبني
باستخدام `node dist/entry.js ...` بعد `pnpm build`؛ يقيس `pnpm openclaw ...`
أيضا حمل مشغل المصدر.

## بدء CLI وقياس أداء الأوامر

استخدم اختبار بدء التشغيل المرجعي المودع عندما يبدو أمر ما بطيئا:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm test:startup:bench:smoke
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
```

للقياس لمرة واحدة عبر مشغل المصدر العادي، عين
`OPENCLAW_RUN_NODE_CPU_PROF_DIR`:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status
```

يضيف مشغل المصدر أعلام ملف تعريف CPU في Node ويكتب ملف `.cpuprofile` للأمر.
استخدم هذا قبل إضافة أدوات قياس مؤقتة إلى كود الأمر.

لتوقفات بدء التشغيل التي تبدو كعمل نظام ملفات متزامن أو محمل وحدات،
أضف علم تتبع الإدخال/الإخراج المتزامن في Node عبر مشغل المصدر:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force
```

يترك `pnpm gateway:watch` هذا العلم معطلا افتراضيا لعملية Gateway الفرعية المراقبة.
عين `OPENCLAW_TRACE_SYNC_IO=1` عندما تريد صراحة مخرجات تتبع الإدخال/الإخراج المتزامن في Node
في وضع المراقبة.

## وضع مراقبة Gateway

للتكرار السريع، شغل Gateway تحت مراقب الملفات:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch
```

افتراضيا، يبدأ هذا أو يعيد تشغيل جلسة tmux باسم
`openclaw-gateway-watch-main` (أو صيغة خاصة بملف/منفذ مثل
`openclaw-gateway-watch-dev-19001`) ويرفقها تلقائيا من الطرفيات التفاعلية.
تبقى الصدف غير التفاعلية وCI واستدعاءات تنفيذ الوكيل منفصلة وتطبع
تعليمات الإرفاق بدلا من ذلك. أرفق يدويا عند الحاجة:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
tmux attach -t openclaw-gateway-watch-main
```

يشغل جزء tmux المراقب الخام:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
node scripts/watch-node.mjs gateway --force
```

استخدم وضع المقدمة عندما لا يكون tmux مطلوبا:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch:raw
# or
OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
```

عطل الإرفاق التلقائي مع إبقاء إدارة tmux:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
```

قس وقت CPU الخاص ب Gateway المراقب عند تصحيح النقاط الساخنة في بدء التشغيل/وقت التشغيل:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch --benchmark
```

يستهلك غلاف المراقبة `--benchmark` قبل استدعاء Gateway ويكتب
ملف V8 `.cpuprofile` واحدا لكل خروج لعملية Gateway فرعية تحت
`.artifacts/gateway-watch-profiles/`. أوقف أو أعد تشغيل Gateway المراقب
لتفريغ الملف الشخصي الحالي، ثم افتحه باستخدام Chrome DevTools أو Speedscope:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
```

استخدم `--benchmark-dir <path>` عندما تريد الملفات الشخصية في مكان آخر.
استخدم `--benchmark-no-force` عندما تريد من العملية الفرعية المقاسة تخطي
تنظيف المنفذ الافتراضي `--force` والفشل بسرعة إذا كان منفذ Gateway مستخدما بالفعل.
يخمد وضع القياس ضجيج تتبع الإدخال/الإخراج المتزامن افتراضيا. عين
`OPENCLAW_TRACE_SYNC_IO=1` مع `--benchmark` عندما تريد صراحة كلا من
ملفات CPU الشخصية وتتبع مكدسات الإدخال/الإخراج المتزامن في Node. في وضع القياس، تكتب كتل التتبع تلك
إلى `gateway-watch-output.log` تحت دليل القياس وتصفى من جزء الطرفية؛ تبقى سجلات Gateway العادية مرئية.

ينقل غلاف tmux محددات وقت التشغيل الشائعة غير السرية مثل
`OPENCLAW_PROFILE`، و`OPENCLAW_CONFIG_PATH`، و`OPENCLAW_STATE_DIR`،
و`OPENCLAW_GATEWAY_PORT`، و`OPENCLAW_SKIP_CHANNELS` إلى الجزء. ضع
بيانات اعتماد المزود في ملفك/إعداداتك العادية، أو استخدم وضع المقدمة الخام
للأسرار المؤقتة لمرة واحدة.
إذا خرج Gateway المراقب أثناء بدء التشغيل، يشغل المراقب
`openclaw doctor --fix --non-interactive` مرة واحدة ويعيد تشغيل عملية Gateway الفرعية.
استخدم `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0` عندما تريد فشل بدء التشغيل الأصلي
دون تمريرة الإصلاح الخاصة بالتطوير فقط.
يفترض جزء tmux المدار أيضا سجلات Gateway ملونة لتحسين القراءة؛
عين `FORCE_COLOR=0` عند بدء `pnpm gateway:watch` لتعطيل مخرجات ANSI.

يعيد المراقب التشغيل عند تغير الملفات ذات الصلة بالبناء تحت `src/`، وملفات مصدر الإضافة،
وبيانات `package.json` و`openclaw.plugin.json` الوصفية للإضافة، و`tsconfig.json`،
و`package.json`، و`tsdown.config.ts`. تعيد تغييرات بيانات الإضافة الوصفية تشغيل
Gateway دون فرض إعادة بناء `tsdown`؛ ما زالت تغييرات المصدر والإعدادات
تعيد بناء `dist` أولا.

أضف أي أعلام CLI خاصة ب Gateway بعد `gateway:watch` وستمرر عبره في
كل إعادة تشغيل. إعادة تشغيل أمر المراقبة نفسه تعيد إنشاء جزء tmux المسمى، وما زال
المراقب الخام يحتفظ بقفل مراقب واحد بحيث تستبدل عمليات المراقبة الأصلية المكررة
بدلا من تراكمها.

## ملف التطوير + Gateway التطوير (`--dev`)

استخدم ملف التطوير لعزل الحالة وتشغيل إعداد آمن وقابل للتخلص منه
للتصحيح. توجد علامتا `--dev` **اثنتان**:

* **`--dev` العام (الملف):** يعزل الحالة تحت `~/.openclaw-dev` ويجعل
  منفذ Gateway الافتراضي `19001` (وتتحرك المنافذ المشتقة معه).
* **`gateway --dev`: يخبر Gateway بإنشاء إعداد افتراضي +
  مساحة عمل تلقائيا** عند غيابهما (وتخطي BOOTSTRAP.md).

التدفق الموصى به (ملف التطوير + تمهيد التطوير):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui
```

إذا لم يكن لديك تثبيت عام بعد، شغل CLI عبر `pnpm openclaw ...`.

ما يفعله هذا:

1. **عزل الملف** (`--dev` العام)
   * `OPENCLAW_PROFILE=dev`
   * `OPENCLAW_STATE_DIR=~/.openclaw-dev`
   * `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
   * `OPENCLAW_GATEWAY_PORT=19001` (يتحرك المتصفح/اللوحة وفقا لذلك)

2. **تمهيد التطوير** (`gateway --dev`)
   * يكتب إعدادا بسيطا إذا كان مفقودا (`gateway.mode=local`، ربط loopback).
   * يعين `agent.workspace` إلى مساحة عمل التطوير.
   * يعين `agent.skipBootstrap=true` (لا يوجد BOOTSTRAP.md).
   * يزرع ملفات مساحة العمل إذا كانت مفقودة:
     `AGENTS.md`، و`SOUL.md`، و`TOOLS.md`، و`IDENTITY.md`، و`USER.md`، و`HEARTBEAT.md`.
   * الهوية الافتراضية: **C3-PO** (روبوت بروتوكول).
   * يتخطى مزودي القنوات في وضع التطوير (`OPENCLAW_SKIP_CHANNELS=1`).

تدفق إعادة الضبط (بدء جديد):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:dev:reset
```

<Note>
  `--dev` هو علم ملف **عام** وتبتلعه بعض المشغلات. إذا احتجت إلى كتابته صراحة، فاستخدم صيغة متغير البيئة:

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
  ```
</Note>

يمسح `--reset` الإعدادات وبيانات الاعتماد والجلسات ومساحة عمل التطوير (باستخدام
`trash`، وليس `rm`)، ثم يعيد إنشاء إعداد التطوير الافتراضي.

<Tip>
  إذا كان Gateway غير تطويري يعمل بالفعل (launchd أو systemd)، فأوقفه أولا:

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  openclaw gateway stop
  ```
</Tip>

## تسجيل البث الخام (OpenClaw)

يمكن ل OpenClaw تسجيل **تيار المساعد الخام** قبل أي ترشيح/تنسيق.
هذه أفضل طريقة لمعرفة ما إذا كان الاستدلال يصل كفروق نصية صرفة
(أو ككتل تفكير منفصلة).

فعله عبر CLI:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch --raw-stream
```

تجاوز مسار اختياري:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
```

متغيرات بيئة مكافئة:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
```

الملف الافتراضي:

`~/.openclaw/logs/raw-stream.jsonl`

## تسجيل أجزاء OpenAI المتوافقة الخام

لالتقاط **أجزاء OpenAI المتوافقة الخام** قبل تحليلها إلى كتل،
فعل مسجل النقل:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_RAW_STREAM=1
```

مسار اختياري:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-openai-completions.jsonl
```

الملف الافتراضي:

`~/.openclaw/logs/raw-openai-completions.jsonl`

## ملاحظات السلامة

* يمكن أن تتضمن سجلات البث الخام المطالبات الكاملة، ومخرجات الأدوات، وبيانات المستخدم.
* أبق السجلات محلية واحذفها بعد التصحيح.
* إذا شاركت السجلات، فأزل الأسرار ومعلومات التعريف الشخصية أولا.

## التصحيح في VSCode

خرائط المصدر مطلوبة لتمكين التصحيح في بيئات IDE المستندة إلى VSCode لأن كثيرا من الملفات المولدة ينتهي بها الأمر بأسماء مجزأة كجزء من عملية البناء. تستهدف إعدادات `launch.json` المضمنة خدمة Gateway، لكنها قابلة للتكييف بسرعة لأغراض أخرى:

1. **إعادة بناء وتصحيح Gateway** - يصحح خدمة Gateway بعد إنشاء بناء جديد
2. **تصحيح Gateway** - يصحح خدمة Gateway من بناء موجود مسبقا

### الإعداد

إعداد **إعادة بناء وتصحيح Gateway** الافتراضي مكتمل التجهيز، وسيحذف مجلد `/dist` تلقائيا ويعيد بناء المشروع مع تمكين التصحيح:

1. افتح لوحة **تشغيل وتصحيح** من شريط النشاط أو اضغط `Ctrl`+`Shift`+`D`
2. في IDE، تأكد من تحديد **إعادة بناء وتصحيح Gateway** في قائمة الإعدادات المنسدلة ثم اضغط زر **بدء التصحيح**

بدلا من ذلك - إذا كنت تفضل إدارة عمليتي البناء والتصحيح يدويا:

1. افتح طرفية وفعل خرائط المصدر:
   * **Linux/macOS**: `export OUTPUT_SOURCE_MAPS=1`
   * **Windows (PowerShell)**: `$env:OUTPUT_SOURCE_MAPS="1"`
   * **Windows (CMD)**: `set OUTPUT_SOURCE_MAPS=1`
2. في الطرفية نفسها، أعد بناء المشروع: `pnpm clean:dist && pnpm build`
3. في IDE، حدد خيار **تصحيح Gateway** في قائمة إعدادات **تشغيل وتصحيح** المنسدلة ثم اضغط زر **بدء التصحيح**

يمكنك الآن تعيين نقاط توقف في ملفات مصدر TypeScript الخاصة بك (دليل `src/`) وسيقوم المصحح بربط نقاط التوقف بشكل صحيح ب JavaScript المترجم عبر خرائط المصدر. ستتمكن من فحص المتغيرات، والتنقل خطوة بخطوة في الكود، وفحص مكدسات الاستدعاء كما هو متوقع.

### ملاحظات

* عند استخدام خيار **"إعادة بناء وتصحيح Gateway"** - في كل مرة يطلق فيها المصحح سيحذف مجلد `/dist` بالكامل ويشغل `pnpm build` كاملا مع تمكين خرائط المصدر قبل بدء Gateway
* عند استخدام خيار **"تصحيح Gateway"** - يمكن بدء جلسات التصحيح وإيقافها في أي وقت دون التأثير على مجلد `/dist`، لكن يجب استخدام عملية طرفية منفصلة لكل من تمكين التصحيح وإدارة دورة البناء
* عدل إعدادات `launch.json` الخاصة ب `args` لتصحيح أقسام أخرى من المشروع
* إذا احتجت إلى استخدام OpenClaw CLI المبني لمهام أخرى (مثل `dashboard --no-open` إذا أنشأت جلسة التصحيح رمز مصادقة جديدا)، فيمكنك تنفيذه في طرفية أخرى ك `node ./openclaw.mjs` أو إنشاء اسم مستعار للصدفة مثل `alias openclaw-build="node $(pwd)/openclaw.mjs"`

## ذو صلة

* [استكشاف الأخطاء وإصلاحها](/ar/help/troubleshooting)
* [الأسئلة الشائعة](/ar/help/faq)