diff --git a/docs/uk/gateway/diagnostics.md b/docs/uk/gateway/diagnostics.md index 2c3993d9e..e44572273 100644 --- a/docs/uk/gateway/diagnostics.md +++ b/docs/uk/gateway/diagnostics.md @@ -1,26 +1,22 @@ --- read_when: - - Підготовка звіту про помилку або запиту на підтримку - - Налагодження аварійних завершень Gateway, перезапусків, тиску на пам’ять або завеликих корисних навантажень - - Перегляд того, які діагностичні дані записуються або приховуються -summary: Створюйте діагностичні пакети Gateway для звітів про помилки, якими можна ділитися + - Підготовка звіту про помилку або запиту до служби підтримки + - Налагодження аварійних завершень Gateway, перезапусків, нестачі пам’яті або завеликих корисних навантажень + - Перегляд того, які діагностичні дані записуються або маскуються +summary: Створюйте діагностичні пакети Gateway для звітів про помилки, якими можна поділитися title: Експорт діагностики x-i18n: - generated_at: "2026-05-03T18:32:10Z" + generated_at: "2026-05-04T22:41:07Z" model: gpt-5.5 provider: openai - source_hash: f6cf8e00fe8033e339b5c947ce3dd10fdee736048a358ad3a0c2ccb77e939f4b + source_hash: 56539280bc7a7868063328626e63b2576feb5578e2651d3a2976ee9c34243382 source_path: gateway/diagnostics.md workflow: 16 --- -OpenClaw може створити локальний zip-архів діагностики для звітів про помилки. Він поєднує -санітизований стан Gateway, справність, журнали, форму конфігурації та нещодавні події -стабільності без payload. +OpenClaw може створити локальний діагностичний zip-архів для звітів про помилки. Він об’єднує очищені від чутливих даних статус Gateway, стан працездатності, журнали, форму конфігурації та нещодавні події стабільності без корисного навантаження. -Ставтеся до діагностичних пакетів як до секретів, доки не переглянете їх. Вони -спроєктовані так, щоб пропускати або редагувати payload і облікові дані, але все одно узагальнюють -локальні журнали Gateway і стан середовища виконання на рівні хоста. +Ставтеся до діагностичних пакетів як до секретів, доки не переглянете їх. Вони розроблені так, щоб пропускати або редагувати корисні навантаження та облікові дані, але все одно підсумовують локальні журнали Gateway і стан виконання на рівні хоста. ## Швидкий старт @@ -42,95 +38,59 @@ openclaw gateway diagnostics export --json ## Команда чату -Власники можуть використовувати `/diagnostics [note]` у чаті, щоб запросити локальний експорт Gateway. -Використовуйте це, коли помилка сталася в реальній розмові й потрібен один -звіт для підтримки, який можна скопіювати та вставити: +Власники можуть використовувати `/diagnostics [note]` у чаті, щоб запросити локальний експорт Gateway. Використовуйте це, коли помилка сталася в реальній розмові й вам потрібен один звіт для підтримки, який можна скопіювати та вставити: -1. Надішліть `/diagnostics` у розмові, де ви помітили проблему. Додайте - коротку нотатку, якщо це допоможе, наприклад `/diagnostics bad tool choice`. -2. OpenClaw надсилає преамбулу діагностики й просить одне явне підтвердження exec. - Підтвердження запускає `openclaw gateway diagnostics export --json`. - Не підтверджуйте діагностику через правило allow-all. -3. Після підтвердження OpenClaw відповідає звітом для вставлення, який містить локальний - шлях до пакета, підсумок маніфесту, нотатки про приватність і відповідні ідентифікатори сеансів. +1. Надішліть `/diagnostics` у розмові, де ви помітили проблему. Додайте коротку примітку, якщо це допоможе, наприклад `/diagnostics bad tool choice`. +2. OpenClaw надсилає вступ до діагностики та просить одне явне підтвердження exec. Підтвердження запускає `openclaw gateway diagnostics export --json`. Не підтверджуйте діагностику через правило allow-all. +3. Після підтвердження OpenClaw відповідає звітом, який можна вставити, з локальним шляхом до пакета, підсумком маніфесту, примітками щодо приватності та відповідними ідентифікаторами сесій. -У групових чатах власник усе ще може запускати `/diagnostics`, але OpenClaw не -публікує діагностичні деталі назад у спільний чат. Він надсилає преамбулу, -запити підтвердження, результат експорту Gateway і розбивку сеансів/потоків Codex -власнику через приватний маршрут підтвердження. Група отримує лише коротке сповіщення -про те, що діагностичний процес було надіслано приватно. Якщо OpenClaw не може знайти приватний -маршрут до власника, команда завершується безпечною відмовою і просить власника запустити її з DM. +У групових чатах власник усе ще може запускати `/diagnostics`, але OpenClaw не публікує діагностичні подробиці назад у спільний чат. Він надсилає вступ, запити підтвердження, результат експорту Gateway і розбивку сесії/потоку Codex власнику через приватний маршрут підтвердження. Група отримує лише коротке повідомлення, що діагностичний процес було надіслано приватно. Якщо OpenClaw не може знайти приватний маршрут до власника, команда безпечно завершується помилкою та просить власника запустити її з DM. -Коли активний сеанс OpenClaw використовує нативний OpenAI Codex harness, -те саме підтвердження exec також охоплює завантаження відгуку OpenAI для потоків -середовища виконання Codex, про які знає OpenClaw. Це завантаження є окремим від локального -zip-архіву Gateway і з'являється лише для сеансів Codex harness. Перед підтвердженням -запит пояснює, що підтвердження діагностики також надішле відгук Codex, але він -не перелічує ідентифікатори сеансів або потоків Codex. Після підтвердження відповідь у чаті перелічує -канали, ідентифікатори сеансів OpenClaw, ідентифікатори потоків Codex і локальні команди відновлення -для потоків, надісланих на сервери OpenAI. Якщо ви відхилите або проігноруєте -підтвердження, OpenClaw не запускає експорт, не надсилає відгук Codex і -не виводить ідентифікатори Codex. +Коли активна сесія OpenClaw використовує нативний OpenAI Codex harness, те саме підтвердження exec також охоплює завантаження відгуку OpenAI для runtime-потоків Codex, про які знає OpenClaw. Це завантаження відокремлене від локального zip-архіву Gateway і з’являється лише для сесій Codex harness. Перед підтвердженням запит пояснює, що підтвердження діагностики також надішле відгук Codex, але не перелічує ідентифікатори сесій або потоків Codex. Після підтвердження відповідь у чаті перелічує канали, ідентифікатори сесій OpenClaw, ідентифікатори потоків Codex і локальні команди відновлення для потоків, які було надіслано на сервери OpenAI. Якщо ви відхилите або проігноруєте підтвердження, OpenClaw не запускає експорт, не надсилає відгук Codex і не виводить ідентифікатори Codex. -Це робить типовий цикл налагодження Codex коротким: помітили неправильну поведінку в -Telegram, Discord або іншому каналі, запустили `/diagnostics`, один раз підтвердили, поділилися -звітом із підтримкою, а потім локально запустили виведену команду `codex resume `, -якщо хочете самостійно перевірити нативний потік Codex. Див. -[Codex harness](/uk/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) для -цього процесу перевірки. +Це робить типовий цикл налагодження Codex коротким: помітьте неправильну поведінку в Telegram, Discord або іншому каналі, запустіть `/diagnostics`, підтвердьте один раз, поділіться звітом із підтримкою, а потім запустіть виведену команду `codex resume ` локально, якщо хочете самостійно перевірити нативний потік Codex. Див. [Codex harness](/uk/plugins/codex-harness#inspect-a-codex-thread-from-the-cli) для цього процесу перевірки. ## Що містить експорт Zip-архів містить: -- `summary.md`: зручний для читання огляд для підтримки. -- `diagnostics.json`: машинозчитуваний підсумок конфігурації, журналів, стану, справності - та даних стабільності. -- `manifest.json`: метадані експорту й список файлів. -- Санітизовану форму конфігурації та несекретні деталі конфігурації. -- Санітизовані підсумки журналів і нещодавні відредаговані рядки журналів. -- Найкращі можливі знімки стану й справності Gateway. +- `summary.md`: зрозумілий для людини огляд для підтримки. +- `diagnostics.json`: машиночитаний підсумок конфігурації, журналів, статусу, стану працездатності та даних стабільності. +- `manifest.json`: метадані експорту та список файлів. +- Очищену від чутливих даних форму конфігурації та несекретні подробиці конфігурації. +- Очищені від чутливих даних підсумки журналів і нещодавні відредаговані рядки журналів. +- Найкращі можливі знімки статусу та стану працездатності Gateway. - `stability/latest.json`: найновіший збережений пакет стабільності, коли доступний. -Експорт корисний навіть тоді, коли Gateway несправний. Якщо Gateway не може -відповісти на запити стану або справності, локальні журнали, форма конфігурації та найновіший -пакет стабільності все одно збираються, коли доступні. +Експорт корисний навіть тоді, коли Gateway несправний. Якщо Gateway не може відповідати на запити статусу або стану працездатності, локальні журнали, форма конфігурації та найновіший пакет стабільності все одно збираються, коли доступні. ## Модель приватності -Діагностика спроєктована так, щоб нею можна було ділитися. Експорт зберігає операційні дані, -які допомагають налагодженню, як-от: +Діагностика розроблена так, щоб нею можна було ділитися. Експорт зберігає операційні дані, які допомагають у налагодженні, зокрема: - назви підсистем, ідентифікатори Plugin, ідентифікатори провайдерів, ідентифікатори каналів і налаштовані режими -- коди стану, тривалості, кількість байтів, стан черги та показники пам'яті -- санітизовані метадані журналів і відредаговані операційні повідомлення +- коди статусу, тривалості, кількість байтів, стан черги та показники пам’яті +- очищені від чутливих даних метадані журналів і відредаговані операційні повідомлення - форму конфігурації та несекретні налаштування функцій Експорт пропускає або редагує: -- текст чатів, промпти, інструкції, тіла webhook і результати інструментів -- облікові дані, API-ключі, токени, cookies і секретні значення -- необроблені тіла запитів або відповідей -- ідентифікатори облікових записів, ідентифікатори повідомлень, необроблені ідентифікатори сеансів, імена хостів і локальні імена користувачів +- текст чату, підказки, інструкції, тіла Webhook і результати інструментів +- облікові дані, ключі API, токени, cookies і секретні значення +- сирі тіла запитів або відповідей +- ідентифікатори облікових записів, ідентифікатори повідомлень, сирі ідентифікатори сесій, імена хостів і локальні імена користувачів -Коли повідомлення журналу схоже на текст payload користувача, чату, промпта або інструмента, -експорт зберігає лише факт пропуску повідомлення та кількість байтів. +Коли повідомлення журналу схоже на текст користувача, чату, підказки або корисного навантаження інструмента, експорт зберігає лише факт, що повідомлення було пропущено, і кількість байтів. -## Реєстратор стабільності +## Записувач стабільності -Gateway за замовчуванням записує обмежений потік стабільності без payload, коли -діагностику ввімкнено. Він призначений для операційних фактів, а не для вмісту. +Gateway за замовчуванням записує обмежений потік стабільності без корисного навантаження, коли діагностику ввімкнено. Він призначений для операційних фактів, а не для вмісту. -Той самий діагностичний heartbeat записує зразки активності, коли Gateway продовжує -працювати, але event loop Node.js або CPU здаються перевантаженими. Ці події -`diagnostic.liveness.warning` містять затримку event loop, використання event loop, -співвідношення ядер CPU та кількість активних/очікувальних/поставлених у чергу сеансів. Неактивні -зразки залишаються в телеметрії на рівні `info`. Зразки активності стають попередженнями Gateway -лише тоді, коли робота очікує або стоїть у черзі, або коли активна робота збігається зі -сталою затримкою event loop. Тимчасові піки максимальної затримки під час загалом справної -фонової роботи залишаються в журналах debug. Вони самі по собі не перезапускають Gateway. +Той самий діагностичний Heartbeat записує зразки активності, коли Gateway продовжує працювати, але цикл подій Node.js або CPU виглядає перевантаженим. Ці події `diagnostic.liveness.warning` містять затримку циклу подій, використання циклу подій, співвідношення CPU-ядер, кількість активних/очікуваних/поставлених у чергу сесій, поточну фазу запуску/runtime, коли відома, нещодавні проміжки фаз і обмежені мітки активної/поставленої в чергу роботи. Зразки простою залишаються в телеметрії на рівні `info`. Зразки активності стають попередженнями Gateway лише тоді, коли робота очікує або перебуває в черзі, або коли активна робота збігається зі сталою затримкою циклу подій. Тимчасові піки максимальної затримки під час загалом здорової фонової роботи залишаються в журналах налагодження. Самі по собі вони не перезапускають Gateway. -Перевірити активний реєстратор: +Фази запуску також генерують події `diagnostic.phase.completed` з часом за настінним годинником і CPU. Діагностика застряглих вбудованих запусків позначає `terminalProgressStale=true`, коли останній прогрес bridge виглядав термінальним, наприклад сирий елемент відповіді або подія завершення відповіді, але Gateway усе ще вважає вбудований запуск активним. + +Перевірте live recorder: ```bash openclaw gateway stability @@ -138,14 +98,13 @@ openclaw gateway stability --type payload.large openclaw gateway stability --json ``` -Перевірити найновіший збережений пакет стабільності після фатального завершення, тайм-ауту -завершення роботи або помилки запуску після перезапуску: +Перевірте найновіший збережений пакет стабільності після фатального завершення, тайм-ауту вимкнення або помилки запуску після перезапуску: ```bash openclaw gateway stability --bundle latest ``` -Створити zip-архів діагностики з найновішого збереженого пакета: +Створіть діагностичний zip-архів із найновішого збереженого пакета: ```bash openclaw gateway stability --bundle latest --export @@ -153,7 +112,7 @@ openclaw gateway stability --bundle latest --export Збережені пакети розміщуються в `~/.openclaw/logs/stability/`, коли події існують. -## Корисні опції +## Корисні параметри ```bash openclaw gateway diagnostics export \ @@ -162,20 +121,19 @@ openclaw gateway diagnostics export \ --log-bytes 1000000 ``` -- `--output `: записати в конкретний шлях zip-архіву. -- `--log-lines `: максимальна кількість санітизованих рядків журналу для включення. +- `--output `: записати до конкретного шляху zip-архіву. +- `--log-lines `: максимальна кількість очищених від чутливих даних рядків журналу для включення. - `--log-bytes `: максимальна кількість байтів журналу для перевірки. -- `--url `: WebSocket URL Gateway для знімків стану й справності. -- `--token `: токен Gateway для знімків стану й справності. -- `--password `: пароль Gateway для знімків стану й справності. -- `--timeout `: тайм-аут знімків стану й справності. +- `--url `: URL WebSocket Gateway для знімків статусу та стану працездатності. +- `--token `: токен Gateway для знімків статусу та стану працездатності. +- `--password `: пароль Gateway для знімків статусу та стану працездатності. +- `--timeout `: тайм-аут знімків статусу та стану працездатності. - `--no-stability-bundle`: пропустити пошук збереженого пакета стабільності. -- `--json`: вивести машинозчитувані метадані експорту. +- `--json`: вивести машиночитані метадані експорту. -## Вимкнути діагностику +## Вимкнення діагностики -Діагностику ввімкнено за замовчуванням. Щоб вимкнути реєстратор стабільності та -збір діагностичних подій: +Діагностику ввімкнено за замовчуванням. Щоб вимкнути записувач стабільності та збір діагностичних подій: ```json5 { @@ -185,13 +143,12 @@ openclaw gateway diagnostics export \ } ``` -Вимкнення діагностики зменшує деталізацію звіту про помилку. Це не впливає на звичайне -журналювання Gateway. +Вимкнення діагностики зменшує деталізацію звітів про помилки. Це не впливає на звичайне журналювання Gateway. -## Пов'язане +## Пов’язане -- [Перевірки справності](/uk/gateway/health) +- [Перевірки стану працездатності](/uk/gateway/health) - [CLI Gateway](/uk/cli/gateway#gateway-diagnostics-export) - [Протокол Gateway](/uk/gateway/protocol#system-and-identity) - [Журналювання](/uk/logging) -- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — окремий процес для потокової передачі діагностики до колектора +- [Експорт OpenTelemetry](/uk/gateway/opentelemetry) — окремий процес для потокової передачі діагностики до збирача diff --git a/docs/uk/help/debugging.md b/docs/uk/help/debugging.md index c59775b11..11f28a7e8 100644 --- a/docs/uk/help/debugging.md +++ b/docs/uk/help/debugging.md @@ -1,25 +1,25 @@ --- read_when: - Потрібно перевірити необроблений вивід моделі на витік міркувань - - Ви хочете запускати Gateway у режимі відстеження під час ітеративної роботи + - Ви хочете запускати Gateway у режимі відстеження під час ітераційної роботи - Вам потрібен відтворюваний робочий процес налагодження -summary: 'Інструменти налагодження: режим спостереження, необроблені потоки моделі та відстеження витоку міркувань' +summary: 'Інструменти налагодження: режим спостереження, необроблені потоки моделі та трасування витоку міркувань' title: Налагодження x-i18n: - generated_at: "2026-05-03T16:16:07Z" + generated_at: "2026-05-04T22:41:07Z" model: gpt-5.5 provider: openai - source_hash: 7230112013a8db8d6a3853b765f4302a61609051ac4ffaf35a6f09de328deafc + source_hash: d2b48aab9e3d8be36a78e797fdd723e3af4b35dd28ed3a95e63bb422422bccc6 source_path: help/debugging.md workflow: 16 --- -Допоміжні засоби налагодження для потокового виводу, особливо коли провайдер змішує reasoning зі звичайним текстом. +Помічники для налагодження потокового виводу, особливо коли provider домішує reasoning у звичайний текст. -## Перевизначення налагодження під час виконання +## Перевизначення runtime debug -Використовуйте `/debug` у чаті, щоб установити перевизначення конфігурації **лише на час виконання** (у пам’яті, не на диску). -`/debug` вимкнено за замовчуванням; увімкніть його за допомогою `commands.debug: true`. +Використовуйте `/debug` у чаті, щоб установити **лише runtime** перевизначення config (у пам’яті, не на диску). +`/debug` вимкнено за замовчуванням; увімкніть через `commands.debug: true`. Це зручно, коли потрібно перемикати маловідомі налаштування без редагування `openclaw.json`. Приклади: @@ -31,12 +31,12 @@ x-i18n: /debug reset ``` -`/debug reset` очищує всі перевизначення й повертає конфігурацію з диска. +`/debug reset` очищає всі перевизначення й повертає config на диску. ## Вивід трасування сесії -Використовуйте `/trace`, коли хочете бачити рядки трасування/налагодження, якими володіє Plugin, в одній сесії -без увімкнення повного докладного режиму. +Використовуйте `/trace`, коли хочете бачити trace/debug рядки, що належать Plugin, в одній сесії +без увімкнення повного verbose mode. Приклади: @@ -46,16 +46,16 @@ x-i18n: /trace off ``` -Використовуйте `/trace` для діагностики Plugin, наприклад налагоджувальних зведень Active Memory. -Продовжуйте використовувати `/verbose` для звичайного докладного виводу стану/інструментів, а -`/debug` — для перевизначень конфігурації лише на час виконання. +Використовуйте `/trace` для діагностики Plugin, наприклад debug-зведень Active Memory. +Продовжуйте використовувати `/verbose` для звичайного докладного виводу статусу/tool, і продовжуйте використовувати +`/debug` для лише runtime перевизначень config. ## Трасування життєвого циклу Plugin Використовуйте `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`, коли команди життєвого циклу Plugin здаються повільними -і вам потрібна вбудована розбивка за фазами для метаданих Plugin, виявлення, registry, -runtime mirror, зміни конфігурації та оновлення. Трасування вмикається явно та записує -в stderr, тому JSON-вивід команди залишається придатним для парсингу. +і потрібна вбудована розбивка фаз для metadata, discovery, registry Plugin, +runtime mirror, мутації config і refresh-робіт. Трасування є opt-in і пише +в stderr, тож JSON-вивід команд залишається придатним до парсингу. Приклад: @@ -71,14 +71,14 @@ OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force [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 ...` -також вимірює накладні витрати source-runner. +Використовуйте це для дослідження життєвого циклу Plugin перед тим, як переходити до CPU profiler. +Якщо команда запускається з source checkout, надавайте перевагу вимірюванню зібраного +runtime через `node dist/entry.js ...` після `pnpm build`; `pnpm openclaw ...` +також вимірює overhead source-runner. -## Профілювання запуску CLI та команд +## Профілювання запуску CLI і команд -Використовуйте включений у репозиторій бенчмарк запуску, коли команда здається повільною: +Використовуйте доданий startup benchmark, коли команда здається повільною: ```bash pnpm test:startup:bench:smoke @@ -86,35 +86,46 @@ 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 ``` -Для одноразового профілювання через звичайний source runner установіть +Для одноразового профілювання через звичайний source runner задайте `OPENCLAW_RUN_NODE_CPU_PROF_DIR`: ```bash OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status ``` -Source runner додає прапорці профілю CPU Node і записує `.cpuprofile` для -команди. Використовуйте це перед додаванням тимчасової інструментації до коду команди. +Source runner додає прапорці Node CPU profile і записує `.cpuprofile` для +команди. Використовуйте це перед додаванням тимчасового інструментування в код команди. -## Режим спостереження Gateway +Для зависань під час запуску, які схожі на синхронну роботу filesystem або module-loader, +додайте прапорець Node для трасування sync I/O через source runner: -Для швидкої ітерації запускайте Gateway під файловим спостерігачем: +```bash +OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force +``` + +`pnpm gateway:watch` вмикає цей прапорець за замовчуванням для відстежуваного дочірнього Gateway. +Установіть `OPENCLAW_TRACE_SYNC_IO=0`, щоб придушити вивід Node sync I/O trace у watch +mode. + +## Watch mode Gateway + +Для швидкої ітерації запускайте gateway під file watcher: ```bash pnpm gateway:watch ``` -За замовчуванням це запускає або перезапускає сесію tmux із назвою -`openclaw-gateway-watch-main` (або варіант для профілю/порту, наприклад +За замовчуванням це запускає або перезапускає tmux-сесію з назвою +`openclaw-gateway-watch-main` (або profile/port-specific варіант, наприклад `openclaw-gateway-watch-dev-19001`) і автоматично під’єднується з інтерактивних терміналів. -Неінтерактивні оболонки, CI та виклики agent exec залишаються від’єднаними й натомість друкують -інструкції для під’єднання. За потреби під’єднайтеся вручну: +Неінтерактивні shell, CI та agent exec calls залишаються від’єднаними й натомість друкують +інструкції для під’єднання. Під’єднуйтеся вручну за потреби: ```bash tmux attach -t openclaw-gateway-watch-main ``` -Панель tmux запускає сирий спостерігач: +Панель tmux запускає raw watcher: ```bash node scripts/watch-node.mjs gateway --force @@ -128,99 +139,102 @@ pnpm gateway:watch:raw OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch ``` -Вимкніть автоматичне під’єднання, зберігаючи керування tmux: +Вимкніть auto-attach, зберігаючи керування tmux: ```bash OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch ``` -Профілюйте CPU-час Gateway під спостереженням під час налагодження вузьких місць запуску/runtime: +Профілюйте CPU-час відстежуваного Gateway під час налагодження hotspot запуску/runtime: ```bash pnpm gateway:watch --benchmark ``` -Обгортка спостерігача споживає `--benchmark` перед викликом Gateway і записує -один V8 `.cpuprofile` для кожного завершення дочірнього процесу Gateway у -`.artifacts/gateway-watch-profiles/`. Зупиніть або перезапустіть gateway під спостереженням, щоб -скинути поточний профіль, потім відкрийте його в Chrome DevTools або Speedscope: +Watch wrapper споживає `--benchmark` перед викликом Gateway і записує +один V8 `.cpuprofile` для кожного завершення дочірнього Gateway у +`.artifacts/gateway-watch-profiles/`. Зупиніть або перезапустіть відстежуваний gateway, щоб +скинути поточний profile, потім відкрийте його через Chrome DevTools або Speedscope: ```bash npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile ``` -Використовуйте `--benchmark-dir `, коли хочете зберігати профілі в іншому місці. -Використовуйте `--benchmark-no-force`, коли хочете, щоб профільований дочірній процес пропустив -типове очищення порту `--force` і швидко завершився з помилкою, якщо порт Gateway уже +Використовуйте `--benchmark-dir `, коли хочете зберігати profiles в іншому місці. +Використовуйте `--benchmark-no-force`, коли хочете, щоб benchmarked child пропускав +стандартне очищення порту `--force` і швидко завершувався помилкою, якщо порт Gateway уже використовується. +Benchmark mode за замовчуванням пригнічує спам sync-I/O trace. Установіть +`OPENCLAW_TRACE_SYNC_IO=1` з `--benchmark`, коли явно хочете і CPU +profiles, і stack traces Node sync-I/O. -Обгортка tmux переносить у панель поширені несекретні runtime-селектори, як-от +Tmux wrapper переносить у панель поширені несекретні runtime selectors, як-от `OPENCLAW_PROFILE`, `OPENCLAW_CONFIG_PATH`, `OPENCLAW_STATE_DIR`, `OPENCLAW_GATEWAY_PORT` і `OPENCLAW_SKIP_CHANNELS`. Розміщуйте -облікові дані провайдерів у звичайному профілі/конфігурації або використовуйте сирий foreground mode -для одноразових ефемерних секретів. -Якщо Gateway під спостереженням завершується під час запуску, спостерігач один раз запускає -`openclaw doctor --fix --non-interactive` і перезапускає дочірній процес Gateway. -Використовуйте `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0`, коли потрібна початкова помилка запуску -без dev-only проходу відновлення. -Керована панель tmux також за замовчуванням використовує кольорові журнали Gateway для читабельності; -задайте `FORCE_COLOR=0` під час запуску `pnpm gateway:watch`, щоб вимкнути ANSI-вивід. +облікові дані provider у своєму звичайному profile/config або використовуйте raw foreground mode +для одноразових ephemeral secrets. +Якщо відстежуваний Gateway завершується під час запуску, watcher один раз запускає +`openclaw doctor --fix --non-interactive` і перезапускає дочірній Gateway. +Використовуйте `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0`, коли хочете бачити початкову помилку запуску +без dev-only repair pass. +Керована tmux-панель також за замовчуванням використовує кольорові логи Gateway для читабельності; +установіть `FORCE_COLOR=0` під час запуску `pnpm gateway:watch`, щоб вимкнути ANSI-вивід. -Спостерігач перезапускається при зміні build-relevant файлів у `src/`, вихідних файлів extension, -метаданих extension `package.json` і `openclaw.plugin.json`, `tsconfig.json`, -`package.json` і `tsdown.config.ts`. Зміни метаданих extension перезапускають -gateway без примусового перебудовування `tsdown`; зміни вихідного коду та конфігурації все ще -спочатку перебудовують `dist`. +Watcher перезапускається на build-relevant файлах у `src/`, source-файлах extension, +metadata `package.json` і `openclaw.plugin.json` extension, `tsconfig.json`, +`package.json` і `tsdown.config.ts`. Зміни metadata extension перезапускають +gateway без примусового `tsdown` rebuild; source і config зміни все ще +спершу перебудовують `dist`. -Додайте будь-які прапорці CLI gateway після `gateway:watch`, і вони передаватимуться під час -кожного перезапуску. Повторний запуск тієї самої команди спостереження пересоздає названу панель tmux, а -сирий спостерігач усе ще зберігає блокування єдиного спостерігача, тому дублікати батьківських процесів спостерігача -замінюються, а не накопичуються. +Додавайте будь-які прапорці gateway CLI після `gateway:watch`, і їх буде передано далі під час +кожного перезапуску. Повторний запуск тієї самої watch-команди respawn-ить названу tmux-панель, а +raw watcher усе ще зберігає свій single-watcher lock, щоб дублікати watcher parents +замінювалися, а не накопичувалися. -## Dev-профіль + dev-gateway (--dev) +## Dev profile + dev gateway (--dev) -Використовуйте dev-профіль, щоб ізолювати стан і підняти безпечне одноразове середовище для +Використовуйте dev profile, щоб ізолювати state і підняти безпечне одноразове середовище для налагодження. Є **два** прапорці `--dev`: -- **Глобальний `--dev` (профіль):** ізолює стан у `~/.openclaw-dev` і - задає типовий порт gateway `19001` (похідні порти зсуваються разом із ним). -- **`gateway --dev`: повідомляє Gateway автоматично створити типову конфігурацію + - workspace** за їх відсутності (і пропустити BOOTSTRAP.md). +- **Global `--dev` (profile):** ізолює state у `~/.openclaw-dev` і + задає стандартний порт gateway `19001` (derived ports зміщуються разом із ним). +- **`gateway --dev`: каже Gateway автоматично створити default config + + workspace**, якщо їх немає (і пропустити BOOTSTRAP.md). -Рекомендований процес (dev-профіль + dev-bootstrap): +Рекомендований flow (dev profile + dev bootstrap): ```bash pnpm gateway:dev OPENCLAW_PROFILE=dev openclaw tui ``` -Якщо у вас ще немає глобального встановлення, запускайте CLI через `pnpm openclaw ...`. +Якщо глобального install ще немає, запускайте CLI через `pnpm openclaw ...`. Що це робить: -1. **Ізоляція профілю** (глобальний `--dev`) +1. **Ізоляція profile** (global `--dev`) - `OPENCLAW_PROFILE=dev` - `OPENCLAW_STATE_DIR=~/.openclaw-dev` - `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json` - - `OPENCLAW_GATEWAY_PORT=19001` (browser/canvas відповідно зсуваються) + - `OPENCLAW_GATEWAY_PORT=19001` (browser/canvas зміщуються відповідно) -2. **Dev-bootstrap** (`gateway --dev`) - - Записує мінімальну конфігурацію, якщо її немає (`gateway.mode=local`, прив’язка до loopback). +2. **Dev bootstrap** (`gateway --dev`) + - Записує мінімальний config, якщо його немає (`gateway.mode=local`, bind loopback). - Установлює `agent.workspace` у dev workspace. - Установлює `agent.skipBootstrap=true` (без BOOTSTRAP.md). - - Засіває файли workspace, якщо їх немає: + - Seed-ить файли workspace, якщо їх немає: `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`. - - Типова ідентичність: **C3‑PO** (протокольний дроїд). - - Пропускає провайдери каналів у dev mode (`OPENCLAW_SKIP_CHANNELS=1`). + - Default identity: **C3‑PO** (protocol droid). + - Пропускає channel providers у dev mode (`OPENCLAW_SKIP_CHANNELS=1`). -Процес скидання (свіжий старт): +Reset flow (fresh start): ```bash pnpm gateway:dev:reset ``` -`--dev` — це **глобальний** прапорець профілю, і деякі runner його поглинають. Якщо потрібно вказати його явно, використовуйте форму env var: +`--dev` — це **global** profile flag, і деякі runners його поглинають. Якщо потрібно прописати це явно, використовуйте форму env var: ```bash OPENCLAW_PROFILE=dev openclaw gateway --dev --reset @@ -228,11 +242,11 @@ OPENCLAW_PROFILE=dev openclaw gateway --dev --reset -`--reset` стирає конфігурацію, облікові дані, сесії та dev workspace (за допомогою -`trash`, а не `rm`), потім повторно створює типове dev-середовище. +`--reset` стирає config, credentials, sessions і dev workspace (через +`trash`, а не `rm`), потім повторно створює default dev setup. -Якщо non-dev gateway уже запущено (launchd або systemd), спочатку зупиніть його: +Якщо non-dev gateway уже запущено (launchd або systemd), спершу зупиніть його: ```bash openclaw gateway stop @@ -240,11 +254,11 @@ openclaw gateway stop -## Логування сирого потоку (OpenClaw) +## Логування raw stream (OpenClaw) -OpenClaw може логувати **сирий потік асистента** перед будь-якою фільтрацією/форматуванням. -Це найкращий спосіб побачити, чи reasoning надходить як прості текстові дельти -(або як окремі блоки thinking). +OpenClaw може логувати **raw assistant stream** перед будь-якою фільтрацією/форматуванням. +Це найкращий спосіб побачити, чи reasoning надходить як plain text deltas +(або як окремі thinking blocks). Увімкніть через CLI: @@ -252,7 +266,7 @@ OpenClaw може логувати **сирий потік асистента** pnpm gateway:watch --raw-stream ``` -Необов’язкове перевизначення шляху: +Optional path override: ```bash pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl @@ -265,39 +279,39 @@ OPENCLAW_RAW_STREAM=1 OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl ``` -Типовий файл: +Default file: `~/.openclaw/logs/raw-stream.jsonl` -## Логування сирих фрагментів (pi-mono) +## Логування raw chunk (pi-mono) -Щоб захопити **сирі OpenAI-сумісні фрагменти** до того, як їх буде розібрано на блоки, +Щоб захопити **raw OpenAI-compat chunks** до того, як вони будуть розпарсені на blocks, pi-mono надає окремий logger: ```bash PI_RAW_STREAM=1 ``` -Необов’язковий шлях: +Optional path: ```bash PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl ``` -Типовий файл: +Default file: `~/.pi-mono/logs/raw-openai-completions.jsonl` -> Примітка: це виводиться лише процесами, що використовують провайдер pi-mono +> Note: це випускається лише процесами, що використовують provider pi-mono > `openai-completions`. -## Примітки щодо безпеки +## Нотатки з безпеки -- Журнали сирого потоку можуть містити повні prompts, вивід інструментів і дані користувача. -- Зберігайте журнали локально й видаляйте їх після налагодження. -- Якщо ділитеся журналами, спочатку очистьте секрети та PII. +- Raw stream logs можуть містити повні prompts, tool output і user data. +- Зберігайте logs локально й видаляйте їх після налагодження. +- Якщо ділитеся logs, спершу очистьте secrets і PII. ## Пов’язане - [Усунення несправностей](/uk/help/troubleshooting) -- [Поширені запитання](/uk/help/faq) +- [FAQ](/uk/help/faq)