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

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

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

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

أمثلة:

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

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

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

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

أمثلة:

/trace/trace on/trace off

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

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

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

مثال:

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

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

[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 وقياس أداء الأوامر

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

pnpm test:startup:bench:smokepnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

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

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

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

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

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

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

وضع مراقبة Gateway

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

pnpm gateway:watch

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

tmux attach -t openclaw-gateway-watch-main

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

node scripts/watch-node.mjs gateway --force

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

pnpm gateway:watch:raw# orOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

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

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

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

pnpm gateway:watch --benchmark

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

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).

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

pnpm gateway:devOPENCLAW_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).

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

pnpm gateway:dev:reset

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

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

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

فعله عبر CLI:

pnpm gateway:watch --raw-stream

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

pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl

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

OPENCLAW_RAW_STREAM=1OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

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

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

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

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

OPENCLAW_RAW_STREAM=1

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

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"

ذو صلة

• استكشاف الأخطاء وإصلاحها
• الأسئلة الشائعة