پرچم‌های عیب‌یابی

پرچم‌های عیب‌یابی، ثبت گزارش اضافی را برای یک زیرسامانه فعال می‌کنند، بدون اینکه logging.level را به‌صورت سراسری افزایش دهند. یک پرچم فقط زمانی اثر دارد که زیرسامانه‌ای آن را بررسی کند.

نحوهٔ کار

• پرچم‌ها رشته‌هایی بدون حساسیت به بزرگی و کوچکی حروف هستند که از diagnostics.flags در پیکربندی به‌همراه بازنویسی متغیر محیطی OPENCLAW_DIAGNOSTICS استخراج، تکراری‌زدایی و با حروف کوچک تبدیل می‌شوند.
• name.* با خود name و هر چیزی زیر name. مطابقت دارد (برای مثال، telegram.* با telegram.http مطابقت دارد).
• * یا all همهٔ پرچم‌ها را فعال می‌کند.
• پس از تغییر diagnostics.flags در پیکربندی، Gateway را راه‌اندازی مجدد کنید؛ این مقدار به‌صورت آنی بارگذاری مجدد نمی‌شود.

پرچم‌های شناخته‌شده

فعال‌سازی از طریق پیکربندی

{  "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

فعال‌کردن فقط بازه‌های پروفایلر راه‌اندازی، ابزار و رشتهٔ app-server متعلق به Codex:

OPENCLAW_DIAGNOSTICS=codex.profiler openclaw gateway run

profiler هم پروفایلر پاسخ و هم پروفایلر Codex را فعال می‌کند؛ برای فعال‌کردن فقط یکی، از نام‌های پرچم دارای دامنه استفاده کنید.

یا آن را در پیکربندی تنظیم کنید:

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

پس از تغییر پرچم‌های پیکربندی، Gateway را راه‌اندازی مجدد کنید. برای غیرفعال‌کردن یک پرچم پروفایلر، آن را از diagnostics.flags حذف و Gateway را راه‌اندازی مجدد کنید، یا فرایند را با 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 و =* نیز خط زمانی را فعال می‌کنند، زیرا همهٔ پرچم‌ها را فعال می‌کنند. وقتی فقط آرتیفکت JSONL را می‌خواهید و نه همهٔ پرچم‌های عیب‌یابی دیگر را، پرچم دامنه‌دار timeline را ترجیح دهید.

نمونه‌های تأخیر حلقهٔ رویداد در خط زمانی، علاوه بر 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 نشانی‌های اینترنتی و پارامترهای پرس‌وجوی درخواست Brave Search، وضعیت و زمان‌بندی پاسخ و رویدادهای اصابت، عدم اصابت و نوشتن حافظهٔ نهان را ثبت می‌کند. این پرچم کلید API (که به‌صورت سرآیند درخواست ارسال می‌شود) یا بدنهٔ پاسخ‌ها را ثبت نمی‌کند، اما عبارت‌های جست‌وجو ممکن است حساس باشند.
• فعال‌ماندن پرچم‌ها ایمن است؛ آن‌ها فقط حجم گزارش زیرسامانهٔ مشخص‌شده را تحت تأثیر قرار می‌دهند.
• برای تغییر مقصد، سطح و پوشاندن اطلاعات حساس گزارش‌ها، از /logging استفاده کنید.

مرتبط

• عیب‌یابی Gateway
• رفع اشکال Gateway