Прапорці діагностики

Прапорці діагностики вмикають додаткове журналювання для окремої підсистеми, не підвищуючи глобально рівень 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

Увімкнути лише інтервали профайлера запуску, інструментів і потоків сервера застосунку 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 і =* також вмикають часову шкалу, оскільки вони вмикають усі прапорці. Віддавайте перевагу спеціалізованому прапорцю timeline, якщо вам потрібен лише артефакт JSONL, а не всі інші прапорці діагностики.

Для запису у часову шкалу вибірок затримки циклу подій потрібна ще одна окрема згода, крім timeline: додатково до ввімкнення часової шкали задайте OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 (або on/true/yes).

Записи часової шкали використовують конверт openclaw.diagnostics.v1 і можуть містити ідентифікатори процесів, назви фаз, назви інтервалів, тривалості, ідентифікатори плагінів, кількість залежностей, вибірки затримки циклу подій, назви операцій постачальників, стан завершення дочірніх процесів, а також назви й повідомлення помилок запуску. Вважайте файли часової шкали локальними діагностичними артефактами; перевіряйте їх перед передаванням за межі свого комп’ютера.

Куди записуються журнали

Прапорці записують повідомлення до стандартного файлу журналу діагностики. Типово:

/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