diff --git a/docs/uk/cli/plugins.md b/docs/uk/cli/plugins.md index 515cff7a3..8f5be0f01 100644 --- a/docs/uk/cli/plugins.md +++ b/docs/uk/cli/plugins.md @@ -1,27 +1,27 @@ --- read_when: - - Ви хочете встановити або керувати плагінами Gateway чи сумісними пакетами + - Ви хочете встановити або керувати плагінами Gateway чи сумісними наборами пакунків - Ви хочете налагодити збої завантаження плагінів summary: Довідник CLI для `openclaw plugins` (`list`, `install`, `marketplace`, `uninstall`, `enable`/`disable`, `doctor`) -title: Плагіни +title: Plugins x-i18n: - generated_at: "2026-04-25T17:39:21Z" + generated_at: "2026-04-25T18:41:32Z" model: gpt-5.4 provider: openai - source_hash: 2ae8f71873fb90dc7acde2ac522228cc60603ba34322e5b6d031e8de7545684e + source_hash: 9536d2df20b9284855878dbfc649d7905d6440e9fe8d8d00e63b97c4e428194d source_path: cli/plugins.md workflow: 15 --- # `openclaw plugins` -Керуйте плагінами Gateway, наборами хуків і сумісними пакетами. +Керуйте плагінами Gateway, наборами хуків і сумісними наборами пакунків. Пов’язано: -- Система плагінів: [Плагіни](/uk/tools/plugin) -- Сумісність пакетів: [Пакети плагінів](/uk/plugins/bundles) -- Маніфест плагіна + схема: [Маніфест плагіна](/uk/plugins/manifest) +- Система Plugin: [Plugins](/uk/tools/plugin) +- Сумісність наборів пакунків: [Набори пакунків Plugin](/uk/plugins/bundles) +- Маніфест Plugin + схема: [Маніфест Plugin](/uk/plugins/manifest) - Посилення безпеки: [Безпека](/uk/gateway/security) ## Команди @@ -48,17 +48,23 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Вбудовані плагіни постачаються разом з OpenClaw. Деякі з них увімкнені за замовчуванням (наприклад, вбудовані провайдери моделей, вбудовані провайдери мовлення та вбудований браузерний Plugin); інші потребують `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`. У докладному виводі list/info також показується підтип пакета (`codex`, `claude` або `cursor`), а також виявлені можливості пакета. +`plugins list` показує `Format: openclaw` або `Format: bundle`. Докладний вивід list/info +також показує підтип набору пакунків (`codex`, `claude` або `cursor`) плюс виявлені +можливості набору пакунків. ### Встановлення ```bash openclaw plugins install # спочатку ClawHub, потім npm -openclaw plugins install clawhub: # тільки ClawHub +openclaw plugins install clawhub: # лише ClawHub openclaw plugins install --force # перезаписати наявне встановлення openclaw plugins install --pin # закріпити версію openclaw plugins install --dangerously-force-unsafe-install @@ -68,31 +74,58 @@ 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 із сусідніми перевизначеннями завершуються безпечною відмовою замість сплощення. Підтримувані форми див. у [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`. +Якщо конфігурація невалідна, `plugins install` зазвичай аварійно зупиняється та пропонує +спочатку виконати `openclaw doctor --fix`. Єдиний задокументований виняток — вузький +шлях відновлення для вбудованого плагіна для плагінів, які явно погоджуються на +`openclaw.install.allowInvalidConfigRecovery`. -Єдиний задокументований виняток — вузький шлях відновлення для вбудованих плагінів, які явно вмикають `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. -`--pin` застосовується лише до встановлень npm. Він не підтримується з `--marketplace`, тому що встановлення з marketplace зберігають метадані джерела marketplace, а не специфікацію npm. +`--dangerously-force-unsafe-install` — це аварійний параметр для хибнопозитивних спрацьовувань +у вбудованому сканері небезпечного коду. Він дозволяє продовжити встановлення навіть +коли вбудований сканер повідомляє про результати рівня `critical`, але **не** +обходить блокування політики хука плагіна `before_install` і **не** +обходить збої сканування. -`--dangerously-force-unsafe-install` — це аварійний параметр для хибнопозитивних спрацювань вбудованого сканера небезпечного коду. Він дозволяє продовжити встановлення навіть тоді, коли вбудований сканер повідомляє про результати рівня `critical`, але він **не** обходить блокування політики хуків `before_install` плагіна і **не** обходить збої сканування. +Цей прапорець CLI застосовується до потоків встановлення/оновлення плагінів. Встановлення +залежностей Skills через Gateway використовують відповідне перевизначення запиту +`dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` лишається окремим +потоком завантаження/встановлення навичок ClawHub. -Цей прапорець CLI застосовується до потоків встановлення/оновлення плагінів. Встановлення залежностей Skills через Gateway використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення навичок ClawHub. +`plugins install` також є поверхнею встановлення для наборів хуків, які надають +`openclaw.hooks` у `package.json`. Використовуйте `openclaw hooks` для відфільтрованої +видимості хуків і ввімкнення окремих хуків, а не для встановлення пакунків. -`plugins install` також є поверхнею встановлення для наборів хуків, які оголошують `openclaw.hooks` у `package.json`. Використовуйте `openclaw hooks` для відфільтрованої видимості хуків і вмикання окремих хуків, а не для встановлення пакета. +Специфікації npm є **лише реєстровими** (назва пакунка + необов’язкова **точна версія** або +**dist-tag**). Специфікації Git/URL/file і діапазони semver відхиляються. Встановлення +залежностей для безпеки запускаються з `--ignore-scripts`. -Специфікації npm є **лише реєстровими** (назва пакета + необов’язкова **точна версія** або **dist-tag**). Специфікації git/URL/файлів і діапазони semver відхиляються. Для безпеки встановлення залежностей виконуються з `--ignore-scripts`. +Специфікації без уточнень і `@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`. @@ -105,15 +138,20 @@ openclaw plugins install clawhub:openclaw-codex-app-server openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3 ``` -Тепер OpenClaw також надає перевагу ClawHub для простих npm-безпечних специфікацій плагінів. Повернення до npm відбувається лише тоді, коли в ClawHub немає цього пакета або версії: +Тепер OpenClaw також віддає перевагу ClawHub для специфікацій плагінів, сумісних із bare npm. Він переходить +до npm лише якщо в ClawHub немає цього пакунка або версії: ```bash openclaw plugins install openclaw-codex-app-server ``` -OpenClaw завантажує архів пакета з ClawHub, перевіряє заявлену сумісність API плагіна / мінімального Gateway, а потім встановлює його через звичайний шлях архіву. Зафіксовані встановлення зберігають метадані джерела ClawHub для подальших оновлень. +OpenClaw завантажує архів пакунка з ClawHub, перевіряє оголошену +сумісність API Plugin / мінімальну сумісність 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 @@ -132,21 +170,30 @@ openclaw plugins install --marketplace ./my-marketplace Джерелами marketplace можуть бути: - назва відомого marketplace Claude з `~/.claude/plugins/known_marketplaces.json` -- локальний корінь marketplace або шлях до `marketplace.json` -- скорочення GitHub-репозиторію, наприклад `owner/repo` +- локальний корінь marketplace або шлях `marketplace.json` +- скорочений запис GitHub-репозиторію, наприклад `owner/repo` - URL GitHub-репозиторію, наприклад `https://github.com/owner/repo` - git URL -Для віддалених marketplace, завантажених із GitHub або git, записи плагінів мають залишатися всередині клонованого репозиторію marketplace. OpenClaw приймає джерела відносних шляхів із цього репозиторію та відхиляє 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`) +- нативні плагіни OpenClaw (`openclaw.plugin.json`) +- сумісні набори пакунків Codex (`.codex-plugin/plugin.json`) +- сумісні набори пакунків Claude (`.claude-plugin/plugin.json` або типовий + макет компонентів Claude) +- сумісні набори пакунків Cursor (`.cursor-plugin/plugin.json`) -Сумісні пакети встановлюються до звичайного кореня плагінів і беруть участь у тому самому потоці list/info/enable/disable. Наразі підтримуються skills пакетів, command-skills Claude, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` / `lspServers`, оголошені в маніфесті, command-skills Cursor та сумісні каталоги хуків Codex; інші виявлені можливості пакетів показуються в diagnostics/info, але ще не підключені до виконання під час роботи. +Сумісні набори пакунків установлюються до звичайного кореня плагінів і беруть участь +у тому самому потоці list/info/enable/disable. Наразі підтримуються bundle skills, Claude +command-skills, типові значення Claude `settings.json`, типові значення Claude `.lsp.json` / +`lspServers`, оголошені в маніфесті, Cursor command-skills і сумісні +каталоги хуків Codex; інші виявлені можливості наборів пакунків +показуються в diagnostics/info, але ще не підключені до виконання під час роботи. ### Список @@ -157,15 +204,29 @@ openclaw plugins list --verbose openclaw plugins list --json ``` -Використовуйте `--enabled`, щоб показати лише увімкнені плагіни. Використовуйте `--verbose`, щоб перейти від табличного подання до рядків із докладною інформацією про кожен плагін із метаданими джерела/походження/версії/активації. Використовуйте `--json` для машинозчитуваного переліку плюс діагностики реєстру. +Використовуйте `--enabled`, щоб показати лише ввімкнені плагіни. Використовуйте `--verbose`, щоб перейти +від табличного подання до докладних рядків для кожного плагіна з метаданими +джерела/походження/версії/активації. Використовуйте `--json` для машиночитаного +інвентарю та diagnostics реєстру. -`plugins list` спочатку читає збережений локальний реєстр плагінів із резервним переходом на похідний режим лише за маніфестом, якщо реєстр відсутній або недійсний. Це корисно для перевірки, чи встановлено плагін, чи він увімкнений і чи видимий для планування холодного запуску, але це не жива перевірка середовища виконання вже запущеного процесу Gateway. Після зміни коду плагіна, стану ввімкнення, політики хуків або `plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж очікувати виконання нового коду `register(api)` або хуків. Для віддалених/контейнерних розгортань переконайтеся, що ви перезапускаєте саме дочірній процес `openclaw gateway run`, а не лише процес-обгортку. +`plugins list` спочатку читає збережений локальний реєстр плагінів, а за його +відсутності або невалідності використовує резервний варіант, похідний лише від маніфесту. Це +зручно для перевірки, чи встановлено плагін, чи він увімкнений і чи видимий для +планування холодного запуску, але це не живе runtime-зондування вже запущеного +процесу Gateway. Після зміни коду плагіна, стану ввімкнення, політики хуків або +`plugins.load.paths` перезапустіть Gateway, який обслуговує канал, перш ніж +очікувати виконання нового коду `register(api)` або хуків. Для віддалених/контейнерних +розгортань переконайтеся, що ви перезапускаєте саме дочірній процес `openclaw gateway run`, +а не лише процес-обгортку. -Для налагодження хуків під час виконання: +Для налагодження runtime-хуків: -- `openclaw plugins inspect --json` показує зареєстровані хуки та diagnostics із проходу inspection із завантаженням модуля. -- `openclaw gateway status --deep --require-rpc` підтверджує досяжний Gateway, підказки щодо сервісу/процесу, шлях до конфігурації та справність RPC. -- Невбудовані хуки розмови (`llm_input`, `llm_output`, `agent_end`) потребують `plugins.entries..hooks.allowConversationAccess=true`. +- `openclaw plugins inspect --json` показує зареєстровані хуки та diagnostics + з проходу інспекції із завантаженням модуля. +- `openclaw gateway status --deep --require-rpc` підтверджує доступний Gateway, + підказки про сервіс/процес, шлях до config і стан RPC. +- Для невбудованих хуків розмови (`llm_input`, `llm_output`, `agent_end`) потрібно + `plugins.entries..hooks.allowConversationAccess=true`. Використовуйте `--link`, щоб уникнути копіювання локального каталогу (додає його до `plugins.load.paths`): @@ -173,9 +234,23 @@ openclaw plugins list --json openclaw plugins install -l ./my-plugin ``` -`--force` не підтримується разом із `--link`, тому що зв’язані встановлення повторно використовують вихідний шлях замість копіювання в керовану ціль встановлення. +`--force` не підтримується з `--link`, оскільки встановлення з посиланням повторно використовують +вихідний шлях замість копіювання до керованої цілі встановлення. -Використовуйте `--pin` під час встановлень npm, щоб зберегти точну розв’язану специфікацію (`name@version`) у `plugins.installs`, залишивши стандартну поведінку без закріплення. +Використовуйте `--pin` для встановлень npm, щоб зберегти розв’язану точну специфікацію (`name@version`) у +керованому журналі встановлень, зберігаючи типову поведінку без закріплення. + +### Журнал встановлень + +Метадані встановлення плагінів — це машинно керований стан, а не конфігурація користувача. Нові +встановлення та оновлення записують його до `plugins/installs.json` у межах активного каталогу +стану OpenClaw. Файл містить попередження не редагувати його вручну та використовується +`openclaw plugins update`, uninstall, diagnostics і холодним реєстром плагінів. + +Застарілі записи `plugins.installs` у `openclaw.json` усе ще можна читати як +застарілий резервний механізм сумісності. Коли шляхи install/update/uninstall +перезаписують стан встановлення плагіна, OpenClaw записує файл журналу та видаляє +`plugins.installs` зі збереженого payload конфігурації. ### Видалення @@ -185,9 +260,12 @@ openclaw plugins uninstall --dry-run openclaw plugins uninstall --keep-files ``` -`uninstall` видаляє записи плагінів з `plugins.entries`, `plugins.installs`, списку дозволених плагінів і, за потреби, зв’язані записи `plugins.load.paths`. Для плагінів активної пам’яті слот пам’яті скидається до `memory-core`. +`uninstall` видаляє записи плагінів із `plugins.entries`, керованого журналу встановлень, +allowlist плагінів і пов’язаних записів `plugins.load.paths`, коли це застосовно. +Для плагінів active memory слот пам’яті скидається до `memory-core`. -За замовчуванням `uninstall` також видаляє каталог встановлення плагіна в активному кореневому каталозі плагінів state-dir. Використовуйте `--keep-files`, щоб зберегти файли на диску. +Типово uninstall також видаляє каталог встановлення плагіна в корені плагінів активного state-dir. Використовуйте +`--keep-files`, щоб зберегти файли на диску. `--keep-config` підтримується як застарілий псевдонім для `--keep-files`. @@ -201,56 +279,64 @@ openclaw plugins update @openclaw/voice-call@beta openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install ``` -Оновлення застосовуються до відстежуваних встановлень у `plugins.installs` і відстежуваних встановлень наборів хуків у `hooks.internal.installs`. +Оновлення застосовуються до відстежуваних встановлень плагінів у керованому журналі встановлень і +відстежуваних встановлень наборів хуків у `hooks.internal.installs`. -Коли ви передаєте id плагіна, OpenClaw повторно використовує записану специфікацію встановлення для цього плагіна. Це означає, що раніше збережені dist-tag, як-от `@beta`, і точні закріплені версії надалі використовуються в наступних запусках `update `. +Коли ви передаєте id плагіна, OpenClaw повторно використовує записану специфікацію встановлення для цього +плагіна. Це означає, що раніше збережені dist-tag, такі як `@beta`, і точні закріплені +версії продовжують використовуватися в наступних запусках `update `. -Для встановлень npm ви також можете передати явну специфікацію пакета npm з dist-tag або точною версією. OpenClaw зіставляє цю назву пакета з відстежуваним записом плагіна, оновлює встановлений плагін і записує нову специфікацію npm для майбутніх оновлень за 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` як -аварійне перевизначення для хибнопозитивних спрацювань вбудованого сканування -небезпечного коду під час оновлень плагінів. Він, як і раніше, не обходить -блокування політики `before_install` плагіна чи блокування через збої -сканування, і застосовується лише до оновлень плагінів, а не до оновлень -наборів хуків. +аварійне перевизначення для хибнопозитивних спрацьовувань вбудованого сканування +небезпечного коду під час оновлення плагінів. Він усе ще не обходить блокування +політики плагіна `before_install` або блокування через збої сканування, і +застосовується лише до оновлень плагінів, а не до оновлень наборів хуків. -### Inspect +### Інспекція ```bash openclaw plugins inspect openclaw plugins inspect --json ``` -Глибока інтроспекція для одного плагіна. Показує ідентичність, статус -завантаження, джерело, зареєстровані можливості, хуки, інструменти, команди, -сервіси, методи gateway, HTTP-маршрути, прапорці політик, diagnostics, -метадані встановлення, можливості пакета, а також будь-яку виявлену підтримку -серверів MCP або LSP. +Глибока інспекція для одного плагіна. Показує ідентичність, стан завантаження, джерело, +зареєстровані можливості, хуки, інструменти, команди, сервіси, методи gateway, +HTTP-маршрути, прапорці політики, diagnostics, метадані встановлення, можливості набору пакунків, +а також будь-яку виявлену підтримку MCP або LSP-сервера. -Кожен плагін класифікується за тим, що саме він реєструє під час виконання: +Кожен плагін класифікується за тим, що він фактично реєструє під час роботи: -- **plain-capability** — один тип можливостей (наприклад, плагін лише з одним провайдером) +- **plain-capability** — один тип можливостей (наприклад, плагін лише для провайдера) - **hybrid-capability** — кілька типів можливостей (наприклад, текст + мовлення + зображення) - **hook-only** — лише хуки, без можливостей або поверхонь - **non-capability** — інструменти/команди/сервіси, але без можливостей -Докладніше про модель можливостей див. у [Форми плагінів](/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` виводить загальнофлотську таблицю з колонками shape, kinds можливостей, +повідомленнями про сумісність, можливостями наборів пакунків і підсумком хуків. `info` — це псевдонім для `inspect`. @@ -260,15 +346,15 @@ compatibility notices, bundle capabilities і hook summary. openclaw plugins doctor ``` -`doctor` повідомляє про помилки завантаження плагінів, diagnostics -маніфесту/виявлення та повідомлення про сумісність. Коли все чисто, він виводить `No plugin issues +`doctor` повідомляє про помилки завантаження плагінів, diagnostics виявлення/маніфестів і +повідомлення про сумісність. Якщо все чисто, він виводить `No plugin issues detected.` -Для збоїв форми модуля, як-от відсутні експорти `register`/`activate`, повторно -запустіть із `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб включити стислий підсумок -форми експорту до діагностичного виводу. +Для збоїв форми модуля, таких як відсутні експорти `register`/`activate`, повторно запустіть +із `OPENCLAW_PLUGIN_LOAD_DEBUG=1`, щоб включити компактний підсумок форми експортів у +діагностичний вивід. -### Registry +### Реєстр ```bash openclaw plugins registry @@ -276,21 +362,20 @@ openclaw plugins registry --refresh openclaw plugins registry --json ``` -Локальний реєстр плагінів — це збережена холодна модель читання OpenClaw для -ідентичності встановлених плагінів, стану ввімкнення, метаданих джерела та -власності внесків. Звичайний запуск, пошук власника провайдера, класифікація -налаштування каналу та інвентаризація плагінів можуть читати його без імпорту -модулів середовища виконання плагінів. +Локальний реєстр плагінів — це збережена модель холодного читання OpenClaw для встановленої +ідентичності плагінів, стану ввімкнення, метаданих джерела та належності внесків. +Звичайний запуск, пошук власника провайдера, класифікація налаштування каналу та +інвентаризація плагінів можуть читати його без імпорту модулів runtime плагінів. -Використовуйте `plugins registry`, щоб перевірити, чи збережений реєстр -наявний, актуальний чи застарілий. Використовуйте `--refresh`, щоб перебудувати -його з довговічного журналу встановлень, політики конфігурації та метаданих -маніфесту/пакета. Це шлях відновлення, а не шлях активації під час виконання. +Використовуйте `plugins registry`, щоб перевірити, чи наявний збережений реєстр, +чи він актуальний, чи застарілий. Використовуйте `--refresh`, щоб перебудувати його з +довговічного журналу встановлень, політики config і метаданих маніфесту/пакунка. Це +шлях відновлення, а не шлях runtime-активації. `OPENCLAW_DISABLE_PERSISTED_PLUGIN_REGISTRY=1` — це застарілий аварійний -перемикач сумісності для збоїв читання реєстру. Надавайте перевагу `plugins registry +перемикач сумісності для збоїв читання реєстру. Віддавайте перевагу `plugins registry --refresh` або `openclaw doctor --fix`; резервний варіант через env призначений лише для -аварійного відновлення запуску, поки розгортається міграція. +аварійного відновлення запуску, поки триває розгортання міграції. ### Marketplace @@ -299,7 +384,7 @@ openclaw plugins marketplace list openclaw plugins marketplace list --json ``` -Список marketplace приймає локальний шлях до marketplace, шлях до `marketplace.json`, +Список marketplace приймає локальний шлях marketplace, шлях `marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL GitHub-репозиторію або git URL. `--json` виводить мітку розв’язаного джерела, а також розібраний маніфест marketplace і записи плагінів. diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index eeb76d8de..8c06519a7 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -5,62 +5,62 @@ read_when: summary: Довідник із конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем title: Довідник із конфігурації x-i18n: - generated_at: "2026-04-25T18:14:13Z" + generated_at: "2026-04-25T18:41:25Z" model: gpt-5.4 provider: openai - source_hash: 0b7e904455845a9559a0a8ed67b217597819f4a8abc38e6c8ecb69b6481528e8 + source_hash: 20618b101b5c287343e0f97cd2536f42950d855ba8a8ca5f6f5b5eb10cba749d 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 і надає посилання, коли підсистема має власний глибший довідник. Каталоги команд і детальні параметри пам’яті/QMD, що належать каналам і плагінам, винесені на окремі сторінки, а не розміщені тут. Джерело істини в коді: -- `openclaw config schema` виводить актуальну JSON Schema, що використовується для валідації та Control UI, із об’єднаними метаданими bundled/plugin/channel, коли вони доступні -- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів детального перегляду -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють baseline hash документації конфігурації щодо поточної поверхні схеми +- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, із об’єднаними метаданими bundled/plugin/channel, коли вони доступні +- `config.schema.lookup` повертає один вузол схеми, прив’язаний до шляху, для інструментів деталізованого перегляду +- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш документації конфігурації щодо поточної поверхні схеми Окремі детальні довідники: - [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-власника для специфічних поверхонь команд каналів +- [Slash commands](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд +- сторінки відповідних каналів/плагінів для специфічних для каналу поверхонь команд -Формат конфігурації — **JSON5** (дозволено коментарі та кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано. +Формат конфігурації — **JSON5** (дозволені коментарі та кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. --- ## Канали -Ключі конфігурації для кожного каналу перенесено на окрему сторінку — див. +Ключі конфігурації окремих каналів перенесено на окрему сторінку — див. [Configuration — channels](/uk/gateway/config-channels) для `channels.*`, зокрема Slack, Discord, Telegram, WhatsApp, Matrix, iMessage та інших -bundled каналів (автентифікація, контроль доступу, кілька облікових записів, обмеження згадувань). +bundled каналів (автентифікація, контроль доступу, кілька облікових записів, обмеження згадок). -## Значення агентів за замовчуванням, multi-agent, сесії та повідомлення +## Значення агентів за замовчуванням, мультиагентність, сесії та повідомлення Перенесено на окрему сторінку — див. [Configuration — agents](/uk/gateway/config-agents) для: - `agents.defaults.*` (робочий простір, модель, thinking, heartbeat, пам’ять, медіа, skills, sandbox) - `multiAgent.*` (маршрутизація та прив’язки multi-agent) -- `session.*` (життєвий цикл сесії, compaction, обрізання) +- `session.*` (життєвий цикл сесії, compaction, очищення) - `messages.*` (доставка повідомлень, TTS, рендеринг markdown) - `talk.*` (режим Talk) - - `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS і Android, 900 ms на iOS`) + - `talk.silenceTimeoutMs`: якщо не задано, Talk зберігає стандартне для платформи вікно паузи перед надсиланням транскрипту (`700 ms на macOS та Android, 900 ms на iOS`) -## Інструменти та власні провайдери +## Інструменти та користувацькі провайдери -Політика інструментів, експериментальні перемикачі, конфігурація інструментів із підтримкою провайдерів і налаштування власних -провайдерів / base-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` керують цим блоком без підключення до цільового сервера під час редагування конфігурації. @@ -68,7 +68,7 @@ bundled каналів (автентифікація, контроль дост ```json5 { mcp: { - // Необов’язково. За замовчуванням: 600000 ms (10 хвилин). Установіть 0, щоб вимкнути виселення під час простою. + // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction. sessionIdleTtlMs: 600000, servers: { docs: { @@ -87,17 +87,17 @@ bundled каналів (автентифікація, контроль дост } ``` -- `mcp.servers`: іменовані визначення stdio- або віддалених MCP-серверів для середовищ виконання, які - надають налаштовані MCP-інструменти. -- `mcp.sessionIdleTtlMs`: TTL простою для bundled MCP runtime, прив’язаних до сесії. - Одноразові вбудовані запуски запитують очищення після завершення виконання; цей TTL є резервним механізмом для +- `mcp.servers`: іменовані визначення stdio або віддалених MCP серверів для середовищ виконання, які + надають налаштовані MCP інструменти. +- `mcp.sessionIdleTtlMs`: TTL простою для session-scoped bundled MCP runtime. + Одноразові вбудовані запуски запитують очищення після завершення запуску; цей TTL є страховкою для довготривалих сесій і майбутніх викликів. -- Зміни в `mcp.*` застосовуються на гарячу через знищення кешованих session MCP runtime. - Наступне виявлення/використання інструмента відтворює їх із нової конфігурації, тому вилучені - записи `mcp.servers` прибираються негайно, а не чекають TTL простою. +- Зміни в `mcp.*` застосовуються гарячим способом через вивільнення кешованих session MCP runtime. + Наступне виявлення/використання інструмента створить їх заново з нової конфігурації, тому видалені + записи `mcp.servers` прибираються негайно, а не чекають завершення idle TTL. Див. [MCP](/uk/cli/mcp#openclaw-as-an-mcp-client-registry) і -[CLI backends](/uk/gateway/cli-backends#bundle-mcp-overlays) щодо поведінки runtime. +[CLI backends](/uk/gateway/cli-backends#bundle-mcp-overlays) щодо поведінки середовища виконання. ## Skills @@ -124,18 +124,18 @@ bundled каналів (автентифікація, контроль дост } ``` -- `allowBundled`: необов’язковий allowlist лише для bundled skills (керовані/workspace skills не зачіпаються). +- `allowBundled`: необов’язковий список дозволу лише для bundled skills (керовані/workspace skills не зачіпаються). - `load.extraDirs`: додаткові спільні корені skills (найнижчий пріоритет). - `install.preferBrew`: якщо `true`, надавати перевагу інсталяторам Homebrew, коли `brew` доступний, перш ніж переходити до інших типів інсталяторів. -- `install.nodeManager`: пріоритет інсталятора Node для специфікацій `metadata.openclaw.install` +- `install.nodeManager`: перевага менеджера Node для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). - `entries..enabled: false` вимикає skill, навіть якщо він bundled/installed. -- `entries..apiKey`: зручне поле для skills, які оголошують основну env-змінну (рядок відкритим текстом або об’єкт SecretRef). +- `entries..apiKey`: зручне поле для skills, які оголошують основну env var (простий рядок або об’єкт SecretRef). --- -## Plugin +## Плагіни ```json5 { @@ -160,42 +160,47 @@ bundled каналів (автентифікація, контроль дост ``` - Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення підтримує нативні Plugin OpenClaw, а також сумісні набори Codex і Claude, зокрема набори Claude стандартного макета без manifest. -- **Зміни конфігурації потребують перезапуску gateway.** -- `allow`: необов’язковий allowlist (завантажуються лише перелічені Plugin). `deny` має пріоритет. -- `plugins.entries..apiKey`: зручне поле API key на рівні Plugin (коли Plugin це підтримує). -- `plugins.entries..env`: карта env-змінних у межах Plugin. -- `plugins.entries..hooks.allowPromptInjection`: якщо `false`, ядро блокує `before_prompt_build` та ігнорує поля legacy `before_agent_start`, що змінюють prompt, зберігаючи legacy `modelOverride` і `providerOverride`. Застосовується до нативних hook Plugin і підтримуваних каталогів hook, наданих наборами. -- `plugins.entries..hooks.allowConversationAccess`: якщо `true`, довірені небандловані Plugin можуть читати необроблений вміст розмови з типізованих hook, таких як `llm_input`, `llm_output` і `agent_end`. -- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремого запуску фонових subagent. -- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли навмисно хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (валідується схемою нативного Plugin OpenClaw, коли вона доступна). -- Налаштування облікових записів/runtime для channel Plugin розміщуються в `channels.` і мають описуватися метаданими `channelConfigs` у manifest Plugin-власника, а не центральним реєстром параметрів OpenClaw. -- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера Firecrawl web-fetch. - - `apiKey`: API key Firecrawl (приймає SecretRef). Резервно використовує `plugins.entries.firecrawl.config.webSearch.apiKey`, legacy `tools.web.fetch.firecrawl.apiKey` або env-змінну `FIRECRAWL_API_KEY`. - - `baseUrl`: базовий URL API Firecrawl (за замовчуванням: `https://api.firecrawl.dev`). - - `onlyMainContent`: витягувати лише основний вміст сторінок (за замовчуванням: `true`). - - `maxAgeMs`: максимальний вік кешу в мілісекундах (за замовчуванням: `172800000` / 2 дні). - - `timeoutSeconds`: тайм-аут запиту на збирання в секундах (за замовчуванням: `60`). +- Виявлення приймає нативні плагіни OpenClaw, а також сумісні бандли Codex і Claude, включно з безманіфестними бандлами Claude стандартної структури. +- **Зміни конфігурації потребують перезапуску Gateway.** +- `allow`: необов’язковий список дозволу (завантажуються лише перелічені плагіни). `deny` має пріоритет. +- `plugins.entries..apiKey`: зручне поле API-ключа на рівні плагіна (коли це підтримується плагіном). +- `plugins.entries..env`: мапа env var у межах плагіна. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, ядро блокує `before_prompt_build` і ігнорує поля, що змінюють prompt, із застарілого `before_agent_start`, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hooks плагінів і підтримуваних каталогів hooks, наданих бандлами. +- `plugins.entries..hooks.allowConversationAccess`: коли `true`, довірені небудовані плагіни можуть читати необроблений вміст розмови з типізованих hooks, таких як `llm_input`, `llm_output` і `agent_end`. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому плагіну запитувати перевизначення `provider` і `model` для окремого запуску фонових subagent-запусків. +- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволу канонічних цілей `provider/model` для довірених перевизначень subagent. Використовуйте `"*"` лише тоді, коли ви свідомо хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений плагіном (перевіряється схемою нативного плагіна OpenClaw, якщо вона доступна). +- Налаштування облікових записів/середовища виконання channel plugin розміщуються в `channels.` і мають описуватися метаданими `channelConfigs` маніфесту відповідного плагіна, а не центральним реєстром параметрів OpenClaw. +- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера web-fetch Firecrawl. + - `apiKey`: API-ключ Firecrawl (приймає SecretRef). Використовує як запасний варіант `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілий `tools.web.fetch.firecrawl.apiKey` або env var `FIRECRAWL_API_KEY`. + - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). + - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`). + - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). + - `timeoutSeconds`: тайм-аут запиту скрапінгу в секундах (типово: `60`). - `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). - - `enabled`: увімкнути провайдер X Search. + - `enabled`: увімкнути провайдера X Search. - `model`: модель Grok для пошуку (наприклад, `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: налаштування dreaming пам’яті. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. - - `enabled`: головний перемикач dreaming (за замовчуванням `false`). - - `frequency`: Cron-ритм для кожного повного циклу dreaming (за замовчуванням `"0 3 * * *"`). - - політика фаз і пороги є деталями реалізації (не є користувацькими ключами конфігурації). -- Повна конфігурація пам’яті розміщена в [Memory configuration reference](/uk/reference/memory-config): +- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Див. [Dreaming](/uk/concepts/dreaming) щодо фаз і порогів. + - `enabled`: головний перемикач dreaming (типово `false`). + - `frequency`: Cron-частота для кожного повного циклу dreaming (`"0 3 * * *"` типово). + - політика фаз і пороги є деталями реалізації (не користувацькими ключами конфігурації). +- Повна конфігурація пам’яті наведена в [Memory configuration reference](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені Claude bundle Plugin також можуть додавати вбудовані значення Pi за замовчуванням із `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як необроблені патчі конфігурації OpenClaw. -- `plugins.slots.memory`: вибрати id активного Plugin пам’яті або `"none"`, щоб вимкнути Plugin пам’яті. -- `plugins.slots.contextEngine`: вибрати id активного Plugin механізму контексту; за замовчуванням `"legacy"`, якщо ви не встановите та не виберете інший механізм. -- `plugins.installs`: метадані інсталяції, керовані CLI, що використовуються `openclaw plugins update`. - - Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI замість ручного редагування. +- Увімкнені бандлові плагіни Claude також можуть додавати вбудовані типові значення Pi із `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як сирі патчі конфігурації OpenClaw. +- `plugins.slots.memory`: вибрати id активного плагіна пам’яті або `"none"`, щоб вимкнути плагіни пам’яті. +- `plugins.slots.contextEngine`: вибрати id активного плагіна рушія контексту; типово `"legacy"`, якщо ви не встановите й не виберете інший рушій. +- `plugins.installs`: застарілий сумісний резервний варіант для застарілих + метаданих встановлення, якими керує CLI. Нові встановлення плагінів записують керований + журнал стану `plugins/installs.json`. + - Застарілі записи містять `source`, `spec`, `sourcePath`, `installPath`, + `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, + `shasum`, `resolvedAt`, `installedAt`. + - Розглядайте `plugins.installs.*` як керований стан; надавайте перевагу командам CLI над + ручним редагуванням. Див. [Plugins](/uk/tools/plugin). @@ -248,46 +253,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` і надалі підтримується як legacy alias. +- У суворому режимі кінцеві точки віддалених CDP-профілів (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок доступності/виявлення. +- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі працюють лише в режимі attach-only (start/stop/reset вимкнено). +- Віддалені профілі працюють лише в режимі attach-only (запуск/зупинка/скидання вимкнено). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. - Використовуйте HTTP(S), коли хочете, щоб OpenClaw виконав виявлення `/json/version`; використовуйте WS(S), - коли ваш провайдер надає вам прямий URL WebSocket DevTools. -- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до перевірки доступності віддаленого та - `attachOnly` CDP, а також до запитів на відкриття вкладок. Керовані профілі - local loopback зберігають локальні значення CDP за замовчуванням. -- Якщо до зовнішньо керованого сервісу CDP можна дістатися через local loopback, установіть - для цього профілю `attachOnly: true`; інакше OpenClaw сприйматиме порт loopback як - локальний керований профіль браузера й може повідомляти про помилки володіння локальним портом. -- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися - до вибраного хоста або через підключений вузол браузера. + Використовуйте HTTP(S), якщо хочете, щоб OpenClaw виявляв `/json/version`; використовуйте WS(S), + коли ваш провайдер надає прямий URL DevTools WebSocket. +- `remoteCdpTimeoutMs` і `remoteCdpHandshakeTimeoutMs` застосовуються до віддалених і + `attachOnly` перевірок доступності CDP, а також до запитів відкриття вкладок. Керовані loopback- + профілі зберігають локальні типові значення CDP. +- Якщо зовнішньо керований сервіс CDP доступний через loopback, установіть для цього + профілю `attachOnly: true`; інакше OpenClaw трактуватиме loopback-порт як + локальний керований профіль браузера і може повідомляти про помилки володіння локальним портом. +- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на + вибраному хості або через підключений browser node. - Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний профіль браузера на базі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання через CSS-селектори, hook завантаження - одного файла, без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без - `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. + дії на основі snapshot/ref замість націлювання через CSS-селектори, хуки + завантаження одного файла, без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без + `responsebody`, експорту PDF, перехоплення завантажень чи пакетних дій. - Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. - Локальні керовані профілі можуть задавати `executablePath`, щоб перевизначити глобальний `browser.executablePath` для цього профілю. Використовуйте це, щоб запускати один профіль у Chrome, а інший — у Brave. - Локальні керовані профілі використовують `browser.localLaunchTimeoutMs` для HTTP-виявлення Chrome CDP - після запуску процесу та `browser.localCdpReadyTimeoutMs` для + після старту процесу та `browser.localCdpReadyTimeoutMs` для готовності websocket CDP після запуску. Збільшуйте їх на повільніших хостах, де Chrome - запускається успішно, але перевірки готовності випереджають завершення запуску. -- Порядок автовиявлення: браузер за замовчуванням, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. + успішно запускається, але перевірки готовності змагаються зі стартом. +- Порядок автовиявлення: типовий браузер, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. - `browser.executablePath` приймає `~` для домашнього каталогу вашої ОС. -- Сервіс керування: лише loopback (порт похідний від `gateway.port`, за замовчуванням `18791`). -- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад, - `--disable-gpu`, налаштування розміру вікна або прапорці налагодження). +- Сервіс керування: лише loopback (порт визначається з `gateway.port`, типово `18791`). +- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад + `--disable-gpu`, розміри вікна або прапорці налагодження). --- @@ -305,8 +310,8 @@ bundled каналів (автентифікація, контроль дост } ``` -- `seamColor`: акцентний колір для chrome UI нативного застосунку (тон бульбашки режиму Talk тощо). -- `assistant`: перевизначення ідентичності для Control UI. Якщо не задано, використовується ідентичність активного агента. +- `seamColor`: колір акценту для chrome інтерфейсу нативного застосунку (відтінок бульбашки Talk Mode тощо). +- `assistant`: перевизначення ідентичності Control UI. Якщо не задано, використовується ідентичність активного агента. --- @@ -381,68 +386,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`. -- **Legacy aliases для 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**: за замовчуванням обов’язкова. Non-loopback bind вимагають auth gateway. На практиці це означає спільний token/password або reverse proxy з контролем ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер початкового налаштування за замовчуванням генерує token. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Під час запуску та у потоках встановлення/відновлення сервісу виникає помилка, якщо налаштовано обидва, а mode не задано. -- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань loopback; цей режим навмисно не пропонується у підказках onboarding. -- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з контролем ідентичності та довіряти заголовкам ідентичності від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **non-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. Цей потік без token передбачає, що хост gateway є довіреним. За замовчуванням `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб auth. Застосовується для кожної IP-адреси клієнта та кожної області auth (shared-secret і device-token відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. - - В асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні хибні спроби від одного клієнта можуть увімкнути обмежувач уже на другому запиті, замість того щоб обидві одночасно пройти як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` за замовчуванням `true`; установіть `false`, якщо ви навмисно хочете, щоб трафік localhost теж підлягав rate limiting (для тестових конфігурацій або суворих proxy-розгортань). -- Спроби WS auth із браузерного джерела завжди обмежуються без винятку для loopback (додатковий захист від brute force localhost через браузер). -- На loopback ці блокування для браузерного джерела ізольовані для кожного нормалізованого значення `Origin`, - тому повторні невдалі спроби з одного localhost origin не блокують автоматично +- `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` усередині контейнера. За використання bridge-мережі Docker (`-p 18789:18789`) трафік надходить на `eth0`, тому gateway недосяжний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` із `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Auth**: типово обов’язкова. Не-loopback bind вимагають auth gateway. На практиці це означає спільний токен/пароль або reverse proxy з урахуванням ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер onboarding типово генерує токен. +- Якщо налаштовано і `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)). Цей режим очікує **не-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`, якщо ви навмисно хочете також обмежувати localhost-трафік (для тестових конфігурацій або суворих proxy-розгортань). +- Спроби auth для WS з походженням браузера завжди обмежуються, причому виняток для loopback вимкнено (захист у глибину від brute-force атак браузера на localhost). +- На loopback ці блокування для браузерного походження ізолюються за нормалізованим значенням `Origin`, + тож повторні невдачі з одного localhost origin не блокують автоматично інший origin. - `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний, потребує auth). -- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень Gateway WebSocket. Обов’язковий, коли клієнти браузера очікуються з non-loopback origin. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає резервний варіант origin через заголовок Host для розгортань, які навмисно покладаються на політику origin на основі Host-header. -- `remote.transport`: `ssh` (за замовчуванням) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. -- `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`: базовий URL HTTPS для зовнішнього APNs relay, який використовують офіційні/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 URL relay через HTTP. У production URL relay мають лишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. За замовчуванням: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте це значення більшим або рівним `gateway.channelHealthCheckMinutes`. За замовчуванням: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис за ковзну годину. За замовчуванням: `10`. -- `channels..healthMonitor.enabled`: opt-out на рівні каналу для перезапусків health-monitor, при цьому глобальний монітор лишається ввімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для каналів із кількома обліковими записами. Якщо задано, воно має пріоритет над перевизначенням на рівні каналу. -- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef, але не розв’язано, розв’язання завершується fail-closed (без маскування резервним віддаленим варіантом). -- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Вказуйте лише proxy, які ви контролюєте. Записи loopback і далі припустимі для конфігурацій same-host proxy/local-detection (наприклад, 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`: необов’язковий allowlist CIDR/IP для автоматичного схвалення першого спарювання пристрою вузла без запитаних scope. Якщо не задано, вимкнено. Це не схвалює автоматично спарювання operator/browser/Control UI/WebChat, а також не схвалює автоматично підвищення ролі, scope, metadata або public-key. -- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд вузла після спарювання та перевірки allowlist. -- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює стандартний deny list). -- `gateway.tools.allow`: вилучає назви інструментів зі стандартного deny list. +- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються браузерні клієнти з не-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`: клієнтський аварійний override у середовищі процесу, + який дозволяє plaintext `ws://` до довірених IP-адрес приватної мережі; типовим значенням залишається plaintext лише для 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-backed реєстрації в gateway. Цей URL має збігатися з URL relay, скомпільованим у збірці iOS. +- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання gateway-to-relay у мілісекундах. Типово `10000`. +- Relay-backed реєстрації делегуються конкретній ідентичності 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 relay URL. У production URL relay мають залишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу стану каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типово: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Тримайте його більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис у ковзній годині. Типово: `10`. +- `channels..healthMonitor.enabled`: opt-out на рівні каналу для перезапусків health-monitor із збереженням увімкненого глобального монітора. +- `channels..accounts..healthMonitor.enabled`: перевизначення на рівні облікового запису для multi-account каналів. Якщо задано, має пріоритет над перевизначенням на рівні каналу. +- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як запасний варіант лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання завершується fail-closed (без маскування через запасний remote fallback). +- `trustedProxies`: IP-адреси reverse proxy, які завершують TLS або вставляють forwarded-client заголовки. Указуйте лише proxy, які ви контролюєте. Записи loopback і далі є чинними для конфігурацій same-host proxy/local-detection (наприклад 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 для автоматичного схвалення першого pairing пристрою node без запитаних областей доступу. Коли не задано — вимкнено. Це не схвалює автоматично pairing operator/browser/Control UI/WebChat і не схвалює автоматично оновлення ролі, областей доступу, метаданих чи публічного ключа. +- `gateway.nodes.allowCommands` / `gateway.nodes.denyCommands`: глобальне формування allow/deny для оголошених команд node після pairing і перевірки списку дозволу. +- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список deny). +- `gateway.tools.allow`: вилучає назви інструментів із типового HTTP deny-списку. -### OpenAI-compatible endpoints +### 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` + Порожні allowlist сприймаються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. -- Необов’язковий заголовок посиленого захисту відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для origin HTTPS, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) +- Необов’язковий заголовок посилення захисту відповіді: + - `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS origin, які ви контролюєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) ### Ізоляція кількох екземплярів @@ -474,11 +479,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (за замовчуванням: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, якщо явні файли не налаштовано; лише для local/dev. -- `certPath`: шлях файлової системи до файла сертифіката TLS. -- `keyPath`: шлях файлової системи до файла приватного ключа TLS; зберігайте з обмеженими правами доступу. -- `caPath`: необов’язковий шлях до пакета CA для перевірки клієнта або користувацьких ланцюжків довіри. +- `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). +- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, якщо явні файли не налаштовано; лише для локального/dev використання. +- `certPath`: шлях файлової системи до файла TLS-сертифіката. +- `keyPath`: шлях файлової системи до файла приватного TLS-ключа; обмежте доступ через дозволи. +- `caPath`: необов’язковий шлях до CA bundle для перевірки клієнта або користувацьких ланцюгів довіри. ### `gateway.reload` @@ -495,12 +500,12 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час виконання. - - `"off"`: ігнорувати зміни наживо; зміни потребують явного перезапуску. + - `"off"`: ігнорувати живі зміни; зміни потребують явного перезапуску. - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. - - `"hot"`: застосовувати зміни в межах процесу без перезапуску. - - `"hybrid"` (за замовчуванням): спочатку спробувати hot reload; якщо потрібно, перейти до перезапуску. + - `"hot"`: застосовувати зміни в процесі без перезапуску. + - `"hybrid"` (типово): спочатку спробувати hot reload; якщо потрібно, перейти до перезапуску. - `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: необов’язковий максимальний час у мс для очікування поточних операцій перед примусовим перезапуском. Не вказуйте його або встановіть `0`, щоб чекати необмежено довго й періодично журналювати попередження про те, що ще є незавершені операції. +- `deferralTimeoutMs`: необов’язковий максимальний час у мс, протягом якого чекати завершення операцій у процесі перед примусовим перезапуском. Пропустіть його або встановіть `0`, щоб чекати необмежено довго та періодично записувати попередження про операції, що все ще очікують. --- @@ -538,37 +543,37 @@ openclaw gateway --port 19001 ``` Auth: `Authorization: Bearer ` або `x-openclaw-token: `. -Hook token у query string відхиляються. +Hook-токени в рядку запиту відхиляються. Примітки щодо валідації та безпеки: - `hooks.enabled=true` вимагає непорожній `hooks.token`. -- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання token Gateway відхиляється. +- `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. +- Якщо `hooks.allowRequestSessionKey=true`, обмежуйте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). +- Якщо mapping або preset використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують такого opt-in. -**Endpoints:** +**Кінцеві точки:** - `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` відповідає полю корисного навантаження для загальних шляхів. +- `match.path` зіставляє підшлях після `/hooks` (наприклад, `/hooks/gmail` → `gmail`). +- `match.source` зіставляє поле корисного навантаження для загальних шляхів. - Шаблони на кшталт `{{messages[0].subject}}` читають дані з корисного навантаження. -- `transform` може вказувати на модуль JS/TS, що повертає hook action. +- `transform` може вказувати на модуль JS/TS, що повертає дію hook. - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). -- `agentId` спрямовує до конкретного агента; невідомі ID повертаються до стандартного. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або не вказано = дозволити всі, `[]` = заборонити всі). -- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook agent без явного `sessionKey`. -- `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` і ключам сесії mapping, керованим шаблонами, задавати `sessionKey` (за замовчуванням: `false`). -- `allowedSessionKeyPrefixes`: необов’язковий allowlist префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Він стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`. -- `deliver: true` надсилає фінальну відповідь у канал; `channel` за замовчуванням — `last`. +- `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 (має бути дозволена, якщо задано каталог моделей). @@ -576,8 +581,8 @@ Hook token у query string відхиляються. ### Інтеграція 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 { @@ -600,12 +605,12 @@ Hook token у query string відхиляються. } ``` -- 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. --- -## Canvas host +## Хост Canvas ```json5 { @@ -620,11 +625,11 @@ Hook token у query string відхиляються. - Обслуговує редаговані агентом HTML/CSS/JS і A2UI через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Лише локально: зберігайте `gateway.bind: "loopback"` (за замовчуванням). -- Для 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, що обслуговується. +- Лише локально: зберігайте `gateway.bind: "loopback"` (типово). +- Для не-loopback bind: маршрути canvas потребують auth Gateway (token/password/trusted-proxy), як і інші HTTP-поверхні Gateway. +- Node WebView зазвичай не надсилають заголовки auth; після pairing і підключення node Gateway рекламує URL можливостей у межах node для доступу до canvas/A2UI. +- URL можливостей прив’язані до активної WS-сесії node і швидко спливають. Резервний варіант на основі IP не використовується. +- Вбудовує клієнт live-reload у HTML, що обслуговується. - Автоматично створює стартовий `index.html`, якщо каталог порожній. - Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. - Зміни потребують перезапуску gateway. @@ -646,9 +651,9 @@ Hook token у query string відхиляються. } ``` -- `minimal` (за замовчуванням): пропускає `cliPath` + `sshPort` із записів TXT. +- `minimal` (типово): не включає `cliPath` + `sshPort` у TXT-записи. - `full`: включає `cliPath` + `sshPort`. -- Ім’я хоста за замовчуванням — `openclaw`. Перевизначайте через `OPENCLAW_MDNS_HOSTNAME`. +- Ім’я хоста типово `openclaw`. Перевизначайте через `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -660,7 +665,7 @@ Hook token у query string відхиляються. } ``` -Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) і Tailscale split DNS. +Записує зону unicast DNS-SD до `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте це з DNS-сервером (рекомендується CoreDNS) + split DNS у Tailscale. Налаштування: `openclaw dns setup --apply`. @@ -668,7 +673,7 @@ Hook token у query string відхиляються. ## Середовище -### `env` (вбудовані env-змінні) +### `env` (вбудовані env var) ```json5 { @@ -685,14 +690,14 @@ Hook token у query string відхиляються. } ``` -- Вбудовані env-змінні застосовуються лише тоді, коли в середовищі процесу відсутній ключ. -- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден не перевизначає наявні змінні). +- Вбудовані env var застосовуються лише тоді, коли в середовищі процесу відсутній ключ. +- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). - `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний пріоритет див. у [Environment](/uk/help/environment). +- Див. [Environment](/uk/help/environment) щодо повного пріоритету. -### Підстановка env-змінних +### Підстановка env var -Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`: +Посилайтеся на env var у будь-якому рядку конфігурації через `${VAR_NAME}`: ```json5 { @@ -702,16 +707,16 @@ Hook token у query string відхиляються. } ``` -- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. -- Екрануйте через `$${VAR}`, щоб отримати буквальний `${VAR}`. +- Екрануйте через `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. --- ## Секрети -Посилання на секрети є адитивними: значення у відкритому тексті й надалі працюють. +Посилання на секрети є адитивними: прості текстові значення й далі працюють. ### `SecretRef` @@ -725,15 +730,15 @@ Hook token у query string відхиляються. - шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$` - шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- `id` для `source: "file"`: абсолютний покажчик JSON pointer (наприклад, `"/providers/openai/apiKey"`) +- `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"` не повинні містити slash-delimited сегменти шляху `.` або `..` (наприклад, `a/../b` відхиляється) ### Підтримувана поверхня облікових даних - Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання в `auth-profiles.json` включено до runtime-розв’язання та покриття аудиту. +- Посилання в `auth-profiles.json` включені в покриття розв’язання під час виконання та аудиту. ### Конфігурація провайдерів секретів @@ -765,14 +770,14 @@ Hook token у query string відхиляються. Примітки: -- Провайдер `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 завершуються fail-closed, якщо перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. +- Провайдер `exec` вимагає абсолютний шлях `command` і використовує корисні навантаження протоколу через stdin/stdout. +- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання з перевіркою розв’язаного цільового шляху. +- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до розв’язаного цільового шляху. +- Дочірнє середовище `exec` типово є мінімальним; явно передавайте потрібні змінні через `passEnv`. - Посилання на секрети розв’язуються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. -- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на ввімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. +- Фільтрація активної поверхні застосовується під час активації: нерозв’язані посилання на увімкнених поверхнях призводять до помилки запуску/перезавантаження, а неактивні поверхні пропускаються з діагностикою. --- @@ -796,11 +801,11 @@ Hook token у query string відхиляються. - Профілі для кожного агента зберігаються в `/auth-profiles.json`. - `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. -- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілів auth на основі SecretRef. -- Статичні runtime-облікові дані надходять із розв’язаних знімків у пам’яті; legacy записи в `auth.json` очищаються при виявленні. -- Legacy імпорт OAuth із `~/.openclaw/credentials/oauth.json`. +- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані auth-profile на основі SecretRef. +- Статичні облікові дані runtime надходять із розв’язаних знімків у пам’яті; застарілі статичні записи `auth.json` очищуються при виявленні. +- Застарілий імпорт OAuth із `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Runtime-поведінка секретів та інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). +- Поведінка runtime секретів та інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). ### `auth.cooldowns` @@ -822,24 +827,24 @@ Hook token у query string відхиляються. } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні - помилки білінгу/недостатнього кредиту (за замовчуванням: `5`). Явний текст про білінг - усе ще може потрапити сюди навіть у відповідях `401`/`403`, але провайдер-специфічні - зіставлювачі тексту лишаються в межах провайдера, якому вони належать (наприклад OpenRouter - `Key limit exceeded`). Повторювані повідомлення HTTP `402` про usage-window або - ліміти витрат organization/workspace залишаються в шляху `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff для білінгу для кожного провайдера. -- `billingMaxHours`: верхня межа в годинах для експоненційного зростання backoff білінгу (за замовчуванням: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для помилок `auth_permanent` із високою впевненістю (за замовчуванням: `10`). -- `authPermanentMaxMinutes`: верхня межа в хвилинах для зростання backoff `auth_permanent` (за замовчуванням: `60`). -- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (за замовчуванням: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для перевантажених помилок перед переходом до резервної моделі (за замовчуванням: `1`). Форми на кшталт `ModelNotReadyException`, що вказують на зайнятість провайдера, потрапляють сюди. -- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (за замовчуванням: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок rate-limit перед переходом до резервної моделі (за замовчуванням: `1`). До цього кошика rate-limit входить текст, характерний для провайдерів, такий як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає невдачі через справжні помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст про білінг + усе ще може потрапити сюди навіть за відповідей `401`/`403`, але + зіставлювачі тексту, специфічні для провайдера, залишаються прив’язаними до + провайдера, якому вони належать (наприклад OpenRouter + `Key limit exceeded`). Повторювані HTTP `402` повідомлення про usage-window або + organization/workspace spend-limit натомість залишаються в шляху `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff для білінгу за провайдерами. +- `billingMaxHours`: верхня межа в годинах для експоненційного зростання billing backoff (типово: `24`). +- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для збоїв `auth_permanent` з високою впевненістю (типово: `10`). +- `authPermanentMaxMinutes`: верхня межа в хвилинах для зростання backoff `auth_permanent` (типово: `60`). +- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок перевантаження перед переходом до резервної моделі (типово: `1`). Сюди потрапляють форми на кшталт `ModelNotReadyException`, що означають зайнятість провайдера. +- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого провайдера для помилок rate-limit перед переходом до резервної моделі (типово: `1`). Цей кошик rate-limit включає текст у формі провайдера, наприклад `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- -## Журналювання +## Логування ```json5 { @@ -854,10 +859,10 @@ Hook token у query string відхиляються. } ``` -- Стандартний файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. +- Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Установіть `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug` за `--verbose`. -- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого записи припиняються (додатне ціле число; за замовчуванням: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. +- `consoleLevel` підвищується до `debug` із `--verbose`. +- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис припиняється (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію логів. --- @@ -902,22 +907,22 @@ Hook token у query string відхиляються. } ``` -- `enabled`: головний перемикач для виводу інструментування (за замовчуванням: `true`). -- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналів (підтримує шаблони з wildcard, як-от `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку в мс для виводу попереджень про завислу сесію, поки сесія лишається у стані обробки. -- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (за замовчуванням: `false`). +- `enabled`: головний перемикач для виведення інструментування (типово: `true`). +- `flags`: масив рядків-прапорців, які вмикають цільове виведення логів (підтримує шаблони з wildcard, як-от `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, поки сесія залишається в стані обробки. +- `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). - `otel.endpoint`: URL колектора для експорту OTel. -- `otel.protocol`: `"http/protobuf"` (за замовчуванням) або `"grpc"`. +- `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. - `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. -- `otel.serviceName`: назва сервісу для атрибутів ресурсу. -- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт трасувань, метрик або журналів. -- `otel.sampleRate`: коефіцієнт семплювання трасувань `0`–`1`. +- `otel.serviceName`: ім’я сервісу для атрибутів ресурсу. +- `otel.traces` / `otel.metrics` / `otel.logs`: вмикають експорт trace, metrics або logs. +- `otel.sampleRate`: частота вибірки trace `0`–`1`. - `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. -- `otel.captureContent`: opt-in захоплення необробленого вмісту для атрибутів span OTEL. За замовчуванням вимкнено. Булеве значення `true` захоплює вміст повідомлень/інструментів, крім system; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. -- `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.captureContent`: opt-in захоплення сирого вмісту для атрибутів span OTEL. Типово вимкнено. Булеве значення `true` захоплює вміст не-system повідомлень/інструментів; форма об’єкта дає змогу явно ввімкнути `inputMessages`, `outputMessages`, `toolInputs`, `toolOutputs` і `systemPrompt`. +- `OPENCLAW_OTEL_PRELOADED=1`: прапорець середовища для хостів, які вже зареєстрували глобальний OpenTelemetry SDK. Тоді OpenClaw пропускає запуск/завершення SDK, що належить плагіну, зберігаючи активними діагностичні слухачі. +- `cacheTrace.enabled`: журналювати знімки trace кешу для вбудованих запусків (типово: `false`). +- `cacheTrace.filePath`: шлях виводу для cache trace JSONL (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід cache trace (усі типово: `true`). --- @@ -939,12 +944,12 @@ Hook token у query string відхиляються. } ``` -- `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`). +- `channel`: канал релізів для npm/git-встановлень — `"stable"`, `"beta"` або `"dev"`. +- `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). +- `auto.enabled`: увімкнути фонове автооновлення для package-встановлень (типово: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автозастосуванням stable-каналу (типово: `6`; максимум: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; максимум: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу, у годинах (типово: `1`; максимум: `24`). --- @@ -977,22 +982,22 @@ Hook token у query string відхиляються. } ``` -- `enabled`: глобальний feature gate ACP (за замовчуванням: `false`). -- `dispatch.enabled`: незалежний перемикач для dispatch ходів сесії ACP (за замовчуванням: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. -- `backend`: ID стандартного runtime-backend ACP (має збігатися із зареєстрованим Plugin runtime ACP). -- `defaultAgent`: резервний ID цільового агента ACP, коли spawn не задає явну ціль. -- `allowedAgents`: allowlist ID агентів, дозволених для runtime-сесій ACP; порожнє значення означає відсутність додаткових обмежень. +- `enabled`: глобальний feature gate ACP (типово: `false`). +- `dispatch.enabled`: незалежний gate для диспетчеризації ходів сесії ACP (типово: `true`). Установіть `false`, щоб команди ACP залишалися доступними, але виконання блокувалося. +- `backend`: id типового backend середовища виконання ACP (має збігатися із зареєстрованим плагіном runtime ACP). +- `defaultAgent`: резервний id цільового агента ACP, коли spawn не задає явну ціль. +- `allowedAgents`: список дозволу id агентів, дозволених для сесій runtime 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`: запис імен тегів у логічні перевизначення видимості для потокових подій. -- `runtime.ttlMinutes`: TTL простою в хвилинах для працівників сесії ACP до моменту, коли їх можна очищати. -- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час початкового налаштування середовища runtime ACP. +- `stream.maxChunkChars`: максимальний розмір фрагмента перед розбиттям проєкції потокового блока. +- `stream.repeatSuppression`: придушувати повторювані рядки статусу/інструментів на хід (типово: `true`). +- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до термінальних подій ходу. +- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). +- `stream.maxOutputChars`: максимальна кількість символів виводу помічника, проєктованих на хід ACP. +- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлень ACP. +- `stream.tagVisibility`: запис імен тегів до булевих перевизначень видимості для потокових подій. +- `runtime.ttlMinutes`: TTL простою в хвилинах для worker сесій ACP перед допустимим очищенням. +- `runtime.installCommand`: необов’язкова команда встановлення, яку слід запустити під час bootstrap середовища runtime ACP. --- @@ -1009,16 +1014,16 @@ Hook token у query string відхиляються. ``` - `cli.banner.taglineMode` керує стилем слогана банера: - - `"random"` (за замовчуванням): ротація кумедних/сезонних слоганів. + - `"random"` (типово): змінні кумедні/сезонні слогани. - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`). - `"off"`: без тексту слогана (заголовок/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. +- Щоб приховати весь банер (а не лише слогани), задайте env `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Метадані, які записуються потоками покрокового налаштування CLI (`onboard`, `configure`, `doctor`): +Метадані, які записуються потоками керованого налаштування CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -1034,17 +1039,17 @@ Hook token у query string відхиляються. --- -## Ідентичність +## Identity -Див. поля ідентичності `agents.list` у [Agent defaults](/uk/gateway/config-agents#agent-defaults). +Див. поля identity у `agents.list` у розділі [Agent defaults](/uk/gateway/config-agents#agent-defaults). --- -## Bridge (legacy, вилучено) +## Bridge (застарілий, видалено) -Поточні збірки більше не містять TCP bridge. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не входять до схеми конфігурації (валідація завершується помилкою, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Node підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). - + ```json { @@ -1082,11 +1087,11 @@ Hook token у query string відхиляються. } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сесії запуску cron перед обрізанням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. За замовчуванням: `24h`; установіть `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір файла журналу для одного запуску (`cron/runs/.jsonl`) перед обрізанням. За замовчуванням: `2_000_000` байтів. -- `runLog.keepLines`: кількість найновіших рядків, що зберігаються під час обрізання журналу запуску. За замовчуванням: `2000`. -- `webhookToken`: bearer token, що використовується для доставлення POST у Webhook cron (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається. -- `webhook`: застарілий legacy fallback URL Webhook (http/https), що використовується лише для збережених завдань, які все ще мають `notify: true`. +- `sessionRetention`: як довго зберігати завершені ізольовані сесії запусків cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. Типово: `24h`; установіть `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір файла журналу на запуск (`cron/runs/.jsonl`) перед очищенням. Типово: `2_000_000` байтів. +- `runLog.keepLines`: найновіші рядки, що зберігаються при запуску очищення run-log. Типово: `2000`. +- `webhookToken`: bearer token, що використовується для доставки cron Webhook POST (`delivery.mode = "webhook"`); якщо не задано, заголовок auth не надсилається. +- `webhook`: застарілий резервний URL Webhook (http/https), який використовується лише для збережених завдань, що все ще мають `notify: true`. ### `cron.retry` @@ -1102,11 +1107,11 @@ Hook token у query string відхиляються. } ``` -- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (за замовчуванням: `3`; діапазон: `0`–`10`). -- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (за замовчуванням: `[30000, 60000, 300000]`; 1–10 елементів). -- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не вказуйте, щоб повторювати для всіх тимчасових типів. +- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). +- `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). +- `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати всі тимчасові типи. -Застосовується лише до одноразових cron-завдань. Для повторюваних завдань обробка помилок окрема. +Застосовується лише до одноразових cron-завдань. Повторювані завдання використовують окрему обробку помилок. ### `cron.failureAlert` @@ -1124,11 +1129,11 @@ Hook token у query string відхиляються. } ``` -- `enabled`: увімкнути сповіщення про збої для cron-завдань (за замовчуванням: `false`). -- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мін.: `1`). +- `enabled`: увімкнути сповіщення про збої для cron-завдань (типово: `false`). +- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мінімум: `1`). - `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `mode`: режим доставлення — `"announce"` надсилає через повідомлення каналу; `"webhook"` надсилає POST на налаштований Webhook. -- `accountId`: необов’язковий ID облікового запису або каналу для обмеження області доставлення сповіщень. +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST на налаштований Webhook. +- `accountId`: необов’язковий id облікового запису або каналу для області доставки сповіщення. ### `cron.failureDestination` @@ -1145,13 +1150,13 @@ Hook token у query string відхиляються. } ``` -- Стандартне місце призначення для сповіщень про збої cron для всіх завдань. -- `mode`: `"announce"` або `"webhook"`; за замовчуванням `"announce"`, коли є достатньо даних про ціль. -- `channel`: перевизначення каналу для доставлення announce. `"last"` повторно використовує останній відомий канал доставлення. +- Типова ціль для сповіщень про збої cron для всіх завдань. +- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних про ціль. +- `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. - `to`: явна ціль announce або URL Webhook. Обов’язкове для режиму webhook. -- `accountId`: необов’язкове перевизначення облікового запису для доставлення. -- `delivery.failureDestination` для окремого завдання перевизначає це глобальне значення. -- Коли не задано ні глобальне, ні значення призначення збою для окремого завдання, завдання, які вже доставляють через `announce`, у разі збою використовують цю основну announce-ціль як резервну. +- `accountId`: необов’язкове перевизначення облікового запису для доставки. +- `delivery.failureDestination` на рівні завдання перевизначає це глобальне типове значення. +- Якщо не задано ні глобальної, ні окремої цілі збою для завдання, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної announce-цілі. - `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [background tasks](/uk/automation/tasks). @@ -1160,36 +1165,36 @@ Hook token у query string відхиляються. ## Змінні шаблону моделі медіа -Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`: +Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`: -| Змінна | Опис | -| ----------------- | --------------------------------------------------- | -| `{{Body}}` | Повний текст вхідного повідомлення | -| `{{RawBody}}` | Необроблений текст (без обгорток історії/відправника) | -| `{{BodyStripped}}`| Текст без згадувань у групі | -| `{{From}}` | Ідентифікатор відправника | -| `{{To}}` | Ідентифікатор призначення | -| `{{MessageSid}}` | ID повідомлення каналу | -| `{{SessionId}}` | UUID поточної сесії | -| `{{IsNewSession}}`| `"true"`, коли створено нову сесію | -| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | -| `{{MediaPath}}` | Локальний шлях до медіа | -| `{{MediaType}}` | Тип медіа (image/audio/document/…) | -| `{{Transcript}}` | Транскрипт аудіо | -| `{{Prompt}}` | Розв’язаний медіа-промпт для записів CLI | +| Змінна | Опис | +| ----------------- | ------------------------------------------------- | +| `{{Body}}` | Повний текст вхідного повідомлення | +| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | +| `{{BodyStripped}}`| Текст без згадок у групі | +| `{{From}}` | Ідентифікатор відправника | +| `{{To}}` | Ідентифікатор призначення | +| `{{MessageSid}}` | id повідомлення каналу | +| `{{SessionId}}` | UUID поточної сесії | +| `{{IsNewSession}}`| `"true"`, коли створено нову сесію | +| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | +| `{{MediaPath}}` | Локальний шлях до медіа | +| `{{MediaType}}` | Тип медіа (image/audio/document/…) | +| `{{Transcript}}` | Транскрипт аудіо | +| `{{Prompt}}` | Розв’язаний медіа-prompt для записів CLI | | `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI | -| `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}`| Тема групи (best effort) | -| `{{GroupMembers}}`| Попередній список учасників групи (best effort) | -| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | -| `{{SenderE164}}` | Номер телефону відправника (best effort) | +| `{{ChatType}}` | `"direct"` або `"group"` | +| `{{GroupSubject}}`| Тема групи (best effort) | +| `{{GroupMembers}}`| Попередній перегляд учасників групи (best effort) | +| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | +| `{{SenderE164}}` | Номер телефону відправника (best effort) | | `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | --- ## Include конфігурації (`$include`) -Розділяйте конфігурацію на кілька файлів: +Розділіть конфігурацію на кілька файлів: ```json5 // ~/.openclaw/openclaw.json @@ -1205,13 +1210,13 @@ Hook token у query string відхиляються. **Поведінка злиття:** - Один файл: замінює об’єкт-контейнер. -- Масив файлів: deep merge у заданому порядку (пізніші перевизначають попередні). +- Масив файлів: deep-merge у вказаному порядку (пізніші значення перевизначають попередні). - Сусідні ключі: зливаються після include (перевизначають включені значення). - Вкладені include: до 10 рівнів глибини. -- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми та `../` дозволені лише тоді, коли після розв’язання вони все ще лишаються в межах цієї границі. -- Записи, які належать OpenClaw і змінюють лише один розділ верхнього рівня, підкріплений include одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. -- Кореневі include, масиви include та include із сусідніми перевизначеннями є лише для читання для записів, що належать OpenClaw; такі записи завершуються fail-closed замість сплощення конфігурації. -- Помилки: зрозумілі повідомлення для відсутніх файлів, помилок розбору та циклічних include. +- Шляхи: розв’язуються відносно файлу, який містить include, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли після розв’язання вони все одно залишаються в межах цього кордону. +- Записи, якими керує OpenClaw і які змінюють лише один розділ верхнього рівня, підкріплений include одного файлу, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` незмінним. +- Кореневі include, масиви include та include із сусідніми перевизначеннями доступні лише для читання для записів, якими керує OpenClaw; такі записи завершуються fail-closed замість сплощення конфігурації. +- Помилки: зрозумілі повідомлення про відсутні файли, помилки парсингу та циклічні include. --- diff --git a/docs/uk/logging.md b/docs/uk/logging.md index 084d5970a..57a0bb250 100644 --- a/docs/uk/logging.md +++ b/docs/uk/logging.md @@ -1,15 +1,15 @@ --- read_when: - - Вам потрібен зрозумілий для початківців огляд журналювання + - Вам потрібен огляд журналювання, зрозумілий для початківців - Ви хочете налаштувати рівні журналювання або формати - - Ви усуваєте неполадки й хочете швидко знайти журнали -summary: 'Огляд журналювання: журнали у файлах, вивід у консолі, відстеження через CLI та Control UI' + - Ви усуваєте несправності й хочете швидко знайти журнали +summary: 'Огляд журналювання: журнали файлів, виведення в консоль, перегляд журналів у CLI та інтерфейс Control UI' title: Огляд журналювання x-i18n: - generated_at: "2026-04-25T08:32:08Z" + generated_at: "2026-04-25T18:41:27Z" model: gpt-5.4 provider: openai - source_hash: e16a8aa487616c338c625c55fdfcc604759ee7b1e235b0b318b36d7a6fb07ab8 + source_hash: 745c14ef9ca008d43a0f4f2d5c051ec6bafbe5249e1a1753448182fff72afd6e source_path: logging.md workflow: 15 --- @@ -18,14 +18,14 @@ x-i18n: OpenClaw має дві основні поверхні журналювання: -- **Журнали у файлах** (рядки JSON), які записує Gateway. -- **Вивід у консоль**, що показується в терміналах і в Gateway Debug UI. +- **Файлові журнали** (рядки JSON), які записує Gateway. +- **Виведення в консоль**, яке показується в терміналах і в інтерфейсі Gateway Debug UI. -Вкладка **Logs** у Control UI відстежує журнал файлу gateway. На цій сторінці пояснюється, де зберігаються журнали, як їх читати та як налаштовувати рівні журналювання і формати. +Вкладка **Logs** в Control UI відстежує файловий журнал gateway. На цій сторінці пояснюється, де зберігаються журнали, як їх читати та як налаштовувати рівні й формати журналювання. ## Де зберігаються журнали -Типово Gateway записує ротаційний файл журналу в: +За замовчуванням Gateway записує циклічний файл журналу в: `/tmp/openclaw/openclaw-YYYY-MM-DD.log` @@ -43,7 +43,7 @@ OpenClaw має дві основні поверхні журналювання: ## Як читати журнали -### CLI: відстеження в реальному часі (рекомендовано) +### CLI: перегляд у реальному часі (рекомендовано) Використовуйте CLI, щоб відстежувати файл журналу gateway через RPC: @@ -51,30 +51,30 @@ OpenClaw має дві основні поверхні журналювання: openclaw logs --follow ``` -Корисні актуальні параметри: +Корисні поточні параметри: - `--local-time`: відображати часові мітки у вашому локальному часовому поясі - `--url ` / `--token ` / `--timeout `: стандартні прапорці Gateway RPC -- `--expect-final`: прапорець очікування фінальної відповіді для RPC на основі агентів (підтримується тут через спільний клієнтський шар) +- `--expect-final`: прапорець очікування фінальної відповіді для RPC на базі агента (приймається тут через спільний клієнтський шар) -Режими виводу: +Режими виведення: -- **TTY-сеанси**: гарні, кольорові, структуровані рядки журналу. -- **Не-TTY-сеанси**: звичайний текст. -- `--json`: JSON з розділенням по рядках (одна подія журналу на рядок). -- `--plain`: примусово використовувати звичайний текст у TTY-сеансах. +- **Сеанси TTY**: зручні для читання, кольорові, структуровані рядки журналу. +- **Сеанси без TTY**: звичайний текст. +- `--json`: JSON із розділенням по рядках (одна подія журналу на рядок). +- `--plain`: примусово використовувати звичайний текст у сеансах TTY. - `--no-color`: вимкнути кольори ANSI. -Коли ви передаєте явний `--url`, CLI не застосовує автоматично облікові дані з конфігурації або середовища; додайте `--token` самостійно, якщо цільовий Gateway вимагає автентифікації. +Коли ви передаєте явний `--url`, CLI не застосовує автоматично облікові дані з конфігурації або середовища; якщо цільовий Gateway вимагає автентифікації, додайте `--token` самостійно. -У режимі JSON CLI виводить об’єкти з міткою `type`: +У режимі JSON CLI виводить об’єкти з тегом `type`: - `meta`: метадані потоку (файл, курсор, розмір) - `log`: розібраний запис журналу -- `notice`: підказки щодо обрізання / ротації +- `notice`: підказки про обрізання / ротацію - `raw`: нерозібраний рядок журналу -Якщо Gateway на local loopback запитує сполучення, `openclaw logs` автоматично переключається на налаштований локальний файл журналу. Явні цілі `--url` цей резервний механізм не використовують. +Якщо локальний loopback Gateway запитує сполучення, `openclaw logs` автоматично переходить до налаштованого локального файлу журналу. Явні цілі `--url` не використовують цей резервний механізм. Якщо Gateway недоступний, CLI виводить коротку підказку виконати: @@ -84,12 +84,12 @@ openclaw doctor ### Control UI (веб) -Вкладка **Logs** у Control UI відстежує той самий файл через `logs.tail`. +Вкладка **Logs** у Control UI відстежує той самий файл за допомогою `logs.tail`. Див. [/web/control-ui](/uk/web/control-ui), щоб дізнатися, як її відкрити. ### Журнали лише каналів -Щоб відфільтрувати активність каналу (WhatsApp/Telegram/тощо), використовуйте: +Щоб фільтрувати активність каналів (WhatsApp/Telegram/etc), використовуйте: ```bash openclaw channels logs --channel whatsapp @@ -97,20 +97,19 @@ openclaw channels logs --channel whatsapp ## Формати журналів -### Журнали у файлах (JSONL) +### Файлові журнали (JSONL) -Кожен рядок у файлі журналу — це об’єкт JSON. CLI і Control UI розбирають ці -записи, щоб відображати структурований вивід (час, рівень, підсистема, повідомлення). +Кожен рядок у файлі журналу — це об’єкт JSON. CLI і Control UI розбирають ці записи, щоб відображати структуроване виведення (час, рівень, підсистема, повідомлення). -### Вивід у консоль +### Виведення в консоль -Журнали в консолі **враховують TTY** і форматуються для зручності читання: +Журнали консолі **враховують TTY** і форматуються для зручності читання: - Префікси підсистем (наприклад, `gateway/channels/whatsapp`) -- Кольорове виділення рівнів (info/warn/error) +- Кольори рівнів (info/warn/error) - Необов’язковий компактний або JSON-режим -Форматування консолі керується через `logging.consoleStyle`. +Форматування консолі керується `logging.consoleStyle`. ### Журнали WebSocket Gateway @@ -131,7 +130,7 @@ openclaw gateway --verbose --ws-log full ## Налаштування журналювання -Усі налаштування журналювання знаходяться в `logging` у `~/.openclaw/openclaw.json`. +Усі налаштування журналювання розміщені в розділі `logging` у `~/.openclaw/openclaw.json`. ```json { @@ -148,52 +147,48 @@ openclaw gateway --verbose --ws-log full ### Рівні журналювання -- `logging.level`: рівень для **журналів у файлах** (JSONL). -- `logging.consoleLevel`: рівень деталізації для **консолі**. +- `logging.level`: рівень **файлових журналів** (JSONL). +- `logging.consoleLevel`: рівень докладності **консолі**. -Обидва параметри можна перевизначити через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має вищий пріоритет, ніж файл конфігурації, тож ви можете підвищити деталізацію для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level `** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди. +Ви можете перевизначити обидва через змінну середовища **`OPENCLAW_LOG_LEVEL`** (наприклад, `OPENCLAW_LOG_LEVEL=debug`). Змінна середовища має вищий пріоритет за файл конфігурації, тож ви можете підвищити докладність для одного запуску без редагування `openclaw.json`. Ви також можете передати глобальний параметр CLI **`--log-level `** (наприклад, `openclaw --log-level debug gateway run`), який перевизначає змінну середовища для цієї команди. -`--verbose` впливає лише на вивід у консоль і деталізацію журналів WS; він не змінює -рівні журналів у файлах. +`--verbose` впливає лише на виведення в консоль і докладність журналу WS; він не змінює рівні файлового журналу. ### Стилі консолі `logging.consoleStyle`: - `pretty`: зручний для людей, кольоровий, із часовими мітками. -- `compact`: щільніший вивід (найкраще для довгих сеансів). +- `compact`: більш стислий вивід (найкраще для довгих сеансів). - `json`: JSON у кожному рядку (для обробників журналів). -### Редагування +### Редагування чутливих даних -Зведення інструментів можуть редагувати чутливі токени перед потраплянням у консоль: +Підсумки інструментів можуть редагувати чутливі токени до того, як вони потраплять у консоль: - `logging.redactSensitive`: `off` | `tools` (типово: `tools`) - `logging.redactPatterns`: список рядків regex для перевизначення типового набору -Редагування впливає **лише на вивід у консоль** і не змінює журнали у файлах. +Редагування впливає **лише на виведення в консоль** і не змінює файлові журнали. ## Діагностика + OpenTelemetry -Діагностика — це структуровані, машинозчитувані події для запусків моделей **і** -телеметрії потоку повідомлень (webhooks, постановка в чергу, стан сеансу). Вони **не** -замінюють журнали; вони існують, щоб передавати дані в метрики, трасування та інші експортери. +Діагностика — це структуровані, машиночитні події для запусків моделей **і** +телеметрії потоку повідомлень (webhooks, постановка в чергу, стан сеансу). Вони **не** замінюють журнали; вони існують для подачі метрик, трасувань та інших експортерів. -Події діагностики генеруються в процесі, але експортери підключаються лише тоді, коли -ввімкнено діагностику та Plugin експортера. +Події діагностики створюються всередині процесу, але експортери підключаються лише тоді, коли ввімкнено діагностику та plugin експортера. ### OpenTelemetry проти OTLP - **OpenTelemetry (OTel)**: модель даних і SDK для трасувань, метрик і журналів. -- **OTLP**: протокол передавання, який використовується для експорту даних OTel до колектора/бекенда. -- OpenClaw сьогодні експортує через **OTLP/HTTP (protobuf)**. +- **OTLP**: мережевий протокол, який використовується для експорту даних OTel у collector/backend. +- OpenClaw наразі експортує через **OTLP/HTTP (protobuf)**. ### Експортовані сигнали -- **Метрики**: лічильники та гістограми (використання токенів, потік повідомлень, черги). +- **Метрики**: лічильники та гістограми (використання токенів, потік повідомлень, постановка в чергу). - **Трасування**: spans для використання моделей і обробки webhook/повідомлень. -- **Журнали**: експортуються через OTLP, коли ввімкнено `diagnostics.otel.logs`. Обсяг - журналів може бути великим; враховуйте `logging.level` і фільтри експортера. +- **Журнали**: експортуються через OTLP, коли ввімкнено `diagnostics.otel.logs`. Обсяг журналів може бути великим; зважайте на `logging.level` і фільтри експортера. ### Каталог подій діагностики @@ -203,33 +198,33 @@ openclaw gateway --verbose --ws-log full Потік повідомлень: -- `webhook.received`: вхід webhook для кожного каналу. +- `webhook.received`: вхідний webhook для кожного каналу. - `webhook.processed`: оброблений webhook + тривалість. - `webhook.error`: помилки обробника webhook. -- `message.queued`: повідомлення поставлено в чергу на обробку. +- `message.queued`: повідомлення поставлено в чергу для обробки. - `message.processed`: результат + тривалість + необов’язкова помилка. - `message.delivery.started`: розпочато спробу вихідної доставки. - `message.delivery.completed`: завершено спробу вихідної доставки + тривалість/кількість результатів. -- `message.delivery.error`: спроба вихідної доставки завершилася помилкою + тривалість/обмежена категорія помилки. +- `message.delivery.error`: помилка спроби вихідної доставки + тривалість/обмежена категорія помилки. Черга + сеанс: - `queue.lane.enqueue`: додавання в lane черги команд + глибина. -- `queue.lane.dequeue`: видалення з lane черги команд + час очікування. +- `queue.lane.dequeue`: вилучення з lane черги команд + час очікування. - `session.state`: перехід стану сеансу + причина. -- `session.stuck`: попередження про зависання сеансу + вік. +- `session.stuck`: попередження про завислий сеанс + вік. - `run.attempt`: метадані повторної спроби/спроби запуску. - `diagnostic.heartbeat`: агреговані лічильники (webhooks/черга/сеанс). -Виконання: +Exec: - `exec.process.completed`: результат процесу terminal exec, тривалість, ціль, режим, - код виходу та тип збою. Текст команди й робочі каталоги не + код завершення та тип збою. Текст команди й робочі каталоги не включаються. ### Увімкнення діагностики (без експортера) -Використовуйте це, якщо хочете, щоб події діагностики були доступні Plugins або власним приймачам: +Використовуйте це, якщо хочете, щоб події діагностики були доступні plugin-ам або користувацьким sinks: ```json { @@ -241,8 +236,8 @@ openclaw gateway --verbose --ws-log full ### Прапорці діагностики (цільові журнали) -Використовуйте прапорці, щоб увімкнути додаткові цільові журнали налагодження без підвищення `logging.level`. -Прапорці нечутливі до регістру та підтримують шаблони (наприклад, `telegram.*` або `*`). +Використовуйте прапорці, щоб увімкнути додаткові, цільові журнали налагодження без підвищення `logging.level`. +Прапорці нечутливі до регістру та підтримують wildcard-шаблони (наприклад, `telegram.*` або `*`). ```json { @@ -252,7 +247,7 @@ openclaw gateway --verbose --ws-log full } ``` -Перевизначення через змінну середовища (одноразово): +Перевизначення через змінну середовища (разово): ``` OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload @@ -260,14 +255,14 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload Примітки: -- Журнали прапорців записуються у стандартний файл журналу (той самий, що й `logging.file`). -- Вивід усе ще редагується відповідно до `logging.redactSensitive`. +- Журнали за прапорцями записуються у стандартний файл журналу (той самий, що й `logging.file`). +- Виведення все одно редагується відповідно до `logging.redactSensitive`. - Повний посібник: [/diagnostics/flags](/uk/diagnostics/flags). ### Експорт до OpenTelemetry -Діагностику можна експортувати через Plugin `diagnostics-otel` (OTLP/HTTP). Це -працює з будь-яким колектором/бекендом OpenTelemetry, який приймає OTLP/HTTP. +Діагностику можна експортувати через plugin `diagnostics-otel` (OTLP/HTTP). Це +працює з будь-яким collector/backend OpenTelemetry, який приймає OTLP/HTTP. ```json { @@ -306,72 +301,84 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload Примітки: -- Ви також можете ввімкнути Plugin за допомогою `openclaw plugins enable diagnostics-otel`. +- Ви також можете ввімкнути plugin за допомогою `openclaw plugins enable diagnostics-otel`. - `protocol` наразі підтримує лише `http/protobuf`. `grpc` ігнорується. -- Метрики включають використання токенів, вартість, розмір контексту, тривалість запуску та лічильники/гістограми потоку повідомлень (webhooks, черги, стан сеансу, глибина/очікування черги). -- Трасування/метрики можна перемикати через `traces` / `metrics` (типово: увімкнено). Трасування - включають spans використання моделей, а також spans обробки webhook/повідомлень, коли це ввімкнено. -- Сирий вміст моделей/інструментів типово не експортується. Використовуйте - `diagnostics.otel.captureContent` лише тоді, коли ваш колектор і політика зберігання - схвалені для тексту підказок, відповідей, інструментів або системних підказок. -- Установіть `headers`, якщо ваш колектор вимагає автентифікації. +- Метрики включають використання токенів, вартість, розмір контексту, тривалість запуску та лічильники/гістограми потоку повідомлень (webhooks, постановка в чергу, стан сеансу, глибина/очікування черги). +- Трасування/метрики можна перемикати через `traces` / `metrics` (типово: увімкнено). Трасування включають spans використання моделей, а також spans обробки webhook/повідомлень, коли це ввімкнено. +- Необроблений вміст моделей/інструментів типово не експортується. Використовуйте + `diagnostics.otel.captureContent` лише тоді, коли ваші правила щодо collector і зберігання + схвалюють текст підказок, відповідей, інструментів або системних підказок. +- Установіть `headers`, якщо ваш collector вимагає автентифікації. - Підтримувані змінні середовища: `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_SERVICE_NAME`, `OTEL_EXPORTER_OTLP_PROTOCOL`. -- Установіть `OPENCLAW_OTEL_PRELOADED=1`, якщо інше попереднє завантаження або хост-процес уже - зареєстрував глобальний SDK OpenTelemetry. У цьому режимі Plugin не запускає - і не завершує роботу власного SDK, але все одно підключає слухачі діагностики OpenClaw і - враховує `diagnostics.otel.traces`, `metrics` і `logs`. +- Установіть `OPENCLAW_OTEL_PRELOADED=1`, коли інше попереднє завантаження або хост-процес уже + зареєстрували глобальний SDK OpenTelemetry. У цьому режимі plugin не запускає + і не завершує власний SDK, але все одно підключає слухачі діагностики OpenClaw і + дотримується `diagnostics.otel.traces`, `metrics` і `logs`. ### Експортовані метрики (назви + типи) Використання моделей: -- `openclaw.tokens` (лічильник, атрибути: `openclaw.token`, `openclaw.channel`, +- `openclaw.tokens` (counter, attrs: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.cost.usd` (лічильник, атрибути: `openclaw.channel`, `openclaw.provider`, +- `openclaw.cost.usd` (counter, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.run.duration_ms` (гістограма, атрибути: `openclaw.channel`, +- `openclaw.run.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `openclaw.context.tokens` (гістограма, атрибути: `openclaw.context`, +- `openclaw.context.tokens` (histogram, attrs: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) +- `gen_ai.client.token.usage` (histogram, метрика семантичних конвенцій GenAI, + attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.system`, + `gen_ai.operation.name`, `gen_ai.request.model`) Потік повідомлень: -- `openclaw.webhook.received` (лічильник, атрибути: `openclaw.channel`, +- `openclaw.webhook.received` (counter, attrs: `openclaw.channel`, `openclaw.webhook`) -- `openclaw.webhook.error` (лічильник, атрибути: `openclaw.channel`, +- `openclaw.webhook.error` (counter, attrs: `openclaw.channel`, `openclaw.webhook`) -- `openclaw.webhook.duration_ms` (гістограма, атрибути: `openclaw.channel`, +- `openclaw.webhook.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.webhook`) -- `openclaw.message.queued` (лічильник, атрибути: `openclaw.channel`, +- `openclaw.message.queued` (counter, attrs: `openclaw.channel`, `openclaw.source`) -- `openclaw.message.processed` (лічильник, атрибути: `openclaw.channel`, +- `openclaw.message.processed` (counter, attrs: `openclaw.channel`, `openclaw.outcome`) -- `openclaw.message.duration_ms` (гістограма, атрибути: `openclaw.channel`, +- `openclaw.message.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.outcome`) -- `openclaw.message.delivery.started` (лічильник, атрибути: `openclaw.channel`, +- `openclaw.message.delivery.started` (counter, attrs: `openclaw.channel`, `openclaw.delivery.kind`) -- `openclaw.message.delivery.duration_ms` (гістограма, атрибути: +- `openclaw.message.delivery.duration_ms` (histogram, attrs: `openclaw.channel`, `openclaw.delivery.kind`, `openclaw.outcome`, `openclaw.errorCategory`) Черги + сеанси: -- `openclaw.queue.lane.enqueue` (лічильник, атрибути: `openclaw.lane`) -- `openclaw.queue.lane.dequeue` (лічильник, атрибути: `openclaw.lane`) -- `openclaw.queue.depth` (гістограма, атрибути: `openclaw.lane` або +- `openclaw.queue.lane.enqueue` (counter, attrs: `openclaw.lane`) +- `openclaw.queue.lane.dequeue` (counter, attrs: `openclaw.lane`) +- `openclaw.queue.depth` (histogram, attrs: `openclaw.lane` або `openclaw.channel=heartbeat`) -- `openclaw.queue.wait_ms` (гістограма, атрибути: `openclaw.lane`) -- `openclaw.session.state` (лічильник, атрибути: `openclaw.state`, `openclaw.reason`) -- `openclaw.session.stuck` (лічильник, атрибути: `openclaw.state`) -- `openclaw.session.stuck_age_ms` (гістограма, атрибути: `openclaw.state`) -- `openclaw.run.attempt` (лічильник, атрибути: `openclaw.attempt`) +- `openclaw.queue.wait_ms` (histogram, attrs: `openclaw.lane`) +- `openclaw.session.state` (counter, attrs: `openclaw.state`, `openclaw.reason`) +- `openclaw.session.stuck` (counter, attrs: `openclaw.state`) +- `openclaw.session.stuck_age_ms` (histogram, attrs: `openclaw.state`) +- `openclaw.run.attempt` (counter, attrs: `openclaw.attempt`) -Виконання: +Exec: -- `openclaw.exec.duration_ms` (гістограма, атрибути: `openclaw.exec.target`, +- `openclaw.exec.duration_ms` (histogram, attrs: `openclaw.exec.target`, `openclaw.exec.mode`, `openclaw.outcome`, `openclaw.failureKind`) +Внутрішні компоненти діагностики (пам’ять + цикл інструментів): + +- `openclaw.memory.heap_used_bytes` (histogram, attrs: `openclaw.memory.kind`) +- `openclaw.memory.rss_bytes` (histogram) +- `openclaw.memory.pressure` (counter, attrs: `openclaw.memory.level`) +- `openclaw.tool.loop.iterations` (counter, attrs: `openclaw.toolName`, + `openclaw.outcome`) +- `openclaw.tool.loop.duration_ms` (histogram, attrs: `openclaw.toolName`, + `openclaw.outcome`) + ### Експортовані spans (назви + ключові атрибути) - `openclaw.model.usage` @@ -383,7 +390,9 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload - `openclaw.model.call` - `gen_ai.system`, `gen_ai.request.model`, `gen_ai.operation.name`, `openclaw.provider`, `openclaw.model`, `openclaw.api`, - `openclaw.transport` + `openclaw.transport`, `openclaw.provider.request_id_hash` (обмежений + SHA-хеш ідентифікатора запиту до висхідного provider; необроблені id не + експортуються) - `openclaw.tool.execution` - `gen_ai.tool.name`, `openclaw.toolName`, `openclaw.errorCategory`, `openclaw.tool.params.*` @@ -404,6 +413,16 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload `openclaw.errorCategory`, `openclaw.delivery.result_count` - `openclaw.session.stuck` - `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth` +- `openclaw.context.assembled` + - `openclaw.prompt.size`, `openclaw.history.size`, + `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту prompt, + history, response або ключа сеансу) +- `openclaw.tool.loop` + - `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, + `openclaw.errorCategory` (без повідомлень циклу, параметрів або виводу інструмента) +- `openclaw.memory.pressure` + - `openclaw.memory.level`, `openclaw.memory.heap_used_bytes`, + `openclaw.memory.rss_bytes` Коли захоплення вмісту явно ввімкнено, spans моделей/інструментів також можуть містити обмежені, відредаговані атрибути `openclaw.content.*` для конкретних класів вмісту, @@ -411,34 +430,34 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload ### Семплювання + скидання -- Семплювання трасувань: `diagnostics.otel.sampleRate` (0.0–1.0, лише кореневі spans). +- Семплювання трасувань: `diagnostics.otel.sampleRate` (0.0–1.0, лише root spans). - Інтервал експорту метрик: `diagnostics.otel.flushIntervalMs` (мінімум 1000 мс). ### Примітки щодо протоколу -- Кінцеві точки OTLP/HTTP можна встановити через `diagnostics.otel.endpoint` або +- Кінцеві точки OTLP/HTTP можна задавати через `diagnostics.otel.endpoint` або `OTEL_EXPORTER_OTLP_ENDPOINT`. - Якщо кінцева точка вже містить `/v1/traces` або `/v1/metrics`, вона використовується як є. - Якщо кінцева точка вже містить `/v1/logs`, вона використовується як є для журналів. - `OPENCLAW_OTEL_PRELOADED=1` повторно використовує зовнішньо зареєстрований SDK OpenTelemetry - для трасувань/метрик замість запуску NodeSDK, яким керує Plugin. -- `diagnostics.otel.logs` вмикає експорт журналів OTLP для виводу основного журналювальника. + для трасувань/метрик замість запуску NodeSDK, що належить plugin-у. +- `diagnostics.otel.logs` вмикає експорт журналів OTLP для виведення основного логера. ### Поведінка експорту журналів - Журнали OTLP використовують ті самі структуровані записи, що записуються в `logging.file`. -- Враховується `logging.level` (рівень журналів у файлах). Редагування консолі **не** застосовується +- Дотримуються `logging.level` (рівень файлового журналу). Редагування консолі **не** застосовується до журналів OTLP. -- Для інсталяцій із великим обсягом даних слід віддавати перевагу семплюванню/фільтрації на боці колектора OTLP. +- Для інсталяцій із великим обсягом даних краще використовувати семплювання/фільтрацію на рівні OTLP collector. -## Поради з усунення неполадок +## Поради з усунення несправностей -- **Gateway недоступний?** Спочатку запустіть `openclaw doctor`. -- **Журнали порожні?** Перевірте, що Gateway запущений і записує у шлях файлу, - указаний у `logging.file`. -- **Потрібно більше деталей?** Установіть `logging.level` на `debug` або `trace` і повторіть спробу. +- **Gateway недоступний?** Спочатку виконайте `openclaw doctor`. +- **Журнали порожні?** Перевірте, що Gateway запущений і записує у шлях до файлу, + вказаний у `logging.file`. +- **Потрібно більше деталей?** Установіть `logging.level` у `debug` або `trace` і повторіть спробу. -## Пов’язані матеріали +## Пов’язане -- [Внутрішня реалізація журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі +- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі - [Діагностика](/uk/gateway/configuration-reference#diagnostics) — експорт OpenTelemetry і конфігурація трасування кешу diff --git a/docs/uk/plugins/architecture-internals.md b/docs/uk/plugins/architecture-internals.md index dd42f16d1..69377a78a 100644 --- a/docs/uk/plugins/architecture-internals.md +++ b/docs/uk/plugins/architecture-internals.md @@ -2,49 +2,49 @@ read_when: - Реалізація хуків середовища виконання провайдера, життєвого циклу каналу або пакетних наборів - Налагодження порядку завантаження plugin або стану реєстру - - Додавання нової можливості plugin або plugin рушія контексту + - Додавання нової можливості Plugin або plugin рушія контексту summary: 'Внутрішні аспекти архітектури Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці' title: Внутрішні аспекти архітектури Plugin x-i18n: - generated_at: "2026-04-24T20:18:23Z" + generated_at: "2026-04-25T18:41:27Z" model: gpt-5.4 provider: openai - source_hash: 0e505155ee2acc84f7f26fa81b62121f03a998b249886d74f798c0f258bd8da4 + source_hash: 074b0a0fb1678b73a2c9236fb9fbc208d8e39dcbba39c904b2bd7b5ceac473b6 source_path: plugins/architecture-internals.md workflow: 15 --- -Для загальнодоступної моделі можливостей, форм plugin, а також контрактів -володіння/виконання див. [Plugin architecture](/uk/plugins/architecture). Ця сторінка — -довідник щодо внутрішньої механіки: конвеєра завантаження, реєстру, хуків середовища виконання, +Щоб дізнатися про публічну модель можливостей, форми plugin, а також контракти +власності/виконання, див. [Plugin architecture](/uk/plugins/architecture). Ця сторінка є +довідником щодо внутрішньої механіки: конвеєра завантаження, реєстру, хуків середовища виконання, HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем. ## Конвеєр завантаження Під час запуску OpenClaw приблизно виконує таке: -1. виявляє корені кандидатів plugin +1. виявляє кореневі каталоги потенційних plugin 2. зчитує маніфести нативних або сумісних збірок і метадані пакетів -3. відхиляє небезпечних кандидатів +3. відхиляє небезпечні кандидати 4. нормалізує конфігурацію plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. визначає, чи увімкнено кожного кандидата -6. завантажує увімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач; +5. визначає, чи ввімкнено кожного кандидата +6. завантажує ввімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач; незібрані нативні plugin використовують jiti 7. викликає нативні хуки `register(api)` і збирає реєстрації до реєстру plugin -8. надає реєстр поверхням команд/середовища виконання +8. надає реєстр командам/поверхням середовища виконання -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає його в тій самій точці. Усі вбудовані plugin використовують `register`; для нових plugin надавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані plugin використовують `register`; для нових plugin віддавайте перевагу `register`. Перевірки безпеки відбуваються **до** виконання в середовищі виконання. Кандидати блокуються, -коли точка входу виходить за межі кореня plugin, шлях доступний для запису всім, або -володіння шляхом виглядає підозрілим для невбудованих plugin. +коли точка входу виходить за межі кореня plugin, шлях має права на запис для всіх, або +власність шляху виглядає підозріло для невбудованих plugin. ### Поведінка з пріоритетом маніфесту -Маніфест — це джерело істини для control plane. OpenClaw використовує його, щоб: +Маніфест є джерелом істини для контрольної площини. OpenClaw використовує його, щоб: - ідентифікувати plugin - виявляти оголошені канали/Skills/схему конфігурації або можливості збірки @@ -53,41 +53,41 @@ HTTP-маршрутів Gateway, шляхів імпорту та таблиць - показувати метадані встановлення/каталогу - зберігати дешеві дескриптори активації та налаштування без завантаження середовища виконання plugin -Для нативних plugin модуль середовища виконання є частиною data plane. Він реєструє +Для нативних plugin модуль середовища виконання є частиною площини даних. Він реєструє фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера. -Необов’язкові блоки маніфесту `activation` і `setup` залишаються в control plane. -Це дескриптори лише з метаданими для планування активації та виявлення налаштування; +Необов’язкові блоки маніфесту `activation` і `setup` залишаються в контрольній площині. +Це лише дескриптори метаданих для планування активації та виявлення налаштування; вони не замінюють реєстрацію в середовищі виконання, `register(...)` або `setupEntry`. -Перші активні споживачі активації тепер використовують підказки маніфесту щодо команд, каналів і провайдерів, +Перші споживачі живої активації тепер використовують підказки маніфесту щодо команд, каналів і провайдерів, щоб звузити завантаження plugin до ширшої матеріалізації реєстру: -- завантаження CLI звужується до plugin, які володіють запитаною основною командою -- налаштування каналу/визначення plugin звужується до plugin, які володіють запитаним - ідентифікатором каналу -- явне визначення налаштування/середовища виконання провайдера звужується до plugin, які володіють - запитаним ідентифікатором провайдера +- завантаження CLI звужується до plugin, яким належить запитана основна команда +- налаштування каналу/визначення plugin звужується до plugin, яким належить запитаний + id каналу +- явне визначення налаштування/середовища виконання провайдера звужується до plugin, яким належить + запитаний id провайдера -Планувальник активації надає як API лише з ідентифікаторами для наявних викликів, так і -API плану для нової діагностики. Записи плану повідомляють, чому plugin було вибрано, +Планувальник активації надає як API лише для id для наявних викликачів, так і +API плану для нової діагностики. Записи плану повідомляють, чому було вибрано plugin, відокремлюючи явні підказки планувальника `activation.*` від резервного -володіння за маніфестом, такого як `providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і хуки. Цей поділ причин є межею сумісності: -наявні метадані plugin і далі працюють, водночас новий код може виявляти широкі підказки -або резервну поведінку без зміни семантики завантаження середовища виконання. +визначення власності через маніфест, такого як `providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і хуки. Це розділення причин є межею сумісності: +наявні метадані plugin і далі працюють, тоді як новий код може виявляти широкі підказки +або резервну поведінку без зміни семантики завантаження в середовищі виконання. -Виявлення налаштування тепер надає перевагу ідентифікаторам, якими володіє дескриптор, таким як `setup.providers` і -`setup.cliBackends`, щоб звузити кандидатів plugin до того, як воно повернеться до -`setup-api` для plugin, яким усе ще потрібні хуки середовища виконання під час налаштування. Потік +Виявлення налаштування тепер надає перевагу id, якими володіють дескриптори, як-от `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. +для сумісності повертається до варіантів майстра середовища виконання та варіантів каталогу встановлення. Явне +`setup.requiresRuntime: false` є межею лише для дескриптора; пропущений +`requiresRuntime` зберігає застарілий резервний варіант `setup-api` для сумісності. Якщо більше +ніж один виявлений plugin заявляє права на той самий нормалізований id провайдера налаштування або +backend CLI, пошук налаштування відмовляється від неоднозначного власника замість покладання на +порядок виявлення. Коли середовище виконання налаштування все ж виконується, діагностика реєстру повідомляє +про розбіжності між `setup.providers` / `setup.cliBackends` і провайдерами або backend CLI, +зареєстрованими через setup-api, не блокуючи застарілі plugin. ### Що кешує завантажувач @@ -97,26 +97,26 @@ OpenClaw зберігає короткочасні внутрішньопроц - даних реєстру маніфестів - завантажених реєстрів 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 (ідентичність, джерело, походження, стан, діагностика) - інструменти -- застарілі хуки й типізовані хуки +- застарілі хуки та типізовані хуки - канали - провайдерів - обробники Gateway RPC @@ -125,20 +125,20 @@ OpenClaw зберігає короткочасні внутрішньопроц - фонові служби - команди, що належать plugin -Потім можливості ядра читають із цього реєстру замість прямої взаємодії з модулями plugin. -Це підтримує одностороннє завантаження: +Потім функції ядра читають з цього реєстру замість прямої взаємодії з модулями plugin. +Це робить завантаження односпрямованим: - модуль plugin -> реєстрація в реєстрі - середовище виконання ядра -> споживання реєстру -Це розділення важливе для супроводу. Воно означає, що більшості поверхонь ядра потрібна -лише одна точка інтеграції: «читати реєстр», а не «створювати окрему логіку для кожного модуля plugin». +Це розділення важливе для супроводу. Воно означає, що більшості поверхонь ядра потрібна лише +одна точка інтеграції: «читати реєстр», а не «робити спеціальні випадки для кожного модуля plugin». -## Колбеки прив’язки розмови +## Зворотні виклики прив’язування розмови -Plugin, які прив’язують розмову, можуть реагувати, коли погодження вирішено. +Plugin, які прив’язують розмову, можуть реагувати, коли затвердження вирішено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек після того, як запит на прив’язку буде схвалено або відхилено: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, як запит на прив’язування буде схвалено або відхилено: ```ts export default { @@ -146,127 +146,127 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // Тепер для цього plugin + розмови існує прив’язка. + // A binding now exists for this plugin + conversation. 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`: початковий підсумок запиту, підказка від’єднання, ідентифікатор відправника та +- `binding`: вирішене прив’язування для схвалених запитів +- `request`: підсумок початкового запиту, підказка від’єднання, id відправника та метадані розмови -Цей колбек призначений лише для сповіщення. Він не змінює те, кому дозволено прив’язувати -розмову, і виконується після завершення обробки погодження в ядрі. +Цей зворотний виклик призначений лише для сповіщення. Він не змінює, хто має право прив’язувати +розмову, і виконується після завершення обробки схвалення ядром. ## Хуки середовища виконання провайдера -Plugin провайдера мають три шари: +Plugin провайдерів мають три рівні: -- **Метадані маніфесту** для дешевого пошуку до запуску середовища виконання: - `setup.providers[].envVars`, застарілий сумісний `providerAuthEnvVars`, +- **Метадані маніфесту** для дешевого пошуку до середовища виконання: + `setup.providers[].envVars`, застарілий сумісний варіант `providerAuthEnvVars`, `providerAuthAliases`, `providerAuthChoices` і `channelEnvVars`. - **Хуки часу конфігурації**: `catalog` (застарілий `discovery`) плюс `applyConfigDefaults`. -- **Хуки середовища виконання**: понад 40 необов’язкових хуків, що охоплюють автентифікацію, визначення моделей, - обгортання потоків, рівні thinking, політику відтворення та кінцеві точки використання. Див. - повний список у розділі [Порядок і використання хуків](#hook-order-and-usage). +- **Хуки середовища виконання**: понад 40 необов’язкових хуків для auth, визначення моделі, + обгортання потоку, рівнів thinking, політики повтору та кінцевих точок використання. Див. + повний список у [Порядок і використання хуків](#hook-order-and-usage). -OpenClaw, як і раніше, володіє загальним циклом агента, failover, обробкою транскриптів і +OpenClaw і далі володіє загальним циклом агента, failover, обробкою транскрипту та політикою інструментів. Ці хуки є поверхнею розширення для поведінки, специфічної для провайдера, -без потреби в цілому користувацькому транспорті інференсу. +без потреби у повністю власному транспорті inference. -Використовуйте маніфест `setup.providers[].envVars`, коли провайдер має облікові дані на основі змінних середовища, які повинні бути видимими для загальних шляхів автентифікації/стану/вибору моделі без -завантаження середовища виконання plugin. Застарілий `providerAuthEnvVars` усе ще зчитується -адаптером сумісності протягом вікна застарівання, а невбудовані plugin, які його використовують, -отримують діагностику маніфесту. Використовуйте маніфест `providerAuthAliases`, коли один -ідентифікатор провайдера має повторно використовувати env vars, профілі автентифікації, -автентифікацію на основі конфігурації та варіант онбордингу з API-ключем іншого ідентифікатора провайдера. Використовуйте маніфест -`providerAuthChoices`, коли поверхні CLI онбордингу/вибору автентифікації повинні знати -ідентифікатор вибору провайдера, мітки групи та просте підключення автентифікації одним прапорцем без -завантаження середовища виконання провайдера. Залишайте `envVars` у середовищі виконання провайдера -для підказок, орієнтованих на операторів, таких як мітки онбордингу або змінні налаштування -client-id/client-secret OAuth. +Використовуйте маніфест `setup.providers[].envVars`, коли провайдер має облікові дані на основі env, які +загальні шляхи auth/status/вибору моделі повинні бачити без завантаження середовища виконання plugin. Застарілий +`providerAuthEnvVars` усе ще зчитується адаптером сумісності під час вікна +депрецiації, і невбудовані plugin, які його використовують, отримують діагностику маніфесту. Використовуйте маніфест `providerAuthAliases`, коли один id провайдера має +повторно використовувати env vars, auth-профілі, auth на основі конфігурації та варіант +онбордингу API-ключа іншого id провайдера. Використовуйте маніфест +`providerAuthChoices`, коли поверхні CLI для онбордингу/вибору auth повинні знати +про id вибору провайдера, мітки груп і просте налаштування auth з одним прапорцем без +завантаження середовища виконання провайдера. Залишайте в середовищі виконання провайдера +`envVars` для підказок, орієнтованих на операторів, таких як мітки онбордингу або змінні налаштування +ідентифікатора/секрета клієнта OAuth. -Використовуйте маніфест `channelEnvVars`, коли канал має автентифікацію або налаштування, керовані env, -які повинні бути видимими загальному резервному шляху shell-env, перевіркам config/status або підказкам налаштування +Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування, керовані env, які +загальний резервний варіант shell-env, перевірки config/status або підказки налаштування повинні бачити без завантаження середовища виконання каналу. ### Порядок і використання хуків -Для plugin моделі/провайдера OpenClaw викликає хуки приблизно в такому порядку. -Стовпець «Коли використовувати» — це короткий посібник для вибору. +Для plugin моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку. +Стовпець «Коли використовувати» є коротким довідником для вибору. -| # | Хук | Що він робить | Коли використовувати | +| # | Хук | Що він робить | Коли використовувати | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями base URL | -| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму автентифікації, env або семантики сімейства моделей провайдера | -| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(не хук plugin)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним визначенням моделі | -| 4 | `normalizeTransport` | Нормалізує сімейство провайдера `api` / `baseUrl` перед загальним складанням моделі | Провайдер володіє очищенням транспорту для користувацьких ідентифікаторів провайдера в тому самому сімействі транспорту | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням середовища виконання/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із plugin; вбудовані помічники сімейства Google також страхують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування використання нативного потокового режиму до конфігурованих провайдерів | Провайдеру потрібні виправлення метаданих використання нативного потокового режиму, що залежать від кінцевої точки | -| 7 | `resolveConfigApiKey` | Визначає автентифікацію через env-marker для конфігурованих провайдерів до завантаження автентифікації середовища виконання | Провайдер має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований AWS-розпізнавач env-marker | -| 8 | `resolveSyntheticAuth` | Показує локальну/self-hosted або засновану на конфігурації автентифікацію без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | -| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, що належать провайдеру; типове значення `persistence` — `runtime-only` для облікових даних, що належать CLI/застосунку | Провайдер повторно використовує зовнішні облікові дані автентифікації без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті | -| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілю порівняно з автентифікацією на основі env/конфігурації | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет | -| 11 | `resolveDynamicModel` | Синхронний резервний шлях для model id, що належать провайдеру, яких ще немає в локальному реєстрі | Провайдер приймає довільні ідентифікатори моделей верхнього рівня | -| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих ідентифікаторів | -| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як вбудований раннер використає визначену модель | Провайдеру потрібні переписування транспорту, але він і далі використовує транспорт ядра | -| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для моделей вендора за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспортах, не перехоплюючи керування провайдером | -| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру та використовуються спільною логікою ядра | Провайдеру потрібні особливості транскрипту/сімейства провайдера | -| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований раннер | Провайдеру потрібне очищення схем для сімейства транспорту | -| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження щодо ключових слів без навчання ядра правилам, специфічним для провайдера | -| 18 | `resolveReasoningOutputMode` | Вибирає нативний або тегований контракт виводу reasoning | Провайдеру потрібен тегований reasoning/фінальний вивід замість нативних полів | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдеру потрібен користувацький wire protocol, а не просто обгортка | -| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки заголовків/тіла запиту/сумісності моделі без користувацького транспорту | -| 22 | `resolveTransportTurnState` | Додає нативні заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали нативну для провайдера ідентичність ходу | -| 23 | `resolveWebSocketSessionPolicy` | Додає нативні заголовки WebSocket або політику cool-down сеансу | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сеансу або резервну політику | -| 24 | `formatApiKey` | Форматувальник профілю автентифікації: збережений профіль стає рядком `apiKey` у середовищі виконання | Провайдер зберігає додаткові метадані автентифікації й потребує користувацької форми токена для середовища виконання | -| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких кінцевих точок оновлення або політики збоїв оновлення | Провайдер не відповідає спільним механізмам оновлення `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка для виправлення, що додається, коли не вдається оновлення OAuth | Провайдеру потрібна власна підказка щодо відновлення автентифікації після збою оновлення | -| 27 | `matchesContextOverflowError` | Власний для провайдера розпізнавач переповнення вікна контексту | Провайдер має сирі помилки переповнення, які загальні евристики не виявлять | -| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з обмеженням швидкості/перевантаженням тощо | -| 29 | `isCacheTtlEligible` | Політика prompt-cache для провайдерів proxy/backhaul | Провайдеру потрібне керування TTL кешу, специфічне для proxy | -| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення про відсутню автентифікацію | Провайдеру потрібна власна підказка щодо відновлення при відсутній автентифікації | -| 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` | Розпізнавач modern-model для фільтрів live profile і вибору smoke | Провайдер володіє зіставленням бажаної моделі для live/smoke | -| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед інференсом | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | -| 39 | `resolveUsageAuth` | Визначає облікові дані використання/білінгу для `/usage` і пов’язаних поверхонь статусу | Провайдеру потрібен користувацький розбір токена використання/квоти або інші облікові дані використання | -| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки використання/квоти, специфічні для провайдера, після визначення автентифікації | Провайдеру потрібна специфічна для провайдера кінцева точка використання або парсер корисного навантаження | -| 41 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті належить plugin провайдера | -| 42 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна користувацька політика транскрипту (наприклад, видалення блоків thinking) | -| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні специфічні для провайдера переписування replay понад спільні помічники Compaction | -| 44 | `validateReplayTurns` | Остаточна перевірка або переформування ходів replay перед вбудованим раннером | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санітизації | -| 45 | `onModelSelected` | Виконує побічні ефекти після вибору, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | +| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями `base URL` | +| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму auth, env або семантики сімейства моделей провайдера | +| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(це не хук plugin)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми `model-id` перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним визначенням моделі | +| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для власних id провайдера в межах того самого сімейства транспорту | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням конфігурації/провайдера в середовищі виконання | Провайдеру потрібне очищення конфігурації, яке має жити разом із plugin; вбудовані допоміжні засоби сімейства Google також страхують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування нативного використання потокової передачі до конфігурованих провайдерів | Провайдеру потрібні виправлення метаданих нативного використання потокової передачі, керовані кінцевою точкою | +| 7 | `resolveConfigApiKey` | Визначає auth маркера env для конфігурованих провайдерів перед завантаженням auth у середовищі виконання | Провайдер має власне визначення API-ключа маркера env; `amazon-bedrock` також має тут вбудований AWS-визначник маркера env | +| 8 | `resolveSyntheticAuth` | Відображає локальний/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | +| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth-профілі, що належать провайдеру; типове значення `persistence` — `runtime-only` для облікових даних, що належать CLI/застосунку | Провайдер повторно використовує зовнішні auth-облікові дані без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті | +| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених заповнювачів синтетичного профілю відносно auth на основі env/конфігурації | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет | +| 11 | `resolveDynamicModel` | Синхронний резервний варіант для model id, що належать провайдеру, але яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream id моделей | +| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | +| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як вбудований виконавець використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра | +| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для vendor-моделей за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспортах, не перебираючи на себе керування провайдером | +| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру, і використовуються спільною логікою ядра | Провайдеру потрібні особливості транскрипту/сімейства провайдера | +| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить вбудований виконавець | Провайдеру потрібне очищення схем для сімейства транспорту | +| 17 | `inspectToolSchemas` | Відображає діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження про ключові слова без навчання ядра правилам, специфічним для провайдера | +| 18 | `resolveReasoningOutputMode` | Вибирає нативний чи тегований контракт виводу reasoning | Провайдеру потрібен тегований reasoning/фінальний вивід замість нативних полів | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдеру потрібен власний wire protocol, а не просто обгортка | +| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності заголовків/тіла/моделі запиту без власного транспорту | +| 22 | `resolveTransportTurnState` | Додає нативні заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали нативну для провайдера ідентичність ходу | +| 23 | `resolveWebSocketSessionPolicy` | Додає нативні заголовки WebSocket або політику затримки session | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки session або політику резервного варіанта | +| 24 | `formatApiKey` | Форматувач auth-профілю: збережений профіль стає рядком `apiKey` середовища виконання | Провайдер зберігає додаткові auth-метадані й потребує власної форми токена для середовища виконання | +| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких кінцевих точок оновлення або політики збоїв оновлення | Провайдер не відповідає спільним механізмам оновлення `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка з виправлення, яка додається, коли оновлення OAuth завершується збоєм | Провайдеру потрібні власні рекомендації з виправлення auth після збою оновлення | +| 27 | `matchesContextOverflowError` | Власний засіб зіставлення переповнення контекстного вікна для провайдера | Провайдер має сирі помилки переповнення, які загальні евристики не виявлять | +| 28 | `classifyFailoverReason` | Власна класифікація причин failover для провайдера | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/перевантаженням тощо | +| 29 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для проксі | +| 30 | `buildMissingAuthMessage` | Заміна для загального повідомлення про відновлення у разі відсутнього auth | Провайдеру потрібна власна підказка відновлення у разі відсутнього auth | +| 31 | `suppressBuiltInModel` | Пригнічення застарілої upstream-моделі плюс необов’язкова користувацька підказка про помилку | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх vendor-підказкою | +| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, що додаються після виявлення | Провайдеру потрібні синтетичні рядки для прямої сумісності в майбутньому в `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` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед inference | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | +| 39 | `resolveUsageAuth` | Визначає облікові дані використання/білінгу для `/usage` і пов’язаних поверхонь стану | Провайдеру потрібен користувацький розбір токена використання/квоти або інші облікові дані використання | +| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки використання/квоти, специфічні для провайдера, після визначення auth | Провайдеру потрібна кінцева точка використання або парсер корисного навантаження, специфічні для провайдера | +| 41 | `createEmbeddingProvider` | Створює адаптер ембедингів, що належить провайдеру, для пам’яті/пошуку | Поведінка memory-ембедингів має належати plugin провайдера | +| 42 | `buildReplayPolicy` | Повертає політику повтору, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна користувацька політика транскрипту (наприклад, вилучення блоків thinking) | +| 43 | `sanitizeReplayHistory` | Переписує історію повтору після загального очищення транскрипту | Провайдеру потрібні переписування повтору, специфічні для провайдера, понад спільні допоміжні засоби Compaction | +| 44 | `validateReplayTurns` | Остаточна перевірка або переформування ходів повтору перед вбудованим виконавцем | Транспорту провайдера потрібна суворіша перевірка ходів після загального очищення | +| 45 | `onModelSelected` | Виконує побічні ефекти після вибору, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -відповідний plugin провайдера, а потім переходять до інших plugin провайдерів, що підтримують хуки, -доки один із них фактично не змінить id моделі або transport/config. Це дозволяє -працювати shim-плагінам для псевдонімів/сумісності провайдерів без потреби, щоб викликач знав, який -саме вбудований plugin володіє цим переписуванням. Якщо жоден хук провайдера не переписує підтримуваний -запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно застосує -це очищення для сумісності. +відповідний plugin провайдера, а потім переходять до інших plugin провайдерів, які підтримують хуки, +доки один із них справді не змінить id моделі або транспорт/конфігурацію. Це дозволяє +працювати shim-провайдерам для псевдонімів/сумісності без потреби, щоб викликач знав, який +вбудований plugin володіє цим переписуванням. Якщо жоден хук провайдера не перепише підтримуваний +запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google усе одно застосує +це очищення сумісності. -Якщо провайдеру потрібен повністю користувацький wire protocol або користувацький виконавець запитів, -це вже інший клас розширення. Ці хуки призначені для поведінки провайдера, яка все ще -працює в межах звичайного циклу інференсу OpenClaw. +Якщо провайдеру потрібен повністю власний wire protocol або власний виконавець запитів, +це інший клас розширення. Ці хуки призначені для поведінки провайдера, яка +все ще працює в межах звичайного циклу inference OpenClaw. ### Приклад провайдера @@ -324,36 +324,36 @@ api.registerProvider({ ### Вбудовані приклади -Вбудовані plugin провайдерів поєднують наведені вище хуки, щоб відповідати потребам кожного вендора щодо каталогу, -автентифікації, thinking, replay і використання. Авторитетний набір хуків живе разом -із кожним plugin у `extensions/`; ця сторінка ілюструє форми, а не -дзеркалить список. +Вбудовані plugin провайдерів поєднують наведені вище хуки відповідно до потреб +кожного постачальника щодо каталогу, auth, thinking, повтору та використання. Авторитетний набір хуків +зберігається в кожному plugin у `extensions/`; ця сторінка ілюструє форми, а не +дзеркально відтворює список. - + OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` разом із - `resolveDynamicModel` / `prepareDynamicModel`, щоб показувати верхньорівневі + `resolveDynamicModel` / `prepareDynamicModel`, щоб відображати upstream id моделей раніше за статичний каталог OpenClaw. GitHub Copilot, Gemini CLI, ChatGPT Codex, MiniMax, Xiaomi, z.ai поєднують `prepareRuntimeAuth` або `formatApiKey` з `resolveUsageAuth` + - `fetchUsageSnapshot`, щоб керувати обміном токенів і інтеграцією `/usage`. + `fetchUsageSnapshot`, щоб керувати обміном токенів та інтеграцією `/usage`. - + Спільні іменовані сімейства (`google-gemini`, `passthrough-gemini`, - `anthropic-by-model`, `hybrid-anthropic-openai`) дають змогу провайдерам - підключатися до політики транскрипту через `buildReplayPolicy` замість того, щоб кожен plugin - повторно реалізовував очищення. + `anthropic-by-model`, `hybrid-anthropic-openai`) дозволяють провайдерам + підключати політику транскрипту через `buildReplayPolicy` замість того, щоб + кожен plugin наново реалізовував очищення. `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і - `volcengine` реєструють лише `catalog` і працюють на спільному циклі інференсу. + `volcengine` реєструють лише `catalog` і використовують спільний цикл inference. - Бета-заголовки, `/fast` / `serviceTier` і `context1m` живуть усередині - публічного шва `api.ts` / `contract-api.ts` plugin Anthropic + Бета-заголовки, `/fast` / `serviceTier` і `context1m` знаходяться в + публічному шві `api.ts` / `contract-api.ts` plugin Anthropic (`wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`), а не в загальному SDK. @@ -385,9 +385,9 @@ const voices = await api.runtime.tts.listVoices({ - `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових нотаток. - Використовує конфігурацію ядра `messages.tts` і вибір провайдера. -- Повертає буфер PCM-аудіо + частоту дискретизації. Plugin мають виконувати ресемплінг/кодування для провайдерів. -- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу, що належать вендору, або для потоків налаштування. -- Списки голосів можуть містити багатші метадані, як-от locale, gender і теги personality для засобів вибору, обізнаних про провайдера. +- Повертає PCM-буфер аудіо + частоту дискретизації. Plugin мають виконувати ресемплінг/кодування для провайдерів. +- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать постачальнику. +- Списки голосів можуть містити багатші метадані, як-от локаль, стать і теги особистості для засобів вибору, обізнаних про провайдера. - OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. Plugin також можуть реєструвати мовленнєвих провайдерів через `api.registerSpeechProvider(...)`. @@ -410,15 +410,15 @@ api.registerSpeechProvider({ Примітки: -- Зберігайте політику TTS, резервний перехід і доставку відповіді в ядрі. -- Використовуйте мовленнєвих провайдерів для поведінки синтезу, що належить вендору. -- Застарілий вхід Microsoft `edge` нормалізується до ідентифікатора провайдера `microsoft`. -- Бажана модель володіння орієнтована на компанію: один plugin вендора може володіти - текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами, коли OpenClaw додаватиме ці - контракти можливостей. +- Зберігайте політику TTS, резервний варіант і доставку відповіді в ядрі. +- Використовуйте мовленнєвих провайдерів для поведінки синтезу, що належить постачальнику. +- Застаріле значення `edge` для Microsoft нормалізується до id провайдера `microsoft`. +- Бажана модель володіння орієнтована на компанію: один plugin постачальника може + володіти текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами в міру того, + як OpenClaw додає ці контракти можливостей. Для розуміння зображень/аудіо/відео plugin реєструють одного типізованого -провайдера розуміння медіа замість універсального мішка ключ/значення: +провайдера розуміння медіа замість загального сховища ключ/значення: ```ts api.registerMediaUnderstandingProvider({ @@ -432,14 +432,14 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Зберігайте оркестрацію, резервний перехід, конфігурацію та прив’язку каналу в ядрі. -- Зберігайте поведінку вендора в plugin провайдера. +- Зберігайте оркестрацію, резервний варіант, конфігурацію та зв’язування каналів у ядрі. +- Зберігайте поведінку постачальника в plugin провайдера. - Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові поля результату, нові необов’язкові можливості. -- Генерація відео вже дотримується того самого шаблону: +- Генерація відео вже дотримується тієї самої схеми: - ядро володіє контрактом можливості та допоміжним засобом середовища виконання - - plugin вендора реєструють `api.registerVideoGenerationProvider(...)` - - plugin можливостей/каналів споживають `api.runtime.videoGeneration.*` + - plugin постачальника реєструють `api.registerVideoGenerationProvider(...)` + - feature/channel plugin споживають `api.runtime.videoGeneration.*` Для допоміжних засобів середовища виконання розуміння медіа plugin можуть викликати: @@ -456,14 +456,14 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрибування аудіо plugin можуть використовувати або середовище виконання -розуміння медіа, або старіший псевдонім STT: +Для транскрибування аудіо plugin можуть використовувати або середовище виконання розуміння медіа, +або старіший псевдонім STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Необов’язково, коли MIME не можна надійно визначити: + // Optional when MIME cannot be inferred reliably: mime: "audio/ogg", }); ``` @@ -472,11 +472,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ - `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для розуміння зображень/аудіо/відео. -- Використовує конфігурацію аудіо розуміння медіа ядра (`tools.media.audio`) і порядок резервного вибору провайдера. -- Повертає `{ text: undefined }`, коли вихід транскрибування не створено (наприклад, для пропущеного/непідтримуваного вводу). -- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності. +- Використовує конфігурацію аудіо розуміння медіа ядра (`tools.media.audio`) і порядок резервних провайдерів. +- Повертає `{ text: undefined }`, коли вивід транскрибування не створюється (наприклад, для пропущеного/непідтримуваного вводу). +- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом сумісності. -Plugin також можуть запускати фонові виконання субагента через `api.runtime.subagent`: +Plugin також можуть запускати фонові виконання subagent через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -490,14 +490,14 @@ const result = await api.runtime.subagent.run({ Примітки: -- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. +- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сеансу. - OpenClaw враховує ці поля перевизначення лише для довірених викликачів. - Для резервних запусків, що належать plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. - Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugin конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. -- Запуски субагента з недовірених plugin усе ще працюють, але запити на перевизначення відхиляються замість тихого резервного переходу. +- Запуски subagent від недовірених plugin усе ще працюють, але запити на перевизначення відхиляються замість тихого переходу до резервного варіанта. Для вебпошуку plugin можуть використовувати спільний допоміжний засіб середовища виконання замість -звернення до прив’язки інструментів агента: +доступу до зв’язування інструментів агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -518,9 +518,9 @@ Plugin також можуть реєструвати провайдерів в Примітки: -- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у ядрі. -- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для вендора. -- `api.runtime.webSearch.*` — це бажана спільна поверхня для plugin можливостей/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструментів агента. +- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запиту в ядрі. +- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для постачальника. +- `api.runtime.webSearch.*` — це бажана спільна поверхня для feature/channel plugin, яким потрібна поведінка пошуку без залежності від обгортки інструментів агента. ### `api.runtime.imageGeneration` @@ -535,12 +535,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: створити зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. -- `listProviders(...)`: перелічити доступних провайдерів генерації зображень і їхні можливості. +- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. +- `listProviders(...)`: перелічує доступних провайдерів генерації зображень та їхні можливості. ## HTTP-маршрути Gateway -Plugin можуть відкривати HTTP-кінцеві точки за допомогою `api.registerHttpRoute(...)`. +Plugin можуть відкривати HTTP-ендпоїнти за допомогою `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -558,54 +558,54 @@ api.registerHttpRoute({ Поля маршруту: - `path`: шлях маршруту під HTTP-сервером gateway. -- `auth`: обов’язкове. Використовуйте `"gateway"` для звичайної автентифікації gateway або `"plugin"` для автентифікації/перевірки Webhook, якими керує plugin. -- `match`: необов’язкове. `"exact"` (типово) або `"prefix"`. -- `replaceExisting`: необов’язкове. Дозволяє тому самому plugin замінити власну наявну реєстрацію маршруту. +- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайний auth gateway, або `"plugin"` для auth/webhook-перевірки, якими керує plugin. +- `match`: необов’язкове поле. `"exact"` (типово) або `"prefix"`. +- `replaceExisting`: необов’язкове поле. Дозволяє тому самому plugin замінити власну наявну реєстрацію маршруту. - `handler`: повертайте `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` було видалено і воно спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`. +- `api.registerHttpHandler(...)` було видалено, і воно спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`. - Маршрути plugin мають явно оголошувати `auth`. -- Конфлікти точних `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin. -- Маршрути, що перекриваються, з різними рівнями `auth` відхиляються. Тримайте ланцюжки переходу `exact`/`prefix` fallthrough лише в межах одного рівня auth. -- Маршрути `auth: "plugin"` **не** отримують автоматично області доступу середовища виконання оператора. Вони призначені для Webhook/перевірки підпису, якими керує plugin, а не для привілейованих допоміжних викликів Gateway. -- Маршрути `auth: "gateway"` працюють усередині області середовища виконання запиту Gateway, але ця область навмисно консервативна: - - bearer-автентифікація зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області середовища виконання маршрутів plugin на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` - - довірені HTTP-режими з передачею ідентичності (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` у приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах до маршрутів plugin із передачею ідентичності, область середовища виконання повертається до `operator.write` -- Практичне правило: не припускайте, що маршрут plugin з gateway-auth є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим автентифікації з передачею ідентичності та задокументуйте явний контракт заголовка `x-openclaw-scopes`. +- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin. +- Перекривні маршрути з різними рівнями `auth` відхиляються. Ланцюжки переходу `exact`/`prefix` мають бути лише в межах одного рівня auth. +- Маршрути `auth: "plugin"` **не** отримують автоматично області runtime оператора. Вони призначені для webhook або перевірки підпису, якими керує plugin, а не для привілейованих допоміжних викликів Gateway. +- Маршрути `auth: "gateway"` працюють у межах області runtime запиту Gateway, але ця область навмисно є консервативною: + - bearer-auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області runtime маршрутів plugin зафіксованими на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` + - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` у приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах маршрутів plugin з ідентичністю, область runtime повертається до `operator.write` +- Практичне правило: не припускайте, що маршрут plugin із gateway-auth є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth із ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK -Під час створення нових plugin використовуйте вузькі підшляхи SDK замість монолітного -кореневого barrel `openclaw/plugin-sdk`. Основні підшляхи: +Використовуйте вузькі підшляхи SDK замість монолітного кореневого +barrel `openclaw/plugin-sdk` під час створення нових plugin. Основні підшляхи: -| Підшлях | Призначення | -| ---------------------------------- | -------------------------------------------------- | -| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації plugin | -| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/побудови каналу | -| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella contract | -| `openclaw/plugin-sdk/config-schema` | Коренева схема Zod `openclaw.json` (`OpenClawSchema`) | +| Підшлях | Призначення | +| ----------------------------------- | ------------------------------------------------------ | +| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації plugin | +| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/побудови каналу | +| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella-контракт | +| `openclaw/plugin-sdk/config-schema` | Коренева схема Zod для `openclaw.json` (`OpenClawSchema`) | -Plugin каналів обирають із сімейства вузьких швів — `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`, а не змішувати між не пов’язаними +`channel-targets` і `channel-actions`. Поведінка затвердження має консолідуватися +в одному контракті `approvalCapability`, а не змішуватися між не пов’язаними полями plugin. Див. [Channel plugins](/uk/plugins/sdk-channel-plugins). -Допоміжні засоби середовища виконання і конфігурації розміщені у відповідних підшляхах `*-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. Новий код має імпортувати натомість вужчі загальні примітиви. +старіших plugin. Новий код має імпортувати вужчі загальні примітиви. -Внутрішні для репозиторію точки входу (для кореня пакета кожного вбудованого plugin): +Внутрішні точки входу репозиторію (для кореня пакета кожного вбудованого plugin): - `index.js` — точка входу вбудованого plugin - `api.js` — barrel допоміжних засобів/типів @@ -614,57 +614,57 @@ Plugin каналів обирають із сімейства вузьких ш Зовнішні plugin мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи не імпортуйте `src/*` іншого пакета plugin з ядра або з іншого plugin. -Точки входу, завантажені через facade, надають перевагу активному знімку конфігурації середовища виконання, коли він є, -а потім повертаються до визначеного файлу конфігурації на диску. +Точки входу, завантажені через фасад, надають перевагу активному знімку конфігурації середовища виконання, якщо він +існує, а потім повертаються до визначеного файлу конфігурації на диску. -Підшляхи, специфічні для можливостей, як-от `image-generation`, `media-understanding` -і `speech`, існують, тому що вбудовані plugin уже використовують їх сьогодні. Вони не є -автоматично зовнішніми контрактами, остаточно зафіксованими на довгий строк — перевіряйте відповідну +Підшляхи для конкретних можливостей, такі як `image-generation`, `media-understanding` +і `speech`, існують, бо вбудовані plugin використовують їх уже сьогодні. Вони не є +автоматично довгостроково замороженими зовнішніми контрактами — перевіряйте відповідну довідкову сторінку SDK, коли покладаєтеся на них. ## Схеми інструментів повідомлень -Plugin мають володіти внесками до схем `describeMessageTool(...)`, специфічними для каналу, -для немовних примітивів, таких як реакції, прочитання і опитування. -Спільне подання надсилання має використовувати загальний контракт `MessagePresentation` -замість нативних для провайдера полів button, component, block або card. -Див. [Message Presentation](/uk/plugins/message-presentation) щодо контракту, -правил резервного переходу, зіставлення провайдерів і контрольного списку автора plugin. +Plugin мають володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу, +для немеседжевих примітивів, таких як реакції, прочитання та опитування. +Спільне представлення надсилання має використовувати загальний контракт `MessagePresentation`, +а не нативні для провайдера поля кнопок, компонентів, блоків або карток. +Див. [Message Presentation](/uk/plugins/message-presentation), щоб ознайомитися з контрактом, +правилами резервного варіанта, зіставленням провайдерів і контрольним списком автора plugin. -Plugin із можливістю надсилання оголошують, що вони можуть відтворювати, через можливості повідомлень: +Plugin, здатні до надсилання, оголошують, що вони можуть відтворювати, через можливості повідомлень: -- `presentation` для блоків семантичного подання (`text`, `context`, `divider`, `buttons`, `select`) -- `delivery-pin` для запитів pinned-delivery +- `presentation` для блоків семантичного представлення (`text`, `context`, `divider`, `buttons`, `select`) +- `delivery-pin` для запитів закріпленої доставки -Ядро вирішує, чи відтворювати подання нативно, чи деградувати його до тексту. -Не відкривайте нативні для провайдера шляхи обходу UI із загального інструмента повідомлень. -Застарілі допоміжні засоби SDK для старих нативних схем і далі експортуються для наявних +Ядро вирішує, чи відтворювати представлення нативно, чи деградувати його до тексту. +Не відкривайте нативні для провайдера обхідні шляхи UI із загального інструмента повідомлень. +Застарілі допоміжні засоби SDK для застарілих нативних схем залишаються експортованими для наявних сторонніх plugin, але нові plugin не повинні їх використовувати. -## Визначення цілей каналу +## Визначення цілі каналу -Plugin каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний -вихідний хост загальним і використовуйте поверхню адаптера повідомлень для правил провайдера: +Plugin каналів мають володіти семантикою цілі, специфічною для каналу. Зберігайте спільний +хост вихідних повідомлень загальним і використовуйте поверхню адаптера обміну повідомленнями для правил провайдера: -- `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль - слід трактувати як `direct`, `group` або `channel` до пошуку в каталозі. +- `messaging.inferTargetChatType({ to })` визначає, чи слід нормалізовану ціль + трактувати як `direct`, `group` або `channel` перед пошуком у каталозі. - `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи - вхідні дані слід одразу передати до визначення, подібного до id, замість пошуку в каталозі. -- `messaging.targetResolver.resolveTarget(...)` — це резервний шлях plugin, коли - ядру потрібне остаточне визначення, що належить провайдеру, після нормалізації або після - промаху в каталозі. -- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту - сеансу вихідних повідомлень, специфічною для провайдера, після визначення цілі. + слід вводу одразу перейти до визначення, подібного до id, замість пошуку в каталозі. +- `messaging.targetResolver.resolveTarget(...)` є резервним варіантом plugin, коли + ядру потрібно остаточне визначення, що належить провайдеру, після нормалізації або + після промаху в каталозі. +- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, специфічною для провайдера, + після того як ціль визначено. -Рекомендований поділ: +Рекомендований розподіл: -- Використовуйте `inferTargetChatType` для категорійних рішень, які мають відбутися до - пошуку peers/groups. -- Використовуйте `looksLikeId` для перевірок типу «сприймати це як явний/нативний id цілі». -- Використовуйте `resolveTarget` для резервної нормалізації, специфічної для провайдера, а не для +- Використовуйте `inferTargetChatType` для рішень щодо категорії, які мають відбуватися до + пошуку серед контактів/груп. +- Використовуйте `looksLikeId` для перевірок «трактувати це як явний/нативний id цілі». +- Використовуйте `resolveTarget` для резервного варіанта нормалізації, специфічного для провайдера, а не для широкого пошуку в каталозі. -- Зберігайте нативні для провайдера id, такі як chat id, thread id, JID, handle і room - id, усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK. +- Зберігайте нативні для провайдера id, такі як id чату, id потоку, JID, handle і id кімнати, + усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK. ## Каталоги на основі конфігурації @@ -672,25 +672,25 @@ Plugin, які виводять записи каталогу з конфігу plugin і повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, наприклад: +Використовуйте це, коли каналу потрібні контакти/групи на основі конфігурації, такі як: -- DM-peers, керовані allowlist -- налаштовані мапи каналів/груп +- контакти DM на основі allowlist +- налаштовані відповідності каналів/груп - статичні резервні варіанти каталогу в межах облікового запису Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: -- фільтрування запитів -- застосування обмежень -- допоміжні засоби дедуплікації/нормалізації -- побудову `ChannelDirectoryEntry[]` +- фільтрація запиту +- застосування ліміту +- усунення дублікатів/допоміжні засоби нормалізації +- побудова `ChannelDirectoryEntry[]` -Перевірка облікового запису і нормалізація id, специфічні для каналу, мають залишатися в +Перевірка облікового запису та нормалізація id, специфічні для каналу, мають залишатися в реалізації plugin. ## Каталоги провайдерів -Plugin провайдерів можуть визначати каталоги моделей для інференсу за допомогою +Plugin провайдерів можуть визначати каталоги моделей для inference за допомогою `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в @@ -699,53 +699,53 @@ Plugin провайдерів можуть визначати каталоги - `{ provider }` для одного запису провайдера - `{ providers }` для кількох записів провайдера -Використовуйте `catalog`, коли plugin володіє id моделей, специфічними для провайдера, типовими -значеннями base URL або метаданими моделей, захищеними автентифікацією. +Використовуйте `catalog`, коли plugin володіє model id, типовими значеннями base URL +або метаданими моделей, захищеними auth, специфічними для провайдера. -`catalog.order` керує тим, коли каталог plugin зливається відносно -вбудованих неявних провайдерів OpenClaw: +`catalog.order` керує тим, коли каталог plugin зливається відносно вбудованих +неявних провайдерів OpenClaw: - `simple`: звичайні провайдери з API-ключем або на основі env -- `profile`: провайдери, які з’являються, коли існують профілі автентифікації -- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів +- `profile`: провайдери, які з’являються, коли існують auth-профілі +- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдера - `late`: останній прохід, після інших неявних провайдерів -Пізніші провайдери перемагають у разі конфлікту ключів, тому plugin можуть навмисно +Пізніші провайдери перемагають у разі конфлікту ключів, тож plugin можуть навмисно перевизначати вбудований запис провайдера з тим самим id провайдера. Сумісність: -- `discovery` і далі працює як застарілий псевдонім +- `discovery` усе ще працює як застарілий псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Інспекція каналу лише для читання +## Інспектування каналу лише для читання -Якщо ваш 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, не повинні потребувати матеріалізації облікових даних середовища виконання лише для + `openclaw channels status`, `openclaw channels resolve` і потоки doctor/config + repair, не повинні потребувати матеріалізації облікових даних середовища виконання лише для опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: - Повертає лише описовий стан облікового запису. - Зберігає `enabled` і `configured`. -- Включає поля джерела/статусу облікових даних, коли це доречно, наприклад: +- За потреби включає поля джерела/стану облікових даних, наприклад: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність тільки для читання. Повернення `tokenStatus: "available"` (і відповідного поля джерела) достатньо для команд на кшталт status. +- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі лише читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела) для команд типу status. - Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але вони недоступні в поточному шляху команди. -Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. +Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. ## Пакетні набори @@ -761,63 +761,63 @@ Plugin провайдерів можуть визначати каталоги } ``` -Кожен запис стає plugin. Якщо набір перелічує кілька extensions, id plugin +Кожен запис стає plugin. Якщо пакет перелічує кілька extensions, id plugin стає `name/`. -Якщо ваш plugin імпортує npm-залежності, встановіть їх у цьому каталозі, щоб +Якщо ваш plugin імпортує npm-залежності, установіть їх у цьому каталозі, щоб `node_modules` був доступний (`npm install` / `pnpm install`). Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу plugin -після визначення symlink. Записи, які виходять за межі каталогу пакета, +після визначення симлінків. Записи, які виходять за межі каталогу пакета, відхиляються. -Примітка щодо безпеки: `openclaw plugins install` встановлює залежності plugin за допомогою -`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev dependencies у середовищі виконання). Тримайте дерева залежностей plugin -«чистими JS/TS» і уникайте пакетів, які потребують збірок через `postinstall`. +Примітка щодо безпеки: `openclaw plugins install` установлює залежності plugin через +`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей у середовищі виконання). Підтримуйте дерева залежностей plugin +«чистими JS/TS» і уникайте пакетів, які потребують збирання через `postinstall`. Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування. Коли OpenClaw потребує поверхонь налаштування для вимкненого plugin каналу або -коли plugin каналу увімкнено, але ще не налаштовано, він завантажує `setupEntry` +коли plugin каналу ввімкнено, але ще не налаштовано, він завантажує `setupEntry` замість повної точки входу plugin. Це робить запуск і налаштування легшими, -коли основна точка входу вашого plugin також підключає інструменти, хуки або інший код +коли основна точка входу plugin також підключає інструменти, хуки або інший код лише для середовища виконання. Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести plugin каналу на той самий шлях `setupEntry` під час -передпрослуховувальної фази запуску gateway, навіть якщо канал уже налаштовано. +може підключити plugin каналу до того самого шляху `setupEntry` під час +передслухової фази запуску gateway, навіть якщо канал уже налаштовано. Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати -до того, як gateway почне прослуховування. На практиці це означає, що точка входу налаштування -має реєструвати кожну можливість, що належить каналу і від якої залежить запуск, наприклад: +до того, як gateway почне слухати. На практиці це означає, що точка входу налаштування +має реєструвати кожну можливість, що належить каналу, від якої залежить запуск, зокрема: - саму реєстрацію каналу -- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне прослуховування +- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне слухати - будь-які методи gateway, інструменти або служби, які мають існувати в той самий проміжок часу -Якщо ваша повна точка входу все ще володіє будь-якою обов’язковою можливістю запуску, не вмикайте -цей прапорець. Залиште plugin на стандартній поведінці й дозвольте OpenClaw завантажити +Якщо ваша повна точка входу все ще володіє будь-якою необхідною можливістю запуску, не вмикайте +цей прапорець. Залишайте plugin у типовій поведінці й дозвольте OpenClaw завантажити повну точку входу під час запуску. Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, які ядро -може перевіряти до завантаження повного середовища виконання каналу. Поточна поверхня +може консультувати до завантаження повного середовища виконання каналу. Поточна поверхня просування налаштування така: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію каналу -з одним обліковим записом у `channels..accounts.*` без завантаження повної точки входу plugin. -Matrix — поточний вбудований приклад: він переносить лише ключі auth/bootstrap в -іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може -зберегти налаштований неканонічний ключ default-account замість того, щоб завжди створювати +Ядро використовує цю поверхню, коли потрібно просунути застарілу конфігурацію +каналу з одним обліковим записом до `channels..accounts.*` без завантаження повної точки входу plugin. +Matrix є поточним вбудованим прикладом: він переносить лише ключі auth/bootstrap до +іменованого просунутого облікового запису, коли іменовані облікові записи вже існують, і може +зберегти налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати `accounts.default`. -Ці адаптери patch налаштування зберігають ліниве виявлення поверхні контракту вбудованих каналів. Час імпорту залишається легким; поверхня просування завантажується лише під час першого використання замість повторного входу в запуск вбудованого каналу при імпорті модуля. +Ці адаптери патчів налаштування зберігають ледаче виявлення поверхні контракту вбудованих каналів. Час імпорту залишається легким; поверхня просування завантажується лише під час першого використання замість повторного входу у запуск вбудованого каналу під час імпорту модуля. -Коли ці поверхні запуску включають методи Gateway RPC, тримайте їх на +Коли ці поверхні запуску містять методи Gateway RPC, зберігайте їх на префіксі, специфічному для plugin. Простори імен адміністратора ядра (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди визначаються +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються як `operator.admin`, навіть якщо plugin запитує вужчу область. Приклад: @@ -835,9 +835,9 @@ Matrix — поточний вбудований приклад: він пере } ``` -### Метадані каталогу каналу +### Метадані каталогу каналів -Plugin каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і +Plugin каналів можуть рекламувати метадані налаштування/виявлення через `openclaw.channel` і підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити даних каталогу. Приклад: @@ -853,7 +853,7 @@ Plugin каналів можуть оголошувати метадані на "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Самостійно розгорнутий чат через Webhook-ботів Nextcloud Talk.", + "blurb": "Self-hosted чат через webhook-ботів Nextcloud Talk.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -868,63 +868,66 @@ Plugin каналів можуть оголошувати метадані на Корисні поля `openclaw.channel`, окрім мінімального прикладу: -- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу +- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/стану - `docsLabel`: перевизначає текст посилання для посилання на документацію -- `preferOver`: id plugin/каналу з нижчим пріоритетом, які цей запис каталогу має випереджати +- `preferOver`: id plugin/каналу з нижчим пріоритетом, які цей запис каталогу має перевершувати - `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору - `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо форматування вихідних повідомлень - `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` - `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено `false` - `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації -- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure` +- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure` - `quickstartAllowFrom`: підключає канал до стандартного потоку quickstart `allowFrom` -- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сеансу під час визначення цілей announce +- `forceAccountBinding`: вимагає явного прив’язування облікового запису, навіть якщо існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення цілей announce -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 spec є точною версією або плаваючим селектором, -чи присутні очікувані метадані цілісності, і чи також доступний локальний -шлях джерела. Коли ідентичність каталогу/пакета відома, нормалізовані факти -попереджають, якщо розібране ім’я npm-пакета відхиляється від цієї ідентичності. +Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів містять +нормалізовані факти джерела встановлення поруч із сирим блоком `openclaw.install`. Ці +нормалізовані факти вказують, чи є специфікація npm точною версією чи плаваючим +селектором, чи присутні очікувані метадані цілісності, і чи також доступний +локальний шлях джерела. Коли відома ідентичність каталогу/пакета, нормалізовані +факти попереджають, якщо розібране ім’я пакета npm відхиляється від цієї ідентичності. Вони також попереджають, коли `defaultChoice` є недійсним або вказує на джерело, яке -недоступне, і коли метадані цілісності npm присутні без дійсного npm- -джерела. Споживачі мають розглядати `installSource` як адитивне необов’язкове поле, щоб -старі вручну створені записи та shim сумісності не мусили його синтезувати. -Це дає змогу онбордингу й діагностиці пояснювати стан source plane без -імпорту середовища виконання plugin. +недоступне, а також коли метадані цілісності npm присутні без дійсного джерела +npm. Споживачі мають розглядати `installSource` як адитивне необов’язкове поле, щоб +старі записи, зібрані вручну, і shim сумісності не мусили його синтезувати. +Це дає змогу онбордингу та діагностиці пояснювати стан площини джерел без +імпортування середовища виконання plugin. -Офіційні зовнішні записи npm мають надавати перевагу точному `npmSpec` плюс +Офіційні зовнішні записи npm мають надавати перевагу точному `npmSpec` разом із `expectedIntegrity`. Голі імена пакетів і dist-tag усе ще працюють для -сумісності, але вони показують попередження source plane, щоб каталог міг рухатися -до зафіксованих, перевірених за цілісністю встановлень без порушення роботи наявних plugin. -Коли онбординг виконує встановлення з локального шляху каталогу, він записує -запис `plugins.installs` із `source: "path"` і відносним до робочого простору -`sourcePath`, коли це можливо. Абсолютний операційний шлях завантаження залишається в +сумісності, але вони породжують попередження площини джерел, щоб каталог міг +рухатися до закріплених інсталяцій із перевіркою цілісності без порушення роботи +наявних plugin. Коли онбординг виконує встановлення з локального шляху каталогу, він записує керований +запис реєстру встановлення plugin з `source: "path"` і +`sourcePath`, відносним до робочого простору, коли це можливо. Абсолютний робочий шлях завантаження залишається в `plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів -робочої станції в довгоживучій конфігурації. Це зберігає видимість локальних установлень для розробки для -діагностики source plane без додавання другої сирої поверхні розкриття шляхів файлової системи. +робочої станції в довготривалій конфігурації. Це зберігає видимість локальних інсталяцій для розробки для +діагностики площини джерел без додавання другої сирої поверхні розкриття +шляху файлової системи. Застарілі записи конфігурації `plugins.installs` усе ще читаються як +резервний варіант сумісності, тоді як керований станом реєстр `plugins/installs.json` +стає джерелом істини для встановлень. ## Plugin рушія контексту -Plugin рушія контексту володіють оркестрацією контексту сеансу для ingest, assembly -і Compaction. Реєструйте їх зі свого plugin через +Plugin рушія контексту володіють оркестрацією контексту сесії для приймання, збирання +та Compaction. Реєструйте їх зі свого plugin за допомогою `api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через `plugins.slots.contextEngine`. -Використовуйте це, коли вашому plugin потрібно замінити або розширити стандартний конвеєр -контексту, а не просто додати пошук у пам’яті або хуки. +Використовуйте це, коли ваш plugin має замінити або розширити типовий конвеєр +контексту, а не просто додати пошук у пам’яті чи хуки. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -990,43 +993,43 @@ export default function (api) { ## Додавання нової можливості -Коли plugin потребує поведінки, яка не вписується в поточний API, не обходьте -систему plugin через приватне глибоке втручання. Додайте відсутню можливість. +Коли plugin потрібна поведінка, яка не вписується в поточний API, не обходьте +систему plugin через приватне проникнення всередину. Додайте відсутню можливість. Рекомендована послідовність: 1. визначте контракт ядра - Вирішіть, якою спільною поведінкою має володіти ядро: політикою, резервним переходом, злиттям конфігурації, - життєвим циклом, семантикою для каналу та формою допоміжних засобів середовища виконання. + Вирішіть, якою спільною поведінкою має володіти ядро: політикою, резервним варіантом, злиттям конфігурації, + життєвим циклом, семантикою для каналів і формою допоміжного засобу середовища виконання. 2. додайте типізовані поверхні реєстрації plugin/середовища виконання - Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною + Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною типізованою поверхнею можливості. -3. підключіть ядро + споживачів каналів/можливостей - Канали і plugin можливостей мають споживати нову можливість через ядро, - а не імпортувати реалізацію вендора напряму. -4. зареєструйте реалізації вендора - Потім plugin вендора реєструють свої бекенди для цієї можливості. +3. підключіть ядро + споживачів каналів/функцій + Канали та feature plugin мають споживати нову можливість через ядро, + а не через прямий імпорт реалізації постачальника. +4. зареєструйте реалізації постачальників + Потім plugin постачальників реєструють свої backend відносно цієї можливості. 5. додайте покриття контракту - Додайте тести, щоб із часом володіння і форма реєстрації залишалися явними. + Додайте тести, щоб форма володіння та реєстрації з часом залишалася явною. -Саме так OpenClaw зберігає власну позицію, не стаючи жорстко прив’язаним до -світогляду одного провайдера. Див. [Capability Cookbook](/uk/plugins/architecture) -для конкретного контрольного списку файлів і робочого прикладу. +Саме так OpenClaw зберігає свою виразну позицію, не стаючи жорстко +прив’язаним до світогляду одного провайдера. Див. [Capability Cookbook](/uk/plugins/architecture), +щоб отримати конкретний контрольний список файлів і готовий приклад. ### Контрольний список можливості -Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих -поверхонь разом: +Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися +таких поверхонь: -- типи контрактів ядра в `src//types.ts` -- раннер/допоміжний засіб середовища виконання ядра в `src//runtime.ts` +- типи контракту ядра в `src//types.ts` +- виконавець ядра/допоміжний засіб середовища виконання в `src//runtime.ts` - поверхня реєстрації API plugin в `src/plugins/types.ts` - підключення реєстру plugin в `src/plugins/registry.ts` -- відкриття середовища виконання plugin в `src/plugins/runtime/*`, коли plugin можливостей/каналів - мають його споживати +- відкриття в середовищі виконання plugin у `src/plugins/runtime/*`, коли feature/channel + plugin мають це споживати - допоміжні засоби capture/test в `src/test-utils/plugin-registration.ts` - перевірки володіння/контракту в `src/plugins/contracts/registry.ts` -- документація для операторів/plugin в `docs/` +- документація для операторів/plugin у `docs/` Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість ще не повністю інтегрована. @@ -1052,9 +1055,9 @@ api.registerVideoGenerationProvider({ }, }); -// спільний допоміжний засіб середовища виконання для plugin можливостей/каналів +// спільний допоміжний засіб середовища виконання для feature/channel plugin const clip = await api.runtime.videoGeneration.generate({ - prompt: "Покажи, як робот іде через лабораторію.", + prompt: "Show the robot walking through the lab.", cfg, }); ``` @@ -1065,16 +1068,16 @@ const clip = await api.runtime.videoGeneration.generate({ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -Це зберігає правило простим: +Це зберігає просте правило: - ядро володіє контрактом можливості + оркестрацією -- plugin вендора володіють реалізаціями вендора -- plugin можливостей/каналів споживають допоміжні засоби середовища виконання +- plugin постачальників володіють реалізаціями постачальників +- feature/channel plugin споживають допоміжні засоби середовища виконання - тести контракту зберігають явність володіння ## Пов’язані матеріали -- [Plugin architecture](/uk/plugins/architecture) — загальнодоступна модель можливостей і форми +- [Plugin architecture](/uk/plugins/architecture) — публічна модель можливостей і форми - [Plugin SDK subpaths](/uk/plugins/sdk-subpaths) - [Plugin SDK setup](/uk/plugins/sdk-setup) - [Building plugins](/uk/plugins/building-plugins)