openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-26 22:05:44 +00:00
parent cc9755a50f
commit 5f6552f3cb
1 changed files with 104 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

197
docs/uk/logging.md
View File

@ -1,38 +1,38 @@
---
read_when:
- Вам потрібен огляд логування OpenClaw, зрозумілий для початківців
- Ви хочете налаштувати рівні логування, формати або редагування конфіденційних даних
- Ви усуваєте несправності й вам потрібно швидко знайти логи
summary: Файлові логи, вивід консолі, відстеження CLI та вкладка «Логи» в Control UI
title: Логування
- Вам потрібен огляд журналювання OpenClaw, зрозумілий для початківців
- Ви хочете налаштувати рівні журналювання, формати або редагування конфіденційних даних
- Ви усуваєте несправності й вам потрібно швидко знайти журнали
summary: Журнали файлів, вивід консолі, відстеження CLI та вкладка «Журнали» в Control UI
title: Журналювання
x-i18n:
generated_at: "2026-04-26T21:17:02Z"
generated_at: "2026-04-26T22:05:00Z"
model: gpt-5.4
provider: openai
source_hash: ece4fe127194144fccda44d42903cdbb989183b6e87aedf9ac2470704be26bdb
source_hash: 6fb71b94a5c4fb8db9c704552f73f364b45c9d19bfb74c92abe1f22576fe1480
source_path: logging.md
workflow: 15
---
OpenClaw має дві основні поверхні логування:
OpenClaw має дві основні поверхні журналювання:
- **Файлові логи** (рядки JSON), які записує Gateway.
- **Файлові журнали** (рядки JSON), які записує Gateway.
- **Вивід консолі**, що показується в терміналах і в Gateway Debug UI.
Вкладка **Logs** у Control UI відстежує файловий лог gateway. На цій сторінці пояснюється, де зберігаються логи, як їх читати та як налаштовувати рівні й формати логування.
Вкладка **Logs** у Control UI відстежує файловий журнал gateway. На цій сторінці пояснюється, де розташовані журнали, як їх читати та як налаштовувати рівні й формати журналювання.
## Де зберігаються логи
## Де розташовані журнали
Типово Gateway записує циклічний файл логу за шляхом:
Типово Gateway записує ротаційний файл журналу в:
`/tmp/openclaw/openclaw-YYYY-MM-DD.log`
Дата використовує локальний часовий пояс хоста gateway.
Кожен файл ротується, коли досягає `logging.maxFileBytes` (типово: 100 МБ).
OpenClaw зберігає до п’яти пронумерованих архівів поруч з активним файлом, наприклад
`openclaw-YYYY-MM-DD.1.log`, і продовжує писати в новий активний лог, а не
приглушує діагностичні дані.
Кожен файл ротується, коли досягає `logging.maxFileBytes` (типово: 100 MB).
OpenClaw зберігає до п’яти нумерованих архівів поруч з активним файлом, наприклад
`openclaw-YYYY-MM-DD.1.log`, і продовжує запис у новий активний журнал замість
приглушення діагностичних даних.
Ви можете перевизначити це в `~/.openclaw/openclaw.json`:
@ -44,11 +44,11 @@ OpenClaw зберігає до п’яти пронумерованих архі
}
```
## Як читати логи
## Як читати журнали
### CLI: відстеження в реальному часі (рекомендовано)
Використовуйте CLI, щоб відстежувати файл логу gateway через RPC:
Використовуйте CLI для відстеження файла журналу gateway через RPC:
```bash
openclaw logs --follow
@ -56,32 +56,32 @@ openclaw logs --follow
Корисні поточні параметри:
- `--local-time`: показувати часові мітки у вашому локальному часовому поясі
- `--local-time`: відображати часові мітки у вашому локальному часовому поясі
- `--url <url>` / `--token <token>` / `--timeout <ms>`: стандартні прапорці Gateway RPC
- `--expect-final`: прапорець очікування фінальної відповіді RPC із підтримкою агентів (підтримується тут через спільний клієнтський шар)
- `--expect-final`: прапорець очікування фінальної відповіді для RPC, що працює через агента (приймається тут через спільний клієнтський шар)
Режими виводу:
- **TTY-сеанси**: гарно оформлені, кольорові, структуровані рядки логів.
- **Не-TTY сеанси**: звичайний текст.
- `--json`: JSON з розділенням по рядках (одна подія логу на рядок).
- **TTY-сеанси**: гарні, кольорові, структуровані рядки журналу.
- **Не-TTY-сеанси**: звичайний текст.
- `--json`: JSON з розділенням по рядках (одна подія журналу на рядок).
- `--plain`: примусово використовувати звичайний текст у TTY-сеансах.
- `--no-color`: вимкнути ANSI-кольори.
- `--no-color`: вимкнути кольори ANSI.
Коли ви передаєте явний `--url`, CLI не застосовує автоматично конфігурацію чи
облікові дані із середовища; додайте `--token` самостійно, якщо цільовий Gateway
потребує автентифікації.
облікові дані середовища; якщо цільовий Gateway
вимагає автентифікацію, вкажіть `--token` самостійно.
У режимі JSON CLI виводить об’єкти з тегом `type`:
У режимі JSON CLI виводить об’єкти з міткою `type`:
- `meta`: метадані потоку (файл, курсор, розмір)
- `log`: розібраний запис логу
- `log`: розібраний запис журналу
- `notice`: підказки про обрізання / ротацію
- `raw`: нерозібраний рядок логу
- `raw`: нерозібраний рядок журналу
Якщо Gateway на local loopback запитує pairing, `openclaw logs` автоматично
перемикається на налаштований локальний файл логу. Для явних цілей `--url`
цей резервний варіант не використовується.
Якщо локальний loopback Gateway запитує сполучення, `openclaw logs` автоматично
перемикається на налаштований локальний файл журналу. Явні цілі `--url` не
використовують цей резервний варіант.
Якщо Gateway недоступний, CLI виводить коротку підказку виконати:
@ -94,38 +94,49 @@ openclaw doctor
Вкладка **Logs** у Control UI відстежує той самий файл за допомогою `logs.tail`.
Див. [/web/control-ui](/uk/web/control-ui), щоб дізнатися, як її відкрити.
### Логи лише каналів
### Журнали лише каналу
Щоб відфільтрувати активність каналів (WhatsApp/Telegram тощо), використовуйте:
Щоб відфільтрувати активність каналу (WhatsApp/Telegram тощо), використовуйте:
```bash
openclaw channels logs --channel whatsapp
```
## Формати логів
## Формати журналів
### Файлові логи (JSONL)
### Файлові журнали (JSONL)
Кожен рядок у файлі логу — це об’єкт JSON. CLI і Control UI розбирають ці
записи, щоб показувати структурований вивід (час, рівень, підсистема, повідомлення).
Кожен рядок у файлі журналу — це об’єкт JSON. CLI і Control UI розбирають ці
записи для відображення структурованого виводу (час, рівень, підсистема, повідомлення).
Записи JSONL файлового журналу також містять машинно-фільтровані поля верхнього рівня, коли вони доступні:
- `hostname`: ім’я хоста gateway.
- `message`: зведений текст повідомлення журналу для повнотекстового пошуку.
- `agent_id`: id активного агента, коли виклик журналу містить контекст агента.
- `session_id`: id/ключ активної сесії, коли виклик журналу містить контекст сесії.
- `channel`: активний канал, коли виклик журналу містить контекст каналу.
OpenClaw зберігає оригінальні структуровані аргументи журналу поряд із цими полями,
щоб наявні парсери, які читають нумеровані ключі аргументів tslog, продовжували працювати.
### Вивід консолі
Логи консолі **враховують TTY** і форматуються для зручності читання:
Журнали консолі **з урахуванням TTY** і відформатовані для зручності читання:
- Префікси підсистем (наприклад, `gateway/channels/whatsapp`)
- Кольорове позначення рівнів (info/warn/error)
- Кольорове виділення рівнів (info/warn/error)
- Необов’язковий компактний або JSON-режим
Форматування консолі керується через `logging.consoleStyle`.
### Логи Gateway WebSocket
### Журнали WebSocket Gateway
`openclaw gateway` також має логування протоколу WebSocket для RPC-трафіку:
`openclaw gateway` також має журналювання протоколу WebSocket для RPC-трафіку:
- звичайний режим: лише важливі результати (помилки, помилки розбору, повільні виклики)
- звичайний режим: лише цікаві результати (помилки, помилки розбору, повільні виклики)
- `--verbose`: увесь трафік запитів/відповідей
- `--ws-log auto|compact|full`: вибір стилю детального виводу
- `--ws-log auto|compact|full`: вибір стилю докладного відображення
- `--compact`: псевдонім для `--ws-log compact`
Приклади:
@ -136,9 +147,9 @@ openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full
```
## Налаштування логування
## Налаштування журналювання
Усі налаштування логування зберігаються в `logging` у `~/.openclaw/openclaw.json`.
Усі налаштування журналювання розміщені в `logging` у `~/.openclaw/openclaw.json`.
```json
{
@ -153,85 +164,85 @@ openclaw gateway --verbose --ws-log full
}
```
### Рівні логування
### Рівні журналювання
- `logging.level`: рівень **файлових логів** (JSONL).
- `logging.level`: рівень **файлових журналів** (JSONL).
- `logging.consoleLevel`: рівень деталізації **консолі**.
Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має пріоритет над файлом конфігурації, тому ви можете підвищити деталізацію для одного запуску без редагування `openclaw.json`. Також можна передати глобальний параметр CLI **`--log-level <level>`** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди.
Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має вищий пріоритет за файл конфігурації, тому ви можете підвищити рівень деталізації для одного запуску без редагування `openclaw.json`. Також можна передати глобальний параметр CLI **`--log-level <level>`** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди.
`--verbose` впливає лише на вивід у консоль і деталізацію WS-логів; він не змінює
рівні файлових логів.
`--verbose` впливає лише на вивід консолі та рівень деталізації журналів WS; він не змінює
рівні файлових журналів.
### Кореляція трасування
Файлові логи мають формат JSONL. Коли виклик логу містить коректний діагностичний контекст трасування,
Файлові журнали мають формат JSONL. Коли виклик журналу містить коректний контекст діагностичного трасування,
OpenClaw записує поля трасування як JSON-ключі верхнього рівня (`traceId`, `spanId`,
`parentSpanId`, `traceFlags`), щоб зовнішні обробники логів могли пов’язувати рядок
із span OTEL і передаванням `traceparent` провайдера.
`parentSpanId`, `traceFlags`), щоб зовнішні обробники журналів могли співвідносити рядок
із діапазонами OTEL та поширенням `traceparent` у провайдера.
HTTP-запити Gateway і WebSocket-фрейми Gateway створюють внутрішню область трасування запиту.
Логи й діагностичні події, згенеровані в межах цієї асинхронної області, успадковують
трасування запиту, якщо не передано явний контекст трасування. Трасування запуску агента й
виклику моделі стають дочірніми до активного трасування запиту, тому локальні логи,
діагностичні знімки, span OTEL і довірені заголовки провайдера `traceparent` можна
пов’язати через `traceId` без логування сирого вмісту запиту або моделі.
HTTP-запити Gateway і кадри WebSocket Gateway створюють внутрішню область трасування запиту.
Журнали й діагностичні події, створені в межах цієї асинхронної області, успадковують
трасування запиту, якщо їм не передано явний контекст трасування. Трасування запуску агента й
виклику моделі стають дочірніми для активного трасування запиту, тому локальні журнали,
діагностичні знімки, діапазони OTEL і довірені заголовки `traceparent` провайдера можна
об’єднати за `traceId` без журналювання сирого вмісту запиту чи моделі.
### Розмір і час виклику моделі
### Розмір і тривалість виклику моделі
Діагностика викликів моделі записує обмежені вимірювання запиту/відповіді без
захоплення сирого вмісту prompt або відповіді:
Діагностичні дані виклику моделі фіксують обмежені вимірювання запиту/відповіді без
захоплення сирого вмісту запиту або відповіді:
- `requestPayloadBytes`: розмір у байтах UTF-8 фінального payload запиту до моделі
- `requestPayloadBytes`: розмір у байтах UTF-8 фінального корисного навантаження запиту до моделі
- `responseStreamBytes`: розмір у байтах UTF-8 подій потокової відповіді моделі
- `timeToFirstByteMs`: затримка до першої події потокової відповіді
- `timeToFirstByteMs`: минулий час до першої події потокової відповіді
- `durationMs`: загальна тривалість виклику моделі
Ці поля доступні для діагностичних знімків, hook-ів Plugin для викликів моделі та
span/метрик OTEL для викликів моделі, коли ввімкнено експорт діагностики.
Ці поля доступні для діагностичних знімків, хуків Plugin виклику моделі та
діапазонів/метрик виклику моделі OTEL, коли ввімкнено експорт діагностики.
### Стилі консолі
`logging.consoleStyle`:
- `pretty`: зручний для людини, кольоровий, з часовими мітками.
- `pretty`: зручний для читання людиною, кольоровий, із часовими мітками.
- `compact`: щільніший вивід (найкраще для довгих сеансів).
- `json`: JSON у кожному рядку (для обробників логів).
- `json`: JSON на рядок (для обробників журналів).
### Редагування конфіденційних даних
OpenClaw може маскувати конфіденційні токени до того, як вони потраплять у вивід консолі,
файлові логи, записи логів OTLP або збережений текст транскрипту сеансу:
OpenClaw може маскувати конфіденційні токени до того, як вони потраплять у вивід консолі, файлові журнали,
записи журналів OTLP або збережений текст стенограми сесії:
- `logging.redactSensitive`: `off` | `tools` (типово: `tools`)
- `logging.redactPatterns`: список рядків regex для перевизначення типового набору
Файлові логи й транскрипти сеансів залишаються у форматі JSONL, але значення секретів,
що збігаються, маскуються до того, як рядок або повідомлення буде записано на диск. Маскування виконується в межах найкращих зусиль:
воно застосовується до текстового вмісту повідомлень і рядків логів, але не до кожного
ідентифікатора чи поля двійкового payload.
Файлові журнали й стенограми сесій залишаються у форматі JSONL, але значення секретів, які збігаються,
маскуються до того, як рядок або повідомлення буде записано на диск. Маскування виконується за принципом best-effort:
воно застосовується до текстового вмісту повідомлень і рядків журналу, але не до кожного
ідентифікатора чи поля двійкового корисного навантаження.
## Діагностика та OpenTelemetry
Діагностика — це структуровані, машинозчитувані події для запусків моделей і
телеметрії потоку повідомлень (Webhook, постановка в чергу, стан сеансу). Вони **не**
замінюють логи — вони живлять метрики, трасування й експортери. Події генеруються
в процесі незалежно від того, чи експортуєте ви їх.
Діагностичні дані — це структуровані, машинозчитувані події для запусків моделей і
телеметрії потоку повідомлень (Webhooks, постановка в чергу, стан сесії). Вони **не**
замінюють журнали — вони живлять метрики, трасування та експортери. Події створюються
в процесі незалежно від того, експортуєте ви їх чи ні.
Дві суміжні поверхні:
- **Експорт OpenTelemetry** — надсилання метрик, трасувань і логів через OTLP/HTTP до
- **Експорт OpenTelemetry** — надсилає метрики, трасування та журнали через OTLP/HTTP до
будь-якого колектора або бекенда, сумісного з OpenTelemetry (Grafana, Datadog,
Honeycomb, New Relic, Tempo тощо). Повна конфігурація, каталог сигналів,
назви метрик/span, змінні середовища та модель приватності наведені на окремій сторінці:
назви метрик/діапазонів, змінні середовища й модель конфіденційності описані на окремій сторінці:
[Експорт OpenTelemetry](/uk/gateway/opentelemetry).
- **Прапорці діагностики** — цільові прапорці debug-логів, які спрямовують додаткові логи до
- **Прапорці діагностики** — цільові прапорці налагоджувальних журналів, які спрямовують додаткові журнали до
`logging.file` без підвищення `logging.level`. Прапорці нечутливі до регістру
й підтримують шаблони з wildcard (`telegram.*`, `*`). Налаштовуються в `diagnostics.flags`
або через перевизначення середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник:
і підтримують шаблони з підстановками (`telegram.*`, `*`). Налаштовуються в `diagnostics.flags`
або через перевизначення змінною середовища `OPENCLAW_DIAGNOSTICS=...`. Повний посібник:
[Прапорці діагностики](/uk/diagnostics/flags).
Щоб увімкнути діагностичні події для Plugin або користувацьких приймачів без експорту OTLP:
Щоб увімкнути діагностичні події для Plugins або власних приймачів без експорту OTLP:
```json5
{
@ -239,18 +250,18 @@ OpenClaw може маскувати конфіденційні токени д
}
```
Для експорту OTLP до колектора див. [Експорт OpenTelemetry](/uk/gateway/opentelemetry).
Щоб налаштувати експорт OTLP до колектора, див. [Експорт OpenTelemetry](/uk/gateway/opentelemetry).
## Поради з усунення несправностей
- **Gateway недоступний?** Спочатку виконайте `openclaw doctor`.
- **Логи порожні?** Перевірте, що Gateway запущено і він записує у шлях файлу,
указаний у `logging.file`.
- **Потрібно більше деталей?** Установіть `logging.level` у `debug` або `trace` і повторіть спробу.
- **Журнали порожні?** Переконайтеся, що Gateway запущено і він записує у шлях до файла,
вказаний у `logging.file`.
- **Потрібно більше деталей?** Встановіть `logging.level` у `debug` або `trace` і повторіть спробу.
## Пов’язане
- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог метрик/span, модель приватності
- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці debug-логів
- [Внутрішня будова логування Gateway](/uk/gateway/logging) — стилі WS-логів, префікси підсистем і захоплення консолі
- [Довідник із конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*`
- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — експорт OTLP/HTTP, каталог метрик/діапазонів, модель конфіденційності
- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці налагоджувальних журналів
- [Внутрішні механізми журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі
- [Довідник конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*`