From f278d73eb4c855b68e1ffd5b236245a77d2c8767 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 26 Apr 2026 00:22:12 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/cli/plugins.md | 189 ++--- docs/uk/concepts/agent-runtimes.md | 183 ++--- docs/uk/gateway/bonjour.md | 141 ++-- docs/uk/gateway/configuration-reference.md | 543 +++++++------ docs/uk/gateway/doctor.md | 522 ++++++------- docs/uk/gateway/security/audit-checks.md | 231 +++--- docs/uk/help/testing.md | 783 +++++++++---------- docs/uk/plugins/architecture-internals.md | 840 ++++++++++----------- docs/uk/plugins/codex-harness.md | 502 ++++++------ docs/uk/plugins/community.md | 104 +-- docs/uk/plugins/manifest.md | 733 +++++++++++------- docs/uk/tools/acp-agents.md | 448 ++++++----- docs/uk/tools/plugin.md | 429 ++++++----- docs/uk/tools/subagents.md | 418 +++++----- 14 files changed, 3087 insertions(+), 2979 deletions(-) diff --git a/docs/uk/cli/plugins.md b/docs/uk/cli/plugins.md index 6cc48c7a5..d965fe70f 100644 --- a/docs/uk/cli/plugins.md +++ b/docs/uk/cli/plugins.md @@ -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 openclaw plugins marketplace list --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 --marketplace # marketplace (явно) openclaw plugins install --marketplace https://github.com// ``` -Прості назви пакетів спочатку перевіряються в 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 `. +`--force` повторно використовує наявну ціль встановлення і перезаписує вже встановлений плагін або набір хуків на місці. Використовуйте його, коли ви свідомо перевстановлюєте той самий id з нового локального шляху, архіву, пакета ClawHub або артефакту npm. Для звичайних оновлень уже відстежуваного npm-плагіна віддавайте перевагу `openclaw plugins update `. -Якщо ви запускаєте `plugins install` для id плагіна, який уже встановлено, OpenClaw зупиняється й указує на `plugins update ` для звичайного оновлення або на `plugins install --force`, якщо ви справді хочете перезаписати поточне встановлення з іншого джерела. +Якщо ви запускаєте `plugins install` для id плагіна, який уже встановлено, OpenClaw зупиняється і пропонує `plugins update ` для звичайного оновлення або `plugins install --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:`: @@ -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 @@ -130,21 +130,21 @@ openclaw plugins install --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 --json` показує зареєстровані хуки та diagnostics із проходу inspection після завантаження модуля. -- `openclaw gateway status --deep --require-rpc` підтверджує досяжний Gateway, підказки щодо service/process, шлях до конфігурації та стан RPC. -- Невбудовані conversation hooks (`llm_input`, `llm_output`, `agent_end`) потребують `plugins.entries..hooks.allowConversationAccess=true`. +- `openclaw plugins inspect --json` показує зареєстровані хуки та діагностику з проходу перевірки завантаженого модуля. +- `openclaw gateway status --deep --require-rpc` підтверджує доступний Gateway, підказки щодо service/process, шлях до конфігурації та стан RPC. +- Для невбудованих хуків розмови (`llm_input`, `llm_output`, `agent_end`) потрібно `plugins.entries..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 --dry-run openclaw plugins uninstall --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 плагіна, OpenClaw повторно використовує записану специфікацію встановлення для цього плагіна. Це означає, що раніше збережені dist-tag, наприклад `@beta`, і точні закріплені версії надалі також використовуватимуться в наступних запусках `update `. -Для встановлень із 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 openclaw plugins inspect --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 openclaw plugins marketplace list --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) diff --git a/docs/uk/concepts/agent-runtimes.md b/docs/uk/concepts/agent-runtimes.md index 7d60d58b4..b1df415d0 100644 --- a/docs/uk/concepts/agent-runtimes.md +++ b/docs/uk/concepts/agent-runtimes.md @@ -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=` примусово задає цей runtime для нових або скинутих сесій. +## Вибір середовища виконання + +OpenClaw вибирає вбудоване середовище виконання після визначення постачальника й моделі: + +1. Пріоритет має записане для сесії середовище виконання. Зміни конфігурації не перемикають + на гарячу вже наявний транскрипт на іншу нативну систему тредів. +2. `OPENCLAW_AGENT_RUNTIME=` примусово задає це середовище виконання для нових або скинутих сесій. 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) diff --git a/docs/uk/gateway/bonjour.md b/docs/uk/gateway/bonjour.md index b2cab9260..40d86bcd3 100644 --- a/docs/uk/gateway/bonjour.md +++ b/docs/uk/gateway/bonjour.md @@ -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/.db` Перевірте з машини, підключеної до tailnet: @@ -69,55 +69,55 @@ dig @ -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=.local` -- `gatewayPort=` (Gateway WS + HTTP) +- `gatewayPort=` (WS + HTTP Gateway) - `gatewayTls=1` (лише коли TLS увімкнено) -- `gatewayTlsSha256=` (лише коли TLS увімкнено і відбиток доступний) -- `canvasPort=` (лише коли хост canvas увімкнено; наразі той самий, що й `gatewayPort`) +- `gatewayTlsSha256=` (лише коли TLS увімкнено і доступний відбиток) +- `canvasPort=` (лише коли ввімкнено хост canvas; наразі такий самий, як `gatewayPort`) - `transport=gateway` -- `tailnetDns=` (лише в режимі mDNS full; необов’язкова підказка, коли Tailnet доступний) -- `sshPort=` (лише в режимі mDNS full; wide-area DNS-SD може його не містити) -- `cliPath=` (лише в режимі mDNS full; wide-area DNS-SD усе одно записує його як підказку для віддаленого встановлення) +- `tailnetDns=` (лише у повному режимі mDNS, необов’язкова підказка, коли доступний Tailnet) +- `sshPort=` (лише у повному режимі mDNS; DNS-SD широкої зони може його не включати) +- `cliPath=` (лише у повному режимі 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 "" _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) diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 044b26416..facfc0dbf 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -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..enabled: false` вимикає skill, навіть якщо він bundled/installed. -- `entries..apiKey`: зручне поле для skills, які оголошують основну змінну середовища (простий рядок або об’єкт SecretRef). +- `entries..enabled: false` вимикає Skill, навіть якщо він bundled/встановлений. +- `entries..apiKey`: спрощене поле для Skills, що оголошують основну env-змінну (простий рядок або об’єкт SecretRef). --- @@ -158,48 +160,40 @@ bundled каналів (автентифікація, контроль дост } ``` -- Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також з `plugins.load.paths`. -- Виявлення підтримує нативні Plugin OpenClaw, а також сумісні пакети Codex і Claude, включно з пакетами Claude типового макета без маніфесту. -- **Зміни конфігурації вимагають перезапуску gateway.** -- `allow`: необов’язковий список дозволених (завантажуються лише перелічені Plugin). `deny` має пріоритет. -- `plugins.entries..apiKey`: зручне поле API-ключа на рівні Plugin (коли Plugin це підтримує). -- `plugins.entries..env`: мапа змінних середовища в межах Plugin. -- `plugins.entries..hooks.allowPromptInjection`: якщо `false`, ядро блокує `before_prompt_build` та ігнорує поля мутації prompt із застарілого `before_agent_start`, при цьому зберігає застарілі `modelOverride` і `providerOverride`. Застосовується до нативних хуків Plugin і підтримуваних каталогів хуків, наданих пакетами. -- `plugins.entries..hooks.allowConversationAccess`: якщо `true`, довірені небандловані Plugin можуть читати необроблений вміст розмови з типізованих хуків, таких як `llm_input`, `llm_output` і `agent_end`. -- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запит перевизначень `provider` і `model` для окремих запусків фонових subagent. -- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли свідомо хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, якщо вона доступна). -- Налаштування облікових записів/середовища виконання Plugin-каналів містяться в `channels.` і мають описуватися метаданими `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`, `/.openclaw/extensions`, а також `plugins.load.paths`. +- Виявлення підтримує нативні Plugin OpenClaw, а також сумісні пакунки Codex і Claude, зокрема пакунки Claude стандартного макета без маніфесту. +- **Зміни конфігурації потребують перезапуску gateway.** +- `allow`: необов’язковий список дозволів (завантажуються лише перелічені Plugin). `deny` має пріоритет. +- `plugins.entries..apiKey`: спрощене поле API-ключа на рівні Plugin (коли підтримується Plugin). +- `plugins.entries..env`: карта env-змінних у межах Plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` і ігнорує поля, що змінюють prompt, із застарілого `before_agent_start`, водночас зберігаючи застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hooks Plugin і підтримуваних каталогів hooks, наданих пакунками. +- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені небандловані Plugin можуть читати необроблений вміст розмови з типізованих hooks, таких як `llm_input`, `llm_output` і `agent_end`. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремих запусків фонових subagent. +- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"`, лише якщо ви свідомо хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (перевіряється схемою нативного Plugin OpenClaw, якщо доступна). +- Налаштування облікових записів/середовища виконання channel Plugin розміщуються в `channels.` і мають описуватися метаданими `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..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 каналів (автентифікація, контроль дост } ``` - + -- `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..healthMonitor.enabled`: відмова на рівні каналу від перезапусків монітора стану зі збереженням глобального монітора увімкненим. -- `channels..accounts..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..healthMonitor.enabled`: відмова від перезапусків health-monitor для окремого каналу зі збереженням глобального моніторингу. +- `channels..accounts..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. -### 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 ` (використовує `~/.openclaw-`). -Див. [Кілька 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 ` або `x-openclaw-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 ` або `x-openclaw-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/` → розв’язується через `hooks.mappings` - - Значення `sessionKey` у mapping, згенеровані шаблоном, вважаються зовнішньо наданими й також потребують `hooks.allowRequestSessionKey=true`. + - Значення `sessionKey` у mapping, згенеровані через шаблон, вважаються зовнішньо наданими й також вимагають `hooks.allowRequestSessionKey=true`. - + -- `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 (має бути дозволена, якщо задано каталог моделей). -### Інтеграція 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 ` або `x-openclaw-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 ` або `x-openclaw-token: `. } ``` -- Обслуговує HTML/CSS/JS і A2UI, які може редагувати агент, через HTTP на порту Gateway: +- Обслуговує HTML/CSS/JS, які може редагувати агент, і A2UI через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__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 ` або `x-openclaw-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 ` або `x-openclaw-token: `. ## Середовище -### `env` (вбудовані змінні середовища) +### `env` (вбудовані env-змінні) ```json5 { @@ -692,14 +687,14 @@ Auth: `Authorization: Bearer ` або `x-openclaw-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 ` або `x-openclaw-token: `. } ``` -- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. -- Екрануйте через `$${VAR}` для буквального `${VAR}`. +- Використовуйте `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. --- ## Секрети -Посилання на секрети є адитивними: прості текстові значення теж продовжують працювати. +Посилання на секрети є адитивними: прості текстові значення також продовжують працювати. ### `SecretRef` @@ -734,13 +729,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-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 ` або `x-openclaw-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 ` або `x-openclaw-token: `. } ``` -- Профілі для кожного агента зберігаються в `/auth-profiles.json`. +- Профілі для окремих агентів зберігаються в `/auth-profiles.json`. - `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. -- Профілі в режимі OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілю auth на основі SecretRef. -- Статичні облікові дані середовища виконання надходять зі знімків, розв’язаних у пам’яті; застарілі статичні записи `auth.json` очищуються під час виявлення. -- Застарілий імпорт OAuth здійснюється з `~/.openclaw/credentials/oauth.json`. +- Профілі режиму OAuth (`auth.profiles..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 ` або `x-openclaw-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 ` або `x-openclaw-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 ` або `x-openclaw-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 ` або `x-openclaw-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 ` або `x-openclaw-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 ` або `x-openclaw-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 ` або `x-openclaw-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` може прибрати невідомі ключі). @@ -1090,11 +1085,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `sessionRetention`: як довго зберігати завершені сесії ізольованих запусків cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. Типово: `24h`; задайте `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір файла журналу на запуск (`cron/runs/.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/.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 ` або `x-openclaw-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 ` або `x-openclaw-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 ` або `x-openclaw-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 ` або `x-openclaw-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 ` або `x-openclaw-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) diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index 4addc391f..120f8e11a 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -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.`. -- Перевірки міграції браузера для застарілих конфігурацій розширення 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.`. Doctor переписує старі форми -`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / -`talk.apiKey` у мапу провайдера. +Сюди входять і застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. 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.` - `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..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний акаунт. -- Якщо `channels..defaultAccount` вказує на невідомий ID акаунта, doctor попереджає та перелічує налаштовані ID акаунтів. +- Якщо налаштовано два або більше записи `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що fallback routing може вибрати неочікуваний акаунт. +- Якщо `channels..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//sessions/` -- Каталог агента: +- Каталог agent: - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` - Стан автентифікації WhatsApp (Baileys): - - із застарілого `~/.openclaw/credentials/*.json` (крім `oauth.json`) - - до `~/.openclaw/credentials/whatsapp//...` (типовий id акаунта: `default`) + - із застарілих `~/.openclaw/credentials/*.json` (крім `oauth.json`) + - до `~/.openclaw/credentials/whatsapp//...` (типовий 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 ` -- виконати ротацію нового токена за допомогою `openclaw devices rotate --device --role ` -- видалити та повторно схвалити застарілий запис за допомогою `openclaw devices remove ` +- перегляньте очікувані запити за допомогою `openclaw devices list` +- схваліть точний запит за допомогою `openclaw devices approve ` +- виконайте ротацію нового токена за допомогою `openclaw devices rotate --device --role ` +- видаліть і повторно схваліть застарілий запис за допомогою `openclaw devices remove ` -Це закриває поширену проблему "вже сполучено, але все ще потрібно сполучення": -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) diff --git a/docs/uk/gateway/security/audit-checks.md b/docs/uk/gateway/security/audit-checks.md index c4a95eb28..79d385e2a 100644 --- a/docs/uk/gateway/security/audit-checks.md +++ b/docs/uk/gateway/security/audit-checks.md @@ -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//agent/auth-profiles.json` | так | -| `fs.auth_profiles.perms_readable` | warn | Інші можуть читати API key і OAuth token | права для `agents//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//agent/auth-profiles.json` | так | +| `fs.auth_profiles.perms_readable` | попередження | Інші можуть читати API-ключі та OAuth-токени | дозволи для `agents//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) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 2907ad62d..e0f41cab4 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,26 +1,26 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для багів моделі/провайдера + - Додавання регресійних тестів для багів моделей/провайдерів - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' +summary: 'Набір тестування: набори unit/e2e/live, ранери Docker і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-25T22:53:51Z" + generated_at: "2026-04-26T00:18:19Z" model: gpt-5.4 provider: openai - source_hash: f75a132d527cc81329a93cdf47859622e2ac5347d7e9ab922bbd604948a43bf4 + source_hash: 106fd042e6b065595df0b7c7667cb0e07aceff28d88bb2cd59752c0946ba2edd source_path: help/testing.md workflow: 15 --- OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір -Docker-ранерів. Цей документ — посібник «як ми тестуємо»: +ранерів Docker. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює). - Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. -- Як додавати регресійні тести для реальних проблем моделей/провайдерів. +- Як додавати регресійні тести для реальних проблем із моделями/провайдерами. ## Швидкий старт @@ -28,11 +28,11 @@ Docker-ранерів. Цей документ — посібник «як ми - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` - Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` -- Прямий цикл watch для Vitest: `pnpm test:watch` -- Пряме націлювання на файл тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Коли ви ітеруєтеся над однією помилкою, спочатку віддавайте перевагу цільовим запускам. +- Прямий цикл спостереження Vitest: `pnpm test:watch` +- Прямий таргетинг файлу тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` +- Під час ітерацій над однією проблемою спочатку віддавайте перевагу цільовим запускам. - QA-сайт на базі Docker: `pnpm qa:lab:up` -- QA-lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- QA lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` Коли ви змінюєте тести або хочете додаткової впевненості: @@ -41,125 +41,133 @@ Docker-ранерів. Цей документ — посібник «як ми Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + tool/image-проби Gateway): `pnpm test:live` -- Тихо націлитися на один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Набір live (моделі + зондування tool/image через Gateway): `pnpm test:live` +- Тихо націлити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` - Docker sweep live-моделей: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер виконує текстовий хід плюс невелику пробу у стилі читання файлу. - Моделі, у metadata яких вказано вхід `image`, також виконують невеликий хід із зображенням. - Вимкніть додаткові проби через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або + - Кожна вибрана модель тепер виконує текстовий хід плюс невелике зондування у стилі читання файлу. + Моделі, чиї метадані вказують на вхід `image`, також виконують невеликий хід із зображенням. + Вимкніть додаткові зондування через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні - `OpenClaw Release Checks` обидва викликають повторно використовуваний live/E2E workflow з - `include_live_suites: true`, що включає окремі matrix-job для Docker live-моделей, - розшардовані за провайдерами. - - Для цільових повторних запусків у CI запустіть `OpenClaw Live And E2E Checks (Reusable)` + `OpenClaw Release Checks` обидва викликають повторно використовуваний workflow live/E2E з + `include_live_suites: true`, який включає окремі matrix jobs Docker live-моделей, + розбиті за провайдерами. + - Для точкових повторних запусків у CI викликайте `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, + - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його - scheduled/release-викликачів. -- Native Codex smoke bound-chat: `pnpm test:docker:live-codex-bind` - - Запускає Docker live-lane проти шляху app-server Codex, прив’язує синтетичний + викликів зі schedule/release. +- Native Codex smoke для bound-chat: `pnpm test:docker:live-codex-bind` + - Запускає Docker live lane проти шляху Codex app-server, прив’язує синтетичний Slack DM через `/codex bind`, виконує `/codex fast` і `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення-зображення - проходять через native binding Plugin, а не через ACP. -- Smoke команди відновлення Crestodian: `pnpm test:live:crestodian-rescue-channel` - - Opt-in перевірка belt-and-suspenders для поверхні rescue command у message-channel. - Вона виконує `/crestodian status`, ставить у чергу постійну + проходять через native Plugin binding, а не через ACP. +- Smoke команди rescue для Crestodian: `pnpm test:live:crestodian-rescue-channel` + - Необов’язкова додаткова перевірка поверхні команди rescue для message-channel. + Вона виконує `/crestodian status`, ставить у чергу стійку зміну моделі, відповідає `/crestodian yes` і перевіряє шлях запису audit/config. -- Docker smoke планувальника Crestodian: `pnpm test:docker:crestodian-planner` - - Запускає Crestodian у контейнері без config із фейковим Claude CLI у `PATH` - і перевіряє, що fuzzy planner fallback перетворюється на типізований запис config з audit. -- Docker smoke першого запуску Crestodian: `pnpm test:docker:crestodian-first-run` - - Починає з порожнього state-dir OpenClaw, маршрутизує `openclaw` без аргументів до +- Docker smoke planner для Crestodian: `pnpm test:docker:crestodian-planner` + - Запускає Crestodian у контейнері без конфігурації з фальшивим Claude CLI у `PATH` + і перевіряє, що нечіткий fallback planner перетворюється на audited typed + запис у конфігурацію. +- Docker smoke першого запуску для Crestodian: `pnpm test:docker:crestodian-first-run` + - Стартує з порожнього каталогу стану OpenClaw, маршрутизує голий `openclaw` до Crestodian, застосовує записи setup/model/agent/Discord Plugin + SecretRef, - перевіряє config і перевіряє записи audit. Той самий шлях налаштування Ring 0 - також покривається в QA Lab командою + перевіряє конфігурацію та записи audit. Той самий шлях налаштування Ring 0 + також охоплюється в QA Lab через `pnpm openclaw qa suite --scenario crestodian-ring-zero-setup`. - Smoke перевірка вартості Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, а потім виконайте ізольований + `openclaw models list --provider moonshot --json`, потім виконайте ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - проти `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє про Moonshot/K2.6, а - transcript помічника зберігає нормалізоване `usage.cost`. + проти `moonshot/kimi-k2.6`. Перевірте, що JSON повідомляє Moonshot/K2.6 і що + transcript асистента зберігає нормалізоване `usage.cost`. Порада: коли вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через env-змінні allowlist, описані нижче. -## QA-специфічні ранери +## Спеціальні ранери для QA -Ці команди розташовані поруч із основними наборами тестів, коли вам потрібна реалістичність QA-lab: +Ці команди стоять поруч з основними наборами тестів, коли вам потрібен реалізм QA-lab: -CI запускає QA Lab в окремих workflow. `Parity gate` запускається на відповідних PR і -з ручного dispatch із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на -`main` і з ручного dispatch з mock parity gate, live Matrix lane і +CI запускає QA Lab в окремих workflow. `Parity gate` запускається для відповідних PR +і через ручний dispatch з mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і через ручний dispatch із mock parity gate, live Matrix lane і керованим Convex live Telegram lane як паралельними jobs. `OpenClaw Release Checks` -запускає ті самі lanes перед схваленням релізу. +запускає ті самі lane перед затвердженням релізу. - `pnpm openclaw qa suite` - - Запускає QA-сценарії на основі репозиторію безпосередньо на хості. + - Запускає сценарії QA на базі репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - workers Gateway. `qa-channel` за замовчуванням має concurrency 4 (обмежено - кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати кількість - workers, або `--concurrency 1` для старішого послідовного lane. - - Завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, коли + worker-и Gateway. Для `qa-channel` типовим є concurrency 4 (обмежується + кількістю вибраних сценаріїв). Використовуйте `--concurrency ` для налаштування + кількості worker-ів або `--concurrency 1` для старішого послідовного lane. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнав невдачі. Використовуйте `--allow-failures`, коли вам потрібні артефакти без коду завершення з помилкою. - - Підтримує режими провайдера `live-frontier`, `mock-openai` і `aimock`. + - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття фікстур і mock протоколу без заміни lane `mock-openai`, що знає про сценарії. + покриття фікстур і protocol-mock без заміни lane `mock-openai`, + орієнтованого на сценарії. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір усередині disposable Linux VM Multipass. + - Запускає той самий QA suite всередині тимчасової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані QA auth-входи, практичні для guest: - env-ключі провайдерів, шлях до config live-провайдера QA і `CODEX_HOME`, якщо присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через - змонтований workspace. - - Записує звичайний QA report + summary, а також логи Multipass у + - Live-запуски передають підтримувані вхідні дані автентифікації QA, практичні для guest: + ключі провайдерів через env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, + якщо він наявний. + - Каталоги виводу мають залишатися під коренем репозиторію, щоб guest міг записувати назад через + змонтований робочий простір. + - Записує звичайний звіт і підсумок QA, а також логи Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. + - Запускає QA-сайт на базі Docker для операторської роботи в QA. - `pnpm test:docker:npm-onboard-channel-agent` - Збирає npm tarball з поточного checkout, глобально встановлює його в - Docker, виконує неінтерактивний onboarding із ключем OpenAI API, налаштовує Telegram - за замовчуванням, перевіряє, що ввімкнення Plugin встановлює runtime-залежності за потреби, - запускає doctor і виконує один локальний хід агента проти mock endpoint OpenAI. + Docker, виконує неінтерактивний onboarding з ключем OpenAI API, за замовчуванням налаштовує Telegram, + перевіряє, що ввімкнення Plugin встановлює runtime-залежності на вимогу, + запускає doctor і один локальний хід агента проти mocked OpenAI endpoint. - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий lane - встановлення з пакета для Discord. + пакетного встановлення з Discord. +- `pnpm test:docker:session-runtime-context` + - Запускає детермінований Docker smoke для зібраного застосунку для transcript-ів із + вбудованим runtime context. Перевіряє, що прихований runtime context OpenClaw + зберігається як недоступне для відображення кастомне повідомлення замість витоку у видимий хід користувача, + потім підставляє уражений зламаний JSONL сесії та перевіряє, що + `openclaw doctor --fix` переписує його в активну гілку з резервною копією. - `pnpm test:docker:npm-telegram-live` - Встановлює опублікований пакет OpenClaw у Docker, виконує onboarding встановленого пакета, налаштовує Telegram через встановлений CLI, а потім повторно використовує - live Telegram QA lane з цим встановленим пакетом як SUT Gateway. - - За замовчуванням використовує `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`. - - Використовує ті самі облікові дані Telegram через env або джерело облікових даних Convex, що й + QA lane live Telegram із цим встановленим пакетом як SUT Gateway. + - За замовчуванням використовується `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`. + - Використовує ті самі env-облікові дані Telegram або джерело облікових даних Convex, що й `pnpm openclaw qa telegram`. Для автоматизації CI/release встановіть - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` разом із - `OPENCLAW_QA_CONVEX_SITE_URL` і секретом ролі. Якщо - `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі Convex присутні в CI, - Docker-обгортка автоматично вибирає Convex. + `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex`, а також + `OPENCLAW_QA_CONVEX_SITE_URL` і role secret. Якщо + `OPENCLAW_QA_CONVEX_SITE_URL` і secret ролі Convex присутні в CI, + обгортка Docker автоматично вибирає Convex. - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільний `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цього lane. - GitHub Actions надає цей lane як ручний workflow для мейнтейнерів `NPM Telegram Beta E2E`. Він не запускається при merge. Workflow використовує середовище `qa-live-shared` і оренду облікових даних Convex CI. - `pnpm test:docker:bundled-channel-deps` - - Пакує та встановлює поточний білд OpenClaw у Docker, запускає Gateway - з налаштованим OpenAI, а потім вмикає bundled channel/plugins через редагування config. - - Перевіряє, що виявлення setup залишає відсутніми runtime-залежності - не налаштованих plugin, що перший налаштований запуск Gateway або doctor встановлює runtime-залежності - кожного bundled plugin за потреби, і що другий restart не перевстановлює залежності, - які вже були активовані. - - Також установлює відому старішу npm-базу, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що post-update doctor - кандидата виправляє runtime-залежності bundled channel без postinstall-виправлення - з боку harness. + - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway + зі сконфігурованим OpenAI, а потім вмикає bundled channel/plugins через зміни конфігурації. + - Перевіряє, що виявлення setup залишає runtime-залежності + не налаштованих Plugin відсутніми, що перший налаштований запуск Gateway або doctor + встановлює runtime-залежності кожного bundled Plugin на вимогу, і що другий restart + не перевстановлює залежності, які вже були активовані. + - Також встановлює відому старішу npm-базову версію, вмикає Telegram перед запуском + `openclaw update --tag `, а потім перевіряє, що + post-update doctor у candidate відновлює runtime-залежності bundled channel без + postinstall-виправлення з боку harness. - `pnpm test:parallels:npm-update` - - Запускає native smoke перевірки оновлення встановленого пакета на гостях Parallels. Кожна - вибрана платформа спочатку встановлює запитаний базовий пакет, потім запускає - встановлену команду `openclaw update` у тому самому guest і перевіряє встановлену версію, - статус оновлення, готовність gateway і один локальний хід агента. - - Використовуйте `--platform macos`, `--platform windows` або `--platform linux`, поки - ітеруєтеся над одним guest. Використовуйте `--json` для шляху до summary artifact і - статусу кожного lane. - - Обгортайте довгі локальні запуски в host timeout, щоб зависання транспорту Parallels не - поглинало решту вікна тестування: + - Запускає native smoke оновлення пакетного встановлення в guest-системах Parallels. Для кожної + вибраної платформи спочатку встановлюється потрібний базовий пакет, а потім у тій самій guest-системі + запускається встановлена команда `openclaw update` і перевіряються встановлена версія, + статус оновлення, готовність Gateway і один локальний хід агента. + - Під час ітерацій над однією guest-системою використовуйте `--platform macos`, `--platform windows` або `--platform linux`. + Використовуйте `--json` для шляху до підсумкового артефакту і статусу кожного lane. + - Обгортайте довгі локальні запуски в host timeout, щоб зависання транспорту Parallels + не з’їли решту вікна тестування: ```bash timeout --foreground 150m pnpm test:parallels:npm-update -- --json @@ -168,54 +176,54 @@ CI запускає QA Lab в окремих workflow. `Parity gate` запус - Скрипт записує вкладені логи lane у `/tmp/openclaw-parallels-npm-update.*`. Перевіряйте `windows-update.log`, `macos-update.log` або `linux-update.log`, - перш ніж вважати, що зовнішня обгортка зависла. + перш ніж припускати, що зовнішня обгортка зависла. - Оновлення Windows може витрачати від 10 до 15 хвилин на post-update doctor/runtime - repair залежностей на «холодному» guest; це все ще є нормальним, якщо вкладений - npm debug log просувається. - - Не запускайте цю агреговану обгортку паралельно з окремими smoke lanes Parallels - для macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати через - відновлення snapshot, роздавання пакетів або стан guest gateway. - - Доказ після оновлення запускає звичайну поверхню bundled plugin, тому що - capability facades, як-от speech, image generation і media - understanding, завантажуються через bundled runtime API навіть тоді, коли сам - хід агента перевіряє лише просту текстову відповідь. + repair залежностей на холодній guest-системі; це все ще нормальний стан, якщо вкладений + npm debug log продовжує оновлюватися. + - Не запускайте цю агреговану обгортку паралельно з окремими smoke lane Parallels для + macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати під час + відновлення snapshot, обслуговування пакетів або стану guest Gateway. + - Post-update proof запускає звичайну поверхню bundled Plugin, оскільки + capability facades, такі як speech, генерація зображень і + розуміння медіа, завантажуються через bundled runtime API, навіть коли сам хід агента + перевіряє лише просту текстову відповідь. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування - протоколу. + - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - - Запускає live QA-lane Matrix проти disposable homeserver Tuwunel на базі Docker. - - Цей QA-хост наразі призначений лише для репозиторію/розробки. Пакетні встановлення OpenClaw не постачають - `qa-lab`, тому вони не надають `openclaw qa`. - - Checkout репозиторію напряму завантажують bundled runner; окремий крок встановлення Plugin не потрібен. - - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) і одну приватну кімнату, а потім запускає дочірній QA gateway з реальним Matrix Plugin як транспортом SUT. + - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на базі Docker. + - Цей QA host наразі призначений лише для repo/dev. Пакетні встановлення OpenClaw не постачають + `qa-lab`, тому не відкривають `openclaw qa`. + - Checkout-и репозиторію завантажують bundled runner напряму; окремий крок встановлення Plugin не потрібен. + - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway з реальним Plugin Matrix як транспортом SUT. - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. - - Matrix не надає спільних прапорців джерела облікових даних, оскільки lane локально створює disposable користувачів. - - Записує Matrix QA report, summary, артефакт observed-events і комбінований лог виводу stdout/stderr у `.artifacts/qa-e2e/...`. - - За замовчуванням виводить прогрес і застосовує жорсткий timeout запуску через `OPENCLAW_QA_MATRIX_TIMEOUT_MS` (за замовчуванням 30 хвилин). Очищення обмежується `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`, а у випадку помилок включається команда відновлення `docker compose ... down --remove-orphans`. + - Matrix не надає спільних прапорців джерела облікових даних, оскільки lane локально створює тимчасових користувачів. + - Записує звіт Matrix QA, підсумок, артефакт observed-events і об’єднаний лог виводу stdout/stderr у `.artifacts/qa-e2e/...`. + - За замовчуванням виводить прогрес і примусово застосовує жорсткий timeout виконання через `OPENCLAW_QA_MATRIX_TIMEOUT_MS` (типово 30 хвилин). Очищення обмежується `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`, а у випадку збоїв включається команда відновлення `docker compose ... down --remove-orphans`. - `pnpm openclaw qa telegram` - - Запускає live QA-lane Telegram проти реальної приватної групи, використовуючи токени ботів driver і SUT з env. - - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. - - Підтримує `--credential-source convex` для спільних пулінгових облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути пулінгові lease. - - Завершується з ненульовим кодом, якщо будь-який сценарій завершується невдачею. Використовуйте `--allow-failures`, коли вам потрібні артефакти без коду завершення з помилкою. - - Потребує двох різних ботів в одній приватній групі, причому бот SUT має надавати Telegram username. + - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени ботів driver і SUT з env. + - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим chat id Telegram. + - Підтримує `--credential-source convex` для спільних пулованих облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб перейти на пуловані lease. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнав невдачі. Використовуйте `--allow-failures`, коли + вам потрібні артефакти без коду завершення з помилкою. + - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати username Telegram. - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. - - Записує Telegram QA report, summary і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання driver до спостереженої відповіді SUT. + - Записує звіт Telegram QA, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання від driver до спостережуваної відповіді SUT. -Live transport lanes мають один спільний стандартний контракт, щоб нові транспорти не відхилялися: +Live transport lane використовують один стандартний контракт, щоб нові транспорти не розходилися: -`qa-channel` залишається широким синтетичним QA-набором і не є частиною matrix покриття live transport. +`qa-channel` залишається широким синтетичним набором QA і не входить до матриці покриття live transport. -| Lane | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після restart | Follow-up у thread | Ізоляція thread | Спостереження реакцій | Команда help | -| -------- | ------ | -------------- | -------------------- | ------------------------- | ------------------------- | ------------------ | --------------- | --------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Фільтрація за згадуванням | Блокування allowlist | Відповідь верхнього рівня | Відновлення після restart | Подальша відповідь у треді | Ізоляція тредів | Спостереження за реакціями | Команда help | +| -------- | ------ | ------------------------- | -------------------- | ------------------------- | ------------------------- | -------------------------- | --------------- | -------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Спільні облікові дані Telegram через Convex (v1) Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивний lease із пулу на базі Convex, надсилає Heartbeat -цього lease, поки lane виконується, і звільняє lease під час завершення. +для цього lease, поки lane виконується, і звільняє lease під час завершення роботи. Еталонний scaffold проєкту Convex: @@ -229,24 +237,24 @@ QA lab отримує ексклюзивний lease із пулу на базі - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (у CI за замовчуванням `ci`, інакше `maintainer`) + - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) Необов’язкові env-змінні: -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (за замовчуванням `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (за замовчуванням `30000`) -- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (за замовчуванням `90000`) -- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (за замовчуванням `15000`) -- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (за замовчуванням `/qa-credentials/v1`) +- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) +- `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (типово `90000`) +- `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (типово `15000`) +- `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (типово `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL Convex лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback URL Convex `http://` лише для локальної розробки. -У звичайному режимі `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. +У звичайному режимі роботи `OPENCLAW_QA_CONVEX_SITE_URL` має використовувати `https://`. -Адміністративні команди maintainer (`add/remove/list` у пулі) потребують саме -`OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. +Адміністративні команди мейнтейнера (додавання/видалення/список пулу) потребують +саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-хелпери для maintainer: +CLI-хелпери для мейнтейнерів: ```bash pnpm openclaw qa credentials doctor @@ -255,9 +263,10 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, секрети broker, -prefix endpoint, HTTP timeout і доступність admin/list без виведення -значень секретів. Використовуйте `--json` для машиночитаного виводу у скриптах і CI-утилітах. +Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, секрети брокера, +префікс endpoint, HTTP timeout і доступність admin/list без виведення +значень секретів. Використовуйте `--json` для машиночитаного виводу в скриптах і CI +утилітах. Контракт endpoint за замовчуванням (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): @@ -282,63 +291,63 @@ prefix endpoint, HTTP timeout і доступність admin/list без вив - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` -Форма payload для виду Telegram: +Форма payload для типу Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком із числовим Telegram chat id. -- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректний payload. +- `groupId` має бути рядком із числовим chat id Telegram. +- `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні payload. ### Додавання каналу до QA Додавання каналу до markdown-системи QA потребує рівно двох речей: -1. Адаптер транспорту для каналу. -2. Набір сценаріїв, що перевіряє контракт каналу. +1. Транспортний адаптер для каналу. +2. Пакет сценаріїв, який перевіряє контракт каналу. -Не додавайте новий кореневий QA-командний простір верхнього рівня, коли спільний хост `qa-lab` може -володіти цим потоком. +Не додавайте новий кореневий top-level-командний простір QA, якщо спільний host `qa-lab` +може керувати цим потоком. -`qa-lab` володіє спільною механікою хоста: +`qa-lab` керує спільною механікою host: - кореневою командою `openclaw qa` -- запуском і завершенням набору -- concurrency workers +- запуском і завершенням suite +- паралелізмом worker-ів - записом артефактів -- генерацією report +- генерацією звітів - виконанням сценаріїв - alias сумісності для старіших сценаріїв `qa-channel` -Runner Plugins володіють транспортним контрактом: +Runner Plugin володіють транспортним контрактом: - як `openclaw qa ` монтується під спільним коренем `qa` -- як налаштовується gateway для цього транспорту +- як Gateway конфігурується для цього транспорту - як перевіряється готовність - як інжектуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються transcript і нормалізований стан транспорту -- як виконуються дії на основі транспорту -- як обробляється transport-specific reset або cleanup +- як надаються transcript-и й нормалізований транспортний стан +- як виконуються дії, прив’язані до транспорту +- як обробляються транспортно-специфічні reset або cleanup Мінімальний поріг прийняття для нового каналу: -1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте transport runner на спільному seam хоста `qa-lab`. -3. Залишайте transport-specific механіку всередині runner Plugin або harness каналу. -4. Монтуйте runner як `openclaw qa `, а не реєструйте конкуруючу кореневу команду. - Runner Plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. - Тримайте `runtime-api.ts` легким; лінивий CLI і виконання runner мають залишатися за окремими entrypoint. -5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте generic helper для нових сценаріїв. -7. Зберігайте наявні alias сумісності, якщо тільки репозиторій не виконує навмисну міграцію. +1. Залишити `qa-lab` власником спільного кореня `qa`. +2. Реалізувати transport runner на спільному seam host `qa-lab`. +3. Залишити транспортно-специфічну механіку всередині runner Plugin або harness каналу. +4. Монтувати runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. + Runner Plugin мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. + Залишайте `runtime-api.ts` легким; ліниве виконання CLI і runner має бути винесене за окремі entrypoint. +5. Створювати або адаптувати markdown-сценарії в тематичних каталогах `qa/scenarios/`. +6. Для нових сценаріїв використовувати загальні scenario helper-и. +7. Зберігати працездатність наявних alias сумісності, якщо тільки репозиторій не виконує навмисну міграцію. -Правило прийняття рішення суворе: +Правило ухвалення рішення суворе: - Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від транспорту одного каналу, залишайте її в runner Plugin або harness цього Plugin. -- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додавайте generic helper замість channel-specific гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно зазначайте це в контракті сценарію. +- Якщо поведінка залежить від одного транспортного каналу, залишайте її в runner Plugin або harness цього Plugin. +- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додавайте загальний helper замість channel-specific гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій транспортно-специфічним і явно фіксуйте це в контракті сценарію. -Бажані назви generic helper для нових сценаріїв: +Для нових сценаріїв бажані назви загальних helper-ів: - `waitForTransportReady` - `waitForChannelReady` @@ -361,22 +370,22 @@ Alias сумісності залишаються доступними для н - `formatConversationTranscript` - `resetBus` -Нова робота над каналами має використовувати generic назви helper. -Alias сумісності існують, щоб уникнути міграції в один день, а не як модель для +Нова робота над каналами має використовувати загальні назви helper-ів. +Alias сумісності існують, щоб уникнути міграції «в один день», а не як модель для створення нових сценаріїв. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалістичності» (і зростання нестабільності/вартості): +Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): -### Unit / integration (за замовчуванням) +### Unit / integration (типово) - Команда: `pnpm test` -- Config: ненаправлені запуски використовують набір шардованих `vitest.full-*.config.ts` і можуть розгортати multi-project shards у per-project config для паралельного планування -- Файли: core/unit inventory у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelist node-тести `ui`, що покриваються `vitest.unit.config.ts` +- Конфігурація: нетаргетовані запуски використовують набір shard `vitest.full-*.config.ts` і можуть розгортати multi-project shard-и в конфігурації для окремих проєктів для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelisted node-тести `ui`, які охоплюються `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - In-process integration-тести (auth Gateway, маршрутизація, tooling, parsing, config) + - In-process integration-тести (автентифікація Gateway, маршрутизація, tooling, парсинг, конфігурація) - Детерміновані регресії для відомих багів - Очікування: - Запускається в CI @@ -384,45 +393,45 @@ Alias сумісності існують, щоб уникнути міграц - Має бути швидким і стабільним - + - - Ненаправлений `pnpm test` запускає дванадцять менших shard-config (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського нативного процесу root-project. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - - `pnpm test --watch` усе ще використовує нативний граф проєктів root `vitest.config.ts`, оскільки багатошардовий watch-цикл непрактичний. - - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - - `pnpm test:changed` розгортає змінені шляхи git у ті самі scoped lanes, коли diff зачіпає лише routable файли source/test; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. - - `pnpm check:changed` — це звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні typecheck/lint/test lanes. Зміни публічного Plugin SDK і plugin-contract включають один прохід валідації extension, оскільки extensions залежать від цих контрактів core. Бамп версії лише в release metadata запускає цільові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни package поза полем версії верхнього рівня. - - Unit-тести з легкими import із agents, commands, plugins, helper auto-reply, `plugin-sdk` та подібних чистих утилітних зон маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - - Вибрані helper source-файли `plugin-sdk` і `commands` також у режимі changed зіставляються з явними sibling-тестами в цих легких lanes, тож редагування helper уникають повторного запуску повного важкого набору для цього каталогу. - - `auto-reply` має окремі buckets для helper верхнього рівня core, integration-тестів верхнього рівня `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково ділить піддерево reply на shard agent-runner, dispatch і commands/state-routing, щоб один bucket із важкими import не володів усім Node tail. + - Нетаргетований `pnpm test` запускає дванадцять менших конфігурацій shard (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project процесу. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension витісняти не пов’язані набори. + - `pnpm test --watch` усе ще використовує native root-граф проєктів `vitest.config.ts`, оскільки цикл watch із кількома shard не є практичним. + - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scoped lane, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lane, коли diff зачіпає лише routable файли джерел/тестів; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. + - `pnpm check:changed` — це звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lane typecheck/lint/test. Зміни в публічному Plugin SDK і plugin-contract включають один прохід валідації extension, оскільки extensions залежать від цих контрактів core. Підвищення версії лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни пакета поза полем версії верхнього рівня. + - Unit-тести з легкими імпортами з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` і подібних чистих утилітних областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; файли зі станом/важким runtime залишаються в наявних lane. + - Вибрані helper-вихідники `plugin-sdk` і `commands` також зіставляють запуски в режимі changed з явними сусідніми тестами в цих легких lane, тож редагування helper-ів уникають повторного запуску повного важкого набору для цього каталогу. + - `auto-reply` має окремі кошики для top-level helper-ів core, top-level integration-тестів `reply.*` і піддерева `src/auto-reply/reply/**`. CI додатково розділяє піддерево reply на shard agent-runner, dispatch і commands/state-routing, щоб один кошик із важкими імпортами не контролював увесь tail Node. - - Коли ви змінюєте входи виявлення message-tool або runtime-контекст Compaction, - зберігайте обидва рівні покриття. - - Додавайте сфокусовані регресії helper для чистих меж маршрутизації та + - Коли ви змінюєте вхідні дані виявлення message-tool або runtime + context Compaction, зберігайте обидва рівні покриття. + - Додавайте сфокусовані регресії helper-ів для чистих меж маршрутизації та нормалізації. - - Підтримуйте здоровими integration-набори embedded runner: + - Підтримуйте інтеграційні набори embedded runner у здоровому стані: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка compaction усе ще проходять - через реальні шляхи `run.ts` / `compact.ts`; тести лише на helper - не є достатньою заміною для цих integration-шляхів. + - Ці набори перевіряють, що scoped id і поведінка compaction все ще проходять + через реальні шляхи `run.ts` / `compact.ts`; тести лише helper-ів + не є достатньою заміною для цих інтеграційних шляхів. - + - - Базовий config Vitest за замовчуванням використовує `threads`. - - Спільний config Vitest фіксує `isolate: false` і використовує + - Базова конфігурація Vitest типово використовує `threads`. + - Спільна конфігурація Vitest фіксує `isolate: false` і використовує неізольований runner у root projects, e2e і live config. - - Root lane UI зберігає свій `jsdom` setup і optimizer, але також працює на + - Root lane UI зберігає свій `jsdom` setup і optimizer, але теж запускається на спільному неізольованому runner. - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` - зі спільного config Vitest. - - `scripts/run-vitest.mjs` за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, + зі спільної конфігурації Vitest. + - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх процесів Node Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. @@ -431,300 +440,300 @@ Alias сумісності існують, щоб уникнути міграц - - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. - - Pre-commit hook відповідає лише за форматування. Він повторно додає відформатовані файли до staging і + - `pnpm changed:lanes` показує, які архітектурні lane зачіпає diff. + - Pre-commit hook виконує лише форматування. Він знову додає відформатовані файли до stage і не запускає lint, typecheck або тести. - - Явно запускайте `pnpm check:changed` перед передачею або push, коли - вам потрібен розумний локальний gate. Зміни публічного Plugin SDK і plugin-contract + - Явно запускайте `pnpm check:changed` перед передачею роботи або push, коли + вам потрібен розумний локальний gate. Зміни в публічному Plugin SDK і plugin-contract включають один прохід валідації extension. - - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи - чисто зіставляються з меншим набором. + - `pnpm test:changed` маршрутизує через scoped lane, коли змінені шляхи + чітко зіставляються з меншим набором. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - лише з вищим лімітом workers. - - Автоматичне масштабування локальних workers навмисно консервативне та знижує навантаження, + лише з вищим лімітом worker-ів. + - Автомасштабування локальних worker-ів навмисно є консервативним і зменшує навантаження, коли середнє навантаження хоста вже високе, тож кілька одночасних - запусків Vitest за замовчуванням завдають менше шкоди. - - Базовий config Vitest позначає файли projects/config як + запусків Vitest типово завдають менше шкоди. + - Базова конфігурація Vitest позначає файли projects/config як `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли - змінюється тестова обв’язка. - - Config тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + змінюється зв’язування тестів. + - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете - одну явну локацію кешу для прямого профілювання. + мати одну явну локацію кешу для прямого профілювання. - - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість import плюс - вивід breakdown import. - - `pnpm test:perf:imports:changed` звужує той самий профілювальний вигляд до - файлів, змінених від `origin/main`. - - Дані про час shard записуються в `.artifacts/vitest-shard-timings.json`. - Запуски цілих config використовують шлях config як ключ; CI-shards з include-pattern - додають назву shard, щоб відфільтровані shards можна було - відстежувати окремо. - - Коли один гарячий тест усе ще витрачає більшість часу на стартові import, + - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпортів плюс + вивід детального розбору імпортів. + - `pnpm test:perf:imports:changed` обмежує той самий режим профілювання + файлами, зміненими відносно `origin/main`. + - Дані часу shard записуються до `.artifacts/vitest-shard-timings.json`. + Запуски всієї конфігурації використовують шлях конфігурації як ключ; shard-и CI з include-pattern + додають назву shard, щоб відфільтровані shard можна було відстежувати + окремо. + - Коли один гарячий тест усе ще витрачає більшість часу на стартові імпорти, тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і - напряму мокайте цей seam замість глибокого import runtime-helper лише - для того, щоб передати їх у `vi.mock(...)`. + напряму mock-айте цей seam замість глибокого імпорту helper-ів runtime + лише для того, щоб передати їх у `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` із нативним шляхом root-project для цього зафіксованого + `test:changed` з native шляхом root-project для цього зафіксованого diff і виводить wall time плюс macOS max RSS. - - `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного - брудного дерева, маршрутизуючи список змінених файлів через - `scripts/test-projects.mjs` і root config Vitest. - - `pnpm test:perf:profile:main` записує CPU-профіль main-thread для - витрат запуску й transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує CPU+heap-профілі runner для - unit-набору з вимкненим файловим паралелізмом. + - `pnpm test:perf:changed:bench -- --worktree` вимірює поточне брудне дерево, + маршрутизуючи список змінених файлів через + `scripts/test-projects.mjs` і root-конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує профіль CPU основного потоку для + накладних витрат старту та transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner-а для + unit-набору з вимкненим паралелізмом файлів. -### Stability (Gateway) +### Стабільність (Gateway) - Команда: `pnpm test:stability:gateway` -- Config: `vitest.gateway.config.ts`, примусово один worker +- Конфігурація: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - - Запускає реальний loopback Gateway із діагностикою, увімкненою за замовчуванням - - Пропускає синтетичний churn повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій - - Запитує `diagnostics.stability` через WS RPC Gateway - - Покриває helper персистентності diagnostic stability bundle - - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS лишаються в межах бюджету тиску, а глибина черг на сесію повертається до нуля + - Запускає реальний loopback Gateway з діагностикою, увімкненою за замовчуванням + - Проганяє синтетичне навантаження повідомленнями gateway, пам’яттю та великими payload через шлях діагностичних подій + - Виконує запит до `diagnostics.stability` через WS RPC Gateway + - Охоплює helper-и збереження пакета діагностичної стабільності + - Перевіряє, що recorder залишається обмеженим, синтетичні зразки RSS лишаються в межах бюджету тиску, а глибини черг на сесію знову зменшуються до нуля - Очікування: - - Безпечно для CI і без ключів - - Вузький lane для подальшого аналізу регресій stability, а не заміна повного набору Gateway + - Безпечно для CI і не потребує ключів + - Вузький lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway -### E2E (smoke Gateway) +### E2E (smoke для gateway) - Команда: `pnpm test:e2e` -- Config: `vitest.e2e.config.ts` +- Конфігурація: `vitest.e2e.config.ts` - Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і bundled-plugin E2E-тести в `extensions/` -- Типові значення runtime: - - Використовує Vitest `threads` з `isolate: false`, як і в решті репозиторію. - - Використовує адаптивну кількість workers (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням працює в тихому режимі, щоб зменшити витрати на console I/O. +- Типові параметри runtime: + - Використовує `threads` Vitest з `isolate: false`, як і решта репозиторію. + - Використовує адаптивну кількість worker-ів (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням запускається в тихому режимі, щоб зменшити накладні витрати на вивід у консоль. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` для примусового задання кількості workers (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід console. + - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість worker-ів (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути детальний вивід у консоль. - Обсяг: - - Наскрізна поведінка multi-instance gateway - - Поверхні WebSocket/HTTP, pairинг Node і важча мережева взаємодія + - Наскрізна поведінка gateway з кількома екземплярами + - Поверхні WebSocket/HTTP, спарювання Node і важчий мережевий стек - Очікування: - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: smoke backend OpenShell +### E2E: smoke для backend OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - Запускає ізольований Gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + виконання SSH - - Перевіряє remote-canonical поведінку файлової системи через fs bridge sandbox + - Перевіряє backend OpenShell у OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локальний CLI `openshell` і справний Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox + - Потребує локальний CLI `openshell` і робочий Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, після чого знищує тестовий gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого e2e-набору + - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний бінарний файл CLI або wrapper-скрипт ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` -- Config: `vitest.live.config.ts` +- Конфігурація: `vitest.live.config.ts` - Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і bundled-plugin live-тести в `extensions/` -- За замовчуванням: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) +- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи цей провайдер/модель справді працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей виклику tool, проблем auth і поведінки rate limit + - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» + - Виявляє зміни формату провайдера, особливості виклику tool, проблеми автентифікації та поведінку rate limit - Очікування: - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - Коштує грошей / використовує rate limit - Краще запускати звужені підмножини, а не «все» - Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий тестовий home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. - Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно хочете, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але пригнічує додаткове повідомлення `~/.profile` і вимикає логи bootstrap Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. -- Ротація API-ключів (залежно від провайдера): встановіть `*_API_KEYS` у форматі ком/крапка з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використовуйте перевизначення для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. -- Вивід progress/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, щоб довгі виклики провайдерів було видно як активні навіть тоді, коли перехоплення console Vitest тихе. - - `vitest.live.config.ts` вимикає перехоплення console у Vitest, тож рядки прогресу провайдера/gateway транслюються одразу під час live-запусків. +- `pnpm test:live` тепер типово працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення про `~/.profile` і приглушує логи bootstrap Gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні стартові логи. +- Ротація API-ключів (специфічна для провайдера): встановлюйте `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для окремого live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. +- Вивід прогресу/Heartbeat: + - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдера видно як активні навіть тоді, коли захоплення консолі Vitest є тихим. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/Gateway негайно транслювалися під час live-запусків. - Налаштовуйте Heartbeat для direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Використовуйте таку таблицю рішень: +Користуйтеся цією таблицею рішень: -- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато що змінили) -- Зачіпаєте мережеву взаємодію gateway / WS protocol / pairинг: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / специфічні для провайдера збої / виклики tool: запускайте звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Зачіпаєте мережеву взаємодію Gateway / WS protocol / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / специфічні збої провайдера / виклик tool: запускайте звужений `pnpm test:live` -## Live-тести (що торкаються мережі) +## Live-тести (із доступом до мережі) -Для live matrix моделей, smoke перевірок backend CLI, smoke перевірок ACP, harness -app-server Codex і всіх live-тестів media-provider (Deepgram, BytePlus, ComfyUI, image, -music, video, media harness) — а також обробки облікових даних для live-запусків — див. +Для live-матриці моделей, smoke backend CLI, smoke ACP, harness +app-server Codex і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, +music, video, media harness) — а також для обробки облікових даних для live-запусків — див. [Тестування — live-набори](/uk/help/testing-live). -## Docker-ранери (необов’язкові перевірки «працює в Linux») +## Ранери Docker (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві категорії: +Ці ранери Docker поділяються на дві групи: -- Docker-ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл profile-key всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker-ранери live за замовчуванням використовують менший smoke-ліміт, щоб повний Docker sweep залишався практичним: - `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Ранери live-моделей: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл із profile-key всередині образу Docker репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та робочий простір (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint-и — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live runner-и типово мають менший smoke-ліміт, щоб повний Docker sweep залишався практичним: + `test:docker:live-models` типово використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` типово використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли - ви явно хочете більший вичерпний скан. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для Docker-lane live. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для контейнерних smoke-ранерів E2E, які перевіряють зібраний застосунок. Агрегат використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, тоді як ресурсні ліміти не дозволяють усім важким live-, npm-install- і multi-service-lane стартувати одночасно. За замовчуванням це 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT`, лише коли Docker-хост має більший запас ресурсів. Runner за замовчуванням виконує Docker preflight, видаляє застарілі контейнери OpenClaw E2E, виводить статус кожні 30 секунд, зберігає час успішних lane у `.artifacts/docker-tests/lane-timings.json` і використовує ці значення часу, щоб у наступних запусках спочатку стартували довші lanes. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести зважений manifest lane без збирання або запуску Docker. -- Контейнерні smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + вам явно потрібне більше, вичерпне сканування. +- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для live Docker lane. Також він збирає один спільний image `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для E2E smoke-ранерів у контейнерах, які перевіряють зібраний застосунок. Агрегат використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, тоді як обмеження ресурсів не дають одночасно стартувати всім важким live-, npm-install- і multi-service lane. Типові значення: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker host має більший запас ресурсів. Runner типово виконує Docker preflight, видаляє застарілі контейнери OpenClaw E2E, виводить статус кожні 30 секунд, зберігає таймінги успішних lane у `.artifacts/docker-tests/lane-timings.json` і використовує ці таймінги, щоб у наступних запусках спочатку стартували довші lane. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести зважений маніфест lane без збирання або запуску Docker. +- Smoke-ранери контейнерів: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:session-runtime-context`, `test:docker:agents-delete-shared-workspace`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-ранери live-моделей також монтують лише потрібні домівки auth CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни auth-store хоста: +Docker runner-и live-моделей також bind-mount-ять лише потрібні home-каталоги CLI auth (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у home каталогу контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у host auth store: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- ACP bind smoke: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`; за замовчуванням покриває Claude, Codex і Gemini, зі строгим покриттям OpenCode через `pnpm test:docker:live-acp-bind:opencode`) -- CLI backend smoke: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke bind для ACP: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`; типово охоплює Claude, Codex і Gemini, із суворим покриттям OpenCode через `pnpm test:docker:live-acp-bind:opencode`) +- Smoke для backend CLI: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) - Smoke harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) - Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Onboarding wizard (TTY, повне scaffold): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Smoke onboarding/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding env-ref плюс Telegram за замовчуванням, перевіряє, що doctor виправляє runtime-залежності активованих Plugin, і виконує один змоканий хід агента OpenAI. Щоб повторно використати попередньо зібраний tarball, використовуйте `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, щоб пропустити host rebuild — `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0`, або щоб змінити канал — `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Smoke глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає bundled image provider замість зависання. Щоб повторно використати попередньо зібраний tarball, використовуйте `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, щоб пропустити host build — `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0`, або щоб скопіювати `dist/` зі зібраного Docker-образу — `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Docker smoke інсталятора: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm-кеш у контейнерах root, update і direct-npm. Smoke оновлення за замовчуванням використовує npm `latest` як стабільну базу перед оновленням до tarball-кандидата. Перевірки інсталятора без root зберігають ізольований npm-кеш, щоб записи кешу, що належать root, не маскували поведінку локального встановлення користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm у локальних повторних запусках. -- CI Install Smoke пропускає дубльоване direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; локально запускайте скрипт без цього env, коли потрібне покриття прямого `npm install -g`. -- Smoke CLI видалення спільного workspace агентів: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) за замовчуванням збирає образ root Dockerfile, засіває двох агентів із одним workspace в ізольованому home контейнера, запускає `agents delete --json` і перевіряє коректний JSON плюс поведінку збереженого workspace. Щоб повторно використати образ install-smoke, встановіть `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. +- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Smoke onboarding/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює упакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding з env-ref плюс типово Telegram, перевіряє, що doctor відновлює runtime deps активованого Plugin, і виконує один агентський хід проти mocked OpenAI. Використовуйте вже зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host rebuild через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke runtime context сесії: `pnpm test:docker:session-runtime-context` перевіряє збереження transcript прихованого runtime context плюс виправлення doctor для уражених дубльованих гілок prompt-rewrite. +- Smoke глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольований home і перевіряє, що `openclaw infer image providers --json` повертає bundled image providers замість зависання. Використовуйте вже зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host build через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` із зібраного Docker image через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Docker smoke інсталятора: `bash scripts/test-install-sh-docker.sh` використовує один npm cache для своїх контейнерів root, update і direct-npm. Smoke оновлення типово бере npm `latest` як стабільну базову версію перед оновленням до tarball-кандидата. Перевірки інсталятора без root зберігають ізольований npm cache, щоб записи кешу з правами root не маскували поведінку локального встановлення користувача. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними перезапусками. +- Install Smoke CI пропускає дубльований direct-npm global update через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; локально запускайте скрипт без цього env, коли потрібне покриття прямого `npm install -g`. +- Smoke CLI для видалення спільного робочого простору agents: `pnpm test:docker:agents-delete-shared-workspace` (скрипт: `scripts/e2e/agents-delete-shared-workspace-docker.sh`) типово збирає image з root Dockerfile, ініціалізує двох агентів з одним робочим простором в ізольованому home контейнера, виконує `agents delete --json` і перевіряє коректний JSON плюс поведінку зі збереженням робочого простору. Повторно використовуйте image install-smoke через `OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1`. - Мережева взаємодія Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Регресія мінімального reasoning OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає змоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово викликає відхилення provider schema і перевіряє, що необроблена detail з’являється в логах Gateway. -- Міст MCP channel (seeded Gateway + stdio bridge + raw smoke notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти MCP bundle Pi (реальний stdio MCP-сервер + smoke allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення MCP Cron/subagent (реальний Gateway + teardown дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke інсталяції + alias `/plugin` + семантика restart Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -- Smoke незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke metadata перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime-залежності bundled Plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker-образ runner, один раз збирає і пакує OpenClaw на хості, а потім монтує цей tarball у кожний сценарій встановлення Linux. Щоб повторно використати образ, встановіть `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб пропустити host rebuild після свіжого локального build — `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0`, або щоб вказати на наявний tarball — `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker-агрегат заздалегідь пакує цей tarball один раз, а потім розподіляє перевірки bundled channel на незалежні lanes, включно з окремими lanes оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити matrix каналів під час прямого запуску bundled lane, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Lane також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують repair doctor/runtime-dependency. -- Щоб звузити runtime-залежності bundled Plugin під час ітерації, вимкніть непов’язані сценарії, наприклад: +- Регресія мінімального reasoning для OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає mocked сервер OpenAI через Gateway, перевіряє, що `web_search` піднімає `reasoning.effort` із `minimal` до `low`, потім примушує схему провайдера відхилити запит і перевіряє, що сирі деталі з’являються в логах Gateway. +- Міст каналу MCP (seeded Gateway + stdio bridge + smoke сирого notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти MCP у Pi bundle (реальний stdio MCP server + smoke allow/deny для вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Очищення MCP для Cron/subagent (реальний Gateway + teardown дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (smoke встановлення + alias `/plugin` + семантика restart для Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Smoke оновлення Plugin без змін: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke метаданих перезавантаження конфігурації: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime deps bundled Plugin: `pnpm test:docker:bundled-channel-deps` типово збирає невеликий Docker runner image, один раз збирає та пакує OpenClaw на host, а потім монтує цей tarball у кожен Linux-сценарій встановлення. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть host rebuild після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker aggregate один раз попередньо пакує цей tarball, а потім розбиває перевірки bundled channel на незалежні lane, зокрема окремі lane оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити channel matrix під час прямого запуску bundled lane, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Lane також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення doctor/runtime-dependency. +- Під час ітерацій звужуйте runtime deps bundled Plugin, вимикаючи не пов’язані сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Щоб вручну попередньо зібрати й повторно використовувати спільний образ built-app: +Щоб вручну попередньо зібрати і повторно використовувати спільний image built-app: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення образів для конкретних наборів, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо їх установлено. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти витягують його, якщо його ще немає локально. Docker-тести QR та інсталятора зберігають власні Dockerfile, оскільки вони перевіряють поведінку пакетів/встановлення, а не спільний runtime зібраного застосунку. +Перевизначення image для конкретних наборів, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та інсталятора зберігають власні Dockerfile, оскільки вони перевіряють поведінку пакування/встановлення, а не спільний runtime зібраного застосунку. -Docker-ранери live-моделей також монтують поточний checkout у режимі лише читання та -розміщують його в тимчасовому workdir усередині контейнера. Це дозволяє зберігати runtime-образ -компактним, водночас запускаючи Vitest точно на вашому локальному source/config. -Крок staging пропускає великі локальні кеші та результати збірки застосунку, як-от -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунку каталоги `.build` або -вивід Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -артефактів, специфічних для машини. -Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-проби Gateway не запускали -реальні workers каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити покриття -gateway live з цього Docker-lane. -`test:docker:openwebui` — це smoke-перевірка сумісності вищого рівня: вона запускає -контейнер gateway OpenClaw з увімкненими HTTP-endpoint, сумісними з OpenAI, -запускає закріплений контейнер Open WebUI проти цього gateway, входить через +Docker runner-и live-моделей також bind-mount-ять поточний checkout у режимі лише для читання і +розміщують його в тимчасовому workdir усередині контейнера. Це дозволяє зберегти runtime +image компактним, водночас запускаючи Vitest точно проти вашого локального source/config. +Крок staging пропускає великі локальні кеші та вихідні дані збірки застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або +вихідні каталоги Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +машинно-специфічних артефактів. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали +реальні worker-и каналів Telegram/Discord тощо всередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити live-покриття Gateway з цього Docker lane. +`test:docker:openwebui` — це smoke перевірка сумісності вищого рівня: вона запускає +контейнер Gateway OpenClaw з увімкненими HTTP endpoint-ами, сумісними з OpenAI, +запускає зафіксований контейнер Open WebUI проти цього Gateway, входить через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через проксі Open WebUI `/api/chat/completions`. -Перший запуск може бути помітно повільнішим, тому що Docker може знадобитися витягнути -образ Open WebUI, а самому Open WebUI — завершити власне холодне початкове налаштування. +реальний chat-запит через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження +image Open WebUI, а Open WebUI може потребувати завершення власного cold-start налаштування. Цей lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(`~/.profile` за замовчуванням) — це основний спосіб надати його в Dockerized-запусках. -Успішні запуски виводять невеликий JSON-payload на кшталт `{ "ok": true, "model": +(типово `~/.profile`) — основний спосіб надати його в Dockerized-запусках. +Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway -контейнер, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання transcript, metadata вкладень, -поведінку черги live-подій, маршрутизацію вихідного надсилання та сповіщення -каналу + дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо перевіряє необроблені stdio MCP frames, тож smoke перевіряє те, що -міст справді випромінює, а не лише те, що випадково показує конкретний SDK клієнта. +`test:docker:mcp-channels` навмисно є детермінованим і не потребує +реального облікового запису Telegram, Discord або iMessage. Він запускає seeded контейнер +Gateway, стартує другий контейнер, який запускає `openclaw mcp serve`, а потім +перевіряє виявлення маршрутованих розмов, читання transcript, метадані вкладень, +поведінку черги live-подій, маршрутизацію outbound send, а також сповіщення у стилі Claude про канал + +дозволи через реальний stdio MCP bridge. Перевірка сповіщень +безпосередньо аналізує сирі stdio MCP frame, тож smoke перевіряє те, що міст +справді виводить, а не лише те, що випадково показує конкретний клієнтський SDK. `test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує -ключа live-моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server -всередині контейнера, матеріалізує цей сервер через вбудований runtime Pi bundle -MCP, виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають -tools `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. -`test:docker:cron-mcp-cleanup` є детермінованим і не потребує -ключа live-моделі. Він запускає seeded Gateway з реальним stdio MCP probe server, -виконує ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, +ключа live-моделі. Він збирає Docker image репозиторію, запускає реальний stdio MCP probe server +усередині контейнера, матеріалізує цей сервер через embedded Pi bundle +MCP runtime, виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають +інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. +`test:docker:cron-mcp-cleanup` є детермінованим і не потребує ключа live-моделі. +Він запускає seeded Gateway з реальним stdio MCP probe server, виконує ізольований +хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручний smoke thread ACP plain-language (не для CI): +Ручний smoke для ACP plain-language thread (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. +- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. Корисні env-змінні: -- `OPENCLAW_CONFIG_DIR=...` (за замовчуванням: `~/.openclaw`) монтується в `/home/node/.openclaw` -- `OPENCLAW_WORKSPACE_DIR=...` (за замовчуванням: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` -- `OPENCLAW_PROFILE_FILE=...` (за замовчуванням: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, використані з `OPENCLAW_PROFILE_FILE`, із тимчасовими каталогами config/workspace та без зовнішніх монтувань auth CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI всередині Docker -- Зовнішні каталоги/файли auth CLI в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів +- `OPENCLAW_CONFIG_DIR=...` (типово: `~/.openclaw`) монтується в `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (типово: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (типово: `~/.profile`) монтується в `/home/node/.profile` і source-иться перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, source-нуті з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішнього CLI auth +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI всередині Docker +- Зовнішні каталоги/файли CLI auth під `$HOME` монтуються в режимі лише для читання під `/host-auth...`, а потім копіюються до `/home/node/...` перед початком тестів - Типові каталоги: `.minimax` - Типові файли: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - - Для ручного перевизначення використовуйте `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` - `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск - `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібна перебудова -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища profile (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний image `openclaw:local-live` для перезапусків, яким не потрібна нова збірка +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані надходять зі сховища профілю (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway показує для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt для перевірки nonce, який використовує smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити зафіксований тег image Open WebUI ## Перевірка документації Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків усередині сторінок: `pnpm docs:check-links:anchors`. +Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресія (безпечно для CI) +## Offline-регресія (безпечна для CI) Це регресії «реального pipeline» без реальних провайдерів: - Виклик tool через Gateway (mock OpenAI, реальний Gateway + цикл агента): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, записує config + auth enforced): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") +- Wizard Gateway (WS `wizard.start`/`wizard.next`, записує config + auth enforced): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") ## Оцінювання надійності агентів (Skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агентів»: -- Виклик mock tool через реальний Gateway + цикл агента (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють обв’язку сесії та ефекти config (`src/gateway/gateway.test.ts`). +- Mock tool-calling через реальний Gateway + цикл агента (`src/gateway/gateway.test.ts`). +- Наскрізні потоки wizard, які перевіряють прив’язку сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). -Що ще відсутнє для Skills (див. [Skills](/uk/tools/skills)): +Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? +- **Ухвалення рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Відповідність вимогам:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? - **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок tool, перенесення історії сесії та межі sandbox. -Майбутні eval мають залишатися детермінованими в першу чергу: +Майбутні eval мають спочатку залишатися детермінованими: -- Runner сценаріїв, що використовує mock-провайдерів для перевірки викликів tool + їх порядку, читання файлів Skill і обв’язки сесії. -- Невеликий набір сценаріїв, зосереджених на Skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live eval (opt-in, керовані env) лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв із mock-провайдерами для перевірки викликів tool + порядку, читання файлів skill і прив’язки сесії. +- Невеликий набір сценаріїв, зосереджених на skill (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live-eval (opt-in, керовані env) лише після того, як безпечний для CI набір уже буде на місці. -## Контрактні тести (форма Plugin і каналу) +## Contract-тести (форма Plugin і каналу) -Контрактні тести перевіряють, що кожен зареєстрований Plugin і канал відповідає своєму -контракту інтерфейсу. Вони ітерують усі виявлені Plugins і запускають набір -перевірок форми та поведінки. Типовий unit-lane `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди окремо, -коли ви змінюєте спільні поверхні каналу або провайдера. +Contract-тести перевіряють, що кожен зареєстрований Plugin і канал відповідає своєму +контракту інтерфейсу. Вони ітеруються по всіх виявлених Plugin і запускають набір +перевірок форми та поведінки. Типовий unit lane `pnpm test` навмисно +пропускає ці файли спільних seam і smoke; запускайте contract-команди явно, +коли зачіпаєте спільні поверхні каналу або провайдера. ### Команди @@ -734,60 +743,60 @@ tools `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх ### Контракти каналів -Розміщені в `src/channels/plugins/contracts/*.contract.test.ts`: +Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Базова форма Plugin (id, name, capabilities) -- **setup** - Контракт майстра налаштування +- **setup** - Контракт setup wizard - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій каналу -- **threading** - Обробка ID thread +- **threading** - Обробка ID тредів - **directory** - API каталогу/складу -- **group-policy** - Примусове застосування group policy +- **group-policy** - Застосування групової політики -### Контракти статусу провайдерів +### Контракти статусу провайдера -Розміщені в `src/plugins/contracts/*.contract.test.ts`. +Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Проби статусу каналу -- **registry** - Форма registry Plugin +- **status** - Зондування статусу каналу +- **registry** - Форма реєстру Plugin ### Контракти провайдерів -Розміщені в `src/plugins/contracts/*.contract.test.ts`: +Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** - Контракт потоку auth -- **auth-choice** - Вибір/підбір auth +- **auth** - Контракт потоку автентифікації +- **auth-choice** - Вибір/selection автентифікації - **catalog** - API каталогу моделей - **discovery** - Виявлення Plugin - **loader** - Завантаження Plugin - **runtime** - Runtime провайдера - **shape** - Форма/інтерфейс Plugin -- **wizard** - Майстер налаштування +- **wizard** - Setup wizard ### Коли запускати -- Після зміни експортів або subpath у plugin-sdk -- Після додавання або зміни Plugin каналу чи провайдера +- Після зміни export-ів або subpath у plugin-sdk +- Після додавання або зміни каналу чи Plugin провайдера - Після рефакторингу реєстрації або виявлення Plugin -Контрактні тести запускаються в CI та не потребують реальних API-ключів. +Contract-тести запускаються в CI і не потребують реальних API-ключів. -## Додавання регресій (настанови) +## Додавання регресійних тестів (настанови) Коли ви виправляєте проблему провайдера/моделі, виявлену в live: - Якщо можливо, додайте безпечну для CI регресію (mock/stub провайдера або фіксацію точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live (rate limit, політики auth), зберігайте live-тест вузьким і opt-in через env-змінні +- Якщо проблема за своєю природою лише live (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env-змінні - Віддавайте перевагу найменшому рівню, який виявляє баг: - - баг конвертації/відтворення запиту провайдера → прямий тест моделей - - баг pipeline сесії/історії/tool gateway → smoke gateway live або безпечний для CI mock-тест gateway -- Захисний механізм обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef із metadata registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що traversal-segment exec id відхиляються. - - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою для некласифікованих target id, щоб нові класи не можна було тихо пропустити. + - баг перетворення/відтворення запиту провайдера → direct models test + - баг pipeline сесії/історії/tool у gateway → live smoke Gateway або безпечний для CI mock-тест Gateway +- Захисне правило обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef із метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. + - Якщо ви додаєте нову цільову сім’ю SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не могли бути тихо пропущені. ## Пов’язане -- [Тестування live](/uk/help/testing-live) +- [Live-тестування](/uk/help/testing-live) - [CI](/uk/ci) diff --git a/docs/uk/plugins/architecture-internals.md b/docs/uk/plugins/architecture-internals.md index 84e1da9d0..f326aface 100644 --- a/docs/uk/plugins/architecture-internals.md +++ b/docs/uk/plugins/architecture-internals.md @@ -1,145 +1,144 @@ --- read_when: - - Реалізація хуків середовища виконання провайдера, життєвого циклу каналу або пакетних наборів - - Налагодження порядку завантаження plugin або стану реєстру - - Додавання нової можливості plugin або plugin рушія контексту -summary: 'Внутрішня будова архітектури Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці' -title: Внутрішня будова архітектури Plugin + - Реалізація гачків середовища виконання провайдера, життєвого циклу каналу або пакетних наборів + - Налагодження порядку завантаження Plugin або стану реєстру + - Додавання нової можливості Plugin або Plugin рушія контексту +summary: 'Внутрішня архітектура Plugin: конвеєр завантаження, реєстр, гачки середовища виконання, HTTP-маршрути та довідкові таблиці' +title: Внутрішня архітектура Plugin x-i18n: - generated_at: "2026-04-25T21:54:32Z" + generated_at: "2026-04-26T00:18:16Z" model: gpt-5.4 provider: openai - source_hash: d521f78bbd6aa4da09a28dcffa3c2309d46c8c1ec08f2f6b0616b3c2259339fc + source_hash: b8d82e74fc30e47dc5d699c5cf2268a7a65f4e3871d06cb0a1936aede5591625 source_path: plugins/architecture-internals.md workflow: 15 --- -Щодо публічної моделі можливостей, форм plugin і контрактів -володіння/виконання див. [Архітектура Plugin](/uk/plugins/architecture). Ця сторінка є -довідником з внутрішньої механіки: конвеєр завантаження, реєстр, хуки середовища виконання, +Щоб дізнатися про публічну модель можливостей, форми Plugin і контракти +володіння/виконання, див. [архітектуру Plugin](/uk/plugins/architecture). Ця сторінка — +довідник із внутрішньої механіки: конвеєр завантаження, реєстр, гачки середовища виконання, HTTP-маршрути Gateway, шляхи імпорту та таблиці схем. ## Конвеєр завантаження -Під час запуску OpenClaw приблизно виконує таке: +Під час запуску OpenClaw приблизно робить таке: -1. виявляє кореневі каталоги потенційних plugin -2. зчитує маніфести нативних або сумісних збірок і метадані пакетів -3. відхиляє небезпечні кандидати -4. нормалізує конфігурацію plugin (`plugins.enabled`, `allow`, `deny`, `entries`, +1. виявляє кореневі каталоги кандидатів Plugin +2. зчитує маніфести native або сумісних пакетів і метадані package +3. відхиляє небезпечних кандидатів +4. нормалізує конфігурацію Plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. визначає, чи буде ввімкнено кожного кандидата -6. завантажує ввімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач; - незібрані нативні plugin використовують jiti -7. викликає нативні хуки `register(api)` і збирає реєстрації в реєстр plugin -8. надає реєстр поверхням команд/середовища виконання +5. вирішує, чи вмикати кожного кандидата +6. завантажує ввімкнені native-модулі: зібрані вбудовані модулі використовують native loader; + незібрані native Plugin використовують jiti +7. викликає native-гачки `register(api)` і збирає реєстрації в реєстр Plugin +8. відкриває реєстр для команд/поверхонь середовища виконання -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це на тому самому етапі. Усі вбудовані plugin використовують `register`; для нових plugin віддавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — loader визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це на тому самому етапі. Усі вбудовані Plugin використовують `register`; для нових Plugin надавайте перевагу `register`. -Перевірки безпеки відбуваються **до** виконання в середовищі виконання. Кандидати блокуються, -коли точка входу виходить за межі кореня plugin, шлях доступний на запис для всіх, або -володіння шляхом виглядає підозріло для невбудованих plugin. +Перевірки безпеки відбуваються **до** виконання в середовищі виконання. Кандидатів блокують, +коли точка входу виходить за межі кореня Plugin, шлях доступний для запису всім, або +володіння шляхом виглядає підозріло для невбудованих Plugin. -### Поведінка з пріоритетом маніфесту +### Поведінка на основі маніфесту -Маніфест є джерелом істини для керувальної площини. OpenClaw використовує його, щоб: +Маніфест — це джерело істини для control plane. OpenClaw використовує його, щоб: -- ідентифікувати plugin -- виявляти оголошені канали/Skills/схему конфігурації або можливості збірки -- валідувати `plugins.entries..config` -- доповнювати мітки/заповнювачі в Control UI +- ідентифікувати Plugin +- виявляти оголошені канали/Skills/схему конфігурації або можливості пакета +- перевіряти `plugins.entries..config` +- доповнювати підписи/заповнювачі в Control UI - показувати метадані встановлення/каталогу -- зберігати дешеві дескриптори активації та налаштування без завантаження середовища виконання plugin +- зберігати дешеві дескриптори активації та налаштування без завантаження середовища виконання Plugin -Для нативних plugin модуль середовища виконання є частиною площини даних. Він реєструє -фактичну поведінку, наприклад хуки, інструменти, команди або потоки провайдера. +Для native Plugin модуль середовища виконання — це частина data plane. Він реєструє +фактичну поведінку, як-от гачки, інструменти, команди або потоки провайдера. -Необов’язкові блоки маніфесту `activation` і `setup` залишаються на керувальній площині. -Це лише дескриптори метаданих для планування активації та виявлення налаштування; +Необов’язкові блоки маніфесту `activation` і `setup` залишаються в control plane. +Це лише метадані-дескриптори для планування активації та виявлення налаштування; вони не замінюють реєстрацію в середовищі виконання, `register(...)` або `setupEntry`. -Перші споживачі живої активації тепер використовують підказки маніфесту про команди, канали та провайдерів, -щоб звузити завантаження plugin до ширшої матеріалізації реєстру: +Перші споживачі живої активації тепер використовують підказки маніфесту щодо команд, каналів і провайдерів, +щоб звузити завантаження Plugin до ширшої матеріалізації реєстру: -- завантаження CLI звужується до plugin, які володіють запитаною основною командою -- розв’язання налаштування каналу/plugin звужується до plugin, які володіють запитаним - ідентифікатором каналу -- явне розв’язання налаштування/середовища виконання провайдера звужується до plugin, які володіють - запитаним ідентифікатором провайдера +- завантаження CLI звужується до Plugin, які володіють запитаною основною командою +- зіставлення налаштування/Plugin каналу звужується до Plugin, які володіють запитаним + id каналу +- явне зіставлення налаштування/середовища виконання провайдера звужується до Plugin, які володіють + запитаним id провайдера -Планувальник активації надає як API лише з ідентифікаторами для наявних викликачів, так і -API плану для нової діагностики. Записи плану повідомляють, чому plugin було вибрано, -відокремлюючи явні підказки планувальника `activation.*` від резервного -володіння через маніфест, наприклад `providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і хуки. Це розділення причин є межею сумісності: -наявні метадані plugin продовжують працювати, а новий код може виявляти широкі підказки +Планувальник активації надає як API лише з id для наявних викликачів, так і +API плану для нової діагностики. Записи плану повідомляють, чому Plugin було вибрано, +відокремлюючи явні підказки планувальника `activation.*` від резервного варіанта +володіння з маніфесту, як-от `providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і гачки. Це розділення причин є межею сумісності: +наявні метадані Plugin продовжують працювати, а новий код може виявляти широкі підказки або резервну поведінку без зміни семантики завантаження середовища виконання. -Виявлення налаштування тепер надає перевагу ідентифікаторам, що належать дескрипторам, таким як `setup.providers` і -`setup.cliBackends`, щоб звузити коло plugin-кандидатів, перш ніж переходити до -`setup-api` для plugin, яким і далі потрібні хуки середовища виконання на етапі налаштування. Потік -налаштування провайдера спочатку використовує маніфест `providerAuthChoices`, а потім, для сумісності, -переходить до варіантів майстра середовища виконання та варіантів каталогу встановлення. Явне -`setup.requiresRuntime: false` є межею лише на рівні дескриптора; якщо -`requiresRuntime` пропущено, для сумісності зберігається застарілий резервний перехід до setup-api. Якщо більше -ніж один виявлений plugin претендує на той самий нормалізований ідентифікатор провайдера налаштування або бекенда CLI, -пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на -порядок виявлення. Коли середовище виконання налаштування все ж запускається, діагностика реєстру повідомляє -про розходження між `setup.providers` / `setup.cliBackends` і провайдерами або бекендами CLI, -зареєстрованими через setup-api, не блокуючи застарілі plugin. +Виявлення налаштування тепер надає перевагу id, що належать дескриптору, як-от +`setup.providers` і `setup.cliBackends`, щоб звузити коло кандидатів Plugin перед тим, як перейти +до `setup-api` для Plugin, яким усе ще потрібні гачки середовища виконання під час налаштування. Потік налаштування провайдера +спочатку використовує маніфест `providerAuthChoices`, а потім для сумісності повертається до +варіантів майстра середовища виконання та варіантів каталогу встановлення. Явний +`setup.requiresRuntime: false` — це межа лише для дескриптора; якщо +`requiresRuntime` пропущено, для сумісності зберігається застарілий резервний варіант `setup-api`. Якщо більше +ніж один виявлений Plugin заявляє той самий нормалізований id провайдера налаштування або +CLI-backend, пошук налаштування відхиляє неоднозначного власника, а не покладається на +порядок виявлення. Коли середовище виконання налаштування все ж виконується, діагностика реєстру повідомляє про +розбіжність між `setup.providers` / `setup.cliBackends` і провайдерами або CLI-backend, +зареєстрованими через setup-api, не блокуючи застарілі Plugin. -### Що кешує завантажувач +### Що кешує loader -OpenClaw підтримує короткоживучі внутрішньопроцесні кеші для: +OpenClaw зберігає короткоживучі внутрішньопроцесні кеші для: - результатів виявлення - даних реєстру маніфестів -- завантажених реєстрів plugin +- завантажених реєстрів Plugin -Ці кеші зменшують пікове навантаження під час запуску та накладні витрати повторних команд. Їх безпечно -сприймати як короткоживучі кеші продуктивності, а не як постійне збереження. +Ці кеші зменшують пікове навантаження під час запуску та накладні витрати від повторних команд. Їх безпечно +розглядати як короткоживучі кеші продуктивності, а не сховище. Примітка щодо продуктивності: -- Установіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або +- Встановіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, щоб вимкнути ці кеші. -- Налаштовуйте вікна кешу через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і +- Налаштовуйте вікна кешу за допомогою `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Модель реєстру -Завантажені plugin не змінюють безпосередньо довільні глобальні сутності ядра. Вони реєструються в -центральному реєстрі plugin. +Завантажені Plugin не змінюють безпосередньо довільні глобальні об’єкти ядра. Вони реєструються в +центральному реєстрі Plugin. Реєстр відстежує: -- записи plugin (ідентичність, джерело, походження, статус, діагностика) +- записи Plugin (ідентичність, джерело, походження, статус, діагностика) - інструменти -- застарілі хуки та типізовані хуки +- застарілі гачки й типізовані гачки - канали -- провайдерів +- провайдери - обробники Gateway RPC - HTTP-маршрути - реєстратори CLI - фонові служби -- команди, що належать plugin +- команди, що належать Plugin -Потім функції ядра читають із цього реєстру, а не взаємодіють із модулями plugin -напряму. Це зберігає одностороннє завантаження: +Потім можливості ядра читають із цього реєстру замість прямої взаємодії з модулями Plugin. +Це зберігає односторонність завантаження: -- модуль plugin -> реєстрація в реєстрі +- модуль Plugin -> реєстрація в реєстрі - середовище виконання ядра -> споживання реєстру Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра потрібна -лише одна точка інтеграції: «читати реєстр», а не «робити спеціальну обробку для кожного модуля plugin». +лише одна точка інтеграції: «читати реєстр», а не «робити спеціальний випадок для кожного модуля Plugin». ## Зворотні виклики прив’язки розмови -Plugin, які прив’язують розмову, можуть реагувати, коли затвердження буде вирішено. +Plugin, які прив’язують розмову, можуть реагувати, коли погодження вирішено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, -як запит на прив’язку буде схвалено або відхилено: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, як запит на прив’язку буде схвалено або відхилено: ```ts export default { @@ -147,128 +146,128 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // A binding now exists for this plugin + conversation. + // Тепер для цього Plugin + розмови існує прив’язка. console.log(event.binding?.conversationId); return; } - // The request was denied; clear any local pending state. + // Запит було відхилено; очистіть будь-який локальний стан очікування. console.log(event.request.conversation.conversationId); }); }, }; ``` -Поля вмісту зворотного виклику: +Поля корисного навантаження зворотного виклику: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` - `binding`: розв’язана прив’язка для схвалених запитів -- `request`: підсумок початкового запиту, підказка від’єднання, ідентифікатор відправника та +- `request`: початковий підсумок запиту, підказка від’єднання, id відправника та метадані розмови -Цей зворотний виклик призначений лише для сповіщення. Він не змінює, кому дозволено прив’язувати -розмову, і виконується після завершення обробки схвалення в ядрі. +Цей зворотний виклик призначений лише для сповіщення. Він не змінює того, кому дозволено прив’язувати +розмову, і виконується після завершення обробки погодження ядром. -## Хуки середовища виконання провайдера +## Гачки середовища виконання провайдера -Plugin провайдерів мають три шари: +Plugin провайдера мають три шари: -- **Метадані маніфесту** для дешевого пошуку до запуску середовища виконання: +- **Метадані маніфесту** для дешевого пошуку до запуску: `setup.providers[].envVars`, застарілий сумісний `providerAuthEnvVars`, `providerAuthAliases`, `providerAuthChoices` і `channelEnvVars`. -- **Хуки часу конфігурації**: `catalog` (застарілий `discovery`) плюс +- **Гачки під час конфігурації**: `catalog` (застарілий `discovery`) плюс `applyConfigDefaults`. -- **Хуки середовища виконання**: понад 40 необов’язкових хуків для auth, розв’язання моделей, - обгортання потоків, рівнів thinking, політики повторного відтворення та - кінцевих точок використання. Повний список див. в розділі [Порядок хуків і використання](#hook-order-and-usage). +- **Гачки середовища виконання**: 40+ необов’язкових гачків, що охоплюють auth, зіставлення моделей, + обгортання потоку, рівні thinking, політику відтворення та кінцеві точки використання. Див. + повний список у розділі [Порядок гачків і використання](#hook-order-and-usage). OpenClaw, як і раніше, відповідає за загальний цикл агента, failover, обробку транскриптів і -політику інструментів. Ці хуки є поверхнею розширення для поведінки, специфічної для провайдера, -без потреби у повністю власному транспорті інференсу. +політику інструментів. Ці гачки є поверхнею розширення для поведінки, специфічної для провайдера, +без потреби в цілком власному транспорті inference. Використовуйте маніфест `setup.providers[].envVars`, коли провайдер має облікові дані на основі env, які загальні шляхи auth/status/model-picker повинні бачити без -завантаження середовища виконання plugin. Застарілий `providerAuthEnvVars` і далі зчитується -адаптером сумісності протягом вікна deprecation, а невбудовані plugin, -які його використовують, отримують діагностику маніфесту. Використовуйте маніфест `providerAuthAliases`, -коли один ідентифікатор провайдера має повторно використовувати env vars, профілі auth, -auth на основі конфігурації та варіант онбордингу з API-ключем іншого ідентифікатора провайдера. Використовуйте маніфест -`providerAuthChoices`, коли поверхні CLI для онбордингу/вибору auth повинні знати -ідентифікатор вибору провайдера, мітки груп і просту схему auth з одним прапорцем без +завантаження середовища виконання Plugin. Застарілий `providerAuthEnvVars` усе ще читається +адаптером сумісності під час вікна знецінення, а невбудовані Plugin, які його використовують, +отримують діагностику маніфесту. Використовуйте маніфест `providerAuthAliases`, коли один id провайдера +має повторно використовувати env vars, профілі auth, auth на основі конфігурації та +варіант онбордингу API-ключа іншого id провайдера. Використовуйте маніфест +`providerAuthChoices`, коли CLI-поверхні онбордингу/вибору auth мають знати +id варіанта провайдера, мітки груп і просте однофлагове підключення auth без завантаження середовища виконання провайдера. Залишайте в середовищі виконання провайдера -`envVars` для підказок, орієнтованих на операторів, таких як мітки онбордингу або змінні налаштування +`envVars` для підказок, орієнтованих на операторів, як-от мітки онбордингу або змінні налаштування OAuth client-id/client-secret. Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування на основі env, які -загальний резервний механізм shell-env, перевірки config/status або підказки налаштування повинні бачити +загальний резервний варіант shell-env, перевірки config/status або запити налаштування мають бачити без завантаження середовища виконання каналу. -### Порядок хуків і використання +### Порядок гачків і використання -Для plugin моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку. -Стовпець «Коли використовувати» — це короткий посібник для вибору. +Для Plugin моделей/провайдерів OpenClaw викликає гачки приблизно в такому порядку. +Стовпець «Коли використовувати» — це короткий довідник для вибору. -| # | Хук | Що він робить | Коли використовувати | +| # | Гачок | Що робить | Коли використовувати | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями `base URL` | | 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму auth, env або семантики сімейства моделей провайдера | -| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(це не хук plugin)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним розв’язанням моделі | -| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним складанням моделі | Провайдер володіє очищенням транспорту для власних ідентифікаторів провайдерів у тому самому сімействі транспорту | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед розв’язанням середовища виконання/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із plugin; вбудовані допоміжні засоби сімейства Google також підстраховують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування native streaming-usage до конфігураційних провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, зумовлені кінцевою точкою | -| 7 | `resolveConfigApiKey` | Розв’язує auth через env-marker для конфігураційних провайдерів перед завантаженням auth у середовищі виконання | Провайдер має власне розв’язання API-ключа env-marker; `amazon-bedrock` також має тут вбудований розв’язувач AWS env-marker | -| 8 | `resolveSyntheticAuth` | Надає local/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Провайдер може працювати із synthetic/local маркером облікових даних | -| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі auth, що належать провайдеру; типовим `persistence` є `runtime-only` для облікових даних, що належать CLI/застосунку | Провайдер повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh-токенів; оголосіть `contracts.externalAuthProviders` у маніфесті | -| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених synthetic-заповнювачів профілів порівняно з auth на основі env/конфігурації | Провайдер зберігає synthetic-профілі-заповнювачі, які не повинні мати вищий пріоритет | -| 11 | `resolveDynamicModel` | Синхронний резервний варіант для model id, що належать провайдеру, яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream-ідентифікатори моделей | -| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед розв’язанням невідомих ідентифікаторів | -| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як вбудований виконавець використає розв’язану модель | Провайдеру потрібні переписування транспорту, але він і далі використовує транспорт ядра | -| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для моделей вендора за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспортах, не перебираючи на себе роль провайдера | -| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру і використовуються спільною логікою ядра | Провайдеру потрібні особливості транскрипту/сімейства провайдера | -| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований виконавець | Провайдеру потрібне очищення схем для сімейства транспорту | -| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження щодо ключових слів без навчання ядра правилам, специфічним для провайдера | -| 18 | `resolveReasoningOutputMode` | Вибирає контракт виводу reasoning: native чи tagged | Провайдеру потрібен tagged reasoning/кінцевий вивід замість native-полів | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним транспортом | Провайдеру потрібен власний wire protocol, а не просто обгортка | -| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки для заголовків/тіла запиту/сумісності моделей без власного транспорту | -| 22 | `resolveTransportTurnState` | Прикріплює native-заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали native-ідентичність ходу, властиву провайдеру | -| 23 | `resolveWebSocketSessionPolicy` | Прикріплює native-заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або резервну політику | -| 24 | `formatApiKey` | Форматувач профілю auth: збережений профіль стає рядком `apiKey` у середовищі виконання | Провайдер зберігає додаткові метадані auth і потребує власної форми токена в середовищі виконання | -| 25 | `refreshOAuth` | Перевизначення OAuth refresh для власних кінцевих точок refresh або політики помилки refresh | Провайдер не підходить під спільні засоби refresh для `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка з виправлення, що додається, коли OAuth refresh завершується помилкою | Провайдеру потрібні власні рекомендації з виправлення auth після помилки refresh | -| 27 | `matchesContextOverflowError` | Матчер переповнення вікна контексту, що належить провайдеру | У провайдера є сирі помилки переповнення, які загальні евристики не виявлять | -| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/перевантаженням тощо | -| 29 | `isCacheTtlEligible` | Політика TTL кешу запитів для проксі/backhaul-провайдерів | Провайдеру потрібне обмеження TTL кешу, специфічне для проксі | -| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення за відсутнього auth | Провайдеру потрібна специфічна для нього підказка відновлення за відсутнього auth | -| 31 | `suppressBuiltInModel` | Пригнічення застарілих upstream-моделей плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх підказкою від вендора | -| 32 | `augmentModelCatalog` | Synthetic/кінцеві рядки каталогу, додані після виявлення | Провайдеру потрібні synthetic-рядки для forward-compat у `models list` і засобах вибору | -| 33 | `resolveThinkingProfile` | Встановлення рівня `/think`, міток відображення та типового значення для конкретної моделі | Провайдер надає власну шкалу thinking або бінарну мітку для вибраних моделей | -| 34 | `isBinaryThinking` | Хук сумісності для перемикача reasoning увімк./вимк. | Провайдер надає лише бінарний режим thinking увімк./вимк. | -| 35 | `supportsXHighThinking` | Хук сумісності для підтримки reasoning `xhigh` | Провайдер хоче `xhigh` лише для підмножини моделей | -| 36 | `resolveDefaultThinkingLevel` | Хук сумісності для типового рівня `/think` | Провайдер володіє типовою політикою `/think` для сімейства моделей | -| 37 | `isModernModelRef` | Матчер modern-model для live-фільтрів профілів і вибору smoke | Провайдер володіє зіставленням бажаної моделі для live/smoke | -| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед інференсом | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | -| 39 | `resolveUsageAuth` | Розв’язує облікові дані usage/billing для `/usage` і пов’язаних поверхонь статусу | Провайдеру потрібен власний парсинг токена usage/quota або інші облікові дані usage | -| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки usage/quota, специфічні для провайдера, після розв’язання auth | Провайдеру потрібна специфічна для нього кінцева точка usage або парсер вмісту | -| 41 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті належить plugin провайдера | -| 42 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна власна політика транскрипту (наприклад, видалення блоків thinking) | -| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні специфічні для нього переписування replay понад спільні допоміжні засоби Compaction | -| 44 | `validateReplayTurns` | Остаточна валідація або переформування ходів replay перед вбудованим виконавцем | Транспорту провайдера потрібна суворіша валідація ходів після загальної санітизації | -| 45 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | +| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку намагається пройти звичайним шляхом реєстру/каталогу | _(це не гачок Plugin)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним зіставленням моделі | +| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для власних id провайдера в тому самому сімействі транспорту | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед зіставленням конфігурації/провайдера в середовищі виконання | Провайдеру потрібне очищення конфігурації, яке має жити разом із Plugin; вбудовані допоміжні засоби сімейства Google також страхують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування native streaming-usage до конфігураційних провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, керовані кінцевою точкою | +| 7 | `resolveConfigApiKey` | Зіставляє auth env-marker для конфігураційних провайдерів перед завантаженням auth середовища виконання | Провайдер має власне зіставлення API-ключа env-marker; `amazon-bedrock` також має тут вбудований AWS env-marker resolver | +| 8 | `resolveSyntheticAuth` | Показує локальний/self-hosted або config-backed auth без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | +| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth-профілі, що належать провайдеру; типовий `persistence` — `runtime-only` для облікових даних CLI/app | Провайдер повторно використовує зовнішні auth-облікові дані без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті | +| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених заповнювачів синтетичного профілю порівняно з env/config-backed auth | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет | +| 11 | `resolveDynamicModel` | Синхронний резервний варіант для model id провайдера, яких ще немає в локальному реєстрі | Провайдер приймає довільні id моделей верхнього рівня | +| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед зіставленням невідомих id | +| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як вбудований runner використає зіставлену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра | +| 14 | `contributeResolvedModelCompat` | Додає прапори сумісності для моделей постачальника за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе роль провайдера | +| 15 | `capabilities` | Метадані транскрипту/інструментарію, що належать провайдеру та використовуються спільною логікою ядра | Провайдеру потрібні особливості транскрипту/сімейства провайдера | +| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить вбудований runner | Провайдеру потрібне очищення схем для сімейства транспорту | +| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження щодо ключових слів без навчання ядра правил, специфічних для провайдера | +| 18 | `resolveReasoningOutputMode` | Вибирає native чи tagged-контракт reasoning output | Провайдеру потрібен tagged reasoning/final output замість native-полів | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним транспортом | Провайдеру потрібен власний wire protocol, а не просто обгортка | +| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності заголовків/тіла/model запиту без власного транспорту | +| 22 | `resolveTransportTurnState` | Додає native-заголовки транспорту на хід або метадані | Провайдер хоче, щоб загальні транспорти надсилали native-ідентичність ходу провайдера | +| 23 | `resolveWebSocketSessionPolicy` | Додає native-заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або резервну політику | +| 24 | `formatApiKey` | Форматувальник auth-профілю: збережений профіль стає рядком `apiKey` у середовищі виконання | Провайдер зберігає додаткові auth-метадані та потребує власної форми токена в середовищі виконання | +| 25 | `refreshOAuth` | Перевизначення OAuth refresh для власних кінцевих точок refresh або політики помилки refresh | Провайдер не відповідає спільним refreshers `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка виправлення, що додається, коли OAuth refresh завершується помилкою | Провайдеру потрібні власні вказівки з виправлення auth після помилки refresh | +| 27 | `matchesContextOverflowError` | Matcher переповнення context window, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики не помітять | +| 28 | `classifyFailoverReason` | Класифікація причини failover, що належить провайдеру | Провайдер може зіставляти сирі API/транспортні помилки з rate-limit/overload тощо | +| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-провайдерів | Провайдеру потрібне обмеження TTL кешу, специфічне для proxy | +| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення про відсутній auth для відновлення | Провайдеру потрібна власна підказка відновлення при відсутньому auth | +| 31 | `suppressBuiltInModel` | Приховування застарілої моделі верхнього рівня плюс необов’язкова підказка про помилку для користувача | Провайдеру потрібно приховати застарілі рядки верхнього рівня або замінити їх підказкою від постачальника | +| 32 | `augmentModelCatalog` | Синтетичні/остаточні рядки каталогу, що додаються після виявлення | Провайдеру потрібні синтетичні рядки для прямої сумісності в `models list` і засобах вибору | +| 33 | `resolveThinkingProfile` | Набір рівнів `/think` для конкретної моделі, мітки відображення та типове значення | Провайдер відкриває власну шкалу thinking або двійкову мітку для вибраних моделей | +| 34 | `isBinaryThinking` | Гачок сумісності для перемикача reasoning увімк./вимк. | Провайдер підтримує лише двійкове thinking увімк./вимк. | +| 35 | `supportsXHighThinking` | Гачок сумісності для підтримки reasoning `xhigh` | Провайдер хоче `xhigh` лише для підмножини моделей | +| 36 | `resolveDefaultThinkingLevel` | Гачок сумісності для типового рівня `/think` | Провайдер володіє типовою політикою `/think` для сімейства моделей | +| 37 | `isModernModelRef` | Matcher modern-model для фільтрів live-профілю та вибору smoke | Провайдер володіє зіставленням бажаної моделі для live/smoke | +| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед inference | Провайдеру потрібен обмін токена або короткоживучі облікові дані для запиту | +| 39 | `resolveUsageAuth` | Зіставляє облікові дані usage/billing для `/usage` і пов’язаних поверхонь статусу | Провайдеру потрібен власний парсинг токена usage/quota або інші облікові дані usage | +| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки usage/quota, специфічні для провайдера, після зіставлення auth | Провайдеру потрібна кінцева точка usage, специфічна для провайдера, або парсер корисного навантаження | +| 41 | `createEmbeddingProvider` | Створює adapter embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті належить Plugin провайдера | +| 42 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна власна політика транскрипту (наприклад, вилучення блоків thinking) | +| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні переписування replay, специфічні для провайдера, понад спільні допоміжні засоби Compaction | +| 44 | `validateReplayTurns` | Остаточна перевірка або переформування ходів replay перед вбудованим runner | Транспорту провайдера потрібна суворіша перевірка ходів після загального очищення | +| 45 | `onModelSelected` | Виконує побічні ефекти після вибору, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -відповідний plugin провайдера, а потім переходять до інших plugin провайдерів, здатних до хуків, -доки один із них фактично не змінить ідентифікатор моделі або transport/config. Це дозволяє -shim-прошаркам alias/compat для провайдерів працювати без потреби, щоб викликач знав, -який саме вбудований plugin володіє цим переписуванням. Якщо жоден хук провайдера не переписує +зіставлений Plugin провайдера, а потім переходять до інших Plugin провайдерів, що підтримують гачки, +доки один із них справді не змінить model id або transport/config. Це дає змогу +працювати shim-прошаркам alias/compat провайдера без потреби, щоб викликач знав, який +вбудований Plugin відповідає за переписування. Якщо жоден гачок провайдера не переписує підтримуваний запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google -все одно застосовує це очищення сумісності. +усе одно застосує це очищення сумісності. Якщо провайдеру потрібен повністю власний wire protocol або власний виконавець запитів, -це інший клас розширення. Ці хуки призначені для поведінки провайдера, яка все ще -працює в межах звичайного циклу інференсу OpenClaw. +це інший клас розширення. Ці гачки призначені для поведінки провайдера, яка +все ще виконується в межах звичайного циклу inference OpenClaw. ### Приклад провайдера @@ -326,13 +325,13 @@ api.registerProvider({ ### Вбудовані приклади -Вбудовані plugin провайдерів поєднують наведені вище хуки, щоб відповідати потребам кожного вендора щодо каталогу, -auth, thinking, replay та usage. Авторитетний набір хуків міститься разом із -кожним plugin у `extensions/`; ця сторінка ілюструє форми, а не -дублює список. +Вбудовані Plugin провайдерів поєднують наведені вище гачки відповідно до потреб +кожного постачальника щодо каталогу, auth, thinking, replay і usage. Авторитетний +набір гачків розміщено разом із кожним Plugin у `extensions/`; ця сторінка +ілюструє форми, а не дублює список. - + OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` разом із `resolveDynamicModel` / `prepareDynamicModel`, щоб вони могли показувати upstream model id раніше за статичний каталог OpenClaw. @@ -342,20 +341,20 @@ auth, thinking, replay та usage. Авторитетний набір хукі `prepareRuntimeAuth` або `formatApiKey` з `resolveUsageAuth` + `fetchUsageSnapshot`, щоб керувати обміном токенів та інтеграцією `/usage`. - + Спільні іменовані сімейства (`google-gemini`, `passthrough-gemini`, `anthropic-by-model`, `hybrid-anthropic-openai`) дають змогу провайдерам підключатися до - політики транскриптів через `buildReplayPolicy` замість того, щоб кожен plugin - повторно реалізовував очищення. + політики транскрипту через `buildReplayPolicy` замість того, щоб кожен Plugin + окремо повторно реалізовував очищення. - + `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і - `volcengine` реєструють лише `catalog` і використовують спільний цикл інференсу. + `volcengine` реєструють лише `catalog` і працюють на спільному циклі inference. - - Beta-заголовки, `/fast` / `serviceTier` і `context1m` розміщені всередині - публічного шару `api.ts` / `contract-api.ts` plugin Anthropic + + Beta-заголовки, `/fast` / `serviceTier` і `context1m` знаходяться в + публічному шві `api.ts` / `contract-api.ts` Plugin Anthropic (`wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`), а не в загальному SDK. @@ -385,14 +384,14 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайне навантаження виводу TTS ядра для поверхонь файлів/голосових нотаток. +- `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових нотаток. - Використовує конфігурацію ядра `messages.tts` і вибір провайдера. -- Повертає буфер аудіо PCM + частоту дискретизації. Plugin мають виконати ресемплінг/кодування для провайдерів. -- `listVoices` є необов’язковим залежно від провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать вендору. -- Списки голосів можуть містити багатші метадані, такі як локаль, стать і теги особистості для засобів вибору, обізнаних про провайдера. -- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. +- Повертає PCM audio buffer + sample rate. Plugin повинні виконати resample/encode для провайдерів. +- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для voice picker, що належать постачальнику, або потоків налаштування. +- Списки голосів можуть містити багатші метадані, як-от locale, gender і теги personality для picker, обізнаних про провайдера. +- OpenAI і ElevenLabs сьогодні підтримують telephony. Microsoft — ні. -Plugin також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. +Plugin також можуть реєструвати speech-провайдерів через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -412,15 +411,15 @@ api.registerSpeechProvider({ Примітки: -- Зберігайте політику TTS, fallback і доставку відповідей у ядрі. -- Використовуйте провайдерів мовлення для поведінки синтезу, що належить вендору. -- Застарілий вхід Microsoft `edge` нормалізується до ідентифікатора провайдера `microsoft`. -- Бажана модель володіння є орієнтованою на компанію: один plugin вендора може володіти - текстом, мовленням, зображенням і майбутніми медіапровайдерами, коли OpenClaw додаватиме ці - контракти можливостей. +- Зберігайте політику TTS, fallback і доставлення відповіді в ядрі. +- Використовуйте speech-провайдерів для поведінки синтезу, що належить постачальнику. +- Застарілий ввід Microsoft `edge` нормалізується до id провайдера `microsoft`. +- Бажана модель володіння — орієнтована на компанію: один Plugin постачальника може володіти + текстовими, мовними, графічними та майбутніми медіапровайдерами, коли OpenClaw додаватиме + ці контракти можливостей. -Для розуміння зображень/аудіо/відео plugin реєструють одного типізованого -провайдера media-understanding замість загального сховища ключ/значення: +Для розуміння зображень/аудіо/відео Plugin реєструють один типізований +провайдер розуміння медіа замість універсального мішка key/value: ```ts api.registerMediaUnderstandingProvider({ @@ -434,16 +433,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Зберігайте оркестрацію, fallback, конфігурацію та прив’язку каналу в ядрі. -- Зберігайте поведінку вендора в plugin провайдера. +- Зберігайте orchestration, fallback, config і підключення каналів у ядрі. +- Зберігайте поведінку постачальника в Plugin провайдера. - Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові поля результату, нові необов’язкові можливості. - Генерація відео вже дотримується того самого шаблону: - - ядро володіє контрактом можливості та допоміжним засобом середовища виконання - - plugin вендорів реєструють `api.registerVideoGenerationProvider(...)` - - plugin функцій/каналів споживають `api.runtime.videoGeneration.*` + - ядро володіє контрактом можливостей і допоміжним засобом середовища виконання + - Plugin постачальників реєструють `api.registerVideoGenerationProvider(...)` + - Plugin можливостей/каналів використовують `api.runtime.videoGeneration.*` -Для допоміжних засобів середовища виконання media-understanding plugin можуть викликати: +Для допоміжних засобів середовища виконання розуміння медіа Plugin можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -458,14 +457,14 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрибування аудіо plugin можуть використовувати або середовище виконання media-understanding, +Для транскрибування аудіо Plugin можуть використовувати або середовище виконання розуміння медіа, або старіший псевдонім STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Optional when MIME cannot be inferred reliably: + // Необов’язково, коли MIME неможливо надійно визначити: mime: "audio/ogg", }); ``` @@ -474,11 +473,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ - `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для розуміння зображень/аудіо/відео. -- Використовує конфігурацію аудіо media-understanding ядра (`tools.media.audio`) і порядок fallback провайдерів. -- Повертає `{ text: undefined }`, коли вивід транскрибування не було створено (наприклад, через пропущене/непідтримуване введення). +- Використовує аудіоконфігурацію ядра для розуміння медіа (`tools.media.audio`) і порядок fallback провайдерів. +- Повертає `{ text: undefined }`, коли вивід транскрипції не створено (наприклад, якщо вхід пропущено або не підтримується). - `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом сумісності. -Plugin також можуть запускати фонові запускі субагентів через `api.runtime.subagent`: +Plugin також можуть запускати фонові виконання subagent через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -494,12 +493,12 @@ const result = await api.runtime.subagent.run({ - `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. - OpenClaw враховує ці поля перевизначення лише для довірених викликачів. -- Для fallback-запусків, що належать plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugin конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. -- Запуски субагентів із недовірених plugin також працюють, але запити на перевизначення відхиляються замість тихого переходу до fallback. +- Для fallback-запусків, що належать Plugin, оператори повинні явно ввімкнути це через `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені Plugin конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. +- Запуски subagent із недовірених Plugin теж працюють, але запити на перевизначення відхиляються замість тихого переходу до fallback. -Для вебпошуку plugin можуть використовувати спільний допоміжний засіб середовища виконання замість -звернення до прив’язки інструментів агента: +Для вебпошуку Plugin можуть використовувати спільний допоміжний засіб середовища виконання замість +прямого доступу до підключення інструментів агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -520,9 +519,9 @@ Plugin також можуть реєструвати провайдерів в Примітки: -- Зберігайте вибір провайдера, розв’язання облікових даних і спільну семантику запитів у ядрі. -- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для вендора. -- `api.runtime.webSearch.*` — це бажана спільна поверхня для plugin функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструментів агента. +- Зберігайте вибір провайдера, зіставлення облікових даних і спільну семантику запитів у ядрі. +- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для постачальника. +- `api.runtime.webSearch.*` — це бажана спільна поверхня для Plugin можливостей/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. ### `api.runtime.imageGeneration` @@ -538,11 +537,11 @@ const providers = api.runtime.imageGeneration.listProviders({ ``` - `generate(...)`: генерує зображення, використовуючи налаштований ланцюжок провайдерів генерації зображень. -- `listProviders(...)`: перелічує доступних провайдерів генерації зображень і їхні можливості. +- `listProviders(...)`: виводить список доступних провайдерів генерації зображень та їхніх можливостей. ## HTTP-маршрути Gateway -Plugin можуть відкривати HTTP-ендпоїнти через `api.registerHttpRoute(...)`. +Plugin можуть відкривати HTTP-кінцеві точки за допомогою `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -560,140 +559,139 @@ api.registerHttpRoute({ Поля маршруту: - `path`: шлях маршруту в HTTP-сервері gateway. -- `auth`: обов’язкове. Використовуйте `"gateway"`, щоб вимагати звичайний auth gateway, або `"plugin"` для auth/перевірки Webhook, якими керує plugin. -- `match`: необов’язкове. `"exact"` (типово) або `"prefix"`. -- `replaceExisting`: необов’язкове. Дає змогу тому самому plugin замінити власну наявну реєстрацію маршруту. -- `handler`: повертає `true`, коли маршрут обробив запит. +- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайну auth gateway, або `"plugin"` для auth/webhook verification, якими керує Plugin. +- `match`: необов’язкове поле. `"exact"` (типово) або `"prefix"`. +- `replaceExisting`: необов’язкове поле. Дозволяє тому самому Plugin замінити власну наявну реєстрацію маршруту. +- `handler`: повертайте `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` було видалено, і воно спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`. -- Маршрути plugin мають явно оголошувати `auth`. -- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin. -- Перекривні маршрути з різними рівнями `auth` відхиляються. Ланцюжки переходу `exact`/`prefix` мають залишатися лише в межах одного рівня auth. -- Маршрути `auth: "plugin"` **не** отримують автоматично операторські runtime-scopes. Вони призначені для Webhook і перевірки підписів, якими керує plugin, а не для привілейованих допоміжних викликів Gateway. -- Маршрути `auth: "gateway"` працюють у межах runtime scope запиту Gateway, але цей scope навмисно консервативний: - - bearer auth на основі спільного секрету (`gateway.auth.mode = "token"` / `"password"`) утримує runtime-scopes маршрутів plugin на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` - - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах до маршрутів plugin з ідентичністю, runtime scope повертається до `operator.write` -- Практичне правило: не вважайте маршрут plugin з gateway-auth неявною адміністративною поверхнею. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю й задокументуйте явний контракт заголовка `x-openclaw-scopes`. +- `api.registerHttpHandler(...)` було вилучено, і воно спричинить помилку завантаження Plugin. Натомість використовуйте `api.registerHttpRoute(...)`. +- Маршрути Plugin повинні явно оголошувати `auth`. +- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один Plugin не може замінити маршрут іншого Plugin. +- Маршрути, що перекриваються, з різними рівнями `auth` відхиляються. Використовуйте ланцюжки переходу `exact`/`prefix` лише в межах одного рівня auth. +- Маршрути `auth: "plugin"` **не** отримують автоматично runtime scopes оператора. Вони призначені для webhook/signature verification, якими керує Plugin, а не для привілейованих допоміжних викликів Gateway. +- Маршрути `auth: "gateway"` виконуються в межах runtime scope запиту Gateway, але цей scope навмисно консервативний: + - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує runtime scopes маршрутів Plugin зафіксованими на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` + - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` у приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах до маршрутів Plugin з ідентичністю, runtime scope повертається до `operator.write` +- Практичне правило: не вважайте маршрут Plugin з gateway-auth неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю та задокументуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK Використовуйте вузькі підшляхи SDK замість монолітного кореневого -barrel `openclaw/plugin-sdk` під час створення нових plugin. Основні підшляхи: +barrel `openclaw/plugin-sdk`, коли створюєте нові Plugin. Основні підшляхи: | Підшлях | Призначення | | ---------------------------------- | -------------------------------------------------- | | `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin | | `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/побудови каналу | -| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella-контракт | +| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella contract | | `openclaw/plugin-sdk/config-schema` | Коренева схема Zod для `openclaw.json` (`OpenClawSchema`) | -Плагіни каналів вибирають із сімейства вузьких шарів — `channel-setup`, +Plugin каналів вибирають із сімейства вузьких швів — `channel-setup`, `setup-runtime`, `setup-adapter-runtime`, `setup-tools`, `channel-pairing`, `channel-contract`, `channel-feedback`, `channel-inbound`, `channel-lifecycle`, `channel-reply-pipeline`, `command-auth`, `secret-input`, `webhook-ingress`, -`channel-targets` і `channel-actions`. Поведінка схвалення має бути зведена -до одного контракту `approvalCapability`, а не змішуватися між не пов’язаними -полями plugin. Див. [Плагіни каналів](/uk/plugins/sdk-channel-plugins). +`channel-targets` і `channel-actions`. Поведінку погодження слід зосередити +в одному контракті `approvalCapability`, а не змішувати між не пов’язаними +полями Plugin. Див. [Plugin каналів](/uk/plugins/sdk-channel-plugins). -Допоміжні засоби середовища виконання та конфігурації розміщені у відповідних підшляхах -`*-runtime` (`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`, +Допоміжні засоби середовища виконання та конфігурації розміщені у відповідних підшляхах `*-runtime` +(`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`, `lazy-runtime`, `directory-runtime`, `text-runtime`, `runtime-store` тощо). -`openclaw/plugin-sdk/channel-runtime` є застарілим — це shim сумісності для -старіших plugin. Новий код має імпортувати натомість вужчі загальні примітиви. +`openclaw/plugin-sdk/channel-runtime` застарів — це shim сумісності для +старіших Plugin. Новий код має імпортувати натомість вужчі загальні примітиви. -Внутрішні для репозиторію точки входу (для кореня пакета кожного вбудованого plugin): +Внутрішні для репозиторію точки входу (для кореня пакета кожного вбудованого Plugin): -- `index.js` — точка входу вбудованого plugin +- `index.js` — точка входу вбудованого Plugin - `api.js` — barrel допоміжних засобів/типів - `runtime-api.js` — barrel лише для середовища виконання -- `setup-entry.js` — точка входу plugin налаштування +- `setup-entry.js` — точка входу Plugin налаштування -Зовнішні plugin повинні імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи -не імпортуйте `src/*` іншого пакета plugin із ядра або з іншого plugin. -Точки входу, завантажені через facade, віддають перевагу активному знімку конфігурації середовища виконання, якщо він -існує, а потім переходять до розв’язаної конфігурації на диску. +Зовнішні Plugin мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи +не імпортуйте `src/*` іншого пакета Plugin з ядра або з іншого Plugin. +Точки входу, завантажені через facade, надають перевагу активному знімку конфігурації середовища виконання, якщо він існує, +а потім повертаються до зіставленого файлу конфігурації на диску. -Підшляхи, специфічні для можливостей, такі як `image-generation`, `media-understanding` -і `speech`, існують, тому що вбудовані plugin уже використовують їх сьогодні. Вони не є -автоматично зовнішніми контрактами, замороженими на довгий строк — перевіряйте відповідну +Підшляхи, специфічні для можливостей, як-от `image-generation`, `media-understanding` +і `speech`, існують, тому що вбудовані Plugin використовують їх уже сьогодні. Вони не є +автоматично довгостроково зафіксованими зовнішніми контрактами — перевіряйте відповідну довідкову сторінку SDK, коли покладаєтеся на них. ## Схеми інструментів повідомлень -Plugin повинні володіти внесками у схему `describeMessageTool(...)`, специфічними для каналу, -для примітивів, відмінних від повідомлень, таких як реакції, прочитання та опитування. -Спільне представлення надсилання має використовувати загальний контракт `MessagePresentation` -замість нативних для провайдера полів кнопок, компонентів, блоків або карток. -Див. [Message Presentation](/uk/plugins/message-presentation) щодо контракту, -правил fallback, зіставлення провайдерів і контрольного списку для авторів plugin. +Plugin повинні володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу, +для немеседжевих примітивів, як-от реакції, позначення прочитаного й опитування. +Спільне подання надсилання має використовувати загальний контракт `MessagePresentation` +замість native-полів кнопок, компонентів, блоків або карток, специфічних для провайдера. +Див. [Message Presentation](/uk/plugins/message-presentation), щоб ознайомитися з контрактом, +правилами fallback, зіставленням провайдерів і контрольним списком для авторів Plugin. -Plugin із підтримкою надсилання оголошують, що вони можуть рендерити, через можливості повідомлень: +Plugin, здатні до надсилання, оголошують, що саме вони можуть відображати, через можливості повідомлень: -- `presentation` для семантичних блоків представлення (`text`, `context`, `divider`, `buttons`, `select`) -- `delivery-pin` для запитів закріпленої доставки +- `presentation` для блоків семантичного подання (`text`, `context`, `divider`, `buttons`, `select`) +- `delivery-pin` для запитів закріпленого доставлення -Ядро вирішує, чи рендерити представлення нативно, чи деградувати його до тексту. -Не відкривайте з generic message tool шляхи обходу до нативного UI провайдера. -Застарілі допоміжні засоби SDK для старих нативних схем і далі експортуються для наявних -сторонніх plugin, але нові plugin не повинні їх використовувати. +Ядро вирішує, чи відображати подання native-способом, чи деградувати його до тексту. +Не відкривайте зі спільного інструмента повідомлень шляхів обходу native UI, специфічних для провайдера. +Застарілі допоміжні засоби SDK для старих native-схем усе ще експортуються для наявних +сторонніх Plugin, але нові Plugin не повинні їх використовувати. -## Розв’язання цілей каналу +## Зіставлення цілей каналу -Плагіни каналів повинні володіти семантикою цілей, специфічною для каналу. Зберігайте спільний -вихідний host загальним і використовуйте поверхню адаптера повідомлень для правил провайдера: +Plugin каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний +вихідний хост універсальним і використовуйте поверхню messaging adapter для правил провайдера: -- `messaging.inferTargetChatType({ to })` визначає, чи нормалізовану ціль - слід трактувати як `direct`, `group` або `channel` до пошуку в каталозі. -- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи - слід для вхідного значення одразу переходити до розв’язання, подібного до id, а не до пошуку в каталозі. -- `messaging.targetResolver.resolveTarget(...)` — це резервний варіант plugin, коли - ядру потрібне остаточне розв’язання, що належить провайдеру, після нормалізації або після - промаху в каталозі. +- `messaging.inferTargetChatType({ to })` визначає, чи слід нормалізовану ціль + трактувати як `direct`, `group` або `channel` до пошуку в directory. +- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи має + вхід одразу перейти до зіставлення в стилі id замість пошуку в directory. +- `messaging.targetResolver.resolveTarget(...)` — це fallback Plugin, коли + ядру потрібне остаточне зіставлення, що належить провайдеру, після нормалізації або + після промаху в directory. - `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, - специфічною для провайдера, після того як ціль розв’язано. + специфічною для провайдера, після того, як ціль зіставлено. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають ухвалюватися до +- Використовуйте `inferTargetChatType` для рішень за категоріями, які мають ухвалюватися до пошуку peer/group. -- Використовуйте `looksLikeId` для перевірок «трактувати це як явний/нативний id цілі». +- Використовуйте `looksLikeId` для перевірок на кшталт «трактувати це як явний/native id цілі». - Використовуйте `resolveTarget` для резервної нормалізації, специфічної для провайдера, а не для - широкого пошуку в каталозі. -- Зберігайте нативні для провайдера id, як-от chat id, thread id, JID, handle та room - id, усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних - полях SDK. + широкого пошуку в directory. +- Зберігайте native id провайдера, як-от chat id, thread id, JID, handle і room id, + усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK. -## Каталоги на основі конфігурації +## Directory на основі конфігурації -Plugin, які формують записи каталогу з конфігурації, повинні тримати цю логіку в -plugin і повторно використовувати спільні допоміжні засоби з +Plugin, які виводять записи directory з конфігурації, мають зберігати цю логіку в самому +Plugin і повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні peer/group на основі конфігурації, наприклад: +Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, наприклад: -- DM-peer на основі allowlist -- налаштовані зіставлення каналів/груп -- статичні fallback-каталоги в межах облікового запису +- DM peers, керовані allowlist +- налаштовані зіставлення channel/group +- статичні fallback directory в межах облікового запису Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: -- фільтрацію запиту +- фільтрацію запитів - застосування лімітів -- допоміжні засоби dedupe/нормалізації +- допоміжні засоби deduping/normalization - побудову `ChannelDirectoryEntry[]` Перевірка облікового запису та нормалізація id, специфічні для каналу, мають залишатися -в реалізації plugin. +в реалізації Plugin. ## Каталоги провайдерів -Плагіни провайдерів можуть визначати каталоги моделей для інференсу через +Plugin провайдерів можуть визначати каталоги моделей для inference за допомогою `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в @@ -702,19 +700,19 @@ plugin і повторно використовувати спільні доп - `{ provider }` для одного запису провайдера - `{ providers }` для кількох записів провайдера -Використовуйте `catalog`, коли plugin володіє model id, специфічними для провайдера, типовими +Використовуйте `catalog`, коли Plugin володіє model id, специфічними для провайдера, типовими значеннями base URL або метаданими моделей, захищеними auth. -`catalog.order` керує тим, коли каталог plugin зливається відносно -неявних вбудованих провайдерів OpenClaw: +`catalog.order` керує тим, коли каталог Plugin зливається відносно +вбудованих неявних провайдерів OpenClaw: -- `simple`: прості провайдери з API-ключем або на основі env -- `profile`: провайдери, що з’являються, коли існують профілі auth -- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів +- `simple`: звичайні провайдери на основі API-ключа або env +- `profile`: провайдери, які з’являються, коли існують auth-профілі +- `paired`: провайдери, що синтезують кілька пов’язаних записів провайдерів - `late`: останній прохід, після інших неявних провайдерів -Пізніші провайдери перемагають у разі колізії ключів, тож plugin можуть навмисно -перевизначити вбудований запис провайдера з тим самим id провайдера. +Пізніші провайдери перемагають у разі колізії ключів, тож Plugin можуть свідомо перевизначити +вбудований запис провайдера з тим самим id провайдера. Сумісність: @@ -723,39 +721,34 @@ plugin і повторно використовувати спільні доп ## Інспекція каналу лише для читання -Якщо ваш plugin реєструє канал, віддавайте перевагу реалізації -`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`. +Якщо ваш Plugin реєструє канал, краще реалізувати +`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це шлях середовища виконання. Він може припускати, що облікові дані - повністю матеріалізовані, і швидко завершуватися з помилкою, якщо потрібних секретів бракує. -- Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` і потоки doctor/config - repair, не повинні потребувати матеріалізації облікових даних середовища виконання лише для того, - щоб описати конфігурацію. +- `resolveAccount(...)` — це шлях середовища виконання. Йому дозволено припускати, що облікові дані + повністю матеріалізовані, і швидко завершуватися помилкою, якщо потрібні секрети відсутні. +- Шляхи команд лише для читання, як-от `openclaw status`, `openclaw status --all`, + `openclaw channels status`, `openclaw channels resolve`, а також потоки repair doctor/config, + не повинні матеріалізовувати runtime-облікові дані лише для опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: - Повертає лише описовий стан облікового запису. - Зберігає `enabled` і `configured`. -- Додає поля джерела/статусу облікових даних, коли це доречно, наприклад: +- Включає поля джерела/статусу облікових даних, коли це доречно, наприклад: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Не потрібно повертати сирі значення токенів лише для звітування про доступність у режимі лише читання. - Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела) - для команд на кшталт status. -- Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але - вони недоступні в поточному шляху команди. +- Не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі лише читання. Повернення `tokenStatus: "available"` (і відповідного поля джерела) достатньо для команд у стилі status. +- Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але вони недоступні в поточному шляху команди. -Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» -замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. +Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. ## Пакетні набори -Каталог plugin може містити `package.json` з `openclaw.extensions`: +Каталог Plugin може містити `package.json` з `openclaw.extensions`: ```json { @@ -767,43 +760,41 @@ plugin і повторно використовувати спільні доп } ``` -Кожен запис стає plugin. Якщо набір перелічує кілька extensions, id plugin +Кожен запис стає Plugin. Якщо пакетний набір містить кілька розширень, id Plugin стає `name/`. -Якщо ваш plugin імпортує залежності npm, установіть їх у цьому каталозі, щоб -`node_modules` був доступний (`npm install` / `pnpm install`). +Якщо ваш Plugin імпортує npm-залежності, встановіть їх у цьому каталозі, щоб був +доступний `node_modules` (`npm install` / `pnpm install`). -Запобіжник безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу plugin -після розв’язання symlink. Записи, що виходять за межі каталогу пакета, -відхиляються. +Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу Plugin +після розв’язання симлінків. Записи, що виходять за межі каталогу пакета, відхиляються. -Примітка щодо безпеки: `openclaw plugins install` установлює залежності plugin через -локальний для проєкту `npm install --omit=dev --ignore-scripts` (без lifecycle scripts, -без dev dependencies під час виконання), ігноруючи успадковані глобальні налаштування встановлення npm. -Підтримуйте дерева залежностей plugin як "pure JS/TS" і уникайте пакетів, які потребують -збірок `postinstall`. +Примітка щодо безпеки: `openclaw plugins install` встановлює залежності Plugin за допомогою +локального для проєкту `npm install --omit=dev --ignore-scripts` (без lifecycle scripts, +без dev dependencies у середовищі виконання), ігноруючи успадковані глобальні налаштування встановлення npm. +Підтримуйте дерева залежностей Plugin «чистими JS/TS» та уникайте пакетів, яким потрібні +збірки `postinstall`. -Необов’язково: `openclaw.setupEntry` може вказувати на полегшений модуль лише для налаштування. -Коли OpenClaw потребує поверхонь налаштування для вимкненого plugin каналу або -коли plugin каналу ввімкнений, але ще не налаштований, він завантажує `setupEntry` -замість повної точки входу plugin. Це робить запуск і налаштування легшими, -коли основна точка входу plugin також підключає інструменти, хуки або інший код, -призначений лише для середовища виконання. +Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування. +Коли OpenClaw потребує поверхонь налаштування для вимкненого Plugin каналу або +коли Plugin каналу ввімкнено, але ще не налаштовано, він завантажує `setupEntry` +замість повної точки входу Plugin. Це робить запуск і налаштування легшими, +коли основна точка входу Plugin також підключає інструменти, гачки або інший код лише для середовища виконання. Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може ввімкнути для plugin каналу той самий шлях `setupEntry` під час -передслухової фази запуску gateway, навіть коли канал уже налаштований. +може підключити Plugin каналу до того самого шляху `setupEntry` під час +передпрослуховувальної фази запуску gateway, навіть якщо канал уже налаштовано. Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати -до того, як gateway почне слухати. На практиці це означає, що точка входу налаштування -має зареєструвати кожну можливість каналу, від якої залежить запуск, наприклад: +до того, як gateway почне прослуховування. На практиці це означає, що точка входу налаштування +має реєструвати кожну можливість, що належить каналу, від якої залежить запуск, наприклад: - саму реєстрацію каналу -- будь-які HTTP-маршрути, які мають бути доступними до того, як gateway почне слухати -- будь-які методи gateway, інструменти або служби, які мають існувати в той самий проміжок часу +- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне прослуховування +- будь-які методи gateway, інструменти або служби, які мають існувати в це саме вікно часу Якщо ваша повна точка входу все ще володіє будь-якою необхідною можливістю запуску, не вмикайте -цей прапорець. Залиште plugin із типовою поведінкою та дозвольте OpenClaw завантажити +цей прапорець. Залиште Plugin на типовій поведінці та дайте OpenClaw завантажити повну точку входу під час запуску. Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, які ядро @@ -814,21 +805,21 @@ plugin і повторно використовувати спільні доп - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Ядро використовує цю поверхню, коли потрібно просунути застарілу конфігурацію каналу з одним обліковим записом -у `channels..accounts.*` без завантаження повної точки входу plugin. -Поточний вбудований приклад — Matrix: він переносить лише ключі auth/bootstrap до -іменованого просунутого облікового запису, коли іменовані облікові записи вже існують, і може -зберігати налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати +Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію +однокористувацького каналу в `channels..accounts.*` без завантаження повної точки входу Plugin. +Matrix — поточний вбудований приклад: він переносить лише ключі auth/bootstrap в +іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може +зберегти налаштований неканонічний ключ default-account замість того, щоб завжди створювати `accounts.default`. -Ці адаптери patch налаштування зберігають lazy-виявлення поверхні контракту вбудованих каналів. Час -імпорту залишається малим; поверхня просування завантажується лише під час першого використання, а не -повторно входить у запуск вбудованого каналу під час імпорту модуля. +Ці setup patch adapters зберігають ледаче виявлення поверхні контракту вбудованих каналів. Час +імпорту залишається малим; поверхня просування завантажується лише за першого використання замість +повторного входу в запуск вбудованого каналу під час імпорту модуля. -Коли ці поверхні запуску містять Gateway RPC methods, зберігайте їх у -префіксі, специфічному для plugin. Простори імен адміністратора ядра (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди розв’язуються -до `operator.admin`, навіть якщо plugin запитує вужчий scope. +Коли ці поверхні запуску включають Gateway RPC methods, зберігайте їх на +префіксі, специфічному для Plugin. Простори імен адміністратора ядра (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди зіставляються +з `operator.admin`, навіть якщо Plugin запитує вужчий scope. Приклад: @@ -847,8 +838,8 @@ plugin і повторно використовувати спільні доп ### Метадані каталогу каналу -Плагіни каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і -підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити даних каталогу. +Plugin каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і +підказки встановлення через `openclaw.install`. Це дає змогу ядру залишатися вільним від даних. Приклад: @@ -863,7 +854,7 @@ plugin і повторно використовувати спільні доп "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Власний чат через webhook-ботів Nextcloud Talk.", + "blurb": "Самостійно розміщений чат через webhook-ботів Nextcloud Talk.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -876,70 +867,69 @@ plugin і повторно використовувати спільні доп } ``` -Корисні поля `openclaw.channel` поза мінімальним прикладом: +Корисні поля `openclaw.channel` понад мінімальний приклад: - `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу -- `docsLabel`: перевизначення тексту посилання для посилання на документацію -- `preferOver`: ідентифікатори plugin/каналів із нижчим пріоритетом, які цей запис каталогу має перевершувати -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування копією поверхні вибору -- `markdownCapable`: позначає канал як сумісний із Markdown для рішень форматування вихідних даних +- `docsLabel`: перевизначає текст посилання для посилання на документацію +- `preferOver`: id Plugin/каналів із нижчим пріоритетом, які цей запис каталогу має випереджати +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору +- `markdownCapable`: позначає канал як сумісний із Markdown для рішень щодо вихідного форматування - `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` -- `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено `false` +- `exposure.setup`: приховує канал з інтерактивних picker налаштування/конфігурації, якщо встановлено `false` - `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації -- `showConfigured` / `showInSetup`: застарілі псевдоніми, які й далі приймаються для сумісності; віддавайте перевагу `exposure` -- `quickstartAllowFrom`: вмикає для каналу стандартний потік quickstart `allowFrom` +- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure` +- `quickstartAllowFrom`: підключає канал до стандартного потоку quickstart `allowFrom` - `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час розв’язання announce target +- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час зіставлення цілей оголошення -OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт -реєстру MPM). Помістіть JSON-файл в одне з таких місць: +OpenClaw також може об’єднувати **зовнішні каталоги каналів** (наприклад, експорт +реєстру MPM). Помістіть JSON-файл у один із таких шляхів: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на -один або кілька JSON-файлів (розділених комами/крапками з комою/`PATH`). Кожен файл має +один чи кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл має містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів відкривають нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Ці нормалізовані факти визначають, чи є npm-специфікація точною версією чи плаваючим -селектором, чи присутні очікувані метадані цілісності та чи доступний також локальний -шлях джерела. Коли ідентичність каталогу/пакета відома, нормалізовані факти -попереджають, якщо розібране ім’я пакета npm відхиляється від цієї ідентичності. -Вони також попереджають, коли `defaultChoice` є невалідним або вказує на джерело, яке -недоступне, і коли метадані цілісності npm присутні без валідного npm- -джерела. Споживачі повинні трактувати `installSource` як адитивне необов’язкове поле, щоб -старі вручну зібрані записи та shim сумісності не мусили його синтезувати. -Це дає змогу онбордингу та діагностиці пояснювати стан площини джерела без -імпорту середовища виконання plugin. +селектором, чи присутні очікувані метадані цілісності та чи також доступний +локальний шлях джерела. Коли ідентичність каталогу/пакета відома, нормалізовані +факти попереджають, якщо розібране ім’я npm-пакета відхиляється від цієї ідентичності. +Вони також попереджають, коли `defaultChoice` є недійсним або вказує на джерело, +яке недоступне, і коли метадані цілісності npm присутні без дійсного npm- +джерела. Споживачі мають трактувати `installSource` як адитивне необов’язкове поле, щоб +створені вручну записи та shim каталогу не мусили синтезувати його. +Це дає змогу онбордингу та діагностиці пояснювати стан площини джерел без +імпорту середовища виконання Plugin. -Офіційні зовнішні npm-записи мають віддавати перевагу точному `npmSpec` разом із -`expectedIntegrity`. Прості імена пакетів і dist-tags все ще працюють для -сумісності, але вони показують попередження площини джерела, щоб каталог міг рухатися -до інсталяцій із pinned-версіями та перевіркою цілісності без порушення роботи наявних plugin. -Коли онбординг виконує інсталяцію з локального шляху каталогу, він записує керований запис -ledger інсталяції plugin із `source: "path"` і `sourcePath`, відносним до робочої області, -коли це можливо. Абсолютний робочий шлях завантаження залишається в -`plugins.load.paths`; запис інсталяції уникає дублювання локальних шляхів робочої станції -в довготривалій конфігурації. Це зберігає видимість локальних інсталяцій для розробки для -діагностики площини джерела без додавання другої сирої поверхні розкриття шляху файлової системи. -Застарілі записи конфігурації `plugins.installs` і далі зчитуються як -резервний варіант сумісності, поки керований станом ledger `plugins/installs.json` -стає джерелом істини для стану інсталяції. -`openclaw doctor --fix` мігрує ці застарілі записи конфігурації до керованого -ledger і оновлює холодний індекс реєстру без завантаження модулів середовища виконання plugin. +Офіційні зовнішні записи npm мають надавати перевагу точному `npmSpec` разом із +`expectedIntegrity`. Голі імена пакетів і dist-tag усе ще працюють для +сумісності, але вони показують попередження рівня площини джерел, щоб каталог міг +рухатися до зафіксованих установлень із перевіркою цілісності, не ламаючи +наявні Plugin. Коли онбординг виконує встановлення з локального шляху каталогу, він записує керований Plugin +запис індексу Plugin із `source: "path"` і відносним до workspace +`sourcePath`, коли це можливо. Абсолютний робочий шлях завантаження залишається в +`plugins.load.paths`; запис встановлення уникає дублювання шляхів локальної робочої станції +в довгоживучій конфігурації. Це робить локальні інсталяції для розробки видимими для +діагностики площини джерел без додавання другої сирої поверхні розкриття +шляху файлової системи. Постійний індекс Plugin `plugins/installs.json` є джерелом істини для встановлень і +може оновлюватися без завантаження модулів середовища виконання Plugin. +Його мапа `installRecords` є сталою навіть тоді, коли маніфест Plugin відсутній або +недійсний; його масив `plugins` — це відтворюваний вигляд маніфесту/кешу. ## Plugin рушія контексту Plugin рушія контексту володіють оркестрацією контексту сесії для ingest, assembly -та Compaction. Реєструйте їх зі свого plugin за допомогою -`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через +і Compaction. Реєструйте їх зі свого Plugin через +`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій за допомогою `plugins.slots.contextEngine`. -Використовуйте це, коли вашому plugin потрібно замінити або розширити типовий -конвеєр контексту, а не просто додати пошук у пам’яті чи хуки. +Використовуйте це, коли вашому Plugin потрібно замінити або розширити типовий конвеєр +контексту, а не просто додати пошук у пам’яті чи гачки. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1005,45 +995,45 @@ export default function (api) { ## Додавання нової можливості -Коли plugin потребує поведінки, яка не вписується в поточний API, не обходьте -систему plugin через приватне внутрішнє звернення. Додайте відсутню можливість. +Коли Plugin потрібна поведінка, яка не вписується в поточний API, не обходьте +систему Plugin через приватне глибоке втручання. Додайте відсутню можливість. Рекомендована послідовність: 1. визначте контракт ядра - Вирішіть, якою спільною поведінкою має володіти ядро: policy, fallback, merge конфігурації, + Вирішіть, якою спільною поведінкою має володіти ядро: policy, fallback, злиття config, lifecycle, семантика для каналів і форма допоміжних засобів середовища виконання. -2. додайте типізовані поверхні реєстрації plugin/середовища виконання - Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною - типізованою поверхнею можливості. -3. підключіть ядро + споживачів каналів/функцій - Канали та plugin функцій мають споживати нову можливість через ядро, - а не імпортувати реалізацію вендора напряму. -4. зареєструйте реалізації вендора - Потім plugin вендорів реєструють свої бекенди для цієї можливості. +2. додайте типізовані поверхні реєстрації/середовища виконання Plugin + Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною + типізованою поверхнею можливостей. +3. підключіть ядро + споживачів каналів/можливостей + Канали та Plugin можливостей мають споживати нову можливість через ядро, + а не імпортувати реалізацію постачальника безпосередньо. +4. зареєструйте реалізації постачальників + Потім Plugin постачальників реєструють свої бекенди для цієї можливості. 5. додайте покриття контракту - Додайте тести, щоб форма володіння та реєстрації з часом залишалася явною. + Додайте тести, щоб форма володіння й реєстрації з часом залишалася явною. -Саме так OpenClaw зберігає чітку позицію, не стаючи жорстко прив’язаним до -бачення одного провайдера. Див. [Capability Cookbook](/uk/plugins/architecture) -для конкретного контрольного списку файлів і готового прикладу. +Саме так OpenClaw зберігає свою виразну архітектуру, не стаючи жорстко прив’язаним до +бачення одного провайдера. Див. [Capability Cookbook](/uk/plugins/architecture), +щоб переглянути конкретний перелік файлів і готовий приклад. -### Контрольний список можливостей +### Контрольний список можливості -Коли ви додаєте нову можливість, реалізація зазвичай має разом зачіпати ці -поверхні: +Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися +цих поверхонь: -- типи контрактів ядра в `src//types.ts` -- виконавець ядра/допоміжний засіб середовища виконання в `src//runtime.ts` -- поверхню реєстрації API plugin в `src/plugins/types.ts` -- підключення реєстру plugin в `src/plugins/registry.ts` -- відкриття середовища виконання plugin в `src/plugins/runtime/*`, коли plugin функцій/каналів - мають це споживати -- допоміжні засоби capture/test в `src/test-utils/plugin-registration.ts` +- типи контракту ядра в `src//types.ts` +- runner/допоміжний засіб середовища виконання ядра в `src//runtime.ts` +- поверхня реєстрації API Plugin у `src/plugins/types.ts` +- підключення реєстру Plugin у `src/plugins/registry.ts` +- відкриття середовища виконання Plugin у `src/plugins/runtime/*`, коли Plugin можливостей/каналів + мають її споживати +- допоміжні засоби capture/test у `src/test-utils/plugin-registration.ts` - перевірки володіння/контракту в `src/plugins/contracts/registry.ts` -- документацію для операторів/plugin у `docs/` +- документація для операторів/Plugin у `docs/` -Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість +Якщо однієї з цих поверхонь бракує, зазвичай це ознака того, що можливість ще не повністю інтегрована. ### Шаблон можливості @@ -1051,14 +1041,14 @@ export default function (api) { Мінімальний шаблон: ```ts -// core contract +// контракт ядра export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// plugin API +// API Plugin api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1067,7 +1057,7 @@ api.registerVideoGenerationProvider({ }, }); -// shared runtime helper for feature/channel plugins +// спільний допоміжний засіб середовища виконання для Plugin можливостей/каналів const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, @@ -1080,16 +1070,16 @@ const clip = await api.runtime.videoGeneration.generate({ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -Це зберігає правило простим: +Це зберігає просте правило: -- ядро володіє контрактом можливості + оркестрацією -- plugin вендорів володіють реалізаціями вендорів -- plugin функцій/каналів споживають допоміжні засоби середовища виконання -- тести контрактів зберігають явність володіння +- ядро володіє контрактом можливості + orchestration +- Plugin постачальників володіють реалізаціями постачальників +- Plugin можливостей/каналів споживають допоміжні засоби середовища виконання +- тести контракту зберігають явність володіння -## Пов’язане +## Пов’язані матеріали - [Архітектура Plugin](/uk/plugins/architecture) — публічна модель можливостей і форми -- [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths) -- [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення plugin](/uk/plugins/building-plugins) +- [Підшляхи SDK Plugin](/uk/plugins/sdk-subpaths) +- [Налаштування SDK Plugin](/uk/plugins/sdk-setup) +- [Створення Plugin](/uk/plugins/building-plugins) diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index 1542029fa..ddcd46784 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -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/`, усе ще автоматично вмикають комплектний Plugin `codex`. Нові конфігурації мають -надавати перевагу `openai/` плюс явний запис `embeddedHarness`, наведений вище. +Застарілі конфігурації, які задають `agents.defaults.model` або модель агента як +`codex/`, усе ще автоматично вмикають вбудований Plugin `codex`. Нові конфігурації мають +віддавати перевагу `openai/` плюс явний запис `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 ` приєднує поточну сесію 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 ` прив’язує поточну сесію 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) diff --git a/docs/uk/plugins/community.md b/docs/uk/plugins/community.md index 9f7e1b0fd..c7a69ad56 100644 --- a/docs/uk/plugins/community.md +++ b/docs/uk/plugins/community.md @@ -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 ``` -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 спільноти, які є корисними, документованими та безпечними в експлуатації. Ваш Plugin має встановлюватися через `openclaw plugins install \`. - Публікуйте в [ClawHub](/uk/tools/clawhub) (бажано) або npm. - Повний посібник див. у [Building Plugins](/uk/plugins/building-plugins). + Опублікуйте його в [ClawHub](/uk/tools/clawhub) (бажано) або npm. + Повний посібник дивіться в [Створення Plugin](/uk/plugins/building-plugins). - Вихідний код має бути в публічному репозиторії з документацією щодо налаштування та - issue tracker. + Вихідний код має бути в публічному репозиторії з документацією з налаштування та + трекером проблем. - Вам не потрібен PR до документації лише для того, щоб зробити свій Plugin доступним для пошуку. Опублікуйте його + Вам не потрібен PR до документації лише для того, щоб ваш Plugin можна було знайти. Натомість опублікуйте його в ClawHub. - Відкривайте PR до документації лише тоді, коли вихідна документація OpenClaw справді потребує - зміни вмісту, наприклад для виправлення інструкцій зі встановлення або додавання міжрепозиторної + Відкривайте PR до документації лише тоді, коли у вихідній документації OpenClaw потрібна реальна + зміна вмісту, наприклад виправлення інструкцій зі встановлення або додавання міжрепозиторної документації, яка має належати до основного набору документації. @@ -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) — схема маніфесту diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index c4290697d..e6c06928e 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,53 +1,64 @@ --- read_when: - - Ви створюєте Plugin OpenClaw - - Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin -summary: Вимоги до маніфесту Plugin + схеми JSON (сувора валідація конфігурації) + - Ви створюєте Plugin для OpenClaw + - Вам потрібно постачати схему конфігурації plugin або налагодити помилки валідації plugin +summary: Маніфест Plugin + вимоги до JSON schema (сувора валідація конфігурації) title: Маніфест Plugin x-i18n: - generated_at: "2026-04-25T02:02:02Z" + generated_at: "2026-04-26T00:19:16Z" model: gpt-5.4 provider: openai - source_hash: fa96930c3c9b890194869eb793c65a0af9db43f8f8b1f78d3c3d6ef18b70be6e + source_hash: 47e3d74576a33c98ea58d29e74d3589eed3c69750e53f1acfe164dcc92b0e592 source_path: plugins/manifest.md workflow: 15 --- -Ця сторінка стосується лише **власного маніфесту Plugin OpenClaw**. +Ця сторінка призначена **лише для нативного маніфесту Plugin OpenClaw**. -Сумісні макети пакетів див. у [Пакети Plugin](/uk/plugins/bundles). +Сумісні макети bundle описані в [Plugin bundles](/uk/plugins/bundles). -Сумісні формати пакетів використовують інші файли маніфесту: +Сумісні формати bundle використовують інші файли маніфесту: -- Пакет Codex: `.codex-plugin/plugin.json` -- Пакет Claude: `.claude-plugin/plugin.json` або стандартний макет компонента Claude без маніфесту -- Пакет Cursor: `.cursor-plugin/plugin.json` +- Codex bundle: `.codex-plugin/plugin.json` +- Claude bundle: `.claude-plugin/plugin.json` або стандартний макет компонента Claude + без маніфесту +- Cursor bundle: `.cursor-plugin/plugin.json` -OpenClaw також автоматично визначає ці макети пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. +OpenClaw також автоматично визначає ці макети bundle, але вони не проходять валідацію +за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені кореневі каталоги skill, кореневі каталоги команд Claude, значення за замовчуванням із `settings.json` пакета Claude, значення LSP за замовчуванням пакета Claude та підтримувані набори hook, коли макет відповідає очікуванням рантайму OpenClaw. +Для сумісних bundle OpenClaw наразі читає метадані bundle разом з оголошеними +коренями Skills, коренями команд Claude, значеннями `settings.json` bundle Claude за замовчуванням, +типовими значеннями LSP bundle Claude та підтримуваними наборами hook, коли макет відповідає +очікуванням runtime OpenClaw. -Кожен власний Plugin OpenClaw **повинен** постачати файл `openclaw.plugin.json` у **корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду Plugin**. Відсутні або недійсні маніфести вважаються помилками Plugin і блокують валідацію конфігурації. +Кожен нативний Plugin OpenClaw **повинен** постачати файл `openclaw.plugin.json` у +**корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації +**без виконання коду plugin**. Відсутні або невалідні маніфести вважаються +помилками plugin і блокують валідацію конфігурації. -Повний посібник із системи Plugin див. тут: [Plugins](/uk/tools/plugin). -Щодо власної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності: +Повний посібник із системи plugin дивіться тут: [Plugins](/uk/tools/plugin). +Для нативної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). -## Що робить цей файл +## Для чого потрібен цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **перед завантаженням коду вашого Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску рантайму Plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження коду +вашого plugin**. Усе нижче має бути достатньо легким для перевірки без запуску +runtime plugin. **Використовуйте його для:** -- ідентичності Plugin, валідації конфігурації та підказок для UI конфігурації -- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) -- підказок активації для поверхонь control plane -- скороченого визначення належності до сімейства моделей -- статичних знімків належності можливостей (`contracts`) -- метаданих QA runner, які може перевіряти спільний хост `openclaw qa` -- метаданих конфігурації каналу, специфічних для каналу, об’єднаних у поверхні каталогу та валідації +- ідентичності plugin, валідації конфігурації та підказок UI для конфігурації +- метаданих автентифікації, онбордингу й налаштування (псевдонім, автоувімкнення, env vars провайдера, варіанти автентифікації) +- підказок активації для поверхонь control-plane +- скороченого володіння сімейством моделей +- статичних знімків володіння можливостями (`contracts`) +- метаданих QA runner, які спільний хост `openclaw qa` може перевіряти +- метаданих конфігурації, специфічних для каналу, які об’єднуються з поверхнями каталогу та валідації -**Не використовуйте його для:** реєстрації поведінки рантайму, оголошення точок входу коду або метаданих встановлення npm. Це належить до коду вашого Plugin і `package.json`. +**Не використовуйте його для:** реєстрації поведінки runtime, оголошення +точок входу коду або метаданих встановлення npm. Вони належать коду вашого plugin і `package.json`. ## Мінімальний приклад @@ -68,7 +79,7 @@ OpenClaw також автоматично визначає ці макети п { "id": "openrouter", "name": "OpenRouter", - "description": "OpenRouter provider plugin", + "description": "Plugin провайдера OpenRouter", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { @@ -96,19 +107,19 @@ OpenClaw також автоматично визначає ці макети п "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "OpenRouter API key", + "choiceLabel": "Ключ API OpenRouter", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "OpenRouter API key", + "cliDescription": "Ключ API OpenRouter", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "API key", + "label": "Ключ API", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -129,66 +140,69 @@ OpenClaw також автоматично визначає ці макети п | Поле | Обов’язкове | Тип | Що воно означає | | ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний id Plugin. Це id, який використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована схема JSON для конфігурації цього Plugin. | -| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Пропустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб Plugin залишався вимкненим за замовчуванням. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id Plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які мають автоматично вмикати цей Plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Id каналів, що належать цьому Plugin. Використовуються для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Id провайдерів, що належать цьому Plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення провайдера, відносний до кореня Plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного рантайму Plugin. | -| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту, і використовуються для автоматичного завантаження Plugin до рантайму. | -| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, що належать цьому Plugin. Це контракт control plane для майбутнього читання списків у режимі лише для читання, онбордингу, засобів вибору моделей, псевдонімів і приглушення без завантаження рантайму Plugin. | -| `providerEndpoints` | Ні | `object[]` | Метадані хостів кінцевих точок/baseUrl, що належать маніфесту, для маршрутів провайдерів, які ядро має класифікувати до завантаження рантайму провайдера. | -| `cliBackends` | Ні | `string[]` | Id backend CLI inference, що належать цьому Plugin. Використовуються для автоактивації під час запуску на основі явних посилань у конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдерів або backend CLI, для яких синтетичний hook автентифікації, що належить Plugin, має перевірятися під час cold model discovery до завантаження рантайму. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, що належать вбудованому Plugin і представляють не секретний локальний стан, OAuth або стан ambient credentials. | -| `commandAliases` | Ні | `object[]` | Імена команд, що належать цьому Plugin і мають створювати діагностику конфігурації та CLI, обізнану про Plugin, до завантаження рантайму. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/статусу провайдера. Для нових Plugin віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це протягом періоду знецінення. | -| `providerAuthAliases` | Ні | `Record` | Id провайдерів, які мають повторно використовувати інший id провайдера для пошуку автентифікації, наприклад провайдер кодування, що використовує той самий API-ключ базового провайдера та профілі автентифікації. | -| `channelEnvVars` | Ні | `Record` | Легкі метадані env каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналів на основі env або поверхонь автентифікації, які мають бачити універсальні помічники запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення пріоритетного провайдера та простого зв’язування CLI-прапорців. | -| `activation` | Ні | `object` | Легкі метадані планувальника активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактична поведінка все ще належить рантайму Plugin. | -| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження рантайму Plugin. | -| `qaRunners` | Ні | `object[]` | Легкі дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження рантайму Plugin. | -| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх hook автентифікації, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, web search і належності інструментів. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легкі значення за замовчуванням для розуміння медіа для id провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту, об’єднані в поверхні виявлення та валідації до завантаження рантайму. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореня Plugin. | -| `name` | Ні | `string` | Зрозуміла для людини назва Plugin. | -| `description` | Ні | `string` | Короткий опис, що відображається на поверхнях Plugin. | -| `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки чутливості для полів конфігурації. | +| `id` | Так | `string` | Канонічний id plugin. Це id, який використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього plugin. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований plugin як увімкнений за замовчуванням. Пропустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб plugin був вимкнений за замовчуванням. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які мають автоматично вмикати цей plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип plugin, який використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Id каналів, якими володіє цей plugin. Використовується для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Id провайдерів, якими володіє цей plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Полегшений шлях до модуля виявлення провайдера, відносно кореня plugin, для метаданих каталогу провайдерів в області маніфесту, які можна завантажити без активації повного runtime plugin. | +| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, якими володіє маніфест, що використовуються для автоматичного завантаження plugin до runtime. | +| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей plugin. Це контракт control-plane для майбутніх режимів лише читання: переліку, онбордингу, вибору моделей, псевдонімів і приховування без завантаження runtime plugin. | +| `providerEndpoints` | Ні | `object[]` | Метадані хостів/`baseUrl` кінцевих точок, якими володіє маніфест, для маршрутів провайдерів, які ядро має класифікувати до завантаження runtime провайдера. | +| `cliBackends` | Ні | `string[]` | Id backend CLI inference, якими володіє цей plugin. Використовується для автоматичної активації під час запуску з явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або backend CLI, для яких слід перевіряти синтетичний hook автентифікації, що належить plugin, під час холодного виявлення моделей до завантаження runtime. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, що належать вбудованому plugin і позначають несекретний локальний стан, OAuth або стан ambient credential. | +| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей plugin, що мають давати діагностику конфігурації та CLI з урахуванням plugin до завантаження runtime. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/статусу провайдера. Для нових plugin віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це протягом вікна зворотної сумісності. | +| `providerAuthAliases` | Ні | `Record` | Id провайдерів, які мають повторно використовувати інший id провайдера для пошуку автентифікації, наприклад провайдер для кодування, який спільно використовує API-ключ базового провайдера та профілі автентифікації. | +| `channelEnvVars` | Ні | `Record` | Легкі метадані env для каналів, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для налаштування каналів або поверхонь автентифікації на основі env, які мають бачити загальні helpers запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для вибору під час онбордингу, визначення бажаного провайдера та простого зв’язування прапорців CLI. | +| `activation` | Ні | `object` | Легкі метадані планувальника активації для завантаження, що запускається провайдерами, командами, каналами, маршрутами й можливостями. Лише метадані; фактична поведінка, як і раніше, належить runtime plugin. | +| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime plugin. | +| `qaRunners` | Ні | `object[]` | Легкі дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження runtime plugin. | +| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх hook автентифікації, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, web search і володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легкі типові значення розуміння медіа для id провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналів, якими володіє маніфест, що об’єднуються з поверхнями виявлення та валідації до завантаження runtime. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. | +| `name` | Ні | `string` | Зрозуміла людині назва plugin. | +| `description` | Ні | `string` | Короткий опис, що показується на поверхнях plugin. | +| `version` | Ні | `string` | Інформаційна версія plugin. | +| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. -OpenClaw зчитує це до завантаження рантайму провайдера. -Потік налаштування провайдера надає перевагу цим варіантам із маніфесту, а потім для сумісності повертається до метаданих wizard рантайму та варіантів каталогу встановлення. +OpenClaw читає це до завантаження runtime провайдера. +Потік налаштування провайдера надає перевагу цим варіантам з маніфесту, а потім для сумісності +переходить до метаданих wizard runtime та варіантів із каталогу встановлення. | Поле | Обов’язкове | Тип | Що воно означає | | --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `provider` | Так | `string` | Id провайдера, до якого належить цей варіант. | -| `method` | Так | `string` | Id методу автентифікації, до якого слід маршрутизувати. | -| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, який використовується потоками онбордингу та CLI. | +| `method` | Так | `string` | Id методу автентифікації, до якого потрібно диспетчеризувати. | +| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, який використовується в онбордингу та CLI-потоках. | | `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | | `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих помічником. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант у засобах вибору помічника, але все ще дозволяє ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів до цього замінного варіанта. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих асистентом. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант від засобів вибору асистента, але все ще дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які повинні перенаправляти користувачів до цього варіанта-замінника. | | `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. | +| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. | | `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | | `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним прапорцем. | | `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, використовується `["text-inference"]` за замовчуванням. | +| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має відображатися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли Plugin володіє назвою команди рантайму, яку користувачі можуть помилково помістити в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду рантайму Plugin. +Використовуйте `commandAliases`, коли plugin володіє назвою runtime-команди, яку користувачі можуть +помилково додати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw +використовує ці метадані для діагностики без імпорту коду runtime plugin. ```json { @@ -202,21 +216,34 @@ OpenClaw зчитує це до завантаження рантайму про } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | -------------------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, яка належить цьому Plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як команду слеша чату, а не як кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо існує. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, яка належить цьому plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід підказати для операцій CLI, якщо така існує. | ## Довідник `activation` -Використовуйте `activation`, коли Plugin може дешево оголосити, які події control plane мають включати його до плану активації/завантаження. +Використовуйте `activation`, коли plugin може дешево оголосити, які події control-plane +мають включати його до плану активації/завантаження. -Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку рантайму, не замінює `register(...)` і не обіцяє, що код Plugin уже був виконаний. Планувальник активації використовує ці поля, щоб звузити коло кандидатів серед Plugin, перш ніж повернутися до наявних метаданих належності в маніфесті, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hooks. +Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє +поведінку runtime, не замінює `register(...)` і не обіцяє, що код +plugin уже виконано. Планувальник активації використовує ці поля, щоб звузити коло +кандидатів plugin, перш ніж переходити до наявних метаданих володіння маніфестом, +таких як `providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і hooks. -Надавайте перевагу найвужчим метаданим, які вже описують належність. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальнику, які не можна представити цими полями належності. +Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте +`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, +коли ці поля виражають цей зв’язок. Використовуйте `activation` для додаткових підказок планувальника, +які не можна представити цими полями володіння. -Цей блок містить лише метадані. Він не реєструє поведінку рантайму й не замінює `register(...)`, `setupEntry` чи інші точки входу рантайму/Plugin. Поточні споживачі використовують його як підказку для звуження кола перед ширшим завантаженням Plugin, тому відсутність метаданих активації зазвичай впливає лише на продуктивність; це не повинно змінювати коректність, поки ще існують застарілі резервні механізми належності маніфесту. +Цей блок містить лише метадані. Він не реєструє поведінку runtime і +не замінює `register(...)`, `setupEntry` або інші точки входу runtime/plugin. +Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням plugin, тому +відсутність метаданих активації зазвичай впливає лише на продуктивність; це не повинно +змінювати коректність, доки все ще існують застарілі резервні механізми володіння маніфестом. ```json { @@ -230,49 +257,58 @@ OpenClaw зчитує це до завантаження рантайму про } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ---------------- | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Id провайдерів, які мають включати цей Plugin до планів активації/завантаження. | -| `onCommands` | Ні | `string[]` | Id команд, які мають включати цей Plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Id каналів, які мають включати цей Plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Види маршрутів, які мають включати цей Plugin до планів активації/завантаження. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки щодо можливостей, які використовуються плануванням активації control plane. За можливості надавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ---------------- | ----------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Id провайдерів, які мають включати цей plugin до планів активації/завантаження. | +| `onCommands` | Ні | `string[]` | Id команд, які мають включати цей plugin до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | Id каналів, які мають включати цей plugin до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей plugin до планів активації/завантаження. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки щодо можливостей, що використовуються плануванням активації control-plane. За можливості надавайте перевагу вужчим полям. | Поточні активні споживачі: -- планування CLI, ініційоване командою, повертається до застарілого +- CLI-планування, запущене командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` -- планування setup/каналу, ініційоване каналом, повертається до застарілої - належності `channels[]`, якщо явні метадані активації каналу відсутні -- планування setup/рантайму, ініційоване провайдером, повертається до застарілої - належності `providers[]` і верхньорівневої `cliBackends[]`, якщо явні - метадані активації провайдера відсутні +- планування setup/каналів, запущене каналом, повертається до застарілого володіння `channels[]`, + коли відсутні явні метадані активації каналу +- планування setup/runtime, запущене провайдером, повертається до застарілого + володіння `providers[]` і `cliBackends[]` верхнього рівня, коли відсутні явні метадані + активації провайдера -Діагностика планувальника може розрізняти явні підказки активації та резервне використання належності маніфесту. Наприклад, `activation-command-hint` означає, що збіглося `activation.onCommands`, а `manifest-command-alias` означає, що планувальник натомість використав належність `commandAliases`. Ці мітки причин призначені для діагностики та тестів хоста; автори Plugin мають і надалі оголошувати метадані, які найкраще описують належність. +Діагностика планувальника може відрізняти явні підказки активації від резервного +володіння маніфестом. Наприклад, `activation-command-hint` означає, що +спрацював збіг `activation.onCommands`, а `manifest-command-alias` означає, що +планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для +діагностики хоста та тестів; авторам plugin слід і далі оголошувати ті метадані, +які найкраще описують володіння. ## Довідник `qaRunners` -Використовуйте `qaRunners`, коли Plugin додає один або кілька runner транспорту під спільним коренем `openclaw qa`. Зберігайте ці метадані легкими та статичними; фактична реєстрація CLI все ще належить рантайму Plugin через легку поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. +Використовуйте `qaRunners`, коли plugin додає один або більше транспортних runner під +спільний корінь `openclaw qa`. Залишайте ці метадані легкими й статичними; runtime +plugin, як і раніше, володіє фактичною реєстрацією CLI через полегшену +поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { "qaRunners": [ { "commandName": "matrix", - "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver" + "description": "Запустити live QA lane для Matrix на основі Docker проти одноразового homeserver" } ] } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | -------- | ----------------------------------------------------------------------- | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | -------- | --------------------------------------------------------------------- | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | | `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. | ## Довідник `setup` -Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні дешеві метадані, що належать Plugin, до завантаження рантайму. +Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні дешеві метадані plugin, +якими він володіє, до завантаження runtime. ```json { @@ -291,47 +327,72 @@ OpenClaw зчитує це до завантаження рантайму про } ``` -Верхньорівневе `cliBackends` залишається дійсним і надалі описує backend CLI inference. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків control plane/setup, які мають залишатися лише метаданими. +`cliBackends` верхнього рівня залишається валідним і й надалі описує +backend CLI inference. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для +потоків control-plane/setup, які мають залишатися лише метаданими. -Якщо вони присутні, `setup.providers` і `setup.cliBackends` є пріоритетною поверхнею пошуку за принципом “спочатку дескриптор” для виявлення setup. Якщо дескриптор лише звужує коло кандидатів Plugin, а setup усе ще потребує багатших hook рантайму під час налаштування, встановіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. +Коли вони присутні, `setup.providers` і `setup.cliBackends` є бажаною +поверхнею пошуку для виявлення setup за принципом "спочатку дескриптор". Якщо дескриптор лише +звужує кандидатний plugin, а setup усе ще потребує багатших runtime-hooks під час налаштування, +установіть `requiresRuntime: true` і залиште `setup-api` як +резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` до загальних пошуків автентифікації провайдера та змінних середовища. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом періоду знецінення, але небудовані Plugin, які все ще його використовують, отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані env для setup/статусу в `setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` до загальних пошуків автентифікації провайдерів і +env vars. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом +вікна знецінення, але plugin не з комплекту, які все ще його використовують, +отримують діагностику маніфесту. Нові plugin мають розміщувати метадані env для setup/статусу +в `setup.providers[].envVars`. -OpenClaw також може виводити прості варіанти setup із `setup.providers[].authMethods`, коли запис setup недоступний або коли `setup.requiresRuntime: false` оголошує, що рантайм setup не потрібен. Явні записи `providerAuthChoices` і далі мають пріоритет для нетипових міток, прапорців CLI, області онбордингу та метаданих помічника. +OpenClaw також може виводити прості варіанти setup з `setup.providers[].authMethods`, +коли запис setup недоступний або коли `setup.requiresRuntime: false` +оголошує runtime setup непотрібним. Явні записи `providerAuthChoices` і далі мають +перевагу для спеціальних міток, прапорців CLI, області онбордингу та метаданих асистента. -Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише на рівні дескрипторів і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо Plugin, що має працювати лише на дескрипторах, усе ж постачає один із цих записів рантайму setup, OpenClaw повідомляє додаткову діагностику й продовжує його ігнорувати. Пропущене `requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні Plugin, які додали дескриптори без цього прапорця, не ламалися. +Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для +поверхні setup. OpenClaw трактує явне `false` як контракт лише з дескрипторами +і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо +plugin лише з дескрипторами все ж постачає одну з цих runtime-точок входу setup, +OpenClaw повідомляє про додаткову діагностику та продовжує її ігнорувати. Пропущене +`requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні plugin, які додали +дескриптори без цього прапорця, не ламалися. -Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед виявлених Plugin. Неоднозначна належність завершується за принципом fail closed замість вибору переможця за порядком виявлення. +Оскільки пошук setup може виконувати код `setup-api`, яким володіє plugin, +нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед +виявлених plugin. Неоднозначне володіння завершується закриттям, а не вибором +переможця за порядком виявлення. -Коли рантайм setup все ж виконується, діагностика реєстру setup повідомляє про розходження дескрипторів, якщо `setup-api` реєструє провайдера або backend CLI, яких не оголошують дескриптори маніфесту, або якщо для дескриптора немає відповідної реєстрації рантайму. Ці діагностики є додатковими й не відхиляють застарілі Plugin. +Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про розходження дескрипторів, якщо +`setup-api` реєструє провайдера або backend CLI, які не оголошені дескрипторами маніфесту, +або якщо дескриптор не має відповідної реєстрації в runtime. +Ця діагностика є додатковою і не відхиляє застарілі plugin. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Id провайдера, що надається під час setup або онбордингу. Підтримуйте глобально унікальні нормалізовані id. | -| `authMethods` | Ні | `string[]` | Id методів setup/автентифікації, які цей провайдер підтримує без завантаження повного рантайму. | -| `envVars` | Ні | `string[]` | Змінні середовища, які універсальні поверхні setup/статусу можуть перевіряти до завантаження рантайму Plugin. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Id провайдера, який відкривається під час setup або онбордингу. Нормалізовані id мають бути глобально унікальними. | +| `authMethods` | Ні | `string[]` | Id методів setup/автентифікації, які цей провайдер підтримує без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/статусу можуть перевіряти до завантаження runtime plugin. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | ----------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори setup провайдера, доступні під час setup та онбордингу. | -| `cliBackends` | Ні | `string[]` | Id backend часу setup, які використовуються для пошуку setup за принципом “спочатку дескриптор”. Підтримуйте глобально унікальні нормалізовані id. | -| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, що належать поверхні setup цього Plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори setup провайдерів, доступні під час setup та онбордингу. | +| `cliBackends` | Ні | `string[]` | Id backend для setup, які використовуються для пошуку setup за принципом "спочатку дескриптор". Нормалізовані id мають бути глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє поверхня setup цього plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. | ## Довідник `uiHints` -`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу. +`uiHints` — це мапа від імен полів конфігурації до невеликих підказок рендерингу. ```json { "uiHints": { "apiKey": { - "label": "API key", - "help": "Used for OpenRouter requests", + "label": "Ключ API", + "help": "Використовується для запитів OpenRouter", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -339,20 +400,21 @@ OpenClaw також може виводити прості варіанти setu } ``` -Кожна підказка для поля може містити: +Кожна підказка поля може містити: -| Поле | Тип | Що воно означає | -| ------------- | ---------- | --------------------------------------- | -| `label` | `string` | Мітка поля для користувача. | -| `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові теги UI. | -| `advanced` | `boolean` | Позначає поле як розширене. | -| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст-заповнювач для полів форми. | +| Поле | Тип | Що воно означає | +| ------------- | ---------- | -------------------------------------- | +| `label` | `string` | Мітка поля для користувача. | +| `help` | `string` | Короткий допоміжний текст. | +| `tags` | `string[]` | Необов’язкові теги UI. | +| `advanced` | `boolean` | Позначає поле як розширене. | +| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | +| `placeholder` | `string` | Текст-заповнювач для полів форми. | ## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих належності можливостей, які OpenClaw може зчитувати без імпорту рантайму Plugin. +Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може +прочитати без імпорту runtime plugin. ```json { @@ -375,31 +437,46 @@ OpenClaw також може виводити прості варіанти setu Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | ------------------------------------------------------------------------ | -| `embeddedExtensionFactories` | `string[]` | Id фабрик extension app-server Codex, наразі `codex-app-server`. | -| `agentToolResultMiddleware` | `string[]` | Id рантайму, для яких вбудований Plugin може зареєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | Id провайдерів, чий hook профілю зовнішньої автентифікації належить цьому Plugin. | -| `speechProviders` | `string[]` | Id провайдерів мовлення, що належать цьому Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів транскрипції в реальному часі, що належать цьому Plugin. | -| `realtimeVoiceProviders` | `string[]` | Id провайдерів голосу в реальному часі, що належать цьому Plugin. | -| `memoryEmbeddingProviders` | `string[]` | Id провайдерів embedding пам’яті, що належать цьому Plugin. | -| `mediaUnderstandingProviders` | `string[]` | Id провайдерів розуміння медіа, що належать цьому Plugin. | -| `imageGenerationProviders` | `string[]` | Id провайдерів генерації зображень, що належать цьому Plugin. | -| `videoGenerationProviders` | `string[]` | Id провайдерів генерації відео, що належать цьому Plugin. | -| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, що належать цьому Plugin. | -| `webSearchProviders` | `string[]` | Id провайдерів web search, що належать цьому Plugin. | -| `tools` | `string[]` | Назви інструментів агента, що належать цьому Plugin для перевірок вбудованих контрактів. | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | -------------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Id фабрик розширень app-server Codex, наразі `codex-app-server`. | +| `agentToolResultMiddleware` | `string[]` | Id runtime, для яких вбудований plugin може реєструвати middleware результатів інструментів. | +| `externalAuthProviders` | `string[]` | Id провайдерів, hook зовнішнього профілю автентифікації яких належить цьому plugin. | +| `speechProviders` | `string[]` | Id провайдерів мовлення, якими володіє цей plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів транскрипції в реальному часі, якими володіє цей plugin. | +| `realtimeVoiceProviders` | `string[]` | Id провайдерів голосу в реальному часі, якими володіє цей plugin. | +| `memoryEmbeddingProviders` | `string[]` | Id провайдерів embedding для пам’яті, якими володіє цей plugin. | +| `mediaUnderstandingProviders` | `string[]` | Id провайдерів розуміння медіа, якими володіє цей plugin. | +| `imageGenerationProviders` | `string[]` | Id провайдерів генерації зображень, якими володіє цей plugin. | +| `videoGenerationProviders` | `string[]` | Id провайдерів генерації відео, якими володіє цей plugin. | +| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей plugin. | +| `webSearchProviders` | `string[]` | Id провайдерів web search, якими володіє цей plugin. | +| `tools` | `string[]` | Імена інструментів агента, якими володіє цей plugin, для перевірок вбудованих контрактів. | -`contracts.embeddedExtensionFactories` збережено для фабрик extension лише для вбудованого app-server Codex. Вбудовані трансформації результатів інструментів натомість мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися через `api.registerAgentToolResultMiddleware(...)`. Зовнішні Plugin не можуть реєструвати middleware результатів інструментів, оскільки цей шов може переписувати вихід інструменту з високим рівнем довіри до того, як модель його побачить. +`contracts.embeddedExtensionFactories` збережено для вбудованих фабрик розширень +app-server лише для Codex. Вбудовані перетворення результатів інструментів повинні +оголошувати `contracts.agentToolResultMiddleware` і реєструватися через +`api.registerAgentToolResultMiddleware(...)`. Зовнішні plugin не можуть +реєструвати middleware результатів інструментів, оскільки цей seam може переписувати вихід +інструментів із високим рівнем довіри до того, як модель їх побачить. -Plugin провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють через застарілий резервний механізм сумісності, але він повільніший і буде видалений після завершення вікна міграції. +Plugin провайдерів, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати +`contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють +через застарілий резервний механізм сумісності, але він повільніший і +буде видалений після завершення вікна міграції. -Вбудовані провайдери embedding пам’яті мають оголошувати `contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони надають, включно з вбудованими адаптерами, такими як `local`. Автономні шляхи CLI використовують цей контракт маніфесту, щоб завантажити лише Plugin-власник до того, як повний рантайм Gateway зареєструє провайдерів. +Вбудовані провайдери embedding для пам’яті повинні оголошувати +`contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони відкривають, зокрема +для вбудованих адаптерів, таких як `local`. Автономні шляхи CLI використовують цей контракт маніфесту, +щоб завантажити лише plugin-власник до того, як повний runtime Gateway +зареєструє провайдерів. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має моделі за замовчуванням, пріоритет резервної автоавтентифікації або вбудовану підтримку документів, які потрібні універсальним допоміжним функціям ядра до завантаження рантайму. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має +типові моделі, пріоритет резервного автоматичного вибору автентифікації або нативну підтримку документів, які +потрібні загальним helpers ядра до завантаження runtime. Ключі також мають бути оголошені в +`contracts.mediaUnderstandingProviders`. ```json { @@ -424,23 +501,35 @@ Plugin провайдерів, які реалізують `resolveExternalAuthP Кожен запис провайдера може містити: -| Поле | Тип | Що воно означає | -| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | -| `defaultModels` | `Record` | Значення за замовчуванням “можливість → модель”, які використовуються, коли конфігурація не задає модель. | +| Поле | Тип | Що воно означає | +| ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | +| `defaultModels` | `Record` | Типові значення "можливість → модель", що використовуються, коли в конфігурації не вказано модель. | | `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Вбудовані входи документів, які підтримує провайдер. | +| `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує провайдер. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли Plugin каналу потребує дешевих метаданих конфігурації до завантаження рантайму. Виявлення setup/статусу каналу в режимі лише для читання може використовувати ці метадані безпосередньо для налаштованих зовнішніх каналів, коли запис setup недоступний або коли `setup.requiresRuntime: false` оголошує, що рантайм setup не потрібен. +Використовуйте `channelConfigs`, коли plugin каналу потребує легких метаданих конфігурації до +завантаження runtime. Виявлення setup/статусу каналу лише для читання може безпосередньо використовувати ці метадані +для налаштованих зовнішніх каналів, коли запис setup недоступний, або +коли `setup.requiresRuntime: false` оголошує runtime setup непотрібним. -Для Plugin каналу `configSchema` і `channelConfigs` описують різні шляхи: +`channelConfigs` — це метадані маніфесту plugin, а не новий розділ конфігурації користувача верхнього рівня. +Користувачі, як і раніше, налаштовують екземпляри каналів у `channels.`. +OpenClaw читає метадані маніфесту, щоб визначити, якому plugin належить налаштований +канал, до виконання коду runtime plugin. + +Для plugin каналу `configSchema` і `channelConfigs` описують різні +шляхи: - `configSchema` перевіряє `plugins.entries..config` - `channelConfigs..schema` перевіряє `channels.` -Небудовані Plugin, які оголошують `channels[]`, також мають оголошувати відповідні записи `channelConfigs`. Без них OpenClaw все ще може завантажити Plugin, але поверхні схеми конфігурації холодного шляху, setup і Control UI не можуть знати форму параметрів, що належать каналу, доки не виконається рантайм Plugin. +Plugin не з комплекту, які оголошують `channels[]`, також повинні оголошувати відповідні +записи `channelConfigs`. Без них OpenClaw все ще може завантажити plugin, але +схема конфігурації холодного шляху, setup і поверхні Control UI не зможуть знати форму +параметрів, якими володіє канал, доки не виконається runtime plugin. ```json { @@ -455,12 +544,12 @@ Plugin провайдерів, які реалізують `resolveExternalAuthP }, "uiHints": { "homeserverUrl": { - "label": "Homeserver URL", + "label": "URL homeserver", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Matrix homeserver connection", + "description": "Підключення до homeserver Matrix", "preferOver": ["matrix-legacy"] } } @@ -469,17 +558,55 @@ Plugin провайдерів, які реалізують `resolveExternalAuthP Кожен запис каналу може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ | -| `schema` | `object` | Схема JSON для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, об’єднана в поверхні вибору та інспектування, коли метадані рантайму ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь інспектування та каталогу. | -| `preferOver` | `string[]` | Id застарілих або менш пріоритетних Plugin, які цей канал має перевершувати на поверхнях вибору. | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | -------------------------------------------------------------------------------------------- | +| `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації каналу. | +| `uiHints` | `Record` | Необов’язкові мітки UI/заповнювачі/підказки щодо чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Мітка каналу, що об’єднується з поверхнями вибору та перевірки, коли метадані runtime ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь перевірки та каталогу. | +| `preferOver` | `string[]` | Id застарілих plugin або plugin з нижчим пріоритетом, які цей канал має випереджати на поверхнях вибору. | + +### Заміна іншого plugin каналу + +Використовуйте `preferOver`, коли ваш plugin є бажаним власником для id каналу, який +інший plugin також може надавати. Типові випадки — перейменований id plugin, +автономний plugin, що замінює вбудований plugin, або підтримуваний fork, який +зберігає той самий id каналу для сумісності конфігурації. + +```json +{ + "id": "acme-chat", + "channels": ["chat"], + "channelConfigs": { + "chat": { + "schema": { + "type": "object", + "additionalProperties": false, + "properties": { + "webhookUrl": { "type": "string" } + } + }, + "preferOver": ["chat"] + } + } +} +``` + +Коли налаштовано `channels.chat`, OpenClaw враховує як id каналу, так і +id бажаного plugin. Якщо plugin з нижчим пріоритетом було вибрано лише тому, що +він вбудований або ввімкнений за замовчуванням, OpenClaw вимикає його в ефективній +конфігурації runtime, щоб один plugin володів каналом і його інструментами. Явний +вибір користувача все одно має перевагу: якщо користувач явно вмикає обидва plugin, OpenClaw +зберігає цей вибір і повідомляє про діагностику дубльованих каналів/інструментів замість +тихої зміни запитаного набору plugin. + +Обмежуйте `preferOver` id plugin, які справді можуть надавати той самий канал. +Це не загальне поле пріоритету і воно не перейменовує ключі конфігурації користувача. ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має визначати ваш Plugin провайдера зі скорочених id моделей, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження рантайму Plugin. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш plugin провайдера з +скорочених id моделей, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження runtime plugin. ```json { @@ -490,23 +617,28 @@ Plugin провайдерів, які реалізують `resolveExternalAuthP } ``` -OpenClaw застосовує такий пріоритет: +OpenClaw застосовує такий порядок пріоритету: -- явні посилання `provider/model` використовують метадані маніфесту-власника `providers` -- `modelPatterns` мають пріоритет над `modelPrefixes` -- якщо збігаються один небудований Plugin і один вбудований Plugin, перемагає небудований Plugin -- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкажуть провайдера +- явні посилання `provider/model` використовують метадані маніфесту `providers` плагіна-власника +- `modelPatterns` мають вищий пріоритет за `modelPrefixes` +- якщо збігаються один невбудований plugin і один вбудований plugin, перемагає невбудований + plugin +- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | ------------------------------------------------------------------------------ | -| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими id моделей. | -| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими id моделей після видалення суфікса профілю. | +| Поле | Тип | Що воно означає | +| --------------- | ---------- | ---------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id моделей після видалення суфікса профілю. | ## Довідник `modelCatalog` -Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до завантаження рантайму Plugin. Це джерело, що належить маніфесту, для фіксованих рядків каталогу, псевдонімів провайдера, правил приглушення та режиму виявлення. Оновлення рантайму все ще належить коду рантайму провайдера, але маніфест повідомляє ядру, коли рантайм є обов’язковим. +Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до +завантаження runtime plugin. Це джерело, яким володіє маніфест, для фіксованих +рядків каталогу, псевдонімів провайдерів, правил приховування та режиму виявлення. Оновлення runtime +і далі належить коду runtime провайдера, але маніфест повідомляє ядру, коли runtime +є обов’язковим. ```json { @@ -545,7 +677,7 @@ OpenClaw застосовує такий пріоритет: { "provider": "azure-openai-responses", "model": "gpt-5.3-codex-spark", - "reason": "not available on Azure OpenAI Responses" + "reason": "недоступно в Azure OpenAI Responses" } ], "discovery": { @@ -557,101 +689,133 @@ OpenClaw застосовує такий пріоритет: Поля верхнього рівня: -| Поле | Тип | Що воно означає | -| -------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | Рядки каталогу для id провайдерів, що належать цьому Plugin. Ключі також мають з’являтися у верхньорівневому `providers`. | -| `aliases` | `Record` | Псевдоніми провайдерів, які мають розв’язуватися в провайдера-власника для планування каталогу або приглушення. | -| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin приглушує з причини, специфічної для провайдера. | -| `discovery` | `Record` | Чи можна прочитати каталог провайдера з метаданих маніфесту, оновити в кеш або для цього потрібен рантайм. | +| Поле | Тип | Що воно означає | +| -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | +| `providers` | `Record` | Рядки каталогу для id провайдерів, якими володіє цей plugin. Ключі також мають бути присутні у `providers` верхнього рівня. | +| `aliases` | `Record` | Псевдоніми провайдерів, які мають резолвитися до провайдера-власника для планування каталогу або приховування. | +| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей plugin приховує з причин, специфічних для провайдера. | +| `discovery` | `Record` | Чи каталог провайдера можна читати з метаданих маніфесту, оновлювати в кеш, чи для нього потрібен runtime. | Поля провайдера: -| Поле | Тип | Що воно означає | -| --------- | ------------------------ | ------------------------------------------------------------------- | -| `baseUrl` | `string` | Необов’язковий base URL за замовчуванням для моделей у цьому каталозі провайдера. | -| `api` | `ModelApi` | Необов’язковий адаптер API за замовчуванням для моделей у цьому каталозі провайдера. | +| Поле | Тип | Що воно означає | +| --------- | ------------------------ | ------------------------------------------------------------------ | +| `baseUrl` | `string` | Необов’язковий типовий `baseUrl` для моделей у цьому каталозі провайдера. | +| `api` | `ModelApi` | Необов’язковий типовий адаптер API для моделей у цьому каталозі провайдера. | | `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до цього каталогу провайдера. | -| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | +| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | Поля моделі: | Поле | Тип | Що воно означає | | --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| `id` | `string` | Локальний для провайдера id моделі, без префікса `provider/`. | -| `name` | `string` | Необов’язкова відображувана назва. | -| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | -| `baseUrl` | `string` | Необов’язкове перевизначення base URL для окремої моделі. | -| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | -| `input` | `Array<"text" \| "image" \| "document">` | Модальності, які приймає модель. | -| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | -| `contextWindow` | `number` | Власне вікно контексту провайдера. | -| `contextTokens` | `number` | Необов’язкова ефективна межа контексту рантайму, якщо вона відрізняється від `contextWindow`. | -| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | -| `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, включно з необов’язковим `tieredPricing`. | -| `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделі OpenClaw. | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Використовуйте приглушення лише тоді, коли рядок взагалі не повинен з’являтися. | -| `statusReason` | `string` | Необов’язкова причина, що показується разом зі статусом, відмінним від доступного. | -| `replaces` | `string[]` | Старіші локальні для провайдера id моделей, які ця модель замінює. | -| `replacedBy` | `string` | Локальний для провайдера id моделі-заміни для застарілих рядків. | -| `tags` | `string[]` | Стабільні теги, які використовуються засобами вибору та фільтрами. | +| `id` | `string` | Локальний для провайдера id моделі без префікса `provider/`. | +| `name` | `string` | Необов’язкова відображувана назва. | +| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | +| `baseUrl` | `string` | Необов’язкове перевизначення `baseUrl` для окремої моделі. | +| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | +| `input` | `Array<"text" \| "image" \| "document">` | Модальності, які приймає модель. | +| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | +| `contextWindow` | `number` | Нативне вікно контексту провайдера. | +| `contextTokens` | `number` | Необов’язкове ефективне обмеження контексту runtime, якщо воно відрізняється від `contextWindow`. | +| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | +| `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, зокрема необов’язковий `tieredPricing`. | +| `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделей OpenClaw. | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у переліку. Приховуйте лише тоді, коли рядок взагалі не повинен відображатися. | +| `statusReason` | `string` | Необов’язкова причина, що показується з недоступним статусом. | +| `replaces` | `string[]` | Старіші локальні для провайдера id моделей, які ця модель замінює. | +| `replacedBy` | `string` | Локальний для провайдера id моделі-замінника для застарілих рядків. | +| `tags` | `string[]` | Стабільні теги, що використовуються засобами вибору та фільтрами. | -Не розміщуйте в `modelCatalog` дані, що стосуються лише рантайму. Якщо провайдеру потрібен стан облікового запису, API-запит або виявлення локального процесу, щоб знати повний набір моделей, оголосіть цього провайдера як `refreshable` або `runtime` у `discovery`. +Не розміщуйте в `modelCatalog` дані лише для runtime. Якщо провайдеру потрібен стан +облікового запису, API-запит або виявлення локального процесу, щоб визначити повний +набір моделей, оголосіть цього провайдера як `refreshable` або `runtime` у `discovery`. -Застарілі верхньорівневі ключі можливостей не рекомендовані. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під `contracts`; звичайне завантаження маніфесту більше не трактує ці верхньорівневі поля як належність можливостей. +Застарілі ключі можливостей верхнього рівня знецінено. Використовуйте `openclaw doctor --fix`, щоб +перемістити `speechProviders`, `realtimeTranscriptionProviders`, +`realtimeVoiceProviders`, `mediaUnderstandingProviders`, +`imageGenerationProviders`, `videoGenerationProviders`, +`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне +завантаження маніфесту більше не розглядає ці поля верхнього рівня як +володіння можливостями. -## Маніфест і `package.json` +## Маніфест проти `package.json` Ці два файли виконують різні завдання: -| Файл | Використовуйте його для | -| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідації конфігурації, метаданих варіантів автентифікації та підказок UI, які мають існувати до запуску коду Plugin | -| `package.json` | Метаданих npm, встановлення залежностей і блока `openclaw`, який використовується для точок входу, контролю встановлення, setup або метаданих каталогу | +| Файл | Для чого використовувати | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду plugin | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, обмеження встановлення, setup або метаданих каталогу | -Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте таке правило: +Якщо ви не впевнені, де має бути певний фрагмент метаданих, використовуйте таке правило: -- якщо OpenClaw має знати це до завантаження коду Plugin, помістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, помістіть це в `package.json` +- якщо OpenClaw повинен знати це до завантаження коду plugin, розміщуйте це в `openclaw.plugin.json` +- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json` -### Поля `package.json`, які впливають на виявлення +### Поля `package.json`, що впливають на виявлення -Деякі метадані Plugin до рантайму навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. +Деякі метадані plugin до runtime навмисно розміщуються в `package.json` у блоці +`openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує точки входу власного Plugin. Повинні залишатися в каталозі пакета Plugin. | -| `openclaw.runtimeExtensions` | Оголошує точки входу вбудованого рантайму JavaScript для встановлених пакетів. Повинні залишатися в каталозі пакета Plugin. | -| `openclaw.setupEntry` | Легка точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef у режимі лише для читання. Повинна залишатися в каталозі пакета Plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує точку входу setup для зібраного JavaScript для встановлених пакетів. Повинна залишатися в каталозі пакета Plugin. | -| `openclaw.channel` | Легкі метадані каталогу каналу, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. | -| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного рантайму каналу. | -| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного рантайму каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих Plugin і зовнішньо опублікованих Plugin. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого Plugin, коли конфігурація недійсна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | +| Поле | Що воно означає | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `openclaw.extensions` | Оголошує точки входу нативного plugin. Вони мають залишатися в межах каталогу пакунка plugin. | +| `openclaw.runtimeExtensions` | Оголошує точки входу runtime збудованого JavaScript для встановлених пакунків. Вони мають залишатися в межах каталогу пакунка plugin. | +| `openclaw.setupEntry` | Полегшена точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Має залишатися в межах каталогу пакунка plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує збудовану JavaScript-точку входу setup для встановлених пакунків. Має залишатися в межах каталогу пакунка plugin. | +| `openclaw.channel` | Легкі метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та тексти вибору. | +| `openclaw.channel.configuredState` | Полегшені метадані перевірки налаштованого стану, які можуть відповісти на питання "чи вже існує налаштування лише через env?" без завантаження повного runtime каналу. | +| `openclaw.channel.persistedAuthState` | Полегшені метадані перевірки збереженого стану автентифікації, які можуть відповісти на питання "чи вже є хоча б один вхід у систему?" без завантаження повного runtime каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих plugin. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із semver-нижньою межею на кшталт `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення та оновлення звіряють із ним отриманий артефакт. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого plugin, коли конфігурація невалідна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного plugin каналу під час запуску. | -Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в онбордингу до завантаження рантайму. `package.json#openclaw.install` повідомляє онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`. +Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в +онбордингу до завантаження runtime. `package.json#openclaw.install` повідомляє +онбордингу, як отримати або ввімкнути цей plugin, коли користувач вибирає один із цих +варіантів. Не переносіть підказки встановлення до `openclaw.plugin.json`. -`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження реєстру маніфестів. Недійсні значення відхиляються; новіші, але дійсні значення пропускають Plugin на старіших хостах. +`openclaw.install.minHostVersion` перевіряється під час встановлення та завантаження +реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають +plugin на старіших хостах. Точне закріплення версії npm уже міститься в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися за принципом fail closed, якщо отриманий артефакт npm більше не відповідає закріпленому релізу. Інтерактивний онбординг для сумісності все ще пропонує npm-специфікації довіреного реєстру, зокрема прості назви пакетів і dist-tag. Діагностика каталогу може розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, із невідповідністю назви пакета та недійсні джерела default choice. Вони також попереджають, коли `expectedIntegrity` присутній, але немає дійсного джерела npm, яке воно може закріпити. +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу +повинні поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення +завершувалися в закритий спосіб, якщо отриманий npm-артефакт більше не відповідає +закріпленому релізу. Інтерактивний онбординг для сумісності все ще пропонує npm-специфікації +довіреного реєстру, зокрема прості назви пакунків і dist-tags. Діагностика каталогу може +розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з +невідповідністю назви пакунка та з невалідним default-choice джерела. Вона також попереджає, коли +`expectedIntegrity` присутній, але немає валідного npm-джерела, до якого його можна прив’язати. Коли `expectedIntegrity` присутній, -потоки встановлення/оновлення застосовують його; коли його пропущено, розв’язання реєстру записується без закріплення цілісності. +потоки встановлення/оновлення застосовують його; коли його пропущено, розв’язання реєстру +фіксується без прив’язки до цілісності. -Plugin каналів мають надавати `openclaw.setupEntry`, коли перевірки статусу, списку каналів або SecretRef мають визначати налаштовані облікові записи без завантаження повного рантайму. Запис setup має надавати метадані каналу разом з безпечними для setup адаптерами конфігурації, статусу та секретів; залишайте мережеві клієнти, слухачі Gateway і рантайми транспорту в основній точці входу extension. +Plugin каналів повинні надавати `openclaw.setupEntry`, коли перевірки статусу, списку каналів +або SecretRef мають визначати налаштовані облікові записи без завантаження повного +runtime. Точка входу setup повинна відкривати метадані каналу разом із безпечними для setup +адаптерами конфігурації, статусу та секретів; мережеві клієнти, слухачі Gateway і +transport runtime слід залишати в основній точці входу розширення. -Поля точки входу рантайму не перевизначають перевірки меж пакета для полів точки входу вихідного коду. -Наприклад, `openclaw.runtimeExtensions` не може зробити придатним до завантаження шлях `openclaw.extensions`, що виходить за межі. +Поля точок входу runtime не перевизначають перевірки меж пакунка для полів +точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити +придатним до завантаження шлях `openclaw.extensions`, що виходить за межі. -`openclaw.install.allowInvalidConfigRecovery` навмисно вузьке. Воно не робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам встановлення відновлюватися після конкретних застарілих збоїв оновлення вбудованого Plugin, наприклад відсутнього шляху вбудованого Plugin або застарілого запису `channels.` для того самого вбудованого Plugin. Непов’язані помилки конфігурації все одно блокують встановлення й спрямовують операторів до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьку дію. Він +не робить довільні зламані конфігурації придатними до встановлення. Наразі він дозволяє потокам встановлення +відновлюватися лише після конкретних застарілих збоїв оновлення вбудованих plugin, як-от +відсутній шлях до вбудованого plugin або застарілий запис `channels.` для цього самого +вбудованого plugin. Не пов’язані помилки конфігурації й далі блокують встановлення і спрямовують операторів +до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакунка для крихітного модуля-перевіряча: ```json { @@ -667,9 +831,13 @@ Plugin каналів мають надавати `openclaw.setupEntry`, кол } ``` -Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева yes/no перевірка автентифікації до завантаження повного Plugin каналу. Цільовий експорт має бути невеликою функцією, яка лише зчитує збережений стан; не маршрутизуйте її через повний barrel рантайму каналу. +Використовуйте це, коли потоки setup, doctor або configured-state потребують дешевого +позитивного/негативного запиту автентифікації до завантаження повного plugin каналу. Цільовий експорт має бути +невеликою функцією, яка читає лише збережений стан; не спрямовуйте його через широкий runtime-barrel +повного каналу. -`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок налаштованого стану лише через env: +`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок +налаштованого стану лише через env: ```json { @@ -685,66 +853,69 @@ Plugin каналів мають надавати `openclaw.setupEntry`, кол } ``` -Використовуйте це, коли канал може визначити configured-state із env або інших невеликих невиконуваних входів. Якщо перевірка потребує повного розв’язання конфігурації або реального рантайму каналу, залишайте цю логіку в hook Plugin `config.hasConfiguredState`. +Використовуйте це, коли канал може визначити налаштований стан за env або іншими невеликими +не-runtime-входами. Якщо перевірка потребує повного розв’язання конфігурації або реального +runtime каналу, залиште цю логіку в hook `config.hasConfiguredState` +plugin. -## Пріоритет виявлення (дублікати id Plugin) +## Пріоритет виявлення (дубльовані id plugin) -OpenClaw виявляє Plugin з кількох коренів (вбудовані, глобально встановлені, робочого простору, явно вибрані в конфігурації шляхи). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються, а не завантажуються поруч із ним. +OpenClaw виявляє plugin з кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлені plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. -Пріоритет, від найвищого до найнижчого: +Пріоритет від найвищого до найнижчого: -1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` -2. **Вбудований** — Plugin, що постачаються з OpenClaw -3. **Глобально встановлений** — Plugin, встановлені в глобальний корінь Plugin OpenClaw -4. **Робочий простір** — Plugin, виявлені відносно поточного робочого простору +1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.` +2. **Вбудований** — plugin, що постачаються з OpenClaw +3. **Глобальне встановлення** — plugin, встановлені в глобальний корінь plugin OpenClaw +4. **Workspace** — plugin, виявлені відносно поточного workspace Наслідки: -- Форк або застаріла копія вбудованого Plugin, що лежить у робочому просторі, не перекриє вбудовану збірку. -- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він виграв за пріоритетом, а не покладайтеся на виявлення в робочому просторі. +- Розгалужена або застаріла копія вбудованого plugin у workspace не перекриє вбудовану збірку. +- Щоб справді перевизначити вбудований plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення у workspace. - Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. -## Вимоги до схеми JSON +## Вимоги до JSON Schema -- **Кожен Plugin повинен постачати схему JSON**, навіть якщо він не приймає конфігурацію. -- Порожня схема є прийнятною (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми перевіряються під час читання/запису конфігурації, а не під час рантайму. +- **Кожен plugin повинен постачати JSON Schema**, навіть якщо він не приймає конфігурацію. +- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми перевіряються під час читання/запису конфігурації, а не під час runtime. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошено - маніфестом Plugin. +- Невідомі ключі `channels.*` — це **помилки**, якщо лише id каналу не оголошено + маніфестом plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - мають посилатися на **такі id Plugin, які можна виявити**. Невідомі id є **помилками**. -- Якщо Plugin встановлено, але він має зламаний або відсутній маніфест чи схему, - валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. -- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається й - у Doctor + журналах показується **попередження**. + повинні посилатися на **виявлювані** id plugin. Невідомі id — це **помилки**. +- Якщо plugin встановлено, але його маніфест або схема пошкоджені чи відсутні, + валідація завершується помилкою, а Doctor повідомляє про помилку plugin. +- Якщо конфігурація plugin існує, але plugin **вимкнений**, конфігурація зберігається і + в Doctor + журналах з’являється **попередження**. Повну схему `plugins.*` див. у [Довіднику з конфігурації](/uk/gateway/configuration). ## Примітки -- Маніфест **обов’язковий для власних Plugin OpenClaw**, зокрема для локальних завантажень із файлової системи. Рантайм усе одно завантажує модуль Plugin окремо; маніфест використовується лише для виявлення + валідації. -- Власні маніфести аналізуються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок приймаються, якщо кінцеве значення все ще є об’єктом. -- Завантажувач маніфесту зчитує лише задокументовані поля маніфесту. Уникайте користувацьких верхньорівневих ключів. -- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує. -- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широкий код рантайму; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час запиту. -- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). -- Метадані змінних середовища (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, перевірка доставки Cron та інші поверхні лише для читання все одно застосовують довіру до Plugin і політику ефективної активації, перш ніж вважати змінну середовища налаштованою. -- Для метаданих wizard рантайму, які потребують коду провайдера, див. [Hooks рантайму провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш Plugin залежить від native modules, задокументуйте кроки збирання та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Маніфест **обов’язковий для нативних Plugin OpenClaw**, зокрема для локальних завантажень із файлової системи. Runtime і далі завантажує модуль plugin окремо; маніфест потрібен лише для виявлення + валідації. +- Нативні маніфести парсяться за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок дозволені, якщо кінцеве значення все ще є об’єктом. +- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня. +- `channels`, `providers`, `cliBackends` і `skills` можна опускати, якщо plugin їх не потребує. +- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час запиту. +- Ексклюзивні типи plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). +- Метадані env vars (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, перевірка доставки Cron та інші поверхні лише для читання й далі застосовують політику довіри до plugin та ефективної активації перед тим, як вважати env var налаштованою. +- Метадані runtime wizard, які потребують коду провайдера, див. у [Хуки runtime провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш plugin залежить від нативних модулів, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакунків (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане - - Початок роботи з Plugin. + + Початок роботи з plugin. - + Внутрішня архітектура та модель можливостей. - Довідник SDK Plugin і імпортів підшляхів. + Довідник SDK plugin та імпорти підшляхів. diff --git a/docs/uk/tools/acp-agents.md b/docs/uk/tools/acp-agents.md index 9d7317e8b..53c6c5434 100644 --- a/docs/uk/tools/acp-agents.md +++ b/docs/uk/tools/acp-agents.md @@ -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 `, `/acp permissions `, `/acp timeout ` -5. **Скоригуйте** без заміни контексту — `/acp steer tighten logging and continue` +5. **Скоригуйте курс** без заміни контексту — `/acp steer tighten logging and continue` 6. **Зупиніть** — `/acp cancel` (поточний хід) або `/acp close` (сеанс + прив’язки) -Тригери природною мовою, які мають маршрутизуватися до нативного плагіна Codex: +Тригери природною мовою, які мають спрямовуватися до нативного плагіна Codex, коли +його увімкнено: - «Прив’яжи цей канал Discord до Codex». -- «Під’єднай цей чат до треду Codex ``». -- «Покажи треди Codex, а потім прив’яжи цей». +- «Під’єднай цей чат до гілки Codex ``». +- «Покажи гілки 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::acp:` | `agent::subagent:` | -| Основні команди | `/acp ...` | `/subagents ...` | -| Інструмент запуску | `sessions_spawn` з `runtime:"acp"` | `sessions_spawn` (середовище виконання за замовчуванням) | +| Область | Сеанс ACP | Запуск субагента | +| ------------- | ------------------------------------- | ----------------------------------- | +| Runtime | Плагін бекенда ACP (наприклад acpx) | Нативний runtime субагентів OpenClaw | +| Ключ сеансу | `agent::acp:` | `agent::subagent:` | +| Основні команди | `/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 --bind here` прив’язує поточну розмову до запущеного сеансу ACP — без дочірнього треду, у тій самій поверхні чату. OpenClaw зберігає керування транспортом, автентифікацією, безпекою та доставкою; подальші повідомлення в цій розмові маршрутизуються до того самого сеансу; `/new` і `/reset` скидають сеанс на місці; `/acp close` видаляє прив’язку. +`/acp spawn --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=""` + - Канал або гілка Discord: `match.channel="discord"` + `match.peer.id=""` - Тема форуму Telegram: `match.channel="telegram"` + `match.peer.id=":topic:"` - - DM/груповий чат BlueBubbles: `match.channel="bluebubbles"` + `match.peer.id=""` - Для стабільних прив’язок груп надавайте перевагу `chat_id:*` або `chat_identifier:*`. - - DM/груповий чат iMessage: `match.channel="imessage"` + `match.peer.id=""` - Для стабільних прив’язок груп надавайте перевагу `chat_id:*`. -- `bindings[].agentId` — це ідентифікатор агента OpenClaw, якому належить прив’язка. + - BlueBubbles DM/груповий чат: `match.channel="bluebubbles"` + `match.peer.id=""` + Для стабільних прив’язок груп віддавайте перевагу `chat_id:*` або `chat_identifier:*`. + - iMessage DM/груповий чат: `match.channel="imessage"` + `match.peer.id=""` + Для стабільних прив’язок груп віддавайте перевагу `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-журнал у межах сеансу (`.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-журнал у межах сеансу (`.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 сеансу не знайдено, запуск завершується з чіткою помилкою — без тихого повернення до нового сеансу. - + -Після розгортання 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-потоку є окремими, багатшими інтеграційними перевірками. @@ -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 ` - `--label ` -Див. [Слеш-команди](/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:` | | `/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 ` відображається на ключ конфігурації runtime `model`. Для Codex ACP OpenClaw нормалізує `openai-codex/` до ідентифікатора моделі адаптера та відображає суфікси міркування через slash, такі як `openai-codex/gpt-5.4/high`, на Codex ACP `reasoning_effort`. Для інших harness керування моделлю залежить від підтримки адаптером ACP `models` і `session/set_model`. +- `/acp model ` відображається на ключ конфігурації runtime `model`. Для Codex ACP OpenClaw нормалізує `openai-codex/` до id моделі адаптера та відображає суфікси міркування через слеш, такі як `openai-codex/gpt-5.4/high`, на Codex ACP `reasoning_effort`. Для інших середовищ керування моделлю залежить від підтримки адаптером ACP `models` і `session/set_model`. - `/acp set thinking ` відображається на ключ конфігурації runtime `thinking`. Для Codex ACP OpenClaw надсилає відповідний `reasoning_effort`, якщо адаптер це підтримує. - `/acp permissions ` відображається на ключ конфігурації runtime `approval_policy`. - `/acp timeout ` відображається на ключ конфігурації runtime `timeout`. -- `/acp cwd ` безпосередньо оновлює перевизначення cwd runtime. +- `/acp cwd ` напряму оновлює перевизначення `cwd` runtime. - `/acp set ` — це загальний шлях. - - Особливий випадок: `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 "" 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 .` | Адаптер не підтримує ACP-прив’язку до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, якщо це підтримується, налаштуйте верхньорівневі `bindings[]` або перейдіть до підтримуваного каналу. | -| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом треду. | Перейдіть до цільового треду або використовуйте `--thread auto`/`off`. | -| `Only can rebind this channel/conversation/thread.` | Активна ціль прив’язки належить іншому користувачеві. | Переприв’яжіть як власник або використайте іншу розмову чи тред. | -| `Thread bindings are unavailable for .` | Адаптер не підтримує прив’язку до тредів. | Використовуйте `--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 "" 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 .` | Адаптер не підтримує ACP-прив’язку до поточної розмови. | Використовуйте `/acp spawn ... --thread ...`, де це підтримується, налаштуйте `bindings[]` верхнього рівня або перейдіть до підтримуваного каналу. | +| `--thread here requires running /acp spawn inside an active ... thread` | `--thread here` використано поза контекстом гілки. | Перейдіть до цільової гілки або використайте `--thread auto`/`off`. | +| `Only can rebind this channel/conversation/thread.` | Інший користувач володіє активною ціллю прив’язки. | Переприв’яжіть як власник або використайте іншу розмову чи гілку. | +| `Thread bindings are unavailable for .` | Адаптер не підтримує прив’язку до гілок. | Використайте `--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) diff --git a/docs/uk/tools/plugin.md b/docs/uk/tools/plugin.md index f1e0474e3..fba46f50d 100644 --- a/docs/uk/tools/plugin.md +++ b/docs/uk/tools/plugin.md @@ -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: ``` - + ```bash # З npm openclaw plugins install @openclaw/voice-call @@ -52,7 +48,7 @@ x-i18n: -Якщо ви віддаєте перевагу керуванню безпосередньо в чаті, увімкніть `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:` або специфікація пакета без префікса (спочатку ClawHub, потім резервний перехід на npm). +Шлях встановлення використовує той самий механізм розв’язання, що й CLI: локальний шлях/архів, явний +`clawhub:` або специфікація пакета без префікса (спочатку ClawHub, потім резервний варіант через npm). -Якщо конфігурація некоректна, встановлення зазвичай безпечно завершується відмовою і пропонує -скористатися `openclaw doctor --fix`. Єдиний виняток для відновлення — це вузький шлях -перевстановлення вбудованого плагіна для плагінів, які підтримують +Якщо конфігурація невалідна, встановлення зазвичай безпечно завершується відмовою й спрямовує вас до +`openclaw doctor --fix`. Єдиний виняток для відновлення — вузький шлях перевстановлення вбудованого Plugin +для Plugins, які підтримують `openclaw.install.allowInvalidConfigRecovery`. -Пакетні встановлення OpenClaw не встановлюють завчасно все дерево залежностей середовища виконання кожного вбудованого плагіна. -Коли вбудований плагін, що належить OpenClaw, активний через -конфігурацію плагіна, застарілу конфігурацію каналу або маніфест, увімкнений за замовчуванням, -під час запуску відновлюються лише оголошені цим плагіном залежності середовища виконання перед його імпортом. +Пакетні інсталяції OpenClaw не встановлюють наперед усе дерево залежностей середовища виконання кожного вбудованого Plugin. +Коли вбудований Plugin від OpenClaw активний через конфігурацію Plugin, застарілу конфігурацію каналу або маніфест +із увімкненням за замовчуванням, під час запуску відновлюються лише оголошені залежності середовища виконання цього Plugin перед його імпортом. Явне вимкнення все одно має пріоритет: `plugins.entries..enabled: false`, `plugins.deny`, `plugins.enabled: false` і `channels..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` - + - `memory-core` — вбудований пошук у пам’яті (типово через `plugins.slots.memory`) - - `memory-lancedb` — довгострокова пам’ять із встановленням за потреби та автоматичним пригадуванням/захопленням (встановіть `plugins.slots.memory = "memory-lancedb"`) + - `memory-lancedb` — довготривала пам’ять із встановленням за потреби та автоматичним пригадуванням/захопленням (установіть `plugins.slots.memory = "memory-lancedb"`) @@ -126,12 +121,12 @@ OpenClaw розпізнає два формати плагінів: - - `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 (вимкнений за замовчуванням) -Шукаєте сторонні плагіни? Див. [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.\` | Перемикачі та конфігурація для окремого плагіна | +| `entries.\` | Перемикачі та конфігурація для окремого 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. - - - **Disabled**: плагін існує, але правила увімкнення його вимкнули. Конфігурація зберігається. - - **Missing**: конфігурація посилається на ідентифікатор плагіна, який не було знайдено під час виявлення. - - **Invalid**: плагін існує, але його конфігурація не відповідає оголошеній схемі. + + - **Disabled**: Plugin існує, але правила ввімкнення його вимкнули. Конфігурація зберігається. + - **Missing**: конфігурація посилається на ідентифікатор Plugin, який не знайдено під час виявлення. + - **Invalid**: Plugin існує, але його конфігурація не відповідає оголошеній схемі. -## Виявлення та пріоритет +## Виявлення та пріоритетність -OpenClaw сканує плагіни в такому порядку (перше збіг — пріоритетний): +OpenClaw сканує Plugins у такому порядку (перше збігання має пріоритет): - + `plugins.load.paths` — явні шляхи до файлів або каталогів. - + `\/.openclaw//*.ts` і `\/.openclaw//*/index.ts`. - + `~/.openclaw//*.ts` і `~/.openclaw//*/index.ts`. - - Постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (постачальники моделей, мовлення). + + Постачаються з OpenClaw. Багато з них увімкнені за замовчуванням (постачальники моделей, мовлення). Інші потребують явного ввімкнення. -### Правила увімкнення +### Правила ввімкнення -- `plugins.enabled: false` вимикає всі плагіни +- `plugins.enabled: false` вимикає всі Plugins - `plugins.deny` завжди має пріоритет над allow -- `plugins.entries.\.enabled: false` вимикає цей плагін -- Плагіни з робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути) -- Вбудовані плагіни дотримуються вбудованого набору, увімкненого за замовчуванням, якщо його не перевизначено -- Ексклюзивні слоти можуть примусово ввімкнути вибраний для цього слота плагін -- Деякі вбудовані плагіни з режимом opt-in вмикаються автоматично, коли конфігурація вказує поверхню, що належить плагіну, - наприклад посилання на модель постачальника, конфігурацію каналу або - runtime середовища -- Маршрути Codex родини OpenAI зберігають окремі межі плагінів: - `openai-codex/*` належить плагіну OpenAI, тоді як вбудований плагін - app-server Codex вибирається через `embeddedHarness.runtime: "codex"` або застарілі - посилання на моделі `codex/*` +- `plugins.entries.\.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 --json`, щоб підтвердити реєстрації хуків і - діагностику. Для невбудованих розмовних хуків, таких як `llm_input`, - `llm_output` і `agent_end`, потрібен +- Використайте `openclaw plugins inspect --json`, щоб підтвердити реєстрацію хуків і + діагностику. Невбудовані хуки діалогу, такі як `llm_input`, + `llm_output` і `agent_end`, потребують `plugins.entries..hooks.allowConversationAccess=true`. -- Для перемикання моделей надавайте перевагу `before_model_resolve`. Цей хук виконується до - розв’язання моделі для ходів агента; `llm_output` виконується лише після того, як спроба - моделі створить відповідь асистента. +- Для перемикання моделей віддавайте перевагу `before_model_resolve`. Він виконується до + розв’язання моделі для ходів агента; `llm_output` виконується лише після того, як спроба моделі + створює вивід помічника. - Щоб підтвердити фактичну модель сеансу, використовуйте `openclaw sessions` або поверхні сеансу/стану Gateway, а під час налагодження навантажень постачальника запускайте Gateway з `--raw-stream --raw-stream-path `. -## Слоти плагінів (ексклюзивні категорії) +### Дублювання володіння каналом або інструментом -Деякі категорії є ексклюзивними (одночасно може бути активним лише один): +Симптоми: + +- `channel already registered: ()` +- `channel setup already registered: ()` +- `plugin tool name conflict (): ` + +Це означає, що більш ніж один увімкнений Plugin намагається володіти тим самим каналом, +потоком налаштування або назвою інструмента. Найпоширеніша причина — зовнішній Plugin каналу, +установлений поруч із вбудованим Plugin, який тепер надає той самий ідентифікатор каналу. + +Кроки налагодження: + +- Запустіть `openclaw plugins list --enabled --verbose`, щоб побачити кожен увімкнений Plugin + і його походження. +- Запустіть `openclaw plugins inspect --json` для кожного підозрюваного Plugin і + порівняйте `channels`, `channelConfigs`, `tools` і діагностику. +- Запустіть `openclaw plugins registry --refresh` після встановлення або видалення + пакетів Plugin, щоб збережені метадані відображали поточне встановлення. +- Перезапустіть Gateway після змін установлення, реєстру або конфігурації. + +Варіанти виправлення: + +- Якщо один Plugin навмисно замінює інший для того самого ідентифікатора каналу, + бажаний Plugin має оголошувати `channelConfigs..preferOver` із + ідентифікатором Plugin нижчого пріоритету. Див. [/plugins/manifest#replacing-another-channel-plugin](/uk/plugins/manifest#replacing-another-channel-plugin). +- Якщо дублювання випадкове, вимкніть одну зі сторін через + `plugins.entries..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 # докладна інформація -openclaw plugins inspect --json # машиночитаний формат -openclaw plugins inspect --all # таблиця для всіх -openclaw plugins info # псевдонім для inspect +openclaw plugins list --enabled # лише увімкнені Plugins +openclaw plugins list --verbose # детальні рядки для кожного Plugin +openclaw plugins list --json # машиночитний список +openclaw plugins inspect # детальна інформація +openclaw plugins inspect --json # машиночитний формат +openclaw plugins inspect --all # таблиця для всього набору +openclaw plugins info # псевдонім inspect openclaw plugins doctor # діагностика -openclaw plugins registry # перевірка збереженого стану реєстру +openclaw plugins registry # перегляд збереженого стану реєстру openclaw plugins registry --refresh # перебудувати збережений реєстр -openclaw doctor --fix # виправити стан міграції реєстру/журналу +openclaw doctor --fix # відновити стан реєстру Plugin openclaw plugins install # встановити (спочатку ClawHub, потім npm) openclaw plugins install clawhub: # встановити лише з ClawHub openclaw plugins install --force # перезаписати наявне встановлення openclaw plugins install # встановити з локального шляху -openclaw plugins install -l # підключити (без копіювання) для розробки +openclaw plugins install -l # прив’язати (без копіювання) для розробки openclaw plugins install --marketplace openclaw plugins install --marketplace https://github.com// -openclaw plugins install --pin # зберегти точну розв’язану npm-специфікацію +openclaw plugins install --pin # записати точну розв’язану специфікацію npm openclaw plugins install --dangerously-force-unsafe-install -openclaw plugins update # оновити один плагін +openclaw plugins update # оновити один Plugin openclaw plugins update --dangerously-force-unsafe-install openclaw plugins update --all # оновити всі -openclaw plugins uninstall # видалити записи конфігурації та журналу встановлення +openclaw plugins uninstall # видалити конфігурацію та записи індексу Plugin openclaw plugins uninstall --keep-files openclaw plugins marketplace list openclaw plugins marketplace list --json @@ -296,69 +323,67 @@ openclaw plugins enable openclaw plugins disable ``` -Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад, -вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований browser- -плагін). Інші вбудовані плагіни все ще потребують `openclaw plugins enable `. +Вбудовані Plugins постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад, +вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований browser +Plugin). Інші вбудовані Plugins усе ще потрібно вмикати через `openclaw plugins enable `. -`--force` перезаписує наявний встановлений плагін або набір хуків на місці. Для -звичайних оновлень відстежуваних npm-плагінів використовуйте -`openclaw plugins update `. Цей параметр не підтримується з `--link`, який повторно використовує вихідний шлях +`--force` перезаписує наявний встановлений Plugin або набір hooks на місці. Використовуйте +`openclaw plugins update ` для звичайних оновлень відстежуваних 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 ` застосовується до відстежуваних встановлень. Передавання -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 ` також повідомляє про виявлені можливості пакета, а також -підтримувані або непідтримувані записи серверів MCP і LSP для плагінів на основі пакетів. +`openclaw plugins inspect ` також повідомляє про виявлені можливості 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) — сторонні списки diff --git a/docs/uk/tools/subagents.md b/docs/uk/tools/subagents.md index bb83f4db0..14545ea51 100644 --- a/docs/uk/tools/subagents.md +++ b/docs/uk/tools/subagents.md @@ -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::subagent:`) і після завершення **повідомляють** про свій результат назад у чат-канал запитувача. Кожне виконання підагента відстежується як [фонове завдання](/uk/automation/tasks). +Sub-agents — це фонові виконання agent, породжені з наявного виконання agent. Вони працюють у власній сесії (`agent::subagent:`) і після завершення **повідомляють** про свій результат назад у канал чату запитувача. Кожне виконання sub-agent відстежується як [фонове завдання](/uk/automation/tasks). -## Команда зі скісною рискою +## Slash-команда -Використовуйте `/subagents`, щоб переглядати або керувати виконаннями підагентів для **поточної сесії**: +Використовуйте `/subagents`, щоб переглядати або керувати виконаннями sub-agent для **поточної сесії**: - `/subagents list` - `/subagents kill ` @@ -30,7 +30,7 @@ x-i18n: Елементи керування прив’язкою до потоку: -Ці команди працюють у каналах, що підтримують постійні прив’язки до потоку. Див. **Канали з підтримкою потоків** нижче. +Ці команди працюють у каналах, які підтримують постійні прив’язки до потоку. Див. **Канали з підтримкою потоків** нижче. - `/focus ` - `/unfocus` @@ -38,114 +38,114 @@ x-i18n: - `/session idle ` - `/session max-age ` -`/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 ` прив’язує поточний потік (або створює новий) до цілі підагента/сесії. +- `/focus ` прив’язує поточний потік (або створює його) до цільової сесії/sub-agent. - `/unfocus` видаляє прив’язку для поточного прив’язаного потоку. - `/agents` перелічує активні виконання та стан прив’язки (`thread:` або `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.` (у тій самій теці). -- `cleanup: "delete"` архівує відразу після повідомлення (транскрипт усе одно зберігається через перейменування). -- Автоархівація є best-effort; заплановані таймери втрачаються, якщо Gateway перезапускається. +- Сесії Sub-agent автоматично архівуються після `agents.defaults.subagents.archiveAfterMinutes` (типово: 60). +- Архівація використовує `sessions.delete` і перейменовує транскрипт у `*.deleted.` (та сама папка). +- `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::main` | Основний агент | Завжди | -| 1 | `agent::subagent:` | Підагент (оркестратор, якщо дозволено глибину 2) | Лише якщо `maxSpawnDepth >= 2` | -| 2 | `agent::subagent::subagent:` | Підагент другого рівня (кінцевий виконавець) | Ніколи | +| Глибина | Форма ключа сесії | Роль | Може породжувати? | +| ------- | ------------------------------------------- | --------------------------------------------- | ---------------------------- | +| 0 | `agent::main` | Основний agent | Завжди | +| 1 | `agent::subagent:` | Sub-agent (оркестратор, якщо дозволено depth 2) | Лише якщо `maxSpawnDepth >= 2` | +| 2 | `agent::subagent::subagent:` | 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 ` зупиняє конкретного підагента та каскадно зупиняє його дочірніх агентів. -- `/subagents kill all` зупиняє всіх підагентів для запитувача та виконує каскадну зупинку. +- `/stop` в основному чаті зупиняє всіх agent depth-1 і каскадно зупиняє їхніх дочірніх процесів depth-2. +- `/subagents kill ` зупиняє конкретний sub-agent і каскадно зупиняє його дочірніх процесів. +- `/subagents kill all` зупиняє всіх sub-agents для запитувача і виконує каскадну зупинку. ## Автентифікація -Автентифікація підагента визначається за **id агента**, а не за типом сесії: +Автентифікація sub-agent розв’язується за **ID agent**, а не за типом сесії: -- Ключ сесії підагента має вигляд `agent::subagent:`. -- Сховище автентифікації завантажується з `agentDir` цього агента. -- Профілі автентифікації основного агента зливаються як **резервні**; профілі агента мають пріоритет над профілями main у разі конфліктів. +- Ключ сесії sub-agent — `agent::subagent:`. +- Сховище автентифікації завантажується з `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 видаляються - блоки каркаса `` / `` видаляються - - текстові XML-блоки корисного навантаження викликів інструментів, такі як `...`, + - блоки plain-text XML payload викликів інструментів, такі як `...`, `...`, `...` і - `...`, видаляються, включно з усіченими - корисними навантаженнями, які так і не закриваються належним чином - - знижений до тексту каркас викликів/результатів інструментів і маркери історичного контексту видаляються - - витеклі токени керування моделлю, такі як `<|assistant|>`, інші ASCII-токени - `<|...|>` і повноширинні варіанти `<｜...｜>`, видаляються - - неправильний XML викликів інструментів MiniMax видаляється + `...`, видаляються, включно з обрізаними + 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 ` зупиняє конкретного підагента та каскадно зупиняє його дочірніх агентів. +- Надсилання `/stop` у чаті запитувача перериває сесію запитувача і зупиняє всі активні виконання sub-agent, породжені з неї, з каскадним поширенням на вкладених дочірніх процесів. +- `/subagents kill ` зупиняє конкретний 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)