From 8177939bfb0d205e3b80d529cdd690d0625bcb4a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Wed, 22 Apr 2026 23:34:50 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/help/testing.md | 853 ++++++++++++++------------- docs/uk/plugins/codex-harness.md | 313 +++++----- docs/uk/plugins/sdk-agent-harness.md | 117 ++-- 3 files changed, 673 insertions(+), 610 deletions(-) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index afdacbbd7..c271bcb69 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,15 +1,15 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресій для помилок моделей/провайдерів + - Додавання регресійних тестів для багів моделі/провайдера - Налагодження поведінки Gateway + агента summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-22T23:11:26Z" + generated_at: "2026-04-22T23:30:48Z" model: gpt-5.4 provider: openai - source_hash: 73da7ae34464cf08d337e53670ceed538fe90d9622fac13b649f9d11aa2d1df7 + source_hash: b26f70756380e76203e61f9ee80b44b133eb813e99b9f5909c63a01fc3ec9827 source_path: help/testing.md workflow: 15 --- @@ -21,113 +21,114 @@ OpenClaw має три набори Vitest (unit/integration, e2e, live) і не Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює) -- Які команди запускати для типових робочих процесів (локально, перед push, налагодження) +- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресії для реальних проблем моделей/провайдерів +- Як додавати регресійні тести для реальних проблем із моделями/провайдерами ## Швидкий старт У більшості випадків: -- Повний контрольний прогін (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` +- Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Швидший локальний запуск повного набору на машині з достатніми ресурсами: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` -- Пряме націлювання на файл тепер також маршрутизує шляхи plugin/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Під час ітерації над однією помилкою спочатку віддавайте перевагу цільовим запускам. +- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Під час ітерації над однією помилкою спочатку надавайте перевагу точковим запускам. - QA-сайт на базі Docker: `pnpm qa:lab:up` - QA-ланка на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете додаткової впевненості: +Коли ви змінюєте тести або хочете більше впевненості: -- Контрольний прогін покриття: `pnpm test:coverage` +- Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): - Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` -- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Димовий тест вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, потім виконайте ізольований +- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Smoke-тест вартості Moonshot/Kimi: якщо задано `MOONSHOT_API_KEY`, виконайте + `openclaw models list --provider moonshot --json`, а потім запустіть ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` для `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє про Moonshot/K2.6 і що - транскрипт асистента зберігає нормалізоване `usage.cost`. + транскрипт асистента зберігає нормалізований `usage.cost`. -Порада: коли вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. +Порада: коли вам потрібен лише один проблемний випадок, надавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. ## QA-специфічні ранери -Ці команди використовуються поряд з основними наборами тестів, коли вам потрібен реалізм qa-lab: +Ці команди розташовані поруч з основними наборами тестів, коли вам потрібна реалістичність qa-lab: - `pnpm openclaw qa suite` - - Запускає QA-сценарії з репозиторію безпосередньо на хості. - - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими воркерами Gateway. Для `qa-channel` типовим є рівень паралелізму 4 (обмежений кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість воркерів, або `--concurrency 1` для старішої послідовної ланки. - - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає збою. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального покриття фікстур і mock-протоколу без заміни сценаріє-орієнтованої ланки `mock-openai`. + - Запускає сценарії QA з репозиторію безпосередньо на хості. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими воркерами Gateway. Для `qa-channel` типовий рівень паралелізму — 4 (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість воркерів, або `--concurrency 1` для старішої послідовної ланки. + - Завершується з ненульовим кодом, якщо будь-який сценарій не пройшов. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. + - Підтримує режими провайдера `live-frontier`, `mock-openai` і `aimock`. + `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального + покриття фікстур і моків протоколу без заміни ланки `mock-openai`, яка враховує сценарії. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. + - Запускає той самий набір QA всередині тимчасової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані QA-входи автентифікації, які практичні для guest: - ключі провайдерів через env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через змонтований робочий простір. - - Записує звичайний QA-звіт + підсумок, а також логи Multipass у + - Під час live-запусків пересилає підтримувані вхідні дані автентифікації QA, які доцільні для гостьової системи: + ключі провайдерів через env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він наявний. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через змонтовану робочу область. + - Записує звичайний QA-звіт і підсумок, а також журнали Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. - `pnpm test:docker:bundled-channel-deps` - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway - зі сконфігурованим OpenAI, а потім вмикає Telegram і Discord через редагування конфігурації. - - Перевіряє, що перезапуск Gateway уперше встановлює runtime-залежності кожного вбудованого channel plugin за потреби, а другий перезапуск не перевстановлює залежності, які вже були активовані. - - Також встановлює відому старішу базову версію npm, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що post-update doctor кандидата відновлює runtime-залежності вбудованих channel без відновлення postinstall з боку harness. + з налаштованим OpenAI, а потім вмикає Telegram і Discord через редагування конфігурації. + - Перевіряє, що під час першого перезапуску Gateway кожен вбудований channel Plugin встановлює свої runtime-залежності на вимогу, а під час другого перезапуску вже активовані залежності не перевстановлюються. + - Також встановлює відомий старіший базовий стан npm, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що після оновлення doctor у кандидата відновлює runtime-залежності вбудованих channel без postinstall-відновлення з боку harness. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямого димового тестування протоколу. + - Запускає лише локальний сервер провайдера AIMock для прямих smoke-тестів протоколу. - `pnpm openclaw qa matrix` - Запускає live QA-ланку Matrix проти тимчасового homeserver Tuwunel на базі Docker. - - Цей QA-хост сьогодні призначений лише для repo/dev. Паковані встановлення OpenClaw не постачають `qa-lab`, тому вони не надають `openclaw qa`. - - Checkout-и репозиторію завантажують вбудований раннер безпосередньо; окремий крок встановлення plugin не потрібен. - - Надає три тимчасові користувачі Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway з реальним plugin Matrix як транспортом SUT. - - За замовчуванням використовує закріплений стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. - - Matrix не надає спільних прапорців джерела облікових даних, оскільки ця ланка локально створює тимчасових користувачів. + - Цей QA-хост наразі призначений лише для репозиторію/розробки. Паковані встановлення OpenClaw не постачають `qa-lab`, тож не відкривають `openclaw qa`. + - Checkout-и репозиторію завантажують вбудований ранер напряму; окремий крок встановлення plugin не потрібен. + - Надає три тимчасові користувачі Matrix (`driver`, `sut`, `observer`) і одну приватну кімнату, а потім запускає дочірній QA Gateway з реальним Matrix plugin як транспортом SUT. + - За замовчуванням використовує закріплений стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. + - Matrix не надає спільних прапорців джерела облікових даних, оскільки ланка локально створює тимчасових користувачів. - Записує QA-звіт Matrix, підсумок, артефакт observed-events і комбінований журнал stdout/stderr у `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає 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`, щоб увімкнути пуловані оренди. - - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає збою. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - - Потребує двох різних ботів у тій самій приватній групі, при цьому бот SUT має мати доступне ім’я користувача Telegram. - - Для стабільного спостереження бот-за-ботом увімкніть режим Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. + - Запускає live QA-ланку Telegram проти реальної приватної групи з використанням токенів ботів driver і SUT із env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. ID групи має бути числовим Telegram chat id. + - Підтримує `--credential-source convex` для спільних пулінгових облікових даних. Типово використовуйте режим env, або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути орендовані спільні облікові дані. + - Завершується з ненульовим кодом, якщо будь-який сценарій не пройшов. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. + - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати username у Telegram. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати груповий трафік ботів. - Записує QA-звіт Telegram, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. -Live-транспортні ланки поділяють один стандартний контракт, щоб нові транспорти не дрейфували: +Live-транспортні ланки використовують один стандартний контракт, щоб нові транспорти не розходилися: -`qa-channel` залишається широким синтетичним QA-набором і не є частиною матриці покриття live-транспортів. +`qa-channel` залишається широким синтетичним набором QA і не входить до матриці покриття live-транспортів. -| Ланка | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у треді | Ізоляція тредів | Спостереження за реакціями | Команда help | -| -------- | ------ | -------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | --------------- | -------------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Ланка | Канарка | Гейтинг згадок | Блок 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: +Еталонний каркас проєкту Convex: - `qa/convex-credential-broker/` Обов’язкові змінні середовища: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) + - Типове значення через env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) Необов’язкові змінні середовища: @@ -141,10 +142,10 @@ QA lab отримує ексклюзивну оренду з пулу на ба У звичайному режимі `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. -Команди адміністрування для maintainers (додавання/видалення/список пулу) вимагають +Адміністративні команди maintainer (додавання/видалення/список пулу) вимагають саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-хелпери для maintainers: +CLI-хелпери для maintainer: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -152,7 +153,7 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `--json` для машиночитаного виводу в скриптах і утилітах CI. +Використовуйте `--json` для машинозчитуваного виводу в скриптах і CI-утилітах. Контракт типового endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): @@ -172,7 +173,7 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Захист від активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` @@ -180,60 +181,60 @@ pnpm openclaw qa credentials remove --credential-id Форма payload для типу Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком числового ідентифікатора чату Telegram. +- `groupId` має бути рядком із числовим Telegram chat id. - `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректний payload. -### Додавання channel до QA +### Додавання каналу до QA -Додавання channel до markdown QA system вимагає рівно двох речей: +Додавання каналу до markdown-системи QA вимагає рівно двох речей: -1. Транспортного адаптера для channel. -2. Пакета сценаріїв, який перевіряє контракт channel. +1. Адаптер транспорту для каналу. +2. Набір сценаріїв, що перевіряє контракт каналу. Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` -може володіти цим потоком. +може керувати цим потоком. -`qa-lab` володіє спільною хост-механікою: +`qa-lab` відповідає за спільну хост-логіку: -- коренем команди `openclaw qa` -- запуском і завершенням набору -- паралелізмом воркерів -- записом артефактів -- генерацією звітів -- виконанням сценаріїв -- псевдонімами сумісності для старіших сценаріїв `qa-channel` +- кореневий простір команд `openclaw qa` +- запуск і завершення набору +- паралелізм воркерів +- запис артефактів +- генерацію звітів +- виконання сценаріїв +- псевдоніми сумісності для старіших сценаріїв `qa-channel` -Runner plugins володіють транспортним контрактом: +Runner plugins відповідають за контракт транспорту: - як `openclaw qa ` монтується під спільним коренем `qa` -- як Gateway конфігурується для цього транспорту +- як налаштовується Gateway для цього транспорту - як перевіряється готовність - як інжектуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються транскрипти й нормалізований стан транспорту -- як виконуються дії з транспортною підтримкою -- як обробляються скидання або очищення, специфічні для транспорту +- як надаються транскрипти та нормалізований стан транспорту +- як виконуються дії з підтримкою транспорту +- як обробляються transport-specific скидання або очищення -Мінімальна планка для впровадження нового channel: +Мінімальний поріг впровадження для нового каналу: 1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте транспортний раннер на спільному хост-сімі `qa-lab`. -3. Зберігайте транспортно-специфічну механіку всередині runner plugin або harness channel. -4. Монтуйте раннер як `openclaw qa `, а не реєструйте конкуруючий кореневий простір команд. +2. Реалізуйте transport runner на спільному host seam `qa-lab`. +3. Зберігайте transport-specific механіку всередині runner plugin або channel harness. +4. Монтуйте ранер як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. - Тримайте `runtime-api.ts` легким; відкладене виконання CLI і раннера має залишатися за окремими entrypoint. -5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте узагальнені хелпери сценаріїв для нових сценаріїв. -7. Зберігайте робочими наявні псевдоніми сумісності, якщо репозиторій не виконує навмисну міграцію. + Залишайте `runtime-api.ts` легким; ліниве виконання CLI та раннера має залишатися за окремими entrypoint. +5. Створюйте або адаптуйте markdown-сценарії в тематичних директоріях `qa/scenarios/`. +6. Використовуйте generic helper-и сценаріїв для нових сценаріїв. +7. Зберігайте наявні compatibility alias у робочому стані, якщо тільки репозиторій не виконує навмисну міграцію. -Правило ухвалення рішення суворе: +Правило прийняття рішень суворе: - Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. - Якщо поведінка залежить від одного channel transport, зберігайте її в цьому runner plugin або plugin harness. -- Якщо сценарію потрібна нова можливість, яку може використати більше ніж один channel, додайте узагальнений хелпер замість channel-специфічної гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного transport, залишайте сценарій transport-специфічним і явно вказуйте це в контракті сценарію. +- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте generic helper замість channel-specific гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного transport, зберігайте сценарій transport-specific і явно вказуйте це в контракті сценарію. -Бажані назви узагальнених хелперів для нових сценаріїв: +Бажані назви generic helper для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -248,7 +249,7 @@ Runner plugins володіють транспортним контрактом: - `formatTransportTranscript` - `resetTransport` -Псевдоніми сумісності залишаються доступними для наявних сценаріїв, зокрема: +Compatibility alias залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -256,248 +257,248 @@ Runner plugins володіють транспортним контрактом: - `formatConversationTranscript` - `resetBus` -Нова робота з channel має використовувати узагальнені назви хелперів. -Псевдоніми сумісності існують, щоб уникнути міграції «в один день», а не як модель для +Нова робота над каналами має використовувати generic helper names. +Compatibility alias існують, щоб уникнути міграції одним днем, а не як модель для створення нових сценаріїв. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): +Сприймайте набори як «зростання реалістичності» (і зростання нестабільності/вартості): -### Unit / integration (типовий) +### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) по наявних scoped Vitest projects -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і внесені до allowlist node-тести `ui`, охоплені `vitest.unit.config.ts` -- Область: +- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) через наявні scoped Vitest projects +- Файли: core/unit inventory у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, які охоплює `vitest.unit.config.ts` +- Обсяг: - Чисті unit-тести - - In-process integration-тести (автентифікація Gateway, маршрутизація, інструменти, парсинг, конфігурація) - - Детерміновані регресії для відомих помилок + - In-process integration-тести (автентифікація Gateway, маршрутизація, tooling, парсинг, конфігурація) + - Детерміновані регресії для відомих багів - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним -- Примітка про projects: - - Ненаправлений `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського root-project native process. Це зменшує піковий RSS на навантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` досі використовує native root `vitest.config.ts` project graph, оскільки цикл спостереження з багатьма shard непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі file/directory через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff зачіпає лише routable source/test files; редагування config/setup досі повертаються до широкого повторного запуску root-project. - - `pnpm check:changed` — це звичайний розумний локальний контрольний прогін для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни у публічному Plugin SDK і plugin-contract включають перевірку extension, бо extensions залежать від цих контрактів core. Оновлення версій лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, що відхиляє зміни package поза полем version верхнього рівня. - - Unit-тести з легкими import із agents, commands, plugins, хелперів auto-reply, `plugin-sdk` та подібних чистих утилітних областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - - Вибрані вихідні файли хелперів `plugin-sdk` і `commands` також відображають changed-mode запуски на явні sibling-тести в цих легких lanes, тож редагування хелперів уникають повторного запуску всього важкого набору для цього каталогу. - - `auto-reply` тепер має три окремі bucket: top-level core helpers, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це прибирає найважчу роботу harness reply із дешевих тестів status/chunk/token. +- Примітка про проєкти: + - Ненацілений `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. + - `pnpm test --watch` все ще використовує native root `vitest.config.ts` project graph, бо multi-shard watch loop непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файл/директорія через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test файлів; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. + - `pnpm check:changed` — це звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни публічного Plugin SDK і plugin-contract включають перевірку extension, оскільки extensions залежать від цих core-контрактів. Оновлення версій лише в release metadata запускають точкові перевірки version/config/root-dependency замість повного набору, із захистом, що відхиляє зміни package поза верхньорівневим полем version. + - Легкі щодо імпортів unit-тести з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` та подібних чистих utility-областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. + - Вибрані helper source files у `plugin-sdk` і `commands` також маплять changed-mode запуски на явні sibling-тести в цих легких lanes, тож зміни helper-ів не перезапускають увесь важкий набір для цієї директорії. + - `auto-reply` тепер має три виділені bucket: top-level core helper-и, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це тримає найважчу роботу harness reply осторонь від дешевих тестів status/chunk/token. - Примітка про embedded runner: - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime context Compaction, + - Коли ви змінюєте входи виявлення message-tool або runtime context Compaction, зберігайте обидва рівні покриття. - - Додавайте цільові helper-регресії для чистих меж routing/normalization. - - Також підтримуйте здоровими integration-набори embedded runner: + - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації/нормалізації. + - Також підтримуйте здоровий стан integration-наборів embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped ids і поведінка Compaction досі проходять + - Ці набори перевіряють, що scoped id і поведінка Compaction досі проходять через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є достатньою заміною для цих integration-шляхів. -- Примітка про пул: +- Примітка про pool: - Базова конфігурація Vitest тепер типово використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує неізольований runner у root projects, e2e і live configs. - - Коренева lane UI зберігає свій `jsdom` setup і optimizer, але тепер також працює на спільному неізольованому runner. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, конфігураціях e2e та live. + - Коренева lane UI зберігає свій `jsdom` setup і optimizer, але тепер також працює на спільному non-isolated runner. - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-process Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо вам потрібно порівняти зі стандартною поведінкою V8. + - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. - Примітка про швидку локальну ітерацію: - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. - - Pre-commit hook запускає `pnpm check:changed --staged` після staged formatting/linting, тож core-only commits не оплачують вартість extension tests, якщо вони не зачіпають публічні extension-facing contracts. Коміти лише з release metadata залишаються в цільовій lane version/config/root-dependency. - - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи чисто відображаються на менший набір. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим обмеженням воркерів. - - Автомасштабування локальних воркерів тепер навмисно консервативне і також зменшується, коли середнє навантаження хоста вже високе, тому кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, коли змінюється wiring тестів. - - Конфігурація зберігає увімкненим `OPENCLAW_VITEST_FS_MODULE_CACHE` на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо вам потрібне одне явне розташування кешу для прямого профілювання. -- Примітка про Perf-debug: - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість import разом із виводом деталізації import. - - `pnpm test:perf:imports:changed` обмежує той самий вид профілювання файлами, зміненими відносно `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` із native root-project path для цього закоміченого diff і виводить wall time плюс macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного dirty tree, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує main-thread CPU-profile для overhead запуску і transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner для unit-набору з вимкненим file parallelism. + - Pre-commit hook запускає `pnpm check:changed --staged` після форматування/linting staged-файлів, тож core-only коміти не оплачують вартість extension-тестів, якщо не торкаються публічних контрактів, орієнтованих на extension. Коміти лише з release metadata залишаються на точковій lane version/config/root-dependency. + - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи чітко мапляться на менший набір. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом воркерів. + - Автомасштабування локальних воркерів тепер навмисно консервативне і також відступає, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає projects/config files як `forceRerunTriggers`, щоб повторні запуски в changed-mode залишалися коректними, коли змінюється wiring тестів. + - Конфігурація залишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одну явну локацію кешу для прямого профілювання. +- Примітка про perf-debug: + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту плюс вивід деталізації імпортів. + - `pnpm test:perf:imports:changed` обмежує той самий режим профілювання файлами, зміненими відносно `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` із native root-project path для цього закоміченого diff і друкує wall time та macOS max RSS. +- `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує CPU-профіль main-thread для накладних витрат запуску і transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner-а для unit-набору з вимкненим паралелізмом файлів. -### E2E (димовий тест Gateway) +### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` -- Типові параметри runtime: +- Типові runtime-параметри: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 за замовчуванням). - - Типово працює в silent mode, щоб зменшити overhead консольного I/O. + - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 типово). + - Типово запускається в silent mode, щоб зменшити витрати на console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість воркерів (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний консольний вивід. -- Область: - - Наскрізна поведінка кількох екземплярів Gateway - - Поверхні WebSocket/HTTP, pairing вузлів і складніша мережна взаємодія + - `OPENCLAW_E2E_WORKERS=` для примусового задання кількості воркерів (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у консоль. +- Обсяг: + - Наскрізна поведінка multi-instance Gateway + - Поверхні WebSocket/HTTP, pairing вузлів і важче мережеве навантаження - Очікування: - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) + - Більше рухомих частин, ніж у unit-тестів (може бути повільніше) -### E2E: димовий тест бекенда OpenShell +### E2E: smoke OpenShell backend - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` -- Область: +- Обсяг: - Запускає ізольований Gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє бекенд OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє канонічну поведінку віддаленої файлової системи через міст fs sandbox + - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + виконання SSH + - Перевіряє remote-canonical поведінку файлової системи через bridge fs sandbox - Очікування: - - Лише opt-in; не є частиною типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і працездатного демона Docker - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox + - Лише opt-in; не входить до типового запуску `pnpm test:e2e` + - Потребує локальний CLI `openshell` і робочий Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий Gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб указати нестандартний бінарний файл CLI або wrapper script + - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний бінарний файл CLI або wrapper script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts` -- Типово: **увімкнено** командою `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) -- Область: - - «Чи цей провайдер/модель справді працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей tool-calling, проблем автентифікації та поведінки rate limit +- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) +- Обсяг: + - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» + - Виявлення змін форматів провайдера, особливостей виклику tools, проблем автентифікації та поведінки rate limit - Очікування: - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - Коштує грошей / використовує rate limits - Краще запускати звужені підмножини, а не «все» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API keys. -- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер типово працює в тихішому режимі: воно зберігає вивід прогресу `[live] ...`, але пригнічує додаткове повідомлення `~/.profile` і вимикає логи bootstrap Gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні startup logs. -- Ротація API keys (специфічно для провайдера): установіть `*_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` у форматі comma/semicolon або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для конкретного live через `OPENCLAW_LIVE_*_KEY`; тести виконують повторну спробу у відповідь на rate limit. - Вивід progress/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, щоб під час довгих викликів провайдера було видно, що робота триває, навіть коли Vitest працює з тихим перехопленням консолі. + - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдера помітно активні, навіть коли захоплення консолі Vitest працює тихо. - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/Gateway одразу транслювалися під час live-запусків. - - Налаштовуйте Heartbeat прямої моделі через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat Gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Скористайтеся цією таблицею рішень: +Використовуйте цю таблицю рішень: -- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато чого змінили) -- Якщо зачіпаєте мережну взаємодію Gateway / протокол WS / pairing: додайте `pnpm test:e2e` -- Під час налагодження «мій бот не працює» / збоїв, специфічних для провайдера / tool calling: запускайте звужений `pnpm test:live` +- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змін було багато) +- Якщо торкалися мережевої взаємодії Gateway / протоколу WS / pairing: додайте `pnpm test:e2e` +- Під час налагодження «мій бот не працює» / збоїв, специфічних для провайдера / виклику tools: запускайте звужений `pnpm test:live` -## Live: перевірка можливостей Android node +## Live: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку зараз оголошує** підключений Android node, і перевірити поведінку контракту команди. -- Область: +- Мета: викликати **кожну команду, яку зараз оголошує** підключений Android Node, і перевірити поведінку контракту команди. +- Обсяг: - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не виконує pairing застосунку). - - Перевірка `node.invoke` Gateway для вибраного Android node, команда за командою. + - Перевірка `node.invoke` у Gateway для вибраного Android Node, команда за командою. - Обов’язкове попереднє налаштування: - - Android-застосунок уже підключено й виконано pairing із Gateway. - - Застосунок має залишатися на передньому плані. - - Для можливостей, які мають проходити перевірку, надано дозволи/згоду на захоплення. + - Android app уже підключений і виконано pairing із Gateway. + - Застосунок утримується на передньому плані. + - Надані дозволи/погодження на захоплення для тих можливостей, які ви очікуєте як успішні. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. - Повні відомості про налаштування Android: [Android App](/uk/platforms/android) -## Live: димовий тест моделі (ключі профілів) +## Live: smoke моделей (ключі профілів) -Live-тести поділено на два рівні, щоб ми могли ізолювати збої: +Live-тести поділено на два шари, щоб можна було ізолювати збої: -- «Пряма модель» показує, що провайдер/модель взагалі може відповісти з наданим ключем. -- «Димовий тест Gateway» показує, що повний конвеєр gateway+agent працює для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). +- «Direct model» показує, чи провайдер/модель взагалі може відповісти з наданим ключем. +- «Gateway smoke» показує, чи працює повний конвеєр gateway+agent для цієї моделі (сесії, історія, tools, sandbox policy тощо). -### Рівень 1: пряме завершення моделі (без Gateway) +### Шар 1: пряме завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використовувати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані - - Виконати невелике завершення для кожної моделі (і цільові регресії, де потрібно) + - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані + - Виконати невелике completion для кожної моделі (і точкові регресії, де потрібно) - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запускати цей набір; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на димовому тесті Gateway +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб цей набір справді запускався; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern` для запуску modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Для modern/all sweeps типово використовується curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого cap. + - Для modern/all sweep типово діє curated high-signal cap; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого обмеження. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - Типово: сховище профілів і резервні варіанти з env - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** + - Типово: profile store і резервні значення з env + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр gateway agent зламаний» - - Містить невеликі ізольовані регресії (приклад: повторення reasoning у OpenAI Responses/Codex Responses + потоки tool-call) + - Відокремлює «API провайдера зламане / ключ недійсний» від «зламаний конвеєр gateway agent» + - Містить невеликі ізольовані регресії (приклад: повторення міркувань OpenAI Responses/Codex Responses + потоки tool-call) -### Рівень 2: димовий тест Gateway + dev agent (що насправді робить "@openclaw") +### Шар 2: Gateway + smoke dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - Підняти in-process Gateway - - Створити/пропатчити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) - - Ітерувати моделі-з-ключами й перевіряти: - - «змістовну» відповідь (без інструментів) - - що працює реальний виклик інструмента (probe читання) - - необов’язкові додаткові probe інструментів (probe exec+read) + - Створити/змінити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) + - Перебрати моделі з ключами та перевірити: + - «змістовну» відповідь (без tools) + - що працює реальний виклик tool (перевірка read) + - необов’язкові додаткові перевірки tools (перевірка exec+read) - що шляхи регресії OpenAI (лише tool-call → подальший виклик) і далі працюють -- Подробиці probe (щоб ви могли швидко пояснювати збої): - - probe `read`: тест записує nonce-файл у робочому просторі й просить агента `read` його та повернути nonce назад. - - probe `exec+read`: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. - - image probe: тест прикріплює згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. +- Деталі перевірок probe (щоб ви могли швидко пояснювати збої): + - `read` probe: тест записує файл із nonce у workspace і просить агента `read` його та повернути nonce. + - `exec+read` probe: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. + - image probe: тест прикріплює згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - Як вибирати моделі: - Типово: 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 або додатне число для меншого cap. -- Як вибирати провайдерів (уникаючи «все через OpenRouter»): + - Або задайте `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому) для звуження + - Для gateway sweep modern/all типово діє curated high-signal cap; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern sweep або додатне число для меншого обмеження. +- Як вибирати провайдерів (уникайте «усе з OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Probe інструментів і зображень у цьому live-тесті завжди увімкнені: - - probe `read` + probe `exec+read` (навантаження на інструменти) - - image probe запускається, коли модель оголошує підтримку вхідних зображень - - Потік (високий рівень): - - Тест генерує крихітний PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) +- Перевірки tool + image завжди увімкнені в цьому live-тесті: + - `read` probe + `exec+read` probe (навантаження на tools) + - image probe запускається, коли модель оголошує підтримку image input + - Потік (на високому рівні): + - Тест генерує крихітний 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`) - - Вбудований агент передає multimodal-повідомлення користувача моделі + - Gateway парсить attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Embedded agent пересилає multimodal user message моделі - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що ви можете тестувати на своїй машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що можна протестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: димовий тест CLI-бекенда (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent, використовуючи локальний CLI-бекенд, не зачіпаючи вашу типову конфігурацію. -- Типові параметри димового тесту, специфічні для бекенда, зберігаються у визначенні `cli-backend.ts` extension, яка ним володіє. +- Мета: перевірити конвеєр Gateway + agent з використанням локального CLI backend, не торкаючись вашої типової конфігурації. +- Типові значення smoke, специфічні для backend, розміщені у визначенні `cli-backend.ts` відповідного extension. - Увімкнення: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` -- Типові параметри: +- Типові значення: - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих plugin CLI backend, яка ним володіє. -- Перевизначення (необов’язково): + - Поведінка command/args/image береться з метаданих plugin відповідного CLI backend. +- Перевизначення (необов’язкові): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне вкладення-зображення (шляхи інжектуються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість інжекції в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати тим, як передаються аргументи зображень, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік відновлення. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типовий probe безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути його, коли вибрана модель підтримує ціль переключення). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне image-attachment (шляхи інжектуються у prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до image-файлів як CLI args замість інжекції в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати передаванням image args, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити flow відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -524,29 +525,29 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає димовий тест live CLI-backend усередині Docker-образу репозиторію як непривілейований користувач `node`. -- Він визначає метадані димового тесту 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 Claude Code subscription OAuth через `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він перевіряє прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження змінних середовища Anthropic API-key. Ця subscription-ланка за замовчуванням вимикає probe Claude MCP/tool і зображень, оскільки Claude наразі маршрутизує використання сторонніх застосунків через додаткове billing за використання замість звичайних лімітів subscription plan. -- Димовий тест live CLI-backend тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через Gateway CLI. -- Типовий димовий тест Claude також патчить сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Docker-ранер розміщено в `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані smoke CLI з відповідного extension, а потім установлює відповідний Linux CLI package (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` потребує portable OAuth підписки Claude Code через `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType` або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він перевіряє прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-backend без збереження змінних середовища Anthropic API-key. Ця ланка підписки типово вимикає перевірки Claude MCP/tool та image, тому що зараз Claude маршрутизує використання сторонніх застосунків через додаткову оплату usage, а не через звичайні ліміти плану підписки. +- Live smoke CLI-backend тепер перевіряє той самий наскрізний flow для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик tool MCP `cron`, перевірений через Gateway CLI. +- Типовий smoke Claude також змінює сесію із Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. -## Live: димовий тест прив’язки ACP (`/acp spawn ... --bind here`) +## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік прив’язки розмови ACP із live ACP agent: +- Мета: перевірити реальний flow conversation-bind для ACP з live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну розмову message-channel на місці - - надіслати звичайне подальше повідомлення в цій самій розмові - - перевірити, що подальше повідомлення потрапляє в транскрипт прив’язаної сесії ACP + - прив’язати синтетичну conversation message-channel на місці + - надіслати звичайне подальше повідомлення в цю саму conversation + - перевірити, що подальше повідомлення потрапляє в transcript прив’язаної ACP-сесії - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` -- Типові параметри: +- Типові значення: - ACP agents у Docker: `claude,codex,gemini` - ACP agent для прямого `pnpm test:live ...`: `claude` - - Синтетичний channel: контекст розмови в стилі Slack DM - - Бекенд ACP: `acpx` + - Синтетичний канал: контекст conversation у стилі Slack DM + - ACP backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -554,8 +555,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, щоб тести могли приєднувати контекст message-channel без удавання зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness agent. + - Ця ланка використовує поверхню Gateway `chat.send` з admin-only synthetic полями originating-route, щоб тести могли прикріплювати контекст message-channel без імітації зовнішньої доставки. + - Якщо `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness agent. Приклад: @@ -581,31 +582,35 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає димовий тест прив’язки ACP послідовно для всіх підтримуваних live CLI agents: `claude`, `codex`, а потім `gemini`. +- Docker-ранер розміщено в `scripts/test-live-acp-bind-docker.sh`. +- Типово він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI agent: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він використовує `~/.profile`, переносить відповідні auth-матеріали CLI в контейнер, встановлює `acpx` у записуваний npm-префікс, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. -- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав змінні середовища провайдера зі sourced profile доступними для дочірнього harness CLI. +- Він підвантажує `~/.profile`, переносить відповідні матеріали автентифікації CLI в контейнер, встановлює `acpx` у записуваний npm-префікс, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. +- Усередині Docker ранер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб `acpx` зберігав змінні середовища провайдера зі завантаженого профілю доступними для дочірнього CLI harness. -## Live: димовий тест harness app-server Codex +## Live: smoke harness Codex app-server -- Мета: перевірити harness Codex, яким володіє plugin, через звичайний gateway - метод `agent`: +- Мета: перевірити harness Codex, яким володіє plugin, через звичайний метод gateway + `agent`: - завантажити вбудований plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - надіслати перший хід gateway agent до `codex/gpt-5.4` - - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що thread + - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що потік app-server може відновитися - виконати `/codex status` і `/codex models` через той самий командний шлях gateway + - за бажанням виконати дві shell-перевірки з ескалацією, переглянуті Guardian: одну безпечну + команду, яку слід схвалити, і одне фальшиве завантаження секрету, + яке слід відхилити, щоб агент перепитав - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `codex/gpt-5.4` -- Необов’язковий image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` -- Необов’язковий MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Димовий тест встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex - harness не міг пройти перевірку, тихо переключившись на PI. -- Автентифікація: `OPENAI_API_KEY` із shell/profile, плюс необов’язково скопійовані +- Необов’язкова image-перевірка: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язкова MCP/tool-перевірка: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Необов’язкова перевірка Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` +- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex + не міг пройти завдяки тихому fallback на PI. +- Автентифікація: `OPENAI_API_KEY` із shell/profile, а також необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -615,11 +620,12 @@ source ~/.profile OPENCLAW_LIVE_CODEX_HARNESS=1 \ OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 \ OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 \ + OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1 \ OPENCLAW_LIVE_CODEX_HARNESS_MODEL=codex/gpt-5.4 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` -Рецепт Docker: +Docker-рецепт: ```bash source ~/.profile @@ -628,48 +634,50 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. -- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації Codex CLI, якщо вони присутні, встановлює `@openai/codex` у записуваний змонтований npm +- Docker-ранер розміщено в `scripts/test-live-codex-harness-docker.sh`. +- Він підвантажує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + автентифікації Codex CLI, якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm префікс, готує дерево вихідного коду, а потім запускає лише live-тест Codex-harness. -- Docker типово вмикає image і MCP/tool probes. Установіть +- Docker типово вмикає image-, MCP/tool- і Guardian-перевірки. Установіть `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 не міг приховати регресію - Codex harness. + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` або + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий режим + налагодження. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і live- + тестова конфігурація, щоб fallback `openai-codex/*` або PI не міг приховати + регресію harness Codex. ### Рекомендовані live-рецепти -Вузькі, явні allowlist — найшвидші та найменш нестабільні: +Вузькі, явні allowlist є найшвидшими й найменш нестабільними: -- Одна модель, напряму (без Gateway): +- Одна модель, direct (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Одна модель, димовий тест Gateway: +- Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Tool calling через кілька провайдерів: +- Виклик tools через кількох провайдерів: - `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 key Gemini + Antigravity): +- Фокус на Google (Gemini API key + Antigravity): - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Примітки: - `google/...` використовує Gemini API (API key). -- `google-antigravity/...` використовує OAuth-міст Antigravity (endpoint агента у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). +- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint агента у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості tooling). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений у Google Gemini API через HTTP (автентифікація через API key / profile); це те, що більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw викликає локальний бінарний файл `gemini`; він має власну автентифікацію й може поводитися інакше (streaming/підтримка інструментів/розходження версій). + - API: OpenClaw викликає розміщений Gemini API від Google через HTTP (API key / автентифікація профілю); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує локальний бінарний файл `gemini`; він має власну автентифікацію та може поводитися інакше (streaming/підтримка tools/version skew). ## Live: матриця моделей (що ми охоплюємо) -Фіксованого «списку моделей CI» не існує (live — це opt-in), але це **рекомендовані** моделі для регулярного покриття на dev-машині з ключами. +Фіксованого «списку моделей CI» немає (live — це opt-in), але ось **рекомендовані** моделі, які варто регулярно перевіряти на dev-машині з ключами. -### Сучасний набір димових тестів (tool calling + image) +### Сучасний smoke-набір (виклик tools + image) Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: @@ -681,10 +689,10 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск димового тесту Gateway з tools + image: +Запуск gateway smoke з tools + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: tool calling (Read + необов’язковий Exec) +### Базовий рівень: виклик tools (Read + необов’язковий Exec) Виберіть щонайменше одну модель на сімейство провайдерів: @@ -694,81 +702,81 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (було б добре мати): +Необов’язкове додаткове покриття (приємно мати): -- xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою “tools”, яку у вас увімкнено) -- Cerebras: `cerebras/`… (якщо у вас є доступ) -- LM Studio: `lmstudio/`… (локально; tool calling залежить від режиму API) +- xAI: `xai/grok-4` (або останню доступну) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас увімкнено) +- Cerebras: `cerebras/`… (якщо маєте доступ) +- LM Studio: `lmstudio/`… (локально; виклик tools залежить від режиму API) -### Vision: надсилання зображення (вкладення → multimodal-повідомлення) +### Vision: надсилання image (вкладення → multimodal message) -Включіть щонайменше одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб задіяти image probe. +Включіть принаймні одну модель із підтримкою image у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб перевірити image probe. -### Агрегатори / альтернативні Gateway +### Агрегатори / альтернативні gateway Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+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` (custom endpoints): `minimax` (хмара/API), а також будь-який сумісний із OpenAI/Anthropic proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (власні endpoint): `minimax` (cloud/API), а також будь-який проксі, сумісний з OpenAI/Anthropic (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко прописати в документації «усі моделі». Авторитетним списком є те, що `discoverModels(...)` повертає на вашій машині, плюс ті ключі, які доступні. +Порада: не намагайтеся жорстко прописати в документації «усі моделі». Авторитетним списком є те, що `discoverModels(...)` повертає на вашій машині + які ключі доступні. ## Облікові дані (ніколи не комітьте) -Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: +Live-тести виявляють облікові дані так само, як CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знайти ті самі ключі. -- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. +- Якщо CLI працює, live-тести мають знаходити ті самі ключі. +- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як для `openclaw models list` / вибору моделі. -- Профілі автентифікації для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в live-тестах означає «ключі профілів») +- Автентифікаційні профілі на рівні агента: `~/.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 homes пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probes не працювали у вашому реальному робочому просторі хоста. +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо існує, але не є основним сховищем profile key) +- Локальні live-запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` прибираються, щоб probe не торкалися вашого реального workspace хоста. -Якщо ви хочете покладатися на env keys (наприклад, експортовані у вашому `~/.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 +## Live BytePlus coding plan - Тест: `src/agents/byteplus.live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live: медіа workflow ComfyUI +## Live медіа робочих процесів ComfyUI - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` -- Область: - - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` - - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` - - Корисно після змін у поданні workflow comfy, опитуванні, завантаженнях або реєстрації plugin +- Обсяг: + - Перевіряє вбудовані шляхи comfy для image, video і `music_generate` + - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано + - Корисно після змін у надсиланні робочих процесів 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 vars провайдера з вашого shell входу (`~/.profile`) перед probe - - Типово використовує live/env API keys раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - - Пропускає провайдерів без придатної автентифікації/profile/model - - Запускає стандартні варіанти генерації зображень через спільну runtime-можливість: +- Обсяг: + - Перелічує кожен зареєстрований provider plugin генерації зображень + - Завантажує відсутні env-змінні провайдерів із вашого login shell (`~/.profile`) перед перевіркою + - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Запускає стандартні варіанти генерації зображень через спільну runtime capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані провайдери, що охоплюються: +- Поточні вбудовані провайдери, які охоплюються: - `openai` - `google` - `xai` @@ -777,75 +785,75 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через сховище профілів і ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через сховище профілів і ігнорувати перевизначення лише через env -## 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 vars провайдера з вашого shell входу (`~/.profile`) перед probe - - Типово використовує live/env API keys раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - - Пропускає провайдерів без придатної автентифікації/profile/model + - Завантажує env-змінні провайдерів із вашого login shell (`~/.profile`) перед перевіркою + - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної автентифікації/профілю/моделі - Запускає обидва оголошені runtime-режими, коли вони доступні: - `generate` із введенням лише prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - Поточне покриття спільної ланки: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, не цей спільний sweep + - `comfy`: окремий live-файл Comfy, а не цей спільний sweep - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через сховище профілів і ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через сховище профілів і ігнорувати перевизначення лише через 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` -- Область: +- Обсяг: - Перевіряє спільний вбудований шлях провайдера генерації відео - - Типово використовує безпечний для релізу шлях димового тесту: провайдери без FAL, один запит text-to-video на провайдера, односекундний lobster-prompt і обмеження операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (типово `180000`) - - Типово пропускає FAL, оскільки затримка черги на боці провайдера може домінувати над часом релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно - - Завантажує env vars провайдера з вашого shell входу (`~/.profile`) перед probe - - Типово використовує live/env API keys раніше за збережені профілі автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - - Пропускає провайдерів без придатної автентифікації/profile/model + - Типово використовує безпечний для релізу smoke-шлях: провайдери без FAL, один text-to-video запит на провайдера, односекундний prompt із lobster і обмеження часу операції на провайдера через `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` типово) + - Типово пропускає FAL, тому що затримка черги на боці провайдера може домінувати над часом релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно + - Завантажує env-змінні провайдерів із вашого login shell (`~/.profile`) перед перевіркою + - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатної автентифікації/профілю/моделі - Типово запускає лише `generate` - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальне buffer-backed введення зображення у спільному sweep - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальне buffer-backed введення відео у спільному sweep + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальне введення image на основі buffer у спільному sweep + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальне введення video на основі buffer у спільному sweep - Поточні провайдери `imageToVideo`, оголошені, але пропущені у спільному sweep: - - `vydra`, бо вбудований `veo3` підтримує лише text, а вбудований `kling` вимагає віддалений URL зображення + - `vydra`, тому що вбудований `veo3` підтримує лише text-to-video, а вбудований `kling` потребує віддалений URL зображення - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс ланку `kling`, яка типово використовує фікстуру віддаленого URL зображення + - цей файл запускає `veo3` text-to-video, а також ланку `kling`, яка типово використовує фікстуру віддаленого URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - Поточні провайдери `videoToVideo`, оголошені, але пропущені у спільному sweep: - - `alibaba`, `qwen`, `xai`, бо ці шляхи наразі вимагають віддалені референсні URL `http(s)` / MP4 - - `google`, бо поточна спільна ланка Gemini/Veo використовує локальне buffer-backed введення, а цей шлях не приймається у спільному sweep - - `openai`, бо поточна спільна ланка не гарантує доступ до video inpaint/remix, специфічний для org + - `alibaba`, `qwen`, `xai`, тому що ці шляхи зараз потребують віддалені reference URL `http(s)` / MP4 + - `google`, тому що поточна спільна ланка Gemini/Veo використовує локальне введення на основі buffer, а цей шлях не приймається у спільному sweep + - `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_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового sweep, включно з FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження операції для кожного провайдера в агресивному димовому запуску + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного провайдера для агресивного smoke-запуску - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через сховище профілів і ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через сховище профілів і ігнорувати перевизначення лише через env ## Live media harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори для зображень, музики та відео через один native-entrypoint репозиторію - - Автоматично завантажує відсутні env vars провайдера з `~/.profile` - - Типово автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і тихого режиму залишається узгодженою + - Запускає спільні live-набори image, music і video через один рідний для репозиторію entrypoint + - Автоматично завантажує відсутні env-змінні провайдерів із `~/.profile` + - Типово автоматично звужує кожен набір до провайдерів, які зараз мають придатну автентифікацію + - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і quiet mode залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -856,125 +864,124 @@ Live-тести знаходять облікові дані так само, я Ці Docker-ранери поділяються на дві групи: -- Ранери live-model: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл для profile-key усередині 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-cap, щоб повний Docker sweep залишався практичним: - `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл із ключами профілів усередині 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-cap, щоб повний Docker sweep залишався практичним: + `test:docker:live-models` типово встановлює `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` типово встановлює `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли вам явно потрібне більше вичерпне сканування. -- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для двох live Docker lanes. -- Ранери димових тестів контейнерів: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. +- `test:docker:all` один раз збирає Docker-образ live через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ланок live. +- Smoke-ранери контейнерів: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-ранери live-model також bind-монтують лише потрібні домівки автентифікації CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени, не змінюючи auth store хоста: +Docker-ранери live-моделей також bind-mount-ять лише потрібні домашні каталоги автентифікації CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у сховищі автентифікації хоста: -- Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Димовий тест прив’язки ACP: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- Димовий тест CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Димовий тест harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- Direct models: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) +- Smoke ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- Smoke CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke harness Codex app-server: `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 Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повний scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Мережева взаємодія Gateway (два контейнери, автентифікація WS + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Міст channel MCP (seeded Gateway + stdio bridge + димовий тест raw Claude notification-frame): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (димовий тест встановлення + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-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 auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Міст MCP channel (ініціалізований Gateway + stdio bridge + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (smoke встановлення + псевдонім `/plugin` + семантика перезапуску bundle Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Docker-ранери live-model також bind-монтують поточний checkout лише для читання і -готують його в тимчасовий workdir усередині контейнера. Це зберігає runtime -image компактним, але все одно запускає Vitest точно проти ваших локальних source/config. -Етап підготовки пропускає великі локальні кеші та виводи збірки застосунків, такі як -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або -вивід Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -машиноспецифічних артефактів. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probes Gateway не запускали +Docker-ранери live-моделей також bind-mount-ять поточний checkout лише для читання і +готують його у тимчасовий workdir всередині контейнера. Це зберігає runtime- +образ компактним і водночас дозволяє запускати Vitest точно на вашому локальному source/config. +Крок підготовки пропускає великі лише локальні кеші та результати збірки застосунків, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для app каталоги `.build` або вихідні каталоги Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +артефактів, специфічних для машини. +Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали реальні воркери channel Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття gateway -live із цієї Docker-ланки. -`test:docker:openwebui` — це димовий тест сумісності вищого рівня: він запускає -контейнер Gateway OpenClaw з увімкненими HTTP-endpoint, сумісними з OpenAI, -запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через -Open WebUI, перевіряє, що `/api/models` надає `openclaw/default`, а потім надсилає -реальний chat-запит через проксі Open WebUI `/api/chat/completions`. -Перший запуск може бути помітно повільнішим, тому що Docker може потребувати завантаження -image Open WebUI, а сам Open WebUI може потребувати завершення власного cold-start налаштування. -Ця ланка очікує придатний ключ live model, а `OPENCLAW_PROFILE_FILE` +`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway +live-покриття з цієї Docker-ланки. +`test:docker:openwebui` — це smoke-перевірка сумісності вищого рівня: вона запускає +контейнер Gateway OpenClaw з увімкненими сумісними з OpenAI HTTP endpoint, +запускає закріплений контейнер Open WebUI проти цього Gateway, виконує вхід через +Open WebUI, перевіряє, що `/api/models` відкриває `openclaw/default`, а потім надсилає +реальний chat-запит через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися завантажити +образ Open WebUI, а самому Open WebUI може знадобитися завершити власне холодне стартове налаштування. +Ця ланка очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` (типово `~/.profile`) — основний спосіб надати його в Dockerized-запусках. -Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": +Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway -container, запускає другий container, який піднімає `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, -поведінку черги live event, маршрутизацію outbound send і повідомлення channel + -дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка повідомлень -безпосередньо аналізує raw stdio MCP frames, тому димовий тест перевіряє те, що міст -справді випромінює, а не лише те, що випадково показує певний SDK клієнта. +`test:docker:mcp-channels` навмисно є детермінованим і не потребує +реального облікового запису Telegram, Discord або iMessage. Він запускає ініціалізований контейнер Gateway, +запускає другий контейнер, який виконує `openclaw mcp serve`, а потім +перевіряє виявлення conversation з маршрутизацією, читання transcript, метадані вкладень, +поведінку live event queue, маршрутизацію outbound send і сповіщення про channel + +дозволи у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень +безпосередньо аналізує сирі кадри stdio MCP, тож smoke перевіряє те, що +міст реально видає, а не лише те, що випадково відкриває конкретний клієнтський SDK. -Ручний ACP plain-language thread smoke (не CI): +Ручний smoke plain-language thread для ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. +- Зберігайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. Корисні env vars: - `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і підвантажується перед запуском тестів - `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env vars, підвантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої автентифікації CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker -- Зовнішні каталоги/файли автентифікації CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установлень CLI усередині Docker +- Зовнішні каталоги/файли автентифікації CLI під `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед запуском тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому на кшталт `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Перевизначення вручну: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків, які не потребують перебудови -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані походять зі сховища профілів (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для димового тесту Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує димовий тест Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег image Open WebUI +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків без потреби перебудови +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані надходять зі сховища профілів (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway відкриває для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI ## Перевірка документації Після редагування документації запускайте перевірки документації: `pnpm check:docs`. -Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Запускайте повну перевірку якірних посилань Mintlify, коли вам також потрібна перевірка заголовків у межах сторінки: `pnpm docs:check-links:anchors`. -## Офлайнова регресія (безпечна для CI) +## Офлайн-регресія (безпечно для CI) Це регресії «реального конвеєра» без реальних провайдерів: -- Tool calling Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, запис config + примусова auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик tools Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, примусовий запис config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") ## Оцінювання надійності агента (Skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: -- Mock tool-calling через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють прив’язку сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Mock-виклик tools через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- Наскрізні потоки майстра, які перевіряють wiring сесій і вплив конфігурації (`src/gateway/gateway.test.ts`). -Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Вибір рішення:** коли в prompt перелічено Skills, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Відповідність:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? -- **Контракти робочих процесів:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Вибір рішення:** коли Skills перелічено в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? +- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/args? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок tools, перенесення історії сесії та межі sandbox. -Майбутні evals мають насамперед залишатися детермінованими: +Майбутні оцінювання мають насамперед залишатися детермінованими: -- Runner сценаріїв, який використовує mock-провайдерів для перевірки викликів інструментів + порядку, читання skill-файлів і прив’язки сесії. -- Невеликий набір сценаріїв, зосереджених на skills (використовувати чи уникати, гейтінг, prompt injection). -- Необов’язкові live evals (opt-in, із гейтінгом через env) лише після того, як буде готовий безпечний для CI набір. +- Scenario runner із mock-провайдерами для перевірки викликів tools + їхнього порядку, читання skill-файлів і wiring сесій. +- Невеликий набір сценаріїв, сфокусованих на Skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live-eval (opt-in, із gating через env) лише після того, як буде готовий безпечний для CI набір. -## Контрактні тести (форма plugin і channel) +## Contract-тести (форма plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму -контракту інтерфейсу. Вони ітерують усі виявлені plugins і запускають набір перевірок -форми та поведінки. Типова unit-ланка `pnpm test` навмисно -пропускає ці файли спільних seam і smoke; запускайте контрактні команди явно, -коли зачіпаєте спільні поверхні channel або provider. +Contract-тести перевіряють, що кожен зареєстрований plugin і channel відповідає +своєму контракту інтерфейсу. Вони проходять по всіх виявлених plugin і запускають набір +перевірок форми та поведінки. Типова unit-ланка `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте contract-команди явно, +коли торкаєтеся спільних поверхонь channel або provider. ### Команди @@ -984,7 +991,7 @@ container, запускає другий container, який піднімає `o ### Контракти channel -Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: +Розміщені в `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Базова форма plugin (id, name, capabilities) - **setup** - Контракт майстра налаштування @@ -994,21 +1001,21 @@ container, запускає другий container, який піднімає `o - **actions** - Обробники дій channel - **threading** - Обробка thread ID - **directory** - API каталогу/списку учасників -- **group-policy** - Застосування group policy +- **group-policy** - Примусове застосування групової політики ### Контракти статусу provider -Розташовані в `src/plugins/contracts/*.contract.test.ts`. +Розміщені в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Probe статусу channel +- **status** - Перевірки статусу channel - **registry** - Форма реєстру plugin ### Контракти provider -Розташовані в `src/plugins/contracts/*.contract.test.ts`: +Розміщені в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір/визначення автентифікації +- **auth-choice** - Вибір/селектор автентифікації - **catalog** - API каталогу моделей - **discovery** - Виявлення plugin - **loader** - Завантаження plugin @@ -1018,21 +1025,21 @@ container, запускає другий container, який піднімає `o ### Коли запускати -- Після зміни export або subpath у plugin-sdk -- Після додавання або зміни plugin channel або provider +- Після змін export/subpath у plugin-sdk +- Після додавання або зміни channel чи provider plugin - Після рефакторингу реєстрації або виявлення plugin -Контрактні тести запускаються в CI й не потребують реальних API keys. +Contract-тести запускаються в CI і не потребують реальних API-ключів. -## Додавання регресій (рекомендації) +## Додавання регресійних тестів (рекомендації) Коли ви виправляєте проблему provider/model, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або захопіть точну трансформацію форми запиту) -- Якщо проблема за своєю природою лише live (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env vars -- Віддавайте перевагу найменшому рівню, який ловить помилку: - - помилка перетворення/повтору запиту provider → тест прямих моделей - - помилка конвеєра gateway session/history/tool → live smoke Gateway або безпечний для CI gateway mock-тест -- Захисний механізм обходу 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 provider або фіксація точної трансформації форми запиту) +- Якщо проблема за своєю природою лише live-only (rate limits, політики автентифікації), залишайте live-тест вузьким і opt-in через env vars +- Надавайте перевагу найменшому шару, який ловить баг: + - баг перетворення/повторення запиту provider → direct models test + - баг конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI gateway mock test +- Guardrail обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибрану ціль на клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегмента обходу відхиляються. + - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index 53f170f94..41cedecd4 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,70 +1,74 @@ --- read_when: - - Ви хочете використовувати комплектний каркас app-server Codex + - Ви хочете використовувати комплектний harness app-server Codex - Вам потрібні посилання на моделі Codex і приклади конфігурації - Ви хочете вимкнути резервний перехід на PI для розгортань лише з Codex -summary: Запускайте вбудовані ходи агента OpenClaw через комплектний каркас app-server Codex -title: Каркас Codex +summary: Запускайте вбудовані ходи агента OpenClaw через комплектний harness app-server Codex +title: Harness Codex x-i18n: - generated_at: "2026-04-22T23:11:34Z" + generated_at: "2026-04-22T23:30:52Z" model: gpt-5.4 provider: openai - source_hash: 1807184a085f4b54e1b722e02c1f47f059dc393a0ba7ecb0ec5903f74495267f + source_hash: ffd539ad6544284a31bc32f2e506fa46b7ba70d2994ef80eb422ae6cb459d8fa source_path: plugins/codex-harness.md workflow: 15 --- -# Каркас Codex +# Harness Codex Комплектний plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через -app-server Codex замість вбудованого каркаса PI. +app-server Codex замість вбудованого harness PI. -Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням -моделей, нативним відновленням потоку, нативною Compaction і виконанням через app-server. -OpenClaw і далі керує каналами чату, файлами сесій, вибором моделей, інструментами, -погодженнями, доставкою медіа та видимим дзеркалом транскрипту. +Використовуйте це, коли ви хочете, щоб Codex керував низькорівневою сесією агента: виявленням +моделей, нативним відновленням потоку, нативною Compaction і виконанням app-server. +OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделей, інструментами, +погодженнями, доставленням медіа та видимим дзеркалом стенограми. -Нативні ходи Codex також поважають спільні plugin-хуки `before_prompt_build`, -`before_compaction` і `after_compaction`, тож шими prompt і автоматизація з урахуванням -Compaction можуть залишатися узгодженими з каркасом PI. +Нативні ходи Codex також підтримують спільні хоки plugin `before_prompt_build`, +`before_compaction` і `after_compaction`, тож шими підказок і +автоматизація з урахуванням Compaction можуть залишатися узгодженими з harness PI. +Нативні ходи Codex також підтримують спільні хоки plugin `before_prompt_build`, +`before_compaction`, `after_compaction`, `llm_input`, `llm_output` і +`agent_end`, тож шими підказок, автоматизація з урахуванням Compaction і +спостерігачі життєвого циклу можуть залишатися узгодженими з harness PI. -Каркас вимкнений типово. Він вибирається лише тоді, коли plugin `codex` увімкнено і -визначена модель є моделлю `codex/*`, або коли ви явно примусово задаєте -`embeddedHarness.runtime: "codex"` чи `OPENCLAW_AGENT_RUNTIME=codex`. -Якщо ви взагалі не налаштовуєте `codex/*`, наявні запуски PI, OpenAI, Anthropic, Gemini, local +Harness вимкнено за замовчуванням. Він вибирається лише тоді, коли plugin `codex` +увімкнено і визначена модель є моделлю `codex/*`, або коли ви явно +примусово задаєте `embeddedHarness.runtime: "codex"` чи `OPENCLAW_AGENT_RUNTIME=codex`. +Якщо ви ніколи не налаштовуєте `codex/*`, наявні запуски PI, OpenAI, Anthropic, Gemini, local і custom-provider зберігають свою поточну поведінку. ## Виберіть правильний префікс моделі -OpenClaw має окремі маршрути для доступу у форматі OpenAI та Codex: +OpenClaw має окремі маршрути для доступу у формі OpenAI та Codex: -| Посилання на модель | Шлях середовища виконання | Використовуйте, коли | -| -------------------- | ------------------------------------------ | ------------------------------------------------------------------------ | -| `openai/gpt-5.4` | Провайдер OpenAI через обв’язку OpenClaw/PI | Вам потрібен прямий доступ до OpenAI Platform API за допомогою `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.4` | Провайдер OpenAI Codex OAuth через PI | Вам потрібен ChatGPT/Codex OAuth без каркаса app-server Codex. | -| `codex/gpt-5.4` | Комплектний провайдер Codex плюс каркас Codex | Вам потрібне нативне виконання через app-server Codex для вбудованого ходу агента. | +| Посилання на модель | Шлях runtime | Використовуйте, коли | +| -------------------- | -------------------------------------------- | ----------------------------------------------------------------------- | +| `openai/gpt-5.4` | Провайдер OpenAI через інфраструктуру OpenClaw/PI | Вам потрібен прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.4` | Провайдер OpenAI Codex OAuth через PI | Вам потрібен ChatGPT/Codex OAuth без harness app-server Codex. | +| `codex/gpt-5.4` | Комплектний провайдер Codex плюс harness Codex | Вам потрібне нативне виконання app-server Codex для вбудованого ходу агента. | -Каркас Codex обробляє лише посилання на моделі `codex/*`. Наявні посилання `openai/*`, +Harness Codex працює лише з посиланнями на моделі `codex/*`. Наявні посилання `openai/*`, `openai-codex/*`, Anthropic, Gemini, xAI, local і custom provider зберігають свої звичайні шляхи. ## Вимоги - OpenClaw із доступним комплектним plugin `codex`. -- app-server Codex версії `0.118.0` або новішої. +- Codex app-server `0.118.0` або новіший. - Автентифікація Codex, доступна процесу app-server. -Plugin блокує старіші або безверсійні рукостискання app-server. Це гарантує, що -OpenClaw працює в межах поверхні протоколу, з якою його було протестовано. +Plugin блокує старіші або неверсіоновані handshake app-server. Це утримує +OpenClaw у межах поверхні протоколу, з якою його було протестовано. -Для live- і Docker-smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також -за потреби з файлів CLI Codex, таких як `~/.codex/auth.json` і -`~/.codex/config.toml`. Використовуйте ті самі матеріали автентифікації, що й ваш локальний -app-server Codex. +Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також із +необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і +`~/.codex/config.toml`. Використовуйте ті самі матеріали автентифікації, які застосовує +ваш локальний app-server Codex. ## Мінімальна конфігурація -Використайте `codex/gpt-5.4`, увімкніть комплектний plugin і примусово задайте каркас `codex`: +Використайте `codex/gpt-5.4`, увімкніть комплектний plugin і примусово задайте harness `codex`: ```json5 { @@ -87,7 +91,7 @@ app-server Codex. } ``` -Якщо у вашій конфігурації використовується `plugins.allow`, також додайте туди `codex`: +Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди також `codex`: ```json5 { @@ -103,12 +107,12 @@ app-server Codex. ``` Установлення `agents.defaults.model` або моделі агента в `codex/` також -автоматично вмикає комплектний plugin `codex`. Явний запис plugin усе одно +автоматично вмикає комплектний plugin `codex`. Явний запис plugin усе ще корисний у спільних конфігураціях, бо робить намір розгортання очевидним. ## Додайте Codex без заміни інших моделей -Залиште `runtime: "auto"`, якщо хочете використовувати Codex для моделей `codex/*` і PI для +Залишайте `runtime: "auto"`, якщо хочете використовувати Codex для моделей `codex/*`, а PI — для всього іншого: ```json5 @@ -141,17 +145,17 @@ app-server Codex. } ``` -З такою структурою: +За такої конфігурації: -- `/model codex` або `/model codex/gpt-5.4` використовує каркас app-server Codex. +- `/model codex` або `/model codex/gpt-5.4` використовує harness app-server Codex. - `/model gpt` або `/model openai/gpt-5.4` використовує шлях провайдера OpenAI. - `/model opus` використовує шлях провайдера Anthropic. -- Якщо вибрано не-Codex модель, PI залишається каркасом сумісності. +- Якщо вибрано не-Codex модель, PI залишається harness сумісності. ## Розгортання лише з Codex -Вимкніть резервний перехід на PI, якщо вам потрібно довести, що кожен вбудований хід агента -використовує каркас Codex: +Вимкніть резервний перехід на PI, якщо потрібно підтвердити, що кожен вбудований хід агента використовує +harness Codex: ```json5 { @@ -167,7 +171,7 @@ app-server Codex. } ``` -Перевизначення через середовище: +Перевизначення через змінні середовища: ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -175,13 +179,13 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -За вимкненого fallback OpenClaw завершується з помилкою на ранньому етапі, якщо plugin Codex вимкнено, -потрібна модель не є посиланням `codex/*`, app-server занадто старий або +Коли резервний перехід вимкнено, OpenClaw завершує роботу на ранньому етапі, якщо plugin Codex вимкнено, +потрібна модель не є посиланням `codex/*`, app-server надто старий або app-server не може запуститися. ## Codex для окремого агента -Ви можете зробити один агент лише-Codex, тоді як типовий агент зберігатиме звичайний +Ви можете зробити одного агента лише з Codex, тоді як агент за замовчуванням зберігатиме звичайний автовибір: ```json5 @@ -213,14 +217,14 @@ app-server не може запуститися. } ``` -Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову -сесію OpenClaw, а каркас Codex за потреби створює або відновлює свій sidecar-потік app-server. -`/reset` очищає прив’язку сесії OpenClaw для цього потоку. +Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову +сесію OpenClaw, а harness Codex створює або відновлює свій sidecar app-server +потік за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього потоку. ## Виявлення моделей -Типово plugin Codex запитує app-server про доступні моделі. Якщо -виявлення не вдається або перевищує час очікування, він використовує комплектний резервний каталог: +За замовчуванням plugin Codex запитує app-server про доступні моделі. Якщо +виявлення завершується помилкою або перевищує час очікування, він використовує комплектний резервний каталог: - `codex/gpt-5.4` - `codex/gpt-5.4-mini` @@ -246,8 +250,8 @@ app-server не може запуститися. } ``` -Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалося зондування Codex і -використовувався резервний каталог: +Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалося опитування Codex і використовувався +лише резервний каталог: ```json5 { @@ -266,20 +270,22 @@ app-server не може запуститися. } ``` -## З’єднання app-server і політика +## Підключення app-server і політика -Типово plugin локально запускає Codex так: +За замовчуванням plugin запускає Codex локально за допомогою: ```bash codex app-server --listen stdio:// ``` -Типово OpenClaw запускає локальні сесії каркаса Codex повністю без обмежень: -`approvalPolicy: "never"` і `sandbox: "danger-full-access"`. Це відповідає -позиції довіреного локального оператора, яку використовує CLI Codex, і дозволяє автономним -Heartbeat використовувати мережеві та shell-інструменти без очікування на невидимий нативний -шлях погодження. Ви можете посилити цю політику, наприклад, спрямовуючи перевірки -через guardian: +За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO: +`approvalPolicy: "never"`, `approvalsReviewer: "user"` і +`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, яка використовується +для автономних Heartbeat: Codex може користуватися shell- та network-інструментами без +зупинки на нативних запитах погодження, на які нікому відповідати. + +Щоб увімкнути погодження Codex із перевіркою Guardian, задайте `appServer.mode: +"guardian"`: ```json5 { @@ -289,9 +295,7 @@ Heartbeat використовувати мережеві та shell-інстр enabled: true, config: { appServer: { - approvalPolicy: "untrusted", - approvalsReviewer: "guardian_subagent", - sandbox: "workspace-write", + mode: "guardian", serviceTier: "priority", }, }, @@ -301,7 +305,46 @@ Heartbeat використовувати мережеві та shell-інстр } ``` -Для app-server, який уже працює, використовуйте транспорт WebSocket: +Режим Guardian розгортається до: + +```json5 +{ + plugins: { + entries: { + codex: { + enabled: true, + config: { + appServer: { + mode: "guardian", + approvalPolicy: "on-request", + approvalsReviewer: "guardian_subagent", + sandbox: "workspace-write", + }, + }, + }, + }, + }, +} +``` + +Guardian — це нативний рецензент погоджень Codex. Коли Codex просить вийти за межі +sandbox, записати поза межами workspace або додати дозволи, такі як доступ до мережі, +Codex спрямовує цей запит на погодження до підлеглого агента-рецензента, а не до підказки людині. +Рецензент збирає контекст і застосовує рамки оцінки ризиків Codex, а потім +схвалює або відхиляє конкретний запит. Guardian корисний, коли вам потрібно більше +запобіжників, ніж у режимі YOLO, але водночас потрібно, щоб агенти та Heartbeat без нагляду +могли просуватися далі. + +Docker live harness містить перевірку Guardian, коли +`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`. Він запускає harness Codex у +режимі Guardian, перевіряє, що безпечну shell-команду з підвищеними правами схвалено, і +перевіряє, що вивантаження фальшивого секрету до ненадійного зовнішнього призначення відхилено, +щоб агент повернувся із запитом на явне погодження. + +Окремі поля політики все одно мають пріоритет над `mode`, тож розширені розгортання можуть +поєднувати цей preset із явними параметрами. + +Для уже запущеного app-server використовуйте транспорт WebSocket: ```json5 { @@ -325,34 +368,39 @@ Heartbeat використовувати мережеві та shell-інстр Підтримувані поля `appServer`: -| Поле | Типове значення | Значення | -| ------------------- | ----------------------------------------- | ------------------------------------------------------------------------ | -| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | -| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | -| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | -| `url` | не задано | URL WebSocket app-server. | -| `authToken` | не задано | Bearer-токен для транспорту WebSocket. | -| `headers` | `{}` | Додаткові заголовки WebSocket. | -| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control-plane app-server. | -| `approvalPolicy` | `"never"` | Нативна політика погодження Codex, що надсилається під час start/resume/turn потоку. | -| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час start/resume потоку. | -| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб guardian Codex перевіряв нативні погодження. | -| `serviceTier` | не задано | Необов’язковий рівень сервісу Codex, наприклад `"priority"`. | +| Поле | За замовчуванням | Значення | +| ------------------- | ---------------------------------------- | --------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | +| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | +| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | +| `url` | не задано | URL app-server WebSocket. | +| `authToken` | не задано | Bearer-токен для транспорту WebSocket. | +| `headers` | `{}` | Додаткові заголовки WebSocket. | +| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control-plane до app-server. | +| `mode` | `"yolo"` | Preset для виконання YOLO або з перевіркою Guardian. | +| `approvalPolicy` | `"never"` | Нативна політика погоджень Codex, що передається під час start/resume/turn потоку. | +| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що передається під час start/resume. | +| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дозволити Codex Guardian перевіряти підказки. | +| `serviceTier` | не задано | Необов’язковий рівень сервісу Codex, наприклад `"priority"`. | -Старі змінні середовища все ще працюють як резервні варіанти для локального тестування, коли +Старіші змінні середовища все ще працюють як резервні варіанти для локального тестування, коли відповідне поле конфігурації не задано: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` +- `OPENCLAW_CODEX_APP_SERVER_MODE=yolo|guardian` - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -- `OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` -Для відтворюваних розгортань краще використовувати конфігурацію. +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` видалено. Натомість використовуйте +`plugins.entries.codex.config.appServer.mode: "guardian"` або +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Конфігурація є +бажаною для відтворюваних розгортань, бо зберігає поведінку plugin у тому самому +перевіреному файлі, що й решту налаштувань harness Codex. ## Поширені рецепти -Локальний Codex зі стандартним транспортом stdio: +Локальний Codex із транспортом stdio за замовчуванням: ```json5 { @@ -366,7 +414,7 @@ Heartbeat використовувати мережеві та shell-інстр } ``` -Перевірка каркаса лише-Codex із вимкненим резервним переходом на PI: +Перевірка harness лише з Codex, із вимкненим резервним переходом на PI: ```json5 { @@ -383,7 +431,7 @@ Heartbeat використовувати мережеві та shell-інстр } ``` -Погодження Codex, перевірені guardian: +Погодження Codex із перевіркою Guardian: ```json5 { @@ -393,6 +441,7 @@ Heartbeat використовувати мережеві та shell-інстр enabled: true, config: { appServer: { + mode: "guardian", approvalPolicy: "on-request", approvalsReviewer: "guardian_subagent", sandbox: "workspace-write", @@ -427,87 +476,87 @@ Heartbeat використовувати мережеві та shell-інстр } ``` -Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw прив’язано -до наявного потоку Codex, наступний хід знову надсилає в app-server поточну вибрану -модель `codex/*`, провайдера, політику погодження, sandbox і рівень сервісу. -Перемикання з `codex/gpt-5.4` на `codex/gpt-5.2` зберігає прив’язку потоку, але просить Codex -продовжити роботу з новою вибраною моделлю. +Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw приєднано +до наявного потоку Codex, наступний хід знову надсилає до +app-server поточні вибрані `codex/*` модель, провайдера, політику погоджень, sandbox і +рівень сервісу. Перемикання з `codex/gpt-5.4` на `codex/gpt-5.2` зберігає +прив’язку до потоку, але просить Codex продовжити з новою вибраною моделлю. ## Команда Codex -Комплектний plugin реєструє `/codex` як авторизовану slash-команду. Вона -є загальною і працює в будь-якому каналі, який підтримує текстові команди OpenClaw. +Комплектний plugin реєструє `/codex` як авторизовану slash-команду. Вона є +узагальненою і працює на будь-якому каналі, що підтримує текстові команди OpenClaw. Поширені форми: -- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та Skills. -- `/codex models` виводить список живих моделей app-server Codex. -- `/codex threads [filter]` виводить список нещодавніх потоків Codex. -- `/codex resume ` прив’язує поточну сесію OpenClaw до наявного потоку Codex. -- `/codex compact` просить app-server Codex виконати Compaction для прив’язаного потоку. -- `/codex review` запускає нативну перевірку Codex для прив’язаного потоку. -- `/codex account` показує стан облікового запису та лімітів швидкості. -- `/codex mcp` виводить стан MCP-сервера app-server Codex. -- `/codex skills` виводить Skills app-server Codex. +- `/codex status` показує поточне підключення до app-server, моделі, обліковий запис, ліміти швидкості, сервери MCP і skills. +- `/codex models` показує список поточних моделей app-server Codex. +- `/codex threads [filter]` показує список недавніх потоків Codex. +- `/codex resume ` приєднує поточну сесію OpenClaw до наявного потоку Codex. +- `/codex compact` просить app-server Codex виконати Compaction приєднаного потоку. +- `/codex review` запускає нативний review Codex для приєднаного потоку. +- `/codex account` показує стан облікового запису й лімітів швидкості. +- `/codex mcp` показує стан серверів MCP app-server Codex. +- `/codex skills` показує Skills app-server Codex. -`/codex resume` записує той самий sidecar-файл прив’язки, який каркас використовує для -звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає -поточну вибрану в OpenClaw модель `codex/*` в app-server і зберігає ввімкненою +`/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для +звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає поточну +вибрану модель OpenClaw `codex/*` до app-server і зберігає увімкнену розширену історію. -Поверхня команд вимагає app-server Codex версії `0.118.0` або новішої. Окремі -методи керування позначаються як `unsupported by this Codex app-server`, якщо -майбутній або кастомний app-server не надає цей JSON-RPC-метод. +Поверхня команд вимагає Codex app-server `0.118.0` або новішої версії. Про окремі +методи керування повідомляється як `unsupported by this Codex app-server`, якщо +майбутній або кастомний app-server не надає цей метод JSON-RPC. ## Інструменти, медіа та Compaction -Каркас Codex змінює лише низькорівневий виконавець вбудованого агента. +Harness Codex змінює лише низькорівневий виконавець вбудованого агента. -OpenClaw і далі формує список інструментів і отримує динамічні результати інструментів із -каркаса. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів повідомлень -і далі проходять через звичайний шлях доставки OpenClaw. +OpenClaw, як і раніше, формує список інструментів і отримує динамічні результати інструментів від +harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів повідомлень +і далі проходять через звичайний шлях доставлення OpenClaw. -Коли вибрана модель використовує каркас Codex, нативна Compaction потоку -делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, -пошуку, `/new`, `/reset` і майбутнього перемикання моделей або каркасів. Дзеркало -включає prompt користувача, фінальний текст асистента та полегшені записи міркувань -або плану Codex, коли їх видає app-server. Наразі OpenClaw записує лише сигнали -початку та завершення нативної Compaction. Він ще не показує людинозрозумілий -підсумок Compaction або придатний для аудиту список записів, які Codex -залишив після Compaction. +Коли вибрана модель використовує harness Codex, нативна Compaction потоку +делегується app-server Codex. OpenClaw зберігає дзеркало стенограми для історії каналу, +пошуку, `/new`, `/reset` і майбутнього перемикання моделей або harness. Дзеркало +містить підказку користувача, фінальний текст помічника та полегшені записи міркувань або плану Codex, +коли їх надсилає app-server. Наразі OpenClaw записує лише сигнали початку й завершення +нативної Compaction. Він поки що не надає +людинозрозумілого підсумку Compaction або придатного до аудиту списку того, які записи Codex +зберіг після Compaction. -Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і -розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, як-от +Генерація медіа не потребує PI. Зображення, відео, музика, PDF, TTS і розуміння медіа +і далі використовують відповідні налаштування провайдера/моделі, такі як `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. -## Усунення неполадок +## Усунення проблем **Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`, задайте посилання на модель `codex/*` або перевірте, чи `plugins.allow` не виключає `codex`. -**OpenClaw використовує PI замість Codex:** якщо жоден каркас Codex не обробляє запуск, -OpenClaw може використовувати PI як backend сумісності. Установіть +**OpenClaw використовує PI замість Codex:** якщо жоден harness Codex не обробляє запуск, +OpenClaw може використовувати PI як backend сумісності. Задайте `embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування, або -`embeddedHarness.fallback: "none"`, щоб завершуватися з помилкою, коли жоден plugin-каркас не підходить. Щойно -вибрано app-server Codex, його помилки передаються безпосередньо без додаткової -конфігурації fallback. +`embeddedHarness.fallback: "none"`, щоб завершуватися з помилкою, коли жоден plugin harness не підходить. Щойно +вибрано app-server Codex, його збої відображаються безпосередньо без додаткової +конфігурації резервного переходу. -**app-server відхиляється:** оновіть Codex, щоб рукостискання app-server -повідомляло версію `0.118.0` або новішу. +**app-server відхиляється:** оновіть Codex, щоб handshake app-server +повідомляв версію `0.118.0` або новішу. **Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. -**Транспорт WebSocket одразу завершується з помилкою:** перевірте `appServer.url`, `authToken` -і чи віддалений app-server використовує ту саму версію протоколу app-server Codex. +**Транспорт WebSocket відразу завершується помилкою:** перевірте `appServer.url`, `authToken` +і те, що віддалений app-server використовує ту саму версію протоколу app-server Codex. -**Не-Codex модель використовує PI:** це очікувана поведінка. Каркас Codex обробляє лише -посилання на моделі `codex/*`. +**Не-Codex модель використовує PI:** це очікувано. Harness Codex працює лише з +посиланнями на моделі `codex/*`. ## Пов’язане -- [Plugins каркаса агента](/uk/plugins/sdk-agent-harness) +- [Plugin-и harness агента](/uk/plugins/sdk-agent-harness) - [Провайдери моделей](/uk/concepts/model-providers) - [Довідник із конфігурації](/uk/gateway/configuration-reference) - [Тестування](/uk/help/testing#live-codex-app-server-harness-smoke) diff --git a/docs/uk/plugins/sdk-agent-harness.md b/docs/uk/plugins/sdk-agent-harness.md index cc58de986..6e0cfc3a3 100644 --- a/docs/uk/plugins/sdk-agent-harness.md +++ b/docs/uk/plugins/sdk-agent-harness.md @@ -1,51 +1,51 @@ --- read_when: - - Ви змінюєте вбудоване середовище виконання агента або реєстр обв’язки агента + - Ви змінюєте вбудоване середовище виконання агента або реєстр обв’язок агента - Ви реєструєте обв’язку агента з bundled або trusted plugin - Вам потрібно зрозуміти, як plugin Codex пов’язаний із постачальниками моделей sidebarTitle: Agent Harness -summary: Експериментальна поверхня SDK для plugin, які замінюють низькорівневий вбудований виконавець агента -title: Plugin обв’язки агента +summary: Експериментальна поверхня SDK для plugins, які замінюють низькорівневий вбудований виконавець агента +title: Plugins обв’язки агента x-i18n: - generated_at: "2026-04-22T05:35:02Z" + generated_at: "2026-04-22T23:30:48Z" model: gpt-5.4 provider: openai - source_hash: 728fef59ae3cce29a3348842820f1f71a2eac98ae6b276179bce6c85d16613df + source_hash: efaecca18210af0e9e641bd888c1edb55e08e96299158ff021d6c2dd0218ec25 source_path: plugins/sdk-agent-harness.md workflow: 15 --- -# Plugin обв’язки агента +# Plugins обв’язки агента **Обв’язка агента** — це низькорівневий виконавець одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. -Використовуйте цю поверхню лише для bundled або trusted native plugin. Контракт усе ще експериментальний, оскільки типи параметрів навмисно віддзеркалюють поточний вбудований виконавець. +Використовуйте цю поверхню лише для bundled або trusted native plugins. Контракт усе ще експериментальний, тому що типи параметрів навмисно віддзеркалюють поточний вбудований виконавець. ## Коли використовувати обв’язку -Реєструйте обв’язку агента, коли сімейство моделей має власне native середовище виконання сесії і звичайний транспорт постачальника OpenClaw є хибною абстракцією. +Реєструйте обв’язку агента, коли сімейство моделей має власне native session runtime і звичайний транспорт постачальника OpenClaw є хибною абстракцією. Приклади: -- native сервер coding-agent, який керує потоками та Compaction -- локальний CLI або демон, який має транслювати native події плану/міркувань/інструментів +- native server кодувального агента, який керує потоками та Compaction +- локальний CLI або демон, який має потоково передавати native plan/reasoning/tool events - середовище виконання моделі, якому потрібен власний resume id на додачу до транскрипту сесії OpenClaw -**Не** реєструйте обв’язку лише для того, щоб додати новий API LLM. Для звичайних HTTP або WebSocket API моделей створіть [plugin постачальника](/uk/plugins/sdk-provider-plugins). +**Не** реєструйте обв’язку лише для додавання нового API LLM. Для звичайних HTTP або WebSocket API моделей створіть [provider plugin](/uk/plugins/sdk-provider-plugins). -## Що все ще належить core +## Чим усе ще керує ядро -Перш ніж буде вибрано обв’язку, OpenClaw уже визначив: +До того, як обв’язка буде вибрана, OpenClaw уже визначив: -- постачальника і модель -- стан auth середовища виконання -- рівень thinking і бюджет контексту +- постачальника й модель +- стан автентифікації середовища виконання +- рівень мислення та бюджет контексту - файл транскрипту/сесії OpenClaw -- workspace, sandbox і політику інструментів -- callback-функції відповіді каналу та callback-функції трансляції -- політику fallback моделі та живого перемикання моделі +- робочий простір, sandbox і політику інструментів +- зворотні виклики відповіді каналу та потокові зворотні виклики +- політику резервної моделі та live-перемикання моделей -Цей поділ є навмисним. Обв’язка виконує підготовлену спробу; вона не вибирає постачальників, не замінює доставку каналу і не перемикає моделі непомітно. +Такий поділ є навмисним. Обв’язка виконує підготовлену спробу; вона не вибирає постачальників, не замінює доставку через канал і не перемикає моделі непомітно. ## Зареєструвати обв’язку @@ -89,45 +89,50 @@ OpenClaw вибирає обв’язку після визначення пос 1. `OPENCLAW_AGENT_RUNTIME=` примусово вибирає зареєстровану обв’язку з цим id. 2. `OPENCLAW_AGENT_RUNTIME=pi` примусово вибирає вбудовану обв’язку PI. -3. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані обв’язки, чи підтримують вони визначеного постачальника/модель. -4. Якщо жодна зареєстрована обв’язка не підходить, OpenClaw використовує PI, якщо fallback до PI не вимкнено. +3. `OPENCLAW_AGENT_RUNTIME=auto` запитує в зареєстрованих обв’язок, чи підтримують вони визначеного постачальника/модель. +4. Якщо жодна зареєстрована обв’язка не підходить, OpenClaw використовує PI, якщо резервний перехід на PI не вимкнено. -Збої обв’язок plugin відображаються як збої виконання. У режимі `auto` fallback до PI використовується лише тоді, коли жодна зареєстрована обв’язка plugin не підтримує визначеного постачальника/модель. Щойно обв’язка plugin заявила про виконання, OpenClaw не повторює той самий хід через PI, оскільки це може змінити семантику auth/середовища виконання або продублювати побічні ефекти. +Збої plugin-обв’язки відображаються як збої виконання. У режимі `auto` резервний перехід на PI використовується лише тоді, коли жодна зареєстрована plugin-обв’язка не підтримує визначеного постачальника/модель. Щойно plugin-обв’язка взяла виконання на себе, OpenClaw не повторює той самий хід через PI, тому що це може змінити семантику автентифікації/середовища виконання або продублювати побічні ефекти. -Bundled plugin Codex реєструє `codex` як свій id обв’язки. Core розглядає це як звичайний id обв’язки plugin; специфічні для Codex псевдоніми мають належати plugin або конфігурації оператора, а не спільному селектору середовища виконання. +Bundled plugin Codex реєструє `codex` як id своєї обв’язки. Ядро розглядає це як звичайний id plugin-обв’язки; специфічні для Codex псевдоніми мають належати plugin або конфігурації оператора, а не спільному селектору середовища виконання. ## Поєднання постачальника й обв’язки -Більшість обв’язок також мають реєструвати постачальника. Постачальник робить посилання на моделі, стан auth, метадані моделі й вибір `/model` видимими для решти OpenClaw. Потім обв’язка заявляє про цей постачальник у `supports(...)`. +Більшість обв’язок також мають реєструвати постачальника. Постачальник робить посилання на моделі, стан автентифікації, метадані моделей і вибір `/model` видимими для решти OpenClaw. Потім обв’язка заявляє про підтримку цього постачальника в `supports(...)`. Bundled plugin Codex дотримується цього шаблону: - id постачальника: `codex` -- посилання користувацьких моделей: `codex/gpt-5.4`, `codex/gpt-5.2` або інша модель, яку повертає сервер застосунку Codex +- посилання користувача на моделі: `codex/gpt-5.4`, `codex/gpt-5.2` або інша модель, повернена Codex app server - id обв’язки: `codex` -- auth: синтетична доступність постачальника, оскільки обв’язка Codex керує native входом/сесією Codex -- запит до app-server: OpenClaw надсилає Codex базовий id моделі й дозволяє обв’язці спілкуватися з native протоколом app-server +- автентифікація: синтетична доступність постачальника, тому що обв’язка Codex керує native login/session Codex +- запит до app-server: OpenClaw надсилає в Codex bare model id і дозволяє обв’язці працювати з native app-server protocol -Plugin Codex є адитивним. Звичайні посилання `openai/gpt-*` залишаються посиланнями постачальника OpenAI і продовжують використовувати звичайний шлях постачальника OpenClaw. Вибирайте `codex/gpt-*`, коли вам потрібні auth під керуванням Codex, виявлення моделей Codex, native потоки та виконання через app-server Codex. `/model` може перемикатися між моделями Codex, які повертає app-server Codex, без потреби в облікових даних постачальника OpenAI. +Plugin Codex є адитивним. Звичайні посилання `openai/gpt-*` лишаються посиланнями постачальника OpenAI й далі використовують звичайний шлях постачальника OpenClaw. Вибирайте `codex/gpt-*`, коли вам потрібні керована Codex автентифікація, виявлення моделей Codex, native threads і виконання через Codex app-server. `/model` може перемикатися між моделями Codex, які повертає Codex app server, без потреби в облікових даних постачальника OpenAI. -Щоб дізнатися про налаштування оператора, приклади префіксів моделей і конфігурації лише для Codex, див. [Обв’язка Codex](/uk/plugins/codex-harness). +Щоб дізнатися про налаштування для операторів, приклади префіксів моделей і конфігурації лише для Codex, див. [Codex Harness](/uk/plugins/codex-harness). -OpenClaw вимагає Codex app-server `0.118.0` або новішої версії. Plugin Codex перевіряє initialize handshake app-server і блокує старіші або неверсіоновані сервери, щоб OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано. +OpenClaw вимагає Codex app-server `0.118.0` або новішої версії. Plugin Codex перевіряє initialize handshake app-server і блокує старіші сервери або сервери без версії, щоб OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано. + +### Middleware tool-result Codex app-server + +Bundled plugins також можуть підключати middleware `tool_result`, специфічний для Codex app-server, через `api.registerCodexAppServerExtensionFactory(...)`, коли їхній manifest оголошує `contracts.embeddedExtensionFactories: ["codex-app-server"]`. +Це seam trusted-plugin для асинхронних перетворень tool-result, які мають виконуватися всередині native обв’язки Codex до того, як вивід інструмента буде спроєктовано назад у транскрипт OpenClaw. ### Режим native обв’язки Codex -Bundled обв’язка `codex` — це native режим Codex для вбудованих ходів агента OpenClaw. Спочатку увімкніть bundled plugin `codex` і додайте `codex` у `plugins.allow`, якщо ваша конфігурація використовує обмежувальний allowlist. Він відрізняється від `openai-codex/*`: +Bundled обв’язка `codex` — це native режим Codex для вбудованих ходів агента OpenClaw. Спочатку ввімкніть bundled plugin `codex` і додайте `codex` до `plugins.allow`, якщо у вашій конфігурації використовується обмежувальний allowlist. Це відрізняється від `openai-codex/*`: - `openai-codex/*` використовує OAuth ChatGPT/Codex через звичайний шлях постачальника OpenClaw. -- `codex/*` використовує bundled постачальник Codex і маршрутизує хід через app-server Codex. +- `codex/*` використовує bundled постачальника Codex і маршрутизує хід через Codex app-server. -Коли цей режим працює, Codex керує native id потоку, поведінкою resume, Compaction і виконанням app-server. OpenClaw усе ще керує каналом чату, видимим дзеркалом транскрипту, політикою інструментів, схваленнями, доставкою медіа та вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із `embeddedHarness.fallback: "none"`, коли вам потрібно довести, що лише шлях app-server Codex може заявити про виконання. Ця конфігурація є лише захистом вибору: збої app-server Codex і так завершуються помилкою напряму, а не повторною спробою через PI. +Коли цей режим виконується, Codex керує native thread id, поведінкою resume, Compaction і виконанням app-server. OpenClaw усе ще керує каналом чату, видимим дзеркалом транскрипту, політикою інструментів, підтвердженнями, доставкою медіа та вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із `embeddedHarness.fallback: "none"`, коли вам потрібно довести, що лише шлях Codex app-server може взяти виконання на себе. Ця конфігурація є лише захистом вибору: збої Codex app-server уже напряму завершуються помилкою замість повторної спроби через PI. -## Вимкнути fallback до PI +## Вимкнути резервний перехід на PI -За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, встановленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані обв’язки plugin можуть заявляти про пару постачальник/модель. Якщо жодна не підходить, OpenClaw повертається до PI. +За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, встановленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані plugin-обв’язки можуть взяти на себе пару постачальник/модель. Якщо жодна не підходить, OpenClaw переходить на PI. -Установіть `fallback: "none"`, коли вам потрібно, щоб відсутність вибору обв’язки plugin завершувалася помилкою замість використання PI. Збої вже вибраних обв’язок plugin і так призводять до жорсткої помилки. Це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. +Установіть `fallback: "none"`, коли вам потрібно, щоб відсутність вибору plugin-обв’язки завершувалася помилкою замість використання PI. Збої вже вибраних plugin-обв’язок і так завершуються жорсткою помилкою. Це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. Для вбудованих запусків лише з Codex: @@ -145,7 +150,7 @@ Bundled обв’язка `codex` — це native режим Codex для вбу } ``` -Якщо ви хочете, щоб будь-яка зареєстрована обв’язка plugin могла заявляти про відповідні моделі, але ніколи не хочете, щоб OpenClaw непомітно повертався до PI, залиште `runtime: "auto"` і вимкніть fallback: +Якщо ви хочете, щоб будь-яка зареєстрована plugin-обв’язка брала на себе відповідні моделі, але ніколи не хочете, щоб OpenClaw непомітно переходив на PI, залиште `runtime: "auto"` і вимкніть резервний перехід: ```json { @@ -185,7 +190,7 @@ Bundled обв’язка `codex` — це native режим Codex для вбу } ``` -`OPENCLAW_AGENT_RUNTIME` усе ще перевизначає налаштоване середовище виконання. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback до PI з оточення. +`OPENCLAW_AGENT_RUNTIME` усе ще перевизначає налаштоване середовище виконання. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід на PI через середовище. ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -193,39 +198,41 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Якщо fallback вимкнено, сесія завершується помилкою рано, коли запитана обв’язка не зареєстрована, не підтримує визначеного постачальника/модель або завершується помилкою до створення побічних ефектів ходу. Це зроблено навмисно для розгортань лише з Codex і для live-тестів, які мають довести, що шлях app-server Codex справді використовується. +Якщо резервний перехід вимкнено, сесія завершується помилкою рано, коли запитана обв’язка не зареєстрована, не підтримує визначеного постачальника/модель або завершується помилкою до створення побічних ефектів ходу. Це навмисно для розгортань лише з Codex і для live-тестів, які мають довести, що шлях Codex app-server справді використовується. -Це налаштування керує лише вбудованою обв’язкою агента. Воно не вимикає маршрутизацію моделей постачальників для image, video, music, TTS, PDF або інших специфічних для постачальника типів. +Цей параметр керує лише вбудованою обв’язкою агента. Він не вимикає маршрутизацію image, video, music, TTS, PDF або іншої модельної маршрутизації, специфічної для постачальника. -## Native сесії та дзеркало транскрипту +## Native sessions і дзеркало транскрипту -Обв’язка може зберігати native id сесії, id потоку або токен resume на боці демона. Явно пов’язуйте цю прив’язку із сесією OpenClaw і продовжуйте віддзеркалювати видимий для користувача вивід assistant/tool у транскрипт OpenClaw. +Обв’язка може зберігати native session id, thread id або daemon-side resume token. +Явно зберігайте цю прив’язку пов’язаною із сесією OpenClaw і продовжуйте дзеркалити видимий користувачеві вивід assistant/tool у транскрипт OpenClaw. Транскрипт OpenClaw залишається шаром сумісності для: - видимої в каналі історії сесії -- пошуку та індексації транскрипту -- повернення до вбудованої обв’язки PI на пізнішому ході -- узагальненої поведінки `/new`, `/reset` і видалення сесії +- пошуку та індексації транскриптів +- перемикання назад на вбудовану обв’язку PI на наступному ході +- загальної поведінки `/new`, `/reset` і видалення сесії -Якщо ваша обв’язка зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг очистити її, коли пов’язану сесію OpenClaw скинуто. +Якщо ваша обв’язка зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг очистити її, коли пов’язану сесію OpenClaw буде скинуто. ## Результати інструментів і медіа -Core формує список інструментів OpenClaw і передає його в підготовлену спробу. Коли обв’язка виконує динамічний виклик інструмента, повертайте результат інструмента назад через форму результату обв’язки замість того, щоб самостійно надсилати медіа в канал. +Ядро створює список інструментів OpenClaw і передає його в підготовлену спробу. +Коли обв’язка виконує dynamic tool call, поверніть результат інструмента назад через форму результату обв’язки замість самостійного надсилання канального медіа. -Це зберігає text, image, video, music, TTS, approval і виводи інструментів обміну повідомленнями на тому самому шляху доставки, що й для запусків на базі PI. +Це зберігає text, image, video, music, TTS, approval і виводи messaging-tool на тому самому шляху доставки, що й у запусків на базі PI. ## Поточні обмеження -- Публічний шлях імпорту є узагальненим, але деякі псевдоніми типів спроб/результатів усе ще містять назви `Pi` заради сумісності. -- Встановлення сторонніх обв’язок є експериментальним. Надавайте перевагу plugin постачальників, доки вам не знадобиться native середовище виконання сесії. -- Перемикання обв’язок між ходами підтримується. Не перемикайте обв’язки посеред ходу після того, як уже почалися native інструменти, схвалення, текст assistant або надсилання повідомлень. +- Публічний шлях імпорту є загальним, але деякі псевдоніми типів attempt/result усе ще містять назви `Pi` для сумісності. +- Встановлення сторонніх обв’язок є експериментальним. Віддавайте перевагу provider plugins, доки вам не знадобиться native session runtime. +- Перемикання обв’язок між ходами підтримується. Не перемикайте обв’язки посеред ходу після того, як уже почалися native tools, approvals, текст assistant або надсилання повідомлень. ## Пов’язане - [Огляд SDK](/uk/plugins/sdk-overview) -- [Runtime Helpers](/uk/plugins/sdk-runtime) -- [Plugin постачальника](/uk/plugins/sdk-provider-plugins) -- [Обв’язка Codex](/uk/plugins/codex-harness) +- [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime) +- [Provider Plugins](/uk/plugins/sdk-provider-plugins) +- [Codex Harness](/uk/plugins/codex-harness) - [Постачальники моделей](/uk/concepts/model-providers)