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

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

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

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

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

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

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

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

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

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

По умолчанию эта команда запускает или перезапускает сеанс tmux с именем openclaw-gateway-watch-<profile> (например, openclaw-gateway-watch-main), добавляя суффикс порта, такой как openclaw-gateway-watch-dev-19001, только когда OPENCLAW_GATEWAY_PORT отличается от порта по умолчанию 18789. В интерактивных терминалах подключение выполняется автоматически; неинтерактивные оболочки, CI и вызовы выполнения агента остаются отсоединёнными и вместо этого выводят инструкции по подключению:
Панель использует tmux remain-on-exit, поэтому сведения об ошибках запуска остаются доступными для подключения или захвата вместо удаления сеанса. Повторный запуск pnpm gateway:watch заново создаёт эту панель. В панели tmux работает непосредственный наблюдатель:
Перед началом наблюдения за настроенным портом или портом по умолчанию обёртка tmux останавливает установленную службу Gateway активного профиля. Это передаёт порт наблюдателю исходного кода, не позволяя launchd, systemd или Scheduled Task повторно запустить службу и заменить его. Служба остаётся установленной; восстановите её после завершения сеанса наблюдения:
Если явно заданный --port или OPENCLAW_GATEWAY_PORT отличается от фактического порта установленной службы, обёртка оставляет службу работающей, чтобы оба экземпляра Gateway могли работать параллельно. Режим переднего плана без tmux:
Непосредственный режим не управляет установленной службой. Если она использует тот же порт, сначала выполните pnpm openclaw gateway stop. Чтобы сохранить управление через tmux, но отключить автоматическое подключение:
Профилируйте процессорное время наблюдаемого Gateway при отладке узких мест запуска или среды выполнения:
Обёртка наблюдения обрабатывает --benchmark перед запуском Gateway и записывает один файл V8 .cpuprofile при каждом завершении дочернего процесса Gateway в каталоге .artifacts/gateway-watch-profiles/. Остановите или перезапустите наблюдаемый Gateway, чтобы записать текущий профиль на диск, затем откройте его с помощью Chrome DevTools или Speedscope:
  • --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 автоматически создать конфигурацию и рабочее пространство по умолчанию, если они отсутствуют, и пропустить начальную настройку.
Рекомендуемый процесс (профиль разработки и начальная настройка для разработки):
Без глобальной установки запускайте 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, чтобы пропустить провайдеры каналов.
Процесс сброса (запуск с чистого состояния):
--dev — глобальный флаг профиля, который некоторые средства запуска перехватывают. Если его нужно указать явно, используйте форму переменной окружения:
--reset очищает конфигурацию, учётные данные, сеансы и рабочее пространство разработки (перемещая их в корзину, а не удаляя), после чего повторно создаёт стандартную среду разработки.
Если уже работает Gateway не для разработки (через launchd или systemd), сначала остановите его:

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

OpenClaw может журналировать необработанный поток ассистента до любой фильтрации или форматирования. Это лучший способ выяснить, поступают ли рассуждения как дельты обычного текста или как отдельные блоки размышлений. Включите через CLI:
Необязательное переопределение пути:
Эквивалентные переменные окружения:
Файл по умолчанию: ~/.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".

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