openclaw/docs

Fork 0

openclaw-docs-i18n[bot] e9280cbf79 chore(i18n): refresh uk translations

2026-04-25 18:45:20 +00:00

24 KiB

Raw Blame History

read_when

summary

title

x-i18n

Вам потрібен огляд журналювання, зрозумілий для початківців

Ви хочете налаштувати рівні журналювання або формати

Ви усуваєте несправності й хочете швидко знайти журнали

Огляд журналювання: журнали файлів, виведення в консоль, перегляд журналів у CLI та інтерфейс Control UI

Огляд журналювання

generated_at	model	provider	source_hash	source_path	workflow
2026-04-25T18:41:27Z	gpt-5.4	openai	745c14ef9ca008d43a0f4f2d5c051ec6bafbe5249e1a1753448182fff72afd6e	logging.md	15

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

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

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

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

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

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

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

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

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

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

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

CLI: перегляд у реальному часі (рекомендовано)

Використовуйте 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 не застосовує автоматично облікові дані з конфігурації або середовища; якщо цільовий Gateway вимагає автентифікації, додайте --token самостійно.

У режимі JSON CLI виводить об’єкти з тегом type:

meta: метадані потоку (файл, курсор, розмір)
log: розібраний запис журналу
notice: підказки про обрізання / ротацію
raw: нерозібраний рядок журналу

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

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

openclaw doctor

Control UI (веб)

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

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

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

openclaw channels logs --channel whatsapp

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

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

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

Виведення в консоль

Журнали консолі враховують 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 gateway
openclaw gateway --verbose --ws-log compact
openclaw 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; він не змінює рівні файлового журналу.

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

logging.consoleStyle:

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

Редагування чутливих даних

Підсумки інструментів можуть редагувати чутливі токени до того, як вони потраплять у консоль:

logging.redactSensitive: off | tools (типово: tools)
logging.redactPatterns: список рядків regex для перевизначення типового набору

Редагування впливає лише на виведення в консоль і не змінює файлові журнали.

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

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

Події діагностики створюються всередині процесу, але експортери підключаються лише тоді, коли ввімкнено діагностику та plugin експортера.

OpenTelemetry проти OTLP

OpenTelemetry (OTel): модель даних і SDK для трасувань, метрик і журналів.
OTLP: мережевий протокол, який використовується для експорту даних OTel у collector/backend.
OpenClaw наразі експортує через OTLP/HTTP (protobuf).

Експортовані сигнали

Метрики: лічильники та гістограми (використання токенів, потік повідомлень, постановка в чергу).
Трасування: spans для використання моделей і обробки webhook/повідомлень.
Журнали: експортуються через OTLP, коли ввімкнено diagnostics.otel.logs. Обсяг журналів може бути великим; зважайте на logging.level і фільтри експортера.

Каталог подій діагностики

Використання моделей:

model.usage: токени, вартість, тривалість, контекст, provider/model/channel, ідентифікатори сеансів.

Потік повідомлень:

webhook.received: вхідний webhook для кожного каналу.
webhook.processed: оброблений webhook + тривалість.
webhook.error: помилки обробника webhook.
message.queued: повідомлення поставлено в чергу для обробки.
message.processed: результат + тривалість + необов’язкова помилка.
message.delivery.started: розпочато спробу вихідної доставки.
message.delivery.completed: завершено спробу вихідної доставки + тривалість/кількість результатів.
message.delivery.error: помилка спроби вихідної доставки + тривалість/обмежена категорія помилки.

Черга + сеанс:

queue.lane.enqueue: додавання в lane черги команд + глибина.
queue.lane.dequeue: вилучення з lane черги команд + час очікування.
session.state: перехід стану сеансу + причина.
session.stuck: попередження про завислий сеанс + вік.
run.attempt: метадані повторної спроби/спроби запуску.
diagnostic.heartbeat: агреговані лічильники (webhooks/черга/сеанс).

Exec:

exec.process.completed: результат процесу terminal exec, тривалість, ціль, режим, код завершення та тип збою. Текст команди й робочі каталоги не включаються.

Увімкнення діагностики (без експортера)

Використовуйте це, якщо хочете, щоб події діагностики були доступні plugin-ам або користувацьким sinks:

{
  "diagnostics": {
    "enabled": true
  }
}

Прапорці діагностики (цільові журнали)

Використовуйте прапорці, щоб увімкнути додаткові, цільові журнали налагодження без підвищення logging.level. Прапорці нечутливі до регістру та підтримують wildcard-шаблони (наприклад, telegram.* або *).

{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}

Перевизначення через змінну середовища (разово):

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Примітки:

Журнали за прапорцями записуються у стандартний файл журналу (той самий, що й logging.file).
Виведення все одно редагується відповідно до logging.redactSensitive.
Повний посібник: /diagnostics/flags.

Експорт до OpenTelemetry

Діагностику можна експортувати через plugin diagnostics-otel (OTLP/HTTP). Це працює з будь-яким collector/backend OpenTelemetry, який приймає OTLP/HTTP.

{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "protocol": "http/protobuf",
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000,
      "captureContent": {
        "enabled": false,
        "inputMessages": false,
        "outputMessages": false,
        "toolInputs": false,
        "toolOutputs": false,
        "systemPrompt": false
      }
    }
  }
}