Gateway

التسجيل

لدى 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 المرقمة عاملة.

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

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

سجلات وحدة التحكم مدركة لـ 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؛ ولا يغير مستويات سجل الملفات.

ربط التتبعات

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

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

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

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

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

requestPayloadBytes: حجم حمولة طلب النموذج النهائية بالبايت وفق UTF-8
responseStreamBytes: حجم أحداث استجابة النموذج المتدفقة بالبايت وفق UTF-8
timeToFirstByteMs: الوقت المنقضي قبل أول حدث استجابة متدفقة
durationMs: إجمالي مدة استدعاء النموذج

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

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

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، إلخ). توجد الإعدادات الكاملة، وفهرس الإشارات، وأسماء المقاييس/spans، ومتغيرات البيئة، ونموذج الخصوصية في صفحة مخصصة: تصدير 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 ثم أعد المحاولة.

ذو صلة

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

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

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

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

# Control UI (الويب)

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

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

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

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

# سجلات Gateway WebSocket

# تكوين التسجيل

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

# ربط التتبعات

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

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

# التنقيح

# التشخيصات وOpenTelemetry

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

# ذو صلة