--- read_when: - Вам нужен понятный для начинающих обзор журналирования в OpenClaw - Вы хотите настроить уровни журналирования, форматы или редактирование конфиденциальных данных - Вы устраняете неполадки, и вам нужно быстро найти журналы. summary: Файловые журналы, вывод в консоль, просмотр журналов через CLI и вкладка журналов в интерфейсе управления title: Ведение журналов x-i18n: generated_at: "2026-07-13T18:17:05Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: add41e125c22ca1b2343a3a1fb1e88e94ef9c81a07c48b9eb67f4d4b2510dd08 source_path: logging.md workflow: 16 --- OpenClaw предоставляет две основные поверхности журналирования: - **Файловые журналы** (строки JSON), записываемые Gateway. - **Консольный вывод** в терминале, где запущен Gateway. Вкладка **Журналы** интерфейса управления отслеживает файловый журнал Gateway. На этой странице объясняется, где располагаются журналы, как их читать и как настраивать уровни и форматы журналирования. ## Где располагаются журналы По умолчанию Gateway ежедневно записывает циклический файл журнала: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` Дата определяется по локальному часовому поясу хоста Gateway. Если `/tmp/openclaw` небезопасен или недоступен (а также всегда в Windows), OpenClaw вместо него использует пользовательский каталог `openclaw-` в каталоге временных файлов ОС. Файлы журналов с датами удаляются через 24 часа. Каждый файл ротируется, когда следующая запись привела бы к превышению `logging.maxFileBytes` (по умолчанию: 100 МБ). OpenClaw сохраняет рядом с активным файлом до пяти нумерованных архивов, например `openclaw-YYYY-MM-DD.1.log`, и продолжает запись в новый активный журнал, не подавляя диагностические данные. Путь можно переопределить в `~/.openclaw/openclaw.json`: ```json { "logging": { "file": "/path/to/openclaw.log" } } ``` ## Как читать журналы ### CLI: отслеживание в реальном времени (рекомендуется) Отслеживайте файловый журнал Gateway через RPC: ```bash openclaw logs --follow ``` Параметры: | Флаг | По умолчанию | Поведение | | ------------------- | -------- | ------------------------------------------------------------------------------------- | | `--follow` | выкл. | Продолжать отслеживание; при отключении повторно подключаться с увеличивающейся задержкой | | `--limit ` | `200` | Максимальное количество строк за одно получение | | `--max-bytes ` | `250000` | Максимальное количество байтов для чтения за одно получение | | `--interval ` | `1000` | Интервал опроса при отслеживании | | `--json` | выкл. | JSON с разделением по строкам (одно событие в строке) | | `--plain` | выкл. | Принудительно использовать обычный текст в сеансах TTY | | `--no-color` | — | Отключить цвета ANSI | | `--utc` | выкл. | Отображать метки времени в UTC (по умолчанию используется локальное время) | | `--local-time` | выкл. | Допустимый вариант написания для режима локального времени по умолчанию; другого эффекта не имеет | | `--url` / `--token` | — | Стандартные флаги RPC Gateway | | `--timeout ` | `30000` | Время ожидания RPC Gateway | | `--expect-final` | выкл. | Флаг ожидания окончательного ответа RPC с поддержкой агента (принимается здесь через общий клиентский слой) | Режимы вывода: - **Сеансы 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 выводит краткую подсказку выполнить: ```bash openclaw doctor ``` ### Интерфейс управления (веб) Вкладка **Журналы** интерфейса управления отслеживает тот же файл с помощью `logs.tail`. Инструкции по открытию см. в разделе [Интерфейс управления](/ru/web/control-ui). ### Журналы только для каналов Чтобы отфильтровать активность каналов (WhatsApp/Telegram и т. д.), используйте: ```bash openclaw channels logs --channel whatsapp ``` По умолчанию `--channel` имеет значение `all`; также доступны `--lines ` (по умолчанию 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` Примеры: ```bash openclaw gateway openclaw gateway --verbose --ws-log compact openclaw gateway --verbose --ws-log full ``` ## Настройка журналирования Вся конфигурация журналирования находится в разделе `logging` файла `~/.openclaw/openclaw.json`. ```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 `** (например, `openclaw --log-level debug gateway run`), который для этой команды переопределяет переменную окружения. `--verbose` влияет только на консольный вывод и подробность журналов WS; он не изменяет уровни файлового журналирования. ### Целевая диагностика транспорта модели При отладке вызовов провайдера используйте целевые флаги окружения вместо повышения уровня всех журналов до `debug`: ```bash 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` и вкладка «Журналы» интерфейса управления отображают их. Без этих флагов те же диагностические данные остаются доступны на уровне `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](/ru/gateway/opentelemetry). - **Флаги диагностики** — целевые флаги отладочного журналирования, направляющие дополнительные журналы в `logging.file` без повышения `logging.level`. Флаги нечувствительны к регистру и поддерживают подстановочные знаки (`telegram.*`, `*`). Настройте их в `diagnostics.flags` или с помощью переопределяющей переменной окружения `OPENCLAW_DIAGNOSTICS=...`. Полное руководство: [Флаги диагностики](/ru/diagnostics/flags). Сведения об экспорте OTLP в коллектор см. в разделе [Экспорт OpenTelemetry](/ru/gateway/opentelemetry). ## Советы по устранению неполадок - **Gateway недоступен?** Сначала выполните `openclaw doctor`. - **Журналы пусты?** Убедитесь, что Gateway запущен и выполняет запись по пути к файлу, указанному в `logging.file`. - **Нужно больше подробностей?** Установите `logging.level` в значение `debug` или `trace` и повторите попытку. ## Связанные материалы - [Экспорт OpenTelemetry](/ru/gateway/opentelemetry) — экспорт по OTLP/HTTP, каталог метрик и интервалов, модель конфиденциальности - [Флаги диагностики](/ru/diagnostics/flags) — целевые флаги отладочного журналирования - [Внутреннее устройство журналирования Gateway](/ru/gateway/logging) — стили журналов WS, префиксы подсистем и перехват консольного вывода - [Справочник по конфигурации](/ru/gateway/configuration-reference#diagnostics) — полный справочник по полям `diagnostics.*`