From b048d924fa14f960721f7ad36c7dcfdf8a0d8395 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 14 Apr 2026 20:35:33 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/help/testing.md | 868 ++++++++++++++++++------------------ docs/uk/plugins/manifest.md | 487 ++++++++++---------- 2 files changed, 699 insertions(+), 656 deletions(-) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index c9bdf1b15..d0627cca7 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,41 +1,41 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для багів моделей/провайдерів - - Налагодження поведінки Gateway + агентів -summary: 'Набір тестування: unit/e2e/live набори, Docker-запускачі та що охоплює кожен тест' + - Додавання регресій для помилок моделі/провайдера + - Налагодження поведінки Gateway + агента +summary: 'Набір для тестування: модульні/e2e/live набори, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-14T14:00:54Z" + generated_at: "2026-04-14T20:31:18Z" model: gpt-5.4 provider: openai - source_hash: ba64fd19580b8064078fcf885a2c7d99db70fc03de6d59c64cdcc31ab8ea4c43 + source_hash: 5efa95e37c3c4b8d4ff979b42981fb238dd8441b747d38a81c66d77050d78337 source_path: help/testing.md workflow: 15 --- # Тестування -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-запускачів. +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ — це посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює) -- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) +- Які команди запускати для поширених сценаріїв роботи (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресійні тести для реальних проблем із моделями/провайдерами +- Як додавати регресії для реальних проблем моделей/провайдерів ## Швидкий старт У більшості випадків: - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm test` -- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` +- Швидший локальний запуск повного набору на продуктивній машині: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` -- Пряме націлювання на файл тепер також маршрутизує шляхи extensions/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Якщо ви ітеруєте над однією помилкою, спочатку віддавайте перевагу цільовим запускам. +- Пряме націлення на файл тепер також маршрутизує шляхи 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` +- QA-лінія на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` Коли ви змінюєте тести або хочете більше впевненості: @@ -44,62 +44,66 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + gateway tool/image probes): `pnpm test:live` -- Тихо націлити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Live-набір (моделі + gateway-проби інструментів/зображень): `pnpm test:live` +- Тихо запустити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Порада: якщо вам потрібен лише один проблемний кейс, віддавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. +Порада: коли вам потрібен лише один збійний випадок, краще звузити live-тести через env-змінні allowlist, описані нижче. -## QA-специфічні запускаючі засоби +## Спеціалізовані QA-ранери -Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм qa-lab: +Ці команди розташовані поряд з основними тестовими наборами, коли вам потрібен реалізм QA-lab: - `pnpm openclaw qa suite` - - Запускає QA-сценарії на основі репозиторію безпосередньо на хості. - - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими gateway workers, до 64 workers або кількості вибраних сценаріїв. Використовуйте `--concurrency ` для налаштування кількості workers, або `--concurrency 1` для старішого послідовного каналу. + - Запускає QA-сценарії з репозиторію безпосередньо на хості. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими worker-процесами gateway, до 64 воркерів або кількості вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати кількість воркерів, або `--concurrency 1` для старішої послідовної лінії. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. + - Запускає той самий QA-набір у тимчасовій Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапори вибору провайдера/моделі, що й `qa suite`. - - Live-запуски перенаправляють підтримувані вхідні дані автентифікації QA, які практично використовувати для guest: - env-ключі провайдерів, шлях до конфігурації live-провайдера QA та `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через змонтований workspace. - - Записує звичайний QA-звіт + підсумок, а також логи Multipass у `.artifacts/qa-e2e/...`. + - Live-запуски передають підтримувані вхідні дані QA-автентифікації, які практичні для гостьової системи: + ключі провайдерів через env, шлях до конфігурації QA live-провайдера та `CODEX_HOME`, якщо він присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через змонтований workspace. + - Записує звичайний QA-звіт і summary, а також логи Multipass у + `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для операторської QA-роботи. + - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. - `pnpm openclaw qa matrix` - - Запускає Matrix live QA-канал проти тимчасового homeserver Tuwunel на базі Docker. - - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, потім запускає дочірній процес QA gateway із реальним Matrix Plugin як транспортом SUT. - - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. - - Matrix наразі підтримує лише `--credential-source env`, оскільки канал створює тимчасових користувачів локально. - - Записує Matrix QA-звіт, підсумок і observed-events artifact у `.artifacts/qa-e2e/...`. + - Запускає Matrix live QA-лінію на основі тимчасового homeserver Tuwunel у Docker. + - Цей QA-хост наразі призначений лише для репозиторію/розробки. Упаковані інсталяції OpenClaw не постачають `qa-lab`, тому вони не надають `openclaw qa`. + - Копії репозиторію можуть напряму підключати plugin з дерева: + `openclaw plugins install -l ./extensions/qa-matrix`. + - Налаштовує трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, потім запускає дочірній QA gateway з реальним Matrix plugin як транспортом SUT. + - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Замініть через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. + - Matrix не надає спільні прапори джерел облікових даних, оскільки ця лінія локально створює тимчасових користувачів. + - Записує Matrix QA-звіт, summary та observed-events artifact у `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає Telegram live QA-канал проти реальної приватної групи, використовуючи driver і SUT bot tokens з env. + - Запускає Telegram live QA-лінію проти реальної приватної групи з токенами ботів driver і SUT з 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. - - Потребує двох різних ботів в одній приватній групі, при цьому бот SUT має мати Telegram username. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що driver bot може спостерігати груповий трафік ботів. - - Записує Telegram QA-звіт, підсумок і observed-messages artifact у `.artifacts/qa-e2e/...`. + - Підтримує `--credential-source convex` для спільних пулових облікових даних. За замовчуванням використовуйте env-режим або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути орендовані облікові дані з пулу. + - Потребує двох різних ботів в одній приватній групі, причому бот SUT має надавати Telegram username. + - Для стабільного спостереження бот-до-бота увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати груповий трафік ботів. + - Записує Telegram QA-звіт, summary та observed-messages artifact у `.artifacts/qa-e2e/...`. -Live transport lanes мають один спільний стандартний контракт, щоб нові транспорти не розходилися: +Live-транспортні лінії використовують один стандартний контракт, щоб нові транспорти не дрейфували: -`qa-channel` залишається широким синтетичним QA-набором і не є частиною матриці покриття live transport. +`qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live-транспортів. -| Канал | Canary | Обмеження згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Продовження в треді | Ізоляція тредів | Спостереження за реакціями | Команда help | -| -------- | ------ | ---------------- | -------------------- | ------------------------- | ----------------------------- | ------------------- | --------------- | -------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Лінія | Canary | Gating за згадками | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Продовження у треді | Ізоляція тредів | Спостереження за реакціями | Команда help | +| -------- | ------ | ------------------ | -------------------- | ------------------------- | ----------------------------- | ------------------- | --------------- | --------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -### Спільні облікові дані Telegram через Convex (v1) +### Спільні Telegram-облікові дані через Convex (v1) -Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивний lease із пулу на базі Convex, надсилає Heartbeat цього lease, поки канал виконується, і звільняє lease під час завершення роботи. +Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat для цієї оренди під час роботи лінії та звільняє оренду під час завершення. -Довідковий scaffold проєкту Convex: +Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові змінні середовища: +Потрібні env-змінні: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` @@ -107,7 +111,7 @@ Live transport lanes мають один спільний стандартний - CLI: `--credential-role maintainer|ci` - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `maintainer`) -Необов’язкові змінні середовища: +Необов’язкові env-змінні: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) @@ -115,13 +119,13 @@ Live transport lanes мають один спільний стандартний - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL-адреси Convex лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback-URL Convex виду `http://` лише для локальної розробки. -`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. +У звичайному режимі `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. -Адміністративні команди maintainer (`pool 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 @@ -129,7 +133,7 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `--json` для machine-readable виводу в scripts і CI utilities. +Використовуйте `--json` для машиночитаного виводу в скриптах і утилітах CI. Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): @@ -149,7 +153,7 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активного lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Захист від активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` @@ -162,49 +166,54 @@ pnpm openclaw qa credentials remove --credential-id ### Додавання каналу до QA -Додавання каналу до markdown QA-системи вимагає рівно двох речей: +Додавання каналу до markdown QA-системи потребує рівно двох речей: -1. Транспортного адаптера для каналу. -2. Набору сценаріїв, що перевіряє контракт каналу. +1. Транспортний адаптер для каналу. +2. Набір сценаріїв, який перевіряє контракт каналу. -Не додавайте channel-specific QA runner, якщо спільний запускаючий засіб `qa-lab` може взяти цей процес на себе. +Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може володіти цим потоком. -`qa-lab` володіє спільною механікою: +`qa-lab` володіє спільною хост-логікою: -- запуском і завершенням набору -- паралелізмом workers -- записом artifact-файлів +- кореневою командою `openclaw qa` +- запуском і завершенням наборів +- паралелізмом воркерів +- записом артефактів - генерацією звітів - виконанням сценаріїв -- сумісними alias для старіших сценаріїв `qa-channel` +- alias сумісності для старіших сценаріїв `qa-channel` -Адаптер каналу володіє транспортним контрактом: +Runner plugins володіють транспортним контрактом: -- як конфігурується gateway для цього транспорту +- як `openclaw qa ` монтується під спільним коренем `qa` +- як gateway налаштовується для цього транспорту - як перевіряється готовність - як інжектуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються transcripts і нормалізований стан транспорту -- як виконуються transport-backed дії -- як обробляється transport-specific reset або cleanup +- як надаються транскрипти та нормалізований стан транспорту +- як виконуються дії на базі транспорту +- як обробляються транспортно-специфічні скидання або очищення -Мінімальний поріг для впровадження нового каналу: +Мінімальна планка впровадження для нового каналу така: -1. Реалізувати транспортний адаптер на спільному шві `qa-lab`. -2. Зареєструвати адаптер у transport registry. -3. Тримати transport-specific механіку всередині адаптера або harness каналу. -4. Написати або адаптувати markdown-сценарії в `qa/scenarios/`. -5. Використовувати generic helpers для нових сценаріїв. -6. Зберігати працездатність наявних compatibility aliases, якщо в репозиторії не відбувається навмисна міграція. +1. Залишайте `qa-lab` власником спільного кореня `qa`. +2. Реалізуйте transport runner на спільному шві хоста `qa-lab`. +3. Залишайте транспортно-специфічну механіку в runner plugin або harness plugin. +4. Монтуйте ранер як `openclaw qa `, а не реєструйте конкуруючий кореневий простір команд. + Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. + Залишайте `runtime-api.ts` легким; ліниве виконання CLI і ранерів має залишатися за окремими entrypoint. +5. Створюйте або адаптуйте markdown-сценарії в `qa/scenarios/`. +6. Використовуйте generic helper-и для нових сценаріїв. +7. Зберігайте наявні alias сумісності працездатними, якщо тільки репозиторій не виконує навмисну міграцію. -Правило ухвалення рішень є строгим: +Правило прийняття рішення суворе: -- Якщо поведінку можна виразити один раз у `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного channel transport, тримайте її в цьому адаптері або Plugin harness. -- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте generic helper замість channel-specific гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно зазначайте це в контракті сценарію. +- Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. +- Якщо поведінка залежить від одного транспортного каналу, залишайте її в цьому runner plugin або plugin harness. +- Якщо сценарію потрібна нова можливість, яку можуть використовувати більше ніж один канал, додайте generic helper замість channel-specific гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно відображайте це в контракті сценарію. -Бажані назви generic helper для нових сценаріїв: +Бажані назви generic helper-ів для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -219,7 +228,7 @@ pnpm openclaw qa credentials remove --credential-id - `formatTransportTranscript` - `resetTransport` -Compatibility aliases залишаються доступними для наявних сценаріїв, зокрема: +Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -227,64 +236,65 @@ Compatibility aliases залишаються доступними для ная - `formatConversationTranscript` - `resetBus` -У новій роботі з каналами слід використовувати generic helper names. -Compatibility aliases існують, щоб уникнути одномоментної міграції, а не як модель для написання нових сценаріїв. +Нова робота над каналами має використовувати generic helper-и. +Alias сумісності існують, щоб уникнути міграції «за один день», а не як модель для +створення нових сценаріїв. -## Набори тестів (що де запускається) +## Тестові набори (що де запускається) -Думайте про набори як про «зростання реалізму» (і зростання flaky/cost): +Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): ### Unit / integration (типовий) - Команда: `pnpm test` -- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) поверх наявних scoped Vitest projects -- Файли: core/unit inventories у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` та whitelisted `ui` node-тести, охоплені `vitest.unit.config.ts` +- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) поверх наявних scoped-проєктів Vitest +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і внесені до allowlist node-тести `ui`, які охоплює `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - In-process integration-тести (gateway auth, routing, tooling, parsing, config) - - Детерміновані регресії для відомих багів + - In-process integration-тести (автентифікація gateway, маршрутизація, tooling, парсинг, конфігурація) + - Детерміновані регресії для відомих помилок - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним -- Примітка про проєкти: - - Нецільовий `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` усе ще використовує граф проєктів native root `vitest.config.ts`, оскільки 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. - - Import-light unit-тести з agents, commands, plugins, helper-функцій auto-reply, `plugin-sdk` та подібних чисто утилітарних областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - - Вибрані helper source files `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними sibling tests у цих light lanes, щоб зміни helper-файлів не запускали повторно весь важкий набір для цього каталогу. - - `auto-reply` тепер має три окремі bucket-и: top-level core helper-функції, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі reply harness потрапляти на дешеві тести status/chunk/token. -- Примітка про embedded runner: - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime context Compaction, +- Примітка щодо проєктів: + - Нетаргетований `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` досі використовує native root-граф проєктів `vitest.config.ts`, оскільки цикл спостереження з кількома shard-ами непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні file/directory target-и через scoped-лінії, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root-проєкту. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped-лінії, коли diff торкається лише маршрутизованих source/test файлів; редагування config/setup усе ще повертаються до широкого повторного запуску root-проєкту. + - Легкі для імпорту unit-тести з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` і подібних чистих утилітарних областей маршрутизуються через лінію `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних лініях. + - Вибрані helper source-файли `plugin-sdk` і `commands` також маплять changed-mode запуски на явні sibling-тести в цих легких лініях, тому редагування helper-ів не потребують повторного запуску всього важкого набору для цього каталогу. + - `auto-reply` тепер має три окремі кошики: top-level core helper-и, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це не дає найважчій harness-роботі reply навантажувати дешеві тести status/chunk/token. +- Примітка щодо embedded runner: + - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст Compaction, зберігайте обидва рівні покриття. - - Додавайте сфокусовані helper-регресії для чистих меж routing/normalization. - - Також підтримуйте здоровий стан integration-наборів embedded runner: + - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації/нормалізації. + - Також підтримуйте здоровими integration-набори embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped ids і поведінка Compaction усе ще проходять - через реальні шляхи `run.ts` / `compact.ts`; helper-only тести не є + - Ці набори перевіряють, що scoped id та поведінка Compaction, як і раніше, проходять + через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є достатньою заміною для цих integration-шляхів. -- Примітка про pool: +- Примітка щодо pool: - Базова конфігурація Vitest тепер типово використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e і live configs. - - Root UI lane зберігає своє налаштування `jsdom` і optimizer, але тепер теж працює на спільному non-isolated runner. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root-проєктах, e2e та live-конфігураціях. + - Коренева лінія UI зберігає свій `jsdom` setup та optimizer, але тепер також працює на спільному non-isolated runner. - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. -- Примітка про швидку локальну ітерацію: - - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи чисто зіставляються з меншим набором. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею workers. - - Автомасштабування локальних workers тепер навмисно консервативне й також зменшує навантаження, коли середнє навантаження хоста вже високе, тому кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базова конфігурація Vitest позначає projects/config files як `forceRerunTriggers`, щоб reruns у changed-mode залишалися коректними, коли змінюється wiring тестів. + - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо вам потрібно порівняти зі стандартною поведінкою V8. +- Примітка щодо швидкої локальної ітерації: + - `pnpm test:changed` маршрутизується через scoped-лінії, коли змінені шляхи чисто мапляться на менший набір. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом воркерів. + - Автомасштабування локальних воркерів тепер навмисно консервативне й також зменшує навантаження, коли середнє завантаження хоста вже високе, тому кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає файли проєктів/конфігурації як `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 path для цього зафіксованого diff і виводить wall time та macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` виконує benchmarking поточного брудного дерева, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує CPU profile головного потоку для накладних витрат запуску та transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap profiles runner-а для unit-набору з вимкненим file parallelism. +- Примітка щодо налагодження продуктивності: + - `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 та macOS max RSS. +- `pnpm test:perf:changed:bench -- --worktree` вимірює поточне брудне дерево, маршрутизуючи список змінених файлів через `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) @@ -292,36 +302,36 @@ Compatibility aliases існують, щоб уникнути одномомен - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` - Типові параметри runtime: - - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує adaptive workers (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням запускається в silent mode, щоб зменшити накладні витрати на console I/O. -- Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість workers (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути verbose console output. + - Використовує `threads` у Vitest з `isolate: false`, як і решта репозиторію. + - Використовує адаптивну кількість воркерів (CI: до 2, локально: типово 1). + - Типово запускається в silent-режимі, щоб зменшити накладні витрати на console I/O. +- Корисні override-и: + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість воркерів (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - End-to-end поведінка gateway з кількома інстансами - - Поверхні WebSocket/HTTP, pairing Node і важчі мережеві сценарії + - Наскрізна поведінка gateway з кількома інстансами + - Поверхні WebSocket/HTTP, pairing Node та важча мережева взаємодія - Очікування: - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: backend smoke OpenShell +### E2E: smoke для backend OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` - Обсяг: - - Запускає ізольований OpenShell gateway на хості через Docker - - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Запускає ізольований gateway OpenShell на хості через Docker + - Створює sandbox з тимчасового локального Dockerfile + - Перевіряє backend OpenShell OpenClaw через реальні `sandbox ssh-config` + SSH exec - Перевіряє remote-canonical поведінку файлової системи через fs bridge sandbox - Очікування: - - Лише opt-in; не є частиною типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` плюс працездатний Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує test gateway і sandbox -- Корисні перевизначення: + - Лише opt-in; не входить до типового запуску `pnpm test:e2e` + - Потребує локальний CLI `openshell` і працездатний Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox +- Корисні override-и: - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний CLI binary або wrapper script + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний CLI-бінарник або wrapper-скрипт ### Live (реальні провайдери + реальні моделі) @@ -330,141 +340,141 @@ Compatibility aliases існують, щоб уникнути одномомен - Файли: `src/**/*.live.test.ts` - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей tool calling, проблем auth і поведінки rate limit + - «Чи ця модель/провайдер справді працює _сьогодні_ з реальними обліковими даними?» + - Виявлення змін форматів провайдерів, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit - Очікування: - - Навмисно не є CI-stable (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / використовує rate limits + - За задумом нестабільно для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / використовує rate limit - Краще запускати звужені підмножини, а не «все» -- Live-запуски завантажують `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють config/auth-матеріали в тимчасовий test home, щоб unit fixtures не могли змінити ваш реальний `~/.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, щоб довгі виклики провайдера було видно як активні навіть тоді, коли захоплення console у Vitest тихе. - - `vitest.live.config.ts` вимикає перехоплення console у Vitest, щоб рядки прогресу провайдера/gateway передавалися негайно під час live-запусків. - - Налаштовуйте Heartbeat прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. +- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. +- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує логи bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні startup-логи. +- Ротація API-ключів (залежно від провайдера): установлюйте `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використовуйте override на рівні live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. +- Вивід progress/Heartbeat: + - Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдерів було видно як активні, навіть коли перехоплення консолі Vitest тихе. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тому рядки прогресу провайдера/gateway відразу транслюються під час live-запусків. + - Налаштовуйте Heartbeat для прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Використовуйте цю таблицю рішень: +Скористайтеся цією таблицею рішень: -- Редагуєте логіку/тести: запустіть `pnpm test` (і `pnpm test:coverage`, якщо змін було багато) -- Торкаєтеся gateway networking / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / provider-specific збої / tool calling: запустіть звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато що змінили) +- Торкаєтеся мережевої взаємодії gateway / WS-протоколу / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / виклик інструментів: запускайте звужений `pnpm test:live` ## Live: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку наразі рекламує** підключений Android Node, і перевірити поведінку контракту команди. +- Мета: викликати **кожну команду, яка зараз рекламується** підключеним Android Node, і перевірити поведінку контракту команди. - Обсяг: - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не pair-ить застосунок). - - Перевірка `node.invoke` у Gateway для вибраного Android Node, команда за командою. -- Обов’язкова попередня підготовка: - - Android-застосунок уже підключено та pair-ено до gateway. + - Перевірка gateway `node.invoke` для вибраного Android Node команда за командою. +- Потрібне попереднє налаштування: + - Android-застосунок уже підключено та зpairено з gateway. - Застосунок утримується на передньому плані. - - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте побачити як успішні. -- Необов’язкові перевизначення цілі: + - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте як успішні. +- Необов’язкові override-и цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Повні відомості про налаштування Android: [Android App](/uk/platforms/android) +- Повні подробиці налаштування Android: [Android App](/uk/platforms/android) -## Live: model smoke (profile keys) +## Live: smoke для моделей (ключі профілів) -Live-тести поділено на два рівні, щоб можна було ізолювати збої: +Live-тести поділено на два шари, щоб можна було ізолювати збої: -- «Direct model» показує, чи може провайдер/модель взагалі відповісти з даним ключем. -- «Gateway smoke» показує, чи працює повний pipeline gateway+agent для цієї моделі (sessions, history, tools, sandbox policy тощо). +- «Пряма модель» показує нам, чи може провайдер/модель взагалі відповісти з наданим ключем. +- «Smoke Gateway» показує нам, чи працює повний pipeline gateway+agent для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). -### Рівень 1: Пряме завершення моделі (без gateway) +### Шар 1: Пряме завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використовувати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Запустити невелике completion для кожної моделі (і цільові регресії, де це потрібно) + - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані + - Запустити невелике completion для кожної моделі (і точкові регресії за потреби) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest безпосередньо) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб справді запустити цей набір; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на gateway smoke + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest напряму) +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб фактично запустити цей набір; інакше його буде пропущено, щоб `pnpm test:live` залишався сфокусованим на gateway smoke - Як вибирати моделі: - `OPENCLAW_LIVE_MODELS=modern` для запуску modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` — це alias для modern allowlist - - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (comma allowlist) - - Sweeps modern/all за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого обмеження. + - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через коми) + - Modern/all sweeps типово використовують curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого ліміту. - Як вибирати провайдерів: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (comma allowlist) + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через коми) - Звідки беруться ключі: - - За замовчуванням: profile store і env fallbacks - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** + - Типово: сховище профілів і env-fallback-и + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «pipeline gateway agent зламаний» - - Містить малі, ізольовані регресії (приклад: reasoning replay + потоки tool-call у OpenAI Responses/Codex Responses) + - Відокремлює «API провайдера зламаний / ключ недійсний» від «pipeline gateway agent зламаний» + - Містить невеликі ізольовані регресії (наприклад: повторне відтворення reasoning OpenAI Responses/Codex Responses + потоки tool-call) -### Рівень 2: Gateway + smoke dev agent (що насправді робить "@openclaw") +### Шар 2: smoke Gateway + dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - Підняти in-process gateway - - Створити/оновити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) - - Ітеруватися по моделях-із-ключами та перевіряти: + - Створити/оновити сесію `agent:dev:*` (override моделі для кожного запуску) + - Ітерувати моделі з ключами та перевіряти: - «змістовну» відповідь (без інструментів) - - що працює реальний виклик інструмента (перевірка `read`) - - необов’язкові додаткові перевірки інструментів (перевірка `exec+read`) - - що регресійні шляхи OpenAI (лише tool-call → follow-up) продовжують працювати -- Деталі probe-ів (щоб можна було швидко пояснювати збої): - - probe `read`: тест записує файл із nonce у workspace і просить агента `read` його та повернути nonce. - - probe `exec+read`: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. - - image probe: тест прикріплює згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. - - Довідка щодо реалізації: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. + - що реальний виклик інструмента працює (проба `read`) + - необов’язкові додаткові проби інструментів (проба `exec+read`) + - що шляхи регресій OpenAI (лише tool-call → follow-up) продовжують працювати +- Деталі probes (щоб ви могли швидко пояснювати збої): + - Проба `read`: тест записує файл з nonce у workspace і просить агента `read` його та повернути nonce у відповіді. + - Проба `exec+read`: тест просить агента через `exec` записати nonce у тимчасовий файл, а потім через `read` прочитати його назад. + - Проба зображення: тест додає згенерований PNG (кіт + рандомізований код) і очікує, що модель поверне `cat `. + - Еталонна реалізація: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest безпосередньо) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest напряму) - Як вибирати моделі: - Типово: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — alias для modern allowlist - - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або comma list), щоб звузити вибір - - Gateway sweeps modern/all за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого обмеження. -- Як вибирати провайдерів (уникати «усе через OpenRouter»): - - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (comma allowlist) -- Tool + image probes у цьому live-тесті завжди ввімкнені: - - probe `read` + probe `exec+read` (навантаження на інструменти) - - image probe запускається, коли модель оголошує підтримку image input + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це alias для modern allowlist + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір + - Modern/all gateway sweeps типово використовують curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого ліміту. +- Як вибирати провайдерів (уникати «усе OpenRouter»): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) +- Проби інструментів і зображень у цьому live-тесті завжди ввімкнені: + - проба `read` + проба `exec+read` (навантаження на інструменти) + - проба зображення запускається, коли модель заявляє підтримку вхідних зображень - Потік (на високому рівні): - - Тест генерує крихітний PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) + - Тест генерує маленький 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 агент пересилає мультимодальне повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) + - Embedded agent передає моделі мультимодальне повідомлення користувача + - Перевірка: відповідь містить `cat` + код (допускаються незначні OCR-помилки) -Порада: щоб побачити, що саме можна протестувати на вашій машині (і точні id `provider/model`), виконайте: +Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), запустіть: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke backend CLI (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke для CLI backend (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити pipeline Gateway + агент, використовуючи локальний CLI backend, не торкаючись вашої типової конфігурації. -- Типові smoke-параметри для backend живуть у визначенні `cli-backend.ts` відповідного extension. +- Мета: перевірити pipeline Gateway + agent з використанням локального CLI backend, не торкаючись вашої типової конфігурації. +- Типові smoke-параметри для конкретного backend зберігаються у визначенні `cli-backend.ts` відповідного extension. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest безпосередньо) + - `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. -- Перевизначення (необов’язкові): + - Поведінка команди/аргументів/зображень береться з метаданих plugin власника CLI backend. +- Override-и (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальний image attachment (шляхи інжектуються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до image-файлів як CLI args замість інжекції в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) щоб керувати способом передавання image args, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий хід і перевірити flow відновлення. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` щоб вимкнути типову перевірку безперервності однієї сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує перемикання цілі). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальне вкладення-зображення (шляхи інжектуються у 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` щоб надіслати другий хід і перевірити потік resume. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` щоб вимкнути типову пробу безперервності в тій самій сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово її ввімкнути, коли вибрана модель підтримує ціль переключення). Приклад: @@ -480,7 +490,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` -Рецепти Docker для одного провайдера: +Docker-рецепти для окремих провайдерів: ```bash pnpm test:docker:live-cli-backend:claude @@ -491,38 +501,38 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker runner розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke CLI-backend усередині Docker image репозиторію як непривілейований користувач `node`. -- Він визначає метадані CLI smoke від extension-власника, а потім встановлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує portable 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 lane за замовчуванням вимикає Claude MCP/tool та image probes, оскільки Claude зараз маршрутизує використання сторонніх застосунків через додаткову оплату, а не через звичайні ліміти subscription plan. -- Live smoke CLI-backend тепер перевіряє той самий end-to-end flow для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик інструмента MCP `cron`, перевірений через Gateway CLI. -- Типовий smoke для Claude також оновлює сесію з Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke для CLI backend усередині Docker-образу репозиторію як непривілейований користувач `node`. +- Він визначає метадані CLI smoke з extension власника, а потім встановлює відповідний Linux-пакет CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований writable prefix за адресою `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 без збереження env-змінних Anthropic API key. Ця subscription-лінія типово вимикає Claude MCP/tool і probes зображень, оскільки Claude наразі маршрутизує використання стороннього застосунку через білінг extra-usage, а не через звичайні ліміти subscription plan. +- Live smoke CLI backend тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через Gateway CLI. +- Типовий smoke для Claude також оновлює сесію з Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. -## Live: smoke ACP bind (`/acp spawn ... --bind here`) +## Live: smoke для прив’язки ACP (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний flow прив’язки розмови ACP із live ACP-агентом: +- Мета: перевірити реальний потік conversation-bind ACP із live ACP agent: - надіслати `/acp spawn --bind here` - прив’язати synthetic conversation каналу повідомлень на місці - - надіслати звичайний follow-up у цій самій розмові - - перевірити, що follow-up потрапляє в transcript прив’язаної сесії ACP + - надіслати звичайний follow-up у тій самій conversation + - перевірити, що follow-up потрапляє в transcript прив’язаної ACP session - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - ACP-агенти в Docker: `claude,codex,gemini` - ACP-агент для прямого `pnpm test:live ...`: `claude` - - Synthetic channel: контекст розмови у стилі Slack DM + - Synthetic channel: контекст conversation у стилі Slack DM - ACP backend: `acpx` -- Перевизначення: +- Override-и: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` - `OPENCLAW_LIVE_ACP_BIND_AGENT=gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Примітки: - - Цей lane використовує поверхню Gateway `chat.send` з admin-only synthetic originating-route fields, щоб тести могли додавати контекст каналу повідомлень без удавання зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований agent registry Plugin `acpx` для вибраного ACP harness agent. + - Ця лінія використовує поверхню gateway `chat.send` з synthetic полями originating-route, доступними лише адміністратору, щоб тести могли приєднати контекст message-channel без удавання зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness agent. Приклад: @@ -538,7 +548,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Рецепти Docker для одного агента: +Docker-рецепти для окремих агентів: ```bash pnpm test:docker:live-acp-bind:claude @@ -548,31 +558,31 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker runner розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI agents: `claude`, `codex`, потім `gemini`. +- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він послідовно запускає smoke ACP bind для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він завантажує `~/.profile`, підготовлює відповідні CLI auth-матеріали в контейнері, встановлює `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. +- Він використовує `~/.profile`, готує відповідні матеріали автентифікації CLI в контейнері, встановлює `acpx` у writable npm prefix, а потім, за потреби, встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`). +- Усередині Docker ранер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера зі зчитаного profile доступними для дочірнього harness CLI. -## Live: smoke app-server harness Codex +## Live: smoke для harness app-server Codex -- Мета: перевірити Plugin-owned harness Codex через звичайний метод Gateway +- Мета: перевірити plugin-owned harness Codex через звичайний gateway-метод `agent`: - - завантажити bundled Plugin `codex` + - завантажити bundled plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший хід gateway agent до `codex/gpt-5.4` - - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що thread - app-server можна відновити - - запустити `/codex status` і `/codex models` через той самий command - path Gateway + - надіслати перший gateway agent turn до `codex/gpt-5.4` + - надіслати другий turn до тієї самої сесії OpenClaw і перевірити, що thread + app-server може відновитися + - запустити `/codex status` і `/codex models` через той самий шлях + gateway-команд - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `codex/gpt-5.4` -- Необов’язковий image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Необов’язковий MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex - не міг пройти перевірку завдяки тихому fallback до PI. -- Auth: `OPENAI_API_KEY` із shell/profile, плюс необов’язково скопійовані +- Необов’язкова probe зображення: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язкова MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Цей smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex + harness не міг пройти тест, тихо перемкнувшись назад на PI. +- Автентифікація: `OPENAI_API_KEY` із shell/profile, а також за потреби скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -595,48 +605,52 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker runner розташований у `scripts/test-live-codex-harness-docker.sh`. -- Він завантажує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює auth-файли Codex CLI за їх наявності, встановлює `@openai/codex` у записуваний змонтований npm prefix, підготовлює source tree, а потім запускає лише live-тест harness Codex. -- Docker за замовчуванням вмикає image і MCP/tool probes. Установіть +- Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + автентифікації CLI Codex, якщо вони присутні, встановлює `@openai/codex` у writable змонтований npm + prefix, готує дерево вихідного коду, а потім запускає лише live-тест Codex-harness. +- У Docker probes зображення та MCP/tool увімкнені за замовчуванням. Установіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, коли потрібен вужчий запуск для налагодження. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і конфігурація live-тесту, щоб fallback до `openai-codex/*` або PI не міг приховати регресію harness Codex. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і конфігурація live-тесту, + тож fallback на `openai-codex/*` або PI не зможе приховати регресію + Codex harness. ### Рекомендовані live-рецепти -Вузькі, явні allowlist-и — найшвидші та найменш flaky: +Найшвидшими та найменш нестабільними є вузькі, явні allowlist: -- Одна модель, прямий режим (без gateway): +- Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` - Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling для кількох провайдерів: +- Виклик інструментів у кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Фокус на Google (Gemini API key + Antigravity): +- Фокус на 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 key). -- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint агента у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема auth + особливості tooling). +- `google-antigravity/...` використовує OAuth-міст Antigravity (endpoint агента у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості tooling). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає хостований Gemini API від Google через HTTP (API key / profile auth); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує локальний binary `gemini`; він має власну auth і може поводитися інакше (streaming/tool support/version skew). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API key / автентифікація профілю); це те, що більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує shell-виклик локального бінарника `gemini`; він має власну автентифікацію та може поводитися інакше (streaming/підтримка інструментів/version skew). -## Live: матриця моделей (що ми покриваємо) +## Live: матриця моделей (що ми охоплюємо) -Немає фіксованого «CI-списку моделей» (live — це opt-in), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. +Фіксованого «списку моделей CI» немає (live — це opt-in), але це **рекомендовані** моделі, які варто регулярно покривати на dev-машині з ключами. -### Сучасний smoke-набір (tool calling + image) +### Набір modern smoke (виклик інструментів + зображення) -Це запуск «поширених моделей», який ми очікуємо підтримувати робочим: +Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: -- OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) +- OpenAI (не-Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) - Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) @@ -644,12 +658,12 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запускати gateway smoke з tools + image: +Запускати gateway smoke з інструментами + зображенням: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: tool calling (Read + необов’язковий Exec) +### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) -Вибирайте щонайменше одну модель із кожної сім’ї провайдерів: +Виберіть принаймні одну модель на сімейство провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -660,61 +674,61 @@ pnpm test:docker:live-codex-harness Необов’язкове додаткове покриття (було б добре мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою tools, яку у вас увімкнено) +- Mistral: `mistral/`… (виберіть одну модель з підтримкою “tools”, яку у вас ввімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) -- LM Studio: `lmstudio/`… (локально; tool calling залежить від API mode) +- LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) -### Vision: надсилання зображення (attachment → мультимодальне повідомлення) +### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте щонайменше одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI-варіанти з підтримкою vision тощо), щоб перевірити image probe. +Додайте принаймні одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI-варіанти з підтримкою vision тощо), щоб перевірити image probe. -### Агрегатори / альтернативні Gateway +### Агрегатори / альтернативні gateway Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) -- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою інструментів+зображень) +- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Інші провайдери, які можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): +Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-compatible proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (custom endpoint-и): `minimax` (хмара/API), а також будь-який OpenAI/Anthropic-сумісний проксі (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко закодувати «всі моделі» в документації. Авторитетний список — це те, що `discoverModels(...)` повертає на вашій машині, плюс ті ключі, які доступні. +Порада: не намагайтеся жорстко зафіксувати в документації «всі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс ті ключі, які доступні. ## Облікові дані (ніколи не комітьте) -Live-тести виявляють облікові дані так само, як і CLI. Практичні наслідки: +Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знаходити ті самі ключі. +- Якщо CLI працює, live-тести мають знайти ті самі ключі. - Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі auth для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «profile keys» у live-тестах) +- Профілі автентифікації для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «profile keys» у live-тестах) - Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Застарілий каталог стану: `~/.openclaw/credentials/` (копіюється в підготовлений live home, якщо присутній, але це не основне сховище profile keys) -- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги CLI auth у тимчасовий test home; підготовлені live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` вилучаються, щоб probes не торкалися вашого реального хостового workspace. +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється у staged live home, якщо присутній, але не є основним сховищем profile keys) +- Локальні live-запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий каталог `credentials/` і підтримувані зовнішні каталоги автентифікації CLI у тимчасовий test home; staged live home пропускають `workspace/` і `sandboxes/`, а override-и шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не торкалися вашого реального host-workspace. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker runners нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Live: Deepgram (транскрипція аудіо) +## Live: Deepgram (транскрибування аудіо) - Тест: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live: coding plan BytePlus +## Live: BytePlus 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` +- Необов’язковий override моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live: media workflow ComfyUI +## Live: media для workflow ComfyUI - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи зображення, відео та `music_generate` у comfy + - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у надсиланні workflow comfy, polling, downloads або реєстрації Plugin + - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації plugin ## Live: генерація зображень @@ -722,24 +736,24 @@ Live-тести виявляють облікові дані так само, я - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перелічує кожен зареєстрований Plugin провайдера генерації зображень - - Завантажує відсутні env vars провайдерів із вашого login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API keys раніше за збережені auth profiles, щоб застарілі test keys у `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдерів без придатної auth/profile/model - - Запускає стандартні варіанти генерації зображень через спільну runtime capability: + - Перелічує кожен зареєстрований plugin провайдера генерації зображень + - Завантажує відсутні env-змінні провайдера з вашої login shell (`~/.profile`) перед виконанням probes + - Типово використовує live/env API keys раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Запускає стандартні варіанти генерації зображень через спільну runtime-можливість: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Наразі покриті вбудовані провайдери: +- Поточні вбудовані провайдери, які охоплено: - `openai` - `google` - Необов’язкове звуження: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env +- Необов’язкова поведінка автентифікації: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати override-и лише через env ## Live: генерація музики @@ -747,23 +761,23 @@ Live-тести виявляють облікові дані так само, я - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний шлях вбудованих провайдерів генерації музики + - Перевіряє спільний вбудований шлях провайдера генерації музики - Наразі охоплює Google і MiniMax - - Завантажує env vars провайдерів із вашого login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API keys раніше за збережені auth profiles, щоб застарілі test keys у `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдерів без придатної auth/profile/model - - Запускає обидва оголошені runtime modes, коли вони доступні: - - `generate` із вхідними даними лише prompt + - Завантажує env-змінні провайдера з вашої login shell (`~/.profile`) перед виконанням probes + - Типово використовує live/env API keys раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Запускає обидва оголошені runtime-режими, коли вони доступні: + - `generate` з вхідними даними лише у вигляді prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільного каналу: + - Поточне покриття спільної лінії: - `google`: `generate`, `edit` - `minimax`: `generate` - `comfy`: окремий live-файл Comfy, не цей спільний sweep - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env +- Необов’язкова поведінка автентифікації: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати override-и лише через env ## Live: генерація відео @@ -771,170 +785,170 @@ Live-тести виявляють облікові дані так само, я - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний шлях вбудованих провайдерів генерації відео - - За замовчуванням використовує безпечний для релізу smoke-шлях: провайдери не-FAL, один запит text-to-video на провайдера, одноcекундний lobster prompt і ліміт операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) - - За замовчуванням пропускає FAL, оскільки затримка черги на стороні провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно - - Завантажує env vars провайдерів із вашого login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API keys раніше за збережені auth profiles, щоб застарілі test keys у `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдерів без придатної auth/profile/model - - За замовчуванням запускає лише `generate` - - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені transform modes, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled`, а вибраний провайдер/модель приймає buffer-backed локальний ввід зображення у спільному sweep - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled`, а вибраний провайдер/модель приймає buffer-backed локальний ввід відео у спільному sweep - - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному sweep: - - `vydra`, бо вбудований `veo3` підтримує лише text-to-video, а вбудований `kling` вимагає віддалений URL зображення - - Специфічне покриття Vydra для провайдера: + - Перевіряє спільний вбудований шлях провайдера генерації відео + - Типово використовує безпечний для релізу шлях smoke: провайдери без FAL, один текст-у-відео запит на провайдера, one-second lobster prompt і обмеження операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (типово `180000`) + - Типово пропускає FAL, оскільки затримка черги на стороні провайдера може домінувати над часом релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно + - Завантажує env-змінні провайдера з вашої login shell (`~/.profile`) перед виконанням probes + - Типово використовує live/env API keys раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Типово запускає лише `generate` + - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний ввід зображень у буфері в межах спільного sweep + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний ввід відео у буфері в межах спільного sweep + - Поточні провайдери `imageToVideo`, оголошені, але пропущені у спільному sweep: + - `vydra`, оскільки вбудований `veo3` є лише текстовим, а вбудований `kling` потребує віддалений URL зображення + - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс канал `kling`, який за замовчуванням використовує fixture із віддаленим URL зображення + - цей файл запускає `veo3` text-to-video плюс лінію `kling`, яка типово використовує fixture з віддаленим URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному sweep: - - `alibaba`, `qwen`, `xai`, бо ці шляхи наразі вимагають віддалені reference URL `http(s)` / MP4 - - `google`, бо поточний спільний канал Gemini/Veo використовує локальний buffer-backed ввід, а цей шлях не приймається у спільному sweep - - `openai`, бо поточний спільний канал не гарантує доступ до org-specific video inpaint/remix + - Поточні провайдери `videoToVideo`, оголошені, але пропущені у спільному sweep: + - `alibaba`, `qwen`, `xai`, оскільки ці шляхи зараз потребують віддалених reference URL `http(s)` / MP4 + - `google`, оскільки поточна спільна лінія Gemini/Veo використовує локальний ввід у буфері, і цей шлях не приймається у спільному sweep + - `openai`, оскільки поточна спільна лінія не гарантує доступ до org-specific video inpaint/remix - Необов’язкове звуження: - `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-запуску -- Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового sweep, включно з FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного провайдера для агресивного smoke-запуску +- Необов’язкова поведінка автентифікації: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати override-и лише через env -## Harness live media +## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори image, music і video через один рідний для репозиторію entrypoint - - Автоматично завантажує відсутні env vars провайдерів із `~/.profile` - - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну auth - - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і quiet mode залишається узгодженою + - Запускає спільні live-набори для зображень, музики та відео через один вбудований entrypoint репозиторію + - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` + - Типово автоматично звужує кожен набір до провайдерів, які зараз мають придатну автентифікацію + - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і quiet mode залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker runners (необов’язкові перевірки «працює в Linux») +## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці Docker runners поділяються на дві групи: +Ці Docker-ранери поділяються на дві категорії: -- Live-model runners: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм live-файл profile-key усередині Docker image репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний config dir і workspace (та завантажують `~/.profile`, якщо він змонтований). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live runners за замовчуванням використовують менший smoke cap, щоб повний Docker sweep залишався практичним: - `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Live-model ранери: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл з profile keys усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та workspace (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-ранери типово використовують менший smoke-ліміт, щоб повний Docker sweep залишався практичним: + `test:docker:live-models` типово встановлює `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` типово встановлює `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли - навмисно хочете більший вичерпний scan. -- `test:docker:all` один раз збирає live Docker 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:plugins` підіймають один або кілька реальних контейнерів і перевіряють integration-шляхи вищого рівня. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли + вам явно потрібен більший вичерпний scan. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох live Docker-ліній. +- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` підіймають один або більше реальних контейнерів і перевіряють integration-шляхи вищого рівня. -Docker runners для live-model також bind-mount-ять лише потрібні CLI auth home-каталоги (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи auth store хоста: +Live-model Docker-ранери також bind-mount лише потрібні home-каталоги автентифікації CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішніх CLI міг оновлювати токени без змін у host-сховищі автентифікації: - Прямі моделі: `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 app-server harness Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Мережева взаємодія Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Міст каналу MCP (seeded Gateway + stdio bridge + raw smoke notification-frame Claude): `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`) +- Майстер онбордингу (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Мережа Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Міст каналу MCP (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`) -Docker runners для live-model також bind-mount-ять поточний checkout у режимі лише читання та -підготовлюють його в тимчасовий workdir усередині контейнера. Це зберігає runtime -image компактним, але все одно дозволяє запускати Vitest точно на вашому локальному source/config. -Етап підготовки пропускає великі локальні кеші та результати збірки застосунків, як-от +Live-model Docker-ранери також bind-mount поточний checkout лише для читання і +готує його в тимчасовий workdir усередині контейнера. Це зберігає runtime-образ +компактним, але водночас дозволяє запускати Vitest точно на вашому локальному source/config. +Етап staging пропускає великі локальні кеші та вихідні дані збірки застосунків, як-от `.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання machine-specific artifact-ів. -Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes Gateway не запускали -реальні workers каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway -live coverage з цього Docker-каналу. -`test:docker:openwebui` — це compatibility smoke вищого рівня: він запускає -контейнер Gateway OpenClaw з увімкненими HTTP endpoint-ами, сумісними з OpenAI, -запускає pinned контейнер Open WebUI проти цього Gateway, виконує вхід через +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб gateway live-probes не запускали +реальні worker-и каналів Telegram/Discord тощо всередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити gateway +live-покриття з цієї Docker-лінії. +`test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає +контейнер Gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoint-ами, +запускає pinned-контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat request через proxy `/api/chat/completions` Open WebUI. +реальний chat-запит через проксі `/api/chat/completions` Open WebUI. Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження -image Open WebUI, а Open WebUI може завершувати власне налаштування cold-start. -Цей канал очікує придатний ключ live model, а `OPENCLAW_PROFILE_FILE` -(`~/.profile` за замовчуванням) — основний спосіб надати його в Dockerized runs. +образу Open WebUI, а сам Open WebUI може завершувати власний cold-start setup. +Ця лінія очікує наявність придатного ключа live-моделі, а `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) є основним способом надати його в Dockerized-запусках. Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає seeded контейнер Gateway, -стартує другий контейнер, який запускає `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання transcript, metadata attachment-ів, -поведінку черги live event, маршрутизацію outbound send, а також notifications каналу + permissions -у стилі Claude через реальний stdio MCP bridge. Перевірка notification -безпосередньо інспектує raw stdio MCP frames, тому smoke перевіряє те, що -міст реально випромінює, а не лише те, що випадково показує конкретний client SDK. +`test:docker:mcp-channels` навмисно є детермінованим і не потребує +реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway +контейнер, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім +перевіряє виявлення conversation із маршрутизацією, читання transcript-ів, metadata вкладень, +поведінку черги live-подій, маршрутизацію outbound send, а також channel- і +permission-сповіщення у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +напряму досліджує raw stdio MCP frame-и, тож smoke перевіряє те, що міст +справді випромінює, а не лише те, що випадково показує конкретний client SDK. -Ручний smoke plain-language thread ACP (не CI): +Ручний smoke plain-language thread для ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для workflow регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. +- Зберігайте цей скрипт для регресійних сценаріїв і налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. -Корисні env vars: +Корисні env-змінні: -- `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_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`), монтується в `/home/node/.npm-global` для кешованих CLI-встановлень у Docker -- Зовнішні CLI auth dirs/files у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів +- `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_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установок CLI усередині Docker +- Зовнішні каталоги/файли автентифікації CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Для звужених запусків монтуються лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Ручне перевизначення: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_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`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків без потреби в перебудові -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться зі сховища профілів, а не з env -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway показуватиме для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити pinned tag image Open WebUI +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів у контейнері +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків без потреби в перебудові +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться зі сховища профілів (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, використаний у smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити pinned tag образу Open WebUI ## Перевірка документації -Після змін у документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. +Запускайте перевірки docs після редагування документації: `pnpm check:docs`. +Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресії (безпечні для CI) +## Офлайн-регресія (безпечна для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Tool calling Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, примусовий запис config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик інструментів Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, запис конфігурації + примусова auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") ## Оцінювання надійності агентів (Skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»: -- Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- End-to-end flow майстра, які перевіряють session wiring і ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Mock-виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- Наскрізні потоки майстра, які перевіряють wiring сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). -Що ще відсутнє для Skills (див. [Skills](/uk/tools/skills)): +Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Ухвалення рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? +- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? - **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок виклику інструментів, перенесення history між сесіями та межі sandbox. +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. Майбутні eval-и мають насамперед залишатися детермінованими: -- Запускач сценаріїв із mock providers для перевірки tool calls + порядку, читання skill files і session wiring. -- Невеликий набір сценаріїв, зосереджених на Skills (використати чи уникнути, gate-умови, prompt injection). -- Необов’язкові live eval-и (opt-in, з env gate) — лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв з mock-провайдерами для перевірки викликів інструментів + їх порядку, читання skill-файлів і wiring сесій. +- Невеликий набір сценаріїв, сфокусованих на skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live eval-и (opt-in, керовані env) — лише після появи безпечного для CI набору. ## Контрактні тести (форма Plugin і каналу) -Контрактні тести перевіряють, що кожен зареєстрований Plugin і канал відповідає -контракту свого інтерфейсу. Вони ітеруються по всіх виявлених Plugin і запускають набір -перевірок форми та поведінки. Типовий unit-канал `pnpm test` навмисно -пропускає ці файли спільних швів і smoke; запускайте контрактні команди явно, +Контрактні тести перевіряють, що кожен зареєстрований Plugin і канал відповідає своєму +контракту інтерфейсу. Вони перебирають усі виявлені plugins і запускають набір +перевірок форми та поведінки. Типова unit-лінія `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, коли торкаєтеся спільних поверхонь каналу або провайдера. ### Команди @@ -947,29 +961,29 @@ image Open WebUI, а Open WebUI може завершувати власне н Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма Plugin (id, name, capabilities) +- **plugin** - Базова форма plugin (id, name, capabilities) - **setup** - Контракт майстра налаштування - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій каналу -- **threading** - Обробка ID тредів +- **threading** - Обробка ID thread - **directory** - API каталогу/реєстру -- **group-policy** - Забезпечення групової policy +- **group-policy** - Забезпечення політики групи -### Контракти стану провайдера +### Контракти стану провайдерів Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки status провайдера -- **registry** - Форма registry Plugin +- **status** - Probes стану каналу +- **registry** - Форма реєстру Plugin ### Контракти провайдерів Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт flow auth -- **auth-choice** - Вибір/відбір auth +- **auth** - Контракт потоку автентифікації +- **auth-choice** - Вибір/селекція автентифікації - **catalog** - API каталогу моделей - **discovery** - Виявлення Plugin - **loader** - Завантаження Plugin @@ -979,21 +993,21 @@ image Open WebUI, а Open WebUI може завершувати власне н ### Коли запускати -- Після змін в export-ах або subpath `plugin-sdk` -- Після додавання або зміни Plugin каналу чи провайдера -- Після рефакторингу реєстрації Plugin або discovery +- Після змін export-ів або subpath-ів plugin-sdk +- Після додавання або зміни channel чи provider plugin +- Після рефакторингу реєстрації Plugin або виявлення -Контрактні тести запускаються в CI і не потребують реальних API keys. +Контрактні тести запускаються в CI й не потребують реальних API key. ## Додавання регресій (рекомендації) -Коли ви виправляєте проблему провайдера/моделі, виявлену у live: +Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Якщо можливо, додавайте безпечну для CI регресію (mock/stub провайдера або фіксацію точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live (rate limits, auth policies), залишайте live-тест вузьким і opt-in через env vars -- Намагайтеся націлюватися на найменший рівень, який ловить баг: - - баг перетворення/повторення запиту провайдера → тест direct models - - баг pipeline Gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест Gateway -- Guardrail обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef із metadata registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec id відхиляються. - - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Додайте безпечну для CI регресію, якщо це можливо (mock/stub провайдера або фіксація точної трансформації форми запиту) +- Якщо проблема за своєю природою лише live (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env-змінні +- Віддавайте перевагу найменшому шару, який ловить помилку: + - помилка конвертації/повторного відтворення запиту провайдера → тест прямих моделей + - помилка pipeline gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway +- Guardrail для обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на кожен клас SecretRef з metadata реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec id відхиляються. + - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою для некласифікованих target id, щоб нові класи не могли бути тихо пропущені. diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index d103ac0ef..0138b832b 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,71 +1,73 @@ --- read_when: - Ви створюєте Plugin для OpenClaw - - Вам потрібно постачати схему конфігурації plugin або налагодити помилки валідації plugin -summary: Вимоги до маніфесту Plugin + JSON schema (сувора валідація конфігурації) + - Вам потрібно надати схему конфігурації plugin або налагодити помилки валідації plugin +summary: Вимоги до маніфесту Plugin + схеми JSON (сувора валідація конфігурації) title: Маніфест Plugin x-i18n: - generated_at: "2026-04-12T16:25:38Z" + generated_at: "2026-04-14T20:31:17Z" model: gpt-5.4 provider: openai - source_hash: 93b57c7373e4ccd521b10945346db67991543bd2bed4cc8b6641e1f215b48579 + source_hash: ba2183bfa8802871e4ef33a0ebea290606e8351e9e83e25ee72456addb768730 source_path: plugins/manifest.md workflow: 15 --- # Маніфест Plugin (`openclaw.plugin.json`) -Ця сторінка стосується лише **нативного маніфесту Plugin OpenClaw**. +Ця сторінка стосується лише **власного маніфесту Plugin OpenClaw**. -Сумісні макети пакетів описано тут: [Пакети Plugin](/uk/plugins/bundles). +Щоб дізнатися про сумісні макети bundle, див. [Пакети Plugin](/uk/plugins/bundles). -Сумісні формати пакетів використовують інші файли маніфесту: +Сумісні формати bundle використовують інші файли маніфесту: -- Пакет Codex: `.codex-plugin/plugin.json` -- Пакет Claude: `.claude-plugin/plugin.json` або типовий макет компонента Claude +- Codex bundle: `.codex-plugin/plugin.json` +- Claude bundle: `.claude-plugin/plugin.json` або стандартний макет компонента Claude без маніфесту -- Пакет Cursor: `.cursor-plugin/plugin.json` +- Cursor bundle: `.cursor-plugin/plugin.json` -OpenClaw також автоматично визначає ці макети пакетів, але вони не проходять валідацію +OpenClaw також автоматично виявляє ці макети bundle, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі читає метадані пакета, а також оголошені -корені skills, корені команд Claude, типові значення `settings.json` пакета Claude, -типові значення LSP пакета Claude та підтримувані набори хуків, якщо макет відповідає +Для сумісних bundle OpenClaw наразі читає метадані bundle, а також оголошені +кореневі каталоги skill, кореневі каталоги команд Claude, типові значення `settings.json` для bundle Claude, +типові значення LSP для bundle Claude та підтримувані набори hook, якщо макет відповідає очікуванням середовища виконання OpenClaw. -Кожен нативний Plugin OpenClaw **має** містити файл `openclaw.plugin.json` у +Кожен власний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у **корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації -**без виконання коду plugin**. Відсутні або недійсні маніфести вважаються +**без виконання коду plugin**. Відсутні або невалідні маніфести вважаються помилками plugin і блокують валідацію конфігурації. -Дивіться повний посібник по системі plugin: [Plugins](/uk/tools/plugin). -Щодо нативної моделі можливостей і поточних рекомендацій із зовнішньої сумісності: -[Модель можливостей](/uk/plugins/architecture#public-capability-model). +Див. повний посібник із системи Plugin: [Plugins](/uk/tools/plugin). +Для власної моделі capability і поточних рекомендацій щодо зовнішньої сумісності: +[Модель capability](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw читає перед завантаженням коду вашого -plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw читає до завантаження коду +вашого plugin. Використовуйте його для: -- ідентичності plugin +- ідентифікації plugin - валідації конфігурації - метаданих автентифікації та онбордингу, які мають бути доступні без запуску середовища виконання plugin -- недорогих підказок активації, які поверхні площини керування можуть перевіряти до +- легких підказок активації, які поверхні площини керування можуть перевіряти до завантаження середовища виконання -- недорогих дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до +- легких дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до завантаження середовища виконання -- метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження середовища виконання plugin -- скорочених метаданих належності до сімейств моделей, які мають автоматично активувати +- метаданих псевдонімів та автоувімкнення, які мають визначатися до завантаження середовища виконання plugin +- скорочених метаданих належності до сімейства моделей, які мають автоматично активувати plugin до завантаження середовища виконання -- статичних знімків належності можливостей, які використовуються для вбудованої сумісної прив’язки та +- статичних знімків належності capability, що використовуються для bundled wiring сумісності та покриття контрактів -- метаданих конфігурації для конкретних каналів, які мають об’єднуватися в поверхні каталогу та валідації +- легких метаданих виконувача QA, які спільний хост `openclaw qa` може перевіряти + до завантаження середовища виконання plugin +- метаданих конфігурації, специфічних для channel, які мають об’єднуватися з поверхнями каталогу та валідації без завантаження середовища виконання -- підказок інтерфейсу для конфігурації +- підказок UI для конфігурації Не використовуйте його для: @@ -73,7 +75,7 @@ plugin. - оголошення точок входу коду - метаданих встановлення npm -Це належить коду вашого plugin і `package.json`. +Це належить вашому коду plugin і `package.json`. ## Мінімальний приклад @@ -94,7 +96,7 @@ plugin. { "id": "openrouter", "name": "OpenRouter", - "description": "Plugin провайдера OpenRouter", + "description": "OpenRouter provider plugin", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -115,19 +117,19 @@ plugin. "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "Ключ API OpenRouter", + "choiceLabel": "OpenRouter API key", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "Ключ API OpenRouter", + "cliDescription": "OpenRouter API key", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "Ключ API", + "label": "API key", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -146,61 +148,62 @@ plugin. ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що воно означає | +| Поле | Обов’язкове | Тип | Що це означає | | ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | Так | `string` | Канонічний id plugin. Це id, що використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього plugin. | -| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Пропустіть це поле або вкажіть будь-яке значення, відмінне від `true`, щоб plugin залишався вимкненим за замовчуванням. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які мають автоматично вмикати цей plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип plugin, що використовується в `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Id каналів, якими володіє цей plugin. Використовується для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Id провайдерів, якими володіє цей plugin. | -| `modelSupport` | Ні | `object` | Скорочені метадані сімейств моделей, що належать маніфесту та використовуються для автозавантаження plugin до запуску середовища виконання. | -| `cliBackends` | Ні | `string[]` | Id backend CLI, якими володіє цей plugin. Використовується для автоактивації під час запуску на основі явних посилань у конфігурації. | -| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей plugin і які мають формувати діагностику конфігурації та CLI з урахуванням plugin до завантаження середовища виконання. | -| `providerAuthEnvVars` | Ні | `Record` | Недорогі метадані змінних середовища автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду plugin. | -| `providerAuthAliases` | Ні | `Record` | Id провайдерів, які мають повторно використовувати інший id провайдера для пошуку автентифікації, наприклад провайдер кодування, який спільно використовує базовий ключ API провайдера та профілі автентифікації. | -| `channelEnvVars` | Ні | `Record` | Недорогі метадані змінних середовища каналу, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для поверхонь налаштування або автентифікації каналу через змінні середовища, які мають бачити типові допоміжні засоби запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення бажаного провайдера та простого зв’язування прапорців CLI. | -| `activation` | Ні | `object` | Недорогі підказки активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливостями. Лише метадані; фактичною поведінкою як і раніше володіє середовище виконання plugin. | -| `setup` | Ні | `object` | Недорогі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання plugin. | -| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і належності інструментів. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналів, що належать маніфесту та об’єднуються в поверхні виявлення й валідації до завантаження середовища виконання. | +| `id` | Так | `string` | Канонічний ідентифікатор plugin. Це ідентифікатор, який використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована схема JSON для конфігурації цього plugin. | +| `enabledByDefault` | Ні | `true` | Позначає bundled plugin як увімкнений типово. Не вказуйте його або задайте будь-яке значення, відмінне від `true`, щоб plugin залишався вимкненим типово. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори provider, які мають автоматично вмикати цей plugin, коли автентифікація, конфігурація або посилання на модель згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип plugin, який використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Ідентифікатори channel, що належать цьому plugin. Використовуються для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Ідентифікатори provider, що належать цьому plugin. | +| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту та використовуються для автозавантаження plugin до середовища виконання. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI, що належать цьому plugin. Використовуються для автоактивації під час запуску з явних посилань у конфігурації. | +| `commandAliases` | Ні | `object[]` | Імена команд, що належать цьому plugin і мають формувати діагностику конфігурації та CLI з урахуванням plugin до завантаження середовища виконання. | +| `providerAuthEnvVars` | Ні | `Record` | Легкі метадані змінних середовища для автентифікації provider, які OpenClaw може перевіряти без завантаження коду plugin. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори provider, які мають повторно використовувати інший ідентифікатор provider для пошуку автентифікації, наприклад provider для кодування, що спільно використовує API key та профілі автентифікації базового provider. | +| `channelEnvVars` | Ні | `Record` | Легкі метадані змінних середовища для channel, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для поверхонь налаштування або автентифікації channel на основі змінних середовища, які мають бачити загальні допоміжні засоби запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для засобів вибору в онбордингу, визначення бажаного provider та простого зв’язування прапорців CLI. | +| `activation` | Ні | `object` | Легкі підказки активації для завантаження, яке запускається provider, командою, channel, маршрутом і capability. Лише метадані; фактична поведінка, як і раніше, належить середовищу виконання plugin. | +| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання plugin. | +| `qaRunners` | Ні | `object[]` | Легкі дескриптори виконувачів QA, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання plugin. | +| `contracts` | Ні | `object` | Статичний bundled-знімок capability для speech, транскрибування в реальному часі, голосу в реальному часі, media-understanding, генерації зображень, генерації музики, генерації відео, web-fetch, web search і належності tools. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації channel, що належать маніфесту та об’єднуються з поверхнями виявлення й валідації до завантаження середовища виконання. | | `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. | -| `name` | Ні | `string` | Зрозуміла для людини назва plugin. | -| `description` | Ні | `string` | Короткий опис, який показується в поверхнях plugin. | +| `name` | Ні | `string` | Зрозуміла людині назва plugin. | +| `description` | Ні | `string` | Короткий опис, що показується на поверхнях plugin. | | `version` | Ні | `string` | Інформаційна версія plugin. | -| `uiHints` | Ні | `Record` | Мітки інтерфейсу, заповнювачі та підказки чутливості для полів конфігурації. | +| `uiHints` | Ні | `Record` | Підписи UI, заповнювачі та підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. -OpenClaw читає це до завантаження середовища виконання провайдера. +OpenClaw читає це до завантаження середовища виконання provider. -| Поле | Обов’язкове | Тип | Що воно означає | -| --------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Id провайдера, до якого належить цей варіант. | -| `method` | Так | `string` | Id методу автентифікації, до якого треба спрямувати запит. | -| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, що використовується в потоках онбордингу та CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо її пропущено, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих асистентом. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із засобів вибору асистента, але все одно дозволяє ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів на цей варіант-заміну. | -| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | -| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо пропущено, типово це `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що це означає | +| -------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор provider, якому належить цей варіант. | +| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід спрямувати. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується онбордингом і потоками CLI. | +| `choiceLabel` | Ні | `string` | Підпис для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих assistant. | +| `assistantVisibility`| Ні | `"visible"` \| `"manual-only"` | Приховує варіант із засобів вибору assistant, але все ще дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds`| Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів до цього варіанта-замінника. | +| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Підпис цієї групи для користувача. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, за замовчуванням це `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли Plugin володіє назвою команди середовища виконання, яку користувачі можуть -помилково додати до `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw +Використовуйте `commandAliases`, коли plugin володіє назвою команди середовища виконання, яку користувачі можуть +помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду середовища виконання plugin. ```json @@ -215,22 +218,45 @@ OpenClaw читає це до завантаження середовища ви } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------------ | -| `name` | Так | `string` | Назва команди, що належить цьому plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід підказати для операцій CLI, якщо є. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------ | ----------- | ----------------- | -------------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, яка належить цьому plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо вона існує. | ## Довідник `activation` Використовуйте `activation`, коли plugin може недорого оголосити, які події площини керування мають активувати його пізніше. -Цей блок містить лише метадані. Він не реєструє поведінку середовища виконання і не -замінює `register(...)`, `setupEntry` чи інші точки входу runtime/plugin. +## Довідник `qaRunners` + +Використовуйте `qaRunners`, коли plugin додає один або кілька виконувачів транспорту в межах +спільного кореня `openclaw qa`. Зберігайте ці метадані легкими й статичними; середовище виконання plugin +як і раніше відповідає за фактичну реєстрацію CLI через легку +поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. + +```json +{ + "qaRunners": [ + { + "commandName": "matrix", + "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver" + } + ] +} +``` + +| Поле | Обов’язкове | Тип | Що це означає | +| ------------- | ----------- | -------- | ---------------------------------------------------------------------- | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. | + +Цей блок — лише метадані. Він не реєструє поведінку середовища виконання і +не замінює `register(...)`, `setupEntry` або інші точки входу середовища виконання/plugin. Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням plugin, тому -відсутність метаданих активації зазвичай впливає лише на продуктивність; вона не повинна -змінювати коректність, доки все ще існують застарілі резервні варіанти володіння через маніфест. +відсутність метаданих активації зазвичай впливає лише на продуктивність; це не має +змінювати коректність, доки все ще існують застарілі резервні механізми володіння маніфестом. ```json { @@ -244,28 +270,28 @@ OpenClaw читає це до завантаження середовища ви } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ---------------- | ----------- | ---------------------------------------------------- | ---------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Id провайдерів, які мають активувати цей plugin за запитом. | -| `onCommands` | Ні | `string[]` | Id команд, які мають активувати цей plugin. | -| `onChannels` | Ні | `string[]` | Id каналів, які мають активувати цей plugin. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей plugin. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються для планування активації площини керування. | +| Поле | Обов’язкове | Тип | Що це означає | +| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Ідентифікатори provider, які мають активувати цей plugin за запитом. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають активувати цей plugin. | +| `onChannels` | Ні | `string[]` | Ідентифікатори channel, які мають активувати цей plugin. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей plugin. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки capability, що використовуються для планування активації площини керування. | Поточні активні споживачі: -- планування CLI, що запускається командою, використовує резервний варіант +- планування CLI, що запускається командою, використовує застарілий резервний механізм `commandAliases[].cliCommand` або `commandAliases[].name` -- планування налаштування/каналу, що запускається каналом, використовує резервний варіант застарілого володіння - `channels[]`, якщо явні метадані активації каналу відсутні -- планування налаштування/runtime, що запускається провайдером, використовує резервний варіант застарілого - володіння `providers[]` і верхньорівневого `cliBackends[]`, якщо явні метадані активації провайдера - відсутні +- планування налаштування/channel, що запускається channel, використовує застарілий резервний механізм належності + `channels[]`, коли явні метадані активації channel відсутні +- планування налаштування/середовища виконання, що запускається provider, використовує застарілий резервний механізм + `providers[]` і належності верхньорівневих `cliBackends[]`, коли явні метадані + активації provider відсутні ## Довідник `setup` -Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні недорогі метадані plugin -до завантаження runtime. +Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні недорогі метадані plugin, якими він володіє, +до завантаження середовища виконання. ```json { @@ -284,36 +310,37 @@ OpenClaw читає це до завантаження середовища ви } ``` -Верхньорівневий `cliBackends` залишається дійсним і надалі описує backend CLI для inference. -`setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків -площини керування/setup, які мають залишатися лише метаданими. +Верхньорівневе `cliBackends` залишається валідним і, як і раніше, описує backend-и +інференсу CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, +для потоків площини керування/setup, яка має залишатися лише метаданими. -Якщо `setup.providers` і `setup.cliBackends` присутні, вони є бажаною -поверхнею пошуку setup за принципом «спочатку дескриптор» для виявлення setup. Якщо дескриптор лише -звужує кандидатний plugin, а setup усе ще потребує багатших runtime-хуків під час setup, -встановіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. +За наявності `setup.providers` і `setup.cliBackends` є бажаною поверхнею пошуку +для виявлення setup на основі дескрипторів. Якщо дескриптор лише звужує коло +потенційних plugin, а setup все ще потребує багатших hook середовища виконання під час setup, +установіть `requiresRuntime: true` і залиште `setup-api` як +резервний шлях виконання. Оскільки пошук setup може виконувати код plugin `setup-api`, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед -виявлених plugin. Неоднозначне володіння завершується безпечною відмовою замість вибору +виявлених plugin. Неоднозначна належність завершується безпечною відмовою, а не вибором переможця за порядком виявлення. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------- | -| `id` | Так | `string` | Id провайдера, доступний під час setup або онбордингу. Зберігайте нормалізовані id глобально унікальними. | -| `authMethods` | Ні | `string[]` | Id методів setup/автентифікації, які цей провайдер підтримує без завантаження повного runtime. | -| `envVars` | Ні | `string[]` | Змінні середовища, які типові поверхні setup/status можуть перевіряти до завантаження runtime plugin. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Ідентифікатор provider, який надається під час setup або онбордингу. Підтримуйте глобальну унікальність нормалізованих ідентифікаторів. | +| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей provider підтримує без завантаження повного середовища виконання. | +| `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні setup/status можуть перевіряти до завантаження середовища виконання plugin. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------ | -| `providers` | Ні | `object[]` | Дескриптори setup провайдера, доступні під час setup та онбордингу. | -| `cliBackends` | Ні | `string[]` | Id backend часу setup, що використовуються для пошуку setup за принципом «спочатку дескриптор». Зберігайте нормалізовані id глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє поверхня setup цього plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори setup provider, доступні під час setup та онбордингу. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend-ів на етапі setup, що використовуються для пошуку setup на основі дескрипторів. Підтримуйте глобальну унікальність нормалізованих ідентифікаторів. | +| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. | ## Довідник `uiHints` @@ -334,19 +361,19 @@ OpenClaw читає це до завантаження середовища ви Кожна підказка поля може містити: -| Поле | Тип | Що воно означає | +| Поле | Тип | Що це означає | | ------------- | ---------- | -------------------------------------- | -| `label` | `string` | Мітка поля для користувача. | +| `label` | `string` | Підпис поля для користувача. | | `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові теги інтерфейсу. | +| `tags` | `string[]` | Необов’язкові теги UI. | | `advanced` | `boolean` | Позначає поле як розширене. | | `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | | `placeholder` | `string` | Текст-заповнювач для полів форми. | ## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може -читати без імпорту runtime plugin. +Використовуйте `contracts` лише для статичних метаданих належності capability, які OpenClaw може +читати без імпорту середовища виконання plugin. ```json { @@ -364,24 +391,24 @@ OpenClaw читає це до завантаження середовища ви } ``` -Кожен список є необов’язковим: +Кожен список необов’язковий: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | --------------------------------------------------------- | -| `speechProviders` | `string[]` | Id speech-провайдерів, якими володіє цей plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів транскрипції в реальному часі, якими володіє цей plugin. | -| `realtimeVoiceProviders` | `string[]` | Id voice-провайдерів у реальному часі, якими володіє цей plugin. | -| `mediaUnderstandingProviders` | `string[]` | Id провайдерів розуміння медіа, якими володіє цей plugin. | -| `imageGenerationProviders` | `string[]` | Id провайдерів генерації зображень, якими володіє цей plugin. | -| `videoGenerationProviders` | `string[]` | Id провайдерів генерації відео, якими володіє цей plugin. | -| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей plugin. | -| `webSearchProviders` | `string[]` | Id провайдерів web search, якими володіє цей plugin. | -| `tools` | `string[]` | Назви інструментів агента, якими володіє цей plugin, для перевірок вбудованих контрактів. | +| Поле | Тип | Що це означає | +| -------------------------------- | ---------- | ----------------------------------------------------------- | +| `speechProviders` | `string[]` | Ідентифікатори speech provider, якими володіє цей plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори provider транскрибування в реальному часі, якими володіє цей plugin. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори provider голосу в реальному часі, якими володіє цей plugin. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори provider media-understanding, якими володіє цей plugin. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори provider генерації зображень, якими володіє цей plugin. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори provider генерації відео, якими володіє цей plugin. | +| `webFetchProviders` | `string[]` | Ідентифікатори provider web-fetch, якими володіє цей plugin. | +| `webSearchProviders` | `string[]` | Ідентифікатори provider web search, якими володіє цей plugin. | +| `tools` | `string[]` | Назви tool агента, якими володіє цей plugin, для bundled-перевірок контрактів. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли channel plugin потребує недорогих метаданих конфігурації до -завантаження runtime. +Використовуйте `channelConfigs`, коли channel plugin потребує недорогих метаданих конфігурації +до завантаження середовища виконання. ```json { @@ -401,27 +428,28 @@ OpenClaw читає це до завантаження середовища ви } }, "label": "Matrix", - "description": "Підключення до homeserver Matrix", + "description": "Matrix homeserver connection", "preferOver": ["matrix-legacy"] } } } ``` -Кожен запис каналу може містити: +Кожен запис channel може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові мітки інтерфейсу/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, що об’єднується в поверхні вибору та інспекції, коли метадані runtime ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь інспекції та каталогу. | -| `preferOver` | `string[]` | Id застарілих plugin або plugin з нижчим пріоритетом, які цей канал має випереджати на поверхнях вибору. | +| Поле | Тип | Що це означає | +| ------------- | ------------------------ | -------------------------------------------------------------------------------------------- | +| `schema` | `object` | Схема JSON для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації channel. | +| `uiHints` | `Record` | Необов’язкові підписи UI/заповнювачі/підказки чутливості для цього розділу конфігурації channel. | +| `label` | `string` | Підпис channel, що об’єднується з поверхнями вибору та інспектування, коли метадані середовища виконання ще не готові. | +| `description` | `string` | Короткий опис channel для поверхонь інспектування та каталогу. | +| `preferOver` | `string[]` | Ідентифікатори застарілих plugin або plugin із нижчим пріоритетом, які цей channel має перевершувати на поверхнях вибору. | ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має визначати ваш provider plugin на основі -скорочених id моделей, як-от `gpt-5.4` або `claude-sonnet-4.6`, до завантаження runtime plugin. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш provider plugin із +скорочених ідентифікаторів моделей, таких як `gpt-5.4` або `claude-sonnet-4.6`, до завантаження +середовища виконання plugin. ```json { @@ -434,74 +462,73 @@ OpenClaw читає це до завантаження середовища ви OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers`, що визначають власника +- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать власнику - `modelPatterns` мають пріоритет над `modelPrefixes` -- якщо збігаються один невбудований plugin і один вбудований plugin, перемагає невбудований +- якщо збігаються один небудований plugin і один bundled plugin, перемагає небудований plugin -- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкаже провайдера +- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкажуть provider Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | -------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, що звіряються через `startsWith` зі скороченими id моделей. | -| `modelPatterns` | `string[]` | Джерела regex, що звіряються зі скороченими id моделей після видалення суфікса профілю. | +| Поле | Тип | Що це означає | +| --------------- | ---------- | ------------------------------------------------------------------------------------ | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | -Застарілі ключі можливостей верхнього рівня більше не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб -перенести `speechProviders`, `realtimeTranscriptionProviders`, +Застарілі ключі capability верхнього рівня не рекомендовані. Використовуйте `openclaw doctor --fix`, щоб +перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` до `contracts`; звичайне завантаження маніфесту більше не трактує ці поля верхнього рівня як -належність можливостей. +належність capability. -## Маніфест у порівнянні з package.json +## Маніфест і `package.json` -Ці два файли виконують різні завдання: +Ці два файли виконують різні ролі: -| Файл | Для чого його використовувати | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки інтерфейсу, які мають існувати до запуску коду plugin | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, обмежень встановлення, setup або метаданих каталогу | +| Файл | Для чого використовувати | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду plugin | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, обмежень установлення, setup або метаданих каталогу | Якщо ви не впевнені, куди має належати певний фрагмент метаданих, користуйтеся таким правилом: - якщо OpenClaw має знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json` - якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, помістіть це в `package.json` -### Поля `package.json`, що впливають на виявлення +### Поля `package.json`, які впливають на виявлення -Частина метаданих plugin до runtime навмисно зберігається в `package.json` у блоці +Деякі метадані plugin до середовища виконання навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує нативні точки входу plugin. | -| `openclaw.setupEntry` | Легка точка входу лише для setup, що використовується під час онбордингу та відкладеного запуску каналів. | -| `openclaw.channel` | Недорогі метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. | -| `openclaw.channel.configuredState` | Недорогі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного runtime каналу. | -| `openclaw.channel.persistedAuthState` | Недорогі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного runtime каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих plugin. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із semver-нижньою межею на кшталт `>=2026.3.22`. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого plugin, коли конфігурація недійсна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналів лише для setup завантажуватися до повного channel plugin під час запуску. | +| Поле | Що це означає | +| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Оголошує власні точки входу plugin. | +| `openclaw.setupEntry` | Легка точка входу лише для setup, що використовується під час онбордингу та відкладеного запуску channel. | +| `openclaw.channel` | Легкі метадані каталогу channel, як-от підписи, шляхи до документації, псевдоніми та текст для вибору. | +| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує setup лише через env?» без завантаження повного середовища виконання channel. | +| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже є хоч один вхід у систему?» без завантаження повного середовища виконання channel. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення bundled plugin і plugin, опублікованих зовнішньо. | +| `openclaw.install.defaultChoice` | Бажаний шлях установлення, коли доступно кілька джерел установлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення bundled plugin, коли конфігурація невалідна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного channel plugin під час запуску. | -`openclaw.install.minHostVersion` перевіряється під час встановлення та завантаження -реєстру маніфестів. Недійсні значення відхиляються; новіші, але коректні значення пропускають +`openclaw.install.minHostVersion` застосовується під час установлення та завантаження +реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають plugin на старіших хостах. `openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке застосування. Воно -не робить довільно зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє -потокам встановлення відновлюватися після конкретних застарілих збоїв оновлення вбудованих plugin, наприклад -відсутнього шляху до вбудованого plugin або застарілого запису `channels.` для цього самого -вбудованого plugin. Непов’язані помилки конфігурації й далі блокують встановлення та спрямовують +не робить довільні зламані конфігурації придатними для встановлення. Наразі воно лише дозволяє +потокам установлення відновлюватися після певних застарілих збоїв оновлення bundled plugin, наприклад +відсутнього шляху bundled plugin або застарілого запису `channels.` для того самого +bundled plugin. Непов’язані помилки конфігурації все одно блокують установлення та спрямовують операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного -модуля перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для невеликого модуля перевірки: ```json { @@ -517,11 +544,12 @@ plugin на старіших хостах. } ``` -Використовуйте це, коли потоки setup, doctor або configured-state потребують недорогої перевірки -автентифікації типу так/ні до завантаження повного channel plugin. Цільовий експорт має бути невеликою -функцією, яка читає лише збережений стан; не спрямовуйте її через повний barrel runtime каналу. +Використовуйте це, коли потокам setup, doctor або configured-state потрібна недорога +перевірка автентифікації з відповіддю так/ні до завантаження повного channel plugin. Цільовий +експорт має бути невеликою функцією, яка читає лише збережений стан; не спрямовуйте її через повний +barrel середовища виконання channel. -`openclaw.channel.configuredState` використовує таку саму форму для недорогих перевірок +`openclaw.channel.configuredState` має таку саму форму для недорогих перевірок налаштованого стану лише через env: ```json @@ -538,64 +566,65 @@ plugin на старіших хостах. } ``` -Використовуйте це, коли канал може визначити налаштований стан через env або інші невеликі -входи без runtime. Якщо перевірка потребує повного визначення конфігурації або реального -runtime каналу, залиште цю логіку у хуку plugin `config.hasConfiguredState`. +Використовуйте це, коли channel може визначити налаштований стан із env або інших невеликих +вхідних даних поза середовищем виконання. Якщо перевірка потребує повного розв’язання конфігурації або реального +середовища виконання channel, натомість залишайте цю логіку в hook `config.hasConfiguredState` +plugin. -## Вимоги до JSON Schema +## Вимоги до схеми JSON -- **Кожен plugin має постачати JSON Schema**, навіть якщо він не приймає конфігурацію. -- Порожня схема є прийнятною (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми проходять валідацію під час читання/запису конфігурації, а не під час runtime. +- **Кожен plugin повинен постачатися зі схемою JSON**, навіть якщо він не приймає жодної конфігурації. +- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми проходять валідацію під час читання/запису конфігурації, а не під час виконання. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошено +- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор channel не оголошено в маніфесті plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - мають посилатися на **виявлювані** id plugin. Невідомі id є **помилками**. -- Якщо plugin встановлено, але його маніфест або схема пошкоджені чи відсутні, - валідація завершується помилкою, а Doctor повідомляє про помилку plugin. -- Якщо конфігурація plugin існує, але plugin **вимкнений**, конфігурація зберігається, і - в Doctor + логах з’являється **попередження**. + повинні посилатися на **виявлювані** ідентифікатори plugin. Невідомі ідентифікатори є **помилками**. +- Якщо plugin установлено, але він має зламаний або відсутній маніфест чи схему, + валідація завершується помилкою, і Doctor повідомляє про помилку plugin. +- Якщо конфігурація plugin існує, але plugin **вимкнено**, конфігурація зберігається, і + у Doctor + журналах з’являється **попередження**. -Повну схему `plugins.*` дивіться в [Довіднику з конфігурації](/uk/gateway/configuration). +Див. [Довідник із конфігурації](/uk/gateway/configuration), щоб переглянути повну схему `plugins.*`. ## Примітки -- Маніфест **обов’язковий для нативних Plugin OpenClaw**, зокрема для завантажень із локальної файлової системи. -- Runtime, як і раніше, завантажує модуль plugin окремо; маніфест використовується лише для - виявлення + валідації. -- Нативні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та - ключі без лапок допускаються, якщо кінцеве значення все ще є об’єктом. +- Маніфест **обов’язковий для власних Plugin OpenClaw**, зокрема для завантаження з локальної файлової системи. +- Середовище виконання все одно завантажує модуль plugin окремо; маніфест призначений лише для + виявлення та валідації. +- Власні маніфести розбираються за допомогою JSON5, тому коментарі, коми в кінці списку та + ключі без лапок допускаються, якщо кінцеве значення все одно залишається об’єктом. - Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання - власних ключів верхнього рівня тут. + власних ключів верхнього рівня сюди. - `providerAuthEnvVars` — це недорогий шлях метаданих для перевірок автентифікації, валідації - env-маркерів і подібних поверхонь автентифікації провайдерів, які не повинні запускати runtime plugin - лише для перевірки імен env. -- `providerAuthAliases` дозволяє варіантам провайдера повторно використовувати змінні середовища - автентифікації іншого провайдера, профілі автентифікації, автентифікацію на основі конфігурації та - варіант онбордингу з ключем API без жорсткого кодування цього зв’язку в core. -- `channelEnvVars` — це недорогий шлях метаданих для резервного використання shell-env, підказок setup - і подібних поверхонь каналів, які не повинні запускати runtime plugin - лише для перевірки імен env. + маркерів env і подібних поверхонь автентифікації provider, які не повинні запускати + середовище виконання plugin лише для перевірки назв env. +- `providerAuthAliases` дає змогу варіантам provider повторно використовувати змінні середовища автентифікації, + профілі автентифікації, автентифікацію на основі конфігурації та варіант онбордингу + з API key іншого provider без жорсткого кодування цього зв’язку в core. +- `channelEnvVars` — це недорогий шлях метаданих для резервного використання env оболонки, підказок + setup і подібних поверхонь channel, які не повинні запускати середовище виконання plugin + лише для перевірки назв env. - `providerAuthChoices` — це недорогий шлях метаданих для засобів вибору варіантів автентифікації, - визначення `--auth-choice`, мапінгу бажаного провайдера та простої реєстрації прапорців CLI - для онбордингу до завантаження runtime провайдера. Для метаданих wizard у runtime, - які потребують коду провайдера, див. - [Хуки runtime провайдера](/uk/plugins/architecture#provider-runtime-hooks). + розв’язання `--auth-choice`, зіставлення бажаного provider і простої реєстрації + прапорців CLI для онбордингу до завантаження середовища виконання provider. Для метаданих + майстра середовища виконання, що потребують коду provider, див. + [Hook середовища виконання provider](/uk/plugins/architecture#provider-runtime-hooks). - Ексклюзивні типи plugin вибираються через `plugins.slots.*`. - `kind: "memory"` вибирається через `plugins.slots.memory`. - `kind: "context-engine"` вибирається через `plugins.slots.contextEngine` (типово: вбудований `legacy`). -- `channels`, `providers`, `cliBackends` і `skills` можна пропустити, якщо +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо plugin їх не потребує. -- Якщо ваш plugin залежить від нативних модулів, задокументуйте кроки збірки та всі +- Якщо ваш plugin залежить від власних модулів, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` - `pnpm rebuild `). -## Пов’язані матеріали +## Пов’язане - [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з plugins - [Архітектура Plugin](/uk/plugins/architecture) — внутрішня архітектура -- [Огляд SDK](/uk/plugins/sdk-overview) — довідник по SDK Plugin +- [Огляд SDK](/uk/plugins/sdk-overview) — довідник із SDK Plugin