diff --git a/docs/uk/ci.md b/docs/uk/ci.md index 5ca9f7588..a32680449 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,75 +1,75 @@ --- read_when: - - Вам потрібно зрозуміти, чому завдання CI виконалося або не виконалося - - Ви налагоджуєте невдалу перевірку GitHub Actions - - Ви координуєте запуск або повторний запуск перевірки релізу -summary: Граф завдань CI, контрольні перевірки за областю, парасолькові релізні процеси та локальні еквіваленти команд -title: Конвеєр CI + - Вам потрібно зрозуміти, чому завдання CI запустилося чи не запустилося + - Ви налагоджуєте перевірку GitHub Actions, яка завершується невдачею + - Ви координуєте запуск або повторний запуск валідації релізу +summary: Граф завдань CI, межі області дії, парасольки випусків і локальні еквіваленти команд +title: CI-конвеєр x-i18n: - generated_at: "2026-05-01T20:36:51Z" + generated_at: "2026-05-01T20:49:28Z" model: gpt-5.5 provider: openai - source_hash: db8f529b1f373d31aef3dac963d71cff575bc24b808a6ad1fa1c20a1725ad994 + source_hash: e7bd0c3eca0730b9121cb7971f46924451b0377515fd326352f72499c37103bd source_path: ci.md workflow: 16 --- -OpenClaw CI запускається на кожному push до `main` і для кожного pull request. Завдання `preflight` класифікує diff і вимикає дорогі lanes, коли змінено лише непов’язані області. Ручні запуски `workflow_dispatch` навмисно оминають розумне обмеження scope і розгортають повний граф для release candidates та широкої валідації. Android lanes залишаються opt-in через `include_android`. Release-only покриття plugin міститься в окремому workflow [`Plugin Prerelease`](#plugin-prerelease) і запускається лише з [`Full Release Validation`](#full-release-validation) або явного ручного dispatch. +OpenClaw CI запускається під час кожного push до `main` і кожного pull request. Завдання `preflight` класифікує diff і вимикає дорогі лінії, коли змінилися лише неповʼязані області. Ручні запуски `workflow_dispatch` навмисно обходять розумне обмеження області й розгортають повний граф для release candidate і широкої валідації. Android-лінії лишаються opt-in через `include_android`. Покриття плагінів лише для релізу міститься в окремому workflow [`Передреліз Plugin`](#plugin-prerelease) і запускається лише з [`Повної релізної валідації`](#full-release-validation) або через явний ручний dispatch. ## Огляд pipeline -| Завдання | Призначення | Коли запускається | -| -------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------- | -| `preflight` | Виявляє docs-only зміни, змінені scopes, змінені extensions і будує CI manifest | Завжди для non-draft pushes і PRs | -| `security-scm-fast` | Виявлення приватних ключів і audit workflow через `zizmor` | Завжди для non-draft pushes і PRs | -| `security-dependency-audit` | Production lockfile audit без встановлення залежностей щодо npm advisories | Завжди для non-draft pushes і PRs | -| `security-fast` | Обов’язковий aggregate для швидких security jobs | Завжди для non-draft pushes і PRs | -| `check-dependencies` | Production Knip dependency-only pass плюс guard allowlist невикористаних файлів | Node-релевантні зміни | -| `build-artifacts` | Збірка `dist/`, Control UI, перевірки built artifacts і reusable downstream artifacts | Node-релевантні зміни | -| `checks-fast-core` | Швидкі Linux correctness lanes, як-от bundled/plugin-contract/protocol checks | Node-релевантні зміни | -| `checks-fast-contracts-channels` | Sharded перевірки channel contract зі стабільним aggregate check result | Node-релевантні зміни | -| `checks-node-core-test` | Core Node test shards, без channel, bundled, contract і extension lanes | Node-релевантні зміни | -| `check` | Sharded еквівалент головного локального gate: prod types, lint, guards, test types і strict smoke | Node-релевантні зміни | -| `check-additional` | Architecture, boundary, extension-surface guards, package-boundary і gateway-watch shards | Node-релевантні зміни | -| `build-smoke` | Built-CLI smoke tests і startup-memory smoke | Node-релевантні зміни | -| `checks` | Verifier для built-artifact channel tests | Node-релевантні зміни | -| `checks-node-compat-node22` | Node 22 compatibility build і smoke lane | Ручний CI dispatch для releases | -| `check-docs` | Форматування docs, lint і broken-link checks | Docs змінено | -| `skills-python` | Ruff + pytest для Python-backed skills | Python-skill-релевантні зміни | -| `checks-windows` | Windows-specific process/path tests плюс shared runtime import specifier regressions | Windows-релевантні зміни | -| `macos-node` | macOS TypeScript test lane із shared built artifacts | macOS-релевантні зміни | -| `macos-swift` | Swift lint, build і tests для macOS app | macOS-релевантні зміни | -| `android` | Android unit tests для обох flavors плюс одна debug APK build | Android-релевантні зміни | -| `test-performance-agent` | Щоденна оптимізація повільних tests у Codex після trusted activity | Успіх Main CI або ручний dispatch | +| Завдання | Призначення | Коли запускається | +| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | +| `preflight` | Виявляє зміни лише в docs, змінені області, змінені розширення та будує CI manifest | Завжди на non-draft push і PR | +| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди на non-draft push і PR | +| `security-dependency-audit` | Аудит production lockfile без залежностей щодо npm advisories | Завжди на non-draft push і PR | +| `security-fast` | Обовʼязковий aggregate для швидких security-завдань | Завжди на non-draft push і PR | +| `check-dependencies` | Production Knip dependency-only pass плюс guard allowlist невикористаних файлів | Зміни, релевантні для Node | +| `build-artifacts` | Збірка `dist/`, Control UI, перевірки built-artifact і багаторазові downstream artifacts | Зміни, релевантні для Node | +| `checks-fast-core` | Швидкі Linux-лінії коректності, як-от bundled/plugin-contract/protocol checks | Зміни, релевантні для Node | +| `checks-fast-contracts-channels` | Sharded перевірки контрактів каналів зі стабільним aggregate check result | Зміни, релевантні для Node | +| `checks-node-core-test` | Шарди тестів Core Node, окрім channel, bundled, contract і extension ліній | Зміни, релевантні для Node | +| `check` | Sharded еквівалент основного локального gate: prod types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | +| `check-additional` | Architecture, boundary, extension-surface guards, package-boundary і gateway-watch shards | Зміни, релевантні для Node | +| `build-smoke` | Smoke-тести built-CLI і smoke startup-memory | Зміни, релевантні для Node | +| `checks` | Verifier для built-artifact channel tests | Зміни, релевантні для Node | +| `checks-node-compat-node22` | Збірка сумісності з Node 22 і smoke-лінія | Ручний CI dispatch для релізів | +| `check-docs` | Перевірки форматування docs, lint і broken-link | Docs змінено | +| `skills-python` | Ruff + pytest для Python-backed skills | Зміни, релевантні для Python skills | +| `checks-windows` | Специфічні для Windows тести process/path плюс спільні регресії runtime import specifier | Зміни, релевантні для Windows | +| `macos-node` | Лінія macOS TypeScript тестів із використанням спільних built artifacts | Зміни, релевантні для macOS | +| `macos-swift` | Swift lint, build і tests для macOS app | Зміни, релевантні для macOS | +| `android` | Android unit tests для обох flavors плюс одна debug APK build | Зміни, релевантні для Android | +| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після trusted activity | Успіх Main CI або manual dispatch | ## Порядок fail-fast -1. `preflight` вирішує, які lanes взагалі існують. Логіка `docs-scope` і `changed-scope` є steps усередині цього job, а не окремими jobs. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко падають, не очікуючи важчих artifact і platform matrix jobs. -3. `build-artifacts` перекривається зі швидкими Linux lanes, щоб downstream consumers могли стартувати щойно shared build буде готовий. -4. Після цього розгортаються важчі platform і runtime lanes: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. +1. `preflight` вирішує, які лінії взагалі існують. Логіка `docs-scope` і `changed-scope` є кроками всередині цього завдання, а не окремими завданнями. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко падають, не чекаючи на важчі artifact і platform matrix jobs. +3. `build-artifacts` перекривається зі швидкими Linux-лініями, щоб downstream consumers могли стартувати щойно спільна збірка готова. +4. Після цього розгортаються важчі platform і runtime лінії: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. -GitHub може позначати superseded jobs як `cancelled`, коли новіший push потрапляє в той самий PR або `main` ref. Сприймайте це як CI noise, якщо найновіший run для того самого ref також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тому вони все ще повідомляють звичайні shard failures, але не стають у queue після того, як увесь workflow уже superseded. Автоматичний CI concurrency key версіонований (`CI-v7-*`), щоб GitHub-side zombie у старій queue group не міг безкінечно блокувати новіші main runs. Ручні full-suite runs використовують `CI-manual-v1-*` і не скасовують in-progress runs. +GitHub може позначати superseded jobs як `cancelled`, коли новіший push потрапляє в той самий PR або `main` ref. Сприймайте це як шум CI, якщо найновіший run для того самого ref також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тому вони все одно повідомляють звичайні shard failures, але не стають у чергу після того, як увесь workflow уже superseded. Automatic CI concurrency key версіонований (`CI-v7-*`), щоб GitHub-side zombie у старій queue group не міг безстроково блокувати новіші main runs. Manual full-suite runs використовують `CI-manual-v1-*` і не скасовують in-progress runs. -## Scope і routing +## Область і маршрутизація -Логіка scope міститься в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`. Manual dispatch пропускає changed-scope detection і змушує preflight manifest поводитися так, ніби кожна scoped area змінилася. +Логіка області міститься в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`. Manual dispatch пропускає changed-scope detection і змушує preflight manifest діяти так, ніби змінилася кожна scoped area. -- **CI workflow edits** валідують Node CI graph плюс workflow linting, але самі по собі не форсують Windows, Android або macOS native builds; ці platform lanes залишаються scoped до platform source changes. -- **CI routing-only edits, вибрані cheap core-test fixture edits і вузькі plugin contract helper/test-routing edits** використовують fast Node-only manifest path: `preflight`, security і єдине завдання `checks-fast-core`. Цей path пропускає build artifacts, Node 22 compatibility, channel contracts, full core shards, bundled-plugin shards і additional guard matrices, коли зміна обмежена routing або helper surfaces, які fast task перевіряє напряму. -- **Windows Node checks** scoped до Windows-specific process/path wrappers, npm/pnpm/UI runner helpers, package manager config і CI workflow surfaces, які виконують цю lane; непов’язані source, plugin, install-smoke і test-only зміни залишаються на Linux Node lanes. +- **Редагування CI workflow** валідовують Node CI graph плюс workflow linting, але самі собою не примушують Windows, Android або macOS native builds; ці platform lanes лишаються scoped до змін platform source. +- **Редагування лише маршрутизації CI, вибрані дешеві core-test fixture edits і вузькі plugin contract helper/test-routing edits** використовують швидкий Node-only manifest path: `preflight`, security і одне завдання `checks-fast-core`. Цей шлях пропускає build artifacts, Node 22 compatibility, channel contracts, full core shards, bundled-plugin shards і additional guard matrices, коли зміна обмежена routing або helper surfaces, які fast task перевіряє напряму. +- **Windows Node checks** обмежені Windows-specific process/path wrappers, npm/pnpm/UI runner helpers, package manager config і CI workflow surfaces, які виконують цю лінію; неповʼязані source, plugin, install-smoke і test-only changes лишаються на Linux Node lanes. -Найповільніші Node test families розділено або збалансовано, щоб кожен job залишався малим без надмірного резервування runners: channel contracts запускаються як три weighted shards, малі core unit lanes об’єднуються в пари, auto-reply запускається як чотири збалансовані workers (із reply subtree, розділеним на agent-runner, dispatch і commands/state-routing shards), а agentic gateway/plugin configs розподіляються між наявними source-only agentic Node jobs замість очікування built artifacts. Broad browser, QA, media і miscellaneous plugin tests використовують свої dedicated Vitest configs замість shared plugin catch-all. Include-pattern shards записують timing entries із назвою CI shard, тому `.artifacts/vitest-shard-timings.json` може відрізнити whole config від filtered shard. `check-additional` тримає package-boundary compile/canary work разом і відокремлює runtime topology architecture від gateway watch coverage; boundary guard shard запускає свої малі independent guards паралельно в одному job. Gateway watch, channel tests і core support-boundary shard запускаються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані. +Найповільніші сімейства Node tests розділені або збалансовані так, щоб кожне завдання лишалося малим без надмірного резервування runners: channel contracts запускаються як три weighted shards, малі core unit lanes обʼєднані парами, auto-reply запускається як чотири збалансовані workers (з reply subtree, розділеним на agent-runner, dispatch і commands/state-routing shards), а agentic gateway/plugin configs розподілені між наявними source-only agentic Node jobs замість очікування built artifacts. Широкі browser, QA, media і miscellaneous plugin tests використовують свої dedicated Vitest configs замість спільного plugin catch-all. Include-pattern shards записують timing entries із CI shard name, тому `.artifacts/vitest-shard-timings.json` може відрізнити цілий config від filtered shard. `check-additional` тримає package-boundary compile/canary work разом і відокремлює runtime topology architecture від gateway watch coverage; boundary guard shard запускає свої малі independent guards паралельно всередині одного job. Gateway watch, channel tests і core support-boundary shard запускаються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane все одно компілює flavor з BuildConfig flags для SMS/call-log, уникаючи водночас дублювання debug APK packaging job на кожному Android-релевантному push. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane все одно компілює flavor із SMS/call-log BuildConfig flags, водночас уникаючи дублювання debug APK packaging job на кожному Android-relevant push. -Shard `check-dependencies` запускає `pnpm deadcode:dependencies` (production Knip dependency-only pass, pinned до найновішої версії Knip, із вимкненим pnpm minimum release age для встановлення `dlx`) і `pnpm deadcode:unused-files`, який порівнює production unused-file findings Knip із `scripts/deadcode-unused-files.allowlist.mjs`. Unused-file guard падає, коли PR додає новий unreviewed unused file або залишає stale allowlist entry, зберігаючи intentional dynamic plugin, generated, build, live-test і package bridge surfaces, які Knip не може resolve статично. +Shard `check-dependencies` запускає `pnpm deadcode:dependencies` (production Knip dependency-only pass, pinned до найновішої версії Knip, із вимкненим minimum release age pnpm для `dlx` install) і `pnpm deadcode:unused-files`, який порівнює production unused-file findings Knip з `scripts/deadcode-unused-files.allowlist.mjs`. Unused-file guard падає, коли PR додає новий непереглянутий unused file або лишає stale allowlist entry, водночас зберігаючи intentional dynamic plugin, generated, build, live-test і package bridge surfaces, які Knip не може статично розвʼязати. ## Ручні dispatches -Manual CI dispatches запускають той самий job graph, що й звичайний CI, але примусово вмикають кожну non-Android scoped lane: Linux Node shards, bundled-plugin shards, channel contracts, Node 22 compatibility, `check`, `check-additional`, build smoke, docs checks, Python skills, Windows, macOS і Control UI i18n. Standalone manual CI dispatches запускають Android лише з `include_android=true`; full release umbrella вмикає Android, передаючи `include_android=true`. Plugin prerelease static checks, release-only shard `agentic-plugins`, full extension batch sweep і plugin prerelease Docker lanes виключені з CI. Docker prerelease suite запускається лише тоді, коли `Full Release Validation` dispatches окремий workflow `Plugin Prerelease` з увімкненим release-validation gate. +Manual CI dispatches запускають той самий job graph, що й normal CI, але примусово вмикають кожну non-Android scoped lane: Linux Node shards, bundled-plugin shards, channel contracts, Node 22 compatibility, `check`, `check-additional`, build smoke, docs checks, Python skills, Windows, macOS і Control UI i18n. Standalone manual CI dispatches запускають Android лише з `include_android=true`; full release umbrella вмикає Android, передаючи `include_android=true`. Plugin prerelease static checks, release-only shard `agentic-plugins`, full extension batch sweep і plugin prerelease Docker lanes виключені з CI. Docker prerelease suite запускається лише тоді, коли `Full Release Validation` dispatches окремий workflow `Plugin Prerelease` з увімкненим release-validation gate. -Manual runs використовують унікальну concurrency group, тому release-candidate full suite не скасовується іншим push або PR run на тому самому ref. Optional input `target_ref` дає trusted caller змогу запустити цей graph для branch, tag або full commit SHA, використовуючи workflow file з вибраного dispatch ref. +Manual runs використовують унікальну concurrency group, тому release-candidate full suite не скасовується іншим push або PR run на тому самому ref. Необовʼязковий input `target_ref` дає trusted caller змогу запускати цей graph для branch, tag або full commit SHA, використовуючи workflow file з вибраного dispatch ref. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -79,15 +79,15 @@ gh workflow run full-release-validation.yml --ref main -f ref= ## Runners -| Виконавець | Завдання | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки протоколу/контрактів/вбудованого, шардовані перевірки контрактів каналів, шарди `check`, окрім lint, шарди й агрегати `check-additional`, агрегатні верифікатори тестів Node, перевірки документації, Python Skills, workflow-sanity, labeler, auto-response; install-smoke preflight також використовує GitHub-хостований Ubuntu, щоб матриця Blacksmith могла стати в чергу раніше | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, менш ресурсомісткі шарди Plugin, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` і `check-test-types` | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди тестів Linux Node, шарди тестів вбудованих Plugin, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (достатньо чутливий до CPU, тому 8 vCPU коштували більше, ніж заощаджували); install-smoke Docker-збірки (час очікування в черзі для 32-vCPU коштував більше, ніж заощаджував) | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node` на `openclaw/openclaw`; форки повертаються до `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; форки повертаються до `macos-latest` | +| Виконавець | Завдання | +| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки протоколу/контрактів/пакетних компонентів, шардовані перевірки контрактів каналів, шарди `check`, крім lint, шарди й агрегати `check-additional`, агрегатні верифікатори тестів Node, перевірки документації, Python Skills, workflow-sanity, labeler, auto-response; install-smoke preflight також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла стати в чергу раніше | +| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, легші шарди Plugin, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` і `check-test-types` | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди тестів Linux Node, шарди тестів пакетних plugin, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (достатньо чутливий до CPU, щоб 8 vCPU коштували більше, ніж заощаджували); Docker-збірки install-smoke (час очікування черги 32-vCPU коштував більше, ніж заощаджував) | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `macos-node` на `openclaw/openclaw`; форки повертаються до `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; форки повертаються до `macos-latest` | ## Локальні еквіваленти @@ -117,37 +117,39 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac ## Повна валідація релізу -`Full Release Validation` — це ручний парасольковий workflow для «запустити все перед релізом». Він приймає гілку, тег або повний SHA коміту, запускає ручний workflow `CI` з цією ціллю, запускає `Plugin Prerelease` для релізних доказів Plugin/пакета/статики/Docker і запускає `OpenClaw Release Checks` для install smoke, package acceptance, наборів release-path для Docker, live/E2E, OpenWebUI, QA Lab parity, Matrix і Telegram lanes. Він також може запускати постпублікаційний workflow `NPM Telegram Beta E2E`, коли надано специфікацію опублікованого пакета. +`Full Release Validation` — це ручний парасольковий workflow для «запустити все перед релізом». Він приймає гілку, тег або повний SHA коміту, запускає ручний workflow `CI` із цією ціллю, запускає `Plugin Prerelease` для релізного підтвердження plugin/package/static/Docker і запускає `OpenClaw Release Checks` для install smoke, package acceptance, наборів Docker release-path, live/E2E, OpenWebUI, QA Lab parity, Matrix і Telegram lanes. Він також може запускати після публікації workflow `NPM Telegram Beta E2E`, коли надано специфікацію опублікованого пакета. -Див. [Повну валідацію релізу](/uk/reference/full-release-validation) для +Див. [повну валідацію релізу](/uk/reference/full-release-validation) для матриці етапів, точних назв завдань workflow, відмінностей профілів, артефактів і -цільових способів повторного запуску. +точкових дескрипторів повторного запуску. -`release_profile` керує широтою live/provider, що передається в release checks. Ручні release workflows за замовчуванням використовують `stable`; використовуйте `full` лише тоді, коли навмисно потрібна широка консультативна матриця provider/media. +`release_profile` керує широтою live/provider, що передається в release checks. Ручні +release workflows за замовчуванням використовують `stable`; використовуйте `full` лише тоді, коли ви +навмисно хочете широку advisory-матрицю provider/media. -- `minimum` зберігає найшвидші критичні для релізу lanes OpenAI/core. +- `minimum` зберігає найшвидші критичні для релізу OpenAI/core lanes. - `stable` додає стабільний набір provider/backend. -- `full` запускає широку консультативну матрицю provider/media. +- `full` запускає широку advisory-матрицю provider/media. -Парасолька записує ідентифікатори запущених дочірніх виконань, а фінальне завдання `Verify full validation` повторно перевіряє поточні висновки дочірніх виконань і додає таблиці найповільніших завдань для кожного дочірнього виконання. Якщо дочірній workflow перезапущено й він стає зеленим, перезапустіть лише батьківське завдання verifier, щоб оновити результат парасольки та підсумок часу. +Парасолька записує ідентифікатори запущених дочірніх run, а фінальне завдання `Verify full validation` повторно перевіряє поточні висновки дочірніх run і додає таблиці найповільніших завдань для кожного дочірнього run. Якщо дочірній workflow перезапущено і він стає зеленим, перезапустіть лише батьківське завдання verifier, щоб оновити результат парасольки та підсумок таймінгів. -Для відновлення і `Full Release Validation`, і `OpenClaw Release Checks` приймають `rerun_group`. Використовуйте `all` для реліз-кандидата, `ci` лише для звичайного дочірнього full CI, `plugin-prerelease` лише для дочірнього plugin prerelease, `release-checks` для кожного дочірнього релізного виконання або вужчу групу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` чи `npm-telegram` у парасольці. Це утримує повторний запуск невдалого release box у межах після цільового виправлення. +Для відновлення і `Full Release Validation`, і `OpenClaw Release Checks` приймають `rerun_group`. Використовуйте `all` для release candidate, `ci` лише для звичайного дочірнього full CI, `plugin-prerelease` лише для дочірнього plugin prerelease, `release-checks` для кожного дочірнього release або вужчу групу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` або `npm-telegram` у парасольці. Це утримує повторний запуск невдалого release box у межах після точкового виправлення. -`OpenClaw Release Checks` використовує довірене посилання workflow, щоб один раз розв’язати вибране посилання в tarball `release-package-under-test`, а потім передає цей артефакт і live/E2E release-path Docker workflow, і шарду package acceptance. Це зберігає байти пакета узгодженими між release boxes і уникає повторного пакування того самого кандидата в кількох дочірніх завданнях. +`OpenClaw Release Checks` використовує довірений ref workflow, щоб один раз розв’язати вибраний ref у tarball `release-package-under-test`, а потім передає цей артефакт і в Docker workflow release-path live/E2E, і в shard package acceptance. Це зберігає байти пакета узгодженими між release boxes і уникає повторного пакування того самого кандидата в кількох дочірніх завданнях. -Дублікати запусків `Full Release Validation` для `ref=main` і `rerun_group=all` +Дубльовані run `Full Release Validation` для `ref=main` і `rerun_group=all` замінюють старішу парасольку. Батьківський монітор скасовує будь-який дочірній workflow, який -він уже запустив, коли батьківський запуск скасовано, тому новіша валідація main -не чекає за застарілим двогодинним запуском release-check. Валідація release branch/tag -і цільові групи повторного запуску зберігають `cancel-in-progress: false`. +він уже запустив, коли батьківський скасовано, тому новіша валідація main +не стоїть за застарілим двогодинним release-check run. Валідація release branch/tag +і точкові групи повторного запуску зберігають `cancel-in-progress: false`. -## Live і E2E шарди +## Live та E2E шарди Дочірній release live/E2E зберігає широке нативне покриття `pnpm test:live`, але запускає його як іменовані шарди через `scripts/test-live-shard.mjs` замість одного послідовного завдання: - `native-live-src-agents` - `native-live-src-gateway-core` -- provider-filtered завдання `native-live-src-gateway-profiles` +- відфільтровані за provider завдання `native-live-src-gateway-profiles` - `native-live-src-gateway-backends` - `native-live-test` - `native-live-extensions-a-k` @@ -155,35 +157,35 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac - `native-live-extensions-openai` - `native-live-extensions-o-z-other` - `native-live-extensions-xai` -- розділені медіашарди audio/video і provider-filtered шарди music +- розділені шарди media audio/video та відфільтровані за provider музичні шарди -Це зберігає те саме покриття файлів, водночас спрощуючи повторний запуск і діагностику повільних live-збоїв provider. Агреговані назви шардів `native-live-extensions-o-z`, `native-live-extensions-media` і `native-live-extensions-media-music` залишаються чинними для ручних одноразових повторних запусків. +Це зберігає те саме файлове покриття, водночас спрощуючи повторний запуск і діагностику повільних live-збоїв provider. Агрегатні назви шардів `native-live-extensions-o-z`, `native-live-extensions-media` і `native-live-extensions-media-music` залишаються чинними для ручних одноразових повторних запусків. -Нативні live media шарди працюють у `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, створеному workflow `Live Media Runner Image`. Цей образ попередньо встановлює `ffmpeg` і `ffprobe`; медіазавдання лише перевіряють бінарні файли перед налаштуванням. Тримайте Docker-backed live suites на звичайних Blacksmith runners — container jobs є неправильним місцем для запуску вкладених Docker-тестів. +Нативні шарди live media запускаються в `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, зібраному workflow `Live Media Runner Image`. Цей image попередньо встановлює `ffmpeg` і `ffprobe`; media jobs лише перевіряють бінарні файли перед налаштуванням. Тримайте live-набори з Docker на звичайних Blacksmith runners — container jobs є неправильним місцем для запуску вкладених Docker tests. -Docker-backed live model/backend шарди використовують окремий спільний образ `ghcr.io/openclaw/openclaw-live-test:` для кожного вибраного коміту. Live release workflow один раз збирає й надсилає цей образ, після чого Docker live model, provider-sharded gateway, CLI backend, ACP bind і Codex harness шарди запускаються з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway Docker шарди мають явні обмеження `timeout` на рівні скриптів нижче за timeout завдання workflow, щоб завислий контейнер або шлях очищення швидко завершувався помилкою замість споживання всього бюджету release-check. Якщо ці шарди незалежно перебудовують повну source Docker target, release run налаштовано неправильно, і він витрачатиме реальний час на дубльовані збірки образів. +Docker-backed live model/backend шарди використовують окремий спільний image `ghcr.io/openclaw/openclaw-live-test:` для кожного вибраного коміту. Live release workflow збирає й публікує цей image один раз, після чого Docker live model, provider-sharded Gateway, CLI backend, ACP bind і Codex harness шарди запускаються з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway Docker shards мають явні обмеження `timeout` на рівні script нижче за timeout workflow job, щоб завислий container або cleanup path швидко падав, а не споживав увесь бюджет release-check. Якщо ці шарди незалежно перебудовують повну source Docker target, release run неправильно налаштований і марнуватиме wall clock на дубльовані збірки image. -## Package Acceptance +## Приймання пакета -Використовуйте `Package Acceptance`, коли питання таке: «чи працює цей інстальований пакет OpenClaw як продукт?» Це відрізняється від звичайного CI: звичайний CI валідує дерево джерельного коду, тоді як package acceptance валідує один tarball через той самий Docker E2E harness, який користувачі задіюють після інсталяції або оновлення. +Використовуйте `Package Acceptance`, коли питання звучить як «чи працює цей інстальований пакет OpenClaw як продукт?» Це відрізняється від звичайного CI: звичайний CI валідує source tree, тоді як package acceptance валідує один tarball через той самий Docker E2E harness, який користувачі виконують після встановлення або оновлення. ### Завдання -1. `resolve_package` виконує checkout `workflow_ref`, визначає одного кандидата пакета, записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як артефакт `package-under-test` і виводить джерело, workflow ref, package ref, версію, SHA-256 і профіль у підсумку кроку GitHub. -2. `docker_acceptance` викликає `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і `package_artifact_name=package-under-test`. Багаторазовий workflow завантажує цей артефакт, перевіряє інвентар tarball, за потреби готує Docker-образи package-digest і запускає вибрані Docker-доріжки для цього пакета замість пакування checkout workflow. Коли профіль вибирає кілька цільових `docker_lanes`, багаторазовий workflow один раз готує пакет і спільні образи, а потім розгортає ці доріжки як паралельні цільові Docker-завдання з унікальними артефактами. -3. `package_telegram` необов’язково викликає `NPM Telegram Beta E2E`. Він запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, коли Package Acceptance визначив його; автономний dispatch Telegram все ще може встановити опубліковану npm-специфікацію. -4. `summary` завершує workflow з помилкою, якщо визначення пакета, Docker acceptance або необов’язкова доріжка Telegram завершилися невдало. +1. `resolve_package` перевіряє `workflow_ref`, визначає одного кандидата пакета, записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як артефакт `package-under-test` і виводить джерело, посилання workflow, посилання пакета, версію, SHA-256 і профіль у зведенні кроку GitHub. +2. `docker_acceptance` викликає `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і `package_artifact_name=package-under-test`. Повторно використовуваний workflow завантажує цей артефакт, перевіряє інвентар tarball, за потреби готує Docker-образи з дайджестом пакета й запускає вибрані Docker-доріжки для цього пакета замість пакування checkout workflow. Коли профіль вибирає кілька цільових `docker_lanes`, повторно використовуваний workflow один раз готує пакет і спільні образи, а потім розгортає ці доріжки як паралельні цільові Docker-завдання з унікальними артефактами. +3. `package_telegram` необов’язково викликає `NPM Telegram Beta E2E`. Він запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, якщо Package Acceptance визначив його; окремий Telegram dispatch усе ще може встановити опубліковану npm-специфікацію. +4. `summary` завершує workflow з помилкою, якщо не вдалося визначити пакет, пройти Docker acceptance або необов’язкову Telegram-доріжку. ### Джерела кандидатів -- `source=npm` приймає лише `openclaw@beta`, `openclaw@latest` або точну версію релізу OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для acceptance опублікованих beta/stable. -- `source=ref` пакує довірену гілку, тег або повний commit SHA з `package_ref`. Resolver отримує гілки/теги OpenClaw, перевіряє, що вибраний commit досяжний з історії гілки репозиторію або релізного тегу, встановлює залежності у detached worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`. +- `source=npm` приймає лише `openclaw@beta`, `openclaw@latest` або точну версію релізу OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для перевірки опублікованих beta/stable. +- `source=ref` пакує довірену гілку, тег або повний commit SHA з `package_ref`. Резолвер отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт досяжний з історії гілки репозиторію або тега релізу, встановлює залежності у від’єднаному worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`. - `source=url` завантажує HTTPS `.tgz`; `package_sha256` є обов’язковим. -- `source=artifact` завантажує один `.tgz` з `artifact_run_id` і `artifact_name`; `package_sha256` необов’язковий, але його варто вказувати для артефактів, поширених назовні. +- `source=artifact` завантажує один `.tgz` з `artifact_run_id` і `artifact_name`; `package_sha256` необов’язковий, але його варто вказувати для артефактів, що поширюються зовнішньо. -Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це довірений код workflow/тестового каркаса, який запускає тест. `package_ref` — це вихідний commit, який пакується, коли `source=ref`. Це дає змогу поточному тестовому каркасу перевіряти старіші довірені вихідні commits без запуску старої логіки workflow. +Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це довірений код workflow/тестового harness, який запускає тест. `package_ref` — це коміт джерела, який пакується, коли `source=ref`. Це дає змогу поточному тестовому harness перевіряти старі довірені коміти джерела без запуску старої логіки workflow. -### Профілі наборів +### Профілі набору - `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload` - `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `plugins-offline`, `plugin-update` @@ -191,21 +193,21 @@ Docker-backed live model/backend шарди використовують окр - `full` — повні фрагменти Docker release-path з OpenWebUI - `custom` — точні `docker_lanes`; обов’язково, коли `suite_profile=custom` -Профіль `package` використовує офлайн-покриття плагінів, щоб перевірка опублікованого пакета не залежала від доступності live ClawHub. Необов’язкова доріжка Telegram повторно використовує артефакт `package-under-test` у `NPM Telegram Beta E2E`, а шлях опублікованої npm-специфікації зберігається для автономних dispatch. +Профіль `package` використовує покриття офлайн-Plugin, щоб перевірка опублікованого пакета не залежала від доступності живого ClawHub. Необов’язкова Telegram-доріжка повторно використовує артефакт `package-under-test` у `NPM Telegram Beta E2E`, а шлях опублікованої npm-специфікації зберігається для окремих dispatch. -Release checks викликають Package Acceptance з `source=ref`, `package_ref=`, `workflow_ref=`, `suite_profile=custom`, `docker_lanes='plugins-offline plugin-update'` і `telegram_mode=mock-openai`. Docker-фрагменти release-path покривають суміжні доріжки package/update/plugin; Package Acceptance зберігає офлайн-докази для plugin, update і Telegram щодо того самого визначеного tarball пакета. Cross-OS release checks все ще покривають OS-специфічні onboarding, installer і platform behavior; перевірку package/update product слід починати з Package Acceptance. Docker-доріжка `published-upgrade-survivor` перевіряє один опублікований базовий пакет за запуск. У Package Acceptance визначений tarball `package-under-test` завжди є кандидатом, а `published_upgrade_survivor_baseline` вибирає fallback опубліковану baseline, типово `openclaw@latest`; команди повторного запуску невдалих доріжок зберігають цю baseline. Задайте `published_upgrade_survivor_baselines=release-history`, щоб розгорнути доріжку в deduped history matrix: шість останніх stable-релізів, `2026.4.23` і останній stable-реліз перед `2026-03-15`. Задайте `published_upgrade_survivor_scenarios=reported-issues`, щоб розгорнути ті самі baselines на issue-shaped fixtures для конфігурації Feishu, збережених bootstrap/persona файлів, шляхів логів з tilde і застарілих коренів залежностей legacy plugin. Локальні агреговані запуски можуть передавати точні package specs через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, залишати одну доріжку з `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, наприклад `openclaw@2026.4.15`, або задавати `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` для матриці сценаріїв. Опублікована доріжка налаштовує baseline за допомогою вбудованого рецепта команди `openclaw config set`, записує кроки рецепта в `summary.json` і перевіряє `/healthz`, `/readyz`, а також статус RPC після старту Gateway. Windows packaged і installer fresh lanes також перевіряють, що встановлений пакет може імпортувати browser-control override із сирого абсолютного шляху Windows. Cross-OS agent-turn smoke для OpenAI типово використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли його задано, інакше `openai/gpt-5.4-mini`, щоб install і gateway proof залишалися швидкими та детермінованими. +Перевірки релізу викликають Package Acceptance із `source=ref`, `package_ref=`, `workflow_ref=`, `suite_profile=custom`, `docker_lanes='plugins-offline plugin-update'` і `telegram_mode=mock-openai`. Docker-фрагменти release-path покривають перехресні доріжки package/update/plugin; Package Acceptance зберігає офлайн-докази для Plugin, update і Telegram на тому самому визначеному package tarball. Cross-OS перевірки релізу все ще покривають специфічну для ОС поведінку onboarding, installer і platform; перевірку продукту package/update слід починати з Package Acceptance. Docker-доріжка `published-upgrade-survivor` перевіряє одну опубліковану базову лінію пакета за запуск. У Package Acceptance визначений tarball `package-under-test` завжди є кандидатом, а `published_upgrade_survivor_baseline` вибирає fallback опубліковану базову лінію, за замовчуванням `openclaw@latest`; команди повторного запуску невдалих доріжок зберігають цю базову лінію. Встановіть `published_upgrade_survivor_baselines=release-history`, щоб розширити доріжку до дедуплікованої матриці історії: шість останніх стабільних релізів, `2026.4.23` і останній стабільний реліз до `2026-03-15`. Встановіть `published_upgrade_survivor_scenarios=reported-issues`, щоб розширити ті самі базові лінії на issue-подібні fixture для конфігурації Feishu, збережених bootstrap/persona-файлів, шляхів журналів із тильдою та застарілих коренів залежностей legacy Plugin. Локальні агреговані запуски можуть передавати точні специфікації пакетів через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, зберігати одну доріжку з `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, наприклад `openclaw@2026.4.15`, або встановити `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` для матриці сценаріїв. Опублікована доріжка налаштовує базову лінію за допомогою вбудованого рецепта команди `openclaw config set`, записує кроки рецепта в `summary.json` і перевіряє `/healthz`, `/readyz`, а також статус RPC після старту Gateway. Свіжі доріжки Windows packaged та installer також перевіряють, що встановлений пакет може імпортувати browser-control override із raw абсолютного шляху Windows. Cross-OS agent-turn smoke для OpenAI за замовчуванням використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, якщо його встановлено, інакше `openai/gpt-5.5`, тож докази install і gateway лишаються на бажаній тестовій моделі GPT-5. ### Вікна сумісності з legacy -Package Acceptance має обмежені вікна legacy-сумісності для вже опублікованих пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть використовувати шлях сумісності: +Package Acceptance має обмежені вікна сумісності з legacy для вже опублікованих пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть використовувати шлях сумісності: -- відомі приватні QA-записи в `dist/postinstall-inventory.json` можуть вказувати на файли, пропущені в tarball; -- `doctor-switch` може пропустити підвипадок збереження `gateway install --wrapper`, коли пакет не надає цей flag; -- `update-channel-switch` може вилучати відсутні `pnpm.patchedDependencies` з fake git fixture, отриманої з tarball, і може логувати відсутній збережений `update.channel`; -- plugin smokes можуть читати legacy розташування install-record або приймати відсутнє збереження marketplace install-record; -- `plugin-update` може дозволяти міграцію config metadata, водночас все ще вимагаючи, щоб install record і поведінка no-reinstall залишалися незмінними. +- відомі приватні QA-записи в `dist/postinstall-inventory.json` можуть вказувати на файли, пропущені з tarball; +- `doctor-switch` може пропускати підвипадок збереження `gateway install --wrapper`, коли пакет не надає цей прапорець; +- `update-channel-switch` може обрізати відсутні `pnpm.patchedDependencies` з tarball-похідного фальшивого git fixture і може логувати відсутній збережений `update.channel`; +- plugin smokes можуть читати legacy-розташування install-record або приймати відсутнє збереження marketplace install-record; +- `plugin-update` може дозволяти міграцію метаданих конфігурації, водночас усе ще вимагаючи, щоб install record і поведінка без перевстановлення лишалися незмінними. -Опублікований пакет `2026.4.26` також може попереджати про local build metadata stamp files, які вже були поставлені. Пізніші пакети мають відповідати сучасним контрактам; ті самі умови спричиняють помилку замість попередження або пропуску. +Опублікований пакет `2026.4.26` також може попереджати про файли штампів метаданих локальної збірки, які вже були випущені. Пізніші пакети мають відповідати сучасним контрактам; ті самі умови призводять до помилки, а не попередження чи пропуску. ### Приклади @@ -248,152 +250,152 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -Під час налагодження невдалого запуску package acceptance почніть із підсумку `resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перегляньте дочірній запуск `docker_acceptance` і його Docker-артефакти: `.artifacts/docker-tests/**/summary.json`, `failures.json`, логи доріжок, timings фаз і команди повторного запуску. Віддавайте перевагу повторному запуску невдалого package profile або точних Docker-доріжок, а не повторному запуску всієї release validation. +Під час налагодження невдалого запуску package acceptance починайте зі зведення `resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перевірте дочірній запуск `docker_acceptance` і його Docker-артефакти: `.artifacts/docker-tests/**/summary.json`, `failures.json`, журнали доріжок, таймінги фаз і команди повторного запуску. Надавайте перевагу повторному запуску невдалого профілю пакета або точних Docker-доріжок замість повторного запуску повної перевірки релізу. ## Install smoke Окремий workflow `Install Smoke` повторно використовує той самий scope script через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. -- **Швидкий шлях** запускається для pull requests, що зачіпають Docker/package surfaces, зміни package/manifest bundled plugin або core plugin/channel/gateway/Plugin SDK surfaces, які перевіряють Docker smoke jobs. Зміни лише у вихідному коді bundled plugin, test-only edits і docs-only edits не резервують Docker workers. Швидкий шлях один раз збирає образ root Dockerfile, перевіряє CLI, запускає CLI smoke для agents delete shared-workspace, запускає container gateway-network e2e, перевіряє bundled extension build arg і запускає обмежений bundled-plugin Docker profile з 240-секундним aggregate command timeout (Docker run кожного сценарію обмежено окремо). -- **Повний шлях** зберігає QR package install та installer Docker/update coverage для нічних scheduled runs, manual dispatches, workflow-call release checks і pull requests, які справді зачіпають installer/package/Docker surfaces. У full mode install-smoke готує або повторно використовує один target-SHA GHCR root Dockerfile smoke image, а потім запускає QR package install, root Dockerfile/gateway smokes, installer/update smokes і fast bundled-plugin Docker E2E як окремі jobs, щоб installer work не чекала після root image smokes. +- **Швидкий шлях** запускається для pull request, що торкаються Docker/package-поверхонь, змін package/manifest для bundled Plugin або core plugin/channel/gateway/Plugin SDK-поверхонь, які перевіряють Docker smoke jobs. Зміни лише в джерелі bundled Plugin, тестові правки та правки лише документації не резервують Docker workers. Швидкий шлях один раз збирає root Dockerfile image, перевіряє CLI, запускає CLI smoke для agents delete shared-workspace, запускає container gateway-network e2e, перевіряє build arg bundled extension і запускає обмежений Docker-профіль bundled-plugin під 240-секундним загальним таймаутом команди (кожен Docker-запуск сценарію обмежується окремо). +- **Повний шлях** зберігає встановлення QR package та installer Docker/update-покриття для нічних запланованих запусків, ручних dispatch, workflow-call перевірок релізу й pull request, які справді торкаються installer/package/Docker-поверхонь. У повному режимі install-smoke готує або повторно використовує один target-SHA GHCR root Dockerfile smoke image, а потім запускає QR package install, root Dockerfile/gateway smokes, installer/update smokes і швидкий bundled-plugin Docker E2E як окремі завдання, щоб робота installer не чекала за root image smokes. -Пуші в `main` (включно з merge commits) не примушують повний шлях; коли changed-scope logic запросила б full coverage на push, workflow залишає fast Docker smoke, а full install smoke лишає для nightly або release validation. +Пуші в `main` (включно з merge commits) не примушують повний шлях; коли логіка changed-scope запитувала б повне покриття під час push, workflow зберігає швидкий Docker smoke і залишає повний install smoke для нічної або релізної перевірки. -Повільний Bun global install image-provider smoke окремо керується через `run_bun_global_install_smoke`. Він запускається за nightly schedule і з release checks workflow, а manual `Install Smoke` dispatches можуть увімкнути його, але pull requests і пуші в `main` — ні. QR і installer Docker tests зберігають власні install-focused Dockerfiles. +Повільний Bun global install image-provider smoke окремо керується `run_bun_global_install_smoke`. Він запускається за нічним розкладом і з workflow перевірок релізу, а ручні dispatch `Install Smoke` можуть його ввімкнути, але pull request і пуші в `main` — ні. QR і installer Docker tests зберігають власні install-focused Dockerfile. ## Локальний Docker E2E `pnpm test:docker:all` попередньо збирає один спільний live-test image, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`: - bare Node/Git runner для доріжок installer/update/plugin-dependency; -- функціональний образ, який встановлює той самий tarball у `/app` для звичайних functionality lanes. +- функціональний образ, який встановлює той самий tarball у `/app` для звичайних функціональних доріжок. -Визначення Docker-доріжок розміщені в `scripts/lib/docker-e2e-scenarios.mjs`, логіка planner — у `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний plan. Scheduler вибирає образ для кожної доріжки через `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає доріжки з `OPENCLAW_SKIP_DOCKER_BUILD=1`. +Визначення Docker-доріжок містяться в `scripts/lib/docker-e2e-scenarios.mjs`, логіка planner — у `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний план. Scheduler вибирає образ для кожної доріжки за допомогою `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає доріжки з `OPENCLAW_SKIP_DOCKER_BUILD=1`. -### Параметри налаштування +### Налаштування -| Змінна | Типове значення | Призначення | -| ------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------- | -| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Кількість слотів основного пулу для звичайних смуг. | -| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Кількість слотів хвостового пулу, чутливого до провайдерів. | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Ліміт одночасних live-смуг, щоб провайдери не застосовували throttling. | -| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Ліміт одночасних смуг установлення npm. | -| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Ліміт одночасних багатосервісних смуг. | -| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Затримка між стартами смуг, щоб уникнути штормів створення в демоні Docker; задайте `0`, щоб вимкнути затримку. | -| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Резервний тайм-аут для кожної смуги (120 хвилин); вибрані live/хвостові смуги використовують жорсткіші ліміти. | -| `OPENCLAW_DOCKER_ALL_DRY_RUN` | не задано | `1` друкує план планувальника без запуску смуг. | -| `OPENCLAW_DOCKER_ALL_LANES` | не задано | Розділений комами точний список смуг; пропускає cleanup smoke, щоб агенти могли відтворити одну невдалу смугу. | +| Змінна | За замовчуванням | Призначення | +| -------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------- | +| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Кількість слотів основного пулу для звичайних ліній. | +| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Кількість слотів хвостового пулу, чутливого до провайдера. | +| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Обмеження одночасних live-ліній, щоб провайдери не застосовували throttling. | +| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Обмеження одночасних ліній встановлення npm. | +| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Обмеження одночасних багатосервісних ліній. | +| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Затримка між стартами ліній, щоб уникнути хвиль створення в Docker daemon; встановіть `0`, щоб вимкнути затримку. | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Резервний тайм-аут для кожної лінії (120 хвилин); вибрані live/хвостові лінії використовують жорсткіші обмеження. | +| `OPENCLAW_DOCKER_ALL_DRY_RUN` | не встановлено | `1` друкує план планувальника без запуску ліній. | +| `OPENCLAW_DOCKER_ALL_LANES` | не встановлено | Розділений комами точний список ліній; пропускає cleanup smoke, щоб агенти могли відтворити одну невдалу лінію. | -Смуга, важча за свій ефективний ліміт, усе одно може стартувати з порожнього пулу, а потім виконується самостійно, доки не звільнить місткість. Локальний агрегат попередньо перевіряє Docker, видаляє застарілі контейнери OpenClaw E2E, виводить статус активних смуг, зберігає час виконання смуг для впорядкування від найдовших до найкоротших і типово припиняє планувати нові pooled-смуги після першого збою. +Лінія, важча за своє ефективне обмеження, все одно може стартувати з порожнього пулу, а потім виконуватися самостійно, доки не звільнить місткість. Локальний aggregate виконує попередні перевірки Docker, видаляє застарілі контейнери OpenClaw E2E, виводить статус активних ліній, зберігає таймінги ліній для впорядкування від найдовших до найкоротших і за замовчуванням припиняє планувати нові pooled-лінії після першої помилки. ### Багаторазовий live/E2E workflow -Багаторазовий live/E2E workflow запитує в `scripts/test-docker-all.mjs --plan-json`, яке покриття пакета, типу образу, live-образу, смуги та облікових даних потрібне. Потім `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і зведення. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, або завантажує артефакт пакета з поточного запуску, або завантажує артефакт пакета з `package_artifact_run_id`; перевіряє інвентар tarball; збирає та надсилає bare/functional Docker E2E-образи GHCR із тегом digest пакета через кеш шарів Docker від Blacksmith, коли план потребує смуг з установленим пакетом; і повторно використовує надані входи `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні образи з digest пакета замість повторної збірки. Завантаження Docker-образів повторюються з обмеженим тайм-аутом 180 секунд на спробу, щоб завислий потік registry/cache швидко повторювався, а не споживав більшу частину критичного шляху CI. +Багаторазовий live/E2E workflow запитує `scripts/test-docker-all.mjs --plan-json`, яке покриття package, типу image, live image, лінії та облікових даних потрібне. Потім `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і summaries. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує артефакт package з поточного запуску, або завантажує артефакт package з `package_artifact_run_id`; перевіряє inventory tarball; збирає та публікує tagged за package-digest bare/functional GHCR Docker E2E images через Docker layer cache Blacksmith, коли плану потрібні лінії з установленим package; і повторно використовує надані inputs `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні package-digest images замість повторної збірки. Завантаження Docker image повторюються з обмеженим 180-секундним тайм-аутом на спробу, щоб завислий registry/cache stream швидко повторювався, а не споживав більшу частину критичного шляху CI. ### Фрагменти release-path -Покриття Release Docker запускає менші фрагментовані jobs з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен фрагмент завантажував лише потрібний йому тип образу й виконував кілька смуг через той самий зважений планувальник: +Release Docker coverage запускає менші chunked jobs з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk завантажував лише потрібний йому тип image і виконував кілька ліній через той самий weighted scheduler: - `OPENCLAW_DOCKER_ALL_PROFILE=release-path` - `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h` -Поточні фрагменти Release Docker: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` і від `plugins-runtime-install-a` до `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` залишаються агрегатними псевдонімами Plugin/runtime. Псевдонім смуги `install-e2e` залишається агрегатним псевдонімом ручного повторного запуску для обох смуг установника провайдера. +Поточні Release Docker chunks: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` і від `plugins-runtime-install-a` до `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` залишаються aggregate aliases Plugin/runtime. Псевдонім лінії `install-e2e` залишається aggregate manual rerun alias для обох ліній встановлювачів провайдерів. -OpenWebUI включається в `plugins-runtime-services`, коли це запитує повне покриття release-path, і зберігає окремий фрагмент `openwebui` лише для dispatch лише OpenWebUI. Смуги оновлення bundled-channel один раз повторюються в разі тимчасових мережевих збоїв npm. +OpenWebUI включається в `plugins-runtime-services`, коли це запитує повне release-path coverage, і зберігає окремий chunk `openwebui` лише для dispatches, що стосуються тільки OpenWebUI. Bundled-channel update lanes повторюють спробу один раз у разі тимчасових мережевих помилок npm. -Кожен фрагмент вивантажує `.artifacts/docker-tests/` з журналами смуг, часом виконання, `summary.json`, `failures.json`, часом фаз, JSON плану планувальника, таблицями повільних смуг і командами повторного запуску для кожної смуги. Вхід workflow `docker_lanes` запускає вибрані смуги проти підготовлених образів замість jobs фрагментів, що обмежує налагодження невдалої смуги одним цільовим Docker job і готує, завантажує або повторно використовує артефакт пакета для цього запуску; якщо вибрана смуга є live Docker-смугою, цільовий job локально збирає образ live-test для цього повторного запуску. Згенеровані команди повторного запуску GitHub для кожної смуги містять `package_artifact_run_id`, `package_artifact_name` і входи підготовлених образів, коли ці значення існують, щоб невдала смуга могла повторно використати точний пакет і образи з невдалого запуску. +Кожен chunk завантажує `.artifacts/docker-tests/` з logs ліній, timings, `summary.json`, `failures.json`, phase timings, scheduler plan JSON, slow-lane tables і per-lane rerun commands. Input workflow `docker_lanes` запускає вибрані лінії проти підготовлених images замість chunk jobs, що утримує налагодження невдалої лінії в межах одного targeted Docker job і готує, завантажує або повторно використовує артефакт package для цього запуску; якщо вибрана лінія є live Docker lane, targeted job локально збирає live-test image для цього повторного запуску. Згенеровані per-lane GitHub rerun commands містять `package_artifact_run_id`, `package_artifact_name` і prepared image inputs, коли ці значення існують, щоб невдала лінія могла повторно використати точний package та images з невдалого запуску. ```bash -pnpm test:docker:rerun # download Docker artifacts and print combined/per-lane targeted rerun commands -pnpm test:docker:timings # slow-lane and phase critical-path summaries +pnpm test:docker:rerun # завантажити Docker artifacts і надрукувати combined/per-lane targeted rerun commands +pnpm test:docker:timings # summaries slow-lane і phase critical-path ``` -Запланований live/E2E workflow щодня запускає повний набір Docker release-path. +Scheduled live/E2E workflow щодня запускає повний release-path Docker suite. -## Prerelease Plugin +## Передреліз Plugin -`Plugin Prerelease` є дорожчим покриттям продукту/пакета, тому це окремий workflow, який запускається `Full Release Validation` або явним оператором. Звичайні pull requests, push у `main` і окремі ручні CI dispatches не запускають цей набір. Він балансує bundled Plugin tests між вісьмома extension workers; ці shard jobs extensions запускають до двох груп конфігурації Plugin одночасно з одним Vitest worker на групу й більшим heap Node, щоб import-heavy пакети Plugin не створювали додаткові CI jobs. Release-only шлях Docker prerelease групує цільові Docker-смуги в невеликі групи, щоб не резервувати десятки runners для jobs тривалістю від однієї до трьох хвилин. +`Plugin Prerelease` є дорожчим product/package coverage, тому це окремий workflow, який запускається `Full Release Validation` або явним оператором. Звичайні pull requests, pushes у `main` і standalone manual CI dispatches тримають цей suite вимкненим. Він балансує bundled plugin tests між вісьмома extension workers; ці extension shard jobs запускають до двох plugin config groups одночасно з одним Vitest worker на групу та більшим heap Node, щоб import-heavy plugin batches не створювали додаткових CI jobs. Release-only Docker prerelease path групує targeted Docker lanes у малі групи, щоб не резервувати десятки runners для завдань на одну-три хвилини. ## QA Lab -QA Lab має виділені CI-смуги поза основним smart-scoped workflow. +QA Lab має виділені CI lanes поза основним smart-scoped workflow. -- Workflow `Parity gate` запускається для відповідних змін PR і ручного dispatch; він збирає приватний QA runtime і порівнює mock GPT-5.5 та Opus 4.6 agentic packs. -- Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і за ручним dispatch; він розгортає mock parity gate, live Matrix-смугу та live Telegram і Discord смуги як паралельні jobs. Live jobs використовують середовище `qa-live-shared`, а Telegram/Discord використовують Convex leases. +- Workflow `Parity gate` запускається на відповідних PR changes і manual dispatch; він збирає private QA runtime і порівнює mock GPT-5.5 та Opus 4.6 agentic packs. +- Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через manual dispatch; він розгортає mock parity gate, live Matrix lane, а також live Telegram і Discord lanes як parallel jobs. Live jobs використовують environment `qa-live-shared`, а Telegram/Discord використовують Convex leases. -Release checks запускають Matrix і Telegram live transport lanes з детермінованим mock provider і mock-qualified models (`mock-openai/gpt-5.5` та `mock-openai/gpt-5.5-alt`), щоб контракт каналу був ізольований від затримки live model і звичайного запуску provider-Plugin. Live transport Gateway вимикає пошук памʼяті, оскільки QA parity окремо покриває поведінку памʼяті; підключення провайдера покривається окремими наборами live model, native provider і Docker provider. +Release checks запускають Matrix і Telegram live transport lanes з deterministic mock provider і mock-qualified models (`mock-openai/gpt-5.5` та `mock-openai/gpt-5.5-alt`), щоб channel contract був ізольований від затримки live model і звичайного запуску provider-plugin. Live transport gateway вимикає memory search, оскільки QA parity окремо покриває поведінку memory; provider connectivity покривається окремими suites live model, native provider і Docker provider. -Matrix використовує `--profile fast` для запланованих і release gates, додаючи `--fail-fast` лише тоді, коли checked-out CLI це підтримує. Типове значення CLI та вхід ручного workflow залишаються `all`; ручний dispatch `matrix_profile=all` завжди розбиває повне покриття Matrix на jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. +Matrix використовує `--profile fast` для scheduled і release gates, додаючи `--fail-fast` лише тоді, коли checked-out CLI це підтримує. Значення CLI за замовчуванням і manual workflow input залишаються `all`; manual dispatch `matrix_profile=all` завжди ділить повне Matrix coverage на jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. -`OpenClaw Release Checks` також запускає release-critical смуги QA Lab перед схваленням релізу; його QA parity gate запускає candidate і baseline packs як паралельні lane jobs, а потім завантажує обидва артефакти в невеликий report job для остаточного порівняння parity. +`OpenClaw Release Checks` також запускає критичні для release лінії QA Lab перед release approval; його QA parity gate запускає candidate і baseline packs як parallel lane jobs, а потім завантажує обидва артефакти в малий report job для фінального parity comparison. -Не ставте шлях landing PR за `Parity gate`, якщо зміна насправді не торкається QA runtime, model-pack parity або поверхні, якою володіє parity workflow. Для звичайних виправлень каналів, конфігурації, документації або unit tests вважайте це необовʼязковим сигналом і спирайтеся на scoped CI/check evidence. +Не ставте PR landing path за `Parity gate`, якщо зміна справді не торкається QA runtime, model-pack parity або surface, якою володіє parity workflow. Для звичайних виправлень channel, config, docs або unit-test розглядайте це як optional signal і натомість дотримуйтеся scoped CI/check evidence. ## CodeQL -Workflow `CodeQL` навмисно є вузьким security scanner першого проходу, а не повним sweep репозиторію. Щоденні, ручні та non-draft pull request guard runs сканують код Actions workflow і поверхні JavaScript/TypeScript з найвищим ризиком, використовуючи high-confidence security queries, відфільтровані до high/critical `security-severity`. +Workflow `CodeQL` навмисно є вузьким security scanner першого проходу, а не повним repository sweep. Daily, manual і non-draft pull request guard runs сканують Actions workflow code плюс JavaScript/TypeScript surfaces з найвищим ризиком за допомогою high-confidence security queries, відфільтрованих до high/critical `security-severity`. -Pull request guard залишається легким: він стартує лише для змін у `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` або `src`, і запускає ту саму high-confidence security matrix, що й запланований workflow. Android і macOS CodeQL не входять до типових PR-перевірок. +Pull request guard залишається легким: він стартує лише для змін у `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` або `src`, і запускає ту саму high-confidence security matrix, що й scheduled workflow. Android і macOS CodeQL не входять до PR defaults. ### Категорії безпеки -| Категорія | Поверхня | -| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| `/codeql-security-high/core-auth-secrets` | Auth, secrets, sandbox, cron і gateway baseline | -| `/codeql-security-high/channel-runtime-boundary` | Контракти реалізації core channel плюс runtime channel Plugin, gateway, Plugin SDK, secrets, audit touchpoints | -| `/codeql-security-high/network-ssrf-boundary` | Поверхні core SSRF, розбору IP, network guard, web-fetch і політики SSRF Plugin SDK | -| `/codeql-security-high/mcp-process-tool-boundary` | MCP servers, process execution helpers, outbound delivery і gates виконання agent tools | -| `/codeql-security-high/plugin-trust-boundary` | Поверхні довіри для встановлення Plugin, loader, manifest, registry, package-manager install, source-loading і package contract Plugin SDK | +| Категорія | Surface | +| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `/codeql-security-high/core-auth-secrets` | Auth, secrets, sandbox, cron і gateway baseline | +| `/codeql-security-high/channel-runtime-boundary` | Core channel implementation contracts плюс channel plugin runtime, gateway, Plugin SDK, secrets, audit touchpoints | +| `/codeql-security-high/network-ssrf-boundary` | Core SSRF, IP parsing, network guard, web-fetch і Plugin SDK SSRF policy surfaces | +| `/codeql-security-high/mcp-process-tool-boundary` | MCP servers, process execution helpers, outbound delivery і agent tool-execution gates | +| `/codeql-security-high/plugin-trust-boundary` | Plugin install, loader, manifest, registry, package-manager install, source-loading і Plugin SDK package contract trust surfaces | -### Платформоспецифічні security shards +### Platform-specific security shards -- `CodeQL Android Critical Security` — запланований Android security shard. Вручну збирає Android app для CodeQL на найменшому Blacksmith Linux runner, прийнятому workflow sanity. Вивантажує під `/codeql-critical-security/android`. -- `CodeQL macOS Critical Security` — щотижневий/ручний macOS security shard. Вручну збирає macOS app для CodeQL на Blacksmith macOS, відфільтровує результати dependency build із завантаженого SARIF і вивантажує під `/codeql-critical-security/macos`. Тримається поза щоденними типовими запускми, бо macOS build домінує в часі виконання навіть за чистого стану. +- `CodeQL Android Critical Security` — scheduled Android security shard. Збирає Android app вручну для CodeQL на найменшому Blacksmith Linux runner, прийнятому workflow sanity. Завантажує під `/codeql-critical-security/android`. +- `CodeQL macOS Critical Security` — weekly/manual macOS security shard. Збирає macOS app вручну для CodeQL на Blacksmith macOS, відфільтровує dependency build results із завантаженого SARIF і завантажує під `/codeql-critical-security/macos`. Утримується поза daily defaults, оскільки macOS build домінує над часом виконання навіть за чистого стану. -### Категорії Critical Quality +### Critical Quality categories -`CodeQL Critical Quality` є відповідним non-security shard. Він запускає лише error-severity, non-security JavaScript/TypeScript quality queries на вузьких високовартісних поверхнях на меншому Blacksmith Linux runner. Його pull request guard навмисно менший за запланований profile: non-draft PRs запускають лише відповідні shards `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` і `plugin-sdk-reply-runtime` для змін у коді agent command/model/tool execution і reply dispatch, config schema/migration/IO, auth/secrets/sandbox/security, core channel і runtime bundled channel Plugin, gateway protocol/server-method, memory runtime/SDK glue, MCP/process/outbound delivery, provider runtime/model catalog, session diagnostics/delivery queues, Plugin loader, Plugin SDK/package-contract або Plugin SDK reply runtime. Зміни конфігурації CodeQL і quality workflow запускають усі дванадцять PR quality shards. +`CodeQL Critical Quality` є відповідним non-security shard. Він запускає лише error-severity, non-security JavaScript/TypeScript quality queries на вузьких high-value surfaces на меншому Blacksmith Linux runner. Його pull request guard навмисно менший за scheduled profile: non-draft PRs запускають лише відповідні shards `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` і `plugin-sdk-reply-runtime` для agent command/model/tool execution і reply dispatch code, config schema/migration/IO code, auth/secrets/sandbox/security code, core channel і bundled channel plugin runtime, gateway protocol/server-method, memory runtime/SDK glue, MCP/process/outbound delivery, provider runtime/model catalog, session diagnostics/delivery queues, plugin loader, Plugin SDK/package-contract або Plugin SDK reply runtime changes. CodeQL config і quality workflow changes запускають усі дванадцять PR quality shards. -Ручний dispatch приймає: +Manual dispatch приймає: ``` profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary ``` -Вузькі profiles є навчальними/ітераційними hooks для запуску одного quality shard ізольовано. +Вузькі profiles є teaching/iteration hooks для запуску одного quality shard ізольовано. -| Категорія | Поверхня | -| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-critical-quality/core-auth-secrets` | Код межі безпеки автентифікації, секретів, sandbox, cron і Gateway | -| `/codeql-critical-quality/config-boundary` | Схема конфігурації, міграція, нормалізація та контракти IO | -| `/codeql-critical-quality/gateway-runtime-boundary` | Схеми протоколу Gateway і контракти серверних методів | -| `/codeql-critical-quality/channel-runtime-boundary` | Контракти ядра каналів і реалізації вбудованих каналів Plugin | -| `/codeql-critical-quality/agent-runtime-boundary` | Контракти виконання команд, диспетчеризації моделей/провайдерів, диспетчеризації та черг автовідповідей, а також runtime-контракти control plane ACP | -| `/codeql-critical-quality/mcp-process-runtime-boundary` | Сервери MCP і мости інструментів, допоміжні засоби нагляду за процесами та контракти вихідної доставки | -| `/codeql-critical-quality/memory-runtime-boundary` | SDK хоста пам’яті, фасади runtime пам’яті, псевдоніми SDK пам’яті Plugin, зв’язувальний код активації runtime пам’яті та команди doctor пам’яті | -| `/codeql-critical-quality/session-diagnostics-boundary` | Внутрішні механізми черги відповідей, черги доставки сесій, допоміжні засоби прив’язування/доставки вихідних сесій, поверхні діагностичних подій/пакетів журналів і контракти CLI doctor для сесій | -| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Диспетчеризація вхідних відповідей SDK Plugin, допоміжні засоби payload/розбиття на фрагменти/runtime для відповідей, параметри відповідей каналу, черги доставки та допоміжні засоби прив’язування сесії/треду | -| `/codeql-critical-quality/provider-runtime-boundary` | Нормалізація каталогу моделей, автентифікація та виявлення провайдерів, реєстрація runtime провайдерів, типові значення/каталоги провайдерів і реєстри web/search/fetch/embedding | -| `/codeql-critical-quality/ui-control-plane` | Початкове завантаження Control UI, локальне збереження, потоки керування Gateway і runtime-контракти control plane задач | -| `/codeql-critical-quality/web-media-runtime-boundary` | Контракти runtime для core web fetch/search, media IO, розуміння медіа, генерації зображень і генерації медіа | -| `/codeql-critical-quality/plugin-boundary` | Контракти завантажувача, реєстру, публічної поверхні та точок входу SDK Plugin | -| `/codeql-critical-quality/plugin-sdk-package-contract` | Опублікований package-side вихідний код SDK Plugin і допоміжні засоби контрактів пакетів Plugin | +| Категорія | Поверхня | +| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/codeql-critical-quality/core-auth-secrets` | Код межі безпеки автентифікації, секретів, пісочниці, Cron і Gateway | +| `/codeql-critical-quality/config-boundary` | Схема конфігурації, міграція, нормалізація та контракти IO | +| `/codeql-critical-quality/gateway-runtime-boundary` | Схеми протоколу Gateway і контракти серверних методів | +| `/codeql-critical-quality/channel-runtime-boundary` | Контракти реалізації основного каналу та вбудованого channel plugin | +| `/codeql-critical-quality/agent-runtime-boundary` | Виконання команд, диспетчеризація моделей/провайдерів, диспетчеризація автовідповідей і черги, а також runtime-контракти контрольної площини ACP | +| `/codeql-critical-quality/mcp-process-runtime-boundary` | Сервери MCP і мости інструментів, допоміжні засоби нагляду за процесами та контракти вихідної доставки | +| `/codeql-critical-quality/memory-runtime-boundary` | SDK хоста пам’яті, runtime-фасади пам’яті, псевдоніми SDK пам’яті Plugin, зв’язувальний код активації runtime пам’яті та команди doctor пам’яті | +| `/codeql-critical-quality/session-diagnostics-boundary` | Внутрішня реалізація черги відповідей, черги доставки сесій, допоміжні засоби прив’язування/доставки вихідних сесій, поверхні діагностичних подій/пакетів логів і контракти CLI doctor сесій | +| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Вхідна диспетчеризація відповідей Plugin SDK, допоміжні засоби payload/chunking/runtime для відповідей, параметри відповідей каналу, черги доставки та допоміжні засоби прив’язування сесій/тредів | +| `/codeql-critical-quality/provider-runtime-boundary` | Нормалізація каталогу моделей, автентифікація й виявлення провайдерів, реєстрація runtime провайдерів, типові налаштування/каталоги провайдерів і реєстри web/search/fetch/embedding | +| `/codeql-critical-quality/ui-control-plane` | Bootstrap Control UI, локальна персистентність, потоки керування Gateway та runtime-контракти контрольної площини завдань | +| `/codeql-critical-quality/web-media-runtime-boundary` | Runtime-контракти основного web fetch/search, media IO, розуміння медіа, image-generation і media-generation | +| `/codeql-critical-quality/plugin-boundary` | Контракти завантажувача, реєстру, публічної поверхні та точок входу Plugin SDK | +| `/codeql-critical-quality/plugin-sdk-package-contract` | Опублікований package-side вихідний код Plugin SDK і допоміжні засоби контрактів пакетів plugin | -Якість залишається окремою від безпеки, щоб findings якості можна було планувати, вимірювати, вимикати або розширювати без приховування сигналу безпеки. Розширення CodeQL для Swift, Python і вбудованих Plugin слід додавати назад як scoped або sharded подальшу роботу лише після того, як вузькі профілі матимуть стабільний runtime і сигнал. +Якість лишається окремою від безпеки, щоб висновки щодо якості можна було планувати, вимірювати, вимикати або розширювати без затемнення сигналу безпеки. Розширення CodeQL для Swift, Python і bundled-plugin слід повертати лише як scoped або sharded подальшу роботу після того, як вузькі профілі матимуть стабільний runtime і сигнал. -## Робочі процеси супроводу +## Робочі процеси обслуговування ### Docs Agent -Робочий процес `Docs Agent` — це керована подіями смуга супроводу Codex для підтримання наявної документації у відповідності з нещодавно landed змінами. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, а manual dispatch може запустити його напряму. Виклики workflow-run пропускаються, коли `main` уже просунувся далі або коли інший non-skipped запуск Docs Agent було створено за останню годину. Під час запуску він переглядає діапазон комітів від попереднього non-skipped source SHA Docs Agent до поточного `main`, тож один погодинний запуск може охопити всі зміни main, накопичені з останнього проходу документації. +Робочий процес `Docs Agent` — це подієво-керована lane обслуговування Codex для підтримання наявної документації узгодженою з нещодавно landed змінами. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, а manual dispatch може запустити його напряму. Виклики workflow-run пропускаються, коли `main` уже просунувся далі або коли інший non-skipped запуск Docs Agent було створено протягом останньої години. Коли він запускається, то переглядає діапазон комітів від попереднього non-skipped source SHA Docs Agent до поточного `main`, тож один щогодинний запуск може охопити всі зміни main, накопичені з часу останнього проходу документації. ### Test Performance Agent -Робочий процес `Test Performance Agent` — це керована подіями смуга супроводу Codex для повільних тестів. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, але він пропускається, якщо інший workflow-run invocation уже виконувався або виконується в цей UTC-день. Manual dispatch обходить цей щоденний activity gate. Смуга будує звіт продуктивності Vitest для full-suite grouped, дозволяє Codex робити лише невеликі coverage-preserving виправлення продуктивності тестів замість широких рефакторингів, потім повторно запускає full-suite report і відхиляє зміни, які зменшують baseline кількість passing tests. Якщо baseline має failing tests, Codex може виправити лише очевидні failures, а after-agent full-suite report має пройти перед будь-яким комітом. Коли `main` просувається до того, як bot push потрапить у репозиторій, смуга rebases validated patch, повторно запускає `pnpm check:changed` і повторює push; конфліктні застарілі patches пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб Codex action могла зберігати ту саму drop-sudo safety posture, що й docs agent. +Робочий процес `Test Performance Agent` — це подієво-керована lane обслуговування Codex для повільних тестів. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, але він пропускається, якщо інший workflow-run invocation уже виконувався або виконується цього UTC-дня. Manual dispatch обходить цей щоденний activity gate. Lane будує full-suite grouped звіт продуктивності Vitest, дозволяє Codex робити лише невеликі coverage-preserving виправлення продуктивності тестів замість широких рефакторингів, потім повторно запускає full-suite звіт і відхиляє зміни, які зменшують базову кількість passing тестів. Якщо baseline має failing тести, Codex може виправляти лише очевидні failures, а after-agent full-suite звіт має пройти перед тим, як щось буде закомічено. Коли `main` просувається до того, як bot push буде landed, lane перебазовує validated patch, повторно запускає `pnpm check:changed` і повторює push; конфліктні застарілі patches пропускаються. Він використовує GitHub-hosted Ubuntu, щоб action Codex міг зберігати таку саму drop-sudo safety posture, як docs agent. ### Дублікати PR після merge -Робочий процес `Duplicate PRs After Merge` — це ручний maintainer workflow для очищення дублікатів після land. За замовчуванням він працює в dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед зміною GitHub він перевіряє, що landed PR merged і що кожен дублікат має або спільне referenced issue, або overlapping changed hunks. +Робочий процес `Duplicate PRs After Merge` — це manual maintainer workflow для cleanup дублікатів після landing. Типово він працює як dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед зміною GitHub він перевіряє, що landed PR merged і що кожен duplicate має або спільну referenced issue, або overlapping changed hunks. ```bash gh workflow run duplicate-after-merge.yml \ @@ -404,27 +406,27 @@ gh workflow run duplicate-after-merge.yml \ ## Локальні check gates і changed routing -Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей local check gate суворіший щодо архітектурних меж, ніж широкий scope платформи CI: +Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний check gate суворіший щодо архітектурних меж, ніж широка platform scope CI: -- зміни production у core запускають core prod і core test typecheck плюс core lint/guards; -- зміни лише core tests запускають лише core test typecheck плюс core lint; -- зміни production в extension запускають extension prod і extension test typecheck плюс extension lint; -- зміни лише extension tests запускають extension test typecheck плюс extension lint; -- зміни публічного SDK Plugin або plugin-contract розширюються до extension typecheck, бо extensions залежать від цих core contracts (Vitest extension sweeps залишаються explicit test work); +- зміни core production запускають core prod і core test typecheck плюс core lint/guards; +- зміни лише core test запускають тільки core test typecheck плюс core lint; +- зміни extension production запускають extension prod і extension test typecheck плюс extension lint; +- зміни лише extension test запускають extension test typecheck плюс extension lint; +- зміни public Plugin SDK або plugin-contract розширюються до extension typecheck, бо extensions залежать від цих core contracts (Vitest extension sweeps залишаються explicit test work); - version bumps лише release metadata запускають targeted version/config/root-dependency checks; -- невідомі root/config changes fail safe до всіх check lanes. +- невідомі root/config зміни fail safe до всіх check lanes. -Локальний changed-test routing міститься в `scripts/test-projects.test-support.mjs` і навмисно дешевший за `check:changed`: прямі редагування тестів запускають самі себе, редагування source віддають перевагу explicit mappings, потім sibling tests і import-graph dependents. Shared group-room delivery config є одним із explicit mappings: зміни до group visible-reply config, source reply delivery mode або message-tool system prompt проходять через core reply tests плюс Discord і Slack delivery regressions, щоб shared default change впала до першого PR push. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли зміна настільки harness-wide, що cheap mapped set не є надійним proxy. +Локальний changed-test routing міститься в `scripts/test-projects.test-support.mjs` і навмисно дешевший за `check:changed`: прямі зміни тестів запускають самі себе, зміни source віддають перевагу explicit mappings, потім sibling tests та import-graph dependents. Shared group-room delivery config є одним із explicit mappings: зміни group visible-reply config, source reply delivery mode або message-tool system prompt проходять через core reply tests плюс регресії доставки Discord і Slack, щоб зміна shared default зафейлилася до першого PR push. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише коли зміна достатньо harness-wide, що дешевий mapped set не є надійним proxy. ## Валідація Testbox -Запускайте Testbox з кореня репозиторію і для broad proof віддавайте перевагу свіжому warmed box. Перед тим як витрачати повільний gate на box, який було reused, expired або який щойно повідомив про несподівано великий sync, спершу запустіть `pnpm testbox:sanity` всередині box. +Запускайте Testbox з кореня repo й віддавайте перевагу свіжій warmed box для broad proof. Перед тим як витрачати повільний gate на box, що була reused, expired або щойно повідомила про несподівано великий sync, спершу запустіть `pnpm testbox:sanity` всередині box. -Sanity check швидко падає, коли потрібні root files, як-от `pnpm-lock.yaml`, зникли або коли `git status --short` показує щонайменше 200 tracked deletions. Зазвичай це означає, що remote sync state не є надійною копією PR; зупиніть цей box і warm a fresh one замість debugging product test failure. Для навмисних large-deletion PR установіть `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього sanity run. +Sanity check швидко fails, коли required root files, як-от `pnpm-lock.yaml`, зникли або коли `git status --short` показує щонайменше 200 tracked deletions. Зазвичай це означає, що remote sync state не є trustworthy copy PR; зупиніть цю box і warm свіжу замість debugging product test failure. Для intentional large-deletion PR встановіть `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього sanity run. -`pnpm testbox:run` також завершує локальний виклик Blacksmith CLI, який залишається у sync phase понад п’ять хвилин без post-sync output. Установіть `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, щоб вимкнути цей guard, або використайте більше значення в мілісекундах для незвично великих local diffs. +`pnpm testbox:run` також завершує локальний invocation Blacksmith CLI, який залишається у фазі sync понад п’ять хвилин без post-sync output. Установіть `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, щоб вимкнути цей guard, або використайте більше значення в мілісекундах для незвично великих local diffs. -Crabbox — це repo-owned другий remote-box path для Linux proof, коли Blacksmith недоступний або коли owned cloud capacity є кращою. Warm a box, hydrate його через project workflow, потім запускайте команди через Crabbox CLI: +Crabbox — це repo-owned другий remote-box path для Linux proof, коли Blacksmith недоступний або коли owned cloud capacity краща. Warm box, hydrate її через project workflow, потім запускайте команди через Crabbox CLI: ```bash pnpm crabbox:warmup -- --idle-timeout 90m @@ -433,7 +435,7 @@ pnpm crabbox:run -- --id --shell "OPENCLAW_TESTBOX=1 pnpm check:changed pnpm crabbox:stop -- ``` -`.crabbox.yaml` містить defaults для provider, sync і GitHub Actions hydration. Він виключає локальний `.git`, щоб hydrated Actions checkout зберігав власні remote Git metadata замість синхронізації maintainer-local remotes і object stores, а також виключає local runtime/build artifacts, які ніколи не слід передавати. `.github/workflows/crabbox-hydrate.yml` містить checkout, налаштування Node/pnpm, fetch `origin/main` і non-secret environment handoff, який пізніші команди `crabbox run --id ` source. +`.crabbox.yaml` володіє provider, sync і GitHub Actions hydration defaults. Він виключає локальний `.git`, щоб hydrated Actions checkout зберігав власні remote Git metadata замість синхронізації maintainer-local remotes і object stores, а також виключає local runtime/build artifacts, які ніколи не мають передаватися. `.github/workflows/crabbox-hydrate.yml` володіє checkout, Node/pnpm setup, `origin/main` fetch і non-secret environment handoff, який подальші команди `crabbox run --id ` source. ## Пов’язане diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 4ab74c2ef..1cb35dbad 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -3,96 +3,96 @@ read_when: - Запуск тестів локально або в CI - Додавання регресійних тестів для помилок моделей/провайдерів - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: набори модульних/e2e/живих тестів, ранери Docker і що охоплює кожен тест' +summary: 'Набір для тестування: модульні/e2e/live-набори, Docker-ранери та те, що покриває кожен тест' title: Тестування x-i18n: - generated_at: "2026-05-01T20:38:27Z" + generated_at: "2026-05-01T20:49:27Z" model: gpt-5.5 provider: openai - source_hash: c2d214c011572b21eb0bc03206627d6381216a30fcd0d4b213a52fb31f27d2e8 + source_hash: 3fb72ec57b41f776663f83380df89550e918887d96b7f420e4c9ebf53a57cdb8 source_path: help/testing.md workflow: 16 --- -OpenClaw має три набори тестів Vitest (unit/integration, e2e, live) і невеликий набір +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ є посібником "як ми тестуємо": - Що покриває кожен набір (і що він навмисно _не_ покриває). -- Які команди запускати для типових робочих процесів (локально, перед push, налагодження). +- Які команди запускати для типових робочих процесів (локально, перед push, для налагодження). - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. -- Як додавати регресійні тести для реальних проблем моделей/провайдерів. +- Як додавати регресійні тести для реальних проблем із моделями/провайдерами. **QA-стек (qa-lab, qa-channel, live transport lanes)** задокументовано окремо: -- [Огляд QA](/uk/concepts/qa-e2e-automation) — архітектура, поверхня команд, створення сценаріїв. +- [Огляд QA](/uk/concepts/qa-e2e-automation) — архітектура, командна поверхня, створення сценаріїв. - [Matrix QA](/uk/concepts/qa-matrix) — довідник для `pnpm openclaw qa matrix`. -- [QA channel](/uk/channels/qa-channel) — синтетичний транспортний Plugin, який використовують сценарії на основі репозиторію. +- [QA channel](/uk/channels/qa-channel) — синтетичний транспортний Plugin, який використовується сценаріями з репозиторію. -Ця сторінка описує запуск звичайних наборів тестів і Docker/Parallels-ранерів. Розділ QA-specific runners нижче ([QA-specific runners](#qa-specific-runners)) перелічує конкретні виклики `qa` і відсилає до наведених вище довідників. +Ця сторінка описує запуск звичайних наборів тестів і Docker/Parallels-ранерів. Розділ про QA-специфічні ранери нижче ([QA-специфічні ранери](#qa-specific-runners)) перелічує конкретні виклики `qa` і відсилає до наведених вище довідників. ## Швидкий старт -У більшості випадків: +У більшість днів: - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` +- Швидший локальний запуск повного набору на просторій машині: `pnpm test:max` - Прямий цикл Vitest watch: `pnpm test:watch` - Пряме таргетування файлів тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Під час ітерацій над окремим збоєм спочатку віддавайте перевагу таргетованим запускам. -- Docker-backed QA site: `pnpm qa:lab:up` +- Під час ітерацій над одиничною помилкою спочатку віддавайте перевагу таргетованим запускам. +- Docker-backed QA-сайт: `pnpm qa:lab:up` - Linux VM-backed QA lane: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете додаткової впевненості: +Коли ви змінюєте тести або хочете більше впевненості: -- Coverage gate: `pnpm test:coverage` +- Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + перевірки Gateway tool/image): `pnpm test:live` -- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Live-набір (моделі + gateway tool/image probes): `pnpm test:live` +- Таргетувати один live-файл тихо: `pnpm test:live -- src/agents/models.profiles.live.test.ts` - Docker live model sweep: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер виконує текстовий хід плюс невелику перевірку в стилі читання файлу. - Моделі, метадані яких оголошують підтримку введення `image`, також виконують невеликий image-хід. - Вимикайте додаткові перевірки за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або + - Кожна вибрана модель тепер виконує текстовий turn плюс невелику probe у стилі читання файлу. + Моделі, чиї метадані оголошують input `image`, також виконують крихітний image turn. + Вимкніть додаткові probes через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - Покриття CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні - `OpenClaw Release Checks` обидва викликають повторно використовуваний live/E2E workflow з + `OpenClaw Release Checks` обидва викликають reusable live/E2E workflow з `include_live_suites: true`, що включає окремі Docker live model - matrix-завдання, розбиті за провайдером. - - Для сфокусованих повторних запусків CI запускайте `OpenClaw Live And E2E Checks (Reusable)` + matrix jobs, розшардовані за провайдером. + - Для сфокусованих повторних запусків CI запустіть `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh` - плюс `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його - scheduled/release викликачів. + плюс `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` та його + scheduled/release callers. - Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind` - - Запускає Docker live lane проти шляху Codex app-server, прив’язує синтетичний + - Запускає Docker live lane проти шляху Codex app-server, прив'язує синтетичний Slack DM через `/codex bind`, виконує `/codex fast` і - `/codex permissions`, потім перевіряє, що звичайна відповідь і вкладення зображення + `/codex permissions`, а потім перевіряє, що звичайна відповідь і image attachment проходять через native plugin binding замість ACP. - Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` - - Запускає ходи агента Gateway через harness Codex app-server, який належить Plugin, - перевіряє `/codex status` і `/codex models`, і за замовчуванням виконує перевірки image, - cron MCP, sub-agent і Guardian. Вимикайте перевірку sub-agent за допомогою + - Запускає gateway agent turns через plugin-owned Codex app-server harness, + перевіряє `/codex status` і `/codex models`, а за замовчуванням виконує probes для image, + cron MCP, sub-agent і Guardian. Вимкніть sub-agent probe через `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, коли ізолюєте інші збої Codex - app-server. Для сфокусованої перевірки sub-agent вимкніть інші перевірки: + app-server. Для сфокусованої перевірки sub-agent вимкніть інші probes: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`. - Це завершується після перевірки sub-agent, якщо не встановлено + Це завершується після sub-agent probe, якщо не встановлено `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0`. - Crestodian rescue command smoke: `pnpm test:live:crestodian-rescue-channel` - - Додаткова belt-and-suspenders перевірка поверхні команди rescue для message-channel. - Вона виконує `/crestodian status`, ставить у чергу постійну зміну моделі, - відповідає `/crestodian yes` і перевіряє шлях запису audit/config. + - Opt-in belt-and-suspenders перевірка для поверхні команди rescue message-channel. + Вона виконує `/crestodian status`, ставить у чергу persistent model + change, відповідає `/crestodian yes` і перевіряє шлях audit/config write. - Crestodian planner Docker smoke: `pnpm test:docker:crestodian-planner` - - Запускає Crestodian у контейнері без конфігурації з фейковим Claude CLI у `PATH` - і перевіряє, що нечіткий planner fallback перетворюється на audited typed + - Запускає Crestodian у контейнері без конфігурації з фальшивим Claude CLI у `PATH` + і перевіряє, що fuzzy planner fallback перетворюється на audited typed config write. - Crestodian first-run Docker smoke: `pnpm test:docker:crestodian-first-run` - - Стартує з порожньої директорії стану OpenClaw, маршрутизує bare `openclaw` до - Crestodian, застосовує setup/model/agent/Discord Plugin + записи SecretRef, - валідовує конфігурацію та перевіряє записи audit. Той самий шлях налаштування Ring 0 + - Стартує з порожнього state dir OpenClaw, маршрутизує bare `openclaw` до + Crestodian, застосовує setup/model/agent/Discord Plugin + SecretRef writes, + валідує конфігурацію та перевіряє audit entries. Той самий шлях Ring 0 setup також покрито в QA Lab через `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`. - Moonshot/Kimi cost smoke: з установленим `MOONSHOT_API_KEY` запустіть @@ -102,44 +102,44 @@ Docker-ранерів. Цей документ є посібником "як м transcript асистента зберігає нормалізований `usage.cost`. -Коли потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через allowlist env vars, описані нижче. +Коли вам потрібен лише один failing case, віддавайте перевагу звуженню live-тестів через allowlist env vars, описані нижче. -## QA-specific runners +## QA-специфічні ранери -Ці команди розташовані поруч з основними наборами тестів, коли потрібен реалізм QA-lab: +Ці команди розташовані поруч з основними наборами тестів, коли потрібна реалістичність QA-lab: CI запускає QA Lab у dedicated workflows. `Parity gate` запускається на відповідних PR і -через manual dispatch з mock providers. `QA-Lab - All Lanes` запускається щоночі на -`main` і через manual dispatch з mock parity gate, live Matrix lane, +з ручного dispatch із mock providers. `QA-Lab - All Lanes` запускається щоночі на +`main` і з ручного dispatch із mock parity gate, live Matrix lane, Convex-managed live Telegram lane і Convex-managed live Discord lane як -паралельні jobs. Scheduled QA і release checks явно передають Matrix `--profile fast`, -тоді як Matrix CLI і manual workflow input за замовчуванням залишаються -`all`; manual dispatch може розбити `all` на jobs `transport`, `media`, `e2ee-smoke`, +parallel jobs. Scheduled QA і release checks явно передають Matrix `--profile fast`, +тоді як Matrix CLI і manual workflow input default залишаються +`all`; manual dispatch може шардити `all` на jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` запускає parity плюс -fast Matrix і Telegram lanes перед approval релізу, використовуючи +fast Matrix і Telegram lanes перед release approval, використовуючи `mock-openai/gpt-5.5` для release transport checks, щоб вони залишалися детермінованими -й уникали звичайного запуску provider-plugin. Ці live transport gateways вимикають +та уникали звичайного старту provider-plugin. Ці live transport gateways вимикають memory search; поведінка memory залишається покритою QA parity suites. Full release live media shards використовують `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, який уже має `ffmpeg` і `ffprobe`. Docker live model/backend shards використовують спільний -образ `ghcr.io/openclaw/openclaw-live-test:`, зібраний один раз для вибраного -commit, а потім отримують його з `OPENCLAW_SKIP_DOCKER_BUILD=1` замість перебудови -всередині кожного shard. +image `ghcr.io/openclaw/openclaw-live-test:`, зібраний один раз для вибраного +commit, потім витягують його з `OPENCLAW_SKIP_DOCKER_BUILD=1` замість rebuild +усередині кожного shard. - `pnpm openclaw qa suite` - - Запускає QA-сценарії на основі репозиторію безпосередньо на host. + - Запускає QA-сценарії з репозиторію безпосередньо на host. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими gateway workers. `qa-channel` за замовчуванням має concurrency 4 (обмежено - кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати - кількість workers, або `--concurrency 1` для старішого serial lane. - - Завершується з ненульовим кодом, коли будь-який сценарій зазнає збою. Використовуйте `--allow-failures`, коли + кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати worker + count, або `--concurrency 1` для старішого serial lane. + - Завершується з ненульовим кодом, коли будь-який сценарій падає. Використовуйте `--allow-failures`, коли вам потрібні artifacts без failing exit code. - Підтримує provider modes `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний provider server на базі AIMock для експериментального - покриття fixture і protocol-mock без заміни scenario-aware + `aimock` запускає локальний AIMock-backed provider server для experimental + fixture і protocol-mock coverage без заміни scenario-aware `mock-openai` lane. - `pnpm test:gateway:cpu-scenarios` - Запускає gateway startup bench плюс невеликий mock QA Lab scenario pack @@ -147,19 +147,19 @@ commit, а потім отримують його з `OPENCLAW_SKIP_DOCKER_BUILD `gateway-restart-inflight-run`) і записує combined CPU observation summary у `.artifacts/gateway-cpu-scenarios/`. - За замовчуванням позначає лише sustained hot CPU observations (`--cpu-core-warn` - плюс `--hot-wall-warn-ms`), тож короткі startup bursts записуються як metrics - і не виглядають як регресія minutes-long gateway peg. - - Використовує зібрані artifacts `dist`; спершу запустіть build, якщо checkout ще не + плюс `--hot-wall-warn-ms`), тому короткі startup bursts записуються як metrics + без вигляду minutes-long gateway peg regression. + - Використовує зібрані artifacts `dist`; спочатку запустіть build, коли checkout ще не має свіжого runtime output. - `pnpm openclaw qa suite --runner multipass` - Запускає той самий QA suite всередині одноразової Multipass Linux VM. - - Зберігає ту саму поведінку scenario-selection, що й `qa suite` на host. - - Повторно використовує ті самі прапорці provider/model selection, що й `qa suite`. - - Live-запуски передають підтримувані QA auth inputs, практичні для guest: + - Зберігає таку саму поведінку вибору сценаріїв, як `qa suite` на host. + - Повторно використовує ті самі provider/model selection flags, що й `qa suite`. + - Live runs передають підтримувані QA auth inputs, практичні для guest: env-based provider keys, шлях QA live provider config і `CODEX_HOME`, - коли він наявний. - - Output dirs мають залишатися в межах repo root, щоб guest міг записувати назад через - змонтований workspace. + коли він присутній. + - Output dirs мають залишатися під repo root, щоб guest міг записувати назад через + mounted workspace. - Записує звичайний QA report + summary плюс Multipass logs у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` @@ -167,20 +167,20 @@ commit, а потім отримують його з `OPENCLAW_SKIP_DOCKER_BUILD - `pnpm test:docker:npm-onboard-channel-agent` - Збирає npm tarball з поточного checkout, встановлює його глобально в Docker, запускає non-interactive OpenAI API-key onboarding, за замовчуванням налаштовує Telegram, - перевіряє, що packaged Plugin runtime завантажується без startup - dependency repair, запускає doctor і виконує один локальний agent turn проти - mock OpenAI endpoint. + перевіряє, що packaged plugin runtime завантажується без startup + dependency repair, запускає doctor і виконує один local agent turn проти + mocked OpenAI endpoint. - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий packaged-install lane з Discord. - `pnpm test:docker:session-runtime-context` - Запускає deterministic built-app Docker smoke для embedded runtime context transcripts. Він перевіряє, що hidden OpenClaw runtime context зберігається як - non-display custom message замість витоку у видимий user turn, + non-display custom message замість витоку у visible user turn, потім засіває affected broken session JSONL і перевіряє, що - `openclaw doctor --fix` переписує його на active branch з backup. + `openclaw doctor --fix` переписує його на active branch із backup. - `pnpm test:docker:npm-telegram-live` - Встановлює candidate package OpenClaw у Docker, запускає installed-package - onboarding, налаштовує Telegram через installed CLI, а потім повторно використовує + onboarding, налаштовує Telegram через installed CLI, потім повторно використовує live Telegram QA lane з цим installed package як SUT Gateway. - За замовчуванням використовує `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; встановіть `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` або @@ -190,18 +190,18 @@ commit, а потім отримують його з `OPENCLAW_SKIP_DOCKER_BUILD `pnpm openclaw qa telegram`. Для CI/release automation встановіть `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` плюс `OPENCLAW_QA_CONVEX_SITE_URL` і role secret. Якщо - `OPENCLAW_QA_CONVEX_SITE_URL` і Convex role secret наявні в CI, + `OPENCLAW_QA_CONVEX_SITE_URL` і Convex role secret присутні в CI, Docker wrapper автоматично вибирає Convex. - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає shared `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цього lane. - - GitHub Actions виставляє цей lane як ручний maintainer workflow + - GitHub Actions відкриває цей lane як ручний maintainer workflow `NPM Telegram Beta E2E`. Він не запускається під час merge. Workflow використовує - середовище `qa-live-shared` і Convex CI credential leases. -- GitHub Actions також виставляє `Package Acceptance` для side-run product proof + environment `qa-live-shared` і Convex CI credential leases. +- GitHub Actions також відкриває `Package Acceptance` для side-run product proof проти одного candidate package. Він приймає trusted ref, published npm spec, HTTPS tarball URL плюс SHA-256 або tarball artifact з іншого run, завантажує - нормалізований `openclaw-current.tgz` як `package-under-test`, а потім запускає - наявний Docker E2E scheduler з профілями lane smoke, package, product, full або custom. + normalized `openclaw-current.tgz` як `package-under-test`, потім запускає + existing Docker E2E scheduler з lane profiles smoke, package, product, full або custom. Встановіть `telegram_mode=mock-openai` або `live-frontier`, щоб запустити Telegram QA workflow проти того самого artifact `package-under-test`. - Latest beta product proof: @@ -214,7 +214,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- Exact tarball URL proof потребує digest: +- Exact tarball URL proof вимагає digest: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -236,31 +236,31 @@ gh workflow run package-acceptance.yml --ref main \ - `pnpm test:docker:plugins` - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає вбудований канал/Plugin через - редагування конфігурації. - - Перевіряє, що виявлення налаштування не залишає неналаштованих завантажуваних plugins, + з налаштованим OpenAI, а потім вмикає вбудовані канали/плагіни через + зміни конфігурації. + - Перевіряє, що виявлення налаштування не показує неналаштовані завантажувані плагіни, перше налаштоване виправлення doctor явно встановлює кожен відсутній завантажуваний - plugin, а другий перезапуск не запускає приховане + плагін, а другий перезапуск не запускає приховане виправлення залежностей. - - Також встановлює відомий старіший базовий варіант npm, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що doctor кандидата - після оновлення очищає залишки застарілих залежностей plugin без - виправлення postinstall з боку тестового обв’язування. + - Також встановлює відому старішу npm-базу, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що doctor кандидата після + оновлення очищає залишки застарілих залежностей плагінів без + postinstall-виправлення з боку тестового оточення. - `pnpm test:parallels:npm-update` - - Запускає нативну димову перевірку оновлення пакетного встановлення на гостях Parallels. Кожна + - Запускає нативний smoke-тест оновлення пакетного встановлення на гостях Parallels. Кожна вибрана платформа спочатку встановлює запитаний базовий пакет, потім запускає - встановлену команду `openclaw update` у тому самому гості й перевіряє - встановлену версію, статус оновлення, готовність gateway та один локальний + встановлену команду `openclaw update` у тому самому гості та перевіряє + встановлену версію, статус оновлення, готовність Gateway і один локальний хід агента. - Використовуйте `--platform macos`, `--platform windows` або `--platform linux` під час ітерацій на одному гості. Використовуйте `--json` для шляху до підсумкового артефакта та статусу кожної лінії. - - Лінія OpenAI типово використовує `openai/gpt-5.4` для доказу живого ходу агента. - Передайте `--model ` або задайте - `OPENCLAW_PARALLELS_OPENAI_MODEL`, коли свідомо перевіряєте іншу + - Лінія OpenAI за замовчуванням використовує `openai/gpt-5.5` для живого доказу + ходу агента. Передайте `--model ` або задайте + `OPENCLAW_PARALLELS_OPENAI_MODEL`, коли навмисно перевіряєте іншу модель OpenAI. - - Обгортайте довгі локальні запуски в таймаут хоста, щоб зависання транспорту Parallels не могли - використати решту вікна тестування: + - Обгорніть довгі локальні запуски в тайм-аут хоста, щоб зависання транспорту Parallels не + забрало решту вікна тестування: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json @@ -268,73 +268,73 @@ gh workflow run package-acceptance.yml --ref main \ ``` - Скрипт записує вкладені журнали ліній у `/tmp/openclaw-parallels-npm-update.*`. - Перегляньте `windows-update.log`, `macos-update.log` або `linux-update.log`, - перш ніж припускати, що зовнішня обгортка зависла. - - Оновлення Windows може витрачати від 10 до 15 хвилин на post-update doctor та роботу з - оновленням пакетів на холодному гості; це все ще нормально, коли вкладений журнал налагодження npm - просувається. - - Не запускайте цю агреговану обгортку паралельно з окремими димовими лініями Parallels - macOS, Windows або Linux. Вони спільно використовують стан ВМ і можуть конфліктувати під час - відновлення знімка, обслуговування пакетів або стану gateway гостя. - - Доказ після оновлення запускає звичайну поверхню вбудованих plugin, оскільки + Перегляньте `windows-update.log`, `macos-update.log` або `linux-update.log` + перед тим, як припускати, що зовнішня обгортка зависла. + - Оновлення Windows може витратити 10-15 хвилин на post-update doctor і + роботу з оновлення пакетів на холодному гості; це все ще справний стан, якщо вкладений + журнал налагодження npm просувається. + - Не запускайте цю агреговану обгортку паралельно з окремими smoke-лініями Parallels + macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати під час + відновлення snapshot, обслуговування пакетів або стану гостьового gateway. + - Доказ після оновлення запускає звичайну поверхню вбудованих плагінів, оскільки фасади можливостей, як-от мовлення, генерація зображень і розуміння медіа, - завантажуються через вбудовані runtime API навіть тоді, коли сам хід агента + завантажуються через вбудовані runtime API, навіть коли сам хід агента перевіряє лише просту текстову відповідь. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямого димового - тестування протоколу. + - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування + протоколу. - `pnpm openclaw qa matrix` - - Запускає живу лінію QA Matrix проти одноразового homeserver Tuwunel на базі Docker. Лише вихідний checkout — пакетні встановлення не постачають `qa-lab`. - - Повний CLI, каталог профілів/сценаріїв, змінні середовища та структура артефактів: [QA Matrix](/uk/concepts/qa-matrix). + - Запускає live QA-лінію Matrix проти одноразового homeserver Tuwunel на базі Docker. Лише source-checkout — пакетні встановлення не постачають `qa-lab`. + - Повний CLI, каталог профілів/сценаріїв, змінні середовища та структура артефактів: [Matrix QA](/uk/concepts/qa-matrix). - `pnpm openclaw qa telegram` - - Запускає живу лінію QA Telegram проти реальної приватної групи, використовуючи токени бота-драйвера та SUT з env. - - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим id чату Telegram. - - Підтримує `--credential-source convex` для спільних пулових облікових даних. Типово використовуйте режим env або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути пулові оренди. - - Завершується з ненульовим кодом, коли будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, коли - потрібні артефакти без коду виходу, що позначає помилку. - - Потребує двох різних ботів в одній приватній групі, причому SUT-бот має надавати ім’я користувача Telegram. - - Для стабільного спостереження бот-до-бота увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот-драйвер може спостерігати трафік ботів у групі. - - Записує звіт QA Telegram, підсумок і артефакт спостережених повідомлень у `.artifacts/qa-e2e/...`. Сценарії з відповідями містять RTT від запиту надсилання драйвера до спостереженої відповіді SUT. + - Запускає live QA-лінію Telegram проти реальної приватної групи, використовуючи токени driver і SUT-бота з середовища. + - Потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим id чату Telegram. + - Підтримує `--credential-source convex` для спільних pooled-облікових даних. За замовчуванням використовуйте режим env або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. + - Завершується з ненульовим кодом, коли будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, коли вам + потрібні артефакти без коду виходу з помилкою. + - Потрібні два різні боти в одній приватній групі, причому SUT-бот має надавати ім'я користувача Telegram. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що driver-бот може спостерігати груповий bot-трафік. + - Записує звіт Telegram QA, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту надсилання driver до спостереженої відповіді SUT. -Живі транспортні лінії мають один стандартний контракт, щоб нові транспорти не розходилися; матриця покриття за лініями міститься в [Огляд QA → Покриття живих транспортів](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` — це широкий синтетичний набір і не є частиною цієї матриці. +Live transport-лінії мають один стандартний контракт, щоб нові транспорти не відхилялися; матриця покриття кожної лінії розміщена в [Огляд QA → Покриття live transport](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` — це широкий синтетичний набір і не є частиною цієї матриці. ### Спільні облікові дані Telegram через Convex (v1) -Коли `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) увімкнено для -`openclaw qa telegram`, лабораторія QA отримує ексклюзивну оренду з пулу на базі Convex, надсилає heartbeats -для цієї оренди, поки лінія виконується, і звільняє оренду під час завершення роботи. +Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або +`OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивну lease з pool на базі Convex, надсилає heartbeats +для цієї lease під час виконання лінії та звільняє lease під час завершення. -Еталонний scaffold проєкту Convex: +Еталонний каркас проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові змінні середовища: +Обов'язкові змінні середовища: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) -- Один secret для вибраної ролі: +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) +- Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (у CI типово `ci`, інакше `maintainer`) + - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (за замовчуванням `ci` у CI, інакше `maintainer`) -Необов’язкові змінні середовища: +Необов'язкові змінні середовища: -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) -- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (типово `90000`) -- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) -- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий id трасування) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback URL-адреси Convex `http://` лише для локальної розробки. +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (за замовчуванням `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (за замовчуванням `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (за замовчуванням `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (за замовчуванням `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (за замовчуванням `/qa-credentials/v1`) +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов'язковий trace id) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL Convex лише для локальної розробки. `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://` у звичайній роботі. -Адміністративні команди maintainer (додавання/видалення/список пулу) потребують +Адміністративні команди maintainer (додавання/видалення/список pool) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -Допоміжні CLI-команди для maintainer: +CLI-помічники для maintainer: ```bash pnpm openclaw qa credentials doctor @@ -343,10 +343,10 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `doctor` перед живими запусками, щоб перевірити URL сайту Convex, secrets брокера, -префікс endpoint, HTTP-таймаут і доступність admin/list без друку -секретних значень. Використовуйте `--json` для машинозчитуваного виводу в скриптах і -утилітах CI. +Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, broker-секрети, +префікс endpoint, HTTP-тайм-аут і доступність admin/list без друку +секретних значень. Використовуйте `--json` для машинозчитуваного виводу в скриптах і CI +утилітах. Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): @@ -360,14 +360,14 @@ pnpm openclaw qa credentials remove --credential-id - `POST /release` - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Успіх: `{ status: "ok" }` (або порожній `2xx`) -- `POST /admin/add` (лише secret maintainer) +- `POST /admin/add` (лише секрет maintainer) - Запит: `{ kind, actorId, payload, note?, status? }` - Успіх: `{ status: "ok", credential }` -- `POST /admin/remove` (лише secret maintainer) +- `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (лише secret maintainer) + - Запобіжник активної lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` @@ -379,59 +379,58 @@ pnpm openclaw qa credentials remove --credential-id ### Додавання каналу до QA -Назви архітектури та scenario-helper для нових адаптерів каналів містяться в [Огляд QA → Додавання каналу](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна вимога: реалізувати transport runner на спільному host seam `qa-lab`, оголосити `qaRunners` у маніфесті plugin, змонтувати як `openclaw qa ` і створити сценарії в `qa/scenarios/`. +Архітектура й назви scenario-helper для нових адаптерів каналів описані в [Огляд QA → Додавання каналу](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна планка: реалізуйте transport runner на спільному seam хоста `qa-lab`, оголосіть `qaRunners` у маніфесті плагіна, змонтуйте як `openclaw qa ` і створіть сценарії в `qa/scenarios/`. -## Набори тестів (що де запускається) +## Тестові набори (що де запускається) -Думайте про набори як про “зростання реалістичності” (і зростання нестабільності/вартості): +Думайте про набори як про «зростання реалістичності» (і зростання нестабільності/вартості): -### Модульні / інтеграційні (типово) +### Unit / integration (за замовчуванням) - Команда: `pnpm test` -- Конфігурація: нецільові запуски використовують набір shards `vitest.full-*.config.ts` і можуть розгортати multi-project shards у конфігурації за проєктами для паралельного планування -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts` і `test/**/*.test.ts`; модульні тести UI запускаються у виділеному shard `unit-ui` +- Конфігурація: нецільові запуски використовують набір shards `vitest.full-*.config.ts` і можуть розгортати multi-project shards у конфігурації окремих проєктів для паралельного планування +- Файли: core/unit-інвентарі в `src/**/*.test.ts`, `packages/**/*.test.ts` і `test/**/*.test.ts`; UI unit-тести запускаються у виділеному shard `unit-ui` - Обсяг: - - Чисті модульні тести - - Внутрішньопроцесні інтеграційні тести (автентифікація gateway, маршрутизація, інструменти, parsing, конфігурація) + - Чисті unit-тести + - In-process integration-тести (автентифікація gateway, маршрутизація, інструменти, парсинг, конфігурація) - Детерміновані регресії для відомих помилок - Очікування: - Запускається в CI - Не потребує реальних ключів - Має бути швидким і стабільним - - Тести resolver і public-surface loader мають доводити широку fallback-поведінку `api.js` і - `runtime-api.js` згенерованими крихітними фікстурами plugin, а не - реальними API вихідного коду вбудованих plugin. Реальні завантаження API plugin належать до - contract/integration наборів, якими володіє plugin. + - Тести resolver і loader публічної поверхні мають доводити broad fallback-поведінку `api.js` і + `runtime-api.js` за допомогою згенерованих крихітних plugin fixtures, а не + API вихідного коду реальних вбудованих плагінів. Завантаження API реальних плагінів належать до + contract/integration-наборів, якими володіють плагіни. - + - - Нецільовий `pnpm test` запускає дванадцять менших конфігурацій шардів (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного величезного нативного процесу кореневого проєкту. Це зменшує піковий RSS на навантажених машинах і не дає auto-reply/extension роботі витісняти непов’язані набори тестів. - - `pnpm test --watch` усе ще використовує нативний граф проєктів кореневого `vitest.config.ts`, бо цикл спостереження з кількома шардами непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спершу спрямовують явні цілі файлів/каталогів через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` не платить повну ціну запуску кореневого проєкту. - - `pnpm test:changed` за замовчуванням розгортає змінені git-шляхи в дешеві scoped lanes: прямі правки тестів, сусідні файли `*.test.ts`, явні зіставлення джерел і локальні залежні елементи графа імпортів. Правки config/setup/package не запускають широкі тести, якщо ви явно не використаєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. - - `pnpm check:changed` — звичайний розумний локальний check gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata, live Docker tooling і tooling, а потім запускає відповідні команди typecheck, lint і guard. Він не запускає Vitest-тести; для тестового підтвердження викликайте `pnpm test:changed` або явний `pnpm test `. Підвищення версій лише в release metadata запускають цільові перевірки version/config/root-dependency з guard, який відхиляє package-зміни поза полем версії верхнього рівня. - - Правки live Docker ACP harness запускають сфокусовані перевірки: синтаксис shell для live Docker auth scripts і dry-run live Docker scheduler. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; dependency, export, version та інші правки package-surface усе ще використовують ширші guards. - - Import-light unit-тести з agents, commands, plugins, auto-reply helpers, `plugin-sdk` і подібних чистих utility-ділянок спрямовуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли лишаються на наявних lanes. - - Вибрані helper source files `plugin-sdk` і `commands` також зіставляють changed-mode запуски з явними сусідніми тестами в цих light lanes, тож helper-правки не перезапускають увесь важкий набір для цього каталогу. - - `auto-reply` має окремі buckets для top-level core helpers, top-level `reply.*` integration tests і піддерева `src/auto-reply/reply/**`. CI додатково ділить reply-піддерево на шарди agent-runner, dispatch і commands/state-routing, щоб один import-heavy bucket не володів усім хвостом Node. - - Звичайний PR/main CI навмисно пропускає extension batch sweep і release-only шард `agentic-plugins`. Full Release Validation запускає окремий дочірній workflow `Plugin Prerelease` для цих plugin/extension-heavy наборів на release candidates. + - Ненацілені запуски `pnpm test` виконують дванадцять менших конфігурацій шардів (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського нативного процесу кореневого проєкту. Це зменшує пікове RSS на навантажених машинах і не дає роботі auto-reply/розширень виснажувати ресурси для непов’язаних наборів. + - `pnpm test --watch` усе ще використовує нативний граф проєктів кореневого `vitest.config.ts`, бо цикл watch із багатьма шардами непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку спрямовують явні цілі файлів/каталогів через обмежені смуги, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску кореневого проєкту. + - `pnpm test:changed` за замовчуванням розгортає змінені git-шляхи в дешеві обмежені смуги: прямі зміни тестів, сусідні файли `*.test.ts`, явні зіставлення джерел і локальні залежні елементи графа імпортів. Зміни конфігурації/налаштувань/пакетів не запускають тести широко, якщо ви явно не використаєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. + - `pnpm check:changed` — це звичайний розумний локальний контрольний шлюз для вузьких змін. Він класифікує diff на core, тести core, розширення, тести розширень, застосунки, docs, метадані релізу, live Docker tooling і tooling, а потім запускає відповідні команди typecheck, lint і guard. Він не запускає тести Vitest; для тестового підтвердження викликайте `pnpm test:changed` або явний `pnpm test `. Version bump лише для метаданих релізу запускає націлені перевірки версії/конфігурації/кореневих залежностей із guard, який відхиляє зміни пакетів поза полем версії верхнього рівня. + - Зміни live Docker ACP harness запускають сфокусовані перевірки: синтаксис shell для live Docker auth scripts і dry-run live Docker scheduler. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; зміни залежностей, export, версії та іншої поверхні пакета все ще використовують ширші guards. + - Легкі за імпортами unit-тести з agents, commands, plugins, helpers auto-reply, `plugin-sdk` і подібних областей чистих утиліт спрямовуються через смугу `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних смугах. + - Вибрані вихідні файли helper у `plugin-sdk` і `commands` також зіставляють запуски в changed-mode з явними сусідніми тестами в цих легких смугах, тож зміни helper уникають повторного запуску повного важкого набору для цього каталогу. + - `auto-reply` має окремі buckets для top-level core helpers, top-level інтеграційних тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково ділить піддерево reply на шарди agent-runner, dispatch і commands/state-routing, щоб один import-heavy bucket не володів повним Node-хвостом. + - Звичайний CI для PR/main навмисно пропускає пакетний sweep розширень і релізний шард `agentic-plugins`. Повна Release Validation запускає окремий дочірній workflow `Plugin Prerelease` для цих suite, важких на plugins/розширення, на реліз-кандидатах. - - Коли ви змінюєте вхідні дані для виявлення message-tool або runtime - контекст compaction, підтримуйте обидва рівні покриття. - - Додавайте сфокусовані helper-регресії для меж чистого routing і - normalization. - - Підтримуйте справність embedded runner integration suites: + - Коли ви змінюєте inputs для виявлення message-tool або runtime-контекст compaction, + зберігайте обидва рівні покриття. + - Додавайте сфокусовані регресійні тести helper для меж чистої маршрутизації та нормалізації. + - Підтримуйте працездатність інтеграційних suite 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-only тести - не є достатньою заміною для цих integration paths. + - Ці suite перевіряють, що scoped ids і поведінка compaction усе ще проходять + через реальні шляхи `run.ts` / `compact.ts`; тести лише helper + не є достатньою заміною для цих інтеграційних шляхів. @@ -439,323 +438,322 @@ pnpm openclaw qa credentials remove --credential-id - Базова конфігурація Vitest за замовчуванням використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - non-isolated runner для кореневих проєктів, e2e і live configs. - - Кореневий UI lane зберігає свої `jsdom` setup і optimizer, але також - працює на спільному non-isolated runner. - - Кожен шард `pnpm test` успадковує ті самі стандартні `threads` + `isolate: false` - зі спільної конфігурації Vitest. - - `scripts/run-vitest.mjs` за замовчуванням додає `--no-maglev` для дочірніх Node - процесів Vitest, щоб зменшити V8 compile churn під час великих локальних запусків. - Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною - поведінкою V8. + неізольований runner у кореневих проєктах, e2e та live-конфігураціях. + - Коренева UI-смуга зберігає свої `jsdom` setup і optimizer, але також працює + на спільному неізольованому runner. + - Кожен шард `pnpm test` успадковує ті самі значення за замовчуванням + `threads` + `isolate: false` зі спільної конфігурації Vitest. + - `scripts/run-vitest.mjs` за замовчуванням додає `--no-maglev` для дочірніх Node-процесів + Vitest, щоб зменшити компіляційний churn V8 під час великих локальних запусків. + Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - - `pnpm changed:lanes` показує, які architectural lanes запускає diff. - - Pre-commit hook лише форматує. Він повторно додає відформатовані файли в stage і - не запускає lint, typecheck або tests. - - Явно запускайте `pnpm check:changed` перед handoff або push, коли вам - потрібен smart local check gate. - - `pnpm test:changed` за замовчуванням спрямовує через дешеві scoped lanes. Використовуйте + - `pnpm changed:lanes` показує, які архітектурні смуги запускає diff. + - Pre-commit hook виконує лише форматування. Він повторно stage-ить відформатовані файли й + не запускає lint, typecheck або тести. + - Запускайте `pnpm check:changed` явно перед handoff або push, коли вам + потрібен розумний локальний контрольний шлюз. + - `pnpm test:changed` за замовчуванням спрямовується через дешеві обмежені смуги. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли agent - вирішує, що правка harness, config, package або contract справді потребує ширшого + вирішить, що зміна harness, config, package або contract справді потребує ширшого покриття Vitest. - - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку routing, + - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищою межею workers. - - Локальне auto-scaling workers навмисно консервативне й зменшує навантаження, - коли load average хоста вже високий, тож кілька одночасних - запусків Vitest за замовчуванням завдають меншої шкоди. - - Базова конфігурація Vitest позначає проєкти/config files як - `forceRerunTriggers`, щоб changed-mode reruns лишалися коректними, коли змінюється + - Локальне автоматичне масштабування workers навмисно консервативне й відступає, + коли середнє навантаження host уже високе, тож кілька одночасних запусків + Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає проєкти/конфігураційні файли як + `forceRerunTriggers`, щоб повторні запуски changed-mode залишалися коректними, коли змінюється test wiring. - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних - хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете - одну явну cache location для прямого profiling. + host; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + одне явне розташування cache для прямого профілювання. - - `pnpm test:perf:imports` вмикає звітування Vitest про import-duration плюс + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпортів плюс import-breakdown output. - - `pnpm test:perf:imports:changed` обмежує той самий profiling view файлами, - зміненими відносно `origin/main`. - - Дані shard timing записуються в `.artifacts/vitest-shard-timings.json`. - Whole-config runs використовують config path як ключ; include-pattern CI - shards додають назву шарда, щоб filtered shards можна було відстежувати + - `pnpm test:perf:imports:changed` обмежує той самий profiling view + файлами, зміненими після `origin/main`. + - Дані timing шардів записуються в `.artifacts/vitest-shard-timings.json`. + Whole-config запуски використовують шлях конфігурації як key; include-pattern CI + shards додають назву shard, щоб filtered shards можна було відстежувати окремо. - - Коли один hot test усе ще витрачає більшість часу на startup imports, - тримайте важкі dependencies за вузьким локальним seam `*.runtime.ts` і - mock-айте цей seam напряму замість deep-importing runtime helpers лише - для передавання їх через `vi.mock(...)`. + - Коли один hot test усе ще витрачає більшу частину часу на startup imports, + тримайте важкі залежності за вузьким локальним швом `*.runtime.ts` і + mock-айте цей шов напряму замість deep-importing runtime helpers лише + щоб пропустити їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює routed - `test:changed` з нативним шляхом root-project для цього committed - diff і виводить wall time плюс macOS max RSS. - - `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного - dirty tree, спрямовуючи список changed file через + `test:changed` із нативним шляхом root-project для цього committed + diff і друкує wall time плюс macOS max RSS. + - `pnpm test:perf:changed:bench -- --worktree` бенчмаркить поточне + dirty tree, маршрутизуючи changed file list через `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. - `pnpm test:perf:profile:main` записує main-thread CPU profile для - startup і transform overhead Vitest/Vite. + startup Vitest/Vite і transform overhead. - `pnpm test:perf:profile:runner` записує runner CPU+heap profiles для unit suite з вимкненим file parallelism. -### Стабільність (gateway) +### Стабільність (Gateway) - Команда: `pnpm test:stability:gateway` - Конфігурація: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - - Запускає справжній loopback Gateway з діагностикою, увімкненою за замовчуванням - - Проганяє синтетичний gateway message, memory і large-payload churn через diagnostic event path - - Запитує `diagnostics.stability` через Gateway WS RPC - - Покриває helpers для збереження diagnostic stability bundle - - Перевіряє, що recorder лишається bounded, synthetic RSS samples лишаються нижче pressure budget, а per-session queue depths повертаються до нуля + - Запускає реальний loopback Gateway із diagnostics, увімкненими за замовчуванням + - Проганяє synthetic gateway message, memory і large-payload churn через шлях diagnostic event + - Опитує `diagnostics.stability` через Gateway WS RPC + - Покриває helpers збереження diagnostic stability bundle + - Перевіряє, що recorder залишається bounded, synthetic RSS samples залишаються нижче pressure budget, а depths per-session queue повертаються до нуля - Очікування: - - Безпечно для CI і не потребує ключів - - Вузький lane для stability-regression follow-up, а не заміна повного Gateway suite + - Безпечно для CI й не потребує ключів + - Вузька смуга для подальшої роботи зі stability-regression, не заміна повного suite Gateway ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і bundled-plugin E2E tests у `extensions/` +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести bundled-plugin у `extensions/` - Runtime defaults: - - Використовує Vitest `threads` з `isolate: false`, як і решта repo. - - Використовує adaptive workers (CI: до 2, локально: за замовчуванням 1). + - Використовує Vitest `threads` із `isolate: false`, як і решта repo. + - Використовує adaptive workers (CI: до 2, local: 1 за замовчуванням). - За замовчуванням працює в silent mode, щоб зменшити overhead console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати worker count (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути verbose console output. + - `OPENCLAW_E2E_WORKERS=` для примусового worker count (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` для повторного ввімкнення verbose console output. - Обсяг: - - End-to-end поведінка multi-instance gateway - - WebSocket/HTTP surfaces, node pairing і важчий networking + - End-to-end поведінка багатьох екземплярів Gateway + - WebSocket/HTTP surfaces, pairing node і важчий networking - Очікування: - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж у unit tests (може бути повільніше) + - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) ### E2E: OpenShell backend smoke - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - - Запускає ізольований OpenShell gateway на хості через Docker + - Запускає ізольований OpenShell gateway на host через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє OpenShell backend OpenClaw через справжні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical filesystem behavior через sandbox fs bridge + - Випробовує OpenClaw OpenShell backend через реальні `sandbox ssh-config` + SSH exec + - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - Лише opt-in; не є частиною стандартного запуску `pnpm test:e2e` - Потребує локального `openshell` CLI і робочого Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, потім знищує test gateway і sandbox + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого e2e suite - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб указати нестандартний CLI binary або wrapper script + - `OPENCLAW_E2E_OPENSHELL=1` для ввімкнення тесту під час ручного запуску ширшого e2e suite + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` для вказання на нестандартний CLI binary або wrapper script -### Live (real providers + real models) +### Live (реальні providers + реальні models) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і bundled-plugin live tests у `extensions/` -- За замовчуванням: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести bundled-plugin у `extensions/` +- За замовчуванням: **увімкнено** через `pnpm test:live` (установлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - “Чи цей provider/model справді працює _сьогодні_ з реальними creds?” - - Виявляє зміни provider format, tool-calling quirks, auth issues і rate limit behavior + - Виявляє зміни format у provider, особливості tool-calling, auth issues і поведінку rate limit - Очікування: - - Навмисно не є CI-stable (реальні мережі, реальні provider policies, quotas, outages) + - За задумом не стабільний для CI (реальні мережі, реальні політики providers, quotas, outages) - Коштує грошей / використовує rate limits - - Віддавайте перевагу запуску звужених subsets замість “усього” -- Live runs завантажують `~/.profile`, щоб підхопити відсутні API keys. -- За замовчуванням live runs усе ще ізолюють `HOME` і копіюють config/auth material у тимчасовий test home, щоб unit fixtures не могли змінити ваш справжній `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live tests використовували ваш справжній home directory. -- `pnpm test:live` тепер за замовчуванням працює тихіше: він зберігає progress output `[live] ...`, але приховує додаткове повідомлення `~/.profile` і приглушує gateway bootstrap logs/Bonjour chatter. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні startup logs. -- Ротація API key (provider-specific): установіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) чи per-live override через `OPENCLAW_LIVE_*_KEY`; tests повторюють спробу на rate limit responses. + - Надавайте перевагу запуску звужених subsets замість “усього” +- Live-запуски source-ять `~/.profile`, щоб підхопити відсутні API keys. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють config/auth material у тимчасовий test home, щоб unit fixtures не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний home directory. +- `pnpm test:live` тепер за замовчуванням використовує тихіший режим: він зберігає progress output `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і mutes gateway bootstrap logs/Bonjour chatter. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні startup logs. +- Rotation API keys (provider-specific): задайте `*_API_KEYS` у форматі з comma/semicolon або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або per-live override через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу на rate limit responses. - Progress/heartbeat output: - - Live suites тепер виводять progress lines у stderr, щоб довгі provider calls були видимо активними, навіть коли Vitest console capture тихий. - - `vitest.live.config.ts` вимикає Vitest console interception, щоб provider/gateway progress lines одразу транслювалися під час live runs. - - Налаштовуйте direct-model heartbeats через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте gateway/probe heartbeats через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Live suite тепер виводять progress lines у stderr, щоб довгі provider calls були видимо активними навіть коли Vitest console capture тихий. + - `vitest.live.config.ts` вимикає Vitest console interception, тож provider/gateway progress lines stream-яться негайно під час live-запусків. + - Налаштуйте direct-model heartbeats за допомогою `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштуйте gateway/probe heartbeats за допомогою `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Який suite мені запускати? +## Який suite запускати? Використовуйте цю таблицю рішень: - Редагування логіки/тестів: запустіть `pnpm test` (і `pnpm test:coverage`, якщо ви змінили багато) -- Зміни в мережевій частині Gateway / WS-протоколі / сполученні: додайте `pnpm test:e2e` -- Налагодження “мій бот не працює” / помилок, специфічних для провайдера / виклику інструментів: запустіть звужений `pnpm test:live` +- Зміни в gateway-мережі / протоколі WS / спарюванні: додайте `pnpm test:e2e` +- Налагодження “мій бот не працює” / збоїв, специфічних для провайдера / виклику інструментів: запустіть звужений `pnpm test:live` -## Live (тести, що торкаються мережі) +## Live-тести (які торкаються мережі) -Для live-матриці моделей, smoke-тестів бекенда CLI, smoke-тестів ACP, harness app-server -Codex і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, зображення, -музика, відео, media harness), а також обробки облікових даних для live-запусків див. +Для live-матриці моделей, smoke-тестів бекенда CLI, smoke-тестів ACP, harness Codex app-server +і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, зображення, +музика, відео, media harness) — а також обробки облікових даних для live-запусків — див. [Тестування — live-набори](/uk/help/testing-live). -## Docker runners (необов’язкові перевірки "працює в Linux") +## Docker runner-и (необов’язкові перевірки "працює в Linux") -Ці Docker runners поділяються на дві групи: +Ці Docker runner-и поділяються на дві групи: -- Live-model runners: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл ключа профілю всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та робочий простір (і підвантажують `~/.profile`, якщо його змонтовано). Відповідні локальні точки входу: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live runners за замовчуванням використовують менший ліміт smoke-перевірок, щоб повний Docker-прогін залишався практичним: - `test:docker:live-models` за замовчуванням має `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` за замовчуванням має `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Runner-и live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл profile-key всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та робочу область (і підвантажують `~/.profile`, якщо його змонтовано). Відповідні локальні точки входу: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live runner-и за замовчуванням мають меншу межу smoke-тестів, щоб повний Docker sweep залишався практичним: + `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` за замовчуванням використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env vars, коли ви - явно хочете більший вичерпний скан. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, один раз пакує OpenClaw як npm-тарбол через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два образи `scripts/e2e/Dockerfile`. Базовий образ є лише Node/Git runner для напрямів install/update/plugin-dependency; ці напрями монтують попередньо зібраний тарбол. Функціональний образ встановлює той самий тарбол у `/app` для напрямів функціональності зібраного застосунку. Визначення Docker-напрямів містяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка планувальника міститься в `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегований запуск використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, тоді як ліміти ресурсів не дають важким live-, npm-install- і multi-service-напрямам стартувати одночасно. Якщо один напрям важчий за активні ліміти, планувальник усе одно може стартувати його, коли пул порожній, і потім тримає його єдиним запущеним, доки місткість знову не стане доступною. Типові значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker-хост має більше запасу. Runner за замовчуванням виконує Docker preflight, видаляє застарілі OpenClaw E2E-контейнери, друкує статус кожні 30 секунд, зберігає таймінги успішних напрямів у `.artifacts/docker-tests/lane-timings.json` і використовує ці таймінги, щоб у наступних запусках спершу стартували довші напрями. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати зважений маніфест напрямів без складання чи запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб надрукувати CI-план для вибраних напрямів, потреб у пакеті/образі та облікових даних. -- `Package Acceptance` — це GitHub-native шлюз пакета для питання "чи працює цей встановлюваний тарбол як продукт?" Він визначає один кандидатний пакет із `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає багаторазові Docker E2E-напрями проти саме цього тарбола замість повторного пакування вибраного ref. `workflow_ref` вибирає довірені скрипти workflow/harness, тоді як `package_ref` вибирає source commit/branch/tag для пакування, коли `source=ref`; це дає поточній acceptance-логіці змогу перевіряти старіші довірені коміти. Профілі впорядковано за широтою: `smoke` — це швидка перевірка install/channel/agent плюс gateway/config, `package` — це контракт package/update/plugin плюс keyless upgrade-survivor fixture, напрям published-baseline upgrade survivor і типова нативна заміна більшості покриття package/update у Parallels, `product` додає MCP-канали, очищення cron/subagent, OpenAI web search і OpenWebUI, а `full` запускає Docker-частини release-path з OpenWebUI. Для `published-upgrade-survivor` Package Acceptance завжди використовує `package-under-test` як кандидата і `published_upgrade_survivor_baseline` як fallback published baseline, за замовчуванням `openclaw@latest`; задайте `published_upgrade_survivor_baselines=release-history`, щоб розбити напрям на дедупліковану матрицю з останніх шести stable-релізів, `2026.4.23` і останнього stable-релізу перед `2026-03-15`. Опублікований напрям налаштовує свій baseline за допомогою вбудованого рецепта команди `openclaw config set`, а потім записує кроки рецепта в підсумок напряму. Release validation запускає custom package delta (`plugins-offline plugin-update`) плюс Telegram package QA, тому що Docker-частини release-path уже покривають суміжні напрями package/update/plugin. Цільові GitHub-команди повторного запуску Docker, згенеровані з артефактів, містять попередній артефакт пакета, підготовлені вхідні образи та список baseline для published upgrade-survivor, коли він доступний, щоб невдалі напрями могли уникнути повторної збірки пакета й образів. -- Перевірки складання й релізу запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Захист обходить статичний зібраний граф від `dist/entry.js` і `dist/cli/run-main.js` та падає, якщо startup до dispatch імпортує залежності пакета, як-от Commander, prompt UI, undici або logging, до dispatch команди; він також утримує зібраний gateway run chunk у межах бюджету й відхиляє статичні імпорти відомих cold gateway paths. Packaged CLI smoke також покриває root help, onboard help, doctor help, status, config schema і команду model-list. -- Застаріла сумісність Package Acceptance обмежена `2026.4.25` (включно з `2026.4.25-beta.*`). До цієї межі harness толерує лише прогалини метаданих уже випущених пакетів: пропущені приватні записи QA inventory, відсутній `gateway install --wrapper`, відсутні patch-файли у git fixture, отриманому з тарбола, відсутній збережений `update.channel`, застарілі розташування install-record для plugin, відсутню persistence install-record marketplace і міграцію метаданих конфігурації під час `plugins update`. Для пакетів після `2026.4.25` ці шляхи є суворими помилками. -- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці змінні середовища, коли ви + явно хочете більший вичерпний scan. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два образи `scripts/e2e/Dockerfile`. Bare-образ — це лише Node/Git runner для ліній install/update/plugin-dependency; ці лінії монтують попередньо зібраний tarball. Функціональний образ встановлює той самий tarball у `/app` для ліній функціональності зібраного застосунку. Визначення Docker-ліній містяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка планувальника міститься в `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегат використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а ресурсні обмеження не дають важким live-, npm-install- і multi-service-лініям стартувати всім одночасно. Якщо окрема лінія важча за активні обмеження, планувальник усе одно може запустити її, коли пул порожній, і потім тримає її єдиною запущеною, доки знову не з’явиться місткість. Значення за замовчуванням: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker-хост має більше запасу ресурсів. Runner за замовчуванням виконує Docker preflight, видаляє застарілі OpenClaw E2E-контейнери, друкує статус кожні 30 секунд, зберігає часи успішних ліній у `.artifacts/docker-tests/lane-timings.json` і використовує ці часи, щоб у наступних запусках спочатку стартували довші лінії. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати зважений маніфест ліній без збирання чи запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб надрукувати CI-план для вибраних ліній, потреб пакетів/образів і облікових даних. +- `Package Acceptance` — це GitHub-native gate пакета для перевірки "чи працює цей встановлюваний tarball як продукт?" Він визначає один пакет-кандидат із `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає багаторазові Docker E2E-лінії проти саме цього tarball замість повторного пакування вибраного ref. `workflow_ref` вибирає довірені workflow/harness-скрипти, а `package_ref` вибирає source commit/branch/tag для пакування, коли `source=ref`; це дає змогу поточній логіці acceptance перевіряти старіші довірені коміти. Профілі впорядковані за шириною охоплення: `smoke` — це швидкі install/channel/agent плюс gateway/config, `package` — це package/update/plugin contract плюс keyless upgrade-survivor fixture, published-baseline upgrade survivor lane і стандартна native-заміна для більшості Parallels package/update-покриття, `product` додає MCP-канали, очищення cron/subagent, OpenAI web search і OpenWebUI, а `full` запускає Docker-фрагменти release-path з OpenWebUI. Для `published-upgrade-survivor` Package Acceptance завжди використовує `package-under-test` як кандидата і `published_upgrade_survivor_baseline` як fallback published baseline, за замовчуванням `openclaw@latest`; задайте `published_upgrade_survivor_baselines=release-history`, щоб розбити лінію на deduped-матрицю з останніх шести стабільних релізів, `2026.4.23` і останнього стабільного релізу перед `2026-03-15`. Published-лінія налаштовує свій baseline за допомогою вбудованого рецепта команди `openclaw config set`, а потім записує кроки рецепта в підсумок лінії. Release validation запускає custom package delta (`plugins-offline plugin-update`) плюс Telegram package QA, бо release-path Docker-фрагменти вже покривають лінії package/update/plugin, що перетинаються. Цільові команди GitHub Docker rerun, згенеровані з артефактів, містять попередній package artifact, підготовлені image inputs і список baseline для published upgrade-survivor, коли він доступний, щоб невдалі лінії могли уникати повторного збирання пакета й образів. +- Перевірки build і release запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Guard проходить статичний зібраний граф від `dist/entry.js` і `dist/cli/run-main.js` та падає, якщо startup до dispatch імпортує залежності пакета, такі як Commander, prompt UI, undici або logging, до dispatch команди; він також утримує bundled gateway run chunk у межах бюджету й відхиляє статичні імпорти відомих cold gateway paths. Packaged CLI smoke також покриває root help, onboard help, doctor help, status, config schema і команду model-list. +- Legacy-сумісність Package Acceptance обмежена `2026.4.25` (включно з `2026.4.25-beta.*`). До цієї межі harness допускає лише прогалини metadata вже випущених пакетів: пропущені private QA inventory entries, відсутній `gateway install --wrapper`, відсутні patch-файли у git fixture, отриманому з tarball, відсутній збережений `update.channel`, старі місця install-record для plugin, відсутнє збереження marketplace install-record і міграція config metadata під час `plugins update`. Для пакетів після `2026.4.25` ці шляхи є строгими збоями. +- Container smoke runner-и: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або кілька реальних контейнерів і перевіряють високорівневі інтеграційні шляхи. -Live-model Docker runners також bind-mount лише потрібні домівки автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб external-CLI OAuth міг оновлювати токени без зміни сховища автентифікації хоста: +Live-model Docker runner-и також bind-mount-ять лише потрібні CLI auth homes (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб external-CLI OAuth міг оновлювати токени без змін у host auth store: - Прямі моделі: `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`; типово охоплює Claude, Codex і Gemini, зі строгим покриттям Droid/OpenCode через `pnpm test:docker:live-acp-bind:droid` і `pnpm test:docker:live-acp-bind:opencode`) -- Smoke CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Smoke harness сервера застосунку Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + агент розробки: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Smoke observability: `pnpm qa:otel:smoke` — це приватний lane перевірки source checkout для QA. Його навмисно не включено до package Docker release lanes, бо npm tarball не містить QA Lab. +- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) +- Observability smoke: `pnpm qa:otel:smoke` — приватна QA-доріжка з source-checkout. Її навмисно не включено до Docker-доріжок релізу пакета, бо npm-архів не містить QA Lab. - Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) - Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Smoke onboarding/channel/agent для npm tarball: `pnpm test:docker:npm-onboard-channel-agent` встановлює запакований OpenClaw tarball глобально в Docker, налаштовує OpenAI через onboarding з env-ref і типово Telegram, запускає doctor і виконує один замоканий хід агента OpenAI. Повторно використайте попередньо зібраний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host rebuild через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемкніть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Smoke перемикання update channel: `pnpm test:docker:update-channel-switch` встановлює запакований OpenClaw tarball глобально в Docker, перемикає з package `stable` на git `dev`, перевіряє збережений канал і роботу Plugin після оновлення, потім перемикає назад на package `stable` і перевіряє статус оновлення. -- Smoke upgrade survivor: `pnpm test:docker:upgrade-survivor` встановлює запакований OpenClaw tarball поверх забрудненої фікстури старого користувача з агентами, конфігурацією каналів, allowlists Plugin, застарілим станом залежностей Plugin і наявними файлами workspace/session. Він запускає оновлення package плюс неінтерактивний doctor без live provider або ключів каналів, потім запускає loopback Gateway і перевіряє збереження config/state, а також startup/status budgets. -- Smoke published upgrade survivor: `pnpm test:docker:published-upgrade-survivor` типово встановлює `openclaw@latest`, сіє реалістичні файли наявного користувача, налаштовує цей baseline за допомогою вбудованого command recipe, перевіряє отриманий config, оновлює опубліковане встановлення до candidate tarball, запускає неінтерактивний doctor, записує `.artifacts/upgrade-survivor/summary.json`, потім запускає loopback Gateway і перевіряє налаштовані intents, збереження стану, startup, `/healthz`, `/readyz` і RPC status budgets. Перевизначте один baseline через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, попросіть aggregate scheduler розгорнути точні baselines через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` і розгорніть фікстури у формі issue через `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS`, як-от `reported-issues`; Package Acceptance надає їх як `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` і `published_upgrade_survivor_scenarios`. -- Smoke session runtime context: `pnpm test:docker:session-runtime-context` перевіряє збереження прихованого runtime context transcript плюс repair через doctor для уражених дубльованих гілок prompt-rewrite. -- Smoke глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольований home і перевіряє, що `openclaw infer image providers --json` повертає bundled image providers замість зависання. Повторно використайте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host build через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` із зібраного Docker image через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Smoke installer Docker: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm cache для своїх root, update і direct-npm контейнерів. Update smoke типово використовує npm `latest` як stable baseline перед оновленням до candidate tarball. Перевизначте через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` локально або через input `update_baseline_version` workflow Install Smoke на GitHub. Перевірки non-root installer зберігають ізольований npm cache, щоб cache entries, власником яких є root, не маскували поведінку user-local install. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати root/update/direct-npm cache між локальними повторними запусками. -- Install Smoke CI пропускає дубльоване direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. -- Smoke CLI видалення агентами спільного workspace: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) типово збирає image з кореневого Dockerfile, сіє двох агентів з одним workspace в ізольованому container home, запускає `agents delete --json` і перевіряє валідний JSON плюс поведінку retained workspace. Повторно використайте install-smoke image через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. -- Мережа Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Smoke snapshot Browser CDP: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає source E2E image плюс шар Chromium, запускає Chromium із raw CDP, виконує `browser doctor --deep` і перевіряє, що snapshots ролей CDP охоплюють URL посилань, clickables, підвищені cursor, iframe refs і frame metadata. -- Регресія OpenAI Responses web_search minimal reasoning: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає замоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово відхиляє provider schema і перевіряє, що raw detail з’являється в логах Gateway. +- Npm tarball onboarding/channel/agent smoke: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding з env-ref і типово Telegram, запускає doctor і виконує один змодельований хід агента OpenAI. Повторно використайте попередньо зібраний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть rebuild на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Update channel switch smoke: `pnpm test:docker:update-channel-switch` глобально встановлює запакований tarball OpenClaw у Docker, перемикає пакет із `stable` на git `dev`, перевіряє збережений канал і роботу Plugin після оновлення, потім перемикає назад на пакет `stable` і перевіряє статус оновлення. +- Upgrade survivor smoke: `pnpm test:docker:upgrade-survivor` встановлює запакований tarball OpenClaw поверх забрудненого fixture старого користувача з агентами, конфігурацією каналу, allowlist Plugin, застарілим станом залежностей Plugin і наявними файлами workspace/session. Він виконує оновлення пакета плюс неінтерактивний doctor без живих ключів провайдера чи каналу, потім запускає loopback Gateway і перевіряє збереження config/state, а також бюджети startup/status. +- Published upgrade survivor smoke: `pnpm test:docker:published-upgrade-survivor` типово встановлює `openclaw@latest`, засіває реалістичні файли наявного користувача, налаштовує цю базову версію за вбудованим рецептом команд, перевіряє отриману конфігурацію, оновлює це опубліковане встановлення до candidate tarball, запускає неінтерактивний doctor, записує `.artifacts/upgrade-survivor/summary.json`, потім запускає loopback Gateway і перевіряє налаштовані intents, збереження стану, startup, `/healthz`, `/readyz` і бюджети RPC status. Перевизначте одну базову версію через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, попросіть aggregate scheduler розгорнути точні базові версії через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` і розгорніть issue-подібні fixtures через `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS`, наприклад `reported-issues`; Package Acceptance відкриває їх як `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` і `published_upgrade_survivor_scenarios`. +- Session runtime context smoke: `pnpm test:docker:session-runtime-context` перевіряє збереження transcript прихованого runtime context плюс doctor repair для зачеплених дубльованих гілок prompt-rewrite. +- Bun global install smoke: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає bundled image providers замість зависання. Повторно використайте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host build через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` із зібраного Docker image через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Installer Docker smoke: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm cache для своїх root, update і direct-npm контейнерів. Update smoke типово використовує npm `latest` як stable baseline перед оновленням до candidate tarball. Перевизначте через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` локально або через input `update_baseline_version` workflow Install Smoke на GitHub. Перевірки non-root installer тримають ізольований npm cache, щоб cache entries, власником яких є root, не маскували поведінку встановлення user-local. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використати root/update/direct-npm cache між локальними повторними запусками. +- Install Smoke CI пропускає дубльоване direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття direct `npm install -g`. +- Agents delete shared workspace CLI smoke: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) типово будує root Dockerfile image, засіває двох агентів з одним workspace в ізольованому container home, запускає `agents delete --json` і перевіряє валідний JSON плюс поведінку збереженого workspace. Повторно використайте install-smoke image через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. +- Gateway networking (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Browser CDP snapshot smoke: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) будує source E2E image плюс шар Chromium, запускає Chromium із raw CDP, виконує `browser doctor --deep` і перевіряє, що CDP role snapshots охоплюють link URLs, cursor-promoted clickables, iframe refs і frame metadata. +- OpenAI Responses web_search minimal reasoning regression: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змодельований OpenAI server через Gateway, перевіряє, що `web_search` піднімає `reasoning.effort` з `minimal` до `low`, потім примусово викликає reject provider schema і перевіряє, що raw detail зʼявляється в логах Gateway. - MCP channel bridge (засіяний Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти MCP Pi bundle (справжній stdio MCP server + smoke embedded Pi profile allow/deny): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення Cron/subagent MCP (справжній Gateway + teardown дочірнього stdio MCP після ізольованих запусків cron і one-shot subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (install smoke, ClawHub kitchen-sink install/uninstall, marketplace updates і Claude-bundle enable/inspect): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) - Установіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити блок ClawHub, або перевизначте типову пару kitchen-sink package/runtime через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Без `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` тест використовує герметичний локальний сервер фікстури ClawHub. -- Smoke незміненого оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke metadata перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Plugins: `pnpm test:docker:plugins` охоплює install smoke, встановлення локальних фікстур ClawHub, marketplace updates, встановлення залежностей npm package і Claude-bundle enable/inspect. `pnpm test:docker:plugin-update` охоплює поведінку незміненого оновлення для встановлених plugins. +- Pi bundle MCP tools (реальний stdio MCP server + вбудований Pi profile allow/deny smoke): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Cron/subagent MCP cleanup (реальний Gateway + teardown дочірнього stdio MCP після ізольованих запусків cron і one-shot subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (install smoke, встановлення/видалення kitchen-sink із ClawHub, marketplace updates і enable/inspect для Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) + Установіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити блок ClawHub, або перевизначте типову пару kitchen-sink package/runtime через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Без `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` тест використовує герметичний локальний fixture server ClawHub. +- Plugin update unchanged smoke: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Config reload metadata smoke: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Plugins: `pnpm test:docker:plugins` охоплює install smoke, встановлення з локального fixture ClawHub, marketplace updates, встановлення залежностей npm package і enable/inspect для Claude-bundle. `pnpm test:docker:plugin-update` охоплює поведінку unchanged update для встановлених plugins. -Щоб вручну попередньо зібрати й повторно використовувати спільний функціональний image: +Щоб вручну попередньо зібрати та повторно використати спільний functional image: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення image для окремих suite, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, коли встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на remote shared image, скрипти завантажують його, якщо він ще не є локальним. QR і installer Docker tests зберігають власні Dockerfiles, бо вони перевіряють поведінку package/install, а не спільний built-app runtime. +Suite-specific image overrides, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе одно мають пріоритет, коли встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на remote shared image, скрипти pull його, якщо він ще не є локальним. Docker-тести QR та installer тримають власні Dockerfiles, бо вони перевіряють поведінку package/install, а не спільний runtime built-app. -Docker runner-и live-model також монтують поточний checkout лише для читання і -stage його в тимчасовий workdir всередині контейнера. Це зберігає runtime -image компактним, водночас усе ще запускаючи Vitest проти вашого точного локального source/config. -Крок staging пропускає великі локальні-only caches і app build outputs, як-от +Docker runners для live-model також bind-mount поточний checkout у режимі read-only і +розгортають його в тимчасовий workdir усередині контейнера. Це зберігає runtime +image компактним, водночас запускаючи Vitest проти саме вашого локального source/config. +Крок staging пропускає великі локальні-only caches і app build outputs, такі як `.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також app-local `.build` або -каталоги output Gradle, щоб Docker live runs не витрачали хвилини на копіювання +Gradle output directories, щоб Docker live runs не витрачали хвилини на копіювання machine-specific artifacts. -Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live probes Gateway не запускали -справжніх workers каналів Telegram/Discord/тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити live coverage Gateway -із цього Docker lane. +Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб gateway live probes не запускали +реальні Telegram/Discord/etc. channel workers усередині контейнера. +`test:docker:live-models` усе одно запускає `pnpm test:live`, тому також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway +live coverage із цієї Docker lane. `test:docker:openwebui` — це вищорівневий compatibility smoke: він запускає -контейнер OpenClaw gateway з увімкненими OpenAI-сумісними HTTP endpoints, -запускає pinned контейнер Open WebUI проти цього gateway, виконує вхід через -Open WebUI, перевіряє, що `/api/models` надає `openclaw/default`, а потім надсилає -справжній chat request через proxy `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, бо Docker може знадобитися завантажити -image Open WebUI, а Open WebUI може знадобитися завершити власне cold-start setup. -Цей lane очікує придатний live model key, а `OPENCLAW_PROFILE_FILE` +контейнер Gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoints, +запускає pinned контейнер Open WebUI проти цього gateway, входить через +Open WebUI, перевіряє, що `/api/models` відкриває `openclaw/default`, потім надсилає +реальний chat request через proxy Open WebUI `/api/chat/completions`. +Перший запуск може бути помітно повільнішим, бо Docker може потребувати pull +image Open WebUI, а Open WebUI може потребувати завершення власного cold-start setup. +Ця lane очікує придатний live model key, і `OPENCLAW_PROFILE_FILE` (типово `~/.profile`) є основним способом надати його в Dockerized runs. Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно deterministic і не потребує -справжнього облікового запису Telegram, Discord або iMessage. Він завантажує засіяний Gateway -container, запускає другий container, який породжує `openclaw mcp serve`, потім +`test:docker:mcp-channels` навмисно детермінований і не потребує +реального облікового запису Telegram, Discord або iMessage. Він завантажує засіяний Gateway +container, запускає другий контейнер, що spawn `openclaw mcp serve`, потім перевіряє routed conversation discovery, transcript reads, attachment metadata, -поведінку live event queue, outbound send routing і channel + -permission notifications у стилі Claude через справжній stdio MCP bridge. Перевірка notification -інспектує raw stdio MCP frames напряму, тож smoke перевіряє те, що -bridge справді emits, а не лише те, що конкретний client SDK випадково expose. -`test:docker:pi-bundle-mcp-tools` deterministic і не потребує live -model key. Він збирає repo Docker image, запускає справжній stdio MCP probe server -всередині container, materializes цей server через embedded Pi bundle +поведінку live event queue, outbound send routing і Claude-style channel + +permission notifications через реальний stdio MCP bridge. Перевірка notification +інспектує raw stdio MCP frames напряму, щоб smoke перевіряв те, що +bridge фактично emit, а не лише те, що випадково показує конкретний client SDK. +`test:docker:pi-bundle-mcp-tools` детермінований і не потребує live +model key. Він будує repo Docker image, запускає реальний stdio MCP probe server +усередині контейнера, матеріалізує цей server через вбудований Pi bundle MCP runtime, виконує tool, потім перевіряє, що `coding` і `messaging` зберігають `bundle-mcp` tools, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. -`test:docker:cron-mcp-cleanup` deterministic і не потребує live model -key. Він запускає seeded Gateway зі справжнім stdio MCP probe server, виконує -isolated cron turn і one-shot child turn `/subagents spawn`, потім перевіряє, -що дочірній процес MCP завершується після кожного запуску. +`test:docker:cron-mcp-cleanup` детермінований і не потребує live model +key. Він запускає засіяний Gateway із реальним stdio MCP probe server, виконує +ізольований cron turn і one-shot child turn `/subagents spawn`, потім перевіряє, +що MCP child process завершується після кожного запуску. -Ручний ACP smoke потоку plain-language (не CI): +Ручний ACP plain-language thread smoke (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Збережіть цей скрипт для regression/debug workflow. Він може знову знадобитися для перевірки ACP thread routing, тому не видаляйте його. +- Зберігайте цей скрипт для regression/debug workflow. Він може знову знадобитися для перевірки ACP thread routing, тому не видаляйте його. Корисні env vars: -- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується до `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується до `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується до `/home/node/.profile` і завантажується перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише змінні середовища, завантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги конфігурації/робочої області та без зовнішніх монтувань автентифікації CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується до `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker -- Зовнішні каталоги/файли автентифікації CLI у `$HOME` монтуються лише для читання у `/host-auth...`, а потім копіюються до `/home/node/...` перед початком тестів +- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`), змонтовано до `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`), змонтовано до `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`), змонтовано до `/home/node/.profile` і підвантажено перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише змінні env, підвантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без зовнішніх монтувань автентифікації CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`), змонтовано до `/home/node/.npm-global` для кешованих інсталяцій CLI усередині Docker +- Зовнішні каталоги/файли автентифікації CLI у `$HOME` монтуються лише для читання у `/host-auth...`, а потім копіюються до `/home/node/...` перед стартом тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Перевизначте вручну за допомогою `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або списку через кому, як-от `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Перевизначте вручну за допомогою `OPENCLAW_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`, щоб переконатися, що облікові дані надходять зі сховища профілю (не з середовища) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway надає для smoke-тесту Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити запит перевірки nonce, який використовує smoke-тест Open WebUI +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів у контейнері +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібне повторне складання +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища профілю (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway надає для Open WebUI smoke +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовується Open WebUI smoke - `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI ## Перевірка документації -Запускайте перевірки документації після редагування документації: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли також потрібні перевірки заголовків на сторінці: `pnpm docs:check-links:anchors`. +Запускайте перевірки документації після редагування документів: `pnpm check:docs`. +Запускайте повну перевірку anchors Mintlify, коли також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресії (безпечні для CI) +## Offline-регресія (безпечна для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів Gateway (mock OpenAI, реальний Gateway + цикл агента): `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 loop): `src/gateway/gateway.test.ts` (case: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, записує config + enforced auth): `src/gateway/gateway.test.ts` (case: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агентів (Skills) +## Оцінювання надійності агента (skills) -Ми вже маємо кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»: +У нас уже є кілька безпечних для CI тестів, які поводяться як «agent reliability evals»: -- Mock-виклик інструментів через реальний Gateway + цикл агента (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють зв’язування сеансу та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Mock tool-calling через реальний gateway + agent loop (`src/gateway/gateway.test.ts`). +- Наскрізні потоки майстра, які перевіряють wiring сесії та ефекти config (`src/gateway/gateway.test.ts`). -Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого ще бракує для skills (див. [Skills](/uk/tools/skills)): -- **Ухвалення рішень:** коли Skills перелічені в запиті, чи агент обирає правильний skill (або уникає нерелевантних)? -- **Відповідність вимогам:** чи агент читає `SKILL.md` перед використанням і виконує потрібні кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сеансу та межі sandbox. +- **Ухвалення рішень:** коли skills перелічені в prompt, чи агент вибирає правильний skill (або уникає нерелевантних)? +- **Відповідність:** чи агент читає `SKILL.md` перед використанням і дотримується потрібних кроків/аргументів? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні оцінювання мають передусім залишатися детермінованими: +Майбутні evals спершу мають залишатися детермінованими: -- Виконавець сценаріїв, що використовує mock-провайдерів для перевірки викликів інструментів + порядку, читання файлів skill і зв’язування сеансу. -- Невеликий набір сценаріїв, сфокусованих на skill (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live-оцінювання (opt-in, з gate через змінні середовища) лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв із mock providers для перевірки tool calls + order, читання skill files і wiring сесії. +- Невеликий набір сценаріїв, зосереджених на skills (use vs avoid, gating, prompt injection). +- Необов’язкові live evals (opt-in, через env gate) лише після того, як буде створено безпечний для CI набір. -## Контрактні тести (форма Plugin і каналу) +## Контрактні тести (форма plugin і каналу) -Контрактні тести перевіряють, що кожен зареєстрований Plugin і канал відповідає своєму -контракту інтерфейсу. Вони ітеруються всіма виявленими Plugin і запускають набір -перевірок форми та поведінки. Типовий unit lane `pnpm test` навмисно -пропускає ці спільні файли швів і smoke-тестів; запускайте контрактні команди явно, -коли змінюєте спільні поверхні каналу або провайдера. +Контрактні тести перевіряють, що кожен зареєстрований plugin і канал відповідає своєму +інтерфейсному контракту. Вони проходять усі виявлені plugins і запускають набір +перевірок форми та поведінки. Типова unit lane `pnpm test` навмисно +пропускає ці спільні файли seam і smoke; запускайте контрактні команди явно, +коли змінюєте спільні поверхні каналів або провайдерів. ### Команди @@ -767,17 +765,17 @@ isolated cron turn і one-shot child turn `/subagents spawn`, потім пер Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма Plugin (id, name, capabilities) +- **plugin** - Базова форма plugin (id, name, capabilities) - **setup** - Контракт майстра налаштування -- **session-binding** - Поведінка зв’язування сеансу +- **session-binding** - Поведінка прив’язування сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій каналу -- **threading** - Обробка ID тредів -- **directory** - API каталогу/реєстру +- **threading** - Обробка ID thread +- **directory** - Directory/roster API - **group-policy** - Застосування групової політики -### Контракти статусу провайдерів +### Контракти статусу провайдера Розташовані в `src/plugins/contracts/*.contract.test.ts`. @@ -790,7 +788,7 @@ isolated cron turn і one-shot child turn `/subagents spawn`, потім пер - **auth** - Контракт потоку автентифікації - **auth-choice** - Вибір автентифікації -- **catalog** - API каталогу моделей +- **catalog** - Model catalog API - **discovery** - Виявлення Plugin - **loader** - Завантаження Plugin - **runtime** - Runtime провайдера @@ -799,24 +797,24 @@ isolated cron turn і one-shot child turn `/subagents spawn`, потім пер ### Коли запускати -- Після зміни експортів або підшляхів plugin-sdk -- Після додавання або модифікації каналу чи Plugin провайдера +- Після зміни exports або subpaths plugin-sdk +- Після додавання або змінення каналу чи provider plugin - Після рефакторингу реєстрації або виявлення Plugin -Контрактні тести виконуються в CI і не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API keys. ## Додавання регресій (настанови) Коли ви виправляєте проблему провайдера/моделі, виявлену в live: -- Додайте безпечну для CI регресію, якщо можливо (mock/stub провайдера або захоплення точної трансформації форми запиту) -- Якщо це за своєю природою лише live (ліміти частоти, політики автентифікації), тримайте live-тест вузьким і opt-in через змінні середовища -- Віддавайте перевагу націлюванню на найменший шар, який ловить помилку: - - помилка конвертації/відтворення запиту провайдера → прямий тест моделей - - помилка pipeline сеансу/історії/інструментів Gateway → live smoke Gateway або безпечний для CI mock-тест Gateway -- Захисний бар’єр обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id із сегментами обходу відхиляються. - - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Додайте безпечну для CI регресію, якщо можливо (mock/stub provider або зафіксуйте точне перетворення request-shape) +- Якщо це за своєю суттю лише live-only (rate limits, auth policies), зробіть live test вузьким і opt-in через env vars +- Надавайте перевагу найменшому шару, який ловить bug: + - bug перетворення/відтворення provider request → прямий models test + - bug pipeline Gateway session/history/tool → gateway live smoke або безпечний для CI gateway mock test +- Guardrail обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибрану ціль для кожного класу SecretRef з metadata реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec ids із traversal segment відхиляються. + - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target ids, щоб нові класи не можна було пропустити непомітно. ## Пов’язане diff --git a/docs/uk/reference/RELEASING.md b/docs/uk/reference/RELEASING.md index a5019adf7..85d04365a 100644 --- a/docs/uk/reference/RELEASING.md +++ b/docs/uk/reference/RELEASING.md @@ -1,246 +1,246 @@ --- read_when: - - Пошук визначень публічних каналів випуску + - Шукаємо визначення публічних каналів випуску - Запуск перевірки релізу або приймання пакета - - Пошук інформації про найменування версій і періодичність випусків -summary: Лінії релізів, контрольний список оператора, валідаційні бокси, іменування версій і періодичність + - Шукаєте іменування версій і періодичність випусків +summary: Канали випусків, контрольний список оператора, валідаційні бокси, іменування версій і періодичність title: Політика випусків x-i18n: - generated_at: "2026-05-01T20:41:04Z" + generated_at: "2026-05-01T20:49:28Z" model: gpt-5.5 provider: openai - source_hash: 2c764896371f67abdf7b7e85605f03136d4ed905cb74b73b56fe8c5965e84883 + source_hash: 9897d7388f9110f291a62a908c95b58abe099be688d6a398c28dc368059e163f source_path: reference/RELEASING.md workflow: 16 --- OpenClaw має три публічні канали випусків: -- stable: теговані випуски, які за замовчуванням публікуються в npm `beta`, або в npm `latest`, коли це явно запитано -- beta: передрелізні теги, які публікуються в npm `beta` -- dev: рухома вершина `main` +- stable: позначені тегами випуски, які за замовчуванням публікуються в npm `beta`, або в npm `latest`, коли це явно запитано +- beta: теги передрелізів, які публікуються в npm `beta` +- dev: рухома голова `main` -## Іменування версій +## Назви версій - Версія стабільного випуску: `YYYY.M.D` - Git-тег: `vYYYY.M.D` -- Версія коригувального стабільного випуску: `YYYY.M.D-N` +- Версія корекційного стабільного випуску: `YYYY.M.D-N` - Git-тег: `vYYYY.M.D-N` - Версія beta-передрелізу: `YYYY.M.D-beta.N` - Git-тег: `vYYYY.M.D-beta.N` -- Не доповнюйте місяць або день нулями +- Не додавайте початковий нуль до місяця або дня - `latest` означає поточний просунутий стабільний npm-випуск -- `beta` означає поточну ціль встановлення beta -- Стабільні та коригувальні стабільні випуски за замовчуванням публікуються в npm `beta`; оператори випуску можуть явно вказати `latest` або просунути перевірену beta-збірку пізніше -- Кожен стабільний випуск OpenClaw постачає npm-пакет і macOS-застосунок разом; +- `beta` означає поточну beta-ціль установлення +- Стабільні та корекційні стабільні випуски за замовчуванням публікуються в npm `beta`; оператори випуску можуть явно націлити `latest` або просунути перевірену beta-збірку пізніше +- Кожен стабільний випуск OpenClaw постачає npm-пакет і застосунок macOS разом; beta-випуски зазвичай спочатку перевіряють і публікують шлях npm/пакета, а - збирання/підписування/нотаризація mac-застосунку резервуються для стабільного випуску, якщо інше не запитано явно + збірку/підпис/нотаризацію застосунку macOS залишають для stable, якщо це явно не запитано -## Періодичність випусків +## Частота випусків - Випуски рухаються спочатку через beta -- Стабільний випуск іде лише після перевірки найновішої beta -- Супровідники зазвичай створюють випуски з гілки `release/YYYY.M.D`, створеної - з поточної `main`, щоб перевірка випуску та виправлення не блокували нову +- Stable виходить лише після перевірки останньої beta +- Мейнтейнери зазвичай роблять випуски з гілки `release/YYYY.M.D`, створеної + з поточного `main`, щоб перевірка випуску й виправлення не блокували нову розробку в `main` -- Якщо beta-тег уже було надіслано або опубліковано і він потребує виправлення, супровідники створюють +- Якщо beta-тег уже було надіслано або опубліковано й він потребує виправлення, мейнтейнери створюють наступний тег `-beta.N` замість видалення або повторного створення старого beta-тега -- Детальна процедура випуску, схвалення, облікові дані та примітки з відновлення - доступні лише супровідникам +- Докладна процедура випуску, затвердження, облікові дані та нотатки з відновлення + доступні лише мейнтейнерам ## Контрольний список оператора випуску -Цей контрольний список описує публічну форму процесу випуску. Приватні облікові дані, -підписування, нотаризація, відновлення dist-tag і деталі екстреного відкату залишаються в -runbook випуску лише для супровідників. +Цей контрольний список є публічною формою процесу випуску. Приватні облікові дані, +підписування, нотаризація, відновлення dist-tag і деталі аварійного відкату залишаються в +runbook випуску лише для мейнтейнерів. -1. Почніть із поточної `main`: отримайте найновіші зміни, підтвердьте, що цільовий коміт надіслано, - і переконайтеся, що поточна CI `main` достатньо зелена, щоб відгалузитися від неї. -2. Перепишіть верхній розділ `CHANGELOG.md` з реальної історії комітів за допомогою - `/changelog`, залиште записи орієнтованими на користувачів, закомітьте його, надішліть його та виконайте rebase/pull +1. Почніть із поточного `main`: отримайте останні зміни, підтвердьте, що цільовий коміт надіслано, + і підтвердьте, що поточний CI `main` достатньо зелений, щоб створити від нього гілку. +2. Перепишіть верхній розділ `CHANGELOG.md` на основі реальної історії комітів за допомогою + `/changelog`, залиште записи орієнтованими на користувача, закомітьте його, надішліть і виконайте rebase/pull ще раз перед створенням гілки. 3. Перегляньте записи сумісності випуску в `src/plugins/compat/registry.ts` і `src/commands/doctor/shared/deprecation-compat.ts`. Видаляйте прострочену сумісність лише тоді, коли шлях оновлення залишається покритим, або зафіксуйте, чому її - навмисно збережено. -4. Створіть `release/YYYY.M.D` з поточної `main`; не виконуйте звичайну роботу над випуском + навмисно залишено. +4. Створіть `release/YYYY.M.D` з поточного `main`; не виконуйте звичайну роботу з випуску безпосередньо в `main`. -5. Оновіть кожне потрібне місце з версією для запланованого тегу, потім запустіть - локальну детерміновану попередню перевірку: +5. Оновіть кожне потрібне місце версії для запланованого тега, потім запустіть + локальний детермінований preflight: `pnpm check:test-types`, `pnpm check:architecture`, `pnpm build && pnpm ui:build` і `pnpm release:check`. -6. Запустіть `OpenClaw NPM Release` з `preflight_only=true`. До появи тегу - повний 40-символьний SHA гілки випуску дозволено для попередньої перевірки лише з метою валідації. +6. Запустіть `OpenClaw NPM Release` з `preflight_only=true`. До існування тега + для validation-only preflight дозволено повний 40-символьний SHA гілки випуску. Збережіть успішний `preflight_run_id`. 7. Запустіть усі передрелізні тести через `Full Release Validation` для - гілки випуску, тегу або повного SHA коміту. Це єдина ручна точка входу - для чотирьох великих тестових боксів випуску: Vitest, Docker, QA Lab і Package. -8. Якщо валідація не проходить, виправте в гілці випуску та повторно запустіть найменший невдалий - файл, канал, завдання workflow, профіль пакета, провайдера або allowlist моделі, що - доводить виправлення. Повторно запускайте весь umbrella лише тоді, коли змінена поверхня робить + гілки випуску, тега або повного SHA коміту. Це єдина ручна точка входу + для чотирьох великих тестових середовищ випуску: Vitest, Docker, QA Lab і Package. +8. Якщо перевірка завершується невдало, виправте в гілці випуску й повторно запустіть найменший невдалий + файл, канал, завдання workflow, профіль пакета, provider або allowlist моделей, що + доводить виправлення. Повторно запускайте повну парасольку лише тоді, коли змінена поверхня робить попередні докази застарілими. 9. Для beta позначте тегом `vYYYY.M.D-beta.N`, опублікуйте з npm dist-tag `beta`, потім запустіть - приймання пакета після публікації проти опублікованого пакета `openclaw@YYYY.M.D-beta.N` + post-publish package acceptance для опублікованого пакета `openclaw@YYYY.M.D-beta.N` або `openclaw@beta`. Якщо надіслана або опублікована beta потребує виправлення, створіть наступний `-beta.N`; не видаляйте й не переписуйте стару beta. -10. Для стабільного випуску продовжуйте лише після того, як перевірена beta або release candidate має - потрібні докази валідації. Публікація стабільного npm повторно використовує успішний - артефакт попередньої перевірки через `preflight_run_id`; готовність стабільного macOS-випуску - також вимагає запакованих `.zip`, `.dmg`, `.dSYM.zip` і оновленого +10. Для stable продовжуйте лише після того, як перевірена beta або кандидат на випуск має + потрібні докази перевірки. Публікація stable npm повторно використовує успішний + preflight-артефакт через `preflight_run_id`; готовність stable macOS-випуску + також потребує запакованих `.zip`, `.dmg`, `.dSYM.zip` і оновленого `appcast.xml` у `main`. -11. Після публікації запустіть npm-верифікатор після публікації, необов'язковий окремий - опублікований-npm Telegram E2E, коли потрібен доказ каналу після публікації, +11. Після публікації запустіть npm post-publish verifier, необов’язковий автономний + published-npm Telegram E2E, коли потрібен доказ каналу після публікації, просування dist-tag за потреби, нотатки GitHub release/prerelease з повного відповідного розділу `CHANGELOG.md` і кроки оголошення випуску. -## Попередня перевірка випуску +## Release preflight - Запустіть `pnpm check:test-types` перед передрелізною перевіркою, щоб тестовий TypeScript залишався покритим поза швидшим локальним gate `pnpm check` -- Запустіть `pnpm check:architecture` перед передрелізною перевіркою, щоб ширші перевірки циклів - імпортів і меж архітектури були зеленими поза швидшим локальним gate +- Запустіть `pnpm check:architecture` перед передрелізною перевіркою, щоб ширші перевірки + циклів імпорту та архітектурних меж були green поза швидшим локальним gate - Запустіть `pnpm build && pnpm ui:build` перед `pnpm release:check`, щоб очікувані - релізні артефакти `dist/*` і пакет Control UI існували для кроку - перевірки пакування + релізні артефакти `dist/*` і bundle Control UI існували для кроку + валідації пакування - Запустіть ручний workflow `Full Release Validation` перед затвердженням релізу, щоб - запустити всі передрелізні тестові бокси з однієї точки входу. Він приймає гілку, - тег або повний SHA коміту, запускає ручний `CI` і запускає + запустити всі передрелізні test boxes з однієї точки входу. Він приймає branch, + tag або повний commit SHA, запускає ручний `CI` і запускає `OpenClaw Release Checks` для install smoke, package acceptance, Docker release-path suites, live/E2E, OpenWebUI, QA Lab parity, Matrix і Telegram - lanes. Надавайте `npm_telegram_package_spec` лише після публікації пакета - і коли післяпублікаційний Telegram E2E також має бути запущений. Надавайте - `evidence_package_spec`, коли приватний звіт доказів має підтвердити, що - перевірка відповідає опублікованому npm-пакету без примусового запуску Telegram E2E. + lanes. Передавайте `npm_telegram_package_spec` лише після того, як пакет + опубліковано і також має виконатися post-publish Telegram E2E. Передавайте + `evidence_package_spec`, коли приватний evidence report має довести, що + validation відповідає опублікованому npm package, без примусового Telegram E2E. Приклад: `gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D` - Запустіть ручний workflow `Package Acceptance`, коли потрібне side-channel підтвердження для кандидата пакета, поки релізна робота триває. Використовуйте `source=npm` для `openclaw@beta`, `openclaw@latest` або точної версії релізу; `source=ref`, - щоб запакувати довірену гілку/тег/SHA `package_ref` з поточним + щоб спакувати довірений branch/tag/SHA `package_ref` з поточним harness `workflow_ref`; `source=url` для HTTPS tarball з обов’язковим - SHA-256; або `source=artifact` для tarball, завантаженого іншим запуском GitHub - Actions. Workflow розв’язує кандидата до - `package-under-test`, повторно використовує Docker E2E release scheduler для цього - tarball і може запускати Telegram QA для того самого tarball з + SHA-256; або `source=artifact` для tarball, завантаженого іншим GitHub + Actions run. Workflow resolve-ить кандидата в + `package-under-test`, повторно використовує Docker E2E release scheduler проти цього + tarball і може запускати Telegram QA проти того самого tarball з `telegram_mode=mock-openai` або `telegram_mode=live-frontier`. Коли вибрані Docker lanes містять `published-upgrade-survivor`, артефакт пакета є кандидатом, а `published_upgrade_survivor_baseline` вибирає опублікований baseline. Приклад: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai` - Типові профілі: - - `smoke`: lanes для install/channel/agent, gateway network і config reload - - `package`: artifact-native lanes для package/update/plugin без OpenWebUI або live ClawHub + Поширені профілі: + - `smoke`: lanes встановлення/channel/agent, мережі gateway і перезавантаження config + - `package`: artifact-native package/update/plugin lanes без OpenWebUI або live ClawHub - `product`: профіль package плюс MCP channels, cron/subagent cleanup, OpenAI web search і OpenWebUI - `full`: Docker release-path chunks з OpenWebUI - `custom`: точний вибір `docker_lanes` для сфокусованого повторного запуску - Запустіть ручний workflow `CI` напряму, коли потрібне лише повне звичайне CI - покриття для кандидата релізу. Ручні dispatch для CI обходять changed + coverage для release candidate. Ручні CI dispatches обходять changed scoping і примусово запускають Linux Node shards, bundled-plugin shards, channel contracts, сумісність Node 22, `check`, `check-additional`, build smoke, - перевірки docs, Python skills, Windows, macOS, Android і Control UI i18n + docs checks, Python skills, Windows, macOS, Android і Control UI i18n lanes. Приклад: `gh workflow run ci.yml --ref release/YYYY.M.D` -- Запустіть `pnpm qa:otel:smoke`, коли перевіряєте релізну telemetry. Він проганяє - QA-lab через локальний OTLP/HTTP receiver і перевіряє експортовані назви trace - span, обмежені атрибути та редагування content/identifier без потреби в - Opik, Langfuse або іншому зовнішньому collector. -- Запускайте `pnpm release:check` перед кожним релізом із тегом +- Запустіть `pnpm qa:otel:smoke` під час валідації release telemetry. Він перевіряє + QA-lab через локальний OTLP/HTTP receiver і верифікує експортовані trace + span names, обмежені attributes та редагування content/identifier без + потреби в Opik, Langfuse або іншому зовнішньому collector. +- Запускайте `pnpm release:check` перед кожним tagged release - Release checks тепер виконуються в окремому ручному workflow: `OpenClaw Release Checks` -- `OpenClaw Release Checks` також запускає gate mock parity QA Lab плюс швидкий +- `OpenClaw Release Checks` також запускає QA Lab mock parity gate плюс швидкий live Matrix profile і Telegram QA lane перед затвердженням релізу. Live lanes використовують environment `qa-live-shared`; Telegram також використовує Convex CI credential leases. Запустіть ручний workflow `QA-Lab - All Lanes` з `matrix_profile=all` і `matrix_shards=true`, коли потрібен повний Matrix - transport, media та E2EE inventory паралельно. + transport, media і E2EE inventory паралельно. - Cross-OS install і upgrade runtime validation є частиною публічних `OpenClaw Release Checks` і `Full Release Validation`, які напряму викликають reusable workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml` -- Це розділення навмисне: реальний npm release path має бути коротким, - детермінованим і зосередженим на артефактах, тоді як повільніші live checks лишаються у власному - lane, щоб вони не затримували й не блокували publish -- Release checks із секретами слід dispatch через `Full Release +- Цей поділ навмисний: тримати справжній npm release path коротким, + детермінованим і сфокусованим на артефактах, тоді як повільніші live checks залишаються у своєму + власному lane, щоб вони не затримували й не блокували publish +- Secret-bearing release checks слід dispatch-ити через `Full Release Validation` або з workflow ref `main`/release, щоб workflow logic і secrets залишалися контрольованими -- `OpenClaw Release Checks` приймає гілку, тег або повний SHA коміту, якщо - розв’язаний коміт доступний з гілки OpenClaw або release tag +- `OpenClaw Release Checks` приймає branch, tag або повний commit SHA, якщо + resolved commit reachable з OpenClaw branch або release tag - Validation-only preflight `OpenClaw NPM Release` також приймає поточний - повний 40-символьний SHA коміту workflow branch без потреби у pushed tag -- Цей SHA path призначений лише для validation і не може бути підвищений до реального publish + повний 40-символьний workflow-branch commit SHA без вимоги pushed tag +- Цей SHA path є validation-only і не може бути promoted у справжній publish - У SHA mode workflow синтезує `v` лише для - перевірки package metadata; реальний publish усе ще потребує реального release tag -- Обидва workflows тримають реальний publish і promotion path на GitHub-hosted - runners, тоді як немутуючий validation path може використовувати більші + package metadata check; справжній publish усе ще потребує справжнього release tag +- Обидва workflows тримають справжній publish і promotion path на GitHub-hosted + runners, тоді як немутувальний validation path може використовувати більші Blacksmith Linux runners - Цей workflow запускає `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache` з використанням workflow secrets `OPENAI_API_KEY` і `ANTHROPIC_API_KEY` - npm release preflight більше не чекає на окремий release checks lane - Запустіть `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts` - (або відповідний beta/correction tag) перед approval + (або відповідний beta/correction tag) перед затвердженням - Після npm publish запустіть `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D` (або відповідну beta/correction version), щоб перевірити published registry install path у свіжому temp prefix -- Після beta publish запустіть `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live` - щоб перевірити onboarding установленого пакета, налаштування Telegram і реальний Telegram E2E - проти опублікованого npm-пакета з використанням спільного leased Telegram credential - pool. Локальні одноразові запуски maintainer можуть пропустити Convex vars і передати три +- Після beta publish запустіть `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`, + щоб перевірити installed-package onboarding, Telegram setup і справжній Telegram E2E + проти опублікованого npm package з використанням shared leased Telegram credential + pool. Локальні одноразові maintainer запуски можуть опустити Convex vars і передати три env credentials `OPENCLAW_QA_TELEGRAM_*` напряму. -- Maintainers можуть запускати таку саму post-publish check з GitHub Actions через - ручний workflow `NPM Telegram Beta E2E`. Він навмисно лише ручний і - не запускається на кожному merge. +- Maintainers можуть запустити ту саму post-publish check з GitHub Actions через + ручний workflow `NPM Telegram Beta E2E`. Він навмисно manual-only і + не запускається при кожному merge. - Maintainer release automation тепер використовує preflight-then-promote: - - реальний npm publish має пройти успішний npm `preflight_run_id` - - реальний npm publish має бути dispatch з тієї самої гілки `main` або + - справжній npm publish має пройти успішний npm `preflight_run_id` + - справжній npm publish має бути dispatched з того самого branch `main` або `release/YYYY.M.D`, що й успішний preflight run - - stable npm releases за замовчуванням спрямовані на `beta` + - stable npm releases default to `beta` - stable npm publish може явно націлюватися на `latest` через workflow input - - token-based npm dist-tag mutation тепер живе в + - token-based npm dist-tag mutation тепер міститься в `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` - з міркувань безпеки, бо `npm dist-tag add` усе ще потребує `NPM_TOKEN`, тоді як - публічний репозиторій тримає OIDC-only publish - - публічний `macOS Release` є validation-only; коли tag існує лише на - release branch, але workflow запускається з `main`, встановіть + для безпеки, бо `npm dist-tag add` досі потребує `NPM_TOKEN`, тоді як + public repo зберігає OIDC-only publish + - public `macOS Release` є validation-only; коли tag існує лише на + release branch, але workflow dispatched з `main`, задайте `public_release_branch=release/YYYY.M.D` - - реальний private mac publish має пройти успішні private mac + - справжній private mac publish має пройти успішні private mac `preflight_run_id` і `validate_run_id` - - реальні publish paths просувають підготовлені артефакти замість повторного + - справжні publish paths promote підготовлені артефакти замість повторного rebuilding - Для stable correction releases на кшталт `YYYY.M.D-N` post-publish verifier також перевіряє той самий temp-prefix upgrade path з `YYYY.M.D` до `YYYY.M.D-N`, - щоб release corrections не могли непомітно лишити старіші global installs на + щоб release corrections не могли непомітно залишити старіші global installs на базовому stable payload -- npm release preflight fail-closed, якщо tarball не містить і - `dist/control-ui/index.html`, і непорожній payload `dist/control-ui/assets/`, - щоб ми знову не відправили порожню browser dashboard +- npm release preflight fails closed, якщо tarball не містить одночасно + `dist/control-ui/index.html` і непорожній payload `dist/control-ui/assets/`, + щоб ми знову не відвантажили порожню browser dashboard - Post-publish verification також перевіряє, що published plugin entrypoints і - package metadata присутні в установленому registry layout. Реліз, у якому - відсутні plugin runtime payloads, не проходить postpublish verifier і + package metadata присутні в installed registry layout. Реліз, який + відвантажує відсутні plugin runtime payloads, провалює postpublish verifier і не може бути promoted до `latest`. -- `pnpm test:install:smoke` також примусово перевіряє бюджет npm pack `unpackedSize` для - candidate update tarball, щоб installer e2e ловив випадкове pack bloat +- `pnpm test:install:smoke` також enforce-ить budget `unpackedSize` npm pack на + candidate update tarball, тож installer e2e виявляє випадкове pack bloat до release publish path - Якщо release work торкнулася CI planning, extension timing manifests або - extension test matrices, згенеруйте повторно та перегляньте planner-owned - matrix outputs `plugin-prerelease-extension-shard` з - `.github/workflows/plugin-prerelease.yml` перед approval, щоб release notes не - описували застарілий CI layout -- Готовність stable macOS release також включає updater surfaces: - - GitHub release має в підсумку містити запаковані `.zip`, `.dmg` і `.dSYM.zip` + extension test matrices, regenerate і review planner-owned + `plugin-prerelease-extension-shard` matrix outputs з + `.github/workflows/plugin-prerelease.yml` перед затвердженням, щоб release notes не + описували stale CI layout +- Stable macOS release readiness також включає updater surfaces: + - GitHub release має зрештою містити packaged `.zip`, `.dmg` і `.dSYM.zip` - `appcast.xml` на `main` має вказувати на новий stable zip після publish - packaged app має зберігати non-debug bundle id, непорожній Sparkle feed URL і `CFBundleVersion` на рівні або вище canonical Sparkle build floor для цієї release version -## Релізні тестові бокси +## Release test boxes -`Full Release Validation` — це спосіб, яким operators запускають усі передрелізні тести з +`Full Release Validation` — це спосіб, яким operators запускають усі передрелізні tests з однієї точки входу. Запускайте його з довіреного workflow ref `main` і передавайте release -branch, tag або full commit SHA як `ref`: +branch, tag або повний commit SHA як `ref`: ```bash gh workflow run full-release-validation.yml \ @@ -252,23 +252,23 @@ gh workflow run full-release-validation.yml \ -f evidence_package_spec=openclaw@YYYY.M.D-beta.N ``` -Workflow розв’язує target ref, dispatch manual `CI` з -`target_ref=`, dispatch `OpenClaw Release Checks` і -за потреби dispatch standalone post-publish Telegram E2E, коли -`npm_telegram_package_spec` встановлено. Далі `OpenClaw Release Checks` розгалужує +Workflow resolve-ить target ref, dispatch-ить ручний `CI` з +`target_ref=`, dispatch-ить `OpenClaw Release Checks` і +опційно dispatch-ить standalone post-publish Telegram E2E, коли +`npm_telegram_package_spec` задано. Потім `OpenClaw Release Checks` fan out-ить install smoke, cross-OS release checks, live/E2E Docker release-path coverage, Package Acceptance з Telegram package QA, QA Lab parity, live Matrix і -live Telegram. Повний запуск прийнятний лише тоді, коли summary `Full Release Validation` -показує `normal_ci` і `release_checks` як успішні, а будь-який optional -child `npm_telegram` або успішний, або навмисно skipped. Final -verifier summary містить таблиці slowest-job для кожного child run, щоб release +live Telegram. Повний run прийнятний лише тоді, коли summary `Full Release Validation` +показує `normal_ci` і `release_checks` як successful, а будь-який optional +child `npm_telegram` або successful, або intentionally skipped. Final +verifier summary містить slowest-job tables для кожного child run, щоб release manager міг бачити поточний critical path без завантаження logs. Див. [Full release validation](/uk/reference/full-release-validation) для -повної stage matrix, точних workflow job names, відмінностей між stable і full profile, +повної stage matrix, точних workflow job names, відмінностей stable та full profile, artifacts і focused rerun handles. -Child workflows запускаються з довіреного ref, який запускає `Full Release +Child workflows dispatch-яться з trusted ref, який запускає `Full Release Validation`, зазвичай `--ref main`, навіть коли target `ref` вказує на -старішу release branch або tag. Окремого workflow-ref input для Full Release Validation +старіший release branch або tag. Окремого workflow-ref input для Full Release Validation немає; вибирайте trusted harness, вибираючи workflow run ref. Використовуйте `release_profile`, щоб вибрати ширину live/provider: @@ -277,7 +277,7 @@ Validation`, зазвичай `--ref main`, навіть коли target `ref` - `stable`: minimum плюс stable provider/backend coverage для release approval - `full`: stable плюс широке advisory provider/media coverage -`OpenClaw Release Checks` використовує довірене посилання workflow, щоб один раз визначити цільове посилання як `release-package-under-test`, і повторно використовує цей артефакт як у Docker-перевірках release-path, так і в Package Acceptance. Це тримає всі бокси, що працюють із пакетом, на тих самих байтах і уникає повторних збірок пакета. Cross-OS OpenAI install smoke використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли змінна repo/org задана, інакше `openai/gpt-5.4-mini`, тому що ця lane доводить встановлення пакета, onboarding, запуск gateway і один live agent turn, а не бенчмарк найповільнішої типової моделі. Ширша live provider matrix залишається місцем для model-specific покриття. +`OpenClaw Release Checks` використовує довірене посилання workflow, щоб один раз визначити цільове посилання як `release-package-under-test`, і повторно використовує цей артефакт як у Docker-перевірках release-path, так і в Прийнятності пакета. Це утримує всі box-и, що працюють із пакетами, на тих самих байтах і уникає повторних збірок пакета. Cross-OS OpenAI install smoke використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли задано змінну repo/org, інакше `openai/gpt-5.5`, тому що ця lane підтверджує встановлення пакета, onboarding, запуск gateway і один live agent turn, а не бенчмарк найповільнішої моделі за замовчуванням. Ширша матриця live provider лишається місцем для покриття, специфічного для моделей. Використовуйте ці варіанти залежно від етапу релізу: @@ -308,22 +308,22 @@ gh workflow run full-release-validation.yml \ -f npm_telegram_provider_mode=mock-openai ``` -Не використовуйте повну парасольку як перший повторний запуск після сфокусованого виправлення. Якщо один box падає, використовуйте failed child workflow, job, Docker lane, package profile, model provider або QA lane для наступного доказу. Запускайте повну парасольку знову лише тоді, коли виправлення змінило спільну release orchestration або зробило попередні all-box докази застарілими. Фінальний verifier парасольки повторно перевіряє записані child workflow run ids, тому після успішного повторного запуску child workflow повторно запускайте лише failed parent job `Verify full validation`. +Не використовуйте повний umbrella як перший повторний запуск після цільового виправлення. Якщо один box падає, використовуйте невдалий дочірній workflow, job, Docker lane, профіль пакета, провайдера моделі або QA lane для наступного підтвердження. Запускайте повний umbrella знову лише тоді, коли виправлення змінило спільну release orchestration або зробило попередні докази з усіх box-ів застарілими. Фінальний verifier umbrella повторно перевіряє записані ідентифікатори запусків дочірніх workflow, тому після успішного повторного запуску дочірнього workflow перезапускайте лише невдалий батьківський job `Verify full validation`. -Для обмеженого відновлення передайте `rerun_group` до парасольки. `all` — це справжній release-candidate run, `ci` запускає лише normal CI child, `plugin-prerelease` запускає лише release-only plugin child, `release-checks` запускає кожен release box, а вужчі release groups — це `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` і `npm-telegram`, коли надано standalone package Telegram lane. +Для обмеженого відновлення передайте `rerun_group` до umbrella. `all` — це справжній запуск release-candidate, `ci` запускає лише звичайний дочірній CI, `plugin-prerelease` запускає лише release-only дочірній plugin, `release-checks` запускає кожен release box, а вужчі release-групи — це `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` і `npm-telegram`, коли надано автономну package Telegram lane. ### Vitest -Vitest box — це ручний child workflow `CI`. Manual CI навмисно обходить changed scoping і примусово запускає normal test graph для release candidate: Linux Node shards, bundled-plugin shards, channel contracts, Node 22 compatibility, `check`, `check-additional`, build smoke, docs checks, Python skills, Windows, macOS, Android і Control UI i18n. +Vitest box — це ручний дочірній workflow `CI`. Ручний CI навмисно обходить changed scoping і примусово запускає звичайний граф тестів для release candidate: Linux Node shards, bundled-plugin shards, channel contracts, сумісність Node 22, `check`, `check-additional`, build smoke, docs checks, Python skills, Windows, macOS, Android і Control UI i18n. -Використовуйте цей box, щоб відповісти: «чи пройшло source tree повний normal test suite?» Це не те саме, що release-path product validation. Докази, які треба зберегти: +Використовуйте цей box, щоб відповісти на запитання «чи пройшло дерево вихідного коду повний звичайний набір тестів?» Це не те саме, що release-path product validation. Докази, які слід зберігати: -- summary `Full Release Validation`, що показує dispatched `CI` run URL -- `CI` run зелений на exact target SHA -- назви failed або slow shards із CI jobs під час розслідування регресій -- артефакти Vitest timing, такі як `.artifacts/vitest-shard-timings.json`, коли run потребує аналізу продуктивності +- summary `Full Release Validation`, що показує URL запущеного `CI` +- зелений запуск `CI` на точному цільовому SHA +- назви невдалих або повільних shard-ів із CI jobs під час розслідування регресій +- артефакти таймінгу Vitest, як-от `.artifacts/vitest-shard-timings.json`, коли запуск потребує аналізу продуктивності -Запускайте manual CI напряму лише тоді, коли релізу потрібен deterministic normal CI, але не потрібні Docker, QA Lab, live, cross-OS або package boxes: +Запускайте ручний CI напряму лише тоді, коли релізу потрібен детермінований звичайний CI, але не потрібні Docker, QA Lab, live, cross-OS або package boxes: ```bash gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D @@ -331,12 +331,12 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D ### Docker -Docker box живе в `OpenClaw Release Checks` через `openclaw-live-and-e2e-checks-reusable.yml`, а також у release-mode workflow `install-smoke`. Він перевіряє release candidate через packaged Docker environments, а не лише source-level tests. +Docker box живе в `OpenClaw Release Checks` через `openclaw-live-and-e2e-checks-reusable.yml`, а також у release-mode workflow `install-smoke`. Він перевіряє release candidate через упаковані Docker-середовища, а не лише через тести рівня вихідного коду. Покриття release Docker включає: -- full install smoke з увімкненим slow Bun global install smoke -- підготовку/повторне використання root Dockerfile smoke image за target SHA, з QR, root/gateway і installer/Bun smoke jobs, що запускаються як окремі install-smoke shards +- повний install smoke з увімкненим повільним Bun global install smoke +- підготовку/повторне використання root Dockerfile smoke image за цільовим SHA, із QR, root/gateway та installer/Bun smoke jobs, що запускаються як окремі install-smoke shards - repository E2E lanes - release-path Docker chunks: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, @@ -345,13 +345,14 @@ Docker box живе в `OpenClaw Release Checks` через `openclaw-live-and-e `plugins-runtime-install-c`, `plugins-runtime-install-d`, `plugins-runtime-install-e`, `plugins-runtime-install-f`, `plugins-runtime-install-g` і `plugins-runtime-install-h` -- OpenWebUI coverage всередині chunk `plugins-runtime-services`, коли це запитано +- покриття OpenWebUI всередині chunk `plugins-runtime-services`, коли це запитано - розділені bundled plugin install/uninstall lanes `bundled-plugin-install-uninstall-0` через `bundled-plugin-install-uninstall-23` -- live/E2E provider suites і Docker live model coverage, коли release checks включають live suites +- live/E2E provider suites і Docker live model coverage, коли release checks + включають live suites -Використовуйте Docker artifacts перед повторним запуском. Release-path scheduler завантажує `.artifacts/docker-tests/` з lane logs, `summary.json`, `failures.json`, phase timings, scheduler plan JSON і rerun commands. Для сфокусованого відновлення використовуйте `docker_lanes=` у reusable live/E2E workflow замість повторного запуску всіх release chunks. Згенеровані rerun commands включають попередні `package_artifact_run_id` і prepared Docker image inputs, коли вони доступні, тому failed lane може повторно використати той самий tarball і GHCR images. +Використовуйте Docker-артефакти перед повторним запуском. Release-path scheduler завантажує `.artifacts/docker-tests/` із lane logs, `summary.json`, `failures.json`, phase timings, scheduler plan JSON і командами повторного запуску. Для цільового відновлення використовуйте `docker_lanes=` у reusable live/E2E workflow замість повторного запуску всіх release chunks. Згенеровані команди повторного запуску включають попередній `package_artifact_run_id` і prepared Docker image inputs, коли вони доступні, тож невдала lane може повторно використати той самий tarball і GHCR images. ### QA Lab @@ -359,31 +360,29 @@ QA Lab box також є частиною `OpenClaw Release Checks`. Це agenti Покриття release QA Lab включає: -- mock parity gate, що порівнює OpenAI candidate lane з Opus 4.6 baseline за допомогою agentic parity pack +- mock parity gate, що порівнює OpenAI candidate lane з базовою лінією Opus 4.6 за допомогою agentic parity pack - fast live Matrix QA profile з використанням середовища `qa-live-shared` - live Telegram QA lane з використанням Convex CI credential leases -- `pnpm qa:otel:smoke`, коли release telemetry потребує явного local proof +- `pnpm qa:otel:smoke`, коли release telemetry потребує явного локального доказу -Використовуйте цей box, щоб відповісти: «чи реліз поводиться правильно у QA scenarios і live channel flows?» Зберігайте artifact URLs для parity, Matrix і Telegram lanes під час схвалення релізу. Full Matrix coverage залишається доступним як manual sharded QA-Lab run, а не default release-critical lane. +Використовуйте цей box, щоб відповісти на запитання «чи реліз поводиться правильно у QA scenarios і live channel flows?» Зберігайте URL артефактів для parity, Matrix і Telegram lanes під час схвалення релізу. Повне Matrix coverage лишається доступним як ручний sharded QA-Lab run, а не як default release-critical lane. -### Package +### Пакет -Package box — це installable-product gate. Він підтримується `Package Acceptance` і resolver `scripts/resolve-openclaw-package-candidate.mjs`. Resolver нормалізує candidate у tarball `package-under-test`, який споживає Docker E2E, перевіряє package inventory, записує package version і SHA-256, а також тримає workflow harness ref окремо від package source ref. +Package box — це gate для installable-product. Він спирається на `Package Acceptance` і resolver `scripts/resolve-openclaw-package-candidate.mjs`. Resolver нормалізує candidate у tarball `package-under-test`, який споживає Docker E2E, перевіряє package inventory, записує версію пакета й SHA-256 та тримає workflow harness ref окремо від package source ref. Підтримувані джерела candidate: -- `source=npm`: `openclaw@beta`, `openclaw@latest` або exact OpenClaw release - version -- `source=ref`: пакує trusted `package_ref` branch, tag або full commit SHA - із вибраним harness `workflow_ref` -- `source=url`: завантажує HTTPS `.tgz` з обов’язковим `package_sha256` -- `source=artifact`: повторно використовує `.tgz`, завантажений іншим GitHub Actions run +- `source=npm`: `openclaw@beta`, `openclaw@latest` або точна версія релізу OpenClaw +- `source=ref`: запакувати довірену гілку `package_ref`, tag або full commit SHA з вибраним harness `workflow_ref` +- `source=url`: завантажити HTTPS `.tgz` з обов’язковим `package_sha256` +- `source=artifact`: повторно використати `.tgz`, завантажений іншим запуском GitHub Actions -`OpenClaw Release Checks` запускає Package Acceptance з `source=ref`, `package_ref=`, `suite_profile=custom`, `docker_lanes=plugins-offline plugin-update` і `telegram_mode=mock-openai`. Release-path Docker chunks покривають overlapping install, update і plugin-update lanes; Package Acceptance тримає offline plugin fixtures, plugin update і Telegram package QA на тому самому resolved tarball. Це GitHub-native заміна для більшості package/update coverage, яке раніше вимагало Parallels. Cross-OS release checks усе ще важливі для OS-specific onboarding, installer і platform behavior, але package/update product validation має віддавати перевагу Package Acceptance. +`OpenClaw Release Checks` запускає Прийнятність пакета з `source=ref`, `package_ref=`, `suite_profile=custom`, `docker_lanes=plugins-offline plugin-update` і `telegram_mode=mock-openai`. Release-path Docker chunks покривають перетин install, update і plugin-update lanes; Прийнятність пакета зберігає offline plugin fixtures, plugin update і Telegram package QA проти того самого resolved tarball. Це GitHub-native заміна більшої частини package/update coverage, яке раніше потребувало Parallels. Cross-OS release checks усе ще важливі для OS-specific onboarding, installer і platform behavior, але package/update product validation має віддавати перевагу Прийнятності пакета. -Legacy package-acceptance leniency навмисно обмежена в часі. Packages до `2026.4.25` включно можуть використовувати compatibility path для metadata gaps, уже опублікованих у npm: private QA inventory entries, відсутні в tarball, відсутній `gateway install --wrapper`, відсутні patch files у tarball-derived git fixture, відсутній persisted `update.channel`, legacy plugin install-record locations, відсутня marketplace install-record persistence і config metadata migration під час `plugins update`. Опублікований package `2026.4.26` може попереджати про local build metadata stamp files, які вже були поставлені. Пізніші packages мають відповідати modern package contracts; ті самі gaps провалюють release validation. +Поблажливість legacy package-acceptance навмисно обмежена в часі. Пакети до `2026.4.25` включно можуть використовувати compatibility path для metadata gaps, уже опублікованих у npm: приватні QA inventory entries, відсутні в tarball, відсутній `gateway install --wrapper`, відсутні patch files у tarball-derived git fixture, відсутній persisted `update.channel`, legacy plugin install-record locations, відсутнє marketplace install-record persistence і config metadata migration під час `plugins update`. Опублікований пакет `2026.4.26` може попереджати про local build metadata stamp files, які вже були shipped. Пізніші пакети мають задовольняти сучасні package contracts; ті самі прогалини провалюють release validation. -Використовуйте ширші Package Acceptance profiles, коли release question стосується фактичного installable package: +Використовуйте ширші профілі Прийнятності пакета, коли release question стосується фактичного installable package: ```bash gh workflow run package-acceptance.yml \ @@ -397,82 +396,76 @@ gh workflow run package-acceptance.yml \ Поширені package profiles: -- `smoke`: quick package install/channel/agent, gateway network і config +- `smoke`: швидкі package install/channel/agent, gateway network і config reload lanes -- `package`: install/update/plugin package contracts без live ClawHub; це release-check - default +- `package`: install/update/plugin package contracts без live ClawHub; це default для release-check - `product`: `package` плюс MCP channels, cron/subagent cleanup, OpenAI web search і OpenWebUI - `full`: Docker release-path chunks з OpenWebUI -- `custom`: точний список `docker_lanes` для focused reruns +- `custom`: точний список `docker_lanes` для цільових повторних запусків -Для package-candidate Telegram proof увімкніть `telegram_mode=mock-openai` або `telegram_mode=live-frontier` у Package Acceptance. Workflow передає resolved tarball `package-under-test` у Telegram lane; standalone Telegram workflow усе ще приймає published npm spec для post-publish checks. +Для package-candidate Telegram proof увімкніть `telegram_mode=mock-openai` або `telegram_mode=live-frontier` у Прийнятності пакета. Workflow передає resolved tarball `package-under-test` у Telegram lane; автономний Telegram workflow усе ще приймає published npm spec для post-publish checks. -## Вхідні дані NPM workflow +## Вхідні параметри NPM workflow -`OpenClaw NPM Release` приймає ці operator-controlled inputs: +`OpenClaw NPM Release` приймає такі керовані оператором вхідні параметри: -- `tag`: обов’язковий release tag, такий як `v2026.4.2`, `v2026.4.2-1` або +- `tag`: обов’язковий release tag, як-от `v2026.4.2`, `v2026.4.2-1` або `v2026.4.2-beta.1`; коли `preflight_only=true`, це також може бути поточний - full 40-character workflow-branch commit SHA для validation-only preflight -- `preflight_only`: `true` для validation/build/package only, `false` для - real publish path -- `preflight_run_id`: обов’язковий на real publish path, щоб workflow повторно використовував - prepared tarball з successful preflight run -- `npm_dist_tag`: npm target tag для publish path; типово `beta` + повний 40-символьний workflow-branch commit SHA для validation-only preflight +- `preflight_only`: `true` для лише validation/build/package, `false` для + справжнього publish path +- `preflight_run_id`: обов’язковий у справжньому publish path, щоб workflow повторно використав prepared tarball з успішного preflight run +- `npm_dist_tag`: npm target tag для publish path; за замовчуванням `beta` -`OpenClaw Release Checks` приймає ці operator-controlled inputs: +`OpenClaw Release Checks` приймає такі керовані оператором вхідні параметри: -- `ref`: branch, tag або full commit SHA для перевірки. Secret-bearing checks - вимагають, щоб resolved commit був reachable з OpenClaw branch або - release tag. +- `ref`: гілка, tag або full commit SHA для перевірки. Перевірки із секретами вимагають, щоб resolved commit був досяжний із гілки OpenClaw або release tag. Правила: - Stable і correction tags можуть публікуватися або в `beta`, або в `latest` - Beta prerelease tags можуть публікуватися лише в `beta` -- Для `OpenClaw NPM Release` full commit SHA input дозволений лише коли +- Для `OpenClaw NPM Release` full commit SHA input дозволено лише коли `preflight_only=true` -- `OpenClaw Release Checks` і `Full Release Validation` завжди - validation-only -- Real publish path має використовувати той самий `npm_dist_tag`, який використовувався під час preflight; - workflow перевіряє ці metadata перед продовженням publish +- `OpenClaw Release Checks` і `Full Release Validation` завжди лише validation-only +- Справжній publish path має використовувати той самий `npm_dist_tag`, що використовувався під час preflight; workflow перевіряє ці metadata перед продовженням publish ## Послідовність stable npm release -Коли готуєте stable npm release: +Під час створення stable npm release: 1. Запустіть `OpenClaw NPM Release` з `preflight_only=true` - - До появи тегу можна використати поточний повний SHA коміту гілки робочого процесу - для пробного запуску робочого процесу попередньої перевірки лише з валідацією -2. Виберіть `npm_dist_tag=beta` для звичайного потоку, де спочатку йде beta, або `latest` лише - коли ви навмисно хочете прямої стабільної публікації -3. Запустіть `Full Release Validation` на релізній гілці, релізному тегу або повному - SHA коміту, коли потрібні звичайний CI разом із live-кешем промптів, Docker, QA Lab, - Matrix і покриттям Telegram з одного ручного робочого процесу -4. Якщо навмисно потрібен лише детермінований звичайний граф тестів, натомість запустіть - ручний робочий процес `CI` на релізному ref + - До створення тега можна використати поточний повний SHA коміту гілки + workflow для сухого запуску перевірки лише preflight workflow +2. Виберіть `npm_dist_tag=beta` для звичайного потоку спершу beta або `latest` лише + тоді, коли ви навмисно хочете пряме стабільне публікування +3. Запустіть `Full Release Validation` на гілці релізу, тезі релізу або повному + SHA коміту, коли потрібні звичайний CI плюс покриття live prompt cache, Docker, + QA Lab, Matrix і Telegram з одного ручного workflow +4. Якщо вам навмисно потрібен лише детермінований звичайний граф тестів, натомість + запустіть ручний workflow `CI` на ref релізу 5. Збережіть успішний `preflight_run_id` -6. Знову запустіть `OpenClaw NPM Release` з `preflight_only=false`, тим самим +6. Запустіть `OpenClaw NPM Release` ще раз із `preflight_only=false`, тим самим `tag`, тим самим `npm_dist_tag` і збереженим `preflight_run_id` -7. Якщо реліз потрапив у `beta`, використайте приватний - `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` - робочий процес, щоб просунути цю стабільну версію з `beta` до `latest` +7. Якщо реліз потрапив у `beta`, використайте приватний workflow + `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`, + щоб просунути цю стабільну версію з `beta` до `latest` 8. Якщо реліз навмисно опубліковано безпосередньо в `latest`, а `beta` - має негайно слідувати за тією самою стабільною збіркою, використайте той самий приватний - робочий процес, щоб спрямувати обидва dist-теги на стабільну версію, або дозвольте його запланованій + має негайно наслідувати той самий стабільний білд, використайте той самий приватний + workflow, щоб спрямувати обидва dist-tags на стабільну версію, або дозвольте його запланованій самовідновлювальній синхронізації перемістити `beta` пізніше -Зміна dist-тегу живе в приватному репозиторії з міркувань безпеки, тому що для неї досі -потрібен `NPM_TOKEN`, тоді як публічний репозиторій зберігає публікацію лише через OIDC. +Мутація dist-tag розміщена в приватному репозиторії з міркувань безпеки, бо вона все ще +потребує `NPM_TOKEN`, тоді як публічний репозиторій зберігає публікування лише через OIDC. -Це зберігає прямий шлях публікації й шлях просування, де спочатку йде beta, одночасно +Це зберігає як шлях прямого публікування, так і шлях просування спершу через beta задокументованими та видимими для оператора. -Якщо супровіднику доводиться повернутися до локальної автентифікації npm, виконуйте будь-які команди 1Password -CLI (`op`) лише всередині виділеної сесії tmux. Не викликайте `op` -безпосередньо з основної оболонки агента; утримання його всередині tmux робить промпти, -сповіщення й обробку OTP спостережуваними та запобігає повторним сповіщенням хоста. +Якщо мейнтейнер мусить повернутися до локальної автентифікації npm, запускайте будь-які +команди CLI 1Password (`op`) лише всередині окремого сеансу tmux. Не викликайте `op` +безпосередньо з основної оболонки агента; утримання його всередині tmux робить підказки, +сповіщення та обробку OTP спостережуваними й запобігає повторним сповіщенням хоста. ## Публічні посилання @@ -486,10 +479,10 @@ CLI (`op`) лише всередині виділеної сесії tmux. Не - [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh) - [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh) -Супровідники використовують приватну документацію релізів у +Мейнтейнери використовують приватну документацію релізів у [`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md) як фактичний runbook. ## Пов’язане -- [Релізні канали](/uk/install/development-channels) +- [Канали релізів](/uk/install/development-channels)