---
read_when:
    - Вам потрібен зручний для початківців огляд журналювання OpenClaw
    - Ви хочете налаштувати рівні журналювання, формати або маскування
    - Ви усуваєте несправність і вам потрібно швидко знайти журнали.
summary: Файлові журнали, консольний вивід, відстеження через CLI і вкладка журналів Control UI
title: Журналювання
x-i18n:
    generated_at: "2026-05-11T20:44:23Z"
    model: gpt-5.5
    provider: openai
    source_hash: 49b28755998bbe667dd986ae8440d9006d03b0704679bb6d64b5a148a25fc50e
    source_path: logging.md
    workflow: 16
---

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`:

```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>`: стандартні прапорці 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 друкує коротку підказку запустити:

```bash
openclaw doctor
```

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

Вкладка **Журнали** в інтерфейсі керування відстежує той самий файл за допомогою `logs.tail`.
Див. [Інтерфейс керування](/uk/web/control-ui), щоб дізнатися, як його відкрити.

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

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

```bash
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`

Приклади:

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

Щоб увімкнути діагностичні події для плагінів або власних приймачів без експорту 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) — цільові прапорці debug-журналів
- [Внутрішнє журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі
- [Довідник конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*`