> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "logging": {
    "file": "/path/to/openclaw.log"
  }
}
```

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

### CLI: отслеживание в реальном времени (рекомендуется)

Отслеживайте файловый журнал Gateway через RPC:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw logs --follow
```

Параметры:

| Флаг | По умолчанию | Поведение |
| - | - | - |
| `--follow` | выкл. | Продолжать отслеживание; при отключении повторно подключаться с увеличивающейся задержкой |
| `--limit <n>` | `200` | Максимальное количество строк за одно получение |
| `--max-bytes <n>` | `250000` | Максимальное количество байтов для чтения за одно получение |
| `--interval <ms>` | `1000` | Интервал опроса при отслеживании |
| `--json` | выкл. | JSON с разделением по строкам (одно событие в строке) |
| `--plain` | выкл. | Принудительно использовать обычный текст в сеансах TTY |
| `--no-color` | — | Отключить цвета ANSI |
| `--utc` | выкл. | Отображать метки времени в UTC (по умолчанию используется локальное время) |
| `--local-time` | выкл. | Допустимый вариант написания для режима локального времени по умолчанию; другого эффекта не имеет |
| `--url` / `--token` | — | Стандартные флаги RPC Gateway |
| `--timeout <ms>` | `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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw doctor
```

### Интерфейс управления (веб)

Вкладка **Журналы** интерфейса управления отслеживает тот же файл с помощью `logs.tail`.
Инструкции по открытию см. в разделе [Интерфейс управления](https://docs2.openclaw.ai/ru/web/control-ui.md).

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`

Примеры:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full
```

## Настройка журналирования

Вся конфигурация журналирования находится в разделе `logging` файла `~/.openclaw/openclaw.json`.

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "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`:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](https://docs2.openclaw.ai/ru/gateway/opentelemetry.md).
* **Флаги диагностики** — целевые флаги отладочного журналирования, направляющие дополнительные журналы в
  `logging.file` без повышения `logging.level`. Флаги нечувствительны к регистру
  и поддерживают подстановочные знаки (`telegram.*`, `*`). Настройте их в `diagnostics.flags`
  или с помощью переопределяющей переменной окружения `OPENCLAW_DIAGNOSTICS=...`. Полное руководство:
  [Флаги диагностики](https://docs2.openclaw.ai/ru/diagnostics/flags.md).

Сведения об экспорте OTLP в коллектор см. в разделе [Экспорт OpenTelemetry](https://docs2.openclaw.ai/ru/gateway/opentelemetry.md).

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

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

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

* [Экспорт OpenTelemetry](https://docs2.openclaw.ai/ru/gateway/opentelemetry.md) — экспорт по OTLP/HTTP, каталог метрик и интервалов, модель конфиденциальности
* [Флаги диагностики](https://docs2.openclaw.ai/ru/diagnostics/flags.md) — целевые флаги отладочного журналирования
* [Внутреннее устройство журналирования Gateway](https://docs2.openclaw.ai/ru/gateway/logging.md) — стили журналов WS, префиксы подсистем и перехват консольного вывода
* [Справочник по конфигурации](https://docs2.openclaw.ai/ru/gateway/configuration-reference.md#diagnostics) — полный справочник по полям `diagnostics.*`