​

التسجيل

• سجلات الملفات ‏(أسطر JSON) التي يكتبها Gateway.
• مخرجات Console المعروضة في الطرفيات وواجهة Debug UI الخاصة بـ Gateway.

​

مكان وجود السجلات

{
  "logging": {
    "file": "/path/to/openclaw.log"
  }
}

​

كيفية قراءة السجلات

​

CLI: تتبع مباشر (موصى به)

openclaw logs --follow

• --local-time: عرض الطوابع الزمنية بمنطقتك الزمنية المحلية
• --url <url> / --token <token> / --timeout <ms>: أعلام Gateway RPC القياسية
• --expect-final: علم انتظار الاستجابة النهائية لـ RPC المدعومة بالوكيل (مقبول هنا عبر طبقة العميل المشتركة)

• جلسات TTY: أسطر سجل منظمة وجميلة وملونة.
• جلسات غير TTY: نص عادي.
• --json: JSON مفصول بأسطر (حدث سجل واحد في كل سطر).
• --plain: فرض النص العادي في جلسات TTY.
• --no-color: تعطيل ألوان ANSI.

• meta: بيانات وصفية للبث (الملف، والمؤشر، والحجم)
• log: إدخال سجل محلل
• notice: تلميحات حول الاقتطاع / التدوير
• raw: سطر سجل غير محلل

openclaw doctor

​

Control UI ‏(الويب)

​

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

openclaw channels logs --channel whatsapp

​

تنسيقات السجل

​

سجلات الملفات (JSONL)

​

مخرجات Console

• بادئات الأنظمة الفرعية (مثل gateway/channels/whatsapp)
• تلوين المستويات (info/warn/error)
• وضع compact أو JSON اختياري

​

سجلات Gateway WebSocket

• الوضع العادي: النتائج المهمة فقط (الأخطاء، وأخطاء التحليل، والاستدعاءات البطيئة)
• --verbose: كل حركة الطلب/الاستجابة
• --ws-log auto|compact|full: اختيار نمط العرض المفصل
• --compact: اسم بديل لـ --ws-log compact

openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full

​

تهيئة التسجيل

{
  "logging": {
    "level": "info",
    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

​

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

• logging.level: مستوى سجلات الملفات ‏(JSONL).
• logging.consoleLevel: مستوى تفاصيل Console.

​

أنماط Console

• pretty: مناسب للبشر، وملون، مع طوابع زمنية.
• compact: خرج أكثر إحكامًا (أفضل للجلسات الطويلة).
• json: JSON في كل سطر (لمعالجات السجل).

​

التنقيح

• logging.redactSensitive: ‏off | tools ‏(الافتراضي: tools)
• logging.redactPatterns: قائمة سلاسل regex لتجاوز المجموعة الافتراضية

​

التشخيصات + OpenTelemetry

​

OpenTelemetry مقابل OTLP

• OpenTelemetry (OTel): نموذج البيانات + SDKs الخاصة بـ traces والمقاييس والسجلات.
• OTLP: بروتوكول النقل المستخدم لتصدير بيانات OTel إلى جامع/خلفية.
• يقوم OpenClaw بالتصدير عبر OTLP/HTTP (protobuf) حاليًا.

​

الإشارات المصدّرة

• المقاييس: عدادات + مدرجات تكرارية (استخدام الرموز، وتدفق الرسائل، والطوابير).
• Traces: spans لاستخدام النماذج + معالجة webhooks/الرسائل.
• السجلات: يتم تصديرها عبر OTLP عند تمكين diagnostics.otel.logs. وقد يكون حجم السجل كبيرًا؛ لذا ضع logging.level ومرشحات المصدّر في الحسبان.

​

فهرس أحداث التشخيص

• model.usage: الرموز، والتكلفة، والمدة، والسياق، والمزوّد/النموذج/القناة، ومعرّفات الجلسات.

• webhook.received: دخول webhook لكل قناة.
• webhook.processed: معالجة webhook + المدة.
• webhook.error: أخطاء معالج webhook.
• message.queued: إدراج رسالة في الطابور للمعالجة.
• message.processed: النتيجة + المدة + خطأ اختياري.

• queue.lane.enqueue: إدراج مسار طابور الأوامر + العمق.
• queue.lane.dequeue: سحب مسار طابور الأوامر + وقت الانتظار.
• session.state: انتقال حالة الجلسة + السبب.
• session.stuck: تحذير تعثر الجلسة + العمر.
• run.attempt: بيانات وصفية لمحاولة/إعادة محاولة التشغيل.
• diagnostic.heartbeat: عدادات مجمعة (webhooks/الطابور/الجلسة).

​

تمكين التشخيصات (بدون مصدّر)

{
  "diagnostics": {
    "enabled": true
  }
}

​

أعلام التشخيص (سجلات مستهدفة)

{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

• تذهب سجلات الأعلام إلى ملف السجل القياسي (نفس logging.file).
• يبقى الخرج منقحًا وفقًا لـ logging.redactSensitive.
• الدليل الكامل: /diagnostics/flags.

​

التصدير إلى OpenTelemetry

{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "protocol": "http/protobuf",
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}

• يمكنك أيضًا تمكين plugin باستخدام openclaw plugins enable diagnostics-otel.
• يدعم protocol حاليًا فقط http/protobuf. ويتم تجاهل grpc.
• تتضمن المقاييس استخدام الرموز، والتكلفة، وحجم السياق، ومدة التشغيل، وعدادات/مدرجات تدفق الرسائل (webhooks، والطوابير، وحالة الجلسة، وعمق الطابور/الانتظار).
• يمكن تبديل traces/metrics عبر traces / metrics ‏(الافتراضي: مفعّلة). وتتضمن traces spans استخدام النموذج بالإضافة إلى spans معالجة webhooks/الرسائل عند التمكين.
• اضبط headers عندما يتطلب جامعك المصادقة.
• متغيرات البيئة المدعومة: OTEL_EXPORTER_OTLP_ENDPOINT، وOTEL_SERVICE_NAME، وOTEL_EXPORTER_OTLP_PROTOCOL.

​

المقاييس المصدّرة (الأسماء + الأنواع)

• openclaw.tokens ‏(عداد، سمات: openclaw.token وopenclaw.channel، وopenclaw.provider وopenclaw.model)
• openclaw.cost.usd ‏(عداد، سمات: openclaw.channel وopenclaw.provider، وopenclaw.model)
• openclaw.run.duration_ms ‏(مدرج تكراري، سمات: openclaw.channel، وopenclaw.provider وopenclaw.model)
• openclaw.context.tokens ‏(مدرج تكراري، سمات: openclaw.context، وopenclaw.channel وopenclaw.provider وopenclaw.model)

• openclaw.webhook.received ‏(عداد، سمات: openclaw.channel، وopenclaw.webhook)
• openclaw.webhook.error ‏(عداد، سمات: openclaw.channel، وopenclaw.webhook)
• openclaw.webhook.duration_ms ‏(مدرج تكراري، سمات: openclaw.channel، وopenclaw.webhook)
• openclaw.message.queued ‏(عداد، سمات: openclaw.channel، وopenclaw.source)
• openclaw.message.processed ‏(عداد، سمات: openclaw.channel، وopenclaw.outcome)
• openclaw.message.duration_ms ‏(مدرج تكراري، سمات: openclaw.channel، وopenclaw.outcome)

• openclaw.queue.lane.enqueue ‏(عداد، سمات: openclaw.lane)
• openclaw.queue.lane.dequeue ‏(عداد، سمات: openclaw.lane)
• openclaw.queue.depth ‏(مدرج تكراري، سمات: openclaw.lane أو openclaw.channel=heartbeat)
• openclaw.queue.wait_ms ‏(مدرج تكراري، سمات: openclaw.lane)
• openclaw.session.state ‏(عداد، سمات: openclaw.state وopenclaw.reason)
• openclaw.session.stuck ‏(عداد، سمات: openclaw.state)
• openclaw.session.stuck_age_ms ‏(مدرج تكراري، سمات: openclaw.state)
• openclaw.run.attempt ‏(عداد، سمات: openclaw.attempt)

​

spans المصدّرة (الأسماء + السمات الأساسية)

• openclaw.model.usage
  • openclaw.channel وopenclaw.provider وopenclaw.model
  • openclaw.sessionKey وopenclaw.sessionId
  • openclaw.tokens.* ‏(input/output/cache_read/cache_write/total)
• openclaw.webhook.processed
  • openclaw.channel وopenclaw.webhook وopenclaw.chatId
• openclaw.webhook.error
  • openclaw.channel وopenclaw.webhook وopenclaw.chatId، وopenclaw.error
• openclaw.message.processed
  • openclaw.channel وopenclaw.outcome وopenclaw.chatId، وopenclaw.messageId وopenclaw.sessionKey وopenclaw.sessionId، وopenclaw.reason
• openclaw.session.stuck
  • openclaw.state وopenclaw.ageMs وopenclaw.queueDepth، وopenclaw.sessionKey وopenclaw.sessionId

​

أخذ العينات والتفريغ

• أخذ عينات traces: ‏diagnostics.otel.sampleRate ‏(0.0–1.0، spans الجذر فقط).
• فاصل تصدير المقاييس: ‏diagnostics.otel.flushIntervalMs ‏(حد أدنى 1000ms).

​

ملاحظات البروتوكول

• يمكن ضبط نقاط نهاية OTLP/HTTP عبر diagnostics.otel.endpoint أو OTEL_EXPORTER_OTLP_ENDPOINT.
• إذا كانت نقطة النهاية تحتوي بالفعل على /v1/traces أو /v1/metrics، فسيتم استخدامها كما هي.
• إذا كانت نقطة النهاية تحتوي بالفعل على /v1/logs، فسيتم استخدامها كما هي للسجلات.
• يؤدي diagnostics.otel.logs إلى تمكين تصدير سجلات OTLP لمخرجات المُسجّل الرئيسي.

​

سلوك تصدير السجلات

• تستخدم سجلات OTLP السجلات المنظمة نفسها المكتوبة إلى logging.file.
• تحترم logging.level ‏(مستوى سجل الملف). ولا ينطبق تنقيح console على سجلات OTLP.
• يجب على عمليات التثبيت ذات الحجم الكبير تفضيل أخذ العينات/التصفية في جامع OTLP.

​

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

• تعذر الوصول إلى Gateway؟ شغّل openclaw doctor أولًا.
• السجلات فارغة؟ تحقّق من أن Gateway يعمل ويكتب إلى مسار الملف في logging.file.
• تحتاج إلى مزيد من التفاصيل؟ اضبط logging.level على debug أو trace ثم أعد المحاولة.

​

ذو صلة

• الآليات الداخلية لتسجيل Gateway — أنماط سجل WS، وبادئات الأنظمة الفرعية، والتقاط console
• التشخيصات — تصدير OpenTelemetry وإعدادات تتبع cache