chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
56ed7e6f51
commit
3bf0c7e97e
371
docs/uk/ci.md
371
docs/uk/ci.md
@ -1,75 +1,75 @@
|
||||
---
|
||||
read_when:
|
||||
- Потрібно зрозуміти, чому CI-завдання запустилося або не запустилося
|
||||
- Ви налагоджуєте перевірку GitHub Actions, що не проходить
|
||||
- Ви координуєте запуск або повторний запуск перевірки релізу
|
||||
summary: Граф завдань CI, перевірки області дії, релізні парасольки та локальні еквіваленти команд
|
||||
- Потрібно зрозуміти, чому завдання CI запустилося або не запустилося
|
||||
- Ви діагностуєте перевірку GitHub Actions, яка не проходить
|
||||
- Ви координуєте запуск або повторний запуск валідації релізу
|
||||
summary: Граф завдань CI, шлюзи за областю дії, релізні парасолі та локальні еквіваленти команд
|
||||
title: CI-конвеєр
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T08:28:36Z"
|
||||
generated_at: "2026-05-01T08:52:09Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: fdf65df865a8efcee7b0745b33b5ff633e885823177fb19c9920db37a10c59e4
|
||||
source_hash: 679913539743f9495fffa010489ec95e05ce875751afa8a93bf8bf7045d6d9de
|
||||
source_path: ci.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
OpenClaw CI запускається для кожного push у `main` і кожного pull request. Завдання `preflight` класифікує diff і вимикає дорогі lanes, коли змінено лише непов’язані ділянки. Ручні запуски `workflow_dispatch` навмисно обходять розумне обмеження scope і розгортають повний граф для release candidates та широкої валідації. Android lanes залишаються opt-in через `include_android`. Покриття Plugin лише для релізу міститься в окремому workflow [`Plugin Prerelease`](#plugin-prerelease) і запускається лише з [`Full Release Validation`](#full-release-validation) або явного ручного dispatch.
|
||||
OpenClaw CI запускається на кожному push у `main` і для кожного pull request. Завдання `preflight` класифікує diff і вимикає дорогі лінії, коли змінено лише непов’язані області. Ручні запуски `workflow_dispatch` навмисно обходять розумне обмеження області й розгортають повний граф для реліз-кандидатів і широкої валідації. Лінії Android залишаються опційними через `include_android`. Релізне покриття Plugin живе в окремому workflow [`Plugin Prerelease`](#plugin-prerelease) і запускається лише з [`Full Release Validation`](#full-release-validation) або явного ручного dispatch.
|
||||
|
||||
## Огляд pipeline
|
||||
|
||||
| Завдання | Призначення | Коли запускається |
|
||||
| -------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------- |
|
||||
| `preflight` | Виявляє зміни лише в docs, змінені scopes, змінені extensions і збирає маніфест CI | Завжди для non-draft pushes і PRs |
|
||||
| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft pushes і PRs |
|
||||
| `security-dependency-audit` | Аудит production lockfile без встановлення залежностей за npm advisories | Завжди для non-draft pushes і PRs |
|
||||
| `security-fast` | Обов’язковий aggregate для швидких security jobs | Завжди для non-draft pushes і PRs |
|
||||
| `check-dependencies` | Production Knip dependency-only pass плюс guard allowlist невикористаних файлів | Зміни, релевантні для Node |
|
||||
| `build-artifacts` | Збірка `dist/`, Control UI, перевірки built-artifact і reusable downstream artifacts | Зміни, релевантні для Node |
|
||||
| `checks-fast-core` | Швидкі Linux correctness lanes, як-от bundled/plugin-contract/protocol checks | Зміни, релевантні для Node |
|
||||
| `checks-fast-contracts-channels` | Sharded перевірки channel contract зі стабільним aggregate check result | Зміни, релевантні для Node |
|
||||
| `checks-node-core-test` | Core Node test shards, без channel, bundled, contract і extension lanes | Зміни, релевантні для Node |
|
||||
| `check` | Sharded еквівалент головного local gate: prod types, lint, guards, test types і strict smoke | Зміни, релевантні для Node |
|
||||
| `check-additional` | Architecture, boundary, extension-surface guards, package-boundary і gateway-watch shards | Зміни, релевантні для Node |
|
||||
| `build-smoke` | Built-CLI smoke tests і startup-memory smoke | Зміни, релевантні для Node |
|
||||
| `checks` | Verifier для built-artifact channel tests | Зміни, релевантні для Node |
|
||||
| `checks-node-compat-node22` | Node 22 compatibility build і smoke lane | Ручний CI dispatch для релізів |
|
||||
| `check-docs` | Форматування docs, lint і перевірки broken links | Docs змінено |
|
||||
| `skills-python` | Ruff + pytest для Skills на базі Python | Зміни, релевантні для Python Skills |
|
||||
| `checks-windows` | Специфічні для Windows process/path tests плюс shared runtime import specifier regressions | Зміни, релевантні для Windows |
|
||||
| `macos-node` | macOS TypeScript test lane із використанням shared built artifacts | Зміни, релевантні для macOS |
|
||||
| `macos-swift` | Swift lint, build і tests для застосунку macOS | Зміни, релевантні для macOS |
|
||||
| `android` | Android unit tests для обох flavors плюс одна debug APK build | Зміни, релевантні для Android |
|
||||
| `test-performance-agent` | Щоденна оптимізація повільних Codex tests після довіреної активності | Успіх Main CI або ручний dispatch |
|
||||
| `preflight` | Виявляє зміни лише в документації, змінені області, змінені extensions і будує manifest CI | Завжди для non-draft push і PR |
|
||||
| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft push і PR |
|
||||
| `security-dependency-audit` | Аудит production lockfile без залежностей за npm advisories | Завжди для non-draft push і PR |
|
||||
| `security-fast` | Обов’язкова aggregate-перевірка для швидких завдань безпеки | Завжди для non-draft push і PR |
|
||||
| `check-dependencies` | Production-прохід Knip лише для залежностей плюс guard allowlist невикористаних файлів | Зміни, релевантні для Node |
|
||||
| `build-artifacts` | Збірка `dist/`, Control UI, перевірки built-artifact і перевикористовні downstream artifacts | Зміни, релевантні для Node |
|
||||
| `checks-fast-core` | Швидкі Linux-лінії коректності, як-от bundled/plugin-contract/protocol перевірки | Зміни, релевантні для Node |
|
||||
| `checks-fast-contracts-channels` | Sharded-перевірки channel contract зі стабільним aggregate-результатом перевірки | Зміни, релевантні для Node |
|
||||
| `checks-node-core-test` | Шарди core Node tests, без ліній 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-тести built-CLI і smoke startup-memory | Зміни, релевантні для Node |
|
||||
| `checks` | Verifier для channel tests built-artifact | Зміни, релевантні для Node |
|
||||
| `checks-node-compat-node22` | Збірка сумісності Node 22 і smoke-лінія | Ручний CI dispatch для релізів |
|
||||
| `check-docs` | Форматування документації, lint і перевірки broken-link | Документацію змінено |
|
||||
| `skills-python` | Ruff + pytest для Skills на базі Python | Зміни, релевантні для Python-skill |
|
||||
| `checks-windows` | Windows-специфічні тести process/path плюс регресії shared runtime import specifier | Зміни, релевантні для Windows |
|
||||
| `macos-node` | Лінія TypeScript-тестів macOS із використанням shared built artifacts | Зміни, релевантні для macOS |
|
||||
| `macos-swift` | Swift lint, збірка й тести для macOS-застосунку | Зміни, релевантні для macOS |
|
||||
| `android` | Android unit tests для обох flavor плюс одна збірка debug APK | Зміни, релевантні для Android |
|
||||
| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успіх main CI або ручний dispatch |
|
||||
|
||||
## Порядок fail-fast
|
||||
|
||||
1. `preflight` вирішує, які lanes взагалі існують. Логіка `docs-scope` і `changed-scope` є кроками всередині цього завдання, а не окремими завданнями.
|
||||
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко падають без очікування важчих artifact і platform matrix jobs.
|
||||
3. `build-artifacts` перекривається зі швидкими Linux lanes, щоб downstream consumers могли стартувати щойно shared build буде готовий.
|
||||
4. Важчі platform і runtime lanes розгортаються після цього: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`.
|
||||
1. `preflight` вирішує, які лінії взагалі існують. Логіка `docs-scope` і `changed-scope` є кроками всередині цього завдання, а не окремими завданнями.
|
||||
2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко падають, не чекаючи на важчі artifact і platform matrix jobs.
|
||||
3. `build-artifacts` перекривається зі швидкими Linux-лініями, щоб downstream-споживачі могли стартувати, щойно shared build буде готовий.
|
||||
4. Важчі platform і runtime лінії розгортаються після цього: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-core-test`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`.
|
||||
|
||||
GitHub може позначати superseded jobs як `cancelled`, коли новіший push потрапляє в той самий PR або `main` ref. Сприймайте це як CI noise, якщо найновіший run для того самого ref також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тому вони все одно повідомляють звичайні shard failures, але не стають у чергу після того, як увесь workflow уже superseded. Автоматичний CI concurrency key має версію (`CI-v7-*`), щоб GitHub-side zombie у старій queue group не міг безкінечно блокувати новіші main runs. Ручні full-suite runs використовують `CI-manual-v1-*` і не скасовують in-progress runs.
|
||||
GitHub може позначати superseded jobs як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Вважайте це шумом CI, якщо найновіший запуск для того самого ref також не падає. Aggregate shard checks використовують `!cancelled() && always()`, тож вони все ще повідомляють про звичайні shard failures, але не стають у чергу після того, як увесь workflow вже був superseded. Автоматичний concurrency key CI версіонований (`CI-v7-*`), тому GitHub-side zombie у старій queue group не може нескінченно блокувати новіші main runs. Ручні full-suite runs використовують `CI-manual-v1-*` і не скасовують запуски, що вже виконуються.
|
||||
|
||||
## Scope і маршрутизація
|
||||
## Область і маршрутизація
|
||||
|
||||
Логіка scope міститься в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`. Manual dispatch пропускає changed-scope detection і змушує preflight manifest поводитися так, ніби змінилася кожна scoped area.
|
||||
Логіка області живе в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`. Ручний dispatch пропускає changed-scope detection і змушує preflight manifest поводитися так, ніби кожна scoped area змінилася.
|
||||
|
||||
- **Редагування CI workflow** валідують Node CI graph плюс workflow linting, але самі по собі не примушують Windows, Android або macOS native builds; ці platform lanes залишаються scoped до platform source changes.
|
||||
- **CI routing-only edits, вибрані cheap core-test fixture edits і вузькі plugin contract helper/test-routing edits** використовують швидкий Node-only manifest path: `preflight`, security і одне завдання `checks-fast-core`. Цей path пропускає build artifacts, Node 22 compatibility, channel contracts, full core shards, bundled-plugin shards і additional guard matrices, коли зміна обмежена routing або helper surfaces, які fast task перевіряє напряму.
|
||||
- **Windows Node checks** scoped до специфічних для Windows process/path wrappers, npm/pnpm/UI runner helpers, package manager config і CI workflow surfaces, які виконують цю lane; непов’язані source, plugin, install-smoke і test-only changes залишаються на Linux Node lanes.
|
||||
- **Зміни CI workflow** валідують Node CI graph плюс workflow linting, але самі по собі не примушують Windows, Android або macOS native builds; ці platform lanes залишаються прив’язаними до platform source changes.
|
||||
- **Routing-only зміни CI, вибрані cheap core-test fixture edits і вузькі plugin contract helper/test-routing edits** використовують швидкий Node-only manifest path: `preflight`, security і одне завдання `checks-fast-core`. Цей шлях пропускає build artifacts, сумісність Node 22, channel contracts, full core shards, bundled-plugin shards і additional guard matrices, коли зміна обмежена routing або helper surfaces, які fast task безпосередньо перевіряє.
|
||||
- **Windows Node checks** обмежені Windows-специфічними process/path wrappers, npm/pnpm/UI runner helpers, package manager config і CI workflow surfaces, які виконують цю лінію; непов’язані source, plugin, install-smoke і test-only зміни залишаються на Linux Node lanes.
|
||||
|
||||
Найповільніші Node test families розділено або збалансовано, щоб кожне завдання залишалося малим без надмірного резервування runners: channel contracts запускаються як три weighted shards, малі core unit lanes об’єднуються парами, auto-reply запускається як чотири збалансовані workers (із reply subtree, розділеним на agent-runner, dispatch і commands/state-routing shards), а agentic gateway/plugin configs розподіляються між наявними source-only agentic Node jobs замість очікування built artifacts. Broad browser, QA, media і miscellaneous plugin tests використовують свої dedicated Vitest configs замість shared plugin catch-all. Include-pattern shards записують timing entries із використанням CI shard name, тому `.artifacts/vitest-shard-timings.json` може відрізнити цілий config від filtered shard. `check-additional` тримає package-boundary compile/canary work разом і відокремлює runtime topology architecture від gateway watch coverage; boundary guard shard запускає свої малі independent guards паралельно всередині одного job. Gateway watch, channel tests і core support-boundary shard запускаються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані.
|
||||
Найповільніші родини Node tests розділені або збалансовані, щоб кожне завдання залишалося малим без надмірного резервування runners: channel contracts запускаються як три weighted shards, малі core unit lanes згруповані попарно, auto-reply запускається як чотири збалансовані workers (із reply subtree, розділеним на agent-runner, dispatch і commands/state-routing shards), а agentic gateway/plugin configs розподілені між наявними source-only agentic Node jobs замість очікування built artifacts. Широкі browser, QA, media і miscellaneous plugin tests використовують свої dedicated Vitest configs замість shared plugin catch-all. Include-pattern shards записують timing entries із використанням CI shard name, тому `.artifacts/vitest-shard-timings.json` може відрізнити цілий config від filtered shard. `check-additional` тримає package-boundary compile/canary work разом і відокремлює runtime topology architecture від gateway watch coverage; boundary guard shard запускає свої малі independent guards конкурентно всередині одного job. Gateway watch, channel tests і core support-boundary shard запускаються конкурентно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` вже зібрані.
|
||||
|
||||
Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane усе одно компілює flavor із SMS/call-log BuildConfig flags, уникаючи duplicate debug APK packaging job для кожного Android-relevant push.
|
||||
Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Third-party flavor не має окремого source set або manifest; його unit-test lane все одно компілює flavor із SMS/call-log BuildConfig flags, уникаючи дубльованого debug APK packaging job на кожному Android-relevant push.
|
||||
|
||||
Shard `check-dependencies` запускає `pnpm deadcode:dependencies` (production Knip dependency-only pass, pinned до найновішої версії Knip, з вимкненим pnpm minimum release age для встановлення `dlx`) і `pnpm deadcode:unused-files`, який порівнює production unused-file findings від Knip із `scripts/deadcode-unused-files.allowlist.mjs`. Unused-file guard падає, коли PR додає новий unreviewed unused file або залишає stale allowlist entry, водночас зберігаючи intentional dynamic plugin, generated, build, live-test і package bridge surfaces, які Knip не може статично resolve.
|
||||
Shard `check-dependencies` запускає `pnpm deadcode:dependencies` (production-прохід Knip лише для залежностей, закріплений на latest Knip version, із вимкненим minimum release age pnpm для встановлення `dlx`) і `pnpm deadcode:unused-files`, який порівнює Knip production unused-file findings із `scripts/deadcode-unused-files.allowlist.mjs`. Unused-file guard падає, коли PR додає новий непереглянутий unused file або залишає stale allowlist entry, водночас зберігаючи навмисні dynamic plugin, generated, build, live-test і package bridge surfaces, які Knip не може статично resolve.
|
||||
|
||||
## Ручні dispatches
|
||||
|
||||
Manual CI dispatches запускають той самий job graph, що й звичайний CI, але примусово вмикають кожну non-Android scoped lane: Linux Node shards, bundled-plugin shards, channel contracts, Node 22 compatibility, `check`, `check-additional`, build smoke, docs checks, Python Skills, Windows, macOS і Control UI i18n. Standalone manual CI dispatches запускають Android лише з `include_android=true`; повна release umbrella вмикає Android, передаючи `include_android=true`. Plugin prerelease static checks, release-only shard `agentic-plugins`, full extension batch sweep і plugin prerelease Docker lanes виключені з CI. Docker prerelease suite запускається лише тоді, коли `Full Release Validation` dispatches окремий workflow `Plugin Prerelease` із увімкненим release-validation gate.
|
||||
Ручні CI dispatches запускають той самий job graph, що й звичайний CI, але примусово вмикають кожну scoped lane не для Android: Linux Node shards, bundled-plugin shards, channel contracts, сумісність Node 22, `check`, `check-additional`, build smoke, docs checks, Python skills, Windows, macOS і Control UI i18n. Окремі ручні CI dispatches запускають Android лише з `include_android=true`; повна релізна парасолька вмикає Android, передаючи `include_android=true`. Plugin prerelease static checks, release-only shard `agentic-plugins`, full extension batch sweep і plugin prerelease Docker lanes виключені з CI. Docker prerelease suite запускається лише тоді, коли `Full Release Validation` dispatches окремий workflow `Plugin Prerelease` з увімкненим release-validation gate.
|
||||
|
||||
Manual runs використовують унікальну concurrency group, щоб release-candidate full suite не скасовувався іншим push або PR run на тому самому ref. Необов’язковий input `target_ref` дає довіреному caller змогу запустити цей graph проти branch, tag або full commit SHA, використовуючи workflow file з вибраного dispatch ref.
|
||||
Ручні запуски використовують унікальну concurrency group, тому release-candidate full suite не скасовується іншим push або PR run на тому самому ref. Опційний input `target_ref` дає довіреному caller змогу запустити цей graph проти branch, tag або full commit SHA, використовуючи workflow file з вибраного dispatch ref.
|
||||
|
||||
```bash
|
||||
gh workflow run ci.yml --ref release/YYYY.M.D
|
||||
@ -79,17 +79,17 @@ gh workflow run full-release-validation.yml --ref main -f ref=<branch-or-sha>
|
||||
|
||||
## Runners
|
||||
|
||||
| Runner | Завдання |
|
||||
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки й агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки протоколу/контрактів/вбудованих компонентів, сегментовані перевірки контрактів каналів, сегменти `check`, окрім lint, сегменти й агрегати `check-additional`, агрегатні верифікатори тестів Node, перевірки документації, Python skills, workflow-sanity, labeler, auto-response; попередня перевірка install-smoke також використовує Ubuntu, розміщену на GitHub, щоб матриця Blacksmith могла ставати в чергу раніше |
|
||||
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, легші сегменти розширень, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` і `check-test-types` |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, сегменти тестів Linux Node, сегменти тестів вбудованих плагінів, `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (достатньо чутливий до CPU, тож 8 vCPU коштували більше, ніж заощаджували); Docker-збірки install-smoke (час очікування в черзі для 32-vCPU коштував більше, ніж заощаджував) |
|
||||
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` на `openclaw/openclaw`; форки повертаються до `macos-latest` |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; форки повертаються до `macos-latest` |
|
||||
| Засіб виконання | Завдання |
|
||||
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки й агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки протоколу/контрактів/вбудованого, шардовані перевірки контрактів каналів, шарди `check`, крім lint, шарди й агрегати `check-additional`, агрегатні верифікатори тестів Node, перевірки документації, Python skills, workflow-sanity, labeler, auto-response; передперевірка install-smoke також використовує GitHub-хостований Ubuntu, щоб матриця Blacksmith могла ставати в чергу раніше |
|
||||
| `blacksmith-4vcpu-ubuntu-2404` | `CodeQL Critical Quality`, менш ресурсомісткі шарди розширень, `checks-fast-core`, `checks-node-compat-node22`, `check-prod-types` і `check-test-types` |
|
||||
| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди тестів Linux Node, шарди тестів вбудованих plugin, `android` |
|
||||
| `blacksmith-16vcpu-ubuntu-2404` | `check-lint` (достатньо чутливий до CPU, тож 8 vCPU коштували дорожче, ніж заощаджували); Docker-збірки install-smoke (час очікування в черзі 32-vCPU коштував дорожче, ніж заощаджував) |
|
||||
| `blacksmith-16vcpu-windows-2025` | `checks-windows` |
|
||||
| `blacksmith-6vcpu-macos-latest` | `macos-node` на `openclaw/openclaw`; форки повертаються до `macos-latest` |
|
||||
| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; форки повертаються до `macos-latest` |
|
||||
|
||||
## Локальні еквіваленти
|
||||
## Локальні відповідники
|
||||
|
||||
```bash
|
||||
pnpm changed:lanes # inspect the local changed-lane classifier for origin/main...HEAD
|
||||
@ -115,41 +115,39 @@ pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-per
|
||||
pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json
|
||||
```
|
||||
|
||||
## Повна валідація релізу
|
||||
## Повна валідація випуску
|
||||
|
||||
`Full Release Validation` — це ручний парасольковий workflow для «запустити все перед релізом». Він приймає гілку, тег або повний SHA коміту, запускає ручний workflow `CI` з цією ціллю, запускає `Plugin Prerelease` для релізного доказу плагінів/пакетів/статичних файлів/Docker, а також запускає `OpenClaw Release Checks` для install smoke, package acceptance, наборів release-path для Docker, live/E2E, OpenWebUI, QA Lab parity, Matrix і Telegram lanes. Він також може запускати післяпублікаційний workflow `NPM Telegram Beta E2E`, коли надано специфікацію опублікованого пакета.
|
||||
`Full Release Validation` — це ручний парасольковий workflow для «запустити все перед випуском». Він приймає гілку, тег або повний SHA коміту, запускає ручний workflow `CI` із цією ціллю, запускає `Plugin Prerelease` для release-only proof plugin/пакета/статичних ресурсів/Docker, а також запускає `OpenClaw Release Checks` для install smoke, package acceptance, наборів release-path Docker, live/E2E, OpenWebUI, паритету QA Lab, Matrix і смуг Telegram. Він також може запускати після публікації workflow `NPM Telegram Beta E2E`, коли надано специфікацію опублікованого пакета.
|
||||
|
||||
Дивіться [Повну валідацію релізу](/uk/reference/full-release-validation) для
|
||||
Див. [Повну валідацію випуску](/uk/reference/full-release-validation) для
|
||||
матриці етапів, точних назв завдань workflow, відмінностей профілів, артефактів і
|
||||
цільових обробників повторного запуску.
|
||||
цільових ручок повторного запуску.
|
||||
|
||||
`release_profile` керує шириною live/provider, переданою у release checks. Ручні
|
||||
релізні workflow за замовчуванням використовують `stable`; використовуйте `full` лише тоді, коли ви
|
||||
навмисно хочете широку рекомендаційну матрицю провайдерів/медіа.
|
||||
`release_profile` керує шириною live/provider, що передається до перевірок випуску. Ручні workflow випуску за замовчуванням використовують `stable`; використовуйте `full` лише тоді, коли навмисно потрібна широка рекомендаційна матриця provider/media.
|
||||
|
||||
- `minimum` залишає найшвидші критичні для релізу OpenAI/core lanes.
|
||||
- `minimum` залишає найшвидші критичні для випуску смуги OpenAI/core.
|
||||
- `stable` додає стабільний набір provider/backend.
|
||||
- `full` запускає широку рекомендаційну матрицю provider/media.
|
||||
|
||||
Парасолька записує ідентифікатори запущених дочірніх запусків, а фінальне завдання `Verify full validation` повторно перевіряє поточні висновки дочірніх запусків і додає таблиці найповільніших завдань для кожного дочірнього запуску. Якщо дочірній workflow перезапущено і він став зеленим, перезапустіть лише батьківське завдання verifier, щоб оновити результат парасольки та підсумок часу.
|
||||
Парасолька записує id запущених дочірніх прогонів, а фінальне завдання `Verify full validation` повторно перевіряє поточні висновки дочірніх прогонів і додає таблиці найповільніших завдань для кожного дочірнього прогону. Якщо дочірній workflow перезапущено й він стає зеленим, перезапустіть лише батьківське завдання верифікатора, щоб оновити результат парасольки та підсумок часу.
|
||||
|
||||
Для відновлення і `Full Release Validation`, і `OpenClaw Release Checks` приймають `rerun_group`. Використовуйте `all` для release candidate, `ci` лише для звичайного дочірнього full CI, `plugin-prerelease` лише для дочірнього plugin prerelease, `release-checks` для кожного релізного дочірнього workflow або вужчу групу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` чи `npm-telegram` у парасольці. Це тримає повторний запуск невдалої release box обмеженим після цільового виправлення.
|
||||
Для відновлення і `Full Release Validation`, і `OpenClaw Release Checks` приймають `rerun_group`. Використовуйте `all` для кандидата на випуск, `ci` лише для звичайного дочірнього повного CI, `plugin-prerelease` лише для дочірнього prerelease plugin, `release-checks` для кожного дочірнього завдання випуску або вужчу групу: `install-smoke`, `cross-os`, `live-e2e`, `package`, `qa`, `qa-parity`, `qa-live` чи `npm-telegram` у парасольці. Це утримує повторний запуск невдалого release box у межах після цільового виправлення.
|
||||
|
||||
`OpenClaw Release Checks` використовує довірене посилання workflow, щоб один раз розв’язати вибраний ref у tarball `release-package-under-test`, а потім передає цей артефакт і в Docker workflow live/E2E release-path, і в сегмент package acceptance. Це зберігає байти пакета узгодженими між release boxes і уникає повторного пакування того самого кандидата в кількох дочірніх завданнях.
|
||||
`OpenClaw Release Checks` використовує довірене посилання workflow, щоб один раз розв’язати вибране посилання в tarball `release-package-under-test`, а потім передає цей артефакт і до live/E2E release-path Docker workflow, і до шарда package acceptance. Це зберігає байти пакета узгодженими між release boxes і уникає повторного пакування того самого кандидата в кількох дочірніх завданнях.
|
||||
|
||||
Дублікати запусків `Full Release Validation` для `ref=main` і `rerun_group=all`
|
||||
замінюють старішу парасольку. Батьківський монітор скасовує будь-який дочірній workflow, який
|
||||
він уже запустив, коли батьківський workflow скасовано, тож новіша валідація main
|
||||
не стоїть позаду застарілого двогодинного запуску release-check. Валідація release branch/tag
|
||||
Дублікати прогонів `Full Release Validation` для `ref=main` і `rerun_group=all`
|
||||
замінюють старішу парасольку. Батьківський монітор скасовує будь-який дочірній workflow,
|
||||
який він уже запустив, коли батьківський скасовано, тож новіша валідація main
|
||||
не стоятиме за застарілим двогодинним прогоном release-check. Валідація release-гілок/тегів
|
||||
і цільові групи повторного запуску зберігають `cancel-in-progress: false`.
|
||||
|
||||
## Live та E2E сегменти
|
||||
## Live та E2E шарди
|
||||
|
||||
Дочірній live/E2E реліз зберігає широке нативне покриття `pnpm test:live`, але запускає його як іменовані сегменти через `scripts/test-live-shard.mjs` замість одного послідовного завдання:
|
||||
Дочірній live/E2E випуск зберігає широке нативне покриття `pnpm test:live`, але запускає його як іменовані шарди через `scripts/test-live-shard.mjs` замість одного послідовного завдання:
|
||||
|
||||
- `native-live-src-agents`
|
||||
- `native-live-src-gateway-core`
|
||||
- provider-filtered завдання `native-live-src-gateway-profiles`
|
||||
- відфільтровані за provider завдання `native-live-src-gateway-profiles`
|
||||
- `native-live-src-gateway-backends`
|
||||
- `native-live-test`
|
||||
- `native-live-extensions-a-k`
|
||||
@ -157,57 +155,57 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac
|
||||
- `native-live-extensions-openai`
|
||||
- `native-live-extensions-o-z-other`
|
||||
- `native-live-extensions-xai`
|
||||
- розділені сегменти media audio/video і provider-filtered music segments
|
||||
- розділені шарди audio/video для media та відфільтровані за provider шарди music
|
||||
|
||||
Це зберігає те саме покриття файлів, водночас спрощуючи повторний запуск і діагностику повільних збоїв live provider. Агрегатні назви сегментів `native-live-extensions-o-z`, `native-live-extensions-media` і `native-live-extensions-media-music` лишаються чинними для ручних одноразових повторних запусків.
|
||||
Це зберігає те саме покриття файлів, водночас спрощуючи повторний запуск і діагностику повільних збоїв live provider. Агрегатні назви шардів `native-live-extensions-o-z`, `native-live-extensions-media` і `native-live-extensions-media-music` залишаються чинними для ручних одноразових повторних запусків.
|
||||
|
||||
Нативні live media segments запускаються в `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, зібраному workflow `Live Media Runner Image`. Цей образ попередньо встановлює `ffmpeg` і `ffprobe`; media jobs лише перевіряють бінарні файли перед setup. Тримайте live suites на базі Docker на звичайних Blacksmith runners — container jobs є неправильним місцем для запуску вкладених Docker tests.
|
||||
Нативні live media шарди виконуються в `ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04`, зібраному workflow `Live Media Runner Image`. У цьому образі попередньо встановлено `ffmpeg` і `ffprobe`; media-завдання лише перевіряють бінарні файли перед налаштуванням. Тримайте Docker-backed live suites на звичайних раннерах Blacksmith — контейнерні завдання є неправильним місцем для запуску вкладених Docker-тестів.
|
||||
|
||||
Live model/backend segments на базі Docker використовують окремий спільний образ `ghcr.io/openclaw/openclaw-live-test:<sha>` для кожного вибраного коміту. Live release workflow збирає та публікує цей образ один раз, після чого Docker live model, provider-sharded gateway, CLI backend, ACP bind і Codex harness segments запускаються з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway Docker segments мають явні обмеження `timeout` на рівні скриптів нижче за timeout завдання workflow, щоб застряглий контейнер або шлях очищення швидко завершувався з помилкою, а не споживав увесь бюджет release-check. Якщо ці сегменти самостійно перебудовують повну source Docker target, релізний запуск налаштовано неправильно і він марнуватиме wall clock на дубльовані збірки образів.
|
||||
Docker-backed live model/backend шарди використовують окремий спільний образ `ghcr.io/openclaw/openclaw-live-test:<sha>` для вибраного коміту. Live release workflow збирає й публікує цей образ один раз, а потім Docker live model, шардований за provider Gateway, CLI backend, ACP bind і шарди Codex harness запускаються з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Gateway Docker шарди мають явні обмеження `timeout` на рівні скриптів нижче за timeout завдання workflow, щоб завислий контейнер або шлях очищення швидко падав, а не споживав увесь бюджет release-check. Якщо ці шарди незалежно перебудовують повну source Docker target, release-прогін налаштовано неправильно, і він марнуватиме wall clock на дублікати збірок образів.
|
||||
|
||||
## Package Acceptance
|
||||
|
||||
Використовуйте `Package Acceptance`, коли питання звучить як «чи працює цей installable пакет OpenClaw як продукт?» Він відрізняється від звичайного CI: звичайний CI перевіряє source tree, тоді як package acceptance перевіряє один tarball через той самий Docker E2E harness, яким користувачі послуговуються після встановлення або оновлення.
|
||||
Використовуйте `Package Acceptance`, коли питання звучить так: «чи працює цей інстальований пакет OpenClaw як продукт?» Він відрізняється від звичайного CI: звичайний CI перевіряє дерево вихідного коду, тоді як package acceptance перевіряє один tarball через той самий Docker E2E harness, який користувачі застосовують після встановлення або оновлення.
|
||||
|
||||
### Завдання
|
||||
|
||||
1. `resolve_package` перевіряє `workflow_ref`, визначає одного кандидата пакета, записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує `.artifacts/docker-e2e-package/package-candidate.json`, завантажує обидва як артефакт `package-under-test` і друкує джерело, посилання workflow, посилання пакета, версію, SHA-256 і профіль у підсумку кроку GitHub.
|
||||
2. `docker_acceptance` викликає `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і `package_artifact_name=package-under-test`. Повторно використовуваний workflow завантажує цей артефакт, перевіряє інвентар tarball, за потреби готує Docker-образи package-digest і запускає вибрані Docker-лінії для цього пакета замість пакування checkout workflow. Коли профіль вибирає кілька цільових `docker_lanes`, повторно використовуваний workflow готує пакет і спільні образи один раз, а потім розгалужує ці лінії як паралельні цільові Docker-завдання з унікальними артефактами.
|
||||
3. `package_telegram` опціонально викликає `NPM Telegram Beta E2E`. Він запускається, коли `telegram_mode` не є `none`, і встановлює той самий артефакт `package-under-test`, коли Package Acceptance визначив його; автономний Telegram dispatch усе ще може встановлювати опубліковану npm-специфікацію.
|
||||
4. `summary` завершує workflow з помилкою, якщо визначення пакета, Docker acceptance або опціональна Telegram-лінія зазнали невдачі.
|
||||
1. `resolve_package` витягує `workflow_ref`, визначає одного кандидата пакета, записує `.artifacts/docker-e2e-package/openclaw-current.tgz`, записує `.artifacts/docker-e2e-package/package-candidate.json`, вивантажує обидва як артефакт `package-under-test` і виводить джерело, посилання workflow, посилання пакета, версію, SHA-256 і профіль у підсумку кроку GitHub.
|
||||
2. `docker_acceptance` викликає `openclaw-live-and-e2e-checks-reusable.yml` з `ref=workflow_ref` і `package_artifact_name=package-under-test`. Повторно використовуваний workflow завантажує цей артефакт, перевіряє інвентар tarball, за потреби готує Docker-образи з digest пакета й запускає вибрані Docker-напрями для цього пакета замість пакування checkout workflow. Коли профіль вибирає кілька цільових `docker_lanes`, повторно використовуваний workflow готує пакет і спільні образи один раз, а потім розгортає ці напрями як паралельні цільові Docker-завдання з унікальними артефактами.
|
||||
3. `package_telegram` за бажанням викликає `NPM Telegram Beta E2E`. Він запускається, коли `telegram_mode` не дорівнює `none`, і встановлює той самий артефакт `package-under-test`, якщо Package Acceptance визначив його; окремий dispatch Telegram усе ще може встановити опубліковану npm-специфікацію.
|
||||
4. `summary` завершує workflow з помилкою, якщо визначення пакета, Docker acceptance або необов’язковий напрям Telegram завершилися невдало.
|
||||
|
||||
### Джерела кандидатів
|
||||
|
||||
- `source=npm` приймає лише `openclaw@beta`, `openclaw@latest` або точну версію релізу OpenClaw, наприклад `openclaw@2026.4.27-beta.2`. Використовуйте це для acceptance опублікованих beta/stable.
|
||||
- `source=ref` пакує довірену гілку, тег або повний SHA коміту `package_ref`. Resolver отримує гілки/теги OpenClaw, перевіряє, що вибраний коміт досяжний з історії гілки репозиторію або тегу релізу, встановлює залежності у від’єднаному worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`.
|
||||
- `source=ref` пакує довірену гілку `package_ref`, тег або повний commit SHA. Резолвер отримує гілки/теги OpenClaw, перевіряє, що вибраний commit досяжний з історії гілок репозиторію або релізного тегу, встановлює залежності у від’єднаному worktree і пакує його за допомогою `scripts/package-openclaw-for-docker.mjs`.
|
||||
- `source=url` завантажує HTTPS `.tgz`; `package_sha256` є обов’язковим.
|
||||
- `source=artifact` завантажує один `.tgz` з `artifact_run_id` і `artifact_name`; `package_sha256` є опціональним, але його варто надавати для артефактів, поширених назовні.
|
||||
- `source=artifact` завантажує один `.tgz` з `artifact_run_id` і `artifact_name`; `package_sha256` необов’язковий, але його слід указувати для зовнішньо поширених артефактів.
|
||||
|
||||
Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це довірений код workflow/обв’язки, який запускає тест. `package_ref` — це вихідний коміт, який пакується, коли `source=ref`. Це дозволяє поточній тестовій обв’язці перевіряти старі довірені вихідні коміти без запуску старої логіки workflow.
|
||||
Тримайте `workflow_ref` і `package_ref` окремо. `workflow_ref` — це довірений код workflow/тестового harness, який запускає тест. `package_ref` — це вихідний commit, який пакується, коли `source=ref`. Це дає змогу поточному тестовому harness перевіряти старі довірені вихідні commit без запуску старої логіки workflow.
|
||||
|
||||
### Профілі наборів
|
||||
|
||||
- `smoke` — `npm-onboard-channel-agent`, `gateway-network`, `config-reload`
|
||||
- `package` — `npm-onboard-channel-agent`, `doctor-switch`, `update-channel-switch`, `upgrade-survivor`, `published-upgrade-survivor`, `bundled-channel-deps-compat`, `plugins-offline`, `plugin-update`
|
||||
- `product` — `package` плюс `mcp-channels`, `cron-mcp-cleanup`, `openai-web-search-minimal`, `openwebui`
|
||||
- `full` — повні фрагменти Docker release-path з OpenWebUI
|
||||
- `full` — повні фрагменти release-path Docker з OpenWebUI
|
||||
- `custom` — точні `docker_lanes`; обов’язково, коли `suite_profile=custom`
|
||||
|
||||
Профіль `package` використовує offline-покриття plugin, щоб перевірка опублікованого пакета не залежала від доступності live ClawHub. Опціональна Telegram-лінія повторно використовує артефакт `package-under-test` у `NPM Telegram Beta E2E`, а шлях опублікованої npm-специфікації збережено для автономних dispatch.
|
||||
Профіль `package` використовує офлайн-покриття plugin, щоб валідація опублікованого пакета не залежала від доступності live ClawHub. Необов’язковий напрям Telegram повторно використовує артефакт `package-under-test` у `NPM Telegram Beta E2E`, а шлях опублікованої npm-специфікації збережено для окремих dispatch.
|
||||
|
||||
Перевірки релізу викликають Package Acceptance з `source=ref`, `package_ref=<release-ref>`, `workflow_ref=<release workflow ref>`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` і `telegram_mode=mock-openai`. Docker-фрагменти release-path покривають перетин ліній package/update/plugin; Package Acceptance зберігає artifact-native proof для сумісності bundled-channel, offline plugin і Telegram щодо того самого визначеного tarball пакета. Cross-OS перевірки релізу все ще покривають специфічні для ОС onboarding, installer і platform behavior; перевірку продукту package/update слід починати з Package Acceptance. Docker-лінія `published-upgrade-survivor` перевіряє одну опубліковану baseline пакета за запуск. У Package Acceptance визначений tarball `package-under-test` завжди є кандидатом, а `published_upgrade_survivor_baseline` вибирає fallback опубліковану baseline, за замовчуванням `openclaw@latest`; команди rerun для failed-lane зберігають цю baseline. Встановіть `published_upgrade_survivor_baselines=release-history`, щоб розширити лінію на дедупліковану history matrix: останні шість stable-релізів, `2026.4.23` і останній stable-реліз до `2026-03-15`. Встановіть `published_upgrade_survivor_scenarios=reported-issues`, щоб розширити ті самі baselines на issue-shaped fixtures для Feishu config/runtime-deps, збережених bootstrap/persona-файлів, tilde log paths і застарілих versioned runtime-deps roots. Локальні aggregate-запуски можуть передавати точні package specs через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, зберігати одну лінію з `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, наприклад `openclaw@2026.4.15`, або встановлювати `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` для scenario matrix. Опублікована лінія налаштовує 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-mini`, щоб proof встановлення й gateway залишався швидким і детермінованим.
|
||||
Релізні перевірки викликають Package Acceptance з `source=ref`, `package_ref=<release-ref>`, `workflow_ref=<release workflow ref>`, `suite_profile=custom`, `docker_lanes='bundled-channel-deps-compat plugins-offline'` і `telegram_mode=mock-openai`. Фрагменти release-path Docker покривають суміжні напрями package/update/plugin; Package Acceptance зберігає artifact-native перевірку сумісності bundled-channel, офлайн plugin і доказ Telegram для того самого визначеного package tarball. Cross-OS релізні перевірки все ще покривають OS-специфічний onboarding, installer і поведінку платформи; валідацію продукту package/update слід починати з Package Acceptance. Docker-напрям `published-upgrade-survivor` перевіряє один опублікований базовий пакет за запуск. У Package Acceptance визначений tarball `package-under-test` завжди є кандидатом, а `published_upgrade_survivor_baseline` вибирає резервну опубліковану baseline, за замовчуванням `openclaw@latest`; команди повторного запуску невдалого напряму зберігають цю baseline. Установіть `published_upgrade_survivor_baselines=release-history`, щоб розширити напрям до дедуплікованої матриці історії: останні шість stable-релізів, `2026.4.23` і останній stable-реліз до `2026-03-15`. Установіть `published_upgrade_survivor_scenarios=reported-issues`, щоб розширити ті самі baselines на issue-подібні fixtures для конфігурації/runtime-deps Feishu, збережених bootstrap/persona файлів, шляхів журналів із тильдою та застарілих versioned runtime-deps коренів. Локальні агреговані запуски можуть передавати точні package specs через `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS`, залишати один напрям із `OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC`, наприклад `openclaw@2026.4.15`, або встановлювати `OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS` для матриці сценаріїв. Опублікований напрям налаштовує baseline за допомогою вбудованого рецепта команди `openclaw config set`, записує кроки рецепта в `summary.json` і перевіряє `/healthz`, `/readyz`, а також статус RPC після старту Gateway. Свіжі напрями packaged і installer для Windows також перевіряють, що встановлений пакет може імпортувати browser-control override із сирого абсолютного шляху Windows. Cross-OS agent-turn smoke для OpenAI за замовчуванням використовує `OPENCLAW_CROSS_OS_OPENAI_MODEL`, якщо задано, інакше `openai/gpt-5.4-mini`, тому доказ встановлення й Gateway залишається швидким і детермінованим.
|
||||
|
||||
### Вікна сумісності зі спадщиною
|
||||
### Вікна сумісності зі спадковими версіями
|
||||
|
||||
Package Acceptance має обмежені вікна сумісності зі спадщиною для вже опублікованих пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть використовувати compatibility path:
|
||||
Package Acceptance має обмежені вікна сумісності зі спадковими версіями для вже опублікованих пакетів. Пакети до `2026.4.25` включно, зокрема `2026.4.25-beta.*`, можуть використовувати шлях сумісності:
|
||||
|
||||
- відомі приватні QA-записи в `dist/postinstall-inventory.json` можуть вказувати на файли, пропущені з tarball;
|
||||
- `doctor-switch` може пропускати підвипадок persistence `gateway install --wrapper`, коли пакет не надає цей прапорець;
|
||||
- `update-channel-switch` може обрізати відсутні `pnpm.patchedDependencies` з fake git fixture, отриманого з tarball, і може логувати відсутній persisted `update.channel`;
|
||||
- plugin smokes можуть читати застарілі місця install-record або приймати відсутню persistence marketplace install-record;
|
||||
- `plugin-update` може дозволяти міграцію config metadata, водночас усе ще вимагаючи, щоб install record і no-reinstall behavior залишалися незмінними.
|
||||
- відомі приватні записи QA у `dist/postinstall-inventory.json` можуть указувати на файли, пропущені в tarball;
|
||||
- `doctor-switch` може пропустити підвипадок збереження `gateway install --wrapper`, коли пакет не надає цей прапорець;
|
||||
- `update-channel-switch` може прибрати відсутні `pnpm.patchedDependencies` з tarball-derived fake git fixture і може логувати відсутній збережений `update.channel`;
|
||||
- plugin smokes можуть читати спадкові розташування install-record або приймати відсутнє збереження marketplace install-record;
|
||||
- `plugin-update` може дозволити міграцію метаданих конфігурації, водночас усе ще вимагаючи, щоб install record і поведінка без перевстановлення залишалися незмінними.
|
||||
|
||||
Опублікований пакет `2026.4.26` також може попереджати про файли штампа local build metadata, які вже були випущені. Пізніші пакети мають відповідати сучасним контрактам; ті самі умови завершуються помилкою замість попередження або пропуску.
|
||||
Опублікований пакет `2026.4.26` також може попереджати про локальні build metadata stamp files, які вже були shipped. Пізніші пакети мають відповідати сучасним контрактам; ті самі умови спричиняють помилку замість попередження або пропуску.
|
||||
|
||||
### Приклади
|
||||
|
||||
@ -250,152 +248,152 @@ gh workflow run package-acceptance.yml \
|
||||
-f docker_lanes='install-e2e plugin-update'
|
||||
```
|
||||
|
||||
Під час налагодження невдалого запуску package acceptance починайте з підсумку `resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перевірте дочірній запуск `docker_acceptance` і його Docker-артефакти: `.artifacts/docker-tests/**/summary.json`, `failures.json`, логи ліній, таймінги фаз і команди rerun. Надавайте перевагу повторному запуску невдалого package profile або точних Docker lanes замість повторного запуску повної release validation.
|
||||
Під час налагодження невдалого запуску package acceptance починайте з підсумку `resolve_package`, щоб підтвердити джерело пакета, версію та SHA-256. Потім перегляньте дочірній запуск `docker_acceptance` і його Docker-артефакти: `.artifacts/docker-tests/**/summary.json`, `failures.json`, журнали напрямів, таймінги фаз і команди повторного запуску. Надавайте перевагу повторному запуску невдалого профілю пакета або точних Docker-напрямів замість повторного запуску повної релізної валідації.
|
||||
|
||||
## Install smoke
|
||||
|
||||
Окремий workflow `Install Smoke` повторно використовує той самий scope script через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`.
|
||||
Окремий workflow `Install Smoke` повторно використовує той самий скрипт scope через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`.
|
||||
|
||||
- **Швидкий шлях** запускається для pull requests, що торкаються Docker/package surfaces, змін bundled plugin package/manifest або поверхонь core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke jobs. Зміни лише source-only bundled plugin, редагування лише tests і редагування лише docs не резервують Docker workers. Швидкий шлях один раз збирає образ root Dockerfile, перевіряє CLI, запускає agents delete shared-workspace CLI smoke, запускає container gateway-network e2e, перевіряє bundled extension build arg і запускає обмежений bundled-plugin Docker profile з aggregate command timeout 240 секунд (Docker run кожного сценарію обмежується окремо).
|
||||
- **Повний шлях** зберігає QR package install і installer Docker/update coverage для нічних scheduled runs, manual dispatches, workflow-call release checks і pull requests, які справді торкаються installer/package/Docker surfaces. У full mode install-smoke готує або повторно використовує один target-SHA GHCR root Dockerfile smoke image, а потім запускає QR package install, root Dockerfile/gateway smokes, installer/update smokes і fast bundled-plugin Docker E2E як окремі завдання, щоб installer work не чекав за root image smokes.
|
||||
- **Швидкий шлях** запускається для pull requests, що зачіпають Docker/package surfaces, зміни bundled plugin package/manifest або core plugin/channel/gateway/Plugin SDK surfaces, які перевіряють Docker smoke jobs. Зміни лише вихідного коду bundled plugin, зміни лише тестів і зміни лише документації не резервують Docker workers. Швидкий шлях один раз збирає образ root Dockerfile, перевіряє CLI, запускає CLI smoke для agents delete shared-workspace, запускає container gateway-network e2e, перевіряє build arg bundled extension і запускає обмежений bundled-plugin Docker profile під 240-секундним aggregate command timeout (кожен Docker-запуск сценарію обмежено окремо).
|
||||
- **Повний шлях** зберігає QR package install і installer Docker/update coverage для нічних scheduled runs, manual dispatches, workflow-call release checks і pull requests, які справді зачіпають installer/package/Docker surfaces. У повному режимі install-smoke готує або повторно використовує один GHCR root Dockerfile smoke image для target-SHA, а потім запускає QR package install, root Dockerfile/gateway smokes, installer/update smokes і швидкий bundled-plugin Docker E2E як окремі завдання, щоб installer work не очікувала за root image smokes.
|
||||
|
||||
Пуші в `main` (зокрема merge commits) не примушують повний шлях; коли changed-scope logic запитувала б full coverage на push, workflow зберігає fast Docker smoke і залишає full install smoke для нічної або release validation.
|
||||
Пуші в `main` (зокрема merge commits) не примушують повний шлях; коли логіка changed-scope запитувала б повне покриття під час push, workflow зберігає швидкий Docker smoke і залишає повний install smoke для нічної або релізної валідації.
|
||||
|
||||
Повільний Bun global install image-provider smoke окремо керується `run_bun_global_install_smoke`. Він запускається за нічним розкладом і з workflow release checks, а manual `Install Smoke` dispatches можуть увімкнути його, але pull requests і пуші в `main` — ні. QR і installer Docker tests зберігають власні install-focused Dockerfiles.
|
||||
Повільний Bun global install image-provider smoke окремо контролюється `run_bun_global_install_smoke`. Він запускається за нічним розкладом і з workflow релізних перевірок, а manual dispatches `Install Smoke` можуть увімкнути його, але pull requests і пуші в `main` — ні. QR і installer Docker tests зберігають власні install-focused Dockerfiles.
|
||||
|
||||
## Локальний Docker E2E
|
||||
|
||||
`pnpm test:docker:all` попередньо збирає один спільний live-test image, один раз пакує OpenClaw як npm tarball і збирає два спільні образи `scripts/e2e/Dockerfile`:
|
||||
|
||||
- bare Node/Git runner для ліній installer/update/plugin-dependency;
|
||||
- функціональний образ, який встановлює той самий tarball у `/app` для normal functionality lanes.
|
||||
- bare Node/Git runner для напрямів installer/update/plugin-dependency;
|
||||
- функціональний образ, який встановлює той самий tarball у `/app` для звичайних functionality lanes.
|
||||
|
||||
Визначення Docker lanes містяться в `scripts/lib/docker-e2e-scenarios.mjs`, planner logic міститься в `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний plan. Scheduler вибирає образ для кожної лінії через `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає лінії з `OPENCLAW_SKIP_DOCKER_BUILD=1`.
|
||||
Визначення Docker-напрямів містяться в `scripts/lib/docker-e2e-scenarios.mjs`, логіка planner — у `scripts/lib/docker-e2e-plan.mjs`, а runner виконує лише вибраний план. Scheduler вибирає образ для кожного напряму за допомогою `OPENCLAW_DOCKER_E2E_BARE_IMAGE` і `OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE`, а потім запускає напрями з `OPENCLAW_SKIP_DOCKER_BUILD=1`.
|
||||
|
||||
### Налаштування
|
||||
### Параметри налаштування
|
||||
|
||||
| Змінна | Типове значення | Призначення |
|
||||
| -------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Кількість слотів основного пулу для звичайних доріжок. |
|
||||
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Кількість слотів tail-пулу, чутливого до провайдерів. |
|
||||
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Обмеження одночасних live-доріжок, щоб провайдери не застосовували throttling. |
|
||||
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Обмеження одночасних доріжок установлення npm. |
|
||||
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Обмеження одночасних багатосервісних доріжок. |
|
||||
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Затримка між стартами доріжок, щоб уникнути шквалу створень Docker daemon; установіть `0` без затримки. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Резервний тайм-аут на доріжку (120 хвилин); вибрані live/tail-доріжки використовують жорсткіші ліміти. |
|
||||
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | не задано | `1` друкує план планувальника без запуску доріжок. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANES` | не задано | Розділений комами список точних доріжок; пропускає cleanup smoke, щоб агенти могли відтворити одну збійну доріжку. |
|
||||
| Змінна | Типове значення | Призначення |
|
||||
| -------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------- |
|
||||
| `OPENCLAW_DOCKER_ALL_PARALLELISM` | 10 | Кількість слотів основного пулу для звичайних ліній. |
|
||||
| `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM` | 10 | Кількість слотів хвостового пулу для ліній, чутливих до провайдерів. |
|
||||
| `OPENCLAW_DOCKER_ALL_LIVE_LIMIT` | 9 | Обмеження одночасних live-ліній, щоб провайдери не застосовували throttling. |
|
||||
| `OPENCLAW_DOCKER_ALL_NPM_LIMIT` | 10 | Обмеження одночасних ліній встановлення npm. |
|
||||
| `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT` | 7 | Обмеження одночасних багатосервісних ліній. |
|
||||
| `OPENCLAW_DOCKER_ALL_START_STAGGER_MS` | 2000 | Рознесення запусків ліній, щоб уникнути сплесків створення в Docker daemon; установіть `0`, щоб вимкнути його. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS` | 7200000 | Резервний тайм-аут на лінію (120 хвилин); вибрані live/хвостові лінії використовують жорсткіші обмеження. |
|
||||
| `OPENCLAW_DOCKER_ALL_DRY_RUN` | не задано | `1` виводить план планувальника без запуску ліній. |
|
||||
| `OPENCLAW_DOCKER_ALL_LANES` | не задано | Розділений комами точний список ліній; пропускає cleanup smoke, щоб агенти могли відтворити одну невдалу лінію. |
|
||||
|
||||
Доріжка, важча за свій ефективний ліміт, усе одно може стартувати з порожнього пулу, а потім працює сама, доки не звільнить ємність. Локальний агрегатор виконує preflight Docker, видаляє застарілі OpenClaw E2E-контейнери, виводить стан активних доріжок, зберігає тривалості доріжок для впорядкування від найдовших, і типово припиняє планувати нові pooled-доріжки після першого збою.
|
||||
Лінія, важча за її ефективне обмеження, усе ще може стартувати з порожнього пулу, а потім працює самостійно, доки не звільнить місткість. Локальний агрегатор попередньо перевіряє Docker, видаляє застарілі OpenClaw E2E-контейнери, виводить стан активних ліній, зберігає таймінги ліній для впорядкування від найдовших, і за замовчуванням припиняє планувати нові пулові лінії після першого збою.
|
||||
|
||||
### Перевикористовуваний live/E2E workflow
|
||||
### Багаторазовий live/E2E workflow
|
||||
|
||||
Перевикористовуваний live/E2E workflow запитує `scripts/test-docker-all.mjs --plan-json`, яке покриття пакета, типу образу, live-образу, доріжки й облікових даних потрібне. Потім `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і підсумки. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує артефакт пакета з поточного запуску, або завантажує артефакт пакета з `package_artifact_run_id`; перевіряє інвентар tarball; збирає й публікує bare/functional GHCR Docker E2E-образи з тегами package digest через кеш шарів Docker від Blacksmith, коли план потребує доріжок із установленим пакетом; і перевикористовує надані inputs `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні образи з package digest замість повторної збірки. Pull Docker-образів повторюється з обмеженим 180-секундним тайм-аутом на спробу, щоб завислий потік registry/cache швидко повторився, а не спожив більшість критичного шляху CI.
|
||||
Багаторазовий live/E2E workflow запитує в `scripts/test-docker-all.mjs --plan-json`, який пакет, тип образу, live-образ, лінія та покриття обліковими даними потрібні. Потім `scripts/docker-e2e.mjs` перетворює цей план на GitHub outputs і summary. Він або пакує OpenClaw через `scripts/package-openclaw-for-docker.mjs`, завантажує артефакт пакета з поточного запуску, або завантажує артефакт пакета з `package_artifact_run_id`; перевіряє інвентар tarball; збирає й публікує bare/functional GHCR Docker E2E-образи з тегом package digest через кеш Docker-шарів Blacksmith, коли план потребує ліній зі встановленим пакетом; і повторно використовує надані inputs `docker_e2e_bare_image`/`docker_e2e_functional_image` або наявні образи package digest замість повторної збірки. Завантаження Docker-образів повторюються з обмеженим тайм-аутом 180 секунд на спробу, щоб завислий потік registry/cache швидко повторювався, а не споживав більшість критичного шляху CI.
|
||||
|
||||
### Фрагменти release-шляху
|
||||
### Фрагменти шляху релізу
|
||||
|
||||
Release Docker-покриття запускає менші chunked-завдання з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен фрагмент завантажував лише потрібний тип образу й виконував кілька доріжок через той самий зважений планувальник:
|
||||
Релізне Docker-покриття запускає менші фрагментовані завдання з `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб кожен фрагмент завантажував лише потрібний йому тип образу та виконував кілька ліній через той самий зважений планувальник:
|
||||
|
||||
- `OPENCLAW_DOCKER_ALL_PROFILE=release-path`
|
||||
- `OPENCLAW_DOCKER_ALL_CHUNK=core | package-update-openai | package-update-anthropic | package-update-core | plugins-runtime-plugins | plugins-runtime-services | plugins-runtime-install-a..h | bundled-channels`
|
||||
|
||||
Поточні release Docker-фрагменти: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, від `plugins-runtime-install-a` до `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` і `bundled-channels-contracts`. Агрегований фрагмент `bundled-channels` залишається доступним для ручних одноразових повторних запусків, а `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` залишаються агрегованими aliases для plugin/runtime. Alias доріжки `install-e2e` залишається агрегованим ручним alias повторного запуску для обох доріжок інсталятора провайдерів. Фрагмент `bundled-channels` запускає розділені доріжки `bundled-channel-*` і `bundled-channel-update-*` замість послідовної all-in-one доріжки `bundled-channel-deps`.
|
||||
Поточні релізні Docker-фрагменти: `core`, `package-update-openai`, `package-update-anthropic`, `package-update-core`, `plugins-runtime-plugins`, `plugins-runtime-services`, від `plugins-runtime-install-a` до `plugins-runtime-install-h`, `bundled-channels-core`, `bundled-channels-update-a`, `bundled-channels-update-discord`, `bundled-channels-update-b` і `bundled-channels-contracts`. Агрегований фрагмент `bundled-channels` лишається доступним для ручних одноразових повторних запусків, а `plugins-runtime-core`, `plugins-runtime` і `plugins-integrations` лишаються агрегованими псевдонімами Plugin/runtime. Псевдонім лінії `install-e2e` лишається агрегованим ручним псевдонімом повторного запуску для обох ліній інсталяторів провайдерів. Фрагмент `bundled-channels` запускає розділені лінії `bundled-channel-*` і `bundled-channel-update-*`, а не послідовну універсальну лінію `bundled-channel-deps`.
|
||||
|
||||
OpenWebUI включається в `plugins-runtime-services`, коли повне покриття release-path його запитує, і зберігає окремий фрагмент `openwebui` лише для dispatches тільки OpenWebUI. Доріжки оновлення bundled-channel повторюють спробу один раз для тимчасових мережевих збоїв npm.
|
||||
OpenWebUI включається в `plugins-runtime-services`, коли повне покриття release-path цього потребує, і зберігає окремий фрагмент `openwebui` лише для dispatch, що стосуються тільки OpenWebUI. Лінії оновлення bundled-channel повторюють спробу один раз для тимчасових мережевих збоїв npm.
|
||||
|
||||
Кожен фрагмент завантажує `.artifacts/docker-tests/` із логами доріжок, тривалостями, `summary.json`, `failures.json`, тривалостями фаз, JSON плану планувальника, таблицями повільних доріжок і командами повторного запуску для кожної доріжки. Input workflow `docker_lanes` запускає вибрані доріжки проти підготовлених образів замість chunk-завдань, що обмежує налагодження збійної доріжки одним цільовим Docker-завданням і готує, завантажує або перевикористовує артефакт пакета для цього запуску; якщо вибрана доріжка є live Docker-доріжкою, цільове завдання збирає live-test образ локально для цього повторного запуску. Згенеровані для кожної доріжки GitHub-команди повторного запуску містять `package_artifact_run_id`, `package_artifact_name` і inputs підготовлених образів, коли ці значення існують, щоб збійна доріжка могла перевикористати точний пакет і образи зі збійного запуску.
|
||||
Кожен фрагмент завантажує `.artifacts/docker-tests/` з журналами ліній, таймінгами, `summary.json`, `failures.json`, таймінгами фаз, JSON плану планувальника, таблицями повільних ліній і командами повторного запуску для кожної лінії. Input workflow `docker_lanes` запускає вибрані лінії проти підготовлених образів замість фрагментованих завдань, що обмежує налагодження невдалої лінії одним цільовим Docker-завданням і готує, завантажує або повторно використовує артефакт пакета для цього запуску; якщо вибрана лінія є live Docker-лінією, цільове завдання локально збирає live-test образ для цього повторного запуску. Згенеровані команди повторного запуску GitHub для кожної лінії містять `package_artifact_run_id`, `package_artifact_name` і inputs підготовлених образів, коли ці значення існують, щоб невдала лінія могла повторно використати точний пакет і образи з невдалого запуску.
|
||||
|
||||
```bash
|
||||
pnpm test:docker:rerun <run-id> # download Docker artifacts and print combined/per-lane targeted rerun commands
|
||||
pnpm test:docker:timings <summary> # slow-lane and phase critical-path summaries
|
||||
```
|
||||
|
||||
Запланований live/E2E workflow щодня запускає повний release-path Docker-набір.
|
||||
Запланований live/E2E workflow щодня запускає повний Docker-набір release-path.
|
||||
|
||||
## Plugin Prerelease
|
||||
## Попередній реліз Plugin
|
||||
|
||||
`Plugin Prerelease` є дорожчим покриттям product/package, тому це окремий workflow, який запускається `Full Release Validation` або явним оператором. Звичайні pull requests, pushes у `main` і standalone ручні CI dispatches тримають цей набір вимкненим. Він балансує тести bundled plugin між вісьмома extension workers; ці extension shard-завдання запускають до двох груп plugin config одночасно з одним Vitest worker на групу й більшим heap Node, щоб насичені імпортами plugin-batches не створювали додаткових CI-завдань. Release-only Docker prerelease path групує цільові Docker-доріжки в невеликі групи, щоб не резервувати десятки runners для завдань на одну-три хвилини.
|
||||
`Plugin Prerelease` є дорожчим покриттям продукту/пакета, тому це окремий workflow, який запускається `Full Release Validation` або явним оператором. Звичайні pull requests, push у `main` і автономні ручні CI dispatch не запускають цей набір. Він балансує тести bundled Plugin між вісьмома extension-воркерами; ці shard-завдання extension виконують до двох груп конфігурації Plugin одночасно з одним Vitest-воркером на групу та більшим heap Node, щоб import-heavy партії Plugin не створювали додаткових CI-завдань. Релізний Docker prerelease path групує цільові Docker-лінії в невеликі групи, щоб не резервувати десятки runner для завдань тривалістю від однієї до трьох хвилин.
|
||||
|
||||
## QA Lab
|
||||
|
||||
QA Lab має окремі CI-доріжки поза основним smart-scoped workflow.
|
||||
QA Lab має окремі CI-лінії поза основним smart-scoped workflow.
|
||||
|
||||
- Workflow `Parity gate` запускається для відповідних змін PR і ручного dispatch; він збирає приватний QA runtime і порівнює mock GPT-5.5 та Opus 4.6 agentic packs.
|
||||
- Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і за ручним dispatch; він розгортає mock parity gate, live Matrix-доріжку, а також live Telegram і Discord-доріжки як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а Telegram/Discord використовують Convex leases.
|
||||
- Workflow `Parity gate` запускається на відповідних змінах PR і ручному dispatch; він збирає приватний QA runtime і порівнює agentic-паки mock GPT-5.5 та Opus 4.6.
|
||||
- Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і при ручному dispatch; він розгортає mock parity gate, live Matrix-лінію та live Telegram і Discord лінії як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а Telegram/Discord використовують оренди Convex.
|
||||
|
||||
Release checks запускають Matrix і Telegram live transport-доріжки з детермінованим mock provider і mock-qualified моделями (`mock-openai/gpt-5.5` і `mock-openai/gpt-5.5-alt`), щоб контракт каналу був ізольований від затримки live model і звичайного запуску provider-plugin. Live transport gateway вимикає memory search, бо QA parity окремо покриває поведінку memory; з’єднання з провайдерами покривають окремі набори live model, native provider і Docker provider.
|
||||
Релізні перевірки запускають live transport-лінії Matrix і Telegram з deterministic mock provider та mock-qualified моделями (`mock-openai/gpt-5.5` і `mock-openai/gpt-5.5-alt`), щоб контракт каналу був ізольований від затримки live-моделі та звичайного запуску provider-plugin. Live transport Gateway вимикає пошук у пам’яті, тому що QA parity окремо покриває поведінку пам’яті; підключення провайдера покривається окремими наборами live model, native provider і Docker provider.
|
||||
|
||||
Matrix використовує `--profile fast` для scheduled і release gates, додаючи `--fail-fast` лише коли checked-out CLI це підтримує. Типове значення CLI і manual workflow input залишаються `all`; ручний dispatch `matrix_profile=all` завжди розбиває повне Matrix-покриття на завдання `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`.
|
||||
Matrix використовує `--profile fast` для запланованих і релізних gate, додаючи `--fail-fast` лише тоді, коли checked-out CLI це підтримує. Типове значення CLI і input ручного workflow лишаються `all`; ручний dispatch `matrix_profile=all` завжди розділяє повне Matrix-покриття на завдання `transport`, `media`, `e2ee-smoke`, `e2ee-deep` і `e2ee-cli`.
|
||||
|
||||
`OpenClaw Release Checks` також запускає release-critical QA Lab-доріжки перед схваленням release; його QA parity gate запускає candidate і baseline packs як паралельні lane-завдання, потім завантажує обидва артефакти в невелике report-завдання для фінального порівняння parity.
|
||||
`OpenClaw Release Checks` також запускає критично важливі для релізу лінії QA Lab перед схваленням релізу; його QA parity gate запускає candidate і baseline паки як паралельні завдання ліній, а потім завантажує обидва артефакти в невелике звітне завдання для фінального parity-порівняння.
|
||||
|
||||
Не ставте PR landing path за `Parity gate`, якщо зміна фактично не торкається QA runtime, model-pack parity або поверхні, якою володіє parity workflow. Для звичайних виправлень channel, config, docs або unit-test вважайте це необов’язковим сигналом і дотримуйтеся scoped CI/check-доказів.
|
||||
Не ставте шлях landing PR за `Parity gate`, якщо зміна фактично не зачіпає QA runtime, model-pack parity або поверхню, якою володіє parity workflow. Для звичайних виправлень каналів, конфігурації, документації або unit-тестів вважайте це необов’язковим сигналом і дотримуйтеся scoped CI/check evidence.
|
||||
|
||||
## CodeQL
|
||||
|
||||
Workflow `CodeQL` навмисно є вузьким first-pass security scanner, а не повним скануванням репозиторію. Daily, manual і non-draft pull request guard runs сканують код Actions workflow плюс найризикованіші поверхні JavaScript/TypeScript за допомогою high-confidence security queries, відфільтрованих до high/critical `security-severity`.
|
||||
Workflow `CodeQL` навмисно є вузьким первинним security scanner, а не повним sweep репозиторію. Щоденні, ручні та non-draft pull request guard-запуски сканують код Actions workflow плюс найризикованіші JavaScript/TypeScript поверхні з high-confidence security queries, відфільтрованими до high/critical `security-severity`.
|
||||
|
||||
Pull request guard залишається легким: він стартує лише для змін у `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` або `src`, і запускає ту саму high-confidence security matrix, що й scheduled workflow. Android і macOS CodeQL не входять до типових PR-запусків.
|
||||
Pull request guard лишається легким: він стартує лише для змін у `.github/actions`, `.github/codeql`, `.github/workflows`, `packages` або `src`, і запускає ту саму high-confidence security matrix, що й запланований workflow. Android і macOS CodeQL не входять до типових PR-запусків.
|
||||
|
||||
### Категорії безпеки
|
||||
|
||||
| Категорія | Поверхня |
|
||||
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/codeql-security-high/core-auth-secrets` | Auth, secrets, sandbox, cron і gateway baseline |
|
||||
| `/codeql-security-high/channel-runtime-boundary` | Контракти реалізації core channel плюс channel plugin runtime, gateway, Plugin SDK, secrets, audit touchpoints |
|
||||
| `/codeql-security-high/network-ssrf-boundary` | Core SSRF, IP parsing, network guard, web-fetch і поверхні Plugin SDK SSRF policy |
|
||||
| `/codeql-security-high/channel-runtime-boundary` | Core channel implementation contracts плюс runtime channel plugin, gateway, Plugin SDK, secrets, audit touchpoints |
|
||||
| `/codeql-security-high/network-ssrf-boundary` | Core SSRF, IP parsing, network guard, web-fetch і поверхні SSRF policy Plugin SDK |
|
||||
| `/codeql-security-high/mcp-process-tool-boundary` | MCP servers, process execution helpers, outbound delivery і agent tool-execution gates |
|
||||
| `/codeql-security-high/plugin-trust-boundary` | Plugin install, loader, manifest, registry, runtime-dependency staging, source-loading і trust-поверхні контракту пакета Plugin SDK |
|
||||
| `/codeql-security-high/plugin-trust-boundary` | Plugin install, loader, manifest, registry, runtime-dependency staging, source-loading і trust surfaces package contract Plugin SDK |
|
||||
|
||||
### Платформо-специфічні security shards
|
||||
### Платформозалежні security shards
|
||||
|
||||
- `CodeQL Android Critical Security` — scheduled Android security shard. Збирає Android app вручну для CodeQL на найменшому Blacksmith Linux runner, прийнятому workflow sanity. Завантажує під `/codeql-critical-security/android`.
|
||||
- `CodeQL macOS Critical Security` — weekly/manual macOS security shard. Збирає macOS app вручну для CodeQL на Blacksmith macOS, відфільтровує dependency build results із завантаженого SARIF і завантажує під `/codeql-critical-security/macos`. Тримається поза daily defaults, бо збірка macOS домінує runtime навіть у чистому стані.
|
||||
- `CodeQL Android Critical Security` — запланований Android security shard. Збирає Android app вручну для CodeQL на найменшому Blacksmith Linux runner, прийнятому workflow sanity. Завантажує під `/codeql-critical-security/android`.
|
||||
- `CodeQL macOS Critical Security` — щотижневий/ручний macOS security shard. Збирає macOS app вручну для CodeQL на Blacksmith macOS, відфільтровує результати dependency build із завантаженого SARIF і завантажує під `/codeql-critical-security/macos`. Утримується поза щоденними типовими запусками, бо macOS build домінує runtime навіть у чистому стані.
|
||||
|
||||
### Категорії Critical Quality
|
||||
|
||||
`CodeQL Critical Quality` є відповідним non-security shard. Він запускає лише error-severity, non-security JavaScript/TypeScript quality queries по вузьких високоцінних поверхнях на меншому Blacksmith Linux runner. Його pull request guard навмисно менший за scheduled profile: non-draft PRs запускають лише відповідні shards `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` і `plugin-sdk-reply-runtime` для змін у коді виконання agent command/model/tool і reply dispatch, config schema/migration/IO code, auth/secrets/sandbox/security code, core channel і bundled channel plugin runtime, gateway protocol/server-method, memory runtime/SDK glue, MCP/process/outbound delivery, provider runtime/model catalog, session diagnostics/delivery queues, plugin loader, Plugin SDK/package-contract або Plugin SDK reply runtime. Зміни CodeQL config і quality workflow запускають усі дванадцять PR quality shards.
|
||||
`CodeQL Critical Quality` є відповідним non-security shard. Він запускає лише error-severity, non-security JavaScript/TypeScript quality queries на вузьких high-value surfaces на меншому Blacksmith Linux runner. Його pull request guard навмисно менший за запланований профіль: non-draft PR запускають лише відповідні shards `agent-runtime-boundary`, `config-boundary`, `core-auth-secrets`, `channel-runtime-boundary`, `gateway-runtime-boundary`, `memory-runtime-boundary`, `mcp-process-runtime-boundary`, `provider-runtime-boundary`, `session-diagnostics-boundary`, `plugin-boundary`, `plugin-sdk-package-contract` і `plugin-sdk-reply-runtime` для змін у коді виконання agent command/model/tool і dispatch replies, коді config schema/migration/IO, auth/secrets/sandbox/security коді, core channel і bundled channel plugin runtime, gateway protocol/server-method, memory runtime/SDK glue, MCP/process/outbound delivery, provider runtime/model catalog, session diagnostics/delivery queues, plugin loader, Plugin SDK/package-contract або Plugin SDK reply runtime. Зміни CodeQL config і quality workflow запускають усі дванадцять PR quality shards.
|
||||
|
||||
Manual dispatch приймає:
|
||||
Ручний 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
|
||||
```
|
||||
|
||||
Вузькі профілі — це навчальні/ітераційні хуки для запуску одного якісного шарда ізольовано.
|
||||
Вузькі профілі — це хуки для навчання/ітерації, щоб запускати один якісний шард ізольовано.
|
||||
|
||||
| Категорія | Поверхня |
|
||||
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/codeql-critical-quality/core-auth-secrets` | Автентифікація, секрети, пісочниця, cron і код межі безпеки Gateway |
|
||||
| `/codeql-critical-quality/config-boundary` | Схема конфігурації, міграція, нормалізація та контракти введення-виведення |
|
||||
| `/codeql-critical-quality/gateway-runtime-boundary` | Схеми протоколу Gateway і контракти серверних методів |
|
||||
| `/codeql-critical-quality/channel-runtime-boundary` | Контракти основних каналів і реалізації вбудованих Plugin каналів |
|
||||
| `/codeql-critical-quality/agent-runtime-boundary` | Виконання команд, диспетчеризація моделей/провайдерів, диспетчеризація та черги автовідповідей, а також runtime-контракти площини керування ACP |
|
||||
| `/codeql-critical-quality/mcp-process-runtime-boundary` | MCP-сервери й мости інструментів, допоміжні засоби нагляду за процесами та контракти вихідної доставки |
|
||||
| `/codeql-critical-quality/memory-runtime-boundary` | SDK хоста пам'яті, runtime-фасади пам'яті, псевдоніми Plugin SDK пам'яті, клейовий код активації runtime пам'яті та команди doctor для пам'яті |
|
||||
| `/codeql-critical-quality/session-diagnostics-boundary` | Внутрішня логіка черги відповідей, черги доставки сесій, допоміжні засоби прив'язування/доставки вихідних сесій, поверхні діагностичних подій/пакетів журналів і CLI-контракти doctor для сесій |
|
||||
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Вхідна диспетчеризація відповідей Plugin SDK, допоміжні засоби payload/розбиття на фрагменти/runtime для відповідей, параметри відповідей каналів, черги доставки та допоміжні засоби прив'язування сесій/тредів |
|
||||
| `/codeql-critical-quality/provider-runtime-boundary` | Нормалізація каталогу моделей, автентифікація та виявлення провайдерів, реєстрація runtime провайдерів, стандартні налаштування/каталоги провайдерів і реєстри web/search/fetch/embedding |
|
||||
| `/codeql-critical-quality/ui-control-plane` | Ініціалізація Control UI, локальне збереження, потоки керування Gateway і runtime-контракти площини керування завданнями |
|
||||
| `/codeql-critical-quality/web-media-runtime-boundary` | Основні web fetch/search, media IO, розуміння медіа, генерація зображень і runtime-контракти генерації медіа |
|
||||
| `/codeql-critical-quality/plugin-boundary` | Контракти завантажувача, реєстру, публічної поверхні та точок входу Plugin SDK |
|
||||
| `/codeql-critical-quality/plugin-sdk-package-contract` | Опублікований вихідний код Plugin SDK на боці пакета та допоміжні засоби контрактів пакетів Plugin |
|
||||
| Категорія | Поверхня |
|
||||
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `/codeql-critical-quality/core-auth-secrets` | Код межі безпеки автентифікації, секретів, пісочниці, Cron і Gateway |
|
||||
| `/codeql-critical-quality/config-boundary` | Схема конфігурації, міграція, нормалізація та контракти IO |
|
||||
| `/codeql-critical-quality/gateway-runtime-boundary` | Схеми протоколу Gateway і контракти методів сервера |
|
||||
| `/codeql-critical-quality/channel-runtime-boundary` | Контракти реалізації основного каналу та вбудованого Plugin каналу |
|
||||
| `/codeql-critical-quality/agent-runtime-boundary` | Виконання команд, диспетчеризація моделей/провайдерів, диспетчеризація й черги автоматичних відповідей, а також runtime-контракти площини керування ACP |
|
||||
| `/codeql-critical-quality/mcp-process-runtime-boundary` | Сервери MCP і мости інструментів, допоміжні засоби нагляду за процесами та контракти вихідної доставки |
|
||||
| `/codeql-critical-quality/memory-runtime-boundary` | SDK хоста пам'яті, runtime-фасади пам'яті, псевдоніми SDK пам'яті Plugin, зв'язувальний код активації runtime пам'яті та команди doctor для пам'яті |
|
||||
| `/codeql-critical-quality/session-diagnostics-boundary` | Внутрішня логіка черги відповідей, черги доставки сеансів, допоміжні засоби прив'язування/доставки вихідних сеансів, поверхні діагностичних подій/пакетів журналів і контракти CLI doctor для сеансів |
|
||||
| `/codeql-critical-quality/plugin-sdk-reply-runtime` | Вхідна диспетчеризація відповідей Plugin SDK, допоміжні засоби payload/розбиття на фрагменти/runtime для відповідей, параметри відповідей каналів, черги доставки та допоміжні засоби прив'язування сеансів/потоків |
|
||||
| `/codeql-critical-quality/provider-runtime-boundary` | Нормалізація каталогу моделей, автентифікація та виявлення провайдерів, реєстрація runtime провайдерів, стандартні значення/каталоги провайдерів і реєстри web/search/fetch/embedding |
|
||||
| `/codeql-critical-quality/ui-control-plane` | Bootstrap інтерфейсу керування, локальне збереження, потоки керування Gateway і runtime-контракти площини керування завданнями |
|
||||
| `/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 |
|
||||
|
||||
Якість залишається окремо від безпеки, щоб результати перевірок якості можна було планувати, вимірювати, вимикати або розширювати без затемнення сигналу безпеки. Розширення CodeQL для Swift, Python і вбудованих Plugin слід додавати назад як обмежену за областю або розшардовану подальшу роботу лише після того, як вузькі профілі матимуть стабільний runtime і сигнал.
|
||||
Якість залишається окремою від безпеки, щоб знахідки щодо якості можна було планувати, вимірювати, вимикати або розширювати, не затуляючи сигнал безпеки. Розширення CodeQL для Swift, Python і вбудованих Plugin слід додавати назад як scoped або sharded подальшу роботу лише після того, як вузькі профілі матимуть стабільні runtime і сигнал.
|
||||
|
||||
## Робочі процеси супроводу
|
||||
## Робочі процеси обслуговування
|
||||
|
||||
### Docs Agent
|
||||
### Агент документації
|
||||
|
||||
Робочий процес `Docs Agent` — це подієво-керована смуга супроводу Codex для підтримання наявної документації у відповідності з нещодавно доданими змінами. Він не має чистого розкладу: успішний CI-запуск push від небота на `main` може його запустити, а ручний dispatch може запустити його напряму. Виклики через workflow-run пропускаються, коли `main` уже зрушив далі або коли інший непропущений запуск Docs Agent був створений протягом останньої години. Коли він запускається, він переглядає діапазон комітів від попереднього непропущеного вихідного SHA Docs Agent до поточного `main`, тож один щогодинний запуск може покрити всі зміни main, накопичені від останнього проходу документації.
|
||||
Робочий процес `Docs Agent` — це подієво-керована лінія обслуговування Codex для підтримання наявної документації узгодженою з нещодавно внесеними змінами. Він не має чистого розкладу: успішний CI-запуск push не від бота на `main` може його запустити, а ручний dispatch може запустити його напряму. Виклики workflow-run пропускаються, коли `main` уже просунувся далі або коли за останню годину було створено інший непропущений запуск Docs Agent. Під час запуску він переглядає діапазон комітів від попереднього непропущеного SHA джерела Docs Agent до поточного `main`, тож один погодинний запуск може охопити всі зміни main, накопичені з моменту останнього проходу документації.
|
||||
|
||||
### Test Performance Agent
|
||||
### Агент продуктивності тестів
|
||||
|
||||
Робочий процес `Test Performance Agent` — це подієво-керована смуга супроводу Codex для повільних тестів. Він не має чистого розкладу: успішний CI-запуск push від небота на `main` може його запустити, але він пропускається, якщо інший виклик workflow-run уже виконувався або виконується цього UTC-дня. Ручний dispatch обходить цей щоденний шлюз активності. Смуга формує згрупований звіт продуктивності Vitest для повного набору, дозволяє Codex робити лише невеликі виправлення продуктивності тестів зі збереженням покриття замість широких рефакторингів, потім повторно запускає звіт повного набору й відхиляє зміни, які зменшують базову кількість прохідних тестів. Якщо базовий стан має падіння тестів, Codex може виправляти лише очевидні збої, а звіт повного набору після агента має пройти перед будь-яким комітом. Коли `main` просувається до того, як push бота потрапить у репозиторій, смуга перебазовує перевірений патч, повторно запускає `pnpm check:changed` і повторює push; конфліктні застарілі патчі пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати таку саму безпечну позицію drop-sudo, як і агент документації.
|
||||
Робочий процес `Test Performance Agent` — це подієво-керована лінія обслуговування Codex для повільних тестів. Він не має чистого розкладу: успішний CI-запуск push не від бота на `main` може його запустити, але він пропускається, якщо інший виклик workflow-run уже виконувався або виконується того самого дня UTC. Ручний dispatch обходить цей щоденний запобіжник активності. Лінія будує згрупований звіт продуктивності Vitest для повного набору тестів, дозволяє Codex робити лише невеликі виправлення продуктивності тестів зі збереженням покриття замість широких рефакторингів, потім повторно запускає звіт повного набору й відхиляє зміни, які зменшують базову кількість тестів, що проходять. Якщо в базовому стані є тести, що падають, Codex може виправляти лише очевидні збої, а звіт повного набору після агента має пройти перед тим, як щось буде закомічено. Коли `main` просувається вперед до того, як bot push потрапить у репозиторій, лінія перебазовує перевірений патч, повторно запускає `pnpm check:changed` і повторює push; конфліктні застарілі патчі пропускаються. Він використовує GitHub-хостований Ubuntu, щоб дія Codex могла зберігати таку саму позицію безпеки drop-sudo, як агент документації.
|
||||
|
||||
### Дублікати PR після злиття
|
||||
### Дублікати PR після merge
|
||||
|
||||
Робочий процес `Duplicate PRs After Merge` — це ручний робочий процес супровідника для очищення дублікатів після landing. За замовчуванням він працює в dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед зміною GitHub він перевіряє, що landing PR змерджено і що кожен дублікат має або спільне згадане issue, або перетин змінених hunk.
|
||||
Робочий процес `Duplicate PRs After Merge` — це ручний робочий процес мейнтейнера для прибирання дублікатів після land. За замовчуванням він працює в dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед змінами в GitHub він перевіряє, що landed PR змерджено й що кожен дублікат має або спільне referenced issue, або перетин змінених hunks.
|
||||
|
||||
```bash
|
||||
gh workflow run duplicate-after-merge.yml \
|
||||
@ -406,25 +404,36 @@ gh workflow run duplicate-after-merge.yml \
|
||||
|
||||
## Локальні контрольні шлюзи та маршрутизація змін
|
||||
|
||||
Локальна логіка changed-lane живе в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний контрольний шлюз суворіший щодо архітектурних меж, ніж широка область платформи CI:
|
||||
Локальна логіка змінених смуг живе в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний контрольний шлюз суворіше ставиться до архітектурних меж, ніж широка область платформи CI:
|
||||
|
||||
- зміни основного production-коду запускають typecheck основного prod і основних тестів, а також основні lint/guards;
|
||||
- зміни лише основних тестів запускають тільки typecheck основних тестів плюс основний lint;
|
||||
- зміни production-коду розширень запускають typecheck prod і тестів розширень плюс lint розширень;
|
||||
- зміни лише тестів розширень запускають typecheck тестів розширень плюс lint розширень;
|
||||
- зміни публічного Plugin SDK або контрактів Plugin розширюються до typecheck розширень, бо розширення залежать від цих основних контрактів (sweep-и Vitest для розширень залишаються явною тестовою роботою);
|
||||
- version bump-и лише метаданих релізу запускають цільові перевірки версії/конфігурації/root-dependency;
|
||||
- невідомі зміни root/config безпечно падають до всіх check lanes.
|
||||
- зміни виробничого коду ядра запускають перевірку типів core prod і core test, а також lint/guards ядра;
|
||||
- зміни лише в тестах ядра запускають тільки перевірку типів core test і lint ядра;
|
||||
- зміни виробничого коду розширень запускають перевірку типів extension prod і extension test, а також lint розширень;
|
||||
- зміни лише в тестах розширень запускають перевірку типів extension test і lint розширень;
|
||||
- зміни публічного Plugin SDK або контракту Plugin розширюються до перевірки типів розширень, бо розширення залежать від цих контрактів ядра (розгортальні перевірки розширень Vitest залишаються явною тестовою роботою);
|
||||
- зміни лише метаданих релізної версії запускають цільові перевірки версії, конфігурації та кореневих залежностей;
|
||||
- невідомі зміни кореня/конфігурації безпечно переходять до всіх смуг перевірок.
|
||||
|
||||
Локальна маршрутизація changed-test живе в `scripts/test-projects.test-support.mjs` і навмисно дешевша за `check:changed`: прямі редагування тестів запускають самі себе, редагування вихідного коду віддають перевагу явним мапінгам, потім sibling-тестам і залежним за import-graph. Конфігурація доставки shared group-room — один із явних мапінгів: зміни конфігурації group visible-reply, режиму доставки source reply або системного prompt message-tool проходять через основні тести відповідей плюс регресії доставки Discord і Slack, щоб зміна спільного стандартного значення падала ще до першого push PR. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли зміна достатньо широка для harness, що дешевий змеплений набір не є надійним проксі.
|
||||
Локальна маршрутизація змінених тестів живе в `scripts/test-projects.test-support.mjs` і навмисно дешевша за `check:changed`: прямі зміни тестів запускають самі себе, зміни джерельного коду віддають перевагу явним зіставленням, потім спорідненим тестам і залежним елементам графа імпортів. Спільна конфігурація доставки групової кімнати є одним з явних зіставлень: зміни конфігурації видимої відповіді групи, режиму доставки відповіді джерела або системної підказки інструмента повідомлень проходять через тести відповідей ядра, а також регресії доставки Discord і Slack, щоб зміна спільного стандартного значення падала ще до першого push PR. Використовуйте `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` лише тоді, коли зміна настільки широка для всього harness, що дешевий зіставлений набір не є надійним наближенням.
|
||||
|
||||
## Валідація Testbox
|
||||
|
||||
Запускайте Testbox з кореня репозиторію та віддавайте перевагу свіжому прогрітому box для широкого доказу. Перш ніж витрачати повільний шлюз на box, який було повторно використано, термін якого сплив або який щойно повідомив про несподівано велику синхронізацію, спершу запустіть `pnpm testbox:sanity` всередині box.
|
||||
Запускайте Testbox з кореня репозиторію та віддавайте перевагу свіжій прогрітій box для широкого підтвердження. Перш ніж витрачати повільний шлюз на box, яку було використано повторно, термін дії якої минув або яка щойно повідомила про несподівано велику синхронізацію, спочатку запустіть `pnpm testbox:sanity` всередині box.
|
||||
|
||||
Sanity check швидко падає, коли зникли потрібні root-файли, як-от `pnpm-lock.yaml`, або коли `git status --short` показує щонайменше 200 відстежуваних видалень. Зазвичай це означає, що стан віддаленої синхронізації не є надійною копією PR; зупиніть цей box і прогрійте свіжий замість налагодження падіння product-тесту. Для навмисних PR із великими видаленнями встановіть `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього sanity-запуску.
|
||||
Перевірка sanity швидко падає, коли потрібні кореневі файли, як-от `pnpm-lock.yaml`, зникли або коли `git status --short` показує щонайменше 200 відстежуваних видалень. Зазвичай це означає, що віддалений стан синхронізації не є надійною копією PR; зупиніть цю box і прогрійте свіжу замість налагодження збою продуктового тесту. Для PR із навмисним великим видаленням задайте `OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1` для цього запуску sanity.
|
||||
|
||||
`pnpm testbox:run` також завершує локальний виклик Blacksmith CLI, який залишається у фазі синхронізації понад п'ять хвилин без виводу після синхронізації. Встановіть `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, щоб вимкнути цей guard, або використайте більше значення в мілісекундах для незвично великих локальних diff.
|
||||
`pnpm testbox:run` також завершує локальний виклик Blacksmith CLI, який залишається у фазі синхронізації понад п'ять хвилин без виводу після синхронізації. Задайте `OPENCLAW_TESTBOX_SYNC_TIMEOUT_MS=0`, щоб вимкнути цей запобіжник, або використайте більше значення в мілісекундах для незвично великих локальних diff.
|
||||
|
||||
Crabbox — це другий віддалений шлях box, яким володіє репозиторій, для підтвердження Linux, коли Blacksmith недоступний або коли бажано використати власну хмарну потужність. Прогрійте box, гідратуйте її через проєктний workflow, потім запускайте команди через Crabbox CLI:
|
||||
|
||||
```bash
|
||||
pnpm crabbox:warmup -- --idle-timeout 90m
|
||||
pnpm crabbox:hydrate -- --id <cbx_id>
|
||||
pnpm crabbox:run -- --id <cbx_id> --shell "OPENCLAW_TESTBOX=1 pnpm check:changed"
|
||||
pnpm crabbox:stop -- <cbx_id>
|
||||
```
|
||||
|
||||
`.crabbox.yaml` володіє стандартними налаштуваннями provider, sync і гідратації GitHub Actions. Він виключає локальний `.git`, щоб гідратований checkout Actions зберігав власні віддалені метадані Git замість синхронізації локальних remotes і сховищ об'єктів maintainer, і виключає локальні runtime/build артефакти, які ніколи не слід передавати. `.github/workflows/crabbox-hydrate.yml` володіє checkout, налаштуванням Node/pnpm, отриманням `origin/main` і передачею несекретного середовища, яке пізніші команди `crabbox run --id <cbx_id>` підхоплюють як source.
|
||||
|
||||
## Пов'язане
|
||||
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете безпечно оновити робочу копію вихідного коду
|
||||
- Вам потрібно зрозуміти поведінку скороченого запису `--update`
|
||||
summary: Довідка CLI для `openclaw update` (відносно безпечне оновлення джерела + автоматичний перезапуск Gateway)
|
||||
- Потрібно розуміти поведінку скороченого запису `--update`
|
||||
summary: Довідник CLI для `openclaw update` (порівняно безпечне оновлення вихідного коду + автоматичний перезапуск Gateway)
|
||||
title: Оновити
|
||||
x-i18n:
|
||||
generated_at: "2026-04-28T11:08:06Z"
|
||||
generated_at: "2026-05-01T08:52:00Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 9cd4be6be8f6ae7df501f8bce3d208dd507ae5a1539f9772101cd844dcd93976
|
||||
source_hash: bc71740dac6b1af8f695ab60d0ffc1b44a10dd40363538c2a8a37ad518790ce9
|
||||
source_path: cli/update.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -17,8 +17,8 @@ x-i18n:
|
||||
|
||||
Безпечно оновлюйте OpenClaw і перемикайтеся між каналами stable/beta/dev.
|
||||
|
||||
Якщо ви встановили через **npm/pnpm/bun** (глобальне встановлення, без git-метаданих),
|
||||
оновлення відбуваються через потік менеджера пакетів у [Оновленні](/uk/install/updating).
|
||||
Якщо ви встановили через **npm/pnpm/bun** (глобальне встановлення, без метаданих git),
|
||||
оновлення виконуються через потік менеджера пакетів у [Оновлення](/uk/install/updating).
|
||||
|
||||
## Використання
|
||||
|
||||
@ -39,13 +39,14 @@ openclaw --update
|
||||
|
||||
## Параметри
|
||||
|
||||
- `--no-restart`: пропустити перезапуск служби Gateway після успішного оновлення. Оновлення через менеджер пакетів, які перезапускають Gateway, перевіряють, що перезапущена служба повідомляє очікувану оновлену версію, перш ніж команда завершиться успішно.
|
||||
- `--channel <stable|beta|dev>`: установити канал оновлення (git + npm; зберігається в конфігурації).
|
||||
- `--tag <dist-tag|version|spec>`: перевизначити цільовий пакет лише для цього оновлення. Для пакетних встановлень `main` зіставляється з `github:openclaw/openclaw#main`.
|
||||
- `--dry-run`: попередньо переглянути заплановані дії оновлення (потік канал/тег/ціль/перезапуск) без запису конфігурації, встановлення, синхронізації plugins або перезапуску.
|
||||
- `--json`: вивести машинозчитуваний JSON `UpdateRunResult`, включно з
|
||||
`postUpdate.plugins.integrityDrifts`, коли під час післяоновлювальної синхронізації plugin виявлено відхилення артефактів npm plugin.
|
||||
- `--timeout <seconds>`: тайм-аут для кожного кроку (типово 1800 с).
|
||||
- `--no-restart`: пропустити перезапуск сервісу Gateway після успішного оновлення. Оновлення через менеджер пакетів, які перезапускають Gateway, перевіряють, що перезапущений сервіс повідомляє очікувану оновлену версію, перш ніж команда завершиться успішно.
|
||||
- `--channel <stable|beta|dev>`: задати канал оновлень (git + npm; зберігається в конфігурації).
|
||||
- `--tag <dist-tag|version|spec>`: перевизначити ціль пакета лише для цього оновлення. Для пакетних установлень `main` відповідає `github:openclaw/openclaw#main`.
|
||||
- `--dry-run`: попередньо переглянути заплановані дії оновлення (канал/тег/ціль/потік перезапуску) без запису конфігурації, встановлення, синхронізації plugins або перезапуску.
|
||||
- `--json`: вивести машинозчитуваний JSON `UpdateRunResult`, зокрема
|
||||
`postUpdate.plugins.integrityDrifts`, коли під час синхронізації plugins після оновлення
|
||||
виявлено розбіжність артефактів npm plugin.
|
||||
- `--timeout <seconds>`: тайм-аут для кожного кроку (за замовчуванням 1800 с).
|
||||
- `--yes`: пропустити запити підтвердження (наприклад, підтвердження пониження версії).
|
||||
|
||||
<Warning>
|
||||
@ -54,7 +55,7 @@ openclaw --update
|
||||
|
||||
## `update status`
|
||||
|
||||
Показати активний канал оновлення + git-тег/гілку/SHA (для вихідних checkout), а також доступність оновлень.
|
||||
Показати активний канал оновлень + тег/гілку/SHA git (для checkout із вихідного коду), а також доступність оновлень.
|
||||
|
||||
```bash
|
||||
openclaw update status
|
||||
@ -65,57 +66,61 @@ openclaw update status --timeout 10
|
||||
Параметри:
|
||||
|
||||
- `--json`: вивести машинозчитуваний JSON стану.
|
||||
- `--timeout <seconds>`: тайм-аут для перевірок (типово 3 с).
|
||||
- `--timeout <seconds>`: тайм-аут для перевірок (за замовчуванням 3 с).
|
||||
|
||||
## `update wizard`
|
||||
|
||||
Інтерактивний потік для вибору каналу оновлення та підтвердження, чи перезапускати Gateway
|
||||
після оновлення (типово перезапускати). Якщо вибрати `dev` без git checkout, він
|
||||
Інтерактивний потік для вибору каналу оновлень і підтвердження, чи перезапускати Gateway
|
||||
після оновлення (за замовчуванням перезапуск виконується). Якщо вибрати `dev` без git checkout, він
|
||||
запропонує створити його.
|
||||
|
||||
Параметри:
|
||||
|
||||
- `--timeout <seconds>`: тайм-аут для кожного кроку оновлення (типово `1800`)
|
||||
- `--timeout <seconds>`: тайм-аут для кожного кроку оновлення (за замовчуванням `1800`)
|
||||
|
||||
## Що це робить
|
||||
## Що він робить
|
||||
|
||||
Коли ви явно перемикаєте канали (`--channel ...`), OpenClaw також підтримує
|
||||
узгодженість способу встановлення:
|
||||
узгодженість методу встановлення:
|
||||
|
||||
- `dev` → забезпечує git checkout (типово: `~/openclaw`, перевизначається через `OPENCLAW_GIT_DIR`),
|
||||
оновлює його та встановлює глобальний CLI з цього checkout.
|
||||
- `dev` → забезпечує git checkout (за замовчуванням: `~/openclaw`, перевизначення через `OPENCLAW_GIT_DIR`),
|
||||
оновлює його та встановлює глобальний CLI із цього checkout.
|
||||
- `stable` → встановлює з npm за допомогою `latest`.
|
||||
- `beta` → надає перевагу npm dist-tag `beta`, але повертається до `latest`, коли beta
|
||||
відсутня або старіша за поточний stable-випуск.
|
||||
|
||||
Автооновлювач ядра Gateway (коли ввімкнений через конфігурацію) повторно використовує той самий шлях оновлення.
|
||||
Основний автооновлювач Gateway (коли його ввімкнено через конфігурацію) запускає шлях оновлення CLI
|
||||
поза активним обробником запиту Gateway. Оновлення через менеджер пакетів у площині керування `update.run`
|
||||
примусово виконують невідкладений перезапуск оновлення після заміни пакета, оскільки старий
|
||||
процес Gateway усе ще може мати в пам’яті фрагменти, що вказують на файли, видалені
|
||||
новим пакетом.
|
||||
|
||||
Для встановлень через менеджер пакетів `openclaw update` визначає цільову версію
|
||||
пакета перед викликом менеджера пакетів. Глобальні встановлення npm використовують поетапне
|
||||
встановлення: OpenClaw встановлює новий пакет у тимчасовий npm-префікс, перевіряє
|
||||
запакований інвентар `dist` там, а потім замінює це чисте дерево пакета в
|
||||
реальному глобальному префіксі. Якщо перевірка не вдається, післяоновлювальні doctor, синхронізація plugin і
|
||||
робота з перезапуску не запускаються з підозрілого дерева. Навіть коли встановлена версія
|
||||
вже збігається з цільовою, команда оновлює глобальне встановлення пакета,
|
||||
а потім запускає синхронізацію plugin, оновлення завершення основних команд і роботу з перезапуску. Це
|
||||
підтримує узгодженість запакованих sidecar і записів plugin, що належать каналу, з
|
||||
установленою збіркою OpenClaw, залишаючи повні перебудови завершення команд plugin для
|
||||
встановлення: OpenClaw встановлює новий пакет у тимчасовий npm prefix, перевіряє
|
||||
пакетований інвентар `dist` там, а потім замінює це чисте дерево пакета в
|
||||
реальному глобальному prefix. Якщо перевірка не вдається, post-update doctor, синхронізація plugin і
|
||||
перезапуск не виконуються з підозрілого дерева. Навіть коли встановлена версія
|
||||
вже відповідає цілі, команда оновлює глобальне встановлення пакета,
|
||||
а потім запускає синхронізацію plugin, оновлення завершень основних команд і перезапуск. Це
|
||||
підтримує узгодженість пакетованих sidecar-компонентів і записів plugin, що належать каналу, з
|
||||
установленою збіркою OpenClaw, залишаючи повні перебудови завершень команд plugin для
|
||||
явних запусків `openclaw completion --write-state`.
|
||||
|
||||
Коли встановлено локальну керовану службу Gateway і перезапуск увімкнено,
|
||||
оновлення через менеджер пакетів зупиняють запущену службу перед заміною дерева
|
||||
пакета, потім оновлюють метадані служби з оновленого встановлення, перезапускають
|
||||
службу та перевіряють, що перезапущений Gateway повідомляє очікувану версію. З
|
||||
`--no-restart` заміна пакета все одно виконується, але керована служба не
|
||||
зупиняється й не перезапускається, тому запущений Gateway може зберігати старий код, доки ви не перезапустите
|
||||
Коли встановлено локальний керований сервіс Gateway і ввімкнено перезапуск,
|
||||
оновлення через менеджер пакетів зупиняють запущений сервіс перед заміною дерева
|
||||
пакета, потім оновлюють метадані сервісу з оновленого встановлення, перезапускають
|
||||
сервіс і перевіряють, що перезапущений Gateway повідомляє очікувану версію. З
|
||||
`--no-restart` заміна пакета все одно виконується, але керований сервіс не
|
||||
зупиняється і не перезапускається, тож запущений Gateway може зберігати старий код, доки ви не перезапустите
|
||||
його вручну.
|
||||
|
||||
## Потік git checkout
|
||||
|
||||
### Вибір каналу
|
||||
|
||||
- `stable`: checkout найновішого небета-тега, потім build і doctor.
|
||||
- `beta`: віддати перевагу найновішому тегу `-beta`, але повернутися до найновішого stable-тега, коли beta відсутня або старіша.
|
||||
- `stable`: checkout останнього не-beta тегу, потім build і doctor.
|
||||
- `beta`: надати перевагу останньому тегу `-beta`, але повернутися до останнього stable тегу, коли beta відсутня або старіша.
|
||||
- `dev`: checkout `main`, потім fetch і rebase.
|
||||
|
||||
### Кроки оновлення
|
||||
@ -130,14 +135,14 @@ openclaw update status --timeout 10
|
||||
<Step title="Отримати upstream">
|
||||
Лише dev.
|
||||
</Step>
|
||||
<Step title="Передпольотна збірка (лише dev)">
|
||||
Запускає lint і TypeScript build у тимчасовому worktree. Якщо tip не проходить, відступає назад до 10 комітів, щоб знайти найновішу чисту збірку.
|
||||
<Step title="Попередній build (лише dev)">
|
||||
Запускає lint і TypeScript build у тимчасовому worktree. Якщо tip не проходить, відступає до 10 комітів назад, щоб знайти найновіший чистий build.
|
||||
</Step>
|
||||
<Step title="Rebase">
|
||||
Виконує rebase на вибраний коміт (лише dev).
|
||||
</Step>
|
||||
<Step title="Встановити залежності">
|
||||
Використовує менеджер пакетів репозиторію. Для pnpm checkout оновлювач bootstraps `pnpm` на вимогу (спершу через `corepack`, потім через тимчасовий fallback `npm install pnpm@10`) замість запуску `npm run build` усередині pnpm workspace.
|
||||
Використовує менеджер пакетів репозиторію. Для pnpm checkout оновлювач завантажує `pnpm` на вимогу (спочатку через `corepack`, потім тимчасовий fallback `npm install pnpm@10`) замість запуску `npm run build` всередині pnpm workspace.
|
||||
</Step>
|
||||
<Step title="Зібрати Control UI">
|
||||
Збирає gateway і Control UI.
|
||||
@ -151,24 +156,24 @@ openclaw update status --timeout 10
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
Якщо точно закріплене оновлення npm plugin визначає артефакт, цілісність якого відрізняється від збереженого запису встановлення, `openclaw update` перериває оновлення цього артефакту plugin замість його встановлення. Перевстановлюйте або оновлюйте plugin явно лише після перевірки, що ви довіряєте новому артефакту.
|
||||
Якщо точне pinned оновлення npm plugin визначається як артефакт, integrity якого відрізняється від збереженого запису встановлення, `openclaw update` перериває оновлення цього артефакту plugin замість його встановлення. Перевстановлюйте або оновлюйте plugin явно лише після перевірки, що ви довіряєте новому артефакту.
|
||||
</Warning>
|
||||
|
||||
<Note>
|
||||
Збої післяоновлювальної синхронізації plugin позначають результат оновлення як невдалий і зупиняють подальшу роботу з перезапуску. Виправте помилку встановлення або оновлення plugin, потім повторно запустіть `openclaw update`.
|
||||
Збої синхронізації plugin після оновлення роблять результат оновлення невдалим і зупиняють подальший перезапуск. Виправте помилку встановлення або оновлення plugin, а потім повторно запустіть `openclaw update`.
|
||||
|
||||
Коли оновлений Gateway запускається, runtime-залежності ввімкнених bundled plugin готуються перед активацією plugin. Перезапуски, спричинені оновленням, завершують будь-яке активне staging runtime-залежностей перед закриттям Gateway, тому перезапуски service manager не переривають npm install, що виконується.
|
||||
Коли оновлений Gateway запускається, увімкнені bundled plugin runtime-залежності staging виконуються перед активацією plugin. Перезапуски `update.run` через менеджер пакетів обходять звичайне відкладення під час простою після заміни дерева пакета, тому старий процес не може продовжувати lazy-loading видалених фрагментів. Перезапуски service-manager усе ще очікують завершення staging runtime-залежностей перед закриттям Gateway.
|
||||
|
||||
Якщо pnpm bootstrap усе ще не вдається, оновлювач зупиняється рано з помилкою, специфічною для менеджера пакетів, замість спроби `npm run build` усередині checkout.
|
||||
Якщо завантаження pnpm усе ще не вдається, оновлювач зупиняється рано з помилкою, специфічною для менеджера пакетів, замість спроби `npm run build` всередині checkout.
|
||||
</Note>
|
||||
|
||||
## Скорочення `--update`
|
||||
|
||||
`openclaw --update` переписується в `openclaw update` (корисно для shell і launcher scripts).
|
||||
`openclaw --update` переписується на `openclaw update` (корисно для shell і скриптів запуску).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- `openclaw doctor` (пропонує спершу запустити update для git checkout)
|
||||
- `openclaw doctor` (пропонує спершу запустити оновлення для git checkout)
|
||||
- [Канали розробки](/uk/install/development-channels)
|
||||
- [Оновлення](/uk/install/updating)
|
||||
- [Довідник CLI](/uk/cli)
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
---
|
||||
read_when:
|
||||
- Додавання або змінення міграцій doctor
|
||||
- Запровадження несумісних змін конфігурації
|
||||
- Додавання або зміна міграцій doctor
|
||||
- Запровадження несумісних змін у конфігурації
|
||||
sidebarTitle: Doctor
|
||||
summary: 'Команда doctor: перевірки справності, міграції конфігурації та кроки відновлення'
|
||||
summary: 'Команда doctor: перевірки стану, міграції конфігурації та кроки відновлення'
|
||||
title: Діагностика
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T07:53:24Z"
|
||||
generated_at: "2026-05-01T08:51:57Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 928f6854d5721e468e5edc01420fc911652f706ef24e47e8d47461bbe8998214
|
||||
source_hash: eef5715d485609fa60bdb4aa97ee441b053a60519b9dea03b0c8ec09db157474
|
||||
source_path: gateway/doctor.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
`openclaw doctor` — це інструмент ремонту + міграції для OpenClaw. Він виправляє застарілі конфігурацію/стан, перевіряє працездатність і надає придатні до виконання кроки ремонту.
|
||||
`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілі конфігурацію/стан, перевіряє справність і надає дієві кроки для відновлення.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
@ -30,7 +30,7 @@ openclaw doctor
|
||||
openclaw doctor --yes
|
||||
```
|
||||
|
||||
Приймати типові значення без запитів (включно з кроками ремонту перезапуску/сервісу/пісочниці, коли застосовно).
|
||||
Приймати типові значення без запитів (зокрема кроки відновлення перезапуску/сервісу/пісочниці, коли застосовно).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair">
|
||||
@ -38,7 +38,7 @@ openclaw doctor
|
||||
openclaw doctor --repair
|
||||
```
|
||||
|
||||
Застосувати рекомендовані ремонти без запитів (ремонти + перезапуски, де це безпечно).
|
||||
Застосувати рекомендовані відновлення без запитів (відновлення + перезапуски, де це безпечно).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--repair --force">
|
||||
@ -46,7 +46,7 @@ openclaw doctor
|
||||
openclaw doctor --repair --force
|
||||
```
|
||||
|
||||
Також застосувати агресивні ремонти (перезаписує користувацькі конфігурації supervisor).
|
||||
Також застосувати агресивні відновлення (перезаписує користувацькі конфігурації супервізора).
|
||||
|
||||
</Tab>
|
||||
<Tab title="--non-interactive">
|
||||
@ -54,7 +54,7 @@ openclaw doctor
|
||||
openclaw doctor --non-interactive
|
||||
```
|
||||
|
||||
Запускати без запитів і застосовувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/сервісом/пісочницею, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично після виявлення.
|
||||
Запустити без запитів і застосувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/сервісом/пісочницею, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично, коли їх виявлено.
|
||||
|
||||
</Tab>
|
||||
<Tab title="--deep">
|
||||
@ -62,131 +62,131 @@ openclaw doctor
|
||||
openclaw doctor --deep
|
||||
```
|
||||
|
||||
Сканувати системні сервіси на наявність додаткових інсталяцій gateway (launchd/systemd/schtasks).
|
||||
Сканувати системні сервіси на наявність додаткових установлень Gateway (launchd/systemd/schtasks).
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Якщо ви хочете переглянути зміни перед записом, спершу відкрийте файл конфігурації:
|
||||
Якщо ви хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації:
|
||||
|
||||
```bash
|
||||
cat ~/.openclaw/openclaw.json
|
||||
```
|
||||
|
||||
## Що він робить (зведення)
|
||||
## Що він робить (коротко)
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Стан, інтерфейс і оновлення">
|
||||
- Необов’язкове попереднє оновлення для git-інсталяцій (лише інтерактивно).
|
||||
- Перевірка актуальності протоколу інтерфейсу (перебудовує Control UI, коли схема протоколу новіша).
|
||||
- Перевірка працездатності + запит на перезапуск.
|
||||
<Accordion title="Справність, UI та оновлення">
|
||||
- Необов’язкове попереднє оновлення для git-установлень (лише інтерактивно).
|
||||
- Перевірка актуальності протоколу UI (перезбирає Control UI, коли схема протоколу новіша).
|
||||
- Перевірка справності + запит на перезапуск.
|
||||
- Зведення стану Skills (придатні/відсутні/заблоковані) і стан Plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Конфігурація та міграції">
|
||||
- Нормалізація конфігурації для застарілих значень.
|
||||
- Міграція конфігурації Talk із застарілих пласких полів `talk.*` у `talk.provider` + `talk.providers.<provider>`.
|
||||
- Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.<provider>`.
|
||||
- Перевірки міграції браузера для застарілих конфігурацій розширення 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.
|
||||
- Міграція застарілого стану на диску (sessions/agent dir/WhatsApp auth).
|
||||
- Перевірка передумов OAuth TLS для OAuth-профілів OpenAI Codex.
|
||||
- Попередження про allowlist Plugin/інструментів, коли `plugins.allow` є обмежувальним, але політика інструментів усе ще запитує wildcard або інструменти, що належать Plugin.
|
||||
- Міграція застарілого стану на диску (сесії/каталог агента/автентифікація WhatsApp).
|
||||
- Міграція застарілих ключів контракту маніфесту Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
|
||||
- Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, payload `provider`, прості fallback-завдання webhook `notify: true`).
|
||||
- Міграція застарілої runtime-policy агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`.
|
||||
- Очищення застарілої конфігурації Plugin, коли plugins увімкнені; коли `plugins.enabled=false`, застарілі посилання Plugin вважаються інертною containment-конфігурацією та зберігаються.
|
||||
- Міграція застарілого сховища Cron (`jobId`, `schedule.cron`, поля доставки/payload верхнього рівня, payload `provider`, прості fallback-завдання Webhook `notify: true`).
|
||||
- Міграція застарілої runtime-політики агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`.
|
||||
- Очищення застарілої конфігурації Plugin, коли plugins увімкнено; коли `plugins.enabled=false`, застарілі посилання на Plugin вважаються інертною конфігурацією ізоляції та зберігаються.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Стан і цілісність">
|
||||
- Перевірка файлів блокування сесій і очищення застарілих блокувань.
|
||||
- Ремонт транскриптів сесій для дубльованих гілок prompt-rewrite, створених ураженими збірками 2026.4.24.
|
||||
- Виявлення tombstone для restart-recovery завислих субагентів, з підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб під час запуску дочірній елемент не продовжував вважатися restart-aborted.
|
||||
- Перевірки цілісності стану та дозволів (sessions, transcripts, state dir).
|
||||
- Перевірка lock-файлів сесій і очищення застарілих lock-файлів.
|
||||
- Відновлення транскрипту сесії для дубльованих гілок переписування prompt, створених ураженими збірками 2026.4.24.
|
||||
- Виявлення tombstone для відновлення після перезапуску завислого субагента з підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб запуск не продовжував вважати дочірній процес перерваним через перезапуск.
|
||||
- Перевірки цілісності стану та дозволів (сесії, транскрипти, каталог стану).
|
||||
- Перевірки дозволів файлу конфігурації (chmod 600) під час локального запуску.
|
||||
- Стан автентифікації моделі: перевіряє завершення терміну дії OAuth, може оновлювати токени, термін дії яких спливає, і повідомляє про стани cooldown/disabled auth-profile.
|
||||
- Виявлення додаткового каталогу workspace (`~/openclaw`).
|
||||
- Справність автентифікації моделі: перевіряє завершення строку дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled для auth-profile.
|
||||
- Виявлення додаткового каталогу робочого простору (`~/openclaw`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Gateway, сервіси та supervisors">
|
||||
- Ремонт образу пісочниці, коли sandboxing увімкнено.
|
||||
- Міграція застарілого сервісу та виявлення додаткового gateway.
|
||||
<Accordion title="Gateway, служби та супервізори">
|
||||
- Відновлення образу пісочниці, коли пісочницю ввімкнено.
|
||||
- Міграція застарілих служб і виявлення додаткового gateway.
|
||||
- Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`).
|
||||
- Runtime-перевірки Gateway (сервіс інстальовано, але він не запущений; кешована мітка launchd).
|
||||
- Попередження про стан каналу (перевіряються з запущеного gateway).
|
||||
- Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим ремонтом.
|
||||
- Очищення середовища вбудованого проксі для сервісів gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час інсталяції або оновлення.
|
||||
- Перевірки найкращих практик runtime Gateway (Node проти Bun, шляхи version-manager).
|
||||
- Діагностика конфлікту портів gateway (типовий `18789`).
|
||||
- Перевірки runtime Gateway (службу встановлено, але вона не працює; кешована мітка launchd).
|
||||
- Попередження про статус каналу (перевіряються із запущеного gateway).
|
||||
- Аудит конфігурації супервізора (launchd/systemd/schtasks) з необов’язковим відновленням.
|
||||
- Очищення середовища вбудованого проксі для служб gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення.
|
||||
- Перевірки найкращих практик runtime Gateway (Node проти Bun, шляхи менеджера версій).
|
||||
- Діагностика конфліктів порту Gateway (типово `18789`).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Автентифікація, безпека та pairing">
|
||||
- Попередження безпеки для відкритих DM-політик.
|
||||
- Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли джерела токена немає; не перезаписує конфігурації SecretRef токена).
|
||||
- Виявлення проблем із pairing пристрою (очікувані перші запити pairing, очікувані підвищення ролі/області, застарілий дрейф кешу локального device-token і дрейф автентифікації paired-record).
|
||||
<Accordion title="Автентифікація, безпека та сполучення">
|
||||
- Попередження безпеки для відкритих політик DM.
|
||||
- Перевірки автентифікації Gateway для режиму локального токена (пропонує створення токена, коли немає джерела токена; не перезаписує конфігурації SecretRef токена).
|
||||
- Виявлення проблем зі сполученням пристроїв (очікувані первинні запити на сполучення, очікувані підвищення ролі/області дії, розходження застарілого кешу локального токена пристрою та розходження автентифікації запису сполучення).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Workspace і shell">
|
||||
<Accordion title="Робоча область і shell">
|
||||
- Перевірка systemd linger у Linux.
|
||||
- Перевірка розміру файлу bootstrap workspace (попередження про обрізання/наближення до ліміту для контекстних файлів).
|
||||
- Перевірка стану shell completion і автоматична інсталяція/оновлення.
|
||||
- Перевірка готовності провайдера embedding для пошуку пам’яті (локальна модель, ключ віддаленого API або бінарний файл QMD).
|
||||
- Перевірки source-інсталяції (невідповідність pnpm workspace, відсутні UI assets, відсутній бінарний файл tsx).
|
||||
- Записує оновлену конфігурацію + метадані wizard.
|
||||
- Перевірка розміру bootstrap-файлу робочої області (попередження про обрізання/наближення до ліміту для контекстних файлів).
|
||||
- Перевірка стану автодоповнення shell та автоматичне встановлення/оновлення.
|
||||
- Перевірка готовності провайдера embedding для пошуку пам’яті (локальна модель, ключ віддаленого API або двійковий файл QMD).
|
||||
- Перевірки встановлення з вихідного коду (невідповідність workspace pnpm, відсутні ресурси UI, відсутній двійковий файл tsx).
|
||||
- Записує оновлену конфігурацію та метадані майстра.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Зворотне заповнення та скидання в інтерфейсі Dreams
|
||||
## Зворотне заповнення та скидання UI Dreams
|
||||
|
||||
Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для робочого процесу 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 у `DREAMS.md`.
|
||||
- **Reset** видаляє лише ці позначені backfill diary entries з `DREAMS.md`.
|
||||
- **Clear Grounded** видаляє лише staged grounded-only short-term entries, які походять з історичного replay і ще не накопичили live recall або daily support.
|
||||
- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активній робочій області, запускає grounded REM diary pass і записує оборотні записи зворотного заповнення в `DREAMS.md`.
|
||||
- **Reset** видаляє з `DREAMS.md` лише ці позначені записи щоденника зворотного заповнення.
|
||||
- **Clear Grounded** видаляє лише підготовлені короткострокові записи лише grounded, які походять з історичного відтворення і ще не накопичили live recall або daily support.
|
||||
|
||||
Що вони **не** роблять самі по собі:
|
||||
Чого вони **не** роблять самі по собі:
|
||||
|
||||
- вони не редагують `MEMORY.md`
|
||||
- вони не запускають повні міграції doctor
|
||||
- вони не виконують автоматичний stage grounded candidates у live short-term promotion store, якщо ви явно спершу не запустите staged CLI path
|
||||
- вони не додають автоматично grounded-кандидатів до live-сховища короткострокового просування, якщо ви явно спершу не запустите підготовлений шлях CLI
|
||||
|
||||
Якщо ви хочете, щоб grounded historical replay впливав на звичайну deep promotion lane, натомість використовуйте CLI flow:
|
||||
Якщо ви хочете, щоб grounded historical replay вплинув на звичайну смугу deep promotion, натомість використовуйте потік CLI:
|
||||
|
||||
```bash
|
||||
openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
```
|
||||
|
||||
Це виконує stage grounded durable candidates у short-term dreaming store, водночас залишаючи `DREAMS.md` як review surface.
|
||||
Це додає grounded durable candidates у short-term dreaming store, залишаючи `DREAMS.md` поверхнею для перегляду.
|
||||
|
||||
## Детальна поведінка та обґрунтування
|
||||
## Докладна поведінка й обґрунтування
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="0. Необов’язкове оновлення (git-інсталяції)">
|
||||
<Accordion title="0. Необов’язкове оновлення (встановлення з git)">
|
||||
Якщо це git checkout і doctor запускається інтерактивно, він пропонує оновитися (fetch/rebase/build) перед запуском doctor.
|
||||
</Accordion>
|
||||
<Accordion title="1. Нормалізація конфігурації">
|
||||
Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без channel-specific override), doctor нормалізує їх до поточної схеми.
|
||||
Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми.
|
||||
|
||||
Це включає застарілі пласкі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.<provider>`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у map провайдерів.
|
||||
Це включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.<provider>`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдерів.
|
||||
|
||||
Doctor також попереджає, коли `plugins.allow` непорожній, а політика інструментів використовує
|
||||
wildcard або записи інструментів, що належать Plugin. `tools.allow: ["*"]` збігається лише з інструментами
|
||||
з plugins, які фактично завантажуються; він не обходить ексклюзивний allowlist Plugin.
|
||||
Doctor також попереджає, коли `plugins.allow` не порожній, а політика інструментів використовує
|
||||
wildcard або записи інструментів, що належать Plugin. `tools.allow: ["*"]` відповідає лише інструментам
|
||||
із plugins, які фактично завантажуються; він не обходить ексклюзивний список дозволених plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2. Міграції застарілих ключів конфігурації">
|
||||
Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися та просять вас виконати `openclaw doctor`.
|
||||
Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися і просять вас запустити `openclaw doctor`.
|
||||
|
||||
Doctor:
|
||||
|
||||
- Пояснить, які застарілі ключі знайдено.
|
||||
- Покаже міграцію, яку застосував.
|
||||
- Пояснить, які застарілі ключі було знайдено.
|
||||
- Покаже застосовану міграцію.
|
||||
- Перепише `~/.openclaw/openclaw.json` з оновленою схемою.
|
||||
|
||||
Gateway також автоматично запускає міграції doctor під час запуску, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації ремонтуються без ручного втручання. Міграції сховища Cron jobs обробляються через `openclaw doctor --fix`.
|
||||
Gateway також автоматично запускає міграції doctor під час запуску, коли виявляє застарілий формат конфігурації, тому застарілі конфігурації відновлюються без ручного втручання. Міграції сховища Cron jobs обробляються командою `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.<provider>`
|
||||
- `routing.agentToAgent` → `tools.agentToAgent`
|
||||
@ -211,247 +211,247 @@ 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.<id>.timeoutSeconds` для таймаутів повільних провайдерів/моделей
|
||||
- видаліть `agents.defaults.llm`; використовуйте `models.providers.<id>.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, замість аварійного закриття)
|
||||
- застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (запуск gateway також пропускає провайдерів, у яких `api` задано як майбутнє або невідоме значення enum, замість того щоб аварійно завершуватися)
|
||||
|
||||
Попередження doctor також містять настанови щодо типового облікового запису для каналів із кількома обліковими записами:
|
||||
Попередження doctor також містять поради щодо типового облікового запису для багатооблікових каналів:
|
||||
|
||||
- Якщо налаштовано два або більше записів `channels.<channel>.accounts` без `channels.<channel>.defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис.
|
||||
- Якщо `channels.<channel>.defaultAccount` встановлено на невідомий ID облікового запису, doctor попереджає і перелічує налаштовані ID облікових записів.
|
||||
- Якщо `channels.<channel>.defaultAccount` задано як невідомий ID облікового запису, doctor попереджає про це й перелічує налаштовані ID облікових записів.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2b. OpenCode provider overrides">
|
||||
Якщо ви вручну додали `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 + витрати для кожної моделі.
|
||||
</Accordion>
|
||||
<Accordion title="2c. Browser migration and Chrome MCP readiness">
|
||||
Якщо ваша конфігурація браузера досі вказує на видалений шлях extension Chrome, doctor нормалізує її до поточної моделі host-local підключення Chrome MCP:
|
||||
Якщо ваша конфігурація браузера досі вказує на видалений шлях Chrome extension, doctor нормалізує її до поточної моделі під’єднання Chrome MCP на локальному хості:
|
||||
|
||||
- `browser.profiles.*.driver: "extension"` стає `"existing-session"`
|
||||
- `browser.relayBindHost` видаляється
|
||||
|
||||
Doctor також перевіряє шлях host-local Chrome MCP, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`:
|
||||
Doctor також перевіряє шлях Chrome MCP на локальному хості, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`:
|
||||
|
||||
- перевіряє, чи Google Chrome встановлено на тому самому хості для профілів типового автоматичного підключення
|
||||
- перевіряє, чи встановлено Google Chrome на тому самому хості для типових профілів автоматичного під’єднання
|
||||
- перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144
|
||||
- нагадує ввімкнути віддалене налагодження на сторінці інспектування браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`)
|
||||
- нагадує ввімкнути віддалене налагодження на сторінці інспектування браузера (наприклад `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`)
|
||||
|
||||
Doctor не може ввімкнути налаштування на боці Chrome замість вас. Host-local Chrome MCP все ще потребує:
|
||||
Doctor не може ввімкнути налаштування на боці Chrome за вас. Chrome MCP на локальному хості все ще потребує:
|
||||
|
||||
- браузера на основі Chromium 144+ на хості gateway/node
|
||||
- локально запущеного браузера
|
||||
- увімкненого віддаленого налагодження в цьому браузері
|
||||
- схвалення першого запиту згоди на підключення в браузері
|
||||
- браузер на базі Chromium 144+ на хості gateway/node
|
||||
- браузер, запущений локально
|
||||
- віддалене налагодження, увімкнене в цьому браузері
|
||||
- підтвердження першого запиту згоди на під’єднання в браузері
|
||||
|
||||
Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути на кшталт `responsebody`, експорту PDF, перехоплення завантажень і пакетних дій усе ще потребують керованого браузера або raw CDP profile.
|
||||
Готовність тут стосується лише передумов локального під’єднання. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого браузера або профілю raw CDP.
|
||||
|
||||
Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless потоків. Вони й надалі використовують raw CDP.
|
||||
Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують raw CDP.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="2d. OAuth TLS prerequisites">
|
||||
Коли налаштовано профіль 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 Codex OAuth, doctor перевіряє кінцеву точку авторизації OpenAI, щоб упевнитися, що локальний стек Node/OpenSSL TLS може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor друкує поради з виправлення для конкретної платформи. На macOS із Homebrew Node виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть тоді, коли gateway справний.
|
||||
</Accordion>
|
||||
<Accordion title="2e. Codex OAuth provider overrides">
|
||||
Якщо раніше ви додали застарілі транспортні налаштування в `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі транспортні налаштування разом із Codex OAuth, щоб ви могли видалити або переписати застаріле транспортне перевизначення й повернути вбудовану маршрутизацію/резервну поведінку. Власні проксі та перевизначення лише заголовків досі підтримуються й не викликають це попередження.
|
||||
Якщо раніше ви додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі транспортні налаштування разом із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану поведінку маршрутизації/резервування. Власні проксі й перевизначення лише заголовків усе ще підтримуються та не спричиняють цього попередження.
|
||||
</Accordion>
|
||||
<Accordion title="2f. Codex plugin route warnings">
|
||||
Коли ввімкнено bundled Codex plugin, doctor також перевіряє, чи refs основної моделі `openai-codex/*` досі резолвляться через типовий PI runner. Така комбінація коректна, коли вам потрібна автентифікація Codex OAuth/subscription через PI, але її легко сплутати з нативним harness app-server Codex. Doctor попереджає й указує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`.
|
||||
Коли ввімкнено bundled Codex plugin, doctor також перевіряє, чи посилання первинних моделей `openai-codex/*` досі розв’язуються через типовий PI runner. Така комбінація коректна, коли вам потрібна автентифікація Codex OAuth/підписки через PI, але її легко сплутати з нативним harness сервера застосунку Codex. Doctor попереджає й указує на явну форму сервера застосунку: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`.
|
||||
|
||||
Doctor не виправляє це автоматично, оскільки обидва маршрути коректні:
|
||||
Doctor не виправляє це автоматично, бо обидва маршрути коректні:
|
||||
|
||||
- `openai-codex/*` + PI означає "використовувати автентифікацію Codex OAuth/subscription через звичайний runner OpenClaw."
|
||||
- `openai/*` + `runtime: "codex"` означає "запустити вбудований turn через нативний app-server Codex."
|
||||
- `/codex ...` означає "керувати або прив’язати нативну розмову Codex із чату."
|
||||
- `/acp ...` або `runtime: "acp"` означає "використовувати зовнішній адаптер ACP/acpx."
|
||||
- `openai-codex/*` + PI означає «використовувати автентифікацію Codex OAuth/підписки через звичайний runner OpenClaw».
|
||||
- `openai/*` + `runtime: "codex"` означає «запустити вбудований turn через нативний сервер застосунку Codex».
|
||||
- `/codex ...` означає «керувати або прив’язати нативну розмову Codex із чату».
|
||||
- `/acp ...` або `runtime: "acp"` означає «використовувати зовнішній адаптер ACP/acpx».
|
||||
|
||||
Якщо з’являється попередження, виберіть задуманий маршрут і відредагуйте конфігурацію вручну. Залишайте попередження як є, коли PI Codex OAuth є навмисним.
|
||||
Якщо з’являється попередження, виберіть задуманий маршрут і відредагуйте конфігурацію вручну. Залиште попередження як є, коли PI Codex OAuth є навмисним.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3. Legacy state migrations (disk layout)">
|
||||
Doctor може мігрувати старіші дискові макети до поточної структури:
|
||||
Doctor може мігрувати старіші дискові макети в поточну структуру:
|
||||
|
||||
- Сховище sessions + transcripts:
|
||||
- Сховище сесій + транскрипти:
|
||||
- з `~/.openclaw/sessions/` до `~/.openclaw/agents/<agentId>/sessions/`
|
||||
- Каталог agent:
|
||||
- Каталог агента:
|
||||
- з `~/.openclaw/agent/` до `~/.openclaw/agents/<agentId>/agent/`
|
||||
- Стан автентифікації WhatsApp (Baileys):
|
||||
- із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`)
|
||||
- до `~/.openclaw/credentials/whatsapp/<accountId>/...` (типовий ID облікового запису: `default`)
|
||||
|
||||
Ці міграції виконуються за принципом best-effort і є ідемпотентними; doctor видаватиме попередження, коли залишатиме будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі sessions + каталог agent під час запуску, щоб history/auth/models потрапляли в шлях per-agent без ручного запуску doctor. Автентифікацію WhatsApp навмисно мігрують лише через `openclaw doctor`. Нормалізація provider/provider-map для Talk тепер порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не запускають повторні no-op зміни `doctor --fix`.
|
||||
Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor видасть попередження, коли залишить будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сесії + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапили в шлях для окремого агента без ручного запуску doctor. Нормалізація провайдера talk/мапи провайдерів тепер порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не запускають повторні no-op зміни `doctor --fix`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3a. Legacy plugin manifest migrations">
|
||||
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` уже має ті самі значення, застарілий ключ видаляється без дублювання даних.
|
||||
</Accordion>
|
||||
<Accordion title="3b. Legacy cron store migrations">
|
||||
Doctor також перевіряє сховище завдань cron (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, коли перевизначено) на старі форми завдань, які планувальник досі приймає для сумісності.
|
||||
Doctor також перевіряє сховище завдань cron (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, якщо перевизначено) на старі форми завдань, які планувальник усе ще приймає для сумісності.
|
||||
|
||||
Поточні очищення cron включають:
|
||||
|
||||
- `jobId` → `id`
|
||||
- `schedule.cron` → `schedule.expr`
|
||||
- поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- aliases delivery для payload `provider` → явний `delivery.channel`
|
||||
- прості застарілі webhook fallback завдання `notify: true` → явне `delivery.mode="webhook"` з `delivery.to=cron.webhook`
|
||||
- верхньорівневі поля payload (`message`, `model`, `thinking`, ...) → `payload`
|
||||
- верхньорівневі поля доставки (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
|
||||
- псевдоніми доставки `provider` у payload → явний `delivery.channel`
|
||||
- прості застарілі fallback-завдання webhook з `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook`
|
||||
|
||||
Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий notify fallback з наявним режимом delivery, що не є webhook, doctor попереджає й залишає це завдання для ручної перевірки.
|
||||
Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий fallback notify з наявним режимом доставки, що не є webhook, doctor попереджає й залишає це завдання для ручної перевірки.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="3c. Session lock cleanup">
|
||||
Doctor сканує кожен каталог session agent на застарілі файли write-lock — файли, що залишилися після аварійного завершення session. Для кожного знайденого lock file він повідомляє: шлях, PID, чи PID досі живий, вік lock і чи він вважається застарілим (мертвий PID або старший за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі lock files; інакше виводить примітку й інструктує повторно запустити з `--fix`.
|
||||
Doctor сканує кожен каталог сесій агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сесії. Для кожного знайденого файла блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше друкує примітку й інструктує повторно запустити з `--fix`.
|
||||
</Accordion>
|
||||
<Accordion title="3d. Session transcript branch repair">
|
||||
Doctor сканує файли JSONL agent session на дубльовану форму branch, створену помилкою переписування prompt transcript від 2026.4.24: покинутий user turn із внутрішнім runtime context OpenClaw плюс активний sibling, що містить той самий видимий user prompt. У режимі `--fix` / `--repair` doctor створює резервну копію кожного зачепленого файлу поруч з оригіналом і переписує transcript на активний branch, щоб gateway history і memory readers більше не бачили дубльованих turns.
|
||||
Doctor сканує JSONL-файли сесій агента на дубльовану форму гілки, створену помилкою переписування транскрипту prompt від 2026.4.24: покинутий користувацький turn із внутрішнім runtime-контекстом OpenClaw плюс активний sibling, що містить той самий видимий користувацький prompt. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файла поруч з оригіналом і переписує транскрипт до активної гілки, щоб читачі історії gateway і memory більше не бачили дубльованих turns.
|
||||
</Accordion>
|
||||
<Accordion title="4. State integrity checks (session persistence, routing, and safety)">
|
||||
Каталог state — це operational brainstem. Якщо він зникне, ви втратите sessions, credentials, logs і config (якщо у вас немає резервних копій деінде).
|
||||
Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите сесії, облікові дані, журнали й конфігурацію (якщо не маєте резервних копій в іншому місці).
|
||||
|
||||
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`.
|
||||
- **Невідповідність transcript**: попереджає, коли в нещодавніх записах сесій відсутні файли transcript.
|
||||
- **Основна сесія "1-line JSONL"**: позначає випадки, коли основний transcript має лише один рядок (історія не накопичується).
|
||||
- **Кілька каталогів стану**: попереджає, коли існує кілька папок `~/.openclaw` у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділятися між інсталяціями).
|
||||
- **Нагадування про remote-режим**: якщо `gateway.mode=remote`, doctor нагадує запустити його на remote-хості (стан зберігається там).
|
||||
- **Дозволи конфігураційного файла**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/усім, і пропонує посилити дозволи до `600`.
|
||||
- **Синхронізований із хмарою каталог стану macOS**: попереджає, коли стан розташовано в iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи з синхронізацією можуть спричиняти повільніше I/O та перегони блокувань/синхронізації.
|
||||
- **Каталог стану на SD або eMMC у Linux**: попереджає, коли стан розташовано на джерелі монтування `mmcblk*`, оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів і облікових даних.
|
||||
- **Каталоги сеансів відсутні**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення аварій `ENOENT`.
|
||||
- **Невідповідність транскрипту**: попереджає, коли в нещодавніх записах сеансів бракує файлів транскриптів.
|
||||
- **Головний сеанс "1-line JSONL"**: позначає ситуацію, коли головний транскрипт має лише один рядок (історія не накопичується).
|
||||
- **Кілька каталогів стану**: попереджає, коли кілька папок `~/.openclaw` існують у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може розділитися між інсталяціями).
|
||||
- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити його на віддаленому хості (стан зберігається там).
|
||||
- **Дозволи файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/усім, і пропонує звузити дозволи до `600`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="5. Стан автентифікації моделі (закінчення OAuth)">
|
||||
Doctor перевіряє OAuth-профілі у сховищі автентифікації, попереджає, коли термін дії токенів добігає кінця або вже минув, і може безпечно їх оновити. Якщо OAuth/токен-профіль Anthropic застарів, він пропонує API-ключ Anthropic або шлях із setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення.
|
||||
<Accordion title="5. Справність автентифікації моделей (закінчення строку OAuth)">
|
||||
Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли токени скоро закінчаться або вже закінчилися, і може безпечно їх оновити. Якщо профіль OAuth/токена Anthropic застарів, він пропонує API-ключ Anthropic або шлях setup-token Anthropic. Запити на оновлення з'являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення.
|
||||
|
||||
Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`, `invalid_grant` або provider повідомляє, що потрібно знову ввійти), doctor повідомляє, що потрібна повторна автентифікація, і друкує точну команду `openclaw models auth login --provider ...`, яку слід виконати.
|
||||
Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`, `invalid_grant` або provider повідомляє, що потрібно ввійти знову), doctor повідомляє, що потрібна повторна автентифікація, і друкує точну команду `openclaw models auth login --provider ...`, яку треба виконати.
|
||||
|
||||
Doctor також повідомляє про auth-профілі, які тимчасово непридатні через:
|
||||
Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні через:
|
||||
|
||||
- короткі періоди очікування (обмеження частоти/тайм-аути/збої автентифікації)
|
||||
- довші вимкнення (збої білінгу/кредитів)
|
||||
- короткі періоди очікування (ліміти швидкості/тайм-аути/помилки автентифікації)
|
||||
- довші вимкнення (помилки білінгу/кредитів)
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="6. Перевірка моделі hooks">
|
||||
Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, коли воно не розв’язується або заборонене.
|
||||
<Accordion title="6. Перевірка моделей хуків">
|
||||
Якщо задано `hooks.gmail.model`, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, коли його неможливо розв'язати або воно заборонене.
|
||||
</Accordion>
|
||||
<Accordion title="7. Відновлення sandbox image">
|
||||
Коли sandboxing увімкнено, doctor перевіряє Docker images і пропонує зібрати або перемкнутися на legacy names, якщо поточний image відсутній.
|
||||
<Accordion title="7. Відновлення образу sandbox">
|
||||
Коли sandbox увімкнено, doctor перевіряє образи Docker і пропонує зібрати або перемкнутися на застарілі назви, якщо поточного образу бракує.
|
||||
</Accordion>
|
||||
<Accordion title="7b. Runtime-залежності bundled plugin">
|
||||
Doctor перевіряє runtime-залежності лише для bundled plugins, які активні в поточній конфігурації або ввімкнені за замовчуванням у своєму bundled manifest, наприклад `plugins.entries.discord.enabled: true`, legacy `channels.discord.enabled: true`, налаштовані `models.providers.*` / посилання на моделі агентів або bundled plugin, увімкнений за замовчуванням без provider ownership. Якщо якісь відсутні, doctor повідомляє пакети й інсталює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. External plugins і далі використовують `openclaw plugins install` / `openclaw plugins update`; doctor не інсталює залежності для довільних шляхів plugin.
|
||||
<Accordion title="7b. Runtime-залежності вбудованих plugin">
|
||||
Doctor перевіряє runtime-залежності лише для вбудованих plugins, активних у поточній конфігурації або ввімкнених за типовим значенням їхнього вбудованого маніфесту, наприклад `plugins.entries.discord.enabled: true`, застаріле `channels.discord.enabled: true`, налаштовані `models.providers.*` / посилання на моделі агентів або типово ввімкнений вбудований plugin без власника provider. Якщо чогось бракує, doctor повідомляє пакети й установлює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні plugins і далі використовують `openclaw plugins install` / `openclaw plugins update`; doctor не встановлює залежності для довільних шляхів plugin.
|
||||
|
||||
Під час відновлення doctor, npm-інсталяції bundled runtime-dependency повідомляють про поступ через spinner у TTY-сесіях і періодичні рядки поступу в piped/headless виводі. Gateway і local CLI також можуть за потреби відновлювати runtime-залежності активних bundled plugin перед імпортом bundled plugin. Ці інсталяції обмежені коренем runtime-інсталяції plugin, запускаються з вимкненими scripts, не записують package lock і захищені install-root lock, щоб одночасні запуски CLI або Gateway не змінювали одне й те саме дерево `node_modules` одночасно. Застарілі legacy locks від убитих запусків Docker/container повертаються, коли metadata їхнього власника не може підтвердити поточне втілення процесу, а lock-файли старі.
|
||||
Під час відновлення doctor встановлення npm для вбудованих runtime-залежностей показують прогрес spinner у сеансах TTY і періодичний рядковий прогрес у piped/headless-виводі. Запуск Gateway і перезавантаження конфігурації входять у режим плану plugin перед імпортом runtime-модулів вбудованого plugin; звичайні runtime-імпорти виконують лише перевірку й не запускають відновлення через менеджер пакетів. Ці встановлення обмежені коренем встановлення runtime plugin, запускаються з вимкненими scripts, не записують package lock і захищені блокуванням кореня встановлення, щоб паралельні запуски CLI або Gateway не змінювали одне й те саме дерево `node_modules` одночасно. Застарілі legacy-блокування від убитих запусків Docker/container повертаються, коли їхні метадані власника не можуть підтвердити поточне втілення процесу, а файли блокування старі.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8. Міграції сервісу Gateway і підказки з очищення">
|
||||
Doctor виявляє legacy gateway services (launchd/systemd/schtasks) і пропонує видалити їх та встановити сервіс OpenClaw, використовуючи поточний порт gateway. Він також може сканувати додаткові gateway-like services і друкувати підказки з очищення. Gateway-сервіси OpenClaw з іменами профілів вважаються першокласними та не позначаються як "extra."
|
||||
<Accordion title="8. Міграції служби Gateway і підказки з очищення">
|
||||
Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw із поточним портом gateway. Він також може сканувати додаткові gateway-подібні служби й друкувати підказки з очищення. Служби gateway OpenClaw з іменами профілів вважаються повноцінними й не позначаються як "зайві."
|
||||
|
||||
У Linux, якщо user-level gateway service відсутній, але існує system-level OpenClaw gateway service, doctor не встановлює другий user-level service автоматично. Перевірте через `openclaw gateway status --deep` або `openclaw doctor --deep`, потім видаліть дублікат або встановіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний supervisor керує життєвим циклом gateway.
|
||||
У Linux, якщо служба gateway рівня користувача відсутня, але існує служба gateway OpenClaw системного рівня, doctor не встановлює автоматично другу службу рівня користувача. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, потім видаліть дублікат або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний supervisor керує життєвим циклом gateway.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="8b. Міграція Startup Matrix">
|
||||
Коли обліковий запис каналу Matrix має pending або actionable legacy state migration, doctor (у режимі `--fix` / `--repair`) створює pre-migration snapshot, а потім виконує best-effort кроки міграції: legacy Matrix state migration і legacy encrypted-state preparation. Обидва кроки non-fatal; помилки логуються, а запуск продовжується. У режимі read-only (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається.
|
||||
Коли обліковий запис каналу Matrix має pending або actionable міграцію legacy-стану, doctor (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім виконує best-effort кроки міграції: міграцію legacy-стану Matrix і підготовку legacy encrypted-state. Обидва кроки не є фатальними; помилки журналюються, а запуск продовжується. У режимі лише для читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається.
|
||||
</Accordion>
|
||||
<Accordion title="8c. Спряження пристроїв і drift автентифікації">
|
||||
Doctor тепер перевіряє стан device-pairing як частину звичайного health pass.
|
||||
<Accordion title="8c. Сполучення пристроїв і drift автентифікації">
|
||||
Doctor тепер перевіряє стан сполучення пристроїв як частину звичайної перевірки справності.
|
||||
|
||||
Що він повідомляє:
|
||||
|
||||
- pending first-time pairing requests
|
||||
- pending role upgrades для вже спряжених пристроїв
|
||||
- pending scope upgrades для вже спряжених пристроїв
|
||||
- виправлення public-key mismatch, коли device id усе ще збігається, але ідентичність пристрою більше не збігається із затвердженим записом
|
||||
- paired records без active token для approved role
|
||||
- paired tokens, чиї scopes відхилилися від approved pairing baseline
|
||||
- локальні кешовані device-token записи для поточної машини, що передують gateway-side token rotation або містять stale scope metadata
|
||||
- pending запити першого сполучення
|
||||
- pending підвищення ролі для вже сполучених пристроїв
|
||||
- pending розширення scope для вже сполучених пристроїв
|
||||
- виправлення невідповідності публічного ключа, коли id пристрою досі збігається, але ідентичність пристрою більше не збігається із затвердженим записом
|
||||
- сполучені записи без активного токена для затвердженої ролі
|
||||
- сполучені токени, scopes яких відхилилися від затвердженої базової лінії сполучення
|
||||
- локальні кешовані записи device-token для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані scope
|
||||
|
||||
Doctor не auto-approve pair requests і не auto-rotate device tokens. Натомість він друкує точні наступні кроки:
|
||||
Doctor не затверджує автоматично запити сполучення й не обертає автоматично токени пристроїв. Натомість він друкує точні наступні кроки:
|
||||
|
||||
- переглянути pending requests через `openclaw devices list`
|
||||
- затвердити точний request через `openclaw devices approve <requestId>`
|
||||
- ротувати свіжий token через `openclaw devices rotate --device <deviceId> --role <role>`
|
||||
- видалити й повторно затвердити stale record через `openclaw devices remove <deviceId>`
|
||||
- перегляньте pending запити за допомогою `openclaw devices list`
|
||||
- затвердьте точний запит за допомогою `openclaw devices approve <requestId>`
|
||||
- оберніть свіжий токен за допомогою `openclaw devices rotate --device <deviceId> --role <role>`
|
||||
- видаліть і повторно затвердьте застарілий запис за допомогою `openclaw devices remove <deviceId>`
|
||||
|
||||
Це закриває поширену прогалину "already paired but still getting pairing required": doctor тепер відрізняє first-time pairing від pending role/scope upgrades і від stale token/device-identity drift.
|
||||
Це закриває поширену прогалину "уже сполучено, але все ще потрібне сполучення": doctor тепер відрізняє перше сполучення від pending підвищень ролі/scope і від застарілого drift токена/ідентичності пристрою.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="9. Попередження безпеки">
|
||||
Doctor виводить попередження, коли provider відкритий для DM без allowlist або коли policy налаштовано небезпечно.
|
||||
Doctor виводить попередження, коли provider відкритий для DM без allowlist або коли policy налаштовано небезпечним способом.
|
||||
</Accordion>
|
||||
<Accordion title="10. systemd linger (Linux)">
|
||||
Якщо запуск відбувається як systemd user service, doctor гарантує, що lingering увімкнено, щоб gateway залишався активним після виходу з системи.
|
||||
Якщо запуск відбувається як користувацька служба systemd, doctor переконується, що lingering увімкнено, щоб gateway залишався активним після виходу з системи.
|
||||
</Accordion>
|
||||
<Accordion title="11. Стан workspace (skills, plugins і legacy dirs)">
|
||||
Doctor друкує підсумок стану workspace для default agent:
|
||||
<Accordion title="11. Стан workspace (skills, plugins і legacy-каталоги)">
|
||||
Doctor друкує зведення стану workspace для типового агента:
|
||||
|
||||
- **Стан Skills**: підраховує eligible, missing-requirements і allowlist-blocked skills.
|
||||
- **Legacy workspace dirs**: попереджає, коли `~/openclaw` або інші legacy workspace directories існують поруч із поточним workspace.
|
||||
- **Стан Plugin**: підраховує enabled/disabled/errored plugins; перелічує plugin IDs для всіх помилок; повідомляє bundle plugin capabilities.
|
||||
- **Попередження сумісності Plugin**: позначає plugins, які мають проблеми сумісності з поточним runtime.
|
||||
- **Діагностика Plugin**: показує всі load-time warnings або errors, виведені plugin registry.
|
||||
- **Стан Skills**: підраховує придатні skills, skills з відсутніми вимогами та skills, заблоковані allowlist.
|
||||
- **Legacy-каталоги workspace**: попереджає, коли `~/openclaw` або інші legacy-каталоги workspace існують поруч із поточним workspace.
|
||||
- **Стан Plugin**: підраховує ввімкнені/вимкнені/помилкові plugins; перелічує ID plugin для будь-яких помилок; повідомляє можливості bundle plugin.
|
||||
- **Попередження сумісності Plugin**: позначає plugins, що мають проблеми сумісності з поточним runtime.
|
||||
- **Діагностика Plugin**: показує будь-які попередження або помилки часу завантаження, виведені registry plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="11b. Розмір bootstrap-файла">
|
||||
Doctor перевіряє, чи workspace bootstrap files (наприклад `AGENTS.md`, `CLAUDE.md` або інші injected context files) наближаються до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файла кількість raw vs. injected characters, відсоток truncation, причину truncation (`max/file` або `max/total`) і загальну кількість injected characters як частку від total budget. Коли файли truncated або near the limit, doctor друкує поради з налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`.
|
||||
<Accordion title="11b. Розмір bootstrap-файлу">
|
||||
Doctor перевіряє, чи bootstrap-файли workspace (наприклад `AGENTS.md`, `CLAUDE.md` або інші впроваджені контекстні файли) близькі до налаштованого бюджету символів або перевищують його. Він повідомляє сирі та впроваджені кількості символів для кожного файлу, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість впроваджених символів як частку від загального бюджету. Коли файли обрізано або вони близькі до ліміту, doctor друкує поради з налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`.
|
||||
</Accordion>
|
||||
<Accordion title="11d. Очищення stale channel plugin">
|
||||
Коли `openclaw doctor --fix` видаляє missing channel plugin, він також видаляє dangling channel-scoped config, що посилався на цей plugin: записи `channels.<id>`, heartbeat targets, які називали channel, і перевизначення `agents.*.models["<channel>/*"]`. Це запобігає boot loops Gateway, коли channel runtime зник, але конфігурація все ще просить gateway прив’язатися до нього.
|
||||
<Accordion title="11d. Очищення застарілих channel plugin">
|
||||
Коли `openclaw doctor --fix` видаляє відсутній channel plugin, він також видаляє dangling конфігурацію в scope каналу, що посилалася на цей plugin: записи `channels.<id>`, цілі heartbeat, що називали канал, і перевизначення `agents.*.models["<channel>/*"]`. Це запобігає циклам завантаження Gateway, коли runtime каналу зник, але конфігурація все ще просить gateway прив'язатися до нього.
|
||||
</Accordion>
|
||||
<Accordion title="11c. Автодоповнення shell">
|
||||
Doctor перевіряє, чи встановлено tab completion для поточного shell (zsh, bash, fish або PowerShell):
|
||||
<Accordion title="11c. Shell completion">
|
||||
Doctor перевіряє, чи встановлено tab completion для поточної shell (zsh, bash, fish або PowerShell):
|
||||
|
||||
- Якщо профіль shell використовує повільний dynamic completion pattern (`source <(openclaw completion ...)`), doctor оновлює його до швидшого cached file variant.
|
||||
- Якщо completion налаштовано в профілі, але cache file відсутній, doctor автоматично регенерує cache.
|
||||
- Якщо completion узагалі не налаштовано, doctor пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`).
|
||||
- Якщо профіль shell використовує повільний динамічний шаблон completion (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанту з кешованим файлом.
|
||||
- Якщо completion налаштовано в профілі, але кеш-файл відсутній, doctor автоматично генерує кеш повторно.
|
||||
- Якщо completion взагалі не налаштовано, doctor пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`).
|
||||
|
||||
Запустіть `openclaw completion --write-state`, щоб регенерувати cache вручну.
|
||||
Запустіть `openclaw completion --write-state`, щоб повторно згенерувати кеш вручну.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12. Перевірки автентифікації Gateway (local token)">
|
||||
Doctor перевіряє готовність local gateway token auth.
|
||||
<Accordion title="12. Перевірки автентифікації Gateway (локальний токен)">
|
||||
Doctor перевіряє готовність автентифікації локального gateway-токена.
|
||||
|
||||
- Якщо token mode потребує token, а token source не існує, doctor пропонує згенерувати його.
|
||||
- Якщо `gateway.auth.token` керується SecretRef, але недоступний, doctor попереджає і не перезаписує його plaintext.
|
||||
- `openclaw doctor --generate-gateway-token` примусово генерує token лише тоді, коли token SecretRef не налаштовано.
|
||||
- Якщо режим токена потребує токена, а джерела токена немає, doctor пропонує згенерувати його.
|
||||
- Якщо `gateway.auth.token` керується SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом.
|
||||
- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано token SecretRef.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="12b. Read-only ремонти з урахуванням SecretRef">
|
||||
Деякі repair flows мають перевіряти налаштовані облікові дані без послаблення runtime fail-fast behavior.
|
||||
<Accordion title="12b. Відновлення лише для читання з урахуванням SecretRef">
|
||||
Деякі потоки відновлення мають перевіряти налаштовані облікові дані без послаблення runtime-поведінки fail-fast.
|
||||
|
||||
- `openclaw doctor --fix` тепер використовує ту саму read-only SecretRef summary model, що й status-family commands, для targeted config repairs.
|
||||
- Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані bot credentials, коли вони доступні.
|
||||
- Якщо bot token Telegram налаштовано через SecretRef, але він недоступний у поточному command path, doctor повідомляє, що credential налаштований, але недоступний, і пропускає auto-resolution замість збою або помилкового повідомлення, що token відсутній.
|
||||
- `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації.
|
||||
- Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані bot, коли вони доступні.
|
||||
- Якщо токен bot Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв'язання замість аварійного завершення або помилкового повідомлення, що токен відсутній.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="13. Health check Gateway + перезапуск">
|
||||
Doctor запускає health check і пропонує перезапустити gateway, коли він виглядає unhealthy.
|
||||
<Accordion title="13. Перевірка справності Gateway + перезапуск">
|
||||
Doctor запускає перевірку справності й пропонує перезапустити gateway, коли він виглядає несправним.
|
||||
</Accordion>
|
||||
<Accordion title="13b. Готовність пошуку memory">
|
||||
Doctor перевіряє, чи налаштований memory search embedding provider готовий для default agent. Поведінка залежить від налаштованого backend і provider:
|
||||
<Accordion title="13b. Готовність пошуку в пам'яті">
|
||||
Doctor перевіряє, чи налаштований provider embedding для пошуку в пам'яті готовий для типового агента. Поведінка залежить від налаштованого backend і provider:
|
||||
|
||||
- **QMD backend**: перевіряє, чи доступний і придатний до запуску binary `qmd`. Якщо ні, друкує fix guidance, включно з npm package і manual binary path option.
|
||||
- **Explicit local provider**: перевіряє local model file або recognized remote/downloadable model URL. Якщо відсутній, пропонує перемкнутися на remote provider.
|
||||
- **Explicit remote provider** (`openai`, `voyage` тощо): перевіряє наявність API key в environment або auth store. Друкує actionable fix hints, якщо його бракує.
|
||||
- **Auto provider**: спершу перевіряє local model availability, потім пробує кожен remote provider у порядку auto-selection.
|
||||
- **QMD backend**: перевіряє, чи доступний і придатний до запуску binary `qmd`. Якщо ні, друкує рекомендації з виправлення, зокрема npm-пакет і варіант ручного шляху до binary.
|
||||
- **Явний локальний provider**: перевіряє наявність локального файлу моделі або розпізнаної віддаленої/завантажуваної URL моделі. Якщо бракує, пропонує перемкнутися на віддалений provider.
|
||||
- **Явний віддалений provider** (`openai`, `voyage` тощо): перевіряє, що API-ключ присутній в environment або auth store. Друкує actionable підказки з виправлення, якщо його бракує.
|
||||
- **Auto provider**: спершу перевіряє доступність локальної моделі, потім пробує кожен віддалений provider у порядку auto-selection.
|
||||
|
||||
Коли доступний кешований результат перевірки gateway (gateway був працездатним на момент перевірки), doctor звіряє його результат із конфігурацією, видимою для CLI, і зазначає будь-яку невідповідність. Doctor не запускає новий embedding ping у стандартному шляху; використовуйте команду глибокого стану пам’яті, коли потрібна жива перевірка провайдера.
|
||||
Коли доступний кешований результат перевірки Gateway (Gateway був справним на момент перевірки), doctor звіряє його результат із конфігурацією, видимою для CLI, і позначає будь-яку невідповідність. Doctor не запускає нову перевірку embedding у стандартному шляху; використовуйте команду докладного стану пам’яті, коли потрібна жива перевірка провайдера.
|
||||
|
||||
Використайте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання.
|
||||
Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="14. Попередження про стан каналу">
|
||||
Якщо gateway працездатний, doctor запускає перевірку стану каналу й повідомляє попередження із запропонованими виправленнями.
|
||||
Якщо Gateway справний, doctor запускає перевірку стану каналу та повідомляє попередження із запропонованими виправленнями.
|
||||
</Accordion>
|
||||
<Accordion title="15. Аудит і відновлення конфігурації supervisor">
|
||||
Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на відсутні або застарілі стандартні значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він знаходить невідповідність, він рекомендує оновлення й може переписати файл служби/завдання до поточних стандартних значень.
|
||||
Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на відсутні або застарілі стандартні параметри (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він знаходить невідповідність, він рекомендує оновлення й може переписати файл служби/завдання до поточних стандартних параметрів.
|
||||
|
||||
Примітки:
|
||||
|
||||
@ -459,34 +459,34 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
- `openclaw doctor --yes` приймає стандартні запити на відновлення.
|
||||
- `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів.
|
||||
- `openclaw doctor --repair --force` перезаписує користувацькі конфігурації supervisor.
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби gateway. Він усе ще повідомляє про справність служби й виконує відновлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації supervisor і очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній supervisor.
|
||||
- У Linux doctor не переписує метадані команди/entrypoint, поки відповідний systemd-модуль gateway активний. Він також ігнорує неактивні додаткові не застарілі модулі, схожі на gateway, під час сканування дубльованих служб, щоб супровідні файли служб не створювали зайвого шуму очищення.
|
||||
- Якщо для token auth потрібен токен і `gateway.auth.token` керується SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення plaintext-токена в метаданих середовища служби supervisor.
|
||||
- Doctor виявляє керовані `.env`/SecretRef-backed значення середовища служби, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудували inline, і переписує метадані служби так, щоб ці значення завантажувалися з runtime-джерела, а не з визначення supervisor.
|
||||
- Doctor виявляє, коли команда служби досі закріплює старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт.
|
||||
- Якщо для token auth потрібен токен, а налаштований token SecretRef не розв’язується, doctor блокує шлях встановлення/відновлення з практичними інструкціями.
|
||||
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби Gateway. Він усе ще повідомляє про справність служби та виконує відновлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації supervisor і очищення застарілих служб, бо цим життєвим циклом керує зовнішній supervisor.
|
||||
- У Linux doctor не переписує метадані команди/entrypoint, доки відповідний systemd-юніт Gateway активний. Він також ігнорує неактивні додаткові gateway-подібні юніти, що не є застарілими, під час сканування дубльованих служб, щоб супровідні файли служб не створювали зайвого шуму очищення.
|
||||
- Якщо автентифікація токеном вимагає токен і `gateway.auth.token` керується SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токена у відкритому тексті в метаданих середовища служби supervisor.
|
||||
- Doctor виявляє керовані значення середовища служби на основі `.env`/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудували inline, і переписує метадані служби так, щоб ці значення завантажувалися з runtime-джерела замість визначення supervisor.
|
||||
- Doctor виявляє, коли команда служби все ще фіксує старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт.
|
||||
- Якщо автентифікація токеном вимагає токен, а налаштований SecretRef токена не розв’язано, doctor блокує шлях встановлення/відновлення з практичними вказівками.
|
||||
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки mode не буде задано явно.
|
||||
- Для Linux user-systemd модулів перевірки розбіжності токенів doctor тепер включають джерела і `Environment=`, і `EnvironmentFile=` під час порівняння auth-метаданих служби.
|
||||
- Відновлення служби doctor відмовляються переписувати, зупиняти або перезапускати службу gateway зі старішого бінарного файлу OpenClaw, коли конфігурацію востаннє було записано новішою версією. Див. [Усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
|
||||
- Для користувацьких systemd-юнітів Linux перевірки drift токена doctor тепер включають джерела і `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби.
|
||||
- Відновлення служби doctor відмовляються переписувати, зупиняти або перезапускати службу Gateway зі старішого бінарного файлу OpenClaw, коли конфігурацію востаннє було записано новішою версією. Див. [Усунення проблем Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
|
||||
- Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="16. Діагностика runtime Gateway і порту">
|
||||
Doctor перевіряє runtime служби (PID, останній статус виходу) і попереджає, коли служба встановлена, але фактично не запущена. Він також перевіряє конфлікти портів на порту gateway (стандартно `18789`) і повідомляє ймовірні причини (gateway уже запущений, SSH-тунель).
|
||||
Doctor перевіряє runtime служби (PID, останній статус виходу) і попереджає, коли служба встановлена, але фактично не запущена. Він також перевіряє конфлікти портів на порту Gateway (стандартно `18789`) і повідомляє ймовірні причини (Gateway уже запущений, SSH-тунель).
|
||||
</Accordion>
|
||||
<Accordion title="17. Найкращі практики runtime Gateway">
|
||||
Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджера версій можуть ламатися після оновлень, оскільки служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує мігрувати на системне встановлення Node, коли воно доступне (Homebrew/apt/choco).
|
||||
<Accordion title="17. Рекомендовані практики runtime Gateway">
|
||||
Doctor попереджає, коли служба Gateway працює на Bun або шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджера версій можуть ламатися після оновлень, бо служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує мігрувати на системне встановлення Node, коли воно доступне (Homebrew/apt/choco).
|
||||
|
||||
Нові встановлені або відновлені служби зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні каталоги user-bin, але вгадані резервні каталоги менеджера версій записуються до service PATH лише тоді, коли ці каталоги існують на диску. Це тримає згенерований supervisor PATH узгодженим із тим самим аудитом мінімального PATH, який doctor запускає пізніше.
|
||||
Нововстановлені або відновлені служби зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні каталоги user-bin, але вгадані fallback-каталоги менеджера версій записуються до service PATH лише тоді, коли ці каталоги існують на диску. Це узгоджує згенерований supervisor PATH із тим самим аудитом мінімального PATH, який doctor запускає пізніше.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="18. Запис конфігурації й метадані майстра">
|
||||
Doctor зберігає всі зміни конфігурації та проставляє метадані майстра, щоб зафіксувати запуск doctor.
|
||||
<Accordion title="18. Запис конфігурації та метадані майстра">
|
||||
Doctor зберігає будь-які зміни конфігурації та ставить позначку в метаданих майстра, щоб зафіксувати запуск doctor.
|
||||
</Accordion>
|
||||
<Accordion title="19. Поради щодо робочого простору (резервна копія + система пам’яті)">
|
||||
<Accordion title="19. Поради щодо робочого простору (резервне копіювання + система пам’яті)">
|
||||
Doctor пропонує систему пам’яті робочого простору, коли її немає, і виводить пораду щодо резервного копіювання, якщо робочий простір ще не перебуває під git.
|
||||
|
||||
Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі структури робочого простору й резервного копіювання git (рекомендовано приватний GitHub або GitLab).
|
||||
Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace) для повного посібника зі структури робочого простору та резервного копіювання git (рекомендовано приватний GitHub або GitLab).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -494,4 +494,4 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
|
||||
## Пов’язане
|
||||
|
||||
- [Runbook Gateway](/uk/gateway)
|
||||
- [Усунення несправностей Gateway](/uk/gateway/troubleshooting)
|
||||
- [Усунення проблем Gateway](/uk/gateway/troubleshooting)
|
||||
|
||||
@ -1,40 +1,40 @@
|
||||
---
|
||||
read_when:
|
||||
- Реалізація або оновлення WS-клієнтів Gateway
|
||||
- Впровадження або оновлення WS-клієнтів Gateway
|
||||
- Налагодження невідповідностей протоколу або збоїв підключення
|
||||
- Повторне генерування схеми/моделей протоколу
|
||||
summary: 'Протокол WebSocket Gateway: рукостискання, кадри, версіонування'
|
||||
summary: 'Протокол WebSocket для Gateway: рукостискання, кадри, версіонування'
|
||||
title: Протокол Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T08:21:03Z"
|
||||
generated_at: "2026-05-01T08:52:01Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 1b80ee7d9a36f78b05b8ca83d70baf6ec53fc907ca25e8b4c2ab39350ff95c54
|
||||
source_hash: 8ea0181fda62326ec835ff1f28ef6079e5afff5ffe3f06e08867bf16fb84f967
|
||||
source_path: gateway/protocol.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Протокол Gateway WS є **єдиною площиною керування + транспортом вузлів** для
|
||||
Gateway WS-протокол є **єдиною площиною керування + транспортом вузлів** для
|
||||
OpenClaw. Усі клієнти (CLI, вебінтерфейс, застосунок macOS, вузли iOS/Android,
|
||||
безголові вузли) підключаються через WebSocket і оголошують свою **роль** +
|
||||
**область дії** під час рукостискання.
|
||||
headless-вузли) підключаються через WebSocket і оголошують свою **роль** +
|
||||
**область** під час handshake.
|
||||
|
||||
## Транспорт
|
||||
|
||||
- WebSocket, текстові кадри з JSON-навантаженнями.
|
||||
- Перший кадр **має** бути запитом `connect`.
|
||||
- Кадри до підключення обмежені 64 KiB. Після успішного рукостискання клієнти
|
||||
- WebSocket, текстові фрейми з JSON-навантаженнями.
|
||||
- Перший фрейм **має** бути запитом `connect`.
|
||||
- Фрейми до підключення обмежені 64 KiB. Після успішного handshake клієнти
|
||||
мають дотримуватися обмежень `hello-ok.policy.maxPayload` і
|
||||
`hello-ok.policy.maxBufferedBytes`. Коли діагностику ввімкнено,
|
||||
завеликі вхідні кадри та повільні вихідні буфери створюють події
|
||||
`payload.large` перед тим, як Gateway закриє або відкине відповідний кадр.
|
||||
`hello-ok.policy.maxBufferedBytes`. Якщо діагностику увімкнено,
|
||||
завеликі вхідні фрейми та повільні вихідні буфери емітують події
|
||||
`payload.large` до того, як gateway закриє або відкине відповідний фрейм.
|
||||
Ці події зберігають розміри, обмеження, поверхні та безпечні коди причин.
|
||||
Вони не зберігають тіло повідомлення, вміст вкладень, сире тіло кадру,
|
||||
токени, cookies або секретні значення.
|
||||
Вони не зберігають тіло повідомлення, вміст вкладень, сире тіло фрейму,
|
||||
токени, cookie або секретні значення.
|
||||
|
||||
## Рукостискання (connect)
|
||||
## Handshake (connect)
|
||||
|
||||
Gateway → Клієнт (виклик до підключення):
|
||||
Gateway → Клієнт (попередній challenge до підключення):
|
||||
|
||||
```json
|
||||
{
|
||||
@ -105,18 +105,18 @@ Gateway → Клієнт:
|
||||
}
|
||||
```
|
||||
|
||||
Поки Gateway ще завершує запуск побічних процесів, запит `connect` може
|
||||
Поки Gateway ще завершує запуск допоміжних sidecar-процесів, запит `connect` може
|
||||
повернути повторювану помилку `UNAVAILABLE` з `details.reason`, установленим у
|
||||
`"startup-sidecars"`, і `retryAfterMs`. Клієнти мають повторити цю відповідь
|
||||
`"startup-sidecars"`, і `retryAfterMs`. Клієнти мають повторити таку відповідь
|
||||
у межах свого загального бюджету підключення, а не показувати її як остаточний
|
||||
збій рукостискання.
|
||||
збій handshake.
|
||||
|
||||
`server`, `features`, `snapshot` і `policy` є обов’язковими за схемою
|
||||
(`src/gateway/protocol/schema/frames.ts`). `auth` також є обов’язковим і
|
||||
повідомляє узгоджену роль/області дії. `canvasHostUrl` є необов’язковим.
|
||||
(`src/gateway/protocol/schema/frames.ts`). `auth` також є обов’язковим і повідомляє
|
||||
узгоджену роль/області. `canvasHostUrl` є необов’язковим.
|
||||
|
||||
Коли токен пристрою не видано, `hello-ok.auth` повідомляє узгоджені дозволи
|
||||
без полів токена:
|
||||
Коли токен пристрою не видано, `hello-ok.auth` повідомляє узгоджені
|
||||
дозволи без полів токена:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -128,14 +128,12 @@ Gateway → Клієнт:
|
||||
```
|
||||
|
||||
Довірені backend-клієнти в тому самому процесі (`client.id: "gateway-client"`,
|
||||
`client.mode: "backend"`) можуть не передавати `device` для прямих loopback-з’єднань,
|
||||
коли вони автентифікуються спільним токеном/паролем Gateway. Цей шлях
|
||||
зарезервований для внутрішніх RPC площини керування і не дає застарілим
|
||||
базовим станам сполучення CLI/пристрою блокувати локальну backend-роботу,
|
||||
таку як оновлення сеансів субагентів. Віддалені клієнти, клієнти з браузерним
|
||||
походженням, клієнти-вузли та явні клієнти з токеном пристрою/ідентичністю
|
||||
пристрою й далі використовують звичайні перевірки сполучення та підвищення
|
||||
області дії.
|
||||
`client.mode: "backend"`) можуть пропускати `device` для прямих local loopback-підключень, коли
|
||||
вони автентифікуються за допомогою спільного токена/пароля gateway. Цей шлях зарезервований
|
||||
для внутрішніх RPC площини керування й не дає застарілим базовим даним парування CLI/пристрою
|
||||
блокувати локальну backend-роботу, як-от оновлення сеансів субагентів. Віддалені клієнти,
|
||||
клієнти з браузерним origin, клієнти-вузли та явні клієнти з device-token/device-identity
|
||||
далі використовують звичайні перевірки парування й підвищення області.
|
||||
|
||||
Коли токен пристрою видано, `hello-ok` також містить:
|
||||
|
||||
@ -149,8 +147,8 @@ Gateway → Клієнт:
|
||||
}
|
||||
```
|
||||
|
||||
Під час довіреної передачі bootstrap `hello-ok.auth` також може містити
|
||||
додаткові обмежені записи ролей у `deviceTokens`:
|
||||
Під час довіреної передачі bootstrap `hello-ok.auth` може також містити додаткові
|
||||
обмежені записи ролей у `deviceTokens`:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -169,15 +167,14 @@ Gateway → Клієнт:
|
||||
}
|
||||
```
|
||||
|
||||
Для вбудованого bootstrap-потоку вузол/оператор основний токен вузла
|
||||
залишається з `scopes: []`, а будь-який переданий операторський токен
|
||||
залишається обмеженим allowlist bootstrap-оператора (`operator.approvals`,
|
||||
`operator.read`, `operator.talk.secrets`, `operator.write`). Перевірки областей
|
||||
дії bootstrap залишаються префіксованими роллю: операторські записи
|
||||
задовольняють лише операторські запити, а неоператорські ролі все ще потребують
|
||||
областей дії з префіксом власної ролі.
|
||||
Для вбудованого потоку bootstrap вузла/оператора основний токен вузла лишається
|
||||
`scopes: []`, а будь-який переданий токен оператора лишається обмеженим allowlist
|
||||
bootstrap-оператора (`operator.approvals`, `operator.read`,
|
||||
`operator.talk.secrets`, `operator.write`). Перевірки областей bootstrap лишаються
|
||||
префіксованими роллю: записи оператора задовольняють лише запити оператора, а неоператорські
|
||||
ролі й далі потребують областей під власним префіксом ролі.
|
||||
|
||||
### Приклад вузла
|
||||
### Приклад Node
|
||||
|
||||
```json
|
||||
{
|
||||
@ -212,7 +209,7 @@ Gateway → Клієнт:
|
||||
}
|
||||
```
|
||||
|
||||
## Обрамлення
|
||||
## Фреймінг
|
||||
|
||||
- **Запит**: `{type:"req", id, method, params}`
|
||||
- **Відповідь**: `{type:"res", id, ok, payload|error}`
|
||||
@ -220,16 +217,16 @@ Gateway → Клієнт:
|
||||
|
||||
Методи з побічними ефектами потребують **ключів ідемпотентності** (див. схему).
|
||||
|
||||
## Ролі + області дії
|
||||
## Ролі + області
|
||||
|
||||
### Ролі
|
||||
|
||||
- `operator` = клієнт площини керування (CLI/UI/автоматизація).
|
||||
- `node` = хост можливостей (camera/screen/canvas/system.run).
|
||||
|
||||
### Області дії (оператор)
|
||||
### Області (operator)
|
||||
|
||||
Поширені області дії:
|
||||
Поширені області:
|
||||
|
||||
- `operator.read`
|
||||
- `operator.write`
|
||||
@ -241,47 +238,45 @@ Gateway → Клієнт:
|
||||
`talk.config` з `includeSecrets: true` потребує `operator.talk.secrets`
|
||||
(або `operator.admin`).
|
||||
|
||||
RPC-методи Gateway, зареєстровані Plugin, можуть запитувати власну операторську
|
||||
область дії, але зарезервовані основні префікси адміністратора (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) завжди перетворюються на
|
||||
`operator.admin`.
|
||||
Методи Gateway RPC, зареєстровані Plugin, можуть запитувати власну область оператора, але
|
||||
зарезервовані основні admin-префікси (`config.*`, `exec.approvals.*`, `wizard.*`,
|
||||
`update.*`) завжди розв’язуються в `operator.admin`.
|
||||
|
||||
Область дії методу є лише першою перевіркою. Деякі slash-команди, доступні
|
||||
через `chat.send`, застосовують суворіші перевірки рівня команди поверх цього.
|
||||
Наприклад, сталі записи `/config set` і `/config unset` потребують
|
||||
`operator.admin`.
|
||||
Область методу — лише перший бар’єр. Деякі slash-команди, доступні через
|
||||
`chat.send`, застосовують суворіші перевірки на рівні команди. Наприклад, постійні
|
||||
записи `/config set` і `/config unset` потребують `operator.admin`.
|
||||
|
||||
`node.pair.approve` також має додаткову перевірку області дії під час
|
||||
затвердження поверх базової області дії методу:
|
||||
`node.pair.approve` також має додаткову перевірку області під час схвалення поверх
|
||||
базової області методу:
|
||||
|
||||
- запити без команд: `operator.pairing`
|
||||
- запити з node-командами не для exec: `operator.pairing` + `operator.write`
|
||||
- запити, які містять `system.run`, `system.run.prepare` або `system.which`:
|
||||
- запити з не-exec командами вузла: `operator.pairing` + `operator.write`
|
||||
- запити, що містять `system.run`, `system.run.prepare` або `system.which`:
|
||||
`operator.pairing` + `operator.admin`
|
||||
|
||||
### Можливості/команди/дозволи (вузол)
|
||||
### Можливості/команди/дозволи (node)
|
||||
|
||||
Вузли оголошують заявки на можливості під час підключення:
|
||||
Вузли оголошують claims можливостей під час підключення:
|
||||
|
||||
- `caps`: категорії можливостей високого рівня.
|
||||
- `commands`: allowlist команд для виклику.
|
||||
- `permissions`: детальні перемикачі (наприклад, `screen.record`, `camera.capture`).
|
||||
- `caps`: високорівневі категорії можливостей.
|
||||
- `commands`: allowlist команд для invoke.
|
||||
- `permissions`: гранулярні перемикачі (наприклад, `screen.record`, `camera.capture`).
|
||||
|
||||
Gateway розглядає їх як **заявки** і забезпечує server-side allowlist.
|
||||
Gateway розглядає їх як **claims** і застосовує server-side allowlist-и.
|
||||
|
||||
## Присутність
|
||||
|
||||
- `system-presence` повертає записи, ключовані ідентичністю пристрою.
|
||||
- Записи присутності містять `deviceId`, `roles` і `scopes`, щоб UI могли показувати один рядок на пристрій,
|
||||
навіть коли він підключається одночасно як **operator** і **node**.
|
||||
- `system-presence` повертає записи, індексовані за ідентичністю пристрою.
|
||||
- Записи присутності містять `deviceId`, `roles` і `scopes`, щоб інтерфейси могли показувати один рядок на пристрій
|
||||
навіть коли він підключається і як **operator**, і як **node**.
|
||||
- `node.list` містить необов’язкові поля `lastSeenAtMs` і `lastSeenReason`. Підключені вузли повідомляють
|
||||
свій поточний час підключення як `lastSeenAtMs` із причиною `connect`; сполучені вузли також можуть повідомляти
|
||||
сталу фонову присутність, коли довірена подія вузла оновлює їхні метадані сполучення.
|
||||
свій поточний час підключення як `lastSeenAtMs` з причиною `connect`; спаровані вузли також можуть повідомляти
|
||||
стійку фонову присутність, коли довірена подія вузла оновлює їхні метадані парування.
|
||||
|
||||
### Фонова подія активності вузла
|
||||
### Фонова alive-подія вузла
|
||||
|
||||
Вузли можуть викликати `node.event` з `event: "node.presence.alive"`, щоб записати, що сполучений вузол був
|
||||
активним під час фонового пробудження, не позначаючи його як підключений.
|
||||
Вузли можуть викликати `node.event` з `event: "node.presence.alive"`, щоб записати, що спарований вузол був
|
||||
активний під час фонового пробудження, не позначаючи його як підключений.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -292,10 +287,10 @@ Gateway розглядає їх як **заявки** і забезпечує se
|
||||
|
||||
`trigger` є закритим enum: `background`, `silent_push`, `bg_app_refresh`,
|
||||
`significant_location`, `manual` або `connect`. Невідомі рядки trigger нормалізуються до
|
||||
`background` Gateway перед збереженням. Подія є сталою лише для автентифікованих node-сеансів
|
||||
пристрою; сеанси без пристрою або без сполучення повертають `handled: false`.
|
||||
`background` gateway перед збереженням. Подія є стійкою лише для автентифікованих сеансів
|
||||
пристроїв-вузлів; сеанси без пристрою або без парування повертають `handled: false`.
|
||||
|
||||
Успішні Gateway повертають структурований результат:
|
||||
Успішні gateway повертають структурований результат:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -306,156 +301,156 @@ Gateway розглядає їх як **заявки** і забезпечує se
|
||||
}
|
||||
```
|
||||
|
||||
Старіші Gateway можуть усе ще повертати `{ "ok": true }` для `node.event`; клієнти мають трактувати це як
|
||||
підтверджений RPC, а не як стале збереження присутності.
|
||||
Старіші gateway можуть усе ще повертати `{ "ok": true }` для `node.event`; клієнти мають трактувати це як
|
||||
підтверджений RPC, а не як стійке збереження присутності.
|
||||
|
||||
## Обмеження області дії broadcast-подій
|
||||
## Обмеження області broadcast-подій
|
||||
|
||||
Broadcast-події WebSocket, які надсилає сервер, обмежуються областями дії, щоб сеанси з областю дії сполучення або лише вузлами не отримували пасивно вміст сеансів.
|
||||
Server-pushed WebSocket broadcast-події обмежуються областями, щоб сеанси з областю парування або лише вузлові сеанси не отримували пасивно вміст сеансів.
|
||||
|
||||
- **Кадри чату, агента та результатів інструментів** (включно зі streamed-подіями `agent` і результатами викликів інструментів) потребують щонайменше `operator.read`. Сеанси без `operator.read` повністю пропускають ці кадри.
|
||||
- **Визначені Plugin broadcast-події `plugin.*`** обмежуються `operator.write` або `operator.admin`, залежно від того, як Plugin їх зареєстрував.
|
||||
- **Події стану й транспорту** (`heartbeat`, `presence`, `tick`, життєвий цикл connect/disconnect тощо) залишаються необмеженими, щоб справність транспорту була видимою для кожного автентифікованого сеансу.
|
||||
- **Невідомі сімейства broadcast-подій** за замовчуванням обмежуються областю дії (fail-closed), якщо зареєстрований обробник явно не послаблює їх.
|
||||
- **Фрейми чату, агента та результатів інструментів** (включно зі streaming-подіями `agent` і результатами викликів інструментів) потребують щонайменше `operator.read`. Сеанси без `operator.read` повністю пропускають ці фрейми.
|
||||
- **Визначені Plugin broadcast-и `plugin.*`** обмежуються `operator.write` або `operator.admin`, залежно від того, як plugin їх зареєстрував.
|
||||
- **Події статусу й транспорту** (`heartbeat`, `presence`, `tick`, життєвий цикл connect/disconnect тощо) лишаються необмеженими, щоб стан транспорту був видимий кожному автентифікованому сеансу.
|
||||
- **Невідомі сімейства broadcast-подій** за замовчуванням обмежуються областю (fail-closed), якщо зареєстрований handler явно не послаблює їх.
|
||||
|
||||
Кожне клієнтське підключення зберігає власний порядковий номер для кожного клієнта, тому broadcast-події зберігають монотонний порядок у цьому socket навіть тоді, коли різні клієнти бачать різні підмножини потоку подій після фільтрації за областями дії.
|
||||
Кожне клієнтське підключення зберігає власний послідовний номер на клієнта, тож broadcast-и зберігають монотонний порядок на цьому сокеті, навіть коли різні клієнти бачать різні відфільтровані за областями підмножини потоку подій.
|
||||
|
||||
## Поширені сімейства RPC-методів
|
||||
## Поширені сімейства методів RPC
|
||||
|
||||
Публічна поверхня WS ширша за наведені вище приклади рукостискання/auth. Це
|
||||
не згенерований дамп — `hello-ok.features.methods` є консервативним списком
|
||||
виявлення, побудованим із `src/gateway/server-methods-list.ts` плюс завантажені
|
||||
експорти методів Plugin/каналів. Трактуйте його як виявлення функцій, а не
|
||||
повний перелік `src/gateway/server-methods/*.ts`.
|
||||
Публічна WS-поверхня ширша за наведені вище приклади handshake/auth. Це
|
||||
не згенерований дамп — `hello-ok.features.methods` є консервативним
|
||||
списком виявлення, побудованим із `src/gateway/server-methods-list.ts` плюс завантажені
|
||||
експорти методів plugin/channel. Розглядайте його як виявлення функцій, а не повний
|
||||
перелік `src/gateway/server-methods/*.ts`.
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="System and identity">
|
||||
- `health` повертає кешований або щойно перевірений знімок стану Gateway.
|
||||
- `diagnostics.stability` повертає нещодавній обмежений реєстратор діагностичної стабільності. Він зберігає операційні метадані, як-от назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сеансу, назви каналів/Plugin і ідентифікатори сеансів. Він не зберігає текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookies чи секретні значення. Потрібна операторська область дії read.
|
||||
- `status` повертає зведення Gateway у стилі `/status`; чутливі поля включаються лише для операторських клієнтів з admin-областю дії.
|
||||
- `gateway.identity.get` повертає ідентичність пристрою Gateway, яку використовують потоки relay і сполучення.
|
||||
<Accordion title="Система та ідентичність">
|
||||
- `health` повертає кешований або щойно перевірений health-знімок gateway.
|
||||
- `diagnostics.stability` повертає нещодавній обмежений діагностичний recorder стабільності. Він зберігає операційні метадані, як-от назви подій, лічильники, розміри в байтах, показники пам’яті, стан черги/сеансу, назви каналів/plugin-ів та ідентифікатори сеансів. Він не зберігає текст чату, тіла webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookie чи секретні значення. Потрібна область читання оператора.
|
||||
- `status` повертає gateway-зведення у стилі `/status`; чутливі поля включаються лише для операторських клієнтів з admin-областю.
|
||||
- `gateway.identity.get` повертає ідентичність пристрою gateway, яку використовують потоки relay і парування.
|
||||
- `system-presence` повертає поточний знімок присутності для підключених пристроїв operator/node.
|
||||
- `system-event` додає системну подію і може оновлювати/транслювати контекст присутності.
|
||||
- `last-heartbeat` повертає останню збережену подію Heartbeat.
|
||||
- `set-heartbeats` перемикає обробку Heartbeat на Gateway.
|
||||
- `set-heartbeats` перемикає обробку Heartbeat на gateway.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Моделі та використання">
|
||||
- `models.list` повертає каталог моделей, дозволених під час виконання. Передайте `{ "view": "configured" }` для стислого для вибірника списку налаштованих моделей (спочатку `agents.defaults.models`, потім `models.providers.*.models`) або `{ "view": "all" }` для повного каталогу.
|
||||
- `usage.status` повертає зведення щодо вікон використання провайдера та залишкової квоти.
|
||||
- `usage.cost` повертає агреговані зведення витрат за діапазон дат.
|
||||
- `doctor.memory.status` повертає готовність векторної памʼяті / кешованих embedding для активного робочого простору типового агента. Передавайте `{ "probe": true }` або `{ "deep": true }` лише коли викликач явно хоче живий ping провайдера embedding.
|
||||
- `doctor.memory.remHarness` повертає обмежений, доступний лише для читання попередній перегляд REM harness для віддалених клієнтів control-plane. Він може містити шляхи робочого простору, фрагменти памʼяті, відрендерений grounded markdown і кандидатів на deep promotion, тому викликачам потрібен `operator.read`.
|
||||
- `sessions.usage` повертає зведення використання за сеансами.
|
||||
- `sessions.usage.timeseries` повертає часовий ряд використання для одного сеансу.
|
||||
- `sessions.usage.logs` повертає записи журналу використання для одного сеансу.
|
||||
- `models.list` повертає каталог моделей, дозволених середовищем виконання. Передайте `{ "view": "configured" }` для налаштованих моделей розміру вибирача (`agents.defaults.models` спочатку, потім `models.providers.*.models`), або `{ "view": "all" }` для повного каталогу.
|
||||
- `usage.status` повертає вікна використання провайдера / зведення залишку квоти.
|
||||
- `usage.cost` повертає агреговані зведення вартості використання за діапазон дат.
|
||||
- `doctor.memory.status` повертає готовність векторної пам’яті / кешованих embedding для активного стандартного робочого простору агента. Передавайте `{ "probe": true }` або `{ "deep": true }` лише тоді, коли викликач явно хоче живий ping провайдера embedding.
|
||||
- `doctor.memory.remHarness` повертає обмежений, доступний лише для читання попередній перегляд REM harness для віддалених клієнтів control-plane. Він може містити шляхи робочого простору, фрагменти пам’яті, відрендерений обґрунтований Markdown і кандидатів на глибоке просування, тому викликачам потрібен `operator.read`.
|
||||
- `sessions.usage` повертає зведення використання для кожної сесії.
|
||||
- `sessions.usage.timeseries` повертає часовий ряд використання для однієї сесії.
|
||||
- `sessions.usage.logs` повертає записи журналу використання для однієї сесії.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Канали та помічники входу">
|
||||
- `channels.status` повертає зведення статусу вбудованих і комплектних каналів/Plugin.
|
||||
- `channels.logout` виконує вихід із певного каналу/облікового запису, якщо канал підтримує вихід.
|
||||
- `web.login.start` запускає QR/web-потік входу для поточного web-провайдера каналу з підтримкою QR.
|
||||
- `web.login.wait` очікує завершення цього QR/web-потоку входу та в разі успіху запускає канал.
|
||||
- `push.test` надсилає тестовий APNs push на зареєстрований iOS-вузол.
|
||||
- `channels.status` повертає зведення стану вбудованих і пакетних каналів / Plugin.
|
||||
- `channels.logout` виконує вихід із конкретного каналу / облікового запису, якщо канал підтримує вихід.
|
||||
- `web.login.start` запускає потік входу через QR/web для поточного провайдера вебканалу з підтримкою QR.
|
||||
- `web.login.wait` очікує завершення цього потоку входу через QR/web і запускає канал у разі успіху.
|
||||
- `push.test` надсилає тестовий APNs push до зареєстрованого iOS-вузла.
|
||||
- `voicewake.get` повертає збережені тригери wake-word.
|
||||
- `voicewake.set` оновлює тригери wake-word і транслює зміну.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Повідомлення та журнали">
|
||||
- `send` — це прямий RPC для вихідної доставки, націлений на канал/обліковий запис/тред, для надсилань поза chat runner.
|
||||
- `logs.tail` повертає налаштований хвіст файлового журналу gateway з елементами керування cursor/limit і max-byte.
|
||||
- `send` — це прямий RPC вихідної доставки для надсилань, націлених на канал / обліковий запис / гілку, поза chat runner.
|
||||
- `logs.tail` повертає налаштований хвіст файлового журналу gateway з курсором / лімітом і керуванням максимальною кількістю байтів.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Talk і TTS">
|
||||
- `talk.config` повертає ефективне корисне навантаження конфігурації Talk; `includeSecrets` вимагає `operator.talk.secrets` (або `operator.admin`).
|
||||
- `talk.mode` встановлює/транслює поточний стан режиму Talk для клієнтів WebChat/Control UI.
|
||||
- `talk.config` повертає ефективне корисне навантаження конфігурації Talk; `includeSecrets` потребує `operator.talk.secrets` (або `operator.admin`).
|
||||
- `talk.mode` встановлює / транслює поточний стан режиму Talk для клієнтів WebChat/Control UI.
|
||||
- `talk.speak` синтезує мовлення через активного провайдера мовлення Talk.
|
||||
- `tts.status` повертає стан увімкнення TTS, активного провайдера, резервних провайдерів і стан конфігурації провайдера.
|
||||
- `tts.providers` повертає видимий інвентар провайдерів TTS.
|
||||
- `tts.enable` і `tts.disable` перемикають стан налаштувань TTS.
|
||||
- `tts.setProvider` оновлює бажаного провайдера TTS.
|
||||
- `tts.convert` виконує одноразове перетворення тексту на мовлення.
|
||||
- `tts.convert` запускає одноразове перетворення тексту на мовлення.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Секрети, конфігурація, оновлення та майстер">
|
||||
- `secrets.reload` повторно розвʼязує активні SecretRefs і замінює стан секретів під час виконання лише в разі повного успіху.
|
||||
- `secrets.resolve` розвʼязує призначення секретів для цільових команд для певного набору command/target.
|
||||
- `config.get` повертає поточний знімок конфігурації та hash.
|
||||
- `secrets.reload` повторно розв’язує активні SecretRefs і замінює стан секретів середовища виконання лише після повного успіху.
|
||||
- `secrets.resolve` розв’язує призначення секретів, націлені на команду, для конкретного набору команд / цілей.
|
||||
- `config.get` повертає поточний знімок конфігурації та хеш.
|
||||
- `config.set` записує перевірене корисне навантаження конфігурації.
|
||||
- `config.patch` зливає часткове оновлення конфігурації.
|
||||
- `config.apply` перевіряє та замінює повне корисне навантаження конфігурації.
|
||||
- `config.schema` повертає живе корисне навантаження схеми конфігурації, яке використовують Control UI та інструменти CLI: schema, `uiHints`, version і метадані generation, зокрема метадані схеми plugin + channel, коли середовище виконання може їх завантажити. Схема містить метадані полів `title` / `description`, отримані з тих самих міток і довідкового тексту, які використовує UI, зокрема вкладені обʼєкти, wildcard, елементи масиву та гілки композиції `anyOf` / `oneOf` / `allOf`, коли існує відповідна документація поля.
|
||||
- `config.schema.lookup` повертає корисне навантаження пошуку, обмежене шляхом, для одного шляху конфігурації: нормалізований шлях, поверхневий вузол схеми, відповідний hint + `hintPath` і зведення безпосередніх дочірніх елементів для деталізації в UI/CLI. Вузли схеми пошуку зберігають користувацьку документацію та поширені поля валідації (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, межі numeric/string/array/object і прапорці на кшталт `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Дочірні зведення показують `key`, нормалізований `path`, `type`, `required`, `hasChildren`, а також відповідні `hint` / `hintPath`.
|
||||
- `update.run` запускає потік оновлення gateway і планує перезапуск лише тоді, коли саме оновлення завершилося успішно.
|
||||
- `update.status` повертає останній кешований restart sentinel оновлення, зокрема поточну версію після перезапуску, коли вона доступна.
|
||||
- `wizard.start`, `wizard.next`, `wizard.status` і `wizard.cancel` відкривають майстер онбордингу через WS RPC.
|
||||
- `config.patch` об’єднує часткове оновлення конфігурації.
|
||||
- `config.apply` перевіряє й замінює повне корисне навантаження конфігурації.
|
||||
- `config.schema` повертає живе корисне навантаження схеми конфігурації, яке використовують Control UI та інструменти CLI: схему, `uiHints`, версію та метадані генерації, зокрема метадані схем Plugin і каналів, коли середовище виконання може їх завантажити. Схема містить метадані полів `title` / `description`, отримані з тих самих міток і довідкового тексту, які використовує UI, включно з вкладеними об’єктами, wildcard, елементами масиву та гілками композиції `anyOf` / `oneOf` / `allOf`, коли існує відповідна документація поля.
|
||||
- `config.schema.lookup` повертає корисне навантаження пошуку, обмежене шляхом, для одного шляху конфігурації: нормалізований шлях, поверхневий вузол схеми, відповідну підказку + `hintPath` і зведення безпосередніх дочірніх елементів для деталізації в UI/CLI. Вузли схеми пошуку зберігають користувацьку документацію та поширені поля перевірки (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, межі чисел / рядків / масивів / об’єктів і прапорці на кшталт `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Зведення дочірніх елементів показують `key`, нормалізований `path`, `type`, `required`, `hasChildren`, а також відповідні `hint` / `hintPath`.
|
||||
- `update.run` запускає потік оновлення gateway і планує перезапуск лише тоді, коли саме оновлення завершилося успішно. Оновлення через менеджер пакетів примусово виконують невідкладений перезапуск після заміни пакета, щоб старий процес Gateway не продовжував lazy-loading із заміненого дерева `dist`.
|
||||
- `update.status` повертає останній кешований sentinel перезапуску оновлення, включно з версією, що працює після перезапуску, якщо вона доступна.
|
||||
- `wizard.start`, `wizard.next`, `wizard.status` і `wizard.cancel` відкривають майстер onboarding через WS RPC.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Помічники агента та робочого простору">
|
||||
- `agents.list` повертає налаштовані записи агентів, зокрема ефективну модель і метадані середовища виконання.
|
||||
- `agents.create`, `agents.update` і `agents.delete` керують записами агентів і привʼязкою робочого простору.
|
||||
- `agents.list` повертає налаштовані записи агентів, включно з ефективною моделлю та метаданими середовища виконання.
|
||||
- `agents.create`, `agents.update` і `agents.delete` керують записами агентів і прив’язкою робочого простору.
|
||||
- `agents.files.list`, `agents.files.get` і `agents.files.set` керують bootstrap-файлами робочого простору, відкритими для агента.
|
||||
- `artifacts.list`, `artifacts.get` і `artifacts.download` відкривають зведення артефактів і завантаження, отримані з транскрипту, для явної області `sessionKey`, `runId` або `taskId`. Запити run і task розвʼязують власний сеанс на боці сервера та повертають лише медіа транскрипту з відповідним походженням; небезпечні або локальні URL-джерела повертають непідтримувані завантаження замість завантаження на боці сервера.
|
||||
- `agent.identity.get` повертає ефективну ідентичність асистента для агента або сеансу.
|
||||
- `agent.wait` очікує завершення run і повертає фінальний знімок, коли він доступний.
|
||||
- `artifacts.list`, `artifacts.get` і `artifacts.download` відкривають зведення та завантаження артефактів, отриманих із транскрипту, для явної області `sessionKey`, `runId` або `taskId`. Запити run і task розв’язують сесію-власника на боці сервера й повертають лише медіа транскрипту з відповідним походженням; небезпечні або локальні URL-джерела повертають непідтримувані завантаження замість отримання на боці сервера.
|
||||
- `agent.identity.get` повертає ефективну ідентичність асистента для агента або сесії.
|
||||
- `agent.wait` очікує завершення run і повертає фінальний знімок, якщо він доступний.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Керування сеансами">
|
||||
- `sessions.list` повертає поточний індекс сеансів, зокрема метадані `agentRuntime` для кожного рядка, коли налаштовано backend середовища виконання агента.
|
||||
- `sessions.subscribe` і `sessions.unsubscribe` перемикають підписки на події зміни сеансів для поточного WS-клієнта.
|
||||
- `sessions.messages.subscribe` і `sessions.messages.unsubscribe` перемикають підписки на події транскрипту/повідомлень для одного сеансу.
|
||||
- `sessions.preview` повертає обмежені попередні перегляди транскриптів для певних ключів сеансів.
|
||||
- `sessions.resolve` розвʼязує або канонізує ціль сеансу.
|
||||
- `sessions.create` створює новий запис сеансу.
|
||||
- `sessions.send` надсилає повідомлення в наявний сеанс.
|
||||
- `sessions.steer` — це варіант interrupt-and-steer для активного сеансу.
|
||||
- `sessions.abort` перериває активну роботу для сеансу. Викликач може передати `key` плюс необовʼязковий `runId` або передати лише `runId` для активних run, які Gateway може розвʼязати до сеансу.
|
||||
- `sessions.patch` оновлює метадані/перевизначення сеансу та повідомляє розвʼязану канонічну модель плюс ефективний `agentRuntime`.
|
||||
- `sessions.reset`, `sessions.delete` і `sessions.compact` виконують обслуговування сеансів.
|
||||
- `sessions.get` повертає повний збережений рядок сеансу.
|
||||
- Виконання чату й надалі використовує `chat.history`, `chat.send`, `chat.abort` і `chat.inject`. `chat.history` нормалізовано для відображення UI-клієнтам: inline directive tags вилучаються з видимого тексту, plain-text XML payloads викликів інструментів (зокрема `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізані блоки викликів інструментів) та leaked ASCII/full-width model control tokens вилучаються, чисті silent-token рядки асистента, як-от точні `NO_REPLY` / `no_reply`, опускаються, а надмірно великі рядки можуть замінюватися placeholder.
|
||||
<Accordion title="Керування сесіями">
|
||||
- `sessions.list` повертає поточний індекс сесій, включно з метаданими `agentRuntime` для кожного рядка, коли налаштовано бекенд середовища виконання агента.
|
||||
- `sessions.subscribe` і `sessions.unsubscribe` перемикають підписки на події зміни сесій для поточного WS-клієнта.
|
||||
- `sessions.messages.subscribe` і `sessions.messages.unsubscribe` перемикають підписки на події транскрипту / повідомлень для однієї сесії.
|
||||
- `sessions.preview` повертає обмежені попередні перегляди транскриптів для конкретних ключів сесій.
|
||||
- `sessions.resolve` розв’язує або канонізує ціль сесії.
|
||||
- `sessions.create` створює новий запис сесії.
|
||||
- `sessions.send` надсилає повідомлення в наявну сесію.
|
||||
- `sessions.steer` — це варіант interrupt-and-steer для активної сесії.
|
||||
- `sessions.abort` перериває активну роботу для сесії. Викликач може передати `key` плюс необов’язковий `runId` або передати лише `runId` для активних run, які Gateway може розв’язати до сесії.
|
||||
- `sessions.patch` оновлює метадані / перевизначення сесії та повідомляє розв’язану канонічну модель разом з ефективним `agentRuntime`.
|
||||
- `sessions.reset`, `sessions.delete` і `sessions.compact` виконують обслуговування сесій.
|
||||
- `sessions.get` повертає повний збережений рядок сесії.
|
||||
- Виконання чату й надалі використовує `chat.history`, `chat.send`, `chat.abort` і `chat.inject`. `chat.history` нормалізовано для відображення клієнтам UI: вбудовані directive tags вилучаються з видимого тексту, XML-навантаження викликів інструментів у plain-text (включно з `<tool_call>...</tool_call>`, `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>` і обрізаними блоками викликів інструментів) та витоки ASCII/full-width токенів керування моделлю вилучаються, суто silent-token рядки асистента, як-от точні `NO_REPLY` / `no_reply`, пропускаються, а завеликі рядки можуть замінюватися placeholders.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Спарювання пристроїв і токени пристроїв">
|
||||
- `device.pair.list` повертає очікувані та схвалені спарені пристрої.
|
||||
- `device.pair.list` повертає пристрої, що очікують, і схвалені спарені пристрої.
|
||||
- `device.pair.approve`, `device.pair.reject` і `device.pair.remove` керують записами спарювання пристроїв.
|
||||
- `device.token.rotate` ротує токен спареного пристрою в межах його схваленої ролі та області викликача.
|
||||
- `device.token.rotate` ротирує токен спареного пристрою в межах його схваленої ролі та області викликача.
|
||||
- `device.token.revoke` відкликає токен спареного пристрою в межах його схваленої ролі та області викликача.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Спарювання Node, invoke і очікувана робота">
|
||||
- `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` і `node.pair.verify` покривають спарювання вузлів і перевірку bootstrap.
|
||||
- `node.list` і `node.describe` повертають стан відомих/підключених вузлів.
|
||||
- `node.rename` оновлює мітку спареного вузла.
|
||||
- `node.invoke` пересилає команду підключеному вузлу.
|
||||
<Accordion title="Спарювання Node, виклик і робота в очікуванні">
|
||||
- `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` і `node.pair.verify` охоплюють спарювання node і перевірку bootstrap.
|
||||
- `node.list` і `node.describe` повертають відомий / підключений стан node.
|
||||
- `node.rename` оновлює мітку спареного node.
|
||||
- `node.invoke` пересилає команду до підключеного node.
|
||||
- `node.invoke.result` повертає результат для запиту invoke.
|
||||
- `node.event` переносить події, що походять від вузла, назад у gateway.
|
||||
- `node.canvas.capability.refresh` оновлює scoped canvas-capability tokens.
|
||||
- `node.pending.pull` і `node.pending.ack` — це API черги підключеного вузла.
|
||||
- `node.pending.enqueue` і `node.pending.drain` керують надійно збереженою очікуваною роботою для офлайн/відключених вузлів.
|
||||
- `node.event` переносить події, що походять від node, назад у gateway.
|
||||
- `node.canvas.capability.refresh` оновлює токени можливостей canvas з обмеженою областю.
|
||||
- `node.pending.pull` і `node.pending.ack` — це API черги підключеного node.
|
||||
- `node.pending.enqueue` і `node.pending.drain` керують сталою роботою в очікуванні для offline / відключених node.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Сімейства схвалень">
|
||||
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` і `exec.approval.resolve` покривають одноразові запити схвалення exec, а також пошук/повторне відтворення очікуваних схвалень.
|
||||
- `exec.approval.waitDecision` очікує на одне очікуване схвалення exec і повертає остаточне рішення (або `null` у разі timeout).
|
||||
- `exec.approvals.get` і `exec.approvals.set` керують знімками політики схвалення exec для gateway.
|
||||
- `exec.approvals.node.get` і `exec.approvals.node.set` керують локальною для вузла політикою схвалення exec через команди relay вузла.
|
||||
- `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` і `plugin.approval.resolve` покривають потоки схвалень, визначені plugin.
|
||||
- `exec.approval.request`, `exec.approval.get`, `exec.approval.list` і `exec.approval.resolve` охоплюють одноразові запити схвалення exec, а також пошук / відтворення схвалень, що очікують.
|
||||
- `exec.approval.waitDecision` очікує на одне схвалення exec, що очікує, і повертає остаточне рішення (або `null` у разі тайм-ауту).
|
||||
- `exec.approvals.get` і `exec.approvals.set` керують знімками політики схвалення exec gateway.
|
||||
- `exec.approvals.node.get` і `exec.approvals.node.set` керують локальною для node політикою схвалення exec через relay-команди node.
|
||||
- `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` і `plugin.approval.resolve` охоплюють потоки схвалення, визначені plugin.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Автоматизація, Skills та інструменти">
|
||||
- Автоматизація: `wake` планує негайну або під час наступного heartbeat інʼєкцію тексту wake; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` керують запланованою роботою.
|
||||
<Accordion title="Автоматизація, skills та інструменти">
|
||||
- Автоматизація: `wake` планує негайну або на наступний Heartbeat ін’єкцію wake-тексту; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` керують запланованою роботою.
|
||||
- Skills та інструменти: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`, `tools.invoke`.
|
||||
|
||||
</Accordion>
|
||||
@ -463,219 +458,198 @@ Broadcast-події WebSocket, які надсилає сервер, обмеж
|
||||
|
||||
### Поширені сімейства подій
|
||||
|
||||
- `chat`: оновлення чату UI, як-от `chat.inject` та інші події чату
|
||||
лише для транскрипту.
|
||||
- `session.message` і `session.tool`: оновлення транскрипту/потоку подій для
|
||||
підписаного сеансу.
|
||||
- `sessions.changed`: індекс сеансів або метадані змінено.
|
||||
- `chat`: оновлення чату UI, як-от `chat.inject`, та інші події чату лише з транскриптом.
|
||||
- `session.message` і `session.tool`: оновлення транскрипту / потоку подій для підписаної сесії.
|
||||
- `sessions.changed`: індекс сесій або метадані змінено.
|
||||
- `presence`: оновлення знімка присутності системи.
|
||||
- `tick`: періодична подія keepalive / liveness.
|
||||
- `health`: оновлення знімка стану gateway.
|
||||
- `heartbeat`: оновлення потоку подій heartbeat.
|
||||
- `cron`: подія зміни run/job cron.
|
||||
- `shutdown`: сповіщення про вимкнення gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: життєвий цикл спарювання вузлів.
|
||||
- `node.invoke.request`: трансляція запиту invoke вузла.
|
||||
- `health`: оновлення знімка справності gateway.
|
||||
- `heartbeat`: оновлення потоку подій Heartbeat.
|
||||
- `cron`: подія зміни run/job Cron.
|
||||
- `shutdown`: сповіщення про завершення роботи gateway.
|
||||
- `node.pair.requested` / `node.pair.resolved`: життєвий цикл спарювання node.
|
||||
- `node.invoke.request`: трансляція запиту invoke для node.
|
||||
- `device.pair.requested` / `device.pair.resolved`: життєвий цикл спареного пристрою.
|
||||
- `voicewake.changed`: конфігурацію тригерів wake-word змінено.
|
||||
- `voicewake.changed`: змінено конфігурацію тригерів wake-word.
|
||||
- `exec.approval.requested` / `exec.approval.resolved`: життєвий цикл схвалення exec.
|
||||
- `plugin.approval.requested` / `plugin.approval.resolved`: життєвий цикл схвалення plugin.
|
||||
|
||||
### Методи-помічники Node
|
||||
### Допоміжні методи Node
|
||||
|
||||
- Вузли можуть викликати `skills.bins`, щоб отримати поточний список виконуваних файлів Skills
|
||||
для перевірок auto-allow.
|
||||
- Nodes можуть викликати `skills.bins`, щоб отримати поточний список виконуваних файлів skills для перевірок auto-allow.
|
||||
|
||||
### Методи-помічники оператора
|
||||
### Допоміжні методи оператора
|
||||
|
||||
- Оператори можуть викликати `commands.list` (`operator.read`), щоб отримати runtime
|
||||
інвентар команд для агента.
|
||||
- `agentId` необов’язковий; пропустіть його, щоб прочитати стандартний робочий простір агента.
|
||||
- `scope` керує тим, на яку поверхню націлюється основний `name`:
|
||||
- Оператори можуть викликати `commands.list` (`operator.read`), щоб отримати інвентар команд часу виконання для агента.
|
||||
- `agentId` необов’язковий; опустіть його, щоб читати робочий простір агента за замовчуванням.
|
||||
- `scope` керує тим, на яку поверхню спрямовано основний `name`:
|
||||
- `text` повертає основний текстовий токен команди без початкового `/`
|
||||
- `native` і стандартний шлях `both` повертають native-імена з урахуванням провайдера,
|
||||
коли вони доступні
|
||||
- `textAliases` містить точні slash-аліаси, як-от `/model` і `/m`.
|
||||
- `nativeName` містить native-ім’я команди з урахуванням провайдера, коли воно існує.
|
||||
- `provider` необов’язковий і впливає лише на native-іменування та доступність native-команд Plugin.
|
||||
- `includeArgs=false` пропускає серіалізовані метадані аргументів у відповіді.
|
||||
- Оператори можуть викликати `tools.catalog` (`operator.read`), щоб отримати runtime-каталог інструментів для
|
||||
агента. Відповідь містить згруповані інструменти та метадані походження:
|
||||
- `native` і типовий шлях `both` повертають нативні імена з урахуванням провайдера, коли вони доступні
|
||||
- `textAliases` містить точні slash-псевдоніми, як-от `/model` і `/m`.
|
||||
- `nativeName` містить нативне ім’я команди з урахуванням провайдера, якщо воно існує.
|
||||
- `provider` необов’язковий і впливає лише на нативне іменування та доступність нативних команд plugin.
|
||||
- `includeArgs=false` вилучає серіалізовані метадані аргументів із відповіді.
|
||||
- Оператори можуть викликати `tools.catalog` (`operator.read`), щоб отримати каталог інструментів часу виконання для агента. Відповідь містить згруповані інструменти та метадані походження:
|
||||
- `source`: `core` або `plugin`
|
||||
- `pluginId`: власник Plugin, коли `source="plugin"`
|
||||
- `optional`: чи є інструмент Plugin необов’язковим
|
||||
- Оператори можуть викликати `tools.effective` (`operator.read`), щоб отримати runtime-ефективний
|
||||
інвентар інструментів для сесії.
|
||||
- `pluginId`: власник plugin, коли `source="plugin"`
|
||||
- `optional`: чи є інструмент plugin необов’язковим
|
||||
- Оператори можуть викликати `tools.effective` (`operator.read`), щоб отримати ефективний для часу виконання інвентар інструментів для сесії.
|
||||
- `sessionKey` обов’язковий.
|
||||
- Gateway виводить довірений runtime-контекст із сесії на серверному боці замість прийняття
|
||||
auth або контексту доставки, наданого викликачем.
|
||||
- Відповідь обмежена сесією та відображає те, що активна розмова може використовувати прямо зараз,
|
||||
включно з core, Plugin і channel-інструментами.
|
||||
- Оператори можуть викликати `tools.invoke` (`operator.write`), щоб викликати один доступний інструмент через
|
||||
той самий шлях політики Gateway, що й `/tools/invoke`.
|
||||
- `name` обов’язковий. `args`, `sessionKey`, `agentId`, `confirm` і
|
||||
`idempotencyKey` необов’язкові.
|
||||
- Якщо наявні і `sessionKey`, і `agentId`, визначений агент сесії має збігатися з
|
||||
`agentId`.
|
||||
- Відповідь є envelope для SDK з полями `ok`, `toolName`, необов’язковим `output` і типізованими
|
||||
`error`. Відмови через погодження або політику повертають `ok:false` у payload, а не
|
||||
обходять pipeline політики інструментів Gateway.
|
||||
- Оператори можуть викликати `skills.status` (`operator.read`), щоб отримати видимий
|
||||
інвентар Skills для агента.
|
||||
- `agentId` необов’язковий; пропустіть його, щоб прочитати стандартний робочий простір агента.
|
||||
- Відповідь містить eligibility, відсутні вимоги, перевірки конфігурації та
|
||||
очищені параметри встановлення без розкриття необроблених секретних значень.
|
||||
- Оператори можуть викликати `skills.search` і `skills.detail` (`operator.read`) для
|
||||
метаданих discovery у ClawHub.
|
||||
- Gateway виводить довірений контекст часу виконання із сесії на серверному боці замість приймання наданого викликачем контексту автентифікації або доставки.
|
||||
- Відповідь обмежена сесією й відображає те, що активна розмова може використовувати просто зараз, включно з основними інструментами, інструментами plugin і каналів.
|
||||
- Оператори можуть викликати `tools.invoke` (`operator.write`), щоб викликати один доступний інструмент через той самий шлях політики Gateway, що й `/tools/invoke`.
|
||||
- `name` обов’язковий. `args`, `sessionKey`, `agentId`, `confirm` і `idempotencyKey` необов’язкові.
|
||||
- Якщо присутні і `sessionKey`, і `agentId`, розв’язаний агент сесії має відповідати `agentId`.
|
||||
- Відповідь є конвертом, орієнтованим на SDK, з полями `ok`, `toolName`, необов’язковим `output` і типізованими полями `error`. Відмови через схвалення або політику повертають `ok:false` у корисному навантаженні, а не обходять конвеєр політики інструментів Gateway.
|
||||
- Оператори можуть викликати `skills.status` (`operator.read`), щоб отримати видимий інвентар skill для агента.
|
||||
- `agentId` необов’язковий; опустіть його, щоб читати робочий простір агента за замовчуванням.
|
||||
- Відповідь містить придатність, відсутні вимоги, перевірки конфігурації та санітизовані параметри встановлення без розкриття необроблених секретних значень.
|
||||
- Оператори можуть викликати `skills.search` і `skills.detail` (`operator.read`) для метаданих виявлення ClawHub.
|
||||
- Оператори можуть викликати `skills.install` (`operator.admin`) у двох режимах:
|
||||
- Режим ClawHub: `{ source: "clawhub", slug, version?, force? }` встановлює
|
||||
теку Skills у директорію `skills/` стандартного робочого простору агента.
|
||||
- Режим інсталятора Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }`
|
||||
запускає оголошену дію `metadata.openclaw.install` на хості Gateway.
|
||||
- Режим ClawHub: `{ source: "clawhub", slug, version?, force? }` встановлює папку skill у директорію `skills/` робочого простору агента за замовчуванням.
|
||||
- Режим інсталятора Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` запускає оголошену дію `metadata.openclaw.install` на хості Gateway.
|
||||
- Оператори можуть викликати `skills.update` (`operator.admin`) у двох режимах:
|
||||
- Режим ClawHub оновлює один відстежуваний slug або всі відстежувані встановлення ClawHub у
|
||||
стандартному робочому просторі агента.
|
||||
- Режим конфігурації патчить значення `skills.entries.<skillKey>`, як-от `enabled`,
|
||||
`apiKey` і `env`.
|
||||
- Режим ClawHub оновлює один відстежуваний slug або всі відстежувані встановлення ClawHub у робочому просторі агента за замовчуванням.
|
||||
- Режим конфігурації виправляє значення `skills.entries.<skillKey>`, як-от `enabled`, `apiKey` і `env`.
|
||||
|
||||
### Подання `models.list`
|
||||
|
||||
`models.list` приймає необов’язковий параметр `view`:
|
||||
|
||||
- Пропущено або `"default"`: поточна runtime-поведінка. Якщо `agents.defaults.models` налаштовано, відповідь є дозволеним каталогом; інакше відповідь є повним каталогом Gateway.
|
||||
- `"configured"`: поведінка розміру picker. Якщо `agents.defaults.models` налаштовано, він усе одно має пріоритет. Інакше відповідь використовує явні записи `models.providers.*.models`, повертаючись до повного каталогу лише тоді, коли немає жодних налаштованих рядків моделей.
|
||||
- `"all"`: повний каталог Gateway, оминаючи `agents.defaults.models`. Використовуйте це для діагностики та discovery UI, а не для звичайних picker моделей.
|
||||
- Опущено або `"default"`: поточна поведінка часу виконання. Якщо `agents.defaults.models` налаштовано, відповідь є дозволеним каталогом; інакше відповідь є повним каталогом Gateway.
|
||||
- `"configured"`: поведінка розміру picker. Якщо `agents.defaults.models` налаштовано, він усе одно має пріоритет. Інакше відповідь використовує явні записи `models.providers.*.models`, повертаючись до повного каталогу лише тоді, коли немає налаштованих рядків моделей.
|
||||
- `"all"`: повний каталог Gateway, в обхід `agents.defaults.models`. Використовуйте це для діагностики та UI виявлення, а не для звичайних picker моделей.
|
||||
|
||||
## Погодження exec
|
||||
## Схвалення виконання
|
||||
|
||||
- Коли exec-запит потребує погодження, Gateway транслює `exec.approval.requested`.
|
||||
- Операторські клієнти вирішують це, викликаючи `exec.approval.resolve` (потребує scope `operator.approvals`).
|
||||
- Коли запит на виконання потребує схвалення, Gateway транслює `exec.approval.requested`.
|
||||
- Операторські клієнти розв’язують це, викликаючи `exec.approval.resolve` (потребує scope `operator.approvals`).
|
||||
- Для `host=node` `exec.approval.request` має містити `systemRunPlan` (канонічні `argv`/`cwd`/`rawCommand`/метадані сесії). Запити без `systemRunPlan` відхиляються.
|
||||
- Після погодження переслані виклики `node.invoke system.run` повторно використовують цей канонічний
|
||||
`systemRunPlan` як authoritative контекст команди/cwd/сесії.
|
||||
- Якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або
|
||||
`sessionKey` між підготовкою та фінальним погодженим forward `system.run`, Gateway
|
||||
відхиляє запуск замість того, щоб довіряти зміненому payload.
|
||||
- Після схвалення перенаправлені виклики `node.invoke system.run` повторно використовують цей канонічний `systemRunPlan` як авторитетний контекст команди/cwd/сесії.
|
||||
- Якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або `sessionKey` між підготовкою та фінальним схваленим перенаправленням `system.run`, Gateway відхиляє запуск замість того, щоб довіряти зміненому корисному навантаженню.
|
||||
|
||||
## Fallback доставки агентом
|
||||
## Резервний варіант доставки агента
|
||||
|
||||
- Запити `agent` можуть містити `deliver=true`, щоб запросити вихідну доставку.
|
||||
- `bestEffortDeliver=false` зберігає сувору поведінку: нерозв’язані або лише внутрішні цілі доставки повертають `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` дозволяє fallback до виконання лише в сесії, коли неможливо визначити зовнішній доставний маршрут (наприклад, внутрішні/webchat-сесії або неоднозначні багатоканальні конфігурації).
|
||||
- Запити `agent` можуть містити `deliver=true`, щоб запитати вихідну доставку.
|
||||
- `bestEffortDeliver=false` зберігає строгу поведінку: нерозв’язані або лише внутрішні цілі доставки повертають `INVALID_REQUEST`.
|
||||
- `bestEffortDeliver=true` дозволяє резервний перехід до виконання лише в сесії, коли не вдається розв’язати зовнішній маршрут доставки (наприклад, внутрішні/вебчат-сесії або неоднозначні багатоканальні конфігурації).
|
||||
|
||||
## Версіонування
|
||||
|
||||
- `PROTOCOL_VERSION` міститься в `src/gateway/protocol/schema/protocol-schemas.ts`.
|
||||
- `PROTOCOL_VERSION` розміщено в `src/gateway/protocol/schema/protocol-schemas.ts`.
|
||||
- Клієнти надсилають `minProtocol` + `maxProtocol`; сервер відхиляє невідповідності.
|
||||
- Схеми + моделі генеруються з визначень TypeBox:
|
||||
- `pnpm protocol:gen`
|
||||
- `pnpm protocol:gen:swift`
|
||||
- `pnpm protocol:check`
|
||||
|
||||
### Константи клієнта
|
||||
### Клієнтські константи
|
||||
|
||||
Референсний клієнт у `src/gateway/client.ts` використовує ці стандартні значення. Значення
|
||||
стабільні в protocol v3 і є очікуваною baseline для сторонніх клієнтів.
|
||||
Еталонний клієнт у `src/gateway/client.ts` використовує ці значення за замовчуванням. Значення стабільні в межах protocol v3 і є очікуваною базою для сторонніх клієнтів.
|
||||
|
||||
| Константа | Стандартне значення | Джерело |
|
||||
| Константа | За замовчуванням | Джерело |
|
||||
| ----------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` |
|
||||
| Тайм-аут запиту (на RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) |
|
||||
| Тайм-аут preauth / connect-challenge | `15_000` ms | `src/gateway/handshake-timeouts.ts` (config/env може збільшити спільний server/client budget) |
|
||||
| Початковий backoff повторного підключення | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
|
||||
| Максимальний backoff повторного підключення | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
|
||||
| Fast-retry clamp після закриття device-token | `250` ms | `src/gateway/client.ts` |
|
||||
| Grace force-stop перед `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
|
||||
| Стандартний тайм-аут `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
|
||||
| Стандартний інтервал tick (до `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
|
||||
| Тайм-аут preauth / connect-challenge | `15_000` ms | `src/gateway/handshake-timeouts.ts` (config/env можуть збільшити парний бюджет сервера/клієнта) |
|
||||
| Початкова затримка повторного підключення | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) |
|
||||
| Максимальна затримка повторного підключення | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) |
|
||||
| Обмеження швидкої повторної спроби після закриття device-token | `250` ms | `src/gateway/client.ts` |
|
||||
| Пільговий час force-stop перед `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` |
|
||||
| Типовий тайм-аут `stopAndWait()` | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` |
|
||||
| Типовий інтервал tick (до `hello-ok`) | `30_000` ms | `src/gateway/client.ts` |
|
||||
| Закриття через tick-timeout | code `4000`, коли тиша перевищує `tickIntervalMs * 2` | `src/gateway/client.ts` |
|
||||
| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` |
|
||||
|
||||
Сервер оголошує ефективні `policy.tickIntervalMs`, `policy.maxPayload`
|
||||
і `policy.maxBufferedBytes` у `hello-ok`; клієнти мають дотримуватися цих значень
|
||||
замість стандартних значень до handshake.
|
||||
Сервер оголошує ефективні `policy.tickIntervalMs`, `policy.maxPayload` і `policy.maxBufferedBytes` у `hello-ok`; клієнти мають дотримуватися цих значень, а не значень за замовчуванням до handshake.
|
||||
|
||||
## Auth
|
||||
## Автентифікація
|
||||
|
||||
- Автентифікація Gateway зі спільним секретом використовує `connect.params.auth.token` або
|
||||
`connect.params.auth.password`, залежно від налаштованого режиму автентифікації.
|
||||
- Режими з ідентичністю, як-от Tailscale Serve
|
||||
(`gateway.auth.allowTailscale: true`) або не-loopback
|
||||
`gateway.auth.mode: "trusted-proxy"`, задовольняють перевірку автентифікації підключення за
|
||||
заголовками запиту замість `connect.params.auth.*`.
|
||||
- Private-ingress `gateway.auth.mode: "none"` повністю пропускає автентифікацію підключення зі спільним секретом; не відкривайте цей режим для публічного/ненадійного ingress.
|
||||
- Після сполучення Gateway видає **токен пристрою**, обмежений роллю підключення
|
||||
+ scopes. Він повертається в `hello-ok.auth.deviceToken` і має бути
|
||||
збережений клієнтом для майбутніх підключень.
|
||||
`gateway.auth.mode: "trusted-proxy"`, проходять перевірку автентифікації підключення з
|
||||
заголовків запиту замість `connect.params.auth.*`.
|
||||
- Приватний вхід `gateway.auth.mode: "none"` повністю пропускає автентифікацію підключення
|
||||
зі спільним секретом; не відкривайте цей режим на публічному або недовіреному вході.
|
||||
- Після спарювання Gateway видає **токен пристрою**, обмежений роллю підключення
|
||||
+ областями доступу. Він повертається в `hello-ok.auth.deviceToken`, і клієнт має
|
||||
зберігати його для майбутніх підключень.
|
||||
- Клієнти мають зберігати основний `hello-ok.auth.deviceToken` після будь-якого
|
||||
успішного підключення.
|
||||
- Повторне підключення з цим **збереженим** токеном пристрою також має повторно використовувати збережений
|
||||
набір схвалених scopes для цього токена. Це зберігає доступ read/probe/status,
|
||||
який уже було надано, і запобігає непомітному звуженню повторних підключень до
|
||||
вужчого неявного scope лише для адміністратора.
|
||||
- Клієнтське складання автентифікації підключення (`selectConnectAuth` у
|
||||
- Повторне підключення з цим **збереженим** токеном пристрою також має повторно використовувати
|
||||
збережений набір схвалених областей доступу для цього токена. Це зберігає доступ
|
||||
до читання/зондування/статусу, який уже було надано, і запобігає непомітному
|
||||
звуженню повторних підключень до неявної області доступу лише для адміністратора.
|
||||
- Складання автентифікації підключення на боці клієнта (`selectConnectAuth` у
|
||||
`src/gateway/client.ts`):
|
||||
- `auth.password` є ортогональним і завжди пересилається, коли його задано.
|
||||
- `auth.password` є ортогональним і завжди передається, коли заданий.
|
||||
- `auth.token` заповнюється в порядку пріоритету: спочатку явний спільний токен,
|
||||
потім явний `deviceToken`, потім збережений токен для окремого пристрою (за ключем
|
||||
`deviceId` + `role`).
|
||||
- `auth.bootstrapToken` надсилається лише тоді, коли жоден із наведених вище варіантів не визначив
|
||||
`auth.token`. Спільний токен або будь-який визначений токен пристрою пригнічує його.
|
||||
- Автоматичне підвищення збереженого токена пристрою під час одноразової
|
||||
повторної спроби `AUTH_TOKEN_MISMATCH` дозволене **лише для довірених кінцевих точок** —
|
||||
потім явний `deviceToken`, потім збережений токен для окремого пристрою
|
||||
(з ключем за `deviceId` + `role`).
|
||||
- `auth.bootstrapToken` надсилається лише тоді, коли жоден із наведених вище варіантів
|
||||
не визначив `auth.token`. Спільний токен або будь-який визначений токен пристрою
|
||||
пригнічує його.
|
||||
- Автопросування збереженого токена пристрою під час одноразової повторної спроби
|
||||
`AUTH_TOKEN_MISMATCH` дозволене **лише для довірених кінцевих точок** —
|
||||
loopback або `wss://` із закріпленим `tlsFingerprint`. Публічний `wss://`
|
||||
без закріплення не підходить.
|
||||
- Додаткові записи `hello-ok.auth.deviceTokens` є токенами передавання bootstrap.
|
||||
Зберігайте їх лише тоді, коли підключення використовувало bootstrap-автентифікацію на довіреному транспорті,
|
||||
як-от `wss://` або loopback/локальне сполучення.
|
||||
- Якщо клієнт надає **явний** `deviceToken` або явні `scopes`, цей
|
||||
запитаний викликачем набір scopes залишається авторитетним; кешовані scopes використовуються повторно лише
|
||||
тоді, коли клієнт повторно використовує збережений токен для окремого пристрою.
|
||||
Зберігайте їх лише тоді, коли підключення використовувало bootstrap-автентифікацію
|
||||
на довіреному транспорті, як-от `wss://` або loopback/локальне спарювання.
|
||||
- Якщо клієнт надає **явний** `deviceToken` або явні `scopes`, цей запитаний
|
||||
викликачем набір областей доступу залишається авторитетним; кешовані області доступу
|
||||
повторно використовуються лише тоді, коли клієнт повторно використовує збережений
|
||||
токен для окремого пристрою.
|
||||
- Токени пристроїв можна ротувати/відкликати через `device.token.rotate` і
|
||||
`device.token.revoke` (потрібен scope `operator.pairing`).
|
||||
- `device.token.rotate` повертає метадані ротації. Він віддзеркалює replacement
|
||||
bearer token лише для викликів із того самого пристрою, які вже автентифіковані цим
|
||||
токеном пристрою, щоб клієнти лише з токеном могли зберегти заміну перед
|
||||
повторним підключенням. Ротації shared/admin не віддзеркалюють bearer token.
|
||||
`device.token.revoke` (потрібна область доступу `operator.pairing`).
|
||||
- `device.token.rotate` повертає метадані ротації. Він відлунює замінний
|
||||
bearer-токен лише для викликів із того самого пристрою, які вже автентифіковані
|
||||
цим токеном пристрою, щоб клієнти лише з токеном могли зберегти свою заміну перед
|
||||
повторним підключенням. Ротації через спільний/адміністративний доступ не відлунюють bearer-токен.
|
||||
- Видача, ротація та відкликання токенів залишаються обмеженими схваленим набором ролей,
|
||||
записаним у записі сполучення цього пристрою; зміна токена не може розширити або
|
||||
націлитися на роль пристрою, яку ніколи не надавало схвалення сполучення.
|
||||
- Для токен-сесій сполучених пристроїв керування пристроями є self-scoped, якщо
|
||||
записаним у записі спарювання цього пристрою; мутація токена не може розширити або
|
||||
націлити роль пристрою, яку схвалення спарювання ніколи не надавало.
|
||||
- Для сеансів токенів спарених пристроїв керування пристроями є самообмеженим, якщо
|
||||
викликач також не має `operator.admin`: викликачі без прав адміністратора можуть видаляти/відкликати/ротувати
|
||||
лише запис **власного** пристрою.
|
||||
- `device.token.rotate` і `device.token.revoke` також перевіряють цільовий набір scopes токена
|
||||
оператора щодо поточних scopes сесії викликача. Викликачі без прав адміністратора
|
||||
не можуть ротувати або відкликати ширший токен оператора, ніж той, який вони вже мають.
|
||||
- `device.token.rotate` і `device.token.revoke` також перевіряють набір областей доступу
|
||||
цільового токена оператора щодо поточних областей доступу сеансу викликача. Викликачі
|
||||
без прав адміністратора не можуть ротувати або відкликати ширший токен оператора,
|
||||
ніж той, який вони вже мають.
|
||||
- Помилки автентифікації містять `error.details.code` плюс підказки для відновлення:
|
||||
- `error.details.canRetryWithDeviceToken` (boolean)
|
||||
- `error.details.canRetryWithDeviceToken` (булеве значення)
|
||||
- `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`)
|
||||
- Поведінка клієнта для `AUTH_TOKEN_MISMATCH`:
|
||||
- Довірені клієнти можуть виконати одну обмежену повторну спробу з кешованим токеном для окремого пристрою.
|
||||
- Якщо ця повторна спроба зазнає невдачі, клієнти мають припинити автоматичні цикли повторного підключення та показати оператору вказівки щодо дій.
|
||||
- Якщо ця повторна спроба зазнає невдачі, клієнти мають зупинити автоматичні цикли повторного підключення
|
||||
і показати оператору вказівки щодо дій.
|
||||
|
||||
## Ідентичність пристрою + сполучення
|
||||
## Ідентичність пристрою + спарювання
|
||||
|
||||
- Nodes мають містити стабільну ідентичність пристрою (`device.id`), отриману з
|
||||
- Вузли мають містити стабільну ідентичність пристрою (`device.id`), похідну від
|
||||
відбитка пари ключів.
|
||||
- Gateways видають токени для кожного пристрою + ролі.
|
||||
- Для нових ідентифікаторів пристроїв потрібні схвалення сполучення, якщо не ввімкнено локальне автоматичне схвалення.
|
||||
- Автоматичне схвалення сполучення зосереджене на прямих підключеннях local loopback.
|
||||
- OpenClaw також має вузький backend/container-local шлях self-connect для
|
||||
- Екземпляри Gateway видають токени для кожного пристрою + ролі.
|
||||
- Схвалення спарювання потрібні для нових ідентифікаторів пристроїв, якщо локальне автосхвалення
|
||||
не ввімкнено.
|
||||
- Автосхвалення спарювання зосереджене на прямих підключеннях через local loopback.
|
||||
- OpenClaw також має вузький шлях самопідключення в межах бекенда/контейнера для
|
||||
довірених допоміжних потоків зі спільним секретом.
|
||||
- Підключення з same-host tailnet або LAN все одно розглядаються як віддалені для сполучення та
|
||||
- Підключення через tailnet або LAN на тому самому хості все одно вважаються віддаленими для спарювання і
|
||||
потребують схвалення.
|
||||
- WS-клієнти зазвичай додають ідентичність `device` під час `connect` (operator +
|
||||
node). Єдині винятки оператора без пристрою — явні довірені шляхи:
|
||||
- `gateway.controlUi.allowInsecureAuth=true` для localhost-only insecure HTTP-сумісності.
|
||||
- успішна автентифікація operator Control UI з `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (break-glass, серйозне зниження безпеки).
|
||||
- direct-loopback `gateway-client` backend RPCs, автентифіковані спільним
|
||||
токеном/паролем gateway.
|
||||
- WS-клієнти зазвичай включають ідентичність `device` під час `connect` (оператор +
|
||||
вузол). Єдині винятки оператора без пристрою — явні шляхи довіри:
|
||||
- `gateway.controlUi.allowInsecureAuth=true` для сумісності з небезпечним HTTP лише на localhost.
|
||||
- успішна автентифікація оператора Control UI через `gateway.auth.mode: "trusted-proxy"`.
|
||||
- `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (аварійний доступ, суттєве зниження безпеки).
|
||||
- прямі loopback RPC-запити бекенда `gateway-client`, автентифіковані спільним
|
||||
токеном/паролем Gateway.
|
||||
- Усі підключення мають підписувати наданий сервером nonce `connect.challenge`.
|
||||
|
||||
### Діагностика міграції автентифікації пристрою
|
||||
### Діагностика міграції автентифікації пристроїв
|
||||
|
||||
Для застарілих клієнтів, які все ще використовують поведінку підписування до challenge, `connect` тепер повертає
|
||||
Для застарілих клієнтів, які досі використовують поведінку підписування до challenge, `connect` тепер повертає
|
||||
коди деталей `DEVICE_AUTH_*` у `error.details.code` зі стабільним `error.details.reason`.
|
||||
|
||||
Поширені помилки міграції:
|
||||
@ -683,35 +657,35 @@ Broadcast-події WebSocket, які надсилає сервер, обмеж
|
||||
| Повідомлення | details.code | details.reason | Значення |
|
||||
| --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- |
|
||||
| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Клієнт пропустив `device.nonce` (або надіслав порожнє значення). |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Клієнт підписав застарілий/неправильний nonce. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Payload підпису не відповідає payload v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Підписана позначка часу поза дозволеним зсувом. |
|
||||
| `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Клієнт підписав із застарілим/неправильним nonce. |
|
||||
| `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Корисне навантаження підпису не відповідає корисному навантаженню v2. |
|
||||
| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Підписана часова позначка поза дозволеним відхиленням. |
|
||||
| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` не відповідає відбитку публічного ключа. |
|
||||
| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Формат/канонікалізація публічного ключа зазнали невдачі. |
|
||||
|
||||
Ціль міграції:
|
||||
|
||||
- Завжди чекайте на `connect.challenge`.
|
||||
- Підписуйте payload v2, що містить nonce сервера.
|
||||
- Підписуйте корисне навантаження v2, яке містить nonce сервера.
|
||||
- Надсилайте той самий nonce у `connect.params.device.nonce`.
|
||||
- Бажаний payload підпису — `v3`, який прив’язує `platform` і `deviceFamily`
|
||||
на додачу до полів device/client/role/scopes/token/nonce.
|
||||
- Застарілі підписи `v2` залишаються прийнятими для сумісності, але pinning метаданих
|
||||
сполученого пристрою все ще керує політикою команд під час повторного підключення.
|
||||
- Бажане корисне навантаження підпису — `v3`, яке прив’язує `platform` і `deviceFamily`
|
||||
на додачу до полів пристрою/клієнта/ролі/областей доступу/токена/nonce.
|
||||
- Застарілі підписи `v2` залишаються прийнятими для сумісності, але закріплення
|
||||
метаданих спареного пристрою все одно керує політикою команд під час повторного підключення.
|
||||
|
||||
## TLS + закріплення
|
||||
|
||||
- TLS підтримується для WS-підключень.
|
||||
- Клієнти можуть опційно закріпити відбиток сертифіката gateway (див. конфігурацію `gateway.tls`
|
||||
- Клієнти можуть необов’язково закріпити відбиток сертифіката Gateway (див. конфігурацію `gateway.tls`
|
||||
плюс `gateway.remote.tlsFingerprint` або CLI `--tls-fingerprint`).
|
||||
|
||||
## Scope
|
||||
## Область
|
||||
|
||||
Цей протокол відкриває **повний API gateway** (status, channels, models, chat,
|
||||
agent, sessions, nodes, approvals тощо). Точна поверхня визначена
|
||||
схемами TypeBox у `src/gateway/protocol/schema.ts`.
|
||||
Цей протокол відкриває **повний API Gateway** (статус, канали, моделі, чат,
|
||||
агент, сеанси, вузли, схвалення тощо). Точну поверхню визначають
|
||||
схеми TypeBox у `src/gateway/protocol/schema.ts`.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Протокол Bridge](/uk/gateway/bridge-protocol)
|
||||
- [Runbook Gateway](/uk/gateway)
|
||||
- [Операційний посібник Gateway](/uk/gateway)
|
||||
|
||||
@ -2,28 +2,28 @@
|
||||
read_when:
|
||||
- Оновлення OpenClaw
|
||||
- Щось ламається після оновлення
|
||||
summary: Безпечне оновлення OpenClaw (глобальне встановлення або вихідний код), а також стратегія відкату
|
||||
summary: Безпечне оновлення OpenClaw (глобальне встановлення або з вихідного коду), а також стратегія відкату
|
||||
title: Оновлення
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T14:31:28Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-01T08:51:54Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 17d4839002b153976e014e0eefcb44f92dcb9bb45b81bf30efb1e8e8c0f30ec3
|
||||
source_hash: 98631ce432a28af244ec22ce0cf4a23ded356dd93e9c154f502347683eef52d1
|
||||
source_path: install/updating.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Підтримуйте OpenClaw в актуальному стані.
|
||||
|
||||
## Рекомендовано: `openclaw update`
|
||||
|
||||
Найшвидший спосіб оновлення. Він визначає тип вашого встановлення (npm або git), отримує найновішу версію, запускає `openclaw doctor` і перезапускає Gateway.
|
||||
Найшвидший спосіб оновлення. Він визначає тип встановлення (npm або git), отримує найновішу версію, запускає `openclaw doctor` і перезапускає Gateway.
|
||||
|
||||
```bash
|
||||
openclaw update
|
||||
```
|
||||
|
||||
Щоб перемкнути канал або вибрати конкретну версію:
|
||||
Щоб перемикати канали або вибрати конкретну версію:
|
||||
|
||||
```bash
|
||||
openclaw update --channel beta
|
||||
@ -32,13 +32,17 @@ openclaw update --tag main
|
||||
openclaw update --dry-run # попередній перегляд без застосування
|
||||
```
|
||||
|
||||
`--channel beta` надає перевагу beta, але середовище виконання повертається до stable/latest, якщо тег beta відсутній або старіший за останній stable-реліз. Використовуйте `--tag beta`, якщо вам потрібен сирий npm dist-tag beta для одноразового оновлення пакета.
|
||||
`--channel beta` надає перевагу beta, але середовище виконання повертається до stable/latest, коли
|
||||
тег beta відсутній або старіший за найновіший стабільний реліз. Використовуйте `--tag beta`,
|
||||
якщо вам потрібен необроблений npm beta dist-tag для одноразового оновлення пакета.
|
||||
|
||||
Див. [Канали розробки](/uk/install/development-channels) щодо семантики каналів.
|
||||
Див. [Канали розробки](/uk/install/development-channels), щоб дізнатися про семантику каналів.
|
||||
|
||||
## Перемикання між встановленнями npm і git
|
||||
|
||||
Використовуйте канали, якщо хочете змінити тип встановлення. Засіб оновлення зберігає ваш стан, конфігурацію, облікові дані та робочий простір у `~/.openclaw`; він змінює лише те, яке встановлення коду OpenClaw використовують CLI і Gateway.
|
||||
Використовуйте канали, коли хочете змінити тип встановлення. Засіб оновлення зберігає ваші
|
||||
стан, конфігурацію, облікові дані та робочий простір у `~/.openclaw`; він змінює лише те,
|
||||
яке встановлення коду OpenClaw використовують CLI і Gateway.
|
||||
|
||||
```bash
|
||||
# встановлення npm-пакета -> редагований git checkout
|
||||
@ -55,7 +59,10 @@ openclaw update --channel dev --dry-run
|
||||
openclaw update --channel stable --dry-run
|
||||
```
|
||||
|
||||
Канал `dev` гарантує git checkout, збирає його та встановлює глобальний CLI з цього checkout. Канали `stable` і `beta` використовують встановлення пакетів. Якщо Gateway уже встановлено, `openclaw update` оновлює метадані служби та перезапускає її, якщо ви не передасте `--no-restart`.
|
||||
Канал `dev` забезпечує git checkout, збирає його та встановлює глобальний CLI
|
||||
з цього checkout. Канали `stable` і `beta` використовують пакетні встановлення. Якщо
|
||||
Gateway уже встановлено, `openclaw update` оновлює метадані сервісу
|
||||
та перезапускає його, якщо ви не передали `--no-restart`.
|
||||
|
||||
## Альтернатива: повторно запустіть інсталятор
|
||||
|
||||
@ -63,15 +70,19 @@ openclaw update --channel stable --dry-run
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash
|
||||
```
|
||||
|
||||
Додайте `--no-onboard`, щоб пропустити початкове налаштування. Щоб примусово вибрати конкретний тип встановлення через інсталятор, передайте `--install-method git --no-onboard` або `--install-method npm --no-onboard`.
|
||||
Додайте `--no-onboard`, щоб пропустити onboarding. Щоб примусово вибрати конкретний тип встановлення через
|
||||
інсталятор, передайте `--install-method git --no-onboard` або
|
||||
`--install-method npm --no-onboard`.
|
||||
|
||||
Якщо `openclaw update` завершується помилкою після етапу встановлення npm-пакета, повторно запустіть інсталятор. Інсталятор не викликає старий засіб оновлення; він напряму запускає глобальне встановлення пакета і може відновити частково оновлене встановлення npm.
|
||||
Якщо `openclaw update` завершується помилкою після етапу встановлення npm-пакета, повторно запустіть
|
||||
інсталятор. Інсталятор не викликає старий засіб оновлення; він напряму запускає глобальне
|
||||
встановлення пакета й може відновити частково оновлене npm-встановлення.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
|
||||
```
|
||||
|
||||
Щоб зафіксувати відновлення на конкретній версії або dist-tag, додайте `--version`:
|
||||
Щоб закріпити відновлення за конкретною версією або dist-tag, додайте `--version`:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
|
||||
@ -83,7 +94,13 @@ curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm --ve
|
||||
npm i -g openclaw@latest
|
||||
```
|
||||
|
||||
Коли `openclaw update` керує глобальним встановленням npm, він спочатку встановлює цільову версію в тимчасовий npm prefix, перевіряє інвентар запакованого `dist`, а потім підміняє чисте дерево пакета у справжньому глобальному prefix. Це запобігає накладанню нового пакета npm поверх застарілих файлів зі старого пакета. Якщо команда встановлення завершується помилкою, OpenClaw повторює спробу один раз із `--omit=optional`. Така повторна спроба допомагає на хостах, де необов’язкові нативні залежності не можуть бути скомпільовані, водночас зберігаючи початкову помилку видимою, якщо резервна спроба також завершується невдачею.
|
||||
Коли `openclaw update` керує глобальним npm-встановленням, він спочатку встановлює ціль у
|
||||
тимчасовий npm prefix, перевіряє інвентар упакованого `dist`, а потім замінює
|
||||
чисте дерево пакета в реальному глобальному prefix. Це запобігає накладанню npm
|
||||
нового пакета на застарілі файли зі старого пакета. Якщо команда встановлення завершується помилкою,
|
||||
OpenClaw повторює спробу один раз із `--omit=optional`. Ця повторна спроба допомагає хостам, де нативні
|
||||
необов’язкові залежності не можуть скомпілюватися, водночас зберігаючи видимою початкову помилку,
|
||||
якщо резервний варіант також завершується помилкою.
|
||||
|
||||
```bash
|
||||
pnpm add -g openclaw@latest
|
||||
@ -97,43 +114,43 @@ bun add -g openclaw@latest
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Дерево пакетів лише для читання">
|
||||
OpenClaw розглядає запаковані глобальні встановлення як доступні лише для читання під час виконання, навіть якщо каталог глобального пакета доступний для запису поточному користувачеві. Залежності середовища виконання вбудованих Plugin розміщуються в доступному для запису каталозі середовища виконання замість зміни дерева пакета. Це не дає `openclaw update` конфліктувати з запущеним Gateway або локальним агентом, який відновлює залежності Plugin під час того самого встановлення.
|
||||
OpenClaw розглядає упаковані глобальні встановлення як такі, що під час виконання доступні лише для читання, навіть коли глобальний каталог пакета доступний для запису поточному користувачу. Залежності середовища виконання вбудованих плагінів розміщуються в доступному для запису каталозі середовища виконання замість зміни дерева пакета. Це не дає `openclaw update` конфліктувати із запущеним Gateway або локальним агентом, який відновлює залежності плагінів під час того самого встановлення.
|
||||
|
||||
Деякі конфігурації npm у Linux встановлюють глобальні пакети в каталоги, що належать root, наприклад `/usr/lib/node_modules/openclaw`. OpenClaw підтримує таку схему через той самий зовнішній шлях розміщення.
|
||||
Деякі конфігурації npm у Linux встановлюють глобальні пакети в каталоги, що належать root, наприклад `/usr/lib/node_modules/openclaw`. OpenClaw підтримує таку структуру через той самий зовнішній шлях staging.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Посилені модулі systemd">
|
||||
Вкажіть доступний для запису каталог staging, який включено до `ReadWritePaths`:
|
||||
<Accordion title="Посилені systemd units">
|
||||
Задайте доступний для запису staging-каталог, який включено до `ReadWritePaths`:
|
||||
|
||||
```ini
|
||||
Environment=OPENCLAW_PLUGIN_STAGE_DIR=/var/lib/openclaw/plugin-runtime-deps
|
||||
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
|
||||
```
|
||||
|
||||
`OPENCLAW_PLUGIN_STAGE_DIR` також приймає список шляхів. OpenClaw розв’язує залежності середовища виконання вбудованих Plugin зліва направо в межах перелічених коренів, розглядає попередні корені як попередньо встановлені шари лише для читання та встановлює або відновлює лише у фінальний корінь із доступом на запис:
|
||||
`OPENCLAW_PLUGIN_STAGE_DIR` також приймає список шляхів. OpenClaw розв’язує залежності середовища виконання вбудованих плагінів зліва направо по перелічених коренях, розглядає попередні корені як встановлені заздалегідь шари лише для читання, а встановлює або відновлює лише в останній доступний для запису корінь:
|
||||
|
||||
```ini
|
||||
Environment=OPENCLAW_PLUGIN_STAGE_DIR=/opt/openclaw/plugin-runtime-deps:/var/lib/openclaw/plugin-runtime-deps
|
||||
ReadWritePaths=/var/lib/openclaw /home/openclaw/.openclaw /tmp
|
||||
```
|
||||
|
||||
Якщо `OPENCLAW_PLUGIN_STAGE_DIR` не задано, OpenClaw використовує `$STATE_DIRECTORY`, коли його надає systemd, а потім повертається до `~/.openclaw/plugin-runtime-deps`. Крок відновлення розглядає цей staging як локальний корінь пакета, що належить OpenClaw, і ігнорує npm prefix користувача та глобальні налаштування, тому конфігурація npm для глобального встановлення не перенаправляє залежності середовища виконання вбудованих Plugin до `~/node_modules` або дерева глобального пакета.
|
||||
Якщо `OPENCLAW_PLUGIN_STAGE_DIR` не задано, OpenClaw використовує `$STATE_DIRECTORY`, коли systemd його надає, а потім повертається до `~/.openclaw/plugin-runtime-deps`. Крок відновлення розглядає цей staging як локальний корінь пакетів, що належить OpenClaw, і ігнорує користувацький npm prefix та глобальні налаштування, тому npm-конфігурація глобального встановлення не перенаправляє залежності вбудованих плагінів у `~/node_modules` або глобальне дерево пакета.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Попередня перевірка вільного місця на диску">
|
||||
Перед оновленнями пакета та відновленням залежностей середовища виконання OpenClaw намагається виконати перевірку вільного місця для цільового тому в режимі best-effort. Нестача місця спричиняє попередження із перевіреним шляхом, але не блокує оновлення, оскільки файлові квоти, знімки та мережеві томи можуть змінитися після перевірки. Фактичне встановлення npm, копіювання та перевірка після встановлення залишаються авторитетними.
|
||||
<Accordion title="Попередня перевірка місця на диску">
|
||||
Перед оновленнями пакетів і відновленням вбудованих залежностей середовища виконання OpenClaw намагається виконати best-effort перевірку місця на диску для цільового тому. Недостатній обсяг місця створює попередження з перевіреним шляхом, але не блокує оновлення, оскільки файлові квоти, snapshots і мережеві томи можуть змінитися після перевірки. Фактичне встановлення npm, копіювання та перевірка після встановлення залишаються авторитетними.
|
||||
</Accordion>
|
||||
<Accordion title="Залежності середовища виконання вбудованих Plugin">
|
||||
Запаковані встановлення зберігають залежності середовища виконання вбудованих Plugin поза деревом пакета лише для читання. Під час запуску та під час `openclaw doctor --fix` OpenClaw відновлює залежності середовища виконання лише для вбудованих Plugin, які активні в конфігурації, активні через застарілу конфігурацію каналу або ввімкнені типовим значенням у вбудованому маніфесті. Сам по собі збережений стан автентифікації каналу не запускає відновлення залежностей середовища виконання під час запуску Gateway.
|
||||
<Accordion title="Залежності середовища виконання вбудованих плагінів">
|
||||
Упаковані встановлення тримають залежності середовища виконання вбудованих плагінів поза деревом пакета лише для читання. Під час запуску та під час `openclaw doctor --fix` OpenClaw відновлює залежності середовища виконання лише для вбудованих плагінів, які активні в конфігурації, активні через застарілу конфігурацію каналу або ввімкнені стандартним значенням їхнього вбудованого manifest. Сам лише збережений стан автентифікації каналу не запускає відновлення залежностей середовища виконання під час запуску Gateway.
|
||||
|
||||
Явне вимкнення має пріоритет. Для вимкненого Plugin або каналу його залежності середовища виконання не відновлюються лише тому, що він існує в пакеті. Зовнішні Plugin і користувацькі шляхи завантаження, як і раніше, використовують `openclaw plugins install` або `openclaw plugins update`.
|
||||
Явне вимкнення має пріоритет. Вимкнений плагін або канал не отримує відновлення своїх залежностей середовища виконання лише тому, що він існує в пакеті. Зовнішні плагіни та користувацькі шляхи завантаження й надалі використовують `openclaw plugins install` або `openclaw plugins update`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Автооновлювач
|
||||
## Автоматичний засіб оновлення
|
||||
|
||||
Автооновлювач вимкнено за замовчуванням. Увімкніть його в `~/.openclaw/openclaw.json`:
|
||||
Автоматичний засіб оновлення вимкнено за замовчуванням. Увімкніть його в `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -149,14 +166,21 @@ bun add -g openclaw@latest
|
||||
}
|
||||
```
|
||||
|
||||
| Канал | Поведінка |
|
||||
| ------ | -------------------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | Очікує `stableDelayHours`, а потім застосовує з детермінованим jitter у межах `stableJitterHours` (поетапне розгортання). |
|
||||
| `beta` | Перевіряє кожні `betaCheckIntervalHours` (типово: щогодини) і застосовує негайно. |
|
||||
| `dev` | Автоматичне застосування відсутнє. Використовуйте `openclaw update` вручну. |
|
||||
| Канал | Поведінка |
|
||||
| -------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| `stable` | Чекає `stableDelayHours`, потім застосовує з детермінованим jitter у межах `stableJitterHours` (поступове розгортання). |
|
||||
| `beta` | Перевіряє кожні `betaCheckIntervalHours` (за замовчуванням: щогодини) і застосовує негайно. |
|
||||
| `dev` | Без автоматичного застосування. Використовуйте `openclaw update` вручну. |
|
||||
|
||||
Gateway також записує підказку про оновлення під час запуску (вимикається через `update.checkOnStart: false`).
|
||||
Для пониження версії або відновлення після інциденту встановіть `OPENCLAW_NO_AUTO_UPDATE=1` у середовищі Gateway, щоб заблокувати автоматичне застосування, навіть якщо налаштовано `update.auto.enabled`. Підказки про оновлення під час запуску все одно можуть працювати, якщо також не вимкнути `update.checkOnStart`.
|
||||
Gateway також записує підказку про оновлення під час запуску (вимкніть за допомогою `update.checkOnStart: false`).
|
||||
Для downgrade або відновлення після інциденту задайте `OPENCLAW_NO_AUTO_UPDATE=1` в оточенні Gateway, щоб блокувати автоматичні застосування навіть коли налаштовано `update.auto.enabled`. Підказки про оновлення під час запуску все одно можуть виконуватися, якщо також не вимкнено `update.checkOnStart`.
|
||||
|
||||
Оновлення менеджера пакетів, запитані через live handler площини керування Gateway,
|
||||
примусово виконують негайний перезапуск після заміни пакета. Це не залишає
|
||||
старий процес у пам’яті достатньо довго, щоб він lazy-load завантажував chunks із дерева пакета,
|
||||
яке вже було замінено. Shell `openclaw update` залишається
|
||||
рекомендованим шляхом для керованих встановлень, оскільки він може зупиняти й перезапускати
|
||||
сервіс навколо оновлення.
|
||||
|
||||
## Після оновлення
|
||||
|
||||
@ -186,7 +210,7 @@ openclaw health
|
||||
|
||||
## Відкат
|
||||
|
||||
### Зафіксуйте версію (npm)
|
||||
### Закріпити версію (npm)
|
||||
|
||||
```bash
|
||||
npm i -g openclaw@<version>
|
||||
@ -198,7 +222,7 @@ openclaw gateway restart
|
||||
`npm view openclaw version` показує поточну опубліковану версію.
|
||||
</Tip>
|
||||
|
||||
### Зафіксуйте коміт (вихідний код)
|
||||
### Закріпити commit (source)
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
@ -207,17 +231,17 @@ pnpm install && pnpm build
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Щоб повернутися до останньої версії: `git checkout main && git pull`.
|
||||
Щоб повернутися до найновішої версії: `git checkout main && git pull`.
|
||||
|
||||
## Якщо ви не можете просунутися далі
|
||||
## Якщо ви застрягли
|
||||
|
||||
- Знову запустіть `openclaw doctor` і уважно прочитайте вивід.
|
||||
- Для `openclaw update --channel dev` у вихідних checkout засіб оновлення автоматично завантажує `pnpm`, коли це потрібно. Якщо ви бачите помилку bootstrap `pnpm`/corepack, встановіть `pnpm` вручну (або знову ввімкніть `corepack`) і повторно запустіть оновлення.
|
||||
- Запустіть `openclaw doctor` ще раз і уважно прочитайте вивід.
|
||||
- Для `openclaw update --channel dev` у source checkouts засіб оновлення автоматично bootstrap-ить `pnpm`, коли це потрібно. Якщо ви бачите помилку bootstrap для pnpm/corepack, встановіть `pnpm` вручну (або повторно ввімкніть `corepack`) і перезапустіть оновлення.
|
||||
- Перевірте: [Усунення несправностей](/uk/gateway/troubleshooting)
|
||||
- Запитайте в Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд встановлення](/uk/install): усі методи встановлення.
|
||||
- [Огляд встановлення](/uk/install): усі способи встановлення.
|
||||
- [Doctor](/uk/gateway/doctor): перевірки стану після оновлень.
|
||||
- [Міграція](/uk/install/migrating): посібники з міграції для основних версій.
|
||||
- [Міграція](/uk/install/migrating): посібники з міграції основних версій.
|
||||
|
||||
@ -1,23 +1,23 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви хочете здійснити вихідний голосовий дзвінок з OpenClaw
|
||||
- Ви налаштовуєте або розробляєте voice-call Plugin
|
||||
- Вам потрібен голос у реальному часі або потокова транскрипція для телефонії
|
||||
- Ви налаштовуєте або розробляєте Plugin для голосових викликів
|
||||
- Вам потрібні голосовий зв’язок у реальному часі або потокова транскрипція в телефонії
|
||||
sidebarTitle: Voice call
|
||||
summary: Здійснюйте вихідні та приймайте вхідні голосові дзвінки через Twilio, Telnyx або Plivo з опціональним голосом у реальному часі та потоковою транскрипцією
|
||||
title: Plugin голосових викликів
|
||||
summary: Здійснюйте вихідні та приймайте вхідні голосові дзвінки через Twilio, Telnyx або Plivo, з необов’язковим голосовим зв’язком у реальному часі та потоковою транскрипцією
|
||||
title: Plugin для голосових викликів
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T06:43:08Z"
|
||||
generated_at: "2026-05-01T08:52:07Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 2fc13bcfcab09cf1118c851b56ca3bf870720f5a419e86c3c91138ff6c33f2be
|
||||
source_hash: 6334e5418e0fb530fc5d372ee1ada06ba987ce86bbf70746ee4ffe4c3ed4844e
|
||||
source_path: plugins/voice-call.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
Голосові виклики для OpenClaw через плагін. Підтримує вихідні сповіщення,
|
||||
багатоходові розмови, повнодуплексний голос у реальному часі, потокову
|
||||
транскрипцію та вхідні виклики з політиками allowlist.
|
||||
багатоетапні розмови, повнодуплексний голос у реальному часі, потокову
|
||||
транскрипцію та вхідні виклики з політиками списку дозволених.
|
||||
|
||||
**Поточні провайдери:** `twilio` (Programmable Voice + Media Streams),
|
||||
`telnyx` (Call Control v2), `plivo` (Voice API + XML transfer + GetInput
|
||||
@ -25,21 +25,21 @@ speech), `mock` (розробка/без мережі).
|
||||
|
||||
<Note>
|
||||
Плагін Voice Call працює **всередині процесу Gateway**. Якщо ви використовуєте
|
||||
віддалений Gateway, установіть і налаштуйте плагін на машині, де запущено
|
||||
віддалений Gateway, встановіть і налаштуйте плагін на машині, де працює
|
||||
Gateway, а потім перезапустіть Gateway, щоб завантажити його.
|
||||
</Note>
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
<Steps>
|
||||
<Step title="Установіть плагін">
|
||||
<Step title="Install the plugin">
|
||||
<Tabs>
|
||||
<Tab title="З npm">
|
||||
<Tab title="From npm">
|
||||
```bash
|
||||
openclaw plugins install @openclaw/voice-call
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="З локальної папки (розробка)">
|
||||
<Tab title="From a local folder (dev)">
|
||||
```bash
|
||||
PLUGIN_SRC=./path/to/local/voice-call-plugin
|
||||
openclaw plugins install "$PLUGIN_SRC"
|
||||
@ -48,39 +48,38 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Якщо npm повідомляє, що пакет, який належить OpenClaw, застарілий, ця версія
|
||||
пакета походить зі старішої зовнішньої лінійки пакетів; використовуйте поточну
|
||||
пакетовану збірку OpenClaw або шлях до локальної папки, доки не буде опубліковано
|
||||
новіший пакет npm.
|
||||
Якщо npm повідомляє, що пакет, який належить OpenClaw, застарілий, ця версія пакета
|
||||
походить зі старішої зовнішньої лінійки пакетів; використовуйте поточну пакетовану збірку OpenClaw
|
||||
або шлях до локальної папки, доки не буде опубліковано новіший пакет npm.
|
||||
|
||||
Після цього перезапустіть Gateway, щоб плагін завантажився.
|
||||
|
||||
</Step>
|
||||
<Step title="Налаштуйте провайдера та webhook">
|
||||
Установіть конфігурацію в `plugins.entries.voice-call.config` (див.
|
||||
[Конфігурація](#configuration) нижче для повної структури). Мінімально потрібні:
|
||||
`provider`, облікові дані провайдера, `fromNumber` і публічно
|
||||
доступна URL-адреса webhook.
|
||||
<Step title="Configure provider and webhook">
|
||||
Задайте конфігурацію в `plugins.entries.voice-call.config` (повну структуру див.
|
||||
у розділі [Конфігурація](#configuration) нижче). Мінімально потрібні:
|
||||
`provider`, облікові дані провайдера, `fromNumber` і загальнодоступна
|
||||
URL-адреса Webhook.
|
||||
</Step>
|
||||
<Step title="Перевірте налаштування">
|
||||
<Step title="Verify setup">
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
```
|
||||
|
||||
Типовий вивід зручно читати в журналах чату й терміналах. Він перевіряє
|
||||
ввімкнення плагіна, облікові дані провайдера, доступність webhook і те, що
|
||||
активний лише один аудіорежим (`streaming` або `realtime`). Використовуйте
|
||||
Типовий вивід зручно читати в журналах чату й терміналах. Він перевіряє,
|
||||
чи ввімкнено плагін, облікові дані провайдера, доступність Webhook і те,
|
||||
що активний лише один аудіорежим (`streaming` або `realtime`). Використовуйте
|
||||
`--json` для скриптів.
|
||||
|
||||
</Step>
|
||||
<Step title="Smoke-тест">
|
||||
<Step title="Smoke test">
|
||||
```bash
|
||||
openclaw voicecall smoke
|
||||
openclaw voicecall smoke --to "+15555550123"
|
||||
```
|
||||
|
||||
Обидва варіанти типово є пробними запусками. Додайте `--yes`, щоб фактично
|
||||
здійснити короткий вихідний виклик-сповіщення:
|
||||
Обидві команди за замовчуванням є пробними запусками. Додайте `--yes`, щоб фактично здійснити короткий
|
||||
вихідний виклик-сповіщення:
|
||||
|
||||
```bash
|
||||
openclaw voicecall smoke --to "+15555550123" --yes
|
||||
@ -90,21 +89,21 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
Для Twilio, Telnyx і Plivo налаштування має визначати **публічну URL-адресу webhook**.
|
||||
Для Twilio, Telnyx і Plivo налаштування має визначити **публічну URL-адресу Webhook**.
|
||||
Якщо `publicUrl`, URL тунелю, URL Tailscale або резервний варіант serve
|
||||
визначається як loopback чи простір приватної мережі, налаштування завершується
|
||||
помилкою замість запуску провайдера, який не зможе отримувати webhook від оператора.
|
||||
визначається як loopback чи простір приватної мережі, налаштування завершується помилкою замість
|
||||
запуску провайдера, який не зможе отримувати Webhook від оператора.
|
||||
</Warning>
|
||||
|
||||
## Конфігурація
|
||||
|
||||
Якщо `enabled: true`, але у вибраного провайдера бракує облікових даних,
|
||||
під час запуску Gateway записує попередження про неповне налаштування з відсутніми ключами та
|
||||
пропускає запуск runtime. Команди, виклики RPC і інструменти агента все одно
|
||||
Якщо `enabled: true`, але для вибраного провайдера бракує облікових даних,
|
||||
під час запуску Gateway записує попередження про незавершене налаштування з відсутніми ключами та
|
||||
пропускає запуск runtime. Команди, виклики RPC й інструменти агента все одно
|
||||
повертають точну відсутню конфігурацію провайдера під час використання.
|
||||
|
||||
<Note>
|
||||
Облікові дані Voice Call приймають SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` і `plugins.entries.voice-call.config.tts.providers.*.apiKey` розв’язуються через стандартну поверхню SecretRef; див. [поверхню облікових даних SecretRef](/uk/reference/secretref-credential-surface).
|
||||
Облікові дані voice-call приймають SecretRefs. `plugins.entries.voice-call.config.twilio.authToken`, `plugins.entries.voice-call.config.realtime.providers.*.apiKey`, `plugins.entries.voice-call.config.streaming.providers.*.apiKey` і `plugins.entries.voice-call.config.tts.providers.*.apiKey` розв’язуються через стандартну поверхню SecretRef; див. [поверхню облікових даних SecretRef](/uk/reference/secretref-credential-surface).
|
||||
</Note>
|
||||
|
||||
```json5
|
||||
@ -165,31 +164,31 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Нотатки щодо доступності провайдера та безпеки">
|
||||
- Twilio, Telnyx і Plivo потребують **публічно доступної** URL-адреси webhook.
|
||||
- `mock` — це локальний провайдер для розробки (без мережевих викликів).
|
||||
- Telnyx потребує `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо `skipSignatureVerification` не має значення true.
|
||||
<Accordion title="Provider exposure and security notes">
|
||||
- Twilio, Telnyx і Plivo всі потребують **публічно доступної** URL-адреси Webhook.
|
||||
- `mock` — локальний провайдер для розробки (без мережевих викликів).
|
||||
- Telnyx потребує `telnyx.publicKey` (або `TELNYX_PUBLIC_KEY`), якщо `skipSignatureVerification` не дорівнює true.
|
||||
- `skipSignatureVerification` призначено лише для локального тестування.
|
||||
- На безплатному рівні ngrok установіть `publicUrl` на точну URL-адресу ngrok; перевірка підпису завжди застосовується.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє webhook Twilio з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Лише для локальної розробки.
|
||||
- URL-адреси безплатного рівня ngrok можуть змінюватися або додавати проміжну поведінку; якщо `publicUrl` зміщується, підписи Twilio не проходять перевірку. Для продакшну надавайте перевагу стабільному домену або funnel Tailscale.
|
||||
- На безплатному тарифі ngrok задайте `publicUrl` як точну URL-адресу ngrok; перевірка підпису завжди обов’язкова.
|
||||
- `tunnel.allowNgrokFreeTierLoopbackBypass: true` дозволяє Webhook Twilio з недійсними підписами **лише** коли `tunnel.provider="ngrok"` і `serve.bind` є loopback (локальний агент ngrok). Лише для локальної розробки.
|
||||
- URL-адреси безплатного тарифу Ngrok можуть змінюватися або додавати проміжну сторінку; якщо `publicUrl` зміниться, підписи Twilio не проходитимуть перевірку. Для production віддавайте перевагу стабільному домену або Tailscale funnel.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Обмеження потокових підключень">
|
||||
<Accordion title="Streaming connection caps">
|
||||
- `streaming.preStartTimeoutMs` закриває сокети, які ніколи не надсилають дійсний кадр `start`.
|
||||
- `streaming.maxPendingConnections` обмежує загальну кількість неавтентифікованих сокетів до старту.
|
||||
- `streaming.maxPendingConnectionsPerIp` обмежує кількість неавтентифікованих сокетів до старту для кожної IP-адреси джерела.
|
||||
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів медіапотоків (очікуваних + активних).
|
||||
- `streaming.maxPendingConnectionsPerIp` обмежує неавтентифіковані сокети до старту для кожної вихідної IP-адреси.
|
||||
- `streaming.maxConnections` обмежує загальну кількість відкритих сокетів media stream (очікуваних + активних).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Міграції застарілої конфігурації">
|
||||
<Accordion title="Legacy config migrations">
|
||||
Старіші конфігурації, що використовують `provider: "log"`, `twilio.from` або застарілі
|
||||
ключі OpenAI `streaming.*`, переписуються через `openclaw doctor --fix`.
|
||||
Резервний runtime поки що все ще приймає старі ключі voice-call, але
|
||||
шлях переписування — це `openclaw doctor --fix`, а compat-прокладка є
|
||||
тимчасовою.
|
||||
ключі OpenAI `streaming.*`, переписуються командою `openclaw doctor --fix`.
|
||||
Резервний runtime наразі все ще приймає старі ключі voice-call, але
|
||||
шлях переписування — `openclaw doctor --fix`, а шар сумісності є
|
||||
тимчасовим.
|
||||
|
||||
Автоматично мігровані ключі streaming:
|
||||
Автомігровані ключі streaming:
|
||||
|
||||
- `streaming.sttProvider` → `streaming.provider`
|
||||
- `streaming.openaiApiKey` → `streaming.providers.openai.apiKey`
|
||||
@ -202,9 +201,9 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
|
||||
## Голосові розмови в реальному часі
|
||||
|
||||
`realtime` вибирає повнодуплексного голосового провайдера реального часу для live-аудіо виклику.
|
||||
Це окремо від `streaming`, який лише пересилає аудіо до
|
||||
провайдерів транскрипції в реальному часі.
|
||||
`realtime` вибирає повнодуплексного провайдера голосу в реальному часі для живого аудіо виклику.
|
||||
Він окремий від `streaming`, який лише пересилає аудіо
|
||||
провайдерам транскрипції в реальному часі.
|
||||
|
||||
<Warning>
|
||||
`realtime.enabled` не можна поєднувати з `streaming.enabled`. Виберіть один
|
||||
@ -214,28 +213,29 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
Поточна поведінка runtime:
|
||||
|
||||
- `realtime.enabled` підтримується для Twilio Media Streams.
|
||||
- `realtime.provider` необов’язковий. Якщо його не задано, Voice Call використовує першого зареєстрованого голосового провайдера реального часу.
|
||||
- Вбудовані голосові провайдери реального часу: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми provider-плагінами.
|
||||
- Сирa конфігурація, що належить провайдеру, міститься в `realtime.providers.<providerId>`.
|
||||
- Voice Call типово відкриває спільний realtime-інструмент `openclaw_agent_consult`. Realtime-модель може викликати його, коли абонент просить глибшого міркування, актуальної інформації або звичайних інструментів OpenClaw.
|
||||
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або жодного голосового провайдера реального часу взагалі не зареєстровано, Voice Call записує попередження та пропускає realtime-медіа замість того, щоб зупиняти весь плагін.
|
||||
- Ключі consult-сеансу повторно використовують наявний голосовий сеанс, коли він доступний, а потім переходять до номера телефону абонента/одержувача, щоб подальші consult-виклики зберігали контекст під час дзвінка.
|
||||
- `realtime.provider` є необов’язковим. Якщо його не задано, Voice Call використовує першого зареєстрованого провайдера голосу в реальному часі.
|
||||
- Вбудовані провайдери голосу в реальному часі: Google Gemini Live (`google`) і OpenAI (`openai`), зареєстровані їхніми плагінами провайдерів.
|
||||
- Необроблена конфігурація, що належить провайдеру, міститься в `realtime.providers.<providerId>`.
|
||||
- Voice Call за замовчуванням надає спільний інструмент `openclaw_agent_consult` для реального часу. Модель реального часу може викликати його, коли абонент просить глибше міркування, актуальну інформацію або звичайні інструменти OpenClaw.
|
||||
- `realtime.fastContext.enabled` за замовчуванням вимкнено. Коли ввімкнено, Voice Call спершу шукає індексований контекст пам’яті/сесії для питання consult і повертає ці фрагменти моделі реального часу протягом `realtime.fastContext.timeoutMs`, перш ніж відступити до повного агента consult лише якщо `realtime.fastContext.fallbackToConsult` дорівнює true.
|
||||
- Якщо `realtime.provider` вказує на незареєстрованого провайдера або жодного провайдера голосу в реальному часі взагалі не зареєстровано, Voice Call записує попередження та пропускає realtime media замість того, щоб завершити весь плагін помилкою.
|
||||
- Ключі сесії consult повторно використовують наявну голосову сесію, коли вона доступна, а потім відступають до номера телефону абонента/одержувача, щоб подальші виклики consult зберігали контекст під час виклику.
|
||||
|
||||
### Політика інструментів
|
||||
|
||||
`realtime.toolPolicy` керує consult-запуском:
|
||||
`realtime.toolPolicy` керує запуском consult:
|
||||
|
||||
| Політика | Поведінка |
|
||||
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `safe-read-only` | Відкрити consult-інструмент і обмежити звичайного агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. |
|
||||
| `owner` | Відкрити consult-інструмент і дозволити звичайному агенту використовувати нормальну політику інструментів агента. |
|
||||
| `none` | Не відкривати consult-інструмент. Користувацькі `realtime.tools` усе одно передаються провайдеру realtime. |
|
||||
| `safe-read-only` | Надає інструмент consult і обмежує звичайного агента до `read`, `web_search`, `web_fetch`, `x_search`, `memory_search` і `memory_get`. |
|
||||
| `owner` | Надає інструмент consult і дозволяє звичайному агенту використовувати нормальну політику інструментів агента. |
|
||||
| `none` | Не надає інструмент consult. Користувацькі `realtime.tools` усе одно передаються провайдеру realtime. |
|
||||
|
||||
### Приклади realtime-провайдерів
|
||||
### Приклади провайдерів реального часу
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Google Gemini Live">
|
||||
Типові значення: API-ключ із `realtime.providers.google.apiKey`,
|
||||
Значення за замовчуванням: API-ключ із `realtime.providers.google.apiKey`,
|
||||
`GEMINI_API_KEY` або `GOOGLE_GENERATIVE_AI_API_KEY`; модель
|
||||
`gemini-2.5-flash-native-audio-preview-12-2025`; голос `Kore`.
|
||||
|
||||
@ -292,22 +292,23 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Див. [провайдер Google](/uk/providers/google) і
|
||||
[провайдер OpenAI](/uk/providers/openai), щоб переглянути специфічні для провайдера параметри голосу в реальному часі.
|
||||
Див. [провайдера Google](/uk/providers/google) і
|
||||
[провайдера OpenAI](/uk/providers/openai) для параметрів голосу в реальному часі,
|
||||
специфічних для провайдера.
|
||||
|
||||
## Потокова транскрипція
|
||||
|
||||
`streaming` вибирає провайдера транскрипції в реальному часі для live-аудіо виклику.
|
||||
`streaming` вибирає провайдера транскрипції в реальному часі для живого аудіо виклику.
|
||||
|
||||
Поточна поведінка runtime:
|
||||
|
||||
- `streaming.provider` необов’язковий. Якщо його не задано, Voice Call використовує першого зареєстрованого провайдера транскрипції в реальному часі.
|
||||
- Вбудовані провайдери транскрипції в реальному часі: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI (`xai`), зареєстровані їхніми provider-плагінами.
|
||||
- Сирa конфігурація, що належить провайдеру, міститься в `streaming.providers.<providerId>`.
|
||||
- Після того як Twilio надсилає прийняте повідомлення `start` потоку, Voice Call негайно реєструє потік, ставить вхідні медіа в чергу через провайдера транскрипції, поки провайдер підключається, і запускає початкове привітання лише після готовності транскрипції в реальному часі.
|
||||
- Якщо `streaming.provider` вказує на незареєстрованого провайдера або жодного не зареєстровано, Voice Call записує попередження та пропускає медіапотокове передавання замість того, щоб зупиняти весь плагін.
|
||||
- `streaming.provider` необов’язковий. Якщо не задано, Voice Call використовує першого зареєстрованого провайдера транскрипції в реальному часі.
|
||||
- Вбудовані провайдери транскрипції в реальному часі: Deepgram (`deepgram`), ElevenLabs (`elevenlabs`), Mistral (`mistral`), OpenAI (`openai`) і xAI (`xai`), зареєстровані їхніми Plugin провайдерів.
|
||||
- Необроблена конфігурація, що належить провайдеру, розміщується в `streaming.providers.<providerId>`.
|
||||
- Після того як Twilio надсилає прийняте stream-повідомлення `start`, Voice Call негайно реєструє stream, ставить вхідні медіадані в чергу через провайдера транскрипції, доки провайдер підключається, і запускає початкове привітання лише після готовності транскрипції в реальному часі.
|
||||
- Якщо `streaming.provider` вказує на незареєстрованого провайдера або жодного провайдера не зареєстровано, Voice Call записує попередження в журнал і пропускає потокове передавання медіа, замість того щоб спричиняти збій усього Plugin.
|
||||
|
||||
### Приклади streaming-провайдерів
|
||||
### Приклади провайдера потокового передавання
|
||||
|
||||
<Tabs>
|
||||
<Tab title="OpenAI">
|
||||
@ -343,8 +344,8 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
|
||||
</Tab>
|
||||
<Tab title="xAI">
|
||||
Типові значення: ключ API `streaming.providers.xai.apiKey` або `XAI_API_KEY`;
|
||||
кінцева точка `wss://api.x.ai/v1/stt`; кодування `mulaw`; частота дискретизації `8000`;
|
||||
Типові значення: API-ключ `streaming.providers.xai.apiKey` або `XAI_API_KEY`;
|
||||
endpoint `wss://api.x.ai/v1/stt`; кодування `mulaw`; частота дискретизації `8000`;
|
||||
`endpointingMs: 800`; `interimResults: true`.
|
||||
|
||||
```json5
|
||||
@ -378,8 +379,8 @@ Gateway, а потім перезапустіть Gateway, щоб заванта
|
||||
## TTS для викликів
|
||||
|
||||
Voice Call використовує основну конфігурацію `messages.tts` для потокового
|
||||
мовлення у викликах. Ви можете перевизначити її в конфігурації Plugin з
|
||||
**такою самою формою** — вона глибоко об'єднується з `messages.tts`.
|
||||
мовлення під час викликів. Ви можете перевизначити її в конфігурації Plugin з
|
||||
**тією самою структурою** — вона глибоко об’єднується з `messages.tts`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -397,21 +398,21 @@ Voice Call використовує основну конфігурацію `mes
|
||||
|
||||
<Warning>
|
||||
**Microsoft speech ігнорується для голосових викликів.** Телефонному аудіо потрібен PCM;
|
||||
поточний транспорт Microsoft не надає вихід телефонного PCM.
|
||||
поточний транспорт Microsoft не надає телефонний PCM-вивід.
|
||||
</Warning>
|
||||
|
||||
Примітки щодо поведінки:
|
||||
|
||||
- Застарілі ключі `tts.<provider>` у конфігурації Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; зафіксована конфігурація має використовувати `tts.providers.<provider>`.
|
||||
- Основний TTS використовується, коли ввімкнено потокове медіа Twilio; інакше виклики повертаються до власних голосів провайдера.
|
||||
- Застарілі ключі `tts.<provider>` у конфігурації Plugin (`openai`, `elevenlabs`, `microsoft`, `edge`) виправляються командою `openclaw doctor --fix`; зафіксована в репозиторії конфігурація має використовувати `tts.providers.<provider>`.
|
||||
- Основний TTS використовується, коли потокове передавання медіа Twilio увімкнено; інакше виклики повертаються до нативних голосів провайдера.
|
||||
- Якщо медіапотік Twilio вже активний, Voice Call не повертається до TwiML `<Say>`. Якщо телефонний TTS недоступний у цьому стані, запит відтворення завершується помилкою замість змішування двох шляхів відтворення.
|
||||
- Коли телефонний TTS повертається до вторинного провайдера, Voice Call записує попередження з ланцюжком провайдерів (`from`, `to`, `attempts`) для налагодження.
|
||||
- Коли barge-in Twilio або завершення потоку очищає чергу TTS, поставлені в чергу запити відтворення завершуються, а не залишають абонентів чекати завершення відтворення.
|
||||
- Коли barge-in Twilio або завершення stream очищає чергу TTS, що очікує, поставлені в чергу запити відтворення завершуються, а не залишають абонентів чекати на завершення відтворення.
|
||||
|
||||
### Приклади TTS
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Core TTS only">
|
||||
<Tab title="Лише основний TTS">
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
@ -425,7 +426,7 @@ Voice Call використовує основну конфігурацію `mes
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Override to ElevenLabs (calls only)">
|
||||
<Tab title="Перевизначення на ElevenLabs (лише виклики)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -449,7 +450,7 @@ Voice Call використовує основну конфігурацію `mes
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="OpenAI model override (deep-merge)">
|
||||
<Tab title="Перевизначення моделі OpenAI (глибоке об’єднання)">
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
@ -475,7 +476,7 @@ Voice Call використовує основну конфігурацію `mes
|
||||
|
||||
## Вхідні виклики
|
||||
|
||||
Вхідна політика типово має значення `disabled`. Щоб увімкнути вхідні виклики, задайте:
|
||||
Типове значення політики вхідних викликів — `disabled`. Щоб увімкнути вхідні виклики, задайте:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -486,62 +487,62 @@ Voice Call використовує основну конфігурацію `mes
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`inboundPolicy: "allowlist"` — це перевірка caller ID з низькою гарантією. Plugin
|
||||
`inboundPolicy: "allowlist"` — це перевірка caller ID із низьким рівнем гарантії. Plugin
|
||||
нормалізує надане провайдером значення `From` і порівнює його з
|
||||
`allowFrom`. Перевірка Webhook автентифікує доставку провайдером і
|
||||
цілісність корисного навантаження, але вона **не** доводить володіння номером
|
||||
абонента PSTN/VoIP. Сприймайте `allowFrom` як фільтрацію caller ID, а не як надійну
|
||||
цілісність payload, але **не** доводить право власності на PSTN/VoIP номер
|
||||
абонента. Сприймайте `allowFrom` як фільтрацію caller ID, а не як надійну
|
||||
ідентичність абонента.
|
||||
</Warning>
|
||||
|
||||
Автовідповіді використовують систему агента. Налаштовуйте за допомогою `responseModel`,
|
||||
Автовідповіді використовують систему агентів. Налаштовуйте за допомогою `responseModel`,
|
||||
`responseSystemPrompt` і `responseTimeoutMs`.
|
||||
|
||||
### Контракт мовленнєвого виводу
|
||||
### Контракт голосового виводу
|
||||
|
||||
Для автовідповідей Voice Call додає до системного prompt суворий контракт мовленнєвого виводу:
|
||||
Для автовідповідей Voice Call додає до системного prompt суворий контракт голосового виводу:
|
||||
|
||||
```text
|
||||
{"spoken":"..."}
|
||||
```
|
||||
|
||||
Voice Call обережно витягує текст мовлення:
|
||||
Voice Call захисно витягує текст мовлення:
|
||||
|
||||
- Ігнорує payloads, позначені як reasoning/error content.
|
||||
- Розбирає прямий JSON, JSON у fenced-блоці або inline-ключі `"spoken"`.
|
||||
- Повертається до простого тексту й видаляє ймовірні вступні абзаци планування/метаданих.
|
||||
- Ігнорує payload, позначені як reasoning/error content.
|
||||
- Розбирає прямий JSON, fenced JSON або вбудовані ключі `"spoken"`.
|
||||
- Повертається до звичайного тексту й видаляє ймовірні вступні абзаци з плануванням або метаданими.
|
||||
|
||||
Це утримує мовленнєве відтворення зосередженим на тексті для абонента й запобігає
|
||||
потраплянню тексту планування в аудіо.
|
||||
Це зберігає голосове відтворення зосередженим на тексті для абонента й запобігає
|
||||
витоку тексту планування в аудіо.
|
||||
|
||||
### Поведінка запуску розмови
|
||||
|
||||
Для вихідних викликів `conversation` обробка першого повідомлення прив'язана до поточного
|
||||
Для вихідних викликів `conversation` обробка першого повідомлення прив’язана до поточного
|
||||
стану відтворення:
|
||||
|
||||
- Очищення черги barge-in і автовідповідь пригнічуються лише поки початкове привітання активно промовляється.
|
||||
- Очищення черги barge-in і автовідповідь пригнічуються лише тоді, коли початкове привітання активно промовляється.
|
||||
- Якщо початкове відтворення завершується помилкою, виклик повертається до `listening`, а початкове повідомлення залишається в черзі для повторної спроби.
|
||||
- Початкове відтворення для потокового Twilio починається під час підключення потоку без додаткової затримки.
|
||||
- Barge-in перериває активне відтворення й очищає поставлені в чергу, але ще не відтворювані записи Twilio TTS. Очищені записи завершуються як пропущені, тож логіка подальшої відповіді може продовжити роботу без очікування аудіо, яке ніколи не відтвориться.
|
||||
- Realtime voice conversations використовують власний початковий хід realtime-потоку. Voice Call **не** надсилає застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тому вихідні сесії `<Connect><Stream>` залишаються підключеними.
|
||||
- Початкове відтворення для потокового передавання Twilio починається після підключення stream без додаткової затримки.
|
||||
- Barge-in перериває активне відтворення й очищає поставлені в чергу, але ще не відтворювані записи Twilio TTS. Очищені записи завершуються як пропущені, тож логіка подальшої відповіді може продовжуватися без очікування аудіо, яке ніколи не відтвориться.
|
||||
- Голосові розмови в реальному часі використовують власну початкову репліку realtime stream. Voice Call **не** надсилає застаріле оновлення TwiML `<Say>` для цього початкового повідомлення, тож вихідні сесії `<Connect><Stream>` залишаються приєднаними.
|
||||
|
||||
### Пільговий період відключення потоку Twilio
|
||||
### Пільговий період відключення stream Twilio
|
||||
|
||||
Коли медіапотік Twilio відключається, Voice Call чекає **2000 мс** перед
|
||||
автоматичним завершенням виклику:
|
||||
|
||||
- Якщо потік повторно підключиться протягом цього вікна, автоматичне завершення скасовується.
|
||||
- Якщо після пільгового періоду потік не зареєструється повторно, виклик завершується, щоб запобігти зависанню активних викликів.
|
||||
- Якщо stream повторно підключається впродовж цього вікна, автоматичне завершення скасовується.
|
||||
- Якщо після пільгового періоду stream не реєструється повторно, виклик завершується, щоб запобігти завислим активним викликам.
|
||||
|
||||
## Reaper застарілих викликів
|
||||
## Прибирач застарілих викликів
|
||||
|
||||
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують термінальний
|
||||
Webhook (наприклад, виклики в режимі сповіщення, які ніколи не завершуються). Типове значення
|
||||
Використовуйте `staleCallReaperSeconds`, щоб завершувати виклики, які ніколи не отримують фінальний
|
||||
Webhook (наприклад, виклики в режимі notify, які ніколи не завершуються). Типове значення
|
||||
— `0` (вимкнено).
|
||||
|
||||
Рекомендовані діапазони:
|
||||
|
||||
- **Production:** `120`–`300` секунд для потоків у стилі сповіщень.
|
||||
- **Production:** `120`–`300` секунд для потоків у стилі notify.
|
||||
- Тримайте це значення **вищим за `maxDurationSeconds`**, щоб звичайні виклики могли завершитися. Хороша початкова точка — `maxDurationSeconds + 30–60` секунд.
|
||||
|
||||
```json5
|
||||
@ -561,26 +562,26 @@ Webhook (наприклад, виклики в режимі сповіщення
|
||||
|
||||
## Безпека Webhook
|
||||
|
||||
Коли проксі або тунель стоїть перед Gateway, Plugin
|
||||
реконструює публічний URL для перевірки підпису. Ці параметри
|
||||
керують тим, яким перенаправленим заголовкам довіряти:
|
||||
Коли proxy або tunnel розташований перед Gateway, Plugin
|
||||
відновлює публічний URL для перевірки підпису. Ці параметри
|
||||
керують тим, яким forwarded headers можна довіряти:
|
||||
|
||||
<ParamField path="webhookSecurity.allowedHosts" type="string[]">
|
||||
Дозволені хости із заголовків forwarding.
|
||||
Дозволений список хостів із forwarding headers.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustForwardingHeaders" type="boolean">
|
||||
Довіряти forwarded-заголовкам без allowlist.
|
||||
Довіряти forwarded headers без дозволеного списку.
|
||||
</ParamField>
|
||||
<ParamField path="webhookSecurity.trustedProxyIPs" type="string[]">
|
||||
Довіряти forwarded-заголовкам лише тоді, коли віддалена IP-адреса запиту відповідає списку.
|
||||
Довіряти forwarded headers лише тоді, коли remote IP запиту збігається зі списком.
|
||||
</ParamField>
|
||||
|
||||
Додаткові засоби захисту:
|
||||
|
||||
- **Захист від replay** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні запити Webhook підтверджуються, але пропускаються для побічних ефектів.
|
||||
- Ходи розмови Twilio містять per-turn token у callbacks `<Gather>`, тому застарілі/повторно відтворені speech callbacks не можуть задовольнити новіший очікуваний хід транскрипта.
|
||||
- Неавтентифіковані запити Webhook відхиляються до читання тіла, коли відсутні обов'язкові signature headers провайдера.
|
||||
- Webhook voice-call використовує спільний pre-auth body profile (64 КБ / 5 секунд) плюс per-IP in-flight cap перед перевіркою підпису.
|
||||
- **Захист від повторного відтворення** Webhook увімкнено для Twilio і Plivo. Повторно відтворені дійсні Webhook-запити підтверджуються, але пропускаються для побічних ефектів.
|
||||
- Репліки розмови Twilio містять per-turn token у callback `<Gather>`, тож застарілі або повторно відтворені speech callbacks не можуть задовольнити новішу очікувану репліку transcript.
|
||||
- Неавтентифіковані Webhook-запити відхиляються до читання тіла, якщо відсутні обов’язкові signature headers провайдера.
|
||||
- Webhook voice-call використовує спільний pre-auth body profile (64 КБ / 5 секунд) плюс per-IP ліміт in-flight перед перевіркою підпису.
|
||||
|
||||
Приклад зі стабільним публічним хостом:
|
||||
|
||||
@ -616,15 +617,15 @@ openclaw voicecall latency # summarize turn latency from lo
|
||||
openclaw voicecall expose --mode funnel
|
||||
```
|
||||
|
||||
Коли Gateway уже запущено, операційні команди `voicecall` делегують
|
||||
рантайму voice-call, що належить Gateway, щоб CLI не прив'язував другий
|
||||
Webhook-сервер. Якщо Gateway недоступний, команди повертаються до
|
||||
самостійного CLI runtime.
|
||||
Коли Gateway уже запущено, операційні команди `voicecall` делегують виконання
|
||||
runtime voice-call, що належить Gateway, щоб CLI не прив’язував другий
|
||||
Webhook-сервер. Якщо Gateway недосяжний, команди повертаються до
|
||||
автономного runtime CLI.
|
||||
|
||||
`latency` читає `calls.jsonl` зі стандартного шляху сховища voice-call.
|
||||
Використовуйте `--file <path>`, щоб указати інший журнал, і `--last <n>`, щоб обмежити
|
||||
аналіз останніми N записами (типово 200). Вивід містить p50/p90/p99
|
||||
для latency ходу та часу listen-wait.
|
||||
для latency реплік і часу listen-wait.
|
||||
|
||||
## Інструмент агента
|
||||
|
||||
@ -639,7 +640,7 @@ Webhook-сервер. Якщо Gateway недоступний, команди п
|
||||
| `end_call` | `callId` |
|
||||
| `get_status` | `callId` |
|
||||
|
||||
Цей репозиторій постачає відповідний документ Skills за адресою `skills/voice-call/SKILL.md`.
|
||||
Цей репозиторій постачає відповідний документ skill за адресою `skills/voice-call/SKILL.md`.
|
||||
|
||||
## Gateway RPC
|
||||
|
||||
@ -652,13 +653,13 @@ Webhook-сервер. Якщо Gateway недоступний, команди п
|
||||
| `voicecall.end` | `callId` |
|
||||
| `voicecall.status` | `callId` |
|
||||
|
||||
`dtmfSequence` дійсний лише з `mode: "conversation"`. Виклики notify-mode
|
||||
`dtmfSequence` чинний лише з `mode: "conversation"`. Виклики в режимі notify
|
||||
мають використовувати `voicecall.dtmf` після створення виклику, якщо їм потрібні
|
||||
цифри після підключення.
|
||||
digits після підключення.
|
||||
|
||||
## Усунення несправностей
|
||||
|
||||
### Налаштування не може відкрити Webhook
|
||||
### Налаштування не вдається через expose Webhook
|
||||
|
||||
Запустіть налаштування з того самого середовища, у якому працює Gateway:
|
||||
|
||||
@ -667,11 +668,7 @@ openclaw voicecall setup
|
||||
openclaw voicecall setup --json
|
||||
```
|
||||
|
||||
Для `twilio`, `telnyx` і `plivo` `webhook-exposure` має бути зеленим. Навіть
|
||||
налаштований `publicUrl` завершиться помилкою, якщо він вказує на локальний або приватний мережевий
|
||||
простір, тому що оператор не може виконати зворотний виклик на ці адреси. Не використовуйте
|
||||
`localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`,
|
||||
`192.168.x`, `169.254.x`, `fc00::/7` або `fd00::/8` як `publicUrl`.
|
||||
Для `twilio`, `telnyx` і `plivo` `webhook-exposure` має бути зеленим. Налаштований `publicUrl` усе одно не спрацює, якщо вказує на локальний або приватний мережевий простір, тому що оператор не може виконати зворотний виклик на ці адреси. Не використовуйте `localhost`, `127.0.0.1`, `0.0.0.0`, `10.x`, `172.16.x`-`172.31.x`, `192.168.x`, `169.254.x`, `fc00::/7` або `fd00::/8` як `publicUrl`.
|
||||
|
||||
Використовуйте один публічний шлях доступу:
|
||||
|
||||
@ -700,11 +697,11 @@ openclaw voicecall setup
|
||||
openclaw voicecall smoke
|
||||
```
|
||||
|
||||
`voicecall smoke` — це сухий запуск, якщо не передати `--yes`.
|
||||
`voicecall smoke` виконує пробний запуск, якщо не передати `--yes`.
|
||||
|
||||
### Не вдається перевірити облікові дані провайдера
|
||||
### Облікові дані провайдера не проходять перевірку
|
||||
|
||||
Перевірте вибраного провайдера та потрібні поля облікових даних:
|
||||
Перевірте вибраного провайдера та обов’язкові поля облікових даних:
|
||||
|
||||
- Twilio: `twilio.accountSid`, `twilio.authToken` і `fromNumber`, або
|
||||
`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` і `TWILIO_FROM_NUMBER`.
|
||||
@ -712,11 +709,9 @@ openclaw voicecall smoke
|
||||
`fromNumber`.
|
||||
- Plivo: `plivo.authId`, `plivo.authToken` і `fromNumber`.
|
||||
|
||||
Облікові дані мають існувати на хості Gateway. Редагування локального профілю оболонки
|
||||
не впливає на вже запущений Gateway, доки він не перезапуститься або не перезавантажить
|
||||
своє середовище.
|
||||
Облікові дані мають існувати на хості Gateway. Редагування локального профілю оболонки не впливає на вже запущений Gateway, доки його не буде перезапущено або доки він не перезавантажить своє середовище.
|
||||
|
||||
### Виклики запускаються, але Webhook-и провайдера не надходять
|
||||
### Виклики починаються, але Webhook-и провайдера не надходять
|
||||
|
||||
Переконайтеся, що консоль провайдера вказує на точну публічну URL-адресу Webhook:
|
||||
|
||||
@ -734,33 +729,26 @@ openclaw logs --follow
|
||||
|
||||
Поширені причини:
|
||||
|
||||
- `publicUrl` вказує на інший шлях, ніж `serve.path`.
|
||||
- URL тунелю змінилася після запуску Gateway.
|
||||
- Проксі пересилає запит, але вилучає або переписує заголовки host/proto.
|
||||
- Брандмауер або DNS спрямовує публічне ім’я хоста кудись інде, а не до Gateway.
|
||||
- `publicUrl` вказує на шлях, відмінний від `serve.path`.
|
||||
- URL тунелю змінився після запуску Gateway.
|
||||
- Проксі пересилає запит, але видаляє або переписує заголовки host/proto.
|
||||
- Брандмауер або DNS спрямовує публічне ім’я хоста не до Gateway.
|
||||
- Gateway було перезапущено без увімкненого Plugin Voice Call.
|
||||
|
||||
Коли перед Gateway стоїть зворотний проксі або тунель, установіть
|
||||
`webhookSecurity.allowedHosts` на публічне ім’я хоста або використайте
|
||||
`webhookSecurity.trustedProxyIPs` для відомої адреси проксі. Використовуйте
|
||||
`webhookSecurity.trustForwardingHeaders` лише тоді, коли межа проксі перебуває під
|
||||
вашим контролем.
|
||||
Коли перед Gateway стоїть зворотний проксі або тунель, задайте `webhookSecurity.allowedHosts` як публічне ім’я хоста або використайте `webhookSecurity.trustedProxyIPs` для відомої адреси проксі. Використовуйте `webhookSecurity.trustForwardingHeaders` лише тоді, коли межа проксі перебуває під вашим контролем.
|
||||
|
||||
### Не вдається перевірити підпис
|
||||
### Перевірка підпису не проходить
|
||||
|
||||
Підписи провайдера перевіряються відносно публічної URL-адреси, яку OpenClaw відтворює
|
||||
з вхідного запиту. Якщо перевірка підписів не проходить:
|
||||
Підписи провайдера перевіряються відносно публічної URL-адреси, яку OpenClaw відновлює з вхідного запиту. Якщо підписи не проходять перевірку:
|
||||
|
||||
- Переконайтеся, що URL Webhook провайдера точно збігається з `publicUrl`, включно зі
|
||||
схемою, хостом і шляхом.
|
||||
- Для URL ngrok безплатного рівня оновлюйте `publicUrl`, коли змінюється ім’я хоста тунелю.
|
||||
- Переконайтеся, що проксі зберігає початкові заголовки host і proto, або налаштуйте
|
||||
`webhookSecurity.allowedHosts`.
|
||||
- Переконайтеся, що URL-адреса Webhook у провайдера точно збігається з `publicUrl`, включно зі схемою, хостом і шляхом.
|
||||
- Для URL безплатного рівня ngrok оновлюйте `publicUrl`, коли змінюється ім’я хоста тунелю.
|
||||
- Переконайтеся, що проксі зберігає оригінальні заголовки host і proto, або налаштуйте `webhookSecurity.allowedHosts`.
|
||||
- Не вмикайте `skipSignatureVerification` поза локальним тестуванням.
|
||||
|
||||
### Не вдаються приєднання Google Meet через Twilio
|
||||
### Приєднання Google Meet через Twilio не спрацьовує
|
||||
|
||||
Google Meet використовує цей Plugin для приєднань через Twilio dial-in. Спершу перевірте Voice Call:
|
||||
Google Meet використовує цей Plugin для приєднання через дозвін Twilio. Спочатку перевірте Voice Call:
|
||||
|
||||
```bash
|
||||
openclaw voicecall setup
|
||||
@ -773,43 +761,33 @@ openclaw voicecall smoke --to "+15555550123"
|
||||
openclaw googlemeet setup --transport twilio
|
||||
```
|
||||
|
||||
Якщо Voice Call працює справно, але учасник Meet так і не приєднується, перевірте номер
|
||||
dial-in Meet, PIN і `--dtmf-sequence`. Телефонний виклик може бути справним, тоді як
|
||||
зустріч відхиляє або ігнорує неправильну DTMF-послідовність.
|
||||
Якщо Voice Call зелений, але учасник Meet так і не приєднується, перевірте номер дозвону Meet, PIN і `--dtmf-sequence`. Телефонний виклик може бути справним, тоді як зустріч відхиляє або ігнорує неправильну DTMF-послідовність.
|
||||
|
||||
Google Meet передає DTMF-послідовність Meet і вступний текст до `voicecall.start`.
|
||||
Для викликів Twilio Voice Call спершу віддає DTMF TwiML, перенаправляє назад до
|
||||
Webhook, а потім відкриває медіапотік реального часу, щоб збережений вступ був
|
||||
згенерований після приєднання телефонного учасника до зустрічі.
|
||||
Google Meet передає DTMF-послідовність Meet і вступний текст у `voicecall.start`. Для викликів Twilio Voice Call спочатку подає DTMF TwiML, перенаправляє назад до Webhook, а потім відкриває медіапотік у реальному часі, щоб збережений вступ було згенеровано після того, як телефонний учасник приєднався до зустрічі.
|
||||
|
||||
Використовуйте `openclaw logs --follow` для трасування фази наживо. Справне приєднання
|
||||
Twilio до Meet журналює такий порядок:
|
||||
Використовуйте `openclaw logs --follow` для трасування живої фази. Справне приєднання Twilio до Meet записує події в такому порядку:
|
||||
|
||||
- Google Meet делегує приєднання Twilio до Voice Call.
|
||||
- Voice Call зберігає DTMF TwiML перед з’єднанням.
|
||||
- Початковий TwiML Twilio споживається й віддається перед обробкою в реальному часі.
|
||||
- Voice Call віддає TwiML реального часу для виклику Twilio.
|
||||
- Міст реального часу запускається з початковим привітанням у черзі.
|
||||
- Voice Call зберігає DTMF TwiML перед підключенням.
|
||||
- Початковий TwiML Twilio споживається й подається перед обробкою в реальному часі.
|
||||
- Voice Call подає TwiML у реальному часі для виклику Twilio.
|
||||
- Міст реального часу запускається з поставленим у чергу початковим привітанням.
|
||||
|
||||
`openclaw voicecall tail` і далі показує збережені записи викликів; це корисно для
|
||||
стану виклику й транскриптів, але не кожен перехід Webhook/реального часу з’являється
|
||||
там.
|
||||
`openclaw voicecall tail` усе ще показує збережені записи викликів; це корисно для стану виклику й транскриптів, але не кожен перехід Webhook/реального часу там відображається.
|
||||
|
||||
### Виклик у реальному часі не має мовлення
|
||||
### У виклику реального часу немає мовлення
|
||||
|
||||
Переконайтеся, що ввімкнено лише один аудіорежим. `realtime.enabled` і
|
||||
`streaming.enabled` не можуть одночасно мати значення true.
|
||||
Переконайтеся, що ввімкнено лише один аудіорежим. `realtime.enabled` і `streaming.enabled` не можуть одночасно бути `true`.
|
||||
|
||||
Для викликів Twilio у реальному часі також перевірте:
|
||||
|
||||
- Plugin провайдера реального часу завантажено й зареєстровано.
|
||||
- `realtime.provider` не задано або він називає зареєстрованого провайдера.
|
||||
- API-ключ провайдера доступний процесу Gateway.
|
||||
- `openclaw logs --follow` показує, що TwiML реального часу віддано, міст реального часу
|
||||
запущено, а початкове привітання поставлено в чергу.
|
||||
- `openclaw logs --follow` показує, що TwiML у реальному часі подано, міст реального часу запущено, а початкове привітання поставлено в чергу.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Режим розмови](/uk/nodes/talk)
|
||||
- [Перетворення тексту на мовлення](/uk/tools/tts)
|
||||
- [Синтез мовлення](/uk/tools/tts)
|
||||
- [Голосове пробудження](/uk/nodes/voicewake)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user