diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md
index 166886a9b..40cdff6b0 100644
--- a/docs/uk/help/testing.md
+++ b/docs/uk/help/testing.md
@@ -3,226 +3,229 @@ read_when:
- Запуск тестів локально або в CI
- Додавання регресійних тестів для помилок моделей/провайдерів
- Налагодження поведінки Gateway + агента
-summary: 'Комплект для тестування: набори модульних/e2e/живих тестів, ранери Docker і що охоплює кожен тест'
+summary: 'Набір для тестування: модульні, наскрізні та live-набори, Docker runners і що покриває кожен тест'
title: Тестування
x-i18n:
- generated_at: "2026-05-04T21:07:00Z"
+ generated_at: "2026-05-04T21:16:56Z"
model: gpt-5.5
provider: openai
- source_hash: f2c4210847ca14db8aebd17e3a5cf84cf09190ead1d34e8c3068eab20557dbf6
+ source_hash: 9fec86c0e3843a3ad0dcc686f2b942c202af7dd23c33cf55ba384a9643702030
source_path: help/testing.md
workflow: 16
---
-OpenClaw має три набори Vitest (модульний/інтеграційний, e2e, live) і невеликий набір
-ранерів Docker. Цей документ є посібником «як ми тестуємо»:
+OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір
+Docker-ранерів. Цей документ є посібником «як ми тестуємо»:
- Що покриває кожен набір (і що він свідомо _не_ покриває).
- Які команди запускати для типових робочих процесів (локально, перед push, налагодження).
- Як live-тести знаходять облікові дані та вибирають моделі/провайдерів.
-- Як додавати регресії для реальних проблем моделей/провайдерів.
+- Як додавати регресії для реальних проблем із моделями/провайдерами.
-**Стек QA (qa-lab, qa-channel, live транспортні лінії)** задокументовано окремо:
+**QA-стек (qa-lab, qa-channel, live transport lanes)** документовано окремо:
-- [Огляд QA](/uk/concepts/qa-e2e-automation) — архітектура, поверхня команд, написання сценаріїв.
-- [Матричний QA](/uk/concepts/qa-matrix) — довідка для `pnpm openclaw qa matrix`.
-- [Канал QA](/uk/channels/qa-channel) — синтетичний транспортний Plugin, який використовується сценаріями на основі репозиторію.
+- [Огляд QA](/uk/concepts/qa-e2e-automation) — архітектура, поверхня команд, створення сценаріїв.
+- [Matrix QA](/uk/concepts/qa-matrix) — довідник для `pnpm openclaw qa matrix`.
+- [QA channel](/uk/channels/qa-channel) — синтетичний транспортний Plugin, який використовують сценарії, підкріплені репозиторієм.
-Ця сторінка описує запуск звичайних наборів тестів і ранерів Docker/Parallels. Розділ нижче про специфічні для QA ранери ([Специфічні для QA ранери](#qa-specific-runners)) перелічує конкретні виклики `qa` і відсилає до наведених вище довідкових матеріалів.
+Ця сторінка описує запуск звичайних тестових наборів і Docker/Parallels-ранерів. Розділ про QA-специфічні ранери нижче ([QA-специфічні ранери](#qa-specific-runners)) перелічує конкретні виклики `qa` і відсилає до наведених вище довідників.
## Швидкий старт
-У більшості випадків:
+Більшість днів:
- Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test`
-- Швидший локальний запуск повного набору на машині з достатніми ресурсами: `pnpm test:max`
+- Швидший локальний запуск повного набору на просторій машині: `pnpm test:max`
- Прямий цикл спостереження Vitest: `pnpm test:watch`
-- Пряме націлювання на файл тепер також маршрутизує шляхи розширень/каналів: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
-- Під час ітерацій над одним збоєм спочатку віддавайте перевагу цільовим запускам.
-- QA-сайт на основі Docker: `pnpm qa:lab:up`
-- QA-лінія на основі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline`
+- Пряме таргетування файлів тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts`
+- Коли ви ітеруєте над одним збоєм, спочатку віддавайте перевагу таргетованим запускам.
+- Docker-підтримуваний QA-сайт: `pnpm qa:lab:up`
+- QA lane, підтримуваний Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline`
-Коли змінюєте тести або хочете мати більше впевненості:
+Коли ви змінюєте тести або хочете більшої впевненості:
- Gate покриття: `pnpm test:coverage`
- Набір E2E: `pnpm test:e2e`
-Під час налагодження реальних провайдерів/моделей (потрібні справжні облікові дані):
+Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані):
-- Live-набір (моделі + проби інструментів/зображень Gateway): `pnpm test:live`
-- Тихий запуск одного live-файла: `pnpm test:live -- src/agents/models.profiles.live.test.ts`
+- Live-набір (моделі + Gateway-зонди інструментів/зображень): `pnpm test:live`
+- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts`
- Звіти про продуктивність runtime: запустіть `OpenClaw Performance` з
`live_gpt54=true` для реального ходу агента `openai/gpt-5.4` або
`deep_profile=true` для артефактів CPU/heap/trace Kova. Щоденні заплановані запуски
- публікують артефакти ліній mock-provider, deep-profile і GPT 5.4 до
+ публікують артефакти mock-provider, deep-profile і GPT 5.4 lane до
`openclaw/clawgrit-reports`, коли налаштовано `CLAWGRIT_REPORTS_TOKEN`. Звіт
- mock-provider також містить показники запуску Gateway на рівні вихідного коду, пам’яті,
- plugin-навантаження, повторюваного fake-model hello-loop і запуску CLI.
-- Docker live-перебір моделей: `pnpm test:docker:live-models`
- - Кожна вибрана модель тепер виконує текстовий хід і невелику пробу в стилі читання файлу.
+ mock-provider також містить показники завантаження Gateway на рівні джерел, пам’яті,
+ plugin-pressure, повторюваного hello-loop fake-model і запуску CLI.
+- Docker live model sweep: `pnpm test:docker:live-models`
+ - Кожна вибрана модель тепер виконує текстовий хід і невеликий зонд у стилі читання файлу.
Моделі, метадані яких оголошують вхід `image`, також виконують крихітний хід із зображенням.
- Вимкніть додаткові проби за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або
+ Вимикайте додаткові зонди за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або
`OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера.
- Покриття CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні
- `OpenClaw Release Checks` обидва викликають багаторазовий workflow live/E2E з
- `include_live_suites: true`, що включає окремі Docker live matrix-завдання моделей,
- розбиті за провайдерами.
+ `OpenClaw Release Checks` обидва викликають багаторазовий live/E2E workflow з
+ `include_live_suites: true`, що включає окремі Docker live model
+ matrix-завдання, розбиті за провайдером.
- Для сфокусованих повторних запусків CI запустіть `OpenClaw Live And E2E Checks (Reusable)`
з `include_live_suites: true` і `live_models_only: true`.
- Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`
- плюс `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` та його
- запланованих/release викликачів.
-- Native Codex smoke-тест прив’язаного чату: `pnpm test:docker:live-codex-bind`
- - Запускає Docker live-лінію проти шляху app-server Codex, прив’язує синтетичне
- Slack DM за допомогою `/codex bind`, виконує `/codex fast` і
+ плюс `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його
+ запланованих/release-викликачів.
+- Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind`
+ - Запускає Docker live lane проти шляху Codex app-server, прив’язує синтетичний
+ Slack DM через `/codex bind`, виконує `/codex fast` і
`/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення зображення
- проходять через native прив’язку Plugin замість ACP.
-- Smoke-тест harness app-server Codex: `pnpm test:docker:live-codex-harness`
- - Запускає ходи агента Gateway через належний Plugin harness app-server Codex,
- перевіряє `/codex status` і `/codex models` і за замовчуванням виконує проби image,
- cron MCP, sub-agent і Guardian. Вимкніть пробу sub-agent за допомогою
- `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, коли ізолюєте інші збої app-server
- Codex. Для сфокусованої перевірки sub-agent вимкніть інші проби:
+ проходять через нативну прив’язку Plugin замість ACP.
+- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness`
+ - Запускає ходи агента Gateway через harness Codex app-server, що належить Plugin,
+ перевіряє `/codex status` і `/codex models`, а за замовчуванням виконує зонди image,
+ cron MCP, sub-agent і Guardian. Вимикайте зонд sub-agent за допомогою
+ `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, коли ізолюєте інші збої Codex
+ app-server. Для сфокусованої перевірки sub-agent вимкніть інші зонди:
`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`.
- Це завершується після проби sub-agent, якщо не встановлено
+ Це завершується після зонда sub-agent, якщо не встановлено
`OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0`.
-- Smoke-тест команди порятунку Crestodian: `pnpm test:live:crestodian-rescue-channel`
- - Додаткова перевірка з подвійним захистом для поверхні команди порятунку message-channel.
+- Crestodian rescue command smoke: `pnpm test:live:crestodian-rescue-channel`
+ - Опціональна додаткова перевірка поверхні команди порятунку message-channel.
Вона виконує `/crestodian status`, ставить у чергу постійну зміну моделі,
відповідає `/crestodian yes` і перевіряє шлях запису audit/config.
-- Docker smoke-тест планувальника Crestodian: `pnpm test:docker:crestodian-planner`
- - Запускає Crestodian у контейнері без конфігурації з фальшивим Claude CLI у `PATH`
- і перевіряє, що нечіткий fallback планувальника перетворюється на аудитований типізований
+- Crestodian planner Docker smoke: `pnpm test:docker:crestodian-planner`
+ - Запускає Crestodian у контейнері без конфігурації з фейковим Claude CLI у `PATH`
+ і перевіряє, що fuzzy planner fallback перетворюється на аудитований типізований
запис конфігурації.
-- Docker smoke-тест першого запуску Crestodian: `pnpm test:docker:crestodian-first-run`
- - Стартує з порожнього каталогу стану OpenClaw, маршрутизує bare `openclaw` до
- Crestodian, застосовує setup/model/agent/Discord Plugin + записи SecretRef,
- перевіряє конфігурацію та записи аудиту. Той самий шлях налаштування Ring 0 також
- покрито в QA Lab через
+- Crestodian first-run Docker smoke: `pnpm test:docker:crestodian-first-run`
+ - Починає з порожнього каталогу стану OpenClaw, маршрутизує голий `openclaw` до
+ Crestodian, застосовує setup/model/agent/Discord Plugin + SecretRef-записи,
+ перевіряє конфігурацію та audit-записи. Той самий шлях налаштування Ring 0
+ також покрито в QA Lab через
`pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`.
-- Smoke-тест вартості Moonshot/Kimi: із встановленим `MOONSHOT_API_KEY` запустіть
+- Moonshot/Kimi cost smoke: із встановленим `MOONSHOT_API_KEY` запустіть
`openclaw models list --provider moonshot --json`, потім запустіть ізольований
`openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json`
проти `moonshot/kimi-k2.6`. Перевірте, що JSON повідомляє Moonshot/K2.6, а
- транскрипт помічника зберігає нормалізоване `usage.cost`.
+ транскрипт асистента зберігає нормалізований `usage.cost`.
-Коли потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче.
+Коли вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через env allowlist vars, описані нижче.
-## Специфічні для QA ранери
+## QA-специфічні ранери
-Ці команди розташовані поруч з основними наборами тестів, коли потрібен реалізм QA-lab:
+Ці команди розташовані поруч із головними тестовими наборами, коли потрібна реалістичність QA-lab:
-CI запускає QA Lab у спеціальних workflow. Agentic parity вкладено в
-`QA-Lab - All Lanes` і release validation, а не в окремий PR workflow.
-Широка валідація має використовувати `Full Release Validation` з
+CI запускає QA Lab у виділених workflow. Agentic parity вкладено під
+`QA-Lab - All Lanes` і release validation, а не окремий PR workflow.
+Широка перевірка має використовувати `Full Release Validation` з
`rerun_group=qa-parity` або QA-групу release-checks. `QA-Lab - All Lanes`
-запускається щоночі на `main` і з ручного dispatch з mock parity-лінією, live
-Matrix-лінією, керованою Convex live Telegram-лінією і керованою Convex live Discord
-лінією як паралельними завданнями. Запланований QA і release checks явно передають Matrix
-`--profile fast`, тоді як Matrix CLI і вхід ручного workflow за замовчуванням
-залишаються `all`; ручний dispatch може розбити `all` на завдання `transport`,
-`media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release
-Checks` запускає parity плюс швидкі лінії Matrix і Telegram перед затвердженням релізу,
-використовуючи `mock-openai/gpt-5.5` для release transport checks, щоб вони залишалися
-детермінованими та уникали звичайного запуску provider-plugin. Ці live transport
-Gateway вимикають пошук пам’яті; поведінка пам’яті залишається покритою QA parity
-наборами.
+запускається щоночі на `main` і з ручного dispatch з mock parity lane, live
+Matrix lane, Convex-managed live Telegram lane і Convex-managed live Discord
+lane як паралельними завданнями. Заплановані QA та release checks явно передають Matrix
+`--profile fast`, тоді як Matrix CLI і manual workflow input
+за замовчуванням залишаються `all`; ручний dispatch може розбити `all` на `transport`,
+`media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli` завдання. `OpenClaw Release
+Checks` запускає parity плюс fast Matrix і Telegram lanes перед release
+approval, використовуючи `mock-openai/gpt-5.5` для release transport checks, щоб вони залишалися
+детермінованими й уникали звичайного запуску provider-plugin. Ці live transport
+gateways вимикають пошук у пам’яті; поведінка пам’яті лишається покритою QA parity
+suites.
Full release live media shards використовують
`ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, який уже має
-`ffmpeg` і `ffprobe`. Docker live model/backend shards використовують спільний образ
-`ghcr.io/openclaw/openclaw-live-test:`, зібраний один раз для вибраного
-коміту, а потім завантажують його з `OPENCLAW_SKIP_DOCKER_BUILD=1` замість повторної збірки
+`ffmpeg` і `ffprobe`. Docker live model/backend shards використовують спільний
+образ `ghcr.io/openclaw/openclaw-live-test:`, зібраний один раз для вибраного
+commit, а потім витягують його з `OPENCLAW_SKIP_DOCKER_BUILD=1` замість повторної збірки
всередині кожного shard.
- `pnpm openclaw qa suite`
- - Запускає сценарії QA, підкріплені репозиторієм, безпосередньо на хості.
+ - Запускає QA-сценарії, прив’язані до репозиторію, безпосередньо на хості.
- За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими
- працівниками gateway. `qa-channel` за замовчуванням має паралельність 4 (обмежено
+ Gateway-воркерами. `qa-channel` за замовчуванням має паралельність 4 (обмежену
кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати
- кількість працівників, або `--concurrency 1` для старішої послідовної лінії.
- - Завершується з ненульовим кодом, коли будь-який сценарій не вдається. Використовуйте `--allow-failures`, коли
- потрібні артефакти без коду завершення, що позначає помилку.
+ кількість воркерів, або `--concurrency 1` для старішої послідовної лінії.
+ - Завершується з ненульовим кодом, коли будь-який сценарій завершується невдало. Використовуйте `--allow-failures`, коли
+ потрібні артефакти без коду завершення з помилкою.
- Підтримує режими провайдера `live-frontier`, `mock-openai` і `aimock`.
`aimock` запускає локальний сервер провайдера на базі AIMock для експериментального
- покриття фікстур і моків протоколу, не замінюючи лінію `mock-openai`, обізнану зі сценаріями.
+ покриття фікстур і моків протоколу, не замінюючи сценарно-орієнтовану
+ лінію `mock-openai`.
- `pnpm test:plugins:kitchen-sink-live`
- - Запускає живий випробувальний комплекс OpenAI Kitchen Sink plugin через QA Lab. Він
- встановлює зовнішній пакет Kitchen Sink, перевіряє інвентар поверхні plugin SDK,
- перевіряє `/healthz` і `/readyz`, записує докази CPU/RSS gateway,
- запускає живий хід OpenAI і перевіряє діагностику для ворожих сценаріїв.
- Потребує живої автентифікації OpenAI, наприклад `OPENAI_API_KEY`.
+ - Запускає живий набір випробувань Plugin OpenAI Kitchen Sink через QA Lab. Він
+ встановлює зовнішній пакет Kitchen Sink, перевіряє інвентар поверхні SDK Plugin,
+ зондує `/healthz` і `/readyz`, записує докази CPU/RSS Gateway,
+ запускає живий хід OpenAI і перевіряє змагальну діагностику.
+ Потребує живої автентифікації OpenAI, наприклад `OPENAI_API_KEY`. У гідратованих сесіях Testbox
+ автоматично підтягує профіль живої автентифікації Testbox, коли наявний
+ помічник `openclaw-testbox-env`.
- `pnpm test:gateway:cpu-scenarios`
- - Запускає бенчмарк запуску gateway плюс невеликий пакет мок-сценаріїв QA Lab
+ - Запускає бенч запуску Gateway разом із невеликим пакетом мок-сценаріїв QA Lab
(`channel-chat-baseline`, `memory-failure-fallback`,
`gateway-restart-inflight-run`) і записує об’єднаний підсумок спостережень CPU
у `.artifacts/gateway-cpu-scenarios/`.
- - За замовчуванням позначає лише тривалі спостереження високого CPU (`--cpu-core-warn`
+ - За замовчуванням позначає лише сталі спостереження гарячого CPU (`--cpu-core-warn`
плюс `--hot-wall-warn-ms`), тому короткі сплески під час запуску записуються як метрики
- без вигляду регресії, де gateway був завантажений хвилинами.
- - Використовує зібрані артефакти `dist`; спершу запустіть збірку, якщо checkout ще не
- має свіжого runtime-виводу.
+ і не виглядають як регресія Gateway із багатохвилинним завантаженням CPU.
+ - Використовує зібрані артефакти `dist`; спершу запустіть збірку, якщо checkout ще не має
+ свіжого runtime-виводу.
- `pnpm openclaw qa suite --runner multipass`
- - Запускає той самий набір QA усередині одноразової Linux VM Multipass.
- - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості.
+ - Запускає той самий QA-набір у одноразовій Linux-VM Multipass.
+ - Зберігає таку саму поведінку вибору сценаріїв, як `qa suite` на хості.
- Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`.
- - Живі запуски передають підтримувані входи автентифікації QA, практичні для гостьової системи:
- ключі провайдера з env, шлях до конфігурації живого провайдера QA і `CODEX_HOME`,
+ - Живі запуски переспрямовують підтримувані QA-вхідні дані автентифікації, практичні для гостьової системи:
+ ключі провайдерів на базі env, шлях до конфігурації живого QA-провайдера та `CODEX_HOME`,
коли він наявний.
- - Каталоги виводу мають залишатися під коренем репозиторію, щоб гостьова система могла записувати назад через
- змонтований workspace.
- - Записує звичайний звіт QA + підсумок і журнали Multipass у
+ - Каталоги виводу мають залишатися в корені репозиторію, щоб гостьова система могла записувати назад через
+ змонтований робочий простір.
+ - Записує звичайний QA-звіт і підсумок, а також логи Multipass у
`.artifacts/qa-e2e/...`.
- `pnpm qa:lab:up`
- - Запускає Docker-підкріплений сайт QA для операторської QA-роботи.
+ - Запускає QA-сайт на базі Docker для операторської QA-роботи.
- `pnpm test:docker:npm-onboard-channel-agent`
- - Збирає npm tarball із поточного checkout, встановлює його глобально в
- Docker, запускає неінтерактивний onboarding із ключем OpenAI API, за замовчуванням налаштовує Telegram,
- перевіряє, що запакований runtime plugin завантажується без стартового
- ремонту залежностей, запускає doctor і виконує один локальний agent turn проти
- mocked OpenAI endpoint.
- - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму лінію
- packaged-install із Discord.
+ - Збирає npm-tarball із поточного checkout, встановлює його глобально в
+ Docker, запускає неінтерактивний онбординг із ключем OpenAI API, налаштовує Telegram
+ за замовчуванням, перевіряє, що запакований runtime Plugin завантажується без startup
+ dependency repair, запускає doctor і виконує один локальний хід агента проти
+ змоканого endpoint OpenAI.
+ - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму лінію packaged-install
+ з Discord.
- `pnpm test:docker:session-runtime-context`
- - Запускає детермінований Docker smoke для зібраного застосунку щодо вбудованих transcript runtime context.
+ - Запускає детермінований Docker smoke для зібраного застосунку для transcript-ів вбудованого runtime context.
Він перевіряє, що прихований runtime context OpenClaw зберігається як
- custom message без відображення, а не витікає у видимий user turn,
+ невідображуване кастомне повідомлення замість витоку у видимий хід користувача,
потім засіває уражений зламаний session JSONL і перевіряє, що
- `openclaw doctor --fix` переписує його до active branch із backup.
+ `openclaw doctor --fix` переписує його на активну гілку з резервною копією.
- `pnpm test:docker:npm-telegram-live`
- - Встановлює кандидат пакета OpenClaw у Docker, запускає onboarding встановленого пакета,
- налаштовує Telegram через встановлений CLI, потім повторно використовує
- live Telegram QA lane з цим встановленим пакетом як SUT Gateway.
- - За замовчуванням `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; задайте
+ - Встановлює кандидат пакета OpenClaw у Docker, запускає онбординг встановленого пакета,
+ налаштовує Telegram через встановлений CLI, а потім повторно використовує
+ живу QA-лінію Telegram із цим встановленим пакетом як SUT Gateway.
+ - За замовчуванням використовує `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; задайте
`OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` або
- `OPENCLAW_CURRENT_PACKAGE_TGZ`, щоб протестувати resolved local tarball замість
+ `OPENCLAW_CURRENT_PACKAGE_TGZ`, щоб тестувати розв’язаний локальний tarball замість
встановлення з registry.
- - Використовує ті самі Telegram env credentials або джерело облікових даних Convex, що й
- `pnpm openclaw qa telegram`. Для CI/release automation задайте
+ - Використовує ті самі env-облікові дані Telegram або джерело облікових даних Convex, що й
+ `pnpm openclaw qa telegram`. Для CI/автоматизації релізу задайте
`OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` плюс
- `OPENCLAW_QA_CONVEX_SITE_URL` і role secret. Якщо
- `OPENCLAW_QA_CONVEX_SITE_URL` і Convex role secret наявні в CI,
- Docker wrapper автоматично вибирає Convex.
- - Wrapper перевіряє env облікових даних Telegram або Convex на хості перед
+ `OPENCLAW_QA_CONVEX_SITE_URL` і рольовий секрет. Якщо
+ `OPENCLAW_QA_CONVEX_SITE_URL` і рольовий секрет Convex наявні в CI,
+ Docker-обгортка автоматично вибирає Convex.
+ - Обгортка перевіряє env облікових даних Telegram або Convex на хості перед
роботою Docker build/install. Задавайте `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1`
- лише тоді, коли навмисно налагоджуєте pre-credential setup.
+ лише під час навмисного налагодження підготовки до облікових даних.
- `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільну
`OPENCLAW_QA_CREDENTIAL_ROLE` лише для цієї лінії.
- - GitHub Actions надає цю лінію як ручний maintainer workflow
+ - GitHub Actions надає цю лінію як ручний maintainer-workflow
`NPM Telegram Beta E2E`. Він не запускається під час merge. Workflow використовує
- середовище `qa-live-shared` і Convex CI credential leases.
-- GitHub Actions також надає `Package Acceptance` для side-run product proof
- проти одного candidate package. Він приймає trusted ref, published npm spec,
- HTTPS tarball URL плюс SHA-256 або tarball artifact з іншого запуску, завантажує
- нормалізований `openclaw-current.tgz` як `package-under-test`, потім запускає
- наявний Docker E2E scheduler із smoke, package, product, full або custom
- lane profiles. Задайте `telegram_mode=mock-openai` або `live-frontier`, щоб запустити
- Telegram QA workflow проти того самого artifact `package-under-test`.
- - Останній beta product proof:
+ середовище `qa-live-shared` і lease-и облікових даних Convex CI.
+- GitHub Actions також надає `Package Acceptance` для побічного продуктового доказу
+ проти одного кандидата пакета. Він приймає довірений ref, опубліковану npm-специфікацію,
+ HTTPS-URL tarball плюс SHA-256 або tarball artifact з іншого run, завантажує
+ нормалізований `openclaw-current.tgz` як `package-under-test`, а потім запускає
+ наявний Docker E2E scheduler із профілями ліній smoke, package, product, full або custom.
+ Задайте `telegram_mode=mock-openai` або `live-frontier`, щоб запустити
+ QA-workflow Telegram проти того самого артефакта `package-under-test`.
+ - Доказ останньої beta для продукту:
```bash
gh workflow run package-acceptance.yml --ref main \
@@ -232,7 +235,7 @@ gh workflow run package-acceptance.yml --ref main \
-f telegram_mode=mock-openai
```
-- Доказ exact tarball URL потребує digest:
+- Доказ точного URL tarball потребує digest:
```bash
gh workflow run package-acceptance.yml --ref main \
@@ -242,7 +245,7 @@ gh workflow run package-acceptance.yml --ref main \
-f suite_profile=package
```
-- Artifact proof завантажує tarball artifact з іншого Actions run:
+- Доказ артефакта завантажує tarball artifact з іншого run Actions:
```bash
gh workflow run package-acceptance.yml --ref main \
@@ -253,83 +256,83 @@ gh workflow run package-acceptance.yml --ref main \
```
- `pnpm test:docker:plugins`
- - Пакує й встановлює поточну збірку OpenClaw у Docker, запускає Gateway
- з налаштованим OpenAI, потім вмикає bundled channel/plugins через config
- edits.
- - Перевіряє, що setup discovery залишає неналаштовані downloadable plugins відсутніми,
- перший налаштований doctor repair явно встановлює кожен missing downloadable
- plugin, а другий restart не запускає hidden dependency
+ - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway
+ з налаштованим OpenAI, а потім вмикає bundled channel/plugins через редагування config.
+ - Перевіряє, що setup discovery залишає неналаштовані завантажувані plugins відсутніми,
+ перший налаштований doctor repair явно встановлює кожен відсутній завантажуваний
+ plugin, а другий restart не запускає прихований dependency
repair.
- - Також встановлює відому старішу npm baseline, вмикає Telegram перед запуском
+ - Також встановлює відомий старіший npm baseline, вмикає Telegram перед запуском
`openclaw update --tag ` і перевіряє, що post-update doctor кандидата
- очищає debris legacy plugin dependency без harness-side postinstall repair.
+ очищає сміття legacy-залежностей Plugin без
+ postinstall repair з боку harness.
- `pnpm test:parallels:npm-update`
- - Запускає native packaged-install update smoke на гостях Parallels. Кожна
+ - Запускає native packaged-install update smoke у гостьових системах Parallels. Кожна
вибрана платформа спершу встановлює запитаний baseline package, потім запускає
- встановлену команду `openclaw update` у тому самому guest і перевіряє
- installed version, update status, gateway readiness і один local agent
- turn.
+ встановлену команду `openclaw update` у тій самій гостьовій системі й перевіряє
+ встановлену версію, статус оновлення, готовність Gateway і один локальний
+ хід агента.
- Використовуйте `--platform macos`, `--platform windows` або `--platform linux` під час
- ітерації на одному guest. Використовуйте `--json` для summary artifact path і
- per-lane status.
- - Лінія OpenAI за замовчуванням використовує `openai/gpt-5.5` для live agent-turn proof.
+ ітерацій на одній гостьовій системі. Використовуйте `--json` для шляху до summary artifact і
+ статусу кожної лінії.
+ - Лінія OpenAI за замовчуванням використовує `openai/gpt-5.5` для живого proof ходу агента.
Передайте `--model ` або задайте
`OPENCLAW_PARALLELS_OPENAI_MODEL`, коли навмисно перевіряєте іншу
модель OpenAI.
- - Обгорніть довгі локальні запуски timeout на хості, щоб зависання транспорту Parallels не
- спожили решту testing window:
+ - Обгорніть довгі локальні запуски в host timeout, щоб зависання транспорту Parallels не могли
+ забрати решту тестового вікна:
```bash
timeout --foreground 150m pnpm test:parallels:npm-update -- --json
timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json
```
- - Скрипт записує вкладені lane logs у `/tmp/openclaw-parallels-npm-update.*`.
+ - Скрипт записує вкладені логи ліній у `/tmp/openclaw-parallels-npm-update.*`.
Перегляньте `windows-update.log`, `macos-update.log` або `linux-update.log`
- перед припущенням, що outer wrapper завис.
- - Windows update може витрачати 10-15 хвилин на post-update doctor і package
- update work на cold guest; це все ще нормально, коли nested npm
+ перед припущенням, що зовнішня обгортка зависла.
+ - Оновлення Windows може витрачати 10-15 хвилин на post-update doctor і package
+ update work у холодній гостьовій системі; це все ще справний стан, коли вкладений npm
debug log просувається.
- - Не запускайте цей aggregate wrapper паралельно з окремими Parallels
- macOS, Windows або Linux smoke lanes. Вони ділять VM state і можуть конфліктувати під час
- snapshot restore, package serving або guest gateway state.
- - Post-update proof запускає звичайну bundled plugin surface, оскільки
- capability facades, як-от speech, image generation і media
- understanding, завантажуються через bundled runtime APIs, навіть коли сам agent
- turn перевіряє лише просту text response.
+ - Не запускайте цю агрегатну обгортку паралельно з окремими smoke-лініями Parallels
+ macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати під час
+ відновлення snapshot, serving package або стану Gateway у гостьовій системі.
+ - Post-update proof запускає звичайну поверхню bundled Plugin, оскільки
+ capability facades, такі як мовлення, генерація зображень і розуміння media,
+ завантажуються через bundled runtime APIs, навіть коли сам хід агента
+ перевіряє лише просту текстову відповідь.
- `pnpm openclaw qa aimock`
- - Запускає лише локальний provider server AIMock для прямого protocol smoke
+ - Запускає лише локальний сервер провайдера AIMock для прямого protocol smoke
testing.
- `pnpm openclaw qa matrix`
- - Запускає Matrix live QA lane проти одноразового Docker-backed Tuwunel homeserver. Лише source-checkout — packaged installs не постачають `qa-lab`.
- - Повний CLI, profile/scenario catalog, env vars і artifact layout: [Matrix QA](/uk/concepts/qa-matrix).
+ - Запускає живу QA-лінію Matrix проти одноразового homeserver Tuwunel на базі Docker. Лише source-checkout — packaged installs не постачають `qa-lab`.
+ - Повний CLI, каталог профілів/сценаріїв, env vars і layout артефактів: [QA Matrix](/uk/concepts/qa-matrix).
- `pnpm openclaw qa telegram`
- - Запускає Telegram live QA lane проти реальної приватної групи, використовуючи токени driver і SUT bot з env.
- - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Group id має бути числовим Telegram chat id.
- - Підтримує `--credential-source convex` для спільних pooled credentials. За замовчуванням використовуйте env mode або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases.
- - Завершується з ненульовим кодом, коли будь-який сценарій не вдається. Використовуйте `--allow-failures`, коли
- потрібні артефакти без коду завершення, що позначає помилку.
- - Потребує двох різних bots в одній приватній групі, причому SUT bot має відкривати Telegram username.
- - Для стабільного bot-to-bot observation увімкніть Bot-to-Bot Communication Mode в `@BotFather` для обох bots і переконайтеся, що driver bot може спостерігати group bot traffic.
- - Записує Telegram QA report, summary і observed-messages artifact у `.artifacts/qa-e2e/...`. Replying scenarios містять RTT від driver send request до observed SUT reply.
+ - Запускає живу QA-лінію Telegram проти реальної приватної групи, використовуючи токени driver і SUT bot з env.
+ - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Group id має бути числовим chat id Telegram.
+ - Підтримує `--credential-source convex` для спільних pooled credentials. Використовуйте env mode за замовчуванням або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases.
+ - Завершується з ненульовим кодом, коли будь-який сценарій завершується невдало. Використовуйте `--allow-failures`, коли
+ потрібні артефакти без коду завершення з помилкою.
+ - Потребує двох різних ботів в одній приватній групі, причому SUT bot має мати Telegram username.
+ - Для стабільного bot-to-bot спостереження увімкніть Bot-to-Bot Communication Mode в `@BotFather` для обох ботів і переконайтеся, що driver bot може спостерігати group bot traffic.
+ - Записує Telegram QA report, summary і observed-messages artifact у `.artifacts/qa-e2e/...`. Replying scenarios містять RTT від driver send request до спостереженої відповіді SUT.
-Live transport lanes мають один стандартний контракт, щоб нові transports не розходилися; per-lane coverage matrix розміщено в [Огляд QA → Live transport coverage](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` — це широкий synthetic suite і не є частиною цієї matrix.
+Живі транспортні лінії спільно використовують один стандартний контракт, щоб нові транспорти не розходилися; матриця покриття кожної лінії міститься в [огляд QA → Покриття живого транспорту](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` є широким синтетичним набором і не входить до цієї матриці.
### Спільні облікові дані Telegram через Convex (v1)
Коли `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) увімкнено для
-`openclaw qa telegram`, QA lab отримує exclusive lease із Convex-backed pool, надсилає heartbeats
-для цього lease, доки lane виконується, і звільняє lease під час shutdown.
+`openclaw qa telegram`, QA lab отримує ексклюзивний lease з пулу на базі Convex, виконує Heartbeat
+цього lease, поки лінія працює, і звільняє lease під час shutdown.
-Reference Convex project scaffold:
+Еталонний scaffold проєкту Convex:
- `qa/convex-credential-broker/`
Обов’язкові env vars:
- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`)
-- Один secret для вибраної ролі:
+- Один секрет для вибраної ролі:
- `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer`
- `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci`
- Вибір credential role:
@@ -344,14 +347,14 @@ Reference Convex project scaffold:
- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (за замовчуванням `15000`)
- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (за замовчуванням `/qa-credentials/v1`)
- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id)
-- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` Convex URLs для local-only development.
+- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL-адреси Convex для локальної розробки.
-`OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://` у звичайній роботі.
+`OPENCLAW_QA_CONVEX_SITE_URL` у звичайній роботі має використовувати `https://`.
-Адміністративні команди супровідника (pool add/remove/list) вимагають саме
+Команди адміністратора для супровідників (додати/видалити/перелічити пул) вимагають саме
`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`.
-CLI-допоміжні команди для супровідників:
+Допоміжні CLI-команди для супровідників:
```bash
pnpm openclaw qa credentials doctor
@@ -360,9 +363,9 @@ pnpm openclaw qa credentials list --kind telegram
pnpm openclaw qa credentials remove --credential-id
```
-Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, секрети брокера,
-префікс endpoint, HTTP-таймаут і доступність admin/list без виведення
-значень секретів. Використовуйте `--json` для машинозчитуваного виводу в скриптах і CI
+Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, секрети broker,
+префікс endpoint, HTTP timeout і доступність admin/list без виведення
+значень секретів. Використовуйте `--json` для машинозчитуваного виводу у скриптах і CI
утилітах.
Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`):
@@ -383,462 +386,461 @@ pnpm openclaw qa credentials remove --credential-id
- `POST /admin/remove` (лише секрет супровідника)
- Запит: `{ credentialId, actorId }`
- Успіх: `{ status: "ok", changed, credential }`
- - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }`
+ - Захист активної lease: `{ status: "error", code: "LEASE_ACTIVE", ... }`
- `POST /admin/list` (лише секрет супровідника)
- Запит: `{ kind?, status?, includePayload?, limit? }`
- Успіх: `{ status: "ok", credentials, count }`
-Форма payload для виду Telegram:
+Форма payload для типу Telegram:
- `{ groupId: string, driverToken: string, sutToken: string }`
-- `groupId` має бути рядком числового ідентифікатора чату Telegram.
+- `groupId` має бути числовим рядком ідентифікатора чату Telegram.
- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє неправильно сформовані payload.
### Додавання каналу до QA
-Архітектура та назви допоміжних сценарних компонентів для нових адаптерів каналів описані в [огляді QA → Додавання каналу](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна вимога: реалізувати транспортний runner на спільному host seam `qa-lab`, оголосити `qaRunners` у маніфесті plugin, змонтувати як `openclaw qa ` і створити сценарії в `qa/scenarios/`.
+Архітектура й назви допоміжних сценарних функцій для нових адаптерів каналів описані в [огляді QA → Додавання каналу](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна планка: реалізувати transport runner на спільному host seam `qa-lab`, оголосити `qaRunners` у маніфесті Plugin, змонтувати як `openclaw qa ` і створити сценарії в `qa/scenarios/`.
## Набори тестів (що де запускається)
-Сприймайте набори як «зростання реалістичності» (і зростання нестабільності/вартості):
+Сприймайте набори як “зростання реалістичності” (і зростання нестабільності/вартості):
### Модульні / інтеграційні (типово)
- Команда: `pnpm test`
-- Конфігурація: нецільові запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати багатопроєктні шарди в поконфігураційні проєкти для паралельного планування
-- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts` і `test/**/*.test.ts`; модульні тести UI запускаються в окремому шарді `unit-ui`
+- Конфігурація: нецільові запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати багатопроєктні шарди в попроєктні конфігурації для паралельного планування
+- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts` і `test/**/*.test.ts`; модульні тести UI запускаються у виділеному шарді `unit-ui`
- Обсяг:
- Чисті модульні тести
- - Внутрішньопроцесні інтеграційні тести (автентифікація gateway, маршрутизація, інструменти, parsing, config)
- - Детерміновані регресії для відомих багів
+ - Внутрішньопроцесні інтеграційні тести (автентифікація Gateway, маршрутизація, tooling, parsing, config)
+ - Детерміновані регресії для відомих помилок
- Очікування:
- Запускається в CI
- Реальні ключі не потрібні
- Має бути швидким і стабільним
- - Тести резолвера та завантажувача публічної поверхні мають доводити широку fallback-поведінку `api.js` і
- `runtime-api.js` за допомогою згенерованих крихітних plugin-фікстур, а не
- реальних source API вбудованого plugin. Реальні завантаження API plugin належать до
- contract/integration-наборів, власником яких є plugin.
+ - Тести resolver і public-surface loader мають доводити широку fallback-поведінку `api.js` і
+ `runtime-api.js` зі згенерованими малими фікстурами Plugin, а не
+ реальними API джерел вбудованих Plugin. Завантаження API реальних Plugin належать до
+ contract/integration наборів, якими володіє Plugin.
-
+
- - Нецільовий `pnpm test` запускає дванадцять менших конфігурацій шардів (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project процесу. Це знижує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension витісняти непов’язані набори.
- - `pnpm test --watch` і далі використовує native root граф проєктів `vitest.config.ts`, бо multi-shard watch loop непрактичний.
- - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку спрямовують явні цілі файлів/директорій через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості старту root project.
- - `pnpm test:changed` типово розгортає змінені git-шляхи в дешеві scoped lanes: прямі редагування тестів, сусідні файли `*.test.ts`, явні source-мапінги та локальні залежні елементи import graph. Редагування config/setup/package не запускають широкі тести, якщо явно не використати `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`.
- - `pnpm check:changed` є звичайним розумним локальним check gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata, live Docker tooling і tooling, а потім запускає відповідні команди typecheck, lint і guard. Він не запускає Vitest-тести; для тестового доказу викликайте `pnpm test:changed` або явний `pnpm test `. Version bump лише для release metadata запускають цільові перевірки version/config/root-dependency з guard, який відхиляє package-зміни поза верхньорівневим полем version.
- - Редагування live Docker ACP harness запускають сфокусовані перевірки: синтаксис shell для скриптів live Docker auth і dry-run планувальника live Docker. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; зміни dependency, export, version та інші package-surface редагування й далі використовують ширші guards.
- - Import-light модульні тести з agents, commands, plugins, auto-reply helpers, `plugin-sdk` і подібних чистих utility-зон спрямовуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes.
- - Вибрані source-файли helpers у `plugin-sdk` і `commands` також маплять changed-mode запуски на явні сусідні тести в цих легких lanes, тож редагування helpers уникають повторного запуску повного важкого набору для цієї директорії.
- - `auto-reply` має окремі кошики для верхньорівневих core helpers, верхньорівневих інтеграційних тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково розділяє піддерево reply на шарди agent-runner, dispatch і commands/state-routing, щоб один import-heavy кошик не володів усім хвостом Node.
- - Звичайний PR/main CI навмисно пропускає batch sweep extension і release-only шард `agentic-plugins`. Full Release Validation запускає окремий дочірній workflow `Plugin Prerelease` для цих plugin/extension-heavy наборів на release candidates.
+ - Нецільовий `pnpm test` запускає дванадцять менших конфігурацій шардів (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного величезного нативного процесу root-project. Це зменшує пікове RSS на завантажених машинах і не дає роботі auto-reply/extension витісняти непов’язані набори.
+ - `pnpm test --watch` і далі використовує нативний граф проєктів кореневого `vitest.config.ts`, бо багатоshardовий watch loop непрактичний.
+ - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку спрямовують явні цілі файлів/каталогів через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску кореневого проєкту.
+ - `pnpm test:changed` типово розгортає змінені git-шляхи в дешеві scoped lanes: прямі правки тестів, сусідні файли `*.test.ts`, явні зіставлення джерел і локальні залежні з import-graph. Правки config/setup/package не запускають широкі тести, якщо ви явно не використаєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`.
+ - `pnpm check:changed` є звичайним розумним локальним check gate для вузької роботи. Він класифікує diff на core, тести core, extensions, тести extension, apps, docs, release metadata, live Docker tooling і tooling, а потім запускає відповідні команди typecheck, lint і guard. Він не запускає тести Vitest; для доказу тестами викликайте `pnpm test:changed` або явний `pnpm test `. Підняття версій лише в release metadata запускає цільові перевірки version/config/root-dependency із guard, який відхиляє зміни package поза верхньорівневим полем версії.
+ - Правки live Docker ACP harness запускають сфокусовані перевірки: синтаксис shell для скриптів live Docker auth і dry-run планувальника live Docker. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; dependency, export, version та інші правки package-surface і далі використовують ширші guard.
+ - Import-light модульні тести з agents, commands, plugins, auto-reply helpers, `plugin-sdk` і схожих чистих utility-ділянок спрямовуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes.
+ - Вибрані файли джерел helpers `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними сусідніми тестами в цих light lanes, тож правки helpers не перезапускають увесь важкий набір для цього каталогу.
+ - `auto-reply` має виділені buckets для верхньорівневих core helpers, верхньорівневих інтеграційних тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково розділяє піддерево reply на шарди agent-runner, dispatch і commands/state-routing, щоб один import-heavy bucket не володів усім хвостом Node.
+ - Звичайний PR/main CI навмисно пропускає пакетний sweep extension і release-only шард `agentic-plugins`. Full Release Validation dispatch окремо запускає дочірній workflow `Plugin Prerelease` для цих plugin/extension-heavy наборів на release candidates.
- - Коли змінюєте вхідні дані discovery для message-tool або runtime
- context compaction, зберігайте обидва рівні покриття.
- - Додавайте сфокусовані helper-регресії для чистих меж routing і normalization.
+ - Коли змінюєте вхідні дані discovery message-tool або runtime-контекст Compaction,
+ зберігайте обидва рівні покриття.
+ - Додавайте сфокусовані регресії helpers для чистих меж маршрутизації та нормалізації.
- Підтримуйте справність інтеграційних наборів embedded runner:
`src/agents/pi-embedded-runner/compact.hooks.test.ts`,
`src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і
`src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`.
- - Ці набори перевіряють, що scoped ids і поведінка compaction і далі проходять
- через реальні шляхи `run.ts` / `compact.ts`; helper-only тести
- не є достатньою заміною для цих інтеграційних шляхів.
+ - Ці набори перевіряють, що scoped ids і поведінка Compaction і далі проходять
+ через реальні шляхи `run.ts` / `compact.ts`; тести лише helpers
+ не є достатньою заміною цих інтеграційних шляхів.
-
+
- Базова конфігурація Vitest типово використовує `threads`.
- Спільна конфігурація Vitest фіксує `isolate: false` і використовує
- non-isolated runner у root projects, e2e і live configs.
- - Root UI lane зберігає свій setup `jsdom` і optimizer, але також працює на
- спільному non-isolated runner.
- - Кожен шард `pnpm test` успадковує ті самі типові налаштування `threads` + `isolate: false`
+ неізольований runner у кореневих проєктах, e2e і live config.
+ - Коренева UI lane зберігає свій setup `jsdom` і optimizer, але теж працює на
+ спільному неізольованому runner.
+ - Кожен шард `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false`
зі спільної конфігурації Vitest.
- - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node
- процесів Vitest, щоб зменшити V8 compile churn під час великих локальних запусків.
- Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною
- поведінкою V8.
+ - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх процесів Node
+ Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків.
+ Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8.
- `pnpm changed:lanes` показує, які архітектурні lanes запускає diff.
- - Pre-commit hook виконує лише форматування. Він повторно staged відформатовані файли й
+ - Pre-commit hook виконує лише форматування. Він повторно stage-ить відформатовані файли і
не запускає lint, typecheck або тести.
- Запускайте `pnpm check:changed` явно перед handoff або push, коли вам
- потрібен smart local check gate.
- - `pnpm test:changed` типово проходить через дешеві scoped lanes. Використовуйте
- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли agent
- вирішує, що редагування harness, config, package або contract справді потребує ширшого
+ потрібен розумний локальний check gate.
+ - `pnpm test:changed` типово маршрутизує через дешеві scoped lanes. Використовуйте
+ `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли агент
+ вирішує, що правка harness, config, package або contract справді потребує ширшого
покриття Vitest.
- - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку routing,
- лише з вищою межею workers.
- - Локальне auto-scaling workers навмисно консервативне й знижує активність,
- коли load average хоста вже високий, тож кілька одночасних
+ - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації,
+ лише з вищим worker cap.
+ - Локальне auto-scaling workers навмисно консервативне й відступає,
+ коли середнє навантаження host уже високе, тож кілька одночасних
запусків Vitest типово завдають менше шкоди.
- - Базова конфігурація Vitest позначає projects/config файли як
- `forceRerunTriggers`, щоб changed-mode reruns залишалися коректними, коли змінюється
+ - Базова конфігурація Vitest позначає проєкти/config файли як
+ `forceRerunTriggers`, щоб reruns у changed-mode залишалися коректними, коли змінюється
test wiring.
- Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних
- хостах; задайте `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете
- одну явну cache location для прямого profiling.
+ hosts; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете
+ одне явне розташування cache для прямого profiling.
- - `pnpm test:perf:imports` вмикає звітування Vitest про import-duration разом із
- import-breakdown output.
- - `pnpm test:perf:imports:changed` звужує той самий profiling view до
- файлів, змінених від `origin/main`.
+ - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість import плюс
+ вивід import-breakdown.
+ - `pnpm test:perf:imports:changed` обмежує той самий profiling view
+ файлами, зміненими після `origin/main`.
- Дані часу шардів записуються в `.artifacts/vitest-shard-timings.json`.
- Whole-config runs використовують шлях config як ключ; include-pattern CI
- shards додають назву shard, щоб filtered shards можна було відстежувати
+ Запуски всієї конфігурації використовують шлях config як ключ; include-pattern CI
+ шарди додають назву шарда, щоб відфільтровані шарди можна було відстежувати
окремо.
- - Коли один hot test і далі витрачає більшість часу на startup imports,
- тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і
- мокайте цей seam напряму замість deep-importing runtime helpers лише
+ - Коли один гарячий тест усе ще витрачає більшість часу на startup imports,
+ тримайте важкі dependencies за вузьким локальним seam `*.runtime.ts` і
+ mock-айте цей seam напряму замість deep-import runtime helpers лише
щоб передати їх через `vi.mock(...)`.
- - `pnpm test:perf:changed:bench -- --ref ` порівнює routed
- `test:changed` із native root-project path для цього committed
- diff і виводить wall time плюс macOS max RSS.
+ - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований
+ `test:changed` із нативним шляхом root-project для цього закоміченого
+ diff і виводить wall time плюс max RSS macOS.
- `pnpm test:perf:changed:bench -- --worktree` benchmark-ить поточне
- dirty tree, спрямовуючи список changed file через
- `scripts/test-projects.mjs` і root конфігурацію Vitest.
- - `pnpm test:perf:profile:main` записує CPU profile main-thread для
+ dirty tree, маршрутизуючи список змінених файлів через
+ `scripts/test-projects.mjs` і кореневу конфігурацію Vitest.
+ - `pnpm test:perf:profile:main` записує CPU profile головного потоку для
startup Vitest/Vite і transform overhead.
- - `pnpm test:perf:profile:runner` записує runner CPU+heap profiles для
+ - `pnpm test:perf:profile:runner` записує CPU+heap profiles runner для
unit suite з вимкненим file parallelism.
-### Stability (gateway)
+### Стабільність (Gateway)
- Команда: `pnpm test:stability:gateway`
- Конфігурація: `vitest.gateway.config.ts`, примусово один worker
- Обсяг:
- - Запускає реальний loopback Gateway із діагностикою, увімкненою типово
- - Проганяє synthetic gateway message, memory і large-payload churn через шлях diagnostic event
- - Запитує `diagnostics.stability` через Gateway WS RPC
- - Покриває helpers для persistence diagnostic stability bundle
- - Перевіряє, що recorder залишається обмеженим, synthetic RSS samples не перевищують pressure budget, а per-session queue depths повертаються до нуля
+ - Запускає реальний loopback Gateway із типово ввімкненою diagnostics
+ - Проганяє синтетичний churn повідомлень gateway, memory і large-payload через diagnostic event path
+ - Опитує `diagnostics.stability` через Gateway WS RPC
+ - Покриває helpers збереження diagnostic stability bundle
+ - Перевіряє, що recorder залишається bounded, синтетичні RSS samples лишаються нижче pressure budget, а глибини per-session queue повертаються до нуля
- Очікування:
- Безпечно для CI і без ключів
- - Вузька lane для stability-regression follow-up, а не заміна повного набору Gateway
+ - Вузька lane для подальшої stability-regression, не заміна повному набору Gateway
### E2E (gateway smoke)
- Команда: `pnpm test:e2e`
- Конфігурація: `vitest.e2e.config.ts`
-- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` та E2E-тести вбудованих plugins у `extensions/`
+- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` та E2E-тести вбудованих plugin під `extensions/`
- Типові параметри середовища виконання:
- Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію.
- - Використовує адаптивну кількість воркерів (CI: до 2, локально: типово 1).
- - Типово запускається в тихому режимі, щоб зменшити накладні витрати консольного вводу-виводу.
+ - Використовує адаптивні workers (CI: до 2, локально: типово 1).
+ - Типово запускається в тихому режимі, щоб зменшити накладні витрати консольного I/O.
- Корисні перевизначення:
- - `OPENCLAW_E2E_WORKERS=` для примусового задання кількості воркерів (обмежено 16).
+ - `OPENCLAW_E2E_WORKERS=` для примусового задання кількості workers (обмежено 16).
- `OPENCLAW_E2E_VERBOSE=1` для повторного ввімкнення докладного консольного виводу.
- Область:
- - Наскрізна поведінка Gateway у кількох екземплярах
+ - Наскрізна поведінка Gateway з кількома інстансами
- Поверхні WebSocket/HTTP, сполучення вузлів і важчі мережеві сценарії
- Очікування:
- - Запускається в CI (коли ввімкнено в конвеєрі)
+ - Запускається в CI (коли ввімкнено в pipeline)
- Реальні ключі не потрібні
- - Більше рухомих частин, ніж у модульних тестах (може бути повільніше)
+ - Більше рухомих частин, ніж у unit-тестах (може бути повільніше)
-### E2E: базова перевірка backend OpenShell
+### E2E: smoke-перевірка бекенду OpenShell
- Команда: `pnpm test:e2e:openshell`
- Файл: `extensions/openshell/src/backend.e2e.test.ts`
- Область:
- - Запускає ізольований Gateway OpenShell на хості через Docker
- - Створює пісочницю з тимчасового локального Dockerfile
- - Перевіряє backend OpenShell OpenClaw через реальні `sandbox ssh-config` + SSH exec
- - Перевіряє канонічну поведінку віддаленої файлової системи через sandbox fs bridge
+ - Запускає ізольований OpenShell Gateway на хості через Docker
+ - Створює sandbox із тимчасового локального Dockerfile
+ - Перевіряє бекенд OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec
+ - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge
- Очікування:
- Лише за явним увімкненням; не входить до типового запуску `pnpm test:e2e`
- - Потребує локального CLI `openshell` і робочого демона Docker
- - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, потім знищує тестовий Gateway і пісочницю
+ - Потребує локального `openshell` CLI та робочого Docker daemon
+ - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий Gateway і sandbox
- Корисні перевизначення:
- `OPENCLAW_E2E_OPENSHELL=1` для ввімкнення тесту під час ручного запуску ширшого e2e-набору
- - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` для вказання нетипового CLI-бінарника або wrapper-скрипта
+ - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` для вказання нестандартного CLI-бінарника або wrapper-скрипта
### Live (реальні провайдери + реальні моделі)
- Команда: `pnpm test:live`
- Конфігурація: `vitest.live.config.ts`
-- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` та live-тести вбудованих plugins у `extensions/`
-- Типово: **увімкнено** через `pnpm test:live` (задає `OPENCLAW_LIVE_TEST=1`)
+- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` та live-тести вбудованих plugin під `extensions/`
+- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`)
- Область:
- - «Чи цей провайдер/модель справді працює _сьогодні_ з реальними обліковими даними?»
- - Виявляти зміни форматів провайдерів, особливості виклику інструментів, проблеми автентифікації та поведінку обмежень швидкості
+ - “Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?”
+ - Виявлення змін формату провайдера, особливостей tool calling, проблем автентифікації та поведінки rate limit
- Очікування:
- За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої)
- - Коштує грошей / використовує ліміти швидкості
- - Краще запускати звужені підмножини, а не «все»
-- Live-запуски підключають `~/.profile`, щоб отримати відсутні API-ключі.
-- Типово live-запуски все одно ізолюють `HOME` і копіюють матеріали конфігурації/автентифікації в тимчасовий тестовий home, щоб модульні фікстури не могли змінити ваш реальний `~/.openclaw`.
-- Задавайте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог.
-- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає прогрес-вивід `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає логи початкового запуску Gateway/повідомлення Bonjour. Задайте `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні логи запуску.
-- Ротація API-ключів (залежно від провайдера): задайте `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) чи перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях про обмеження швидкості.
-- Вивід прогресу/Heartbeat:
- - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдерів видимо активні навіть тоді, коли захоплення консолі Vitest тихе.
- - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/Gateway одразу транслювалися під час live-запусків.
- - Налаштовуйте Heartbeat для прямої моделі через `OPENCLAW_LIVE_HEARTBEAT_MS`.
- - Налаштовуйте Heartbeat для Gateway/проб через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`.
+ - Коштує грошей / використовує rate limits
+ - Краще запускати звужені підмножини, а не “все”
+- Live-запуски завантажують `~/.profile`, щоб підхопити відсутні API-ключі.
+- Типово live-запуски все одно ізолюють `HOME` і копіюють конфігурацію/матеріали автентифікації в тимчасовий тестовий home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`.
+- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно потрібно, щоб live-тести використовували вашу реальну домашню директорію.
+- `pnpm test:live` тепер типово працює тихіше: зберігає progress-вивід `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає логи bootstrap Gateway/повідомлення Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні startup-логи.
+- Ротація API-ключів (залежить від провайдера): встановіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) чи per-live перевизначення через `OPENCLAW_LIVE_*_KEY`; тести повторюють спроби на відповідях rate limit.
+- Вивід progress/heartbeat:
+ - Live-набори тепер виводять progress-рядки в stderr, щоб довгі виклики провайдера були помітно активними навіть тоді, коли консольне захоплення Vitest тихе.
+ - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб progress-рядки провайдера/Gateway одразу транслювалися під час live-запусків.
+ - Налаштовуйте heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`.
+ - Налаштовуйте heartbeat для Gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`.
## Який набір запускати?
Скористайтеся цією таблицею рішень:
-- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви змінили багато)
-- Зміни мережевої взаємодії Gateway / протоколу WS / сполучення: додайте `pnpm test:e2e`
-- Діагностика «мій бот не працює» / відмов, специфічних для провайдера / виклику інструментів: запускайте звужений `pnpm test:live`
+- Редагуєте логіку/тести: запустіть `pnpm test` (і `pnpm test:coverage`, якщо змінили багато)
+- Торкаєтеся мережевої частини Gateway / WS-протоколу / pairing: додайте `pnpm test:e2e`
+- Налагоджуєте “мій bot не працює” / помилки, специфічні для провайдера / tool calling: запустіть звужений `pnpm test:live`
-## Live-тести (з мережевою взаємодією)
+## Live-тести (що торкаються мережі)
-Для live-матриці моделей, базових перевірок CLI backend, базових перевірок ACP, harness Codex app-server
-та всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image,
-music, video, media harness), а також обробки облікових даних для live-запусків, див.
-[Тестування live-наборів](/uk/help/testing-live). Для спеціального контрольного списку оновлень і
-перевірки plugins див.
+Для live model matrix, smoke-перевірок CLI-бекенду, smoke-перевірок ACP, harness Codex app-server
+та всіх live-тестів media-provider (Deepgram, BytePlus, ComfyUI, image,
+music, video, media harness) — а також обробки облікових даних для live-запусків — див.
+[Тестування live-наборів](/uk/help/testing-live). Для спеціального чекліста оновлень і
+перевірки plugin див.
[Тестування оновлень і plugins](/uk/help/testing-updates-plugins).
## Docker runners (необов’язкові перевірки "працює в Linux")
Ці Docker runners поділяються на дві групи:
-- Live-model runners: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл із ключем профілю всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та робочу область (і підключають `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints: `test:live:models-profiles` і `test:live:gateway-profiles`.
-- Docker live runners типово мають менший smoke-ліміт, щоб повна Docker-перевірка залишалася практичною:
+- Live-model runners: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл profile-key всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують вашу локальну директорію конфігурації та workspace (і завантажують `~/.profile`, якщо змонтовано). Відповідні локальні entrypoints: `test:live:models-profiles` і `test:live:gateway-profiles`.
+- Docker live runners типово використовують менший smoke-ліміт, щоб повний Docker sweep залишався практичним:
`test:docker:live-models` типово задає `OPENCLAW_LIVE_MAX_MODELS=12`, а
`test:docker:live-gateway` типово задає `OPENCLAW_LIVE_GATEWAY_SMOKE=1`,
`OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`,
`OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і
- `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли ви
- явно хочете більший повний scan.
-- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два образи `scripts/e2e/Dockerfile`. Bare-образ є лише Node/Git runner для напрямів install/update/plugin-dependency; ці напрями монтують попередньо зібраний tarball. Functional-образ встановлює той самий tarball у `/app` для напрямів функціональності зібраного застосунку. Визначення Docker-напрямів містяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка планувальника міститься в `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегат використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, тоді як ліміти ресурсів не дають важким live-, npm-install- і multi-service-напрямам стартувати всім одночасно. Якщо один напрям важчий за активні ліміти, планувальник усе одно може запустити його, коли пул порожній, а потім тримає його запущеним наодинці, доки місткість знову не стане доступною. Типові значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker-хост має більше запасу ресурсів. Runner типово виконує Docker preflight, видаляє застарілі OpenClaw E2E-контейнери, друкує статус кожні 30 секунд, зберігає таймінги успішних напрямів у `.artifacts/docker-tests/lane-timings.json` і використовує ці таймінги, щоб у наступних запусках першими стартували довші напрями. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати зважений маніфест напрямів без збирання або запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб надрукувати CI-план для вибраних напрямів, потреб пакетів/образів і облікових даних.
-- `Package Acceptance` — це нативний для GitHub package gate для питання "чи цей інстальований tarball працює як продукт?" Він визначає один пакет-кандидат із `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає reusable Docker E2E-напрями проти саме цього tarball замість перепакування вибраного ref. Профілі впорядковані за широтою: `smoke`, `package`, `product` і `full`. Див. [Тестування оновлень і plugins](/uk/help/testing-updates-plugins) щодо контракту package/update/plugin, матриці published-upgrade survivor, типових параметрів релізу та triage відмов.
-- Перевірки збірки й релізу запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Захист обходить статичний зібраний граф від `dist/entry.js` і `dist/cli/run-main.js` та завершується з помилкою, якщо pre-dispatch startup імпортує залежності пакетів, як-от Commander, prompt UI, undici або logging, до dispatch команди; він також утримує bundled gateway run chunk у межах бюджету й відхиляє статичні імпорти відомих cold gateway paths. Packaged CLI smoke також охоплює root help, onboard help, doctor help, status, config schema і команду списку моделей.
-- Legacy compatibility Package Acceptance обмежено версією `2026.4.25` (включно з `2026.4.25-beta.*`). До цієї межі harness допускає лише прогалини метаданих shipped-package: пропущені private QA inventory entries, відсутній `gateway install --wrapper`, відсутні patch-файли у tarball-derived git fixture, відсутній persisted `update.channel`, legacy plugin install-record locations, відсутня marketplace install-record persistence і config metadata migration під час `plugins update`. Для пакетів після `2026.4.25` ці шляхи є strict failures.
-- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update`, `test:docker:plugin-lifecycle-matrix` і `test:docker:config-reload` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня.
+ `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли
+ явно хочете більший вичерпний scan.
+- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/перевикористовує два образи `scripts/e2e/Dockerfile`. Bare image — це лише Node/Git runner для install/update/plugin-dependency lanes; ці lanes монтують попередньо зібраний tarball. Functional image встановлює той самий tarball у `/app` для built-app functionality lanes. Визначення Docker lanes містяться в `scripts/lib/docker-e2e-scenarios.mjs`; planner-логіка — у `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний plan. Агрегат використовує weighted local scheduler: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує process slots, а resource caps не дають важким live, npm-install і multi-service lanes запускатися одночасно. Якщо один lane важчий за активні caps, scheduler усе ще може запустити його, коли pool порожній, і тримає його єдиним запущеним, доки capacity знову не стане доступною. Типові значення: 10 slots, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише коли Docker host має більше запасу. Runner типово виконує Docker preflight, видаляє застарілі OpenClaw E2E containers, друкує статус кожні 30 секунд, зберігає timings успішних lanes у `.artifacts/docker-tests/lane-timings.json` і використовує ці timings, щоб у наступних запусках стартувати довші lanes першими. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати weighted lane manifest без складання або запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб надрукувати CI plan для вибраних lanes, потреб package/image і облікових даних.
+- `Package Acceptance` — це GitHub-native package gate для "чи працює цей installable tarball як продукт?" Він визначає один candidate package з `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає reusable Docker E2E lanes проти саме цього tarball замість повторного пакування вибраного ref. Профілі впорядковані за шириною: `smoke`, `package`, `product` і `full`. Див. [Тестування оновлень і plugins](/uk/help/testing-updates-plugins) щодо contract package/update/plugin, матриці published-upgrade survivor, release defaults і failure triage.
+- Build and release checks запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Guard обходить статичний built graph від `dist/entry.js` і `dist/cli/run-main.js` та падає, якщо startup до dispatch імпортує package dependencies, як-от Commander, prompt UI, undici або logging, до command dispatch; він також утримує bundled gateway run chunk у межах бюджету й відхиляє статичні імпорти відомих cold gateway paths. Packaged CLI smoke також покриває root help, onboard help, doctor help, status, config schema і model-list command.
+- Legacy-сумісність Package Acceptance обмежена `2026.4.25` (включно з `2026.4.25-beta.*`). До цього cutoff harness допускає лише прогалини metadata shipped-package: пропущені private QA inventory entries, відсутній `gateway install --wrapper`, відсутні patch files у tarball-derived git fixture, відсутній persisted `update.channel`, legacy plugin install-record locations, відсутня persistence marketplace install-record і міграція config metadata під час `plugins update`. Для packages після `2026.4.25` ці шляхи є strict failures.
+- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update`, `test:docker:plugin-lifecycle-matrix` і `test:docker:config-reload` завантажують один або кілька реальних containers і перевіряють high-level integration paths.
-Live-model Docker runners також bind-mount лише потрібні домівки автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у container home перед запуском, щоб external-CLI OAuth міг оновлювати tokens без зміни сховища автентифікації хоста:
+Live-model Docker runners також bind-mount лише потрібні CLI auth homes (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у container home перед запуском, щоб external-CLI OAuth міг оновлювати tokens без зміни host auth store:
- Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`)
-- Smoke-перевірка прив’язки ACP: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`; типово охоплює Claude, Codex і Gemini, зі суворим покриттям Droid/OpenCode через `pnpm test:docker:live-acp-bind:droid` і `pnpm test:docker:live-acp-bind:opencode`)
+- Smoke-перевірка прив’язки ACP: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`; типово охоплює Claude, Codex і Gemini, зі строгим покриттям Droid/OpenCode через `pnpm test:docker:live-acp-bind:droid` і `pnpm test:docker:live-acp-bind:opencode`)
- Smoke-перевірка бекенда CLI: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`)
-- Smoke-перевірка обв’язки сервера застосунку Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`)
+- Smoke-перевірка harness сервера застосунку Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`)
- Gateway + агент розробки: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`)
-- Smoke-перевірка спостережуваності: `pnpm qa:otel:smoke` — це приватна гілка перевірки QA для checkout вихідного коду. Вона навмисно не входить до гілок Docker-релізу пакета, оскільки npm-архів не містить QA Lab.
-- Жива smoke-перевірка Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`)
-- Майстер онбордингу (TTY, повне створення каркаса): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`)
-- Smoke-перевірка онбордингу/каналу/агента npm-архіву: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює упакований архів OpenClaw у Docker, налаштовує OpenAI через онбординг із посиланням на env і типово Telegram, запускає doctor і виконує один змодельований хід агента OpenAI. Повторно використовуйте попередньо зібраний архів через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемикайте канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`.
-- Smoke-перевірка перемикання каналу оновлення: `pnpm test:docker:update-channel-switch` глобально встановлює упакований архів OpenClaw у Docker, перемикається з пакета `stable` на git `dev`, перевіряє збережений канал і роботу Plugin після оновлення, потім перемикається назад на пакет `stable` і перевіряє статус оновлення.
-- Smoke-перевірка виживання після оновлення: `pnpm test:docker:upgrade-survivor` встановлює упакований архів OpenClaw поверх забрудненої фікстури старого користувача з агентами, конфігурацією каналу, allowlist плагінів, застарілим станом залежностей Plugin і наявними файлами workspace/session. Вона запускає оновлення пакета плюс неінтерактивний doctor без ключів live-провайдера або каналу, потім запускає loopback Gateway і перевіряє збереження config/state, а також бюджети запуску/статусу.
-- Smoke-перевірка виживання після опублікованого оновлення: `pnpm test:docker:published-upgrade-survivor` типово встановлює `openclaw@latest`, засіває реалістичні файли наявного користувача, налаштовує цей baseline за допомогою вбудованого рецепта команд, перевіряє отриману конфігурацію, оновлює цю опубліковану інсталяцію до кандидатного архіву, запускає неінтерактивний doctor, записує `.artifacts/upgrade-survivor/summary.json`, потім запускає loopback Gateway і перевіряє налаштовані intents, збереження стану, запуск, `/healthz`, `/readyz` і бюджети статусу RPC. Перевизначте один baseline через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, попросіть агрегувальний планувальник розгорнути точні baselines через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, наприклад `all-since-2026.4.23`, і розгорнути фікстури у формі issues через `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS`, наприклад `reported-issues`; набір reported-issues містить `configured-plugin-installs` для автоматичного ремонту інсталяції зовнішнього OpenClaw Plugin. Package Acceptance надає їх як `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` і `published_upgrade_survivor_scenarios`.
-- Smoke-перевірка runtime-контексту сесії: `pnpm test:docker:session-runtime-context` перевіряє збереження прихованого runtime-контексту в transcript, а також repair через doctor для зачеплених дубльованих гілок переписування prompt.
-- Smoke-перевірка глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає вбудованих image providers замість зависання. Повторно використовуйте попередньо зібраний архів через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте збірку на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або копіюйте `dist/` із зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`.
-- Smoke-перевірка Docker-інсталятора: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm-кеш між контейнерами root, update і direct-npm. Smoke-перевірка оновлення типово використовує npm `latest` як stable baseline перед оновленням до кандидатного архіву. Локально перевизначте через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` або через input `update_baseline_version` у workflow Install Smoke на GitHub. Перевірки інсталятора без root зберігають ізольований npm-кеш, щоб записи кешу, що належать root, не маскували поведінку локального встановлення користувача. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm під час локальних повторних запусків.
+- Smoke-перевірка спостережуваності: `pnpm qa:otel:smoke` — це приватна QA-гілка перевірки вихідного checkout. Її навмисно не включено до пакетних Docker-гілок релізу, бо npm tarball не містить QA Lab.
+- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`)
+- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`)
+- Smoke-перевірка npm tarball onboarding/каналу/агента: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через env-ref onboarding і типово Telegram, запускає doctor та виконує один мокований хід агента OpenAI. Повторно використайте попередньо зібраний tarball із `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемкніть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`.
+- Smoke-перевірка перемикання каналу оновлень: `pnpm test:docker:update-channel-switch` глобально встановлює запакований tarball OpenClaw у Docker, перемикається з пакета `stable` на git `dev`, перевіряє збережений канал і роботу Plugin після оновлення, потім перемикається назад на пакет `stable` і перевіряє статус оновлення.
+- Smoke-перевірка збереження після оновлення: `pnpm test:docker:upgrade-survivor` встановлює запакований tarball OpenClaw поверх забрудненого фікстурного стану старого користувача з агентами, конфігурацією каналу, allowlist Plugin, застарілим станом залежностей Plugin і наявними файлами workspace/сесій. Вона запускає оновлення пакета та неінтерактивний doctor без live ключів провайдера чи каналу, потім запускає loopback Gateway і перевіряє збереження конфігурації/стану, а також бюджети запуску/статусу.
+- Smoke-перевірка збереження після опублікованого оновлення: `pnpm test:docker:published-upgrade-survivor` типово встановлює `openclaw@latest`, засіває реалістичні файли наявного користувача, налаштовує цей базовий стан за допомогою вбудованого рецепта команд, перевіряє отриману конфігурацію, оновлює це опубліковане встановлення до tarball кандидата, запускає неінтерактивний doctor, записує `.artifacts/upgrade-survivor/summary.json`, потім запускає loopback Gateway і перевіряє налаштовані intents, збереження стану, запуск, `/healthz`, `/readyz` і бюджети статусу RPC. Перевизначте один базовий стан через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, попросіть aggregate scheduler розгорнути точні базові стани через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, наприклад `all-since-2026.4.23`, і розгорніть фікстури у формі issue через `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS`, наприклад `reported-issues`; набір reported-issues містить `configured-plugin-installs` для автоматичного ремонту встановлення зовнішніх OpenClaw Plugin. Package Acceptance надає їх як `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` і `published_upgrade_survivor_scenarios`.
+- Smoke-перевірка runtime-контексту сесії: `pnpm test:docker:session-runtime-context` перевіряє збереження transcript прихованого runtime-контексту та ремонт doctor для уражених дубльованих гілок prompt-rewrite.
+- Smoke-перевірка глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає вбудованих провайдерів зображень замість зависання. Повторно використайте попередньо зібраний tarball із `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть збірку на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` зі зібраного Docker image через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`.
+- Smoke-перевірка Docker інсталятора: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm cache між root, update і direct-npm контейнерами. Update smoke типово використовує npm `latest` як стабільний базовий стан перед оновленням до tarball кандидата. Перевизначте локально через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` або через input `update_baseline_version` workflow Install Smoke на GitHub. Перевірки інсталятора без root зберігають ізольований npm cache, щоб записи cache, власником яких є root, не маскували поведінку встановлення в локальному середовищі користувача. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати cache root/update/direct-npm між локальними повторними запусками.
- Install Smoke CI пропускає дубльоване глобальне оновлення direct-npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`.
-- Smoke-перевірка CLI видалення агентами спільного workspace: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) типово збирає root Dockerfile image, засіває двох агентів з одним workspace в ізольованому container home, запускає `agents delete --json` і перевіряє коректний JSON та поведінку зі збереженим workspace. Повторно використовуйте install-smoke image через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`.
-- Мережева взаємодія Gateway (два контейнери, автентифікація WS + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`)
-- Smoke-перевірка snapshot Browser CDP: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає source E2E image плюс шар Chromium, запускає Chromium із raw CDP, виконує `browser doctor --deep` і перевіряє, що snapshots ролей CDP охоплюють URL посилань, clickables, підвищені курсором, iframe refs і frame metadata.
-- Регресія мінімального reasoning для OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змодельований сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово викликає відхилення schema провайдером і перевіряє, що raw detail з’являється в логах Gateway.
-- Міст каналу MCP (засіяний Gateway + stdio bridge + smoke-перевірка raw Claude notification-frame): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`)
-- Інструменти MCP Pi bundle (реальний stdio MCP server + smoke-перевірка вбудованого Pi profile allow/deny): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`)
-- Очищення Cron/subagent MCP (реальний Gateway + teardown дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`)
-- Плагіни (smoke-перевірка install/update для локального path, `file:`, npm registry з hoisted dependencies, рухомих git refs, ClawHub kitchen-sink, marketplace updates і enable/inspect Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`)
- Установіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити блок ClawHub, або перевизначте типову пару kitchen-sink package/runtime через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Без `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` тест використовує герметичний локальний fixture server ClawHub.
-- Smoke-перевірка незміненого оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`)
-- Smoke-перевірка матриці життєвого циклу Plugin: `pnpm test:docker:plugin-lifecycle-matrix` встановлює упакований архів OpenClaw у порожній контейнер, встановлює npm-плагін, перемикає enable/disable, підвищує та знижує його версію через локальний npm registry, видаляє встановлений код, потім перевіряє, що uninstall все одно видаляє застарілий стан, одночасно логуючи метрики RSS/CPU для кожної фази життєвого циклу.
+- Smoke-перевірка CLI видалення спільного workspace агентів: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) типово збирає image з кореневого Dockerfile, засіває двох агентів з одним workspace в ізольованому container home, запускає `agents delete --json` і перевіряє валідний JSON та поведінку збереженого workspace. Повторно використайте image install-smoke через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`.
+- Мережа Gateway (два контейнери, auth WS + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`)
+- Smoke-перевірка browser CDP snapshot: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає source E2E image разом із шаром Chromium, запускає Chromium із raw CDP, виконує `browser doctor --deep` і перевіряє, що snapshot ролей CDP охоплюють URL посилань, clickables, підвищені курсором, iframe refs і метадані frame.
+- Регресія OpenAI Responses web_search minimal reasoning: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає мокований сервер OpenAI через Gateway, перевіряє, що `web_search` піднімає `reasoning.effort` з `minimal` до `low`, потім примусово викликає reject схеми провайдера й перевіряє, що raw detail з’являється в логах Gateway.
+- Міст MCP каналу (засіяний Gateway + stdio bridge + smoke-перевірка raw notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`)
+- MCP інструменти Pi bundle (реальний stdio MCP server + smoke-перевірка allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`)
+- Очищення Cron/subagent MCP (реальний Gateway + teardown дочірнього stdio MCP після ізольованого cron і one-shot запусків subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`)
+- Plugins (smoke-перевірка install/update для local path, `file:`, npm registry з hoisted dependencies, git moving refs, ClawHub kitchen-sink, marketplace updates і enable/inspect Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`)
+ Установіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити блок ClawHub, або перевизначте типову пару package/runtime kitchen-sink через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Без `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` тест використовує герметичний локальний сервер фікстури ClawHub.
+- Smoke-перевірка незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`)
+- Smoke-перевірка матриці життєвого циклу Plugin: `pnpm test:docker:plugin-lifecycle-matrix` встановлює запакований tarball OpenClaw у порожньому контейнері, встановлює npm Plugin, перемикає enable/disable, оновлює й відкотить його через локальний npm registry, видаляє встановлений код, потім перевіряє, що uninstall все одно видаляє застарілий стан, одночасно логуючи метрики RSS/CPU для кожної фази життєвого циклу.
- Smoke-перевірка metadata перезавантаження конфігурації: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`)
-- Плагіни: `pnpm test:docker:plugins` охоплює smoke-перевірку install/update для локального path, `file:`, npm registry з hoisted dependencies, рухомих git refs, фікстур ClawHub, marketplace updates і enable/inspect Claude-bundle. `pnpm test:docker:plugin-update` охоплює поведінку незміненого оновлення для встановлених плагінів. `pnpm test:docker:plugin-lifecycle-matrix` охоплює встановлення npm-плагіна з відстеженням ресурсів, enable, disable, upgrade, downgrade і uninstall за відсутнього коду.
+- Plugins: `pnpm test:docker:plugins` охоплює smoke-перевірку install/update для local path, `file:`, npm registry з hoisted dependencies, git moving refs, фікстур ClawHub, marketplace updates і enable/inspect Claude-bundle. `pnpm test:docker:plugin-update` охоплює поведінку незмінного оновлення встановлених Plugin. `pnpm test:docker:plugin-lifecycle-matrix` охоплює відстежувані за ресурсами встановлення, enable, disable, upgrade, downgrade npm Plugin і uninstall за відсутнього коду.
-Щоб вручну попередньо зібрати й повторно використати спільний функціональний image:
+Щоб вручну попередньо зібрати й повторно використати спільний functional image:
```bash
OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build
OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels
```
-Перевизначення image для конкретних suites, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе одно мають пріоритет, коли встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти pull його, якщо він ще не доступний локально. QR і Docker-тести інсталятора зберігають власні Dockerfiles, оскільки вони перевіряють поведінку package/install, а не спільний runtime зібраного застосунку.
+Специфічні для suite перевизначення image, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, коли встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти завантажують його, якщо він ще не локальний. Docker тести QR та інсталятора зберігають власні Dockerfile, бо вони перевіряють поведінку package/install, а не спільний runtime зібраного застосунку.
-Запускачі Docker для live-моделей також монтують поточний checkout лише для читання і
-розгортають його в тимчасову робочу директорію всередині контейнера. Це зберігає runtime-образ
-компактним, водночас запускаючи Vitest саме з вашим локальним вихідним кодом/конфігурацією.
-Етап розгортання пропускає великі локальні кеші та вихідні артефакти збірки застосунків, такі як
-`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні для застосунку `.build` або
-директорії виводу Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання
-машинно-специфічних артефактів.
-Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-перевірки Gateway не запускали
-реальні воркери каналів Telegram/Discord/тощо всередині контейнера.
+Docker-ранери для live-моделей також bind-mount-ять поточний checkout у режимі лише для читання та
+розгортають його в тимчасовий workdir усередині контейнера. Це зберігає runtime
+image компактним, водночас запускаючи Vitest проти вашого точного локального source/config.
+Крок розгортання пропускає великі локальні кеші та вихідні файли збірки застосунків, як-от
+`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також app-local `.build` або
+каталоги виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання
+machine-specific артефактів.
+Вони також задають `OPENCLAW_SKIP_CHANNELS=1`, щоб gateway live probes не запускали
+реальні Telegram/Discord тощо channel workers усередині контейнера.
`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте
-`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити live-покриття Gateway
-з цієї Docker-смуги.
-`test:docker:openwebui` — це вищорівневий smoke-тест сумісності: він запускає контейнер
-Gateway OpenClaw з увімкненими HTTP-ендпойнтами, сумісними з OpenAI,
-запускає контейнер Open WebUI із зафіксованою версією проти цього Gateway, виконує вхід через
+`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway
+live-покриття з цієї Docker lane.
+`test:docker:openwebui` — це smoke-тест сумісності вищого рівня: він запускає
+контейнер Gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoints,
+запускає закріплений контейнер Open WebUI проти цього Gateway, входить через
Open WebUI, перевіряє, що `/api/models` відкриває `openclaw/default`, а потім надсилає
-реальний чат-запит через проксі `/api/chat/completions` Open WebUI.
-Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися завантажити
-образ Open WebUI, а Open WebUI може знадобитися завершити власне налаштування холодного старту.
-Ця смуга очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE`
-(`~/.profile` за замовчуванням) є основним способом надати його в Dockerизованих запусках.
-Успішні запуски виводять невелике JSON-навантаження на кшталт `{ "ok": true, "model":
+реальний chat request через proxy Open WebUI `/api/chat/completions`.
+Перший запуск може бути помітно повільнішим, бо Docker може знадобитися завантажити
+image Open WebUI, а Open WebUI може знадобитися завершити власне налаштування cold-start.
+Ця lane очікує придатний live model key, а `OPENCLAW_PROFILE_FILE`
+(`~/.profile` за замовчуванням) є основним способом надати його в Dockerized runs.
+Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model":
"openclaw/default", ... }`.
`test:docker:mcp-channels` навмисно детермінований і не потребує
-реального облікового запису Telegram, Discord або iMessage. Він запускає seeded-контейнер Gateway,
+реального облікового запису Telegram, Discord або iMessage. Він завантажує seeded контейнер Gateway,
запускає другий контейнер, який породжує `openclaw mcp serve`, а потім
-перевіряє виявлення маршрутованих розмов, читання транскриптів, метадані вкладень,
-поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення каналів +
-дозволів у стилі Claude через реальний stdio-міст MCP. Перевірка сповіщень
-безпосередньо інспектує сирі stdio-кадри MCP, тому smoke-тест перевіряє те, що
-міст фактично випромінює, а не лише те, що випадково показує конкретний SDK клієнта.
-`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує live-ключа
-моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio-пробний сервер MCP
-усередині контейнера, матеріалізує цей сервер через вбудований runtime MCP пакета Pi,
-виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають
-інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують.
-`test:docker:cron-mcp-cleanup` є детермінованим і не потребує live-ключа моделі.
-Він запускає seeded Gateway з реальним stdio-пробним сервером MCP, виконує
-ізольований Cron-turn і одноразовий дочірній turn `/subagents spawn`, а потім перевіряє,
-що дочірній процес MCP завершується після кожного запуску.
+перевіряє виявлення routed conversation, читання transcript, metadata attachment,
+поведінку live event queue, outbound send routing і channel +
+permission notifications у стилі Claude через реальний stdio MCP bridge. Перевірка notifications
+безпосередньо інспектує сирі stdio MCP frames, тому smoke-тест перевіряє те, що
+bridge фактично видає, а не лише те, що випадково показує конкретний client SDK.
+`test:docker:pi-bundle-mcp-tools` детермінований і не потребує live
+model key. Він збирає Docker image репозиторію, запускає реальний stdio MCP probe server
+усередині контейнера, матеріалізує цей server через embedded Pi bundle
+MCP runtime, виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають
+tools `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують.
+`test:docker:cron-mcp-cleanup` детермінований і не потребує live model
+key. Він запускає seeded Gateway з реальним stdio MCP probe server, виконує
+ізольований cron turn і one-shot child turn `/subagents spawn`, а потім перевіряє,
+що MCP child process завершується після кожного запуску.
-Ручний ACP smoke-тест тредів простою мовою (не CI):
+Ручний ACP plain-language thread smoke-тест (не CI):
- `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...`
-- Збережіть цей скрипт для регресійних/налагоджувальних workflow. Він може знову знадобитися для перевірки маршрутизації ACP-тредів, тому не видаляйте його.
+- Зберігайте цей script для regression/debug workflows. Він може знову знадобитися для валідації ACP thread routing, тому не видаляйте його.
Корисні змінні середовища:
-- `OPENCLAW_CONFIG_DIR=...` (за замовчуванням: `~/.openclaw`) монтується до `/home/node/.openclaw`
-- `OPENCLAW_WORKSPACE_DIR=...` (за замовчуванням: `~/.openclaw/workspace`) монтується до `/home/node/.openclaw/workspace`
-- `OPENCLAW_PROFILE_FILE=...` (за замовчуванням: `~/.profile`) монтується до `/home/node/.profile` і підвантажується перед запуском тестів
-- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише змінні середовища, підвантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові директорії конфігурації/робочого простору та без зовнішніх монтувань автентифікації CLI
-- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`) монтується до `/home/node/.npm-global` для кешованих установлень CLI всередині Docker
-- Зовнішні директорії/файли автентифікації CLI під `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються до `/home/node/...` перед початком тестів
- - Директорії за замовчуванням: `.minimax`
- - Файли за замовчуванням: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json`
- - Звужені запуски провайдерів монтують лише потрібні директорії/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS`
- - Перевизначайте вручну за допомогою `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або списку через кому на кшталт `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`
-- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск
-- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера
-- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, які не потребують перебудови
-- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб забезпечити надходження облікових даних зі сховища профілю (не з env)
-- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway відкриває для smoke-тесту Open WebUI
-- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke-тест Open WebUI
-- `OPENWEBUI_IMAGE=...`, щоб перевизначити зафіксований тег образу Open WebUI
+- `OPENCLAW_CONFIG_DIR=...` (за замовчуванням: `~/.openclaw`) mounted до `/home/node/.openclaw`
+- `OPENCLAW_WORKSPACE_DIR=...` (за замовчуванням: `~/.openclaw/workspace`) mounted до `/home/node/.openclaw/workspace`
+- `OPENCLAW_PROFILE_FILE=...` (за замовчуванням: `~/.profile`) mounted до `/home/node/.profile` і sourced перед запуском tests
+- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1` для перевірки лише env vars, sourced з `OPENCLAW_PROFILE_FILE`, з використанням тимчасових config/workspace dirs і без external CLI auth mounts
+- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`) mounted до `/home/node/.npm-global` для кешованих CLI installs усередині Docker
+- External CLI auth dirs/files у `$HOME` mounted у режимі read-only під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком tests
+ - Default dirs: `.minimax`
+ - Default files: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json`
+ - Narrowed provider runs монтують лише потрібні dirs/files, inferred з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS`
+ - Перевизначте вручну за допомогою `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або comma list на кшталт `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex`
+- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` для звуження запуску
+- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` для фільтрації providers in-container
+- `OPENCLAW_SKIP_DOCKER_BUILD=1` для повторного використання наявного image `openclaw:local-live` для reruns, яким не потрібна повторна збірка
+- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` для гарантії, що creds надходять із profile store (а не env)
+- `OPENCLAW_OPENWEBUI_MODEL=...` для вибору model, яку Gateway відкриває для smoke-тесту Open WebUI
+- `OPENCLAW_OPENWEBUI_PROMPT=...` для перевизначення nonce-check prompt, що використовується smoke-тестом Open WebUI
+- `OPENWEBUI_IMAGE=...` для перевизначення закріпленого image tag Open WebUI
-## Санітарна перевірка документації
+## Перевірка документації
-Запускайте перевірки документації після редагувань документації: `pnpm check:docs`.
-Запускайте повну перевірку anchors Mintlify, коли також потрібні перевірки заголовків на сторінці: `pnpm docs:check-links:anchors`.
+Запускайте перевірки документації після редагування docs: `pnpm check:docs`.
+Запускайте повну валідацію anchors Mintlify, коли також потрібні перевірки in-page headings: `pnpm docs:check-links:anchors`.
-## Offline-регресія (безпечна для CI)
+## Офлайн-регресія (CI-safe)
-Це регресії “реального pipeline” без реальних провайдерів:
+Це регресії «real pipeline» без реальних providers:
-- Виклик інструментів Gateway (mock OpenAI, реальні gateway + agent loop): `src/gateway/gateway.test.ts` (кейс: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
-- Wizard Gateway (WS `wizard.start`/`wizard.next`, записує конфігурацію + автентифікація enforced): `src/gateway/gateway.test.ts` (кейс: "runs wizard over ws and writes auth token config")
+- Gateway tool calling (mock OpenAI, реальний Gateway + agent loop): `src/gateway/gateway.test.ts` (case: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
+- Gateway wizard (WS `wizard.start`/`wizard.next`, записує config + auth enforced): `src/gateway/gateway.test.ts` (case: "runs wizard over ws and writes auth token config")
-## Оцінювання надійності агента (Skills)
+## Agent reliability evals (Skills)
-У нас уже є кілька безпечних для CI тестів, які поводяться як “оцінювання надійності агента”:
+У нас уже є кілька CI-safe tests, які поводяться як «agent reliability evals»:
-- Mock-виклик інструментів через реальні Gateway + agent loop (`src/gateway/gateway.test.ts`).
-- End-to-end wizard-потоки, які перевіряють wiring сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`).
+- Mock tool-calling через реальний Gateway + agent loop (`src/gateway/gateway.test.ts`).
+- End-to-end wizard flows, які перевіряють session wiring і config effects (`src/gateway/gateway.test.ts`).
Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)):
-- **Прийняття рішень:** коли Skills перелічені в prompt, чи агент вибирає правильний skill (або уникає нерелевантних)?
-- **Відповідність:** чи агент читає `SKILL.md` перед використанням і виконує потрібні кроки/аргументи?
-- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox.
+- **Прийняття рішень:** коли skills перелічені в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)?
+- **Відповідність вимогам:** чи читає agent `SKILL.md` перед використанням і чи виконує required steps/args?
+- **Workflow contracts:** multi-turn scenarios, які assert-ять tool order, session history carryover і sandbox boundaries.
-Майбутні оцінювання мають передусім залишатися детермінованими:
+Майбутні evals мають спочатку лишатися детермінованими:
-- Scenario runner із mock-провайдерами для перевірки викликів інструментів + порядку, читання файлів skill і wiring сесії.
-- Невеликий набір сценаріїв, сфокусованих на skill (використати чи уникнути, gating, prompt injection).
-- Необов’язкові live-оцінювання (opt-in, env-gated) лише після появи безпечного для CI набору.
+- Scenario runner з mock providers для assert tool calls + order, skill file reads і session wiring.
+- Невеликий suite skill-focused scenarios (use vs avoid, gating, prompt injection).
+- Optional live evals (opt-in, env-gated) лише після того, як CI-safe suite буде на місці.
-## Контрактні тести (форма Plugin і каналу)
+## Contract tests (plugin and channel shape)
-Контрактні тести перевіряють, що кожен зареєстрований Plugin і канал відповідає своєму
-контракту інтерфейсу. Вони ітерують усі виявлені Plugins і запускають набір
-перевірок форми та поведінки. Стандартна unit-смуга `pnpm test` навмисно
-пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно,
-коли торкаєтеся спільних поверхонь каналів або провайдерів.
+Contract tests перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму
+interface contract. Вони ітерують усі виявлені plugins і запускають suite
+assertions для shape і behavior. Default unit lane `pnpm test` навмисно
+пропускає ці shared seam і smoke files; запускайте contract commands явно,
+коли змінюєте shared channel або provider surfaces.
-### Команди
+### Commands
-- Усі контракти: `pnpm test:contracts`
-- Лише контракти каналів: `pnpm test:contracts:channels`
-- Лише контракти провайдерів: `pnpm test:contracts:plugins`
+- Усі contracts: `pnpm test:contracts`
+- Лише channel contracts: `pnpm test:contracts:channels`
+- Лише provider contracts: `pnpm test:contracts:plugins`
-### Контракти каналів
+### Channel contracts
Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`:
-- **plugin** - базова форма Plugin (id, name, capabilities)
-- **setup** - контракт setup wizard
-- **session-binding** - поведінка прив’язування сесії
-- **outbound-payload** - структура payload повідомлення
-- **inbound** - обробка вхідних повідомлень
-- **actions** - обробники дій каналу
-- **threading** - обробка ID тредів
-- **directory** - API директорії/списку учасників
-- **group-policy** - застосування групової політики
+- **plugin** - Базова shape Plugin (id, name, capabilities)
+- **setup** - Contract setup wizard
+- **session-binding** - Поведінка session binding
+- **outbound-payload** - Структура message payload
+- **inbound** - Обробка inbound message
+- **actions** - Channel action handlers
+- **threading** - Обробка Thread ID
+- **directory** - API directory/roster
+- **group-policy** - Застосування group policy
-### Контракти статусу провайдерів
+### Provider status contracts
Розташовані в `src/plugins/contracts/*.contract.test.ts`.
-- **status** - probes статусу каналу
-- **registry** - форма registry Plugin
+- **status** - Channel status probes
+- **registry** - Shape registry Plugin
-### Контракти провайдерів
+### Provider contracts
Розташовані в `src/plugins/contracts/*.contract.test.ts`:
-- **auth** - контракт auth flow
-- **auth-choice** - вибір/selection auth
-- **catalog** - API каталогу моделей
-- **discovery** - виявлення Plugin
-- **loader** - завантаження Plugin
-- **runtime** - runtime провайдера
-- **shape** - форма/інтерфейс Plugin
-- **wizard** - setup wizard
+- **auth** - Contract auth flow
+- **auth-choice** - Auth choice/selection
+- **catalog** - API model catalog
+- **discovery** - Виявлення Plugin
+- **loader** - Завантаження Plugin
+- **runtime** - Provider runtime
+- **shape** - Shape/interface Plugin
+- **wizard** - Setup wizard
### Коли запускати
- Після зміни exports або subpaths plugin-sdk
-- Після додавання або змінення каналу чи провайдерського Plugin
-- Після рефакторингу реєстрації або виявлення Plugin
+- Після додавання або зміни channel чи provider Plugin
+- Після refactoring реєстрації або виявлення Plugin
-Контрактні тести виконуються в CI і не потребують реальних API-ключів.
+Contract tests запускаються в CI і не потребують реальних API keys.
## Додавання регресій (настанови)
-Коли ви виправляєте проблему провайдера/моделі, виявлену наживо:
+Коли ви виправляєте provider/model issue, виявлену live:
-- Додайте безпечну для CI регресію, якщо можливо (mock/stub провайдера або захопіть точне перетворення форми запиту)
-- Якщо це за своєю природою лише live-випадок (rate limits, auth policies), тримайте live-тест вузьким і opt-in через змінні середовища
-- Віддавайте перевагу найменшому шару, який ловить помилку:
- - помилка перетворення/відтворення запиту провайдера → прямий тест моделей
- - помилка pipeline сесії/історії/інструментів Gateway → live-smoke Gateway або безпечний для CI mock-тест Gateway
-- Guardrail обходу SecretRef:
- - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить по одній sampled-цілі на клас SecretRef з метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec ids із traversal-сегментами відхиляються.
- - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target ids, щоб нові класи не можна було мовчки пропустити.
+- Додайте CI-safe regression, якщо можливо (mock/stub provider або зафіксуйте точну request-shape transformation)
+- Якщо це inherently live-only (rate limits, auth policies), тримайте live test вузьким і opt-in через env vars
+- Віддавайте перевагу найменшому layer, який ловить bug:
+ - provider request conversion/replay bug → direct models test
+ - gateway session/history/tool pipeline bug → gateway live smoke або CI-safe gateway mock test
+- SecretRef traversal guardrail:
+ - `src/secrets/exec-secret-ref-id-parity.test.ts` derives one sampled target per SecretRef class з registry metadata (`listSecretTargetRegistryEntries()`), а потім asserts, що traversal-segment exec ids відхиляються.
+ - Якщо ви додаєте нову `includeInPlan` SecretRef target family у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому test. Test навмисно fails на unclassified target ids, щоб нові classes не могли бути skipped silently.
## Пов’язане
-- [Тестування live](/uk/help/testing-live)
-- [Тестування оновлень і plugins](/uk/help/testing-updates-plugins)
+- [Testing live](/uk/help/testing-live)
+- [Testing updates and plugins](/uk/help/testing-updates-plugins)
- [CI](/uk/ci)
diff --git a/docs/uk/providers/openrouter.md b/docs/uk/providers/openrouter.md
index 847738f79..9117ff765 100644
--- a/docs/uk/providers/openrouter.md
+++ b/docs/uk/providers/openrouter.md
@@ -1,36 +1,36 @@
---
read_when:
- - Вам потрібен єдиний API-ключ для багатьох LLM
+ - Вам потрібен єдиний ключ API для багатьох LLM
- Ви хочете запускати моделі через OpenRouter в OpenClaw
- Ви хочете використовувати OpenRouter для генерації зображень
- Ви хочете використовувати OpenRouter для генерації відео
summary: Використовуйте уніфікований API OpenRouter для доступу до багатьох моделей в OpenClaw
title: OpenRouter
x-i18n:
- generated_at: "2026-05-04T00:14:04Z"
+ generated_at: "2026-05-04T21:16:48Z"
model: gpt-5.5
provider: openai
- source_hash: f6b7299408aa0de7530e2248c7fa5dae8c09095e2d20a0e9d12a64cab83966fc
+ source_hash: b2876669c6fcc958ac13c19930cd23977b8ec27ae57069d9231932cc13c75244
source_path: providers/openrouter.md
workflow: 16
---
-OpenRouter надає **уніфікований API**, який спрямовує запити до багатьох моделей через одну
-кінцеву точку й ключ API. Він сумісний з OpenAI, тому більшість SDK OpenAI працюють після зміни базової URL-адреси.
+OpenRouter надає **уніфікований API**, який маршрутизує запити до багатьох моделей за одним
+endpoint і API-ключем. Він сумісний з OpenAI, тому більшість OpenAI SDK працюють після перемикання базового URL.
## Початок роботи
-
- Створіть ключ API на [openrouter.ai/keys](https://openrouter.ai/keys).
+
+ Створіть API-ключ на [openrouter.ai/keys](https://openrouter.ai/keys).
-
+
```bash
openclaw onboard --auth-choice openrouter-api-key
```
-
- Onboarding за замовчуванням використовує `openrouter/auto`. Виберіть конкретну модель пізніше:
+
+ Початкове налаштування типово використовує `openrouter/auto`. Пізніше виберіть конкретну модель:
```bash
openclaw models set openrouter//
@@ -59,16 +59,16 @@ OpenRouter надає **уніфікований API**, який спрямов
доступних провайдерів і моделей див. у [/concepts/model-providers](/uk/concepts/model-providers).
-Вбудовані приклади fallback:
+Приклади вбудованого резервного варіанта:
-| Посилання на модель | Примітки |
-| --------------------------------- | ------------------------------------- |
+| Посилання на модель | Примітки |
+| --------------------------------- | ---------------------------------- |
| `openrouter/auto` | Автоматична маршрутизація OpenRouter |
-| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 через MoonshotAI |
+| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 через MoonshotAI |
## Генерація зображень
-OpenRouter також може забезпечувати інструмент `image_generate`. Використовуйте модель зображень OpenRouter у `agents.defaults.imageGenerationModel`:
+OpenRouter також може забезпечувати роботу інструмента `image_generate`. Використовуйте модель зображень OpenRouter у `agents.defaults.imageGenerationModel`:
```json5
{
@@ -84,11 +84,11 @@ OpenRouter також може забезпечувати інструмент `
}
```
-OpenClaw надсилає запити зображень до image API чат-завершень OpenRouter із `modalities: ["image", "text"]`. Моделі зображень Gemini отримують підтримувані підказки `aspectRatio` і `resolution` через `image_config` OpenRouter. Використовуйте `agents.defaults.imageGenerationModel.timeoutMs` для повільніших моделей зображень OpenRouter; параметр `timeoutMs` інструмента `image_generate` для окремого виклику все одно має пріоритет.
+OpenClaw надсилає запити зображень до OpenRouter chat completions image API з `modalities: ["image", "text"]`. Моделі зображень Gemini отримують підтримувані підказки `aspectRatio` і `resolution` через `image_config` OpenRouter. Використовуйте `agents.defaults.imageGenerationModel.timeoutMs` для повільніших моделей зображень OpenRouter; параметр `timeoutMs` інструмента `image_generate` для окремого виклику все одно має пріоритет.
## Генерація відео
-OpenRouter також може забезпечувати інструмент `video_generate` через свій асинхронний API `/videos`. Використовуйте відеомодель OpenRouter у `agents.defaults.videoGenerationModel`:
+OpenRouter також може забезпечувати роботу інструмента `video_generate` через свій асинхронний API `/videos`. Використовуйте модель відео OpenRouter у `agents.defaults.videoGenerationModel`:
```json5
{
@@ -103,20 +103,20 @@ OpenRouter також може забезпечувати інструмент `
}
```
-OpenClaw надсилає до OpenRouter завдання text-to-video та image-to-video, опитує
+OpenClaw надсилає завдання text-to-video та image-to-video до OpenRouter, опитує
повернений `polling_url` і завантажує завершене відео з
-`unsigned_urls` OpenRouter або задокументованої кінцевої точки вмісту завдання.
-Еталонні зображення за замовчуванням надсилаються як зображення першого/останнього кадру; зображення,
-позначені `reference_image`, надсилаються як вхідні посилання OpenRouter. Вбудований
-типовий варіант `google/veo-3.1-fast` оголошує поточно підтримувані тривалості 4/6/8
+`unsigned_urls` OpenRouter або задокументованого endpoint вмісту завдання.
+Еталонні зображення типово надсилаються як зображення першого/останнього кадру; зображення,
+позначені `reference_image`, надсилаються як вхідні посилання OpenRouter. Вбудоване
+типове значення `google/veo-3.1-fast` оголошує поточно підтримувані тривалості 4/6/8
секунд, роздільності `720P`/`1080P` і співвідношення сторін `16:9`/`9:16`.
-Video-to-video не зареєстровано для OpenRouter, оскільки upstream
+Video-to-video не зареєстровано для OpenRouter, тому що upstream
API генерації відео наразі приймає текст і посилання на зображення.
## Перетворення тексту на мовлення
-OpenRouter також можна використовувати як провайдер TTS через його сумісну з OpenAI
-кінцеву точку `/audio/speech`.
+OpenRouter також можна використовувати як провайдера TTS через його сумісний з OpenAI
+endpoint `/audio/speech`.
```json5
{
@@ -141,10 +141,10 @@ OpenRouter також можна використовувати як прова
## Автентифікація та заголовки
-OpenRouter внутрішньо використовує Bearer-токен із вашим ключем API.
+OpenRouter використовує Bearer token із вашим API-ключем під капотом.
У реальних запитах OpenRouter (`https://openrouter.ai/api/v1`) OpenClaw також додає
-задокументовані OpenRouter заголовки атрибуції застосунку:
+задокументовані заголовки атрибуції застосунку OpenRouter:
| Заголовок | Значення |
| ------------------------- | ------------------------------------------------------------------------------------------------------ |
@@ -153,16 +153,16 @@ OpenRouter внутрішньо використовує Bearer-токен із
| `X-OpenRouter-Categories` | `cli-agent,cloud-agent,programming-app,creative-writing,writing-assistant,general-chat,personal-agent` |
-Якщо ви перенаправите провайдер OpenRouter на інший проксі або базову URL-адресу, OpenClaw
-**не** вставлятиме ці специфічні для OpenRouter заголовки або маркери кешу Anthropic.
+Якщо ви перенаправите провайдера OpenRouter на інший proxy або базовий URL, OpenClaw
+**не** вставляє ці специфічні для OpenRouter заголовки або маркери кешу Anthropic.
## Розширена конфігурація
-
- Кешування відповідей OpenRouter вмикається явно. Увімкніть його для окремої моделі OpenRouter за допомогою
- параметрів моделі:
+
+ Кешування відповідей OpenRouter вмикається явно. Увімкніть його для кожної моделі OpenRouter через
+ параметри моделі:
```json5
{
@@ -181,70 +181,72 @@ OpenRouter внутрішньо використовує Bearer-токен із
}
```
- OpenClaw надсилає `X-OpenRouter-Cache: true` і, коли налаштовано,
+ OpenClaw надсилає `X-OpenRouter-Cache: true` і, якщо налаштовано,
`X-OpenRouter-Cache-TTL`. `responseCacheClear: true` примусово оновлює
- поточний запит і зберігає замінну відповідь. Також приймаються псевдоніми snake_case
+ поточний запит і зберігає замінну відповідь. Також приймаються snake_case aliases
(`response_cache`, `response_cache_ttl_seconds` і
`response_cache_clear`).
- Це окремо від кешування промптів провайдера та від маркерів
- Anthropic `cache_control` OpenRouter. Застосовується лише на перевірених
- маршрутах `openrouter.ai`, а не на користувацьких базових URL проксі.
+ Це окремо від кешування prompt провайдера та від маркерів Anthropic
+ `cache_control` OpenRouter. Воно застосовується лише на перевірених
+ маршрутах `openrouter.ai`, а не на базових URL користувацьких proxy.
-
+
На перевірених маршрутах OpenRouter посилання на моделі Anthropic зберігають
специфічні для OpenRouter маркери Anthropic `cache_control`, які OpenClaw використовує для
- кращого повторного використання кешу промптів у блоках системних/розробницьких промптів.
+ кращого повторного використання prompt-cache у блоках system/developer prompt.
-
- На перевірених маршрутах OpenRouter посилання на моделі Anthropic з увімкненим міркуванням
- відкидають кінцеві ходи попереднього заповнення асистента до того, як запит досягне OpenRouter,
- відповідно до вимоги Anthropic, щоб розмови з міркуванням завершувалися ходом користувача.
+
+ На перевірених маршрутах OpenRouter посилання на моделі Anthropic з увімкненим reasoning
+ відкидають кінцеві попередньо заповнені ходи assistant до того, як запит досягне OpenRouter,
+ відповідно до вимоги Anthropic, що reasoning-розмови мають завершуватися ходом user.
-
- На підтримуваних не-`auto` маршрутах OpenClaw зіставляє вибраний рівень thinking із
- payloads reasoning проксі OpenRouter. Непідтримувані підказки моделей і
- `openrouter/auto` пропускають цю ін’єкцію reasoning. Hunter Alpha також пропускає
- reasoning проксі для застарілих налаштованих посилань на моделі, оскільки OpenRouter міг
- повертати текст остаточної відповіді в полях reasoning для цього вилученого маршруту.
+
+ На підтримуваних маршрутах, відмінних від `auto`, OpenClaw зіставляє вибраний рівень thinking із
+ payload reasoning proxy OpenRouter. Непідтримувані підказки моделей і
+ `openrouter/auto` пропускають це вставлення reasoning. Hunter Alpha також пропускає
+ proxy reasoning для застарілих налаштованих посилань на модель, тому що OpenRouter міг
+ повертати текст фінальної відповіді в полях reasoning для цього виведеного з використання маршруту.
-
+
На перевірених маршрутах OpenRouter `openrouter/deepseek/deepseek-v4-flash` і
`openrouter/deepseek/deepseek-v4-pro` заповнюють відсутній `reasoning_content` у
- повторно відтворених ходах асистента, щоб розмови thinking/tool зберігали потрібну для DeepSeek V4
- форму продовження.
+ повторно відтворених ходах assistant, щоб розмови thinking/tool зберігали
+ потрібну для DeepSeek V4 форму подальшого продовження. OpenClaw надсилає підтримувані OpenRouter
+ значення `reasoning_effort` для цих маршрутів; `xhigh` є найвищим оголошеним
+ рівнем, а застарілі перевизначення `max` зіставляються з `xhigh`.
-
- OpenRouter усе ще проходить шлях OpenAI-сумісного проксі-стилю, тому
+
+ OpenRouter усе ще працює через proxy-style OpenAI-compatible шлях, тому
нативне формування запитів лише для OpenAI, як-от `serviceTier`, Responses `store`,
- payloads сумісності reasoning OpenAI і підказки кешу промптів, не пересилається.
+ payload для сумісності reasoning OpenAI і підказки prompt-cache, не передається далі.
-
+
Посилання OpenRouter на базі Gemini залишаються на proxy-Gemini шляху: OpenClaw зберігає
- очищення thought-signature Gemini там, але не вмикає нативну валідацію повтору Gemini
- або bootstrap-переписування.
+ очищення thought-signature Gemini там, але не вмикає нативну валідацію replay Gemini
+ або bootstrap rewrites.
-
+
Якщо ви передаєте маршрутизацію провайдера OpenRouter у параметрах моделі, OpenClaw пересилає
- її як метадані маршрутизації OpenRouter до запуску спільних обгорток потоку.
+ її як routing metadata OpenRouter перед запуском спільних stream wrappers.
## Пов’язане
-
+
Вибір провайдерів, посилань на моделі та поведінки failover.
-
- Повний довідник конфігурації для агентів, моделей і провайдерів.
+
+ Повний довідник конфігурації для agents, models і providers.
diff --git a/docs/uk/tools/thinking.md b/docs/uk/tools/thinking.md
index 055ed8688..78b60074f 100644
--- a/docs/uk/tools/thinking.md
+++ b/docs/uk/tools/thinking.md
@@ -1,13 +1,13 @@
---
read_when:
- - Налаштування парсингу або стандартних значень для мислення, швидкого режиму чи докладної директиви
-summary: Синтаксис директив для /think, /fast, /verbose, /trace і видимості міркувань
+ - Коригування розбору або типових значень директив мислення, швидкого режиму чи докладного виводу
+summary: Синтаксис директив для /think, /fast, /verbose, /trace та видимості міркувань
title: Рівні мислення
x-i18n:
- generated_at: "2026-05-04T18:18:28Z"
+ generated_at: "2026-05-04T21:16:41Z"
model: gpt-5.5
provider: openai
- source_hash: fcd1cd76ca5d0b08656e0629df656ad8aa037201d8de68093b3e46eb0708f811
+ source_hash: d2282c9eccda4693680bbfbfc42de508021f4472b00d40a1a8c1bc19a4516012
source_path: tools/thinking.md
workflow: 16
---
@@ -20,88 +20,89 @@ x-i18n:
- low → “think hard”
- medium → “think harder”
- high → “ultrathink” (максимальний бюджет)
- - xhigh → “ultrathink+” (моделі GPT-5.2+ і Codex, а також Anthropic Claude Opus 4.7 effort)
- - adaptive → адаптивне мислення, кероване провайдером (підтримується для Claude 4.6 в Anthropic/Bedrock, Anthropic Claude Opus 4.7 і Google Gemini dynamic thinking)
- - max → максимальне міркування провайдера (Anthropic Claude Opus 4.7; Ollama зіставляє це зі своїм найвищим нативним рівнем `think`)
+ - xhigh → “ultrathink+” (моделі GPT-5.2+ і Codex, а також effort Anthropic Claude Opus 4.7)
+ - adaptive → адаптивне мислення, кероване провайдером (підтримується для Claude 4.6 в Anthropic/Bedrock, Anthropic Claude Opus 4.7 і динамічного мислення Google Gemini)
+ - max → максимальне міркування провайдера (Anthropic Claude Opus 4.7; Ollama зіставляє це зі своїм найвищим нативним effort `think`)
- `x-high`, `x_high`, `extra-high`, `extra high` і `extra_high` зіставляються з `xhigh`.
- `highest` зіставляється з `high`.
- Нотатки щодо провайдерів:
- - Меню та вибір мислення керуються профілем провайдера. Provider plugins оголошують точний набір рівнів для вибраної моделі, зокрема мітки на кшталт бінарного `on`.
- - `adaptive`, `xhigh` і `max` рекламуються лише для профілів провайдера/моделі, які їх підтримують. Типізовані директиви для непідтримуваних рівнів відхиляються з коректними параметрами для цієї моделі.
- - Наявні збережені непідтримувані рівні перепризначаються за рангом профілю провайдера. `adaptive` повертається до `medium` на неадаптивних моделях, а `xhigh` і `max` повертаються до найбільшого підтримуваного не-`off` рівня для вибраної моделі.
- - Моделі Anthropic Claude 4.6 за замовчуванням використовують `adaptive`, коли явний рівень мислення не задано.
- - Anthropic Claude Opus 4.7 не використовує адаптивне мислення за замовчуванням. Його типовий API effort лишається під контролем провайдера, якщо ви явно не задасте рівень мислення.
- - Anthropic Claude Opus 4.7 зіставляє `/think xhigh` з адаптивним мисленням плюс `output_config.effort: "xhigh"`, тому що `/think` є директивою мислення, а `xhigh` є налаштуванням effort для Opus 4.7.
- - Anthropic Claude Opus 4.7 також надає `/think max`; це зіставляється з тим самим шляхом максимального effort, керованим провайдером.
- - Моделі DeepSeek V4 надають `/think xhigh|max`; обидва зіставляються з DeepSeek `reasoning_effort: "max"`, тоді як нижчі не-`off` рівні зіставляються з `high`.
- - Моделі Ollama з підтримкою мислення надають `/think low|medium|high|max`; `max` зіставляється з нативним `think: "high"`, тому що нативний API Ollama приймає рядки effort `low`, `medium` і `high`.
- - Моделі OpenAI GPT зіставляють `/think` через підтримку effort у Responses API, специфічну для моделі. `/think off` надсилає `reasoning.effort: "none"` лише тоді, коли цільова модель це підтримує; інакше OpenClaw пропускає вимкнене корисне навантаження міркування замість надсилання непідтримуваного значення.
- - Користувацькі сумісні з OpenAI записи каталогу можуть увімкнути підтримку `/think xhigh`, задавши `models.providers..models[].compat.supportedReasoningEfforts` так, щоб він містив `"xhigh"`. Це використовує ті самі метадані сумісності, які зіставляють вихідні корисні навантаження OpenAI reasoning effort, тож меню, валідація сеансу, agent CLI і `llm-task` узгоджуються з поведінкою транспорту.
- - Застарілі налаштовані посилання OpenRouter Hunter Alpha пропускають інʼєкцію проксі-міркування, тому що цей вилучений маршрут міг повертати текст фінальної відповіді через поля міркування.
- - Google Gemini зіставляє `/think adaptive` з керованим провайдером dynamic thinking Gemini. Запити Gemini 3 пропускають фіксований `thinkingLevel`, тоді як запити Gemini 2.5 надсилають `thinkingBudget: -1`; фіксовані рівні й далі зіставляються з найближчим Gemini `thinkingLevel` або бюджетом для цієї сімʼї моделей.
- - MiniMax (`minimax/*`) на Anthropic-сумісному потоковому шляху за замовчуванням використовує `thinking: { type: "disabled" }`, якщо ви явно не задасте мислення в параметрах моделі або параметрах запиту. Це запобігає витоку дельт `reasoning_content` із ненативного потокового формату Anthropic від MiniMax.
- - Z.AI (`zai/*`) підтримує лише бінарне мислення (`on`/`off`). Будь-який не-`off` рівень вважається `on` (зіставляється з `low`).
- - Moonshot (`moonshot/*`) зіставляє `/think off` з `thinking: { type: "disabled" }`, а будь-який не-`off` рівень з `thinking: { type: "enabled" }`. Коли мислення увімкнене, Moonshot приймає лише `tool_choice` `auto|none`; OpenClaw нормалізує несумісні значення до `auto`.
+ - Меню й вибір мислення керуються профілем провайдера. Плагіни провайдерів оголошують точний набір рівнів для вибраної моделі, включно з мітками на кшталт бінарного `on`.
+ - `adaptive`, `xhigh` і `max` рекламуються лише для профілів провайдера/моделі, які їх підтримують. Типізовані директиви для непідтримуваних рівнів відхиляються з переліком припустимих параметрів для цієї моделі.
+ - Наявні збережені непідтримувані рівні перепризначаються за рангом профілю провайдера. `adaptive` на неадаптивних моделях повертається до `medium`, тоді як `xhigh` і `max` повертаються до найбільшого підтримуваного рівня, відмінного від `off`, для вибраної моделі.
+ - Моделі Anthropic Claude 4.6 типово використовують `adaptive`, якщо явний рівень мислення не задано.
+ - Anthropic Claude Opus 4.7 не використовує адаптивне мислення за замовчуванням. Типове значення effort в його API залишається під керуванням провайдера, якщо ви явно не задасте рівень мислення.
+ - Anthropic Claude Opus 4.7 зіставляє `/think xhigh` з адаптивним мисленням плюс `output_config.effort: "xhigh"`, оскільки `/think` є директивою мислення, а `xhigh` є параметром effort для Opus 4.7.
+ - Anthropic Claude Opus 4.7 також надає `/think max`; він зіставляється з тим самим шляхом максимального effort, керованого провайдером.
+ - Прямі моделі DeepSeek V4 надають `/think xhigh|max`; обидва варіанти зіставляються з DeepSeek `reasoning_effort: "max"`, тоді як нижчі рівні, відмінні від `off`, зіставляються з `high`.
+ - Моделі DeepSeek V4, маршрутизовані через OpenRouter, надають `/think xhigh` і надсилають підтримувані OpenRouter значення `reasoning_effort`. Збережені перевизначення `max` повертаються до `xhigh`.
+ - Моделі Ollama з підтримкою мислення надають `/think low|medium|high|max`; `max` зіставляється з нативним `think: "high"`, оскільки нативний API Ollama приймає рядки effort `low`, `medium` і `high`.
+ - Моделі OpenAI GPT зіставляють `/think` через підтримку effort у Responses API, специфічну для моделі. `/think off` надсилає `reasoning.effort: "none"` лише тоді, коли цільова модель це підтримує; інакше OpenClaw пропускає вимкнене навантаження міркування замість надсилання непідтримуваного значення.
+ - Власні записи каталогу, сумісні з OpenAI, можуть увімкнути `/think xhigh`, задавши `models.providers..models[].compat.supportedReasoningEfforts` так, щоб воно містило `"xhigh"`. Це використовує ті самі метадані сумісності, які зіставляють вихідні навантаження effort міркування OpenAI, тому меню, перевірка сесії, agent CLI і `llm-task` узгоджуються з поведінкою транспорту.
+ - Застарілі налаштовані посилання OpenRouter Hunter Alpha пропускають інʼєкцію проксі-міркування, оскільки цей вилучений маршрут міг повертати текст фінальної відповіді через поля міркування.
+ - Google Gemini зіставляє `/think adaptive` з динамічним мисленням Gemini, керованим провайдером. Запити Gemini 3 пропускають фіксований `thinkingLevel`, тоді як запити Gemini 2.5 надсилають `thinkingBudget: -1`; фіксовані рівні все ще зіставляються з найближчим Gemini `thinkingLevel` або бюджетом для цієї сімʼї моделей.
+ - MiniMax (`minimax/*`) на Anthropic-сумісному потоковому шляху типово використовує `thinking: { type: "disabled" }`, якщо ви явно не задасте мислення в параметрах моделі або параметрах запиту. Це запобігає витоку дельт `reasoning_content` з ненативного Anthropic-формату потоку MiniMax.
+ - Z.AI (`zai/*`) підтримує лише бінарне мислення (`on`/`off`). Будь-який рівень, відмінний від `off`, розглядається як `on` (зіставляється з `low`).
+ - Moonshot (`moonshot/*`) зіставляє `/think off` з `thinking: { type: "disabled" }`, а будь-який рівень, відмінний від `off`, з `thinking: { type: "enabled" }`. Коли мислення увімкнене, Moonshot приймає лише `tool_choice` `auto|none`; OpenClaw нормалізує несумісні значення до `auto`.
## Порядок визначення
1. Вбудована директива в повідомленні (застосовується лише до цього повідомлення).
-2. Перевизначення сеансу (задається надсиланням повідомлення лише з директивою).
+2. Перевизначення сесії (задається надсиланням повідомлення, що містить лише директиву).
3. Типове значення для агента (`agents.list[].thinkingDefault` у конфігурації).
4. Глобальне типове значення (`agents.defaults.thinkingDefault` у конфігурації).
-5. Резервний варіант: оголошене провайдером типове значення, якщо доступне; інакше моделі з підтримкою міркування визначаються як `medium` або найближчий підтримуваний не-`off` рівень для цієї моделі, а моделі без міркування лишаються `off`.
+5. Резервний варіант: типове значення, оголошене провайдером, коли доступне; інакше моделі з підтримкою міркування визначаються як `medium` або найближчий підтримуваний рівень, відмінний від `off`, для цієї моделі, а моделі без міркування залишаються `off`.
-## Налаштування типового значення сеансу
+## Налаштування типового значення сесії
- Надішліть повідомлення, яке містить **лише** директиву (пробіли дозволені), наприклад `/think:medium` або `/t high`.
-- Це закріплюється для поточного сеансу (типово для кожного відправника); очищується через `/think:off` або скидання після простою сеансу.
-- Надсилається відповідь-підтвердження (`Thinking level set to high.` / `Thinking disabled.`). Якщо рівень некоректний (наприклад, `/thinking big`), команда відхиляється з підказкою, а стан сеансу лишається незмінним.
+- Воно закріплюється для поточної сесії (типово для кожного відправника); очищується через `/think:off` або скидання після простою сесії.
+- Надсилається відповідь-підтвердження (`Thinking level set to high.` / `Thinking disabled.`). Якщо рівень недійсний (наприклад, `/thinking big`), команда відхиляється з підказкою, а стан сесії не змінюється.
- Надішліть `/think` (або `/think:`) без аргументу, щоб побачити поточний рівень мислення.
## Застосування за агентом
-- **Вбудований Pi**: визначений рівень передається в рантайм агента Pi в межах процесу.
-- **Бекенд Claude CLI**: не-`off` рівні передаються в Claude Code як `--effort` під час використання `claude-cli`; див. [CLI-бекенди](/uk/gateway/cli-backends).
+- **Вбудований Pi**: визначений рівень передається в runtime агента Pi в процесі.
+- **Бекенд Claude CLI**: рівні, відмінні від off, передаються в Claude Code як `--effort` під час використання `claude-cli`; див. [бекенди CLI](/uk/gateway/cli-backends).
## Швидкий режим (/fast)
- Рівні: `on|off`.
-- Повідомлення лише з директивою перемикає перевизначення швидкого режиму сеансу й відповідає `Fast mode enabled.` / `Fast mode disabled.`.
+- Повідомлення лише з директивою перемикає перевизначення швидкого режиму сесії й відповідає `Fast mode enabled.` / `Fast mode disabled.`.
- Надішліть `/fast` (або `/fast status`) без режиму, щоб побачити поточний ефективний стан швидкого режиму.
- OpenClaw визначає швидкий режим у такому порядку:
- 1. Вбудована директива або повідомлення лише з директивою `/fast on|off`
- 2. Перевизначення сеансу
+ 1. Вбудований/лише-директивний `/fast on|off`
+ 2. Перевизначення сесії
3. Типове значення для агента (`agents.list[].fastModeDefault`)
4. Конфігурація для моделі: `agents.defaults.models["/"].params.fastMode`
5. Резервний варіант: `off`
- Для `openai/*` швидкий режим зіставляється з пріоритетною обробкою OpenAI через надсилання `service_tier=priority` у підтримуваних запитах Responses.
- Для `openai-codex/*` швидкий режим надсилає той самий прапорець `service_tier=priority` у Codex Responses. OpenClaw зберігає один спільний перемикач `/fast` для обох шляхів автентифікації.
-- Для прямих публічних запитів `anthropic/*`, зокрема OAuth-автентифікованого трафіку, надісланого до `api.anthropic.com`, швидкий режим зіставляється з рівнями сервісу Anthropic: `/fast on` задає `service_tier=auto`, `/fast off` задає `service_tier=standard_only`.
+- Для прямих публічних запитів `anthropic/*`, включно з OAuth-автентифікованим трафіком, надісланим до `api.anthropic.com`, швидкий режим зіставляється з рівнями сервісу Anthropic: `/fast on` задає `service_tier=auto`, `/fast off` задає `service_tier=standard_only`.
- Для `minimax/*` на Anthropic-сумісному шляху `/fast on` (або `params.fastMode: true`) переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`.
-- Явні параметри моделі Anthropic `serviceTier` / `service_tier` перевизначають типове значення швидкого режиму, коли задано обидва. OpenClaw і далі пропускає інʼєкцію рівня сервісу Anthropic для базових URL проксі, які не є Anthropic.
+- Явні параметри моделі Anthropic `serviceTier` / `service_tier` перевизначають типове значення швидкого режиму, коли задано обидва. OpenClaw усе одно пропускає інʼєкцію рівня сервісу Anthropic для не-Anthropic проксі-URL бази.
- `/status` показує `Fast` лише тоді, коли швидкий режим увімкнено.
## Директиви докладності (/verbose або /v)
- Рівні: `on` (мінімальний) | `full` | `off` (типово).
-- Повідомлення лише з директивою перемикає докладність сеансу й відповідає `Verbose logging enabled.` / `Verbose logging disabled.`; некоректні рівні повертають підказку без зміни стану.
-- `/verbose off` зберігає явне перевизначення сеансу; очистьте його через UI сеансів, вибравши `inherit`.
-- Вбудована директива впливає лише на це повідомлення; інакше застосовуються типові значення сеансу/глобальні типові значення.
+- Повідомлення лише з директивою перемикає докладність сесії й відповідає `Verbose logging enabled.` / `Verbose logging disabled.`; недійсні рівні повертають підказку без зміни стану.
+- `/verbose off` зберігає явне перевизначення сесії; очистьте його через UI сесій, вибравши `inherit`.
+- Вбудована директива впливає лише на це повідомлення; інакше застосовуються типові значення сесії/глобальні типові значення.
- Надішліть `/verbose` (або `/verbose:`) без аргументу, щоб побачити поточний рівень докладності.
-- Коли докладність увімкнена, агенти, що виводять структуровані результати інструментів (Pi, інші JSON-агенти), надсилають кожен виклик інструмента назад як окреме повідомлення лише з метаданими, з префіксом ` : `, коли доступно. Ці підсумки інструментів надсилаються одразу після запуску кожного інструмента (окремі бульбашки), а не як потокові дельти.
-- Підсумки помилок інструментів лишаються видимими у звичайному режимі, але суфікси з необробленими деталями помилок приховані, якщо докладність не `on` або `full`.
-- Коли докладність дорівнює `full`, результати інструментів також пересилаються після завершення (окрема бульбашка, обрізана до безпечної довжини). Якщо перемкнути `/verbose on|full|off`, поки виконання триває, наступні бульбашки інструментів врахують нове налаштування.
-- `agents.defaults.toolProgressDetail` керує формою підсумків інструментів `/verbose` і рядків інструментів у чернетках прогресу. Використовуйте `"explain"` (типово) для компактних зрозумілих міток на кшталт `🛠️ Exec: checking JS syntax`; використовуйте `"raw"`, коли також потрібно додавати необроблену команду/деталі для налагодження. `agents.list[].toolProgressDetail` для окремого агента перевизначає типове значення.
+- Коли докладність увімкнена, агенти, які виводять структуровані результати інструментів (Pi, інші JSON-агенти), надсилають кожен виклик інструмента назад як окреме повідомлення лише з метаданими, з префіксом ` : `, коли доступно. Ці підсумки інструментів надсилаються щойно кожен інструмент запускається (окремі бульбашки), а не як потокові дельти.
+- Підсумки збоїв інструментів залишаються видимими у звичайному режимі, але сирі суфікси деталей помилок приховані, якщо докладність не `on` або `full`.
+- Коли докладність дорівнює `full`, виводи інструментів також пересилаються після завершення (окрема бульбашка, обрізана до безпечної довжини). Якщо перемкнути `/verbose on|full|off`, поки виконання триває, наступні бульбашки інструментів враховують нове налаштування.
+- `agents.defaults.toolProgressDetail` керує формою підсумків інструментів `/verbose` і рядків інструментів у чернетках прогресу. Використовуйте `"explain"` (типово) для компактних зрозумілих міток на кшталт `🛠️ Exec: checking JS syntax`; використовуйте `"raw"`, коли також потрібно додати сиру команду/деталі для налагодження. `agents.list[].toolProgressDetail` для агента перевизначає типове значення.
- `explain`: `🛠️ Exec: check JS syntax for /tmp/app.js`
- `raw`: `🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js`
## Директиви трасування Plugin (/trace)
- Рівні: `on` | `off` (типово).
-- Повідомлення лише з директивою перемикає вивід трасування Plugin у сеансі й відповідає `Plugin trace enabled.` / `Plugin trace disabled.`.
-- Вбудована директива впливає лише на це повідомлення; інакше застосовуються типові значення сеансу/глобальні типові значення.
+- Повідомлення лише з директивою перемикає вивід трасування plugin-ів сесії й відповідає `Plugin trace enabled.` / `Plugin trace disabled.`.
+- Вбудована директива впливає лише на це повідомлення; інакше застосовуються типові значення сесії/глобальні типові значення.
- Надішліть `/trace` (або `/trace:`) без аргументу, щоб побачити поточний рівень трасування.
-- `/trace` вужчий за `/verbose`: він показує лише рядки трасування/налагодження, що належать Plugin, наприклад підсумки налагодження Active Memory.
+- `/trace` вужчий за `/verbose`: він відкриває лише рядки трасування/налагодження, що належать plugin-ам, як-от налагоджувальні підсумки Active Memory.
- Рядки трасування можуть зʼявлятися в `/status` і як подальше діагностичне повідомлення після звичайної відповіді асистента.
## Видимість міркування (/reasoning)
@@ -109,36 +110,36 @@ x-i18n:
- Рівні: `on|off|stream`.
- Повідомлення лише з директивою перемикає, чи показуються блоки мислення у відповідях.
- Коли увімкнено, міркування надсилається як **окреме повідомлення** з префіксом `Reasoning:`.
-- `stream` (лише Telegram): транслює міркування в чернеткову бульбашку Telegram, поки генерується відповідь, а потім надсилає фінальну відповідь без міркування.
+- `stream` (лише Telegram): транслює міркування в бульбашку чернетки Telegram, поки відповідь генерується, а потім надсилає фінальну відповідь без міркування.
- Псевдонім: `/reason`.
- Надішліть `/reasoning` (або `/reasoning:`) без аргументу, щоб побачити поточний рівень міркування.
-- Порядок визначення: вбудована директива, потім перевизначення сеансу, потім типове значення для агента (`agents.list[].reasoningDefault`), потім резервний варіант (`off`).
+- Порядок визначення: вбудована директива, потім перевизначення сесії, потім типове значення для агента (`agents.list[].reasoningDefault`), потім резервний варіант (`off`).
-Некоректні теги міркування локальних моделей обробляються консервативно. Закриті блоки `...` лишаються прихованими у звичайних відповідях, а незакрите міркування після вже видимого тексту також приховується. Якщо відповідь повністю обгорнута в один незакритий початковий тег і інакше була б доставлена як порожній текст, OpenClaw видаляє некоректний початковий тег і доставляє решту тексту.
+Некоректні теги міркування локальної моделі обробляються консервативно. Закриті блоки `...` залишаються прихованими у звичайних відповідях, а незакрите міркування після вже видимого тексту також приховується. Якщо відповідь повністю обгорнута в один незакритий початковий тег і інакше була б доставлена як порожній текст, OpenClaw видаляє некоректний початковий тег і доставляє решту тексту.
## Повʼязане
-- Документація режиму підвищених прав міститься в [Режим підвищених прав](/uk/tools/elevated).
+- Документація підвищеного режиму розміщена в [підвищеному режимі](/uk/tools/elevated).
-## Heartbeat
+## Heartbeat-и
-- Тіло зонду Heartbeat є налаштованим запитом heartbeat (типово: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Вбудовані директиви в повідомленні heartbeat застосовуються як зазвичай (але уникайте зміни типових значень сеансу з heartbeat).
-- Доставка Heartbeat за замовчуванням обмежується лише фінальним корисним навантаженням. Щоб також надсилати окреме повідомлення `Reasoning:` (коли доступно), задайте `agents.defaults.heartbeat.includeReasoning: true` або для окремого агента `agents.list[].heartbeat.includeReasoning: true`.
+- Тіло зонду Heartbeat є налаштованим запитом Heartbeat (типово: `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`). Вбудовані директиви в повідомленні Heartbeat застосовуються як зазвичай (але уникайте зміни типових значень сесії з Heartbeat-ів).
+- Доставка Heartbeat типово надсилає лише фінальне навантаження. Щоб також надіслати окреме повідомлення `Reasoning:` (коли доступне), задайте `agents.defaults.heartbeat.includeReasoning: true` або для агента `agents.list[].heartbeat.includeReasoning: true`.
## UI вебчату
-- Селектор мислення вебчату віддзеркалює збережений рівень сеансу зі сховища/конфігурації вхідного сеансу під час завантаження сторінки.
-- Вибір іншого рівня негайно записує перевизначення сеансу через `sessions.patch`; він не чекає наступного надсилання й не є одноразовим перевизначенням `thinkingOnce`.
-- Перший параметр завжди `Default ()`, де визначене типове значення береться з профілю мислення провайдера активної моделі сеансу плюс та сама резервна логіка, яку використовують `/status` і `session_status`.
-- Селектор використовує `thinkingLevels`, повернені рядком/типовими значеннями сеансу Gateway, а `thinkingOptions` збережено як застарілий список міток. UI браузера не зберігає власний список регулярних виразів провайдерів; plugins володіють наборами рівнів, специфічними для моделей.
-- `/think:` і далі працює та оновлює той самий збережений рівень сеансу, тож директиви чату й селектор лишаються синхронізованими.
+- Селектор мислення вебчату віддзеркалює збережений рівень сесії з вхідного сховища/конфігурації сесії під час завантаження сторінки.
+- Вибір іншого рівня негайно записує перевизначення сесії через `sessions.patch`; він не чекає наступного надсилання і не є одноразовим перевизначенням `thinkingOnce`.
+- Перший параметр завжди `Default ()`, де визначене типове значення походить із профілю мислення провайдера активної моделі сесії плюс та сама резервна логіка, яку використовують `/status` і `session_status`.
+- Вибір використовує `thinkingLevels`, повернені рядком/типовими значеннями сесії Gateway, а `thinkingOptions` зберігається як застарілий список міток. UI браузера не зберігає власний список regex провайдерів; plugin-и володіють наборами рівнів, специфічними для моделей.
+- `/think:` усе ще працює й оновлює той самий збережений рівень сесії, тому директиви чату й селектор залишаються синхронізованими.
## Профілі провайдерів
-- Plugin провайдерів можуть надавати `resolveThinkingProfile(ctx)`, щоб визначати підтримувані моделлю рівні та значення за замовчуванням.
-- Plugin провайдерів, які проксіюють моделі Claude, мають повторно використовувати `resolveClaudeThinkingProfile(modelId)` з `openclaw/plugin-sdk/provider-model-shared`, щоб прямі каталоги Anthropic і проксі-каталоги залишалися узгодженими.
+- Плагіни провайдерів можуть надавати `resolveThinkingProfile(ctx)`, щоб визначити підтримувані моделлю рівні та значення за замовчуванням.
+- Плагіни провайдерів, які проксіюють моделі Claude, мають повторно використовувати `resolveClaudeThinkingProfile(modelId)` з `openclaw/plugin-sdk/provider-model-shared`, щоб прямі каталоги Anthropic і проксі-каталоги залишалися узгодженими.
- Кожен рівень профілю має збережений канонічний `id` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `adaptive` або `max`) і може містити відображуваний `label`. Бінарні провайдери використовують `{ id: "low", label: "on" }`.
-- Tool Plugin, яким потрібно перевіряти явне перевизначення мислення, мають використовувати `api.runtime.agent.resolveThinkingPolicy({ provider, model })` разом із `api.runtime.agent.normalizeThinkingLevel(...)`; вони не повинні зберігати власні списки рівнів провайдера/моделі.
-- Tool Plugin із доступом до налаштованих метаданих користувацької моделі можуть передавати `catalog` у `resolveThinkingPolicy`, щоб opt-in `compat.supportedReasoningEfforts` відображалися у валідації на боці Plugin.
+- Плагіни інструментів, яким потрібно перевіряти явне перевизначення мислення, мають використовувати `api.runtime.agent.resolveThinkingPolicy({ provider, model })` разом із `api.runtime.agent.normalizeThinkingLevel(...)`; вони не повинні зберігати власні списки рівнів провайдерів/моделей.
+- Плагіни інструментів із доступом до налаштованих метаданих користувацьких моделей можуть передавати `catalog` у `resolveThinkingPolicy`, щоб opt-in-и `compat.supportedReasoningEfforts` відображалися у перевірці на боці плагіна.
- Опубліковані застарілі хуки (`supportsXHighThinking`, `isBinaryThinking` і `resolveDefaultThinkingLevel`) залишаються адаптерами сумісності, але нові користувацькі набори рівнів мають використовувати `resolveThinkingProfile`.
-- Рядки/значення за замовчуванням Gateway надають `thinkingLevels`, `thinkingOptions` і `thinkingDefault`, щоб клієнти ACP/чату відображали ті самі ідентифікатори й мітки профілю, які використовує валідація під час виконання.
+- Рядки/значення за замовчуванням Gateway надають `thinkingLevels`, `thinkingOptions` і `thinkingDefault`, щоб клієнти ACP/чату відображали ті самі ідентифікатори й мітки профілів, які використовує перевірка під час виконання.