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

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

• Файлові журнали (рядки JSON), які записує Gateway.
• Консольний вивід у терміналі, де працює Gateway.

Вкладка Журнали в інтерфейсі керування відстежує файловий журнал Gateway. На цій сторінці пояснено, де розташовані журнали, як їх читати та як налаштовувати рівні й формати журналювання.

Де розташовані журнали

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

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

Дата визначається за локальним часовим поясом хоста Gateway. Якщо /tmp/openclaw небезпечний або недоступний (а у Windows — завжди), OpenClaw натомість використовує каталог openclaw-<uid> для поточного користувача в каталозі тимчасових файлів ОС. Датовані файли журналів видаляються через 24 години.

Кожен файл ротують, коли наступний запис перевищив би logging.maxFileBytes (за замовчуванням: 100 МБ). OpenClaw зберігає поруч з активним файлом до п’яти нумерованих архівів, наприклад openclaw-YYYY-MM-DD.1.log, і продовжує запис у новий активний журнал замість придушення діагностичних даних.

Шлях можна перевизначити в ~/.openclaw/openclaw.json:

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

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

CLI: відстеження наживо (рекомендовано)

Відстежуйте файл журналу Gateway через RPC:

openclaw logs --follow

Параметри:

Режими виводу:

• Сеанси TTY: наочні кольорові структуровані рядки журналу.
• Сеанси без TTY: звичайний текст.

Якщо явно передати --url, CLI не застосовує автоматично облікові дані з конфігурації або середовища; укажіть --token самостійно, інакше виклик завершиться помилкою gateway url override requires explicit credentials.

У режимі JSON CLI виводить об’єкти з позначкою type:

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

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

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

openclaw doctor

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

Вкладка Журнали в інтерфейсі керування відстежує той самий файл за допомогою logs.tail. Інструкції з відкриття див. у розділі Інтерфейс керування.

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

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

openclaw channels logs --channel whatsapp

Для --channel за замовчуванням використовується all; також доступні --lines <n> (за замовчуванням 200) і --json.

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

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

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

Записи JSONL файлового журналу також містять доступні для машинної фільтрації поля верхнього рівня, якщо вони наявні:

• hostname: ім’я хоста Gateway.
• message: зведений текст повідомлення журналу для повнотекстового пошуку.
• agent_id: ідентифікатор активного агента, якщо виклик журналювання містить контекст агента.
• session_id: ідентифікатор/ключ активного сеансу, якщо виклик журналювання містить контекст сеансу.
• channel: активний канал, якщо виклик журналювання містить контекст каналу.

OpenClaw зберігає вихідні структуровані аргументи журналювання разом із цими полями, тому наявні аналізатори, які читають нумеровані ключі аргументів tslog, продовжують працювати.

Активність розмов, голосового зв’язку в реальному часі та керованих кімнат створює обмежені записи журналу життєвого циклу через той самий конвеєр файлового журналювання. Ці записи містять тип події, режим, транспорт, постачальника та показники розміру/часу, якщо вони доступні, але не містять тексту розшифрування, звукових даних, ідентифікаторів реплік, викликів і елементів постачальника.

Консольний вивід

Консольні журнали враховують TTY і форматуються для зручності читання:

• Префікси підсистем (наприклад, gateway/channels/whatsapp)
• Кольорове позначення рівнів (інформація/попередження/помилка)
• Необов’язковий компактний режим або режим JSON

Форматування консолі керується параметром logging.consoleStyle.

Журнали WebSocket Gateway

openclaw gateway також підтримує журналювання протоколу WebSocket для трафіку RPC:

• звичайний режим: лише важливі результати (помилки, помилки аналізу, повільні виклики)
• --verbose: увесь трафік запитів/відповідей
• --ws-log auto|compact|full: вибір стилю докладного відображення
• --compact: псевдонім для --ws-log compact

Приклади:

openclaw gatewayopenclaw gateway --verbose --ws-log compactopenclaw 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-.*"]  }}

Рівні журналювання

Рівні: silent, fatal, error, warn, info, debug, trace.

• logging.level: рівень файлових журналів (JSONL) (за замовчуванням: info).
• logging.consoleLevel: рівень докладності консолі.

Обидва значення можна перевизначити за допомогою змінної середовища OPENCLAW_LOG_LEVEL (наприклад, OPENCLAW_LOG_LEVEL=debug). Змінна середовища має пріоритет над файлом конфігурації, тому можна підвищити докладність для одного запуску без редагування openclaw.json. Також можна передати глобальний параметр CLI --log-level <level> (наприклад, openclaw --log-level debug gateway run), який для цієї команди перевизначає змінну середовища.

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

Цільова діагностика транспорту моделей

Під час налагодження викликів постачальника використовуйте цільові прапорці середовища замість підвищення рівня всіх журналів до debug:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gatewayOPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway

Доступні прапорці:

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1: виводити початок запиту, відповідь отримання, заголовки 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.

Метадані початку та відповіді [model-fetch] (постачальник, API, модель, стан, затримка й поля запиту, як-от метод, URL, час очікування, проксі та політика) завжди виводяться на рівні info незалежно від OPENCLAW_DEBUG_MODEL_TRANSPORT, тому базовий стан транспорту моделі видно без прапорців налагодження.

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

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

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

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

Розмір і часові показники виклику моделі

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

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

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

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

logging.consoleStyle:

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

Редагування конфіденційних даних

OpenClaw може редагувати конфіденційні токени до їх потрапляння в консольний вивід, файлові журнали, записи журналів OTLP, збережений текст розшифрування сеансу або корисне навантаження подій інструментів інтерфейсу керування (аргументи запуску інструмента, часткові/остаточні результати, похідний вивід виконання та підсумки виправлень):

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

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

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

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

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

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

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

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

Щоб експортувати дані через OTLP до збирача, див. Експорт OpenTelemetry.

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

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

Пов’язані матеріали

• Експорт OpenTelemetry — експорт через OTLP/HTTP, каталог метрик/інтервалів, модель конфіденційності
• Прапорці діагностики — цільові прапорці журналювання налагодження
• Внутрішня реалізація журналювання Gateway — стилі журналів WS, префікси підсистем і захоплення консолі
• Довідник із конфігурації — повний довідник полів diagnostics.*