diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 2c8aaaf57..d9e181ce5 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,29 +1,29 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для багів моделі/провайдера + - Додавання регресійних тестів для помилок моделей/провайдерів - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' +summary: 'Набір для тестування: набори unit/e2e/live, виконувані середовища Docker і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-23T04:24:24Z" + generated_at: "2026-04-23T04:54:32Z" model: gpt-5.4 provider: openai - source_hash: 3f965b3d818730c7c58125a29f7cc2508a45aba6c7534b7f13755380dedcef66 + source_hash: d8d80348fd025100a5a57fe26fbc53fa90c04a6248ca8f6b940a79a9471be666 source_path: help/testing.md workflow: 15 --- # Тестування -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker runner-ів. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює) - Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресії для реальних проблем моделей/провайдерів +- Як додавати регресійні тести для реальних проблем моделей/провайдерів ## Швидкий старт @@ -31,96 +31,105 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` - Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` -- Прямий цикл watch у Vitest: `pnpm test:watch` -- Пряме націлення на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Під час ітерацій над однією проблемою спочатку віддавайте перевагу цільовим запускам. -- QA-сайт на базі Docker: `pnpm qa:lab:up` -- QA-лінія на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Прямий цикл спостереження Vitest: `pnpm test:watch` +- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Під час ітерацій над однією помилкою спочатку віддавайте перевагу цільовим запускам. +- QA-сайт на основі Docker: `pnpm qa:lab:up` +- QA-лінія на основі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете додаткової впевненості: +Коли ви змінюєте тести або хочете більшої впевненості: -- Coverage gate: `pnpm test: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` -- Cost smoke для Moonshot/Kimi: коли встановлено `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, потім виконайте ізольований +- Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` +- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Перевірка вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте + `openclaw models list --provider moonshot --json`, а потім запустіть ізольовану команду `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - для `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє Moonshot/K2.6, а - транскрипт помічника зберігає нормалізоване `usage.cost`. + для `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє про Moonshot/K2.6, а + транскрипт асистента зберігає нормалізоване `usage.cost`. -Порада: коли вам потрібен лише один проблемний випадок, віддавайте перевагу звуженню live-тестів через env-змінні allowlist, описані нижче. +Порада: коли вам потрібен лише один збійний випадок, звужуйте live-тести через змінні середовища allowlist, описані нижче. -## QA-специфічні ранери +## Runner-и, специфічні для QA -Ці команди використовуються поруч з основними наборами тестів, коли вам потрібен реалізм qa-lab: +Ці команди використовуються поряд з основними наборами тестів, коли вам потрібна реалістичність qa-lab: - `pnpm openclaw qa suite` - - Запускає сценарії QA, що спираються на репозиторій, безпосередньо на хості. - - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими Gateway workers. `qa-channel` за замовчуванням має concurrency 4 (обмежену кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість workers, або `--concurrency 1` для старішої послідовної лінії. - - Завершується з ненульовим кодом, якщо будь-який сценарій не вдався. Використовуйте `--allow-failures`, коли вам потрібні артефакти без коду завершення з помилкою. + - Запускає QA-сценарії з репозиторію безпосередньо на хості. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими worker-ами Gateway. Для `qa-channel` типовий рівень concurrency — 4 (обмежений кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість worker-ів, або `--concurrency 1` для старішої послідовної лінії. + - Завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального покриття fixture і protocol-mock без заміни сценарно-орієнтованої лінії `mock-openai`. + `aimock` запускає локальний сервер провайдера на основі AIMock для експериментального + покриття фікстур і моків протоколу, не замінюючи орієнтовану на сценарії лінію `mock-openai`. - `pnpm openclaw qa suite --runner multipass` - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані QA-входи автентифікації, які практично використовувати в гостьовому середовищі: - ключі провайдера через env, шлях до конфігурації QA live provider та `CODEX_HOME`, якщо він є. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гість міг записувати назад через змонтований workspace. - - Записує звичайний QA-звіт + підсумок, а також логи Multipass у + - Live-запуски передають у гостьову систему підтримувані QA-входи автентифікації, які практично використовувати: + ключі провайдерів на основі env, шлях до конфігурації QA live-провайдера та `CODEX_HOME`, якщо він присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через змонтовану робочу область. + - Записує звичайний QA-звіт + підсумок, а також логи 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, запускає неінтерактивний онбординг із ключем OpenAI API, за замовчуванням налаштовує Telegram, + перевіряє, що увімкнення plugin встановлює runtime-залежності на вимогу, + запускає doctor і виконує один локальний хід агента проти мокованого endpoint OpenAI. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму + лінію встановлення з пакета з Discord. - `pnpm test:docker:bundled-channel-deps` - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway - зі сконфігурованим OpenAI, а потім вмикає bundled channel/plugins через - редагування config. - - Перевіряє, що виявлення setup залишає невідсутніми лише не налаштовані runtime dependencies Plugin, що перший налаштований запуск Gateway або doctor встановлює runtime dependencies кожного bundled Plugin на вимогу, і що другий restart не перевстановлює dependencies, які вже були активовані. - - Також встановлює відому старішу npm baseline, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що doctor кандидата після оновлення відновлює runtime dependencies bundled channel без відновлення postinstall з боку harness. + з налаштованим OpenAI, а потім вмикає вбудовані channel/plugin через + редагування конфігурації. + - Перевіряє, що виявлення налаштування залишає неналаштовані runtime-залежності plugin відсутніми, що перший налаштований запуск Gateway або doctor встановлює runtime-залежності кожного вбудованого plugin на вимогу, і що другий перезапуск не перевстановлює залежності, які вже були активовані. + - Також встановлює відому старішу базову версію npm, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що + `doctor` кандидата після оновлення відновлює runtime-залежності вбудованих channel без postinstall-відновлення з боку harness. - `pnpm openclaw qa aimock` - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає Matrix live QA-лінію проти тимчасового Docker-backed homeserver Tuwunel. - - Цей QA-хост наразі призначений лише для repo/dev. У пакетованих інсталяціях OpenClaw `qa-lab` не постачається, тому вони не надають `openclaw qa`. - - Checkouts репозиторію завантажують 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 не надає спільних прапорців джерела облікових даних, оскільки ця лінія локально створює тимчасових користувачів. - - Записує Matrix QA-звіт, підсумок, артефакт observed-events і комбінований журнал виводу stdout/stderr у `.artifacts/qa-e2e/...`. + - Запускає лінію Matrix live QA проти тимчасового Docker-backed homeserver Tuwunel. + - Цей QA-хост наразі призначений лише для репозиторію/розробки. Пакетні інсталяції OpenClaw не постачають `qa-lab`, тому вони не надають `openclaw qa`. + - Checkout-версії репозиторію завантажують вбудований runner безпосередньо; окремий крок встановлення plugin не потрібен. + - Налаштовує трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA Gateway із реальним Matrix plugin як SUT transport. + - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначте його через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. + - Matrix не надає спільних прапорців джерела облікових даних, тому що ця лінія локально створює тимчасових користувачів. + - Записує Matrix QA-звіт, підсумок, артефакт observed-events і комбінований лог stdout/stderr до `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає Telegram live QA-лінію проти реальної приватної групи, використовуючи driver і SUT bot tokens з env. - - Потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. ID групи має бути числовим ID чату Telegram. - - Підтримує `--credential-source convex` для спільних пулів облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. - - Завершується з ненульовим кодом, якщо будь-який сценарій не вдався. Використовуйте `--allow-failures`, коли вам потрібні артефакти без коду завершення з помилкою. - - Потрібні два різні боти в одній приватній групі, при цьому бот SUT має мати username Telegram. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що driver bot може спостерігати трафік ботів у групі. - - Записує Telegram QA-звіт, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. + - Запускає лінію Telegram live QA проти реальної приватної групи, використовуючи токени bot `driver` і `sut` із env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. ID групи має бути числовим Telegram chat id. + - Підтримує `--credential-source convex` для спільних pooled credentials. Типово використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. + - Завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. + - Потребує двох різних bot в одній приватній групі, причому bot SUT має надавати ім’я користувача Telegram. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох bot і переконайтеся, що bot driver може спостерігати груповий трафік bot. + - Записує Telegram QA-звіт, підсумок і артефакт observed-messages до `.artifacts/qa-e2e/...`. -Live transport lines спільно використовують один стандартний контракт, щоб нові транспорти не розходилися: +Live transport-лінії мають спільний стандартний контракт, щоб нові transport не розходилися в поведінці: -`qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live transport. +`qa-channel` залишається широким синтетичним QA-набором і не є частиною матриці покриття live transport. -| Лінія | Canary | Gating згадок | Блок allowlist | Відповідь верхнього рівня | Відновлення після restart | Подальша взаємодія в потоці | Ізоляція потоку | Спостереження за реакціями | Команда help | -| -------- | ------ | ------------- | --------------- | ------------------------- | ------------------------- | --------------------------- | --------------- | -------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Лінія | Canary | Блокування згадок | Блок allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша дія в треді | Ізоляція тредів | Спостереження реакцій | Команда help | +| -------- | ------ | ----------------- | -------------- | ------------------------- | ----------------------------- | -------------------- | --------------- | --------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Спільні облікові дані Telegram через Convex (v1) Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), -QA lab отримує ексклюзивну lease із пулу на базі Convex, надсилає Heartbeat -цієї lease під час роботи лінії та звільняє lease під час завершення. +QA lab отримує ексклюзивну оренду з пулу на основі Convex, надсилає Heartbeat +для цієї оренди під час роботи лінії та звільняє оренду під час завершення. -Базовий scaffold проєкту Convex: +Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові env-змінні: +Обов’язкові змінні середовища: - `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: @@ -128,24 +137,24 @@ QA lab отримує ексклюзивну lease із пулу на базі C - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Значення env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (`ci` у CI, інакше `maintainer`) + - Типове значення з env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) -Необов’язкові env-змінні: +Необов’язкові змінні середовища: -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (за замовчуванням `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (за замовчуванням `30000`) -- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (за замовчуванням `90000`) -- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (за замовчуванням `15000`) -- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (за замовчуванням `/qa-credentials/v1`) +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (типово `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) - `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL Convex лише для локальної розробки. -У нормальному режимі `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. +`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. -Команди адміністрування maintainer (додавання/видалення/перелік пулу) вимагають +Адміністративні команди maintainer-а (додавання/видалення/список пулу) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-хелпери для maintainer: +CLI-хелпери для maintainer-ів: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -153,9 +162,9 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `--json` для machine-readable виводу в скриптах і 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 }` @@ -167,74 +176,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: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком із числовим ID чату Telegram. +- `groupId` має бути рядком із числовим Telegram chat id. - `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректний payload. -### Додавання channel до QA +### Додавання каналу до QA -Додавання channel до markdown QA-системи вимагає рівно двох речей: +Додавання каналу до markdown-системи QA потребує рівно двох речей: -1. Транспортний адаптер для channel. -2. Набір сценаріїв, що перевіряє контракт channel. +1. Transport adapter для каналу. +2. Набір сценаріїв, який перевіряє контракт каналу. -Не додавайте новий корінь команди верхнього рівня для QA, якщо спільний хост `qa-lab` -може володіти цим потоком. +Не додавайте новий кореневий QA-командний маршрут верхнього рівня, якщо спільний хост `qa-lab` може +керувати цим потоком. -`qa-lab` володіє спільною механікою хоста: +`qa-lab` відповідає за спільну механіку хоста: -- коренем команди `openclaw qa` -- запуском і завершенням набору -- concurrency workers -- записом артефактів -- генерацією звітів -- виконанням сценаріїв -- alias сумісності для старіших сценаріїв `qa-channel` +- кореневий маршрут команди `openclaw qa` +- запуск і завершення наборів +- concurrency worker-ів +- запис артефактів +- генерацію звітів +- виконання сценаріїв +- alias-и сумісності для старіших сценаріїв `qa-channel` -Runner plugins володіють транспортним контрактом: +Runner plugin-и відповідають за транспортний контракт: - як `openclaw qa ` монтується під спільним коренем `qa` -- як Gateway конфігурується для цього транспорту +- як Gateway налаштовується для цього transport - як перевіряється готовність -- як інжектуються вхідні події +- як ін’єктуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються транскрипти та нормалізований транспортний стан -- як виконуються дії на базі транспорту -- як обробляється reset або cleanup, специфічний для транспорту +- як надаються транскрипти та нормалізований стан transport +- як виконуються дії на основі transport +- як обробляється специфічний для transport reset або cleanup -Мінімальна планка впровадження для нового channel така: +Мінімальний поріг прийняття для нового каналу: -1. Зберігайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте транспортний runner на спільному host seam `qa-lab`. -3. Зберігайте специфічну для транспорту механіку всередині runner Plugin або harness channel. +1. Зберігайте `qa-lab` як власника спільного кореня `qa`. +2. Реалізуйте transport runner на спільному host seam `qa-lab`. +3. Зберігайте механіку, специфічну для transport, усередині runner plugin або harness каналу. 4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. - Зберігайте `runtime-api.ts` легким; ліниве виконання CLI і runner має залишатися за окремими entrypoints. + Runner plugin-и мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. + Зберігайте `runtime-api.ts` легким; ліниве виконання CLI і runner має залишатися за окремими entrypoint-ами. 5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте загальні scenario helpers для нових сценаріїв. -7. Зберігайте наявні alias сумісності працездатними, якщо тільки репозиторій не виконує навмисну міграцію. +6. Використовуйте загальні helper-и сценаріїв для нових сценаріїв. +7. Зберігайте наявні alias-и сумісності працездатними, якщо тільки репозиторій не виконує навмисну міграцію. -Правило прийняття рішень суворе: +Правило прийняття рішення суворе: - Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного транспорту channel, зберігайте її в цьому runner Plugin або harness Plugin. +- Якщо поведінка залежить від одного channel transport, зберігайте її в цьому runner plugin або harness plugin. - Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один channel, додайте загальний helper замість channel-специфічної гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, зберігайте сценарій специфічним для цього транспорту і явно відображайте це в контракті сценарію. +- Якщо поведінка має сенс лише для одного transport, зберігайте сценарій специфічним для цього transport і явно зазначайте це в контракті сценарію. -Бажані назви загальних helper для нових сценаріїв: +Бажані назви загальних helper-ів для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -249,7 +258,7 @@ Runner plugins володіють транспортним контрактом: - `formatTransportTranscript` - `resetTransport` -Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: +Alias-и сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -257,236 +266,236 @@ Alias сумісності залишаються доступними для н - `formatConversationTranscript` - `resetBus` -Для нової роботи з channel слід використовувати загальні назви helper. -Alias сумісності існують, щоб уникнути міграції в стилі flag day, а не як модель для +Нова робота з channel має використовувати загальні назви helper-ів. +Alias-и сумісності існують, щоб уникнути міграції в стилі flag day, а не як модель для створення нових сценаріїв. ## Набори тестів (що де запускається) -Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): +Сприймайте набори як «зростання реалістичності» (і зростання флейковості/вартості): -### Unit / integration (за замовчуванням) +### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) по наявних scoped Vitest projects -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted node-тести `ui`, охоплені `vitest.unit.config.ts` +- Конфігурація: десять послідовних запусків shard (`vitest.full-*.config.ts`) по наявних scoped Vitest project +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, які охоплює `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - Внутрішньопроцесні integration-тести (автентифікація Gateway, маршрутизація, tooling, parsing, config) - - Детерміновані регресії для відомих багів + - In-process integration-тести (автентифікація gateway, маршрутизація, tooling, парсинг, конфігурація) + - Детерміновані регресії для відомих помилок - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним -- Примітка про projects: - - Нетаргетований `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project 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 через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test файлів; редагування config/setup все ще повертаються до широкого повторного запуску root-project. - - `pnpm check:changed` — це звичайний smart локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні typecheck/lint/test lanes. Зміни публічного Plugin SDK і plugin-contract включають перевірку extension, оскільки extensions залежать від цих core-контрактів. Оновлення лише release metadata із version bumps запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, що відхиляє зміни package поза полем version верхнього рівня. - - Unit-тести з легкими імпортами з agents, commands, plugins, helpers auto-reply, `plugin-sdk` та подібних суто утилітних областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - - Вибрані helper source-файли `plugin-sdk` і `commands` також прив’язують changed-mode запуски до явних sibling tests у цих легких lanes, тому зміни helper уникають повторного запуску повного важкого набору для цього каталогу. - - `auto-reply` тепер має три окремі buckets: helpers core верхнього рівня, integration-тести `reply.*` верхнього рівня та піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі harness reply потрапляти на дешеві тести status/chunk/token. +- Примітка щодо project: + - Ненацілений `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського процесу native root-project. Це знижує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. + - `pnpm test --watch` усе ще використовує native root `vitest.config.ts` project graph, тому що цикл watch із кількома shard є непрактичним. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` не сплачує повну ціну запуску root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff зачіпає лише routable source/test-файли; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. + - `pnpm check:changed` — це звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни публічного Plugin SDK і plugin-contract включають валідацію extension, тому що extensions залежать від цих core-контрактів. Зміни version bump лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із guard, який відхиляє зміни пакета поза полем version верхнього рівня. + - Unit-тести з легкими import з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` та подібних чистих утилітних областей маршрутизуються через lane `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. + - Вибрані вихідні helper-файли `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними sibling-тестами в цих легких lanes, тому редагування helper-ів не призводять до повторного запуску повного важкого набору для цього каталогу. + - `auto-reply` тепер має три окремі bucket-и: helper-и верхнього рівня core, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі harness reply потрапляти на дешеві тести status/chunk/token. - Примітка про embedded runner: - - Коли ви змінюєте входи виявлення message-tool або runtime context Compaction, + - Коли ви змінюєте вхідні дані виявлення message-tool або контекст runtime Compaction, зберігайте обидва рівні покриття. - - Додавайте цільові helper-регресії для суто меж маршрутизації/нормалізації. - - Також підтримуйте integration-набори embedded runner у здоровому стані: + - Додавайте сфокусовані 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 - не є достатньою заміною для цих integration-шляхів. + - Ці набори перевіряють, що scoped id і поведінка Compaction усе ще проходять + через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є + достатньою заміною для цих integration-шляхів. - Примітка про pool: - - Базова конфігурація Vitest тепер за замовчуванням використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e і live configs. - - Root UI lane зберігає свої `jsdom` setup та optimizer, але тепер теж працює на спільному non-isolated runner. - - Кожен shard `pnpm test` успадковує ті самі значення `threads` + `isolate: false` за замовчуванням зі спільної конфігурації Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. -- Примітка про швидкі локальні ітерації: - - `pnpm changed:lanes` показує, які архітектурні lanes активує diff. - - Pre-commit hook запускає `pnpm check:changed --staged` після staged formatting/linting, тому core-only commits не платять вартість extension tests, якщо не торкаються публічних контрактів, орієнтованих на extensions. Коміти лише з release metadata залишаються на цільовій lane version/config/root-dependency. - - `pnpm test:changed` маршрутизується через scoped lanes, коли змінені шляхи чисто зіставляються з меншим набором. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом workers. - - Автомасштабування локальних workers тепер навмисно консервативне й також знижує навантаження, коли середнє навантаження хоста вже високе, тому кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базова конфігурація Vitest позначає projects/config files як `forceRerunTriggers`, щоб повторні changed-mode запуски залишалися коректними, коли змінюється wiring тестів. + - Базова конфігурація Vitest тепер типово використовує `threads`. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root project, e2e і live config. + - Root lane UI зберігає своє налаштування `jsdom` та optimizer, але тепер також працює на спільному non-isolated runner. + - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. + - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх процесів Node Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. +- Примітка про швидку локальну ітерацію: + - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. + - Pre-commit hook запускає `pnpm check:changed --staged` після staged formatting/linting, тому коміти лише для core не оплачують вартість тестів extension, якщо тільки вони не зачіпають публічні extension-facing контракти. Коміти лише з release metadata залишаються на цільовій lane version/config/root-dependency. + - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи чисто відображаються на менший набір. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею кількості worker-ів. + - Автомасштабування локальних worker-ів тепер навмисно консервативне і також знижує навантаження, коли середнє навантаження хоста вже високе, тому кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, коли змінюється wiring тестів. - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. - Примітка про налагодження продуктивності: - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпортів плюс вивід розподілу імпортів. - - `pnpm test:perf:imports:changed` обмежує той самий профільний вигляд файлами, зміненими від `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project path для цього закоміченого diff і виводить wall time плюс macOS max RSS. + - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість import, а також вивід розбивки import. + - `pnpm test:perf:imports:changed` обмежує той самий профільований перегляд файлами, зміненими відносно `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` із native root-project-шляхом для цього закоміченого diff і виводить загальний час та macOS max RSS. - `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного брудного дерева, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує main-thread CPU profile для накладних витрат запуску та transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap profiles runner для unit-набору з вимкненим файловим parallelism. + - `pnpm test:perf:profile:main` записує CPU profile основного потоку для накладних витрат запуску і transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner для unit-набору з вимкненим файловим паралелізмом. -### Stability (Gateway) +### Стабільність (gateway) - Команда: `pnpm test:stability:gateway` - Конфігурація: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - - Запускає реальний loopback Gateway з увімкненою за замовчуванням діагностикою - - Проганяє синтетичне churn повідомлень gateway, пам’яті та великих payload через шлях подій діагностики - - Виконує запит `diagnostics.stability` через WS RPC Gateway - - Охоплює helper персистентності bundle діагностичної стабільності - - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS залишаються нижче бюджету тиску, а глибина черг на сесію знову знижується до нуля + - Запускає реальний loopback Gateway з увімкненою діагностикою за замовчуванням + - Пропускає синтетичні churn message, memory і великих payload через шлях діагностичних подій gateway + - Виконує запити до `diagnostics.stability` через WS RPC Gateway + - Охоплює helper-и збереження діагностичного stability bundle + - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS залишаються в межах бюджету навантаження, а глибина черг для кожної сесії повертається до нуля - Очікування: - Безпечно для CI і без ключів - - Вузька lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway + - Вузька lane для подальшого аналізу регресій стабільності, а не заміна повного набору Gateway -### E2E (Gateway smoke) +### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Параметри runtime за замовчуванням: +- Типові параметри runtime: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує adaptive workers (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням працює в silent mode, щоб зменшити накладні витрати console I/O. + - Використовує адаптивну кількість worker-ів (CI: до 2, локально: типово 1). + - Типово запускається в silent mode, щоб зменшити накладні витрати console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість workers (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у console. + - `OPENCLAW_E2E_WORKERS=` — щоб примусово задати кількість worker-ів (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` — щоб знову ввімкнути докладний вивід у console. - Обсяг: - - End-to-end поведінка Gateway з кількома екземплярами + - End-to-end поведінка gateway з кількома екземплярами - Поверхні WebSocket/HTTP, pairing Node і важчі мережеві сценарії - Очікування: - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) + - Більше рухомих частин, ніж у unit-тестів (може бути повільніше) ### E2E: smoke OpenShell backend - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` - Обсяг: - - Запускає ізольований OpenShell gateway на хості через Docker + - Запускає ізольований Gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge + - Перевіряє поведінку файлової системи remote-canonical через міст fs sandbox - Очікування: - - Лише opt-in; не є частиною стандартного запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і працездатного Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox + - Лише за явним увімкненням; не є частиною типового запуску `pnpm test:e2e` + - Потребує локальний CLI `openshell` і робочий Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестові gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний бінарний файл CLI або wrapper script + - `OPENCLAW_E2E_OPENSHELL=1` — щоб увімкнути тест під час ручного запуску ширшого e2e-набору + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` — щоб указати нестандартний двійковий файл CLI або wrapper-скрипт ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` -- За замовчуванням: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) +- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей tool-calling, проблем автентифікації та поведінки rate limit + - Виявлення змін формату провайдера, особливостей tool calling, проблем автентифікації та поведінки rate limit - Очікування: - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / витрачає rate limits + - Коштує грошей / використовує rate limit - Краще запускати звужені підмножини, а не «все» -- Live-запуски читають `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють config/auth-матеріали до тимчасового test home, щоб unit-fixtures не могли змінити ваш реальний `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер за замовчуванням використовує тихіший режим: він зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає логи запуску gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете знову бачити повні стартові логи. -- Ротація API-ключів (специфічна для провайдера): установіть `*_API_KEYS` у форматі comma/semicolon або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використайте перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. -- Вивід progress/Heartbeat: - - Live-набори тепер виводять рядки прогресу до stderr, щоб було видно, що довгі виклики провайдера активні, навіть коли захоплення console у Vitest працює тихо. - - `vitest.live.config.ts` вимикає перехоплення console у Vitest, тому рядки прогресу провайдера/gateway транслюються негайно під час live-запусків. - - Налаштуйте Heartbeat для прямої моделі через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. +- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. +- Типово live-запуски все ще ізолюють `HOME` і копіюють конфігурацію/матеріали автентифікації до тимчасового 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. +- Вивід прогресу/Heartbeat: + - Live-набори тепер виводять рядки прогресу до stderr, тому довгі виклики провайдерів помітно активні навіть тоді, коли перехоплення console Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення console у Vitest, щоб рядки прогресу провайдера/Gateway одразу передавалися під час live-запусків. + - Налаштовуйте Heartbeat для прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat для Gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Використовуйте таку таблицю рішень: +Використовуйте цю таблицю рішень: -- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Зміни в мережевій взаємодії Gateway / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагодження «мій бот не працює» / збоїв, специфічних для провайдера / tool calling: запускайте звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Торкаєтесь мережевої взаємодії Gateway / протоколу WS / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій bot не працює» / збої, специфічні для провайдера / tool calling: запускайте звужений `pnpm test:live` -## Live: перевірка можливостей Android Node +## Live: огляд можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку зараз рекламує** підключений Android Node, і перевірити поведінку контракту команди. +- Мета: викликати **кожну команду, яку наразі оголошує** підключений Android Node, і перевірити поведінку контракту команди. - Обсяг: - - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не pair застосунок). - - Перевірка `node.invoke` Gateway покомандно для вибраного Android Node. -- Необхідна попередня підготовка: - - Android-застосунок уже підключено та pair з gateway. - - Застосунок залишається на передньому плані. - - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте пройти. + - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не pair-ить застосунок). + - Перевірка `node.invoke` Gateway команда за командою для вибраного Android Node. +- Обов’язкове попереднє налаштування: + - Android-застосунок уже підключений і pair-ений із 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-тести поділено на два шари, щоб ми могли ізолювати збої: -- «Пряма модель» показує, чи здатен провайдер/модель взагалі відповідати з наданим ключем. -- «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (сесії, історія, tools, політика sandbox тощо). +- «Пряма модель» показує, чи може провайдер/модель взагалі відповісти з наданим ключем. +- «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). -### Рівень 1: пряме завершення моделі (без gateway) +### Шар 1: Пряме завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані - - Запустити невелике completion для кожної моделі (і цільові регресії там, де потрібно) + - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані + - Виконати невелике completion для кожної моделі (і цільові регресії, де потрібно) - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб справді запустити цей набір; інакше він буде пропущений, щоб `pnpm test:live` залишався зосередженим на Gateway smoke +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб цей набір справді запускався; інакше він пропускається, щоб `pnpm test:live` залишався зосередженим на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це alias для modern allowlist - - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (comma allowlist) - - Для modern/all sweep за замовчуванням використовується curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого ліміту. + - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це alias для сучасного allowlist + - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) + - Огляди modern/all типово використовують підібрану верхню межу з високим сигналом; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного сучасного огляду або додатне число для меншої межі. - Як вибирати провайдерів: - - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (comma allowlist) + - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: сховище профілів і env-fallbacks + - Типово: сховище профілів і резервні значення з env - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API провайдера зламаний / ключ недійсний» від «конвеєр Gateway agent зламаний» - - Містить невеликі ізольовані регресії (приклад: повторне відтворення reasoning у OpenAI Responses/Codex Responses + потоки tool-call) + - Відокремлює «API провайдера зламаний / ключ недійсний» від «конвеєр gateway agent зламаний» + - Містить малі, ізольовані регресії (приклад: відтворення reasoning replay + потоки tool-call для OpenAI Responses/Codex Responses) -### Рівень 2: Gateway + smoke dev agent (те, що насправді робить "@openclaw") +### Шар 2: smoke Gateway + dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Підняти in-process gateway - - Створити/оновити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) - - Ітерувати моделі з ключами та перевіряти: - - «змістовну» відповідь (без tools) - - роботу реального виклику tool (read probe) - - необов’язкові додаткові probes tools (exec+read probe) - - що шляхи регресій OpenAI (лише tool-call → follow-up) продовжують працювати -- Деталі probe (щоб ви могли швидко пояснювати збої): - - `read` probe: тест записує nonce-файл у workspace і просить agent `read` його та повернути nonce. - - `exec+read` probe: тест просить agent записати nonce у тимчасовий файл через `exec`, а потім зчитати його назад через `read`. - - image probe: тест прикріплює згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. + - Підняти in-process Gateway + - Створити/патчити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) + - Ітеруватися по моделях-із-ключами та перевіряти: + - «змістовну» відповідь (без інструментів) + - що справжній виклик інструмента працює (probe читання) + - необов’язкові додаткові probe інструментів (probe exec+read) + - що шляхи регресії OpenAI (лише tool-call → follow-up) продовжують працювати +- Відомості про probe (щоб ви могли швидко пояснювати збої): + - probe `read`: тест записує файл nonce у робочий простір і просить агента `read` його та повернути nonce. + - probe `exec+read`: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. + - image probe: тест додає згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) - Як вибирати моделі: - - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це alias для modern allowlist - - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або comma list), щоб звузити вибір - - Для 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"` (comma allowlist) -- Tool + image probes у цьому live-тесті завжди ввімкнені: - - `read` probe + `exec+read` probe (навантаження на tools) - - image probe запускається, коли модель оголошує підтримку image input - - Потік (високий рівень): - - Тест генерує крихітний PNG з «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) + - Типово: сучасний allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це alias для сучасного allowlist + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір + - Огляди modern/all для gateway типово використовують підібрану верхню межу з високим сигналом; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного сучасного огляду або додатне число для меншої межі. +- Як вибирати провайдерів (уникайте «усе OpenRouter»): + - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) +- Probe інструментів + зображень у цьому live-тесті завжди увімкнені: + - probe `read` + probe `exec+read` (навантаження інструментів) + - image probe запускається, коли модель оголошує підтримку вхідних зображень + - Потік (на високому рівні): + - Тест генерує крихітний PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Embedded agent пересилає multimodal user message до моделі - - Перевірка: відповідь містить `cat` + код (толерантність OCR: незначні помилки допускаються) + - Gateway парсить attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Embedded agent передає мультимодальне повідомлення користувача до моделі + - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що можна тестувати на вашій машині (і точні id `provider/model`), виконайте: +Порада: щоб побачити, що саме ви можете протестувати на своїй машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list @@ -496,23 +505,23 @@ openclaw models list --json ## Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent, використовуючи локальний CLI backend, не торкаючись вашої конфігурації за замовчуванням. -- Значення smoke за замовчуванням для конкретного backend розміщено у визначенні `cli-backend.ts` extension-власника. +- Мета: перевірити конвеєр Gateway + agent, використовуючи локальний CLI backend, не змінюючи конфігурацію за замовчуванням. +- Типові значення smoke для конкретного backend зберігаються у визначенні `cli-backend.ts` extension-власника. - Увімкнення: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Значення за замовчуванням: - - Провайдер/модель за замовчуванням: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image походить із метаданих Plugin CLI backend-власника. +- Типові значення: + - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` + - Поведінка command/args/image походить із метаданих plugin CLI backend-власника. - Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне вкладення зображення (шляхи інжектуються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як CLI args замість інжекції в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати способом передавання args зображень, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_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`, щоб вимкнути стандартний probe безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути його, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -540,11 +549,11 @@ 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 package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований доступний для запису префікс `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує portable OAuth підписки Claude Code через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім виконує два ходи Gateway CLI-backend без збереження env-змінних API-ключа Anthropic. Ця лінія підписки за замовчуванням вимикає probes Claude MCP/tool і image, оскільки Claude наразі маршрутизує використання сторонніх застосунків через додаткову оплату usage замість звичайних лімітів плану підписки. -- Live smoke CLI-backend тепер перевіряє той самий end-to-end потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик tool MCP `cron`, перевірений через CLI gateway. -- Стандартний smoke Claude також оновлює сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію від імені non-root користувача `node`. +- Він визначає метадані smoke CLI з extension-власника, а потім встановлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований доступний для запису prefix за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносиму OAuth-автентифікацію підписки Claude Code через `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він підтверджує прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження змінних середовища ключа Anthropic API. Ця лінія підписки типово вимикає probe Claude MCP/tool і image probe, тому що Claude наразі маршрутизує використання сторонніх застосунків через додаткове виставлення рахунків, а не через звичайні ліміти плану підписки. +- Live smoke CLI-backend тепер перевіряє той самий end-to-end потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик інструмента MCP `cron`, перевірений через CLI Gateway. +- Типовий smoke для Claude також патчить сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. ## Live: smoke ACP bind (`/acp spawn ... --bind here`) @@ -552,13 +561,13 @@ pnpm test:docker:live-cli-backend:gemini - Мета: перевірити реальний потік прив’язки розмови ACP з live ACP agent: - надіслати `/acp spawn --bind here` - прив’язати синтетичну розмову message-channel на місці - - надіслати звичайний follow-up у цій самій розмові - - перевірити, що follow-up потрапляє в transcript прив’язаної сесії ACP + - надіслати звичайне follow-up у тій самій розмові + - перевірити, що follow-up потрапляє до транскрипту прив’язаної сесії ACP - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Значення за замовчуванням: - - ACP agents у Docker: `claude,codex,gemini` +- Типові значення: + - ACP agent-и в Docker: `claude,codex,gemini` - ACP agent для прямого `pnpm test:live ...`: `claude` - Синтетичний channel: контекст розмови у стилі Slack DM - ACP backend: `acpx` @@ -570,8 +579,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.4` - Примітки: - - Ця лінія використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли під’єднати контекст message-channel, не вдаючи зовнішню доставку. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent Plugin `acpx` для вибраного harness agent ACP. + - Ця лінія використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли прикріплювати контекст message-channel без удавання зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent-ів plugin `acpx` для вибраного ACP harness agent. Приклад: @@ -598,34 +607,34 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: - Docker runner розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він послідовно запускає ACP bind smoke для всіх підтримуваних live CLI agents: `claude`, `codex`, потім `gemini`. +- Типово він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI agent-ів: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він читає `~/.profile`, переносить відповідні auth-матеріали CLI в контейнер, встановлює `acpx` у доступний для запису npm prefix, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. -- Усередині Docker runner встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера з прочитаного profile доступними для дочірнього harness CLI. +- Він використовує `~/.profile`, розміщує відповідні матеріали автентифікації CLI в контейнері, встановлює `acpx` у доступний для запису npm prefix, а потім встановлює запитаний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його бракує. +- Усередині Docker runner встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав змінні середовища провайдера з підключеного профілю доступними для дочірнього harness CLI. ## Live: smoke harness app-server Codex -- Мета: перевірити harness Codex, яким володіє Plugin, через звичайний метод - gateway `agent`: - - завантажити bundled Plugin `codex` +- Мета: перевірити Codex harness, що належить plugin, через звичайний gateway + метод `agent`: + - завантажити вбудований plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - надіслати перший хід gateway agent до `codex/gpt-5.4` - - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що потік - app-server може відновитися - - запустити `/codex status` і `/codex models` через той самий шлях команди - gateway - - необов’язково запустити два shell probes з ескалацією, перевірені Guardian: одну - безпечну команду, яку слід схвалити, і одне фіктивне вивантаження секрету, яке має бути - відхилене, щоб agent перепитав + - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що тред app-server + може відновитися + - запустити `/codex status` і `/codex models` через той самий шлях + команди gateway + - за бажанням виконати дві перевірки escalated shell, переглянуті Guardian: одну нешкідливу + команду, яку слід схвалити, і одне фіктивне завантаження секрету, + яке має бути відхилене, щоб agent попросив підтвердження - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` -- Модель за замовчуванням: `codex/gpt-5.4` +- Типова модель: `codex/gpt-5.4` - Необов’язковий image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` - Необов’язковий MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` - Необов’язковий Guardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex - не міг пройти, тихо переключившись на PI. -- Автентифікація: `OPENAI_API_KEY` з shell/profile, а також необов’язково скопійовані +- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex + harness не міг успішно пройти тест, непомітно переключившись на PI. +- Автентифікація: `OPENAI_API_KEY` з shell/profile, а також за бажанням скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -650,25 +659,28 @@ 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 prefix, переносить дерево source, а потім запускає лише live-тест harness Codex. -- У Docker probes image, MCP/tool і Guardian увімкнені за замовчуванням. Установіть +- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + автентифікації Codex CLI, якщо вони є, встановлює `@openai/codex` у доступний для запису змонтований npm + prefix, розміщує вихідне дерево, а потім запускає лише 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-тесту, тому fallback `openai-codex/*` або PI не може приховати регресію harness Codex. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і конфігурація live + тесту, щоб fallback `openai-codex/*` або PI не міг приховати регресію Codex harness. ### Рекомендовані live-рецепти -Вузькі, явні allowlist — найшвидші й найменш нестабільні: +Найшвидші та найменш флейкові — вузькі, явні allowlist: - Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Одна модель, Gateway smoke: +- Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling через кількох провайдерів: +- Tool calling для кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Фокус на Google (API-ключ Gemini + Antigravity): @@ -677,35 +689,35 @@ pnpm test:docker:live-codex-harness Примітки: -- `google/...` використовує Gemini API (API-ключ). +- `google/...` використовує API Gemini (API-ключ). - `google-antigravity/...` використовує міст OAuth Antigravity (endpoint agent у стилі Cloud Code Assist). - `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості tooling). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений у Google Gemini API через HTTP (автентифікація через API-ключ / profile); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw викликає локальний бінарний файл `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/tool support/version skew). + - API: OpenClaw викликає хостований API Gemini від Google через HTTP (автентифікація через API-ключ / профіль); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw викликає локальний двійковий файл `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/підтримка інструментів/version skew). -## Live: матриця моделей (що ми покриваємо) +## Live: матриця моделей (що ми охоплюємо) -Фіксованого «списку моделей CI» немає (live є opt-in), але це **рекомендовані** моделі для регулярного покриття на dev-машині з ключами. +Немає фіксованого «списку моделей CI» (live — це opt-in), але це **рекомендовані** моделі, які варто регулярно охоплювати на машині розробника з ключами. -### Сучасний smoke-набір (tool calling + image) +### Сучасний набір smoke (tool calling + image) Це запуск «поширених моделей», який ми очікуємо підтримувати працездатним: - OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) -- Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) +- Google (API Gemini): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` і `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запустіть Gateway smoke з tools + image: +Запуск smoke Gateway з tools + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` ### Базовий рівень: tool calling (Read + необов’язковий Exec) -Виберіть принаймні одну модель з кожного сімейства провайдерів: +Виберіть принаймні одну модель для кожної родини провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -713,81 +725,81 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (було б добре мати): +Необов’язкове додаткове покриття (бажано мати): -- xAI: `xai/grok-4` (або найновіша доступна) +- xAI: `xai/grok-4` (або найновіша доступна версія) - Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас увімкнено) - Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) -### Vision: надсилання image (вкладення → multimodal message) +### Vision: надсилання зображень (вкладення → мультимодальне повідомлення) -Додайте принаймні одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб перевірити image probe. +Додайте принаймні одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI з підтримкою vision тощо), щоб перевірити image probe. -### Aggregators / альтернативні gateway +### Агрегатори / альтернативні Gateway -Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: - OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/config): +Інші провайдери, які можна включити в live-матрицю (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні endpoint): `minimax` (хмара/API), а також будь-який проксі, сумісний з OpenAI/Anthropic (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко фіксувати в документації «всі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс наявні ключі. +Порада: не намагайтеся жорстко закодувати в документації «усі моделі». Авторитетним списком є те, що на вашій машині повертає `discoverModels(...)`, плюс доступні ключі. ## Облікові дані (ніколи не комітьте) -Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: +Live-тести виявляють облікові дані так само, як це робить CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знайти ті самі ключі. -- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. +- Якщо CLI працює, live-тести мають знаходити ті самі ключі. +- Якщо live-тест повідомляє «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілів» у live-тестах) -- Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище ключів профілів) -- Локальні live-запуски за замовчуванням копіюють активний config, файли `auth-profiles.json` для окремих агентів, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` прибираються, щоб probes не торкалися вашого реального host workspace. +- Профілі автентифікації для кожного agent: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілю» у live-тестах) +- Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється в staged live home, якщо присутній, але це не головне сховище ключів профілю) +- Локальні live-запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для кожного agent, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staged live homes пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probe не торкалися вашого реального host workspace. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на ключі з env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker runner-и нижче (вони можуть монтувати `~/.profile` у контейнер). -## Deepgram live (транскрибування аудіо) +## Live Deepgram (транскрипція аудіо) - Тест: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## BytePlus coding plan live +## Live BytePlus coding plan - Тест: `src/agents/byteplus.live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## ComfyUI workflow media live +## Live медіа workflow ComfyUI - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє bundled шляхи comfy image, video та `music_generate` + - Перевіряє вбудовані шляхи comfy для зображень, відео і `music_generate` - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` - - Корисно після змін у надсиланні workflow comfy, polling, downloads або реєстрації Plugin + - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації plugin -## Image generation live +## Live: генерація зображень - Тест: `src/image-generation/runtime.live.test.ts` - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перелічує кожен зареєстрований Plugin провайдера генерації image - - Завантажує відсутні env-змінні провайдера з вашої login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API-ключі перед збереженими auth profiles, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдерів без придатної auth/profile/model - - Проганяє стандартні варіанти генерації image через спільну runtime capability: + - Перелічує кожен зареєстрований plugin провайдера генерації зображень + - Завантажує відсутні змінні середовища провайдера з вашої login shell (`~/.profile`) перед перевіркою + - Типово використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Проганяє стандартні варіанти генерації зображень через спільну runtime-можливість: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні bundled провайдери, які покриваються: +- Поточні вбудовані провайдери, що охоплюються: - `openai` - `google` - `xai` @@ -796,276 +808,277 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише з env -## Music generation live +## Live: генерація музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний bundled шлях провайдера генерації music + - Перевіряє спільний шлях вбудованого провайдера генерації музики - Наразі охоплює Google і MiniMax - - Завантажує env-змінні провайдера з вашої login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API-ключі перед збереженими auth profiles, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдерів без придатної auth/profile/model - - Запускає обидва оголошені runtime modes, коли вони доступні: - - `generate` з вхідними даними лише через prompt + - Завантажує змінні середовища провайдера з вашої login shell (`~/.profile`) перед перевіркою + - Типово використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Запускає обидва оголошені режими runtime, коли вони доступні: + - `generate` із вхідними даними лише у вигляді prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - Поточне покриття спільної лінії: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, не цей спільний sweep + - `comfy`: окремий live-файл Comfy, а не цей спільний огляд - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише з env -## Video generation live +## Live: генерація відео - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний bundled шлях провайдера генерації video - - За замовчуванням використовує безпечний для релізу smoke-шлях: провайдери без FAL, один запит text-to-video на провайдера, односекундний prompt про lobster і ліміт операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) - - За замовчуванням пропускає FAL, оскільки затримка черги на боці провайдера може домінувати над часом релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно запустити його - - Завантажує env-змінні провайдера з вашої login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API-ключі перед збереженими auth profiles, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell credentials - - Пропускає провайдерів без придатної auth/profile/model - - За замовчуванням запускає лише `generate` + - Перевіряє спільний шлях вбудованого провайдера генерації відео + - Типово використовує безпечний для релізу 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-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Типово запускає лише `generate` - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний image input на основі buffer у спільному sweep - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний video input на основі buffer у спільному sweep - - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному sweep: - - `vydra`, оскільки bundled `veo3` підтримує лише текст, а bundled `kling` вимагає віддалений image URL + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід зображень із буфера в межах спільного огляду + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід відео з буфера в межах спільного огляду + - Поточні провайдери `imageToVideo`, які оголошено, але пропущено в спільному огляді: + - `vydra`, тому що вбудований `veo3` підтримує лише text, а вбудований `kling` потребує віддалений URL зображення - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс лінію `kling`, яка за замовчуванням використовує fixture з віддаленим image URL + - цей файл запускає `veo3` text-to-video плюс лінію `kling`, яка типово використовує фікстуру віддаленого URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному sweep: - - `alibaba`, `qwen`, `xai`, оскільки ці шляхи зараз вимагають віддалені reference URL `http(s)` / MP4 - - `google`, оскільки поточна спільна лінія Gemini/Veo використовує локальні вхідні дані на основі buffer, і цей шлях не приймається у спільному sweep - - `openai`, оскільки поточна спільна лінія не гарантує доступ до video inpaint/remix, специфічний для org + - Поточні провайдери `videoToVideo`, які оголошено, але пропущено в спільному огляді: + - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі потребують віддалені еталонні URL `http(s)` / MP4 + - `google`, тому що поточна спільна лінія Gemini/Veo використовує локальний вхід із буфера, і цей шлях не приймається в межах спільного огляду + - `openai`, тому що поточна спільна лінія не гарантує доступ до org-специфічного video inpaint/remix - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до стандартного sweep, зокрема FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції кожного провайдера для агресивного smoke-запуску + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового огляду, включно з FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження операції для кожного провайдера в агресивному smoke-запуску - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів та ігнорувати перевизначення лише з env ## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори image, music і video через один native entrypoint репозиторію - - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` - - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну auth - - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і quiet mode залишається узгодженою + - Запускає спільні live-набори для зображень, музики й відео через одну вбудовану в репозиторій точку входу + - Автоматично завантажує відсутні змінні середовища провайдера з `~/.profile` + - Типово автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію + - Повторно використовує `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-ранери (необов’язкові перевірки «працює в Linux») +## Docker runner-и (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві групи: +Ці Docker runner-и поділяються на дві групи: -- Live-model ранери: `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`), монтують ваш локальний каталог config і workspace (і читають `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live-ранери за замовчуванням використовують менший smoke-ліміт, щоб повний Docker sweep залишався практичним: - `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` за замовчуванням використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Runner-и live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл для профільних ключів усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та workspace (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні точки входу — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live runner-и типово використовують меншу верхню межу smoke, щоб повний Docker-огляд залишався практичним: + `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці змінні середовища, коли вам явно потрібне більше вичерпне сканування. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ліній live. -- Smoke-ранери контейнерів: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools` і `test:docker:plugins` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. +- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ліній live. +- Runner-и container smoke: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-ранери live-model також bind-mount лише потрібні CLI auth homes (або всі підтримувані, коли запуск не звужений), а потім копіюють їх у home контейнера перед запуском, щоб зовнішній OAuth CLI міг оновлювати токени, не змінюючи auth store хоста: +Docker runner-и live-моделей також bind-mount-ять лише потрібні home-каталоги автентифікації CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх до home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи сховище автентифікації на хості: - Прямі моделі: `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`) +- 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`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Мережа Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Міст каналу MCP (seeded Gateway + stdio bridge + raw smoke кадру сповіщення Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти MCP комплекту Pi (реальний stdio MCP server + embedded smoke allow/deny профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення MCP Cron/subagent (реальний Gateway + teardown дочірнього stdio MCP після ізольованого Cron і одноразових запусків subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke встановлення + alias `/plugin` + семантика restart комплекту Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -- Runtime dependencies 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 dependencies bundled Plugin під час ітерації, вимикаючи не пов’язані сценарії, наприклад: +- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Майстер онбордингу (TTY, повне scaffold): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Мережева взаємодія Gateway (два контейнери, автентифікація WS + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Міст каналу MCP (seeded Gateway + міст stdio + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти MCP пакета Pi (реальний stdio MCP server + embedded smoke allow/deny профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Очищення MCP Cron/subagent (реальний Gateway + teardown дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugin-и (smoke встановлення + alias `/plugin` + семантика перезапуску пакета Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-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`. +- Runtime-залежності вбудованих plugin: `pnpm test:docker:bundled-channel-deps` типово збирає невеликий Docker runner image, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій встановлення Linux. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову хоста після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Звужуйте runtime-залежності вбудованих plugin під час ітерацій, вимикаючи не пов’язані сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Docker-ранери live-model також bind-mount поточний checkout у режимі лише для читання й -переносять його до тимчасового workdir усередині контейнера. Це дозволяє зберігати -runtime-образ компактним і водночас запускати Vitest точно на вашому локальному source/config. -Крок перенесення пропускає великі локальні кеші й результати збірки застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні каталоги `.build` або +Docker runner-и live-моделей також bind-mount-ять поточний checkout у режимі лише для читання і +розміщують його в тимчасовому workdir усередині контейнера. Це дозволяє зберігати runtime +image компактним, але все одно запускати Vitest точно на ваших локальних source/config. +Крок розміщення пропускає великі локальні кеші та артефакти збірки застосунків, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні для застосунків каталоги `.build` або виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -артефактів, специфічних для машини. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes Gateway не запускали -реальні workers channel Telegram/Discord тощо всередині контейнера. +машинозалежних артефактів. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали +реальні worker-и каналів Telegram/Discord тощо всередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити Gateway +`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити gateway live-покриття з цієї Docker-лінії. -`test:docker:openwebui` — це smoke вищого рівня на сумісність: він запускає -контейнер gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoint, -запускає pinned контейнер Open WebUI проти цього gateway, виконує вхід через +`test:docker:openwebui` — це smoke-перевірка сумісності вищого рівня: вона запускає +контейнер Gateway OpenClaw з увімкненими HTTP endpoint, сумісними з OpenAI, +запускає контейнер Open WebUI із зафіксованою версією проти цього Gateway, виконує вхід через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через proxy `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження -образу Open WebUI, а Open WebUI може потребувати завершення власного cold-start налаштування. +реальний chat-запит через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, тому що Docker може потребувати завантажити +image Open WebUI, а сам Open WebUI може потребувати завершити власне cold-start налаштування. Ця лінія очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(`~/.profile` за замовчуванням) — основний спосіб надати його в Dockerized-запусках. +(типово `~/.profile`) є основним способом надати його в Dockerized-запусках. Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway -container, запускає другий container, який стартує `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання transcript, метадані attachment, -поведінку черги live events, маршрутизацію вихідного надсилання та сповіщення в стилі Claude про channel + -дозволи через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує сирі stdio MCP frames, тому smoke перевіряє те, що -міст справді випромінює, а не лише те, що випадково показує конкретний SDK клієнта. -`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує ключа -live-моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server -усередині контейнера, матеріалізує цей server через embedded runtime MCP комплекту Pi, -виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають +реального облікового запису Telegram, Discord або iMessage. Він запускає seeded-контейнер +Gateway, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, +поведінку live-черги подій, маршрутизацію вихідного надсилання, а також channel + +сповіщення про дозволи у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +безпосередньо інспектує raw stdio MCP frame, тож smoke перевіряє те, що міст +справді виводить, а не лише те, що випадково показує конкретний client SDK. +`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує +ключа live-моделі. Він збирає Docker image репозиторію, запускає реальний stdio MCP probe server +усередині контейнера, матеріалізує цей server через вбудований runtime MCP пакета Pi, +виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. -`test:docker:cron-mcp-cleanup` є детермінованим і не потребує ключа -live-моделі. Він запускає seeded Gateway з реальним stdio MCP probe server, виконує -ізольований хід Cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, +`test:docker:cron-mcp-cleanup` є детермінованим і не потребує ключа live-моделі. +Він запускає seeded Gateway з реальним stdio MCP probe server, виконує +ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручний smoke plain-language thread для ACP (не CI): +Ручний smoke plain-language для тредів ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. +- Зберігайте цей скрипт для регресійних сценаріїв/налагодження. Він може знову знадобитися для перевірки маршрутизації тредів ACP, тому не видаляйте його. -Корисні env-змінні: +Корисні змінні середовища: -- `OPENCLAW_CONFIG_DIR=...` (за замовчуванням: `~/.openclaw`) монтується в `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (за замовчуванням: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (за замовчуванням: `~/.profile`) монтується в `/home/node/.profile` і читається перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, прочитані з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої CLI auth -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker -- Зовнішні CLI auth-каталоги/файли в `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів - - Каталоги за замовчуванням: `.minimax` - - Файли за замовчуванням: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` +- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і підключається перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише змінні середовища, підключені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої CLI-автентифікації +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- Зовнішні каталоги/файли CLI-автентифікації під `$HOME` монтуються в режимі лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів + - Типові каталоги: `.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` або comma list на кшталт `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Ручне перевизначення: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків, яким не потрібна перебудова - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться зі сховища профілів (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway показує для smoke Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити pinned tag образу Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити тег image Open WebUI із зафіксованою версією ## Перевірка документації Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли вам також потрібна перевірка заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресія (безпечна для CI) +## Офлайн-регресія (безпечно для CI) Це регресії «реального конвеєра» без реальних провайдерів: -- Tool calling Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, записує config + примусову auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Tool calling Gateway (мокований OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Wizard Gateway (WS `wizard.start`/`wizard.next`, примусово записує config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агента (Skills) +## Оцінювання надійності agent (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності agent»: -- Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- End-to-end потоки майстра, які перевіряють прив’язку сесії та ефекти config (`src/gateway/gateway.test.ts`). +- Мокований tool calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- End-to-end потоки wizard, які перевіряють session wiring і ефекти config (`src/gateway/gateway.test.ts`). -Що ще відсутнє для Skills (див. [Skills](/uk/tools/skills)): +Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Вибір рішення:** коли Skills перелічено в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/args? -- **Контракти робочих процесів:** багатокрокові сценарії, які перевіряють порядок tools, перенесення історії сесії та межі sandbox. +- **Decisioning:** коли Skills перелічено в prompt, чи вибирає agent правильний skill (або уникає нерелевантних)? +- **Compliance:** чи читає agent `SKILL.md` перед використанням і чи виконує потрібні кроки/args? +- **Workflow contracts:** багатохідні сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні оцінювання мають спочатку залишатися детермінованими: +Майбутні eval-и мають спочатку залишатися детермінованими: -- Runner сценаріїв з mock providers для перевірки викликів tools + їх порядку, читання skill-файлів і прив’язки сесії. -- Невеликий набір сценаріїв, сфокусованих на Skills (використати чи уникнути, gating, injection у prompt). -- Необов’язкові live-оцінювання (opt-in, керовані через env) лише після того, як безпечний для CI набір буде готовий. +- Scenario runner з mock-провайдерами для перевірки викликів інструментів + їх порядку, читання файлів skill і wiring сесії. +- Невеликий набір сценаріїв, зосереджених на skills (використати чи уникнути, gating, prompt injection). +- Необов’язкові live eval-и (opt-in, gated через env) лише після того, як буде готовий безпечний для CI набір. -## Контрактні тести (форма Plugin і channel) +## Contract-тести (форма plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму -контракту інтерфейсу. Вони ітерують усі виявлені plugins і запускають набір перевірок -форми та поведінки. Unit-лінія `pnpm test` за замовчуванням навмисно -пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, -коли торкаєтеся спільних поверхонь channel або provider. +Contract-тести перевіряють, що кожен зареєстрований plugin і channel відповідає +своєму interface contract. Вони проходять по всіх виявлених plugin-ах і запускають набір +перевірок форми та поведінки. Типова unit-лінія `pnpm test` навмисно +пропускає ці файли спільних seam і smoke; запускайте contract-команди явно, +коли змінюєте спільні поверхні channel або провайдера. ### Команди - Усі контракти: `pnpm test:contracts` - Лише контракти channel: `pnpm test:contracts:channels` -- Лише контракти provider: `pnpm test:contracts:plugins` +- Лише контракти провайдерів: `pnpm test:contracts:plugins` ### Контракти channel Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма Plugin (id, name, capabilities) -- **setup** - Контракт майстра налаштування +- **plugin** - Базова форма plugin (id, name, capabilities) +- **setup** - Contract майстра налаштування - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel -- **threading** - Обробка ID thread -- **directory** - API directory/roster -- **group-policy** - Примусове застосування group policy +- **threading** - Обробка Thread ID +- **directory** - API каталогу/реєстру +- **group-policy** - Забезпечення group policy -### Контракти status provider +### Контракти статусу провайдера Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Probes status channel -- **registry** - Форма реєстру Plugin +- **status** - Перевірки статусу channel +- **registry** - Форма реєстру plugin -### Контракти provider +### Контракти провайдерів Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку auth -- **auth-choice** - Вибір/selection auth +- **auth** - Contract потоку автентифікації +- **auth-choice** - Вибір/відбір автентифікації - **catalog** - API каталогу моделей -- **discovery** - Виявлення Plugin -- **loader** - Завантаження Plugin -- **runtime** - Runtime provider -- **shape** - Форма/інтерфейс Plugin +- **discovery** - Виявлення plugin +- **loader** - Завантаження plugin +- **runtime** - Runtime провайдера +- **shape** - Форма/interface plugin - **wizard** - Майстер налаштування ### Коли запускати -- Після зміни export або subpath у plugin-sdk -- Після додавання або зміни Plugin channel чи provider -- Після рефакторингу реєстрації Plugin або виявлення +- Після зміни export-ів або subpath-ів plugin-sdk +- Після додавання або зміни channel або plugin провайдера +- Після рефакторингу реєстрації plugin або виявлення -Контрактні тести запускаються в CI і не потребують реальних API-ключів. +Contract-тести запускаються в CI і не потребують реальних API-ключів. ## Додавання регресій (рекомендації) -Коли ви виправляєте проблему provider/model, виявлену в live: +Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Додайте безпечну для CI регресію, якщо це можливо (mock/stub provider або захоплення точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env-змінні -- Віддавайте перевагу найменшому рівню, який ловить баг: - - баг перетворення/відтворення запиту provider → тест прямих моделей - - баг конвеєра gateway session/history/tool → Gateway live smoke або безпечний для CI mock-тест gateway -- Guardrail обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef із метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегмента обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою на некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- За можливості додайте безпечну для CI регресію (мокований/заглушений провайдер або захоплення точної трансформації форми запиту) +- Якщо це за своєю природою лише live-проблема (rate limit, політики автентифікації), залишайте live-тест вузьким і opt-in через змінні середовища +- Надавайте перевагу найменшому шару, який виявляє помилку: + - помилка конвертації/повторення запиту провайдера → тест прямих моделей + - помилка конвеєра сесія/історія/інструменти gateway → gateway live smoke або безпечний для CI мокований тест gateway +- Захисне обмеження обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` отримує одну вибіркову ціль на клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегмента обходу відхиляються. + - Якщо ви додаєте нову родину цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою для некласифікованих target id, щоб нові класи не могли бути тихо пропущені. diff --git a/docs/uk/platforms/linux.md b/docs/uk/platforms/linux.md index 77b5fb21f..28a8e1f9a 100644 --- a/docs/uk/platforms/linux.md +++ b/docs/uk/platforms/linux.md @@ -1,47 +1,48 @@ --- read_when: - - Пошук статусу companion app для Linux - - Планування покриття платформ або внеску в розробку -summary: Підтримка Linux + статус companion app -title: Linux App + - Шукаю статус супутнього застосунку для Linux + - Планування покриття платформ або внесків + - Налагодження Linux OOM-kill або коду виходу 137 на VPS чи в контейнері +summary: Підтримка Linux + статус супутнього застосунку +title: Застосунок Linux x-i18n: - generated_at: "2026-04-05T18:09:53Z" + generated_at: "2026-04-23T04:54:39Z" model: gpt-5.4 provider: openai - source_hash: 5dbfc89eb65e04347479fc6c9a025edec902fb0c544fb8d5bd09c24558ea03b1 + source_hash: c56151406517a1259e66626b8f4b48c16917b10580e7626463afd8a68dc286f7 source_path: platforms/linux.md workflow: 15 --- -# Linux App +# Застосунок Linux -Gateway повністю підтримується на Linux. **Node — рекомендоване runtime-середовище**. -Bun не рекомендується для Gateway (помилки WhatsApp/Telegram). +Gateway повністю підтримується на Linux. **Node — рекомендоване середовище виконання**. +Bun не рекомендується для Gateway (баги WhatsApp/Telegram). -Нативні companion apps для Linux заплановані. Якщо ви хочете допомогти створити такий застосунок, внески вітаються. +Власні супутні застосунки для Linux заплановані. Внески вітаються, якщо ви хочете допомогти створити такий застосунок. ## Швидкий шлях для початківців (VPS) -1. Установіть Node 24 (рекомендовано; Node 22 LTS, зараз `22.14+`, також працює для сумісності) +1. Встановіть Node 24 (рекомендовано; Node 22 LTS, наразі `22.14+`, усе ще працює для сумісності) 2. `npm i -g openclaw@latest` 3. `openclaw onboard --install-daemon` 4. Із вашого ноутбука: `ssh -N -L 18789:127.0.0.1:18789 @` -5. Відкрийте `http://127.0.0.1:18789/` і пройдіть автентифікацію за допомогою налаштованого shared secret (типово token; password, якщо ви встановили `gateway.auth.mode: "password"`) +5. Відкрийте `http://127.0.0.1:18789/` і пройдіть автентифікацію за допомогою налаштованого спільного секрету (типово токен; пароль, якщо ви встановили `gateway.auth.mode: "password"`) -Повний гайд для Linux server: [Linux Server](/vps). Покроковий приклад VPS: [exe.dev](/install/exe-dev) +Повний посібник із Linux Server: [Linux Server](/uk/vps). Покроковий приклад VPS: [exe.dev](/uk/install/exe-dev) ## Встановлення -- [Початок роботи](/start/getting-started) -- [Встановлення та оновлення](/install/updating) -- Необов’язкові потоки: [Bun (експериментально)](/install/bun), [Nix](/install/nix), [Docker](/install/docker) +- [Початок роботи](/uk/start/getting-started) +- [Встановлення й оновлення](/uk/install/updating) +- Додаткові варіанти: [Bun (experimental)](/uk/install/bun), [Nix](/uk/install/nix), [Docker](/uk/install/docker) ## Gateway -- [Runbook Gateway](/gateway) -- [Конфігурація](/gateway/configuration) +- [Інструкція з експлуатації Gateway](/uk/gateway) +- [Конфігурація](/uk/gateway/configuration) -## Встановлення сервісу Gateway (CLI) +## Встановлення служби Gateway (CLI) Використайте один із цих варіантів: @@ -61,7 +62,7 @@ openclaw gateway install openclaw configure ``` -Коли буде запит, виберіть **Gateway service**. +Коли з’явиться запит, виберіть **Служба Gateway**. Відновлення/міграція: @@ -69,12 +70,13 @@ openclaw configure openclaw doctor ``` -## Керування системою (користувацький unit systemd) +## Керування системою (користувацький модуль systemd) -OpenClaw за замовчуванням встановлює користувацький сервіс systemd **user**. Для спільних або постійно увімкнених серверів використовуйте **system** service. Команди `openclaw gateway install` і -`openclaw onboard --install-daemon` уже генерують для вас поточний канонічний unit; -пишіть його вручну лише тоді, коли вам потрібне кастомне налаштування system/service-manager. -Повні вказівки щодо сервісу містяться в [runbook Gateway](/gateway). +OpenClaw типово встановлює користувацьку службу systemd. Використовуйте системну +службу для спільних або постійно активних серверів. `openclaw gateway install` і +`openclaw onboard --install-daemon` уже генерують для вас поточний канонічний модуль; +створюйте його вручну лише тоді, коли вам потрібне нетипове налаштування +system/service-manager. Повні вказівки щодо служби наведено в [інструкції з експлуатації Gateway](/uk/gateway). Мінімальне налаштування: @@ -104,3 +106,41 @@ WantedBy=default.target ``` systemctl --user enable --now openclaw-gateway[-].service ``` + +## Тиск на пам’ять і OOM-kill + +У Linux ядро вибирає жертву OOM, коли на хості, у VM або cgroup контейнера +закінчується пам’ять. Gateway може бути невдалою жертвою, оскільки він утримує +довгоживучі сесії та з’єднання каналів. Тому OpenClaw, коли це можливо, +зміщує пріоритет так, щоб тимчасові дочірні процеси вбивалися раніше за Gateway. + +Для відповідних запусків дочірніх процесів у Linux OpenClaw запускає дочірній +процес через коротку обгортку `/bin/sh`, яка підвищує власний `oom_score_adj` +дочірнього процесу до `1000`, а потім виконує `exec` реальної команди. Це +непривілейована операція, оскільки дочірній процес лише підвищує ймовірність +власного OOM-kill. + +Поверхні дочірніх процесів, які охоплюються, включають: + +- дочірні процеси команд, керовані supervisor, +- дочірні процеси PTY shell, +- дочірні процеси сервера MCP stdio, +- процеси браузера/Chrome, запущені OpenClaw. + +Обгортка працює лише в Linux і пропускається, якщо `/bin/sh` недоступний. Вона +також пропускається, якщо в середовищі дочірнього процесу встановлено `OPENCLAW_CHILD_OOM_SCORE_ADJ=0`, `false`, +`no` або `off`. + +Щоб перевірити дочірній процес: + +```bash +cat /proc//oom_score_adj +``` + +Очікуване значення для охоплених дочірніх процесів — `1000`. Процес Gateway має +зберігати свій звичайний показник, зазвичай `0`. + +Це не замінює звичайне налаштування пам’яті. Якщо VPS або контейнер регулярно +завершує дочірні процеси, збільште ліміт пам’яті, зменште паралелізм або +додайте жорсткіші обмеження ресурсів, наприклад systemd `MemoryMax=` або +ліміти пам’яті на рівні контейнера. diff --git a/docs/uk/vps.md b/docs/uk/vps.md index d364ca798..375aa980f 100644 --- a/docs/uk/vps.md +++ b/docs/uk/vps.md @@ -1,25 +1,25 @@ --- read_when: - - Ви хочете запустити Gateway на сервері Linux або хмарному VPS - - Вам потрібен короткий огляд посібників із розміщення - - Вам потрібне загальне налаштування сервера Linux для OpenClaw + - Ви хочете запустити Gateway на Linux-сервері або хмарному VPS + - Вам потрібен короткий огляд посібників із хостингу + - Вам потрібне загальне налаштування Linux-сервера для OpenClaw sidebarTitle: Linux Server -summary: Запустіть OpenClaw на сервері Linux або хмарному VPS — вибір провайдера, архітектура та налаштування продуктивності -title: Сервер Linux +summary: Запуск OpenClaw на Linux-сервері або хмарному VPS — вибір провайдера, архітектура та налаштування продуктивності +title: Linux-сервер x-i18n: - generated_at: "2026-04-13T13:14:21Z" + generated_at: "2026-04-23T04:54:32Z" model: gpt-5.4 provider: openai - source_hash: e623f4c770132e01628d66bfb8cd273bbef6dad633b812496c90da5e3e0f1383 + source_hash: 759428cf20204207a5505a73c880aa776ddd0eabf969fc0dcf444fc8ce6991b2 source_path: vps.md workflow: 15 --- -# Сервер Linux +# Linux-сервер -Запустіть Gateway OpenClaw на будь-якому сервері Linux або хмарному VPS. Ця сторінка допоможе вам -вибрати провайдера, пояснює, як працюють хмарні розгортання, і охоплює загальні -налаштування Linux, які застосовуються всюди. +Запустіть Gateway OpenClaw на будь-якому Linux-сервері або хмарному VPS. Ця сторінка допоможе вам +вибрати провайдера, пояснює, як працюють хмарні розгортання, і охоплює загальне +налаштування Linux, яке застосовується всюди. ## Вибір провайдера @@ -32,47 +32,47 @@ x-i18n: Docker на VPS Hetzner VPS із налаштуванням в один клік Compute Engine - Віртуальна машина Linux - Віртуальна машина з HTTPS-проксі - ARM на власному хостингу + Linux VM + VM із HTTPS-проксі + ARM із самостійним хостингом -**AWS (EC2 / Lightsail / безкоштовний рівень)** також добре працює. -Доступне відеооглядове керівництво від спільноти за адресою +**AWS (EC2 / Lightsail / free tier)** також добре підходить. +Відеоогляд від спільноти доступний за посиланням [x.com/techfrenAJ/status/2014934471095812547](https://x.com/techfrenAJ/status/2014934471095812547) (ресурс спільноти — може стати недоступним). ## Як працюють хмарні налаштування -- **Gateway працює на VPS** і керує станом + робочим простором. -- Ви підключаєтеся з ноутбука або телефона через **Control UI** чи **Tailscale/SSH**. -- Сприймайте VPS як джерело істини та регулярно **створюйте резервні копії** стану + робочого простору. -- Безпечний варіант за замовчуванням: тримайте Gateway на loopback-інтерфейсі та отримуйте доступ через SSH-тунель або Tailscale Serve. - Якщо ви прив’язуєтеся до `lan` або `tailnet`, обов’язково використовуйте `gateway.auth.token` або `gateway.auth.password`. +- **Gateway працює на VPS** і зберігає стан + робочий простір. +- Ви підключаєтеся зі свого ноутбука або телефона через **Control UI** або **Tailscale/SSH**. +- Вважайте VPS джерелом істини та регулярно **створюйте резервні копії** стану + робочого простору. +- Безпечний варіант за замовчуванням: тримайте Gateway на loopback і отримуйте до нього доступ через SSH-тунель або Tailscale Serve. + Якщо ви прив’язуєте його до `lan` або `tailnet`, обов’язково використовуйте `gateway.auth.token` або `gateway.auth.password`. Пов’язані сторінки: [Віддалений доступ до Gateway](/uk/gateway/remote), [Центр платформ](/uk/platforms). ## Спільний агент компанії на VPS -Запуск одного агента для команди — це припустимий варіант, якщо всі користувачі перебувають у межах однакової моделі довіри, а агент використовується лише для бізнесу. +Запуск одного агента для команди — цілком прийнятний варіант, якщо всі користувачі перебувають в одній межі довіри, а агент використовується лише для бізнесу. -- Тримайте його в окремому середовищі виконання (VPS/VM/контейнер + окремий користувач ОС/облікові записи). +- Тримайте його в окремому середовищі виконання (VPS/VM/контейнер + окремий користувач або облікові записи ОС). - Не входьте в цьому середовищі до особистих облікових записів Apple/Google або особистих профілів браузера/менеджера паролів. -- Якщо користувачі є взаємно недовіреними, розділяйте за gateway/хостом/користувачем ОС. +- Якщо користувачі є потенційними противниками один для одного, розділяйте їх за gateway/хостом/користувачем ОС. -Деталі моделі безпеки: [Безпека](/uk/gateway/security). +Подробиці моделі безпеки: [Безпека](/uk/gateway/security). -## Використання Node із VPS +## Використання вузлів із VPS -Ви можете тримати Gateway у хмарі та під’єднувати **Node** на своїх локальних пристроях -(Mac/iOS/Android/headless). Node надають локальні можливості екрана/камери/canvas і `system.run`, -тоді як Gateway залишається у хмарі. +Ви можете тримати Gateway у хмарі та підключати **вузли** на своїх локальних пристроях +(Mac/iOS/Android/headless). Вузли надають локальні можливості screen/camera/canvas і `system.run`, +тоді як Gateway залишається в хмарі. -Документація: [Node](/uk/nodes), [CLI Node](/cli/nodes). +Документація: [Вузли](/uk/nodes), [CLI вузлів](/cli/nodes). ## Налаштування запуску для малих VM і ARM-хостів -Якщо команди CLI здаються повільними на малопотужних VM (або ARM-хостах), увімкніть кеш компіляції модулів Node: +Якщо команди CLI працюють повільно на малопотужних VM (або ARM-хостах), увімкніть кеш компіляції модулів Node: ```bash grep -q 'NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache' ~/.bashrc || cat >> ~/.bashrc <<'EOF' @@ -83,14 +83,14 @@ EOF source ~/.bashrc ``` -- `NODE_COMPILE_CACHE` пришвидшує повторний запуск команд. +- `NODE_COMPILE_CACHE` пришвидшує повторні запуски команд. - `OPENCLAW_NO_RESPAWN=1` усуває додаткові накладні витрати запуску через шлях самоперезапуску. -- Перший запуск команди прогріває кеш; наступні запуски швидші. -- Для особливостей Raspberry Pi дивіться [Raspberry Pi](/uk/install/raspberry-pi). +- Перший запуск команди прогріває кеш; наступні запуски працюють швидше. +- Докладніше саме для Raspberry Pi див. [Raspberry Pi](/uk/install/raspberry-pi). ### Контрольний список налаштування systemd (необов’язково) -Для VM-хостів, що використовують `systemd`, варто розглянути таке: +Для VM-хостів, які використовують `systemd`, розгляньте таке: - Додайте змінні середовища сервісу для стабільного шляху запуску: - `OPENCLAW_NO_RESPAWN=1` @@ -99,7 +99,7 @@ source ~/.bashrc - `Restart=always` - `RestartSec=2` - `TimeoutStartSec=90` -- Віддавайте перевагу дискам на SSD для шляхів стану/кешу, щоб зменшити штрафи холодного запуску через випадковий I/O. +- Віддавайте перевагу дискам на SSD для шляхів стану/кешу, щоб зменшити штрафи холодного старту через випадковий I/O. Для стандартного шляху `openclaw onboard --install-daemon` відредагуйте користувацький unit: @@ -116,8 +116,11 @@ RestartSec=2 TimeoutStartSec=90 ``` -Якщо натомість ви навмисно встановили системний unit, відредагуйте +Якщо ви навмисно встановили системний unit, натомість редагуйте `openclaw-gateway.service` через `sudo systemctl edit openclaw-gateway.service`. -Як політики `Restart=` допомагають автоматизованому відновленню: -[systemd може автоматизувати відновлення сервісу](https://www.redhat.com/en/blog/systemd-automate-recovery). +Як політики `Restart=` допомагають автоматичному відновленню: +[systemd може автоматизувати відновлення сервісів](https://www.redhat.com/en/blog/systemd-automate-recovery). + +Про поведінку OOM у Linux, вибір жертви серед дочірніх процесів і діагностику `exit 137` +див. [Тиск на пам’ять Linux і завершення через OOM](/uk/platforms/linux#memory-pressure-and-oom-kills).