> ## 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.

# Отладка

Вспомогательные средства отладки потокового вывода, итераций Gateway и профилирования запуска.

## Переопределения конфигурации среды выполнения для отладки

`/debug` задаёт переопределения конфигурации **только для среды выполнения** (в памяти, не на диске). По умолчанию отключено; включите с помощью `commands.debug: true`.

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/debug show
/debug set messages.responsePrefix="[openclaw]"
/debug unset messages.responsePrefix
/debug reset
```

`/debug reset` удаляет все переопределения и возвращает конфигурацию с диска.

## Вывод трассировки сеанса

`/trace` показывает принадлежащие плагину строки трассировки и отладки для одного сеанса без включения полного подробного режима. Используйте эту команду для диагностики плагинов, например сводок отладки Active Memory; для обычного вывода состояния и инструментов используйте `/verbose`.

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/trace
/trace on
/trace off
```

## Трассировка жизненного цикла плагина

Задайте `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`, чтобы получить поэтапную разбивку работы с метаданными плагинов, обнаружением, реестром, зеркалом среды выполнения, изменением конфигурации и обновлением. Вывод записывается в stderr, поэтому вывод команд в формате JSON остаётся пригодным для разбора.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
```

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"
[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"
```

Используйте это средство, прежде чем обращаться к профилировщику ЦП. При работе из исходного дерева измеряйте собранную среду выполнения с помощью `node dist/entry.js ...` после `pnpm build`; `pnpm openclaw ...` также измеряет накладные расходы средства запуска из исходного кода.

## Профилирование запуска CLI и команд

Включённые в репозиторий тесты производительности запуска:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm test:startup:bench:smoke
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
```

Для разового профилирования через обычное средство запуска из исходного кода задайте `OPENCLAW_RUN_NODE_CPU_PROF_DIR`:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status
```

Средство запуска из исходного кода добавляет флаги профилирования ЦП Node и записывает `.cpuprofile` для команды. Используйте это средство, прежде чем добавлять временное инструментирование в код команды.

Для зависаний при запуске, похожих на синхронную работу файловой системы или загрузчика модулей, добавьте флаг трассировки синхронного ввода-вывода Node через средство запуска из исходного кода:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force
```

`pnpm gateway:watch` по умолчанию оставляет этот флаг отключённым для дочернего процесса Gateway в режиме наблюдения; задайте `OPENCLAW_TRACE_SYNC_IO=1`, если хотите получать вывод трассировки синхронного ввода-вывода и в режиме наблюдения.

## Режим наблюдения Gateway

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch
```

По умолчанию эта команда запускает или перезапускает сеанс tmux с именем `openclaw-gateway-watch-<profile>` (например, `openclaw-gateway-watch-main`), добавляя суффикс порта, такой как `openclaw-gateway-watch-dev-19001`, только когда `OPENCLAW_GATEWAY_PORT` отличается от порта по умолчанию `18789`. В интерактивных терминалах подключение выполняется автоматически; неинтерактивные оболочки, CI и вызовы выполнения агента остаются отсоединёнными и вместо этого выводят инструкции по подключению:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
tmux attach -t openclaw-gateway-watch-main
# Просмотреть недавний вывод без подключения
tmux capture-pane -ep -t openclaw-gateway-watch-main -S -200
```

Панель использует tmux `remain-on-exit`, поэтому сведения об ошибках запуска остаются доступными для подключения или захвата вместо удаления сеанса. Повторный запуск `pnpm gateway:watch` заново создаёт эту панель.

В панели tmux работает непосредственный наблюдатель:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
node scripts/watch-node.mjs gateway --force
```

Перед началом наблюдения за настроенным портом или портом по умолчанию обёртка tmux останавливает установленную службу Gateway активного профиля. Это передаёт порт наблюдателю исходного кода, не позволяя launchd, systemd или Scheduled Task повторно запустить службу и заменить его. Служба остаётся установленной; восстановите её после завершения сеанса наблюдения:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm openclaw gateway start
```

Если явно заданный `--port` или `OPENCLAW_GATEWAY_PORT` отличается от фактического порта установленной службы, обёртка оставляет службу работающей, чтобы оба экземпляра Gateway могли работать параллельно.

Режим переднего плана без tmux:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch:raw
# или
OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
```

Непосредственный режим не управляет установленной службой. Если она использует тот же порт, сначала выполните `pnpm openclaw gateway stop`.

Чтобы сохранить управление через tmux, но отключить автоматическое подключение:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
```

Профилируйте процессорное время наблюдаемого Gateway при отладке узких мест запуска или среды выполнения:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch --benchmark
```

Обёртка наблюдения обрабатывает `--benchmark` перед запуском Gateway и записывает один файл V8 `.cpuprofile` при каждом завершении дочернего процесса Gateway в каталоге `.artifacts/gateway-watch-profiles/`. Остановите или перезапустите наблюдаемый Gateway, чтобы записать текущий профиль на диск, затем откройте его с помощью Chrome DevTools или Speedscope:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
```

* `--benchmark-dir <path>`: записывать профили в другое место.
* `--benchmark-no-force`: пропустить стандартную очистку порта `--force` и немедленно завершиться с ошибкой, если порт Gateway уже используется.

Режим тестирования производительности по умолчанию подавляет избыточную трассировку синхронного ввода-вывода. Задайте `OPENCLAW_TRACE_SYNC_IO=1` вместе с `--benchmark`, чтобы получать и профили ЦП, и трассировки стека синхронного ввода-вывода; в режиме тестирования производительности эти блоки трассировки записываются в `gateway-watch-output.log` в каталоге тестирования производительности и отфильтровываются из панели терминала, а обычные журналы Gateway остаются видимыми.

Обёртка tmux передаёт в панель распространённые несекретные селекторы среды выполнения, включая `OPENCLAW_PROFILE`, `OPENCLAW_CONFIG_PATH`, `OPENCLAW_STATE_DIR`, `OPENCLAW_GATEWAY_PORT` и `OPENCLAW_SKIP_CHANNELS`. Храните учётные данные провайдера в обычном профиле или конфигурации либо используйте непосредственный режим переднего плана для разовых временных секретов.

Если наблюдаемый Gateway завершается во время запуска, наблюдатель один раз выполняет `openclaw doctor --fix --non-interactive` и перезапускает дочерний процесс Gateway. Задайте `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0`, чтобы увидеть исходную ошибку запуска без предназначенного только для разработки этапа восстановления.

Управляемая панель tmux по умолчанию использует цветные журналы Gateway; задайте `FORCE_COLOR=0` при запуске `pnpm gateway:watch`, чтобы отключить вывод ANSI.

Наблюдатель перезапускается при изменении влияющих на сборку файлов в `src/`, исходных файлов расширений, метаданных расширений `package.json` и `openclaw.plugin.json`, а также `tsconfig.json`, `package.json` и `tsdown.config.ts`. Изменения метаданных расширений перезапускают Gateway без принудительной пересборки; изменения исходного кода и конфигурации по-прежнему сначала пересобирают `dist`.

Добавьте флаги CLI Gateway после `gateway:watch`, и они будут передаваться при каждом перезапуске. Повторный запуск той же команды наблюдения заново создаёт именованную панель tmux; непосредственный наблюдатель использует блокировку единственного экземпляра, поэтому дублирующиеся родительские процессы наблюдателя заменяются, а не накапливаются.

## Профиль разработки и Gateway для разработки (--dev)

Два **отдельных** флага `--dev`:

* **Глобальный `--dev` (профиль):** изолирует состояние в `~/.openclaw-dev` и задаёт для порта Gateway значение по умолчанию `19001` (производные порты смещаются вместе с ним).
* **`gateway --dev`:** указывает Gateway автоматически создать конфигурацию и рабочее пространство по умолчанию, если они отсутствуют, и пропустить начальную настройку.

Рекомендуемый процесс (профиль разработки и начальная настройка для разработки):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui
```

Без глобальной установки запускайте CLI через `pnpm openclaw ...`.

Что при этом происходит:

1. **Изоляция профиля** (глобальный `--dev`)
   * `OPENCLAW_PROFILE=dev`
   * `OPENCLAW_STATE_DIR=~/.openclaw-dev`
   * `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
   * `OPENCLAW_GATEWAY_PORT=19001` (порты браузера и canvas смещаются соответствующим образом)

2. **Начальная настройка для разработки** (`gateway --dev`)
   * Записывает минимальную конфигурацию, если она отсутствует (`gateway.mode=local`, привязка к loopback-интерфейсу).
   * Задаёт для `agents.defaults.workspace` рабочее пространство разработки и `agents.defaults.skipBootstrap=true`.
   * Создаёт отсутствующие файлы рабочего пространства: `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`.
   * Идентичность по умолчанию: **C3-PO** (протокольный дроид).
   * `pnpm gateway:dev` также задаёт `OPENCLAW_SKIP_CHANNELS=1`, чтобы пропустить провайдеры каналов.

Процесс сброса (запуск с чистого состояния):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:dev:reset
```

> [!NOTE]
>
> `--dev` — **глобальный** флаг профиля, который некоторые средства запуска перехватывают. Если его нужно указать явно, используйте форму переменной окружения:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
> ```

`--reset` очищает конфигурацию, учётные данные, сеансы и рабочее пространство разработки (перемещая их в корзину, а не удаляя), после чего повторно создаёт стандартную среду разработки.

> [!TIP]
>
> Если уже работает Gateway не для разработки (через launchd или systemd), сначала остановите его:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> openclaw gateway stop
> ```

## Журналирование необработанного потока

OpenClaw может журналировать **необработанный поток ассистента** до любой фильтрации или форматирования. Это лучший способ выяснить, поступают ли рассуждения как дельты обычного текста или как отдельные блоки размышлений.

Включите через CLI:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch --raw-stream
```

Необязательное переопределение пути:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
```

Эквивалентные переменные окружения:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
```

Файл по умолчанию: `~/.openclaw/logs/raw-stream.jsonl`

## Примечания по безопасности

* Журналы необработанного потока могут содержать полные запросы, вывод инструментов и пользовательские данные.
* Храните журналы локально и удаляйте их после завершения отладки.
* Перед передачей журналов удалите из них секреты и персональные данные.

## Отладка в VSCode

Карты исходного кода обязательны, поскольку при сборке к именам создаваемых файлов добавляются хеши. Включённая конфигурация `launch.json` предназначена для службы Gateway:

1. **Rebuild and Debug Gateway** — удаляет `/dist` и выполняет пересборку с включённой отладкой перед запуском Gateway.
2. **Debug Gateway** — отлаживает существующую сборку, не изменяя `/dist`.

### Настройка

1. Откройте **Run and Debug** (на панели действий или с помощью `Ctrl`+`Shift`+`D`).
2. Выберите **Rebuild and Debug Gateway** и нажмите **Start Debugging**.

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

1. Включите карты исходного кода в терминале:
   * **Linux/macOS**: `export OUTPUT_SOURCE_MAPS=1`
   * **Windows (PowerShell)**: `$env:OUTPUT_SOURCE_MAPS="1"`
   * **Windows (CMD)**: `set OUTPUT_SOURCE_MAPS=1`
2. Выполните пересборку: `pnpm clean:dist && pnpm build`
3. Выберите **Debug Gateway** и нажмите **Start Debugging**.

Устанавливайте точки останова в файлах TypeScript `src/`; отладчик сопоставит их со скомпилированным JavaScript с помощью карт исходного кода.

### Примечания

* **Rebuild and Debug Gateway** удаляет `/dist` и при каждом запуске выполняет полную команду `pnpm build` с картами исходного кода.
* **Debug Gateway** можно запускать и останавливать, не затрагивая `/dist`, но циклом сборки необходимо управлять в отдельном терминале.
* Измените `launch.json` `args`, чтобы отлаживать другие подкоманды CLI.
* Чтобы использовать собранный CLI для других задач (например, `dashboard --no-open`, если сеанс отладки создаёт новый токен аутентификации), запустите его из другого терминала: `node ./openclaw.mjs` или через псевдоним, такой как `alias openclaw-build="node $(pwd)/openclaw.mjs"`.

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

* [Устранение неполадок](https://docs2.openclaw.ai/ru/help/troubleshooting.md)
* [Часто задаваемые вопросы](https://docs2.openclaw.ai/ru/help/faq.md)