علامات التشخيص

تُفعِّل علامات التشخيص تسجيلًا إضافيًا لنظام فرعي واحد من دون رفع logging.level عموميًا. ولا يكون للعلامة أي تأثير ما لم يتحقق منها نظام فرعي.

كيفية العمل

• العلامات سلاسل غير حساسة لحالة الأحرف، وتُستمد من diagnostics.flags في الإعدادات بالإضافة إلى تجاوز متغير البيئة OPENCLAW_DIAGNOSTICS، مع إزالة التكرارات وتحويلها إلى أحرف صغيرة.
• يطابق name.* الاسم name نفسه وأي شيء ضمن name. (على سبيل المثال، يطابق telegram.* القيمة telegram.http).
• تفعّل * أو all كل علامة.
• أعد تشغيل Gateway بعد تغيير diagnostics.flags في الإعدادات؛ إذ لا تُعاد تهيئتها تلقائيًا أثناء التشغيل.

العلامات المعروفة

التفعيل عبر الإعدادات

{  "diagnostics": {    "flags": ["telegram.http"]  }}

علامات متعددة:

{  "diagnostics": {    "flags": ["telegram.http", "brave.http", "gateway.*"]  }}

تجاوز متغير البيئة (لمرة واحدة)

OPENCLAW_DIAGNOSTICS=telegram.http,brave.http

تُقسَّم القيم عند الفواصل أو المسافات البيضاء. القيم الخاصة:

تعطّل OPENCLAW_DIAGNOSTICS=0 العلامات من متغير البيئة والإعدادات معًا لتلك العملية، وهو أمر مفيد لإسكات علامة محلل أداء متروكة مفعّلة في الإعدادات مؤقتًا من دون تعديل الملف.

علامات محلل الأداء

تتحكم علامات محلل الأداء في فترات قياس زمنية خفيفة؛ ولا تضيف أي عبء عند تعطيلها.

لتفعيل كل الفترات التي تتحكم فيها علامات محلل الأداء لتشغيل واحد لـ Gateway:

OPENCLAW_DIAGNOSTICS=profiler openclaw gateway run

لتفعيل فترات محلل أداء توزيع الردود فقط:

OPENCLAW_DIAGNOSTICS=reply.profiler openclaw gateway run

لتفعيل فترات محلل أداء بدء تشغيل/أداة/سلسلة خادم تطبيق Codex فقط:

OPENCLAW_DIAGNOSTICS=codex.profiler openclaw gateway run

تفعّل profiler كلًا من محلل أداء الردود ومحلل أداء Codex؛ استخدم أسماء العلامات محددة النطاق لتفعيل واحد فقط.

أو عيّنها في الإعدادات:

{  "diagnostics": {    "flags": ["reply.profiler", "codex.profiler"]  }}

أعد تشغيل Gateway بعد تغيير علامات الإعدادات. لتعطيل علامة محلل أداء، أزلها من diagnostics.flags وأعد التشغيل، أو ابدأ العملية باستخدام OPENCLAW_DIAGNOSTICS=0 لتجاوز كل علامات التشخيص لذلك التشغيل.

أدوات الخط الزمني

تكتب العلامة timeline (الاسم البديل: diagnostics.timeline) أحداث توقيت منظّمة لبدء التشغيل ووقت التشغيل بتنسيق JSONL، لاستخدامها في أُطر ضمان الجودة الخارجية:

OPENCLAW_DIAGNOSTICS=timeline \OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=/tmp/openclaw-timeline.jsonl \openclaw gateway run

أو فعّلها في الإعدادات:

{  "diagnostics": {    "flags": ["timeline"]  }}

يأتي مسار الإخراج دائمًا من OPENCLAW_DIAGNOSTICS_TIMELINE_PATH، حتى عندما تكون العلامة نفسها معيّنة في الإعدادات؛ فلا يوجد مفتاح إعدادات للمسار. عند تفعيل timeline من الإعدادات فقط، تغيب الفترات الأولى لتحميل الإعدادات لأن OpenClaw لم يقرأ الإعدادات بعد؛ وتُلتقط فترات بدء التشغيل اللاحقة بصورة طبيعية.

تفعّل أيضًا OPENCLAW_DIAGNOSTICS=1 و=all و=* الخط الزمني، لأنها تفعّل كل علامة. فضّل العلامة محددة النطاق timeline عندما لا تريد سوى أداة JSONL دون جميع علامات التشخيص الأخرى.

تحتاج عينات تأخر حلقة الأحداث في الخط الزمني إلى موافقة إضافية إلى جانب timeline: عيّن OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 (أو on/true/yes) بالإضافة إلى تفعيل الخط الزمني.

تستخدم سجلات الخط الزمني غلاف openclaw.diagnostics.v1، ويمكن أن تتضمن معرّفات العمليات، وأسماء المراحل، وأسماء الفترات، والمدد، ومعرّفات Plugin، وأعداد التبعيات، وعينات تأخر حلقة الأحداث، وأسماء عمليات المزوّد، وحالة خروج العملية الفرعية، وأسماء/رسائل أخطاء بدء التشغيل. تعامل مع ملفات الخط الزمني كأدوات تشخيص محلية؛ وراجعها قبل مشاركتها خارج جهازك.

وجهة السجلات

تُصدر العلامات السجلات إلى ملف سجل التشخيص القياسي. افتراضيًا:

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

إذا عيّنت logging.file، فاستخدم ذلك المسار بدلًا منه. تكون السجلات بتنسيق JSONL (كائن JSON واحد في كل سطر). يظل التنقيح مطبقًا استنادًا إلى logging.redactSensitive. راجع التسجيل للاطلاع على النموذج الكامل لتحديد مسار السجل وتدويره وتنقيحه.

استخراج السجلات

اختر أحدث ملف سجل:

ls -t /tmp/openclaw/openclaw-*.log | head -n 1

رشّح تشخيصات HTTP لـ Telegram:

rg "telegram http error" /tmp/openclaw/openclaw-*.log

رشّح تشخيصات HTTP لـ Brave Search:

rg "brave http" /tmp/openclaw/openclaw-*.log

أو راقب السجل أثناء إعادة إنتاج المشكلة:

tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"

بالنسبة إلى بوابات Gateway البعيدة، استخدم openclaw logs --follow بدلًا من ذلك (راجع /cli/logs).

ملاحظات

• إذا عُيّن logging.level على مستوى أعلى من warn، فقد تُحجب السجلات التي تتحكم فيها العلامات. المستوى الافتراضي info مناسب.
• يسجّل brave.http عناوين URL/معلمات الاستعلام لطلبات Brave Search، وحالة الاستجابة/توقيتها، وأحداث إصابة/إخفاق/كتابة ذاكرة التخزين المؤقت. ولا يسجّل مفتاح API (المرسل في ترويسة الطلب) أو نصوص الاستجابة، لكن استعلامات البحث قد تكون حساسة.
• من الآمن إبقاء العلامات مفعّلة؛ فهي لا تؤثر إلا في حجم السجل الخاص بالنظام الفرعي المحدد.
• استخدم /logging لتغيير وجهات السجلات ومستوياتها وتنقيحها.

ذو صلة

• تشخيصات Gateway
• استكشاف أخطاء Gateway وإصلاحها