diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 170f82da4..c7d897f43 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,136 +1,209 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресій для помилок моделей/провайдерів - - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' + - Додавання регресійних тестів для багів моделей/провайдерів + - Налагодження поведінки Gateway + агентів +summary: 'Набір для тестування: набори unit/e2e/live, ранери Docker і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-12T18:04:22Z" + generated_at: "2026-04-13T03:05:09Z" model: gpt-5.4 provider: openai - source_hash: a66ea672c386094ab4a8035a082c8a85d508a14301ad44b628d2a10d9cec3a52 + source_hash: 3db91b4bc36f626cd014958ec66b08b9cecd9faaa20a5746cd3a49ad4b0b1c38 source_path: help/testing.md workflow: 15 --- # Тестування -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір раннерів Docker. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює) -- Які команди запускати для типових робочих сценаріїв (локально, перед push, налагодження) +- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресії для реальних проблем із моделями/провайдерами +- Як додавати регресійні тести для реальних проблем моделей/провайдерів ## Швидкий старт У більшості випадків: -- Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm test` +- Повний набір перевірок (очікується перед push): `pnpm build && pnpm check && pnpm test` - Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` -- Безпосередній цикл спостереження Vitest: `pnpm test:watch` -- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Під час ітерацій над однією помилкою спочатку віддавайте перевагу цільовим запускам. +- Прямий цикл спостереження 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` +- QA-лінія на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` Коли ви змінюєте тести або хочете більше впевненості: -- Gate покриття: `pnpm test:coverage` +- Перевірка покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` -Під час налагодження реальних провайдерів/моделей (потрібні справжні облікові дані): +Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Набір live (моделі + probe інструментів/зображень Gateway): `pnpm test:live` -- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Live-набір (моделі + gateway-перевірки tool/image): `pnpm test:live` +- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Порада: коли вам потрібен лише один проблемний випадок, звужуйте live-тести через змінні середовища allowlist, описані нижче. +Порада: якщо вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. -## Ранери, специфічні для QA +## QA-специфічні раннери -Ці команди використовуються поряд з основними наборами тестів, коли вам потрібен реалізм QA-lab: +Ці команди розміщені поряд з основними наборами тестів, коли вам потрібен рівень реалістичності QA-lab: - `pnpm openclaw qa suite` - Запускає QA-сценарії з репозиторію безпосередньо на хості. - - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими працівниками Gateway, до 64 працівників або кількості вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати кількість працівників, або `--concurrency 1` для старішої послідовної черги. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими gateway-воркерами, до 64 воркерів або кількості вибраних сценаріїв. Використовуйте `--concurrency `, щоб налаштувати кількість воркерів, або `--concurrency 1` для старішої послідовної лінії. - `pnpm openclaw qa suite --runner multipass` - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Для live-запусків пересилає підтримувані вхідні дані автентифікації QA, практичні для guest-системи: ключі провайдера через env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest-система могла записувати назад через змонтовану робочу область. - - Записує звичайні QA-звіт і summary, а також журнали Multipass у `.artifacts/qa-e2e/...`. + - Live-запуски пересилають підтримувані QA-входи автентифікації, практичні для гостьової системи: ключі провайдерів через env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, якщо він є. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гість міг записувати назад через змонтований workspace. + - Записує звичайний QA-звіт + підсумок, а також логи Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. - `pnpm openclaw qa matrix` - - Запускає live-QA-чергу Matrix проти тимчасового homeserver Tuwunel на базі Docker. - - Готує трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA Gateway з реальним Plugin Matrix як транспортом SUT. - - За замовчуванням використовує закріплений стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. - - Записує QA-звіт Matrix, summary і артефакт observed-events у `.artifacts/qa-e2e/...`. + - Запускає live QA-лінію Matrix проти тимчасового homeserver Tuwunel на базі Docker. + - Ініціалізує трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway з реальним Plugin Matrix як транспортом SUT. + - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. + - Matrix наразі підтримує лише `--credential-source env`, оскільки ця лінія локально ініціалізує тимчасових користувачів. + - Записує QA-звіт Matrix, підсумок і артефакт observed-events у `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає live-QA-чергу Telegram проти реальної приватної групи, використовуючи токени bot для driver і SUT з env. - - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. - - Потребує двох різних bot в одній приватній групі, причому bot SUT має надавати Telegram username. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох bot і переконайтеся, що bot driver може спостерігати трафік bot у групі. - - Записує QA-звіт Telegram, summary і артефакт observed-messages у `.artifacts/qa-e2e/...`. + - Запускає live QA-лінію Telegram проти реальної приватної групи, використовуючи токени ботів driver і SUT з env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим ідентифікатором чату Telegram. + - Підтримує `--credential-source convex` для спільних пулів облікових даних. Типово використовуйте режим env або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути оренду зі спільного пулу. + - Потребує двох різних ботів у тій самій приватній групі, причому бот SUT має мати ім’я користувача Telegram. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. + - Записує QA-звіт Telegram, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. -Live-транспортні черги використовують один стандартний контракт, щоб нові транспорти не дрейфували: +Live transport lanes share one standard contract so new transports do not drift: -`qa-channel` лишається широким синтетичним QA-набором і не входить до матриці покриття live-транспорту. +`qa-channel` лишається широким синтетичним QA-набором і не входить до матриці покриття live transport. -| Черга | Canary | Обмеження за згадкою | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша взаємодія в треді | Ізоляція тредів | Спостереження за реакціями | Команда help | -| -------- | ------ | -------------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | --------------- | -------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Лінія | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша взаємодія в треді | Ізоляція тредів | Спостереження за реакціями | Команда help | +| -------- | ------ | -------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | --------------- | -------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | + +### Спільні облікові дані Telegram через Convex (v1) + +Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat для цієї оренди, поки лінія виконується, і звільняє оренду під час завершення. + +Еталонний каркас проєкту Convex: + +- `qa/convex-credential-broker/` + +Обов’язкові змінні середовища: + +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) +- Один секрет для вибраної ролі: + - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` + - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` +- Вибір ролі облікових даних: + - CLI: `--credential-role maintainer|ci` + - Типове значення через env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `maintainer`) + +Необов’язкові змінні середовища: + +- `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://`. + +Адміністраторські команди maintainer (додавання/видалення/список пулу) вимагають саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. + +CLI-хелпери для maintainer: + +```bash +pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json +pnpm openclaw qa credentials list --kind telegram +pnpm openclaw qa credentials remove --credential-id +``` + +Використовуйте `--json` для машиночитаного виводу у скриптах і CI-утилітах. + +Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): + +- `POST /acquire` + - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` + - Успіх: `{ status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }` + - Вичерпано/можна повторити: `{ status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }` +- `POST /heartbeat` + - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }` + - Успіх: `{ status: "ok" }` (або порожній `2xx`) +- `POST /release` + - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken }` + - Успіх: `{ status: "ok" }` (або порожній `2xx`) +- `POST /admin/add` (лише секрет maintainer) + - Запит: `{ kind, actorId, payload, note?, status? }` + - Успіх: `{ status: "ok", credential }` +- `POST /admin/remove` (лише секрет maintainer) + - Запит: `{ credentialId, actorId }` + - Успіх: `{ status: "ok", changed, credential }` + - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (лише секрет maintainer) + - Запит: `{ kind?, status?, includePayload?, limit? }` + - Успіх: `{ status: "ok", credentials, count }` + +Форма payload для типу Telegram: + +- `{ groupId: string, driverToken: string, sutToken: string }` +- `groupId` має бути рядком із числовим ідентифікатором чату Telegram. +- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректний payload. ### Додавання каналу до QA Додавання каналу до markdown-системи QA вимагає рівно двох речей: -1. Транспортного адаптера для каналу. +1. Адаптера транспорту для каналу. 2. Набору сценаріїв, який перевіряє контракт каналу. -Не додавайте канал-специфічний QA-ранер, якщо спільний ранер `qa-lab` може взяти цей потік на себе. +Не додавайте QA-раннер, специфічний для каналу, якщо спільний раннер `qa-lab` може взяти на себе цей потік. `qa-lab` відповідає за спільну механіку: - запуск і завершення набору -- паралельність працівників +- паралелізм воркерів - запис артефактів - генерацію звітів - виконання сценаріїв -- сумісні alias для старіших сценаріїв `qa-channel` +- аліаси сумісності для старіших сценаріїв `qa-channel` -Адаптер каналу відповідає за транспортний контракт: +Адаптер каналу відповідає за контракт транспорту: -- як Gateway налаштовується для цього транспорту +- як налаштовується gateway для цього транспорту - як перевіряється готовність - як інжектуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються транскрипти та нормалізований стан транспорту +- як надаються транскрипти й нормалізований стан транспорту - як виконуються дії на базі транспорту -- як обробляється транспорт-специфічне скидання або очищення +- як обробляється специфічне для транспорту скидання або очищення Мінімальний поріг впровадження для нового каналу: -1. Реалізуйте транспортний адаптер на спільному шві `qa-lab`. -2. Зареєструйте адаптер у реєстрі транспортів. -3. Тримайте транспорт-специфічну механіку всередині адаптера або harness каналу. -4. Створіть або адаптуйте markdown-сценарії в `qa/scenarios/`. -5. Для нових сценаріїв використовуйте узагальнені допоміжні функції сценаріїв. -6. Зберігайте працездатність наявних alias сумісності, якщо в репозиторії не виконується навмисна міграція. +1. Реалізувати адаптер транспорту на спільному шві `qa-lab`. +2. Зареєструвати адаптер у реєстрі транспортів. +3. Тримати специфічну для транспорту механіку всередині адаптера або harness каналу. +4. Написати або адаптувати markdown-сценарії в `qa/scenarios/`. +5. Використовувати generic-хелпери сценаріїв для нових сценаріїв. +6. Зберігати роботу наявних аліасів сумісності, якщо в репозиторії не виконується навмисна міграція. Правило ухвалення рішення суворе: - Якщо поведінку можна виразити один раз у `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного транспортного каналу, тримайте її в цьому адаптері або harness Plugin. -- Якщо сценарію потрібна нова можливість, яку може використати більше ніж один канал, додайте узагальнену допоміжну функцію замість канал-специфічної гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій транспорт-специфічним і явно відображайте це в контракті сценарію. +- Якщо поведінка залежить від транспорту одного каналу, тримайте її в цьому адаптері або harness Plugin. +- Якщо сценарію потрібна нова можливість, яку можуть використовувати більше ніж один канал, додайте generic-хелпер замість гілки, специфічної для каналу, в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту і чітко позначайте це в контракті сценарію. -Бажані назви узагальнених допоміжних функцій для нових сценаріїв: +Бажані назви generic-хелперів для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -145,7 +218,7 @@ Live-транспортні черги використовують один с - `formatTransportTranscript` - `resetTransport` -Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: +Аліаси сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -153,102 +226,101 @@ Alias сумісності залишаються доступними для н - `formatConversationTranscript` - `resetBus` -Нова робота з каналами має використовувати узагальнені назви допоміжних функцій. -Alias сумісності існують, щоб уникнути міграції в один день, а не як модель для -створення нових сценаріїв. +Нова робота з каналами має використовувати generic-хелпери. +Аліаси сумісності існують, щоб уникнути одночасної міграції всього, а не як модель для написання нових сценаріїв. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): +Думайте про набори як про «зростання реалістичності» (і зростання нестабільності/вартості): -### Unit / integration (типовий варіант) +### Unit / integration (типовий) - Команда: `pnpm test` -- Конфігурація: десять послідовних запусків shard (`vitest.full-*.config.ts`) поверх наявних scoped-проєктів Vitest -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted node-тести `ui`, охоплені `vitest.unit.config.ts` -- Охоплення: +- Конфігурація: десять послідовних запусків шардів (`vitest.full-*.config.ts`) поверх наявних scoped-проєктів Vitest +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, охоплені `vitest.unit.config.ts` +- Область: - Чисті unit-тести - - In-process інтеграційні тести (автентифікація gateway, маршрутизація, tooling, парсинг, конфігурація) + - In-process integration-тести (автентифікація gateway, маршрутизація, інструменти, парсинг, конфігурація) - Детерміновані регресії для відомих багів - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним -- Примітка про проєкти: - - `pnpm test` без точного таргетингу тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project процесу. Це зменшує піковий RSS на завантажених машинах і не дає роботі `auto-reply`/extension виснажувати не пов’язані набори. - - `pnpm test --watch` усе ще використовує native root-граф проєктів `vitest.config.ts`, оскільки цикл спостереження з кількома shard непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні таргети файлів/каталогів через scoped-черги, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped-черги, якщо diff торкається лише routable-файлів коду/тестів; зміни конфігурації/налаштування все ще повертаються до широкого повторного запуску root-project. - - Легкі за імпортами unit-тести з agents, commands, plugins, допоміжних модулів `auto-reply`, `plugin-sdk` і подібних чистих утилітних ділянок маршрутизуються через чергу `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли лишаються на наявних чергах. - - Вибрані допоміжні вихідні файли `plugin-sdk` і `commands` також зіставляють запуски в режимі changed з явними sibling-тестами в цих легких чергах, тому редагування helper уникають повторного запуску повного важкого набору для цього каталогу. - - `auto-reply` тепер має три окремі кошики: допоміжні модулі верхнього рівня core, інтеграційні тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це тримає найважчу роботу harness для reply подалі від дешевших тестів status/chunk/token. -- Примітка про embedded runner: - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст Compaction, +- Примітка щодо проєктів: + - Ненацілений `pnpm test` тепер запускає одинадцять менших конфігурацій шардів (`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`, оскільки цикл спостереження з кількома шардами непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped-лінії, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` розгортає змінені шляхи git у ті самі scoped-лінії, коли diff зачіпає лише маршрутизовані файли source/test; зміни config/setup, як і раніше, повертаються до широкого повторного запуску root project. + - Import-light unit-тести з agents, commands, plugins, helper-ів `auto-reply`, `plugin-sdk` та подібних чистих utility-областей маршрутизуються через лінію `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли лишаються на наявних лініях. + - Деякі helper source-файли `plugin-sdk` і `commands` також зіставляють запуски changed-mode з явними sibling-тестами в цих легких лініях, тому редагування helper-ів не змушує повторно запускати весь важкий набір для цього каталогу. + - `auto-reply` тепер має три окремі бакети: top-level core helper-и, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це тримає найважчу роботу harness reply подалі від дешевих тестів status/chunk/token. +- Примітка щодо embedded runner: + - Коли ви змінюєте входи discovery message-tool або runtime-контекст Compaction, зберігайте обидва рівні покриття. - - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації/нормалізації. - - Також підтримуйте в здоровому стані інтеграційні набори embedded runner: + - Додавайте сфокусовані helper-регресії для чистих меж routing/normalization. + - Також підтримуйте в доброму стані integration-набори embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - Ці набори перевіряють, що scoped id і поведінка Compaction усе ще проходять - через реальні шляхи `run.ts` / `compact.ts`; helper-only тести не є - достатньою заміною цих інтеграційних шляхів. -- Примітка про pool: - - Базова конфігурація Vitest тепер за замовчуванням використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root-проєктах, e2e і live-конфігураціях. - - Root-черга UI зберігає своє налаштування `jsdom` та optimizer, але тепер також працює на спільному non-isolated runner. + через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є + достатньою заміною для цих integration-шляхів. +- Примітка щодо pool: + - Базова конфігурація Vitest тепер типово використовує `threads`. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e і live-конфігураціях. + - Коренева лінія UI зберігає свій `jsdom` setup і optimizer, але тепер теж працює на спільному non-isolated runner. - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. -- Примітка про швидку локальну ітерацію: - - `pnpm test:changed` маршрутизує через scoped-черги, коли змінені шляхи чисто відображаються на менший набір. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею кількості працівників. - - Автомасштабування локальних працівників тепер навмисно консервативніше і також зменшує навантаження, коли середнє навантаження хоста вже високе, тому кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базова конфігурація Vitest позначає проєкти/файли конфігурації як `forceRerunTriggers`, щоб повторні запуски в режимі changed лишалися коректними, коли змінюється зв’язування тестів. - - Конфігурація зберігає `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 шляхом для цього зафіксованого diff і виводить wall time та macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного dirty tree, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує CPU-профіль main-thread для витрат Vitest/Vite на startup і transform. - - `pnpm test:perf:profile:runner` записує CPU+heap профілі runner для unit-набору з вимкненим паралелізмом файлів. + - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. +- Примітка щодо швидкої локальної ітерації: + - `pnpm test:changed` маршрутизує через scoped-лінії, коли змінені шляхи чисто зіставляються з меншим набором. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом воркерів. + - Автомасштабування локальних воркерів тепер навмисно консервативне й також зменшується, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски changed-mode лишалися коректними, коли змінюється тестова обв’язка. + - Конфігурація тримає `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 для цього зафіксованого diff і виводить wall time плюс macOS max RSS. +- `pnpm test:perf:changed:bench -- --worktree` виконує бенчмарк поточного dirty tree, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує CPU-профіль main-thread для витрат запуску й transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує CPU+heap-профілі runner-а для unit-набору з вимкненим паралелізмом файлів. -### E2E (smoke Gateway) +### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Типові параметри runtime: - - Використовує Vitest `threads` з `isolate: false`, узгоджено з рештою репозиторію. - - Використовує адаптивну кількість працівників (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням запускається в silent-режимі, щоб зменшити накладні витрати на консольний I/O. +- Типові значення runtime: + - Використовує `threads` Vitest з `isolate: false`, узгоджено з рештою репозиторію. + - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням працює в silent mode, щоб зменшити накладні витрати на I/O консолі. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово встановити кількість працівників (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний консольний вивід. -- Охоплення: - - End-to-end поведінка Gateway з кількома інстансами - - Поверхні WebSocket/HTTP, парування Node і важча мережева взаємодія + - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість воркерів (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у консоль. +- Область: + - End-to-end-поведінка gateway з кількома інстансами + - Поверхні WebSocket/HTTP, pairинг вузлів і важча мережева взаємодія - Очікування: - - Запускається в CI (коли увімкнено в pipeline) + - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Має більше рухомих частин, ніж unit-тести (може бути повільніше) + - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: smoke backend OpenShell +### E2E: backend smoke OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` -- Охоплення: - - Запускає ізольований Gateway OpenShell на хості через Docker +- Область: + - Запускає ізольований gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical поведінку файлової системи через міст fs sandbox + - Перевіряє поведінку файлової системи remote-canonical через bridge fs sandbox - Очікування: - - Лише за явним увімкненням; не входить до типового запуску `pnpm test:e2e` - - Потребує локальний CLI `openshell` і працездатний Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий Gateway і sandbox + - Лише за бажанням; не входить до типового запуску `pnpm test:e2e` + - Потребує локального CLI `openshell` і справного демона Docker + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний бінарний файл CLI або wrapper-скрипт + - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний двійковий файл CLI або wrapper-скрипт ### Live (реальні провайдери + реальні моделі) @@ -256,114 +328,114 @@ Alias сумісності існують, щоб уникнути міграц - Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) -- Охоплення: - - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей tool calling, проблем автентифікації та поведінки rate limit +- Область: + - «Чи працює цей провайдер/модель _сьогодні_ з реальними обліковими даними?» + - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки при rate limit - Очікування: - - За задумом нестабільний для CI (реальні мережі, реальні політики провайдера, квоти, збої) - - Коштує грошей / використовує rate limit + - За задумом нестабільні для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштують грошей / витрачають rate limit - Краще запускати звужені підмножини, а не «все» -- 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. +- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють config/auth-матеріали в тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер типово працює в тихішому режимі: зберігає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає логи bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. +- Ротація API-ключів (залежно від провайдера): задавайте `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. - Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, тому довгі виклики провайдера явно видно як активні, навіть коли перехоплення консолі Vitest працює тихо. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/Gateway передавалися негайно під час live-запусків. + - Live-набори тепер виводять рядки прогресу в stderr, тож тривалі виклики провайдерів помітно активні, навіть коли перехоплення консолі Vitest працює тихо. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/gateway одразу транслювалися під час live-запусків. - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat для Gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Користуйтеся цією таблицею рішень: +Скористайтеся цією таблицею рішень: -- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Торкаєтеся мережевої взаємодії Gateway / протоколу WS / парування: додайте `pnpm test:e2e` -- Налагоджуєте «мій bot не працює» / специфічні для провайдера збої / tool calling: запускайте звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змін було багато) +- Зачіпаєте мережеву взаємодію gateway / протокол WS / pairинг: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / виклик інструментів: запускайте звужений `pnpm test:live` ## Live: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку наразі оголошує** підключений Android Node, і перевірити поведінку контракту команди. -- Охоплення: - - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не парує застосунок). - - Валідація Gateway `node.invoke` команда за командою для вибраного Android Node. -- Обов’язкова попередня підготовка: - - Android-застосунок уже підключено та спарено з Gateway. - - Застосунок лишається на передньому плані. - - Дозволи/згода на захоплення надані для можливостей, які ви очікуєте успішно пройти. +- Мета: викликати **кожну команду, яку зараз рекламує** підключений Android Node, і перевірити поведінку контракту команди. +- Область: + - Підготовлений/ручний setup (набір не встановлює/не запускає/не pair-ить застосунок). + - Перевірка `node.invoke` gateway для вибраного Android Node команда за командою. +- Обов’язкове попереднє налаштування: + - Android-застосунок уже підключений і спарений із gateway. + - Застосунок утримується на передньому плані. + - Для можливостей, які ви очікуєте як успішні, надано дозволи/згоду на захоплення. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Повні відомості з налаштування Android: [Android App](/uk/platforms/android) +- Повні деталі setup Android: [Android App](/uk/platforms/android) ## Live: smoke моделей (ключі профілів) Live-тести поділено на два шари, щоб можна було ізолювати збої: -- «Direct model» показує, чи може провайдер/модель взагалі відповісти з наданим ключем. +- «Direct model» показує, чи взагалі може відповісти провайдер/модель із заданим ключем. - «Gateway smoke» показує, чи працює для цієї моделі повний конвеєр gateway+agent (сесії, історія, інструменти, політика sandbox тощо). -### Шар 1: Direct model completion (без Gateway) +### Шар 1: Direct model completion (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Виконати невелике completion для кожної моделі (і цільові регресії там, де потрібно) + - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані + - Виконати невелике completion для кожної моделі (і цільові регресії, де потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest безпосередньо) -- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб справді запустити цей набір; інакше він пропускається, щоб `pnpm test:live` залишався зосередженим на Gateway smoke + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для 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=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Modern/all-прогони за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern-прогону або додатне число для меншого обмеження. + - Розгортки modern/all за замовчуванням використовують curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого ліміту. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: сховище профілів і резервні env-джерела - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** + - Типово: profile store і резервні значення з env + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр агента Gateway зламаний» - - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) + - Відокремлює «API провайдера зламане / ключ недійсний» від «зламано конвеєр gateway agent» + - Містить невеликі ізольовані регресії (приклад: reasoning replay OpenAI Responses/Codex Responses + потоки tool-call) -### Шар 2: smoke Gateway + dev agent (що насправді робить "@openclaw") +### Шар 2: Gateway + smoke dev agent (що реально робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Підняти in-process Gateway + - Підняти in-process gateway - Створити/оновити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) - - Ітерувати моделі з ключами і перевіряти: + - Ітеруватися по моделях-із-ключами й перевіряти: - «змістовну» відповідь (без інструментів) - - що реальний виклик інструмента працює (probe `read`) - - необов’язкові додаткові probe інструментів (probe `exec+read`) + - що реальний виклик інструмента працює (`read` probe) + - необов’язкові додаткові перевірки інструментів (`exec+read` probe) - що регресійні шляхи OpenAI (лише tool-call → подальший крок) продовжують працювати -- Деталі probe (щоб ви могли швидко пояснювати збої): - - probe `read`: тест записує nonce-файл у workspace і просить агента `read` прочитати його та повернути nonce. +- Деталі probe (щоб можна було швидко пояснити збої): + - probe `read`: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. - probe `exec+read`: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. - - probe зображення: тест додає згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. - - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. + - image probe: тест прикріплює згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. + - Еталон реалізації: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest безпосередньо) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибирати моделі: - - Типово: modern-allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це alias для modern-allowlist - - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір - - Modern/all-прогони Gateway за замовчуванням мають curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern-прогону або додатне число для меншого обмеження. -- Як вибирати провайдерів (уникаючи «усе OpenRouter»): + - Типово: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це псевдонім для modern allowlist + - Або задайте `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір + - Modern/all gateway sweeps типово використовують curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого ліміту. +- Як вибирати провайдерів (уникати «всього OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Probe інструментів і зображень у цьому live-тесті завжди увімкнені: +- Probe інструментів + зображень у цьому live-тесті завжди ввімкнені: - probe `read` + probe `exec+read` (навантаження на інструменти) - - probe зображення запускається, коли модель оголошує підтримку вхідних зображень + - image probe запускається, коли модель оголошує підтримку вхідних зображень - Потік (на високому рівні): - - Тест генерує крихітний PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) + - Тест генерує маленький PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway парсить вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Embedded agent передає моделі мультимодальне повідомлення користувача - - Перевірка: відповідь містить `cat` + код (толерантність OCR: незначні помилки допустимі) + - Gateway розбирає вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Embedded agent пересилає мультимодальне повідомлення користувача до моделі + - Перевірка: відповідь містить `cat` + код (OCR-tolerance: незначні помилки допустимі) Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: @@ -375,23 +447,23 @@ openclaw models list --json ## Live: smoke backend CLI (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent, використовуючи локальний backend CLI, не торкаючись вашої типової конфігурації. -- Типові параметри smoke для конкретного backend зберігаються у визначенні `cli-backend.ts` extension-власника. +- Мета: перевірити конвеєр Gateway + agent із використанням локального backend CLI, не торкаючись вашої типової конфігурації. +- Типові значення smoke, специфічні для backend, розміщені у визначенні `cli-backend.ts` extension-власника. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускати Vitest безпосередньо) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих Plugin CLI-backend-власника. + - Поведінка command/args/image походить із метаданих Plugin backend CLI-власника. - Перевизначення (необов’язкові): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальне вкладення-зображення (шляхи інжектуються в prompt) - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до файлів зображень як аргументи CLI замість інжекції в prompt - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) щоб керувати передаванням аргументів зображень, коли встановлено `IMAGE_ARG` - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий хід і перевірити потік resume - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` щоб вимкнути типову перевірку безперервності тієї самої сесії Claude Sonnet -> Opus (встановіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне вкладення-зображення (шляхи інжектуються в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість інжекції в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати способом передавання аргументів зображень, коли задано `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити flow відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типовий probe безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути його, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -418,20 +490,20 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker-ранер розташовано в `scripts/test-live-cli-backend-docker.sh`. -- Він запускає smoke CLI-backend live всередині Docker-образу репозиторію як непривілейований користувач `node`. -- Він визначає метадані smoke CLI із Plugin-власника, а потім встановлює відповідний пакет Linux CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований доступний для запису префікс за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносної OAuth-підписки Claude Code через або `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить прямий запуск `claude -p` у Docker, а потім виконує два ходи Gateway CLI-backend без збереження env-змінних API-ключа Anthropic. Ця черга підписки за замовчуванням вимикає probe Claude MCP/tool і image, оскільки Claude наразі маршрутизує використання сторонніх застосунків через додаткову оплату usage замість звичайних лімітів плану підписки. -- Smoke live CLI-backend тепер перевіряє той самий end-to-end потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик інструмента MCP `cron`, перевірений через Gateway CLI. -- Типовий smoke Claude також оновлює сесію із Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Docker-раннер розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke backend CLI всередині Docker-образу репозиторію як непривілейований користувач `node`. +- Він визначає метадані smoke CLI з extension-власника, а потім встановлює відповідний Linux-пакет CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає portable OAuth підписки Claude Code через `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім виконує два ходи Gateway CLI-backend без збереження env-змінних ключа Anthropic API. Ця subscription-лінія типово вимикає Claude MCP/tool і image probes, оскільки Claude наразі маршрутизує використання сторонніх застосунків через білінг extra-usage замість звичайних лімітів плану підписки. +- Live smoke backend CLI тепер перевіряє той самий наскрізний flow для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик інструмента MCP `cron`, перевірений через Gateway CLI. +- Типовий smoke Claude також оновлює сесію з Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. -## Live: smoke ACP bind (`/acp spawn ... --bind here`) +## Live: smoke прив’язки ACP (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік conversation-bind ACP із live ACP-агентом: +- Мета: перевірити реальний flow conversation-bind ACP із live ACP-агентом: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну conversation каналу повідомлень на місці - - надіслати звичайне подальше повідомлення в тій самій conversation + - прив’язати synthetic conversation каналу повідомлень на місці + - надіслати звичайне подальше повідомлення в цій самій conversation - перевірити, що подальше повідомлення потрапляє в transcript прив’язаної сесії ACP - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` @@ -439,8 +511,8 @@ pnpm test:docker:live-cli-backend:gemini - Типові значення: - ACP-агенти в Docker: `claude,codex,gemini` - ACP-агент для прямого `pnpm test:live ...`: `claude` - - Синтетичний канал: контекст conversation у стилі Slack DM - - ACP-backend: `acpx` + - Synthetic channel: контекст conversation у стилі Slack DM + - Backend ACP: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -448,8 +520,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude,codex,gemini` - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - Примітки: - - Ця черга використовує поверхню Gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли приєднати контекст каналу повідомлень без удавання зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів Plugin `acpx` для вибраного ACP harness agent. + - Ця лінія використовує поверхню gateway `chat.send` з synthetic-полями originating-route лише для адміністратора, щоб тести могли додавати контекст message-channel без імітації зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів Plugin `acpx` для вибраного ACP harness-агента. Приклад: @@ -475,31 +547,31 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker-ранер розташовано в `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. +- Docker-раннер розташований у `scripts/test-live-acp-bind-docker.sh`. +- Типово він послідовно запускає smoke прив’язки ACP для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він підтягує `~/.profile`, переносить відповідний автентифікаційний матеріал CLI в контейнер, встановлює `acpx` у доступний для запису npm-префікс, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. -- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера з підключеного профілю доступними для дочірнього harness CLI. +- Він використовує `~/.profile`, підготовлює відповідні auth-матеріали CLI в контейнері, встановлює `acpx` у записуваний npm-префікс, а потім встановлює запитаний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. +- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера із sourced profile доступними для дочірнього harness CLI. ## Live: smoke harness app-server Codex -- Мета: перевірити Plugin-власний harness Codex через звичайний метод Gateway - `agent`: - - завантажити bundled Plugin `codex` +- Мета: перевірити harness Codex, що належить Plugin, через звичайний метод + gateway `agent`: + - завантажити вбудований Plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший хід Gateway agent до `codex/gpt-5.4` - - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що потік + - надіслати перший хід gateway agent до `codex/gpt-5.4` + - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що thread app-server може відновитися - запустити `/codex status` і `/codex models` через той самий шлях - команд Gateway + команди gateway - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `codex/gpt-5.4` -- Необов’язковий probe зображення: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Необов’язковий probe MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний - harness Codex не міг пройти перевірку через тихий fallback на PI. -- Автентифікація: `OPENAI_API_KEY` із shell/profile, а також необов’язково скопійовані +- Необов’язковий image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язковий MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex + не міг пройти тест, тихо переключившись на запасний PI. +- Auth: `OPENAI_API_KEY` із shell/profile, а також за потреби скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -522,28 +594,28 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker-ранер розташовано в `scripts/test-live-codex-harness-docker.sh`. -- Він підтягує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації CLI Codex, якщо вони є, встановлює `@openai/codex` у доступний для запису змонтований npm - префікс, готує дерево вихідного коду, а потім запускає лише live-тест harness Codex. -- Docker за замовчуванням вмикає probe зображення та MCP/tool. Встановіть +- Docker-раннер розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + auth Codex CLI, якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm + префікс, підготовлює дерево вихідного коду, а потім запускає лише live-тест Codex-harness. +- Docker типово вмикає image і MCP/tool probes. Установіть `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, коли потрібен вужчий налагоджувальний запуск. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, узгоджено з live - конфігурацією тесту, щоб fallback `openai-codex/*` або PI не міг приховати регресію - harness Codex. + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, коли потрібен вужчий запуск для налагодження. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, узгоджено з live- + конфігурацією тесту, щоб запасний перехід на `openai-codex/*` або PI не міг приховати + регресію harness Codex. ### Рекомендовані live-рецепти -Вузькі явні allowlist є найшвидшими й найменш нестабільними: +Вузькі, явні allowlist — найшвидші та найменш нестабільні: -- Одна модель, direct (без Gateway): +- Одна модель, direct (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Одна модель, smoke Gateway: +- Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling через кількох провайдерів: +- Виклик інструментів для кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Фокус на Google (API-ключ Gemini + Antigravity): @@ -553,19 +625,19 @@ pnpm test:docker:live-codex-harness Примітки: - `google/...` використовує Gemini API (API-ключ). -- `google-antigravity/...` використовує міст OAuth Antigravity (кінцева точка агента в стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості tooling). +- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint агента у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає хостований Gemini API від Google через HTTP (автентифікація API-ключем / профілем); саме це більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw виконує shell-виклик локального бінарного файла `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/підтримка інструментів/version skew). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (автентифікація через API-ключ / профіль); це те, що більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує shell-виклик локального двійкового файла `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/підтримка інструментів/version skew). -## Live: матриця моделей (що ми охоплюємо) +## Live: матриця моделей (що ми покриваємо) -Немає фіксованого «списку моделей CI» (live запускається лише за явним увімкненням), але це **рекомендовані** моделі для регулярного покриття на dev-машині з ключами. +Немає фіксованого «списку моделей CI» (live — опціональний), але це **рекомендовані** моделі, які варто регулярно покривати на dev-машині з ключами. -### Modern smoke-набір (tool calling + image) +### Сучасний smoke-набір (виклик інструментів + зображення) -Це запуск «поширених моделей», який ми очікуємо підтримувати в робочому стані: +Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: - OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` @@ -575,12 +647,12 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запускати Gateway smoke з інструментами + image: +Запуск gateway smoke з інструментами + зображенням: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: tool calling (Read + необов’язковий Exec) +### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) -Вибирайте щонайменше одну модель на сімейство провайдерів: +Виберіть принаймні одну модель на сімейство провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -591,73 +663,73 @@ pnpm test:docker:live-codex-harness Необов’язкове додаткове покриття (бажано мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яка у вас увімкнена) -- Cerebras: `cerebras/`… (якщо маєте доступ) -- LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас увімкнено) +- Cerebras: `cerebras/`… (якщо у вас є доступ) +- LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) -### Vision: надсилання image (вкладення → мультимодальне повідомлення) +### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте принаймні одну модель із підтримкою image в `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/OpenAI-варіанти з підтримкою vision тощо), щоб перевірити probe зображень. +Додайте принаймні одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб перевірити image probe. -### Агрегатори / альтернативні Gateway +### Агрегатори / альтернативні gateway Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою `tool`+`image`) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): +Інші провайдери, які можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (кастомні кінцеві точки): `minimax` (cloud/API), а також будь-який сумісний із OpenAI/Anthropic proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (custom endpoints): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний проксі (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко зашити в документацію «усі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс доступні ключі. +Порада: не намагайтеся жорстко закодувати в документації «усі моделі». Авторитетний список — це все, що `discoverModels(...)` повертає на вашій машині + усі доступні ключі. ## Облікові дані (ніколи не комітьте) -Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: +Live-тести виявляють облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знайти ті самі ключі. +- Якщо CLI працює, live-тести мають знаходити ті самі ключі. - Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілю» в live-тестах) +- Профілі автентифікації для кожного агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означають «profile keys» у live-тестах) - Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється у staged live home, якщо існує, але це не основне сховище ключів профілю) -- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI в тимчасовий test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probe не працювали у вашому реальному workspace хоста. +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється у staged live home, якщо присутній, але це не основне сховище profile keys) +- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI у тимчасовий test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не працювали у вашому реальному хостовому workspace. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть змонтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-раннери нижче (вони можуть змонтувати `~/.profile` у контейнер). -## Live Deepgram (транскрипція аудіо) +## Live: Deepgram (транскрибування аудіо) - Тест: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## Live BytePlus coding plan +## Live: план кодування BytePlus - Тест: `src/agents/byteplus.live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live мультимедійних workflow ComfyUI +## Live: медіа workflow ComfyUI - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` -- Охоплення: - - Перевіряє вбудовані шляхи comfy для image, video і `music_generate` +- Область: + - Перевіряє вбудовані шляхи comfy для зображень, відео і `music_generate` - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - - Корисно після змін подання workflow comfy, polling, завантажень або реєстрації Plugin + - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації Plugin -## 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 провайдера генерації зображень - - Завантажує відсутні env-змінні провайдерів із вашого shell входу (`~/.profile`) перед probe - - За замовчуванням надає перевагу live/env API-ключам над збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Завантажує відсутні env-змінні провайдерів із вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Проганяє стандартні варіанти генерації зображень через спільну runtime-можливість: + - Запускає стандартні варіанти генерації зображень через спільну runtime-можливість: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` @@ -670,199 +742,199 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію profile store і ігнорувати перевизначення лише через env -## Live генерації музики +## Live: генерація музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` -- Охоплення: - - Перевіряє спільний шлях вбудованих провайдерів генерації музики +- Область: + - Перевіряє спільний шлях вбудованого провайдера генерації музики - Наразі охоплює Google і MiniMax - - Завантажує env-змінні провайдерів із вашого shell входу (`~/.profile`) перед probe - - За замовчуванням надає перевагу live/env API-ключам над збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Завантажує env-змінні провайдерів із вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - Пропускає провайдерів без придатної автентифікації/профілю/моделі - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` з вхідними даними лише у вигляді prompt + - `generate` із вхідними даними лише у вигляді prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільної черги: + - Поточне покриття спільної лінії: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, а не цей спільний прогін + - `comfy`: окремий live-файл Comfy, а не ця спільна розгортка - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію profile store і ігнорувати перевизначення лише через env -## Live генерації відео +## Live: генерація відео - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` -- Охоплення: - - Перевіряє спільний шлях вбудованих провайдерів генерації відео - - Завантажує env-змінні провайдерів із вашого shell входу (`~/.profile`) перед probe - - За замовчуванням надає перевагу live/env API-ключам над збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell +- Область: + - Перевіряє спільний шлях вбудованого провайдера генерації відео + - Завантажує env-змінні провайдерів із вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API-ключі раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - Пропускає провайдерів без придатної автентифікації/профілю/моделі - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` з вхідними даними лише у вигляді prompt - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель у спільному прогоні приймає локальні вхідні image на основі buffer - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель у спільному прогоні приймає локальні вхідні video на основі buffer - - Поточні провайдери `imageToVideo`, оголошені, але пропущені в спільному прогоні: - - `vydra`, оскільки вбудований `veo3` є лише текстовим, а вбудований `kling` вимагає віддалений image URL + - `generate` із вхідними даними лише у вигляді prompt + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальне введення зображення на основі buffer у спільній розгортці + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальне введення відео на основі buffer у спільній розгортці + - Поточні провайдери `imageToVideo`, оголошені, але пропущені у спільній розгортці: + - `vydra`, оскільки вбудований `veo3` є лише текстовим, а вбудований `kling` вимагає віддалений URL зображення - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс чергу `kling`, яка за замовчуванням використовує фікстуру віддаленого image URL + - цей файл запускає `veo3` text-to-video плюс лінію `kling`, яка типово використовує фікстуру з віддаленим URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні провайдери `videoToVideo`, оголошені, але пропущені в спільному прогоні: - - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі вимагають віддалені еталонні URL `http(s)` / MP4 - - `google`, оскільки поточна спільна черга Gemini/Veo використовує локальні вхідні дані на основі buffer, а цей шлях не приймається у спільному прогоні - - `openai`, оскільки поточна спільна черга не гарантує організаційно-специфічний доступ до video inpaint/remix + - Поточні провайдери `videoToVideo`, оголошені, але пропущені у спільній розгортці: + - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі вимагають віддалені reference URL `http(s)` / MP4 + - `google`, оскільки поточна спільна лінія Gemini/Veo використовує локальне введення на основі buffer, а цей шлях не приймається у спільній розгортці + - `openai`, оскільки поточна спільна лінія не гарантує доступ до org-specific 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_REQUIRE_PROFILE_KEYS=1` щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію profile store і ігнорувати перевизначення лише через env -## Harness для media live +## Harness live для медіа - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори для image, music і video через один native entrypoint репозиторію + - Запускає спільні live-набори для зображень, музики й відео через один рідний для репозиторію entrypoint - Автоматично завантажує відсутні env-змінні провайдерів із `~/.profile` - - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і quiet-mode залишається узгодженою + - За замовчуванням автоматично звужує кожен набір до провайдерів, які зараз мають придатну автентифікацію + - Повторно використовує `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-раннери (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві категорії: +Ці Docker-раннери поділяються на дві категорії: -- Docker-ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний profile-key live-файл усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та workspace (і підтягують `~/.profile`, якщо він змонтований). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker-ранери live за замовчуванням використовують менший smoke-ліміт, щоб повний Docker-прогін залишався практичним: - `test:docker:live-models` за замовчуванням має `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Раннери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм profile-key live-файл усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (та використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker-раннери live типово використовують менший 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-змінні, коли - вам явно потрібне більше вичерпне сканування. -- `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:plugins` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + вам навмисно потрібне більше, вичерпне сканування. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ліній live. +- Раннери container smoke: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-ранери live-моделей також bind-mount лише потрібні домівки автентифікації CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у сховищі автентифікації хоста: +Docker-раннери live-моделей також bind-mount-ять лише потрібні домівки автентифікації CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішніх CLI міг оновлювати токени без змін у host auth store: - Direct models: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Smoke ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- Smoke прив’язки ACP: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) - Smoke backend CLI: `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`) - Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повне scaffold-налаштування): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Мережа Gateway (два контейнери, автентифікація WS + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Міст каналу MCP (підготовлений Gateway + міст stdio + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (smoke інсталяції + alias `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Wizard 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 (ініціалізований Gateway + міст stdio + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (smoke встановлення + аліас `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Docker-ранери live-моделей також bind-mount поточний checkout у режимі лише для читання і -переносять його в тимчасовий workdir усередині контейнера. Це зберігає runtime-образ -компактним і водночас дає змогу запускати Vitest на вашому точному локальному вихідному коді/конфігурації. -Під час перенесення пропускаються великі локальні кеші та результати збірки застосунків, як-от +Docker-раннери live-моделей також bind-mount-ять поточний checkout лише для читання і +підготовлюють його в тимчасовий workdir усередині контейнера. Це зберігає runtime- +образ компактним, але все одно дозволяє запускати Vitest точно по вашому локальному source/config. +Крок підготовки пропускає великі локальні кеші й результати збірки застосунків, такі як `.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або -виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -машинно-специфічних артефактів. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали -реальні працівники каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття Gateway -live з цієї Docker-черги. -`test:docker:openwebui` — це smoke перевірка сумісності вищого рівня: вона запускає -контейнер Gateway OpenClaw з увімкненими HTTP endpoint, сумісними з OpenAI, -запускає pinned-контейнер Open WebUI проти цього Gateway, входить через +виводу Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання +машиноспецифічних артефактів. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe gateway не запускали +реальні воркери каналів Telegram/Discord тощо всередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити покриття gateway +live з цієї Docker-лінії. +`test:docker:openwebui` — це compatibility smoke вищого рівня: він запускає +контейнер Gateway OpenClaw з увімкненими HTTP-endpoint-ами, сумісними з OpenAI, +запускає прив’язаний контейнер Open WebUI проти цього gateway, входить через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний запит чату через proxy `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися завантажити -образ Open WebUI, а самому Open WebUI — завершити власне cold-start налаштування. -Ця черга очікує наявний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) — основний спосіб надати його в Docker-ізольованих запусках. -Успішні запуски виводять невелике JSON-повідомлення на кшталт `{ "ok": true, "model": +реальний chat-запит через проксі Open WebUI `/api/chat/completions`. +Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження +образу Open WebUI, а Open WebUI — завершення власного cold-start setup. +Ця лінія очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) є основним способом надати його в Docker-запусках. +Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає підготовлений контейнер Gateway, -стартує другий контейнер, який запускає `openclaw mcp serve`, а потім -перевіряє маршрутизоване виявлення conversation, читання transcript, метадані вкладень, -поведінку черги live events, маршрутизацію outbound send і сповіщення про канал + -дозволи в стилі Claude через реальний міст stdio MCP. Перевірка сповіщень -безпосередньо аналізує raw-кадри stdio MCP, тож smoke перевіряє те, що -міст реально видає, а не лише те, що випадково показує конкретний SDK клієнта. +реального облікового запису Telegram, Discord чи iMessage. Він піднімає ініціалізований контейнер Gateway, +запускає другий контейнер, який стартує `openclaw mcp serve`, а потім +перевіряє виявлення conversation через маршрутизацію, читання transcript, метадані вкладень, +поведінку черги live-подій, маршрутизацію outbound send і сповіщення у стилі Claude про канал + +дозволи через реальний міст stdio MCP. Перевірка сповіщень +напряму аналізує raw stdio MCP frames, тож smoke перевіряє те, що +міст справді випромінює, а не лише те, що випадково показує конкретний SDK клієнта. Ручний smoke plain-language thread ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для потоків регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. +- Залишайте цей скрипт для workflow регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації тредів 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_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих інсталяцій CLI всередині Docker -- Зовнішні каталоги/файли автентифікації CLI під `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI всередині Docker +- Зовнішні каталоги/файли автентифікації CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Для звужених запусків провайдерів монтуються лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, як-от `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` для звуження запуску -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` для фільтрації провайдерів у контейнері -- `OPENCLAW_SKIP_DOCKER_BUILD=1` щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` щоб гарантувати, що облікові дані беруться зі сховища профілів (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...` щоб вибрати модель, яку Gateway показує для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...` щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...` щоб перевизначити pinned-тег образу Open WebUI + - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна нова збірка +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться з profile store (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити зафіксований тег образу Open WebUI -## Перевірка коректності документації +## Перевірка документації Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку якірних посилань Mintlify, коли також потрібна перевірка заголовків на сторінці: `pnpm docs:check-links:anchors`. +Запускайте повну перевірку якорів Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для 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`, запис конфігурації + примусова автентифікація): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик інструментів Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Wizard Gateway (WS `wizard.start`/`wizard.next`, запис config + примусова auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") ## Оцінювання надійності агентів (Skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»: -- Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють зв’язування сесій і ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Mock-виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- Наскрізні потоки wizard, які перевіряють wiring сесій і ефекти конфігурації (`src/gateway/gateway.test.ts`). Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Вибір рішення:** коли Skills перелічені в prompt, чи вибирає агент правильний Skill (або уникає неважливих)? -- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок виклику інструментів, перенесення історії сесії та межі sandbox. +- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? +- **Відповідність:** чи читає агент `SKILL.md` перед використанням і виконує обов’язкові кроки/аргументи? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні eval мають лишатися насамперед детермінованими: +Майбутні eval-оцінювання мають насамперед залишатися детермінованими: -- Ранер сценаріїв із mock-провайдерами для перевірки викликів інструментів + їхнього порядку, читання файлів Skill і зв’язування сесій. -- Невеликий набір сценаріїв, сфокусованих на Skills (використати чи уникнути, gating, prompt injection). -- Необов’язкові live-eval (лише за явним увімкненням, під контролем env) — тільки після появи безпечного для CI набору. +- Раннер сценаріїв, що використовує mock-провайдери для перевірки викликів інструментів + порядку, читання файлів Skill і wiring сесій. +- Невеликий набір сценаріїв, сфокусованих на Skills (використовувати чи уникати, гейтінг, prompt injection). +- Необов’язкові live-оцінювання (за згодою, з env-gating) лише після того, як безпечний для CI набір уже існуватиме. ## Контрактні тести (форма Plugin і каналу) -Контрактні тести перевіряють, що кожен зареєстрований Plugin і канал відповідає своєму -інтерфейсному контракту. Вони ітеруються по всіх виявлених Plugin і запускають набір -перевірок форми та поведінки. Типова unit-черга `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, -коли торкаєтеся спільних поверхонь каналів або провайдерів. +Контрактні тести перевіряють, що кожен зареєстрований Plugin і канал відповідає +контракту свого інтерфейсу. Вони ітеруються по всіх виявлених Plugin і запускають набір +перевірок форми та поведінки. Типова unit-лінія `pnpm test` навмисно +пропускає ці shared seam і smoke-файли; запускайте контрактні команди явно, +коли зачіпаєте спільні поверхні каналу або провайдера. ### Команди @@ -874,39 +946,39 @@ Open WebUI, перевіряє, що `/api/models` показує `openclaw/defa Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** — базова форма Plugin (id, name, capabilities) -- **setup** — контракт майстра налаштування -- **session-binding** — поведінка прив’язки сесії -- **outbound-payload** — структура payload повідомлення -- **inbound** — обробка вхідних повідомлень -- **actions** — обробники дій каналу -- **threading** — обробка ID thread -- **directory** — API каталогу/реєстру -- **group-policy** — примусове застосування групової політики +- **plugin** - Базова форма Plugin (id, name, capabilities) +- **setup** - Контракт wizard налаштування +- **session-binding** - Поведінка прив’язки сесії +- **outbound-payload** - Структура payload повідомлення +- **inbound** - Обробка вхідних повідомлень +- **actions** - Обробники дій каналу +- **threading** - Обробка ID тредів +- **directory** - API каталогу/складу +- **group-policy** - Забезпечення group policy ### Контракти статусу провайдера Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** — probe статусу каналу -- **registry** — форма реєстру Plugin +- **status** - Status probe каналу +- **registry** - Форма реєстру Plugin ### Контракти провайдерів Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** — контракт потоку автентифікації -- **auth-choice** — вибір/селектор автентифікації -- **catalog** — API каталогу моделей -- **discovery** — виявлення Plugin -- **loader** — завантаження Plugin -- **runtime** — runtime провайдера -- **shape** — форма/інтерфейс Plugin -- **wizard** — майстер налаштування +- **auth** - Контракт потоку auth +- **auth-choice** - Вибір/селекція auth +- **catalog** - API каталогу моделей +- **discovery** - Виявлення Plugin +- **loader** - Завантаження Plugin +- **runtime** - Runtime провайдера +- **shape** - Форма/інтерфейс Plugin +- **wizard** - Wizard налаштування ### Коли запускати -- Після змін експорту або підшляхів plugin-sdk +- Після зміни export-ів або subpath-ів plugin-sdk - Після додавання або зміни каналу чи Plugin провайдера - Після рефакторингу реєстрації або виявлення Plugin @@ -914,13 +986,13 @@ Open WebUI, перевіряє, що `/api/models` показує `openclaw/defa ## Додавання регресій (рекомендації) -Коли ви виправляєте проблему провайдера/моделі, виявлену в live: +Коли ви виправляєте проблему провайдера/моделі, виявлену у live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдера або фіксацію точної трансформації форми запиту) -- Якщо це за своєю природою лише live-проблема (rate limits, політики автентифікації), залишайте live-тест вузьким і з увімкненням через env-змінні -- Намагайтеся націлюватися на найменший шар, який ловить баг: - - баг перетворення/повтору запиту провайдера → тест direct models - - баг конвеєра Gateway session/history/tool → live smoke Gateway або безпечний для CI mock-тест Gateway -- Захисне правило обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить по одній вибірковій цілі на клас SecretRef із метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою для некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- За можливості додайте безпечну для CI регресію (mock/stub провайдера або захопіть точне перетворення форми запиту) +- Якщо це за природою лише live-проблема (rate limit, політики auth), залишайте live-тест вузьким і з opt-in через env-змінні +- Віддавайте перевагу найменшому шару, який ловить баг: + - баг перетворення/повторення запиту провайдера → тест direct models + - баг конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway +- Guardrail обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec id відхиляються. + - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на не класифікованих target id, щоб нові класи не можна було тихо пропустити.