--- read_when: - Вам потрібно перевірити сирий вивід моделі на витік міркувань - Ви хочете запускати Gateway у режимі спостереження під час ітеративної роботи - Вам потрібен повторюваний робочий процес налагодження summary: 'Інструменти налагодження: режим спостереження, необроблені потоки моделі та трасування витоку міркувань' title: Налагодження x-i18n: generated_at: "2026-06-27T17:38:00Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: f643862e3d88801acabc98c72ac037dc582c2d44da339715ad70d169ca0819fe source_path: help/debugging.md workflow: 16 --- Помічники налагодження для потокового виводу, особливо коли провайдер змішує міркування зі звичайним текстом. ## Перевизначення налагодження під час виконання Використовуйте `/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 рядки трасування/налагодження в одному сеансі без увімкнення повного докладного режиму. Приклади: ```text /trace /trace on /trace off ``` Використовуйте `/trace` для діагностики Plugin, наприклад налагоджувальних підсумків Active Memory. Продовжуйте використовувати `/verbose` для звичайного докладного виводу стану/інструментів, а `/debug` — для лише runtime перевизначень конфігурації. ## Трасування життєвого циклу Plugin Використовуйте `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`, коли команди життєвого циклу Plugin здаються повільними й потрібна вбудована розбивка фаз для метаданих Plugin, виявлення, реєстру, дзеркала runtime, зміни конфігурації та оновлення. Трасування вмикається явно й пише в 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" ``` Використовуйте це для дослідження життєвого циклу Plugin перед тим, як звертатися до CPU-профайлера. Якщо команда виконується з робочої копії вихідного коду, краще вимірювати зібраний runtime за допомогою `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 ``` Запускач вихідного коду додає прапорці CPU-профілю Node і записує `.cpuprofile` для команди. Використовуйте це перед додаванням тимчасової інструментації в код команд. Для зависань під час запуску, схожих на синхронну роботу файлової системи або завантажувача модулів, додайте прапорець трасування синхронного вводу-виводу Node через запускач вихідного коду: ```bash OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force ``` `pnpm gateway:watch` залишає цей прапорець вимкненим за замовчуванням для дочірнього процесу Gateway під наглядом. Задайте `OPENCLAW_TRACE_SYNC_IO=1`, коли явно хочете отримати вивід трасування синхронного вводу-виводу Node у режимі спостереження. ## Режим спостереження Gateway Для швидких ітерацій запускайте gateway під файловим спостерігачем: ```bash pnpm gateway:watch ``` За замовчуванням це запускає або перезапускає сеанс tmux з назвою `openclaw-gateway-watch-main` (або варіант для профілю/порту, наприклад `openclaw-gateway-watch-dev-19001`) і автоматично приєднується з інтерактивних терміналів. Неінтерактивні оболонки, CI та виклики виконання агентів залишаються від'єднаними й натомість друкують інструкції для приєднання. За потреби приєднайтеся вручну: ```bash tmux attach -t openclaw-gateway-watch-main ``` Панель tmux запускає сирий спостерігач: ```bash node scripts/watch-node.mjs gateway --force ``` Використовуйте режим переднього плану, коли tmux не потрібен: ```bash pnpm gateway:watch:raw # or OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch ``` Вимкніть автоматичне приєднання, зберігаючи керування tmux: ```bash OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch ``` Профілюйте CPU-час Gateway під спостереженням під час налагодження вузьких місць запуску/runtime: ```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`, коли явно хочете і 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-завантаження): ```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` (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`). Процес скидання (свіжий старт): ```bash pnpm gateway:dev:reset ``` `--dev` — це **глобальний** прапорець профілю, і деякі запускові засоби його поглинають. Якщо потрібно вказати його явно, використовуйте форму зі змінною середовища: ```bash OPENCLAW_PROFILE=dev openclaw gateway --dev --reset ``` `--reset` стирає конфігурацію, облікові дані, сеанси й dev-робочу область (за допомогою `trash`, а не `rm`), потім відтворює типове dev-середовище. Якщо вже працює не-dev gateway (launchd або systemd), спершу зупиніть його: ```bash openclaw gateway stop ``` ## Сире журналювання потоку (OpenClaw) OpenClaw може журналювати **сирий потік асистента** до будь-якого фільтрування/форматування. Це найкращий спосіб побачити, чи міркування надходять як звичайні текстові дельти (або як окремі блоки thinking). Увімкніть це через 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` ## Журналювання сирих OpenAI-сумісних фрагментів Щоб захопити **сирі OpenAI-сумісні фрагменти** до їх парсингу в блоки, увімкніть журналювання транспорту: ```bash OPENCLAW_RAW_STREAM=1 ``` Необов'язковий шлях: ```bash 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"` ## Пов'язане - [Усунення неполадок](/uk/help/troubleshooting) - [Поширені запитання](/uk/help/faq)