---
read_when:
    - Вам потрібно перевірити сирий вивід моделі на наявність витоку міркувань
    - Ви хочете запускати Gateway у режимі спостереження під час ітерації
    - Вам потрібен відтворюваний робочий процес налагодження
summary: 'Інструменти налагодження: режим спостереження, сирі потоки моделі та трасування витоку міркувань'
title: Налагодження
x-i18n:
    generated_at: "2026-04-12T18:22:02Z"
    model: gpt-5.4
    provider: openai
    source_hash: bc31ce9b41e92a14c4309f32df569b7050b18024f83280930e53714d3bfcd5cc
    source_path: help/debugging.md
    workflow: 15
---

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

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

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

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

Приклади:

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

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

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

Використовуйте `/trace`, коли хочете бачити рядки trace/debug, що належать plugin, в одній сесії
без увімкнення повного режиму verbose.

Приклади:

```text
/trace
/trace on
/trace off
```

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

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

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

```bash
pnpm gateway:watch
```

Це відповідає:

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

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

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

## Профіль dev + dev gateway (--dev)

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

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

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

```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 bootstrap** (`gateway --dev`)
   - Записує мінімальну конфігурацію, якщо її немає (`gateway.mode=local`, bind loopback).
   - Установлює `agent.workspace` на dev workspace.
   - Установлює `agent.skipBootstrap=true` (без BOOTSTRAP.md).
   - Заповнює файли workspace, якщо їх немає:
     `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 workspace (за допомогою
`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`

## Логування сирих чанків (pi-mono)

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

```bash
PI_RAW_STREAM=1
```

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

```bash
PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl
```

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

`~/.pi-mono/logs/raw-openai-completions.jsonl`

> Примітка: це виводиться лише процесами, які використовують провайдер pi-mono
> `openai-completions`.

## Примітки щодо безпеки

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