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

پرچم‌های عیب‌یابی، بدون افزایش سراسری 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 برای چارچوب‌های خارجی QA می‌نویسد:

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

پروفایل‌های نام‌گذاری‌شده از /tmp/openclaw/openclaw-<profile>-YYYY-MM-DD.log استفاده می‌کنند؛ برای مثال، --dev از openclaw-dev-YYYY-MM-DD.log استفاده می‌کند.

اگر logging.file را تنظیم کرده‌اید، به‌جای آن از همان مسیر استفاده کنید. گزارش‌ها JSONL هستند (در هر خط یک شیء JSON). پنهان‌سازی همچنان بر اساس logging.redactSensitive اعمال می‌شود. برای مدل کامل تعیین مسیر گزارش، چرخش و پنهان‌سازی، ثبت گزارش را ببینید.

استخراج گزارش‌ها

جدیدترین فایل گزارش پروفایل فعال را بخوانید:

openclaw logs --plain# نمونه پروفایل نام‌گذاری‌شده:openclaw --profile work logs --plain

برای عیب‌یابی HTTP مربوط به Telegram فیلتر کنید:

openclaw logs --plain --limit 5000 | rg "telegram http error"

برای عیب‌یابی HTTP مربوط به Brave Search فیلتر کنید:

openclaw logs --plain --limit 5000 | rg "brave http"

یا هنگام بازتولید، گزارش را به‌صورت زنده دنبال کنید:

openclaw logs --follow --plain | rg "telegram http error"

برای Gatewayهای راه‌دور، به‌جای آن از openclaw logs --follow استفاده کنید (به /cli/logs مراجعه کنید).

نکته‌ها

• اگر logging.level بالاتر از warn تنظیم شده باشد، ممکن است گزارش‌های تحت کنترل پرچم سرکوب شوند. مقدار پیش‌فرض info مناسب است.
• brave.http نشانی‌های URL/پارامترهای پرس‌وجوی درخواست Brave Search، وضعیت/زمان‌بندی پاسخ و رویدادهای اصابت/عدم اصابت/نوشتن حافظه نهان را ثبت می‌کند. کلید API (که به‌صورت سرآیند درخواست ارسال می‌شود) یا بدنه پاسخ‌ها را ثبت نمی‌کند، اما پرس‌وجوهای جست‌وجو می‌توانند حساس باشند.
• فعال نگه‌داشتن پرچم‌ها ایمن است؛ آن‌ها فقط بر حجم گزارش‌های زیرسامانه مشخص اثر می‌گذارند.
• برای تغییر مقصدها، سطوح و پنهان‌سازی گزارش از /logging استفاده کنید.

مرتبط

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