openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-02 06:56:13 +00:00
parent 79f3841a26
commit c31db0755e
4 changed files with 629 additions and 542 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

420
docs/uk/ci.md
View File

@ -1,93 +1,93 @@
---
read_when:
- Потрібно зрозуміти, чому завдання CI запустилося або не запустилося
- Ви налагоджуєте невдалу перевірку GitHub Actions
- Ви координуєте запуск або повторний запуск перевірки релізу
- Вам потрібно зрозуміти, чому завдання CI запустилося або не запустилося
- Ви налагоджуєте перевірку GitHub Actions, яка не проходить
- Ви координуєте запуск або повторний запуск валідації релізу
- Ви змінюєте диспетчеризацію ClawSweeper або пересилання активності GitHub
summary: Граф завдань CI, гейти за областю дії, парасолькові релізні перевірки та локальні еквіваленти команд
summary: Граф завдань CI, контрольні перевірки за обсягом, релізні парасольки та локальні еквіваленти команд
title: CI-конвеєр
x-i18n:
generated_at: "2026-05-02T06:28:34Z"
generated_at: "2026-05-02T06:53:39Z"
model: gpt-5.5
provider: openai
source_hash: 03258176c6672355abf335bfcb2a962c0ddc62605aaeaba1f60f513d03bce2d4
source_hash: 39af4afcb3e7c847c44a9d47513ac4b99c62d13fb139ece0bee979f24687ea38
source_path: ci.md
workflow: 16
---
OpenClaw CI запускається для кожного push у `main` і кожного pull request. Завдання `preflight` класифікує diff і вимикає дорогі lane, коли змінено лише непов’язані області. Ручні запуски `workflow_dispatch` навмисно обходять розумне scoped-обмеження й розгортають повний граф для release candidate та широкої валідації. Android lane залишаються 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-лінії залишаються опційними через `include_android`. Покриття Plugin лише для релізу розміщене в окремому workflow [`Plugin Prerelease`](#plugin-prerelease) і запускається лише з [`Full Release Validation`](#full-release-validation) або явного ручного dispatch.
## Огляд pipeline
| Завдання | Призначення | Коли запускається |
| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- |
| `preflight` | Виявляє docs-only зміни, змінені scopes, змінені extensions і будує CI manifest | Завжди для non-draft push і PR |
| `security-scm-fast` | Виявлення приватних ключів і audit workflow через `zizmor` | Завжди для non-draft push і PR |
| `security-dependency-audit` | Audit production lockfile без залежностей щодо npm advisories | Завжди для non-draft push і PR |
| `security-fast` | Обов’язковий aggregate для швидких security jobs | Завжди для non-draft push і PR |
| `check-dependencies` | Production Knip dependency-only pass плюс guard allowlist для unused-file | Node-релевантні зміни |
| `build-artifacts` | Build `dist/`, Control UI, built-artifact checks і повторно використовувані downstream artifacts | Node-релевантні зміни |
| `checks-fast-core` | Швидкі Linux correctness lanes, як-от bundled/plugin-contract/protocol checks | Node-релевантні зміни |
| `checks-fast-contracts-channels` | Sharded channel contract checks зі стабільним aggregate check result | Node-релевантні зміни |
| `checks-node-core-test` | Core Node test shards, за винятком channel, bundled, contract і extension lanes | Node-релевантні зміни |
| `check` | Sharded еквівалент основного local 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 для релізів |
| `check-docs` | Форматування docs, lint і перевірки broken-link | Docs змінено |
| `skills-python` | Ruff + pytest для Python-backed skills | Зміни, релевантні Python-skill |
| `checks-windows` | Windows-specific process/path tests плюс shared runtime import specifier regressions | Windows-релевантні зміни |
| `macos-node` | macOS TypeScript test lane з використанням shared built artifacts | macOS-релевантні зміни |
| `macos-swift` | Swift lint, build і tests для macOS app | macOS-релевантні зміни |
| `android` | Android unit tests для обох flavors плюс один debug APK build | Android-релевантні зміни |
| `test-performance-agent` | Щоденна Codex оптимізація повільних тестів після trusted activity | Успіх Main CI або ручний dispatch |
| `preflight` | Виявляє зміни лише в документації, змінені області, змінені extensions і будує CI manifest | Завжди для non-draft push і PR |
| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft push і PR |
| `security-dependency-audit` | Аудит production lockfile без залежностей щодо npm advisories | Завжди для non-draft push і PR |
| `security-fast` | Обов’язковий агрегат для швидких security-завдань | Завжди для non-draft push і PR |
| `check-dependencies` | Production Knip dependency-only pass плюс guard allowlist невикористаних файлів | Зміни, релевантні для Node |
| `build-artifacts` | Збірка `dist/`, Control UI, перевірки built-artifact і багаторазові downstream artifacts | Зміни, релевантні для Node |
| `checks-fast-core` | Швидкі Linux-лінії коректності, як-от bundled/plugin-contract/protocol checks | Зміни, релевантні для Node |
| `checks-fast-contracts-channels` | Sharded перевірки channel contract зі стабільним aggregate check result | Зміни, релевантні для Node |
| `checks-node-core-test` | Core Node test shards, без channel, bundled, contract і extension ліній | Зміни, релевантні для Node |
| `check` | Sharded еквівалент головного локального gate: prod types, lint, guards, test types і strict smoke | Зміни, релевантні для Node |
| `check-additional` | Architecture, boundary, extension-surface guards, package-boundary і gateway-watch shards | Зміни, релевантні для Node |
| `build-smoke` | Built-CLI smoke tests і startup-memory smoke | Зміни, релевантні для Node |
| `checks` | Verifier для built-artifact channel tests | Зміни, релевантні для Node |
| `checks-node-compat-node22` | Збірка сумісності Node 22 і smoke-лінія | Ручний CI dispatch для релізів |
| `check-docs` | Форматування документації, lint і перевірки broken-link | Документація змінилася |
| `skills-python` | Ruff + pytest для Skills на Python | Зміни, релевантні для Python-skill |
| `checks-windows` | Windows-специфічні тести процесів/шляхів плюс спільні регресії 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 або manual dispatch |
## Порядок fail-fast
1. `preflight` вирішує, які lane взагалі існують. Логіка `docs-scope` і `changed-scope` є кроками всередині цього завдання, а не окремими завданнями.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко падають без очікування важчих artifact і platform matrix jobs.
3. `build-artifacts` перекривається зі швидкими Linux lanes, щоб downstream consumers могли стартувати, щойно shared build буде готовий.
4. Важчі platform і runtime lanes розгортаються після цього: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`.
1. `preflight` вирішує, які лінії взагалі існують. Логіка `docs-scope` і `changed-scope` є кроками всередині цього завдання, а не окремими завданнями.
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` падають швидко, не чекаючи на важчі artifact і platform matrix jobs.
3. `build-artifacts` перекривається зі швидкими Linux-лініями, щоб downstream consumers могли стартувати щойно спільна збірка готова.
4. Важчі platform і runtime лінії розгортаються після цього: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`.
GitHub може позначати superseded jobs як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Сприймайте це як CI noise, якщо найновіший run для того самого ref також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тому вони все одно повідомляють звичайні shard failures, але не стають у чергу після того, як увесь workflow уже було superseded. Automatic CI concurrency key має versioned формат (`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 також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тому вони все одно звітують про нормальні shard failures, але не стають у чергу після того, як весь workflow уже витіснено. Автоматичний CI concurrency key має версію (`CI-v7-*`), щоб GitHub-side zombie у старій queue group не міг безстроково блокувати новіші main runs. Ручні full-suite runs використовують `CI-manual-v1-*` і не скасовують in-progress runs.
## Scope і routing
## Область і routing
Логіка scope міститься в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`. Manual dispatch пропускає changed-scope detection і змушує preflight manifest діяти так, ніби кожна scoped area змінилася.
Логіка області міститься в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`. Manual dispatch пропускає виявлення changed-scope і змушує preflight manifest поводитися так, ніби кожна scoped area змінилася.
- **CI workflow edits** валідують Node CI graph плюс workflow linting, але самі собою не примушують Windows, Android або macOS native builds; ці platform lanes залишаються scoped до platform source changes.
- **CI routing-only edits, selected cheap core-test fixture edits і narrow plugin contract helper/test-routing edits** використовують fast Node-only manifest path: `preflight`, security і одне завдання `checks-fast-core`. Цей path пропускає build artifacts, Node 22 compatibility, channel contracts, full core shards, bundled-plugin shards і additional guard matrices, коли зміна обмежена routing або helper surfaces, які fast task перевіряє безпосередньо.
- **Windows Node checks** scoped до Windows-specific process/path wrappers, npm/pnpm/UI runner helpers, package manager config і CI workflow surfaces, які виконують цю lane; unrelated source, plugin, install-smoke і test-only changes залишаються на Linux Node lanes.
- **Редагування CI workflow** валідують Node CI graph плюс workflow linting, але самі по собі не примушують Windows, Android або macOS native builds; ці platform lanes залишаються прив’язаними до змін platform source.
- **Редагування лише CI routing, вибрані дешеві core-test fixture edits і вузькі plugin contract helper/test-routing edits** використовують швидкий Node-only manifest path: `preflight`, security і одне завдання `checks-fast-core`. Цей path пропускає build artifacts, сумісність Node 22, channel contracts, full core shards, bundled-plugin shards і additional guard matrices, коли зміна обмежена routing або helper surfaces, які fast task напряму виконує.
- **Windows Node checks** обмежені Windows-specific process/path wrappers, npm/pnpm/UI runner helpers, package manager config і CI workflow surfaces, які виконують цю лінію; непов’язані source, plugin, install-smoke і test-only changes залишаються на Linux Node lanes.
Найповільніші сімейства Node test розділено або збалансовано так, щоб кожне завдання залишалося малим без надмірного резервування runners: channel contracts працюють як три weighted shards, small core unit lanes об’єднані в пари, auto-reply працює як чотири balanced workers (із reply subtree, розділеним на agent-runner, dispatch і commands/state-routing shards), а agentic gateway/plugin configs розподілено між наявними source-only agentic Node jobs замість очікування built artifacts. Broad browser, QA, media і miscellaneous plugin tests використовують свої dedicated Vitest configs замість shared plugin catch-all. Include-pattern shards записують timing entries із назвою CI shard, тому `.artifacts/vitest-shard-timings.json` може відрізнити whole config від filtered shard. `check-additional` тримає package-boundary compile/canary work разом і відокремлює runtime topology architecture від gateway watch coverage; boundary guard shard запускає свої small independent guards паралельно всередині одного job. Gateway watch, channel tests і core support-boundary shard запускаються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже збудовано.
Найповільніші Node test families розділені або збалансовані, щоб кожне завдання лишалося малим без надмірного резервування runners: channel contracts виконуються як три weighted shards, малі core unit lanes поєднані парами, auto-reply працює як чотири balanced workers (із reply subtree, розділеним на agent-runner, dispatch і commands/state-routing shards), а agentic gateway/plugin configs розподілені між наявними source-only agentic Node jobs замість очікування built artifacts. Широкі browser, QA, media і miscellaneous plugin tests використовують свої dedicated Vitest configs замість shared plugin catch-all. Include-pattern shards записують timing entries із назвою CI shard, щоб `.artifacts/vitest-shard-timings.json` міг відрізнити whole config від filtered shard. `check-additional` тримає package-boundary compile/canary work разом і відокремлює runtime topology architecture від gateway watch coverage; boundary guard shard запускає свої малі незалежні 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 з BuildConfig flags для SMS/call-log, уникаючи duplicate debug APK packaging job на кожному Android-релевантному push.
Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane все одно компілює flavor із SMS/call-log BuildConfig flags, уникаючи водночас duplicate debug APK packaging job для кожного Android-relevant push.
Shard `check-dependencies` запускає `pnpm deadcode:dependencies` (production Knip dependency-only pass, pinned до latest Knip version, із вимкненим pnpm minimum release age для встановлення `dlx`) і `pnpm deadcode:unused-files`, який порівнює production unused-file findings від Knip з `scripts/deadcode-unused-files.allowlist.mjs`. Unused-file guard падає, коли PR додає новий unreviewed unused file або залишає stale allowlist entry, зберігаючи intentional dynamic plugin, generated, build, live-test і package bridge surfaces, які Knip не може статично resolve.
Shard `check-dependencies` запускає `pnpm deadcode:dependencies` (production Knip dependency-only pass, закріплений на найновішій версії Knip, з вимкненим minimum release age pnpm для встановлення `dlx`) і `pnpm deadcode:unused-files`, який порівнює production unused-file findings Knip із `scripts/deadcode-unused-files.allowlist.mjs`. Unused-file guard падає, коли PR додає новий непереглянутий unused file або залишає застарілий allowlist entry, зберігаючи водночас intentional dynamic plugin, generated, build, live-test і package bridge surfaces, які Knip не може статично розв’язати.
## ClawSweeper activity forwarding
## Пересилання активності ClawSweeper
`.github/workflows/clawsweeper-dispatch.yml` є target-side bridge від активності репозиторію OpenClaw до ClawSweeper. Він не check out і не виконує untrusted pull request code. Workflow створює GitHub App token із `CLAWSWEEPER_APP_PRIVATE_KEY`, а потім dispatches компактні `repository_dispatch` payloads до `openclaw/clawsweeper`.
`.github/workflows/clawsweeper-dispatch.yml` є target-side bridge з активності репозиторію 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 commands у issue comments;
- `clawsweeper_commit_review` для commit-level review requests на push у `main`;
- `github_activity` для загальної GitHub activity, яку ClawSweeper agent може inspect.
- `clawsweeper_item` для точних запитів review issue і pull request;
- `clawsweeper_comment` для явних команд ClawSweeper у коментарях issue;
- `clawsweeper_commit_review` для запитів commit-level review на push до `main`;
- `github_activity` для загальної GitHub activity, яку агент 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` пересилає лише нормалізовані metadata: event type, action, actor, repository, item number, URL, title, state і короткі excerpts для comments або reviews, коли вони є. Вона навмисно уникає пересилання повного webhook body. Receiving workflow в `openclaw/clawsweeper` — це `.github/workflows/github-activity.yml`, який надсилає normalized event до OpenClaw Gateway hook для агента 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` лише коли event є несподіваним, actionable, ризиковим або операційно корисним. Рутинні opens, edits, bot churn, duplicate webhook noise і normal review traffic мають давати `NO_REPLY`.
Сприймайте GitHub titles, comments, bodies, review text, branch names і commit messages як untrusted data на всьому цьому path. Вони є input для summarization і triage, а не інструкціями для workflow або agent runtime.
Сприймайте GitHub titles, comments, bodies, review text, branch names і commit messages як ненадійні дані на всьому цьому path. Вони є input для summarization і triage, а не інструкціями для workflow або agent runtime.
## Ручні dispatches
Manual CI dispatches запускають той самий job graph, що й normal CI, але примусово вмикають кожну non-Android scoped lane: Linux Node shards, bundled-plugin shards, channel contracts, Node 22 compatibility, `check`, `check-additional`, build smoke, docs checks, Python skills, Windows, macOS і Control UI i18n. Standalone manual CI dispatches запускають Android лише з `include_android=true`; full release umbrella вмикає Android, передаючи `include_android=true`. Plugin prerelease static checks, release-only shard `agentic-plugins`, full extension batch sweep і plugin prerelease Docker lanes виключені з CI. Docker prerelease suite запускається лише тоді, коли `Full Release Validation` dispatches окремий workflow `Plugin Prerelease` з увімкненим release-validation gate.
Manual CI dispatches запускають той самий job graph, що й normal CI, але примусово вмикають кожну non-Android scoped lane: Linux Node shards, bundled-plugin shards, channel contracts, сумісність Node 22, `check`, `check-additional`, build smoke, docs checks, Python skills, Windows, macOS і Control UI i18n. Standalone manual CI dispatches запускають Android лише з `include_android=true`; повна 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` dispatch окремий workflow `Plugin Prerelease` з увімкненим release-validation gate.
Manual runs використовують unique concurrency group, тому release-candidate full suite не скасовується іншим push або PR run на тому самому ref. Необов’язковий input `target_ref` дає trusted caller змогу запускати цей graph проти branch, tag або full commit SHA, використовуючи workflow file із selected dispatch ref.
Manual runs використовують унікальну concurrency group, щоб release-candidate full suite не скасовувався іншим push або PR run на тому самому ref. Опційний input `target_ref` дає trusted caller змогу запустити цей graph для branch, tag або full commit SHA, використовуючи workflow file з вибраного dispatch ref.
```bash
gh workflow run ci.yml --ref release/YYYY.M.D
@ -97,17 +97,17 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
## Ранери
| Ранер | Завдання |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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 також використовує 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-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки протоколу/контрактів/вбудованого, шардовані перевірки контрактів каналів, шарди `check`, окрім lint, шарди й агрегати `check-additional`, агреговані верифікатори тестів Node, перевірки документації, Python skills, workflow-sanity, labeler, auto-response; install-smoke preflight також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла ставати в чергу раніше |
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, легші шарди плагінів, `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` |
## Локальні відповідники
## Локальні еквіваленти
```bash
pnpm changed:lanes # inspect the local changed-lane classifier for origin/main...HEAD
@ -135,60 +135,68 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac
## Повна валідація релізу
`Full Release Validation` — це ручний парасольковий workflow для «запустити все перед релізом». Він приймає гілку, тег або повний SHA коміту, запускає ручний workflow `CI` із цією ціллю, запускає `Plugin Prerelease` для релізних доказів Plugin/пакетів/статичних артефактів/Docker, а також запускає `OpenClaw Release Checks` для install smoke, приймання пакетів, наборів Docker для релізного шляху, live/E2E, OpenWebUI, паритету QA Lab, Matrix і доріжок Telegram. З `rerun_group=all` і `release_profile=full` він також запускає `NPM Telegram Beta E2E` проти артефакту `release-package-under-test` з release checks. Після публікації передайте `npm_telegram_package_spec`, щоб повторно запустити ту саму доріжку пакета Telegram проти опублікованого npm-пакета.
`Full Release Validation` — це ручний парасольковий workflow для «запустити все перед релізом». Він приймає гілку, тег або повний SHA коміту, запускає ручний workflow `CI` із цією ціллю, запускає `Plugin Prerelease` для релізного підтвердження Plugin/пакетів/статичних артефактів/Docker, а також запускає `OpenClaw Release Checks` для install smoke, package acceptance, Docker release-path suite, live/E2E, OpenWebUI, QA Lab parity, Matrix і Telegram lane. З `rerun_group=all` і `release_profile=full` він також запускає `NPM Telegram Beta E2E` проти артефакту `release-package-under-test` із release checks. Після публікації передайте `npm_telegram_package_spec`, щоб повторно запустити той самий Telegram package lane проти опублікованого npm-пакета.
Див. [повну валідацію релізу](/uk/reference/full-release-validation) для
матриці етапів, точних назв завдань workflow, відмінностей профілів, артефактів і
ручок для сфокусованого повторного запуску.
Див. [повну валідацію релізу](/uk/reference/full-release-validation), щоб переглянути
матрицю етапів, точні назви завдань workflow, відмінності профілів, артефакти та
ідентифікатори для сфокусованих повторних запусків.
`OpenClaw Release Publish` — це ручний змінювальний workflow релізу. Запускайте його
з `release/YYYY.M.D` або `main` після того, як існує тег релізу, і після того, як
передперевірка OpenClaw npm успішно завершилася. Він перевіряє `pnpm plugins:sync:check`,
`OpenClaw Release Publish` — це ручний workflow релізу, який змінює стан. Запускайте його
з `release/YYYY.M.D` або `main` після того, як існує тег релізу і після успішного
OpenClaw npm preflight. Він перевіряє `pnpm plugins:sync:check`,
запускає `Plugin NPM Release` для всіх публікованих пакетів Plugin, запускає
`Plugin ClawHub Release` для того самого SHA релізу, і лише після цього запускає
`Plugin ClawHub Release` для того самого SHA релізу і лише потім запускає
`OpenClaw NPM Release` зі збереженим `preflight_run_id`.
Для доказу зафіксованого коміту на швидко змінюваній гілці використовуйте helper замість
```bash
gh workflow run openclaw-release-publish.yml \
--ref release/YYYY.M.D \
-f tag=vYYYY.M.D-beta.N \
-f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
-f npm_dist_tag=beta
```
Для підтвердження за закріпленим комітом на гілці, що швидко рухається, використовуйте helper замість
`gh workflow run ... --ref main -f ref=<sha>`:
```bash
pnpm ci:full-release --sha <full-sha>
```
Refs запуску workflow GitHub мають бути гілками або тегами, а не сирими SHA комітів. Helper
надсилає тимчасову гілку `release-ci/<sha>-...` на цільовий SHA,
запускає `Full Release Validation` з цього зафіксованого ref, перевіряє, що кожен дочірній
workflow `headSha` збігається з ціллю, і видаляє тимчасову гілку, коли запуск
завершується. Парасольковий верифікатор також завершується з помилкою, якщо будь-який дочірній workflow виконувався на
GitHub workflow dispatch refs мають бути гілками або тегами, а не сирими SHA комітів.
Helper пушить тимчасову гілку `release-ci/<sha>-...` на цільовому SHA,
запускає `Full Release Validation` із цього закріпленого ref, перевіряє, що кожен дочірній
workflow `headSha` збігається з ціллю, і видаляє тимчасову гілку після завершення
запуску. Парасольковий верифікатор також падає, якщо будь-який дочірній workflow виконувався на
іншому SHA.
`release_profile` керує широтою live/provider, що передається в release checks. Ручні
релізні workflow типово використовують `stable`; використовуйте `full` лише тоді, коли ви
навмисно хочете широку дорадчу матрицю provider/media.
`release_profile` керує шириною live/provider, що передається в release checks. Ручні
release workflows типово використовують `stable`; використовуйте `full` лише тоді, коли
навмисно потрібна широка advisory provider/media matrix.
- `minimum` залишає найшвидші критичні для релізу доріжки OpenAI/core.
- `minimum` залишає найшвидші критичні для релізу OpenAI/core lanes.
- `stable` додає стабільний набір provider/backend.
- `full` запускає широку дорадчу матрицю provider/media.
- `full` запускає широку advisory provider/media matrix.
Парасолька записує id запущених дочірніх запусків, а фінальне завдання `Verify full validation` повторно перевіряє поточні висновки дочірніх запусків і додає таблиці найповільніших завдань для кожного дочірнього запуску. Якщо дочірній workflow перезапустили і він став зеленим, перезапустіть лише батьківське завдання верифікатора, щоб оновити результат парасольки й підсумок часу.
Парасолька записує ідентифікатори запущених дочірніх запусків, а фінальне завдання `Verify full validation` повторно перевіряє поточні результати дочірніх запусків і додає таблиці найповільніших завдань для кожного дочірнього запуску. Якщо дочірній workflow перезапущено і він став зеленим, перезапустіть лише батьківське завдання верифікатора, щоб оновити результат парасольки та підсумок таймінгів.
Для відновлення і `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` для release candidate, `ci` лише для звичайного повного дочірнього CI, `plugin-prerelease` лише для дочірнього plugin prerelease, `release-checks` для кожного дочірнього release, або вужчу групу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` чи `npm-telegram` на парасольці. Це утримує повторний запуск невдалого release box обмеженим після сфокусованого виправлення.
`OpenClaw Release Checks` використовує довірений ref workflow, щоб один раз розв’язати вибраний ref у tarball `release-package-under-test`, а потім передає цей артефакт і в Docker workflow live/E2E релізного шляху, і в шард приймання пакета. Це зберігає байти пакета узгодженими між релізними боксами й уникає повторного пакування того самого кандидата в кількох дочірніх завданнях.
`OpenClaw Release Checks` використовує довірений workflow ref, щоб один раз розв’язати вибраний ref у tarball `release-package-under-test`, а потім передає цей артефакт і в live/E2E release-path Docker workflow, і в package acceptance shard. Це зберігає однакові байти пакета між release boxes і уникає повторного пакування того самого кандидата в кількох дочірніх завданнях.
Дублікати запусків `Full Release Validation` для `ref=main` і `rerun_group=all`
замінюють старішу парасольку. Батьківський монітор скасовує будь-який дочірній workflow, який він
уже запустив, коли батьківський запуск скасовано, тому новіша валідація main
не стоїть за застарілим двогодинним запуском release-check. Валідація гілки/тега релізу
та сфокусовані групи повторного запуску зберігають `cancel-in-progress: false`.
витісняють старішу парасольку. Батьківський монітор скасовує будь-який дочірній workflow, який він
уже запустив, коли батьківський запуск скасовано, тож новіша валідація main
не стоїть за застарілим двогодинним запуском release-check. Валідація release branch/tag
і сфокусовані групи повторного запуску зберігають `cancel-in-progress: false`.
## Live та E2E шарди
Дочірній release live/E2E зберігає широке нативне покриття `pnpm test:live`, але запускає його як іменовані шарди через `scripts/test-live-shard.mjs` замість одного послідовного завдання:
Дочірній release live/E2E зберігає широке native покриття `pnpm test:live`, але запускає його як іменовані шарди через `scripts/test-live-shard.mjs` замість одного послідовного завдання:
- `native-live-src-agents`
- `native-live-src-gateway-core`
- provider-filtered завдання `native-live-src-gateway-profiles`
- відфільтровані за provider завдання `native-live-src-gateway-profiles`
- `native-live-src-gateway-backends`
- `native-live-test`
- `native-live-extensions-a-k`
@ -196,61 +204,61 @@ workflow `headSha` збігається з ціллю, і видаляє тим
- `native-live-extensions-openai`
- `native-live-extensions-o-z-other`
- `native-live-extensions-xai`
- розділені шарди audio/video media та provider-filtered шарди music
- розділені media audio/video шарди та відфільтровані за provider music шарди
Це зберігає те саме файлове покриття, водночас полегшуючи повторний запуск і діагностику повільних збоїв live provider. Агреговані назви шардів `native-live-extensions-o-z`, `native-live-extensions-media` і `native-live-extensions-media-music` залишаються чинними для ручних одноразових повторних запусків.
Це зберігає те саме покриття файлів, водночас спрощуючи повторний запуск і діагностику повільних збоїв live provider. Агреговані назви шард `native-live-extensions-o-z`, `native-live-extensions-media` і `native-live-extensions-media-music` залишаються чинними для ручних одноразових повторних запусків.
Нативні шарди live media запускаються в `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, зібраному workflow `Live Media Runner Image`. Цей образ попередньо встановлює `ffmpeg` і `ffprobe`; завдання media лише перевіряють бінарні файли перед налаштуванням. Тримайте Docker-backed live-набори на звичайних раннерах Blacksmith — container jobs є неправильним місцем для запуску вкладених Docker-тестів.
Native live media шарди виконуються в `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, зібраному workflow `Live Media Runner Image`. Цей образ попередньо встановлює `ffmpeg` і `ffprobe`; media jobs лише перевіряють бінарні файли перед налаштуванням. Тримайте Docker-backed live suites на звичайних Blacksmith runners — container jobs є неправильним місцем для запуску вкладених Docker tests.
Docker-підкріплені live-шарди моделей/backend використовують окремий спільний образ `ghcr.io/openclaw/openclaw-live-test:<sha>` для кожного вибраного коміту. Workflow live-релізу один раз збирає й публікує цей образ, а потім 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. Якщо ці шарди незалежно перебудовують повну Docker-ціль із джерельного коду, запуск релізу налаштований неправильно й марнуватиме реальний час на дубльовані збірки образів.
Підтримувані Docker шард-и live-моделей/бекендів використовують окремий спільний образ `ghcr.io/openclaw/openclaw-live-test:<sha>` для кожного вибраного коміту. Робочий процес live-релізу збирає й публікує цей образ один раз, після чого шард-и Docker live-моделі, provider-sharded Gateway, бекенду CLI, прив’язки ACP і Codex harness запускаються з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Docker-шард-и Gateway мають явні обмеження `timeout` на рівні скриптів нижче за тайм-аут завдання робочого процесу, щоб завислий контейнер або шлях очищення швидко завершувався помилкою, а не споживав увесь бюджет release-check. Якщо ці шард-и самостійно перебудовують повну ціль Docker з вихідного коду, запуск релізу налаштований неправильно й марнуватиме реальний час на дубльовані збірки образів.
## Приймання пакета
Використовуйте `Package Acceptance`, коли питання звучить так: "чи працює цей інстальований пакет OpenClaw як продукт?" Це відрізняється від звичайного CI: звичайний CI перевіряє дерево джерельного коду, тоді як приймання пакета перевіряє один tarball через той самий Docker E2E harness, який користувачі задіюють після встановлення або оновлення.
Використовуйте `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` і виводить source, workflow ref, package ref, version, SHA-256 і profile у GitHub step summary.
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 проти цього пакета замість пакування workflow checkout. Коли profile вибирає кілька цільових `docker_lanes`, повторно використовуваний workflow один раз готує пакет і спільні образи, а потім розгалужує ці lanes як паралельні цільові Docker jobs з унікальними артефактами.
3. `package_telegram` опційно викликає `NPM Telegram Beta E2E`. Він запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, якщо Package Acceptance визначив його; standalone Telegram dispatch усе ще може встановити опубліковану npm spec.
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`. Повторно використовуваний робочий процес завантажує цей артефакт, перевіряє інвентар tarball, за потреби готує Docker-образи package-digest і запускає вибрані Docker lanes проти цього пакета замість пакування checkout робочого процесу. Коли профіль вибирає кілька цільових `docker_lanes`, повторно використовуваний робочий процес готує пакет і спільні образи один раз, а потім розгалужує ці lanes як паралельні цільові Docker-завдання з унікальними артефактами.
3. `package_telegram` необов’язково викликає `NPM Telegram Beta E2E`. Він запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, якщо Package Acceptance визначив його; автономний dispatch Telegram все ще може встановити опубліковану npm-специфікацію.
4. `summary` завершує робочий процес помилкою, якщо визначення пакета, Docker acceptance або необов’язкова Telegram lane завершилися помилкою.
### Джерела кандидатів
- `source=npm` приймає лише `openclaw@beta`, `openclaw@latest` або точну версію релізу OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для приймання опублікованих beta/stable.
- `source=ref` пакує довірену гілку `package_ref`, тег або повний commit SHA. Resolver отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт досяжний з історії гілок репозиторію або release tag, встановлює залежності у detached worktree і пакує його через `scripts/package-openclaw-for-docker.mjs`.
- `source=url` завантажує HTTPS `.tgz`; `package_sha256` обов'язковий.
- `source=artifact` завантажує один `.tgz` з `artifact_run_id` і `artifact_name`; `package_sha256` опційний, але його варто надавати для зовнішньо поширених артефактів.
- `source=ref` пакує довірену гілку `package_ref`, тег або повний SHA коміту. Розв’язувач отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт досяжний з історії гілки репозиторію або релізного тегу, встановлює залежності в detached worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`.
- `source=url` завантажує HTTPS `.tgz`; `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=ref`. Це дає змогу поточному тестовому harness перевіряти старі довірені коміти вихідного коду без запуску старої логіки workflow.
### Профілі suite
### Профілі наборів
- `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` — повні Docker chunks релізного шляху з OpenWebUI
- `custom` — точні `docker_lanes`; обов'язково, коли `suite_profile=custom`
- `full` — повні фрагменти Docker release-path з OpenWebUI
- `custom` — точні `docker_lanes`; обов’язково, коли `suite_profile=custom`
Профіль `package` використовує offline-покриття plugin, щоб перевірка опублікованого пакета не залежала від live-доступності ClawHub. Опційна Telegram lane повторно використовує артефакт `package-under-test` у `NPM Telegram Beta E2E`, із шляхом опублікованої npm spec, залишеним для standalone dispatches.
Профіль `package` використовує offline plugin coverage, щоб перевірка опублікованого пакета не залежала від доступності live ClawHub. Необов’язкова Telegram lane повторно використовує артефакт `package-under-test` у `NPM Telegram Beta E2E`, а шлях опублікованої npm-специфікації збережено для автономних dispatch.
Окрему політику тестування оновлень і plugin, включно з локальними командами,
Docker lanes, входами Package Acceptance, типовими налаштуваннями релізу й triage збоїв,
Докладну політику тестування оновлень і plugin, включно з локальними командами,
Docker lanes, вхідними даними Package Acceptance, типовими параметрами релізу й triage помилок,
див. у [Тестування оновлень і plugin](/uk/help/testing-updates-plugins).
Release checks викликають Package Acceptance з `source=artifact`, підготовленим артефактом release package, `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, offline plugin, plugin-update і Telegram на тому самому визначеному package tarball. Крос-OS release checks усе ще покривають OS-специфічне onboarding, installer і поведінку платформи; продуктову перевірку package/update слід починати з Package Acceptance. Docker lane `published-upgrade-survivor` перевіряє один baseline опублікованого пакета за запуск. У Package Acceptance визначений tarball `package-under-test` завжди є кандидатом, а `published_upgrade_survivor_baseline` вибирає резервний опублікований baseline, за замовчуванням `openclaw@latest`; команди rerun для failed-lane зберігають цей baseline. Установіть `published_upgrade_survivor_baselines=release-history`, щоб розширити lane на deduped history matrix: останні шість stable-релізів, `2026.4.23` і останній stable-реліз перед `2026-03-15`. Установіть `published_upgrade_survivor_scenarios=reported-issues`, щоб розширити ті самі baselines на issue-shaped fixtures для конфігурації Feishu, збережених bootstrap/persona файлів, tilde log paths і застарілих legacy plugin dependency roots. Окремий workflow `Update Migration` використовує Docker lane `update-migration` з `all-since-2026.4.23` і `plugin-deps-cleanup`, коли питання стосується вичерпного очищення опублікованих оновлень, а не звичайної широти Full Release CI. Локальні aggregate runs можуть передавати точні package specs через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, залишати одну lane з `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, наприклад `openclaw@2026.4.15`, або встановлювати `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` для scenario matrix. Published lane налаштовує baseline через вбудований рецепт команд `openclaw config set`, записує кроки рецепта в `summary.json` і перевіряє `/healthz`, `/readyz`, а також RPC status після запуску Gateway. Windows packaged і installer fresh lanes також перевіряють, що встановлений пакет може імпортувати browser-control override із raw absolute Windows path. OpenAI cross-OS agent-turn smoke за замовчуванням використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли він заданий, інакше `openai/gpt-5.5`, щоб install і gateway proof залишалися на пріоритетній GPT-5 тестовій моделі.
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-залежності, offline plugin, plugin-update і Telegram на одному й тому самому визначеному package tarball. Cross-OS release checks все ще покривають специфічну для ОС поведінку onboarding, installer і platform; перевірку продукту package/update слід починати з Package Acceptance. Docker lane `published-upgrade-survivor` перевіряє один базовий опублікований пакет за запуск. У Package Acceptance визначений tarball `package-under-test` завжди є кандидатом, а `published_upgrade_survivor_baseline` вибирає fallback базовий опублікований пакет, типово `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`, щоб розширити ті самі baseline на issue-shaped fixtures для конфігурації Feishu, збережених bootstrap/persona-файлів, шляхів журналів із tilde та застарілих коренів legacy plugin-залежностей. Окремий workflow `Update Migration` використовує Docker lane `update-migration` з `all-since-2026.4.23` і `plugin-deps-cleanup`, коли питання полягає у вичерпному очищенні опублікованих оновлень, а не у звичайній широті Full Release CI. Локальні aggregate-запуски можуть передавати точні package specs через `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. Windows packaged і installer fresh lanes також перевіряють, що встановлений пакет може імпортувати browser-control override із raw absolute Windows path. OpenAI cross-OS agent-turn smoke типово використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли його задано, інакше `openai/gpt-5.5`, тож install і gateway proof залишаються на бажаній тестовій моделі GPT-5.
### Legacy compatibility windows
### Вікна сумісності зі спадщиною
Package Acceptance має обмежені legacy-compatibility windows для вже опублікованих пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть використовувати compatibility path:
Package Acceptance має обмежені вікна legacy-compatibility для вже опублікованих пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть використовувати шлях сумісності:
- відомі private QA entries у `dist/postinstall-inventory.json` можуть указувати на файли, пропущені в tarball;
- `doctor-switch` може пропускати subcase persistence для `gateway install --wrapper`, коли пакет не expose-ить цей flag;
- `update-channel-switch` може prune-ити відсутні `pnpm.patchedDependencies` з tarball-derived fake git fixture і може логувати відсутній persisted `update.channel`;
- відомі приватні записи QA в `dist/postinstall-inventory.json` можуть вказувати на файли, пропущені в tarball;
- `doctor-switch` може пропускати підвипадок persistence `gateway install --wrapper`, коли пакет не надає цей прапорець;
- `update-channel-switch` може прибирати відсутні `pnpm.patchedDependencies` з fake git fixture, отриманої з tarball, і може логувати відсутній збережений `update.channel`;
- plugin smokes можуть читати legacy install-record locations або приймати відсутню marketplace install-record persistence;
- `plugin-update` може дозволяти міграцію config metadata, водночас усе ще вимагаючи, щоб install record і no-reinstall behavior залишалися незмінними.
- `plugin-update` може дозволяти міграцію metadata config, усе ще вимагаючи, щоб install record і no-reinstall behavior лишалися незмінними.
Опублікований пакет `2026.4.26` також може попереджати про local build metadata stamp files, які вже були випущені. Пізніші пакети мають задовольняти сучасні контракти; ті самі умови призводять до failure, а не warn або skip.
Опублікований пакет `2026.4.26` також може попереджати про локальні build metadata stamp files, які вже були відвантажені. Пізніші пакети мають відповідати сучасним контрактам; ті самі умови завершуються помилкою замість попередження або пропуску.
### Приклади
@ -293,111 +301,111 @@ gh workflow run package-acceptance.yml \
-f docker_lanes='install-e2e plugin-update'
```
Під час debugging failed package acceptance run почніть із summary `resolve_package`, щоб підтвердити package source, version і SHA-256. Потім огляньте child run `docker_acceptance` і його Docker artifacts: `.artifacts/docker-tests/**/summary.json`, `failures.json`, lane logs, phase timings і rerun commands. Віддавайте перевагу rerun failed package profile або точних Docker lanes замість rerun повної release validation.
Під час налагодження невдалого запуску package acceptance почніть із підсумку `resolve_package`, щоб підтвердити джерело пакета, версію й SHA-256. Потім перевірте дочірній запуск `docker_acceptance` і його Docker-артефакти: `.artifacts/docker-tests/**/summary.json`, `failures.json`, журнали lane, phase timings і команди повторного запуску. Віддавайте перевагу повторному запуску невдалого package profile або точних Docker lanes замість повторного запуску повної release validation.
## Install smoke
Окремий workflow `Install Smoke` повторно використовує той самий scope script через власний job `preflight`. Він розділяє smoke coverage на `run_fast_install_smoke` і `run_full_install_smoke`.
Окремий workflow `Install Smoke` повторно використовує той самий scope script через власне завдання `preflight`. Він розділяє smoke coverage на `run_fast_install_smoke` і `run_full_install_smoke`.
- **Швидкий шлях** запускається для pull requests, що торкаються Docker/package surfaces, змін bundled plugin package/manifest або core plugin/channel/gateway/Plugin SDK surfaces, які перевіряють Docker smoke jobs. Source-only зміни bundled plugin, test-only edits і docs-only edits не резервують Docker workers. Fast path один раз збирає root Dockerfile image, перевіряє CLI, запускає agents delete shared-workspace CLI smoke, запускає container gateway-network e2e, перевіряє bundled extension build arg і запускає bounded bundled-plugin Docker profile під 240-секундним aggregate command timeout (Docker run кожного scenario обмежено окремо).
- **Повний шлях** зберігає QR package install і installer Docker/update coverage для nightly scheduled runs, manual dispatches, workflow-call release checks і pull requests, які справді торкаються installer/package/Docker surfaces. У full mode install-smoke готує або повторно використовує один target-SHA GHCR root Dockerfile smoke image, а потім запускає QR package install, root Dockerfile/gateway smokes, installer/update smokes і fast bundled-plugin Docker E2E як окремі jobs, щоб installer work не чекав за root image smokes.
- **Швидкий шлях** запускається для pull requests, що торкаються Docker/package surfaces, змін bundled plugin package/manifest або surfaces core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke jobs. Зміни лише у вихідному коді bundled plugin, редагування лише тестів і редагування лише документації не резервують Docker workers. Швидкий шлях один раз збирає root Dockerfile image, перевіряє CLI, запускає agents delete shared-workspace CLI smoke, запускає container gateway-network e2e, перевіряє bundled extension build arg і запускає обмежений bundled-plugin Docker profile під 240-секундним aggregate command timeout (кожен Docker run сценарію обмежено окремо).
- **Повний шлях** зберігає QR package install і installer Docker/update coverage для нічних запланованих запусків, manual dispatches, workflow-call release checks і pull requests, які справді торкаються installer/package/Docker surfaces. У full mode install-smoke готує або повторно використовує один target-SHA GHCR root Dockerfile smoke image, а потім запускає QR package install, root Dockerfile/gateway smokes, installer/update smokes і fast bundled-plugin Docker E2E як окремі завдання, щоб installer work не чекав за root image smokes.
`main` pushes (включно з merge commits) не примушують full path; коли changed-scope logic запитала б full coverage на push, workflow залишає fast Docker smoke і лишає full install smoke для nightly або release validation.
Пуші в `main` (включно з merge commits) не примушують запуск повного шляху; коли логіка changed-scope запитала б повне покриття на push, workflow зберігає fast Docker smoke і залишає full install smoke для nightly або release validation.
Повільний Bun global install image-provider smoke окремо gated через `run_bun_global_install_smoke`. Він запускається за nightly schedule і з workflow release checks, а manual dispatches `Install Smoke` можуть opt into it, але pull requests і `main` pushes — ні. QR і installer Docker tests зберігають власні install-focused Dockerfiles.
Повільний Bun global install image-provider smoke окремо керується `run_bun_global_install_smoke`. Він запускається за нічним розкладом і з workflow release checks, а manual `Install Smoke` dispatches можуть увімкнути його, але pull requests і пуші в `main` — ні. QR і installer Docker tests зберігають власні install-focused Dockerfiles.
## Локальний Docker E2E
`pnpm test:docker:all` попередньо збирає один спільний live-test image, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`:
- bare Node/Git runner для installer/update/plugin-dependency lanes;
- functional image, який встановлює той самий tarball у `/app` для звичайних functionality lanes.
- функціональний образ, який встановлює той самий tarball у `/app` для normal functionality lanes.
Визначення 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 | Кількість слотів хвостового пулу, чутливого до провайдерів. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Обмеження одночасних live-ліній, щоб провайдери не вмикали throttling. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Обмеження одночасних ліній встановлення npm. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Обмеження одночасних багатосервісних ліній. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Інтервал між стартами ліній, щоб уникати штормів створення в Docker daemon; задайте `0`, щоб вимкнути інтервал. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Резервний тайм-аут на лінію (120 хвилин); вибрані live/хвостові лінії використовують жорсткіші обмеження. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` друкує план планувальника без запуску ліній. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Розділений комами точний список ліній; пропускає cleanup smoke, щоб агенти могли відтворити одну збійну лінію. |
| Змінна | Типово | Призначення |
| -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Кількість слотів основного пулу для звичайних ланів. |
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Кількість слотів хвостового пулу, чутливого до провайдерів. |
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Обмеження одночасних live-ланів, щоб провайдери не застосовували throttling. |
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Обмеження одночасних ланів установлення npm. |
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Обмеження одночасних ланів із кількома сервісами. |
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Затримка між стартами ланів, щоб уникнути сплесків створення в Docker daemon; установіть `0` без неї. |
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Резервний тайм-аут для кожного лану (120 хвилин); вибрані live/tail лани використовують жорсткіші обмеження. |
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` виводить план планувальника без запуску ланів. |
| `OPENCLAW_DOCKER_ALL_LANES` | unset | Точний список ланів, розділених комами; пропускає cleanup smoke, щоб агенти могли відтворити один збійний лан. |
Лінія, важча за її ефективне обмеження, все ще може стартувати з порожнього пулу, а потім працює самостійно, доки не звільнить місткість. Локальний агрегат попередньо перевіряє Docker, видаляє застарілі OpenClaw E2E-контейнери, виводить статус активних ліній, зберігає таймінги ліній для впорядкування від найдовших до найкоротших і типово припиняє планувати нові pooled-лінії після першого збою.
Лан, важчий за свій ефективний ліміт, усе ще може стартувати з порожнього пулу, а потім працює сам, доки не звільнить місткість. Локальний агрегатор попередньо перевіряє Docker, видаляє застарілі OpenClaw E2E контейнери, виводить статус активних ланів, зберігає таймінги ланів для впорядкування від найдовших і за замовчуванням припиняє планувати нові лани в пулі після першого збою.
### Багаторазовий live/E2E workflow
Багаторазовий live/E2E workflow запитує `scripts/test-docker-all.mjs --plan-json`, яке покриття package, типу образу, live-образу, лінії та облікових даних потрібне. Потім `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і summaries. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує артефакт package з поточного запуску, або завантажує артефакт package з `package_artifact_run_id`; перевіряє інвентар tarball; збирає й пушить bare/functional GHCR Docker E2E-образи з тегом package digest через кеш Docker-шарів Blacksmith, коли плану потрібні лінії з установленим package; і повторно використовує надані inputs `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні образи з package digest замість перебудови. Pull Docker-образів повторюється з обмеженим 180-секундним тайм-аутом на спробу, щоб завислий registry/cache stream швидко повторювався, а не споживав більшу частину критичного шляху CI.
Багаторазовий live/E2E workflow запитує в `scripts/test-docker-all.mjs --plan-json`, який пакет, тип образу, live-образ, лан і покриття облікових даних потрібні. Потім `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і summary. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує артефакт пакета з поточного запуску, або завантажує артефакт пакета з `package_artifact_run_id`; перевіряє інвентар tarball; збирає й публікує позначені digest пакета bare/functional GHCR Docker E2E образи через кеш Docker-шарів Blacksmith, коли план потребує ланів з установленим пакетом; і повторно використовує надані вхідні значення `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні образи з digest пакета замість повторної збірки. Завантаження Docker-образів повторюються з обмеженим 180-секундним тайм-аутом на спробу, щоб завислий потік registry/cache швидко повторювався, а не займав більшість критичного шляху CI.
### Частини release-path
### Фрагменти release-шляху
Release Docker-покриття запускає менші jobs із chunks з `OPENCLAW_SKIP_DOCKER_BUILD=1`, тож кожен chunk підтягує лише потрібний йому тип образу й виконує кілька ліній через той самий зважений планувальник:
Release Docker coverage запускає менші фрагментовані jobs з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен фрагмент завантажував лише потрібний йому тип образу й виконував кілька ланів через той самий зважений планувальник:
- `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 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` залишаються агрегатними alias для plugin/runtime. Alias лінії `install-e2e` залишається агрегатним manual rerun alias для обох ліній встановлювача провайдера.
Поточні Docker-фрагменти release — це `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` і від `plugins-runtime-install-a` до `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` залишаються агрегованими псевдонімами Plugin/runtime. Псевдонім лану `install-e2e` залишається агрегованим ручним псевдонімом повторного запуску для обох ланів інсталяторів провайдерів.
OpenWebUI входить до `plugins-runtime-services`, коли повне release-path покриття його запитує, і зберігає окремий chunk `openwebui` лише для dispatch, присвячених тільки OpenWebUI. Лінії оновлення bundled-channel повторюють запуск один раз у разі тимчасових npm network failures.
OpenWebUI включається в `plugins-runtime-services`, коли це запитує повне покриття release-path, і зберігає окремий фрагмент `openwebui` лише для dispatch, що стосуються тільки OpenWebUI. Лани оновлення bundled-channel повторюються один раз у разі тимчасових мережевих збоїв npm.
Кожен chunk завантажує `.artifacts/docker-tests/` з logs ліній, таймінгами, `summary.json`, `failures.json`, фазовими таймінгами, JSON плану планувальника, таблицями повільних ліній і командами rerun для кожної лінії. Input workflow `docker_lanes` запускає вибрані лінії проти підготовлених образів замість chunk jobs, що обмежує налагодження збійної лінії одним targeted Docker job і готує, завантажує або повторно використовує артефакт package для цього запуску; якщо вибрана лінія є live Docker-лінією, targeted job локально збирає live-test image для цього rerun. Згенеровані для кожної лінії GitHub-команди rerun включають `package_artifact_run_id`, `package_artifact_name` і inputs підготовлених образів, коли ці значення існують, тож збійна лінія може повторно використати точний package і образи зі збійного запуску.
Кожен фрагмент вивантажує `.artifacts/docker-tests/` із журналами ланів, таймінгами, `summary.json`, `failures.json`, таймінгами фаз, JSON плану планувальника, таблицями повільних ланів і командами повторного запуску для кожного лану. Вхідне значення workflow `docker_lanes` запускає вибрані лани проти підготовлених образів замість chunk jobs, що обмежує debugging збійного лану одним цільовим Docker job і готує, завантажує або повторно використовує артефакт пакета для цього запуску; якщо вибраний лан є live Docker ланом, цільовий job збирає образ live-тесту локально для цього повторного запуску. Згенеровані для кожного лану команди повторного запуску GitHub містять `package_artifact_run_id`, `package_artifact_name` і вхідні значення підготовлених образів, коли ці значення існують, щоб збійний лан міг повторно використати точний пакет і образи зі збійного запуску.
```bash
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
```
Запланований live/E2E workflow щодня запускає повний release-path Docker suite.
Запланований live/E2E workflow щодня запускає повний Docker-набір release-path.
## Попередній реліз Plugin
## Передреліз Plugin
`Plugin Prerelease` є дорожчим покриттям product/package, тому це окремий workflow, який запускається `Full Release Validation` або явним оператором. Звичайні pull requests, pushes у `main` і standalone manual CI dispatches не запускають цей suite. Він балансує тести bundled plugin між вісьмома extension workers; ці extension shard jobs запускають до двох груп plugin config одночасно з одним Vitest worker на групу та більшим Node heap, щоб import-heavy plugin batches не створювали додаткових CI jobs. Release-only Docker prerelease path групує targeted Docker lanes у невеликі групи, щоб не резервувати десятки runners для jobs тривалістю від однієї до трьох хвилин.
`Plugin Prerelease` — це дорожче покриття product/package, тому він є окремим workflow, який запускається `Full Release Validation` або явним оператором. Звичайні pull requests, push у `main` і автономні ручні CI dispatch не запускають цей набір. Він балансує тести bundled Plugin між вісьмома extension workers; ці extension shard jobs запускають до двох груп конфігурації Plugin одночасно з одним Vitest worker на групу та більшим heap Node, щоб насичені import пакети Plugin не створювали додаткових CI jobs. Docker prerelease path лише для release групує цільові Docker-лани в малі групи, щоб не резервувати десятки runners для jobs тривалістю від однієї до трьох хвилин.
## QA Lab
QA Lab має окремі CI-лінії поза основним smart-scoped workflow.
QA Lab має dedicated CI лани поза основним smart-scoped workflow.
- Workflow `Parity gate` запускається для відповідних змін PR і manual dispatch; він збирає приватний QA runtime і порівнює mock GPT-5.5 та Opus 4.6 agentic packs.
- Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і за manual dispatch; він розгортає mock parity gate, live Matrix lane, а також live Telegram і Discord lanes як паралельні jobs. Live jobs використовують середовище `qa-live-shared`, а Telegram/Discord використовують Convex leases.
- Workflow `Parity gate` запускається для відповідних змін PR і ручного dispatch; він збирає приватний QA runtime і порівнює агентні пакети mock GPT-5.5 та Opus 4.6.
- Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через ручний dispatch; він розгалужує mock parity gate, live Matrix лан і live Telegram та Discord лани як паралельні jobs. Live jobs використовують середовище `qa-live-shared`, а Telegram/Discord використовують Convex leases.
Release checks запускають Matrix і Telegram live transport lanes з deterministic mock provider і mock-qualified models (`mock-openai/gpt-5.5` і `mock-openai/gpt-5.5-alt`), щоб contract каналу був ізольований від live model latency і звичайного provider-plugin startup. Live transport gateway вимикає memory search, бо QA parity окремо покриває поведінку memory; provider connectivity покривається окремими suites live model, native provider і Docker provider.
Release checks запускають Matrix і Telegram live transport лани з детермінованим mock провайдером і mock-qualified моделями (`mock-openai/gpt-5.5` і `mock-openai/gpt-5.5-alt`), щоб контракт каналу був ізольований від затримки live-моделі та звичайного запуску provider-plugin. Live transport Gateway вимикає пошук у пам’яті, бо QA parity окремо покриває поведінку пам’яті; підключення провайдерів покривають окремі live model, native provider і Docker provider suites.
Matrix використовує `--profile fast` для scheduled і release gates, додаючи `--fail-fast` лише коли checked-out CLI це підтримує. Типове значення CLI і manual workflow input залишаються `all`; manual dispatch `matrix_profile=all` завжди розбиває повне Matrix coverage на jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`.
Matrix використовує `--profile fast` для scheduled і release gates, додаючи `--fail-fast` лише тоді, коли checkout CLI це підтримує. Типове значення CLI і ручне вхідне значення workflow залишаються `all`; ручний dispatch `matrix_profile=all` завжди шардує повне Matrix coverage на jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`.
`OpenClaw Release Checks` також запускає release-critical QA Lab lanes перед approval релізу; його QA parity gate запускає candidate і baseline packs як паралельні lane jobs, а потім завантажує обидва artifacts у невеликий report job для фінального parity comparison.
`OpenClaw Release Checks` також запускає release-critical QA Lab лани перед схваленням release; його QA parity gate запускає candidate і baseline packs як паралельні lane jobs, а потім завантажує обидва артефакти в малий report job для фінального parity comparison.
Не ставте PR landing path за `Parity gate`, якщо зміна насправді не зачіпає QA runtime, model-pack parity або surface, яким володіє parity workflow. Для звичайних виправлень channel, config, docs або unit-test розглядайте це як optional signal і дотримуйтеся scoped CI/check evidence.
Не ставте PR landing path за `Parity gate`, якщо зміна фактично не торкається QA runtime, model-pack parity або поверхні, якою володіє parity workflow. Для звичайних виправлень каналів, конфігурації, документації або unit tests вважайте це необов’язковим сигналом і дотримуйтеся доказів scoped CI/check.
## CodeQL
Workflow `CodeQL` навмисно є вузьким first-pass security scanner, а не повним sweep репозиторію. Daily, manual і non-draft pull request guard runs сканують Actions workflow code плюс JavaScript/TypeScript surfaces із найвищим ризиком за допомогою high-confidence security queries, відфільтрованих до high/critical `security-severity`.
Workflow `CodeQL` навмисно є вузьким security scanner першого проходу, а не повним sweep репозиторію. Daily, manual і non-draft pull request guard runs сканують Actions workflow code плюс найризиковіші JavaScript/TypeScript поверхні з 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 defaults.
Pull request guard залишається легким: він стартує лише для змін у `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` або `src`, і запускає ту саму high-confidence security matrix, що й scheduled workflow. Android і macOS CodeQL не входять до PR defaults.
### Категорії безпеки
| Категорія | Surface |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Auth, secrets, sandbox, cron і gateway baseline |
| `/codeql-security-high/channel-runtime-boundary` | Core channel implementation contracts плюс channel plugin runtime, gateway, Plugin SDK, secrets, audit touchpoints |
| `/codeql-security-high/network-ssrf-boundary` | Core SSRF, IP parsing, network guard, web-fetch і Plugin SDK SSRF policy surfaces |
| `/codeql-security-high/mcp-process-tool-boundary` | MCP servers, process execution helpers, outbound delivery і agent tool-execution gates |
| `/codeql-security-high/plugin-trust-boundary` | Plugin install, loader, manifest, registry, package-manager install, source-loading і trust surfaces package contract Plugin SDK |
| Категорія | Поверхня |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-security-high/core-auth-secrets` | Auth, secrets, sandbox, cron і gateway baseline |
| `/codeql-security-high/channel-runtime-boundary` | Контракти реалізації core channel плюс channel Plugin runtime, Gateway, Plugin SDK, secrets, audit touchpoints |
| `/codeql-security-high/network-ssrf-boundary` | Core SSRF, IP parsing, network guard, web-fetch і поверхні SSRF policy Plugin SDK |
| `/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 і trust surfaces контракту package Plugin SDK |
### Platform-specific security shards
### Платформоспецифічні security shards
- `CodeQL Android Critical Security` — scheduled Android security shard. Збирає Android app вручну для CodeQL на найменшому Blacksmith Linux runner, прийнятому workflow sanity. Завантажує під `/codeql-critical-security/android`.
- `CodeQL macOS Critical Security` — weekly/manual macOS security shard. Збирає macOS app вручну для CodeQL на Blacksmith macOS, відфільтровує dependency build results із завантаженого SARIF і завантажує під `/codeql-critical-security/macos`. Утримується поза daily defaults, бо macOS build домінує runtime навіть коли clean.
- `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 із вивантаженого SARIF і вивантажує під `/codeql-critical-security/macos`. Залишається поза daily defaults, бо macOS build домінує runtime навіть коли clean.
### Категорії 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` — відповідний 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.
Manual dispatch приймає:
@ -405,40 +413,40 @@ Manual dispatch приймає:
profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary
```
Вузькі профілі є навчальними/ітераційними хуками для запуску одного якісного сегмента ізольовано.
Вузькі профілі є навчальними/ітераційними hooks для запуску одного якісного shard ізольовано.
| Категорія | Поверхня |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/codeql-critical-quality/core-auth-secrets` | Код межі безпеки автентифікації, секретів, пісочниці, Cron і Gateway |
| `/codeql-critical-quality/config-boundary` | Схема конфігурації, міграція, нормалізація та контракти введення-виведення |
| `/codeql-critical-quality/gateway-runtime-boundary` | Схеми протоколу Gateway і контракти методів сервера |
| `/codeql-critical-quality/channel-runtime-boundary` | Контракти реалізації основного каналу та вбудованого канального plugin |
| `/codeql-critical-quality/agent-runtime-boundary` | Виконання команд, диспетчеризація моделей/провайдерів, диспетчеризація автовідповідей і черги, а також runtime-контракти площини керування ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-сервери та мости інструментів, допоміжні засоби нагляду за процесами й контракти вихідної доставки |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK хоста пам’яті, runtime-фасади пам’яті, псевдоніми SDK пам’яті Plugin, зв’язувальний код активації runtime пам’яті та команди doctor для пам’яті |
| `/codeql-critical-quality/session-diagnostics-boundary` | Внутрішня логіка черги відповідей, черги доставки сеансів, допоміжні засоби прив’язування/доставки вихідних сеансів, поверхні діагностичних подій/пакетів журналів і CLI-контракти doctor для сеансів |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Диспетчеризація вхідних відповідей Plugin SDK, допоміжні засоби payload/нарізання/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, розуміння медіа, image-generation і media-generation |
| `/codeql-critical-quality/plugin-boundary` | Контракти завантажувача, реєстру, публічної поверхні та entrypoint Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Опублікований package-side вихідний код Plugin SDK і допоміжні засоби контрактів пакетів plugin |
| Категорія | Поверхня |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/codeql-critical-quality/core-auth-secrets` | Код межі безпеки автентифікації, секретів, пісочниці, Cron і Gateway |
| `/codeql-critical-quality/config-boundary` | Схема конфігурації, міграція, нормалізація та контракти IO |
| `/codeql-critical-quality/gateway-runtime-boundary` | Схеми протоколу Gateway і контракти методів сервера |
| `/codeql-critical-quality/channel-runtime-boundary` | Контракти реалізації каналів ядра та вбудованих Plugin каналів |
| `/codeql-critical-quality/agent-runtime-boundary` | Виконання команд, диспетчеризація моделей/провайдерів, диспетчеризація й черги автовідповідей, а також runtime-контракти control plane ACP |
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Сервери MCP і мости інструментів, помічники нагляду за процесами та контракти вихідної доставки |
| `/codeql-critical-quality/memory-runtime-boundary` | SDK хоста пам'яті, runtime-фасади пам'яті, псевдоніми Plugin SDK для пам'яті, зв'язувальний код runtime-активації пам'яті та команди doctor для пам'яті |
| `/codeql-critical-quality/session-diagnostics-boundary` | Внутрішня логіка черги відповідей, черги доставки сеансів, помічники прив'язування/доставки вихідних сеансів, поверхні діагностичних подій/пакетів логів і CLI-контракти doctor для сеансів |
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Диспетчеризація вхідних відповідей Plugin SDK, помічники payload/chunking/runtime для відповідей, параметри відповідей каналів, черги доставки та помічники прив'язування сеансів/потоків |
| `/codeql-critical-quality/provider-runtime-boundary` | Нормалізація каталогу моделей, автентифікація та виявлення провайдерів, реєстрація runtime провайдерів, defaults/каталоги провайдерів і реєстри web/search/fetch/embedding |
| `/codeql-critical-quality/ui-control-plane` | Початкове завантаження Control UI, локальне збереження, control flows Gateway і runtime-контракти control plane завдань |
| `/codeql-critical-quality/web-media-runtime-boundary` | Контракти runtime для core web fetch/search, media IO, розуміння медіа, генерації зображень і генерації медіа |
| `/codeql-critical-quality/plugin-boundary` | Контракти завантажувача, реєстру, публічної поверхні та entrypoint Plugin SDK |
| `/codeql-critical-quality/plugin-sdk-package-contract` | Опублікований package-side вихідний код Plugin SDK і помічники контракту пакета Plugin |
Якість залишається окремо від безпеки, щоб знахідки якості можна було планувати, вимірювати, вимикати або розширювати без затемнення сигналу безпеки. Розширення CodeQL для Swift, Python і вбудованих plugin слід додавати назад як scoped або sharded подальшу роботу лише після того, як вузькі профілі матимуть стабільний runtime і сигнал.
Якість залишається окремою від безпеки, щоб findings якості можна було планувати, вимірювати, вимикати або розширювати без затемнення сигналу безпеки. Розширення CodeQL для Swift, Python і вбудованих Plugin слід додавати назад як scoped або sharded follow-up роботу лише після того, як вузькі профілі матимуть стабільні runtime і сигнал.
## Робочі процеси обслуговування
### Docs Agent
Робочий процес `Docs Agent` — це подієво-керована лінія обслуговування Codex для підтримання наявної документації в узгодженості з нещодавно доданими змінами. Він не має чистого розкладу: успішний CI-запуск push не від бота на `main` може його запустити, а manual dispatch може запустити його напряму. Виклики workflow-run пропускаються, коли `main` уже просунувся далі або коли за останню годину було створено інший непропущений запуск Docs Agent. Коли він запускається, він переглядає діапазон комітів від попереднього непропущеного source SHA Docs Agent до поточного `main`, тож один погодинний запуск може покрити всі зміни main, накопичені з часу останнього проходу документації.
Workflow `Docs Agent` — це подієво-керована lane обслуговування Codex для підтримання наявної документації узгодженою з нещодавно злитими змінами. Він не має чистого розкладу: успішний CI run після non-bot push на `main` може його запустити, а manual dispatch може запустити його напряму. Виклики workflow-run пропускаються, коли `main` уже просунувся далі або коли інший non-skipped run Docs Agent було створено протягом останньої години. Коли він виконується, він переглядає діапазон комітів від попереднього non-skipped source SHA Docs Agent до поточного `main`, тож один погодинний run може охопити всі зміни main, накопичені від останнього проходу документації.
### Test Performance Agent
Робочий процес `Test Performance Agent` — це подієво-керована лінія обслуговування Codex для повільних тестів. Він не має чистого розкладу: успішний CI-запуск push не від бота на `main` може його запустити, але він пропускається, якщо інший виклик workflow-run уже виконувався або виконується цього UTC-дня. Manual dispatch обходить цей щоденний шлюз активності. Лінія збирає згрупований звіт продуктивності Vitest для всього набору, дозволяє Codex робити лише невеликі виправлення продуктивності тестів зі збереженням покриття замість широких рефакторингів, потім повторно запускає звіт для всього набору й відхиляє зміни, які зменшують базову кількість успішних тестів. Якщо в базовому стані є тести, що падають, Codex може виправляти лише очевидні збої, а повний звіт після агента для всього набору має пройти перед тим, як щось буде закомічено. Коли `main` просувається до того, як bot push потрапляє в репозиторій, лінія ребейзить перевірений патч, повторно запускає `pnpm check:changed` і повторює push; конфліктні застарілі патчі пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму позицію безпеки drop-sudo, що й docs agent.
Workflow `Test Performance Agent` — це подієво-керована lane обслуговування Codex для повільних тестів. Він не має чистого розкладу: успішний CI run після non-bot push на `main` може його запустити, але він пропускається, якщо інший виклик workflow-run уже виконувався або виконується цього UTC-дня. Manual dispatch обходить цей щоденний activity gate. Lane будує згрупований performance report Vitest для всього suite, дозволяє Codex робити лише малі виправлення продуктивності тестів зі збереженням покриття замість широких рефакторингів, потім повторно запускає full-suite report і відхиляє зміни, які зменшують базову кількість прохідних тестів. Якщо baseline має failing tests, Codex може виправляти лише очевидні failures, а full-suite report після агента має пройти, перш ніж щось буде закомічено. Коли `main` просувається до того, як bot push буде злитий, lane rebase-ить перевірений patch, повторно запускає `pnpm check:changed` і повторює push; конфліктні застарілі patches пропускаються. Він використовує GitHub-hosted Ubuntu, щоб action Codex міг зберегти ту саму drop-sudo safety posture, що й docs agent.
### Дублікати PR після злиття
### Дублікати PR після Merge
Робочий процес `Duplicate PRs After Merge` — це ручний workflow для мейнтейнерів для очищення дублікатів після land. За замовчуванням він працює в dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед змінами в GitHub він перевіряє, що landed PR злито і що кожен дублікат має або спільне referenced issue, або перетин змінених hunks.
Workflow `Duplicate PRs After Merge` — це manual maintainer workflow для очищення дублікатів після land. За замовчуванням він працює як dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед мутацією GitHub він перевіряє, що landed PR змерджено і що кожен дублікат має або спільне referenced issue, або overlapping changed hunks.
```bash
gh workflow run duplicate-after-merge.yml \
@ -447,29 +455,29 @@ gh workflow run duplicate-after-merge.yml \
-f apply=true
```
## Локальні check-gates і маршрутизація змін
## Локальні check gates і changed routing
Логіка локальних changed-lane розміщена в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний check gate суворіший щодо архітектурних меж, ніж широкий scope CI-платформи:
Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний check gate суворіший щодо архітектурних меж, ніж широка область CI platform:
- зміни 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 extension, бо extensions залежать від цих core contracts (Vitest extension sweeps залишаються явною тестовою роботою);
- version bumps лише release metadata запускають цільові перевірки version/config/root-dependency;
- production-зміни ядра запускають typecheck core prod і core test плюс core lint/guards;
- test-only зміни ядра запускають лише typecheck core test плюс core lint;
- production-зміни Plugin запускають typecheck extension prod і extension test плюс extension lint;
- test-only зміни Plugin запускають typecheck extension test плюс extension lint;
- зміни публічного Plugin SDK або plugin-contract розширюються до typecheck Plugin, бо Plugin залежать від цих core-контрактів (Vitest extension sweeps залишаються явною тестовою роботою);
- release metadata-only version bumps запускають цільові перевірки версії/конфігурації/root-dependency;
- невідомі зміни root/config fail safe до всіх check lanes.
Локальна маршрутизація changed-test розміщена в `scripts/test-projects.test-support.mjs` і навмисно дешевша за `check:changed`: прямі редагування тестів запускають самі себе, редагування source віддають перевагу явним mappings, потім sibling tests і import-graph dependents. Спільна конфігурація доставки group-room є одним із явних mappings: зміни до group visible-reply config, source reply delivery mode або message-tool system prompt проходять через core reply tests плюс регресії доставки Discord і Slack, щоб зміна спільного default падала до першого PR push. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли зміна достатньо harness-wide, що дешевий mapped set не є надійним proxy.
Локальний changed-test routing міститься в `scripts/test-projects.test-support.mjs` і навмисно дешевший за `check:changed`: прямі правки тестів запускають самі себе, правки вихідного коду спершу віддають перевагу явним mappings, потім sibling tests і import-graph dependents. Shared group-room delivery config є одним із явних mappings: зміни group visible-reply config, source reply delivery mode або system prompt message-tool проходять через core reply tests плюс регресії доставки Discord і Slack, щоб спільна зміна default упала до першого PR push. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли зміна настільки harness-wide, що дешевий mapped set не є надійним proxy.
## Валідація Testbox
Запускайте Testbox з кореня репозиторію й віддавайте перевагу свіжому прогрітому box для широкого доказу. Перед тим як витрачати повільний gate на box, який був повторно використаний, протермінований або щойно повідомив про несподівано великий sync, спочатку запустіть `pnpm testbox:sanity` всередині box.
Запускайте Testbox із кореня репозиторію та віддавайте перевагу свіжому warmed box для широкого proof. Перед витрачанням повільного gate на box, який був reused, expired або щойно повідомив про неочікувано великий sync, спершу запустіть `pnpm testbox:sanity` всередині box.
Sanity check швидко падає, коли потрібні root files, як-от `pnpm-lock.yaml`, зникли або коли `git status --short` показує щонайменше 200 tracked deletions. Зазвичай це означає, що remote sync state не є надійною копією PR; зупиніть цей box і прогрійте свіжий замість налагодження збою product test. Для навмисних PR із великими видаленнями задайте `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього sanity run.
Sanity check швидко падає, коли required root files, як-от `pnpm-lock.yaml`, зникли або коли `git status --short` показує щонайменше 200 tracked deletions. Зазвичай це означає, що remote sync state не є надійною копією PR; зупиніть цей box і warm-ніть свіжий замість налагодження 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, який залишається у фазі sync понад п'ять хвилин без post-sync output. Встановіть `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, щоб вимкнути цей guard, або використайте більше значення в мілісекундах для незвично великих локальних diff.
Crabbox — це repo-owned другий шлях remote-box для Linux proof, коли Blacksmith недоступний або коли власна хмарна потужність є кращою. Прогрійте box, hydrate його через project workflow, а потім запускайте команди через Crabbox CLI:
Crabbox — це repo-owned другий remote-box path для Linux proof, коли Blacksmith недоступний або коли бажаніша owned cloud capacity. Warm-ніть box, hydrate-ніть його через project workflow, потім запускайте команди через Crabbox CLI:
```bash
pnpm crabbox:warmup -- --idle-timeout 90m
@ -478,9 +486,9 @@ pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed
pnpm crabbox:stop -- <cbx_id>
```
`.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 <cbx_id>` source.
`.crabbox.yaml` володіє defaults провайдера, 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 <cbx_id>` source-ять.
## Пов’язане
## Пов'язане
- [Огляд встановлення](/uk/install)
- [Канали розробки](/uk/install/development-channels)

63
docs/uk/diagnostics/flags.md
View File

@ -1,25 +1,25 @@
---
read_when:
- Вам потрібні цільові журнали налагодження без підвищення глобальних рівнів журналювання
- Потрібно зібрати журнали певної підсистеми для служби підтримки
- Потрібні точкові журнали налагодження без підвищення глобальних рівнів журналювання
- Потрібно зібрати журнали конкретної підсистеми для служби підтримки
summary: Прапорці діагностики для цільових журналів налагодження
title: Діагностичні прапорці
title: Прапорці діагностики
x-i18n:
generated_at: "2026-04-29T18:57:58Z"
generated_at: "2026-05-02T06:53:26Z"
model: gpt-5.5
provider: openai
source_hash: 486051e54c456dedcae5dce59e253add3554d8417660bfc97a75d21fa5fdd6f5
source_hash: 1d0ff92d45cf1c5a12a7103ba5b97d656a55a13a7a4f2e86e26ba3a9cfae7687
source_path: diagnostics/flags.md
workflow: 16
---
Прапорці діагностики дають змогу ввімкнути цільові журнали налагодження, не вмикаючи детальне журналювання всюди. Прапорці вмикаються явно й не мають ефекту, якщо підсистема їх не перевіряє.
Прапорці діагностики дають змогу вмикати цільові журнали налагодження без увімкнення докладного журналювання всюди. Прапорці вмикаються явно й не мають ефекту, якщо підсистема їх не перевіряє.
## Як це працює
- Прапорці — це рядки (без урахування регістру).
- Ви можете ввімкнути прапорці в конфігурації або через перевизначення змінною середовища.
- Підтримуються символи підстановки:
- Ви можете ввімкнути прапорці в конфігурації або через перевизначення env.
- Підтримуються шаблони:
- `telegram.*` відповідає `telegram.http`
- `*` вмикає всі прапорці
@ -38,14 +38,14 @@ x-i18n:
```json
{
"diagnostics": {
"flags": ["telegram.http", "gateway.*"]
"flags": ["telegram.http", "brave.http", "gateway.*"]
}
}
```
Перезапустіть Gateway після зміни прапорців.
Перезапустіть gateway після зміни прапорців.
## Перевизначення змінною середовища (одноразово)
## Перевизначення env (одноразове)
```bash
OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload
@ -60,7 +60,7 @@ OPENCLAW_DIAGNOSTICS=0
## Артефакти часової шкали
Прапорець `timeline` записує структуровані події часу запуску й виконання для
зовнішніх засобів QA:
зовнішніх QA-стендів:
```bash
OPENCLAW_DIAGNOSTICS=timeline \
@ -80,31 +80,31 @@ openclaw gateway run
Шлях до файлу часової шкали все одно береться з
`OPENCLAW_DIAGNOSTICS_TIMELINE_PATH`. Коли `timeline` увімкнено лише з
конфігурації, найраніші інтервали завантаження конфігурації не створюються, бо OpenClaw ще
не прочитав конфігурацію; подальші інтервали запуску використовують прапорець конфігурації.
конфігурації, найраніші проміжки завантаження конфігурації не виводяться, тому що OpenClaw ще
не прочитав конфігурацію; наступні проміжки запуску використовують прапорець із конфігурації.
`OPENCLAW_DIAGNOSTICS=1`, `OPENCLAW_DIAGNOSTICS=all` і
`OPENCLAW_DIAGNOSTICS=*` також вмикають часову шкалу, бо вони вмикають кожен
прапорець діагностики. Надавайте перевагу `timeline`, коли вам потрібен лише
артефакт часу у форматі JSONL.
`OPENCLAW_DIAGNOSTICS=*` також вмикають часову шкалу, оскільки вони вмикають кожен
прапорець діагностики. Використовуйте `timeline`, коли вам потрібен лише JSONL-артефакт
часових вимірювань.
Записи часової шкали використовують оболонку `openclaw.diagnostics.v1`. Події можуть містити
ідентифікатори процесів, назви фаз, назви інтервалів, тривалість, ідентифікатори Plugin, кількість залежностей,
вибірки затримки циклу подій, назви операцій провайдера, стан завершення дочірнього процесу
та назви/повідомлення помилок запуску. Розглядайте файли часової шкали як локальні артефакти
діагностики; переглядайте їх перед поширенням за межами вашого комп’ютера.
ідентифікатори процесів, назви фаз, назви проміжків, тривалості, ідентифікатори plugin, кількість залежностей,
зразки затримки циклу подій, назви операцій провайдера, стан завершення дочірнього процесу,
а також назви/повідомлення помилок запуску. Розглядайте файли часової шкали як локальні
діагностичні артефакти; переглядайте їх перед поширенням за межами вашого комп’ютера.
## Куди потрапляють журнали
Прапорці записують журнали у стандартний файл журналу діагностики. Типово:
Прапорці виводять журнали у стандартний файл журналу діагностики. За замовчуванням:
```
/tmp/openclaw/openclaw-YYYY-MM-DD.log
```
Якщо ви задали `logging.file`, використовуйте цей шлях натомість. Журнали мають формат JSONL (один об’єкт JSON на рядок). Редагування чутливих даних усе ще застосовується на основі `logging.redactSensitive`.
Якщо ви встановили `logging.file`, використовуйте цей шлях натомість. Журнали мають формат JSONL (один JSON-об’єкт на рядок). Редагування чутливих даних усе ще застосовується на основі `logging.redactSensitive`.
## Витяг журналів
## Витягування журналів
Виберіть найновіший файл журналу:
@ -112,23 +112,30 @@ openclaw gateway run
ls -t /tmp/openclaw/openclaw-*.log | head -n 1
```
Відфільтруйте діагностику HTTP для Telegram:
Фільтр для діагностики Telegram HTTP:
```bash
rg "telegram http error" /tmp/openclaw/openclaw-*.log
```
Або відстежуйте журнал під час відтворення:
Фільтр для діагностики Brave Search HTTP:
```bash
rg "brave http" /tmp/openclaw/openclaw-*.log
```
Або переглядайте хвіст під час відтворення:
```bash
tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"
```
Для віддалених Gateway також можна використовувати `openclaw logs --follow` (див. [/cli/logs](/uk/cli/logs)).
Для віддалених gateway також можна використовувати `openclaw logs --follow` (див. [/cli/logs](/uk/cli/logs)).
## Примітки
- Якщо `logging.level` встановлено вище за `warn`, ці журнали можуть бути придушені. Типове значення `info` підходить.
- Якщо `logging.level` встановлено вище за `warn`, ці журнали можуть бути приглушені. Значення `info` за замовчуванням підходить.
- `brave.http` журналює URL-адреси/параметри запиту Brave Search, статус/час відповіді та події влучання/промаху/запису кешу. Він не журналює API-ключі або тіла відповідей, але пошукові запити можуть бути чутливими.
- Прапорці безпечно залишати ввімкненими; вони впливають лише на обсяг журналів для конкретної підсистеми.
- Використовуйте [/logging](/uk/logging), щоб змінити призначення журналів, рівні та редагування чутливих даних.

661
docs/uk/reference/RELEASING.md
View File

@ -2,260 +2,267 @@
read_when:
- Пошук визначень публічних каналів випуску
- Запуск перевірки релізу або приймання пакета
- Шукаєте правила іменування версій і періодичність випусків
summary: Релізні лінії, контрольний список оператора, бокси валідації, іменування версій і ритм
- Шукаєте іменування версій і періодичність випусків
summary: Лінії релізів, контрольний список оператора, середовища валідації, іменування версій і періодичність
title: Політика випусків
x-i18n:
generated_at: "2026-05-02T06:28:27Z"
generated_at: "2026-05-02T06:53:33Z"
model: gpt-5.5
provider: openai
source_hash: 97554cdf9ac79080a7b371afe0a0c8288a6ca53729abb42401399dca24a12067
source_hash: ce52c9144de3c8b914954db64f6ca5b2196edbbdcc7385984235a39c208bb59e
source_path: reference/RELEASING.md
workflow: 16
---
OpenClaw має три публічні гілки релізів:
OpenClaw має три публічні канали випусків:
- stable: релізи з тегами, які за замовчуванням публікуються в npm `beta`, або в npm `latest`, коли це явно запитано
- beta: теги попередніх релізів, які публікуються в npm `beta`
- dev: рухома вершина `main`
- стабільний: теговані випуски, які типово публікуються до npm `beta` або до npm `latest` за явним запитом
- бета: передрелізні теги, які публікуються до npm `beta`
- розробницький: рухома вершина `main`
## Назви версій
- Версія стабільного релізу: `YYYY.M.D`
- Версія стабільного випуску: `YYYY.M.D`
- Git-тег: `vYYYY.M.D`
- Версія стабільного коригувального релізу: `YYYY.M.D-N`
- Версія корекційного стабільного випуску: `YYYY.M.D-N`
- Git-тег: `vYYYY.M.D-N`
- Версія beta-попереднього релізу: `YYYY.M.D-beta.N`
- Версія бета-передрелізу: `YYYY.M.D-beta.N`
- Git-тег: `vYYYY.M.D-beta.N`
- Не додавайте нулі на початку місяця або дня
- `latest` означає поточний підвищений стабільний реліз npm
- `beta` означає поточну ціль установлення beta
- Стабільні та стабільні коригувальні релізи за замовчуванням публікуються в npm `beta`; оператори релізу можуть явно вибрати `latest` або пізніше підвищити перевірену збірку beta
- Кожен стабільний реліз OpenClaw постачає npm-пакет і застосунок macOS разом;
beta-релізи зазвичай спочатку перевіряють і публікують шлях npm/package, а
складання/підписування/нотаризацію застосунку Mac залишають для стабільних релізів, якщо це явно не запитано
- Не додавайте початкові нулі до місяця або дня
- `latest` означає поточний просунутий стабільний npm-випуск
- `beta` означає поточну ціль встановлення бета-версії
- Стабільні й корекційні стабільні випуски типово публікуються до npm `beta`; оператори випуску можуть явно вибрати `latest` або пізніше просунути перевірену бета-збірку
- Кожен стабільний випуск OpenClaw постачається разом із npm-пакетом і застосунком macOS;
бета-випуски зазвичай спершу перевіряють і публікують шлях npm/пакета, а
збирання/підписування/нотаризацію застосунку для Mac лишають для стабільного випуску, якщо немає явного запиту
## Періодичність релізів
## Періодичність випусків
- Релізи рухаються спочатку через beta
- Стабільний реліз виходить лише після перевірки останньої beta
- Мейнтейнери зазвичай створюють релізи з гілки `release/YYYY.M.D`, створеної
з поточного `main`, щоб перевірка релізу та виправлення не блокували нову
- Випуски рухаються спершу через бета-канал
- Стабільний випуск з’являється лише після валідації останньої бета-версії
- Супровідники зазвичай готують випуски з гілки `release/YYYY.M.D`, створеної
з поточного `main`, щоб валідація випуску й виправлення не блокували нову
розробку в `main`
- Якщо beta-тег уже надіслано або опубліковано і він потребує виправлення, мейнтейнери створюють
наступний тег `-beta.N` замість видалення або повторного створення старого beta-тега
- Детальна процедура релізу, затвердження, облікові дані та нотатки щодо відновлення
доступні лише мейнтейнерам
- Якщо бета-тег уже було відправлено або опубліковано й він потребує виправлення, супровідники створюють
наступний тег `-beta.N` замість видалення або повторного створення старого бета-тега
- Докладна процедура випуску, схвалення, облікові дані та нотатки щодо відновлення
доступні лише супровідникам
## Контрольний список оператора релізу
## Контрольний список оператора випуску
Цей контрольний список є публічною формою процесу релізу. Приватні облікові дані,
підписування, нотаризація, відновлення dist-tag і деталі екстреного відкату залишаються в
runbook релізів лише для мейнтейнерів.
Цей контрольний список описує публічну форму потоку випуску. Приватні облікові дані,
підписування, нотаризація, відновлення dist-tag і деталі аварійного відкату залишаються в
інструкції з випуску лише для супровідників.
1. Почніть із поточного `main`: підтягніть останні зміни, підтвердьте, що цільовий коміт надіслано,
і підтвердьте, що поточний CI для `main` достатньо зелений, щоб створювати від нього гілку.
1. Почніть із поточного `main`: підтягніть останні зміни, підтвердьте, що цільовий коміт відправлено,
і переконайтеся, що поточний CI для `main` достатньо зелений, щоб створювати від нього гілку.
2. Перепишіть верхній розділ `CHANGELOG.md` на основі реальної історії комітів за допомогою
`/changelog`, залиште записи орієнтованими на користувача, закомітьте його, надішліть його, і виконайте rebase/pull
ще раз перед створенням гілки.
3. Перегляньте записи сумісності релізу в
`/changelog`, залиште записи орієнтованими на користувачів, закомітьте його, відправте й ще раз виконайте rebase/pull
перед створенням гілки.
3. Перегляньте записи сумісності випуску в
`src/plugins/compat/registry.ts` і
`src/commands/doctor/shared/deprecation-compat.ts`. Видаляйте застарілу
сумісність лише тоді, коли шлях оновлення залишається покритим, або зафіксуйте, чому вона
навмисно зберігається.
4. Створіть `release/YYYY.M.D` з поточного `main`; не виконуйте звичайну роботу над релізом
`src/commands/doctor/shared/deprecation-compat.ts`. Видаляйте прострочену
сумісність лише тоді, коли шлях оновлення лишається покритим, або зафіксуйте, чому її
навмисно збережено.
4. Створіть `release/YYYY.M.D` з поточного `main`; не виконуйте звичайну роботу над випуском
безпосередньо в `main`.
5. Підвищте кожне потрібне місце версії для запланованого тега, запустіть
`pnpm plugins:sync`, щоб пакети Plugin, придатні для публікації, мали спільну версію релізу
та метадані сумісності, потім запустіть локальну детерміновану попередню перевірку:
5. Оновіть усі потрібні місця з версіями для запланованого тегу, виконайте
`pnpm plugins:sync`, щоб публіковні пакети Plugin мали спільну версію випуску
й метадані сумісності, а потім запустіть локальну детерміновану попередню перевірку:
`pnpm check:test-types`, `pnpm check:architecture`,
`pnpm build && pnpm ui:build`, `pnpm plugins:sync:check` і
`pnpm release:check`.
6. Запустіть `OpenClaw NPM Release` з `preflight_only=true`. Поки тег не існує,
повний 40-символьний SHA гілки релізу дозволено для попередньої перевірки лише з метою валідації.
6. Запустіть `OpenClaw NPM Release` з `preflight_only=true`. До існування тегу
для валідаційної попередньої перевірки дозволено повний 40-символьний SHA гілки випуску.
Збережіть успішний `preflight_run_id`.
7. Запустіть усі передрелізні тести через `Full Release Validation` для
гілки релізу, тега або повного SHA коміту. Це єдина ручна точка входу
для чотирьох великих тестових середовищ релізу: Vitest, Docker, QA Lab і Package.
8. Якщо перевірка не проходить, виправте проблему в гілці релізу та повторно запустіть найменший невдалий
файл, гілку, job workflow, профіль пакета, провайдера або allowlist моделі, що
доводить виправлення. Повторно запускайте повну umbrella-перевірку лише тоді, коли змінена поверхня робить
гілки випуску, тегу або повного SHA коміту. Це єдина ручна точка входу
для чотирьох великих тестових середовищ випуску: Vitest, Docker, QA Lab і Package.
8. Якщо валідація не пройшла, виправте в гілці випуску й повторно запустіть найменший невдалий
файл, канал, завдання workflow, профіль пакета, провайдера або allowlist моделей, який
доводить виправлення. Повторно запускайте повну парасольку лише тоді, коли змінена поверхня робить
попередні докази застарілими.
9. Для beta поставте тег `vYYYY.M.D-beta.N`, потім запустіть `OpenClaw Release Publish` з
9. Для бета-версії створіть тег `vYYYY.M.D-beta.N`, а потім запустіть `OpenClaw Release Publish` з
відповідної гілки `release/YYYY.M.D`. Він перевіряє `pnpm plugins:sync:check`,
спочатку публікує всі пакети Plugin, придатні для публікації, в npm, другим кроком публікує той самий
набір у ClawHub, а потім підвищує підготовлений артефакт попередньої перевірки OpenClaw npm
з dist-tag `beta`. Після публікації запустіть post-publish package
acceptance для опублікованого пакета `openclaw@YYYY.M.D-beta.N` або `openclaw@beta`.
Якщо надіслана або опублікована beta потребує виправлення, створіть наступний `-beta.N`;
не видаляйте і не переписуйте стару beta.
10. Для стабільного релізу продовжуйте лише після того, як перевірена beta або release candidate має
потрібні докази валідації. Публікація стабільного npm також проходить через
спершу публікує всі публіковні пакети Plugin до npm, потім публікує той самий
набір до ClawHub, а далі просуває підготовлений артефакт попередньої перевірки npm для OpenClaw
з dist-tag `beta`. Після публікації запустіть post-publish приймання пакета
для опублікованого пакета `openclaw@YYYY.M.D-beta.N` або `openclaw@beta`.
Якщо відправлена або опублікована бета-версія потребує виправлення, створіть наступний `-beta.N`;
не видаляйте й не переписуйте стару бета-версію.
10. Для стабільного випуску продовжуйте лише після того, як перевірена бета-версія або release candidate має
потрібні докази валідації. Публікація стабільної версії до npm також проходить через
`OpenClaw Release Publish`, повторно використовуючи успішний артефакт попередньої перевірки через
`preflight_run_id`; готовність стабільного релізу macOS також потребує
упакованих `.zip`, `.dmg`, `.dSYM.zip` і оновленого `appcast.xml` у `main`.
11. Після публікації запустіть npm post-publish verifier, необов’язковий окремий
published-npm Telegram E2E, коли вам потрібен post-publish доказ каналу,
підвищення dist-tag за потреби, нотатки GitHub release/prerelease з
повного відповідного розділу `CHANGELOG.md` і кроки оголошення релізу.
`preflight_run_id`; готовність стабільного випуску для macOS також потребує
запакованих `.zip`, `.dmg`, `.dSYM.zip` і оновленого `appcast.xml` у `main`.
11. Після публікації запустіть npm post-publish verifier, за потреби окремий
опублікований-npm Telegram E2E, коли потрібен post-publish доказ каналу,
просування dist-tag за потреби, нотатки GitHub release/prerelease з
повного відповідного розділу `CHANGELOG.md` і кроки оголошення випуску.
## Попередня перевірка релізу
## Попередня перевірка випуску
- Запустіть `pnpm check:test-types` перед передрелізною перевіркою, щоб тестовий TypeScript залишався
покритим поза швидшим локальним gate `pnpm check`
- Запустіть `pnpm check:architecture` перед передрелізною перевіркою, щоб ширші перевірки циклів
імпорту та меж архітектури були зеленими поза швидшим локальним gate
- Запустіть `pnpm check:architecture` перед передрелізною перевіркою, щоб ширші перевірки
циклів імпорту та архітектурних меж були зеленими поза швидшим локальним gate
- Запустіть `pnpm build && pnpm ui:build` перед `pnpm release:check`, щоб очікувані
релізні артефакти `dist/*` і bundle Control UI існували для етапу валідації
pack
- Запустіть ручний workflow `Full Release Validation` перед схваленням релізу, щоб
запустити всі передрелізні тестові boxes з однієї точки входу. Він приймає гілку,
tag або повний commit SHA, запускає ручний `CI` і запускає
релізні артефакти `dist/*` і бандл Control UI існували для кроку
валідації пакування
- Запустіть `pnpm plugins:sync` після bump версії в корені та перед тегуванням. Він
оновлює версії пакетів publishable plugin, metadata сумісності OpenClaw peer/API,
metadata збірки та заготовки changelog plugin, щоб вони відповідали core
release version. `pnpm plugins:sync:check` є немутуючим release guard;
publish workflow завершується помилкою до будь-якої зміни registry, якщо цей крок
було забуто.
- Запустіть ручний workflow `Full Release Validation` перед release approval, щоб
запустити всі передрелізні test boxes з однієї точки входу. Він приймає branch,
tag або повний commit SHA, dispatches manual `CI` і dispatches
`OpenClaw Release Checks` для install smoke, package acceptance, Docker
release-path suites, live/E2E, OpenWebUI, QA Lab parity, Matrix і Telegram
lanes. З `release_profile=full` і `rerun_group=all` він також запускає package
Telegram E2E проти артефакту `release-package-under-test` з release
checks. Надайте `npm_telegram_package_spec` після публікації, коли той самий
Telegram E2E також має підтвердити опублікований npm package. Надайте
`evidence_package_spec`, коли приватний звіт доказів має підтвердити, що
валідація відповідає опублікованому npm package, без примусового Telegram E2E.
Telegram E2E має також підтвердити опублікований npm package. Надайте
`evidence_package_spec`, коли приватний evidence report має підтвердити, що
валідація відповідає опублікованому npm package без примусового Telegram E2E.
Приклад:
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- Запустіть ручний workflow `Package Acceptance`, коли потрібен side-channel доказ
для package candidate, поки релізна робота триває. Використовуйте `source=npm` для
- Запустіть ручний workflow `Package Acceptance`, коли вам потрібен side-channel proof
для package candidate, поки release work триває. Використовуйте `source=npm` для
`openclaw@beta`, `openclaw@latest` або точної release version; `source=ref`,
щоб упакувати довірену гілку/tag/SHA `package_ref` з поточним
harness `workflow_ref`; `source=url` для HTTPS tarball з обов’язковим
SHA-256; або `source=artifact` для tarball, завантаженого іншим GitHub
Actions run. Workflow resolves candidate to
щоб запакувати trusted `package_ref` branch/tag/SHA з поточним
`workflow_ref` harness; `source=url` для HTTPS tarball з обов’язковим
SHA-256; або `source=artifact` для tarball, uploaded by another GitHub
Actions run. Workflow resolves the candidate to
`package-under-test`, повторно використовує Docker E2E release scheduler проти цього
tarball і може запускати Telegram QA проти того самого tarball з
`telegram_mode=mock-openai` або `telegram_mode=live-frontier`. Коли вибрані
Docker lanes містять `published-upgrade-survivor`, package artifact є candidate,
а `published_upgrade_survivor_baseline` вибирає published baseline.
`telegram_mode=mock-openai` або `telegram_mode=live-frontier`. Коли
selected Docker lanes включають `published-upgrade-survivor`, package
artifact є candidate, а `published_upgrade_survivor_baseline` вибирає
published baseline.
Приклад: `gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f published_upgrade_survivor_baseline=openclaw@2026.4.26 -f telegram_mode=mock-openai`
Поширені профілі:
Типові profiles:
- `smoke`: install/channel/agent, gateway network і config reload lanes
- `package`: artifact-native package/update/plugin lanes без OpenWebUI або live ClawHub
- `product`: package profile плюс MCP channels, cron/subagent cleanup,
OpenAI web search і OpenWebUI
- `full`: Docker release-path chunks з OpenWebUI
- `custom`: точний вибір `docker_lanes` для сфокусованого повторного запуску
- Запустіть ручний workflow `CI` напряму, коли потрібне лише повне звичайне CI
покриття для release candidate. Ручні CI dispatches bypass changed
- `custom`: точний вибір `docker_lanes` для focused rerun
- Запустіть ручний workflow `CI` напряму, коли вам потрібне лише повне нормальне CI
coverage для release candidate. Manual CI dispatches bypass changed
scoping і примусово запускають Linux Node shards, bundled-plugin shards, channel
contracts, Node 22 compatibility, `check`, `check-additional`, build smoke,
docs checks, Python skills, Windows, macOS, Android і Control UI i18n
lanes.
Приклад: `gh workflow run ci.yml --ref release/YYYY.M.D`
- Запустіть `pnpm qa:otel:smoke` під час валідації release telemetry. Він проганяє
QA-lab через локальний OTLP/HTTP receiver і перевіряє експортовані назви trace
span, обмежені attributes і редагування content/identifier без потреби в
Opik, Langfuse або іншому зовнішньому collector.
- Запустіть `pnpm release:check` перед кожним tagged release
- Запустіть `pnpm qa:otel:smoke` під час валідації release telemetry. Він запускає
QA-lab через локальний OTLP/HTTP receiver і перевіряє exported trace
span names, bounded attributes і редагування content/identifier без
потреби в Opik, Langfuse чи іншому external collector.
- Запускайте `pnpm release:check` перед кожним tagged release
- Запустіть `OpenClaw Release Publish` для mutating publish sequence після того, як
tag існує. Dispatch його з `release/YYYY.M.D` (або `main`, коли публікується
tag існує. Dispatch it from `release/YYYY.M.D` (або `main`, коли публікуєте
main-reachable tag), передайте release tag і успішний OpenClaw npm
`preflight_run_id`, і залиште default plugin publish scope
`all-publishable`, якщо ви не виконуєте навмисний focused repair. Workflow
`all-publishable`, якщо ви не запускаєте deliberate focused repair. Workflow
serializes plugin npm publish, plugin ClawHub publish і OpenClaw
npm publish, щоб core package не було опубліковано перед його externalized
npm publish, щоб core package не був опублікований перед своїми externalized
plugins.
- Release checks тепер виконуються в окремому ручному workflow:
`OpenClaw Release Checks`
- `OpenClaw Release Checks` також запускає QA Lab mock parity gate плюс fast
live Matrix profile і Telegram QA lane перед схваленням релізу. Live
lanes використовують середовище `qa-live-shared`; Telegram також використовує Convex CI
live Matrix profile і Telegram QA lane перед release approval. Live
lanes використовують environment `qa-live-shared`; Telegram також використовує Convex CI
credential leases. Запустіть ручний workflow `QA-Lab - All Lanes` з
`matrix_profile=all` і `matrix_shards=true`, коли потрібен повний Matrix
`matrix_profile=all` і `matrix_shards=true`, коли вам потрібен повний Matrix
transport, media і E2EE inventory паралельно.
- Cross-OS install і upgrade runtime validation є частиною публічних
- Cross-OS install і upgrade runtime validation є частиною public
`OpenClaw Release Checks` і `Full Release Validation`, які напряму викликають
reusable workflow
`.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- Цей поділ навмисний: тримайте реальний npm release path коротким,
deterministic і artifact-focused, тоді як повільніші live checks залишаються у власному
lane, щоб вони не затримували й не блокували publish
- Secret-bearing release checks слід dispatch через `Full Release
- Цей split навмисний: тримайте real npm release path коротким,
deterministic і artifact-focused, тоді як повільніші live checks залишаються у своєму
окремому lane, щоб вони не затримували і не блокували publish
- Secret-bearing release checks слід dispatch through `Full Release
Validation` або з `main`/release workflow ref, щоб workflow logic і
secrets залишалися контрольованими
- `OpenClaw Release Checks` приймає гілку, tag або повний commit SHA, якщо
resolved commit reachable з OpenClaw branch або release tag
- Validation-only preflight `OpenClaw NPM Release` також приймає поточний
повний 40-символьний workflow-branch commit SHA без потреби в pushed tag
- Цей SHA path призначений лише для валідації й не може бути promoted у реальний publish
- `OpenClaw Release Checks` приймає branch, tag або full commit SHA, якщо
resolved commit reachable from an OpenClaw branch або release tag
- `OpenClaw NPM Release` validation-only preflight також приймає поточний
повний 40-character workflow-branch commit SHA без вимоги pushed tag
- Цей SHA path є validation-only і не може бути promoted into a real publish
- У SHA mode workflow synthesizes `v<package.json version>` лише для
package metadata check; реальний publish усе ще потребує справжнього release tag
- Обидва workflows тримають реальний publish і promotion path на GitHub-hosted
package metadata check; real publish усе ще вимагає real release tag
- Обидва workflows тримають real publish і promotion path на GitHub-hosted
runners, тоді як non-mutating validation path може використовувати більші
Blacksmith Linux runners
- Цей workflow запускає
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
з використанням обох workflow secrets `OPENAI_API_KEY` і `ANTHROPIC_API_KEY`
- npm release preflight більше не чекає на окремий release checks lane
- npm release preflight більше не чекає окремий release checks lane
- Запустіть `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
(або відповідний beta/correction tag) перед схваленням
(або відповідний beta/correction tag) перед approval
- Після npm publish запустіть
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
(або відповідну beta/correction version), щоб перевірити published registry
install path у свіжому temp prefix
install path у fresh temp prefix
- Після beta publish запустіть `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`,
щоб перевірити installed-package onboarding, Telegram setup і реальний Telegram E2E
проти опублікованого npm package, використовуючи shared leased Telegram credential
pool. Локальні одноразові maintainer runs можуть пропускати Convex vars і передавати три
env credentials `OPENCLAW_QA_TELEGRAM_*` напряму.
щоб перевірити installed-package onboarding, Telegram setup і real Telegram E2E
проти published npm package за допомогою shared leased Telegram credential
pool. Local maintainer one-offs можуть omit Convex vars і передавати три
`OPENCLAW_QA_TELEGRAM_*` env credentials directly.
- Maintainers можуть запускати ту саму post-publish check з GitHub Actions через
ручний workflow `NPM Telegram Beta E2E`. Він навмисно manual-only і
не запускається на кожному merge.
manual workflow `NPM Telegram Beta E2E`. Він навмисно manual-only і
не виконується на кожному merge.
- Maintainer release automation тепер використовує preflight-then-promote:
- реальний npm publish має пройти успішний npm `preflight_run_id`
- реальний npm publish має бути dispatched з тієї самої гілки `main` або
`release/YYYY.M.D`, що й успішний preflight run
- real npm publish must pass a successful npm `preflight_run_id`
- real npm publish має dispatch from the same `main` або
`release/YYYY.M.D` branch as the successful preflight run
- stable npm releases default to `beta`
- stable npm publish може явно цілитися в `latest` через workflow input
- token-based npm dist-tag mutation тепер живе в
- stable npm publish can target `latest` explicitly via workflow input
- token-based npm dist-tag mutation now lives in
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
для безпеки, бо `npm dist-tag add` все ще потребує `NPM_TOKEN`, тоді як
for security, because `npm dist-tag add` still needs `NPM_TOKEN` while the
public repo keeps OIDC-only publish
- public `macOS Release` є validation-only; коли tag існує лише на
release branch, але workflow dispatched з `main`, встановіть
- public `macOS Release` is validation-only; when a tag lives only on a
release branch but the workflow is dispatched from `main`, set
`public_release_branch=release/YYYY.M.D`
- реальний private mac publish має пройти успішні private mac
`preflight_run_id` і `validate_run_id`
- реальні publish paths promote prepared artifacts замість того, щоб rebuilding
- real private mac publish must pass successful private mac
`preflight_run_id` and `validate_run_id`
- real publish paths promote prepared artifacts instead of rebuilding
them again
- Для stable correction releases на кшталт `YYYY.M.D-N` post-publish verifier
також перевіряє той самий temp-prefix upgrade path з `YYYY.M.D` до `YYYY.M.D-N`,
щоб release corrections не могли непомітно залишити старіші global installs на
- For stable correction releases like `YYYY.M.D-N`, the post-publish verifier
also checks the same temp-prefix upgrade path from `YYYY.M.D` to `YYYY.M.D-N`
so release corrections cannot silently leave older global installs on the
base stable payload
- npm release preflight fails closed, якщо tarball не містить одночасно
`dist/control-ui/index.html` і non-empty payload `dist/control-ui/assets/`,
щоб ми знову не shipped empty browser dashboard
- Post-publish verification також перевіряє, що published plugin entrypoints і
package metadata присутні в installed registry layout. Реліз, який
ships missing plugin runtime payloads, fails postpublish verifier і
не може бути promoted to `latest`.
- `pnpm test:install:smoke` також enforces npm pack `unpackedSize` budget on
candidate update tarball, щоб installer e2e catches accidental pack bloat
перед release publish path
- Якщо release work touched CI planning, extension timing manifests або
extension test matrices, regenerate and review planner-owned
- npm release preflight fails closed unless the tarball includes both
`dist/control-ui/index.html` and a non-empty `dist/control-ui/assets/` payload
so we do not ship an empty browser dashboard again
- Post-publish verification also checks that published plugin entrypoints and
package metadata are present in the installed registry layout. A release that
ships missing plugin runtime payloads fails the postpublish verifier and
cannot be promoted to `latest`.
- `pnpm test:install:smoke` also enforces the npm pack `unpackedSize` budget on
the candidate update tarball, so installer e2e catches accidental pack bloat
before the release publish path
- If the release work touched CI planning, extension timing manifests, or
extension test matrices, regenerate and review the planner-owned
`plugin-prerelease-extension-shard` matrix outputs from
`.github/workflows/plugin-prerelease.yml` перед approval, щоб release notes не
описували stale CI layout
- Stable macOS release readiness також includes updater surfaces:
- GitHub release має в підсумку містити packaged `.zip`, `.dmg` і `.dSYM.zip`
- `appcast.xml` on `main` має point at new stable zip after publish
- packaged app має keep non-debug bundle id, non-empty Sparkle feed
URL і `CFBundleVersion` на або вище canonical Sparkle build floor
`.github/workflows/plugin-prerelease.yml` before approval so release notes do
not describe a stale CI layout
- Stable macOS release readiness also includes the updater surfaces:
- the GitHub release must end up with the packaged `.zip`, `.dmg`, and `.dSYM.zip`
- `appcast.xml` on `main` must point at the new stable zip after publish
- the packaged app must keep a non-debug bundle id, a non-empty Sparkle feed
URL, and a `CFBundleVersion` at or above the canonical Sparkle build floor
for that release version
## Release test boxes
`Full Release Validation` — це спосіб, яким operators запускають усі передрелізні тести з
однієї точки входу. Для pinned commit proof на швидко змінюваній гілці використовуйте
helper, щоб кожен child workflow запускався з тимчасової гілки, зафіксованої на target
`Full Release Validation` — це спосіб, яким operators запускають усі pre-release tests з
однієї точки входу. Для pinned commit proof на fast-moving branch використовуйте
helper, щоб кожен child workflow запускався з тимчасової branch, fixed at the target
SHA:
```bash
@ -264,11 +271,11 @@ pnpm ci:full-release --sha <full-sha>
Helper pushes `release-ci/<sha>-...`, dispatches `Full Release Validation`
from that branch with `ref=<sha>`, verifies every child workflow `headSha`
matches the target, then deletes the temporary branch. This avoids proving a
newer `main` child run by accident.
matches the target, then deletes the temporary branch. Це запобігає випадковому
підтвердженню newer `main` child run.
Для валідації release branch або tag запустіть його з довіреного workflow
ref `main` і передайте release branch або tag як `ref`:
Для release branch або tag validation запускайте його з trusted `main` workflow
ref і передавайте release branch або tag як `ref`:
```bash
gh workflow run full-release-validation.yml \
@ -283,44 +290,44 @@ gh workflow run full-release-validation.yml \
Робочий процес визначає цільовий ref, запускає ручний `CI` з
`target_ref=<release-ref>`, запускає `OpenClaw Release Checks` і запускає
окремий пакетний Telegram E2E, коли `release_profile=full` з
`rerun_group=all` або коли задано `npm_telegram_package_spec`. Потім `OpenClaw Release
Checks` розгортає install smoke, cross-OS release checks, live/E2E Docker
coverage для release path, Package Acceptance з QA пакета Telegram, QA Lab
`rerun_group=all` або коли задано `npm_telegram_package_spec`. Далі `OpenClaw Release
Checks` розгортається в install smoke, cross-OS release checks, live/E2E Docker
покриття release-path, Package Acceptance з Telegram package QA, QA Lab
parity, live Matrix і live Telegram. Повний запуск прийнятний лише тоді, коли
зведення `Full Release Validation`
показує `normal_ci` і `release_checks` як успішні. У режимі full/all
дочірній `npm_telegram` також має бути успішним; поза full/all він пропускається,
якщо не було надано опублікований `npm_telegram_package_spec`. Фінальне
зведення verifier містить таблиці найповільніших завдань для кожного дочірнього запуску, щоб release
підсумок `Full Release Validation`
показує `normal_ci` і `release_checks` як успішні. У режимі full/all дочірній
`npm_telegram` також має бути успішним; поза full/all він пропускається,
якщо не було надано опублікований `npm_telegram_package_spec`. Фінальний
підсумок verifier містить таблиці найповільніших завдань для кожного дочірнього запуску, щоб release
manager міг бачити поточний критичний шлях без завантаження логів.
Див. [Повна валідація релізу](/uk/reference/full-release-validation) для
повної матриці етапів, точних назв завдань workflow, відмінностей між stable і full профілями,
артефактів і ручок для сфокусованого повторного запуску.
Дочірні workflow запускаються з довіреного ref, який виконує `Full Release
Validation`, зазвичай `--ref main`, навіть коли цільовий `ref` вказує на
старішу релізну гілку або тег. Окремого input workflow-ref для Full Release Validation
немає; обирайте довірений harness, обираючи ref запуску workflow.
Не використовуйте `--ref main -f ref=<sha>` для доказу точного коміту на рухомому `main`;
сирі SHA комітів не можуть бути refs для workflow dispatch, тому використовуйте
Див. [повну release validation](/uk/reference/full-release-validation), щоб отримати
повну матрицю етапів, точні назви завдань workflow, відмінності між профілями stable і full,
артефакти та вказівники для сфокусованих повторних запусків.
Дочірні workflows запускаються з довіреного ref, який виконує `Full Release
Validation`, зазвичай `--ref main`, навіть коли цільовий `ref` указує на
старішу release-гілку або tag. Окремого вхідного параметра workflow-ref для Full Release Validation
немає; вибирайте довірений harness, вибираючи ref запуску workflow.
Не використовуйте `--ref main -f ref=<sha>` для доказу точного commit на рухомій `main`;
raw commit SHA не можуть бути workflow dispatch refs, тому використовуйте
`pnpm ci:full-release --sha <sha>`, щоб створити закріплену тимчасову гілку.
Використовуйте `release_profile`, щоб вибрати ширину live/provider:
- `minimum`: найшвидший release-critical OpenAI/core live і Docker path
- `stable`: minimum плюс stable provider/backend coverage для затвердження релізу
- `full`: stable плюс широке advisory provider/media coverage
- `stable`: minimum плюс stable provider/backend покриття для схвалення release
- `full`: stable плюс широке advisory provider/media покриття
`OpenClaw Release Checks` використовує довірений workflow ref, щоб один раз визначити цільовий
ref як `release-package-under-test`, і повторно використовує цей артефакт як у
release-path Docker checks, так і в Package Acceptance. Це утримує всі
package-facing бокси на тих самих байтах і уникає повторних збірок пакета.
package-facing boxes на тих самих bytes і уникає повторних package builds.
Cross-OS OpenAI install smoke використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли
змінну repo/org задано, інакше `openai/gpt-5.5`, оскільки ця lane
доводить встановлення пакета, onboarding, запуск gateway і один live agent turn,
а не бенчмарк найповільнішої моделі за замовчуванням. Ширша live provider
matrix залишається місцем для model-specific coverage.
задано repo/org variable, інакше `openai/gpt-5.5`, тому що цей lane
доводить package install, onboarding, Gateway startup і один live agent turn,
а не benchmark найповільнішої default model. Ширша live provider
matrix лишається місцем для model-specific coverage.
Використовуйте ці варіанти залежно від етапу релізу:
Використовуйте ці варіанти залежно від етапу release:
```bash
# Validate an unpublished release candidate branch.
@ -350,41 +357,41 @@ gh workflow run full-release-validation.yml \
-f npm_telegram_provider_mode=mock-openai
```
Не використовуйте повну umbrella як перший повторний запуск після сфокусованого виправлення. Якщо один box
Не використовуйте повний umbrella як перший повторний запуск після сфокусованого виправлення. Якщо один box
падає, використовуйте невдалий дочірній workflow, job, Docker lane, package profile, model
provider або QA lane для наступного доказу. Запускайте повну umbrella знову лише тоді, коли
виправлення змінило спільну release orchestration або зробило попередній all-box evidence
застарілим. Фінальний verifier umbrella повторно перевіряє записані child workflow run
ids, тому після успішного повторного запуску child workflow повторно запускайте лише невдалий
батьківський job `Verify full validation`.
provider або QA lane для наступного доказу. Запускайте повний umbrella знову лише тоді, коли
виправлення змінило спільну release orchestration або зробило попередні all-box докази
застарілими. Фінальний verifier umbrella повторно перевіряє записані child workflow run
ids, тому після успішного повторного запуску дочірнього workflow перезапустіть лише невдале
батьківське завдання `Verify full validation`.
Для обмеженого відновлення передайте `rerun_group` в umbrella. `all` — це справжній
запуск release candidate, `ci` запускає лише звичайний дочірній CI, `plugin-prerelease`
Для обмеженого відновлення передайте `rerun_group` до umbrella. `all` є справжнім
release-candidate запуском, `ci` запускає лише звичайний дочірній CI, `plugin-prerelease`
запускає лише release-only plugin child, `release-checks` запускає кожен release
box, а вужчі release groups — це `install-smoke`, `cross-os`,
`live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` і `npm-telegram`.
Сфокусовані повторні запуски `npm-telegram` потребують `npm_telegram_package_spec`; запуски full/all
з `release_profile=full` використовують артефакт пакета release-checks.
Сфокусовані повторні запуски `npm-telegram` потребують `npm_telegram_package_spec`; full/all runs
з `release_profile=full` використовують package artifact із release-checks.
### Vitest
Vitest box — це ручний дочірній workflow `CI`. Ручний CI навмисно
обходить changed scoping і примусово виконує звичайний тестовий граф для release
Vitest box — це ручний дочірній workflow `CI`. Manual CI навмисно
оминає changed scoping і примусово запускає звичайний test graph для release
candidate: Linux Node shards, bundled-plugin shards, channel contracts, Node 22
compatibility, `check`, `check-additional`, build smoke, docs checks, Python
skills, Windows, macOS, Android і Control UI i18n.
Skills, Windows, macOS, Android і Control UI i18n.
Використовуйте цей box, щоб відповісти: "чи пройшло дерево джерел повний звичайний набір тестів?"
Це не те саме, що release-path product validation. Докази, які слід зберігати:
Використовуйте цей box, щоб відповісти на питання «чи пройшло source tree повний звичайний test suite?»
Це не те саме, що release-path product validation. Докази, які слід зберегти:
- зведення `Full Release Validation`, що показує URL запущеного `CI` run
- зелений `CI` run на точному цільовому SHA
- назви невдалих або повільних shard із CI jobs під час розслідування регресій
- артефакти таймінгів Vitest, такі як `.artifacts/vitest-shard-timings.json`, коли
запуск потребує аналізу продуктивності
- підсумок `Full Release Validation`, що показує URL запущеного `CI`
- зелений запуск `CI` на точному цільовому SHA
- назви невдалих або повільних shards із CI jobs під час розслідування regressions
- артефакти timing Vitest, як-от `.artifacts/vitest-shard-timings.json`, коли
запуск потребує performance analysis
Запускайте ручний CI напряму лише тоді, коли релізу потрібен детермінований звичайний CI, але
не Docker, QA Lab, live, cross-OS або package boxes:
Запускайте manual CI напряму лише тоді, коли release потребує deterministic normal CI, але
не потребує Docker, QA Lab, live, cross-OS або package boxes:
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -392,16 +399,16 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
### Docker
Docker box живе в `OpenClaw Release Checks` через
Docker box знаходиться в `OpenClaw Release Checks` через
`openclaw-live-and-e2e-checks-reusable.yml`, плюс release-mode
workflow `install-smoke`. Він перевіряє release candidate через упаковані
Docker середовища, а не лише тести рівня джерел.
workflow `install-smoke`. Він перевіряє release candidate через packaged
Docker environments, а не лише source-level tests.
Release Docker coverage включає:
- повний install smoke з увімкненим повільним Bun global install smoke
- підготовку/повторне використання root Dockerfile smoke image за цільовим SHA, з QR,
root/gateway і installer/Bun smoke jobs, що виконуються як окремі install-smoke
- підготовку/повторне використання root Dockerfile smoke image за target SHA, з QR,
root/gateway і installer/Bun smoke jobs, що працюють як окремі install-smoke
shards
- repository E2E lanes
- release-path Docker chunks: `core`, `package-update-openai`,
@ -413,18 +420,18 @@ Release Docker coverage включає:
`plugins-runtime-install-g` і `plugins-runtime-install-h`
- OpenWebUI coverage всередині chunk `plugins-runtime-services`, коли це запитано
- розділені bundled plugin install/uninstall lanes
`bundled-plugin-install-uninstall-0` до
від `bundled-plugin-install-uninstall-0` до
`bundled-plugin-install-uninstall-23`
- live/E2E provider suites і Docker live model coverage, коли release checks
включають live suites
Використовуйте Docker артефакти перед повторним запуском. Release-path scheduler завантажує
`.artifacts/docker-tests/` з логами lane, `summary.json`, `failures.json`,
таймінгами фаз, scheduler plan JSON і командами повторного запуску. Для сфокусованого відновлення
Використовуйте Docker artifacts перед повторним запуском. Release-path scheduler завантажує
`.artifacts/docker-tests/` з lane logs, `summary.json`, `failures.json`,
phase timings, scheduler plan JSON і rerun commands. Для сфокусованого відновлення
використовуйте `docker_lanes=<lane[,lane]>` у reusable live/E2E workflow замість
повторного запуску всіх release chunks. Згенеровані команди повторного запуску включають попередні
`package_artifact_run_id` і підготовлені Docker image inputs, коли доступні, щоб
невдала lane могла повторно використати той самий tarball і GHCR images.
повторного запуску всіх release chunks. Згенеровані rerun commands включають попередні
`package_artifact_run_id` і prepared Docker image inputs, коли вони доступні, щоб
невдалий lane міг повторно використати той самий tarball і GHCR images.
### QA Lab
@ -435,63 +442,63 @@ package mechanics.
Release QA Lab coverage включає:
- mock parity gate, що порівнює OpenAI candidate lane з Opus 4.6
baseline за допомогою agentic parity pack
- швидкий live Matrix QA profile з використанням середовища `qa-live-shared`
- live Telegram QA lane з використанням Convex CI credential leases
- `pnpm qa:otel:smoke`, коли release telemetry потребує явного локального доказу
baseline, використовуючи agentic parity pack
- fast live Matrix QA profile, що використовує environment `qa-live-shared`
- live Telegram QA lane, що використовує Convex CI credential leases
- `pnpm qa:otel:smoke`, коли release telemetry потребує explicit local proof
Використовуйте цей box, щоб відповісти: "чи поводиться реліз коректно у QA сценаріях і
live channel flows?" Зберігайте URL артефактів для parity, Matrix і Telegram
lanes під час затвердження релізу. Повне Matrix coverage залишається доступним як
ручний sharded QA-Lab run, а не release-critical lane за замовчуванням.
Використовуйте цей box, щоб відповісти на питання «чи поводиться release правильно в QA scenarios і
live channel flows?» Зберігайте artifact URLs для parity, Matrix і Telegram
lanes під час схвалення release. Full Matrix coverage лишається доступним як
ручний sharded QA-Lab run, а не default release-critical lane.
### Пакет
### Package
Package box — це installable-product gate. Він підтримується
Package box — це installable-product gate. Він спирається на
`Package Acceptance` і resolver
`scripts/resolve-openclaw-package-candidate.mjs`. Resolver нормалізує
candidate у tarball `package-under-test`, який споживає Docker E2E, перевіряє
інвентар пакета, записує версію пакета та SHA-256 і тримає
package inventory, записує package version і SHA-256 та тримає
workflow harness ref окремо від package source ref.
Підтримувані джерела candidate:
Підтримувані candidate sources:
- `source=npm`: `openclaw@beta`, `openclaw@latest` або точна release
version OpenClaw
- `source=ref`: пакувати довірену `package_ref` branch, tag або full commit SHA
- `source=npm`: `openclaw@beta`, `openclaw@latest` або точна OpenClaw release
version
- `source=ref`: pack довірену `package_ref` branch, tag або повний commit SHA
з вибраним `workflow_ref` harness
- `source=url`: завантажити HTTPS `.tgz` з обов’язковим `package_sha256`
- `source=artifact`: повторно використати `.tgz`, завантажений іншим GitHub Actions run
`OpenClaw Release Checks` запускає Package Acceptance з `source=artifact`,
підготовленим release package artifact, `suite_profile=custom`,
prepared release package 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`. Package Acceptance утримує migration, update, stale
`telegram_mode=mock-openai`. Package Acceptance тримає migration, update, stale
plugin dependency cleanup, offline plugin fixtures, plugin update і Telegram
package QA проти того самого resolved tarball. Це GitHub-native
заміна більшої частини package/update coverage, яка раніше потребувала
package QA на тому самому resolved tarball. Це GitHub-native
заміна для більшості package/update coverage, яке раніше вимагало
Parallels. Cross-OS release checks усе ще важливі для OS-specific onboarding,
installer і platform behavior, але package/update product validation має
надавати перевагу Package Acceptance.
віддавати перевагу Package Acceptance.
Канонічний checklist для update і plugin validation —
[Тестування оновлень і plugins](/uk/help/testing-updates-plugins). Використовуйте його, коли
вирішуєте, яка local, Docker, Package Acceptance або release-check lane доводить
[тестування оновлень і плагінів](/uk/help/testing-updates-plugins). Використовуйте його, коли
вирішуєте, який local, Docker, Package Acceptance або release-check lane доводить
plugin install/update, doctor cleanup або published-package migration change.
Exhaustive published update migration з кожного stable пакета `2026.4.23+` — це
окремий ручний workflow `Update Migration`, а не частина Full Release CI.
Exhaustive published update migration з кожного stable package `2026.4.23+` є
окремим ручним workflow `Update Migration`, а не частиною Full Release CI.
Legacy package-acceptance leniency навмисно обмежена в часі. Пакети до
`2026.4.25` можуть використовувати compatibility path для metadata gaps, уже опублікованих
Legacy package-acceptance leniency навмисно обмежена в часі. Packages до
`2026.4.25` включно можуть використовувати compatibility path для metadata gaps, уже опублікованих
до npm: private QA inventory entries, відсутні в tarball, відсутній
`gateway install --wrapper`, відсутні patch files у tarball-derived git
fixture, відсутній persisted `update.channel`, legacy plugin install-record
locations, відсутній marketplace install-record persistence і config metadata
migration під час `plugins update`. Опублікований пакет `2026.4.26` може попереджати
про local build metadata stamp files, які вже були shipped. Пізніші пакети
мають задовольняти сучасні package contracts; ті самі gaps провалюють release
migration під час `plugins update`. Опублікований package `2026.4.26` може попереджати
про local build metadata stamp files, які вже були shipped. Пізніші packages
мають задовольняти modern package contracts; ті самі gaps провалюють release
validation.
Використовуйте ширші Package Acceptance profiles, коли release question стосується
@ -509,7 +516,7 @@ gh workflow run package-acceptance.yml \
Поширені package profiles:
- `smoke`: quick package install/channel/agent, gateway network і config
- `smoke`: швидкі package install/channel/agent, gateway network і config
reload lanes
- `package`: install/update/plugin package contracts без live ClawHub; це release-check
default
@ -518,77 +525,141 @@ gh workflow run package-acceptance.yml \
- `full`: Docker release-path chunks з OpenWebUI
- `custom`: точний список `docker_lanes` для сфокусованих повторних запусків
Для підтвердження пакета-кандидата Telegram увімкніть `telegram_mode=mock-openai` або
Для підтвердження кандидата пакета Telegram увімкніть `telegram_mode=mock-openai` або
`telegram_mode=live-frontier` у Package Acceptance. Workflow передає
розв’язаний tarball `package-under-test` у доріжку Telegram; окремий
workflow Telegram досі приймає опубліковану npm-специфікацію для перевірок
розв’язаний tarball `package-under-test` у lane Telegram; окремий
workflow Telegram і далі приймає опубліковану npm-специфікацію для перевірок
після публікації.
## Вхідні дані workflow NPM
## Автоматизація публікації релізу
`OpenClaw NPM Release` приймає такі вхідні дані, керовані оператором:
`OpenClaw Release Publish` є звичайною мутувальною точкою входу для публікації. Він
оркеструє workflows довіреного видавця в порядку, потрібному релізу:
- `tag`: обов’язковий тег релізу, наприклад `v2026.4.2`, `v2026.4.2-1` або
1. Отримати release tag і визначити його commit SHA.
2. Перевірити, що tag доступний з `main` або `release/*`.
3. Запустити `pnpm plugins:sync:check`.
4. Запустити `Plugin NPM Release` з `publish_scope=all-publishable` і
`ref=<release-sha>`.
5. Запустити `Plugin ClawHub Release` з тією самою областю дії та SHA.
6. Запустити `OpenClaw NPM Release` з release tag, npm dist-tag і
збереженим `preflight_run_id`.
Приклад публікації beta:
```bash
gh workflow run openclaw-release-publish.yml \
--ref release/YYYY.M.D \
-f tag=vYYYY.M.D-beta.N \
-f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
-f npm_dist_tag=beta
```
Stable-публікація до типового beta dist-tag:
```bash
gh workflow run openclaw-release-publish.yml \
--ref release/YYYY.M.D \
-f tag=vYYYY.M.D \
-f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
-f npm_dist_tag=beta
```
Stable-просування безпосередньо до `latest` є явним:
```bash
gh workflow run openclaw-release-publish.yml \
--ref release/YYYY.M.D \
-f tag=vYYYY.M.D \
-f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
-f npm_dist_tag=latest
```
Використовуйте нижчорівневі workflows `Plugin NPM Release` і `Plugin ClawHub Release`
лише для цільового виправлення або повторної публікації. Для виправлення вибраного plugin передайте
`plugin_publish_scope=selected` і `plugins=@openclaw/name` до
`OpenClaw Release Publish`, або запустіть дочірній workflow напряму, коли
пакет OpenClaw не має бути опублікований.
## Вхідні параметри workflow NPM
`OpenClaw NPM Release` приймає такі вхідні параметри, контрольовані оператором:
- `tag`: обов’язковий release tag, наприклад `v2026.4.2`, `v2026.4.2-1` або
`v2026.4.2-beta.1`; коли `preflight_only=true`, це також може бути поточний
повний 40-символьний SHA коміту гілки workflow для preflight лише з валідацією
- `preflight_only`: `true` лише для валідації/збірки/пакета, `false` для
реального шляху публікації
- `preflight_run_id`: обов’язковий на реальному шляху публікації, щоб workflow повторно використав
повний 40-символьний commit SHA гілки workflow для preflight лише з валідацією
- `preflight_only`: `true` лише для валідації/збирання/пакування, `false` для
справжнього шляху публікації
- `preflight_run_id`: обов’язковий на справжньому шляху публікації, щоб workflow повторно використав
підготовлений tarball з успішного preflight-запуску
- `npm_dist_tag`: цільовий тег npm для шляху публікації; типове значення `beta`
- `npm_dist_tag`: цільовий npm tag для шляху публікації; типово `beta`
`OpenClaw Release Checks` приймає такі вхідні дані, керовані оператором:
`OpenClaw Release Publish` приймає такі вхідні параметри, контрольовані оператором:
- `ref`: гілка, тег або повний SHA коміту для валідації. Перевірки, що містять
secrets, вимагають, щоб розв’язаний коміт був досяжний з гілки OpenClaw або
релізного тегу.
- `tag`: обов’язковий release tag; має вже існувати
- `preflight_run_id`: id успішного preflight-запуску `OpenClaw NPM Release`;
обов’язковий, коли `publish_openclaw_npm=true`
- `npm_dist_tag`: цільовий npm tag для пакета OpenClaw
- `plugin_publish_scope`: типово `all-publishable`; використовуйте `selected` лише
для цільового виправлення
- `plugins`: розділені комами назви пакетів `@openclaw/*`, коли
`plugin_publish_scope=selected`
- `publish_openclaw_npm`: типово `true`; встановлюйте `false` лише коли використовуєте
workflow як оркестратор виправлення лише plugins
`OpenClaw Release Checks` приймає такі вхідні параметри, контрольовані оператором:
- `ref`: гілка, tag або повний commit SHA для валідації. Перевірки з секретами
вимагають, щоб розв’язаний commit був доступний з гілки OpenClaw або
release tag.
Правила:
- Стабільні та корекційні теги можна публікувати або в `beta`, або в `latest`
- Beta-теги prerelease можна публікувати лише в `beta`
- Для `OpenClaw NPM Release` вхідний повний SHA коміту дозволений лише коли
- Stable- та correction-теги можуть публікуватися або до `beta`, або до `latest`
- Beta prerelease-теги можуть публікуватися лише до `beta`
- Для `OpenClaw NPM Release` вхідний повний commit SHA дозволений лише коли
`preflight_only=true`
- `OpenClaw Release Checks` і `Full Release Validation` завжди
призначені лише для валідації
- Реальний шлях публікації має використовувати той самий `npm_dist_tag`, що використовувався під час preflight;
workflow перевіряє ці metadata перед продовженням публікації
- Справжній шлях публікації має використовувати той самий `npm_dist_tag`, що використовувався під час preflight;
workflow перевіряє ці метадані перед продовженням публікації
## Послідовність стабільного npm-релізу
## Послідовність stable npm-релізу
Коли готуєте стабільний npm-реліз:
Під час підготовки stable npm-релізу:
1. Запустіть `OpenClaw NPM Release` з `preflight_only=true`
- До створення тегу можна використовувати поточний повний SHA коміту гілки workflow
- До появи tag можна використати поточний повний commit SHA гілки workflow
для пробного запуску preflight workflow лише з валідацією
2. Виберіть `npm_dist_tag=beta` для звичайного потоку спочатку в beta або `latest` лише
коли ви навмисно хочете пряму стабільну публікацію
3. Запустіть `Full Release Validation` на релізній гілці, релізному тегу або повному
SHA коміту, коли потрібні звичайний CI плюс покриття live prompt cache, Docker, QA Lab,
Matrix і Telegram з одного ручного workflow
4. Якщо вам навмисно потрібен лише детермінований звичайний граф тестів, запустіть
ручний workflow `CI` на release ref натомість
2. Виберіть `npm_dist_tag=beta` для звичайного потоку beta-first або `latest` лише
коли навмисно потрібна пряма stable-публікація
3. Запустіть `Full Release Validation` на release-гілці, release tag або повному
commit SHA, коли потрібно отримати звичайний CI плюс live prompt cache, Docker, QA Lab,
Matrix і покриття Telegram з одного ручного workflow
4. Якщо навмисно потрібен лише детермінований звичайний граф тестів, запустіть
ручний workflow `CI` на release ref
5. Збережіть успішний `preflight_run_id`
6. Запустіть `OpenClaw NPM Release` знову з `preflight_only=false`, тим самим
`tag`, тим самим `npm_dist_tag` і збереженим `preflight_run_id`
7. Якщо реліз потрапив у `beta`, використайте приватний
workflow `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`,
щоб просунути цю стабільну версію з `beta` до `latest`
8. Якщо реліз навмисно опубліковано напряму в `latest`, а `beta`
має негайно вказувати на ту саму стабільну збірку, використайте той самий приватний
workflow, щоб спрямувати обидва dist-tags на стабільну версію, або дозвольте його запланованій
6. Запустіть `OpenClaw Release Publish` з тим самим `tag`, тим самим `npm_dist_tag`
і збереженим `preflight_run_id`; він публікує винесені назовні plugins до npm
і ClawHub перед просуванням npm-пакета OpenClaw
7. Якщо реліз потрапив на `beta`, використайте приватний workflow
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
для просування цієї stable-версії з `beta` до `latest`
8. Якщо реліз навмисно опубліковано безпосередньо до `latest`, а `beta`
має негайно вказувати на ту саму stable-збірку, використайте той самий приватний
workflow, щоб спрямувати обидва dist-tags на stable-версію, або дозвольте його запланованій
самовідновлювальній синхронізації перемістити `beta` пізніше
Зміна dist-tag розміщена у приватному repo з міркувань безпеки, оскільки вона досі
потребує `NPM_TOKEN`, тоді як публічний repo зберігає публікацію лише через OIDC.
Мутація dist-tag розміщена в приватному repo з міркувань безпеки, оскільки вона досі
вимагає `NPM_TOKEN`, тоді як публічний repo зберігає публікацію лише через OIDC.
Це робить і шлях прямої публікації, і шлях просування спочатку через beta
Це зберігає як шлях прямої публікації, так і шлях beta-first просування
задокументованими та видимими для оператора.
Якщо maintainer мусить повернутися до локальної npm-автентифікації, запускайте будь-які команди 1Password
CLI (`op`) лише всередині виділеної tmux-сесії. Не викликайте `op`
напряму з основної оболонки агента; утримання його всередині tmux робить prompts,
alerts і обробку OTP видимими та запобігає повторним сповіщенням хоста.
Якщо maintainer має повернутися до локальної npm-автентифікації, запускайте будь-які
команди 1Password CLI (`op`) лише всередині окремої tmux-сесії. Не викликайте `op`
безпосередньо з основної оболонки агента; утримання цього всередині tmux робить prompts,
сповіщення та обробку OTP спостережуваними й запобігає повторним сповіщенням host.
## Публічні посилання

27
docs/uk/tools/brave-search.md
View File

@ -5,10 +5,10 @@ read_when:
summary: Налаштування Brave Search API для web_search
title: Пошук Brave
x-i18n:
generated_at: "2026-05-02T03:43:54Z"
generated_at: "2026-05-02T06:53:23Z"
model: gpt-5.5
provider: openai
source_hash: d5b6624d078ba55e30fbac4dd863a0d016e2e8d160e32bcc406e5070998241ba
source_hash: 06cfef368f01d0af91ddb4e8adc13b7699019cbf662783b88c573049bfb77e18
source_path: tools/brave-search.md
workflow: 16
---
@ -20,7 +20,7 @@ OpenClaw підтримує Brave Search API як провайдера `web_sear
## Отримання API-ключа
1. Створіть обліковий запис Brave Search API на [https://brave.com/search/api/](https://brave.com/search/api/)
2. На панелі керування виберіть план **Search** і згенеруйте API-ключ.
2. На панелі керування виберіть тариф **Search** і згенеруйте API-ключ.
3. Збережіть ключ у конфігурації або задайте `BRAVE_API_KEY` у середовищі Gateway.
## Приклад конфігурації
@ -51,8 +51,8 @@ OpenClaw підтримує Brave Search API як провайдера `web_sear
}
```
Специфічні для провайдера налаштування пошуку Brave тепер містяться в `plugins.entries.brave.config.webSearch.*`.
Застарілий `tools.web.search.apiKey` досі завантажується через шар сумісності, але більше не є канонічним шляхом конфігурації.
Специфічні для провайдера налаштування пошуку Brave тепер розміщені в `plugins.entries.brave.config.webSearch.*`.
Застарілий `tools.web.search.apiKey` досі завантажується через сумісний прошарок, але це більше не канонічний шлях конфігурації.
`webSearch.mode` керує транспортом Brave:
@ -82,7 +82,7 @@ OpenClaw підтримує Brave Search API як провайдера `web_sear
</ParamField>
<ParamField path="ui_lang" type="string">
Код мови ISO для елементів інтерфейсу.
Код мови ISO для елементів інтерфейсу користувача.
</ParamField>
<ParamField path="freshness" type="'day' | 'week' | 'month' | 'year'">
@ -123,16 +123,17 @@ await web_search({
## Примітки
- OpenClaw використовує план Brave **Search**. Якщо у вас є застаріла підписка (наприклад, початковий безкоштовний план із 2 000 запитів на місяць), вона залишається чинною, але не включає новіші можливості, як-от LLM Context або вищі ліміти частоти запитів.
- Кожен план Brave включає **\$5/місяць безкоштовного кредиту** (з поновленням). План Search коштує \$5 за 1 000 запитів, тож кредит покриває 1 000 запитів на місяць. Задайте ліміт використання на панелі керування Brave, щоб уникнути неочікуваних витрат. Актуальні плани дивіться на [порталі Brave API](https://brave.com/search/api/).
- План Search включає кінцеву точку LLM Context і права на AI-інференс. Збереження результатів для навчання або налаштування моделей потребує плану з явними правами на зберігання. Дивіться [Умови надання послуг](https://api-dashboard.search.brave.com/terms-of-service) Brave.
- Режим `llm-context` повертає обґрунтовані записи джерел замість звичайної структури фрагментів вебпошуку.
- Режим `llm-context` підтримує `freshness` і обмежені діапазони `date_after` + `date_before`. Він не підтримує `ui_lang`; `date_before` без `date_after` відхиляється, оскільки Brave вимагає, щоб користувацькі діапазони свіжості містили і початкову, і кінцеву дати.
- `ui_lang` має містити підтеґ регіону, як-от `en-US`.
- OpenClaw використовує тариф Brave **Search**. Якщо у вас застаріла підписка (наприклад, початковий тариф Free з 2 000 запитів на місяць), вона залишається чинною, але не включає новіші функції, як-от LLM Context або вищі ліміти швидкості.
- Кожен тариф Brave включає **\$5/місяць безкоштовного кредиту** (з поновленням). Тариф Search коштує \$5 за 1 000 запитів, тож кредит покриває 1 000 запитів на місяць. Задайте ліміт використання на панелі керування Brave, щоб уникнути неочікуваних витрат. Актуальні тарифи дивіться на [порталі Brave API](https://brave.com/search/api/).
- Тариф Search включає кінцеву точку LLM Context і права на AI-інференс. Зберігання результатів для навчання або донавчання моделей потребує тарифу з явними правами на зберігання. Дивіться Brave [Умови надання послуг](https://api-dashboard.search.brave.com/terms-of-service).
- Режим `llm-context` повертає обґрунтовані записи джерел замість звичайної форми фрагментів вебпошуку.
- Режим `llm-context` підтримує `freshness` і обмежені діапазони `date_after` + `date_before`. Він не підтримує `ui_lang`; `date_before` без `date_after` відхиляється, оскільки Brave вимагає, щоб власні діапазони свіжості містили і дату початку, і дату завершення.
- `ui_lang` має містити регіональний підтеґ, наприклад `en-US`.
- Результати кешуються на 15 хвилин за замовчуванням (налаштовується через `cacheTtlMinutes`).
- Увімкніть діагностичний прапорець `brave.http`, щоб під час усунення несправностей журналювати URL-адреси/параметри запитів Brave, статус/час відповіді та події влучання/промаху/запису пошукового кешу. Прапорець ніколи не журналює API-ключ або тіла відповідей, але пошукові запити можуть бути чутливими.
## Пов’язане
- [Огляд Web Search](/uk/tools/web) -- усі провайдери та автоматичне виявлення
- [Огляд Web Search](/uk/tools/web) -- усі провайдери та автовиявлення
- [Perplexity Search](/uk/tools/perplexity-search) -- структуровані результати з фільтрацією за доменами
- [Exa Search](/uk/tools/exa-search) -- нейронний пошук із витягуванням вмісту