--- read_when: - Вам необходимо проверять необработанный вывод модели на утечку рассуждений - Вы хотите запустить Gateway в режиме наблюдения во время разработки - Вам нужен воспроизводимый процесс отладки summary: 'Инструменты отладки: режим наблюдения, необработанные потоки модели и трассировка утечки рассуждений' title: Отладка x-i18n: generated_at: "2026-07-13T19:51:24Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: b34d2a09b6c669e8362dcc346a5f7343e262028907f68b2313ed597d8784534f source_path: help/debugging.md workflow: 16 --- Вспомогательные средства отладки потокового вывода, итераций Gateway и профилирования запуска. ## Переопределения конфигурации среды выполнения для отладки `/debug` задаёт переопределения конфигурации **только для среды выполнения** (в памяти, не на диске). По умолчанию отключено; включите с помощью `commands.debug: true`. ```text /debug show /debug set messages.responsePrefix="[openclaw]" /debug unset messages.responsePrefix /debug reset ``` `/debug reset` удаляет все переопределения и возвращает конфигурацию с диска. ## Вывод трассировки сеанса `/trace` показывает принадлежащие плагину строки трассировки и отладки для одного сеанса без включения полного подробного режима. Используйте эту команду для диагностики плагинов, например сводок отладки Active Memory; для обычного вывода состояния и инструментов используйте `/verbose`. ```text /trace /trace on /trace off ``` ## Трассировка жизненного цикла плагина Задайте `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`, чтобы получить поэтапную разбивку работы с метаданными плагинов, обнаружением, реестром, зеркалом среды выполнения, изменением конфигурации и обновлением. Вывод записывается в stderr, поэтому вывод команд в формате JSON остаётся пригодным для разбора. ```bash OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force ``` ```text [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 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 OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status ``` Средство запуска из исходного кода добавляет флаги профилирования ЦП Node и записывает `.cpuprofile` для команды. Используйте это средство, прежде чем добавлять временное инструментирование в код команды. Для зависаний при запуске, похожих на синхронную работу файловой системы или загрузчика модулей, добавьте флаг трассировки синхронного ввода-вывода Node через средство запуска из исходного кода: ```bash OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force ``` `pnpm gateway:watch` по умолчанию оставляет этот флаг отключённым для дочернего процесса Gateway в режиме наблюдения; задайте `OPENCLAW_TRACE_SYNC_IO=1`, если хотите получать вывод трассировки синхронного ввода-вывода и в режиме наблюдения. ## Режим наблюдения Gateway ```bash pnpm gateway:watch ``` По умолчанию эта команда запускает или перезапускает сеанс tmux с именем `openclaw-gateway-watch-` (например, `openclaw-gateway-watch-main`), добавляя суффикс порта, такой как `openclaw-gateway-watch-dev-19001`, только когда `OPENCLAW_GATEWAY_PORT` отличается от порта по умолчанию `18789`. В интерактивных терминалах подключение выполняется автоматически; неинтерактивные оболочки, CI и вызовы выполнения агента остаются отсоединёнными и вместо этого выводят инструкции по подключению: ```bash 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 node scripts/watch-node.mjs gateway --force ``` Перед началом наблюдения за настроенным портом или портом по умолчанию обёртка tmux останавливает установленную службу Gateway активного профиля. Это передаёт порт наблюдателю исходного кода, не позволяя launchd, systemd или Scheduled Task повторно запустить службу и заменить его. Служба остаётся установленной; восстановите её после завершения сеанса наблюдения: ```bash pnpm openclaw gateway start ``` Если явно заданный `--port` или `OPENCLAW_GATEWAY_PORT` отличается от фактического порта установленной службы, обёртка оставляет службу работающей, чтобы оба экземпляра Gateway могли работать параллельно. Режим переднего плана без tmux: ```bash pnpm gateway:watch:raw # или OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch ``` Непосредственный режим не управляет установленной службой. Если она использует тот же порт, сначала выполните `pnpm openclaw gateway stop`. Чтобы сохранить управление через tmux, но отключить автоматическое подключение: ```bash OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch ``` Профилируйте процессорное время наблюдаемого Gateway при отладке узких мест запуска или среды выполнения: ```bash pnpm gateway:watch --benchmark ``` Обёртка наблюдения обрабатывает `--benchmark` перед запуском Gateway и записывает один файл V8 `.cpuprofile` при каждом завершении дочернего процесса Gateway в каталоге `.artifacts/gateway-watch-profiles/`. Остановите или перезапустите наблюдаемый Gateway, чтобы записать текущий профиль на диск, затем откройте его с помощью Chrome DevTools или Speedscope: ```bash npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile ``` - `--benchmark-dir `: записывать профили в другое место. - `--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 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 pnpm gateway:dev:reset ``` `--dev` — **глобальный** флаг профиля, который некоторые средства запуска перехватывают. Если его нужно указать явно, используйте форму переменной окружения: ```bash OPENCLAW_PROFILE=dev openclaw gateway --dev --reset ``` `--reset` очищает конфигурацию, учётные данные, сеансы и рабочее пространство разработки (перемещая их в корзину, а не удаляя), после чего повторно создаёт стандартную среду разработки. Если уже работает Gateway не для разработки (через launchd или systemd), сначала остановите его: ```bash openclaw gateway stop ``` ## Журналирование необработанного потока OpenClaw может журналировать **необработанный поток ассистента** до любой фильтрации или форматирования. Это лучший способ выяснить, поступают ли рассуждения как дельты обычного текста или как отдельные блоки размышлений. Включите через CLI: ```bash pnpm gateway:watch --raw-stream ``` Необязательное переопределение пути: ```bash pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl ``` Эквивалентные переменные окружения: ```bash 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"`. ## Связанные материалы - [Устранение неполадок](/ru/help/troubleshooting) - [Часто задаваемые вопросы](/ru/help/faq)