Перейти к основному содержанию
OpenClaw имеет две основные поверхности журналирования:
  • Файловые журналы (строки JSON), записываемые Gateway.
  • Консольный вывод, отображаемый в терминалах и UI отладки Gateway.
Вкладка Журналы в 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 не используют этот резервный вариант. openclaw logs --follow работает строже: в Linux он использует активный пользовательский systemd-журнал Gateway по PID, когда доступен, а в остальных случаях продолжает повторять попытки подключения к живому Gateway вместо отслеживания потенциально устаревшего соседнего файла. Если Gateway недоступен, CLI выводит короткую подсказку запустить: 
openclaw doctor

​
Control UI (web)

Вкладка Журналы в Control UI отслеживает тот же файл с помощью logs.tail. См. Control UI, чтобы узнать, как его открыть.

​
Журналы только каналов

Чтобы отфильтровать активность каналов (WhatsApp/Telegram/и т. д.), используйте: 
openclaw channels logs --channel whatsapp

​
Форматы журналов

​
Файловые журналы (JSONL)

Каждая строка в файле журнала является объектом JSON. CLI и Control UI разбирают эти записи для отображения структурированного вывода (время, уровень, подсистема, сообщение). Записи JSONL файлового журнала также включают машино-фильтруемые поля верхнего уровня, когда они доступны:
  • hostname: имя хоста gateway.
  • message: развернутый текст сообщения журнала для полнотекстового поиска.
  • agent_id: id активного агента, когда вызов журналирования несет контекст агента.
  • session_id: id/ключ активного сеанса, когда вызов журналирования несет контекст сеанса.
  • channel: активный канал, когда вызов журналирования несет контекст канала.
OpenClaw сохраняет исходные структурированные аргументы журнала рядом с этими полями, так что существующие парсеры, читающие пронумерованные ключи аргументов tslog, продолжают работать. Активность разговоров, голосовой связи в реальном времени и управляемых комнат выпускает ограниченные записи журнала жизненного цикла через тот же конвейер файлового журналирования. Эти записи включают тип события, режим, транспорт, провайдера, а также измерения размера/времени, когда они доступны, но не включают текст транскрипта, аудио-полезные нагрузки, id ходов, id вызовов и id элементов провайдера.

​
Консольный вывод

Консольные журналы учитывают 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; он не меняет уровни файловых журналов.

​
Целевая диагностика транспорта модели

При отладке вызовов провайдера используйте целевые флаги окружения вместо повышения всех журналов до debug: 
OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_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 и вкладка Журналы в Control UI их показывают. Без флагов та же диагностика остается доступной на уровне 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, stdout JSONL или оба приемника.

​
Размер и время вызова модели

Диагностика вызовов модели записывает ограниченные измерения запроса/ответа без захвата сырого содержимого промпта или ответа:
  • requestPayloadBytes: размер финальной полезной нагрузки запроса модели в байтах UTF-8
  • responseStreamBytes: размер в байтах UTF-8 полезных нагрузок потоковых фрагментов ответа модели. Высокочастотный текст, reasoning и delta-события вызовов инструментов учитывают только инкрементальные байты delta вместо полных снимков partial.
  • timeToFirstByteMs: прошедшее время до первого события потокового ответа
  • durationMs: общая длительность вызова модели
Эти поля доступны диагностическим снимкам, Plugin hooks вызовов модели и спанам/метрикам вызовов модели OTEL, когда экспорт диагностики включен.

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

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

​
Редакция секретов

OpenClaw может редактировать чувствительные токены до того, как они попадут в консольный вывод, файловые журналы, записи журналов OTLP, сохраненный текст транскрипта сеанса или полезные нагрузки событий инструментов Control UI (аргументы запуска инструмента, частичные/финальные полезные нагрузки результата, производный вывод exec и сводки патчей):
  • logging.redactSensitive: off | tools (по умолчанию: tools)
  • logging.redactPatterns: список строк regex для переопределения набора по умолчанию. Пользовательские шаблоны применяются поверх встроенных значений по умолчанию для полезных нагрузок инструментов Control UI, поэтому добавление шаблона никогда не ослабляет редакцию значений, уже захватываемых значениями по умолчанию.
Файловые журналы и транскрипты сеансов остаются JSONL, но совпадающие секретные значения маскируются до записи строки или сообщения на диск. Редакция выполняется по мере возможности: она применяется к текстовому содержимому сообщений и строкам журнала, но не к каждому идентификатору или полю бинарной полезной нагрузки. Встроенные значения по умолчанию покрывают распространенные учетные данные API и имена полей платежных учетных данных, такие как номер карты, CVC/CVV, общий платежный токен и платежные учетные данные, когда они встречаются как поля JSON, параметры URL, флаги CLI или присваивания. logging.redactSensitive: "off" отключает только эту общую политику журналов/транскриптов. OpenClaw по-прежнему редактирует полезные нагрузки на границах безопасности, которые могут показываться клиентам UI, пакетам поддержки, наблюдателям диагностики, запросам одобрения или инструментам агента. Примеры включают события вызовов инструментов Control UI, вывод sessions_history, экспорты диагностики для поддержки, наблюдения ошибок провайдера, отображение команды одобрения exec и журналы протокола WebSocket Gateway. Пользовательские logging.redactPatterns по-прежнему могут добавлять проектно-специфичные шаблоны на этих поверхностях.

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

Диагностика — это структурированные, машиночитаемые события для запусков моделей и телеметрии потока сообщений (webhooks, очереди, состояние сеанса). Они не заменяют журналы — они питают метрики, трассировки и экспортеры. События выпускаются внутри процесса независимо от того, экспортируете вы их или нет. Две смежные поверхности:
  • Экспорт OpenTelemetry — отправка метрик, трассировок и журналов через OTLP/HTTP в любой OpenTelemetry-совместимый collector или backend (Grafana, Datadog, Honeycomb, New Relic, Tempo и т. д.). Полная конфигурация, каталог сигналов, имена метрик/спанов, переменные окружения и модель приватности находятся на отдельной странице: Экспорт OpenTelemetry.
  • Флаги диагностики — целевые флаги отладочного журналирования, которые направляют дополнительные журналы в logging.file без повышения logging.level. Флаги нечувствительны к регистру и поддерживают подстановочные знаки (telegram.*, *). Настройте в diagnostics.flags или через переопределение окружения OPENCLAW_DIAGNOSTICS=.... Полное руководство: Флаги диагностики.
Чтобы включить диагностические события для plugins или пользовательских приемников без экспорта OTLP: 
{
  diagnostics: { enabled: true },
}
Для экспорта OTLP в сборщик см. экспорт OpenTelemetry.

​
Советы по устранению неполадок

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

​
Связанные материалы