---
read_when:
    - Вам потрібен зручний для початківців огляд журналювання OpenClaw
    - Ви хочете налаштувати рівні журналювання, формати або редагування чутливих даних
    - Ви усуваєте неполадки й маєте швидко знайти журнали
summary: Файлові журнали, вивід консолі, відстеження журналів через CLI та вкладка «Журнали» Control UI
title: Журналювання
x-i18n:
    generated_at: "2026-06-27T17:43:08Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: caf2780dfeeaf29f4ee94429894a03422b211a4414e63062642d1134f38b6b3f
    source_path: logging.md
    workflow: 16
---

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](/uk/web/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 gateway
openclaw gateway --verbose --ws-log compact
openclaw 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 gateway
OPENCLAW_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](/uk/gateway/opentelemetry).
- **Прапорці діагностики** — цільові прапорці журналів налагодження, які спрямовують додаткові журнали до
  `logging.file` без підвищення `logging.level`. Прапорці нечутливі до регістру
  та підтримують wildcard (`telegram.*`, `*`). Налаштовуйте в `diagnostics.flags`
  або через перевизначення середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник:
  [Прапорці діагностики](/uk/diagnostics/flags).

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

```json5
{
  diagnostics: { enabled: true },
}
```

Для експорту OTLP до колектора див. [експорт OpenTelemetry](/uk/gateway/opentelemetry).

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

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

## Пов’язане

- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог метрик/спанів, модель приватності
- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці журналів налагодження
- [Внутрішні механізми журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі
- [Довідник із конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*`