diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index c271bcb69..460c28bd6 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для багів моделі/провайдера + - Додавання регресійних тестів для помилок моделі/провайдера - Налагодження поведінки Gateway + агента summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-22T23:30:48Z" + generated_at: "2026-04-22T23:37:04Z" model: gpt-5.4 provider: openai - source_hash: b26f70756380e76203e61f9ee80b44b133eb813e99b9f5909c63a01fc3ec9827 + source_hash: 2bc29de65f80848b12cf5ead2e8c82b60085d6cbb017eeb1617e8406e1458f90 source_path: help/testing.md workflow: 15 --- @@ -21,7 +21,7 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює) -- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) +- Які команди запускати для типових робочих процесів (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів - Як додавати регресійні тести для реальних проблем із моделями/провайдерами @@ -30,85 +30,87 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не У більшості випадків: - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск повного набору на машині з достатніми ресурсами: `pnpm test:max` +- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` - Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `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` -Коли ви змінюєте тести або хочете більше впевненості: +Коли ви змінюєте тести або хочете додаткової впевненості: - Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` -Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): +Під час налагодження реальних провайдерів/моделей (потребує реальних облікових даних): - Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` -- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Smoke-тест вартості Moonshot/Kimi: якщо задано `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, а потім запустіть ізольований +- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Smoke-тест вартості Moonshot/Kimi: якщо встановлено `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`. + для `moonshot/kimi-k2.6`. Переконайтеся, що JSON показує Moonshot/K2.6, а + транскрипт асистента зберігає нормалізоване `usage.cost`. -Порада: коли вам потрібен лише один проблемний випадок, надавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. +Порада: коли вам потрібен лише один проблемний випадок, краще звужувати live-тести через змінні середовища allowlist, описані нижче. -## QA-специфічні ранери +## Ранери, специфічні для QA -Ці команди розташовані поруч з основними наборами тестів, коли вам потрібна реалістичність qa-lab: +Ці команди розташовані поруч із основними наборами тестів, коли вам потрібен реалізм qa-lab: - `pnpm openclaw qa suite` - - Запускає сценарії QA з репозиторію безпосередньо на хості. - - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими воркерами Gateway. Для `qa-channel` типовий рівень паралелізму — 4 (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість воркерів, або `--concurrency 1` для старішої послідовної ланки. - - Завершується з ненульовим кодом, якщо будь-який сценарій не пройшов. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - - Підтримує режими провайдера `live-frontier`, `mock-openai` і `aimock`. + - Запускає QA-сценарії з репозиторію безпосередньо на хості. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими воркерами Gateway. `qa-channel` за замовчуванням має concurrency 4 (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість воркерів, або `--concurrency 1` для старішої послідовної ланки. + - Завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без помилкового коду завершення. + - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття фікстур і моків протоколу без заміни ланки `mock-openai`, яка враховує сценарії. + покриття фікстур і моків протоколу без заміни сценарно-орієнтованої ланки `mock-openai`. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий набір QA всередині тимчасової Linux VM Multipass. + - Запускає той самий QA-набір усередині одноразової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Під час live-запусків пересилає підтримувані вхідні дані автентифікації QA, які доцільні для гостьової системи: - ключі провайдерів через env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він наявний. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через змонтовану робочу область. - - Записує звичайний QA-звіт і підсумок, а також журнали Multipass у + - Live-запуски пересилають підтримувані QA-входи автентифікації, які практично використовувати для гостьової системи: + ключі провайдерів через env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо задано. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гість міг записувати назад через змонтовану робочу область. + - Записує звичайні QA-звіт і зведення, а також логи Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. - `pnpm test:docker:bundled-channel-deps` - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway з налаштованим OpenAI, а потім вмикає Telegram і Discord через редагування конфігурації. - - Перевіряє, що під час першого перезапуску Gateway кожен вбудований channel Plugin встановлює свої runtime-залежності на вимогу, а під час другого перезапуску вже активовані залежності не перевстановлюються. - - Також встановлює відомий старіший базовий стан npm, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що після оновлення doctor у кандидата відновлює runtime-залежності вбудованих channel без postinstall-відновлення з боку harness. + - Перевіряє, що перший перезапуск Gateway установлює runtime-залежності кожного вбудованого channel Plugin на вимогу, а другий перезапуск не перевстановлює + залежності, які вже були активовані. + - Також установлює відому старішу базову версію npm, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що doctor після оновлення в candidate + відновлює runtime-залежності вбудованих channel без postinstall-відновлення з боку harness. - `pnpm openclaw qa aimock` - Запускає лише локальний сервер провайдера AIMock для прямих smoke-тестів протоколу. - `pnpm openclaw qa matrix` - - Запускає live QA-ланку Matrix проти тимчасового homeserver Tuwunel на базі Docker. - - Цей QA-хост наразі призначений лише для репозиторію/розробки. Паковані встановлення OpenClaw не постачають `qa-lab`, тож не відкривають `openclaw qa`. - - Checkout-и репозиторію завантажують вбудований ранер напряму; окремий крок встановлення plugin не потрібен. - - Надає три тимчасові користувачі Matrix (`driver`, `sut`, `observer`) і одну приватну кімнату, а потім запускає дочірній QA Gateway з реальним Matrix plugin як транспортом SUT. - - За замовчуванням використовує закріплений стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. - - Matrix не надає спільних прапорців джерела облікових даних, оскільки ланка локально створює тимчасових користувачів. - - Записує QA-звіт Matrix, підсумок, артефакт observed-events і комбінований журнал stdout/stderr у `.artifacts/qa-e2e/...`. + - Запускає live QA-ланку Matrix проти одноразового homeserver Tuwunel на базі Docker. + - Цей QA-хост наразі призначений лише для репозиторію/розробки. Упаковані інсталяції OpenClaw не постачають `qa-lab`, тому вони не надають `openclaw qa`. + - Копії репозиторію завантажують вбудований ранер напряму; окремий крок встановлення Plugin не потрібен. + - Налаштовує трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway із реальним Plugin Matrix як транспортом SUT. + - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. + - Matrix не надає спільних прапорців джерела облікових даних, оскільки ланка локально створює одноразових користувачів. + - Записує звіт Matrix QA, зведення, артефакт observed-events і об’єднаний лог stdout/stderr у `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає live QA-ланку Telegram проти реальної приватної групи з використанням токенів ботів driver і SUT із env. - - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. ID групи має бути числовим Telegram chat id. - - Підтримує `--credential-source convex` для спільних пулінгових облікових даних. Типово використовуйте режим env, або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути орендовані спільні облікові дані. - - Завершується з ненульовим кодом, якщо будь-який сценарій не пройшов. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати username у Telegram. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати груповий трафік ботів. - - Записує QA-звіт Telegram, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. + - Запускає live QA-ланку Telegram проти реальної приватної групи, використовуючи токени ботів driver і SUT із env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим ідентифікатором чату Telegram. + - Підтримує `--credential-source convex` для спільних пулових облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути спільні оренди. + - Завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без помилкового коду завершення. + - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати Telegram username. + - Для стабільного спостереження bot-to-bot увімкніть режим Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. + - Записує звіт Telegram QA, зведення й артефакт observed-messages у `.artifacts/qa-e2e/...`. -Live-транспортні ланки використовують один стандартний контракт, щоб нові транспорти не розходилися: +Live transport-ланки мають один спільний стандартний контракт, щоб нові транспорти не розходилися: -`qa-channel` залишається широким синтетичним набором QA і не входить до матриці покриття live-транспортів. +`qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live transport. -| Ланка | Канарка | Гейтинг згадок | Блок allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша дія в треді | Ізоляція тредів | Спостереження за реакціями | Команда help | -| -------- | ------- | -------------- | --------------- | ------------------------- | ----------------------------- | -------------------- | --------------- | -------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Обмеження згадок | Блок allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у треді | Ізоляція тредів | Спостереження реакцій | Команда help | +| -------- | ------ | ---------------- | -------------- | ------------------------- | ----------------------------- | -------------------------- | --------------- | --------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Спільні облікові дані Telegram через Convex (v1) @@ -116,13 +118,13 @@ Live-транспортні ланки використовують один с QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat для цієї оренди, поки ланка виконується, і звільняє оренду під час завершення роботи. -Еталонний каркас проєкту Convex: +Опорний scaffold проєкту Convex: - `qa/convex-credential-broker/` Обов’язкові змінні середовища: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` @@ -138,11 +140,11 @@ QA lab отримує ексклюзивну оренду з пулу на ба - `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://` URL Convex лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback URL Convex `http://` лише для локальної розробки. -У звичайному режимі `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. +`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. -Адміністративні команди maintainer (додавання/видалення/список пулу) вимагають +Адміністративні команди maintainer (add/remove/list пулу) вимагають саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. CLI-хелпери для maintainer: @@ -153,9 +155,9 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `--json` для машинозчитуваного виводу в скриптах і CI-утилітах. +Використовуйте `--json` для машинозчитуваного виводу в скриптах і утилітах CI. -Контракт типового endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -173,7 +175,7 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист від активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` @@ -181,60 +183,60 @@ pnpm openclaw qa credentials remove --credential-id Форма payload для типу Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком із числовим Telegram chat id. +- `groupId` має бути рядком із числовим ідентифікатором чату Telegram. - `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректний payload. -### Додавання каналу до QA +### Додавання channel до QA -Додавання каналу до markdown-системи QA вимагає рівно двох речей: +Додавання channel до markdown-системи QA потребує рівно двох речей: -1. Адаптер транспорту для каналу. -2. Набір сценаріїв, що перевіряє контракт каналу. +1. Адаптер транспорту для channel. +2. Набір сценаріїв, який перевіряє контракт channel. -Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` -може керувати цим потоком. +Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може +керувати цим процесом. -`qa-lab` відповідає за спільну хост-логіку: +`qa-lab` керує спільною механікою хоста: -- кореневий простір команд `openclaw qa` -- запуск і завершення набору -- паралелізм воркерів -- запис артефактів -- генерацію звітів -- виконання сценаріїв -- псевдоніми сумісності для старіших сценаріїв `qa-channel` +- коренем команд `openclaw qa` +- запуском і завершенням набору +- паралелізмом воркерів +- записом артефактів +- генерацією звітів +- виконанням сценаріїв +- alias сумісності для старіших сценаріїв `qa-channel` -Runner plugins відповідають за контракт транспорту: +Runner Plugin керують транспортним контрактом: - як `openclaw qa ` монтується під спільним коренем `qa` -- як налаштовується Gateway для цього транспорту +- як для цього транспорту налаштовується gateway - як перевіряється готовність - як інжектуються вхідні події - як спостерігаються вихідні повідомлення - як надаються транскрипти та нормалізований стан транспорту -- як виконуються дії з підтримкою транспорту -- як обробляються transport-specific скидання або очищення +- як виконуються дії на базі транспорту +- як обробляється специфічне для транспорту скидання або очищення -Мінімальний поріг впровадження для нового каналу: +Мінімальний поріг прийняття для нового channel: 1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте transport runner на спільному host seam `qa-lab`. -3. Зберігайте transport-specific механіку всередині runner plugin або channel harness. -4. Монтуйте ранер як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. - Залишайте `runtime-api.ts` легким; ліниве виконання CLI та раннера має залишатися за окремими entrypoint. -5. Створюйте або адаптуйте markdown-сценарії в тематичних директоріях `qa/scenarios/`. -6. Використовуйте generic helper-и сценаріїв для нових сценаріїв. -7. Зберігайте наявні compatibility alias у робочому стані, якщо тільки репозиторій не виконує навмисну міграцію. +2. Реалізуйте транспортний ранер на спільному seam хоста `qa-lab`. +3. Залишайте специфічну для транспорту механіку всередині runner Plugin або harness channel. +4. Монтуйте ранер як `openclaw qa ` замість реєстрації конкуруючого кореневого командного простору. + Runner Plugin мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. + Зберігайте `runtime-api.ts` легким; ліниве виконання CLI і раннера має залишатися за окремими entrypoint. +5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. +6. Використовуйте загальні helper сценаріїв для нових сценаріїв. +7. Зберігайте наявні alias сумісності працездатними, якщо тільки репозиторій не виконує навмисну міграцію. -Правило прийняття рішень суворе: +Правило ухвалення рішення суворе: - Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного channel transport, зберігайте її в цьому runner plugin або plugin harness. -- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте generic helper замість channel-specific гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного transport, зберігайте сценарій transport-specific і явно вказуйте це в контракті сценарію. +- Якщо поведінка залежить від одного транспорту channel, залишайте її в цьому runner Plugin або harness Plugin. +- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один channel, додавайте загальний helper замість channel-специфічної гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту й явно зазначайте це в контракті сценарію. -Бажані назви generic helper для нових сценаріїв: +Бажані назви загальних helper для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -249,7 +251,7 @@ Runner plugins відповідають за контракт транспорт - `formatTransportTranscript` - `resetTransport` -Compatibility alias залишаються доступними для наявних сценаріїв, зокрема: +Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -257,161 +259,161 @@ Compatibility alias залишаються доступними для наяв - `formatConversationTranscript` - `resetBus` -Нова робота над каналами має використовувати generic helper names. -Compatibility alias існують, щоб уникнути міграції одним днем, а не як модель для +Нова робота з channel має використовувати загальні назви helper. +Alias сумісності існують, щоб уникнути міграції одним днем, а не як модель для створення нових сценаріїв. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалістичності» (і зростання нестабільності/вартості): +Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) через наявні scoped Vitest projects -- Файли: core/unit inventory у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, які охоплює `vitest.unit.config.ts` +- Конфіг: десять послідовних запусків shard (`vitest.full-*.config.ts`) по наявних scoped Vitest projects +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і внесені до allowlist node-тести `ui`, які покриває `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - In-process integration-тести (автентифікація Gateway, маршрутизація, tooling, парсинг, конфігурація) + - Внутрішньопроцесні integration-тести (автентифікація gateway, маршрутизація, інструменти, парсинг, конфіг) - Детерміновані регресії для відомих багів - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним -- Примітка про проєкти: - - Ненацілений `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`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 process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` все ще використовує native root `vitest.config.ts` project graph, бо 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, коли diff торкається лише routable source/test файлів; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. - - `pnpm check:changed` — це звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни публічного Plugin SDK і plugin-contract включають перевірку extension, оскільки extensions залежать від цих core-контрактів. Оновлення версій лише в release metadata запускають точкові перевірки version/config/root-dependency замість повного набору, із захистом, що відхиляє зміни package поза верхньорівневим полем version. - - Легкі щодо імпортів unit-тести з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` та подібних чистих utility-областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - - Вибрані helper source files у `plugin-sdk` і `commands` також маплять changed-mode запуски на явні sibling-тести в цих легких lanes, тож зміни helper-ів не перезапускають увесь важкий набір для цієї директорії. - - `auto-reply` тепер має три виділені bucket: top-level core helper-и, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це тримає найважчу роботу harness reply осторонь від дешевих тестів status/chunk/token. +- Примітка про projects: + - Ненаправлений `pnpm test` тепер запускає одинадцять менших shard-конфігів (`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` усе ще використовує граф project native root `vitest.config.ts`, тому що багатошардовий watch-цикл непрактичний. + - `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, коли diff зачіпає лише routable source/test файли; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. + - `pnpm check:changed` — це звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, тести core, extensions, тести extension, apps, docs, метадані release і tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни у публічному SDK Plugin і plugin-contract включають валідацію extension, тому що extensions залежать від цих контрактів core. Зміни лише метаданих release із bump версії запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, що відхиляє зміни package поза полем версії верхнього рівня. + - Полегшені щодо імпортів unit-тести з agents, commands, plugins, helper auto-reply, `plugin-sdk` і подібних чистих утилітних ділянок маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. + - Вибрані вихідні helper-файли `plugin-sdk` і `commands` також зіставляють запуски changed-mode з явними сусідніми тестами в цих легких lanes, щоб редагування helper не спричиняло повторний запуск повного важкого набору для цього каталогу. + - `auto-reply` тепер має три окремі сегменти: helper верхнього рівня core, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це прибирає найважчу роботу harness reply із дешевих тестів status/chunk/token. - Примітка про embedded runner: - - Коли ви змінюєте входи виявлення message-tool або runtime context Compaction, + - Коли ви змінюєте входи виявлення message-tool або runtime-контекст Compaction, зберігайте обидва рівні покриття. - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації/нормалізації. - - Також підтримуйте здоровий стан integration-наборів embedded runner: + - Також підтримуйте здоровими integration-набори 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 id і поведінка Compaction досі проходять + - Ці набори перевіряють, що scoped id і поведінка Compaction усе ще проходять через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є достатньою заміною для цих integration-шляхів. - Примітка про pool: - - Базова конфігурація Vitest тепер типово використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, конфігураціях e2e та live. - - Коренева lane UI зберігає свій `jsdom` setup і optimizer, але тепер також працює на спільному non-isolated runner. - - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. -- Примітка про швидку локальну ітерацію: - - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. - - Pre-commit hook запускає `pnpm check:changed --staged` після форматування/linting staged-файлів, тож core-only коміти не оплачують вартість extension-тестів, якщо не торкаються публічних контрактів, орієнтованих на extension. Коміти лише з release metadata залишаються на точковій lane version/config/root-dependency. - - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи чітко мапляться на менший набір. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом воркерів. - - Автомасштабування локальних воркерів тепер навмисно консервативне і також відступає, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базова конфігурація Vitest позначає projects/config files як `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, коли змінюється wiring тестів. - - Конфігурація залишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. -- Примітка про perf-debug: - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту плюс вивід деталізації імпортів. - - `pnpm test:perf:imports:changed` обмежує той самий режим профілювання файлами, зміненими відносно `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` із native root-project path для цього закоміченого diff і друкує wall time та macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує CPU-профіль main-thread для накладних витрат запуску і transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner-а для unit-набору з вимкненим паралелізмом файлів. + - Базовий конфіг Vitest тепер типово використовує `threads`. + - Спільний конфіг Vitest також фіксує `isolate: false` і використовує неізольований runner для root projects, конфігів e2e та live. + - Root lane UI зберігає своє налаштування `jsdom` і optimizer, але тепер теж працює на спільному неізольованому runner. + - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільного конфіга Vitest. + - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх процесів Node у Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. +- Примітка про швидкі локальні ітерації: + - `pnpm changed:lanes` показує, які архітектурні lanes зачіпає diff. + - Хук pre-commit запускає `pnpm check:changed --staged` після staged formatting/linting, тому commit лише core не сплачують вартість тестів extension, якщо не зачіпають публічні контракти, орієнтовані на extension. Commit лише метаданих release залишаються на цільовій lane version/config/root-dependency. + - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи чисто відповідають меншому набору. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею воркерів. + - Автомасштабування локальних воркерів тепер навмисно консервативне й також зменшує інтенсивність, коли середнє навантаження хоста вже високе, тому кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базовий конфіг Vitest позначає projects/config-файли як `forceRerunTriggers`, щоб повторні запуски changed-mode залишалися коректними, коли змінюється wiring тестів. + - Конфіг зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одне явне розташування кешу для прямого профілювання. +- Примітка про налагодження продуктивності: + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпорту плюс вивід import-breakdown. + - `pnpm test:perf:imports:changed` обмежує той самий вигляд профілювання файлами, зміненими відносно `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project шляхом для цього закоміченого diff і виводить wall time плюс max RSS macOS. +- `pnpm test:perf:changed:bench -- --worktree` вимірює поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфіг Vitest. + - `pnpm test:perf:profile:main` записує профіль CPU основного потоку для накладних витрат запуску й трансформації Vitest/Vite. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner для unit-набору з вимкненим паралелізмом файлів. ### E2E (gateway smoke) - Команда: `pnpm test:e2e` -- Конфігурація: `vitest.e2e.config.ts` +- Конфіг: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Типові runtime-параметри: +- Типові параметри runtime: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 типово). - - Типово запускається в silent mode, щоб зменшити витрати на console I/O. + - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` для примусового задання кількості воркерів (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у консоль. + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість воркерів (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - Наскрізна поведінка multi-instance Gateway - - Поверхні WebSocket/HTTP, pairing вузлів і важче мережеве навантаження + - End-to-end поведінка gateway з кількома інстансами + - Поверхні WebSocket/HTTP, парування Node та важче мережеве навантаження - Очікування: - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - Більше рухомих частин, ніж у unit-тестів (може бути повільніше) -### E2E: smoke OpenShell backend +### E2E: smoke для backend OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` - Обсяг: - - Запускає ізольований Gateway OpenShell на хості через Docker + - Запускає ізольований gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + виконання SSH + - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - Перевіряє remote-canonical поведінку файлової системи через bridge fs sandbox - Очікування: - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локальний CLI `openshell` і робочий Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий Gateway і sandbox + - Потребує локального CLI `openshell` і працездатного Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний бінарний файл CLI або wrapper script + - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого набору e2e + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний двійковий файл CLI або wrapper script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` -- Конфігурація: `vitest.live.config.ts` +- Конфіг: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` -- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) +- Типово: **увімкнено** через `pnpm test:live` (установлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін форматів провайдера, особливостей виклику tools, проблем автентифікації та поведінки rate limit + - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - За задумом не є стабільним у CI (реальні мережі, реальні політики провайдерів, квоти, збої) - Коштує грошей / використовує rate limits - Краще запускати звужені підмножини, а не «все» -- Live-запуски підвантажують `~/.profile`, щоб отримати відсутні API-ключі. -- Типово live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth до тимчасового test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно потрібно, щоб live-тести використовували вашу реальну домашню директорію. -- `pnpm test:live` тепер типово працює в тихішому режимі: зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і вимикає журнали bootstrap Gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові журнали. -- Ротація API-ключів (специфічно для провайдера): задайте `*_API_KEYS` у форматі comma/semicolon або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для конкретного live через `OPENCLAW_LIVE_*_KEY`; тести виконують повторну спробу у відповідь на rate limit. -- Вивід progress/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдера помітно активні, навіть коли захоплення консолі Vitest працює тихо. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/Gateway одразу транслювалися під час live-запусків. - - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. +- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення `~/.profile` і приглушує логи bootstrap gateway/трафік Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете знову отримати повні логи запуску. +- Ротація API-ключів (специфічна для провайдера): установіть `*_API_KEYS` у форматі comma/semicolon або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення на рівні live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. +- Вивід прогресу/Heartbeat: + - Live-набори тепер виводять рядки прогресу в stderr, тому довгі виклики провайдера виглядають активними навіть коли захоплення консолі Vitest працює в тихому режимі. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/gateway передавалися негайно під час live-запусків. + - Налаштовуйте Heartbeat прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Використовуйте цю таблицю рішень: +Скористайтеся цією таблицею рішень: -- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змін було багато) -- Якщо торкалися мережевої взаємодії Gateway / протоколу WS / pairing: додайте `pnpm test:e2e` -- Під час налагодження «мій бот не працює» / збоїв, специфічних для провайдера / виклику tools: запускайте звужений `pnpm test:live` +- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато змінили) +- Якщо зачіпаєте мережеву взаємодію gateway / протокол WS / парування: додайте `pnpm test:e2e` +- Для налагодження «мій бот не працює» / збоїв, специфічних для провайдера / виклику інструментів: запускайте звужений `pnpm test:live` ## Live: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку зараз оголошує** підключений Android Node, і перевірити поведінку контракту команди. +- Мета: викликати **кожну команду, що наразі рекламується** підключеним Android Node, і перевірити поведінку контракту команди. - Обсяг: - - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не виконує pairing застосунку). - - Перевірка `node.invoke` у Gateway для вибраного Android Node, команда за командою. + - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не парує app). + - Перевірка `node.invoke` у gateway для вибраного Android Node, команда за командою. - Обов’язкове попереднє налаштування: - - Android app уже підключений і виконано pairing із Gateway. - - Застосунок утримується на передньому плані. - - Надані дозволи/погодження на захоплення для тих можливостей, які ви очікуєте як успішні. + - Android app уже підключено та спарено з gateway. + - App утримується на передньому плані. + - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте пройти. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Повні відомості про налаштування Android: [Android App](/uk/platforms/android) +- Повні подробиці налаштування Android: [Android App](/uk/platforms/android) ## Live: smoke моделей (ключі профілів) -Live-тести поділено на два шари, щоб можна було ізолювати збої: +Live-тести поділені на два шари, щоб можна було ізолювати збої: - «Direct model» показує, чи провайдер/модель взагалі може відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (сесії, історія, tools, sandbox policy тощо). +- «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). ### Шар 1: пряме завершення моделі (без gateway) @@ -419,86 +421,86 @@ Live-тести поділено на два шари, щоб можна бул - Мета: - Перелічити виявлені моделі - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані - - Виконати невелике completion для кожної моделі (і точкові регресії, де потрібно) + - Запустити невелике завершення для кожної моделі (і цільові регресії, де це потрібно) - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб цей набір справді запускався; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на gateway smoke +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб справді запустити цей набір; інакше він пропускається, щоб `pnpm test:live` залишався зосередженим на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist + - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це alias для сучасного allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Для modern/all sweep типово діє curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого обмеження. + - Сучасні/all-прогони за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного сучасного прогону або додатне число для меншого ліміту. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - Типово: profile store і резервні значення з env - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** + - За замовчуванням: сховище профілів і резервні значення з env + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб вимагати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «зламаний конвеєр gateway agent» - - Містить невеликі ізольовані регресії (приклад: повторення міркувань OpenAI Responses/Codex Responses + потоки tool-call) + - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр gateway agent зламаний» + - Містить невеликі, ізольовані регресії (приклад: відтворення reasoning replay + потоки tool-call у OpenAI Responses/Codex Responses) -### Шар 2: Gateway + smoke dev agent (що насправді робить "@openclaw") +### Шар 2: smoke Gateway + dev agent (те, що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Підняти in-process Gateway - - Створити/змінити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) - - Перебрати моделі з ключами та перевірити: - - «змістовну» відповідь (без tools) - - що працює реальний виклик tool (перевірка read) - - необов’язкові додаткові перевірки tools (перевірка exec+read) - - що шляхи регресії OpenAI (лише tool-call → подальший виклик) і далі працюють -- Деталі перевірок probe (щоб ви могли швидко пояснювати збої): - - `read` probe: тест записує файл із nonce у workspace і просить агента `read` його та повернути nonce. - - `exec+read` probe: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. - - image probe: тест прикріплює згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. + - Підняти in-process gateway + - Створити/пропатчити сесію `agent:dev:*` (перевизначення моделі на кожен запуск) + - Ітерувати моделі-з-ключами й перевіряти: + - «змістовну» відповідь (без інструментів) + - що реальний виклик інструмента працює (probe `read`) + - необов’язкові додаткові probe інструментів (probe `exec+read`) + - що шляхи регресії OpenAI (лише tool-call → наступний крок) продовжують працювати +- Подробиці probe (щоб ви могли швидко пояснювати збої): + - probe `read`: тест записує nonce-файл у робочій області та просить agent `read` його і повернути nonce назад. + - probe `exec+read`: тест просить agent записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. + - probe зображення: тест прикріплює згенерований PNG (кіт + рандомізований код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибирати моделі: - - Типово: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist - - Або задайте `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому) для звуження - - Для gateway sweep modern/all типово діє curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого обмеження. -- Як вибирати провайдерів (уникайте «усе з OpenRouter»): + - За замовчуванням: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це alias для сучасного allowlist + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір + - Сучасні/all gateway-прогони за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного сучасного прогону або додатне число для меншого ліміту. +- Як вибирати провайдерів (уникаючи «все через OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Перевірки tool + image завжди увімкнені в цьому live-тесті: - - `read` probe + `exec+read` probe (навантаження на tools) - - image probe запускається, коли модель оголошує підтримку image input - - Потік (на високому рівні): +- Probe інструментів і зображень у цьому live-тесті завжди ввімкнені: + - probe `read` + probe `exec+read` (навантаження на інструменти) + - probe зображення запускається, коли модель рекламує підтримку введення зображень + - Потік (високий рівень): - Тест генерує крихітний PNG з «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - Gateway парсить attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Embedded agent пересилає multimodal user message моделі + - Embedded agent пересилає моделі мультимодальне повідомлення користувача - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що можна протестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що саме ви можете тестувати на своїй машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke CLI-backend (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent з використанням локального CLI backend, не торкаючись вашої типової конфігурації. -- Типові значення smoke, специфічні для backend, розміщені у визначенні `cli-backend.ts` відповідного extension. +- Мета: перевірити конвеєр Gateway + agent із використанням локального CLI-backend, не зачіпаючи ваш типовий конфіг. +- Типові параметри smoke, специфічні для backend, розміщено у визначенні `cli-backend.ts` extension-власника. - Увімкнення: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих plugin відповідного CLI backend. + - Поведінка command/args/image походить із метаданих Plugin CLI-backend-власника. - Перевизначення (необов’язкові): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне image-attachment (шляхи інжектуються у prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до image-файлів як CLI args замість інжекції в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати передаванням image args, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити flow відновлення. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальний attachment із зображенням (шляхи інжектуються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість інжекції в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати тим, як передаються аргументи зображення, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типовий probe безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути його, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -525,29 +527,29 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker-ранер розміщено в `scripts/test-live-cli-backend-docker.sh`. +- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. - Він запускає live smoke CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. -- Він визначає метадані smoke CLI з відповідного extension, а потім установлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує portable OAuth підписки Claude Code через `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він перевіряє прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження змінних середовища Anthropic API-key. Ця ланка підписки типово вимикає перевірки Claude MCP/tool та image, тому що зараз Claude маршрутизує використання сторонніх застосунків через додаткову оплату usage, а не через звичайні ліміти плану підписки. -- Live smoke CLI-backend тепер перевіряє той самий наскрізний flow для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик tool MCP `cron`, перевірений через Gateway CLI. -- Типовий smoke Claude також змінює сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Він визначає метадані smoke CLI з extension-власника, а потім встановлює відповідний пакет Linux CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований префікс із можливістю запису за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` потребує portable Claude Code subscription OAuth через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження змінних середовища Anthropic API-key. Ця subscription-ланка за замовчуванням вимикає Claude MCP/tool і probe зображень, тому що Claude наразі маршрутизує використання сторонніх app через білінг extra-usage замість звичайних лімітів subscription plan. +- Live smoke CLI-backend тепер перевіряє той самий end-to-end потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик інструмента MCP `cron`, перевірений через gateway CLI. +- Типовий smoke Claude також патчить сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. -## Live: smoke ACP bind (`/acp spawn ... --bind here`) +## Live: smoke прив’язки ACP (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний flow conversation-bind для ACP з live ACP agent: +- Мета: перевірити реальний потік conversation-bind ACP із live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну conversation message-channel на місці - - надіслати звичайне подальше повідомлення в цю саму conversation - - перевірити, що подальше повідомлення потрапляє в transcript прив’язаної ACP-сесії + - прив’язати синтетичну розмову message-channel на місці + - надіслати звичайний наступний хід у цій самій розмові + - перевірити, що наступне повідомлення потрапляє в транскрипт пов’язаної сесії ACP - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - ACP agents у Docker: `claude,codex,gemini` - ACP agent для прямого `pnpm test:live ...`: `claude` - - Синтетичний канал: контекст conversation у стилі Slack DM - - ACP backend: `acpx` + - Синтетичний channel: контекст розмови у стилі Slack DM + - ACP-backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -555,8 +557,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Примітки: - - Ця ланка використовує поверхню Gateway `chat.send` з admin-only synthetic полями originating-route, щоб тести могли прикріплювати контекст message-channel без імітації зовнішньої доставки. - - Якщо `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness agent. + - Ця ланка використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли прикріплювати контекст message-channel без удавання зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent Plugin `acpx` для вибраного harness agent ACP. Приклад: @@ -572,7 +574,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Рецепти Docker для одного агента: +Рецепти Docker для одного agent: ```bash pnpm test:docker:live-acp-bind:claude @@ -582,35 +584,35 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker-ранер розміщено в `scripts/test-live-acp-bind-docker.sh`. -- Типово він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI agent: `claude`, `codex`, потім `gemini`. +- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає smoke прив’язки ACP послідовно для всіх підтримуваних live CLI agent: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він підвантажує `~/.profile`, переносить відповідні матеріали автентифікації CLI в контейнер, встановлює `acpx` у записуваний npm-префікс, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. -- Усередині Docker ранер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб `acpx` зберігав змінні середовища провайдера зі завантаженого профілю доступними для дочірнього CLI harness. +- Він використовує `~/.profile`, переносить відповідний матеріал автентифікації CLI в контейнер, установлює `acpx` у npm-префікс із можливістю запису, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його бракує. +- Усередині Docker ранер установлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав змінні середовища провайдера з використаного профілю доступними для дочірнього harness CLI. -## Live: smoke harness Codex app-server +## Live: smoke harness app-server Codex -- Мета: перевірити harness Codex, яким володіє plugin, через звичайний метод gateway - `agent`: - - завантажити вбудований plugin `codex` +- Мета: перевірити harness Codex, що належить Plugin, через звичайний метод + gateway `agent`: + - завантажити вбудований Plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - надіслати перший хід gateway agent до `codex/gpt-5.4` - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що потік app-server може відновитися - - виконати `/codex status` і `/codex models` через той самий командний шлях + - виконати `/codex status` і `/codex models` через той самий шлях команд gateway - - за бажанням виконати дві shell-перевірки з ескалацією, переглянуті Guardian: одну безпечну - команду, яку слід схвалити, і одне фальшиве завантаження секрету, - яке слід відхилити, щоб агент перепитав + - за потреби виконати дві shell-перевірки з ескалацією, переглянуті Guardian: одну безпечну + команду, яку слід схвалити, і одне фальшиве завантаження секрету, яке має бути + відхилене, щоб agent перепитав - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `codex/gpt-5.4` -- Необов’язкова image-перевірка: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Необов’язкова MCP/tool-перевірка: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Необов’язкова перевірка Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` +- Необов’язковий probe зображення: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язковий probe MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Необов’язковий probe Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` - Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex - не міг пройти завдяки тихому fallback на PI. -- Автентифікація: `OPENAI_API_KEY` із shell/profile, а також необов’язково скопійовані + не міг пройти, тихо переключившись на PI. +- Автентифікація: `OPENAI_API_KEY` із shell/profile, плюс за потреби скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -625,7 +627,7 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` -Docker-рецепт: +Рецепт Docker: ```bash source ~/.profile @@ -634,52 +636,52 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker-ранер розміщено в `scripts/test-live-codex-harness-docker.sh`. -- Він підвантажує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації Codex CLI, якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm - префікс, готує дерево вихідного коду, а потім запускає лише live-тест Codex-harness. -- Docker типово вмикає image-, MCP/tool- і Guardian-перевірки. Установіть +- Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + автентифікації CLI Codex, коли вони наявні, установлює `@openai/codex` у змонтований npm-префікс + із можливістю запису, готує дерево вихідного коду, а потім запускає лише live-тест Codex-harness. +- Docker за замовчуванням вмикає probe зображення, MCP/tool і Guardian. Установіть `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_GUARDIAN_PROBE=0`, коли потрібен вужчий запуск налагодження. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і live- - тестова конфігурація, щоб fallback `openai-codex/*` або PI не міг приховати - регресію harness Codex. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, відповідно до конфіга + live-тесту, щоб fallback `openai-codex/*` або PI не міг приховати регресію + harness Codex. ### Рекомендовані live-рецепти Вузькі, явні allowlist є найшвидшими й найменш нестабільними: -- Одна модель, direct (без gateway): +- Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` - Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклик tools через кількох провайдерів: +- Виклик інструментів у кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Фокус на Google (Gemini API key + Antigravity): - - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Фокус на Google (API-ключ Gemini + Antigravity): + - Gemini (API-ключ): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Примітки: -- `google/...` використовує Gemini API (API key). -- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint агента у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості tooling). +- `google/...` використовує Gemini API (API-ключ). +- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint agent у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений Gemini API від Google через HTTP (API key / автентифікація профілю); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує локальний бінарний файл `gemini`; він має власну автентифікацію та може поводитися інакше (streaming/підтримка tools/version skew). + - API: OpenClaw викликає розміщений Gemini API від Google через HTTP (автентифікація через API-ключ / профіль); саме це більшість користувачів мають на увазі під “Gemini”. + - CLI: OpenClaw виконує локальний двійковий файл `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка інструментів/розсинхрон версій). -## Live: матриця моделей (що ми охоплюємо) +## Live: матриця моделей (що ми покриваємо) -Фіксованого «списку моделей CI» немає (live — це opt-in), але ось **рекомендовані** моделі, які варто регулярно перевіряти на dev-машині з ключами. +Фіксованого «списку моделей CI» немає (live — це opt-in), але ось **рекомендовані** моделі, які варто регулярно покривати на машині розробника з ключами. -### Сучасний smoke-набір (виклик tools + image) +### Сучасний smoke-набір (виклик інструментів + зображення) -Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: +Це запуск «поширених моделей», який ми очікуємо підтримувати працездатним: - OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` @@ -689,12 +691,12 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск gateway smoke з tools + image: +Запуск gateway smoke з інструментами + зображенням: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: виклик tools (Read + необов’язковий Exec) +### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) -Виберіть щонайменше одну модель на сімейство провайдерів: +Виберіть принаймні одну модель для кожного сімейства провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -704,44 +706,44 @@ pnpm test:docker:live-codex-harness Необов’язкове додаткове покриття (приємно мати): -- xAI: `xai/grok-4` (або останню доступну) +- xAI: `xai/grok-4` (або найновіша доступна) - Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас увімкнено) -- Cerebras: `cerebras/`… (якщо маєте доступ) -- LM Studio: `lmstudio/`… (локально; виклик tools залежить від режиму API) +- Cerebras: `cerebras/`… (якщо у вас є доступ) +- LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) -### Vision: надсилання image (вкладення → multimodal message) +### Vision: надсилання зображення (attachment → мультимодальне повідомлення) -Включіть принаймні одну модель із підтримкою image у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб перевірити image probe. +Додайте принаймні одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI vision-capable варіанти тощо), щоб перевірити probe зображення. -### Агрегатори / альтернативні gateway +### Aggregators / альтернативні gateway -Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: - OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): +Більше провайдерів, які можна включити в live-матрицю (якщо у вас є облікові дані/конфіг): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (власні endpoint): `minimax` (cloud/API), а також будь-який проксі, сумісний з OpenAI/Anthropic (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні endpoint): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко прописати в документації «усі моделі». Авторитетним списком є те, що `discoverModels(...)` повертає на вашій машині + які ключі доступні. +Порада: не намагайтеся жорстко прописати «всі моделі» в документації. Авторитетний список — це те, що `discoverModels(...)` повертає на вашій машині, плюс доступні ключі. ## Облікові дані (ніколи не комітьте) -Live-тести виявляють облікові дані так само, як CLI. Практичні наслідки: +Live-тести виявляють облікові дані так само, як і CLI. Практичні наслідки: - Якщо CLI працює, live-тести мають знаходити ті самі ключі. -- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як для `openclaw models list` / вибору моделі. +- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Автентифікаційні профілі на рівні агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «profile keys» у live-тестах) -- Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо існує, але не є основним сховищем profile key) -- Локальні live-запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` прибираються, щоб probe не торкалися вашого реального workspace хоста. +- Профілі автентифікації для кожного agent: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає “profile keys” у live-тестах) +- Конфіг: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється в підготовлений live home, якщо існує, але це не основне сховище profile-key) +- Локальні live-запуски за замовчуванням копіюють активний конфіг, файли `auth-profiles.json` для кожного agent, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI в тимчасовий test home; підготовлені live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляху `agents.*.workspace` / `agentDir` вилучаються, щоб probe не торкалися вашої реальної робочої області хоста. -Якщо хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на ключі з env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Live Deepgram (аудіотранскрипція) +## Live Deepgram (транскрибування аудіо) - Тест: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` @@ -752,31 +754,31 @@ Live-тести виявляють облікові дані так само, я - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live медіа робочих процесів ComfyUI +## Live медіа workflow ComfyUI - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи comfy для image, video і `music_generate` + - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у надсиланні робочих процесів comfy, polling, завантаженнях або реєстрації plugin + - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації Plugin -## Live генерації зображень +## Live генерація зображень - Тест: `src/image-generation/runtime.live.test.ts` - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перелічує кожен зареєстрований provider plugin генерації зображень - - Завантажує відсутні env-змінні провайдерів із вашого login shell (`~/.profile`) перед перевіркою - - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Перелічує кожен зареєстрований Plugin провайдера генерації зображень + - Завантажує відсутні змінні середовища провайдерів із вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Запускає стандартні варіанти генерації зображень через спільну runtime capability: + - Запускає стандартні варіанти генерації зображень через спільну runtime-можливість: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані провайдери, які охоплюються: +- Поточні вбудовані провайдери, які покриваються: - `openai` - `google` - `xai` @@ -785,23 +787,23 @@ Live-тести виявляють облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через сховище профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env -## Live генерації музики +## Live генерація музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - Перевіряє спільний вбудований шлях провайдера генерації музики - - Наразі охоплює Google і MiniMax - - Завантажує env-змінні провайдерів із вашого login shell (`~/.profile`) перед перевіркою - - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Наразі покриває Google і MiniMax + - Завантажує змінні середовища провайдерів із вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - Пропускає провайдерів без придатної автентифікації/профілю/моделі - Запускає обидва оголошені runtime-режими, коли вони доступні: - `generate` із введенням лише prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільної ланки: + - Поточне покриття спільної lane: - `google`: `generate`, `edit` - `minimax`: `generate` - `comfy`: окремий live-файл Comfy, а не цей спільний sweep @@ -809,51 +811,51 @@ Live-тести виявляють облікові дані так само, я - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через сховище профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env -## Live генерації відео +## Live генерація відео - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - Перевіряє спільний вбудований шлях провайдера генерації відео - - Типово використовує безпечний для релізу smoke-шлях: провайдери без FAL, один text-to-video запит на провайдера, односекундний prompt із lobster і обмеження часу операції на провайдера через `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` типово) - - Типово пропускає FAL, тому що затримка черги на боці провайдера може домінувати над часом релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно - - Завантажує env-змінні провайдерів із вашого login shell (`~/.profile`) перед перевіркою - - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - За замовчуванням використовує безпечний для release smoke-шлях: провайдери без FAL, один запит text-to-video на провайдера, односекундний lobster prompt і обмеження операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) + - За замовчуванням пропускає FAL, тому що затримка черги на боці провайдера може домінувати над часом release; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно + - Завантажує змінні середовища провайдерів із вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Типово запускає лише `generate` + - За замовчуванням запускає лише `generate` - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальне введення image на основі buffer у спільному sweep - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальне введення video на основі buffer у спільному sweep - - Поточні провайдери `imageToVideo`, оголошені, але пропущені у спільному sweep: - - `vydra`, тому що вбудований `veo3` підтримує лише text-to-video, а вбудований `kling` потребує віддалений URL зображення + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід зображення на основі buffer у спільному sweep + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід відео на основі buffer у спільному sweep + - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному sweep: + - `vydra`, тому що вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддаленого URL зображення - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video, а також ланку `kling`, яка типово використовує фікстуру віддаленого URL зображення + - цей файл запускає `veo3` для text-to-video, а також lane `kling`, яка за замовчуванням використовує фікстуру віддаленого URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні провайдери `videoToVideo`, оголошені, але пропущені у спільному sweep: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи зараз потребують віддалені reference URL `http(s)` / MP4 - - `google`, тому що поточна спільна ланка Gemini/Veo використовує локальне введення на основі buffer, а цей шлях не приймається у спільному sweep - - `openai`, тому що поточна спільна ланка не має гарантій доступу до org-specific inpaint/remix для відео + - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному sweep: + - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалених референсних URL `http(s)` / MP4 + - `google`, тому що поточна спільна lane Gemini/Veo використовує локальний вхід на основі buffer, і цей шлях не приймається у спільному sweep + - `openai`, тому що поточна спільна lane не має гарантій доступу до video inpaint/remix, специфічних для org - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового sweep, включно з FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного провайдера для агресивного smoke-запуску + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера в типовий sweep, включно з FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження операції для кожного провайдера в агресивному smoke-запуску - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через сховище профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env -## Live media harness +## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори image, music і video через один рідний для репозиторію entrypoint - - Автоматично завантажує відсутні env-змінні провайдерів із `~/.profile` - - Типово автоматично звужує кожен набір до провайдерів, які зараз мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і quiet mode залишається узгодженою + - Запускає спільні live-набори для зображень, музики та відео через один нативний для репозиторію entrypoint + - Автоматично завантажує відсутні змінні середовища провайдерів із `~/.profile` + - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію + - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і тихого режиму залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -862,184 +864,188 @@ Live-тести виявляють облікові дані так само, я ## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві групи: +Ці Docker-ранери поділяються на дві категорії: -- Ранери live-моделей: `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`), монтуючи ваш локальний каталог конфігурації та workspace (і підвантажуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker-ранери live типово використовують менший smoke-cap, щоб повний Docker sweep залишався практичним: - `test:docker:live-models` типово встановлює `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` типово встановлює `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Ранери live-model: `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`), монтують ваш локальний каталог конфігурації та робочу область (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-ранери за замовчуванням мають менший 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, коли вам явно потрібне більше вичерпне сканування. -- `test:docker:all` один раз збирає Docker-образ live через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ланок live. -- Smoke-ранери контейнерів: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-lane live. +- Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` піднімають один або більше реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-ранери live-моделей також bind-mount-ять лише потрібні домашні каталоги автентифікації CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у сховищі автентифікації хоста: +Docker-ранери live-model також bind-mount лише потрібні home каталоги автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у сховищі автентифікації хоста: -- Direct models: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Smoke ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- Прямі моделі: `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`) - Smoke CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Smoke harness Codex app-server: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- Smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повне scaffold): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Мережева взаємодія Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Міст MCP channel (ініціалізований Gateway + stdio bridge + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (smoke встановлення + псевдонім `/plugin` + семантика перезапуску bundle Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Майстер онбордингу (TTY, повне scaffold): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Мережева взаємодія Gateway (два контейнери, автентифікація WS + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Міст channel MCP (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (smoke встановлення + alias `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Runtime-залежності вбудованих Plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker-образ раннера, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте образ із `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропускайте повторну збірку на хості після свіжої локальної збірки з `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Під час ітерацій звужуйте runtime-залежності вбудованих Plugin, вимикаючи не пов’язані сценарії, наприклад: + `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Docker-ранери live-моделей також bind-mount-ять поточний checkout лише для читання і -готують його у тимчасовий workdir всередині контейнера. Це зберігає runtime- -образ компактним і водночас дозволяє запускати Vitest точно на вашому локальному source/config. -Крок підготовки пропускає великі лише локальні кеші та результати збірки застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для app каталоги `.build` або вихідні каталоги Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -артефактів, специфічних для машини. -Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали +Docker-ранери live-model також bind-mount поточний checkout лише для читання і +розгортають його в тимчасовий workdir усередині контейнера. Це зберігає runtime-образ +компактним, але все одно запускає Vitest точно на вашому локальному source/config. +Крок розгортання пропускає великі локальні кеші та результати збірки app, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні каталоги `.build` або +виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +машиноспецифічних артефактів. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe gateway не запускали реальні воркери channel Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте +`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте `OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway -live-покриття з цієї Docker-ланки. -`test:docker:openwebui` — це smoke-перевірка сумісності вищого рівня: вона запускає -контейнер Gateway OpenClaw з увімкненими сумісними з OpenAI HTTP endpoint, -запускає закріплений контейнер Open WebUI проти цього Gateway, виконує вхід через -Open WebUI, перевіряє, що `/api/models` відкриває `openclaw/default`, а потім надсилає -реальний chat-запит через проксі `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися завантажити -образ Open WebUI, а самому Open WebUI може знадобитися завершити власне холодне стартове налаштування. -Ця ланка очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) — основний спосіб надати його в Dockerized-запусках. +live-покриття з цієї Docker-lane. +`test:docker:openwebui` — це суміснісний smoke вищого рівня: він запускає +контейнер gateway OpenClaw з увімкненими HTTP endpoint, сумісними з OpenAI, +запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через +Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає +реальний чат-запит через proxy `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, тому що Docker може потребувати завантаження +образу Open WebUI, а самому Open WebUI може знадобитися завершити власний cold-start setup. +Ця lane очікує придатний ключ live-моделі, і `OPENCLAW_PROFILE_FILE` +(`~/.profile` за замовчуванням) — основний спосіб надати його в Dockerized-запусках. Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно є детермінованим і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає ініціалізований контейнер Gateway, -запускає другий контейнер, який виконує `openclaw mcp serve`, а потім -перевіряє виявлення conversation з маршрутизацією, читання transcript, метадані вкладень, -поведінку live event queue, маршрутизацію outbound send і сповіщення про channel + -дозволи у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує сирі кадри stdio MCP, тож smoke перевіряє те, що -міст реально видає, а не лише те, що випадково відкриває конкретний клієнтський SDK. +`test:docker:mcp-channels` навмисно детермінований і не потребує +реального облікового запису Telegram, Discord або iMessage. Він піднімає seeded Gateway +у контейнері, запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, +поведінку черги live-подій, маршрутизацію вихідних надсилань і channel-сповіщення в стилі Claude + +сповіщення про дозволи через реальний міст stdio MCP. Перевірка сповіщень +напряму досліджує raw stdio MCP frames, тож smoke перевіряє те, що міст +справді випромінює, а не лише те, що випадково показує певний SDK клієнта. -Ручний smoke plain-language thread для ACP (не CI): +Ручний smoke plain-language thread ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. +- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації thread ACP, тож не видаляйте його. -Корисні env vars: +Корисні змінні середовища: - `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`, щоб перевіряти лише env vars, підвантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої автентифікації CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установлень CLI усередині Docker -- Зовнішні каталоги/файли автентифікації CLI під `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише змінні середовища, використані з `OPENCLAW_PROFILE_FILE`, з тимчасовими каталогами config/workspace і без монтування зовнішньої автентифікації 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_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_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_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI - `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI ## Перевірка документації -Після редагування документації запускайте перевірки документації: `pnpm check:docs`. -Запускайте повну перевірку якірних посилань Mintlify, коли вам також потрібна перевірка заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Після редагування документації запускайте перевірки docs: `pnpm check:docs`. +Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки heading у межах сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресія (безпечно для CI) +## Офлайн-регресія (безпечна для CI) Це регресії «реального конвеєра» без реальних провайдерів: -- Виклик tools Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, примусовий запис config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик інструментів gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер gateway (WS `wizard.start`/`wizard.next`, запис конфіга + примусова автентифікація): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агента (Skills) +## Оцінювання надійності agent (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності agent»: -- Mock-виклик tools через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють wiring сесій і вплив конфігурації (`src/gateway/gateway.test.ts`). +- Mock-виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- End-to-end потоки майстра, які перевіряють wiring сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Вибір рішення:** коли Skills перелічено в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/args? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок tools, перенесення історії сесії та межі sandbox. +- **Вибір рішення:** коли Skills перелічені в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)? +- **Відповідність вимогам:** чи читає agent `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? +- **Контракти робочих процесів:** багатокрокові сценарії, що перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні оцінювання мають насамперед залишатися детермінованими: +Майбутні evals мають спочатку залишатися детермінованими: -- Scenario runner із mock-провайдерами для перевірки викликів tools + їхнього порядку, читання skill-файлів і wiring сесій. -- Невеликий набір сценаріїв, сфокусованих на Skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live-eval (opt-in, із gating через env) лише після того, як буде готовий безпечний для CI набір. +- Ранер сценаріїв із mock-провайдерами для перевірки викликів інструментів + порядку, читання skill-файлів і wiring сесії. +- Невеликий набір сценаріїв, зосереджених на skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live-evals (opt-in, керовані env) лише після того, як буде готовий безпечний для CI набір. -## Contract-тести (форма plugin і channel) +## Контрактні тести (форма Plugin і channel) -Contract-тести перевіряють, що кожен зареєстрований plugin і channel відповідає -своєму контракту інтерфейсу. Вони проходять по всіх виявлених plugin і запускають набір -перевірок форми та поведінки. Типова unit-ланка `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте contract-команди явно, -коли торкаєтеся спільних поверхонь channel або provider. +Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму +контракту інтерфейсу. Вони перебирають усі виявлені Plugins і запускають набір +перевірок форми та поведінки. Типова unit-lane `pnpm test` навмисно +пропускає ці shared seam і smoke-файли; запускайте контрактні команди явно, +коли зачіпаєте спільні поверхні channel або провайдера. ### Команди - Усі контракти: `pnpm test:contracts` - Лише контракти channel: `pnpm test:contracts:channels` -- Лише контракти provider: `pnpm test:contracts:plugins` +- Лише контракти провайдерів: `pnpm test:contracts:plugins` ### Контракти channel -Розміщені в `src/channels/plugins/contracts/*.contract.test.ts`: +Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма plugin (id, name, capabilities) +- **plugin** - Базова форма Plugin (id, name, capabilities) - **setup** - Контракт майстра налаштування - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel -- **threading** - Обробка thread ID -- **directory** - API каталогу/списку учасників -- **group-policy** - Примусове застосування групової політики +- **threading** - Обробка ID thread +- **directory** - API directory/roster +- **group-policy** - Застосування групової політики -### Контракти статусу provider +### Контракти статусу провайдера -Розміщені в `src/plugins/contracts/*.contract.test.ts`. +Розташовані в `src/plugins/contracts/*.contract.test.ts`. - **status** - Перевірки статусу channel -- **registry** - Форма реєстру plugin +- **registry** - Форма реєстру Plugin -### Контракти provider +### Контракти провайдерів -Розміщені в `src/plugins/contracts/*.contract.test.ts`: +Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір/селектор автентифікації +- **auth-choice** - Вибір/selection автентифікації - **catalog** - API каталогу моделей -- **discovery** - Виявлення plugin -- **loader** - Завантаження plugin -- **runtime** - Runtime provider -- **shape** - Форма/інтерфейс plugin +- **discovery** - Виявлення Plugin +- **loader** - Завантаження Plugin +- **runtime** - Runtime провайдера +- **shape** - Форма/інтерфейс Plugin - **wizard** - Майстер налаштування ### Коли запускати -- Після змін export/subpath у plugin-sdk -- Після додавання або зміни channel чи provider plugin -- Після рефакторингу реєстрації або виявлення plugin +- Після зміни export або subpath у plugin-sdk +- Після додавання або зміни channel чи Plugin провайдера +- Після рефакторингу реєстрації або виявлення Plugin -Contract-тести запускаються в CI і не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API-ключів. -## Додавання регресійних тестів (рекомендації) +## Додавання регресій (рекомендації) -Коли ви виправляєте проблему provider/model, виявлену в live: +Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Додайте безпечну для CI регресію, якщо це можливо (mock/stub provider або фіксація точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live-only (rate limits, політики автентифікації), залишайте live-тест вузьким і opt-in через env vars -- Надавайте перевагу найменшому шару, який ловить баг: - - баг перетворення/повторення запиту provider → direct models test - - баг конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI gateway mock test +- Додайте безпечну для CI регресію, якщо це можливо (mock/stub провайдера або фіксація точної трансформації форми запиту) +- Якщо це за своєю природою лише live-випадок (rate limits, політики автентифікації), залишайте live-тест вузьким і opt-in через env vars +- Віддавайте перевагу найменшому шару, який ловить баг: + - баг перетворення/повторення запиту провайдера → тест прямих моделей + - баг конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI gateway mock-тест - Guardrail обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибрану ціль на клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегмента обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. + - Якщо ви додаєте нове сімейство цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою на некласифікованих target id, щоб нові класи не можна було тихо пропустити.