From 015f9e992aed53c39578e9465cafb8bc2161bf1a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 7 Apr 2026 18:46:39 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/matrix.md | 640 +++++----- docs/uk/plugins/architecture.md | 1560 ++++++++++++------------ docs/uk/plugins/sdk-channel-plugins.md | 291 ++--- docs/uk/plugins/sdk-migration.md | 463 +++---- docs/uk/plugins/sdk-overview.md | 540 ++++---- docs/uk/tools/exec-approvals.md | 455 ++++--- 6 files changed, 2007 insertions(+), 1942 deletions(-) diff --git a/docs/uk/channels/matrix.md b/docs/uk/channels/matrix.md index c5bb1b291..cde13328b 100644 --- a/docs/uk/channels/matrix.md +++ b/docs/uk/channels/matrix.md @@ -1,29 +1,29 @@ --- read_when: - Налаштування Matrix в OpenClaw - - Налаштування E2EE та верифікації Matrix + - Налаштування Matrix E2EE та верифікації summary: Стан підтримки Matrix, налаштування та приклади конфігурації title: Matrix x-i18n: - generated_at: "2026-04-07T03:26:13Z" + generated_at: "2026-04-07T18:44:59Z" model: gpt-5.4 provider: openai - source_hash: d53baa2ea5916cd00a99cae0ded3be41ffa13c9a69e8ea8461eb7baa6a99e13c + source_hash: ec926df79a41fa296d63f0ec7219d0f32e075628d76df9ea490e93e4c5030f83 source_path: channels/matrix.md workflow: 15 --- # Matrix -Matrix — це вбудований канальний plugin Matrix для OpenClaw. -Він використовує офіційний `matrix-js-sdk` і підтримує особисті повідомлення, кімнати, треди, медіа, реакції, опитування, місцезнаходження та E2EE. +Matrix — це вбудований плагін каналу Matrix для OpenClaw. +Він використовує офіційний `matrix-js-sdk` і підтримує DM, кімнати, треди, медіа, реакції, опитування, геолокацію та E2EE. -## Вбудований plugin +## Вбудований плагін -Matrix постачається як вбудований plugin у поточних релізах OpenClaw, тому звичайним -пакетованим збіркам не потрібне окреме встановлення. +Matrix постачається як вбудований плагін у поточних релізах OpenClaw, тож звичайним +пакетним збіркам не потрібне окреме встановлення. -Якщо ви використовуєте старішу збірку або спеціальне встановлення без Matrix, встановіть +Якщо ви використовуєте старішу збірку або кастомне встановлення без Matrix, встановіть його вручну: Встановлення з npm: @@ -38,22 +38,22 @@ openclaw plugins install @openclaw/matrix openclaw plugins install ./path/to/local/matrix-plugin ``` -Див. [Plugins](/uk/tools/plugin), щоб дізнатися про поведінку plugin і правила встановлення. +Див. [Плагіни](/uk/tools/plugin) щодо поведінки плагінів і правил встановлення. ## Налаштування -1. Переконайтеся, що plugin Matrix доступний. - - У поточних пакетованих релізах OpenClaw він уже вбудований. - - У старіших або спеціальних встановленнях його можна додати вручну наведеними вище командами. -2. Створіть обліковий запис Matrix на вашому homeserver. -3. Налаштуйте `channels.matrix` одним із таких способів: +1. Переконайтеся, що плагін Matrix доступний. + - У поточних пакетних релізах OpenClaw він уже вбудований. + - У старіших/кастомних встановленнях його можна додати вручну наведеними вище командами. +2. Створіть обліковий запис Matrix на своєму homeserver. +3. Налаштуйте `channels.matrix` одним із варіантів: - `homeserver` + `accessToken`, або - `homeserver` + `userId` + `password`. -4. Перезапустіть шлюз. -5. Почніть DM з ботом або запросіть його до кімнати. +4. Перезапустіть gateway. +5. Почніть DM із ботом або запросіть його до кімнати. - Нові запрошення Matrix працюють лише тоді, коли їх дозволяє `channels.matrix.autoJoin`. -Шляхи інтерактивного налаштування: +Інтерактивні шляхи налаштування: ```bash openclaw channels add @@ -63,31 +63,31 @@ openclaw configure --section channels Що саме запитує майстер Matrix: - URL homeserver -- метод автентифікації: access token або пароль -- user ID лише якщо ви вибрали автентифікацію паролем +- метод автентифікації: токен доступу або пароль +- user ID лише якщо ви обираєте автентифікацію за паролем - необов’язкова назва пристрою - чи вмикати E2EE -- чи налаштовувати доступ до кімнат Matrix зараз -- чи налаштовувати автоматичне приєднання до запрошень Matrix зараз -- якщо автоматичне приєднання до запрошень увімкнено, чи має це бути `allowlist`, `always` або `off` +- чи налаштувати доступ до кімнат Matrix зараз +- чи налаштувати авто-приєднання до запрошень Matrix зараз +- коли авто-приєднання до запрошень увімкнено, чи має це бути `allowlist`, `always` або `off` -Поведінка майстра, яку важливо знати: +Важлива поведінка майстра: -- Якщо для вибраного облікового запису вже існують змінні середовища автентифікації Matrix і в конфігурації для цього облікового запису ще не збережено автентифікацію, майстер пропонує скорочений варіант із env, щоб під час налаштування зберегти автентифікацію в змінних середовища замість копіювання секретів у конфігурацію. -- Коли ви інтерактивно додаєте ще один обліковий запис Matrix, введене ім’я облікового запису нормалізується в ID облікового запису, який використовується в конфігурації та змінних середовища. Наприклад, `Ops Bot` стає `ops-bot`. -- Запити allowlist для DM одразу приймають повні значення `@user:server`. Відображувані імена працюють лише тоді, коли живий пошук у каталозі знаходить один точний збіг; інакше майстер попросить повторити спробу з повним Matrix ID. -- Запити allowlist для кімнат приймають ID кімнат і псевдоніми безпосередньо. Вони також можуть у реальному часі визначати назви вже приєднаних кімнат, але невизначені назви зберігаються лише в тому вигляді, як їх введено під час налаштування, і пізніше ігноруються під час виконання резолюції allowlist. Віддавайте перевагу `!room:server` або `#alias:server`. -- Тепер майстер показує явне попередження перед кроком автоматичного приєднання до запрошень, оскільки `channels.matrix.autoJoin` за замовчуванням має значення `off`; агенти не приєднуватимуться до запрошених кімнат або нових запрошень у стилі DM, якщо ви це не ввімкнете. -- У режимі allowlist для автоматичного приєднання до запрошень використовуйте лише стабільні цілі запрошень: `!roomId:server`, `#alias:server` або `*`. Прості назви кімнат відхиляються. -- Ідентичність кімнати/сеансу під час виконання використовує стабільний ID кімнати Matrix. Оголошені в кімнаті псевдоніми використовуються лише як вхідні дані для пошуку, а не як довгостроковий ключ сеансу чи стабільна ідентичність групи. -- Щоб визначити назви кімнат перед збереженням, використовуйте `openclaw channels resolve --channel matrix "Project Room"`. +- Якщо змінні середовища автентифікації Matrix вже існують для вибраного облікового запису, і для цього облікового запису ще не збережено автентифікацію в конфігурації, майстер запропонує скористатися env, щоб зберігати автентифікацію у змінних середовища замість копіювання секретів у конфігурацію. +- Коли ви інтерактивно додаєте ще один обліковий запис Matrix, введена назва облікового запису нормалізується до ID облікового запису, який використовується в конфігурації та змінних середовища. Наприклад, `Ops Bot` стає `ops-bot`. +- Підказки allowlist для DM одразу приймають повні значення `@user:server`. Відображувані імена працюють лише тоді, коли live directory lookup знаходить одну точну відповідність; інакше майстер попросить повторити спробу з повним Matrix ID. +- Підказки allowlist для кімнат безпосередньо приймають room ID та alias. Вони також можуть live-режимом визначати назви приєднаних кімнат, але назви, які не вдалося визначити, зберігаються лише як були введені під час налаштування і пізніше ігноруються під час runtime-визначення allowlist. Надавайте перевагу `!room:server` або `#alias:server`. +- Тепер майстер показує явне попередження перед кроком авто-приєднання до запрошень, оскільки `channels.matrix.autoJoin` за замовчуванням має значення `off`; агенти не приєднуватимуться до запрошених кімнат або нових запрошень у стилі DM, якщо ви це не налаштуєте. +- У режимі авто-приєднання за allowlist використовуйте лише стабільні цілі запрошень: `!roomId:server`, `#alias:server` або `*`. Звичайні назви кімнат відхиляються. +- Ідентичність runtime-кімнати/сесії використовує стабільний Matrix room ID. Оголошені для кімнати alias використовуються лише як вхідні дані для пошуку, а не як довгостроковий ключ сесії чи стабільна ідентичність групи. +- Щоб визначити назви кімнат перед їх збереженням, використовуйте `openclaw channels resolve --channel matrix "Project Room"`. `channels.matrix.autoJoin` за замовчуванням має значення `off`. -Якщо ви не встановите його, бот не приєднуватиметься до запрошених кімнат або нових запрошень у стилі DM, тому не з’являтиметься в нових групах або запрошених DM, якщо ви спочатку не приєднаєтеся вручну. +Якщо залишити його невизначеним, бот не приєднуватиметься до запрошених кімнат або нових запрошень у стилі DM, тож не з’являтиметься в нових групах чи запрошених DM, якщо ви спочатку не приєднаєтеся вручну. -Установіть `autoJoin: "allowlist"` разом із `autoJoinAllowlist`, щоб обмежити, які запрошення він приймає, або встановіть `autoJoin: "always"`, якщо хочете, щоб він приєднувався до кожного запрошення. +Встановіть `autoJoin: "allowlist"` разом із `autoJoinAllowlist`, щоб обмежити, які запрошення він приймає, або встановіть `autoJoin: "always"`, якщо хочете, щоб він приєднувався до кожного запрошення. У режимі `allowlist` `autoJoinAllowlist` приймає лише `!roomId:server`, `#alias:server` або `*`. @@ -137,7 +137,7 @@ openclaw configure --section channels } ``` -Налаштування на основі пароля (токен кешується після входу): +Налаштування на основі пароля (після входу токен кешується): ```json5 { @@ -154,10 +154,10 @@ openclaw configure --section channels ``` Matrix зберігає кешовані облікові дані в `~/.openclaw/credentials/matrix/`. -Обліковий запис за замовчуванням використовує `credentials.json`; іменовані облікові записи — `credentials-.json`. -Коли там є кешовані облікові дані, OpenClaw вважає Matrix налаштованим для виявлення під час setup, doctor і channel-status, навіть якщо поточна автентифікація не задана безпосередньо в конфігурації. +Обліковий запис за замовчуванням використовує `credentials.json`; іменовані облікові записи використовують `credentials-.json`. +Коли там існують кешовані облікові дані, OpenClaw вважає Matrix налаштованим для setup, doctor і виявлення стану каналу, навіть якщо поточну автентифікацію не задано безпосередньо в конфігурації. -Відповідні змінні середовища (використовуються, коли ключ конфігурації не задано): +Еквівалентні змінні середовища (використовуються, коли ключ конфігурації не задано): - `MATRIX_HOMESERVER` - `MATRIX_ACCESS_TOKEN` @@ -185,14 +185,14 @@ Matrix зберігає кешовані облікові дані в `~/.opencl - `MATRIX_OPS_X2D_BOT_HOMESERVER` - `MATRIX_OPS_X2D_BOT_ACCESS_TOKEN` -Matrix екранує розділові знаки в ID облікових записів, щоб змінні середовища з областю дії не конфліктували. -Наприклад, `-` стає `_X2D_`, тому `ops-prod` перетворюється на `MATRIX_OPS_X2D_PROD_*`. +Matrix екранує розділові знаки в ID облікових записів, щоб уникнути колізій у змінних середовища з областю видимості. +Наприклад, `-` перетворюється на `_X2D_`, тож `ops-prod` відповідає `MATRIX_OPS_X2D_PROD_*`. -Інтерактивний майстер пропонує скорочений варіант зі змінними середовища лише тоді, коли ці env-змінні автентифікації вже існують і для вибраного облікового запису ще не збережено автентифікацію Matrix у конфігурації. +Інтерактивний майстер пропонує скористатися ярликом змінних середовища лише тоді, коли ці змінні автентифікації вже присутні, а для вибраного облікового запису ще не збережено автентифікацію Matrix у конфігурації. ## Приклад конфігурації -Це практичний базовий конфіг із DM pairing, allowlist кімнат і ввімкненим E2EE: +Це практична базова конфігурація з DM pairing, allowlist для кімнат і ввімкненим E2EE: ```json5 { @@ -228,17 +228,17 @@ Matrix екранує розділові знаки в ID облікових з ``` `autoJoin` застосовується до запрошень Matrix загалом, а не лише до запрошень у кімнати/групи. -Це включає нові запрошення в стилі DM. У момент запрошення OpenClaw не завжди може надійно визначити, чи -запрошена кімната в підсумку вважатиметься DM чи групою, тому всі запрошення спочатку проходять через однакове -рішення `autoJoin`. `dm.policy` усе одно застосовується після того, як бот приєднався й кімнату -класифіковано як DM, тому `autoJoin` керує поведінкою приєднання, а `dm.policy` — поведінкою відповіді/доступу. +Сюди також входять нові запрошення у стилі DM. На момент запрошення OpenClaw не може надійно визначити, чи +запрошену кімнату буде зрештою оброблено як DM чи як групу, тому всі запрошення спочатку проходять через одне й те саме +рішення `autoJoin`. `dm.policy` як і раніше застосовується після того, як бот приєднався і кімнату +класифіковано як DM, тож `autoJoin` керує поведінкою приєднання, а `dm.policy` — поведінкою відповіді/доступу. -## Попередній перегляд streaming +## Потокові попередні перегляди -Streaming відповідей Matrix вмикається за бажанням. +Потокова передача відповідей Matrix вмикається лише за бажанням. -Установіть `channels.matrix.streaming` у значення `"partial"`, якщо хочете, щоб OpenClaw надсилав одну живу -відповідь попереднього перегляду, редагував її на місці, поки модель генерує текст, а потім завершував її, +Установіть `channels.matrix.streaming` у `"partial"`, якщо хочете, щоб OpenClaw надсилав один live-попередній +перегляд відповіді, редагував цей попередній перегляд на місці під час генерації тексту моделлю, а потім завершував його, коли відповідь буде готова: ```json5 @@ -251,38 +251,38 @@ Streaming відповідей Matrix вмикається за бажанням } ``` -- `streaming: "off"` — значення за замовчуванням. OpenClaw чекає на фінальну відповідь і надсилає її один раз. -- `streaming: "partial"` створює одне редаговане повідомлення попереднього перегляду для поточного блоку відповіді помічника, використовуючи звичайні текстові повідомлення Matrix. Це зберігає успадковану поведінку Matrix із попереднім сповіщенням за першим прев’ю, тож стандартні клієнти можуть сповіщати про перший текст streamed preview, а не про завершений блок. -- `streaming: "quiet"` створює одне редаговане тихе повідомлення попереднього перегляду для поточного блоку відповіді помічника. Використовуйте це лише тоді, коли ви також налаштували push rules одержувача для фіналізованих редагувань прев’ю. -- `blockStreaming: true` вмикає окремі повідомлення прогресу Matrix. Якщо streaming попереднього перегляду ввімкнено, Matrix зберігає живу чернетку для поточного блоку та залишає завершені блоки як окремі повідомлення. -- Коли preview streaming увімкнено, а `blockStreaming` вимкнено, Matrix редагує живу чернетку на місці й фіналізує ту саму подію, коли блок або хід завершується. -- Якщо preview більше не вміщується в одну подію Matrix, OpenClaw припиняє preview streaming і повертається до звичайної фінальної доставки. -- Відповіді з медіа, як і раніше, надсилають вкладення звичайним способом. Якщо застаріле прев’ю більше не можна безпечно повторно використати, OpenClaw редагує його перед надсиланням фінальної відповіді з медіа. -- Редагування прев’ю збільшують кількість викликів API Matrix. Якщо ви хочете максимально консервативну поведінку щодо rate limit, залиште streaming вимкненим. +- `streaming: "off"` — значення за замовчуванням. OpenClaw чекає фінальної відповіді й надсилає її один раз. +- `streaming: "partial"` створює одне редаговане повідомлення попереднього перегляду для поточного блоку відповіді асистента, використовуючи звичайні текстові повідомлення Matrix. Це зберігає застарілу поведінку Matrix із сповіщенням спочатку про попередній перегляд, тому стандартні клієнти можуть сповіщати про перший потоковий текст попереднього перегляду замість завершеного блоку. +- `streaming: "quiet"` створює одне редаговане тихе повідомлення-попередній перегляд для поточного блоку асистента. Використовуйте це лише тоді, коли ви також налаштовуєте push rules отримувача для фіналізованих редагувань попереднього перегляду. +- `blockStreaming: true` вмикає окремі повідомлення прогресу Matrix. Коли потоковий попередній перегляд увімкнено, Matrix зберігає live-чернетку для поточного блоку і залишає завершені блоки як окремі повідомлення. +- Коли попередній потоковий перегляд увімкнено, а `blockStreaming` вимкнено, Matrix редагує live-чернетку на місці та фіналізує ту саму подію, коли блок або хід завершуються. +- Якщо попередній перегляд більше не вміщується в одну подію Matrix, OpenClaw припиняє потоковий попередній перегляд і повертається до звичайної фінальної доставки. +- Відповіді з медіа, як і раніше, надсилають вкладення звичайним способом. Якщо застарілий попередній перегляд більше неможливо безпечно використати повторно, OpenClaw редагує його перед надсиланням фінальної відповіді з медіа. +- Редагування попереднього перегляду потребують додаткових викликів Matrix API. Залиште потокову передачу вимкненою, якщо хочете найбільш консервативну поведінку щодо rate limit. `blockStreaming` сам по собі не вмикає чернетки попереднього перегляду. -Використовуйте `streaming: "partial"` або `streaming: "quiet"` для редагувань попереднього перегляду; потім додайте `blockStreaming: true`, лише якщо також хочете, щоб завершені блоки відповіді помічника залишалися видимими як окремі повідомлення прогресу. +Використовуйте `streaming: "partial"` або `streaming: "quiet"` для редагувань попереднього перегляду; потім додайте `blockStreaming: true`, лише якщо також хочете, щоб завершені блоки асистента залишалися видимими як окремі повідомлення прогресу. -Якщо вам потрібні стандартні сповіщення Matrix без власних push rules, використовуйте `streaming: "partial"` для поведінки з попереднім прев’ю або залиште `streaming` вимкненим для доставки лише фінальної відповіді. Для `streaming: "off"`: +Якщо вам потрібні стандартні сповіщення Matrix без користувацьких push rules, використовуйте `streaming: "partial"` для поведінки з попереднім переглядом спочатку або залиште `streaming` вимкненим для доставки лише фінального варіанта. Із `streaming: "off"`: - `blockStreaming: true` надсилає кожен завершений блок як звичайне повідомлення Matrix зі сповіщенням. - `blockStreaming: false` надсилає лише фінальну завершену відповідь як звичайне повідомлення Matrix зі сповіщенням. -### Self-hosted push rules для тихих фіналізованих прев’ю +### Самохостингові push rules для тихих фіналізованих попередніх переглядів -Якщо ви використовуєте власну інфраструктуру Matrix і хочете, щоб тихі прев’ю сповіщали лише тоді, коли блок або -фінальна відповідь завершені, установіть `streaming: "quiet"` і додайте push rule для кожного користувача для фіналізованих редагувань прев’ю. +Якщо ви запускаєте власну Matrix-інфраструктуру і хочете, щоб тихі попередні перегляди сповіщали лише тоді, коли блок або +фінальна відповідь завершені, установіть `streaming: "quiet"` і додайте push rule на рівні користувача для фіналізованих редагувань попереднього перегляду. -Зазвичай це налаштовується на боці користувача-одержувача, а не як глобальна зміна конфігурації homeserver: +Зазвичай це налаштування для користувача-отримувача, а не глобальна зміна конфігурації homeserver: Швидка схема перед початком: -- recipient user = людина, яка має отримати сповіщення -- bot user = обліковий запис Matrix OpenClaw, який надсилає відповідь -- використовуйте access token користувача-одержувача для наведених нижче викликів API -- зіставляйте `sender` у push rule з повним MXID користувача-бота +- користувач-отримувач = людина, яка має отримати сповіщення +- користувач-бот = обліковий запис OpenClaw Matrix, що надсилає відповідь +- для наведених нижче викликів API використовуйте access token користувача-отримувача +- у push rule зіставляйте `sender` з повним MXID користувача-бота -1. Налаштуйте OpenClaw на використання тихих прев’ю: +1. Налаштуйте OpenClaw на використання тихих попередніх переглядів: ```json5 { @@ -294,13 +294,13 @@ Streaming відповідей Matrix вмикається за бажанням } ``` -2. Переконайтеся, що обліковий запис одержувача вже отримує звичайні push-сповіщення Matrix. Правила тихих прев’ю - працюють лише якщо для цього користувача вже працюють pushers/пристрої. +2. Переконайтеся, що обліковий запис отримувача вже отримує звичайні push-сповіщення Matrix. Правила для тихих попередніх переглядів + працюють лише тоді, коли в цього користувача вже є робочі pusher-и/пристрої. -3. Отримайте access token користувача-одержувача. +3. Отримайте access token користувача-отримувача. - Використовуйте токен користувача, який отримує повідомлення, а не токен бота. - - Найпростіше зазвичай повторно використати токен існуючої сесії клієнта. - - Якщо потрібно випустити новий токен, можна увійти через стандартний Matrix Client-Server API: + - Найпростіше зазвичай повторно використати токен наявної клієнтської сесії. + - Якщо потрібно випустити новий токен, можна ввійти через стандартний Matrix Client-Server API: ```bash curl -sS -X POST \ @@ -316,7 +316,7 @@ curl -sS -X POST \ }' ``` -4. Перевірте, що обліковий запис одержувача вже має pushers: +4. Перевірте, що в облікового запису отримувача вже є pusher-и: ```bash curl -sS \ @@ -324,10 +324,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushers" ``` -Якщо це повертає відсутність активних pushers/пристроїв, спочатку виправте звичайні сповіщення Matrix, а вже потім додавайте -правило OpenClaw нижче. +Якщо у відповіді немає активних pusher-ів/пристроїв, спочатку виправте звичайні сповіщення Matrix, а вже потім додавайте +наведене нижче правило OpenClaw. -OpenClaw позначає фіналізовані редагування прев’ю лише з текстом так: +OpenClaw позначає фіналізовані редагування попереднього перегляду лише для тексту так: ```json { @@ -335,7 +335,7 @@ OpenClaw позначає фіналізовані редагування пре } ``` -5. Створіть override push rule для кожного облікового запису одержувача, який повинен отримувати ці сповіщення: +5. Створіть override push rule для кожного облікового запису отримувача, який має отримувати ці сповіщення: ```bash curl -sS -X PUT \ @@ -368,19 +368,19 @@ curl -sS -X PUT \ Замініть ці значення перед виконанням команди: - `https://matrix.example.org`: базовий URL вашого homeserver -- `$USER_ACCESS_TOKEN`: access token користувача-одержувача -- `openclaw-finalized-preview-botname`: `rule ID`, унікальний для цього бота для цього користувача-одержувача -- `@bot:example.org`: MXID вашого бота Matrix OpenClaw, а не MXID користувача-одержувача +- `$USER_ACCESS_TOKEN`: access token користувача, який отримує повідомлення +- `openclaw-finalized-preview-botname`: rule ID, унікальний для цього бота для цього користувача-отримувача +- `@bot:example.org`: MXID вашого Matrix-бота OpenClaw, а не MXID користувача-отримувача -Важливо для сценаріїв із кількома ботами: +Важливо для конфігурацій із кількома ботами: -- Push rules прив’язані до `ruleId`. Повторний запуск `PUT` для того самого rule ID оновлює саме це правило. -- Якщо один користувач-одержувач повинен отримувати сповіщення від кількох облікових записів ботів Matrix OpenClaw, створіть по одному правилу на кожного бота з унікальним rule ID для кожного збігу sender. +- Ключем push rules є `ruleId`. Повторний `PUT` для того самого rule ID оновлює лише це правило. +- Якщо один користувач-отримувач має отримувати сповіщення для кількох облікових записів Matrix-ботів OpenClaw, створіть окреме правило для кожного бота з унікальним rule ID для кожної відповідності sender. - Простий шаблон — `openclaw-finalized-preview-`, наприклад `openclaw-finalized-preview-ops` або `openclaw-finalized-preview-support`. -Правило оцінюється щодо відправника події: +Правило оцінюється відносно відправника події: -- автентифікуйтеся токеном користувача-одержувача +- автентифікуйтеся токеном користувача-отримувача - зіставляйте `sender` з MXID бота OpenClaw 6. Перевірте, що правило існує: @@ -391,10 +391,10 @@ curl -sS \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -7. Протестуйте streamed reply. У тихому режимі в кімнаті має з’явитися тиха чернетка прев’ю, а фінальне +7. Протестуйте потокову відповідь. У тихому режимі кімната має показати тихий чернетковий попередній перегляд, а фінальне редагування на місці має надіслати сповіщення, коли блок або хід завершиться. -Якщо згодом потрібно видалити правило, видаліть той самий rule ID токеном користувача-одержувача: +Якщо згодом потрібно видалити правило, видаліть той самий rule ID токеном користувача-отримувача: ```bash curl -sS -X DELETE \ @@ -402,39 +402,39 @@ curl -sS -X DELETE \ "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview-botname" ``` -Примітки: +Нотатки: -- Створюйте правило з access token користувача-одержувача, а не бота. -- Нові визначені користувачем правила `override` вставляються перед стандартними правилами придушення, тому додатковий параметр порядку не потрібен. -- Це впливає лише на редагування прев’ю, що містять лише текст, які OpenClaw може безпечно фіналізувати на місці. Випадки повернення до медіа та застарілих прев’ю все одно використовують звичайну доставку Matrix. -- Якщо `GET /_matrix/client/v3/pushers` показує відсутність pushers, у користувача ще не налаштована робоча доставка push у Matrix для цього облікового запису/пристрою. +- Створюйте правило за допомогою access token користувача-отримувача, а не токена бота. +- Нові користувацькі правила `override` вставляються перед стандартними suppress rules, тож додатковий параметр порядку не потрібен. +- Це впливає лише на текстові редагування попереднього перегляду, які OpenClaw може безпечно фіналізувати на місці. Резервні варіанти для медіа та застарілих попередніх переглядів, як і раніше, використовують звичайну доставку Matrix. +- Якщо `GET /_matrix/client/v3/pushers` не показує pusher-ів, користувач ще не має робочої доставки push-сповіщень Matrix для цього облікового запису/пристрою. #### Synapse Для Synapse наведеного вище налаштування зазвичай достатньо: -- Жодних спеціальних змін у `homeserver.yaml` для сповіщень про фіналізовані прев’ю OpenClaw не потрібно. -- Якщо ваше розгортання Synapse уже надсилає звичайні push-сповіщення Matrix, основним кроком налаштування є токен користувача + виклик `pushrules` вище. -- Якщо ви запускаєте Synapse за reverse proxy або workers, переконайтеся, що `/_matrix/client/.../pushrules/` правильно потрапляє до Synapse. -- Якщо ви використовуєте workers у Synapse, переконайтеся, що pushers працюють справно. Доставка push обробляється головним процесом або `synapse.app.pusher` / налаштованими pusher workers. +- Жодних спеціальних змін у `homeserver.yaml` для фіналізованих сповіщень про попередній перегляд OpenClaw не потрібно. +- Якщо ваше розгортання Synapse вже надсилає звичайні push-сповіщення Matrix, основним кроком налаштування є токен користувача + виклик `pushrules` вище. +- Якщо ви запускаєте Synapse за reverse proxy або workers, переконайтеся, що `/_matrix/client/.../pushrules/` коректно надходить до Synapse. +- Якщо ви використовуєте Synapse workers, переконайтеся, що pusher-и справні. Доставка push-сповіщень обробляється головним процесом або `synapse.app.pusher` / налаштованими pusher workers. #### Tuwunel -Для Tuwunel використовуйте той самий процес налаштування й той самий виклик API `push-rule`, наведений вище: +Для Tuwunel використовуйте той самий потік налаштування і виклик API `pushrules`, показаний вище: -- Жодної специфічної для Tuwunel конфігурації для самого маркера фіналізованого прев’ю не потрібно. -- Якщо звичайні сповіщення Matrix уже працюють для цього користувача, основним кроком налаштування є токен користувача + виклик `pushrules` вище. -- Якщо сповіщення наче зникають, поки користувач активний на іншому пристрої, перевірте, чи ввімкнено `suppress_push_when_active`. Tuwunel додав цю опцію у Tuwunel 1.4.2 12 вересня 2025 року, і вона може навмисно приглушувати push на інші пристрої, поки один пристрій активний. +- Жодної специфічної конфігурації Tuwunel для самого маркера фіналізованого попереднього перегляду не потрібно. +- Якщо звичайні сповіщення Matrix для цього користувача вже працюють, основним кроком налаштування є токен користувача + виклик `pushrules` вище. +- Якщо здається, що сповіщення зникають, поки користувач активний на іншому пристрої, перевірте, чи увімкнено `suppress_push_when_active`. Tuwunel додав цей параметр у Tuwunel 1.4.2 12 вересня 2025 року, і він може навмисно приглушувати push-сповіщення на інші пристрої, поки один пристрій активний. ## Шифрування та верифікація -У зашифрованих кімнатах (E2EE) вихідні події зображень використовують `thumbnail_file`, тому прев’ю зображень шифруються разом із повним вкладенням. Незашифровані кімнати, як і раніше, використовують звичайний `thumbnail_url`. Налаштування не потрібні — plugin автоматично визначає стан E2EE. +У зашифрованих (E2EE) кімнатах вихідні події зображень використовують `thumbnail_file`, тому попередні перегляди зображень шифруються разом із повним вкладенням. Незашифровані кімнати, як і раніше, використовують звичайний `thumbnail_url`. Жодної конфігурації не потрібно — плагін автоматично визначає стан E2EE. -### Кімнати bot-to-bot +### Кімнати бот-бот -За замовчуванням повідомлення Matrix від інших налаштованих облікових записів Matrix OpenClaw ігноруються. +За замовчуванням повідомлення Matrix від інших налаштованих облікових записів OpenClaw Matrix ігноруються. -Використовуйте `allowBots`, якщо ви свідомо хочете дозволити міжагентний трафік Matrix: +Використовуйте `allowBots`, якщо ви навмисно хочете міжагентський трафік Matrix: ```json5 { @@ -451,13 +451,13 @@ curl -sS -X DELETE \ } ``` -- `allowBots: true` приймає повідомлення від інших налаштованих облікових записів ботів Matrix у дозволених кімнатах і DM. -- `allowBots: "mentions"` приймає такі повідомлення лише тоді, коли вони явно згадують цього бота в кімнатах. DM усе одно дозволені. +- `allowBots: true` приймає повідомлення від інших налаштованих облікових записів Matrix-ботів у дозволених кімнатах і DM. +- `allowBots: "mentions"` приймає ці повідомлення лише тоді, коли вони явно згадують цього бота в кімнатах. DM, як і раніше, дозволені. - `groups..allowBots` перевизначає налаштування рівня облікового запису для однієї кімнати. -- OpenClaw усе одно ігнорує повідомлення від того самого Matrix user ID, щоб уникнути циклів самовідповіді. -- Matrix тут не надає вбудованого прапорця бота; OpenClaw трактує «створено ботом» як «надіслано іншим налаштованим обліковим записом Matrix на цьому шлюзі OpenClaw». +- OpenClaw, як і раніше, ігнорує повідомлення від того самого Matrix user ID, щоб уникнути циклів самовідповіді. +- Matrix тут не надає нативного прапорця бота; OpenClaw вважає "створене ботом" повідомленням, "надісланим іншим налаштованим обліковим записом Matrix на цьому gateway OpenClaw". -Використовуйте суворі allowlist для кімнат і вимоги згадки, коли вмикаєте bot-to-bot трафік у спільних кімнатах. +Використовуйте суворі allowlist кімнат і вимоги щодо згадок, коли вмикаєте трафік бот-бот у спільних кімнатах. Увімкнення шифрування: @@ -487,7 +487,7 @@ openclaw matrix verify status openclaw matrix verify status --verbose ``` -Включити збережений recovery key у машинозчитуваний вивід: +Включити збережений recovery key у машиночитаному виводі: ```bash openclaw matrix verify status --include-recovery-key --json @@ -499,7 +499,7 @@ openclaw matrix verify status --include-recovery-key --json openclaw matrix verify bootstrap ``` -Підтримка кількох облікових записів: використовуйте `channels.matrix.accounts` з обліковими даними для кожного облікового запису й необов’язковим `name`. Див. [Configuration reference](/uk/gateway/configuration-reference#multi-account-all-channels), щоб ознайомитися зі спільним шаблоном. +Підтримка кількох облікових записів: використовуйте `channels.matrix.accounts` з обліковими даними для кожного облікового запису та необов’язковим `name`. Див. [Довідник із конфігурації](/uk/gateway/configuration-reference#multi-account-all-channels) щодо спільного шаблону. Докладна діагностика bootstrap: @@ -507,7 +507,7 @@ openclaw matrix verify bootstrap openclaw matrix verify bootstrap --verbose ``` -Примусово скинути identity cross-signing перед bootstrap: +Примусово скинути поточну ідентичність cross-signing і створити нову перед bootstrap: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing @@ -525,7 +525,7 @@ openclaw matrix verify device "" openclaw matrix verify device "" --verbose ``` -Перевірити стан резервного копіювання ключів кімнат: +Перевірити стан резервного копіювання room-key: ```bash openclaw matrix verify backup status @@ -537,7 +537,7 @@ openclaw matrix verify backup status openclaw matrix verify backup status --verbose ``` -Відновити ключі кімнат із резервної копії на сервері: +Відновити room keys із резервної копії на сервері: ```bash openclaw matrix verify backup restore @@ -549,20 +549,20 @@ openclaw matrix verify backup restore openclaw matrix verify backup restore --verbose ``` -Видалити поточну серверну резервну копію та створити нову базову резервну копію. Якщо збережений -ключ резервної копії неможливо коректно завантажити, це скидання також може повторно створити secret storage, щоб -майбутні cold start могли завантажувати новий ключ резервної копії: +Видалити поточну резервну копію на сервері та створити нову базову резервну копію. Якщо збережений +ключ резервної копії не вдається коректно завантажити, це скидання також може повторно створити secret storage, щоб +майбутні холодні запуски могли завантажити новий ключ резервної копії: ```bash openclaw matrix verify backup reset --yes ``` -Усі команди `verify` за замовчуванням лаконічні (включно з тихим внутрішнім логуванням SDK) і показують детальну діагностику лише з `--verbose`. -Для сценаріїв використовуйте `--json`, щоб отримати повний машинозчитуваний вивід. +Усі команди `verify` за замовчуванням лаконічні (включно з тихим внутрішнім логуванням SDK) і показують докладну діагностику лише з `--verbose`. +Використовуйте `--json` для повного машиночитаного виводу під час написання скриптів. -У конфігураціях із кількома обліковими записами CLI-команди Matrix використовують неявний обліковий запис Matrix за замовчуванням, якщо ви не передасте `--account `. -Якщо у вас налаштовано кілька іменованих облікових записів, спочатку встановіть `channels.matrix.defaultAccount`, інакше такі неявні CLI-операції зупиняться й попросять вас явно вибрати обліковий запис. -Використовуйте `--account`, коли хочете, щоб операції верифікації або з пристроями були явно спрямовані на певний іменований обліковий запис: +У конфігураціях із кількома обліковими записами Matrix CLI-команди використовують неявний обліковий запис Matrix за замовчуванням, якщо ви не передасте `--account `. +Якщо налаштовано кілька іменованих облікових записів, спочатку встановіть `channels.matrix.defaultAccount`, інакше такі неявні CLI-операції зупиняться і попросять вас явно вибрати обліковий запис. +Використовуйте `--account`, коли хочете, щоб операції верифікації або роботи з пристроями були явно націлені на іменований обліковий запис: ```bash openclaw matrix verify status --account assistant @@ -574,39 +574,39 @@ openclaw matrix devices list --account assistant ### Що означає "verified" -OpenClaw вважає цей пристрій Matrix верифікованим лише тоді, коли його верифіковано вашою власною identity cross-signing. +OpenClaw вважає цей пристрій Matrix верифікованим лише тоді, коли його верифіковано вашою власною ідентичністю cross-signing. На практиці `openclaw matrix verify status --verbose` показує три сигнали довіри: - `Locally trusted`: цьому пристрою довіряє лише поточний клієнт - `Cross-signing verified`: SDK повідомляє, що пристрій верифіковано через cross-signing -- `Signed by owner`: пристрій підписаний вашим власним self-signing key +- `Signed by owner`: пристрій підписано вашим власним self-signing key -`Verified by owner` стає `yes` лише тоді, коли присутня верифікація cross-signing або підпис власника. -Однієї лише локальної довіри недостатньо, щоб OpenClaw вважав пристрій повністю верифікованим. +`Verified by owner` стає `yes` лише тоді, коли присутні верифікація через cross-signing або підпис власника. +Самої лише локальної довіри недостатньо, щоб OpenClaw вважав пристрій повністю верифікованим. ### Що робить bootstrap -`openclaw matrix verify bootstrap` — це команда відновлення й налаштування для зашифрованих облікових записів Matrix. -Вона виконує все наведене нижче в такому порядку: +`openclaw matrix verify bootstrap` — це команда відновлення та налаштування для зашифрованих облікових записів Matrix. +Вона послідовно робить усе наведене нижче: -- ініціалізує secret storage, повторно використовуючи наявний recovery key, якщо це можливо +- ініціалізує secret storage, повторно використовуючи наявний recovery key, коли це можливо - ініціалізує cross-signing і завантажує відсутні публічні ключі cross-signing -- намагається позначити й підписати поточний пристрій через cross-signing -- створює нову серверну резервну копію ключів кімнат, якщо її ще не існує +- намагається позначити та cross-sign поточний пристрій +- створює нову серверну резервну копію room-key, якщо такої ще не існує -Якщо homeserver вимагає інтерактивної автентифікації для завантаження ключів cross-signing, OpenClaw спочатку намагається завантажити їх без автентифікації, потім із `m.login.dummy`, а потім із `m.login.password`, якщо налаштовано `channels.matrix.password`. +Якщо homeserver вимагає інтерактивну автентифікацію для завантаження ключів cross-signing, OpenClaw спочатку намагається виконати завантаження без автентифікації, потім із `m.login.dummy`, а потім із `m.login.password`, коли налаштовано `channels.matrix.password`. -Використовуйте `--force-reset-cross-signing`, лише якщо ви свідомо хочете відкинути поточну identity cross-signing і створити нову. +Використовуйте `--force-reset-cross-signing` лише тоді, коли ви навмисно хочете відкинути поточну ідентичність cross-signing і створити нову. -Якщо ви навмисно хочете відкинути поточну резервну копію ключів кімнат і почати нову +Якщо ви навмисно хочете відкинути поточну резервну копію room-key і почати нову базову резервну копію для майбутніх повідомлень, використовуйте `openclaw matrix verify backup reset --yes`. -Робіть це лише тоді, коли приймаєте, що невідновна стара зашифрована історія залишиться -недоступною і що OpenClaw може повторно створити secret storage, якщо поточний секрет -резервної копії неможливо безпечно завантажити. +Робіть це лише тоді, коли погоджуєтеся, що невідновлювана стара зашифрована історія +залишиться недоступною і що OpenClaw може повторно створити secret storage, якщо поточний +секрет резервної копії неможливо безпечно завантажити. ### Нова базова резервна копія -Якщо ви хочете, щоб майбутні зашифровані повідомлення працювали, і погоджуєтеся втратити невідновну стару історію, виконайте ці команди по черзі: +Якщо ви хочете, щоб майбутні зашифровані повідомлення працювали й приймаєте втрату невідновлюваної старої історії, виконайте ці команди в такому порядку: ```bash openclaw matrix verify backup reset --yes @@ -614,60 +614,60 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -Додавайте `--account ` до кожної команди, якщо хочете явно націлити їх на певний іменований обліковий запис Matrix. +Додайте `--account ` до кожної команди, якщо хочете явно націлити їх на іменований обліковий запис Matrix. ### Поведінка під час запуску -Коли `encryption: true`, Matrix за замовчуванням встановлює `startupVerification` у `"if-unverified"`. -Під час запуску, якщо цей пристрій усе ще не верифікований, Matrix надішле запит на самоверифікацію в іншому клієнті Matrix, +Коли `encryption: true`, для Matrix значення `startupVerification` за замовчуванням — `"if-unverified"`. +Під час запуску, якщо цей пристрій ще не верифіковано, Matrix надішле запит на самоверифікацію в іншому Matrix-клієнті, пропустить дубльовані запити, якщо один уже очікує, і застосує локальний cooldown перед повторною спробою після перезапусків. -Невдалі спроби запитів за замовчуванням повторюються раніше, ніж успішне створення запиту. +Невдалі спроби запиту за замовчуванням повторюються швидше, ніж успішне створення запиту. Установіть `startupVerification: "off"`, щоб вимкнути автоматичні запити під час запуску, або налаштуйте `startupVerificationCooldownHours`, -якщо вам потрібне коротше або довше вікно повторних спроб. +якщо хочете коротше або довше вікно повторної спроби. -Під час запуску також автоматично виконується консервативний прохід bootstrap для crypto. -Цей прохід спочатку намагається повторно використати поточні secret storage та identity cross-signing і не скидає cross-signing, якщо ви не запускаєте явний потік відновлення bootstrap. +Під час запуску також автоматично виконується консервативний прохід crypto bootstrap. +Цей прохід спочатку намагається повторно використати поточні secret storage і ідентичність cross-signing та уникає скидання cross-signing, якщо ви не запускаєте явний потік відновлення bootstrap. Якщо під час запуску виявлено пошкоджений стан bootstrap і налаштовано `channels.matrix.password`, OpenClaw може спробувати суворіший шлях відновлення. -Якщо поточний пристрій уже підписаний власником, OpenClaw зберігає цю identity замість автоматичного скидання. +Якщо поточний пристрій уже підписано власником, OpenClaw зберігає цю ідентичність і не скидає її автоматично. -Оновлення з попереднього публічного plugin Matrix: +Оновлення з попереднього публічного плагіна Matrix: -- OpenClaw автоматично повторно використовує той самий обліковий запис Matrix, access token і identity пристрою, коли це можливо. -- Перед запуском будь-яких практичних змін міграції Matrix OpenClaw створює або повторно використовує snapshot відновлення в `~/Backups/openclaw-migrations/`. -- Якщо ви використовуєте кілька облікових записів Matrix, установіть `channels.matrix.defaultAccount` перед оновленням зі старої плоскої схеми зберігання, щоб OpenClaw знав, який обліковий запис має отримати цей спільний застарілий стан. -- Якщо попередній plugin зберігав локально ключ дешифрування резервної копії ключів кімнат Matrix, запуск або `openclaw doctor --fix` автоматично імпортує його в новий потік recovery key. -- Якщо access token Matrix змінився після підготовки міграції, під час запуску тепер виконується сканування сусідніх коренів сховища з хешами токенів на наявність очікуваного стану застарілого відновлення перед тим, як відмовитися від автоматичного відновлення резервної копії. -- Якщо access token Matrix зміниться пізніше для того самого облікового запису, homeserver і користувача, OpenClaw тепер надає перевагу повторному використанню найповнішого наявного кореня сховища з хешем токена замість старту з порожнього каталогу стану Matrix. -- Під час наступного запуску шлюзу резервні ключі кімнат автоматично відновляться в нове crypto store. -- Якщо старий plugin мав лише локальні ключі кімнат, які ніколи не резервувалися, OpenClaw чітко попередить про це. Ці ключі не можна автоматично експортувати з попереднього rust crypto store, тому частина старої зашифрованої історії може залишатися недоступною, доки її не буде відновлено вручну. -- Див. [Matrix migration](/uk/install/migrating-matrix), щоб ознайомитися з повним процесом оновлення, обмеженнями, командами відновлення та поширеними повідомленнями міграції. +- OpenClaw автоматично повторно використовує той самий обліковий запис Matrix, access token і ідентичність пристрою, коли це можливо. +- Перш ніж запускати будь-які важливі зміни міграції Matrix, OpenClaw створює або повторно використовує recovery snapshot у `~/Backups/openclaw-migrations/`. +- Якщо ви використовуєте кілька облікових записів Matrix, установіть `channels.matrix.defaultAccount` перед оновленням зі старого flat-store layout, щоб OpenClaw знав, який обліковий запис має отримати цей спільний застарілий стан. +- Якщо попередній плагін локально зберігав ключ дешифрування резервної копії Matrix room-key, під час запуску або `openclaw doctor --fix` його буде автоматично імпортовано в новий потік recovery key. +- Якщо access token Matrix змінився після підготовки міграції, під час запуску тепер виконується пошук коренів сховища sibling token-hash на наявність очікуваного застарілого стану відновлення перед тим, як відмовитися від автоматичного відновлення резервної копії. +- Якщо access token Matrix зміниться пізніше для того самого облікового запису, homeserver і користувача, OpenClaw тепер віддає перевагу повторному використанню найповнішого наявного кореня сховища token-hash замість старту з порожнього каталогу стану Matrix. +- Під час наступного запуску gateway резервні room keys буде автоматично відновлено до нового crypto store. +- Якщо у старому плагіні були локальні room keys, які ніколи не резервувалися, OpenClaw чітко попередить про це. Ці ключі неможливо автоматично експортувати зі старого rust crypto store, тому частина старої зашифрованої історії може залишатися недоступною, доки її не буде відновлено вручну. +- Див. [Міграція Matrix](/uk/install/migrating-matrix) щодо повного процесу оновлення, обмежень, команд відновлення та типових повідомлень міграції. -Зашифрований стан під час виконання організовано в коренях із хешами токенів для кожного облікового запису й користувача -у `~/.openclaw/matrix/accounts//__//`. +Зашифрований runtime-стан організовано за коренями token-hash для кожного облікового запису й користувача в +`~/.openclaw/matrix/accounts//__//`. Цей каталог містить sync store (`bot-storage.json`), crypto store (`crypto/`), файл recovery key (`recovery-key.json`), snapshot IndexedDB (`crypto-idb-snapshot.json`), прив’язки тредів (`thread-bindings.json`) і стан startup verification (`startup-verification.json`), -коли ці можливості використовуються. -Коли токен змінюється, але identity облікового запису лишається тією самою, OpenClaw повторно використовує найкращий наявний -корінь для цього кортежу account/homeserver/user, щоб попередній sync state, crypto state, прив’язки тредів -і стан startup verification залишалися видимими. +коли ці функції використовуються. +Коли токен змінюється, але ідентичність облікового запису залишається тією самою, OpenClaw повторно використовує найкращий наявний +корінь для цього кортежу account/homeserver/user, щоб попередній sync state, crypto state, thread bindings +і стан startup verification залишалися доступними. ### Модель Node crypto store -Matrix E2EE у цьому plugin використовує офіційний шлях Rust crypto з `matrix-js-sdk` у Node. -Цей шлях очікує збереження на основі IndexedDB, якщо ви хочете, щоб crypto state переживав перезапуски. +Matrix E2EE у цьому плагіні використовує офіційний шлях Rust crypto з `matrix-js-sdk` у Node. +Цей шлях очікує persistence на основі IndexedDB, якщо ви хочете, щоб crypto state зберігався після перезапусків. Наразі OpenClaw забезпечує це в Node так: - використовує `fake-indexeddb` як shim API IndexedDB, який очікує SDK - відновлює вміст Rust crypto IndexedDB з `crypto-idb-snapshot.json` перед `initRustCrypto` -- зберігає оновлений вміст IndexedDB назад у `crypto-idb-snapshot.json` після ініціалізації та під час виконання -- серіалізує відновлення та збереження snapshot для `crypto-idb-snapshot.json` за допомогою advisory file lock, щоб збереження під час виконання шлюзу й обслуговування CLI не конфліктували через один і той самий файл snapshot +- зберігає оновлений вміст IndexedDB назад у `crypto-idb-snapshot.json` після init і під час runtime +- серіалізує відновлення та збереження snapshot відносно `crypto-idb-snapshot.json` за допомогою advisory file lock, щоб runtime-persistence gateway та CLI-обслуговування не конфліктували за один і той самий snapshot-файл -Це інфраструктура сумісності/зберігання, а не власна реалізація crypto. -Файл snapshot є чутливим станом під час виконання і зберігається з обмежувальними правами доступу до файлу. -У межах моделі безпеки OpenClaw хост шлюзу й локальний каталог стану OpenClaw уже входять до довіреної межі оператора, тож це передусім операційне питання надійності, а не окрема віддалена межа довіри. +Це plumbing для сумісності/зберігання, а не кастомна crypto-реалізація. +Файл snapshot містить чутливий runtime-стан і зберігається з обмежувальними правами доступу. +У межах моделі безпеки OpenClaw хост gateway і локальний каталог стану OpenClaw вже входять до довіреної межі оператора, тож це переважно питання операційної надійності, а не окрема віддалена межа довіри. Заплановане покращення: @@ -675,46 +675,46 @@ Matrix E2EE у цьому plugin використовує офіційний ш ## Керування профілем -Оновіть self-profile Matrix для вибраного облікового запису так: +Оновіть власний профіль Matrix для вибраного облікового запису за допомогою: ```bash openclaw matrix profile set --name "OpenClaw Assistant" openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png ``` -Додайте `--account `, якщо хочете явно націлити команду на певний іменований обліковий запис Matrix. +Додайте `--account `, якщо хочете явно націлити команду на іменований обліковий запис Matrix. -Matrix приймає URL аватарів `mxc://` напряму. Якщо ви передаєте URL аватара `http://` або `https://`, OpenClaw спочатку завантажує його в Matrix, а потім зберігає отриманий URL `mxc://` назад у `channels.matrix.avatarUrl` (або в перевизначення вибраного облікового запису). +Matrix безпосередньо приймає URL аватарів `mxc://`. Якщо ви передаєте URL аватара `http://` або `https://`, OpenClaw спочатку завантажує його в Matrix і зберігає визначений URL `mxc://` назад у `channels.matrix.avatarUrl` (або у вибране перевизначення облікового запису). ## Автоматичні сповіщення про верифікацію -Тепер Matrix публікує сповіщення про життєвий цикл верифікації безпосередньо в сувору DM-кімнату верифікації як повідомлення `m.notice`. -Це включає: +Тепер Matrix публікує сповіщення про життєвий цикл верифікації безпосередньо в суворій DM-кімнаті верифікації як повідомлення `m.notice`. +Сюди входять: -- сповіщення про запит верифікації +- сповіщення про запити на верифікацію - сповіщення про готовність до верифікації (з явною підказкою "Verify by emoji") - сповіщення про початок і завершення верифікації -- відомості SAS (emoji і десяткові значення), коли вони доступні +- деталі SAS (emoji і decimal), коли вони доступні -Вхідні запити на верифікацію від іншого клієнта Matrix відстежуються та автоматично приймаються OpenClaw. -Для потоків самоверифікації OpenClaw також автоматично запускає потік SAS, коли стає доступною верифікація за emoji, і підтверджує свій бік. -Для запитів на верифікацію від іншого користувача/пристрою Matrix OpenClaw автоматично приймає запит, а потім чекає, поки потік SAS продовжиться звичайним чином. -Вам усе одно потрібно порівняти emoji або десятковий SAS у вашому клієнті Matrix і підтвердити "They match" там, щоб завершити верифікацію. +Вхідні запити на верифікацію від іншого Matrix-клієнта відстежуються та автоматично приймаються OpenClaw. +Для потоків самоверифікації OpenClaw також автоматично запускає SAS-потік, щойно стає доступною emoji-верифікація, і підтверджує свій бік. +Для запитів на верифікацію від іншого Matrix-користувача/пристрою OpenClaw автоматично приймає запит, а потім чекає, поки SAS-потік продовжиться у звичайному режимі. +Вам усе одно потрібно порівняти emoji або decimal SAS у вашому Matrix-клієнті й підтвердити там "They match", щоб завершити верифікацію. -OpenClaw не приймає бездумно дубльовані потоки, ініційовані ним самим. Під час запуску не створюється новий запит, якщо запит на самоверифікацію вже очікує. +OpenClaw не приймає автоматично самостійно ініційовані дубльовані потоки бездумно. Під час запуску не створюється новий запит, якщо запит на самоверифікацію вже очікує. -Сповіщення протоколу/системи верифікації не пересилаються в конвеєр чату агента, тому вони не спричиняють `NO_REPLY`. +Сповіщення протоколу/системи верифікації не пересилаються в конвеєр чату агента, тому вони не створюють `NO_REPLY`. ### Гігієна пристроїв -Старі керовані OpenClaw пристрої Matrix можуть накопичуватися в обліковому записі й ускладнювати розуміння довіри в зашифрованих кімнатах. -Перелічіть їх так: +Старі пристрої Matrix, керовані OpenClaw, можуть накопичуватися в обліковому записі й ускладнювати розуміння довіри в зашифрованих кімнатах. +Перегляньте їх за допомогою: ```bash openclaw matrix devices list ``` -Видаліть застарілі керовані OpenClaw пристрої так: +Видаліть застарілі пристрої Matrix, керовані OpenClaw, за допомогою: ```bash openclaw matrix devices prune-stale @@ -722,65 +722,65 @@ openclaw matrix devices prune-stale ### Відновлення Direct Room -Якщо стан direct-message виходить із синхронізації, OpenClaw може залишити застарілі зіставлення `m.direct`, що вказують на старі solo-кімнати замість актуального DM. Переглянути поточне зіставлення для співрозмовника можна так: +Якщо стан direct message виходить із синхронізації, OpenClaw може отримати застарілі зіставлення `m.direct`, які вказують на старі solo rooms замість активного DM. Перегляньте поточне зіставлення для співрозмовника за допомогою: ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -Виправити це можна так: +Відновіть його за допомогою: ```bash openclaw matrix direct repair --user-id @alice:example.org ``` -Відновлення зберігає логіку, специфічну для Matrix, усередині plugin: +Відновлення зберігає Matrix-специфічну логіку всередині плагіна: -- воно надає перевагу суворому DM 1:1, який уже відображений у `m.direct` -- інакше повертається до будь-якого поточного strict 1:1 DM з цим користувачем, до якого вже виконано приєднання -- якщо здорового DM не існує, створює нову direct room і переписує `m.direct`, щоб вона вказувала на неї +- воно віддає перевагу суворому 1:1 DM, який уже зіставлено в `m.direct` +- інакше воно переходить до будь-якого поточного приєднаного суворого 1:1 DM із цим користувачем +- якщо здорового DM не існує, воно створює нову direct room і переписує `m.direct`, щоб вказувати на неї -Потік відновлення не видаляє старі кімнати автоматично. Він лише вибирає здоровий DM і оновлює зіставлення, щоб нові надсилання Matrix, сповіщення про верифікацію й інші потоки direct-message знову спрямовувалися до правильної кімнати. +Потік відновлення не видаляє старі кімнати автоматично. Він лише вибирає здоровий DM і оновлює зіставлення, щоб нові надсилання Matrix, сповіщення про верифікацію та інші потоки direct message знову націлювалися на правильну кімнату. ## Треди -Matrix підтримує нативні треди Matrix як для автоматичних відповідей, так і для надсилань через message-tool. +Matrix підтримує нативні Matrix threads як для автоматичних відповідей, так і для надсилань через message-tool. -- `dm.sessionScope: "per-user"` (за замовчуванням) зберігає маршрутизацію DM Matrix прив’язаною до відправника, тому кілька кімнат DM можуть ділити один сеанс, якщо вони визначаються як один і той самий співрозмовник. -- `dm.sessionScope: "per-room"` ізолює кожну кімнату DM Matrix у власний ключ сеансу, зберігаючи водночас звичайну автентифікацію DM і перевірки allowlist. -- Явні прив’язки розмов Matrix усе одно мають пріоритет над `dm.sessionScope`, тому прив’язані кімнати й треди зберігають вибраний цільовий сеанс. -- `threadReplies: "off"` залишає відповіді на верхньому рівні та зберігає вхідні threaded messages на батьківському сеансі. -- `threadReplies: "inbound"` відповідає всередині треда лише тоді, коли вхідне повідомлення вже було в цьому треді. -- `threadReplies: "always"` залишає відповіді в треді, коренем якого є повідомлення-тригер, і спрямовує цю розмову через відповідний сеанс із областю треда від першого повідомлення-тригера. +- `dm.sessionScope: "per-user"` (за замовчуванням) зберігає маршрутизацію Matrix DM у межах відправника, тож кілька DM-кімнат можуть використовувати одну сесію, якщо вони визначаються як той самий співрозмовник. +- `dm.sessionScope: "per-room"` ізолює кожну Matrix DM-кімнату у власний ключ сесії, водночас зберігаючи звичайні перевірки автентифікації DM і allowlist. +- Явні прив’язки Matrix conversation, як і раніше, мають пріоритет над `dm.sessionScope`, тому прив’язані кімнати й треди зберігають свою вибрану цільову сесію. +- `threadReplies: "off"` зберігає відповіді на верхньому рівні й залишає вхідні тредові повідомлення на батьківській сесії. +- `threadReplies: "inbound"` відповідає всередині треду лише тоді, коли вхідне повідомлення вже було в цьому треді. +- `threadReplies: "always"` зберігає відповіді в кімнаті в треді, коренем якого є повідомлення-тригер, і маршрутизує цю розмову через відповідну сесію з областю треду від першого повідомлення-тригера. - `dm.threadReplies` перевизначає налаштування верхнього рівня лише для DM. Наприклад, ви можете ізолювати треди в кімнатах, залишивши DM пласкими. -- Вхідні threaded messages включають кореневе повідомлення треда як додатковий контекст агента. -- Надсилання через message-tool тепер автоматично успадковують поточний тред Matrix, коли ціллю є та сама кімната або той самий DM-користувач, якщо явно не вказано `threadId`. -- Повторне використання цілі DM-користувача в тому самому сеансі спрацьовує лише тоді, коли метадані поточного сеансу підтверджують того самого DM-співрозмовника в тому самому обліковому записі Matrix; інакше OpenClaw повертається до звичайної маршрутизації за користувачем. -- Коли OpenClaw бачить, що кімната DM Matrix конфліктує з іншою кімнатою DM у тому самому спільному сеансі DM Matrix, він публікує в цій кімнаті одноразове `m.notice` із запасним варіантом `/focus`, коли прив’язки тредів увімкнені, і з підказкою `dm.sessionScope`. -- Прив’язки тредів під час виконання підтримуються для Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язаний до треда `/acp spawn` тепер працюють у кімнатах і DM Matrix. -- `/focus` верхнього рівня в кімнаті/DM Matrix створює новий тред Matrix і прив’язує його до цільового сеансу, коли `threadBindings.spawnSubagentSessions=true`. -- Виконання `/focus` або `/acp spawn --thread here` всередині наявного треда Matrix прив’язує натомість поточний тред. +- Вхідні тредові повідомлення включають кореневе повідомлення треду як додатковий контекст агента. +- Надсилання через message-tool тепер автоматично успадковують поточний Matrix thread, коли ціль — та сама кімната або той самий DM-користувач, якщо явно не вказано `threadId`. +- Повторне використання цілі DM-користувача в межах тієї самої сесії спрацьовує лише тоді, коли метадані поточної сесії підтверджують того самого співрозмовника DM в тому самому обліковому записі Matrix; інакше OpenClaw повертається до звичайної маршрутизації в межах користувача. +- Коли OpenClaw бачить, що Matrix DM-кімната конфліктує з іншою DM-кімнатою в межах тієї самої спільної Matrix DM-сесії, він публікує одноразове `m.notice` у цій кімнаті з аварійним варіантом `/focus`, коли ввімкнено прив’язки тредів і підказку `dm.sessionScope`. +- Runtime-прив’язки тредів підтримуються для Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язане до треду `/acp spawn` тепер працюють у Matrix-кімнатах і DM. +- Верхньорівневий Matrix room/DM `/focus` створює новий Matrix thread і прив’язує його до цільової сесії, коли `threadBindings.spawnSubagentSessions=true`. +- Запуск `/focus` або `/acp spawn --thread here` всередині наявного Matrix thread натомість прив’язує поточний thread. -## Прив’язки розмов ACP +## ACP conversation bindings -Кімнати Matrix, DM і наявні треди Matrix можна перетворити на довговічні робочі простори ACP без зміни поверхні чату. +Matrix rooms, DM і наявні Matrix threads можна перетворити на довговічні робочі простори ACP без зміни поверхні чату. -Швидкий операторський потік: +Швидкий потік для оператора: -- Виконайте `/acp spawn codex --bind here` всередині DM, кімнати або наявного треда Matrix, які ви хочете й надалі використовувати. -- У DM або кімнаті Matrix верхнього рівня поточний DM/кімната лишається поверхнею чату, а майбутні повідомлення маршрутизуються до створеного сеансу ACP. -- Усередині наявного треда Matrix `--bind here` прив’язує цей поточний тред на місці. -- `/new` і `/reset` скидають той самий прив’язаний сеанс ACP на місці. -- `/acp close` закриває сеанс ACP і видаляє прив’язку. +- Виконайте `/acp spawn codex --bind here` усередині Matrix DM, кімнати або наявного треду, який хочете й надалі використовувати. +- У верхньорівневому Matrix DM або кімнаті поточний DM/кімната залишається поверхнею чату, а майбутні повідомлення маршрутизуються до створеної ACP-сесії. +- Усередині наявного Matrix thread `--bind here` прив’язує поточний thread на місці. +- `/new` і `/reset` скидають ту саму прив’язану ACP-сесію на місці. +- `/acp close` закриває ACP-сесію й видаляє прив’язку. -Примітки: +Нотатки: -- `--bind here` не створює дочірній тред Matrix. -- `threadBindings.spawnAcpSessions` потрібен лише для `/acp spawn --thread auto|here`, коли OpenClaw має створити або прив’язати дочірній тред Matrix. +- `--bind here` не створює дочірній Matrix thread. +- `threadBindings.spawnAcpSessions` потрібен лише для `/acp spawn --thread auto|here`, коли OpenClaw має створити або прив’язати дочірній Matrix thread. ### Конфігурація прив’язки тредів -Matrix успадковує глобальні значення за замовчуванням із `session.threadBindings`, а також підтримує перевизначення для конкретного каналу: +Matrix успадковує глобальні значення за замовчуванням з `session.threadBindings`, а також підтримує перевизначення для каналу: - `threadBindings.enabled` - `threadBindings.idleHours` @@ -788,29 +788,29 @@ Matrix успадковує глобальні значення за замов - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Прапорці запуску, прив’язаного до тредів Matrix, вмикаються за бажанням: +Прапорці породження для Matrix thread-bound є opt-in: -- Установіть `threadBindings.spawnSubagentSessions: true`, щоб дозволити `/focus` верхнього рівня створювати й прив’язувати нові треди Matrix. -- Установіть `threadBindings.spawnAcpSessions: true`, щоб дозволити `/acp spawn --thread auto|here` прив’язувати сеанси ACP до тредів Matrix. +- Установіть `threadBindings.spawnSubagentSessions: true`, щоб дозволити верхньорівневому `/focus` створювати й прив’язувати нові Matrix threads. +- Установіть `threadBindings.spawnAcpSessions: true`, щоб дозволити `/acp spawn --thread auto|here` прив’язувати ACP-сесії до Matrix threads. ## Реакції -Matrix підтримує дії вихідних реакцій, вхідні сповіщення про реакції та вхідні ack reactions. +Matrix підтримує вихідні дії з реакціями, вхідні сповіщення про реакції та вхідні реакції-підтвердження. -- Інструменти вихідних реакцій контролюються через `channels["matrix"].actions.reactions`. +- Інструментарій вихідних реакцій керується через `channels["matrix"].actions.reactions`. - `react` додає реакцію до конкретної події Matrix. - `reactions` показує поточне зведення реакцій для конкретної події Matrix. -- `emoji=""` видаляє власні реакції облікового запису бота на цю подію. +- `emoji=""` видаляє власні реакції облікового запису бота на цій події. - `remove: true` видаляє лише вказану реакцію emoji від облікового запису бота. -Область ack reactions визначається у стандартному порядку резолюції OpenClaw: +Область реакцій-підтверджень визначається за стандартним порядком OpenClaw: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- резервний emoji identity агента +- резервний emoji з ідентичності агента -Область ack reaction визначається в такому порядку: +Область `ackReactionScope` визначається в такому порядку: - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` @@ -820,32 +820,32 @@ Matrix підтримує дії вихідних реакцій, вхідні - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` -- за замовчуванням: `own` +- значення за замовчуванням: `own` Поточна поведінка: - `reactionNotifications: "own"` пересилає додані події `m.reaction`, коли вони націлені на створені ботом повідомлення Matrix. - `reactionNotifications: "off"` вимикає системні події реакцій. -- Видалення реакцій усе ще не синтезуються в системні події, оскільки Matrix відображає їх як редагування, а не як окремі видалення `m.reaction`. +- Видалення реакцій досі не синтезується в системні події, тому що Matrix показує їх як redactions, а не як окремі видалення `m.reaction`. ## Контекст історії -- `channels.matrix.historyLimit` керує тим, скільки нещодавніх повідомлень кімнати включається як `InboundHistory`, коли повідомлення кімнати Matrix запускає агента. -- Резервно використовується `messages.groupChat.historyLimit`. Якщо обидва значення не задані, ефективне значення за замовчуванням — `0`, тому повідомлення кімнати з обов’язковою згадкою не буферизуються. Установіть `0`, щоб вимкнути. -- Історія кімнати Matrix стосується лише кімнати. DM продовжують використовувати звичайну історію сеансу. -- Історія кімнати Matrix є лише для очікування: OpenClaw буферизує повідомлення кімнати, які ще не спричинили відповідь, а потім фіксує це вікно, коли надходить згадка або інший тригер. +- `channels.matrix.historyLimit` керує тим, скільки останніх повідомлень кімнати включається як `InboundHistory`, коли повідомлення Matrix у кімнаті активує агента. +- Використовується fallback до `messages.groupChat.historyLimit`. Якщо обидва значення не задані, ефективне значення за замовчуванням — `0`, тому повідомлення кімнат із вимогою згадки не буферизуються. Установіть `0`, щоб вимкнути. +- Історія кімнат Matrix — лише для кімнат. DM і далі використовують звичайну історію сесії. +- Історія кімнат Matrix — лише для очікуваних повідомлень: OpenClaw буферизує повідомлення кімнати, які ще не спричинили відповідь, а потім фіксує це вікно, коли надходить згадка чи інший тригер. - Поточне повідомлення-тригер не включається до `InboundHistory`; воно залишається в основному вхідному тілі цього ходу. -- Повторні спроби для тієї самої події Matrix повторно використовують початковий snapshot історії замість дрейфу вперед до новіших повідомлень кімнати. +- Повторні спроби для тієї самої події Matrix повторно використовують початковий snapshot історії замість зсуву вперед до новіших повідомлень кімнати. ## Видимість контексту -Matrix підтримує спільний елемент керування `contextVisibility` для додаткового контексту кімнати, наприклад отриманого тексту відповіді, коренів тредів і історії, що очікує. +Matrix підтримує спільний елемент керування `contextVisibility` для додаткового контексту кімнати, наприклад отриманого тексту відповіді, коренів тредів і очікуваної історії. -- `contextVisibility: "all"` — значення за замовчуванням. Додатковий контекст зберігається в отриманому вигляді. -- `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками allowlist для кімнати/користувача. -- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явну процитовану відповідь. +- `contextVisibility: "all"` — значення за замовчуванням. Додатковий контекст зберігається як отримано. +- `contextVisibility: "allowlist"` фільтрує додатковий контекст за відправниками, дозволеними активними перевірками allowlist кімнати/користувача. +- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явну цитовану відповідь. -Це налаштування впливає на видимість додаткового контексту, а не на те, чи може саме вхідне повідомлення запускати відповідь. +Це налаштування впливає на видимість додаткового контексту, а не на те, чи може саме вхідне повідомлення спричинити відповідь. Авторизація тригера, як і раніше, визначається `groupPolicy`, `groups`, `groupAllowFrom` і налаштуваннями політики DM. ## Приклад політики DM і кімнат @@ -871,60 +871,62 @@ Matrix підтримує спільний елемент керування `co } ``` -Див. [Groups](/uk/channels/groups), щоб дізнатися про обов’язкові згадки та поведінку allowlist. +Див. [Групи](/uk/channels/groups) щодо поведінки із згадками та allowlist. -Приклад pairing для DM Matrix: +Приклад pairing для Matrix DM: ```bash openclaw pairing list matrix openclaw pairing approve matrix ``` -Якщо неавторизований користувач Matrix продовжує писати вам до схвалення, OpenClaw повторно використовує той самий код pairing, що очікує, і після короткого cooldown може знову надіслати відповідь-нагадування замість створення нового коду. +Якщо непідтверджений користувач Matrix продовжує вам писати до схвалення, OpenClaw повторно використовує той самий очікуваний код pairing і може знову надіслати відповідь-нагадування після короткого cooldown замість створення нового коду. -Див. [Pairing](/uk/channels/pairing), щоб дізнатися про спільний потік pairing для DM і структуру зберігання. +Див. [Pairing](/uk/channels/pairing) щодо спільного потоку DM pairing і структури зберігання. -## Погодження exec +## Підтвердження exec -Matrix може виступати клієнтом погодження exec для облікового запису Matrix. +Matrix може виступати нативним клієнтом підтвердження для облікового запису Matrix. Нативні +перемикачі маршрутизації DM/каналу, як і раніше, знаходяться в конфігурації підтверджень exec: - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (необов’язково; резервно використовується `channels.matrix.dm.allowFrom`) +- `channels.matrix.execApprovals.approvers` (необов’язково; fallback до `channels.matrix.dm.allowFrom`) - `channels.matrix.execApprovals.target` (`dm` | `channel` | `both`, за замовчуванням: `dm`) - `channels.matrix.execApprovals.agentFilter` - `channels.matrix.execApprovals.sessionFilter` -Особи, що погоджують, мають бути Matrix user ID, наприклад `@owner:example.org`. Matrix автоматично вмикає нативні погодження exec, коли `enabled` не задано або має значення `"auto"` і принаймні одного погоджувача можна визначити або з `execApprovals.approvers`, або з `channels.matrix.dm.allowFrom`. Установіть `enabled: false`, щоб явно вимкнути Matrix як нативний клієнт погодження. Інакше запити на погодження резервно пересилаються до інших налаштованих маршрутів погодження або до резервної політики погодження exec. +Особи, що підтверджують, мають бути Matrix user ID, наприклад `@owner:example.org`. Matrix автоматично вмикає нативні підтвердження, коли `enabled` не задано або має значення `"auto"` і можна визначити принаймні одного approver. Підтвердження exec спочатку використовують `execApprovals.approvers` і можуть fallback до `channels.matrix.dm.allowFrom`. Підтвердження плагіна авторизуються через `channels.matrix.dm.allowFrom`. Установіть `enabled: false`, щоб явно вимкнути Matrix як нативний клієнт підтвердження. В іншому разі запити на підтвердження fallback до інших налаштованих маршрутів підтвердження або до fallback policy для підтверджень. -Нативна маршрутизація Matrix наразі стосується лише exec: +Нативна маршрутизація Matrix тепер підтримує обидва типи підтверджень: -- `channels.matrix.execApprovals.*` керує нативною маршрутизацією в DM/канал для погоджень exec. -- Погодження plugin і далі використовують спільний `/approve` у тому самому чаті плюс будь-яке налаштоване пересилання `approvals.plugin`. -- Matrix і далі може повторно використовувати `channels.matrix.dm.allowFrom` для авторизації погоджень plugin, коли може безпечно визначити погоджувачів, але не надає окремого нативного шляху fanout DM/каналу для погоджень plugin. +- `channels.matrix.execApprovals.*` керує нативним режимом fanout DM/каналу для запитів на підтвердження в Matrix. +- Підтвердження exec використовують набір approver-ів для exec з `execApprovals.approvers` або `channels.matrix.dm.allowFrom`. +- Підтвердження плагіна використовують allowlist Matrix DM з `channels.matrix.dm.allowFrom`. +- Скорочення через реакції Matrix та оновлення повідомлень застосовуються і до підтверджень exec, і до підтверджень плагіна. Правила доставки: -- `target: "dm"` надсилає запити на погодження в DM погоджувачам -- `target: "channel"` надсилає запит назад у початкову кімнату або DM Matrix -- `target: "both"` надсилає погоджувачам у DM і в початкову кімнату або DM Matrix +- `target: "dm"` надсилає запити на підтвердження в DM approver-ів +- `target: "channel"` надсилає запит назад до вихідної Matrix-кімнати або DM +- `target: "both"` надсилає і в DM approver-ів, і у вихідну Matrix-кімнату або DM -Запити на погодження в Matrix ініціалізують швидкі реакції в основному повідомленні погодження: +Запити на підтвердження Matrix ініціалізують скорочення через реакції на основному повідомленні підтвердження: - `✅` = дозволити один раз - `❌` = заборонити -- `♾️` = дозволити завжди, коли таке рішення дозволене чинною політикою exec +- `♾️` = дозволити завжди, якщо таке рішення дозволене ефективною політикою exec -Погоджувачі можуть реагувати на це повідомлення або використовувати резервні slash-команди: `/approve allow-once`, `/approve allow-always` або `/approve deny`. +Особи, що підтверджують, можуть реагувати на це повідомлення або використовувати резервні slash commands: `/approve allow-once`, `/approve allow-always` або `/approve deny`. -Лише визначені погоджувачі можуть дозволяти або забороняти. Доставка в канал включає текст команди, тому вмикайте `channel` або `both` лише в довірених кімнатах. +Лише визначені approver-и можуть дозволяти або забороняти. Для підтверджень exec доставка в канал включає текст команди, тож вмикайте `channel` або `both` лише в довірених кімнатах. -Запити на погодження в Matrix повторно використовують спільний core approval planner. Нативна поверхня Matrix є transport only для погоджень exec: маршрутизація кімнат/DM і поведінка надсилання/оновлення/видалення повідомлень. +Запити на підтвердження Matrix повторно використовують спільний core approval planner. Matrix-специфічна нативна поверхня обробляє маршрутизацію кімната/DM, реакції та поведінку надсилання/оновлення/видалення повідомлень як для підтверджень exec, так і для підтверджень плагіна. -Перевизначення для окремого облікового запису: +Перевизначення для облікового запису: - `channels.matrix.accounts..execApprovals` -Пов’язана документація: [Exec approvals](/uk/tools/exec-approvals) +Пов’язана документація: [Підтвердження exec](/uk/tools/exec-approvals) ## Приклад кількох облікових записів @@ -956,21 +958,21 @@ Matrix може виступати клієнтом погодження exec д } ``` -Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для іменованих облікових записів, якщо обліковий запис їх не перевизначає. +Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для іменованих облікових записів, якщо обліковий запис не перевизначає їх. Ви можете обмежити успадкований запис кімнати одним обліковим записом Matrix через `groups..account` (або застарілий `rooms..account`). -Записи без `account` залишаються спільними для всіх облікових записів Matrix, а записи з `account: "default"` і далі працюють, коли обліковий запис за замовчуванням налаштовано безпосередньо на верхньому рівні `channels.matrix.*`. -Часткові спільні значення автентифікації за замовчуванням самі по собі не створюють окремий неявний обліковий запис за замовчуванням. OpenClaw синтезує верхньорівневий обліковий запис `default` лише тоді, коли цей default має актуальну автентифікацію (`homeserver` плюс `accessToken`, або `homeserver` плюс `userId` і `password`); іменовані облікові записи все одно можуть залишатися доступними для виявлення через `homeserver` плюс `userId`, коли кешовані облікові дані пізніше задовольняють автентифікацію. -Якщо Matrix уже має рівно один іменований обліковий запис або `defaultAccount` вказує на наявний ключ іменованого облікового запису, просування з одного облікового запису до кількох під час відновлення/налаштування зберігає цей обліковий запис замість створення нового запису `accounts.default`. У цей просунутий обліковий запис переміщуються лише ключі автентифікації/bootstrap Matrix; спільні ключі політики доставки залишаються на верхньому рівні. -Установіть `defaultAccount`, якщо хочете, щоб OpenClaw віддавав перевагу одному іменованому обліковому запису Matrix для неявної маршрутизації, probing і операцій CLI. -Якщо у вас налаштовано кілька іменованих облікових записів, установіть `defaultAccount` або передавайте `--account ` для CLI-команд, які покладаються на неявний вибір облікового запису. +Записи без `account` залишаються спільними для всіх облікових записів Matrix, а записи з `account: "default"` і далі працюють, коли обліковий запис за замовчуванням налаштований безпосередньо на верхньому рівні `channels.matrix.*`. +Часткові спільні значення автентифікації за замовчуванням самі по собі не створюють окремий неявний обліковий запис за замовчуванням. OpenClaw синтезує верхньорівневий обліковий запис `default` лише тоді, коли для цього значення за замовчуванням є актуальна автентифікація (`homeserver` плюс `accessToken` або `homeserver` плюс `userId` і `password`); іменовані облікові записи все одно можуть залишатися доступними через `homeserver` плюс `userId`, коли кешовані облікові дані пізніше задовольняють автентифікацію. +Якщо в Matrix уже є рівно один іменований обліковий запис або `defaultAccount` вказує на наявний ключ іменованого облікового запису, просування від однооблікового до багатооблікового режиму під час відновлення/налаштування зберігає цей обліковий запис замість створення нового запису `accounts.default`. У цей підвищений обліковий запис переміщуються лише ключі Matrix auth/bootstrap; спільні ключі політики доставки залишаються на верхньому рівні. +Установіть `defaultAccount`, якщо хочете, щоб OpenClaw віддавав перевагу одному іменованому обліковому запису Matrix для неявної маршрутизації, probe і CLI-операцій. +Якщо налаштовано кілька іменованих облікових записів, установіть `defaultAccount` або передавайте `--account ` для CLI-команд, що покладаються на неявний вибір облікового запису. Передавайте `--account ` до `openclaw matrix verify ...` і `openclaw matrix devices ...`, якщо хочете перевизначити цей неявний вибір для однієї команди. -## Приватні/LAN homeserver +## Приватні/LAN homeserver-и -За замовчуванням OpenClaw блокує приватні/внутрішні homeserver Matrix для захисту від SSRF, якщо ви -явно не дозволите їх для кожного облікового запису. +За замовчуванням OpenClaw блокує приватні/внутрішні Matrix homeserver-и для захисту від SSRF, якщо ви +явно не надасте дозвіл окремо для кожного облікового запису. -Якщо ваш homeserver працює на localhost, LAN/Tailscale IP або внутрішньому hostname, увімкніть +Якщо ваш homeserver працює на localhost, LAN/Tailscale IP або внутрішньому імені хоста, увімкніть `network.dangerouslyAllowPrivateNetwork` для цього облікового запису Matrix: ```json5 @@ -997,7 +999,7 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -Це явне ввімкнення дозволяє лише довірені приватні/внутрішні цілі. Публічні незашифровані homeserver, такі як +Цей opt-in дозволяє лише довірені приватні/внутрішні цілі. Публічні незашифровані homeserver-и, наприклад `http://matrix.example.org:8008`, як і раніше, блокуються. За можливості надавайте перевагу `https://`. ## Проксіювання трафіку Matrix @@ -1016,87 +1018,87 @@ openclaw matrix account add \ } ``` -Іменовані облікові записи можуть перевизначати верхньорівневе значення за замовчуванням через `channels.matrix.accounts..proxy`. -OpenClaw використовує це саме налаштування проксі для трафіку Matrix під час виконання та для probes стану облікового запису. +Іменовані облікові записи можуть перевизначати значення верхнього рівня через `channels.matrix.accounts..proxy`. +OpenClaw використовує те саме налаштування проксі для runtime-трафіку Matrix і probe стану облікового запису. ## Визначення цілі -Matrix приймає такі форми цілей усюди, де OpenClaw просить вас указати ціль кімнати або користувача: +Matrix приймає такі форми цілей скрізь, де OpenClaw просить вас указати ціль кімнати або користувача: - Користувачі: `@user:server`, `user:@user:server` або `matrix:user:@user:server` - Кімнати: `!room:server`, `room:!room:server` або `matrix:room:!room:server` -- Псевдоніми: `#alias:server`, `channel:#alias:server` або `matrix:channel:#alias:server` +- Alias: `#alias:server`, `channel:#alias:server` або `matrix:channel:#alias:server` -Живий пошук у каталозі використовує обліковий запис Matrix, у який виконано вхід: +Live directory lookup використовує обліковий запис Matrix, у який виконано вхід: - Пошук користувачів виконує запити до каталогу користувачів Matrix на цьому homeserver. -- Пошук кімнат безпосередньо приймає явні ID кімнат і псевдоніми, а потім резервно переходить до пошуку за назвами кімнат, до яких приєднався цей обліковий запис. -- Пошук за назвами приєднаних кімнат є best-effort. Якщо назву кімнати не вдається визначити як ID або псевдонім, її буде проігноровано під час виконання резолюції allowlist. +- Пошук кімнат безпосередньо приймає явні room ID та alias, а потім за потреби переходить до пошуку за назвами приєднаних кімнат для цього облікового запису. +- Пошук за назвою приєднаної кімнати є best-effort. Якщо назву кімнати не вдається визначити як ID або alias, її буде проігноровано під час runtime-визначення allowlist. -## Довідка з конфігурації +## Довідник із конфігурації - `enabled`: увімкнути або вимкнути канал. - `name`: необов’язкова мітка для облікового запису. - `defaultAccount`: бажаний ID облікового запису, коли налаштовано кілька облікових записів Matrix. - `homeserver`: URL homeserver, наприклад `https://matrix.example.org`. -- `network.dangerouslyAllowPrivateNetwork`: дозволити цьому обліковому запису Matrix підключатися до приватних/внутрішніх homeserver. Увімкніть це, коли homeserver визначається як `localhost`, LAN/Tailscale IP або внутрішній хост, наприклад `matrix-synapse`. -- `proxy`: необов’язковий URL HTTP(S)-проксі для трафіку Matrix. Іменовані облікові записи можуть перевизначати верхньорівневе значення за замовчуванням власним `proxy`. -- `userId`: повний ID користувача Matrix, наприклад `@bot:example.org`. -- `accessToken`: access token для автентифікації на основі токена. Для `channels.matrix.accessToken` і `channels.matrix.accounts..accessToken` підтримуються звичайні текстові значення та значення SecretRef у провайдерах env/file/exec. Див. [Secrets Management](/uk/gateway/secrets). -- `password`: пароль для входу на основі пароля. Підтримуються звичайні текстові значення та значення SecretRef. -- `deviceId`: явний ID пристрою Matrix. +- `network.dangerouslyAllowPrivateNetwork`: дозволяє цьому обліковому запису Matrix підключатися до приватних/внутрішніх homeserver-ів. Увімкніть це, коли homeserver визначається як `localhost`, LAN/Tailscale IP або внутрішній хост, наприклад `matrix-synapse`. +- `proxy`: необов’язковий URL HTTP(S)-проксі для трафіку Matrix. Іменовані облікові записи можуть перевизначати значення верхнього рівня власним `proxy`. +- `userId`: повний Matrix user ID, наприклад `@bot:example.org`. +- `accessToken`: access token для автентифікації на основі токена. Для `channels.matrix.accessToken` і `channels.matrix.accounts..accessToken` підтримуються звичайні текстові значення та значення SecretRef у провайдерах env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). +- `password`: пароль для входу за паролем. Підтримуються звичайні текстові значення та значення SecretRef. +- `deviceId`: явний Matrix device ID. - `deviceName`: відображувана назва пристрою для входу за паролем. - `avatarUrl`: збережений URL власного аватара для синхронізації профілю та оновлень `set-profile`. - `initialSyncLimit`: ліміт подій синхронізації під час запуску. - `encryption`: увімкнути E2EE. -- `allowlistOnly`: примусово вмикати поведінку лише за allowlist для DM і кімнат. -- `allowBots`: дозволяти повідомлення від інших налаштованих облікових записів Matrix OpenClaw (`true` або `"mentions"`). +- `allowlistOnly`: примусово вмикати режим лише allowlist для DM і кімнат. +- `allowBots`: дозволяти повідомлення від інших налаштованих облікових записів OpenClaw Matrix (`true` або `"mentions"`). - `groupPolicy`: `open`, `allowlist` або `disabled`. - `contextVisibility`: режим видимості додаткового контексту кімнати (`all`, `allowlist`, `allowlist_quote`). -- `groupAllowFrom`: allowlist user ID для трафіку в кімнатах. -- Записи `groupAllowFrom` мають бути повними Matrix user ID. Невизначені імена ігноруються під час виконання. -- `historyLimit`: максимальна кількість повідомлень кімнати, що включаються як контекст історії групи. Резервно використовується `messages.groupChat.historyLimit`; якщо обидва значення не задані, ефективне значення за замовчуванням — `0`. Установіть `0`, щоб вимкнути. +- `groupAllowFrom`: allowlist user ID для трафіку кімнат. +- Записи `groupAllowFrom` мають бути повними Matrix user ID. Невизначені імена ігноруються під час runtime. +- `historyLimit`: максимальна кількість повідомлень кімнати для включення в контекст історії групи. Використовується fallback до `messages.groupChat.historyLimit`; якщо обидва значення не задані, ефективне значення за замовчуванням — `0`. Установіть `0`, щоб вимкнути. - `replyToMode`: `off`, `first`, `all` або `batched`. - `markdown`: необов’язкова конфігурація рендерингу Markdown для вихідного тексту Matrix. -- `streaming`: `off` (за замовчуванням), `partial`, `quiet`, `true` або `false`. `partial` і `true` вмикають оновлення чернеток із попереднім прев’ю через звичайні текстові повідомлення Matrix. `quiet` використовує прев’ю-сповіщення без нотифікацій для self-hosted сценаріїв з push-rule. -- `blockStreaming`: `true` вмикає окремі повідомлення прогресу для завершених блоків відповіді помічника, поки активний streaming чернетки. +- `streaming`: `off` (за замовчуванням), `partial`, `quiet`, `true` або `false`. `partial` і `true` вмикають оновлення чернеток із попереднім переглядом через звичайні текстові повідомлення Matrix. `quiet` використовує попередні перегляди у вигляді сповіщень без нотифікації для самохостингових налаштувань push rules. +- `blockStreaming`: `true` вмикає окремі повідомлення прогресу для завершених блоків асистента, поки активна потокова передача чернетки попереднього перегляду. - `threadReplies`: `off`, `inbound` або `always`. -- `threadBindings`: перевизначення для конкретного каналу для маршрутизації та життєвого циклу сеансів, прив’язаних до тредів. +- `threadBindings`: перевизначення на рівні каналу для маршрутизації та життєвого циклу сесій, прив’язаних до тредів. - `startupVerification`: режим автоматичного запиту на самоверифікацію під час запуску (`if-unverified`, `off`). -- `startupVerificationCooldownHours`: cooldown перед повторною спробою автоматичних запитів на верифікацію під час запуску. +- `startupVerificationCooldownHours`: cooldown перед повторною спробою автоматичного запиту на верифікацію під час запуску. - `textChunkLimit`: розмір фрагмента вихідного повідомлення. - `chunkMode`: `length` або `newline`. - `responsePrefix`: необов’язковий префікс повідомлення для вихідних відповідей. - `ackReaction`: необов’язкове перевизначення ack reaction для цього каналу/облікового запису. - `ackReactionScope`: необов’язкове перевизначення області ack reaction (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). - `reactionNotifications`: режим вхідних сповіщень про реакції (`own`, `off`). -- `mediaMaxMb`: обмеження розміру медіа в MB для обробки медіа Matrix. Воно застосовується до вихідних надсилань і обробки вхідних медіа. -- `autoJoin`: політика автоматичного приєднання до запрошень (`always`, `allowlist`, `off`). За замовчуванням: `off`. Це застосовується до запрошень Matrix загалом, включно із запрошеннями в стилі DM, а не лише до запрошень у кімнати/групи. OpenClaw приймає це рішення в момент запрошення, до того як може надійно класифікувати приєднану кімнату як DM або групу. -- `autoJoinAllowlist`: кімнати/псевдоніми, дозволені, коли `autoJoin` має значення `allowlist`. Псевдоніми визначаються в ID кімнат під час обробки запрошень; OpenClaw не довіряє стану псевдоніма, який заявляє запрошена кімната. +- `mediaMaxMb`: обмеження розміру медіа в МБ для обробки Matrix media. Застосовується до вихідних надсилань і обробки вхідних медіа. +- `autoJoin`: політика авто-приєднання до запрошень (`always`, `allowlist`, `off`). За замовчуванням: `off`. Це застосовується до запрошень Matrix загалом, включно із запрошеннями у стилі DM, а не лише до запрошень у кімнати/групи. OpenClaw приймає це рішення в момент запрошення, ще до того, як може надійно класифікувати приєднану кімнату як DM або групу. +- `autoJoinAllowlist`: кімнати/alias, дозволені, коли `autoJoin` має значення `allowlist`. Записи alias визначаються в room ID під час обробки запрошення; OpenClaw не довіряє стану alias, який заявляє запрошена кімната. - `dm`: блок політики DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). -- `dm.policy`: керує доступом до DM після того, як OpenClaw приєднався до кімнати й класифікував її як DM. Це не змінює того, чи буде автоматично прийняте запрошення. -- Записи `dm.allowFrom` мають бути повними Matrix user ID, якщо тільки ви вже не визначили їх за допомогою живого пошуку в каталозі. -- `dm.sessionScope`: `per-user` (за замовчуванням) або `per-room`. Використовуйте `per-room`, якщо хочете, щоб кожна кімната DM Matrix зберігала окремий контекст, навіть якщо співрозмовник той самий. -- `dm.threadReplies`: перевизначення політики тредів лише для DM (`off`, `inbound`, `always`). Воно перевизначає верхньорівневе налаштування `threadReplies` як для розміщення відповідей, так і для ізоляції сеансів у DM. -- `execApprovals`: нативна доставка погоджень exec через Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). -- `execApprovals.approvers`: Matrix user ID, яким дозволено погоджувати запити exec. Необов’язково, якщо `dm.allowFrom` уже визначає погоджувачів. +- `dm.policy`: керує доступом до DM після того, як OpenClaw приєднався до кімнати і класифікував її як DM. Це не змінює того, чи буде запрошення автоматично прийнято. +- Записи `dm.allowFrom` мають бути повними Matrix user ID, якщо ви вже не визначили їх через live directory lookup. +- `dm.sessionScope`: `per-user` (за замовчуванням) або `per-room`. Використовуйте `per-room`, якщо хочете, щоб кожна Matrix DM-кімната зберігала окремий контекст, навіть якщо співрозмовник той самий. +- `dm.threadReplies`: перевизначення політики тредів лише для DM (`off`, `inbound`, `always`). Воно перевизначає налаштування верхнього рівня `threadReplies` як для розміщення відповідей, так і для ізоляції сесій у DM. +- `execApprovals`: нативна доставка підтверджень exec для Matrix (`enabled`, `approvers`, `target`, `agentFilter`, `sessionFilter`). +- `execApprovals.approvers`: Matrix user ID, яким дозволено підтверджувати exec-запити. Необов’язково, якщо `dm.allowFrom` уже визначає approver-ів. - `execApprovals.target`: `dm | channel | both` (за замовчуванням: `dm`). -- `accounts`: іменовані перевизначення для кожного облікового запису. Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для цих записів. -- `groups`: мапа політик для кожної кімнати. Віддавайте перевагу ID кімнат або псевдонімам; невизначені назви кімнат ігноруються під час виконання. Ідентичність сеансу/групи після резолюції використовує стабільний ID кімнати, а зрозумілі людині мітки, як і раніше, походять із назв кімнат. -- `groups..account`: обмежити один успадкований запис кімнати конкретним обліковим записом Matrix у конфігураціях із кількома обліковими записами. -- `groups..allowBots`: перевизначення на рівні кімнати для відправників — налаштованих ботів (`true` або `"mentions"`). +- `accounts`: іменовані перевизначення для облікових записів. Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для цих записів. +- `groups`: карта політик для кімнат. Надавайте перевагу room ID або alias; невизначені назви кімнат ігноруються під час runtime. Ідентичність сесії/групи використовує стабільний room ID після визначення, тоді як зрозумілі людині мітки й далі походять із назв кімнат. +- `groups..account`: обмежує один успадкований запис кімнати конкретним обліковим записом Matrix у конфігураціях із кількома обліковими записами. +- `groups..allowBots`: перевизначення на рівні кімнати для відправників-ботів, налаштованих у системі (`true` або `"mentions"`). - `groups..users`: allowlist відправників для конкретної кімнати. -- `groups..tools`: перевизначення дозволу/заборони інструментів для конкретної кімнати. +- `groups..tools`: перевизначення allow/deny інструментів для конкретної кімнати. - `groups..autoReply`: перевизначення вимоги згадки на рівні кімнати. `true` вимикає вимогу згадки для цієї кімнати; `false` знову примусово вмикає її. -- `groups..skills`: необов’язковий фільтр Skills для конкретної кімнати. -- `groups..systemPrompt`: необов’язковий фрагмент system prompt для конкретної кімнати. -- `rooms`: застарілий псевдонім для `groups`. -- `actions`: керування інструментами для конкретних дій (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). +- `groups..skills`: необов’язковий фільтр Skills на рівні кімнати. +- `groups..systemPrompt`: необов’язковий фрагмент system prompt на рівні кімнати. +- `rooms`: застарілий alias для `groups`. +- `actions`: керування інструментами для кожної дії (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). ## Пов’язане -- [Channels Overview](/uk/channels) — усі підтримувані канали +- [Огляд каналів](/uk/channels) — усі підтримувані канали - [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing -- [Groups](/uk/channels/groups) — поведінка групового чату та обов’язкові згадки -- [Channel Routing](/uk/channels/channel-routing) — маршрутизація сеансів для повідомлень -- [Security](/uk/gateway/security) — модель доступу та посилення безпеки +- [Групи](/uk/channels/groups) — поведінка групового чату та вимога згадки +- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень +- [Безпека](/uk/gateway/security) — модель доступу та зміцнення захисту diff --git a/docs/uk/plugins/architecture.md b/docs/uk/plugins/architecture.md index 0f80a1441..2243483b1 100644 --- a/docs/uk/plugins/architecture.md +++ b/docs/uk/plugins/architecture.md @@ -1,186 +1,186 @@ --- read_when: - - Створення або налагодження нативних плагінів OpenClaw - - Розуміння моделі можливостей плагінів або меж володіння - - Робота над конвеєром завантаження плагінів або реєстром - - Реалізація гачків середовища виконання провайдера або плагінів каналів + - Створення або налагодження нативних plugin OpenClaw + - Розуміння моделі можливостей plugin або меж власності + - Робота над конвеєром завантаження plugin або реєстром + - Реалізація runtime-хуків provider або channel plugin sidebarTitle: Internals -summary: 'Внутрішні компоненти плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби середовища виконання' -title: Внутрішні компоненти плагінів +summary: 'Внутрішня будова plugin: модель можливостей, межі власності, контракти, конвеєр завантаження та допоміжні засоби runtime' +title: Внутрішня будова plugin x-i18n: - generated_at: "2026-04-07T08:06:01Z" + generated_at: "2026-04-07T18:46:39Z" model: gpt-5.4 provider: openai - source_hash: a48b387152c5a6a9782c5aaa9d6c215c16adb7cb256302d3e85f80b03f9b6898 + source_hash: fc5a62710390dc6ad064b818222c1bb7609b3d076741f80bb5bbd9edb90342f1 source_path: plugins/architecture.md workflow: 15 --- -# Внутрішні компоненти плагінів +# Внутрішня будова plugin - Це **поглиблений довідник з архітектури**. Практичні посібники дивіться тут: - - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник для користувачів - - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний посібник зі створення плагіна - - [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями - - [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення провайдера моделей - - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпорту та API реєстрації + Це **довідник із глибокої архітектури**. Практичні посібники дивіться тут: + - [Встановлення та використання plugin](/uk/tools/plugin) — посібник користувача + - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний посібник зі створення plugin + - [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями + - [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення постачальника моделей + - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпортів і API реєстрації -На цій сторінці описано внутрішню архітектуру системи плагінів OpenClaw. +Ця сторінка описує внутрішню архітектуру системи plugin в OpenClaw. ## Публічна модель можливостей -Можливості — це публічна модель **нативних плагінів** усередині OpenClaw. Кожен -нативний плагін OpenClaw реєструється для одного або кількох типів можливостей: +Можливості — це публічна модель **нативних plugin** всередині OpenClaw. Кожен +нативний plugin OpenClaw реєструється для одного або кількох типів можливостей: -| Можливість | Метод реєстрації | Приклади плагінів | -| --------------------- | ----------------------------------------------- | ------------------------------------ | -| Текстовий інференс | `api.registerProvider(...)` | `openai`, `anthropic` | -| Бекенд CLI інференсу | `api.registerCliBackend(...)` | `openai`, `anthropic` | -| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | -| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Веб-отримання | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Веб-пошук | `api.registerWebSearchProvider(...)` | `google` | -| Канал / повідомлення | `api.registerChannel(...)` | `msteams`, `matrix` | +| Можливість | Метод реєстрації | Приклади plugin | +| ---------------------- | ---------------------------------------------- | ----------------------------------- | +| Текстова інференція | `api.registerProvider(...)` | `openai`, `anthropic` | +| Бекенд CLI для інференції | `api.registerCliBackend(...)` | `openai`, `anthropic` | +| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` | +| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Веботримання | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Вебпошук | `api.registerWebSearchProvider(...)` | `google` | +| Канал / обмін повідомленнями | `api.registerChannel(...)` | `msteams`, `matrix` | -Плагін, який не реєструє жодної можливості, але надає гачки, інструменти або -сервіси, є **застарілим плагіном лише з гачками**. Цей шаблон і далі повністю підтримується. +Plugin, який не реєструє жодної можливості, але надає hooks, tools або +services, є **застарілим plugin лише з hooks**. Такий шаблон досі повністю підтримується. -### Позиція щодо сумісності із зовнішніми плагінами +### Позиція щодо зовнішньої сумісності -Модель можливостей уже реалізована в core і сьогодні використовується -вбудованими/нативними плагінами, але сумісність із зовнішніми плагінами все ще -потребує чіткішої планки, ніж «це експортується, отже, це зафіксовано». +Модель можливостей уже впроваджена в core і сьогодні використовується +вбудованими/нативними plugin, але сумісність із зовнішніми plugin усе ще +потребує вищої планки, ніж "це експортується, отже, це заморожено." Поточні рекомендації: -- **наявні зовнішні плагіни:** зберігати працездатність інтеграцій на основі гачків; вважати - це базовим рівнем сумісності -- **нові вбудовані/нативні плагіни:** надавати перевагу явній реєстрації можливостей замість - vendor-специфічних прямолінійних доступів або нових реалізацій лише з гачками -- **зовнішні плагіни, що переходять на реєстрацію можливостей:** це дозволено, але - допоміжні поверхні, специфічні для можливостей, слід вважати такими, що розвиваються, - якщо в документації контракт явно не позначено як стабільний +- **наявні зовнішні plugin:** зберігайте працездатність інтеграцій на основі hook; + вважайте це базовим рівнем сумісності +- **нові вбудовані/нативні plugin:** віддавайте перевагу явній реєстрації можливостей, + а не vendor-специфічним зверненням углиб або новим дизайнам лише з hooks +- **зовнішні plugin, що переходять на реєстрацію можливостей:** це дозволено, але + вважайте допоміжні поверхні, специфічні для можливостей, такими, що еволюціонують, + якщо документація явно не позначає контракт як стабільний Практичне правило: -- API реєстрації можливостей — це бажаний напрям розвитку -- застарілі гачки залишаються найбезпечнішим шляхом без порушення сумісності для зовнішніх плагінів під час - переходу -- не всі експортовані підшляхи допоміжних засобів однаково важливі; надавайте перевагу вузькому документованому - контракту, а не випадковим допоміжним експортам +- API реєстрації можливостей — це бажаний напрям +- застарілі hooks залишаються найбезпечнішим шляхом без порушення сумісності + для зовнішніх plugin під час переходу +- не всі експортовані допоміжні підшляхи однакові; віддавайте перевагу вузькому + задокументованому контракту, а не випадковим експортам допоміжних засобів -### Форми плагінів +### Форми plugin -OpenClaw класифікує кожен завантажений плагін за формою на основі його фактичної -поведінки під час реєстрації (а не лише статичних метаданих): +OpenClaw класифікує кожен завантажений plugin за формою на основі його +фактичної поведінки під час реєстрації, а не лише статичних метаданих: - **plain-capability** -- реєструє рівно один тип можливості (наприклад, - плагін лише провайдера, як-от `mistral`) + plugin лише для provider, як-от `mistral`) - **hybrid-capability** -- реєструє кілька типів можливостей (наприклад, - `openai` володіє текстовим інференсом, мовленням, розумінням медіа та - генерацією зображень) -- **hook-only** -- реєструє лише гачки (типізовані або користувацькі), без можливостей, - інструментів, команд або сервісів -- **non-capability** -- реєструє інструменти, команди, сервіси або маршрути, але без + `openai` володіє текстовою інференцією, мовленням, розумінням медіа та генерацією зображень) +- **hook-only** -- реєструє лише hooks (типізовані або кастомні), без можливостей, + tools, commands або services +- **non-capability** -- реєструє tools, commands, services або routes, але без можливостей -Використовуйте `openclaw plugins inspect `, щоб побачити форму плагіна та -розподіл за можливостями. Докладніше див. у [довіднику CLI](/cli/plugins#inspect). +Використайте `openclaw plugins inspect `, щоб побачити форму plugin та +розподіл можливостей. Докладніше див. у [довідці CLI](/cli/plugins#inspect). -### Застарілі гачки +### Застарілі hooks -Гачок `before_agent_start` і далі підтримується як шлях сумісності для -плагінів лише з гачками. Реальні застарілі плагіни все ще від нього залежать. +Hook `before_agent_start` залишається підтримуваним як шлях сумісності для +plugin лише з hooks. Наявні реальні застарілі plugin досі від нього залежать. -Напрям розвитку: +Напрям: -- зберігати його працездатність +- зберігати його працездатним - документувати його як застарілий -- для перевизначення моделі/провайдера надавати перевагу `before_model_resolve` -- для модифікації промпту надавати перевагу `before_prompt_build` -- вилучати лише після зниження реального використання та підтвердження безпеки міграції покриттям фікстурами +- для перевизначення моделі/provider віддавати перевагу `before_model_resolve` +- для мутації prompt віддавати перевагу `before_prompt_build` +- видаляти лише після зниження реального використання і після того, як покриття + фікстурами доведе безпечність міграції ### Сигнали сумісності -Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете побачити -одну з цих позначок: +Під час виконання `openclaw doctor` або `openclaw plugins inspect ` ви можете побачити +одну з таких міток: | Сигнал | Значення | | -------------------------- | ------------------------------------------------------------ | -| **config valid** | Конфігурація коректно парситься, і плагіни успішно визначаються | -| **compatibility advisory** | Плагін використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | -| **legacy warning** | Плагін використовує `before_agent_start`, який є застарілим | -| **hard error** | Конфігурація некоректна або плагін не вдалося завантажити | +| **config valid** | Конфігурація успішно парситься, і plugin успішно розв'язуються | +| **compatibility advisory** | Plugin використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | +| **legacy warning** | Plugin використовує `before_agent_start`, який є застарілим | +| **hard error** | Конфігурація невалідна або plugin не вдалося завантажити | -Ні `hook-only`, ні `before_agent_start` не зламають ваш плагін сьогодні -- -`hook-only` є рекомендаційним сигналом, а `before_agent_start` лише спричиняє попередження. Ці -сигнали також з’являються в `openclaw status --all` і `openclaw plugins doctor`. +Ні `hook-only`, ні `before_agent_start` не зламають ваш plugin сьогодні -- +`hook-only` має дорадчий характер, а `before_agent_start` лише викликає попередження. Ці +сигнали також з'являються в `openclaw status --all` і `openclaw plugins doctor`. ## Огляд архітектури -Система плагінів OpenClaw має чотири шари: +Система plugin в OpenClaw має чотири шари: 1. **Маніфест + виявлення** - OpenClaw знаходить потенційні плагіни в налаштованих шляхах, коренях workspace, - глобальних коренях розширень і вбудованих розширеннях. Виявлення спочатку читає нативні - маніфести `openclaw.plugin.json` і маніфести підтримуваних пакетів. + OpenClaw знаходить потенційні plugin у налаштованих шляхах, коренях workspace, + глобальних коренях extension і серед вбудованих extension. Під час виявлення спочатку + читаються нативні маніфести `openclaw.plugin.json` і підтримувані bundle-маніфести. 2. **Увімкнення + валідація** - Core вирішує, чи знайдений плагін увімкнений, вимкнений, заблокований або - вибраний для ексклюзивного слота, такого як пам’ять. -3. **Завантаження середовища виконання** - Нативні плагіни OpenClaw завантажуються в процес через jiti і реєструють - можливості в центральному реєстрі. Сумісні пакети нормалізуються в - записи реєстру без імпорту коду середовища виконання. -4. **Споживання поверхонь** - Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування - провайдерів, гачки, HTTP-маршрути, команди CLI та сервіси. + Core вирішує, чи виявлений plugin увімкнений, вимкнений, заблокований або + вибраний для ексклюзивного слота, такого як memory. +3. **Завантаження runtime** + Нативні plugin OpenClaw завантажуються в процес через jiti і реєструють + можливості в центральному реєстрі. Сумісні bundles нормалізуються у записи + реєстру без імпорту коду runtime. +4. **Використання поверхонь** + Решта OpenClaw читає реєстр, щоб надавати tools, channels, налаштування provider, + hooks, HTTP routes, CLI commands і services. -Зокрема для CLI плагінів, виявлення кореневих команд розділено на дві фази: +Зокрема для CLI plugin виявлення кореневих команд розділене на дві фази: -- метадані на етапі парсингу надходять із `registerCli(..., { descriptors: [...] })` -- справжній модуль CLI плагіна може залишатися лінивим і реєструватися під час першого виклику +- метадані часу парсингу надходять із `registerCli(..., { descriptors: [...] })` +- реальний модуль CLI plugin може залишатися лінивим і реєструватися під час першого виклику -Це дозволяє зберігати код CLI, який належить плагіну, всередині плагіна, водночас даючи OpenClaw -можливість резервувати імена кореневих команд до початку парсингу. +Це дає змогу тримати код CLI, який належить plugin, всередині plugin і водночас дозволяє OpenClaw +резервувати імена кореневих команд до початку парсингу. Важлива межа проєктування: -- виявлення + валідація конфігурації мають працювати на основі **метаданих маніфесту/схеми** - без виконання коду плагіна -- нативна поведінка середовища виконання походить із шляху `register(api)` модуля плагіна +- виявлення + валідація config мають працювати на основі **метаданих manifest/schema** + без виконання коду plugin +- нативна поведінка runtime надходить із шляху `register(api)` модуля plugin -Такий поділ дає OpenClaw змогу перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни та -створювати підказки для UI/схеми ще до повної активації середовища виконання. +Такий поділ дозволяє OpenClaw валідовувати config, пояснювати відсутні/вимкнені plugin і +будувати підказки для UI/schema ще до повної активації runtime. -### Плагіни каналів і спільний інструмент повідомлень +### Channel plugin і спільний tool повідомлень -Плагінам каналів не потрібно реєструвати окремий інструмент send/edit/react для -звичайних дій у чаті. OpenClaw зберігає один спільний інструмент `message` у core, а -плагіни каналів володіють специфічним для каналу виявленням і виконанням за ним. +Channel plugin не потрібно реєструвати окремий tool для надсилання/редагування/реакцій +для звичайних дій у чаті. OpenClaw підтримує один спільний tool `message` у core, а +channel plugin відповідають за специфічне для каналу виявлення та виконання за ним. Поточна межа така: -- core володіє спільним хостом інструмента `message`, підключенням до промптів, веденням - обліку сесій/гілок і диспетчеризацією виконання -- плагіни каналів володіють виявленням дій в області видимості, виявленням можливостей і будь-якими - специфічними для каналу фрагментами схеми -- плагіни каналів володіють граматикою розмов сеансів, специфічною для провайдера, наприклад - тим, як ідентифікатори розмов кодують ідентифікатори гілок або успадковуються від батьківських розмов -- плагіни каналів виконують фінальну дію через свій адаптер дій +- core відповідає за спільний host tool `message`, підключення до prompt, + облік сесій/потоків і диспетчеризацію виконання +- channel plugin відповідають за виявлення дій у межах області, виявлення + можливостей і будь-які фрагменти schema, специфічні для каналу +- channel plugin відповідають за граматику розмови сесії, специфічну для provider, + зокрема за те, як conversation id кодують thread id або успадковуються від батьківських conversations +- channel plugin виконують фінальну дію через свій action adapter -Для плагінів каналів поверхнею SDK є -`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик виявлення -дозволяє плагіну повернути видимі дії, можливості та внески в схему разом, -щоб ці частини не розходилися. +Для channel plugin поверхнею SDK є +`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик +виявлення дозволяє plugin повертати видимі дії, можливості та внески в schema +разом, щоб ці частини не розходилися. -Core передає область середовища виконання в цей крок виявлення. Важливі поля: +Core передає до цього кроку виявлення runtime-область. Важливі поля: - `accountId` - `currentChannelId` @@ -191,123 +191,124 @@ Core передає область середовища виконання в ц - `agentId` - довірений вхідний `requesterSenderId` -Це важливо для плагінів, чутливих до контексту. Канал може приховувати або показувати -дії повідомлень залежно від активного облікового запису, поточної кімнати/гілки/повідомлення або -довіреної особи відправника запиту без жорсткого кодування специфічних для каналу гілок у -core-інструменті `message`. +Це важливо для context-sensitive plugin. Канал може приховувати або показувати +дії повідомлень залежно від активного облікового запису, поточної кімнати/потоку/повідомлення або +довіреної ідентичності запитувача без жорстко закодованих розгалужень, специфічних для каналу, +у core tool `message`. -Саме тому зміни маршрутизації embedded-runner і далі залишаються роботою плагінів: runner -відповідає за передавання поточної ідентичності чату/сесії до межі виявлення плагіна, щоб -спільний інструмент `message` показував правильну поверхню, що належить каналу, +Саме тому зміни маршрутизації embedded-runner усе ще є роботою plugin: runner +відповідає за передавання поточної ідентичності чату/сесії в межу виявлення plugin, щоб +спільний tool `message` показував правильну поверхню, що належить каналу, для поточного ходу. -Для допоміжних засобів виконання, що належать каналу, вбудовані плагіни мають зберігати середовище виконання -виконання всередині власних модулів розширення. Core більше не володіє -середовищами виконання дій повідомлень Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. +Для допоміжних засобів виконання, що належать каналу, вбудовані plugin мають тримати runtime +виконання всередині власних модулів extension. Core більше не володіє runtime +message-action для Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, і вбудовані -плагіни мають імпортувати свій локальний код середовища виконання безпосередньо зі своїх -модулів розширення. +plugin мають імпортувати свій локальний код runtime безпосередньо зі своїх +модулів extension. -Та сама межа застосовується і до загальних seams SDK з іменами провайдерів: core не має -імпортувати зручні панелі, специфічні для каналів, для Slack, Discord, Signal, -WhatsApp або подібних розширень. Якщо core потрібна певна поведінка, він має або -використовувати власну панель `api.ts` / `runtime-api.ts` вбудованого плагіна, або підвищити цю потребу -до вузької загальної можливості у спільному SDK. +Та сама межа застосовується і до SDK seam, названих на честь provider, загалом: +core не повинен імпортувати channel-специфічні convenience barrel для Slack, Discord, Signal, +WhatsApp або подібних extension. Якщо core потрібна певна поведінка, або +використовуйте власний barrel `api.ts` / `runtime-api.ts` відповідного вбудованого plugin, +або підніміть потребу в вузьку узагальнену можливість у спільному SDK. -Зокрема для опитувань є два шляхи виконання: +Зокрема для polls існують два шляхи виконання: -- `outbound.sendPoll` — спільна базова лінія для каналів, які відповідають загальній +- `outbound.sendPoll` — спільний базовий варіант для каналів, які відповідають загальній моделі опитувань -- `actions.handleAction("poll")` — бажаний шлях для специфічної для каналу +- `actions.handleAction("poll")` — бажаний шлях для channel-специфічної семантики опитувань або додаткових параметрів опитування -Тепер core відкладає спільний парсинг опитувань до моменту, коли диспетчеризація опитувань плагіна -відхилить дію, щоб обробники опитувань, що належать плагіну, могли приймати специфічні для каналу -поля опитувань, не блокуючись спочатку загальним парсером опитувань. +Тепер core відкладає спільний парсинг опитувань до моменту, коли dispatch опитування plugin +відхилить дію, щоб обробники опитувань, що належать plugin, могли приймати +channel-специфічні поля опитувань без блокування спочатку загальним парсером poll. -Повну послідовність запуску див. у розділі [Конвеєр завантаження](#load-pipeline). +Повну послідовність запуску див. у [Конвеєр завантаження](#load-pipeline). -## Модель володіння можливостями +## Модель власності можливостей -OpenClaw розглядає нативний плагін як межу володіння для **компанії** або -**функції**, а не як набір не пов’язаних між собою інтеграцій. +OpenClaw розглядає нативний plugin як межу власності для **компанії** або +**функції**, а не як набір не пов'язаних між собою інтеграцій. Це означає: -- плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, пов’язаними з цією компанією -- плагін функції зазвичай має володіти повною поверхнею функції, яку він вводить -- канали мають споживати спільні можливості core замість разового повторного - впровадження поведінки провайдера +- plugin компанії зазвичай має володіти всіма OpenClaw-поверхнями цієї компанії +- plugin функції зазвичай має володіти повною поверхнею функції, яку він вводить +- channels мають споживати спільні можливості core замість того, щоб + ситуативно перевпроваджувати поведінку provider Приклади: -- вбудований плагін `openai` володіє поведінкою провайдера моделей OpenAI та - поведінкою OpenAI для мовлення + голосу в реальному часі + розуміння медіа + генерації зображень -- вбудований плагін `elevenlabs` володіє поведінкою мовлення ElevenLabs -- вбудований плагін `microsoft` володіє поведінкою мовлення Microsoft -- вбудований плагін `google` володіє поведінкою провайдера моделей Google, а також - поведінкою Google для розуміння медіа + генерації зображень + веб-пошуку -- вбудований плагін `firecrawl` володіє поведінкою веб-отримання Firecrawl -- вбудовані плагіни `minimax`, `mistral`, `moonshot` і `zai` володіють своїми +- вбудований plugin `openai` володіє поведінкою provider моделей OpenAI і поведінкою OpenAI для + мовлення + голосу в реальному часі + розуміння медіа + генерації зображень +- вбудований plugin `elevenlabs` володіє поведінкою мовлення ElevenLabs +- вбудований plugin `microsoft` володіє поведінкою мовлення Microsoft +- вбудований plugin `google` володіє поведінкою provider моделей Google, а також поведінкою Google для + розуміння медіа + генерації зображень + вебпошуку +- вбудований plugin `firecrawl` володіє поведінкою веботримання Firecrawl +- вбудовані plugin `minimax`, `mistral`, `moonshot` і `zai` володіють своїми бекендами розуміння медіа -- плагін `voice-call` — це плагін функції: він володіє транспортом дзвінків, інструментами, - CLI, маршрутами та мостом медіапотоків Twilio, але споживає спільні можливості мовлення, - а також транскрипції в реальному часі й голосу в реальному часі замість прямого імпорту - vendor-плагінів +- вбудований plugin `qwen` володіє текстовою поведінкою provider Qwen, а також + поведінкою розуміння медіа і генерації відео +- plugin `voice-call` — це plugin функції: він володіє транспортом дзвінків, tools, + CLI, routes і мостом медіапотоків Twilio, але споживає спільні можливості мовлення, + а також транскрипції і голосу в реальному часі замість прямого імпорту vendor plugin -Бажаний кінцевий стан такий: +Бажаний кінцевий стан: -- OpenAI живе в одному плагіні, навіть якщо охоплює текстові моделі, мовлення, зображення та +- OpenAI живе в одному plugin, навіть якщо він охоплює текстові моделі, мовлення, зображення і майбутнє відео -- інший постачальник може так само зробити для власної поверхні -- каналам байдуже, який vendor-плагін володіє провайдером; вони споживають +- інший vendor може зробити те саме для власної області +- channels не турбує, який vendor plugin володіє provider; вони споживають спільний контракт можливості, який надає core Ось ключова відмінність: -- **plugin** = межа володіння -- **capability** = контракт core, який можуть реалізовувати або споживати кілька плагінів +- **plugin** = межа власності +- **можливість** = контракт core, який можуть реалізовувати або споживати кілька plugin -Отже, якщо OpenClaw додає нову доменну область, наприклад відео, перше запитання не -«який провайдер має жорстко кодувати обробку відео?». Перше запитання — «який -контракт core для можливості відео?». Коли цей контракт існує, vendor-плагіни -можуть реєструватися для нього, а плагіни каналів/функцій — споживати його. +Тому, якщо OpenClaw додає нову доменну область, наприклад відео, перше запитання не +"який provider має жорстко закодувати обробку відео?" Перше запитання — "яким є +контракт core для можливості відео?" Щойно такий контракт існує, vendor plugin +можуть реєструватися для нього, а channel/feature plugin можуть його споживати. -Якщо можливість ще не існує, правильний крок зазвичай такий: +Якщо можливість ще не існує, зазвичай правильний крок такий: 1. визначити відсутню можливість у core -2. типізовано відкрити її через API/середовище виконання плагіна -3. підключити канали/функції до цієї можливості -4. дати vendor-плагінам можливість зареєструвати реалізації +2. відкрити її через API/runtime plugin у типізований спосіб +3. під'єднати channels/features до цієї можливості +4. дозволити vendor plugin реєструвати реалізації -Це робить володіння явним і водночас уникає поведінки core, що залежить від -одного постачальника або одноразового специфічного для плагіна шляху коду. +Це зберігає явну власність і водночас уникає поведінки core, що залежить від +одного vendor або одноразового plugin-специфічного шляху коду. ### Шарування можливостей -Використовуйте цю ментальну модель, вирішуючи, де має знаходитися код: +Використовуйте цю ментальну модель, коли вирішуєте, де має бути код: -- **шар можливостей core**: спільна оркестрація, політика, резервний вибір, правила - злиття конфігурації, семантика доставки та типізовані контракти -- **шар vendor-плагіна**: специфічні для постачальника API, автентифікація, каталоги моделей, синтез мовлення, - генерація зображень, майбутні бекенди відео, кінцеві точки використання -- **шар плагіна каналу/функції**: інтеграція Slack/Discord/voice-call тощо, - яка споживає можливості core і надає їх на поверхні +- **шар можливостей core**: спільна оркестрація, політика, fallback, правила + злиття config, семантика доставки та типізовані контракти +- **шар vendor plugin**: vendor-специфічні API, auth, каталоги моделей, синтез мовлення, + генерація зображень, майбутні відеобекенди, endpoint використання +- **шар channel/feature plugin**: інтеграції Slack/Discord/voice-call/etc., + які споживають можливості core і представляють їх на певній поверхні Наприклад, TTS має таку форму: -- core володіє політикою TTS під час відповіді, порядком резервного вибору, налаштуваннями та доставкою в канал +- core володіє політикою TTS під час відповіді, порядком fallback, prefs і доставкою в канал - `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу -- `voice-call` споживає допоміжний засіб середовища виконання TTS для телефонії +- `voice-call` споживає допоміжний runtime TTS для телефонії -Такий самий шаблон слід надавати перевагу й для майбутніх можливостей. +Той самий шаблон слід віддавати перевагу і для майбутніх можливостей. -### Приклад компанійного плагіна з кількома можливостями +### Приклад plugin компанії з кількома можливостями -Компанійний плагін має виглядати цілісно ззовні. Якщо OpenClaw має спільні +Plugin компанії має виглядати цілісно ззовні. Якщо OpenClaw має спільні контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, -генерації зображень, генерації відео, веб-отримання та веб-пошуку, -постачальник може володіти всіма своїми поверхнями в одному місці: +генерації зображень, генерації відео, веботримання та вебпошуку, +vendor може володіти всіма своїми поверхнями в одному місці: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -322,12 +323,12 @@ const plugin: OpenClawPluginDefinition = { register(api) { api.registerProvider({ id: "exampleai", - // гачки auth/каталогу моделей/середовища виконання + // auth/model catalog/runtime hooks }); api.registerSpeechProvider({ id: "exampleai", - // конфігурація мовлення постачальника — безпосередньо реалізує інтерфейс SpeechProviderPlugin + // vendor speech config — implement the SpeechProviderPlugin interface directly }); api.registerMediaUnderstandingProvider({ @@ -352,7 +353,7 @@ const plugin: OpenClawPluginDefinition = { api.registerWebSearchProvider( createPluginBackedWebSearchProvider({ id: "exampleai-search", - // логіка облікових даних + отримання + // credential + fetch logic }), ); }, @@ -361,223 +362,222 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Важливі не точні назви допоміжних засобів. Важлива форма: +Важливі не точні назви helper. Важлива форма: -- один плагін володіє поверхнею постачальника -- core і далі володіє контрактами можливостей -- канали й плагіни функцій споживають допоміжні засоби `api.runtime.*`, а не код постачальника -- контрактні тести можуть перевіряти, що плагін зареєстрував ті можливості, - якими, як стверджується, він володіє +- один plugin володіє поверхнею vendor +- core все одно володіє контрактами можливостей +- channels і feature plugin споживають helper `api.runtime.*`, а не код vendor +- контрактні тести можуть перевіряти, що plugin зареєстрував можливості, якими + він заявляє, що володіє ### Приклад можливості: розуміння відео OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну -можливість. До неї застосовується та сама модель володіння: +можливість. Та сама модель власності застосовується і тут: -1. core визначає контракт розуміння медіа -2. vendor-плагіни за потреби реєструють `describeImage`, `transcribeAudio` і - `describeVideo` -3. канали та плагіни функцій споживають спільну поведінку core замість - прямого підключення до коду постачальника +1. core визначає контракт media-understanding +2. vendor plugin реєструють `describeImage`, `transcribeAudio` і + `describeVideo`, де це застосовно +3. channels і feature plugin споживають спільну поведінку core, а не + напряму під'єднуються до коду vendor -Це дозволяє не вбудовувати припущення одного провайдера щодо відео в core. Плагін володіє -поверхнею постачальника; core володіє контрактом можливості та поведінкою резервного вибору. +Це дозволяє не вбудовувати припущення одного provider щодо відео в core. Plugin володіє +поверхнею vendor; core володіє контрактом можливості та поведінкою fallback. Генерація відео вже використовує ту саму послідовність: core володіє типізованим -контрактом можливості та допоміжним засобом середовища виконання, а vendor-плагіни реєструють -реалізації `api.registerVideoGenerationProvider(...)` для нього. +контрактом можливості та helper runtime, а vendor plugin реєструють +реалізації `api.registerVideoGenerationProvider(...)` для неї. -Потрібен конкретний контрольний список розгортання? Див. -[Практичний посібник із можливостей](/uk/plugins/architecture). +Потрібен конкретний контрольний список впровадження? Див. +[Capability Cookbook](/uk/plugins/architecture). ## Контракти та контроль -Поверхня API плагінів навмисно типізована та централізована в +Поверхня API plugin навмисно типізована і централізована в `OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та -допоміжні засоби середовища виконання, на які може покладатися плагін. +helper runtime, на які plugin може покладатися. Чому це важливо: -- автори плагінів отримують один стабільний внутрішній стандарт -- core може відхиляти дублювання володіння, наприклад коли два плагіни реєструють той самий - id провайдера -- під час запуску можна показувати придатну до дії діагностику для некоректної реєстрації -- контрактні тести можуть контролювати володіння вбудованими плагінами та запобігати тихому дрейфу +- автори plugin отримують один стабільний внутрішній стандарт +- core може відхиляти дубльовану власність, наприклад коли два plugin реєструють один і той самий provider id +- під час запуску можна показувати діагностику з конкретними діями для + некоректної реєстрації +- контрактні тести можуть контролювати власність вбудованих plugin і запобігати тихому дрейфу Є два шари контролю: -1. **контроль реєстрації під час виконання** - Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Приклади: - дублікати id провайдерів, дублікати id провайдерів мовлення та некоректні - реєстрації створюють діагностику плагіна замість невизначеної поведінки. +1. **контроль реєстрації під час runtime** + Реєстр plugin валідовує реєстрації під час завантаження plugin. Приклади: + дубльовані id provider, дубльовані id provider мовлення та некоректні + реєстрації породжують діагностику plugin замість невизначеної поведінки. 2. **контрактні тести** - Вбудовані плагіни фіксуються в контрактних реєстрах під час виконання тестів, щоб - OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для - провайдерів моделей, провайдерів мовлення, провайдерів веб-пошуку та - володіння вбудованою реєстрацією. + Вбудовані plugin захоплюються в контрактні реєстри під час тестових запусків, щоб + OpenClaw міг явно перевіряти власність. Сьогодні це використовується для model + providers, speech providers, web-search providers і власності вбудованих реєстрацій. -Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який плагін якою -поверхнею володіє. Це дозволяє core і каналам безшовно поєднуватися, оскільки -володіння оголошене, типізоване та перевіряється тестами, а не є неявним. +Практичний ефект у тому, що OpenClaw наперед знає, який plugin якою +поверхнею володіє. Це дозволяє core і channels безшовно поєднуватися, оскільки +власність оголошена, типізована і піддається тестуванню, а не є неявною. -### Що має належати контракту +### Що має входити до контракту -Хороші контракти плагінів: +Хороші контракти plugin: - типізовані -- невеликі +- малі - специфічні для можливості - належать core -- придатні для повторного використання кількома плагінами -- можуть споживатися каналами/функціями без знання про постачальника +- повторно використовуються кількома plugin +- можуть споживатися channels/features без знання про vendor -Погані контракти плагінів: +Погані контракти plugin: -- політика, специфічна для постачальника, прихована в core -- одноразові обхідні шляхи для плагіна, які оминають реєстр -- код каналу, що напряму звертається до реалізації постачальника -- разові об’єкти середовища виконання, які не є частиною `OpenClawPluginApi` або +- vendor-специфічна політика, прихована в core +- одноразові лазівки для plugin, які обходять реєстр +- код каналу, який напряму лізе у vendor-реалізацію +- спеціальні runtime-об'єкти, що не входять до `OpenClawPluginApi` або `api.runtime` -Якщо сумніваєтеся, підніміть рівень абстракції: спочатку визначте можливість, а потім -дозвольте плагінам підключатися до неї. +Якщо сумніваєтеся, піднімайте рівень абстракції: спочатку визначте можливість, а +потім дозволяйте plugin підключатися до неї. ## Модель виконання -Нативні плагіни OpenClaw працюють **у процесі** разом із Gateway. Вони не -ізольовані. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що й -код core. +Нативні plugin OpenClaw працюють **у межах процесу** разом із Gateway. Вони не +ізольовані. Завантажений нативний plugin має ту саму межу довіри на рівні процесу, +що й код core. Наслідки: -- нативний плагін може реєструвати інструменти, мережеві обробники, гачки та сервіси -- помилка нативного плагіна може аварійно завершити роботу gateway або дестабілізувати його -- зловмисний нативний плагін рівнозначний довільному виконанню коду всередині процесу OpenClaw +- нативний plugin може реєструвати tools, network handlers, hooks і services +- помилка нативного plugin може призвести до аварії gateway або його дестабілізації +- зловмисний нативний plugin еквівалентний довільному виконанню коду всередині + процесу OpenClaw -Сумісні пакети за замовчуванням безпечніші, оскільки OpenClaw наразі розглядає їх -як пакети метаданих/вмісту. У поточних випусках це переважно означає вбудовані -Skills. +Сумісні bundles безпечніші за замовчуванням, тому що зараз OpenClaw розглядає їх +як набори метаданих/контенту. У поточних релізах це переважно означає +вбудовані Skills. -Для невбудованих плагінів використовуйте allowlists і явні шляхи встановлення/завантаження. Вважайте -workspace-плагіни кодом часу розробки, а не виробничими значеннями за замовчуванням. +Використовуйте allowlist і явні шляхи встановлення/завантаження для невбудованих plugin. Розглядайте +workspace plugin як код для часу розробки, а не як бойові типові значення. -Для імен пакетів у вбудованому workspace id плагіна має бути прив’язаний до npm-імені: -`@openclaw/` за замовчуванням або затверджений типізований суфікс на кшталт -`-provider`, `-plugin`, `-speech`, `-sandbox` чи `-media-understanding`, якщо -пакет навмисно надає вужчу роль плагіна. +Для назв пакетів у workspace-вбудованих plugin зберігайте прив'язку id plugin у npm-імені: +`@openclaw/` за замовчуванням або затверджений типізований суфікс, наприклад +`-provider`, `-plugin`, `-speech`, `-sandbox` або `-media-understanding`, коли +пакет навмисно відкриває вужчу роль plugin. -Важливе зауваження щодо довіри: +Важлива примітка щодо довіри: -- `plugins.allow` довіряє **id плагінів**, а не походженню джерела. -- Workspace-плагін із тим самим id, що й у вбудованого плагіна, навмисно затіняє - вбудовану копію, коли такий workspace-плагін увімкнено/додано до allowlist. +- `plugins.allow` довіряє **id plugin**, а не походженню джерела. +- workspace plugin з тим самим id, що й вбудований plugin, навмисно затіняє + вбудовану копію, коли цей workspace plugin увімкнено/додано до allowlist. - Це нормально й корисно для локальної розробки, тестування патчів і hotfix. ## Межа експорту -OpenClaw експортує можливості, а не зручні реалізації. +OpenClaw експортує можливості, а не зручні реалізаційні helper. -Зберігайте публічною реєстрацію можливостей. Скорочуйте допоміжні експорти, які не є частиною контракту: +Залишайте реєстрацію можливостей публічною. Скорочуйте експорти helper, які не є контрактом: -- підшляхи допоміжних засобів, специфічні для вбудованих плагінів -- підшляхи внутрішньої логіки середовища виконання, які не призначені як публічний API -- зручні допоміжні засоби, специфічні для постачальника -- допоміжні засоби налаштування/onboarding, що є деталями реалізації +- допоміжні підшляхи, специфічні для вбудованих plugin +- підшляхи plumbing runtime, не призначені як публічний API +- vendor-специфічні convenience helper +- helper налаштування/onboarding, які є деталями реалізації -Деякі підшляхи допоміжних засобів вбудованих плагінів усе ще залишаються у згенерованій карті експорту SDK -для сумісності та обслуговування вбудованих плагінів. Поточні приклади включають +Деякі підшляхи helper вбудованих plugin усе ще залишаються в згенерованій карті +експортів SDK для сумісності та підтримки вбудованих plugin. Поточні приклади: `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` і кілька seams `plugin-sdk/matrix*`. Розглядайте їх як +`plugin-sdk/zalo-setup` і кілька seam `plugin-sdk/matrix*`. Розглядайте їх як зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для -нових сторонніх плагінів. +нових сторонніх plugin. ## Конвеєр завантаження -Під час запуску OpenClaw приблизно виконує таке: +Під час запуску OpenClaw приблизно робить таке: -1. виявляє корені потенційних плагінів -2. читає маніфести нативних або сумісних пакетів і метадані пакетів -3. відхиляє небезпечних кандидатів -4. нормалізує конфігурацію плагінів (`plugins.enabled`, `allow`, `deny`, `entries`, +1. знаходить корені потенційних plugin +2. читає нативні або сумісні bundle-маніфести та метадані package +3. відхиляє небезпечні кандидати +4. нормалізує config plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) 5. визначає стан увімкнення для кожного кандидата 6. завантажує увімкнені нативні модулі через jiti -7. викликає нативні гачки `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру плагінів -8. відкриває реєстр для команд/поверхонь середовища виконання +7. викликає hooks нативного `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру plugin +8. відкриває реєстр для команд/поверхонь runtime -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів надавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — loader знаходить будь-який із них (`def.register ?? def.activate`) і викликає його в тій самій точці. Усі вбудовані plugin використовують `register`; для нових plugin віддавайте перевагу `register`. -Перевірки безпеки відбуваються **до** виконання під час runtime. Кандидати блокуються, -якщо точка входу виходить за межі кореня плагіна, шлях має права запису для всіх або -для невбудованих плагінів підозріло виглядає володіння шляхом. +Запобіжні перевірки відбуваються **до** виконання runtime. Кандидати блокуються, +якщо entry виходить за межі кореня plugin, шлях доступний на запис для всіх або +власність шляху виглядає підозріло для невбудованих plugin. ### Поведінка manifest-first -Маніфест — це джерело істини рівня control-plane. OpenClaw використовує його, щоб: +Маніфест є джерелом істини для control plane. OpenClaw використовує його, щоб: -- ідентифікувати плагін -- виявляти оголошені канали/Skills/схему конфігурації або можливості пакета -- перевіряти `plugins.entries..config` -- доповнювати мітки/плейсхолдери Control UI +- ідентифікувати plugin +- знаходити оголошені channels/skills/schema config або можливості bundle +- валідовувати `plugins.entries..config` +- доповнювати labels/placeholders у Control UI - показувати метадані встановлення/каталогу -Для нативних плагінів модуль середовища виконання — це частина data-plane. Він реєструє -фактичну поведінку, таку як гачки, інструменти, команди або потоки провайдера. +Для нативних plugin модуль runtime є частиною data plane. Він реєструє +фактичну поведінку, таку як hooks, tools, commands або потоки provider. -### Що кешує завантажувач +### Що кешує loader -OpenClaw зберігає короткочасні внутрішньопроцесні кеші для: +OpenClaw підтримує короткоживучі кеші в межах процесу для: - результатів виявлення - даних реєстру маніфестів -- реєстрів завантажених плагінів +- завантажених реєстрів plugin -Ці кеші зменшують пікове навантаження під час запуску та повторних виконань команд. Їх безпечно -розглядати як короткоживучі кеші продуктивності, а не як постійне сховище. +Ці кеші зменшують ривкове навантаження під час запуску та повторних команд. Їх +доречно розглядати як короткоживучі кеші продуктивності, а не як сховище. Примітка щодо продуктивності: - Установіть `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`. ## Модель реєстру -Завантажені плагіни не змінюють напряму довільні глобальні змінні core. Вони реєструються в -центральному реєстрі плагінів. +Завантажені plugin не змінюють випадкові глобальні об'єкти core напряму. Вони +реєструються в центральному реєстрі plugin. Реєстр відстежує: -- записи плагінів (ідентичність, джерело, походження, статус, діагностика) -- інструменти -- застарілі гачки й типізовані гачки -- канали -- провайдерів -- обробники gateway RPC -- HTTP-маршрути +- записи plugin (ідентичність, джерело, походження, статус, діагностика) +- tools +- застарілі hooks і типізовані hooks +- channels +- providers +- handlers Gateway RPC +- HTTP routes - реєстратори CLI -- фонові сервіси -- команди, що належать плагіну +- фонові services +- commands, що належать plugin -Потім можливості core читають із цього реєстру замість прямої взаємодії з модулями плагінів. -Це робить завантаження односпрямованим: +Після цього можливості core читають із цього реєстру замість прямої взаємодії +з модулями plugin. Це зберігає односторонність завантаження: -- модуль плагіна -> реєстрація в реєстрі -- середовище виконання core -> споживання з реєстру +- модуль plugin -> реєстрація в реєстрі +- runtime core -> споживання реєстру Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь core -потрібна лише одна точка інтеграції: «читати реєстр», а не «окремо обробляти кожен -модуль плагіна». +потрібна лише одна точка інтеграції: "читати реєстр", а не "створювати окремі special-case для кожного модуля plugin". -## Зворотні виклики прив’язки розмови +## Callback-и прив'язки conversation -Плагіни, які прив’язують розмову, можуть реагувати, коли схвалення вирішено. +Plugin, які прив'язують conversation, можуть реагувати, коли схвалення вирішено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після схвалення або відхилення -запиту на прив’язку: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати callback після +схвалення або відхилення запиту на прив'язку: ```ts export default { @@ -585,39 +585,39 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // Тепер існує прив’язка для цього плагіна + розмови. + // 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); }); }, }; ``` -Поля корисного навантаження зворотного виклику: +Поля callback payload: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` -- `binding`: визначена прив’язка для схвалених запитів -- `request`: підсумок початкового запиту, підказка від’єднання, id відправника та - метадані розмови +- `binding`: розв'язана прив'язка для схвалених запитів +- `request`: підсумок оригінального запиту, підказка від'єднання, id відправника та + метадані conversation -Цей зворотний виклик призначений лише для сповіщення. Він не змінює те, кому дозволено прив’язувати -розмову, і запускається після завершення обробки схвалення в core. +Цей callback має лише повідомний характер. Він не змінює, кому дозволено +прив'язувати conversation, і виконується після завершення обробки схвалення в core. -## Гачки середовища виконання провайдера +## Runtime-hooks provider -Тепер плагіни провайдерів мають два шари: +Тепер plugin provider мають два шари: -- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth провайдера +- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth provider до завантаження runtime, `channelEnvVars` для дешевого пошуку env/setup каналу - до завантаження runtime, а також `providerAuthChoices` для дешевих міток - onboarding/вибору auth і метаданих прапорців CLI до завантаження runtime -- гачки часу конфігурації: `catalog` / застарілий `discovery` плюс `applyConfigDefaults` -- гачки runtime: `normalizeModelId`, `normalizeTransport`, + до завантаження runtime, а також `providerAuthChoices` для дешевих + labels onboarding/auth-choice і метаданих прапорців CLI до завантаження runtime +- hooks часу config: `catalog` / застарілий `discovery` плюс `applyConfigDefaults` +- hooks runtime: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `resolveExternalAuthProfiles`, @@ -637,88 +637,88 @@ export default { `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw і далі володіє загальним циклом агента, резервним переключенням, обробкою транскриптів і -політикою інструментів. Ці гачки є поверхнею розширення для специфічної для провайдера поведінки без -потреби в повністю власному транспорті інференсу. +OpenClaw як і раніше володіє загальним циклом агента, failover, обробкою transcript і +політикою tools. Ці hooks є поверхнею розширення для поведінки provider без +потреби в повністю кастомному транспорті інференції. -Використовуйте маніфест `providerAuthEnvVars`, коли провайдер має облікові дані на основі env, -які загальні шляхи auth/status/model-picker мають бачити без завантаження runtime плагіна. -Використовуйте маніфест `providerAuthChoices`, коли поверхні CLI onboarding/auth-choice -мають знати id вибору провайдера, мітки груп і просте підключення auth одним прапорцем -без завантаження runtime провайдера. Зберігайте runtime `envVars` провайдера для -операторських підказок, таких як мітки onboarding або змінні налаштування -OAuth client-id/client-secret. +Використовуйте manifest `providerAuthEnvVars`, коли provider має облікові дані на основі env, +які загальні шляхи auth/status/model-picker мають бачити без завантаження runtime plugin. +Використовуйте manifest `providerAuthChoices`, коли поверхні onboarding/auth-choice CLI +мають знати id варіанта provider, labels груп і просте підключення auth одним прапорцем +без завантаження runtime provider. Зберігайте `envVars` runtime provider для +підказок для операторів, таких як labels onboarding або змінні налаштування OAuth +client-id/client-secret. -Використовуйте маніфест `channelEnvVars`, коли канал має auth або setup на основі env, -які загальні шляхи резервного shell-env, перевірки config/status або підказки setup +Використовуйте manifest `channelEnvVars`, коли канал має auth або setup на основі env, +які загальні шляхи shell-env fallback, перевірок config/status або prompts setup мають бачити без завантаження runtime каналу. -### Порядок гачків і спосіб використання +### Порядок hook і спосіб використання -Для плагінів моделей/провайдерів OpenClaw викликає гачки приблизно в такому порядку. -Стовпець «Коли використовувати» — це короткий посібник для прийняття рішення. +Для plugin моделей/provider OpenClaw викликає hooks приблизно в такому порядку. +Стовпчик "Коли використовувати" — це швидкий орієнтир для вибору. -| # | Гачок | Що він робить | Коли використовувати | -| --- | -------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або значеннями base URL за замовчуванням | -| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації за замовчуванням, що належать провайдеру, під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей провайдера | -| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(це не гачок плагіна)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми id моделі перед пошуком | Провайдер володіє очищенням псевдонімів до канонічного визначення моделі | -| 4 | `normalizeTransport` | Нормалізує сімейство провайдера `api` / `baseUrl` перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для користувацьких id провайдерів у тому самому сімействі транспорту | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням runtime/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із плагіном; вбудовані допоміжні засоби сімейства Google також підстраховують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування native streaming-usage до конфігурацій провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, що залежать від endpoint | -| 7 | `resolveConfigApiKey` | Визначає env-marker auth для конфігураційних провайдерів до завантаження runtime auth | Провайдер має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований резолвер AWS env-marker | -| 8 | `resolveSyntheticAuth` | Показує локальну/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | -| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth-профілі, що належать провайдеру; значення `persistence` за замовчуванням — `runtime-only` для облікових даних CLI/app | Провайдер повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token | -| 10 | `shouldDeferSyntheticProfileAuth` | Понижує збережені синтетичні заповнювачі профілів нижче auth на основі env/config | Провайдер зберігає синтетичні профілі-заповнювачі, які не мають мати пріоритет | -| 11 | `resolveDynamicModel` | Синхронний резервний варіант для id моделей провайдера, яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream id моделей | -| 12 | `prepareDynamicModel` | Асинхронний розігрів, після чого знову запускається `resolveDynamicModel` | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | -| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як embedded runner використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт core | -| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей постачальника за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе провайдера | -| 15 | `capabilities` | Метадані транскриптів/інструментарію, що належать провайдеру та використовуються спільною логікою core | Провайдеру потрібні особливості транскриптів/сімейства провайдерів | -| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить embedded runner | Провайдеру потрібне очищення схеми для сімейства транспорту | -| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження про ключові слова без навчання core правилам, специфічним для провайдера | -| 18 | `resolveReasoningOutputMode` | Вибирає native чи tagged-контракт виводу reasoning | Провайдеру потрібен tagged reasoning/final output замість native полів | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками опцій потоку | Провайдеру потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного провайдера | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдеру потрібен користувацький wire protocol, а не просто обгортка | -| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки заголовків/тіла/сумісності моделей без користувацького транспорту | -| 22 | `resolveTransportTurnState` | Приєднує native заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали native ідентичність ходу провайдера | -| 23 | `resolveWebSocketSessionPolicy` | Приєднує native WebSocket-заголовки або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику резервного вибору | -| 24 | `formatApiKey` | Форматувач auth-профілю: збережений профіль стає рядком runtime `apiKey` | Провайдер зберігає додаткові метадані auth і потребує користувацької форми runtime-токена | -| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких endpoint оновлення або політики помилки оновлення | Провайдер не вписується у спільні засоби оновлення `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка виправлення, яка додається, коли оновлення OAuth не вдається | Провайдеру потрібні власні рекомендації з виправлення auth після помилки оновлення | -| 27 | `matchesContextOverflowError` | Засіб зіставлення переповнення контекстного вікна, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики пропускають | -| 28 | `classifyFailoverReason` | Класифікація причин резервного переключення, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо | -| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-провайдерів | Провайдеру потрібне обмеження TTL кешу, специфічне для proxy | -| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення про відновлення після відсутньої auth | Провайдеру потрібна специфічна для провайдера підказка про відновлення auth | -| 31 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх підказкою постачальника | -| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, що додаються після виявлення | Провайдеру потрібні синтетичні рядки forward-compat у `models list` і в пікерах | -| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для провайдерів із binary-thinking | Провайдер надає лише бінарне thinking увімк./вимк. | -| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для підмножини моделей | -| 35 | `resolveDefaultThinkingLevel` | Рівень `/think` за замовчуванням для конкретного сімейства моделей | Провайдер володіє політикою `/think` за замовчуванням для сімейства моделей | -| 36 | `isModernModelRef` | Матчер сучасних моделей для фільтрів live-профілів і вибору smoke | Провайдер володіє зіставленням бажаних live/smoke моделей | -| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime-токен/ключ безпосередньо перед інференсом | Провайдеру потрібен обмін токенів або короткоживучі облікові дані запиту | -| 38 | `resolveUsageAuth` | Визначає облікові дані використання/білінгу для `/usage` та пов’язаних поверхонь статусу | Провайдеру потрібен користувацький парсинг токена usage/quota або інші облікові дані usage | -| 39 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для провайдера знімки usage/quota після визначення auth | Провайдеру потрібен специфічний endpoint usage або парсер корисного навантаження | -| 40 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding у пам’яті має належати плагіну провайдера | -| 41 | `buildReplayPolicy` | Повертає політику replay, що керує обробкою транскрипту для провайдера | Провайдеру потрібна власна політика транскрипту (наприклад, видалення thinking-блоків) | -| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні специфічні для провайдера переписування replay понад спільні засоби компактування | -| 43 | `validateReplayTurns` | Остаточна перевірка або зміна форми ходів replay перед embedded runner | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санації | -| 44 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | +| # | Hook | Що він робить | Коли використовувати | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Публікує config provider у `models.providers` під час генерації `models.json` | Provider володіє каталогом або типовими значеннями base URL | +| 2 | `applyConfigDefaults` | Застосовує типові значення config, що належать provider, під час матеріалізації config | Типові значення залежать від режиму auth, env або семантики сімейства моделей provider | +| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(це не hook plugin)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Provider володіє очищенням псевдонімів до канонічного розв'язання моделі | +| 4 | `normalizeTransport` | Нормалізує provider-family `api` / `baseUrl` перед загальним складанням моделі | Provider володіє очищенням транспорту для кастомних id provider у тій самій transport family | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед розв'язанням runtime/provider | Provider потребує очищення config, яке має жити разом із plugin; вбудовані helper для сімейства Google також підстраховують підтримувані записи config Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-перезаписи native streaming-usage до config providers | Provider потребує виправлень метаданих native streaming usage, що залежать від endpoint | +| 7 | `resolveConfigApiKey` | Розв'язує env-marker auth для config providers до завантаження runtime auth | Provider має власне розв'язання API-ключа env-marker; `amazon-bedrock` також має тут вбудований resolver env-marker AWS | +| 8 | `resolveSyntheticAuth` | Показує локальний/self-hosted або auth на основі config без збереження plaintext | Provider може працювати із synthetic/local marker credential | +| 9 | `resolveExternalAuthProfiles` | Накладає профілі зовнішньої auth, що належать provider; типове `persistence` — `runtime-only` для creds CLI/app | Provider повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token | +| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених synthetic placeholder profile порівняно з auth на основі env/config | Provider зберігає synthetic placeholder profiles, які не мають переважати | +| 11 | `resolveDynamicModel` | Синхронний fallback для model id provider, яких ще немає в локальному реєстрі | Provider приймає довільні upstream model id | +| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Provider потребує мережевих метаданих перед розв'язанням невідомих id | +| 13 | `normalizeResolvedModel` | Фінальний rewrite перед тим, як embedded runner використає розв'язану модель | Provider потребує rewrite транспорту, але все ще використовує core transport | +| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для vendor-моделей за іншим сумісним transport | Provider розпізнає власні моделі на proxy transport без перехоплення ролі provider | +| 15 | `capabilities` | Метадані transcript/tooling, що належать provider і використовуються спільною логікою core | Provider потрібні особливості transcript/provider-family | +| 16 | `normalizeToolSchemas` | Нормалізує schema tools до того, як їх побачить embedded runner | Provider потребує очищення schema для transport-family | +| 17 | `inspectToolSchemas` | Показує diagnostics schema, що належать provider, після нормалізації | Provider хоче попередження щодо keyword без навчання core правилам, специфічним для provider | +| 18 | `resolveReasoningOutputMode` | Вибирає контракт виводу reasoning: native чи tagged | Provider потребує tagged reasoning/final output замість native fields | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту до загальних обгорток опцій stream | Provider потребує типових параметрів запиту або очищення параметрів для конкретного provider | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях stream кастомним transport | Provider потребує кастомного wire protocol, а не лише wrapper | +| 21 | `wrapStreamFn` | Обгортка stream після застосування загальних wrapper | Provider потребує wrapper для headers/body/model compat без кастомного transport | +| 22 | `resolveTransportTurnState` | Додає native headers або metadata на один хід transport | Provider хоче, щоб загальні transport надсилали native turn identity provider | +| 23 | `resolveWebSocketSessionPolicy` | Додає native headers WebSocket або політику cool-down сесії | Provider хоче, щоб загальні transport WS налаштовували headers сесії або політику fallback | +| 24 | `formatApiKey` | Форматер auth-profile: збережений profile стає runtime-рядком `apiKey` | Provider зберігає додаткові метадані auth і потребує кастомної форми runtime token | +| 25 | `refreshOAuth` | Перевизначення OAuth refresh для кастомних endpoint refresh або політики помилок refresh | Provider не вписується у спільні refreshers `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка для виправлення, що додається, коли не вдається OAuth refresh | Provider потребує власних рекомендацій з ремонту auth після помилки refresh | +| 27 | `matchesContextOverflowError` | Matcher переповнення контекстного вікна, що належить provider | Provider має сирі помилки переповнення, які пропустять загальні heuristics | +| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить provider | Provider може зіставляти сирі API/transport помилки з rate-limit/overload тощо | +| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul provider | Provider потребує gating TTL кешу, специфічного для proxy | +| 30 | `buildMissingAuthMessage` | Замінює загальне повідомлення відновлення для відсутньої auth | Provider потребує provider-специфічної підказки для відновлення після відсутності auth | +| 31 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей з необов'язковою користувацькою підказкою про помилку | Provider потребує приховати застарілі upstream-рядки або замінити їх підказкою vendor | +| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після discovery | Provider потребує синтетичних рядків прямої сумісності в `models list` і picker-ах | +| 33 | `isBinaryThinking` | Перемикач reasoning on/off для provider з binary-thinking | Provider підтримує лише бінарне thinking on/off | +| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Provider хоче `xhigh` лише для підмножини моделей | +| 35 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Provider володіє типовою політикою `/think` для сімейства моделей | +| 36 | `isModernModelRef` | Matcher сучасних моделей для фільтрів live profile і вибору smoke | Provider володіє зіставленням бажаних моделей для live/smoke | +| 37 | `prepareRuntimeAuth` | Обмінює налаштовані credentials на фактичний runtime token/key безпосередньо перед інференцією | Provider потребує обміну token або короткоживучих облікових даних запиту | +| 38 | `resolveUsageAuth` | Розв'язує credentials використання/білінгу для `/usage` і пов'язаних поверхонь status | Provider потребує кастомного парсингу token використання/квот або інших credentials використання | +| 39 | `fetchUsageSnapshot` | Отримує та нормалізує знімки використання/квот, специфічні для provider, після розв'язання auth | Provider потребує власний endpoint використання або parser payload | +| 40 | `createEmbeddingProvider` | Створює adapter embeddings, що належить provider, для memory/search | Поведінка embeddings для memory має належати plugin provider | +| 41 | `buildReplayPolicy` | Повертає політику replay, що керує обробкою transcript для provider | Provider потребує кастомну політику transcript (наприклад, видалення блоків thinking) | +| 42 | `sanitizeReplayHistory` | Перезаписує історію replay після загального очищення transcript | Provider потребує provider-специфічні rewrite replay понад спільні helper compaction | +| 43 | `validateReplayTurns` | Фінальна валідація або зміна форми turn replay перед embedded runner | Transport provider потребує суворішої валідації ходів після загальної санітизації | +| 44 | `onModelSelected` | Запускає побічні ефекти після вибору моделі, що належать provider | Provider потребує телеметрію або власний стан, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -відповідний плагін провайдера, а потім переходять до інших плагінів провайдерів, які підтримують гачки, -доки один із них справді не змінить id моделі або transport/config. Це зберігає -працездатність shim-плагінів alias/compat без вимоги до виклику знати, який саме -вбудований плагін володіє переписуванням. Якщо жоден гачок провайдера не переписує підтримуваний -запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно -застосує це очищення сумісності. +відповідний plugin provider, а потім переходять до інших plugin provider, здатних до hooks, +доки хтось справді не змінить model id або transport/config. Це дозволяє +shim-и псевдонімів/compat provider працювати без потреби, щоб викликаючий код знав, +який саме вбудований plugin володіє rewrite. Якщо жоден hook provider не перепише +підтримуваний запис config сімейства Google, вбудований нормалізатор config Google +усе одно виконає це очищення для сумісності. -Якщо провайдеру потрібен повністю користувацький wire protocol або власний виконавець запитів, -це інший клас розширення. Ці гачки призначені для поведінки провайдера, -яка все ще виконується в межах звичайного циклу інференсу OpenClaw. +Якщо provider потребує повністю кастомного wire protocol або кастомного виконавця запитів, +це інший клас extension. Ці hooks призначені для поведінки provider, +яка все ще працює на звичайному циклі інференції OpenClaw. -### Приклад провайдера +### Приклад provider ```ts api.registerProvider({ @@ -777,116 +777,116 @@ api.registerProvider({ - Anthropic використовує `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef` - і `wrapStreamFn`, оскільки володіє forward-compat для Claude 4.6, - підказками сімейства провайдерів, рекомендаціями з виправлення auth, інтеграцією з endpoint usage, - відповідністю prompt-cache, значеннями конфігурації за замовчуванням з урахуванням auth, - політикою thinking за замовчуванням/адаптивного thinking для Claude - та специфічним для Anthropic формуванням потоку для - beta-заголовків, `/fast` / `serviceTier` і `context1m`. -- Допоміжні засоби потоку, специфічні для Claude в Anthropic, поки що залишаються у власних - публічних seams `api.ts` / `contract-api.ts` вбудованого плагіна. Ця поверхня пакета + і `wrapStreamFn`, тому що володіє прямою сумісністю вперед для Claude 4.6, + підказками щодо сімейства provider, вказівками з ремонту auth, інтеграцією з endpoint використання, + придатністю prompt-cache, типовими значеннями config з урахуванням auth, + типовою/адаптивною політикою thinking Claude та формуванням stream, + специфічним для Anthropic, для beta headers, `/fast` / `serviceTier` і `context1m`. +- Допоміжні засоби stream, специфічні для Claude в Anthropic, поки що залишаються у + власному публічному seam plugin `api.ts` / `contract-api.ts`. Ця поверхня пакета експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, - `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і допоміжні - засоби побудови обгорток Anthropic нижчого рівня замість розширення загального SDK - навколо правил beta-заголовків одного провайдера. + `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і нижчорівневі + builder-и wrapper Anthropic замість того, щоб розширювати загальний SDK навколо правил + beta headers одного provider. - OpenAI використовує `resolveDynamicModel`, `normalizeResolvedModel` і `capabilities`, а також `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` і `isModernModelRef`, - оскільки володіє forward-compat для GPT-5.4, прямою нормалізацією OpenAI - `openai-completions` -> `openai-responses`, підказками auth з урахуванням Codex, - приглушенням Spark, синтетичними рядками списку OpenAI та політикою GPT-5 thinking / - live-моделей; сімейство потоків `openai-responses-defaults` володіє - спільними native-обгортками OpenAI Responses для заголовків атрибуції, - `/fast`/`serviceTier`, деталізації тексту, native веб-пошуку Codex, - формуванням payload reasoning-compat та керуванням контекстом Responses. + тому що володіє прямою сумісністю вперед для GPT-5.4, нормалізацією + прямого OpenAI `openai-completions` -> `openai-responses`, підказками auth з урахуванням Codex, + придушенням Spark, синтетичними рядками списку OpenAI і політикою thinking / + live-model для GPT-5; сімейство stream `openai-responses-defaults` володіє + спільними native wrappers OpenAI Responses для headers атрибуції, + `/fast`/`serviceTier`, деталізації тексту, native вебпошуку Codex, + формування payload reasoning-compat і керування контекстом Responses. - OpenRouter використовує `catalog`, а також `resolveDynamicModel` і - `prepareDynamicModel`, оскільки провайдер є pass-through і може відкривати нові - id моделей до оновлення статичного каталогу OpenClaw; він також використовує + `prepareDynamicModel`, тому що provider є наскрізним і може відкривати нові + model id до оновлення статичного каталогу OpenClaw; він також використовує `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб тримати - специфічні для провайдера заголовки запитів, метадані маршрутизації, патчі reasoning і - політику prompt-cache поза core. Його політика replay походить із сімейства - `passthrough-gemini`, тоді як сімейство потоків `openrouter-thinking` - володіє ін’єкцією proxy reasoning і пропусками для непідтримуваних моделей / `auto`. + provider-специфічні headers запитів, metadata маршрутизації, патчі reasoning і + політику prompt-cache поза core. Його replay policy надходить від сімейства + `passthrough-gemini`, тоді як сімейство stream `openrouter-thinking` + володіє ін'єкцією proxy reasoning і пропусками для непідтримуваних моделей / `auto`. - GitHub Copilot використовує `catalog`, `auth`, `resolveDynamicModel` і - `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, оскільки - йому потрібні власний device login, поведінка резервного вибору моделі, - особливості транскриптів Claude, обмін токена GitHub на токен Copilot - і власний endpoint usage. + `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, + тому що йому потрібні login пристрою, що належать provider, поведінка fallback моделей, + особливості transcript Claude, обмін GitHub token -> Copilot token і + endpoint використання, що належить provider. - OpenAI Codex використовує `catalog`, `resolveDynamicModel`, `normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog`, а також - `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки - він і далі працює на core-транспортах OpenAI, але володіє нормалізацією - transport/base URL, політикою резервного оновлення OAuth, вибором транспорту за замовчуванням, - синтетичними рядками каталогу Codex та інтеграцією з endpoint usage ChatGPT; він - спільно використовує сімейство потоків `openai-responses-defaults` із прямим OpenAI. + `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, + тому що він усе ще працює на core transport OpenAI, але володіє своєю + нормалізацією transport/base URL, політикою fallback для OAuth refresh, + типовим вибором transport, синтетичними рядками каталогу Codex і інтеграцією з + endpoint використання ChatGPT; він використовує те саме сімейство stream + `openai-responses-defaults`, що й прямий OpenAI. - Google AI Studio і Gemini CLI OAuth використовують `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, - `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, оскільки - сімейство replay `google-gemini` володіє резервним варіантом forward-compat для Gemini 3.1, - native-перевіркою replay Gemini, санацією replay початкового завантаження, - режимом виводу reasoning з тегами та зіставленням сучасних моделей, тоді як - сімейство потоків `google-thinking` володіє нормалізацією payload thinking Gemini; + `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, тому що + сімейство replay `google-gemini` володіє fallback прямої сумісності вперед для Gemini 3.1, + native валідацією replay Gemini, санітизацією bootstrap replay, режимом + tagged reasoning-output і зіставленням сучасних моделей, тоді як + сімейство stream `google-thinking` володіє нормалізацією payload thinking Gemini; Gemini CLI OAuth також використовує `formatApiKey`, `resolveUsageAuth` і - `fetchUsageSnapshot` для форматування токенів, парсингу токенів і підключення + `fetchUsageSnapshot` для форматування token, парсингу token і підключення endpoint квот. - Anthropic Vertex використовує `buildReplayPolicy` через - сімейство replay `anthropic-by-model`, щоб очищення replay, специфічне для Claude, залишалося - прив’язаним до id Claude, а не до кожного транспорту `anthropic-messages`. + сімейство replay `anthropic-by-model`, щоб очищення replay, специфічне для Claude, + залишалося обмеженим ідентифікаторами Claude, а не всіма transport `anthropic-messages`. - Amazon Bedrock використовує `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` і `resolveDefaultThinkingLevel`, оскільки володіє - класифікацією помилок throttle/not-ready/context-overflow, специфічною для Bedrock, - для трафіку Anthropic-on-Bedrock; його політика replay все ще використовує той самий - guard `anthropic-by-model`, лише для Claude. + `classifyFailoverReason` і `resolveDefaultThinkingLevel`, тому що володіє + Bedrock-специфічною класифікацією помилок throttle/not-ready/context-overflow + для трафіку Anthropic-on-Bedrock; його replay policy при цьому все ще використовує той самий + guard `anthropic-by-model`, обмежений Claude. - OpenRouter, Kilocode, Opencode і Opencode Go використовують `buildReplayPolicy` - через сімейство replay `passthrough-gemini`, оскільки вони проксіюють моделі Gemini - через транспорти, сумісні з OpenAI, і потребують санації підпису думок Gemini - без native-перевірки replay Gemini або переписування початкового завантаження. + через сімейство replay `passthrough-gemini`, тому що вони проксіюють моделі Gemini + через transport, сумісні з OpenAI, і потребують санітизації + thought-signature Gemini без native валідації replay Gemini або rewrite bootstrap. - MiniMax використовує `buildReplayPolicy` через - сімейство replay `hybrid-anthropic-openai`, оскільки один провайдер володіє і - семантикою повідомлень Anthropic, і семантикою, сумісною з OpenAI; він зберігає - видалення thinking-блоків лише для Claude на стороні Anthropic, водночас перевизначаючи режим - виводу reasoning назад на native, а сімейство потоків `minimax-fast-mode` володіє - переписуванням моделей fast-mode на спільному шляху потоку. -- Moonshot використовує `catalog`, а також `wrapStreamFn`, оскільки він усе ще використовує спільний - транспорт OpenAI, але потребує нормалізації payload thinking, що належить провайдеру; - сімейство потоків `moonshot-thinking` зіставляє config плюс стан `/think` зі своїм - native payload binary thinking. + сімейство replay `hybrid-anthropic-openai`, тому що один provider володіє і + семантикою повідомлень Anthropic, і OpenAI-compatible; він зберігає видалення + блоків thinking лише для Claude з боку Anthropic, одночасно перевизначаючи режим + reasoning output назад на native, а сімейство stream `minimax-fast-mode` володіє + rewrite моделей fast-mode на спільному шляху stream. +- Moonshot використовує `catalog` і `wrapStreamFn`, тому що він усе ще + використовує спільний transport OpenAI, але потребує нормалізації payload thinking, + що належить provider; сімейство stream `moonshot-thinking` зіставляє config і стан `/think` + на його native binary payload thinking. - Kilocode використовує `catalog`, `capabilities`, `wrapStreamFn` і - `isCacheTtlEligible`, оскільки йому потрібні заголовки запитів, що належать провайдеру, - нормалізація payload reasoning, підказки транскриптів Gemini і - обмеження Anthropic cache-TTL; сімейство потоків `kilocode-thinking` зберігає ін’єкцію - thinking Kilo на спільному шляху proxy-потоку, водночас пропускаючи `kilo/auto` та - інші proxy-id моделей, які не підтримують явні payload reasoning. + `isCacheTtlEligible`, тому що йому потрібні headers запитів, що належать provider, + нормалізація payload reasoning, підказки transcript Gemini та gating + Anthropic cache-TTL; сімейство stream `kilocode-thinking` зберігає ін'єкцію + thinking Kilo на спільному шляху proxy stream, пропускаючи `kilo/auto` та + інші id proxy-моделей, які не підтримують явний payload reasoning. - Z.AI використовує `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки володіє резервним варіантом GLM-5, - значеннями `tool_stream` за замовчуванням, UX бінарного thinking, зіставленням сучасних моделей - та і auth для usage, і отриманням квот; сімейство потоків `tool-stream-default-on` - тримає обгортку `tool_stream`, увімкнену за замовчуванням, поза рукописним glue - для окремих провайдерів. + `resolveUsageAuth` і `fetchUsageSnapshot`, тому що володіє fallback для GLM-5, + типовими значеннями `tool_stream`, UX binary thinking, зіставленням сучасних моделей + і як auth використання, так і отриманням квот; сімейство stream `tool-stream-default-on` + не дає wrapper за замовчуванням увімкненого `tool_stream` перетворитися на + рукописний клей для кожного provider. - xAI використовує `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` і `isModernModelRef`, - оскільки володіє нормалізацією native xAI Responses transport, переписуванням псевдонімів - Grok fast-mode, `tool_stream` за замовчуванням, очищенням strict-tool / reasoning-payload, - повторним використанням резервної auth для інструментів, що належать плагіну, визначенням - моделей Grok з forward-compat і compat-патчами, що належать провайдеру, такими як профіль - схем інструментів xAI, непідтримувані ключові слова схеми, native `web_search` та декодування - аргументів виклику інструментів із HTML-entity. + тому що володіє нормалізацією native transport xAI Responses, rewrite псевдонімів + fast-mode для Grok, типовим `tool_stream`, очищенням strict-tool / reasoning-payload, + повторним використанням fallback auth для tools, що належать plugin, прямим розв'язанням + моделей Grok для сумісності вперед і compat-патчами, що належать provider, такими як профіль + schema tools xAI, непідтримувані keywords schema, native `web_search` і декодування + аргументів tool-call із HTML-сутностями. - Mistral, OpenCode Zen і OpenCode Go використовують лише `capabilities`, щоб - тримати особливості транскриптів/інструментарію поза core. -- Каталогові вбудовані провайдери, такі як `byteplus`, `cloudflare-ai-gateway`, + тримати особливості transcript/tooling поза core. +- Провайдери, вбудовані лише з catalog, такі як `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і `volcengine`, використовують лише `catalog`. -- Qwen використовує `catalog` для свого текстового провайдера, а також спільні реєстрації - розуміння медіа й генерації відео для своїх мультимодальних поверхонь. -- MiniMax і Xiaomi використовують `catalog` плюс гачки usage, оскільки їхня поведінка `/usage` - належить плагіну, навіть попри те, що інференс усе ще виконується через спільні транспорти. +- Qwen використовує `catalog` для свого текстового provider, а також спільні + реєстрації media-understanding і video-generation для своїх мультимодальних поверхонь. +- MiniMax і Xiaomi використовують `catalog` плюс hooks використання, тому що їхня поведінка `/usage` + належить plugin, навіть якщо інференція все ще виконується через спільні transport. -## Допоміжні засоби середовища виконання +## Допоміжні засоби runtime -Плагіни можуть отримувати доступ до вибраних допоміжних засобів core через `api.runtime`. Для TTS: +Plugin можуть отримувати доступ до вибраних helper core через `api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -907,14 +907,14 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайне корисне навантаження виводу TTS із core для поверхонь файлів/голосових повідомлень. -- Використовує конфігурацію core `messages.tts` і вибір провайдера. -- Повертає PCM-аудіобуфер + частоту дискретизації. Плагіни мають виконувати ресемплінг/кодування для провайдерів. -- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для вибору голосів, що належать постачальнику, або потоків setup. -- Списки голосів можуть містити багатші метадані, такі як мова, стать і теги особистості для вибору, орієнтованого на провайдера. -- Сьогодні телефонію підтримують OpenAI і ElevenLabs. Microsoft — ні. +- `textToSpeech` повертає звичайний payload TTS core для поверхонь файлів/голосових повідомлень. +- Використовує config core `messages.tts` і вибір provider. +- Повертає PCM audio buffer + sample rate. Plugin мають виконувати ресемплінг/кодування для providers. +- `listVoices` є необов'язковим для кожного provider. Використовуйте його для picker-ів голосів або потоків setup, що належать vendor. +- Списки голосів можуть містити багатші metadata, такі як locale, gender і теги personality для picker-ів, що враховують provider. +- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. -Плагіни також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. +Plugin також можуть реєструвати speech providers через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -934,15 +934,15 @@ api.registerSpeechProvider({ Примітки: -- Зберігайте політику TTS, резервний вибір і доставку відповідей у core. -- Використовуйте провайдерів мовлення для поведінки синтезу, що належить постачальнику. -- Застарілий вхід Microsoft `edge` нормалізується до id провайдера `microsoft`. -- Бажана модель володіння орієнтована на компанію: один vendor-плагін може володіти - текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами в міру додавання - OpenClaw контрактів цих можливостей. +- Тримайте політику TTS, fallback і доставку відповідей у core. +- Використовуйте speech providers для поведінки синтезу, що належить vendor. +- Застарілий вхід Microsoft `edge` нормалізується до id provider `microsoft`. +- Бажана модель власності — орієнтована на компанію: один vendor plugin може володіти + text, speech, image і майбутніми media providers у міру того, як OpenClaw додає ці + контракти можливостей. -Для розуміння зображень/аудіо/відео плагіни реєструють один типізований -провайдер розуміння медіа замість узагальненого набору ключ/значення: +Для розуміння зображень/аудіо/відео plugin реєструють один типізований +provider media-understanding замість узагальненого key/value bag: ```ts api.registerMediaUnderstandingProvider({ @@ -956,16 +956,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Зберігайте оркестрацію, резервний вибір, конфігурацію та підключення каналів у core. -- Зберігайте поведінку постачальника в плагіні провайдера. -- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові - поля результату, нові необов’язкові можливості. +- Оркестрацію, fallback, config і підключення каналів тримайте в core. +- Поведінку vendor тримайте в plugin provider. +- Розширення мають залишатися адитивно типізованими: нові необов'язкові методи, + нові необов'язкові поля результату, нові необов'язкові можливості. - Генерація відео вже дотримується того самого шаблону: - - core володіє контрактом можливості та допоміжним засобом середовища виконання - - vendor-плагіни реєструють `api.registerVideoGenerationProvider(...)` - - плагіни функцій/каналів споживають `api.runtime.videoGeneration.*` + - core володіє контрактом можливості та helper runtime + - vendor plugin реєструють `api.registerVideoGenerationProvider(...)` + - feature/channel plugin споживають `api.runtime.videoGeneration.*` -Для допоміжних засобів середовища виконання розуміння медіа плагіни можуть викликати: +Для helper runtime media-understanding plugin можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -980,27 +980,27 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрипції аудіо плагіни можуть використовувати або середовище виконання розуміння медіа, -або старий псевдонім STT: +Для транскрипції аудіо plugin можуть використовувати або runtime media-understanding, +або старіший псевдонім 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", }); ``` Примітки: -- `api.runtime.mediaUnderstanding.*` — бажана спільна поверхня для +- `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для розуміння зображень/аудіо/відео. -- Використовує конфігурацію аудіо розуміння медіа core (`tools.media.audio`) і порядок резервного вибору провайдерів. -- Повертає `{ text: undefined }`, якщо вихід транскрипції не створено (наприклад, для пропущеного/непідтримуваного вводу). +- Використовує config аудіо media-understanding у core (`tools.media.audio`) і порядок fallback provider. +- Повертає `{ text: undefined }`, коли вихід транскрипції не створено (наприклад, для пропущеного/непідтримуваного вводу). - `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності. -Плагіни також можуть запускати фонові підагентні виконання через `api.runtime.subagent`: +Plugin також можуть запускати фонові запуски subagent через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -1014,14 +1014,14 @@ const result = await api.runtime.subagent.run({ Примітки: -- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. -- OpenClaw застосовує ці поля перевизначення лише для довірених викликачів. -- Для резервних запусків, що належать плагіну, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни певними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі. -- Недовірені запуски підагентів із плагінів теж працюють, але запити на перевизначення відхиляються, а не тихо переводяться на резервний варіант. +- `provider` і `model` — це необов'язкові перевизначення на один запуск, а не постійні зміни сесії. +- OpenClaw враховує ці поля перевизначення лише для довірених викликаючих. +- Для запусків fallback, що належать plugin, оператори мають явним чином дозволити це через `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugin конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі. +- Запуски subagent із недовірених plugin усе ще працюють, але запити на перевизначення відхиляються, а не безшумно повертаються до fallback. -Для веб-пошуку плагіни можуть використовувати спільний допоміжний засіб середовища виконання -замість звернення до підключення інструмента агента: +Для вебпошуку plugin можуть споживати спільний helper runtime замість +звернення до підключення agent tool: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1037,14 +1037,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Плагіни також можуть реєструвати провайдерів веб-пошуку через +Plugin також можуть реєструвати web-search providers через `api.registerWebSearchProvider(...)`. Примітки: -- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у core. -- Використовуйте провайдерів веб-пошуку для транспортів пошуку, специфічних для постачальника. -- `api.runtime.webSearch.*` — бажана спільна поверхня для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. +- Тримайте вибір provider, розв'язання credentials і спільну семантику запитів у core. +- Використовуйте web-search providers для transport пошуку, специфічних для vendor. +- `api.runtime.webSearch.*` — це бажана спільна поверхня для feature/channel plugin, яким потрібна поведінка пошуку без залежності від wrapper agent tool. ### `api.runtime.imageGeneration` @@ -1059,12 +1059,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: згенерувати зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. -- `listProviders(...)`: перелічити доступних провайдерів генерації зображень і їхні можливості. +- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка provider генерації зображень. +- `listProviders(...)`: показує доступні providers генерації зображень і їхні можливості. -## HTTP-маршрути Gateway +## HTTP routes Gateway -Плагіни можуть відкривати HTTP endpoint-и через `api.registerHttpRoute(...)`. +Plugin можуть відкривати HTTP endpoints через `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -1079,36 +1079,36 @@ api.registerHttpRoute({ }); ``` -Поля маршруту: +Поля route: -- `path`: шлях маршруту під HTTP-сервером gateway. -- `auth`: обов’язково. Використовуйте `"gateway"` для вимоги звичайної auth gateway або `"plugin"` для auth/перевірки webhook, якими керує плагін. -- `match`: необов’язково. `"exact"` (за замовчуванням) або `"prefix"`. -- `replaceExisting`: необов’язково. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту. -- `handler`: повертайте `true`, коли маршрут обробив запит. +- `path`: шлях route під HTTP server gateway. +- `auth`: обов'язково. Використовуйте `"gateway"`, щоб вимагати звичайну auth gateway, або `"plugin"` для auth/webhook verification, якими керує plugin. +- `match`: необов'язково. `"exact"` (типово) або `"prefix"`. +- `replaceExisting`: необов'язково. Дозволяє тому самому plugin замінити власну наявну реєстрацію route. +- `handler`: повертайте `true`, коли route обробив запит. Примітки: -- `api.registerHttpHandler(...)` було видалено, і його використання спричинить помилку завантаження плагіна. Натомість використовуйте `api.registerHttpRoute(...)`. -- Маршрути плагінів мають явно оголошувати `auth`. -- Конфлікти точного `path + match` відхиляються, якщо не встановлено `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. -- Маршрути, що перекриваються, з різними рівнями `auth` відхиляються. Ланцюги проходження `exact`/`prefix` мають бути лише на одному рівні auth. -- Маршрути `auth: "plugin"` **не** отримують автоматично області runtime оператора. Вони призначені для webhook/перевірки підпису, якими керує плагін, а не для привілейованих викликів допоміжних засобів Gateway. -- Маршрути `auth: "gateway"` виконуються в межах області runtime запиту Gateway, але ця область навмисно є консервативною: - - bearer-аутентифікація зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області runtime маршрутів плагінів на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` - - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах до маршрутів плагіна з ідентичністю, область runtime повертається до `operator.write` -- Практичне правило: не вважайте маршрут плагіна з gateway-auth неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з носієм ідентичності та документуйте явний контракт заголовка `x-openclaw-scopes`. +- `api.registerHttpHandler(...)` було видалено, і він спричинить помилку завантаження plugin. Використовуйте натомість `api.registerHttpRoute(...)`. +- Plugin routes мають явно оголошувати `auth`. +- Конфлікти точних `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінювати route іншого plugin. +- Перекривні routes з різними рівнями `auth` відхиляються. Ланцюжки fallthrough `exact`/`prefix` мають залишатися лише в межах одного рівня auth. +- Routes `auth: "plugin"` **не** отримують автоматично operator runtime scope. Вони призначені для webhook/signature verification, якими керує plugin, а не для привілейованих helper-викликів Gateway. +- Routes `auth: "gateway"` працюють усередині runtime scope запиту Gateway, але ця область навмисно консервативна: + - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) тримає runtime scope route plugin на рівні `operator.write`, навіть якщо викликаючий надсилає `x-openclaw-scopes` + - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей header явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах plugin-route з ідентичністю, runtime scope повертається до `operator.write` +- Практичне правило: не припускайте, що route plugin з auth gateway автоматично є поверхнею адміністратора. Якщо вашому route потрібна лише admin-поведінка, вимагайте auth-режим з ідентичністю і документуйте явний контракт header `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK -Під час створення плагінів використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`: +Під час створення plugin використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`: -- `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації плагінів. -- `openclaw/plugin-sdk/core` для загального спільного контракту, орієнтованого на плагіни. -- `openclaw/plugin-sdk/config-schema` для експорту Zod-схеми кореневого `openclaw.json` - (`OpenClawSchema`). -- Стабільні примітиви каналів, такі як `openclaw/plugin-sdk/channel-setup`, +- `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації plugin. +- `openclaw/plugin-sdk/core` для узагальненого спільного контракту для plugin. +- `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod schema + `openclaw.json` (`OpenClawSchema`). +- Стабільні channel-примітиви, такі як `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/setup-tools`, @@ -1121,14 +1121,14 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/command-auth`, `openclaw/plugin-sdk/secret-input` і `openclaw/plugin-sdk/webhook-ingress` для спільного підключення - setup/auth/reply/webhook. `channel-inbound` — це спільний дім для debounce, зіставлення згадок, - допоміжних засобів політики згадок у вхідних повідомленнях, форматування конвертів і - допоміжних засобів контексту вхідних конвертів. - `channel-setup` — це вузький seam setup з необов’язковим встановленням. - `setup-runtime` — це безпечна для runtime поверхня setup, що використовується `setupEntry` / - відкладеним запуском, включно з адаптерами патчів setup, безпечними для імпорту. - `setup-adapter-runtime` — це seam env-aware адаптера налаштування облікового запису. - `setup-tools` — це невеликий seam допоміжних засобів CLI/архівів/документації (`formatCliCommand`, + setup/auth/reply/webhook. `channel-inbound` є спільним місцем для debounce, + зіставлення mention, helper-ів вхідної політики mention, форматування envelope та + helper-ів контексту вхідних envelope. + `channel-setup` — це вузький seam setup для необов'язкового встановлення. + `setup-runtime` — це безпечна для runtime поверхня setup, яку використовують `setupEntry` / + відкладений запуск, включно з adapter-ами патчів setup, безпечними для імпорту. + `setup-adapter-runtime` — це seam adapter налаштування облікових записів із урахуванням env. + `setup-tools` — це малий seam helper для CLI/archive/docs (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). - Доменні підшляхи, такі як `openclaw/plugin-sdk/channel-config-helpers`, @@ -1136,6 +1136,7 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-config-schema`, `openclaw/plugin-sdk/telegram-command-config`, `openclaw/plugin-sdk/channel-policy`, + `openclaw/plugin-sdk/approval-handler-runtime`, `openclaw/plugin-sdk/approval-runtime`, `openclaw/plugin-sdk/config-runtime`, `openclaw/plugin-sdk/infra-runtime`, @@ -1146,195 +1147,198 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, `openclaw/plugin-sdk/runtime-store` і - `openclaw/plugin-sdk/directory-runtime` для спільних допоміжних засобів runtime/config. - `telegram-command-config` — це вузький публічний seam для нормалізації/валідації - користувацьких команд Telegram і він залишається доступним, навіть якщо поверхня контракту + `openclaw/plugin-sdk/directory-runtime` для спільних helper runtime/config. + `telegram-command-config` — це вузький публічний seam для нормалізації/валідації кастомних + команд Telegram і він залишається доступним, навіть якщо поверхня контракту вбудованого Telegram тимчасово недоступна. - `text-runtime` — це спільний seam text/markdown/logging, зокрема - видалення тексту, видимого асистенту, допоміжні засоби рендерингу/фрагментації markdown, редагування, - допоміжні засоби тегів директив і безпечний текст. -- Для специфічних каналів seam-ів схвалення слід надавати перевагу одному контракту - `approvalCapability` на плагіні. Тоді core читає auth, доставку, рендеринг і - native-routing для схвалення через цю одну можливість замість змішування - поведінки схвалення з не пов’язаними полями плагіна. -- `openclaw/plugin-sdk/channel-runtime` є застарілим і зберігається лише як - shim сумісності для старіших плагінів. Новий код має імпортувати вужчі - загальні примітиви, і код репозиторію не повинен додавати нові імпорти цього - shim. -- Внутрішні компоненти вбудованих розширень залишаються приватними. Зовнішні плагіни мають використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код core/тестів OpenClaw може використовувати - публічні точки входу репозиторію під коренем пакета плагіна, такі як `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js` і вузькоспрямовані файли, як-от - `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з core або з - іншого розширення. -- Поділ точок входу репозиторію: - `/api.js` — панель допоміжних засобів/типів, - `/runtime-api.js` — панель лише для runtime, - `/index.js` — точка входу вбудованого плагіна, - а `/setup-entry.js` — точка входу setup-плагіна. -- Поточні приклади вбудованих провайдерів: - - Anthropic використовує `api.js` / `contract-api.js` для допоміжних засобів потоку Claude, таких - як `wrapAnthropicProviderStream`, допоміжні засоби beta-заголовків і парсинг `service_tier`. - - OpenAI використовує `api.js` для builder-ів провайдера, допоміжних засобів моделі за замовчуванням і - builder-ів провайдера реального часу. - - OpenRouter використовує `api.js` для свого builder-а провайдера, а також допоміжних засобів onboarding/config, - тоді як `register.runtime.js` усе ще може повторно експортувати загальні - допоміжні засоби `plugin-sdk/provider-stream` для локального використання в репозиторії. -- Публічні точки входу, завантажувані через facade, надають перевагу активному знімку конфігурації runtime, - якщо він існує, а потім повертаються до визначеного файла конфігурації на диску, коли - OpenClaw ще не надає знімок runtime. -- Загальні спільні примітиви залишаються бажаним публічним контрактом SDK. Невеликий - зарезервований набір seams з брендингом вбудованих каналів для сумісності все ще існує. - Розглядайте їх як seams для обслуговування/сумісності вбудованих компонентів, а не як нові цілі імпорту для сторонніх плагінів; нові міжканальні контракти все одно мають - потрапляти в загальні підшляхи `plugin-sdk/*` або локальні панелі `api.js` / - `runtime-api.js` плагіна. + `text-runtime` — це спільний seam text/markdown/logging, включно з + видаленням assistant-visible-text, helper-ами рендерингу/розбиття markdown, helper-ами + редагування, helper-ами directive-tag і утилітами safe-text. +- Approval-специфічні channel seam мають віддавати перевагу одному контракту + `approvalCapability` на plugin. Тоді core читає auth, delivery, render, + native-routing і ліниву поведінку native-handler для approval через цю одну можливість, + а не змішує поведінку approval з не пов'язаними полями plugin. +- `openclaw/plugin-sdk/channel-runtime` є застарілим і залишається лише як shim + сумісності для старіших plugin. Новий код має імпортувати вузькіші загальні примітиви, а + код репозиторію не повинен додавати нові імпорти цього shim. +- Внутрішні частини вбудованих extension залишаються приватними. Зовнішні plugin мають + використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код core/test OpenClaw може + використовувати публічні entry point репозиторію під коренем пакета plugin, такі як `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js` і вузько спрямовані файли, наприклад + `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета plugin із core або з + іншого extension. +- Розділення entry point у репозиторії: + `/api.js` — це barrel helper/types, + `/runtime-api.js` — це barrel лише для runtime, + `/index.js` — це entry вбудованого plugin, + а `/setup-entry.js` — це entry plugin setup. +- Поточні приклади вбудованих provider: + - Anthropic використовує `api.js` / `contract-api.js` для helper stream Claude, таких + як `wrapAnthropicProviderStream`, helper-и beta-header і парсинг `service_tier`. + - OpenAI використовує `api.js` для builder-ів provider, helper-ів типових моделей і builder-ів provider realtime. + - OpenRouter використовує `api.js` для свого builder-а provider, а також helper-ів onboarding/config, + тоді як `register.runtime.js` і далі може повторно експортувати загальні + helper `plugin-sdk/provider-stream` для локального використання в репозиторії. +- Публічні entry point, завантажені через facade, віддають перевагу активному snapshot config runtime, + якщо він існує, а потім переходять до розв'язаного config-файлу на диску, коли + OpenClaw ще не надає snapshot runtime. +- Загальні примітиви залишаються бажаним публічним контрактом SDK. Невеликий + зарезервований набір сумісності з helper seam вбудованих каналів, названих на їхню честь, усе ще існує. + Розглядайте їх як seam підтримки вбудованих/сумісності, а не нові цілі імпорту + для сторонніх рішень; нові міжканальні контракти, як і раніше, мають + потрапляти у загальні підшляхи `plugin-sdk/*` або локальні barrel-и plugin `api.js` / + `runtime-api.js`. Примітка щодо сумісності: -- Уникайте кореневої панелі `openclaw/plugin-sdk` у новому коді. -- Спочатку надавайте перевагу вузьким стабільним примітивам. Новіші підшляхи +- Уникайте кореневого barrel `openclaw/plugin-sdk` у новому коді. +- Насамперед віддавайте перевагу вузьким стабільним примітивам. Новіші підшляхи setup/pairing/reply/feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool — це бажаний контракт для нової роботи - з вбудованими та зовнішніми плагінами. - Парсинг/зіставлення цілей має належати `openclaw/plugin-sdk/channel-targets`. - Шлюзи дій повідомлень і допоміжні засоби id повідомлень для реакцій мають належати + allowlist/status/message-tool — це бажаний контракт для нової роботи з + вбудованими та зовнішніми plugin. + Парсинг/зіставлення цілей має бути в `openclaw/plugin-sdk/channel-targets`. + Гейти message action і helper-и message-id для реакцій мають бути в `openclaw/plugin-sdk/channel-actions`. -- Панелі допоміжних засобів, специфічні для вбудованих розширень, не є стабільними за замовчуванням. Якщо - допоміжний засіб потрібен лише вбудованому розширенню, тримайте його за локальним seam - `api.js` або `runtime-api.js` цього розширення замість винесення в +- Допоміжні barrel-и, специфічні для вбудованих extension, за замовчуванням нестабільні. Якщо + helper потрібен лише вбудованому extension, тримайте його за локальним seam + `api.js` або `runtime-api.js` цього extension, а не просувайте в `openclaw/plugin-sdk/`. -- Нові seams спільних допоміжних засобів мають бути загальними, а не брендовими для каналу. Спільний парсинг цілей - належить `openclaw/plugin-sdk/channel-targets`; специфічні для каналу - внутрішні компоненти залишаються за локальним seam `api.js` або `runtime-api.js` - плагіна-власника. +- Нові спільні helper seam мають бути загальними, а не названими на честь каналу. Спільний парсинг цілей + має бути в `openclaw/plugin-sdk/channel-targets`; channel-специфічні + внутрішні частини мають залишатися за локальним seam `api.js` або `runtime-api.js` + відповідного plugin. - Підшляхи, специфічні для можливостей, такі як `image-generation`, - `media-understanding` і `speech`, існують, тому що вбудовані/нативні плагіни використовують - їх сьогодні. Їх наявність сама по собі не означає, що кожен експортований допоміжний засіб є - довгостроковим зафіксованим зовнішнім контрактом. + `media-understanding` і `speech`, існують тому, що вбудовані/нативні plugin використовують + їх сьогодні. Їхня наявність сама по собі не означає, що кожен експортований helper є + довгостроковим замороженим зовнішнім контрактом. -## Схеми інструмента повідомлень +## Schema tool повідомлень -Плагіни мають володіти внесками в схему `describeMessageTool(...)`, специфічними для каналу. -Тримайте поля, специфічні для провайдера, у плагіні, а не в спільному core. +Plugin мають володіти channel-специфічними внесками schema в `describeMessageTool(...)`. +Тримайте provider-специфічні поля в plugin, а не в спільному core. -Для спільних переносних фрагментів схеми повторно використовуйте загальні допоміжні засоби, експортовані через +Для спільних портативних фрагментів schema повторно використовуйте загальні helper, експортовані через `openclaw/plugin-sdk/channel-actions`: -- `createMessageToolButtonsSchema()` для корисного навантаження у стилі сітки кнопок -- `createMessageToolCardSchema()` для структурованого корисного навантаження карток +- `createMessageToolButtonsSchema()` для payload у стилі сітки кнопок +- `createMessageToolCardSchema()` для структурованих payload карток -Якщо форма схеми має сенс лише для одного провайдера, визначайте її у вихідному коді -цього плагіна, а не виносьте до спільного SDK. +Якщо форма schema має сенс лише для одного provider, визначайте її у +власному коді цього plugin замість того, щоб просувати у спільний SDK. -## Визначення цілі каналу +## Розв'язання цілей каналу -Плагіни каналів мають володіти семантикою цілей, специфічною для каналу. Тримайте спільний -outbound host загальним і використовуйте поверхню адаптера повідомлень для правил провайдера: +Channel plugin мають володіти channel-специфічною семантикою цілей. Зберігайте +спільний outbound host загальним і використовуйте поверхню messaging adapter для правил provider: -- `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль - слід вважати `direct`, `group` або `channel` до пошуку в каталозі. -- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи - слід для вводу одразу перейти до визначення за схожістю на id замість пошуку в каталозі. -- `messaging.targetResolver.resolveTarget(...)` — це резервний варіант плагіна, коли - core потребує фінального визначення, що належить провайдеру, після нормалізації або після - промаху каталогу. -- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту outbound-сесії, специфічною для провайдера, - після визначення цілі. +- `messaging.inferTargetChatType({ to })` вирішує, чи слід трактувати нормалізовану ціль + як `direct`, `group` або `channel` до пошуку в directory. +- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи слід + одразу перейти до розв'язання у стилі id замість пошуку в directory. +- `messaging.targetResolver.resolveTarget(...)` є fallback plugin, коли + core потребує фінального розв'язання, що належить provider, після нормалізації або + після пропуску в directory. +- `messaging.resolveOutboundSessionRoute(...)` володіє channel-специфічним побудуванням + route сесії після того, як ціль розв'язано. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають прийматися до - пошуку однолітків/груп. -- Використовуйте `looksLikeId` для перевірок «розглядати це як явний/native id цілі». -- Використовуйте `resolveTarget` для специфічного для провайдера резервного варіанту нормалізації, а не для - широкого пошуку в каталозі. -- Зберігайте native id провайдера, як-от chat id, thread id, JID, handle і room id, - усередині значень `target` або в параметрах, специфічних для провайдера, а не в загальних полях SDK. +- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають + прийматися до пошуку peers/groups. +- Використовуйте `looksLikeId` для перевірок "вважати це явним/native id цілі". +- Використовуйте `resolveTarget` для provider-специфічного fallback нормалізації, а не для + широкого пошуку в directory. +- Тримайте native id provider, такі як id чатів, id потоків, JID, handles і id кімнат, + всередині значень `target` або provider-специфічних параметрів, а не в загальних полях SDK. -## Каталоги на основі конфігурації +## Directory на основі config -Плагіни, які виводять записи каталогу з конфігурації, мають тримати цю логіку в -плагіні та повторно використовувати спільні допоміжні засоби з +Plugin, які виводять записи directory із config, мають тримати цю логіку в +plugin і повторно використовувати спільні helper з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні каталоги на основі конфігурації, наприклад: +Використовуйте це, коли каналу потрібні peers/groups на основі config, такі як: -- DM-контакти, керовані allowlist -- налаштовані зіставлення каналів/груп -- резервні статичні каталоги в межах облікового запису +- peers DM на основі allowlist +- налаштовані maps каналів/груп +- статичні fallback directory в межах облікового запису -Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: +Спільні helper у `directory-runtime` виконують лише загальні операції: - фільтрацію запитів - застосування обмежень -- допоміжні засоби дедуплікації/нормалізації +- дедуплікацію/нормалізацію - побудову `ChannelDirectoryEntry[]` -Перевірка облікових записів і нормалізація id, специфічні для каналу, мають залишатися -в реалізації плагіна. +Channel-специфічну перевірку облікових записів і нормалізацію id слід залишати в +реалізації plugin. -## Каталоги провайдерів +## Каталоги provider -Плагіни провайдерів можуть визначати каталоги моделей для інференсу за допомогою +Plugin provider можуть визначати каталоги моделей для інференції через `registerProvider({ catalog: { run(...) { ... } } })`. -`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в +`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує у `models.providers`: -- `{ provider }` для одного запису провайдера -- `{ providers }` для кількох записів провайдерів +- `{ provider }` для одного запису provider +- `{ providers }` для кількох записів provider -Використовуйте `catalog`, коли плагін володіє специфічними для провайдера id моделей, значеннями base URL -за замовчуванням або метаданими моделей, що залежать від auth. +Використовуйте `catalog`, коли plugin володіє model id, типовими base URL +або metadata моделей із прив'язкою до auth, специфічними для provider. -`catalog.order` керує тим, коли каталог плагіна зливається відносно вбудованих -неявних провайдерів OpenClaw: +`catalog.order` керує тим, коли каталог plugin зливається відносно вбудованих +неявних providers OpenClaw: -- `simple`: звичайні провайдери з API-ключем або на основі env -- `profile`: провайдери, що з’являються, коли існують профілі auth -- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів -- `late`: останній прохід, після інших неявних провайдерів +- `simple`: providers зі звичайним API-key або env +- `profile`: providers, які з'являються, коли існують auth profiles +- `paired`: providers, що синтезують кілька пов'язаних записів provider +- `late`: останній прохід, після інших неявних providers -Пізніші провайдери виграють у разі конфлікту ключів, тому плагіни можуть навмисно -перевизначати вбудований запис провайдера з тим самим id провайдера. +Пізніші providers перемагають у разі колізії ключів, тож plugin можуть +навмисно перевизначати вбудований запис provider з тим самим id provider. Сумісність: -- `discovery` і далі працює як застарілий псевдонім +- `discovery` усе ще працює як застарілий псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Канальна інспекція лише для читання +## Read-only інспекція каналів -Якщо ваш плагін реєструє канал, надавайте перевагу реалізації -`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`. +Якщо ваш plugin реєструє канал, віддавайте перевагу реалізації +`plugin.config.inspectAccount(cfg, accountId)` поруч із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це шлях runtime. Він може припускати, що облікові дані - повністю матеріалізовані, і швидко завершуватися помилкою, коли потрібні секрети відсутні. -- Командні шляхи лише для читання, такі як `openclaw status`, `openclaw status --all`, +- `resolveAccount(...)` — це шлях runtime. Він може виходити з припущення, що credentials + повністю матеріалізовані, і швидко завершуватися з помилкою, коли потрібних secret бракує. +- Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`, `openclaw channels status`, `openclaw channels resolve` і потоки - doctor/config repair, не повинні потребувати матеріалізації runtime-облікових даних лише для + doctor/config repair, не повинні потребувати матеріалізації runtime credentials лише для опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: - Повертає лише описовий стан облікового запису. - Зберігає `enabled` і `configured`. -- Включає поля джерела/стану облікових даних, коли це доречно, такі як: +- Включає поля джерела/статусу credentials, якщо це доречно, наприклад: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Вам не потрібно повертати сирі значення токенів лише для звіту про доступність у режимі лише для читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). -- Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але - вони недоступні в поточному шляху команди. +- Не потрібно повертати сирі значення token лише для повідомлення про read-only + доступність. Для команд у стилі status достатньо повернути `tokenStatus: "available"` + (і відповідне поле source). +- Використовуйте `configured_unavailable`, коли credential налаштовано через SecretRef, але + він недоступний у поточному шляху команди. -Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» -замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштований. +Це дозволяє командам лише для читання повідомляти "налаштовано, але недоступно в +цьому шляху команди" замість аварійного завершення або хибного повідомлення, що +обліковий запис не налаштований. -## Пакетні набори +## Package packs -Каталог плагіна може містити `package.json` із `openclaw.extensions`: +Каталог plugin може містити `package.json` з `openclaw.extensions`: ```json { @@ -1346,60 +1350,64 @@ outbound host загальним і використовуйте поверхн } ``` -Кожен запис стає плагіном. Якщо пакет перераховує кілька розширень, id плагіна +Кожен entry стає plugin. Якщо pack перелічує кілька extension, id plugin стає `name/`. -Якщо ваш плагін імпортує залежності npm, установіть їх у цьому каталозі, щоб -`node_modules` були доступні (`npm install` / `pnpm install`). +Якщо ваш plugin імпортує npm-залежності, установіть їх у цьому каталозі, щоб +був доступний `node_modules` (`npm install` / `pnpm install`). -Запобіжник безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу плагіна -після визначення символьних посилань. Записи, що виходять за межі каталогу пакета, відхиляються. +Запобіжна перевірка безпеки: кожен entry `openclaw.extensions` має залишатися всередині каталогу plugin +після розв'язання symlink. Entries, які виходять за межі каталогу package, +відхиляються. -Зауваження щодо безпеки: `openclaw plugins install` установлює залежності плагіна через -`npm install --omit=dev --ignore-scripts` (без lifecycle-скриптів і без dev-залежностей під час runtime). Підтримуйте дерева залежностей плагіна як «чисті JS/TS» і уникайте пакетів, які потребують `postinstall`-збирань. +Примітка щодо безпеки: `openclaw plugins install` установлює залежності plugin через +`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev dependencies під час runtime). Тримайте дерева залежностей plugin "чистими JS/TS" і уникайте пакетів, яким потрібні збірки через `postinstall`. -Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup. -Коли OpenClaw потребує поверхонь setup для вимкненого плагіна каналу або -коли плагін каналу увімкнений, але ще не налаштований, він завантажує `setupEntry` -замість повної точки входу плагіна. Це робить запуск і setup легшими, -коли ваша основна точка входу плагіна також підключає інструменти, гачки або інший код лише для runtime. +Необов'язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup. +Коли OpenClaw потребує поверхонь setup для вимкненого channel plugin або +коли channel plugin увімкнено, але ще не налаштовано, він завантажує `setupEntry` +замість повного entry plugin. Це робить запуск і setup легшими, +коли ваш основний entry plugin також підключає tools, hooks або інший код лише для runtime. -Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести плагін каналу на той самий шлях `setupEntry` на етапі запуску gateway -до початку прослуховування, навіть якщо канал уже налаштований. +Необов'язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` +дозволяє channel plugin підключитися до того самого шляху `setupEntry` під час +передслухової фази запуску gateway, навіть якщо канал уже налаштовано. -Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати -до того, як gateway почне прослуховування. На практиці це означає, що точка входу setup -має реєструвати кожну можливість каналу, від якої залежить запуск, наприклад: +Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, +яка має існувати до того, як gateway почне слухати. На практиці це означає, що +entry setup має реєструвати всі можливості каналу, від яких залежить запуск, наприклад: -- саму реєстрацію каналу -- будь-які HTTP-маршрути, які мають бути доступні до початку прослуховування gateway -- будь-які методи gateway, інструменти або сервіси, які мають існувати в тому ж часовому вікні +- реєстрацію самого каналу +- будь-які HTTP routes, які мають бути доступні до початку прослуховування gateway +- будь-які methods, tools або services gateway, які мають існувати в тому самому вікні часу -Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте -цей прапорець. Залиште плагін із типовою поведінкою й дозвольте OpenClaw завантажити -повну точку входу під час запуску. +Якщо ваш повний entry усе ще володіє будь-якою необхідною для запуску можливістю, не вмикайте +цей прапорець. Залиште plugin зі стандартною поведінкою і дозвольте OpenClaw завантажити +повний entry під час запуску. -Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для setup, які core -може використовувати до завантаження повного runtime каналу. Поточна поверхня просування setup така: +Вбудовані channels також можуть публікувати helper-и поверхні контракту лише для setup, до яких core +може звертатися до завантаження повного runtime каналу. Поточна поверхня +просування setup така: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Core використовує цю поверхню, коли потрібно просунути застарілу конфігурацію каналу з одним обліковим записом у -`channels..accounts.*` без завантаження повної точки входу плагіна. -Matrix — поточний вбудований приклад: він переміщує лише ключі auth/bootstrap у -іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може -зберегти налаштований неканонічний ключ default-account замість того, щоб завжди створювати +Core використовує цю поверхню, коли йому потрібно просунути застарілий config каналу з +одним обліковим записом у `channels..accounts.*` без завантаження повного entry plugin. +Matrix є поточним вбудованим прикладом: він переносить лише ключі auth/bootstrap у +іменований promoted account, коли іменовані accounts уже існують, і може зберігати +налаштований неканонічний ключ default-account замість того, щоб завжди створювати `accounts.default`. -Ці адаптери патчів setup зберігають лінивий характер виявлення поверхні контракту вбудованих компонентів. Час імпорту залишається малим; поверхня просування завантажується лише під час першого використання замість повторного входу в запуск вбудованого каналу під час імпорту модуля. +Ці patch adapter-и setup зберігають ліниве виявлення поверхні контракту вбудованих plugin. +Час імпорту залишається малим; поверхня promotion завантажується лише під час першого використання, +а не повторно входить у запуск вбудованого каналу під час імпорту модуля. -Коли ці поверхні запуску включають gateway RPC-методи, тримайте їх на -префіксі, специфічному для плагіна. Простори імен адміністратора core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються -як `operator.admin`, навіть якщо плагін запитує вужчу область. +Коли ці поверхні запуску містять methods Gateway RPC, тримайте їх на +plugin-специфічному префіксі. Простори імен admin core (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди розв'язуються +до `operator.admin`, навіть якщо plugin запитує вужчу область. Приклад: @@ -1418,8 +1426,8 @@ Matrix — поточний вбудований приклад: він пере ### Метадані каталогу каналів -Плагіни каналів можуть оголошувати метадані setup/discovery через `openclaw.channel` і -підказки встановлення через `openclaw.install`. Це дозволяє core не містити власних даних каталогу. +Channel plugin можуть рекламувати метадані setup/discovery через `openclaw.channel` і +підказки встановлення через `openclaw.install`. Це дозволяє core не містити дані каталогу. Приклад: @@ -1434,7 +1442,7 @@ Matrix — поточний вбудований приклад: він пере "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Самостійно розміщений чат через webhook-ботів Nextcloud Talk.", + "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -1447,41 +1455,41 @@ Matrix — поточний вбудований приклад: він пере } ``` -Корисні поля `openclaw.channel`, крім мінімального прикладу: +Корисні поля `openclaw.channel`, окрім мінімального прикладу: -- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу -- `docsLabel`: перевизначення тексту посилання на документацію -- `preferOver`: id плагінів/каналів із нижчим пріоритетом, які цей запис каталогу має випереджати -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: керування текстом поверхонь вибору -- `markdownCapable`: позначає канал як здатний до markdown для рішень щодо форматування outbound +- `detailLabel`: вторинний label для багатших поверхонь catalog/status +- `docsLabel`: перевизначає текст посилання на документацію +- `preferOver`: id plugin/channel з нижчим пріоритетом, які цей запис каталогу має перевершувати +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування копірайтом для поверхні вибору +- `markdownCapable`: позначає канал як markdown-capable для рішень щодо outbound-форматування - `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` -- `exposure.setup`: приховує канал із інтерактивних пікерів setup/configure, якщо встановлено `false` +- `exposure.setup`: приховує канал з інтерактивних picker-ів setup/configure, якщо встановлено `false` - `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації -- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure` -- `quickstartAllowFrom`: вмикає для каналу стандартний потік quickstart `allowFrom` -- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть якщо існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення announce-цілей +- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure` +- `quickstartAllowFrom`: додає канал до стандартного потоку quickstart `allowFrom` +- `forceAccountBinding`: вимагає явної прив'язки облікового запису, навіть якщо існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: віддає перевагу пошуку за сесією під час розв'язання цілей announce OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт -реєстру MPM). Помістіть JSON-файл в одне з місць: +реєстру 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"`. -## Плагіни рушія контексту +## Plugin context engine -Плагіни рушія контексту володіють оркестрацією контексту сесії для поглинання, -збирання та компактування. Реєструйте їх із вашого плагіна через -`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через +Plugin context engine володіють оркестрацією контексту сесії для ingest, assembly +і compaction. Реєструйте їх зі свого plugin через +`api.registerContextEngine(id, factory)`, а потім вибирайте активний engine через `plugins.slots.contextEngine`. -Використовуйте це, коли вашому плагіну потрібно замінити або розширити типовий -конвеєр контексту, а не просто додати пошук у пам’яті чи гачки. +Використовуйте це, коли вашому plugin потрібно замінити або розширити типовий конвеєр context, +а не просто додати memory search або hooks. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -1509,7 +1517,7 @@ export default function (api) { } ``` -Якщо ваш рушій **не** володіє алгоритмом компактування, залиште `compact()` +Якщо ваш engine **не** володіє алгоритмом compaction, залишайте `compact()` реалізованим і явно делегуйте його: ```ts @@ -1547,60 +1555,60 @@ export default function (api) { ## Додавання нової можливості -Коли плагіну потрібна поведінка, яка не вписується в поточний API, не обходьте -систему плагінів через приватний прямий доступ. Додайте відсутню можливість. +Коли plugin потребує поведінки, яка не вписується в поточний API, не обходьте +систему plugin приватним зверненням углиб. Додайте відсутню можливість. Рекомендована послідовність: 1. визначте контракт core - Вирішіть, якою спільною поведінкою має володіти core: політика, резервний вибір, злиття конфігурації, - життєвий цикл, семантика для каналів і форма допоміжного засобу runtime. -2. додайте типізовані поверхні реєстрації/runtime для плагіна + Вирішіть, якою спільною поведінкою має володіти core: політикою, fallback, злиттям config, + життєвим циклом, channel-facing семантикою і формою helper runtime. +2. додайте типізовані поверхні реєстрації/runtime plugin Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною типізованою поверхнею можливості. -3. підключіть споживачів core + каналів/функцій - Канали та плагіни функцій мають споживати нову можливість через core, - а не імпортувати реалізацію постачальника напряму. -4. зареєструйте реалізації постачальників - Тоді vendor-плагіни реєструють свої бекенди для цієї можливості. +3. під'єднайте споживачів core + channel/feature + Channels і feature plugin мають споживати нову можливість через core, + а не імпортувати vendor-реалізацію напряму. +4. зареєструйте vendor-реалізації + Потім vendor plugin реєструють свої бекенди для цієї можливості. 5. додайте контрактне покриття - Додайте тести, щоб володіння і форма реєстрації з часом залишалися явними. + Додайте тести, щоб форма власності та реєстрації залишалася явною з часом. -Саме так OpenClaw зберігає власну думку, не стаючи жорстко прив’язаним до -світогляду одного провайдера. Див. [Практичний посібник із можливостей](/uk/plugins/architecture) -для конкретного списку файлів і опрацьованого прикладу. +Саме так OpenClaw залишається opinionated, не стаючи жорстко прив'язаним до +світогляду одного provider. Див. [Capability Cookbook](/uk/plugins/architecture) +для конкретного контрольного списку файлів і робочого прикладу. ### Контрольний список можливості -Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися -таких поверхонь: +Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих +поверхонь разом: -- типи контрактів core у `src//types.ts` -- runner/допоміжний засіб runtime core у `src//runtime.ts` -- поверхня реєстрації API плагіна у `src/plugins/types.ts` -- підключення реєстру плагінів у `src/plugins/registry.ts` -- відкриття runtime плагіна у `src/plugins/runtime/*`, коли плагіни функцій/каналів - мають її споживати -- допоміжні засоби захоплення/тестування у `src/test-utils/plugin-registration.ts` -- перевірки володіння/контракту у `src/plugins/contracts/registry.ts` -- документація для операторів/плагінів у `docs/` +- типи контракту core у `src//types.ts` +- runner/helper runtime core у `src//runtime.ts` +- поверхня реєстрації API plugin у `src/plugins/types.ts` +- підключення реєстру plugin у `src/plugins/registry.ts` +- відкриття runtime plugin у `src/plugins/runtime/*`, коли feature/channel + plugin мають її споживати +- helper-и capture/test у `src/test-utils/plugin-registration.ts` +- перевірки власності/контракту в `src/plugins/contracts/registry.ts` +- документація для операторів/plugin у `docs/` -Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість -ще не повністю інтегрована. +Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість ще +не повністю інтегрована. ### Шаблон можливості Мінімальний шаблон: ```ts -// контракт core +// core contract export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// API плагіна +// plugin API api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1609,7 +1617,7 @@ api.registerVideoGenerationProvider({ }, }); -// спільний допоміжний засіб runtime для плагінів функцій/каналів +// shared runtime helper for feature/channel plugins const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, @@ -1622,9 +1630,9 @@ const clip = await api.runtime.videoGeneration.generate({ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -Це зберігає просте правило: +Це зберігає правило простим: - core володіє контрактом можливості + оркестрацією -- vendor-плагіни володіють реалізаціями постачальників -- плагіни функцій/каналів споживають допоміжні засоби runtime -- контрактні тести зберігають явність володіння +- vendor plugin володіють vendor-реалізаціями +- feature/channel plugin споживають helper runtime +- контрактні тести зберігають явну власність diff --git a/docs/uk/plugins/sdk-channel-plugins.md b/docs/uk/plugins/sdk-channel-plugins.md index d91ce9019..7bfe21719 100644 --- a/docs/uk/plugins/sdk-channel-plugins.md +++ b/docs/uk/plugins/sdk-channel-plugins.md @@ -1,16 +1,16 @@ --- read_when: - - Ви створюєте новий плагін каналу обміну повідомленнями + - Ви створюєте новий плагін каналу повідомлень - Ви хочете підключити OpenClaw до платформи обміну повідомленнями - Вам потрібно зрозуміти поверхню адаптера ChannelPlugin sidebarTitle: Channel Plugins -summary: Покроковий посібник зі створення плагіна каналу обміну повідомленнями для OpenClaw +summary: Покроковий посібник зі створення плагіна каналу повідомлень для OpenClaw title: Створення плагінів каналів x-i18n: - generated_at: "2026-04-07T06:53:56Z" + generated_at: "2026-04-07T18:43:35Z" model: gpt-5.4 provider: openai - source_hash: 0aab6cc835b292c62e33c52ad0c35f989fb1a5b225511e8bdc2972feb3c64f09 + source_hash: b709fda7527fcf437b119c4668172804f2f9c9a46f5e39a2161467a4f5f1e42f source_path: plugins/sdk-channel-plugins.md workflow: 15 --- @@ -18,8 +18,8 @@ x-i18n: # Створення плагінів каналів Цей посібник покроково пояснює створення плагіна каналу, який підключає OpenClaw до -платформи обміну повідомленнями. Наприкінці у вас буде працездатний канал із безпекою DM, -паруванням, потоками відповідей і вихідними повідомленнями. +платформи обміну повідомленнями. Наприкінці у вас буде робочий канал із безпекою DM, +паруванням, гілкуванням відповідей і надсиланням вихідних повідомлень. Якщо ви ще не створювали жодного плагіна OpenClaw, спочатку прочитайте @@ -30,164 +30,179 @@ x-i18n: ## Як працюють плагіни каналів Плагінам каналів не потрібні власні інструменти send/edit/react. OpenClaw зберігає один -спільний інструмент `message` у core. Ваш плагін відповідає за: +спільний інструмент `message` у ядрі. Ваш плагін відповідає за: - **Config** — визначення облікового запису та майстер налаштування -- **Security** — політика DM та списки дозволених -- **Pairing** — потік схвалення DM -- **Session grammar** — як ідентифікатори розмов, специфічні для провайдера, зіставляються з базовими чатами, ідентифікаторами потоків і резервними батьківськими значеннями -- **Outbound** — надсилання тексту, медіа та опитувань на платформу -- **Threading** — як організовуються відповіді в потоки +- **Security** — політика DM і списки дозволених +- **Pairing** — процес підтвердження DM +- **Session grammar** — як ідентифікатори розмов, специфічні для провайдера, зіставляються з базовими чатами, ідентифікаторами гілок і запасними батьківськими варіантами +- **Outbound** — надсилання тексту, медіа й опитувань на платформу +- **Threading** — як організовуються відповіді в гілки -Core відповідає за спільний інструмент повідомлень, підключення до prompt, зовнішню форму ключа сесії, -загальне ведення `:thread:` та диспетчеризацію. +Ядро відповідає за спільний інструмент message, зв’язування промптів, зовнішню форму +ключа сесії, загальний облік `:thread:` і диспетчеризацію. -Якщо ваша платформа зберігає додаткову область дії в ідентифікаторах розмов, зберігайте цей розбір -у плагіні через `messaging.resolveSessionConversation(...)`. Це -канонічний хук для зіставлення `rawId` з базовим ідентифікатором розмови, необов’язковим ідентифікатором потоку, -явним `baseConversationId` та будь-якими `parentConversationCandidates`. -Коли ви повертаєте `parentConversationCandidates`, зберігайте їхній порядок -від найвужчого батьківського елемента до найширшої/базової розмови. +Якщо ваша платформа зберігає додатковий контекст в ідентифікаторах розмов, залишайте цей +розбір у плагіні через `messaging.resolveSessionConversation(...)`. Це +канонічний хук для зіставлення `rawId` з базовим ідентифікатором розмови, необов’язковим +ідентифікатором гілки, явним `baseConversationId` і будь-якими +`parentConversationCandidates`. +Коли ви повертаєте `parentConversationCandidates`, зберігайте їх впорядкованими від +найвужчого батьківського елемента до найширшої/базової розмови. -Вбудовані плагіни, яким потрібен такий самий розбір до запуску реєстру каналів, -також можуть експортувати файл верхнього рівня `session-key-api.ts` із -відповідним експортом `resolveSessionConversation(...)`. Core використовує цю безпечну для bootstrap поверхню -лише тоді, коли реєстр плагінів середовища виконання ще недоступний. +Вбудовані плагіни, яким потрібен той самий розбір до запуску реєстру каналів, +також можуть надавати файл верхнього рівня `session-key-api.ts` із відповідним +експортом `resolveSessionConversation(...)`. Ядро використовує цю безпечну для +завантаження поверхню лише тоді, коли реєстр плагінів під час виконання ще недоступний. `messaging.resolveParentConversationCandidates(...)` залишається доступним як -застарілий резервний варіант сумісності, коли плагіну потрібні лише батьківські резервні значення поверх -загального/raw id. Якщо існують обидва хуки, core спочатку використовує -`resolveSessionConversation(...).parentConversationCandidates` і лише потім +застарілий запасний варіант для сумісності, коли плагіну потрібні лише +резервні батьківські варіанти поверх загального/raw id. Якщо існують обидва хуки, ядро спочатку +використовує `resolveSessionConversation(...).parentConversationCandidates` і лише потім переходить до `resolveParentConversationCandidates(...)`, якщо канонічний хук -їх не вказує. +їх не повертає. -## Схвалення та можливості каналу +## Підтвердження та можливості каналу -Більшості плагінів каналів не потрібен код, специфічний для схвалень. +Більшості плагінів каналів не потрібен код, специфічний для підтверджень. -- Core відповідає за `/approve` у тому ж чаті, спільні payload кнопок схвалення та загальну резервну доставку. -- Віддавайте перевагу одному об’єкту `approvalCapability` у плагіні каналу, якщо каналу потрібна поведінка, специфічна для схвалень. -- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — це канонічний шов автентифікації схвалень. -- Якщо ваш канал надає нативні схвалення exec, реалізуйте `approvalCapability.getActionAvailabilityState`, навіть якщо нативний транспорт повністю знаходиться в `approvalCapability.native`. Core використовує цей хук доступності, щоб розрізняти `enabled` і `disabled`, визначати, чи підтримує канал-ініціатор нативні схвалення, і включати канал до інструкцій резервного варіанта для нативного клієнта. -- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для специфічної для каналу поведінки життєвого циклу payload, наприклад приховування дубльованих локальних запитів на схвалення або надсилання індикаторів набору перед доставкою. -- Використовуйте `approvalCapability.delivery` лише для нативної маршрутизації схвалень або вимкнення резервного варіанта. -- Використовуйте `approvalCapability.render` лише тоді, коли каналу справді потрібні власні payload схвалення замість спільного рендерера. -- Використовуйте `approvalCapability.describeExecApprovalSetup`, якщо канал хоче, щоб відповідь для вимкненого шляху пояснювала точні параметри config, потрібні для ввімкнення нативних схвалень exec. Хук отримує `{ channel, channelLabel, accountId }`; канали з іменованими обліковими записами мають відображати шляхи з областю дії облікового запису, такі як `channels..accounts..execApprovals.*`, замість дефолтів верхнього рівня. -- Якщо канал може вивести стабільні DM-ідентичності, подібні до власника, з наявного config, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому ж чаті без додавання логіки core, специфічної для схвалень. -- Якщо каналу потрібна нативна доставка схвалень, зосередьте код каналу на нормалізації цілі та хуках транспорту. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver`, `createApproverRestrictedNativeApprovalCapability` і `createChannelNativeApprovalRuntime` з `openclaw/plugin-sdk/approval-runtime`, щоб core відповідав за фільтрацію запитів, маршрутизацію, усунення дублікатів, строк дії та підписку на gateway. -- Канали нативних схвалень мають маршрутизувати і `accountId`, і `approvalKind` через ці helper-и. `accountId` утримує політику схвалень для кількох облікових записів у межах правильного бот-облікового запису, а `approvalKind` зберігає поведінку схвалень exec і plugin доступною для каналу без жорстко закодованих гілок у core. +- Ядро відповідає за `/approve` у тому самому чаті, спільні payload кнопок підтвердження та загальну запасну доставку. +- Віддавайте перевагу одному об’єкту `approvalCapability` у плагіні каналу, якщо каналу потрібна поведінка, специфічна для підтверджень. +- `ChannelPlugin.approvals` видалено. Виносьте факти про доставку/нативний режим/рендеринг/автентифікацію підтверджень у `approvalCapability`. +- `plugin.auth` призначений лише для login/logout; ядро більше не читає хуки автентифікації підтверджень із цього об’єкта. +- `approvalCapability.authorizeActorAction` і `approvalCapability.getActionAvailabilityState` — це канонічний шов автентифікації підтверджень. +- Використовуйте `approvalCapability.getActionAvailabilityState` для доступності автентифікації підтверджень у тому самому чаті. +- Якщо ваш канал надає нативні підтвердження exec, використовуйте `approvalCapability.getExecInitiatingSurfaceState` для стану ініціювальної поверхні/нативного клієнта, коли він відрізняється від автентифікації підтверджень у тому самому чаті. Ядро використовує цей специфічний для exec хук, щоб розрізняти `enabled` і `disabled`, визначати, чи підтримує ініціювальний канал нативні підтвердження exec, і включати канал у рекомендації щодо запасного сценарію для нативного клієнта. `createApproverRestrictedNativeApprovalCapability(...)` заповнює це для типового випадку. +- Використовуйте `outbound.shouldSuppressLocalPayloadPrompt` або `outbound.beforeDeliverPayload` для поведінки життєвого циклу payload, специфічної для каналу, наприклад приховування дубльованих локальних запитів підтвердження або надсилання індикаторів набору перед доставкою. +- Використовуйте `approvalCapability.delivery` лише для маршрутизації нативних підтверджень або придушення запасної доставки. +- Використовуйте `approvalCapability.nativeRuntime` для фактів нативного підтвердження, що належать каналу. Зберігайте його ледачим у гарячих точках входу каналу за допомогою `createLazyChannelApprovalNativeRuntimeAdapter(...)`, який може імпортувати ваш runtime-модуль на вимогу, водночас дозволяючи ядру збирати життєвий цикл підтверджень. +- Використовуйте `approvalCapability.render` лише тоді, коли каналу справді потрібні власні payload підтвердження замість спільного рендера. +- Використовуйте `approvalCapability.describeExecApprovalSetup`, коли канал хоче, щоб відповідь на вимкнений шлях пояснювала точні параметри config, потрібні для ввімкнення нативних підтверджень exec. Хук отримує `{ channel, channelLabel, accountId }`; канали з іменованими обліковими записами мають відображати шляхи з областю облікового запису, як-от `channels..accounts..execApprovals.*`, замість верхньорівневих типових значень. +- Якщо канал може вивести стабільні схожі на власника DM-ідентичності з наявної config, використовуйте `createResolvedApproverActionAuthAdapter` з `openclaw/plugin-sdk/approval-runtime`, щоб обмежити `/approve` у тому самому чаті без додавання логіки підтверджень у ядро. +- Якщо каналу потрібна доставка нативних підтверджень, зосередьте код каналу на нормалізації цілі плюс фактах транспорту/представлення. Використовуйте `createChannelExecApprovalProfile`, `createChannelNativeOriginTargetResolver`, `createChannelApproverDmTargetResolver` і `createApproverRestrictedNativeApprovalCapability` з `openclaw/plugin-sdk/approval-runtime`. Розміщуйте факти, специфічні для каналу, за `approvalCapability.nativeRuntime`, бажано через `createChannelApprovalNativeRuntimeAdapter(...)` або `createLazyChannelApprovalNativeRuntimeAdapter(...)`, щоб ядро могло зібрати обробник і взяти на себе фільтрацію запитів, маршрутизацію, усунення дублікатів, завершення строку дії, підписку шлюзу та сповіщення про перенаправлення. `nativeRuntime` поділено на кілька менших швів: +- `availability` — чи налаштовано обліковий запис і чи слід обробляти запит +- `presentation` — перетворення спільної view model підтверджень у нативні payload очікування/вирішення/прострочення або фінальні дії +- `transport` — підготовка цілей плюс надсилання/оновлення/видалення нативних повідомлень підтвердження +- `interactions` — необов’язкові хуки bind/unbind/clear-action для нативних кнопок або реакцій +- `observe` — необов’язкові хуки діагностики доставки +- Якщо каналу потрібні об’єкти, що належать runtime, як-от client, token, додаток Bolt або приймач webhook, реєструйте їх через `openclaw/plugin-sdk/channel-runtime-context`. Загальний реєстр runtime-context дозволяє ядру ініціалізувати обробники на основі можливостей зі стану запуску каналу без додавання обгорток, специфічних для підтверджень. +- Звертайтеся до нижчорівневого `createChannelApprovalHandler` або `createChannelNativeApprovalRuntime` лише тоді, коли шов на основі можливостей ще недостатньо виразний. +- Канали з нативними підтвердженнями мають маршрутизувати і `accountId`, і `approvalKind` через ці помічники. `accountId` зберігає область політики підтверджень для багатьох облікових записів прив’язаною до правильного бот-акаунта, а `approvalKind` зберігає для каналу доступною поведінку підтверджень exec чи plugin без жорстко закодованих розгалужень у ядрі. +- Ядро тепер також відповідає за сповіщення про перенаправлення підтверджень. Плагіни каналів не повинні надсилати власні додаткові повідомлення на кшталт «підтвердження надійшло в DM / інший канал» із `createChannelNativeApprovalRuntime`; натомість надавайте точну маршрутизацію origin + approver-DM через спільні помічники можливостей підтверджень і дозвольте ядру агрегувати фактичні доставки перед публікацією будь-якого сповіщення назад в ініціювальний чат. - Зберігайте тип delivered approval id наскрізно. Нативні клієнти не повинні - вгадувати або переписувати маршрутизацію схвалень exec чи plugin на основі локального стану каналу. -- Різні типи схвалень можуть навмисно надавати різні нативні поверхні. - Поточні приклади вбудованих: - - Slack зберігає доступність нативної маршрутизації схвалень як для exec, так і для plugin id. - - Matrix зберігає нативну DM/канальну маршрутизацію лише для схвалень exec і залишає - схвалення plugin на спільному шляху `/approve` у тому ж чаті. -- `createApproverRestrictedNativeApprovalAdapter` усе ще існує як обгортка сумісності, але новий код має віддавати перевагу builder-у можливостей і експонувати `approvalCapability` у плагіні. + вгадувати або переписувати маршрутизацію підтверджень exec чи plugin зі стану, локального для каналу. +- Різні типи підтверджень можуть навмисно відкривати різні нативні поверхні. + Поточні приклади вбудованих плагінів: + - Slack зберігає доступною нативну маршрутизацію підтверджень як для exec, так і для plugin id. + - Matrix зберігає ту саму нативну маршрутизацію DM/каналу та UX реакцій для підтверджень exec + і plugin, водночас дозволяючи автентифікації відрізнятися за типом підтвердження. +- `createApproverRestrictedNativeApprovalAdapter` усе ще існує як обгортка для сумісності, але новий код має надавати перевагу будівнику можливостей і експонувати `approvalCapability` у плагіні. -Для гарячих точок входу каналу віддавайте перевагу вужчим runtime subpath, коли вам -потрібна лише одна частина цієї сім’ї: +Для гарячих точок входу каналу віддавайте перевагу вужчим runtime-підшляхам, коли вам потрібна лише +одна частина цієї сім’ї: - `openclaw/plugin-sdk/approval-auth-runtime` - `openclaw/plugin-sdk/approval-client-runtime` - `openclaw/plugin-sdk/approval-delivery-runtime` +- `openclaw/plugin-sdk/approval-handler-runtime` - `openclaw/plugin-sdk/approval-native-runtime` - `openclaw/plugin-sdk/approval-reply-runtime` +- `openclaw/plugin-sdk/channel-runtime-context` Так само віддавайте перевагу `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/reply-runtime`, `openclaw/plugin-sdk/reply-dispatch-runtime`, `openclaw/plugin-sdk/reply-reference` і -`openclaw/plugin-sdk/reply-chunking`, коли вам не потрібна ширша узагальнена +`openclaw/plugin-sdk/reply-chunking`, коли вам не потрібна ширша зонтична поверхня. Зокрема для налаштування: -- `openclaw/plugin-sdk/setup-runtime` охоплює безпечні для runtime helper-и налаштування: - безпечні для import адаптери патчів налаштування (`createPatchedAccountSetupAdapter`, +- `openclaw/plugin-sdk/setup-runtime` охоплює безпечні для runtime помічники налаштування: + безпечні для імпорту адаптери патчів налаштування (`createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, - `createSetupInputPresenceValidator`), вивід lookup-note, + `createSetupInputPresenceValidator`), виведення lookup-note, `promptResolvedAllowFrom`, `splitSetupEntries` і делеговані - builder-и setup-proxy + будівники setup-proxy - `openclaw/plugin-sdk/setup-adapter-runtime` — це вузький env-aware шов адаптера для `createEnvPatchedAccountSetupAdapter` -- `openclaw/plugin-sdk/channel-setup` охоплює builder-и налаштування з необов’язковим встановленням - плюс кілька примітивів, безпечних для setup: +- `openclaw/plugin-sdk/channel-setup` охоплює будівники налаштування з необов’язковим встановленням + плюс кілька безпечних для налаштування примітивів: `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, -Якщо ваш канал підтримує налаштування або auth на основі env і загальні потоки startup/config -мають знати ці назви env до завантаження runtime, оголосіть їх у +Якщо ваш канал підтримує налаштування або auth на основі env, і загальні процеси запуску/config +мають знати ці назви env до завантаження runtime, оголошуйте їх у маніфесті плагіна через `channelEnvVars`. Зберігайте runtime `envVars` каналу або локальні -константи лише для копії, орієнтованої на оператора. +константи лише для копірайту, орієнтованого на операторів. `createOptionalChannelSetupWizard`, `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled` і `splitSetupEntries` - використовуйте ширший шов `openclaw/plugin-sdk/setup` лише тоді, коли вам також потрібні - важчі спільні helper-и setup/config, наприклад + важчі спільні помічники налаштування/config, такі як `moveSingleAccountChannelSectionToDefaultAccount(...)` -Якщо ваш канал хоче лише рекламувати «спочатку встановіть цей плагін» у поверхнях setup, -віддавайте перевагу `createOptionalChannelSetupSurface(...)`. Згенеровані -адаптер/майстер fail closed під час запису config та завершення, і повторно використовують -те саме повідомлення про необхідність встановлення в копії валідації, finalize та docs-link. +Якщо ваш канал лише хоче повідомляти «спочатку встановіть цей плагін» на +поверхнях налаштування, віддавайте перевагу `createOptionalChannelSetupSurface(...)`. Згенеровані +adapter/wizard працюють за принципом fail closed для записів config і фіналізації, а також +повторно використовують те саме повідомлення про обов’язкове встановлення для валідації, фіналізації та тексту +з посиланням на документацію. -Для інших гарячих шляхів каналу віддавайте перевагу вузьким helper-ам замість ширших застарілих -поверхонь: +Для інших гарячих шляхів каналу віддавайте перевагу вузьким помічникам над ширшими застарілими +поверхнями: - `openclaw/plugin-sdk/account-core`, `openclaw/plugin-sdk/account-id`, `openclaw/plugin-sdk/account-resolution` і - `openclaw/plugin-sdk/account-helpers` для config кількох облікових записів та - резервного варіанта для облікового запису за замовчуванням + `openclaw/plugin-sdk/account-helpers` для config багатьох облікових записів і + запасного сценарію облікового запису за замовчуванням - `openclaw/plugin-sdk/inbound-envelope` і - `openclaw/plugin-sdk/inbound-reply-dispatch` для маршруту/конверта inbound та - запису й диспетчеризації + `openclaw/plugin-sdk/inbound-reply-dispatch` для вхідного маршруту/конверта та + зв’язування record-and-dispatch - `openclaw/plugin-sdk/messaging-targets` для розбору/зіставлення цілей - `openclaw/plugin-sdk/outbound-media` і - `openclaw/plugin-sdk/outbound-runtime` для завантаження медіа плюс - делегатів ідентичності/надсилання outbound -- `openclaw/plugin-sdk/thread-bindings-runtime` для життєвого циклу прив’язок потоків - та реєстрації адаптерів -- `openclaw/plugin-sdk/agent-media-payload` лише тоді, коли все ще потрібне - застаріле компонування полів payload agent/media -- `openclaw/plugin-sdk/telegram-command-config` для нормалізації користувацьких команд Telegram, - перевірки дублікатів/конфліктів і стабільного для резервного варіанта контракту - config команд + `openclaw/plugin-sdk/outbound-runtime` для завантаження медіа плюс делегатів + ідентичності/надсилання вихідних повідомлень +- `openclaw/plugin-sdk/thread-bindings-runtime` для життєвого циклу прив’язок гілок + і реєстрації адаптерів +- `openclaw/plugin-sdk/agent-media-payload` лише коли все ще потрібна застаріла + схема полів payload агента/медіа +- `openclaw/plugin-sdk/telegram-command-config` для нормалізації спеціальних команд Telegram, + валідації дублікатів/конфліктів і стабільного при запасному сценарії контракту config команд -Канали лише з auth зазвичай можуть зупинитися на стандартному шляху: core обробляє схвалення, а плагін лише надає можливості outbound/auth. Канали нативних схвалень, такі як Matrix, Slack, Telegram і користувацькі chat-транспорти, повинні використовувати спільні нативні helper-и замість власної реалізації життєвого циклу схвалень. +Канали лише з auth зазвичай можуть зупинитися на типовому шляху: ядро обробляє підтвердження, а плагін лише надає можливості outbound/auth. Канали з нативними підтвердженнями, як-от Matrix, Slack, Telegram і спеціальні транспортні канали чату, повинні використовувати спільні нативні помічники замість реалізації власного життєвого циклу підтверджень. ## Політика вхідних згадок -Розділяйте обробку вхідних згадок на два шари: +Розділяйте обробку вхідних згадок на два рівні: -- збирання доказів, яким володіє плагін -- спільне оцінювання політики +- збирання доказів, що належить плагіну +- оцінювання спільної політики -Для спільного шару використовуйте `openclaw/plugin-sdk/channel-inbound`. +Для спільного рівня використовуйте `openclaw/plugin-sdk/channel-inbound`. -Добре підходить для локальної логіки плагіна: +Підходить для логіки, локальної для плагіна: -- виявлення reply-to-bot -- виявлення quoted-bot -- перевірки участі в потоці -- виключення службових/системних повідомлень -- платформені нативні кеші, потрібні для підтвердження участі бота +- виявлення відповіді боту +- виявлення цитування бота +- перевірки участі в гілці +- виключення сервісних/системних повідомлень +- платформонативні кеші, потрібні для доведення участі бота -Добре підходить для спільного helper-а: +Підходить для спільного помічника: - `requireMention` - явний результат згадки - список дозволених неявних згадок -- обхід команди -- фінальне рішення про пропуск +- обхід для команд +- остаточне рішення про пропуск -Бажаний потік: +Рекомендований процес: -1. Обчисліть локальні факти згадок. +1. Обчисліть локальні факти згадки. 2. Передайте ці факти в `resolveInboundMentionDecision({ facts, policy })`. -3. Використовуйте `decision.effectiveWasMentioned`, `decision.shouldBypassMention` і `decision.shouldSkip` у вашому вхідному шлюзі. +3. Використовуйте `decision.effectiveWasMentioned`, `decision.shouldBypassMention` і `decision.shouldSkip` у своїй вхідній перевірці. ```typescript import { @@ -226,8 +241,8 @@ const decision = resolveInboundMentionDecision({ if (decision.shouldSkip) return; ``` -`api.runtime.channel.mentions` надає ті самі спільні helper-и згадок для -вбудованих плагінів каналів, які вже залежать від ін’єкції runtime: +`api.runtime.channel.mentions` надає ті самі спільні помічники згадок для +вбудованих плагінів каналів, які вже залежать від інʼєкції runtime: - `buildMentionRegexes` - `matchesMentionPatterns` @@ -235,8 +250,8 @@ if (decision.shouldSkip) return; - `implicitMentionKindWhen` - `resolveInboundMentionDecision` -Старіші helper-и `resolveMentionGating*` залишаються в -`openclaw/plugin-sdk/channel-inbound` лише як експорти сумісності. Новий код +Старіші помічники `resolveMentionGating*` залишаються в +`openclaw/plugin-sdk/channel-inbound` лише як експорти для сумісності. Новий код має використовувати `resolveInboundMentionDecision({ facts, policy })`. ## Покроковий розбір @@ -244,8 +259,8 @@ if (decision.shouldSkip) return; - Створіть стандартні файли плагіна. Поле `channel` у `package.json` — - це те, що робить його плагіном каналу. Повну поверхню метаданих пакета + Створіть стандартні файли плагіна. Поле `channel` у `package.json` + робить це плагіном каналу. Повну поверхню метаданих пакета дивіться в [Налаштування плагіна і Config](/uk/plugins/sdk-setup#openclawchannel): @@ -296,7 +311,7 @@ if (decision.shouldSkip) return; - Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь адаптера. Почніть із + Інтерфейс `ChannelPlugin` має багато необов’язкових поверхонь адаптерів. Почніть із мінімуму — `id` і `setup` — і додавайте адаптери за потреби. Створіть `src/channel.ts`: @@ -392,18 +407,18 @@ if (decision.shouldSkip) return; }); ``` - - Замість ручної реалізації низькорівневих інтерфейсів адаптера ви передаєте - декларативні параметри, а builder компонуватиме їх: + + Замість ручної реалізації низькорівневих інтерфейсів адаптерів ви передаєте + декларативні параметри, а будівник поєднує їх: | Параметр | Що він підключає | | --- | --- | - | `security.dm` | Визначення scoped DM security з полів config | - | `pairing.text` | Потік парування DM на основі тексту з обміном кодом | - | `threading` | Визначення режиму reply-to (фіксований, у межах облікового запису або користувацький) | - | `outbound.attachedResults` | Функції надсилання, що повертають метадані результату (ідентифікатори повідомлень) | + | `security.dm` | Визначення DM-безпеки з областю дії з полів config | + | `pairing.text` | Текстовий процес парування DM з обміном кодами | + | `threading` | Визначення режиму reply-to (фіксований, з областю облікового запису або власний) | + | `outbound.attachedResults` | Функції надсилання, які повертають метадані результату (ID повідомлень) | - Ви також можете передавати сирі об’єкти адаптера замість декларативних параметрів, + Ви також можете передавати сирі об’єкти адаптерів замість декларативних параметрів, якщо вам потрібен повний контроль. @@ -445,20 +460,20 @@ if (decision.shouldSkip) return; }); ``` - Розміщуйте CLI-дескриптори, що належать каналу, у `registerCliMetadata(...)`, щоб OpenClaw + Розміщуйте дескриптори CLI, що належать каналу, у `registerCliMetadata(...)`, щоб OpenClaw міг показувати їх у кореневій довідці без активації повного runtime каналу, тоді як звичайні повні завантаження все одно підхоплюватимуть ті самі дескриптори для реєстрації - реальних команд. Залишайте `registerFull(...)` для роботи лише в runtime. + реальних команд. Залишайте `registerFull(...)` для роботи лише під час runtime. Якщо `registerFull(...)` реєструє gateway RPC methods, використовуйте - префікс, специфічний для плагіна. Простори імен адміністрування core (`config.*`, - `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими та завжди + префікс, специфічний для плагіна. Простори імен адміністратора ядра (`config.*`, + `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди визначаються як `operator.admin`. `defineChannelPluginEntry` автоматично обробляє поділ режимів реєстрації. Усі параметри дивіться в [Точки входу](/uk/plugins/sdk-entrypoints#definechannelpluginentry). - + Створіть `setup-entry.ts` для легкого завантаження під час онбордингу: ```typescript setup-entry.ts @@ -468,16 +483,16 @@ if (decision.shouldSkip) return; export default defineSetupPluginEntry(acmeChatPlugin); ``` - OpenClaw завантажує це замість повної точки входу, коли канал вимкнений - або не налаштований. Це дає змогу не підтягувати важкий runtime-код під час потоків setup. - Подробиці дивіться в [Setup and Config](/uk/plugins/sdk-setup#setup-entry). + OpenClaw завантажує це замість повної точки входу, коли канал вимкнено + або не налаштовано. Це дає змогу не підтягувати важкий runtime-код під час процесів налаштування. + Докладніше дивіться в [Налаштування і Config](/uk/plugins/sdk-setup#setup-entry). - Вашому плагіну потрібно отримувати повідомлення з платформи та пересилати їх до + Ваш плагін має отримувати повідомлення з платформи й переспрямовувати їх до OpenClaw. Типовий шаблон — це webhook, який перевіряє запит і - диспетчеризує його через inbound-обробник вашого каналу: + диспетчеризує його через вхідний обробник вашого каналу: ```typescript registerFull(api) { @@ -501,16 +516,16 @@ if (decision.shouldSkip) return; ``` - Обробка вхідних повідомлень залежить від каналу. Кожен плагін каналу має - власний inbound-конвеєр. Подивіться на вбудовані плагіни каналів - (наприклад, пакет плагіна Microsoft Teams або Google Chat), щоб побачити реальні шаблони. + Обробка вхідних повідомлень залежить від каналу. Кожен плагін каналу відповідає + за власний вхідний конвеєр. Подивіться на вбудовані плагіни каналів + (наприклад, пакет плагінів Microsoft Teams або Google Chat), щоб побачити реальні шаблони. -Пишіть colocated тести в `src/channel.test.ts`: +Пишіть колоковані тести в `src/channel.test.ts`: ```typescript src/channel.test.ts import { describe, it, expect } from "vitest"; @@ -548,7 +563,7 @@ if (decision.shouldSkip) return; pnpm test -- /acme-chat/ ``` - Спільні helper-и для тестування дивіться в [Тестування](/uk/plugins/sdk-testing). + Спільні помічники тестування дивіться в [Тестування](/uk/plugins/sdk-testing). @@ -562,7 +577,7 @@ if (decision.shouldSkip) return; ├── index.ts # defineChannelPluginEntry ├── setup-entry.ts # defineSetupPluginEntry ├── api.ts # Публічні експорти (необов’язково) -├── runtime-api.ts # Внутрішні експорти runtime (необов’язково) +├── runtime-api.ts # Внутрішні runtime-експорти (необов’язково) └── src/ ├── channel.ts # ChannelPlugin через createChatChannelPlugin ├── channel.test.ts # Тести @@ -573,30 +588,30 @@ if (decision.shouldSkip) return; ## Розширені теми - - Фіксовані, у межах облікового запису або користувацькі режими reply + + Фіксовані режими відповіді, режими з областю облікового запису або власні - + describeMessageTool і виявлення дій inferTargetChatType, looksLikeId, resolveTarget - - TTS, STT, media, subagent через api.runtime + + TTS, STT, медіа, subagent через api.runtime -Деякі вбудовані helper-шви все ще існують для підтримки вбудованих плагінів і -сумісності. Вони не є рекомендованим шаблоном для нових плагінів каналів; -віддавайте перевагу загальним channel/setup/reply/runtime subpath зі спільної -поверхні SDK, якщо тільки ви безпосередньо не підтримуєте цю сім’ю вбудованих плагінів. +Деякі вбудовані допоміжні шви все ще існують для підтримки вбудованих плагінів і +сумісності. Це не рекомендований шаблон для нових плагінів каналів; +віддавайте перевагу загальним підшляхам channel/setup/reply/runtime зі спільної +поверхні SDK, якщо тільки ви не підтримуєте безпосередньо це сімейство вбудованих плагінів. ## Наступні кроки - [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — якщо ваш плагін також надає моделі -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник з import subpath +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів підшляхів - [Тестування SDK](/uk/plugins/sdk-testing) — тестові утиліти та контрактні тести - [Маніфест плагіна](/uk/plugins/manifest) — повна схема маніфесту diff --git a/docs/uk/plugins/sdk-migration.md b/docs/uk/plugins/sdk-migration.md index e371a6055..474dbcd7c 100644 --- a/docs/uk/plugins/sdk-migration.md +++ b/docs/uk/plugins/sdk-migration.md @@ -5,95 +5,131 @@ read_when: - Ви оновлюєте plugin до сучасної архітектури plugin - Ви підтримуєте зовнішній plugin OpenClaw sidebarTitle: Migrate to SDK -summary: Перейдіть із застарілого шару зворотної сумісності на сучасний plugin SDK +summary: Перейдіть зі застарілого шару зворотної сумісності на сучасний plugin SDK title: Міграція Plugin SDK x-i18n: - generated_at: "2026-04-06T22:33:54Z" + generated_at: "2026-04-07T18:43:55Z" model: gpt-5.4 provider: openai - source_hash: 3691060e9dc00ca8bee49240a047f0479398691bd14fb96e9204cc9243fdb32c + source_hash: 509699c3432191a1b2e4214c66d6d620e8d13a064cb2e7b9b38460c7ea45a20d source_path: plugins/sdk-migration.md workflow: 15 --- # Міграція Plugin SDK -OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури -plugin із цільовими, задокументованими імпортами. Якщо ваш plugin було створено -до появи нової архітектури, цей посібник допоможе вам виконати міграцію. +OpenClaw перейшов від широкого шару зворотної сумісності до сучасної +архітектури plugin із цільовими, задокументованими імпортами. Якщо ваш plugin +було створено до появи нової архітектури, цей посібник допоможе вам +перейти на неї. ## Що змінюється -Стара система plugin надавала дві дуже широкі поверхні, які дозволяли plugin -імпортувати все, що їм потрібно, з однієї точки входу: +Стара система plugin надавала дві відкриті поверхні, які дозволяли plugin +імпортувати все необхідне з єдиної точки входу: - **`openclaw/plugin-sdk/compat`** — єдиний імпорт, який повторно експортував - десятки допоміжних засобів. Його було запроваджено, щоб старіші plugin на - основі hooks продовжували працювати, поки будувалася нова архітектура plugin. -- **`openclaw/extension-api`** — міст, який надавав plugin прямий доступ до - допоміжних засобів на боці хоста, таких як вбудований runner агента. + десятки допоміжних функцій. Його було запроваджено, щоб зберегти роботу + старіших plugin на основі hook, поки створювалася нова архітектура plugin. +- **`openclaw/extension-api`** — міст, що надавав plugin прямий доступ до + допоміжних функцій на боці хоста, як-от вбудований засіб запуску agent. Обидві поверхні тепер **застарілі**. Вони все ще працюють під час виконання, -але нові plugin не повинні їх використовувати, а наявні plugin мають виконати -міграцію до того, як наступний мажорний реліз їх видалить. +але нові plugin не повинні їх використовувати, а наявним plugin слід +перейти до того, як наступний мажорний випуск їх прибере. - Шар зворотної сумісності буде видалено в одному з майбутніх мажорних релізів. - Plugins, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться. + Шар зворотної сумісності буде видалено в одному з майбутніх мажорних + випусків. Plugins, які все ще імпортують із цих поверхонь, перестануть + працювати, коли це станеться. ## Чому це змінилося -Старий підхід створював проблеми: +Старий підхід спричиняв проблеми: -- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки не пов’язаних між собою модулів -- **Циклічні залежності** — широкі повторні експорти спрощували створення циклів імпорту -- **Нечітка поверхня API** — не було способу визначити, які експорти були стабільними, а які внутрішніми +- **Повільний запуск** — імпорт однієї допоміжної функції завантажував десятки + не пов’язаних між собою модулів +- **Циклічні залежності** — широкі повторні експорти спрощували створення + циклів імпорту +- **Нечітка поверхня API** — не було способу визначити, які експорти є + стабільними, а які внутрішніми -Сучасний plugin SDK виправляє це: кожен шлях імпорту (`openclaw/plugin-sdk/\`) -є невеликим, самодостатнім модулем із чітким призначенням і задокументованим контрактом. +Сучасний plugin SDK вирішує це: кожен шлях імпорту (`openclaw/plugin-sdk/\`) +є невеликим, самодостатнім модулем із чітким призначенням і задокументованим +контрактом. -Застарілі зручні seams провайдерів для вбудованих каналів також зникли. Імпорти +Застарілі зручні шви provider для вбудованих каналів також зникли. Імпорти на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -допоміжні seams із брендуванням каналів і -`openclaw/plugin-sdk/telegram-core` були приватними скороченнями mono-repo, а не -стабільними контрактами plugin. Натомість використовуйте вузькі узагальнені SDK subpaths. Усередині -робочого простору вбудованих plugin зберігайте допоміжні засоби, що належать провайдеру, у власних -`api.ts` або `runtime-api.ts` цього plugin. +брендовані допоміжні шви каналів і +`openclaw/plugin-sdk/telegram-core` були приватними скороченнями +моно-репозиторію, а не стабільними контрактами plugin. Натомість +використовуйте вузькі загальні підшляхи SDK. Усередині робочого простору +вбудованих plugin зберігайте допоміжні функції, що належать provider, у +власному `api.ts` або `runtime-api.ts` цього plugin. -Поточні приклади вбудованих провайдерів: +Поточні приклади вбудованих provider: -- Anthropic зберігає допоміжні засоби потоків, специфічні для Claude, у власному seam `api.ts` / - `contract-api.ts` -- OpenAI зберігає конструктори провайдерів, допоміжні засоби моделей за замовчуванням і конструктори realtime-провайдерів +- Anthropic зберігає допоміжні функції потоку, специфічні для Claude, у + власному шві `api.ts` / `contract-api.ts` +- OpenAI зберігає builder-и provider, допоміжні функції моделей за + замовчуванням і builder-и realtime provider у власному `api.ts` +- OpenRouter зберігає builder provider та допоміжні функції онбордингу/конфігурації у власному `api.ts` -- OpenRouter зберігає конструктор провайдера та допоміжні засоби онбордингу/конфігурації у власному - `api.ts` -## Як виконати міграцію +## Як перейти + + Plugins каналів із підтримкою approval тепер розкривають нативну поведінку + approval через `approvalCapability.nativeRuntime` разом зі спільним + реєстром runtime-context. + + Ключові зміни: + + - Замініть `approvalCapability.handler.loadRuntime(...)` на + `approvalCapability.nativeRuntime` + - Перенесіть автентифікацію/доставку, специфічні для approval, зі + застарілого зв’язування `plugin.auth` / `plugin.approvals` + на `approvalCapability` + - `ChannelPlugin.approvals` видалено з публічного контракту + channel-plugin; перенесіть поля delivery/native/render до + `approvalCapability` + - `plugin.auth` залишається лише для потоків входу/виходу з channel; hook + автентифікації approval там більше не читаються ядром + - Реєструйте runtime-об’єкти, що належать каналу, як-от clients, tokens або Bolt + apps, через `openclaw/plugin-sdk/channel-runtime-context` + - Не надсилайте повідомлення про перенаправлення, що належать plugin, з native approval handlers; + тепер ядро відповідає за повідомлення routed-elsewhere на основі фактичних результатів доставки + - Під час передавання `channelRuntime` у `createChannelManager(...)` надавайте + справжню поверхню `createPluginRuntime().channel`. Часткові stubs відхиляються. + + Поточне компонування можливостей approval дивіться в + `/plugins/sdk-channel-plugins`. + + + - Якщо ваш plugin використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані Windows - wrappers `.cmd`/`.bat` тепер аварійно завершуються в закритому режимі, якщо ви явно не передасте + Якщо ваш plugin використовує `openclaw/plugin-sdk/windows-spawn`, невизначені Windows + wrappers `.cmd`/`.bat` тепер завершуються з закритою відмовою, якщо ви явно не передасте `allowShellFallback: true`. ```typescript - // Before + // До const program = applyWindowsSpawnProgramPolicy({ candidate }); - // After + // Після const program = applyWindowsSpawnProgramPolicy({ candidate, - // Only set this for trusted compatibility callers that intentionally - // accept shell-mediated fallback. + // Установлюйте це лише для довірених викликів сумісності, які свідомо + // допускають резервний перехід через shell. allowShellFallback: true, }); ``` - Якщо ваш виклик не покладається навмисно на резервний shell-механізм, не встановлюйте - `allowShellFallback`, а натомість обробляйте викинуту помилку. + Якщо ваш виклик не покладається навмисно на резервний перехід через shell, + не встановлюйте `allowShellFallback` і натомість обробляйте згенеровану помилку. @@ -107,36 +143,36 @@ plugin із цільовими, задокументованими імпорт - + Кожен експорт зі старої поверхні відповідає конкретному сучасному шляху імпорту: ```typescript - // Before (deprecated backwards-compatibility layer) + // До (застарілий шар зворотної сумісності) import { createChannelReplyPipeline, createPluginRuntimeStore, resolveControlCommandGate, } from "openclaw/plugin-sdk/compat"; - // After (modern focused imports) + // Після (сучасні цільові імпорти) import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline"; import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Для допоміжних засобів на боці хоста використовуйте введений runtime plugin замість - прямого імпорту: + Для допоміжних функцій на боці хоста використовуйте впроваджений runtime plugin + замість прямого імпорту: ```typescript - // Before (deprecated extension-api bridge) + // До (застарілий міст extension-api) import { runEmbeddedPiAgent } from "openclaw/extension-api"; const result = await runEmbeddedPiAgent({ sessionId, prompt }); - // After (injected runtime) + // Після (впроваджений runtime) const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Той самий шаблон застосовується й до інших застарілих допоміжних засобів моста: + Такий самий шаблон застосовується й до інших застарілих допоміжних функцій моста: | Старий імпорт | Сучасний еквівалент | | --- | --- | @@ -146,7 +182,7 @@ plugin із цільовими, задокументованими імпорт | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | session store helpers | `api.runtime.agent.session.*` | + | допоміжні функції сховища session | `api.runtime.agent.session.*` | @@ -163,174 +199,176 @@ plugin із цільовими, задокументованими імпорт | Шлях імпорту | Призначення | Ключові експорти | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу plugin | `definePluginEntry` | - | `plugin-sdk/core` | Застарілий umbrella-повторний експорт для визначень/конструкторів входу каналу | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/plugin-entry` | Канонічна допоміжна функція точки входу plugin | `definePluginEntry` | + | `plugin-sdk/core` | Застарілий umbrella-повторний експорт для визначень/builders входу каналу | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | Експорт кореневої схеми конфігурації | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного провайдера | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Цільові визначення та конструктори входу каналу | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Підказки allowlist, конструктори статусу налаштування | - | `plugin-sdk/setup-runtime` | Допоміжні засоби runtime для налаштування | Безпечні для імпорту patch-адаптери налаштування, допоміжні засоби приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | - | `plugin-sdk/setup-adapter-runtime` | Допоміжні засоби адаптера налаштування | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | Допоміжні засоби інструментів налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби для кількох облікових записів | Допоміжні засоби списку облікових записів/конфігурації/гейтів дій | - | `plugin-sdk/account-id` | Допоміжні засоби account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису | Допоміжні засоби пошуку облікового запису + fallback до значення за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби облікового запису | Допоміжні засоби списку облікових записів/дій з обліковими записами | + | `plugin-sdk/provider-entry` | Допоміжна функція точки входу для одного provider | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Цільові визначення та builders входу каналу | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Спільні допоміжні функції майстра налаштування | Запити allowlist, builders стану налаштування | + | `plugin-sdk/setup-runtime` | Допоміжні функції runtime на етапі налаштування | Безпечні для імпорту patch-adapters налаштування, допоміжні функції нотаток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | + | `plugin-sdk/setup-adapter-runtime` | Допоміжні функції адаптера налаштування | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | Допоміжні функції інструментарію налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Допоміжні функції для кількох облікових записів | Допоміжні функції списку облікових записів/конфігурації/action-gate | + | `plugin-sdk/account-id` | Допоміжні функції account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | + | `plugin-sdk/account-resolution` | Допоміжні функції пошуку облікового запису | Допоміжні функції пошуку облікового запису + резервного значення за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі допоміжні функції облікових записів | Допоміжні функції списку облікових записів/дій облікового запису | | `plugin-sdk/channel-setup` | Адаптери майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | | `plugin-sdk/channel-pairing` | Примітиви DM pairing | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Підключення префікса відповіді + typing | `createChannelReplyPipeline` | + | `plugin-sdk/channel-reply-pipeline` | Префікс відповіді + wiring індикатора набору | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | Фабрики адаптерів конфігурації | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Конструктори схем конфігурації | Типи схем конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби конфігурації команд Telegram | Нормалізація назв команд, обрізання опису, перевірка дублікатів/конфліктів | - | `plugin-sdk/channel-policy` | Визначення політики груп/DM | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Відстеження статусу облікового запису | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Допоміжні засоби вхідного envelope | Спільні допоміжні засоби побудови route + envelope | - | `plugin-sdk/inbound-reply-dispatch` | Допоміжні засоби вхідної відповіді | Спільні допоміжні засоби record-and-dispatch | - | `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Допоміжні засоби вихідного медіа | Спільне завантаження вихідного медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби outbound runtime | Допоміжні засоби outbound identity/send delegate | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби thread-binding | Життєвий цикл thread-binding і допоміжні засоби адаптера | - | `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби media payload | Конструктор agent media payload для застарілих схем полів | - | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти channel runtime | + | `plugin-sdk/channel-config-schema` | Builders схем конфігурації | Типи схем конфігурації каналу | + | `plugin-sdk/telegram-command-config` | Допоміжні функції конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, валідація дублікатів/конфліктів | + | `plugin-sdk/channel-policy` | Визначення політики group/DM | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | Відстеження стану облікового запису | `createAccountStatusSink` | + | `plugin-sdk/inbound-envelope` | Допоміжні функції вхідних envelope | Спільні допоміжні функції маршрутизації + побудови envelope | + | `plugin-sdk/inbound-reply-dispatch` | Допоміжні функції вхідних відповідей | Спільні допоміжні функції запису та dispatch | + | `plugin-sdk/messaging-targets` | Розбір messaging targets | Допоміжні функції розбору/зіставлення цілей | + | `plugin-sdk/outbound-media` | Допоміжні функції вихідних медіа | Спільне завантаження вихідних медіа | + | `plugin-sdk/outbound-runtime` | Допоміжні функції вихідного runtime | Допоміжні функції outbound identity/send delegate | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні функції thread-binding | Допоміжні функції життєвого циклу thread-binding та адаптерів | + | `plugin-sdk/agent-media-payload` | Застарілі допоміжні функції media payload | Builder agent media payload для застарілих layout полів | + | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти runtime каналу | | `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів відповіді | | `plugin-sdk/runtime-store` | Постійне сховище plugin | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime | Допоміжні засоби runtime/logging/backup/install plugin | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби середовища runtime | Logger/runtime env, допоміжні засоби timeout, retry і backoff | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби plugin runtime | Допоміжні засоби команд/hooks/http/interactive для plugin | - | `plugin-sdk/hook-runtime` | Допоміжні засоби pipeline hooks | Спільні допоміжні засоби pipeline webhook/internal hook | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні засоби процесів | Спільні допоміжні засоби exec | - | `plugin-sdk/cli-runtime` | Допоміжні засоби CLI runtime | Форматування команд, очікування, допоміжні засоби версій | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби gateway | Gateway client і допоміжні засоби patch статусу каналу | - | `plugin-sdk/config-runtime` | Допоміжні засоби конфігурації | Допоміжні засоби завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби перевірки команд Telegram зі стабільним fallback, коли поверхня контракту вбудованого Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні засоби prompt для approval | Payload approval exec/plugin, допоміжні засоби можливостей/профілю approval, маршрутизація/runtime native approval | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби auth для approval | Визначення approver, auth дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби approval client | Допоміжні засоби профілю/фільтра native approval exec | - | `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби доставки approval | Адаптери можливостей/доставки native approval | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей approval | Допоміжні засоби прив’язки цілі/облікового запису native approval | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби відповіді approval | Допоміжні засоби payload відповіді approval exec/plugin | - | `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби trust, DM gating, external-content і збору секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Допоміжні засоби allowlist хостів і політики приватної мережі | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби SSRF runtime | Допоміжні засоби pinned-dispatcher, guarded fetch, SSRF policy | - | `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого кешу | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби diagnostic gating | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | Допоміжні засоби форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні засоби графа помилок | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch/proxy | `resolveFetch`, допоміжні засоби proxy | - | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Допоміжні засоби retry | `RetryConfig`, `retryAsync`, виконавці policy | + | `plugin-sdk/runtime` | Широкі допоміжні функції runtime | Допоміжні функції runtime/logging/backup/встановлення plugin | + | `plugin-sdk/runtime-env` | Вузькі допоміжні функції середовища runtime | Logger/runtime env, timeout, retry та backoff helpers | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні функції runtime plugin | Допоміжні функції команд/hooks/http/interactive plugin | + | `plugin-sdk/hook-runtime` | Допоміжні функції конвеєра hook | Спільні допоміжні функції конвеєра webhook/internal hook | + | `plugin-sdk/lazy-runtime` | Допоміжні функції lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Допоміжні функції процесів | Спільні допоміжні функції exec | + | `plugin-sdk/cli-runtime` | Допоміжні функції runtime CLI | Форматування команд, очікування, допоміжні функції версій | + | `plugin-sdk/gateway-runtime` | Допоміжні функції gateway | Client gateway та допоміжні функції patch статусу каналу | + | `plugin-sdk/config-runtime` | Допоміжні функції конфігурації | Допоміжні функції завантаження/запису конфігурації | + | `plugin-sdk/telegram-command-config` | Допоміжні функції команд Telegram | Допоміжні функції валідації команд Telegram зі стабільним резервним режимом, коли surface контракту вбудованого Telegram недоступна | + | `plugin-sdk/approval-runtime` | Допоміжні функції prompt approval | Payload approval exec/plugin, допоміжні функції capability/profile approval, native approval routing/runtime helpers | + | `plugin-sdk/approval-auth-runtime` | Допоміжні функції автентифікації approval | Визначення approver, автентифікація дій у тому ж чаті | + | `plugin-sdk/approval-client-runtime` | Допоміжні функції client approval | Допоміжні функції native exec approval profile/filter | + | `plugin-sdk/approval-delivery-runtime` | Допоміжні функції доставки approval | Адаптери native approval capability/delivery | + | `plugin-sdk/approval-handler-runtime` | Допоміжні функції handler approval | Спільні допоміжні функції runtime handler approval, включно із завантаженням native approval на основі capability | + | `plugin-sdk/approval-native-runtime` | Допоміжні функції цілей approval | Допоміжні функції binding native approval target/account | + | `plugin-sdk/approval-reply-runtime` | Допоміжні функції reply approval | Допоміжні функції payload reply approval exec/plugin | + | `plugin-sdk/channel-runtime-context` | Допоміжні функції runtime-context каналу | Загальні допоміжні функції register/get/watch для channel runtime-context | + | `plugin-sdk/security-runtime` | Допоміжні функції безпеки | Спільні допоміжні функції trust, DM gating, external-content і збирання secret | + | `plugin-sdk/ssrf-policy` | Допоміжні функції політики SSRF | Допоміжні функції allowlist хостів і політики приватної мережі | + | `plugin-sdk/ssrf-runtime` | Допоміжні функції runtime SSRF | Допоміжні функції pinned-dispatcher, guarded fetch, політики SSRF | + | `plugin-sdk/collection-runtime` | Допоміжні функції обмеженого кешу | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | Допоміжні функції керування діагностикою | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | Допоміжні функції форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні функції графа помилок | + | `plugin-sdk/fetch-runtime` | Допоміжні функції обгорнутого fetch/proxy | `resolveFetch`, допоміжні функції proxy | + | `plugin-sdk/host-runtime` | Допоміжні функції нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | Допоміжні функції retry | `RetryConfig`, `retryAsync`, виконавці політик | | `plugin-sdk/allow-from` | Форматування allowlist | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Зіставлення вводу allowlist | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Допоміжні засоби gating команд і поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд | - | `plugin-sdk/secret-input` | Розбір введення секретів | Допоміжні засоби введення секретів | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів webhook | Утиліти цілей webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби guards для тіла webhook-запиту | Допоміжні засоби читання/обмеження тіла запиту | - | `plugin-sdk/reply-runtime` | Спільний runtime відповідей | Inbound dispatch, heartbeat, планувальник відповідей, chunking | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch відповідей | Допоміжні засоби finalize + provider dispatch | - | `plugin-sdk/reply-history` | Допоміжні засоби історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | Планування посилань на відповідь | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Допоміжні засоби chunks відповіді | Допоміжні засоби chunking тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби session store | Допоміжні засоби шляху сховища + updated-at | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів стану | Допоміжні засоби каталогів state і OAuth | - | `plugin-sdk/routing` | Допоміжні засоби routing/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні засоби нормалізації session-key | - | `plugin-sdk/status-helpers` | Допоміжні засоби статусу каналу | Конструктори підсумку статусу каналу/облікового запису, значення runtime-state за замовчуванням, допоміжні засоби метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Допоміжні засоби target resolver | Спільні допоміжні засоби target resolver | - | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації рядків | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Допоміжні засоби URL запиту | Витяг рядкових URL із request-подібних вхідних даних | - | `plugin-sdk/run-command` | Допоміжні засоби timed command | Виконавець команд із таймерами та нормалізованими stdout/stderr | - | `plugin-sdk/param-readers` | Читачі параметрів | Поширені читачі параметрів tool/CLI | + | `plugin-sdk/allowlist-resolution` | Зіставлення вхідних даних allowlist | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Керування командами та допоміжні функції surface команд | `resolveControlCommandGate`, допоміжні функції авторизації відправника, допоміжні функції реєстру команд | + | `plugin-sdk/secret-input` | Розбір secret input | Допоміжні функції secret input | + | `plugin-sdk/webhook-ingress` | Допоміжні функції запитів webhook | Утиліти цілей webhook | + | `plugin-sdk/webhook-request-guards` | Допоміжні функції guard тіла webhook | Допоміжні функції читання/обмеження тіла запиту | + | `plugin-sdk/reply-runtime` | Спільний runtime відповідей | Inbound dispatch, heartbeat, planner відповідей, chunking | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch відповідей | Допоміжні функції finalize + dispatch provider | + | `plugin-sdk/reply-history` | Допоміжні функції історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-reference` | Планування reply reference | `createReplyReferencePlanner` | + | `plugin-sdk/reply-chunking` | Допоміжні функції chunk відповіді | Допоміжні функції chunking тексту/markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні функції сховища session | Шлях до сховища та допоміжні функції updated-at | + | `plugin-sdk/state-paths` | Допоміжні функції шляхів стану | Допоміжні функції директорій стану та OAuth | + | `plugin-sdk/routing` | Допоміжні функції маршрутизації/session-key | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні функції нормалізації session-key | + | `plugin-sdk/status-helpers` | Допоміжні функції статусу каналу | Builders зведення стану каналу/облікового запису, типові значення runtime-state, допоміжні функції метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Допоміжні функції target resolver | Спільні допоміжні функції target resolver | + | `plugin-sdk/string-normalization-runtime` | Допоміжні функції нормалізації рядків | Допоміжні функції нормалізації slug/рядків | + | `plugin-sdk/request-url` | Допоміжні функції URL запиту | Витягування рядкових URL з request-подібних вхідних даних | + | `plugin-sdk/run-command` | Допоміжні функції команд із тайм-аутом | Запускач команд із нормалізованими stdout/stderr | + | `plugin-sdk/param-readers` | Зчитувачі параметрів | Поширені зчитувачі параметрів tool/CLI | | `plugin-sdk/tool-send` | Витягування tool send | Витягування канонічних полів цілі надсилання з аргументів tool | - | `plugin-sdk/temp-path` | Допоміжні засоби тимчасових шляхів | Спільні допоміжні засоби тимчасових шляхів для завантажень | - | `plugin-sdk/logging-core` | Допоміжні засоби logging | Допоміжні засоби logger підсистеми та редагування | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби markdown-table | Допоміжні засоби режимів markdown-таблиць | - | `plugin-sdk/reply-payload` | Типи reply повідомлень | Типи reply payload | - | `plugin-sdk/provider-setup` | Куровані допоміжні засоби налаштування локального/self-hosted провайдера | Допоміжні засоби виявлення/конфігурації self-hosted провайдера | - | `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні засоби налаштування self-hosted провайдера, сумісного з OpenAI | Ті самі допоміжні засоби виявлення/конфігурації self-hosted провайдера | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби auth runtime провайдера | Допоміжні засоби визначення API-ключа під час runtime | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключа провайдера | Допоміжні засоби онбордингу/запису профілю API-ключа | - | `plugin-sdk/provider-auth-result` | Допоміжні засоби результату auth провайдера | Стандартний конструктор результату OAuth auth | - | `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу провайдера | Спільні допоміжні засоби інтерактивного входу | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби env vars провайдера | Допоміжні засоби пошуку env vars auth провайдера | - | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделі/повтору провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори replay-policy, допоміжні засоби endpoint провайдера та нормалізації model-id | - | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу провайдера | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Патчі онбордингу провайдера | Допоміжні засоби конфігурації онбордингу | - | `plugin-sdk/provider-http` | Допоміжні засоби HTTP провайдера | Узагальнені допоміжні засоби HTTP/можливостей endpoint провайдера | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch провайдера | Допоміжні засоби реєстрації/кешу провайдера web-fetch | - | `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту web-search провайдера | Цільові допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setters/getters облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби web-search провайдера | Допоміжні засоби реєстрації/кешу/runtime провайдера web-search | - | `plugin-sdk/provider-tools` | Допоміжні засоби сумісності tool/schema провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + diagnostics і допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Допоміжні засоби використання провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби використання провайдерів | - | `plugin-sdk/provider-stream` | Допоміжні засоби обгорток потоків провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/keyed-async-queue` | Упорядкована асинхронна черга | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби медіа | Допоміжні засоби fetch/transform/store медіа плюс конструктори media payload | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації медіа | Спільні допоміжні засоби failover, вибір кандидатів і повідомлення про відсутні моделі для генерації зображень/відео/музики | - | `plugin-sdk/media-understanding` | Допоміжні засоби media-understanding | Типи провайдера media understanding плюс орієнтовані на провайдера експорти допоміжних засобів для зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні текстові допоміжні засоби | Видалення видимого асистенту тексту, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування, directive-tag, safe-text utilities і пов’язані допоміжні засоби text/logging | - | `plugin-sdk/text-chunking` | Допоміжні засоби text chunking | Допоміжний засіб chunking вихідного тексту | - | `plugin-sdk/speech` | Допоміжні засоби speech | Типи провайдера speech плюс орієнтовані на провайдера допоміжні засоби директив, реєстру та перевірки | - | `plugin-sdk/speech-core` | Спільне ядро speech | Типи провайдера speech, реєстр, директиви, нормалізація | - | `plugin-sdk/realtime-transcription` | Допоміжні засоби realtime transcription | Типи провайдера та допоміжні засоби реєстру | - | `plugin-sdk/realtime-voice` | Допоміжні засоби realtime voice | Типи провайдера та допоміжні засоби реєстру | - | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Допоміжні засоби типів, failover, auth і реєстру для генерації зображень | - | `plugin-sdk/music-generation` | Допоміжні засоби генерації музики | Типи провайдера/запиту/результату для генерації музики | - | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, допоміжні засоби failover, пошук провайдера та розбір model-ref | - | `plugin-sdk/video-generation` | Допоміжні засоби генерації відео | Типи провайдера/запиту/результату для генерації відео | - | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, допоміжні засоби failover, пошук провайдера та розбір model-ref | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивної відповіді | Нормалізація/зведення payload інтерактивної відповіді | - | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви schema конфігурації каналу | - | `plugin-sdk/channel-config-writes` | Допоміжні засоби запису конфігурації каналу | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Спільні експорти prelude channel plugin | - | `plugin-sdk/channel-status` | Допоміжні засоби статусу каналу | Спільні допоміжні засоби snapshot/summary статусу каналу | - | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби конфігурації allowlist | Допоміжні засоби редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Допоміжні засоби доступу груп | Спільні допоміжні засоби рішень group-access | - | `plugin-sdk/direct-dm` | Допоміжні засоби direct-DM | Спільні допоміжні засоби auth/guard direct-DM | - | `plugin-sdk/extension-shared` | Спільні допоміжні засоби extension | Примітиви passive-channel/status і ambient proxy helper | - | `plugin-sdk/webhook-targets` | Допоміжні засоби цілей webhook | Реєстр цілей webhook і допоміжні засоби встановлення route | - | `plugin-sdk/webhook-path` | Допоміжні засоби шляху webhook | Допоміжні засоби нормалізації шляху webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби web media | Допоміжні засоби завантаження віддаленого/локального медіа | + | `plugin-sdk/temp-path` | Допоміжні функції тимчасових шляхів | Спільні допоміжні функції шляхів тимчасового завантаження | + | `plugin-sdk/logging-core` | Допоміжні функції logging | Logger підсистеми та допоміжні функції редагування | + | `plugin-sdk/markdown-table-runtime` | Допоміжні функції таблиць Markdown | Допоміжні функції режиму таблиць Markdown | + | `plugin-sdk/reply-payload` | Типи відповідей на повідомлення | Типи payload відповіді | + | `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локальних/self-hosted provider | Допоміжні функції виявлення/конфігурації self-hosted provider | + | `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні функції налаштування self-hosted provider, сумісних з OpenAI | Ті самі допоміжні функції виявлення/конфігурації self-hosted provider | + | `plugin-sdk/provider-auth-runtime` | Допоміжні функції runtime-автентифікації provider | Допоміжні функції визначення ключа API під час runtime | + | `plugin-sdk/provider-auth-api-key` | Допоміжні функції налаштування ключа API provider | Допоміжні функції онбордингу/запису профілю для ключів API | + | `plugin-sdk/provider-auth-result` | Допоміжні функції результату автентифікації provider | Стандартний builder результату автентифікації OAuth | + | `plugin-sdk/provider-auth-login` | Допоміжні функції інтерактивного входу provider | Спільні допоміжні функції інтерактивного входу | + | `plugin-sdk/provider-env-vars` | Допоміжні функції env vars provider | Допоміжні функції пошуку env var для автентифікації provider | + | `plugin-sdk/provider-model-shared` | Спільні допоміжні функції моделей/replay provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builders політик replay, допоміжні функції endpoint provider та нормалізації model-id | + | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні функції каталогу provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Patches онбордингу provider | Допоміжні функції конфігурації онбордингу | + | `plugin-sdk/provider-http` | Допоміжні функції HTTP provider | Загальні допоміжні функції HTTP/можливостей endpoint provider | + | `plugin-sdk/provider-web-fetch` | Допоміжні функції web-fetch provider | Допоміжні функції реєстрації/кешу web-fetch provider | + | `plugin-sdk/provider-web-search-contract` | Допоміжні функції контракту web-search provider | Вузькі допоміжні функції контракту конфігурації/облікових даних web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і setter/getter для scoped credentials | + | `plugin-sdk/provider-web-search` | Допоміжні функції web-search provider | Допоміжні функції реєстрації/кешу/runtime web-search provider | + | `plugin-sdk/provider-tools` | Допоміжні функції сумісності tool/schema provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + діагностика, а також допоміжні функції сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Допоміжні функції використання provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні функції використання provider | + | `plugin-sdk/provider-stream` | Допоміжні функції обгорток потоку provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper та спільні допоміжні функції обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/keyed-async-queue` | Упорядкована async-черга | `KeyedAsyncQueue` | + | `plugin-sdk/media-runtime` | Спільні допоміжні функції медіа | Допоміжні функції fetch/transform/store медіа, а також builders media payload | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції генерації медіа | Спільні допоміжні функції failover, вибору candidate та повідомлень про відсутність моделі для генерації зображень/відео/музики | + | `plugin-sdk/media-understanding` | Допоміжні функції media-understanding | Типи provider media understanding, а також exports допоміжних функцій зображення/аудіо для provider | + | `plugin-sdk/text-runtime` | Спільні допоміжні функції тексту | Видалення тексту, видимого assistant, допоміжні функції render/chunking/table для markdown, допоміжні функції редагування, directive-tag, safe-text utilities та пов’язані допоміжні функції text/logging | + | `plugin-sdk/text-chunking` | Допоміжні функції chunking тексту | Допоміжна функція chunking вихідного тексту | + | `plugin-sdk/speech` | Допоміжні функції speech | Типи provider speech, а також exports допоміжних функцій directive, registry і validation для provider | + | `plugin-sdk/speech-core` | Спільне ядро speech | Типи provider speech, registry, directives, normalization | + | `plugin-sdk/realtime-transcription` | Допоміжні функції realtime transcription | Типи provider та допоміжні функції registry | + | `plugin-sdk/realtime-voice` | Допоміжні функції realtime voice | Типи provider та допоміжні функції registry | + | `plugin-sdk/image-generation-core` | Спільне ядро image-generation | Типи image-generation, failover, auth та допоміжні функції registry | + | `plugin-sdk/music-generation` | Допоміжні функції music-generation | Типи provider/request/result для генерації музики | + | `plugin-sdk/music-generation-core` | Спільне ядро music-generation | Типи music-generation, допоміжні функції failover, пошуку provider та розбору model-ref | + | `plugin-sdk/video-generation` | Допоміжні функції video-generation | Типи provider/request/result для генерації відео | + | `plugin-sdk/video-generation-core` | Спільне ядро video-generation | Типи video-generation, допоміжні функції failover, пошуку provider та розбору model-ref | + | `plugin-sdk/interactive-runtime` | Допоміжні функції інтерактивних відповідей | Нормалізація/зведення payload інтерактивних відповідей | + | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви channel config-schema | + | `plugin-sdk/channel-config-writes` | Допоміжні функції запису конфігурації каналу | Допоміжні функції авторизації запису конфігурації каналу | + | `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Exports спільного prelude channel plugin | + | `plugin-sdk/channel-status` | Допоміжні функції статусу каналу | Спільні допоміжні функції snapshot/summary статусу каналу | + | `plugin-sdk/allowlist-config-edit` | Допоміжні функції конфігурації allowlist | Допоміжні функції редагування/читання конфігурації allowlist | + | `plugin-sdk/group-access` | Допоміжні функції доступу до group | Спільні допоміжні функції прийняття рішень щодо доступу до group | + | `plugin-sdk/direct-dm` | Допоміжні функції direct-DM | Спільні допоміжні функції автентифікації/guard для direct-DM | + | `plugin-sdk/extension-shared` | Спільні допоміжні функції extension | Примітиви passive-channel/status та ambient proxy helper | + | `plugin-sdk/webhook-targets` | Допоміжні функції цілей webhook | Реєстр цілей webhook і допоміжні функції встановлення маршрутів | + | `plugin-sdk/webhook-path` | Допоміжні функції шляхів webhook | Допоміжні функції нормалізації шляхів webhook | + | `plugin-sdk/web-media` | Спільні допоміжні функції web media | Допоміжні функції завантаження віддалених/локальних медіа | | `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для споживачів plugin SDK | - | `plugin-sdk/memory-core` | Допоміжні засоби вбудованого memory-core | Поверхня допоміжних засобів memory manager/config/file/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime для memory engine | Фасад runtime для індексації/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Foundation engine хоста пам’яті | Експорти foundation engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Embedding engine хоста пам’яті | Експорти embedding engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-qmd` | QMD engine хоста пам’яті | Експорти QMD engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-storage` | Storage engine хоста пам’яті | Експорти storage engine хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті | Мультимодальні допоміжні засоби хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні засоби query хоста пам’яті | Допоміжні засоби query хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста пам’яті | Допоміжні засоби secret хоста пам’яті | - | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | Допоміжні засоби журналу подій хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | Допоміжні засоби статусу хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime хоста пам’яті | Допоміжні засоби CLI runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Core runtime хоста пам’яті | Допоміжні засоби core runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Псевдонім core runtime хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних засобів core runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Допоміжні засоби керованого markdown | Спільні допоміжні засоби керованого markdown для plugin, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Фасад активного пошуку пам’яті | Лінивий фасад runtime search-manager активної пам’яті | - | `plugin-sdk/memory-host-status` | Псевдонім статусу хоста пам’яті | Нейтральний до постачальника псевдонім для допоміжних засобів статусу хоста пам’яті | - | `plugin-sdk/memory-lancedb` | Допоміжні засоби вбудованого memory-lancedb | Поверхня допоміжних засобів memory-lancedb | - | `plugin-sdk/testing` | Утиліти тестування | Допоміжні засоби тестування та mocks | + | `plugin-sdk/memory-core` | Допоміжні функції вбудованого memory-core | Surface допоміжних функцій memory manager/config/file/CLI | + | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime рушія пам’яті | Фасад runtime індексації/пошуку пам’яті | + | `plugin-sdk/memory-core-host-engine-foundation` | Рушій foundation хоста пам’яті | Exports рушія foundation хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embeddings хоста пам’яті | Exports рушія embeddings хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD хоста пам’яті | Exports рушія QMD хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-storage` | Рушій сховища хоста пам’яті | Exports рушія сховища хоста пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції multimodal хоста пам’яті | Допоміжні функції multimodal хоста пам’яті | + | `plugin-sdk/memory-core-host-query` | Допоміжні функції запитів хоста пам’яті | Допоміжні функції запитів хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Допоміжні функції secret хоста пам’яті | Допоміжні функції secret хоста пам’яті | + | `plugin-sdk/memory-core-host-events` | Допоміжні функції журналу подій хоста пам’яті | Допоміжні функції журналу подій хоста пам’яті | + | `plugin-sdk/memory-core-host-status` | Допоміжні функції статусу хоста пам’яті | Допоміжні функції статусу хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime хоста пам’яті | Допоміжні функції CLI runtime хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-core` | Core runtime хоста пам’яті | Допоміжні функції core runtime хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції файлів/runtime хоста пам’яті | Допоміжні функції файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-core` | Псевдонім core runtime хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних функцій core runtime хоста пам’яті | + | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних функцій журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних функцій файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-markdown` | Допоміжні функції керованого markdown | Спільні допоміжні функції керованого markdown для plugin, суміжних із memory | + | `plugin-sdk/memory-host-search` | Фасад пошуку active memory | Лінивий фасад runtime search-manager active memory | + | `plugin-sdk/memory-host-status` | Псевдонім статусу хоста пам’яті | Нейтральний щодо постачальника псевдонім для допоміжних функцій статусу хоста пам’яті | + | `plugin-sdk/memory-lancedb` | Допоміжні функції вбудованого memory-lancedb | Surface допоміжних функцій memory-lancedb | + | `plugin-sdk/testing` | Тестові утиліти | Допоміжні функції та mocks для тестування | -Ця таблиця навмисно містить поширену підмножину для міграції, а не повну -поверхню SDK. Повний список із понад 200 entrypoints розміщено в +Ця таблиця навмисно охоплює поширену підмножину для міграції, а не всю +поверхню SDK. Повний список із понад 200 точок входу наведено в `scripts/lib/plugin-sdk-entrypoints.json`. -Цей список усе ще містить деякі допоміжні seams вбудованих plugin, такі як +Цей список усе ще містить деякі шви допоміжних функцій вбудованих plugin, як-от `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й далі експортуються для підтримки та сумісності вбудованих plugin, але навмисно -не включені до таблиці поширеної міграції та не є рекомендованою ціллю для +не включені до таблиці поширеної міграції й не є рекомендованою ціллю для нового коду plugin. -Те саме правило застосовується й до інших сімейств вбудованих допоміжних засобів, зокрема: +Те саме правило застосовується до інших сімейств вбудованих допоміжних функцій, таких як: -- допоміжні засоби підтримки браузера: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` +- допоміжні функції підтримки browser: `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- вбудовані допоміжні засоби/поверхні plugin, такі як `plugin-sdk/googlechat`, +- surfaces вбудованих helper/plugin, як-от `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -339,39 +377,40 @@ plugin із цільовими, задокументованими імпорт `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` і `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` наразі надає вузьку поверхню допоміжних засобів токена: +`plugin-sdk/github-copilot-token` наразі розкриває вузьку surface допоміжних функцій токенів: `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken`. -Використовуйте найвужчий імпорт, який відповідає вашому завданню. Якщо ви не можете знайти потрібний експорт, -перевірте вихідний код у `src/plugin-sdk/` або запитайте в Discord. +Використовуйте найвужчий імпорт, який відповідає завданню. Якщо ви не можете +знайти потрібний експорт, перевірте вихідний код у `src/plugin-sdk/` +або запитайте в Discord. -## Хронологія видалення +## Часова шкала видалення | Коли | Що відбувається | | ---------------------- | ----------------------------------------------------------------------- | -| **Зараз** | Застарілі поверхні надсилають попередження під час runtime | -| **Наступний мажорний реліз** | Застарілі поверхні буде видалено; plugins, які все ще їх використовують, перестануть працювати | +| **Зараз** | Застарілі поверхні видають попередження під час runtime | +| **Наступний мажорний випуск** | Застарілі поверхні буде видалено; plugins, які все ще їх використовують, перестануть працювати | -Усі core plugins уже мігровано. Зовнішнім plugins слід виконати міграцію -до наступного мажорного релізу. +Усі core plugins уже перенесено. Зовнішнім plugin слід перейти +до наступного мажорного випуску. ## Тимчасове приглушення попереджень -Поки ви працюєте над міграцією, встановіть ці змінні середовища: +Установіть ці змінні середовища, поки працюєте над міграцією: ```bash OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -Це тимчасовий обхідний механізм, а не постійне рішення. +Це тимчасовий обхідний шлях, а не постійне рішення. ## Пов’язане - [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший plugin -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпорту subpath -- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення channel plugins -- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення provider plugins -- [Внутрішня будова plugin](/uk/plugins/architecture) — глибокий огляд архітектури +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів subpath +- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення plugin каналів +- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення plugin provider +- [Внутрішня будова plugin](/uk/plugins/architecture) — глибокий розбір архітектури - [Маніфест plugin](/uk/plugins/manifest) — довідник зі схеми маніфесту diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index 981dde3b6..ad7d7c43c 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,33 +1,33 @@ --- read_when: - Вам потрібно знати, з якого підшляху SDK імпортувати - - Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi + - Вам потрібен довідник щодо всіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK Overview summary: Карта імпорту, довідник API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-07T08:02:41Z" + generated_at: "2026-04-07T18:43:53Z" model: gpt-5.4 provider: openai - source_hash: 6ba11d1708a117f3872a09fd0bebb0481d36b89b473aec861192e8c2745ef727 + source_hash: 68d9b78dab757747cfa0e315376af72040ef79453129c0fa051c4c9dd948060f source_path: plugins/sdk-overview.md workflow: 15 --- # Огляд Plugin SDK -Plugin SDK — це типізований контракт між плагінами та ядром. Ця сторінка — -довідник про **що імпортувати** і **що можна зареєструвати**. +Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка є +довідником щодо **що імпортувати** і **що можна реєструвати**. - **Шукаєте покроковий посібник?** - - Перший плагін? Почніть із [Getting Started](/uk/plugins/building-plugins) - - Плагін каналу? Дивіться [Channel Plugins](/uk/plugins/sdk-channel-plugins) - - Плагін провайдера? Дивіться [Provider Plugins](/uk/plugins/sdk-provider-plugins) + **Шукаєте практичний посібник?** + - Перший plugin? Почніть із [Getting Started](/uk/plugins/building-plugins) + - Plugin каналу? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins) + - Plugin провайдера? Див. [Provider Plugins](/uk/plugins/sdk-provider-plugins) -## Угода щодо імпорту +## Угода про імпорт Завжди імпортуйте з конкретного підшляху: @@ -36,40 +36,40 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Кожен підшлях — це невеликий самодостатній модуль. Це зберігає швидкий запуск і +Кожен підшлях — це невеликий, самодостатній модуль. Це пришвидшує запуск і запобігає проблемам із циклічними залежностями. Для специфічних для каналу -допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте -для ширшої узагальненої поверхні та спільних допоміжних засобів, таких як +допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для +ширшої парасолькової поверхні та спільних допоміжних засобів, таких як `buildChannelConfigSchema`. -Не додавайте і не покладайтеся на зручні шви, названі на честь провайдерів, такі як +Не додавайте й не використовуйте зручні шари з назвами провайдерів, як-от `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або -допоміжні шви з брендингом каналів. Вбудовані плагіни мають компонувати -загальні підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а ядро -має або використовувати ці локальні для плагіна barrel-файли, або додати вузький загальний SDK -контракт, якщо потреба справді є міжканальною. +допоміжні шари з брендуванням каналів. Вбудовані plugins мають компонувати загальні +підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а ядро +має або використовувати ці локальні для plugin barrel-файли, або додати вузький загальний SDK +контракт, коли потреба справді є міжканальною. -Згенерована карта експорту все ще містить невеликий набір допоміжних -швів вбудованих плагінів, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +Згенерована карта експортів усе ще містить невеликий набір допоміжних +шарів для вбудованих plugins, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці -підшляхи існують лише для підтримки та сумісності вбудованих плагінів; вони -навмисно пропущені в загальній таблиці нижче і не є рекомендованим -шляхом імпорту для нових сторонніх плагінів. +підшляхи існують лише для підтримки вбудованих plugins і сумісності; вони +навмисно не включені до загальної таблиці нижче й не є рекомендованим +шляхом імпорту для нових сторонніх plugins. ## Довідник підшляхів Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. -Зарезервовані допоміжні підшляхи вбудованих плагінів усе ще з’являються в цьому -згенерованому списку. Вважайте їх деталями реалізації/поверхнями сумісності, якщо -сторінка документації явно не оголошує якийсь із них публічним. +Зарезервовані допоміжні підшляхи для вбудованих plugins усе ще з’являються в цьому згенерованому списку. +Ставтеся до них як до деталей реалізації/поверхонь сумісності, якщо якась сторінка документації +явно не позначає один із них як публічний. -### Entry плагіна +### Вхід plugin -| Підшлях | Ключові експорти | -| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| Subpath | Ключові експорти | +| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | | `plugin-sdk/config-schema` | `OpenClawSchema` | @@ -77,155 +77,157 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; - | Підшлях | Ключові експорти | + | Subpath | Ключові експорти | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити списку allowlist, збирачі статусу налаштування | + | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити списку дозволених, конструктори статусу налаштування | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби багатооблікового запису config/action-gate, допоміжні засоби резервного вибору типового облікового запису | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації id облікового запису | - | `plugin-sdk/account-resolution` | Пошук облікового запису + допоміжні засоби резервного вибору типового значення | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби списку облікових записів/дій з обліковими записами | + | `plugin-sdk/account-core` | Допоміжні засоби для мультиакаунтної конфігурації/гейтінгу дій, допоміжні засоби резервного переходу до акаунта за замовчуванням | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації ідентифікатора акаунта | + | `plugin-sdk/account-resolution` | Пошук акаунта + допоміжні засоби резервного переходу до значення за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку акаунтів/дій з акаунтами | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Типи схеми конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервним варіантом для вбудованого контракту | + | `plugin-sdk/channel-config-schema` | Типи схем конфігурації каналу | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною сумісністю для вбудованого контракту | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних повідомлень + побудови envelope | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних даних | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби побудови вхідного маршруту та envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних повідомлень | | `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей | | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби делегування вихідної ідентичності/надсилання | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу та адаптера прив’язок потоків | - | `plugin-sdk/agent-media-payload` | Застарілий збирач медіапейлоаду агента | - | `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки розмови/потоку, парування та налаштованих прив’язок | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби для вихідної ідентичності/делегатів надсилання | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптерів | + | `plugin-sdk/agent-media-payload` | Застарілий конструктор медіа-пейлоаду агента | + | `plugin-sdk/conversation-runtime` | Допоміжні засоби для прив’язки розмови/потоку, pairing і налаштованих прив’язок | | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації runtime | - | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групової політики runtime | - | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку стану каналу | + | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення політик груп у runtime | + | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімків/зведень статусу каналу | | `plugin-sdk/channel-config-primitives` | Вузькі примітиви schema конфігурації каналу | | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти плагінів каналів | - | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Спільні допоміжні засоби ухвалення рішень щодо групового доступу | - | `plugin-sdk/direct-dm` | Спільні допоміжні засоби авторизації/захисту для прямих DM | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби нормалізації/скорочення інтерактивного reply payload | - | `plugin-sdk/channel-inbound` | Допоміжні засоби debounce для вхідних повідомлень, зіставлення згадок, політики згадок і допоміжні засоби envelope | - | `plugin-sdk/channel-send-result` | Типи результату відповіді | + | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти channel plugin | + | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби читання/редагування конфігурації списку дозволених | + | `plugin-sdk/group-access` | Спільні допоміжні засоби прийняття рішень щодо групового доступу | + | `plugin-sdk/direct-dm` | Спільні допоміжні засоби авторизації/захисту прямих DM | + | `plugin-sdk/interactive-runtime` | Допоміжні засоби нормалізації/зведення пейлоадів інтерактивних відповідей | + | `plugin-sdk/channel-inbound` | Вхідний debounce, зіставлення згадок, допоміжні засоби політики згадок і допоміжні засоби envelope | + | `plugin-sdk/channel-send-result` | Типи результатів відповіді | | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` | | `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей | | `plugin-sdk/channel-contract` | Типи контракту каналу | - | `plugin-sdk/channel-feedback` | Налаштування зворотного зв’язку/реакцій | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби секретного контракту, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів | + | `plugin-sdk/channel-feedback` | Підключення відгуків/реакцій | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби секретного контракту, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, а також типи цілей секретів | - | Підшлях | Ключові експорти | + | Subpath | Ключові експорти | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | - | `plugin-sdk/cli-backend` | Типові значення CLI backend + константи watchdog | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключа в runtime для плагінів провайдерів | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-ключа, такі як `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний збирач результату OAuth-автентифікації | - | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для плагінів провайдерів | + | `plugin-sdk/cli-backend` | Значення за замовчуванням бекенда CLI + константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключів у runtime для plugins провайдерів | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю для API-ключів, такі як `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний конструктор результату OAuth-автентифікації | + | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для plugins провайдерів | | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env vars для автентифікації провайдера | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні збирачі політик replay, допоміжні засоби endpoint провайдерів і допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори replay-policy, допоміжні засоби endpoint провайдера та допоміжні засоби нормалізації model-id, як-от `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint провайдера | - | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту config/selection для web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешу для web-fetch провайдера | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту config/credential для web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешу/runtime для web-search провайдера | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення + діагностика схеми Gemini та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування web-fetch провайдерів | + | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter-и облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime web-search провайдерів | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні засоби wrapper для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-onboard` | Допоміжні засоби внесення патчів до конфігурації онбордингу | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper-ів і спільні допоміжні wrapper-и для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу | | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | - | Підшлях | Ключові експорти | + | Subpath | Ключові експорти | | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, допоміжні засоби авторизації відправника | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення апрувера та авторизації дій у тому самому чаті | + | `plugin-sdk/approval-auth-runtime` | Визначення approver-а та допоміжні засоби action-auth у тому самому чаті | | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval | - | `plugin-sdk/approval-delivery-runtime` | Адаптери доставки/можливостей native approval | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби native approval target + прив’язки облікового запису | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби reply payload для approval exec/plugin | + | `plugin-sdk/approval-delivery-runtime` | Адаптери доставлення/можливостей native approval | + | `plugin-sdk/approval-handler-runtime` | Спільні допоміжні засоби runtime обробника approval, зокрема capability-driven завантаження native approval | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей native approval + прив’язки акаунтів | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби пейлоаду відповіді для exec/plugin approval | | `plugin-sdk/command-auth-native` | Native command auth + допоміжні засоби native session-target | | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | - | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команди та поверхні команд | + | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команд і командної поверхні | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збору секретних контрактів для секретних поверхонь каналу/плагіна | - | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору секретних контрактів/конфігурації | - | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, обмеження DM, external-content і збору секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом від SSRF і політики SSRF | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь секретів каналів/plugins | + | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору secret-contract/config | + | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, зовнішнього контенту та збирання секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби host allowlist і політики SSRF для приватних мереж | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, SSRF-захищеного fetch і політики SSRF | | `plugin-sdk/secret-input` | Допоміжні засоби розбору секретного вводу | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілі webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру body/timeout для запитів | + | `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілей webhook | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби для розміру тіла запиту/таймаутів | - | Підшлях | Ключові експорти | + | Subpath | Ключові експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/logging/backup/plugin-install | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env, logger, timeout, retry і backoff | + | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/логування/резервних копій/встановлення plugins | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env runtime, logger, timeout, retry і backoff | + | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку channel runtime-context | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби command/hook/http/interactive для плагінів | - | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline для webhook/internal hook | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy runtime import/binding, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/hook/http/interactive для plugins | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби пайплайна webhook/internal hook | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy import/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Допоміжні засоби exec процесів | | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування та версій | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта gateway і патчів статусу каналу | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта gateway і патчів статусу каналів | | `plugin-sdk/config-runtime` | Допоміжні засоби завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram та перевірки на дублікати/конфлікти, навіть коли поверхня вбудованого контракту Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні засоби approval exec/plugin, збирачі approval-capability, допоміжні засоби auth/profile, native routing/runtime | - | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби inbound/reply runtime, chunking, dispatch, heartbeat, планувальник reply | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize для reply | - | `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window reply-history, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram і перевірки дублювання/конфліктів, навіть якщо поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, конструктори approval-capability, допоміжні засоби auth/profile, native routing/runtime | + | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби вхідного/reply runtime, chunking, dispatch, heartbeat, planner відповідей | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize для відповідей | + | `plugin-sdk/reply-history` | Спільні допоміжні засоби коротковіконної історії відповідей, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій + updated-at | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів каталогу state/OAuth | - | `plugin-sdk/routing` | Допоміжні засоби прив’язки маршруту/ключа сесії/облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку статусу каналу/облікового запису, типові значення стану runtime та допоміжні засоби метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілі | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху до session store + updated-at | + | `plugin-sdk/state-paths` | Допоміжні засоби шляхів до каталогів state/OAuth | + | `plugin-sdk/routing` | Допоміжні засоби прив’язки route/session-key/account, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби зведення статусу каналів/акаунтів, значення runtime-state за замовчуванням і допоміжні засоби метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби target resolver | | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Витягування рядкових URL із введення, подібного до fetch/request | + | `plugin-sdk/request-url` | Витяг рядкових URL із fetch/request-подібних входів | | `plugin-sdk/run-command` | Виконавець команд із таймером і нормалізованими результатами stdout/stderr | - | `plugin-sdk/param-readers` | Поширені читачі параметрів tool/CLI | - | `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів інструмента | - | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляху тимчасового завантаження | - | `plugin-sdk/logging-core` | Допоміжні засоби subsystem logger і редагування чутливих даних | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму Markdown-таблиць | - | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON | - | `plugin-sdk/file-lock` | Допоміжні засоби повторно-вхідного file-lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні засоби дискового кешу dedupe | - | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/session і reply-dispatch для ACP | + | `plugin-sdk/param-readers` | Поширені читачі параметрів tools/CLI | + | `plugin-sdk/tool-send` | Витяг канонічних полів цілей надсилання з аргументів tool | + | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів тимчасових завантажень | + | `plugin-sdk/logging-core` | Допоміжні засоби logger підсистеми та редагування конфіденційних даних | + | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму markdown-таблиць | + | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON state | + | `plugin-sdk/file-lock` | Реентрантні допоміжні засоби file-lock | + | `plugin-sdk/persistent-dedupe` | Допоміжні засоби disk-backed dedupe cache | + | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/session ACP і reply-dispatch | | `plugin-sdk/agent-config-primitives` | Вузькі примітиви schema конфігурації runtime агента | | `plugin-sdk/boolean-param` | Гнучкий читач булевих параметрів | - | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення зіставлення небезпечних назв | - | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів сполучення | - | `plugin-sdk/extension-shared` | Спільні примітиви для passive-channel, статусу та ambient proxy helper | - | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді `/models` command/provider | + | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення небезпечних імен | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів pairing | + | `plugin-sdk/extension-shared` | Спільні примітиви пасивного каналу, статусу й ambient proxy helper | + | `plugin-sdk/models-provider-runtime` | Допоміжні засоби команд `/models` і відповідей провайдерів | | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби переліку команд Skills | - | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize для native command | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI | + | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize native команд | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.A.I | | `plugin-sdk/infra-runtime` | Допоміжні засоби системних подій/heartbeat | | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців і подій | | `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy та pinned lookup | - | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації імені хоста та SCP-хоста | + | `plugin-sdk/fetch-runtime` | Допоміжні засоби wrapped fetch, proxy і pinned lookup | + | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host | | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконавця retry | | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/workspace агента | | `plugin-sdk/directory-runtime` | Запит/усунення дублікатів каталогів на основі конфігурації | @@ -233,125 +235,125 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; - | Підшлях | Ключові експорти | + | Subpath | Ключові експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також збирачі медіапейлоадів | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store медіа плюс конструктори медіа-пейлоадів | | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибір кандидатів і повідомлення про відсутню модель | - | `plugin-sdk/media-understanding` | Типи провайдера media understanding, а також орієнтовані на провайдерів експорти допоміжних засобів для зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як вилучення видимого для асистента тексту, допоміжні засоби render/chunking/table для markdown, редагування чутливих даних, допоміжні засоби тегів директив і safe-text утиліти | - | `plugin-sdk/text-chunking` | Допоміжний засіб chunking для вихідного тексту | - | `plugin-sdk/speech` | Типи провайдерів мовлення, а також орієнтовані на провайдерів допоміжні засоби для директив, реєстру та валідації | - | `plugin-sdk/speech-core` | Спільні типи провайдерів мовлення, допоміжні засоби реєстру, директив і нормалізації | - | `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі та допоміжні засоби реєстру | - | `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та допоміжні засоби реєстру | + | `plugin-sdk/media-understanding` | Типи провайдерів Media understanding плюс орієнтовані на провайдерів експорти допоміжних засобів для зображень/аудіо | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби для тексту/markdown/логування, такі як видалення видимого асистенту тексту, допоміжні засоби render/chunking/table для markdown, редагування конфіденційних даних, допоміжні засоби тегів директив і безпечного тексту | + | `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту | + | `plugin-sdk/speech` | Типи speech-провайдерів плюс орієнтовані на провайдерів допоміжні засоби директив, реєстру та валідації | + | `plugin-sdk/speech-core` | Спільні типи speech-провайдерів, реєстру, директив і допоміжні засоби нормалізації | + | `plugin-sdk/realtime-transcription` | Типи провайдерів realtime transcription і допоміжні засоби реєстру | + | `plugin-sdk/realtime-voice` | Типи провайдерів realtime voice і допоміжні засоби реєстру | | `plugin-sdk/image-generation` | Типи провайдерів генерації зображень | | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і реєстру | - | `plugin-sdk/music-generation` | Типи провайдера/запиту/результату генерації музики | - | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук провайдера та розбір model-ref | - | `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео | - | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук провайдера та розбір model-ref | + | `plugin-sdk/music-generation` | Типи провайдерів/запитів/результатів генерації музики | + | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук провайдерів і розбір model-ref | + | `plugin-sdk/video-generation` | Типи провайдерів/запитів/результатів генерації відео | + | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук провайдерів і розбір model-ref | | `plugin-sdk/webhook-targets` | Реєстр цілей webhook і допоміжні засоби встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху webhook | + | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляхів webhook | | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | + | `plugin-sdk/zod` | Реекспортований `zod` для користувачів Plugin SDK | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - | Підшлях | Ключові експорти | + | Subpath | Ключові експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для manager/config/file/CLI | + | `plugin-sdk/memory-core` | Поверхня допоміжних засобів вбудованого memory-core для manager/config/file/CLI helper-ів | | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексації/пошуку пам’яті | | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті | | `plugin-sdk/memory-core-host-engine-embeddings` | Експорти embedding engine хоста пам’яті | | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті | | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби multimodal хоста пам’яті | + | `plugin-sdk/memory-core-host-query` | Допоміжні засоби query хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста пам’яті | | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби CLI runtime хоста пам’яті | | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста пам’яті | | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Нейтральний щодо вендора псевдонім для допоміжних засобів core runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Нейтральний щодо вендора псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Нейтральний щодо вендора псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для плагінів, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Активний фасад runtime пам’яті для доступу до search-manager | - | `plugin-sdk/memory-host-status` | Нейтральний щодо вендора псевдонім для допоміжних засобів статусу хоста пам’яті | - | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb | + | `plugin-sdk/memory-host-core` | Вендорно-нейтральний псевдонім для допоміжних засобів core runtime хоста пам’яті | + | `plugin-sdk/memory-host-events` | Вендорно-нейтральний псевдонім для допоміжних засобів журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Вендорно-нейтральний псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби managed-markdown для plugins, суміжних із пам’яттю | + | `plugin-sdk/memory-host-search` | Фасад runtime активної пам’яті для доступу до search-manager | + | `plugin-sdk/memory-host-status` | Вендорно-нейтральний псевдонім для допоміжних засобів статусу хоста пам’яті | + | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів вбудованого memory-lancedb | - - | Сімейство | Поточні підшляхи | Призначення | + + | Family | Поточні підшляхи | Призначення | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки вбудованого browser plugin (`browser-support` залишається barrel-файлом сумісності) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня helper/runtime вбудованого Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper/runtime вбудованого LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів вбудованого IRC | - | Допоміжні засоби, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжних засобів для вбудованих каналів | - | Допоміжні засоби, специфічні для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних засобів для вбудованих можливостей/плагінів; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки вбудованого browser plugin (`browser-support` лишається barrel-ом сумісності) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня helper-ів/runtime вбудованого Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper-ів/runtime вбудованого LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня helper-ів вбудованого IRC | + | Channel-specific helpers | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шари helper-ів/сумісності для вбудованих каналів | + | Auth/plugin-specific helpers | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шари helper-ів для вбудованих функцій/plugins; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | ## API реєстрації -Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими +Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими методами: ### Реєстрація можливостей -| Метод | Що він реєструє | -| ------------------------------------------------ | -------------------------------- | -| `api.registerProvider(...)` | Текстовий inference (LLM) | -| `api.registerCliBackend(...)` | Локальний CLI backend для inference | -| `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | -| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі | -| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерація зображень | -| `api.registerMusicGenerationProvider(...)` | Генерація музики | +| Method | Що реєструє | +| ------------------------------------------------ | ------------------------------- | +| `api.registerProvider(...)` | Текстовий inference (LLM) | +| `api.registerCliBackend(...)` | Локальний inference-бекенд CLI | +| `api.registerChannel(...)` | Канал обміну повідомленнями | +| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Потокова realtime transcription | +| `api.registerRealtimeVoiceProvider(...)` | Двосторонні сесії realtime voice | +| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | +| `api.registerImageGenerationProvider(...)` | Генерація зображень | +| `api.registerMusicGenerationProvider(...)` | Генерація музики | | `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | -| `api.registerWebSearchProvider(...)` | Вебпошук | +| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | +| `api.registerWebSearchProvider(...)` | Вебпошук | -### Інструменти та команди +### Tools і команди -| Метод | Що він реєструє | -| ------------------------------- | --------------------------------------------- | +| Method | Що реєструє | +| ------------------------------- | -------------------------------------------- | | `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацька команда (обходить LLM) | +| `api.registerCommand(def)` | Користувацька команда (обходить LLM) | ### Інфраструктура -| Метод | Що він реєструє | -| ---------------------------------------------- | --------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Хук подій | -| `api.registerHttpRoute(params)` | HTTP endpoint gateway | -| `api.registerGatewayMethod(name, handler)` | RPC-метод gateway | -| `api.registerCli(registrar, opts?)` | Підкоманда CLI | -| `api.registerService(service)` | Фонова служба | -| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | +| Method | Що реєструє | +| ---------------------------------------------- | ------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Хук подій | +| `api.registerHttpRoute(params)` | HTTP endpoint gateway | +| `api.registerGatewayMethod(name, handler)` | RPC-метод gateway | +| `api.registerCli(registrar, opts?)` | Підкоманда CLI | +| `api.registerService(service)` | Фоновий сервіс | +| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | | `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із пам’яттю | -| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | +| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | -Зарезервовані простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити -вужчу область методу gateway. Для -методів, що належать плагіну, віддавайте перевагу префіксам, специфічним для плагіна. +Зарезервовані простори імен адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`, +`update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається призначити +вужчу область методу gateway. Для методів, що належать plugin, віддавайте перевагу префіксам, +специфічним для plugin. ### Метадані реєстрації CLI -`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: +`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня: -- `commands`: явні корені команд, які належать registrar -- `descriptors`: дескриптори команд на етапі розбору, які використовуються для довідки кореневого CLI, - маршрутизації та ледачої реєстрації CLI плагіна +- `commands`: явні корені команд, що належать registrar +- `descriptors`: дескриптори команд на етапі розбору, які використовуються для кореневої довідки CLI, + маршрутизації та lazy-реєстрації plugin CLI -Якщо ви хочете, щоб команда плагіна залишалася ледачо завантажуваною в -звичайному шляху кореневого CLI, надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що експонується цим +Якщо ви хочете, щоб команда plugin залишалася lazy-loaded у звичайному шляху кореневого CLI, +надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, відкритий цим registrar. ```typescript @@ -364,7 +366,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Керуйте обліковими записами Matrix, верифікацією, пристроями та станом профілю", + description: "Керування акаунтами Matrix, верифікацією, пристроями та станом профілю", hasSubcommands: true, }, ], @@ -372,128 +374,128 @@ api.registerCli( ); ``` -Використовуйте лише `commands`, якщо вам не потрібна ледача реєстрація кореневого CLI. -Цей сумісний eager-шлях залишається підтримуваним, але він не встановлює -placeholders на основі descriptor для ледачого завантаження на етапі розбору. +Використовуйте лише `commands`, якщо вам не потрібна lazy-реєстрація кореневого CLI. +Цей сумісний eager-шлях і далі підтримується, але він не встановлює +placeholder-и на основі descriptor для lazy loading на етапі розбору. ### Реєстрація CLI backend -`api.registerCliBackend(...)` дає змогу плагіну володіти типовою конфігурацією для локального -AI CLI backend, такого як `codex-cli`. +`api.registerCliBackend(...)` дозволяє plugin керувати конфігурацією за замовчуванням для локального +CLI backend AI, такого як `codex-cli`. -- `id` backend стає префіксом провайдера в model ref на кшталт `codex-cli/gpt-5`. +- `id` backend стає префіксом провайдера в model ref, наприклад `codex-cli/gpt-5`. - `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.`. - Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.` поверх - типового значення плагіна перед запуском CLI. -- Використовуйте `normalizeConfig`, коли backend потребує переписування для сумісності після злиття + значення за замовчуванням plugin перед запуском CLI. +- Використовуйте `normalizeConfig`, коли backend потребує переписування сумісності після злиття (наприклад, нормалізації старих форм прапорців). ### Ексклюзивні слоти -| Метод | Що він реєструє | -| ------------------------------------------ | ------------------------------------- | -| `api.registerContextEngine(id, factory)` | Контекстний рушій (одночасно активний лише один) | -| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам’яті | -| `api.registerMemoryPromptSection(builder)` | Конструктор розділу prompt пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Resolver плану очищення пам’яті | -| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | +| Method | Що реєструє | +| ------------------------------------------ | ------------------------------------ | +| `api.registerContextEngine(id, factory)` | Context engine (лише один активний одночасно) | +| `api.registerMemoryCapability(capability)` | Єдину можливість пам’яті | +| `api.registerMemoryPromptSection(builder)` | Конструктор розділу prompt пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану flush для пам’яті | +| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | -### Адаптери вбудовування пам’яті +### Адаптери embedding для пам’яті -| Метод | Що він реєструє | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного плагіна | +| Method | Що реєструє | +| ---------------------------------------------- | --------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного plugin | -- `registerMemoryCapability` — це рекомендований API ексклюзивного плагіна пам’яті. -- `registerMemoryCapability` також може експонувати `publicArtifacts.listArtifacts(...)`, - щоб супутні плагіни могли споживати експортовані артефакти пам’яті через - `openclaw/plugin-sdk/memory-host-core` замість звернення до приватної - структури конкретного плагіна пам’яті. +- `registerMemoryCapability` — рекомендований API ексклюзивного plugin пам’яті. +- `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`, + щоб супровідні plugins могли споживати експортовані артефакти пам’яті через + `openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватної + структури конкретного plugin пам’яті. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` — це застарілі, але сумісні API ексклюзивних плагінів пам’яті. -- `registerMemoryEmbeddingProvider` дає активному плагіну пам’яті змогу зареєструвати один - або більше id адаптерів embedding (наприклад, `openai`, `gemini` або користувацький - id, визначений плагіном). -- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і + `registerMemoryRuntime` — це застарілі, але сумісні API ексклюзивного plugin пам’яті. +- `registerMemoryEmbeddingProvider` дозволяє активному plugin пам’яті зареєструвати один + або кілька id адаптерів embedding (наприклад, `openai`, `gemini` або власний + id, визначений plugin). +- Користувацька конфігурація, така як `agents.defaults.memorySearch.provider` і `agents.defaults.memorySearch.fallback`, визначається відносно цих зареєстрованих id адаптерів. ### Події та життєвий цикл -| Метод | Що він робить | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | -| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови | +| Method | Що робить | +| -------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | +| `api.onConversationBindingResolved(handler)` | Колбек прив’язки розмови | -### Семантика рішень хука +### Семантика рішень hook -- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановить це значення, обробники з нижчим пріоритетом пропускаються. - `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. -- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановить це значення, обробники з нижчим пріоритетом пропускаються. - `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник заявляє про диспетчеризацію, обробники з нижчим пріоритетом і типовий шлях диспетчеризації моделі пропускаються. -- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник візьме dispatch на себе, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються. +- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановить це значення, обробники з нижчим пріоритетом пропускаються. - `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як пропуск `cancel`), а не перевизначенням. ### Поля об’єкта API -| Поле | Тип | Опис | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | ID плагіна | -| `api.name` | `string` | Назва для відображення | -| `api.version` | `string?` | Версія плагіна (необов’язково) | -| `api.description` | `string?` | Опис плагіна (необов’язково) | -| `api.source` | `string` | Шлях до джерела плагіна | -| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime у пам’яті, коли доступний) | -| `api.pluginConfig` | `Record` | Конфігурація, специфічна для плагіна, з `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger з обмеженою областю (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування до повного entry | -| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня плагіна | +| Field | Type | Опис | +| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------- | +| `api.id` | `string` | Ідентифікатор plugin | +| `api.name` | `string` | Відображувана назва | +| `api.version` | `string?` | Версія plugin (необов’язково) | +| `api.description` | `string?` | Опис plugin (необов’язково) | +| `api.source` | `string` | Шлях до джерела plugin | +| `api.rootDir` | `string?` | Кореневий каталог plugin (необов’язково) | +| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок runtime у пам’яті, якщо доступний) | +| `api.pluginConfig` | `Record` | Конфігурація plugin з `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного entry | +| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня plugin | -## Внутрішня угода щодо модулів +## Угода про внутрішні модулі -Усередині вашого плагіна використовуйте локальні barrel-файли для внутрішніх імпортів: +У межах вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів: ``` my-plugin/ api.ts # Публічні експорти для зовнішніх споживачів - runtime-api.ts # Лише внутрішні експорти runtime - index.ts # Точка входу плагіна + runtime-api.ts # Внутрішні runtime-експорти + index.ts # Точка входу plugin setup-entry.ts # Полегшений entry лише для налаштування (необов’язково) ``` - Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/` - у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або + Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/` + у production-коді. Для внутрішніх імпортів використовуйте `./api.ts` або `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. -Фасадно-завантажувані публічні поверхні вбудованих плагінів (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` та подібні публічні entry-файли) тепер віддають перевагу -активному знімку конфігурації runtime, якщо OpenClaw уже запущено. Якщо знімок runtime -ще не існує, вони повертаються до визначеного файла конфігурації на диску. +Facade-loaded публічні поверхні вбудованих plugins (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` і подібні публічні entry-файли) тепер віддають перевагу +активному знімку конфігурації runtime, якщо OpenClaw уже запущено. Якщо знімка runtime +ще не існує, вони повертаються до визначеного файлу конфігурації на диску. -Плагіни провайдерів також можуть експонувати вузький локальний barrel-файл контракту плагіна, коли -певний допоміжний засіб навмисно є специфічним для провайдера і ще не належить до -загального підшляху SDK. Поточний вбудований приклад: провайдер Anthropic зберігає свої -допоміжні засоби потоків Claude у власному публічному шві `api.ts` / `contract-api.ts` -замість просування логіки beta-header Anthropic і `service_tier` у загальний -контракт `plugin-sdk/*`. +Plugins провайдерів також можуть надавати вузький локальний barrel контракту plugin, якщо +helper навмисно є специфічним для провайдера й поки що не належить до загального +підшляху SDK. Поточний приклад серед вбудованих: провайдер Anthropic зберігає свої helper-и +Claude stream у власному публічному шарі `api.ts` / `contract-api.ts` замість +просування логіки Anthropic beta-header і `service_tier` до загального +контракту `plugin-sdk/*`. -Інші поточні вбудовані приклади: +Інші поточні приклади серед вбудованих: -- `@openclaw/openai-provider`: `api.ts` експортує збирачі провайдерів, - допоміжні засоби типових моделей і збирачі realtime-провайдерів -- `@openclaw/openrouter-provider`: `api.ts` експортує збирач провайдера, а також - допоміжні засоби онбордингу/конфігурації +- `@openclaw/openai-provider`: `api.ts` експортує конструктори провайдерів, + helper-и моделей за замовчуванням і конструктори realtime-провайдерів +- `@openclaw/openrouter-provider`: `api.ts` експортує конструктор провайдера та + helper-и онбордингу/конфігурації - Production-код розширень також має уникати імпортів `openclaw/plugin-sdk/`. - Якщо допоміжний засіб справді є спільним, перенесіть його до нейтрального підшляху SDK, - такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - поверхні, орієнтованої на можливість, замість зв’язування двох плагінів між собою. + Production-код extension також має уникати імпортів `openclaw/plugin-sdk/`. + Якщо helper справді є спільним, перенесіть його до нейтрального підшляху SDK, + такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або до іншої + поверхні, орієнтованої на можливості, замість жорсткого зв’язування двох plugins. ## Пов’язане @@ -503,4 +505,4 @@ my-plugin/ - [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації - [Testing](/uk/plugins/sdk-testing) — утиліти тестування та правила lint - [SDK Migration](/uk/plugins/sdk-migration) — міграція із застарілих поверхонь -- [Plugin Internals](/uk/plugins/architecture) — глибока архітектура та модель можливостей +- [Plugin Internals](/uk/plugins/architecture) — поглиблена архітектура та модель можливостей diff --git a/docs/uk/tools/exec-approvals.md b/docs/uk/tools/exec-approvals.md index b1d38ba9e..bcf4d7d01 100644 --- a/docs/uk/tools/exec-approvals.md +++ b/docs/uk/tools/exec-approvals.md @@ -1,65 +1,65 @@ --- read_when: - - Налаштовуєте підтвердження exec або allowlist-и - - Реалізуєте UX підтвердження exec у застосунку macOS - - Переглядаєте запити на вихід із sandbox та їхні наслідки -summary: Підтвердження Exec, allowlist-и та запити на вихід із sandbox -title: Підтвердження Exec + - Налаштування підтверджень exec або списків дозволів + - Реалізація UX підтвердження exec у застосунку macOS + - Перегляд запитів на вихід із sandbox і пов’язаних наслідків +summary: Підтвердження exec, списки дозволів і запити на вихід із sandbox +title: Підтвердження exec x-i18n: - generated_at: "2026-04-05T18:21:15Z" + generated_at: "2026-04-07T18:43:49Z" model: gpt-5.4 provider: openai - source_hash: 39e91cd5c7615bdb9a6b201a85bde7514327910f6f12da5a4b0532bceb229c22 + source_hash: 6041929185bab051ad873cc4822288cb7d6f0470e19e7ae7a16b70f76dfc2cd9 source_path: tools/exec-approvals.md workflow: 15 --- # Підтвердження exec -Підтвердження exec — це **запобіжний механізм companion app / вузла-хоста** для того, щоб дозволити sandbox-агенту запускати -команди на реальному хості (`gateway` або `node`). Думайте про це як про запобіжне блокування: -команди дозволяються лише тоді, коли політика + allowlist + (необов’язкове) підтвердження користувача збігаються. +Підтвердження exec — це **захисний механізм застосунку-компаньйона / хоста вузла** для дозволу sandbox-агенту запускати +команди на реальному хості (`gateway` або `node`). Сприймайте це як запобіжне блокування: +команди дозволяються лише тоді, коли політика + список дозволів + (необов’язкове) підтвердження користувача всі погоджуються. Підтвердження exec діють **додатково** до політики інструментів і elevated gating (якщо тільки elevated не встановлено в `full`, що пропускає підтвердження). -Ефективна політика — це **суворіше** з `tools.exec.*` і типових значень підтверджень; якщо поле підтверджень пропущено, використовується значення `tools.exec`. +Ефективна політика — це **суворіша** з `tools.exec.*` і типових значень підтверджень; якщо поле підтверджень пропущене, використовується значення `tools.exec`. Host exec також використовує локальний стан підтверджень на цій машині. Локальне для хоста -`ask: "always"` у `~/.openclaw/exec-approvals.json` продовжує показувати запити, навіть якщо +`ask: "always"` у `~/.openclaw/exec-approvals.json` продовжує запитувати навіть якщо типові значення сесії або конфігурації вимагають `ask: "on-miss"`. Використовуйте `openclaw approvals get`, `openclaw approvals get --gateway` або `openclaw approvals get --node `, щоб переглянути запитану політику, джерела політики хоста та ефективний результат. -Якщо UI companion app **недоступний**, будь-який запит, що потребує підтвердження, -обробляється через **ask fallback** (типово: deny). +Якщо UI застосунку-компаньйона **недоступний**, будь-який запит, що потребує підтвердження, +обробляється через **резервну поведінку ask** (типово: deny). -Нативні клієнти підтвердження в чаті також можуть надавати прив’язаний до каналу інтерфейс у -повідомленні з очікуванням підтвердження. Наприклад, Matrix може додати скорочення через реакції до -запиту підтвердження (`✅` дозволити один раз, `❌` відхилити та `♾️` дозволити завжди, якщо доступно), -при цьому залишаючи команди `/approve ...` у повідомленні як резервний варіант. +Власні клієнти підтвердження в чаті також можуть надавати специфічні для каналу елементи інтерфейсу в повідомленні +про очікуване підтвердження. Наприклад, Matrix може додавати швидкі реакції до +запиту на підтвердження (`✅` дозволити один раз, `❌` відхилити та `♾️` завжди дозволяти, коли доступно), +водночас залишаючи команди `/approve ...` у повідомленні як резервний варіант. ## Де це застосовується Підтвердження exec застосовуються локально на хості виконання: - **gateway host** → процес `openclaw` на машині gateway -- **node host** → runner вузла (companion app macOS або headless node host) +- **node host** → раннер вузла (застосунок-компаньйон macOS або headless node host) -Примітка про модель довіри: +Примітка щодо моделі довіри: -- Виклики, автентифіковані gateway, вважаються довіреними операторами для цього Gateway. -- Спарені вузли розширюють цю можливість довіреного оператора на host вузла. -- Підтвердження exec знижують ризик випадкового виконання, але не є межею автентифікації на рівні користувача. -- Схвалені запуски на host вузла прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env, - якщо вона присутня, і зафіксований шлях до виконуваного файла, якщо застосовно. +- Викликачі, автентифіковані gateway, є довіреними операторами для цього Gateway. +- Спарені вузли розширюють цю можливість довіреного оператора на хост вузла. +- Підтвердження exec зменшують ризик випадкового виконання, але не є межею автентифікації на рівні користувача. +- Схвалені запуски на хості вузла прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env + за наявності та зафіксований шлях до виконуваного файла, де це застосовно. - Для shell-скриптів і прямих викликів файлів інтерпретатора/середовища виконання OpenClaw також намагається прив’язати один конкретний локальний файловий операнд. Якщо цей прив’язаний файл змінюється після підтвердження, але до виконання, запуск відхиляється замість виконання зміненого вмісту. -- Ця прив’язка файла навмисно є best-effort, а не повною семантичною моделлю для кожного - шляху завантажувача інтерпретатора/середовища виконання. Якщо режим підтвердження не може визначити рівно один конкретний локальний - файл для прив’язки, він відмовляється створювати запуск на основі підтвердження замість того, щоб удавати повне покриття. +- Ця прив’язка файлів навмисно є best-effort, а не повною семантичною моделлю для кожного шляху + завантажувача інтерпретатора/середовища виконання. Якщо режим підтвердження не може точно визначити один конкретний локальний + файл для прив’язки, він відмовляється створювати запуск із підтвердженням, а не вдає повне покриття. -Поділ на macOS: +Поділ у macOS: -- **служба node host** пересилає `system.run` до **застосунку macOS** через локальний IPC. +- **служба хоста вузла** пересилає `system.run` до **застосунку macOS** через локальний IPC. - **застосунок macOS** застосовує підтвердження + виконує команду в контексті UI. ## Налаштування та зберігання @@ -105,10 +105,10 @@ Host exec також використовує локальний стан під ## Режим "YOLO" без підтверджень -Якщо ви хочете, щоб host exec працював без запитів на підтвердження, потрібно відкрити **обидва** шари політики: +Якщо ви хочете, щоб host exec запускався без запитів на підтвердження, потрібно відкрити **обидва** шари політики: -- запитана політика exec у конфігурації OpenClaw (`tools.exec.*`) -- локальна політика підтверджень хоста в `~/.openclaw/exec-approvals.json` +- запитану політику exec у конфігурації OpenClaw (`tools.exec.*`) +- локальну для хоста політику підтверджень у `~/.openclaw/exec-approvals.json` Тепер це типова поведінка хоста, якщо ви явно не зробите її суворішою: @@ -116,17 +116,17 @@ Host exec також використовує локальний стан під - `tools.exec.ask`: `off` - host `askFallback`: `full` -Важлива різниця: +Важливе розрізнення: -- `tools.exec.host=auto` вибирає, де виконується exec: у sandbox, якщо доступно, інакше на gateway. -- YOLO визначає, як підтверджується host exec: `security=full` плюс `ask=off`. -- У режимі YOLO OpenClaw не додає окремий евристичний бар’єр підтвердження для обфускації команд поверх налаштованої політики host exec. -- `auto` не перетворює маршрутизацію на gateway на вільне перевизначення із сесії в sandbox. Запит `host=node` для окремого виклику дозволений із `auto`, а `host=gateway` дозволений із `auto` лише тоді, коли немає активного середовища виконання sandbox. Якщо вам потрібне стабільне типове значення без auto, задайте `tools.exec.host` або використовуйте `/exec host=...` явно. +- `tools.exec.host=auto` вибирає, де виконується exec: у sandbox, коли доступно, інакше на gateway. +- YOLO вибирає, як схвалюється host exec: `security=full` плюс `ask=off`. +- У режимі YOLO OpenClaw не додає окремий евристичний бар’єр підтвердження обфускації команд поверх налаштованої політики host exec. +- `auto` не робить маршрутизацію через gateway вільним обходом із sandbox-сесії. Запит `host=node` на рівні окремого виклику дозволений із `auto`, а `host=gateway` дозволяється з `auto` лише тоді, коли немає активного runtime sandbox. Якщо вам потрібен стабільний типово не-`auto` режим, задайте `tools.exec.host` або використовуйте `/exec host=...` явно. -Якщо ви хочете більш консервативне налаштування, поверніть будь-який шар до `allowlist` / `on-miss` +Якщо вам потрібне більш консервативне налаштування, знову зробіть суворішим будь-який із шарів до `allowlist` / `on-miss` або `deny`. -Постійне налаштування для gateway host "ніколи не показувати запит": +Постійне налаштування gateway host "ніколи не запитувати": ```bash openclaw config set tools.exec.host gateway @@ -135,7 +135,7 @@ openclaw config set tools.exec.ask off openclaw gateway restart ``` -Потім налаштуйте файл підтверджень хоста відповідно: +Потім приведіть файл підтверджень хоста у відповідність: ```bash openclaw approvals set --stdin <<'EOF' @@ -150,7 +150,7 @@ openclaw approvals set --stdin <<'EOF' EOF ``` -Для host вузла застосуйте той самий файл підтверджень на цьому вузлі: +Для хоста вузла замість цього застосуйте той самий файл підтверджень на цьому вузлі: ```bash openclaw approvals set --node --stdin <<'EOF' @@ -165,39 +165,39 @@ openclaw approvals set --node --stdin <<'EOF' EOF ``` -Скорочення лише для сесії: +Ярлик лише для сесії: - `/exec security=full ask=off` змінює лише поточну сесію. -- `/elevated full` — це break-glass скорочення, яке також пропускає підтвердження exec для цієї сесії. +- `/elevated full` — це аварійний shortcut, який також пропускає підтвердження exec для цієї сесії. -Якщо файл підтверджень хоста залишається суворішим за конфігурацію, суворіша політика хоста все одно має пріоритет. +Якщо файл підтверджень хоста залишається суворішим за конфігурацію, усе одно перемагає суворіша політика хоста. ## Параметри політики ### Security (`exec.security`) - **deny**: блокувати всі запити host exec. -- **allowlist**: дозволяти лише команди з allowlist. -- **full**: дозволяти все (еквівалент elevated). +- **allowlist**: дозволяти лише команди зі списку дозволів. +- **full**: дозволяти все (еквівалентно elevated). ### Ask (`exec.ask`) -- **off**: ніколи не показувати запит. -- **on-miss**: показувати запит лише тоді, коли allowlist не збігається. -- **always**: показувати запит для кожної команди. -- тривала довіра `allow-always` не пригнічує запити, коли ефективний режим ask дорівнює `always` +- **off**: ніколи не запитувати. +- **on-miss**: запитувати лише коли список дозволів не збігається. +- **always**: запитувати для кожної команди. +- довіреність `allow-always` не пригнічує запити, коли ефективний режим ask — `always` ### Ask fallback (`askFallback`) -Якщо потрібне підтвердження, але жоден UI недоступний, fallback визначає результат: +Якщо потрібне підтвердження, але жоден UI недосяжний, резервна поведінка вирішує: - **deny**: блокувати. -- **allowlist**: дозволяти лише за збігом allowlist. +- **allowlist**: дозволяти лише якщо є збіг зі списком дозволів. - **full**: дозволяти. -### Посилення для inline interpreter eval (`tools.exec.strictInlineEval`) +### Посилення для inline eval інтерпретатора (`tools.exec.strictInlineEval`) -Коли `tools.exec.strictInlineEval=true`, OpenClaw розглядає inline форми виконання коду як такі, що потребують лише підтвердження, навіть якщо сам бінарний файл інтерпретатора є в allowlist. +Коли `tools.exec.strictInlineEval=true`, OpenClaw розглядає inline-форми виконання коду лише як такі, що потребують підтвердження, навіть якщо сам бінарний файл інтерпретатора є в списку дозволів. Приклади: @@ -209,18 +209,18 @@ EOF - `lua -e` - `osascript -e` -Це захист у глибину для завантажувачів інтерпретаторів, які не можна чисто зіставити з одним стабільним файловим операндом. У строгому режимі: +Це defense-in-depth для завантажувачів інтерпретаторів, які не можна чисто відобразити на один стабільний файловий операнд. У strict mode: - ці команди все одно потребують явного підтвердження; -- `allow-always` не зберігає для них нові записи allowlist автоматично. +- `allow-always` не зберігає для них нові записи списку дозволів автоматично. -## Allowlist (для кожного агента) +## Список дозволів (для кожного агента) -Allowlist-и є **для кожного агента окремо**. Якщо агентів кілька, перемкніть агента, -якого редагуєте, у застосунку macOS. Патерни — це **glob-збіги без урахування регістру**. -Патерни мають вказувати на **шляхи до бінарних файлів** (записи лише з basename ігноруються). -Застарілі записи `agents.default` мігрують у `agents.main` під час завантаження. -Shell-ланцюжки на зразок `echo ok && pwd` усе одно вимагають, щоб кожен сегмент верхнього рівня задовольняв правила allowlist. +Списки дозволів є **окремими для кожного агента**. Якщо існує кілька агентів, перемкніть, якого агента ви +редагуєте, у застосунку macOS. Шаблони — це **нечутливі до регістру glob-збіги**. +Шаблони мають вказувати на **шляхи до бінарних файлів** (записи лише з basename ігноруються). +Застарілі записи `agents.default` мігрують до `agents.main` під час завантаження. +Shell-ланцюжки на кшталт `echo ok && pwd` усе одно вимагають, щоб кожен верхньорівневий сегмент відповідав правилам списку дозволів. Приклади: @@ -228,43 +228,43 @@ Shell-ланцюжки на зразок `echo ok && pwd` усе одно вим - `~/.local/bin/*` - `/opt/homebrew/bin/rg` -Кожен запис allowlist відстежує: +Кожен запис списку дозволів відстежує: -- **id** — стабільний UUID для ідентичності в UI (необов’язково) -- **last used** timestamp +- **id** стабільний UUID, який використовується для ідентичності в UI (необов’язково) +- **last used** мітка часу - **last used command** - **last resolved path** -## Автодозвіл CLI навичок +## Автодозвіл для CLI Skills -Коли увімкнено **Auto-allow skill CLIs**, виконувані файли, на які посилаються відомі Skills, -вважаються такими, що входять в allowlist на вузлах (macOS node або headless node host). Для цього використовується -`skills.bins` через Gateway RPC, щоб отримати список бінарних файлів навичок. Вимкніть це, якщо вам потрібні суворі ручні allowlist-и. +Коли **Auto-allow skill CLIs** увімкнено, виконувані файли, на які посилаються відомі Skills, +вважаються такими, що входять до списку дозволів на вузлах (macOS node або headless node host). Для цього +використовується `skills.bins` через Gateway RPC, щоб отримати список бінарних файлів skill. Вимкніть це, якщо вам потрібні суворі ручні списки дозволів. Важливі примітки щодо довіри: -- Це **неявний зручний allowlist**, окремий від ручних записів allowlist за шляхами. -- Він призначений для середовищ довірених операторів, де Gateway і вузол перебувають у межах однієї моделі довіри. -- Якщо вам потрібна сувора явна довіра, залиште `autoAllowSkills: false` і використовуйте лише ручні записи allowlist за шляхами. +- Це **неявний зручний список дозволів**, окремий від ручних записів списку дозволів для шляхів. +- Він призначений для середовищ із довіреними операторами, де Gateway і вузол перебувають в одній межі довіри. +- Якщо вам потрібна сувора явна довіра, залиште `autoAllowSkills: false` і використовуйте лише ручні записи списку дозволів для шляхів. ## Safe bins (лише stdin) -`tools.exec.safeBins` визначає невеликий список бінарних файлів **лише для stdin** (наприклад, `cut`), -які можуть виконуватися в режимі allowlist **без** явних записів allowlist. Safe bins відхиляють -позиційні файлові аргументи й токени, схожі на шляхи, тому можуть працювати лише з вхідним потоком. -Розглядайте це як вузький швидкий шлях для потокових фільтрів, а не як загальний список довіри. -**Не** додавайте бінарні файли інтерпретаторів або середовищ виконання (наприклад, `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`) до `safeBins`. -Якщо команда може виконувати код, запускати підкоманди або читати файли за своїм задумом, краще використовувати явні записи allowlist і залишити запити підтвердження увімкненими. +`tools.exec.safeBins` визначає невеликий список **бінарних файлів лише для stdin** (наприклад, `cut`), +які можуть запускатися в режимі списку дозволів **без** явних записів у списку дозволів. Safe bins відхиляють +позиційні файлові аргументи та токени, схожі на шляхи, тому можуть працювати лише з вхідним потоком. +Розглядайте це як вузький fast-path для потокових фільтрів, а не як загальний список довіри. +**Не** додавайте до `safeBins` бінарні файли інтерпретаторів або середовищ виконання (наприклад, `python3`, `node`, `ruby`, `bash`, `sh`, `zsh`). +Якщо команда за задумом може обчислювати код, виконувати підкоманди або читати файли, краще використовувати явні записи списку дозволів і залишати ввімкненими запити на підтвердження. Користувацькі safe bins мають визначати явний профіль у `tools.exec.safeBinProfiles.`. -Перевірка детерміновано ґрунтується лише на формі argv (без перевірок існування файлів у файловій системі хоста), що -запобігає поведінці oracle за існуванням файлів через різницю allow/deny. -Орієнтовані на файли опції відхиляються для типових safe bins (наприклад, `sort -o`, `sort --output`, +Перевірка є детермінованою лише за формою argv (без перевірок існування у файловій системі хоста), що +запобігає поведінці оракула існування файлів через різницю між allow/deny. +Файлоорієнтовані параметри відхиляються для типових safe bins (наприклад, `sort -o`, `sort --output`, `sort --files0-from`, `sort --compress-program`, `sort --random-source`, `sort --temporary-directory`/`-T`, `wc --files0-from`, `jq -f/--from-file`, `grep -f/--file`). -Safe bins також застосовують явну політику для прапорців кожного бінарного файла окремо для опцій, які порушують поведінку -лише зі stdin (наприклад, `sort -o/--output/--compress-program` і рекурсивні прапорці grep). -Довгі опції перевіряються fail-closed у режимі safe-bin: невідомі прапорці й неоднозначні +Safe bins також застосовують явну політику для прапорців кожного бінарного файла окремо щодо параметрів, які порушують поведінку +лише для stdin (наприклад, `sort -o/--output/--compress-program` і рекурсивні прапорці grep). +Довгі параметри перевіряються в режимі safe-bin fail-closed: невідомі прапорці й неоднозначні скорочення відхиляються. Відхилені прапорці за профілем safe-bin: @@ -278,31 +278,31 @@ Safe bins також застосовують явну політику для [//]: # "SAFE_BIN_DENIED_FLAGS:END" Safe bins також примусово обробляють токени argv як **буквальний текст** під час виконання (без globbing -і без розгортання `$VARS`) для сегментів лише зі stdin, тож шаблони на кшталт `*` або `$HOME/...` не можуть бути +і без розгортання `$VARS`) для сегментів лише зі stdin, тому шаблони на кшталт `*` або `$HOME/...` не можуть бути використані для прихованого читання файлів. -Safe bins також мають розв’язуватися лише з довірених каталогів бінарних файлів (типові системні каталоги плюс необов’язкові -`tools.exec.safeBinTrustedDirs`). Записи `PATH` ніколи не вважаються довіреними автоматично. +Safe bins також мають визначатися з довірених каталогів бінарних файлів (системні типові плюс необов’язкові +`tools.exec.safeBinTrustedDirs`). Записи `PATH` ніколи не вважаються автоматично довіреними. Типові довірені каталоги safe-bin навмисно мінімальні: `/bin`, `/usr/bin`. -Якщо ваш виконуваний файл safe-bin знаходиться у шляхах пакетного менеджера/користувача (наприклад +Якщо ваш виконуваний файл safe-bin знаходиться в шляхах пакетного менеджера/користувача (наприклад `/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), додайте їх явно до `tools.exec.safeBinTrustedDirs`. -Shell chaining і redirection не дозволяються автоматично в режимі allowlist. +Shell-ланцюжки та перенаправлення не дозволяються автоматично в режимі списку дозволів. -Shell chaining (`&&`, `||`, `;`) дозволено, коли кожен сегмент верхнього рівня задовольняє allowlist -(включно з safe bins або автодозволом навичок). Redirection залишається непідтримуваним у режимі allowlist. -Підстановка команд (`$()` / backticks) відхиляється під час розбору allowlist, зокрема й усередині +Shell-ланцюжки (`&&`, `||`, `;`) дозволяються, коли кожен верхньорівневий сегмент відповідає списку дозволів +(включно із safe bins або автодозволом для skill). Перенаправлення залишаються непідтримуваними в режимі списку дозволів. +Підстановка команд (`$()` / зворотні лапки) відхиляється під час розбору списку дозволів, зокрема всередині подвійних лапок; використовуйте одинарні лапки, якщо вам потрібен буквальний текст `$()`. -У підтвердженнях companion app macOS сирий shell-текст, що містить синтаксис керування shell або розгортання -(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), вважається промахом allowlist, якщо -сам бінарний файл shell не входить до allowlist. -Для shell-обгорток (`bash|sh|zsh ... -c/-lc`) перевизначення env на рівні запиту зводяться до -невеликого явного allowlist (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). -Для рішень allow-always у режимі allowlist відомі dispatch-обгортки -(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) зберігають внутрішні шляхи виконуваних файлів, а не шляхи -обгорток. Shell-мультиплексори (`busybox`, `toybox`) також розгортаються для shell-аплетів (`sh`, `ash`, -тощо), тож зберігаються внутрішні виконувані файли, а не бінарні файли мультиплексора. Якщо обгортку або -мультиплексор не можна безпечно розгорнути, жоден запис allowlist автоматично не зберігається. -Якщо ви додаєте інтерпретатори на кшталт `python3` або `node` в allowlist, краще встановити `tools.exec.strictInlineEval=true`, щоб inline eval усе одно потребував явного підтвердження. У строгому режимі `allow-always` усе ще може зберігати нешкідливі виклики інтерпретатора/скрипта, але носії inline-eval автоматично не зберігаються. +У підтвердженнях застосунку-компаньйона macOS сирий shell-текст, що містить синтаксис керування shell або розгортання +(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), розглядається як промах списку дозволів, якщо +сам бінарний файл shell не входить до списку дозволів. +Для shell-обгорток (`bash|sh|zsh ... -c/-lc`) перевизначення env у межах запиту зводяться до +невеликого явного списку дозволів (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). +Для рішень allow-always у режимі списку дозволів відомі dispatch-обгортки +(`env`, `nice`, `nohup`, `stdbuf`, `timeout`) зберігають внутрішні шляхи до виконуваних файлів, а не шляхи +до самих обгорток. Shell-мультиплексори (`busybox`, `toybox`) також розгортаються для shell-аплетів (`sh`, `ash`, +тощо), щоб зберігалися внутрішні виконувані файли, а не бінарні файли мультиплексора. Якщо обгортку або +мультиплексор неможливо безпечно розгорнути, запис списку дозволів не зберігається автоматично. +Якщо ви вносите до списку дозволів інтерпретатори на кшталт `python3` або `node`, віддавайте перевагу `tools.exec.strictInlineEval=true`, щоб inline eval усе одно вимагав явного підтвердження. У strict mode `allow-always` усе ще може зберігати нешкідливі виклики інтерпретатора/скрипта, але носії inline-eval автоматично не зберігаються. Типові safe bins: @@ -312,57 +312,57 @@ Shell chaining (`&&`, `||`, `;`) дозволено, коли кожен сег [//]: # "SAFE_BIN_DEFAULTS:END" -`grep` і `sort` не входять до типового списку. Якщо ви явно додаєте їх, залишайте явні записи allowlist для +`grep` і `sort` не входять до типового списку. Якщо ви явно вмикаєте їх, зберігайте явні записи списку дозволів для їхніх сценаріїв, не пов’язаних лише зі stdin. -Для `grep` у режимі safe-bin задавайте патерн через `-e`/`--regexp`; позиційна форма патерна -відхиляється, щоб файлові операнди не можна було приховати як неоднозначні позиційні аргументи. +Для `grep` у режимі safe-bin передавайте шаблон через `-e`/`--regexp`; позиційна форма шаблону +відхиляється, щоб файлові операнди не могли бути приховано передані як неоднозначні позиційні аргументи. -### Safe bins проти allowlist +### Safe bins проти списку дозволів -| Тема | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) | +| Тема | `tools.exec.safeBins` | Список дозволів (`exec-approvals.json`) | | ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ | -| Мета | Автодозвіл вузьких stdin-фільтрів | Явна довіра до конкретних виконуваних файлів | -| Тип збігу | Ім’я виконуваного файла + політика argv safe-bin | Glob-патерн шляху до розв’язаного виконуваного файла | -| Область аргументів | Обмежена профілем safe-bin і правилами буквальних токенів | Лише збіг шляху; за аргументи далі відповідаєте ви | +| Мета | Автоматично дозволяти вузькі stdin-фільтри | Явно довіряти конкретним виконуваним файлам | +| Тип збігу | Назва виконуваного файла + політика argv safe-bin | Glob-шаблон шляху до визначеного виконуваного файла | +| Обсяг аргументів | Обмежений профілем safe-bin і правилами буквальних токенів | Лише збіг шляху; за аргументи в іншому ви відповідаєте самі | | Типові приклади | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, користувацькі CLI | -| Найкраще використання | Низькоризикові текстові перетворення в конвеєрах | Будь-який інструмент із ширшою поведінкою або побічними ефектами | +| Найкраще використання | Текстові перетворення з низьким ризиком у конвеєрах | Будь-який інструмент із ширшою поведінкою або побічними ефектами | Розташування конфігурації: -- `safeBins` надходить із конфігурації (`tools.exec.safeBins` або для агента `agents.list[].tools.exec.safeBins`). -- `safeBinTrustedDirs` надходить із конфігурації (`tools.exec.safeBinTrustedDirs` або для агента `agents.list[].tools.exec.safeBinTrustedDirs`). -- `safeBinProfiles` надходить із конфігурації (`tools.exec.safeBinProfiles` або для агента `agents.list[].tools.exec.safeBinProfiles`). Ключі профілів для агента перевизначають глобальні ключі. -- записи allowlist зберігаються в локальному для хоста `~/.openclaw/exec-approvals.json` у `agents..allowlist` (або через Control UI / `openclaw approvals allowlist ...`). -- `openclaw security audit` попереджає через `tools.exec.safe_bins_interpreter_unprofiled`, коли бінарні файли інтерпретатора/середовища виконання з’являються в `safeBins` без явних профілів. -- `openclaw doctor --fix` може згенерувати відсутні записи `safeBinProfiles.` як `{}` (після цього перегляньте їх і зробіть суворішими). Для бінарних файлів інтерпретатора/середовища виконання автоматичне створення не виконується. +- `safeBins` надходить із конфігурації (`tools.exec.safeBins` або для окремого агента `agents.list[].tools.exec.safeBins`). +- `safeBinTrustedDirs` надходить із конфігурації (`tools.exec.safeBinTrustedDirs` або для окремого агента `agents.list[].tools.exec.safeBinTrustedDirs`). +- `safeBinProfiles` надходить із конфігурації (`tools.exec.safeBinProfiles` або для окремого агента `agents.list[].tools.exec.safeBinProfiles`). Ключі профілів окремого агента мають пріоритет над глобальними ключами. +- записи списку дозволів зберігаються в локальному для хоста `~/.openclaw/exec-approvals.json` у `agents..allowlist` (або через Control UI / `openclaw approvals allowlist ...`). +- `openclaw security audit` попереджає через `tools.exec.safe_bins_interpreter_unprofiled`, коли бінарні файли інтерпретаторів/середовищ виконання з’являються в `safeBins` без явних профілів. +- `openclaw doctor --fix` може створити відсутні записи `safeBinProfiles.` як `{}` (після цього перегляньте й посильте їх). Бінарні файли інтерпретаторів/середовищ виконання не створюються автоматично. Приклад користувацького профілю: __OC_I18N_900004__ Якщо ви явно додаєте `jq` до `safeBins`, OpenClaw усе одно відхиляє builtin `env` у режимі safe-bin, -щоб `jq -n env` не міг вивантажити env хост-процесу без явного шляху allowlist +тому `jq -n env` не може вивести env процесу хоста без явного шляху у списку дозволів або запиту на підтвердження. ## Редагування в Control UI Використовуйте картку **Control UI → Nodes → Exec approvals**, щоб редагувати типові значення, перевизначення -для кожного агента й allowlist-и. Виберіть область (Defaults або агент), змініть політику, -додайте/видаліть патерни allowlist, потім натисніть **Save**. UI показує метадані **last used** -для кожного патерна, щоб ви могли підтримувати список у порядку. +для окремих агентів і списки дозволів. Виберіть область дії (Defaults або агент), налаштуйте політику, +додайте/видаліть шаблони списку дозволів, а потім натисніть **Save**. UI показує метадані **last used** +для кожного шаблону, щоб вам було легше підтримувати порядок у списку. -Перемикач цілі вибирає **Gateway** (локальні підтвердження) або **Node**. Вузли -мають повідомляти про `system.execApprovals.get/set` (застосунок macOS або headless node host). -Якщо вузол ще не повідомляє про підтвердження exec, відредагуйте його локальний -`~/.openclaw/exec-approvals.json` напряму. +Селектор цілі вибирає **Gateway** (локальні підтвердження) або **Node**. Вузли +мають оголошувати `system.execApprovals.get/set` (застосунок macOS або headless node host). +Якщо вузол ще не оголошує exec approvals, відредагуйте його локальний +`~/.openclaw/exec-approvals.json` безпосередньо. -CLI: `openclaw approvals` підтримує редагування gateway або node (див. [CLI підтверджень](/cli/approvals)). +CLI: `openclaw approvals` підтримує редагування gateway або node (див. [Approvals CLI](/cli/approvals)). ## Потік підтвердження -Коли потрібен запит на підтвердження, gateway транслює `exec.approval.requested` клієнтам-операторам. +Коли потрібне підтвердження, gateway транслює `exec.approval.requested` клієнтам операторів. Control UI та застосунок macOS обробляють це через `exec.approval.resolve`, після чого gateway пересилає -схвалений запит до node host. +схвалений запит на хост вузла. -Для `host=node` запити на підтвердження містять канонічне корисне навантаження `systemRunPlan`. Gateway використовує +Для `host=node` запити на підтвердження містять канонічний payload `systemRunPlan`. Gateway використовує цей план як авторитетний контекст команди/cwd/сесії під час пересилання схвалених запитів `system.run`. Це важливо для затримки асинхронного підтвердження: @@ -370,57 +370,58 @@ Control UI та застосунок macOS обробляють це через - шлях exec вузла готує один канонічний план наперед - запис підтвердження зберігає цей план і його метадані прив’язки - після схвалення фінальний пересланий виклик `system.run` повторно використовує збережений план - замість того, щоб довіряти пізнішим змінам виклику -- якщо виклик змінює `command`, `rawCommand`, `cwd`, `agentId` або + замість довіри до пізніших змін викликача +- якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або `sessionKey` після створення запиту на підтвердження, gateway відхиляє - пересланий запуск через невідповідність підтвердженню + пересланий запуск як невідповідність підтвердженню ## Команди інтерпретатора/середовища виконання -Запуски інтерпретатора/середовища виконання, що спираються на підтвердження, навмисно консервативні: +Запуски інтерпретатора/середовища виконання з підтвердженням навмисно є консервативними: - Точний контекст argv/cwd/env завжди прив’язується. -- Форми прямого shell-скрипта та прямого runtime-файла прив’язуються до одного конкретного локального - знімка файла на основі best-effort. -- Поширені форми обгорток пакетних менеджерів, які все ще розв’язуються в один прямий локальний файл (наприклад +- Форми прямого shell-скрипта і прямого runtime-файла best-effort прив’язуються до одного конкретного snapshot локального + файла. +- Поширені форми обгорток пакетних менеджерів, які все ще зводяться до одного прямого локального файла (наприклад `pnpm exec`, `pnpm node`, `npm exec`, `npx`), розгортаються перед прив’язкою. - Якщо OpenClaw не може визначити рівно один конкретний локальний файл для команди інтерпретатора/середовища виконання - (наприклад, package scripts, eval-форми, ланцюжки завантажувачів, специфічні для runtime, або - неоднозначні форми з кількома файлами), виконання на основі підтвердження відхиляється замість того, щоб заявляти семантичне покриття, якого воно не має. -- Для таких сценаріїв краще використовувати sandbox, окрему межу host або явний - довірений робочий процес allowlist/full, де оператор приймає ширшу семантику runtime. + (наприклад package scripts, eval-форми, ланцюжки завантажувачів, специфічні для runtime, або неоднозначні форми + з кількома файлами), виконання з підтвердженням відхиляється замість заяв про семантичне покриття, якого + насправді немає. +- Для таких сценаріїв віддавайте перевагу sandboxing, окремій межі хоста або явному довіреному + workflow зі списком дозволів/full, де оператор приймає ширшу семантику runtime. -Коли потрібні підтвердження, інструмент exec одразу повертає id підтвердження. Використовуйте цей id для -співставлення з пізнішими системними подіями (`Exec finished` / `Exec denied`). Якщо рішення не надходить до -закінчення тайм-ауту, запит вважається тайм-аутом підтвердження і відображається як причина відхилення. +Коли потрібні підтвердження, інструмент exec негайно повертає id підтвердження. Використовуйте цей id, щоб +співвідносити подальші системні події (`Exec finished` / `Exec denied`). Якщо жодне рішення не надходить до +закінчення часу очікування, запит вважається тайм-аутом підтвердження й відображається як причина відмови. ### Поведінка доставки followup -Після завершення схваленого асинхронного exec OpenClaw надсилає followup-хід `agent` у ту саму сесію. +Після завершення схваленого асинхронного exec OpenClaw надсилає followup-turn `agent` у ту саму сесію. -- Якщо існує дійсна зовнішня ціль доставки (канал доставки плюс ціль `to`), followup доставляється через цей канал. -- У потоках лише webchat або внутрішніх сесіях без зовнішньої цілі followup залишається лише в сесії (`deliver: false`). -- Якщо виклик явно вимагає суворої зовнішньої доставки, але жоден зовнішній канал не можна розв’язати, запит завершується помилкою `INVALID_REQUEST`. -- Якщо ввімкнено `bestEffortDeliver` і жоден зовнішній канал не можна розв’язати, доставка знижується до режиму лише сесії замість помилки. +- Якщо існує дійсна зовнішня ціль доставки (канал, у який можна доставити, плюс ціль `to`), followup-доставка використовує цей канал. +- У потоках лише webchat або внутрішньосесійних потоках без зовнішньої цілі доставка followup залишається лише в межах сесії (`deliver: false`). +- Якщо викликач явно запитує сувору зовнішню доставку без зовнішнього каналу, який можна визначити, запит завершується помилкою `INVALID_REQUEST`. +- Якщо ввімкнено `bestEffortDeliver` і неможливо визначити зовнішній канал, доставку знижують до режиму лише в сесії замість помилки. Діалог підтвердження містить: - команду + аргументи - cwd - id агента -- розв’язаний шлях до виконуваного файла -- метадані host + policy +- визначений шлях до виконуваного файла +- хост + метадані політики Дії: -- **Allow once** → виконати зараз -- **Always allow** → додати до allowlist + виконати +- **Allow once** → запустити зараз +- **Always allow** → додати до списку дозволів + запустити - **Deny** → заблокувати -## Пересилання підтверджень у канали чату +## Пересилання підтверджень до чат-каналів -Ви можете пересилати запити підтвердження exec у будь-який канал чату (включно з каналами plugin) і підтверджувати -їх через `/approve`. Це використовує звичайний конвеєр вихідної доставки. +Ви можете пересилати запити на підтвердження exec до будь-якого чат-каналу (включно з каналами plugin) і підтверджувати +їх через `/approve`. Для цього використовується звичайний конвеєр вихідної доставки. Конфігурація: __OC_I18N_900005__ @@ -434,102 +435,100 @@ __OC_I18N_900006__ незалежну конфігурацію в `approvals.plugin`. Увімкнення або вимкнення одного не впливає на інше. __OC_I18N_900007__ Форма конфігурації ідентична `approvals.exec`: `enabled`, `mode`, `agentFilter`, -`sessionFilter` і `targets` працюють так само. +`sessionFilter` і `targets` працюють однаково. -Канали, які підтримують спільні інтерактивні відповіді, показують ті самі кнопки підтвердження як для exec, так і для -підтверджень plugin. Канали без спільного інтерактивного UI повертаються до звичайного тексту з інструкціями -`/approve`. +Канали, які підтримують спільні інтерактивні відповіді, відображають однакові кнопки підтвердження як для exec, так і для +підтверджень plugin. Канали без спільного інтерактивного UI повертаються до звичайного тексту з інструкціями `/approve`. ### Підтвердження в тому самому чаті на будь-якому каналі -Коли запит підтвердження exec або plugin походить із чату, який підтримує доставку, той самий чат -тепер може підтвердити його через `/approve` типово. Це стосується таких каналів, як Slack, Matrix і -Microsoft Teams, на додачу до наявних потоків через Web UI і terminal UI. +Коли запит на підтвердження exec або plugin походить із чат-поверхні, у яку можна доставити повідомлення, цей самий чат +тепер може типово підтвердити його через `/approve`. Це застосовується до таких каналів, як Slack, Matrix і +Microsoft Teams, на додачу до наявних потоків Web UI і terminal UI. -Цей спільний шлях через текстову команду використовує звичайну модель автентифікації каналу для цієї розмови. Якщо -початковий чат уже може надсилати команди й отримувати відповіді, запитам підтвердження більше не потрібен -окремий нативний адаптер доставки лише для того, щоб залишатися в очікуванні. +Цей спільний шлях текстової команди використовує звичайну модель автентифікації каналу для цієї розмови. Якщо чат- +джерело вже може надсилати команди й отримувати відповіді, запитам на підтвердження більше не потрібен +окремий власний адаптер доставки лише для того, щоб залишатися в очікуванні. -Discord і Telegram також підтримують `/approve` у тому самому чаті, але ці канали все одно використовують -свій розв’язаний список схвалювачів для авторизації, навіть коли нативну доставку підтверджень вимкнено. +Discord і Telegram також підтримують `/approve` у тому самому чаті, але ці канали все одно використовують свій +визначений список схвалювачів для авторизації, навіть коли власну доставку підтверджень вимкнено. -Для Telegram та інших нативних клієнтів підтвердження, які викликають Gateway напряму, -цей fallback навмисно обмежений помилками типу "approval not found". Реальне -відхилення/помилка підтвердження exec не повторюється мовчки як підтвердження plugin. +Для Telegram та інших власних клієнтів підтвердження, які напряму викликають Gateway, +цей fallback навмисно обмежений помилками типу "підтвердження не знайдено". Реальна +відмова/помилка підтвердження exec не повторюється мовчки як підтвердження plugin. -### Нативна доставка підтверджень +### Власна доставка підтверджень -Деякі канали також можуть працювати як нативні клієнти підтвердження. Нативні клієнти додають DM схвалювачам, fanout до початкового чату -та прив’язаний до каналу інтерактивний UX підтвердження поверх спільного потоку `/approve` -в тому самому чаті. +Деякі канали також можуть діяти як власні клієнти підтвердження. Власні клієнти додають DM для схвалювачів, fanout у чат- +джерело та специфічний для каналу інтерактивний UX підтвердження поверх спільного потоку `/approve` у тому самому чаті. -Коли доступні нативні картки/кнопки підтвердження, цей нативний UI є основним -шляхом для агента. Агент не повинен також дублювати звичайну команду чату -`/approve`, якщо тільки результат інструмента не вказує, що підтвердження через чат недоступні або -ручне підтвердження — єдиний шлях, що залишився. +Коли доступні власні картки/кнопки підтвердження, цей власний UI є основним +шляхом для агента. Агент не повинен також дублювати звичайну чат-команду +`/approve`, якщо тільки результат інструмента не каже, що чат-підтвердження недоступні або +ручне підтвердження — це єдиний шлях, що залишився. Загальна модель: -- політика host exec усе ще визначає, чи потрібне підтвердження exec -- `approvals.exec` керує пересиланням запитів на підтвердження до інших цілей чату -- `channels..execApprovals` визначає, чи діє цей канал як нативний клієнт підтвердження +- політика host exec, як і раніше, визначає, чи потрібне підтвердження exec +- `approvals.exec` керує пересиланням запитів на підтвердження до інших чат-призначень +- `channels..execApprovals` керує тим, чи діє цей канал як власний клієнт підтвердження -Нативні клієнти підтвердження автоматично вмикають доставку спочатку в DM, коли всі ці умови істинні: +Власні клієнти підтвердження автоматично вмикають доставку спочатку в DM, коли всі ці умови істинні: -- канал підтримує нативну доставку підтверджень -- схвалювачів можна розв’язати з явних `execApprovals.approvers` або з - документованих для цього каналу fallback-джерел -- `channels..execApprovals.enabled` не задано або дорівнює `"auto"` +- канал підтримує власну доставку підтверджень +- схвалювачів можна визначити з явних `execApprovals.approvers` або з + документованих fallback-джерел цього каналу +- `channels..execApprovals.enabled` не задано або має значення `"auto"` -Встановіть `enabled: false`, щоб явно вимкнути нативний клієнт підтвердження. Встановіть `enabled: true`, щоб примусово -увімкнути його, коли схвалювачі розв’язуються. Доставка в публічний початковий чат залишається явною через +Установіть `enabled: false`, щоб явно вимкнути власний клієнт підтвердження. Установіть `enabled: true`, щоб примусово +ввімкнути його, коли схвалювачів визначено. Публічна доставка в чат-джерело, як і раніше, вмикається явно через `channels..execApprovals.target`. -FAQ: [Чому існують дві конфігурації підтвердження exec для підтверджень у чаті?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) +FAQ: [Чому існують дві конфігурації підтверджень exec для чат-підтверджень?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) - Discord: `channels.discord.execApprovals.*` - Slack: `channels.slack.execApprovals.*` - Telegram: `channels.telegram.execApprovals.*` -Ці нативні клієнти підтвердження додають маршрутизацію до DM і необов’язковий fanout по каналу поверх спільного -потоку `/approve` в тому самому чаті та спільних кнопок підтвердження. +Ці власні клієнти підтвердження додають маршрутизацію в DM і необов’язковий fanout у канал поверх спільного +потоку `/approve` у тому самому чаті та спільних кнопок підтвердження. Спільна поведінка: - Slack, Matrix, Microsoft Teams та подібні чати з доставкою використовують звичайну модель автентифікації каналу для `/approve` у тому самому чаті -- коли нативний клієнт підтвердження вмикається автоматично, типовою нативною ціллю доставки є DM схвалювачів -- для Discord і Telegram лише розв’язані схвалювачі можуть підтвердити або відхилити -- схвалювачі Discord можуть бути явними (`execApprovals.approvers`) або виведеними з `commands.ownerAllowFrom` -- схвалювачі Telegram можуть бути явними (`execApprovals.approvers`) або виведеними з наявної конфігурації owner (`allowFrom`, плюс `defaultTo` для direct message, де це підтримується) -- схвалювачі Slack можуть бути явними (`execApprovals.approvers`) або виведеними з `commands.ownerAllowFrom` -- нативні кнопки Slack зберігають вид ID підтвердження, тож ID `plugin:` можуть розв’язувати підтвердження plugin +- коли власний клієнт підтвердження вмикається автоматично, типовою власною ціллю доставки є DM схвалювачів +- для Discord і Telegram лише визначені схвалювачі можуть схвалювати або відхиляти +- схвалювачі Discord можуть бути явними (`execApprovals.approvers`) або виводитися з `commands.ownerAllowFrom` +- схвалювачі Telegram можуть бути явними (`execApprovals.approvers`) або виводитися з наявної конфігурації owner (`allowFrom`, плюс `defaultTo` для direct-message, де це підтримується) +- схвалювачі Slack можуть бути явними (`execApprovals.approvers`) або виводитися з `commands.ownerAllowFrom` +- власні кнопки Slack зберігають тип id підтвердження, тому id `plugin:` можуть визначати підтвердження plugin без другого локального fallback-рівня Slack -- нативна маршрутизація Matrix до DM/каналу стосується лише exec; підтвердження plugin у Matrix залишаються на спільному - шляху `/approve` у тому самому чаті та необов’язковому пересиланні через `approvals.plugin` -- відправник запиту не обов’язково має бути схвалювачем -- початковий чат може підтвердити напряму через `/approve`, коли цей чат уже підтримує команди й відповіді -- нативні кнопки підтвердження Discord маршрутизуються за видом ID підтвердження: ID `plugin:` переходять +- власна маршрутизація Matrix у DM/канал і shortcut-реакції обробляють як підтвердження exec, так і plugin; + авторизація plugin, як і раніше, походить із `channels.matrix.dm.allowFrom` +- запитувач не обов’язково має бути схвалювачем +- чат-джерело може схвалити напряму через `/approve`, коли цей чат уже підтримує команди та відповіді +- власні кнопки підтвердження Discord маршрутизують за типом id підтвердження: id `plugin:` переходять безпосередньо до підтверджень plugin, усе інше — до підтверджень exec -- нативні кнопки підтвердження Telegram дотримуються того самого обмеженого fallback exec-to-plugin, що й `/approve` -- коли нативний `target` вмикає доставку до початкового чату, запити на підтвердження містять текст команди +- власні кнопки підтвердження Telegram дотримуються того самого обмеженого fallback exec-to-plugin, що й `/approve` +- коли власний `target` вмикає доставку в чат-джерело, запити на підтвердження містять текст команди - очікувані підтвердження exec типово спливають через 30 хвилин - якщо жоден UI оператора або налаштований клієнт підтвердження не може прийняти запит, запит переходить до `askFallback` -Типово Telegram використовує DM схвалювачів (`target: "dm"`). Ви можете переключити на `channel` або `both`, коли +Telegram типово використовує DM схвалювачів (`target: "dm"`). Ви можете перемкнути на `channel` або `both`, якщо хочете, щоб запити на підтвердження також з’являлися в початковому чаті/темі Telegram. Для тем форуму Telegram -OpenClaw зберігає тему для запиту підтвердження та followup після підтвердження. +OpenClaw зберігає тему для запиту на підтвердження й follow-up після підтвердження. -Див.: +Дивіться: - [Discord](/channels/discord) - [Telegram](/channels/telegram) -### Потік IPC на macOS +### Потік IPC у macOS __OC_I18N_900008__ Примітки щодо безпеки: -- Режим Unix socket `0600`, токен зберігається в `exec-approvals.json`. +- Режим Unix-сокета `0600`, токен зберігається в `exec-approvals.json`. - Перевірка peer з тим самим UID. - Challenge/response (nonce + HMAC token + hash запиту) + короткий TTL. @@ -541,36 +540,36 @@ __OC_I18N_900008__ - `Exec finished` - `Exec denied` -Вони публікуються в сесію агента після того, як вузол повідомляє про подію. -Підтвердження exec на gateway host генерують ті самі події життєвого циклу, коли команда завершується (і, за потреби, коли виконується довше за поріг). +Вони публікуються в сесії агента після того, як вузол повідомляє про подію. +Підтвердження exec на gateway host надсилають ті самі події життєвого циклу, коли команда завершується (і, за потреби, коли виконується довше за поріг). Exec із підтвердженням повторно використовують id підтвердження як `runId` у цих повідомленнях для зручної кореляції. ## Поведінка при відхиленому підтвердженні -Коли асинхронне підтвердження exec відхиляється, OpenClaw не дозволяє агенту повторно використовувати +Коли асинхронне підтвердження exec відхиляється, OpenClaw забороняє агенту повторно використовувати вивід будь-якого попереднього запуску тієї самої команди в сесії. Причина відхилення -передається з явною вказівкою, що вивід команди недоступний, що не дає -агенту стверджувати, ніби є новий вивід, або повторювати відхилену команду зі -старими результатами від попереднього успішного запуску. +передається разом із явною вказівкою, що жодного виводу команди немає, що заважає +агенту стверджувати, що є новий вивід, або повторювати відхилену команду зі +застарілими результатами попереднього успішного запуску. ## Наслідки -- **full** має великі повноваження; за можливості віддавайте перевагу allowlist-ам. -- **ask** тримає вас у циклі, водночас даючи змогу швидко підтверджувати. -- Allowlist-и для кожного агента окремо не дають підтвердженням одного агента просочуватися в інших. +- **full** — це потужний режим; за можливості віддавайте перевагу спискам дозволів. +- **ask** залишає вас у циклі, водночас даючи можливість швидко підтверджувати. +- Списки дозволів для окремих агентів не дають підтвердженням одного агента просочуватися до інших. - Підтвердження застосовуються лише до запитів host exec від **авторизованих відправників**. Неавторизовані відправники не можуть виконувати `/exec`. -- `/exec security=full` — це зручність на рівні сесії для авторизованих операторів, яка за задумом пропускає підтвердження. - Щоб жорстко заборонити host exec, встановіть `security` підтверджень у `deny` або забороніть інструмент `exec` через політику інструментів. +- `/exec security=full` — це зручність на рівні сесії для авторизованих операторів і за задумом пропускає підтвердження. + Щоб жорстко заборонити host exec, установіть безпеку підтверджень у `deny` або забороніть інструмент `exec` через політику інструментів. Пов’язане: -- [Інструмент Exec](/tools/exec) -- [Режим Elevated](/tools/elevated) -- [Skills](/tools/skills) +- [Exec tool](/uk/tools/exec) +- [Elevated mode](/uk/tools/elevated) +- [Skills](/uk/tools/skills) ## Пов’язане -- [Exec](/tools/exec) — інструмент виконання shell-команд -- [Sandboxing](/uk/gateway/sandboxing) — режими sandbox і доступ до робочого простору +- [Exec](/uk/tools/exec) — інструмент виконання shell-команд +- [Sandboxing](/uk/gateway/sandboxing) — режими sandbox і доступ до workspace - [Security](/uk/gateway/security) — модель безпеки та посилення -- [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) — коли що використовувати +- [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated) — коли використовувати кожен варіант