التصحيح 🐞

أدوات وتقنيات لتصحيح مشاكل OpenClaw.

مستويات السجل

تكوين مستوى السجل

# في .env
LOG_LEVEL=debug  # debug, info, warn, error

# أو عبر CLI
openclaw gateway --log-level debug

# أو في openclaw.json
{
  "logging": {
    "level": "debug"
  }
}

عرض السجلات

سجلات Gateway

# عرض آخر 50 سطراً
openclaw logs --tail 50

# متابعة السجلات المباشرة
openclaw logs --follow

# تصفية حسب المستوى
openclaw logs --level error

# تصفية حسب الوحدة
openclaw logs --module gateway
openclaw logs --module whatsapp

سجلات القنوات

# سجلات قناة معينة
openclaw channels logs whatsapp
openclaw channels logs telegram

# مع متابعة مباشرة
openclaw channels logs whatsapp --follow

ملفات السجل

تُحفظ السجلات في:

• macOS/Linux: /tmp/openclaw/gateway.log
• Windows: %TEMP%\openclaw\gateway.log

# عرض ملف السجل مباشرة
tail -f /tmp/openclaw/gateway.log

# البحث في السجلات
grep "ERROR" /tmp/openclaw/gateway.log

# عرض آخر 100 سطر
tail -n 100 /tmp/openclaw/gateway.log

وضع التطوير

تشغيل Gateway في وضع التطوير

# من المستودع
cd openclaw
pnpm install
pnpm gateway:watch  # إعادة التحميل التلقائي

# مع تصحيح إضافي
DEBUG=* pnpm gateway:watch

# أو استخدم Node inspector
node --inspect openclaw.mjs gateway

استخدام Node Debugger

# بدء مع debugger
node --inspect-brk openclaw.mjs gateway

# ثم افتح في Chrome:
# chrome://inspect

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Gateway",
      "program": "${workspaceFolder}/openclaw.mjs",
      "args": ["gateway", "--verbose"],
      "console": "integratedTerminal"
    }
  ]
}

تشخيص المشاكل

Gateway لا يبدأ

# تحقق من المنافذ
lsof -i :18789  # macOS/Linux
netstat -ano | findstr :18789  # Windows

# تحقق من الصلاحيات
ls -la ~/.openclaw/

# تحقق من التكوين
openclaw doctor

# تحقق من إصدار Node
node --version  # يجب أن يكون >= 22

القناة لا تتصل

# تحقق من حالة القناة
openclaw channels status

# تحقق من السجلات
openclaw channels logs whatsapp

# اختبر الاتصال
openclaw channels test whatsapp

# أعد تسجيل الدخول
openclaw channels logout whatsapp
openclaw channels login whatsapp

Agent لا يستجيب

# تحقق من مفاتيح API
openclaw models scan

# تحقق من الجلسات
openclaw sessions list

# اختبر Agent مباشرة
openclaw agent "مرحباً"

# تحقق من السياق
ls -la ~/.openclaw/workspace/

مراقبة الأداء

استخدام الذاكرة

# عرض استخدام الذاكرة
node --expose-gc openclaw.mjs gateway

# في كود Node.js
console.log(process.memoryUsage());

# مراقبة بـ htop/top
htop

استخدام CPU

# Profile CPU
node --prof openclaw.mjs gateway
# اترك يعمل ثم Ctrl+C
node --prof-process isolate-*.log > processed.txt

# باستخدام clinic.js
npm install -g clinic
clinic doctor -- node openclaw.mjs gateway

تتبع الأخطاء

تفعيل Stack Traces مفصلة

# في .env
NODE_OPTIONS="--trace-warnings --trace-deprecation"

# عرض async stack traces
NODE_OPTIONS="--async-stack-traces"

التقاط الأخطاء غير المُعالجة

# في الكود
process.on('unhandledRejection', (reason, promise) => {
  console.error('Unhandled Rejection:', reason);
});

process.on('uncaughtException', (error) => {
  console.error('Uncaught Exception:', error);
  process.exit(1);
});

أدوات التصحيح المتقدمة

Network Debugging

# تتبع HTTP requests
DEBUG=axios openclaw gateway

# استخدم mitmproxy لتحليل traffic
mitmproxy --port 8080
# ثم قم بتكوين HTTP_PROXY=http://localhost:8080

Database Debugging

# عرض بيانات الجلسة
cat ~/.openclaw/agents/main/sessions/*/session.json | jq .

# تحليل حجم الجلسات
du -sh ~/.openclaw/agents/main/sessions/*

قائمة التحقق من التصحيح