English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

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:

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

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

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

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

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 не використовують цей резервний варіант.

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

openclaw doctor

Control UI (веб)

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

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

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

openclaw channels logs --channel whatsapp

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

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

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

Записи 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

Приклади:

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; він не змінює рівні файлових журналів.

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

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

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

Записи журналу життєвого циклу розмов також надходять до журналів OTLP, коли ввімкнено експорт журналів OpenTelemetry, використовуючи ті самі обмежені атрибути, що й файлові журнали.

Розмір і таймінг виклику моделі

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

  • requestPayloadBytes: розмір у байтах UTF-8 фінального payload запиту до моделі
  • responseStreamBytes: розмір у байтах UTF-8 потокових подій відповіді моделі
  • timeToFirstByteMs: час, що минув до першої потокової події відповіді
  • durationMs: загальна тривалість виклику моделі

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

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

logging.consoleStyle:

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

Редакція

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

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

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

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

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

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

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

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

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

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

{
  diagnostics: { enabled: true },
}

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

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

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

Пов’язане