diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 6e8ddba27..39a045d32 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -3,18 +3,18 @@ read_when: - Запуск тестів локально або в CI - Додавання регресійних тестів для помилок моделей/провайдерів - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: unit/e2e/live набори, Docker runners і що охоплює кожен тест' +summary: 'Набір для тестування: unit/e2e/live набори, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-23T23:27:49Z" + generated_at: "2026-04-24T00:42:37Z" model: gpt-5.4 provider: openai - source_hash: 5bb91a95c7b56825fe20a816a81603a9f3afe1bf62dbe20a2d500cefac27d798 + source_hash: bf98cc453740fefbd85fd453ec0fc2f08b3546f99aa62a4fd50c01f303314c94 source_path: help/testing.md workflow: 15 --- -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker runners. Цей документ — посібник «як ми тестуємо»: +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює). - Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). @@ -26,142 +26,139 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не У більшості випадків: - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск повного набору на машині з достатніми ресурсами: `pnpm test:max` +- Швидший локальний запуск усього набору на потужній машині: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` -- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Пряме націлення на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` - Під час роботи над однією помилкою спочатку віддавайте перевагу цільовим запускам. -- QA-сайт на базі 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` -Коли ви торкаєтеся тестів або хочете більше впевненості: +Коли ви змінюєте тести або хочете більше впевненості: -- Gate покриття: `pnpm test:coverage` +- Coverage gate: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + зонди інструментів/зображень Gateway): `pnpm test:live` -- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Live-перевірка моделей у Docker: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер виконує текстовий хід плюс невеликий зонд у стилі читання файлу. - Моделі, чиї метадані оголошують вхід `image`, також виконують невеликий хід із зображенням. - Вимкніть додаткові зонди за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або +- Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` +- Тихо націлити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Docker live-перебір моделей: `pnpm test:docker:live-models` + - Кожна вибрана модель тепер виконує текстовий хід плюс невелику перевірку в стилі читання файлу. + Моделі, у чиїх метаданих заявлено вхід `image`, також виконують маленький хід із зображенням. + Вимкніть додаткові перевірки за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - Покриття CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні - `OpenClaw Release Checks` обидва викликають багаторазово використовуваний workflow live/E2E з - `include_live_suites: true`, який включає окремі Docker live model - matrix jobs, розшардовані за провайдером. - - Для точкових повторних запусків у CI викличте `OpenClaw Live And E2E Checks (Reusable)` + `OpenClaw Release Checks` обидва викликають повторно використовуваний workflow live/E2E з + `include_live_suites: true`, який містить окремі Docker live model + matrix jobs, розшардені за провайдером. + - Для цільових повторних запусків CI викликайте `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, - а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його - викликачів scheduled/release. -- Перевірка вартості Moonshot/Kimi: коли встановлено `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, а потім ізольований + - Додавайте нові high-signal секрети провайдерів до `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 і що - стенограма помічника зберігає нормалізоване `usage.cost`. + для `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє про Moonshot/K2.6 і що + transcript помічника зберігає нормалізоване `usage.cost`. -Порада: коли вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. +Порада: якщо вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через env-змінні allowlist, описані нижче. -## QA-специфічні runners +## QA-специфічні ранери -Ці команди розташовані поруч з основними наборами тестів, коли вам потрібна реалістичність QA-lab: +Ці команди розміщені поруч з основними наборами тестів, коли вам потрібен реалізм qa-lab: -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` +CI запускає QA Lab в окремих workflow. `Parity gate` виконується для відповідних PR і +при ручному виклику з mock-провайдерами. `QA-Lab - All Lanes` виконується щоночі на +`main` і при ручному виклику з mock parity gate, live Matrix lane і +Convex-керованою live lane Telegram як паралельними job. `OpenClaw Release Checks` запускає ті самі lane перед затвердженням релізу. - `pnpm openclaw qa suite` - - Запускає repo-backed QA-сценарії безпосередньо на хості. + - Запускає QA-сценарії з репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - Gateway workers. `qa-channel` за замовчуванням має concurrency 4 (обмежено - кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати - кількість workers, або `--concurrency 1` для старого послідовного lane. - - Завершується з ненульовим кодом, якщо якийсь сценарій завершується невдачею. Використовуйте `--allow-failures`, коли + workers Gateway. Для `qa-channel` типовим є concurrency 4 (обмежено + кількістю вибраних сценаріїв). Використовуйте `--concurrency ` для налаштування + кількості workers або `--concurrency 1` для старішої послідовної lane. + - Завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, якщо ви хочете отримати артефакти без коду завершення з помилкою. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття фікстур і mock-покриття протоколу, не замінюючи сценарно-орієнтований - lane `mock-openai`. + `aimock` запускає локальний сервер провайдера на основі AIMock для експериментального + покриття фікстурами та імітацією протоколу, не замінюючи + lane `mock-openai`, орієнтовану на сценарії. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. + - Запускає той самий QA-набір у тимчасовій Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані вхідні дані QA auth, практичні для guest: - ключі провайдерів на основі env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, - якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через - змонтований workspace. - - Записує звичайний QA-звіт + підсумок, а також логи Multipass до + - Live-запуски пересилають підтримувані QA-входи автентифікації, які практично передати в гостьову систему: + ключі провайдерів через env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через + змонтований робочий простір. + - Записує звичайні QA report + summary, а також логи Multipass до `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. + - Запускає QA-сайт на основі Docker для QA-роботи в операторському стилі. - `pnpm test:docker:npm-onboard-channel-agent` - Збирає npm tarball з поточного checkout, глобально встановлює його в - Docker, виконує неінтерактивне onboarding з ключем OpenAI API, за замовчуванням налаштовує - Telegram, перевіряє, що ввімкнення Plugin встановлює runtime-залежності за потреби, + Docker, виконує неінтерактивний онбординг із ключем API OpenAI, за замовчуванням налаштовує Telegram, + перевіряє, що ввімкнення Plugin встановлює runtime-залежності на вимогу, запускає doctor і виконує один локальний хід агента проти змоканого endpoint OpenAI. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий - lane пакетного встановлення з Discord. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму + lane встановлення з пакета з Discord. - `pnpm test:docker:bundled-channel-deps` - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає bundled channel/plugins через - редагування конфігурації. - - Перевіряє, що виявлення setup залишає runtime-залежності - не налаштованих plugin відсутніми, перший налаштований запуск Gateway або doctor встановлює - runtime-залежності кожного bundled plugin за потреби, а другий перезапуск не - перевстановлює залежності, які вже були активовані. - - Також встановлює відому старішу базову версію npm, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що doctor кандидата - після оновлення відновлює runtime-залежності bundled channel без - відновлення postinstall з боку harness. + з налаштованим OpenAI, а потім вмикає вбудовані channel/plugin через редагування конфігурації. + - Перевіряє, що виявлення налаштування залишає runtime-залежності + неналаштованих Plugin відсутніми, що перший налаштований запуск Gateway або doctor встановлює + runtime-залежності кожного вбудованого Plugin на вимогу, і що другий перезапуск не перевстановлює + залежності, які вже були активовані. + - Також встановлює відому старішу npm baseline, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що + post-update doctor кандидата відновлює runtime-залежності вбудованого channel без + postinstall-відновлення з боку harness. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування - протоколу. + - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на базі Docker. + - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на основі Docker. - Цей QA-хост наразі призначений лише для repo/dev. Пакетні встановлення OpenClaw не постачають `qa-lab`, тому вони не надають `openclaw qa`. - - 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 локально надає тимчасових користувачів. - - Записує QA-звіт Matrix, підсумок, артефакт observed-events і комбінований лог виводу stdout/stderr до `.artifacts/qa-e2e/...`. + - 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 локально створює тимчасових користувачів. + - Записує report Matrix QA, summary, артефакт observed-events і поєднаний лог виводу stdout/stderr до `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени bot driver і SUT із env. - - Потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим ідентифікатором чату Telegram. - - Підтримує `--credential-source convex` для спільних пулованих облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути пуловані lease. - - Завершується з ненульовим кодом, якщо якийсь сценарій завершується невдачею. Використовуйте `--allow-failures`, коли + - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени bot driver і SUT з env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. + - Підтримує `--credential-source convex` для спільних пулових облікових даних. Типово використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. + - Завершується з ненульовим кодом, якщо будь-який сценарій завершується помилкою. Використовуйте `--allow-failures`, якщо ви хочете отримати артефакти без коду завершення з помилкою. - - Потрібні два різні боти в одній приватній групі, причому bot SUT має надавати ім’я користувача Telegram. - - Для стабільного спостереження bot-to-bot увімкніть режим Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що bot driver може спостерігати трафік ботів у групі. - - Записує QA-звіт Telegram, підсумок і артефакт observed-messages до `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту надсилання driver до спостережуваної відповіді SUT. + - Потребує двох різних bot в одній приватній групі, причому bot SUT має мати Telegram username. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох bot і переконайтеся, що bot driver може спостерігати трафік bot у групі. + - Записує report Telegram QA, summary і артефакт observed-messages до `.artifacts/qa-e2e/...`. Сценарії reply містять RTT від запиту на надсилання driver до спостереженої відповіді SUT. -Live transport lane використовують один стандартний контракт, щоб нові транспорти не розходилися: +Live transport lane поділяють один стандартний контракт, щоб нові транспорти не розходилися: -`qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live transport. +`qa-channel` залишається широким синтетичним QA-набором і не є частиною матриці покриття live transport. -| Lane | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у thread | Ізоляція thread | Спостереження за реакціями | Команда 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) -Коли для `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 виконується, і звільняє оренду під час завершення роботи. Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові змінні середовища: +Обов’язкові env-змінні: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` @@ -169,7 +166,7 @@ QA lab отримує ексклюзивний lease із пулу на базі - CLI: `--credential-role maintainer|ci` - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) -Необов’язкові змінні середовища: +Необов’язкові env-змінні: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) @@ -181,10 +178,10 @@ QA lab отримує ексклюзивний lease із пулу на базі `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 @@ -192,9 +189,9 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `--json` для машиночитаного виводу в скриптах і CI-утилітах. +Використовуйте `--json` для машинозчитуваного виводу в скриптах і CI-утилітах. -Контракт типового endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -206,74 +203,74 @@ pnpm openclaw qa credentials remove --credential-id - `POST /release` - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Успіх: `{ status: "ok" }` (або порожній `2xx`) -- `POST /admin/add` (лише секрет maintainer) +- `POST /admin/add` (лише для секрету maintainer) - Запит: `{ kind, actorId, payload, note?, status? }` - Успіх: `{ status: "ok", credential }` -- `POST /admin/remove` (лише секрет maintainer) +- `POST /admin/remove` (лише для секрету 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` (лише для секрету maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` -Форма payload для типу Telegram: +Форма payload для Telegram kind: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком числового ідентифікатора чату Telegram. +- `groupId` має бути рядком із числовим Telegram chat id. - `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні payload. -### Додавання каналу до QA +### Додавання channel до QA -Додавання каналу до markdown-системи QA вимагає рівно двох речей: +Додавання channel до markdown-системи QA потребує рівно двох речей: -1. Адаптера транспорту для каналу. -2. Набору сценаріїв, що перевіряє контракт каналу. +1. Transport adapter для channel. +2. Scenario pack, який перевіряє контракт channel. Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може -володіти цим потоком. +керувати цим потоком. -`qa-lab` відповідає за спільні механізми хоста: +`qa-lab` відповідає за спільну хостову механіку: -- кореневий командний простір `openclaw qa` -- запуск і завершення набору +- кореневий простір команд `openclaw qa` +- запуск і завершення suite - concurrency workers - запис артефактів -- генерацію звітів +- генерацію report - виконання сценаріїв -- alias сумісності для старіших сценаріїв `qa-channel` +- compatibility aliases для старіших сценаріїв `qa-channel` Runner plugins відповідають за транспортний контракт: - як `openclaw qa ` монтується під спільним коренем `qa` - як Gateway налаштовується для цього транспорту - як перевіряється готовність -- як ін’єктуються вхідні події +- як інжектяться вхідні події - як спостерігаються вихідні повідомлення -- як надаються стенограми та нормалізований стан транспорту +- як надаються transcript і нормалізований стан транспорту - як виконуються дії, підкріплені транспортом -- як обробляється скидання або очищення, специфічні для транспорту +- як обробляється transport-specific reset або cleanup -Мінімальний поріг впровадження для нового каналу: +Мінімальний поріг впровадження для нового channel: 1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте transport runner на спільному seam хоста `qa-lab`. -3. Залишайте механіку, специфічну для транспорту, всередині runner plugin або harness каналу. +2. Реалізуйте transport runner на спільному хостовому seam `qa-lab`. +3. Зберігайте transport-specific механіку всередині runner plugin або channel harness. 4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. - Залишайте `runtime-api.ts` легким; відкладене виконання CLI і runner має залишатися за окремими entrypoint. + Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. + Тримайте `runtime-api.ts` легким; відкладене виконання CLI та runner має залишатися за окремими entrypoint. 5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте загальні helper-и сценаріїв для нових сценаріїв. -7. Зберігайте роботу наявних alias сумісності, якщо тільки репозиторій не виконує навмисну міграцію. +6. Використовуйте generic scenario helpers для нових сценаріїв. +7. Зберігайте наявні compatibility aliases робочими, якщо тільки репозиторій не виконує навмисну міграцію. -Правило прийняття рішення суворе: +Правило ухвалення рішень суворе: -- Якщо поведінку можна виразити один раз у `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від транспорту одного каналу, зберігайте її в цьому runner plugin або harness plugin. -- Якщо сценарію потрібна нова можливість, яку може використовувати більш ніж один канал, додавайте загальний helper замість гілки, специфічної для каналу, у `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту й явно зазначайте це в контракті сценарію. +- Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. +- Якщо поведінка залежить від одного channel transport, залишайте її в цьому runner plugin або plugin harness. +- Якщо сценарію потрібна нова можливість, яку можуть використовувати більше ніж один channel, додавайте generic helper замість channel-specific гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно вказуйте це в контракті сценарію. -Бажані назви загальних helper-ів для нових сценаріїв: +Бажані назви generic helper для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -288,7 +285,7 @@ Runner plugins відповідають за транспортний контр - `formatTransportTranscript` - `resetTransport` -Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: +Compatibility aliases залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -296,294 +293,294 @@ Alias сумісності залишаються доступними для н - `formatConversationTranscript` - `resetBus` -Нова робота над каналами має використовувати загальні назви helper-ів. -Alias сумісності існують, щоб уникнути міграції одним днем, а не як модель для +Нова робота з channel має використовувати generic helper names. +Compatibility aliases існують, щоб уникнути міграції в стилі flag day, а не як модель для створення нових сценаріїв. -## Набори тестів (що і де запускається) +## Набори тестів (що де запускається) -Думайте про ці набори як про «зростання реалістичності» (і зростання нестабільності/вартості): +Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: ненацілені запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project shard-и в конфігурації для кожного проєкту для паралельного планування -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, охоплені `vitest.unit.config.ts` +- Config: нецільові запуски використовують набір shard `vitest.full-*.config.ts` і можуть розгортати multi-project shards у per-project config для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelist-тести `ui` для node, охоплені `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - In-process integration-тести (gateway auth, маршрутизація, tooling, parsing, config) + - In-process integration-тести (автентифікація Gateway, маршрутизація, інструменти, парсинг, конфігурація) - Детерміновані регресії для відомих помилок - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним - - Ненацілені запуски `pnpm test` використовують дванадцять менших shard-конфігурацій (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського процесу native root-project. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - `pnpm test --watch` усе ще використовує native-граф проєктів root `vitest.config.ts`, тому що multi-shard цикл watch непрактичний. - `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 торкається лише маршрутизованих файлів source/test; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. - `pnpm check:changed` — це типовий розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, метадані релізу й tooling, а потім запускає відповідні lane typecheck/lint/test. Зміни публічного Plugin SDK і plugin-contract включають один прохід перевірки extension, оскільки extensions залежать від цих контрактів core. Оновлення версій лише в метаданих релізу запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, що відхиляє зміни package поза полем версії верхнього рівня. - Легкі щодо імпортів unit-тести з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` та подібних чистих утилітних областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються в наявних lane. - Вибрані файли source helper-ів `plugin-sdk` і `commands` також відображають запуски в режимі changed на явні sibling-тести в цих легких lane, тому редагування helper-ів уникає повторного запуску повного важкого набору для цього каталогу. - `auto-reply` має три окремі bucket: helper-и core верхнього рівня, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply поза дешевими тестами status/chunk/token. + - Нецільовий `pnpm test` запускає дванадцять менших shard config (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project process. Це знижує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - `pnpm test --watch` усе ще використовує native root `vitest.config.ts` project graph, тому що multi-shard watch loop непрактичний. - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні file/directory targets через 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 включають один додатковий прохід перевірки extension, оскільки extensions залежать від цих core-контрактів. Оновлення версій лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, що відхиляє зміни package поза верхньорівневим полем version. - Unit-тести з малими імпортами з agents, commands, plugins, допоміжних засобів 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: top-level core helpers, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply поза дешевими тестами status/chunk/token. - - - Коли ви змінюєте входи виявлення message-tool або runtime-контекст Compaction, + + - Коли ви змінюєте входи виявлення message-tool або runtime-контекст compaction, зберігайте обидва рівні покриття. - - Додавайте точкові helper-регресії для чистих меж маршрутизації та нормалізації. - - Підтримуйте вбудовані integration-набори runner у здоровому стані: + - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації та нормалізації. + - Підтримуйте справність integration-наборів embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка Compaction усе ще проходять - через реальні шляхи `run.ts` / `compact.ts`; тести лише для helper-ів не є + - Ці набори перевіряють, що scoped id і поведінка compaction і далі проходять + через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є достатньою заміною для цих integration-шляхів. - - Базова конфігурація Vitest за замовчуванням використовує `threads`. - - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - неізольований runner у конфігураціях root projects, e2e і live. - - Root UI lane зберігає своє налаштування `jsdom` та optimizer, але також працює на - спільному неізольованому runner. + - Базова config Vitest типово використовує `threads`. + - Спільна config Vitest фіксує `isolate: false` і використовує + non-isolated runner у root projects, e2e і live config. + - Коренева lane UI зберігає свій `jsdom` setup і optimizer, але теж працює на + спільному non-isolated runner. - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` - зі спільної конфігурації Vitest. - - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх процесів Node Vitest, + зі спільної config Vitest. + - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. - Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною - поведінкою V8. + Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - - `pnpm changed:lanes` показує, які архітектурні lane запускає diff. - - Pre-commit hook відповідає лише за форматування. Він повторно додає відформатовані файли до staging і - не запускає lint, typecheck чи тести. + - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. + - Pre-commit hook лише форматує. Він повторно індексує відформатовані файли і + не запускає lint, typecheck або тести. - Явно запускайте `pnpm check:changed` перед передачею роботи або push, коли вам - потрібен розумний локальний gate. Зміни публічного Plugin SDK і plugin-contract + потрібен smart local gate. Зміни публічного Plugin SDK і plugin-contract включають один прохід перевірки extension. - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи - однозначно відображаються на менший набір. + чітко відповідають меншому набору. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - лише з вищою межею workers. - - Автоматичне масштабування локальних workers навмисно консервативне й зменшує навантаження, - коли середнє навантаження хоста вже високе, тому кілька одночасних + лише з вищою межею кількості workers. + - Автомасштабування локальних workers навмисно консервативне і зменшує навантаження, + коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest типово завдають менше шкоди. - - Базова конфігурація Vitest позначає файли projects/config як - `forceRerunTriggers`, щоб повторні запуски в режимі changed лишалися коректними, коли змінюється тестова обв’язка. - - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних - хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + - Базова config Vitest позначає проєкти/config files як + `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, + коли змінюється wiring тестів. + - Config зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту плюс - вивід деталізації імпорту. - - `pnpm test:perf:imports:changed` звужує той самий вигляд профілювання до - файлів, змінених від `origin/main`. + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту, а також + вивід breakdown імпорту. + - `pnpm test:perf:imports:changed` обмежує той самий профілювальний вигляд + файлами, зміненими відносно `origin/main`. - Коли один гарячий тест усе ще витрачає більшість часу на стартові імпорти, тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і - напряму мокайте цей seam замість deep-import runtime-helper-ів лише - для того, щоб передати їх через `vi.mock(...)`. + напряму змокайте цей seam замість deep-import runtime helpers + лише для того, щоб передати їх через `vi.mock(...)`. - `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` і кореневу конфігурацію Vitest. + `test:changed` із native root-project шляхом для цього зафіксованого + diff і виводить wall time та macOS max RSS. + - `pnpm test:perf:changed:bench -- --worktree` вимірює поточне + брудне дерево, маршрутизуючи список змінених файлів через + `scripts/test-projects.mjs` і кореневу config Vitest. - `pnpm test:perf:profile:main` записує профіль CPU основного потоку для - накладних витрат запуску та transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує профілі CPU+heap для runner - unit-набору з вимкненим паралелізмом за файлами. + накладних витрат запуску й трансформації Vitest/Vite. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner для + unit-набору з вимкненим паралелізмом файлів. ### Stability (Gateway) - Команда: `pnpm test:stability:gateway` -- Конфігурація: `vitest.gateway.config.ts`, примусово один worker +- Config: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - - Запускає реальний loopback Gateway з увімкненою за замовчуванням діагностикою + - Запускає реальний loopback Gateway з увімкненою діагностикою за замовчуванням - Проганяє синтетичне churn повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій - - Виконує запити до `diagnostics.stability` через WS RPC Gateway - - Охоплює helper-и збереження bundle стабільності діагностики - - Перевіряє, що recorder залишається обмеженим, синтетичні зразки RSS залишаються нижче бюджету тиску, а глибина черги для кожної сесії знову спадає до нуля + - Запитує `diagnostics.stability` через Gateway WS RPC + - Охоплює helper persistence для diagnostic stability bundle + - Перевіряє, що recorder залишається обмеженим, синтетичні зразки RSS лишаються в межах бюджету тиску, а глибина черг на рівні сесії знову зменшується до нуля - Очікування: - Безпечно для CI і без ключів - - Вузький lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway + - Вузька lane для подальшого відстеження stability-регресій, а не заміна повного набору Gateway -### E2E (smoke-тести Gateway) +### E2E (Gateway smoke) - Команда: `pnpm test:e2e` -- Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести bundled-plugin у `extensions/` +- Config: `vitest.e2e.config.ts` +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести вбудованих Plugin у `extensions/` - Типові параметри runtime: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість workers (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням запускається в silent mode, щоб зменшити накладні витрати на console I/O. + - Використовує адаптивну кількість workers (CI: до 2, локально: типово 1). + - За замовчуванням працює в тихому режимі, щоб зменшити накладні витрати на консольний I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` для примусового задання кількості workers (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` для повторного ввімкнення детального виводу console. + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість workers (обмежено до 16). + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - Наскрізна поведінка Gateway з кількома екземплярами - - Поверхні WebSocket/HTTP, pairing вузлів і складніша мережева взаємодія + - End-to-end поведінка gateway з кількома інстансами + - Поверхні WebSocket/HTTP, спарювання Node і важча мережева взаємодія - Очікування: - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж в unit-тестах (може бути повільніше) + - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: smoke-тест backend OpenShell +### E2E: smoke-тест бекенда OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - Запускає ізольований Gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell у OpenClaw через реальні `sandbox ssh-config` + виконання SSH - - Перевіряє канонічну для віддаленого середовища поведінку файлової системи через міст fs sandbox + - Перевіряє бекенд OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє remote-canonical поведінку файлової системи через міст fs sandbox - Очікування: - - Лише за явним увімкненням; не входить до типового запуску `pnpm test:e2e` - - Потрібні локальний CLI `openshell` і працюючий Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox + - Лише opt-in; не входить до типового запуску `pnpm test:e2e` + - Потребує локального CLI `openshell` і справного демона Docker + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб указати нестандартний двійковий файл CLI або wrapper-скрипт + - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого набору e2e + - `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-тести bundled-plugin у `extensions/` +- Config: `vitest.live.config.ts` +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести вбудованих Plugin у `extensions/` - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін форматів провайдерів, особливостей виклику інструментів, проблем auth і поведінки rate limit + - «Чи працює цей провайдер/модель _сьогодні_ з реальними обліковими даними?» + - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit - Очікування: - - Навмисно нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / використовує rate limits - - Краще запускати звужені підмножини, а не «все» -- Live-запуски читають `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють матеріали config/auth до тимчасового test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно хочете, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер за замовчуванням використовує тихіший режим: він зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає логи bootstrap Gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API-ключів (залежно від провайдера): установіть `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте перевизначення для live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. + - За задумом нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / витрачає ліміти rate limit + - Краще запускати звужені піднабори, а не «все» +- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. +- Типово live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий тестовий home, щоб unit-фікстури не могли змінювати ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає логи bootstrap gateway / шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. +- Ротація API-ключів (специфічна для провайдера): установіть `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або окреме live-перевизначення через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. - Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, щоб було видно активність тривалих викликів провайдерів, навіть коли перехоплення console Vitest тихе. - - `vitest.live.config.ts` вимикає перехоплення console у Vitest, тому рядки прогресу провайдера/Gateway відразу транслюються під час live-запусків. + - Live-набори тепер виводять рядки прогресу в stderr, щоб було видно, що довгі виклики провайдера активні, навіть коли захоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/gateway негайно потоково виводилися під час live-запусків. - Налаштовуйте Heartbeat для прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? Використовуйте цю таблицю рішень: -- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змін багато) -- Зміни мережевої взаємодії Gateway / протоколу WS / pairing: додайте `pnpm test:e2e` -- Налагодження «мій бот не працює» / збоїв, специфічних для провайдера / виклику інструментів: запускайте звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Зачіпаєте мережеву взаємодію gateway / протокол WS / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / виклик інструментів: запускайте звужений `pnpm test:live` ## Live: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку наразі оголошує** підключений Android Node, і перевірити поведінку контракту команди. +- Мета: викликати **кожну команду, яка зараз рекламується** підключеним Android Node, і перевірити поведінку контракту команди. - Обсяг: - - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не pair-ить застосунок). - - Перевірка `node.invoke` Gateway команда за командою для вибраного Android Node. + - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не спаровує застосунок). + - Перевірка `node.invoke` gateway команда за командою для вибраного Android Node. - Обов’язкове попереднє налаштування: - - Android-застосунок уже підключено та pair-ено з gateway. - - Застосунок має залишатися на передньому плані. - - Надано дозволи/згоду на capture для можливостей, які ви очікуєте як успішні. + - Android-застосунок уже підключений і спарений із gateway. + - Застосунок утримується на передньому плані. + - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте успішно пройти. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - Повні відомості про налаштування Android: [Android App](/uk/platforms/android) -## Live: smoke-тест моделей (ключі профілів) +## Live: smoke-тест моделі (ключі профілів) -Live-тести поділено на два рівні, щоб можна було ізолювати збої: +Live-тести поділено на два шари, щоб можна було ізолювати збої: -- «Пряма модель» показує, чи може провайдер/модель узагалі відповісти з наданим ключем. -- «Smoke Gateway» показує, чи працює для цієї моделі повний конвеєр gateway+agent (sessions, history, tools, політика sandbox тощо). +- «Direct model» показує, чи може провайдер/модель узагалі відповісти з наданим ключем. +- «Gateway smoke» показує, чи працює повний pipeline gateway+agent для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). -### Рівень 1: пряме завершення моделі (без gateway) +### Шар 1: Direct model completion (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Виконати невелике завершення для кожної моделі (і точкові регресії за потреби) + - Виконати невелике completion для кожної моделі (і цільові регресії там, де потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб дійсно запустити цей набір; інакше він пропускається, щоб `pnpm test:live` залишався зосередженим на smoke Gateway + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб цей набір справді запустився; інакше він буде пропущений, щоб `pnpm test:live` залишався сфокусованим на smoke-тесті gateway - Як вибирати моделі: - - `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=modern` щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` — це alias для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - За замовчуванням перевірки modern/all обмежені підібраною високосигнальною межею; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншої межі. + - Modern/all sweep типово використовують curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого обмеження. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: сховище профілів і резервні значення env - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** + - Типово: profile store і env fallback + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр gateway agent зламаний» - - Утримує невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) + - Відділяє «API провайдера зламане / ключ недійсний» від «pipeline gateway agent зламаний» + - Містить малі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + tool-call flows) -### Рівень 2: smoke Gateway + dev agent (що насправді робить "@openclaw") +### Шар 2: smoke-тест Gateway + dev agent (те, що реально робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Запустити in-process gateway - - Створити/оновити session `agent:dev:*` (перевизначення моделі для кожного запуску) - - Ітеруватися по моделях із ключами і перевіряти: + - Підняти in-process gateway + - Створити/пропатчити сесію `agent:dev:*` (перевизначення моделі на кожен запуск) + - Перебрати моделі-з-ключами і перевірити: - «змістовну» відповідь (без інструментів) - - що працює реальний виклик інструмента (зонд читання) - - необов’язкові додаткові зонди інструментів (зонд exec+read) - - що шляхи регресії OpenAI (лише tool-call → follow-up) продовжують працювати -- Відомості про зонди (щоб ви могли швидко пояснювати збої): - - Зонд `read`: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. - - Зонд `exec+read`: тест просить агента через `exec` записати nonce у тимчасовий файл, а потім `read` його назад. - - Зонд зображення: тест прикріплює згенерований PNG (кіт + рандомізований код) і очікує, що модель поверне `cat `. + - що працює реальний виклик інструмента (read probe) + - необов’язкові додаткові перевірки інструментів (exec+read probe) + - що шляхи регресій OpenAI (лише виклик інструмента → подальший крок) і далі працюють +- Деталі probe (щоб ви могли швидко пояснювати збої): + - `read` probe: тест записує nonce-файл у робочий простір і просить агента `read` його та повернути nonce назад. + - `exec+read` probe: тест просить агента `exec`-ом записати nonce у тимчасовий файл, а потім `read`-ом прочитати його назад. + - image probe: тест прикріплює згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) - Як вибирати моделі: - Типово: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це alias для modern allowlist - - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - За замовчуванням перевірки gateway modern/all обмежені підібраною високосигнальною межею; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншої межі. -- Як вибирати провайдерів (уникати «все з OpenRouter»): + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити + - Modern/all gateway sweep типово використовують curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого обмеження. +- Як вибирати провайдерів (уникайте «усе з OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Зонди інструментів і зображень у цьому live-тесті завжди ввімкнені: - - зонд `read` + зонд `exec+read` (навантаження на інструменти) - - зонд зображення запускається, коли модель оголошує підтримку входу зображень +- Перевірки tool + image у цьому live-тесті завжди ввімкнені: + - `read` probe + `exec+read` probe (стрес для інструментів) + - image probe запускається, коли модель заявляє підтримку вхідного `image` - Потік (на високому рівні): - - Тест генерує крихітний PNG з «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) + - Тест генерує крихітний 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`) - - Вбудований агент передає моделі мультимодальне повідомлення користувача + - Gateway парсить вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Embedded agent пересилає мультимодальне повідомлення користувача моделі - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що можна протестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що ви можете тестувати на своїй машині (і точні id `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke-тест backend CLI (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke-тест CLI backend (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent з використанням локального backend CLI, не торкаючись вашої типової конфігурації. -- Типові параметри smoke для конкретного backend містяться у визначенні `cli-backend.ts` відповідного extension. +- Мета: перевірити pipeline Gateway + agent з використанням локального CLI backend, не зачіпаючи вашу типову config. +- Типові smoke-параметри, специфічні для backend, знаходяться у визначенні `cli-backend.ts` extension-власника. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image походить із метаданих plugin відповідного backend CLI. -- Перевизначення (необов’язково): + - Типовий provider/model: `claude-cli/claude-sonnet-4-6` + - Поведінка command/args/image береться з метаданих plugin CLI backend-власника. +- Перевизначення (необов’язкові): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"` - `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`, щоб надіслати другий хід і перевірити потік resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності в тій самій сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальне вкладення image (шляхи інжектяться в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до файлів image як CLI-аргументи замість інжекції в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) щоб керувати тим, як передаються image-аргументи, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий хід і перевірити потік resume. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` щоб вимкнути типову перевірку безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -610,29 +607,29 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker runner розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke-тест CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. -- Він визначає метадані smoke для CLI з extension-власника, а потім встановлює відповідний Linux-пакет CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносимого OAuth підписки Claude Code через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім виконує два ходи Gateway CLI-backend без збереження змінних середовища API-ключа Anthropic. Цей lane підписки типово вимикає зонди Claude MCP/tool і image, тому що зараз Claude маршрутизує використання сторонніх застосунків через оплату додаткового використання замість звичайних лімітів плану підписки. -- Live smoke-тест CLI-backend тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик інструмента MCP `cron`, перевірений через Gateway CLI. -- Типовий smoke для Claude також оновлює сесію з Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає ранішу примітку. +- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke-тест CLI-backend всередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані CLI smoke з extension-власника, а потім встановлює відповідний Linux CLI-пакет (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс за адресою `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 без збереження env-змінних API-ключа Anthropic. Ця lane підписки типово вимикає перевірки Claude MCP/tool та image, тому що Claude зараз маршрутизує використання сторонніх застосунків через тарифікацію extra-usage замість звичайних лімітів плану підписки. +- Live smoke-тест CLI-backend тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через CLI gateway. +- Типовий smoke-тест Claude також патчить сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. -## Live: smoke-тест ACP bind (`/acp spawn ... --bind here`) +## Live: ACP bind smoke (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік прив’язування розмови ACP з live ACP-агентом: +- Мета: перевірити реальний потік прив’язки розмови ACP з live ACP-агентом: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну розмову message-channel на місці - - надіслати звичайне follow-up у тій самій розмові - - перевірити, що follow-up потрапляє в стенограму прив’язаної сесії ACP + - прив’язати синтетичну розмову каналу повідомлень на місці + - надіслати звичайне подальше повідомлення в цій самій розмові + - перевірити, що подальше повідомлення потрапляє в transcript прив’язаної сесії ACP - Увімкнення: - `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 - - ACP-backend: `acpx` + - Синтетичний channel: контекст розмови у стилі Slack DM + - ACP-бекенд: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -642,8 +639,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.5` - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.4` - Примітки: - - Цей lane використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли приєднувати контекст message-channel, не вдаючи зовнішню доставку. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness agent. + - Ця lane використовує поверхню gateway `chat.send` з полями synthetic originating-route лише для адміністраторів, щоб тести могли приєднувати контекст каналу повідомлень без імітації зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness-агента. Приклад: @@ -659,7 +656,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Рецепти Docker для одного агента: +Docker-рецепти для окремих агентів: ```bash pnpm test:docker:live-acp-bind:claude @@ -669,36 +666,36 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker runner розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає smoke-тест ACP bind послідовно для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. +- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. +- Типово він запускає ACP bind smoke-тест для всіх підтримуваних live CLI-агентів послідовно: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він читає `~/.profile`, переносить відповідний auth-матеріал CLI до контейнера, встановлює `acpx` у записуваний npm-префікс, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. -- Усередині Docker runner встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав змінні середовища провайдера з прочитаного профілю доступними для дочірнього harness CLI. +- Він використовує `~/.profile`, готує відповідний матеріал автентифікації CLI у контейнері, встановлює `acpx` у записуваний 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 зберігав env-змінні провайдера з використаного profile доступними для дочірнього harness CLI. ## Live: smoke-тест harness app-server Codex -- Мета: перевірити harness Codex, яким володіє plugin, через звичайний - метод gateway `agent`: - - завантажити bundled plugin `codex` +- Мета: перевірити plugin-owned harness Codex через звичайний метод gateway + `agent`: + - завантажити вбудований plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший хід gateway agent до `openai/gpt-5.5` з примусовим harness Codex - - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що thread + - надіслати перший хід gateway agent до `openai/gpt-5.5` з примусовим використанням harness Codex + - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що потік app-server може відновитися - - виконати `/codex status` і `/codex models` через той самий командний - шлях gateway - - за потреби виконати два Guardian-reviewed ескаловані shell-зонди: один нешкідливий - командний виклик, який має бути схвалений, і одне фальшиве завантаження секрету, - яке має бути відхилене, щоб агент поставив уточнювальне запитання + - виконати `/codex status` і `/codex models` через той самий шлях + команди gateway + - необов’язково виконати дві escalated shell probes, переглянуті Guardian: одну нешкідливу + команду, яку слід схвалити, і одне фальшиве вивантаження секрету, яке має бути + відхилене, щоб агент перепитав - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `openai/gpt-5.5` -- Необов’язковий зонд зображення: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Необов’язковий зонд MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Необов’язковий зонд Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний - harness Codex не міг пройти непомітно, тихо повернувшись до PI. -- Auth: auth app-server Codex з локального логіну підписки Codex. Docker - smoke-тести також можуть надавати `OPENAI_API_KEY` для не-Codex-зондів, коли доречно, +- Необов’язкова 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 app-server Codex з локального логіну підписки Codex. Docker + smoke-тести також можуть передавати `OPENAI_API_KEY` для probe, не пов’язаних із Codex, коли це доречно, а також необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml`. Локальний рецепт: @@ -722,17 +719,18 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker runner розташований у `scripts/test-live-codex-harness-docker.sh`. -- Він читає змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює auth-файли CLI Codex, - якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm-префікс, - переносить дерево source, а потім запускає лише live-тест harness Codex. -- Docker типово вмикає зонди image, MCP/tool і Guardian. Установіть +- Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + auth CLI Codex, якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm- + префікс, готує вихідне дерево, а потім запускає лише live-тест Codex-harness. +- Docker типово вмикає image-, MCP/tool- і Guardian-probe. Установіть `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-тесту, - щоб старі alias або fallback до PI не могли приховати регресію harness Codex. + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` або + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли вам потрібен вужчий + налагоджувальний запуск. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і live + config тесту, щоб застарілі alias або fallback на PI не могли приховати + регресію harness Codex. ### Рекомендовані live-рецепти @@ -741,7 +739,7 @@ pnpm test:docker:live-codex-harness - Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Одна модель, smoke Gateway: +- Одна модель, smoke-тест gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Виклик інструментів через кількох провайдерів: @@ -754,21 +752,21 @@ pnpm test:docker:live-codex-harness Примітки: - `google/...` використовує API Gemini (API-ключ). -- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint агента у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний CLI Gemini на вашій машині (окремий auth + особливості tooling). +- `google-antigravity/...` використовує OAuth-міст Antigravity (endpoint агента у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний CLI Gemini на вашій машині (окрема автентифікація + особливості tooling). - API Gemini проти CLI Gemini: - - API: OpenClaw викликає розміщений Google API Gemini через HTTP (API-ключ / auth профілю); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує локальний двійковий файл `gemini`; він має власний auth і може поводитися інакше (streaming/підтримка інструментів/розсинхрон версій). + - API: OpenClaw викликає розміщений Google API Gemini через HTTP (auth через API-ключ / profile); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує локальний бінарник `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка інструментів/розбіжності версій). ## Live: матриця моделей (що ми охоплюємо) -Фіксованого «списку моделей CI» не існує (live запускається за явним увімкненням), але ось **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. +Немає фіксованого «списку моделей CI» (live є opt-in), але це **рекомендовані** моделі, які варто регулярно покривати на dev-машині з ключами. -### Сучасний набір smoke (виклик інструментів + image) +### Сучасний набір smoke-тестів (виклик інструментів + 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 OAuth: `openai-codex/gpt-5.5` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) - Google (API Gemini): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) @@ -776,12 +774,12 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск smoke Gateway з інструментами + image: +Запуск smoke-тесту gateway з інструментами + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.5,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) -Вибирайте щонайменше одну модель на сімейство провайдерів: +Виберіть принаймні одну модель для кожного сімейства провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -789,318 +787,320 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (корисно мати): +Необов’язкове додаткове покриття (було б добре мати): -- xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас увімкнено) -- Cerebras: `cerebras/`… (якщо маєте доступ) +- xAI: `xai/grok-4` (або найновішу доступну) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас ввімкнено) +- Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) -### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) +### Vision: надсилання image (вкладення → мультимодальне повідомлення) -Додайте принаймні одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI із підтримкою vision тощо), щоб перевірити image probe. +Додайте принаймні одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI-варіанти з підтримкою vision тощо), щоб перевірити image probe. -### Aggregators / альтернативні gateway +### Агрегатори / альтернативні gateway Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: - OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Інші провайдери, які можна включити до live matrix (якщо у вас є облікові дані/конфігурація): +Більше провайдерів, яких можна включити до live matrix (якщо у вас є облікові дані/config): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (власні endpoint): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (custom endpoint): `minimax` (cloud/API), а також будь-який сумісний із OpenAI/Anthropic proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко закодувати в документації «усі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі. +Порада: не намагайтеся жорстко прописати в документації «усі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині + які ключі доступні. ## Облікові дані (ніколи не комітьте) Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: - Якщо CLI працює, live-тести мають знаходити ті самі ключі. -- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. +- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як ви б налагоджували `openclaw models list` / вибір моделі. -- Профілі auth для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в live-тестах означає «ключі профілів») -- Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо існує, але не є основним сховищем ключів профілів) -- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги auth CLI до тимчасового test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` прибираються, щоб зонди не працювали у вашому реальному workspace хоста. +- Профілі auth для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає “profile keys” у live-тестах) +- Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) +- Застарілий каталог стану: `~/.openclaw/credentials/` (копіюється в підготовлений live home за наявності, але це не основне сховище profile keys) +- Локальні live-запуски типово копіюють активну config, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги auth CLI до тимчасового тестового home; підготовлені live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` і `agentDir` видаляються, щоб probe не працювали у вашому реальному робочому просторі хоста. -Якщо ви хочете покладатися на ключі env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker runners нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). -## Live Deepgram (транскрипція аудіо) +## Deepgram live (транскрипція аудіо) - Тест: `extensions/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` -## Live BytePlus coding plan +## BytePlus coding plan 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` -## Live workflow media ComfyUI +## ComfyUI workflow media live - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє bundled-шляхи comfy для зображень, відео і `music_generate` - - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` - - Корисно після змін у надсиланні workflow comfy, опитуванні, завантаженнях або реєстрації plugin + - Перевіряє вбудовані шляхи comfy для image, video і `music_generate` + - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано + - Корисно після змін у поданні workflow comfy, polling, завантаженнях або реєстрації plugin -## Live генерація зображень +## Image generation live - Тест: `test/image-generation.runtime.live.test.ts` - Команда: `pnpm test:live test/image-generation.runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перелічує кожен зареєстрований bundled plugin провайдера генерації зображень - - Перед перевіркою завантажує відсутні змінні середовища провайдера з вашого login shell (`~/.profile`) - - За замовчуванням використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі test-ключі в `auth-profiles.json` не маскували реальні облікові дані shell - - Пропускає провайдерів без придатного auth/профілю/моделі - - Запускає стандартні варіанти генерації зображень через спільну runtime-capability: + - Перелічує кожен зареєстрований plugin провайдера генерації image + - Завантажує відсутні env-змінні провайдера з вашої login shell (`~/.profile`) перед probe + - Типово використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатного auth/profile/model + - Проганяє стандартні варіанти генерації image через спільну runtime-можливість: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні bundled-провайдери, що охоплюються: +- Поточні вбудовані провайдери в покритті: - `fal` - `google` - `minimax` - `openai` + - `openrouter` - `vydra` - `xai` - Необов’язкове звуження: - - `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_IMAGE_GENERATION_PROVIDERS="openai,google,openrouter,xai"` + - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,openrouter/google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` + - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,openrouter:generate,xai:default-generate,xai:default-edit"` - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env -## Live генерація музики +## Music generation live - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний bundled-шлях провайдера генерації музики + - Перевіряє спільний шлях вбудованого провайдера генерації музики - Наразі охоплює Google і MiniMax - - Перед перевіркою завантажує змінні середовища провайдера з вашого login shell (`~/.profile`) - - За замовчуванням використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі test-ключі в `auth-profiles.json` не маскували реальні облікові дані shell - - Пропускає провайдерів без придатного auth/профілю/моделі + - Завантажує env-змінні провайдера з вашої login shell (`~/.profile`) перед probe + - Типово використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатного auth/profile/model - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` з вхідними даними лише prompt + - `generate` з вхідними даними лише у вигляді prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільного lane: + - Поточне покриття спільної lane: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, а не ця спільна перевірка + - `comfy`: окремий live-файл Comfy, а не цей спільний sweep - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env -## Live генерація відео +## Video generation live - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний bundled-шлях провайдера генерації відео - - За замовчуванням використовує безпечний для релізу smoke-шлях: провайдери, крім FAL, один запит text-to-video на провайдера, 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, щоб застарілі test-ключі в `auth-profiles.json` не маскували реальні облікові дані shell - - Пропускає провайдерів без придатного auth/профілю/моделі - - За замовчуванням запускає лише `generate` + - Перевіряє спільний шлях вбудованого провайдера генерації video + - Типово використовує безпечний для релізу шлях smoke-тесту: провайдери не-FAL, один запит text-to-video на провайдера, односекундний prompt із лобстером і ліміт операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (типово `180000`) + - Типово пропускає FAL, тому що затримка черги з боку провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно запустити його + - Завантажує env-змінні провайдера з вашої login shell (`~/.profile`) перед probe + - Типово використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатного auth/profile/model + - Типово запускає лише `generate` - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими трансформації, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled`, а вибраний провайдер/модель приймає локальні вхідні дані зображень на основі буфера в спільній перевірці - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled`, а вибраний провайдер/модель приймає локальні вхідні дані відео на основі буфера в спільній перевірці - - Поточні провайдери `imageToVideo`, оголошені, але пропущені в спільній перевірці: - - `vydra`, тому що bundled `veo3` підтримує лише текст, а bundled `kling` вимагає віддалений URL зображення + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід image на основі buffer у спільному sweep + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід video на основі buffer у спільному sweep + - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному sweep: + - `vydra`, тому що вбудований `veo3` підтримує лише text, а вбудований `kling` потребує віддаленого URL image - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс lane `kling`, який за замовчуванням використовує fixture віддаленого URL зображення + - цей файл запускає `veo3` text-to-video плюс lane `kling`, яка типово використовує фікстуру віддаленого URL image - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні провайдери `videoToVideo`, оголошені, але пропущені в спільній перевірці: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалені URL-посилання `http(s)` / MP4 - - `google`, тому що поточний спільний lane Gemini/Veo використовує локальний вхід на основі буфера, і цей шлях не приймається в спільній перевірці - - `openai`, тому що поточний спільний lane не гарантує доступ до inpaint/remix відео, специфічний для організації + - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному sweep: + - `alibaba`, `qwen`, `xai`, тому що ці шляхи зараз потребують віддалених reference URL `http(s)` / MP4 + - `google`, тому що поточна спільна lane Gemini/Veo використовує локальний вхід на основі buffer, а цей шлях не приймається у спільному sweep + - `openai`, тому що поточна спільна lane не гарантує доступ до video inpaint/remix, специфічний для org - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типової перевірки, включно з FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження операції для кожного провайдера під час агресивного smoke-запуску + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового sweep, включно з FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного провайдера під час агресивного smoke-запуску - Необов’язкова поведінка auth: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише через env ## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори для зображень, музики і відео через один рідний для репозиторію entrypoint - - Автоматично завантажує відсутні змінні середовища провайдерів із `~/.profile` - - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатний auth - - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і quiet mode залишається узгодженою + - Запускає спільні live-набори image, music і video через один природний для репозиторію entrypoint + - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` + - Типово автоматично звужує кожен набір до провайдерів, які зараз мають придатний auth + - Повторно використовує `scripts/test-live.mjs`, щоб поведінка Heartbeat і тихого режиму залишалася узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker runners (необов’язкові перевірки «працює в Linux») +## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці Docker runners поділяються на дві групи: +Ці Docker-ранери поділяються на дві групи: -- Live-model runners: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм live-файл із ключами профілів усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та workspace (і читають `~/.profile`, якщо він змонтований). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live runners за замовчуванням використовують меншу межу smoke, щоб повна Docker-перевірка лишалася практичною: - `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Ранери live-моделей: `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 і робочий простір (і використовуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-ранери типово використовують менший smoke-cap, щоб повний Docker sweep залишався практичним: + `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці змінні середовища, коли - явно хочете більшу вичерпну перевірку. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker lane live. Воно також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для E2E container smoke runners, які перевіряють зібраний застосунок. -- Container smoke runners: `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-змінні, коли + ви явно хочете більший вичерпний прогін. +- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох Docker lane live. Він також збирає один спільний image `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для E2E smoke-ранерів у контейнері, які перевіряють зібраний застосунок. +- 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` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker runners для live-model також монтують лише потрібні домашні каталоги auth CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх до домашнього каталогу контейнера перед запуском, щоб зовнішній OAuth CLI міг оновлювати токени, не змінюючи сховище auth хоста: +Docker-ранери live-моделей також bind-mount лише потрібні home-каталоги auth CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у сховищі auth на хості: -- Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Smoke-тест ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- Smoke-тест CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Smoke-тест harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- 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 smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повний scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Smoke-тест onboarding/channel/agent із npm tarball: `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`. -- Smoke-тест глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає bundled-провайдерів зображень, а не зависає. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть збірку на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` зі зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Installer Docker smoke: `bash scripts/test-install-sh-docker.sh` використовує спільний npm-кеш для своїх контейнерів root, update і direct-npm. Smoke-тест оновлення за замовчуванням використовує npm `latest` як стабільну базову версію перед оновленням до tarball-кандидата. Перевірки installer без root зберігають ізольований npm-кеш, щоб записи кешу, створені root, не маскували поведінку локального встановлення користувача. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними повторними запусками. -- У CI для Install Smoke пропускається дубльоване пряме глобальне оновлення npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. -- Мережева взаємодія Gateway (два контейнери, 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 (seeded Gateway + міст stdio + smoke-тест сирого notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти MCP у наборі Pi (реальний stdio MCP server + 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 (smoke-тест встановлення + alias `/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-тест метаданих перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime-залежності bundled 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-залежностей bundled plugin під час ітерації, вимикаючи не пов’язані сценарії, наприклад: +- Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Майстер онбордингу (TTY, повне scaffold): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Smoke-тест онбордингу/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг env-ref і типово Telegram, перевіряє, що ввімкнення plugin встановлює його runtime-залежності на вимогу, запускає doctor і виконує один змоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть channel через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke-тест глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає вбудованих провайдерів image, а не зависає. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть збірку на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` зі зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Docker smoke-тест інсталятора: `bash scripts/test-install-sh-docker.sh` використовує один спільний npm-кеш для своїх контейнерів root, update і direct-npm. Smoke-тест оновлення типово використовує npm `latest` як стабільну baseline перед оновленням до tarball кандидата. Перевірки інсталятора без root зберігають ізольований npm-кеш, щоб записи кешу, що належать root, не маскували поведінку локального встановлення користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними повторними запусками. +- Install Smoke CI пропускає дубльоване пряме глобальне оновлення direct-npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. +- Мережа Gateway (два контейнери, 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`, потім примусово викликає відхилення provider schema і перевіряє, що сирі деталі з’являються в логах Gateway. +- Міст channel MCP (seeded Gateway + stdio bridge + smoke raw Claude notification-frame): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти MCP у Pi bundle (реальний stdio MCP server + smoke 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 і one-shot 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-тест метаданих reload config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime-залежності вбудованих Plugin: `pnpm test:docker:bundled-channel-deps` типово збирає невеликий Docker-образ раннера, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожний Linux-сценарій встановлення. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть на наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Звужуйте перевірки runtime-залежностей вбудованих Plugin під час ітерацій, вимикаючи не пов’язані сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Щоб вручну попередньо зібрати й повторно використати спільний образ built-app: +Щоб вручну попередньо зібрати й повторно використовувати спільний image built-app: ```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 і installer зберігають власні Dockerfile, тому що вони перевіряють поведінку пакетування/встановлення, а не runtime спільного built-app. +Перевизначення image для конкретних наборів, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо їх установлено. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та інсталятора зберігають власні Dockerfile, тому що вони перевіряють поведінку пакета/встановлення, а не спільний runtime built-app. -Docker runners для live-model також монтують поточний checkout лише для читання і -переносять його до тимчасового workdir усередині контейнера. Це зберігає runtime-образ -легким і водночас дозволяє запускати Vitest точно проти вашого локального source/config. -Етап перенесення пропускає великі локальні кеші та результати збірки застосунку, такі як -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунку каталоги `.build` або -виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +Docker-ранери live-моделей також монтують поточний checkout лише для читання і +підготовлюють його у тимчасовий workdir всередині контейнера. Це зберігає runtime- +image компактним, але все одно дозволяє запускати Vitest проти ваших точних локальних source/config. +Крок підготовки пропускає великі локальні кеші та результати збірки застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні каталоги `.build` застосунків або +вивід Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання артефактів, специфічних для машини. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-зонди gateway не запускали +Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe gateway не запускали реальні workers каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття live gateway з цього Docker lane. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття +gateway live із цієї Docker lane. `test:docker:openwebui` — це smoke-тест сумісності вищого рівня: він запускає -контейнер gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoint, -запускає закріплений контейнер Open WebUI проти цього gateway, входить через +контейнер gateway OpenClaw з увімкненими HTTP endpoint, сумісними з OpenAI, +запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає реальний chat-запит через проксі `/api/chat/completions` Open WebUI. Перший запуск може бути помітно повільнішим, тому що Docker може потребувати завантаження -образу Open WebUI, а самому Open WebUI може знадобитися завершити власне cold-start налаштування. -Цей lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) — основний спосіб надати його в Dockerized-запусках. +image Open WebUI, а сам Open WebUI може завершувати власне налаштування холодного старту. +Ця lane очікує наявності придатного ключа live-моделі, а `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) — це основний спосіб надати його в Dockerized-запусках. Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway -контейнер, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання стенограм, метадані вкладень, -поведінку черги live-подій, маршрутизацію вихідних надсилань і сповіщення у стилі Claude про канал + -дозволи через реальний міст stdio MCP. Перевірка сповіщень -безпосередньо аналізує сирі кадри stdio MCP, тож smoke-тест перевіряє те, що міст -справді випромінює, а не лише те, що випадково показує конкретний SDK клієнта. -`test:docker:pi-bundle-mcp-tools` детермінований і не потребує живого -ключа моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server -усередині контейнера, матеріалізує цей сервер через вбудований runtime MCP набору Pi, -виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають +реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway- +контейнер, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, +поведінку черги live events, маршрутизацію outbound send і сповіщення каналу + +дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +безпосередньо аналізує сирі кадри stdio MCP, тож smoke-тест перевіряє те, що +міст реально виводить, а не лише те, що випадково показує конкретний client SDK. +`test:docker:pi-bundle-mcp-tools` детермінований і не потребує ключа live- +моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server +всередині контейнера, матеріалізує цей сервер через runtime вбудованого Pi bundle +MCP, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. -`test:docker:cron-mcp-cleanup` детермінований і не потребує живого ключа моделі. +`test:docker:cron-mcp-cleanup` детермінований і не потребує ключа live-моделі. Він запускає seeded Gateway з реальним stdio MCP probe server, виконує -ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, +ізольований хід cron і one-shot дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручний smoke-тест ACP plain-language thread (не для CI): +Ручний ACP smoke-тест thread природною мовою (не для CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для workflow регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. +- Зберігайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. -Корисні змінні середовища: +Корисні 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`, щоб перевіряти лише змінні середовища, прочитані з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішнього auth CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`), монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- `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 і без зовнішніх монтувань auth CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker - Зовнішні каталоги/файли auth CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів у контейнері -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, які не потребують перебудови -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища профілів (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke-тесту Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI + - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому на кшталт `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` щоб звузити запуск +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` щоб фільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1` щоб повторно використовувати наявний image `openclaw:local-live` для повторних запусків, яким не потрібна перебудова +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб переконатися, що облікові дані надходять зі сховища профілів (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...` щоб вибрати модель, яку gateway надає для smoke-тесту Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити prompt перевірки nonce, використаний smoke-тестом Open WebUI +- `OPENWEBUI_IMAGE=...` щоб перевизначити закріплений тег image Open WebUI -## Перевірка коректності документації +## Перевірка документації -Запускайте перевірки документації після редагування docs: `pnpm check:docs`. -Запускайте повну перевірку anchor у Mintlify, коли потрібні також перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. +Після редагування документації запускайте перевірки docs: `pnpm check:docs`. +Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресія (безпечна для CI) +## Офлайн-регресії (безпечні для CI) -Це регресії «реального конвеєра» без реальних провайдерів: +Це регресії «реального pipeline» без реальних провайдерів: - Виклик інструментів Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, запис config + примусовий auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, примусово записує config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") ## Оцінювання надійності агента (Skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: - Mock-виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють wiring сесії та ефекти config (`src/gateway/gateway.test.ts`). +- End-to-end потоки майстра, які перевіряють wiring сесії та ефекти config (`src/gateway/gateway.test.ts`). -Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Що ще відсутнє для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? +- **Вибір рішення:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? - **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні eval мають насамперед залишатися детермінованими: +Майбутні оцінювання мають передусім залишатися детермінованими: -- Runner сценаріїв, що використовує mock-провайдерів для перевірки викликів інструментів + порядку, читання skill-файлів і wiring сесії. -- Невеликий набір сценаріїв, сфокусованих на Skills (використовувати чи уникати, гейтінг, prompt injection). -- Необов’язкові live eval (за явним увімкненням, із гейтінгом через env) лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв, який використовує mock-провайдерів для перевірки викликів інструментів + порядку, читання skill-файлів і wiring сесій. +- Невеликий набір сценаріїв, зосереджених на Skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live-evals (opt-in, із gating через env) лише після того, як буде готовий безпечний для CI набір. -## Контрактні тести (форма Plugin і channel) +## Contract-тести (форма plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає -контракту свого інтерфейсу. Вони ітеруються по всіх виявлених plugins і запускають набір -перевірок форми та поведінки. Типовий unit lane `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, +Contract-тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму +контракту інтерфейсу. Вони ітеруються по всіх виявлених plugin і запускають набір +перевірок форми та поведінки. Типова unit lane `pnpm test` навмисно +пропускає ці файли спільних seam і smoke; запускайте contract-команди явно, коли торкаєтеся спільних поверхонь channel або provider. ### Команди @@ -1113,21 +1113,21 @@ Open WebUI, перевіряє, що `/api/models` показує `openclaw/defa Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма Plugin (id, name, capabilities) +- **plugin** - Базова форма plugin (id, name, capabilities) - **setup** - Контракт майстра налаштування -- **session-binding** - Поведінка прив’язування сесії +- **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel - **threading** - Обробка ID thread -- **directory** - API каталогу/списку учасників -- **group-policy** - Забезпечення дотримання групових політик +- **directory** - API каталогу/ростеру +- **group-policy** - Застосування групової політики ### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Зонди статусу channel +- **status** - Перевірки статусу channel - **registry** - Форма реєстру Plugin ### Контракти provider @@ -1135,7 +1135,7 @@ Open WebUI, перевіряє, що `/api/models` показує `openclaw/defa Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку auth -- **auth-choice** - Вибір/селекція auth +- **auth-choice** - Вибір/добір auth - **catalog** - API каталогу моделей - **discovery** - Виявлення Plugin - **loader** - Завантаження Plugin @@ -1145,21 +1145,21 @@ Open WebUI, перевіряє, що `/api/models` показує `openclaw/defa ### Коли запускати -- Після зміни export-ів або subpath у plugin-sdk -- Після додавання або зміни channel чи provider Plugin -- Після рефакторингу реєстрації або виявлення Plugin +- Після зміни експортів або subpath у plugin-sdk +- Після додавання або зміни channel чи provider plugin +- Після рефакторингу реєстрації чи виявлення plugin -Контрактні тести запускаються в CI і не потребують реальних API-ключів. +Contract-тести запускаються в CI і не потребують реальних API-ключів. -## Додавання регресійних тестів (рекомендації) +## Додавання регресій (рекомендації) Коли ви виправляєте проблему provider/model, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або захопіть точну трансформацію форми запиту) -- Якщо проблема за своєю природою лише live (rate limit, політики auth), зберігайте live-тест вузьким і таким, що вмикається через змінні env -- Намагайтеся націлюватися на найменший рівень, який виявляє помилку: - - помилка перетворення/повторного відтворення запиту provider → тест прямих моделей - - помилка конвеєра сесії/історії/інструментів gateway → smoke live gateway або безпечний для CI mock-тест gateway -- Захисний бар’єр обходу SecretRef: +- Додайте безпечну для CI регресію, якщо це можливо (mock/stub provider або захоплення точної трансформації форми запиту) +- Якщо проблема за своєю природою лише live (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env-змінні +- Намагайтеся націлюватися на найменший шар, який виявляє помилку: + - помилка конвертації/повтору запиту provider → тест direct models + - помилка pipeline сесії/історії/інструментів gateway → live smoke-тест 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` у цьому тесті. Тест навмисно завершується помилкою для некласифікованих id цілей, щоб нові класи не можна було тихо пропустити. + - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою для некласифікованих target id, щоб нові класи не можна було тихо пропустити. diff --git a/docs/uk/providers/openrouter.md b/docs/uk/providers/openrouter.md index 32ca49948..4c07088e2 100644 --- a/docs/uk/providers/openrouter.md +++ b/docs/uk/providers/openrouter.md @@ -1,20 +1,21 @@ --- read_when: - - You want a single API key for many LLMs + - Вам потрібен один API-ключ для багатьох LLM-ів - Ви хочете запускати моделі через OpenRouter в OpenClaw -summary: Використання уніфікованого API OpenRouter для доступу до багатьох моделей в OpenClaw + - Ви хочете використовувати OpenRouter для генерації зображень +summary: Використовуйте уніфікований API OpenRouter для доступу до багатьох моделей в OpenClaw title: OpenRouter x-i18n: - generated_at: "2026-04-23T21:07:37Z" + generated_at: "2026-04-24T00:42:40Z" model: gpt-5.4 provider: openai - source_hash: 29532ce2b7fa2b4643db155f6fd6ee17fd9d14ddf65d5e78d0970a4db7b7694a + source_hash: 7516910f67a8adfb107d07cadd73c34ddd110422ecb90278025d4d6344937aac source_path: providers/openrouter.md workflow: 15 --- -OpenRouter надає **уніфікований API**, який маршрутизує запити до багатьох моделей через один -endpoint і один API-ключ. Він сумісний з OpenAI, тому більшість OpenAI SDK працюють, якщо змінити base URL. +OpenRouter надає **уніфікований API**, який спрямовує запити до багатьох моделей через єдину +кінцеву точку та API-ключ. Він сумісний з OpenAI, тому більшість SDK OpenAI працюють, якщо змінити базовий URL. ## Початок роботи @@ -28,7 +29,7 @@ endpoint і один API-ключ. Він сумісний з OpenAI, тому ``` - Онбординг типово встановлює `openrouter/auto`. Пізніше можна вибрати конкретну модель: + Під час онбордингу типовим значенням є `openrouter/auto`. Пізніше виберіть конкретну модель: ```bash openclaw models set openrouter// @@ -50,70 +51,89 @@ endpoint і один API-ключ. Він сумісний з OpenAI, тому } ``` -## Посилання на моделі +## Посилання моделей -Посилання на моделі мають формат `openrouter//`. Повний список -доступних provider і моделей див. у [/concepts/model-providers](/uk/concepts/model-providers). +Посилання моделей відповідають шаблону `openrouter//`. Повний список +доступних провайдерів і моделей дивіться в [/concepts/model-providers](/uk/concepts/model-providers). -Приклади вбудованого fallback: +Приклади вбудованого резервного перемикання: -| Model ref | Примітки | -| ------------------------------------ | ------------------------------- | +| Model ref | Примітки | +| ------------------------------------ | --------------------------------- | | `openrouter/auto` | Автоматична маршрутизація OpenRouter | -| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 через MoonshotAI | -| `openrouter/openrouter/healer-alpha` | Маршрут OpenRouter Healer Alpha | -| `openrouter/openrouter/hunter-alpha` | Маршрут OpenRouter Hunter Alpha | +| `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 через MoonshotAI | +| `openrouter/openrouter/healer-alpha` | Маршрут OpenRouter Healer Alpha | +| `openrouter/openrouter/hunter-alpha` | Маршрут OpenRouter Hunter Alpha | + +## Генерація зображень + +OpenRouter також може працювати як основа для інструмента `image_generate`. Використовуйте модель зображень OpenRouter у `agents.defaults.imageGenerationModel`: + +```json5 +{ + env: { OPENROUTER_API_KEY: "sk-or-..." }, + agents: { + defaults: { + imageGenerationModel: { + primary: "openrouter/google/gemini-3.1-flash-image-preview", + }, + }, + }, +} +``` + +OpenClaw надсилає запити на зображення до API зображень chat completions OpenRouter з `modalities: ["image", "text"]`. Моделі зображень Gemini отримують підтримувані підказки `aspectRatio` і `resolution` через `image_config` OpenRouter. ## Автентифікація та заголовки -Під капотом OpenRouter використовує Bearer token з вашим API-ключем. +OpenRouter використовує Bearer token з вашим API-ключем під капотом. -Для реальних запитів OpenRouter (`https://openrouter.ai/api/v1`) OpenClaw також додає -задокументовані OpenRouter заголовки атрибуції застосунку: +У реальних запитах OpenRouter (`https://openrouter.ai/api/v1`) OpenClaw також додає +задокументовані заголовки атрибуції застосунку OpenRouter: -| Заголовок | Значення | +| Header | Value | | ------------------------- | --------------------- | | `HTTP-Referer` | `https://openclaw.ai` | | `X-OpenRouter-Title` | `OpenClaw` | | `X-OpenRouter-Categories` | `cli-agent` | -Якщо ви перенаправите provider OpenRouter на якийсь інший proxy або base URL, OpenClaw -**не** додаватиме ці OpenRouter-специфічні заголовки або маркери кешу Anthropic. +Якщо ви перенаправите провайдер OpenRouter на якийсь інший проксі або базовий URL, OpenClaw +**не** додаватиме ці специфічні для OpenRouter заголовки або маркери кешу Anthropic. ## Розширена конфігурація - На перевірених маршрутах OpenRouter refs моделей Anthropic зберігають + На перевірених маршрутах OpenRouter посилання моделей Anthropic зберігають специфічні для OpenRouter маркери Anthropic `cache_control`, які OpenClaw використовує для - кращого повторного використання prompt-cache у блоках system/developer prompt. + кращого повторного використання кешу промптів у блоках system/developer prompt. - + На підтримуваних маршрутах, відмінних від `auto`, OpenClaw зіставляє вибраний рівень thinking з - payload міркувань proxy OpenRouter. Непідтримувані підказки моделі та - `openrouter/auto` пропускають це впровадження міркувань. + payload reasoning проксі OpenRouter. Непідтримувані підказки моделей і + `openrouter/auto` пропускають цю ін’єкцію reasoning. - OpenRouter усе одно працює через proxy-подібний OpenAI-сумісний шлях, тому - нативне формування запитів лише для OpenAI, таке як `serviceTier`, Responses `store`, - payload сумісності reasoning OpenAI та підказки prompt-cache, не передається далі. + OpenRouter усе ще працює через сумісний з OpenAI шлях у стилі проксі, тому + нативне формування запитів лише для OpenAI, таке як `serviceTier`, `store` у Responses, + payload сумісності reasoning OpenAI та підказки кешу промптів, не передається далі. - refs OpenRouter на базі Gemini залишаються на proxy-Gemini шляху: OpenClaw зберігає - там санітизацію thought-signature Gemini, але не вмикає нативну валідацію replay Gemini + Посилання OpenRouter на базі Gemini залишаються на шляху proxy-Gemini: OpenClaw зберігає + там очищення thought-signature Gemini, але не вмикає нативну перевірку повторного відтворення Gemini або bootstrap rewrites. - - Якщо ви передаєте маршрутизацію provider OpenRouter у параметрах моделі, OpenClaw передає - її як метадані маршрутизації OpenRouter до запуску спільних stream wrappers. + + Якщо ви передаєте маршрутизацію провайдера OpenRouter через параметри моделі, OpenClaw пересилає + її як метадані маршрутизації OpenRouter до запуску спільних обгорток потоку. @@ -121,9 +141,9 @@ endpoint і один API-ключ. Він сумісний з OpenAI, тому - Вибір provider, refs моделей і поведінки failover. + Вибір провайдерів, посилань моделей і поведінки резервного перемикання. - Повний довідник конфігурації для agents, models і providers. + Повний довідник конфігурації для агентів, моделей і провайдерів. diff --git a/docs/uk/tools/image-generation.md b/docs/uk/tools/image-generation.md index 165c96d09..6647ec664 100644 --- a/docs/uk/tools/image-generation.md +++ b/docs/uk/tools/image-generation.md @@ -3,13 +3,13 @@ read_when: - Генерація зображень через агента - Налаштування провайдерів і моделей для генерації зображень - Розуміння параметрів інструмента `image_generate` -summary: Генеруйте та редагуйте зображення за допомогою налаштованих провайдерів (OpenAI, OpenAI Codex OAuth, Google Gemini, fal, MiniMax, ComfyUI, Vydra, xAI) +summary: Генеруйте та редагуйте зображення за допомогою налаштованих провайдерів (OpenAI, OpenAI Codex OAuth, Google Gemini, OpenRouter, fal, MiniMax, ComfyUI, Vydra, xAI) title: Генерація зображень x-i18n: - generated_at: "2026-04-23T23:47:36Z" + generated_at: "2026-04-24T00:42:41Z" model: gpt-5.4 provider: openai - source_hash: 2ee9f19389824e99d7a2d74f212564e1658b904eb722f09c4a402fcaeabd2487 + source_hash: 427df6a3aa2adebef13cb77b6bbc161c010477d8f669b7c20b917382c3acb224 source_path: tools/image-generation.md workflow: 15 --- @@ -22,8 +22,8 @@ x-i18n: ## Швидкий старт -1. Установіть API-ключ щонайменше для одного провайдера (наприклад, `OPENAI_API_KEY` або `GEMINI_API_KEY`) або увійдіть через OpenAI Codex OAuth. -2. За потреби задайте бажану модель: +1. Установіть API-ключ щонайменше для одного провайдера (наприклад, `OPENAI_API_KEY`, `GEMINI_API_KEY` або `OPENROUTER_API_KEY`) або увійдіть через OpenAI Codex OAuth. +2. За бажанням установіть бажану модель: ```json5 { @@ -37,33 +37,28 @@ x-i18n: } ``` -Codex OAuth використовує той самий референс моделі `openai/gpt-image-2`. Коли -налаштовано OAuth-профіль `openai-codex`, OpenClaw спрямовує запити на -зображення через той самий OAuth-профіль замість того, щоб спочатку пробувати `OPENAI_API_KEY`. -Явна користувацька конфігурація зображень `models.providers.openai`, наприклад API-ключ або -користувацький/Azure base URL, знову вмикає прямий маршрут через OpenAI Images API. -Для OpenAI-сумісних LAN-ендпойнтів, таких як LocalAI, залиште користувацький -`models.providers.openai.baseUrl` і явно ввімкніть -`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; приватні/внутрішні -ендпойнти зображень за замовчуванням залишаються заблокованими. +Codex OAuth використовує те саме посилання на модель `openai/gpt-image-2`. Коли налаштовано OAuth-профіль `openai-codex`, OpenClaw спрямовує запити на зображення через цей самий OAuth-профіль замість того, щоб спочатку пробувати `OPENAI_API_KEY`. +Явна користувацька конфігурація зображень `models.providers.openai`, наприклад API-ключ або користувацький/Azure base URL, знову вмикає прямий маршрут через OpenAI Images API. +Для OpenAI-сумісних LAN-ендпойнтів, таких як LocalAI, зберігайте користувацький `models.providers.openai.baseUrl` і явно вмикайте доступ через `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; приватні/внутрішні ендпойнти зображень за замовчуванням залишаються заблокованими. 3. Попросіть агента: _"Згенеруй зображення дружнього робота-маскота."_ -Агент автоматично викликає `image_generate`. Дозволи для списку інструментів не потрібні — інструмент увімкнений за замовчуванням, коли доступний провайдер. +Агент автоматично викликає `image_generate`. Додавати інструмент до списку дозволених не потрібно — він увімкнений за замовчуванням, коли доступний провайдер. ## Підтримувані провайдери -| Провайдер | Модель за замовчуванням | Підтримка редагування | Автентифікація | -| --------- | -------------------------------- | ---------------------------------- | ------------------------------------------------------ | -| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth | -| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | -| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` | -| MiniMax | `image-01` | Так (референс суб’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) | -| ComfyUI | `workflow` | Так (1 зображення, задається workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для хмари | -| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` | -| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` | +| Провайдер | Модель за замовчуванням | Підтримка редагування | Автентифікація | +| --------- | --------------------------------------- | ---------------------------------- | ------------------------------------------------------ | +| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth | +| OpenRouter | `google/gemini-3.1-flash-image-preview` | Так (до 5 вхідних зображень) | `OPENROUTER_API_KEY` | +| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | +| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` | +| MiniMax | `image-01` | Так (референс об’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) | +| ComfyUI | `workflow` | Так (1 зображення, налаштовується workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для хмари | +| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` | +| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` | -Використовуйте `action: "list"`, щоб під час виконання переглянути доступні провайдери та моделі: +Використовуйте `action: "list"`, щоб переглянути доступні провайдери та моделі під час виконання: ``` /tool image_generate action=list @@ -76,7 +71,7 @@ Codex OAuth використовує той самий референс моде -Використовуйте `"list"`, щоб під час виконання переглянути доступні провайдери та моделі. +Використовуйте `"list"`, щоб переглянути доступні провайдери та моделі під час виконання. @@ -84,7 +79,7 @@ Codex OAuth використовує той самий референс моде -Шлях або URL одного референсного зображення для режиму редагування. +Шлях до одного референсного зображення або URL для режиму редагування. @@ -104,11 +99,11 @@ Codex OAuth використовує той самий референс моде -Підказка щодо якості, якщо провайдер її підтримує. +Підказка щодо якості, якщо провайдер це підтримує. -Підказка щодо формату виводу, якщо провайдер його підтримує. +Підказка щодо формату виводу, якщо провайдер це підтримує. @@ -116,7 +111,7 @@ Codex OAuth використовує той самий референс моде -Необов’язковий таймаут запиту до провайдера в мілісекундах. +Необов’язковий тайм-аут запиту до провайдера в мілісекундах. @@ -127,9 +122,9 @@ Codex OAuth використовує той самий референс моде Підказки лише для OpenAI: `background`, `moderation`, `outputCompression` і `user`. -Не всі провайдери підтримують усі параметри. Коли резервний провайдер підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед надсиланням зіставляє запит із найближчим підтримуваним розміром, співвідношенням сторін або роздільною здатністю. Непідтримувані підказки виводу, такі як `quality` або `outputFormat`, відкидаються для провайдерів, які не заявляють таку підтримку, і про це повідомляється в результаті інструмента. +Не всі провайдери підтримують усі параметри. Коли резервний провайдер підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед надсиланням зіставляє запит із найближчим підтримуваним розміром, співвідношенням сторін або роздільною здатністю. Непідтримувані підказки виводу, як-от `quality` або `outputFormat`, відкидаються для провайдерів, які не заявляють такої підтримки, і про це повідомляється в результаті інструмента. -Результати інструмента містять застосовані налаштування. Коли OpenClaw зіставляє геометрію під час переходу до резервного провайдера, повернуті значення `size`, `aspectRatio` і `resolution` відображають те, що фактично було надіслано, а `details.normalization` містить перетворення від запитаного до застосованого значення. +Результати інструмента повідомляють про застосовані параметри. Коли OpenClaw змінює геометрію під час переходу на резервного провайдера, повернені значення `size`, `aspectRatio` і `resolution` відображають те, що фактично було надіслано, а `details.normalization` містить перетворення від запитаного до застосованого. ## Конфігурація @@ -141,66 +136,71 @@ Codex OAuth використовує той самий референс моде defaults: { imageGenerationModel: { primary: "openai/gpt-image-2", - fallbacks: ["google/gemini-3.1-flash-image-preview", "fal/fal-ai/flux/dev"], + fallbacks: [ + "openrouter/google/gemini-3.1-flash-image-preview", + "google/gemini-3.1-flash-image-preview", + "fal/fal-ai/flux/dev", + ], }, }, }, } ``` -### Порядок вибору провайдерів +### Порядок вибору провайдера Під час генерації зображення OpenClaw пробує провайдерів у такому порядку: -1. **Параметр `model`** з виклику інструмента (якщо агент його вказує) -2. **`imageGenerationModel.primary`** з конфігурації -3. **`imageGenerationModel.fallbacks`** по порядку -4. **Автовизначення** — використовуються лише значення за замовчуванням провайдерів із підтримкою автентифікації: +1. Параметр **`model`** з виклику інструмента (якщо агент його вказує) +2. **`imageGenerationModel.primary`** із конфігурації +3. **`imageGenerationModel.fallbacks`** у заданому порядку +4. **Автовизначення** — використовує лише типові значення провайдерів, підкріплені автентифікацією: - спочатку поточний провайдер за замовчуванням - - далі решта зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів + - потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id -Якщо провайдер завершується помилкою (помилка автентифікації, ліміт запитів тощо), автоматично пробується наступний кандидат. Якщо помиляються всі, помилка містить подробиці про кожну спробу. +Якщо провайдер не спрацьовує (помилка автентифікації, ліміт запитів тощо), автоматично пробується наступний кандидат. Якщо не спрацьовують усі, помилка містить подробиці кожної спроби. Примітки: -- Автовизначення враховує стан автентифікації. Значення провайдера за замовчуванням потрапляє до списку кандидатів - лише тоді, коли OpenClaw справді може автентифікувати цей провайдер. -- Автовизначення ввімкнене за замовчуванням. Установіть - `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень - використовувала лише явні записи `model`, `primary` і `fallbacks`. -- Використовуйте `action: "list"`, щоб переглянути наразі зареєстрованих провайдерів, їхні - моделі за замовчуванням і підказки щодо env vars для автентифікації. +- Автовизначення враховує автентифікацію. Типове значення провайдера потрапляє до списку кандидатів лише тоді, коли OpenClaw дійсно може автентифікувати цей провайдер. +- Автовизначення ввімкнене за замовчуванням. Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень використовувала лише явні записи `model`, `primary` і `fallbacks`. +- Використовуйте `action: "list"`, щоб переглянути наразі зареєстровані провайдери, їхні моделі за замовчуванням і підказки щодо змінних середовища для автентифікації. ### Редагування зображень -OpenAI, Google, fal, MiniMax, ComfyUI і xAI підтримують редагування референсних зображень. Передайте шлях або URL референсного зображення: +OpenAI, OpenRouter, Google, fal, MiniMax, ComfyUI і xAI підтримують редагування референсних зображень. Передайте шлях до референсного зображення або URL: ``` -"Згенеруй акварельну версію цього фото" + image: "/path/to/photo.jpg" +"Згенеруй акварельну версію цієї фотографії" + image: "/path/to/photo.jpg" ``` -OpenAI, Google і xAI підтримують до 5 референсних зображень через параметр `images`. fal, MiniMax і ComfyUI підтримують 1. +OpenAI, OpenRouter, Google і xAI підтримують до 5 референсних зображень через параметр `images`. fal, MiniMax і ComfyUI підтримують 1. + +### Моделі зображень OpenRouter + +Генерація зображень через OpenRouter використовує той самий `OPENROUTER_API_KEY` і маршрутизується через image API chat completions від OpenRouter. Вибирайте моделі зображень OpenRouter за допомогою префікса `openrouter/`: + +```json5 +{ + agents: { + defaults: { + imageGenerationModel: { + primary: "openrouter/google/gemini-3.1-flash-image-preview", + }, + }, + }, +} +``` + +OpenClaw пересилає в OpenRouter `prompt`, `count`, референсні зображення та сумісні з Gemini підказки `aspectRatio` / `resolution`. Серед поточних вбудованих скорочень для моделей зображень OpenRouter є `google/gemini-3.1-flash-image-preview`, `google/gemini-3-pro-image-preview` і `openai/gpt-5.4-image-2`; використовуйте `action: "list"`, щоб побачити, що надає ваш налаштований Plugin. ### OpenAI `gpt-image-2` -Генерація зображень OpenAI за замовчуванням використовує `openai/gpt-image-2`. Якщо -налаштовано OAuth-профіль `openai-codex`, OpenClaw повторно використовує той самий OAuth-профіль, -який застосовується для моделей чату з підпискою Codex, і надсилає запит на зображення -через бекенд Codex Responses; він не виконує непомітний перехід на -`OPENAI_API_KEY` для цього запиту. Щоб примусово використовувати прямий маршрут через OpenAI Images API, -явно налаштуйте `models.providers.openai` за допомогою API-ключа, користувацького base URL -або ендпойнта Azure. Старішу модель -`openai/gpt-image-1` усе ще можна вибрати явно, але нові запити OpenAI -на генерацію та редагування зображень мають використовувати `gpt-image-2`. +Генерація зображень OpenAI за замовчуванням використовує `openai/gpt-image-2`. Якщо налаштовано OAuth-профіль `openai-codex`, OpenClaw повторно використовує той самий OAuth-профіль, що й для чат-моделей підписки Codex, і надсилає запит на зображення через бекенд Codex Responses; він не переходить непомітно на `OPENAI_API_KEY` для цього запиту. Щоб примусово використовувати прямий маршрут через OpenAI Images API, явно налаштуйте `models.providers.openai` з API-ключем, користувацьким base URL або ендпойнтом Azure. Старішу модель `openai/gpt-image-1` усе ще можна явно вибрати, але нові запити OpenAI на генерацію й редагування зображень мають використовувати `gpt-image-2`. -`gpt-image-2` підтримує як генерацію текст-у-зображення, так і редагування -референсних зображень через той самий інструмент `image_generate`. OpenClaw передає в OpenAI `prompt`, -`count`, `size`, `quality`, `outputFormat` і референсні зображення. -OpenAI не отримує `aspectRatio` або `resolution` безпосередньо; коли можливо, -OpenClaw зіставляє їх із підтримуваним `size`, інакше інструмент повідомляє про них як про -проігноровані перевизначення. +`gpt-image-2` підтримує як генерацію зображень із тексту, так і редагування референсних зображень через той самий інструмент `image_generate`. OpenClaw пересилає до OpenAI `prompt`, `count`, `size`, `quality`, `outputFormat` і референсні зображення. OpenAI не отримує `aspectRatio` або `resolution` безпосередньо; коли це можливо, OpenClaw зіставляє їх із підтримуваним `size`, інакше інструмент повідомляє про них як про проігноровані перевизначення. -Параметри, специфічні для OpenAI, розміщуються в об’єкті `openai`: +Специфічні для OpenAI параметри містяться в об’єкті `openai`: ```json { @@ -215,11 +215,9 @@ OpenClaw зіставляє їх із підтримуваним `size`, іна } ``` -`openai.background` приймає значення `transparent`, `opaque` або `auto`; прозорі -результати вимагають `outputFormat` `png` або `webp`. `openai.outputCompression` -застосовується до результатів JPEG/WebP. +`openai.background` приймає значення `transparent`, `opaque` або `auto`; прозорий вивід потребує `outputFormat` `png` або `webp`. `openai.outputCompression` застосовується до виводу у форматах JPEG/WebP. -Згенерувати одне горизонтальне 4K-зображення: +Згенерувати одне горизонтальне зображення 4K: ``` /tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1 @@ -237,56 +235,51 @@ OpenClaw зіставляє їх із підтримуваним `size`, іна /tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536 ``` -Редагування з кількома референсами: +Редагувати з кількома референсами: ``` /tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024 ``` -Щоб спрямувати генерацію зображень OpenAI через розгортання Azure OpenAI замість -`api.openai.com`, див. [ендпойнти Azure OpenAI](/uk/providers/openai#azure-openai-endpoints) -у документації провайдера OpenAI. +Щоб маршрутизувати генерацію зображень OpenAI через розгортання Azure OpenAI замість `api.openai.com`, див. [ендпойнти Azure OpenAI](/uk/providers/openai#azure-openai-endpoints) у документації провайдера OpenAI. Генерація зображень MiniMax доступна через обидва вбудовані шляхи автентифікації MiniMax: - `minimax/image-01` для конфігурацій з API-ключем -- `minimax-portal/image-01` для конфігурацій з OAuth +- `minimax-portal/image-01` для конфігурацій OAuth ## Можливості провайдерів | Можливість | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI | | --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- | -| Генерація | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (кількість виходів задає workflow) | Так (1) | Так (до 4) | -| Редагування/референс | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, референс суб’єкта) | Так (1 зображення, задається workflow) | Ні | Так (до 5 зображень) | +| Генерація | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (кількість виходів визначається workflow) | Так (1) | Так (до 4) | +| Редагування/референси | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, референс об’єкта) | Так (1 зображення, налаштовується workflow) | Ні | Так (до 5 зображень) | | Керування розміром | Так (до 4K) | Так | Так | Ні | Ні | Ні | Ні | | Співвідношення сторін | Ні | Так | Так (лише генерація) | Так | Ні | Ні | Так | | Роздільна здатність (1K/2K/4K) | Ні | Так | Так | Ні | Ні | Ні | Так (1K/2K) | ### xAI `grok-imagine-image` -Вбудований провайдер xAI використовує `/v1/images/generations` для запитів лише з промптом -і `/v1/images/edits`, коли присутній `image` або `images`. +Вбудований провайдер xAI використовує `/v1/images/generations` для запитів лише з промптом і `/v1/images/edits`, коли присутній `image` або `images`. - Моделі: `xai/grok-imagine-image`, `xai/grok-imagine-image-pro` - Кількість: до 4 - Референси: один `image` або до п’яти `images` - Співвідношення сторін: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` - Роздільна здатність: `1K`, `2K` -- Результати: повертаються як вкладення зображень, якими керує OpenClaw +- Вивід: повертається як вкладення зображень, керовані OpenClaw -OpenClaw навмисно не відкриває власні параметри xAI `quality`, `mask`, `user` або -додаткові співвідношення сторін, доступні лише нативно, доки ці елементи керування не з’являться в спільному -міжпровайдерному контракті `image_generate`. +OpenClaw навмисно не надає доступу до специфічних для xAI параметрів `quality`, `mask`, `user` або додаткових native-only співвідношень сторін, доки ці елементи керування не з’являться у спільному міжпровайдерному контракті `image_generate`. ## Пов’язане - [Огляд інструментів](/uk/tools) — усі доступні інструменти агента - [fal](/uk/providers/fal) — налаштування провайдера зображень і відео fal -- [ComfyUI](/uk/providers/comfy) — налаштування локального workflow ComfyUI і Comfy Cloud +- [ComfyUI](/uk/providers/comfy) — налаштування локального ComfyUI і Comfy Cloud workflow - [Google (Gemini)](/uk/providers/google) — налаштування провайдера зображень Gemini - [MiniMax](/uk/providers/minimax) — налаштування провайдера зображень MiniMax - [OpenAI](/uk/providers/openai) — налаштування провайдера OpenAI Images -- [Vydra](/uk/providers/vydra) — налаштування зображень, відео та мовлення Vydra -- [xAI](/uk/providers/xai) — налаштування Grok для зображень, відео, пошуку, виконання коду та TTS +- [Vydra](/uk/providers/vydra) — налаштування зображень, відео й мовлення Vydra +- [xAI](/uk/providers/xai) — налаштування зображень, відео, пошуку, виконання коду та TTS Grok - [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) — конфігурація `imageGenerationModel` -- [Моделі](/uk/concepts/models) — конфігурація моделей і перемикання на резервні варіанти +- [Моделі](/uk/concepts/models) — конфігурація моделей і резервне перемикання