الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

لدى OpenClaw سطحان رئيسيان للسجلات:
  • سجلات الملفات (أسطر JSON) يكتبها Gateway.
  • مخرجات وحدة التحكم المعروضة في الطرفيات وواجهة Gateway Debug UI.
يعرض تبويب 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 الصريحة هذا الرجوع الاحتياطي. إذا تعذر الوصول إلى 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 المرقمة في العمل. تصدر أنشطة Talk والصوت الفوري والغرف المُدارة سجلات دورة حياة محدودة عبر مسار سجلات الملفات نفسه. تتضمن هذه السجلات نوع الحدث، والوضع، والنقل، والموفر، وقياسات الحجم/التوقيت عند توفرها، لكنها تحذف نص التفريغ، وحمولات الصوت، ومعرفات الأدوار، ومعرفات المكالمات، ومعرفات عناصر الموفر.

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

سجلات وحدة التحكم مدركة لـ 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 gateway
openclaw gateway --verbose --ws-log compact
openclaw 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 gateway
OPENCLAW_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.

​
ترابط التتبع

سجلات الملفات هي JSONL. عندما تحمل استدعاءة سجل سياق تتبع تشخيصيًا صالحًا، يكتب OpenClaw حقول التتبع كمفاتيح JSON علوية (traceId, spanId, parentSpanId, traceFlags) حتى تتمكن معالجات السجلات الخارجية من ربط السطر بامتدادات OTEL وانتشار traceparent الخاص بالموفر. تنشئ طلبات Gateway HTTP وإطارات Gateway WebSocket نطاق تتبع طلب داخليًا. ترث السجلات والأحداث التشخيصية الصادرة داخل ذلك النطاق غير المتزامن تتبع الطلب عندما لا تمرر سياق تتبع صريحًا. تصبح تتبعات تشغيل الوكيل واستدعاء النموذج أبناءً لتتبع الطلب النشط، بحيث يمكن ربط السجلات المحلية، واللقطات التشخيصية، وامتدادات OTEL، ورؤوس traceparent الموثوقة الخاصة بالموفر بواسطة traceId دون تسجيل محتوى الطلب أو النموذج الخام. تتدفق سجلات دورة حياة Talk أيضًا إلى سجلات OTLP عند تمكين تصدير سجلات OpenTelemetry، باستخدام السمات المحدودة نفسها مثل سجلات الملفات.

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

تسجل تشخيصات استدعاء النموذج قياسات محدودة للطلب/الاستجابة دون التقاط محتوى المطالبة أو الاستجابة الخام:
  • requestPayloadBytes: حجم حمولة طلب النموذج النهائية ببايتات UTF-8
  • responseStreamBytes: حجم أحداث استجابة النموذج المتدفقة ببايتات UTF-8
  • 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=.... الدليل الكامل: أعلام التشخيصات.
لتمكين أحداث التشخيصات لـ plugins أو وجهات مخصصة دون تصدير OTLP: 
{
  diagnostics: { enabled: true },
}
لتصدير OTLP إلى جامع، راجع تصدير OpenTelemetry.

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

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

​
ذات صلة