تسجيل السجلات

يحتوي OpenClaw على سطحين رئيسيين للسجلات:

• سجلات الملفات (أسطر JSON) التي يكتبها Gateway.
• مخرجات وحدة التحكم المعروضة في الطرفيات وواجهة تصحيح أخطاء Gateway.

يتتبع تبويب Logs في واجهة Control UI سجل ملف Gateway. تشرح هذه الصفحة أين توجد السجلات، وكيفية قراءتها، وكيفية ضبط مستويات السجل وتنسيقاته.

أين توجد السجلات

افتراضيًا، يكتب Gateway ملف سجل متجددًا ضمن:

/tmp/openclaw/openclaw-YYYY-MM-DD.log

يستخدم التاريخ المنطقة الزمنية المحلية لمضيف Gateway.

يدور كل ملف عندما يصل إلى logging.maxFileBytes (الافتراضي: 100 ميغابايت). يحتفظ OpenClaw بما يصل إلى خمسة أرشيفات مرقمة بجانب الملف النشط، مثل openclaw-YYYY-MM-DD.1.log، ويواصل الكتابة إلى سجل نشط جديد بدلًا من كتم التشخيصات.

يمكنك تجاوز ذلك في ~/.openclaw/openclaw.json:

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

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

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

استخدم CLI لتتبع ملف سجل Gateway عبر RPC:

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.

عند تمرير --url صريح، لا يطبق CLI تلقائيًا بيانات اعتماد الإعدادات أو البيئة؛ أضف --token بنفسك إذا كان Gateway الهدف يتطلب المصادقة.

في وضع JSON، يصدر CLI كائنات موسومة بـ type:

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

إذا طلب Gateway الضمني عبر local loopback المحلي الاقتران، أو أغلق أثناء الاتصال، أو انتهت مهلته قبل أن يجيب logs.tail، يعود openclaw logs تلقائيًا إلى ملف سجل Gateway المضبوط. لا تستخدم أهداف --url الصريحة هذا الرجوع الاحتياطي. يكون openclaw logs --follow أكثر صرامة: على Linux يستخدم سجل Gateway النشط الخاص بـ user-systemd حسب PID عند توفره، وإلا يواصل إعادة محاولة Gateway المباشر بدلًا من تتبع ملف جانبي قديم محتملًا.

إذا تعذر الوصول إلى Gateway، يطبع CLI تلميحًا قصيرًا لتشغيل:

openclaw doctor

Control UI (الويب)

يتتبع تبويب Logs في Control UI الملف نفسه باستخدام logs.tail. راجع Control UI لمعرفة كيفية فتحه.

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

لتصفية نشاط القناة (WhatsApp/Telegram/إلخ)، استخدم:

openclaw channels logs --channel whatsapp

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

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

كل سطر في ملف السجل هو كائن JSON. يحلل CLI وControl UI هذه الإدخالات لعرض إخراج منظم (الوقت، المستوى، النظام الفرعي، الرسالة).

تتضمن سجلات JSONL الخاصة بالملفات أيضًا حقولًا علوية قابلة للتصفية آليًا عند توفرها:

• hostname: اسم مضيف Gateway.
• message: نص رسالة السجل المسطح للبحث النصي الكامل.
• agent_id: معرف الوكيل النشط عندما تحمل استدعاء السجل سياق وكيل.
• session_id: معرف/مفتاح الجلسة النشطة عندما تحمل استدعاء السجل سياق جلسة.
• channel: القناة النشطة عندما تحمل استدعاء السجل سياق قناة.

يحافظ OpenClaw على وسيطات السجل المنظمة الأصلية بجانب هذه الحقول حتى تستمر المحللات الحالية التي تقرأ مفاتيح وسيطات tslog المرقمة في العمل.

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

مخرجات وحدة التحكم

سجلات وحدة التحكم مدركة لـ TTY ومنسقة لتسهيل القراءة:

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

يتحكم logging.consoleStyle في تنسيق وحدة التحكم.

سجلات Gateway WebSocket

لدى openclaw gateway أيضًا تسجيل بروتوكول WebSocket لحركة RPC:

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

أمثلة:

openclaw gatewayopenclaw gateway --verbose --ws-log compactopenclaw gateway --verbose --ws-log full

ضبط التسجيل

توجد كل إعدادات التسجيل ضمن logging في ~/.openclaw/openclaw.json.

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

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

• logging.level: مستوى سجلات الملفات (JSONL).
• logging.consoleLevel: مستوى تفصيل وحدة التحكم.

يمكنك تجاوز كليهما عبر متغير البيئة OPENCLAW_LOG_LEVEL (مثل OPENCLAW_LOG_LEVEL=debug). يأخذ متغير البيئة أولوية على ملف الإعدادات، لذا يمكنك رفع مستوى التفصيل لتشغيل واحد دون تعديل openclaw.json. يمكنك أيضًا تمرير خيار CLI العام --log-level <level> (على سبيل المثال، openclaw --log-level debug gateway run)، والذي يتجاوز متغير البيئة لذلك الأمر.

يؤثر --verbose فقط في مخرجات وحدة التحكم وتفصيل سجل WS؛ ولا يغير مستويات سجل الملفات.

تشخيصات نقل النموذج المستهدفة

عند تصحيح استدعاءات المزود، استخدم أعلام البيئة المستهدفة بدلًا من رفع كل السجلات إلى debug:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gatewayOPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway

الأعلام المتاحة:

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1: إصدار بداية الطلب، واستجابة fetch، ورؤوس SDK، وأول حدث تدفق، واكتمال التدفق، وأخطاء النقل عند مستوى info.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: تضمين ملخص محدود لحمولة الطلب في سجلات طلب النموذج.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: تضمين كل أسماء الأدوات المواجهة للنموذج في ملخص الحمولة.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: تضمين لقطة حمولة JSON منقحة ومحدودة. استخدمه أثناء التصحيح فقط؛ يتم تنقيح الأسرار لكن قد تبقى المطالبات ونص الرسائل موجودة.
• OPENCLAW_DEBUG_SSE=events: إصدار توقيت أول حدث واكتمال التدفق.
• OPENCLAW_DEBUG_SSE=peek: إصدار أول خمس حمولات أحداث SSE منقحة أيضًا، مع حد لكل حدث.
• OPENCLAW_DEBUG_CODE_MODE=1: إصدار تشخيصات سطح النموذج في وضع الكود، بما في ذلك عندما تُخفى أدوات المزود الأصلية لأن وضع الكود يملك سطح الأدوات.

تسجل هذه الأعلام عبر تسجيل OpenClaw العادي، لذا يعرضها openclaw logs --follow وتبويب Logs في Control UI. بدون الأعلام، تبقى التشخيصات نفسها متاحة عند مستوى debug.

تُصدر بيانات تعريف بداية واستجابة [model-fetch] (المزود، API، النموذج، الحالة، زمن الاستجابة، وحقول الطلب مثل الطريقة، وURL، والمهلة، والوكيل، والسياسة) دائمًا عند مستوى info بغض النظر عن OPENCLAW_DEBUG_MODEL_TRANSPORT، لذا تكون أساسيات نظافة نقل النموذج مرئية دون أعلام التصحيح.

ربط التتبع

سجلات الملفات هي JSONL. عندما يحمل استدعاء سجل سياق تتبع تشخيصي صالحًا، يكتب OpenClaw حقول التتبع كمفاتيح JSON علوية (traceId، spanId، parentSpanId، traceFlags) حتى تتمكن معالجات السجلات الخارجية من ربط السطر مع امتدادات OTEL ونشر traceparent الخاص بالمزود.

تنشئ طلبات HTTP الخاصة بـ Gateway وإطارات Gateway WebSocket نطاق تتبع طلب داخليًا. ترث السجلات والأحداث التشخيصية الصادرة داخل ذلك النطاق غير المتزامن تتبع الطلب عندما لا تمرر سياق تتبع صريحًا. تصبح تتبعات تشغيل الوكيل واستدعاء النموذج أبناء لتتبع الطلب النشط، لذا يمكن ربط السجلات المحلية، واللقطات التشخيصية، وامتدادات OTEL، ورؤوس traceparent الموثوقة من المزود بواسطة traceId دون تسجيل الطلب الخام أو محتوى النموذج.

تتدفق سجلات دورة حياة الكلام أيضًا إلى تصدير سجلات diagnostics-otel عند تمكين تصدير سجلات OpenTelemetry، باستخدام السمات المحدودة نفسها كسجلات الملفات. اضبط diagnostics.otel.logsExporter لاختيار OTLP، أو stdout JSONL، أو كلا المصبين.

حجم استدعاء النموذج وتوقيته

تسجل تشخيصات استدعاء النموذج قياسات محدودة للطلب/الاستجابة دون التقاط محتوى المطالبة أو الاستجابة الخام:

• requestPayloadBytes: حجم حمولة طلب النموذج النهائية بالبايت وفق UTF-8
• responseStreamBytes: حجم حمولات أجزاء استجابة النموذج المتدفقة بالبايت وفق UTF-8. تُحتسب أحداث النص عالية التكرار، والتفكير، وفروق استدعاءات الأدوات ببايتات delta التزايدية فقط بدلًا من لقطات partial الكاملة.
• timeToFirstByteMs: الوقت المنقضي قبل أول حدث استجابة متدفق
• durationMs: المدة الإجمالية لاستدعاء النموذج

تتوفر هذه الحقول للقطات التشخيصية، وخطافات Plugin لاستدعاء النموذج، وامتدادات/مقاييس استدعاء النموذج في OTEL عند تمكين تصدير التشخيصات.

أنماط وحدة التحكم

logging.consoleStyle:

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

التنقيح

يمكن لـ OpenClaw تنقيح الرموز الحساسة قبل وصولها إلى مخرجات وحدة التحكم، أو سجلات الملفات، أو سجلات OTLP، أو نص نسخ الجلسة المستمر، أو حمولات أحداث أدوات Control UI (وسيطات بدء الأداة، وحمولات النتائج الجزئية/النهائية، ومخرجات exec المشتقة، وملخصات التصحيحات):

• logging.redactSensitive: off | tools (الافتراضي: tools)
• logging.redactPatterns: قائمة بسلاسل regex لتجاوز المجموعة الافتراضية. تطبق الأنماط المخصصة فوق الافتراضيات المدمجة لحمولات أدوات Control UI، لذا فإن إضافة نمط لا تضعف أبدًا تنقيح القيم التي تلتقطها الافتراضيات بالفعل.

تبقى سجلات الملفات ونصوص الجلسات JSONL، لكن تُخفى قيم الأسرار المطابقة قبل كتابة السطر أو الرسالة إلى القرص. التنقيح يبذل أفضل جهد: ينطبق على محتوى الرسائل الحاملة للنص وسلاسل السجل، وليس كل معرف أو حقل حمولة ثنائي.

تغطي الافتراضيات المدمجة بيانات اعتماد API الشائعة وأسماء حقول بيانات اعتماد الدفع مثل رقم البطاقة، وCVC/CVV، ورمز الدفع المشترك، وبيان اعتماد الدفع عندما تظهر كحقول JSON، أو معاملات URL، أو أعلام CLI، أو إسنادات.

يعطل logging.redactSensitive: "off" سياسة السجل/النسخ العامة هذه فقط. لا يزال OpenClaw ينقح حمولات حدود السلامة التي يمكن عرضها لعملاء UI، أو حزم الدعم، أو مراقبي التشخيصات، أو مطالبات الموافقة، أو أدوات الوكيل. تشمل الأمثلة أحداث استدعاء أدوات Control UI، ومخرجات sessions_history، وصادرات دعم التشخيصات، وملاحظات أخطاء المزود، وعرض أمر موافقة exec، وسجلات بروتوكول Gateway WebSocket. يمكن أن تضيف logging.redactPatterns المخصصة أنماطًا خاصة بالمشروع على تلك الأسطح.

التشخيصات وOpenTelemetry

التشخيصات هي أحداث منظمة قابلة للقراءة آليًا لتشغيلات النماذج و قياسات تدفق الرسائل (webhooks، والاصطفاف، وحالة الجلسة). وهي لا تستبدل السجلات — بل تغذي المقاييس، والتتبعات، والمصدرين. تُصدر الأحداث داخل العملية سواء صدّرتها أم لا.

سطحان متجاوران:

• تصدير OpenTelemetry — إرسال المقاييس، والتتبعات، والسجلات عبر OTLP/HTTP إلى أي جامع أو خلفية متوافقة مع OpenTelemetry (Grafana، وDatadog، وHoneycomb، وNew Relic، وTempo، إلخ). توجد الإعدادات الكاملة، وكتالوج الإشارات، وأسماء المقاييس/الامتدادات، ومتغيرات البيئة، ونموذج الخصوصية في صفحة مخصصة: تصدير OpenTelemetry.
• أعلام التشخيصات — أعلام سجل تصحيح مستهدفة توجه سجلات إضافية إلى logging.file دون رفع logging.level. لا تراعي الأعلام حالة الأحرف وتدعم أحرف البدل (telegram.*، *). اضبطها ضمن diagnostics.flags أو عبر تجاوز البيئة OPENCLAW_DIAGNOSTICS=.... الدليل الكامل: أعلام التشخيصات.

لتمكين أحداث التشخيصات لـ Plugin أو مصبات مخصصة دون تصدير OTLP:

{  diagnostics: { enabled: true },}

لتصدير OTLP إلى مجمّع، راجع تصدير OpenTelemetry.

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

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

ذات صلة

• تصدير OpenTelemetry — تصدير OTLP/HTTP، كتالوج المقاييس/النطاقات، نموذج الخصوصية
• أعلام التشخيص — أعلام سجلات تصحيح أخطاء موجّهة
• تفاصيل تسجيل Gateway الداخلية — أنماط سجلات WS، وبادئات الأنظمة الفرعية، والتقاط وحدة التحكم
• مرجع الإعدادات — مرجع كامل لحقول diagnostics.*