chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
8c4ce27ed9
commit
c857614ec9
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібно перевірити сирий вивід моделі на наявність витоку міркувань
|
||||
- Ви хочете запускати Gateway у режимі спостереження під час ітерації
|
||||
- Ви хочете запустити Gateway у режимі спостереження під час ітерації
|
||||
- Вам потрібен відтворюваний робочий процес налагодження
|
||||
summary: 'Інструменти налагодження: режим спостереження, сирі потоки моделі та трасування витоку міркувань'
|
||||
title: Налагодження
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T18:22:02Z"
|
||||
generated_at: "2026-04-23T04:19:01Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: bc31ce9b41e92a14c4309f32df569b7050b18024f83280930e53714d3bfcd5cc
|
||||
source_hash: 45f1c55268c02d2d52abf348760d1e00e7536788c3a9aa77854692c4d964fb6e
|
||||
source_path: help/debugging.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Налагодження
|
||||
|
||||
Ця сторінка описує допоміжні засоби налагодження для потокового виводу, особливо коли
|
||||
Ця сторінка охоплює допоміжні засоби налагодження для потокового виводу, особливо коли
|
||||
провайдер змішує міркування зі звичайним текстом.
|
||||
|
||||
## Перевизначення налагодження під час виконання
|
||||
|
||||
Використовуйте `/debug` у чаті, щоб установити перевизначення конфігурації **лише для поточного виконання** (у пам’яті, не на диску).
|
||||
`/debug` за замовчуванням вимкнено; увімкніть його за допомогою `commands.debug: true`.
|
||||
Це зручно, коли потрібно перемикати малопомітні налаштування без редагування `openclaw.json`.
|
||||
Використовуйте `/debug` у чаті, щоб встановити перевизначення конфігурації **лише під час виконання** (у пам’яті, не на диску).
|
||||
`/debug` вимкнено за замовчуванням; увімкніть через `commands.debug: true`.
|
||||
Це зручно, коли потрібно перемикати маловідомі налаштування без редагування `openclaw.json`.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -34,12 +34,12 @@ x-i18n:
|
||||
/debug reset
|
||||
```
|
||||
|
||||
`/debug reset` очищає всі перевизначення та повертає конфігурацію з диска.
|
||||
`/debug reset` очищає всі перевизначення і повертає конфігурацію з диска.
|
||||
|
||||
## Вивід трасування сесії
|
||||
|
||||
Використовуйте `/trace`, коли хочете бачити рядки trace/debug, що належать plugin, в одній сесії
|
||||
без увімкнення повного режиму verbose.
|
||||
Використовуйте `/trace`, коли хочете бачити рядки trace/debug, що належать plugin, в межах однієї сесії
|
||||
без увімкнення повного докладного режиму.
|
||||
|
||||
Приклади:
|
||||
|
||||
@ -49,13 +49,149 @@ x-i18n:
|
||||
/trace off
|
||||
```
|
||||
|
||||
Використовуйте `/trace` для діагностики plugin, наприклад зведень налагодження Active Memory.
|
||||
Продовжуйте використовувати `/verbose` для звичайного виводу статусу/інструментів у режимі verbose, а також
|
||||
продовжуйте використовувати `/debug` для перевизначень конфігурації лише під час виконання.
|
||||
Використовуйте `/trace` для діагностики plugin, наприклад для зведень налагодження Active Memory.
|
||||
Продовжуйте використовувати `/verbose` для звичайного докладного виводу стану/інструментів, а
|
||||
`/debug` — для перевизначень конфігурації лише під час виконання.
|
||||
|
||||
## Тимчасове налагодження таймінгів CLI
|
||||
|
||||
OpenClaw зберігає `src/cli/debug-timing.ts` як невеликий допоміжний засіб для локального
|
||||
дослідження. Його навмисно не підключено до запуску CLI, маршрутизації команд
|
||||
або будь-якої команди за замовчуванням. Використовуйте його лише під час налагодження повільної команди, а потім
|
||||
видаліть імпорт і спани перед внесенням зміни поведінки.
|
||||
|
||||
Використовуйте це, коли команда працює повільно і вам потрібен швидкий розподіл за фазами, перш ніж
|
||||
вирішувати, чи використовувати профілювальник CPU, чи виправляти конкретну підсистему.
|
||||
|
||||
### Додайте тимчасові спани
|
||||
|
||||
Додайте цей допоміжний засіб поруч із кодом, який ви досліджуєте. Наприклад, під час налагодження
|
||||
`openclaw models list` тимчасовий патч у
|
||||
`src/commands/models/list.list-command.ts` може виглядати так:
|
||||
|
||||
```ts
|
||||
// Temporary debugging only. Remove before landing.
|
||||
import { createCliDebugTiming } from "../../cli/debug-timing.js";
|
||||
|
||||
const timing = createCliDebugTiming({ command: "models list" });
|
||||
|
||||
const authStore = timing.time("debug:models:list:auth_store", () => ensureAuthProfileStore());
|
||||
|
||||
const loaded = await timing.timeAsync(
|
||||
"debug:models:list:registry",
|
||||
() => loadListModelRegistry(cfg, { sourceConfig }),
|
||||
(result) => ({
|
||||
models: result.models.length,
|
||||
discoveredKeys: result.discoveredKeys.size,
|
||||
}),
|
||||
);
|
||||
```
|
||||
|
||||
Рекомендації:
|
||||
|
||||
- Додавайте префікс `debug:` до назв тимчасових фаз.
|
||||
- Додавайте лише кілька спанів навколо підозріло повільних ділянок.
|
||||
- Віддавайте перевагу широким фазам на кшталт `registry`, `auth_store` або `rows`, а не
|
||||
назвам допоміжних функцій.
|
||||
- Використовуйте `time()` для синхронної роботи і `timeAsync()` для промісів.
|
||||
- Зберігайте чистоту stdout. Допоміжний засіб пише в stderr, тож JSON-вивід команди залишається придатним до розбору.
|
||||
- Видаляйте тимчасові імпорти і спани перед відкриттям фінального PR із виправленням.
|
||||
- Додавайте в issue або PR вивід таймінгів чи короткий підсумок, що пояснює оптимізацію.
|
||||
|
||||
### Запуск зі зручним для читання виводом
|
||||
|
||||
Режим зручного для читання виводу найкращий для живого налагодження:
|
||||
|
||||
```bash
|
||||
OPENCLAW_DEBUG_TIMING=1 pnpm openclaw models list --all --provider moonshot
|
||||
```
|
||||
|
||||
Приклад виводу з тимчасового дослідження `models list`:
|
||||
|
||||
```text
|
||||
OpenClaw CLI debug timing: models list
|
||||
0ms +0ms start all=true json=false local=false plain=false provider="moonshot"
|
||||
2ms +2ms debug:models:list:import_runtime duration=2ms
|
||||
17ms +14ms debug:models:list:load_config duration=14ms sourceConfig=true
|
||||
20.3s +20.3s debug:models:list:auth_store duration=20.3s
|
||||
20.3s +0ms debug:models:list:resolve_agent_dir duration=0ms agentDir=true
|
||||
20.3s +0ms debug:models:list:resolve_provider_filter duration=0ms
|
||||
25.3s +5.0s debug:models:list:ensure_models_json duration=5.0s
|
||||
31.2s +5.9s debug:models:list:load_model_registry duration=5.9s models=869 availableKeys=38 discoveredKeys=868 availabilityError=false
|
||||
31.2s +0ms debug:models:list:resolve_configured_entries duration=0ms entries=1
|
||||
31.2s +0ms debug:models:list:build_configured_lookup duration=0ms entries=1
|
||||
33.6s +2.4s debug:models:list:read_registry_models duration=2.4s models=871
|
||||
35.2s +1.5s debug:models:list:append_discovered_rows duration=1.5s seenKeys=0 rows=0
|
||||
36.9s +1.7s debug:models:list:append_catalog_supplement_rows duration=1.7s seenKeys=5 rows=5
|
||||
|
||||
Model Input Ctx Local Auth Tags
|
||||
moonshot/kimi-k2-thinking text 256k no no
|
||||
moonshot/kimi-k2-thinking-turbo text 256k no no
|
||||
moonshot/kimi-k2-turbo text 250k no no
|
||||
moonshot/kimi-k2.5 text+image 256k no no
|
||||
moonshot/kimi-k2.6 text+image 256k no no
|
||||
|
||||
36.9s +0ms debug:models:list:print_model_table duration=0ms rows=5
|
||||
36.9s +0ms complete rows=5
|
||||
```
|
||||
|
||||
Висновки з цього виводу:
|
||||
|
||||
| Фаза | Час | Що це означає |
|
||||
| ---------------------------------------- | --------: | -------------------------------------------------------------------------------------------------------- |
|
||||
| `debug:models:list:auth_store` | 20.3s | Завантаження сховища профілів автентифікації є найбільшою витратою і його слід дослідити в першу чергу. |
|
||||
| `debug:models:list:ensure_models_json` | 5.0s | Синхронізація `models.json` достатньо дорога, щоб перевірити кешування або умови пропуску. |
|
||||
| `debug:models:list:load_model_registry` | 5.9s | Побудова реєстру та робота з доступністю провайдерів також дають помітні витрати. |
|
||||
| `debug:models:list:read_registry_models` | 2.4s | Читання всіх моделей реєстру не є безкоштовним і може мати значення для `--all`. |
|
||||
| фази додавання рядків | 3.2s загалом | Побудова п’яти показаних рядків усе ще займає кілька секунд, тож шлях фільтрації варто розглянути ближче. |
|
||||
| `debug:models:list:print_model_table` | 0ms | Рендеринг не є вузьким місцем. |
|
||||
|
||||
Цих висновків достатньо, щоб спрямувати наступний патч без збереження коду таймінгів у
|
||||
робочих шляхах production.
|
||||
|
||||
### Запуск із JSON-виводом
|
||||
|
||||
Використовуйте режим JSON, коли хочете зберегти або порівняти дані таймінгів:
|
||||
|
||||
```bash
|
||||
OPENCLAW_DEBUG_TIMING=json pnpm openclaw models list --all --provider moonshot \
|
||||
2> .artifacts/models-list-timing.jsonl
|
||||
```
|
||||
|
||||
Кожен рядок stderr — це один JSON-об’єкт:
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "models list",
|
||||
"phase": "debug:models:list:registry",
|
||||
"elapsedMs": 31200,
|
||||
"deltaMs": 5900,
|
||||
"durationMs": 5900,
|
||||
"models": 869,
|
||||
"discoveredKeys": 868
|
||||
}
|
||||
```
|
||||
|
||||
### Приберіть перед внесенням змін
|
||||
|
||||
Перед відкриттям фінального PR:
|
||||
|
||||
```bash
|
||||
rg 'createCliDebugTiming|debug:[a-z0-9_-]+:' src/commands src/cli \
|
||||
--glob '!src/cli/debug-timing.*' \
|
||||
--glob '!*.test.ts'
|
||||
```
|
||||
|
||||
Команда не повинна повертати жодних тимчасових місць виклику інструментування, якщо лише PR
|
||||
явно не додає постійну поверхню діагностики. Для звичайних виправлень продуктивності
|
||||
залишайте лише зміну поведінки, тести й коротку примітку з доказами таймінгів.
|
||||
|
||||
Для глибших вузьких місць CPU використовуйте профілювання Node (`--cpu-prof`) або зовнішній
|
||||
профілювальник замість додавання більшої кількості обгорток таймінгів.
|
||||
|
||||
## Режим спостереження Gateway
|
||||
|
||||
Для швидкої ітерації запускайте Gateway під файловим спостерігачем:
|
||||
Для швидкої ітерації запускайте gateway під файловим спостерігачем:
|
||||
|
||||
```bash
|
||||
pnpm gateway:watch
|
||||
@ -67,27 +203,27 @@ pnpm gateway:watch
|
||||
node scripts/watch-node.mjs gateway --force
|
||||
```
|
||||
|
||||
Спостерігач перезапускається при змінах у файлах, важливих для збірки, у `src/`, вихідних файлах extension,
|
||||
Спостерігач перезапускається при змінах у файлах, важливих для збірки, в `src/`, вихідних файлах extension,
|
||||
метаданих extension `package.json` і `openclaw.plugin.json`, `tsconfig.json`,
|
||||
`package.json` і `tsdown.config.ts`. Зміни метаданих extension перезапускають
|
||||
Gateway без примусового `tsdown`-перезбирання; зміни у вихідному коді та конфігурації, як і раніше,
|
||||
спочатку перебудовують `dist`.
|
||||
`package.json` та `tsdown.config.ts`. Зміни метаданих extension перезапускають
|
||||
gateway без примусового `tsdown`-перезбирання; зміни вихідного коду й конфігурації все ще спочатку
|
||||
перезбирають `dist`.
|
||||
|
||||
Додайте будь-які прапорці CLI Gateway після `gateway:watch`, і вони передаватимуться далі
|
||||
під час кожного перезапуску. Повторний запуск тієї самої команди watch для того самого набору repo/прапорців
|
||||
тепер замінює старіший спостерігач замість того, щоб залишати дубльовані батьківські процеси спостерігача.
|
||||
Додайте будь-які прапорці CLI gateway після `gateway:watch`, і вони передаватимуться під час
|
||||
кожного перезапуску. Повторний запуск тієї самої команди спостереження для того самого набору repo/прапорців тепер
|
||||
замінює старіший спостерігач замість того, щоб залишати дублікати батьківських процесів спостерігача.
|
||||
|
||||
## Профіль dev + dev gateway (--dev)
|
||||
## Профіль dev + gateway dev (--dev)
|
||||
|
||||
Використовуйте профіль dev, щоб ізолювати стан і підняти безпечне, тимчасове середовище для
|
||||
налагодження. Є **два** прапорці `--dev`:
|
||||
налагодження. Існують **два** прапорці `--dev`:
|
||||
|
||||
- **Глобальний `--dev` (профіль):** ізолює стан у `~/.openclaw-dev` і
|
||||
за замовчуванням встановлює порт Gateway на `19001` (пов’язані порти зміщуються разом із ним).
|
||||
- **`gateway --dev`:** вказує Gateway автоматично створити типову конфігурацію +
|
||||
workspace, якщо їх немає (і пропустити BOOTSTRAP.md).
|
||||
за замовчуванням встановлює порт gateway на `19001` (пов’язані порти зміщуються разом із ним).
|
||||
- **`gateway --dev`:** наказує Gateway автоматично створити типову конфігурацію +
|
||||
робочий простір, якщо їх немає (і пропустити BOOTSTRAP.md).
|
||||
|
||||
Рекомендований сценарій (профіль dev + dev bootstrap):
|
||||
Рекомендований потік (профіль dev + bootstrap dev):
|
||||
|
||||
```bash
|
||||
pnpm gateway:dev
|
||||
@ -104,16 +240,16 @@ OPENCLAW_PROFILE=dev openclaw tui
|
||||
- `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, якщо їх немає:
|
||||
2. **Bootstrap dev** (`gateway --dev`)
|
||||
- Записує мінімальну конфігурацію, якщо її немає (`gateway.mode=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`).
|
||||
- У режимі dev пропускає провайдери каналів (`OPENCLAW_SKIP_CHANNELS=1`).
|
||||
|
||||
Сценарій скидання (чистий старт):
|
||||
Потік скидання (чистий старт):
|
||||
|
||||
```bash
|
||||
pnpm gateway:dev:reset
|
||||
@ -126,10 +262,10 @@ pnpm gateway:dev:reset
|
||||
OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
|
||||
```
|
||||
|
||||
`--reset` очищає конфігурацію, облікові дані, сесії та dev workspace (за допомогою
|
||||
`trash`, а не `rm`), а потім заново створює типове dev-середовище.
|
||||
`--reset` очищає конфігурацію, облікові дані, сесії та робочий простір dev (через
|
||||
`trash`, а не `rm`), а потім заново створює типове середовище dev.
|
||||
|
||||
Порада: якщо вже запущено не-dev Gateway (launchd/systemd), спочатку зупиніть його:
|
||||
Порада: якщо gateway не в режимі dev уже запущений (launchd/systemd), спочатку зупиніть його:
|
||||
|
||||
```bash
|
||||
openclaw gateway stop
|
||||
@ -139,9 +275,9 @@ openclaw gateway stop
|
||||
|
||||
OpenClaw може журналювати **сирий потік асистента** до будь-якої фільтрації/форматування.
|
||||
Це найкращий спосіб побачити, чи надходять міркування як звичайні текстові дельти
|
||||
(або як окремі блоки thinking).
|
||||
(або як окремі thinking-блоки).
|
||||
|
||||
Увімкнення через CLI:
|
||||
Увімкніть це через CLI:
|
||||
|
||||
```bash
|
||||
pnpm gateway:watch --raw-stream
|
||||
@ -166,8 +302,8 @@ OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
|
||||
|
||||
## Логування сирих чанків (pi-mono)
|
||||
|
||||
Щоб захопити **сирі OpenAI-сумісні чанки** до того, як їх буде розібрано на блоки,
|
||||
pi-mono надає окремий журналювач:
|
||||
Щоб захоплювати **сирі OpenAI-compat чанки** до того, як вони будуть розібрані на блоки,
|
||||
pi-mono надає окремий логер:
|
||||
|
||||
```bash
|
||||
PI_RAW_STREAM=1
|
||||
@ -183,11 +319,11 @@ PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl
|
||||
|
||||
`~/.pi-mono/logs/raw-openai-completions.jsonl`
|
||||
|
||||
> Примітка: це виводиться лише процесами, які використовують провайдер pi-mono
|
||||
> `openai-completions`.
|
||||
> Примітка: це виводиться лише процесами, які використовують провайдер
|
||||
> `openai-completions` із pi-mono.
|
||||
|
||||
## Примітки щодо безпеки
|
||||
|
||||
- Журнали сирого потоку можуть містити повні підказки, вивід інструментів і дані користувача.
|
||||
- Зберігайте журнали локально та видаляйте їх після налагодження.
|
||||
- Якщо ділитеся журналами, спочатку очищуйте з них секрети та PII.
|
||||
- Журнали сирого потоку можуть містити повні промпти, вивід інструментів і дані користувача.
|
||||
- Зберігайте журнали локально й видаляйте їх після налагодження.
|
||||
- Якщо ділитеся журналами, спочатку очищайте секрети та PII.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user