Ведение журналов

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 с обратной петлёй запрашивает сопряжение, закрывается во время подключения или превышает время ожидания до ответа 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: регистрировать начало запроса, ответ 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.

Метаданные начала и ответа [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: общая продолжительность вызова модели

Эти поля доступны диагностическим снимкам, хукам плагинов вызова модели, а также диапазонам и метрикам вызовов модели OTEL, когда включён экспорт диагностики.

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

logging.consoleStyle:

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

Редактирование конфиденциальных данных

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

• logging.redactSensitive: off | tools (по умолчанию: tools)
• logging.redactPatterns: список строк регулярных выражений, заменяющий набор по умолчанию для вывода в журналы и стенограммы. Для полезных данных инструментов Control UI пользовательские шаблоны применяются поверх встроенных шаблонов по умолчанию, поэтому добавление шаблона никогда не ослабляет скрытие значений, уже обнаруживаемых шаблонами по умолчанию.

Файловые журналы и стенограммы сеансов сохраняют формат JSONL, но совпадающие конфиденциальные значения маскируются до записи строки или сообщения на диск. Скрытие применяется по возможности: оно распространяется на текстовое содержимое сообщений и строки журналов, но не на каждое поле идентификатора или двоичных полезных данных.

Встроенные шаблоны по умолчанию охватывают распространённые учётные данные API и имена полей платёжных реквизитов, такие как номер карты, CVC/CVV, общий платёжный токен и платёжные учётные данные, когда они встречаются в полях JSON, параметрах URL, флагах CLI или присваиваниях.

logging.redactSensitive: "off" отключает только эту общую политику для журналов и стенограмм. OpenClaw по-прежнему скрывает полезные данные на границах безопасности, которые могут отображаться клиентам UI, включаться в пакеты поддержки, передаваться наблюдателям диагностики, показываться в запросах на подтверждение или предоставляться инструментам агента. Примеры: события вызовов инструментов Control UI, вывод sessions_history, экспорт диагностических данных для поддержки, наблюдения ошибок провайдера, отображение команды при подтверждении exec и журналы протокола 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.*