Журналювання

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

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

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

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

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

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

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

Кожен файл ротуються, коли досягає logging.maxFileBytes (за замовчуванням: 100 МБ). OpenClaw зберігає до пʼяти нумерованих архівів поруч з активним файлом, наприклад openclaw-YYYY-MM-DD.1.log, і продовжує запис у новий активний журнал замість пригнічення діагностики.

Це можна перевизначити в ~/.openclaw/openclaw.json:

{  "logging": {    "file": "/path/to/openclaw.log"  }}

Як читати журнали

CLI: live tail (рекомендовано)

Використовуйте 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: нерозібраний рядок журналу

Якщо неявний local loopback Gateway просить спарювання, закривається під час підключення або спливає тайм-аут до відповіді logs.tail, openclaw logs автоматично повертається до налаштованого файлового журналу Gateway. Явні цілі --url не використовують цей резервний механізм.

Якщо Gateway недосяжний, CLI друкує коротку підказку запустити:

openclaw doctor

Інтерфейс керування (web)

Вкладка Журнали в інтерфейсі керування відстежує той самий файл за допомогою logs.tail. Див. Інтерфейс керування, щоб дізнатися, як його відкрити.

Журнали лише каналів

Щоб відфільтрувати активність каналів (WhatsApp/Telegram/тощо), використовуйте:

openclaw channels logs --channel whatsapp

Формати журналів

Файлові журнали (JSONL)

Кожен рядок у файлі журналу є обʼєктом JSON. CLI та інтерфейс керування розбирають ці записи, щоб відобразити структурований вивід (час, рівень, підсистема, повідомлення).

Записи JSONL файлового журналу також містять машинно-фільтровані поля верхнього рівня, коли вони доступні:

• hostname: імʼя хоста gateway.
• message: сплощений текст повідомлення журналу для повнотекстового пошуку.
• agent_id: ідентифікатор активного агента, коли виклик журналу містить контекст агента.
• session_id: ідентифікатор/ключ активного сеансу, коли виклик журналу містить контекст сеансу.
• channel: активний канал, коли виклик журналу містить контекст каналу.

OpenClaw зберігає початкові структуровані аргументи журналу поруч із цими полями, щоб наявні парсери, які читають нумеровані ключі аргументів tslog, продовжували працювати.

Активність розмов, голосу в реальному часі та керованих кімнат створює обмежені записи журналу життєвого циклу через той самий конвеєр файлового журналу. Ці записи містять тип події, режим, транспорт, провайдера та вимірювання розміру/часу, коли вони доступні, але не містять тексту транскрипта, аудіонавантажень, ідентифікаторів ходів, ідентифікаторів викликів і ідентифікаторів елементів провайдера.

Вивід консолі

Консольні журнали враховують TTY і форматуються для читабельності:

• Префікси підсистем (наприклад, gateway/channels/whatsapp)
• Кольорування рівнів (info/warn/error)
• Необовʼязковий компактний режим або режим JSON

Форматування консолі керується logging.consoleStyle.

Журнали WebSocket Gateway

openclaw gateway також має журналювання протоколу WebSocket для RPC-трафіку:

• звичайний режим: лише цікаві результати (помилки, помилки розбору, повільні виклики)
• --verbose: увесь трафік запитів/відповідей
• --ws-log auto|compact|full: вибрати стиль детального відображення
• --compact: псевдонім для --ws-log compact

Приклади:

openclaw gatewayopenclaw gateway --verbose --ws-log compactopenclaw 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; він не змінює рівні файлових журналів.

Цільова діагностика транспорту моделі

Під час налагодження викликів провайдера використовуйте цільові прапорці середовища замість підвищення всіх журналів до debug:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gatewayOPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway

Доступні прапорці:

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1: виводити початок запиту, відповідь fetch, заголовки SDK, першу подію потокової передачі, завершення потоку та помилки транспорту на рівні info.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: додавати обмежений підсумок навантаження запиту до журналів запитів моделі.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: додавати всі назви інструментів, видимі моделі, до підсумку навантаження.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: додавати відредагований, обмежений знімок JSON-навантаження. Використовуйте лише під час налагодження; секрети редагуються, але підказки й текст повідомлень можуть усе ще бути присутні.
• OPENCLAW_DEBUG_SSE=events: виводити час першої події та завершення потоку.
• OPENCLAW_DEBUG_SSE=peek: також виводити перші пʼять відредагованих навантажень подій SSE, обмежених для кожної події.
• OPENCLAW_DEBUG_CODE_MODE=1: виводити діагностику поверхні моделі в режимі коду, зокрема коли нативні інструменти провайдера приховані, бо режим коду володіє поверхнею інструментів.

Ці прапорці журналюються через звичайне журналювання OpenClaw, тож openclaw logs --follow і вкладка Журнали в інтерфейсі керування показують їх. Без прапорців та сама діагностика залишається доступною на рівні debug.

Кореляція трасування

Файлові журнали є JSONL. Коли виклик журналу містить чинний контекст діагностичного трасування, OpenClaw записує поля трасування як ключі JSON верхнього рівня (traceId, spanId, parentSpanId, traceFlags), щоб зовнішні обробники журналів могли корелювати рядок зі спанами OTEL і поширенням traceparent провайдера.

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

Записи журналу життєвого циклу розмов також надходять до журналів OTLP, коли експорт журналів OpenTelemetry увімкнено, з використанням тих самих обмежених атрибутів, що й файлові журнали.

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

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

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

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

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

logging.consoleStyle:

• pretty: зручний для людей, кольоровий, з часовими позначками.
• compact: стисліший вивід (найкраще для довгих сеансів).
• json: JSON на рядок (для обробників журналів).

Редагування секретів

OpenClaw може редагувати чутливі токени до того, як вони потраплять у вивід консолі, файлові журнали, записи журналів OTLP, збережений текст транскрипта сеансу або навантаження подій інструментів інтерфейсу керування (аргументи запуску інструментів, часткові/фінальні навантаження результатів, похідний вивід exec і підсумки патчів):

• logging.redactSensitive: off | tools (за замовчуванням: tools)
• logging.redactPatterns: список рядків regex для перевизначення стандартного набору. Власні шаблони застосовуються поверх вбудованих стандартних шаблонів для навантажень інструментів інтерфейсу керування, тому додавання шаблону ніколи не послаблює редагування значень, які вже перехоплюються стандартними шаблонами.

Файлові журнали та транскрипти сеансів залишаються JSONL, але відповідні секретні значення маскуються до запису рядка або повідомлення на диск. Редагування виконується на основі найкращих зусиль: воно застосовується до текстового вмісту повідомлень і рядків журналу, але не до кожного ідентифікатора або поля бінарного навантаження.

Вбудовані стандартні шаблони охоплюють поширені облікові дані API та назви полів платіжних облікових даних, як-от номер картки, CVC/CVV, спільний платіжний токен і платіжні облікові дані, коли вони зʼявляються як поля JSON, параметри URL, прапорці CLI або присвоєння.

logging.redactSensitive: "off" вимикає лише цю загальну політику журналів/транскриптів. OpenClaw усе одно редагує навантаження межі безпеки, які можуть показуватися клієнтам UI, пакетам підтримки, спостерігачам діагностики, запитам схвалення або інструментам агента. Приклади включають події викликів інструментів інтерфейсу керування, вивід sessions_history, експорти діагностичної підтримки, спостереження помилок провайдера, відображення команди для схвалення exec і журнали протоколу WebSocket Gateway. Власні logging.redactPatterns усе ще можуть додавати проєктно-специфічні шаблони на цих поверхнях.

Діагностика та OpenTelemetry

Діагностика — це структуровані, машинно-читані події для запусків моделі та телеметрії потоку повідомлень (webhooks, черги, стан сеансу). Вони не замінюють журнали — вони живлять метрики, трасування та експортери. Події створюються в процесі незалежно від того, експортуєте ви їх чи ні.

Дві суміжні поверхні:

• Експорт OpenTelemetry — надсилання метрик, трасувань і журналів через OTLP/HTTP до будь-якого сумісного з OpenTelemetry колектора або бекенда (Grafana, Datadog, Honeycomb, New Relic, Tempo тощо). Повна конфігурація, каталог сигналів, назви метрик/спанів, змінні середовища та модель приватності наведені на окремій сторінці: Експорт OpenTelemetry.
• Прапорці діагностики — цільові прапорці debug-журналів, які спрямовують додаткові журнали до logging.file без підвищення logging.level. Прапорці не чутливі до регістру і підтримують символи узагальнення (telegram.*, *). Налаштовуйте в diagnostics.flags або через перевизначення середовища OPENCLAW_DIAGNOSTICS=.... Повний посібник: Прапорці діагностики.

Щоб увімкнути діагностичні події для плагінів або власних приймачів без експорту OTLP:

{  diagnostics: { enabled: true },}

Для експорту OTLP до колектора див. Експорт OpenTelemetry.

Поради з усунення несправностей

• Gateway недосяжний? Спочатку запустіть openclaw doctor.
• Журнали порожні? Перевірте, що Gateway працює й записує до шляху файлу в logging.file.
• Потрібно більше деталей? Установіть logging.level на debug або trace і повторіть.

Повʼязане

• Експорт OpenTelemetry — експорт OTLP/HTTP, каталог метрик/спанів, модель приватності
• Прапорці діагностики — цільові прапорці debug-журналів
• Внутрішнє журналювання Gateway — стилі журналів WS, префікси підсистем і захоплення консолі
• Довідник конфігурації — повний довідник полів diagnostics.*