---
read_when:
    - Вам нужен удобный для новичков обзор журналирования в OpenClaw
    - Вы хотите настроить уровни журналирования, форматы или редактирование чувствительных данных
    - Вы устраняете неполадки и вам нужно быстро найти журналы
summary: Файловые журналы, вывод консоли, отслеживание CLI и вкладка журналов в Control UI
title: Ведение журнала
x-i18n:
    generated_at: "2026-06-28T23:08:53Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: caf2780dfeeaf29f4ee94429894a03422b211a4414e63062642d1134f38b6b3f
    source_path: logging.md
    workflow: 16
---

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`:

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

## Как читать журналы

### CLI: live tail (рекомендуется)

Используйте CLI, чтобы отслеживать файл журнала gateway через RPC:

```bash
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 выводит короткую подсказку запустить:

```bash
openclaw doctor
```

### Control UI (web)

Вкладка **Журналы** в Control UI отслеживает тот же файл с помощью `logs.tail`.
См. [Control UI](/ru/web/control-ui), чтобы узнать, как его открыть.

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

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

```bash
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`

Примеры:

```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-.*"]
  }
}
```

### Уровни журналирования

- `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`:

```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`
и вкладка Журналы в 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](/ru/gateway/opentelemetry).
- **Флаги диагностики** — целевые флаги отладочного журналирования, которые направляют дополнительные журналы в
  `logging.file` без повышения `logging.level`. Флаги нечувствительны к регистру
  и поддерживают подстановочные знаки (`telegram.*`, `*`). Настройте в `diagnostics.flags`
  или через переопределение окружения `OPENCLAW_DIAGNOSTICS=...`. Полное руководство:
  [Флаги диагностики](/ru/diagnostics/flags).

Чтобы включить диагностические события для plugins или пользовательских приемников без экспорта OTLP:

```json5
{
  diagnostics: { enabled: true },
}
```

Для экспорта 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.*`