diff --git a/docs/uk/ci.md b/docs/uk/ci.md index 3d37929e0..8646f987a 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,94 +1,94 @@ --- read_when: - Потрібно зрозуміти, чому завдання CI запустилося або не запустилося - - Ви налагоджуєте перевірку GitHub Actions, що завершується помилкою + - Ви налагоджуєте невдалу перевірку GitHub Actions - Ви координуєте запуск або повторний запуск валідації релізу - Ви змінюєте диспетчеризацію ClawSweeper або пересилання активності GitHub -summary: Граф завдань CI, контрольні шлюзи області дії, релізні парасольки та локальні еквіваленти команд +summary: Граф завдань CI, перевірки за областю, релізні парасольки та локальні еквіваленти команд title: CI-конвеєр x-i18n: - generated_at: "2026-05-02T15:53:14Z" + generated_at: "2026-05-02T15:57:59Z" model: gpt-5.5 provider: openai - source_hash: 1cf280f1f46d49462656de86001b7f2bef7c63f133dbb8d208a7497c48fa3497 + source_hash: 9687e386ce6beb96df10b57b43616af5366f231bd603e575ec20df386671564f source_path: ci.md workflow: 16 --- -OpenClaw CI запускається під час кожного push до `main` і кожного pull request. Завдання `preflight` класифікує diff і вимикає дорогі напрями, коли змінено лише непов’язані області. Ручні запуски `workflow_dispatch` навмисно обходять розумне обмеження області й розгортають повний граф для реліз-кандидатів і широкої валідації. Android-напрями залишаються opt-in через `include_android`. Релізне покриття Plugin живе в окремому workflow [`Передреліз Plugin`](#plugin-prerelease) і запускається лише з [`Повної релізної валідації`](#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` | Виявляє зміни лише в документації, змінені області, змінені extensions і будує маніфест CI | Завжди для нечернеткових push і PR | -| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для нечернеткових push і PR | -| `security-dependency-audit` | Аудит production lockfile без залежностей щодо npm advisories | Завжди для нечернеткових push і PR | -| `security-fast` | Обов’язковий агрегат для швидких security-завдань | Завжди для нечернеткових push і PR | -| `check-dependencies` | Production-прохід Knip лише для залежностей плюс guard allowlist невикористаних файлів | Зміни, релевантні для Node | -| `build-artifacts` | Збірка `dist/`, Control UI, перевірки зібраних артефактів і повторно використовувані downstream-артефакти | Зміни, релевантні для Node | -| `checks-fast-core` | Швидкі Linux-напрями коректності, як-от bundled/plugin-contract/protocol перевірки | Зміни, релевантні для Node | -| `checks-fast-contracts-channels` | Sharded перевірки контрактів каналів зі стабільним агрегованим результатом перевірки | Зміни, релевантні для Node | -| `checks-node-core-test` | Шарди тестів Core Node, без напрямів channel, bundled, contract і extension | Зміни, релевантні для Node | -| `check` | Sharded еквівалент головного локального gate: prod types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | -| `check-additional` | Шарди architecture, boundary, extension-surface guards, package-boundary і gateway-watch | Зміни, релевантні для Node | -| `build-smoke` | Smoke-тести зібраного CLI і smoke startup-memory | Зміни, релевантні для Node | -| `checks` | Верифікатор для тестів каналів зібраних артефактів | Зміни, релевантні для Node | -| `checks-node-compat-node22` | Напрям сумісності Node 22 зі збіркою і smoke | Ручний CI dispatch для релізів | -| `check-docs` | Форматування документації, lint і перевірки битих посилань | Змінено документацію | -| `skills-python` | Ruff + pytest для Skills на базі Python | Зміни, релевантні для Python Skills | -| `checks-windows` | Специфічні для Windows тести процесів/шляхів плюс регресії спільних runtime import specifier | Зміни, релевантні для Windows | -| `macos-node` | Напрям TypeScript-тестів macOS із використанням спільних зібраних артефактів | Зміни, релевантні для macOS | -| `macos-swift` | Swift lint, збірка і тести для застосунку macOS | Зміни, релевантні для macOS | -| `android` | Android unit-тести для обох flavor плюс одна debug APK збірка | Зміни, релевантні для Android | -| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успішний Main CI або ручний dispatch | -| `openclaw-performance` | Щоденні/on-demand звіти продуктивності runtime Kova з mock-provider, deep-profile і GPT 5.4 live напрямами | Запланований і ручний dispatch | +| Завдання | Призначення | Коли виконується | +| -------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | +| `preflight` | Виявляє зміни лише в документації, змінені області, змінені extensions і формує CI-маніфест | Завжди для нечернеткових push і PR | +| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для нечернеткових push і PR | +| `security-dependency-audit` | Аудит production lockfile без залежностей щодо npm advisories | Завжди для нечернеткових push і PR | +| `security-fast` | Обов’язковий агрегат для швидких завдань безпеки | Завжди для нечернеткових push і PR | +| `check-dependencies` | Production-прохід Knip лише для залежностей плюс захист allowlist невикористаних файлів | Зміни, релевантні Node | +| `build-artifacts` | Збірка `dist/`, Control UI, перевірки зібраних артефактів і багаторазові downstream-артефакти | Зміни, релевантні Node | +| `checks-fast-core` | Швидкі Linux-гілки коректності, як-от перевірки bundled/plugin-contract/protocol | Зміни, релевантні Node | +| `checks-fast-contracts-channels` | Sharded-перевірки контрактів каналів зі стабільним агрегованим результатом перевірки | Зміни, релевантні Node | +| `checks-node-core-test` | Шарди тестів Core Node, за винятком гілок каналів, bundled, contract і extension | Зміни, релевантні Node | +| `check` | Sharded-еквівалент головного локального gate: production-типи, lint, guards, test types і strict smoke | Зміни, релевантні Node | +| `check-additional` | Шарди архітектури, boundary, extension-surface guards, package-boundary і gateway-watch | Зміни, релевантні Node | +| `build-smoke` | Smoke-тести зібраного CLI і smoke перевірка пам’яті запуску | Зміни, релевантні Node | +| `checks` | Верифікатор тестів каналів зібраних артефактів | Зміни, релевантні Node | +| `checks-node-compat-node22` | Збірка сумісності з Node 22 і smoke-гілка | Ручний CI dispatch для релізів | +| `check-docs` | Форматування документації, lint і перевірки битих посилань | Змінено документацію | +| `skills-python` | Ruff + pytest для Skills на Python | Зміни, релевантні Python-Skills | +| `checks-windows` | Windows-специфічні тести процесів/шляхів плюс регресії спільних runtime import specifier | Зміни, релевантні Windows | +| `macos-node` | Гілка TypeScript-тестів macOS із використанням спільних зібраних артефактів | Зміни, релевантні macOS | +| `macos-swift` | Swift lint, збірка й тести для застосунку macOS | Зміни, релевантні macOS | +| `android` | Android unit tests для обох flavor плюс одна збірка debug APK | Зміни, релевантні Android | +| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успіх Main CI або ручний dispatch | +| `openclaw-performance` | Щоденні/за запитом Kova runtime звіти продуктивності з гілками mock-provider, deep-profile і GPT 5.4 live | Запланований і ручний dispatch | ## Порядок fail-fast -1. `preflight` вирішує, які напрями взагалі існують. Логіка `docs-scope` і `changed-scope` є кроками всередині цього завдання, а не окремими завданнями. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко падають, не чекаючи важчих завдань матриці артефактів і платформ. -3. `build-artifacts` перетинається зі швидкими Linux-напрямами, щоб downstream-споживачі могли стартувати щойно спільна збірка буде готова. -4. Після цього розгортаються важчі platform і runtime напрями: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. +1. `preflight` вирішує, які гілки взагалі існують. Логіка `docs-scope` і `changed-scope` є кроками всередині цього завдання, а не окремими завданнями. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко падають, не чекаючи на важчі завдання матриці артефактів і платформ. +3. `build-artifacts` перекривається зі швидкими Linux-гілками, щоб downstream-споживачі могли стартувати щойно спільна збірка готова. +4. Після цього розгортаються важчі platform і runtime гілки: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. -GitHub може позначати замінені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Сприймайте це як шум CI, якщо найновіший запуск для того самого ref також не падає. Агреговані перевірки shard використовують `!cancelled() && always()`, тому вони все одно повідомляють звичайні збої shard, але не стають у чергу після того, як увесь workflow уже було замінено. Автоматичний ключ concurrency CI версіонований (`CI-v7-*`), тому zombie на боці GitHub у старій групі черги не може нескінченно блокувати новіші main-запуски. Ручні запуски повного набору використовують `CI-manual-v1-*` і не скасовують запуски, що виконуються. +GitHub може позначати замінені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це шумом CI, якщо найновіший запуск для того самого ref також не падає. Агреговані перевірки шардів використовують `!cancelled() && always()`, тому вони все одно повідомляють звичайні збої шардів, але не стають у чергу після того, як увесь workflow уже був замінений. Автоматичний ключ конкурентності CI версіонований (`CI-v7-*`), тому GitHub-side zombie у старій групі черги не може безстроково блокувати новіші main-запуски. Ручні запуски повного набору використовують `CI-manual-v1-*` і не скасовують запуски, що вже виконуються. ## Область і маршрутизація -Логіка області живе в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`. Manual dispatch пропускає виявлення changed-scope і змушує маніфест preflight поводитися так, ніби змінилася кожна scoped-область. +Логіка областей міститься в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`. Ручний dispatch пропускає виявлення changed-scope і змушує preflight-маніфест поводитися так, ніби змінилися всі scoped області. -- **Редагування CI workflow** валідують граф Node CI плюс workflow linting, але самі по собі не змушують виконувати Windows, Android або macOS native builds; ці platform-напрями залишаються обмеженими змінами platform source. -- **Редагування лише CI routing, вибрані дешеві редагування core-test fixture і вузькі plugin contract helper/test-routing редагування** використовують швидкий шлях маніфесту лише для Node: `preflight`, security і одне завдання `checks-fast-core`. Цей шлях пропускає build artifacts, сумісність Node 22, channel contracts, повні core shards, bundled-plugin shards і додаткові guard matrices, коли зміна обмежена routing або helper surfaces, які швидке завдання напряму вправляє. -- **Windows Node checks** обмежені специфічними для Windows process/path wrappers, npm/pnpm/UI runner helpers, конфігурацією package manager і поверхнями CI workflow, які виконують цей напрям; непов’язані source, plugin, install-smoke і test-only зміни залишаються на Linux Node напрямах. +- **Правки CI workflow** валідують Node CI-граф плюс linting workflow, але самі по собі не примушують Windows, Android або macOS native builds; ці platform-гілки залишаються обмеженими змінами platform source. +- **Правки лише маршрутизації CI, вибрані дешеві правки core-test fixture і вузькі правки helper/test-routing для plugin contract** використовують швидкий Node-only шлях маніфесту: `preflight`, security і одне завдання `checks-fast-core`. Цей шлях пропускає build artifacts, сумісність із Node 22, channel contracts, повні core shards, bundled-plugin shards і додаткові матриці guard, коли зміна обмежена routing або helper surfaces, які швидке завдання напряму перевіряє. +- **Windows Node checks** обмежені Windows-специфічними wrappers процесів/шляхів, npm/pnpm/UI runner helpers, конфігурацією package manager і поверхнями CI workflow, які виконують цю гілку; непов’язані source, plugin, install-smoke і test-only зміни залишаються на Linux Node гілках. -Найповільніші сімейства Node-тестів розділені або збалансовані так, щоб кожне завдання залишалося малим без надмірного резервування runners: channel contracts запускаються як три weighted shards, малі core unit напрями об’єднані парами, auto-reply запускається як чотири збалансовані workers (з reply subtree, розділеним на agent-runner, dispatch і commands/state-routing shards), а agentic gateway/plugin configs розподілені між наявними source-only agentic Node завданнями замість очікування на built artifacts. Широкі browser, QA, media і miscellaneous plugin тести використовують власні виділені конфіги Vitest замість спільного plugin catch-all. Include-pattern shards записують timing entries із назвою CI shard, тому `.artifacts/vitest-shard-timings.json` може відрізнити цілий config від filtered shard. `check-additional` тримає package-boundary compile/canary роботу разом і відокремлює runtime topology architecture від gateway watch coverage; shard boundary guard запускає свої малі незалежні guards паралельно всередині одного завдання. Gateway watch, channel tests і core support-boundary shard запускаються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані. +Найповільніші родини Node-тестів розділено або збалансовано так, щоб кожне завдання залишалося малим без надмірного резервування runners: channel contracts виконуються як три зважені шарди, малі core unit lanes об’єднані парами, auto-reply виконується як чотири збалансовані workers (із reply subtree, розділеним на шарди agent-runner, dispatch і commands/state-routing), а agentic gateway/plugin configs розподілені між наявними source-only agentic Node jobs замість очікування built artifacts. Широкі browser, QA, media і miscellaneous plugin tests використовують власні dedicated Vitest configs замість спільного plugin catch-all. Include-pattern shards записують timing entries із назвою CI shard, щоб `.artifacts/vitest-shard-timings.json` міг відрізнити цілий 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 напрям усе одно компілює flavor з SMS/call-log BuildConfig flags, уникаючи дублювання debug APK packaging job під час кожного Android-релевантного push. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test гілка все одно компілює flavor із SMS/call-log BuildConfig flags, уникаючи дубльованого debug APK packaging job для кожного Android-relevant push. -Shard `check-dependencies` запускає `pnpm deadcode:dependencies` (production-прохід Knip лише для залежностей, закріплений на найновішій версії Knip, з вимкненим мінімальним віком релізу pnpm для встановлення `dlx`) і `pnpm deadcode:unused-files`, який порівнює production findings Knip щодо невикористаних файлів із `scripts/deadcode-unused-files.allowlist.mjs`. Guard невикористаних файлів падає, коли PR додає новий непереглянутий невикористаний файл або залишає застарілий запис allowlist, зберігаючи навмисні dynamic plugin, generated, build, live-test і package bridge surfaces, які Knip не може статично розв’язати. +Шард `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 -`.github/workflows/clawsweeper-dispatch.yml` є bridge на боці target із активності репозиторію OpenClaw до ClawSweeper. Він не checkout і не виконує недовірений код pull request. Workflow створює GitHub App token із `CLAWSWEEPER_APP_PRIVATE_KEY`, потім dispatch компактні payloads `repository_dispatch` до `openclaw/clawsweeper`. +`.github/workflows/clawsweeper-dispatch.yml` є target-side bridge з активності репозиторію OpenClaw до ClawSweeper. Він не check out і не виконує недовірений код pull request. Workflow створює GitHub App token із `CLAWSWEEPER_APP_PRIVATE_KEY`, а потім відправляє компактні payloads `repository_dispatch` до `openclaw/clawsweeper`. -Workflow має чотири напрями: +Workflow має чотири гілки: - `clawsweeper_item` для точних запитів review issue і pull request; - `clawsweeper_comment` для явних команд ClawSweeper у коментарях issue; -- `clawsweeper_commit_review` для запитів review на рівні commit у push до `main`; -- `github_activity` для загальної активності GitHub, яку агент ClawSweeper може інспектувати. +- `clawsweeper_commit_review` для commit-level review requests на push до `main`; +- `github_activity` для загальної активності GitHub, яку може перевіряти агент ClawSweeper. -Напрям `github_activity` пересилає лише нормалізовані метадані: event type, action, actor, repository, item number, URL, title, state і короткі excerpts для comments або reviews, коли вони присутні. Він навмисно уникає пересилання повного webhook body. Приймальний workflow в `openclaw/clawsweeper` — це `.github/workflows/github-activity.yml`, який публікує нормалізовану подію в hook OpenClaw Gateway для агента ClawSweeper. +Гілка `github_activity` пересилає лише нормалізовані metadata: event type, action, actor, repository, item number, URL, title, state і короткі excerpts для comments або reviews, коли вони наявні. Вона навмисно уникає пересилання повного webhook body. Приймальний workflow у `openclaw/clawsweeper` — це `.github/workflows/github-activity.yml`, який публікує нормалізовану подію до OpenClaw Gateway hook для агента ClawSweeper. -Загальна активність є спостереженням, а не доставкою за замовчуванням. Агент ClawSweeper отримує Discord target у своєму prompt і має публікувати в `#clawsweeper` лише коли подія є несподіваною, actionable, ризикованою або операційно корисною. Рутинні відкриття, редагування, bot churn, duplicate webhook noise і звичайний review traffic мають завершуватися `NO_REPLY`. +Загальна активність є спостереженням, а не доставкою за замовчуванням. Агент ClawSweeper отримує Discord target у своєму prompt і має публікувати в `#clawsweeper` лише тоді, коли подія є несподіваною, actionable, risky або operationally useful. Рутинні opens, edits, bot churn, duplicate webhook noise і normal review traffic мають завершуватися `NO_REPLY`. -Сприймайте titles, comments, bodies, review text, branch names і commit messages GitHub як недовірені дані на всьому цьому шляху. Це вхідні дані для summarization і triage, а не інструкції для workflow або agent runtime. +Вважайте GitHub titles, comments, bodies, review text, branch names і commit messages недовіреними даними на всьому цьому шляху. Вони є input для summarization і triage, а не інструкціями для workflow або agent runtime. ## Ручні dispatches -Ручні запуски CI виконують той самий граф завдань, що й звичайний CI, але примусово вмикають усі scoped-доріжки, окрім Android: шарди Linux Node, шарди bundled-plugin, контракти каналів, сумісність із Node 22, `check`, `check-additional`, build smoke, перевірки документації, Python skills, Windows, macOS та інтернаціоналізацію Control UI. Окремі ручні запуски CI виконують лише Android з `include_android=true`; повна release-парасолька вмикає Android, передаючи `include_android=true`. Статичні перевірки попереднього випуску Plugin, release-only шард `agentic-plugins`, повний batch sweep Plugin та Docker-доріжки попереднього випуску Plugin виключено з CI. Docker-набір попереднього випуску запускається лише тоді, коли `Full Release Validation` запускає окремий workflow `Plugin Prerelease` з увімкненим release-validation gate. +Ручні запускі CI виконують той самий граф завдань, що й звичайна CI, але примусово вмикають кожну scoped lane, не пов’язану з Android: шарди Linux Node, шарди bundled-plugin, контракти каналів, сумісність Node 22, `check`, `check-additional`, build smoke, перевірки документації, Python skills, Windows, macOS і Control UI i18n. Окремі ручні запускі CI виконують лише Android із `include_android=true`; повна release umbrella вмикає Android, передаючи `include_android=true`. Статичні перевірки prerelease Plugin, release-only шард `agentic-plugins`, повний batch sweep розширень і Docker lanes prerelease Plugin виключено з CI. Набір Docker prerelease запускається лише тоді, коли `Full Release Validation` запускає окремий workflow `Plugin Prerelease` з увімкненим gate release-validation. -Ручні запуски використовують унікальну concurrency group, тому повний набір для release-candidate не скасовується іншим push або PR-запуском на тому самому ref. Необов’язковий input `target_ref` дає змогу довіреному викликачеві запустити цей граф для branch, tag або повного commit SHA, використовуючи файл workflow з вибраного dispatch ref. +Ручні запускі використовують унікальну concurrency group, тому повний набір release-candidate не скасовується іншим push або PR run на тому самому ref. Необов’язковий вхід `target_ref` дає довіреному викликачеві змогу запускати цей граф для гілки, тега або повного SHA коміту, використовуючи файл workflow з вибраного dispatch ref. ```bash gh workflow run ci.yml --ref release/YYYY.M.D @@ -96,17 +96,17 @@ gh workflow run ci.yml --ref main -f target_ref= -f include_andro gh workflow run full-release-validation.yml --ref main -f ref= ``` -## Ранери +## Runners -| Ранер | Завдання | +| Runner | Завдання | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `ubuntu-24.04` | `preflight`, швидкі security jobs і агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі protocol/contract/bundled перевірки, шардовані перевірки контрактів каналів, шарди `check`, окрім lint, шарди й агрегати `check-additional`, верифікатори агрегатів Node-тестів, перевірки документації, Python skills, workflow-sanity, labeler, auto-response; install-smoke preflight також використовує Ubuntu, розміщений у GitHub, щоб матриця Blacksmith могла стати в чергу раніше | -| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, легші шарди Plugin, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` і `check-test-types` | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди Linux Node-тестів, шарди тестів bundled Plugin, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (достатньо CPU-чутливий, щоб 8 vCPU коштували дорожче, ніж заощаджували); install-smoke Docker-збірки (час очікування в черзі 32-vCPU коштував дорожче, ніж заощаджував) | +| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки протоколу/контрактів/bundled, шардовані перевірки контрактів каналів, шарди `check`, крім lint, шарди та агрегати `check-additional`, перевіряльники агрегатів Node tests, перевірки документації, Python skills, workflow-sanity, labeler, auto-response; install-smoke preflight також використовує GitHub-hosted Ubuntu, щоб Blacksmith matrix могла стати в чергу раніше | +| `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 tests, шарди bundled plugin tests, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (достатньо чутливий до CPU, щоб 8 vCPU коштували більше, ніж заощаджували); install-smoke Docker builds (час очікування в черзі для 32-vCPU коштував більше, ніж заощаджував) | | `blacksmith-16vcpu-windows-2025` | `checks-windows` | | `blacksmith-6vcpu-macos-latest` | `macos-node` на `openclaw/openclaw`; forks повертаються до `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; forks повертаються до `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; forks повертаються до `macos-latest` | ## Локальні еквіваленти @@ -144,26 +144,26 @@ gh workflow run openclaw-performance.yml --ref main -f profile=diagnostic -f rep gh workflow run openclaw-performance.yml --ref main -f profile=smoke -f repeat=1 -f deep_profile=true -f live_gpt54=true ``` -Workflow встановлює OCM із закріпленого release і Kova із закріпленого input `kova_ref`, а потім запускає три доріжки: +Workflow встановлює OCM із закріпленого релізу та Kova із закріпленого входу `kova_ref`, а потім запускає три lanes: -- `mock-provider`: діагностичні сценарії Kova проти local-build runtime з детермінованою фейковою OpenAI-сумісною автентифікацією. -- `mock-deep-profile`: CPU/heap/trace профілювання для startup, Gateway і hotspots agent-turn. -- `live-gpt54`: реальний agent turn OpenAI `openai/gpt-5.4`, який пропускається, коли `OPENAI_API_KEY` недоступний. +- `mock-provider`: діагностичні сценарії Kova проти runtime локальної збірки з детермінованою фейковою OpenAI-compatible auth. +- `mock-deep-profile`: профілювання CPU/heap/trace для startup, Gateway і гарячих точок agent-turn. +- `live-gpt54`: реальний turn агента OpenAI `openai/gpt-5.4`, який пропускається, коли `OPENAI_API_KEY` недоступний. -Кожна доріжка завантажує GitHub artifacts. Коли `CLAWGRIT_REPORTS_TOKEN` налаштовано, workflow також комітить `report.json`, `report.md`, bundles та `index.md` у `openclaw/clawgrit-reports` під `openclaw-performance//-//`. Поточний branch pointer записується як `openclaw-performance//latest-.json`. +Кожна lane завантажує GitHub artifacts. Коли `CLAWGRIT_REPORTS_TOKEN` налаштовано, workflow також комітить `report.json`, `report.md`, bundles і `index.md` до `openclaw/clawgrit-reports` у `openclaw-performance//-//`. Поточний branch pointer записується як `openclaw-performance//latest-.json`. -## Повна release-валідація +## Повна перевірка релізу -`Full Release Validation` — це ручний umbrella workflow для «запустити все перед release». Він приймає branch, tag або повний commit SHA, запускає ручний workflow `CI` із цією ціллю, запускає `Plugin Prerelease` для release-only proof Plugin/package/static/Docker і запускає `OpenClaw Release Checks` для install smoke, package acceptance, Docker release-path suites, live/E2E, OpenWebUI, QA Lab parity, Matrix і Telegram доріжок. З `rerun_group=all` і `release_profile=full` він також запускає `NPM Telegram Beta E2E` проти artifact `release-package-under-test` з release checks. Після публікації передайте `npm_telegram_package_spec`, щоб повторно запустити ту саму доріжку Telegram package проти опублікованого npm package. +`Full Release Validation` — це ручний umbrella workflow для «запустити все перед релізом». Він приймає гілку, тег або повний SHA коміту, запускає ручний workflow `CI` з цією ціллю, запускає `Plugin Prerelease` для release-only proof Plugin/package/static/Docker і запускає `OpenClaw Release Checks` для install smoke, package acceptance, наборів Docker release-path, live/E2E, OpenWebUI, QA Lab parity, Matrix і Telegram lanes. З `rerun_group=all` і `release_profile=full` він також запускає `NPM Telegram Beta E2E` проти artifact `release-package-under-test` з release checks. Після публікації передайте `npm_telegram_package_spec`, щоб повторно запустити ту саму Telegram package lane проти опублікованого npm package. -Див. [Повна release-валідація](/uk/reference/full-release-validation) для -матриці етапів, точних назв workflow jobs, відмінностей профілів, artifacts і +Див. [Повну перевірку релізу](/uk/reference/full-release-validation), щоб отримати +stage matrix, точні назви завдань workflow, відмінності профілів, artifacts і focused rerun handles. -`OpenClaw Release Publish` — це ручний mutating release workflow. Запустіть його -з `release/YYYY.M.D` або `main` після того, як release tag існує, і після того, -як OpenClaw npm preflight успішно завершився. Він перевіряє `pnpm plugins:sync:check`, -запускає `Plugin NPM Release` для всіх publishable Plugin packages, запускає +`OpenClaw Release Publish` — це ручний mutating release workflow. Запускайте його +з `release/YYYY.M.D` або `main` після того, як release tag існує, і після того, як +OpenClaw npm preflight успішно завершився. Він перевіряє `pnpm plugins:sync:check`, +запускає `Plugin NPM Release` для всіх publishable plugin packages, запускає `Plugin ClawHub Release` для того самого release SHA, і лише потім запускає `OpenClaw NPM Release` зі збереженим `preflight_run_id`. @@ -175,47 +175,40 @@ gh workflow run openclaw-release-publish.yml \ -f npm_dist_tag=beta ``` -Для pinned commit proof на branch, що швидко змінюється, використовуйте helper замість +Для proof закріпленого коміту на швидко змінюваній гілці використовуйте helper замість `gh workflow run ... --ref main -f ref=`: ```bash pnpm ci:full-release --sha ``` -GitHub workflow dispatch refs мають бути branches або tags, а не raw commit SHAs. -Helper пушить тимчасовий branch `release-ci/-...` на цільовому SHA, -запускає `Full Release Validation` із цього pinned ref, перевіряє, що кожен child -workflow `headSha` збігається з ціллю, і видаляє тимчасовий branch після завершення -запуску. Umbrella verifier також падає, якщо будь-який child workflow виконувався на -іншому SHA. +GitHub workflow dispatch refs мають бути гілками або тегами, а не сирими SHA комітів. Helper пушить тимчасову гілку `release-ci/-...` на цільовий SHA, запускає `Full Release Validation` із цього закріпленого ref, перевіряє, що кожен child workflow `headSha` збігається з ціллю, і видаляє тимчасову гілку, коли run завершується. Umbrella verifier також завершується з помилкою, якщо будь-який child workflow виконувався на іншому SHA. -`release_profile` керує широтою live/provider, що передається в release checks. Ручні -release workflows за замовчуванням використовують `stable`; використовуйте `full` лише тоді, коли ви -навмисно хочете широку advisory provider/media matrix. +`release_profile` керує шириною live/provider, що передається в release checks. Ручні release workflows за замовчуванням використовують `stable`; використовуйте `full` лише тоді, коли ви навмисно хочете широку advisory provider/media matrix. -- `minimum` зберігає найшвидші OpenAI/core release-critical доріжки. +- `minimum` залишає найшвидші OpenAI/core release-critical lanes. - `stable` додає stable provider/backend set. - `full` запускає широку advisory provider/media matrix. -Umbrella записує ids запущених child runs, а фінальне завдання `Verify full validation` повторно перевіряє поточні conclusions child runs і додає таблиці найповільніших jobs для кожного child run. Якщо child workflow повторно запущено і він став green, повторно запустіть лише parent verifier job, щоб оновити результат umbrella і timing summary. +Umbrella записує ids запущених child runs, а фінальне завдання `Verify full validation` повторно перевіряє поточні conclusions child runs і додає таблиці slowest-job для кожного child run. Якщо child workflow перезапущено і він став зеленим, перезапустіть лише parent verifier job, щоб оновити результат umbrella і підсумок timings. -Для відновлення і `Full Release Validation`, і `OpenClaw Release Checks` приймають `rerun_group`. Використовуйте `all` для реліз-кандидата, `ci` лише для звичайного дочірнього повного CI, `plugin-prerelease` лише для дочірнього передрелізу Plugin, `release-checks` для кожного дочірнього релізу або вужчу групу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` чи `npm-telegram` на парасольковому workflow. Це тримає повторний запуск невдалого релізного середовища обмеженим після сфокусованого виправлення. +Для відновлення `Full Release Validation` і `OpenClaw Release Checks` приймають `rerun_group`. Використовуйте `all` для реліз-кандидата, `ci` лише для звичайного дочірнього повного CI, `plugin-prerelease` лише для дочірнього попереднього релізу plugin, `release-checks` для кожного дочірнього релізу або вужчу групу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` або `npm-telegram` в umbrella. Це утримує повторний запуск невдалого релізного середовища в обмежених межах після цільового виправлення. -`OpenClaw Release Checks` використовує довірений ref workflow, щоб один раз розв’язати вибраний ref у tarball `release-package-under-test`, а потім передає цей артефакт і до Docker workflow live/E2E для релізного шляху, і до шарда приймання пакета. Це зберігає байти пакета узгодженими між релізними середовищами та уникає повторного пакування того самого кандидата в кількох дочірніх job. +`OpenClaw Release Checks` використовує довірене посилання workflow, щоб один раз розв’язати вибране посилання в tarball `release-package-under-test`, а потім передає цей артефакт і workflow Docker для live/E2E релізного шляху, і shard приймання пакета. Це зберігає однакові байти пакета в усіх релізних середовищах і уникає повторного пакування того самого кандидата в кількох дочірніх завданнях. Дублікати запусків `Full Release Validation` для `ref=main` і `rerun_group=all` -замінюють старіший парасольковий workflow. Батьківський монітор скасовує будь-який дочірній workflow, який -він уже запустив, коли батьківський workflow скасовано, тож новіша валідація main -не стоїть у черзі за застарілим двогодинним запуском release-check. Валідація релізної гілки/тега -та сфокусовані групи повторного запуску зберігають `cancel-in-progress: false`. +замінюють старіший umbrella. Батьківський монітор скасовує будь-який дочірній workflow, який +він уже надіслав, коли батьківський workflow скасовано, тому новіша валідація main +не стоїть за застарілим двогодинним запуском release-check. Валідація гілки/тега релізу +і цільові групи повторного запуску зберігають `cancel-in-progress: false`. -## Live та E2E шарди +## Live і E2E shards -Дочірній release live/E2E зберігає широке нативне покриття `pnpm test:live`, але запускає його як іменовані шарди через `scripts/test-live-shard.mjs` замість одного послідовного job: +Дочірній live/E2E для релізу зберігає широке нативне покриття `pnpm test:live`, але запускає його як іменовані shards через `scripts/test-live-shard.mjs` замість одного послідовного завдання: - `native-live-src-agents` - `native-live-src-gateway-core` -- відфільтровані за провайдерами job `native-live-src-gateway-profiles` +- завдання `native-live-src-gateway-profiles`, відфільтровані за провайдером - `native-live-src-gateway-backends` - `native-live-test` - `native-live-extensions-a-k` @@ -223,31 +216,31 @@ Umbrella записує ids запущених child runs, а фінальне - `native-live-extensions-openai` - `native-live-extensions-o-z-other` - `native-live-extensions-xai` -- розділені медіашарди audio/video та відфільтровані за провайдерами музичні шарди +- розділені shards аудіо/відео для медіа та shards музики, відфільтровані за провайдером -Це зберігає те саме файлове покриття, водночас спрощуючи повторний запуск і діагностику повільних збоїв live-провайдерів. Агреговані назви шардів `native-live-extensions-o-z`, `native-live-extensions-media` і `native-live-extensions-media-music` залишаються чинними для ручних одноразових повторних запусків. +Це зберігає те саме файлове покриття, водночас спрощуючи повторний запуск і діагностику повільних збоїв live-провайдерів. Агреговані назви shards `native-live-extensions-o-z`, `native-live-extensions-media` і `native-live-extensions-media-music` залишаються дійсними для ручних одноразових повторних запусків. -Нативні live-медіашарди запускаються в `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, зібраному workflow `Live Media Runner Image`. Цей образ попередньо встановлює `ffmpeg` і `ffprobe`; медіа job лише перевіряють двійкові файли перед налаштуванням. Тримайте live-набори з Docker на звичайних runner Blacksmith — container jobs є неправильним місцем для запуску вкладених Docker-тестів. +Нативні live media shards запускаються в `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, зібраному workflow `Live Media Runner Image`. Цей образ попередньо встановлює `ffmpeg` і `ffprobe`; медіа-завдання лише перевіряють двійкові файли перед налаштуванням. Залишайте live-набори з Docker-підтримкою на звичайних Blacksmith runners — container jobs є неправильним місцем для запуску вкладених Docker-тестів. -Live-шарди моделей/backend на базі Docker використовують окремий спільний образ `ghcr.io/openclaw/openclaw-live-test:` для кожного вибраного commit. Release live workflow збирає та публікує цей образ один раз, після чого Docker live model, provider-sharded gateway, CLI backend, ACP bind і Codex harness шарди запускаються з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Docker-шарди Gateway мають явні обмеження `timeout` на рівні скриптів нижче за timeout job workflow, щоб завислий контейнер або шлях очищення швидко падав, а не витрачав увесь бюджет release-check. Якщо ці шарди самостійно перебудовують повну source Docker target, релізний запуск налаштований неправильно й марнуватиме час на дубльовані збірки образів. +Live shards моделей/backend з Docker-підтримкою використовують окремий спільний образ `ghcr.io/openclaw/openclaw-live-test:` для кожного вибраного коміту. Workflow live-релізу збирає й публікує цей образ один раз, після чого Docker live shards для моделі, Gateway за провайдерами, backend CLI, ACP bind і Codex harness запускаються з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Docker shards Gateway мають явні обмеження `timeout` на рівні скриптів, нижчі за timeout завдання workflow, щоб завислий контейнер або шлях очищення швидко падав, а не споживав увесь бюджет release-check. Якщо ці shards перебудовують повну source Docker target незалежно, релізний запуск налаштовано неправильно, і він марнуватиме реальний час на дубльовані збірки образів. -## Приймання пакета +## Package Acceptance -Використовуйте `Package Acceptance`, коли питання звучить так: «чи працює цей інстальований пакет OpenClaw як продукт?» Це відрізняється від звичайного CI: звичайний CI перевіряє дерево вихідного коду, тоді як приймання пакета перевіряє один tarball через той самий Docker E2E harness, який користувачі задіюють після встановлення або оновлення. +Використовуйте `Package Acceptance`, коли питання таке: «чи працює цей інстальований пакет OpenClaw як продукт?» Це відрізняється від звичайного CI: звичайний CI перевіряє дерево source, тоді як package acceptance перевіряє один tarball через той самий Docker E2E harness, який користувачі застосовують після встановлення або оновлення. -### Jobs +### Завдання -1. `resolve_package` checkout-ить `workflow_ref`, розв’язує одного кандидата пакета, записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як артефакт `package-under-test` і друкує джерело, workflow ref, package ref, версію, SHA-256 та профіль у зведенні кроку GitHub. -2. `docker_acceptance` викликає `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і `package_artifact_name=package-under-test`. Багаторазовий workflow завантажує цей артефакт, перевіряє інвентар tarball, готує Docker-образи package-digest за потреби та запускає вибрані Docker lanes проти цього пакета замість пакування checkout workflow. Коли профіль вибирає кілька цільових `docker_lanes`, багаторазовий workflow готує пакет і спільні образи один раз, а потім розгортає ці lanes як паралельні цільові Docker jobs з унікальними артефактами. -3. `package_telegram` опційно викликає `NPM Telegram Beta E2E`. Він запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, коли Package Acceptance розв’язало його; самостійний Telegram dispatch усе ще може встановити опублікований npm spec. -4. `summary` провалює workflow, якщо розв’язання пакета, Docker-приймання або опційний Telegram lane завершилися невдало. +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`. Reusable workflow завантажує цей артефакт, перевіряє інвентар tarball, готує Docker-образи package-digest за потреби й запускає вибрані Docker lanes проти цього пакета замість пакування checkout workflow. Коли профіль вибирає кілька цільових `docker_lanes`, reusable workflow готує пакет і спільні образи один раз, а потім розгортає ці lanes як паралельні цільові Docker jobs з унікальними артефактами. +3. `package_telegram` опційно викликає `NPM Telegram Beta E2E`. Він запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, коли Package Acceptance розв’язав один; окремий dispatch Telegram усе ще може встановити опубліковану npm-специфікацію. +4. `summary` завершує workflow з помилкою, якщо розв’язання пакета, Docker acceptance або опційна Telegram lane завершилися невдало. ### Джерела кандидатів -- `source=npm` приймає лише `openclaw@beta`, `openclaw@latest` або точну релізну версію OpenClaw, як-от `openclaw@2026.4.27-beta.2`. Використовуйте це для приймання опублікованих beta/stable. -- `source=ref` пакує довірену гілку, тег або повний commit SHA `package_ref`. Resolver отримує гілки/теги OpenClaw, перевіряє, що вибраний commit досяжний з історії гілок репозиторію або релізного тега, встановлює залежності у від’єднаному worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`. +- `source=npm` приймає лише `openclaw@beta`, `openclaw@latest` або точну релізну версію OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для приймання опублікованих beta/stable. +- `source=ref` пакує довірену гілку, тег або повний SHA коміту `package_ref`. Resolver отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт досяжний з історії гілок репозиторію або релізного тега, встановлює залежності у від’єднаному worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`. - `source=url` завантажує HTTPS `.tgz`; `package_sha256` є обов’язковим. -- `source=artifact` завантажує один `.tgz` з `artifact_run_id` і `artifact_name`; `package_sha256` опційний, але його варто вказувати для зовнішньо поширених артефактів. +- `source=artifact` завантажує один `.tgz` з `artifact_run_id` і `artifact_name`; `package_sha256` є опційним, але його слід надавати для зовнішньо поширених артефактів. Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це довірений код workflow/harness, який запускає тест. `package_ref` — це source commit, який пакується, коли `source=ref`. Це дає змогу поточному test harness перевіряти старіші довірені source commits без запуску старої логіки workflow. @@ -256,28 +249,28 @@ Live-шарди моделей/backend на базі Docker використов - `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 +- `full` — повні chunks Docker релізного шляху з OpenWebUI - `custom` — точні `docker_lanes`; обов’язково, коли `suite_profile=custom` -Профіль `package` використовує офлайн-покриття Plugin, щоб валідація опублікованого пакета не залежала від live-доступності ClawHub. Опційний Telegram lane повторно використовує артефакт `package-under-test` у `NPM Telegram Beta E2E`, а шлях опублікованого npm spec зберігається для самостійних dispatch. +Профіль `package` використовує offline-покриття plugins, щоб валідація опублікованого пакета не залежала від live-доступності ClawHub. Опційна Telegram lane повторно використовує артефакт `package-under-test` у `NPM Telegram Beta E2E`, а шлях опублікованої npm-специфікації зберігається для окремих dispatches. -Щодо спеціальної політики тестування оновлень і Plugin, включно з локальними командами, -Docker lanes, вхідними параметрами Package Acceptance, релізними типовими значеннями та triage збоїв, -див. [Тестування оновлень і Plugin](/uk/help/testing-updates-plugins). +Для спеціальної політики тестування оновлень і plugins, зокрема локальних команд, +Docker lanes, inputs Package Acceptance, релізних defaults і triage збоїв, +див. [Тестування оновлень і plugins](/uk/help/testing-updates-plugins). -Release checks викликають Package Acceptance із `source=artifact`, підготовленим артефактом релізного пакета, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=release-history`, `published_upgrade_survivor_scenarios=reported-issues` і `telegram_mode=mock-openai`. Це тримає перевірку міграції пакета, оновлення, очищення застарілих залежностей Plugin, офлайн Plugin, plugin-update і Telegram на тому самому розв’язаному tarball пакета. Cross-OS release checks все ще покривають специфічні для ОС onboarding, installer і platform behavior; product-валідація пакета/оновлення має починатися з Package Acceptance. Docker lane `published-upgrade-survivor` перевіряє одну опубліковану baseline пакета за запуск. У Package Acceptance розв’язаний tarball `package-under-test` завжди є кандидатом, а `published_upgrade_survivor_baseline` вибирає fallback опубліковану baseline, типово `openclaw@latest`; команди повторного запуску failed-lane зберігають цю baseline. Установіть `published_upgrade_survivor_baselines=release-history`, щоб розгорнути lane на дедупліковану історичну матрицю: останні шість stable-релізів, `2026.4.23` і останній stable-реліз перед `2026-03-15`. Установіть `published_upgrade_survivor_scenarios=reported-issues`, щоб розгорнути ті самі baselines на fixtures у формі issue для конфігурації Feishu, збережених bootstrap/persona files, шляхів журналів із тильдою та застарілих коренів залежностей legacy Plugin. Окремий workflow `Update Migration` використовує Docker lane `update-migration` з `all-since-2026.4.23` і `plugin-deps-cleanup`, коли питання стосується вичерпного очищення опублікованого оновлення, а не звичайної широти Full Release CI. Локальні агреговані запуски можуть передавати точні package specs через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, зберігати один lane з `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, як-от `openclaw@2026.4.15`, або встановлювати `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` для scenario matrix. Опублікований lane налаштовує baseline за допомогою вбудованого рецепта команди `openclaw config set`, записує кроки рецепта в `summary.json` і перевіряє `/healthz`, `/readyz`, а також статус RPC після старту Gateway. Windows packaged і installer fresh lanes також перевіряють, що встановлений пакет може імпортувати browser-control override з raw absolute Windows path. Cross-OS agent-turn smoke OpenAI типово використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли встановлено, інакше `openai/gpt-5.4`, тож перевірка встановлення та Gateway лишається на тестовій моделі GPT-5, уникаючи типових значень GPT-4.x. +Release checks викликають Package Acceptance з `source=artifact`, підготовленим артефактом релізного пакета, `suite_profile=custom`, `docker_lanes='doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update'`, `published_upgrade_survivor_baselines=release-history`, `published_upgrade_survivor_scenarios=reported-issues` і `telegram_mode=mock-openai`. Це зберігає перевірку міграції пакета, оновлення, очищення застарілих залежностей plugins, відновлення встановлення налаштованих plugins, offline plugins, plugin-update і Telegram на тому самому розв’язаному package tarball. Cross-OS release checks усе ще покривають OS-specific onboarding, installer і поведінку платформи; продуктова валідація package/update має починатися з Package Acceptance. Docker lane `published-upgrade-survivor` перевіряє один baseline опублікованого пакета за запуск. У Package Acceptance розв’язаний tarball `package-under-test` завжди є кандидатом, а `published_upgrade_survivor_baseline` вибирає fallback published baseline, за замовчуванням `openclaw@latest`; команди повторного запуску failed-lane зберігають цей baseline. Встановіть `published_upgrade_survivor_baselines=release-history`, щоб розширити lane на дедупліковану матрицю історії: останні шість stable releases, `2026.4.23` і останній stable release перед `2026-03-15`. Встановіть `published_upgrade_survivor_scenarios=reported-issues`, щоб розширити ті самі baselines на issue-shaped fixtures для конфігурації Feishu, збережених файлів bootstrap/persona, встановлень налаштованих plugins OpenClaw, 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` для матриці сценаріїв. Published lane налаштовує baseline за допомогою вбудованого рецепта команди `openclaw config set`, записує кроки рецепта в `summary.json` і перевіряє `/healthz`, `/readyz`, а також статус RPC після запуску Gateway. Windows packaged і installer fresh lanes також перевіряють, що встановлений пакет може імпортувати browser-control override з raw absolute Windows path. Cross-OS agent-turn smoke для OpenAI за замовчуванням використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, коли він заданий, інакше `openai/gpt-5.4`, тож доказ встановлення й Gateway залишається на тестовій моделі GPT-5, уникаючи defaults GPT-4.x. -### Вікна сумісності legacy +### Вікна сумісності зі спадковими версіями -Package Acceptance має обмежені вікна legacy-сумісності для вже опублікованих пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть використовувати шлях сумісності: +Package Acceptance має обмежені вікна legacy-compatibility для вже опублікованих пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть використовувати шлях сумісності: -- відомі приватні QA entries у `dist/postinstall-inventory.json` можуть вказувати на файли, пропущені в tarball; -- `doctor-switch` може пропускати підвипадок persistence `gateway install --wrapper`, коли пакет не надає цей flag; -- `update-channel-switch` може прибирати відсутні `pnpm.patchedDependencies` із fake git fixture, похідної від tarball, і може логувати відсутній збережений `update.channel`; -- plugin smokes можуть читати legacy locations install-record або приймати відсутню persistence marketplace install-record; -- `plugin-update` може дозволяти міграцію metadata config, але все ще вимагати, щоб install record і поведінка no-reinstall залишалися незмінними. +- відомі приватні записи QA у `dist/postinstall-inventory.json` можуть указувати на файли, пропущені в tarball; +- `doctor-switch` може пропустити підвипадок збереження `gateway install --wrapper`, коли пакет не надає цей прапорець; +- `update-channel-switch` може вилучати відсутні `pnpm.patchedDependencies` з підробленої git fixture, виведеної з tarball, і може логувати відсутній збережений `update.channel`; +- plugin smokes можуть читати legacy locations install-record або приймати відсутнє збереження marketplace install-record; +- `plugin-update` може дозволяти міграцію config metadata, водночас усе ще вимагаючи, щоб install record і поведінка no-reinstall залишалися незмінними. -Опублікований пакет `2026.4.26` також може попереджати про локальні файли stamp метаданих збірки, які вже були shipped. Пізніші пакети мають відповідати сучасним контрактам; ті самі умови завершуються failure замість warning або skip. +Опублікований пакет `2026.4.26` також може попереджати про локальні файли штампів metadata збірки, які вже були відвантажені. Пізніші пакети мають відповідати сучасним контрактам; ті самі умови призводять до збою, а не до попередження чи пропуску. ### Приклади @@ -320,152 +313,152 @@ gh workflow run package-acceptance.yml \ -f docker_lanes='install-e2e plugin-update' ``` -Під час налагодження невдалого запуску приймання пакета починайте зі зведення `resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перевірте дочірній запуск `docker_acceptance` і його артефакти Docker: `.artifacts/docker-tests/**/summary.json`, `failures.json`, журнали ліній, часові показники фаз і команди повторного запуску. Надавайте перевагу повторному запуску невдалого профілю пакета або точних ліній Docker замість повторного запуску повної валідації релізу. +Коли налагоджуєте невдалий запуск приймання пакета, починайте зі зведення `resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перегляньте дочірній запуск `docker_acceptance` і його Docker-артефакти: `.artifacts/docker-tests/**/summary.json`, `failures.json`, журнали lane, таймінги фаз і команди повторного запуску. Надавайте перевагу повторному запуску невдалого профілю пакета або точних Docker lanes замість повторного запуску повної валідації релізу. -## Димова перевірка встановлення +## Smoke-перевірка встановлення -Окремий workflow `Install Smoke` повторно використовує той самий скрипт області через власне завдання `preflight`. Він розділяє покриття димової перевірки на `run_fast_install_smoke` і `run_full_install_smoke`. +Окремий робочий процес `Install Smoke` повторно використовує той самий scope-скрипт через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. -- **Швидкий шлях** запускається для pull request, які торкаються поверхонь Docker/пакетів, змін пакета/маніфесту bundled Plugin або поверхонь основного Plugin/каналу/Gateway/Plugin SDK, які перевіряють завдання димової перевірки Docker. Зміни лише у вихідному коді bundled Plugin, зміни лише тестів і зміни лише документації не резервують Docker workers. Швидкий шлях один раз збирає образ кореневого Dockerfile, перевіряє CLI, запускає CLI-димову перевірку agents delete shared-workspace, запускає container gateway-network e2e, перевіряє аргумент збірки bundled розширення та запускає обмежений Docker-профіль bundled-plugin із сукупним тайм-аутом команди 240 секунд (Docker-запуск кожного сценарію обмежується окремо). -- **Повний шлях** зберігає встановлення QR-пакета та Docker/update-покриття інсталятора для нічних запланованих запусків, ручних запусків, workflow-call перевірок релізу та pull request, які справді торкаються поверхонь інсталятора/пакета/Docker. У повному режимі install-smoke готує або повторно використовує один target-SHA GHCR образ димової перевірки кореневого Dockerfile, а потім запускає встановлення QR-пакета, димові перевірки кореневого Dockerfile/Gateway, димові перевірки інсталятора/update і швидкий bundled-plugin Docker E2E як окремі завдання, щоб робота інсталятора не чекала після димових перевірок кореневого образу. +- **Швидкий шлях** запускається для pull request, які зачіпають Docker/package поверхні, зміни пакетів/маніфестів bundled plugin або core plugin/channel/gateway/Plugin SDK поверхні, які перевіряють Docker smoke-завдання. Зміни лише у вихідному коді bundled plugin, правки лише тестів і правки лише документації не резервують Docker-воркери. Швидкий шлях один раз збирає образ кореневого Dockerfile, перевіряє CLI, запускає CLI smoke для видалення agents у спільному робочому просторі, запускає container gateway-network e2e, перевіряє build arg bundled extension і запускає обмежений bundled-plugin Docker profile із 240-секундним сукупним таймаутом команди (Docker-запуск кожного сценарію обмежено окремо). +- **Повний шлях** зберігає QR package install і installer Docker/update покриття для нічних запланованих запусків, ручних запусків, release checks через workflow-call і pull request, які справді зачіпають installer/package/Docker поверхні. У повному режимі install-smoke готує або повторно використовує один target-SHA GHCR root Dockerfile smoke image, потім запускає QR package install, root Dockerfile/gateway smokes, installer/update smokes і швидкий bundled-plugin Docker E2E як окремі завдання, щоб installer-робота не чекала за root image smokes. -Пуші в `main` (зокрема merge commits) не примушують повний шлях; коли логіка changed-scope запитала б повне покриття під час push, workflow зберігає швидку димову перевірку Docker і залишає повну димову перевірку встановлення для нічного запуску або валідації релізу. +Пуші в `main` (включно з merge commits) не примушують повний шлях; коли логіка changed-scope запитала б повне покриття під час push, робочий процес зберігає швидкий Docker smoke і залишає повний install smoke для нічного запуску або release validation. -Повільна димова перевірка Bun global install image-provider окремо обмежується через `run_bun_global_install_smoke`. Вона запускається за нічним розкладом і з workflow перевірок релізу, а ручні запуски `Install Smoke` можуть увімкнути її, але pull request і пуші в `main` цього не роблять. QR і Docker-тести інсталятора зберігають власні Dockerfile, зосереджені на встановленні. +Повільний Bun global install image-provider smoke окремо керується через `run_bun_global_install_smoke`. Він запускається за нічним розкладом і з робочого процесу release checks, а ручні запуски `Install Smoke` можуть увімкнути його, але pull request і пуші в `main` ні. QR і installer Docker tests зберігають власні Dockerfile, орієнтовані на встановлення. ## Локальний Docker E2E -`pnpm test:docker:all` попередньо збирає один спільний live-test образ, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`: +`pnpm test:docker:all` попередньо збирає один спільний live-test image, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`: -- bare Node/Git runner для ліній installer/update/plugin-dependency; -- функціональний образ, який встановлює той самий tarball у `/app` для звичайних функціональних ліній. +- базовий Node/Git runner для installer/update/plugin-dependency 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 lane розміщені в `scripts/lib/docker-e2e-scenarios.mjs`, логіка планувальника — у `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний план. Планувальник вибирає образ для кожної lane за допомогою `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1`. -### Параметри налаштування +### Налаштування -| Змінна | Типове значення | Призначення | -| ------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------- | -| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Кількість слотів main-pool для звичайних ліній. | -| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Кількість слотів tail-pool, чутливих до провайдерів. | -| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Ліміт одночасних live ліній, щоб провайдери не throttled. | -| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Ліміт одночасних ліній npm install. | -| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Ліміт одночасних multi-service ліній. | -| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Затримка між стартами ліній, щоб уникати бур створення Docker daemon; установіть `0`, щоб вимкнути затримку. | -| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Резервний тайм-аут для кожної лінії (120 хвилин); вибрані live/tail лінії використовують жорсткіші обмеження. | -| `OPENCLAW_DOCKER_ALL_DRY_RUN` | не задано | `1` виводить план планувальника без запуску ліній. | -| `OPENCLAW_DOCKER_ALL_LANES` | не задано | Список точних ліній, розділених комами; пропускає cleanup smoke, щоб агенти могли відтворити одну невдалу лінію. | +| Змінна | Типово | Призначення | +| ------------------------------------- | ------- | -------------------------------------------------------------------------------------------- | +| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Кількість слотів основного пулу для звичайних lanes. | +| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Кількість слотів tail-пулу, чутливого до провайдерів. | +| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Обмеження паралельних live lanes, щоб провайдери не throttled. | +| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Обмеження паралельних npm install lanes. | +| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Обмеження паралельних multi-service lanes. | +| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Затримка між стартами lanes, щоб уникнути create storms Docker daemon; задайте `0`, щоб вимкнути затримку. | +| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Резервний таймаут для кожної lane (120 хвилин); вибрані live/tail lanes використовують жорсткіші ліміти. | +| `OPENCLAW_DOCKER_ALL_DRY_RUN` | unset | `1` виводить план планувальника без запуску lanes. | +| `OPENCLAW_DOCKER_ALL_LANES` | unset | Розділений комами точний список lanes; пропускає cleanup smoke, щоб agents могли відтворити одну невдалу lane. | -Лінія, важча за свій ефективний ліміт, усе ще може стартувати з порожнього пулу, а потім працює сама, доки не звільнить capacity. Локальні сукупні preflight перевіряють Docker, видаляють застарілі контейнери OpenClaw E2E, виводять статус активних ліній, зберігають часові показники ліній для впорядкування longest-first і типово припиняють планувати нові pooled лінії після першої невдачі. +Lane, важча за свій ефективний ліміт, усе ще може стартувати з порожнього пулу, а потім працює сама, доки не звільнить capacity. Локальний aggregate виконує preflight Docker, видаляє застарілі OpenClaw E2E контейнери, виводить статус активних lanes, зберігає таймінги lanes для longest-first ordering і за замовчуванням припиняє планувати нові pooled lanes після першої помилки. -### Повторно використовуваний live/E2E workflow +### Багаторазовий live/E2E робочий процес -Повторно використовуваний live/E2E workflow запитує в `scripts/test-docker-all.mjs --plan-json`, яке покриття пакета, типу образу, live образу, лінії та облікових даних потрібне. Потім `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і зведення. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує артефакт пакета з поточного запуску, або завантажує артефакт пакета з `package_artifact_run_id`; перевіряє інвентар tarball; збирає та публікує package-digest-tagged bare/functional GHCR Docker E2E образи через кеш Docker layer Blacksmith, коли плану потрібні лінії з установленим пакетом; і повторно використовує надані input `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні package-digest образи замість повторної збірки. Завантаження Docker image повторюються з обмеженим 180-секундним тайм-аутом на спробу, щоб завислий registry/cache stream швидко повторився замість споживання більшої частини критичного шляху CI. +Багаторазовий live/E2E робочий процес запитує `scripts/test-docker-all.mjs --plan-json`, які package, image kind, live image, lane і credential coverage потрібні. Потім `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і summaries. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує package artifact поточного запуску, або завантажує package artifact з `package_artifact_run_id`; перевіряє inventory tarball; збирає й пушить package-digest-tagged bare/functional GHCR Docker E2E images через Docker layer cache Blacksmith, коли план потребує package-installed lanes; і повторно використовує надані inputs `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні package-digest images замість повторної збірки. Docker image pulls повторюються з обмеженим 180-секундним таймаутом на спробу, щоб завислий потік registry/cache швидко повторився, а не спожив більшість критичного шляху CI. -### Фрагменти release-path +### Чанки release-path -Docker-покриття релізу запускає менші chunked завдання з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk завантажував лише потрібний йому тип образу й виконував кілька ліній через той самий зважений планувальник: +Release Docker coverage запускає менші chunked jobs з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен chunk тягнув лише потрібний image kind і виконував кілька lanes через той самий weighted scheduler: - `OPENCLAW_DOCKER_ALL_PROFILE=release-path` - `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h` -Поточні Docker chunks релізу: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` і від `plugins-runtime-install-a` до `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` залишаються aggregate plugin/runtime aliases. Alias лінії `install-e2e` залишається aggregate manual rerun alias для обох provider installer lanes. +Поточні release Docker chunks: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services` і від `plugins-runtime-install-a` до `plugins-runtime-install-h`. `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` залишаються aggregate plugin/runtime aliases. Alias lane `install-e2e` залишається aggregate manual rerun alias для обох provider installer lanes. -OpenWebUI входить до `plugins-runtime-services`, коли повне release-path покриття запитує його, і зберігає окремий chunk `openwebui` лише для OpenWebUI-only dispatches. Лінії оновлення bundled-channel повторюють спробу один раз у разі transient npm network failures. +OpenWebUI входить до `plugins-runtime-services`, коли повне release-path coverage запитує його, і зберігає окремий chunk `openwebui` лише для OpenWebUI-only dispatches. Bundled-channel update lanes повторюються один раз у разі тимчасових npm network failures. -Кожен chunk вивантажує `.artifacts/docker-tests/` із журналами ліній, часовими показниками, `summary.json`, `failures.json`, часовими показниками фаз, JSON плану планувальника, таблицями повільних ліній і командами повторного запуску для кожної лінії. Input workflow `docker_lanes` запускає вибрані лінії проти підготовлених образів замість chunk jobs, що обмежує налагодження failed-lane одним цільовим Docker job і готує, завантажує або повторно використовує артефакт пакета для цього запуску; якщо вибрана лінія є live Docker lane, цільове завдання збирає live-test образ локально для цього rerun. Згенеровані GitHub команди повторного запуску для кожної лінії містять `package_artifact_run_id`, `package_artifact_name` і inputs підготовлених образів, коли ці значення існують, щоб невдала лінія могла повторно використати точний пакет і образи з невдалого запуску. +Кожен chunk завантажує `.artifacts/docker-tests/` з lane logs, timings, `summary.json`, `failures.json`, phase timings, scheduler plan JSON, slow-lane tables і per-lane rerun commands. Input робочого процесу `docker_lanes` запускає вибрані lanes проти підготовлених образів замість chunk jobs, що обмежує налагодження failed-lane одним цільовим Docker job і готує, завантажує або повторно використовує package artifact для цього запуску; якщо вибрана lane є live Docker lane, цільове завдання локально збирає live-test image для цього rerun. Згенеровані per-lane GitHub rerun commands включають `package_artifact_run_id`, `package_artifact_name` і inputs підготовлених образів, коли ці значення існують, щоб невдала lane могла повторно використати точний package і images з невдалого запуску. ```bash pnpm test:docker:rerun # download Docker artifacts and print combined/per-lane targeted rerun commands pnpm test:docker:timings # slow-lane and phase critical-path summaries ``` -Запланований live/E2E workflow щодня запускає повний release-path Docker suite. +Запланований live/E2E робочий процес щодня запускає повний release-path Docker suite. -## Plugin Prerelease +## Передреліз Plugin -`Plugin Prerelease` є дорожчим покриттям продукту/пакета, тому це окремий workflow, який запускається `Full Release Validation` або явним оператором. Звичайні pull request, пуші в `main` і standalone ручні CI dispatches тримають цей suite вимкненим. Він балансує тести bundled Plugin між вісьмома extension workers; ці extension shard jobs запускають до двох plugin config groups одночасно з одним Vitest worker на групу та більшим Node heap, щоб import-heavy plugin batches не створювали додаткові CI jobs. Release-only Docker prerelease path групує цільові Docker lanes у невеликі групи, щоб не резервувати десятки runners для завдань тривалістю від однієї до трьох хвилин. +`Plugin Prerelease` — дорожче product/package coverage, тому це окремий робочий процес, який запускається `Full Release Validation` або явним оператором. Звичайні pull request, пуші в `main` і окремі ручні CI dispatches тримають цей suite вимкненим. Він балансує bundled plugin tests між вісьмома extension workers; ці extension shard jobs запускають до двох plugin config groups одночасно з одним Vitest worker на group і більшим Node heap, щоб import-heavy plugin batches не створювали додаткові CI jobs. Release-only Docker prerelease path групує цільові Docker lanes у невеликі групи, щоб не резервувати десятки runners для одно-трихвилинних jobs. ## QA Lab -QA Lab має окремі CI lanes поза основним smart-scoped workflow. +QA Lab має dedicated CI lanes поза основним smart-scoped workflow. -- Workflow `Parity gate` запускається за відповідних змін PR і ручного dispatch; він збирає private QA runtime і порівнює mock GPT-5.5 та Opus 4.6 agentic packs. -- Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і під час ручного dispatch; він розгортає mock parity gate, live Matrix lane, а також live Telegram і Discord lanes як паралельні jobs. Live jobs використовують середовище `qa-live-shared`, а Telegram/Discord використовують Convex leases. +- Робочий процес `Parity gate` запускається за відповідних PR-змін і ручного dispatch; він збирає приватний QA runtime і порівнює mock GPT-5.5 та Opus 4.6 agentic packs. +- Робочий процес `QA-Lab - All Lanes` запускається щоночі на `main` і вручну; він розгортає mock parity gate, live Matrix lane, а також live Telegram і Discord lanes як паралельні jobs. Live jobs використовують середовище `qa-live-shared`, а Telegram/Discord використовують Convex leases. -Перевірки релізу запускають Matrix і Telegram live transport lanes із детермінованим mock provider і mock-qualified models (`mock-openai/gpt-5.5` і `mock-openai/gpt-5.5-alt`), щоб channel contract був ізольований від затримки live model і звичайного startup provider-plugin. Live transport gateway вимикає memory search, тому що QA parity окремо покриває поведінку пам’яті; provider connectivity покривається окремими live model, native provider і Docker provider suites. +Release checks запускають Matrix і Telegram live transport lanes з deterministic mock provider і mock-qualified models (`mock-openai/gpt-5.5` і `mock-openai/gpt-5.5-alt`), щоб channel contract був ізольований від live model latency і звичайного provider-plugin startup. Live transport gateway вимикає memory search, бо QA parity окремо покриває memory behavior; provider connectivity покривається окремими live model, native provider і Docker provider suites. -Matrix використовує `--profile fast` для scheduled і release gates, додаючи `--fail-fast` лише тоді, коли checked-out CLI підтримує це. Типове значення CLI і input ручного workflow залишаються `all`; ручний dispatch `matrix_profile=all` завжди розбиває повне Matrix coverage на jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. +Matrix використовує `--profile fast` для scheduled і release gates, додаючи `--fail-fast` лише коли checked-out CLI підтримує це. CLI default і manual workflow input залишаються `all`; ручний dispatch `matrix_profile=all` завжди шардить повне Matrix coverage на jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. -`OpenClaw Release Checks` також запускає release-critical QA Lab lanes перед release approval; його QA parity gate запускає candidate і baseline packs як паралельні lane jobs, а потім завантажує обидва artifacts у невеликий report job для фінального parity comparison. +`OpenClaw Release Checks` також запускає release-critical QA Lab lanes перед release approval; його QA parity gate запускає candidate і baseline packs як паралельні lane jobs, а потім завантажує обидва artifacts у невелике report job для фінального parity comparison. -Не ставте PR landing path за `Parity gate`, якщо зміна фактично не торкається QA runtime, model-pack parity або поверхні, якою володіє parity workflow. Для звичайних виправлень каналів, конфігурації, документації або unit-test розглядайте це як optional signal і дотримуйтеся scoped CI/check evidence. +Не ставте PR landing path за `Parity gate`, якщо зміна фактично не зачіпає QA runtime, model-pack parity або поверхню, якою володіє parity workflow. Для звичайних channel, config, docs або unit-test fixes вважайте це optional signal і спирайтеся на scoped CI/check evidence. ## CodeQL -Workflow `CodeQL` навмисно є вузьким first-pass security scanner, а не повним repository sweep. Щоденні, ручні та non-draft pull request guard runs сканують Actions workflow code плюс найризиковіші JavaScript/TypeScript surfaces із high-confidence security queries, відфільтрованими до high/critical `security-severity`. +Робочий процес `CodeQL` навмисно є вузьким first-pass security scanner, а не повним repository sweep. Daily, manual і non-draft pull request guard runs сканують Actions workflow code плюс найризикованіші JavaScript/TypeScript surfaces з high-confidence security queries, відфільтрованими до high/critical `security-severity`. -Pull request guard залишається легким: він стартує лише для змін у `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` або `src` і запускає ту саму high-confidence security matrix, що й scheduled workflow. Android і macOS CodeQL не входять до типових PR перевірок. +Pull request guard залишається легким: він стартує лише для змін у `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` або `src`, і запускає ту саму high-confidence security matrix, що й scheduled workflow. Android і macOS CodeQL залишаються поза PR defaults. ### Категорії безпеки -| Категорія | Поверхня | +| Категорія | Поверхня | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-security-high/core-auth-secrets` | Auth, secrets, sandbox, cron і базовий рівень gateway | -| `/codeql-security-high/channel-runtime-boundary` | Контракти реалізації основного каналу, а також runtime plugin каналу, gateway, Plugin SDK, secrets, точки дотику аудиту | -| `/codeql-security-high/network-ssrf-boundary` | Поверхні політики SSRF для core SSRF, розбору IP, network guard, web-fetch і Plugin SDK | -| `/codeql-security-high/mcp-process-tool-boundary` | MCP-сервери, помічники виконання процесів, вихідна доставка й шлюзи виконання інструментів агента | -| `/codeql-security-high/plugin-trust-boundary` | Поверхні довіри встановлення Plugin, loader, manifest, registry, package-manager install, source-loading і контракту пакета Plugin SDK | +| `/codeql-security-high/core-auth-secrets` | Auth, secrets, sandbox, Cron і базова лінія Gateway | +| `/codeql-security-high/channel-runtime-boundary` | Контракти реалізації основного каналу, а також середовище виконання Plugin каналу, Gateway, Plugin SDK, secrets, точки аудиту | +| `/codeql-security-high/network-ssrf-boundary` | Основні поверхні політики SSRF, розбору IP, мережевого захисту, web-fetch і SSRF у Plugin SDK | +| `/codeql-security-high/mcp-process-tool-boundary` | Сервери MCP, помічники виконання процесів, вихідна доставка та шлюзи виконання інструментів агента | +| `/codeql-security-high/plugin-trust-boundary` | Поверхні довіри для встановлення Plugin, завантажувача, маніфесту, реєстру, встановлення через package-manager, завантаження джерел і контракту пакета Plugin SDK | -### Shard-и безпеки для окремих платформ +### Платформо-специфічні безпекові шарди -- `CodeQL Android Critical Security` — запланований shard безпеки Android. Збирає Android app вручну для CodeQL на найменшому Blacksmith Linux runner, прийнятому workflow sanity. Завантажує в `/codeql-critical-security/android`. -- `CodeQL macOS Critical Security` — щотижневий/ручний shard безпеки macOS. Збирає macOS app вручну для CodeQL на Blacksmith macOS, відфільтровує результати збірки залежностей із завантаженого SARIF і завантажує в `/codeql-critical-security/macos`. Тримається поза щоденними типовими запуском, бо збірка macOS домінує за часом виконання навіть у чистому стані. +- `CodeQL Android Critical Security` — запланований безпековий шард Android. Збирає застосунок Android вручну для CodeQL на найменшому Blacksmith Linux runner, який приймає перевірка коректності workflow. Завантажує в `/codeql-critical-security/android`. +- `CodeQL macOS Critical Security` — щотижневий/ручний безпековий шард macOS. Збирає застосунок macOS вручну для CodeQL на Blacksmith macOS, відфільтровує результати збірки залежностей із завантаженого SARIF і завантажує в `/codeql-critical-security/macos`. Тримається поза щоденними стандартними перевірками, бо збірка macOS домінує за часом виконання навіть коли все чисто. ### Категорії Critical Quality -`CodeQL Critical Quality` — відповідний shard не пов’язаний із безпекою. Він запускає лише error-severity, non-security JavaScript/TypeScript quality-запити для вузьких цінних поверхонь на меншому Blacksmith Linux runner. Його захист pull request навмисно менший за запланований профіль: non-draft PR запускають лише відповідні shard-и `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` і `plugin-sdk-reply-runtime` для змін у коді виконання команд/моделей/інструментів агента та dispatch відповіді, схемі config/міграції/IO, auth/secrets/sandbox/security, основному каналі та runtime bundled channel plugin, gateway protocol/server-method, memory runtime/SDK glue, MCP/process/outbound delivery, provider runtime/model catalog, session diagnostics/delivery queues, plugin loader, Plugin SDK/package-contract або Plugin SDK reply runtime. Зміни CodeQL config і quality workflow запускають усі дванадцять PR quality shard-ів. +`CodeQL Critical Quality` — відповідний небезпековий шард. Він запускає лише JavaScript/TypeScript-запити якості з рівнем серйозності error і безпекою не пов'язані, на вузьких високовартісних поверхнях на меншому Blacksmith Linux runner. Його guard для pull request навмисно менший за запланований профіль: для PR не в статусі draft запускаються лише відповідні шарди `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` і `plugin-sdk-reply-runtime` для коду виконання команд/моделей/інструментів агента й dispatch відповіді, коду схеми/міграції/IO конфігурації, коду auth/secrets/sandbox/security, основного каналу та середовища виконання вбудованого Plugin каналу, протоколу Gateway/методу сервера, memory runtime/SDK glue, MCP/process/вихідної доставки, provider runtime/каталогу моделей, діагностики сесій/черг доставки, завантажувача Plugin, Plugin SDK/контракту пакета або змін у середовищі виконання відповідей Plugin SDK. Зміни конфігурації CodeQL і workflow якості запускають усі дванадцять quality-шардів PR. -Ручний dispatch приймає: +Ручний запуск приймає: ``` profile=all|agent-runtime-boundary|config-boundary|core-auth-secrets|channel-runtime-boundary|gateway-runtime-boundary|memory-runtime-boundary|mcp-process-runtime-boundary|plugin-boundary|plugin-sdk-package-contract|plugin-sdk-reply-runtime|provider-runtime-boundary|session-diagnostics-boundary ``` -Вузькі профілі — це навчальні/ітераційні hooks для запуску одного quality shard ізольовано. +Вузькі профілі — це hooks для навчання/ітерацій, щоб запускати один quality-шард ізольовано. -| Категорія | Поверхня | +| Категорія | Поверхня | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/codeql-critical-quality/core-auth-secrets` | Код межі безпеки Auth, secrets, sandbox, cron і gateway | -| `/codeql-critical-quality/config-boundary` | Контракти config schema, migration, normalization і IO | -| `/codeql-critical-quality/gateway-runtime-boundary` | Схеми Gateway protocol і контракти server method | -| `/codeql-critical-quality/channel-runtime-boundary` | Контракти реалізації основного каналу та bundled channel plugin | -| `/codeql-critical-quality/agent-runtime-boundary` | Runtime-контракти command execution, model/provider dispatch, auto-reply dispatch and queues і ACP control-plane | -| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-сервери та tool bridges, помічники process supervision і контракти outbound delivery | -| `/codeql-critical-quality/memory-runtime-boundary` | Memory host SDK, memory runtime facades, memory Plugin SDK aliases, glue активації memory runtime і команди memory doctor | -| `/codeql-critical-quality/session-diagnostics-boundary` | Внутрішня логіка reply queue, session delivery queues, помічники outbound session binding/delivery, поверхні diagnostic event/log bundle і контракти session doctor CLI | -| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Plugin SDK inbound reply dispatch, reply payload/chunking/runtime helpers, channel reply options, delivery queues і session/thread binding helpers | -| `/codeql-critical-quality/provider-runtime-boundary` | Нормалізація model catalog, provider auth and discovery, provider runtime registration, provider defaults/catalogs і registry web/search/fetch/embedding | -| `/codeql-critical-quality/ui-control-plane` | Control UI bootstrap, local persistence, gateway control flows і runtime-контракти task control-plane | -| `/codeql-critical-quality/web-media-runtime-boundary` | Runtime-контракти core web fetch/search, media IO, media understanding, image-generation і media-generation | -| `/codeql-critical-quality/plugin-boundary` | Контракти entrypoint для loader, registry, public-surface і Plugin SDK | -| `/codeql-critical-quality/plugin-sdk-package-contract` | Опублікований package-side вихідний код Plugin SDK і помічники контрактів plugin package | +| `/codeql-critical-quality/core-auth-secrets` | Auth, secrets, sandbox, Cron і код безпекової межі Gateway | +| `/codeql-critical-quality/config-boundary` | Схема конфігурації, міграція, нормалізація та IO-контракти | +| `/codeql-critical-quality/gateway-runtime-boundary` | Схеми протоколу Gateway і контракти методів сервера | +| `/codeql-critical-quality/channel-runtime-boundary` | Контракти реалізації основного каналу та вбудованого Plugin каналу | +| `/codeql-critical-quality/agent-runtime-boundary` | Виконання команд, dispatch моделі/провайдера, dispatch і черги auto-reply, а також runtime-контракти control-plane ACP | +| `/codeql-critical-quality/mcp-process-runtime-boundary` | Сервери MCP та мости інструментів, помічники нагляду за процесами й контракти вихідної доставки | +| `/codeql-critical-quality/memory-runtime-boundary` | Memory host SDK, фасади memory runtime, псевдоніми memory Plugin SDK, glue активації memory runtime і команди memory doctor | +| `/codeql-critical-quality/session-diagnostics-boundary` | Внутрішня логіка черги відповідей, черги доставки сесій, помічники прив'язування/доставки вихідних сесій, поверхні діагностичних подій/пакетів логів і контракти CLI session doctor | +| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Dispatch вхідних відповідей Plugin SDK, payload/chunking/runtime-помічники відповідей, параметри відповідей каналів, черги доставки та помічники прив'язування сесій/тредів | +| `/codeql-critical-quality/provider-runtime-boundary` | Нормалізація каталогу моделей, auth і виявлення провайдера, реєстрація provider runtime, defaults/каталоги провайдера та реєстри web/search/fetch/embedding | +| `/codeql-critical-quality/ui-control-plane` | Bootstrap Control UI, локальна персистентність, control flows Gateway і runtime-контракти task control-plane | +| `/codeql-critical-quality/web-media-runtime-boundary` | Основні runtime-контракти web fetch/search, media IO, розуміння медіа, генерації зображень і генерації медіа | +| `/codeql-critical-quality/plugin-boundary` | Контракти завантажувача, реєстру, публічної поверхні та entrypoint Plugin SDK | +| `/codeql-critical-quality/plugin-sdk-package-contract` | Опубліковані джерела Plugin SDK на боці пакета та помічники контракту пакета Plugin | -Quality лишається окремою від security, щоб findings якості можна було планувати, вимірювати, вимикати або розширювати без затемнення сигналу безпеки. Розширення CodeQL для Swift, Python і bundled-plugin слід додавати назад як scoped або sharded follow-up work лише після того, як вузькі профілі матимуть стабільний runtime і signal. +Quality тримається окремо від security, щоб findings якості можна було планувати, вимірювати, вимикати або розширювати без затемнення безпекового сигналу. Розширення CodeQL для Swift, Python і вбудованих Plugin слід додавати назад як scoped або sharded follow-up work лише після того, як вузькі профілі матимуть стабільний runtime і сигнал. -## Workflows обслуговування +## Workflow супроводу ### Docs Agent -Workflow `Docs Agent` — це подієва maintenance lane Codex для підтримання наявної документації у відповідності з нещодавно злитими змінами. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, а manual dispatch може запустити його напряму. Виклики workflow-run пропускаються, коли `main` уже зрушив далі або коли інший non-skipped Docs Agent run було створено протягом останньої години. Коли він запускається, він переглядає діапазон комітів від попереднього non-skipped Docs Agent source SHA до поточного `main`, тож один hourly run може охопити всі зміни main, накопичені з останнього проходу docs. +Workflow `Docs Agent` — це подієво-керований lane супроводу Codex для підтримання наявної документації узгодженою з нещодавно внесеними змінами. Він не має чистого розкладу: успішний CI-запуск push від не-бота на `main` може його запустити, а ручний dispatch може запустити його напряму. Виклики через workflow-run пропускаються, коли `main` уже зсунувся або коли за останню годину вже було створено інший непропущений запуск Docs Agent. Коли він запускається, він переглядає діапазон комітів від попереднього SHA джерела непропущеного Docs Agent до поточного `main`, тож один погодинний запуск може покрити всі зміни main, накопичені з останнього проходу документації. ### Test Performance Agent -Workflow `Test Performance Agent` — це подієва maintenance lane Codex для повільних тестів. Він не має чистого розкладу: успішний non-bot push CI run на `main` може його запустити, але він пропускається, якщо інший workflow-run invocation уже запускався або виконується в цей UTC-день. Manual dispatch обходить цей daily activity gate. Lane будує full-suite grouped Vitest performance report, дозволяє Codex вносити лише невеликі performance fixes тестів зі збереженням coverage замість широких refactors, потім повторно запускає full-suite report і відхиляє зміни, які зменшують baseline test count, що проходить. Якщо baseline має failing tests, Codex може виправляти лише очевидні failures, а after-agent full-suite report має пройти, перш ніж щось буде закомічено. Коли `main` просувається до того, як bot push буде злитий, lane rebases validated patch, повторно запускає `pnpm check:changed` і повторює push; конфліктні stale patches пропускаються. Він використовує GitHub-hosted Ubuntu, щоб Codex action могла зберегти таку саму drop-sudo safety posture, як docs agent. +Workflow `Test Performance Agent` — це подієво-керований lane супроводу Codex для повільних тестів. Він не має чистого розкладу: успішний CI-запуск push від не-бота на `main` може його запустити, але він пропускається, якщо інший виклик workflow-run уже запускався або виконується цього UTC-дня. Ручний dispatch обходить цей денний activity gate. Lane збирає згрупований звіт продуктивності Vitest для повного набору, дозволяє Codex робити лише невеликі виправлення продуктивності тестів зі збереженням покриття замість широких refactors, потім повторно запускає звіт повного набору й відхиляє зміни, що зменшують базову кількість прохідних тестів. Якщо в базовій лінії є failing tests, Codex може виправляти лише очевидні failures, а after-agent 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 після merge +### Duplicate PRs After Merge -Workflow `Duplicate PRs After Merge` — це ручний maintainer workflow для post-land duplicate cleanup. Типово це dry-run, і він закриває лише явно перелічені PR, коли `apply=true`. Перед зміною GitHub він перевіряє, що landed PR merged, і що кожен duplicate має або спільний referenced issue, або overlapping changed hunks. +Workflow `Duplicate PRs After Merge` — це ручний workflow maintainer для cleanup дублікатів після landing. За замовчуванням він працює в dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед мутацією GitHub він перевіряє, що landed PR змарджений і що кожен duplicate має або спільну referenced issue, або overlapping changed hunks. ```bash gh workflow run duplicate-after-merge.yml \ @@ -474,29 +467,29 @@ gh workflow run duplicate-after-merge.yml \ -f apply=true ``` -## Local check gates і changed routing +## Локальні check gates і changed routing -Local changed-lane logic живе в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей local check gate суворіший щодо architecture boundaries, ніж широкий scope платформи CI: +Локальна логіка changed-lane живе в `scripts/changed-lanes.mjs` і виконується `scripts/check-changed.mjs`. Цей локальний check gate суворіший щодо архітектурних меж, ніж широкий platform scope CI: -- core production changes запускають core prod і core test typecheck плюс core lint/guards; -- core test-only changes запускають лише core test typecheck плюс core lint; -- extension production changes запускають extension prod і extension test typecheck плюс extension lint; -- extension test-only changes запускають extension test typecheck плюс extension lint; -- public Plugin SDK або plugin-contract changes розширюються до extension typecheck, бо extensions залежать від цих core contracts (Vitest extension sweeps лишаються явною test work); -- release metadata-only version bumps запускають targeted version/config/root-dependency checks; -- unknown root/config changes fail safe до всіх check lanes. +- зміни core production запускають typecheck core prod і core test плюс core lint/guards; +- зміни лише core tests запускають тільки typecheck core test плюс core lint; +- зміни extension production запускають typecheck extension prod і extension test плюс extension lint; +- зміни лише extension tests запускають 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; +- невідомі зміни root/config fail safe до всіх check lanes. -Local changed-test routing живе в `scripts/test-projects.test-support.mjs` і навмисно дешевший за `check:changed`: прямі test edits запускають самі себе, source edits віддають перевагу explicit mappings, потім sibling tests і import-graph dependents. Shared group-room delivery config — одне з explicit mappings: зміни до group visible-reply config, source reply delivery mode або message-tool system prompt проходять через core reply tests плюс Discord і Slack delivery regressions, щоб shared default change впала до першого PR push. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли зміна достатньо harness-wide, що cheap mapped set не є надійним proxy. +Локальний changed-test routing живе в `scripts/test-projects.test-support.mjs` і навмисно дешевший за `check:changed`: прямі зміни тестів запускають самі себе, зміни джерел віддають перевагу явним mappings, потім sibling tests і import-graph dependents. Конфігурація shared group-room delivery — один з явних mappings: зміни до group visible-reply config, source reply delivery mode або message-tool system prompt маршрутизуються через core reply tests плюс delivery regressions Discord і Slack, щоб shared default change зламався до першого PR push. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише коли зміна настільки harness-wide, що дешевий mapped set не є надійним proxy. ## Валідація Testbox -Запускайте Testbox з кореня repo і віддавайте перевагу свіжому warmed box для широкого proof. Перед витратою повільного gate на box, який повторно використали, термін дії якого минув або який щойно повідомив про несподівано великий sync, спершу запустіть `pnpm testbox:sanity` всередині box. +Запускайте Testbox з кореня репозиторію і віддавайте перевагу свіжому warmed box для broad proof. Перед витрачанням повільного gate на box, який був reused, expired або щойно повідомив про неочікувано великий sync, спершу запустіть `pnpm testbox:sanity` всередині box. -Sanity check швидко падає, коли обов’язкові root files, такі як `pnpm-lock.yaml`, зникли або коли `git status --short` показує щонайменше 200 tracked deletions. Зазвичай це означає, що remote sync state не є надійною копією PR; зупиніть цей box і прогрійте свіжий замість налагодження product test failure. Для навмисних PR із великим видаленням задайте `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього sanity run. +Sanity check швидко падає, коли потрібні root files, як-от `pnpm-lock.yaml`, зникли або коли `git status --short` показує щонайменше 200 tracked deletions. Зазвичай це означає, що remote sync state не є trustworthy copy PR; зупиніть цей box і warmed fresh one замість debugging product test failure. Для навмисних PR із large-deletion встановіть `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього sanity run. -`pnpm testbox:run` також завершує локальний виклик Blacksmith CLI, який залишається у фазі синхронізації понад п’ять хвилин без виводу після синхронізації. Установіть `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, щоб вимкнути цей захист, або використайте більше значення в мілісекундах для незвично великих локальних змін. +`pnpm testbox:run` також завершує локальний виклик Blacksmith CLI, який залишається на етапі синхронізації понад п’ять хвилин без виводу після синхронізації. Установіть `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, щоб вимкнути цей захист, або використайте більше значення в мілісекундах для незвично великих локальних diff. -Crabbox — це другий, належний репозиторію, шлях віддаленої машини для підтвердження в Linux, коли Blacksmith недоступний або коли бажаніше використовувати власну хмарну ємність. Прогрійте машину, гідруйте її через робочий процес проєкту, а потім запускайте команди через Crabbox CLI: +Crabbox — це другий, належний репозиторію шлях віддаленого бокса для підтвердження в Linux, коли Blacksmith недоступний або коли бажано використовувати власну хмарну місткість. Прогрійте бокс, гідруйте його через workflow проєкту, а потім виконуйте команди через Crabbox CLI: ```bash pnpm crabbox:warmup -- --idle-timeout 90m @@ -505,9 +498,9 @@ pnpm crabbox:run -- --id --shell "OPENCLAW_TESTBOX=1 pnpm check:changed pnpm crabbox:stop -- ``` -`.crabbox.yaml` визначає типові параметри провайдера, синхронізації та гідратації GitHub Actions. Він виключає локальний `.git`, щоб гідрований checkout Actions зберігав власні віддалені Git-метадані замість синхронізації локальних для мейнтейнера remote і сховищ об’єктів, а також виключає локальні runtime/build-артефакти, які ніколи не слід передавати. `.github/workflows/crabbox-hydrate.yml` визначає checkout, налаштування Node/pnpm, fetch `origin/main` і передавання несекретного середовища, яке пізніші команди `crabbox run --id ` використовують як джерело. +`.crabbox.yaml` визначає типові параметри провайдера, синхронізації та гідрації GitHub Actions. Він виключає локальний `.git`, щоб гідрований checkout Actions зберігав власні віддалені метадані Git замість синхронізації локальних для мейнтейнера remotes і сховищ об’єктів, а також виключає локальні артефакти виконання/збирання, які ніколи не слід передавати. `.github/workflows/crabbox-hydrate.yml` визначає checkout, налаштування Node/pnpm, отримання `origin/main` і передавання несекретного середовища, яке пізніші команди `crabbox run --id ` використовують як джерело. ## Пов’язане -- [Огляд встановлення](/uk/install) +- [Огляд інсталяції](/uk/install) - [Канали розробки](/uk/install/development-channels) diff --git a/docs/uk/cli/doctor.md b/docs/uk/cli/doctor.md index 20ab32ab5..af6a56a31 100644 --- a/docs/uk/cli/doctor.md +++ b/docs/uk/cli/doctor.md @@ -1,14 +1,14 @@ --- read_when: - - У вас проблеми з підключенням чи автентифікацією, і ви хочете покроково усунути їх - - Ви оновили й хочете швидку перевірку -summary: Довідка CLI для `openclaw doctor` (перевірки працездатності + керовані виправлення) + - У вас проблеми з підключенням або автентифікацією, і ви хочете отримати покрокові виправлення + - Ви оновили й хочете виконати базову перевірку +summary: Довідник CLI для `openclaw doctor` (перевірки справності + керовані виправлення) title: Діагностика x-i18n: - generated_at: "2026-05-02T03:33:34Z" + generated_at: "2026-05-02T15:57:48Z" model: gpt-5.5 provider: openai - source_hash: e861fa105737088eafa55815faa1a37ccd61e154e8dbe811cf4b988bc1c571e5 + source_hash: 90da8ffd705cd517fb90367164cc6af3e551befcec15c91746aa1e1e39454f09 source_path: cli/doctor.md workflow: 16 --- @@ -35,42 +35,42 @@ openclaw doctor --generate-gateway-token ## Параметри - `--no-workspace-suggestions`: вимкнути підказки пам’яті/пошуку робочого простору -- `--yes`: приймати типові значення без запитів -- `--repair`: застосувати рекомендовані виправлення, не пов’язані із сервісами, без запитів; установлення та перезапис сервісів Gateway усе ще потребують інтерактивного підтвердження або явних команд Gateway +- `--yes`: приймати значення за замовчуванням без запитів +- `--repair`: застосувати рекомендовані виправлення, не пов’язані із сервісом, без запитів; встановлення й перезапис сервісу Gateway все одно потребують інтерактивного підтвердження або явних команд Gateway - `--fix`: псевдонім для `--repair` -- `--force`: застосувати агресивні виправлення, зокрема перезапис власної конфігурації сервісу, коли це потрібно -- `--non-interactive`: запускати без запитів; лише безпечні міграції та виправлення, не пов’язані із сервісами +- `--force`: застосувати агресивні виправлення, зокрема перезапис власної конфігурації сервісу за потреби +- `--non-interactive`: запускати без запитів; лише безпечні міграції та виправлення, не пов’язані із сервісом - `--generate-gateway-token`: згенерувати й налаштувати токен Gateway -- `--deep`: просканувати системні сервіси на наявність додаткових установлень Gateway +- `--deep`: просканувати системні сервіси на наявність додаткових встановлень Gateway Примітки: -- Інтерактивні запити (наприклад, виправлення keychain/OAuth) запускаються лише тоді, коли stdin є TTY і `--non-interactive` **не** задано. Запуски без інтерфейсу (cron, Telegram, без термінала) пропускатимуть запити. -- Продуктивність: неінтерактивні запуски `doctor` пропускають завчасне завантаження Plugin, щоб перевірки справності без інтерфейсу залишалися швидкими. Інтерактивні сеанси й надалі повністю завантажують Plugin, коли перевірці потрібен їхній внесок. -- `--fix` (псевдонім для `--repair`) записує резервну копію в `~/.openclaw/openclaw.json.bak` і вилучає невідомі ключі конфігурації, перелічуючи кожне вилучення. -- `doctor --fix --non-interactive` повідомляє про відсутні або застарілі визначення сервісу Gateway, але не встановлює й не перезаписує їх поза режимом виправлення оновлення. Запустіть `openclaw gateway install` для відсутнього сервісу або `openclaw gateway install --force`, коли ви навмисно хочете замінити launcher. +- Інтерактивні запити (наприклад, виправлення keychain/OAuth) виконуються лише тоді, коли stdin є TTY і `--non-interactive` **не** задано. Запуски без інтерфейсу (cron, Telegram, без термінала) пропускатимуть запити. +- Продуктивність: неінтерактивні запуски `doctor` пропускають завчасне завантаження plugin, щоб перевірки справності без інтерфейсу залишалися швидкими. Інтерактивні сеанси все одно повністю завантажують plugins, коли перевірці потрібен їхній внесок. +- `--fix` (псевдонім для `--repair`) записує резервну копію в `~/.openclaw/openclaw.json.bak` і видаляє невідомі ключі конфігурації, перелічуючи кожне видалення. +- `doctor --fix --non-interactive` повідомляє про відсутні або застарілі визначення сервісу Gateway, але не встановлює й не перезаписує їх поза режимом відновлення оновлення. Запустіть `openclaw gateway install` для відсутнього сервісу або `openclaw gateway install --force`, коли ви навмисно хочете замінити засіб запуску. - Перевірки цілісності стану тепер виявляють осиротілі файли транскриптів у каталозі сеансів. Архівування їх як `.deleted.` потребує інтерактивного підтвердження; `--fix`, `--yes` і запуски без інтерфейсу залишають їх на місці. -- Doctor також сканує `~/.openclaw/cron/jobs.json` (або `cron.store`) на наявність застарілих форм завдань cron і може перезаписати їх на місці до того, як планувальник муситиме автоматично нормалізувати їх під час виконання. -- На Linux doctor попереджає, коли crontab користувача все ще запускає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`; цей скрипт більше не підтримується і може журналювати хибні збої Gateway WhatsApp, коли cron не має середовища користувацької шини systemd. -- Doctor очищує застарілий проміжний стан залежностей Plugin, створений старішими версіями OpenClaw. Він також виправляє відсутні налаштовані завантажувані Plugin, коли реєстр може їх розв’язати. -- Doctor виправляє застарілу конфігурацію Plugin, вилучаючи відсутні ідентифікатори Plugin з `plugins.allow`/`plugins.entries`, а також відповідні завислі конфігурації каналів, цілі Heartbeat і перевизначення моделей каналів, коли виявлення Plugin працює справно. -- Doctor поміщає недійсну конфігурацію Plugin у карантин, вимикаючи відповідний запис `plugins.entries.` і вилучаючи його недійсне навантаження `config`. Запуск Gateway уже пропускає лише цей несправний Plugin, тож інші Plugin і канали можуть продовжувати працювати. -- Задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли інший supervisor керує життєвим циклом Gateway. Doctor і надалі повідомляє про справність Gateway/сервісу та застосовує виправлення, не пов’язані із сервісами, але пропускає встановлення/запуск/перезапуск/bootstrap сервісу й очищення застарілих сервісів. -- На Linux doctor ігнорує неактивні додаткові systemd-юніти, схожі на Gateway, і не перезаписує метадані команди/точки входу для запущеного systemd-сервісу Gateway під час виправлення. Спершу зупиніть сервіс або використайте `openclaw gateway install --force`, коли ви навмисно хочете замінити активний launcher. -- Doctor автоматично мігрує застарілу плоску конфігурацію Talk (`talk.voiceId`, `talk.modelId` та споріднені) у `talk.provider` + `talk.providers.`. -- Повторні запуски `doctor --fix` більше не повідомляють і не застосовують нормалізацію Talk, коли єдина відмінність полягає в порядку ключів об’єкта. -- Doctor включає перевірку готовності пошуку в пам’яті та може рекомендувати `openclaw configure --section model`, коли відсутні облікові дані embedding. -- Doctor попереджає, коли не налаштовано власника команд. Власник команд — це обліковий запис оператора-людини, якому дозволено запускати команди лише для власника та схвалювати небезпечні дії. Спарювання DM лише дає змогу комусь спілкуватися з ботом; якщо ви схвалили відправника до появи bootstrap першого власника, задайте `commands.ownerAllowFrom` явно. -- Doctor попереджає, коли налаштовано агентів у режимі Codex і в Codex home оператора існують особисті ресурси Codex CLI. Локальні запуски сервера застосунку Codex використовують ізольовані домівки для кожного агента, тому використовуйте `openclaw migrate codex --dry-run`, щоб інвентаризувати ресурси, які слід свідомо підвищити. -- Якщо режим sandbox увімкнено, але Docker недоступний, doctor повідомляє високосигнальне попередження з усуненням (`install Docker` або `openclaw config set agents.defaults.sandbox.mode off`). -- Якщо `gateway.auth.token`/`gateway.auth.password` керуються SecretRef і недоступні в поточному шляху команди, doctor повідомляє попередження лише для читання і не записує резервні облікові дані відкритим текстом. -- Якщо інспекція SecretRef каналу зазнає невдачі в шляху виправлення, doctor продовжує роботу й повідомляє попередження замість дострокового виходу. -- Після міграцій каталогу стану doctor попереджає, коли ввімкнені типові облікові записи Telegram або Discord залежать від резервного env, а `TELEGRAM_BOT_TOKEN` або `DISCORD_BOT_TOKEN` недоступні процесу doctor. -- Автоматичне розв’язання імен користувачів Telegram `allowFrom` (`doctor --fix`) потребує розв’язуваного токена Telegram у поточному шляху команди. Якщо інспекція токена недоступна, doctor повідомляє попередження й пропускає автоматичне розв’язання для цього проходу. +- Doctor також сканує `~/.openclaw/cron/jobs.json` (або `cron.store`) на наявність застарілих форм завдань cron і може перезаписати їх на місці до того, як планувальнику доведеться автоматично нормалізувати їх під час виконання. +- У Linux doctor попереджає, коли crontab користувача все ще запускає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`; цей скрипт більше не підтримується й може журналювати хибні збої Gateway WhatsApp, коли cron не має середовища user-bus systemd. +- Doctor очищає застарілий стан підготовки залежностей plugin, створений старішими версіями OpenClaw. Він також відновлює відсутні налаштовані завантажувані plugins, коли реєстр може їх визначити, а прохід doctor 2026.5.2 автоматично встановлює завантажувані plugins, які вже використовує старіша конфігурація, перш ніж позначати конфігурацію зміненою для цього релізу. +- Doctor виправляє застарілу конфігурацію plugin, видаляючи відсутні ідентифікатори plugin з `plugins.allow`/`plugins.entries`, а також відповідну висячу конфігурацію каналу, цілі Heartbeat і перевизначення моделей каналів, коли виявлення plugin справне. +- Doctor ізолює недійсну конфігурацію plugin, вимикаючи відповідний запис `plugins.entries.` і видаляючи його недійсне корисне навантаження `config`. Запуск Gateway уже пропускає лише цей несправний plugin, тож інші plugins і канали можуть продовжувати працювати. +- Установіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли інший супервізор керує життєвим циклом Gateway. Doctor усе одно повідомляє про справність Gateway/сервісу й застосовує виправлення, не пов’язані із сервісом, але пропускає встановлення/запуск/перезапуск/bootstrap сервісу та очищення застарілого сервісу. +- У Linux doctor ігнорує неактивні додаткові systemd units, схожі на Gateway, і не перезаписує метадані команди/точки входу для запущеного сервісу Gateway systemd під час виправлення. Спершу зупиніть сервіс або скористайтеся `openclaw gateway install --force`, коли ви навмисно хочете замінити активний засіб запуску. +- Doctor автоматично мігрує застарілу пласку конфігурацію Talk (`talk.voiceId`, `talk.modelId` тощо) у `talk.provider` + `talk.providers.`. +- Повторні запуски `doctor --fix` більше не повідомляють і не застосовують нормалізацію Talk, коли єдина відмінність — порядок ключів об’єкта. +- Doctor містить перевірку готовності пошуку в пам’яті й може рекомендувати `openclaw configure --section model`, коли облікові дані embedding відсутні. +- Doctor попереджає, коли власника команд не налаштовано. Власник команд — це обліковий запис людини-оператора, якому дозволено запускати команди лише для власника й схвалювати небезпечні дії. Сполучення через DM лише дає комусь змогу спілкуватися з ботом; якщо ви схвалили відправника до появи bootstrap першого власника, явно задайте `commands.ownerAllowFrom`. +- Doctor попереджає, коли налаштовано агентів у режимі Codex і в Codex home оператора існують особисті ресурси Codex CLI. Локальні запуски app-server Codex використовують ізольовані домівки для кожного агента, тож використовуйте `openclaw migrate codex --dry-run`, щоб інвентаризувати ресурси, які слід просувати свідомо. +- Якщо режим sandbox увімкнено, але Docker недоступний, doctor повідомляє високосигнальне попередження з виправленням (`install Docker` або `openclaw config set agents.defaults.sandbox.mode off`). +- Якщо `gateway.auth.token`/`gateway.auth.password` керуються SecretRef і недоступні в поточному шляху команди, doctor повідомляє попередження лише для читання й не записує резервні облікові дані відкритим текстом. +- Якщо перевірка SecretRef каналу не вдається на шляху виправлення, doctor продовжує роботу й повідомляє попередження замість раннього завершення. +- Після міграцій каталогу стану doctor попереджає, коли увімкнені типові облікові записи Telegram або Discord залежать від резервного env, а `TELEGRAM_BOT_TOKEN` або `DISCORD_BOT_TOKEN` недоступні процесу doctor. +- Автоматичне визначення імен користувачів Telegram `allowFrom` (`doctor --fix`) потребує визначуваного токена Telegram у поточному шляху команди. Якщо перевірка токена недоступна, doctor повідомляє попередження й пропускає автоматичне визначення для цього проходу. ## macOS: перевизначення env `launchctl` -Якщо раніше ви запускали `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення перевизначає ваш файл конфігурації та може спричиняти постійні помилки “unauthorized”. +Якщо ви раніше запускали `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення перевизначає ваш файл конфігурації й може спричиняти постійні помилки “unauthorized”. ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN @@ -83,4 +83,4 @@ launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD ## Пов’язано - [Довідник CLI](/uk/cli) -- [Doctor Gateway](/uk/gateway/doctor) +- [Gateway doctor](/uk/gateway/doctor) diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index 78ac5c3a8..b806236ee 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -1,20 +1,20 @@ --- read_when: - - Додавання або зміна міграцій doctor - - Впровадження несумісних змін конфігурації + - Додавання або змінення міграцій doctor + - Запровадження несумісних змін конфігурації sidebarTitle: Doctor summary: 'Команда doctor: перевірки справності, міграції конфігурації та кроки відновлення' title: Діагностика x-i18n: - generated_at: "2026-05-02T11:07:16Z" + generated_at: "2026-05-02T15:57:45Z" model: gpt-5.5 provider: openai - source_hash: d306099cda1d7f6079ab94ce8bd4a716b8ccf9ab3637e14743c8a1c83db35ca6 + source_hash: 1e8150c43662402a4dfe6eb89a804d1de3a73ad8a78f783fd0506e5976c2761f source_path: gateway/doctor.md workflow: 16 --- -`openclaw doctor` — це інструмент ремонту та міграції для OpenClaw. Він виправляє застарілі конфігурації/стан, перевіряє працездатність і надає практичні кроки для ремонту. +`openclaw doctor` — це інструмент виправлення + міграції для OpenClaw. Він виправляє застарілі конфігурацію/стан, перевіряє справність і надає практичні кроки для виправлення. ## Швидкий старт @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - Приймає стандартні значення без запитів (зокрема кроки ремонту перезапуску/сервісу/пісочниці, коли застосовно). + Приймає стандартні варіанти без запитів (зокрема кроки перезапуску/сервісу/виправлення sandbox, коли застосовно). @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - Застосовує рекомендовані ремонти без запитів (ремонти + перезапуски там, де це безпечно). + Застосовує рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно). @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - Також застосовує агресивні ремонти (перезаписує користувацькі конфігурації supervisor). + Також застосовує агресивні виправлення (перезаписує користувацькі конфігурації супервізора). @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - Запускається без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/сервісу/пісочниці, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично, коли їх виявлено. + Запускається без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/сервісу/sandbox, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично, коли їх виявлено. @@ -62,7 +62,7 @@ openclaw doctor openclaw doctor --deep ``` - Сканує системні сервіси на наявність додаткових встановлень gateway (launchd/systemd/schtasks). + Сканує системні сервіси на наявність додаткових інсталяцій Gateway (launchd/systemd/schtasks). @@ -76,109 +76,109 @@ cat ~/.openclaw/openclaw.json ## Що він робить (коротко) - - - Необов’язкове попереднє оновлення для встановлень із git (лише інтерактивно). - - Перевірка актуальності протоколу UI (перезбирає UI керування, коли схема протоколу новіша). - - Перевірка стану + запит на перезапуск. - - Зведення стану Skills (придатні/відсутні/заблоковані) і стан plugin. + + - Необов’язкове попереднє оновлення для git-інсталяцій (лише інтерактивно). + - Перевірка актуальності протоколу UI (перезбирає Control UI, коли схема протоколу новіша). + - Перевірка справності + запит на перезапуск. + - Зведення стану Skills (придатні/відсутні/заблоковані) і стан Plugin. - Нормалізація конфігурації для застарілих значень. - - Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.`. + - Міграція конфігурації Talk із застарілих пласких полів `talk.*` у `talk.provider` + `talk.providers.`. - Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. - Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - Попередження про затінення OAuth Codex (`models.providers.openai-codex`). - Перевірка передумов OAuth TLS для профілів OpenAI Codex OAuth. - - Попередження allowlist plugin/інструментів, коли `plugins.allow` обмежувальний, але політика інструментів усе ще запитує wildcard або інструменти, що належать plugin. - - Міграція застарілого стану на диску (сесії/каталог agent/автентифікація WhatsApp). - - Міграція застарілих ключів контракту маніфесту plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - - Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля доставки/payload верхнього рівня, payload `provider`, прості fallback-завдання webhook `notify: true`). - - Міграція застарілої політики виконання agent до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. - - Очищення застарілої конфігурації plugin, коли plugins увімкнено; коли `plugins.enabled=false`, застарілі посилання на plugin трактуються як інертна конфігурація обмеження та зберігаються. + - Попередження allowlist Plugin/інструментів, коли `plugins.allow` є обмежувальним, але політика інструментів досі запитує wildcard або інструменти, що належать Plugin. + - Міграція застарілого стану на диску (сесії/каталог агента/автентифікація WhatsApp). + - Міграція застарілих ключів контракту маніфесту Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). + - Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля доставки/корисного навантаження верхнього рівня, `provider` у корисному навантаженні, прості резервні webhook-завдання `notify: true`). + - Міграція застарілої політики runtime агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. + - Очищення застарілої конфігурації Plugin, коли плагіни ввімкнені; коли `plugins.enabled=false`, застарілі посилання на Plugin розглядаються як інертна конфігурація ізоляції та зберігаються. - - Перевірка lock-файлів сесій і очищення застарілих lock. - - Ремонт transcript сесій для дубльованих гілок переписування prompt, створених ураженими збірками 2026.4.24. - - Виявлення tombstone для відновлення після перезапуску завислого subagent, із підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб startup не продовжував трактувати дочірній процес як перерваний перезапуском. - - Перевірки цілісності стану та дозволів (сесії, transcripts, каталог стану). + - Перевірка файлів блокування сесій і очищення застарілих блокувань. + - Виправлення транскриптів сесій для дубльованих гілок переписування prompt, створених ураженими збірками 2026.4.24. + - Виявлення tombstone для відновлення після перезапуску завислого субагента, з підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб запуск не продовжував вважати дочірній процес перерваним через перезапуск. + - Перевірки цілісності стану та дозволів (сесії, транскрипти, каталог стану). - Перевірки дозволів файлу конфігурації (chmod 600) під час локального запуску. - - Стан автентифікації моделей: перевіряє завершення строку дії OAuth, може оновлювати токени, що скоро спливають, і повідомляє про cooldown/вимкнені стани auth-profile. - - Виявлення додаткового каталогу workspace (`~/openclaw`). + - Справність автентифікації моделей: перевіряє завершення строку дії OAuth, може оновлювати токени, що скоро спливають, і повідомляє про cooldown/вимкнені стани auth-profile. + - Виявлення додаткового каталогу робочого простору (`~/openclaw`). - - - Ремонт образу пісочниці, коли sandboxing увімкнено. - - Міграція застарілого сервісу та виявлення додаткового gateway. + + - Виправлення образу sandbox, коли sandboxing увімкнено. + - Міграція застарілих сервісів і виявлення додаткових Gateway. - Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`). - Перевірки runtime Gateway (сервіс встановлено, але він не запущений; кешована мітка launchd). - - Попередження про стан каналів (перевіряються з запущеного gateway). - - Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим ремонтом. - - Очищення середовища вбудованого proxy для сервісів gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення. - - Перевірки найкращих практик runtime Gateway (Node проти Bun, шляхи менеджерів версій). - - Діагностика конфлікту порту gateway (типово `18789`). + - Попередження про стан каналу (зондуються із запущеного Gateway). + - Аудит конфігурації супервізора (launchd/systemd/schtasks) з необов’язковим виправленням. + - Очищення середовища вбудованого проксі для сервісів Gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час інсталяції або оновлення. + - Перевірки найкращих практик runtime Gateway (Node проти Bun, шляхи менеджера версій). + - Діагностика конфліктів порту Gateway (стандартно `18789`). - + - Попередження безпеки для відкритих політик DM. - - Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли джерела токена немає; не перезаписує конфігурації SecretRef токена). - - Виявлення проблем device pairing (очікувані запити першого pairing, очікувані оновлення role/scope, застарілий drift кешу локального device-token і drift автентифікації paired-record). + - Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли джерела токена немає; не перезаписує конфігурації токена SecretRef). + - Виявлення проблем зі спарюванням пристрою (очікувані запити першого спарювання, очікувані підвищення ролі/області дії, застарілий дрейф локального кешу device-token і дрейф автентифікації paired-record). - + - Перевірка systemd linger у Linux. - - Перевірка розміру bootstrap-файлу workspace (попередження про обрізання/наближення до ліміту для файлів context). - - Перевірка стану shell completion і автоматичне встановлення/оновлення. - - Перевірка готовності провайдера embedding для memory search (локальна модель, remote API key або QMD binary). - - Перевірки встановлення з source (невідповідність workspace pnpm, відсутні UI assets, відсутній tsx binary). - - Записує оновлену конфігурацію + метадані wizard. + - Перевірка розміру bootstrap-файлу робочого простору (попередження про обрізання/наближення до ліміту для файлів контексту). + - Перевірка стану shell completion і автоінсталяція/оновлення. + - Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, ключ remote API або бінарний файл QMD). + - Перевірки інсталяції з джерел (невідповідність робочого простору pnpm, відсутні UI-ресурси, відсутній бінарний файл tsx). + - Записує оновлену конфігурацію + метадані майстра. -## Зворотне заповнення та скидання Dreams UI +## Заповнення й скидання Dreams UI -Сцена Dreams в UI керування містить дії **Backfill**, **Reset** і **Clear Grounded** для workflow grounded dreaming. Ці дії використовують RPC-методи gateway у стилі doctor, але вони **не** є частиною ремонту/міграції CLI `openclaw doctor`. +Сцена Dreams у Control UI включає дії **Backfill**, **Reset** і **Clear Grounded** для робочого процесу grounded dreaming. Ці дії використовують RPC-методи в стилі gateway doctor, але вони **не** є частиною виправлення/міграції CLI `openclaw doctor`. Що вони роблять: -- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному workspace, запускає grounded REM diary pass і записує оборотні backfill entries у `DREAMS.md`. -- **Reset** видаляє з `DREAMS.md` лише ті позначені backfill diary entries. -- **Clear Grounded** видаляє лише staged grounded-only short-term entries, які прийшли з історичного replay і ще не накопичили live recall або daily support. +- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає grounded REM diary pass і записує оборотні backfill-записи в `DREAMS.md`. +- **Reset** видаляє з `DREAMS.md` лише ці позначені backfill-записи щоденника. +- **Clear Grounded** видаляє лише staged grounded-only короткострокові записи, що походять з історичного replay і ще не накопичили live recall або daily support. -Чого вони самі по собі **не** роблять: +Що вони **не** роблять самі по собі: - вони не редагують `MEMORY.md` - вони не запускають повні міграції doctor -- вони автоматично не додають grounded candidates у live short-term promotion store, якщо ви явно спершу не запустите staged CLI path +- вони не додають автоматично staged grounded candidates у live short-term promotion store, якщо ви спершу явно не запустите staged CLI path -Якщо ви хочете, щоб grounded historical replay впливав на звичайну deep promotion lane, використовуйте натомість CLI flow: +Якщо ви хочете, щоб grounded historical replay впливав на звичайний deep promotion lane, використовуйте натомість CLI-потік: ```bash openclaw memory rem-backfill --path ./memory --stage-short-term ``` -Це додає grounded durable candidates у short-term dreaming store, зберігаючи `DREAMS.md` як review surface. +Це додає grounded durable candidates у short-term dreaming store, залишаючи `DREAMS.md` поверхнею для перегляду. -## Детальна поведінка та обґрунтування +## Докладна поведінка й обґрунтування - + Якщо це git checkout і doctor запускається інтерактивно, він пропонує оновитися (fetch/rebase/build) перед запуском doctor. Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми. - Це включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у provider map. + Це включає застарілі пласкі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдера. Doctor також попереджає, коли `plugins.allow` не порожній, а політика інструментів використовує - wildcard або записи інструментів, що належать plugin. `tools.allow: ["*"]` відповідає лише інструментам - із plugins, які фактично завантажуються; це не обходить ексклюзивний allowlist plugin. + wildcard або записи інструментів, що належать Plugin. `tools.allow: ["*"]` відповідає лише інструментам + із Plugin, які фактично завантажуються; він не обходить ексклюзивний allowlist Plugin. - Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися й просять вас виконати `openclaw doctor`. + Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися та просять вас виконати `openclaw doctor`. Doctor: @@ -186,7 +186,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - Покаже застосовану міграцію. - Перепише `~/.openclaw/openclaw.json` з оновленою схемою. - Gateway також автоматично запускає міграції doctor під час startup, коли виявляє застарілий формат конфігурації, тому застарілі конфігурації ремонтуються без ручного втручання. Міграції cron job store обробляються командою `openclaw doctor --fix`. + Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання. Міграції сховища cron-завдань обробляються через `openclaw doctor --fix`. Поточні міграції: @@ -195,7 +195,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit` - `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns` - `routing.queue` → `messages.queue` - - `routing.bindings` → верхньорівневі `bindings` + - `routing.bindings` → верхньорівневий `bindings` - `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default` - застарілі `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.` - `routing.agentToAgent` → `tools.agentToAgent` @@ -211,284 +211,284 @@ openclaw memory rem-backfill --path ./memory --stage-short-term - `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider` - `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*` - `bindings[].match.accountID` → `bindings[].match.accountId` - - Для каналів із іменованими `accounts`, але із залишковими верхньорівневими значеннями каналу для одного облікового запису, перемістіть ці значення з областю дії облікового запису в підвищений обліковий запис, вибраний для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/стандартну ціль) + - Для каналів з іменованими `accounts`, але із залишковими верхньорівневими значеннями каналу для одного облікового запису, перемістіть ці значення з областю дії облікового запису до підвищеного облікового запису, вибраного для цього каналу (`accounts.default` для більшості каналів; Matrix може зберегти наявну відповідну іменовану/стандартну ціль) - `identity` → `agents.list[].identity` - `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents) - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks` - - видаліть `agents.defaults.llm`; використовуйте `models.providers..timeoutSeconds` для таймаутів повільних провайдерів/моделей + - видаліть `agents.defaults.llm`; використовуйте `models.providers..timeoutSeconds` для тайм-аутів повільних провайдерів/моделей - `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` - `browser.profiles.*.driver: "extension"` → `"existing-session"` - - видаліть `browser.relayBindHost` (застаріле налаштування ретранслятора extension) - - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (під час запуску Gateway також пропускає провайдерів, у яких `api` встановлено на майбутнє або невідоме значення enum, замість аварійно завершуватися) + - видаліть `browser.relayBindHost` (застаріле налаштування ретранслятора розширення) + - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (запуск Gateway також пропускає провайдерів, у яких `api` задано майбутнім або невідомим значенням enum, замість аварійно завершуватися у закритому режимі) - Попередження doctor також містять рекомендації щодо стандартного облікового запису для каналів із кількома обліковими записами: + Попередження doctor також містять поради щодо стандартного облікового запису для багатооблікових каналів: - Якщо налаштовано два або більше записів `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис. - - Якщо `channels..defaultAccount` встановлено на невідомий ID облікового запису, doctor попереджає та перелічує налаштовані ID облікових записів. + - Якщо `channels..defaultAccount` задано як невідомий ідентифікатор облікового запису, doctor попереджає і перелічує налаштовані ідентифікатори облікових записів. - Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі на неправильний API або обнулити вартість. Doctor попереджає, щоб ви могли видалити перевизначення та відновити маршрутизацію API і вартість для кожної моделі. + Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі до неправильного API або обнулити витрати. Doctor попереджає, щоб ви могли видалити перевизначення та відновити маршрутизацію API й витрати для кожної моделі. - Якщо ваша конфігурація браузера досі вказує на видалений шлях extension Chrome, doctor нормалізує її до поточної моделі підключення Chrome MCP на локальному хості: + Якщо ваша конфігурація браузера досі вказує на видалений шлях розширення Chrome, doctor нормалізує її до поточної моделі локального для хоста підключення Chrome MCP: - `browser.profiles.*.driver: "extension"` стає `"existing-session"` - `browser.relayBindHost` видаляється - Doctor також перевіряє шлях Chrome MCP на локальному хості, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: + Doctor також перевіряє локальний для хоста шлях Chrome MCP, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: - - перевіряє, чи Google Chrome встановлено на тому самому хості для стандартних профілів автопідключення - - перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144 - - нагадує ввімкнути віддалене налагодження на сторінці інспекції браузера (наприклад `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) + - перевіряє, чи встановлено Google Chrome на тому самому хості для стандартних профілів автоматичного підключення + - перевіряє виявлену версію Chrome і попереджає, коли вона нижча за Chrome 144 + - нагадує увімкнути віддалене налагодження на сторінці інспектування браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) - Doctor не може ввімкнути налаштування на боці Chrome за вас. Chrome MCP на локальному хості все ще потребує: + Doctor не може увімкнути налаштування на боці Chrome замість вас. Локальний для хоста Chrome MCP усе ще потребує: - браузер на основі Chromium 144+ на хості gateway/node - браузер, що працює локально - - віддалене налагодження, увімкнене в цьому браузері - - схвалення першого запиту згоди на підключення в браузері + - увімкнене віддалене налагодження в цьому браузері + - підтвердження першого запиту згоди на підключення в браузері Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути на кшталт `responsebody`, експорту PDF, перехоплення завантажень і пакетних дій усе ще потребують керованого браузера або сирого профілю CDP. - Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують сирий CDP. + Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших безголових потоків. Вони й далі використовують сирий CDP. - Коли налаштовано профіль OpenAI Codex OAuth, doctor опитує кінцеву точку авторизації OpenAI, щоб перевірити, що локальний стек Node/OpenSSL TLS може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить рекомендації з виправлення для конкретної платформи. На macOS із Homebrew Node виправлення зазвичай таке: `brew postinstall ca-certificates`. Із `--deep` перевірка виконується навіть тоді, коли gateway справний. + Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації OpenAI, щоб переконатися, що локальний стек Node/OpenSSL TLS може перевірити ланцюг сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить специфічні для платформи поради щодо виправлення. На macOS з Homebrew Node виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть тоді, коли gateway справний. - Якщо раніше ви додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затінити вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі транспортні налаштування поруч із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не запускають це попередження. + Якщо раніше ви додали застарілі транспортні налаштування OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі транспортні налаштування разом із Codex OAuth, щоб ви могли видалити або переписати застаріле транспортне перевизначення та повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків і надалі підтримуються та не спричиняють це попередження. - Коли ввімкнено вбудований Plugin Codex, doctor також перевіряє, чи первинні посилання на моделі `openai-codex/*` досі розв’язуються через стандартний runner PI. Ця комбінація коректна, коли вам потрібна автентифікація Codex OAuth/підписки через PI, але її легко сплутати з нативним harness сервера застосунку Codex. Doctor попереджає та вказує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. + Коли ввімкнено комплектний Plugin Codex, doctor також перевіряє, чи refs первинних моделей `openai-codex/*` досі розв'язуються через стандартний runner PI. Така комбінація є дійсною, коли ви хочете використовувати Codex OAuth/автентифікацію підписки через PI, але її легко сплутати з нативним harness сервера застосунку Codex. Doctor попереджає та вказує на явну форму сервера застосунку: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. - Doctor не виправляє це автоматично, бо обидва маршрути чинні: + Doctor не виправляє це автоматично, бо обидва маршрути є дійсними: - - `openai-codex/*` + PI означає "використовувати автентифікацію Codex OAuth/підписки через звичайний runner OpenClaw." - - `openai/*` + `agentRuntime.id: "codex"` означає "запустити вбудований turn через нативний app-server Codex." - - `/codex ...` означає "керувати нативною розмовою Codex або прив’язати її з чату." - - `/acp ...` або `runtime: "acp"` означає "використовувати зовнішній адаптер ACP/acpx." + - `openai-codex/*` + PI означає «використовувати Codex OAuth/автентифікацію підписки через звичайний runner OpenClaw». + - `openai/*` + `agentRuntime.id: "codex"` означає «виконати вбудований turn через нативний сервер застосунку Codex». + - `/codex ...` означає «керувати або прив'язати нативну розмову Codex із чату». + - `/acp ...` або `runtime: "acp"` означає «використовувати зовнішній адаптер ACP/acpx». - Якщо з’являється попередження, виберіть потрібний маршрут і відредагуйте конфігурацію вручну. Залиште попередження без змін, коли PI Codex OAuth є навмисним. + Якщо з'являється попередження, виберіть потрібний маршрут і відредагуйте конфігурацію вручну. Залиште попередження без змін, коли PI Codex OAuth є навмисним. - Doctor може мігрувати старіші розкладки на диску в поточну структуру: + Doctor може мігрувати старіші розкладки на диску до поточної структури: - - Сховище сесій + транскрипти: + - Сховище сеансів + transcripts: - з `~/.openclaw/sessions/` до `~/.openclaw/agents//sessions/` - Каталог агента: - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` - Стан автентифікації WhatsApp (Baileys): - із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`) - - до `~/.openclaw/credentials/whatsapp//...` (стандартний ID облікового запису: `default`) + - до `~/.openclaw/credentials/whatsapp//...` (стандартний ідентифікатор облікового запису: `default`) - Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виведе попередження, коли залишить будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сесії + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапили в шлях для кожного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера talk/мапи провайдерів тепер порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не спричиняють повторні no-op зміни `doctor --fix`. + Ці міграції виконуються за принципом найкращого зусилля та є ідемпотентними; doctor виводитиме попередження, коли залишатиме будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сеанси + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапляли в шлях для конкретного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера talk/мапи провайдерів тепер порівнює за структурною рівністю, тому різниці лише в порядку ключів більше не спричиняють повторних змін без ефекту від `doctor --fix`. - - Doctor сканує всі встановлені маніфести Plugin на наявність застарілих верхньорівневих ключів capability (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Коли знаходить їх, він пропонує перемістити їх в об’єкт `contracts` і переписати файл маніфесту на місці. Ця міграція ідемпотентна; якщо ключ `contracts` уже має ті самі значення, застарілий ключ видаляється без дублювання даних. + + Doctor сканує всі встановлені маніфести Plugin на наявність застарілих верхньорівневих ключів можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Коли їх знайдено, він пропонує перемістити їх до об'єкта `contracts` і переписати файл маніфесту на місці. Ця міграція є ідемпотентною; якщо ключ `contracts` уже має ті самі значення, застарілий ключ видаляється без дублювання даних. Doctor також перевіряє сховище завдань cron (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, коли перевизначено) на старі форми завдань, які планувальник досі приймає для сумісності. - Поточні очищення cron містять: + Поточні очищення cron включають: - `jobId` → `id` - `schedule.cron` → `schedule.expr` - верхньорівневі поля payload (`message`, `model`, `thinking`, ...) → `payload` - верхньорівневі поля delivery (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - - псевдоніми delivery `provider` у payload → явний `delivery.channel` - - прості застарілі fallback-завдання webhook `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` + - псевдоніми доставки payload `provider` → явний `delivery.channel` + - прості застарілі резервні webhook-завдання `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` - Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий fallback notify з наявним режимом delivery, що не є webhook, doctor попереджає та залишає це завдання для ручної перевірки. + Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий резервний notify з наявним режимом доставки не через webhook, doctor попереджає та залишає це завдання для ручного перегляду. - На Linux doctor також попереджає, коли crontab користувача досі викликає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`. Цей скрипт на локальному хості не підтримується поточним OpenClaw і може записувати хибні повідомлення `Gateway inactive` до `~/.openclaw/logs/whatsapp-health.log`, коли cron не може досягти користувацької шини systemd. Видаліть застарілий запис crontab за допомогою `crontab -e`; використовуйте `openclaw channels status --probe`, `openclaw doctor` і `openclaw gateway status` для поточних перевірок справності. + На Linux doctor також попереджає, коли crontab користувача досі викликає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`. Цей локальний для хоста скрипт не підтримується поточним OpenClaw і може записувати хибні повідомлення `Gateway inactive` до `~/.openclaw/logs/whatsapp-health.log`, коли cron не може досягти користувацької шини systemd. Видаліть застарілий запис crontab за допомогою `crontab -e`; використовуйте `openclaw channels status --probe`, `openclaw doctor` і `openclaw gateway status` для поточних перевірок справності. - Doctor сканує кожен каталог сеансів агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сеансу. Для кожного знайденого файла блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше друкує примітку й просить повторно запустити з `--fix`. + Засіб діагностики сканує кожен каталог сеансу агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сеансу. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше ніж 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше друкує примітку та вказує повторно запустити з `--fix`. - - Doctor сканує JSONL-файли сеансів агента на дубльовану форму гілки, створену помилкою переписування стенограми промпта від 2026.4.24: покинутий хід користувача з внутрішнім runtime-контекстом OpenClaw плюс активний сусідній хід із тим самим видимим промптом користувача. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файла поруч з оригіналом і переписує стенограму до активної гілки, щоб історія gateway і читачі памʼяті більше не бачили дубльованих ходів. + + Засіб діагностики сканує JSONL-файли сеансів агентів на наявність дубльованої форми гілки, створеної помилкою переписування транскрипту промпта від 2026.4.24: покинутий хід користувача з внутрішнім runtime-контекстом OpenClaw і активний сусідній хід із тим самим видимим користувацьким промптом. У режимі `--fix` / `--repair` засіб діагностики створює резервну копію кожного зачепленого файлу поруч з оригіналом і переписує транскрипт на активну гілку, щоб історія Gateway і читачі пам’яті більше не бачили дубльованих ходів. Каталог стану — це операційний мозковий стовбур. Якщо він зникне, ви втратите сеанси, облікові дані, журнали та конфігурацію (якщо не маєте резервних копій деінде). - Doctor перевіряє: + Засіб діагностики перевіряє: - - **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що не може відновити відсутні дані. - - **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує відновити права доступу (і виводить підказку `chown`, коли виявлено невідповідність власника/групи). - - **Синхронізований із хмарою каталог стану на macOS**: попереджає, коли стан розташовано під iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніший I/O та перегони блокування/синхронізації. - - **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розташовано на джерелі монтування `mmcblk*`, оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів та облікових даних. - - **Відсутні каталоги сеансів**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення аварій `ENOENT`. - - **Невідповідність стенограми**: попереджає, коли нещодавні записи сеансів мають відсутні файли стенограм. - - **Основний сеанс "1-line JSONL"**: позначає випадок, коли основна стенограма має лише один рядок (історія не накопичується). - - **Кілька каталогів стану**: попереджає, коли кілька папок `~/.openclaw` існують у домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділитися між інсталяціями). - - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити його на віддаленому хості (стан зберігається там). - - **Права доступу до файла конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/усім, і пропонує обмежити права до `600`. + - **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що не може відновити відсутні дані. + - **Дозволи каталогу стану**: перевіряє можливість запису; пропонує виправити дозволи (і виводить підказку `chown`, коли виявлено невідповідність власника/групи). + - **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розташовано під iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, бо шляхи із синхронізацією можуть спричиняти повільніше I/O та перегони блокування/синхронізації. + - **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розташовано на джерелі монтування `mmcblk*`, бо випадкове I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів і облікових даних. + - **Каталоги сеансів відсутні**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення збоїв `ENOENT`. + - **Невідповідність транскриптів**: попереджає, коли в нещодавніх записах сеансів бракує файлів транскриптів. + - **Основний сеанс "1-рядковий JSONL"**: позначає випадки, коли основний транскрипт має лише один рядок (історія не накопичується). + - **Кілька каталогів стану**: попереджає, коли в домашніх каталогах існує кілька папок `~/.openclaw` або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділитися між інсталяціями). + - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, засіб діагностики нагадує запустити його на віддаленому хості (стан міститься там). + - **Дозволи файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/всім, і пропонує посилити дозволи до `600`. - - Doctor перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли строк дії токенів закінчується або вже закінчився, і може оновити їх, коли це безпечно. Якщо OAuth/token-профіль Anthropic застарів, він пропонує API-ключ Anthropic або шлях setup-token Anthropic. Запити на оновлення зʼявляються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення. + + Засіб діагностики перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли термін дії токенів скоро спливає або вже сплив, і може безпечно оновити їх, коли це можливо. Якщо OAuth/токен-профіль Anthropic застарів, він пропонує API-ключ Anthropic або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення. - Коли оновлення OAuth остаточно не вдається (наприклад `refresh_token_reused`, `invalid_grant` або провайдер просить увійти знову), doctor повідомляє, що потрібна повторна автентифікація, і друкує точну команду `openclaw models auth login --provider ...`, яку треба виконати. + Коли оновлення OAuth остаточно не вдається (наприклад `refresh_token_reused`, `invalid_grant` або провайдер просить увійти знову), засіб діагностики повідомляє, що потрібна повторна автентифікація, і друкує точну команду `openclaw models auth login --provider ...`, яку потрібно запустити. - Doctor також повідомляє про auth-профілі, які тимчасово непридатні через: + Засіб діагностики також повідомляє про профілі автентифікації, які тимчасово непридатні через: - - короткі паузи відновлення (обмеження швидкості/таймаути/помилки автентифікації) + - короткі періоди очікування (обмеження частоти/тайм-аути/помилки автентифікації) - довші вимкнення (помилки білінгу/кредитів) - - Якщо `hooks.gmail.model` задано, doctor перевіряє посилання на модель за каталогом і списком дозволених та попереджає, коли воно не розвʼязується або заборонене. + + Якщо `hooks.gmail.model` задано, засіб діагностики перевіряє посилання на модель за каталогом і allowlist та попереджає, коли його не вдасться розв’язати або воно заборонене. - Коли пісочницю ввімкнено, doctor перевіряє образи Docker і пропонує зібрати або перемкнутися на застарілі назви, якщо поточний образ відсутній. + Коли пісочницю ввімкнено, засіб діагностики перевіряє Docker-образи й пропонує зібрати або перемкнутися на застарілі назви, якщо поточний образ відсутній. - - Doctor видаляє застарілий створений OpenClaw проміжний стан залежностей Plugin у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу інсталяції та локальні для пакета залишки від попереднього коду відновлення залежностей bundled-plugin. + + Засіб діагностики видаляє застарілий згенерований OpenClaw стан проміжної підготовки залежностей плагінів у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу встановлення та локальне сміття пакетів від попереднього коду відновлення залежностей bundled-plugin. - Doctor також може перевстановити налаштовані завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр plugins не може їх знайти. Запуск Gateway і перезавантаження конфігурації не запускають менеджери пакетів; інсталяції plugins залишаються явною роботою doctor/install/update. + Засіб діагностики також може перевстановити налаштовані завантажувані плагіни, коли конфігурація посилається на них, але локальний реєстр плагінів не може їх знайти. Для винесення bundled-plugin назовні у версії 2026.5.2 засіб діагностики автоматично встановлює завантажувані плагіни, які вже використовує наявна конфігурація, а потім покладається на `meta.lastTouchedVersion`, щоб виконати цей релізний прохід лише один раз. Запуск Gateway і перезавантаження конфігурації не запускають менеджери пакетів; встановлення плагінів залишається явною роботою doctor/install/update. - Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw з використанням поточного порту gateway. Він також може сканувати додаткові gateway-подібні служби й друкувати підказки з очищення. Служби gateway OpenClaw з іменами профілів вважаються повноцінними й не позначаються як "зайві". + Засіб діагностики виявляє застарілі служби Gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw із поточним портом Gateway. Він також може просканувати додаткові Gateway-подібні служби та надрукувати підказки з очищення. Служби Gateway OpenClaw з іменами профілів вважаються повноцінними та не позначаються як "додаткові". - У Linux, якщо служба gateway рівня користувача відсутня, але існує служба gateway OpenClaw системного рівня, doctor не встановлює другу службу рівня користувача автоматично. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, потім видаліть дублікат або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли життєвим циклом gateway керує системний супервізор. + У Linux, якщо користувацька служба Gateway відсутня, але існує системна служба Gateway OpenClaw, засіб діагностики не встановлює другу користувацьку службу автоматично. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, а потім видаліть дублікат або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли життєвим циклом Gateway керує системний супервізор. - - Коли обліковий запис каналу Matrix має очікувану або придатну до виконання міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім запускає кроки міграції з найкращим можливим результатом: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки записуються в журнал, а запуск продовжується. У режимі лише для читання (`openclaw doctor` без `--fix`) цю перевірку повністю пропущено. + + Коли обліковий запис каналу Matrix має очікувану або придатну до дії міграцію застарілого стану, засіб діагностики (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім виконує найкращі можливі кроки міграції: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а запуск продовжується. У режимі лише для читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. - Doctor тепер перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки здоровʼя. + Тепер засіб діагностики перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки здоров’я. Що він повідомляє: - - очікувані запити на перше сполучення + - очікувані запити першого сполучення - очікувані підвищення ролі для вже сполучених пристроїв - очікувані підвищення scope для вже сполучених пристроїв - - відновлення невідповідності публічного ключа, коли id пристрою досі збігається, але ідентичність пристрою більше не збігається із затвердженим записом - - сполучені записи без активного токена для затвердженої ролі - - сполучені токени, scope яких відхиляються від затвердженого базового рівня сполучення - - локальні кешовані записи device-token для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані scope + - відновлення невідповідності публічного ключа, коли ідентифікатор пристрою досі збігається, але ідентичність пристрою більше не відповідає схваленому запису + - сполучені записи, у яких бракує активного токена для схваленої ролі + - сполучені токени, чиї scope відхилилися за межі схваленої базової лінії сполучення + - локальні кешовані записи device-token для поточної машини, які передують ротації токена на боці Gateway або містять застарілі метадані scope - Doctor не схвалює запити на сполучення автоматично й не обертає токени пристроїв автоматично. Натомість він друкує точні наступні кроки: + Засіб діагностики не схвалює автоматично запити сполучення й не виконує автоматичну ротацію токенів пристроїв. Натомість він друкує точні наступні кроки: - - переглянути очікувані запити за допомогою `openclaw devices list` - - схвалити точний запит за допомогою `openclaw devices approve ` - - обернути свіжий токен за допомогою `openclaw devices rotate --device --role ` - - видалити й повторно схвалити застарілий запис за допомогою `openclaw devices remove ` + - перегляньте очікувані запити за допомогою `openclaw devices list` + - схваліть точний запит за допомогою `openclaw devices approve ` + - згенеруйте свіжий токен ротацією за допомогою `openclaw devices rotate --device --role ` + - видаліть і повторно схваліть застарілий запис за допомогою `openclaw devices remove ` - Це закриває поширений пробіл "already paired but still getting pairing required": doctor тепер відрізняє перше сполучення від очікуваних підвищень ролі/scope і від дрейфу застарілого токена/ідентичності пристрою. + Це закриває поширену прогалину "вже сполучено, але все ще вимагає сполучення": тепер засіб діагностики відрізняє перше сполучення від очікуваних підвищень ролі/scope і від дрейфу застарілого токена/ідентичності пристрою. - Doctor виводить попередження, коли провайдер відкритий для DM без списку дозволених або коли політику налаштовано небезпечно. + Засіб діагностики видає попередження, коли провайдер відкритий для DM без allowlist або коли політику налаштовано небезпечним способом. - - Якщо працює як користувацька служба systemd, doctor гарантує, що linger увімкнено, щоб gateway залишався активним після виходу із системи. + + Якщо запуск відбувається як користувацька служба systemd, засіб діагностики забезпечує ввімкнення lingering, щоб Gateway залишався активним після виходу з системи. - - Doctor друкує зведення стану робочої області для стандартного агента: + + Засіб діагностики друкує підсумок стану робочого простору для типового агента: - - **Стан Skills**: підраховує eligible, missing-requirements і allowlist-blocked skills. - - **Застарілі каталоги робочої області**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочої області існують поруч із поточною робочою областю. - - **Стан Plugin**: підраховує ввімкнені/вимкнені/помилкові plugins; перелічує ID plugins для будь-яких помилок; повідомляє можливості bundle plugin. - - **Попередження сумісності Plugin**: позначає plugins, що мають проблеми сумісності з поточним runtime. - - **Діагностика Plugin**: показує будь-які попередження або помилки під час завантаження, виведені реєстром plugins. + - **Стан Skills**: рахує придатні, з відсутніми вимогами та заблоковані allowlist Skills. + - **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору існують поруч із поточним робочим простором. + - **Стан Plugin**: рахує ввімкнені/вимкнені/помилкові плагіни; перелічує ID плагінів для всіх помилок; повідомляє можливості bundle plugin. + - **Попередження сумісності Plugin**: позначає плагіни, які мають проблеми сумісності з поточним runtime. + - **Діагностика Plugin**: показує будь-які попередження або помилки під час завантаження, видані реєстром плагінів. - - Doctor перевіряє, чи файли bootstrap робочої області (наприклад `AGENTS.md`, `CLAUDE.md` або інші впроваджені файли контексту) наближаються до налаштованого бюджету символів або перевищують його. Він повідомляє сирі й впроваджені кількості символів для кожного файла, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість впроваджених символів як частку загального бюджету. Коли файли обрізано або вони близько до ліміту, doctor друкує поради з налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. + + Засіб діагностики перевіряє, чи файли початкового контексту робочого простору (наприклад `AGENTS.md`, `CLAUDE.md` або інші ін’єктовані контекстні файли) наближаються до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу необроблену й ін’єктовану кількість символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість ін’єктованих символів як частку від загального бюджету. Коли файли обрізані або близькі до ліміту, засіб діагностики друкує поради для налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. - - Коли `openclaw doctor --fix` видаляє відсутній Plugin каналу, він також видаляє завислу конфігурацію в межах каналу, яка посилалася на цей Plugin: записи `channels.`, цілі Heartbeat, що називали канал, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам завантаження Gateway, коли runtime каналу зник, але конфігурація все ще просить gateway привʼязатися до нього. + + Коли `openclaw doctor --fix` видаляє відсутній плагін каналу, він також видаляє завислу конфігурацію в області цього каналу, яка посилалася на цей плагін: записи `channels.`, цілі Heartbeat, що називали канал, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам завантаження Gateway, коли runtime каналу зник, але конфігурація все ще просить Gateway прив’язатися до нього. - Doctor перевіряє, чи встановлено автодоповнення табуляцією для поточної оболонки (zsh, bash, fish або PowerShell): + Засіб діагностики перевіряє, чи встановлено автодоповнення Tab для поточної оболонки (zsh, bash, fish або PowerShell): - - Якщо профіль оболонки використовує повільний динамічний шаблон автодоповнення (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта кешованого файла. - - Якщо автодоповнення налаштовано в профілі, але файл кешу відсутній, doctor автоматично регенерує кеш. - - Якщо автодоповнення взагалі не налаштовано, doctor пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`). + - Якщо профіль оболонки використовує повільний динамічний шаблон автодоповнення (`source <(openclaw completion ...)`), засіб діагностики оновлює його до швидшого варіанта з кешованим файлом. + - Якщо автодоповнення налаштовано в профілі, але файл кешу відсутній, засіб діагностики автоматично регенерує кеш. + - Якщо автодоповнення взагалі не налаштовано, засіб діагностики пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`). Запустіть `openclaw completion --write-state`, щоб регенерувати кеш вручну. - Doctor перевіряє готовність автентифікації локального токена gateway. + Засіб діагностики перевіряє готовність автентифікації локального токена Gateway. - - Якщо режим токена потребує токена, а джерела токена немає, doctor пропонує згенерувати його. - - Якщо `gateway.auth.token` керується SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом. - - `openclaw doctor --generate-gateway-token` примусово генерує лише тоді, коли не налаштовано жодного SecretRef токена. + - Якщо режим токена потребує токен, а джерела токена немає, засіб діагностики пропонує згенерувати його. + - Якщо `gateway.auth.token` керується SecretRef, але недоступний, засіб діагностики попереджає й не перезаписує його відкритим текстом. + - `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано SecretRef для токена. - Деяким потокам відновлення потрібно перевіряти налаштовані облікові дані, не послаблюючи fail-fast поведінку runtime. + Деякі потоки відновлення мають перевіряти налаштовані облікові дані, не послаблюючи fail-fast поведінку runtime. - - `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef лише для читання, що й команди сімейства status, для цільових відновлень конфігурації. + - `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef лише для читання, що й команди родини status, для цільових відновлень конфігурації. - Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані бота, коли вони доступні. - - Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розвʼязання замість аварійного завершення або хибного повідомлення, що токен відсутній. + - Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, засіб діагностики повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв’язання замість збою або хибного повідомлення, що токен відсутній. - - Doctor запускає перевірку здоровʼя й пропонує перезапустити gateway, коли він здається нездоровим. + + Діагностичний засіб виконує перевірку працездатності й пропонує перезапустити gateway, коли він виглядає непрацездатним. - - Doctor перевіряє, чи налаштований провайдер embedding для пошуку памʼяті готовий для стандартного агента. Поведінка залежить від налаштованого backend і провайдера: + + Діагностичний засіб перевіряє, чи налаштований постачальник embedding для пошуку в пам’яті готовий для стандартного агента. Поведінка залежить від налаштованого backend і постачальника: - - **Бекенд QMD**: перевіряє, чи доступний і чи може запускатися бінарний файл `qmd`. Якщо ні, виводить рекомендації з виправлення, зокрема npm-пакет і варіант ручного шляху до бінарного файлу. - - **Явний локальний провайдер**: перевіряє наявність локального файлу моделі або розпізнаної URL-адреси віддаленої/доступної для завантаження моделі. Якщо відсутня, пропонує перейти на віддаленого провайдера. - - **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи є API-ключ у середовищі або сховищі автентифікації. Якщо його немає, виводить практичні підказки для виправлення. - - **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого провайдера в порядку автоматичного вибору. + - **Backend QMD**: перевіряє, чи доступний і придатний до запуску бінарний файл `qmd`. Якщо ні, друкує вказівки з виправлення, зокрема npm-пакет і варіант ручного шляху до бінарного файла. + - **Явний локальний постачальник**: перевіряє наявність локального файла моделі або розпізнаного URL віддаленої/завантажуваної моделі. Якщо його немає, пропонує перейти на віддаленого постачальника. + - **Явний віддалений постачальник** (`openai`, `voyage` тощо): перевіряє, чи є API-ключ у середовищі або сховищі автентифікації. Друкує дієві підказки для виправлення, якщо ключ відсутній. + - **Автоматичний постачальник**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого постачальника в порядку автоматичного вибору. - Коли доступний кешований результат перевірки Gateway (Gateway був справний на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-які розбіжності. Doctor не запускає новий embedding ping на стандартному шляху; використовуйте команду глибокого статусу пам’яті, коли потрібна жива перевірка провайдера. + Коли доступний кешований результат перевірки Gateway (gateway був працездатним під час перевірки), діагностичний засіб зіставляє його результат із видимою для CLI конфігурацією та зазначає будь-яку розбіжність. Діагностичний засіб не запускає новий embedding ping у стандартному шляху; використовуйте команду поглибленого статусу пам’яті, коли потрібна інтерактивна перевірка постачальника. - Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embeddings під час виконання. + Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання. - - Якщо Gateway справний, doctor запускає перевірку стану каналів і повідомляє попередження із запропонованими виправленнями. + + Якщо Gateway працездатний, діагностичний засіб виконує перевірку статусу каналу та повідомляє попередження із запропонованими виправленнями. - - Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі стандартні налаштування (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він знаходить невідповідність, рекомендує оновлення й може переписати файл служби/завдання до поточних стандартних налаштувань. + + Діагностичний засіб перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на відсутні або застарілі типові значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він знаходить невідповідність, рекомендує оновлення й може переписати файл служби/завдання до поточних типових значень. Примітки: - - `openclaw doctor` запитує підтвердження перед переписуванням конфігурації супервізора. + - `openclaw doctor` запитує підтвердження перед переписуванням конфігурації supervisor. - `openclaw doctor --yes` приймає стандартні запити на відновлення. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. - - `openclaw doctor --repair --force` перезаписує власні конфігурації супервізора. - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби Gateway. Він усе ще повідомляє стан служби й виконує відновлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації супервізора та очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній супервізор. - - У Linux doctor не переписує метадані команди/точки входу, поки відповідний systemd-unit Gateway активний. Він також ігнорує неактивні додаткові не-застарілі units, схожі на Gateway, під час сканування дубльованих служб, щоб допоміжні файли служб не створювали зайвого шуму під час очищення. - - Якщо token auth потребує токена, а `gateway.auth.token` керується SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токена у відкритому тексті в метаданих середовища служби супервізора. - - Doctor виявляє керовані значення середовища служби на основі `.env`/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудували inline, і переписує метадані служби так, щоб ці значення завантажувалися з runtime-джерела, а не з визначення супервізора. - - Doctor виявляє, коли команда служби все ще фіксує старий `--port` після змін `gateway.port`, і переписує метадані служби на поточний порт. - - Якщо token auth потребує токена, а налаштований token SecretRef не розв’язується, doctor блокує шлях встановлення/відновлення з практичними рекомендаціями. - - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим не буде задано явно. - - Для Linux user-systemd units перевірки розбіжностей токенів doctor тепер охоплюють джерела і `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. - - Відновлення служби doctor відмовляється переписувати, зупиняти або перезапускати службу Gateway зі старішого бінарного файлу OpenClaw, коли конфігурацію востаннє було записано новішою версією. Див. [усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). + - `openclaw doctor --repair --force` перезаписує користувацькі конфігурації supervisor. + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає діагностичний засіб у режимі лише читання для життєвого циклу служби Gateway. Він усе ще повідомляє про стан служби та виконує відновлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації supervisor і очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній supervisor. + - У Linux діагностичний засіб не переписує метадані команди/entrypoint, поки відповідний systemd unit Gateway активний. Він також ігнорує неактивні додаткові gateway-подібні units, які не є застарілими, під час сканування дубльованих служб, щоб супутні файли служб не створювали шуму очищення. + - Якщо token auth вимагає token і `gateway.auth.token` керується SecretRef, встановлення/відновлення служби діагностичним засобом перевіряє SecretRef, але не зберігає розв’язані значення plaintext token у метаданих середовища служби supervisor. + - Діагностичний засіб виявляє керовані значення середовища служби на основі `.env`/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудовували inline, і переписує метадані служби так, щоб ці значення завантажувалися з runtime-джерела замість визначення supervisor. + - Діагностичний засіб виявляє, коли команда служби все ще фіксує старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт. + - Якщо token auth вимагає token, а налаштований SecretRef token не розв’язується, діагностичний засіб блокує шлях встановлення/відновлення з дієвими вказівками. + - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, діагностичний засіб блокує встановлення/відновлення, доки mode не буде задано явно. + - Для Linux user-systemd units перевірки розбіжності token у діагностичному засобі тепер включають джерела як `Environment=`, так і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. + - Відновлення служби діагностичним засобом відмовляються переписувати, зупиняти або перезапускати службу Gateway зі старішого бінарного файла OpenClaw, коли конфігурацію востаннє записала новіша версія. Див. [Усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). - Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`. - - Doctor перевіряє runtime служби (PID, останній код виходу) і попереджає, коли службу встановлено, але вона фактично не працює. Він також перевіряє конфлікти портів на порту Gateway (стандартно `18789`) і повідомляє ймовірні причини (Gateway уже працює, SSH-тунель). + + Діагностичний засіб перевіряє runtime служби (PID, останній exit status) і попереджає, коли службу встановлено, але вона фактично не працює. Він також перевіряє конфлікти портів на порту Gateway (типово `18789`) і повідомляє ймовірні причини (Gateway уже працює, SSH-тунель). - Doctor попереджає, коли служба Gateway працює на Bun або шляху Node, керованому версіями (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, бо служба не завантажує ініціалізацію вашої shell. Doctor пропонує мігрувати на системне встановлення Node, коли воно доступне (Homebrew/apt/choco). + Діагностичний засіб попереджає, коли служба Gateway працює на Bun або шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджера версій можуть ламатися після оновлень, бо служба не завантажує вашу shell init. Діагностичний засіб пропонує перейти на системне встановлення Node, коли воно доступне (Homebrew/apt/choco). - Нововстановлені або відновлені macOS LaunchAgents використовують канонічний системний PATH (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) замість копіювання інтерактивного shell PATH, тому Volta, asdf, fnm, pnpm та інші каталоги менеджерів версій не змінюють, який Node визначають дочірні процеси. Служби Linux усе ще зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні каталоги user-bin, але вгадані fallback-каталоги менеджерів версій записуються до PATH служби лише тоді, коли ці каталоги існують на диску. + Нововстановлені або відновлені macOS LaunchAgents використовують канонічний системний PATH (`/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) замість копіювання інтерактивного shell PATH, тому Volta, asdf, fnm, pnpm та інші каталоги менеджерів версій не змінюють, який Node розв’язують дочірні процеси. Служби Linux усе ще зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні каталоги user-bin, але вгадані fallback-каталоги менеджерів версій записуються до PATH служби лише тоді, коли ці каталоги існують на диску. - Doctor зберігає будь-які зміни конфігурації й ставить позначку в метаданих майстра, щоб зафіксувати запуск doctor. + Діагностичний засіб зберігає всі зміни конфігурації та позначає метадані майстра, щоб зафіксувати запуск діагностики. - - Doctor пропонує систему пам’яті робочого простору, коли її немає, і виводить пораду щодо backup, якщо робочий простір ще не перебуває під керуванням git. + + Діагностичний засіб пропонує систему пам’яті робочого простору, коли її немає, і друкує пораду щодо резервного копіювання, якщо робочий простір ще не перебуває під git. - Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі структури робочого простору та backup у git (рекомендовано приватний GitHub або GitLab). + Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі структури робочого простору та резервного копіювання git (рекомендовано приватний GitHub або GitLab). diff --git a/docs/uk/help/testing-updates-plugins.md b/docs/uk/help/testing-updates-plugins.md index c0d86690b..a5c901727 100644 --- a/docs/uk/help/testing-updates-plugins.md +++ b/docs/uk/help/testing-updates-plugins.md @@ -1,47 +1,34 @@ --- read_when: - - Зміна поведінки оновлення, doctor, приймання пакетів або встановлення Plugin в OpenClaw + - Зміна поведінки оновлення OpenClaw, doctor, приймання пакетів або встановлення Plugin - Підготовка або затвердження реліз-кандидата - - Налагодження оновлення пакета, очищення залежностей Plugin або регресій встановлення Plugin + - Налагодження регресій оновлення пакета, очищення залежностей Plugin або встановлення Plugin sidebarTitle: Update and plugin tests summary: Як OpenClaw перевіряє шляхи оновлення, міграції пакетів і поведінку встановлення/оновлення Plugin -title: 'Тестування: оновлення та плагіни' +title: 'Тестування: оновлення та Plugin' x-i18n: - generated_at: "2026-05-02T02:02:09Z" + generated_at: "2026-05-02T15:57:59Z" model: gpt-5.5 provider: openai - source_hash: b1999106b52d2539a6ee0fd7cd88ebb3515c8726e080d4031d7bf421fb99de36 + source_hash: 7843767a4acca25ceea62633faa5f4bec954bebf7cc4eeb9f3b0b990313ff946 source_path: help/testing-updates-plugins.md workflow: 16 --- -Це окремий контрольний список для перевірки оновлень і Plugin. Мета -проста: довести, що інстальований пакет може оновлювати реальний стан користувача, виправляти застарілий -legacy-стан через `doctor` і надалі встановлювати, завантажувати, оновлювати та видаляти -Plugin з підтримуваних джерел. +Це спеціальний контрольний список для перевірки оновлень і Plugin. Мета проста: довести, що інстальований пакет може оновлювати реальний стан користувача, відновлювати застарілий legacy-стан через `doctor` і надалі встановлювати, завантажувати, оновлювати та видаляти plugins з підтримуваних джерел. -Ширшу мапу засобів запуску тестів див. у [Тестування](/uk/help/testing). Для live-ключів провайдерів -і наборів тестів, що торкаються мережі, див. [Live-тестування](/uk/help/testing-live). +Для ширшої мапи засобу запуску тестів див. [Тестування](/uk/help/testing). Для live-ключів провайдерів і наборів, що торкаються мережі, див. [Live-тестування](/uk/help/testing-live). ## Що ми захищаємо Тести оновлень і Plugin захищають такі контракти: -- Tarball пакета повний, має чинний `dist/postinstall-inventory.json` - і не залежить від нерозпакованих файлів репозиторію. -- Користувач може перейти зі старішого опублікованого пакета на пакет-кандидат - без втрати конфігурації, агентів, сесій, робочих просторів, allowlist Plugin або - конфігурації каналів. -- `openclaw doctor --fix --non-interactive` відповідає за очищення та виправлення - legacy-шляхів. Запуск не повинен обростати прихованими міграціями сумісності для застарілого - стану Plugin. -- Встановлення Plugin працює з локальних каталогів, git-репозиторіїв, npm-пакетів і - шляху реєстру ClawHub. -- npm-залежності Plugin встановлюються в керований npm root, скануються перед - довірою й видаляються через npm під час деінсталяції, щоб hoisted-залежності не - залишалися. -- Оновлення Plugin стабільне, коли нічого не змінилося: записи встановлення, resolved - source, структура встановлених залежностей і ввімкнений стан залишаються незмінними. +- Tarball пакета повний, має дійсний `dist/postinstall-inventory.json` і не залежить від розпакованих файлів репозиторію. +- Користувач може перейти зі старішого опублікованого пакета на кандидатний пакет без втрати конфігурації, агентів, сесій, робочих просторів, списків дозволених plugins або конфігурації каналів. +- `openclaw doctor --fix --non-interactive` відповідає за очищення legacy-стану та шляхи відновлення. Startup не має обростати прихованими міграціями сумісності для застарілого стану Plugin. +- Встановлення Plugin працює з локальних директорій, git-репозиторіїв, npm-пакетів і шляху реєстру ClawHub. +- npm-залежності Plugin встановлюються в керований npm-корінь, скануються перед довірою та видаляються через npm під час uninstall, щоб hoisted-залежності не залишалися. +- Оновлення Plugin стабільне, коли нічого не змінилося: записи встановлення, вирішене джерело, розкладка встановлених залежностей і ввімкнений стан залишаються незмінними. ## Локальне підтвердження під час розробки @@ -53,31 +40,25 @@ pnpm check:changed pnpm test:changed ``` -Для змін у встановленні, видаленні, залежностях Plugin або package-inventory також -запустіть цільові тести, що покривають відредаговану межу: +Для змін у встановленні, видаленні, залежностях Plugin або package-inventory також запускайте сфокусовані тести, що покривають змінений seam: ```bash pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts ``` -Перш ніж будь-яка package Docker lane використає tarball, перевірте артефакт пакета: +Перед тим як будь-яка package Docker lane споживатиме tarball, підтвердьте артефакт пакета: ```bash pnpm release:check ``` -`release:check` запускає перевірки дрейфу config/docs/API, записує package dist -inventory, запускає `npm pack --dry-run`, відхиляє заборонені запаковані файли, встановлює -tarball у тимчасовий prefix, запускає postinstall і виконує smoke-перевірку bundled channel -entrypoints. +`release:check` запускає перевірки drift для config/docs/API, записує package dist inventory, виконує `npm pack --dry-run`, відхиляє заборонені запаковані файли, встановлює tarball у тимчасовий prefix, запускає postinstall і виконує smoke-перевірки entrypoints вбудованих каналів. ## Docker lanes -Docker lanes є product-level підтвердженням. Вони встановлюють або оновлюють реальний -пакет у Linux-контейнерах і перевіряють поведінку через CLI-команди, -запуск Gateway, HTTP-проби, RPC-статус і стан файлової системи. +Docker lanes є підтвердженням продуктового рівня. Вони встановлюють або оновлюють реальний пакет усередині Linux-контейнерів і перевіряють поведінку через CLI-команди, запуск Gateway, HTTP-проби, RPC-статус і стан файлової системи. -Під час ітерацій використовуйте цільові lanes: +Використовуйте сфокусовані lanes під час ітерацій: ```bash pnpm test:docker:plugins @@ -89,28 +70,11 @@ pnpm test:docker:update-migration Важливі lanes: -- `test:docker:plugins` перевіряє smoke встановлення Plugin, встановлення з локальної папки, - skip-поведінку оновлення локальної папки, локальні папки з попередньо встановленими - залежностями, встановлення `file:` пакетів, git-встановлення з виконанням CLI, оновлення - moving-ref у git, встановлення з npm registry з hoisted transitive - dependencies, no-op оновлення npm, встановлення з локальної ClawHub fixture і no-op - оновлення, поведінку оновлення marketplace та ввімкнення/інспекцію Claude-bundle. Установіть - `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб блок ClawHub залишався герметичним/offline. -- `test:docker:plugin-update` перевіряє, що незмінений встановлений Plugin не - перевстановлюється й не втрачає install metadata під час `openclaw plugins update`. -- `test:docker:upgrade-survivor` встановлює tarball-кандидат поверх dirty - old-user fixture, запускає оновлення пакета плюс non-interactive doctor, потім запускає - loopback Gateway і перевіряє збереження стану. -- `test:docker:published-upgrade-survivor` спершу встановлює опублікований baseline, - конфігурує його через вбудований рецепт `openclaw config set`, оновлює його до - tarball-кандидата, запускає doctor, перевіряє legacy cleanup, запускає Gateway і - пробує `/healthz`, `/readyz` та RPC-статус. -- `test:docker:update-migration` є cleanup-heavy published-update lane. Він - стартує з налаштованого Discord/Telegram-style стану користувача, запускає baseline - doctor, щоб налаштовані залежності Plugin мали шанс матеріалізуватися, сіє - legacy plugin dependency debris для налаштованого packaged plugin, оновлює до - tarball-кандидата й вимагає, щоб post-update doctor видалив legacy - dependency roots. +- `test:docker:plugins` перевіряє smoke встановлення Plugin, встановлення з локальної папки, поведінку пропуску оновлення локальної папки, локальні папки з попередньо встановленими залежностями, встановлення `file:` пакетів, git-встановлення з виконанням CLI, оновлення git moving-ref, встановлення з npm registry з hoisted transitive dependencies, npm update no-ops, встановлення з локальної ClawHub fixture та update no-ops, поведінку marketplace update і Claude-bundle enable/inspect. Установіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб блок ClawHub залишався hermetic/offline. +- `test:docker:plugin-update` перевіряє, що незмінений встановлений Plugin не перевстановлюється і не втрачає install metadata під час `openclaw plugins update`. +- `test:docker:upgrade-survivor` встановлює candidate tarball поверх dirty old-user fixture, запускає package update плюс non-interactive doctor, потім стартує loopback Gateway і перевіряє збереження стану. +- `test:docker:published-upgrade-survivor` спочатку встановлює published baseline, налаштовує його через вбудований рецепт `openclaw config set`, оновлює до candidate tarball, запускає doctor, перевіряє legacy cleanup, стартує Gateway і пробує `/healthz`, `/readyz` та RPC status. +- `test:docker:update-migration` є cleanup-heavy published-update lane. Він стартує з налаштованого user state у стилі Discord/Telegram, запускає baseline doctor, щоб налаштовані залежності Plugin мали шанс матеріалізуватися, seed-ить legacy plugin dependency debris для налаштованого packaged plugin, оновлює до candidate tarball і вимагає, щоб post-update doctor видалив legacy dependency roots. Корисні варіанти published-upgrade survivor: @@ -124,15 +88,9 @@ OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \ pnpm test:docker:published-upgrade-survivor ``` -Доступні сценарії: `base`, `feishu-channel`, `bootstrap-persona`, -`plugin-deps-cleanup`, `tilde-log-path` і `versioned-runtime-deps`. В aggregate runs -`OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` розгортається в усі reported -issue-shaped scenarios. +Доступні сценарії: `base`, `feishu-channel`, `bootstrap-persona`, `plugin-deps-cleanup`, `configured-plugin-installs`, `tilde-log-path` і `versioned-runtime-deps`. В aggregate runs `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues` розгортається в усі reported issue-shaped сценарії, включно з configured-plugin install migration. -Повна міграція оновлень навмисно відокремлена від Full Release CI. Використовуйте -ручний workflow `Update Migration`, коли release-питання звучить так: "чи може кожен -опублікований stable release від 2026.4.23 і далі оновитися до цього кандидата та -очистити plugin dependency debris?": +Повна update migration навмисно відокремлена від Full Release CI. Використовуйте ручний workflow `Update Migration`, коли release question: «чи може кожен опублікований stable release від 2026.4.23 і далі оновитися до цього кандидата та очистити plugin dependency debris?»: ```bash gh workflow run update-migration.yml \ @@ -145,22 +103,16 @@ gh workflow run update-migration.yml \ ## Package Acceptance -Package Acceptance — це GitHub-native package gate. Він визначає один candidate -package у tarball `package-under-test`, записує version і SHA-256, а потім -запускає reusable Docker E2E lanes проти саме цього tarball. Workflow harness -ref відокремлений від package source ref, тому поточна логіка тестів може перевіряти -старіші trusted releases. +Package Acceptance — це GitHub-native package gate. Він resolve-ить один candidate package у tarball `package-under-test`, записує version і SHA-256, а потім запускає reusable Docker E2E lanes проти саме цього tarball. Workflow harness ref відокремлений від package source ref, тому поточна test logic може перевіряти старіші trusted releases. -Джерела кандидатів: +Джерела candidate: -- `source=npm`: перевірити `openclaw@beta`, `openclaw@latest` або точну - опубліковану версію. -- `source=ref`: запакувати trusted branch, tag або commit з вибраним поточним - harness. -- `source=url`: перевірити HTTPS tarball з обов’язковим `package_sha256`. -- `source=artifact`: повторно використати tarball, завантажений іншим Actions run. +- `source=npm`: перевіряє `openclaw@beta`, `openclaw@latest` або точну опубліковану версію. +- `source=ref`: пакує trusted branch, tag або commit з вибраним current harness. +- `source=url`: перевіряє HTTPS tarball з обов’язковим `package_sha256`. +- `source=artifact`: повторно використовує tarball, завантажений іншим Actions run. -Release checks викликають Package Acceptance із набором package/update/plugin: +Release checks викликають Package Acceptance з набором package/update/plugin: ```text doctor-switch update-channel-switch upgrade-survivor published-upgrade-survivor plugins-offline plugin-update @@ -174,16 +126,11 @@ published_upgrade_survivor_scenarios=reported-issues telegram_mode=mock-openai ``` -Це тримає міграцію пакета, перемикання update channel, очищення застарілих plugin dependency, -offline-покриття Plugin, поведінку оновлення Plugin і Telegram package -QA на одному resolved artifact. +Це тримає package migration, update channel switching, stale plugin dependency cleanup, offline plugin coverage, поведінку plugin update і Telegram package QA на одному resolved artifact. -`release-history` — це bounded release-check sample: останні шість stable releases, -`2026.4.23` і один старіший pre-date anchor. Для вичерпного покриття published update -migration використовуйте `all-since-2026.4.23` в окремому workflow Update Migration -замість Full Release CI. +`release-history` — це bounded release-check sample: останні шість stable releases, `2026.4.23` і один старіший pre-date anchor. Для exhaustive published update migration coverage використовуйте `all-since-2026.4.23` в окремому workflow Update Migration замість Full Release CI. -Запустіть package profile вручну під час перевірки кандидата перед релізом: +Запускайте package profile вручну під час перевірки кандидата перед release: ```bash gh workflow run package-acceptance.yml \ @@ -197,71 +144,49 @@ gh workflow run package-acceptance.yml \ -f telegram_mode=mock-openai ``` -Використовуйте `suite_profile=product`, коли release-питання охоплює MCP channels, -cron/subagent cleanup, OpenAI web search або OpenWebUI. Використовуйте `suite_profile=full` -лише тоді, коли потрібне повне покриття Docker release-path. +Використовуйте `suite_profile=product`, коли release question включає MCP channels, cron/subagent cleanup, OpenAI web search або OpenWebUI. Використовуйте `suite_profile=full` лише тоді, коли потрібне повне покриття Docker release-path. -## Типовий варіант для релізу +## Типове для release -Для release candidates типовий proof stack такий: +Для release candidates типовий stack підтвердження такий: -1. `pnpm check:changed` і `pnpm test:changed` для source-level регресій. -2. `pnpm release:check` для цілісності артефакту пакета. -3. Package Acceptance `package` profile або release-check custom package - lanes для install/update/plugin contracts. -4. Cross-OS release checks для OS-specific installer, onboarding і platform - behavior. -5. Live-набори лише тоді, коли змінена surface зачіпає provider або hosted-service - behavior. +1. `pnpm check:changed` і `pnpm test:changed` для source-level regressions. +2. `pnpm release:check` для integrity артефакта пакета. +3. Package Acceptance `package` profile або release-check custom package lanes для контрактів install/update/plugin. +4. Cross-OS release checks для OS-specific installer, onboarding і platform behavior. +5. Live suites лише тоді, коли змінена поверхня торкається provider або hosted-service behavior. -На maintainer machines broad gates і Docker/package product proof мають запускатися -в Testbox, якщо явно не виконується local proof. +На maintainer machines broad gates і Docker/package product proof мають запускатися в Testbox, якщо явно не виконується local proof. ## Legacy-сумісність -Compatibility leniency вузька й обмежена в часі: +Compatibility leniency є вузькою та обмеженою в часі: -- Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть толерувати - вже випущені прогалини package metadata у Package Acceptance. -- Опублікований пакет `2026.4.26` може попереджати про local build metadata stamp - files, які вже були випущені. -- Пізніші пакети мають задовольняти сучасні контракти. Ті самі прогалини призводять до failure замість - warning або skipping. +- Пакети до `2026.4.25`, включно з `2026.4.25-beta.*`, можуть tolerate already-shipped package metadata gaps у Package Acceptance. +- Опублікований пакет `2026.4.26` може warning для local build metadata stamp files, які вже shipped. +- Пізніші пакети мають задовольняти сучасні контракти. Ті самі gaps fail замість warning або skipping. -Не додавайте нові startup migrations для цих старих форм. Додайте або розширте doctor -repair, а потім доведіть це через `upgrade-survivor` або `published-upgrade-survivor`. +Не додавайте нові startup migrations для цих старих shapes. Додайте або розширте doctor repair, потім підтвердьте це за допомогою `upgrade-survivor` або `published-upgrade-survivor`. ## Додавання покриття -Коли змінюєте поведінку оновлення або Plugin, додавайте покриття на найнижчому рівні, який -може впасти з правильної причини: +Коли змінюєте поведінку update або Plugin, додавайте coverage на найнижчому шарі, який може fail з правильної причини: -- Чиста логіка шляхів або metadata: unit test поруч із source. -- Поведінка package inventory або packed-file: `package-dist-inventory` або tarball - checker test. -- Поведінка CLI install/update: Docker lane assertion або fixture. -- Поведінка published-release migration: сценарій `published-upgrade-survivor`. -- Поведінка registry/package source: fixture `test:docker:plugins` або ClawHub - fixture server. -- Поведінка dependency layout або cleanup: перевіряйте і runtime execution, і - filesystem boundary. npm-залежності можуть бути hoisted під managed npm - root, тому тести мають доводити, що root сканується/очищується, замість припущення про - package-local дерево `node_modules`. +- Pure path або metadata logic: unit test поруч із source. +- Package inventory або packed-file behavior: `package-dist-inventory` або tarball checker test. +- CLI install/update behavior: Docker lane assertion або fixture. +- Published-release migration behavior: сценарій `published-upgrade-survivor`. +- Registry/package source behavior: fixture `test:docker:plugins` або fixture server ClawHub. +- Dependency layout або cleanup behavior: перевіряйте і runtime execution, і filesystem boundary. npm-залежності можуть бути hoisted під managed npm root, тому тести мають доводити, що root сканується/очищається, замість припущення про package-local дерево `node_modules`. -Нові Docker fixtures за замовчуванням мають бути герметичними. Використовуйте локальні fixture registries і -fake packages, якщо метою тесту не є live registry behavior. +Тримайте нові Docker fixtures hermetic за замовчуванням. Використовуйте local fixture registries і fake packages, якщо мета тесту не live registry behavior. -## Тріаж збоїв +## Failure triage -Починайте з ідентичності артефакту: +Почніть з artifact identity: -- Summary `resolve_package` у Package Acceptance: source, version, SHA-256 і - artifact name. -- Docker artifacts: `.artifacts/docker-tests/**/summary.json`, - `failures.json`, lane logs і rerun commands. -- Upgrade survivor summary: `.artifacts/upgrade-survivor/summary.json`, - зокрема baseline version, candidate version, scenario, phase timings і - recipe steps. +- Summary Package Acceptance `resolve_package`: source, version, SHA-256 і artifact name. +- Docker artifacts: `.artifacts/docker-tests/**/summary.json`, `failures.json`, lane logs і rerun commands. +- Upgrade survivor summary: `.artifacts/upgrade-survivor/summary.json`, включно з baseline version, candidate version, scenario, phase timings і recipe steps. -Надавайте перевагу повторному запуску exact lane, що впав, з тим самим package artifact замість -повторного запуску всього release umbrella. +Надавайте перевагу rerun failed exact lane з тим самим package artifact, а не rerun усього release umbrella. diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 1ab3a1da8..454c1556f 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -3,212 +3,213 @@ read_when: - Запуск тестів локально або в CI - Додавання регресійних тестів для помилок моделей/провайдерів - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: набори unit/e2e/live-тестів, Docker-ранери та що охоплює кожен тест' +summary: 'Набір для тестування: набори тестів unit/e2e/live, ранери Docker і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-05-02T15:53:05Z" + generated_at: "2026-05-02T15:57:51Z" model: gpt-5.5 provider: openai - source_hash: eae3bda71caeb2c2ea8842c940897dc79e4e99be6c337967be41e557b44a41fc + source_hash: 217ee866c7e5043c20c09c677e8717e3c8fb836d9016ae3391ecf9058393b2d9 source_path: help/testing.md workflow: 16 --- -OpenClaw має три набори Vitest (модульні/інтеграційні, e2e, live) і невеликий набір -Docker-ранерів. Цей документ є посібником «як ми тестуємо»: +OpenClaw має три набори тестів Vitest (модульні/інтеграційні, e2e, live) і невеликий набір +Docker-запускачів. Цей документ є посібником «як ми тестуємо»: -- Що покриває кожен набір (і що він навмисно _не_ покриває). -- Які команди запускати для типових робочих процесів (локально, перед push, під час налагодження). -- Як live-тести знаходять облікові дані й вибирають моделі/провайдерів. -- Як додавати регресійні тести для реальних проблем моделей/провайдерів. +- Що охоплює кожен набір (і що він навмисно _не_ охоплює). +- Які команди запускати для типових робочих процесів (локально, перед push, для налагодження). +- Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. +- Як додавати регресії для реальних проблем моделей/провайдерів. -**Стек QA (qa-lab, qa-channel, live transport lanes)** задокументовано окремо: +**QA-стек (qa-lab, qa-channel, live transport lanes)** задокументовано окремо: - [Огляд QA](/uk/concepts/qa-e2e-automation) — архітектура, поверхня команд, створення сценаріїв. - [Matrix QA](/uk/concepts/qa-matrix) — довідник для `pnpm openclaw qa matrix`. -- [Канал QA](/uk/channels/qa-channel) — синтетичний транспортний plugin, який використовується сценаріями на основі репозиторію. +- [QA channel](/uk/channels/qa-channel) — синтетичний транспортний плагін, який використовується сценаріями, підтриманими репозиторієм. -Ця сторінка описує запуск звичайних тестових наборів і Docker/Parallels-ранерів. Розділ специфічних для QA раннерів нижче ([специфічні для QA ранери](#qa-specific-runners)) перелічує конкретні виклики `qa` і повертає до наведених вище довідників. +Ця сторінка описує запуск звичайних наборів тестів і Docker/Parallels-запускачів. Розділ про QA-специфічні запускачі нижче ([QA-специфічні запускачі](#qa-specific-runners)) перелічує конкретні виклики `qa` і посилається назад на наведені вище довідники. ## Швидкий старт -У більшість днів: +У більшості випадків: -- Повний гейт (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` +- Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Швидший локальний запуск повного набору на машині з достатніми ресурсами: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` -- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Під час ітерації над окремим збоєм спершу віддавайте перевагу цільовим запускам. -- QA-сайт на Docker: `pnpm qa:lab:up` -- QA-lane на Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Пряме націлювання на файл тепер також маршрутизує шляхи розширень/каналів: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Спершу віддавайте перевагу цільовим запускам, коли ітеруєте над одним збоєм. +- Docker-backed QA-сайт: `pnpm qa:lab:up` +- Linux VM-backed QA lane: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли змінюєте тести або хочете додаткової впевненості: +Коли ви змінюєте тести або хочете додаткової впевненості: -- Гейт покриття: `pnpm test:coverage` +- Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` -Під час налагодження реальних провайдерів/моделей (потрібні справжні облікові дані): +Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + gateway-проби інструментів/зображень): `pnpm test:live` -- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Звіти продуктивності runtime: запустіть `OpenClaw Performance` з +- Live-набір (моделі + gateway tool/image probes): `pnpm test:live` +- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Звіти про продуктивність виконання: запустіть `OpenClaw Performance` з `live_gpt54=true` для реального ходу агента `openai/gpt-5.4` або `deep_profile=true` для артефактів CPU/heap/trace Kova. Щоденні заплановані запуски публікують артефакти mock-provider, deep-profile і GPT 5.4 lane до `openclaw/clawgrit-reports`, коли налаштовано `CLAWGRIT_REPORTS_TOKEN`. -- Live sweep моделей у Docker: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер виконує текстовий хід і невелику пробу в стилі читання файлу. - Моделі, метадані яких оголошують вхід `image`, також виконують крихітний хід із зображенням. - Вимкніть додаткові проби за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або - `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0` під час ізоляції збоїв провайдера. +- Docker live model sweep: `pnpm test:docker:live-models` + - Кожна вибрана модель тепер виконує текстовий хід і невеликий probe у стилі читання файлу. + Моделі, чиї метадані оголошують вхід `image`, також виконують крихітний image-хід. + Вимкніть додаткові probes за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або + `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - Покриття CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні - `OpenClaw Release Checks` обидва викликають повторно використовуваний live/E2E workflow з + `OpenClaw Release Checks` обидва викликають багаторазовий live/E2E workflow з `include_live_suites: true`, що включає окремі Docker live model - matrix-завдання, розділені за провайдерами. + matrix jobs, розділені за провайдером. - Для сфокусованих повторних запусків CI запустіть `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh` - разом із `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` та його - scheduled/release-викликачами. + - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, + а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його + запланованих/release викликачів. - Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind` - Запускає Docker live lane проти шляху Codex app-server, прив’язує синтетичний Slack DM через `/codex bind`, виконує `/codex fast` і - `/codex permissions`, потім перевіряє, що звичайна відповідь і вкладення зображення - проходять через нативну прив’язку plugin замість ACP. + `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення зображення + маршрутизуються через native plugin binding замість ACP. - Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` - - Запускає ходи gateway-агента через harness Codex app-server, що належить plugin, - перевіряє `/codex status` і `/codex models` і за замовчуванням виконує проби image, - cron MCP, sub-agent і Guardian. Вимкніть пробу sub-agent за допомогою - `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0` під час ізоляції інших збоїв Codex - app-server. Для сфокусованої перевірки sub-agent вимкніть інші проби: + - Запускає ходи gateway agent через harness Codex app-server, яким володіє плагін, + перевіряє `/codex status` і `/codex models`, і за замовчуванням виконує image, + cron MCP, sub-agent і Guardian probes. Вимкніть sub-agent probe за допомогою + `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0`, коли ізолюєте інші збої Codex + app-server. Для сфокусованої перевірки sub-agent вимкніть інші probes: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness`. - Це завершується після проби sub-agent, якщо не встановлено + Це завершується після sub-agent probe, якщо не встановлено `OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0`. - Crestodian rescue command smoke: `pnpm test:live:crestodian-rescue-channel` - - Додаткова перевірка з підстрахуванням для поверхні команди порятунку message-channel. + - Додаткова перевірка «ремінь і підтяжки» для поверхні rescue command каналу повідомлень. Вона виконує `/crestodian status`, ставить у чергу постійну зміну моделі, відповідає `/crestodian yes` і перевіряє шлях запису audit/config. - Crestodian planner Docker smoke: `pnpm test:docker:crestodian-planner` - Запускає Crestodian у контейнері без конфігурації з фальшивим Claude CLI у `PATH` - і перевіряє, що нечіткий fallback планувальника перетворюється на аудитований типізований - запис конфігурації. + і перевіряє, що нечіткий fallback планувальника транслюється в audited typed + config write. - Crestodian first-run Docker smoke: `pnpm test:docker:crestodian-first-run` - - Починає з порожнього каталогу стану OpenClaw, маршрутизує простий `openclaw` до - Crestodian, застосовує записи setup/model/agent/Discord plugin + SecretRef, - перевіряє конфігурацію і перевіряє записи audit. Той самий шлях налаштування Ring 0 + - Починає з порожнього каталогу стану OpenClaw, маршрутизує bare `openclaw` до + Crestodian, застосовує setup/model/agent/Discord plugin + SecretRef writes, + перевіряє конфігурацію та audit entries. Той самий шлях Ring 0 setup також покрито в QA Lab через `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`. -- Moonshot/Kimi cost smoke: із встановленим `MOONSHOT_API_KEY` запустіть +- Moonshot/Kimi cost smoke: з установленим `MOONSHOT_API_KEY` запустіть `openclaw models list --provider moonshot --json`, потім запустіть ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` проти `moonshot/kimi-k2.6`. Перевірте, що JSON повідомляє Moonshot/K2.6, а - transcript асистента зберігає нормалізований `usage.cost`. + транскрипт асистента зберігає нормалізований `usage.cost`. Коли потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через allowlist env vars, описані нижче. -## Специфічні для QA ранери +## QA-специфічні запускачі -Ці команди розташовані поруч з основними тестовими наборами, коли потрібен реалізм QA-lab: +Ці команди стоять поруч з основними наборами тестів, коли потрібна реалістичність QA-lab: -CI запускає QA Lab у виділених workflow. `Parity gate` запускається на відповідних PR і -з ручного dispatch із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на -`main` і з ручного dispatch з mock parity gate, live Matrix lane, -керованою Convex live Telegram lane і керованою Convex live Discord lane як -паралельними завданнями. Заплановані QA і release checks явно передають Matrix `--profile fast`, -тоді як Matrix CLI і ручний workflow input за замовчуванням залишаються -`all`; ручний dispatch може розділити `all` на завдання `transport`, `media`, `e2ee-smoke`, +CI запускає QA Lab у dedicated workflows. `Parity gate` запускається на відповідних PR і +з ручного запуску з mock providers. `QA-Lab - All Lanes` запускається щоночі на +`main` і з ручного запуску з mock parity gate, live Matrix lane, +Convex-managed live Telegram lane і Convex-managed live Discord lane як +паралельні jobs. Scheduled QA і release checks явно передають Matrix `--profile fast`, +тоді як Matrix CLI і manual workflow input за замовчуванням залишаються +`all`; ручний запуск може розбити `all` на jobs `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`. `OpenClaw Release Checks` запускає parity плюс -швидкі Matrix і Telegram lanes перед затвердженням релізу, використовуючи +fast Matrix і Telegram lanes перед release approval, використовуючи `mock-openai/gpt-5.5` для release transport checks, щоб вони залишалися детермінованими -й уникали звичайного запуску provider-plugin. Ці live transport gateways вимикають -пошук пам’яті; поведінка пам’яті залишається покритою QA parity suites. +і уникали звичайного запуску provider-plugin. Ці live transport gateways вимикають +memory search; behavior memory залишається покритим наборами QA parity. -Повні release live media shards використовують +Full release live media shards використовують `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, який уже має `ffmpeg` і `ffprobe`. Docker live model/backend shards використовують спільний образ `ghcr.io/openclaw/openclaw-live-test:`, зібраний один раз для вибраного -commit, потім завантажують його з `OPENCLAW_SKIP_DOCKER_BUILD=1` замість повторного збирання +коміту, а потім завантажують його з `OPENCLAW_SKIP_DOCKER_BUILD=1` замість перебудови всередині кожного shard. - `pnpm openclaw qa suite` - - Запускає сценарії QA з репозиторію безпосередньо на хості. + - Запускає QA-сценарії з репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - працівниками gateway. `qa-channel` за замовчуванням має concurrency 4 (обмежено + gateway-працівниками. `qa-channel` за замовчуванням має concurrency 4 (обмежено кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість працівників, або `--concurrency 1` для старішої послідовної lane. - - Завершується з ненульовим кодом, коли будь-який сценарій не вдається. Використовуйте `--allow-failures`, коли - потрібні артефакти без коду виходу з помилкою. + - Завершується з ненульовим кодом, коли будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, коли + потрібні артефакти без коду завершення з помилкою. - Підтримує режими провайдера `live-frontier`, `mock-openai` і `aimock`. `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття fixture і protocol-mock без заміни lane `mock-openai`, що враховує сценарії. + покриття фікстур і protocol-mock без заміни scenario-aware + lane `mock-openai`. - `pnpm test:gateway:cpu-scenarios` - - Запускає bench запуску Gateway плюс невеликий пакет mock-сценаріїв QA Lab + - Запускає startup bench для Gateway плюс невеликий пакет mock-сценаріїв QA Lab (`channel-chat-baseline`, `memory-failure-fallback`, - `gateway-restart-inflight-run`) і записує зведений підсумок спостережень CPU + `gateway-restart-inflight-run`) і записує об'єднане резюме CPU-спостережень у `.artifacts/gateway-cpu-scenarios/`. - - За замовчуванням позначає лише сталі спостереження високого CPU (`--cpu-core-warn` - плюс `--hot-wall-warn-ms`), тому короткі сплески під час запуску записуються як метрики - і не виглядають як регресія з тривалим навантаженням gateway протягом хвилин. - - Використовує зібрані артефакти `dist`; спершу запустіть build, якщо checkout ще не + - За замовчуванням позначає лише сталі спостереження гарячого CPU (`--cpu-core-warn` + плюс `--hot-wall-warn-ms`), тому короткі сплески запуску записуються як метрики + без вигляду регресії Gateway peg тривалістю в хвилини. + - Використовує зібрані артефакти `dist`; спершу запустіть build, коли checkout ще не має свіжого runtime-виводу. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий набір QA у disposable Linux VM Multipass. - - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. + - Запускає той самий QA suite всередині одноразової Linux VM Multipass. + - Зберігає таку саму поведінку вибору сценаріїв, як `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані вхідні дані автентифікації QA, практичні для guest: - ключі провайдера з env, шлях до QA live provider config і `CODEX_HOME`, - якщо він наявний. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через + - Live-запуски пересилають підтримувані вхідні дані QA auth, практичні для guest: + env-ключі провайдера, шлях до QA live provider config і `CODEX_HOME`, + коли він наявний. + - Каталоги виводу мають залишатися під коренем репозиторію, щоб guest міг записувати назад через змонтований workspace. - - Записує звичайний звіт QA + підсумок, а також журнали Multipass у + - Записує звичайний QA-звіт + резюме та логи Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає Docker-backed QA site для operator-style QA-роботи. + - Запускає Docker-backed QA-сайт для operator-style QA-роботи. - `pnpm test:docker:npm-onboard-channel-agent` - - Збирає npm tarball з поточного checkout, встановлює його глобально в - Docker, запускає неінтерактивний onboarding з ключем OpenAI API, за замовчуванням налаштовує Telegram, + - Збирає npm tarball із поточного checkout, глобально встановлює його в + Docker, запускає неінтерактивний onboarding API-ключа OpenAI, за замовчуванням налаштовує Telegram, перевіряє, що packaged plugin runtime завантажується без startup dependency repair, запускає doctor і виконує один локальний agent turn проти - mocked OpenAI endpoint. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму lane packaged-install - з Discord. + mock-ендпоінта OpenAI. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму packaged-install + lane з Discord. - `pnpm test:docker:session-runtime-context` - - Запускає deterministic built-app Docker smoke для transcript вбудованого runtime context. - Він перевіряє, що прихований runtime context OpenClaw зберігається як + - Запускає детермінований built-app Docker smoke для вбудованих runtime context + transcripts. Він перевіряє, що прихований runtime context OpenClaw зберігається як non-display custom message замість витоку у видимий user turn, потім додає affected broken session JSONL і перевіряє, що - `openclaw doctor --fix` переписує його на активну гілку з backup. + `openclaw doctor --fix` переписує його на active branch із резервною копією. - `pnpm test:docker:npm-telegram-live` - - Встановлює package candidate OpenClaw у Docker, запускає installed-package + - Встановлює candidate пакета OpenClaw у Docker, запускає installed-package onboarding, налаштовує Telegram через встановлений CLI, потім повторно використовує - live Telegram QA lane з цим встановленим пакетом як SUT Gateway. - - За замовчуванням використовує `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; встановіть + live Telegram QA lane з цим установленим пакетом як SUT Gateway. + - За замовчуванням використовує `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`; задайте `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` або - `OPENCLAW_CURRENT_PACKAGE_TGZ`, щоб протестувати resolved local tarball замість + `OPENCLAW_CURRENT_PACKAGE_TGZ`, щоб тестувати розв'язаний локальний tarball замість встановлення з registry. - - Використовує ті самі Telegram env credentials або Convex credential source, що й - `pnpm openclaw qa telegram`. Для CI/release automation встановіть + - Використовує ті самі env-облікові дані Telegram або джерело облікових даних Convex, що й + `pnpm openclaw qa telegram`. Для CI/release automation задайте `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` плюс `OPENCLAW_QA_CONVEX_SITE_URL` і role secret. Якщо `OPENCLAW_QA_CONVEX_SITE_URL` і Convex role secret наявні в CI, Docker wrapper автоматично вибирає Convex. - - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільний + - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільну `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цієї lane. - - GitHub Actions надає цю lane як ручний maintainer workflow - `NPM Telegram Beta E2E`. Він не запускається під час merge. Workflow використовує + - GitHub Actions надає цю lane як manual maintainer workflow + `NPM Telegram Beta E2E`. Вона не запускається під час merge. Workflow використовує середовище `qa-live-shared` і Convex CI credential leases. -- GitHub Actions також надає `Package Acceptance` для side-run product proof - проти одного candidate package. Він приймає trusted ref, published npm spec, - HTTPS tarball URL плюс SHA-256 або tarball artifact з іншого run, завантажує +- GitHub Actions також надає `Package Acceptance` для побічного product proof + проти одного candidate package. Він приймає trusted ref, опубліковану npm spec, + HTTPS tarball URL плюс SHA-256 або tarball artifact з іншого запуску, завантажує нормалізований `openclaw-current.tgz` як `package-under-test`, потім запускає - наявний Docker E2E scheduler з профілями lane smoke, package, product, full або custom. - Встановіть `telegram_mode=mock-openai` або `live-frontier`, щоб запустити - Telegram QA workflow проти того самого артефакта `package-under-test`. - - Останній beta product proof: + наявний Docker E2E scheduler із профілями lane smoke, package, product, full або custom. + Задайте `telegram_mode=mock-openai` або `live-frontier`, щоб запустити + Telegram QA workflow проти того самого артефакту `package-under-test`. + - Product proof для останньої beta: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -218,7 +219,7 @@ gh workflow run package-acceptance.yml --ref main \ -f telegram_mode=mock-openai ``` -- Exact tarball URL proof потребує digest: +- Proof для точного tarball URL потребує digest: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -228,7 +229,7 @@ gh workflow run package-acceptance.yml --ref main \ -f suite_profile=package ``` -- Artifact proof завантажує tarball artifact з іншого Actions run: +- Artifact proof завантажує tarball artifact з іншого запуску Actions: ```bash gh workflow run package-acceptance.yml --ref main \ @@ -239,82 +240,83 @@ gh workflow run package-acceptance.yml --ref main \ ``` - `pnpm test:docker:plugins` - - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, потім вмикає bundled channel/plugins через редагування config. + - Пакує та встановлює поточний build OpenClaw у Docker, запускає Gateway + з налаштованим OpenAI, потім вмикає bundled channel/plugins через config + edits. - Перевіряє, що setup discovery залишає неналаштовані downloadable plugins відсутніми, - перший налаштований doctor repair явно встановлює кожен відсутній downloadable - plugin, а другий restart не запускає прихований dependency + перший configured doctor repair встановлює кожен відсутній downloadable + plugin явно, а другий restart не запускає hidden dependency repair. - Також встановлює відомий старіший npm baseline, вмикає Telegram перед запуском `openclaw update --tag ` і перевіряє, що post-update doctor candidate очищає legacy plugin dependency debris без harness-side postinstall repair. - `pnpm test:parallels:npm-update` - - Запускає native packaged-install update smoke на guests Parallels. Кожна - вибрана платформа спершу встановлює requested baseline package, потім запускає + - Запускає native packaged-install update smoke у гостях Parallels. Кожна + вибрана платформа спочатку встановлює запитаний baseline package, потім запускає встановлену команду `openclaw update` у тому самому guest і перевіряє - встановлену версію, статус update, gateway readiness і один локальний agent + встановлену версію, статус оновлення, готовність gateway і один локальний agent turn. - Використовуйте `--platform macos`, `--platform windows` або `--platform linux` під час - ітерацій на одному guest. Використовуйте `--json` для шляху summary artifact і + ітерацій на одному guest. Використовуйте `--json` для шляху до summary artifact і статусу кожної lane. - OpenAI lane за замовчуванням використовує `openai/gpt-5.5` для live agent-turn proof. - Передайте `--model ` або встановіть + Передайте `--model ` або задайте `OPENCLAW_PARALLELS_OPENAI_MODEL`, коли навмисно перевіряєте іншу модель OpenAI. - - Обгорніть довгі локальні запуски host timeout, щоб stalls транспорту Parallels не - забрали решту тестового вікна: + - Обгорніть довгі локальні запуски у host timeout, щоб збої транспорту Parallels не + спожили решту вікна тестування: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json ``` - - Скрипт записує вкладені журнали lane у `/tmp/openclaw-parallels-npm-update.*`. - Перевірте `windows-update.log`, `macos-update.log` або `linux-update.log` - перед тим, як припускати, що зовнішній wrapper завис. + - Скрипт записує вкладені логи lane у `/tmp/openclaw-parallels-npm-update.*`. + Перегляньте `windows-update.log`, `macos-update.log` або `linux-update.log` + перед припущенням, що зовнішній wrapper завис. - Windows update може витратити 10-15 хвилин на post-update doctor і package - update work на cold guest; це все ще справний стан, якщо вкладений npm + update work на cold guest; це все ще справний стан, коли вкладений npm debug log просувається. - - Не запускайте цей aggregate wrapper паралельно з окремими Parallels - macOS, Windows або Linux smoke lanes. Вони спільно використовують VM state і можуть конфліктувати під час + - Не запускайте цей aggregate wrapper паралельно з окремими smoke lanes Parallels + macOS, Windows або Linux. Вони спільно використовують VM state і можуть конфліктувати під час snapshot restore, package serving або guest gateway state. - Post-update proof запускає звичайну bundled plugin surface, тому що capability facades, як-от speech, image generation і media - understanding, завантажуються через bundled runtime APIs, навіть коли сам agent + understanding, завантажуються через bundled runtime APIs навіть тоді, коли сам agent turn перевіряє лише просту текстову відповідь. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер AIMock provider для прямого protocol smoke + - Запускає лише локальний сервер провайдера AIMock для прямого protocol smoke testing. - `pnpm openclaw qa matrix` - - Запускає Matrix live QA lane проти disposable Docker-backed Tuwunel homeserver. Лише source-checkout — packaged installs не постачають `qa-lab`. - - Повний CLI, каталог profile/scenario, env vars і layout артефактів: [Matrix QA](/uk/concepts/qa-matrix). + - Запускає Matrix live QA lane проти одноразового Docker-backed homeserver Tuwunel. Лише source-checkout — packaged installs не постачають `qa-lab`. + - Повний CLI, каталог profile/scenario, env vars і макет артефактів: [Matrix QA](/uk/concepts/qa-matrix). - `pnpm openclaw qa telegram` - - Запускає Telegram live QA lane проти реальної приватної групи, використовуючи токени driver і SUT bot з env. - - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. group id має бути числовим Telegram chat id. - - Підтримує `--credential-source convex` для спільних pooled credentials. За замовчуванням використовуйте env mode або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. - - Завершується з ненульовим кодом, коли будь-який сценарій не вдається. Використовуйте `--allow-failures`, коли вам - потрібні артефакти без коду виходу з помилкою. - - Потребує двох різних bot в одній приватній групі, причому SUT bot має надавати Telegram username. + - Запускає Telegram live QA lane проти реальної приватної групи з використанням driver і SUT bot tokens з env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Group id має бути числовим Telegram chat id. + - Підтримує `--credential-source convex` для спільних pooled credentials. За замовчуванням використовуйте env mode або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути pooled leases. + - Завершується з ненульовим кодом, коли будь-який сценарій зазнає невдачі. Використовуйте `--allow-failures`, коли + потрібні артефакти без коду завершення з помилкою. + - Потребує двох різних bot в одній приватній групі, причому SUT bot має відкривати Telegram username. - Для стабільного bot-to-bot observation увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох bot і переконайтеся, що driver bot може спостерігати group bot traffic. - - Записує Telegram QA report, summary і observed-messages artifact у `.artifacts/qa-e2e/...`. Replying scenarios включають RTT від driver send request до observed SUT reply. + - Записує Telegram QA report, summary і observed-messages artifact у `.artifacts/qa-e2e/...`. Сценарії відповіді включають RTT від driver send request до observed SUT reply. -Live transport lanes мають один standard contract, щоб нові transports не розходилися; per-lane coverage matrix розміщена в [QA overview → Live transport coverage](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` є широким synthetic suite і не входить до цієї matrix. +Live transport lanes мають один стандартний contract, щоб нові transports не розходилися; per-lane coverage matrix розміщено в [QA overview → Live transport coverage](/uk/concepts/qa-e2e-automation#live-transport-coverage). `qa-channel` — це широкий synthetic suite і не є частиною цієї матриці. ### Спільні Telegram credentials через Convex (v1) Коли `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`) увімкнено для -`openclaw qa telegram`, QA lab отримує exclusive lease з Convex-backed pool, heartbeats -цей lease, поки lane працює, і звільняє lease під час shutdown. +`openclaw qa telegram`, QA lab отримує exclusive lease з Convex-backed pool, виконує heartbeats +цього lease, поки lane працює, і звільняє lease під час shutdown. -Reference Convex project scaffold: +Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові env vars: +Обов'язкові env vars: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) - Один secret для вибраної role: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` @@ -322,19 +324,19 @@ Reference Convex project scaffold: - CLI: `--credential-role maintainer|ci` - Env default: `OPENCLAW_QA_CREDENTIAL_ROLE` (за замовчуванням `ci` у CI, інакше `maintainer`) -Необов’язкові env vars: +Необов'язкові env vars: - `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (за замовчуванням `1200000`) - `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (за замовчуванням `30000`) - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (за замовчуванням `90000`) - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (за замовчуванням `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (за замовчуванням `/qa-credentials/v1`) -- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` Convex URLs для local-only development. +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов'язковий trace id) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL-адреси Convex лише для локальної розробки. -`OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://` у нормальній роботі. +`OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://` у звичайній роботі. -Maintainer admin commands (pool add/remove/list) вимагають саме +Admin commands для maintainer (pool add/remove/list) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. CLI helpers для maintainers: @@ -346,12 +348,12 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `doctor` перед live runs, щоб перевірити Convex site URL, broker secrets, -endpoint prefix, HTTP timeout і admin/list reachability без виведення +Використовуйте `doctor` перед live-запусками, щоб перевірити Convex site URL, broker secrets, +endpoint prefix, HTTP timeout і admin/list reachability без друку secret values. Використовуйте `--json` для machine-readable output у scripts і CI utilities. -Контракт типового кінцевого пункту (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): +Стандартний контракт кінцевої точки (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -377,130 +379,130 @@ utilities. Форма корисного навантаження для типу Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком із числовим ідентифікатором чату Telegram. -- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні корисні навантаження. +- `groupId` має бути числовим рядком ідентифікатора чату Telegram. +- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє неправильно сформовані корисні навантаження. ### Додавання каналу до QA -Архітектура й назви допоміжних сценарних компонентів для нових адаптерів каналів наведені в [огляді QA → Додавання каналу](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна планка: реалізувати transport runner на спільному хостовому шві `qa-lab`, оголосити `qaRunners` у маніфесті plugin, змонтувати як `openclaw qa ` і створити сценарії в `qa/scenarios/`. +Архітектура й назви допоміжних сценарних компонентів для нових адаптерів каналів описані в [огляді QA → Додавання каналу](/uk/concepts/qa-e2e-automation#adding-a-channel). Мінімальна вимога: реалізувати транспортний runner на спільному шві хоста `qa-lab`, оголосити `qaRunners` у маніфесті plugin, змонтувати як `openclaw qa ` і написати сценарії в `qa/scenarios/`. ## Набори тестів (що де запускається) -Сприймайте ці набори як «зростання реалістичності» (і зростання нестабільності/вартості): +Сприймайте набори як «зростання реалістичності» (і зростання нестабільності/вартості): -### Модульні / інтеграційні (типово) +### Модульні / інтеграційні (за замовчуванням) - Команда: `pnpm test` -- Конфігурація: нецільові запуски використовують набір шардiв `vitest.full-*.config.ts` і можуть розгортати багатопроєктні шарди в поконфігураційні проєкти для паралельного планування +- Конфігурація: нецільові запуски використовують набір шардiв `vitest.full-*.config.ts` і можуть розгортати багатопроєктні шарди в конфігурації окремих проєктів для паралельного планування - Файли: інвентарі core/модульних тестів у `src/**/*.test.ts`, `packages/**/*.test.ts` і `test/**/*.test.ts`; модульні тести UI запускаються у виділеному шарді `unit-ui` - Обсяг: - Чисті модульні тести - - Внутрішньопроцесні інтеграційні тести (автентифікація Gateway, маршрутизація, інструменти, парсинг, конфігурація) + - Внутрішньопроцесні інтеграційні тести (автентифікація Gateway, маршрутизація, інструменти, розбір, конфігурація) - Детерміновані регресії для відомих помилок - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним - - Тести резолвера й завантажувача публічної поверхні мають доводити резервну поведінку широких `api.js` і - `runtime-api.js` на згенерованих мініатюрних фікстурах plugin, а не - на реальних API джерел вбудованих plugin. Завантаження реального API plugin належать до - контрактних/інтеграційних наборів, якими володіють plugin. + - Тести розпізнавача й завантажувача публічної поверхні мають доводити широку fallback-поведінку `api.js` і + `runtime-api.js` за допомогою згенерованих мінімальних фікстур plugin, а не + реальних API вихідного коду вбудованого plugin. Реальні завантаження API plugin належать до + контрактних/інтеграційних наборів, якими володіє plugin. - + - - Нецільовий `pnpm test` запускає дванадцять менших конфігурацій шардiв (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного великого нативного процесу кореневого проєкту. Це зменшує пікове RSS на завантажених машинах і не дає роботі auto-reply/розширень витісняти непов’язані набори. - - `pnpm test --watch` і далі використовує нативний граф проєктів кореневого `vitest.config.ts`, бо цикл спостереження з багатьма шардами непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через обмежені смуги, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску кореневого проєкту. - - `pnpm test:changed` типово розгортає змінені git-шляхи в дешеві обмежені смуги: прямі зміни тестів, сусідні файли `*.test.ts`, явні зіставлення джерел і локальні залежні вузли графа імпортів. Зміни конфігурації/налаштування/пакетів не запускають широкі тести, якщо ви явно не використаєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. - - `pnpm check:changed` є звичайним розумним локальним контрольним шлюзом для вузької роботи. Він класифікує diff на core, тести core, extensions, тести extension, застосунки, документацію, release metadata, live Docker tooling і tooling, а потім запускає відповідні команди перевірки типів, lint і guard. Він не запускає тести Vitest; для тестового доказу викликайте `pnpm test:changed` або явний `pnpm test `. Підняття версій лише в release metadata запускає цільові перевірки версії/конфігурації/кореневих залежностей із guard, який відхиляє зміни package поза полем версії верхнього рівня. - - Зміни live Docker ACP harness запускають сфокусовані перевірки: синтаксис shell для live Docker auth scripts і dry-run live Docker scheduler. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; зміни залежностей, export, версії та іншої поверхні package все одно використовують ширші guards. - - Легкі за імпортами модульні тести з agents, commands, plugins, helpers auto-reply, `plugin-sdk` та подібних чистих утилітарних зон маршрутизуються через смугу `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; файли зі станом або важкою runtime-логікою лишаються на наявних смугах. - - Вибрані допоміжні джерельні файли `plugin-sdk` і `commands` також зіставляють запуски changed-mode з явними сусідніми тестами в цих легких смугах, тому зміни helpers не перезапускають повний важкий набір для цього каталогу. - - `auto-reply` має окремі кошики для верхньорівневих helpers core, верхньорівневих інтеграційних тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково розділяє піддерево reply на шарди agent-runner, dispatch і commands/state-routing, щоб один важкий за імпортами кошик не володів усім хвостом Node. - - Звичайний CI для PR/main навмисно пропускає пакетний sweep extension і release-only шард `agentic-plugins`. Full Release Validation запускає окремий дочірній workflow `Plugin Prerelease` для цих важких за plugin/extension наборів на кандидатах релізу. + - Нецільовий `pnpm test` запускає дванадцять менших конфігурацій шардiв (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського нативного процесу кореневого проєкту. Це зменшує піковий RSS на навантажених машинах і не дає роботі auto-reply/extension позбавляти ресурсів непов’язані набори. + - `pnpm test --watch` і далі використовує нативний граф проєкту кореневого `vitest.config.ts`, бо цикл спостереження з багатьма шардами непрактичний. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку спрямовують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску кореневого проєкту. + - `pnpm test:changed` за замовчуванням розгортає змінені git-шляхи в дешеві scoped lanes: прямі правки тестів, сусідні файли `*.test.ts`, явні мапінги вихідного коду й локальні залежні елементи графа імпортів. Правки конфігурації/налаштування/пакетів не запускають широкі тести, якщо ви явно не використаєте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`. + - `pnpm check:changed` — це звичайний розумний локальний check gate для вузької роботи. Він класифікує diff на core, тести core, extensions, тести extension, apps, docs, метадані release, live Docker tooling та tooling, а потім запускає відповідні команди typecheck, lint і guard. Він не запускає тести Vitest; викликайте `pnpm test:changed` або явний `pnpm test ` для тестового доказу. Зміни версії лише в метаданих release запускають цільові перевірки version/config/root-dependency із guard, який відхиляє зміни package за межами верхньорівневого поля version. + - Правки live Docker ACP harness запускають сфокусовані перевірки: shell-синтаксис для live Docker auth-скриптів і dry-run live Docker scheduler. Зміни `package.json` включаються лише тоді, коли diff обмежений `scripts["test:docker:live-*"]`; правки dependency, export, version та іншої package-surface і далі використовують ширші guards. + - Import-light модульні тести з agents, commands, plugins, auto-reply helpers, `plugin-sdk` і подібних чистих utility-зон спрямовуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. + - Вибрані вихідні файли helpers `plugin-sdk` і `commands` також маплять changed-mode запуски на явні сусідні тести в цих легких lanes, щоб правки helpers не перезапускали повний важкий набір для цього каталогу. + - `auto-reply` має виділені buckets для верхньорівневих core helpers, верхньорівневих інтеграційних тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково розділяє піддерево reply на шарди agent-runner, dispatch і commands/state-routing, щоб один import-heavy bucket не займав увесь хвіст Node. + - Звичайний CI для PR/main навмисно пропускає пакетний sweep extension і release-only шард `agentic-plugins`. Full Release Validation запускає окремий дочірній workflow `Plugin Prerelease` для цих plugin/extension-heavy наборів на release candidates. - + - - Коли змінюєте входи виявлення message-tool або runtime-контекст compaction, + - Коли ви змінюєте входи виявлення message-tool або runtime-контекст Compaction, зберігайте обидва рівні покриття. - - Додайте сфокусовані регресії helpers для чистих меж маршрутизації та нормалізації. - - Підтримуйте здоровими інтеграційні набори embedded runner: + - Додавайте сфокусовані регресії helpers для меж чистої маршрутизації та нормалізації. + - Підтримуйте справність інтеграційних наборів embedded runner: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped ids і поведінка compaction і далі проходять - реальними шляхами `run.ts` / `compact.ts`; тести лише helpers - не є достатньою заміною для цих інтеграційних шляхів. + - Ці набори перевіряють, що scoped ids і поведінка Compaction і далі проходять + через реальні шляхи `run.ts` / `compact.ts`; тести лише helpers + не є достатньою заміною цих інтеграційних шляхів. - + - - Базова конфігурація Vitest типово використовує `threads`. + - Базова конфігурація Vitest за замовчуванням використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує неізольований runner у кореневих проєктах, e2e та live-конфігураціях. - - Коренева смуга UI зберігає своє налаштування `jsdom` і optimizer, але також - працює на спільному неізольованому runner. + - Коренева UI lane зберігає своє налаштування `jsdom` та optimizer, але також запускається на + спільному неізольованому runner. - Кожен шард `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх процесів Node + - `scripts/run-vitest.mjs` за замовчуванням додає `--no-maglev` для дочірніх процесів Node Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - + - - `pnpm changed:lanes` показує, які архітектурні смуги запускає diff. - - Pre-commit hook виконує лише форматування. Він повторно stage-ить відформатовані файли й - не запускає lint, перевірку типів або тести. - - Запускайте `pnpm check:changed` явно перед handoff або push, коли вам - потрібен розумний локальний контрольний шлюз. - - `pnpm test:changed` типово маршрутизується через дешеві обмежені смуги. Використовуйте - `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли агент - вирішує, що зміна harness, конфігурації, package або contract справді потребує ширшого + - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. + - Pre-commit hook виконує лише форматування. Він повторно індексує відформатовані файли й + не запускає lint, typecheck або тести. + - Запускайте `pnpm check:changed` явно перед передаванням або push, коли вам + потрібен розумний локальний check gate. + - `pnpm test:changed` за замовчуванням проходить через дешеві scoped lanes. Використовуйте + `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли agent + вирішить, що правка harness, config, package або contract справді потребує ширшого покриття Vitest. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - лише з вищим лімітом workers. - - Локальне автоматичне масштабування workers навмисно консервативне й відступає, - коли середнє навантаження host уже високе, тому кілька одночасних - запусків Vitest типово завдають менше шкоди. - - Базова конфігурація Vitest позначає projects/config files як - `forceRerunTriggers`, щоб повторні запуски changed-mode лишалися коректними, коли змінюється + лише з вищою межею workers. + - Автомасштабування локальних workers навмисно консервативне й відступає, + коли середнє навантаження хоста вже високе, тому кілька одночасних + запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає проєкти/конфігураційні файли як + `forceRerunTriggers`, щоб reruns у changed-mode залишалися коректними, коли змінюється test wiring. - - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних - hosts; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + - Конфігурація залишає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете одне явне розташування кешу для прямого профілювання. - + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпортів плюс вивід import-breakdown. - - `pnpm test:perf:imports:changed` обмежує той самий профілювальний перегляд + - `pnpm test:perf:imports:changed` обмежує той самий профілювальний вигляд файлами, зміненими з `origin/main`. - - Дані часу шардiв записуються в `.artifacts/vitest-shard-timings.json`. - Запуски всієї конфігурації використовують шлях конфігурації як ключ; CI-шарди - include-pattern додають назву шарда, щоб відфільтровані шарди можна було відстежувати + - Дані таймінгів шардiв записуються в `.artifacts/vitest-shard-timings.json`. + Запуски всієї конфігурації використовують шлях конфігурації як ключ; include-pattern CI + шарди додають назву шарду, щоб відфільтровані шарди можна було відстежувати окремо. - - Коли один гарячий тест усе ще витрачає більшість часу на стартові імпорти, + - Коли один гарячий тест і далі витрачає більшість часу на стартові імпорти, тримайте важкі залежності за вузьким локальним швом `*.runtime.ts` і - мокайте цей шов напряму замість deep-import runtime helpers лише + мокайте цей шов напряму, замість deep-import runtime helpers лише для передавання їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` з нативним шляхом кореневого проєкту для цього закоміченого + `test:changed` із нативним шляхом кореневого проєкту для цього закоміченого diff і друкує wall time плюс максимальний RSS macOS. - `pnpm test:perf:changed:bench -- --worktree` бенчмаркить поточне - dirty tree, маршрутизуючи список змінених файлів через + брудне дерево, маршрутизуючи список змінених файлів через `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. - `pnpm test:perf:profile:main` записує CPU-профіль main-thread для - startup Vitest/Vite і transform overhead. - - `pnpm test:perf:profile:runner` записує CPU+heap profiles runner для - unit suite з вимкненим паралелізмом файлів. + накладних витрат запуску Vitest/Vite і transform. + - `pnpm test:perf:profile:runner` записує CPU+heap профілі runner для + unit suite з вимкненою файловою паралельністю. @@ -510,90 +512,90 @@ utilities. - Команда: `pnpm test:stability:gateway` - Конфігурація: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - - Запускає реальний loopback Gateway з діагностикою, увімкненою типово - - Проганяє synthetic gateway message, memory і large-payload churn через шлях diagnostic event - - Запитує `diagnostics.stability` через Gateway WS RPC + - Запускає реальний loopback Gateway із діагностикою, увімкненою за замовчуванням + - Проганяє synthetic gateway message, memory і large-payload churn через шлях діагностичної події + - Опитує `diagnostics.stability` через Gateway WS RPC - Покриває helpers збереження diagnostic stability bundle - - Перевіряє, що recorder лишається bounded, synthetic RSS samples лишаються в межах pressure budget, а per-session queue depths повертаються до нуля + - Перевіряє, що recorder залишається обмеженим, synthetic RSS samples залишаються нижче pressure budget, а глибини черг по сесіях спадають назад до нуля - Очікування: - - Безпечно для CI й без ключів - - Вузька смуга для подальших stability-regression робіт, не заміна повного набору Gateway + - Безпечно для CI і без ключів + - Вузька lane для подальшого опрацювання stability-regression, а не заміна повного набору Gateway ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести вбудованих plugin у `extensions/` -- Типові значення runtime: - - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивних workers (CI: до 2, локально: типово 1). - - Типово запускається в silent mode, щоб зменшити overhead console I/O. +- Runtime-типові значення: + - Використовує Vitest `threads` з `isolate: false`, відповідно до решти repo. + - Використовує адаптивних workers (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням запускається в silent mode, щоб зменшити накладні витрати console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість workers (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути verbose console output. + - `OPENCLAW_E2E_WORKERS=` для примусового встановлення кількості workers (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` для повторного ввімкнення докладного виводу console. - Обсяг: - - End-to-end поведінка багатьох екземплярів gateway - - Поверхні WebSocket/HTTP, pairing node і важча мережева взаємодія + - Наскрізна поведінка багатьох екземплярів Gateway + - Поверхні WebSocket/HTTP, сполучення node і важча мережева взаємодія - Очікування: - - Запускається в CI (коли увімкнено в pipeline) + - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - Більше рухомих частин, ніж у модульних тестах (може бути повільніше) -### E2E: smoke бекенду OpenShell +### E2E: smoke OpenShell backend - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` -- Обсяг: - - Запускає ізольований OpenShell Gateway на хості через Docker - - Створює пісочницю з тимчасового локального Dockerfile - - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge +- Область: + - Запускає ізольований Gateway OpenShell на хості через Docker + - Створює sandbox із тимчасового локального Dockerfile + - Перевіряє бекенд OpenShell в OpenClaw через справжні `sandbox ssh-config` + виконання SSH + - Перевіряє поведінку файлової системи з віддаленим канонічним шляхом через міст fs sandbox - Очікування: - - Лише за явного ввімкнення; не входить до стандартного запуску `pnpm test:e2e` + - Лише за явним увімкненням; не входить до стандартного запуску `pnpm test:e2e` - Потребує локального CLI `openshell` і робочого демона Docker - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий Gateway і пісочницю + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий Gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1` для ввімкнення тесту під час ручного запуску ширшого набору e2e - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` для вказання нестандартного CLI-бінарника або wrapper-скрипта + - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб указати нестандартний бінарний файл CLI або wrapper-скрипт -### Живі (реальні провайдери + реальні моделі) +### Live (справжні провайдери + справжні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і живі тести bundled-plugin у `extensions/` +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести bundled-plugin у `extensions/` - Стандартно: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) -- Обсяг: - - “Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?” - - Виявляє зміни формату провайдерів, особливості tool-calling, проблеми автентифікації та поведінку rate limit +- Область: + - “Чи цей провайдер/модель справді працює _сьогодні_ зі справжніми обліковими даними?” + - Виявляє зміни форматів провайдерів, особливості виклику інструментів, проблеми автентифікації та поведінку обмежень швидкості - Очікування: - - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / використовує rate limits - - Краще запускати звужені піднабори, а не “все” -- Живі запуски підвантажують `~/.profile`, щоб отримати відсутні API-ключі. -- Стандартно живі запуски все одно ізолюють `HOME` і копіюють конфігураційні/автентифікаційні матеріали в тимчасовий тестовий home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб живі тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер стандартно працює в тихішому режимі: зберігає виведення прогресу `[live] ...`, але приглушує додаткове повідомлення `~/.profile` і вимикає логи bootstrap Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API-ключів (залежить від провайдера): встановіть `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або override для окремого live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу при відповідях rate limit. -- Виведення прогресу/heartbeat: - - Живі набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдерів були помітно активними навіть тоді, коли захоплення консолі Vitest тихе. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/Gateway транслювалися одразу під час живих запусків. - - Налаштовуйте heartbeat-и direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте heartbeat-и Gateway/проб через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - За задумом не є стабільним для CI (справжні мережі, справжні політики провайдерів, квоти, збої) + - Коштує грошей / використовує ліміти швидкості + - Краще запускати звужені підмножини замість “усього” +- Live-запуски завантажують `~/.profile`, щоб підхопити відсутні API-ключі. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють матеріали конфігурації/автентифікації в тимчасовий тестовий домашній каталог, щоб unit-фікстури не могли змінити ваш справжній `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли ви навмисно хочете, щоб live-тести використовували ваш справжній домашній каталог. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: зберігає прогрес-вивід `[live] ...`, але приглушує додаткове повідомлення про `~/.profile` і вимикає логи bootstrap Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. +- Ротація API-ключів (залежно від провайдера): задайте `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) чи live-перевизначення для окремого провайдера через `OPENCLAW_LIVE_*_KEY`; тести повторюють спроби у відповідь на ліміти швидкості. +- Вивід прогресу/heartbeat: + - Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдерів були помітно активними навіть тоді, коли перехоплення консолі Vitest тихе. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/Gateway одразу передаються під час live-запусків. + - Налаштуйте heartbeat для прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштуйте heartbeat для Gateway/перевірок через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір слід запускати? -Використовуйте цю таблицю рішень: +Скористайтеся цією таблицею рішень: - Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) -- Торкаєтеся мережевої взаємодії Gateway / WS-протоколу / pairing: додайте `pnpm test:e2e` -- Налагоджуєте “мій бот не працює” / збої, специфічні для провайдера / tool calling: запускайте звужений `pnpm test:live` +- Торкаєтеся мережевої взаємодії Gateway / протоколу WS / pairing: додайте `pnpm test:e2e` +- Налагоджуєте “мій бот не працює” / збої, специфічні для провайдера / виклик інструментів: запускайте звужений `pnpm test:live` -## Живі (з мережевим доступом) тести +## Live (тести, що торкаються мережі) -Для live model matrix, CLI backend smokes, ACP smokes, harness Codex app-server -і всіх живих тестів media-provider (Deepgram, BytePlus, ComfyUI, image, -music, video, media harness) — а також обробки облікових даних для живих запусків — див. -[Тестування живих наборів](/uk/help/testing-live). Для спеціального checklist оновлень і +Про live-матрицю моделей, smoke-тести бекенда CLI, smoke-тести ACP, harness app-server Codex +і всі live-тести медіапровайдерів (Deepgram, BytePlus, ComfyUI, зображення, +музика, відео, media harness), а також обробку облікових даних для live-запусків див. +[Тестування live-наборів](/uk/help/testing-live). Для окремого контрольного списку оновлення та перевірки Plugin див. [Тестування оновлень і plugins](/uk/help/testing-updates-plugins). @@ -601,163 +603,163 @@ music, video, media harness) — а також обробки облікових Ці Docker runners поділяються на дві групи: -- Live-model runners: `test:docker:live-models` і `test:docker:live-gateway` запускають лише свій відповідний live-файл profile-key всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та workspace (і підвантажують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoints: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live runners стандартно мають меншу smoke-межу, щоб повний Docker sweep залишався практичним: - `test:docker:live-models` стандартно задає `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` стандартно задає `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Live-model runners: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл profile-key всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та робочу область (і завантажують `~/.profile`, якщо його змонтовано). Відповідні локальні точки входу: `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live runners за замовчуванням мають меншу межу smoke, щоб повний Docker sweep лишався практичним: + `test:docker:live-models` за замовчуванням має `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` за замовчуванням має `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і - `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці змінні середовища, коли - вам явно потрібне більше вичерпне сканування. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два образи `scripts/e2e/Dockerfile`. Bare-образ є лише Node/Git runner для lanes встановлення/оновлення/plugin-dependency; ці lanes монтують попередньо зібраний tarball. Functional-образ встановлює той самий tarball у `/app` для lanes функціональності зібраного застосунку. Визначення Docker lanes містяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка planner міститься в `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегатор використовує зважений локальний scheduler: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а resource caps не дають важким live, npm-install і multi-service lanes стартувати всім одночасно. Якщо один lane важчий за активні caps, scheduler усе одно може запустити його, коли pool порожній, і потім тримає його єдиним запущеним, доки знову не з’явиться місткість. Стандартні значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker-хост має більший запас. Runner стандартно виконує Docker preflight, видаляє застарілі OpenClaw E2E-контейнери, друкує статус кожні 30 секунд, зберігає timings успішних lanes у `.artifacts/docker-tests/lane-timings.json` і використовує ці timings, щоб у наступних запусках спершу стартували довші lanes. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати зважений lane manifest без збірки або запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб надрукувати CI-план для вибраних lanes, потреб пакетів/образів і облікових даних. -- `Package Acceptance` — це GitHub-native package gate для "чи працює цей installable tarball як продукт?" Він визначає один кандидатний пакет із `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає reusable Docker E2E lanes проти саме цього tarball замість повторного пакування вибраного ref. Профілі впорядковано за широтою: `smoke`, `package`, `product` і `full`. Див. [Тестування оновлень і plugins](/uk/help/testing-updates-plugins) щодо контракту package/update/plugin, survivor matrix для published-upgrade, стандартних значень релізу та triage збоїв. -- Перевірки збірки та релізу запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Guard проходить статичний built graph від `dist/entry.js` і `dist/cli/run-main.js` і падає, якщо pre-dispatch startup імпортує залежності пакета, як-от Commander, prompt UI, undici або logging, до dispatch команди; він також утримує bundled gateway run chunk у межах бюджету й відхиляє статичні імпорти відомих cold gateway paths. Packaged CLI smoke також покриває root help, onboard help, doctor help, status, config schema і команду model-list. -- Legacy compatibility для Package Acceptance обмежена `2026.4.25` (включно з `2026.4.25-beta.*`). До цього cutoff harness терпить лише прогалини metadata shipped-package: пропущені записи private QA inventory, відсутній `gateway install --wrapper`, відсутні patch-файли у tarball-derived git fixture, відсутній persisted `update.channel`, legacy розташування plugin install-record, відсутня persistence marketplace install-record і міграція config metadata під час `plugins update`. Для пакетів після `2026.4.25` ці paths є strict failures. -- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` завантажують один або більше реальних контейнерів і перевіряють higher-level integration paths. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли + явно хочете більший вичерпний scan. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, один раз пакує OpenClaw як npm tarball через `scripts/package-openclaw-for-docker.mjs`, а потім збирає/повторно використовує два образи `scripts/e2e/Dockerfile`. Базовий образ є лише runner Node/Git для напрямків install/update/plugin-dependency; ці напрями монтують попередньо зібраний tarball. Функціональний образ встановлює той самий tarball у `/app` для напрямків функціональності зібраного застосунку. Визначення Docker-напрямів містяться в `scripts/lib/docker-e2e-scenarios.mjs`; логіка планувальника — у `scripts/lib/docker-e2e-plan.mjs`; `scripts/test-docker-all.mjs` виконує вибраний план. Агрегат використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а обмеження ресурсів не дають важким live-, npm-install- і multi-service-напрямам стартувати всім одночасно. Якщо один напрям важчий за активні обмеження, планувальник усе одно може запустити його, коли pool порожній, і потім тримає його єдиним активним, доки знову не з’явиться доступна ємність. Стандартні значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=10` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker-хост має більше запасу ресурсів. Runner за замовчуванням виконує Docker preflight, видаляє застарілі контейнери OpenClaw E2E, друкує статус кожні 30 секунд, зберігає таймінги успішних напрямів у `.artifacts/docker-tests/lane-timings.json` і використовує ці таймінги, щоб у наступних запусках спочатку стартували довші напрями. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати зважений маніфест напрямів без збирання або запуску Docker, або `node scripts/test-docker-all.mjs --plan-json`, щоб надрукувати CI-план для вибраних напрямів, потреб у package/image та облікових даних. +- `Package Acceptance` — це нативний для GitHub package gate для питання "чи цей installable tarball працює як продукт?" Він розв’язує один кандидатний package з `source=npm`, `source=ref`, `source=url` або `source=artifact`, завантажує його як `package-under-test`, а потім запускає reusable Docker E2E-напрями проти саме цього tarball замість повторного пакування вибраного ref. Профілі впорядковані за широтою: `smoke`, `package`, `product` і `full`. Див. [Тестування оновлень і plugins](/uk/help/testing-updates-plugins) щодо контракту package/update/plugin, матриці виживання published-upgrade, стандартів release і triage збоїв. +- Перевірки build і release запускають `scripts/check-cli-bootstrap-imports.mjs` після tsdown. Захисна перевірка обходить статичний зібраний граф від `dist/entry.js` і `dist/cli/run-main.js` та завершується помилкою, якщо startup до dispatch імпортує package-залежності, як-от Commander, prompt UI, undici або logging, до dispatch команди; вона також тримає зібраний gateway run chunk у межах бюджету та відхиляє статичні імпорти відомих холодних шляхів Gateway. Packaged CLI smoke також покриває root help, onboard help, doctor help, status, config schema і команду списку моделей. +- Сумісність Package Acceptance legacy обмежена `2026.4.25` (включно з `2026.4.25-beta.*`). До цього cutoff harness допускає лише metadata-прогалини shipped-package: пропущені приватні записи інвентарю QA, відсутній `gateway install --wrapper`, відсутні patch-файли у git-фікстурі, отриманій з tarball, відсутній збережений `update.channel`, legacy-розташування записів встановлення Plugin, відсутнє збереження записів встановлення marketplace і міграцію metadata конфігурації під час `plugins update`. Для packages після `2026.4.25` ці шляхи є суворими помилками. +- Container smoke runners: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:update-channel-switch`, `test:docker:upgrade-survivor`, `test:docker:published-upgrade-survivor`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:browser-cdp-snapshot`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або кілька справжніх контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Live-model Docker runners також bind-mount лише потрібні CLI auth homes (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб external-CLI OAuth міг оновлювати токени без зміни host auth store: +Live-model Docker runners також монтують лише потрібні домашні каталоги автентифікації CLI (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни сховища автентифікації хоста: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) - ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`; за замовчуванням охоплює Claude, Codex і Gemini, зі строгим покриттям Droid/OpenCode через `pnpm test:docker:live-acp-bind:droid` і `pnpm test:docker:live-acp-bind:opencode`) -- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Codex app-server harness smoke: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) -- Gateway + агент розробки: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Observability smoke: `pnpm qa:otel:smoke` — це приватна QA-смуга перевірки вихідного checkout. Її навмисно не включено до Docker-смуг релізу пакета, тому що npm tarball не містить QA Lab. -- Open WebUI live smoke: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Smoke-тест бекенда CLI: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke-тест Codex app-server harness: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- Gateway + dev-агент: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) +- Smoke-тест спостережуваності: `pnpm qa:otel:smoke` — приватна QA-доріжка перевірки source-checkout. Її навмисно не включено до Docker-доріжок випуску пакета, оскільки npm tarball не містить QA Lab. +- Live smoke для Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) - Майстер онбордингу (TTY, повне створення каркаса): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Npm tarball onboarding/channel/agent smoke: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг із посиланням на env і Telegram за замовчуванням, запускає doctor і виконує один змокований хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball за допомогою `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте перебудову на host через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемикайте канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Update channel switch smoke: `pnpm test:docker:update-channel-switch` глобально встановлює запакований tarball OpenClaw у Docker, перемикається з package `stable` на git `dev`, перевіряє збережений канал і роботу Plugin після оновлення, потім перемикається назад на package `stable` і перевіряє статус оновлення. -- Upgrade survivor smoke: `pnpm test:docker:upgrade-survivor` встановлює запакований tarball OpenClaw поверх брудної фікстури старого користувача з агентами, конфігурацією каналу, allowlist Plugin, застарілим станом залежностей Plugin і наявними файлами workspace/session. Він запускає оновлення пакета плюс неінтерактивний doctor без live-ключів провайдера чи каналу, потім запускає loopback Gateway і перевіряє збереження config/state, а також бюджети startup/status. -- Published upgrade survivor smoke: `pnpm test:docker:published-upgrade-survivor` за замовчуванням встановлює `openclaw@latest`, засіває реалістичні файли наявного користувача, налаштовує цей базовий стан за допомогою вбудованого рецепта команд, перевіряє отриману конфігурацію, оновлює це опубліковане встановлення до кандидатного tarball, запускає неінтерактивний doctor, записує `.artifacts/upgrade-survivor/summary.json`, потім запускає loopback Gateway і перевіряє налаштовані intents, збереження стану, startup, `/healthz`, `/readyz` і бюджети RPC-статусу. Перевизначте один baseline через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, попросіть агрегований планувальник розгорнути точні baselines через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, а також розгорніть issue-подібні фікстури через `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS`, як-от `reported-issues`; Package Acceptance надає їх як `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` і `published_upgrade_survivor_scenarios`. -- Session runtime context smoke: `pnpm test:docker:session-runtime-context` перевіряє збереження прихованого runtime context transcript, а також repair doctor для зачеплених дубльованих гілок prompt-rewrite. -- Bun global install smoke: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає bundled image providers, а не зависає. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте host build через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або копіюйте `dist/` із зібраного Docker image через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Installer Docker smoke: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm cache між контейнерами root, update і direct-npm. Update smoke за замовчуванням використовує npm `latest` як stable baseline перед оновленням до кандидатного tarball. Перевизначте локально через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` або через input `update_baseline_version` workflow Install Smoke на GitHub. Перевірки інсталятора без root зберігають ізольований npm cache, щоб записи cache, власником яких є root, не маскували поведінку встановлення user-local. Задайте `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати cache root/update/direct-npm між локальними повторними запусками. -- Install Smoke CI пропускає дубльоване direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття direct `npm install -g`. -- Agents delete shared workspace CLI smoke: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) за замовчуванням збирає image кореневого Dockerfile, засіває двох агентів з одним workspace в ізольованому container home, запускає `agents delete --json` і перевіряє валідний JSON та поведінку збереженого workspace. Повторно використовуйте install-smoke image через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. -- Gateway networking (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Browser CDP snapshot smoke: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає source E2E image плюс Chromium layer, запускає Chromium із raw CDP, запускає `browser doctor --deep` і перевіряє, що CDP role snapshots охоплюють link URLs, cursor-promoted clickables, iframe refs і frame metadata. -- OpenAI Responses web_search minimal reasoning regression: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змокований OpenAI server через Gateway, перевіряє, що `web_search` піднімає `reasoning.effort` з `minimal` до `low`, потім примусово викликає provider schema reject і перевіряє, що raw detail з’являється в Gateway logs. -- MCP channel bridge (засіяний Gateway + stdio bridge + raw Claude notification-frame smoke): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Pi bundle MCP tools (реальний stdio MCP server + embedded Pi profile allow/deny smoke): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Cron/subagent MCP cleanup (реальний Gateway + stdio MCP child teardown після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (install/update smoke для local path, `file:`, npm registry з hoisted dependencies, git moving refs, ClawHub kitchen-sink, marketplace updates і Claude-bundle enable/inspect): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) - Задайте `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити блок ClawHub, або перевизначте стандартну пару kitchen-sink package/runtime через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Без `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` тест використовує герметичний локальний fixture server ClawHub. -- Plugin update unchanged smoke: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Config reload metadata smoke: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Plugins: `pnpm test:docker:plugins` охоплює install/update smoke для local path, `file:`, npm registry з hoisted dependencies, git moving refs, фікстур ClawHub, marketplace updates і Claude-bundle enable/inspect. `pnpm test:docker:plugin-update` охоплює поведінку unchanged update для встановлених plugins. +- Smoke-тест npm tarball для онбордингу/каналу/агента: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг з посиланням на змінні середовища та Telegram за замовчуванням, запускає doctor і виконує один мокований хід агента OpenAI. Повторно використовуйте заздалегідь зібраний tarball з `OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте перебудову на хості з `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемикайте канал з `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke-тест перемикання каналу оновлень: `pnpm test:docker:update-channel-switch` глобально встановлює запакований tarball OpenClaw у Docker, перемикає з пакета `stable` на git `dev`, перевіряє збережений канал і роботу plugin після оновлення, потім перемикає назад на пакет `stable` і перевіряє статус оновлення. +- Smoke-тест виживання після оновлення: `pnpm test:docker:upgrade-survivor` встановлює запакований tarball OpenClaw поверх забрудненої фікстури старого користувача з агентами, конфігурацією каналу, allowlist-ами plugin, застарілим станом залежностей plugin і наявними файлами workspace/сесій. Він запускає оновлення пакета та неінтерактивний doctor без live-ключів провайдера або каналу, потім запускає loopback Gateway і перевіряє збереження конфігурації/стану, а також бюджети запуску/статусу. +- Опублікований smoke-тест виживання після оновлення: `pnpm test:docker:published-upgrade-survivor` за замовчуванням встановлює `openclaw@latest`, засіває реалістичні файли наявного користувача, налаштовує цю базову версію вбудованим рецептом команд, перевіряє отриману конфігурацію, оновлює це опубліковане встановлення до кандидатного tarball, запускає неінтерактивний doctor, записує `.artifacts/upgrade-survivor/summary.json`, потім запускає loopback Gateway і перевіряє налаштовані intents, збереження стану, запуск, `/healthz`, `/readyz` і бюджети RPC-статусу. Перевизначте одну базову версію через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, попросіть агрегований планувальник розгорнути точні базові версії через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS` і розгорніть issue-подібні фікстури через `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS`, наприклад `reported-issues`; набір reported-issues містить `configured-plugin-installs` для автоматичного ремонту встановлення зовнішнього OpenClaw plugin. Package Acceptance показує їх як `published_upgrade_survivor_baseline`, `published_upgrade_survivor_baselines` і `published_upgrade_survivor_scenarios`. +- Smoke-тест runtime context сесії: `pnpm test:docker:session-runtime-context` перевіряє збереження прихованого runtime context у transcript, а також ремонт doctor для зачеплених дубльованих гілок prompt-rewrite. +- Smoke-тест глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольований home і перевіряє, що `openclaw infer image providers --json` повертає вбудованих провайдерів зображень, а не зависає. Повторно використовуйте заздалегідь зібраний tarball з `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропускайте збірку на хості з `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або копіюйте `dist/` із зібраного Docker-образу з `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Smoke-тест Docker-інсталятора: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm cache для root-, update- і direct-npm-контейнерів. Smoke-тест оновлення за замовчуванням використовує npm `latest` як стабільну базову версію перед оновленням до кандидатного tarball. Перевизначте локально через `OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22` або через вхідний параметр `update_baseline_version` workflow Install Smoke на GitHub. Перевірки non-root інсталятора використовують ізольований npm cache, щоб записи cache з root-власником не приховували поведінку встановлення в користувацькому середовищі. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати root/update/direct-npm cache між локальними повторними запусками. +- Install Smoke CI пропускає дубльоване глобальне оновлення direct-npm з `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цієї env, коли потрібне покриття прямого `npm install -g`. +- Smoke-тест CLI видалення агентів зі спільним workspace: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) за замовчуванням збирає образ кореневого Dockerfile, засіває двох агентів з одним workspace в ізольованому home контейнера, запускає `agents delete --json` і перевіряє валідний JSON та поведінку збереженого workspace. Повторно використовуйте образ install-smoke з `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. +- Мережа Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Smoke-тест snapshot Browser CDP: `pnpm test:docker:browser-cdp-snapshot` (скрипт: `scripts/e2e/browser-cdp-snapshot-docker.sh`) збирає вихідний E2E-образ із шаром Chromium, запускає Chromium із сирим CDP, виконує `browser doctor --deep` і перевіряє, що snapshot-и ролей CDP охоплюють URL посилань, clickable-елементи, підвищені cursor-ом, iframe-посилання та метадані frame. +- Регресія OpenAI Responses web_search з мінімальним reasoning: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає мокований сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово відхиляє schema провайдера і перевіряє, що сирі деталі з’являються в логах Gateway. +- MCP-міст каналу (засіяний Gateway + stdio-міст + сирий smoke-тест Claude notification-frame): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- MCP-інструменти Pi bundle (реальний stdio MCP server + smoke-тест allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Очищення Cron/subagent MCP (реальний Gateway + teardown дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (install/update smoke для локального шляху, `file:`, npm registry з hoisted-залежностями, рухомих git refs, ClawHub kitchen-sink, marketplace updates і Claude-bundle enable/inspect): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) + Установіть `OPENCLAW_PLUGINS_E2E_CLAWHUB=0`, щоб пропустити блок ClawHub, або перевизначте стандартну пару package/runtime kitchen-sink через `OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC` і `OPENCLAW_PLUGINS_E2E_CLAWHUB_ID`. Без `OPENCLAW_CLAWHUB_URL`/`CLAWHUB_URL` тест використовує герметичний локальний fixture-сервер ClawHub. +- Smoke-тест незміненого оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke-тест metadata перезавантаження конфігурації: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Plugins: `pnpm test:docker:plugins` охоплює install/update smoke для локального шляху, `file:`, npm registry з hoisted-залежностями, рухомих git refs, фікстур ClawHub, marketplace updates і Claude-bundle enable/inspect. `pnpm test:docker:plugin-update` охоплює поведінку незміненого оновлення для встановлених plugins. -Щоб вручну попередньо зібрати й повторно використовувати спільний functional image: +Щоб вручну попередньо зібрати й повторно використовувати спільний функціональний образ: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення image для конкретного suite, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе одно мають пріоритет, коли задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений shared image, скрипти завантажують його, якщо він ще не є локальним. QR і installer Docker tests зберігають власні Dockerfiles, тому що вони перевіряють поведінку package/install, а не спільний runtime зібраного застосунку. +Специфічні для набору перевизначення образу, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе одно мають пріоритет, коли задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. QR- і installer-Docker-тести зберігають власні Dockerfile, бо вони перевіряють поведінку пакета/встановлення, а не спільний runtime зібраного застосунку. -Docker runners для live-model також bind-mount поточний checkout у режимі read-only і -стейджать його в тимчасовий workdir усередині контейнера. Це зберігає runtime -image компактним, водночас запускаючи Vitest проти саме вашого локального source/config. -Крок staging пропускає великі локальні cache та outputs збірки застосунків, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні для застосунків `.build` або -output-директорії Gradle, щоб Docker live runs не витрачали хвилини на копіювання -machine-specific artifacts. -Вони також задають `OPENCLAW_SKIP_CHANNELS=1`, щоб live probes Gateway не запускали -реальних Telegram/Discord/etc. channel workers усередині контейнера. -`test:docker:live-models` все ще запускає `pnpm test:live`, тому передавайте також +Docker-ранери live-model також монтують поточний checkout у режимі read-only і +переносять його в тимчасовий workdir всередині контейнера. Це зберігає runtime +образ легким, водночас запускаючи Vitest проти вашого точного локального source/config. +Крок staging пропускає великі локальні cache та build output застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні для застосунку `.build` або +каталоги output Gradle, щоб Docker live runs не витрачали хвилини на копіювання +машинно-специфічних артефактів. +Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб gateway live probes не запускали +реальні Telegram/Discord/тощо channel workers всередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте `OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити gateway -live coverage із цієї Docker lane. -`test:docker:openwebui` — це compatibility smoke вищого рівня: він запускає -контейнер Gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoints, -запускає pinned контейнер Open WebUI проти цього Gateway, входить через -Open WebUI, перевіряє, що `/api/models` надає `openclaw/default`, а потім надсилає +live-покриття з цієї Docker-доріжки. +`test:docker:openwebui` — це вищорівневий smoke-тест сумісності: він запускає +контейнер Gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoints, +запускає закріплений контейнер Open WebUI проти цього Gateway, входить через +Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, потім надсилає реальний chat request через proxy `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися завантажити -Open WebUI image, а Open WebUI може потребувати завершення власного cold-start setup. -Ця lane очікує придатний live model key, і `OPENCLAW_PROFILE_FILE` +Перший запуск може бути помітно повільнішим, бо Docker може потребувати завантажити +образ Open WebUI, а Open WebUI може потребувати завершити власне cold-start setup. +Ця доріжка очікує придатний live model key, а `OPENCLAW_PROFILE_FILE` (`~/.profile` за замовчуванням) є основним способом надати його в Dockerized runs. -Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": +Успішні запуски виводять невелике JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він завантажує засіяний контейнер Gateway, -запускає другий контейнер, який породжує `openclaw mcp serve`, а потім -перевіряє routed conversation discovery, transcript reads, attachment metadata, -поведінку live event queue, outbound send routing і channel + -permission notifications у стилі Claude через реальний stdio MCP bridge. Перевірка notification -безпосередньо інспектує raw stdio MCP frames, тож smoke перевіряє те, що -bridge фактично випромінює, а не лише те, що випадково показує конкретний client SDK. +реального облікового запису Telegram, Discord або iMessage. Він запускає засіяний Gateway +container, запускає другий контейнер, який породжує `openclaw mcp serve`, потім +перевіряє routed conversation discovery, читання transcript, metadata attachment, +поведінку live event queue, outbound send routing і Claude-style channel + +permission notifications через реальний stdio MCP bridge. Перевірка notification +безпосередньо інспектує сирі stdio MCP frames, щоб smoke-тест перевіряв те, що +bridge фактично emits, а не лише те, що випадково показує конкретний client SDK. `test:docker:pi-bundle-mcp-tools` детермінований і не потребує live model key. Він збирає repo Docker image, запускає реальний stdio MCP probe server -усередині контейнера, матеріалізує цей server через embedded Pi bundle -MCP runtime, виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають -`bundle-mcp` tools, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. +всередині контейнера, матеріалізує цей server через вбудований Pi bundle +MCP runtime, виконує tool, потім перевіряє, що `coding` і `messaging` зберігають +інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. `test:docker:cron-mcp-cleanup` детермінований і не потребує live model key. Він запускає засіяний Gateway із реальним stdio MCP probe server, виконує -ізольований cron turn і одноразовий child turn `/subagents spawn`, а потім перевіряє, -що MCP child process завершується після кожного запуску. +ізольований cron turn і одноразовий child turn `/subagents spawn`, потім перевіряє, +що дочірній процес MCP завершується після кожного запуску. -Ручний ACP plain-language thread smoke (не CI): +Ручний smoke-тест ACP plain-language thread (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для regression/debug workflows. Він може знову знадобитися для валідації ACP thread routing, тому не видаляйте його. +- Зберігайте цей скрипт для workflows регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. -Корисні env vars: +Корисні змінні середовища: -- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується до `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується до `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується до `/home/node/.profile` і підвантажується перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевірити лише змінні середовища, підвантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги конфігурації/робочого простору й без зовнішніх монтувань автентифікації CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується до `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) змонтовано до `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) змонтовано до `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) змонтовано до `/home/node/.profile` і підвантажується перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише змінні середовища, підвантажені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без зовнішніх монтувань автентифікації CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) змонтовано до `/home/node/.npm-global` для кешованих встановлень CLI всередині Docker - Зовнішні каталоги/файли автентифікації CLI під `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються до `/home/node/...` перед початком тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдера монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Звужені запуски provider монтують лише потрібні каталоги/файли, виведені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Перевизначте вручну за допомогою `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або списку через кому на кшталт `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів у контейнері -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, які не потребують перебудови -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища профілів (а не з середовища) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway відкриває для перевірки Open WebUI smoke -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовується перевіркою Open WebUI smoke +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати providers у контейнері +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібне повторне збирання +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані надходять зі сховища профілю (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway надає для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI - `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI ## Перевірка документації -Запускайте перевірки документації після редагування документів: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. +Запускайте перевірки документації після редагування docs: `pnpm check:docs`. +Запускайте повну перевірку anchors Mintlify, коли також потрібні перевірки заголовків усередині сторінок: `pnpm docs:check-links:anchors`. ## Офлайн-регресія (безпечна для CI) -Це регресії «справжнього pipeline» без справжніх провайдерів: +Це регресії “справжнього pipeline” без реальних providers: -- Виклики інструментів Gateway (імітація OpenAI, справжній gateway + agent loop): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, записує конфігурацію + забезпечує автентифікацію): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Виклик інструментів Gateway (mock OpenAI, реальний gateway + цикл агента): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, записує config + забезпечує auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") -## Оцінювання надійності агента (Skills) +## Оцінювання надійності агента (skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: +У нас уже є кілька безпечних для CI тестів, що поводяться як “оцінювання надійності агента”: -- Імітовані виклики інструментів через справжні gateway + agent loop (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють зв’язування сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Mock-виклик інструментів через реальний gateway + цикл агента (`src/gateway/gateway.test.ts`). +- Наскрізні потоки майстра, що перевіряють зв’язування сесій і ефекти config (`src/gateway/gateway.test.ts`). -Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого ще бракує для skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли skills перелічено в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Ухвалення рішень:** коли skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? +- **Контракти workflow:** багатокрокові сценарії, що перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. Майбутні оцінювання мають насамперед залишатися детермінованими: -- Ранер сценаріїв із mock-провайдерами для перевірки викликів інструментів + порядку, читання файлів skill і зв’язування сесії. -- Невеликий набір сценаріїв, сфокусованих на skill (використати або уникнути, gating, prompt injection). -- Необов’язкові live-оцінювання (opt-in, керовані env) лише після появи безпечного для CI набору. +- Runner сценаріїв із mock providers для перевірки викликів інструментів + порядку, читання skill-файлів і зв’язування сесій. +- Невеликий набір сценаріїв, зосереджених на skills (використати чи уникнути, gating, prompt injection). +- Необов’язкові live evals (opt-in, через env-gate) лише після появи безпечного для CI набору. ## Контрактні тести (форма plugin і channel) Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму -інтерфейсному контракту. Вони проходять усі виявлені plugins і запускають набір -перевірок форми та поведінки. Стандартний unit-lane `pnpm test` навмисно -пропускає ці спільні файли seam і smoke; запускайте контрактні команди явно, +interface contract. Вони ітерують усі виявлені plugins і запускають набір +перевірок форми та поведінки. Типова unit lane `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, коли змінюєте спільні поверхні channel або provider. ### Команди @@ -772,54 +774,54 @@ key. Він запускає засіяний Gateway із реальним stdi - **plugin** - Базова форма plugin (id, name, capabilities) - **setup** - Контракт майстра налаштування -- **session-binding** - Поведінка прив’язування сесії +- **session-binding** - Поведінка зв’язування сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel - **threading** - Обробка ID thread -- **directory** - API каталогу/roster -- **group-policy** - Застосування політики груп +- **directory** - Directory/roster API +- **group-policy** - Застосування групової політики ### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки статусу channel +- **status** - Проби статусу channel - **registry** - Форма registry plugin ### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір автентифікації +- **auth** - Контракт потоку auth +- **auth-choice** - Вибір/selection auth - **catalog** - API каталогу моделей - **discovery** - Виявлення plugin - **loader** - Завантаження plugin - **runtime** - Runtime provider -- **shape** - Форма/інтерфейс plugin +- **shape** - Форма/interface plugin - **wizard** - Майстер налаштування ### Коли запускати -- Після зміни експортів або subpaths plugin-sdk +- Після зміни exports або subpaths plugin-sdk - Після додавання або змінення channel чи provider plugin - Після рефакторингу реєстрації або виявлення plugin -Контрактні тести запускаються в CI і не потребують справжніх API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API keys. ## Додавання регресій (настанови) -Коли ви виправляєте проблему provider/model, виявлену в live: +Коли ви виправляєте проблему provider/model, виявлену наживо: -- Додайте безпечну для CI регресію, якщо можливо (mock/stub provider або захоплення точної трансформації форми запиту) -- Якщо це за своєю природою лише live (обмеження швидкості, політики автентифікації), залишайте live-тест вузьким і opt-in через env vars -- Надавайте перевагу найменшому шару, який ловить помилку: - - помилка перетворення/відтворення запиту provider → прямий тест моделей - - помилка pipeline сесії/історії/інструментів gateway → gateway live smoke або безпечний для CI mock-тест gateway -- Захисне обмеження обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибрану ціль на клас SecretRef з метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec ids із traversal-сегментами відхиляються. - - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target ids, щоб нові класи не можна було мовчки пропустити. +- Додайте безпечну для CI регресію, якщо можливо (mock/stub provider або зафіксуйте точну трансформацію request-shape) +- Якщо це невіддільно live-only (обмеження rate limits, політики auth), тримайте live test вузьким і opt-in через env vars +- Надавайте перевагу найменшому шару, який ловить bug: + - bug конвертації/відтворення запиту provider → прямий тест models + - bug pipeline сесії/історії/інструментів gateway → gateway live smoke або безпечний для CI mock-тест gateway +- Запобіжник обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибрану ціль на клас SecretRef із metadata registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec ids із traversal-сегментами відхиляються. + - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target ids, щоб нові класи не можна було тихо пропустити. ## Пов’язане diff --git a/docs/uk/reference/test.md b/docs/uk/reference/test.md index b9bddbc2f..e44dd938b 100644 --- a/docs/uk/reference/test.md +++ b/docs/uk/reference/test.md @@ -4,60 +4,60 @@ read_when: summary: Як запускати тести локально (vitest) і коли використовувати режими force/coverage title: Тести x-i18n: - generated_at: "2026-05-02T02:01:42Z" + generated_at: "2026-05-02T15:57:36Z" model: gpt-5.5 provider: openai - source_hash: 1100eb4c5990de1a56c8fd65c6152318316232414078cdaad122d4525bf27fee + source_hash: c1e4aec3c056619467bbf51549699cd0387ebb16576e88f91587aab3f382c6c1 source_path: reference/test.md workflow: 16 --- -- Повний набір для тестування (набори, live, Docker): [Тестування](/uk/help/testing) -- Перевірка оновлень і пакета Plugin: [Тестування оновлень і plugins](/uk/help/testing-updates-plugins) +- Повний набір для тестування (набори тестів, живі тести, Docker): [Тестування](/uk/help/testing) +- Перевірка оновлень і пакетів Plugin: [Тестування оновлень і Plugin](/uk/help/testing-updates-plugins) -- `pnpm test:force`: Завершує будь-який завислий процес Gateway, що утримує типовий контрольний порт, а потім запускає повний набір Vitest з ізольованим портом Gateway, щоб серверні тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск Gateway залишив порт 18789 зайнятим. -- `pnpm test:coverage`: Запускає модульний набір із покриттям V8 (через `vitest.unit.config.ts`). Це перевірка покриття модулів для завантажених файлів, а не покриття всіх файлів у всьому репозиторії. Пороги становлять 70% для рядків/функцій/операторів і 55% для гілок. Оскільки `coverage.all` має значення false, перевірка вимірює файли, завантажені набором модульного покриття, замість того щоб вважати кожен вихідний файл із розділених смуг непокритим. +- `pnpm test:force`: Завершує будь-який завислий процес Gateway, що утримує стандартний контрольний порт, а потім запускає повний набір Vitest з ізольованим портом Gateway, щоб серверні тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск Gateway залишив порт 18789 зайнятим. +- `pnpm test:coverage`: Запускає модульний набір із покриттям V8 (через `vitest.unit.config.ts`). Це перевірка модульного покриття завантажених файлів, а не покриття всіх файлів у всьому репозиторії. Пороги становлять 70% для рядків/функцій/операторів і 55% для гілок. Оскільки `coverage.all` має значення false, перевірка вимірює файли, завантажені набором модульного покриття, замість того щоб вважати кожен вихідний файл із розділених доріжок непокритим. - `pnpm test:coverage:changed`: Запускає модульне покриття лише для файлів, змінених після `origin/main`. -- `pnpm test:changed`: дешевий інтелектуальний запуск тестів для змін. Він запускає точні цілі з прямих змін тестів, сусідніх файлів `*.test.ts`, явних зіставлень вихідних файлів і локального графа імпортів. Широкі зміни конфігурації/пакетів пропускаються, якщо вони не зіставляються з точними тестами. -- `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed`: явний широкий запуск тестів для змін. Використовуйте його, коли зміна тестового каркаса/конфігурації/пакета має повертатися до ширшої поведінки Vitest для змінених тестів. -- `pnpm changed:lanes`: показує архітектурні смуги, активовані diff проти `origin/main`. -- `pnpm check:changed`: запускає інтелектуальну перевірку змін для diff проти `origin/main`. Вона запускає typecheck, lint і захисні команди для зачеплених архітектурних смуг, але не запускає тести Vitest. Використовуйте `pnpm test:changed` або явний `pnpm test ` для тестового підтвердження. -- `pnpm test`: маршрутизує явні цілі файлів/каталогів через scoped-смуги Vitest. Запуски без цілей використовують фіксовані групи шардів і розгортаються до leaf-конфігів для локального паралельного виконання; група розширень завжди розгортається до per-extension shard configs замість одного величезного root-project процесу. -- Запуски тестового wrapper завершуються коротким підсумком `[test] passed|failed|skipped ... in ...`. Власний рядок тривалості Vitest залишається деталізацією для кожного шарда. -- Спільний тестовий стан OpenClaw: використовуйте `src/test-utils/openclaw-test-state.ts` з Vitest, коли тесту потрібні ізольовані `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, config fixture, workspace, agent dir або auth-profile store. -- Допоміжні засоби Process E2E: використовуйте `test/helpers/openclaw-test-instance.ts`, коли процесному E2E-тесту Vitest потрібні запущений Gateway, CLI env, захоплення логів і cleanup в одному місці. -- Допоміжні засоби Docker/Bash E2E: смуги, що source `scripts/lib/docker-e2e-image.sh`, можуть передавати `docker_e2e_test_state_shell_b64