التسجيل

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

• سجلات الملفات (أسطر JSON) التي يكتبها Gateway.
• مخرجات وحدة التحكم في الطرفية التي تشغّل Gateway.

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

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

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

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

يستخدم التاريخ المنطقة الزمنية المحلية لمضيف Gateway. عندما يكون /tmp/openclaw غير آمن أو غير متاح (ودائمًا على Windows)، يستخدم OpenClaw بدلًا منه دليلًا خاصًا بالمستخدم باسم openclaw-<uid> ضمن دليل الملفات المؤقتة لنظام التشغيل. تُحذف ملفات السجل المؤرخة بعد 24 ساعة.

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

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

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

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

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

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

openclaw logs --follow

الخيارات:

أوضاع الإخراج:

• جلسات TTY: أسطر سجل منظمة ومنسقة وملونة.
• الجلسات غير التابعة لـ TTY: نص عادي.

عند تمرير --url صراحةً، لا يطبّق CLI تلقائيًا بيانات الاعتماد من الإعدادات أو البيئة؛ أدرج --token بنفسك، وإلا تفشل الاستدعاء بالرسالة gateway url override requires explicit credentials.

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

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

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

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

openclaw doctor

واجهة التحكم (الويب)

تعرض علامة التبويب السجلات في واجهة التحكم الملف نفسه بشكل متواصل باستخدام logs.tail. راجع واجهة التحكم لمعرفة كيفية فتحها.

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

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

openclaw channels logs --channel whatsapp

القيمة الافتراضية لـ --channel هي all؛ ويتوفر أيضًا --lines <n> (الافتراضي 200) و--json.

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

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

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

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

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

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

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

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

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

• بادئات الأنظمة الفرعية (مثل gateway/channels/whatsapp)
• تلوين المستويات (معلومات/تحذير/خطأ)
• وضع مضغوط أو JSON اختياري

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

سجلات WebSocket في Gateway

يتضمن 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-.*"]  }}

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

المستويات: silent، وfatal، وerror، وwarn، وinfo، وdebug، وtrace.

• logging.level: مستوى سجلات الملفات (JSONL) (الافتراضي: info).
• 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: إصدار بداية الطلب واستجابة الجلب وترويسات 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 وعلامة تبويب السجلات في واجهة التحكم. من دون العلامات، تظل التشخيصات نفسها متاحة عند مستوى debug.

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

ربط التتبعات

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

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

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

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

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

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

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

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

logging.consoleStyle:

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

التنقيح

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

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

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

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

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

التشخيص وOpenTelemetry

التشخيصات هي أحداث منظّمة قابلة للقراءة آليًا لعمليات تشغيل النموذج وبيانات القياس عن بُعد لتدفق الرسائل (Webhooks، والإدراج في قوائم الانتظار، وحالة الجلسة). وهي لا تحل محل السجلات، بل تغذي المقاييس والتتبعات وأدوات التصدير. تُصدَر الأحداث افتراضيًا داخل العملية (اضبط diagnostics.enabled: false لإيقافها)، أما تصديرها فهو أمر منفصل.

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

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

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

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

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

ذو صلة

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