> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

Використовуйте `/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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
/trace
/trace on
/trace off
```

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

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

Використовуйте `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`, коли команди життєвого циклу Plugin здаються повільними
й потрібна вбудована розбивка фаз для метаданих Plugin, виявлення, реєстру,
дзеркала runtime, зміни конфігурації та оновлення. Трасування вмикається явно й пише
в stderr, тому JSON-вивід команд залишається придатним для парсингу.

Приклад:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
```

Приклад виводу:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
[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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status
```

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force
```

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

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
tmux attach -t openclaw-gateway-watch-main
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
node scripts/watch-node.mjs gateway --force
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch:raw
# or
OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch --benchmark
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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-завантаження):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:dev:reset
```

<Note>
  `--dev` — це **глобальний** прапорець профілю, і деякі запускові засоби його поглинають. Якщо потрібно вказати його явно, використовуйте форму зі змінною середовища:

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
  ```
</Note>

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

<Tip>
  Якщо вже працює не-dev gateway (launchd або systemd), спершу зупиніть його:

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  openclaw gateway stop
  ```
</Tip>

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

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

Увімкніть це через CLI:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch --raw-stream
```

Необов'язкове перевизначення шляху:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
```

Еквівалентні змінні середовища:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
```

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

`~/.openclaw/logs/raw-stream.jsonl`

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_RAW_STREAM=1
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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)