diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 460c28bd6..cc7aeec72 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для помилок моделі/провайдера - - Налагодження поведінки Gateway + агента + - Додавання регресійних тестів для помилок моделей/провайдерів + - Налагодження поведінки Gateway + агентів summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-22T23:37:04Z" + generated_at: "2026-04-22T23:49:17Z" model: gpt-5.4 provider: openai - source_hash: 2bc29de65f80848b12cf5ead2e8c82b60085d6cbb017eeb1617e8406e1458f90 + source_hash: 7d1392e0a46c5d142d65852e9d05179cce6bb1cd93df2fb372fdf13de6681a8a source_path: help/testing.md workflow: 15 --- @@ -21,9 +21,9 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює) -- Які команди запускати для типових робочих процесів (локально, перед push, налагодження) +- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресійні тести для реальних проблем із моделями/провайдерами +- Як додавати регресійні тести для реальних проблем моделей/провайдерів ## Швидкий старт @@ -33,92 +33,87 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Швидший локальний запуск повного набору на потужній машині: `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-набір (моделі + Gateway tool/image probes): `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`, потім запустіть ізольований +- 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: - `pnpm openclaw qa suite` - Запускає QA-сценарії з репозиторію безпосередньо на хості. - - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими воркерами Gateway. `qa-channel` за замовчуванням має concurrency 4 (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість воркерів, або `--concurrency 1` для старішої послідовної ланки. - - Завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без помилкового коду завершення. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими Gateway workers. `qa-channel` за замовчуванням має concurrency 4 (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість workers, або `--concurrency 1` для старішої послідовної ланки. + - Повертає ненульовий код завершення, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття фікстур і моків протоколу без заміни сценарно-орієнтованої ланки `mock-openai`. + `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального покриття fixture і protocol-mock без заміни ланки `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-входи автентифікації, які практичні для guest: + ключі провайдерів на основі env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через змонтований workspace. + - Записує звичайний 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 установлює runtime-залежності кожного вбудованого channel Plugin на вимогу, а другий перезапуск не перевстановлює - залежності, які вже були активовані. - - Також установлює відому старішу базову версію npm, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що doctor після оновлення в candidate - відновлює runtime-залежності вбудованих channel без postinstall-відновлення з боку harness. + - Перевіряє, що перший перезапуск Gateway встановлює runtime-залежності кожного bundled channel plugin на вимогу, а другий перезапуск не перевстановлює залежності, які вже були активовані. + - Також встановлює відому старішу базову версію npm, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що post-update doctor у кандидата відновлює runtime-залежності bundled channels без postinstall-відновлення з боку harness. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямих smoke-тестів протоколу. + - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає 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/...`. + - Запускає live QA-ланку Matrix проти тимчасового homeserver Tuwunel на базі Docker. + - Цей QA-хост наразі призначений лише для repo/dev. Упаковані встановлення OpenClaw не постачають `qa-lab`, тому вони не відкривають `openclaw qa`. + - Checkout-и репозиторію завантажують bundled runner безпосередньо; окремий крок встановлення plugin не потрібен. + - Надає три тимчасові користувачі Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway з реальним Matrix plugin як transport 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/...`. - `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`. Ідентифікатор групи має бути числовим ідентифікатором чату 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 QA-ланку Telegram проти реальної приватної групи, використовуючи токени driver і SUT bot із env. + - Потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. + - Підтримує `--credential-source convex` для спільних пулових облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. + - Повертає ненульовий код завершення, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. + - Потрібні два різні боти в одній приватній групі, причому SUT bot має мати Telegram username. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що driver bot може спостерігати трафік ботів у групі. + - Записує QA-звіт Telegram, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. -Live transport-ланки мають один спільний стандартний контракт, щоб нові транспорти не розходилися: +Live transport lanes мають один спільний стандартний контракт, щоб нові transports не відхилялися: `qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live transport. -| Lane | Canary | Обмеження згадок | Блок allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у треді | Ізоляція тредів | Спостереження реакцій | Команда help | -| -------- | ------ | ---------------- | -------------- | ------------------------- | ----------------------------- | -------------------------- | --------------- | --------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Ланка | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Продовження в треді | Ізоляція тредів | Спостереження за реакціями | Команда help | +| -------- | ------ | -------------- | -------------------- | ------------------------- | ----------------------------- | ------------------- | --------------- | -------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Спільні облікові дані Telegram через Convex (v1) -Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), -QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat -для цієї оренди, поки ланка виконується, і звільняє оренду під час завершення роботи. +Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat цієї оренди, поки ланка працює, і звільняє оренду під час завершення роботи. -Опорний scaffold проєкту Convex: +Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` @@ -130,7 +125,7 @@ QA lab отримує ексклюзивну оренду з пулу на ба - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Типове значення через env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) + - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) Необов’язкові змінні середовища: @@ -140,14 +135,13 @@ 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 URL Convex `http://` лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL-адреси Convex лише для локальної розробки. -`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. +У нормальному режимі `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. -Адміністративні команди maintainer (add/remove/list пулу) вимагають -саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. +Адміністративні команди maintainer (додавання/видалення/список пулу) вимагають саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-хелпери для maintainer: +CLI-хелпери для maintainers: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -155,9 +149,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 }` @@ -180,61 +174,60 @@ pnpm openclaw qa credentials remove --credential-id - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` -Форма payload для типу Telegram: +Форма payload для виду Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком із числовим ідентифікатором чату Telegram. +- `groupId` має бути рядком із числовим Telegram chat id. - `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректний payload. -### Додавання channel до QA +### Додавання каналу до QA -Додавання channel до markdown-системи QA потребує рівно двох речей: +Додавання каналу до markdown QA system вимагає рівно двох речей: -1. Адаптер транспорту для channel. -2. Набір сценаріїв, який перевіряє контракт channel. +1. Адаптер transport для каналу. +2. Набір сценаріїв, який перевіряє контракт каналу. -Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може -керувати цим процесом. +Не додавайте новий кореневий QA-командний простір верхнього рівня, коли спільний хост `qa-lab` може керувати цим потоком. `qa-lab` керує спільною механікою хоста: -- коренем команд `openclaw qa` +- кореневим командним простором `openclaw qa` - запуском і завершенням набору -- паралелізмом воркерів +- concurrency workers - записом артефактів - генерацією звітів - виконанням сценаріїв -- alias сумісності для старіших сценаріїв `qa-channel` +- aliases сумісності для старіших сценаріїв `qa-channel` -Runner Plugin керують транспортним контрактом: +Плагіни раннерів керують контрактом transport: - як `openclaw qa ` монтується під спільним коренем `qa` -- як для цього транспорту налаштовується gateway +- як Gateway налаштовується для цього transport - як перевіряється готовність -- як інжектуються вхідні події +- як ін’єктуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються транскрипти та нормалізований стан транспорту -- як виконуються дії на базі транспорту -- як обробляється специфічне для транспорту скидання або очищення +- як відкриваються транскрипти й нормалізований стан transport +- як виконуються дії на основі transport +- як обробляються скидання або очищення, специфічні для transport -Мінімальний поріг прийняття для нового channel: +Мінімальний поріг прийняття для нового каналу: 1. Залишайте `qa-lab` власником спільного кореня `qa`. -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. +2. Реалізуйте transport runner на спільному host seam `qa-lab`. +3. Залишайте transport-специфічну механіку всередині runner plugin або channel harness. +4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючого кореневого command. + Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. + Залишайте `runtime-api.ts` легким; ліниві CLI і виконання runner мають залишатися за окремими entrypoints. 5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте загальні helper сценаріїв для нових сценаріїв. -7. Зберігайте наявні alias сумісності працездатними, якщо тільки репозиторій не виконує навмисну міграцію. +6. Використовуйте загальні scenario helpers для нових сценаріїв. +7. Підтримуйте наявні aliases сумісності, якщо тільки репозиторій не виконує навмисну міграцію. Правило ухвалення рішення суворе: - Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного транспорту channel, залишайте її в цьому runner Plugin або harness Plugin. -- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один channel, додавайте загальний helper замість channel-специфічної гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту й явно зазначайте це в контракті сценарію. +- Якщо поведінка залежить від одного channel transport, залишайте її в цьому runner plugin або plugin harness. +- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте загальний helper замість channel-специфічної гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного transport, залишайте сценарій transport-специфічним і явно зазначайте це в контракті сценарію. Бажані назви загальних helper для нових сценаріїв: @@ -251,7 +244,7 @@ Runner Plugin керують транспортним контрактом: - `formatTransportTranscript` - `resetTransport` -Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: +Aliases сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -259,90 +252,90 @@ Alias сумісності залишаються доступними для н - `formatConversationTranscript` - `resetBus` -Нова робота з channel має використовувати загальні назви helper. -Alias сумісності існують, щоб уникнути міграції одним днем, а не як модель для +Нова робота з каналами має використовувати загальні назви helper. +Aliases сумісності існують, щоб уникнути міграції за прапорцевим днем, а не як модель для створення нових сценаріїв. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): +Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфіг: десять послідовних запусків 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` +- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) по наявних scoped Vitest projects +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, що охоплюються `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - Внутрішньопроцесні integration-тести (автентифікація gateway, маршрутизація, інструменти, парсинг, конфіг) - - Детерміновані регресії для відомих багів + - In-process integration-тести (автентифікація gateway, маршрутизація, tooling, парсинг, конфігурація) + - Детерміновані регресійні тести для відомих помилок - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним -- Примітка про 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. +- Примітка щодо 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 process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. + - `pnpm test --watch` і далі використовує native root граф project із `vitest.config.ts`, тому що multi-shard watch loop непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test files; редагування 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 включають перевірку extensions, тому що extensions залежать від цих core-контрактів. Підвищення версії лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, що відхиляє зміни пакунків поза полем версії верхнього рівня. + - Легкі за імпортом unit-тести з agents, commands, plugins, helpers auto-reply, `plugin-sdk` та подібних чистих utility-областей маршрутизуються через lane `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy files залишаються на наявних lanes. + - Деякі helper source files у `plugin-sdk` і `commands` також зіставляють запуски changed-mode з явними sibling tests у цих легких lanes, тож редагування helper уникають повторного запуску повного важкого набору для цього каталогу. + - `auto-reply` тепер має три окремі buckets: helpers core верхнього рівня, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply подалі від дешевих тестів status/chunk/token. - Примітка про embedded runner: - - Коли ви змінюєте входи виявлення message-tool або runtime-контекст Compaction, + - Коли ви змінюєте входи виявлення message-tool або runtime context Compaction, зберігайте обидва рівні покриття. - - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації/нормалізації. + - Додавайте сфокусовані helper-регресії для чистих меж routing/normalization. - Також підтримуйте здоровими 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.test.ts`, і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка Compaction усе ще проходять + - Ці набори перевіряють, що scoped ids і поведінка Compaction і далі проходять через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є достатньою заміною для цих integration-шляхів. - Примітка про pool: - - Базовий конфіг 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`, якщо хочете одне явне розташування кешу для прямого профілювання. + - Базова конфігурація Vitest тепер типово використовує `threads`. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e і live configs. + - Root lane UI зберігає своє налаштування `jsdom` і optimizer, але тепер теж працює на спільному non-isolated runner. + - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. + - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-processes Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. +- Примітка про швидку локальну ітерацію: + - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. + - Pre-commit hook запускає `pnpm check:changed --staged` після staged formatting/linting, тож коміти лише core не оплачують вартість extension tests, якщо вони не торкаються публічних контрактів, орієнтованих на extensions. Коміти лише з release metadata залишаються на цільовій lane version/config/root-dependency. + - `pnpm test:changed` маршрутизується через scoped lanes, коли змінені шляхи чисто зіставляються з меншим набором. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом workers. + - Автомасштабування локальних workers тепер навмисно консервативне й також зменшує навантаження, коли середнє завантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає projects/config files як `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:imports` вмикає звітування Vitest про тривалість імпорту та вивід import-breakdown. + - `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` виконує benchmark поточного брудного дерева, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує профіль CPU main-thread для накладних витрат запуску й трансформації 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: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати на console I/O. + - Використовує адаптивних workers (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням працює в silent mode, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість воркерів (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. + - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість workers (обмеження 16). + - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - End-to-end поведінка gateway з кількома інстансами - - Поверхні WebSocket/HTTP, парування Node та важче мережеве навантаження + - End-to-end-поведінка gateway з кількома інстансами + - Поверхні WebSocket/HTTP, pairing вузлів і важчі мережеві сценарії - Очікування: - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж у unit-тестів (може бути повільніше) + - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: smoke для backend OpenShell +### E2E: smoke OpenShell backend - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` @@ -350,78 +343,78 @@ Alias сумісності існують, щоб уникнути міграц - Запускає ізольований gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical поведінку файлової системи через bridge fs sandbox + - Перевіряє remote-canonical-поведінку файлової системи через sandbox fs bridge - Очікування: - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і працездатного Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox + - Потрібні локальний CLI `openshell` і робочий Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, потім знищує test 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 binary або 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`) - Обсяг: - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit + - Виявлення змін формату провайдера, особливостей виклику tool, проблем автентифікації та поведінки 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. -- Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, тому довгі виклики провайдера виглядають активними навіть коли захоплення консолі Vitest працює в тихому режимі. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/gateway передавалися негайно під час live-запусків. - - Налаштовуйте Heartbeat прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють конфігурацію/матеріали автентифікації в тимчасовий test home, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний home directory. +- `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, тож рядки progress провайдера/Gateway передаються негайно під час live-запусків. + - Налаштовуйте Heartbeat direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - Налаштовуйте Heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? Скористайтеся цією таблицею рішень: -- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато змінили) -- Якщо зачіпаєте мережеву взаємодію gateway / протокол WS / парування: додайте `pnpm test:e2e` -- Для налагодження «мій бот не працює» / збоїв, специфічних для провайдера / виклику інструментів: запускайте звужений `pnpm test:live` +- Редагування логіки/тестів: запустіть `pnpm test` (і `pnpm test:coverage`, якщо ви багато чого змінили) +- Якщо торкалися мережевої взаємодії gateway / протоколу WS / pairing: додайте `pnpm test:e2e` +- Під час налагодження «мій бот не працює» / збоїв, специфічних для провайдера / виклику tool: запустіть звужений `pnpm test:live` ## Live: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, що наразі рекламується** підключеним Android Node, і перевірити поведінку контракту команди. +- Мета: викликати **кожну команду, яку наразі оголошує** підключений Android Node, і перевірити поведінку контракту команди. - Обсяг: - - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не парує app). + - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не pair-ить застосунок). - Перевірка `node.invoke` у gateway для вибраного Android Node, команда за командою. - Обов’язкове попереднє налаштування: - - Android app уже підключено та спарено з gateway. - - App утримується на передньому плані. - - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте пройти. + - Android-застосунок уже підключено та спарено з gateway. + - Застосунок утримується на передньому плані. + - Для можливостей, які ви очікуєте як успішні, надано дозволи/згоду на захоплення. - Необов’язкові перевизначення цілі: - `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) -## Live: smoke моделей (ключі профілів) +## Live: smoke-тест моделей (ключі профілів) -Live-тести поділені на два шари, щоб можна було ізолювати збої: +Live-тести поділено на два шари, щоб можна було ізолювати збої: -- «Direct model» показує, чи провайдер/модель взагалі може відповісти з наданим ключем. -- «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). +- «Direct model» показує, чи провайдер/модель взагалі може відповідати з наданим ключем. +- «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (сесії, історія, tools, policy sandbox тощо). ### Шар 1: пряме завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані - - Запустити невелике завершення для кожної моделі (і цільові регресії, де це потрібно) + - Використовувати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані + - Виконати невелике завершення для кожної моделі (і цільові регресії, де потрібно) - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб справді запустити цей набір; інакше він пропускається, щоб `pnpm test:live` залишався зосередженим на gateway smoke @@ -429,78 +422,78 @@ Live-тести поділені на два шари, щоб можна бул - `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 через кому) - - Сучасні/all-прогони за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного сучасного прогону або додатне число для меншого ліміту. + - Розгортки modern/all за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної сучасної розгортки або додатне число для меншого обмеження. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: сховище профілів і резервні значення з env - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб вимагати **лише сховище профілів** + - За замовчуванням: сховище профілів і резервні значення env + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр gateway agent зламаний» - - Містить невеликі, ізольовані регресії (приклад: відтворення reasoning replay + потоки tool-call у OpenAI Responses/Codex Responses) + - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) -### Шар 2: smoke Gateway + dev agent (те, що насправді робить "@openclaw") +### Шар 2: Gateway + smoke dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - Підняти in-process gateway - - Створити/пропатчити сесію `agent:dev:*` (перевизначення моделі на кожен запуск) - - Ітерувати моделі-з-ключами й перевіряти: - - «змістовну» відповідь (без інструментів) - - що реальний виклик інструмента працює (probe `read`) - - необов’язкові додаткові probe інструментів (probe `exec+read`) - - що шляхи регресії OpenAI (лише tool-call → наступний крок) продовжують працювати + - Створити/оновити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) + - Ітерувати моделі з ключами та перевіряти: + - «осмислену» відповідь (без tools) + - що реальний виклик tool працює (probe читання) + - необов’язкові додаткові probes tools (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`. + - probe `read`: тест записує nonce-файл у workspace і просить agent `read` його та повернути nonce. + - probe `exec+read`: тест просить agent через `exec` записати nonce у тимчасовий файл, а потім прочитати його через `read`. + - image probe: тест прикріплює згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. + - Еталон реалізації: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибирати моделі: - За замовчуванням: сучасний 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_MODELS="provider/model"` (або список через кому), щоб звузити набір + - Розгортки modern/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 через кому) -- Probe інструментів і зображень у цьому live-тесті завжди ввімкнені: - - probe `read` + probe `exec+read` (навантаження на інструменти) - - probe зображення запускається, коли модель рекламує підтримку введення зображень - - Потік (високий рівень): - - Тест генерує крихітний PNG з «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) +- Probes tool + image у цьому live-тесті завжди увімкнені: + - probe `read` + probe `exec+read` (навантаження на tools) + - image 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 пересилає моделі мультимодальне повідомлення користувача + - Embedded agent передає моделі мультимодальне повідомлення користувача - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що саме ви можете тестувати на своїй машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні id `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`, щоб надіслати реальний 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`, щоб примусово ввімкнути його, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне вкладення-зображення (шляхи ін’єктуються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як CLI args замість ін’єкції в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати тим, як передаються args зображень, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік resume. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово її ввімкнути, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -527,29 +520,29 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. -- Він визначає метадані 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 і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Docker-runner розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає smoke CLI-backend live всередині Docker-образу репозиторію як непривілейований користувач `node`. +- Він визначає метадані smoke CLI з extension-власника, а потім встановлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний prefix за адресою `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. Ця ланка підписки типово вимикає probes Claude MCP/tool та image, оскільки Claude наразі маршрутизує використання сторонніх застосунків через billing додаткового використання замість звичайних лімітів плану підписки. +- Smoke CLI-backend live тепер перевіряє той самий end-to-end-потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик tool `cron` через MCP, перевірений через CLI gateway. +- Типовий smoke Claude також оновлює сесію із Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. -## Live: smoke прив’язки ACP (`/acp spawn ... --bind here`) +## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік conversation-bind ACP із live ACP agent: +- Мета: перевірити реальний потік bind розмови ACP з live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну розмову message-channel на місці - - надіслати звичайний наступний хід у цій самій розмові - - перевірити, що наступне повідомлення потрапляє в транскрипт пов’язаної сесії ACP + - прив’язати синтетичну conversation message-channel на місці + - надіслати звичайний подальший запит у тій самій conversation + - перевірити, що подальший запит потрапляє в transcript прив’язаної сесії 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` - - Синтетичний channel: контекст розмови у стилі Slack DM - - ACP-backend: `acpx` + - Синтетичний канал: контекст conversation у стилі Slack DM + - ACP backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -557,8 +550,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 синтетичними полями originating-route, щоб тести могли прикріплювати контекст message-channel без удавання зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent Plugin `acpx` для вибраного harness agent ACP. + - Ця ланка використовує поверхню `chat.send` у gateway з admin-only synthetic полями originating-route, щоб тести могли приєднувати контекст message-channel, не вдаючи зовнішню доставку. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent плагіна `acpx` для вибраного ACP harness agent. Приклад: @@ -584,35 +577,35 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає smoke прив’язки ACP послідовно для всіх підтримуваних live CLI agent: `claude`, `codex`, потім `gemini`. +- Docker-runner розташований у `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI agents: `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 зберігав змінні середовища провайдера з використаного профілю доступними для дочірнього harness CLI. +- Він використовує `~/.profile`, передає відповідні auth-матеріали CLI у контейнер, встановлює `acpx` у записуваний npm prefix, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. +- Усередині Docker runner встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав змінні середовища провайдера з підключеного профілю доступними для дочірнього harness CLI. -## Live: smoke harness app-server Codex +## Live: smoke harness Codex app-server -- Мета: перевірити harness Codex, що належить Plugin, через звичайний метод - gateway `agent`: - - завантажити вбудований Plugin `codex` +- Мета: перевірити harness Codex, якому належить plugin, через звичайний gateway + метод `agent`: + - завантажити bundled plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - надіслати перший хід gateway agent до `codex/gpt-5.4` - - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що потік + - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що thread app-server може відновитися - - виконати `/codex status` і `/codex models` через той самий шлях команд - gateway - - за потреби виконати дві shell-перевірки з ескалацією, переглянуті Guardian: одну безпечну - команду, яку слід схвалити, і одне фальшиве завантаження секрету, яке має бути + - запустити `/codex status` і `/codex models` через той самий шлях gateway + command + - за потреби виконати дві escalated shell probes, перевірені Guardian: одну нешкідливу + command, яку слід схвалити, і одне фальшиве вивантаження секрету, яке має бути відхилене, щоб agent перепитав - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `codex/gpt-5.4` -- Необов’язковий 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 - не міг пройти, тихо переключившись на PI. -- Автентифікація: `OPENAI_API_KEY` із shell/profile, плюс за потреби скопійовані +- Необов’язковий image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язковий MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Необов’язковий Guardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` +- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex + harness не міг пройти, тихо переключившись назад на Pi. +- Auth: `OPENAI_API_KEY` із shell/profile, а також необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -636,52 +629,51 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- 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. Установіть +- Docker-runner розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли auth Codex CLI + за наявності, встановлює `@openai/codex` у записуваний змонтований npm + prefix, готує дерево вихідного коду, а потім запускає лише live-тест Codex-harness. +- Docker типово вмикає probes image, MCP/tool і Guardian. Установіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` або - `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий запуск - налагодження. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, відповідно до конфіга - live-тесту, щоб fallback `openai-codex/*` або PI не міг приховати регресію - harness Codex. + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли вам потрібен вужчий запуск для налагодження. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і live + test config, тож fallback `openai-codex/*` або Pi не може приховати регресію + Codex harness. ### Рекомендовані live-рецепти -Вузькі, явні allowlist є найшвидшими й найменш нестабільними: +Вузькі, явні allowlist — найшвидші та найменш нестабільні: -- Одна модель, напряму (без gateway): +- Одна модель, direct (без 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` -- Виклик інструментів у кількох провайдерів: +- Виклик tool у кількох провайдерів: - `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 (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` +- Фокус на Google (API key Gemini + Antigravity): + - Gemini (API key): `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-ключ). -- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint agent у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). +- `google/...` використовує API Gemini (API key). +- `google-antigravity/...` використовує OAuth-міст Antigravity (endpoint agent у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема auth + особливості tooling). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений Gemini API від Google через HTTP (автентифікація через API-ключ / профіль); саме це більшість користувачів мають на увазі під “Gemini”. - - CLI: OpenClaw виконує локальний двійковий файл `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка інструментів/розсинхрон версій). + - API: OpenClaw викликає розміщений Gemini API від Google через HTTP (API key / auth профілю); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw викликає локальний binary `gemini`; він має власну auth і може поводитися інакше (підтримка streaming/tool/розбіжність версій). -## Live: матриця моделей (що ми покриваємо) +## Live: матриця моделей (що ми охоплюємо) -Фіксованого «списку моделей CI» немає (live — це opt-in), але ось **рекомендовані** моделі, які варто регулярно покривати на машині розробника з ключами. +Фіксованого «списку моделей CI» не існує (live — opt-in), але це **рекомендовані** моделі, які варто регулярно покривати на машині розробника з ключами. -### Сучасний smoke-набір (виклик інструментів + зображення) +### Сучасний набір smoke (виклик tool + image) -Це запуск «поширених моделей», який ми очікуємо підтримувати працездатним: +Це запуск «поширених моделей», який ми очікуємо підтримувати в робочому стані: - OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` @@ -691,12 +683,12 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск gateway smoke з інструментами + зображенням: +Запустіть gateway smoke з tools + image: `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` -### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) +### Базовий рівень: виклик tool (Read + необов’язково Exec) -Виберіть принаймні одну модель для кожного сімейства провайдерів: +Виберіть щонайменше одну модель на сімейство провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -704,81 +696,81 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (приємно мати): +Необов’язкове додаткове покриття (було б добре мати): - xAI: `xai/grok-4` (або найновіша доступна) - Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас увімкнено) -- Cerebras: `cerebras/`… (якщо у вас є доступ) -- LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) +- Cerebras: `cerebras/`… (якщо маєте доступ) +- LM Studio: `lmstudio/`… (локально; виклик tool залежить від режиму API) -### Vision: надсилання зображення (attachment → мультимодальне повідомлення) +### Vision: надсилання image (вкладення → мультимодальне повідомлення) -Додайте принаймні одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI vision-capable варіанти тощо), щоб перевірити probe зображення. +Додайте принаймні одну модель із підтримкою image у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI-варіанти з підтримкою vision тощо), щоб перевірити image probe. -### Aggregators / альтернативні gateway +### Aggregators / alternate gateways Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) -- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти відповідних кандидатів із підтримкою tool+image) +- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити в live-матрицю (якщо у вас є облікові дані/конфіг): +Більше провайдерів, які можна включити до live-матриці (якщо маєте creds/config): - Вбудовані: `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-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який проксі, сумісний з OpenAI/Anthropic (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко прописати «всі моделі» в документації. Авторитетний список — це те, що `discoverModels(...)` повертає на вашій машині, плюс доступні ключі. +Порада: не намагайтеся жорстко закодувати в документації «всі моделі». Авторитетним списком є все, що повертає `discoverModels(...)` на вашій машині, плюс усі доступні ключі. ## Облікові дані (ніколи не комітьте) -Live-тести виявляють облікові дані так само, як і CLI. Практичні наслідки: +Live-тести виявляють облікові дані так само, як це робить CLI. Практичні наслідки: - Якщо CLI працює, live-тести мають знаходити ті самі ключі. -- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. +- Якщо live-тест каже «немає creds», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для кожного 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 не торкалися вашої реальної робочої області хоста. +- Auth-профілі для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означають «ключі профілів» у live-тестах) +- Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) +- Каталог legacy state: `~/.openclaw/credentials/` (копіюється в staged live home за наявності, але це не основне сховище ключів профілів) +- Локальні live-запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, legacy `credentials/` і підтримувані зовнішні каталоги auth CLI у тимчасовий test home; staged live homes пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не торкалися вашого реального host workspace. -Якщо ви хочете покладатися на ключі з env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Live Deepgram (транскрибування аудіо) +## Deepgram live (транскрибування аудіо) - Тест: `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` -## Live BytePlus coding plan +## BytePlus live для coding plan - Тест: `src/agents/byteplus.live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live медіа workflow ComfyUI +## ComfyUI live для workflow медіа - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` - - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації Plugin + - Перевіряє bundled шляхи comfy image, video і `music_generate` + - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` + - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації plugin -## Live генерація зображень +## Live для генерації image - Тест: `src/image-generation/runtime.live.test.ts` - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перелічує кожен зареєстрований Plugin провайдера генерації зображень - - Завантажує відсутні змінні середовища провайдерів із вашого login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Запускає стандартні варіанти генерації зображень через спільну runtime-можливість: + - Перелічує кожен зареєстрований plugin провайдера генерації image + - Перед probing завантажує відсутні env vars провайдерів із вашого shell входу (`~/.profile`) + - За замовчуванням використовує live/env API keys раніше, ніж збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатних auth/profile/model + - Запускає стандартні варіанти генерації image через спільну runtime-можливість: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані провайдери, які покриваються: +- Поточні bundled провайдери, що охоплюються: - `openai` - `google` - `xai` @@ -786,76 +778,76 @@ Live-тести виявляють облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,xai"` - `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 +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів та ігнорувати перевизначення лише через 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 - - Завантажує змінні середовища провайдерів із вашого login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Перевіряє спільний bundled шлях провайдера генерації музики + - Наразі охоплює Google і MiniMax + - Перед probing завантажує env vars провайдерів із вашого shell входу (`~/.profile`) + - За замовчуванням використовує live/env API keys раніше, ніж збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатних auth/profile/model - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` із введенням лише prompt + - `generate` з вхідними даними лише prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільної lane: + - Поточне покриття спільної ланки: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, а не цей спільний sweep + - `comfy`: окремий live-файл Comfy, а не ця спільна розгортка - Необов’язкове звуження: - `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 +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів та ігнорувати перевизначення лише через 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` - Обсяг: - - Перевіряє спільний вбудований шлях провайдера генерації відео - - За замовчуванням використовує безпечний для 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 - - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Перевіряє спільний bundled шлях провайдера генерації відео + - За замовчуванням використовує release-safe smoke path: провайдери без FAL, один запит text-to-video на провайдера, односекундний lobster prompt і обмеження операції на провайдера через `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` типово) + - За замовчуванням пропускає FAL, оскільки затримка черги на боці провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно + - Перед probing завантажує env vars провайдерів із вашого shell входу (`~/.profile`) + - За замовчуванням використовує live/env API keys раніше, ніж збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатних auth/profile/model - За замовчуванням запускає лише `generate` - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід зображення на основі buffer у спільному sweep - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід відео на основі buffer у спільному sweep - - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному sweep: - - `vydra`, тому що вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддаленого URL зображення - - Покриття Vydra, специфічне для провайдера: + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled`, а вибраний провайдер/модель приймає локальний вхід image на основі buffer у спільній розгортці + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled`, а вибраний провайдер/модель приймає локальний вхід video на основі buffer у спільній розгортці + - Поточні провайдери `imageToVideo`, оголошені, але пропущені у спільній розгортці: + - `vydra`, тому що bundled `veo3` підтримує лише текст, а bundled `kling` вимагає віддалений image URL + - Специфічне для провайдера покриття Vydra: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` для text-to-video, а також lane `kling`, яка за замовчуванням використовує фікстуру віддаленого URL зображення + - цей файл запускає `veo3` text-to-video плюс ланку `kling`, яка за замовчуванням використовує fixture із віддаленим image URL - Поточне live-покриття `videoToVideo`: - - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному sweep: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалених референсних URL `http(s)` / MP4 - - `google`, тому що поточна спільна lane Gemini/Veo використовує локальний вхід на основі buffer, і цей шлях не приймається у спільному sweep - - `openai`, тому що поточна спільна lane не має гарантій доступу до video inpaint/remix, специфічних для org + - лише `runway`, коли вибраною моделлю є `runway/gen4_aleph` + - Поточні провайдери `videoToVideo`, оголошені, але пропущені у спільній розгортці: + - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі вимагають віддалені reference URL `http(s)` / MP4 + - `google`, оскільки поточна спільна ланка Gemini/Veo використовує локальний вхід на основі buffer, а цей шлях не приймається у спільній розгортці + - `openai`, оскільки поточна спільна ланка не гарантує доступ до 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_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типової розгортки, включно з FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження операції для кожного провайдера під час агресивного smoke-запуску +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів та ігнорувати перевизначення лише через env ## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори для зображень, музики та відео через один нативний для репозиторію entrypoint - - Автоматично завантажує відсутні змінні середовища провайдерів із `~/.profile` - - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і тихого режиму залишається узгодженою + - Запускає спільні live-набори image, music і video через один repo-native entrypoint + - Автоматично завантажує відсутні env vars провайдерів із `~/.profile` + - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну auth + - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і quiet mode залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -864,176 +856,182 @@ Live-тести виявляють облікові дані так само, я ## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві категорії: +Ці Docker-ранери поділяються на дві групи: -- Ранери 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`, +- Live-model runners: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл ключів профілю всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та workspace (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live runners за замовчуванням мають менше обмеження smoke, щоб повна Docker-розгортка залишалася практичною: + `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` один раз збирає 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` піднімають один або більше реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. +- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ланок live. +- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-ранери live-model також bind-mount лише потрібні home каталоги автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у сховищі автентифікації хоста: +Docker-ранери live-model також bind-mount-ять лише потрібні домівки auth CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни auth-сховища хоста: -- Прямі моделі: `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`) +- 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`) - Smoke CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- Smoke harness Codex app-server: `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`) -- Майстер онбордингу (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, вимикаючи не пов’язані сценарії, наприклад: +- Wizard onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Мережева взаємодія Gateway (два контейнери, auth + health WS): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Міст каналу MCP (seeded Gateway + міст stdio + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Pi bundle MCP tools (реальний stdio MCP server + embedded smoke allow/deny профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Plugins (smoke встановлення + alias `/plugin` + semantics перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Runtime-залежності bundled plugins: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker-runner image, один раз збирає та пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть повторну збірку хоста після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Звужуйте runtime-залежності bundled plugins під час ітерацій, вимикаючи не пов’язані сценарії, наприклад: `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-model також bind-mount поточний checkout лише для читання і -розгортають його в тимчасовий workdir усередині контейнера. Це зберігає runtime-образ -компактним, але все одно запускає Vitest точно на вашому локальному source/config. -Крок розгортання пропускає великі локальні кеші та результати збірки app, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні каталоги `.build` або +Docker-ранери live-model також bind-mount-ять поточний checkout у режимі лише читання і +готує його в тимчасовий workdir усередині контейнера. Це зберігає runtime +image компактним, водночас дозволяючи запускати Vitest точно проти вашого локального source/config. +Крок підготовки пропускає великі локальні кеші та виводи збірок застосунків, такі як +`.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`, тому також передавайте +артефактів, специфічних для машини. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes gateway не запускали +реальні workers каналів Telegram/Discord тощо всередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте `OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway -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` +live-покриття з цієї Docker-ланки. +`test:docker:openwebui` — це smoke перевірка сумісності вищого рівня: вона запускає +контейнер Gateway OpenClaw з увімкненими HTTP endpoints, сумісними з OpenAI, +запускає контейнер Open WebUI із закріпленою версією проти цього gateway, виконує вхід через +Open WebUI, перевіряє, що `/api/models` відкриває `openclaw/default`, а потім надсилає +реальний chat-запит через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантажити +image Open WebUI, а Open WebUI може потребувати завершити власне холодне налаштування запуску. +Ця ланка очікує придатний live-ключ моделі, а `OPENCLAW_PROFILE_FILE` (`~/.profile` за замовчуванням) — основний спосіб надати його в Dockerized-запусках. -Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": +Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він піднімає seeded Gateway -у контейнері, запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, -поведінку черги live-подій, маршрутизацію вихідних надсилань і channel-сповіщення в стилі Claude + +реального облікового запису Telegram, Discord або iMessage. Він запускає seeded контейнер +Gateway, запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім +перевіряє виявлення conversation із маршрутизацією, читання transcript, metadata вкладень, +поведінку черги live events, маршрутизацію outbound send і channel Claude-style + сповіщення про дозволи через реальний міст stdio MCP. Перевірка сповіщень -напряму досліджує raw stdio MCP frames, тож smoke перевіряє те, що міст -справді випромінює, а не лише те, що випадково показує певний SDK клієнта. +безпосередньо перевіряє raw frames stdio MCP, тож smoke перевіряє те, що +міст справді видає, а не лише те, що випадково відкриває певний client SDK. +`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує live +ключа моделі. Він збирає Docker image репозиторію, запускає реальний probe server stdio MCP +усередині контейнера, матеріалізує цей server через embedded runtime Pi bundle +MCP, виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають +tools `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. Ручний smoke plain-language thread ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації thread ACP, тож не видаляйте його. +- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. -Корисні змінні середовища: +Корисні 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`, щоб перевіряти лише змінні середовища, використані з `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_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env vars, використані з `OPENCLAW_PROFILE_FILE`, із тимчасовими каталогами config/workspace і без зовнішніх монтувань auth CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- Зовнішні каталоги/файли auth CLI під `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів у контейнері -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані надходять зі сховища профілів (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків, які не потребують перебудови +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що creds походять зі сховища профілів (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway відкриває для smoke Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег image Open WebUI ## Перевірка документації Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки heading у межах сторінки: `pnpm docs:check-links:anchors`. +Запускайте повну перевірку якорів Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) Це регресії «реального конвеєра» без реальних провайдерів: -- Виклик інструментів 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") +- Виклик tool у Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Wizard Gateway (WS `wizard.start`/`wizard.next`, запис config + примусове застосування auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності agent (Skills) +## Оцінювання надійності агентів (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності agent»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»: -- Mock-виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- End-to-end потоки майстра, які перевіряють wiring сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Mock-виклик tool через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- End-to-end-потоки wizard, які перевіряють wiring сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). -Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Що ще відсутнє для Skills (див. [Skills](/uk/tools/skills)): -- **Вибір рішення:** коли Skills перелічені в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)? -- **Відповідність вимогам:** чи читає agent `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? -- **Контракти робочих процесів:** багатокрокові сценарії, що перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Вибір рішення:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Відповідність:** чи читає агент `SKILL.md` перед використанням і чи дотримується потрібних кроків/args? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок tools, перенесення історії сесії та межі sandbox. -Майбутні evals мають спочатку залишатися детермінованими: +Майбутні оцінювання мають насамперед залишатися детермінованими: -- Ранер сценаріїв із mock-провайдерами для перевірки викликів інструментів + порядку, читання skill-файлів і wiring сесії. -- Невеликий набір сценаріїв, зосереджених на skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live-evals (opt-in, керовані env) лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв, який використовує mock-провайдери для перевірки викликів tools + порядку, читання skill files і wiring сесії. +- Невеликий набір сценаріїв, орієнтованих на skills (використати чи уникнути, gating, prompt injection). +- Необов’язкові live-оцінювання (opt-in, із gating через env) — лише після того, як буде готовий безпечний для CI набір. -## Контрактні тести (форма Plugin і channel) +## Контрактні тести (форма plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму -контракту інтерфейсу. Вони перебирають усі виявлені Plugins і запускають набір -перевірок форми та поведінки. Типова unit-lane `pnpm test` навмисно -пропускає ці shared seam і smoke-файли; запускайте контрактні команди явно, -коли зачіпаєте спільні поверхні channel або провайдера. +Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму +контракту інтерфейсу. Вони ітерують усі виявлені plugins і запускають набір +перевірок форми та поведінки. Типова unit-ланка `pnpm test` навмисно +пропускає ці shared seam і smoke files; запускайте контрактні команди явно, +коли торкаєтеся спільних поверхонь channel або provider. ### Команди - Усі контракти: `pnpm test:contracts` - Лише контракти channel: `pnpm test:contracts:channels` -- Лише контракти провайдерів: `pnpm test:contracts:plugins` +- Лише контракти provider: `pnpm test:contracts:plugins` ### Контракти channel Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма Plugin (id, name, capabilities) -- **setup** - Контракт майстра налаштування -- **session-binding** - Поведінка прив’язки сесії +- **plugin** - Базова форма plugin (id, name, capabilities) +- **setup** - Контракт wizard налаштування +- **session-binding** - Поведінка прив’язування сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel - **threading** - Обробка ID thread -- **directory** - API directory/roster -- **group-policy** - Застосування групової політики +- **directory** - API каталогу/реєстру +- **group-policy** - Застосування політики групи -### Контракти статусу провайдера +### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки статусу channel -- **registry** - Форма реєстру Plugin +- **status** - Probes статусу channel +- **registry** - Форма реєстру plugin -### Контракти провайдерів +### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір/selection автентифікації +- **auth** - Контракт потоку auth +- **auth-choice** - Вибір/відбір auth - **catalog** - API каталогу моделей -- **discovery** - Виявлення Plugin -- **loader** - Завантаження Plugin -- **runtime** - Runtime провайдера -- **shape** - Форма/інтерфейс Plugin -- **wizard** - Майстер налаштування +- **discovery** - Виявлення plugin +- **loader** - Завантаження plugin +- **runtime** - Runtime provider +- **shape** - Форма/інтерфейс plugin +- **wizard** - Wizard налаштування ### Коли запускати -- Після зміни export або subpath у plugin-sdk -- Після додавання або зміни channel чи Plugin провайдера -- Після рефакторингу реєстрації або виявлення Plugin +- Після зміни експортів або subpaths Plugin SDK +- Після додавання або зміни plugin channel або provider +- Після рефакторингу реєстрації або виявлення plugin Контрактні тести запускаються в CI і не потребують реальних API-ключів. @@ -1041,11 +1039,11 @@ Open WebUI, перевіряє, що `/api/models` показує `openclaw/defa Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Додайте безпечну для 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, щоб нові класи не можна було тихо пропустити. +- За можливості додайте безпечну для CI регресію (mock/stub провайдера або захопіть точну трансформацію форми запиту) +- Якщо вона за своєю природою лише live (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env vars +- Віддавайте перевагу найменшому шару, який виявляє помилку: + - помилка перетворення/повторення запиту provider → direct models test + - помилка конвеєра сесії/історії/tool у gateway → gateway live smoke або безпечний для CI mock-тест gateway +- Захисна межа обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec ids сегментів обходу відхиляються. + - Якщо ви додаєте нову родину цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою на некласифікованих target ids, щоб нові класи не могли бути пропущені безшумно. diff --git a/docs/uk/plugins/bundles.md b/docs/uk/plugins/bundles.md index 540b89cce..afec8895b 100644 --- a/docs/uk/plugins/bundles.md +++ b/docs/uk/plugins/bundles.md @@ -3,33 +3,41 @@ read_when: - Ви хочете встановити пакет, сумісний із Codex, Claude або Cursor - Вам потрібно зрозуміти, як OpenClaw зіставляє вміст пакета з нативними можливостями - Ви налагоджуєте виявлення пакета або відсутні можливості -summary: Установлення та використання пакетів Codex, Claude і Cursor як плагінів OpenClaw -title: Пакети плагінів +summary: Встановлюйте та використовуйте пакети Codex, Claude і Cursor як плагіни OpenClaw +title: Набори плагінів x-i18n: - generated_at: "2026-04-05T18:11:52Z" + generated_at: "2026-04-22T23:49:19Z" model: gpt-5.4 provider: openai - source_hash: a8b1eb4633bdff75425d8c2e29be352e11a4cdad7f420c0c66ae5ef07bf9bdcc + source_hash: 91fec13cb1f807231c706318f3e81e27b350d5a0266821cb96c8494c45f01de0 source_path: plugins/bundles.md workflow: 15 --- -# Пакети плагінів +# Набори плагінів -OpenClaw може встановлювати плагіни з трьох зовнішніх екосистем: **Codex**, **Claude** і **Cursor**. Вони називаються **пакетами** — наборами вмісту та метаданих, які OpenClaw зіставляє з нативними можливостями, як-от Skills, hooks і інструменти MCP. +OpenClaw може встановлювати плагіни з трьох зовнішніх екосистем: **Codex**, **Claude** +і **Cursor**. Вони називаються **пакетами** — наборами вмісту та метаданих, які +OpenClaw зіставляє з нативними можливостями, як-от Skills, хуки та інструменти MCP. - Пакети **не** є тим самим, що й нативні плагіни OpenClaw. Нативні плагіни працюють у процесі й можуть реєструвати будь-які можливості. Пакети є наборами вмісту з вибірковим зіставленням можливостей і вужчою межею довіри. + Пакети **не** є тим самим, що й нативні плагіни OpenClaw. Нативні плагіни працюють + у межах процесу та можуть реєструвати будь-яку можливість. Пакети — це набори + вмісту з вибірковим зіставленням можливостей і вужчою межею довіри. ## Навіщо існують пакети -Багато корисних плагінів публікуються у форматах Codex, Claude або Cursor. Замість того щоб змушувати авторів переписувати їх як нативні плагіни OpenClaw, OpenClaw виявляє ці формати й зіставляє підтримуваний у них вміст із нативним набором можливостей. Це означає, що ви можете встановити набір команд Claude або пакет Skills Codex і відразу почати ним користуватися. +Багато корисних плагінів публікуються у форматі Codex, Claude або Cursor. Замість +того щоб змушувати авторів переписувати їх як нативні плагіни OpenClaw, OpenClaw +виявляє ці формати та зіставляє підтримуваний у них вміст із нативним набором +можливостей. Це означає, що ви можете встановити пакет команд Claude або пакет +Skills для Codex і одразу почати ним користуватися. -## Установлення пакета +## Встановлення пакета - + ```bash # Локальний каталог openclaw plugins install ./my-bundle @@ -37,14 +45,14 @@ OpenClaw може встановлювати плагіни з трьох зов # Архів openclaw plugins install ./my-bundle.tgz - # Marketplace Claude + # Claude marketplace openclaw plugins marketplace list openclaw plugins install @ ``` - + ```bash openclaw plugins list openclaw plugins inspect @@ -54,52 +62,62 @@ OpenClaw може встановлювати плагіни з трьох зов - + ```bash openclaw gateway restart ``` - Зіставлені можливості (Skills, hooks, інструменти MCP, типові значення LSP) будуть доступні в наступному сеансі. + Зіставлені можливості (Skills, хуки, інструменти MCP, типові налаштування LSP) будуть доступні в наступному сеансі. ## Що OpenClaw зіставляє з пакетів -Не всі можливості пакетів сьогодні виконуються в OpenClaw. Нижче наведено, що працює, а що виявляється, але ще не підключене. +Сьогодні в OpenClaw працюють не всі можливості пакетів. Нижче наведено, що +працює, а що виявляється, але ще не підключене. ### Підтримується зараз -| Можливість | Як зіставляється | Застосовується до | -| ------------- | ------------------------------------------------------------------------------------------- | -------------- | -| Вміст Skills | Корені Skills пакетів завантажуються як звичайні Skills OpenClaw | Усі формати | -| Команди | `commands/` і `.cursor/commands/` обробляються як корені Skills | Claude, Cursor | -| Пакети hooks | Макети в стилі OpenClaw `HOOK.md` + `handler.ts` | Codex | -| Інструменти MCP | Конфігурація MCP пакета об’єднується з вбудованими налаштуваннями Pi; завантажуються підтримувані сервери stdio і HTTP | Усі формати | -| Сервери LSP | Claude `.lsp.json` і оголошені в маніфесті `lspServers` об’єднуються з типовими значеннями LSP вбудованого Pi | Claude | -| Налаштування | Claude `settings.json` імпортується як типові значення вбудованого Pi | Claude | +| Можливість | Як зіставляється | Застосовується до | +| ------------- | ------------------------------------------------------------------------------------------ | ----------------- | +| Вміст Skills | Кореневі каталоги Skills пакета завантажуються як звичайні Skills OpenClaw | Усі формати | +| Команди | `commands/` і `.cursor/commands/` обробляються як кореневі каталоги Skills | Claude, Cursor | +| Пакети хуків | Макети у стилі OpenClaw з `HOOK.md` + `handler.ts` | Codex | +| Інструменти MCP | Конфігурація MCP пакета об’єднується з вбудованими налаштуваннями Pi; підтримувані сервери stdio та HTTP завантажуються | Усі формати | +| Сервери LSP | Claude `.lsp.json` і оголошені в маніфесті `lspServers` об’єднуються з типовими налаштуваннями LSP вбудованого Pi | Claude | +| Налаштування | Claude `settings.json` імпортується як типові налаштування вбудованого Pi | Claude | #### Вміст Skills -- корені Skills пакетів завантажуються як звичайні корені Skills OpenClaw -- корені Claude `commands` обробляються як додаткові корені Skills -- корені Cursor `.cursor/commands` обробляються як додаткові корені Skills +- кореневі каталоги Skills пакета завантажуються як звичайні кореневі каталоги Skills OpenClaw +- корені Claude `commands` обробляються як додаткові кореневі каталоги Skills +- корені Cursor `.cursor/commands` обробляються як додаткові кореневі каталоги Skills -Це означає, що markdown-файли команд Claude працюють через звичайний завантажувач Skills OpenClaw. Markdown-команди Cursor працюють через той самий шлях. +Це означає, що markdown-файли команд Claude працюють через звичайний завантажувач +Skills в OpenClaw. Markdown-команди Cursor працюють через той самий шлях. -#### Пакети hooks +#### Пакети хуків -- корені hooks пакета працюють **лише** тоді, коли вони використовують звичайний макет пакета hooks OpenClaw. Сьогодні це переважно випадок сумісності з Codex: +- кореневі каталоги хуків пакета працюють **лише** тоді, коли вони використовують + звичайний макет пакета хуків OpenClaw. Сьогодні це переважно випадок сумісності з Codex: - `HOOK.md` - `handler.ts` або `handler.js` #### MCP для Pi - увімкнені пакети можуть додавати конфігурацію сервера MCP -- OpenClaw об’єднує конфігурацію MCP пакета в ефективні вбудовані налаштування Pi як `mcpServers` -- OpenClaw надає підтримувані інструменти MCP пакета під час ходів агента вбудованого Pi, запускаючи сервери stdio або підключаючись до HTTP-серверів -- локальні для проєкту налаштування Pi застосовуються після типових значень пакета, тому налаштування робочого простору можуть за потреби перевизначати записи MCP пакета -- каталоги інструментів MCP пакета сортуються детерміновано перед реєстрацією, щоб зміни у порядку `listTools()` на рівні джерела не розхитували блоки інструментів у prompt-cache +- OpenClaw об’єднує конфігурацію MCP пакета з ефективними вбудованими налаштуваннями Pi як + `mcpServers` +- OpenClaw показує підтримувані інструменти MCP пакета під час ходів агента вбудованого Pi, + запускаючи сервери stdio або підключаючись до HTTP-серверів +- профілі інструментів `coding` і `messaging` типово включають інструменти MCP пакета; + використовуйте `tools.deny: ["bundle-mcp"]`, щоб вимкнути їх для агента або Gateway +- локальні налаштування Pi для проєкту все одно застосовуються після типових налаштувань пакета, + тож за потреби налаштування робочого простору можуть перевизначати записи MCP пакета +- каталоги інструментів MCP пакета сортуються детерміновано перед реєстрацією, щоб + зміни у вихідному порядку `listTools()` не спричиняли нестабільність блоків + інструментів prompt-cache ##### Транспорти @@ -121,7 +139,7 @@ OpenClaw може встановлювати плагіни з трьох зов } ``` -**HTTP** підключається до запущеного MCP-сервера через `sse` типово або через `streamable-http`, якщо це запитано: +**HTTP** підключається до вже запущеного сервера MCP через `sse` типово або через `streamable-http`, якщо це запитано: ```json { @@ -140,27 +158,36 @@ OpenClaw може встановлювати плагіни з трьох зов } ``` -- `transport` можна встановити як `"streamable-http"` або `"sse"`; якщо не вказано, OpenClaw використовує `sse` -- дозволено лише схеми URL `http:` і `https:` -- значення `headers` підтримують інтерполяцію `${ENV_VAR}` -- запис сервера, який містить і `command`, і `url`, відхиляється -- облікові дані URL (userinfo і параметри запиту) редагуються в описах інструментів і журналах -- `connectionTimeoutMs` перевизначає типове 30-секундне обмеження часу підключення як для транспорту stdio, так і для HTTP +- `transport` можна встановити в `"streamable-http"` або `"sse"`; якщо його пропущено, OpenClaw використовує `sse` +- дозволені лише схеми URL `http:` і `https:` +- значення `headers` підтримують підстановку `${ENV_VAR}` +- запис сервера, що містить одночасно `command` і `url`, відхиляється +- облікові дані URL (userinfo і параметри запиту) редагуються в описах інструментів + і журналах +- `connectionTimeoutMs` перевизначає типовий 30-секундний тайм-аут підключення + як для транспортів stdio, так і для HTTP ##### Іменування інструментів -OpenClaw реєструє інструменти MCP пакета з безпечними для провайдера іменами у форматі `serverName__toolName`. Наприклад, сервер із ключем `"vigil-harbor"`, який надає інструмент `memory_search`, реєструється як `vigil-harbor__memory_search`. +OpenClaw реєструє інструменти MCP пакета з безпечними для провайдерів іменами у форматі +`serverName__toolName`. Наприклад, сервер із ключем `"vigil-harbor"`, який надає +інструмент `memory_search`, реєструється як `vigil-harbor__memory_search`. - символи поза межами `A-Za-z0-9_-` замінюються на `-` - префікси серверів обмежуються 30 символами - повні назви інструментів обмежуються 64 символами - порожні назви серверів замінюються на `mcp` - конфліктні санітизовані назви розрізняються числовими суфіксами -- остаточний порядок видимих інструментів є детермінованим за безпечною назвою, щоб повторні ходи Pi залишалися стабільними для кешу +- остаточний порядок видимих інструментів є детермінованим за безпечною назвою, щоб + повторні ходи Pi залишалися стабільними для кешу +- фільтрація профілю розглядає всі інструменти з одного MCP-сервера пакета як такі, + що належать плагіну `bundle-mcp`, тому списки дозволів і заборон профілю можуть + містити або окремі видимі назви інструментів, або ключ плагіна `bundle-mcp` -#### Вбудовані налаштування Pi +#### Налаштування вбудованого Pi -- Claude `settings.json` імпортується як типові вбудовані налаштування Pi, коли пакет увімкнено +- Claude `settings.json` імпортується як типові налаштування вбудованого Pi, коли + пакет увімкнено - OpenClaw санітизує ключі перевизначення оболонки перед застосуванням Санітизовані ключі: @@ -168,20 +195,21 @@ OpenClaw реєструє інструменти MCP пакета з безпе - `shellPath` - `shellCommandPrefix` -#### Вбудований LSP Pi +#### Вбудований Pi LSP - увімкнені пакети Claude можуть додавати конфігурацію сервера LSP - OpenClaw завантажує `.lsp.json`, а також будь-які шляхи `lspServers`, оголошені в маніфесті -- конфігурація LSP пакета об’єднується з ефективними типовими значеннями LSP вбудованого Pi -- сьогодні можна запускати лише підтримувані LSP-сервери на основі stdio; непідтримувані транспорти все одно відображаються в `openclaw plugins inspect ` +- конфігурація LSP пакета об’єднується з ефективними типовими налаштуваннями LSP вбудованого Pi +- сьогодні можна запускати лише підтримувані LSP-сервери на основі stdio; непідтримувані + транспорти все одно відображаються в `openclaw plugins inspect ` ### Виявляється, але не виконується -Ці можливості розпізнаються і показуються в діагностиці, але OpenClaw їх не виконує: +Ці можливості розпізнаються та показуються в діагностиці, але OpenClaw їх не запускає: - Claude `agents`, автоматизація `hooks.json`, `outputStyles` - Cursor `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules` -- Вбудовані/застосункові метадані Codex поза межами звітування про можливості +- вбудовані/застосункові метадані Codex поза межами звітності про можливості ## Формати пакетів @@ -191,7 +219,8 @@ OpenClaw реєструє інструменти MCP пакета з безпе Необов’язковий вміст: `skills/`, `hooks/`, `.mcp.json`, `.app.json` - Пакети Codex найкраще підходять для OpenClaw, коли вони використовують корені Skills і каталоги пакетів hooks у стилі OpenClaw (`HOOK.md` + `handler.ts`). + Пакети Codex найкраще підходять для OpenClaw, коли використовують кореневі каталоги Skills + та каталоги пакетів хуків у стилі OpenClaw (`HOOK.md` + `handler.ts`). @@ -204,11 +233,11 @@ OpenClaw реєструє інструменти MCP пакета з безпе Специфічна поведінка Claude: - `commands/` обробляється як вміст Skills - - `settings.json` імпортується у вбудовані налаштування Pi (ключі перевизначення оболонки санітизуються) - - `.mcp.json` надає підтримувані інструменти stdio для вбудованого Pi - - `.lsp.json` разом із шляхами `lspServers`, оголошеними в маніфесті, завантажуються у типові значення LSP вбудованого Pi + - `settings.json` імпортується в налаштування вбудованого Pi (ключі перевизначення оболонки санітизуються) + - `.mcp.json` показує підтримувані інструменти stdio для вбудованого Pi + - `.lsp.json` разом із шляхами `lspServers`, оголошеними в маніфесті, завантажується до типових налаштувань LSP вбудованого Pi - `hooks/hooks.json` виявляється, але не виконується - - користувацькі шляхи компонентів у маніфесті є адитивними (вони розширюють типові значення, а не замінюють їх) + - спеціальні шляхи компонентів у маніфесті є адитивними (вони розширюють типові значення, а не замінюють їх) @@ -225,46 +254,52 @@ OpenClaw реєструє інструменти MCP пакета з безпе ## Пріоритет виявлення -OpenClaw спочатку перевіряє нативний формат плагіна: +OpenClaw спочатку перевіряє формат нативного плагіна: -1. `openclaw.plugin.json` або коректний `package.json` з `openclaw.extensions` — обробляється як **нативний плагін** +1. `openclaw.plugin.json` або дійсний `package.json` з `openclaw.extensions` — обробляється як **нативний плагін** 2. Маркери пакетів (`.codex-plugin/`, `.claude-plugin/` або типовий макет Claude/Cursor) — обробляються як **пакет** -Якщо каталог містить обидва варіанти, OpenClaw використовує нативний шлях. Це запобігає частковому встановленню пакетів із подвійним форматом як пакетів. +Якщо каталог містить обидва варіанти, OpenClaw використовує нативний шлях. Це запобігає +частковому встановленню пакетів подвійного формату як пакетів. ## Безпека Пакети мають вужчу межу довіри, ніж нативні плагіни: -- OpenClaw **не** завантажує довільні runtime-модулі пакета в процес -- шляхи Skills і пакетів hooks мають залишатися в межах кореня плагіна (перевірка меж) -- файли налаштувань читаються з тими самими перевірками меж -- підтримувані сервери stdio MCP можуть запускатися як підпроцеси +- OpenClaw **не** завантажує довільні runtime-модулі пакета у межах процесу +- шляхи Skills і пакетів хуків мають залишатися всередині кореня плагіна (із перевіркою меж) +- файли налаштувань читаються з тією самою перевіркою меж +- підтримувані сервери MCP на stdio можуть запускатися як підпроцеси -Це робить пакети безпечнішими типово, але вам усе одно слід вважати сторонні пакети довіреним вмістом для тих можливостей, які вони все ж надають. +Це робить пакети безпечнішими типово, але вам усе одно слід вважати сторонні +пакети довіреним вмістом для тих можливостей, які вони все ж надають. -## Усунення неполадок +## Усунення несправностей - Виконайте `openclaw plugins inspect `. Якщо можливість указано, але позначено як не підключену, це обмеження продукту, а не зламана інсталяція. + Виконайте `openclaw plugins inspect `. Якщо можливість перелічено, але позначено як + не підключену, це обмеження продукту, а не проблема встановлення. - Переконайтеся, що пакет увімкнено, а markdown-файли розташовані всередині виявленого кореня `commands/` або `skills/`. + Переконайтеся, що пакет увімкнено, а markdown-файли розташовані всередині + виявленого кореня `commands/` або `skills/`. - Підтримуються лише вбудовані налаштування Pi з `settings.json`. OpenClaw не обробляє налаштування пакета як необроблені патчі конфігурації. + Підтримуються лише налаштування вбудованого Pi із `settings.json`. OpenClaw + не розглядає налаштування пакета як сирі патчі конфігурації. - - `hooks/hooks.json` лише виявляється. Якщо вам потрібні hooks, які можна виконувати, використовуйте макет пакета hooks OpenClaw або постачайте нативний плагін. + + `hooks/hooks.json` лише виявляється. Якщо вам потрібні виконувані хуки, використовуйте + макет пакета хуків OpenClaw або постачайте нативний плагін. ## Пов’язане -- [Установлення та налаштування плагінів](/tools/plugin) -- [Створення плагінів](/plugins/building-plugins) — створення нативного плагіна -- [Маніфест плагіна](/plugins/manifest) — схема нативного маніфесту +- [Встановлення та налаштування плагінів](/uk/tools/plugin) +- [Створення плагінів](/uk/plugins/building-plugins) — створіть нативний плагін +- [Маніфест плагіна](/uk/plugins/manifest) — схема нативного маніфесту diff --git a/docs/uk/tools/index.md b/docs/uk/tools/index.md index 8ec011be7..9ff2eb1d7 100644 --- a/docs/uk/tools/index.md +++ b/docs/uk/tools/index.md @@ -2,25 +2,25 @@ read_when: - Ви хочете зрозуміти, які інструменти надає OpenClaw - Вам потрібно налаштувати, дозволити або заборонити інструменти - - 'Ви вирішуєте, що обрати: вбудовані інструменти, Skills чи плагіни' -summary: 'Огляд інструментів і плагінів OpenClaw: що може робити агент і як його розширювати' -title: Інструменти та плагіни + - Ви обираєте між вбудованими інструментами, Skills і plugin-ами +summary: 'Огляд інструментів і plugin-ів OpenClaw: що може робити агент і як його розширити' +title: Інструменти та plugin-и x-i18n: - generated_at: "2026-04-22T07:16:19Z" + generated_at: "2026-04-22T23:49:17Z" model: gpt-5.4 provider: openai - source_hash: 6edb9e13b72e6345554f25c8d8413d167a69501e6626828d9aa3aac6907cd092 + source_hash: 1c32414dfa99969372e9b0c846305a1af1ffb18a282e6dfc8a6adabe3fab145a source_path: tools/index.md workflow: 15 --- -# Інструменти та плагіни +# Інструменти та plugin-и -Усе, що агент робить понад генерування тексту, відбувається через **інструменти**. +Усе, що агент робить понад генерацію тексту, відбувається через **інструменти**. Інструменти — це спосіб, у який агент читає файли, запускає команди, переглядає вебсторінки, надсилає повідомлення та взаємодіє з пристроями. -## Інструменти, Skills і плагіни +## Інструменти, Skills і plugin-и OpenClaw має три рівні, які працюють разом: @@ -28,99 +28,99 @@ OpenClaw має три рівні, які працюють разом: Інструмент — це типізована функція, яку агент може викликати (наприклад, `exec`, `browser`, `web_search`, `message`). OpenClaw постачається з набором **вбудованих інструментів**, а - плагіни можуть реєструвати додаткові. + plugin-и можуть реєструвати додаткові. Агент бачить інструменти як структуровані визначення функцій, надіслані до API моделі. - Skill — це markdown-файл (`SKILL.md`), який вбудовується в системний промпт. + Skill — це markdown-файл (`SKILL.md`), який вбудовується в системний prompt. Skills надають агенту контекст, обмеження та покрокові вказівки для - ефективного використання інструментів. Skills знаходяться у вашому робочому просторі, у спільних теках - або постачаються всередині плагінів. + ефективного використання інструментів. Skills зберігаються у вашому робочому просторі, у спільних теках + або постачаються всередині plugin-ів. - [Довідник Skills](/uk/tools/skills) | [Створення Skills](/uk/tools/creating-skills) + [Довідник зі Skills](/uk/tools/skills) | [Створення Skills](/uk/tools/creating-skills) - - Плагін — це пакет, який може реєструвати будь-яку комбінацію можливостей: - канали, провайдери моделей, інструменти, Skills, мовлення, транскрибування в реальному часі, + + Plugin — це пакет, який може реєструвати будь-яку комбінацію можливостей: + канали, провайдери моделей, інструменти, Skills, мовлення, транскрипцію в реальному часі, голос у реальному часі, розуміння медіа, генерацію зображень, генерацію відео, - отримання вебконтенту, вебпошук тощо. Деякі плагіни є **core** (постачаються з + отримання даних з вебу, вебпошук тощо. Деякі plugin-и є **core** (постачаються з OpenClaw), інші — **external** (опубліковані спільнотою в npm). - [Установлення та налаштування плагінів](/uk/tools/plugin) | [Створіть власний](/uk/plugins/building-plugins) + [Установлення й налаштування plugin-ів](/uk/tools/plugin) | [Створіть власний](/uk/plugins/building-plugins) ## Вбудовані інструменти -Ці інструменти постачаються з OpenClaw і доступні без установлення будь-яких плагінів: +Ці інструменти постачаються з OpenClaw і доступні без встановлення будь-яких plugin-ів: -| Інструмент | Що він робить | Сторінка | -| ------------------------------------------ | -------------------------------------------------------------------- | ------------------------------------------- | -| `exec` / `process` | Запускає команди оболонки, керує фоновими процесами | [Exec](/uk/tools/exec) | -| `code_execution` | Запускає ізольований віддалений аналіз Python | [Code Execution](/uk/tools/code-execution) | -| `browser` | Керує браузером Chromium (перехід, натискання, знімок екрана) | [Browser](/uk/tools/browser) | -| `web_search` / `x_search` / `web_fetch` | Шукає у вебі, шукає дописи в X, отримує вміст сторінок | [Web](/uk/tools/web) | -| `read` / `write` / `edit` | Операції введення/виведення файлів у робочому просторі | | -| `apply_patch` | Багатофрагментні латки файлів | [Apply Patch](/uk/tools/apply-patch) | -| `message` | Надсилає повідомлення через усі канали | [Agent Send](/uk/tools/agent-send) | -| `canvas` | Керує node Canvas (present, eval, snapshot) | | -| `nodes` | Виявляє та вибирає спарені пристрої | | -| `cron` / `gateway` | Керує запланованими завданнями; переглядає, латає, перезапускає або оновлює Gateway | | -| `image` / `image_generate` | Аналізує або генерує зображення | [Image Generation](/uk/tools/image-generation) | -| `music_generate` | Генерує музичні треки | [Music Generation](/uk/tools/music-generation) | -| `video_generate` | Генерує відео | [Video Generation](/uk/tools/video-generation) | -| `tts` | Одноразове перетворення тексту на мовлення | [TTS](/uk/tools/tts) | -| `sessions_*` / `subagents` / `agents_list` | Керування сесіями, статусом і оркестрацією субагентів | [Sub-agents](/uk/tools/subagents) | -| `session_status` | Полегшене зчитування в стилі `/status` та перевизначення моделі для сесії | [Session Tools](/uk/concepts/session-tool) | +| Інструмент | Що він робить | Сторінка | +| ----------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------- | +| `exec` / `process` | Запускає shell-команди, керує фоновими процесами | [Exec](/uk/tools/exec) | +| `code_execution` | Запускає ізольований віддалений Python-аналіз | [Code Execution](/uk/tools/code-execution) | +| `browser` | Керує браузером Chromium (перехід, натискання, знімок екрана) | [Browser](/uk/tools/browser) | +| `web_search` / `x_search` / `web_fetch` | Шукає у вебі, шукає дописи в X, отримує вміст сторінок | [Веб](/uk/tools/web) | +| `read` / `write` / `edit` | Введення/виведення файлів у робочому просторі | | +| `apply_patch` | Багатофрагментні файлові патчі | [Apply Patch](/uk/tools/apply-patch) | +| `message` | Надсилає повідомлення через усі канали | [Надсилання агентом](/uk/tools/agent-send) | +| `canvas` | Керує node Canvas (present, eval, snapshot) | | +| `nodes` | Виявляє спарені пристрої та працює з ними | | +| `cron` / `gateway` | Керує запланованими завданнями; перевіряє, патчить, перезапускає або оновлює gateway | | +| `image` / `image_generate` | Аналізує або генерує зображення | [Генерація зображень](/uk/tools/image-generation) | +| `music_generate` | Генерує музичні доріжки | [Генерація музики](/uk/tools/music-generation) | +| `video_generate` | Генерує відео | [Генерація відео](/uk/tools/video-generation) | +| `tts` | Одноразове перетворення тексту на мовлення | [TTS](/uk/tools/tts) | +| `sessions_*` / `subagents` / `agents_list` | Керування сесіями, статус і оркестрація субагентів | [Субагенти](/uk/tools/subagents) | +| `session_status` | Легке зчитування у стилі `/status` і перевизначення моделі для сесії | [Інструменти сесії](/uk/concepts/session-tool) | Для роботи із зображеннями використовуйте `image` для аналізу та `image_generate` для генерації або редагування. Якщо ви націлюєтеся на `openai/*`, `google/*`, `fal/*` або іншого нестандартного провайдера зображень, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. Для роботи з музикою використовуйте `music_generate`. Якщо ви націлюєтеся на `google/*`, `minimax/*` або іншого нестандартного музичного провайдера, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. -Для роботи з відео використовуйте `video_generate`. Якщо ви націлюєтеся на `qwen/*` або іншого нестандартного відеопровайдера, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. +Для роботи з відео використовуйте `video_generate`. Якщо ви націлюєтеся на `qwen/*` або іншого нестандартного провайдера відео, спочатку налаштуйте автентифікацію/API-ключ цього провайдера. -Для генерації аудіо на основі робочих процесів використовуйте `music_generate`, коли його реєструє -плагін, такий як ComfyUI. Це окремо від `tts`, який є перетворенням тексту на мовлення. +Для генерації аудіо на основі workflow використовуйте `music_generate`, коли plugin, наприклад +ComfyUI, реєструє його. Це окремо від `tts`, який є перетворенням тексту на мовлення. -`session_status` — це полегшений інструмент статусу/зчитування в групі сесій. -Він відповідає на запитання в стилі `/status` про поточну сесію та може -за потреби встановлювати перевизначення моделі для окремої сесії; `model=default` очищає це -перевизначення. Як і `/status`, він може дозаповнювати відсутні лічильники токенів/кешу та -мітку активної моделі середовища виконання з останнього запису використання в транскрипті. +`session_status` — це легкий інструмент статусу/зчитування в групі sessions. +Він відповідає на запитання у стилі `/status` про поточну сесію та може +за потреби встановити перевизначення моделі для окремої сесії; `model=default` скидає це +перевизначення. Як і `/status`, він може дозаповнювати розріджені лічильники токенів/кешу та +мітку активної runtime-моделі з останнього запису використання в транскрипті. -`gateway` — це інструмент середовища виконання лише для власника для операцій Gateway: +`gateway` — це owner-only runtime-інструмент для операцій gateway: -- `config.schema.lookup` для одного піддерева конфігурації з обмеженням шляхом перед редагуванням -- `config.get` для поточного знімка конфігурації + гешу +- `config.schema.lookup` для одного піддерева конфігурації, обмеженого шляхом, перед редагуванням +- `config.get` для поточного знімка конфігурації + хешу - `config.patch` для часткових оновлень конфігурації з перезапуском - `config.apply` лише для повної заміни конфігурації -- `update.run` для явного самооновлення + перезапуску +- `update.run` для явного самостійного оновлення + перезапуску Для часткових змін надавайте перевагу `config.schema.lookup`, а потім `config.patch`. Використовуйте -`config.apply` лише тоді, коли ви навмисно замінюєте всю конфігурацію. +`config.apply` лише тоді, коли ви свідомо замінюєте всю конфігурацію. Інструмент також відмовляється змінювати `tools.exec.ask` або `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec. -### Інструменти, надані плагінами +### Інструменти, надані plugin-ами -Плагіни можуть реєструвати додаткові інструменти. Деякі приклади: +Plugin-и можуть реєструвати додаткові інструменти. Деякі приклади: -- [Diffs](/uk/tools/diffs) — переглядач і рендерер diff +- [Diffs](/uk/tools/diffs) — переглядач і засіб рендерингу diff - [LLM Task](/uk/tools/llm-task) — крок LLM лише з JSON для структурованого виводу -- [Lobster](/uk/tools/lobster) — типізоване середовище виконання робочих процесів із відновлюваними погодженнями -- [Music Generation](/uk/tools/music-generation) — спільний інструмент `music_generate` із провайдерами на основі робочих процесів -- [OpenProse](/uk/prose) — оркестрація робочих процесів у стилі markdown -- [Tokenjuice](/uk/tools/tokenjuice) — стискає шумні результати інструментів `exec` і `bash` +- [Lobster](/uk/tools/lobster) — типізоване workflow-середовище виконання з відновлюваними погодженнями +- [Music Generation](/uk/tools/music-generation) — спільний інструмент `music_generate` з провайдерами на основі workflow +- [OpenProse](/uk/prose) — оркестрація workflow з пріоритетом markdown +- [Tokenjuice](/uk/tools/tokenjuice) — компактні результати інструментів `exec` і `bash` з шумним виводом ## Налаштування інструментів -### Списки дозволу та заборони +### Списки дозволів і заборон Керуйте тим, які інструменти агент може викликати, через `tools.allow` / `tools.deny` у конфігурації. Заборона завжди має пріоритет над дозволом. @@ -136,48 +136,53 @@ OpenClaw має три рівні, які працюють разом: ### Профілі інструментів -`tools.profile` задає базовий список дозволів перед застосуванням `allow`/`deny`. +`tools.profile` встановлює базовий список дозволів перед застосуванням `allow`/`deny`. Перевизначення для окремого агента: `agents.list[].tools.profile`. -| Профіль | Що він містить | -| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| `full` | Без обмежень (те саме, що не задано) | -| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` | +| Профіль | Що він включає | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `full` | Без обмежень (те саме, що не встановлено) | +| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `minimal` | Лише `session_status` | +| `minimal` | Лише `session_status` | + +Профілі `coding` і `messaging` також дозволяють налаштовані bundle MCP-інструменти +під ключем plugin-а `bundle-mcp`. Додайте `tools.deny: ["bundle-mcp"]`, якщо ви +хочете, щоб профіль зберіг свої звичайні вбудовані інструменти, але приховав усі налаштовані MCP-інструменти. +Профіль `minimal` не включає bundle MCP-інструменти. ### Групи інструментів -Використовуйте скорочення `group:*` у списках дозволу/заборони: +Використовуйте скорочення `group:*` у списках дозволів/заборон: -| Група | Інструменти | -| ------------------ | --------------------------------------------------------------------------------------------------------- | +| Група | Інструменти | +| ------------------ | -------------------------------------------------------------------------------------------------------- | | `group:runtime` | exec, process, code_execution (`bash` приймається як псевдонім для `exec`) | -| `group:fs` | read, write, edit, apply_patch | +| `group:fs` | read, write, edit, apply_patch | | `group:sessions` | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status | -| `group:memory` | memory_search, memory_get | -| `group:web` | web_search, x_search, web_fetch | -| `group:ui` | browser, canvas | -| `group:automation` | cron, gateway | -| `group:messaging` | message | -| `group:nodes` | nodes | -| `group:agents` | agents_list | -| `group:media` | image, image_generate, music_generate, video_generate, tts | -| `group:openclaw` | Усі вбудовані інструменти OpenClaw (без інструментів плагінів) | +| `group:memory` | memory_search, memory_get | +| `group:web` | web_search, x_search, web_fetch | +| `group:ui` | browser, canvas | +| `group:automation` | cron, gateway | +| `group:messaging` | message | +| `group:nodes` | nodes | +| `group:agents` | agents_list | +| `group:media` | image, image_generate, music_generate, video_generate, tts | +| `group:openclaw` | Усі вбудовані інструменти OpenClaw (не включає інструменти plugin-ів) | -`sessions_history` повертає обмежене, відфільтроване з погляду безпеки подання для згадування. Воно видаляє -теги thinking, каркас ``, XML-корисні навантаження викликів інструментів у звичайному тексті -(зокрема `...`, +`sessions_history` повертає обмежений, відфільтрований з погляду безпеки вигляд для пригадування. Він видаляє +теги thinking, каркас ``, XML-корисне навантаження викликів інструментів у звичайному тексті +(включно з `...`, `...`, `...`, -`...` і обрізані блоки викликів інструментів), -каркас викликів інструментів після деградації, витоки ASCII/повноширинних токенів керування -моделлю та некоректний XML викликів інструментів MiniMax з тексту асистента, а потім застосовує -редагування/усікання та, за потреби, заповнювачі для надто великих рядків замість того, щоб діяти -як сирий дамп транскрипту. +`...` і обрізаними блоками викликів інструментів), +понижений до звичайного тексту каркас викликів інструментів, витіклі ASCII/full-width токени +керування моделлю та некоректний XML викликів інструментів MiniMax з тексту асистента, а потім застосовує +редагування/обрізання та, за потреби, заповнювачі надто великих рядків замість того, щоб діяти +як необроблений дамп транскрипту. ### Обмеження для конкретних провайдерів -Використовуйте `tools.byProvider`, щоб обмежувати інструменти для конкретних провайдерів без +Використовуйте `tools.byProvider`, щоб обмежувати інструменти для певних провайдерів без зміни глобальних значень за замовчуванням: ```json5