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

Помічники налагодження для потокового виводу, особливо коли провайдер змішує міркування зі звичайним текстом.

Перевизначення налагодження під час виконання

Використовуйте /debug у чаті, щоб установити лише runtime перевизначення конфігурації (у пам'яті, не на диску). /debug вимкнено за замовчуванням; увімкніть за допомогою commands.debug: true. Це зручно, коли потрібно перемикати неочевидні налаштування без редагування openclaw.json.

Приклади:

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

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

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

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

Приклади:

/trace/trace on/trace off

Використовуйте /trace для діагностики Plugin, наприклад налагоджувальних підсумків Active Memory. Продовжуйте використовувати /verbose для звичайного докладного виводу стану/інструментів, а /debug — для лише runtime перевизначень конфігурації.

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

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

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

Запускач вихідного коду додає прапорці CPU-профілю Node і записує .cpuprofile для команди. Використовуйте це перед додаванням тимчасової інструментації в код команд.

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

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch залишає цей прапорець вимкненим за замовчуванням для дочірнього процесу Gateway під наглядом. Задайте OPENCLAW_TRACE_SYNC_IO=1, коли явно хочете отримати вивід трасування синхронного вводу-виводу Node у режимі спостереження.

Режим спостереження Gateway

Для швидких ітерацій запускайте gateway під файловим спостерігачем:

pnpm gateway:watch

За замовчуванням це запускає або перезапускає сеанс tmux з назвою openclaw-gateway-watch-main (або варіант для профілю/порту, наприклад openclaw-gateway-watch-dev-19001) і автоматично приєднується з інтерактивних терміналів. Неінтерактивні оболонки, CI та виклики виконання агентів залишаються від'єднаними й натомість друкують інструкції для приєднання. За потреби приєднайтеся вручну:

tmux attach -t openclaw-gateway-watch-main

Панель tmux запускає сирий спостерігач:

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

Використовуйте режим переднього плану, коли tmux не потрібен:

pnpm gateway:watch:raw# orOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

Вимкніть автоматичне приєднання, зберігаючи керування tmux:

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

Профілюйте CPU-час Gateway під спостереженням під час налагодження вузьких місць запуску/runtime:

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, коли явно хочете і CPU-профілі, і трасування стеків синхронного вводу-виводу Node. У режимі бенчмарку ці блоки трасування записуються в gateway-watch-output.log у каталозі бенчмарку та фільтруються з панелі термінала; звичайні журнали Gateway залишаються видимими.

Обгортка tmux переносить у панель поширені несекретні селектори runtime, такі як 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, коли хочете побачити початкову помилку запуску без dev-only ремонтного проходу. Керована панель tmux також за замовчуванням використовує кольорові журнали Gateway для читабельності; задайте FORCE_COLOR=0 під час запуску pnpm gateway:watch, щоб вимкнути ANSI-вивід.

Спостерігач перезапускається при зміні файлів, релевантних для збірки, у src/, вихідних файлів розширень, метаданих розширень package.json і openclaw.plugin.json, tsconfig.json, package.json і tsdown.config.ts. Зміни метаданих розширень перезапускають gateway без примусового перебудування tsdown; зміни вихідного коду й конфігурації все ще спершу перебудовують dist.

Додавайте будь-які прапорці CLI gateway після gateway:watch, і вони передаватимуться далі під час кожного перезапуску. Повторний запуск тієї самої команди спостереження перестворює іменовану панель tmux, а сирий спостерігач усе ще тримає своє блокування єдиного спостерігача, тому дублікати батьківських процесів спостерігача замінюються, а не накопичуються.

Dev-профіль + dev-gateway (--dev)

Використовуйте dev-профіль, щоб ізолювати стан і запустити безпечне одноразове середовище для налагодження. Є два прапорці --dev:

• Глобальний --dev (профіль): ізолює стан у ~/.openclaw-dev і задає порт gateway за замовчуванням на 19001 (похідні порти зміщуються разом із ним).
• gateway --dev: каже Gateway автоматично створити типову конфігурацію + робочу область, якщо їх немає (і пропустити BOOTSTRAP.md).

Рекомендований процес (dev-профіль + dev-завантаження):

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 (browser/canvas зміщуються відповідно)

2. Dev-завантаження (gateway --dev)

   • Записує мінімальну конфігурацію, якщо її немає (gateway.mode=local, прив'язка до local loopback).
   • Задає agent.workspace на dev-робочу область.
   • Задає agent.skipBootstrap=true (без BOOTSTRAP.md).
   • Засіває файли робочої області, якщо їх немає: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md.
   • Типова ідентичність: C3-PO (протокольний дроїд).
   • Пропускає провайдерів каналів у dev-режимі (OPENCLAW_SKIP_CHANNELS=1).

Процес скидання (свіжий старт):

pnpm gateway:dev:reset

--reset стирає конфігурацію, облікові дані, сеанси й dev-робочу область (за допомогою trash, а не rm), потім відтворює типове dev-середовище.

Сире журналювання потоку (OpenClaw)

OpenClaw може журналювати сирий потік асистента до будь-якого фільтрування/форматування. Це найкращий спосіб побачити, чи міркування надходять як звичайні текстові дельти (або як окремі блоки thinking).

Увімкніть це через 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

Журналювання сирих OpenAI-сумісних фрагментів

Щоб захопити сирі OpenAI-сумісні фрагменти до їх парсингу в блоки, увімкніть журналювання транспорту:

OPENCLAW_RAW_STREAM=1

Необов'язковий шлях:

OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-openai-completions.jsonl

Типовий файл:

~/.openclaw/logs/raw-openai-completions.jsonl

Нотатки щодо безпеки

• Сирі журнали потоків можуть містити повні промпти, вивід інструментів і дані користувача.
• Зберігайте журнали локально й видаляйте їх після налагодження.
• Якщо ділитеся журналами, спершу вилучіть секрети та персональні дані.

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

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

1. Перезібрати й налагодити Gateway - налагоджує службу Gateway після створення нової збірки
2. Налагодити Gateway - налагоджує службу Gateway із уже наявної збірки

Налаштування

Типова конфігурація Перезібрати й налагодити Gateway є повністю готовою: вона автоматично видалить папку /dist і перебудує проєкт з увімкненим налагодженням:

1. Відкрийте панель Run and Debug на Activity Bar або натисніть Ctrl+Shift+D
2. В IDE переконайтеся, що в розкривному списку конфігурацій вибрано Перезібрати й налагодити 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. В IDE виберіть опцію Налагодити Gateway у розкривному списку конфігурацій Run and Debug, а потім натисніть кнопку Start Debugging

Тепер можна встановлювати точки зупину у вихідних файлах TypeScript (каталог src/), і налагоджувач коректно зіставлятиме точки зупину зі скомпільованим JavaScript через карти вихідного коду. Ви зможете перевіряти змінні, покроково проходити код і переглядати стеки викликів, як очікується.

Нотатки

• Якщо використовується опція "Перезібрати й налагодити Gateway" - щоразу під час запуску налагоджувача вона повністю видалятиме папку /dist і виконуватиме повний pnpm build з увімкненими картами вихідного коду перед запуском Gateway
• Якщо використовується опція "Налагодити Gateway" - сеанси налагодження можна запускати й зупиняти будь-коли без впливу на папку /dist, але потрібно використовувати окремий процес термінала, щоб і ввімкнути налагодження, і керувати циклом збірки
• Змініть параметри launch.json для args, щоб налагоджувати інші частини проєкту
• Якщо потрібно використовувати зібраний CLI OpenClaw для інших завдань (тобто dashboard --no-open, якщо ваш сеанс налагодження створює новий токен автентифікації), його можна виконати в іншому терміналі як node ./openclaw.mjs або створити псевдонім оболонки на кшталт alias openclaw-build="node $(pwd)/openclaw.mjs"

Пов'язане

• Усунення неполадок
• Поширені запитання