التسجيل

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

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

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

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

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

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

المسجّل المعتمد على الملفات

• يوجد ملف السجل المتجدد الافتراضي تحت /tmp/openclaw/ (ملف واحد لكل يوم): openclaw-YYYY-MM-DD.log
  • يستخدم التاريخ المنطقة الزمنية المحلية لمضيف Gateway.
• تدور ملفات السجل النشطة عند logging.maxFileBytes (الافتراضي: 100 ميغابايت)، مع الاحتفاظ بما يصل إلى خمسة أرشيفات مرقمة ومتابعة الكتابة إلى ملف نشط جديد.
• يمكن ضبط مسار ملف السجل ومستواه عبر ~/.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)

التنقيح

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

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

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

سجلات Gateway WebSocket

يطبع 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

أمثلة:

# optimized (only errors/slow)openclaw gateway # show all WS traffic (paired)openclaw gateway --verbose --ws-log compact # show all WS traffic (full meta)openclaw gateway --verbose --ws-log full

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

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

السلوك:

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

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

ذو صلة

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