Налагодження

Допоміжні засоби налагодження потокового виведення, ітерацій Gateway і профілювання запуску.

Перевизначення конфігурації під час виконання

/debug задає перевизначення конфігурації лише на час виконання (у пам’яті, а не на диску). Типово вимкнено; увімкніть за допомогою commands.debug: true.

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

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

Виведення трасування сеансу

/trace показує рядки трасування та налагодження, якими керує Plugin, для одного сеансу без увімкнення повного докладного режиму. Використовуйте його для діагностики Plugin, наприклад налагоджувальних зведень Active Memory; для звичайного виведення стану й інструментів використовуйте /verbose.

/trace/trace on/trace off

Трасування життєвого циклу Plugin

Установіть OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1, щоб отримати поетапний розбір роботи з метаданими Plugin, виявленням, реєстром, дзеркалом середовища виконання, зміною конфігурації та оновленням. Виведення записується до 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 запускає необроблений засіб спостереження:

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

Перш ніж спостерігати за тим самим портом, зупиніть установлену службу Gateway:

pnpm openclaw gateway stop

Параметр --force засобу спостереження звільняє поточний порт прослуховування, але не вимикає службу під наглядом. Інакше служба launchd, systemd або Scheduled Task може перезапуститися й замінити Gateway під спостереженням.

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

pnpm gateway:watch:raw# абоOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

Щоб зберегти керування 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 (порти браузера та полотна зміщуються відповідно)

2. Початкове налаштування розробки (gateway --dev)

   • Записує мінімальну конфігурацію, якщо її немає (gateway.mode=local, прив’язка до 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, але циклом збирання потрібно керувати в окремому терміналі.
• Змініть args у launch.json, щоб налагоджувати інші підкоманди CLI.
• Щоб використовувати зібраний CLI для інших завдань (наприклад, dashboard --no-open, якщо сеанс налагодження створює новий токен автентифікації), запустіть його з іншого термінала: node ./openclaw.mjs або через псевдонім на кшталт alias openclaw-build="node $(pwd)/openclaw.mjs".

Пов’язані матеріали

• Усунення несправностей
• Поширені запитання