diff --git a/docs/uk/ci.md b/docs/uk/ci.md index ddf41c5ab..3d37929e0 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,93 +1,94 @@ --- read_when: - - Вам потрібно зрозуміти, чому завдання CI виконалося або не виконалося - - Ви налагоджуєте перевірку GitHub Actions, яка не проходить. - - Ви координуєте запуск або повторний запуск перевірки релізу + - Потрібно зрозуміти, чому завдання CI запустилося або не запустилося + - Ви налагоджуєте перевірку GitHub Actions, що завершується помилкою + - Ви координуєте запуск або повторний запуск валідації релізу - Ви змінюєте диспетчеризацію ClawSweeper або пересилання активності GitHub -summary: Граф завдань CI, гейти областей, релізні парасольки та локальні еквіваленти команд +summary: Граф завдань CI, контрольні шлюзи області дії, релізні парасольки та локальні еквіваленти команд title: CI-конвеєр x-i18n: - generated_at: "2026-05-02T12:52:43Z" + generated_at: "2026-05-02T15:53:14Z" model: gpt-5.5 provider: openai - source_hash: f773c5a8221e3e458373e80b689d66e8cc4243d0df63364a4766701c2f4344a4 + source_hash: 1cf280f1f46d49462656de86001b7f2bef7c63f133dbb8d208a7497c48fa3497 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` навмисно обходять розумне обмеження області й розгортають повний граф для реліз-кандидатів і широкої валідації. Android-напрями залишаються opt-in через `include_android`. Релізне покриття Plugin живе в окремому workflow [`Передреліз Plugin`](#plugin-prerelease) і запускається лише з [`Повної релізної валідації`](#full-release-validation) або явного ручного dispatch. -## Огляд pipeline +## Огляд конвеєра -| Завдання | Призначення | Коли запускається | -| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- | -| `preflight` | Виявляє зміни лише в docs, змінені scopes, змінені розширення та будує CI manifest | Завжди для non-draft pushes і PRs | -| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft pushes і PRs | -| `security-dependency-audit` | Production-аудит lockfile без залежностей за npm advisories | Завжди для non-draft pushes і PRs | -| `security-fast` | Обов’язковий агрегат для швидких security jobs | Завжди для non-draft pushes і PRs | -| `check-dependencies` | Production-прохід Knip лише для залежностей плюс guard allowlist невикористаних файлів | Зміни, релевантні для Node | -| `build-artifacts` | Збірка `dist/`, Control UI, перевірки built artifacts і reusable downstream artifacts | Зміни, релевантні для Node | -| `checks-fast-core` | Швидкі Linux correctness lanes, як-от перевірки bundled/plugin-contract/protocol | Зміни, релевантні для Node | -| `checks-fast-contracts-channels` | Sharded перевірки channel contract зі стабільним aggregate check result | Зміни, релевантні для Node | -| `checks-node-core-test` | Shards тестів Core Node, крім 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 links | Docs змінено | -| `skills-python` | Ruff + pytest для Python-backed skills | Зміни, релевантні для Python skills | -| `checks-windows` | Windows-specific process/path tests плюс спільні регресії runtime import specifier | Зміни, релевантні для Windows | -| `macos-node` | macOS TypeScript test lane з використанням спільних 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 або ручний dispatch | +| Завдання | Призначення | Коли запускається | +| -------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------- | +| `preflight` | Виявляє зміни лише в документації, змінені області, змінені extensions і будує маніфест CI | Завжди для нечернеткових push і PR | +| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для нечернеткових push і PR | +| `security-dependency-audit` | Аудит production lockfile без залежностей щодо npm advisories | Завжди для нечернеткових push і PR | +| `security-fast` | Обов’язковий агрегат для швидких security-завдань | Завжди для нечернеткових push і PR | +| `check-dependencies` | Production-прохід Knip лише для залежностей плюс guard allowlist невикористаних файлів | Зміни, релевантні для Node | +| `build-artifacts` | Збірка `dist/`, Control UI, перевірки зібраних артефактів і повторно використовувані downstream-артефакти | Зміни, релевантні для Node | +| `checks-fast-core` | Швидкі Linux-напрями коректності, як-от bundled/plugin-contract/protocol перевірки | Зміни, релевантні для Node | +| `checks-fast-contracts-channels` | Sharded перевірки контрактів каналів зі стабільним агрегованим результатом перевірки | Зміни, релевантні для 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 | Зміни, релевантні для Node | +| `build-smoke` | Smoke-тести зібраного CLI і smoke startup-memory | Зміни, релевантні для Node | +| `checks` | Верифікатор для тестів каналів зібраних артефактів | Зміни, релевантні для Node | +| `checks-node-compat-node22` | Напрям сумісності Node 22 зі збіркою і smoke | Ручний CI dispatch для релізів | +| `check-docs` | Форматування документації, lint і перевірки битих посилань | Змінено документацію | +| `skills-python` | Ruff + pytest для Skills на базі Python | Зміни, релевантні для Python Skills | +| `checks-windows` | Специфічні для Windows тести процесів/шляхів плюс регресії спільних runtime import specifier | Зміни, релевантні для Windows | +| `macos-node` | Напрям TypeScript-тестів macOS із використанням спільних зібраних артефактів | Зміни, релевантні для macOS | +| `macos-swift` | Swift lint, збірка і тести для застосунку macOS | Зміни, релевантні для macOS | +| `android` | Android unit-тести для обох flavor плюс одна debug APK збірка | Зміни, релевантні для Android | +| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успішний Main CI або ручний dispatch | +| `openclaw-performance` | Щоденні/on-demand звіти продуктивності runtime Kova з mock-provider, deep-profile і GPT 5.4 live напрямами | Запланований і ручний dispatch | ## Порядок fail-fast -1. `preflight` вирішує, які lanes взагалі існують. Логіка `docs-scope` і `changed-scope` є steps всередині цього job, а не standalone 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` швидко падають, не чекаючи важчих завдань матриці артефактів і платформ. +3. `build-artifacts` перетинається зі швидкими Linux-напрямами, щоб downstream-споживачі могли стартувати щойно спільна збірка буде готова. +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 або ref `main`. Вважайте це CI-шумом, якщо найновіший run для того самого ref також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тому вони все ще повідомляють звичайні shard failures, але не стають у чергу після того, як увесь workflow уже superseded. Автоматичний CI concurrency key версійований (`CI-v7-*`), тому GitHub-side zombie у старій queue group не може нескінченно блокувати новіші main runs. Ручні full-suite runs використовують `CI-manual-v1-*` і не скасовують in-progress runs. +GitHub може позначати замінені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Сприймайте це як шум CI, якщо найновіший запуск для того самого ref також не падає. Агреговані перевірки shard використовують `!cancelled() && always()`, тому вони все одно повідомляють звичайні збої shard, але не стають у чергу після того, як увесь workflow уже було замінено. Автоматичний ключ concurrency CI версіонований (`CI-v7-*`), тому zombie на боці GitHub у старій групі черги не може нескінченно блокувати новіші main-запуски. Ручні запуски повного набору використовують `CI-manual-v1-*` і не скасовують запуски, що виконуються. -## Scope і routing +## Область і маршрутизація -Scope logic міститься в `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-тестами в `src/scripts/ci-changed-scope.test.ts`. Manual dispatch пропускає виявлення changed-scope і змушує маніфест preflight поводитися так, ніби змінилася кожна scoped-область. -- **CI workflow edits** валідують Node CI graph плюс workflow linting, але самі по собі не примушують Windows, Android або macOS native builds; ці platform lanes залишаються scoped до змін platform source. -- **CI routing-only edits, selected cheap core-test fixture edits, and narrow plugin contract helper/test-routing edits** використовують швидкий 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; unrelated source, plugin, install-smoke і test-only changes залишаються на Linux Node lanes. +- **Редагування CI workflow** валідують граф Node CI плюс workflow linting, але самі по собі не змушують виконувати Windows, Android або macOS native builds; ці platform-напрями залишаються обмеженими змінами platform source. +- **Редагування лише CI routing, вибрані дешеві редагування core-test fixture і вузькі plugin contract helper/test-routing редагування** використовують швидкий шлях маніфесту лише для Node: `preflight`, security і одне завдання `checks-fast-core`. Цей шлях пропускає build artifacts, сумісність Node 22, channel contracts, повні core shards, bundled-plugin shards і додаткові guard matrices, коли зміна обмежена routing або helper surfaces, які швидке завдання напряму вправляє. +- **Windows Node checks** обмежені специфічними для Windows process/path wrappers, npm/pnpm/UI runner helpers, конфігурацією package manager і поверхнями CI workflow, які виконують цей напрям; непов’язані source, plugin, install-smoke і test-only зміни залишаються на Linux Node напрямах. -Найповільніші сімейства Node tests розділені або збалансовані, щоб кожне job залишалося малим без надмірного резервування runners: channel contracts запускаються як три weighted shards, малі core unit lanes поєднані парами, auto-reply запускається як чотири balanced workers (із reply subtree, розділеним на shards agent-runner, dispatch і commands/state-routing), а 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 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/` уже зібрані. +Найповільніші сімейства Node-тестів розділені або збалансовані так, щоб кожне завдання залишалося малим без надмірного резервування runners: channel contracts запускаються як три weighted shards, малі core unit напрями об’єднані парами, auto-reply запускається як чотири збалансовані workers (з reply subtree, розділеним на agent-runner, dispatch і commands/state-routing shards), а agentic gateway/plugin configs розподілені між наявними source-only agentic Node завданнями замість очікування на built artifacts. Широкі browser, QA, media і miscellaneous plugin тести використовують власні виділені конфіги Vitest замість спільного plugin catch-all. Include-pattern shards записують timing entries із назвою CI shard, тому `.artifacts/vitest-shard-timings.json` може відрізнити цілий config від filtered shard. `check-additional` тримає package-boundary compile/canary роботу разом і відокремлює runtime topology architecture від gateway watch coverage; shard boundary guard запускає свої малі незалежні guards паралельно всередині одного завдання. 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 з SMS/call-log BuildConfig flags, водночас уникаючи дублювання debug APK packaging job для кожного Android-relevant push. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test напрям усе одно компілює flavor з SMS/call-log BuildConfig flags, уникаючи дублювання debug APK packaging job під час кожного Android-релевантного push. -Shard `check-dependencies` запускає `pnpm deadcode:dependencies` (production Knip dependency-only pass, pinned до latest Knip version, з вимкненим pnpm minimum release age для `dlx` install) і `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 лише для залежностей, закріплений на найновішій версії Knip, з вимкненим мінімальним віком релізу pnpm для встановлення `dlx`) і `pnpm deadcode:unused-files`, який порівнює production findings Knip щодо невикористаних файлів із `scripts/deadcode-unused-files.allowlist.mjs`. Guard невикористаних файлів падає, коли PR додає новий непереглянутий невикористаний файл або залишає застарілий запис allowlist, зберігаючи навмисні dynamic plugin, generated, build, live-test і package bridge surfaces, які Knip не може статично розв’язати. -## Пересилання активності ClawSweeper +## Перенаправлення активності ClawSweeper -`.github/workflows/clawsweeper-dispatch.yml` є target-side bridge з активності репозиторію OpenClaw до ClawSweeper. Він не checkout і не виконує untrusted pull request code. Workflow створює GitHub App token з `CLAWSWEEPER_APP_PRIVATE_KEY`, а потім dispatches компактні `repository_dispatch` payloads до `openclaw/clawsweeper`. +`.github/workflows/clawsweeper-dispatch.yml` є bridge на боці target із активності репозиторію OpenClaw до ClawSweeper. Він не checkout і не виконує недовірений код pull request. Workflow створює GitHub App token із `CLAWSWEEPER_APP_PRIVATE_KEY`, потім dispatch компактні payloads `repository_dispatch` до `openclaw/clawsweeper`. -Workflow має чотири lanes: +Workflow має чотири напрями: -- `clawsweeper_item` для точних issue і pull request review requests; -- `clawsweeper_comment` для явних команд ClawSweeper в issue comments; -- `clawsweeper_commit_review` для commit-level review requests на `main` pushes; -- `github_activity` для загальної GitHub activity, яку ClawSweeper agent може inspect. +- `clawsweeper_item` для точних запитів review issue і pull request; +- `clawsweeper_comment` для явних команд ClawSweeper у коментарях issue; +- `clawsweeper_commit_review` для запитів review на рівні commit у push до `main`; +- `github_activity` для загальної активності GitHub, яку агент ClawSweeper може інспектувати. -Lane `github_activity` пересилає лише normalized metadata: event type, action, actor, repository, item number, URL, title, state і short excerpts для comments або reviews, коли вони наявні. Він навмисно уникає пересилання повного webhook body. Receiving workflow в `openclaw/clawsweeper` — це `.github/workflows/github-activity.yml`, який posts normalized event до OpenClaw Gateway hook для ClawSweeper agent. +Напрям `github_activity` пересилає лише нормалізовані метадані: event type, action, actor, repository, item number, URL, title, state і короткі excerpts для comments або reviews, коли вони присутні. Він навмисно уникає пересилання повного webhook body. Приймальний workflow в `openclaw/clawsweeper` — це `.github/workflows/github-activity.yml`, який публікує нормалізовану подію в hook OpenClaw Gateway для агента ClawSweeper. -General activity — це observation, а не delivery-by-default. ClawSweeper agent отримує Discord target у своєму prompt і має post до `#clawsweeper` лише тоді, коли event є surprising, actionable, risky або operationally useful. Routine opens, edits, bot churn, duplicate webhook noise і normal review traffic мають завершуватися `NO_REPLY`. +Загальна активність є спостереженням, а не доставкою за замовчуванням. Агент ClawSweeper отримує Discord target у своєму prompt і має публікувати в `#clawsweeper` лише коли подія є несподіваною, actionable, ризикованою або операційно корисною. Рутинні відкриття, редагування, bot churn, duplicate webhook noise і звичайний review traffic мають завершуватися `NO_REPLY`. -Вважайте GitHub titles, comments, bodies, review text, branch names і commit messages untrusted data на всьому цьому path. Вони є input для summarization і triage, а не instructions для workflow або agent runtime. +Сприймайте titles, comments, bodies, review text, branch names і commit messages GitHub як недовірені дані на всьому цьому шляху. Це вхідні дані для summarization і triage, а не інструкції для workflow або agent runtime. ## Ручні dispatches -Ручні 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. +Ручні запуски CI виконують той самий граф завдань, що й звичайний CI, але примусово вмикають усі scoped-доріжки, окрім Android: шарди Linux Node, шарди bundled-plugin, контракти каналів, сумісність із Node 22, `check`, `check-additional`, build smoke, перевірки документації, Python skills, Windows, macOS та інтернаціоналізацію Control UI. Окремі ручні запуски CI виконують лише Android з `include_android=true`; повна release-парасолька вмикає Android, передаючи `include_android=true`. Статичні перевірки попереднього випуску Plugin, release-only шард `agentic-plugins`, повний batch sweep Plugin та Docker-доріжки попереднього випуску Plugin виключено з CI. Docker-набір попереднього випуску запускається лише тоді, коли `Full Release Validation` запускає окремий workflow `Plugin Prerelease` з увімкненим release-validation gate. -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. +Ручні запуски використовують унікальну concurrency group, тому повний набір для release-candidate не скасовується іншим push або PR-запуском на тому самому ref. Необов’язковий input `target_ref` дає змогу довіреному викликачеві запустити цей граф для branch, tag або повного commit SHA, використовуючи файл workflow з вибраного dispatch ref. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -95,17 +96,17 @@ gh workflow run ci.yml --ref main -f target_ref= -f include_andro gh workflow run full-release-validation.yml --ref main -f ref= ``` -## Виконавці +## Ранери -| Виконавець | Завдання | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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 також використовує Ubuntu, розміщений у GitHub, щоб матриця Blacksmith могла стати в чергу раніше | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, легші сегменти розширень, `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` | +| Ранер | Завдання | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `ubuntu-24.04` | `preflight`, швидкі security jobs і агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі protocol/contract/bundled перевірки, шардовані перевірки контрактів каналів, шарди `check`, окрім lint, шарди й агрегати `check-additional`, верифікатори агрегатів Node-тестів, перевірки документації, Python skills, workflow-sanity, labeler, auto-response; install-smoke preflight також використовує Ubuntu, розміщений у GitHub, щоб матриця 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-тестів, шарди тестів bundled 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`; forks повертаються до `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; forks повертаються до `macos-latest` | ## Локальні еквіваленти @@ -131,21 +132,39 @@ node scripts/ci-run-timings.mjs --latest-main # ignore issue/comment noise and c node scripts/ci-run-timings.mjs --recent 10 # compare recent successful main CI runs pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json +pnpm perf:kova:summary --report .artifacts/kova/reports/mock-provider/report.json --output .artifacts/kova/summary.md ``` -## Повна перевірка релізу +## Продуктивність OpenClaw -`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, Matrix і напрямків Telegram. З `rerun_group=all` і `release_profile=full` він також запускає `NPM Telegram Beta E2E` проти артефакта `release-package-under-test` з перевірок релізу. Після публікації передайте `npm_telegram_package_spec`, щоб повторно запустити той самий напрям пакета Telegram проти опублікованого пакета npm. +`OpenClaw Performance` — це workflow продуктивності продукту/runtime. Він щодня запускається на `main` і може бути запущений вручну: -Див. [Повна перевірка релізу](/uk/reference/full-release-validation) для -матриці етапів, точних назв завдань workflow, відмінностей профілів, артефактів і -дескрипторів сфокусованого повторного запуску. +```bash +gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f repeat=3 +gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 -f deep_profile=true -f live_gpt54=true +``` -`OpenClaw Release Publish` — це ручний мутаційний workflow релізу. Запускайте його -з `release/YYYY.M.D` або `main` після того, як тег релізу існує і після того, як -попередня перевірка OpenClaw npm успішно завершилася. Він перевіряє `pnpm plugins:sync:check`, -запускає `Plugin NPM Release` для всіх придатних до публікації пакетів Plugin, запускає -`Plugin ClawHub Release` для того самого SHA релізу, і лише потім запускає +Workflow встановлює OCM із закріпленого release і Kova із закріпленого input `kova_ref`, а потім запускає три доріжки: + +- `mock-provider`: діагностичні сценарії Kova проти local-build runtime з детермінованою фейковою OpenAI-сумісною автентифікацією. +- `mock-deep-profile`: CPU/heap/trace профілювання для startup, Gateway і hotspots agent-turn. +- `live-gpt54`: реальний agent turn OpenAI `openai/gpt-5.4`, який пропускається, коли `OPENAI_API_KEY` недоступний. + +Кожна доріжка завантажує GitHub artifacts. Коли `CLAWGRIT_REPORTS_TOKEN` налаштовано, workflow також комітить `report.json`, `report.md`, bundles та `index.md` у `openclaw/clawgrit-reports` під `openclaw-performance//-//`. Поточний branch pointer записується як `openclaw-performance//latest-.json`. + +## Повна release-валідація + +`Full Release Validation` — це ручний umbrella workflow для «запустити все перед release». Він приймає branch, tag або повний commit SHA, запускає ручний workflow `CI` із цією ціллю, запускає `Plugin Prerelease` для release-only proof Plugin/package/static/Docker і запускає `OpenClaw Release Checks` для install smoke, package acceptance, Docker release-path suites, live/E2E, OpenWebUI, QA Lab parity, Matrix і Telegram доріжок. З `rerun_group=all` і `release_profile=full` він також запускає `NPM Telegram Beta E2E` проти artifact `release-package-under-test` з release checks. Після публікації передайте `npm_telegram_package_spec`, щоб повторно запустити ту саму доріжку Telegram package проти опублікованого npm package. + +Див. [Повна release-валідація](/uk/reference/full-release-validation) для +матриці етапів, точних назв workflow jobs, відмінностей профілів, artifacts і +focused rerun handles. + +`OpenClaw Release Publish` — це ручний mutating release workflow. Запустіть його +з `release/YYYY.M.D` або `main` після того, як release tag існує, і після того, +як OpenClaw npm preflight успішно завершився. Він перевіряє `pnpm plugins:sync:check`, +запускає `Plugin NPM Release` для всіх publishable Plugin packages, запускає +`Plugin ClawHub Release` для того самого release SHA, і лише потім запускає `OpenClaw NPM Release` зі збереженим `preflight_run_id`. ```bash @@ -156,46 +175,47 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Для доказу прив’язаного коміту на гілці, що швидко змінюється, використовуйте помічник замість +Для pinned commit proof на branch, що швидко змінюється, використовуйте helper замість `gh workflow run ... --ref main -f ref=`: ```bash pnpm ci:full-release --sha ``` -Посилання dispatch для workflow GitHub мають бути гілками або тегами, а не сирими SHA комітів. Помічник надсилає тимчасову гілку `release-ci/-...` на цільовому SHA, -запускає `Full Release Validation` з цього прив’язаного ref, перевіряє, що кожен дочірній -workflow `headSha` збігається з ціллю, і видаляє тимчасову гілку після завершення -запуску. Парасольковий перевірник також завершується помилкою, якщо будь-який дочірній workflow виконувався на +GitHub workflow dispatch refs мають бути branches або tags, а не raw commit SHAs. +Helper пушить тимчасовий branch `release-ci/-...` на цільовому SHA, +запускає `Full Release Validation` із цього pinned ref, перевіряє, що кожен child +workflow `headSha` збігається з ціллю, і видаляє тимчасовий branch після завершення +запуску. Umbrella verifier також падає, якщо будь-який child workflow виконувався на іншому SHA. -`release_profile` керує широтою live/provider, що передається до перевірок релізу. Ручні -workflow релізу типово використовують `stable`; використовуйте `full` лише тоді, коли -навмисно потрібна широка консультативна матриця provider/media. +`release_profile` керує широтою live/provider, що передається в release checks. Ручні +release workflows за замовчуванням використовують `stable`; використовуйте `full` лише тоді, коли ви +навмисно хочете широку advisory provider/media matrix. -- `minimum` залишає найшвидші критичні для релізу напрями OpenAI/core. -- `stable` додає стабільний набір provider/backend. -- `full` запускає широку консультативну матрицю provider/media. +- `minimum` зберігає найшвидші OpenAI/core release-critical доріжки. +- `stable` додає stable provider/backend set. +- `full` запускає широку advisory provider/media matrix. -Парасолька записує id запущених дочірніх запусків, а фінальне завдання `Verify full validation` повторно перевіряє поточні висновки дочірніх запусків і додає таблиці найповільніших завдань для кожного дочірнього запуску. Якщо дочірній workflow перезапущено і він стає зеленим, перезапустіть лише завдання перевірника батьківського workflow, щоб оновити результат парасольки та підсумок часу. +Umbrella записує ids запущених child runs, а фінальне завдання `Verify full validation` повторно перевіряє поточні conclusions child runs і додає таблиці найповільніших jobs для кожного child run. Якщо child workflow повторно запущено і він став green, повторно запустіть лише parent verifier job, щоб оновити результат umbrella і timing summary. -Для відновлення і `Full Release Validation`, і `OpenClaw Release Checks` приймають `rerun_group`. Використовуйте `all` для кандидата в реліз, `ci` лише для звичайного дочірнього повного CI, `plugin-prerelease` лише для дочірнього prerelease Plugin, `release-checks` для кожного дочірнього релізного завдання або вужчу групу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` або `npm-telegram` на парасольці. Це обмежує повторний запуск невдалого релізного блока після сфокусованого виправлення. +Для відновлення і `Full Release Validation`, і `OpenClaw Release Checks` приймають `rerun_group`. Використовуйте `all` для реліз-кандидата, `ci` лише для звичайного дочірнього повного CI, `plugin-prerelease` лише для дочірнього передрелізу Plugin, `release-checks` для кожного дочірнього релізу або вужчу групу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` чи `npm-telegram` на парасольковому workflow. Це тримає повторний запуск невдалого релізного середовища обмеженим після сфокусованого виправлення. -`OpenClaw Release Checks` використовує довірений ref workflow, щоб один раз розв’язати вибраний ref у tarball `release-package-under-test`, а потім передає цей артефакт і до release-path Docker workflow live/E2E, і до сегмента package acceptance. Це зберігає байти пакета узгодженими між релізними блоками й уникає повторного пакування того самого кандидата в кількох дочірніх завданнях. +`OpenClaw Release Checks` використовує довірений ref workflow, щоб один раз розв’язати вибраний ref у tarball `release-package-under-test`, а потім передає цей артефакт і до Docker workflow live/E2E для релізного шляху, і до шарда приймання пакета. Це зберігає байти пакета узгодженими між релізними середовищами та уникає повторного пакування того самого кандидата в кількох дочірніх job. Дублікати запусків `Full Release Validation` для `ref=main` і `rerun_group=all` -витісняють старішу парасольку. Батьківський монітор скасовує будь-який дочірній workflow, який він -уже запустив, коли батьківський workflow скасовано, тому новіша перевірка main -не стоїть за застарілим двогодинним запуском release-check. Перевірка гілки/тега релізу -і сфокусовані групи повторного запуску зберігають `cancel-in-progress: false`. +замінюють старіший парасольковий workflow. Батьківський монітор скасовує будь-який дочірній workflow, який +він уже запустив, коли батьківський workflow скасовано, тож новіша валідація main +не стоїть у черзі за застарілим двогодинним запуском release-check. Валідація релізної гілки/тега +та сфокусовані групи повторного запуску зберігають `cancel-in-progress: false`. -## Сегменти Live та E2E +## Live та E2E шарди -Дочірній release live/E2E зберігає широке нативне покриття `pnpm test:live`, але запускає його як іменовані сегменти через `scripts/test-live-shard.mjs` замість одного послідовного завдання: +Дочірній release live/E2E зберігає широке нативне покриття `pnpm test:live`, але запускає його як іменовані шарди через `scripts/test-live-shard.mjs` замість одного послідовного job: - `native-live-src-agents` - `native-live-src-gateway-core` -- provider-filtered `native-live-src-gateway-profiles` jobs +- відфільтровані за провайдерами job `native-live-src-gateway-profiles` - `native-live-src-gateway-backends` - `native-live-test` - `native-live-extensions-a-k` @@ -203,61 +223,61 @@ workflow релізу типово використовують `stable`; вик - `native-live-extensions-openai` - `native-live-extensions-o-z-other` - `native-live-extensions-xai` -- split media audio/video shards and provider-filtered music shards +- розділені медіашарди audio/video та відфільтровані за провайдерами музичні шарди -Це зберігає те саме покриття файлів і водночас спрощує повторний запуск і діагностику повільних збоїв live provider. Агрегатні назви сегментів `native-live-extensions-o-z`, `native-live-extensions-media` і `native-live-extensions-media-music` залишаються чинними для ручних одноразових повторних запусків. +Це зберігає те саме файлове покриття, водночас спрощуючи повторний запуск і діагностику повільних збоїв live-провайдерів. Агреговані назви шардів `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`; media-завдання лише перевіряють бінарні файли перед налаштуванням. Тримайте live-набори з Docker-підтримкою на звичайних виконавцях Blacksmith — container jobs є неправильним місцем для запуску вкладених Docker-тестів. +Нативні live-медіашарди запускаються в `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, зібраному workflow `Live Media Runner Image`. Цей образ попередньо встановлює `ffmpeg` і `ffprobe`; медіа job лише перевіряють двійкові файли перед налаштуванням. Тримайте live-набори з Docker на звичайних runner Blacksmith — container jobs є неправильним місцем для запуску вкладених Docker-тестів. -Підкріплені Docker шарди live-моделі/бекенду використовують окремий спільний образ `ghcr.io/openclaw/openclaw-live-test:` для кожного вибраного коміту. Процес live-релізу один раз збирає й публікує цей образ, після чого Docker-шарди live-моделі, розшардованого за провайдерами Gateway, CLI-бекенду, ACP-прив’язки та Codex harness запускаються з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Docker-шарди Gateway мають явні обмеження `timeout` на рівні скриптів нижче за таймаут завдання workflow, щоб завислий контейнер або шлях очищення швидко завершувався помилкою, а не споживав увесь бюджет release-check. Якщо ці шарди незалежно перебудовують повну Docker-ціль із вихідного коду, запуск релізу налаштовано неправильно, і він марнуватиме фактичний час на дубльовані збірки образів. +Live-шарди моделей/backend на базі Docker використовують окремий спільний образ `ghcr.io/openclaw/openclaw-live-test:` для кожного вибраного commit. Release live workflow збирає та публікує цей образ один раз, після чого Docker live model, provider-sharded gateway, CLI backend, ACP bind і Codex harness шарди запускаються з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Docker-шарди Gateway мають явні обмеження `timeout` на рівні скриптів нижче за timeout job workflow, щоб завислий контейнер або шлях очищення швидко падав, а не витрачав увесь бюджет release-check. Якщо ці шарди самостійно перебудовують повну source Docker target, релізний запуск налаштований неправильно й марнуватиме час на дубльовані збірки образів. ## Приймання пакета Використовуйте `Package Acceptance`, коли питання звучить так: «чи працює цей інстальований пакет OpenClaw як продукт?» Це відрізняється від звичайного CI: звичайний CI перевіряє дерево вихідного коду, тоді як приймання пакета перевіряє один tarball через той самий Docker E2E harness, який користувачі задіюють після встановлення або оновлення. -### Завдання +### Jobs -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 lanes проти цього пакета замість пакування checkout workflow. Коли профіль вибирає кілька цільових `docker_lanes`, повторно використовуваний workflow готує пакет і спільні образи один раз, а потім розгортає ці lanes як паралельні цільові Docker-завдання з унікальними артефактами. -3. `package_telegram` за бажанням викликає `NPM Telegram Beta E2E`. Він запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, якщо Package Acceptance визначив його; автономний Telegram dispatch усе ще може встановити опубліковану npm-специфікацію. -4. `summary` завершує workflow з помилкою, якщо визначення пакета, Docker-приймання або необов’язкова Telegram lane завершилися невдало. +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 lanes проти цього пакета замість пакування checkout workflow. Коли профіль вибирає кілька цільових `docker_lanes`, багаторазовий workflow готує пакет і спільні образи один раз, а потім розгортає ці lanes як паралельні цільові Docker jobs з унікальними артефактами. +3. `package_telegram` опційно викликає `NPM Telegram Beta E2E`. Він запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, коли Package Acceptance розв’язало його; самостійний Telegram dispatch усе ще може встановити опублікований npm spec. +4. `summary` провалює workflow, якщо розв’язання пакета, Docker-приймання або опційний Telegram lane завершилися невдало. ### Джерела кандидатів -- `source=npm` приймає лише `openclaw@beta`, `openclaw@latest` або точну версію релізу OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для приймання опублікованих beta/stable. -- `source=ref` пакує довірену гілку `package_ref`, тег або повний SHA коміту. Резолвер отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт досяжний з історії гілок репозиторію або з релізного тегу, встановлює залежності у відокремленому 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`. Resolver отримує гілки/теги OpenClaw, перевіряє, що вибраний commit досяжний з історії гілок репозиторію або релізного тега, встановлює залежності у від’єднаному 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/harness, який запускає тест. `package_ref` — це вихідний коміт, який пакується, коли `source=ref`. Це дає поточному тестовому harness змогу перевіряти старі довірені коміти вихідного коду без запуску старої логіки workflow. +Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це довірений код workflow/harness, який запускає тест. `package_ref` — це source commit, який пакується, коли `source=ref`. Це дає змогу поточному test harness перевіряти старіші довірені source commits без запуску старої логіки 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` - `product` — `package` плюс `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui` -- `full` — повні фрагменти release-path Docker з OpenWebUI +- `full` — повні Docker chunks релізного шляху з OpenWebUI - `custom` — точні `docker_lanes`; обов’язково, коли `suite_profile=custom` -Профіль `package` використовує офлайн-покриття plugins, щоб перевірка опублікованого пакета не залежала від доступності live ClawHub. Необов’язкова Telegram lane повторно використовує артефакт `package-under-test` у `NPM Telegram Beta E2E`, а шлях опублікованої npm-специфікації зберігається для автономних dispatch. +Профіль `package` використовує офлайн-покриття Plugin, щоб валідація опублікованого пакета не залежала від live-доступності ClawHub. Опційний Telegram lane повторно використовує артефакт `package-under-test` у `NPM Telegram Beta E2E`, а шлях опублікованого npm spec зберігається для самостійних dispatch. -Політику, спеціально призначену для тестування оновлень і plugins, включно з локальними командами, -Docker lanes, входами Package Acceptance, типовими значеннями релізу та тріажем помилок, -див. у [Тестування оновлень і plugins](/uk/help/testing-updates-plugins). +Щодо спеціальної політики тестування оновлень і Plugin, включно з локальними командами, +Docker lanes, вхідними параметрами Package Acceptance, релізними типовими значеннями та triage збоїв, +див. [Тестування оновлень і Plugin](/uk/help/testing-updates-plugins). -Release checks викликають Package Acceptance з `source=artifact`, підготовленим артефактом релізного пакета, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=release-history`, `published_upgrade_survivor_scenarios=reported-issues` і `telegram_mode=mock-openai`. Це тримає докази міграції пакета, оновлення, очищення застарілих залежностей plugins, офлайн-plugins, plugin-update і Telegram на одному й тому самому визначеному tarball пакета. Cross-OS release checks і далі покривають специфічні для ОС onboarding, інсталятор і поведінку платформи; перевірку продукту для пакета/оновлення слід починати з Package Acceptance. Docker lane `published-upgrade-survivor` перевіряє один baseline опублікованого пакета за запуск. У Package Acceptance визначений tarball `package-under-test` завжди є кандидатом, а `published_upgrade_survivor_baseline` вибирає fallback baseline опублікованого пакета, типово `openclaw@latest`; команди повторного запуску failed-lane зберігають цей baseline. Установіть `published_upgrade_survivor_baselines=release-history`, щоб розширити lane на дедупліковану матрицю історії: останні шість stable-релізів, `2026.4.23` і останній stable-реліз перед `2026-03-15`. Установіть `published_upgrade_survivor_scenarios=reported-issues`, щоб розширити ті самі baselines на issue-подібні fixtures для конфігурації Feishu, збережених файлів bootstrap/persona, шляхів логів із тильдою та застарілих коренів залежностей legacy plugins. Окремий workflow `Update Migration` використовує Docker lane `update-migration` з `all-since-2026.4.23` і `plugin-deps-cleanup`, коли питання полягає у вичерпному очищенні опублікованих оновлень, а не у звичайній широті Full Release CI. Локальні агреговані запуски можуть передавати точні специфікації пакетів через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, тримати одну lane з `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, наприклад `openclaw@2026.4.15`, або встановити `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` для матриці сценаріїв. Опублікована lane налаштовує baseline за допомогою вбудованого рецепта команди `openclaw config set`, записує кроки рецепта в `summary.json` і перевіряє `/healthz`, `/readyz`, а також статус RPC після запуску Gateway. Свіжі lanes для Windows packaged та installer також перевіряють, що встановлений пакет може імпортувати override browser-control з сирого абсолютного шляху Windows. OpenAI cross-OS agent-turn smoke типово використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли його задано, інакше `openai/gpt-5.4`, тож докази встановлення й Gateway залишаються на тестовій моделі GPT-5, уникаючи типових значень GPT-4.x. +Release checks викликають Package Acceptance із `source=artifact`, підготовленим артефактом релізного пакета, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=release-history`, `published_upgrade_survivor_scenarios=reported-issues` і `telegram_mode=mock-openai`. Це тримає перевірку міграції пакета, оновлення, очищення застарілих залежностей Plugin, офлайн Plugin, plugin-update і Telegram на тому самому розв’язаному tarball пакета. Cross-OS release checks все ще покривають специфічні для ОС onboarding, installer і platform behavior; product-валідація пакета/оновлення має починатися з Package Acceptance. Docker lane `published-upgrade-survivor` перевіряє одну опубліковану baseline пакета за запуск. У Package Acceptance розв’язаний tarball `package-under-test` завжди є кандидатом, а `published_upgrade_survivor_baseline` вибирає fallback опубліковану baseline, типово `openclaw@latest`; команди повторного запуску failed-lane зберігають цю baseline. Установіть `published_upgrade_survivor_baselines=release-history`, щоб розгорнути lane на дедупліковану історичну матрицю: останні шість stable-релізів, `2026.4.23` і останній stable-реліз перед `2026-03-15`. Установіть `published_upgrade_survivor_scenarios=reported-issues`, щоб розгорнути ті самі baselines на fixtures у формі issue для конфігурації Feishu, збережених bootstrap/persona files, шляхів журналів із тильдою та застарілих коренів залежностей legacy Plugin. Окремий workflow `Update Migration` використовує Docker lane `update-migration` з `all-since-2026.4.23` і `plugin-deps-cleanup`, коли питання стосується вичерпного очищення опублікованого оновлення, а не звичайної широти Full Release CI. Локальні агреговані запуски можуть передавати точні package specs через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, зберігати один lane з `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, як-от `openclaw@2026.4.15`, або встановлювати `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` для scenario matrix. Опублікований lane налаштовує baseline за допомогою вбудованого рецепта команди `openclaw config set`, записує кроки рецепта в `summary.json` і перевіряє `/healthz`, `/readyz`, а також статус RPC після старту Gateway. Windows packaged і installer fresh lanes також перевіряють, що встановлений пакет може імпортувати browser-control override з raw absolute Windows path. Cross-OS agent-turn smoke OpenAI типово використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли встановлено, інакше `openai/gpt-5.4`, тож перевірка встановлення та Gateway лишається на тестовій моделі GPT-5, уникаючи типових значень GPT-4.x. -### Вікна legacy-сумісності +### Вікна сумісності legacy Package Acceptance має обмежені вікна legacy-сумісності для вже опублікованих пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть використовувати шлях сумісності: -- відомі приватні QA-записи в `dist/postinstall-inventory.json` можуть вказувати на файли, пропущені в tarball; -- `doctor-switch` може пропускати підвипадок persistence для `gateway install --wrapper`, коли пакет не надає цей прапорець; -- `update-channel-switch` може видаляти відсутні `pnpm.patchedDependencies` з отриманого з tarball фіктивного git fixture і може логувати відсутній збережений `update.channel`; -- plugin smokes можуть читати legacy-розташування install-record або приймати відсутність persistence для marketplace install-record; -- `plugin-update` може дозволяти міграцію metadata конфігурації, водночас і далі вимагаючи, щоб install record і поведінка без перевстановлення залишалися незмінними. +- відомі приватні QA entries у `dist/postinstall-inventory.json` можуть вказувати на файли, пропущені в tarball; +- `doctor-switch` може пропускати підвипадок persistence `gateway install --wrapper`, коли пакет не надає цей flag; +- `update-channel-switch` може прибирати відсутні `pnpm.patchedDependencies` із fake git fixture, похідної від tarball, і може логувати відсутній збережений `update.channel`; +- plugin smokes можуть читати legacy locations install-record або приймати відсутню persistence marketplace install-record; +- `plugin-update` може дозволяти міграцію metadata config, але все ще вимагати, щоб install record і поведінка no-reinstall залишалися незмінними. -Опублікований пакет `2026.4.26` також може попереджати про файли stamp metadata локальної збірки, які вже були відвантажені. Пізніші пакети мають відповідати сучасним контрактам; ті самі умови спричиняють помилку, а не попередження чи пропуск. +Опублікований пакет `2026.4.26` також може попереджати про локальні файли stamp метаданих збірки, які вже були shipped. Пізніші пакети мають відповідати сучасним контрактам; ті самі умови завершуються failure замість warning або skip. ### Приклади @@ -300,152 +320,152 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -Під час налагодження невдалого запуску приймання пакета починайте зі зведення `resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перевірте дочірній запуск `docker_acceptance` і його Docker-артефакти: `.artifacts/docker-tests/**/summary.json`, `failures.json`, логи lanes, timings фаз і команди повторного запуску. Надавайте перевагу повторному запуску невдалого профілю пакета або точних Docker lanes, а не повторному запуску повної release validation. +Під час налагодження невдалого запуску приймання пакета починайте зі зведення `resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перевірте дочірній запуск `docker_acceptance` і його артефакти Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, журнали ліній, часові показники фаз і команди повторного запуску. Надавайте перевагу повторному запуску невдалого профілю пакета або точних ліній Docker замість повторного запуску повної валідації релізу. -## Install smoke +## Димова перевірка встановлення -Окремий workflow `Install Smoke` повторно використовує той самий scope-скрипт через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. +Окремий workflow `Install Smoke` повторно використовує той самий скрипт області через власне завдання `preflight`. Він розділяє покриття димової перевірки на `run_fast_install_smoke` і `run_full_install_smoke`. -- **Швидкий шлях** запускається для pull requests, що зачіпають Docker/package surfaces, зміни пакетів/маніфестів bundled plugins або поверхні core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke-завдання. Зміни лише у вихідному коді bundled plugins, правки лише тестів і правки лише документації не резервують Docker workers. Швидкий шлях один раз збирає образ root Dockerfile, перевіряє CLI, запускає CLI smoke для agents delete shared-workspace, запускає container gateway-network e2e, перевіряє build arg bundled extension і запускає обмежений Docker-профіль bundled-plugin під 240-секундним сукупним таймаутом команди (Docker-запуск кожного сценарію обмежено окремо). -- **Повний шлях** зберігає QR package install і Docker/update-покриття інсталятора для нічних запланованих запусків, ручних dispatch, workflow-call release checks і pull requests, які справді зачіпають installer/package/Docker surfaces. У повному режимі install-smoke готує або повторно використовує один target-SHA GHCR root Dockerfile smoke image, а потім запускає QR package install, root Dockerfile/gateway smokes, installer/update smokes і швидкий bundled-plugin Docker E2E як окремі завдання, щоб робота інсталятора не чекала за root image smokes. +- **Швидкий шлях** запускається для pull request, які торкаються поверхонь Docker/пакетів, змін пакета/маніфесту bundled Plugin або поверхонь основного Plugin/каналу/Gateway/Plugin SDK, які перевіряють завдання димової перевірки Docker. Зміни лише у вихідному коді bundled Plugin, зміни лише тестів і зміни лише документації не резервують Docker workers. Швидкий шлях один раз збирає образ кореневого Dockerfile, перевіряє CLI, запускає CLI-димову перевірку agents delete shared-workspace, запускає container gateway-network e2e, перевіряє аргумент збірки bundled розширення та запускає обмежений Docker-профіль bundled-plugin із сукупним тайм-аутом команди 240 секунд (Docker-запуск кожного сценарію обмежується окремо). +- **Повний шлях** зберігає встановлення QR-пакета та Docker/update-покриття інсталятора для нічних запланованих запусків, ручних запусків, workflow-call перевірок релізу та pull request, які справді торкаються поверхонь інсталятора/пакета/Docker. У повному режимі install-smoke готує або повторно використовує один target-SHA GHCR образ димової перевірки кореневого Dockerfile, а потім запускає встановлення QR-пакета, димові перевірки кореневого Dockerfile/Gateway, димові перевірки інсталятора/update і швидкий bundled-plugin Docker E2E як окремі завдання, щоб робота інсталятора не чекала після димових перевірок кореневого образу. -Пуші в `main` (включно з merge commits) не форсують повний шлях; коли логіка changed-scope вимагала б повного покриття на push, workflow зберігає швидкий Docker smoke і залишає повний install smoke для нічної або релізної перевірки. +Пуші в `main` (зокрема merge commits) не примушують повний шлях; коли логіка changed-scope запитала б повне покриття під час push, workflow зберігає швидку димову перевірку Docker і залишає повну димову перевірку встановлення для нічного запуску або валідації релізу. -Повільний Bun global install image-provider smoke окремо керується через `run_bun_global_install_smoke`. Він запускається за нічним розкладом і з release checks workflow, а ручні dispatch `Install Smoke` можуть увімкнути його, але pull requests і пуші в `main` — ні. QR і installer Docker tests зберігають власні Dockerfiles, сфокусовані на встановленні. +Повільна димова перевірка Bun global install image-provider окремо обмежується через `run_bun_global_install_smoke`. Вона запускається за нічним розкладом і з workflow перевірок релізу, а ручні запуски `Install Smoke` можуть увімкнути її, але pull request і пуші в `main` цього не роблять. QR і Docker-тести інсталятора зберігають власні Dockerfile, зосереджені на встановленні. ## Локальний Docker E2E -`pnpm test:docker:all` попередньо збирає один спільний live-test image, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`: +`pnpm test:docker:all` попередньо збирає один спільний live-test образ, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`: -- bare Node/Git runner для lanes інсталятора/оновлення/plugin-dependency; -- функціональний образ, який встановлює той самий tarball у `/app` для звичайних функціональних lanes. +- bare Node/Git runner для ліній installer/update/plugin-dependency; +- функціональний образ, який встановлює той самий tarball у `/app` для звичайних функціональних ліній. -Docker-визначення ліній містяться в `scripts/lib/docker-e2e-scenarios.mjs`, логіка планувальника міститься в `scripts/lib/docker-e2e-plan.mjs`, а runner лише виконує вибраний план. Планувальник вибирає образ для кожної лінії за допомогою `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає лінії з `OPENCLAW_SKIP_DOCKER_BUILD=1`. +Визначення ліній Docker містяться в `scripts/lib/docker-e2e-scenarios.mjs`, логіка планувальника міститься в `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний план. Планувальник вибирає образ для кожної лінії за допомогою `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 | Кількість слотів tail-пулу, чутливого до провайдерів. | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Обмеження кількості одночасних live-ліній, щоб провайдери не throttled. | -| `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/tail-лінії використовують жорсткіші обмеження. | -| `OPENCLAW_DOCKER_ALL_DRY_RUN` | не встановлено | `1` виводить план планувальника без запуску ліній. | -| `OPENCLAW_DOCKER_ALL_LANES` | не встановлено | Список точних ліній, розділених комами; пропускає cleanup smoke, щоб агенти могли відтворити одну невдалу лінію. | +| Змінна | Типове значення | Призначення | +| ------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------- | +| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Кількість слотів main-pool для звичайних ліній. | +| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Кількість слотів tail-pool, чутливих до провайдерів. | +| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Ліміт одночасних live ліній, щоб провайдери не throttled. | +| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Ліміт одночасних ліній npm install. | +| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Ліміт одночасних multi-service ліній. | +| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Затримка між стартами ліній, щоб уникати бур створення Docker daemon; установіть `0`, щоб вимкнути затримку. | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Резервний тайм-аут для кожної лінії (120 хвилин); вибрані live/tail лінії використовують жорсткіші обмеження. | +| `OPENCLAW_DOCKER_ALL_DRY_RUN` | не задано | `1` виводить план планувальника без запуску ліній. | +| `OPENCLAW_DOCKER_ALL_LANES` | не задано | Список точних ліній, розділених комами; пропускає cleanup smoke, щоб агенти могли відтворити одну невдалу лінію. | -Лінія, важча за свій ефективний ліміт, усе ще може стартувати з порожнього пулу, а потім виконується самостійно, доки не звільнить ємність. Локальний aggregate попередньо перевіряє Docker, видаляє застарілі контейнери OpenClaw E2E, виводить статус активних ліній, зберігає тривалості ліній для впорядкування від найдовших до найкоротших і стандартно припиняє планувати нові pooled-лінії після першої помилки. +Лінія, важча за свій ефективний ліміт, усе ще може стартувати з порожнього пулу, а потім працює сама, доки не звільнить capacity. Локальні сукупні preflight перевіряють Docker, видаляють застарілі контейнери OpenClaw E2E, виводять статус активних ліній, зберігають часові показники ліній для впорядкування longest-first і типово припиняють планувати нові pooled лінії після першої невдачі. -### Багаторазовий live/E2E workflow +### Повторно використовуваний live/E2E workflow -Багаторазовий live/E2E workflow запитує `scripts/test-docker-all.mjs --plan-json`, яке покриття пакета, виду образу, live-образу, лінії та облікових даних потрібне. Потім `scripts/docker-e2e.mjs` перетворює цей план на вихідні дані та підсумки GitHub. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує artifact пакета з поточного запуску, або завантажує artifact пакета з `package_artifact_run_id`; перевіряє inventory tarball; збирає та публікує bare/functional GHCR Docker E2E образи з тегами package-digest через кеш Docker-шарів Blacksmith, коли план потребує ліній із установленим пакетом; і повторно використовує надані вхідні дані `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні package-digest образи замість повторної збірки. Завантаження Docker-образів повторюються з обмеженим 180-секундним тайм-аутом на спробу, щоб завислий потік registry/cache швидко повторився, а не споживав більшість критичного шляху CI. +Повторно використовуваний 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; збирає та публікує package-digest-tagged bare/functional GHCR Docker E2E образи через кеш Docker layer Blacksmith, коли плану потрібні лінії з установленим пакетом; і повторно використовує надані input `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні package-digest образи замість повторної збірки. Завантаження Docker image повторюються з обмеженим 180-секундним тайм-аутом на спробу, щоб завислий registry/cache stream швидко повторився замість споживання більшої частини критичного шляху CI. ### Фрагменти release-path -Release Docker-покриття запускає менші chunked-завдання з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен фрагмент завантажував лише потрібний йому тип образу й виконував кілька ліній через той самий зважений планувальник: +Docker-покриття релізу запускає менші chunked завдання з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk завантажував лише потрібний йому тип образу й виконував кілька ліній через той самий зважений планувальник: - `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` залишаються aggregate-псевдонімами plugin/runtime. Псевдонім лінії `install-e2e` залишається aggregate-псевдонімом ручного повторного запуску для обох ліній інсталяторів провайдерів. +Поточні 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 plugin/runtime aliases. Alias лінії `install-e2e` залишається aggregate manual rerun alias для обох provider installer lanes. -OpenWebUI включається до `plugins-runtime-services`, коли цього вимагає повне release-path покриття, і зберігає окремий фрагмент `openwebui` лише для dispatch, призначених тільки для OpenWebUI. Лінії оновлення bundled-channel повторюють спробу один раз у разі тимчасових npm network failures. +OpenWebUI входить до `plugins-runtime-services`, коли повне release-path покриття запитує його, і зберігає окремий chunk `openwebui` лише для OpenWebUI-only dispatches. Лінії оновлення bundled-channel повторюють спробу один раз у разі transient npm network failures. -Кожен фрагмент завантажує `.artifacts/docker-tests/` з журналами ліній, тривалостями, `summary.json`, `failures.json`, тривалостями фаз, JSON плану планувальника, таблицями повільних ліній і командами повторного запуску для кожної лінії. Вхідні дані workflow `docker_lanes` запускають вибрані лінії проти підготовлених образів замість chunk-завдань, що обмежує налагодження невдалих ліній одним targeted Docker-завданням і готує, завантажує або повторно використовує artifact пакета для цього запуску; якщо вибрана лінія є live Docker-лінією, targeted-завдання локально збирає live-test образ для цього повторного запуску. Згенеровані GitHub-команди повторного запуску для кожної лінії містять `package_artifact_run_id`, `package_artifact_name` і prepared image inputs, коли ці значення існують, щоб невдала лінія могла повторно використати точний пакет і образи з невдалого запуску. +Кожен chunk вивантажує `.artifacts/docker-tests/` із журналами ліній, часовими показниками, `summary.json`, `failures.json`, часовими показниками фаз, JSON плану планувальника, таблицями повільних ліній і командами повторного запуску для кожної лінії. Input workflow `docker_lanes` запускає вибрані лінії проти підготовлених образів замість chunk jobs, що обмежує налагодження failed-lane одним цільовим Docker job і готує, завантажує або повторно використовує артефакт пакета для цього запуску; якщо вибрана лінія є live Docker lane, цільове завдання збирає live-test образ локально для цього rerun. Згенеровані GitHub команди повторного запуску для кожної лінії містять `package_artifact_run_id`, `package_artifact_name` і inputs підготовлених образів, коли ці значення існують, щоб невдала лінія могла повторно використати точний пакет і образи з невдалого запуску. ```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 ``` -Scheduled live/E2E workflow щодня запускає повний release-path Docker-набір. +Запланований live/E2E workflow щодня запускає повний release-path Docker suite. ## Plugin Prerelease -`Plugin Prerelease` є дорожчим покриттям продукту/пакета, тому це окремий workflow, який запускається `Full Release Validation` або явним оператором. Звичайні pull request, push у `main` і автономні ручні CI dispatch не вмикають цей набір. Він балансує bundled plugin tests між вісьмома extension workers; ці extension shard jobs запускають до двох груп конфігурації Plugin одночасно з одним Vitest worker на групу та більшим Node heap, щоб import-heavy Plugin batches не створювали додаткових CI-завдань. Release-only Docker prerelease path групує targeted Docker-лінії в малі групи, щоб не резервувати десятки runners для завдань на одну-три хвилини. +`Plugin Prerelease` є дорожчим покриттям продукту/пакета, тому це окремий workflow, який запускається `Full Release Validation` або явним оператором. Звичайні pull request, пуші в `main` і standalone ручні CI dispatches тримають цей suite вимкненим. Він балансує тести bundled Plugin між вісьмома extension workers; ці extension shard jobs запускають до двох plugin config groups одночасно з одним Vitest worker на групу та більшим Node heap, щоб import-heavy plugin batches не створювали додаткові CI jobs. Release-only Docker prerelease path групує цільові 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-лінії як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а Telegram/Discord використовують Convex leases. +- Workflow `Parity gate` запускається за відповідних змін PR і ручного dispatch; він збирає private QA runtime і порівнює mock GPT-5.5 та Opus 4.6 agentic packs. +- Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і під час ручного dispatch; він розгортає mock parity gate, live Matrix lane, а також live Telegram і Discord lanes як паралельні jobs. Live jobs використовують середовище `qa-live-shared`, а Telegram/Discord використовують Convex leases. -Release checks запускають Matrix і Telegram live transport lanes з deterministic mock provider та mock-qualified models (`mock-openai/gpt-5.5` і `mock-openai/gpt-5.5-alt`), щоб контракт каналу був ізольований від затримки live model і звичайного запуску provider-plugin. Live transport gateway вимикає memory search, оскільки QA parity окремо покриває поведінку пам’яті; підключення провайдера покривають окремі live model, native provider і Docker provider suites. +Перевірки релізу запускають Matrix і Telegram live transport lanes із детермінованим mock provider і mock-qualified models (`mock-openai/gpt-5.5` і `mock-openai/gpt-5.5-alt`), щоб channel contract був ізольований від затримки live model і звичайного startup provider-plugin. Live transport gateway вимикає memory search, тому що QA parity окремо покриває поведінку пам’яті; provider connectivity покривається окремими live model, native provider і Docker provider suites. -Matrix використовує `--profile fast` для scheduled і release gates, додаючи `--fail-fast` лише тоді, коли checked-out CLI це підтримує. Стандартне значення CLI і ручний workflow input залишаються `all`; ручний dispatch `matrix_profile=all` завжди розбиває повне Matrix-покриття на завдання `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. +Matrix використовує `--profile fast` для scheduled і release gates, додаючи `--fail-fast` лише тоді, коли checked-out CLI підтримує це. Типове значення CLI і input ручного workflow залишаються `all`; ручний dispatch `matrix_profile=all` завжди розбиває повне Matrix coverage на jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. -`OpenClaw Release Checks` також запускає release-critical QA Lab-лінії перед approval релізу; його QA parity gate запускає candidate і baseline packs як паралельні lane jobs, а потім завантажує обидва artifacts у невелике report job для фінального parity comparison. +`OpenClaw Release Checks` також запускає release-critical QA Lab lanes перед release approval; його QA parity gate запускає candidate і baseline packs як паралельні lane jobs, а потім завантажує обидва artifacts у невеликий report job для фінального parity comparison. -Не ставте PR landing path за `Parity gate`, якщо зміна фактично не торкається QA runtime, model-pack parity або поверхні, якою володіє parity workflow. Для звичайних виправлень channel, config, docs або unit-test розглядайте це як додатковий сигнал і дотримуйтеся scoped CI/check evidence. +Не ставте PR landing path за `Parity gate`, якщо зміна фактично не торкається QA runtime, model-pack parity або поверхні, якою володіє parity workflow. Для звичайних виправлень каналів, конфігурації, документації або unit-test розглядайте це як optional signal і дотримуйтеся scoped CI/check evidence. ## CodeQL -Workflow `CodeQL` навмисно є вузьким сканером безпеки першого проходу, а не повним sweep репозиторію. Щоденні, ручні та non-draft pull request guard runs сканують код Actions workflow плюс JavaScript/TypeScript поверхні з найвищим ризиком за допомогою high-confidence security queries, відфільтрованих до high/critical `security-severity`. +Workflow `CodeQL` навмисно є вузьким first-pass security scanner, а не повним repository sweep. Щоденні, ручні та 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, що й scheduled 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 перевірок. ### Категорії безпеки -| Категорія | Поверхня | -| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | -| `/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 | +| Категорія | Поверхня | +| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `/codeql-security-high/core-auth-secrets` | Auth, secrets, sandbox, cron і базовий рівень gateway | +| `/codeql-security-high/channel-runtime-boundary` | Контракти реалізації основного каналу, а також runtime plugin каналу, gateway, Plugin SDK, secrets, точки дотику аудиту | +| `/codeql-security-high/network-ssrf-boundary` | Поверхні політики SSRF для core SSRF, розбору IP, network guard, web-fetch і Plugin SDK | +| `/codeql-security-high/mcp-process-tool-boundary` | MCP-сервери, помічники виконання процесів, вихідна доставка й шлюзи виконання інструментів агента | +| `/codeql-security-high/plugin-trust-boundary` | Поверхні довіри встановлення Plugin, loader, manifest, registry, package-manager install, source-loading і контракту пакета Plugin SDK | -### Платформоспецифічні security shards +### Shard-и безпеки для окремих платформ -- `CodeQL Android Critical Security` — scheduled 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 results із завантаженого SARIF і завантажує в `/codeql-critical-security/macos`. Тримається поза щоденними стандартними перевірками, оскільки macOS build домінує за часом виконання навіть коли він чистий. +- `CodeQL Android Critical Security` — запланований shard безпеки Android. Збирає Android app вручну для CodeQL на найменшому Blacksmith Linux runner, прийнятому workflow sanity. Завантажує в `/codeql-critical-security/android`. +- `CodeQL macOS Critical Security` — щотижневий/ручний shard безпеки macOS. Збирає macOS app вручну для CodeQL на Blacksmith macOS, відфільтровує результати збірки залежностей із завантаженого SARIF і завантажує в `/codeql-critical-security/macos`. Тримається поза щоденними типовими запуском, бо збірка macOS домінує за часом виконання навіть у чистому стані. ### Категорії Critical Quality -`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. Зміни CodeQL config і quality workflow запускають усі дванадцять PR quality shards. +`CodeQL Critical Quality` — відповідний shard не пов’язаний із безпекою. Він запускає лише error-severity, non-security JavaScript/TypeScript quality-запити для вузьких цінних поверхонь на меншому Blacksmith Linux runner. Його захист pull request навмисно менший за запланований профіль: non-draft PR запускають лише відповідні shard-и `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` для змін у коді виконання команд/моделей/інструментів агента та dispatch відповіді, схемі config/міграції/IO, auth/secrets/sandbox/security, основному каналі та 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 config і quality workflow запускають усі дванадцять PR quality shard-ів. -Manual dispatch приймає: +Ручний 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 ``` -Вузькі профілі є навчальними та ітераційними хуками для запуску одного якісного шарда ізольовано. +Вузькі профілі — це навчальні/ітераційні hooks для запуску одного quality shard ізольовано. -| Категорія | Поверхня | -| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-critical-quality/core-auth-secrets` | 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` | Виконання команд, диспетчеризація model/provider, диспетчеризація автоматичних відповідей і черги, а також runtime-контракти площини керування ACP | -| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-сервери та мости інструментів, допоміжні засоби нагляду за процесами й контракти вихідної доставки | -| `/codeql-critical-quality/memory-runtime-boundary` | SDK хоста памʼяті, runtime-фасади памʼяті, псевдоніми памʼяті Plugin SDK, звʼязувальний код runtime-активації памʼяті та команди doctor для памʼяті | -| `/codeql-critical-quality/session-diagnostics-boundary` | Внутрішня логіка черги відповідей, черги доставки сеансів, допоміжні засоби привʼязування/доставки вихідних сеансів, поверхні діагностичних подій/пакетів логів і CLI-контракти session 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` | Ініціалізація Control UI, локальна персистентність, потоки керування Gateway і runtime-контракти площини керування завданнями | -| `/codeql-critical-quality/web-media-runtime-boundary` | Контракти runtime для основних web fetch/search, media IO, розуміння медіа, генерації зображень і генерації медіа | -| `/codeql-critical-quality/plugin-boundary` | Контракти завантажувача, реєстру, публічної поверхні та точок входу Plugin SDK | -| `/codeql-critical-quality/plugin-sdk-package-contract` | Опублікований package-side вихідний код Plugin SDK і допоміжні засоби контрактів пакетів Plugin | +| Категорія | Поверхня | +| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `/codeql-critical-quality/core-auth-secrets` | Код межі безпеки Auth, secrets, sandbox, cron і gateway | +| `/codeql-critical-quality/config-boundary` | Контракти config schema, migration, normalization і IO | +| `/codeql-critical-quality/gateway-runtime-boundary` | Схеми Gateway protocol і контракти server method | +| `/codeql-critical-quality/channel-runtime-boundary` | Контракти реалізації основного каналу та bundled channel plugin | +| `/codeql-critical-quality/agent-runtime-boundary` | Runtime-контракти command execution, model/provider dispatch, auto-reply dispatch and queues і ACP control-plane | +| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-сервери та tool bridges, помічники process supervision і контракти outbound delivery | +| `/codeql-critical-quality/memory-runtime-boundary` | Memory host SDK, memory runtime facades, memory Plugin SDK aliases, glue активації memory runtime і команди memory doctor | +| `/codeql-critical-quality/session-diagnostics-boundary` | Внутрішня логіка reply queue, session delivery queues, помічники outbound session binding/delivery, поверхні diagnostic event/log bundle і контракти session doctor CLI | +| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Plugin SDK inbound reply dispatch, reply payload/chunking/runtime helpers, channel reply options, delivery queues і session/thread binding helpers | +| `/codeql-critical-quality/provider-runtime-boundary` | Нормалізація model catalog, provider auth and discovery, provider runtime registration, provider defaults/catalogs і registry web/search/fetch/embedding | +| `/codeql-critical-quality/ui-control-plane` | Control UI bootstrap, local persistence, gateway control flows і runtime-контракти task control-plane | +| `/codeql-critical-quality/web-media-runtime-boundary` | Runtime-контракти core web fetch/search, media IO, media understanding, image-generation і media-generation | +| `/codeql-critical-quality/plugin-boundary` | Контракти entrypoint для loader, registry, public-surface і Plugin SDK | +| `/codeql-critical-quality/plugin-sdk-package-contract` | Опублікований package-side вихідний код Plugin SDK і помічники контрактів plugin package | -Якість залишається окремою від безпеки, щоб висновки щодо якості можна було планувати, вимірювати, вимикати або розширювати без затемнення сигналу безпеки. Розширення CodeQL для Swift, Python і вбудованих Plugin слід додавати назад як scoped або sharded подальшу роботу лише після того, як вузькі профілі матимуть стабільний runtime і сигнал. +Quality лишається окремою від security, щоб findings якості можна було планувати, вимірювати, вимикати або розширювати без затемнення сигналу безпеки. Розширення CodeQL для Swift, Python і bundled-plugin слід додавати назад як scoped або sharded follow-up work лише після того, як вузькі профілі матимуть стабільний runtime і signal. -## Робочі процеси обслуговування +## Workflows обслуговування -### Агент документації +### Docs Agent -Робочий процес `Docs Agent` — це подієво-керована лінія обслуговування Codex для підтримання наявної документації у відповідності до нещодавно внесених змін. Він не має чистого розкладу: успішний CI-запуск після push не від бота на `main` може його запустити, а ручний dispatch може запустити його напряму. Виклики від workflow-run пропускаються, коли `main` уже зсунувся вперед або коли протягом останньої години було створено інший непропущений запуск Docs Agent. Під час запуску він переглядає діапазон комітів від попереднього непропущеного source SHA Docs Agent до поточного `main`, тож один погодинний запуск може охопити всі зміни main, накопичені з останнього проходу документації. +Workflow `Docs Agent` — це подієва maintenance lane Codex для підтримання наявної документації у відповідності з нещодавно злитими змінами. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, а manual dispatch може запустити його напряму. Виклики workflow-run пропускаються, коли `main` уже зрушив далі або коли інший non-skipped Docs Agent run було створено протягом останньої години. Коли він запускається, він переглядає діапазон комітів від попереднього non-skipped Docs Agent source SHA до поточного `main`, тож один hourly run може охопити всі зміни main, накопичені з останнього проходу docs. -### Агент продуктивності тестів +### Test Performance Agent -Робочий процес `Test Performance Agent` — це подієво-керована лінія обслуговування Codex для повільних тестів. Він не має чистого розкладу: успішний CI-запуск після push не від бота на `main` може його запустити, але він пропускається, якщо інший виклик workflow-run уже виконувався або виконується в цей UTC-день. Ручний dispatch обходить цей щоденний activity gate. Лінія будує згрупований звіт продуктивності Vitest для повного набору, дозволяє Codex робити лише невеликі виправлення продуктивності тестів зі збереженням покриття замість широких рефакторингів, потім повторно запускає звіт для повного набору й відхиляє зміни, які зменшують базову кількість тестів, що проходять. Якщо baseline має тести, що падають, Codex може виправляти лише очевидні збої, а after-agent звіт повного набору має пройти перед будь-яким комітом. Коли `main` просувається до того, як bot push потрапить у репозиторій, лінія rebases перевірений patch, повторно запускає `pnpm check:changed` і повторює push; конфліктні застарілі patches пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму drop-sudo позицію безпеки, що й агент документації. +Workflow `Test Performance Agent` — це подієва maintenance lane Codex для повільних тестів. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, але він пропускається, якщо інший workflow-run invocation уже запускався або виконується в цей UTC-день. Manual dispatch обходить цей daily activity gate. Lane будує full-suite grouped Vitest performance report, дозволяє Codex вносити лише невеликі performance fixes тестів зі збереженням coverage замість широких refactors, потім повторно запускає full-suite report і відхиляє зміни, які зменшують baseline test count, що проходить. Якщо baseline має failing tests, Codex може виправляти лише очевидні failures, а after-agent full-suite report має пройти, перш ніж щось буде закомічено. Коли `main` просувається до того, як bot push буде злитий, lane rebases validated patch, повторно запускає `pnpm check:changed` і повторює push; конфліктні stale patches пропускаються. Він використовує GitHub-hosted Ubuntu, щоб Codex action могла зберегти таку саму drop-sudo safety posture, як docs agent. -### Дублікати PR після злиття +### Дублікати PR після merge -Робочий процес `Duplicate PRs After Merge` — це ручний робочий процес maintainer для очищення дублікатів після land. За замовчуванням він працює як dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед зміною GitHub він перевіряє, що landed PR злитий і що кожен дублікат має або спільне referenced issue, або перекривні змінені hunks. +Workflow `Duplicate PRs After Merge` — це ручний maintainer workflow для post-land duplicate cleanup. Типово це dry-run, і він закриває лише явно перелічені PR, коли `apply=true`. Перед зміною GitHub він перевіряє, що landed PR merged, і що кожен duplicate має або спільний referenced issue, або overlapping changed hunks. ```bash gh workflow run duplicate-after-merge.yml \ @@ -454,29 +474,29 @@ gh workflow run duplicate-after-merge.yml \ -f apply=true ``` -## Локальні check gates і маршрутизація змін +## Local check gates і changed routing -Локальна логіка changed-lane живе в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний check gate суворіший щодо архітектурних меж, ніж широка сфера платформи CI: +Local changed-lane logic живе в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей local check gate суворіший щодо architecture boundaries, ніж широкий scope платформи CI: -- зміни core production запускають typecheck core prod і core test, а також core lint/guards; -- зміни лише core test запускають тільки typecheck core test і core lint; -- зміни extension production запускають typecheck extension prod і extension test, а також extension lint; -- зміни лише extension test запускають typecheck extension test і extension lint; -- зміни публічного Plugin SDK або plugin-contract розширюються до typecheck extensions, бо extensions залежать від цих core contracts (Vitest extension sweeps лишаються явною тестовою роботою); -- version bumps лише release metadata запускають цільові перевірки version/config/root-dependency; -- невідомі зміни root/config безпечно провалюються до всіх check lanes. +- core production changes запускають core prod і core test typecheck плюс core lint/guards; +- core test-only changes запускають лише core test typecheck плюс core lint; +- extension production changes запускають extension prod і extension test typecheck плюс extension lint; +- extension test-only changes запускають extension test typecheck плюс extension lint; +- public Plugin SDK або plugin-contract changes розширюються до extension typecheck, бо extensions залежать від цих core contracts (Vitest extension sweeps лишаються явною test work); +- release metadata-only version bumps запускають targeted version/config/root-dependency checks; +- unknown root/config changes fail safe до всіх check lanes. -Локальна маршрутизація changed-test живе в `scripts/test-projects.test-support.mjs` і навмисно дешевша за `check:changed`: прямі редагування тестів запускають самі себе, редагування source надають перевагу явним mappings, потім sibling tests і import-graph dependents. Спільна конфігурація delivery для group-room є одним із явних mappings: зміни до group visible-reply config, source reply delivery mode або message-tool system prompt проходять через core reply tests плюс регресії доставки Discord і Slack, щоб зміна спільного стандартного значення падала до першого PR push. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли зміна достатньо широка для harness і дешевий mapped set не є надійним proxy. +Local changed-test routing живе в `scripts/test-projects.test-support.mjs` і навмисно дешевший за `check:changed`: прямі test edits запускають самі себе, source edits віддають перевагу 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. ## Валідація Testbox -Запускайте Testbox з кореня репозиторію та надавайте перевагу свіжій прогрітій box для широкого доказу. Перед витрачанням повільного gate на box, яку повторно використали, строк дії якої минув або яка щойно повідомила про неочікувано велику синхронізацію, спершу запустіть `pnpm testbox:sanity` всередині box. +Запускайте Testbox з кореня repo і віддавайте перевагу свіжому warmed box для широкого proof. Перед витратою повільного gate на box, який повторно використали, термін дії якого минув або який щойно повідомив про несподівано великий sync, спершу запустіть `pnpm testbox:sanity` всередині box. -Sanity check швидко падає, коли потрібні кореневі файли, такі як `pnpm-lock.yaml`, зникли або коли `git status --short` показує щонайменше 200 tracked deletions. Зазвичай це означає, що remote sync state не є надійною копією PR; зупиніть цю box і прогрійте свіжу замість налагодження product test failure. Для навмисних PR із великим видаленням задайте `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього sanity run. +Sanity check швидко падає, коли обов’язкові root files, такі як `pnpm-lock.yaml`, зникли або коли `git status --short` показує щонайменше 200 tracked deletions. Зазвичай це означає, що remote sync state не є надійною копією PR; зупиніть цей box і прогрійте свіжий замість налагодження product test failure. Для навмисних PR із великим видаленням задайте `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього sanity run. -`pnpm testbox:run` також завершує локальний виклик Blacksmith CLI, який залишається у фазі sync понад пʼять хвилин без post-sync output. Задайте `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, щоб вимкнути цей guard, або використайте більше значення в мілісекундах для незвично великих локальних diffs. +`pnpm testbox:run` також завершує локальний виклик Blacksmith CLI, який залишається у фазі синхронізації понад п’ять хвилин без виводу після синхронізації. Установіть `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, щоб вимкнути цей захист, або використайте більше значення в мілісекундах для незвично великих локальних змін. -Crabbox — це repo-owned другий шлях remote-box для доказу на Linux, коли Blacksmith недоступний або коли власна cloud capacity бажаніша. Прогрійте box, hydrate її через project workflow, потім запускайте команди через Crabbox CLI: +Crabbox — це другий, належний репозиторію, шлях віддаленої машини для підтвердження в Linux, коли Blacksmith недоступний або коли бажаніше використовувати власну хмарну ємність. Прогрійте машину, гідруйте її через робочий процес проєкту, а потім запускайте команди через Crabbox CLI: ```bash pnpm crabbox:warmup -- --idle-timeout 90m @@ -485,9 +505,9 @@ pnpm crabbox:run -- --id --shell "OPENCLAW_TESTBOX=1 pnpm check:changed pnpm crabbox:stop -- ``` -`.crabbox.yaml` визначає стандартні параметри provider, sync і GitHub Actions hydration. Він виключає локальний `.git`, щоб hydrated Actions checkout зберігав власні remote Git metadata замість синхронізації maintainer-local remotes і object stores, а також виключає локальні runtime/build artifacts, які ніколи не слід передавати. `.github/workflows/crabbox-hydrate.yml` визначає checkout, налаштування Node/pnpm, fetch `origin/main` і non-secret environment handoff, який пізніші команди `crabbox run --id ` використовують як source. +`.crabbox.yaml` визначає типові параметри провайдера, синхронізації та гідратації GitHub Actions. Він виключає локальний `.git`, щоб гідрований checkout Actions зберігав власні віддалені Git-метадані замість синхронізації локальних для мейнтейнера remote і сховищ об’єктів, а також виключає локальні runtime/build-артефакти, які ніколи не слід передавати. `.github/workflows/crabbox-hydrate.yml` визначає checkout, налаштування Node/pnpm, fetch `origin/main` і передавання несекретного середовища, яке пізніші команди `crabbox run --id ` використовують як джерело. -## Повʼязане +## Пов’язане - [Огляд встановлення](/uk/install) - [Канали розробки](/uk/install/development-channels) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 875519437..1ab3a1da8 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -3,196 +3,200 @@ read_when: - Запуск тестів локально або в CI - Додавання регресійних тестів для помилок моделей/провайдерів - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' +summary: 'Набір для тестування: набори unit/e2e/live-тестів, Docker-ранери та що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-05-02T02:01:58Z" + generated_at: "2026-05-02T15:53:05Z" model: gpt-5.5 provider: openai - source_hash: 9778143e73683fde493e9652f20b8301455b53adbe6c70e997f5af2f54b3fe6b + source_hash: eae3bda71caeb2c2ea8842c940897dc79e4e99be6c337967be41e557b44a41fc source_path: help/testing.md workflow: 16 --- -OpenClaw має три набори тестів Vitest (unit/integration, e2e, live) і невеликий набір +OpenClaw має три набори Vitest (модульні/інтеграційні, e2e, live) і невеликий набір Docker-ранерів. Цей документ є посібником «як ми тестуємо»: -- Що покриває кожен набір тестів (і що він навмисно _не_ покриває). -- Які команди запускати для типових робочих процесів (локально, перед push, налагодження). -- Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. +- Що покриває кожен набір (і що він навмисно _не_ покриває). +- Які команди запускати для типових робочих процесів (локально, перед 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](/uk/channels/qa-channel) — синтетичний транспортний plugin, який використовується сценаріями на основі репозиторію. -Ця сторінка охоплює запуск звичайних наборів тестів і Docker/Parallels-ранерів. Розділ про специфічні для QA ранери нижче ([Специфічні для QA ранери](#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` -- Прямий цикл Vitest watch: `pnpm test:watch` -- Пряме таргетування файлів тепер маршрутизує також шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Коли ітеруєте над одним збоєм, спочатку надавайте перевагу таргетованим запускам. -- Docker-backed сайт QA: `pnpm qa:lab:up` -- Linux VM-backed QA lane: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Повний гейт (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` +- Прямий цикл спостереження Vitest: `pnpm test:watch` +- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Під час ітерації над окремим збоєм спершу віддавайте перевагу цільовим запускам. +- QA-сайт на Docker: `pnpm qa:lab:up` +- QA-lane на Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` Коли змінюєте тести або хочете додаткової впевненості: -- Coverage gate: `pnpm test:coverage` +- Гейт покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` -Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): +Під час налагодження реальних провайдерів/моделей (потрібні справжні облікові дані): -- 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` - - Кожна вибрана модель тепер виконує текстовий turn плюс невелику пробу в стилі читання файлу. - Моделі, метадані яких оголошують вхід `image`, також виконують крихітний image turn. - Вимикайте додаткові проби через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або - `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - - Покриття CI: щоденний `OpenClaw Scheduled Live And E2E Checks` і ручний - `OpenClaw Release Checks` обидва викликають reusable live/E2E workflow з +- Live-набір (моделі + gateway-проби інструментів/зображень): `pnpm test:live` +- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Звіти продуктивності runtime: запустіть `OpenClaw Performance` з + `live_gpt54=true` для реального ходу агента `openai/gpt-5.4` або + `deep_profile=true` для артефактів CPU/heap/trace Kova. Щоденні заплановані запуски + публікують артефакти mock-provider, deep-profile і GPT 5.4 lane до + `openclaw/clawgrit-reports`, коли налаштовано `CLAWGRIT_REPORTS_TOKEN`. +- Live sweep моделей у Docker: `pnpm test:docker:live-models` + - Кожна вибрана модель тепер виконує текстовий хід і невелику пробу в стилі читання файлу. + Моделі, метадані яких оголошують вхід `image`, також виконують крихітний хід із зображенням. + Вимкніть додаткові проби за допомогою `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 з `include_live_suites: true`, що включає окремі Docker live model - matrix jobs, розділені за провайдером. + matrix-завдання, розділені за провайдерами. - Для сфокусованих повторних запусків CI запустіть `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додавайте нові високосигнальні secrets провайдерів до `scripts/ci-hydrate-live-auth.sh` - плюс `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його - scheduled/release callers. + - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh` + разом із `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` та його + scheduled/release-викликачами. - Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind` - Запускає Docker live lane проти шляху Codex app-server, прив’язує синтетичний Slack DM через `/codex bind`, виконує `/codex fast` і - `/codex permissions`, а потім перевіряє, що звичайна відповідь і image attachment - проходять через native plugin binding замість ACP. + `/codex permissions`, потім перевіряє, що звичайна відповідь і вкладення зображення + проходять через нативну прив’язку plugin замість ACP. - Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` - - Запускає turns агента Gateway через plugin-owned Codex app-server harness, - перевіряє `/codex status` і `/codex models` та за замовчуванням виконує image, - cron MCP, sub-agent і Guardian probes. Вимикайте sub-agent probe через - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, коли ізолюєте інші збої Codex - app-server. Для сфокусованої перевірки sub-agent вимкніть інші probes: + - Запускає ходи gateway-агента через harness Codex app-server, що належить plugin, + перевіряє `/codex status` і `/codex models` і за замовчуванням виконує проби image, + cron MCP, sub-agent і Guardian. Вимкніть пробу sub-agent за допомогою + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` під час ізоляції інших збоїв Codex + app-server. Для сфокусованої перевірки sub-agent вимкніть інші проби: `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 probe, якщо не встановлено + Це завершується після проби sub-agent, якщо не встановлено `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0`. - Crestodian rescue command smoke: `pnpm test:live:crestodian-rescue-channel` - - Opt-in перевірка «belt-and-suspenders» для поверхні rescue command каналу повідомлень. + - Додаткова перевірка з підстрахуванням для поверхні команди порятунку message-channel. Вона виконує `/crestodian status`, ставить у чергу постійну зміну моделі, відповідає `/crestodian yes` і перевіряє шлях запису audit/config. - Crestodian planner Docker smoke: `pnpm test:docker:crestodian-planner` - - Запускає Crestodian у контейнері без конфігурації з фейковим Claude CLI у `PATH` - і перевіряє, що fuzzy planner fallback перетворюється на audited typed - config write. + - Запускає Crestodian у контейнері без конфігурації з фальшивим Claude CLI у `PATH` + і перевіряє, що нечіткий fallback планувальника перетворюється на аудитований типізований + запис конфігурації. - Crestodian first-run Docker smoke: `pnpm test:docker:crestodian-first-run` - - Починає з порожнього каталогу стану OpenClaw, маршрутизує bare `openclaw` до - Crestodian, застосовує setup/model/agent/Discord plugin + SecretRef writes, - валідує конфігурацію та перевіряє audit entries. Той самий шлях налаштування Ring 0 + - Починає з порожнього каталогу стану OpenClaw, маршрутизує простий `openclaw` до + Crestodian, застосовує записи setup/model/agent/Discord plugin + SecretRef, + перевіряє конфігурацію і перевіряє записи audit. Той самий шлях налаштування Ring 0 також покрито в QA Lab через `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`. -- Moonshot/Kimi cost smoke: з установленим `MOONSHOT_API_KEY` запустіть +- Moonshot/Kimi cost smoke: із встановленим `MOONSHOT_API_KEY` запустіть `openclaw models list --provider moonshot --json`, потім запустіть ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` проти `moonshot/kimi-k2.6`. Перевірте, що JSON повідомляє Moonshot/K2.6, а - транскрипт асистента зберігає нормалізований `usage.cost`. + transcript асистента зберігає нормалізований `usage.cost`. -Коли потрібен лише один збійний випадок, надавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. +Коли потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через allowlist env vars, описані нижче. ## Специфічні для QA ранери -Ці команди розташовані поруч з основними наборами тестів, коли потрібна реалістичність QA-lab: +Ці команди розташовані поруч з основними тестовими наборами, коли потрібен реалізм QA-lab: -CI запускає QA Lab у виділених workflows. `Parity gate` запускається на відповідних PR -і з ручного dispatch з mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +CI запускає QA Lab у виділених workflow. `Parity gate` запускається на відповідних PR і +з ручного dispatch із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на `main` і з ручного dispatch з mock parity gate, live Matrix lane, -Convex-managed live Telegram lane і Convex-managed live Discord lane як -паралельні jobs. Заплановані QA та release checks явно передають Matrix `--profile fast`, -тоді як Matrix CLI і стандартне значення manual workflow input лишаються -`all`; manual dispatch може розбити `all` на jobs `transport`, `media`, `e2ee-smoke`, +керованою Convex live Telegram lane і керованою Convex live Discord lane як +паралельними завданнями. Заплановані QA і release checks явно передають Matrix `--profile fast`, +тоді як Matrix CLI і ручний workflow input за замовчуванням залишаються +`all`; ручний dispatch може розділити `all` на завдання `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` запускає parity плюс -fast Matrix і Telegram lanes перед release approval, використовуючи -`mock-openai/gpt-5.5` для release transport checks, щоб вони лишалися детермінованими -та уникали звичайного запуску provider-plugin. Ці live transport gateways вимикають -memory search; поведінка пам’яті лишається покритою QA parity suites. +швидкі Matrix і Telegram lanes перед затвердженням релізу, використовуючи +`mock-openai/gpt-5.5` для release transport checks, щоб вони залишалися детермінованими +й уникали звичайного запуску provider-plugin. Ці live transport gateways вимикають +пошук пам’яті; поведінка пам’яті залишається покритою QA parity suites. -Full release live media shards використовують +Повні 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` замість перебудови +`ffmpeg` і `ffprobe`. Docker live model/backend shards використовують спільний +образ `ghcr.io/openclaw/openclaw-live-test:`, зібраний один раз для вибраного +commit, потім завантажують його з `OPENCLAW_SKIP_DOCKER_BUILD=1` замість повторного збирання всередині кожного shard. - `pnpm openclaw qa suite` - - Запускає сценарії QA з репозиторію безпосередньо на host. + - Запускає сценарії QA з репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - gateway workers. `qa-channel` за замовчуванням має concurrency 4 (обмежену - кількістю вибраних сценаріїв). Використовуйте `--concurrency ` для налаштування - кількості workers або `--concurrency 1` для старішої serial lane. - - Завершується з ненульовим кодом, коли будь-який сценарій зазнає збою. Використовуйте `--allow-failures`, коли - хочете отримати artifacts без failing exit code. - - Підтримує provider modes `live-frontier`, `mock-openai` і `aimock`. - `aimock` запускає локальний AIMock-backed provider server для експериментального - покриття fixtures і protocol-mock без заміни scenario-aware - `mock-openai` lane. + працівниками gateway. `qa-channel` за замовчуванням має concurrency 4 (обмежено + кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати + кількість працівників, або `--concurrency 1` для старішої послідовної lane. + - Завершується з ненульовим кодом, коли будь-який сценарій не вдається. Використовуйте `--allow-failures`, коли + потрібні артефакти без коду виходу з помилкою. + - Підтримує режими провайдера `live-frontier`, `mock-openai` і `aimock`. + `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального + покриття fixture і protocol-mock без заміни lane `mock-openai`, що враховує сценарії. - `pnpm test:gateway:cpu-scenarios` - - Запускає gateway startup bench плюс невеликий пакет mock QA Lab scenarios + - Запускає bench запуску Gateway плюс невеликий пакет mock-сценаріїв QA Lab (`channel-chat-baseline`, `memory-failure-fallback`, - `gateway-restart-inflight-run`) і записує об’єднаний 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 ще не - має свіжого runtime output. + `gateway-restart-inflight-run`) і записує зведений підсумок спостережень CPU + у `.artifacts/gateway-cpu-scenarios/`. + - За замовчуванням позначає лише сталі спостереження високого CPU (`--cpu-core-warn` + плюс `--hot-wall-warn-ms`), тому короткі сплески під час запуску записуються як метрики + і не виглядають як регресія з тривалим навантаженням gateway протягом хвилин. + - Використовує зібрані артефакти `dist`; спершу запустіть build, якщо checkout ще не + має свіжого runtime-виводу. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий набір QA всередині disposable Multipass Linux VM. - - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на host. - - Повторно використовує ті самі прапорці вибору provider/model, що й `qa suite`. - - Live-запуски передають підтримувані QA auth inputs, практичні для guest: - env-based provider keys, шлях QA live provider config і `CODEX_HOME`, - коли він присутній. - - Output dirs мають лишатися під коренем репозиторію, щоб guest міг записувати назад через - mounted workspace. - - Записує звичайний QA report + summary плюс Multipass logs у + - Запускає той самий набір QA у disposable Linux VM Multipass. + - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. + - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. + - Live-запуски передають підтримувані вхідні дані автентифікації QA, практичні для guest: + ключі провайдера з env, шлях до QA live provider config і `CODEX_HOME`, + якщо він наявний. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через + змонтований workspace. + - Записує звичайний звіт QA + підсумок, а також журнали Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає Docker-backed QA site для operator-style QA work. + - Запускає Docker-backed QA site для operator-style QA-роботи. - `pnpm test:docker:npm-onboard-channel-agent` - - Збирає npm tarball з поточного checkout, глобально встановлює його в - Docker, запускає non-interactive OpenAI API-key onboarding, за замовчуванням налаштовує Telegram, + - Збирає npm tarball з поточного checkout, встановлює його глобально в + Docker, запускає неінтерактивний onboarding з ключем OpenAI API, за замовчуванням налаштовує Telegram, перевіряє, що packaged plugin runtime завантажується без startup - dependency repair, запускає doctor і виконує один local agent turn проти + dependency repair, запускає doctor і виконує один локальний agent turn проти mocked OpenAI endpoint. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму packaged-install - lane з Discord. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму lane packaged-install + з Discord. - `pnpm test:docker:session-runtime-context` - - Запускає deterministic built-app Docker smoke для embedded runtime context - transcripts. Він перевіряє, що hidden OpenClaw runtime context зберігається як + - Запускає deterministic built-app Docker smoke для transcript вбудованого runtime context. + Він перевіряє, що прихований runtime context OpenClaw зберігається як non-display custom message замість витоку у видимий user turn, - потім засіває affected broken session JSONL і перевіряє, що - `openclaw doctor --fix` переписує його на active branch із backup. + потім додає affected broken session JSONL і перевіряє, що + `openclaw doctor --fix` переписує його на активну гілку з backup. - `pnpm test:docker:npm-telegram-live` - Встановлює package candidate OpenClaw у Docker, запускає installed-package onboarding, налаштовує Telegram через встановлений CLI, потім повторно використовує - live Telegram QA lane з цим installed package як SUT Gateway. + live Telegram QA lane з цим встановленим пакетом як SUT Gateway. - За замовчуванням використовує `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; встановіть `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` або - `OPENCLAW_CURRENT_PACKAGE_TGZ`, щоб тестувати resolved local tarball замість + `OPENCLAW_CURRENT_PACKAGE_TGZ`, щоб протестувати resolved local tarball замість встановлення з registry. - Використовує ті самі Telegram env credentials або Convex credential source, що й - `pnpm openclaw qa telegram`. Для автоматизації CI/release встановіть + `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` перевизначає спільну + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільний `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цієї lane. - GitHub Actions надає цю lane як ручний maintainer workflow `NPM Telegram Beta E2E`. Він не запускається під час merge. Workflow використовує @@ -200,11 +204,11 @@ commit, а потім завантажують його з `OPENCLAW_SKIP_DOCKER - 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 з profiles lane smoke, package, product, full або custom. + нормалізований `openclaw-current.tgz` як `package-under-test`, потім запускає + наявний Docker E2E scheduler з профілями lane smoke, package, product, full або custom. Встановіть `telegram_mode=mock-openai` або `live-frontier`, щоб запустити - Telegram QA workflow проти того самого artifact `package-under-test`. - - Latest beta product proof: + Telegram QA workflow проти того самого артефакта `package-under-test`. + - Останній beta product proof: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -214,7 +218,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- Доказ точного tarball URL потребує digest: +- Exact tarball URL proof потребує digest: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -224,7 +228,7 @@ gh workflow run package-acceptance.yml --ref main \ -f suite_profile=package ``` -- Підтвердження артефактом завантажує tarball-артефакт з іншого запуску Actions: +- Artifact proof завантажує tarball artifact з іншого Actions run: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -236,105 +240,104 @@ gh workflow run package-acceptance.yml --ref main \ - `pnpm test:docker:plugins` - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає вбудовані канали/плагіни через - зміни конфігурації. - - Перевіряє, що виявлення налаштування не показує неналаштовані завантажувані плагіни, - перше налаштоване виправлення doctor явно встановлює кожен відсутній завантажуваний - плагін, а другий перезапуск не запускає приховане виправлення - залежностей. - - Також встановлює відому старішу базову версію npm, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що doctor кандидата - після оновлення очищає залишки залежностей застарілих плагінів без - виправлення postinstall з боку тестового стенда. + з налаштованим OpenAI, потім вмикає bundled channel/plugins через редагування config. + - Перевіряє, що setup discovery залишає неналаштовані downloadable plugins відсутніми, + перший налаштований doctor repair явно встановлює кожен відсутній downloadable + plugin, а другий restart не запускає прихований dependency + repair. + - Також встановлює відомий старіший npm baseline, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що post-update doctor candidate + очищає legacy plugin dependency debris без + harness-side postinstall repair. - `pnpm test:parallels:npm-update` - - Запускає smoke-тест оновлення нативного пакетного встановлення на гостьових системах Parallels. Кожна - вибрана платформа спочатку встановлює запитаний базовий пакет, потім запускає - встановлену команду `openclaw update` у тій самій гостьовій системі й перевіряє - встановлену версію, статус оновлення, готовність gateway і один локальний - хід агента. + - Запускає native packaged-install update smoke на guests Parallels. Кожна + вибрана платформа спершу встановлює requested baseline package, потім запускає + встановлену команду `openclaw update` у тому самому guest і перевіряє + встановлену версію, статус update, gateway readiness і один локальний agent + turn. - Використовуйте `--platform macos`, `--platform windows` або `--platform linux` під час - ітерацій на одній гостьовій системі. Використовуйте `--json` для шляху до артефакту зведення та - статусу по кожній смузі. - - Смуга OpenAI типово використовує `openai/gpt-5.5` для live-підтвердження ходу агента. + ітерацій на одному guest. Використовуйте `--json` для шляху summary artifact і + статусу кожної lane. + - OpenAI lane за замовчуванням використовує `openai/gpt-5.5` для live agent-turn proof. Передайте `--model ` або встановіть `OPENCLAW_PARALLELS_OPENAI_MODEL`, коли навмисно перевіряєте іншу модель OpenAI. - - Обгорніть довгі локальні запуски в тайм-аут хоста, щоб зависання транспорту Parallels не могли - використати решту вікна тестування: + - Обгорніть довгі локальні запуски host timeout, щоб stalls транспорту Parallels не + забрали решту тестового вікна: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - Скрипт записує вкладені журнали смуг у `/tmp/openclaw-parallels-npm-update.*`. - Перевірте `windows-update.log`, `macos-update.log` або `linux-update.log`, - перш ніж припускати, що зовнішня обгортка зависла. - - Оновлення Windows може витрачати 10-15 хвилин на post-update doctor і роботу з - оновленням пакетів на холодній гостьовій системі; це все ще нормальний стан, коли вкладений npm - debug-журнал просувається. - - Не запускайте цю агреговану обгортку паралельно з окремими smoke-смугами Parallels - macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати під час - відновлення snapshot, обслуговування пакетів або стану gateway гостьової системи. - - Підтвердження після оновлення запускає звичайну поверхню вбудованих плагінів, оскільки - фасади можливостей, як-от мовлення, генерація зображень і розуміння медіа, - завантажуються через вбудовані runtime API, навіть коли сам хід агента - перевіряє лише просту текстову відповідь. + - Скрипт записує вкладені журнали lane у `/tmp/openclaw-parallels-npm-update.*`. + Перевірте `windows-update.log`, `macos-update.log` або `linux-update.log` + перед тим, як припускати, що зовнішній wrapper завис. + - Windows update може витратити 10-15 хвилин на post-update doctor і package + update work на cold guest; це все ще справний стан, якщо вкладений npm + debug log просувається. + - Не запускайте цей aggregate wrapper паралельно з окремими Parallels + macOS, Windows або Linux smoke lanes. Вони спільно використовують VM state і можуть конфліктувати під час + snapshot restore, package serving або guest gateway state. + - Post-update proof запускає звичайну bundled plugin surface, тому що + capability facades, як-от speech, image generation і media + understanding, завантажуються через bundled runtime APIs, навіть коли сам agent + turn перевіряє лише просту текстову відповідь. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування - протоколу. + - Запускає лише локальний сервер AIMock provider для прямого protocol smoke + testing. - `pnpm openclaw qa matrix` - - Запускає live-смугу QA Matrix проти одноразового Docker-backed homeserver Tuwunel. Тільки source-checkout — пакетні встановлення не постачають `qa-lab`. - - Повний CLI, каталог профілів/сценаріїв, env vars і структура артефактів: [Matrix QA](/uk/concepts/qa-matrix). + - Запускає Matrix live QA lane проти disposable Docker-backed Tuwunel homeserver. Лише source-checkout — packaged installs не постачають `qa-lab`. + - Повний CLI, каталог profile/scenario, env vars і layout артефактів: [Matrix QA](/uk/concepts/qa-matrix). - `pnpm openclaw qa telegram` - - Запускає live-смугу QA Telegram проти справжньої приватної групи, використовуючи токени бота-драйвера та SUT-бота з env. - - Потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим chat id Telegram. - - Підтримує `--credential-source convex` для спільних пулованих облікових даних. Типово використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути пуловані lease. - - Завершується з ненульовим кодом, коли будь-який сценарій завершується невдало. Використовуйте `--allow-failures`, коли + - Запускає Telegram live QA lane проти реальної приватної групи, використовуючи токени driver і SUT bot з env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. group id має бути числовим Telegram chat id. + - Підтримує `--credential-source convex` для спільних pooled credentials. За замовчуванням використовуйте env mode або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. + - Завершується з ненульовим кодом, коли будь-який сценарій не вдається. Використовуйте `--allow-failures`, коли вам потрібні артефакти без коду виходу з помилкою. - - Потребує двох різних ботів в одній приватній групі, причому SUT-бот має надавати Telegram username. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode в `@BotFather` для обох ботів і переконайтеся, що бот-драйвер може спостерігати трафік ботів групи. - - Записує звіт Telegram QA, зведення та артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту надсилання драйвера до спостереженої відповіді SUT. + - Потребує двох різних bot в одній приватній групі, причому SUT bot має надавати Telegram username. + - Для стабільного bot-to-bot observation увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох bot і переконайтеся, що driver bot може спостерігати group bot traffic. + - Записує Telegram QA report, summary і observed-messages artifact у `.artifacts/qa-e2e/...`. Replying scenarios включають RTT від driver send request до observed SUT reply. -Live-смуги транспорту спільно використовують один стандартний контракт, щоб нові транспорти не розходилися; матриця покриття по смугах розміщена в [Огляд QA → Покриття live-транспорту](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` — це широкий синтетичний набір і він не є частиною цієї матриці. +Live transport lanes мають один standard contract, щоб нові transports не розходилися; per-lane coverage matrix розміщена в [QA overview → Live transport coverage](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` є широким synthetic suite і не входить до цієї matrix. -### Спільні облікові дані Telegram через Convex (v1) +### Спільні Telegram credentials через Convex (v1) Коли `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) увімкнено для -`openclaw qa telegram`, QA lab отримує ексклюзивний lease з пулу на базі Convex, надсилає Heartbeat -для цього lease, поки смуга працює, і звільняє lease під час завершення. +`openclaw qa telegram`, QA lab отримує exclusive lease з Convex-backed pool, heartbeats +цей lease, поки lane працює, і звільняє lease під час shutdown. -Еталонний каркас проєкту Convex: +Reference Convex project scaffold: - `qa/convex-credential-broker/` Обов’язкові env vars: - `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) -- Один секрет для вибраної ролі: +- Один secret для вибраної role: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` -- Вибір ролі облікових даних: +- Вибір credential role: - CLI: `--credential-role maintainer|ci` - - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) + - Env default: `OPENCLAW_QA_CREDENTIAL_ROLE` (за замовчуванням `ci` у CI, інакше `maintainer`) Необов’язкові env vars: -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) -- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (типово `90000`) -- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) -- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (за замовчуванням `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (за замовчуванням `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (за замовчуванням `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (за замовчуванням `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (за замовчуванням `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL-адреси Convex лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` Convex URLs для local-only development. -`OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://` у звичайній роботі. +`OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://` у нормальній роботі. -Адміністративні команди maintainer (pool add/remove/list) потребують -саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. +Maintainer admin commands (pool add/remove/list) вимагають саме +`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-помічники для maintainers: +CLI helpers для maintainers: ```bash pnpm openclaw qa credentials doctor @@ -343,12 +346,12 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, секрети брокера, -префікс endpoint, HTTP timeout і доступність admin/list без виведення -секретних значень. Використовуйте `--json` для machine-readable виводу в скриптах і CI -утилітах. +Використовуйте `doctor` перед live runs, щоб перевірити Convex site URL, broker secrets, +endpoint prefix, HTTP timeout і admin/list reachability без виведення +secret values. Використовуйте `--json` для machine-readable output у scripts і CI +utilities. -Типовий контракт endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Контракт типового кінцевого пункту (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -360,460 +363,462 @@ pnpm openclaw qa credentials remove --credential-id - `POST /release` - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Успіх: `{ status: "ok" }` (або порожній `2xx`) -- `POST /admin/add` (лише секрет maintainer) +- `POST /admin/add` (лише секрет супровідника) - Запит: `{ kind, actorId, payload, note?, status? }` - Успіх: `{ status: "ok", credential }` -- `POST /admin/remove` (лише секрет maintainer) +- `POST /admin/remove` (лише секрет супровідника) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активного lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (лише секрет maintainer) + - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` +- `POST /admin/list` (лише секрет супровідника) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` -Форма payload для типу Telegram: +Форма корисного навантаження для типу Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком числового chat id Telegram. -- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє malformed payloads. +- `groupId` має бути рядком із числовим ідентифікатором чату Telegram. +- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні корисні навантаження. ### Додавання каналу до QA -Архітектура й назви scenario-helper для нових адаптерів каналів описані в [Огляд QA → Додавання каналу](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна планка: реалізувати transport runner на спільному host seam `qa-lab`, оголосити `qaRunners` у маніфесті плагіна, змонтувати як `openclaw qa ` і створити сценарії в `qa/scenarios/`. +Архітектура й назви допоміжних сценарних компонентів для нових адаптерів каналів наведені в [огляді QA → Додавання каналу](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна планка: реалізувати transport runner на спільному хостовому шві `qa-lab`, оголосити `qaRunners` у маніфесті plugin, змонтувати як `openclaw qa ` і створити сценарії в `qa/scenarios/`. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалістичності» (і зростання нестабільності/вартості): +Сприймайте ці набори як «зростання реалістичності» (і зростання нестабільності/вартості): -### Unit / integration (типово) +### Модульні / інтеграційні (типово) - Команда: `pnpm test` -- Конфігурація: нецільові запуски використовують shard-набір `vitest.full-*.config.ts` і можуть розгортати multi-project shards у per-project configs для паралельного планування -- Файли: core/unit inventories у `src/**/*.test.ts`, `packages/**/*.test.ts` і `test/**/*.test.ts`; UI unit tests запускаються у виділеному shard `unit-ui` -- Область: - - Чисті unit tests - - In-process integration tests (gateway auth, routing, tooling, parsing, config) +- Конфігурація: нецільові запуски використовують набір шардiв `vitest.full-*.config.ts` і можуть розгортати багатопроєктні шарди в поконфігураційні проєкти для паралельного планування +- Файли: інвентарі core/модульних тестів у `src/**/*.test.ts`, `packages/**/*.test.ts` і `test/**/*.test.ts`; модульні тести UI запускаються у виділеному шарді `unit-ui` +- Обсяг: + - Чисті модульні тести + - Внутрішньопроцесні інтеграційні тести (автентифікація Gateway, маршрутизація, інструменти, парсинг, конфігурація) - Детерміновані регресії для відомих помилок - Очікування: - Запускається в CI - - Не потребує справжніх ключів + - Реальні ключі не потрібні - Має бути швидким і стабільним - - Тести resolver і public-surface loader мають доводити широку fallback-поведінку `api.js` і - `runtime-api.js` із generated tiny plugin fixtures, а не - реальними source APIs вбудованих плагінів. Реальні завантаження API плагінів належать до - contract/integration suites, якими володіють плагіни. + - Тести резолвера й завантажувача публічної поверхні мають доводити резервну поведінку широких `api.js` і + `runtime-api.js` на згенерованих мініатюрних фікстурах plugin, а не + на реальних API джерел вбудованих plugin. Завантаження реального API plugin належать до + контрактних/інтеграційних наборів, якими володіють plugin. - + - - Ненацілений `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`, бо цикл спостереження з багатьма шардами непрактичний. - - `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, розширення, тести розширень, застосунки, документацію, метадані релізу, live Docker tooling і tooling, а потім запускає відповідні команди перевірки типів, lint і guard. Він не запускає тести Vitest; викликайте `pnpm test:changed` або явний `pnpm test ` для доказу тестами. Підвищення версій лише в метаданих релізу запускає цільові перевірки версії/конфігурації/кореневих залежностей, із запобіжником, що відхиляє зміни пакунка поза верхньорівневим полем версії. - - Зміни в live Docker ACP harness запускають сфокусовані перевірки: синтаксис shell для live Docker auth-скриптів і dry-run live Docker scheduler. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; зміни залежностей, export, версії та іншої поверхні пакунка все ще використовують ширші guard-перевірки. - - Легкі щодо імпортів unit-тести з agents, commands, plugins, auto-reply helpers, `plugin-sdk` і подібних зон чистих утиліт спрямовуються через смугу `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; файли зі станом або важкі щодо runtime залишаються на наявних смугах. - - Вибрані helper-файли джерел `plugin-sdk` і `commands` також зіставляють запуски changed-mode з явними сусідніми тестами в цих легких смугах, тож зміни helper уникають повторного запуску всього важкого набору для цього каталогу. - - `auto-reply` має окремі кошики для верхньорівневих core helpers, верхньорівневих інтеграційних тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково розділяє піддерево reply на шарди agent-runner, dispatch і commands/state-routing, щоб один важкий щодо імпортів кошик не володів усім хвостом Node. - - Звичайний CI для PR/main навмисно пропускає пакетний sweep розширень і релізний shard `agentic-plugins`. Повна Release Validation запускає окремий дочірній workflow `Plugin Prerelease` для цих важких щодо Plugin/розширень наборів на реліз-кандидатах. + - Нецільовий `pnpm test` запускає дванадцять менших конфігурацій шардiв (`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`, бо цикл спостереження з багатьма шардами непрактичний. + - `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, extensions, тести extension, застосунки, документацію, release metadata, live Docker tooling і tooling, а потім запускає відповідні команди перевірки типів, lint і guard. Він не запускає тести Vitest; для тестового доказу викликайте `pnpm test:changed` або явний `pnpm test `. Підняття версій лише в release metadata запускає цільові перевірки версії/конфігурації/кореневих залежностей із guard, який відхиляє зміни package поза полем версії верхнього рівня. + - Зміни live Docker ACP harness запускають сфокусовані перевірки: синтаксис shell для live Docker auth scripts і dry-run live Docker scheduler. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; зміни залежностей, export, версії та іншої поверхні package все одно використовують ширші guards. + - Легкі за імпортами модульні тести з agents, commands, plugins, helpers auto-reply, `plugin-sdk` та подібних чистих утилітарних зон маршрутизуються через смугу `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; файли зі станом або важкою runtime-логікою лишаються на наявних смугах. + - Вибрані допоміжні джерельні файли `plugin-sdk` і `commands` також зіставляють запуски changed-mode з явними сусідніми тестами в цих легких смугах, тому зміни helpers не перезапускають повний важкий набір для цього каталогу. + - `auto-reply` має окремі кошики для верхньорівневих helpers core, верхньорівневих інтеграційних тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково розділяє піддерево reply на шарди agent-runner, dispatch і commands/state-routing, щоб один важкий за імпортами кошик не володів усім хвостом Node. + - Звичайний CI для PR/main навмисно пропускає пакетний sweep extension і release-only шард `agentic-plugins`. Full Release Validation запускає окремий дочірній workflow `Plugin Prerelease` для цих важких за plugin/extension наборів на кандидатах релізу. - + - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст compaction, + - Коли змінюєте входи виявлення message-tool або runtime-контекст compaction, зберігайте обидва рівні покриття. - - Додавайте сфокусовані регресійні helper-тести для меж чистої маршрутизації та нормалізації. - - Підтримуйте здоровими інтеграційні набори вбудованого runner: + - Додайте сфокусовані регресії helpers для чистих меж маршрутизації та нормалізації. + - Підтримуйте здоровими інтеграційні набори 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 + - Ці набори перевіряють, що scoped ids і поведінка compaction і далі проходять + реальними шляхами `run.ts` / `compact.ts`; тести лише helpers не є достатньою заміною для цих інтеграційних шляхів. - + - Базова конфігурація Vitest типово використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує неізольований runner у кореневих проєктах, e2e та live-конфігураціях. - - Коренева UI-смуга зберігає своє налаштування `jsdom` і optimizer, але також працює на - спільному неізольованому runner. - - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` + - Коренева смуга UI зберігає своє налаштування `jsdom` і optimizer, але також + працює на спільному неізольованому runner. + - Кожен шард `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх процесів Vitest у Node, - щоб зменшити churn компіляції V8 під час великих локальних запусків. + - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх процесів Node + Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - + - `pnpm changed:lanes` показує, які архітектурні смуги запускає diff. - - Pre-commit hook виконує лише форматування. Він повторно додає відформатовані файли до stage і + - Pre-commit hook виконує лише форматування. Він повторно stage-ить відформатовані файли й не запускає lint, перевірку типів або тести. - - Запускайте `pnpm check:changed` явно перед передаванням роботи або push, коли вам + - Запускайте `pnpm check:changed` явно перед handoff або push, коли вам потрібен розумний локальний контрольний шлюз. - - `pnpm test:changed` типово спрямовується через дешеві обмежені смуги. Використовуйте - `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли agent - вирішує, що зміна harness, конфігурації, пакунка або контракту справді потребує ширшого + - `pnpm test:changed` типово маршрутизується через дешеві обмежені смуги. Використовуйте + `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли агент + вирішує, що зміна harness, конфігурації, package або contract справді потребує ширшого покриття Vitest. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - лише з вищою межею worker. - - Автомасштабування локальних worker навмисно консервативне і зменшує навантаження, - коли середнє навантаження хоста вже високе, тож кілька одночасних - запусків Vitest типово завдають меншої шкоди. - - Базова конфігурація Vitest позначає проєкти/конфігураційні файли як - `forceRerunTriggers`, щоб повторні запуски changed-mode залишалися коректними, коли змінюється - wiring тестів. + лише з вищим лімітом workers. + - Локальне автоматичне масштабування workers навмисно консервативне й відступає, + коли середнє навантаження host уже високе, тому кілька одночасних + запусків Vitest типово завдають менше шкоди. + - Базова конфігурація Vitest позначає projects/config files як + `forceRerunTriggers`, щоб повторні запуски changed-mode лишалися коректними, коли змінюється + test wiring. - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних - хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + hosts; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одне явне розташування кешу для прямого профілювання. - + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпортів плюс вивід import-breakdown. - `pnpm test:perf:imports:changed` обмежує той самий профілювальний перегляд - файлами, зміненими від `origin/main`. - - Дані часу shard записуються в `.artifacts/vitest-shard-timings.json`. - Запуски всієї конфігурації використовують шлях конфігурації як ключ; include-pattern CI - shards додають назву shard, щоб відфільтровані shards можна було відстежувати + файлами, зміненими з `origin/main`. + - Дані часу шардiв записуються в `.artifacts/vitest-shard-timings.json`. + Запуски всієї конфігурації використовують шлях конфігурації як ключ; CI-шарди + include-pattern додають назву шарда, щоб відфільтровані шарди можна було відстежувати окремо. - Коли один гарячий тест усе ще витрачає більшість часу на стартові імпорти, - тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і - mock-айте цей seam напряму замість deep-import runtime helpers лише - щоб передати їх через `vi.mock(...)`. + тримайте важкі залежності за вузьким локальним швом `*.runtime.ts` і + мокайте цей шов напряму замість deep-import runtime helpers лише + для передавання їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` із нативним шляхом кореневого проєкту для цього закоміченого - diff і виводить wall time плюс максимальне RSS на macOS. + `test:changed` з нативним шляхом кореневого проєкту для цього закоміченого + diff і друкує wall time плюс максимальний RSS macOS. - `pnpm test:perf:changed:bench -- --worktree` бенчмаркить поточне - брудне дерево, маршрутизуючи список змінених файлів через + dirty tree, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує CPU-профіль головного потоку для - витрат запуску й transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap профілі runner для - unit-набору з вимкненим файловим паралелізмом. + - `pnpm test:perf:profile:main` записує CPU-профіль main-thread для + startup Vitest/Vite і transform overhead. + - `pnpm test:perf:profile:runner` записує CPU+heap profiles runner для + unit suite з вимкненим паралелізмом файлів. -### Стабільність (gateway) +### Стабільність (Gateway) - Команда: `pnpm test:stability:gateway` - Конфігурація: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - - Запускає реальний loopback Gateway із типово ввімкненою діагностикою - - Проганяє синтетичний gateway message, memory і large-payload churn через шлях діагностичних подій + - Запускає реальний loopback Gateway з діагностикою, увімкненою типово + - Проганяє synthetic gateway message, memory і large-payload churn через шлях diagnostic event - Запитує `diagnostics.stability` через Gateway WS RPC - - Покриває helper-и збереження diagnostic stability bundle - - Перевіряє, що recorder лишається обмеженим, синтетичні RSS-зразки залишаються в межах бюджету тиску, а глибини черг на сесію повертаються до нуля + - Покриває helpers збереження diagnostic stability bundle + - Перевіряє, що recorder лишається bounded, synthetic RSS samples лишаються в межах pressure budget, а per-session queue depths повертаються до нуля - Очікування: - - Безпечно для CI і без ключів - - Вузька смуга для подальшої роботи над регресіями стабільності, не заміна повного набору Gateway + - Безпечно для CI й без ключів + - Вузька смуга для подальших stability-regression робіт, не заміна повного набору Gateway ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести bundled-plugin у `extensions/` -- Типові runtime-параметри: - - Використовує `threads` Vitest з `isolate: false`, як і решта репозиторію. - - Використовує адаптивних worker (CI: до 2, локально: типово 1). - - Типово працює в тихому режимі, щоб зменшити витрати console I/O. -- Корисні overrides: - - `OPENCLAW_E2E_WORKERS=` для примусового задання кількості worker (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` для повторного ввімкнення докладного виводу консолі. +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести вбудованих plugin у `extensions/` +- Типові значення runtime: + - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. + - Використовує адаптивних workers (CI: до 2, локально: типово 1). + - Типово запускається в silent mode, щоб зменшити overhead console I/O. +- Корисні перевизначення: + - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість workers (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути verbose console output. - Обсяг: - - Наскрізна поведінка Gateway з кількома інстансами - - Поверхні WebSocket/HTTP, pairing node і важчі мережеві частини + - End-to-end поведінка багатьох екземплярів gateway + - Поверхні WebSocket/HTTP, pairing node і важча мережева взаємодія - Очікування: - - Запускається в CI (коли ввімкнено в pipeline) + - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж в unit-тестах (може бути повільніше) + - Більше рухомих частин, ніж у модульних тестах (може бути повільніше) ### E2E: smoke бекенду OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - - Запускає ізольований OpenShell gateway на хості через Docker - - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє бекенд OpenClaw OpenShell через реальні `sandbox ssh-config` + SSH exec + - Запускає ізольований OpenShell Gateway на хості через Docker + - Створює пісочницю з тимчасового локального Dockerfile + - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і робочого Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox -- Корисні overrides: - - `OPENCLAW_E2E_OPENSHELL=1` для ввімкнення тесту під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` для вказання нестандартного CLI binary або wrapper script + - Лише за явного ввімкнення; не входить до стандартного запуску `pnpm test:e2e` + - Потребує локального CLI `openshell` і робочого демона Docker + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий Gateway і пісочницю +- Корисні перевизначення: + - `OPENCLAW_E2E_OPENSHELL=1` для ввімкнення тесту під час ручного запуску ширшого набору e2e + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` для вказання нестандартного CLI-бінарника або wrapper-скрипта -### Live (реальні провайдери + реальні моделі) +### Живі (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести bundled-plugin у `extensions/` -- Типово: **увімкнено** через `pnpm test:live` (установлює `OPENCLAW_LIVE_TEST=1`) +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і живі тести bundled-plugin у `extensions/` +- Стандартно: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - “Чи цей provider/model справді працює _сьогодні_ з реальними credentials?” - - Виявляє зміни форматів provider, особливості tool-calling, проблеми auth і поведінку rate limit + - “Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?” + - Виявляє зміни формату провайдерів, особливості tool-calling, проблеми автентифікації та поведінку rate limit - Очікування: - - За задумом не є стабільним для CI (реальні мережі, реальні політики provider, квоти, збої) + - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - Коштує грошей / використовує rate limits - - Надавайте перевагу запуску звужених підмножин замість “усього” -- Live-запуски source-ять `~/.profile`, щоб підхопити відсутні API keys. -- Типово live-запуски все ще ізолюють `HOME` і копіюють config/auth material у тимчасовий тестовий home, щоб unit fixtures не могли змінити ваш реальний `~/.openclaw`. -- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно потрібно, щоб live-тести використовували ваш реальний home directory. -- `pnpm test:live` тепер типово працює тихіше: він зберігає progress output `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає gateway bootstrap logs/Bonjour chatter. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні startup logs. -- Ротація API key (залежно від provider): установіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або override для окремого live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу на відповідях rate limit. -- Вивід progress/heartbeat: - - Live-набори тепер виводять progress lines у stderr, щоб довгі виклики provider були видимо активними навіть коли Vitest console capture тихий. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб progress lines provider/gateway передавалися одразу під час live-запусків. - - Налаштовуйте heartbeat direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Краще запускати звужені піднабори, а не “все” +- Живі запуски підвантажують `~/.profile`, щоб отримати відсутні API-ключі. +- Стандартно живі запуски все одно ізолюють `HOME` і копіюють конфігураційні/автентифікаційні матеріали в тимчасовий тестовий home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб живі тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер стандартно працює в тихішому режимі: зберігає виведення прогресу `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає логи bootstrap Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. +- Ротація API-ключів (залежить від провайдера): встановіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або override для окремого live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях rate limit. +- Виведення прогресу/heartbeat: + - Живі набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдерів були помітно активними навіть тоді, коли захоплення консолі Vitest тихе. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/Gateway транслювалися одразу під час живих запусків. + - Налаштовуйте heartbeat-и direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте heartbeat-и Gateway/проб через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. -## Який набір запускати? +## Який набір слід запускати? Використовуйте цю таблицю рішень: -- Редагування логіки/тестів: запустіть `pnpm test` (і `pnpm test:coverage`, якщо ви змінили багато) -- Зміни в мережевій частині gateway / протоколі WS / pairing: додайте `pnpm test:e2e` -- Налагодження “мій бот не працює” / збоїв, специфічних для провайдера / виклику інструментів: запустіть звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Торкаєтеся мережевої взаємодії Gateway / WS-протоколу / pairing: додайте `pnpm test:e2e` +- Налагоджуєте “мій бот не працює” / збої, специфічні для провайдера / tool calling: запускайте звужений `pnpm test:live` -## Живі (мережеві) тести +## Живі (з мережевим доступом) тести -Про живу матрицю моделей, smoke-перевірки бекенда CLI, smoke-перевірки ACP, harness сервера застосунку Codex і всі живі тести медіапровайдерів (Deepgram, BytePlus, ComfyUI, зображення, музика, відео, медіа-harness) — а також обробку облікових даних для живих запусків — див. -[Тестування живих наборів](/uk/help/testing-live). Про спеціальний контрольний список перевірки оновлень і -Plugin див. +Для live model matrix, CLI backend smokes, ACP smokes, harness Codex app-server +і всіх живих тестів media-provider (Deepgram, BytePlus, ComfyUI, image, +music, video, media harness) — а також обробки облікових даних для живих запусків — див. +[Тестування живих наборів](/uk/help/testing-live). Для спеціального checklist оновлень і +перевірки Plugin див. [Тестування оновлень і plugins](/uk/help/testing-updates-plugins). -## Docker runner-и (необов’язкові перевірки "працює в Linux") +## Docker runners (необов’язкові перевірки "працює в Linux") -Ці Docker runner-и поділяються на дві групи: +Ці Docker runners поділяються на дві групи: -- Runner-и живих моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний живий файл 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 runner-и типово використовують менше обмеження для smoke-перевірок, щоб повний Docker-прогін залишався практичним: - `test:docker:live-models` типово має `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` типово має `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Live-model runners: `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`), монтують ваш локальний каталог конфігурації та workspace (і підвантажують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live runners стандартно мають меншу 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` один раз збирає живий 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. Functional-образ встановлює той самий tarball у `/app` для напрямів функціональності зібраного застосунку. Визначення Docker-напрямів містяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка планувальника міститься в `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегатор використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а обмеження ресурсів не дають важким живим, 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/image та облікових даних. -- `Package Acceptance` — це GitHub-native package-gate для питання "чи працює цей installable tarball як продукт?" Він визначає один кандидатний package із `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає багаторазові Docker E2E напрями проти саме цього tarball замість повторного пакування вибраного ref. Профілі впорядковано за широтою: `smoke`, `package`, `product` і `full`. Див. [Тестування оновлень і plugins](/uk/help/testing-updates-plugins) про контракт package/update/plugin, матрицю published-upgrade survivor, типові параметри релізу й triage збоїв. -- Перевірки збірки та релізу запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Guard проходить статичний зібраний граф від `dist/entry.js` і `dist/cli/run-main.js` та завершується помилкою, якщо startup до dispatch імпортує залежності package, як-от Commander, prompt UI, undici або logging до dispatch команди; він також утримує bundled Gateway run chunk у межах бюджету й відхиляє статичні імпорти відомих холодних Gateway шляхів. Packaged CLI smoke також покриває root help, onboard help, doctor help, status, config schema і команду model-list. -- Зворотна сумісність Package Acceptance обмежена `2026.4.25` (включно з `2026.4.25-beta.*`). До цієї межі harness допускає лише прогалини метаданих shipped-package: пропущені приватні QA inventory entries, відсутній `gateway install --wrapper`, відсутні patch-файли у tarball-derived git fixture, відсутній збережений `update.channel`, legacy розташування plugin install-record, відсутнє збереження marketplace install-record і міграцію метаданих конфігурації під час `plugins update`. Для package після `2026.4.25` ці шляхи є строгими помилками. -- Runner-и container smoke: `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`. Перевизначайте ці змінні середовища, коли + вам явно потрібне більше вичерпне сканування. +- `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 для lanes встановлення/оновлення/plugin-dependency; ці lanes монтують попередньо зібраний tarball. Functional-образ встановлює той самий tarball у `/app` для lanes функціональності зібраного застосунку. Визначення Docker lanes містяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка planner міститься в `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегатор використовує зважений локальний scheduler: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а resource caps не дають важким live, npm-install і multi-service lanes стартувати всім одночасно. Якщо один lane важчий за активні caps, scheduler усе одно може запустити його, коли pool порожній, і потім тримає його єдиним запущеним, доки знову не з’явиться місткість. Стандартні значення: 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 секунд, зберігає timings успішних lanes у `.artifacts/docker-tests/lane-timings.json` і використовує ці timings, щоб у наступних запусках спершу стартували довші lanes. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати зважений lane manifest без збірки або запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб надрукувати CI-план для вибраних lanes, потреб пакетів/образів і облікових даних. +- `Package Acceptance` — це GitHub-native package gate для "чи працює цей installable tarball як продукт?" Він визначає один кандидатний пакет із `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає reusable Docker E2E lanes проти саме цього tarball замість повторного пакування вибраного ref. Профілі впорядковано за широтою: `smoke`, `package`, `product` і `full`. Див. [Тестування оновлень і plugins](/uk/help/testing-updates-plugins) щодо контракту package/update/plugin, survivor matrix для published-upgrade, стандартних значень релізу та triage збоїв. +- Перевірки збірки та релізу запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Guard проходить статичний built graph від `dist/entry.js` і `dist/cli/run-main.js` і падає, якщо pre-dispatch startup імпортує залежності пакета, як-от 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 compatibility для Package Acceptance обмежена `2026.4.25` (включно з `2026.4.25-beta.*`). До цього cutoff harness терпить лише прогалини metadata shipped-package: пропущені записи private QA inventory, відсутній `gateway install --wrapper`, відсутні patch-файли у tarball-derived git fixture, відсутній persisted `update.channel`, legacy розташування plugin install-record, відсутня persistence marketplace install-record і міграція config metadata під час `plugins update`. Для пакетів після `2026.4.25` ці paths є strict failures. +- 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` завантажують один або більше реальних контейнерів і перевіряють higher-level integration paths. -Docker runner-и живих моделей також bind-mount-ять лише потрібні домівки автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у домівку контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни auth-сховища хоста: +Live-model Docker runners також bind-mount лише потрібні CLI auth homes (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб external-CLI OAuth міг оновлювати токени без зміни host auth store: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Smoke-перевірка прив’язки ACP: `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: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Smoke-перевірка harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + dev-агент: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Smoke-перевірка спостережуваності: `pnpm qa:otel:smoke` — це приватна QA-ланка для checkout вихідного коду. Вона навмисно не входить до ланок Docker-релізу пакета, бо npm tarball не містить QA Lab. -- Live smoke Open WebUI: `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` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding з env-ref і типово Telegram, запускає doctor і виконує один мокований хід агента OpenAI. Повторно використайте попередньо зібраний tarball через `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемкніть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Smoke-перевірка перемикання каналу оновлень: `pnpm test:docker:update-channel-switch` глобально встановлює запакований tarball OpenClaw у Docker, перемикається з пакетного `stable` на git `dev`, перевіряє збережений канал і роботу Plugin після оновлення, потім перемикається назад на пакетний `stable` і перевіряє статус оновлення. -- Smoke-перевірка збереження після upgrade: `pnpm test:docker:upgrade-survivor` встановлює запакований tarball OpenClaw поверх забрудненої фікстури старого користувача з агентами, конфігурацією каналів, allowlist-ами Plugin, застарілим станом залежностей Plugin і наявними файлами workspace/session. Вона запускає оновлення пакета та неінтерактивний doctor без live-ключів provider або channel, потім запускає loopback Gateway і перевіряє збереження config/state, а також бюджети startup/status. -- Smoke-перевірка збереження після опублікованого upgrade: `pnpm test:docker:published-upgrade-survivor` типово встановлює `openclaw@latest`, засіває реалістичні файли наявного користувача, налаштовує цей baseline вбудованим рецептом команд, перевіряє отриману конфігурацію, оновлює це опубліковане встановлення до candidate tarball, запускає неінтерактивний doctor, записує `.artifacts/upgrade-survivor/summary.json`, потім запускає loopback Gateway і перевіряє налаштовані intents, збереження стану, запуск, `/healthz`, `/readyz` і бюджети RPC-статусу. Перевизначте один 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-перевірка runtime context сесії: `pnpm test:docker:session-runtime-context` перевіряє збереження прихованого transcript runtime context і 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`, пропустіть build на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` із зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Smoke-перевірка Docker installer: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm cache для своїх root-, update- і direct-npm-контейнерів. Smoke-перевірка update типово використовує npm `latest` як stable baseline перед upgrade до candidate tarball. Перевизначте через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` локально або через input `update_baseline_version` workflow Install Smoke на GitHub. Перевірки installer без root зберігають ізольований npm cache, щоб root-owned cache entries не маскували user-local install behavior. Установіть `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`) типово збирає образ root Dockerfile, засіває двох агентів з одним 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 (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Smoke-перевірка Browser CDP snapshot: `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 охоплюють URL посилань, clickables, promoted курсором, iframe refs і frame metadata. -- Регресія мінімального reasoning для OpenAI Responses web_search: `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. -- MCP-міст каналів (засіяний Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- MCP tools Pi bundle (реальний stdio MCP server + smoke-перевірка allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення MCP для Cron/subagent (реальний Gateway + teardown дочірнього stdio MCP після ізольованих cron і one-shot subagent запусків): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke-перевірка install/update для локального шляху, `file:`, npm registry з hoisted dependencies, git moving refs, ClawHub kitchen-sink, 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` тест використовує hermetic локальний fixture server ClawHub. -- Smoke-перевірка незміненого оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke-перевірка metadata reload config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Plugins: `pnpm test:docker:plugins` охоплює smoke-перевірку install/update для локального шляху, `file:`, npm registry з hoisted dependencies, git moving refs, фікстур ClawHub, marketplace updates і enable/inspect Claude-bundle. `pnpm test:docker:plugin-update` охоплює поведінку unchanged update для встановлених plugins. +- 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`) +- 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 + агент розробки: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) +- Observability smoke: `pnpm qa:otel:smoke` — це приватна QA-смуга перевірки вихідного checkout. Її навмисно не включено до Docker-смуг релізу пакета, тому що npm tarball не містить QA Lab. +- Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Майстер онбордингу (TTY, повне створення каркаса): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Npm tarball onboarding/channel/agent smoke: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг із посиланням на env і Telegram за замовчуванням, запускає doctor і виконує один змокований хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball за допомогою `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте перебудову на host через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемикайте канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Update channel switch smoke: `pnpm test:docker:update-channel-switch` глобально встановлює запакований tarball OpenClaw у Docker, перемикається з package `stable` на git `dev`, перевіряє збережений канал і роботу Plugin після оновлення, потім перемикається назад на package `stable` і перевіряє статус оновлення. +- Upgrade survivor smoke: `pnpm test:docker:upgrade-survivor` встановлює запакований tarball OpenClaw поверх брудної фікстури старого користувача з агентами, конфігурацією каналу, allowlist Plugin, застарілим станом залежностей Plugin і наявними файлами workspace/session. Він запускає оновлення пакета плюс неінтерактивний doctor без live-ключів провайдера чи каналу, потім запускає loopback Gateway і перевіряє збереження config/state, а також бюджети startup/status. +- Published upgrade survivor smoke: `pnpm test:docker:published-upgrade-survivor` за замовчуванням встановлює `openclaw@latest`, засіває реалістичні файли наявного користувача, налаштовує цей базовий стан за допомогою вбудованого рецепта команд, перевіряє отриману конфігурацію, оновлює це опубліковане встановлення до кандидатного tarball, запускає неінтерактивний doctor, записує `.artifacts/upgrade-survivor/summary.json`, потім запускає loopback Gateway і перевіряє налаштовані intents, збереження стану, startup, `/healthz`, `/readyz` і бюджети RPC-статусу. Перевизначте один baseline через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, попросіть агрегований планувальник розгорнути точні 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`. +- Session runtime context smoke: `pnpm test:docker:session-runtime-context` перевіряє збереження прихованого runtime context transcript, а також repair doctor для зачеплених дубльованих гілок 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 перед оновленням до кандидатного tarball. Перевизначте локально через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` або через input `update_baseline_version` workflow Install Smoke на GitHub. Перевірки інсталятора без root зберігають ізольований npm cache, щоб записи cache, власником яких є root, не маскували поведінку встановлення user-local. Задайте `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати cache root/update/direct-npm між локальними повторними запусками. +- 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`) за замовчуванням збирає image кореневого Dockerfile, засіває двох агентів з одним 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 layer, запускає 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`, потім примусово викликає provider schema reject і перевіряє, що raw detail з’являється в Gateway logs. +- MCP channel bridge (засіяний Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Pi bundle MCP tools (реальний stdio MCP server + embedded 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 + stdio MCP child teardown після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (install/update smoke для local path, `file:`, npm registry з hoisted dependencies, git moving refs, ClawHub kitchen-sink, 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` тест використовує герметичний локальний 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/update smoke для local path, `file:`, npm registry з hoisted dependencies, git moving refs, фікстур ClawHub, marketplace updates і Claude-bundle enable/inspect. `pnpm test:docker:plugin-update` охоплює поведінку unchanged update для встановлених plugins. -Щоб вручну попередньо зібрати та повторно використати спільний функціональний образ: +Щоб вручну попередньо зібрати й повторно використовувати спільний 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 ``` -Suite-specific перевизначення образів, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе одно мають пріоритет, якщо задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` указує на віддалений спільний образ, скрипти підтягують його, якщо він ще не локальний. QR- і installer Docker tests зберігають власні Dockerfiles, бо вони перевіряють поведінку package/install, а не спільний runtime зібраної app. +Перевизначення image для конкретного suite, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе одно мають пріоритет, коли задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений shared image, скрипти завантажують його, якщо він ще не є локальним. QR і installer Docker tests зберігають власні Dockerfiles, тому що вони перевіряють поведінку package/install, а не спільний runtime зібраного застосунку. -Docker runners для live-model також bind-mount-ять поточний checkout read-only і -переносять його в тимчасовий workdir усередині контейнера. Це зберігає runtime -image компактним, але все одно запускає Vitest проти вашого точного локального source/config. -Етап staging пропускає великі локальні-only caches і outputs build застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні для app `.build` або -директорії output Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання +Docker runners для live-model також bind-mount поточний checkout у режимі read-only і +стейджать його в тимчасовий workdir усередині контейнера. Це зберігає runtime +image компактним, водночас запускаючи Vitest проти саме вашого локального source/config. +Крок staging пропускає великі локальні cache та outputs збірки застосунків, як-от +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні для застосунків `.build` або +output-директорії Gradle, щоб Docker live runs не витрачали хвилини на копіювання machine-specific artifacts. -Вони також задають `OPENCLAW_SKIP_CHANNELS=1`, щоб gateway live probes не запускали -реальні Telegram/Discord/тощо channel workers усередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте +Вони також задають `OPENCLAW_SKIP_CHANNELS=1`, щоб live probes Gateway не запускали +реальних Telegram/Discord/etc. channel workers усередині контейнера. +`test:docker:live-models` все ще запускає `pnpm test:live`, тому передавайте також `OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway -live coverage з цієї Docker-ланки. -`test:docker:openwebui` — це вищорівнева smoke-перевірка сумісності: вона запускає -контейнер OpenClaw gateway з увімкненими OpenAI-сумісними HTTP endpoints, -запускає pinned контейнер Open WebUI проти цього gateway, входить через +live coverage із цієї Docker lane. +`test:docker:openwebui` — це compatibility smoke вищого рівня: він запускає +контейнер Gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoints, +запускає pinned контейнер Open WebUI проти цього Gateway, входить через Open WebUI, перевіряє, що `/api/models` надає `openclaw/default`, а потім надсилає реальний chat request через proxy `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, бо Docker може мати потребу підтягнути -образ Open WebUI, а Open WebUI може мати потребу завершити власний cold-start setup. -Ця ланка очікує придатний live model key, а `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) є основним способом надати його в Dockerized runs. +Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися завантажити +Open WebUI image, а 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` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає засіяний Gateway -container, запускає другий контейнер, який породжує `openclaw mcp serve`, потім -перевіряє routed conversation discovery, читання transcript, attachment metadata, -поведінку live event queue, маршрутизацію outbound send і Claude-style channel + -permission notifications через реальний stdio MCP bridge. Перевірка notification +реального облікового запису Telegram, Discord або iMessage. Він завантажує засіяний контейнер Gateway, +запускає другий контейнер, який породжує `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 фактично emitting, а не лише те, що випадково поверхнює конкретний client SDK. +bridge фактично випромінює, а не лише те, що випадково показує конкретний client SDK. `test:docker:pi-bundle-mcp-tools` детермінований і не потребує live model key. Він збирає repo Docker image, запускає реальний stdio MCP probe server -усередині контейнера, materializes цей server через runtime вбудованого Pi bundle -MCP, виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають -tools `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` фільтрують їх. +усередині контейнера, матеріалізує цей server через embedded Pi bundle +MCP runtime, виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають +`bundle-mcp` tools, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. `test:docker:cron-mcp-cleanup` детермінований і не потребує live model key. Він запускає засіяний Gateway із реальним stdio MCP probe server, виконує -ізольований cron turn і one-shot child turn `/subagents spawn`, а потім перевіряє, -що дочірній MCP process завершується після кожного запуску. +ізольований cron turn і одноразовий child turn `/subagents spawn`, а потім перевіряє, +що MCP child process завершується після кожного запуску. -Ручна plain-language thread smoke-перевірка ACP (не CI): +Ручний ACP plain-language thread smoke (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Збережіть цей скрипт для regression/debug workflows. Він може знову знадобитися для валідації routing thread ACP, тож не видаляйте його. +- Зберігайте цей скрипт для regression/debug workflows. Він може знову знадобитися для валідації 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`, використовуючи тимчасові каталоги config/workspace і без зовнішніх монтувань автентифікації CLI +- `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/...` перед початком тестів - Типові каталоги: `.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_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Перевизначте вручну за допомогою `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або списку через кому на кшталт `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів у контейнері -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища профілю (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway надає для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, які не потребують перебудови +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища профілів (а не з середовища) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway відкриває для перевірки Open WebUI smoke +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовується перевіркою Open WebUI smoke - `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI ## Перевірка документації -Запускайте перевірки документації після редагувань документів: `pnpm check:docs`. -Запускайте повну валідацію anchor Mintlify, коли також потрібні перевірки заголовків на сторінці: `pnpm docs:check-links:anchors`. +Запускайте перевірки документації після редагування документів: `pnpm check:docs`. +Запускайте повну перевірку якорів Mintlify, коли також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) -Це регресії «реального pipeline» без реальних провайдерів: +Це регресії «справжнього 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`, записує config + примусова автентифікація): `src/gateway/gateway.test.ts` (кейс: "runs wizard over ws and writes auth token config") +- Виклики інструментів Gateway (імітація OpenAI, справжній gateway + agent loop): `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") -## Оцінювання надійності агента (skills) +## Оцінювання надійності агента (Skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: -- Mock виклику інструментів через реальний gateway + цикл агента (`src/gateway/gateway.test.ts`). -- End-to-end потоки майстра, які перевіряють зв’язування сесії та ефекти config (`src/gateway/gateway.test.ts`). +- Імітовані виклики інструментів через справжні gateway + agent loop (`src/gateway/gateway.test.ts`). +- Наскрізні потоки майстра, які перевіряють зв’язування сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). -Чого ще бракує для skills (див. [Skills](/uk/tools/skills)): +Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Ухвалення рішень:** коли skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Відповідність:** чи читає агент `SKILL.md` перед використанням і чи дотримується обов’язкових кроків/аргументів? +- **Прийняття рішень:** коли skills перелічено в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? - **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні evals мають спершу залишатися детермінованими: +Майбутні оцінювання мають насамперед залишатися детермінованими: -- Запускач сценаріїв із mock провайдерами для перевірки викликів інструментів + порядку, читання файлів skill і зв’язування сесії. -- Невеликий набір сценаріїв, зосереджених на skill (використати чи уникнути, gating, prompt injection). -- Необов’язкові live evals (opt-in, керовані env) лише після появи безпечного для CI набору. +- Ранер сценаріїв із mock-провайдерами для перевірки викликів інструментів + порядку, читання файлів skill і зв’язування сесії. +- Невеликий набір сценаріїв, сфокусованих на skill (використати або уникнути, gating, prompt injection). +- Необов’язкові live-оцінювання (opt-in, керовані env) лише після появи безпечного для CI набору. -## Контрактні тести (форма plugin і каналу) +## Контрактні тести (форма plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований plugin і канал відповідає своєму -контракту інтерфейсу. Вони проходять по всіх виявлених plugins і запускають набір -перевірок форми та поведінки. Типова unit-ланка `pnpm test` навмисно -пропускає ці спільні seam і smoke-файли; запускайте контрактні команди явно, -коли змінюєте спільні поверхні каналів або провайдерів. +Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму +інтерфейсному контракту. Вони проходять усі виявлені plugins і запускають набір +перевірок форми та поведінки. Стандартний unit-lane `pnpm test` навмисно +пропускає ці спільні файли seam і smoke; запускайте контрактні команди явно, +коли змінюєте спільні поверхні channel або provider. ### Команди - Усі контракти: `pnpm test:contracts` -- Лише контракти каналів: `pnpm test:contracts:channels` -- Лише контракти провайдерів: `pnpm test:contracts:plugins` +- Лише контракти channel: `pnpm test:contracts:channels` +- Лише контракти provider: `pnpm test:contracts:plugins` -### Контракти каналів +### Контракти channel Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма plugin (id, назва, можливості) +- **plugin** - Базова форма plugin (id, name, capabilities) - **setup** - Контракт майстра налаштування -- **session-binding** - Поведінка зв’язування сесії +- **session-binding** - Поведінка прив’язування сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень -- **actions** - Обробники дій каналу -- **threading** - Обробка ID гілки -- **directory** - API каталогу/реєстру -- **group-policy** - Застосування групової політики +- **actions** - Обробники дій channel +- **threading** - Обробка ID thread +- **directory** - API каталогу/roster +- **group-policy** - Застосування політики груп -### Контракти статусу провайдерів +### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки статусу каналу -- **registry** - Форма реєстру Plugin +- **status** - Перевірки статусу channel +- **registry** - Форма registry plugin -### Контракти провайдерів +### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку автентифікації - **auth-choice** - Вибір автентифікації - **catalog** - API каталогу моделей -- **discovery** - Виявлення Plugin -- **loader** - Завантаження Plugin -- **runtime** - Runtime провайдера -- **shape** - Форма/інтерфейс Plugin +- **discovery** - Виявлення plugin +- **loader** - Завантаження plugin +- **runtime** - Runtime provider +- **shape** - Форма/інтерфейс plugin - **wizard** - Майстер налаштування ### Коли запускати -- Після зміни експортів plugin-sdk або subpaths -- Після додавання чи зміни каналу або provider plugin +- Після зміни експортів або subpaths plugin-sdk +- Після додавання або змінення channel чи provider plugin - Після рефакторингу реєстрації або виявлення plugin -Контрактні тести запускаються в CI і не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують справжніх API-ключів. ## Додавання регресій (настанови) -Коли ви виправляєте проблему провайдера/моделі, виявлену в live: +Коли ви виправляєте проблему provider/model, виявлену в live: -- Додайте безпечну для CI регресію, якщо можливо (mock/stub провайдер або зафіксуйте точне перетворення форми запиту) -- Якщо це за своєю природою лише live-only (обмеження швидкості, політики автентифікації), тримайте live-тест вузьким і opt-in через env vars -- Надавайте перевагу найменшому шару, який ловить баг: - - баг перетворення/відтворення запиту провайдера → прямий тест моделей - - баг pipeline сесії/історії/інструментів gateway → gateway live smoke або безпечний для CI mock-тест gateway +- Додайте безпечну для CI регресію, якщо можливо (mock/stub provider або захоплення точної трансформації форми запиту) +- Якщо це за своєю природою лише live (обмеження швидкості, політики автентифікації), залишайте live-тест вузьким і opt-in через env vars +- Надавайте перевагу найменшому шару, який ловить помилку: + - помилка перетворення/відтворення запиту provider → прямий тест моделей + - помилка pipeline сесії/історії/інструментів gateway → gateway live smoke або безпечний для CI mock-тест gateway - Захисне обмеження обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибрану ціль для кожного класу SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec ids із traversal-segment відхиляються. + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибрану ціль на клас SecretRef з метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec ids із traversal-сегментами відхиляються. - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target ids, щоб нові класи не можна було мовчки пропустити. ## Пов’язане