diff --git a/docs/uk/ci.md b/docs/uk/ci.md index a1d4f5078..c2787f123 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,76 +1,77 @@ --- read_when: - Вам потрібно зрозуміти, чому завдання CI запустилося або не запустилося - - Ви налагоджуєте перевірки GitHub Actions, що завершуються з помилкою -summary: Граф завдань CI, перевірки за охопленням і локальні еквіваленти команд + - Ви налагоджуєте збої перевірок GitHub Actions +summary: Граф завдань CI, обмежувальні перевірки за областю змін і локальні еквіваленти команд title: Конвеєр CI x-i18n: - generated_at: "2026-04-20T12:57:36Z" + generated_at: "2026-04-20T14:13:25Z" model: gpt-5.4 provider: openai - source_hash: b128a0112dbaa6449b4f2ace018939f552f99929044732d18d5bea8b46695815 + source_hash: dd4ffb6986739ee6f4fca6e8b1f40baee7e47a8387e8d06c722881ebe78b4766 source_path: ci.md workflow: 15 --- # Конвеєр CI -CI запускається для кожного push у `main` і для кожного pull request. Він використовує розумне визначення охоплення, щоб пропускати дорогі завдання, коли змінювалися лише не пов’язані ділянки. +CI запускається для кожного push до `main` і для кожного pull request. Він використовує розумне обмеження за областю змін, щоб пропускати дорогі завдання, коли змінено лише непов’язані частини. ## Огляд завдань -| Завдання | Призначення | Коли запускається | -| ------------------------ | -------------------------------------------------------------------------------------- | ----------------------------------- | -| `preflight` | Визначає зміни лише в документації, змінені охоплення, змінені розширення та збирає маніфест CI | Завжди для push і PR, що не є draft | -| `security-fast` | Виявлення приватних ключів, аудит workflow через `zizmor`, аудит production-залежностей | Завжди для push і PR, що не є draft | -| `build-artifacts` | Збирає `dist/` і Control UI один раз, завантажує повторно використовувані артефакти для наступних завдань | Зміни, релевантні для Node | -| `checks-fast-core` | Швидкі Linux-етапи перевірки коректності, як-от bundled/plugin-contract/protocol checks | Зміни, релевантні для Node | -| `checks-node-extensions` | Повні шарди тестів bundled-plugin для набору розширень | Зміни, релевантні для Node | -| `checks-node-core-test` | Шарди тестів core Node, за винятком channel-, bundled-, contract- і extension-етапів | Зміни, релевантні для Node | -| `extension-fast` | Цільові тести лише для змінених bundled plugins | Коли виявлено зміни розширень | -| `check` | Основний локальний gate у CI: `pnpm check` плюс `pnpm build:strict-smoke` | Зміни, релевантні для Node | -| `check-additional` | Захисти архітектури, меж, циклів імпорту плюс regression harness для gateway watch | Зміни, релевантні для Node | -| `build-smoke` | Smoke-тести зібраного CLI та smoke-тест пам’яті під час запуску | Зміни, релевантні для Node | -| `checks` | Решта Linux Node-етапів: тести каналів і сумісність Node 22 лише для push | Зміни, релевантні для Node | -| `check-docs` | Форматування документації, lint і перевірки битих посилань | Документацію змінено | -| `skills-python` | Ruff + pytest для Skills на основі Python | Зміни, релевантні для Python Skills | -| `checks-windows` | Специфічні для Windows етапи тестування | Зміни, релевантні для Windows | -| `macos-node` | Етап тестів TypeScript на macOS із використанням спільних зібраних артефактів | Зміни, релевантні для macOS | -| `macos-swift` | Lint, збірка й тести Swift для застосунку macOS | Зміни, релевантні для macOS | -| `android` | Матриця збірки й тестування Android | Зміни, релевантні для Android | +| Завдання | Призначення | Коли запускається | +| ------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------ | +| `preflight` | Визначає зміни лише в документації, змінені області, змінені розширення та збирає маніфест CI | Завжди для push і PR, що не є draft | +| `security-fast` | Виявлення приватних ключів, аудит workflow через `zizmor`, аудит production-залежностей | Завжди для push і PR, що не є draft | +| `build-artifacts` | Збирає `dist/` і Control UI один раз, завантажує повторно використовувані артефакти для downstream-завдань | Зміни, релевантні для Node | +| `checks-fast-core` | Швидкі Linux-перевірки коректності, як-от bundled/plugin-contract/protocol checks | Зміни, релевантні для Node | +| `checks-node-extensions` | Повні шарди тестів bundled-plugin для всього набору розширень | Зміни, релевантні для Node | +| `checks-node-core-test` | Шарди основних Node-тестів, без channel, bundled, contract і extension-ланів | Зміни, релевантні для Node | +| `extension-fast` | Сфокусовані тести лише для змінених bundled plugins | Коли виявлено зміни розширень | +| `check` | Основна локальна перевірка в CI: `pnpm check`, `pnpm check:test-types` і `pnpm build:strict-smoke` | Зміни, релевантні для Node | +| `check-additional` | Перевірки архітектури, меж, циклів імпорту, а також regression harness для gateway watch | Зміни, релевантні для Node | +| `build-smoke` | Smoke-тести зібраного CLI та smoke-тест пам’яті під час запуску | Зміни, релевантні для Node | +| `checks` | Решта Linux Node-ланів: channel-тести та сумісність лише для push з Node 22 | Зміни, релевантні для Node | +| `check-docs` | Форматування документації, lint і перевірки битих посилань | Документацію змінено | +| `skills-python` | Ruff + pytest для Skills на Python | Зміни, релевантні для Python Skills | +| `checks-windows` | Специфічні для Windows тестові лани | Зміни, релевантні для Windows | +| `macos-node` | Лан тестів TypeScript на macOS із використанням спільних зібраних артефактів | Зміни, релевантні для macOS | +| `macos-swift` | Swift lint, збірка та тести для застосунку macOS | Зміни, релевантні для macOS | +| `android` | Матриця збірки й тестів Android | Зміни, релевантні для Android | ## Порядок Fail-Fast Завдання впорядковані так, щоб дешеві перевірки завершувалися з помилкою раніше, ніж запустяться дорогі: -1. `preflight` визначає, які етапи взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. -2. `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко завершуються з помилкою, не чекаючи важчих завдань із артефактами та платформними матрицями. -3. `build-artifacts` виконується паралельно зі швидкими Linux-етапами, щоб наступні споживачі могли почати роботу, щойно буде готова спільна збірка. -4. Після цього розгалужуються важчі платформні та runtime-етапи: `checks-fast-core`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. +1. `preflight` вирішує, які лани взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. +2. `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко завершуються з помилкою, не чекаючи важчих завдань з артефактами та матрицями платформ. +3. `build-artifacts` виконується паралельно зі швидкими Linux-ланами, щоб downstream-споживачі могли почати роботу, щойно буде готова спільна збірка. +4. Після цього розгалужуються важчі платформні та runtime-лани: `checks-fast-core`, `checks-node-extensions`, `checks-node-core-test`, `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. -Логіка охоплення розташована в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`. -Окремий workflow `install-smoke` повторно використовує той самий скрипт охоплення через власне завдання `preflight`. Він обчислює `run_install_smoke` із вужчого сигналу changed-smoke, тому Docker/install smoke запускається лише для змін, пов’язаних із встановленням, пакуванням і контейнерами. +Логіка обмеження за областю змін знаходиться в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`. +Окремий workflow `install-smoke` повторно використовує той самий скрипт областей через власне завдання `preflight`. Він обчислює `run_install_smoke` на основі вужчого сигналу `changed-smoke`, тому Docker/install smoke запускається лише для змін, пов’язаних зі встановленням, пакуванням і контейнерами. -Для push матриця `checks` додає етап `compat-node22`, який виконується лише для push. Для pull request цей етап пропускається, і матриця залишається зосередженою на звичайних test/channel-етапах. +Для push матриця `checks` додає лан `compat-node22`, який запускається лише для push. Для pull request цей лан пропускається, і матриця зосереджується на звичайних тестових/channel-ланах. -## Runner-и +## Runners -| Runner | Завдання | -| -------------------------------- | ------------------------------------------------------------------------------------------------------ | +| Runner | Завдання | +| -------------------------------- | ---------------------------------------------------------------------------------------------------- | | `blacksmith-16vcpu-ubuntu-2404` | `preflight`, `security-fast`, `build-artifacts`, Linux-перевірки, перевірки документації, Python Skills, `android` | -| `blacksmith-32vcpu-windows-2025` | `checks-windows` | -| `macos-latest` | `macos-node`, `macos-swift` | +| `blacksmith-32vcpu-windows-2025` | `checks-windows` | +| `macos-latest` | `macos-node`, `macos-swift` | ## Локальні еквіваленти ```bash -pnpm check # швидкий локальний gate: tsgo з project references + sharded lint + паралельні швидкі захисти -pnpm check:timed # той самий gate із таймінгами по етапах +pnpm check # швидка локальна перевірка: production tsgo + шардований lint + паралельні швидкі перевірки +pnpm check:test-types +pnpm check:timed # та сама перевірка з помітками часу для кожного етапу pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression -pnpm test # тести vitest +pnpm test # vitest-тести pnpm test:channels pnpm check:docs # форматування документації + lint + биті посилання -pnpm build # збірка dist, коли важливі етапи CI artifact/build-smoke +pnpm build # збірка dist, коли важливі CI-лани artifact/build-smoke ``` diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 534067f28..5dedec3df 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,112 +1,113 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для помилок моделі/провайдера + - Додавання регресійних тестів для багів моделей/провайдерів - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: набори unit/e2e/live, Docker-раннери та що покриває кожен тест' +summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-20T02:15:05Z" + generated_at: "2026-04-20T14:13:27Z" model: gpt-5.4 provider: openai - source_hash: 88457038e2e2c7940d0348762d0ece187111a8c61fa9bad54b39eade4217ddbc + source_hash: b47e97513172c0c0225bbcd657840b3177002d5a59d81f0f05afc6f57b362b56 source_path: help/testing.md workflow: 15 --- # Тестування -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-раннерів. +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ — це посібник «як ми тестуємо»: -- Що покриває кожен набір (і що він навмисно _не_ покриває) -- Які команди запускати для поширених сценаріїв роботи (локально, перед push, налагодження) +- Що охоплює кожен набір (і що він навмисно _не_ охоплює) +- Які команди запускати для типових робочих сценаріїв (локально, перед push, налагодження) - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів -- Як додавати регресійні тести для реальних проблем моделі/провайдера +- Як додавати регресійні тести для реальних проблем із моделями/провайдерами ## Швидкий старт У більшості випадків: -- Повна перевірка (очікується перед push): `pnpm build && pnpm check && pnpm test` -- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` +- Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Швидший локальний запуск усього набору на потужній машині: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` - Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Якщо ви працюєте над однією помилкою, спочатку віддавайте перевагу точковим запускам. +- Якщо ви ітеруєтеся над однією помилкою, спочатку надавайте перевагу таргетованим запускам. - QA-сайт на базі Docker: `pnpm qa:lab:up` -- QA-канал на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- QA-лайн на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` Коли ви змінюєте тести або хочете мати додаткову впевненість: -- Перевірка покриття: `pnpm test:coverage` +- Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Набір live (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` +- Набір live (моделі + gateway-проби інструментів/зображень): `pnpm test:live` - Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -Порада: коли вам потрібен лише один проблемний випадок, звужуйте live-тести через змінні середовища allowlist, описані нижче. +Порада: коли вам потрібен лише один збійний кейс, надавайте перевагу звуженню live-тестів через env-змінні allowlist, описані нижче. -## Спеціальні QA-раннери +## QA-специфічні ранери -Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм qa-lab: +Ці команди розташовані поруч з основними тестовими наборами, коли вам потрібен реалізм qa-lab: - `pnpm openclaw qa suite` - - Запускає QA-сценарії з репозиторію безпосередньо на хості. - - Типово запускає кілька вибраних сценаріїв паралельно з ізольованими воркерами gateway. Для `qa-channel` типовий рівень паралелізму — 4 (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість воркерів, або `--concurrency 1` для старішого послідовного режиму. - - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає помилки. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. + - Запускає QA-сценарії на базі репозиторію безпосередньо на хості. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими gateway-воркерами. Для `qa-channel` за замовчуванням використовується concurrency 4 (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість воркерів, або `--concurrency 1` для старого послідовного лайну. + - Завершується з ненульовим кодом, якщо будь-який сценарій не вдався. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального покриття фікстур і протокольних моків без заміни сценарно-орієнтованого режиму `mock-openai`. + `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального покриття фікстур і mock-покриття протоколу без заміни сценарійно-орієнтованого лайну `mock-openai`. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір усередині тимчасової Multipass Linux VM. + - Запускає той самий QA-набір усередині одноразової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані QA-входи автентифікації, практичні для гостьової системи: - ключі провайдера через env, шлях конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через змонтований workspace. - - Записує звичайний QA-звіт + підсумок, а також логи Multipass у + - Live-запуски пересилають підтримувані QA-входи автентифікації, практичні для guest-середовища: + ключі провайдерів на основі env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, якщо він присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через змонтований workspace. + - Записує звичайний QA-звіт і підсумок, а також логи Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для операторської QA-роботи. + - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. - `pnpm openclaw qa aimock` - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає Matrix live QA-канал проти тимчасового Docker-backed сервера Tuwunel homeserver. - - Цей 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 не надає спільних прапорців джерела облікових даних, оскільки цей канал локально створює тимчасових користувачів. - - Записує Matrix QA-звіт, підсумок, артефакт observed-events і комбінований лог stdout/stderr у `.artifacts/qa-e2e/...`. + - Запускає live QA-лайн Matrix проти одноразового homeserver Tuwunel на базі Docker. + - Цей QA-хост наразі призначений лише для репозиторію/розробки. Упаковані встановлення OpenClaw не постачають `qa-lab`, тож вони не надають `openclaw qa`. + - Копії репозиторію напряму завантажують вбудований раннер; окремий крок встановлення 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` - - Запускає Telegram live QA-канал проти реальної приватної групи, використовуючи токени 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 username. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що driver-бот може спостерігати трафік ботів у групі. - - Записує Telegram QA-звіт, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. + - Запускає live QA-лайн Telegram проти реальної приватної групи, використовуючи токени ботів driver і SUT з env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. + - Підтримує `--credential-source convex` для спільних пулінгових облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. + - Завершується з ненульовим кодом, якщо будь-який сценарій не вдався. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. + - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати Telegram username. + - Для стабільного спостереження між ботами ввімкніть 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 | +| Лайн | Canary | Гейтинг згадувань | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у треді | Ізоляція тредів | Спостереження за реакціями | Команда help | +| -------- | ------ | ----------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | --------------- | -------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -### Спільні Telegram-облікові дані через Convex (v1) +### Спільні облікові дані Telegram через Convex (v1) -Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивну оренду з пулу на базі Convex, підтримує Heartbeat цієї оренди, поки канал працює, і звільняє оренду під час завершення роботи. +Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), +QA lab отримує ексклюзивний lease із Convex-backed pool, надсилає Heartbeat цього lease, поки лайн виконується, і звільняє lease під час завершення роботи. Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові змінні середовища: +Обов’язкові env-змінні: - `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: @@ -114,9 +115,9 @@ Live-канали транспорту мають один спільний ст - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Типове значення з env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) + - Env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (у CI за замовчуванням `ci`, в інших випадках — `maintainer`) -Необов’язкові змінні середовища: +Необов’язкові env-змінні: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) @@ -124,13 +125,14 @@ Live-канали транспорту мають один спільний ст - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL-и Convex лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback-URL Convex через `http://` лише для локальної розробки. -`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. +У звичайному режимі `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. -Адміністративні команди maintainer-а (додавання/видалення/перелік пулу) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. +Адміністративні команди maintainer (додавання/видалення/перелік пулу) потребують саме +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-хелпери для maintainer-ів: +CLI-хелпери для maintainer: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -140,7 +142,7 @@ pnpm openclaw qa credentials remove --credential-id Використовуйте `--json` для машинозчитуваного виводу в скриптах і CI-утилітах. -Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Контракт endpoint за замовчуванням (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -152,69 +154,70 @@ pnpm openclaw qa credentials remove --credential-id - `POST /release` - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Успіх: `{ status: "ok" }` (або порожній `2xx`) -- `POST /admin/add` (лише секрет maintainer-а) +- `POST /admin/add` (лише секрет maintainer) - Запит: `{ kind, actorId, payload, note?, status? }` - Успіх: `{ status: "ok", credential }` -- `POST /admin/remove` (лише секрет maintainer-а) +- `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (лише секрет maintainer-а) + - Захист активного lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` -Форма payload для виду Telegram: +Форма payload для типу Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком із числовим ідентифікатором чату Telegram. +- `groupId` має бути рядком із числовим Telegram chat id. - `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректний payload. ### Додавання каналу до QA -Щоб додати канал до markdown-системи QA, потрібні рівно дві речі: +Додавання каналу до markdown-системи QA потребує рівно двох речей: -1. Транспортний адаптер для каналу. -2. Пакет сценаріїв, який перевіряє контракт каналу. +1. Транспортного адаптера для каналу. +2. Пакета сценаріїв, який перевіряє контракт каналу. -Не додавайте новий кореневий QA-командний namespace верхнього рівня, якщо спільний хост `qa-lab` може керувати цим потоком. +Не додавайте новий кореневий QA-командний простір верхнього рівня, коли спільний хост `qa-lab` +може керувати цим потоком. -`qa-lab` володіє спільною механікою хоста: +`qa-lab` відповідає за спільну механіку хоста: -- кореневою командою `openclaw qa` -- запуском і завершенням набору -- паралелізмом воркерів -- записом артефактів -- генерацією звітів -- виконанням сценаріїв -- aliases сумісності для старіших сценаріїв `qa-channel` +- кореневий командний простір `openclaw qa` +- запуск і завершення набору +- паралелізм воркерів +- запис артефактів +- генерацію звітів +- виконання сценаріїв +- аліаси сумісності для старіших сценаріїв `qa-channel` -Runner plugins володіють транспортним контрактом: +Runner Plugins володіють транспортним контрактом: -- як `openclaw qa ` монтується під спільний корінь `qa` +- як `openclaw qa ` монтується під спільним коренем `qa` - як gateway налаштовується для цього транспорту - як перевіряється готовність - як інжектуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються транскрипти та нормалізований стан транспорту +- як надаються транскрипти й нормалізований стан транспорту - як виконуються дії, пов’язані з транспортом -- як обробляється специфічне для транспорту скидання або очищення +- як обробляється скидання або очищення, специфічне для транспорту -Мінімальна планка для впровадження нового каналу: +Мінімальний поріг прийняття для нового каналу: -1. Залишити `qa-lab` власником спільного кореня `qa`. -2. Реалізувати transport runner на спільному host seam `qa-lab`. -3. Залишити транспортно-специфічну механіку всередині runner plugin або channel harness. -4. Монтувати раннер як `openclaw qa `, а не реєструвати конкуруючий кореневий командний namespace. - Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. - Тримайте `runtime-api.ts` легким; ліниве виконання CLI й раннера має залишатися за окремими entrypoint-ами. -5. Створювати або адаптувати markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовувати загальні scenario helpers для нових сценаріїв. -7. Зберігати працездатність наявних aliases сумісності, якщо в репозиторії не виконується навмисна міграція. +1. Зберігайте `qa-lab` як власника спільного кореня `qa`. +2. Реалізуйте транспортний runner на спільному шві хоста `qa-lab`. +3. Зберігайте механіку, специфічну для транспорту, всередині runner plugin або channel harness. +4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючого кореневого простору команд. + Runner Plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. + Зберігайте `runtime-api.ts` легким; ліниве виконання CLI і runner має залишатися за окремими entrypoint. +5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. +6. Використовуйте загальні helper-и сценаріїв для нових сценаріїв. +7. Підтримуйте наявні аліаси сумісності, якщо в репозиторії не виконується навмисна міграція. -Правило прийняття рішення суворе: +Правило ухвалення рішень суворе: - Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного транспортного каналу, залишайте її в цьому runner plugin або plugin harness. +- Якщо поведінка залежить від одного транспорту каналу, зберігайте її в цьому runner plugin або plugin harness. - Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте загальний helper замість channel-specific гілки в `suite.ts`. - Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно відображайте це в контракті сценарію. @@ -233,7 +236,7 @@ Runner plugins володіють транспортним контрактом: - `formatTransportTranscript` - `resetTransport` -Aliases сумісності залишаються доступними для наявних сценаріїв, зокрема: +Аліаси сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -242,66 +245,66 @@ Aliases сумісності залишаються доступними для - `resetBus` Нова робота над каналами має використовувати загальні назви helper-ів. -Aliases сумісності існують, щоб уникнути міграції «в один день», а не як модель для -створення нових сценаріїв. +Аліаси сумісності існують, щоб уникнути одночасної міграції всього одразу, а не як модель для +авторингу нових сценаріїв. -## Набори тестів (що де запускається) +## Тестові набори (що запускається і де) -Сприймайте набори як такі, що мають «зростаючий реалізм» (і зростаючу нестабільність/вартість): +Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) поверх наявних scoped-проєктів Vitest -- Файли: core/unit-інвентарі в `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, що покриваються `vitest.unit.config.ts` +- Конфігурація: десять послідовних shard-запусків (`vitest.full-*.config.ts`) поверх наявних scoped Vitest project +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelist-нуті node-тести `ui`, які охоплюються `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - In-process integration-тести (автентифікація gateway, маршрутизація, tooling, парсинг, конфігурація) - - Детерміновані регресії для відомих помилок + - Детерміновані регресійні тести для відомих багів - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним -- Примітка про проєкти: - - Нетаргетований `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project процесу. Це зменшує піковий RSS на навантажених машинах і не дає роботі auto-reply/extension заважати іншим наборам. - - `pnpm test --watch` і далі використовує граф native root `vitest.config.ts`, оскільки багатошардовий цикл watch непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файл/каталог через scoped-канали, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped-канали, коли diff зачіпає лише маршрутизовані source/test-файли; зміни config/setup, як і раніше, повертаються до широкого повторного запуску root-project. - - Import-light unit-тести з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` та подібних чистих утилітних областей маршрутизуються через канал `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних каналах. - - Вибрані helper source-файли `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними sibling-тестами в цих легких каналах, тож зміни helper-ів не змушують повторно запускати повний важкий набір для цього каталогу. - - `auto-reply` тепер має три окремі кошики: top-level core helper-и, top-level integration-тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply поза дешевими тестами status/chunk/token. -- Примітка про embedded runner: - - Коли ви змінюєте вхідні дані виявлення message-tool або контекст runtime Compaction, +- Примітка щодо project: + - Нетаргетований `pnpm test` тепер запускає одинадцять менших shard-конфігурацій (`core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project process. Це зменшує пік RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. + - `pnpm test --watch` усе ще використовує native root `vitest.config.ts` project graph, тому що multi-shard цикл watch непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спершу маршрутизують явні цілі файлів/каталогів через scoped-лайни, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped-лайни, коли diff торкається лише routable source/test-файлів; редагування config/setup усе ще повертається до ширшого повторного запуску root-project. + - Import-light unit-тести з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` і подібних суто утилітарних областей маршрутизуються через лайн `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних лайнах. + - Вибрані helper source-файли `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними sibling-тестами в цих легких лайнах, тож редагування 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, зберігайте обидва рівні покриття. - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації/нормалізації. - - Також підтримуйте в хорошому стані integration-набори embedded runner: + - Також підтримуйте в здоровому стані 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 як і раніше проходять - через реальні шляхи `run.ts` / `compact.ts`; лише helper-тести не є - достатньою заміною для цих integration-шляхів. -- Примітка про pool: + - Ці набори перевіряють, що scoped id і поведінка Compaction, як і раніше, проходять + через реальні шляхи `run.ts` / `compact.ts`; одних лише helper-тестів + недостатньо як заміни для цих integration-шляхів. +- Примітка щодо pool: - Базова конфігурація Vitest тепер типово використовує `threads`. - - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root projects, e2e і live-конфігураціях. - - Кореневий канал UI зберігає свій `jsdom` setup та optimizer, але тепер також працює на спільному non-isolated runner. + - Спільна конфігурація Vitest також фіксує `isolate: false` і використовує non-isolated runner у root project, e2e і live-конфігураціях. + - Кореневий лайн UI зберігає свій `jsdom` setup і optimizer, але тепер теж запускається на спільному non-isolated runner. - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. -- Примітка про швидку локальну ітерацію: - - `pnpm test:changed` маршрутизує через scoped-канали, коли змінені шляхи добре зіставляються з меншим набором. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею кількості воркерів. - - Локальне автомасштабування воркерів тепер навмисно консервативне й також зменшується, коли середнє навантаження хоста вже високе, тож кілька паралельних запусків Vitest типово завдають менше шкоди. - - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні changed-mode запуски залишалися коректними, коли змінюється wiring тестів. - - Конфігурація залишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете мати одну явну локацію кешу для прямого профілювання. -- Примітка про налагодження продуктивності: - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту плюс вивід розбивки імпортів. - - `pnpm test:perf:imports:changed` обмежує той самий вигляд профілювання файлами, зміненими від `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований `test:changed` з native root-project шляхом для цього закоміченого diff і виводить wall time плюс macOS max RSS. -- `pnpm test:perf:changed:bench -- --worktree` вимірює поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує CPU-профіль головного потоку для накладних витрат запуску й трансформації Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap-профілі runner-а для unit-набору з вимкненим файловим паралелізмом. + - Спільний launcher `scripts/run-vitest.mjs` тепер також типово додає `--no-maglev` для дочірніх Node-process Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, якщо потрібно порівняти зі стандартною поведінкою V8. +- Примітка щодо швидкої локальної ітерації: + - `pnpm test:changed` маршрутизується через scoped-лайни, коли змінені шляхи чисто зіставляються з меншим набором. + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом воркерів. + - Автомасштабування локальних воркерів тепер навмисно консервативне і також зменшується, коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає project/config-файли як `forceRerunTriggers`, щоб changed-mode повторні запуски лишалися коректними, коли змінюється тестова обв’язка. + - Конфігурація зберігає `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 шляхом для цього зафіксованого diff і виводить wall time плюс max RSS на macOS. +- `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточне брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і root-конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує профіль CPU main-thread для накладних витрат запуску й трансформації Vitest/Vite. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner для unit-набору з вимкненим файловим паралелізмом. -### E2E (smoke Gateway) +### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` @@ -309,15 +312,15 @@ Aliases сумісності існують, щоб уникнути мігра - Типові налаштування runtime: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - Використовує адаптивну кількість воркерів (CI: до 2, локально: типово 1). - - Типово запускається в тихому режимі, щоб зменшити накладні витрати на console I/O. + - За замовчуванням запускається в silent mode, щоб зменшити накладні витрати вводу/виводу консолі. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість воркерів (обмежено 16). + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість воркерів (не більше 16). - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - End-to-end поведінка gateway з кількома інстансами - - Поверхні WebSocket/HTTP, парування Node і важчий мережевий стек + - Наскрізна поведінка gateway з кількома інстансами + - Поверхні WebSocket/HTTP, спарювання Node і складніша робота з мережею - Очікування: - - Запускається в CI (коли ввімкнено в pipeline) + - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) @@ -326,17 +329,17 @@ Aliases сумісності існують, щоб уникнути мігра - Команда: `pnpm test:e2e:openshell` - Файл: `test/openshell-sandbox.e2e.test.ts` - Обсяг: - - Запускає ізольований OpenShell gateway на хості через Docker + - Запускає ізольований gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - Перевіряє OpenShell backend OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Підтверджує поведінку файлової системи remote-canonical через sandbox fs bridge + - Перевіряє поведінку файлової системи з remote-canonical шляхами через sandbox fs bridge - Очікування: - - Лише за явним увімкненням; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і працездатного демона Docker + - Лише 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-скрипт + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб указати нестандартний двійковий файл CLI або wrapper-скрипт ### Live (реальні провайдери + реальні моделі) @@ -346,114 +349,114 @@ Aliases сумісності існують, щоб уникнути мігра - Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей tool-calling, проблем автентифікації та поведінки rate limit + - Виявлення змін форматів провайдерів, особливостей виклику інструментів, проблем автентифікації та поведінки обмежень rate limit - Очікування: - - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - За задумом нестабільний у CI (реальні мережі, реальні політики провайдерів, квоти, збої) - Коштує грошей / витрачає rate limits - Краще запускати звужені підмножини, а не «все» -- Live-запуски використовують `~/.profile`, щоб підхоплювати відсутні API-ключі. -- Типово live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий тестовий home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і глушить логи bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API-ключів (залежить від провайдера): установіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використовуйте перевизначення на рівні live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. +- Live-запуски підвантажують `~/.profile`, щоб отримати відсутні API-ключі. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли ви свідомо хочете, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення `~/.profile` і вимикає логи bootstrap gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. +- Ротація API-ключів (залежно від провайдера): установіть `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використовуйте перевизначення для live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. - Вивід прогресу/Heartbeat: - - Live-набори тепер надсилають рядки прогресу в stderr, тож довгі виклики провайдера видно як активні, навіть коли захоплення консолі Vitest працює тихо. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/gateway негайно транслювалися під час live-запусків. - - Налаштовуйте Heartbeat прямої моделі через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Live-набори тепер виводять рядки прогресу в stderr, щоб під час тривалих викликів провайдерів було видно, що процес активний, навіть коли захоплення консолі Vitest тихе. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/gateway одразу транслюються під час live-запусків. + - Налаштовуйте Heartbeat для прямої моделі через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Використовуйте цю таблицю рішень: +Скористайтеся цією таблицею рішень: -- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Зачіпаєте мережеву взаємодію gateway / протокол WS / парування: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / tool calling: запускайте звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато що змінили) +- Торкаєтеся мережевої частини gateway / WS-протоколу / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої, специфічні для провайдера / виклик інструментів: запускайте звужений `pnpm test:live` ## Live: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яка зараз оголошена** підключеним Android Node, і перевірити поведінку контракту команд. +- Мета: викликати **кожну команду, що наразі рекламується** підключеним Android Node, і перевірити поведінку контракту команди. - Обсяг: - - Передумови/ручне налаштування (набір не встановлює, не запускає й не парує застосунок). - - Перевірка `node.invoke` gateway команда за командою для вибраного Android Node. -- Обов’язкове попереднє налаштування: - - Android-застосунок уже підключений і спарений із gateway. - - Застосунок утримується на передньому плані. - - Надано дозволи/підтвердження захоплення для можливостей, які ви очікуєте як успішні. + - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не pair-ить app). + - Валідація `node.invoke` gateway для вибраного Android Node, команда за командою. +- Потрібне попереднє налаштування: + - Android app уже підключено й спарено з gateway. + - App має залишатися на передньому плані. + - Дозволи/згода на capture мають бути надані для тих можливостей, які ви очікуєте як успішні. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Повні відомості про налаштування Android: [Android App](/uk/platforms/android) +- Повні деталі налаштування Android: [Android App](/uk/platforms/android) -## Live: smoke моделі (ключі профілю) +## Live: smoke моделей (ключі профілю) -Live-тести розділені на два рівні, щоб можна було ізолювати збої: +Live-тести поділені на два шари, щоб можна було ізолювати збої: -- «Direct model» показує, що провайдер/модель взагалі може відповісти з наданим ключем. -- «Gateway smoke» показує, що повний конвеєр gateway+agent працює для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). +- «Direct model» повідомляє нам, що провайдер/модель взагалі можуть відповісти з указаним ключем. +- «Gateway smoke» повідомляє нам, що повний конвеєр gateway+agent працює для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). -### Рівень 1: пряме завершення моделі (без gateway) +### Шар 1: Direct model completion (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - - Перерахувати виявлені моделі - - Використовувати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Виконати невелике completion для кожної моделі (і цільові регресії там, де потрібно) + - Перелічити виявлені моделі + - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані + - Запустити невелике completion для кожної моделі (і таргетовані регресії, де потрібно) - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб справді запустити цей набір; інакше він пропускається, щоб `pnpm test:live` залишався зосередженим на smoke Gateway -- Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern` для запуску modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — це alias для modern allowlist +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб цей набір справді запускався; інакше його буде пропущено, щоб `pnpm test:live` залишався сфокусованим на gateway smoke +- Як вибрати моделі: + - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це псевдонім для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Перегляди modern/all типово мають curated high-signal обмеження; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern-перегляду або додатне число для меншого ліміту. -- Як вибирати провайдерів: + - Для modern/all-прогонів за замовчуванням використовується відібраний ліміт із високим сигналом; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного modern-прогону або додатне число для меншого ліміту. +- Як вибрати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - Типово: profile store і env fallback-и - - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** + - За замовчуванням: сховище профілів і резервні значення з env + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр gateway agent зламаний» - - Містить малі, ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) + - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) -### Рівень 2: smoke Gateway + dev agent (що насправді робить "@openclaw") +### Шар 2: Gateway + smoke dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - Підняти in-process gateway - - Створити/оновити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) - - Ітерувати моделі-з-ключами й перевіряти: + - Створити/оновити сесію `agent:dev:*` (перевизначення моделі на кожен запуск) + - Ітеруватися за моделями-з-ключами і перевіряти: - «змістовну» відповідь (без інструментів) - - що реальний виклик інструмента працює (перевірка read) - - необов’язкові додаткові перевірки інструментів (перевірка exec+read) - - що шляхи регресії OpenAI (лише tool-call → follow-up) і далі працюють + - що реальний виклик інструмента працює (`read` probe) + - необов’язкові додаткові probe інструментів (`exec+read` probe) + - що шляхи регресії OpenAI (лише tool-call → follow-up) продовжують працювати - Деталі probe (щоб ви могли швидко пояснювати збої): - - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce назад. - - `exec+read` probe: тест просить агента записати nonce у тимчасовий файл через `exec`, а потім прочитати його назад через `read`. - - image probe: тест прикріплює згенерований PNG (кіт + рандомізований код) і очікує, що модель поверне `cat `. + - `read` probe: тест записує файл із nonce у workspace і просить agent виконати `read` цього файла та повернути nonce. + - `exec+read` probe: тест просить agent через `exec` записати nonce у тимчасовий файл, а потім прочитати його назад через `read`. + - image probe: тест додає згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Як вибирати моделі: - - Типово: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це alias для modern allowlist +- Як вибрати моделі: + - За замовчуванням: 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 типово мають curated high-signal обмеження; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern-перегляду або додатне число для меншого ліміту. -- Як вибирати провайдерів (уникайте «OpenRouter для всього»): + - Для modern/all gateway-прогонів за замовчуванням використовується відібраний ліміт із високим сигналом; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного modern-прогону або додатне число для меншого ліміту. +- Як вибрати провайдерів (уникайте «всього OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Tool + image probe у цьому live-тесті завжди ввімкнені: - - `read` probe + `exec+read` probe (stress для інструментів) - - image probe запускається, коли модель заявляє підтримку введення зображень +- Probe інструментів + зображень у цьому live-тесті завжди увімкнені: + - `read` probe + `exec+read` probe (стрес-тест інструментів) + - image probe запускається, коли модель заявляє підтримку image input - Потік (на високому рівні): - Тест генерує крихітний PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway парсить attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Embedded agent передає multimodal повідомлення користувача моделі - - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) + - Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Embedded agent пересилає multimodal user message моделі + - Перевірка: відповідь містить `cat` + код (допускається OCR-tolerance: незначні помилки) -Порада: щоб побачити, що саме можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що саме ви можете тестувати на своїй машині (і точні id `provider/model`), виконайте: ```bash openclaw models list @@ -463,23 +466,23 @@ openclaw models list --json ## Live: smoke CLI backend (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent з використанням локального CLI backend, не зачіпаючи вашу типову конфігурацію. -- Типові значення smoke, специфічні для backend, розміщено у визначенні `cli-backend.ts` extension-власника. +- Мета: перевірити конвеєр Gateway + agent з використанням локального CLI backend без зміни вашого типового config. +- Типові параметри smoke для конкретного backend живуть у визначенні `cli-backend.ts` відповідного extension. - Увімкнення: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - - Типовий provider/model: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image походить із metadata plugin CLI backend-власника. + - Типові provider/model: `claude-cli/claude-sonnet-4-6` + - Поведінка command/args/image береться з метаданих plugin CLI backend, якому це належить. - Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.4"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальне вкладення-зображення (шляхи інжектуються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до файлів зображень як CLI-аргументи замість інжекції в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) щоб керувати тим, як передаються аргументи зображень, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий turn і перевірити потік відновлення. - - `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"`, щоб передавати шляхи до файлів зображень як CLI args замість інжекції в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати способом передавання args зображень, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову probe безперервності тієї самої сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -495,7 +498,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` -Docker-рецепти для одного провайдера: +Рецепти Docker для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude @@ -506,28 +509,28 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker-раннер розташовано в `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію як непривілейований користувач `node`. -- Він визначає metadata CLI smoke від extension-власника, а потім встановлює відповідний Linux CLI-пакет (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний prefix за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` потребує переносного OAuth підписки Claude Code через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він підтверджує прямий `claude -p` у Docker, а потім запускає два Gateway CLI-backend turns без збереження env-змінних ключа Anthropic API. Цей канал підписки типово вимикає Claude MCP/tool і image probe, оскільки Claude наразі маршрутизує використання сторонніх застосунків через тарифікацію extra-usage, а не через звичайні ліміти тарифного плану підписки. -- Smoke live CLI-backend тепер перевіряє той самий end-to-end потік для Claude, Codex і Gemini: текстовий turn, turn класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через gateway CLI. -- Типовий smoke Claude також оновлює сесію з Sonnet на Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Docker-ранер розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає метадані smoke CLI з extension, якому це належить, а потім встановлює відповідний Linux CLI-пакет (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований записуваний префікс у `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (типово: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` потребує portable Claude Code subscription OAuth через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім виконує два ходи Gateway CLI-backend без збереження env-змінних Anthropic API-key. Цей subscription-лайн типово вимикає Claude MCP/tool і image probe, оскільки наразі Claude маршрутизує використання сторонніх застосунків через extra-usage billing, а не через звичайні ліміти subscription plan. +- Live smoke CLI-backend тепер перевіряє той самий end-to-end потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через CLI gateway. +- Типовий smoke Claude також оновлює сесію із Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. ## Live: smoke ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік прив’язки розмови ACP з live ACP-агентом: +- Мета: перевірити реальний потік bind розмови ACP з live ACP agent: - надіслати `/acp spawn --bind here` - - прив’язати synthetic розмову каналу повідомлень на місці - - надіслати звичайне follow-up у тій самій розмові - - перевірити, що follow-up потрапляє в transcript прив’язаної ACP-сесії + - прив’язати синтетичну розмову message-channel на місці + - надіслати звичайний follow-up у тій самій розмові + - перевірити, що follow-up потрапляє в transcript прив’язаної сесії ACP - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP-агенти в Docker: `claude,codex,gemini` - - ACP-агент для прямого `pnpm test:live ...`: `claude` - - Synthetic канал: контекст розмови у стилі Slack DM + - ACP agent у Docker: `claude,codex,gemini` + - ACP agent для прямого `pnpm test:live ...`: `claude` + - Синтетичний канал: контекст розмови в стилі Slack DM - ACP backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` @@ -536,8 +539,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 synthetic originating-route полями, щоб тести могли прикріплювати контекст message-channel без удавання зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів плагіна `acpx` для вибраного ACP harness agent. + - Цей лайн використовує поверхню gateway `chat.send` з admin-only synthetic originating-route fields, щоб тести могли прикріплювати контекст message-channel без удавання зовнішньої доставки. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр agent плагіна `acpx` для вибраного ACP harness agent. Приклад: @@ -553,7 +556,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Docker-рецепти для одного агента: +Рецепти Docker для одного agent: ```bash pnpm test:docker:live-acp-bind:claude @@ -563,31 +566,31 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker-раннер розташовано в `scripts/test-live-acp-bind-docker.sh`. -- Типово він запускає smoke ACP bind послідовно для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. +- Docker-ранер розташований у `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він послідовно запускає smoke ACP 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`, переносить відповідні матеріали автентифікації CLI в контейнер, встановлює `acpx` у записуваний npm-prefix, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його бракує. -- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера з підключеного profile доступними для дочірнього harness CLI. +- Він підвантажує `~/.profile`, переносить відповідні auth-матеріали CLI в контейнер, встановлює `acpx` у записуваний npm-префікс, а потім за потреби встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`). +- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера із підвантаженого profile доступними для дочірнього CLI harness. -## Live: smoke harness app-server Codex +## Live: smoke app-server harness Codex -- Мета: перевірити plugin-власний harness Codex через звичайний метод gateway - `agent`: +- Мета: перевірити Plugin-керований harness Codex через звичайний gateway + метод `agent`: - завантажити вбудований plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший gateway agent turn до `codex/gpt-5.4` - - надіслати другий turn до тієї самої сесії OpenClaw і перевірити, що thread app-server - можна відновити - - виконати `/codex status` і `/codex models` через той самий командний шлях - gateway + - надіслати перший хід gateway agent до `codex/gpt-5.4` + - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що thread app-server + може відновитися + - виконати `/codex status` і `/codex models` через той самий gateway command + path - Тест: `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` -- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний Codex - harness не міг пройти, тихо переключившись назад на PI. -- Auth: `OPENAI_API_KEY` із shell/profile, плюс необов’язково скопійовані +- Необов’язкова image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язкова MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, тож зламаний harness Codex + не зможе пройти, тихо переключившись назад на PI. +- Auth: `OPENAI_API_KEY` із shell/profile плюс необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -610,65 +613,65 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker-раннер розташовано в `scripts/test-live-codex-harness-docker.sh`. -- Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації CLI Codex, якщо вони присутні, встановлює `@openai/codex` у записуваний змонтований npm - prefix, готує дерево вихідного коду, а потім запускає лише live-тест Codex-harness. -- Docker типово вмикає image- і MCP/tool-probe. Установіть +- Docker-ранер розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він підвантажує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли + auth Codex CLI, якщо вони наявні, встановлює `@openai/codex` у записуваний змонтований npm + префікс, готує дерево вихідного коду, а потім запускає лише live-тест Codex-harness. +- У Docker image і MCP/tool probe увімкнені за замовчуванням. Установіть `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. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і live + test config, тож fallback до `openai-codex/*` або PI не зможе приховати регресію + harness Codex. -### Рекомендовані live-рецепти +### Рекомендовані рецепти live -Вузькі, явні allowlist-и — найшвидші й найменш нестабільні: +Найшвидші й найменш нестабільні — вузькі, явні allowlist: -- Одна модель, напряму (без gateway): +- Одна модель, direct (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Одна модель, smoke Gateway: +- Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклик інструментів у кількох провайдерів: +- Виклик інструментів для кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Фокус на Google (API-ключ Gemini + Antigravity): - - Gemini (API-ключ): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Фокус на Google (API key Gemini + 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/...` використовує API Gemini (API-ключ). -- `google-antigravity/...` використовує OAuth-міст Antigravity (endpoint агента у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний CLI Gemini на вашій машині (окрема автентифікація + особливості tooling). -- API Gemini проти CLI Gemini: - - API: OpenClaw викликає хостований Google API Gemini через HTTP (API-ключ / автентифікація профілю); це те, що більшість користувачів мають на увазі під «Gemini». - - CLI: OpenClaw викликає локальний бінарний файл `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/підтримка інструментів/розсинхрон версій). +- `google/...` використовує Gemini API (API key). +- `google-antigravity/...` використовує OAuth-міст Antigravity (endpoint агента в стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема auth + особливості tooling). +- Gemini API проти Gemini CLI: + - API: OpenClaw викликає розміщений у Google Gemini API через HTTP (API key / auth профілю); це те, що більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує локальний двійковий файл `gemini`; він має власну auth і може поводитися інакше (streaming/підтримка інструментів/розбіжність версій). ## Live: матриця моделей (що ми покриваємо) -Немає фіксованого «списку моделей CI» (live запускається лише за явним увімкненням), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. +Фіксованого «списку моделей CI» немає (live — opt-in), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. -### Сучасний smoke-набір (виклик інструментів + зображення) +### Сучасний smoke-набір (виклик інструментів + image) -Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: +Це прогін «поширених моделей», який ми очікуємо зберігати працездатним: -- OpenAI (не-Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) +- OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex: `openai-codex/gpt-5.4` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) -- Google (API Gemini): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) +- Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` і `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запустіть smoke Gateway з інструментами + зображенням: +Запустіть gateway smoke з інструментами + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,openai-codex/gpt-5.4,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий набір: виклик інструментів (Read + необов’язковий Exec) +### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) -Виберіть щонайменше одну модель для кожного сімейства провайдерів: +Виберіть щонайменше по одній моделі на сімейство провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -676,286 +679,286 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (бажано мати): +Необов’язкове додаткове покриття (було б добре мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою «tools», яку у вас ввімкнено) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку ви увімкнули) - Cerebras: `cerebras/`… (якщо у вас є доступ) - LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) -### Vision: надсилання зображення (вкладення → multimodal-повідомлення) +### Vision: надсилання image (attachment → multimodal message) -Включіть щонайменше одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб перевірити image probe. +Додайте щонайменше одну модель із підтримкою image до `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI із підтримкою vision тощо), щоб перевірити image probe. ### Агрегатори / альтернативні gateway Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: - OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) -- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити до live-матриці (якщо у вас є облікові дані/конфігурація): +Більше провайдерів, яких можна включити в live-матрицю (якщо у вас є creds/config): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (власні endpoint-и): `minimax` (cloud/API), плюс будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (custom endpoint): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-compatible proxy (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко прописати в документації «всі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс ті ключі, які доступні. +Порада: не намагайтеся жорстко зашити в документацію «всі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс усі доступні ключі. ## Облікові дані (ніколи не комітьте) -Live-тести виявляють облікові дані так само, як і CLI. Практичні наслідки: +Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знаходити ті самі ключі. -- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. +- Якщо CLI працює, live-тести мають знайти ті самі ключі. +- Якщо live-тест каже «немає creds», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації на рівні агента: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілю» у live-тестах) +- Профілі auth для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це у live-тестах означає «ключі профілю») - Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється в підготовлений live-home, якщо присутній, але це не основне сховище ключів профілю) -- Локальні live-запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI в тимчасовий тестовий home; підготовлені live-home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probe-и не зачіпали ваш реальний workspace хоста. +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється в staged live home, якщо присутній, але не є основним сховищем ключів профілю) +- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для окремих агентів, застарілий `credentials/` і підтримувані зовнішні каталоги auth CLI у тимчасовий test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` вилучаються, щоб probe-и не торкалися вашого реального host workspace. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-раннери нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте наведені нижче Docker-ранери (вони можуть монтувати `~/.profile` у контейнер). -## Deepgram live (транскрипція аудіо) +## Live: Deepgram (транскрибування аудіо) - Тест: `src/media-understanding/providers/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live src/media-understanding/providers/deepgram/audio.live.test.ts` -## BytePlus coding plan live +## Live: план кодування BytePlus - Тест: `src/agents/byteplus.live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live src/agents/byteplus.live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## ComfyUI workflow media live +## Live: медіа workflow ComfyUI - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє вбудовані шляхи comfy для зображень, відео та `music_generate` + - Перевіряє вбудовані шляхи зображень, відео та `music_generate` comfy - Пропускає кожну можливість, якщо `models.providers.comfy.` не налаштовано - Корисно після змін у відправленні workflow comfy, polling, завантаженнях або реєстрації plugin -## Live генерації зображень +## Live: генерація зображень - Тест: `src/image-generation/runtime.live.test.ts` - Команда: `pnpm test:live src/image-generation/runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перераховує кожен зареєстрований provider plugin генерації зображень - - Завантажує відсутні env-змінні провайдерів із вашої login shell (`~/.profile`) перед probe - - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Перелічує кожен зареєстрований Plugin провайдера генерації зображень + - Перед probe-ами завантажує відсутні env-змінні провайдера з вашої login shell (`~/.profile`) + - За замовчуванням використовує live/env API keys раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатних auth/profile/model - Запускає стандартні варіанти генерації зображень через спільну runtime-можливість: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні вбудовані провайдери, які покриваються: +- Поточні вбудовані провайдери, що покриваються: - `openai` - `google` - Необов’язкове звуження: - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google"` - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-1,google/gemini-3.1-flash-image-preview"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit"` -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile store і ігнорувати перевизначення лише через env +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з 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` - Обсяг: - - Перевіряє спільний вбудований шлях provider-а генерації музики + - Перевіряє спільний вбудований шлях провайдера генерації музики - Наразі охоплює Google і MiniMax - - Завантажує env-змінні провайдерів із вашої login shell (`~/.profile`) перед probe - - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Перед probe-ами завантажує env-змінні провайдера з вашої login shell (`~/.profile`) + - За замовчуванням використовує live/env API keys раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатних auth/profile/model - Запускає обидва оголошені runtime-режими, коли вони доступні: - `generate` із введенням лише prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільного каналу: + - Поточне покриття спільного лайну: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, а не цей спільний перегляд + - `comfy`: окремий live-файл Comfy, а не цей спільний прогін - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile store і ігнорувати перевизначення лише через env +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з 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` - Обсяг: - - Перевіряє спільний вбудований шлях provider-а генерації відео - - Типово використовує release-safe smoke-шлях: провайдери без FAL, один запит text-to-video на провайдера, односекундний lobster prompt і ліміт операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (типово `180000`) - - Типово пропускає FAL, оскільки затримка черги на боці провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно його запустити - - Завантажує env-змінні провайдерів із вашої login shell (`~/.profile`) перед probe - - Типово використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell - - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Типово запускає лише `generate` + - Перевіряє спільний вбудований шлях провайдера генерації відео + - За замовчуванням використовує release-safe smoke-шлях: провайдери без FAL, один запит text-to-video на провайдера, односекундний prompt lobster і ліміт операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (типово `180000`) + - FAL типово пропускається, оскільки затримка черги на боці провайдера може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно його запустити + - Перед probe-ами завантажує env-змінні провайдера з вашої login shell (`~/.profile`) + - За замовчуванням використовує live/env API keys раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані + - Пропускає провайдерів без придатних auth/profile/model + - За замовчуванням запускає лише `generate` - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний provider/model приймає локальне введення зображення через buffer-backed у спільному перегляді - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний provider/model приймає локальне введення відео через buffer-backed у спільному перегляді - - Поточні провайдери `imageToVideo`, оголошені, але пропущені в спільному перегляді: - - `vydra`, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддалений URL зображення - - Специфічне для провайдера покриття Vydra: + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід зображення на основі buffer у спільному прогоні + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід відео на основі buffer у спільному прогоні + - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному прогоні: + - `vydra`, тому що вбудований `veo3` працює лише з текстом, а вбудований `kling` потребує віддалений image 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`, який типово використовує фікстуру з віддаленим image URL - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні провайдери `videoToVideo`, оголошені, але пропущені в спільному перегляді: - - `alibaba`, `qwen`, `xai`, оскільки ці шляхи зараз потребують віддалені референсні URL `http(s)` / MP4 - - `google`, оскільки поточний спільний канал Gemini/Veo використовує локальне buffer-backed введення, і цей шлях не приймається в спільному перегляді - - `openai`, оскільки поточний спільний канал не гарантує доступ до video inpaint/remix, специфічний для org + - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному прогоні: + - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі потребують віддалені еталонні URL `http(s)` / MP4 + - `google`, тому що поточний спільний лайн Gemini/Veo використовує локальний вхід на основі buffer, а цей шлях не приймається у спільному прогоні + - `openai`, тому що поточний спільний лайн не гарантує доступ до org-specific video inpaint/remix - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типового перегляду, зокрема FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт часу операції для кожного провайдера для агресивного smoke-запуску -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile store і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера в типовий прогін, зокрема FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити ліміт операції для кожного провайдера під час агресивного smoke-запуску +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env ## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори для зображень, музики та відео через один repo-native entrypoint - - Автоматично завантажує відсутні env-змінні провайдерів із `~/.profile` - - Типово автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і quiet-mode залишається узгодженою + - Запускає спільні live-набори image, music і video через один рідний для репозиторію entrypoint + - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` + - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну auth + - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і quiet mode залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` - `pnpm test:live:media video --video-providers openai,runway --all-providers` - `pnpm test:live:media music --quiet` -## Docker-раннери (необов’язкові перевірки «працює в Linux») +## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці Docker-раннери поділяються на дві групи: +Ці Docker-ранери поділяються на дві категорії: -- Раннери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм live-файл з ключами профілю всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та workspace (і використовують `~/.profile`, якщо він змонтований). Відповідні локальні entrypoint-и — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker-раннери live типово мають менше обмеження smoke, щоб повний Docker-перегляд залишався практичним: - `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Live-model ранери: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм profile-key live-файл усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтуючи ваш локальний каталог config і workspace (а також підвантажуючи `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-ранери за замовчуванням використовують менший smoke-ліміт, щоб повний Docker-прогін залишався практичним: + `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` за замовчуванням використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли - вам явно потрібен більший вичерпний перегляд. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-каналів live. -- Раннери smoke контейнерів: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + ви явно хочете більший вичерпний прогін. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох live Docker-лайнів. +- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:gateway-network`, `test:docker:mcp-channels` і `test:docker:plugins` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-раннери live-моделей також bind-mount-ять лише потрібні home-каталоги автентифікації CLI (або всі підтримувані, якщо запуск не звужений), а потім копіюють їх у home контейнера перед запуском, щоб зовнішній CLI OAuth міг оновлювати токени, не змінюючи сховище автентифікації хоста: +Live-model Docker-ранери також bind-mount-ять лише потрібні home-каталоги auth CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни host auth store: -- Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Smoke ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- Smoke CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- Direct models: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) +- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke Codex app-server harness: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повне scaffold-налаштування): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Мережева взаємодія Gateway (два контейнери, автентифікація WS + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- MCP channel bridge (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Plugins (smoke встановлення + alias `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Майстер онбордингу (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Мережа Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Міст каналу MCP (seeded Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Plugins (install smoke + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -Docker-раннери live-моделей також bind-mount-ять поточний checkout лише для читання і -підготовлюють його у тимчасовий workdir усередині контейнера. Це робить runtime-образ -компактним, але все одно дає змогу запускати Vitest проти точно вашої локальної source/config. -Крок підготовки пропускає великі локальні кеші та артефакти збірки застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні каталоги `.build` або -виводу Gradle, тож Docker live-запуски не витрачають хвилини на копіювання +Live-model Docker-ранери також bind-mount-ять поточну checkout-копію лише для читання і +розміщують її в тимчасовому workdir усередині контейнера. Це зберігає runtime +image компактним, але все одно запускає Vitest на ваших точних локальних source/config. +Крок staging пропускає великі локальні кеші та результати збірки застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для app каталоги `.build` або +виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання артефактів, специфічних для машини. Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe-и gateway не запускали реальні воркери каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте +`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте `OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити gateway -live-покриття з цього Docker-каналу. -`test:docker:openwebui` — це compatibility smoke вищого рівня: він запускає -контейнер gateway OpenClaw з увімкненими OpenAI-сумісними HTTP-endpoint-ами, -запускає закріплений контейнер Open WebUI проти цього gateway, входить через +live-покриття з цього Docker-лайна. +`test:docker:openwebui` — це smoke-перевірка сумісності вищого рівня: вона запускає +контейнер gateway OpenClaw з увімкненими HTTP-endpoint, сумісними з OpenAI, +запускає pinned контейнер Open WebUI проти цього gateway, входить через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає реальний chat-запит через proxy `/api/chat/completions` Open WebUI. Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження -образу Open WebUI, а сам Open WebUI може завершувати власний cold-start setup. -Цей канал очікує наявність придатного ключа live-моделі, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) є основним способом надати його в Dockerized-запусках. -Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": +образу Open WebUI, а самому Open WebUI може знадобитися завершити власний cold-start setup. +Цей лайн очікує придатний live-ключ моделі, а `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) — основний спосіб надати його в Dockerized-запусках. +Успішні запуски виводять невеликий JSON payload, наприклад `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно є детермінованим і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway -контейнер, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання transcript, metadata вкладень, -поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення каналів + +реального облікового запису Telegram, Discord або iMessage. Він запускає seeded контейнер Gateway, +запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім +перевіряє routed conversation discovery, читання transcript, метадані attachment, +поведінку черги live-подій, маршрутизацію outbound send і сповіщення каналу + дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує сирі stdio MCP-фрейми, тож smoke перевіряє те, що bridge -справді випромінює, а не лише те, що випадково показує конкретний client SDK. +напряму інспектує raw stdio MCP frames, тож smoke перевіряє те, що міст +справді виводить, а не лише те, що випадково показує конкретний client SDK. -Ручний smoke звичайною мовою для ACP thread (не CI): +Ручний smoke plain-language thread ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для регресійних сценаріїв/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. +- Зберігайте цей скрипт для workflows регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. Корисні env-змінні: - `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, підключені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без зовнішніх mount-ів автентифікації CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих установок CLI у Docker -- Зовнішні каталоги/файли автентифікації CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і підвантажується перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, підвантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої auth CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI всередині Docker +- Зовнішні каталоги/файли auth CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` до початку тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Перевизначення вручну: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...` для звуження запуску -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...` для фільтрації провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків без перебудови -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані надходять із profile store (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway надає для smoke Open WebUI + - Можна перевизначити вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна нова збірка +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що creds надходять зі сховища профілів (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити pinned tag образу Open WebUI ## Перевірка документації Запускайте перевірки документації після редагування docs: `pnpm check:docs`. -Запускайте повну перевірку anchor-ів Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Запускайте повну перевірку якірних посилань Mintlify, коли вам також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) Це регресії «реального конвеєра» без реальних провайдерів: -- Виклик інструментів Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, запис конфігурації + примусова автентифікація): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик інструментів gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (кейс: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер gateway (WS `wizard.start`/`wizard.next`, записує config + застосування auth): `src/gateway/gateway.test.ts` (кейс: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агента (Skills) +## Оцінювання надійності agent (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності agent»: - Mock-виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- End-to-end потоки майстра, які перевіряють wiring сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Наскрізні потоки майстра, які перевіряють прив’язку сесії та вплив config (`src/gateway/gateway.test.ts`). -Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого все ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли в prompt перелічено Skills, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Відповідність:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок tool, перенесення історії сесії та межі sandbox. +- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає agent правильний Skill (або уникає нерелевантних)? +- **Відповідність вимогам:** чи читає agent `SKILL.md` перед використанням і чи дотримується обов’язкових кроків/args? +- **Контракти workflow:** multi-turn сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні eval-и мають насамперед залишатися детермінованими: +Майбутні оцінювання мають насамперед залишатися детермінованими: -- Scenario runner із mock-провайдерами для перевірки викликів tool + порядку, читання skill-файлів і wiring сесії. -- Невеликий набір сценаріїв, зосереджених на skill-ах (використати чи уникнути, gating, prompt injection). -- Необов’язкові live eval-и (за явним увімкненням, із gating через env) — лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв із mock-провайдерами для перевірки tool call + порядку, читання skill-файлів і прив’язки сесій. +- Невеликий набір сценаріїв, сфокусованих на Skills (використовувати чи уникати, гейтинг, prompt injection). +- Необов’язкові live-оцінювання (opt-in, з гейтингом через env) — лише після появи безпечного для CI набору. ## Контрактні тести (форма plugin і channel) Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму -контракту інтерфейсу. Вони проходять по всіх виявлених plugin-ах і запускають набір -перевірок форми та поведінки. Типовий unit-канал `pnpm test` навмисно +контракту інтерфейсу. Вони ітеруються по всіх виявлених plugins і запускають набір перевірок +форми та поведінки. Типовий unit-лайн `pnpm test` навмисно пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, -коли зачіпаєте спільні поверхні channel або provider. +коли торкаєтеся спільних поверхонь channel або provider. ### Команди @@ -967,29 +970,29 @@ Open WebUI, перевіряє, що `/api/models` показує `openclaw/defa Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма plugin (`id`, `name`, `capabilities`) +- **plugin** - Базова форма plugin (id, name, capabilities) - **setup** - Контракт майстра налаштування - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel -- **threading** - Обробка ідентифікаторів тредів +- **threading** - Обробка ID тредів - **directory** - API каталогу/списку учасників -- **group-policy** - Застосування групової політики +- **group-policy** - Забезпечення групової політики ### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки статусу channel +- **status** - Проби статусу channel - **registry** - Форма реєстру plugin ### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір/добір автентифікації +- **auth** - Контракт потоку auth +- **auth-choice** - Вибір/селектор auth - **catalog** - API каталогу моделей - **discovery** - Виявлення plugin - **loader** - Завантаження plugin @@ -999,21 +1002,21 @@ Open WebUI, перевіряє, що `/api/models` показує `openclaw/defa ### Коли запускати -- Після зміни export-ів або subpath-ів plugin-sdk -- Після додавання або зміни channel чи provider plugin -- Після рефакторингу реєстрації або виявлення plugin +- Після зміни експортів або subpath у Plugin SDK +- Після додавання або зміни channel чи provider Plugin +- Після рефакторингу реєстрації plugin або виявлення -Контрактні тести запускаються в CI і не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API keys. ## Додавання регресій (рекомендації) Коли ви виправляєте проблему provider/model, виявлену в live: -- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або зафіксуйте точну трансформацію форми запиту) -- Якщо проблема за своєю природою лише live (rate limits, політики автентифікації), залишайте live-тест вузьким і з явним увімкненням через env-змінні -- Віддавайте перевагу найменшому рівню, який виявляє помилку: - - помилка перетворення/повторення запиту provider → direct models test - - помилка конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway -- Захисне правило обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef з metadata реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою на некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або захопіть точну трансформацію форми запиту) +- Якщо проблема за своєю природою лише live (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env-змінні +- Віддавайте перевагу найменшому шару, який ловить баг: + - баг конвертації/повторення запиту provider → тест direct models + - баг конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway +- Guardrail обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef із метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec id відхиляються. + - Якщо ви додаєте нову родину цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. diff --git a/docs/uk/reference/RELEASING.md b/docs/uk/reference/RELEASING.md index 5a408e3e1..451166a14 100644 --- a/docs/uk/reference/RELEASING.md +++ b/docs/uk/reference/RELEASING.md @@ -1,14 +1,14 @@ --- read_when: - - Шукаю визначення публічних каналів випусків - - Шукаю іменування версій і частоту випусків -summary: Публічні канали випусків, іменування версій і частота випусків + - Шукаєте визначення публічних каналів випусків + - Шукаєте назви версій і частоту випусків +summary: Публічні канали випусків, назви версій і частота випусків title: Політика випусків x-i18n: - generated_at: "2026-04-20T12:31:53Z" + generated_at: "2026-04-20T14:13:28Z" model: gpt-5.4 provider: openai - source_hash: 1ce04bd255ae5f13ff5088414c87e865fe56a8a0d0bf6ef6d8d84cb07ef65f18 + source_hash: 281b3fd1764c60cb35a25a12c338595020d7c04bcb662e96c4131193a0607537 source_path: reference/RELEASING.md workflow: 15 --- @@ -21,160 +21,161 @@ OpenClaw має три публічні канали випусків: - beta: теги попередніх випусків, які публікуються в npm `beta` - dev: рухома вершина `main` -## Іменування версій +## Назви версій -- Версія stable-випуску: `YYYY.M.D` +- Версія стабільного випуску: `YYYY.M.D` - Git-тег: `vYYYY.M.D` -- Версія stable-випуску з виправленням: `YYYY.M.D-N` +- Версія випуску стабільного виправлення: `YYYY.M.D-N` - Git-тег: `vYYYY.M.D-N` -- Версія beta попереднього випуску: `YYYY.M.D-beta.N` +- Версія beta prerelease: `YYYY.M.D-beta.N` - Git-тег: `vYYYY.M.D-beta.N` - Не додавайте нулі попереду для місяця або дня -- `latest` означає поточний підвищений stable-випуск у npm +- `latest` означає поточний стабільний випуск npm, який було підвищено - `beta` означає поточну ціль встановлення beta -- Stable-випуски та stable-випуски з виправленнями за замовчуванням публікуються в npm `beta`; оператори випусків можуть явно націлити `latest` або пізніше підвищити перевірену beta-збірку -- Кожен випуск OpenClaw постачається разом як npm-пакет і macOS app +- Стабільні випуски та випуски стабільних виправлень за замовчуванням публікуються в npm `beta`; оператори випусків можуть явно націлюватися на `latest` або підвищити перевірену beta-збірку пізніше +- Кожен випуск OpenClaw одночасно постачає npm package і застосунок macOS ## Частота випусків - Випуски спочатку проходять через beta -- Stable виходить лише після перевірки останньої beta -- Детальна процедура випуску, погодження, облікові дані та примітки щодо відновлення - доступні лише для супроводжувачів +- Stable з’являється лише після перевірки останньої beta +- Детальна процедура випуску, затвердження, облікові дані та примітки щодо відновлення доступні + лише для супроводжувачів -## Передрелізна перевірка +## Попередня перевірка випуску -- Запускайте `pnpm check:architecture` перед передрелізною перевіркою, щоб ширші перевірки - циклів імпорту та меж архітектури були зеленими поза межами швидшого локального циклу -- Запускайте `pnpm build && pnpm ui:build` перед `pnpm release:check`, щоб очікувані - артефакти випуску `dist/*` і пакет Control UI були наявні для кроку +- Виконайте `pnpm check:test-types` перед попередньою перевіркою випуску, щоб тестовий TypeScript лишався + охопленим поза швидшим локальним бар’єром `pnpm check` +- Виконайте `pnpm check:architecture` перед попередньою перевіркою випуску, щоб ширші перевірки + циклів імпорту та меж архітектури були успішними поза швидшим локальним бар’єром +- Виконайте `pnpm build && pnpm ui:build` перед `pnpm release:check`, щоб очікувані + артефакти випуску `dist/*` і bundle Control UI існували для кроку перевірки pack -- Запускайте `pnpm release:check` перед кожним тегованим випуском +- Виконуйте `pnpm release:check` перед кожним тегованим випуском - Перевірки випуску тепер виконуються в окремому ручному workflow: `OpenClaw Release Checks` -- Міжплатформна перевірка встановлення та оновлення під час виконання запускається з - приватного workflow-джерела виклику +- Крос-ОС перевірка встановлення та оновлення під час виконання запускається з + приватного caller workflow `openclaw/releases-private/.github/workflows/openclaw-cross-os-release-checks.yml`, який викликає повторно використовуваний публічний workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` -- Такий поділ навмисний: реальний шлях npm-випуску має залишатися коротким, +- Цей поділ навмисний: він зберігає справжній шлях випуску npm коротким, детермінованим і зосередженим на артефактах, тоді як повільніші live-перевірки залишаються - у власному каналі, щоб не затримувати та не блокувати публікацію -- Перевірки випуску мають запускатися з workflow ref `main`, щоб логіка - workflow та секрети залишалися канонічними + у власному каналі, щоб не затримувати і не блокувати публікацію +- Перевірки випуску мають запускатися з посилання workflow `main`, щоб + логіка workflow і секрети лишалися канонічними - Цей workflow приймає або наявний тег випуску, або поточний повний 40-символьний SHA коміту `main` -- У режимі SHA коміту він приймає лише поточний HEAD `origin/main`; для - старіших комітів випуску використовуйте тег випуску -- Передрелізна перевірка лише для валідації `OpenClaw NPM Release` також приймає поточний - повний 40-символьний SHA коміту `main` без вимоги наявності опублікованого тегу +- У режимі SHA коміту він приймає лише поточний HEAD `origin/main`; використовуйте + тег випуску для старіших комітів випуску +- Попередня перевірка лише для валідації `OpenClaw NPM Release` також приймає поточний + повний 40-символьний SHA коміту `main` без вимоги вже запушеного тега - Цей шлях SHA призначений лише для валідації й не може бути підвищений до реальної публікації -- У режимі SHA workflow синтезує `v` лише для перевірки - метаданих пакета; реальна публікація все одно вимагає реального тегу випуску +- У режимі SHA workflow синтезує `v` лише для перевірки метаданих + package; реальна публікація все одно потребує реального тега випуску - Обидва workflow зберігають реальний шлях публікації та підвищення на GitHub-hosted - runners, тоді як немутуючий шлях валідації може використовувати більші + runners, тоді як немутувальний шлях валідації може використовувати більші Blacksmith Linux runners - Цей workflow запускає `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` - використовуючи обидва секрети workflow: `OPENAI_API_KEY` і `ANTHROPIC_API_KEY` -- Передрелізна перевірка npm-випуску більше не чекає на окремий канал перевірок випуску -- Перед погодженням запускайте - `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - (або відповідний тег beta/виправлення) -- Після публікації в npm запускайте + з використанням обох workflow secrets `OPENAI_API_KEY` і `ANTHROPIC_API_KEY` +- Попередня перевірка випуску npm більше не чекає на окремий канал перевірок випуску +- Виконайте `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` + (або відповідний тег beta/виправлення) перед затвердженням +- Після публікації в npm виконайте `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` (або відповідну версію beta/виправлення), щоб перевірити опублікований шлях - встановлення з реєстру в новому тимчасовому префіксі -- Автоматизація випусків супроводжувачів тепер використовує підхід preflight-then-promote: + встановлення з реєстру в новому тимчасовому prefix +- Автоматизація випусків супроводжувачів тепер використовує схему preflight-then-promote: - реальна публікація в npm має пройти успішний npm `preflight_run_id` - - stable npm-випуски за замовчуванням націлені на `beta` - - stable npm-публікацію можна явно націлити на `latest` через вхідні дані workflow - - зміна npm dist-tag на основі токена тепер знаходиться в + - стабільні випуски npm за замовчуванням спрямовуються в `beta` + - стабільна публікація npm може явно націлюватися на `latest` через вхід workflow + - мутація npm dist-tag на основі токена тепер знаходиться в `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` - з міркувань безпеки, оскільки `npm dist-tag add` досі потребує `NPM_TOKEN`, тоді як - публічний репозиторій зберігає OIDC-only publish + з міркувань безпеки, тому що `npm dist-tag add` усе ще потребує `NPM_TOKEN`, тоді як + публічний репозиторій зберігає публікацію лише через OIDC - публічний `macOS Release` призначений лише для валідації - - реальна приватна mac-публікація має пройти успішні приватні mac + - реальна приватна публікація mac має пройти успішні приватні mac `preflight_run_id` і `validate_run_id` - - реальні шляхи публікації підвищують уже підготовлені артефакти замість того, щоб - знову їх перебудовувати -- Для stable-випусків з виправленнями на кшталт `YYYY.M.D-N` засіб перевірки після публікації - також перевіряє той самий шлях оновлення в тимчасовому префіксі з `YYYY.M.D` до `YYYY.M.D-N`, - щоб виправлення випусків не могли непомітно залишити старі глобальні встановлення на - базовому stable-вмісті -- Передрелізна перевірка npm-випуску завершується помилкою за принципом fail closed, якщо tarball не містить - одночасно `dist/control-ui/index.html` і непорожній вміст `dist/control-ui/assets/`, + - реальні шляхи публікації підвищують уже підготовлені артефакти замість повторного + їх збирання +- Для стабільних випусків виправлень на кшталт `YYYY.M.D-N` постпублікаційний верифікатор + також перевіряє той самий шлях оновлення через тимчасовий prefix з `YYYY.M.D` до `YYYY.M.D-N`, + щоб стабільні виправлення не могли непомітно залишати старі глобальні встановлення на + базовому стабільному payload +- Попередня перевірка випуску npm завершується з помилкою за замовчуванням, якщо tarball не містить і + `dist/control-ui/index.html`, і непорожній payload `dist/control-ui/assets/`, щоб ми знову не випустили порожню панель браузера -- `pnpm test:install:smoke` також примусово перевіряє бюджет `unpackedSize` для npm pack - на tarball кандидата на оновлення, щоб installer e2e виявляв випадкове збільшення pack - до шляху публікації випуску -- Якщо робота над випуском зачепила планування CI, маніфести часу розширень або - матриці тестування розширень, перед погодженням заново згенеруйте й перегляньте - керовані planner виходи матриці workflow `checks-node-extensions` з `.github/workflows/ci.yml`, +- `pnpm test:install:smoke` також примусово застосовує бюджет npm pack `unpackedSize` до + tarball кандидата на оновлення, щоб e2e перевірка інсталятора виявляла випадкове + роздуття pack до шляху публікації випуску +- Якщо робота над випуском торкалася планування CI, маніфестів часу extension або + матриць тестів extension, перед затвердженням заново згенеруйте та перегляньте + виходи матриці workflow `checks-node-extensions`, якими керує planner, з `.github/workflows/ci.yml`, щоб примітки до випуску не описували застарілу структуру CI -- Готовність stable macOS release також включає поверхні оновлювача: - - GitHub release має в результаті містити запаковані `.zip`, `.dmg` і `.dSYM.zip` - - `appcast.xml` у `main` має вказувати на новий stable zip після публікації - - запакований app має зберігати bundle id не для debug, непорожній Sparkle feed - URL і `CFBundleVersion` на рівні або вище канонічного порога збірки Sparkle +- Готовність стабільного випуску macOS також включає поверхні оновлювача: + - GitHub release має врешті містити запаковані `.zip`, `.dmg` і `.dSYM.zip` + - `appcast.xml` у `main` після публікації має вказувати на новий stable zip + - запакований застосунок має зберігати не-debug bundle id, непорожній Sparkle feed + URL і `CFBundleVersion`, не нижчий за канонічний мінімум Sparkle build для цієї версії випуску -## Вхідні дані NPM workflow +## Вхідні параметри workflow NPM -`OpenClaw NPM Release` приймає такі керовані оператором вхідні дані: +`OpenClaw NPM Release` приймає такі керовані оператором вхідні параметри: - `tag`: обов’язковий тег випуску, наприклад `v2026.4.2`, `v2026.4.2-1` або `v2026.4.2-beta.1`; коли `preflight_only=true`, це також може бути поточний - повний 40-символьний SHA коміту `main` для передрелізної перевірки лише для валідації -- `preflight_only`: `true` для лише валідації/збірки/пакування, `false` для + повний 40-символьний SHA коміту `main` для попередньої перевірки лише з валідацією +- `preflight_only`: `true` для лише валідації/збирання/пакування, `false` для реального шляху публікації -- `preflight_run_id`: обов’язковий для реального шляху публікації, щоб workflow повторно використав - підготовлений tarball з успішного запуску передрелізної перевірки -- `npm_dist_tag`: цільовий npm-тег для шляху публікації; за замовчуванням `beta` +- `preflight_run_id`: обов’язковий у реальному шляху публікації, щоб workflow повторно використав + підготовлений tarball з успішного запуску попередньої перевірки +- `npm_dist_tag`: цільовий тег npm для шляху публікації; за замовчуванням `beta` -`OpenClaw Release Checks` приймає такі керовані оператором вхідні дані: +`OpenClaw Release Checks` приймає такі керовані оператором вхідні параметри: -- `ref`: наявний тег випуску або поточний повний 40-символьний коміт - SHA для валідації +- `ref`: наявний тег випуску або поточний повний 40-символьний SHA коміту `main` + для валідації Правила: -- Stable і теги виправлень можуть публікуватися або в `beta`, або в `latest` -- Beta-теги попередніх випусків можуть публікуватися лише в `beta` -- Повний вхідний commit SHA дозволений лише коли `preflight_only=true` -- Режим commit-SHA для перевірок випуску також вимагає поточний HEAD `origin/main` -- Реальний шлях публікації має використовувати той самий `npm_dist_tag`, який використовувався під час передрелізної перевірки; +- Stable і correction теги можуть публікуватися або в `beta`, або в `latest` +- Теги beta prerelease можуть публікуватися лише в `beta` +- Повний SHA коміту дозволений лише коли `preflight_only=true` +- Режим SHA коміту для перевірок випуску також вимагає поточний HEAD `origin/main` +- Реальний шлях публікації має використовувати той самий `npm_dist_tag`, що й під час попередньої перевірки; workflow перевіряє ці метадані перед продовженням публікації -## Послідовність stable npm-випуску +## Послідовність стабільного випуску npm -Під час створення stable npm-випуску: +Під час створення стабільного випуску npm: 1. Запустіть `OpenClaw NPM Release` з `preflight_only=true` - - До появи тегу ви можете використати поточний повний SHA коміту `main` для - dry run передрелізного workflow лише для валідації -2. Виберіть `npm_dist_tag=beta` для звичайного beta-first процесу або `latest` лише - коли ви навмисно хочете прямої stable-публікації -3. Запустіть окремо `OpenClaw Release Checks` з тим самим тегом або - повним поточним SHA `main`, якщо вам потрібне live-покриття prompt cache - - Це навмисно окремо, щоб live-покриття залишалося доступним без - повторного зчеплення довготривалих або нестабільних перевірок із workflow публікації + - Поки тег ще не існує, ви можете використати поточний повний SHA коміту `main` для + dry run попередньої перевірки workflow лише з валідацією +2. Оберіть `npm_dist_tag=beta` для звичайного beta-first потоку, або `latest` лише + якщо ви навмисно хочете пряму стабільну публікацію +3. Запустіть `OpenClaw Release Checks` окремо з тим самим тегом або + повним поточним SHA `main`, коли вам потрібне live-покриття prompt cache + - Це навмисно окремо, щоб live-покриття лишалося доступним без + повторного зв’язування довгих або нестабільних перевірок із workflow публікації 4. Збережіть успішний `preflight_run_id` -5. Знову запустіть `OpenClaw NPM Release` з `preflight_only=false`, тим самим +5. Запустіть `OpenClaw NPM Release` знову з `preflight_only=false`, тим самим `tag`, тим самим `npm_dist_tag` і збереженим `preflight_run_id` 6. Якщо випуск потрапив у `beta`, використайте приватний workflow `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`, - щоб підвищити цю stable-версію з `beta` до `latest` -7. Якщо випуск навмисно був одразу опублікований у `latest`, а `beta` - має відразу наслідувати ту саму stable-збірку, використайте той самий приватний - workflow, щоб спрямувати обидва dist-tag на stable-версію, або дозвольте його запланованій - self-healing синхронізації перемістити `beta` пізніше + щоб підвищити цю стабільну версію з `beta` до `latest` +7. Якщо випуск навмисно було одразу опубліковано в `latest` і `beta` + має відразу слідувати за тією самою стабільною збіркою, використайте той самий приватний + workflow, щоб спрямувати обидва dist-tags на стабільну версію, або дозвольте його плановій + самовідновлювальній синхронізації перемістити `beta` пізніше -Зміна dist-tag знаходиться в приватному репозиторії з міркувань безпеки, оскільки вона досі -вимагає `NPM_TOKEN`, тоді як публічний репозиторій зберігає OIDC-only publish. +Мутація dist-tag живе в приватному репозиторії з міркувань безпеки, тому що вона все ще +потребує `NPM_TOKEN`, тоді як публічний репозиторій зберігає публікацію лише через OIDC. -Це зберігає як шлях прямої публікації, так і шлях підвищення beta-first -задокументованими й видимими для операторів. +Це робить як шлях прямої публікації, так і шлях beta-first promotion +задокументованими та видимими для операторів. ## Публічні посилання @@ -187,4 +188,4 @@ OpenClaw має три публічні канали випусків: Супроводжувачі використовують приватну документацію щодо випусків у [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) -як фактичну інструкцію. +як фактичний runbook. diff --git a/docs/uk/reference/test.md b/docs/uk/reference/test.md index 920cffb67..cfb7b53f5 100644 --- a/docs/uk/reference/test.md +++ b/docs/uk/reference/test.md @@ -1,60 +1,61 @@ --- read_when: - Запуск або виправлення тестів -summary: Як локально запускати тести (vitest) і коли використовувати режими force/coverage +summary: Як запускати тести локально (vitest) і коли використовувати режими force/coverage title: Тести x-i18n: - generated_at: "2026-04-07T08:14:26Z" + generated_at: "2026-04-20T14:13:23Z" model: gpt-5.4 provider: openai - source_hash: f7c19390f7577b3a29796c67514c96fe4c86c9fa0c7686cd4e377c6e31dcd085 + source_hash: 03c44e5e4fab11883d9af416141d3e8013360a46b7c201ad9ac7cee5e6b3d24e source_path: reference/test.md workflow: 15 --- # Тести -- Повний набір інструментів для тестування (набори тестів, live, Docker): [Тестування](/uk/help/testing) +- Повний набір для тестування (набори тестів, live, Docker): [Тестування](/uk/help/testing) -- `pnpm test:force`: Завершує будь-який завислий процес gateway, що утримує типовий порт керування, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб тести сервера не конфліктували із запущеним екземпляром. Використовуйте це, якщо попередній запуск gateway залишив порт 18789 зайнятим. -- `pnpm test:coverage`: Запускає набір модульних тестів із покриттям V8 (через `vitest.unit.config.ts`). Глобальні пороги становлять 70% для рядків/гілок/функцій/інструкцій. Із покриття виключено точки входу з великою інтеграційною складовою (зв’язування CLI, мости gateway/telegram, статичний сервер webchat), щоб ціль залишалася зосередженою на логіці, придатній для модульного тестування. -- `pnpm test:coverage:changed`: Запускає покриття модульних тестів лише для файлів, змінених відносно `origin/main`. -- `pnpm test:changed`: розгортає змінені git-шляхи в цільові lanes Vitest, якщо diff торкається лише маршрутизовних файлів коду/тестів. Зміни конфігурації/налаштування все одно повертаються до нативного запуску кореневих проєктів, щоб зміни у зв’язуванні за потреби повторно запускали тести ширше. -- `pnpm test`: спрямовує явні цілі файлів/каталогів через цільові lanes Vitest. Запуски без указання цілі тепер виконують одинадцять послідовних конфігурацій shard (`vitest.full-core-unit-src.config.ts`, `vitest.full-core-unit-security.config.ts`, `vitest.full-core-unit-ui.config.ts`, `vitest.full-core-unit-support.config.ts`, `vitest.full-core-support-boundary.config.ts`, `vitest.full-core-contracts.config.ts`, `vitest.full-core-bundled.config.ts`, `vitest.full-core-runtime.config.ts`, `vitest.full-agentic.config.ts`, `vitest.full-auto-reply.config.ts`, `vitest.full-extensions.config.ts`) замість одного великого процесу кореневого проєкту. -- Вибрані тестові файли `plugin-sdk` і `commands` тепер спрямовуються через окремі легкі lanes, які залишають лише `test/setup.ts`, а важкі з погляду runtime сценарії — у наявних lanes. -- Вибрані допоміжні файли коду `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними сусідніми тестами в цих легких lanes, щоб невеликі зміни в допоміжних функціях не спричиняли повторний запуск важких наборів із підтримкою runtime. -- `auto-reply` тепер також розділено на три окремі конфігурації (`core`, `top-level`, `reply`), щоб harness reply не домінував над легшими тестами верхнього рівня для status/token/helper. -- Базова конфігурація Vitest тепер типово використовує `pool: "threads"` і `isolate: false`, а спільний неізольований runner увімкнено в усіх конфігураціях репозиторію. +- `pnpm test:force`: Завершує будь-який завислий процес gateway, що утримує типовий control port, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб серверні тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив зайнятим порт 18789. +- `pnpm test:coverage`: Запускає набір unit-тестів із покриттям V8 (через `vitest.unit.config.ts`). Глобальні пороги становлять 70% для рядків/гілок/функцій/інструкцій. Із покриття виключені entrypoint-и з важкою інтеграцією (CLI wiring, мости gateway/telegram, статичний сервер webchat), щоб ціль залишалася зосередженою на логіці, придатній для unit-тестування. +- `pnpm test:coverage:changed`: Запускає покриття unit-тестів лише для файлів, змінених відносно `origin/main`. +- `pnpm test:changed`: розгортає змінені git-шляхи в обмежені lane-и Vitest, коли diff торкається лише routable файлів source/test. Зміни конфігурації/налаштування все ще повертаються до нативного запуску root projects, тож зміни wiring за потреби повторно запускаються ширше. +- `pnpm test`: спрямовує явні цілі файлів/каталогів через обмежені lane-и Vitest. Нетаргетовані запуски тепер виконують одинадцять послідовних shard-конфігурацій (`vitest.full-core-unit-src.config.ts`, `vitest.full-core-unit-security.config.ts`, `vitest.full-core-unit-ui.config.ts`, `vitest.full-core-unit-support.config.ts`, `vitest.full-core-support-boundary.config.ts`, `vitest.full-core-contracts.config.ts`, `vitest.full-core-bundled.config.ts`, `vitest.full-core-runtime.config.ts`, `vitest.full-agentic.config.ts`, `vitest.full-auto-reply.config.ts`, `vitest.full-extensions.config.ts`) замість одного гігантського процесу root-project. +- Вибрані тестові файли `plugin-sdk` і `commands` тепер спрямовуються через окремі легкі lane-и, які залишають лише `test/setup.ts`, а runtime-важкі випадки — у наявних lane-ах. +- Вибрані вихідні helper-файли `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними сусідніми тестами в цих легких lane-ах, тож невеликі зміни helper-ів не змушують повторно запускати важкі набори з підтримкою runtime. +- `auto-reply` тепер також поділяється на три окремі конфігурації (`core`, `top-level`, `reply`), щоб harness для reply не домінував над легшими тестами статусу/token/helper верхнього рівня. +- Базова конфігурація Vitest тепер за замовчуванням використовує `pool: "threads"` та `isolate: false`, із увімкненим спільним неізольованим runner-ом у всіх конфігураціях репозиторію. - `pnpm test:channels` запускає `vitest.channels.config.ts`. - `pnpm test:extensions` запускає `vitest.extensions.config.ts`. -- `pnpm test:extensions`: запускає набори тестів extension/plugin. -- `pnpm test:perf:imports`: вмикає звітування Vitest про тривалість імпорту та деталізацію імпорту, і при цьому все ще використовує маршрутизацію через цільові lanes для явних цілей файлів/каталогів. -- `pnpm test:perf:imports:changed`: те саме профілювання імпорту, але лише для файлів, змінених відносно `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутний шлях режиму changed із нативним запуском кореневого проєкту для того самого зафіксованого git diff. -- `pnpm test:perf:changed:bench -- --worktree` порівнює поточний набір змін у worktree без попереднього коміту. -- `pnpm test:perf:profile:main`: записує CPU profile для головного потоку Vitest (`.artifacts/vitest-main-profile`). -- `pnpm test:perf:profile:runner`: записує профілі CPU + heap для unit runner (`.artifacts/vitest-runner-profile`). -- Інтеграція gateway: увімкнення за бажанням через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. -- `pnpm test:e2e`: запускає наскрізні smoke-тести gateway (багатоекземплярне сполучення WS/HTTP/node). Типово використовує `threads` + `isolate: false` з адаптивною кількістю workers у `vitest.e2e.config.ts`; налаштовуйте через `OPENCLAW_E2E_WORKERS=` і встановіть `OPENCLAW_E2E_VERBOSE=1` для докладних логів. -- `pnpm test:live`: запускає live-тести provider (minimax/zai). Потребує API-ключів і `LIVE=1` (або специфічного для provider `*_LIVE_TEST=1`) для зняття пропуску. -- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, виконує вхід через Open WebUI, перевіряє `/api/models`, а потім запускає реальний проксійований чат через `/api/chat/completions`. Потребує придатного ключа live-моделі (наприклад, OpenAI у `~/.profile`), завантажує зовнішній образ Open WebUI і не очікується як стабільний для CI, як звичайні набори unit/e2e. -- `pnpm test:docker:mcp-channels`: запускає seeded-контейнер Gateway і другий клієнтський контейнер, який запускає `openclaw mcp serve`, а потім перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення в стилі Claude про channel + permission через реальний міст stdio. Перевірка сповіщень Claude читає необроблені кадри stdio MCP напряму, щоб smoke-тест відображав те, що міст насправді надсилає. +- `pnpm test:extensions`: запускає набори розширень/Plugin-ів. +- `pnpm test:perf:imports`: вмикає звітність Vitest щодо тривалості імпорту та розбивки імпортів, при цьому для явних цілей файлів/каталогів усе ще використовується спрямування через обмежені lane-и. +- `pnpm test:perf:imports:changed`: те саме профілювання імпортів, але лише для файлів, змінених відносно `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` виконує бенчмарк спрямованого режиму changed-mode проти нативного запуску root-project для того самого закоміченого git diff. +- `pnpm test:perf:changed:bench -- --worktree` виконує бенчмарк поточного набору змін робочого дерева без попереднього коміту. +- `pnpm test:perf:profile:main`: записує CPU-профіль для головного потоку Vitest (`.artifacts/vitest-main-profile`). +- `pnpm test:perf:profile:runner`: записує CPU- та heap-профілі для unit runner-а (`.artifacts/vitest-runner-profile`). +- Інтеграція Gateway: вмикається через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. +- `pnpm test:e2e`: запускає наскрізні smoke-тести gateway (парування multi-instance WS/HTTP/node). За замовчуванням використовує `threads` + `isolate: false` з адаптивною кількістю workers у `vitest.e2e.config.ts`; налаштовуйте через `OPENCLAW_E2E_WORKERS=` і встановлюйте `OPENCLAW_E2E_VERBOSE=1` для докладних логів. +- `pnpm test:live`: запускає live-тести provider-ів (minimax/zai). Потребує API-ключів і `LIVE=1` (або специфічного для provider `*_LIVE_TEST=1`) для зняття пропуску. +- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, входить через Open WebUI, перевіряє `/api/models`, а потім виконує реальний проксійований чат через `/api/chat/completions`. Потребує придатного live-ключа моделі (наприклад, OpenAI у `~/.profile`), завантажує зовнішній образ Open WebUI і не розрахований на таку стабільність у CI, як звичайні набори unit/e2e. +- `pnpm test:docker:mcp-channels`: запускає seeded контейнер Gateway і другий клієнтський контейнер, який запускає `openclaw mcp serve`, а потім перевіряє виявлення маршрутизованих розмов, читання transcript, метадані attachment, поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення про channel + permission у стилі Claude через реальний міст stdio. Перевірка сповіщень Claude читає сирі кадри stdio MCP безпосередньо, тож smoke відповідає тому, що міст реально надсилає. ## Локальний PR gate -Для локальних перевірок перед приземленням/проходженням gate PR запустіть: +Для локальних перевірок перед злиттям/пропуском PR виконайте: - `pnpm check` +- `pnpm check:test-types` - `pnpm build` - `pnpm test` - `pnpm check:docs` -Якщо `pnpm test` дає нестабільний збій на завантаженому хості, перезапустіть один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test `. Для хостів з обмеженою пам’яттю використовуйте: +Якщо `pnpm test` дає нестабільний збій на навантаженому хості, перезапустіть один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test `. Для хостів з обмеженою пам’яттю використовуйте: - `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test` - `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed` -## Бенчмарк затримки моделі (локальні ключі) +## Бенч латентності моделі (локальні ключі) Скрипт: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts) @@ -62,14 +63,14 @@ x-i18n: - `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10` - Необов’язкові env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY` -- Типовий prompt: “Відповідай одним словом: ok. Без розділових знаків або зайвого тексту.” +- Типовий prompt: “Reply with a single word: ok. No punctuation or extra text.” Останній запуск (2025-12-31, 20 запусків): - minimax median 1279ms (min 1114, max 2431) - opus median 2454ms (min 1224, max 3170) -## Бенчмарк запуску CLI +## Бенч запуску CLI Скрипт: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts) @@ -90,25 +91,25 @@ x-i18n: - `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu` - `pnpm tsx scripts/bench-cli-startup.ts --json` -Набори preset: +Набори preset-ів: - `startup`: `--version`, `--help`, `health`, `health --json`, `status --json`, `status` - `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port` -- `all`: обидва presets +- `all`: обидва набори preset-ів -Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і зведення max RSS для кожної команди. Необов’язковий `--cpu-prof-dir` / `--heap-prof-dir` записує профілі V8 для кожного запуску, щоб вимірювання часу та захоплення профілю використовували той самий harness. +Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і зведення max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8-профілі для кожного запуску, щоб вимірювання часу та збирання профілів використовували один і той самий harness. -Умовні позначення для збереженого виводу: +Угоди щодо збереженого виводу: - `pnpm test:startup:bench:smoke` записує цільовий smoke-артефакт у `.artifacts/cli-startup-bench-smoke.json` -- `pnpm test:startup:bench:save` записує артефакт повного набору в `.artifacts/cli-startup-bench-all.json` з використанням `runs=5` і `warmup=1` -- `pnpm test:startup:bench:update` оновлює закомічений baseline fixture у `test/fixtures/cli-startup-bench.json` з використанням `runs=5` і `warmup=1` +- `pnpm test:startup:bench:save` записує артефакт повного набору в `.artifacts/cli-startup-bench-all.json`, використовуючи `runs=5` і `warmup=1` +- `pnpm test:startup:bench:update` оновлює закомічений baseline fixture у `test/fixtures/cli-startup-bench.json`, використовуючи `runs=5` і `warmup=1` Закомічений fixture: - `test/fixtures/cli-startup-bench.json` -- Оновіть за допомогою `pnpm test:startup:bench:update` -- Порівняйте поточні результати з fixture за допомогою `pnpm test:startup:bench:check` +- Оновлення: `pnpm test:startup:bench:update` +- Порівняння поточних результатів із fixture: `pnpm test:startup:bench:check` ## Onboarding E2E (Docker) @@ -120,11 +121,11 @@ Docker необов’язковий; це потрібно лише для cont scripts/e2e/onboard-docker.sh ``` -Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`. +Цей скрипт проводить інтерактивний майстер через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`. -## QR import smoke (Docker) +## Smoke-тест імпорту QR (Docker) -Гарантує, що `qrcode-terminal` завантажується в підтримуваних Docker runtime Node (типово Node 24, сумісно з Node 22): +Гарантує, що `qrcode-terminal` завантажується у підтримуваних Docker runtime Node (типово Node 24, сумісно з Node 22): ```bash pnpm test:docker:qr