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

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-26 00:22:12 +00:00
parent b8f3801135
commit f278d73eb4
14 changed files with 3087 additions and 2979 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

189
docs/uk/cli/plugins.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Ви хочете встановити або керувати плагінами Gateway чи сумісними пакетами
- Ви хочете встановити або керувати плагінами Gateway чи сумісними пакетами з комплектом модулів
- Ви хочете налагодити збої завантаження плагінів
summary: Довідка CLI для `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
summary: Довідник CLI для `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)
title: Плагіни
x-i18n:
generated_at: "2026-04-25T21:54:35Z"
generated_at: "2026-04-26T00:18:18Z"
model: gpt-5.4
provider: openai
source_hash: 3c8abd8c8faf9fbbe1e586a94d5a84848b03746bff05fdac35ffd47032dda292
source_hash: da98084eb695f0180f928475e31c649a6fc45431b59067688d37417b3727f587
source_path: cli/plugins.md
workflow: 15
---
@ -19,9 +19,9 @@ x-i18n:
Пов’язано:
- Система плагінів: [Плагіни](/uk/tools/plugin)
- Система Plugin: [Плагіни](/uk/tools/plugin)
- Сумісність пакетів: [Пакети плагінів](/uk/plugins/bundles)
- Маніфест плагіна + схема: [Маніфест плагіна](/uk/plugins/manifest)
- Маніфест Plugin + схема: [Маніфест Plugin](/uk/plugins/manifest)
- Посилення безпеки: [Безпека](/uk/gateway/security)
## Команди
@ -48,11 +48,11 @@ openclaw plugins marketplace list <marketplace>
openclaw plugins marketplace list <marketplace> --json
```
Вбудовані плагіни постачаються разом з OpenClaw. Деякі ввімкнені типово (наприклад, вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований браузерний плагін); для інших потрібно виконати `plugins enable`.
Вбудовані плагіни постачаються разом з OpenClaw. Деякі з них увімкнені типово (наприклад, вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований плагін браузера); інші потребують `plugins enable`.
Нативні плагіни OpenClaw мають постачатися з `openclaw.plugin.json` із вбудованою JSON Schema (`configSchema`, навіть якщо вона порожня). Сумісні пакети натомість використовують власні маніфести пакетів.
Нативні плагіни OpenClaw мають постачатися з `openclaw.plugin.json` із вбудованою схемою JSON Schema (`configSchema`, навіть якщо вона порожня). Сумісні пакети натомість використовують власні маніфести пакетів.
`plugins list` показує `Format: openclaw` або `Format: bundle`. Вивід verbose list/info також показує підтип пакета (`codex`, `claude` або `cursor`) плюс виявлені можливості пакета.
`plugins list` показує `Format: openclaw` або `Format: bundle`. Детальний вивід list/info також показує підтип пакета (`codex`, `claude` або `cursor`) і виявлені можливості пакета.
### Встановлення
@ -68,33 +68,33 @@ openclaw plugins install <plugin> --marketplace <name> # marketplace (явно)
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
```
Прості назви пакетів спочатку перевіряються в ClawHub, а потім у npm. Примітка щодо безпеки: ставтеся до встановлення плагінів так само, як до запуску коду. Надавайте перевагу закріпленим версіям.
Прості назви пакетів спочатку перевіряються в ClawHub, а потім у npm. Примітка щодо безпеки: ставтеся до встановлення плагінів як до запуску коду. Віддавайте перевагу закріпленим версіям.
Якщо ваш розділ `plugins` використовує однофайловий `$include`, то `plugins install/update/enable/disable/uninstall` записують зміни безпосередньо до включеного файла і не змінюють `openclaw.json`. Кореневі include, масиви include та include із сусідніми override-параметрами завершуються захищеною відмовою замість сплощення. Підтримувані форми описано в [Config includes](/uk/gateway/configuration).
Якщо ваш розділ `plugins` використовує однофайловий `$include`, то `plugins install/update/enable/disable/uninstall` записують зміни в цей включений файл і не змінюють `openclaw.json`. Кореневі include, масиви include та include із сусідніми перевизначеннями завершуються без змін замість сплощення. Підтримувані форми див. у [Config includes](/uk/gateway/configuration).
Якщо конфігурація невалідна, `plugins install` зазвичай завершується захищеною відмовою і пропонує спочатку запустити `openclaw doctor --fix`. Єдиний задокументований виняток — вузький шлях відновлення для вбудованих плагінів, які явно вмикають `openclaw.install.allowInvalidConfigRecovery`.
Якщо конфігурація невалідна, `plugins install` зазвичай завершується без змін і пропонує спочатку виконати `openclaw doctor --fix`. Єдиний задокументований виняток — вузький шлях відновлення для вбудованих плагінів, які явно вмикають `openclaw.install.allowInvalidConfigRecovery`.
`--force` повторно використовує наявну ціль встановлення й перезаписує вже встановлений плагін або набір хуків на місці. Використовуйте це, коли ви свідомо перевстановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або npm-артефакту. Для звичайних оновлень уже відстежуваного npm-плагіна надавайте перевагу `openclaw plugins update <id-or-npm-spec>`.
`--force` повторно використовує наявну ціль встановлення і перезаписує вже встановлений плагін або набір хуків на місці. Використовуйте його, коли ви свідомо перевстановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або артефакту npm. Для звичайних оновлень уже відстежуваного npm-плагіна віддавайте перевагу `openclaw plugins update <id-or-npm-spec>`.
Якщо ви запускаєте `plugins install` для id плагіна, який уже встановлено, OpenClaw зупиняється й указує на `plugins update <id-or-npm-spec>` для звичайного оновлення або на `plugins install <package> --force`, якщо ви справді хочете перезаписати поточне встановлення з іншого джерела.
Якщо ви запускаєте `plugins install` для id плагіна, який уже встановлено, OpenClaw зупиняється і пропонує `plugins update <id-or-npm-spec>` для звичайного оновлення або `plugins install <package> --force`, якщо ви справді хочете перезаписати поточне встановлення з іншого джерела.
`--pin` застосовується лише до встановлень із npm. Він не підтримується з `--marketplace`, оскільки встановлення з marketplace зберігають метадані джерела marketplace замість npm-spec.
`--pin` застосовується лише до встановлень npm. Він не підтримується з `--marketplace`, оскільки встановлення з marketplace зберігають метадані джерела marketplace, а не npm-spec.
`--dangerously-force-unsafe-install` — це аварійний параметр для хибнопозитивних спрацьовувань вбудованого сканера небезпечного коду. Він дозволяє продовжити встановлення, навіть якщо вбудований сканер повідомляє про знахідки `critical`, але **не** обходить блокування політики хука `before_install` для плагіна і **не** обходить збої сканування.
`--dangerously-force-unsafe-install` — це аварійний параметр для хибнопозитивних спрацьовувань вбудованого сканера небезпечного коду. Він дозволяє продовжити встановлення, навіть якщо вбудований сканер повідомляє про результати `critical`, але **не** обходить блокування політики hook `before_install` плагіна і **не** обходить збої сканування.
Цей прапорець CLI застосовується до потоків встановлення/оновлення плагінів. Встановлення залежностей Skills через Gateway використовують відповідний override запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` лишається окремим потоком завантаження/встановлення Skills із ClawHub.
Цей прапорець CLI застосовується до потоків встановлення/оновлення плагінів. Встановлення залежностей Skills, що виконуються через Gateway, використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills через ClawHub.
`plugins install` також є поверхнею встановлення для наборів хуків, які експонують `openclaw.hooks` у `package.json`. Використовуйте `openclaw hooks` для відфільтрованого перегляду хуків і ввімкнення окремих хуків, а не для встановлення пакета.
`plugins install` також є поверхнею встановлення для наборів хуків, які надають `openclaw.hooks` у `package.json`. Для відфільтрованої видимості хуків і вмикання окремих хуків використовуйте `openclaw hooks`, а не встановлення пакетів.
Npm-spec є **лише реєстровими** (назва пакета + необов’язкова **точна версія** або **dist-tag**). Git/URL/file-spec і діапазони semver відхиляються. Для безпеки встановлення залежностей виконуються локально для проєкту з `--ignore-scripts`, навіть якщо у вашій оболонці є глобальні налаштування встановлення npm.
Npm-spec є **лише реєстровими** (назва пакета + необов’язкова **точна версія** або **dist-tag**). Специфікації Git/URL/file і діапазони semver відхиляються. Для безпеки встановлення залежностей виконуються локально для проєкту з `--ignore-scripts`, навіть якщо у вашій оболонці задані глобальні параметри npm install.
Прості специфікації та `@latest` лишаються на стабільному каналі. Якщо npm для будь-якого з них повертає prerelease, OpenClaw зупиняється й просить вас явно погодитися на це за допомогою prerelease-тега, такого як `@beta`/`@rc`, або точної prerelease-версії, такої як `@1.2.3-beta.4`.
Прості специфікації та `@latest` залишаються на стабільному каналі. Якщо npm розв’язує будь-яку з них до prerelease-версії, OpenClaw зупиняється і просить явно погодитися через тег prerelease, наприклад `@beta`/`@rc`, або через точну версію prerelease, наприклад `@1.2.3-beta.4`.
Якщо проста специфікація встановлення збігається з id вбудованого плагіна (наприклад, `diffs`), OpenClaw встановлює вбудований плагін напряму. Щоб установити npm-пакет із такою самою назвою, використовуйте явну scoped-специфікацію (наприклад, `@scope/diffs`).
Якщо проста специфікація встановлення збігається з id вбудованого плагіна (наприклад, `diffs`), OpenClaw встановлює вбудований плагін напряму. Щоб встановити npm-пакет з такою самою назвою, використовуйте явну scoped-специфікацію (наприклад, `@scope/diffs`).
Підтримувані архіви: `.zip`, `.tgz`, `.tar.gz`, `.tar`.
Також підтримуються встановлення з Claude marketplace.
Також підтримуються встановлення з marketplace Claude.
Встановлення з ClawHub використовують явний локатор `clawhub:<package>`:
@ -103,15 +103,15 @@ openclaw plugins install clawhub:openclaw-codex-app-server
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
```
Тепер OpenClaw також надає перевагу ClawHub для простих npm-safe специфікацій плагінів. Він переходить до npm, лише якщо в ClawHub немає такого пакета або версії:
Тепер OpenClaw також віддає перевагу ClawHub для простих безпечних для npm специфікацій плагінів. До npm він переходить лише тоді, коли в ClawHub немає цього пакета або версії:
```bash
openclaw plugins install openclaw-codex-app-server
```
OpenClaw завантажує архів пакета з ClawHub, перевіряє заявлену сумісність plugin API / minimum gateway, а потім встановлює його через звичайний шлях архіву. Записані встановлення зберігають метадані джерела ClawHub для подальших оновлень.
OpenClaw завантажує архів пакета з ClawHub, перевіряє заявлену сумісність API плагіна / мінімальну сумісність gateway, а потім встановлює його звичайним шляхом для архівів. Записані встановлення зберігають метадані джерела ClawHub для подальших оновлень.
Використовуйте скорочення `plugin@marketplace`, коли назва marketplace існує в локальному кеші реєстру Claude за шляхом `~/.claude/plugins/known_marketplaces.json`:
Використовуйте скорочення `plugin@marketplace`, коли назва marketplace існує в локальному кеші реєстру Claude за адресою `~/.claude/plugins/known_marketplaces.json`:
```bash
openclaw plugins marketplace list <marketplace-name>
@ -130,21 +130,21 @@ openclaw plugins install <plugin-name> --marketplace ./my-marketplace
Джерелами marketplace можуть бути:
- назва відомого marketplace Claude з `~/.claude/plugins/known_marketplaces.json`
- локальний корінь marketplace або шлях до `marketplace.json`
- скорочений запис GitHub repo на кшталт `owner/repo`
- URL GitHub repo на кшталт `https://github.com/owner/repo`
- git URL
- локальний корінь marketplace або шлях `marketplace.json`
- скорочений запис репозиторію GitHub, наприклад `owner/repo`
- URL репозиторію GitHub, наприклад `https://github.com/owner/repo`
- URL git
Для віддалених marketplace, завантажених із GitHub або git, записи плагінів мають залишатися в межах клонованого repo marketplace. OpenClaw приймає відносні джерела шляхів із цього repo і відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші джерела плагінів, що не є шляхами, з віддалених маніфестів.
Для віддалених marketplace, завантажених із GitHub або git, записи плагінів мають залишатися всередині клонованого репозиторію marketplace. OpenClaw приймає джерела відносних шляхів із цього репозиторію та відхиляє HTTP(S), абсолютні шляхи, git, GitHub та інші джерела плагінів, що не є шляхами, із віддалених маніфестів.
Для локальних шляхів і архівів OpenClaw автоматично виявляє:
- нативні плагіни OpenClaw (`openclaw.plugin.json`)
- сумісні з Codex пакети (`.codex-plugin/plugin.json`)
- сумісні з Claude пакети (`.claude-plugin/plugin.json` або стандартний макет компонентів Claude)
- сумісні з Cursor пакети (`.cursor-plugin/plugin.json`)
- пакети, сумісні з Codex (`.codex-plugin/plugin.json`)
- пакети, сумісні з Claude (`.claude-plugin/plugin.json` або типове компонування компонентів Claude)
- пакети, сумісні з Cursor (`.cursor-plugin/plugin.json`)
Сумісні пакети встановлюються в звичайний корінь плагінів і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються bundle skills, Claude command-skills, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` / `lspServers`, оголошені в маніфесті, Cursor command-skills і сумісні каталоги хуків Codex; інші виявлені можливості пакетів показуються в diagnostics/info, але ще не підключені до виконання під час runtime.
Сумісні пакети встановлюються до звичайного кореня плагінів і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються bundle Skills, command-skills Claude, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` / `lspServers`, оголошені в маніфесті, command-skills Cursor і сумісні каталоги хуків Codex; інші виявлені можливості пакетів показуються в diagnostics/info, але ще не підключені до виконання під час роботи.
### Список
@ -155,31 +155,29 @@ openclaw plugins list --verbose
openclaw plugins list --json
```
Використовуйте `--enabled`, щоб показати лише ввімкнені плагіни. Використовуйте `--verbose`, щоб переключитися з табличного вигляду на рядки з деталями для кожного плагіна, включно з метаданими source/origin/version/activation. Використовуйте `--json` для машинозчитуваного переліку плюс diagnostics реєстру.
Використовуйте `--enabled`, щоб показати лише увімкнені плагіни. Використовуйте `--verbose`, щоб перейти від табличного вигляду до детальних рядків для кожного плагіна з метаданими source/origin/version/activation. Використовуйте `--json` для машиночитного інвентарю та діагностики реєстру.
`plugins list` спочатку читає збережений локальний реєстр плагінів із резервним derived-варіантом лише за маніфестом, якщо реєстр відсутній або невалідний. Це корисно для перевірки, чи встановлено плагін, чи ввімкнений він і чи видимий для cold startup planning, але це не live runtime probe уже запущеного процесу Gateway. Після зміни коду плагіна, стану ввімкнення, політики хуків або `plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж очікувати запуску нового коду `register(api)` або хуків. Для віддалених/container-розгортань переконайтеся, що ви перезапускаєте фактичний дочірній процес `openclaw gateway run`, а не лише процес-обгортку.
`plugins list` спочатку читає збережений локальний реєстр плагінів і використовує резервний похідний варіант лише з маніфестів, якщо реєстр відсутній або невалідний. Це корисно для перевірки, чи встановлено плагін, чи ввімкнено його і чи видимий він для планування холодного запуску, але це не є живою перевіркою вже запущеного процесу Gateway під час виконання. Після зміни коду плагіна, стану ввімкнення, політики хуків або `plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж очікувати, що новий код `register(api)` або хуки почнуть виконуватися. Для віддалених/контейнерних розгортань переконайтеся, що ви перезапускаєте фактичний дочірній процес `openclaw gateway run`, а не лише процес-обгортку.
Для налагодження runtime-хуків:
Для налагодження runtime hooks:
- `openclaw plugins inspect <id> --json` показує зареєстровані хуки та diagnostics із проходу inspection після завантаження модуля.
- `openclaw gateway status --deep --require-rpc` підтверджує досяжний Gateway, підказки щодо service/process, шлях до конфігурації та стан RPC.
- Невбудовані conversation hooks (`llm_input`, `llm_output`, `agent_end`) потребують `plugins.entries.<id>.hooks.allowConversationAccess=true`.
- `openclaw plugins inspect <id> --json` показує зареєстровані хуки та діагностику з проходу перевірки завантаженого модуля.
- `openclaw gateway status --deep --require-rpc` підтверджує доступний Gateway, підказки щодо service/process, шлях до конфігурації та стан RPC.
- Для невбудованих хуків розмови (`llm_input`, `llm_output`, `agent_end`) потрібно `plugins.entries.<id>.hooks.allowConversationAccess=true`.
Використовуйте `--link`, щоб уникнути копіювання локального каталогу (додає його до `plugins.load.paths`):
Використовуйте `--link`, щоб не копіювати локальний каталог (додає його до `plugins.load.paths`):
```bash
openclaw plugins install -l ./my-plugin
```
`--force` не підтримується з `--link`, оскільки linked-встановлення повторно використовують вихідний шлях замість копіювання до керованої цілі встановлення.
`--force` не підтримується з `--link`, оскільки зв’язані встановлення повторно використовують вихідний шлях замість копіювання поверх керованої цілі встановлення.
Використовуйте `--pin` для встановлень із npm, щоб зберегти визначену точну специфікацію (`name@version`) у керованому журналі встановлень плагінів, залишивши типову поведінку незакріпленою.
Використовуйте `--pin` під час встановлень npm, щоб зберегти розв’язану точну специфікацію (`name@version`) у керованому індексі плагінів, залишаючи типову поведінку незакріпленою.
### Журнал встановлень
### Індекс Plugin
Метадані встановлення плагінів — це машинно керований стан, а не користувацька конфігурація. Нові встановлення та оновлення записують їх до `plugins/installs.json` у активному каталозі стану OpenClaw. Файл містить попередження не редагувати його вручну й використовується командами `openclaw plugins update`, uninstall, diagnostics і cold plugin registry.
Застарілі записи `plugins.installs` у `openclaw.json` лишаються читабельними як застарілий резервний механізм сумісності. Коли шляхи install/update/uninstall переписують стан встановлення плагіна, OpenClaw записує файл журналу й видаляє `plugins.installs` зі збереженого payload конфігурації.
Метадані встановлення Plugin — це машинно керований стан, а не конфігурація користувача. Під час встановлень і оновлень вони записуються в `plugins/installs.json` у активному каталозі стану OpenClaw. Його карта верхнього рівня `installRecords` є довготривалим джерелом метаданих встановлення, зокрема записів для зламаних або відсутніх маніфестів плагінів. Масив `plugins` — це кеш холодного реєстру, похідний від маніфестів. Файл містить попередження не редагувати його вручну та використовується `openclaw plugins update`, uninstall, diagnostics і холодним реєстром плагінів.
### Видалення
@ -189,11 +187,10 @@ openclaw plugins uninstall <id> --dry-run
openclaw plugins uninstall <id> --keep-files
```
`uninstall` видаляє записи плагіна з `plugins.entries`, керованого журналу встановлень, allowlist плагінів і пов’язаних записів `plugins.load.paths`, коли це застосовно.
Для плагінів Active Memory слот пам’яті скидається до `memory-core`.
`uninstall` видаляє записи плагіна з `plugins.entries`, збереженого індексу плагінів, списку дозволених плагінів і, за потреби, прив’язані записи `plugins.load.paths`.
Для плагінів active memory слот пам’яті скидається до `memory-core`.
Типово uninstall також видаляє каталог встановлення плагіна під коренем плагінів active state-dir. Використовуйте
`--keep-files`, щоб зберегти файли на диску.
Типово uninstall також видаляє каталог встановлення плагіна під коренем плагінів активного state-dir. Використовуйте `--keep-files`, щоб залишити файли на диску.
`--keep-config` підтримується як застарілий псевдонім для `--keep-files`.
@ -207,66 +204,43 @@ openclaw plugins update @openclaw/voice-call@beta
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
```
Оновлення застосовуються до відстежуваних встановлень плагінів у керованому журналі встановлень і відстежуваних встановлень наборів хуків у `hooks.internal.installs`.
Оновлення застосовуються до відстежуваних встановлень плагінів у керованому індексі плагінів і до відстежуваних встановлень наборів хуків у `hooks.internal.installs`.
Коли ви передаєте id плагіна, OpenClaw повторно використовує записану специфікацію встановлення для цього плагіна. Це означає, що раніше збережені dist-tag, такі як `@beta`, і точні закріплені версії й надалі використовуватимуться в наступних запусках `update <id>`.
Коли ви передаєте id плагіна, OpenClaw повторно використовує записану специфікацію встановлення для цього плагіна. Це означає, що раніше збережені dist-tag, наприклад `@beta`, і точні закріплені версії надалі також використовуватимуться в наступних запусках `update <id>`.
Для встановлень із npm ви також можете передати явну npm-spec пакета з dist-tag
або точною версією. OpenClaw зіставляє цю назву пакета назад із записом
відстежуваного плагіна, оновлює цей встановлений плагін і записує нову npm-spec
для майбутніх оновлень за id.
Для встановлень npm ви також можете передати явну npm-специфікацію пакета з dist-tag або точною версією. OpenClaw зіставляє цю назву пакета з відстежуваним записом плагіна, оновлює цей встановлений плагін і записує нову npm-специфікацію для майбутніх оновлень за id.
Передавання назви npm-пакета без версії або тега також зіставляється назад із
записом відстежуваного плагіна. Використовуйте це, коли плагін був закріплений
на точній версії і ви хочете повернути його до типової гілки випусків реєстру.
Передавання назви npm-пакета без версії або тега також зіставляється з відстежуваним записом плагіна. Використовуйте це, коли плагін був закріплений на точній версії, а ви хочете повернути його до типової лінійки випусків реєстру.
Перед живим оновленням npm OpenClaw перевіряє версію встановленого пакета
відносно метаданих реєстру npm. Якщо встановлена версія та записана
ідентичність артефакту вже відповідають цільовому результату розв’язання,
оновлення пропускається без завантаження, перевстановлення або перезапису `openclaw.json`.
Перед живим оновленням npm OpenClaw перевіряє встановлену версію пакета за метаданими реєстру npm. Якщо встановлена версія та ідентичність записаного артефакту вже збігаються з розв’язаною ціллю, оновлення пропускається без завантаження, перевстановлення чи перезапису `openclaw.json`.
Коли існує збережений хеш цілісності й хеш отриманого артефакту змінюється,
OpenClaw розглядає це як дрейф npm-артефакту. Інтерактивна команда
`openclaw plugins update` друкує очікуваний і фактичний хеші та запитує
підтвердження перед продовженням. Неінтерактивні допоміжні засоби оновлення
завершуються захищеною відмовою, якщо викликач не задає явну політику продовження.
Коли існує збережений хеш цілісності і хеш отриманого артефакту змінюється, OpenClaw розглядає це як дрейф артефакту npm. Інтерактивна команда `openclaw plugins update` показує очікувані й фактичні хеші та просить підтвердження перед продовженням. Неінтерактивні допоміжні засоби оновлення завершуються без змін, якщо викликач не передасть явну політику продовження.
`--dangerously-force-unsafe-install` також доступний для `plugins update` як
аварійний override для хибнопозитивних спрацьовувань вбудованого сканування
небезпечного коду під час оновлень плагінів. Він, як і раніше, не обходить
блокування політики `before_install` для плагіна або блокування через збої
сканування, і застосовується лише до оновлень плагінів, а не до оновлень
наборів хуків.
`--dangerously-force-unsafe-install` також доступний у `plugins update` як аварійне перевизначення для хибнопозитивних результатів вбудованого сканування небезпечного коду під час оновлення плагінів. Він так само не обходить блокування політики `before_install` плагіна або блокування через збої сканування і застосовується лише до оновлень плагінів, а не до оновлень наборів хуків.
### Inspect
### Перевірка
```bash
openclaw plugins inspect <id>
openclaw plugins inspect <id> --json
```
Глибока інтроспекція для одного плагіна. Показує ідентичність, стан
завантаження, джерело, зареєстровані можливості, хуки, інструменти, команди,
сервіси, методи gateway, HTTP-маршрути, прапорці політик, diagnostics,
метадані встановлення, можливості пакета та будь-яку виявлену підтримку MCP
або LSP-сервера.
Глибока інтроспекція для одного плагіна. Показує ідентичність, статус завантаження, джерело, зареєстровані можливості, хуки, інструменти, команди, сервіси, методи gateway, HTTP-маршрути, прапорці політик, діагностику, метадані встановлення, можливості пакета та будь-яку виявлену підтримку серверів MCP або LSP.
Кожен плагін класифікується за тим, що саме він фактично реєструє під час runtime:
Кожен плагін класифікується за тим, що саме він реєструє під час виконання:
- **plain-capability** — один тип можливостей (наприклад, плагін лише з provider)
- **hybrid-capability** — кілька типів можливостей (наприклад, text + speech + images)
- **plain-capability** — один тип можливостей (наприклад, плагін лише з провайдером)
- **hybrid-capability** — кілька типів можливостей (наприклад, текст + мовлення + зображення)
- **hook-only** — лише хуки, без можливостей або поверхонь
- **non-capability** — tools/commands/services, але без можливостей
Докладніше про модель можливостей див. у [Plugin shapes](/uk/plugins/architecture#plugin-shapes).
Докладніше про модель можливостей див. у [Форми Plugin](/uk/plugins/architecture#plugin-shapes).
Прапорець `--json` виводить машинозчитуваний звіт, придатний для сценаріїв і
аудиту.
Прапорець `--json` виводить машиночитний звіт, придатний для скриптів і аудиту.
`inspect --all` виводить загальну таблицю з колонками shape, capability kinds,
compatibility notices, bundle capabilities і hook summary.
`inspect --all` відображає загальносистемну таблицю зі стовпцями форми, типів можливостей, повідомлень про сумісність, можливостей пакета та зведення хуків.
`info` — це псевдонім для `inspect`.
`info` є псевдонімом для `inspect`.
### Doctor
@ -274,15 +248,11 @@ compatibility notices, bundle capabilities і hook summary.
openclaw plugins doctor
```
`doctor` повідомляє про помилки завантаження плагінів, diagnostics
маніфестів/виявлення та повідомлення про сумісність. Коли все чисто, він
виводить `No plugin issues detected.`
`doctor` повідомляє про помилки завантаження плагінів, діагностику маніфестів/виявлення та повідомлення про сумісність. Коли все гаразд, він виводить `No plugin issues detected.`
Для збоїв форми модуля, таких як відсутні експорти `register`/`activate`,
запустіть повторно з `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб включити стислий
підсумок форми експорту в діагностичний вивід.
Для збоїв форми модуля, таких як відсутні експорти `register`/`activate`, перезапустіть із `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб включити в діагностичний вивід стислий підсумок форми експортів.
### Registry
### Реєстр
```bash
openclaw plugins registry
@ -290,21 +260,11 @@ openclaw plugins registry --refresh
openclaw plugins registry --json
```
Локальний реєстр плагінів — це збережена модель холодного читання OpenClaw для
ідентичності встановлених плагінів, стану ввімкнення, метаданих джерела та
володіння внесками. Звичайний запуск, пошук власника provider, класифікація
налаштування каналів і перелік плагінів можуть читати його без імпорту
runtime-модулів плагінів.
Локальний реєстр плагінів — це збережена холодна модель читання OpenClaw для ідентичності встановлених плагінів, стану ввімкнення, метаданих джерела та належності внесків. Звичайний запуск, пошук власника провайдера, класифікація налаштування каналу та інвентар плагінів можуть читати його без імпортування runtime-модулів плагінів.
Використовуйте `plugins registry`, щоб перевірити, чи існує збережений реєстр,
чи він актуальний, чи застарілий. Використовуйте `--refresh`, щоб перебудувати
його зі сталого журналу встановлень, політики конфігурації та метаданих
маніфесту/пакета. Це шлях відновлення, а не шлях активації під час runtime.
Використовуйте `plugins registry`, щоб перевірити, чи збережений реєстр наявний, актуальний чи застарілий. Використовуйте `--refresh`, щоб перебудувати його на основі збереженого індексу плагінів, політики конфігурації та метаданих маніфесту/пакета. Це шлях відновлення, а не шлях runtime-активації.
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — це застарілий аварійний
перемикач сумісності для збоїв читання реєстру. Надавайте перевагу `plugins registry
--refresh` або `openclaw doctor --fix`; резервний env-варіант призначений лише
для аварійного відновлення запуску під час розгортання міграції.
`OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — це застарілий аварійний перемикач сумісності для збоїв читання реєстру. Віддавайте перевагу `plugins registry --refresh` або `openclaw doctor --fix`; резервний варіант через env призначений лише для аварійного відновлення запуску під час розгортання міграції.
### Marketplace
@ -313,13 +273,10 @@ openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
```
Список marketplace приймає локальний шлях marketplace, шлях до `marketplace.json`,
скорочення GitHub на кшталт `owner/repo`, URL GitHub repo або git URL. `--json`
виводить мітку розв’язаного джерела, а також розібраний маніфест marketplace і
записи плагінів.
Список marketplace приймає локальний шлях до marketplace, шлях `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL репозиторію GitHub або URL git. `--json` виводить мітку розв’язаного джерела, а також розібраний маніфест marketplace і записи плагінів.
## Пов’язано
- [Довідка CLI](/uk/cli)
- [Довідник CLI](/uk/cli)
- [Створення плагінів](/uk/plugins/building-plugins)
- [Плагіни спільноти](/uk/plugins/community)
- [Спільнотні плагіни](/uk/plugins/community)

183
docs/uk/concepts/agent-runtimes.md
View File

@ -1,40 +1,40 @@
---
read_when:
- Ви обираєте між PI, Codex, ACP або іншим нативним runtime агента
- Ви плутаєтеся в мітках провайдера/моделі/runtime у status або конфігурації
- Ви документуєте паритет підтримки для нативного harness
summary: Як OpenClaw розділяє провайдерів моделей, моделі, канали та runtimes агентів
title: Runtimes агентів
- Ви обираєте між PI, Codex, ACP або іншим нативним середовищем виконання агента
- Вас бентежать позначки постачальника/моделі/середовища виконання в статусі або конфігурації
- Ви документуєте паритет підтримки для нативного каркаса
summary: Як OpenClaw розділяє постачальників моделей, моделі, канали та середовища виконання агентів
title: Середовища виконання агентів
x-i18n:
generated_at: "2026-04-25T05:55:45Z"
generated_at: "2026-04-26T00:18:16Z"
model: gpt-5.4
provider: openai
source_hash: 6f492209da2334361060f0827c243d5d845744be906db9ef116ea00384879b33
source_hash: 2216802244a2886b92f5779a983eaaef6d944849ca41725068b346365da52aa3
source_path: concepts/agent-runtimes.md
workflow: 15
---
**Runtime агента** — це компонент, який володіє одним підготовленим циклом моделі: він
отримує prompt, керує виводом моделі, обробляє нативні виклики інструментів і повертає
завершений хід назад до OpenClaw.
**Середовище виконання агента** — це компонент, який керує одним підготовленим циклом моделі: він
отримує промпт, керує виводом моделі, обробляє нативні виклики інструментів і повертає
завершений хід до OpenClaw.
Runtimes легко сплутати з провайдерами, тому що обидва з’являються поруч із
конфігурацією моделі. Але це різні шари:
Середовища виконання легко сплутати з постачальниками, оскільки обидва відображаються поруч із
конфігурацією моделі. Це різні рівні:
| Шар | Приклади | Що це означає |
| ------------ | ------------------------------------- | ------------------------------------------------------------------ |
| Провайдер | `openai`, `anthropic`, `openai-codex` | Як OpenClaw автентифікується, виявляє моделі та називає model ref. |
| Модель | `gpt-5.5`, `claude-opus-4-6` | Модель, вибрана для ходу агента. |
| Runtime агента | `pi`, `codex`, runtimes на основі ACP | Низькорівневий цикл, який виконує підготовлений хід. |
| Канал | Telegram, Discord, Slack, WhatsApp | Звідки повідомлення надходять до OpenClaw і куди виходять. |
| Рівень | Приклади | Що це означає |
| --------------- | ------------------------------------- | ------------------------------------------------------------------- |
| Постачальник | `openai`, `anthropic`, `openai-codex` | Як OpenClaw автентифікується, виявляє моделі та називає посилання на моделі. |
| Модель | `gpt-5.5`, `claude-opus-4-6` | Модель, вибрана для ходу агента. |
| Середовище виконання агента | `pi`, `codex`, середовища виконання на базі ACP | Низькорівневий цикл, який виконує підготовлений хід. |
| Канал | Telegram, Discord, Slack, WhatsApp | Звідки повідомлення надходять до OpenClaw і куди виходять. |
Ви також побачите слово **harness** у коді та конфігурації. Harness — це
реалізація, яка надає runtime агента. Наприклад, вбудований harness Codex
реалізує runtime `codex`. Ключ конфігурації, як і раніше, має назву
`embeddedHarness` для сумісності, але в користувацькій документації та виводі status
зазвичай слід використовувати слово runtime.
У коді та конфігурації ви також побачите слово **harness**. Harness — це
реалізація, яка надає середовище виконання агента. Наприклад, вбудований Codex
harness реалізує середовище виконання `codex`. Ключ конфігурації досі називається
`embeddedHarness` для сумісності, але в документації для користувачів і у виведенні статусу
зазвичай слід використовувати термін runtime.
Типове налаштування Codex використовує провайдера `openai` з runtime `codex`:
Поширене налаштування Codex використовує постачальника `openai` із середовищем виконання `codex`:
```json5
{
@ -49,93 +49,106 @@ Runtimes легко сплутати з провайдерами, тому що
}
```
Це означає, що OpenClaw вибирає model ref OpenAI, а потім просить app-server
runtime Codex виконати вбудований хід агента. Це не означає, що канал, каталог
провайдера моделей або сховище сесій OpenClaw стає Codex.
Це означає, що OpenClaw вибирає посилання на модель OpenAI, а потім просить
середовище виконання app-server Codex запустити вбудований хід агента. Це не означає, що
канал, каталог постачальника моделей або сховище сесій OpenClaw стають Codex.
Про розділення префіксів у сімействі OpenAI див. [OpenAI](/uk/providers/openai) і
[Провайдери моделей](/uk/concepts/model-providers). Про контракт підтримки runtime
Codex див. [Codex harness](/uk/plugins/codex-harness#v1-support-contract).
Коли ввімкнено вбудований Plugin `codex`, керування Codex природною мовою
має використовувати нативну поверхню команд `/codex` (`/codex bind`, `/codex threads`,
`/codex resume`, `/codex steer`, `/codex stop`) замість ACP. Використовуйте ACP для
Codex лише тоді, коли користувач явно просить ACP/acpx або тестує шлях адаптера ACP.
Claude Code, Gemini CLI, OpenCode, Cursor та подібні зовнішні harness-и, як і раніше, використовують ACP.
## Володіння runtime
| Ви маєте на увазі... | Використовуйте... |
| -------------------------------------- | --------------------------------------------- |
| Керування чатом/тредами app-server Codex | `/codex ...` із вбудованого Plugin `codex` |
| Вбудоване середовище виконання агента app-server Codex | `embeddedHarness.runtime: "codex"` |
| OAuth OpenAI Codex у виконавці PI | посилання на моделі `openai-codex/*` |
| Claude Code або інший зовнішній harness | ACP/acpx |
Різні runtimes володіють різними частинами циклу.
Щоб дізнатися про розділення префіксів сімейства OpenAI, див. [OpenAI](/uk/providers/openai) і
[Постачальники моделей](/uk/concepts/model-providers). Щоб дізнатися про контракт підтримки
середовища виконання Codex, див. [Codex harness](/uk/plugins/codex-harness#v1-support-contract).
| Поверхня | Вбудований PI в OpenClaw | App-server Codex |
| --------------------------- | --------------------------------------- | --------------------------------------------------------------------------- |
| Власник циклу моделі | OpenClaw через вбудований runner PI | App-server Codex |
| Канонічний стан потоку | Транскрипт OpenClaw | Потік Codex плюс дзеркало транскрипту OpenClaw |
| Динамічні tools OpenClaw | Нативний цикл tools OpenClaw | Перекидаються через адаптер Codex |
| Нативні shell- і file-tools | Шлях PI/OpenClaw | Нативні tools Codex, перекинуті через нативні hooks там, де це підтримується |
| Рушій контексту | Нативне збирання контексту OpenClaw | Контекст, зібраний OpenClaw projects у хід Codex |
| Compaction | OpenClaw або вибраний рушій контексту | Нативний Compaction Codex зі сповіщеннями OpenClaw і підтримкою дзеркала |
| Доставка каналом | OpenClaw | OpenClaw |
## Володіння середовищем виконання
Цей поділ володіння — головне правило проєктування:
Різні середовища виконання керують різними частинами циклу.
- Якщо поверхнею володіє OpenClaw, OpenClaw може забезпечити звичайну поведінку hooks плагінів.
- Якщо поверхнею володіє нативний runtime, OpenClaw потребує подій runtime або нативних hooks.
- Якщо нативний runtime володіє канонічним станом потоку, OpenClaw має віддзеркалювати та проєктувати контекст, а не переписувати непідтримувані внутрішні механізми.
| Поверхня | Вбудований OpenClaw PI | app-server Codex |
| --------------------------- | --------------------------------------- | -------------------------------------------------------------------------- |
| Власник циклу моделі | OpenClaw через вбудований виконавець PI | app-server Codex |
| Канонічний стан треду | Транскрипт OpenClaw | Тред Codex плюс дзеркало транскрипту OpenClaw |
| Динамічні інструменти OpenClaw | Нативний цикл інструментів OpenClaw | Мостяться через адаптер Codex |
| Нативні shell- та файлові інструменти | Шлях PI/OpenClaw | Нативні інструменти Codex, що мостяться через нативні хуки, де це підтримується |
| Рушій контексту | Нативне збирання контексту OpenClaw | OpenClaw projects зібрали контекст у хід Codex |
| Compaction | OpenClaw або вибраний рушій контексту | Нативний Compaction Codex із сповіщеннями OpenClaw і підтримкою дзеркала |
| Доставка через канал | OpenClaw | OpenClaw |
## Вибір runtime
Це розділення володіння є головним правилом дизайну:
OpenClaw вибирає вбудований runtime після визначення провайдера й моделі:
- Якщо поверхнею володіє OpenClaw, OpenClaw може надавати звичайну поведінку хуків Plugin.
- Якщо поверхнею володіє нативне середовище виконання, OpenClaw потребує подій середовища виконання або нативних хуків.
- Якщо нативне середовище виконання володіє канонічним станом треду, OpenClaw має дзеркалити та проєктувати контекст, а не переписувати непідтримувані внутрішні механізми.
1. Перевагу має runtime, записаний у сесії. Зміни конфігурації не перемикають
наявний транскрипт на іншу нативну систему потоків «на гарячу».
2. `OPENCLAW_AGENT_RUNTIME=<id>` примусово задає цей runtime для нових або скинутих сесій.
## Вибір середовища виконання
OpenClaw вибирає вбудоване середовище виконання після визначення постачальника й моделі:
1. Пріоритет має записане для сесії середовище виконання. Зміни конфігурації не перемикають
на гарячу вже наявний транскрипт на іншу нативну систему тредів.
2. `OPENCLAW_AGENT_RUNTIME=<id>` примусово задає це середовище виконання для нових або скинутих сесій.
3. `agents.defaults.embeddedHarness.runtime` або
`agents.list[].embeddedHarness.runtime` можуть задавати `auto`, `pi` або зареєстрований
id runtime, наприклад `codex`.
4. У режимі `auto` зареєстровані plugin runtimes можуть заявляти підтримувані пари провайдер/модель.
5. Якщо в режимі `auto` жоден runtime не бере на себе хід і задано `fallback: "pi"`
(типове значення), OpenClaw використовує PI як сумісний fallback. Установіть
`fallback: "none"`, щоб замість цього вибір у режимі `auto` без відповідника завершувався помилкою.
`agents.list[].embeddedHarness.runtime` можуть встановлювати `auto`, `pi` або зареєстрований
ідентифікатор середовища виконання, наприклад `codex`.
4. У режимі `auto` зареєстровані середовища виконання Plugin можуть заявляти про підтримувані пари постачальник/модель.
5. Якщо в режимі `auto` жодне середовище виконання не бере хід на себе і встановлено
`fallback: "pi"` (це значення за замовчуванням), OpenClaw використовує PI як сумісний запасний варіант. Установіть
`fallback: "none"`, щоб вибір у режимі `auto` завершувався помилкою для невідповідних випадків.
Явно задані plugin runtimes за замовчуванням працюють у режимі fail closed. Наприклад,
`runtime: "codex"` означає Codex або явну помилку вибору, якщо ви не задасте
`fallback: "pi"` у тому самому обсязі перевизначення. Перевизначення runtime не успадковує
ширше налаштування fallback, тому `runtime: "codex"` на рівні агента не буде мовчки
спрямовано назад до PI лише тому, що в defaults використовувався `fallback: "pi"`.
Явно вказані середовища виконання Plugin за замовчуванням працюють у режимі fail closed. Наприклад,
`runtime: "codex"` означає Codex або явну помилку вибору, якщо ви не встановите
`fallback: "pi"` у тій самій області перевизначення. Перевизначення середовища виконання не успадковує
ширше значення fallback, тому `runtime: "codex"` на рівні агента не буде мовчки
повернуто до PI лише тому, що в defaults використовувалося `fallback: "pi"`.
## Контракт сумісності
Коли runtime — не PI, він має документувати, які поверхні OpenClaw він підтримує.
Використовуйте таку форму для документації runtime:
Коли середовище виконання — не PI, воно має документувати, які поверхні OpenClaw воно підтримує.
Для документації середовища виконання використовуйте таку форму:
| Питання | Чому це важливо |
| ------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Хто володіє циклом моделі? | Визначає, де відбуваються повторні спроби, продовження tools і рішення щодо фінальної відповіді. |
| Хто володіє канонічною історією потоку? | Визначає, чи може OpenClaw редагувати історію, чи лише віддзеркалювати її. |
| Чи працюють динамічні tools OpenClaw? | Від цього залежать повідомлення, сесії, Cron і tools, якими володіє OpenClaw. |
| Чи працюють hooks динамічних tools? | Плагіни очікують `before_tool_call`, `after_tool_call` і middleware навколо tools OpenClaw. |
| Чи працюють hooks нативних tools? | Shell, patch і tools, якими володіє runtime, потребують підтримки нативних hooks для політик і спостереження. |
| Чи виконується життєвий цикл рушія контексту? | Плагіни пам’яті й контексту залежать від життєвого циклу assemble, ingest, after-turn і Compaction. |
| Які дані Compaction доступні? | Деяким плагінам потрібні лише сповіщення, тоді як іншим потрібні метадані збереженого/відкинутого. |
| Що навмисно не підтримується? | Користувачі не повинні припускати еквівалентність PI там, де нативний runtime володіє більшим обсягом стану. |
| Питання | Чому це важливо |
| ------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Хто володіє циклом моделі? | Визначає, де відбуваються повторні спроби, продовження інструментів і рішення щодо фінальної відповіді. |
| Хто володіє канонічною історією треду? | Визначає, чи може OpenClaw редагувати історію, чи лише дзеркалити її. |
| Чи працюють динамічні інструменти OpenClaw? | Від цього залежать повідомлення, сесії, Cron та інструменти, якими володіє OpenClaw. |
| Чи працюють хуки динамічних інструментів? | Plugins очікують `before_tool_call`, `after_tool_call` і middleware навколо інструментів, якими володіє OpenClaw. |
| Чи працюють хуки нативних інструментів? | Shell, patch та інструменти, якими володіє середовище виконання, потребують підтримки нативних хуків для політик і спостереження. |
| Чи запускається життєвий цикл рушія контексту? | Plugins пам’яті та контексту залежать від життєвого циклу assemble, ingest, after-turn і Compaction. |
| Які дані Compaction доступні? | Деяким Plugins потрібні лише сповіщення, тоді як іншим потрібні метадані про збережене/відкинуте. |
| Що навмисно не підтримується? | Користувачі не повинні припускати еквівалентність PI там, де нативне середовище виконання володіє більшою частиною стану. |
Контракт підтримки runtime Codex задокументовано в
Контракт підтримки середовища виконання Codex задокументовано в
[Codex harness](/uk/plugins/codex-harness#v1-support-contract).
## Мітки status
## Позначки статусу
Вивід status може показувати мітки `Execution` і `Runtime`. Сприймайте їх як
діагностичні позначення, а не як назви провайдерів.
У виведенні статусу можуть відображатися позначки `Execution` і `Runtime`. Сприймайте їх як
діагностичні дані, а не як назви постачальників.
- Model ref, наприклад `openai/gpt-5.5`, показує вибраний провайдер/модель.
- Id runtime, наприклад `codex`, показує, який цикл виконує хід.
- Мітка каналу, наприклад Telegram або Discord, показує, де відбувається розмова.
- Посилання на модель, таке як `openai/gpt-5.5`, вказує на вибраного постачальника/модель.
- Ідентифікатор середовища виконання, такий як `codex`, вказує, який цикл виконує хід.
- Позначка каналу, така як Telegram або Discord, вказує, де відбувається розмова.
Якщо сесія все ще показує PI після зміни конфігурації runtime, почніть нову сесію
за допомогою `/new` або очистьте поточну за допомогою `/reset`. Наявні сесії зберігають
свій записаний runtime, щоб транскрипт не відтворювався через дві несумісні нативні
Якщо після зміни конфігурації середовища виконання сесія все ще показує PI, почніть нову сесію
за допомогою `/new` або очистіть поточну за допомогою `/reset`. Наявні сесії зберігають своє
записане середовище виконання, щоб транскрипт не відтворювався через дві несумісні нативні
системи сесій.
## Пов’язане
- [Codex harness](/uk/plugins/codex-harness)
- [OpenAI](/uk/providers/openai)
- [Плагіни harness агентів](/uk/plugins/sdk-agent-harness)
- [Plugins harness агента](/uk/plugins/sdk-agent-harness)
- [Цикл агента](/uk/concepts/agent-loop)
- [Моделі](/uk/concepts/models)
- [Status](/uk/cli/status)
- [Статус](/uk/cli/status)

141
docs/uk/gateway/bonjour.md
View File

@ -1,14 +1,14 @@
---
read_when:
- Налагодження проблем із виявленням Bonjour на macOS/iOS
- Налагодження проблем виявлення Bonjour на macOS/iOS
- Зміна типів сервісів mDNS, записів TXT або UX виявлення
summary: Виявлення та налагодження Bonjour/mDNS (маяки Gateway, клієнти та типові режими збоїв)
summary: Виявлення та налагодження Bonjour/mDNS (маяки Gateway, клієнти та поширені режими відмови)
title: Виявлення Bonjour
x-i18n:
generated_at: "2026-04-24T06:33:43Z"
generated_at: "2026-04-26T00:18:18Z"
model: gpt-5.4
provider: openai
source_hash: 62961714a0c9880be457c254e1cfc1701020ea51b89f2582757cddc8b3dd2113
source_hash: ced3a4a81ab6a4e8c32a33c967ff3e173485c3e644885192012eaca8b81a065f
source_path: gateway/bonjour.md
workflow: 15
---
@ -16,46 +16,46 @@ x-i18n:
# Виявлення Bonjour / mDNS
OpenClaw використовує Bonjour (mDNS / DNS‑SD) для виявлення активного Gateway (кінцевої точки WebSocket).
Браузинг multicast `local.` — це **лише зручність у межах LAN**. Вбудований Plugin `bonjour`
відповідає за рекламу в LAN і ввімкнений за замовчуванням. Для виявлення між різними мережами
той самий маяк також може бути опублікований через налаштований домен wide-area DNS-SD.
Виявлення все одно залишається best-effort і **не** замінює підключення через SSH або Tailnet.
Багатоадресний перегляд `local.` — це **зручність лише для LAN**. Вбудований
plugin `bonjour` відповідає за рекламування в LAN і ввімкнений за замовчуванням. Для міжмережевого виявлення
той самий маяк також може публікуватися через налаштований домен DNS-SD широкої зони.
Виявлення все одно є best-effort і **не** замінює підключення через SSH або Tailnet.
## Wide-area Bonjour (Unicast DNS-SD) через Tailscale
## Bonjour широкої зони (Unicast DNS-SD) через Tailscale
Якщо node і gateway перебувають у різних мережах, multicast mDNS не перетне
Якщо Node і Gateway перебувають у різних мережах, багатоадресний mDNS не перетне
цю межу. Ви можете зберегти той самий UX виявлення, переключившись на **unicast DNS‑SD**
("Wide‑Area Bonjour") через Tailscale.
("Bonjour широкої зони") через Tailscale.
Кроки на високому рівні:
Загальні кроки:
1. Запустіть DNS-сервер на хості gateway (доступний через Tailnet).
2. Опублікуйте записи DNS‑SD для `_openclaw-gw._tcp` у межах виділеної зони
1. Запустіть DNS-сервер на хості Gateway (доступний через Tailnet).
2. Опублікуйте записи DNS‑SD для `_openclaw-gw._tcp` у виділеній зоні
(приклад: `openclaw.internal.`).
3. Налаштуйте **split DNS** у Tailscale, щоб вибраний вами домен резолвився через цей
3. Налаштуйте в Tailscale **split DNS**, щоб вибраний вами домен резолвився через цей
DNS-сервер для клієнтів (зокрема iOS).
OpenClaw підтримує будь-який домен виявлення; `openclaw.internal.` — лише приклад.
Node на iOS/Android переглядають і `local.`, і ваш налаштований wide-area домен.
Node на iOS/Android переглядають і `local.`, і налаштований вами домен широкої зони.
### Конфігурація Gateway (рекомендовано)
```json5
{
gateway: { bind: "tailnet" }, // лише tailnet (рекомендовано)
discovery: { wideArea: { enabled: true } }, // вмикає публікацію wide-area DNS-SD
discovery: { wideArea: { enabled: true } }, // вмикає публікацію DNS-SD широкої зони
}
```
### Одноразове налаштування DNS-сервера (хост gateway)
### Одноразове налаштування DNS-сервера (хост Gateway)
```bash
openclaw dns setup --apply
```
Це встановлює CoreDNS і налаштовує його так, щоб він:
Це встановить CoreDNS і налаштує його так, щоб він:
- слухав порт 53 лише на Tailscale-інтерфейсах gateway
- слухав порт 53 лише на інтерфейсах Tailscale Gateway
- обслуговував вибраний вами домен (приклад: `openclaw.internal.`) з `~/.openclaw/dns/<domain>.db`
Перевірте з машини, підключеної до tailnet:
@ -69,55 +69,55 @@ dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short
У консолі адміністрування Tailscale:
- Додайте nameserver, що вказує на tailnet IP gateway (UDP/TCP 53).
- Додайте nameserver, що вказує на tailnet IP Gateway (UDP/TCP 53).
- Додайте split DNS, щоб ваш домен виявлення використовував цей nameserver.
Щойно клієнти приймуть DNS tailnet, node на iOS і виявлення CLI зможуть переглядати
`_openclaw-gw._tcp` у вашому домені виявлення без multicast.
Після того як клієнти приймуть DNS tailnet, Node на iOS і виявлення через CLI зможуть переглядати
`_openclaw-gw._tcp` у вашому домені виявлення без багатоадресності.
### Безпека слухача Gateway (рекомендовано)
Порт WS Gateway (типово `18789`) за замовчуванням прив’язується до loopback. Для доступу з LAN/tailnet
явно задайте bind і залиште автентифікацію ввімкненою.
явно задайте прив’язку та залиште автентифікацію ввімкненою.
Для конфігурацій лише з tailnet:
- Встановіть `gateway.bind: "tailnet"` у `~/.openclaw/openclaw.json`.
- Перезапустіть Gateway (або перезапустіть застосунок menubar на macOS).
- Установіть `gateway.bind: "tailnet"` у `~/.openclaw/openclaw.json`.
- Перезапустіть Gateway (або перезапустіть застосунок рядка меню macOS).
## Що рекламується
Лише Gateway рекламує `_openclaw-gw._tcp`. Рекламу через multicast у LAN
забезпечує вбудований Plugin `bonjour`; публікація wide-area DNS-SD і надалі
Лише Gateway рекламує `_openclaw-gw._tcp`. Рекламування багатоадресності в LAN
забезпечується вбудованим plugin `bonjour`; публікація DNS-SD широкої зони й надалі
належить Gateway.
## Типи сервісів
- `_openclaw-gw._tcp` — транспортний маяк gateway (використовується node на macOS/iOS/Android).
- `_openclaw-gw._tcp` — транспортний маяк gateway (використовується Node на macOS/iOS/Android).
## Ключі TXT (не секретні підказки)
## Ключі TXT (несекретні підказки)
Gateway рекламує невеликі не секретні підказки, щоб зробити UI-потоки зручнішими:
Gateway рекламує невеликі несекретні підказки, щоб зробити UI-потоки зручнішими:
- `role=gateway`
- `displayName=<дружня назва>`
- `lanHost=<hostname>.local`
- `gatewayPort=<port>` (Gateway WS + HTTP)
- `gatewayPort=<port>` (WS + HTTP Gateway)
- `gatewayTls=1` (лише коли TLS увімкнено)
- `gatewayTlsSha256=<sha256>` (лише коли TLS увімкнено і відбиток доступний)
- `canvasPort=<port>` (лише коли хост canvas увімкнено; наразі той самий, що й `gatewayPort`)
- `gatewayTlsSha256=<sha256>` (лише коли TLS увімкнено і доступний відбиток)
- `canvasPort=<port>` (лише коли ввімкнено хост canvas; наразі такий самий, як `gatewayPort`)
- `transport=gateway`
- `tailnetDns=<magicdns>` (лише в режимі mDNS full; необов’язкова підказка, коли Tailnet доступний)
- `sshPort=<port>` (лише в режимі mDNS full; wide-area DNS-SD може його не містити)
- `cliPath=<path>` (лише в режимі mDNS full; wide-area DNS-SD усе одно записує його як підказку для віддаленого встановлення)
- `tailnetDns=<magicdns>` (лише у повному режимі mDNS, необов’язкова підказка, коли доступний Tailnet)
- `sshPort=<port>` (лише у повному режимі mDNS; DNS-SD широкої зони може його не включати)
- `cliPath=<path>` (лише у повному режимі mDNS; DNS-SD широкої зони все одно записує його як підказку для віддаленого встановлення)
Примітки щодо безпеки:
- Записи Bonjour/mDNS TXT **неавтентифіковані**. Клієнти не повинні вважати TXT авторитетним джерелом маршрутизації.
- Клієнтам слід маршрутизувати, використовуючи резолвлену кінцеву точку сервісу (SRV + A/AAAA). Сприймайте `lanHost`, `tailnetDns`, `gatewayPort` і `gatewayTlsSha256` лише як підказки.
- Автоматичне визначення цілі для SSH так само має використовувати резолвлений хост сервісу, а не лише підказки з TXT.
- Записи TXT у Bonjour/mDNS **неавтентифіковані**. Клієнти не повинні вважати TXT авторитетним джерелом маршрутизації.
- Клієнти повинні маршрутизувати за допомогою резолвленої кінцевої точки сервісу (SRV + A/AAAA). Розглядайте `lanHost`, `tailnetDns`, `gatewayPort` і `gatewayTlsSha256` лише як підказки.
- Автоматичне націлювання SSH так само повинно використовувати резолвлений хост сервісу, а не лише підказки з TXT.
- TLS pinning ніколи не повинен дозволяти рекламованому `gatewayTlsSha256` перевизначати раніше збережений pin.
- Node на iOS/Android повинні розглядати прямі підключення, засновані на виявленні, як **лише TLS** і вимагати явного підтвердження користувача перед довірою до відбитка при першому підключенні.
- Node на iOS/Android повинні розглядати прямі підключення на основі виявлення як **лише TLS** і вимагати явного підтвердження користувача перед довірою до відбитка, побаченого вперше.
## Налагодження на macOS
@ -135,57 +135,62 @@ Gateway рекламує невеликі не секретні підказки
dns-sd -L "<instance>" _openclaw-gw._tcp local.
```
Якщо перегляд працює, а резолв — ні, зазвичай це означає проблему політики LAN або
резолвера mDNS.
Якщо перегляд працює, а резолв — ні, зазвичай це означає проблему з політикою LAN або
резолвером mDNS.
## Налагодження в логах Gateway
## Налагодження в журналах Gateway
Gateway записує ротаційний лог-файл (виводиться під час запуску як
Gateway записує журнал у циклічний log-файл (виводиться під час запуску як
`gateway log file: ...`). Шукайте рядки `bonjour:`, особливо:
- `bonjour: advertise failed ...`
- `bonjour: ... name conflict resolved` / `hostname conflict resolved`
- `bonjour: watchdog detected non-announced service ...`
- `bonjour: disabling advertiser after ... failed restarts ...`
## Налагодження на iOS node
## Налагодження на iOS Node
Node на iOS використовує `NWBrowser` для виявлення `_openclaw-gw._tcp`.
iOS Node використовує `NWBrowser` для виявлення `_openclaw-gw._tcp`.
Щоб зібрати логи:
Щоб зібрати журнали:
- Settings → Gateway → Advanced → **Discovery Debug Logs**
- Settings → Gateway → Advanced → **Discovery Logs** → відтворіть проблему → **Copy**
Лог містить переходи стану браузера та зміни набору результатів.
Журнал містить переходи стану браузера та зміни набору результатів.
## Типові режими збоїв
## Поширені режими відмови
- **Bonjour не працює між мережами**: використовуйте Tailnet або SSH.
- **Multicast заблоковано**: деякі Wi‑Fi-мережі вимикають mDNS.
- **Сон / зміна інтерфейсів**: macOS може тимчасово втрачати результати mDNS; повторіть спробу.
- **Перегляд працює, але резолв — ні**: використовуйте прості назви машин (уникайте emoji або
розділових знаків), потім перезапустіть Gateway. Назва екземпляра сервісу походить від
імені хоста, тому надто складні назви можуть збивати з пантелику деякі резолвери.
- **Багатоадресність заблокована**: деякі мережі Wi‑Fi вимикають mDNS.
- **Рекламування застрягло на probing/announcing**: хости із заблокованою багатоадресністю,
мостами контейнерів, WSL або змінами інтерфейсів можуть залишити рекламувальник ciao у
стані без оголошення. OpenClaw повторює спробу кілька разів, а потім вимикає Bonjour
для поточного процесу Gateway замість безкінечного перезапуску рекламувальника.
- **Сон / зміни інтерфейсів**: macOS може тимчасово втрачати результати mDNS; повторіть спробу.
- **Перегляд працює, а резолв — ні**: використовуйте прості назви машин (уникайте емодзі чи
розділових знаків), а потім перезапустіть Gateway. Ім’я екземпляра сервісу походить від
імені хоста, тому надто складні імена можуть заплутати деякі резолвери.
## Екрановані назви екземплярів (`\032`)
## Екрановані імена екземплярів (`\032`)
Bonjour/DNS‑SD часто екранує байти в назвах екземплярів сервісів як десяткові послідовності `\DDD`
Bonjour/DNS‑SD часто екранує байти в іменах екземплярів сервісів як десяткові послідовності `\DDD`
(наприклад, пробіли стають `\032`).
- Це нормально на рівні протоколу.
- UI мають декодувати це для відображення (iOS використовує `BonjourEscapes.decode`).
- UI повинні декодувати це для відображення (iOS використовує `BonjourEscapes.decode`).
## Вимкнення / конфігурація
- `openclaw plugins disable bonjour` вимикає рекламу multicast у LAN шляхом вимкнення вбудованого plugin.
- `openclaw plugins enable bonjour` відновлює типовий plugin для виявлення в LAN.
- `OPENCLAW_DISABLE_BONJOUR=1` вимикає рекламу multicast у LAN без зміни конфігурації plugin; приймаються такі truthy-значення: `1`, `true`, `yes` і `on` (застаріле: `OPENCLAW_DISABLE_BONJOUR`).
- `gateway.bind` у `~/.openclaw/openclaw.json` керує режимом bind для Gateway.
- `OPENCLAW_SSH_PORT` перевизначає порт SSH, коли рекламується `sshPort` (застаріле: `OPENCLAW_SSH_PORT`).
- `OPENCLAW_TAILNET_DNS` публікує підказку MagicDNS у TXT, коли ввімкнено режим mDNS full (застаріле: `OPENCLAW_TAILNET_DNS`).
- `OPENCLAW_CLI_PATH` перевизначає рекламований шлях CLI (застаріле: `OPENCLAW_CLI_PATH`).
- `openclaw plugins disable bonjour` вимикає рекламування багатоадресності в LAN, вимикаючи вбудований plugin.
- `openclaw plugins enable bonjour` відновлює типовий plugin виявлення в LAN.
- `OPENCLAW_DISABLE_BONJOUR=1` вимикає рекламування багатоадресності в LAN без зміни конфігурації plugin; допустимі truthy-значення: `1`, `true`, `yes` і `on` (legacy: `OPENCLAW_DISABLE_BONJOUR`).
- `gateway.bind` у `~/.openclaw/openclaw.json` керує режимом прив’язки Gateway.
- `OPENCLAW_SSH_PORT` перевизначає порт SSH, коли рекламується `sshPort` (legacy: `OPENCLAW_SSH_PORT`).
- `OPENCLAW_TAILNET_DNS` публікує підказку MagicDNS у TXT, коли ввімкнено повний режим mDNS (legacy: `OPENCLAW_TAILNET_DNS`).
- `OPENCLAW_CLI_PATH` перевизначає рекламований шлях CLI (legacy: `OPENCLAW_CLI_PATH`).
## Пов’язані документи
## Пов’язана документація
- Політика виявлення та вибір транспорту: [Discovery](/uk/gateway/discovery)
- Спарювання Node + схвалення: [Gateway pairing](/uk/gateway/pairing)
- Політика виявлення та вибір транспорту: [Виявлення](/uk/gateway/discovery)
- Спарювання Node + схвалення: [Спарювання Gateway](/uk/gateway/pairing)

543
docs/uk/gateway/configuration-reference.md
View File

@ -5,62 +5,63 @@ read_when:
summary: Довідник конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем
title: Довідник конфігурації
x-i18n:
generated_at: "2026-04-25T23:50:23Z"
generated_at: "2026-04-26T00:18:15Z"
model: gpt-5.4
provider: openai
source_hash: 6506e09f5bd8d45892bb519ebb66ee827967f785a11dda16e9aea4d941b7cfd1
source_hash: 0c9019c54bb8fbeb9fa52312a8d97ea4481f4cb1bcb38bac745d726eaa648407
source_path: gateway/configuration-reference.md
workflow: 15
---
Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration).
Довідник основної конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration).
Охоплює основні поверхні конфігурації OpenClaw і дає посилання назовні, коли підсистема має власний докладніший довідник. Каталоги команд, що належать каналам і Plugin, а також глибокі параметри пам’яті/QMD винесені на окремі сторінки, а не описуються тут.
Охоплює основні поверхні конфігурації OpenClaw і надає посилання назовні, коли підсистема має власний докладніший довідник. Каталоги команд, що належать каналам і Plugin, а також глибокі параметри пам’яті/QMD розміщені на окремих сторінках, а не на цій.
Джерело істини в коді:
Код як джерело істини:
- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, з об’єднаними метаданими bundled/plugin/channel, коли вони доступні
- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів деталізації
- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють хеш базового рівня документації конфігурації відносно поточної поверхні схеми
- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів детального перегляду
- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш документації конфігурації щодо поточної поверхні схеми
Окремі поглиблені довідники:
Окремі детальні довідники:
- [Довідник конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming`
- [Слеш-команди](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд
- сторінки відповідних каналів/Plugin для поверхонь команд, специфічних для каналів
- [Memory configuration reference](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming`
- [Slash commands](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд
- сторінки відповідних каналів/Plugin для поверхонь команд, специфічних для каналу
Формат конфігурації — **JSON5** (дозволено коментарі + кінцеві коми). Усі поля необов’язкові — якщо їх пропущено, OpenClaw використовує безпечні значення за замовчуванням.
Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено.
---
## Канали
Ключі конфігурації для окремих каналів перенесено на окрему сторінку — див.
Ключі конфігурації окремих каналів перенесено на окрему сторінку — див.
[Configuration — channels](/uk/gateway/config-channels) для `channels.*`,
зокрема Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших
bundled каналів (автентифікація, контроль доступу, кілька облікових записів, керування згадками).
зокрема для Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших
bundled каналів (автентифікація, контроль доступу, кілька облікових записів, обмеження згадок).
## Значення агентів за замовчуванням, multi-agent, сесії та повідомлення
Перенесено на окрему сторінку — див.
[Configuration — agents](/uk/gateway/config-agents) для:
- `agents.defaults.*` (робоча область, модель, thinking, heartbeat, пам’ять, медіа, skills, sandbox)
- `multiAgent.*` (маршрутизація та прив’язки multi-agent)
- `agents.defaults.*` (робочий простір, модель, thinking, heartbeat, пам’ять, медіа, Skills, sandbox)
- `multiAgent.*` (маршрутизація й прив’язки multi-agent)
- `session.*` (життєвий цикл сесії, compaction, очищення)
- `messages.*` (доставка повідомлень, TTS, рендеринг markdown)
- `talk.*` (режим Talk)
- `talk.speechLocale`: необов’язковий ідентифікатор локалі BCP 47 для розпізнавання мовлення Talk на iOS/macOS
- `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS і Android, 900 ms на iOS`)
## Інструменти та власні провайдери
## Інструменти й власні провайдери
Політика інструментів, експериментальні перемикачі, конфігурація інструментів із підтримкою провайдерів і налаштування власних провайдерів / базових URL перенесені на окрему сторінку — див.
Політика інструментів, експериментальні перемикачі, конфігурація інструментів із підтримкою провайдерів, а також налаштування власних
провайдерів / base-URL перенесено на окрему сторінку — див.
[Configuration — tools and custom providers](/uk/gateway/config-tools).
## MCP
Визначення MCP-серверів, якими керує OpenClaw, розміщені в `mcp.servers` і
Визначення MCP-серверів, керованих OpenClaw, розміщуються в `mcp.servers` і
використовуються вбудованим Pi та іншими адаптерами середовища виконання. Команди `openclaw mcp list`,
`show`, `set` і `unset` керують цим блоком без підключення до
цільового сервера під час редагування конфігурації.
@ -89,15 +90,15 @@ bundled каналів (автентифікація, контроль дост
- `mcp.servers`: іменовані визначення stdio або віддалених MCP-серверів для середовищ виконання, які
надають налаштовані MCP-інструменти.
- `mcp.sessionIdleTtlMs`: TTL простою для bundled MCP-середовищ виконання в межах сесії.
Одноразові вбудовані запуски запитують очищення після завершення виконання; цей TTL є резервним механізмом для
- `mcp.sessionIdleTtlMs`: idle TTL для bundled MCP-середовищ виконання на рівні сесії.
Одноразові вбудовані запуски запитують очищення після завершення запуску; цей TTL є резервним механізмом для
довготривалих сесій і майбутніх викликів.
- Зміни в `mcp.*` застосовуються на льоту шляхом вивільнення кешованих MCP-середовищ виконання сесії.
Наступне виявлення/використання інструмента створює їх заново з нової конфігурації, тому видалені
записи `mcp.servers` прибираються негайно, а не чекають завершення TTL простою.
- Зміни в `mcp.*` застосовуються на льоту через вивільнення кешованих MCP-середовищ виконання сесії.
Наступне виявлення/використання інструмента створює їх заново з нової конфігурації, тож видалені
записи `mcp.servers` прибираються негайно, а не чекають завершення idle TTL.
Див. [MCP](/uk/cli/mcp#openclaw-as-an-mcp-client-registry) і
[CLI backends](/uk/gateway/cli-backends#bundle-mcp-overlays) щодо поведінки середовища виконання.
[CLI backends](/uk/gateway/cli-backends#bundle-mcp-overlays) для поведінки середовища виконання.
## Skills
@ -124,13 +125,14 @@ bundled каналів (автентифікація, контроль дост
}
```
- `allowBundled`: необов’язковий список дозволених лише для bundled skills (керовані/workspace skills не зачіпаються).
- `load.extraDirs`: додаткові спільні кореневі каталоги skills (найнижчий пріоритет).
- `install.preferBrew`: якщо `true`, спочатку надається перевага інсталяторам Homebrew, коли доступний `brew`, а вже потім іншим типам інсталяторів.
- `install.nodeManager`: налаштування пріоритетного менеджера Node для специфікацій `metadata.openclaw.install`
- `allowBundled`: необов’язковий список дозволів лише для bundled skills (керовані/робочі Skills не зачіпаються).
- `load.extraDirs`: додаткові спільні кореневі каталоги Skills (найнижчий пріоритет).
- `install.preferBrew`: якщо `true`, надавати перевагу інсталяторам Homebrew, коли `brew`
доступний, перш ніж переходити до інших типів інсталяторів.
- `install.nodeManager`: пріоритет node-інсталятора для специфікацій `metadata.openclaw.install`
(`npm` | `pnpm` | `yarn` | `bun`).
- `entries.<skillKey>.enabled: false` вимикає skill, навіть якщо він bundled/installed.
- `entries.<skillKey>.apiKey`: зручне поле для skills, які оголошують основну змінну середовища (простий рядок або об’єкт SecretRef).
- `entries.<skillKey>.enabled: false` вимикає Skill, навіть якщо він bundled/встановлений.
- `entries.<skillKey>.apiKey`: спрощене поле для Skills, що оголошують основну env-змінну (простий рядок або об’єкт SecretRef).
---
@ -158,48 +160,40 @@ bundled каналів (автентифікація, контроль дост
}
```
- Завантажуються з `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions`, а також з `plugins.load.paths`.
- Виявлення підтримує нативні Plugin OpenClaw, а також сумісні пакети Codex і Claude, включно з пакетами Claude типового макета без маніфесту.
- **Зміни конфігурації вимагають перезапуску gateway.**
- `allow`: необов’язковий список дозволених (завантажуються лише перелічені Plugin). `deny` має пріоритет.
- `plugins.entries.<id>.apiKey`: зручне поле API-ключа на рівні Plugin (коли Plugin це підтримує).
- `plugins.entries.<id>.env`: мапа змінних середовища в межах Plugin.
- `plugins.entries.<id>.hooks.allowPromptInjection`: якщо `false`, ядро блокує `before_prompt_build` та ігнорує поля мутації prompt із застарілого `before_agent_start`, при цьому зберігає застарілі `modelOverride` і `providerOverride`. Застосовується до нативних хуків Plugin і підтримуваних каталогів хуків, наданих пакетами.
- `plugins.entries.<id>.hooks.allowConversationAccess`: якщо `true`, довірені небандловані Plugin можуть читати необроблений вміст розмови з типізованих хуків, таких як `llm_input`, `llm_output` і `agent_end`.
- `plugins.entries.<id>.subagent.allowModelOverride`: явно довіряти цьому Plugin запит перевизначень `provider` і `model` для окремих запусків фонових subagent.
- `plugins.entries.<id>.subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли свідомо хочете дозволити будь-яку модель.
- `plugins.entries.<id>.config`: об’єкт конфігурації, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, якщо вона доступна).
- Налаштування облікових записів/середовища виконання Plugin-каналів містяться в `channels.<id>` і мають описуватися метаданими `channelConfigs` у маніфесті відповідного Plugin, а не центральним реєстром параметрів OpenClaw.
- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl.
- `apiKey`: API-ключ Firecrawl (підтримує SecretRef). Використовує як запасний варіант `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або змінну середовища `FIRECRAWL_API_KEY`.
- Завантажуються з `~/.openclaw/extensions`, `<workspace>/.openclaw/extensions`, а також `plugins.load.paths`.
- Виявлення підтримує нативні Plugin OpenClaw, а також сумісні пакунки Codex і Claude, зокрема пакунки Claude стандартного макета без маніфесту.
- **Зміни конфігурації потребують перезапуску gateway.**
- `allow`: необов’язковий список дозволів (завантажуються лише перелічені Plugin). `deny` має пріоритет.
- `plugins.entries.<id>.apiKey`: спрощене поле API-ключа на рівні Plugin (коли підтримується Plugin).
- `plugins.entries.<id>.env`: карта env-змінних у межах Plugin.
- `plugins.entries.<id>.hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` і ігнорує поля, що змінюють prompt, із застарілого `before_agent_start`, водночас зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hooks Plugin і підтримуваних каталогів hooks, наданих пакунками.
- `plugins.entries.<id>.hooks.allowConversationAccess`: коли `true`, довірені небандловані Plugin можуть читати необроблений вміст розмови з типізованих hooks, таких як `llm_input`, `llm_output` і `agent_end`.
- `plugins.entries.<id>.subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремих запусків фонових subagent.
- `plugins.entries.<id>.subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"`, лише якщо ви свідомо хочете дозволити будь-яку модель.
- `plugins.entries.<id>.config`: об’єкт конфігурації, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, якщо доступна).
- Налаштування облікових записів/середовища виконання channel Plugin розміщуються в `channels.<id>` і мають описуватися метаданими `channelConfigs` у маніфесті відповідного Plugin, а не центральним реєстром параметрів OpenClaw.
- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера веб-отримання Firecrawl.
- `apiKey`: API-ключ Firecrawl (підтримує SecretRef). Використовує запасний варіант із `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або env-змінної `FIRECRAWL_API_KEY`.
- `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`).
- `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`).
- `onlyMainContent`: витягувати лише основний вміст зі сторінок (типово: `true`).
- `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні).
- `timeoutSeconds`: тайм-аут запиту зчитування в секундах (типово: `60`).
- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok).
- `enabled`: увімкнути провайдера X Search.
- `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`).
- `timeoutSeconds`: тайм-аут запиту scrape у секундах (типово: `60`).
- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (веб-пошук Grok).
- `enabled`: увімкнути провайдер X Search.
- `model`: модель Grok, яку слід використовувати для пошуку (наприклад, `"grok-4-1-fast"`).
- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів.
- `enabled`: головний перемикач dreaming (типово `false`).
- `frequency`: Cron-інтервал для кожного повного циклу dreaming (типово `"0 3 * * *"`).
- політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації).
- Повна конфігурація пам’яті міститься в [Довіднику конфігурації пам’яті](/uk/reference/memory-config):
- Повна конфігурація пам’яті міститься в [Memory configuration reference](/uk/reference/memory-config):
- `agents.defaults.memorySearch.*`
- `memory.backend`
- `memory.citations`
- `memory.qmd.*`
- `plugins.entries.memory-core.config.dreaming`
- Увімкнені Plugin-пакети Claude також можуть додавати вбудовані значення Pi за замовчуванням із `settings.json`; OpenClaw застосовує їх як очищені налаштування агентів, а не як сирі патчі конфігурації OpenClaw.
- `plugins.slots.memory`: вибрати id активного Plugin пам’яті або `"none"` для вимкнення Plugin пам’яті.
- `plugins.slots.contextEngine`: вибрати id активного Plugin рушія контексту; типово `"legacy"`, якщо ви не встановите й не виберете інший рушій.
- `plugins.installs`: застарілий резервний механізм сумісності для застарілих
метаданих установлення, якими керує CLI. Нові встановлення Plugin записують
керований журнал стану `plugins/installs.json`.
- Застарілі записи містять `source`, `spec`, `sourcePath`, `installPath`,
`version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`,
`shasum`, `resolvedAt`, `installedAt`.
- Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI замість
ручного редагування.
- Увімкнені Plugin-пакунки Claude також можуть додавати вбудовані значення Pi за замовчуванням із `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як необроблені патчі конфігурації OpenClaw.
- `plugins.slots.memory`: вибрати ідентифікатор активного memory Plugin або `"none"`, щоб вимкнути memory Plugin.
- `plugins.slots.contextEngine`: вибрати ідентифікатор активного Plugin рушія контексту; типово `"legacy"`, якщо ви не встановите й не виберете інший рушій.
Див. [Plugins](/uk/tools/plugin).
@ -252,46 +246,46 @@ bundled каналів (автентифікація, контроль дост
```
- `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`.
- `tabCleanup` звільняє відстежувані вкладки основного агента після простою або коли
- `tabCleanup` вивільняє відстежувані вкладки основного агента після часу простою або коли
сесія перевищує свій ліміт. Установіть `idleMinutes: 0` або `maxTabsPerSession: 0`, щоб
вимкнути ці окремі режими очищення.
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація браузера за замовчуванням залишається суворо обмеженою.
- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тож навігація браузера типово залишається строгою.
- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації браузера в приватній мережі.
- У суворому режимі кінцеві точки віддалених профілів CDP (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок доступності/виявлення.
- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім.
- У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків.
- Віддалені профілі працюють лише в режимі підключення (запуск/зупинка/скидання вимкнено).
- У строгому режимі віддалені кінцеві точки профілів CDP (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок досяжності/виявлення.
- `ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий псевдонім.
- У строгому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків.
- Віддалені профілі підтримують лише під’єднання (start/stop/reset вимкнені).
- `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`.
Використовуйте HTTP(S), якщо хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S),
Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S),
коли ваш провайдер надає прямий URL DevTools WebSocket.
- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до віддалених і
`attachOnly` перевірок доступності CDP, а також до запитів відкриття вкладок. Керовані loopback-
профілі зберігають типові локальні значення CDP.
- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до віддаленої та
`attachOnly`-досяжності CDP, а також до запитів на відкриття вкладок. Керовані loopback-
профілі зберігають локальні значення CDP за замовчуванням.
- Якщо зовнішньо керований сервіс CDP доступний через loopback, установіть для цього
профілю `attachOnly: true`; інакше OpenClaw вважатиме loopback-порт
локальним керованим профілем браузера та може повідомляти про помилки володіння локальним портом.
- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися
до вибраного хоста або через підключений вузол браузера.
профілю `attachOnly: true`; інакше OpenClaw розглядатиме loopback-порт як
локальний керований профіль браузера й може повідомляти про помилки володіння локальним портом.
- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть під’єднуватися на
вибраному хості або через підключений вузол браузера.
- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлюватися на конкретний
профіль браузера на базі Chromium, наприклад Brave або Edge.
профіль браузера на основі Chromium, наприклад Brave або Edge.
- Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP:
дії на основі snapshot/ref замість націлювання через CSS-селектори, хуки завантаження
одного файла, без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без
`responsebody`, експорту PDF, перехоплення завантажень чи пакетних дій.
дії на основі snapshot/ref замість націлювання через CSS-селектори, hooks для завантаження одного файла,
відсутність перевизначень тайм-ауту діалогів, відсутність `wait --load networkidle`, а також
відсутність `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій.
- Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно
задавайте `cdpUrl` лише для віддаленого CDP.
- Локальні керовані профілі можуть задавати `executablePath`, щоб перевизначити глобальний
`browser.executablePath` для цього профілю. Використовуйте це, щоб запускати один профіль у
Chrome, а інший у Brave.
Chrome, а інший — у Brave.
- Локальні керовані профілі використовують `browser.localLaunchTimeoutMs` для HTTP-виявлення Chrome CDP
після запуску процесу та `browser.localCdpReadyTimeoutMs` для
готовності CDP websocket після запуску. Збільшуйте їх на повільніших хостах, де Chrome
успішно запускається, але перевірки готовності випереджають завершення запуску. Обидва значення мають бути
додатними цілими числами до `120000` ms; некоректні значення конфігурації відхиляються.
- Порядок автовиявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
готовності websocket CDP після запуску. Підвищуйте їх на повільніших хостах, де Chrome
запускається успішно, але перевірки готовності змагаються зі стартом. Обидва значення мають бути
додатними цілими числами до `120000` мс; некоректні значення конфігурації відхиляються.
- Порядок автовиявлення: типовий браузер, якщо він на основі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
- `browser.executablePath` і `browser.profiles.<name>.executablePath` обидва
приймають `~` і `~/...` для домашнього каталогу вашої ОС перед запуском Chromium.
`userDataDir` для профілів `existing-session` також розгортає тильду.
`userDataDir` для профілю `existing-session` також розгортається з тильдою.
- Сервіс керування: лише loopback (порт визначається на основі `gateway.port`, типово `18791`).
- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад,
`--disable-gpu`, розмір вікна або прапорці налагодження).
@ -312,8 +306,8 @@ bundled каналів (автентифікація, контроль дост
}
```
- `seamColor`: колір акценту для chrome UI нативного застосунку (відтінок бульбашки Talk Mode тощо).
- `assistant`: перевизначення ідентичності Control UI. Якщо не задано, використовується ідентичність активного агента.
- `seamColor`: колір акценту для chrome інтерфейсу нативного застосунку (тон бульбашки Talk Mode тощо).
- `assistant`: перевизначення ідентичності для Control UI. Якщо не задано, використовується ідентичність активного агента.
---
@ -388,67 +382,68 @@ bundled каналів (автентифікація, контроль дост
}
```
<Accordion title="Подробиці полів Gateway">
<Accordion title="Докладно про поля Gateway">
- `mode`: `local` (запуск gateway) або `remote` (підключення до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`.
- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`.
- `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`.
- `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`.
- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
- **Примітка щодо Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. З мережевим режимом Docker bridge (`-p 18789:18789`) трафік надходить через `eth0`, тому gateway недоступний. Використовуйте `--network host` або задайте `bind: "lan"` (чи `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах.
- **Auth**: за замовчуванням обов’язкова. Bind не на loopback вимагають auth gateway. На практиці це означає спільний токен/пароль або reverse proxy з контролем ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер початкового налаштування за замовчуванням генерує токен.
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Запуск і потоки встановлення/відновлення сервісу завершуються помилкою, якщо налаштовано обидва значення, а режим не задано.
- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань loopback; цей варіант навмисно не пропонується в запитах початкового налаштування.
- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з контролем ідентичності та довіряти заголовкам ідентичності від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy loopback на тій самій машині не задовольняють вимоги auth trusted-proxy.
- `gateway.auth.allowTailscale`: якщо `true`, заголовки ідентичності Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цю auth заголовків Tailscale; вони натомість дотримуються звичайного режиму HTTP auth gateway. Цей безтокенний потік виходить із припущення, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`.
- `gateway.auth.rateLimit`: необов’язковий лімітатор невдалих спроб auth. Застосовується для кожної IP-адреси клієнта та для кожної області auth (спільний секрет і токен пристрою відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`.
- В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні неправильні спроби від того самого клієнта можуть спровокувати спрацювання лімітатора вже на другому запиті, замість того щоб обидві одночасно пройти як звичайні невідповідності.
- `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; задайте `false`, якщо ви навмисно хочете обмежувати за rate limit також localhost-трафік (для тестових середовищ або суворих розгортань proxy).
- Спроби WS auth з походженням браузера завжди обмежуються без винятку для loopback (додатковий захист від brute force localhost через браузер).
- На loopback ці блокування для походження браузера ізольовані за нормалізованим значенням `Origin`,
тож повторні невдалі спроби з одного походження localhost не блокують автоматично
інше походження.
- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічно, потребує auth).
- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються браузерні клієнти не з loopback-origin.
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає резервне визначення origin через заголовок Host для розгортань, які навмисно покладаються на політику origin на основі заголовка Host.
- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хостів (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`).
- **Примітка щодо Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. За використання bridge-мережі Docker (`-p 18789:18789`) трафік надходить на `eth0`, тому gateway недосяжний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах.
- **Auth**: типово обов’язкова. Non-loopback bind вимагають auth gateway. На практиці це означає спільний token/password або reverse proxy з підтримкою ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер onboarding типово генерує token.
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (зокрема через SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Запуск і потоки встановлення/відновлення сервісу завершуються помилкою, коли налаштовано обидва значення, а режим не задано.
- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань local loopback; цей варіант навмисно не пропонується в підказках onboarding.
- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з підтримкою ідентичності та довіряти заголовкам ідентичності від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує джерело proxy **не з loopback**; reverse proxy loopback на тому ж хості не задовольняють вимоги trusted-proxy auth.
- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Кінцеві точки HTTP API **не** використовують цей auth заголовком Tailscale; натомість вони дотримуються звичайного HTTP-режиму auth gateway. Цей безтокеновий потік передбачає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`.
- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб auth. Застосовується для кожної IP-адреси клієнта і для кожної області auth (спільний секрет і токен пристрою відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`.
- В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом помилки. Тому одночасні хибні спроби від того самого клієнта можуть спрацювати на обмежувач уже на другому запиті, а не пройти обидві як звичайні невідповідності.
- `gateway.auth.rateLimit.exemptLoopback` типово дорівнює `true`; встановіть `false`, якщо свідомо хочете, щоб трафік localhost теж підлягав rate limiting (для тестових конфігурацій або строгих proxy-розгортань).
- Спроби WS-auth із джерел browser-origin завжди обмежуються без винятку для loopback (додатковий захист від brute force localhost через браузер).
- На loopback ці блокування browser-origin ізолюються за нормалізованим
значенням `Origin`, тож повторні невдачі з одного localhost-origin не
блокують автоматично інше origin.
- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічно, вимагає auth).
- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються браузерні клієнти з non-loopback origin.
- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає fallback origin через заголовок Host для розгортань, що свідомо покладаються на політику origin через заголовок Host.
- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`.
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійне перевизначення в середовищі процесу на стороні клієнта,
яке дозволяє plaintext `ws://` до довірених IP приватної мережі; за замовчуванням plaintext, як і раніше, дозволено лише для loopback. Еквівалента в `openclaw.json`
- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: аварійне перевизначення
середовища процесу на боці клієнта, яке дозволяє незашифрований `ws://` до довірених IP
приватної мережі; типово незашифрований трафік залишається дозволеним лише для loopback. Еквівалента в `openclaw.json`
немає, а конфігурація приватної мережі браузера, така як
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`, не впливає на клієнтів Gateway
WebSocket.
- `gateway.remote.token` / `.password`: поля облікових даних віддаленого клієнта. Самі по собі вони не налаштовують auth gateway.
- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього relay APNs, який використовують офіційні/TestFlight-збірки iOS після публікації ними relay-реєстрацій до gateway. Цей URL має збігатися з URL relay, вкомпільованим у збірку iOS.
- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типово `10000`.
- Реєстрації, що працюють через relay, делегуються конкретній ідентичності gateway. Спарений застосунок iOS викликає `gateway.identity.get`, включає цю ідентичність у relay-реєстрацію та пересилає gateway дозвіл на надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію.
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення через env для наведеної вище конфігурації relay.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний вихід лише для розробки для URL relay HTTP на loopback. URL relay у production мають залишатися на HTTPS.
- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Задайте `0`, щоб глобально вимкнути перезапуски монітора стану. Типово: `5`.
- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте його більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`.
- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків монітора стану на канал/обліковий запис у ковзній годині. Типово: `10`.
- `channels.<provider>.healthMonitor.enabled`: відмова на рівні каналу від перезапусків монітора стану зі збереженням глобального монітора увімкненим.
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: перевизначення на рівні облікового запису для багатокористувацьких каналів. Якщо задано, має пріоритет над перевизначенням на рівні каналу.
- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано.
- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і його не вдається розв’язати, розв’язання завершується за принципом fail-closed (без маскування резервним віддаленим варіантом).
- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або додають заголовки пересланого клієнта. Указуйте лише proxy, які ви контролюєте. Записи loopback і далі лишаються валідними для налаштувань proxy/локального виявлення на тій самій машині (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`.
- `allowRealIpFallback`: якщо `true`, gateway приймає `X-Real-IP`, якщо відсутній `X-Forwarded-For`. Типово `false` для поведінки fail-closed.
- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий список дозволених CIDR/IP для автоматичного схвалення першого спарювання пристрою вузла без запитаних scopes. Якщо не задано, вимкнено. Це не схвалює автоматично спарювання operator/browser/Control UI/WebChat і не схвалює автоматично оновлення ролі, scope, метаданих чи публічного ключа.
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування списків дозволених/заборонених для оголошених команд вузла після спарювання та оцінки allowlist.
- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список deny).
- `gateway.tools.allow`: прибрати назви інструментів із типового HTTP-списку deny.
- `gateway.remote.token` / `.password`: це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway.
- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього relay APNs, який використовують офіційні/TestFlight збірки iOS після публікації relay-backed реєстрацій у gateway. Цей URL має збігатися з URL relay, зібраним у збірку iOS.
- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay в мілісекундах. Типово `10000`.
- Реєстрації з підтримкою relay делегуються конкретній ідентичності gateway. Спарений застосунок iOS викликає `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і пересилає в gateway дозвіл на надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію.
- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env-перевизначення для наведеної вище конфігурації relay.
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний виняток лише для розробки для loopback HTTP URL relay. У production URL relay мають залишатися на HTTPS.
- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типово: `5`.
- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`.
- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис протягом ковзної години. Типово: `10`.
- `channels.<provider>.healthMonitor.enabled`: відмова від перезапусків health-monitor для окремого каналу зі збереженням глобального моніторингу.
- `channels.<provider>.accounts.<accountId>.healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів із кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням рівня каналу.
- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як запасний варіант лише тоді, коли `gateway.auth.*` не задано.
- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується із закритою відмовою (без маскування через запасний варіант remote).
- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або вставляють заголовки пересланого клієнта. Указуйте лише proxy, які ви контролюєте. Записи loopback також залишаються валідними для налаштувань виявлення proxy/локального трафіку на тому ж хості (наприклад, Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`.
- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо відсутній `X-Forwarded-For`. Типово `false` для поведінки fail-closed.
- `gateway.nodes.pairing.autoApproveCidrs`: необов’язковий список дозволених CIDR/IP для автоматичного схвалення першого спарювання пристрою вузла без запитаних областей доступу. Якщо не задано, вимкнено. Це не схвалює автоматично спарювання operator/browser/Control UI/WebChat і не схвалює автоматично оновлення ролі, області доступу, метаданих або публічного ключа.
- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд вузла після спарювання та оцінки списку дозволів.
- `gateway.tools.deny`: додаткові імена інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список deny).
- `gateway.tools.allow`: видаляє імена інструментів із типового HTTP-списку deny.
</Accordion>
### OpenAI-сумісні кінцеві точки
### Кінцеві точки, сумісні з OpenAI
- Chat Completions: вимкнено за замовчуванням. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`.
- Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`.
- Responses API: `gateway.http.endpoints.responses.enabled`.
- Посилене захист URL-входів Responses:
- Посилення безпеки URL-входів Responses:
- `gateway.http.endpoints.responses.maxUrlParts`
- `gateway.http.endpoints.responses.files.urlAllowlist`
- `gateway.http.endpoints.responses.images.urlAllowlist`
Порожні списки allowlist трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false`
та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL.
- Необов’язковий заголовок посиленого захисту відповідей:
- Необов’язковий заголовок посилення безпеки відповіді:
- `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS-origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts))
### Ізоляція кількох екземплярів
@ -463,7 +458,7 @@ openclaw gateway --port 19001
Зручні прапорці: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile <name>` (використовує `~/.openclaw-<name>`).
Див. [Кілька Gateway](/uk/gateway/multiple-gateways).
Див. [Multiple Gateways](/uk/gateway/multiple-gateways).
### `gateway.tls`
@ -483,9 +478,9 @@ openclaw gateway --port 19001
- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`).
- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, якщо явні файли не налаштовано; лише для локального/dev використання.
- `certPath`: шлях у файловій системі до файла сертифіката TLS.
- `keyPath`: шлях у файловій системі до файла приватного ключа TLS; обмежуйте доступ дозволами.
- `caPath`: необов’язковий шлях до пакета CA для верифікації клієнта або власних ланцюжків довіри.
- `certPath`: шлях файлової системи до файла TLS-сертифіката.
- `keyPath`: шлях файлової системи до файла приватного TLS-ключа; обмежуйте права доступу.
- `caPath`: необов’язковий шлях до пакета CA для перевірки клієнта або власних ланцюжків довіри.
### `gateway.reload`
@ -502,12 +497,12 @@ openclaw gateway --port 19001
```
- `mode`: керує тим, як зміни конфігурації застосовуються під час виконання.
- `"off"`: ігнорувати зміни в реальному часі; зміни потребують явного перезапуску.
- `"off"`: ігнорувати зміни наживо; зміни вимагають явного перезапуску.
- `"restart"`: завжди перезапускати процес gateway при зміні конфігурації.
- `"hot"`: застосовувати зміни в межах процесу без перезапуску.
- `"hot"`: застосовувати зміни в процесі без перезапуску.
- `"hybrid"` (типово): спочатку спробувати hot reload; за потреби перейти до перезапуску.
- `debounceMs`: вікно debounce у ms перед застосуванням змін конфігурації (невід’ємне ціле число).
- `deferralTimeoutMs`: необов’язковий максимальний час у ms очікування завершення поточних операцій перед примусовим перезапуском. Не задавайте його або встановіть `0`, щоб чекати необмежено довго та періодично журналювати попередження про те, що щось іще не завершено.
- `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число).
- `deferralTimeoutMs`: необов’язковий максимальний час у мс очікування завершення поточних операцій перед примусовим перезапуском. Не задавайте його або встановіть `0`, щоб чекати безстроково та періодично журналювати попередження про те, що ще лишається незавершеним.
---
@ -545,12 +540,12 @@ openclaw gateway --port 19001
```
Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
Токени hooks у рядку запиту відхиляються.
Токени hook у рядку запиту відхиляються.
Примітки щодо валідації та безпеки:
- `hooks.enabled=true` вимагає непорожнього `hooks.token`.
- `hooks.token` має бути **відмінним** від `gateway.auth.token`; повторне використання токена Gateway відхиляється.
- `hooks.enabled=true` вимагає непорожній `hooks.token`.
- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється.
- `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`.
- Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`).
- Якщо mapping або preset використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього opt-in.
@ -559,32 +554,32 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
- `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }`
- `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }`
- `sessionKey` із тіла запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`).
- `sessionKey` з тіла запиту приймається лише коли `hooks.allowRequestSessionKey=true` (типово: `false`).
- `POST /hooks/<name>` → розв’язується через `hooks.mappings`
- Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються зовнішньо наданими й також потребують `hooks.allowRequestSessionKey=true`.
- Значення `sessionKey` у mapping, згенеровані через шаблон, вважаються зовнішньо наданими й також вимагають `hooks.allowRequestSessionKey=true`.
<Accordion title="Подробиці mapping">
<Accordion title="Докладно про mapping">
- `match.path` відповідає підшляху після `/hooks` (наприклад, `/hooks/gmail` → `gmail`).
- `match.source` відповідає полю payload для загальних шляхів.
- Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload.
- `match.path` зіставляє підшлях після `/hooks` (наприклад, `/hooks/gmail` → `gmail`).
- `match.source` зіставляє поле payload для загальних шляхів.
- Шаблони на кшталт `{{messages[0].subject}}` читаються з payload.
- `transform` може вказувати на модуль JS/TS, що повертає дію hook.
- `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються).
- `transform.module` має бути відносним шляхом і лишатися в межах `hooks.transformsDir` (абсолютні шляхи й traversal відхиляються).
- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового.
- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі).
- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`.
- `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` і ключам сесії mapping, що керуються шаблонами, задавати `sessionKey` (типово: `false`).
- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Він стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`.
- `deliver: true` надсилає фінальну відповідь до каналу; `channel` типово дорівнює `last`.
- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо задано каталог моделей).
- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і ключам сесії mapping, керованим шаблонами, задавати `sessionKey` (типово: `false`).
- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`.
- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово `last`.
- `model` перевизначає LLM для цього запуску hook (має бути дозволена, якщо задано каталог моделей).
</Accordion>
### Інтеграція Gmail
### Інтеграція з Gmail
- Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`.
- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, задайте `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`.
- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого.
- Якщо ви зберігаєте таку маршрутизацію на рівні повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`.
- Якщо вам потрібен `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість шаблонного значення за замовчуванням.
```json5
{
@ -607,7 +602,7 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
}
```
- Gateway автоматично запускає `gog gmail watch serve` під час завантаження, якщо його налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути це.
- Gateway автоматично запускає `gog gmail watch serve` під час старту, коли це налаштовано. Установіть `OPENCLAW_SKIP_GMAIL_WATCHER=1`, щоб вимкнути.
- Не запускайте окремий `gog gmail watch serve` паралельно з Gateway.
---
@ -624,18 +619,18 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
}
```
- Обслуговує HTML/CSS/JS і A2UI, які може редагувати агент, через HTTP на порту Gateway:
- Обслуговує HTML/CSS/JS, які може редагувати агент, і A2UI через HTTP на порту Gateway:
- `http://<gateway-host>:<gateway.port>/__openclaw__/canvas/`
- `http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/`
- Лише локально: залишайте `gateway.bind: "loopback"` (типово).
- Для bind не на loopback: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway.
- Node WebView зазвичай не надсилають заголовки auth; після спарювання й підключення node Gateway рекламує URL можливостей з областю node для доступу до canvas/A2UI.
- URL можливостей прив’язані до активної WS-сесії node і швидко спливають. Резервний варіант на основі IP не використовується.
- Для non-loopback bind: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway.
- Node WebView зазвичай не надсилають заголовки auth; після спарювання й підключення вузла Gateway рекламує URL можливостей з областю дії вузла для доступу до canvas/A2UI.
- URL можливостей прив’язані до активної WS-сесії вузла й швидко спливають. Резервний варіант на основі IP не використовується.
- Впроваджує клієнт live-reload у HTML, що обслуговується.
- Автоматично створює стартовий `index.html`, якщо каталог порожній.
- Автоматично створює стартовий `index.html`, коли каталог порожній.
- Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`.
- Зміни потребують перезапуску gateway.
- Вимикайте live reload для великих каталогів або при помилках `EMFILE`.
- Зміни вимагають перезапуску gateway.
- Вимкніть live reload для великих каталогів або при помилках `EMFILE`.
---
@ -667,7 +662,7 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
}
```
Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale.
Записує унікасну зону DNS-SD в `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS Tailscale.
Налаштування: `openclaw dns setup --apply`.
@ -675,7 +670,7 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
## Середовище
### `env` (вбудовані змінні середовища)
### `env` (вбудовані env-змінні)
```json5
{
@ -692,14 +687,14 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
}
```
- Вбудовані змінні середовища застосовуються лише тоді, коли в середовищі процесу бракує цього ключа.
- Вбудовані env-змінні застосовуються лише якщо в середовищі процесу бракує цього ключа.
- Файли `.env`: `.env` у CWD + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні).
- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell.
- Повний порядок пріоритету див. у [Environment](/uk/help/environment).
### Підстановка env var
### Підстановка env-змінних
Посилайтеся на змінні середовища в будь-якому рядку конфігурації через `${VAR_NAME}`:
Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`:
```json5
{
@ -709,16 +704,16 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
}
```
- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`.
- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`.
- Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації.
- Екрануйте через `$${VAR}` для буквального `${VAR}`.
- Використовуйте `$${VAR}` для буквального `${VAR}`.
- Працює з `$include`.
---
## Секрети
Посилання на секрети є адитивними: прості текстові значення теж продовжують працювати.
Посилання на секрети є адитивними: прості текстові значення також продовжують працювати.
### `SecretRef`
@ -734,13 +729,13 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
- шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$`
- `id` для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`)
- шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `id` для `source: "exec"` не повинні містити сегменти шляху `.` або `..`, розділені слешами (наприклад, `a/../b` відхиляється)
- `id` для `source: "exec"` не повинні містити сегменти шляху `.` або `..`, розділені `/` (наприклад `a/../b` відхиляється)
### Підтримувана поверхня облікових даних
- Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface)
- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface)
- `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`.
- Посилання в `auth-profiles.json` включаються до розв’язання під час виконання та охоплення аудиту.
- Посилання в `auth-profiles.json` включені до розв’язання під час виконання та покриття аудиту.
### Конфігурація провайдерів секретів
@ -772,14 +767,14 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
Примітки:
- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue значення `id` має бути `"value"`).
- Шляхи до провайдерів file і exec завершуються за принципом fail-closed, коли недоступна перевірка Windows ACL. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити.
- Провайдер `exec` вимагає абсолютний шлях `command` і використовує корисні навантаження протоколу через stdin/stdout.
- Типово шляхи команд-симлінків відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-симлінки з валідацією розв’язаного цільового шляху.
- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до розв’язаного цільового шляху.
- Дочірнє середовище `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`.
- Посилання на секрети розв’язуються під час активації у знімок у пам’яті, після чого шляхи запитів читають лише цей знімок.
- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на ввімкнених поверхнях спричиняють збій запуску/перезавантаження, а неактивні поверхні пропускаються з діагностикою.
- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`).
- Шляхи провайдерів file і exec завершуються із закритою відмовою, коли перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити.
- Провайдер `exec` вимагає абсолютний шлях `command` і використовує протокольні payload через stdin/stdout.
- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання з перевіркою розв’язаного цільового шляху.
- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до розв’язаного цільового шляху.
- Дочірнє середовище `exec` типово мінімальне; явно передавайте потрібні змінні через `passEnv`.
- Посилання на секрети розв’язуються під час активації у snapshot в пам’яті, після чого шляхи запитів читають лише цей snapshot.
- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на ввімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою.
---
@ -801,13 +796,13 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
}
```
- Профілі для кожного агента зберігаються в `<agentDir>/auth-profiles.json`.
- Профілі для окремих агентів зберігаються в `<agentDir>/auth-profiles.json`.
- `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних.
- Профілі в режимі OAuth (`auth.profiles.<id>.mode = "oauth"`) не підтримують облікові дані профілю auth на основі SecretRef.
- Статичні облікові дані середовища виконання надходять зі знімків, розв’язаних у пам’яті; застарілі статичні записи `auth.json` очищуються під час виявлення.
- Застарілий імпорт OAuth здійснюється з `~/.openclaw/credentials/oauth.json`.
- Профілі режиму OAuth (`auth.profiles.<id>.mode = "oauth"`) не підтримують облікові дані профілю auth на основі SecretRef.
- Статичні облікові дані під час виконання надходять із розв’язаних snapshot у пам’яті; застарілі статичні записи `auth.json` очищуються, коли їх виявлено.
- Застарілий імпорт OAuth — з `~/.openclaw/credentials/oauth.json`.
- Див. [OAuth](/uk/concepts/oauth).
- Поведінка секретів під час виконання та інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets).
- Поведінка секретів під час виконання та інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets).
### `auth.cooldowns`
@ -829,19 +824,19 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
}
```
- `billingBackoffHours`: базова затримка в годинах, коли профіль завершується помилкою через справжні помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг
усе ще може потрапити сюди навіть у відповідях `401`/`403`, але провайдер-специфічні
зіставлення тексту залишаються обмеженими провайдером, якому вони належать (наприклад, OpenRouter
`Key limit exceeded`). Повторювані HTTP `402` повідомлення про вікно використання або
ліміти витрат організації/робочої області лишаються натомість у шляху `rate_limit`.
- `billingBackoffHoursByProvider`: необов’язкові перевизначення затримки білінгу в годинах для кожного провайдера.
- `billingMaxHours`: обмеження в годинах для експоненційного зростання затримки білінгу (типово: `24`).
- `authPermanentBackoffMinutes`: базова затримка в хвилинах для збоїв `auth_permanent` із високою впевненістю (типово: `10`).
- `authPermanentMaxMinutes`: обмеження в хвилинах для зростання затримки `auth_permanent` (типово: `60`).
- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників затримки (типово: `24`).
- `overloadedProfileRotations`: максимальна кількість ротацій auth-профілю того самого провайдера для помилок перевантаження перед перемиканням на резервну модель (типово: `1`). Форми перевантаження провайдера на кшталт `ModelNotReadyException` потрапляють сюди.
- `billingBackoffHours`: базова затримка в годинах, коли профіль зазнає помилки через справжні помилки виставлення рахунків/недостатнього кредиту (типово: `5`). Явний текст про billing
усе ще може потрапити сюди навіть за відповідей `401`/`403`, але текстові
зіставлення, специфічні для провайдера, залишаються в межах провайдера, якому вони належать (наприклад OpenRouter
`Key limit exceeded`). Повторювані HTTP `402` повідомлення про usage-window або
ліміти витрат organization/workspace натомість залишаються в шляху `rate_limit`.
- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин затримки billing для окремих провайдерів.
- `billingMaxHours`: верхня межа в годинах для експоненційного зростання затримки billing (типово: `24`).
- `authPermanentBackoffMinutes`: базова затримка в хвилинах для помилок `auth_permanent` із високою впевненістю (типово: `10`).
- `authPermanentMaxMinutes`: верхня межа в хвилинах для зростання затримки `auth_permanent` (типово: `60`).
- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників затримок (типово: `24`).
- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок перевантаження перед переходом до запасної моделі (типово: `1`). Сюди потрапляють форми на кшталт `ModelNotReadyException`, коли провайдер зайнятий.
- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`).
- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-профілю того самого провайдера для помилок rate limit перед перемиканням на резервну модель (типово: `1`). До цього кошика rate limit належить текст, характерний для провайдерів, наприклад `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`.
- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок rate limit перед переходом до запасної моделі (типово: `1`). Цей кошик rate limit включає текстові форми провайдера, такі як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`.
---
@ -863,7 +858,7 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
- Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`.
- Установіть `logging.file` для стабільного шляху.
- `consoleLevel` підвищується до `debug` з `--verbose`.
- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого записи пригнічуються (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів.
- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис припиняється (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів.
---
@ -909,22 +904,22 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
```
- `enabled`: головний перемикач для виводу інструментування (типово: `true`).
- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналу (підтримуються wildcard, як-от `"telegram.*"` або `"*"`).
- `stuckSessionWarnMs`: поріг віку в ms для виводу попереджень про завислі сесії, поки сесія залишається в стані обробки.
- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). Повну конфігурацію, каталог сигналів і модель конфіденційності див. у [Експорт OpenTelemetry](/uk/gateway/opentelemetry).
- `flags`: масив рядків прапорців, що вмикають цільовий вивід журналу (підтримує шаблони з wildcard, як-от `"telegram.*"` або `"*"`).
- `stuckSessionWarnMs`: поріг віку в мс для виводу попереджень про завислі сесії, поки сесія лишається в стані обробки.
- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). Повну конфігурацію, каталог сигналів і модель конфіденційності див. у [OpenTelemetry export](/uk/gateway/opentelemetry).
- `otel.endpoint`: URL колектора для експорту OTel.
- `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`.
- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel.
- `otel.serviceName`: назва сервісу для атрибутів ресурсу.
- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs.
- `otel.sampleRate`: частота семплювання trace `0`–`1`.
- `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в ms.
- `otel.captureContent`: opt-in для захоплення сирого вмісту в атрибути span OTEL. Типово вимкнено. Булеве значення `true` захоплює вміст повідомлень/інструментів, крім системного; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`.
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: перемикач середовища для найновіших експериментальних атрибутів провайдера span GenAI. За замовчуванням span зберігають застарілий атрибут `gen_ai.system` для сумісності; метрики GenAI використовують обмежені семантичні атрибути.
- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, які вже зареєстрували глобальний SDK OpenTelemetry. У такому разі OpenClaw пропускає запуск/завершення SDK, яким володіє Plugin, зберігаючи активними слухачі діагностики.
- `cacheTrace.enabled`: журналювати знімки trace кешу для вбудованих запусків (типово: `false`).
- `cacheTrace.filePath`: шлях виводу для JSONL trace кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається до виводу trace кешу (усе типово: `true`).
- `otel.traces` / `otel.metrics` / `otel.logs`: вмикають експорт trace, metrics або logs.
- `otel.sampleRate`: частота вибірки trace `0`–`1`.
- `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс.
- `otel.captureContent`: opt-in захоплення необробленого вмісту для атрибутів spans OTEL. Типово вимкнено. Булеве `true` захоплює вміст повідомлень/інструментів, крім системного; форма об’єкта дозволяє явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`.
- `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental`: перемикач середовища для найновіших експериментальних атрибутів провайдера spans GenAI. Типово spans зберігають застарілий атрибут `gen_ai.system` для сумісності; метрики GenAI використовують обмежені семантичні атрибути.
- `OPENCLAW_OTEL_PRELOADED=1`: перемикач середовища для хостів, які вже зареєстрували глобальний OpenTelemetry SDK. Тоді OpenClaw пропускає запуск/завершення SDK, яким володіє Plugin, зберігаючи активними діагностичні слухачі.
- `cacheTrace.enabled`: журналювати snapshot трасування кешу для вбудованих запусків (типово: `false`).
- `cacheTrace.filePath`: шлях виводу для JSONL трасування кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`).
- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід трасування кешу (усі типово: `true`).
---
@ -946,12 +941,12 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
}
```
- `channel`: канал релізів для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`.
- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`).
- `auto.enabled`: увімкнути фонове автооновлення для пакетних установлень (типово: `false`).
- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням для каналу stable (типово: `6`; максимум: `168`).
- `channel`: канал релізу для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`.
- `checkOnStart`: перевіряти оновлення npm під час старту gateway (типово: `true`).
- `auto.enabled`: увімкнути фонове автооновлення для встановлень пакетів (типово: `false`).
- `auto.stableDelayHours`: мінімальна затримка в годинах перед авто-застосуванням stable-каналу (типово: `6`; максимум: `168`).
- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; максимум: `168`).
- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (типово: `1`; максимум: `24`).
- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу в годинах (типово: `1`; максимум: `24`).
---
@ -984,23 +979,23 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
}
```
- `enabled`: глобальний feature gate для ACP (типово: `true`; установіть `false`, щоб приховати можливості dispatch і spawn ACP).
- `dispatch.enabled`: окремий gate для dispatch ходу ACP-сесії (типово: `true`). Установіть `false`, щоб залишити ACP-команди доступними, але заблокувати виконання.
- `backend`: типовий id backend середовища виконання ACP (має відповідати зареєстрованому Plugin середовища виконання ACP).
Якщо задано `plugins.allow`, включіть id backend Plugin (наприклад `acpx`), інакше bundled типовий Plugin не завантажиться.
- `defaultAgent`: резервний id цільового агента ACP, коли spawn не задає явну ціль.
- `allowedAgents`: список дозволених id агентів для сесій середовища виконання ACP; порожній список означає відсутність додаткових обмежень.
- `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сесій.
- `stream.coalesceIdleMs`: вікно idle flush у ms для потокового тексту.
- `stream.maxChunkChars`: максимальний розмір chunk перед розбиттям проєкції потокового блока.
- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів у межах ходу (типово: `true`).
- `stream.deliveryMode`: `"live"` транслює поступово; `"final_only"` буферизує до термінальних подій ходу.
- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`).
- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктується на один хід ACP.
- `enabled`: глобальний прапорець функції ACP (типово: `true`; установіть `false`, щоб приховати можливості dispatch і spawn ACP).
- `dispatch.enabled`: незалежний прапорець для dispatch ходів сесії ACP (типово: `true`). Установіть `false`, щоб зберегти доступність команд ACP, одночасно блокуючи виконання.
- `backend`: ідентифікатор типового backend середовища виконання ACP (має збігатися із зареєстрованим Plugin середовища виконання ACP).
Якщо задано `plugins.allow`, включіть ідентифікатор backend Plugin (наприклад `acpx`), інакше bundled Plugin за замовчуванням не завантажиться.
- `defaultAgent`: резервний ідентифікатор цільового агента ACP, коли spawn не задає явної цілі.
- `allowedAgents`: список дозволених ідентифікаторів агентів для сесій середовища виконання ACP; порожнє значення означає відсутність додаткових обмежень.
- `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP.
- `stream.coalesceIdleMs`: вікно скидання простою в мс для потокового тексту.
- `stream.maxChunkChars`: максимальний розмір фрагмента перед поділом проєкції потокового блока.
- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструмента за хід (типово: `true`).
- `stream.deliveryMode`: `"live"` передає потоково інкрементально; `"final_only"` буферизує до термінальних подій ходу.
- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструмента (типово: `"paragraph"`).
- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, що проєктується за хід ACP.
- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлень ACP.
- `stream.tagVisibility`: запис імен тегів у перевизначення видимості streamed подій типу boolean.
- `runtime.ttlMinutes`: idle TTL у хвилинах для worker ACP-сесій до моменту, коли вони підлягають очищенню.
- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час початкового налаштування середовища виконання ACP.
- `stream.tagVisibility`: запис імен тегів у булеві перевизначення видимості для потокових подій.
- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів сесії ACP до моменту, коли їх можна очистити.
- `runtime.installCommand`: необов’язкова команда встановлення, яку слід виконати під час bootstrap середовища виконання ACP.
---
@ -1016,17 +1011,17 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
}
```
- `cli.banner.taglineMode` керує стилем слогана банера:
- `"random"` (типово): змінні кумедні/сезонні слогани.
- `"default"`: фіксований нейтральний слоган (`Усі ваші чати, один OpenClaw.`).
- `"off"`: без тексту слогана (назва/версія банера все одно показуються).
- Щоб приховати весь банер (а не лише слогани), задайте env `OPENCLAW_HIDE_BANNER=1`.
- `cli.banner.taglineMode` керує стилем підзаголовка банера:
- `"random"` (типово): ротаційні кумедні/сезонні підзаголовки.
- `"default"`: фіксований нейтральний підзаголовок (`All your chats, one OpenClaw.`).
- `"off"`: без тексту підзаголовка (назва/версія банера все одно показуються).
- Щоб приховати весь банер (а не лише підзаголовки), установіть env `OPENCLAW_HIDE_BANNER=1`.
---
## Wizard
Метадані, які записують потоки покрокового налаштування CLI (`onboard`, `configure`, `doctor`):
Метадані, які записуються керованими CLI-потоками налаштування (`onboard`, `configure`, `doctor`):
```json5
{
@ -1044,13 +1039,13 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
## Ідентичність
Див. поля ідентичності `agents.list` у [Значеннях агентів за замовчуванням](/uk/gateway/config-agents#agent-defaults).
Див. поля ідентичності `agents.list` у розділі [Agent defaults](/uk/gateway/config-agents#agent-defaults).
---
## Bridge (застарілий, вилучено)
## Bridge (застаріле, видалено)
Поточні збірки більше не містять TCP bridge. Node підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі).
Поточні збірки більше не містять TCP bridge. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі).
<Accordion title="Застаріла конфігурація bridge (історична довідка)">
@ -1090,11 +1085,11 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
}
```
- `sessionRetention`: як довго зберігати завершені сесії ізольованих запусків cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. Типово: `24h`; задайте `false`, щоб вимкнути.
- `runLog.maxBytes`: максимальний розмір файла журналу на запуск (`cron/runs/<jobId>.jsonl`) перед очищенням. Типово: `2_000_000` bytes.
- `runLog.keepLines`: кількість найновіших рядків, що зберігаються, коли спрацьовує очищення журналу запуску. Типово: `2000`.
- `webhookToken`: bearer token, що використовується для POST-доставки cron Webhook (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається.
- `webhook`: застарілий резервний URL Webhook (http/https), який використовується лише для збережених завдань, що все ще мають `notify: true`.
- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. Типово: `24h`; установіть `false`, щоб вимкнути.
- `runLog.maxBytes`: максимальний розмір файла журналу на запуск (`cron/runs/<jobId>.jsonl`) перед очищенням. Типово: `2_000_000` байтів.
- `runLog.keepLines`: кількість найновіших рядків, що зберігаються при спрацюванні очищення журналу запуску. Типово: `2000`.
- `webhookToken`: bearer token, який використовується для доставки POST у cron Webhook (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається.
- `webhook`: застарілий резервний URL Webhook (http/https), який використовується лише для збережених завдань, що досі мають `notify: true`.
### `cron.retry`
@ -1111,10 +1106,10 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
```
- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`).
- `backoffMs`: масив затримок backoff у ms для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів).
- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати всі тимчасові типи.
- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів).
- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати для всіх тимчасових типів.
Застосовується лише до одноразових cron-завдань. Повторювані завдання використовують окрему обробку помилок.
Застосовується лише до одноразових завдань cron. Періодичні завдання використовують окрему обробку збоїв.
### `cron.failureAlert`
@ -1132,11 +1127,11 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
}
```
- `enabled`: увімкнути сповіщення про помилки для cron-завдань (типово: `false`).
- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`).
- `enabled`: увімкнути сповіщення про збої для завдань cron (типово: `false`).
- `after`: кількість послідовних збоїв перед надсиланням сповіщення (додатне ціле число, мін.: `1`).
- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число).
- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST на налаштований Webhook.
- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщення.
- `accountId`: необов’язковий ідентифікатор облікового запису або каналу для обмеження доставки сповіщення.
### `cron.failureDestination`
@ -1153,16 +1148,16 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
}
```
- Типове призначення для сповіщень про помилки cron для всіх завдань.
- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли достатньо даних цілі.
- Типове призначення для сповіщень про збої cron для всіх завдань.
- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних цілі.
- `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки.
- `to`: явна ціль announce або URL Webhook. Обов’язково для режиму webhook.
- `accountId`: необов’язкове перевизначення облікового запису для доставки.
- `delivery.failureDestination` для окремого завдання перевизначає це глобальне значення за замовчуванням.
- Коли не задано ні глобального, ні для окремого завдання призначення помилки, завдання, які вже доставляють через `announce`, у разі помилки повертаються до цієї основної цілі announce.
- `delivery.failureDestination` на рівні завдання перевизначає це глобальне значення за замовчуванням.
- Коли не задано ні глобального, ні призначення збою на рівні завдання, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної цілі announce.
- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`.
Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [фонові завдання](/uk/automation/tasks).
Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [background tasks](/uk/automation/tasks).
---
@ -1170,21 +1165,21 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`:
| Змінна | Опис |
| Variable | Description |
| ------------------ | ------------------------------------------------- |
| `{{Body}}` | Повне тіло вхідного повідомлення |
| `{{RawBody}}` | Сире тіло (без обгорток історії/відправника) |
| `{{BodyStripped}}` | Тіло з вилученими згадками групи |
| `{{Body}}` | Повний вхідний текст повідомлення |
| `{{RawBody}}` | Необроблений текст (без обгорток історії/відправника) |
| `{{BodyStripped}}` | Текст без згадок у групі |
| `{{From}}` | Ідентифікатор відправника |
| `{{To}}` | Ідентифікатор призначення |
| `{{MessageSid}}` | ID повідомлення каналу |
| `{{MessageSid}}` | Ідентифікатор повідомлення каналу |
| `{{SessionId}}` | UUID поточної сесії |
| `{{IsNewSession}}` | `"true"`, коли створено нову сесію |
| `{{MediaUrl}}` | Псевдо-URL вхідного медіа |
| `{{MediaPath}}` | Локальний шлях до медіа |
| `{{MediaType}}` | Тип медіа (image/audio/document/…) |
| `{{Transcript}}` | Транскрипт аудіо |
| `{{Prompt}}` | Розв’язаний prompt медіа для записів CLI |
| `{{Prompt}}` | Розв’язаний media prompt для записів CLI |
| `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI |
| `{{ChatType}}` | `"direct"` або `"group"` |
| `{{GroupSubject}}` | Тема групи (best effort) |
@ -1212,14 +1207,14 @@ Auth: `Authorization: Bearer <token>` або `x-openclaw-token: <token>`.
**Поведінка злиття:**
- Один файл: замінює об’єкт-контейнер.
- Масив файлів: глибоко зливається в заданому порядку (пізніші перевизначають раніші).
- Один файл: замінює об’єкт, що його містить.
- Масив файлів: глибоко зливається за порядком (пізніші перевизначають попередні).
- Сусідні ключі: зливаються після включень (перевизначають включені значення).
- Вкладені включення: до 10 рівнів углиб.
- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах конфігураційного каталогу верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно розв’язуються в межах цієї межі.
- Записи, якими володіє OpenClaw і які змінюють лише один розділ верхнього рівня, підкріплений включенням одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін.
- Кореневі включення, масиви включень і включення із сусідніми перевизначеннями доступні для OpenClaw-власних записів лише в режимі читання; такі записи завершуються за принципом fail-closed замість сплощення конфігурації.
- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок парсингу та циклічних включень.
- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно розв’язуються в межах цього кордону.
- Записи, якими володіє OpenClaw, що змінюють лише один розділ верхнього рівня, підкріплений включенням одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін.
- Кореневі включення, масиви включень і включення із сусідніми перевизначеннями є лише для читання для записів, якими володіє OpenClaw; такі записи завершуються із закритою відмовою замість сплющення конфігурації.
- Помилки: чіткі повідомлення для відсутніх файлів, помилок розбору та циклічних включень.
---
@ -1228,4 +1223,4 @@ _Пов’язане: [Configuration](/uk/gateway/configuration) · [Configurati
## Пов’язане
- [Configuration](/uk/gateway/configuration)
- [Приклади конфігурації](/uk/gateway/configuration-examples)
- [Configuration examples](/uk/gateway/configuration-examples)

522
docs/uk/gateway/doctor.md
View File

@ -1,20 +1,19 @@
---
read_when:
- Додавання або змінення міграцій doctor
- Додавання або зміна міграцій doctor
- Запровадження несумісних змін конфігурації
summary: 'Команда doctor: перевірки стану, міграції конфігурації та кроки відновлення'
summary: 'Команда Doctor: перевірки стану, міграції конфігурації та кроки відновлення'
title: Doctor
x-i18n:
generated_at: "2026-04-25T17:39:18Z"
generated_at: "2026-04-26T00:18:17Z"
model: gpt-5.4
provider: openai
source_hash: 13204a57facd19459fc812a8daa0fe629b6725bdabb014f59f871fa64c22e71d
source_hash: 9d442bf049afa6a9c00e9096bf4aa96964a313a1295ede1fb8e08d18fa7a606b
source_path: gateway/doctor.md
workflow: 15
---
`openclaw doctor` — це інструмент відновлення + міграції для OpenClaw. Він виправляє застарілу
конфігурацію/стан, перевіряє стан системи та надає практичні кроки для відновлення.
`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє стан системи та надає практичні кроки відновлення.
## Швидкий старт
@ -28,7 +27,7 @@ openclaw doctor
openclaw doctor --yes
```
Приймає значення за замовчуванням без запитів (зокрема кроки відновлення перезапуску/сервісу/пісочниці, де це застосовно).
Приймає типові значення без запитів (зокрема кроки відновлення перезапуску/служби/пісочниці, коли це застосовно).
```bash
openclaw doctor --repair
@ -46,14 +45,14 @@ openclaw doctor --repair --force
openclaw doctor --non-interactive
```
Запускається без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/сервісами/пісочницею, які потребують підтвердження людиною.
Міграції застарілого стану запускаються автоматично, якщо їх виявлено.
Запускається без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/службами/пісочницею, які потребують підтвердження людини.
Міграції застарілого стану запускаються автоматично, коли їх виявлено.
```bash
openclaw doctor --deep
```
Сканує системні сервіси на наявність додаткових інсталяцій Gateway (launchd/systemd/schtasks).
Сканує системні служби на наявність додаткових встановлень gateway (launchd/systemd/schtasks).
Якщо ви хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації:
@ -63,108 +62,91 @@ cat ~/.openclaw/openclaw.json
## Що він робить (коротко)
- Необов’язкове попереднє оновлення для git-інсталяцій (лише в інтерактивному режимі).
- Перевірка актуальності UI-протоколу (перебудовує Control UI, якщо схема протоколу новіша).
- Перевірка стану + запит на перезапуск.
- Підсумок стану Skills (доступні/відсутні/заблоковані) і стану Plugin.
- Необов’язкове попереднє оновлення для git-встановлень (лише в інтерактивному режимі).
- Перевірка актуальності протоколу UI (перебудовує Control UI, якщо схема протоколу новіша).
- Перевірка стану системи + запит на перезапуск.
- Зведення стану Skills (доступні/відсутні/заблоковані) і стану Plugin.
- Нормалізація конфігурації для застарілих значень.
- Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.<provider>`.
- Перевірки міграції браузера для застарілих конфігурацій розширення Chrome та готовності Chrome MCP.
- Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP.
- Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Попередження про перекриття Codex OAuth (`models.providers.openai-codex`).
- Перевірка передумов OAuth TLS для профілів OpenAI Codex OAuth.
- Міграція застарілого стану на диску (сесії/каталог агента/автентифікація WhatsApp).
- Міграція застарілих ключів контракту маніфесту Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Міграція застарілого сховища Cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, `provider` у payload, прості резервні завдання Webhook з `notify: true`).
- Попередження про затінення Codex OAuth (`models.providers.openai-codex`).
- Перевірка вимог TLS для OAuth-профілів OpenAI Codex OAuth.
- Міграція застарілого стану на диску (sessions/каталог agent/автентифікація WhatsApp).
- Міграція ключів контрактів маніфесту застарілих Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Міграція сховища застарілих Cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, payload `provider`, прості резервні Webhook-завдання `notify: true`).
- Перевірка файлів блокування сесій і очищення застарілих блокувань.
- Перевірки цілісності та прав доступу до стану (сесії, транскрипти, каталог стану).
- Відновлення транскриптів сесій для дубльованих гілок переписування запитів, створених у вразливих збірках 2026.4.24.
- Перевірки цілісності стану й прав доступу (sessions, transcripts, каталог state).
- Перевірки прав доступу до файлу конфігурації (`chmod 600`) під час локального запуску.
- Стан авторизації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled профілів авторизації.
- Виявлення додаткового каталогу workspace (`~/openclaw`).
- Відновлення образу пісочниці, якщо ізоляція увімкнена.
- Міграція застарілих сервісів і виявлення додаткових Gateway.
- Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк яких спливає, і повідомляє про стани cooldown/disabled профілів автентифікації.
- Виявлення додаткового каталогу робочого простору (`~/openclaw`).
- Відновлення образу пісочниці, коли увімкнено sandboxing.
- Міграція застарілої служби та виявлення додаткових gateway.
- Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`).
- Перевірки середовища виконання Gateway (сервіс встановлено, але не запущено; кешований ярлик launchd).
- Попередження про стан каналів (зондуються із запущеного Gateway).
- Перевірки середовища виконання gateway (службу встановлено, але вона не запущена; кешована мітка launchd).
- Попередження про стан каналів (зчитуються з запущеного gateway).
- Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням.
- Перевірки рекомендованих практик для середовища виконання Gateway (Node vs Bun, шляхи менеджера версій).
- Діагностика конфліктів порту Gateway (типово `18789`).
- Перевірки найкращих практик середовища виконання gateway (Node проти Bun, шляхи менеджера версій).
- Діагностика конфліктів портів gateway (типово `18789`).
- Попередження безпеки для відкритих політик DM.
- Перевірки автентифікації Gateway для режиму локального токена (пропонує згенерувати токен, якщо джерело токена відсутнє; не перезаписує конфігурації token SecretRef).
- Виявлення проблем зі сполученням пристроїв (очікування перших запитів на сполучення, очікування підвищення ролі/обсягу доступу, застарілий дрейф локального кешу токенів пристроїв і дрейф автентифікації у paired-record).
- Перевірки автентифікації gateway для локального режиму токенів (пропонує згенерувати токен, коли джерело токена відсутнє; не перезаписує конфігурації token SecretRef).
- Виявлення проблем зі спарюванням пристроїв (очікувані перші запити на спарювання, очікувані підвищення ролі/області дії, застарілий дрейф кешу локального токена пристрою та дрейф автентифікації парного запису).
- Перевірка `systemd linger` у Linux.
- Перевірка розміру файлів ініціалізації workspace (попередження про обрізання/наближення до межі для контекстних файлів).
- Перевірка стану завершення команд оболонки та автоматичне встановлення/оновлення.
- Перевірка готовності провайдера вбудовувань для пошуку в пам’яті (локальна модель, віддалений API-ключ або бінарний файл QMD).
- Перевірки інсталяції з джерел (невідповідність `pnpm` workspace, відсутні UI-ресурси, відсутній бінарний файл `tsx`).
- Перевірка розміру bootstrap-файлів робочого простору (попередження про обрізання/наближення до ліміту для файлів контексту).
- Перевірка стану доповнення команд оболонки та автоматичне встановлення/оновлення.
- Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, віддалений API-ключ або бінарний файл QMD).
- Перевірки встановлення з джерела (невідповідність робочого простору `pnpm`, відсутні UI-ресурси, відсутній бінарний файл `tsx`).
- Записує оновлену конфігурацію + метадані майстра.
## Дозаповнення та скидання Dreams UI
## Dreams UI: зворотне заповнення та скидання
Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded**
для робочого процесу grounded dreaming. Ці дії використовують RPC-методи в стилі
doctor для Gateway, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`.
Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для workflow grounded dreaming. Ці дії використовують RPC-методи в стилі doctor gateway, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`.
Що вони роблять:
- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному
workspace, запускає grounded REM diary pass і записує зворотні записи дозаповнення
у `DREAMS.md`.
- **Reset** видаляє з `DREAMS.md` лише ті записи щоденника дозаповнення, які позначені.
- **Clear Grounded** видаляє лише staged короткочасні записи тільки для grounded,
які походять з історичного відтворення та ще не накопичили live recall або daily
support.
- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає grounded REM diary pass і записує оборотні записи зворотного заповнення в `DREAMS.md`.
- **Reset** видаляє з `DREAMS.md` лише ті записи щоденника зворотного заповнення, які позначені як такі.
- **Clear Grounded** видаляє лише staged grounded-only short-term записи, які походять з історичного відтворення та ще не накопичили live recall або daily support.
Чого вони самі по собі **не** роблять:
Що вони **не** роблять самі по собі:
- вони не редагують `MEMORY.md`
- вони не запускають повні міграції doctor
- вони не переносять автоматично grounded кандидатів до live short-term
promotion store, якщо ви явно не запустите спочатку staged CLI-шлях
- вони не переводять автоматично grounded candidates до live short-term promotion store, якщо ви явно не запустите staged CLI path спочатку
Якщо ви хочете, щоб grounded historical replay впливав на звичайний deep promotion
lane, використайте натомість CLI-процес:
Якщо ви хочете, щоб grounded historical replay впливав на звичайний deep promotion lane, натомість використовуйте CLI-потік:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
Це переміщує grounded durable candidate до short-term dreaming store, при цьому
залишаючи `DREAMS.md` поверхнею для перевірки.
Це переводить grounded durable candidates до short-term dreaming store, зберігаючи `DREAMS.md` як поверхню для перевірки.
## Детальна поведінка та обґрунтування
### 0) Необов’язкове оновлення (git-інсталяції)
### 0) Необов’язкове оновлення (git-встановлення)
Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує
оновити систему (fetch/rebase/build) перед запуском doctor.
Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує оновити (fetch/rebase/build) перед запуском doctor.
### 1) Нормалізація конфігурації
Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction`
без перевизначення для конкретного каналу), doctor нормалізує їх до поточної
схеми.
Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх до поточної схеми.
Це також включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk —
це `talk.provider` + `talk.providers.<provider>`. Doctor переписує старі форми
`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` /
`talk.apiKey` у мапу провайдера.
Сюди входять і застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.<provider>`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдерів.
### 2) Міграції застарілих ключів конфігурації
Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися
і просять вас виконати `openclaw doctor`.
Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися і просять вас запустити `openclaw doctor`.
Doctor виконає таке:
- Пояснить, які саме застарілі ключі було знайдено.
- Покажe міграцію, яку він застосував.
- Пояснить, які застарілі ключі було знайдено.
- Покаже міграцію, яку він застосував.
- Перезапише `~/.openclaw/openclaw.json` оновленою схемою.
Gateway також автоматично запускає міграції doctor під час старту, коли виявляє
застарілий формат конфігурації, тому застарілі конфігурації відновлюються без
ручного втручання.
Міграції сховища завдань Cron обробляються через `openclaw doctor --fix`.
Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тому застарілі конфігурації виправляються без ручного втручання.
Міграції сховища Cron обробляються командою `openclaw doctor --fix`.
Поточні міграції:
@ -173,7 +155,7 @@ Gateway також автоматично запускає міграції doct
- `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`
@ -190,31 +172,28 @@ Gateway також автоматично запускає міграції doct
- `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`
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- видалити `browser.relayBindHost` (застарілий параметр relay розширення)
- видалення `browser.relayBindHost` (застаріле налаштування relay розширення)
Попередження doctor також включають рекомендації щодо акаунта за замовчуванням для багатoакаунтних каналів:
Попередження doctor також містять рекомендації щодо типового акаунта для багатокористувацьких каналів:
- Якщо налаштовано два або більше записи `channels.<channel>.accounts` без `channels.<channel>.defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний акаунт.
- Якщо `channels.<channel>.defaultAccount` вказує на невідомий ID акаунта, doctor попереджає та перелічує налаштовані ID акаунтів.
- Якщо налаштовано два або більше записи `channels.<channel>.accounts` без `channels.<channel>.defaultAccount` або `accounts.default`, doctor попереджає, що fallback routing може вибрати неочікуваний акаунт.
- Якщо `channels.<channel>.defaultAccount` вказано для невідомого ID акаунта, doctor попереджає та перелічує налаштовані ID акаунтів.
### 2b) Перевизначення провайдера OpenCode
Якщо ви вручну додали `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 та вартість для кожної моделі.
### 2c) Міграція браузера та готовність Chrome MCP
Якщо конфігурація браузера все ще вказує на вилучений шлях розширення Chrome, doctor
нормалізує її до поточної моделі підключення host-local Chrome MCP:
Якщо конфігурація браузера все ще вказує на видалений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення host-local Chrome MCP:
- `browser.profiles.*.driver: "extension"` стає `"existing-session"`
- `browser.relayBindHost` видаляється
@ -222,84 +201,54 @@ Gateway також автоматично запускає міграції doct
Doctor також перевіряє шлях host-local Chrome MCP, коли ви використовуєте `defaultProfile:
"user"` або налаштований профіль `existing-session`:
- перевіряє, чи встановлено Google Chrome на тому самому хості для типових
профілів з автоматичним підключенням
- перевіряє, чи встановлено Google Chrome на тому самому хості для типових профілів авто-підключення
- перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144
- нагадує ввімкнути remote debugging на сторінці inspect браузера (наприклад,
`chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`,
або `edge://inspect/#remote-debugging`)
- нагадує ввімкнути remote debugging на сторінці inspect браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`)
Doctor не може ввімкнути цей параметр на боці Chrome за вас. Host-local Chrome MCP
усе ще вимагає:
Doctor не може сам увімкнути це налаштування на боці Chrome. Host-local Chrome MCP як і раніше потребує:
- браузер на базі Chromium 144+ на хості Gateway/Node
- браузер на базі Chromium 144+ на хості gateway/node
- локально запущений браузер
- увімкнений remote debugging у цьому браузері
- підтвердження першого запиту згоди на підключення в браузері
Готовність тут стосується лише передумов локального підключення. Existing-session зберігає
поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF,
перехоплення завантажень і пакетні дії, як і раніше, потребують керованого
браузера або сирого профілю CDP.
Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, як і раніше потребують керованого браузера або профілю raw CDP.
Ця перевірка **не** застосовується до Docker, пісочниці, remote-browser або інших
безголових сценаріїв. Вони й надалі використовують raw CDP.
Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують raw CDP.
### 2d) Передумови OAuth TLS
### 2d) Передумови TLS для OAuth
Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації OpenAI, щоб переконатися, що локальний стек TLS Node/OpenSSL може
перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад,
`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або self-signed сертифікат),
doctor виводить платформозалежні рекомендації щодо виправлення. На macOS з Homebrew Node
виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується
навіть якщо Gateway у справному стані.
Коли налаштовано OAuth-профіль OpenAI Codex, doctor перевіряє endpoint авторизації OpenAI, щоб упевнитися, що локальний стек TLS Node/OpenSSL може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить платформоспецифічні рекомендації щодо виправлення. У macOS з Homebrew Node виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується, навіть якщо gateway працює справно.
### 2c) Перевизначення провайдера Codex OAuth
Якщо ви раніше додали застарілі параметри транспорту OpenAI у
`models.providers.openai-codex`, вони можуть перекривати вбудований шлях провайдера Codex OAuth,
який новіші релізи використовують автоматично. Doctor попереджає, коли бачить
ці старі параметри транспорту поряд із Codex OAuth, щоб ви могли видалити або переписати
застаріле перевизначення транспорту та повернути вбудовану поведінку маршрутизації/резервного вибору.
Власні проксі та перевизначення лише заголовків, як і раніше, підтримуються і не
викликають цього попередження.
Якщо ви раніше додали застарілі налаштування транспорту OpenAI в
`models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші релізи використовують автоматично. Doctor попереджає, коли бачить ці старі налаштування транспорту поряд із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану маршрутизацію/резервну поведінку. Користувацькі проксі та перевизначення лише заголовків, як і раніше, підтримуються і не викликають цього попередження.
### 3) Міграції застарілого стану (структура на диску)
Doctor може переносити старіші структури на диску до поточної:
Doctor може мігрувати старіші структури на диску до поточної структури:
- Сховище сесій + транскрипти:
- з `~/.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`)
- із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`)
- до `~/.openclaw/credentials/whatsapp/<accountId>/...` (типовий ID акаунта: `default`)
Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виводить попередження,
якщо залишає якісь застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує
застарілі сесії + каталог агента під час старту, щоб історія/автентифікація/моделі потрапляли
до шляху конкретного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно
мігрується лише через `openclaw doctor`. Нормалізація провайдера/мапи провайдерів Talk тепер
порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не викликають
повторні порожні зміни `doctor --fix`.
Ці міграції є best-effort та ідемпотентними; doctor виводить попередження, якщо залишає будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує застарілі сесії + каталог agent під час запуску, тож history/auth/models потрапляють до шляху конкретного agent без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера/мапи провайдерів Talk тепер порівнюється за структурною рівністю, тож відмінності лише в порядку ключів більше не спричиняють повторних порожніх змін `doctor --fix`.
### 3a) Міграції застарілих маніфестів Plugin
Doctor сканує всі встановлені маніфести Plugin на наявність застарілих ключів
можливостей верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`,
Doctor сканує всі встановлені маніфести Plugin на наявність застарілих ключів можливостей верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`,
`webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх до об’єкта `contracts`
та переписати файл маніфесту на місці. Ця міграція ідемпотентна;
якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється
без дублювання даних.
`webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх до об’єкта `contracts` і переписати файл маніфесту на місці. Ця міграція є ідемпотентною; якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється без дублювання даних.
### 3b) Міграції застарілого сховища Cron
Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` за замовчуванням,
або `cron.store`, якщо його перевизначено) на наявність старих форм завдань, які планувальник
досі приймає для сумісності.
Doctor також перевіряє сховище Cron-завдань (`~/.openclaw/cron/jobs.json` типово або `cron.store`, якщо перевизначено) на старі форми завдань, які планувальник усе ще приймає задля сумісності.
Поточні очищення Cron включають:
@ -307,247 +256,242 @@ Doctor також перевіряє сховище завдань Cron (`~/.ope
- `schedule.cron` → `schedule.expr`
- поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload`
- поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- псевдоніми delivery для `provider` у payload → явний `delivery.channel`
- прості застарілі резервні завдання Webhook з `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook`
- псевдоніми delivery `provider` у payload → явний `delivery.channel`
- прості застарілі резервні Webhook-завдання `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook`
Doctor автоматично мігрує завдання `notify: true` лише тоді, коли це можна зробити
без зміни поведінки. Якщо завдання поєднує застарілий резервний `notify`
з наявним режимом delivery не для Webhook, doctor попереджає і залишає це завдання
для ручної перевірки.
Doctor автоматично мігрує завдання `notify: true`, лише якщо може зробити це без зміни поведінки. Якщо завдання поєднує застарілий резервний notify з наявним режимом delivery не через webhook, doctor попереджає і залишає це завдання для ручної перевірки.
### 3c) Очищення блокувань сесій
Doctor сканує каталог сесій кожного агента на наявність застарілих файлів блокування запису —
файлів, що залишилися після аварійного завершення сесії. Для кожного знайденого файла блокування він повідомляє:
шлях, PID, чи PID ще активний, вік блокування та чи
вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair`
він автоматично видаляє застарілі файли блокування; інакше виводить примітку та
просить повторно запустити з `--fix`.
Doctor сканує кожен каталог сесій agent на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сесії. Для кожного знайденого файла блокування він повідомляє:
шлях, PID, чи PID все ще активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше виводить примітку та просить перезапустити з `--fix`.
### 3d) Відновлення гілок транскриптів сесій
Doctor сканує JSONL-файли сесій agent на наявність дубльованої форми гілок, створеної багом переписування транскриптів запитів у версії 2026.4.24: покинутий хід користувача з внутрішнім контекстом середовища виконання OpenClaw плюс активний sibling із тим самим видимим запитом користувача. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файла поруч з оригіналом і переписує транскрипт на активну гілку, щоб history і зчитувачі пам’яті gateway більше не бачили дубльовані ходи.
### 4) Перевірки цілісності стану (збереження сесій, маршрутизація та безпека)
Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите
сесії, облікові дані, журнали та конфігурацію (якщо в іншому місці немає резервних копій).
Каталог стану — це операційний стовбур системи. Якщо він зникне, ви втратите
сесії, облікові дані, журнали й конфігурацію (якщо не маєте резервних копій в іншому місці).
Doctor перевіряє:
- **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує відтворити
каталог і нагадує, що не може відновити втрачені дані.
- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує виправити права
(і виводить підказку `chown`, якщо виявлено невідповідність власника/групи).
- **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розташований у iCloud Drive
- **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує відновити каталог і нагадує, що не може відновити втрачені дані.
- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує виправити права доступу
(і виводить підказку `chown`, якщо виявлено невідповідність owner/group).
- **Каталог стану macOS, синхронізований через хмару**: попереджає, коли стан розташовано в iCloud Drive
(`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або
`~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніший I/O
та гонки блокування/синхронізації.
- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан знаходиться на джерелі монтування `mmcblk*`,
оскільки випадковий I/O на носіях SD або eMMC може бути повільнішим і швидше зношуватися
- **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розташовано на джерелі монтування `mmcblk*`,
оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій
під час запису сесій та облікових даних.
- **Відсутні каталоги сесій**: `sessions/` і каталог сховища сесій
потрібні для збереження історії та уникнення збоїв `ENOENT`.
- **Невідповідність транскриптів**: попереджає, коли в нещодавніх записах сесій відсутні
файли транскриптів.
- **Головна сесія “1-line JSONL”**: позначає ситуацію, коли головний транскрипт містить лише один
рядок (історія не накопичується).
потрібні для збереження history та уникнення збоїв `ENOENT`.
- **Невідповідність транскриптів**: попереджає, коли в нещодавніх записах сесій бракує
файлів транскриптів.
- **Основна сесія “1-line JSONL”**: позначає випадки, коли основний транскрипт містить лише один
рядок (history не накопичується).
- **Кілька каталогів стану**: попереджає, коли існує кілька папок `~/.openclaw` у різних
домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може
розділитися між інсталяціями).
- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запускати
домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (history може
розділитися між встановленнями).
- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запустити
його на віддаленому хості (стан зберігається там).
- **Права доступу до файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json`
доступний для читання групі/усім, і пропонує обмежити права до `600`.
- **Права доступу до файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` є
читабельним для групи/всіх, і пропонує обмежити їх до `600`.
### 5) Стан авторизації моделей (строк дії OAuth)
### 5) Стан автентифікації моделей (строк дії OAuth)
Doctor перевіряє профілі OAuth у сховищі авторизації, попереджає, коли строк дії токенів
спливає/сплив, і може оновити їх, коли це безпечно. Якщо профіль
Anthropic OAuth/token застарів, він пропонує використати API-ключ Anthropic або
шлях setup-token Anthropic.
Doctor перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли строк дії токенів
наближається до завершення або вже завершився, і може оновити їх, коли це безпечно. Якщо профіль
OAuth/token Anthropic застарів, він пропонує Anthropic API key або шлях
Anthropic setup-token.
Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive`
пропускає спроби оновлення.
Коли оновлення OAuth остаточно завершується невдачею (наприклад, `refresh_token_reused`,
`invalid_grant` або провайдер повідомляє, що потрібно знову увійти), doctor повідомляє,
що потрібна повторна авторизація, і виводить точну команду `openclaw models auth login --provider ...`,
Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`,
`invalid_grant` або провайдер повідомляє, що потрібно знову ввійти), doctor повідомляє,
що потрібна повторна автентифікація, і виводить точну команду `openclaw models auth login --provider ...`,
яку потрібно виконати.
Doctor також повідомляє про профілі авторизації, які тимчасово непридатні через:
Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні через:
- короткі cooldown (обмеження частоти/тайм-аути/збої авторизації)
- довші вимкнення (проблеми з білінгом/кредитами)
- короткі cooldown (обмеження швидкості/тайм-аути/збої автентифікації)
- довші вимкнення (збої billing/credit)
### 6) Перевірка моделі hooks
### 6) Перевірка моделі Hooks
Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель у
каталозі та allowlist і попереджає, якщо воно не буде розв’язане або заборонене.
Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель відносно
каталогу та списку дозволених значень і попереджає, якщо воно не буде розв’язане або не дозволене.
### 7) Відновлення образу пісочниці
### 7) Відновлення образу sandbox
Коли пісочницю увімкнено, doctor перевіряє Docker-образи та пропонує зібрати їх або
переключитися на застарілі імена, якщо поточний образ відсутній.
Коли sandboxing увімкнено, doctor перевіряє Docker-образи й пропонує зібрати їх або
переключитися на застарілі назви, якщо поточний образ відсутній.
### 7b) Залежності середовища виконання для вбудованих Plugin
### 7b) Залежності середовища виконання вбудованих Plugin
Doctor перевіряє залежності середовища виконання лише для вбудованих Plugin, які активні в
поточній конфігурації або увімкнені типовим значенням у своєму вбудованому маніфесті, наприклад
поточній конфігурації або увімкнені типовим значенням у їхньому вбудованому маніфесті, наприклад
`plugins.entries.discord.enabled: true`, застаріле
`channels.discord.enabled: true`, або типовий увімкнений вбудований провайдер. Якщо
чогось бракує, doctor повідомляє пакети та встановлює їх у режимі
`channels.discord.enabled: true` або типовий увімкнений вбудований провайдер. Якщо будь-яких
залежностей бракує, doctor повідомляє про пакети та встановлює їх у режимі
`openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні Plugin, як і раніше,
використовують `openclaw plugins install` / `openclaw plugins update`; doctor не
встановлює залежності для довільних шляхів Plugin.
Gateway і локальний CLI також можуть на вимогу відновлювати залежності середовища виконання
активних вбудованих Plugin перед імпортом такого Plugin. Ці встановлення
обмежені коренем встановлення середовища виконання Plugin, запускаються з вимкненими скриптами, не
створюють package lock і захищені блокуванням кореня встановлення, щоб одночасні запуски CLI
або Gateway не змінювали те саме дерево `node_modules` одночасно.
Gateway і локальний CLI також можуть відновлювати залежності середовища виконання активних вбудованих Plugin
за потреби перед імпортом вбудованого Plugin. Ці встановлення
обмежуються коренем встановлення середовища виконання Plugin, запускаються з вимкненими script, не
записують package lock і захищені блокуванням install-root, щоб паралельні запуски CLI
або Gateway не змінювали одне й те саме дерево `node_modules` одночасно.
### 8) Міграції сервісів Gateway і підказки з очищення
### 8) Міграції служб gateway і підказки з очищення
Doctor виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і
пропонує видалити їх та встановити сервіс OpenClaw з використанням поточного порту gateway.
Він також може сканувати додаткові сервіси, схожі на gateway, і виводити підказки з очищення.
Сервіси Gateway OpenClaw з іменем профілю вважаються повноцінними та не
позначаються як "додаткові".
Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і
пропонує видалити їх та встановити службу OpenClaw з поточним портом gateway.
Він також може сканувати додаткові служби, схожі на gateway, і виводити підказки щодо очищення.
Іменовані за профілем служби gateway OpenClaw вважаються повноцінними й не позначаються як "зайві".
### 8b) Міграція Matrix під час запуску
### 8b) Стартова міграція Matrix
Коли акаунт каналу Matrix має очікувану або виконувану міграцію застарілого стану,
Коли акаунт каналу Matrix має очікувану або застосовну міграцію застарілого стану,
doctor (у режимі `--fix` / `--repair`) створює знімок стану до міграції, а потім
запускає best-effort кроки міграції: міграцію застарілого стану Matrix і підготовку
застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, і
запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка
застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а
запуск продовжується. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка
повністю пропускається.
### 8c) Сполучення пристроїв і дрейф авторизації
### 8c) Спарювання пристроїв і дрейф автентифікації
Doctor тепер перевіряє стан сполучення пристроїв як частину звичайної перевірки стану.
Doctor тепер перевіряє стан спарювання пристроїв як частину звичайної перевірки стану.
Що він повідомляє:
- очікувані перші запити на сполучення
- очікувані підвищення ролі для вже сполучених пристроїв
- очікувані підвищення обсягу доступу для вже сполучених пристроїв
- відновлення невідповідності публічного ключа, коли id пристрою ще збігається, але
- очікувані перші запити на спарювання
- очікувані підвищення ролі для вже спарених пристроїв
- очікувані підвищення scope для вже спарених пристроїв
- виправлення невідповідності публічного ключа, коли ID пристрою все ще збігається, але
ідентичність пристрою більше не збігається зі схваленим записом
- сполучені записи без активного токена для схваленої ролі
- сполучені токени, чиї обсяги доступу відхиляються від схваленої базової лінії сполучення
- спарені записи без активного токена для схваленої ролі
- спарені токени, чиї scope виходять за межі схваленого базового рівня спарювання
- локальні кешовані записи токенів пристрою для поточної машини, які передують
ротації токена на боці gateway або містять застарілі метадані обсягу доступу
ротації токена на боці gateway або містять застарілі метадані scope
Doctor не схвалює автоматично запити на сполучення і не виконує автоматично ротацію токенів пристрою. Натомість
Doctor не схвалює запити на спарювання автоматично і не виконує автоматичну ротацію токенів пристрою. Натомість
він виводить точні наступні кроки:
- переглянути очікувані запити за допомогою `openclaw devices list`
- схвалити конкретний запит за допомогою `openclaw devices approve <requestId>`
- виконати ротацію нового токена за допомогою `openclaw devices rotate --device <deviceId> --role <role>`
- видалити та повторно схвалити застарілий запис за допомогою `openclaw devices remove <deviceId>`
- перегляньте очікувані запити за допомогою `openclaw devices list`
- схваліть точний запит за допомогою `openclaw devices approve <requestId>`
- виконайте ротацію нового токена за допомогою `openclaw devices rotate --device <deviceId> --role <role>`
- видаліть і повторно схваліть застарілий запис за допомогою `openclaw devices remove <deviceId>`
Це закриває поширену проблему "вже сполучено, але все ще потрібно сполучення":
doctor тепер розрізняє перше сполучення, очікувані підвищення ролі/обсягу доступу
та дрейф застарілого токена/ідентичності пристрою.
Це закриває поширену прогалину "вже спарено, але все одно отримується pairing required":
doctor тепер розрізняє перше спарювання, очікувані підвищення ролі/scope
і дрейф застарілого токена/ідентичності пристрою.
### 9) Попередження безпеки
Doctor виводить попередження, коли провайдер відкритий для DM без allowlist, або
Doctor виводить попередження, коли провайдер відкритий для DM без списку дозволених значень, або
коли політику налаштовано небезпечним чином.
### 10) `systemd linger` (Linux)
Якщо запуск відбувається як користувацький сервіс systemd, doctor перевіряє, що linger увімкнено, щоб
Якщо запуск відбувається як служба користувача systemd, doctor переконується, що linger увімкнено, щоб
gateway залишався активним після виходу з системи.
### 11) Стан workspace (Skills, Plugins і застарілі каталоги)
### 11) Стан робочого простору (skills, plugins і застарілі каталоги)
Doctor виводить підсумок стану workspace для типового агента:
Doctor виводить зведення стану робочого простору для типового agent:
- **Стан Skills**: кількість доступних, missing-requirements і allowlist-blocked Skills.
- **Застарілі каталоги workspace**: попереджає, коли `~/openclaw` або інші застарілі каталоги workspace
існують поруч із поточним workspace.
- **Стан Plugin**: кількість увімкнених/вимкнених/помилкових Plugins; перелічує ID Plugin для будь-яких
- **Стан Skills**: кількість доступних, missing-requirements і allowlist-blocked skills.
- **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору
існують поряд із поточним робочим простором.
- **Стан Plugin**: кількість увімкнених/вимкнених/помилкових Plugin; перелічує ID Plugin для будь-яких
помилок; повідомляє про можливості bundle Plugin.
- **Попередження про сумісність Plugin**: позначає Plugins, які мають проблеми сумісності з
- **Попередження про сумісність Plugin**: позначає Plugin, які мають проблеми сумісності з
поточним середовищем виконання.
- **Діагностика Plugin**: показує будь-які попередження або помилки під час завантаження, які виводить
реєстр Plugin.
- **Діагностика Plugin**: показує будь-які попередження або помилки під час завантаження, які були видані
реєстром Plugin.
### 11b) Розмір файлу ініціалізації
### 11b) Розмір bootstrap-файлу
Doctor перевіряє, чи файли ініціалізації workspace (наприклад `AGENTS.md`,
`CLAUDE.md` або інші інжектовані контекстні файли) наближаються до налаштованого
ліміту символів або перевищують його. Він повідомляє для кожного файла кількість сирих та інжектованих символів,
відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість інжектованих
символів як частку від загального ліміту. Коли файли обрізаються або наближаються до
межі, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars`
і `agents.defaults.bootstrapTotalMaxChars`.
Doctor перевіряє, чи файли bootstrap робочого простору (наприклад `AGENTS.md`,
`CLAUDE.md` або інші вбудовані файли контексту) наближаються до налаштованого
ліміту символів або перевищують його. Він повідомляє для кожного файла необроблену та вбудовану кількість символів, відсоток обрізання,
причину обрізання (`max/file` або `max/total`) і загальну кількість вбудованих
символів як частку від загального ліміту. Коли файли обрізано або вони наближаються до ліміту,
doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars`
та `agents.defaults.bootstrapTotalMaxChars`.
### 11c) Завершення команд оболонки
### 11c) Доповнення команд оболонки
Doctor перевіряє, чи встановлено tab completion для поточної оболонки
Doctor перевіряє, чи встановлено доповнення через Tab для поточної оболонки
(zsh, bash, fish або PowerShell):
- Якщо профіль оболонки використовує повільний шаблон динамічного completion
- Якщо профіль оболонки використовує повільний динамічний шаблон доповнення
(`source <(openclaw completion ...)`), doctor оновлює його до швидшого
варіанта з кешованим файлом.
- Якщо completion налаштовано в профілі, але файл кешу відсутній,
doctor автоматично відновлює кеш.
- Якщо completion взагалі не налаштовано, doctor пропонує встановити його
- Якщо доповнення налаштовано в профілі, але файл кешу відсутній,
doctor автоматично перебудовує кеш.
- Якщо доповнення взагалі не налаштовано, doctor пропонує встановити його
(лише в інтерактивному режимі; пропускається з `--non-interactive`).
Запустіть `openclaw completion --write-state`, щоб вручну відновити кеш.
Виконайте `openclaw completion --write-state`, щоб перебудувати кеш вручну.
### 12) Перевірки автентифікації Gateway (локальний токен)
### 12) Перевірки автентифікації gateway (локальний токен)
Doctor перевіряє готовність локальної автентифікації токеном Gateway.
Doctor перевіряє готовність автентифікації локального токена gateway.
- Якщо режим токена потребує токен, а джерело токена відсутнє, doctor пропонує його згенерувати.
- Якщо режим токена потребує токен, а джерело токена відсутнє, doctor пропонує згенерувати його.
- Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає і не перезаписує його відкритим текстом.
- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано token SecretRef.
- `openclaw doctor --generate-gateway-token` примусово генерує токен, лише якщо не налаштовано token SecretRef.
### 12b) Відновлення в режимі лише читання з урахуванням SecretRef
### 12b) Відновлення з урахуванням SecretRef у режимі лише читання
Деякі сценарії відновлення потребують перевірки налаштованих облікових даних без послаблення поведінки fail-fast під час виконання.
Деякі потоки відновлення потребують перевірки налаштованих облікових даних без послаблення fail-fast поведінки під час виконання.
- `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef у режимі лише читання, що й команди сімейства status, для цільового відновлення конфігурації.
- Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані бота, якщо вони доступні.
- Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху виконання команди, doctor повідомляє, що облікові дані налаштовано, але вони недоступні, і пропускає автоматичне визначення замість аварійного завершення або хибного повідомлення про відсутність токена.
- Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані бота, якщо вони доступні.
- Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне визначення замість аварійного завершення або хибного повідомлення, що токен відсутній.
### 13) Перевірка стану Gateway + перезапуск
### 13) Перевірка стану gateway + перезапуск
Doctor виконує перевірку стану та пропонує перезапустити gateway, якщо він виглядає
несправним.
Doctor виконує перевірку стану і пропонує перезапустити gateway, якщо той
виглядає несправним.
### 13b) Готовність пошуку в пам’яті
Doctor перевіряє, чи готовий налаштований провайдер вбудовувань для пошуку в пам’яті
для типового агента. Поведінка залежить від налаштованого backend і провайдера:
Doctor перевіряє, чи готовий налаштований embedding-провайдер пошуку в пам’яті
для типового agent. Поведінка залежить від налаштованого backend і провайдера:
- **QMD backend**: перевіряє, чи доступний і чи може запускатися бінарний файл `qmd`.
Якщо ні, виводить підказки щодо виправлення, зокрема npm-пакет і варіант ручного шляху до бінарного файла.
- **QMD backend**: перевіряє, чи бінарний файл `qmd` доступний і може запускатися.
Якщо ні, виводить рекомендації щодо виправлення, зокрема npm-пакет і варіант ручного шляху до бінарного файла.
- **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаваного
віддаленого/завантажуваного URL моделі. Якщо його немає, пропонує перейти на віддаленого провайдера.
- **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи є API-ключ
у середовищі або сховищі авторизації. Якщо його немає, виводить практичні підказки щодо виправлення.
- **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого
провайдера в порядку автоматичного вибору.
URL віддаленої/завантажуваної моделі. Якщо його немає, пропонує перейти на віддаленого провайдера.
- **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи присутній API key
у середовищі або в сховищі автентифікації. Якщо його немає, виводить практичні підказки щодо виправлення.
- **Автоматичний провайдер**: спочатку перевіряє наявність локальної моделі, а потім пробує кожного віддаленого
провайдера в порядку автовибору.
Коли результат перевірки gateway доступний (gateway був справний на момент
перевірки), doctor звіряє його результат із конфігурацією, видимою CLI, і зазначає
Коли доступний результат перевірки gateway (gateway був справний на момент
перевірки), doctor зіставляє його результат із видимою для CLI конфігурацією та зазначає
будь-які розбіжності.
Використайте `openclaw memory status --deep`, щоб перевірити готовність вбудовувань під час виконання.
Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання.
### 14) Попередження про стан каналів
Якщо gateway справний, doctor запускає перевірку стану каналів і повідомляє
Якщо gateway справний, doctor виконує перевірку стану каналів і повідомляє
попередження з рекомендованими виправленнями.
### 15) Аудит конфігурації supervisor + відновлення
Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на
відсутні або застарілі типові значення (наприклад, залежності systemd network-online і
затримку перезапуску). Коли він виявляє невідповідність, то рекомендує оновлення і може
переписати файл сервісу/завдання до поточних типових значень.
відсутні або застарілі типові значення (наприклад, залежності systemd від network-online і
затримку перезапуску). Коли він знаходить невідповідність, то рекомендує оновлення і може
переписати файл служби/завдання відповідно до поточних типових значень.
Примітки:
@ -555,41 +499,41 @@ Doctor перевіряє встановлену конфігурацію superv
- `openclaw doctor --yes` приймає типові запити на відновлення.
- `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів.
- `openclaw doctor --repair --force` перезаписує власні конфігурації supervisor.
- Якщо для автентифікації токеном потрібен токен і `gateway.auth.token` керується через SecretRef, під час встановлення/відновлення сервісу doctor перевіряє SecretRef, але не зберігає розв’язані значення токенів відкритим текстом у метаданих середовища сервісу supervisor.
- Якщо для автентифікації токеном потрібен токен, а налаштований token SecretRef не розв’язується, doctor блокує шлях встановлення/відновлення та надає практичні вказівки.
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, але `gateway.auth.mode` не встановлено, doctor блокує встановлення/відновлення, доки режим не буде явно задано.
- Для Linux user-systemd units перевірки дрейфу токена в doctor тепер включають як джерела `Environment=`, так і `EnvironmentFile=` під час порівняння метаданих автентифікації сервісу.
- Ви завжди можете примусово виконати повний перезапис через `openclaw gateway install --force`.
- Якщо автентифікація токеном потребує токен, а `gateway.auth.token` керується через SecretRef, відновлення/встановлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токенів відкритим текстом у метаданих середовища служби supervisor.
- Якщо автентифікація токеном потребує токен, а налаштований token SecretRef не розв’язується, doctor блокує шлях встановлення/відновлення з практичними рекомендаціями.
- Якщо одночасно налаштовано `gateway.auth.token` і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, doctor блокує встановлення/відновлення, доки режим не буде задано явно.
- Для Linux user-systemd unit перевірки дрейфу токена в doctor тепер охоплюють і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби.
- Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`.
### 16) Діагностика середовища виконання Gateway + порту
### 16) Діагностика середовища виконання gateway + порту
Doctor перевіряє середовище виконання сервісу (PID, останній статус завершення) і попереджає, коли
сервіс встановлено, але він фактично не запущений. Він також перевіряє конфлікти портів
на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже
запущено, SSH-тунель).
Doctor перевіряє середовище виконання служби (PID, останній статус завершення) і попереджає, коли
службу встановлено, але вона фактично не працює. Він також перевіряє конфлікти портів
на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже працює,
SSH-тунель).
### 17) Рекомендовані практики для середовища виконання Gateway
### 17) Найкращі практики середовища виконання gateway
Doctor попереджає, коли сервіс gateway працює на Bun або на шляху Node, керованому менеджером версій
Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому менеджером версій
(`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node,
а шляхи менеджерів версій можуть ламатися після оновлень, оскільки сервіс не
завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, якщо
воно доступне (Homebrew/apt/choco).
а шляхи менеджерів версій можуть ламатися після оновлень, оскільки служба не
завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, якщо воно
доступне (Homebrew/apt/choco).
### 18) Запис конфігурації + метадані майстра
Doctor зберігає будь-які зміни конфігурації та проставляє метадані майстра, щоб зафіксувати
Doctor зберігає будь-які зміни конфігурації та записує метадані майстра, щоб зафіксувати
запуск doctor.
### 19) Поради щодо workspace (резервне копіювання + система пам’яті)
### 19) Поради щодо робочого простору (резервне копіювання + система пам’яті)
Doctor пропонує систему пам’яті workspace, якщо її немає, і виводить пораду щодо резервного копіювання,
якщо workspace ще не перебуває під git.
Doctor пропонує систему пам’яті робочого простору, якщо вона відсутня, і виводить пораду щодо резервного копіювання,
якщо робочий простір ще не перебуває під git.
Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace) для повного посібника зі
структури workspace і резервного копіювання через git (рекомендовано приватний GitHub або GitLab).
структури робочого простору та резервного копіювання через git (рекомендовано приватний GitHub або GitLab).
## Пов’язане
- [Усунення проблем Gateway](/uk/gateway/troubleshooting)
- [Усунення несправностей Gateway](/uk/gateway/troubleshooting)
- [Runbook Gateway](/uk/gateway)

231
docs/uk/gateway/security/audit-checks.md
View File

@ -1,131 +1,128 @@
---
read_when:
- Ви побачили певний `checkId` у виводі `openclaw security audit` і хочете дізнатися, що він означає
- Вам потрібен ключ/шлях виправлення для певного знайденого результату
- Ви виконуєте тріаж severity у межах запуску security audit
summary: Довідковий каталог checkId, які видає `openclaw security audit`
title: Перевірки security audit
- Ви побачили конкретний `checkId` у виводі `openclaw security audit` і хочете дізнатися, що він означає
- Вам потрібен ключ/шлях виправлення для певного результату перевірки
- Ви виконуєте тріаж рівня серйозності під час запуску аудиту безпеки
summary: Довідковий каталог `checkId`, які генерує аудит безпеки openclaw
title: Перевірки аудиту безпеки
x-i18n:
generated_at: "2026-04-23T20:54:50Z"
generated_at: "2026-04-26T00:18:15Z"
model: gpt-5.4
provider: openai
source_hash: 107232e94aae9e12b160840691f5a12be6c354dd6162ff5f59b6a56475d27649
source_hash: 7a5463bd1cec8382eb480cbbe1d8f8cceef0c15efc1f9124990df1e8f70b209a
source_path: gateway/security/audit-checks.md
workflow: 15
---
`openclaw security audit` видає структуровані результати, позначені ключем `checkId`. Ця
сторінка є довідковим каталогом для цих ID. Огляд моделі загроз на високому рівні
та рекомендації з посилення захисту див. у [Security](/uk/gateway/security).
`openclaw security audit` генерує структуровані результати перевірки, ключем для яких є `checkId`. Ця сторінка є довідковим каталогом цих ідентифікаторів. Загальну модель загроз і рекомендації щодо посилення захисту див. у [Безпека](/uk/gateway/security).
Найбільш показові значення `checkId`, які ви найімовірніше побачите в реальних розгортаннях (не
вичерпний список):
Високосигнальні значення `checkId`, які ви найімовірніше побачите в реальних розгортаннях (не вичерпний перелік):
| `checkId` | Severity | Why it matters | Primary fix key/path | Auto-fix |
| ------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------- |
| `fs.state_dir.perms_world_writable` | critical | Інші користувачі/процеси можуть змінювати весь стан OpenClaw | права файлової системи для `~/.openclaw` | так |
| `fs.state_dir.perms_group_writable` | warn | Користувачі групи можуть змінювати весь стан OpenClaw | права файлової системи для `~/.openclaw` | так |
| `fs.state_dir.perms_readable` | warn | Каталог стану доступний для читання іншим | права файлової системи для `~/.openclaw` | так |
| `fs.state_dir.symlink` | warn | Ціль каталогу стану стає іншою межею довіри | макет файлової системи каталогу стану | ні |
| `fs.config.perms_writable` | critical | Інші можуть змінювати auth/tool policy/config | права файлової системи для `~/.openclaw/openclaw.json` | так |
| `fs.config.symlink` | warn | Конфігураційні файли через symlink не підтримуються для запису й додають іншу межу довіри | замініть на звичайний файл конфігурації або вкажіть `OPENCLAW_CONFIG_PATH` на реальний файл | ні |
| `fs.config.perms_group_readable` | warn | Користувачі групи можуть читати токени/налаштування конфігурації | права файлової системи для файла конфігурації | так |
| `fs.config.perms_world_readable` | critical | Конфігурація може розкрити токени/налаштування | права файлової системи для файла конфігурації | так |
| `fs.config_include.perms_writable` | critical | Include-файл конфігурації можуть змінити інші | права include-файла, на який посилається `openclaw.json` | так |
| `fs.config_include.perms_group_readable` | warn | Користувачі групи можуть читати включені секрети/налаштування | права include-файла, на який посилається `openclaw.json` | так |
| `fs.config_include.perms_world_readable` | critical | Включені секрети/налаштування доступні для читання всім | права include-файла, на який посилається `openclaw.json` | так |
| `fs.auth_profiles.perms_writable` | critical | Інші можуть впровадити або замінити збережені облікові дані моделей | права для `agents/<agentId>/agent/auth-profiles.json` | так |
| `fs.auth_profiles.perms_readable` | warn | Інші можуть читати API key і OAuth token | права для `agents/<agentId>/agent/auth-profiles.json` | так |
| `fs.credentials_dir.perms_writable` | critical | Інші можуть змінювати стан спарювання/облікових даних каналів | права файлової системи для `~/.openclaw/credentials` | так |
| `fs.credentials_dir.perms_readable` | warn | Інші можуть читати стан облікових даних каналів | права файлової системи для `~/.openclaw/credentials` | так |
| `fs.sessions_store.perms_readable` | warn | Інші можуть читати transcript/метадані сесій | права сховища сесій | так |
| `fs.log_file.perms_readable` | warn | Інші можуть читати журнали, з яких прибрано частину даних, але які все ще чутливі | права файла журналу gateway | так |
| `fs.synced_dir` | warn | Стан/конфігурація в iCloud/Dropbox/Drive розширює зону доступу до токенів/transcript | перемістіть конфігурацію/стан із синхронізованих папок | ні |
| `gateway.bind_no_auth` | critical | Віддалене bind без спільного секрету | `gateway.bind`, `gateway.auth.*` | ні |
| `gateway.loopback_no_auth` | critical | Loopback через reverse proxy може стати неавтентифікованим | `gateway.auth.*`, налаштування proxy | ні |
| `gateway.trusted_proxies_missing` | warn | Заголовки reverse proxy присутні, але не позначені як довірені | `gateway.trustedProxies` | ні |
| `gateway.http.no_auth` | warn/critical | HTTP API Gateway доступні з `auth.mode="none"` | `gateway.auth.mode`, `gateway.http.endpoints.*` | ні |
| `gateway.http.session_key_override_enabled` | info | Виклики HTTP API можуть перевизначати `sessionKey` | `gateway.http.allowSessionKeyOverride` | ні |
| `gateway.tools_invoke_http.dangerous_allow` | warn/critical | Повторно вмикає небезпечні інструменти через HTTP API | `gateway.tools.allow` | ні |
| `gateway.nodes.allow_commands_dangerous` | warn/critical | Увімкнено високоризикові команди Node (camera/screen/contacts/calendar/SMS) | `gateway.nodes.allowCommands` | ні |
| `gateway.nodes.deny_commands_ineffective` | warn | Записи deny у стилі шаблонів не збігаються з shell-текстом або групами | `gateway.nodes.denyCommands` | ні |
| `gateway.tailscale_funnel` | critical | Відкриття в публічний інтернет | `gateway.tailscale.mode` | ні |
| `gateway.tailscale_serve` | info | Увімкнено доступ через tailnet за допомогою Serve | `gateway.tailscale.mode` | ні |
| `gateway.control_ui.allowed_origins_required` | critical | Control UI не в loopback без явного allowlist browser-origin | `gateway.controlUi.allowedOrigins` | ні |
| `gateway.control_ui.allowed_origins_wildcard` | warn/critical | `allowedOrigins=["*"]` вимикає allowlist browser-origin | `gateway.controlUi.allowedOrigins` | ні |
| `gateway.control_ui.host_header_origin_fallback` | warn/critical | Увімкнено fallback origin через Host-header (послаблення захисту від DNS rebinding) | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | ні |
| `gateway.control_ui.insecure_auth` | warn | Увімкнено перемикач сумісності insecure-auth | `gateway.controlUi.allowInsecureAuth` | ні |
| `gateway.control_ui.device_auth_disabled` | critical | Вимкнено перевірку ідентичності пристрою | `gateway.controlUi.dangerouslyDisableDeviceAuth` | ні |
| `gateway.real_ip_fallback_enabled` | warn/critical | Довіра до fallback `X-Real-IP` може дозволити підміну source-IP через помилкову конфігурацію proxy | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | ні |
| `gateway.token_too_short` | warn | Короткий спільний токен легше підібрати | `gateway.auth.token` | ні |
| `gateway.auth_no_rate_limit` | warn | Відкритий auth без rate limiting підвищує ризик brute-force | `gateway.auth.rateLimit` | ні |
| `gateway.trusted_proxy_auth` | critical | Ідентичність proxy тепер стає межею автентифікації | `gateway.auth.mode="trusted-proxy"` | ні |
| `gateway.trusted_proxy_no_proxies` | critical | Автентифікація trusted-proxy без IP довірених proxy є небезпечною | `gateway.trustedProxies` | ні |
| `gateway.trusted_proxy_no_user_header` | critical | Автентифікація trusted-proxy не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | ні |
| `gateway.trusted_proxy_no_allowlist` | warn | Автентифікація trusted-proxy приймає будь-якого автентифікованого користувача upstream | `gateway.auth.trustedProxy.allowUsers` | ні |
| `gateway.probe_auth_secretref_unavailable` | warn | Глибока probe не змогла визначити auth SecretRef у цьому шляху команди | джерело auth для deep-probe / доступність SecretRef | ні |
| `gateway.probe_failed` | warn/critical | Не вдалася live-probe Gateway | доступність/автентифікація gateway | ні |
| `discovery.mdns_full_mode` | warn/critical | Повний режим mDNS оголошує метадані `cliPath`/`sshPort` у локальній мережі | `discovery.mdns.mode`, `gateway.bind` | ні |
| `config.insecure_or_dangerous_flags` | warn | Увімкнено будь-які небезпечні/незахищені debug-прапорці | кілька ключів (див. деталі результату) | ні |
| `config.secrets.gateway_password_in_config` | warn | Пароль Gateway зберігається безпосередньо в конфігурації | `gateway.auth.password` | ні |
| `config.secrets.hooks_token_in_config` | warn | Bearer token для hooks зберігається безпосередньо в конфігурації | `hooks.token` | ні |
| `hooks.token_reuse_gateway_token` | critical | Токен входу hooks також відкриває доступ до автентифікації Gateway | `hooks.token`, `gateway.auth.token` | ні |
| `hooks.token_too_short` | warn | Полегшує brute force для входу hooks | `hooks.token` | ні |
| `hooks.default_session_key_unset` | warn | Запуски агента через hooks розгалужуються в згенеровані сесії для кожного запиту | `hooks.defaultSessionKey` | ні |
| `hooks.allowed_agent_ids_unrestricted` | warn/critical | Автентифіковані виклики hooks можуть маршрутизуватися до будь-якого налаштованого агента | `hooks.allowedAgentIds` | ні |
| `hooks.request_session_key_enabled` | warn/critical | Зовнішній виклик може вибирати `sessionKey` | `hooks.allowRequestSessionKey` | ні |
| `hooks.request_session_key_prefixes_missing` | warn/critical | Немає обмежень на форму зовнішніх ключів сесії | `hooks.allowedSessionKeyPrefixes` | ні |
| `hooks.path_root` | critical | Шлях hooks — це `/`, що полегшує колізії або помилкову маршрутизацію входу | `hooks.path` | ні |
| `hooks.installs_unpinned_npm_specs` | warn | Записи встановлення hooks не прив’язані до незмінних npm-spec | метадані встановлення hooks | ні |
| `hooks.installs_missing_integrity` | warn | У записах встановлення hooks відсутні метадані integrity | метадані встановлення hooks | ні |
| `hooks.installs_version_drift` | warn | Записи встановлення hooks розходяться з установленими пакетами | метадані встановлення hooks | ні |
| `logging.redact_off` | warn | Чутливі значення потрапляють у журнали/статус | `logging.redactSensitive` | так |
| `browser.control_invalid_config` | warn | Конфігурація керування браузером невалідна ще до runtime | `browser.*` | ні |
| `browser.control_no_auth` | critical | Керування браузером відкрите без автентифікації токеном/паролем | `gateway.auth.*` | ні |
| `browser.remote_cdp_http` | warn | Віддалений CDP через звичайний HTTP не має шифрування транспорту | profile браузера `cdpUrl` | ні |
| `browser.remote_cdp_private_host` | warn | Віддалений CDP націлений на приватний/internal host | profile браузера `cdpUrl`, `browser.ssrfPolicy.*` | ні |
| `sandbox.docker_config_mode_off` | warn | Конфігурація Docker sandbox присутня, але неактивна | `agents.*.sandbox.mode` | ні |
| `sandbox.bind_mount_non_absolute` | warn | Відносні bind mount можуть визначатися непередбачувано | `agents.*.sandbox.docker.binds[]` | ні |
| `sandbox.dangerous_bind_mount` | critical | Bind mount sandbox націлено на заблоковані системні шляхи, облікові дані або Docker socket | `agents.*.sandbox.docker.binds[]` | ні |
| `sandbox.dangerous_network_mode` | critical | Мережа Docker sandbox використовує режим `host` або `container:*` із приєднанням простору імен | `agents.*.sandbox.docker.network` | ні |
| `sandbox.dangerous_seccomp_profile` | critical | Профіль seccomp sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні |
| `sandbox.dangerous_apparmor_profile` | critical | Профіль AppArmor sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні |
| `sandbox.browser_cdp_bridge_unrestricted` | warn | Міст browser sandbox відкритий без обмеження діапазону джерел | `sandbox.browser.cdpSourceRange` | ні |
| `sandbox.browser_container.non_loopback_publish` | critical | Наявний browser container публікує CDP на інтерфейсах, відмінних від loopback | конфігурація publish контейнера browser sandbox | ні |
| `sandbox.browser_container.hash_label_missing` | warn | Наявний browser container створено до поточних міток config-hash | `openclaw sandbox recreate --browser --all` | ні |
| `sandbox.browser_container.hash_epoch_stale` | warn | Наявний browser container передує поточній епосі конфігурації браузера | `openclaw sandbox recreate --browser --all` | ні |
| `tools.exec.host_sandbox_no_sandbox_defaults` | warn | `exec host=sandbox` завершується в режимі fail closed, коли sandbox вимкнено | `tools.exec.host`, `agents.defaults.sandbox.mode` | ні |
| `tools.exec.host_sandbox_no_sandbox_agents` | warn | `exec host=sandbox` для окремого агента завершується в режимі fail closed, коли sandbox вимкнено | `agents.list[].tools.exec.host`, `agents.list[].sandbox.mode` | ні |
| `tools.exec.security_full_configured` | warn/critical | Host exec працює з `security="full"` | `tools.exec.security`, `agents.list[].tools.exec.security` | ні |
| `tools.exec.auto_allow_skills_enabled` | warn | Погодження exec неявно довіряють бінарним файлам Skills | `~/.openclaw/exec-approvals.json` | ні |
| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | warn | Allowlist інтерпретаторів дозволяють inline eval без примусового повторного погодження | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, allowlist погоджень exec | ні |
| `tools.exec.safe_bins_interpreter_unprofiled` | warn | Інтерпретатори/runtime-бінарники в `safeBins` без явних profile розширюють ризик exec | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | ні |
| `tools.exec.safe_bins_broad_behavior` | warn | Інструменти широкої поведінки в `safeBins` послаблюють модель довіри low-risk stdin-filter | `tools.exec.safeBins`, `agents.list[].tools.exec.safeBins` | ні |
| `tools.exec.safe_bin_trusted_dirs_risky` | warn | `safeBinTrustedDirs` містить змінювані або ризикові каталоги | `tools.exec.safeBinTrustedDirs`, `agents.list[].tools.exec.safeBinTrustedDirs` | ні |
| `skills.workspace.symlink_escape` | warn | `skills/**/SKILL.md` у робочому просторі визначається поза коренем робочого простору (drift ланцюга symlink) | стан файлової системи `skills/**` у робочому просторі | ні |
| `plugins.extensions_no_allowlist` | warn | Plugins встановлюються без явного allowlist Plugin | `plugins.allowlist` | ні |
| `plugins.installs_unpinned_npm_specs` | warn | Записи встановлення Plugin не прив’язані до незмінних npm-spec | метадані встановлення Plugin | ні |
| `plugins.installs_missing_integrity` | warn | У записах встановлення Plugin відсутні метадані integrity | метадані встановлення Plugin | ні |
| `plugins.installs_version_drift` | warn | Записи встановлення Plugin розходяться з установленими пакетами | метадані встановлення Plugin | ні |
| `plugins.code_safety` | warn/critical | Сканування коду Plugin виявило підозрілі або небезпечні шаблони | код Plugin / джерело встановлення | ні |
| `plugins.code_safety.entry_path` | warn | Шлях входу Plugin вказує на приховані розташування або `node_modules` | `entry` у manifest Plugin | ні |
| `plugins.code_safety.entry_escape` | critical | Точка входу Plugin виходить за межі каталогу Plugin | `entry` у manifest Plugin | ні |
| `plugins.code_safety.scan_failed` | warn | Сканування коду Plugin не вдалося завершити | шлях Plugin / середовище сканування | ні |
| `skills.code_safety` | warn/critical | Метадані встановлення/код Skill містять підозрілі або небезпечні шаблони | джерело встановлення Skill | ні |
| `skills.code_safety.scan_failed` | warn | Сканування коду Skill не вдалося завершити | середовище сканування Skill | ні |
| `security.exposure.open_channels_with_exec` | warn/critical | Спільні/публічні кімнати можуть звертатися до агентів з увімкненим exec | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*` | ні |
| `security.exposure.open_groups_with_elevated` | critical | Відкриті групи + elevated tools створюють високоризикові шляхи prompt injection | `channels.*.groupPolicy`, `tools.elevated.*` | ні |
| `security.exposure.open_groups_with_runtime_or_fs` | critical/warn | Відкриті групи можуть звертатися до інструментів команд/файлів без захисту sandbox/робочого простору | `channels.*.groupPolicy`, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode` | ні |
| `security.trust_model.multi_user_heuristic` | warn | Конфігурація виглядає багатокористувацькою, тоді як модель довіри gateway — personal-assistant | розділіть межі довіри або застосуйте посилення захисту для спільного використання (`sandbox.mode`, deny інструментів/обмеження робочого простору) | ні |
| `tools.profile_minimal_overridden` | warn | Перевизначення агента обходять глобальний minimal profile | `agents.list[].tools.profile` | ні |
| `plugins.tools_reachable_permissive_policy` | warn | Інструменти розширень досяжні в дозволяючих контекстах | `tools.profile` + allow/deny інструментів | ні |
| `models.legacy` | warn | Застарілі сімейства моделей усе ще налаштовані | вибір моделі | ні |
| `models.weak_tier` | warn | Налаштовані моделі нижчі за поточні рекомендовані рівні | вибір моделі | ні |
| `models.small_params` | critical/info | Малі моделі + небезпечні поверхні інструментів підвищують ризик injection | вибір моделі + policy sandbox/інструментів | ні |
| `summary.attack_surface` | info | Зведений підсумок щодо auth, каналів, інструментів і рівня відкритості | кілька ключів (див. деталі результату) | ні |
| `checkId` | Рівень серйозності | Чому це важливо | Основний ключ/шлях виправлення | Автовиправлення |
| ------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------- |
| `fs.state_dir.perms_world_writable` | критичний | Інші користувачі/процеси можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так |
| `fs.state_dir.perms_group_writable` | попередження | Користувачі групи можуть змінювати весь стан OpenClaw | дозволи файлової системи для `~/.openclaw` | так |
| `fs.state_dir.perms_readable` | попередження | Каталог стану доступний для читання іншими | дозволи файлової системи для `~/.openclaw` | так |
| `fs.state_dir.symlink` | попередження | Ціль каталогу стану стає іншою межею довіри | структура файлової системи каталогу стану | ні |
| `fs.config.perms_writable` | критичний | Інші можуть змінювати політику автентифікації/інструментів/конфігурацію | дозволи файлової системи для `~/.openclaw/openclaw.json` | так |
| `fs.config.symlink` | попередження | Символічні посилання для файлів конфігурації не підтримуються для запису та додають ще одну межу довіри | замініть на звичайний файл конфігурації або вкажіть `OPENCLAW_CONFIG_PATH` на реальний файл | ні |
| `fs.config.perms_group_readable` | попередження | Користувачі групи можуть читати токени/налаштування конфігурації | дозволи файлової системи для файлу конфігурації | так |
| `fs.config.perms_world_readable` | критичний | Конфігурація може розкрити токени/налаштування | дозволи файлової системи для файлу конфігурації | так |
| `fs.config_include.perms_writable` | критичний | Включений файл конфігурації можуть змінювати інші | дозволи файлу включення, на який посилається `openclaw.json` | так |
| `fs.config_include.perms_group_readable` | попередження | Користувачі групи можуть читати включені секрети/налаштування | дозволи файлу включення, на який посилається `openclaw.json` | так |
| `fs.config_include.perms_world_readable` | критичний | Включені секрети/налаштування доступні для читання всім | дозволи файлу включення, на який посилається `openclaw.json` | так |
| `fs.auth_profiles.perms_writable` | критичний | Інші можуть впровадити або замінити збережені облікові дані моделі | дозволи для `agents/<agentId>/agent/auth-profiles.json` | так |
| `fs.auth_profiles.perms_readable` | попередження | Інші можуть читати API-ключі та OAuth-токени | дозволи для `agents/<agentId>/agent/auth-profiles.json` | так |
| `fs.credentials_dir.perms_writable` | критичний | Інші можуть змінювати стан сполучення каналів/облікових даних | дозволи файлової системи для `~/.openclaw/credentials` | так |
| `fs.credentials_dir.perms_readable` | попередження | Інші можуть читати стан облікових даних каналів | дозволи файлової системи для `~/.openclaw/credentials` | так |
| `fs.sessions_store.perms_readable` | попередження | Інші можуть читати транскрипти/метадані сеансів | дозволи сховища сеансів | так |
| `fs.log_file.perms_readable` | попередження | Інші можуть читати журнали, з яких вилучено частину даних, але які все ще містять чутливу інформацію | дозволи файлу журналу Gateway | так |
| `fs.synced_dir` | попередження | Зберігання стану/конфігурації в iCloud/Dropbox/Drive розширює ризик розкриття токенів/транскриптів | перемістіть конфігурацію/стан за межі синхронізованих папок | ні |
| `gateway.bind_no_auth` | критичний | Віддалена прив’язка без спільного секрету | `gateway.bind`, `gateway.auth.*` | ні |
| `gateway.loopback_no_auth` | критичний | local loopback за зворотним проксі може стати неавтентифікованим | `gateway.auth.*`, налаштування проксі | ні |
| `gateway.trusted_proxies_missing` | попередження | Заголовки зворотного проксі присутні, але не довірені | `gateway.trustedProxies` | ні |
| `gateway.http.no_auth` | попередження/критичний | HTTP API Gateway доступні з `auth.mode="none"` | `gateway.auth.mode`, `gateway.http.endpoints.*` | ні |
| `gateway.http.session_key_override_enabled` | інформаційний | Виклики HTTP API можуть перевизначати `sessionKey` | `gateway.http.allowSessionKeyOverride` | ні |
| `gateway.tools_invoke_http.dangerous_allow` | попередження/критичний | Повторно вмикає небезпечні інструменти через HTTP API | `gateway.tools.allow` | ні |
| `gateway.nodes.allow_commands_dangerous` | попередження/критичний | Вмикає команди Node з високим впливом (камера/екран/контакти/календар/SMS) | `gateway.nodes.allowCommands` | ні |
| `gateway.nodes.deny_commands_ineffective` | попередження | Записи deny у стилі шаблонів не збігаються з текстом оболонки або групами | `gateway.nodes.denyCommands` | ні |
| `gateway.tailscale_funnel` | критичний | Публічна доступність з інтернету | `gateway.tailscale.mode` | ні |
| `gateway.tailscale_serve` | інформаційний | Доступність у tailnet увімкнена через Serve | `gateway.tailscale.mode` | ні |
| `gateway.control_ui.allowed_origins_required` | критичний | Для немісцевого Control UI немає явного списку дозволених origin браузера | `gateway.controlUi.allowedOrigins` | ні |
| `gateway.control_ui.allowed_origins_wildcard` | попередження/критичний | `allowedOrigins=["*"]` вимикає список дозволених origin браузера | `gateway.controlUi.allowedOrigins` | ні |
| `gateway.control_ui.host_header_origin_fallback` | попередження/критичний | Вмикає резервне визначення origin через заголовок Host (послаблення захисту від DNS rebinding) | `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback` | ні |
| `gateway.control_ui.insecure_auth` | попередження | Увімкнено перемикач сумісності з небезпечною автентифікацією | `gateway.controlUi.allowInsecureAuth` | ні |
| `gateway.control_ui.device_auth_disabled` | критичний | Вимикає перевірку ідентичності пристрою | `gateway.controlUi.dangerouslyDisableDeviceAuth` | ні |
| `gateway.real_ip_fallback_enabled` | попередження/критичний | Довіра до резервного `X-Real-IP` може дозволити підміну вихідної IP-адреси через хибну конфігурацію проксі | `gateway.allowRealIpFallback`, `gateway.trustedProxies` | ні |
| `gateway.token_too_short` | попередження | Короткий спільний токен легше підібрати перебором | `gateway.auth.token` | ні |
| `gateway.auth_no_rate_limit` | попередження | Доступна автентифікація без обмеження частоти запитів збільшує ризик brute-force | `gateway.auth.rateLimit` | ні |
| `gateway.trusted_proxy_auth` | критичний | Ідентичність проксі тепер стає межею автентифікації | `gateway.auth.mode="trusted-proxy"` | ні |
| `gateway.trusted_proxy_no_proxies` | критичний | Автентифікація trusted-proxy без IP-адрес довірених проксі є небезпечною | `gateway.trustedProxies` | ні |
| `gateway.trusted_proxy_no_user_header` | критичний | Автентифікація trusted-proxy не може безпечно визначити ідентичність користувача | `gateway.auth.trustedProxy.userHeader` | ні |
| `gateway.trusted_proxy_no_allowlist` | попередження | Автентифікація trusted-proxy приймає будь-якого автентифікованого користувача вище за потоком | `gateway.auth.trustedProxy.allowUsers` | ні |
| `gateway.probe_auth_secretref_unavailable` | попередження | Поглиблена перевірка не змогла розв’язати auth SecretRef у цьому шляху команди | джерело auth для поглибленої перевірки / доступність SecretRef | ні |
| `gateway.probe_failed` | попередження/критичний | Жива перевірка Gateway завершилася помилкою | доступність/автентифікація Gateway | ні |
| `discovery.mdns_full_mode` | попередження/критичний | Повний режим mDNS рекламує метадані `cliPath`/`sshPort` у локальній мережі | `discovery.mdns.mode`, `gateway.bind` | ні |
| `config.insecure_or_dangerous_flags` | попередження | Увімкнено будь-які небезпечні або ризиковані налагоджувальні прапорці | кілька ключів (див. деталі результату перевірки) | ні |
| `config.secrets.gateway_password_in_config` | попередження | Пароль Gateway зберігається безпосередньо в конфігурації | `gateway.auth.password` | ні |
| `config.secrets.hooks_token_in_config` | попередження | Bearer-токен hooks зберігається безпосередньо в конфігурації | `hooks.token` | ні |
| `hooks.token_reuse_gateway_token` | критичний | Токен вхідних hooks також відкриває доступ до автентифікації Gateway | `hooks.token`, `gateway.auth.token` | ні |
| `hooks.token_too_short` | попередження | Легше виконати brute force для вхідних hooks | `hooks.token` | ні |
| `hooks.default_session_key_unset` | попередження | Агент hooks запускає fan out у згенеровані окремі сеанси на кожен запит | `hooks.defaultSessionKey` | ні |
| `hooks.allowed_agent_ids_unrestricted` | попередження/критичний | Автентифіковані виклики hooks можуть маршрутизуватися до будь-якого налаштованого агента | `hooks.allowedAgentIds` | ні |
| `hooks.request_session_key_enabled` | попередження/критичний | Зовнішній виклик може вибирати `sessionKey` | `hooks.allowRequestSessionKey` | ні |
| `hooks.request_session_key_prefixes_missing` | попередження/критичний | Немає обмеження на форму зовнішніх ключів сеансу | `hooks.allowedSessionKeyPrefixes` | ні |
| `hooks.path_root` | критичний | Шлях hooks дорівнює `/`, що полегшує колізії або помилкову маршрутизацію вхідних запитів | `hooks.path` | ні |
| `hooks.installs_unpinned_npm_specs` | попередження | Записи встановлення hooks не закріплені за незмінними специфікаціями npm | метадані встановлення hooks | ні |
| `hooks.installs_missing_integrity` | попередження | У записах встановлення hooks відсутні метадані цілісності | метадані встановлення hooks | ні |
| `hooks.installs_version_drift` | попередження | Записи встановлення hooks розходяться з установленими пакетами | метадані встановлення hooks | ні |
| `logging.redact_off` | попередження | Чутливі значення потрапляють у журнали/стан | `logging.redactSensitive` | так |
| `browser.control_invalid_config` | попередження | Конфігурація керування браузером є невалідною ще до виконання | `browser.*` | ні |
| `browser.control_no_auth` | критичний | Керування браузером доступне без автентифікації через токен/пароль | `gateway.auth.*` | ні |
| `browser.remote_cdp_http` | попередження | Віддалений CDP через звичайний HTTP не має шифрування транспорту | профіль браузера `cdpUrl` | ні |
| `browser.remote_cdp_private_host` | попередження | Віддалений CDP націлений на приватний/внутрішній хост | профіль браузера `cdpUrl`, `browser.ssrfPolicy.*` | ні |
| `sandbox.docker_config_mode_off` | попередження | Конфігурація Docker для sandbox присутня, але неактивна | `agents.*.sandbox.mode` | ні |
| `sandbox.bind_mount_non_absolute` | попередження | Відносні bind mount можуть розв’язуватися непередбачувано | `agents.*.sandbox.docker.binds[]` | ні |
| `sandbox.dangerous_bind_mount` | критичний | Bind mount sandbox націлюється на заблоковані системні шляхи, облікові дані або шляхи сокета Docker | `agents.*.sandbox.docker.binds[]` | ні |
| `sandbox.dangerous_network_mode` | критичний | Мережа Docker для sandbox використовує `host` або режим приєднання до простору назв `container:*` | `agents.*.sandbox.docker.network` | ні |
| `sandbox.dangerous_seccomp_profile` | критичний | Профіль seccomp для sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні |
| `sandbox.dangerous_apparmor_profile` | критичний | Профіль AppArmor для sandbox послаблює ізоляцію контейнера | `agents.*.sandbox.docker.securityOpt` | ні |
| `sandbox.browser_cdp_bridge_unrestricted` | попередження | Міст CDP браузера в sandbox доступний без обмеження діапазону джерел | `sandbox.browser.cdpSourceRange` | ні |
| `sandbox.browser_container.non_loopback_publish` | критичний | Наявний контейнер браузера публікує CDP на немісцевих інтерфейсах | конфігурація публікації контейнера browser sandbox | ні |
| `sandbox.browser_container.hash_label_missing` | попередження | Наявний контейнер браузера передує поточним міткам хешу конфігурації | `openclaw sandbox recreate --browser --all` | ні |
| `sandbox.browser_container.hash_epoch_stale` | попередження | Наявний контейнер браузера передує поточній епосі конфігурації браузера | `openclaw sandbox recreate --browser --all` | ні |
| `tools.exec.host_sandbox_no_sandbox_defaults` | попередження | `exec host=sandbox` безпечно завершується відмовою, коли sandbox вимкнено | `tools.exec.host`, `agents.defaults.sandbox.mode` | ні |
| `tools.exec.host_sandbox_no_sandbox_agents` | попередження | `exec host=sandbox` для окремого агента безпечно завершується відмовою, коли sandbox вимкнено | `agents.list[].tools.exec.host`, `agents.list[].sandbox.mode` | ні |
| `tools.exec.security_full_configured` | попередження/критичний | Host exec працює з `security="full"` | `tools.exec.security`, `agents.list[].tools.exec.security` | ні |
| `tools.exec.auto_allow_skills_enabled` | попередження | Схвалення exec неявно довіряють бінарним файлам Skills | `~/.openclaw/exec-approvals.json` | ні |
| `tools.exec.allowlist_interpreter_without_strict_inline_eval` | попередження | Списки дозволів інтерпретаторів дозволяють inline eval без примусового повторного схвалення | `tools.exec.strictInlineEval`, `agents.list[].tools.exec.strictInlineEval`, список дозволів exec | ні |
| `tools.exec.safe_bins_interpreter_unprofiled` | попередження | Бінарні файли інтерпретаторів/середовищ виконання в `safeBins` без явних профілів розширюють ризик exec | `tools.exec.safeBins`, `tools.exec.safeBinProfiles`, `agents.list[].tools.exec.*` | ні |
| `tools.exec.safe_bins_broad_behavior` | попередження | Інструменти з широкою поведінкою в `safeBins` послаблюють модель довіри stdin-фільтра з низьким ризиком | `tools.exec.safeBins`, `agents.list[].tools.exec.safeBins` | ні |
| `tools.exec.safe_bin_trusted_dirs_risky` | попередження | `safeBinTrustedDirs` містить змінювані або ризиковані каталоги | `tools.exec.safeBinTrustedDirs`, `agents.list[].tools.exec.safeBinTrustedDirs` | ні |
| `skills.workspace.symlink_escape` | попередження | `skills/**/SKILL.md` у робочому просторі розв’язується поза коренем робочого простору (зсув ланцюжка символьних посилань) | стан файлової системи робочого простору `skills/**` | ні |
| `plugins.extensions_no_allowlist` | попередження | Plugins встановлені без явного списку дозволених Plugins | `plugins.allowlist` | ні |
| `plugins.installs_unpinned_npm_specs` | попередження | Записи індексу встановлення Plugin не закріплені за незмінними специфікаціями npm | метадані встановлення Plugin | ні |
| `plugins.installs_missing_integrity` | попередження | Записи індексу встановлення Plugin не містять метаданих цілісності | метадані встановлення Plugin | ні |
| `plugins.installs_version_drift` | попередження | Записи індексу встановлення Plugin розходяться з установленими пакетами | метадані встановлення Plugin | ні |
| `plugins.code_safety` | попередження/критичний | Сканування коду Plugin виявило підозрілі або небезпечні шаблони | код Plugin / джерело встановлення | ні |
| `plugins.code_safety.entry_path` | попередження | Шлях входу Plugin вказує на приховані розташування або `node_modules` | `entry` у маніфесті Plugin | ні |
| `plugins.code_safety.entry_escape` | критичний | Точка входу Plugin виходить за межі каталогу Plugin | `entry` у маніфесті Plugin | ні |
| `plugins.code_safety.scan_failed` | попередження | Сканування коду Plugin не вдалося завершити | шлях Plugin / середовище сканування | ні |
| `skills.code_safety` | попередження/критичний | Метадані інсталятора/код Skill містять підозрілі або небезпечні шаблони | джерело встановлення Skill | ні |
| `skills.code_safety.scan_failed` | попередження | Сканування коду Skill не вдалося завершити | середовище сканування Skill | ні |
| `security.exposure.open_channels_with_exec` | попередження/критичний | Спільні/публічні кімнати можуть звертатися до агентів з увімкненим exec | `channels.*.dmPolicy`, `channels.*.groupPolicy`, `tools.exec.*`, `agents.list[].tools.exec.*` | ні |
| `security.exposure.open_groups_with_elevated` | критичний | Відкриті групи разом із привілейованими інструментами створюють шляхи prompt injection з високим впливом | `channels.*.groupPolicy`, `tools.elevated.*` | ні |
| `security.exposure.open_groups_with_runtime_or_fs` | критичний/попередження | Відкриті групи можуть звертатися до інструментів команд/файлів без захисту sandbox/робочого простору | `channels.*.groupPolicy`, `tools.profile/deny`, `tools.fs.workspaceOnly`, `agents.*.sandbox.mode` | ні |
| `security.trust_model.multi_user_heuristic` | попередження | Конфігурація виглядає багатокористувацькою, тоді як модель довіри Gateway призначена для персонального помічника | розділіть межі довіри або застосуйте посилений захист для спільного використання (`sandbox.mode`, deny для інструментів/обмеження робочого простору) | ні |
| `tools.profile_minimal_overridden` | попередження | Перевизначення агента обходять глобальний мінімальний профіль | `agents.list[].tools.profile` | ні |
| `plugins.tools_reachable_permissive_policy` | попередження | Інструменти розширень доступні в поблажливих контекстах | `tools.profile` + allow/deny для інструментів | ні |
| `models.legacy` | попередження | Досі налаштовані застарілі сімейства моделей | вибір моделі | ні |
| `models.weak_tier` | попередження | Налаштовані моделі нижчі за поточні рекомендовані рівні | вибір моделі | ні |
| `models.small_params` | критичний/інформаційний | Малі моделі разом із небезпечними поверхнями інструментів підвищують ризик injection | вибір моделі + політика sandbox/інструментів | ні |
| `summary.attack_surface` | інформаційний | Узагальнювальне резюме стану автентифікації, каналів, інструментів і рівня відкритості | кілька ключів (див. деталі результату перевірки) | ні |
## Пов’язане
- [Security](/uk/gateway/security)
- [Configuration](/uk/gateway/configuration)
- [Trusted proxy auth](/uk/gateway/trusted-proxy-auth)
- [Безпека](/uk/gateway/security)
- [Конфігурація](/uk/gateway/configuration)
- [Автентифікація trusted proxy](/uk/gateway/trusted-proxy-auth)

783
docs/uk/help/testing.md
View File

File diff suppressed because it is too large Load Diff

840
docs/uk/plugins/architecture-internals.md
View File

File diff suppressed because it is too large Load Diff

502
docs/uk/plugins/codex-harness.md
View File

@ -1,32 +1,37 @@
---
read_when:
- Ви хочете використовувати комплектний каркас app-server Codex
- Вам потрібні приклади конфігурації каркаса Codex
- Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу до Pi
summary: Запустіть вбудовані ходи агента OpenClaw через комплектний каркас app-server Codex
title: каркас Codex
- Ви хочете використовувати вбудований harness app-server Codex
- Вам потрібні приклади конфігурації Codex harness
- Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість повернення до PI
summary: Запускайте вбудовані ходи агента OpenClaw через вбудований harness app-server Codex
title: Codex harness
x-i18n:
generated_at: "2026-04-25T23:54:39Z"
generated_at: "2026-04-26T00:18:53Z"
model: gpt-5.4
provider: openai
source_hash: 388e4c015e6af99a9c9184539f4a5fa2bcc828f26a7470a338e8398e0cec1a5f
source_hash: ccd3616a944f83eda679e030a65f9febbe8c4f69100675ead8fa5d2c72142ce3
source_path: plugins/codex-harness.md
workflow: 15
---
Комплектний Plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через
Codex app-server замість вбудованого каркаса Pi.
Вбудований Plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через
app-server Codex замість вбудованого harness PI.
Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням
моделей, нативним відновленням потоку, нативною Compaction і виконанням через app-server.
OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделей, інструментами,
моделей, нативним відновленням тредів, нативним Compaction і виконанням app-server.
OpenClaw, як і раніше, керує чат-каналами, файлами сесій, вибором моделі, інструментами,
погодженнями, доставкою медіа та видимим дзеркалом транскрипту.
Якщо ви намагаєтеся зорієнтуватися, почніть із
[Середовища виконання агентів](/uk/concepts/agent-runtimes). Коротко:
`openai/gpt-5.5` — це посилання на модель, `codex` — це середовище виконання, а Telegram,
`openai/gpt-5.5` — це посилання на модель, `codex` — це runtime, а Telegram,
Discord, Slack або інший канал залишається поверхнею комунікації.
Цей самий Plugin також керує нативною поверхнею команд керування чатом `/codex`. Якщо
Plugin увімкнено і користувач просить прив’язати, відновити, спрямувати, зупинити або перевірити
треди Codex із чату, агенти мають надавати перевагу `/codex ...`, а не ACP. ACP залишається
явним запасним варіантом, коли користувач просить ACP/acpx або тестує адаптер Codex для ACP.
Нативні ходи Codex зберігають хуки Plugin OpenClaw як публічний шар сумісності.
Це внутрішньопроцесні хуки OpenClaw, а не командні хуки Codex `hooks.json`:
@ -37,95 +42,94 @@ Discord, Slack або інший канал залишається поверх
- `before_message_write` для дзеркальних записів транскрипту
- `agent_end`
Plugins також можуть реєструвати незалежне від середовища виконання проміжне ПЗ результатів інструментів, щоб переписувати
динамічні результати інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того,
як результат буде повернуто в Codex. Це окремо від публічного
хука Plugin `tool_result_persist`, який перетворює записи результатів інструментів
у транскрипті, що належить OpenClaw.
Plugins також можуть реєструвати нейтральне до runtime проміжне ПЗ результатів інструментів, щоб переписувати
результати динамічних інструментів OpenClaw після виконання інструмента OpenClaw і до того, як
результат буде повернуто в Codex. Це окремо від публічного
хука Plugin `tool_result_persist`, який перетворює записи результатів інструментів у транскрипті,
якими володіє OpenClaw.
Щодо семантики самих хуків Plugin дивіться [Хуки Plugin](/uk/plugins/hooks)
і [Поведінка захисту Plugin](/uk/tools/plugin).
Щоб дізнатися про саму семантику хуків Plugin, див. [Хуки Plugin](/uk/plugins/hooks)
і [Поведінка guard Plugin](/uk/tools/plugin).
Каркас вимкнений за замовчуванням. Нові конфігурації мають зберігати посилання на моделі OpenAI
у канонічному вигляді `openai/gpt-*` і явно примусово встановлювати
За замовчуванням harness вимкнено. Нові конфігурації мають зберігати посилання на моделі OpenAI
канонічними у вигляді `openai/gpt-*` і явно примусово задавати
`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли їм
потрібне нативне виконання через app-server. Застарілі посилання на моделі `codex/*` усе ще автоматично вибирають
каркас для сумісності, але застарілі префікси провайдерів, підкріплені середовищем виконання,
не показуються як звичайні варіанти моделі/провайдера.
потрібне нативне виконання app-server. Застарілі посилання на моделі `codex/*` усе ще автоматично вибирають
harness для сумісності, але застарілі префікси постачальників на базі runtime не відображаються
як звичайні варіанти моделі/постачальника.
## Виберіть правильний префікс моделі
Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли вам потрібна
авторизація Codex OAuth через Pi; використовуйте `openai/*`, коли вам потрібен прямий доступ до OpenAI API або
коли ви примусово використовуєте нативний каркас app-server Codex:
Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли вам потрібен
OAuth Codex через PI; використовуйте `openai/*`, коли вам потрібен прямий доступ до API OpenAI або
коли ви примусово вмикаєте нативний harness app-server Codex:
| Model ref | Runtime path | Use when |
| ----------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| `openai/gpt-5.4` | Провайдер OpenAI через конвеєр OpenClaw/PI | Вам потрібен поточний прямий доступ до OpenAI Platform API з `OPENAI_API_KEY`. |
| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/PI | Вам потрібна автентифікація підписки ChatGPT/Codex зі стандартним виконавцем PI. |
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Каркас app-server Codex | Вам потрібне нативне виконання через app-server Codex для вбудованого ходу агента. |
| Посилання на модель | Шлях runtime | Використовуйте, коли |
| ----------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- |
| `openai/gpt-5.4` | Постачальник OpenAI через інфраструктуру OpenClaw/PI | Вам потрібен поточний прямий доступ до API OpenAI Platform із `OPENAI_API_KEY`. |
| `openai-codex/gpt-5.5` | OAuth OpenAI Codex через OpenClaw/PI | Вам потрібна автентифікація підписки ChatGPT/Codex із виконавцем PI за замовчуванням. |
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Harness app-server Codex | Вам потрібне нативне виконання app-server Codex для вбудованого ходу агента. |
GPT-5.5 зараз у OpenClaw доступна лише через підписку/OAuth. Використовуйте
`openai-codex/gpt-5.5` для PI OAuth або `openai/gpt-5.5` з каркасом
GPT-5.5 наразі в OpenClaw доступний лише через підписку/OAuth. Використовуйте
`openai-codex/gpt-5.5` для OAuth через PI або `openai/gpt-5.5` із harness
app-server Codex. Прямий доступ через API-ключ для `openai/gpt-5.5` підтримуватиметься,
коли OpenAI увімкне GPT-5.5 у публічному API.
щойно OpenAI увімкне GPT-5.5 у публічному API.
Застарілі посилання `codex/gpt-*` залишаються прийнятними як псевдоніми сумісності. Міграція сумісності
doctor переписує застарілі основні посилання на середовище виконання у канонічні посилання на модель
і записує політику середовища виконання окремо, тоді як застарілі посилання лише для резервного режиму
залишаються без змін, бо середовище виконання налаштовується для всього контейнера агента.
Нові конфігурації PI Codex OAuth мають використовувати `openai-codex/gpt-*`; нові конфігурації нативного
каркаса app-server мають використовувати `openai/gpt-*` плюс
Застарілі посилання `codex/gpt-*` і далі приймаються як псевдоніми сумісності. Міграція сумісності
Doctor переписує застарілі основні посилання runtime на канонічні посилання на моделі
та окремо записує політику runtime, тоді як застарілі посилання лише для fallback залишаються без змін,
оскільки runtime налаштовується для всього контейнера агента.
Нові конфігурації OAuth Codex для PI мають використовувати `openai-codex/gpt-*`; нові конфігурації
нативного harness app-server мають використовувати `openai/gpt-*` плюс
`embeddedHarness.runtime: "codex"`.
`agents.defaults.imageModel` дотримується такого самого розділення префіксів. Використовуйте
`openai-codex/gpt-*`, коли розуміння зображень має проходити через шлях провайдера OpenAI
Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має виконуватися
`agents.defaults.imageModel` використовує той самий поділ префіксів. Використовуйте
`openai-codex/gpt-*`, коли розуміння зображень має проходити через шлях постачальника OAuth OpenAI
Codex. Використовуйте `codex/gpt-*`, коли розуміння зображень має проходити
через обмежений хід app-server Codex. Модель app-server Codex має
заявляти підтримку вхідних зображень; текстові моделі Codex завершуються помилкою до того, як
почнеться медіахід.
оголошувати підтримку вхідних зображень; текстові моделі Codex завершуються помилкою ще до початку
ходу з медіа.
Використовуйте `/status`, щоб підтвердити фактичний каркас для поточної сесії. Якщо вибір
виявився несподіваним, увімкніть журналювання налагодження для підсистеми `agents/harness`
і перегляньте структурований запис шлюзу `agent harness selected`. Він
містить ідентифікатор вибраного каркаса, причину вибору, політику runtime/fallback і,
Використовуйте `/status`, щоб підтвердити фактичний harness для поточної сесії. Якщо
вибір виглядає неочікуваним, увімкніть журналювання налагодження для підсистеми `agents/harness`
і перевірте структурований запис шлюзу `agent harness selected`. Він
містить ідентифікатор вибраного harness, причину вибору, політику runtime/fallback і,
у режимі `auto`, результат підтримки для кожного кандидата Plugin.
Вибір каркаса не є засобом керування живою сесією. Коли виконується вбудований хід,
OpenClaw записує ідентифікатор вибраного каркаса в цю сесію і продовжує використовувати його
для наступних ходів у межах того самого ідентифікатора сесії. Змінюйте конфігурацію `embeddedHarness` або
`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший каркас;
Вибір harness не є керуванням живою сесією. Коли виконується вбудований хід,
OpenClaw записує ідентифікатор вибраного harness у цю сесію і продовжує використовувати його
для наступних ходів із тим самим ідентифікатором сесії. Змінюйте конфігурацію `embeddedHarness` або
`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness;
використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної
розмови між PI і Codex. Це дає змогу уникнути повторного програвання одного транскрипту через
розмови між PI і Codex. Це дає змогу уникнути відтворення одного транскрипту через
дві несумісні нативні системи сесій.
Застарілі сесії, створені до закріплення каркасів, вважаються закріпленими за PI, щойно вони
Застарілі сесії, створені до фіксації harness, вважаються прив’язаними до PI, щойно вони
мають історію транскрипту. Використовуйте `/new` або `/reset`, щоб перевести таку розмову на
Codex після зміни конфігурації.
`/status` показує фактичне runtime моделі. Стандартний каркас PI відображається як
`Runtime: OpenClaw Pi Default`, а каркас app-server Codex відображається як
`/status` показує фактичний runtime моделі. Стандартний harness PI відображається як
`Runtime: OpenClaw Pi Default`, а harness app-server Codex — як
`Runtime: OpenAI Codex`.
## Вимоги
- OpenClaw із доступним комплектним Plugin `codex`.
- Codex app-server `0.125.0` або новіший. Комплектний Plugin за замовчуванням керує сумісним
двійковим файлом Codex app-server, тому локальні команди `codex` у `PATH`
не впливають на звичайний запуск каркаса.
- Автентифікація Codex, доступна процесу app-server.
- OpenClaw із доступним вбудованим Plugin `codex`.
- app-server Codex `0.125.0` або новіший. Вбудований Plugin за замовчуванням керує
сумісним двійковим файлом app-server Codex, тому локальні команди `codex` у `PATH`
не впливають на звичайний запуск harness.
- Автентифікація Codex, доступна для процесу app-server.
Plugin блокує старіші або неверсіоновані рукостискання app-server. Це утримує
Plugin блокує старіші або неверсіоновані handshake app-server. Це утримує
OpenClaw на поверхні протоколу, з якою його було протестовано.
Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також,
за потреби, з файлів Codex CLI, таких як `~/.codex/auth.json` і
`~/.codex/config.toml`. Використовуйте ті самі автентифікаційні матеріали, що й ваш локальний
Codex app-server.
Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також
необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і
`~/.codex/config.toml`. Використовуйте ті самі матеріали автентифікації, що й ваш локальний app-server Codex.
## Мінімальна конфігурація
Використовуйте `openai/gpt-5.5`, увімкніть комплектний Plugin і примусово виберіть каркас `codex`:
Використовуйте `openai/gpt-5.5`, увімкніть вбудований Plugin і примусово задайте harness `codex`:
```json5
{
@ -162,27 +166,27 @@ Codex app-server.
}
```
Застарілі конфігурації, які встановлюють `agents.defaults.model` або модель агента в
`codex/<model>`, усе ще автоматично вмикають комплектний Plugin `codex`. Нові конфігурації мають
надавати перевагу `openai/<model>` плюс явний запис `embeddedHarness`, наведений вище.
Застарілі конфігурації, які задають `agents.defaults.model` або модель агента як
`codex/<model>`, усе ще автоматично вмикають вбудований Plugin `codex`. Нові конфігурації мають
віддавати перевагу `openai/<model>` плюс явний запис `embeddedHarness`, наведений вище.
## Додайте Codex поруч з іншими моделями
## Додайте Codex поряд з іншими моделями
Не встановлюйте `runtime: "codex"` глобально, якщо той самий агент має вільно перемикатися
між Codex і моделями інших провайдерів. Примусове runtime застосовується до кожного
вбудованого ходу для цього агента або сесії. Якщо ви виберете модель Anthropic, коли
це runtime примусово встановлено, OpenClaw однаково спробує каркас Codex і завершиться помилкою,
а не тихо маршрутизує цей хід через PI.
Не задавайте `runtime: "codex"` глобально, якщо той самий агент має вільно перемикатися
між Codex і моделями постачальників, що не є Codex. Примусово заданий runtime застосовується до кожного
вбудованого ходу для цього агента або сесії. Якщо ви виберете модель Anthropic, поки
цей runtime примусово задано, OpenClaw все одно спробує harness Codex і завершиться помилкою в режимі fail closed,
а не непомітно спрямує цей хід через PI.
Натомість використовуйте одну з таких форм:
- Розмістіть Codex на окремому агенті з `embeddedHarness.runtime: "codex"`.
- Залиште для стандартного агента `runtime: "auto"` і резервний перехід на PI для звичайного змішаного
використання провайдерів.
- Використовуйте застарілі посилання `codex/*` лише для сумісності. Нові конфігурації мають надавати перевагу
- Розмістіть Codex в окремому агенті з `embeddedHarness.runtime: "codex"`.
- Залиште для агента за замовчуванням `runtime: "auto"` і fallback на PI для звичайного змішаного
використання постачальників.
- Використовуйте застарілі посилання `codex/*` лише для сумісності. Нові конфігурації мають віддавати перевагу
`openai/*` плюс явна політика runtime Codex.
Наприклад, ця конфігурація залишає стандартного агента на звичайному автоматичному виборі та
Наприклад, ця конфігурація залишає для агента за замовчуванням звичайний автоматичний вибір і
додає окремого агента Codex:
```json5
@ -222,16 +226,16 @@ Codex app-server.
За такої форми:
- Стандартний агент `main` використовує звичайний шлях провайдера та резервну сумісність PI.
- Агент `codex` використовує каркас app-server Codex.
- Якщо Codex відсутній або не підтримується для агента `codex`, хід завершується помилкою
- Агент `main` за замовчуванням використовує звичайний шлях постачальника і сумісний fallback на PI.
- Агент `codex` використовує harness app-server Codex.
- Якщо для агента `codex` Codex відсутній або не підтримується, хід завершиться помилкою
замість тихого використання PI.
## Розгортання лише з Codex
Примусово виберіть каркас Codex, коли потрібно довести, що кожен вбудований хід агента
використовує Codex. Явні runtime Plugin за замовчуванням не використовують резервний перехід на PI, тому
`fallback: "none"` необов’язковий, але часто корисний як документація:
Примусово задайте harness Codex, коли вам потрібно довести, що кожен вбудований хід агента
використовує Codex. Явні runtimes Plugin за замовчуванням не мають fallback на PI, тому
`fallback: "none"` не є обов’язковим, але часто корисний як документація:
```json5
{
@ -247,21 +251,21 @@ Codex app-server.
}
```
Перевизначення через змінну середовища:
Перевизначення через середовище:
```bash
OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run
```
За примусового використання Codex OpenClaw рано завершується помилкою, якщо Plugin Codex вимкнено,
Якщо Codex примусово задано, OpenClaw завершується помилкою на ранньому етапі, якщо Plugin Codex вимкнено,
app-server надто старий або app-server не може запуститися. Установлюйте
`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви свідомо хочете, щоб PI обробляв
випадки відсутності вибору каркаса.
`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви навмисно хочете, щоб PI обробляв
відсутність вибору harness.
## Codex для окремого агента
Ви можете зробити один агент лише для Codex, тоді як стандартний агент зберігатиме звичайний
автовибір:
Ви можете зробити один агент лише для Codex, тоді як агент за замовчуванням зберігатиме
звичайний автоматичний вибір:
```json5
{
@ -293,14 +297,14 @@ app-server надто старий або app-server не може запуст
```
Використовуйте звичайні команди сесії, щоб перемикати агентів і моделі. `/new` створює нову
сесію OpenClaw, а каркас Codex створює або відновлює свій бічний потік app-server
за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього потоку
і дає змогу наступному ходу знову визначити каркас із поточної конфігурації.
сесію OpenClaw, а harness Codex створює або відновлює свій sidecar-тред app-server
за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього треду
і дає змогу наступному ходу знову визначити harness на основі поточної конфігурації.
## Виявлення моделей
За замовчуванням Plugin Codex запитує app-server про доступні моделі. Якщо
виявлення завершується помилкою або перевищує час очікування, він використовує комплектний резервний каталог для:
виявлення не вдається або перевищує час очікування, він використовує вбудований запасний каталог для:
- GPT-5.5
- GPT-5.4 mini
@ -326,8 +330,8 @@ app-server надто старий або app-server не може запуст
}
```
Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалося зондування Codex і використовувався
лише резервний каталог:
Вимкніть виявлення, якщо хочете, щоб під час запуску система не зверталася до Codex і використовувала
запасний каталог:
```json5
{
@ -346,27 +350,27 @@ app-server надто старий або app-server не може запуст
}
```
## Підключення до app-server і політика
## З’єднання app-server і політика
За замовчуванням Plugin локально запускає керований OpenClaw двійковий файл Codex командою:
За замовчуванням Plugin локально запускає керований OpenClaw двійковий файл Codex з такою командою:
```bash
codex app-server --listen stdio://
```
Керований двійковий файл оголошено як залежність середовища виконання комплектного Plugin і підготовлено
разом з рештою залежностей Plugin `codex`. Це прив’язує версію app-server
до комплектного Plugin, а не до якогось окремого Codex CLI,
який випадково встановлено локально. Установлюйте `appServer.command` лише коли
свідомо хочете запускати інший виконуваний файл.
Керований двійковий файл оголошено як залежність runtime вбудованого Plugin і розміщено
разом з рештою залежностей Plugin `codex`. Це дає змогу прив’язати версію app-server
до вбудованого Plugin, а не до якоїсь окремої Codex CLI,
яка випадково встановлена локально. Установлюйте `appServer.command` лише тоді, коли
ви свідомо хочете запустити інший виконуваний файл.
За замовчуванням OpenClaw запускає локальні сесії каркаса Codex у режимі YOLO:
За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO:
`approvalPolicy: "never"`, `approvalsReviewer: "user"` і
`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, яка використовується
для автономних Heartbeat: Codex може використовувати shell та мережеві інструменти без
зупинки на нативних запитах на погодження, на які нікому відповісти.
`sandbox: "danger-full-access"`. Це модель довіреного локального оператора, яка використовується
для автономних Heartbeat: Codex може використовувати shell- і мережеві інструменти, не
зупиняючись на нативних запитах на погодження, на які нікому відповісти.
Щоб увімкнути погодження Codex, перевірені guardian, установіть `appServer.mode:
Щоб увімкнути погодження Codex із нативною перевіркою guardian, установіть `appServer.mode:
"guardian"`:
```json5
@ -387,21 +391,21 @@ codex app-server --listen stdio://
}
```
Режим Guardian використовує нативний шлях автоматичної перевірки погоджень Codex. Коли Codex просить
вийти з пісочниці, записувати поза робочим простором або додати дозволи, як-от мережевий
доступ, Codex спрямовує цей запит на погодження до нативного рецензента, а не до
людського запиту. Рецензент застосовує модель ризиків Codex і схвалює або відхиляє
конкретний запит. Використовуйте Guardian, коли вам потрібно більше захисних механізмів, ніж у режимі YOLO,
але при цьому потрібно, щоб агенти без нагляду могли просуватися далі.
Режим guardian використовує нативний шлях автоперевірки погоджень Codex. Коли Codex просить
вийти із sandbox, записати поза робочим простором або додати дозволи, як-от мережевий
доступ, Codex спрямовує цей запит на погодження до нативного перевіряльника, а не до
людського запиту. Перевіряльник застосовує модель ризиків Codex і схвалює або відхиляє
конкретний запит. Використовуйте Guardian, коли вам потрібні суворіші запобіжники, ніж у режимі YOLO,
але при цьому необхідно, щоб агенти без нагляду могли просуватися далі.
Попередньо налаштований варіант `guardian` розгортається в `approvalPolicy: "on-request"`,
Попереднє налаштування `guardian` розгортається в `approvalPolicy: "on-request"`,
`approvalsReviewer: "auto_review"` і `sandbox: "workspace-write"`.
Окремі поля політики, як і раніше, мають пріоритет над `mode`, тому розширені розгортання можуть поєднувати
цей preset з явними значеннями. Старіше значення рецензента `guardian_subagent`
усе ще приймається як псевдонім сумісності, але нові конфігурації мають використовувати
Окремі поля політики, як і раніше, перевизначають `mode`, тому розширені розгортання можуть поєднувати
це попереднє налаштування з явними варіантами. Старіше значення перевіряльника `guardian_subagent`
і далі приймається як псевдонім сумісності, але в нових конфігураціях слід використовувати
`auto_review`.
Для app-server, який уже запущено, використовуйте транспорт WebSocket:
Для вже запущеного app-server використовуйте транспорт WebSocket:
```json5
{
@ -425,20 +429,20 @@ codex app-server --listen stdio://
Підтримувані поля `appServer`:
| Field | Default | Meaning |
| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. |
| `command` | керований двійковий файл Codex | Виконуваний файл для транспорту stdio. Залиште без значення, щоб використовувати керований двійковий файл; установлюйте лише для явного перевизначення. |
| Поле | За замовчуванням | Значення |
| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. |
| `command` | керований двійковий файл Codex | Виконуваний файл для транспорту stdio. Не задавайте, щоб використовувати керований двійковий файл; задавайте лише для явного перевизначення. |
| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. |
| `url` | не встановлено | URL WebSocket app-server. |
| `authToken` | не встановлено | Bearer-токен для транспорту WebSocket. |
| `headers` | `{}` | Додаткові заголовки WebSocket. |
| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control-plane app-server. |
| `mode` | `"yolo"` | Preset для виконання YOLO або guardian-reviewed. |
| `approvalPolicy` | `"never"` | Нативна політика погоджень Codex, що надсилається під час старту/відновлення/ходу потоку. |
| `sandbox` | `"danger-full-access"` | Нативний режим пісочниці Codex, що надсилається під час старту/відновлення потоку. |
| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex перевіряти нативні запити на погодження. `guardian_subagent` лишається застарілим псевдонімом. |
| `serviceTier` | не встановлено | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. |
| `url` | не задано | URL app-server WebSocket. |
| `authToken` | не задано | Bearer-токен для транспорту WebSocket. |
| `headers` | `{}` | Додаткові заголовки WebSocket. |
| `requestTimeoutMs` | `60000` | Тайм-аут для викликів площини керування app-server. |
| `mode` | `"yolo"` | Попереднє налаштування для виконання YOLO або з перевіркою guardian. |
| `approvalPolicy` | `"never"` | Нативна політика погодження Codex, яка надсилається під час запуску/відновлення треду/ходу. |
| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, який надсилається під час запуску/відновлення треду. |
| `approvalsReviewer` | `"user"` | Використовуйте `"auto_review"`, щоб дозволити Codex перевіряти нативні запити на погодження. `guardian_subagent` залишається застарілим псевдонімом. |
| `serviceTier` | не задано | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. |
Перевизначення через змінні середовища, як і раніше, доступні для локального тестування:
@ -449,13 +453,13 @@ codex app-server --listen stdio://
- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
`OPENCLAW_CODEX_APP_SERVER_BIN` обходить керований двійковий файл, коли
`appServer.command` не встановлено.
`appServer.command` не задано.
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було видалено. Натомість використовуйте
`plugins.entries.codex.config.appServer.mode: "guardian"` або
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Конфігурація
бажаніша для відтворюваних розгортань, оскільки зберігає поведінку Plugin у тому
самому перевіреному файлі, що й решту налаштувань каркаса Codex.
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Натомість використовуйте
`plugins.entries.codex.config.appServer.mode: "guardian"`, або
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Для
відтворюваних розгортань перевага надається конфігурації, оскільки вона зберігає поведінку Plugin
у тому самому перевіреному файлі, що й решта налаштувань harness Codex.
## Поширені рецепти
@ -473,7 +477,7 @@ codex app-server --listen stdio://
}
```
Перевірка каркаса лише з Codex:
Перевірка harness лише з Codex:
```json5
{
@ -495,7 +499,7 @@ codex app-server --listen stdio://
}
```
Погодження Codex, перевірені Guardian:
Погодження Codex із перевіркою guardian:
```json5
{
@ -540,66 +544,67 @@ codex app-server --listen stdio://
}
```
Перемикання моделей залишається під контролем OpenClaw. Коли сесію OpenClaw приєднано
до наявного потоку Codex, наступний хід знову надсилає в
app-server поточні вибрані модель OpenAI, провайдера, політику погоджень, пісочницю та рівень сервісу.
Перемикання моделей залишається під контролем OpenClaw. Коли сесію OpenClaw прив’язано
до наявного треду Codex, наступний хід знову надсилає до
app-server поточну вибрану модель OpenAI, постачальника, політику погодження, sandbox і рівень сервісу.
Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає
прив’язку до потоку, але просить Codex продовжити з новою вибраною моделлю.
прив’язку до треду, але просить Codex продовжити з новою вибраною моделлю.
## Команда Codex
Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона є
Вбудований Plugin реєструє `/codex` як авторизовану slash-команду. Вона є
загальною і працює в будь-якому каналі, який підтримує текстові команди OpenClaw.
Поширені форми:
- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та skills.
- `/codex models` перелічує моделі живого Codex app-server.
- `/codex threads [filter]` перелічує нещодавні потоки Codex.
- `/codex resume <thread-id>` приєднує поточну сесію OpenClaw до наявного потоку Codex.
- `/codex compact` просить Codex app-server виконати Compaction приєднаного потоку.
- `/codex review` запускає нативну перевірку Codex для приєднаного потоку.
- `/codex status` показує поточне підключення до app-server, моделі, обліковий запис, ліміти швидкості, сервери MCP і skills.
- `/codex models` перелічує поточні моделі app-server Codex.
- `/codex threads [filter]` перелічує недавні треди Codex.
- `/codex resume <thread-id>` прив’язує поточну сесію OpenClaw до наявного треду Codex.
- `/codex compact` просить app-server Codex виконати compaction прив’язаного треду.
- `/codex review` запускає нативну перевірку Codex для прив’язаного треду.
- `/codex account` показує стан облікового запису та лімітів швидкості.
- `/codex mcp` перелічує стан MCP-серверів Codex app-server.
- `/codex skills` перелічує skills Codex app-server.
- `/codex mcp` перелічує стан серверів MCP app-server Codex.
- `/codex skills` перелічує skills app-server Codex.
`/codex resume` записує той самий файл бічної прив’язки, який каркас використовує для
звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає
`/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для
звичайних ходів. У наступному повідомленні OpenClaw відновлює цей тред Codex, передає
поточну вибрану модель OpenClaw в app-server і зберігає
увімкнену розширену історію.
Поверхня команд вимагає Codex app-server `0.125.0` або новішої версії. Окремі
методи керування позначаються як `unsupported by this Codex app-server`, якщо
майбутній або нестандартний app-server не надає цей метод JSON-RPC.
Поверхня команд потребує app-server Codex `0.125.0` або новішої версії. Про окремі
методи керування повідомляється як `unsupported by this Codex app-server`, якщо
майбутній або спеціальний app-server не надає цей метод JSON-RPC.
## Межі хуків
Каркас Codex має три шари хуків:
Harness Codex має три шари хуків:
| Layer | Owner | Purpose |
| Шар | Власник | Призначення |
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- |
| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між каркасами PI і Codex. |
| Проміжне ПЗ розширення Codex app-server | Комплектні Plugins OpenClaw | Поведінка адаптера навколо динамічних інструментів OpenClaw для кожного ходу. |
| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і нативна політика інструментів із конфігурації Codex. |
| Хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness PI і Codex. |
| Проміжне ПЗ розширення app-server Codex | Вбудовані Plugins OpenClaw | Поведінка адаптера для кожного ходу навколо динамічних інструментів OpenClaw. |
| Нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і політика нативних інструментів із конфігурації Codex. |
OpenClaw не використовує файли `hooks.json` Codex на рівні проєкту або глобальному рівні для маршрутизації
поведінки Plugin OpenClaw. Для підтримуваного нативного мосту інструментів і дозволів
OpenClaw впроваджує конфігурацію Codex для кожного потоку для `PreToolUse`, `PostToolUse` і
OpenClaw не використовує файли `hooks.json` проєкту або глобальні файли Codex, щоб спрямовувати
поведінку Plugin OpenClaw. Для підтримуваного мосту нативних інструментів і дозволів
OpenClaw впроваджує конфігурацію Codex для кожного треду для `PreToolUse`, `PostToolUse` і
`PermissionRequest`. Інші хуки Codex, такі як `SessionStart`,
`UserPromptSubmit` і `Stop`, залишаються елементами керування рівня Codex; вони не відкриті
як хуки Plugin OpenClaw у контракті v1.
`UserPromptSubmit` і `Stop`, залишаються елементами керування на рівні Codex; у контракті v1 вони
не надаються як хуки Plugin OpenClaw.
Для динамічних інструментів OpenClaw OpenClaw виконує інструмент після того, як Codex запитує
виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою він володіє, у
адаптері каркаса. Для нативних інструментів Codex Codex володіє канонічним записом інструмента.
OpenClaw може дзеркалити вибрані події, але не може переписувати нативний потік Codex,
якщо Codex не надає цю операцію через app-server або зворотні виклики нативних хуків.
виклик, тому OpenClaw запускає поведінку Plugin і проміжного ПЗ, якою він володіє в
адаптері harness. Для нативних інструментів Codex Codex володіє канонічним записом інструмента.
OpenClaw може дзеркалити вибрані події, але не може переписувати нативний
тред Codex, якщо Codex не надає цю операцію через app-server або нативні зворотні виклики
хуків.
Проєкції Compaction і життєвого циклу LLM надходять із сповіщень Codex app-server
Проєкції Compaction і життєвого циклу LLM надходять зі сповіщень app-server Codex
і стану адаптера OpenClaw, а не з команд нативних хуків Codex.
Події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і
`llm_output` є спостереженнями на рівні адаптера, а не побайтними знімками
внутрішнього запиту Codex або корисних даних Compaction.
`llm_output` — це спостереження на рівні адаптера, а не побайтні захоплення
внутрішніх запитів Codex або payload Compaction.
Нативні сповіщення app-server Codex `hook/started` і `hook/completed`
проєктуються як події агента `codex_app_server.hook` для траєкторії та налагодження.
@ -607,119 +612,118 @@ OpenClaw може дзеркалити вибрані події, але не м
## Контракт підтримки V1
Режим Codex — це не PI з іншим викликом моделі під капотом. Codex контролює більшу частину
Режим Codex — це не PI з іншим викликом моделі під ним. Codex володіє більшою частиною
нативного циклу моделі, а OpenClaw адаптує свої поверхні Plugin і сесій
навколо цієї межі.
Підтримується в runtime Codex v1:
| Surface | Support | Why |
| --------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Цикл моделі OpenAI через Codex | Підтримується | Codex app-server керує ходом OpenAI, нативним відновленням потоку та нативним продовженням інструментів. |
| Маршрутизація та доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза runtime моделі. |
| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконати ці інструменти, тому OpenClaw залишається в шляху виконання. |
| Plugins prompt і контексту | Підтримується | OpenClaw будує накладки prompt і проєктує контекст у хід Codex перед запуском або відновленням потоку. |
| Життєвий цикл механізму контексту | Підтримується | Збирання, ingest або обслуговування після ходу, а також координація Compaction механізму контексту виконуються для ходів Codex. |
| Хуки динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів інструментів виконуються навколо динамічних інструментів, що належать OpenClaw. |
| Хуки життєвого циклу | Підтримуються як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` спрацьовують із коректними payload у режимі Codex. |
| Нативні shell, patch і MCP блокують або спостерігають | Підтримується через ретрансляцію нативних хуків | Codex `PreToolUse` і `PostToolUse` ретранслюються для зафіксованих поверхонь нативних інструментів, зокрема payload MCP у Codex app-server `0.125.0` або новішому. Блокування підтримується; переписування аргументів — ні. |
| Нативна політика дозволів | Підтримується через ретрансляцію нативних хуків | Codex `PermissionRequest` може бути маршрутизований через політику OpenClaw там, де runtime це підтримує. Якщо OpenClaw не повертає рішення, Codex продовжує через свій звичайний шлях погодження guardian або користувача. |
| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення, які отримує від app-server. |
| Поверхня | Підтримка | Чому |
| --------------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Цикл моделі OpenAI через Codex | Підтримується | app-server Codex керує ходом OpenAI, нативним відновленням треду та нативним продовженням інструментів. |
| Маршрутизація та доставка каналів OpenClaw | Підтримується | Telegram, Discord, Slack, WhatsApp, iMessage та інші канали залишаються поза runtime моделі. |
| Динамічні інструменти OpenClaw | Підтримується | Codex просить OpenClaw виконати ці інструменти, тому OpenClaw залишається в шляху виконання. |
| Plugins промптів і контексту | Підтримується | OpenClaw будує накладки промптів і проєктує контекст у хід Codex перед запуском або відновленням треду. |
| Життєвий цикл рушія контексту | Підтримується | Для ходів Codex виконуються assemble, ingest або підтримка after-turn, а також координація Compaction рушія контексту. |
| Хуки динамічних інструментів | Підтримується | `before_tool_call`, `after_tool_call` і middleware результатів інструментів працюють навколо динамічних інструментів, якими володіє OpenClaw. |
| Хуки життєвого циклу | Підтримуються як спостереження адаптера | `llm_input`, `llm_output`, `agent_end`, `before_compaction` і `after_compaction` спрацьовують із чесними payload для режиму Codex. |
| Нативні shell, patch і блокування або спостереження MCP | Підтримується через ретрансляцію нативних хуків | `PreToolUse` і `PostToolUse` Codex ретранслюються для зафіксованих поверхонь нативних інструментів, включно з payload MCP в app-server Codex `0.125.0` або новішому. Блокування підтримується; переписування аргументів — ні. |
| Нативна політика дозволів | Підтримується через ретрансляцію нативних хуків | `PermissionRequest` Codex може бути спрямовано через політику OpenClaw там, де runtime це надає. Якщо OpenClaw не повертає рішення, Codex продовжує через свій звичайний шлях погодження guardian або користувача. |
| Захоплення траєкторії app-server | Підтримується | OpenClaw записує запит, який він надіслав до app-server, і сповіщення, які він від нього отримує. |
Не підтримується в runtime Codex v1:
| Surface | Межа v1 | Майбутній шлях |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Мутація аргументів нативного інструмента | Нативні pre-tool хуки Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потрібна підтримка хуків/схем Codex для заміни вхідних даних інструмента. |
| Редагована нативна історія транскрипту Codex | Codex володіє канонічною нативною історією потоку. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не повинен змінювати непідтримувані внутрішні структури. | Додати явні API Codex app-server, якщо потрібна нативна хірургія потоку. |
| `tool_result_persist` для записів нативних результатів інструментів Codex | Цей хук перетворює записи транскрипту, що належать OpenClaw, а не записи нативних інструментів Codex. | Можна було б дзеркалити перетворені записи, але канонічне переписування потребує підтримки Codex. |
| Розширені метадані нативної Compaction | OpenClaw спостерігає початок і завершення Compaction, але не отримує стабільного списку збережених/відкинутих записів, різниці токенів або payload підсумку. | Потрібні багатші події Compaction від Codex. |
| Втручання в Compaction | Поточні хуки Compaction OpenClaw у режимі Codex працюють на рівні сповіщень. | Додати pre/post хуки Compaction Codex, якщо Plugins мають блокувати або переписувати нативну Compaction. |
| Керування зупинкою або фінальною відповіддю | Codex має нативні stop hooks, але OpenClaw не відкриває керування фінальною відповіддю як контракт Plugin v1. | Майбутній opt-in примітив із захистом циклу й тайм-аутів. |
| Побайтне захоплення запиту до API моделі | OpenClaw може захоплювати запити й сповіщення app-server, але ядро Codex внутрішньо будує фінальний запит до OpenAI API. | Потрібна подія трасування запиту моделі Codex або API налагодження. |
| Поверхня | Межа v1 | Майбутній шлях |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Зміна аргументів нативних інструментів | Нативні pre-tool-хуки Codex можуть блокувати, але OpenClaw не переписує аргументи нативних інструментів Codex. | Потребує підтримки Codex hook/schema для заміни вхідних даних інструмента. |
| Редагована нативна історія транскрипту Codex | Codex володіє канонічною нативною історією треду. OpenClaw володіє дзеркалом і може проєктувати майбутній контекст, але не має змінювати непідтримувані внутрішні механізми. | Додати явні API app-server Codex, якщо потрібне втручання в нативний тред. |
| `tool_result_persist` для записів нативних інструментів Codex | Цей хук перетворює записи транскрипту, якими володіє OpenClaw, а не записи нативних інструментів Codex. | Можна було б дзеркалити перетворені записи, але канонічне переписування потребує підтримки Codex. |
| Розширені метадані нативного Compaction | OpenClaw спостерігає початок і завершення compaction, але не отримує стабільного списку збереженого/відкинутого, дельти токенів або payload підсумку. | Потребує багатших подій compaction Codex. |
| Втручання в Compaction | Поточні хуки compaction OpenClaw у режимі Codex мають рівень сповіщень. | Додати pre/post-хуки compaction Codex, якщо Plugins потребують заборони або переписування нативного compaction. |
| Зупинка або контроль фінальної відповіді | Codex має нативні stop-хуки, але OpenClaw не надає контроль фінальної відповіді як контракт Plugin v1. | Майбутній примітив opt-in із захистом циклу та тайм-аутів. |
| Побайтне захоплення запитів API моделі | OpenClaw може захоплювати запити app-server і сповіщення, але ядро Codex внутрішньо будує фінальний запит API OpenAI. | Потребує події трасування запиту моделі Codex або API налагодження. |
## Інструменти, медіа та Compaction
Каркас Codex змінює лише низькорівневий виконавець вбудованого агента.
Harness Codex змінює лише низькорівневий виконавець вбудованого агента.
OpenClaw, як і раніше, будує список інструментів і отримує результати динамічних інструментів від
каркаса. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів повідомлень
продовжують проходити через звичайний шлях доставки OpenClaw.
harness. Текст, зображення, відео, музика, TTS, погодження і виведення інструментів повідомлень
і далі проходять через звичайний шлях доставки OpenClaw.
Ретрансляція нативних хуків навмисно є загальною, але контракт підтримки v1
обмежений шляхами нативних інструментів і дозволів Codex, які тестує OpenClaw. У
Ретрансляція нативних хуків навмисно є узагальненою, але контракт підтримки v1 обмежений
нативними шляхами інструментів і дозволів Codex, які тестує OpenClaw. У
runtime Codex це включає payload `PreToolUse`,
`PostToolUse` і `PermissionRequest` для shell, patch і MCP. Не припускайте, що кожна майбутня
подія хуків Codex є поверхнею Plugin OpenClaw, доки контракт runtime прямо
її не назве.
подія хуків Codex є поверхнею Plugin OpenClaw, доки це не буде названо в контракті runtime.
Для `PermissionRequest` OpenClaw повертає явні рішення дозволити або заборонити
лише тоді, коли це вирішує політика. Результат без рішення — це не дозвіл. Codex трактує це як
Для `PermissionRequest` OpenClaw повертає явні рішення allow або deny
лише тоді, коли політика приймає рішення. Результат без рішення не є allow. Codex сприймає це як
відсутність рішення хука і переходить до власного шляху погодження guardian або користувача.
Запити на погодження інструментів MCP Codex маршрутизуються через потік погодження Plugin
Запити погодження інструментів MCP Codex спрямовуються через потік погодження Plugin
OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як
`"mcp_tool_call"`. Запити Codex `request_user_input` надсилаються назад до
початкового чату, а наступне повідомлення в черзі відповідає на цей нативний
запит сервера замість того, щоб використовуватися як додатковий контекст. Інші запити MCP усе ще завершуються помилкою без резервного варіанта.
`"mcp_tool_call"`. Підказки `request_user_input` Codex надсилаються назад у
початковий чат, а наступне поставлене в чергу follow-up-повідомлення відповідає на цей нативний
запит сервера, а не спрямовується як додатковий контекст. Інші запити elicitation MCP
і далі завершуються помилкою в режимі fail closed.
Коли вибрана модель використовує каркас Codex, нативна Compaction потоку делегується
Codex app-server. OpenClaw зберігає дзеркало транскрипту для історії каналу,
пошуку, `/new`, `/reset` і майбутнього перемикання моделі або каркаса. Дзеркало
містить prompt користувача, фінальний текст помічника та полегшені записи міркувань
або плану Codex, коли app-server їх надсилає. Наразі OpenClaw лише
записує сигнали початку та завершення нативної Compaction. Він ще не показує
людинозрозумілий підсумок Compaction або аудитований список того, які записи Codex
зберіг після Compaction.
Коли вибрана модель використовує harness Codex, нативний Compaction треду делегується
app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу,
пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало
включає промпт користувача, фінальний текст асистента і полегшені записи міркувань або плану Codex,
коли їх генерує app-server. Наразі OpenClaw лише записує сигнали початку
і завершення нативного compaction. Він ще не надає зручного для людини
підсумку compaction або аудитованого списку того, які записи Codex зберіг після compaction.
Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі не
переписує записи нативних результатів інструментів Codex. Він застосовується лише тоді, коли
OpenClaw записує результат інструмента в транскрипт сесії, що належить OpenClaw.
Оскільки Codex володіє канонічним нативним тредом, `tool_result_persist` наразі не
переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, коли
OpenClaw записує результат інструмента в транскрипт сесії, яким володіє OpenClaw.
Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і
розуміння медіа, як і раніше, використовує відповідні налаштування провайдера/моделі, такі як
Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і розуміння медіа
і далі використовують відповідні налаштування постачальника/моделі, як-от
`agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і
`messages.tts`.
## Усунення несправностей
**Codex не з’являється як звичайний провайдер `/model`:** це очікувана поведінка для
нових конфігурацій. Виберіть модель `openai/gpt-*` з
**Codex не відображається як звичайний постачальник `/model`:** це очікувано для
нових конфігурацій. Виберіть модель `openai/gpt-*` із
`embeddedHarness.runtime: "codex"` (або застарілим посиланням `codex/*`), увімкніть
`plugins.entries.codex.enabled` і перевірте, чи не виключає `plugins.allow`
`plugins.entries.codex.enabled` і перевірте, чи `plugins.allow` не виключає
`codex`.
**OpenClaw використовує PI замість Codex:** `runtime: "auto"` усе ще може використовувати PI як
бекенд сумісності, коли жоден каркас Codex не заявляє про цей запуск. Установіть
`embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування. Тепер
примусове runtime Codex завершується помилкою замість переходу до PI, якщо ви
явно не встановите `embeddedHarness.fallback: "pi"`. Щойно буде вибрано Codex app-server,
його помилки відображатимуться безпосередньо без додаткової конфігурації fallback.
**OpenClaw використовує PI замість Codex:** `runtime: "auto"` все ще може використовувати PI як
бекенд сумісності, коли жоден harness Codex не заявляє про цей запуск. Установіть
`embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування. Примусово
заданий runtime Codex тепер завершується помилкою замість повернення до PI, якщо ви
явно не встановите `embeddedHarness.fallback: "pi"`. Щойно буде
вибрано app-server Codex, його збої відображатимуться безпосередньо без додаткової конфігурації fallback.
**app-server відхиляється:** оновіть Codex, щоб рукостискання app-server
повідомляло версію `0.125.0` або новішу. Пререлізи тієї самої версії або версії
із суфіксами збірки, такі як `0.125.0-alpha.2` або `0.125.0+custom`, відхиляються, оскільки
**app-server відхиляється:** оновіть Codex, щоб handshake app-server
повідомляв версію `0.125.0` або новішу. Пререлізи тієї самої версії або версії з суфіксом збірки,
такі як `0.125.0-alpha.2` або `0.125.0+custom`, відхиляються, оскільки
стабільний поріг протоколу `0.125.0` — це те, що тестує OpenClaw.
**Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs`
або вимкніть виявлення.
**Транспорт WebSocket одразу завершується помилкою:** перевірте `appServer.url`, `authToken`
і те, що віддалений app-server використовує ту саму версію протоколу Codex app-server.
і те, що віддалений app-server підтримує ту саму версію протоколу app-server Codex.
**Модель не Codex використовує PI:** це очікувано, якщо ви не примусово встановили
**Модель не Codex використовує PI:** це очікувано, якщо ви не примусово задали
`embeddedHarness.runtime: "codex"` для цього агента або не вибрали застаріле
посилання `codex/*`. Звичайні `openai/gpt-*` та інші посилання провайдерів залишаються на своєму звичайному
шляху провайдера в режимі `auto`. Якщо ви примусово встановите `runtime: "codex"`, кожен вбудований
посилання `codex/*`. Звичайні посилання `openai/gpt-*` та інші посилання постачальників залишаються на
своєму нормальному шляху постачальника в режимі `auto`. Якщо ви примусово задаєте `runtime: "codex"`, кожен вбудований
хід для цього агента має бути моделлю OpenAI, яку підтримує Codex.
## Пов’язане
- [Plugins каркаса агента](/uk/plugins/sdk-agent-harness)
- [Plugins harness агента](/uk/plugins/sdk-agent-harness)
- [Середовища виконання агентів](/uk/concepts/agent-runtimes)
- [Провайдери моделей](/uk/concepts/model-providers)
- [Провайдер OpenAI](/uk/providers/openai)
- [Status](/uk/cli/status)
- [Постачальники моделей](/uk/concepts/model-providers)
- [Постачальник OpenAI](/uk/providers/openai)
- [Статус](/uk/cli/status)
- [Хуки Plugin](/uk/plugins/hooks)
- [Довідник конфігурації](/uk/gateway/configuration-reference)
- [Довідник із конфігурації](/uk/gateway/configuration-reference)
- [Тестування](/uk/help/testing-live#live-codex-app-server-harness-smoke)

104
docs/uk/plugins/community.md
View File

@ -1,40 +1,40 @@
---
read_when:
- Ви хочете знайти сторонні Plugins OpenClaw
- Ви хочете опублікувати або додати до списку власний Plugin
summary: 'Plugins OpenClaw, які підтримує спільнота: перегляд, встановлення та надсилання власних Plugin'
title: Plugins спільноти
- Ви хочете знайти сторонні plugin для OpenClaw
- Ви хочете опублікувати або додати до списку власний plugin
summary: 'Plugin для OpenClaw, що підтримуються спільнотою: перегляд, встановлення та надсилання власних'
title: Plugin спільноти
x-i18n:
generated_at: "2026-04-23T21:02:23Z"
generated_at: "2026-04-26T00:18:50Z"
model: gpt-5.4
provider: openai
source_hash: acce221249df8ceea65436902a33f4906503a1c6f57db3b0ad2058d64c1fb0f7
source_hash: 3af2f0be5e5e75fe26a58576e6f44bce52a1ff8d597f86cafd8fb893f6c6b8f4
source_path: plugins/community.md
workflow: 15
---
Plugins спільноти — це сторонні пакети, які розширюють OpenClaw новими
Plugin спільноти — це сторонні пакунки, які розширюють OpenClaw новими
каналами, інструментами, провайдерами або іншими можливостями. Їх створює та підтримує
спільнота, вони публікуються в [ClawHub](/uk/tools/clawhub) або npm і
встановлюються однією командою.
можуть бути встановлені однією командою.
ClawHub — це канонічна поверхня для пошуку Plugin спільноти. Не відкривайте
PR лише до документації тільки для того, щоб додати тут свій Plugin для видимості; натомість опублікуйте його в
ClawHub — це канонічна поверхня виявлення для Plugin спільноти. Не відкривайте
PR лише до документації, щоб просто додати тут свій Plugin для кращого виявлення; натомість опублікуйте його в
ClawHub.
```bash
openclaw plugins install <package-name>
```
OpenClaw спочатку перевіряє ClawHub, а потім автоматично повертається до npm.
OpenClaw спочатку перевіряє ClawHub, а потім автоматично переходить до npm.
## Plugins у списку
## Перелічені Plugin
### Apify
Збирайте дані з будь-якого вебсайту за допомогою понад 20 000 готових scraper. Дозвольте своєму агенту
Збирайте дані з будь-якого вебсайту за допомогою понад 20 000 готових скрейперів. Дозвольте своєму агенту
витягувати дані з Instagram, Facebook, TikTok, YouTube, Google Maps, Google
Search, e-commerce сайтів та інших джерел — просто за запитом.
Search, сайтів електронної комерції тощо — просто за запитом.
- **npm:** `@apify/apify-openclaw-plugin`
- **repo:** [github.com/apify/apify-openclaw-plugin](https://github.com/apify/apify-openclaw-plugin)
@ -45,9 +45,9 @@ openclaw plugins install @apify/apify-openclaw-plugin
### Codex App Server Bridge
Незалежний міст OpenClaw для conversations Codex App Server. Прив’яжіть чат до
thread Codex, спілкуйтеся з ним звичайним текстом і керуйте ним за допомогою нативних для чату
команд для resume, planning, review, вибору моделі, Compaction тощо.
Незалежний міст OpenClaw для розмов Codex App Server. Прив’яжіть чат до
потоку Codex, спілкуйтеся з ним простим текстом і керуйте ним за допомогою природних для чату
команд для відновлення, планування, перевірки, вибору моделі, Compaction тощо.
- **npm:** `openclaw-codex-app-server`
- **repo:** [github.com/pwrdrvr/openclaw-codex-app-server](https://github.com/pwrdrvr/openclaw-codex-app-server)
@ -58,8 +58,8 @@ openclaw plugins install openclaw-codex-app-server
### DingTalk
Інтеграція корпоративного робота з використанням режиму Stream. Підтримує текст,
зображення й файлові повідомлення через будь-який клієнт DingTalk.
Інтеграція корпоративного робота з використанням режиму Stream. Підтримує текст, зображення та
файлові повідомлення через будь-який клієнт DingTalk.
- **npm:** `@largezhou/ddingtalk`
- **repo:** [github.com/largezhou/openclaw-dingtalk](https://github.com/largezhou/openclaw-dingtalk)
@ -70,9 +70,9 @@ openclaw plugins install @largezhou/ddingtalk
### Lossless Claw (LCM)
Plugin Lossless Context Management для OpenClaw. DAG-базоване
узагальнення розмов з інкрементальним Compaction — зберігає повну точність контексту
при зменшенні використання токенів.
Plugin Lossless Context Management для OpenClaw. Підсумовування розмов
на основі DAG з інкрементною Compaction — зберігає повну цілісність контексту
і водночас зменшує використання токенів.
- **npm:** `@martian-engineering/lossless-claw`
- **repo:** [github.com/Martian-Engineering/lossless-claw](https://github.com/Martian-Engineering/lossless-claw)
@ -83,7 +83,7 @@ openclaw plugins install @martian-engineering/lossless-claw
### Opik
Офіційний Plugin, який експортує трасування агента в Opik. Відстежуйте поведінку агента,
Офіційний Plugin, який експортує трасування агентів до Opik. Відстежуйте поведінку агентів,
вартість, токени, помилки тощо.
- **npm:** `@opik/opik-openclaw`
@ -95,9 +95,9 @@ openclaw plugins install @opik/opik-openclaw
### Prometheus Avatar
Додайте своєму агенту OpenClaw аватар Live2D з синхронізацією губ у реальному часі,
виразами емоцій і перетворенням тексту на мовлення. Містить інструменти для авторів для AI-генерації ресурсів
і розгортання в один клік на Prometheus Marketplace. Наразі в alpha.
Додайте своєму агенту OpenClaw Live2D-аватар із синхронізацією губ у реальному часі, емоційними
виразами та перетворенням тексту на мовлення. Містить інструменти для авторів для генерації AI-активів
і розгортання в один клік у Prometheus Marketplace. Наразі в альфа-версії.
- **npm:** `@prometheusavatar/openclaw-plugin`
- **repo:** [github.com/myths-labs/prometheus-avatar](https://github.com/myths-labs/prometheus-avatar)
@ -109,8 +109,12 @@ openclaw plugins install @prometheusavatar/openclaw-plugin
### QQbot
Підключіть OpenClaw до QQ через QQ Bot API. Підтримує приватні чати, групові
згадки, повідомлення в каналах і розширені медіа, включно з голосом, зображеннями, відео
та файлами.
згадки, повідомлення в каналах і мультимедіа, зокрема голосові повідомлення, зображення, відео
та файли.
Поточні релізи OpenClaw постачаються з QQ Bot у комплекті. Використовуйте вбудоване налаштування з
[QQ Bot](/uk/channels/qqbot) для звичайних встановлень; встановлюйте цей зовнішній Plugin лише
тоді, коли вам навмисно потрібен окремий пакунок, який підтримує Tencent.
- **npm:** `@tencent-connect/openclaw-qqbot`
- **repo:** [github.com/tencent-connect/openclaw-qqbot](https://github.com/tencent-connect/openclaw-qqbot)
@ -121,10 +125,10 @@ openclaw plugins install @tencent-connect/openclaw-qqbot
### wecom
Plugin каналу WeCom для OpenClaw від команди Tencent WeCom. Працює на базі
постійних WebSocket-з’єднань WeCom Bot і підтримує direct messages та групові
чати, потокові відповіді, проактивні повідомлення, обробку зображень/файлів, форматування
Markdown, вбудоване керування доступом і Skills для документів/зустрічей/повідомлень.
Plugin каналу WeCom для OpenClaw від команди Tencent WeCom. Працює на основі
постійних WebSocket-з’єднань WeCom Bot, підтримує прямі повідомлення й групові
чати, потокові відповіді, проактивні повідомлення, обробку зображень/файлів, форматування Markdown,
вбудований контроль доступу та Skills для документів/зустрічей/повідомлень.
- **npm:** `@wecom/wecom-openclaw-plugin`
- **repo:** [github.com/WecomTeam/wecom-openclaw-plugin](https://github.com/WecomTeam/wecom-openclaw-plugin)
@ -135,28 +139,28 @@ openclaw plugins install @wecom/wecom-openclaw-plugin
## Надішліть свій Plugin
Ми вітаємо Plugins спільноти, які є корисними, задокументованими й безпечними в експлуатації.
Ми вітаємо Plugin спільноти, які є корисними, документованими та безпечними в експлуатації.
<Steps>
<Step title="Опублікуйте в ClawHub або npm">
Ваш Plugin має встановлюватися через `openclaw plugins install \<package-name\>`.
Публікуйте в [ClawHub](/uk/tools/clawhub) (бажано) або npm.
Повний посібник див. у [Building Plugins](/uk/plugins/building-plugins).
Опублікуйте його в [ClawHub](/uk/tools/clawhub) (бажано) або npm.
Повний посібник дивіться в [Створення Plugin](/uk/plugins/building-plugins).
</Step>
<Step title="Розмістіть на GitHub">
Вихідний код має бути в публічному репозиторії з документацією щодо налаштування та
issue tracker.
Вихідний код має бути в публічному репозиторії з документацією з налаштування та
трекером проблем.
</Step>
<Step title="Використовуйте PR до документації лише для змін у вихідній документації">
Вам не потрібен PR до документації лише для того, щоб зробити свій Plugin доступним для пошуку. Опублікуйте його
Вам не потрібен PR до документації лише для того, щоб ваш Plugin можна було знайти. Натомість опублікуйте його
в ClawHub.
Відкривайте PR до документації лише тоді, коли вихідна документація OpenClaw справді потребує
зміни вмісту, наприклад для виправлення інструкцій зі встановлення або додавання міжрепозиторної
Відкривайте PR до документації лише тоді, коли у вихідній документації OpenClaw потрібна реальна
зміна вмісту, наприклад виправлення інструкцій зі встановлення або додавання міжрепозиторної
документації, яка має належати до основного набору документації.
</Step>
@ -164,17 +168,17 @@ openclaw plugins install @wecom/wecom-openclaw-plugin
## Планка якості
| Requirement | Why |
| --------------------------- | ------------------------------------------------ |
| Опубліковано в ClawHub або npm | Користувачам потрібно, щоб `openclaw plugins install` працювала |
| Публічний репозиторій GitHub | Перегляд джерела, відстеження проблем, прозорість |
| Документація з налаштування та використання | Користувачі мають знати, як це налаштувати |
| Активна підтримка | Нещодавні оновлення або оперативна робота з issue |
| Вимога | Чому |
| ------------------------- | ----------------------------------------------- |
| Опубліковано в ClawHub або npm | Користувачам потрібно, щоб `openclaw plugins install` працювало |
| Публічний GitHub repo | Перевірка вихідного коду, відстеження проблем, прозорість |
| Документація з налаштування та використання | Користувачі мають знати, як це налаштувати |
| Активна підтримка | Нещодавні оновлення або оперативне опрацювання проблем |
Низькозусильні wrapper, незрозуміла відповідальність або непідтримувані пакети можуть бути відхилені.
Примітивні обгортки, незрозуміле володіння або пакунки без підтримки можуть бути відхилені.
## Пов’язане
- [Install and Configure Plugins](/uk/tools/plugin) — як установити будь-який Plugin
- [Building Plugins](/uk/plugins/building-plugins) — створіть власний
- [Plugin Manifest](/uk/plugins/manifest) — схема manifest
- [Встановлення та налаштування Plugin](/uk/tools/plugin) — як встановити будь-який Plugin
- [Створення Plugin](/uk/plugins/building-plugins) — створіть власний
- [Маніфест Plugin](/uk/plugins/manifest) — схема маніфесту

733
docs/uk/plugins/manifest.md
View File

File diff suppressed because it is too large Load Diff

448
docs/uk/tools/acp-agents.md
View File

@ -1,107 +1,104 @@
---
read_when:
- Запуск harness для кодування через ACP
- Запуск середовищ кодування через ACP
- Налаштування прив’язаних до розмови сеансів ACP у каналах обміну повідомленнями
- Прив’язка розмови в каналі повідомлень до постійного сеансу ACP
- Усунення несправностей бекенда ACP і підключення Plugin
- Налагодження доставки завершення ACP або циклів між агентами
- Використання команд `/acp` з чату
summary: Використовуйте сеанси середовища виконання ACP для Claude Code, Cursor, Gemini CLI, явного резервного ACP Codex, ACP OpenClaw та інших агентів harness
title: агенти ACP
- Прив’язування розмови в каналі обміну повідомленнями до постійного сеансу ACP
- Усунення неполадок бекенда ACP і підключення плагінів
- Налагодження доставки завершення ACP або циклів агент-до-агента
- Використання команд /acp у чаті
summary: Використовуйте runtime-сеанси ACP для Claude Code, Cursor, Gemini CLI, явного резервного варіанту Codex ACP, OpenClaw ACP та інших агентів harness
title: Агенти ACP
x-i18n:
generated_at: "2026-04-25T23:38:41Z"
generated_at: "2026-04-26T00:19:25Z"
model: gpt-5.4
provider: openai
source_hash: af8383ff983f590acde623c9414b8f9578471ca9200a92eaac34fc2bc51a2729
source_hash: fa4164b8d51cb8025c8898153258e96f7e2a2d78baacc1350292fa6a0bc8c377
source_path: tools/acp-agents.md
workflow: 15
---
Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні harness для кодування (наприклад, Pi, Claude Code, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані ACPX harness) через плагін бекенда ACP.
Сеанси [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) дають OpenClaw змогу запускати зовнішні середовища кодування (наприклад, Pi, Claude Code, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI та інші підтримувані середовища ACPX) через плагін бекенда ACP.
Якщо ви попросите OpenClaw звичайною мовою прив’язати або керувати Codex у поточній розмові, OpenClaw має використовувати нативний плагін app-server Codex (`/codex bind`, `/codex threads`, `/codex resume`). Якщо ви просите `/acp`, ACP, acpx або фоновий дочірній сеанс Codex, OpenClaw усе ще може маршрутизувати Codex через ACP. Кожен запуск сеансу ACP відстежується як [фонове завдання](/uk/automation/tasks).
Якщо ви просите OpenClaw звичайною мовою прив’язати або керувати Codex у поточній розмові й увімкнено вбудований плагін `codex`, OpenClaw має використовувати нативний плагін app-server Codex (`/codex bind`, `/codex threads`, `/codex resume`, `/codex steer`, `/codex stop`) замість ACP. Якщо ви явно просите `/acp`, ACP, acpx або тест адаптера ACP, OpenClaw усе одно може спрямувати Codex через ACP. Кожен запуск сеансу ACP відстежується як [фонове завдання](/uk/automation/tasks).
Якщо ви попросите OpenClaw звичайною мовою «запустити Claude Code у треді» або використати інший зовнішній harness, OpenClaw має маршрутизувати цей запит до середовища виконання ACP (а не до нативного середовища виконання субагентів).
Якщо ви просите OpenClaw звичайною мовою «запустити Claude Code у гілці» або використати інше зовнішнє середовище, OpenClaw має спрямувати цей запит до runtime ACP, а не до нативного runtime субагентів.
Якщо ви хочете, щоб Codex або Claude Code підключалися як зовнішній клієнт MCP безпосередньо
до наявних розмов каналів OpenClaw, використовуйте [`openclaw mcp serve`](/uk/cli/mcp)
замість ACP.
Якщо ви хочете, щоб Codex або Claude Code напряму підключалися як зовнішній клієнт MCP
до наявних розмов каналів OpenClaw, використовуйте
[`openclaw mcp serve`](/uk/cli/mcp) замість ACP.
## Яка сторінка мені потрібна?
## Яку сторінку мені потрібно?
Поруч є три поверхні, які легко сплутати:
Є три близькі поверхні, які легко сплутати:
| Ви хочете... | Використовуйте це | Примітки |
| ----------------------------------------------------------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Прив’язати або керувати Codex у поточній розмові | `/codex bind`, `/codex threads` | Нативний шлях app-server Codex; включає прив’язані відповіді в чаті, пересилання зображень, model/fast/permissions, елементи керування stop і steer. ACP — явний резервний варіант |
| Запустити Claude Code, Gemini CLI, явний ACP Codex або інший зовнішній harness _через_ OpenClaw | Ця сторінка: агенти ACP | Прив’язані до чату сеанси, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, елементи керування середовищем виконання |
| Відкрити сеанс Gateway OpenClaw _як_ сервер ACP для редактора або клієнта | [`openclaw acp`](/uk/cli/acp) | Режим мосту. IDE/клієнт використовує ACP для зв’язку з OpenClaw через stdio/WebSocket |
| Повторно використати локальний AI CLI як текстову резервну модель | [Бекенди CLI](/uk/gateway/cli-backends) | Не ACP. Немає інструментів OpenClaw, немає елементів керування ACP, немає середовища виконання harness |
| Ви хочете... | Використовуйте | Примітки |
| ----------------------------------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Прив’язати або керувати Codex у поточній розмові | `/codex bind`, `/codex threads` | Нативний шлях app-server Codex, коли увімкнено плагін `codex`; містить прив’язані відповіді в чаті, пересилання зображень, model/fast/permissions, stop і steer. ACP — це явний резервний варіант |
| Запустити Claude Code, Gemini CLI, явний Codex ACP або інше зовнішнє середовище _через_ OpenClaw | Ця сторінка: агенти ACP | Сеанси, прив’язані до чату, `/acp spawn`, `sessions_spawn({ runtime: "acp" })`, фонові завдання, елементи керування runtime |
| Відкрити сеанс Gateway OpenClaw _як_ сервер ACP для редактора або клієнта | [`openclaw acp`](/uk/cli/acp) | Режим мосту. IDE/клієнт говорить ACP з OpenClaw через stdio/WebSocket |
| Повторно використати локальний AI CLI як текстову резервну модель | [Бекенди CLI](/uk/gateway/cli-backends) | Не ACP. Без інструментів OpenClaw, без елементів керування ACP, без runtime середовища |
## Чи працює це одразу після встановлення?
Зазвичай так. Свіжі встановлення постачаються зі вбудованим плагіном середовища виконання `acpx`, увімкненим за замовчуванням, із локально закріпленим бінарним файлом `acpx`, який OpenClaw перевіряє та самостійно відновлює під час запуску. Запустіть `/acp doctor` для перевірки готовності.
Зазвичай так. Нові встановлення постачаються з увімкненим за замовчуванням вбудованим runtime-плагіном `acpx`, із закріпленим бінарним файлом `acpx`, локальним для плагіна, який OpenClaw перевіряє та самостійно відновлює під час запуску. Запустіть `/acp doctor` для перевірки готовності.
Поширені нюанси першого запуску:
Типові проблеми першого запуску:
- Якщо задано `plugins.allow`, це обмежувальний список плагінів, і він має містити `acpx`; інакше вбудований варіант за замовчуванням буде навмисно заблокований, а `/acp doctor` повідомить про відсутній запис в allowlist.
- Адаптери цільових harness (Codex, Claude тощо) можуть завантажуватися за потреби через `npx` під час першого використання.
- Авторизація постачальника для цього harness все одно має бути налаштована на хості.
- Якщо на хості немає npm або доступу до мережі, завантаження адаптерів під час першого запуску завершиться невдачею, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом.
- Якщо задано `plugins.allow`, це обмежувальний інвентар плагінів, і він має містити `acpx`; інакше вбудоване типове значення буде навмисно заблоковано, а `/acp doctor` повідомить про відсутній запис у списку дозволів.
- Адаптери цільових середовищ (Codex, Claude тощо) можуть бути завантажені за потреби через `npx` під час першого використання.
- Автентифікація постачальника для цього середовища все одно має бути налаштована на хості.
- Якщо на хості немає npm або доступу до мережі, перше завантаження адаптера завершиться невдачею, доки кеші не буде попередньо прогріто або адаптер не буде встановлено іншим способом.
## Операторський runbook
## Інструкція для оператора
Швидкий сценарій `/acp` із чату:
Швидкий потік `/acp` із чату:
1. **Запуск** — `/acp spawn claude --bind here`, `/acp spawn gemini --mode persistent --thread auto` або явний `/acp spawn codex --bind here`
2. **Працюйте** у прив’язаній розмові або треді (або явно вкажіть ключ сеансу).
1. **Запустити** — `/acp spawn claude --bind here`, `/acp spawn gemini --mode persistent --thread auto` або явно `/acp spawn codex --bind here`
2. **Працюйте** в прив’язаній розмові або гілці (або явно вказуйте ключ сеансу).
3. **Перевірте стан** — `/acp status`
4. **Налаштуйте** — `/acp model <provider/model>`, `/acp permissions <profile>`, `/acp timeout <seconds>`
5. **Скоригуйте** без заміни контексту — `/acp steer tighten logging and continue`
5. **Скоригуйте курс** без заміни контексту — `/acp steer tighten logging and continue`
6. **Зупиніть** — `/acp cancel` (поточний хід) або `/acp close` (сеанс + прив’язки)
Тригери природною мовою, які мають маршрутизуватися до нативного плагіна Codex:
Тригери природною мовою, які мають спрямовуватися до нативного плагіна Codex, коли
його увімкнено:
- «Прив’яжи цей канал Discord до Codex».
- «Під’єднай цей чат до треду Codex `<id>`».
- «Покажи треди Codex, а потім прив’яжи цей».
- «Під’єднай цей чат до гілки Codex `<id>`».
- «Покажи гілки Codex, а потім прив’яжи цю».
Нативна прив’язка розмови Codex — це шлях керування чатом за замовчуванням. Динамічні інструменти OpenClaw і далі виконуються через OpenClaw, а нативні інструменти Codex, такі як shell/apply-patch, виконуються всередині Codex. Для подій нативних інструментів Codex OpenClaw впроваджує нативний relay hook для кожного ходу, щоб plugin hooks могли блокувати
Нативна прив’язка розмови Codex — це типовий шлях керування чатом. Динамічні інструменти OpenClaw і далі виконуються через OpenClaw, тоді як нативні інструменти Codex, такі як shell/apply-patch, виконуються всередині Codex. Для подій нативних інструментів Codex OpenClaw інжектує нативний relay хуків для кожного ходу, щоб хуки плагінів могли блокувати
`before_tool_call`, спостерігати `after_tool_call` і маршрутизувати події Codex
`PermissionRequest` через погодження OpenClaw. Relay v1
навмисно є консервативним: він не змінює аргументи нативних інструментів Codex,
не переписує записи тредів Codex і не контролює фінальні відповіді або хуки Stop. Використовуйте явний
ACP лише тоді, коли вам потрібна модель середовища виконання/сеансу ACP. Межу підтримки вбудованого Codex
задокументовано в
`PermissionRequest` через погодження OpenClaw. Relay v1 навмисно консервативний: він не змінює аргументи нативних інструментів Codex, не переписує записи гілок Codex і не контролює фінальні відповіді/хуки Stop. Використовуйте явний ACP лише тоді, коли вам потрібна модель runtime/сеансів ACP. Межу підтримки вбудованого Codex задокументовано в
[контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract).
Тригери природною мовою, які мають маршрутизуватися до середовища виконання ACP:
Тригери природною мовою, які мають спрямовуватися до runtime ACP:
- «Запусти це як одноразовий сеанс Claude Code ACP і підсумуй результат».
- «Використай Gemini CLI для цього завдання в треді, а потім зберігай подальші дії в цьому самому треді».
- «Запусти Codex через ACP у фоновому треді».
- «Використай Gemini CLI для цього завдання в гілці, а потім зберігай подальші запити в цій самій гілці».
- «Запусти Codex через ACP у фоновій гілці».
OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, прив’язує до поточної розмови або треду, коли це підтримується, і маршрутизує подальші дії до цього сеансу до його закриття або завершення строку дії. Codex використовує цей шлях лише тоді, коли ACP задано явно або коли запитуване фонове середовище виконання все ще потребує ACP.
OpenClaw вибирає `runtime: "acp"`, визначає `agentId` середовища, прив’язується до поточної розмови або гілки, якщо це підтримується, і спрямовує подальші запити до цього сеансу до закриття/завершення строку дії. Codex іде цим шляхом лише тоді, коли ACP/acpx зазначено явно або нативний плагін Codex недоступний для потрібної операції.
Для `sessions_spawn`, `runtime: "acp"` оголошується лише тоді, коли ACP увімкнено,
ініціатор запиту не перебуває в sandbox, і завантажено бекенд ACP runtime. Він орієнтований на
ідентифікатори ACP harness, такі як `codex`, `claude`, `gemini` або `opencode`. Не передавайте
звичайний ідентифікатор агента конфігурації OpenClaw з `agents_list`, якщо цей запис
не налаштований явно з `agents.list[].runtime.type="acp"`; інакше використовуйте
середовище виконання субагента за замовчуванням. Якщо агент OpenClaw налаштований із
Для `sessions_spawn` параметр `runtime: "acp"` оголошується лише тоді, коли ACP увімкнено,
запитувач не ізольований і завантажено бекенд runtime ACP. Він націлюється
на id ACP-середовищ, такі як `codex`, `claude`, `gemini` або `opencode`. Не передавайте
звичайний id агента конфігурації OpenClaw з `agents_list`, якщо цей запис не
налаштований явно з `agents.list[].runtime.type="acp"`; інакше використовуйте
типовий runtime субагентів. Коли агент OpenClaw налаштовано з
`runtime.type="acp"`, OpenClaw використовує `runtime.acp.agent` як базовий
ідентифікатор harness.
id середовища.
## ACP проти субагентів
Використовуйте ACP, якщо вам потрібне зовнішнє середовище виконання harness. Використовуйте нативний app-server Codex для прив’язки/керування розмовою Codex. Використовуйте субагентів, якщо вам потрібні делеговані запуски, нативні для OpenClaw.
Використовуйте ACP, якщо вам потрібен runtime зовнішнього середовища. Використовуйте нативний app-server Codex для прив’язки/керування розмовою Codex, коли увімкнено плагін `codex`. Використовуйте субагентів, якщо вам потрібні нативні делеговані запуски OpenClaw.
| Область | Сеанс ACP | Запуск субагента |
| ------------- | -------------------------------------- | ----------------------------------- |
| Runtime | Плагін бекенда ACP (наприклад, acpx) | Нативне середовище виконання субагентів OpenClaw |
| Ключ сеансу | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
| Основні команди | `/acp ...` | `/subagents ...` |
| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (середовище виконання за замовчуванням) |
| Область | Сеанс ACP | Запуск субагента |
| ------------- | ------------------------------------- | ----------------------------------- |
| Runtime | Плагін бекенда ACP (наприклад acpx) | Нативний runtime субагентів OpenClaw |
| Ключ сеансу | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
| Основні команди | `/acp ...` | `/subagents ...` |
| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (типовий runtime) |
Див. також [Субагенти](/uk/tools/subagents).
@ -109,104 +106,104 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п
Для Claude Code через ACP стек такий:
1. Контрольна площина сеансу ACP OpenClaw
2. вбудований плагін середовища виконання `acpx`
1. Площина керування сеансами ACP OpenClaw
2. вбудований runtime-плагін `acpx`
3. адаптер Claude ACP
4. механізм runtime/session на стороні Claude
4. механізм runtime/сеансів на боці Claude
Важлива відмінність:
Важливе розрізнення:
- ACP Claude — це сеанс harness із елементами керування ACP, відновленням сеансу, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/треду.
- Бекенди CLI — це окремі локальні резервні середовища виконання, лише текстові. Див. [Бекенди CLI](/uk/gateway/cli-backends).
- ACP Claude — це сеанс середовища з елементами керування ACP, відновленням сеансів, відстеженням фонових завдань і необов’язковою прив’язкою до розмови/гілки.
- Бекенди CLI — це окремі локальні runtime резервного текстового режиму. Див. [Бекенди CLI](/uk/gateway/cli-backends).
Для операторів практичне правило таке:
- потрібні `/acp spawn`, сеанси з прив’язкою, елементи керування середовищем виконання або постійна робота harness: використовуйте ACP
- потрібні `/acp spawn`, сеанси з прив’язкою, елементи керування runtime або довготривала робота середовища: використовуйте ACP
- потрібен простий локальний текстовий резервний варіант через сирий CLI: використовуйте бекенди CLI
## Прив’язані сеанси
### Прив’язки до поточної розмови
`/acp spawn <harness> --bind here` прив’язує поточну розмову до запущеного сеансу ACP — без дочірнього треду, у тій самій поверхні чату. OpenClaw зберігає керування транспортом, автентифікацією, безпекою та доставкою; подальші повідомлення в цій розмові маршрутизуються до того самого сеансу; `/new` і `/reset` скидають сеанс на місці; `/acp close` видаляє прив’язку.
`/acp spawn <harness> --bind here` прив’язує поточну розмову до запущеного сеансу ACP — без дочірньої гілки, на тій самій поверхні чату. OpenClaw і далі володіє транспортом, автентифікацією, безпекою та доставкою; подальші повідомлення в цій розмові спрямовуються до того самого сеансу; `/new` і `/reset` скидають сеанс на місці; `/acp close` видаляє прив’язку.
Модель для розуміння:
Ментальна модель:
- **поверхня чату** — місце, де люди продовжують спілкування (канал Discord, тема Telegram, чат iMessage).
- **сеанс ACP** — стійкий стан середовища виконання Codex/Claude/Gemini, до якого маршрутизує OpenClaw.
- **дочірній тред/тема** — необов’язкова додаткова поверхня повідомлень, яка створюється лише через `--thread ...`.
- **робочий простір середовища виконання** — розташування у файловій системі (`cwd`, checkout репозиторію, робочий простір бекенда), де виконується harness. Незалежне від поверхні чату.
- **поверхня чату** — де люди продовжують спілкуватися (канал Discord, тема Telegram, чат iMessage).
- **сеанс ACP** — довготривалий стан runtime Codex/Claude/Gemini, до якого OpenClaw спрямовує запити.
- **дочірня гілка/тема** — необов’язкова додаткова поверхня повідомлень, яка створюється лише через `--thread ...`.
- **робочий простір runtime** — розташування у файловій системі (`cwd`, checkout репозиторію, робочий простір бекенда), де працює середовище. Воно не залежить від поверхні чату.
Приклади:
- `/codex bind` — залишити цей чат, запустити або під’єднати нативний app-server Codex, маршрутизувати сюди майбутні повідомлення.
- `/codex model gpt-5.4`, `/codex fast on`, `/codex permissions yolo` — налаштувати прив’язаний нативний тред Codex із чату.
- `/codex stop` або `/codex steer focus on the failing tests first` — керувати активним нативним ходом Codex.
- `/acp spawn codex --bind here` — явний резервний ACP-шлях для Codex.
- `/acp spawn codex --thread auto` — OpenClaw може створити дочірній тред/тему та прив’язати там.
- `/acp spawn codex --bind here --cwd /workspace/repo` — та сама прив’язка до чату, Codex виконується в `/workspace/repo`.
- `/codex bind` — залишити цей чат, запустити або під’єднати нативний app-server Codex, спрямовувати сюди майбутні повідомлення.
- `/codex model gpt-5.4`, `/codex fast on`, `/codex permissions yolo` — налаштувати прив’язану нативну гілку Codex із чату.
- `/codex stop` або `/codex steer focus on the failing tests first` — керувати активним ходом нативного Codex.
- `/acp spawn codex --bind here` — явний резервний варіант ACP для Codex.
- `/acp spawn codex --thread auto` — OpenClaw може створити дочірню гілку/тему і прив’язати її там.
- `/acp spawn codex --bind here --cwd /workspace/repo` — та сама прив’язка чату, Codex працює в `/workspace/repo`.
Примітки:
- `--bind here` і `--thread ...` взаємовиключні.
- `--bind here` працює лише на каналах, які оголошують прив’язку до поточної розмови; інакше OpenClaw повертає чітке повідомлення про відсутність підтримки. Прив’язки зберігаються після перезапусків Gateway.
- У Discord `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірній тред для `--thread auto|here` — не для `--bind here`.
- Якщо ви запускаєте до іншого ACP агента без `--cwd`, OpenClaw за замовчуванням успадковує робочий простір **цільового агента**. Відсутні успадковані шляхи (`ENOENT`/`ENOTDIR`) повертаються до значення бекенда за замовчуванням; інші помилки доступу (наприклад, `EACCES`) відображаються як помилки запуску.
- `--bind here` і `--thread ...` є взаємовиключними.
- `--bind here` працює лише в каналах, які оголошують прив’язку до поточної розмови; інакше OpenClaw повертає чітке повідомлення про непідтримуваність. Прив’язки зберігаються після перезапусків gateway.
- У Discord `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити дочірню гілку для `--thread auto|here`, а не для `--bind here`.
- Якщо ви запускаєте інший агент ACP без `--cwd`, OpenClaw успадковує робочий простір **цільового агента** за замовчуванням. Відсутні успадковані шляхи (`ENOENT`/`ENOTDIR`) повертаються до типового значення бекенда; інші помилки доступу (наприклад, `EACCES`) показуються як помилки запуску.
### Сеанси, прив’язані до тредів
### Сеанси, прив’язані до гілки
Коли прив’язки до тредів увімкнено для адаптера каналу, сеанси ACP можна прив’язувати до тредів:
Коли для адаптера каналу увімкнено прив’язки до гілок, сеанси ACP можна прив’язувати до гілок:
- OpenClaw прив’язує тред до цільового сеансу ACP.
- Подальші повідомлення в цьому треді маршрутизуються до прив’язаного сеансу ACP.
- Вивід ACP доставляється назад у той самий тред.
- Втрата фокуса/закриття/архівування/завершення часу простою або завершення максимального строку дії видаляє прив’язку.
- OpenClaw прив’язує гілку до цільового сеансу ACP.
- Подальші повідомлення в цій гілці спрямовуються до прив’язаного сеансу ACP.
- Вивід ACP доставляється назад у ту саму гілку.
- Втрата фокусу/закриття/архівування/тайм-аут неактивності або завершення максимального строку дії видаляє прив’язку.
Підтримка прив’язки до тредів залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до тредів, OpenClaw повертає чітке повідомлення про відсутність підтримки/недоступність.
Підтримка прив’язки до гілок залежить від адаптера. Якщо активний адаптер каналу не підтримує прив’язки до гілок, OpenClaw повертає чітке повідомлення про непідтримуваність/недоступність.
Обов’язкові feature flags для ACP, прив’язаного до тредів:
Потрібні feature flag для ACP, прив’язаного до гілки:
- `acp.enabled=true`
- `acp.dispatch.enabled` увімкнений за замовчуванням (установіть `false`, щоб призупинити диспетчеризацію ACP)
- Увімкнений прапорець запуску ACP-тредів для адаптера каналу (залежить від адаптера)
- `acp.dispatch.enabled` увімкнено за замовчуванням (встановіть `false`, щоб призупинити диспетчеризацію ACP)
- Увімкнено прапорець запуску ACP-гілок в адаптері каналу (залежить від адаптера)
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
### Канали з підтримкою тредів
### Канали з підтримкою гілок
- Будь-який адаптер каналу, який надає можливість прив’язки сеансу/треду.
- Будь-який адаптер каналу, який надає можливість прив’язки сеансу/гілки.
- Поточна вбудована підтримка:
- треди/канали Discord
- гілки/канали Discord
- теми Telegram (теми форумів у групах/супергрупах і теми в DM)
- Канали Plugin можуть додавати підтримку через той самий інтерфейс прив’язки.
## Налаштування для конкретних каналів
Для неефемерних сценаріїв налаштуйте постійні прив’язки ACP у записах верхнього рівня `bindings[]`.
Для неепізодичних сценаріїв налаштуйте постійні прив’язки ACP у записах верхнього рівня `bindings[]`.
### Модель прив’язки
- `bindings[].type="acp"` позначає постійну прив’язку розмови ACP.
- `bindings[].match` визначає цільову розмову:
- Канал або тред Discord: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- Канал або гілка Discord: `match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
- Тема форуму Telegram: `match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
- DM/груповий чат BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
Для стабільних прив’язок груп надавайте перевагу `chat_id:*` або `chat_identifier:*`.
- DM/груповий чат iMessage: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
Для стабільних прив’язок груп надавайте перевагу `chat_id:*`.
- `bindings[].agentId` — це ідентифікатор агента OpenClaw, якому належить прив’язка.
- BlueBubbles DM/груповий чат: `match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
Для стабільних прив’язок груп віддавайте перевагу `chat_id:*` або `chat_identifier:*`.
- iMessage DM/груповий чат: `match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
Для стабільних прив’язок груп віддавайте перевагу `chat_id:*`.
- `bindings[].agentId` — це id агента OpenClaw-власника.
- Необов’язкові перевизначення ACP містяться в `bindings[].acp`:
- `mode` (`persistent` або `oneshot`)
- `label`
- `cwd`
- `backend`
### Значення runtime за замовчуванням для кожного агента
### Типові значення runtime для кожного агента
Використовуйте `agents.list[].runtime`, щоб один раз визначити значення ACP за замовчуванням для кожного агента:
Використовуйте `agents.list[].runtime`, щоб один раз визначити типові значення ACP для кожного агента:
- `agents.list[].runtime.type="acp"`
- `agents.list[].runtime.acp.agent` (ідентифікатор harness, наприклад `codex` або `claude`)
- `agents.list[].runtime.acp.agent` (id середовища, наприклад `codex` або `claude`)
- `agents.list[].runtime.acp.backend`
- `agents.list[].runtime.acp.mode`
- `agents.list[].runtime.acp.cwd`
@ -215,7 +212,7 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п
1. `bindings[].acp.*`
2. `agents.list[].runtime.acp.*`
3. глобальні значення ACP за замовчуванням (наприклад, `acp.backend`)
3. глобальні типові значення ACP (наприклад `acp.backend`)
Приклад:
@ -299,12 +296,12 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п
Поведінка:
- OpenClaw забезпечує наявність налаштованого сеансу ACP перед використанням.
- Повідомлення в цьому каналі або темі маршрутизуються до налаштованого сеансу ACP.
- OpenClaw гарантує, що налаштований сеанс ACP існує перед використанням.
- Повідомлення в цьому каналі або темі спрямовуються до налаштованого сеансу ACP.
- У прив’язаних розмовах `/new` і `/reset` скидають той самий ключ сеансу ACP на місці.
- Тимчасові прив’язки runtime (наприклад, створені потоками фокусування треду) усе ще застосовуються там, де вони є.
- Тимчасові runtime-прив’язки (наприклад, створені потоками фокусування гілок) усе ще застосовуються, якщо вони наявні.
- Для міжагентних запусків ACP без явного `cwd` OpenClaw успадковує робочий простір цільового агента з конфігурації агента.
- Відсутні успадковані шляхи робочого простору повертаються до `cwd` бекенда за замовчуванням; помилки доступу для наявних шляхів повертаються як помилки запуску.
- Відсутні успадковані шляхи робочого простору повертаються до типового `cwd` бекенда; збої доступу за наявних шляхів показуються як помилки запуску.
## Запуск сеансів ACP (інтерфейси)
@ -324,71 +321,71 @@ OpenClaw вибирає `runtime: "acp"`, визначає `agentId` harness, п
Примітки:
- `runtime` за замовчуванням має значення `subagent`, тому для сеансів ACP явно задавайте `runtime: "acp"`.
- Типове значення `runtime` — `subagent`, тому для сеансів ACP потрібно явно встановити `runtime: "acp"`.
- Якщо `agentId` не вказано, OpenClaw використовує `acp.defaultAgent`, якщо його налаштовано.
- `mode: "session"` вимагає `thread: true`, щоб зберігати постійну прив’язану розмову.
- `mode: "session"` вимагає `thread: true`, щоб зберегти постійну прив’язану розмову.
Відомості про інтерфейс:
Докладно про інтерфейс:
- `task` (обов’язково): початковий prompt, який надсилається до сеансу ACP.
- `runtime` (обов’язково для ACP): має бути `"acp"`.
- `agentId` (необов’язково): цільовий ідентифікатор ACP harness. Якщо задано, використовується `acp.defaultAgent`.
- `thread` (необов’язково, за замовчуванням `false`): запитує сценарій прив’язки треду, де це підтримується.
- `mode` (необов’язково): `run` (одноразово) або `session` (постійно).
- за замовчуванням — `run`
- якщо `thread: true`, а `mode` не вказано, OpenClaw може за замовчуванням використовувати постійну поведінку залежно від шляху runtime
- `agentId` (необов’язково): id цільового середовища ACP. Якщо задано, використовується `acp.defaultAgent`.
- `thread` (необов’язково, типово `false`): запитати потік прив’язки до гілки, де це підтримується.
- `mode` (необов’язково): `run` (одноразовий) або `session` (постійний).
- типове значення — `run`
- якщо `thread: true` і `mode` не вказано, OpenClaw може за замовчуванням використовувати постійну поведінку залежно від шляху runtime
- `mode: "session"` вимагає `thread: true`
- `cwd` (необов’язково): запитаний робочий каталог runtime (перевіряється політикою бекенда/runtime). Якщо не вказано, запуск ACP успадковує робочий простір цільового агента, якщо його налаштовано; відсутні успадковані шляхи повертаються до значень бекенда за замовчуванням, а реальні помилки доступу повертаються.
- `label` (необов’язково): видима для оператора мітка, яка використовується в тексті сеансу/банера.
- `resumeSessionId` (необов’язково): відновлює наявний сеанс ACP замість створення нового. Агент відтворює історію своєї розмови через `session/load`. Вимагає `runtime: "acp"`.
- `streamTo` (необов’язково): `"parent"` передає підсумки перебігу початкового запуску ACP назад до сеансу ініціатора як системні події.
- Якщо доступно, серед прийнятих відповідей є `streamLogPath`, що вказує на JSONL-журнал у межах сеансу (`<sessionId>.acp-stream.jsonl`), який можна відстежувати для повної історії relay.
- `runTimeoutSeconds` (необов’язково): перериває дочірній хід ACP через N секунд. `0` залишає хід на шляху Gateway без тайм-ауту. Те саме значення застосовується до запуску Gateway і runtime ACP, щоб завислі harness або harness із вичерпаною квотою не займали смугу батьківського агента безстроково.
- `model` (необов’язково): явне перевизначення моделі для дочірнього сеансу ACP. Запуски Codex ACP нормалізують посилання Codex OpenClaw, такі як `openai-codex/gpt-5.4`, у стартову конфігурацію Codex ACP перед `session/new`; форми зі слешами, такі як `openai-codex/gpt-5.4/high`, також задають effort міркування Codex ACP. Інші harness мають оголошувати ACP `models` і підтримувати `session/set_model`; інакше OpenClaw/acpx повертає чітку помилку замість тихого повернення до моделі цільового агента за замовчуванням.
- `thinking` (необов’язково): явне effort thinking/reasoning для дочірнього сеансу ACP. Для Codex ACP `minimal` відповідає low effort, `low`/`medium`/`high`/`xhigh` відображаються напряму, а `off` прибирає стартове перевизначення reasoning-effort.
- `cwd` (необов’язково): запитаний робочий каталог runtime (перевіряється політикою бекенда/runtime). Якщо не вказано, запуск ACP успадковує робочий простір цільового агента, якщо його налаштовано; відсутні успадковані шляхи повертаються до типових значень бекенда, тоді як реальні помилки доступу повертаються.
- `label` (необов’язково): операторська мітка, яка використовується в тексті сеансу/банера.
- `resumeSessionId` (необов’язково): відновити наявний сеанс ACP замість створення нового. Агент відтворює свою історію розмови через `session/load`. Потрібно `runtime: "acp"`.
- `streamTo` (необов’язково): `"parent"` транслює підсумки прогресу початкового запуску ACP назад у сеанс запитувача як системні події.
- Якщо доступно, прийнятні відповіді містять `streamLogPath`, що вказує на JSONL-журнал у межах сеансу (`<sessionId>.acp-stream.jsonl`), який можна відстежувати для повної історії relay.
- `runTimeoutSeconds` (необов’язково): перериває дочірній хід ACP після N секунд. `0` зберігає хід на шляху Gateway без тайм-ауту. Те саме значення застосовується до запуску Gateway і runtime ACP, щоб середовища, що зависли або вичерпали квоту, не займали безкінечно смугу батьківського агента.
- `model` (необов’язково): явне перевизначення моделі для дочірнього сеансу ACP. Запуски Codex ACP нормалізують посилання OpenClaw Codex, такі як `openai-codex/gpt-5.4`, до стартової конфігурації Codex ACP перед `session/new`; форми зі слешами, такі як `openai-codex/gpt-5.4/high`, також задають зусилля міркування Codex ACP. Інші середовища мають оголошувати ACP `models` і підтримувати `session/set_model`; інакше OpenClaw/acpx завершується з чіткою помилкою замість тихого переходу до типового значення цільового агента.
- `thinking` (необов’язково): явний рівень thinking/reasoning effort для дочірнього сеансу ACP. Для Codex ACP `minimal` відповідає низькому рівню, `low`/`medium`/`high`/`xhigh` відображаються напряму, а `off` прибирає стартове перевизначення reasoning-effort.
## Модель доставки
Сеанси ACP можуть бути або інтерактивними робочими просторами, або фоновою роботою, що належить батьківському сеансу. Шлях доставки залежить від цієї форми.
Сеанси ACP можуть бути або інтерактивними робочими просторами, або фоновими завданнями під контролем батьківського процесу. Шлях доставки залежить від цієї форми.
### Інтерактивні сеанси ACP
Інтерактивні сеанси призначені для продовження спілкування на видимій поверхні чату:
Інтерактивні сеанси призначені для продовження розмови у видимій поверхні чату:
- `/acp spawn ... --bind here` прив’язує поточну розмову до сеансу ACP.
- `/acp spawn ... --thread ...` прив’язує тред/тему каналу до сеансу ACP.
- Постійні налаштовані `bindings[].type="acp"` маршрутизують відповідні розмови до того самого сеансу ACP.
- `/acp spawn ... --thread ...` прив’язує гілку/тему каналу до сеансу ACP.
- Постійні налаштовані `bindings[].type="acp"` спрямовують відповідні розмови до того самого сеансу ACP.
Подальші повідомлення в прив’язаній розмові маршрутизуються безпосередньо до сеансу ACP, а вивід ACP доставляється назад до того самого каналу/треду/теми.
Подальші повідомлення в прив’язаній розмові спрямовуються безпосередньо до сеансу ACP, а вивід ACP доставляється назад у той самий канал/гілку/тему.
### Одноразові сеанси ACP, що належать батьківському сеансу
### Одноразові сеанси ACP під контролем батьківського процесу
Одноразові сеанси ACP, запущені іншим агентом, є фоновими дочірніми сеансами, подібно до субагентів:
- Батьківський сеанс запитує роботу через `sessions_spawn({ runtime: "acp", mode: "run" })`.
- Дочірній сеанс виконується у власному сеансі ACP harness.
- Дочірні ходи виконуються на тій самій фоновій смузі, що й нативні запуски субагентів, тому повільний ACP harness не блокує іншу роботу основного сеансу.
- Про завершення повідомляється назад через внутрішній шлях анонсування завершення завдання.
- Батьківський сеанс переписує результат дочірнього в звичайному голосі асистента, коли доречна відповідь для користувача.
- Батьківський процес запитує роботу через `sessions_spawn({ runtime: "acp", mode: "run" })`.
- Дочірній процес виконується у власному сеансі ACP-середовища.
- Дочірні ходи виконуються в тій самій фоновій смузі, що й нативні запуски субагентів, тому повільне ACP-середовище не блокує іншу роботу основного сеансу.
- Завершення повертається через внутрішній шлях оголошення про завершення завдання.
- Батьківський процес переписує результат дочірнього в нормальному голосі помічника, коли потрібна відповідь для користувача.
Не розглядайте цей шлях як peer-to-peer чат між батьківським і дочірнім сеансами. Дочірній сеанс уже має канал завершення назад до батьківського.
Не розглядайте цей шлях як peer-to-peer чат між батьківським і дочірнім процесами. Дочірній процес уже має канал завершення назад до батьківського.
### `sessions_send` і доставка A2A
`sessions_send` може бути націлений на інший сеанс після запуску. Для звичайних peer-сеансів OpenClaw використовує шлях agent-to-agent (A2A) для подальших дій після впровадження повідомлення:
`sessions_send` може націлюватися на інший сеанс після запуску. Для звичайних рівноправних сеансів OpenClaw використовує шлях подальших повідомлень agent-to-agent (A2A) після інжекції повідомлення:
- очікує відповідь цільового сеансу
- за потреби дозволяє ініціатору та цільовому сеансу обмінятися обмеженою кількістю подальших ходів
- просить цільовий сеанс сформувати повідомлення анонсу
- доставляє цей анонс до видимого каналу або треду
- чекати відповіді цільового сеансу
- за потреби дозволити запитувачу й цільовому сеансу обмінятися обмеженою кількістю подальших ходів
- попросити цільовий сеанс створити announce-повідомлення
- доставити це announce у видимий канал або гілку
Цей шлях A2A є резервним варіантом для peer-надсилань, коли відправнику потрібна видима подальша дія. Він залишається ввімкненим, коли не пов’язаний сеанс може бачити та надсилати повідомлення до цільового ACP, наприклад за широких налаштувань `tools.sessions.visibility`.
Цей шлях A2A є резервним варіантом для peer-відправлень, де відправнику потрібен видимий подальший відгук. Він залишається увімкненим, коли незв’язаний сеанс може бачити й надсилати повідомлення ACP-цілі, наприклад за широких налаштувань `tools.sessions.visibility`.
OpenClaw пропускає подальшу дію A2A лише тоді, коли ініціатор є батьківським сеансом свого власного одноразового дочірнього сеансу ACP. У такому разі запуск A2A поверх завершення завдання може пробудити батьківський сеанс із результатом дочірнього, переслати відповідь батьківського назад у дочірній сеанс і створити цикл echo між батьківським і дочірнім сеансами. Результат `sessions_send` для цього випадку з дочірнім сеансом, що належить батьківському, містить `delivery.status="skipped"`, оскільки за результат уже відповідає шлях завершення.
OpenClaw пропускає A2A-подовження лише тоді, коли запитувач є батьківським процесом свого власного одноразового дочірнього сеансу ACP. У такому разі запуск A2A поверх завершення завдання може розбудити батьківський процес результатом дочірнього, переслати відповідь батьківського назад у дочірній процес і створити цикл відлуння між батьківським і дочірнім процесами. Результат `sessions_send` повідомляє `delivery.status="skipped"` для такого випадку дочірнього сеансу у власності, оскільки шлях завершення вже відповідає за результат.
### Відновлення наявного сеансу
Використовуйте `resumeSessionId`, щоб продовжити попередній сеанс ACP замість запуску нового. Агент відтворює історію своєї розмови через `session/load`, тому продовжує роботу з повним контекстом попередніх дій.
Використовуйте `resumeSessionId`, щоб продовжити попередній сеанс ACP замість запуску з нуля. Агент відтворює свою історію розмови через `session/load`, тож продовжує з повним контекстом попереднього.
```json
{
@ -401,28 +398,28 @@ OpenClaw пропускає подальшу дію A2A лише тоді, ко
Поширені сценарії використання:
- Передати сеанс Codex із ноутбука на телефон — попросіть агента продовжити з того місця, де ви зупинилися
- Продовжити сеанс кодування, який ви почали інтерактивно в CLI, тепер безголово через свого агента
- Відновити роботу, яку було перервано перезапуском Gateway або тайм-аутом простою
- Передати сеанс Codex з ноутбука на телефон — попросіть агента продовжити з того місця, де ви зупинилися
- Продовжити сеанс кодування, який ви почали інтерактивно в CLI, але тепер безголово через агента
- Продовжити роботу, яку було перервано через перезапуск gateway або тайм-аут неактивності
Примітки:
- `resumeSessionId` вимагає `runtime: "acp"` — повертає помилку, якщо використовується із runtime субагента.
- `resumeSessionId` відновлює історію розмови upstream ACP; `thread` і `mode` все одно застосовуються звичайним чином до нового сеансу OpenClaw, який ви створюєте, тому `mode: "session"` усе ще вимагає `thread: true`.
- `resumeSessionId` вимагає `runtime: "acp"` — якщо використовується з runtime субагента, повертається помилка.
- `resumeSessionId` відновлює вищу історію розмови ACP; `thread` і `mode` усе одно застосовуються звичайним чином до нового сеансу OpenClaw, який ви створюєте, тож `mode: "session"` і далі вимагає `thread: true`.
- Цільовий агент має підтримувати `session/load` (Codex і Claude Code підтримують).
- Якщо ідентифікатор сеансу не знайдено, запуск завершується чіткою помилкою — без тихого повернення до нового сеансу.
- Якщо id сеансу не знайдено, запуск завершується з чіткою помилкою — без тихого повернення до нового сеансу.
<Accordion title="Smoke-тест після розгортання">
<Accordion title="Smoke test після розгортання">
Після розгортання Gateway виконайте реальну наскрізну перевірку, а не покладайтеся лише на модульні тести:
Після розгортання gateway виконайте живу наскрізну перевірку замість того, щоб покладатися лише на unit-тести:
1. Перевірте версію та commit розгорнутого Gateway на цільовому хості.
2. Відкрийте тимчасовий bridge-сеанс ACPX до живого агента.
1. Перевірте версію й коміт розгорнутого gateway на цільовому хості.
2. Відкрийте тимчасовий сеанс мосту ACPX до живого агента.
3. Попросіть цього агента викликати `sessions_spawn` з `runtime: "acp"`, `agentId: "codex"`, `mode: "run"` і завданням `Reply with exactly LIVE-ACP-SPAWN-OK`.
4. Переконайтеся, що є `accepted=yes`, реальний `childSessionKey` і немає помилки validator.
5. Очистьте тимчасовий bridge-сеанс.
4. Переконайтеся, що є `accepted=yes`, реальний `childSessionKey` і немає помилки валідатора.
5. Очистьте тимчасовий сеанс мосту.
Тримайте перевірку на `mode: "run"` і пропускайте `streamTo: "parent"` — прив’язані до тредів шляхи `mode: "session"` і relay-потоків є окремими, більш насиченими інтеграційними перевірками.
Залишайте перевірку на `mode: "run"` і пропускайте `streamTo: "parent"` — шляхи `mode: "session"`, прив’язані до гілок, і шляхи relay-потоку є окремими, багатшими інтеграційними перевірками.
</Accordion>
@ -432,16 +429,16 @@ OpenClaw пропускає подальшу дію A2A лише тоді, ко
Поточні обмеження:
- Якщо сеанс ініціатора працює в sandbox, запуски ACP блокуються як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`.
- Якщо сеанс-запитувач є sandboxed, запуски ACP блокуються як для `sessions_spawn({ runtime: "acp" })`, так і для `/acp spawn`.
- Помилка: `Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.`
- `sessions_spawn` з `runtime: "acp"` не підтримує `sandbox: "require"`.
- Помилка: `sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".`
Використовуйте `runtime: "subagent"`, коли потрібне виконання з примусовим sandbox.
Використовуйте `runtime: "subagent"`, коли вам потрібне виконання з примусовим sandbox.
### З команди `/acp`
За потреби використовуйте `/acp spawn` для явного керування оператором із чату.
Використовуйте `/acp spawn` для явного операторського керування з чату, коли це потрібно.
```text
/acp spawn codex --mode persistent --thread auto
@ -450,7 +447,7 @@ OpenClaw пропускає подальшу дію A2A лише тоді, ко
/acp spawn codex --thread here
```
Основні прапорці:
Ключові прапорці:
- `--mode persistent|oneshot`
- `--bind here|off`
@ -458,80 +455,80 @@ OpenClaw пропускає подальшу дію A2A лише тоді, ко
- `--cwd <absolute-path>`
- `--label <name>`
Див. [Слеш-команди](/uk/tools/slash-commands).
Див. [Slash Commands](/uk/tools/slash-commands).
## Визначення цільового сеансу
## Розв’язання цілі сеансу
Більшість дій `/acp` приймають необов’язкову ціль сеансу (`session-key`, `session-id` або `session-label`).
Порядок визначення:
Порядок розв’язання:
1. Явний аргумент цілі (або `--session` для `/acp steer`)
- спочатку пробує key
- потім session id у форматі UUID
- потім label
2. Поточна прив’язка треду (якщо цю розмову/тред прив’язано до сеансу ACP)
3. Резервний варіант поточного сеансу ініціатора
- спочатку пробує ключ
- потім `session id` у формі UUID
- потім мітку
2. Прив’язка поточної гілки (якщо цю розмову/гілку прив’язано до сеансу ACP)
3. Резервний варіант поточного сеансу запитувача
Прив’язки до поточної розмови й прив’язки до тредів обидві беруть участь у кроці 2.
Прив’язки до поточної розмови та прив’язки до гілки обидві беруть участь у кроці 2.
Якщо ціль не вдається визначити, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`).
Якщо жодну ціль не вдається розв’язати, OpenClaw повертає чітку помилку (`Unable to resolve session target: ...`).
## Режими прив’язки під час запуску
`/acp spawn` підтримує `--bind here|off`.
| Режим | Поведінка |
| ----- | ---------------------------------------------------------------------- |
| `here` | Прив’язати поточну активну розмову на місці; завершитися помилкою, якщо активної розмови немає. |
| `off` | Не створювати прив’язку до поточної розмови. |
| Режим | Поведінка |
| ------ | -------------------------------------------------------------------- |
| `here` | Прив’язати поточну активну розмову на місці; завершитися помилкою, якщо активної немає. |
| `off` | Не створювати прив’язку до поточної розмови. |
Примітки:
- `--bind here` — це найпростіший операторський шлях для сценарію «зробити цей канал або чат підключеним до Codex».
- `--bind here` не створює дочірній тред.
- `--bind here` — це найпростіший операторський шлях для «зробити цей канал або чат підключеним до Codex».
- `--bind here` не створює дочірню гілку.
- `--bind here` доступний лише в каналах, які надають підтримку прив’язки до поточної розмови.
- `--bind` і `--thread` не можна поєднувати в одному виклику `/acp spawn`.
## Режими тредів під час запуску
## Режими гілок під час запуску
`/acp spawn` підтримує `--thread auto|here|off`.
| Режим | Поведінка |
| ----- | ---------------------------------------------------------------------------------------------------- |
| `auto` | У активному треді: прив’язати цей тред. Поза тредом: створити/прив’язати дочірній тред, якщо це підтримується. |
| `here` | Вимагати поточний активний тред; завершитися помилкою, якщо його немає. |
| `off` | Без прив’язки. Сеанс запускається без прив’язки. |
| Режим | Поведінка |
| ------ | --------------------------------------------------------------------------------------------------- |
| `auto` | В активній гілці: прив’язати цю гілку. Поза гілкою: створити/прив’язати дочірню гілку, якщо це підтримується. |
| `here` | Вимагати поточну активну гілку; завершитися помилкою, якщо ви не в ній. |
| `off` | Без прив’язки. Сеанс запускається без прив’язки. |
Примітки:
- На поверхнях без підтримки прив’язки до тредів поведінка за замовчуванням фактично дорівнює `off`.
- Запуск із прив’язкою до треду потребує підтримки політики каналу:
- На поверхнях без підтримки прив’язки до гілки типова поведінка фактично дорівнює `off`.
- Запуск із прив’язкою до гілки потребує підтримки політики каналу:
- Discord: `channels.discord.threadBindings.spawnAcpSessions=true`
- Telegram: `channels.telegram.threadBindings.spawnAcpSessions=true`
- Використовуйте `--bind here`, якщо хочете закріпити поточну розмову без створення дочірнього треду.
- Використовуйте `--bind here`, якщо хочете закріпити поточну розмову без створення дочірньої гілки.
## Елементи керування ACP
| Команда | Що вона робить | Приклад |
| Команда | Що робить | Приклад |
| -------------------- | ------------------------------------------------------- | ------------------------------------------------------------- |
| `/acp spawn` | Створює сеанс ACP; необов’язкова поточна прив’язка або прив’язка до треду. | `/acp spawn codex --bind here --cwd /repo` |
| `/acp spawn` | Створює сеанс ACP; необов’язкова поточна прив’язка або прив’язка до гілки. | `/acp spawn codex --bind here --cwd /repo` |
| `/acp cancel` | Скасовує хід у процесі виконання для цільового сеансу. | `/acp cancel agent:codex:acp:<uuid>` |
| `/acp steer` | Надсилає інструкцію steer до запущеного сеансу. | `/acp steer --session support inbox prioritize failing tests` |
| `/acp close` | Закриває сеанс і відв’язує цілі тредів. | `/acp close` |
| `/acp status` | Показує бекенд, режим, стан, параметри runtime, можливості. | `/acp status` |
| `/acp close` | Закриває сеанс і скасовує прив’язку цільових гілок. | `/acp close` |
| `/acp status` | Показує бекенд, режим, стан, параметри runtime і можливості. | `/acp status` |
| `/acp set-mode` | Встановлює режим runtime для цільового сеансу. | `/acp set-mode plan` |
| `/acp set` | Загальний запис параметра конфігурації runtime. | `/acp set model openai/gpt-5.4` |
| `/acp cwd` | Встановлює перевизначення робочого каталогу runtime. | `/acp cwd /Users/user/Projects/repo` |
| `/acp permissions` | Встановлює профіль політики погодження. | `/acp permissions strict` |
| `/acp timeout` | Встановлює тайм-аут runtime (у секундах). | `/acp timeout 120` |
| `/acp model` | Встановлює перевизначення моделі runtime. | `/acp model anthropic/claude-opus-4-6` |
| `/acp reset-options` | Видаляє перевизначення параметрів runtime сеансу. | `/acp reset-options` |
| `/acp sessions` | Перелічує нещодавні сеанси ACP зі сховища. | `/acp sessions` |
| `/acp doctor` | Стан бекенда, можливості, дії для виправлення. | `/acp doctor` |
| `/acp install` | Виводить детерміновані кроки встановлення та ввімкнення. | `/acp install` |
| `/acp reset-options` | Видаляє перевизначення параметрів runtime для сеансу. | `/acp reset-options` |
| `/acp sessions` | Показує список нещодавніх сеансів ACP зі сховища. | `/acp sessions` |
| `/acp doctor` | Стан бекенда, можливості, практичні виправлення. | `/acp doctor` |
| `/acp install` | Виводить детерміновані кроки встановлення та ввімкнення.| `/acp install` |
`/acp status` показує фактичні параметри runtime, а також ідентифікатори сеансу на рівні runtime і бекенда. Помилки unsupported-control чітко відображаються, коли бекенд не має певної можливості. `/acp sessions` читає сховище для поточного прив’язаного сеансу або сеансу ініціатора; токени цілі (`session-key`, `session-id` або `session-label`) визначаються через виявлення сеансів Gateway, зокрема для власних коренів `session.store` для окремих агентів.
`/acp status` показує фактичні параметри runtime, а також ідентифікатори сеансу на рівні runtime і бекенда. Помилки непідтримуваних елементів керування показуються чітко, коли бекенд не має певної можливості. `/acp sessions` читає сховище для поточного прив’язаного сеансу або сеансу запитувача; цільові токени (`session-key`, `session-id` або `session-label`) розв’язуються через виявлення сеансів gateway, включно з власними коренями `session.store` для кожного агента.
## Відображення параметрів runtime
@ -539,45 +536,44 @@ OpenClaw пропускає подальшу дію A2A лише тоді, ко
Еквівалентні операції:
- `/acp model <id>` відображається на ключ конфігурації runtime `model`. Для Codex ACP OpenClaw нормалізує `openai-codex/<model>` до ідентифікатора моделі адаптера та відображає суфікси міркування через slash, такі як `openai-codex/gpt-5.4/high`, на Codex ACP `reasoning_effort`. Для інших harness керування моделлю залежить від підтримки адаптером ACP `models` і `session/set_model`.
- `/acp model <id>` відображається на ключ конфігурації runtime `model`. Для Codex ACP OpenClaw нормалізує `openai-codex/<model>` до id моделі адаптера та відображає суфікси міркування через слеш, такі як `openai-codex/gpt-5.4/high`, на Codex ACP `reasoning_effort`. Для інших середовищ керування моделлю залежить від підтримки адаптером ACP `models` і `session/set_model`.
- `/acp set thinking <level>` відображається на ключ конфігурації runtime `thinking`. Для Codex ACP OpenClaw надсилає відповідний `reasoning_effort`, якщо адаптер це підтримує.
- `/acp permissions <profile>` відображається на ключ конфігурації runtime `approval_policy`.
- `/acp timeout <seconds>` відображається на ключ конфігурації runtime `timeout`.
- `/acp cwd <path>` безпосередньо оновлює перевизначення cwd runtime.
- `/acp cwd <path>` напряму оновлює перевизначення `cwd` runtime.
- `/acp set <key> <value>` — це загальний шлях.
- Особливий випадок: `key=cwd` використовує шлях перевизначення cwd.
- Особливий випадок: `key=cwd` використовує шлях перевизначення `cwd`.
- `/acp reset-options` очищає всі перевизначення runtime для цільового сеансу.
## Налаштування acpx harness, Plugin, і дозволів
## Середовище acpx, налаштування плагіна та дозволи
Для конфігурації acpx harness (псевдоніми Claude Code / Codex / Gemini CLI),
MCP-мостів plugin-tools і OpenClaw-tools, а також режимів дозволів ACP див.
Щодо конфігурації середовища acpx (псевдоніми Claude Code / Codex / Gemini CLI), MCP-мостів plugin-tools і OpenClaw-tools, а також режимів дозволів ACP див.
[Агенти ACP — налаштування](/uk/tools/acp-agents-setup).
## Усунення несправностей
## Усунення неполадок
| Симптом | Імовірна причина | Виправлення |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ACP runtime backend is not configured` | Плагін бекенда відсутній, вимкнений або заблокований через `plugins.allow`. | Установіть і ввімкніть плагін бекенда, додайте `acpx` до `plugins.allow`, якщо цей allowlist задано, а потім запустіть `/acp doctor`. |
| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Установіть `acp.enabled=true`. |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Диспетчеризацію зі звичайних повідомлень треду вимкнено. | Установіть `acp.dispatch.enabled=true`. |
| `ACP agent "<id>" is not allowed by policy` | Агент відсутній в allowlist. | Використовуйте дозволений `agentId` або оновіть `acp.allowedAgents`. |
| `Unable to resolve session target: ...` | Неправильний токен key/id/label. | Запустіть `/acp sessions`, скопіюйте точний key/label і повторіть спробу. |
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, яку можна прив’язати. | Перейдіть до цільового чату/каналу та повторіть спробу або використайте запуск без прив’язки. |
| `Conversation bindings are unavailable for <channel>.` | Адаптер не підтримує ACP-прив’язку до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, якщо це підтримується, налаштуйте верхньорівневі `bindings[]` або перейдіть до підтримуваного каналу. |
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом треду. | Перейдіть до цільового треду або використовуйте `--thread auto`/`off`. |
| `Only <user-id> can rebind this channel/conversation/thread.` | Активна ціль прив’язки належить іншому користувачеві. | Переприв’яжіть як власник або використайте іншу розмову чи тред. |
| `Thread bindings are unavailable for <channel>.` | Адаптер не підтримує прив’язку до тредів. | Використовуйте `--thread off` або перейдіть до підтримуваного адаптера/каналу. |
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP runtime працює на боці хоста; сеанс ініціатора виконується в sandbox. | Використовуйте `runtime="subagent"` із сеансів у sandbox або запускайте ACP із сеансу поза sandbox. |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для ACP runtime запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкового sandbox або ACP із `sandbox="inherit"` із сеансу поза sandbox. |
| `Cannot apply --model ... did not advertise model support` | Цільовий harness не надає загального перемикання моделей ACP. | Використовуйте harness, який оголошує ACP `models`/`session/set_model`, використовуйте посилання на моделі Codex ACP або налаштуйте модель безпосередньо в harness, якщо він має власний прапорець запуску. |
| Missing ACP metadata for bound session | Застарілі/видалені метадані сеансу ACP. | Створіть його заново через `/acp spawn`, а потім знову прив’яжіть/сфокусуйте тред. |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує записи/виконання в неінтерактивному сеансі ACP. | Установіть `plugins.entries.acpx.config.permissionMode` в `approve-all` і перезапустіть gateway. Див. [Конфігурація дозволів](/uk/tools/acp-agents-setup#permission-configuration). |
| ACP session fails early with little output | Запити дозволів блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних дозволів установіть `permissionMode=approve-all`; для коректної деградації встановіть `nonInteractivePermissions=deny`. |
| ACP session stalls indefinitely after completing work | Процес harness завершився, але сеанс ACP не повідомив про завершення. | Відстежуйте через `ps aux \| grep acpx`; вручну завершіть застарілі процеси. |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ACP runtime backend is not configured` | Бекенд-плагін відсутній, вимкнений або заблокований через `plugins.allow`. | Встановіть і ввімкніть бекенд-плагін, додайте `acpx` до `plugins.allow`, якщо цей список дозволів задано, а потім запустіть `/acp doctor`. |
| `ACP is disabled by policy (acp.enabled=false)` | ACP глобально вимкнено. | Установіть `acp.enabled=true`. |
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | Диспетчеризацію зі звичайних повідомлень гілки вимкнено. | Установіть `acp.dispatch.enabled=true`. |
| `ACP agent "<id>" is not allowed by policy` | Агента немає в списку дозволів. | Використайте дозволений `agentId` або оновіть `acp.allowedAgents`. |
| `Unable to resolve session target: ...` | Неправильний токен key/id/label. | Виконайте `/acp sessions`, скопіюйте точний key/label і повторіть спробу. |
| `--bind here requires running /acp spawn inside an active ... conversation` | `--bind here` використано без активної розмови, до якої можна прив’язатися. | Перейдіть до цільового чату/каналу й повторіть спробу або використайте запуск без прив’язки. |
| `Conversation bindings are unavailable for <channel>.` | Адаптер не підтримує ACP-прив’язку до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте `bindings[]` верхнього рівня або перейдіть до підтримуваного каналу. |
| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом гілки. | Перейдіть до цільової гілки або використайте `--thread auto`/`off`. |
| `Only <user-id> can rebind this channel/conversation/thread.` | Інший користувач володіє активною ціллю прив’язки. | Переприв’яжіть як власник або використайте іншу розмову чи гілку. |
| `Thread bindings are unavailable for <channel>.` | Адаптер не підтримує прив’язку до гілок. | Використайте `--thread off` або перейдіть до підтримуваного адаптера/каналу. |
| `Sandboxed sessions cannot spawn ACP sessions ...` | Runtime ACP працює на хості; сеанс-запитувач є sandboxed. | Використовуйте `runtime="subagent"` із sandboxed-сеансів або запускайте ACP зі сеансу без sandbox. |
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | Для runtime ACP запитано `sandbox="require"`. | Використовуйте `runtime="subagent"` для обов’язкового sandbox або використовуйте ACP із `sandbox="inherit"` зі сеансу без sandbox. |
| `Cannot apply --model ... did not advertise model support` | Цільове середовище не надає загального перемикання моделей ACP. | Використовуйте середовище, яке оголошує ACP `models`/`session/set_model`, використовуйте посилання на моделі Codex ACP або налаштуйте модель безпосередньо в середовищі, якщо воно має власний стартовий прапорець. |
| Missing ACP metadata for bound session | Застарілі/видалені метадані сеансу ACP. | Створіть сеанс заново через `/acp spawn`, а потім повторно прив’яжіть/сфокусуйте гілку. |
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` блокує запис/виконання в неінтерактивному сеансі ACP. | Установіть `plugins.entries.acpx.config.permissionMode` у `approve-all` і перезапустіть gateway. Див. [Налаштування дозволів](/uk/tools/acp-agents-setup#permission-configuration). |
| ACP session fails early with little output | Запити дозволів блокуються через `permissionMode`/`nonInteractivePermissions`. | Перевірте журнали gateway на `AcpRuntimeError`. Для повних дозволів установіть `permissionMode=approve-all`; для контрольованого деградування встановіть `nonInteractivePermissions=deny`. |
| ACP session stalls indefinitely after completing work | Процес середовища завершився, але сеанс ACP не повідомив про завершення. | Відстежуйте через `ps aux \| grep acpx`; вручну завершіть завислі процеси. |
## Пов’язане
## Пов’язано
- [Субагенти](/uk/tools/subagents)
- [Інструменти sandbox для кількох агентів](/uk/tools/multi-agent-sandbox-tools)
- [Інструменти sandbox для мультиагентності](/uk/tools/multi-agent-sandbox-tools)
- [Надсилання агенту](/uk/tools/agent-send)

429
docs/uk/tools/plugin.md
View File

@ -1,25 +1,21 @@
---
read_when:
- Встановлення або налаштування плагінів
- Розуміння правил виявлення та завантаження плагінів
- Робота з сумісними з Codex/Claude пакетами плагінів
- Встановлення або налаштування Plugins
- Розуміння правил виявлення та завантаження Plugins
- Робота з сумісними з Codex/Claude пакетами Plugins
sidebarTitle: Install and Configure
summary: Встановлення, налаштування та керування плагінами OpenClaw
title: Плагіни
summary: Встановлення, налаштування та керування Plugins OpenClaw
title: Plugins
x-i18n:
generated_at: "2026-04-25T19:49:09Z"
generated_at: "2026-04-26T00:19:26Z"
model: gpt-5.4
provider: openai
source_hash: bbc819fc29f0bf58fce83223e43e2ddba3f199c71c6536e900ac6032f181d770
source_hash: 553c70416b9787437d46b3bd6f35570e532a3694c6c52d5d70e5014beed4328a
source_path: tools/plugin.md
workflow: 15
---
Плагіни розширюють OpenClaw новими можливостями: канали, постачальники моделей,
середовища агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному
часі, розуміння медіа, генерація зображень, генерація відео, веб-отримання, веб-
пошук тощо. Деякі плагіни є **core** (постачаються з OpenClaw), інші —
**external** (опубліковані спільнотою в npm).
Plugins розширюють OpenClaw новими можливостями: канали, постачальники моделей, середовища виконання агентів, інструменти, Skills, мовлення, розпізнавання мовлення в реальному часі, голос у реальному часі, розуміння медіа, генерація зображень, генерація відео, отримання вебданих, вебпошук тощо. Деякі Plugins є **core** (постачаються з OpenClaw), інші — **external** (опубліковані спільнотою в npm).
## Швидкий старт
@ -30,7 +26,7 @@ x-i18n:
```
</Step>
<Step title="Встановіть плагін">
<Step title="Встановіть Plugin">
```bash
# З npm
openclaw plugins install @openclaw/voice-call
@ -52,7 +48,7 @@ x-i18n:
</Step>
</Steps>
Якщо ви віддаєте перевагу керуванню безпосередньо в чаті, увімкніть `commands.plugins: true` і використовуйте:
Якщо ви надаєте перевагу керуванню через чат, увімкніть `commands.plugins: true` і використовуйте:
```text
/plugin install clawhub:@openclaw/voice-call
@ -60,43 +56,42 @@ x-i18n:
/plugin enable voice-call
```
Шлях встановлення використовує той самий механізм розв’язання, що й CLI: локальний
шлях/архів, явний `clawhub:<pkg>` або специфікація пакета без префікса (спочатку ClawHub, потім резервний перехід на npm).
Шлях встановлення використовує той самий механізм розв’язання, що й CLI: локальний шлях/архів, явний
`clawhub:<pkg>` або специфікація пакета без префікса (спочатку ClawHub, потім резервний варіант через npm).
Якщо конфігурація некоректна, встановлення зазвичай безпечно завершується відмовою і пропонує
скористатися `openclaw doctor --fix`. Єдиний виняток для відновлення — це вузький шлях
перевстановлення вбудованого плагіна для плагінів, які підтримують
Якщо конфігурація невалідна, встановлення зазвичай безпечно завершується відмовою й спрямовує вас до
`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення вбудованого Plugin
для Plugins, які підтримують
`openclaw.install.allowInvalidConfigRecovery`.
Пакетні встановлення OpenClaw не встановлюють завчасно все дерево залежностей середовища виконання кожного вбудованого плагіна.
Коли вбудований плагін, що належить OpenClaw, активний через
конфігурацію плагіна, застарілу конфігурацію каналу або маніфест, увімкнений за замовчуванням,
під час запуску відновлюються лише оголошені цим плагіном залежності середовища виконання перед його імпортом.
Пакетні інсталяції OpenClaw не встановлюють наперед усе дерево залежностей середовища виконання кожного вбудованого Plugin.
Коли вбудований Plugin від OpenClaw активний через конфігурацію Plugin, застарілу конфігурацію каналу або маніфест
із увімкненням за замовчуванням, під час запуску відновлюються лише оголошені залежності середовища виконання цього Plugin перед його імпортом.
Явне вимкнення все одно має пріоритет: `plugins.entries.<id>.enabled: false`,
`plugins.deny`, `plugins.enabled: false` і `channels.<id>.enabled: false`
запобігають автоматичному відновленню залежностей середовища виконання для цього плагіна/каналу.
External-плагіни та користувацькі шляхи завантаження, як і раніше, потрібно встановлювати через
запобігають автоматичному відновленню залежностей середовища виконання для цього Plugin/каналу.
External Plugins і власні шляхи завантаження, як і раніше, потрібно встановлювати через
`openclaw plugins install`.
## Типи плагінів
## Типи Plugins
OpenClaw розпізнає два формати плагінів:
OpenClaw розпізнає два формати Plugins:
| Формат | Як це працює | Приклади |
| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
| **Native** | `openclaw.plugin.json` + модуль середовища виконання; виконується в тому ж процесі | Офіційні плагіни, пакети npm від спільноти |
| **Bundle** | Сумісне з Codex/Claude/Cursor компонування; відображається на можливості OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
| **Native** | `openclaw.plugin.json` + модуль середовища виконання; виконується в поточному процесі | Офіційні Plugins, пакети npm від спільноти |
| **Bundle** | Сумісне з Codex/Claude/Cursor компонування; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
Обидва відображаються в `openclaw plugins list`. Докладніше про пакети див. у [Plugin Bundles](/uk/plugins/bundles).
Обидва відображаються в `openclaw plugins list`. Докладніше про bundles див. у [Пакети Plugins](/uk/plugins/bundles).
Якщо ви пишете native-плагін, почніть із [Building Plugins](/uk/plugins/building-plugins)
та [Plugin SDK Overview](/uk/plugins/sdk-overview).
Якщо ви пишете native Plugin, почніть із [Створення Plugins](/uk/plugins/building-plugins)
і [Огляду Plugin SDK](/uk/plugins/sdk-overview).
## Офіційні плагіни
## Офіційні Plugins
### Встановлювані (npm)
### Доступні для встановлення (npm)
| Плагін | Пакет | Документація |
| Plugin | Пакет | Документація |
| --------------- | --------------------- | ------------------------------------ |
| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) |
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) |
@ -116,9 +111,9 @@ OpenClaw розпізнає два формати плагінів:
`vercel-ai-gateway`, `volcengine`, `xiaomi`, `zai`
</Accordion>
<Accordion title="Плагіни пам’яті">
<Accordion title="Plugins пам’яті">
- `memory-core` — вбудований пошук у пам’яті (типово через `plugins.slots.memory`)
- `memory-lancedb` — довгострокова пам’ять із встановленням за потреби та автоматичним пригадуванням/захопленням (встановіть `plugins.slots.memory = "memory-lancedb"`)
- `memory-lancedb` — довготривала пам’ять із встановленням за потреби та автоматичним пригадуванням/захопленням (установіть `plugins.slots.memory = "memory-lancedb"`)
</Accordion>
<Accordion title="Постачальники мовлення (увімкнені за замовчуванням)">
@ -126,12 +121,12 @@ OpenClaw розпізнає два формати плагінів:
</Accordion>
<Accordion title="Інше">
- `browser` — вбудований browser-плагін для browser tool, CLI `openclaw browser`, методу Gateway `browser.request`, browser runtime та служби керування браузером за замовчуванням (увімкнений за замовчуванням; вимкніть його перед заміною)
- `browser` — вбудований browser Plugin для інструмента браузера, CLI `openclaw browser`, методу Gateway `browser.request`, середовища виконання браузера та стандартної служби керування браузером (увімкнений за замовчуванням; вимкніть його перед заміною)
- `copilot-proxy` — міст VS Code Copilot Proxy (вимкнений за замовчуванням)
</Accordion>
</AccordionGroup>
Шукаєте сторонні плагіни? Див. [Community Plugins](/uk/plugins/community).
Шукаєте сторонні Plugins? Див. [Plugins спільноти](/uk/plugins/community).
## Конфігурація
@ -152,142 +147,174 @@ OpenClaw розпізнає два формати плагінів:
| Поле | Опис |
| ---------------- | --------------------------------------------------------- |
| `enabled` | Головний перемикач (типово: `true`) |
| `allow` | Список дозволених плагінів (необов’язково) |
| `deny` | Список заборонених плагінів (необов’язково; deny має пріоритет) |
| `load.paths` | Додаткові файли/каталоги плагінів |
| `allow` | Список дозволених Plugins (необов’язково) |
| `deny` | Список заборонених Plugins (необов’язково; deny має пріоритет) |
| `load.paths` | Додаткові файли/каталоги Plugins |
| `slots` | Селектори ексклюзивних слотів (наприклад, `memory`, `contextEngine`) |
| `entries.\<id\>` | Перемикачі та конфігурація для окремого плагіна |
| `entries.\<id\>` | Перемикачі та конфігурація для окремого Plugin |
Зміни конфігурації **потребують перезапуску Gateway**. Якщо Gateway запущено з
відстеженням конфігурації та перезапуском у процесі (типовий шлях `openclaw gateway`),
такий перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації.
Підтримуваного шляху hot-reload для коду native-плагінів або хуків життєвого циклу немає;
перезапустіть процес Gateway, який обслуговує активний канал, перш ніж
очікувати, що оновлений код `register(api)`, хуки `api.on(...)`, інструменти, служби або
хуки постачальника/runtime почнуть виконуватися.
Зміни конфігурації **потребують перезапуску gateway**. Якщо Gateway працює з
відстеженням конфігурації та внутрішньопроцесним перезапуском (типовий шлях `openclaw gateway`),
цей перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації.
Підтримуваного шляху гарячого перезавантаження для native коду середовища виконання Plugin або хуків життєвого циклу немає;
перезапустіть процес Gateway, який обслуговує активний канал, перш ніж очікувати, що оновлений код `register(api)`,
хуки `api.on(...)`, інструменти, служби або хук-и постачальника/середовища виконання почнуть працювати.
`openclaw plugins list` — це локальний знімок реєстру/конфігурації плагінів. Плагін зі
станом `enabled` там означає, що збережений реєстр і поточна конфігурація дозволяють
йому брати участь. Це не доводить, що вже запущений дочірній процес віддаленого Gateway
перезапустився з тим самим кодом плагіна. У VPS/контейнерних конфігураціях із
процесами-обгортками надсилайте перезапуск фактичному процесу `openclaw gateway run`,
або використовуйте `openclaw gateway restart` для запущеного Gateway.
`openclaw plugins list` — це локальний знімок реєстру/конфігурації Plugins. Позначка
`enabled` для Plugin означає, що збережений реєстр і поточна конфігурація дозволяють
Plugin брати участь у роботі. Це не доводить, що вже запущений віддалений дочірній процес Gateway
було перезапущено з тим самим кодом Plugin. У середовищах VPS/контейнерів із
процесами-обгортками надсилайте перезапуск реальному процесу `openclaw gateway run`,
або використовуйте `openclaw gateway restart` щодо запущеного Gateway.
<Accordion title="Стани плагіна: вимкнений, відсутній, некоректний">
- **Disabled**: плагін існує, але правила увімкнення його вимкнули. Конфігурація зберігається.
- **Missing**: конфігурація посилається на ідентифікатор плагіна, який не було знайдено під час виявлення.
- **Invalid**: плагін існує, але його конфігурація не відповідає оголошеній схемі.
<Accordion title="Стани Plugins: disabled vs missing vs invalid">
- **Disabled**: Plugin існує, але правила ввімкнення його вимкнули. Конфігурація зберігається.
- **Missing**: конфігурація посилається на ідентифікатор Plugin, який не знайдено під час виявлення.
- **Invalid**: Plugin існує, але його конфігурація не відповідає оголошеній схемі.
</Accordion>
## Виявлення та пріоритет
## Виявлення та пріоритетність
OpenClaw сканує плагіни в такому порядку (перше збіг — пріоритетний):
OpenClaw сканує Plugins у такому порядку (перше збігання має пріоритет):
<Steps>
<Step title="Шляхи з конфігурації">
<Step title="Шляхи конфігурації">
`plugins.load.paths` — явні шляхи до файлів або каталогів.
</Step>
<Step title="Плагіни робочого простору">
<Step title="Plugins робочого простору">
`\<workspace\>/.openclaw/<plugin-root>/*.ts` і `\<workspace\>/.openclaw/<plugin-root>/*/index.ts`.
</Step>
<Step title="Глобальні плагіни">
<Step title="Глобальні Plugins">
`~/.openclaw/<plugin-root>/*.ts` і `~/.openclaw/<plugin-root>/*/index.ts`.
</Step>
<Step title="Вбудовані плагіни">
Постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (постачальники моделей, мовлення).
<Step title="Вбудовані Plugins">
Постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (постачальники моделей, мовлення).
Інші потребують явного ввімкнення.
</Step>
</Steps>
### Правила увімкнення
### Правила ввімкнення
- `plugins.enabled: false` вимикає всі плагіни
- `plugins.enabled: false` вимикає всі Plugins
- `plugins.deny` завжди має пріоритет над allow
- `plugins.entries.\<id\>.enabled: false` вимикає цей плагін
- Плагіни з робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути)
- Вбудовані плагіни дотримуються вбудованого набору, увімкненого за замовчуванням, якщо його не перевизначено
- Ексклюзивні слоти можуть примусово ввімкнути вибраний для цього слота плагін
- Деякі вбудовані плагіни з режимом opt-in вмикаються автоматично, коли конфігурація вказує поверхню, що належить плагіну,
наприклад посилання на модель постачальника, конфігурацію каналу або
runtime середовища
- Маршрути Codex родини OpenAI зберігають окремі межі плагінів:
`openai-codex/*` належить плагіну OpenAI, тоді як вбудований плагін
app-server Codex вибирається через `embeddedHarness.runtime: "codex"` або застарілі
посилання на моделі `codex/*`
- `plugins.entries.\<id\>.enabled: false` вимикає цей Plugin
- Plugins з походженням із робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути)
- Вбудовані Plugins дотримуються вбудованого набору за замовчуванням, якщо не перевизначено
- Ексклюзивні слоти можуть примусово ввімкнути вибраний Plugin для цього слота
- Деякі вбудовані Plugins з явним opt-in вмикаються автоматично, коли конфігурація називає
поверхню, що належить Plugin, наприклад посилання на модель постачальника, конфігурацію каналу або
середовище виконання harness
- Маршрути Codex сімейства OpenAI зберігають окремі межі Plugins:
`openai-codex/*` належить Plugin OpenAI, тоді як вбудований Plugin сервера застосунку Codex
вибирається через `embeddedHarness.runtime: "codex"` або застарілі
посилання на модель `codex/*`
## Усунення проблем із хуками середовища виконання
Якщо плагін з’являється в `plugins list`, але побічні ефекти `register(api)` або хуки
не виконуються в трафіку живого чату, спочатку перевірте таке:
Якщо Plugin відображається в `plugins list`, але побічні ефекти `register(api)` або хуки
не працюють у трафіку активного чату, спочатку перевірте таке:
- Запустіть `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні
URL Gateway, профіль, шлях до конфігурації та процес — саме ті, які ви редагуєте.
- Перезапустіть активний Gateway після встановлення/зміни конфігурації/зміни коду плагіна. У контейнерах
URL Gateway, профіль, шлях конфігурації та процес — саме ті, які ви редагуєте.
- Перезапустіть активний Gateway після змін установлення/конфігурації/коду Plugin. У контейнерах
з обгортками PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому
процесу `openclaw gateway run`.
- Використовуйте `openclaw plugins inspect <id> --json`, щоб підтвердити реєстрації хуків і
діагностику. Для невбудованих розмовних хуків, таких як `llm_input`,
`llm_output` і `agent_end`, потрібен
- Використайте `openclaw plugins inspect <id> --json`, щоб підтвердити реєстрацію хуків і
діагностику. Невбудовані хуки діалогу, такі як `llm_input`,
`llm_output` і `agent_end`, потребують
`plugins.entries.<id>.hooks.allowConversationAccess=true`.
- Для перемикання моделей надавайте перевагу `before_model_resolve`. Цей хук виконується до
розв’язання моделі для ходів агента; `llm_output` виконується лише після того, як спроба
моделі створить відповідь асистента.
- Для перемикання моделей віддавайте перевагу `before_model_resolve`. Він виконується до
розв’язання моделі для ходів агента; `llm_output` виконується лише після того, як спроба моделі
створює вивід помічника.
- Щоб підтвердити фактичну модель сеансу, використовуйте `openclaw sessions` або
поверхні сеансу/стану Gateway, а під час налагодження навантажень постачальника запускайте
Gateway з `--raw-stream --raw-stream-path <path>`.
## Слоти плагінів (ексклюзивні категорії)
### Дублювання володіння каналом або інструментом
Деякі категорії є ексклюзивними (одночасно може бути активним лише один):
Симптоми:
- `channel already registered: <channel-id> (<plugin-id>)`
- `channel setup already registered: <channel-id> (<plugin-id>)`
- `plugin tool name conflict (<plugin-id>): <tool-name>`
Це означає, що більш ніж один увімкнений Plugin намагається володіти тим самим каналом,
потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній Plugin каналу,
установлений поруч із вбудованим Plugin, який тепер надає той самий ідентифікатор каналу.
Кроки налагодження:
- Запустіть `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений Plugin
і його походження.
- Запустіть `openclaw plugins inspect <id> --json` для кожного підозрюваного Plugin і
порівняйте `channels`, `channelConfigs`, `tools` і діагностику.
- Запустіть `openclaw plugins registry --refresh` після встановлення або видалення
пакетів Plugin, щоб збережені метадані відображали поточне встановлення.
- Перезапустіть Gateway після змін установлення, реєстру або конфігурації.
Варіанти виправлення:
- Якщо один Plugin навмисно замінює інший для того самого ідентифікатора каналу,
бажаний Plugin має оголошувати `channelConfigs.<channel-id>.preferOver` із
ідентифікатором Plugin нижчого пріоритету. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin).
- Якщо дублювання випадкове, вимкніть одну зі сторін через
`plugins.entries.<plugin-id>.enabled: false` або видаліть застаріле встановлення Plugin.
- Якщо ви явно ввімкнули обидва Plugins, OpenClaw зберігає цей запит і
повідомляє про конфлікт. Виберіть одного власника для каналу або перейменуйте інструменти, що належать Plugin,
щоб поверхня середовища виконання була однозначною.
## Слоти Plugins (ексклюзивні категорії)
Деякі категорії є ексклюзивними (одночасно активний лише один):
```json5
{
plugins: {
slots: {
memory: "memory-core", // або "none", щоб вимкнути
contextEngine: "legacy", // або id плагіна
contextEngine: "legacy", // або ідентифікатор Plugin
},
},
}
```
| Слот | Що він контролює | Типове значення |
| --------------- | ------------------------- | ------------------- |
| `memory` | Active Memory плагін | `memory-core` |
| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) |
| Слот | Що він контролює | Значення за замовчуванням |
| --------------- | ----------------------- | ------------------------- |
| `memory` | Active Memory Plugin | `memory-core` |
| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) |
## Довідник CLI
```bash
openclaw plugins list # компактний список
openclaw plugins list --enabled # лише увімкнені плагіни
openclaw plugins list --verbose # докладні рядки для кожного плагіна
openclaw plugins list --json # машиночитаний список
openclaw plugins inspect <id> # докладна інформація
openclaw plugins inspect <id> --json # машиночитаний формат
openclaw plugins inspect --all # таблиця для всіх
openclaw plugins info <id> # псевдонім для inspect
openclaw plugins list --enabled # лише увімкнені Plugins
openclaw plugins list --verbose # детальні рядки для кожного Plugin
openclaw plugins list --json # машиночитний список
openclaw plugins inspect <id> # детальна інформація
openclaw plugins inspect <id> --json # машиночитний формат
openclaw plugins inspect --all # таблиця для всього набору
openclaw plugins info <id> # псевдонім inspect
openclaw plugins doctor # діагностика
openclaw plugins registry # перевірка збереженого стану реєстру
openclaw plugins registry # перегляд збереженого стану реєстру
openclaw plugins registry --refresh # перебудувати збережений реєстр
openclaw doctor --fix # виправити стан міграції реєстру/журналу
openclaw doctor --fix # відновити стан реєстру Plugin
openclaw plugins install <package> # встановити (спочатку ClawHub, потім npm)
openclaw plugins install clawhub:<pkg> # встановити лише з ClawHub
openclaw plugins install <spec> --force # перезаписати наявне встановлення
openclaw plugins install <path> # встановити з локального шляху
openclaw plugins install -l <path> # підключити (без копіювання) для розробки
openclaw plugins install -l <path> # прив’язати (без копіювання) для розробки
openclaw plugins install <plugin> --marketplace <source>
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
openclaw plugins install <spec> --pin # зберегти точну розв’язану npm-специфікацію
openclaw plugins install <spec> --pin # записати точну розв’язану специфікацію npm
openclaw plugins install <spec> --dangerously-force-unsafe-install
openclaw plugins update <id-or-npm-spec> # оновити один плагін
openclaw plugins update <id-or-npm-spec> # оновити один Plugin
openclaw plugins update <id-or-npm-spec> --dangerously-force-unsafe-install
openclaw plugins update --all # оновити всі
openclaw plugins uninstall <id> # видалити записи конфігурації та журналу встановлення
openclaw plugins uninstall <id> # видалити конфігурацію та записи індексу Plugin
openclaw plugins uninstall <id> --keep-files
openclaw plugins marketplace list <source>
openclaw plugins marketplace list <source> --json
@ -296,69 +323,67 @@ openclaw plugins enable <id>
openclaw plugins disable <id>
```
Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад,
вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований browser-
плагін). Інші вбудовані плагіни все ще потребують `openclaw plugins enable <id>`.
Вбудовані Plugins постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад,
вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований browser
Plugin). Інші вбудовані Plugins усе ще потрібно вмикати через `openclaw plugins enable <id>`.
`--force` перезаписує наявний встановлений плагін або набір хуків на місці. Для
звичайних оновлень відстежуваних npm-плагінів використовуйте
`openclaw plugins update <id-or-npm-spec>`. Цей параметр не підтримується з `--link`, який повторно використовує вихідний шлях
`--force` перезаписує наявний встановлений Plugin або набір hooks на місці. Використовуйте
`openclaw plugins update <id-or-npm-spec>` для звичайних оновлень відстежуваних npm
Plugins. Цей прапорець не підтримується разом із `--link`, який повторно використовує вихідний шлях
замість копіювання в керовану ціль встановлення.
Коли `plugins.allow` уже встановлено, `openclaw plugins install` додає
ідентифікатор встановленого плагіна до цього списку дозволених перед його ввімкненням, тож встановлені плагіни
можна завантажувати одразу після перезапуску.
ідентифікатор встановленого Plugin до цього списку дозволених перед його ввімкненням, тому встановлені Plugins
можна одразу завантажувати після перезапуску.
OpenClaw зберігає локальний реєстр плагінів як модель холодного читання для
інвентаризації плагінів, володіння внесками та планування запуску. Потоки встановлення, оновлення,
OpenClaw підтримує збережений локальний реєстр Plugins як модель холодного читання для
обліку Plugins, визначення власності внесків і планування запуску. Потоки встановлення, оновлення,
видалення, увімкнення та вимкнення оновлюють цей реєстр після зміни стану
плагіна. Якщо реєстр відсутній, застарів або некоректний, `openclaw plugins registry
--refresh` перебудовує його на основі довговічного журналу встановлень, політики конфігурації та
метаданих маніфесту/пакета без завантаження модулів середовища виконання плагіна.
Якщо на машині все ще є застарілі записи `plugins.installs` у конфігурації, виконайте
`openclaw doctor --fix`, щоб перемістити їх у керований
журнал `plugins/installs.json` і видалити копію з конфігурації.
Plugin. Той самий файл `plugins/installs.json` зберігає довговічні метадані встановлення в
верхньорівневих `installRecords` і перебудовувані метадані маніфесту в `plugins`. Якщо
реєстр відсутній, застарілий або невалідний, `openclaw plugins registry
--refresh` перебудовує його подання маніфесту з записів встановлення, політики конфігурації та
метаданих маніфесту/пакета без завантаження модулів середовища виконання Plugin.
`openclaw plugins update <id-or-npm-spec>` застосовується до відстежуваних встановлень. Передавання
npm-специфікації пакета з dist-tag або точною версією розв’язує назву пакета
назад до запису відстежуваного плагіна та зберігає нову специфікацію для майбутніх оновлень.
Передавання назви пакета без версії переводить точно закріплене встановлення назад на
типову лінію релізів реєстру. Якщо встановлений npm-плагін уже відповідає
розв’язаній версії та збереженій ідентичності артефакту, OpenClaw пропускає оновлення
без завантаження, перевстановлення чи перезапису конфігурації.
специфікації npm-пакета з dist-tag або точною версією розв’язує назву пакета
назад до запису відстежуваного Plugin і записує нову специфікацію для майбутніх оновлень.
Передавання назви пакета без версії повертає точно закріплене встановлення назад на
типову лінію випуску реєстру. Якщо встановлений npm Plugin уже відповідає
розв’язаній версії та записаній ідентичності артефакту, OpenClaw пропускає оновлення
без завантаження, перевстановлення або переписування конфігурації.
`--pin` призначений лише для npm. Він не підтримується з `--marketplace`, оскільки
встановлення з marketplace зберігають метадані джерела marketplace замість npm-специфікації.
`--pin` працює лише з npm. Він не підтримується разом із `--marketplace`, оскільки
встановлення з marketplace зберігають метадані джерела marketplace замість специфікації npm.
`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибнопозитивних
спрацювань вбудованого сканера небезпечного коду. Воно дозволяє встановленням і оновленням плагінів
продовжуватися попри вбудовані результати `critical`, але все одно
не обходить блокування політики плагіна `before_install` або блокування через помилку сканування.
спрацювань вбудованого сканера небезпечного коду. Воно дозволяє встановленням Plugin
та оновленням Plugin продовжуватися попри вбудовані результати рівня `critical`, але все одно
не обходить блокування політики Plugin `before_install` або блокування через помилку сканування.
Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Встановлення залежностей Skills
через Gateway натомість використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install`
залишається окремим потоком завантаження/встановлення Skills з ClawHub.
Цей прапорець CLI застосовується лише до потоків встановлення/оновлення Plugin. Встановлення залежностей Skill
через Gateway натомість використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як
`openclaw skills install` залишається окремим потоком завантаження/встановлення Skill через ClawHub.
Сумісні пакети беруть участь у тому самому потоці list/inspect/enable/disable
для плагінів. Поточна підтримка середовища виконання включає bundle Skills, Claude command-skills,
типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошених у маніфесті
`lspServers`, Cursor command-skills і сумісні каталоги хуків Codex.
Сумісні bundles беруть участь у тому самому потоці list/inspect/enable/disable для Plugins.
Поточна підтримка середовища виконання включає bundle Skills, command-skills Claude,
типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і
`lspServers`, оголошені в маніфесті, command-skills Cursor та сумісні каталоги hooks Codex.
`openclaw plugins inspect <id>` також повідомляє про виявлені можливості пакета, а також
підтримувані або непідтримувані записи серверів MCP і LSP для плагінів на основі пакетів.
`openclaw plugins inspect <id>` також повідомляє про виявлені можливості bundle, а також
підтримувані або непідтримувані записи серверів MCP і LSP для Plugins на основі bundle.
Джерелами marketplace можуть бути відома назва Claude marketplace з
`~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях до
`marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL GitHub-репозиторію або URL git. Для віддалених marketplace
записи плагінів мають залишатися всередині клонованого репозиторію marketplace і використовувати лише
відносні шляхи як джерела.
Джерела marketplace можуть бути відомою назвою marketplace Claude з
`~/.claude/plugins/known_marketplaces.json`, локальним коренем marketplace або шляхом
`marketplace.json`, скороченим позначенням GitHub на кшталт `owner/repo`, URL репозиторію GitHub
або URL git. Для віддалених marketplace записи Plugin мають залишатися в межах
клонованого репозиторію marketplace та використовувати лише відносні джерела шляхів.
Повні відомості див. у [довіднику CLI `openclaw plugins`](/uk/cli/plugins).
## Огляд API плагінів
## Огляд API Plugin
Native-плагіни експортують об’єкт входу, який надає `register(api)`. Старіші
плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові плагіни мають
Native Plugins експортують об’єкт входу, який надає `register(api)`. Старіші
Plugins можуть усе ще використовувати `activate(api)` як застарілий псевдонім, але нові Plugins мають
використовувати `register`.
```typescript
@ -379,53 +404,53 @@ export default definePluginEntry({
});
```
OpenClaw завантажує об’єкт входу та викликає `register(api)` під час
активації плагіна. Завантажувач усе ще повертається до `activate(api)` для старіших плагінів,
але вбудовані плагіни та нові external-плагіни мають розглядати `register` як
OpenClaw завантажує об’єкт входу та викликає `register(api)` під час активації
Plugin. Завантажувач усе ще повертається до `activate(api)` для старіших Plugins,
але вбудовані Plugins і нові external Plugins мають розглядати `register` як
публічний контракт.
`api.registrationMode` повідомляє плагіну, чому завантажується його об’єкт входу:
`api.registrationMode` повідомляє Plugin, чому завантажується його об’єкт входу:
| Режим | Значення |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `full` | Активація середовища виконання. Реєструйте інструменти, хуки, служби, команди, маршрути та інші побічні ефекти в реальному часі. |
| `discovery` | Виявлення можливостей лише для читання. Реєструйте постачальників і метадані; код входу довіреного плагіна може завантажуватися, але пропускайте побічні ефекти реального часу. |
| `setup-only` | Завантаження метаданих налаштування каналу через полегшений об’єкт входу налаштування. |
| `setup-runtime` | Завантаження налаштування каналу, яке також потребує об’єкта входу середовища виконання. |
| `cli-metadata` | Лише збирання метаданих команди CLI. |
| `full` | Активація середовища виконання. Реєструє інструменти, hooks, сервіси, команди, маршрути та інші побічні ефекти в живому режимі. |
| `discovery` | Виявлення можливостей лише для читання. Реєструє постачальників і метадані; код входу довіреного Plugin може завантажуватися, але має пропускати побічні ефекти живого режиму. |
| `setup-only` | Завантаження метаданих налаштування каналу через полегшений об’єкт налаштування. |
| `setup-runtime` | Завантаження налаштування каналу, якому також потрібен об’єкт середовища виконання. |
| `cli-metadata` | Лише збирання метаданих команд CLI. |
Об’єкти входу плагінів, які відкривають сокети, бази даних, фонові воркери або довготривалі
клієнти, повинні захищати ці побічні ефекти умовою `api.registrationMode === "full"`.
Завантаження для виявлення кешуються окремо від завантажень активації та не замінюють
реєстр запущеного Gateway. Виявлення не активує, але й не є вільним від імпорту:
OpenClaw може обчислювати довірений об’єкт входу плагіна або модуль плагіна каналу, щоб побудувати
знімок. Тримайте верхні рівні модулів легкими та без побічних ефектів і переносьте
мережевих клієнтів, підпроцеси, слухачі, читання облікових даних і запуск служб
Об’єкти входу Plugin, які відкривають сокети, бази даних, фонові worker-и або довгоживучі
клієнти, мають захищати ці побічні ефекти перевіркою `api.registrationMode === "full"`.
Завантаження для discovery кешуються окремо від завантажень активації та не замінюють
реєстр запущеного Gateway. Discovery не активує, але й не є безімпортним:
OpenClaw може обчислювати довірений об’єкт входу Plugin або модуль Plugin каналу, щоб побудувати
знімок. Тримайте верхні рівні модулів легкими та без побічних ефектів і переносіть
мережеві клієнти, підпроцеси, слухачі, читання облікових даних і запуск сервісів
за шляхи повного середовища виконання.
Поширені методи реєстрації:
| Метод | Що він реєструє |
| -------------------------------------- | -------------------------- |
| `registerProvider` | Постачальник моделей (LLM) |
| `registerChannel` | Канал чату |
| `registerTool` | Інструмент агента |
| `registerHook` / `on(...)` | Хуки життєвого циклу |
| `registerSpeechProvider` | Перетворення тексту на мовлення / STT |
| `registerRealtimeTranscriptionProvider`| Потоковий STT |
| `registerRealtimeVoiceProvider` | Двоспрямований голос у реальному часі |
| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
| `registerImageGenerationProvider` | Генерація зображень |
| `registerMusicGenerationProvider` | Генерація музики |
| `registerVideoGenerationProvider` | Генерація відео |
| `registerWebFetchProvider` | Постачальник веб-отримання / скрапінгу |
| `registerWebSearchProvider` | Веб-пошук |
| `registerHttpRoute` | HTTP-ендпойнт |
| `registerCommand` / `registerCli` | Команди CLI |
| `registerContextEngine` | Рушій контексту |
| `registerService` | Фонова служба |
| --------------------------------------- | -------------------------- |
| `registerProvider` | Постачальник моделі (LLM) |
| `registerChannel` | Канал чату |
| `registerTool` | Інструмент агента |
| `registerHook` / `on(...)` | Hooks життєвого циклу |
| `registerSpeechProvider` | Синтез мовлення / STT |
| `registerRealtimeTranscriptionProvider` | Потоковий STT |
| `registerRealtimeVoiceProvider` | Двобічний голос у реальному часі |
| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
| `registerImageGenerationProvider` | Генерація зображень |
| `registerMusicGenerationProvider` | Генерація музики |
| `registerVideoGenerationProvider` | Генерація відео |
| `registerWebFetchProvider` | Постачальник отримання/скрапінгу вебданих |
| `registerWebSearchProvider` | Вебпошук |
| `registerHttpRoute` | HTTP endpoint |
| `registerCommand` / `registerCli` | Команди CLI |
| `registerContextEngine` | Рушій контексту |
| `registerService` | Фоновий сервіс |
Поведінка захисту хуків для типізованих хуків життєвого циклу:
Поведінка захисту hooks для типізованих hooks життєвого циклу:
- `before_tool_call`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування.
@ -434,20 +459,20 @@ OpenClaw може обчислювати довірений об’єкт вхо
- `message_sending`: `{ cancel: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування.
Native app-server Codex повертає події інструментів Codex-native назад у цю
поверхню хуків через міст. Плагіни можуть блокувати native-інструменти Codex через `before_tool_call`,
спостерігати за результатами через `after_tool_call` і брати участь у погодженнях
`PermissionRequest` Codex. Міст поки що не переписує аргументи
інструментів Codex-native. Точна межа підтримки середовища виконання Codex визначена в
Native сервер застосунку Codex повертає події інструментів Codex-native через цю
поверхню hooks. Plugins можуть блокувати native інструменти Codex через `before_tool_call`,
спостерігати результати через `after_tool_call` і брати участь у схваленнях
`PermissionRequest` Codex. Міст поки що не переписує аргументи native інструментів Codex.
Точна межа підтримки середовища виконання Codex описана в
[контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract).
Повну інформацію про типізовану поведінку хуків див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics).
Повну поведінку типізованих hooks див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics).
## Пов’язане
- [Building plugins](/uk/plugins/building-plugins) — створення власного плагіна
- [Plugin bundles](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor
- [Plugin manifest](/uk/plugins/manifest) — схема маніфесту
- [Registering tools](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента до плагіна
- [Plugin internals](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження
- [Community plugins](/uk/plugins/community) — списки сторонніх плагінів
- [Створення Plugins](/uk/plugins/building-plugins) — створіть власний Plugin
- [Пакети Plugins](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor
- [Маніфест Plugin](/uk/plugins/manifest) — схема маніфесту
- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента в Plugin
- [Внутрішня архітектура Plugin](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження
- [Plugins спільноти](/uk/plugins/community) — сторонні списки

418
docs/uk/tools/subagents.md
View File

@ -1,24 +1,24 @@
---
read_when:
- Ви хочете фонову/паралельну роботу через агента
- Ви змінюєте політику інструмента `sessions_spawn` або підагентів
- Ви реалізуєте або усуваєте проблеми із сесіями підагентів, прив’язаними до потоку
summary: 'Підагенти: запуск ізольованих виконань агентів, які повідомляють про результати назад у чат запитувача'
title: Підагенти
- Ви хочете фонову/паралельну роботу через agent
- Ви змінюєте політику інструмента sessions_spawn або sub-agent
- Ви реалізуєте або усуваєте несправності прив’язаних до потоку сесій subagent
summary: 'Sub-agents: запуск ізольованих виконань agent, які повідомляють результати назад у чат запитувача'
title: Sub-agents
x-i18n:
generated_at: "2026-04-25T23:38:40Z"
generated_at: "2026-04-26T00:20:14Z"
model: gpt-5.4
provider: openai
source_hash: 32e8d7fa427d006e10b0186b0d80a96ac1d1c2c0385f362006ee08dadd7a3ff3
source_hash: 190f2dd3b5465fc2f9026769a60d03862fc2dbadb1cb66bf1fe846a7148e1f3f
source_path: tools/subagents.md
workflow: 15
---
Підагенти — це фонові виконання агентів, запущені з наявного виконання агента. Вони працюють у власній сесії (`agent:<agentId>:subagent:<uuid>`) і після завершення **повідомляють** про свій результат назад у чат-канал запитувача. Кожне виконання підагента відстежується як [фонове завдання](/uk/automation/tasks).
Sub-agents — це фонові виконання agent, породжені з наявного виконання agent. Вони працюють у власній сесії (`agent:<agentId>:subagent:<uuid>`) і після завершення **повідомляють** про свій результат назад у канал чату запитувача. Кожне виконання sub-agent відстежується як [фонове завдання](/uk/automation/tasks).
## Команда зі скісною рискою
## Slash-команда
Використовуйте `/subagents`, щоб переглядати або керувати виконаннями підагентів для **поточної сесії**:
Використовуйте `/subagents`, щоб переглядати або керувати виконаннями sub-agent для **поточної сесії**:
- `/subagents list`
- `/subagents kill <id|#|all>`
@ -30,7 +30,7 @@ x-i18n:
Елементи керування прив’язкою до потоку:
Ці команди працюють у каналах, що підтримують постійні прив’язки до потоку. Див. **Канали з підтримкою потоків** нижче.
Ці команди працюють у каналах, які підтримують постійні прив’язки до потоку. Див. **Канали з підтримкою потоків** нижче.
- `/focus <subagent-label|session-key|session-id|session-label>`
- `/unfocus`
@ -38,114 +38,114 @@ x-i18n:
- `/session idle <duration|off>`
- `/session max-age <duration|off>`
`/subagents info` показує метадані виконання (статус, часові мітки, id сесії, шлях до транскрипту, очищення).
`/subagents info` показує метадані виконання (стан, часові мітки, ID сесії, шлях до транскрипту, очищення).
Використовуйте `sessions_history` для обмеженого, відфільтрованого з погляду безпеки перегляду історії; перевіряйте
шлях до транскрипту на диску, коли вам потрібен сирий повний транскрипт.
шлях до транскрипту на диску, коли вам потрібен повний сирий транскрипт.
### Поведінка запуску
### Поведінка spawn
`/subagents spawn` запускає фоновий підагент як команду користувача, а не як внутрішнє пересилання, і надсилає одне фінальне оновлення про завершення назад у чат запитувача, коли виконання закінчується.
`/subagents spawn` запускає фоновий sub-agent як команду користувача, а не як внутрішню relay-операцію, і надсилає одне фінальне оновлення про завершення назад у чат запитувача, коли виконання завершується.
- Команда запуску є неблокувальною; вона відразу повертає id виконання.
- Після завершення підагент повідомляє зведення/результат назад у чат-канал запитувача.
- Доставка після завершення є push-орієнтованою. Після запуску не опитуйте `/subagents list`,
`sessions_list` або `sessions_history` у циклі лише для очікування
завершення; перевіряйте статус лише за потреби для налагодження або втручання.
- Після завершення OpenClaw намагається закрити відстежувані вкладки/процеси браузера, відкриті цією сесією підагента, перш ніж продовжиться потік очищення після повідомлення.
- Для ручних запусків доставка є стійкою:
- Команда spawn є неблокувальною; вона одразу повертає ID виконання.
- Після завершення sub-agent повідомляє зведення/результат назад у канал чату запитувача.
- Доставка завершення ґрунтується на push-механізмі. Після запуску не опитуйте `/subagents list`,
`sessions_list` або `sessions_history` у циклі лише для того, щоб дочекатися
завершення; перевіряйте стан лише за потреби для налагодження або втручання.
- Після завершення OpenClaw у режимі best-effort закриває відстежувані вкладки/процеси браузера, відкриті цією сесією sub-agent, перш ніж продовжиться потік очищення після повідомлення.
- Для ручних spawn доставка є стійкою:
- OpenClaw спочатку намагається виконати пряму доставку `agent` зі стабільним ключем ідемпотентності.
- Якщо пряма доставка не вдається, він повертається до маршрутизації через чергу.
- Якщо маршрутизація через чергу також недоступна, повторна спроба повідомлення виконується з коротким експоненційним backoff перед остаточною відмовою.
- Доставка завершення зберігає визначений маршрут запитувача:
- Якщо пряма доставка не вдається, він переходить до резервної маршрутизації через чергу.
- Якщо маршрутизація через чергу все ще недоступна, повідомлення про завершення повторюється з короткою експоненційною затримкою перед остаточною відмовою.
- Доставка завершення зберігає розв’язаний маршрут запитувача:
- маршрути завершення, прив’язані до потоку або розмови, мають пріоритет, коли доступні
- якщо джерело завершення надає лише канал, OpenClaw заповнює відсутні `target`/обліковий запис із визначеного маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно працювала
- Передача завершення до сесії запитувача — це внутрішній контекст, згенерований під час виконання (а не текст, написаний користувачем), і він містить:
- `Result` (останній видимий текст відповіді `assistant`, інакше санітизований останній текст `tool`/`toolResult`; для термінально невдалих виконань захоплений текст відповіді не використовується повторно)
- якщо джерело завершення надає лише канал, OpenClaw заповнює відсутню ціль/акаунт із розв’язаного маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно працювала
- Передача завершення до сесії запитувача — це внутрішній контекст середовища виконання, згенерований під час виконання (а не текст, створений користувачем), і він включає:
- `Result` (останній видимий текст відповіді `assistant`, або, інакше, санітизований останній текст tool/toolResult; невдалі завершені виконання не використовують повторно захоплений текст відповіді)
- `Status` (`completed successfully` / `failed` / `timed out` / `unknown`)
- компактну статистику виконання/токенів
- інструкцію з доставки, яка вказує агенту запитувача переписати відповідь у звичайному голосі помічника (а не пересилати сирі внутрішні метадані)
- стиснуту статистику runtime/token
- інструкцію доставки, яка наказує agent запитувача переписати це у звичайному голосі assistant (а не пересилати сирі внутрішні метадані)
- `--model` і `--thinking` перевизначають типові значення для цього конкретного виконання.
- Використовуйте `info`/`log`, щоб переглядати деталі та вивід після завершення.
- `/subagents spawn` — це одноразовий режим (`mode: "run"`). Для постійних сесій, прив’язаних до потоку, використовуйте `sessions_spawn` із `thread: true` і `mode: "session"`.
- Для сесій ACP harness (Codex, Claude Code, Gemini CLI, OpenCode) використовуйте `sessions_spawn` із `runtime: "acp"`, коли інструмент оголошує цей runtime, і див. [ACP Agents](/uk/tools/acp-agents), особливо [модель доставки ACP](/uk/tools/acp-agents#delivery-model), коли налагоджуєте завершення або цикли агент-до-агента. OpenClaw приховує `runtime: "acp"`, доки ACP не увімкнено, запитувач не є ізольованим, а бекендовий Plugin, такий як `acpx`, не завантажено. `runtime: "acp"` очікує зовнішній id ACP harness або запис `agents.list[]` з `runtime.type="acp"`; використовуйте типовий runtime підагента для звичайних агентів конфігурації OpenClaw з `agents_list`.
- Використовуйте `info`/`log`, щоб переглянути деталі та вивід після завершення.
- `/subagents spawn` — це одноразовий режим (`mode: "run"`). Для постійних сесій, прив’язаних до потоку, використовуйте `sessions_spawn` з `thread: true` і `mode: "session"`.
- Для ACP harness sessions (Claude Code, Gemini CLI, OpenCode або явно Codex ACP/acpx) використовуйте `sessions_spawn` з `runtime: "acp"`, коли інструмент рекламує це runtime, і див. [ACP Agents](/uk/tools/acp-agents), особливо [модель доставки ACP](/uk/tools/acp-agents#delivery-model) під час налагодження завершень або циклів agent-to-agent. Коли Plugin `codex` увімкнено, для керування чатом/потоком Codex слід віддавати перевагу `/codex ...` замість ACP, якщо користувач явно не просить ACP/acpx. OpenClaw приховує `runtime: "acp"`, доки ACP не ввімкнено, запитувач не працює в sandbox і не завантажено backend Plugin, як-от `acpx`. `runtime: "acp"` очікує зовнішній ACP harness id або запис `agents.list[]` з `runtime.type="acp"`; використовуйте типове runtime sub-agent для звичайних agent конфігурації OpenClaw з `agents_list`.
Основні цілі:
- Паралелізувати роботу типу «дослідження / довге завдання / повільний інструмент» без блокування основного виконання.
- За замовчуванням зберігати ізоляцію підагентів (розділення сесій + необов’язкова ізоляція).
- Зберігати поверхню інструмента такою, щоб нею було важко неправильно користуватися: підагенти **не** отримують інструменти сесії за замовчуванням.
- Розпаралелювати роботу типу "дослідження / довге завдання / повільний інструмент", не блокуючи основне виконання.
- За замовчуванням зберігати ізоляцію sub-agent (розділення сесій + необов’язковий sandboxing).
- Зробити поверхню інструмента стійкою до неправильного використання: sub-agents **не** отримують інструменти сесій за замовчуванням.
- Підтримувати налаштовувану глибину вкладеності для шаблонів оркестрації.
Примітка щодо вартості: кожен підагент за замовчуванням має **власний** контекст і власне використання токенів. Для важких або
повторюваних завдань встановлюйте для підагентів дешевшу модель, а для основного агента залишайте
якіснішу модель. Це можна налаштувати через `agents.defaults.subagents.model` або перевизначення
для окремого агента. Коли дочірньому агенту справді потрібен поточний транскрипт запитувача, агент може запитати
`context: "fork"` для цього конкретного запуску.
Примітка про вартість: кожен sub-agent за замовчуванням має **власний** контекст і використання токенів. Для важких або
повторюваних завдань встановіть для sub-agents дешевшу модель, а основний agent залиште на
якіснішій моделі. Це можна налаштувати через `agents.defaults.subagents.model` або через
перевизначення для окремого agent. Коли дочірньому процесу справді потрібен поточний транскрипт запитувача, agent може запросити
`context: "fork"` для цього одного spawn.
## Режими контексту
Власні підагенти запускаються ізольовано, якщо викликач явно не просить розгалужити
поточний транскрипт.
Нативні sub-agents запускаються ізольовано, якщо тільки викликач явно не просить зробити fork
поточного транскрипту.
| Режим | Коли його використовувати | Поведінка |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `isolated` | Нове дослідження, незалежна реалізація, робота з повільним інструментом або будь-що, що можна коротко описати в тексті завдання | Створює чистий дочірній транскрипт. Це типовий режим і він зменшує використання токенів. |
| `fork` | Робота, що залежить від поточної розмови, попередніх результатів інструментів або нюансованих інструкцій, уже наявних у транскрипті запитувача | Розгалужує транскрипт запитувача в дочірню сесію перед запуском дочірнього агента. |
| Режим | Коли його використовувати | Поведінка |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `isolated` | Нове дослідження, незалежна реалізація, повільна робота інструментів або будь-що, що можна коротко описати в тексті завдання | Створює чистий дочірній транскрипт. Це типове значення і воно знижує використання токенів. |
| `fork` | Робота, яка залежить від поточної розмови, попередніх результатів інструментів або тонких інструкцій, уже наявних у транскрипті запитувача | Відгалужує транскрипт запитувача в дочірню сесію перед запуском дочірнього процесу. |
Використовуйте `fork` помірно. Він призначений для делегування, чутливого до контексту, а не як заміна
чіткому формулюванню запиту завдання.
Використовуйте `fork` ощадливо. Це для делегування, чутливого до контексту, а не заміна
чіткого формулювання завдання.
## Інструмент
Використовуйте `sessions_spawn`:
- Запускає виконання підагента (`deliver: false`, глобальна смуга: `subagent`)
- Потім виконує крок повідомлення й публікує відповідь-повідомлення в чат-канал запитувача
- Типова модель: успадковується від викликача, якщо ви не встановите `agents.defaults.subagents.model` (або `agents.list[].subagents.model` для окремого агента); явний `sessions_spawn.model` усе одно має пріоритет.
- Типовий рівень thinking: успадковується від викликача, якщо ви не встановите `agents.defaults.subagents.thinking` (або `agents.list[].subagents.thinking` для окремого агента); явний `sessions_spawn.thinking` усе одно має пріоритет.
- Типовий тайм-аут виконання: якщо `sessions_spawn.runTimeoutSeconds` пропущено, OpenClaw використовує `agents.defaults.subagents.runTimeoutSeconds`, якщо його задано; інакше використовується `0` (без тайм-ауту).
- Запускає виконання sub-agent (`deliver: false`, глобальна смуга: `subagent`)
- Потім виконує крок повідомлення і публікує відповідь-повідомлення назад у канал чату запитувача
- Типова модель: успадковується від викликача, якщо ви не встановили `agents.defaults.subagents.model` (або `agents.list[].subagents.model` для окремого agent); явне значення `sessions_spawn.model` усе одно має пріоритет.
- Типовий рівень thinking: успадковується від викликача, якщо ви не встановили `agents.defaults.subagents.thinking` (або `agents.list[].subagents.thinking` для окремого agent); явне значення `sessions_spawn.thinking` усе одно має пріоритет.
- Типовий тайм-аут виконання: якщо `sessions_spawn.runTimeoutSeconds` не вказано, OpenClaw використовує `agents.defaults.subagents.runTimeoutSeconds`, якщо його задано; інакше використовується `0` (без тайм-ауту).
Параметри інструмента:
- `task` (обов’язковий)
- `label?` (необов’язковий)
- `agentId?` (необов’язковий; запуск під іншим id агента, якщо дозволено)
- `runtime?` (`subagent|acp`, типово `subagent`; `acp` призначений лише для зовнішніх ACP harness, таких як `codex`, `claude`, `gemini` або `opencode`, або для записів `agents.list[]`, у яких `runtime.type` дорівнює `acp`)
- `model?` (необов’язковий; перевизначає модель підагента; некоректні значення пропускаються, і підагент запускається на типовій моделі з попередженням у результаті інструмента)
- `thinking?` (необов’язковий; перевизначає рівень thinking для виконання підагента)
- `runTimeoutSeconds?` (типово береться з `agents.defaults.subagents.runTimeoutSeconds`, якщо задано, інакше `0`; якщо встановлено, виконання підагента переривається через N секунд)
- `thread?` (типово `false`; якщо `true`, запитує прив’язку до потоку каналу для цієї сесії підагента)
- `task` (обов’язково)
- `label?` (необов’язково)
- `agentId?` (необов’язково; запуск під іншим ID agent, якщо дозволено)
- `runtime?` (`subagent|acp`, типово `subagent`; `acp` призначено лише для зовнішніх ACP harness, таких як `claude`, `gemini`, `opencode`, або явно запитаного Codex ACP/acpx, або для записів `agents.list[]`, у яких `runtime.type` має значення `acp`)
- `model?` (необов’язково; перевизначає модель sub-agent; некоректні значення пропускаються, і sub-agent запускається на типовій моделі з попередженням у результаті інструмента)
- `thinking?` (необов’язково; перевизначає рівень thinking для виконання sub-agent)
- `runTimeoutSeconds?` (типово — `agents.defaults.subagents.runTimeoutSeconds`, якщо задано, інакше `0`; якщо встановлено, виконання sub-agent примусово переривається через N секунд)
- `thread?` (типово `false`; коли `true`, запитує прив’язку до потоку каналу для цієї сесії sub-agent)
- `mode?` (`run|session`)
- типове значення — `run`
- якщо `thread: true`, а `mode` пропущено, типове значення стає `session`
- якщо `thread: true` і `mode` не вказано, типовим стає `session`
- `mode: "session"` вимагає `thread: true`
- `cleanup?` (`delete|keep`, типово `keep`)
- `sandbox?` (`inherit|require`, типово `inherit`; `require` відхиляє запуск, якщо цільовий дочірній runtime не ізольований)
- `context?` (`isolated|fork`, типово `isolated`; лише для власних підагентів)
- `sandbox?` (`inherit|require`, типово `inherit`; `require` відхиляє spawn, якщо цільове дочірнє runtime не працює в sandbox)
- `context?` (`isolated|fork`, типово `isolated`; лише для нативних sub-agent)
- `isolated` створює чистий дочірній транскрипт і є типовим значенням.
- `fork` розгалужує поточний транскрипт запитувача в дочірню сесію, щоб дочірній агент починав із тим самим контекстом розмови.
- Використовуйте `fork` лише тоді, коли дочірньому агенту потрібен поточний транскрипт. Для вузько визначеної роботи не вказуйте `context`.
- `sessions_spawn` **не** приймає параметри доставки каналу (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Для доставки використовуйте `message`/`sessions_send` із запущеного виконання.
- `fork` відгалужує поточний транскрипт запитувача в дочірню сесію, щоб дочірній процес почав із тим самим контекстом розмови.
- Використовуйте `fork`, лише коли дочірньому процесу потрібен поточний транскрипт. Для локалізованої роботи не вказуйте `context`.
- `sessions_spawn` **не** приймає параметри доставки каналу (`target`, `channel`, `to`, `threadId`, `replyTo`, `transport`). Для доставки використовуйте `message`/`sessions_send` із породженого виконання.
## Сесії, прив’язані до потоку
Коли для каналу ввімкнено прив’язки до потоку, підагент може залишатися прив’язаним до потоку, щоб подальші повідомлення користувача в цьому потоці й надалі маршрутизувалися до тієї самої сесії підагента.
Коли прив’язки до потоків увімкнено для каналу, sub-agent може залишатися прив’язаним до потоку, щоб наступні повідомлення користувача в цьому потоці й далі маршрутизувалися до тієї самої сесії sub-agent.
### Канали з підтримкою потоків
- Discord (наразі єдиний підтримуваний канал): підтримує постійні сесії підагентів, прив’язані до потоку (`sessions_spawn` з `thread: true`), ручні елементи керування потоками (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) і ключі адаптера `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours` і `channels.discord.threadBindings.spawnSubagentSessions`.
- Discord (наразі єдиний підтримуваний канал): підтримує постійні сесії subagent, прив’язані до потоку (`sessions_spawn` з `thread: true`), ручне керування потоками (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) і ключі адаптера `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours` та `channels.discord.threadBindings.spawnSubagentSessions`.
Короткий потік:
Короткий сценарій:
1. Запустіть через `sessions_spawn` із `thread: true` (і за потреби `mode: "session"`).
1. Запустіть через `sessions_spawn` з `thread: true` (і, за бажанням, `mode: "session"`).
2. OpenClaw створює потік або прив’язує його до цільової сесії в активному каналі.
3. Відповіді та подальші повідомлення в цьому потоці маршрутизуються до прив’язаної сесії.
4. Використовуйте `/session idle`, щоб переглядати/оновлювати автоматичне зняття фокуса через неактивність, і `/session max-age`, щоб керувати жорстким лімітом.
5. Використовуйте `/unfocus`, щоб відв’язати вручну.
3. Відповіді та наступні повідомлення в цьому потоці маршрутизуються до прив’язаної сесії.
4. Використовуйте `/session idle`, щоб переглядати/оновлювати автоматичне відв’язування за неактивністю, і `/session max-age`, щоб керувати жорстким лімітом.
5. Використовуйте `/unfocus`, щоб вручну від’єднати.
Ручні елементи керування:
- `/focus <target>` прив’язує поточний потік (або створює новий) до цілі підагента/сесії.
- `/focus <target>` прив’язує поточний потік (або створює його) до цільової сесії/sub-agent.
- `/unfocus` видаляє прив’язку для поточного прив’язаного потоку.
- `/agents` перелічує активні виконання та стан прив’язки (`thread:<id>` або `unbound`).
- `/session idle` і `/session max-age` працюють лише для сфокусованих прив’язаних потоків.
@ -153,34 +153,34 @@ x-i18n:
Перемикачі конфігурації:
- Глобальні типові значення: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`
- Перевизначення для каналу та ключі автоматичної прив’язки під час запуску залежать від адаптера. Див. **Канали з підтримкою потоків** вище.
- Перевизначення для каналу та ключі автоматичної прив’язки під час spawn залежать від адаптера. Див. **Канали з підтримкою потоків** вище.
Див. [Довідник з конфігурації](/uk/gateway/configuration-reference) і [Команди зі скісною рискою](/uk/tools/slash-commands), щоб отримати поточні відомості про адаптери.
Див. [Configuration Reference](/uk/gateway/configuration-reference) і [Slash commands](/uk/tools/slash-commands), щоб отримати актуальні відомості про адаптери.
Список дозволених:
Список дозволених значень:
- `agents.list[].subagents.allowAgents`: список id агентів, на які можна націлюватися через `agentId` (`["*"]` дозволяє будь-який). Типово: лише агент запитувача.
- `agents.defaults.subagents.allowAgents`: типовий список дозволених цільових агентів, який використовується, коли агент запитувача не задає власний `subagents.allowAgents`.
- Захист успадкування ізоляції: якщо сесія запитувача ізольована, `sessions_spawn` відхиляє цілі, які працювали б без ізоляції.
- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: коли має значення true, блокують виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю). Типове значення: false.
- `agents.list[].subagents.allowAgents`: список ID agent, на які можна націлюватися через `agentId` (`["*"]` дозволяє будь-який). Типово: лише agent запитувача.
- `agents.defaults.subagents.allowAgents`: типовий список дозволених цільових agent, який використовується, коли agent запитувача не задає власний `subagents.allowAgents`.
- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox.
- `agents.defaults.subagents.requireAgentId` / `agents.list[].subagents.requireAgentId`: коли значення true, блокують виклики `sessions_spawn`, у яких не вказано `agentId` (примушує до явного вибору профілю). Типово: false.
Виявлення:
- Використовуйте `agents_list`, щоб побачити, які id агентів зараз дозволені для `sessions_spawn`.
- Використовуйте `agents_list`, щоб побачити, які ID agent наразі дозволені для `sessions_spawn`. Відповідь містить ефективну модель кожного переліченого agent і вбудовані метадані runtime, щоб викликачі могли розрізняти PI, сервер застосунку Codex та інші налаштовані нативні runtime.
Автоархівація:
- Сесії підагентів автоматично архівуються через `agents.defaults.subagents.archiveAfterMinutes` (типово: 60).
- Під час архівації використовується `sessions.delete`, а транскрипт перейменовується на `*.deleted.<timestamp>` (у тій самій теці).
- `cleanup: "delete"` архівує відразу після повідомлення (транскрипт усе одно зберігається через перейменування).
- Автоархівація є best-effort; заплановані таймери втрачаються, якщо Gateway перезапускається.
- Сесії Sub-agent автоматично архівуються після `agents.defaults.subagents.archiveAfterMinutes` (типово: 60).
- Архівація використовує `sessions.delete` і перейменовує транскрипт у `*.deleted.<timestamp>` (та сама папка).
- `cleanup: "delete"` архівує одразу після повідомлення про завершення (транскрипт усе одно зберігається через перейменування).
- Автоархівація працює в режимі best-effort; очікувані таймери губляться, якщо gateway перезапускається.
- `runTimeoutSeconds` **не** виконує автоархівацію; він лише зупиняє виконання. Сесія залишається до автоархівації.
- Автоархівація однаково застосовується до сесій першого та другого рівня вкладеності.
- Очищення браузера відокремлене від очищення архіву: відстежувані вкладки/процеси браузера намагаються закритися після завершення виконання, навіть якщо транскрипт/запис сесії зберігається.
- Автоархівація однаково застосовується до сесій глибини 1 і глибини 2.
- Очищення браузера відокремлене від очищення архіву: відстежувані вкладки/процеси браузера закриваються в режимі best-effort після завершення виконання, навіть якщо запис транскрипту/сесії зберігається.
## Вкладені підагенти
## Вкладені sub-agents
За замовчуванням підагенти не можуть запускати власних підагентів (`maxSpawnDepth: 1`). Ви можете ввімкнути один рівень вкладеності, встановивши `maxSpawnDepth: 2`, що дозволяє **шаблон оркестратора**: main → підагент-оркестратор → дочірні підагенти-виконавці.
Типово sub-agents не можуть породжувати власні sub-agents (`maxSpawnDepth: 1`). Ви можете увімкнути один рівень вкладеності, встановивши `maxSpawnDepth: 2`, що дозволяє **шаблон оркестратора**: main → sub-agent-оркестратор → sub-sub-agents-воркери.
### Як увімкнути
@ -189,10 +189,10 @@ x-i18n:
agents: {
defaults: {
subagents: {
maxSpawnDepth: 2, // дозволити підагентам запускати дочірніх агентів (типово: 1)
maxChildrenPerAgent: 5, // максимальна кількість активних дочірніх агентів на сесію агента (типово: 5)
maxConcurrent: 8, // глобальне обмеження паралельності для смуги (типово: 8)
runTimeoutSeconds: 900, // типовий тайм-аут для sessions_spawn, якщо параметр пропущено (0 = без тайм-ауту)
maxSpawnDepth: 2, // дозволити sub-agents породжувати дочірні процеси (типово: 1)
maxChildrenPerAgent: 5, // максимальна кількість активних дочірніх процесів на сесію agent (типово: 5)
maxConcurrent: 8, // глобальне обмеження паралельності для lane (типово: 8)
runTimeoutSeconds: 900, // типовий тайм-аут для sessions_spawn, якщо не вказано (0 = без тайм-ауту)
},
},
},
@ -201,133 +201,132 @@ x-i18n:
### Рівні глибини
| Глибина | Форма ключа сесії | Роль | Може запускати? |
| ------- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
| 0 | `agent:<id>:main` | Основний агент | Завжди |
| 1 | `agent:<id>:subagent:<uuid>` | Підагент (оркестратор, якщо дозволено глибину 2) | Лише якщо `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Підагент другого рівня (кінцевий виконавець) | Ніколи |
| Глибина | Форма ключа сесії | Роль | Може породжувати? |
| ------- | ------------------------------------------- | --------------------------------------------- | ---------------------------- |
| 0 | `agent:<id>:main` | Основний agent | Завжди |
| 1 | `agent:<id>:subagent:<uuid>` | Sub-agent (оркестратор, якщо дозволено depth 2) | Лише якщо `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Sub-sub-agent (кінцевий воркер) | Ніколи |
### Ланцюжок повідомлень
### Ланцюжок повідомлень про завершення
Результати повертаються вгору ланцюжком:
Результати повертаються вгору по ланцюжку:
1. Виконавець другого рівня завершує роботу → повідомляє свого батьківського агента (оркестратора першого рівня)
2. Оркестратор першого рівня отримує повідомлення, синтезує результати, завершує роботу → повідомляє main
3. Основний агент отримує повідомлення та доставляє його користувачу
1. Воркер depth-2 завершується → повідомляє свого батька (оркестратор depth-1)
2. Оркестратор depth-1 отримує повідомлення, синтезує результати, завершується → повідомляє main
3. Основний agent отримує повідомлення й доставляє його користувачу
Кожен рівень бачить лише повідомлення від своїх безпосередніх дочірніх агентів.
Кожен рівень бачить лише повідомлення від своїх прямих дочірніх процесів.
Операційні рекомендації:
- Запускайте дочірню роботу один раз і чекайте на події завершення замість побудови циклів
- Запускайте дочірню роботу один раз і чекайте на події завершення, а не будуйте цикли
опитування навколо `sessions_list`, `sessions_history`, `/subagents list` або
команд `exec` зі sleep.
- `sessions_list` і `/subagents list` зберігають зв’язки дочірніх сесій зосередженими
на живій роботі: активні дочірні агенти залишаються прив’язаними, завершені дочірні агенти залишаються видимими
протягом короткого недавнього вікна, а застарілі посилання на дочірні агенти лише в сховищі ігноруються після завершення їхнього
вікна актуальності. Це не дає старим метаданим `spawnedBy` / `parentSessionKey`
відроджувати примарних дочірніх агентів після перезапуску.
- Якщо подія завершення дочірнього агента надходить після того, як ви вже надіслали остаточну відповідь,
команд `exec` зі `sleep`.
- `sessions_list` і `/subagents list` зберігають зв’язки дочірніх сесій
сфокусованими на активній роботі: активні дочірні процеси залишаються прив’язаними, завершені залишаються видимими
протягом короткого недавнього вікна, а застарілі посилання на дочірні процеси лише зі сховища ігноруються після завершення їхнього
вікна свіжості. Це запобігає відродженню примарних дочірніх процесів після перезапуску через старі метадані `spawnedBy` / `parentSessionKey`.
- Якщо подія завершення дочірнього процесу надходить після того, як ви вже надіслали фінальну відповідь,
правильною подальшою дією є точний тихий токен `NO_REPLY` / `no_reply`.
### Політика інструментів за глибиною
- Роль і область керування записуються в метадані сесії під час запуску. Це не дає пласким або відновленим ключам сесії випадково знову отримати привілеї оркестратора.
- **Глибина 1 (оркестратор, коли `maxSpawnDepth >= 2`)**: Отримує `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, щоб керувати своїми дочірніми агентами. Інші інструменти сесії/системи, як і раніше, заборонені.
- **Глибина 1 (кінцевий агент, коли `maxSpawnDepth == 1`)**: Без інструментів сесії (поточна типова поведінка).
- **Глибина 2 (кінцевий виконавець)**: Без інструментів сесії — `sessions_spawn` завжди заборонений на глибині 2. Не може запускати подальших дочірніх агентів.
- Роль і область керування записуються в метадані сесії під час spawn. Це не дає плоским або відновленим ключам сесій випадково повернути привілеї оркестратора.
- **Глибина 1 (оркестратор, коли `maxSpawnDepth >= 2`)**: отримує `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history`, щоб керувати своїми дочірніми процесами. Інші інструменти сесій/системи залишаються забороненими.
- **Глибина 1 (листок, коли `maxSpawnDepth == 1`)**: без інструментів сесій (поточна типова поведінка).
- **Глибина 2 (кінцевий воркер)**: без інструментів сесій — `sessions_spawn` завжди заборонено на глибині 2. Не може породжувати наступних дочірніх процесів.
### Ліміт запуску для одного агента
### Ліміт spawn для кожного agent
Кожна сесія агента (на будь-якій глибині) може одночасно мати не більше `maxChildrenPerAgent` (типово: 5) активних дочірніх агентів. Це запобігає неконтрольованому розгалуженню від одного оркестратора.
Кожна сесія agent (на будь-якій глибині) може мати щонайбільше `maxChildrenPerAgent` (типово: 5) активних дочірніх процесів одночасно. Це запобігає неконтрольованому розгалуженню від одного оркестратора.
### Каскадна зупинка
Зупинка оркестратора першого рівня автоматично зупиняє всіх його дочірніх агентів другого рівня:
Зупинка оркестратора depth-1 автоматично зупиняє всіх його дочірніх процесів depth-2:
- `/stop` в основному чаті зупиняє всіх агентів першого рівня та каскадно зупиняє їхніх дочірніх агентів другого рівня.
- `/subagents kill <id>` зупиняє конкретного підагента та каскадно зупиняє його дочірніх агентів.
- `/subagents kill all` зупиняє всіх підагентів для запитувача та виконує каскадну зупинку.
- `/stop` в основному чаті зупиняє всіх agent depth-1 і каскадно зупиняє їхніх дочірніх процесів depth-2.
- `/subagents kill <id>` зупиняє конкретний sub-agent і каскадно зупиняє його дочірніх процесів.
- `/subagents kill all` зупиняє всіх sub-agents для запитувача і виконує каскадну зупинку.
## Автентифікація
Автентифікація підагента визначається за **id агента**, а не за типом сесії:
Автентифікація sub-agent розв’язується за **ID agent**, а не за типом сесії:
- Ключ сесії підагента має вигляд `agent:<agentId>:subagent:<uuid>`.
- Сховище автентифікації завантажується з `agentDir` цього агента.
- Профілі автентифікації основного агента зливаються як **резервні**; профілі агента мають пріоритет над профілями main у разі конфліктів.
- Ключ сесії sub-agent — `agent:<agentId>:subagent:<uuid>`.
- Сховище автентифікації завантажується з `agentDir` цього agent.
- Профілі автентифікації основного agent додаються як **резервний варіант**; профілі agent мають пріоритет над профілями main у разі конфліктів.
Примітка: злиття є адитивним, тому профілі main завжди доступні як резервні. Повністю ізольована автентифікація для кожного агента поки що не підтримується.
Примітка: об’єднання є адитивним, тому профілі main завжди доступні як резервні. Повністю ізольована автентифікація для кожного agent поки не підтримується.
## Повідомлення
## Повідомлення про завершення
Підагенти звітують назад через крок повідомлення:
Sub-agents звітують назад через крок повідомлення про завершення:
- Крок повідомлення виконується всередині сесії підагента (а не сесії запитувача).
- Якщо підагент відповідає точно `ANNOUNCE_SKIP`, нічого не публікується.
- Якщо останній текст assistant — це точний тихий токен `NO_REPLY` / `no_reply`,
вивід повідомлення пригнічується, навіть якщо раніше був видимий прогрес.
- В іншому разі доставка залежить від глибини запитувача:
- для сесій запитувача верхнього рівня використовується подальший виклик `agent` із зовнішньою доставкою (`deliver=true`)
- вкладені сесії підагентів запитувача отримують внутрішнє подальше впровадження (`deliver=false`), щоб оркестратор міг синтезувати результати дочірніх агентів у межах сесії
- якщо вкладена сесія підагента запитувача вже відсутня, OpenClaw повертається до запитувача цієї сесії, якщо він доступний
- Для сесій запитувача верхнього рівня пряма доставка в режимі завершення спочатку визначає будь-який прив’язаний маршрут розмови/потоку та перевизначення hook, а потім доповнює відсутні поля цілі каналу збереженим маршрутом сесії запитувача. Це зберігає завершення в правильному чаті/темі, навіть коли джерело завершення визначає лише канал.
- Агрегація завершень дочірніх агентів обмежується поточним виконанням запитувача під час побудови вкладених висновків про завершення, щоб застарілі результати дочірніх агентів із попередніх виконань не потрапляли в поточне повідомлення.
- Відповіді-повідомлення зберігають маршрутизацію потоку/теми, коли вона доступна в адаптерах каналів.
- Контекст повідомлення нормалізується до стабільного внутрішнього блоку подій:
- Крок повідомлення про завершення виконується всередині сесії sub-agent (а не сесії запитувача).
- Якщо sub-agent відповідає рівно `ANNOUNCE_SKIP`, нічого не публікується.
- Якщо останній текст assistant є точним тихим токеном `NO_REPLY` / `no_reply`,
вивід повідомлення про завершення пригнічується, навіть якщо раніше був видимий прогрес.
- Інакше доставка залежить від глибини запитувача:
- сесії запитувача верхнього рівня використовують подальший виклик `agent` із зовнішньою доставкою (`deliver=true`)
- вкладені сесії subagent запитувача отримують внутрішнє подальше вливання (`deliver=false`), щоб оркестратор міг синтезувати результати дочірніх процесів усередині сесії
- якщо вкладеної сесії subagent запитувача більше немає, OpenClaw переходить до резервного варіанта з використанням запитувача цієї сесії, коли це можливо
- Для сесій запитувача верхнього рівня пряма доставка в режимі завершення спочатку розв’язує будь-який прив’язаний маршрут розмови/потоку та перевизначення hook, а потім заповнює відсутні поля channel-target зі збереженого маршруту сесії запитувача. Це утримує завершення в правильному чаті/темі, навіть коли джерело завершення ідентифікує лише канал.
- Агрегація завершень дочірніх процесів обмежується поточним виконанням запитувача під час побудови вкладених результатів завершення, що запобігає витіканню застарілих виводів дочірніх процесів із попередніх запусків у поточне повідомлення.
- Відповіді-повідомлення про завершення зберігають маршрутизацію потоку/теми, коли вона доступна в адаптерах каналів.
- Контекст повідомлення про завершення нормалізується до стабільного внутрішнього блоку подій:
- джерело (`subagent` або `cron`)
- ключ/id дочірньої сесії
- ключ/ID дочірньої сесії
- тип повідомлення + мітка завдання
- рядок статусу, похідний від результату виконання (`success`, `error`, `timeout` або `unknown`)
- вміст результату, вибраний з останнього видимого тексту assistant, або, якщо його немає, санітизований останній текст `tool`/`toolResult`; термінально невдалі виконання повідомляють статус невдачі без повторного відтворення захопленого тексту відповіді
- подальшу інструкцію, яка описує, коли відповідати, а коли зберігати тишу
- `Status` не виводиться з виводу моделі; він походить із сигналів результату виконання.
- У разі тайм-ауту, якщо дочірній агент встиг дійти лише до викликів інструментів, повідомлення може згорнути цю історію в короткий підсумок часткового прогресу замість відтворення сирого виводу інструмента.
- рядок стану, похідний від результату runtime (`success`, `error`, `timeout` або `unknown`)
- вміст результату, вибраний з останнього видимого тексту assistant, інакше — санітизований останній текст tool/toolResult; завершені невдалі виконання повідомляють про стан невдачі без відтворення захопленого тексту відповіді
- подальша інструкція, яка описує, коли відповідати, а коли зберігати мовчання
- `Status` не виводиться з виводу моделі; він походить із сигналів результату runtime.
- У разі тайм-ауту, якщо дочірній процес встиг лише виконати виклики інструментів, повідомлення про завершення може згорнути цю історію в коротке зведення часткового прогресу замість відтворення сирого виводу інструментів.
Корисне навантаження повідомлень містить рядок статистики в кінці (навіть коли обгорнуте):
Payload повідомлень про завершення включають рядок статистики в кінці (навіть якщо вони загорнуті):
- Тривалість виконання (наприклад, `runtime 5m12s`)
- Використання токенів (вхідні/вихідні/загалом)
- Оцінена вартість, якщо налаштовано ціни моделей (`models.providers.*.models[].cost`)
- `sessionKey`, `sessionId` і шлях до транскрипту (щоб основний агент міг отримати історію через `sessions_history` або перевірити файл на диску)
- Внутрішні метадані призначені лише для оркестрації; відповіді для користувача слід переписувати звичайним голосом помічника.
- Runtime (наприклад, `runtime 5m12s`)
- Використання токенів (input/output/total)
- Оцінена вартість, коли налаштовано ціни моделі (`models.providers.*.models[].cost`)
- `sessionKey`, `sessionId` і шлях до транскрипту (щоб основний agent міг отримати history через `sessions_history` або перевірити файл на диску)
- Внутрішні метадані призначені лише для оркестрації; відповіді для користувача мають бути переписані звичайним голосом assistant.
`sessions_history` — це безпечніший шлях оркестрації:
`sessions_history` — безпечніший шлях оркестрації:
- історія assistant спочатку нормалізується:
- спочатку нормалізується пригадування assistant:
- теги thinking видаляються
- блоки каркаса `<relevant-memories>` / `<relevant_memories>` видаляються
- текстові XML-блоки корисного навантаження викликів інструментів, такі як `<tool_call>...</tool_call>`,
- блоки plain-text XML payload викликів інструментів, такі як `<tool_call>...</tool_call>`,
`<function_call>...</function_call>`, `<tool_calls>...</tool_calls>` і
`<function_calls>...</function_calls>`, видаляються, включно з усіченими
корисними навантаженнями, які так і не закриваються належним чином
- знижений до тексту каркас викликів/результатів інструментів і маркери історичного контексту видаляються
- витеклі токени керування моделлю, такі як `<|assistant|>`, інші ASCII-токени
`<|...|>` і повноширинні варіанти `<｜...｜>`, видаляються
- неправильний XML викликів інструментів MiniMax видаляється
`<function_calls>...</function_calls>`, видаляються, включно з обрізаними
payload, які так і не закриваються коректно
- понижені каркаси викликів інструментів/результатів та маркери історичного контексту видаляються
- витоки токенів керування моделі, як-от `<|assistant|>`, інші ASCII
токени `<|...|>` і повноширинні варіанти `<｜...｜>`, видаляються
- некоректний XML викликів інструментів MiniMax видаляється
- текст, схожий на облікові дані/токени, редагується
- довгі блоки можуть усікатися
- дуже великі історії можуть відкидати старіші рядки або замінювати надто великий рядок на
- довгі блоки можуть обрізатися
- дуже великі історії можуть втрачати старіші рядки або замінювати надмірно великий рядок на
`[sessions_history omitted: message too large]`
- перевірка сирого транскрипту на диску є запасним варіантом, коли вам потрібен повний транскрипт байт-у-байт
- перевірка сирого транскрипту на диску є резервним варіантом, коли вам потрібен повний побайтовий транскрипт
## Політика інструментів (інструменти підагентів)
## Політика інструментів (інструменти sub-agent)
Підагенти спочатку використовують той самий профіль і конвеєр політики інструментів, що й батьківський або цільовий
агент. Після цього OpenClaw застосовує шар обмежень для підагентів.
Sub-agents спочатку використовують той самий профіль і pipeline політики інструментів, що й батьківський або цільовий
agent. Після цього OpenClaw застосовує шар обмежень sub-agent.
Без обмежувального `tools.profile` підагенти отримують **усі інструменти, крім інструментів
сесії** та системних інструментів:
Без обмежувального `tools.profile` sub-agents отримують **усі інструменти, крім інструментів сесій**
та системних інструментів:
- `sessions_list`
- `sessions_history`
- `sessions_send`
- `sessions_spawn`
Тут також `sessions_history` залишається обмеженим санітизованим переглядом історії;
це не сирий дамп транскрипту.
`sessions_history` і тут залишається обмеженим, санітизованим поданням history; це не
сирий дамп транскрипту.
Коли `maxSpawnDepth >= 2`, підагенти-оркестратори першого рівня додатково отримують `sessions_spawn`, `subagents`, `sessions_list` і `sessions_history`, щоб керувати своїми дочірніми агентами.
Коли `maxSpawnDepth >= 2`, sub-agents-оркестратори depth-1 додатково отримують `sessions_spawn`, `subagents`, `sessions_list` і `sessions_history`, щоб керувати своїми дочірніми процесами.
Перевизначення через конфігурацію:
@ -343,9 +342,9 @@ x-i18n:
tools: {
subagents: {
tools: {
// deny має пріоритет
// заборона має пріоритет
deny: ["gateway", "cron"],
// якщо задано allow, він стає фільтром "дозволено лише це" (deny усе одно має пріоритет)
// якщо задано allow, він стає списком лише дозволених (deny усе одно має пріоритет)
// allow: ["read", "exec", "process"]
},
},
@ -353,11 +352,11 @@ x-i18n:
}
```
`tools.subagents.tools.allow` — це фінальний фільтр "дозволено лише це". Він може звузити
вже визначений набір інструментів, але не може повернути інструмент,
вилучений через `tools.profile`. Наприклад, `tools.profile: "coding"` включає
`web_search`/`web_fetch`, але не інструмент `browser`. Щоб дозволити підагентам
з профілем coding використовувати автоматизацію браузера, додайте browser на етапі профілю:
`tools.subagents.tools.allow` — це фінальний фільтр лише дозволених значень. Він може звузити
вже розв’язаний набір інструментів, але не може повернути інструмент,
видалений `tools.profile`. Наприклад, `tools.profile: "coding"` включає
`web_search`/`web_fetch`, але не інструмент `browser`. Щоб дозволити sub-agents
із профілем coding використовувати автоматизацію браузера, додайте browser на етапі профілю:
```json5
{
@ -368,52 +367,51 @@ x-i18n:
}
```
Використовуйте `agents.list[].tools.alsoAllow: ["browser"]`, коли лише один агент
має отримати автоматизацію браузера.
Використовуйте `agents.list[].tools.alsoAllow: ["browser"]`, коли автоматизацію браузера
має отримати лише один agent.
## Паралельність
Підагенти використовують окрему внутрішньопроцесну смугу черги:
Sub-agents використовують окрему in-process queue lane:
- Назва смуги: `subagent`
- Назва lane: `subagent`
- Паралельність: `agents.defaults.subagents.maxConcurrent` (типово `8`)
## Живучість і відновлення
OpenClaw не вважає відсутність `endedAt` постійним доказом того, що підагент
усе ще активний. Незавершені виконання, старші за вікно застарілого виконання, перестають враховуватися як
активні/очікувані в `/subagents list`, зведеннях статусу, перевірці завершення
OpenClaw не розглядає відсутність `endedAt` як постійний доказ того, що sub-agent
усе ще активний. Незавершені виконання, старіші за вікно застарілого виконання, перестають рахуватися як
активні/очікувані в `/subagents list`, підсумках стану, блокуванні завершення
нащадків і перевірках паралельності для кожної сесії.
Після перезапуску Gateway застарілі відновлені незавершені виконання відсікаються, якщо їхня
дочірня сесія не позначена як `abortedLastRun: true`. Такі дочірні сесії,
перервані під час перезапуску, залишаються відновлюваними через потік відновлення сиріт підагентів,
який надсилає синтетичне повідомлення відновлення перед очищенням маркера переривання.
Після перезапуску gateway застарілі відновлені незавершені виконання відсікаються, якщо їхня
дочірня сесія не позначена як `abortedLastRun: true`. Ці дочірні сесії, перервані під час перезапуску,
залишаються відновлюваними через потік відновлення осиротілих sub-agent, який
надсилає синтетичне повідомлення про відновлення перед очищенням маркера переривання.
Якщо запуск підагента завершується помилкою Gateway `PAIRING_REQUIRED` / `scope-upgrade`,
перевірте викликач RPC, перш ніж редагувати стан pairing. Внутрішня координація `sessions_spawn`
Якщо spawn sub-agent завершується помилкою Gateway `PAIRING_REQUIRED` / `scope-upgrade`,
перевірте викликач RPC перед редагуванням стану pairing. Внутрішня координація `sessions_spawn`
має підключатися як `client.id: "gateway-client"` з
`client.mode: "backend"` через пряму loopback-автентифікацію зі спільним токеном/паролем; цей
шлях не залежить від базового рівня області paired-device у CLI. Віддалені викликачі,
явний `deviceIdentity`, явні шляхи токенів пристроїв і клієнти browser/node, як і раніше,
потребують звичайного схвалення пристрою для розширення області.
`client.mode: "backend"` через пряму local loopback shared-token/password автентифікацію; цей
шлях не залежить від базового рівня scope спареного пристрою CLI. Віддалені викликачі,
явний `deviceIdentity`, явні шляхи токенів пристроїв і клієнти browser/node, як і раніше, потребують звичайного схвалення пристрою для підвищення scope.
## Зупинка
- Надсилання `/stop` у чаті запитувача перериває сесію запитувача та зупиняє всі активні виконання підагентів, запущені з неї, з каскадною зупинкою вкладених дочірніх агентів.
- `/subagents kill <id>` зупиняє конкретного підагента та каскадно зупиняє його дочірніх агентів.
- Надсилання `/stop` у чаті запитувача перериває сесію запитувача і зупиняє всі активні виконання sub-agent, породжені з неї, з каскадним поширенням на вкладених дочірніх процесів.
- `/subagents kill <id>` зупиняє конкретний sub-agent і каскадно зупиняє його дочірніх процесів.
## Обмеження
- Повідомлення підагента — це **best-effort**. Якщо Gateway перезапуститься, відкладена робота «повідомити назад» буде втрачена.
- Підагенти все ще ділять ресурси того самого процесу gateway; розглядайте `maxConcurrent` як запобіжний клапан.
- `sessions_spawn` завжди неблокувальний: він негайно повертає `{ status: "accepted", runId, childSessionKey }`.
- Контекст підагента впроваджує лише `AGENTS.md` + `TOOLS.md` (без `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` або `BOOTSTRAP.md`).
- Максимальна глибина вкладеності — 5 (діапазон `maxSpawnDepth`: 1–5). Для більшості випадків використання рекомендується глибина 2.
- `maxChildrenPerAgent` обмежує кількість активних дочірніх агентів на сесію (типово: 5, діапазон: 1–20).
- Повідомлення sub-agent про завершення працює в режимі **best-effort**. Якщо gateway перезапускається, очікувана робота з "повідомлення назад" втрачається.
- Sub-agents усе ще спільно використовують ресурси того самого процесу gateway; розглядайте `maxConcurrent` як запобіжний клапан.
- `sessions_spawn` завжди є неблокувальним: він одразу повертає `{ status: "accepted", runId, childSessionKey }`.
- Контекст sub-agent інжектує лише `AGENTS.md` + `TOOLS.md` (без `SOUL.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md` або `BOOTSTRAP.md`).
- Максимальна глибина вкладеності — 5 (`maxSpawnDepth` у діапазоні 1–5). Для більшості сценаріїв рекомендовано depth 2.
- `maxChildrenPerAgent` обмежує кількість активних дочірніх процесів на сесію (типово: 5, діапазон: 1–20).
## Пов’язане
- [ACP agents](/uk/tools/acp-agents)
- [Інструменти ізольованого середовища для мультиагентності](/uk/tools/multi-agent-sandbox-tools)
- [Надсилання агенту](/uk/tools/agent-send)
- [Інструменти sandbox для багатьох agent](/uk/tools/multi-agent-sandbox-tools)
- [Надсилання agent](/uk/tools/agent-send)