Отладка

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

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

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

/debug show/debug set messages.responsePrefix="[openclaw]"/debug unset messages.responsePrefix/debug reset

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

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

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

/trace/trace on/trace off

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

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

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

[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 и команд

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

pnpm test:startup:bench:smokepnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

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

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

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

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

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

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

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

pnpm gateway:watch

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

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 работает непосредственный наблюдатель:

node scripts/watch-node.mjs gateway --force

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

pnpm openclaw gateway start

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

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

pnpm gateway:watch:raw# илиOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

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

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

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

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

pnpm gateway:watch --benchmark

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

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 автоматически создать конфигурацию и рабочее пространство по умолчанию, если они отсутствуют, и пропустить начальную настройку.

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

pnpm gateway:devOPENCLAW_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, чтобы пропустить провайдеры каналов.

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

pnpm gateway:dev:reset

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

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

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

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

pnpm gateway:watch --raw-stream

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

pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl

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

OPENCLAW_RAW_STREAM=1OPENCLAW_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".

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

• Устранение неполадок
• Часто задаваемые вопросы