Gateway

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

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

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

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

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

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

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

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

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

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

json

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

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

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

Використовуйте CLI, щоб відстежувати файл журналу gateway через RPC:

bash

openclaw logs --follow

Корисні поточні параметри:

--local-time: відображати часові позначки у вашому локальному часовому поясі
--url <url> / --token <token> / --timeout <ms>: стандартні прапорці RPC Gateway
--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 не використовують цей резервний механізм. openclaw logs --follow суворіший: у Linux він використовує активний журнал user-systemd Gateway за PID, коли доступно, а інакше продовжує повторювати спроби підключення до живого Gateway замість відстеження потенційно застарілого сусіднього файлу.

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

bash

openclaw doctor

Control UI (веб)

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

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

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

bash

openclaw channels logs --channel whatsapp

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

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

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

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

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

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

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

Консольний вивід

Консольні журнали враховують 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

Приклади:

bash

openclaw gatewayopenclaw gateway --verbose --ws-log compactopenclaw gateway --verbose --ws-log full

Налаштування журналювання

Уся конфігурація журналювання міститься в logging у ~/.openclaw/openclaw.json.

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:

bash

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-навантаження. Використовуйте лише під час налагодження; секрети редагуються, але prompts і текст повідомлень можуть усе ще бути присутні.
OPENCLAW_DEBUG_SSE=events: виводити час першої події та завершення потоку.
OPENCLAW_DEBUG_SSE=peek: також виводити перші п’ять відредагованих навантажень подій SSE, обмежених для кожної події.
OPENCLAW_DEBUG_CODE_MODE=1: виводити діагностику поверхні моделі code-mode, зокрема коли власні інструменти провайдера приховані, бо code mode володіє поверхнею інструментів.

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

Метадані початку й відповіді [model-fetch] (провайдер, API, модель, статус, затримка та поля запиту, як-от метод, URL, timeout, proxy і policy) завжди виводяться на рівні info незалежно від OPENCLAW_DEBUG_MODEL_TRANSPORT, тож базова гігієна транспорту моделі видима без прапорців налагодження.

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

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

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

Записи журналу життєвого циклу Talk також надходять до експорту журналів diagnostics-otel, коли експорт журналів OpenTelemetry увімкнено, використовуючи ті самі обмежені атрибути, що й файлові журнали. Налаштуйте diagnostics.otel.logsExporter, щоб вибрати OTLP, stdout JSONL або обидва приймачі.

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

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

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

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

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

logging.consoleStyle:

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

Редагування

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

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

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

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

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

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

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

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

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

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

json5

{  diagnostics: { enabled: true },}

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

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

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

Пов’язане

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

Was this useful?

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

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

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

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

Control UI (веб)

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

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

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

Консольний вивід

Журнали Gateway WebSocket

Налаштування журналювання

Рівні журналів

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

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

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

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

Редагування

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

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

Пов’язане

On this page

Molty