docs/docs/uk/logging.md

read_when	summary	title	x-i18n
Вам потрібен зручний для початківців огляд журналювання OpenClaw Ви хочете налаштувати рівні журналювання, формати або маскування Ви усуваєте несправність і вам потрібно швидко знайти журнали	Файлові журнали, вивід консолі, відстеження CLI та вкладка «Журнали» інтерфейсу керування	Журналювання	generated_at model provider source_hash source_path workflow 2026-05-01T05:53:19Z gpt-5.5 openai d41ce5b1ae30fe1ca65577abe387fc266bd281686acb10098f82b8e78dfaa357 logging.md 16

OpenClaw має дві основні поверхні журналювання:

• Файлові журнали (рядки JSON), які записує Gateway.
• Консольний вивід, що відображається в терміналах і Gateway Debug UI.

Вкладка Logs у Control UI відстежує файловий журнал gateway. Ця сторінка пояснює, де зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання.

Де зберігаються журнали

За замовчуванням Gateway записує ротаційний файл журналу в:

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

Дата використовує локальний часовий пояс хоста gateway.

Кожен файл ротується, коли досягає logging.maxFileBytes (за замовчуванням: 100 MB). 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. Див. /web/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 і поширенням traceparent провайдера.

HTTP-запити Gateway і кадри Gateway WebSocket встановлюють внутрішню область трасування запиту. Журнали й діагностичні події, емітовані в цій асинхронній області, успадковують трасування запиту, коли вони не передають явний контекст трасування. Трасування запуску агента й викликів моделі стають дочірніми до активного трасування запиту, тому локальні журнали, діагностичні знімки, спани OTEL і довірені заголовки traceparent провайдера можна об’єднувати за traceId без журналювання сирого вмісту запиту або моделі.

Розмір і час виклику моделі

Діагностика викликів моделі записує обмежені вимірювання запиту/відповіді без захоплення сирого вмісту промпта або відповіді:

• requestPayloadBytes: розмір у байтах UTF-8 фінального корисного навантаження запиту до моделі
• responseStreamBytes: розмір у байтах UTF-8 потокових подій відповіді моделі
• timeToFirstByteMs: час, що минув до першої потокової події відповіді
• durationMs: загальна тривалість виклику моделі

Ці поля доступні для діагностичних знімків, хуків Plugin для викликів моделі та спанів/метрик викликів моделі OTEL, коли експорт діагностики ввімкнено.

Стилі консолі

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 тощо). Повна конфігурація, каталог сигналів, назви метрик/спанів, змінні середовища й модель приватності розміщені на окремій сторінці: Експорт 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, каталог метрик/спанів, модель приватності
• Прапорці діагностики — цільові прапорці журналів налагодження
• Внутрішні механізми журналювання Gateway — стилі журналів WS, префікси підсистем і захоплення консолі
• Довідник конфігурації — повний довідник полів diagnostics.*