التسجيل

للحصول على نظرة عامة موجّهة للمستخدم (CLI + واجهة التحكم + الإعدادات)، راجع /logging.

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

• مخرجات وحدة التحكم - ما تراه في الطرفية / واجهة التصحيح.
• سجلات الملفات - أسطر JSON يكتبها مسجّل Gateway.

عند بدء التشغيل، يسجّل Gateway نموذج الوكيل الافتراضي الذي جرى تحديده، بالإضافة إلى الإعدادات الافتراضية للأوضاع التي تؤثر في الجلسات الجديدة:

agent model: openai/gpt-5.6-sol (thinking=medium, fast=on)

تأتي قيمة thinking من الوكيل الافتراضي أو معلمات النموذج أو الإعداد الافتراضي العام للوكيل؛ وعندما لا تكون معيّنة، تظهر القيمة medium. تأتي قيمة fast من الوكيل الافتراضي أو معلمات fastMode الخاصة بالنموذج.

المسجّل المستند إلى الملفات

• يوجد ملف السجل المتجدد الافتراضي ضمن /tmp/openclaw/ (ملف واحد يوميًا): openclaw-YYYY-MM-DD.log، ويؤرَّخ وفق المنطقة الزمنية المحلية لمضيف Gateway. إذا كان ذلك الدليل غير آمن أو غير قابل للكتابة (مالك غير صحيح، قابل للكتابة من الجميع، أو رابط رمزي)، يعود OpenClaw بدلًا من ذلك إلى المسار os.tmpdir()/openclaw-<uid> المقيّد بنطاق المستخدم؛ وفي Windows يستخدم دائمًا هذا المسار البديل ضمن دليل نظام التشغيل المؤقت.
• تتناوب ملفات السجل النشطة عند بلوغ logging.maxFileBytes (القيمة الافتراضية: 100 ميغابايت)، مع الاحتفاظ بما يصل إلى خمسة أرشيفات مرقّمة (من .1 إلى .5) ومتابعة الكتابة في ملف نشط جديد.
• اضبط مسار ملف السجل ومستواه عبر ~/.openclaw/openclaw.json:‏ logging.file وlogging.level.
• يتكوّن تنسيق الملف من كائن JSON واحد في كل سطر.

تستخدم مسارات الشيفرة الخاصة بالمحادثة والصوت الفوري والغرف المُدارة مسجّل الملفات المشترك لتسجيل سجلات دورة حياة محدودة مخصّصة للتصحيح التشغيلي وتصدير سجلات OTLP. لا يُنسخ مطلقًا نص النسخة المكتوبة أو حمولات الصوت أو معرّفات الأدوار أو معرّفات المكالمات أو معرّفات عناصر المزوّد إلى سجل التسجيل.

تتابع علامة تبويب السجلات في واجهة التحكم هذا الملف عبر Gateway (logs.tail). ويفعل CLI الشيء نفسه:

openclaw logs --follow

الوضع المفصّل مقابل مستويات السجل

• تتحكم logging.level حصريًا في سجلات الملفات.
• لا يؤثر --verbose إلا في مستوى تفصيل وحدة التحكم (ونمط سجل WS) - وهو لا يرفع مستوى سجل الملفات.
• لالتقاط التفاصيل التي لا تظهر إلا في الوضع المفصّل ضمن سجلات الملفات، اضبط logging.level على debug أو trace.
• يتضمن تسجيل التتبّع أيضًا ملخصات توقيت تشخيصية لمسارات ساخنة محددة، مثل تجهيز مصنع أدوات Plugin. راجع /tools/plugin#slow-plugin-tool-setup.

التقاط وحدة التحكم

يلتقط CLI الاستدعاءات console.log/info/warn/error/debug/trace، ويكتبها في سجلات الملفات، مع الاستمرار في طباعتها إلى stdout/stderr.

اضبط مستوى تفصيل وحدة التحكم بشكل مستقل:

• logging.consoleLevel (القيمة الافتراضية info)
• logging.consoleStyle ‏(pretty | compact | json؛ القيمة الافتراضية pretty على TTY، وcompact في الحالات الأخرى)

التنقيح

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

• logging.redactSensitive:‏ off | tools (القيمة الافتراضية: tools)
• logging.redactPatterns: مصفوفة من سلاسل التعبيرات النمطية (تتجاوز الإعدادات الافتراضية)
  • استخدم سلاسل تعبيرات نمطية خام (تُضاف gi تلقائيًا)، أو /pattern/flags لاستخدام علامات مخصّصة.
  • تُحجب التطابقات مع الإبقاء على أول 6 وآخر 4 محارف (للقيم التي يبلغ طولها 18 محرفًا أو أكثر)؛ وتصبح القيم الأقصر ***.
  • تغطي الإعدادات الافتراضية إسنادات المفاتيح الشائعة، وعلامات CLI، وحقول JSON، وترويسات الحامل، وكتل PEM، وبادئات رموز المورّدين الشائعة، وأسماء حقول بيانات اعتماد الدفع (رقم البطاقة، وCVC/CVV، ورمز الدفع المشترك، وبيانات اعتماد الدفع).

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

سجلات WebSocket الخاصة بـ Gateway

يطبع Gateway سجلات بروتوكول WebSocket في وضعين:

• الوضع العادي (من دون --verbose): لا تُطبع إلا نتائج RPC «المهمة» - الأخطاء (ok=false)، والاستدعاءات البطيئة (العتبة الافتراضية: >= 50ms)، وأخطاء التحليل.
• الوضع المفصّل (--verbose): يطبع كل حركة طلبات واستجابات WS.

نمط سجل WS

يدعم openclaw gateway تبديل النمط لكل Gateway:

• --ws-log auto (الافتراضي): يكون الوضع العادي محسّنًا؛ ويستخدم الوضع المفصّل مخرجات مضغوطة.
• --ws-log compact: مخرجات مضغوطة (طلب/استجابة مقترنان) في الوضع المفصّل.
• --ws-log full: مخرجات كاملة لكل إطار في الوضع المفصّل.
• --compact: اسم بديل لـ--ws-log compact.

# محسّن (الأخطاء/العمليات البطيئة فقط)openclaw gateway # عرض كل حركة WS (مقترنة)openclaw gateway --verbose --ws-log compact # عرض كل حركة WS (بيانات وصفية كاملة)openclaw gateway --verbose --ws-log full

تنسيق وحدة التحكم (تسجيل الأنظمة الفرعية)

يكون منسّق وحدة التحكم مدركًا لـTTY ويطبع أسطرًا متسقة ذات بادئات. تحافظ مسجّلات الأنظمة الفرعية على تجميع المخرجات وسهولة فحصها:

• بادئات الأنظمة الفرعية في كل سطر (مثل [gateway] و[canvas] و[tailscale]).
• ألوان الأنظمة الفرعية (ثابتة لكل نظام فرعي ومشتقة بالتجزئة من الاسم)، بالإضافة إلى تلوين المستوى.
• استخدام الألوان عندما تكون المخرجات TTY أو تبدو البيئة كطرفية غنية (TERM/COLORTERM/TERM_PROGRAM)؛ مع احترام NO_COLOR وFORCE_COLOR.
• بادئات مختصرة للأنظمة الفرعية: تُسقط المقطع الابتدائي gateway/ أو channels/ أو providers/، ثم تحتفظ بآخر مقطعين متبقيين على الأكثر (مثلًا، يُعرض channels/turn/kernel على هيئة turn/kernel). وتُختصر الأنظمة الفرعية للقنوات المعروفة (telegram وwhatsapp وslack وغيرها) دائمًا إلى اسم القناة فقط.
• مسجّلات فرعية حسب النظام الفرعي (بادئة تلقائية + حقل منظّم { subsystem }).
• logRaw() لمخرجات QR/تجربة المستخدم (بلا بادئة أو تنسيق).
• أنماط وحدة التحكم: pretty | compact | json.
• مستوى سجل وحدة التحكم منفصل عن مستوى سجل الملفات (يحتفظ الملف بالتفاصيل الكاملة عندما تكون logging.level بالقيمة debug أو trace).
• تُسجّل نصوص رسائل WhatsApp عند المستوى debug (استخدم --verbose لرؤيتها).

يحافظ هذا على استقرار سجلات الملفات مع جعل المخرجات التفاعلية سهلة الفحص.

ذو صلة

• التسجيل
• تصدير OpenTelemetry
• تصدير بيانات التشخيص