diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index faa2f4722..aad49bc0a 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,29 +1,29 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресій для багів моделі/провайдера - - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: набори unit/e2e/live, Docker runners і що покриває кожен тест' + - Додавання регресійних тестів для багів моделей/провайдерів + - Налагодження поведінки Gateway та агентів +summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-23T06:44:47Z" + generated_at: "2026-04-23T07:42:08Z" model: gpt-5.4 provider: openai - source_hash: 6cb3c7e0644b66e5ca8bce51ec52e874ac8c1dfe02193afa3b34d5e6b5e8a355 + source_hash: a92e9d1cd0ff64aabfbc28b42045aa6c63159375ff41695805488b40280e1b43 source_path: help/testing.md workflow: 15 --- # Тестування -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker runners. +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ — посібник «як ми тестуємо»: -- Що покриває кожен набір (і що він навмисно _не_ покриває) -- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) -- Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресії для реальних проблем моделей/провайдерів +- Що охоплює кожен набір (і що він навмисно _не_ охоплює) +- Які команди запускати для типових робочих процесів (локально, перед push, налагодження) +- Як live-тести знаходять облікові дані й вибирають моделі/провайдерів +- Як додавати регресійні тести для реальних проблем із моделями/провайдерами ## Швидкий старт @@ -31,11 +31,11 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` - Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` -- Прямий цикл watch для Vitest: `pnpm test:watch` +- Прямий цикл спостереження Vitest: `pnpm test:watch` - Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Під час ітерацій над однією помилкою спочатку віддавайте перевагу цільовим запускам. -- QA site на базі Docker: `pnpm qa:lab:up` -- QA lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Якщо ви працюєте над однією помилкою, спочатку віддавайте перевагу цільовим запускам. +- QA-сайт на базі Docker: `pnpm qa:lab:up` +- QA-lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` Коли ви змінюєте тести або хочете більше впевненості: @@ -44,121 +44,130 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + gateway probes для інструментів/зображень): `pnpm test:live` +- Live-набір (моделі + gateway-перевірки tool/image): `pnpm test:live` - Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Cost smoke для Moonshot/Kimi: із заданим `MOONSHOT_API_KEY` виконайте +- Docker live-перевірка моделей: `pnpm test:docker:live-models` + - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні + `OpenClaw Release Checks` обидва викликають повторно використовуваний live/E2E workflow з + `include_live_suites: true`, який включає окремі Docker live model + matrix jobs, шардовані за провайдером. + - Додайте нові high-signal secrets провайдерів до `scripts/ci-hydrate-live-auth.sh` + а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його + scheduled/release викликачів. +- Перевірка вартості Moonshot/Kimi: коли встановлено `MOONSHOT_API_KEY`, виконайте `openclaw models list --provider moonshot --json`, а потім ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - для `moonshot/kimi-k2.6`. Переконайтеся, що JSON показує Moonshot/K2.6, а - transcript асистента зберігає нормалізований `usage.cost`. + для `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє про Moonshot/K2.6 і що + transcript помічника зберігає нормалізоване `usage.cost`. -Порада: коли вам потрібен лише один збійний випадок, звужуйте live-тести через env-змінні allowlist, описані нижче. +Порада: коли вам потрібен лише один проблемний випадок, віддавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. -## QA-орієнтовані runners +## QA-специфічні ранери -Ці команди використовуються поряд з основними тестовими наборами, коли вам потрібен реалізм qa-lab: +Ці команди розташовані поруч з основними тестовими наборами, коли вам потрібен реалізм qa-lab: -CI запускає QA Lab в окремих workflows. `Parity gate` запускається для відповідних PR і -через ручний запуск із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на -`main` і через ручний запуск із mock parity gate, live Matrix lane і -live Telegram lane під керуванням Convex як паралельні jobs. `OpenClaw Release Checks` -запускає ті самі lanes перед схваленням release. +CI запускає QA Lab в окремих workflow. `Parity gate` запускається на відповідних PR +і через manual dispatch із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і через manual dispatch із mock parity gate, live Matrix lane та +Convex-керованим live Telegram lane як паралельними jobs. `OpenClaw Release Checks` +запускає ті самі lanes перед затвердженням релізу. - `pnpm openclaw qa suite` - - Запускає сценарії QA з репозиторію безпосередньо на хості. + - Запускає QA-сценарії з репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - gateway workers. `qa-channel` за замовчуванням має concurrency 4 (обмежується - кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати - кількість workers, або `--concurrency 1` для старішого serial lane. - - Завершується з ненульовим кодом, якщо будь-який сценарій не вдався. Використовуйте `--allow-failures`, коли + gateway-воркерами. `qa-channel` за замовчуванням має concurrency 4 (обмежену + кількістю вибраних сценаріїв). Використовуйте `--concurrency ` для налаштування кількості + воркерів або `--concurrency 1` для старішого послідовного lane. + - Повертає ненульовий код, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, коли вам потрібні артефакти без коду завершення з помилкою. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття через fixture і protocol-mock без заміни сценарно-орієнтованого + покриття фікстур і protocol-mock без заміни сценарно-орієнтованого lane `mock-openai`. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий набір QA всередині тимчасової Linux VM Multipass. + - Запускає той самий QA-набір усередині тимчасової Multipass Linux VM. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски пересилають підтримувані входи автентифікації QA, які практично - використовувати в гостьовій системі: - ключі провайдерів через env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, якщо він заданий. - - Каталоги виводу мають залишатися під коренем репозиторію, щоб гостьова система могла записувати назад через - змонтований workspace. - - Записує звичайний звіт QA + summary, а також журнали Multipass у + - Live-запуски передають підтримувані QA-входи автентифікації, які практичні для гостьової системи: + ключі провайдерів через env, шлях до конфігурації QA live provider і + `CODEX_HOME`, якщо він присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гість міг записувати назад через + змонтоване робоче середовище. + - Записує стандартний QA report + summary, а також логи Multipass до `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA site на базі Docker для операторського QA. + - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. - `pnpm test:docker:npm-onboard-channel-agent` - - Збирає npm tarball із поточного checkout, встановлює його глобально в - Docker, запускає неінтерактивний onboarding з ключем OpenAI API, налаштовує Telegram - за замовчуванням, перевіряє, що ввімкнення plugin встановлює runtime-залежності за потреби, - запускає doctor і виконує один локальний хід агента проти змоканого endpoint OpenAI. + - Збирає npm tarball з поточного checkout, глобально встановлює його в + Docker, виконує неінтерактивний onboarding з API-ключем OpenAI, налаштовує Telegram + за замовчуванням, перевіряє, що ввімкнення plugin встановлює залежності runtime на вимогу, + запускає doctor і виконує один локальний хід агента проти змоканого + endpoint OpenAI. - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий - lane пакетованого встановлення з Discord. + lane пакетного встановлення з Discord. - `pnpm test:docker:bundled-channel-deps` - - Пакує та встановлює поточний build OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає вбудовані channel/plugins через редагування конфігурації. - - Перевіряє, що виявлення налаштування залишає runtime-залежності не налаштованих - plugin відсутніми, перший налаштований запуск Gateway або doctor встановлює runtime-залежності - кожного вбудованого plugin за потреби, а другий перезапуск не перевстановлює - залежності, які вже були активовані. - - Також встановлює відому старішу npm baseline, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що - post-update doctor кандидата відновлює runtime-залежності вбудованих каналів без - додаткового postinstall-виправлення з боку harness. + - Пакує й встановлює поточну збірку OpenClaw у Docker, запускає Gateway + з налаштованим OpenAI, а потім вмикає bundled channel/plugins через редагування + конфігурації. + - Перевіряє, що виявлення налаштування залишає відсутніми залежності runtime + неконфігурованих plugin, що перший налаштований запуск Gateway або doctor встановлює + залежності runtime кожного bundled plugin на вимогу, і що другий перезапуск не + перевстановлює залежності, які вже були активовані. + - Також встановлює відомий старіший npm baseline, вмикає Telegram перед запуском + `openclaw update --tag `, і перевіряє, що doctor після оновлення в + candidate відновлює bundled channel runtime dependencies без післявстановлювального + виправлення з боку harness. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямого protocol smoke - testing. + - Запускає лише локальний сервер провайдера AIMock для прямої перевірки протоколу. - `pnpm openclaw qa matrix` - - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на базі Docker. - - Цей QA host сьогодні доступний лише для repo/dev. Пакетовані встановлення OpenClaw не постачають + - Запускає Matrix live QA lane проти тимчасового homeserver Tuwunel на базі Docker. + - Цей QA-хост наразі призначений лише для репозиторію/розробки. Пакетні встановлення OpenClaw не постачають `qa-lab`, тому вони не надають `openclaw qa`. - - Checkout репозиторію завантажують вбудований runner безпосередньо; окремий крок встановлення plugin не потрібен. - - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway з реальним plugin Matrix як транспортом SUT. - - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. - - Matrix не надає спільних прапорців джерела облікових даних, оскільки lane локально створює тимчасових користувачів. - - Записує звіт Matrix QA, summary, артефакт observed-events і комбінований журнал stdout/stderr у `.artifacts/qa-e2e/...`. + - Checkout-и репозиторію завантажують bundled runner безпосередньо; окремий крок встановлення plugin не потрібен. + - Надає три тимчасові користувачі Matrix (`driver`, `sut`, `observer`) та одну приватну кімнату, а потім запускає дочірній QA gateway із реальним Matrix plugin як транспортом SUT. + - За замовчуванням використовує закріплений стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. + - Matrix не надає спільних прапорців джерела облікових даних, тому що lane локально створює тимчасових користувачів. + - Записує Matrix QA report, summary, артефакт observed-events та комбінований лог stdout/stderr до `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени driver і SUT bot з env. - - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим ідентифікатором чату Telegram. - - Підтримує `--credential-source convex` для спільних пулованих облікових даних. Типово використовуйте режим env або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. - - Завершується з ненульовим кодом, якщо будь-який сценарій не вдався. Використовуйте `--allow-failures`, коли + - Запускає Telegram live QA lane проти реальної приватної групи з використанням токенів driver і SUT bot з env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. + - Підтримує `--credential-source convex` для спільних пулових облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. + - Повертає ненульовий код, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, коли вам потрібні артефакти без коду завершення з помилкою. - - Потребує двох різних bot в одній приватній групі, при цьому bot SUT має мати username Telegram. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode в `@BotFather` для обох bot і переконайтеся, що driver bot може спостерігати bot-трафік у групі. - - Записує звіт Telegram QA, summary і артефакт observed-messages у `.artifacts/qa-e2e/...`. + - Потребує двох різних ботів у тій самій приватній групі, причому бот SUT має мати Telegram username. + - Для стабільного bot-to-bot спостереження увімкніть режим Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що bot driver може спостерігати за трафіком ботів у групі. + - Записує Telegram QA report, summary і артефакт observed-messages до `.artifacts/qa-e2e/...`. -Live transport lanes використовують один стандартний контракт, щоб нові транспорти не дрейфували: +Live transport lanes використовують один стандартний контракт, щоб нові транспорти не розходилися: -`qa-channel` залишається широким синтетичним набором QA і не входить до матриці покриття live transport. +`qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live transport. -| Lane | Canary | Обмеження за згадуванням | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальші дії в гілці | Ізоляція гілок | Спостереження за реакціями | Команда help | -| -------- | ------ | ------------------------ | -------------------- | ------------------------- | ----------------------------- | -------------------- | -------------- | -------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Фільтрація за згадками | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у треді | Ізоляція тредів | Спостереження за реакціями | Команда help | +| -------- | ------ | ---------------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | --------------- | -------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -### Спільні облікові дані Telegram через Convex (v1) +### Спільні Telegram-облікові дані через Convex (v1) -Коли для -`openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивну lease із пулу на базі Convex, надсилає Heartbeat -для цієї lease під час роботи lane і звільняє lease під час завершення. +Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), +QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat цієї +оренди, поки lane працює, і звільняє оренду під час завершення роботи. -Шаблон референсного проєкту Convex: +Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові env-змінні: +Обов’язкові змінні середовища: - `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) -- Один секрет для вибраної ролі: +- Один secret для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Типове значення через env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) + - Типове значення з env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) -Необов’язкові env-змінні: +Необов’язкові змінні середовища: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) @@ -166,14 +175,14 @@ 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 `http://` Convex URL для локальної розробки. -`OPENCLAW_QA_CONVEX_SITE_URL` у звичайній роботі має використовувати `https://`. +У звичайному режимі `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. -Адміністративні команди maintainer (додати/видалити/перелічити пул) потребують +Адміністративні команди maintainer (додавання/видалення/перелік пулу) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-хелпери для maintainer: +Допоміжні CLI-команди для maintainer: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -181,7 +190,7 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `--json` для машинозчитуваного виводу в скриптах і CI utilities. +Використовуйте `--json` для машиночитаного виводу в скриптах і утилітах CI. Контракт endpoint за замовчуванням (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): @@ -195,38 +204,38 @@ pnpm openclaw qa credentials remove --credential-id - `POST /release` - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Успіх: `{ status: "ok" }` (або порожній `2xx`) -- `POST /admin/add` (лише секрет maintainer) +- `POST /admin/add` (лише secret maintainer) - Запит: `{ kind, actorId, payload, note?, status? }` - Успіх: `{ status: "ok", credential }` -- `POST /admin/remove` (лише секрет maintainer) +- `POST /admin/remove` (лише secret maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активної lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (лише секрет maintainer) + - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (лише secret maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` Форма payload для типу Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути числовим рядком ідентифікатора чату Telegram. +- `groupId` має бути рядком із числовим Telegram chat id. - `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректний payload. ### Додавання каналу до QA -Додавання каналу до markdown-системи QA потребує рівно двох речей: +Щоб додати канал до markdown QA system, потрібні рівно дві речі: -1. Транспортний адаптер для каналу. -2. Набір сценаріїв, який перевіряє контракт каналу. +1. Адаптер транспорту для каналу. +2. Пакет сценаріїв, який перевіряє контракт каналу. -Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний host `qa-lab` -може керувати цим процесом. +Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може +керувати цим процесом. -`qa-lab` відповідає за спільну механіку host: +`qa-lab` відповідає за спільні механізми хоста: -- кореневий простір команд `openclaw qa` -- запуск і завершення suite -- concurrency workers +- кореневу команду `openclaw qa` +- запуск і завершення наборів +- паралелізм воркерів - запис артефактів - генерацію звітів - виконання сценаріїв @@ -237,30 +246,30 @@ Runner plugins відповідають за транспортний контр - як `openclaw qa ` монтується під спільним коренем `qa` - як Gateway налаштовується для цього транспорту - як перевіряється готовність -- як інжектуються вхідні події +- як інжектяться вхідні події - як спостерігаються вихідні повідомлення -- як надаються transcript і нормалізований стан транспорту -- як виконуються дії, прив’язані до транспорту -- як обробляється специфічний для транспорту reset або cleanup +- як надаються transcript-и та нормалізований стан транспорту +- як виконуються дії, підкріплені транспортом +- як обробляється транспортно-специфічний reset або cleanup -Мінімальний поріг для впровадження нового каналу: +Мінімальний поріг прийняття для нового каналу: 1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте transport runner на спільному шві host `qa-lab`. -3. Тримайте специфічну для транспорту механіку всередині runner plugin або harness каналу. -4. Монтуйте runner як `openclaw qa `, а не реєструйте конкуруючий кореневий command. - Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. - Тримайте `runtime-api.ts` легким; lazy CLI і виконання runner мають залишатися за окремими entrypoint. -5. Пишіть або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте generic helper для нових сценаріїв. -7. Зберігайте працездатність наявних compatibility alias, якщо репозиторій не виконує навмисну міграцію. +2. Реалізуйте transport runner на спільному seam хоста `qa-lab`. +3. Залишайте транспортно-специфічні механізми всередині runner plugin або harness каналу. +4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. + Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. + Тримайте `runtime-api.ts` легким; лінивий CLI і виконання runner мають залишатися за окремими entrypoint. +5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. +6. Використовуйте generic helpers для нових сценаріїв. +7. Зберігайте працездатність наявних aliases сумісності, якщо тільки в репозиторії не виконується навмисна міграція. -Правило ухвалення рішення є суворим: +Правило прийняття рішення суворе: -- Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного channel transport, тримайте її в цьому runner plugin або plugin harness. +- Якщо поведінку можна виразити один раз у `qa-lab`, розміщуйте її в `qa-lab`. +- Якщо поведінка залежить від одного транспорту каналу, залишайте її в цьому runner plugin або plugin harness. - Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте generic helper замість channel-specific branch у `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно зазначайте це в контракті сценарію. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій транспортно-специфічним і явно фіксуйте це в контракті сценарію. Бажані назви generic helper для нових сценаріїв: @@ -277,7 +286,7 @@ Runner plugins відповідають за транспортний контр - `formatTransportTranscript` - `resetTransport` -Compatibility alias залишаються доступними для наявних сценаріїв, зокрема: +Aliases сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -285,263 +294,263 @@ Compatibility alias залишаються доступними для наяв - `formatConversationTranscript` - `resetBus` -Нова робота над каналами має використовувати generic helper names. -Compatibility alias існують, щоб уникнути одноразової міграції, а не як модель для -написання нових сценаріїв. +Нова робота над каналами має використовувати generic назви helper. +Aliases сумісності існують, щоб уникнути міграції типу flag day, а не як модель для +створення нових сценаріїв. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): +Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): ### Unit / integration (типово) - Команда: `pnpm test` - Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) поверх наявних scoped Vitest projects -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, що покриваються `vitest.unit.config.ts` +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, які охоплює `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - In-process integration-тести (gateway auth, routing, tooling, parsing, config) - Детерміновані регресії для відомих багів - Очікування: - - Запускаються в CI - - Не потребують реальних ключів - - Мають бути швидкими та стабільними -- Примітка щодо projects: - - Ненацілений `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` усе ще використовує native root graph проєктів `vitest.config.ts`, тому що multi-shard watch loop непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні target файлу/каталогу через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test files; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. - - `pnpm check:changed` — це типовий smart local gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни публічного Plugin SDK і plugin-contract включають валідацію extensions, тому що extensions залежать від цих core contracts. Оновлення версії лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни package поза полем version верхнього рівня. - - Import-light unit-тести з agents, commands, plugins, auto-reply helpers, `plugin-sdk` та подібних чистих utility-областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy files залишаються на наявних lanes. - - Вибрані helper source files `plugin-sdk` і `commands` також зіставляють запуски changed-mode з явними sibling tests у цих light lanes, тому редагування helper уникають повторного запуску повного важкого набору для цього каталогу. - - `auto-reply` тепер має три окремі bucket: top-level core helpers, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це не дозволяє найважчій роботі harness для reply потрапляти на дешеві тести status/chunk/token. -- Примітка щодо embedded runner: - - Коли ви змінюєте входи виявлення message-tool або runtime-контекст compaction, + - Запускається в CI + - Реальні ключі не потрібні + - Має бути швидким і стабільним +- Примітка про projects: + - Ненацілений `pnpm test` тепер запускає одинадцять менших shard-конфігів (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project процесу. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати нерелевантні набори. + - `pnpm test --watch` усе ще використовує native root `vitest.config.ts` project graph, тому що multi-shard цикл watch непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` не платить повну ціну запуску root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test файлів; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. + - `pnpm check:changed` — це стандартний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни в public Plugin SDK і plugin-contract включають валідацію extensions, тому що extensions залежать від цих core-контрактів. Version bump-и лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни package поза полем version верхнього рівня. + - Імпорт-легкі unit-тести з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` та подібних чистих утилітних зон маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. + - Вибрані вихідні helper-файли `plugin-sdk` і `commands` також зіставляють запуски в changed-mode з явними sibling tests у цих легких lanes, щоб редагування helper-ів не спричиняли повторний запуск усього важкого набору для цього каталогу. + - `auto-reply` тепер має три виділені bucket-и: helper-и core верхнього рівня, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі reply harness потрапляти до дешевих тестів status/chunk/token. +- Примітка про embedded runner: + - Коли ви змінюєте вхідні дані виявлення message-tool або runtime context для compaction, зберігайте обидва рівні покриття. - Додавайте сфокусовані helper-регресії для чистих меж routing/normalization. - - Також підтримуйте здоровими embedded runner integration-набори: + - Також підтримуйте здоровими 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 досі проходять + - Ці набори перевіряють, що scoped id і поведінка Compaction як і раніше проходять через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є достатньою заміною для цих integration-шляхів. -- Примітка щодо pool: +- Примітка про pool: - Базова конфігурація Vitest тепер типово використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner в root projects, e2e і live configs. - - Кореневий lane UI зберігає своє налаштування `jsdom` та optimizer, але тепер також працює на спільному non-isolated runner. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e та live configs. + - Кореневий lane UI зберігає своє налаштування `jsdom` і optimizer, але тепер теж працює на спільному non-isolated runner. - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-process Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. -- Примітка щодо швидкої локальної ітерації: + - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. +- Примітка про швидку локальну ітерацію: - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. - - Pre-commit hook запускає `pnpm check:changed --staged` після staged formatting/linting, тому commits лише для core не оплачують вартість extension tests, якщо не торкаються публічних extension-facing contracts. Commits лише з release metadata залишаються на цільовому lane version/config/root-dependency. - - Якщо точний staged-набір змін уже було перевірено рівними або сильнішими gate, використовуйте `scripts/committer --fast "" `, щоб пропустити лише повторний changed-scope hook. Staged format/lint усе одно запускаються. Згадайте виконані gate у handoff. Це також припустимо після повторного запуску ізольованого flaky hook failure, якщо він проходить із локальним підтвердженням. - - `pnpm test:changed` маршрутизується через scoped lanes, коли змінені шляхи чисто мапляться на менший набір. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом workers. - - Автомасштабування локальних workers тепер навмисно консервативне й також відступає, коли середнє навантаження хоста вже високе, тому кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски changed-mode лишалися коректними, коли змінюється wiring тестів. - - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію cache для прямого profiling. -- Примітка щодо perf-debug: - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість import плюс вивід import-breakdown. - - `pnpm test:perf:imports:changed` обмежує той самий профільний перегляд файлами, зміненими від `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` із native root-project path для цього committed diff і виводить wall time плюс macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` вимірює поточне dirty tree, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root Vitest config. - - `pnpm test:perf:profile:main` записує CPU-profile головного потоку для overhead запуску й transform Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap profiles runner для unit-набору з вимкненим file parallelism. + - Pre-commit hook запускає `pnpm check:changed --staged` після staged formatting/linting, тому core-only commit-и не оплачують вартість тестів extensions, якщо не торкаються public extension-facing contracts. Commit-и лише з release metadata залишаються на цільовому lane version/config/root-dependency. + - Якщо точний staged-набір змін уже був перевірений рівними або сильнішими gates, використовуйте `scripts/committer --fast "" `, щоб пропустити лише повторний запуск changed-scope hook. Staged format/lint усе одно запускаються. Згадайте завершені gates у своєму handoff. Це також прийнятно після ізольованого flaky hook failure, який був повторно запущений і пройшов зі scoped proof. + - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи чисто зіставляються з меншим набором. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом воркерів. + - Автомасштабування локальних воркерів тепер навмисно консервативне й також знижує навантаження, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб rerun-и в changed-mode лишалися коректними, коли змінюється wiring тестів. + - Конфігурація залишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого profiling. +- Примітка про perf-debug: + - `pnpm test:perf:imports` вмикає звітність про тривалість імпорту у Vitest плюс вивід import-breakdown. + - `pnpm test:perf:imports:changed` обмежує той самий profiling view файлами, зміненими відносно `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 profile основного потоку для накладних витрат запуску та transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує CPU+heap profiles runner-а для unit-набору з вимкненим паралелізмом файлів. ### Стабільність (gateway) - Команда: `pnpm test:stability:gateway` -- Конфігурація: `vitest.gateway.config.ts`, примусово один worker +- Конфігурація: `vitest.gateway.config.ts`, примусово один воркер - Обсяг: - Запускає реальний loopback Gateway з діагностикою, увімкненою за замовчуванням - - Проганяє синтетичне churn для gateway message, memory і large-payload через діагностичний event path - - Опитує `diagnostics.stability` через Gateway WS RPC - - Покриває helper збереження diagnostic stability bundle - - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS залишаються в межах бюджету тиску, а глибини черг на рівні сесії повертаються до нуля + - Пропускає синтетичне churn повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій + - Виконує запити до `diagnostics.stability` через WS RPC Gateway + - Охоплює helper-и persistence для diagnostic stability bundle + - Перевіряє, що recorder лишається обмеженим, синтетичні вибірки RSS залишаються нижче бюджету тиску, а глибина черг для кожної сесії зменшується назад до нуля - Очікування: - - Безпечно для CI й без ключів - - Вузький lane для подальшої роботи над регресіями стабільності, а не заміна повному набору Gateway + - Безпечно для CI і без ключів + - Вузький lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести bundled-plugin у `extensions/` -- Типові параметри середовища виконання: - - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує adaptive workers (CI: до 2, локально: типово 1). - - За замовчуванням працює в silent mode, щоб зменшити накладні витрати на console I/O. +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і bundled-plugin E2E-тести в `extensions/` +- Типові налаштування runtime: + - Використовує `threads` Vitest з `isolate: false`, як і решта репозиторію. + - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість workers (обмежено 16). + - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість воркерів (не більше 16). - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - Поведінка multi-instance gateway end-to-end - - Поверхні WebSocket/HTTP, Node pairing і важчий networking + - Наскрізна поведінка multi-instance gateway + - Поверхні WebSocket/HTTP, pairing вузлів і важчий networking - Очікування: - - Запускається в CI (коли ввімкнено в pipeline) - - Не потребує реальних ключів - - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) + - Запускається в CI (коли увімкнено в pipeline) + - Реальні ключі не потрібні + - Більше рухомих частин, ніж в unit-тестах (може бути повільніше) -### E2E: smoke для backend OpenShell +### E2E: smoke OpenShell backend - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - Запускає ізольований Gateway OpenShell на хості через Docker - - Створює sandbox з тимчасового локального Dockerfile - - Перевіряє backend OpenShell у OpenClaw через реальні `sandbox ssh-config` + виконання через SSH - - Перевіряє remote-canonical поведінку файлової системи через bridge fs sandbox + - Створює sandbox із тимчасового локального Dockerfile + - Перевіряє OpenShell backend OpenClaw через реальні `sandbox ssh-config` + виконання SSH + - Верифікує remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і робочого Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox + - Потребує локального CLI `openshell` і працездатного Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує test gateway і sandbox - Корисні перевизначення: - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб указати нестандартний CLI binary або wrapper script + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний двійковий файл CLI або wrapper script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` -- Конфіг: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести вбудованих plugin у `extensions/` -- За замовчуванням: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) -- Область: - - «Чи справді цей provider/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявляти зміни формату provider, особливості виклику інструментів, проблеми автентифікації та поведінку обмежень швидкості +- Конфігурація: `vitest.live.config.ts` +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і bundled-plugin live-тести в `extensions/` +- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) +- Обсяг: + - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» + - Виявлення змін формату провайдера, особливостей tool calling, проблем автентифікації та поведінки rate limit - Очікування: - - Навмисно не стабільно для CI (реальні мережі, реальні політики provider, квоти, збої) - - Коштує грошей / витрачає ліміти запитів + - За задумом не є CI-стабільним (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / використовує rate limit - Краще запускати звужені підмножини, а не «все» - Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють конфіг/матеріали автентифікації в тимчасовий домашній каталог тесту, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють матеріали config/auth до тимчасового test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. - Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. -- Тепер `pnpm test:live` за замовчуванням працює в тихішому режимі: зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і заглушає логи запуску Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API-ключів (для конкретного provider): встановіть `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує bootstrap-логи Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. +- Ротація API-ключів (залежно від провайдера): встановлюйте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або override для live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спроби при відповідях із rate limit. - Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики provider помітно активні, навіть коли захоплення консолі Vitest тихе. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу provider/Gateway одразу транслювалися під час live-запусків. - - Налаштовуйте Heartbeat для прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat для Gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу в stderr, щоб під час довгих викликів провайдерів було видно, що виконання активне, навіть коли перехоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тому рядки прогресу провайдера/Gateway одразу транслюються під час live-запусків. + - Налаштовуйте Heartbeat direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? Використовуйте цю таблицю рішень: -- Редагуєте логіку/тести: запустіть `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Торкаєтесь мережевої взаємодії Gateway / WS-протоколу / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / збої конкретного provider / виклик інструментів: запустіть звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Торкаєтесь gateway networking / WS protocol / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / tool calling: запускайте звужений `pnpm test:live` ## Live: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, що наразі оголошена** підключеним Android Node, і перевірити поведінку контракту команд. -- Область: - - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає й не виконує pairing застосунку). - - Перевірка `node.invoke` Gateway команда за командою для вибраного Android Node. +- Мета: викликати **кожну команду, яку наразі оголошує** підключений Android Node, і перевірити поведінку контракту команди. +- Обсяг: + - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не pair-ить застосунок). + - Перевірка `node.invoke` Gateway по командах для вибраного Android Node. - Обов’язкове попереднє налаштування: - - Android-застосунок уже підключено й виконано pairing з Gateway. - - Застосунок має залишатися на передньому плані. - - Для можливостей, які ви очікуєте як успішні, мають бути надані дозволи/підтвердження захоплення. -- Необов’язкові перевизначення цілі: + - Android-застосунок уже підключений і спарений із 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: перевірка моделей (ключі профілю) +## Live: smoke моделей (ключі профілів) -Live-тести поділено на два рівні, щоб можна було ізолювати збої: +Live-тести поділено на два шари, щоб можна було ізолювати збої: -- «Пряма модель» показує, чи взагалі provider/модель може відповісти з наданим ключем. -- «Перевірка Gateway» показує, чи працює повний конвеєр Gateway+агента для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). +- «Direct model» показує нам, чи взагалі може відповісти провайдер/модель із наданим ключем. +- «Gateway smoke» показує нам, чи працює повний pipeline gateway+agent для цієї моделі (sessions, history, tools, sandbox policy тощо). -### Рівень 1: пряме завершення моделлю (без Gateway) +### Шар 1: Direct model completion (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Виконати невелике завершення для кожної моделі (і цільові регресійні перевірки там, де потрібно) + - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані + - Виконати невелике completion для кожної моделі (і цільові регресії там, де потрібно) - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб реально запустити цей набір; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на перевірці Gateway +- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше він пропускається, щоб `pnpm test:live` залишався сфокусованим на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern` для запуску сучасного allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` є псевдонімом для сучасного allowlist + - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Modern/all-перевірки за замовчуванням мають курований ліміт із високим сигналом; встановіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого ліміту. -- Як вибирати provider: + - Перевірки modern/all за замовчуванням обмежені curated high-signal cap; встановіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого обмеження. +- Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: зі сховища профілів і резервних env-значень - - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** + - За замовчуванням: profile store і fallback-и env + - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** - Навіщо це існує: - - Відокремлює «API provider зламаний / ключ недійсний» від «конвеєр агента Gateway зламаний» - - Містить невеликі ізольовані регресії (приклад: повторення reasoning у OpenAI Responses/Codex Responses + потоки виклику інструментів) + - Відокремлює «API провайдера зламане / ключ невалідний» від «pipeline gateway agent зламаний» + - Містить невеликі ізольовані регресії (наприклад: reasoning replay + tool-call flows для OpenAI Responses/Codex Responses) -### Рівень 2: перевірка Gateway + dev agent (те, що насправді робить "@openclaw") +### Шар 2: Gateway + smoke dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Підняти внутрішньопроцесний Gateway - - Створити/оновити сесію `agent:dev:*` (із перевизначенням моделі для кожного запуску) - - Перебрати моделі з ключами й перевірити: - - «змістовну» відповідь (без інструментів) - - що реальний виклик інструмента працює (read probe) - - необов’язкові додаткові перевірки інструментів (exec+read probe) - - що регресійні шляхи OpenAI (лише tool-call → подальший крок) продовжують працювати -- Подробиці probe (щоб ви могли швидко пояснювати збої): - - `read` probe: тест записує nonce-файл у робочу область і просить агента `read` його та повернути nonce. - - `exec+read` probe: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його через `read`. - - image probe: тест прикріплює згенерований PNG (кіт + рандомізований код) і очікує, що модель поверне `cat `. + - Підняти in-process gateway + - Створити/змінити session `agent:dev:*` (override моделі для кожного запуску) + - Перебрати models-with-keys і перевірити: + - «змістовну» відповідь (без tools) + - що працює реальний виклик tool (read probe) + - необов’язкові додаткові перевірки tool (exec+read probe) + - що шляхи регресії OpenAI (лише tool-call → follow-up) продовжують працювати +- Деталі probe (щоб ви могли швидко пояснити збої): + - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce назад. + - `exec+read` probe: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. + - image probe: тест прикріплює згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибирати моделі: - - За замовчуванням: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` є псевдонімом для сучасного allowlist + - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - Modern/all Gateway-перевірки за замовчуванням мають курований ліміт із високим сигналом; встановіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого ліміту. -- Як вибирати provider (уникайте «все через OpenRouter»): + - Перевірки modern/all для gateway за замовчуванням обмежені curated high-signal cap; встановіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншого обмеження. +- Як вибирати провайдерів (уникайте «усього OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Перевірки інструментів і зображень у цьому live-тесті завжди увімкнені: - - `read` probe + `exec+read` probe (навантаження інструментів) +- Перевірки tool + image у цьому live-тесті завжди увімкнені: + - `read` probe + `exec+read` probe (навантаження на tools) - image probe запускається, коли модель оголошує підтримку вхідних зображень - - Потік (на високому рівні): + - Потік (високий рівень): - Тест генерує маленький PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway розбирає вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Вбудований агент передає моделі мультимодальне повідомлення користувача - - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки допустимі) + - Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Embedded agent пересилає мультимодальне повідомлення користувача моделі + - Перевірка: відповідь містить `cat` + код (допуск OCR: невеликі помилки дозволені) -Порада: щоб побачити, що саме можна перевірити на вашій машині (і точні ідентифікатори `provider/model`), запустіть: +Порада: щоб побачити, що ви можете тестувати на своїй машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: перевірка CLI backend (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + агента з локальним CLI backend, не торкаючись вашого типового конфігу. -- Значення за замовчуванням для перевірки конкретного backend зберігаються у визначенні `cli-backend.ts` plugin-власника. +- Мета: перевірити pipeline Gateway + agent, використовуючи локальний CLI backend, не торкаючись вашої типової конфігурації. +- Типові значення smoke для backend, специфічні для конкретного backend, зберігаються у визначенні `cli-backend.ts` відповідного extension. - Увімкнення: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Значення за замовчуванням: - - Provider/модель за замовчуванням: `claude-cli/claude-sonnet-4-6` - - Команда/аргументи/поведінка зображень беруться з метаданих plugin-власника CLI backend. -- Перевизначення (необов’язкові): +- Типові значення: + - Типовий provider/model: `claude-cli/claude-sonnet-4-6` + - Поведінка command/args/image береться з метаданих 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`, щоб надіслати реальне вкладення-зображення (шляхи впроваджуються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість впровадження в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати передаванням аргументів зображень, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік відновлення. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності тієї самої сесії 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`, щоб надіслати другий хід і перевірити flow відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності в тій самій session Claude Sonnet -> Opus (встановіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -557,7 +566,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` -Рецепти Docker для одного provider: +Рецепти Docker для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude @@ -568,30 +577,30 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Засіб запуску Docker розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live-перевірку CLI-backend усередині Docker-образу репозиторію як непривілейований користувач `node`. -- Він визначає метадані перевірки CLI з plugin-власника, а потім встановлює відповідний Linux CLI-пакет (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає переносну OAuth-автентифікацію підписки Claude Code через `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім виконує два ходи Gateway CLI-backend без збереження змінних середовища ключа Anthropic API. Цей шлях підписки за замовчуванням вимикає перевірки інструмента Claude MCP та зображень, оскільки Claude наразі маршрутизує використання сторонніх застосунків через додаткову оплату замість звичайних лімітів плану підписки. -- Live-перевірка CLI-backend тепер виконує однаковий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через Gateway CLI. -- Типова перевірка Claude також оновлює сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає ранішу нотатку. +- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію від непривілейованого користувача `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` потребує переносної Claude Code subscription OAuth через `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він доводить, що прямий `claude -p` у Docker працює, а потім запускає два ходи Gateway CLI-backend без збереження змінних середовища API-ключа Anthropic. Цей subscription lane за замовчуванням вимикає перевірки Claude MCP/tool та image, тому що Claude наразі маршрутизує використання сторонніх застосунків через додаткове білінг-споживання замість звичайних лімітів плану subscription. +- Live smoke CLI-backend тепер перевіряє той самий end-to-end flow для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик tool `cron` через MCP, перевірений через gateway CLI. +- Типовий smoke Claude також змінює session із Sonnet на Opus і перевіряє, що відновлена session усе ще пам’ятає попередню нотатку. -## Live: перевірка прив’язки ACP (`/acp spawn ... --bind here`) +## Live: ACP bind smoke (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік прив’язки ACP-розмови з live ACP-агентом: +- Мета: перевірити реальний flow conversation-bind ACP із live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну розмову каналу повідомлень на місці - - надіслати звичайне подальше повідомлення в тій самій розмові - - перевірити, що подальше повідомлення потрапляє в transcript прив’язаної ACP-сесії + - прив’язати на місці синтетичну conversation каналу повідомлень + - надіслати звичайний 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` - - Синтетичний канал: контекст розмови у стилі Slack DM + - Синтетичний канал: контекст 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` @@ -599,8 +608,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.4` - Примітки: - - Цей шлях використовує поверхню Gateway `chat.send` з синтетичними полями originating-route лише для адміністратора, щоб тести могли прикріплювати контекст каналу повідомлень без імітації зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP-агента обв’язки. + - Цей lane використовує поверхню gateway `chat.send` з admin-only synthetic полями originating-route, щоб тести могли додавати контекст message-channel без імітації зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness agent. Приклад: @@ -626,35 +635,35 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Засіб запуску Docker розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає перевірку ACP bind послідовно для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. +- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає ACP bind smoke послідовно для всіх підтримуваних live CLI agent: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він використовує `~/.profile`, переносить відповідні матеріали автентифікації CLI в контейнер, встановлює `acpx` у записуваний npm-префікс, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. -- Усередині Docker засіб запуску встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав змінні середовища provider із використаного `profile`, доступними для дочірнього CLI обв’язки. +- Він використовує `~/.profile`, переносить відповідні матеріали автентифікації CLI до контейнера, встановлює `acpx` у записуваний npm-префікс, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. +- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб `acpx` зберігав змінні середовища провайдера з підвантаженого profile доступними для дочірнього harness CLI. -## Live: перевірка обв’язки app-server Codex +## Live: smoke Codex app-server harness -- Мета: перевірити обв’язку Codex, що належить plugin, через звичайний метод - `agent` Gateway: - - завантажити вбудований plugin `codex` +- Мета: перевірити plugin-owned Codex harness через звичайний gateway + метод `agent`: + - завантажити bundled plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший хід агента Gateway до `codex/gpt-5.4` - - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що потік - app-server може відновитися - - виконати `/codex status` і `/codex models` через той самий шлях - команд Gateway - - за потреби виконати дві shell-перевірки з підвищеними правами, переглянуті Guardian: одну нешкідливу - команду, яку слід схвалити, і одне фальшиве - вивантаження секрету, яке слід заборонити, щоб агент перепитав + - надіслати перший хід gateway agent до `codex/gpt-5.4` + - надіслати другий хід до тієї самої session OpenClaw і перевірити, що app-server + thread може відновитися + - запустити `/codex status` і `/codex models` через той самий шлях + команди gateway + - за потреби запустити дві escalated shell-перевірки, перевірені Guardian: одну нешкідливу + команду, яку має бути схвалено, і одне фальшиве завантаження secret, + яке має бути відхилено, щоб агент перепитав - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` -- Модель за замовчуванням: `codex/gpt-5.4` -- Необов’язкова перевірка зображень: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Необов’язкова перевірка MCP/інструментів: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Необов’язкова перевірка Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Перевірка встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламана обв’язка Codex - не могла пройти, непомітно переключившись на PI. -- Автентифікація: `OPENAI_API_KEY` з shell/profile, плюс за потреби скопійовані +- Типова модель: `codex/gpt-5.4` +- Необов’язкова image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язкова MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Необов’язкова Guardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` +- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex + harness не міг пройти, тихо переключившись на PI. +- Auth: `OPENAI_API_KEY` із shell/profile, а також необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -678,29 +687,30 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Засіб запуску Docker розташований у `scripts/test-live-codex-harness-docker.sh`. +- Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. - Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли автентифікації Codex CLI, якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm - префікс, переносить дерево вихідного коду, а потім запускає лише live-тест обв’язки Codex. -- Docker за замовчуванням увімкнює перевірки зображення, MCP/інструментів і Guardian. Встановіть + префікс, переносить дерево джерел, а потім запускає лише live-тест Codex-harness. +- У Docker за замовчуванням увімкнено image, MCP/tool і Guardian probes. Встановіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` або - `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли вам потрібен вужчий запуск для налагодження. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, відповідно до конфігу live- - тесту, щоб fallback на `openai-codex/*` або PI не міг приховати регресію - обв’язки Codex. + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий налагоджувальний + запуск. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і live + test config, щоб fallback `openai-codex/*` або PI не міг приховати регресію + Codex harness. ### Рекомендовані live-рецепти -Вузькі, явні allowlist — найшвидші та найменш схильні до збоїв: +Вузькі явні allowlist — найшвидші й найменш нестабільні: -- Одна модель, напряму (без Gateway): +- Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Одна модель, перевірка Gateway: +- Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклик інструментів через кількох provider: +- 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 (API-ключ Gemini + Antigravity): @@ -710,21 +720,21 @@ pnpm test:docker:live-codex-harness Примітки: - `google/...` використовує Gemini API (API-ключ). -- `google-antigravity/...` використовує міст OAuth Antigravity (кінцева точка агента у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). +- `google-antigravity/...` використовує міст Antigravity OAuth (endpoint агента в стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості tooling). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений Google Gemini API через HTTP (API-ключ / автентифікація профілю); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує локальний бінарний файл `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/підтримка інструментів/розсинхрон версій). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (автентифікація через API-ключ / profile); саме це більшість користувачів мають на увазі під “Gemini”. + - CLI: OpenClaw викликає локальний двійковий файл `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/tool support/version skew). ## Live: матриця моделей (що ми покриваємо) -Фіксованого «списку моделей CI» немає (live — opt-in), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. +Фіксованого «списку моделей для CI» немає (live — opt-in), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. -### Сучасний набір для перевірки (виклик інструментів + зображення) +### Набір modern smoke (tool calling + image) -Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: +Це запуск «поширених моделей», який ми очікуємо підтримувати в робочому стані: -- 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) @@ -732,12 +742,12 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запускати перевірку Gateway з інструментами + зображенням: +Запуск gateway smoke з tools + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) +### Базовий рівень: tool calling (Read + необов’язковий Exec) -Виберіть щонайменше одну модель на сімейство provider: +Виберіть принаймні одну модель на сімейство провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -745,44 +755,44 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (було б добре мати): +Необов’язкове додаткове покриття (бажано мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас увімкнено) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою tools, яку у вас увімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) -- LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) +- LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) ### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте принаймні одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI-варіанти з підтримкою vision тощо), щоб перевірити image probe. +Додайте принаймні одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI-варіанти з підтримкою vision тощо), щоб задіяти image probe. -### Агрегатори / альтернативні Gateway +### Aggregators / альтернативні gateway Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою інструментів і зображень) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше provider, які можна включити в live-матрицю (якщо у вас є облікові дані/конфіг): +Інші провайдери, які можна включити до live matrix (якщо у вас є облікові дані/конфігурація): - Вбудовані: `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` (кастомні кінцеві точки): `minimax` (хмара/API), а також будь-який сумісний із OpenAI/Anthropic proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (custom endpoint): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко закодувати в документації «усі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс ті ключі, які доступні. +Порада: не намагайтеся жорстко закодувати в документації «усі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі. ## Облікові дані (ніколи не комітьте) -Live-тести знаходять облікові дані так само, як CLI. Практичні наслідки: +Live-тести виявляють облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести повинні знайти ті самі ключі. +- Якщо CLI працює, live-тести мають знаходити ті самі ключі. - Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в live-тестах означає «ключі профілю») -- Конфіг: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється в staged live home, якщо присутній, але це не основне сховище ключів профілю) -- Локальні live-запуски за замовчуванням копіюють активний конфіг, файли `auth-profiles.json` для кожного агента, застарілий каталог `credentials/` і підтримувані зовнішні каталоги автентифікації CLI в тимчасовий домашній каталог тесту; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` прибираються, щоб probe не торкалися вашої реальної робочої області хоста. +- Профілі автентифікації для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це у live-тестах означає “profile keys”) +- Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) +- Застарілий каталог стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище profile keys) +- Локальні live-запуски за замовчуванням копіюють активний config, файли `auth-profiles.json` для окремих агентів, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staged live homes пропускають `workspace/` і `sandboxes/`, а override-и шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не торкалися вашого реального host workspace. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте наведені нижче засоби запуску Docker (вони можуть монтувати `~/.profile` в контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). ## Live Deepgram (транскрибування аудіо) @@ -793,33 +803,33 @@ Live-тести знаходять облікові дані так само, я - Тест: `extensions/byteplus/live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` -- Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` +- Необов’язковий override моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live ComfyUI workflow media +## Live медіа workflow ComfyUI - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` -- Область: +- Обсяг: - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` - - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації plugin + - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` + - Корисно після змін у відправленні workflow comfy, polling, downloads або реєстрації plugin -## Live: генерація зображень +## Live генерація зображень - Тест: `test/image-generation.runtime.live.test.ts` - Команда: `pnpm test:live test/image-generation.runtime.live.test.ts` -- Обв’язка: `pnpm test:live:media image` -- Область: - - Перелічує кожен зареєстрований provider-plugin генерації зображень - - Завантажує відсутні env-змінні provider із вашого login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані з shell - - Пропускає provider без придатної автентифікації/профілю/моделі - - Запускає стандартні варіанти генерації зображень через спільну runtime-можливість: +- Harness: `pnpm test:live:media image` +- Обсяг: + - Перелічує кожен зареєстрований provider plugin для генерації зображень + - Завантажує відсутні змінні середовища провайдера з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API-ключі раніше за збережені auth profile, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатної auth/profile/model + - Проганяє стандартні варіанти генерації зображень через спільну runtime capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані provider, що покриваються: +- Поточні вбудовані провайдери, які покриваються: - `fal` - `google` - `minimax` @@ -830,290 +840,290 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,xai"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"` -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати override-и лише через env -## Live: генерація музики +## Live генерація музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` -- Обв’язка: `pnpm test:live:media music` -- Область: - - Перевіряє спільний шлях вбудованих provider генерації музики - - Наразі покриває Google і MiniMax - - Завантажує env-змінні provider із вашого login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані з shell - - Пропускає provider без придатної автентифікації/профілю/моделі - - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` із введенням лише prompt - - `edit`, коли provider оголошує `capabilities.edit.enabled` - - Поточне покриття спільного шляху: +- Harness: `pnpm test:live:media music` +- Обсяг: + - Перевіряє спільний шлях bundled provider для генерації музики + - Наразі охоплює Google і MiniMax + - Завантажує змінні середовища провайдера з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API-ключі раніше за збережені auth profile, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатної auth/profile/model + - Запускає обидва оголошені runtime modes, коли вони доступні: + - `generate` з вхідними даними лише prompt + - `edit`, коли провайдер оголошує `capabilities.edit.enabled` + - Поточне покриття в спільному lane: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, не ця спільна перевірка + - `comfy`: окремий live-файл Comfy, а не ця спільна перевірка - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати override-и лише через env -## Live: генерація відео +## Live генерація відео - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` -- Обв’язка: `pnpm test:live:media video` -- Область: - - Перевіряє спільний шлях вбудованих provider генерації відео - - За замовчуванням використовує безпечний для релізу шлях перевірки: provider не-FAL, один запит text-to-video на provider, prompt про лобстера на одну секунду та ліміт операції на provider з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) - - За замовчуванням пропускає FAL, оскільки затримка черги на стороні provider може домінувати над часом релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно - - Завантажує env-змінні provider із вашого login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані з shell - - Пропускає provider без придатної автентифікації/профілю/моделі +- Harness: `pnpm test:live:media video` +- Обсяг: + - Перевіряє спільний шлях bundled provider для генерації відео + - За замовчуванням використовує безпечний для релізу 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"`, щоб запустити його явно + - Завантажує змінні середовища провайдера з вашої login shell (`~/.profile`) перед перевіркою + - За замовчуванням використовує live/env API-ключі раніше за збережені auth profile, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатної auth/profile/model - За замовчуванням запускає лише `generate` - - Встановіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими трансформації, коли вони доступні: - - `imageToVideo`, коли provider оголошує `capabilities.imageToVideo.enabled` і вибраний provider/модель приймає локальне введення зображень із буфера у спільній перевірці - - `videoToVideo`, коли provider оголошує `capabilities.videoToVideo.enabled` і вибраний provider/модель приймає локальне введення відео з буфера у спільній перевірці - - Поточні provider `imageToVideo`, оголошені, але пропущені в спільній перевірці: - - `vydra`, тому що вбудований `veo3` підтримує лише text, а вбудований `kling` вимагає віддалений URL зображення - - Покриття Vydra для конкретного provider: + - Встановіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені transform modes, коли вони доступні: + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний provider/model приймає локальні вхідні зображення на основі buffer у спільній перевірці + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний provider/model приймає локальні вхідні відео на основі buffer у спільній перевірці + - Поточні провайдери `imageToVideo`, які оголошені, але пропускаються у спільній перевірці: + - `vydra`, тому що bundled `veo3` підтримує лише text, а bundled `kling` вимагає віддалений URL зображення + - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс шлях `kling`, який за замовчуванням використовує фікстуру віддаленого URL зображення + - цей файл запускає `veo3` text-to-video, а також lane `kling`, який за замовчуванням використовує фікстуру з віддаленим URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні provider `videoToVideo`, оголошені, але пропущені в спільній перевірці: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалені еталонні URL `http(s)` / MP4 - - `google`, тому що поточний спільний шлях Gemini/Veo використовує локальне введення з буфера, і цей шлях не приймається у спільній перевірці - - `openai`, тому що поточний спільний шлях не гарантує доступ до inpaint/remix відео, специфічний для org + - Поточні провайдери `videoToVideo`, які оголошені, але пропускаються у спільній перевірці: + - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалені reference URL `http(s)` / MP4 + - `google`, тому що поточний спільний lane Gemini/Veo використовує локальні вхідні дані на основі buffer, а цей шлях не приймається у спільній перевірці + - `openai`, тому що поточний спільний lane не має гарантій доступу до video inpaint/remix, специфічного для org - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного provider у перевірку за замовчуванням, включно з FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного provider під час агресивного smoke-запуску -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типової перевірки, включно з FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного провайдера під час агресивного smoke-запуску +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати override-и лише через env -## Обв’язка media live +## Harness для media live - Команда: `pnpm test:live:media` - Призначення: - Запускає спільні live-набори для зображень, музики та відео через один рідний для репозиторію entrypoint - - Автоматично завантажує відсутні env-змінні provider з `~/.profile` - - За замовчуванням автоматично звужує кожен набір до provider, які наразі мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і quiet-mode залишається узгодженою + - Автоматично завантажує відсутні змінні середовища провайдера з `~/.profile` + - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну auth + - Повторно використовує `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 (необов’язкові перевірки «працює в Linux») +## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці засоби запуску Docker поділяються на дві групи: +Ці Docker-ранери поділяються на дві групи: -- Засоби запуску live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише свій відповідний live-файл із ключами профілю всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог конфігів і робочу область (і використовуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Засоби запуску Docker для live за замовчуванням використовують менший ліміт smoke, щоб повна перевірка Docker залишалася практичною: +- 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`), монтуючи ваш локальний каталог config і workspace (і використовуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Live Docker-ранери за замовчуванням використовують менший smoke cap, щоб повна Docker-перевірка лишалася практичною: `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли - ви явно хочете більшу вичерпну перевірку. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох live-шляхів Docker. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для контейнерних smoke-засобів запуску E2E, які перевіряють зібраний застосунок. -- Контейнерні smoke-засоби запуску: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли + вам навмисно потрібне більше вичерпне сканування. +- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох Docker lanes live. Він також збирає один спільний image `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для smoke-ранерів E2E у контейнері, які перевіряють зібраний застосунок. +- Ранери container smoke: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` піднімають один або кілька реальних контейнерів і перевіряють integration-шляхи вищого рівня. -Засоби запуску Docker для live-моделей також bind-mount лише потрібні домашні каталоги автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб зовнішній CLI OAuth міг оновлювати токени без зміни сховища автентифікації хоста: +Live-model Docker-ранери також bind-mount-ять лише потрібні домівки автентифікації CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб зовнішня CLI OAuth могла оновлювати токени без зміни сховища auth на хості: -- Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) +- Direct models: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) - ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- Перевірка CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Перевірка обв’язки app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke Codex app-server harness: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повне scaffold-налаштування): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Перевірка npm tarball onboarding/channel/agent: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding із посиланням на env і за замовчуванням Telegram, перевіряє, що ввімкнення plugin встановлює його runtime-залежності на вимогу, запускає doctor і виконує один змокований хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Мережа Gateway (два контейнери, автентифікація WS + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Мінімальна регресія reasoning для OpenAI Responses `web_search`: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змокований сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, а потім примусово викликає відхилення схеми provider і перевіряє, що необроблена деталь з’являється в логах Gateway. -- Міст каналу MCP (ініціалізований Gateway + міст stdio + raw smoke із кадрами сповіщень Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти MCP у комплекті Pi (реальний stdio MCP-сервер + вбудований smoke allow/deny профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення MCP Cron/subagent (реальний Gateway + завершення дочірнього stdio MCP після ізольованого cron і одноразових запусків subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (перевірка встановлення + псевдонім `/plugin` + семантика перезапуску комплекту Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -- Smoke-перевірка незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke-перевірка метаданих перезавантаження конфігу: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime-залежності вбудованого plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий образ Docker runner, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову на хості після свіжого локального білду через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. -- Звужуйте runtime-залежності вбудованого plugin під час ітерації, вимикаючи не пов’язані сценарії, наприклад: +- Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Smoke onboarding/channel/agent з npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding із посиланням на env плюс Telegram за замовчуванням, перевіряє, що ввімкнення plugin встановлює його runtime dependencies на вимогу, запускає doctor і виконує один хід змоканого агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, або перемикайте канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Gateway networking (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Мінімальна reasoning-регресія OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, а потім примусово відхиляє схему провайдера і перевіряє, що сирі деталі з’являються в логах Gateway. +- MCP channel bridge (seeded Gateway + stdio bridge + raw Claude smoke notification-frame): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Pi bundle MCP tools (реальний stdio MCP server + embedded smoke allow/deny профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Очищення Cron/subagent MCP (реальний Gateway + завершення дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (smoke встановлення + alias `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Smoke незмінності оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke метаданих перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime dependencies bundled plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий image Docker runner, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропускайте перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`, або вказуйте наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Під час ітерації звужуйте runtime dependencies bundled plugin, вимикаючи нерелевантні сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Щоб вручну попередньо зібрати й повторно використовувати спільний образ зібраного застосунку: +Щоб вручну попередньо зібрати і повторно використовувати спільний built-app image: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення образу для конкретного набору, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо їх установлено. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та інсталятора зберігають власні Dockerfile, оскільки вони перевіряють поведінку пакета/встановлення, а не спільний runtime зібраного застосунку. +Override-и image для конкретних наборів, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо їх установлено. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти витягують його, якщо його ще немає локально. Docker-тести QR та інсталятора зберігають власні Dockerfile, тому що вони перевіряють поведінку package/install, а не спільний built-app runtime. -Засоби запуску Docker для live-моделей також bind-mount поточний checkout лише для читання і -переносять його в тимчасову робочу директорію всередині контейнера. Це зберігає runtime- -образ компактним і водночас дає змогу запускати Vitest точно на вашому локальному source/config. -Крок перенесення пропускає великі локальні кеші та вихідні дані збирання застосунку, як-от +Live-model Docker-ранери також монтують поточний checkout лише для читання і +переносять його до тимчасового workdir усередині контейнера. Це зберігає runtime +image компактним, водночас дозволяючи запускати Vitest точно проти ваших локальних source/config. +Крок перенесення пропускає великі локальні кеші та результати збірки застосунків, такі як `.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні для застосунків каталоги `.build` або -виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -машинно-специфічних артефактів. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб Gateway live-probe не запускали -реальні воркери каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити Gateway -live-покриття з цього Docker-шляху. -`test:docker:openwebui` — це smoke-перевірка сумісності вищого рівня: вона запускає -контейнер Gateway OpenClaw з увімкненими HTTP-endpoint, сумісними з OpenAI, -запускає pinned-контейнер Open WebUI проти цього Gateway, виконує вхід через +виводу Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання +артефактів, специфічних для машини. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали +реальні channel-воркери Telegram/Discord тощо всередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway +live-покриття з цього Docker lane. +`test:docker:openwebui` — це compatibility smoke вищого рівня: він запускає +контейнер gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoint, +запускає pinned контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний запит чату через proxy Open WebUI `/api/chat/completions`. -Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися завантажити -образ Open WebUI, а самому Open WebUI — завершити власне cold-start-налаштування. -Цей шлях очікує придатний live-ключ моделі, а `OPENCLAW_PROFILE_FILE` -(`~/.profile` за замовчуванням) є основним способом надати його в Dockerized-запусках. -Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": +реальний chat-запит через proxy Open WebUI `/api/chat/completions`. +Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися витягнути +image Open WebUI, а Open WebUI може потребувати завершити власне cold-start налаштування. +Цей lane очікує придатний ключ live-моделі, і `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) — основний спосіб надати його в Dockerized-запусках. +Успішні запуски виводять невеликий JSON payload, наприклад `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає ініціалізований контейнер -Gateway, запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, -поведінку черги live-подій, маршрутизацію вихідних надсилань і сповіщення у стилі Claude про канали + -дозволи через реальний міст stdio MCP. Перевірка сповіщень -безпосередньо перевіряє сирі кадри stdio MCP, тож smoke-перевірка підтверджує те, що -міст реально випромінює, а не лише те, що випадково показує конкретний SDK клієнта. -`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує live-ключа -моделі. Він збирає Docker-образ репозиторію, запускає реальний probe-сервер stdio MCP -усередині контейнера, матеріалізує цей сервер через вбудований runtime MCP комплекту Pi, -виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають -інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. -`test:docker:cron-mcp-cleanup` є детермінованим і не потребує live-ключа -моделі. Він запускає ініціалізований Gateway з реальним probe-сервером stdio MCP, виконує +реального облікового запису Telegram, Discord чи iMessage. Він запускає seeded контейнер Gateway, +потім запускає другий контейнер, який породжує `openclaw mcp serve`, а далі +перевіряє виявлення маршрутизованих conversation, читання transcript, метадані вкладень, +поведінку черги live event, маршрутизацію outbound send і сповіщення каналу + +дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +безпосередньо аналізує сирі stdio MCP frames, тому smoke перевіряє те, що bridge +справді виводить, а не лише те, що випадково показує конкретний SDK клієнта. +`test:docker:pi-bundle-mcp-tools` детермінований і не потребує ключа live-моделі. +Він збирає Docker image репозиторію, запускає реальний stdio MCP probe server +усередині контейнера, матеріалізує цей сервер через embedded runtime Pi bundle +MCP, виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають +tools `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. +`test:docker:cron-mcp-cleanup` детермінований і не потребує ключа live-моделі. +Він запускає seeded Gateway з реальним stdio MCP probe server, виконує ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручна smoke-перевірка ACP plain-language thread (не для CI): +Ручний ACP smoke plain-language для thread (не для CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для регресійних/налагоджувальних сценаріїв. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. +- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки ACP thread routing, тому не видаляйте його. -Корисні 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_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, використані з `OPENCLAW_PROFILE_FILE`, із тимчасовими каталогами config/workspace і без монтування зовнішньої CLI-автентифікації -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`), монтується в `/home/node/.npm-global` для кешованих встановлень CLI всередині Docker -- Зовнішні каталоги/файли CLI-автентифікації в `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів +- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується до `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується до `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується до `/home/node/.profile` і використовується перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише змінні середовища, підвантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої CLI auth +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується до `/home/node/.npm-global` для кешованих встановлень CLI всередині Docker +- Зовнішні каталоги/файли CLI auth у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються до `/home/node/...` перед стартом тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски provider монтують лише потрібні каталоги/файли, визначені з `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=...`, щоб фільтрувати provider усередині контейнера -- `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-тег образу Open WebUI +- `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 -## Перевірка документації +## Перевірка коректності документації -Запускайте перевірки документації після редагування доків: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Після редагування документації запускайте перевірки docs: `pnpm check:docs`. +Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресія (безпечна для CI) +## Офлайн-регресії (безпечні для CI) -Це регресії «реального конвеєра» без реальних provider: +Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів Gateway (змокований OpenAI, реальний цикл Gateway + агента): `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 tool calling (змоканий OpenAI, реальний gateway + цикл agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Gateway wizard (WS `wizard.start`/`wizard.next`, запис config + обов’язкова auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") ## Оцінювання надійності агентів (Skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»: -- Змокований виклик інструментів через реальний цикл Gateway + агента (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють підключення сесії та вплив config (`src/gateway/gateway.test.ts`). +- Mock tool-calling через реальний gateway + цикл agent (`src/gateway/gateway.test.ts`). +- Наскрізні flow майстра, які перевіряють wiring сесій і ефекти config (`src/gateway/gateway.test.ts`). -Що для Skills усе ще відсутнє (див. [Skills](/uk/tools/skills)): +Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічено в prompt, чи обирає агент правильний Skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, що перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Вибір рішення:** коли Skills перелічено в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? +- **Відповідність:** чи читає агент `SKILL.md` перед використанням і чи дотримується потрібних кроків/аргументів? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок tools, перенесення history між сесіями та межі sandbox. -Майбутні оцінювання мають залишатися спершу детермінованими: +Майбутні eval-и мають спершу залишатися детермінованими: -- Засіб запуску сценаріїв із mock-provider для перевірки викликів інструментів + їхнього порядку, читання файлів Skill і підключення сесії. -- Невеликий набір сценаріїв, сфокусованих на Skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live-оцінювання (opt-in, з env-gating) лише після того, як безпечний для CI набір буде готовий. +- Ранер сценаріїв, який використовує mock-провайдери для перевірки викликів tools + їх порядку, читання skill-файлів і wiring сесій. +- Невеликий набір сценаріїв, зосереджених на Skills (використати чи уникнути, gate-умови, ін’єкція в prompt). +- Необов’язкові live eval-и (opt-in, із gate через env) лише після впровадження безпечного для CI набору. -## Контрактні тести (форма plugin і каналу) +## Контрактні тести (форма Plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований plugin і канал відповідає своєму -контракту інтерфейсу. Вони перебирають усі виявлені plugin і запускають набір -перевірок форми й поведінки. Типовий unit-шлях `pnpm test` навмисно +Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає +своєму інтерфейсному контракту. Вони перебирають усі виявлені plugins і запускають набір +перевірок форми та поведінки. Типовий unit lane `pnpm test` навмисно пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, -коли торкаєтеся спільних поверхонь каналів або provider. +коли торкаєтесь спільних поверхонь channel або provider. ### Команди - Усі контракти: `pnpm test:contracts` -- Лише контракти каналів: `pnpm test:contracts:channels` +- Лише контракти channel: `pnpm test:contracts:channels` - Лише контракти provider: `pnpm test:contracts:plugins` -### Контракти каналів +### Контракти channel Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Базова форма plugin (id, name, capabilities) - **setup** - Контракт майстра налаштування -- **session-binding** - Поведінка прив’язки сесії +- **session-binding** - Поведінка прив’язки session - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень -- **actions** - Обробники дій каналу +- **actions** - Обробники дій channel - **threading** - Обробка ID thread -- **directory** - API директорії/ростеру +- **directory** - API directory/roster - **group-policy** - Застосування групової політики ### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Probe перевірки статусу каналу -- **registry** - Форма реєстру plugin +- **status** - Перевірки статусу channel +- **registry** - Форма реєстру Plugin ### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір/добір автентифікації +- **auth** - Контракт flow автентифікації +- **auth-choice** - Вибір/selection автентифікації - **catalog** - API каталогу моделей -- **discovery** - Виявлення plugin -- **loader** - Завантаження plugin -- **runtime** - Runtime provider -- **shape** - Форма/інтерфейс plugin +- **discovery** - Виявлення Plugin +- **loader** - Завантаження Plugin +- **runtime** - Runtime провайдера +- **shape** - Форма/інтерфейс Plugin - **wizard** - Майстер налаштування ### Коли запускати -- Після зміни export або subpath у plugin-sdk -- Після додавання або зміни plugin каналу чи provider +- Після зміни export-ів або subpath-ів plugin-sdk +- Після додавання або зміни channel чи provider plugin - Після рефакторингу реєстрації або виявлення plugin Контрактні тести запускаються в CI й не потребують реальних API-ключів. -## Додавання регресій (настанови) +## Додавання регресійних тестів (рекомендації) -Коли ви виправляєте проблему provider/моделі, виявлену в live: +Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (змокайте/stub provider або зафіксуйте точне перетворення форми запиту) -- Якщо вона за своєю природою лише live (rate limit, політики автентифікації), тримайте live-тест вузьким і opt-in через env-змінні -- Намагайтеся націлюватися на найменший шар, який виявляє помилку: - - помилка перетворення/повтору запиту provider → тест прямих моделей - - помилка конвеєра сесії/історії/інструментів Gateway → live-перевірка Gateway або безпечний для CI mock-тест Gateway -- Захисне обмеження обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef із метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec-id сегментів обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою на некласифікованих target-id, щоб нові класи не могли бути тихо пропущені. +- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдера або фіксацію точної трансформації форми запиту) +- Якщо проблема за своєю природою лише live (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env vars +- Намагайтеся цілитися в найменший шар, який ловить баг: + - баг перетворення/повторення запиту провайдера → тест direct models + - баг pipeline gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway +- Захисний механізм обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить один вибірковий target на кожен клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec id відхиляються. + - Якщо ви додаєте нову сім’ю target-ів 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 337cacd26..13887785d 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,65 +1,81 @@ --- read_when: - - Ви створюєте плагін OpenClaw - - Вам потрібно постачати схему конфігурації плагіна або налагоджувати помилки валідації плагіна -summary: Вимоги до маніфесту Plugin + схеми JSON (сувора валідація конфігурації) + - Ви створюєте Plugin для OpenClaw + - Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin +summary: Вимоги до маніфесту Plugin і схеми JSON (сувора валідація конфігурації) title: Маніфест Plugin x-i18n: - generated_at: "2026-04-23T06:24:10Z" + generated_at: "2026-04-23T07:42:09Z" model: gpt-5.4 provider: openai - source_hash: de71b9d556c2696d3279f202b66d57aa8014e9c89d81e3f453602744120d1675 + source_hash: d48810f604aa0c3ff8553528cfa4cb735d1d5e7a15b1bbca6152070d6c8f9cce source_path: plugins/manifest.md workflow: 15 --- # Маніфест Plugin (`openclaw.plugin.json`) -Ця сторінка стосується лише **власного маніфесту плагіна OpenClaw**. +Ця сторінка стосується лише **власного маніфесту Plugin OpenClaw**. -Сумісні компонування пакетів описано в [Пакети Plugin](/uk/plugins/bundles). +Сумісні макети пакетів описано в [Пакети Plugin](/uk/plugins/bundles). Сумісні формати пакетів використовують інші файли маніфесту: - пакет Codex: `.codex-plugin/plugin.json` -- пакет Claude: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude без маніфесту +- пакет Claude: `.claude-plugin/plugin.json` або стандартний макет компонента Claude + без маніфесту - пакет Cursor: `.cursor-plugin/plugin.json` -OpenClaw також автоматично виявляє ці компонування пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. +OpenClaw також автоматично визначає ці макети пакетів, але вони не проходять валідацію +за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені корені skills, корені команд Claude, значення за замовчуванням `settings.json` пакета Claude, значення LSP за замовчуванням пакета Claude та підтримувані набори хуків, коли компонування відповідає очікуванням середовища виконання OpenClaw. +Для сумісних пакетів OpenClaw наразі зчитує метадані пакета разом з оголошеними +коренями Skills, коренями команд Claude, значеннями за замовчуванням `settings.json` у пакеті Claude, +значеннями LSP за замовчуванням у пакеті Claude та підтримуваними наборами хуків, коли макет відповідає +очікуванням середовища виконання OpenClaw. -Кожен власний плагін OpenClaw **повинен** містити файл `openclaw.plugin.json` у **корені плагіна**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду плагіна**. Відсутні або невалідні маніфести вважаються помилками плагіна й блокують валідацію конфігурації. +Кожен власний Plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у +**корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації +**без виконання коду Plugin**. Відсутні або невалідні маніфести вважаються +помилками Plugin і блокують валідацію конфігурації. -Повний посібник із системи плагінів див. у розділі [Plugins](/uk/tools/plugin). -Для власної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності: +Дивіться повний посібник із системи Plugin: [Plugins](/uk/tools/plugin). +Щодо власної моделі можливостей і поточних рекомендацій із зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw зчитує перед завантаженням коду вашого плагіна. +`openclaw.plugin.json` — це метадані, які OpenClaw зчитує перед завантаженням коду +вашого Plugin. Використовуйте його для: -- ідентифікації плагіна +- ідентичності Plugin - валідації конфігурації -- метаданих автентифікації та онбордингу, які мають бути доступні без запуску середовища виконання плагіна -- недорогих підказок активації, які поверхні control plane можуть перевіряти до завантаження середовища виконання -- недорогих дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до завантаження середовища виконання -- метаданих псевдонімів та автоувімкнення, які мають визначатися до завантаження середовища виконання плагіна -- скорочених метаданих належності до сімейства моделей, які мають автоматично активувати плагін до завантаження середовища виконання -- статичних знімків належності можливостей, що використовуються для вбудованої сумісної прив’язки та покриття контрактів -- недорогих метаданих засобу запуску QA, які спільний хост `openclaw qa` може перевіряти до завантаження середовища виконання плагіна -- метаданих конфігурації, специфічних для каналу, які мають об’єднуватися в поверхні каталогу та валідації без завантаження середовища виконання +- метаданих автентифікації та онбордингу, які мають бути доступні без запуску + середовища виконання Plugin +- недорогих підказок активації, які поверхні control plane можуть перевіряти до + завантаження середовища виконання +- недорогих дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до + завантаження середовища виконання +- метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження середовища виконання Plugin +- метаданих скороченого володіння сімейством моделей, які мають автоматично активувати + Plugin до завантаження середовища виконання +- статичних знімків володіння можливостями, що використовуються для сумісного вбудованого з’єднання та + покриття контрактів +- недорогих метаданих запускальника QA, які спільний хост `openclaw qa` може перевіряти + до завантаження середовища виконання Plugin +- метаданих конфігурації, специфічних для каналу, які мають об’єднуватися в поверхні каталогу та валідації + без завантаження середовища виконання - підказок UI конфігурації Не використовуйте його для: -- реєстрації поведінки середовища виконання +- реєстрації поведінки під час виконання - оголошення точок входу коду - метаданих встановлення npm -Це належить вашому коду плагіна та `package.json`. +Це належить до коду вашого Plugin і `package.json`. ## Мінімальний приклад @@ -139,65 +155,67 @@ OpenClaw також автоматично виявляє ці компонув ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний ідентифікатор плагіна. Це ідентифікатор, який використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього плагіна. | -| `enabledByDefault` | Ні | `true` | Позначає вбудований плагін як увімкнений за замовчуванням. Пропустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб плагін залишався вимкненим за замовчуванням. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора плагіна. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей плагін, коли автентифікація, конфігурація або посилання на моделі згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип плагіна, який використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей плагін. Використовується для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей плагін. | -| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, якими володіє маніфест і які використовуються для автозавантаження плагіна до завантаження середовища виконання. | -| `providerEndpoints` | Ні | `object[]` | Метадані хостів/`baseUrl` кінцевих точок, якими володіє маніфест, для маршрутів провайдерів, які ядро має класифікувати до завантаження середовища виконання провайдера. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI inference, якими володіє цей плагін. Використовується для автоактивації під час запуску з явних посилань конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або backend CLI, для яких синтетичний хук автентифікації, що належить плагіну, має перевірятися під час холодного виявлення моделей до завантаження середовища виконання. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, що належать вбудованому плагіну й представляють не секретний локальний стан, OAuth або ambient credential state. | -| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей плагін і які мають видавати обізнані про плагін діагностики конфігурації та CLI до завантаження середовища виконання. | -| `providerAuthEnvVars` | Ні | `Record` | Недорогі метадані env автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. | -| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер для кодування, який спільно використовує API-ключ базового провайдера та профілі автентифікації. | -| `channelEnvVars` | Ні | `Record` | Недорогі метадані env каналу, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналу через env або поверхонь автентифікації, які мають бути видимі загальним helper запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані вибору автентифікації для засобів вибору в онбордингу, визначення пріоритетного провайдера та простого зв’язування CLI flags. | -| `activation` | Ні | `object` | Недорогі підказки активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактична поведінка, як і раніше, належить середовищу виконання плагіна. | -| `setup` | Ні | `object` | Недорогі дескриптори налаштування/онбордингу, які поверхні виявлення й налаштування можуть перевіряти без завантаження середовища виконання плагіна. | -| `qaRunners` | Ні | `object[]` | Недорогі дескриптори засобів запуску QA, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання плагіна. | -| `contracts` | Ні | `object` | Статичний знімок можливостей вбудованого пакета для зовнішніх хуків автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Недорогі значення за замовчуванням media-understanding для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Канонічний id Plugin. Це id, який використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована схема JSON для конфігурації цього 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 до запуску середовища виконання. | +| `providerEndpoints` | Ні | `object[]` | Метадані хостів/`baseUrl` кінцевих точок, якими володіє маніфест, для маршрутів провайдера, які ядро повинно класифікувати до завантаження середовища виконання провайдера. | +| `cliBackends` | Ні | `string[]` | Id backend-ів інференсу CLI, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або backend-и CLI, для яких під час холодного виявлення моделей до завантаження середовища виконання слід перевіряти синтетичний хук автентифікації, що належить Plugin. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, що належать вбудованому Plugin і представляють несекретний локальний стан, OAuth або ambient credential state. | +| `commandAliases` | Ні | `object[]` | Імена команд, що належать цьому Plugin і мають видавати діагностику конфігурації та CLI з урахуванням Plugin до завантаження середовища виконання. | +| `providerAuthEnvVars` | Ні | `Record` | Недорогі метадані env для автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду Plugin. | +| `providerAuthAliases` | Ні | `Record` | Id провайдерів, які мають повторно використовувати інший id провайдера для пошуку автентифікації, наприклад провайдер кодування, який спільно використовує API-ключ і профілі автентифікації базового провайдера. | +| `channelEnvVars` | Ні | `Record` | Недорогі метадані env каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для керованого env налаштування каналу або поверхонь автентифікації, які мають бачити універсальні допоміжні засоби запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані вибору автентифікації для селекторів онбордингу, визначення пріоритетного провайдера та простого зв’язування прапорців CLI. | +| `activation` | Ні | `object` | Недорогі підказки активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактичною поведінкою як і раніше володіє середовище виконання Plugin. | +| `setup` | Ні | `object` | Недорогі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання Plugin. | +| `qaRunners` | Ні | `object[]` | Недорогі дескриптори запускальників QA, які використовує спільний хост `openclaw qa` до завантаження середовища виконання Plugin. | +| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, мовлення, транскрибування в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, web search і володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Недорогі значення за замовчуванням для розуміння медіа для id провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | | `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, якими володіє маніфест і які об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня плагіна. | -| `name` | Ні | `string` | Людинозрозуміла назва плагіна. | -| `description` | Ні | `string` | Короткий опис, що показується на поверхнях плагіна. | -| `version` | Ні | `string` | Інформаційна версія плагіна. | -| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки чутливості для полів конфігурації. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. | +| `name` | Ні | `string` | Зрозуміла людині назва Plugin. | +| `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. | +| `version` | Ні | `string` | Інформаційна версія Plugin. | +| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. OpenClaw зчитує це до завантаження середовища виконання провайдера. -| Поле | Обов’язкове | Тип | Що воно означає | -| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Ідентифікатор провайдера, якому належить цей варіант. | -| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід маршрутизувати. | -| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується в потоках онбордингу та CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих помічником. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант у засобах вибору помічника, але все ще дозволяє ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів до цього варіанта-замінника. | -| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним флагом. | -| `cliFlag` | Ні | `string` | Назва CLI-флага, наприклад `--openrouter-api-key`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `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"]`. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо пропущено, за замовчуванням це `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли плагіну належить ім’я команди середовища виконання, яке користувачі можуть помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду середовища виконання плагіна. +Використовуйте `commandAliases`, коли Plugin володіє іменем команди середовища виконання, яке користувачі можуть +помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw +використовує ці метадані для діагностики без імпорту коду середовища виконання Plugin. ```json { @@ -211,19 +229,23 @@ OpenClaw зчитує це до завантаження середовища в } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | --------------------------------------------------------------------------- | -| `name` | Так | `string` | Ім’я команди, яка належить цьому плагіну. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо вона існує. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------- | +| `name` | Так | `string` | Ім’я команди, яке належить цьому Plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід підказати для операцій CLI, якщо вона існує. | ## Довідник `activation` -Використовуйте `activation`, коли плагін може недорого оголосити, які події control plane мають активувати його пізніше. +Використовуйте `activation`, коли Plugin може недорого оголосити, які події control plane +мають активувати його пізніше. ## Довідник `qaRunners` -Використовуйте `qaRunners`, коли плагін додає один або кілька транспортних засобів запуску під спільним коренем `openclaw qa`. Зберігайте ці метадані недорогими й статичними; фактична реєстрація CLI, як і раніше, належить середовищу виконання плагіна через легковагову поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. +Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner-ів під спільним +коренем `openclaw qa`. Зберігайте ці метадані легкими та статичними; середовище виконання Plugin +як і раніше володіє фактичною реєстрацією CLI через легку поверхню +`runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { @@ -236,13 +258,16 @@ OpenClaw зчитує це до завантаження середовища в } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | -------- | ----------------------------------------------------------------------- | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | -| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | -------- | --------------------------------------------------------------------- | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. | -Цей блок є лише метаданими. Він не реєструє поведінку середовища виконання і не замінює `register(...)`, `setupEntry` або інші точки входу середовища виконання/плагіна. -Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням плагіна, тому відсутність метаданих активації зазвичай впливає лише на продуктивність; вона не має змінювати коректність, доки ще існують застарілі резервні механізми володіння маніфестом. +Цей блок є лише метаданими. Він не реєструє поведінку під час виконання і не +замінює `register(...)`, `setupEntry` або інші точки входу runtime/Plugin. +Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому +відсутність метаданих активації зазвичай лише впливає на продуктивність; вона не має +змінювати коректність, доки все ще існують застарілі резервні механізми володіння маніфестом. ```json { @@ -256,23 +281,28 @@ OpenClaw зчитує це до завантаження середовища в } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають активувати цей плагін на запит. | -| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають активувати цей плагін. | -| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають активувати цей плагін. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей плагін. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються під час планування активації control plane. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ---------------- | ----------- | ---------------------------------------------------- | ----------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Id провайдерів, які мають активувати цей Plugin за запитом. | +| `onCommands` | Ні | `string[]` | Id команд, які мають активувати цей Plugin. | +| `onChannels` | Ні | `string[]` | Id каналів, які мають активувати цей Plugin. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей Plugin. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки можливостей, що використовуються плануванням активації control plane. | -Поточні активні споживачі: +Поточні живі споживачі: -- планування CLI, що запускається командою, повертається до застарілого `commandAliases[].cliCommand` або `commandAliases[].name` -- планування налаштування/каналу, що запускається каналом, повертається до застарілого володіння `channels[]`, якщо явні метадані активації каналу відсутні -- планування налаштування/середовища виконання, що запускається провайдером, повертається до застарілого володіння `providers[]` і верхньорівневого `cliBackends[]`, якщо явні метадані активації провайдера відсутні +- планування CLI, що запускається командою, повертається до застарілого + `commandAliases[].cliCommand` або `commandAliases[].name` +- планування налаштування/каналу, що запускається каналом, повертається до застарілого володіння + `channels[]`, коли явні метадані активації каналу відсутні +- планування налаштування/runtime, що запускається провайдером, повертається до застарілого + володіння `providers[]` і `cliBackends[]` верхнього рівня, коли явні метадані активації провайдера + відсутні ## Довідник `setup` -Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні недорогі метадані, що належать плагіну, до завантаження середовища виконання. +Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні легкі метадані Plugin +до завантаження середовища виконання. ```json { @@ -291,32 +321,41 @@ OpenClaw зчитує це до завантаження середовища в } ``` -Верхньорівневе `cliBackends` залишається валідним і надалі описує backend CLI inference. `setup.cliBackends` — це поверхня дескрипторів, специфічна для налаштування, для потоків control plane/налаштування, які мають залишатися лише метаданими. +`cliBackends` верхнього рівня залишається валідним і надалі описує backend-и інференсу CLI. +`setup.cliBackends` — це поверхня дескрипторів, специфічна для налаштування, для потоків +control plane/налаштування, які мають залишатися лише на рівні метаданих. -Якщо вони присутні, `setup.providers` і `setup.cliBackends` є пріоритетною поверхнею пошуку за принципом descriptor-first для виявлення налаштування. Якщо дескриптор лише звужує кандидатний плагін, а для налаштування все ще потрібні багатші хуки середовища виконання часу налаштування, установіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. +Якщо присутні `setup.providers` і `setup.cliBackends`, вони є бажаною +поверхнею пошуку setup за принципом descriptor-first для виявлення налаштування. Якщо дескриптор лише +звужує кандидатний Plugin, а налаштуванню все ще потрібні багатші runtime-хуки часу налаштування, +встановіть `requiresRuntime: true` і залиште `setup-api` як +резервний шлях виконання. -Оскільки пошук налаштування може виконувати код `setup-api`, що належить плагіну, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед виявлених плагінів. Неоднозначне володіння завершується в безпечному закритому стані замість вибору переможця за порядком виявлення. +Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, +нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися +унікальними серед виявлених Plugin. Неоднозначне володіння завершується закритою відмовою замість вибору +переможця за порядком виявлення. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------- | -| `id` | Так | `string` | Ідентифікатор провайдера, який відкривається під час налаштування або онбордингу. Нормалізовані ідентифікатори мають бути глобально унікальними. | -| `authMethods` | Ні | `string[]` | Ідентифікатори методів налаштування/автентифікації, які цей провайдер підтримує без завантаження повного середовища виконання. | -| `envVars` | Ні | `string[]` | Змінні env, які загальні поверхні налаштування/стану можуть перевіряти до завантаження середовища виконання плагіна. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | ---------- | ----------------------------------------------------------------------------------- | +| `id` | Так | `string` | Id провайдера, що надається під час налаштування або онбордингу. Зберігайте нормалізовані id глобально унікальними. | +| `authMethods` | Ні | `string[]` | Id методів налаштування/автентифікації, які цей провайдер підтримує без завантаження повного середовища виконання. | +| `envVars` | Ні | `string[]` | Env vars, які універсальні поверхні налаштування/статусу можуть перевіряти до завантаження середовища виконання Plugin. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, що відкриваються під час налаштування та онбордингу. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend часу налаштування, що використовуються для пошуку налаштування за принципом descriptor-first. Нормалізовані ідентифікатори мають бути глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, які належать поверхні налаштування цього плагіна. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує налаштування виконання `setup-api` після пошуку за дескриптором. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори налаштування провайдера, що надаються під час налаштування та онбордингу. | +| `cliBackends` | Ні | `string[]` | Id backend-ів часу налаштування, що використовуються для пошуку setup за принципом descriptor-first. Зберігайте нормалізовані id глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє поверхня setup цього Plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` навіть після пошуку за дескриптором. | ## Довідник `uiHints` -`uiHints` — це відображення від назв полів конфігурації до невеликих підказок рендерингу. +`uiHints` — це мапа від імен полів конфігурації до невеликих підказок рендерингу. ```json { @@ -331,20 +370,21 @@ OpenClaw зчитує це до завантаження середовища в } ``` -Кожна підказка для поля може містити: +Кожна підказка поля може містити: -| Поле | Тип | Що воно означає | -| ------------- | ---------- | ----------------------------------------- | -| `label` | `string` | Мітка поля для користувача. | -| `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові теги UI. | -| `advanced` | `boolean` | Позначає поле як розширене. | -| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст-заповнювач для полів форми. | +| Поле | Тип | Що воно означає | +| ------------- | ---------- | --------------------------------------- | +| `label` | `string` | Мітка поля для користувача. | +| `help` | `string` | Короткий допоміжний текст. | +| `tags` | `string[]` | Необов’язкові теги UI. | +| `advanced` | `boolean` | Позначає поле як розширене. | +| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | +| `placeholder` | `string` | Текст-заповнювач для полів форми. | ## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих належності можливостей, які OpenClaw може зчитати без імпорту середовища виконання плагіна. +Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може +зчитати без імпорту середовища виконання Plugin. ```json { @@ -366,25 +406,31 @@ OpenClaw зчитує це до завантаження середовища в Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | ------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Ідентифікатори вбудованого середовища виконання, для яких вбудований плагін може реєструвати фабрики. | -| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, хук зовнішнього профілю автентифікації яких належить цьому плагіну. | -| `speechProviders` | `string[]` | Ідентифікатори speech-провайдерів, які належать цьому плагіну. | -| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime transcription, які належать цьому плагіну. | -| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів realtime voice, які належать цьому плагіну. | -| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, які належать цьому плагіну. | -| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів image generation, які належать цьому плагіну. | -| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів video generation, які належать цьому плагіну. | -| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, які належать цьому плагіну. | -| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, які належать цьому плагіну. | -| `tools` | `string[]` | Назви інструментів агента, які належать цьому плагіну для перевірок контрактів вбудованих пакетів. | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | -------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Id вбудованого runtime, для яких вбудований Plugin може реєструвати фабрики. | +| `externalAuthProviders` | `string[]` | Id провайдерів, чий зовнішній хук профілю автентифікації належить цьому Plugin. | +| `speechProviders` | `string[]` | Id провайдерів мовлення, якими володіє цей Plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів транскрибування в реальному часі, якими володіє цей Plugin. | +| `realtimeVoiceProviders` | `string[]` | Id провайдерів голосу в реальному часі, якими володіє цей 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 для перевірок вбудованих контрактів. | -Плагіни провайдерів, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати `contracts.externalAuthProviders`. Плагіни без цього оголошення все ще працюють через застарілий резервний механізм сумісності, але він повільніший і буде видалений після завершення вікна міграції. +Plugin провайдера, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати +`contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють +через застарілий резервний механізм сумісності, але цей механізм повільніший і +буде видалений після завершення вікна міграції. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має моделі за замовчуванням, пріоритет резервної auto-auth або власну підтримку документів, які потрібні загальним helper ядра до завантаження середовища виконання. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має +моделі за замовчуванням, пріоритет резервного автоавтентифікації або власну підтримку документів, які +універсальним допоміжним засобам ядра потрібні до завантаження runtime. Ключі також мають бути оголошені в +`contracts.mediaUnderstandingProviders`. ```json { @@ -409,16 +455,17 @@ OpenClaw зчитує це до завантаження середовища в Кожен запис провайдера може містити: -| Поле | Тип | Що воно означає | -| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------ | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | -| `defaultModels` | `Record` | Значення моделей за замовчуванням для можливостей, що використовуються, коли конфігурація не вказує модель. | +| Поле | Тип | Що воно означає | +| ---------------------- | ----------------------------------- | --------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості медіа, які надає цей провайдер. | +| `defaultModels` | `Record` | Типові значення зіставлення можливостей із моделями, які використовуються, коли конфігурація не задає модель. | | `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Власні вхідні дані документів, які підтримує провайдер. | +| `nativeDocumentInputs` | `"pdf"[]` | Власні вхідні дані документів, які підтримує провайдер. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли плагіну каналу потрібні недорогі метадані конфігурації до завантаження середовища виконання. +Використовуйте `channelConfigs`, коли Plugin каналу потребує легких метаданих конфігурації до +завантаження runtime. ```json { @@ -447,17 +494,18 @@ OpenClaw зчитує це до завантаження середовища в Кожен запис каналу може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ | -| `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації каналу. | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | ------------------------------------------------------------------------------- | +| `schema` | `object` | Схема JSON для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | | `uiHints` | `Record` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, яка об’єднується в поверхні вибору та перегляду, коли метадані середовища виконання ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь перегляду та каталогу. | -| `preferOver` | `string[]` | Ідентифікатори застарілих або нижчопріоритетних плагінів, які цей канал має перевершувати на поверхнях вибору. | +| `label` | `string` | Мітка каналу, що об’єднується в поверхні вибору та інспектування, коли метадані runtime ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь інспектування та каталогу. | +| `preferOver` | `string[]` | Id застарілих або менш пріоритетних Plugin, які цей канал має перевершувати в поверхнях вибору. | ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має визначати ваш плагін провайдера за скороченими ідентифікаторами моделей на кшталт `gpt-5.4` або `claude-sonnet-4.6` до завантаження середовища виконання плагіна. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера з +скорочених id моделей, таких як `gpt-5.4` або `claude-sonnet-4.6`, до завантаження runtime Plugin. ```json { @@ -470,69 +518,100 @@ OpenClaw зчитує це до завантаження середовища в OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers`, якому належить провайдер -- `modelPatterns` мають пріоритет над `modelPrefixes` -- якщо збігаються один невбудований плагін і один вбудований плагін, перемагає невбудований плагін -- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть провайдера +- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать власнику +- `modelPatterns` мають вищий пріоритет за `modelPrefixes` +- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований + Plugin +- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | -------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | -| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | +| Поле | Тип | Що воно означає | +| --------------- | ---------- | ------------------------------------------------------------------------------ | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id моделей після видалення суфікса профілю. | -Застарілі ключі можливостей верхнього рівня не рекомендуються до використання. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` до `contracts`; звичайне завантаження маніфесту більше не розглядає ці поля верхнього рівня як належність можливостей. +Застарілі ключі можливостей верхнього рівня застаріли. Використовуйте `openclaw doctor --fix`, щоб +перемістити `speechProviders`, `realtimeTranscriptionProviders`, +`realtimeVoiceProviders`, `mediaUnderstandingProviders`, +`imageGenerationProviders`, `videoGenerationProviders`, +`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне +завантаження маніфесту більше не розглядає ці поля верхнього рівня як +володіння можливостями. -## Маніфест versus package.json +## Маніфест і `package.json` -Ці два файли виконують різні завдання: +Ці два файли виконують різні ролі: | Файл | Для чого використовувати | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду плагіна | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для точок входу, обмежень встановлення, налаштування або метаданих каталогу | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані вибору автентифікації та підказки UI, які мають існувати до запуску коду Plugin | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для точок входу, обмеження встановлення, налаштування або метаданих каталогу | -Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте таке правило: +Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило: -- якщо OpenClaw має знати про нього до завантаження коду плагіна, розміщуйте його в `openclaw.plugin.json` -- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json` +- якщо OpenClaw має знати це до завантаження коду Plugin, помістіть це в `openclaw.plugin.json` +- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, помістіть це в `package.json` ### Поля `package.json`, які впливають на виявлення -Деякі метадані плагіна до запуску середовища виконання навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. +Деякі метадані Plugin до запуску runtime навмисно розміщено в `package.json` у блоці +`openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: | Поле | Що воно означає | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | Оголошує точки входу власного плагіна. Вони мають залишатися в межах каталогу пакета плагіна. | -| `openclaw.runtimeExtensions` | Оголошує точки входу зібраного середовища виконання JavaScript для встановлених пакетів. Вони мають залишатися в межах каталогу пакета плагіна. | -| `openclaw.setupEntry` | Легковагова точка входу лише для налаштування, що використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Вона має залишатися в межах каталогу пакета плагіна. | -| `openclaw.runtimeSetupEntry` | Оголошує точку входу зібраного JavaScript для налаштування для встановлених пакетів. Вона має залишатися в межах каталогу пакета плагіна. | -| `openclaw.channel` | Недорогі метадані каталогу каналу, як-от мітки, шляхи документації, псевдоніми та текст для вибору. | -| `openclaw.channel.configuredState` | Метадані легковагового засобу перевірки налаштованого стану, який може відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного середовища виконання каналу. | -| `openclaw.channel.persistedAuthState` | Метадані легковагового засобу перевірки збереженого стану автентифікації, який може відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного середовища виконання каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих плагінів. | -| `openclaw.install.defaultChoice` | Пріоритетний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw з використанням нижньої межі semver, наприклад `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення звіряють із ним отриманий артефакт. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого плагіна, коли конфігурація невалідна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для налаштування завантажуватися під час запуску раніше, ніж повний плагін каналу. | +| `openclaw.extensions` | Оголошує власні точки входу Plugin. Повинні залишатися всередині каталогу пакета Plugin. | +| `openclaw.runtimeExtensions` | Оголошує точки входу built JavaScript runtime для встановлених пакетів. Повинні залишатися всередині каталогу пакета Plugin. | +| `openclaw.setupEntry` | Легка точка входу лише для setup, яка використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Повинна залишатися всередині каталогу пакета Plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript точку входу setup для встановлених пакетів. Повинна залишатися всередині каталогу пакета Plugin. | +| `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.expectedIntegrity` | Очікуваний рядок npm dist integrity, наприклад `sha512-...`; потоки встановлення та оновлення звіряють із ним завантажений артефакт. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого Plugin, коли конфігурація невалідна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | -Метадані маніфесту визначають, які варіанти провайдера/каналу/налаштування з’являються в онбордингу до завантаження середовища виконання. `package.json#openclaw.install` повідомляє онбордингу, як отримати або ввімкнути цей плагін, коли користувач обирає один із цих варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`. +Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в +онбордингу до завантаження runtime. `package.json#openclaw.install` повідомляє +онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих +варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`. -`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають плагін на старіших хостах. +`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження +реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають +Plugin на старіших хостах. -Точне закріплення версії npm вже міститься в `npmSpec`, наприклад `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Поєднуйте це з `expectedIntegrity`, якщо хочете, щоб потоки оновлення завершувалися в безпечному закритому стані, коли отриманий артефакт npm більше не відповідає закріпленому релізу. Інтерактивний онбординг пропонує варіанти встановлення npm лише з довірених метаданих каталогу, коли `npmSpec` є точною версією і присутній `expectedIntegrity`; інакше він повертається до локального джерела або пропуску. +Точне закріплення версії npm уже живе в `npmSpec`, наприклад +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Поєднуйте це з +`expectedIntegrity`, якщо хочете, щоб потоки оновлення завершувалися закритою відмовою, коли завантажений +артефакт npm більше не відповідає закріпленому релізу. Інтерактивний онбординг +пропонує довірені npm-специфікації реєстру, зокрема прості назви пакетів і dist-tag. Коли +`expectedIntegrity` присутній, потоки встановлення/оновлення застосовують його; коли його +пропущено, дозвіл реєстру записується без закріплення цілісності. -Плагіни каналів повинні надавати `openclaw.setupEntry`, коли статус, список каналів або сканування SecretRef мають визначати налаштовані облікові записи без завантаження повного середовища виконання. Точка входу налаштування має надавати метадані каналу разом із безпечними для налаштування адаптерами конфігурації, статусу та секретів; мережеві клієнти, слухачі Gateway і середовища виконання транспорту слід залишати в основній точці входу розширення. +Plugin каналу повинні надавати `openclaw.setupEntry`, коли статус, список каналів +або сканування SecretRef мають визначати налаштовані облікові записи без завантаження повного +runtime. Точка входу setup має надавати метадані каналу разом із безпечною для setup конфігурацією, +статусом і адаптерами секретів; зберігайте мережеві клієнти, слухачі Gateway і +transport runtime у головній точці входу extension. -Поля точок входу середовища виконання не скасовують перевірки меж пакета для полів вихідних точок входу. Наприклад, `openclaw.runtimeExtensions` не може зробити придатним до завантаження шлях `openclaw.extensions`, що виходить за межі. +Поля точки входу runtime не перевизначають перевірки меж пакета для полів +точки входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити +завантажуваним шлях `openclaw.extensions`, що виходить за межі. -`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке застосування. Воно не робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам встановлення відновлюватися після певних застарілих збоїв оновлення вбудованого плагіна, наприклад відсутнього шляху до вбудованого плагіна або застарілого запису `channels.` для того самого вбудованого плагіна. Не пов’язані помилки конфігурації й далі блокують встановлення та спрямовують операторів до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не +робить довільні зламані конфігурації встановлюваними. Сьогодні він лише дозволяє потокам встановлення +відновлюватися після певних застарілих збоїв оновлення вбудованого Plugin, таких як +відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для того самого +вбудованого Plugin. Непов’язані помилки конфігурації все одно блокують встановлення і спрямовують операторів +до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для маленького модуля перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля +перевірки: ```json { @@ -548,9 +627,13 @@ OpenClaw застосовує такий пріоритет: } ``` -Використовуйте це, коли потоки налаштування, doctor або configured-state потребують недорогої перевірки автентифікації з відповіддю так/ні до завантаження повного плагіна каналу. Цільовий експорт має бути невеликою функцією, яка лише зчитує збережений стан; не маршрутизуйте її через повний barrel середовища виконання каналу. +Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка +автентифікації «так/ні» до завантаження повного Plugin каналу. Цільовий експорт має бути невеликою +функцією, яка читає лише збережений стан; не спрямовуйте її через повний barrel runtime +каналу. -`openclaw.channel.configuredState` має ту саму форму для недорогих перевірок налаштованого стану лише через env: +`openclaw.channel.configuredState` використовує ту саму форму для дешевих перевірок +налаштованого стану лише через env: ```json { @@ -566,62 +649,95 @@ OpenClaw застосовує такий пріоритет: } ``` -Використовуйте це, коли канал може визначити налаштований стан за env або іншими невеликими невиконуваними в середовищі виконання вхідними даними. Якщо перевірка потребує повного визначення конфігурації або реального середовища виконання каналу, залиште цю логіку в хуку плагіна `config.hasConfiguredState`. +Використовуйте це, коли канал може відповідати про налаштований стан через env або інші малі +входи, не пов’язані з runtime. Якщо перевірка потребує повного розв’язання конфігурації або справжнього +runtime каналу, зберігайте цю логіку натомість у хуку Plugin `config.hasConfiguredState`. -## Пріоритет виявлення (дубльовані ідентифікатори плагінів) +## Пріоритет виявлення (дублікати id Plugin) -OpenClaw виявляє плагіни з кількох коренів (вбудовані, глобальне встановлення, робочий простір, шляхи, явно вибрані в конфігурації). Якщо два виявлені плагіни мають однаковий `id`, зберігається лише маніфест **з найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. +OpenClaw виявляє Plugin з кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлення мають спільний `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч. -Пріоритет від найвищого до найнижчого: +Пріоритет, від найвищого до найнижчого: 1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.` -2. **Вбудований** — плагіни, що постачаються з OpenClaw -3. **Глобальне встановлення** — плагіни, встановлені в глобальний корінь плагінів OpenClaw -4. **Робочий простір** — плагіни, виявлені відносно поточного робочого простору +2. **Вбудований** — Plugin, що постачаються разом з OpenClaw +3. **Глобальне встановлення** — Plugin, встановлені в глобальний корінь Plugin OpenClaw +4. **Workspace** — Plugin, виявлені відносно поточного workspace Наслідки: -- Форк або застаріла копія вбудованого плагіна, що лежить у робочому просторі, не перекриє вбудовану збірку. -- Щоб справді перевизначити вбудований плагін локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладався на виявлення в робочому просторі. -- Відкидання дублікатів записується в журнал, щоб Doctor і діагностика під час запуску могли вказати на відкинуту копію. +- Розгалужена або застаріла копія вбудованого Plugin, що лежить у workspace, не затьмарить вбудовану збірку. +- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладався на виявлення у workspace. +- Відкидання дублікатів записується в журнал, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. -## Вимоги до JSON Schema +## Вимоги до схеми JSON -- **Кожен плагін повинен містити JSON Schema**, навіть якщо він не приймає конфігурації. -- Порожня схема є припустимою (наприклад, `{ "type": "object", "additionalProperties": false }`). +- **Кожен Plugin повинен постачати схему JSON**, навіть якщо він не приймає конфігурацію. +- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). - Схеми проходять валідацію під час читання/запису конфігурації, а не під час виконання. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено в маніфесті плагіна. -- `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` повинні посилатися на **виявлювані** ідентифікатори плагінів. Невідомі ідентифікатори є **помилками**. -- Якщо плагін встановлено, але він має зламаний або відсутній маніфест чи схему, валідація завершується помилкою, а Doctor повідомляє про помилку плагіна. -- Якщо конфігурація плагіна існує, але сам плагін **вимкнено**, конфігурація зберігається, і в Doctor + журналах показується **попередження**. +- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошено + маніфестом Plugin. +- `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` + повинні посилатися на id Plugin, які **можна виявити**. Невідомі id є **помилками**. +- Якщо Plugin встановлено, але він має зламаний або відсутній маніфест чи схему, + валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. +- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається і + в Doctor + журналах показується **попередження**. -Повну схему `plugins.*` див. у [Довіднику з конфігурації](/uk/gateway/configuration). +Повну схему `plugins.*` дивіться в [Довідник конфігурації](/uk/gateway/configuration). ## Примітки -- Маніфест **є обов’язковим для власних плагінів OpenClaw**, включно із завантаженням із локальної файлової системи. -- Середовище виконання все одно окремо завантажує модуль плагіна; маніфест використовується лише для виявлення + валідації. -- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, якщо підсумкове значення все ще є об’єктом. -- Завантажувач маніфесту зчитує лише задокументовані поля маніфесту. Уникайте додавання сюди власних ключів верхнього рівня. -- `providerAuthEnvVars` — це недорогий шлях метаданих для перевірок автентифікації, валідації маркерів env та подібних поверхонь автентифікації провайдера, які не повинні запускати середовище виконання плагіна лише для перевірки назв env. -- `providerAuthAliases` дозволяє варіантам провайдера повторно використовувати env vars автентифікації, профілі автентифікації, автентифікацію на основі конфігурації та варіант онбордингу API-ключа іншого провайдера без жорсткого кодування цього зв’язку в ядрі. -- `providerEndpoints` дозволяє плагінам провайдерів володіти простими метаданими зіставлення хоста кінцевої точки/`baseUrl`. Використовуйте це лише для класів кінцевих точок, які ядро вже підтримує; поведінка середовища виконання, як і раніше, належить плагіну. -- `syntheticAuthRefs` — це недорогий шлях метаданих для синтетичних хуків автентифікації, що належать провайдеру й мають бути видимими для холодного виявлення моделей до появи реєстру середовища виконання. Вказуйте лише ті посилання, чий провайдер середовища виконання або backend CLI справді реалізує `resolveSyntheticAuth`. -- `nonSecretAuthMarkers` — це недорогий шлях метаданих для значень-заповнювачів API-ключів, що належать вбудованому плагіну, наприклад локальних маркерів, OAuth або маркерів ambient credential. Ядро трактує їх як не секретні для відображення автентифікації та аудиту секретів без жорсткого кодування провайдера-власника. -- `channelEnvVars` — це недорогий шлях метаданих для резервного використання env оболонки, запитів налаштування та подібних поверхонь каналу, які не повинні запускати середовище виконання плагіна лише для перевірки назв env. Імена env є метаданими, а не активацією самі по собі: статус, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до плагіна й ефективної активації, перш ніж вважати env var налаштованим каналом. -- `providerAuthChoices` — це недорогий шлях метаданих для засобів вибору варіантів автентифікації, визначення `--auth-choice`, зіставлення пріоритетного провайдера та простої реєстрації CLI flags онбордингу до завантаження середовища виконання провайдера. Метадані wizard середовища виконання, для яких потрібен код провайдера, див. у [Хуках середовища виконання провайдера](/uk/plugins/architecture#provider-runtime-hooks). -- Ексклюзивні типи плагінів вибираються через `plugins.slots.*`. +- Маніфест **обов’язковий для власних Plugin OpenClaw**, зокрема для локальних завантажень із файлової системи. +- Runtime усе одно завантажує модуль Plugin окремо; маніфест використовується лише для + виявлення + валідації. +- Власні маніфести розбираються через JSON5, тому коментарі, кінцеві коми та + ключі без лапок приймаються, якщо фінальне значення все ще є об’єктом. +- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання + тут власних ключів верхнього рівня. +- `providerAuthEnvVars` — це шлях дешевих метаданих для перевірок автентифікації, валідації + env-marker та подібних поверхонь автентифікації провайдера, які не повинні запускати runtime Plugin + лише для перевірки імен env. +- `providerAuthAliases` дозволяє варіантам провайдера повторно використовувати env vars + автентифікації, профілі автентифікації, автентифікацію на основі конфігурації та варіант + онбордингу з API-ключем іншого провайдера без жорсткого кодування цього зв’язку в ядрі. +- `providerEndpoints` дозволяє Plugin провайдера володіти простими метаданими + зіставлення хостів/`baseUrl` кінцевих точок. Використовуйте це лише для класів кінцевих точок, які ядро вже підтримує; + поведінкою runtime як і раніше володіє Plugin. +- `syntheticAuthRefs` — це шлях дешевих метаданих для синтетичних + хуків автентифікації, що належать провайдеру, які мають бути видимими для холодного виявлення моделей до того, як реєстр + runtime почне існувати. Вказуйте лише посилання, чий runtime-провайдер або backend CLI справді + реалізує `resolveSyntheticAuth`. +- `nonSecretAuthMarkers` — це шлях дешевих метаданих для значень-заповнювачів API-ключів, + що належать вбудованому Plugin, таких як локальні маркери, OAuth або ambient credential. + Ядро розглядає їх як несекретні для відображення автентифікації та аудитів секретів без + жорсткого кодування провайдера-власника. +- `channelEnvVars` — це шлях дешевих метаданих для резервного використання shell-env, підказок setup + та подібних поверхонь каналів, які не повинні запускати runtime Plugin + лише для перевірки імен env. Імена env — це метадані, а не активація самі по + собі: статус, аудит, перевірка доставки Cron та інші поверхні лише для читання все одно + застосовують довіру до Plugin і політику ефективної активації, перш ніж + розглядати env var як налаштований канал. +- `providerAuthChoices` — це шлях дешевих метаданих для селекторів варіантів автентифікації, + розв’язання `--auth-choice`, зіставлення пріоритетного провайдера та простої + реєстрації прапорців CLI онбордингу до завантаження runtime провайдера. Для метаданих + wizard runtime, які потребують коду провайдера, див. + [Хуки runtime провайдера](/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` можна не вказувати, якщо плагіну вони не потрібні. -- Якщо ваш плагін залежить від native modules, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + - `kind: "context-engine"` вибирається через `plugins.slots.contextEngine` + (типово: вбудований `legacy`). +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, коли + Plugin їх не потребує. +- Якщо ваш Plugin залежить від власних модулів, задокументуйте кроки збірки та всі + вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` - `pnpm rebuild `). ## Пов’язане -- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з плагінами +- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з Plugins - [Архітектура Plugin](/uk/plugins/architecture) — внутрішня архітектура - [Огляд SDK](/uk/plugins/sdk-overview) — довідник SDK Plugin diff --git a/docs/uk/plugins/sdk-setup.md b/docs/uk/plugins/sdk-setup.md index 3c86f7f8e..9f760d1a2 100644 --- a/docs/uk/plugins/sdk-setup.md +++ b/docs/uk/plugins/sdk-setup.md @@ -1,27 +1,27 @@ --- read_when: - Ви додаєте майстер налаштування до Plugin - - Вам потрібно зрозуміти різницю між `setup-entry.ts` та `index.ts` - - Ви визначаєте схеми конфігурації plugin або метадані `openclaw` у `package.json` + - Вам потрібно зрозуміти різницю між setup-entry.ts і index.ts + - Ви визначаєте схеми конфігурації plugin або метадані openclaw у package.json sidebarTitle: Setup and Config -summary: Майстри налаштування, `setup-entry.ts`, схеми конфігурації та метадані `package.json` -title: Налаштування Plugin та конфігурація +summary: Майстри налаштування, setup-entry.ts, схеми конфігурації та метадані package.json +title: Налаштування Plugin і конфігурація x-i18n: - generated_at: "2026-04-23T05:16:42Z" + generated_at: "2026-04-23T07:42:05Z" model: gpt-5.4 provider: openai - source_hash: ccdafb9a562353a7851fcd47bbc382961a449f5d645362c800f64c60579ce7b2 + source_hash: 110cf9aa1bfaeb286d38963cfba2006502e853dd603a126d1c179cbc9b60aea1 source_path: plugins/sdk-setup.md workflow: 15 --- -# Налаштування Plugin та конфігурація +# Налаштування Plugin і конфігурація -Довідник щодо пакування plugin (`package.json` metadata), маніфестів -(`openclaw.plugin.json`), записів налаштування та схем конфігурації. +Довідник із пакування plugin (`package.json` метадані), маніфестів +(`openclaw.plugin.json`), точок входу налаштування та схем конфігурації. - **Шукаєте покроковий посібник?** Практичні інструкції охоплюють пакування в контексті: + **Шукаєте покроковий приклад?** Покрокові інструкції описують пакування в контексті: [Channel Plugins](/uk/plugins/sdk-channel-plugins#step-1-package-and-manifest) і [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-1-package-and-manifest). @@ -50,7 +50,7 @@ x-i18n: } ``` -**Provider plugin / базовий варіант публікації в ClawHub:** +**Provider plugin / базовий варіант публікації ClawHub:** ```json openclaw-clawhub-package.json { @@ -71,47 +71,47 @@ x-i18n: } ``` -Якщо ви публікуєте plugin зовні в ClawHub, поля `compat` і `build` -є обов’язковими. Канонічні фрагменти для публікації знаходяться в +Якщо ви публікуєте plugin зовнішньо в ClawHub, ці поля `compat` і `build` +є обов’язковими. Канонічні фрагменти для публікації розміщені в `docs/snippets/plugin-publish/`. ### Поля `openclaw` -| Поле | Тип | Опис | -| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------- | -| `extensions` | `string[]` | Файли точок входу (відносно кореня пакета) | -| `setupEntry` | `string` | Полегшений запис лише для налаштування (необов’язково) | -| `channel` | `object` | Метадані каталогу каналів для налаштування, вибору, швидкого старту та поверхонь статусу | -| `providers` | `string[]` | Ідентифікатори провайдерів, зареєстровані цим plugin | -| `install` | `object` | Підказки для встановлення: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `expectedIntegrity`, `allowInvalidConfigRecovery` | -| `startup` | `object` | Прапорці поведінки під час запуску | +| Поле | Тип | Опис | +| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `extensions` | `string[]` | Файли точок входу (відносно кореня пакета) | +| `setupEntry` | `string` | Полегшена точка входу лише для налаштування (необов’язково) | +| `channel` | `object` | Метадані каталогу channel для налаштування, вибору, швидкого старту та поверхонь статусу | +| `providers` | `string[]` | Ідентифікатори provider, зареєстрованих цим plugin | +| `install` | `object` | Підказки встановлення: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `expectedIntegrity`, `allowInvalidConfigRecovery` | +| `startup` | `object` | Прапорці поведінки під час запуску | ### `openclaw.channel` -`openclaw.channel` — це недорогі метадані пакета для виявлення каналів і -поверхонь налаштування до завантаження runtime. +`openclaw.channel` — це недорогі метадані пакета для виявлення channel і поверхонь +налаштування до завантаження runtime. | Поле | Тип | Що це означає | | -------------------------------------- | ---------- | --------------------------------------------------------------------------- | -| `id` | `string` | Канонічний ідентифікатор каналу. | -| `label` | `string` | Основна назва каналу. | -| `selectionLabel` | `string` | Назва у виборі/налаштуванні, якщо вона має відрізнятися від `label`. | -| `detailLabel` | `string` | Додаткова детальна назва для багатших каталогів каналів і поверхонь статусу. | -| `docsPath` | `string` | Шлях до документації для посилань у налаштуванні та виборі. | -| `docsLabel` | `string` | Назва для посилань на документацію, якщо вона має відрізнятися від ідентифікатора каналу. | +| `id` | `string` | Канонічний ідентифікатор channel. | +| `label` | `string` | Основний ярлик channel. | +| `selectionLabel` | `string` | Ярлик у засобі вибору/налаштування, якщо він має відрізнятися від `label`. | +| `detailLabel` | `string` | Вторинний ярлик деталей для багатших каталогів channel і поверхонь статусу. | +| `docsPath` | `string` | Шлях до документації для посилань із налаштування та вибору. | +| `docsLabel` | `string` | Ярлик для посилань на документацію, якщо він має відрізнятися від id channel. | | `blurb` | `string` | Короткий опис для онбордингу/каталогу. | -| `order` | `number` | Порядок сортування в каталогах каналів. | -| `aliases` | `string[]` | Додаткові псевдоніми для пошуку каналу. | -| `preferOver` | `string[]` | Ідентифікатори plugin/каналів із нижчим пріоритетом, які цей канал має випереджати. | -| `systemImage` | `string` | Необов’язкова назва піктограми/system-image для каталогів UI каналу. | -| `selectionDocsPrefix` | `string` | Текст-префікс перед посиланнями на документацію в поверхнях вибору. | -| `selectionDocsOmitLabel` | `boolean` | Показувати шлях до документації безпосередньо замість підписаного посилання в тексті вибору. | -| `selectionExtras` | `string[]` | Додаткові короткі рядки, що додаються в тексті вибору. | -| `markdownCapable` | `boolean` | Позначає канал як сумісний із markdown для рішень щодо вихідного форматування. | -| `exposure` | `object` | Керування видимістю каналу для налаштування, списків налаштованих елементів і поверхонь документації. | -| `quickstartAllowFrom` | `boolean` | Вмикає цей канал у стандартний потік налаштування quickstart `allowFrom`. | -| `forceAccountBinding` | `boolean` | Вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис. | -| `preferSessionLookupForAnnounceTarget` | `boolean` | Надає перевагу пошуку сесії під час визначення цілей оголошення для цього каналу. | +| `order` | `number` | Порядок сортування в каталогах channel. | +| `aliases` | `string[]` | Додаткові псевдоніми для пошуку під час вибору channel. | +| `preferOver` | `string[]` | Ідентифікатори plugin/channel з нижчим пріоритетом, які цей channel має випереджати. | +| `systemImage` | `string` | Необов’язкова назва піктограми/system-image для каталогів UI channel. | +| `selectionDocsPrefix` | `string` | Префіксний текст перед посиланнями на документацію в поверхнях вибору. | +| `selectionDocsOmitLabel` | `boolean` | Показувати шлях документації напряму замість підписаного посилання в тексті вибору. | +| `selectionExtras` | `string[]` | Додаткові короткі рядки, додані до тексту вибору. | +| `markdownCapable` | `boolean` | Позначає channel як такий, що підтримує markdown, для рішень щодо вихідного форматування. | +| `exposure` | `object` | Керування видимістю channel для налаштування, списків налаштованих елементів і поверхонь документації. | +| `quickstartAllowFrom` | `boolean` | Додає цей channel до стандартного потоку швидкого старту `allowFrom`. | +| `forceAccountBinding` | `boolean` | Вимагає явного прив’язування облікового запису, навіть якщо існує лише один обліковий запис. | +| `preferSessionLookupForAnnounceTarget` | `boolean` | Надає перевагу пошуку session під час визначення announce target для цього channel. | Приклад: @@ -145,41 +145,40 @@ x-i18n: `exposure` підтримує: -- `configured`: включати канал до поверхонь переліку налаштованих елементів/статусу -- `setup`: включати канал до інтерактивних засобів вибору налаштування/конфігурації -- `docs`: позначати канал як публічно видимий у поверхнях документації/навігації +- `configured`: включати channel до поверхонь списків налаштованих елементів/стану +- `setup`: включати channel до інтерактивних засобів вибору налаштування/конфігурації +- `docs`: позначати channel як публічно видимий на поверхнях документації/навігації -`showConfigured` і `showInSetup` усе ще підтримуються як застарілі псевдоніми. Надавайте перевагу +`showConfigured` і `showInSetup` залишаються підтримуваними як застарілі псевдоніми. Надавайте перевагу `exposure`. ### `openclaw.install` `openclaw.install` — це метадані пакета, а не метадані маніфесту. -| Поле | Тип | Що це означає | -| ---------------------------- | -------------------- | ------------------------------------------------------------------------------ | -| `npmSpec` | `string` | Канонічний npm spec для потоків встановлення/оновлення. | -| `localPath` | `string` | Локальний шлях встановлення для розробки або вбудованого plugin. | -| `defaultChoice` | `"npm"` \| `"local"` | Бажане джерело встановлення, коли доступні обидва варіанти. | -| `minHostVersion` | `string` | Мінімальна підтримувана версія OpenClaw у формі `>=x.y.z`. | -| `expectedIntegrity` | `string` | Очікуваний рядок цілісності npm dist, зазвичай `sha512-...`, для фіксованих встановлень. | -| `allowInvalidConfigRecovery` | `boolean` | Дозволяє потокам перевстановлення вбудованих plugin відновлюватися після окремих збоїв через застарілу конфігурацію. | +| Поле | Тип | Що це означає | +| ---------------------------- | -------------------- | -------------------------------------------------------------------------------- | +| `npmSpec` | `string` | Канонічна специфікація npm для потоків встановлення/оновлення. | +| `localPath` | `string` | Локальний шлях для розробки або вбудованого встановлення. | +| `defaultChoice` | `"npm"` \| `"local"` | Бажане джерело встановлення, коли доступні обидва варіанти. | +| `minHostVersion` | `string` | Мінімально підтримувана версія OpenClaw у формі `>=x.y.z`. | +| `expectedIntegrity` | `string` | Очікуваний рядок цілісності npm dist, зазвичай `sha512-...`, для зафіксованих встановлень. | +| `allowInvalidConfigRecovery` | `boolean` | Дозволяє потокам перевстановлення вбудованих plugin відновлюватися після певних збоїв застарілої конфігурації. | Інтерактивний онбординг також використовує `openclaw.install` для поверхонь -встановлення на вимогу. Якщо ваш plugin показує варіанти авторизації провайдера або -метадані налаштування/каталогу каналу до завантаження runtime, -онбординг може показати цей вибір, запропонувати npm чи локальне встановлення, -встановити або ввімкнути plugin, а потім продовжити вибраний -потік. Варіанти онбордингу через npm вимагають довірених метаданих каталогу з точним -значенням `npmSpec` версії та `expectedIntegrity`; нефіксовані назви пакетів і dist-tags -не пропонуються для автоматичного встановлення під час онбордингу. Зберігайте метадані -«що показувати» в `openclaw.plugin.json`, а метадані «як це встановити» — у -`package.json`. +встановлення на вимогу. Якщо ваш plugin надає варіанти автентифікації provider або метадані +налаштування/каталогу channel до завантаження runtime, онбординг може показати цей вибір, +запропонувати npm чи локальне встановлення, встановити або ввімкнути plugin, а потім продовжити вибраний +потік. Варіанти онбордингу npm потребують довірених метаданих каталогу з реєстровим +`npmSpec`; точні версії та `expectedIntegrity` — необов’язкові фіксації. Якщо +`expectedIntegrity` присутній, потоки встановлення/оновлення примусово перевіряють його. Зберігайте метадані «що +показувати» в `openclaw.plugin.json`, а метадані «як це встановити» — +у `package.json`. Якщо задано `minHostVersion`, і встановлення, і завантаження реєстру маніфестів -застосовують цю вимогу. Старіші хости пропускають plugin; недійсні рядки версій відхиляються. +примусово застосовують його. Старіші host пропускають plugin; некоректні рядки версій відхиляються. -Для фіксованих npm-встановлень зберігайте точну версію в `npmSpec` і додавайте +Для зафіксованих npm-встановлень зберігайте точну версію в `npmSpec` і додавайте очікувану цілісність артефакту: ```json @@ -194,11 +193,11 @@ x-i18n: } ``` -`allowInvalidConfigRecovery` не є загальним обходом для зламаних конфігурацій. Це -призначено лише для вузьких сценаріїв відновлення вбудованих plugin, щоб перевстановлення/налаштування -могло виправити відомі залишки після оновлення, як-от відсутній шлях до вбудованого plugin або застарілий запис `channels.` +`allowInvalidConfigRecovery` не є загальним обхідним шляхом для зламаних конфігурацій. Воно призначене +лише для вузького відновлення вбудованих plugin, щоб перевстановлення/налаштування могли виправити відомі +залишки після оновлення, як-от відсутній шлях до вбудованого plugin або застарілий запис `channels.` для цього самого plugin. Якщо конфігурація зламана з не пов’язаних причин, встановлення -усе одно завершується безпечною відмовою та повідомляє оператору виконати `openclaw doctor --fix`. +усе одно завершується з відмовою та повідомляє оператору запустити `openclaw doctor --fix`. ### Відкладене повне завантаження @@ -216,26 +215,25 @@ Channel plugins можуть увімкнути відкладене заван } ``` -Коли цю опцію ввімкнено, OpenClaw завантажує лише `setupEntry` на фазі запуску -до початку прослуховування, навіть для вже налаштованих каналів. Повний запис завантажується після того, -як Gateway починає прослуховування. +Коли це ввімкнено, OpenClaw завантажує лише `setupEntry` під час фази запуску до початку прослуховування, +навіть для вже налаштованих channel. Повна точка входу завантажується після того, як Gateway починає прослуховування. - Вмикайте відкладене завантаження лише тоді, коли ваш `setupEntry` реєструє все, - що потрібно Gateway до початку прослуховування (реєстрація каналу, HTTP-маршрути, - методи Gateway). Якщо повний запис володіє необхідними можливостями запуску, зберігайте - стандартну поведінку. + Увімкнюйте відкладене завантаження лише тоді, коли ваш `setupEntry` реєструє все, що + потрібно Gateway до початку прослуховування (реєстрація channel, HTTP-маршрути, методи + Gateway). Якщо повна точка входу володіє потрібними можливостями запуску, зберігайте + поведінку за замовчуванням. -Якщо ваш запис налаштування/повний запис реєструє RPC-методи Gateway, залишайте їх на -префіксі, специфічному для plugin. Зарезервовані простори назв адміністратора ядра (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються під контролем ядра й завжди зіставляються +Якщо ваша точка входу налаштування/повна точка входу реєструє методи Gateway RPC, зберігайте їх +на префіксі, специфічному для plugin. Зарезервовані простори імен базового адміністратора (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються у володінні core і завжди зіставляються з `operator.admin`. ## Маніфест plugin -Кожен native plugin має постачати `openclaw.plugin.json` у корені пакета. -OpenClaw використовує його для валідації конфігурації без виконання коду plugin. +Кожен нативний plugin має постачатися з `openclaw.plugin.json` у корені пакета. +OpenClaw використовує його для перевірки конфігурації без виконання коду plugin. ```json { @@ -270,7 +268,7 @@ OpenClaw використовує його для валідації конфі } ``` -Навіть plugins без конфігурації мають постачати схему. Порожня схема є валідною: +Навіть plugins без конфігурації мають постачатися зі схемою. Порожня схема є допустимою: ```json { @@ -282,25 +280,25 @@ OpenClaw використовує його для валідації конфі } ``` -Див. [Plugin Manifest](/uk/plugins/manifest), щоб ознайомитися з повним довідником щодо схеми. +Див. [Plugin Manifest](/uk/plugins/manifest) для повного довідника зі схеми. ## Публікація в ClawHub -Для пакетів plugin використовуйте команду ClawHub, призначену саме для пакетів: +Для пакетів plugin використовуйте команду ClawHub, специфічну для пакетів: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Застарілий псевдонім публікації лише для skills призначений для Skills. Пакети plugin +Застарілий псевдонім публікації лише для Skills призначений для Skills. Пакети plugin завжди мають використовувати `clawhub package publish`. -## Запис налаштування +## Точка входу налаштування Файл `setup-entry.ts` — це полегшена альтернатива `index.ts`, яку OpenClaw завантажує, коли йому потрібні лише поверхні налаштування (онбординг, відновлення конфігурації, -перевірка вимкнених каналів). +перевірка вимкнених channel). ```typescript // setup-entry.ts @@ -310,19 +308,19 @@ import { myChannelPlugin } from "./src/channel.js"; export default defineSetupPluginEntry(myChannelPlugin); ``` -Це дає змогу уникнути завантаження важкого runtime-коду (криптобібліотек, CLI-реєстрацій, +Це дає змогу уникнути завантаження важкого runtime-коду (криптобібліотек, реєстрацій CLI, фонових сервісів) під час потоків налаштування. -Вбудовані workspace-канали, які тримають безпечні для налаштування експорти в sidecar-модулях, можуть +Вбудовані workspace channel, які зберігають безпечні для налаштування експорти в sidecar-модулях, можуть використовувати `defineBundledChannelSetupEntry(...)` з `openclaw/plugin-sdk/channel-entry-contract` замість `defineSetupPluginEntry(...)`. Цей вбудований контракт також підтримує необов’язковий -експорт `runtime`, щоб wiring runtime під час налаштування залишався легким і явним. +експорт `runtime`, тож прив’язування runtime під час налаштування може залишатися легким і явним. -**Коли OpenClaw використовує `setupEntry` замість повного запису:** +**Коли OpenClaw використовує `setupEntry` замість повної точки входу:** -- Канал вимкнено, але потрібні поверхні налаштування/онбордингу -- Канал увімкнено, але не налаштовано +- Channel вимкнений, але потребує поверхонь налаштування/онбордингу +- Channel увімкнений, але не налаштований - Увімкнено відкладене завантаження (`deferConfiguredChannelFullLoadUntilAfterListen`) **Що має реєструвати `setupEntry`:** @@ -331,60 +329,59 @@ export default defineSetupPluginEntry(myChannelPlugin); - Будь-які HTTP-маршрути, потрібні до початку прослуховування Gateway - Будь-які методи Gateway, потрібні під час запуску -Ці методи Gateway для запуску все одно мають уникати зарезервованих просторів -назв адміністратора ядра, таких як `config.*` або `update.*`. +Ці методи Gateway для запуску все одно мають уникати зарезервованих просторів імен +базового адміністратора, таких як `config.*` або `update.*`. -**Що НЕ має містити `setupEntry`:** +**Що НЕ має включати `setupEntry`:** -- CLI-реєстрації +- Реєстрації CLI - Фонові сервіси - Важкі runtime-імпорти (crypto, SDK) - Методи Gateway, потрібні лише після запуску ### Вузькі імпорти допоміжних засобів налаштування -Для гарячих шляхів лише налаштування надавайте перевагу вузьким seam-допоміжним засобам налаштування замість ширшого -парасолькового `plugin-sdk/setup`, коли вам потрібна лише частина поверхні налаштування: +Для гарячих шляхів лише налаштування надавайте перевагу вузьким швам допоміжних засобів налаштування замість ширшого +узагальненого `plugin-sdk/setup`, коли вам потрібна лише частина поверхні налаштування: -| Шлях імпорту | Використовуйте для | Ключові експорти | -| ---------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/setup-runtime` | допоміжні runtime-засоби для часу налаштування, які лишаються доступними в `setupEntry` / під час відкладеного запуску каналу | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | -| `plugin-sdk/setup-adapter-runtime` | адаптери налаштування облікових записів із урахуванням середовища | `createEnvPatchedAccountSetupAdapter` | -| `plugin-sdk/setup-tools` | допоміжні CLI/archive/docs-засоби для налаштування/встановлення | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | +| Шлях імпорту | Для чого використовувати | Ключові експорти | +| --------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/setup-runtime` | допоміжні засоби runtime під час налаштування, які лишаються доступними в `setupEntry` / відкладеному запуску channel | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | +| `plugin-sdk/setup-adapter-runtime` | адаптери налаштування облікових записів з урахуванням середовища | `createEnvPatchedAccountSetupAdapter` | +| `plugin-sdk/setup-tools` | допоміжні засоби налаштування/встановлення CLI/архівів/документації | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | -Використовуйте ширший seam `plugin-sdk/setup`, коли вам потрібен повний спільний -набір інструментів налаштування, включно з допоміжними засобами для латання конфігурації, такими як +Використовуйте ширший шов `plugin-sdk/setup`, коли вам потрібен повний спільний +набір інструментів налаштування, включно з допоміжними засобами patch-конфігурації, такими як `moveSingleAccountChannelSectionToDefaultAccount(...)`. -Адаптери латання налаштування лишаються безпечними для імпорту на гарячому шляху. Їхній вбудований -відкладений пошук поверхні контракту просування одного облікового запису є lazy, тому імпорт -`plugin-sdk/setup-runtime` не виконує завчасне завантаження виявлення поверхні вбудованого контракту до того, як адаптер фактично буде використано. +Адаптери patch для налаштування залишаються безпечними для гарячого шляху під час імпорту. Їхній вбудований +ледачий пошук поверхні контракту для просування single-account, тож імпорт +`plugin-sdk/setup-runtime` не завантажує передчасно виявлення поверхні вбудованого контракту до того, як адаптер справді буде використано. -### Просування одного облікового запису, кероване каналом +### Просування single-account, що належить channel -Коли канал оновлюється з верхньорівневої конфігурації одного облікового запису до -`channels..accounts.*`, типовою спільною поведінкою є переміщення значень -області облікового запису, що просуваються, у `accounts.default`. +Коли channel оновлюється з однокористувацької конфігурації верхнього рівня до +`channels..accounts.*`, типова спільна поведінка полягає в тому, щоб перемістити просунуті +значення з областю облікового запису в `accounts.default`. -Вбудовані канали можуть звузити або перевизначити це просування через свою поверхню -контракту налаштування: +Вбудовані channel можуть звузити або перевизначити це просування через свою поверхню контракту налаштування: -- `singleAccountKeysToMove`: додаткові ключі верхнього рівня, які слід перемістити до - просунутого облікового запису -- `namedAccountPromotionKeys`: якщо іменовані облікові записи вже існують, лише ці - ключі переміщуються до просунутого облікового запису; спільні ключі policy/delivery залишаються в корені - каналу -- `resolveSingleAccountPromotionTarget(...)`: вибір наявного облікового запису, - який отримає просунуті значення +- `singleAccountKeysToMove`: додаткові ключі верхнього рівня, які слід перемістити в + просунутий обліковий запис +- `namedAccountPromotionKeys`: коли іменовані облікові записи вже існують, лише ці + ключі переміщуються в просунутий обліковий запис; спільні ключі policy/delivery залишаються в корені + channel +- `resolveSingleAccountPromotionTarget(...)`: вибирає, який наявний обліковий запис + отримає просунуті значення -Matrix є поточним вбудованим прикладом. Якщо вже існує рівно один іменований обліковий запис Matrix, -або якщо `defaultAccount` вказує на наявний неканонічний ключ, наприклад -`Ops`, просування зберігає цей обліковий запис замість створення нового запису +Matrix — поточний вбудований приклад. Якщо вже існує рівно один іменований обліковий запис Matrix, +або якщо `defaultAccount` вказує на наявний неканонічний ключ, такий як `Ops`, +просування зберігає цей обліковий запис замість створення нового запису `accounts.default`. ## Схема конфігурації -Конфігурація plugin проходить валідацію за JSON Schema у вашому маніфесті. Користувачі +Конфігурація Plugin перевіряється за JSON Schema у вашому маніфесті. Користувачі налаштовують plugins через: ```json5 @@ -401,9 +398,9 @@ Matrix є поточним вбудованим прикладом. Якщо в } ``` -Під час реєстрації ваш plugin отримує цю конфігурацію як `api.pluginConfig`. +Ваш plugin отримує цю конфігурацію як `api.pluginConfig` під час реєстрації. -Для конфігурації, специфічної для каналу, використовуйте натомість розділ конфігурації каналу: +Для конфігурації, специфічної для channel, використовуйте натомість розділ конфігурації channel: ```json5 { @@ -416,10 +413,10 @@ Matrix є поточним вбудованим прикладом. Якщо в } ``` -### Побудова схем конфігурації каналу +### Побудова схем конфігурації channel Використовуйте `buildChannelConfigSchema` з `openclaw/plugin-sdk/core`, щоб перетворити -схему Zod на обгортку `ChannelConfigSchema`, яку OpenClaw валідує: +схему Zod на обгортку `ChannelConfigSchema`, яку перевіряє OpenClaw: ```typescript import { z } from "zod"; @@ -472,19 +469,19 @@ const setupWizard: ChannelSetupWizard = { ``` Тип `ChannelSetupWizard` підтримує `credentials`, `textInputs`, -`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` та інші можливості. -Див. пакети вбудованих plugin (наприклад, plugin Discord `src/channel.setup.ts`), щоб ознайомитися з -повними прикладами. +`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` тощо. +Дивіться вбудовані пакети plugin (наприклад, plugin Discord `src/channel.setup.ts`) для +повних прикладів. -Для запитів allowlist у DM, яким потрібен лише стандартний потік +Для запитів щодо allowlist у DM, яким потрібен лише стандартний потік `note -> prompt -> parse -> merge -> patch`, надавайте перевагу спільним допоміжним засобам налаштування з `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`, `createTopLevelChannelParsedAllowFromPrompt(...)` і `createNestedChannelParsedAllowFromPrompt(...)`. -Для блоків статусу налаштування каналу, які відрізняються лише назвами, оцінками та необов’язковими +Для блоків статусу налаштування channel, які відрізняються лише ярликами, оцінками та необов’язковими додатковими рядками, надавайте перевагу `createStandardChannelSetupStatus(...)` з -`openclaw/plugin-sdk/setup` замість ручного створення того самого об’єкта `status` у +`openclaw/plugin-sdk/setup` замість ручного відтворення того самого об’єкта `status` у кожному plugin. Для необов’язкових поверхонь налаштування, які мають з’являтися лише в певних контекстах, використовуйте @@ -499,28 +496,28 @@ const setupSurface = createOptionalChannelSetupSurface({ npmSpec: "@myorg/openclaw-my-channel", docsPath: "/channels/my-channel", }); -// Returns { setupAdapter, setupWizard } +// Повертає { setupAdapter, setupWizard } ``` -`plugin-sdk/channel-setup` також надає lower-level -білдери `createOptionalChannelSetupAdapter(...)` і +`plugin-sdk/channel-setup` також надає нижчорівневі +будівники `createOptionalChannelSetupAdapter(...)` і `createOptionalChannelSetupWizard(...)`, коли вам потрібна лише одна половина цієї необов’язкової поверхні встановлення. -Згенеровані необов’язкові adapter/wizard завершуються безпечною відмовою на реальних записах конфігурації. Вони +Згенеровані необов’язкові адаптер/майстер завершуються з відмовою на реальних записах конфігурації. Вони повторно використовують одне повідомлення про необхідність встановлення в `validateInput`, -`applyAccountConfig` і `finalize`, а також додають посилання на документацію, якщо задано `docsPath`. +`applyAccountConfig` і `finalize`, а також додають посилання на документацію, якщо встановлено `docsPath`. -Для UI налаштування, що працюють із двійковими файлами, надавайте перевагу спільним делегованим допоміжним засобам замість -копіювання тієї самої логіки двійкових файлів/статусу в кожен канал: +Для UI налаштування, що працюють через binary, надавайте перевагу спільним делегованим допоміжним засобам замість +копіювання однакової логіки binary/status у кожний channel: -- `createDetectedBinaryStatus(...)` для блоків статусу, які відрізняються лише назвами, - підказками, оцінками та визначенням двійкового файла +- `createDetectedBinaryStatus(...)` для блоків статусу, що відрізняються лише ярликами, + підказками, оцінками та виявленням binary - `createCliPathTextInput(...)` для текстових полів на основі шляху - `createDelegatedSetupWizardStatusResolvers(...)`, `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` і - `createDelegatedResolveConfigured(...)`, коли `setupEntry` має ліниво передавати керування - важчому повному майстру + `createDelegatedResolveConfigured(...)`, коли `setupEntry` має ліниво пересилати до + важчого повного майстра - `createDelegatedTextInputShouldPrompt(...)`, коли `setupEntry` має лише делегувати рішення `textInputs[*].shouldPrompt` @@ -532,15 +529,15 @@ const setupSurface = createOptionalChannelSetupSurface({ openclaw plugins install @myorg/openclaw-my-plugin ``` -OpenClaw спочатку намагається використати ClawHub і автоматично переходить до npm у разі невдачі. Ви також можете -явно примусово використати ClawHub: +OpenClaw спочатку пробує ClawHub і автоматично переходить на npm у разі невдачі. Ви також можете +явно примусово використовувати ClawHub: ```bash -openclaw plugins install clawhub:@myorg/openclaw-my-plugin # лише ClawHub +openclaw plugins install clawhub:@myorg/openclaw-my-plugin # Лише ClawHub ``` -Відповідного перевизначення `npm:` не існує. Використовуйте звичайний npm package spec, коли -потрібен шлях npm після переходу з ClawHub: +Відповідного перевизначення `npm:` не існує. Використовуйте звичайну специфікацію npm-пакета, коли +вам потрібен шлях npm після переходу з ClawHub: ```bash openclaw plugins install @myorg/openclaw-my-plugin @@ -556,19 +553,19 @@ openclaw plugins install ``` - Для встановлень із npm `openclaw plugins install` виконує - `npm install --ignore-scripts` (без lifecycle scripts). Підтримуйте дерева залежностей plugin - чистими JS/TS і уникайте пакетів, які потребують збірок через `postinstall`. + Для встановлень із джерела npm `openclaw plugins install` запускає + `npm install --ignore-scripts` (без lifecycle scripts). Зберігайте дерево залежностей plugin + чистим JS/TS і уникайте пакетів, які потребують збірок `postinstall`. -Вбудовані plugins, якими володіє OpenClaw, — єдиний виняток для відновлення під час запуску: коли -пакетне встановлення бачить один із них увімкненим через конфігурацію plugin, застарілу конфігурацію каналу або -його вбудований маніфест із увімкненням за замовчуванням, запуск встановлює відсутні -runtime-залежності цього plugin перед імпортом. Сторонні plugins не повинні покладатися на -встановлення під час запуску; і далі використовуйте явний інсталятор plugin. +Вбудовані plugins, що належать OpenClaw, — єдиний виняток для відновлення під час запуску: коли +пакетне встановлення бачить один із них увімкненим через конфігурацію plugin, застарілу конфігурацію channel або +його вбудований маніфест із увімкненням за замовчуванням, під час запуску встановлюються відсутні +runtime-залежності цього plugin до імпорту. Сторонні plugins не повинні покладатися на +встановлення під час запуску; продовжуйте використовувати явний інсталятор plugin. -## Пов’язане +## Пов’язані матеріали - [SDK Entry Points](/uk/plugins/sdk-entrypoints) -- `definePluginEntry` і `defineChannelPluginEntry` -- [Plugin Manifest](/uk/plugins/manifest) -- повний довідник щодо схеми маніфесту +- [Plugin Manifest](/uk/plugins/manifest) -- повний довідник зі схемою маніфесту - [Building Plugins](/uk/plugins/building-plugins) -- покроковий посібник для початку роботи