diff --git a/docs/uk/channels/matrix.md b/docs/uk/channels/matrix.md index 3ec5d1dd6..8507aae0f 100644 --- a/docs/uk/channels/matrix.md +++ b/docs/uk/channels/matrix.md @@ -1,14 +1,14 @@ --- read_when: - Налаштування Matrix в OpenClaw - - Налаштування Matrix E2EE та верифікації -summary: Стан підтримки Matrix, налаштування та приклади конфігурації + - Налаштування Matrix E2EE і верифікації +summary: Стан підтримки Matrix, приклади налаштування та конфігурації title: Matrix x-i18n: - generated_at: "2026-04-05T19:19:36Z" + generated_at: "2026-04-05T22:39:31Z" model: gpt-5.4 provider: openai - source_hash: 3a1413c8c6fb6991a6bbb54ef7893ce01350ccf9d18405127981ac7369c52ab5 + source_hash: ddd4f14094388b1a4cd542a5956fcf47f7d6734b7a11fde1d6125b3f0d7202c9 source_path: channels/matrix.md workflow: 15 --- @@ -16,23 +16,23 @@ x-i18n: # Matrix Matrix — це вбудований плагін каналу Matrix для OpenClaw. -Він використовує офіційний `matrix-js-sdk` і підтримує DM, кімнати, треди, медіа, реакції, опитування, геолокацію та E2EE. +Він використовує офіційний `matrix-js-sdk` і підтримує особисті повідомлення, кімнати, треди, медіа, реакції, опитування, геолокацію та E2EE. ## Вбудований плагін -Matrix постачається як вбудований плагін у поточних релізах OpenClaw, тому звичайним -зібраним пакетам не потрібне окреме встановлення. +Matrix постачається як вбудований плагін у поточних релізах OpenClaw, тож звичайним +зібраним версіям не потрібне окреме встановлення. -Якщо ви використовуєте старішу збірку або власне встановлення без Matrix, установіть +Якщо ви використовуєте старішу збірку або кастомне встановлення без Matrix, встановіть його вручну: -Установлення з npm: +Встановлення з npm: ```bash openclaw plugins install @openclaw/matrix ``` -Установлення з локального checkout: +Встановлення з локального checkout: ```bash openclaw plugins install ./path/to/local/matrix-plugin @@ -43,16 +43,16 @@ openclaw plugins install ./path/to/local/matrix-plugin ## Налаштування 1. Переконайтеся, що плагін Matrix доступний. - - У поточних пакетних релізах OpenClaw він уже вбудований. - - У старіших/кастомних встановленнях його можна додати вручну наведеними вище командами. + - Поточні зібрані релізи OpenClaw уже містять його. + - У старіших/кастомних встановленнях його можна додати вручну командами вище. 2. Створіть обліковий запис Matrix на своєму homeserver. -3. Налаштуйте `channels.matrix`, використовуючи один із варіантів: +3. Налаштуйте `channels.matrix` одним із варіантів: - `homeserver` + `accessToken`, або - `homeserver` + `userId` + `password`. 4. Перезапустіть gateway. -5. Почніть DM із ботом або запросіть його до кімнати. +5. Почніть DM з ботом або запросіть його до кімнати. -Шляхи інтерактивного налаштування: +Інтерактивні шляхи налаштування: ```bash openclaw channels add @@ -63,19 +63,19 @@ openclaw configure --section channels - URL homeserver - метод автентифікації: токен доступу або пароль -- user ID лише якщо ви вибрали автентифікацію паролем +- ID користувача лише якщо ви обираєте автентифікацію паролем - необов’язкова назва пристрою - чи вмикати E2EE - чи налаштувати доступ до кімнат Matrix зараз Важлива поведінка майстра: -- Якщо для вибраного облікового запису вже існують змінні середовища автентифікації Matrix, і цей обліковий запис ще не має збереженої автентифікації в конфігурації, майстер запропонує скорочений варіант через env і запише для цього облікового запису лише `enabled: true`. -- Коли ви інтерактивно додаєте ще один обліковий запис Matrix, введена назва облікового запису нормалізується до ID облікового запису, що використовується в конфігурації та env vars. Наприклад, `Ops Bot` стає `ops-bot`. -- Підказки allowlist для DM одразу приймають повні значення `@user:server`. Відображувані імена працюють лише тоді, коли живий пошук у директорії знаходить один точний збіг; інакше майстер попросить повторити спробу з повним Matrix ID. -- Підказки allowlist для кімнат напряму приймають ID кімнат і аліаси. Вони також можуть у реальному часі розпізнавати назви приєднаних кімнат, але нерозпізнані назви під час налаштування зберігаються лише як введені та пізніше ігноруються під час виконання allowlist. Надавайте перевагу `!room:server` або `#alias:server`. -- Ідентичність кімнати/сесії під час виконання використовує стабільний Matrix room ID. Аліаси, оголошені кімнатою, використовуються лише як вхідні дані для пошуку, а не як довгостроковий ключ сесії чи стабільна ідентичність групи. -- Щоб розпізнати назви кімнат перед збереженням, використовуйте `openclaw channels resolve --channel matrix "Project Room"`. +- Якщо для вибраного облікового запису вже існують змінні середовища автентифікації Matrix, і для цього облікового запису ще не збережено автентифікацію в конфігурації, майстер пропонує скористатися env і записує для цього облікового запису лише `enabled: true`. +- Коли ви інтерактивно додаєте ще один обліковий запис Matrix, введена назва облікового запису нормалізується до ID облікового запису, який використовується в конфігурації та змінних середовища. Наприклад, `Ops Bot` стає `ops-bot`. +- Підказки allowlist для DM одразу приймають повні значення `@user:server`. Відображувані імена працюють лише тоді, коли живий пошук у каталозі знаходить один точний збіг; інакше майстер просить повторити спробу з повним Matrix ID. +- Підказки allowlist для кімнат безпосередньо приймають ID кімнат і псевдоніми. Вони також можуть у реальному часі визначати назви приєднаних кімнат, але нерозпізнані назви під час налаштування зберігаються лише як введені й надалі ігноруються під час runtime-розв’язання allowlist. Надавайте перевагу `!room:server` або `#alias:server`. +- Ідентичність кімнати/сесії під час runtime використовує стабільний Matrix room ID. Псевдоніми, оголошені кімнатою, використовуються лише як вхідні дані для пошуку, а не як довгостроковий ключ сесії чи стабільна ідентичність групи. +- Щоб визначити назви кімнат перед збереженням, використовуйте `openclaw channels resolve --channel matrix "Project Room"`. Мінімальне налаштування на основі токена: @@ -92,7 +92,7 @@ openclaw configure --section channels } ``` -Налаштування на основі пароля (токен кешується після входу): +Налаштування на основі пароля (після входу токен кешується): ```json5 { @@ -139,10 +139,10 @@ 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 vars лише тоді, коли ці змінні середовища автентифікації вже присутні, а для вибраного облікового запису ще не збережено автентифікацію Matrix у конфігурації. +Інтерактивний майстер пропонує скористатися змінними середовища лише тоді, коли ці env-змінні автентифікації вже присутні, а для вибраного облікового запису ще не збережено автентифікацію Matrix у конфігурації. ## Приклад конфігурації @@ -181,13 +181,13 @@ Matrix екранує розділові знаки в ID облікових з } ``` -## Попередній перегляд потокової відповіді +## Попередній перегляд під час streaming -Потокові відповіді Matrix вмикаються за бажанням. +Streaming відповідей у Matrix є опціональним. -Установіть `channels.matrix.streaming` у `"partial"`, якщо хочете, щоб OpenClaw надсилав одну чернетку відповіді, -редагував цю чернетку на місці під час генерування тексту моделлю, а потім завершував її, коли відповідь -буде готова: +Установіть `channels.matrix.streaming` у `"partial"`, якщо хочете, щоб OpenClaw надсилав один живий попередній +варіант відповіді, редагував його на місці під час генерації тексту моделлю, а потім завершував, коли +відповідь буде готова: ```json5 { @@ -199,24 +199,173 @@ Matrix екранує розділові знаки в ID облікових з } ``` -- `streaming: "off"` — це значення за замовчуванням. OpenClaw чекає на фінальну відповідь і надсилає її один раз. -- `streaming: "partial"` створює одне редаговане повідомлення попереднього перегляду для поточного блоку відповіді помічника замість надсилання кількох часткових повідомлень. -- `blockStreaming: true` вмикає окремі повідомлення прогресу Matrix. Якщо `streaming: "partial"`, Matrix зберігає живу чернетку для поточного блоку та залишає завершені блоки окремими повідомленнями. -- Коли `streaming: "partial"` і `blockStreaming` вимкнено, Matrix лише редагує живу чернетку й надсилає завершену відповідь, коли цей блок або хід завершується. -- Якщо попередній перегляд більше не вміщується в одну подію Matrix, OpenClaw припиняє потоковий попередній перегляд і повертається до звичайного фінального доставлення. -- Відповіді з медіа, як і раніше, надсилають вкладення звичайним способом. Якщо застарілий попередній перегляд більше не можна безпечно використати повторно, OpenClaw виконує його redaction перед надсиланням фінальної медіавідповіді. -- Редагування попереднього перегляду створює додаткові виклики Matrix API. Залишайте streaming вимкненим, якщо хочете найобережнішу поведінку щодо обмежень частоти. +- `streaming: "off"` — значення за замовчуванням. OpenClaw чекає фінальну відповідь і надсилає її один раз. +- `streaming: "partial"` створює одне редаговане повідомлення-попередній перегляд для поточного блоку асистента, використовуючи звичайні текстові повідомлення Matrix. Це зберігає стару поведінку Matrix із попереднім сповіщенням за першим preview, тому стандартні клієнти можуть надсилати сповіщення за першим текстом попереднього перегляду, а не за завершеним блоком. +- `streaming: "quiet"` створює одне редаговане тихе повідомлення-попередній перегляд для поточного блоку асистента. Використовуйте це лише тоді, коли ви також налаштували push rules отримувача для фіналізованих редагувань preview. +- `blockStreaming: true` вмикає окремі повідомлення про прогрес Matrix. Якщо preview streaming увімкнено, Matrix зберігає живу чернетку для поточного блоку та залишає завершені блоки як окремі повідомлення. +- Коли preview streaming увімкнено, а `blockStreaming` вимкнено, Matrix редагує живу чернетку на місці та фіналізує ту саму подію, коли блок або хід завершується. +- Якщо preview більше не вміщується в одну подію Matrix, OpenClaw зупиняє preview streaming і повертається до звичайної фінальної доставки. +- Відповіді з медіа, як і раніше, надсилають вкладення звичайним способом. Якщо застарілий preview більше не можна безпечно перевикористати, OpenClaw редагує його перед надсиланням фінальної медіавідповіді. +- Редагування preview потребують додаткових викликів Matrix API. Залишайте streaming вимкненим, якщо вам потрібна максимально консервативна поведінка щодо rate limit. -`blockStreaming` сам по собі не вмикає чернетки попереднього перегляду. -Використовуйте `streaming: "partial"` для редагування попереднього перегляду; потім додайте `blockStreaming: true`, лише якщо також хочете, щоб завершені блоки помічника залишалися видимими як окремі повідомлення прогресу. +`blockStreaming` сам по собі не вмикає preview чернеток. +Використовуйте `streaming: "partial"` або `streaming: "quiet"` для редагувань preview; потім додавайте `blockStreaming: true`, лише якщо також хочете, щоб завершені блоки асистента залишалися видимими як окремі повідомлення про прогрес. + +Якщо вам потрібні стандартні сповіщення Matrix без кастомних push rules, використовуйте `streaming: "partial"` для поведінки з попереднім preview або залиште `streaming` вимкненим для доставки лише фінальної відповіді. Для `streaming: "off"`: + +- `blockStreaming: true` надсилає кожен завершений блок як звичайне повідомлення Matrix зі сповіщенням. +- `blockStreaming: false` надсилає лише фінальну завершену відповідь як звичайне повідомлення Matrix зі сповіщенням. + +### Self-hosted push rules для тихих фіналізованих preview + +Якщо ви запускаєте власну інфраструктуру Matrix і хочете, щоб тихі preview надсилали сповіщення лише тоді, коли блок або +фінальна відповідь завершені, установіть `streaming: "quiet"` і додайте push rule для кожного користувача для фіналізованих редагувань preview. + +Зазвичай це налаштування на рівні користувача-отримувача, а не глобальна зміна конфігурації homeserver: + +Швидка схема перед початком: + +- recipient user = людина, яка має отримати сповіщення +- bot user = обліковий запис OpenClaw Matrix, що надсилає відповідь +- для наведених нижче викликів API використовуйте токен доступу користувача-отримувача +- у push rule звіряйте `sender` з повним MXID користувача-бота + +1. Налаштуйте OpenClaw на використання тихих preview: + +```json5 +{ + channels: { + matrix: { + streaming: "quiet", + }, + }, +} +``` + +2. Переконайтеся, що обліковий запис отримувача вже отримує звичайні push-сповіщення Matrix. Правила тихих preview + працюють лише тоді, коли в цього користувача вже є робочі pusher-и/пристрої. + +3. Отримайте токен доступу користувача-отримувача. + - Використовуйте токен користувача, який отримує повідомлення, а не токен бота. + - Зазвичай найпростіше повторно використати токен існуючої сесії клієнта. + - Якщо потрібно випустити новий токен, можна увійти через стандартний Matrix Client-Server API: + +```bash +curl -sS -X POST \ + "https://matrix.example.org/_matrix/client/v3/login" \ + -H "Content-Type: application/json" \ + --data '{ + "type": "m.login.password", + "identifier": { + "type": "m.id.user", + "user": "@alice:example.org" + }, + "password": "REDACTED" + }' +``` + +4. Перевірте, що обліковий запис отримувача вже має pusher-и: + +```bash +curl -sS \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + "https://matrix.example.org/_matrix/client/v3/pushers" +``` + +Якщо це не повертає активних pusher-ів/пристроїв, спочатку виправте звичайні сповіщення Matrix, а вже потім додавайте +наведене нижче правило OpenClaw. + +OpenClaw позначає фіналізовані редагування preview лише з текстом так: + +```json +{ + "com.openclaw.finalized_preview": true +} +``` + +5. Створіть override push rule для кожного облікового запису отримувача, який має отримувати ці сповіщення: + +```bash +curl -sS -X PUT \ + "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview" \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + --data '{ + "conditions": [ + { "kind": "event_match", "key": "type", "pattern": "m.room.message" }, + { + "kind": "event_property_is", + "key": "content.m\\.relates_to.rel_type", + "value": "m.replace" + }, + { + "kind": "event_property_is", + "key": "content.com\\.openclaw\\.finalized_preview", + "value": true + }, + { "kind": "event_match", "key": "sender", "pattern": "@bot:example.org" } + ], + "actions": [ + "notify", + { "set_tweak": "sound", "value": "default" }, + { "set_tweak": "highlight", "value": false } + ] + }' +``` + +Замініть ці значення перед запуском команди: + +- `https://matrix.example.org`: базовий URL вашого homeserver +- `$USER_ACCESS_TOKEN`: токен доступу користувача-отримувача +- `@bot:example.org`: MXID вашого бота OpenClaw Matrix, а не MXID користувача-отримувача + +Правило оцінюється відносно відправника події: + +- автентифікуйтеся токеном користувача-отримувача +- звіряйте `sender` з MXID бота OpenClaw + +6. Перевірте, що правило існує: + +```bash +curl -sS \ + -H "Authorization: Bearer $USER_ACCESS_TOKEN" \ + "https://matrix.example.org/_matrix/client/v3/pushrules/global/override/openclaw-finalized-preview" +``` + +7. Перевірте відповідь зі streaming. У тихому режимі кімната має показувати тихий preview чернетки, а фінальне + редагування на місці має надіслати одне сповіщення, коли блок або хід завершиться. + +Примітки: + +- Створюйте правило з токеном доступу користувача-отримувача, а не бота. +- Нові визначені користувачем правила `override` вставляються перед правилами придушення за замовчуванням, тож додатковий параметр порядку не потрібен. +- Це впливає лише на редагування preview лише з текстом, які OpenClaw може безпечно фіналізувати на місці. Fallback-и для медіа та fallback-и для застарілих preview, як і раніше, використовують звичайну доставку Matrix. +- Якщо `GET /_matrix/client/v3/pushers` не показує жодного pusher, значить для цього облікового запису/пристрою в користувача ще не працює доставка push-сповіщень Matrix. + +#### Synapse + +Для Synapse описаного вище налаштування зазвичай достатньо саме по собі: + +- Для фіналізованих сповіщень preview OpenClaw не потрібні спеціальні зміни `homeserver.yaml`. +- Якщо ваше розгортання Synapse уже надсилає звичайні push-сповіщення Matrix, головний крок налаштування — токен користувача + виклик `pushrules` вище. +- Якщо ви запускаєте Synapse за reverse proxy або workers, переконайтеся, що `/_matrix/client/.../pushrules/` коректно доходить до Synapse. +- Якщо ви використовуєте workers Synapse, переконайтеся, що pusher-и справні. Доставка push-сповіщень обробляється головним процесом або `synapse.app.pusher` / налаштованими pusher worker-ами. + +#### Tuwunel + +Для Tuwunel використовуйте той самий сценарій налаштування й виклик API `pushrules`, показаний вище: + +- Специфічна конфігурація Tuwunel для самого маркера фіналізованого preview не потрібна. +- Якщо звичайні сповіщення Matrix уже працюють для цього користувача, головний крок налаштування — токен користувача + виклик `pushrules` вище. +- Якщо сповіщення, схоже, зникають, коли користувач активний на іншому пристрої, перевірте, чи ввімкнено `suppress_push_when_active`. Tuwunel додав цю опцію у Tuwunel 1.4.2 12 вересня 2025 року, і вона може навмисно приглушувати push-сповіщення на інших пристроях, поки один пристрій активний. ## Шифрування та верифікація -У зашифрованих (E2EE) кімнатах вихідні події зображень використовують `thumbnail_file`, тож попередні перегляди зображень шифруються разом із повним вкладенням. Незашифровані кімнати, як і раніше, використовують звичайний `thumbnail_url`. Жодна конфігурація не потрібна — плагін автоматично визначає стан E2EE. +В зашифрованих (E2EE) кімнатах вихідні події зображень використовують `thumbnail_file`, тож preview зображень шифруються разом із повним вкладенням. У незашифрованих кімнатах і далі використовується звичайний `thumbnail_url`. Налаштування не потрібні — плагін автоматично визначає стан E2EE. -### Кімнати bot-to-bot +### Кімнати бот-бот -За замовчуванням повідомлення Matrix від інших налаштованих облікових записів Matrix OpenClaw ігноруються. +За замовчуванням повідомлення Matrix від інших налаштованих облікових записів OpenClaw Matrix ігноруються. Використовуйте `allowBots`, якщо ви навмисно хочете дозволити міжагентний трафік Matrix: @@ -235,13 +384,13 @@ Matrix екранує розділові знаки в ID облікових з } ``` -- `allowBots: true` приймає повідомлення від інших налаштованих облікових записів ботів Matrix у дозволених кімнатах і DM. +- `allowBots: true` приймає повідомлення від інших налаштованих облікових записів Matrix bot у дозволених кімнатах і DM. - `allowBots: "mentions"` приймає ці повідомлення лише тоді, коли вони явно згадують цього бота в кімнатах. DM усе одно дозволені. -- `groups..allowBots` перевизначає налаштування рівня облікового запису для однієї кімнати. -- OpenClaw все одно ігнорує повідомлення від того самого Matrix user ID, щоб уникнути циклів самовідповіді. -- Matrix тут не надає нативного прапорця бота; OpenClaw трактує “bot-authored” як “надіслане іншим налаштованим обліковим записом Matrix на цьому gateway OpenClaw”. +- `groups..allowBots` перевизначає налаштування на рівні облікового запису для однієї кімнати. +- OpenClaw і далі ігнорує повідомлення від того самого Matrix user ID, щоб уникати циклів самовідповіді. +- Matrix тут не надає вбудованого прапорця bot; OpenClaw трактує "створене ботом" як "надіслане іншим налаштованим обліковим записом Matrix на цьому OpenClaw gateway". -Використовуйте суворі allowlist кімнат і вимоги щодо згадок, коли вмикаєте трафік bot-to-bot у спільних кімнатах. +Використовуйте строгі allowlist кімнат і вимоги до згадок, коли вмикаєте трафік bot-to-bot у спільних кімнатах. Увімкнення шифрування: @@ -271,19 +420,19 @@ openclaw matrix verify status openclaw matrix verify status --verbose ``` -Включити збережений recovery key у машиночитний вивід: +Включення збереженого recovery key у машиночитаний вивід: ```bash openclaw matrix verify status --include-recovery-key --json ``` -Ініціалізувати cross-signing і стан верифікації: +Ініціалізація cross-signing і стану верифікації: ```bash openclaw matrix verify bootstrap ``` -Підтримка кількох облікових записів: використовуйте `channels.matrix.accounts` з обліковими даними для кожного облікового запису та необов’язковим `name`. Див. [Configuration reference](/uk/gateway/configuration-reference#multi-account-all-channels) щодо спільного шаблону. +Підтримка кількох облікових записів: використовуйте `channels.matrix.accounts` з обліковими даними для кожного облікового запису та необов’язковим `name`. Див. [Configuration reference](/uk/gateway/configuration-reference#multi-account-all-channels) для спільного шаблону. Докладна діагностика bootstrap: @@ -291,13 +440,13 @@ openclaw matrix verify bootstrap openclaw matrix verify bootstrap --verbose ``` -Примусово скинути ідентичність cross-signing перед bootstrap: +Примусове скидання ідентичності cross-signing перед bootstrap: ```bash openclaw matrix verify bootstrap --force-reset-cross-signing ``` -Верифікувати цей пристрій за допомогою recovery key: +Верифікація цього пристрою за допомогою recovery key: ```bash openclaw matrix verify device "" @@ -321,7 +470,7 @@ openclaw matrix verify backup status openclaw matrix verify backup status --verbose ``` -Відновлення ключів кімнат із резервної копії на сервері: +Відновлення ключів кімнат із серверної резервної копії: ```bash openclaw matrix verify backup restore @@ -333,20 +482,20 @@ openclaw matrix verify backup restore openclaw matrix verify backup restore --verbose ``` -Видалити поточну резервну копію на сервері та створити нову базову резервну копію. Якщо збережений -ключ резервної копії не вдається коректно завантажити, це скидання також може відтворити secret storage, щоб +Видалення поточної серверної резервної копії та створення нової базової резервної копії. Якщо збережений +ключ резервної копії не вдається коректно завантажити, це скидання також може повторно створити secret storage, щоб майбутні холодні запуски могли завантажувати новий ключ резервної копії: ```bash openclaw matrix verify backup reset --yes ``` -Усі команди `verify` за замовчуванням є лаконічними (включно з тихим внутрішнім логуванням SDK) і показують детальну діагностику лише з `--verbose`. -Для повного машиночитного виводу в сценаріях використовуйте `--json`. +Усі команди `verify` за замовчуванням лаконічні (включно з тихим внутрішнім логуванням SDK) і показують детальну діагностику лише з `--verbose`. +Для повного машиночитаного виводу під час скриптування використовуйте `--json`. У конфігураціях із кількома обліковими записами команди Matrix CLI використовують неявний обліковий запис Matrix за замовчуванням, якщо ви не передасте `--account `. -Якщо ви налаштували кілька іменованих облікових записів, спочатку встановіть `channels.matrix.defaultAccount`, інакше такі неявні операції CLI зупиняться й попросять вас явно вибрати обліковий запис. -Використовуйте `--account`, коли хочете, щоб операції верифікації або роботи з пристроями явно націлювалися на іменований обліковий запис: +Якщо ви налаштували кілька іменованих облікових записів, спочатку задайте `channels.matrix.defaultAccount`, інакше такі неявні операції CLI зупинятимуться й проситимуть вас явно вибрати обліковий запис. +Використовуйте `--account`, коли хочете, щоб операції верифікації або з пристроями явно були спрямовані на конкретний іменований обліковий запис: ```bash openclaw matrix verify status --account assistant @@ -354,42 +503,43 @@ openclaw matrix verify backup restore --account assistant openclaw matrix devices list --account assistant ``` -Коли шифрування вимкнено або недоступне для іменованого облікового запису, попередження Matrix і помилки верифікації вказують на ключ конфігурації цього облікового запису, наприклад `channels.matrix.accounts.assistant.encryption`. +Коли шифрування вимкнене або недоступне для іменованого облікового запису, попередження Matrix і помилки верифікації вказують на ключ конфігурації цього облікового запису, наприклад `channels.matrix.accounts.assistant.encryption`. ### Що означає "verified" -OpenClaw вважає цей пристрій Matrix верифікованим лише тоді, коли його верифікує ваша власна ідентичність 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 -`Verified by owner` стає `yes` лише тоді, коли є верифікація cross-signing або підпис власника. -Самої локальної довіри недостатньо, щоб OpenClaw вважав пристрій повністю верифікованим. +`Verified by owner` стає `yes` лише тоді, коли присутня верифікація через cross-signing або підпис власника. +Локальної довіри самої по собі недостатньо, щоб OpenClaw вважав пристрій повністю верифікованим. ### Що робить bootstrap `openclaw matrix verify bootstrap` — це команда відновлення та налаштування для зашифрованих облікових записів Matrix. -Вона послідовно виконує все наведене нижче: +Вона виконує все наведене нижче в такому порядку: - ініціалізує secret storage, повторно використовуючи наявний recovery key, коли це можливо - ініціалізує cross-signing і завантажує відсутні публічні ключі cross-signing - намагається позначити й підписати поточний пристрій через cross-signing - створює нову серверну резервну копію ключів кімнат, якщо її ще не існує -Якщо 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` лише тоді, коли навмисно хочете відкинути поточну ідентичність cross-signing і створити нову. +Використовуйте `--force-reset-cross-signing` лише тоді, коли ви навмисно хочете відкинути поточну ідентичність cross-signing і створити нову. Якщо ви навмисно хочете відкинути поточну резервну копію ключів кімнат і почати нову -базову лінію резервного копіювання для майбутніх повідомлень, використовуйте `openclaw matrix verify backup reset --yes`. -Робіть це лише тоді, коли погоджуєтеся, що невідновлювана стара зашифрована історія залишиться -недоступною і що OpenClaw може відтворити secret storage, якщо поточний секрет резервної копії не вдається безпечно завантажити. +базову резервну копію для майбутніх повідомлень, використовуйте `openclaw matrix verify backup reset --yes`. +Робіть це лише тоді, коли погоджуєтеся, що стару зашифровану історію, яку неможливо відновити, +буде й надалі недоступно, і що OpenClaw може повторно створити secret storage, якщо поточний секрет +резервної копії не вдається безпечно завантажити. ### Нова базова резервна копія -Якщо ви хочете зберегти працездатність майбутніх зашифрованих повідомлень і погоджуєтеся на втрату невідновлюваної старої історії, виконайте ці команди в такому порядку: +Якщо ви хочете зберегти роботу майбутніх зашифрованих повідомлень і погоджуєтеся втратити стару історію, яку неможливо відновити, виконайте ці команди по черзі: ```bash openclaw matrix verify backup reset --yes @@ -397,19 +547,19 @@ openclaw matrix verify backup status --verbose openclaw matrix verify status ``` -Додайте `--account ` до кожної команди, якщо хочете явно націлитися на іменований обліковий запис Matrix. +Додавайте `--account ` до кожної команди, якщо хочете явно націлити їх на іменований обліковий запис Matrix. ### Поведінка під час запуску Коли `encryption: true`, Matrix за замовчуванням встановлює `startupVerification` у `"if-unverified"`. -Під час запуску, якщо цей пристрій усе ще не верифікований, Matrix запитує self-verification в іншому клієнті Matrix, -пропускає дубльовані запити, якщо один уже очікує, і застосовує локальний cooldown перед повторною спробою після перезапусків. -За замовчуванням після невдалих спроб запиту повтор виконується швидше, ніж після успішного створення запиту. +Під час запуску, якщо цей пристрій усе ще не верифікований, Matrix запросить self-verification в іншому Matrix client, +пропустить дублікати запитів, якщо один уже очікує, і застосує локальний cooldown перед повторною спробою після перезапусків. +За замовчуванням спроби, що завершилися помилкою, повторюються швидше, ніж успішне створення запиту. Установіть `startupVerification: "off"`, щоб вимкнути автоматичні запити під час запуску, або налаштуйте `startupVerificationCooldownHours`, -якщо вам потрібне коротше або довше вікно повторних спроб. +якщо хочете коротше або довше вікно повторної спроби. -Під час запуску також автоматично виконується консервативний прохід bootstrap для crypto. -Цей прохід спочатку намагається повторно використати поточні secret storage та ідентичність cross-signing і уникає скидання cross-signing, якщо ви не запускаєте явний сценарій відновлення bootstrap. +Під час запуску також автоматично виконується консервативний bootstrap криптографії. +Цей прохід спочатку намагається повторно використати поточні secret storage та ідентичність cross-signing і не скидає cross-signing, якщо ви не запускаєте явний сценарій відновлення bootstrap. Якщо під час запуску виявлено зламаний стан bootstrap і налаштовано `channels.matrix.password`, OpenClaw може спробувати суворіший шлях відновлення. Якщо поточний пристрій уже підписаний власником, OpenClaw зберігає цю ідентичність замість автоматичного скидання. @@ -417,44 +567,44 @@ openclaw matrix verify status Оновлення з попереднього публічного плагіна Matrix: - OpenClaw автоматично повторно використовує той самий обліковий запис Matrix, токен доступу та ідентичність пристрою, коли це можливо. -- Перш ніж виконуються будь-які дієві зміни міграції Matrix, OpenClaw створює або повторно використовує recovery snapshot у `~/Backups/openclaw-migrations/`. -- Якщо ви використовуєте кілька облікових записів Matrix, установіть `channels.matrix.defaultAccount` перед оновленням зі старого плоского сховища, щоб OpenClaw знав, який обліковий запис має отримати цей спільний застарілий стан. -- Якщо попередній плагін зберігав локально ключ розшифрування резервної копії ключів кімнат Matrix, запуск або `openclaw doctor --fix` автоматично імпортує його в новий потік recovery key. -- Якщо токен доступу Matrix змінився після підготовки міграції, під час запуску тепер виконується сканування сусідніх коренів сховища хеша токена на наявність очікуваного стану відновлення старих даних, перш ніж автоматичне відновлення резервної копії буде припинено. -- Якщо токен доступу зміниться пізніше для того самого облікового запису, homeserver і користувача, OpenClaw тепер надає перевагу повторному використанню найповнішого наявного кореня сховища хеша токена, замість початку з порожнього каталогу стану Matrix. -- Під час наступного запуску gateway резервні ключі кімнат автоматично відновлюються в нове crypto store. -- Якщо старий плагін мав лише локальні ключі кімнат, які ніколи не резервувалися, OpenClaw чітко попередить про це. Ці ключі не можна автоматично експортувати з попереднього rust crypto store, тому частина старої зашифрованої історії може залишатися недоступною, доки її не буде відновлено вручну. -- Повний процес оновлення, обмеження, команди відновлення та типові повідомлення міграції див. у [Matrix migration](/uk/install/migrating-matrix). +- Перш ніж запускати будь-які практичні зміни міграції Matrix, OpenClaw створює або повторно використовує snapshot відновлення в `~/Backups/openclaw-migrations/`. +- Якщо ви використовуєте кілька облікових записів Matrix, перед оновленням зі старого макета flat-store задайте `channels.matrix.defaultAccount`, щоб OpenClaw знав, який обліковий запис має отримати цей спільний legacy state. +- Якщо попередній плагін зберігав локально ключ розшифрування резервної копії ключів кімнат Matrix, startup або `openclaw doctor --fix` автоматично імпортують його в новий сценарій recovery-key. +- Якщо токен доступу Matrix змінився після підготовки міграції, startup тепер сканує сусідні корені сховища з token-hash на наявність незавершеного legacy restore state, перш ніж відмовитися від автоматичного відновлення резервної копії. +- Якщо токен доступу Matrix змінюється пізніше для того самого облікового запису, homeserver і користувача, OpenClaw тепер надає перевагу повторному використанню найбільш повного наявного кореня сховища з token-hash замість запуску з порожнього каталогу стану Matrix. +- Під час наступного запуску gateway збережені резервні ключі кімнат автоматично відновлюються в новому crypto store. +- Якщо старий плагін мав лише локальні ключі кімнат, які ніколи не потрапляли в резервну копію, OpenClaw чітко попередить про це. Ці ключі не можна автоматично експортувати з попереднього rust crypto store, тому частина старої зашифрованої історії може залишатися недоступною, доки її не буде відновлено вручну. +- Див. [Matrix migration](/uk/install/migrating-matrix) для повного сценарію оновлення, обмежень, команд відновлення та типових повідомлень міграції. -Стан зашифрованого runtime організовано в коренях на основі хеша токена для кожного облікового запису та користувача в +Зашифрований runtime state організовано в коренях на основі 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.json`), +прив’язки тредів (`thread-bindings.json`) і стан startup verification (`startup-verification.json`), коли ці можливості використовуються. -Коли токен змінюється, але ідентичність облікового запису залишається тією самою, OpenClaw повторно використовує найкращий наявний -корінь для цього кортежу обліковий запис/homeserver/користувач, щоб попередній sync state, crypto state, прив’язки тредів -і стан верифікації під час запуску залишалися видимими. +Коли токен змінюється, але ідентичність облікового запису лишається тією самою, OpenClaw повторно використовує найкращий наявний +корінь для цього кортежу облікового запису/homeserver/користувача, щоб попередній стан sync, crypto state, прив’язки тредів +і startup verification state залишалися видимими. ### Модель Node crypto store Matrix E2EE у цьому плагіні використовує офіційний шлях Rust crypto з `matrix-js-sdk` у Node. -Цей шлях очікує persistence на основі IndexedDB, якщо ви хочете, щоб crypto state зберігався після перезапусків. +Цей шлях очікує persistence на основі IndexedDB, якщо ви хочете, щоб crypto state переживав перезапуски. -Наразі OpenClaw забезпечує це в Node так: +Наразі OpenClaw забезпечує це в Node таким чином: -- використовуючи `fake-indexeddb` як API shim IndexedDB, який очікує SDK -- відновлюючи вміст Rust crypto IndexedDB з `crypto-idb-snapshot.json` перед `initRustCrypto` -- зберігаючи оновлений вміст IndexedDB назад у `crypto-idb-snapshot.json` після ініціалізації та під час runtime -- серіалізуючи відновлення та збереження snapshot відносно `crypto-idb-snapshot.json` за допомогою advisory file lock, щоб persistence під час виконання gateway і обслуговування CLI не змагалися за той самий файл snapshot +- використовує `fake-indexeddb` як shim API IndexedDB, якого очікує SDK +- відновлює вміст Rust crypto IndexedDB з `crypto-idb-snapshot.json` перед `initRustCrypto` +- зберігає оновлений вміст IndexedDB назад у `crypto-idb-snapshot.json` після init і під час runtime +- серіалізує відновлення та збереження snapshot відносно `crypto-idb-snapshot.json` за допомогою advisory file lock, щоб persistence runtime gateway і обслуговування CLI не змагалися за один і той самий файл snapshot -Це plumbing сумісності/сховища, а не власна криптографічна реалізація. -Файл snapshot є чутливим runtime state і зберігається з обмежувальними правами доступу до файлу. -У межах моделі безпеки OpenClaw хост gateway і локальний каталог стану OpenClaw уже перебувають усередині довіреної межі оператора, тому це насамперед питання експлуатаційної надійності, а не окрема межа віддаленої довіри. +Це plumbing сумісності/сховища, а не кастомна криптографічна реалізація. +Файл snapshot — це чутливий runtime state, і він зберігається з обмеженими правами доступу до файлів. +У межах моделі безпеки OpenClaw gateway host і локальний каталог стану OpenClaw вже входять до межі довіри оператора, тож це насамперед питання операційної стійкості, а не окрема віддалена межа довіри. Заплановане покращення: -- додати підтримку SecretRef для постійного матеріалу ключів Matrix, щоб recovery keys і пов’язані секрети шифрування сховища можна було брати з постачальників секретів OpenClaw, а не лише з локальних файлів +- додати підтримку SecretRef для постійного ключового матеріалу Matrix, щоб recovery keys і пов’язані секрети шифрування сховища можна було отримувати з провайдерів секретів OpenClaw, а не лише з локальних файлів ## Керування профілем @@ -465,39 +615,39 @@ 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 і десяткові значення), коли вони доступні +- повідомлення про запит на верифікацію +- повідомлення про готовність до верифікації (з явною підказкою "Verify by emoji") +- повідомлення про початок і завершення верифікації +- деталі SAS (emoji і десяткові значення), коли вони доступні -Вхідні запити на верифікацію від іншого клієнта Matrix відстежуються й автоматично приймаються OpenClaw. -Для потоків self-verification OpenClaw також автоматично запускає SAS-процес, коли стає доступною верифікація за emoji, і підтверджує свій бік. -Для запитів на верифікацію від іншого користувача/пристрою Matrix OpenClaw автоматично приймає запит, а потім чекає, поки SAS-процес продовжиться звичайним способом. -Вам усе одно потрібно порівняти emoji або десятковий SAS у своєму клієнті Matrix і підтвердити "They match" там, щоб завершити верифікацію. +Вхідні запити на верифікацію від іншого Matrix client відстежуються і автоматично приймаються OpenClaw. +Для сценаріїв self-verification OpenClaw також автоматично запускає SAS, коли стає доступною верифікація через emoji, і підтверджує свій бік. +Для запитів на верифікацію від іншого Matrix user/device OpenClaw автоматично приймає запит, а потім чекає, поки SAS продовжиться у звичайному режимі. +Вам усе одно потрібно порівняти emoji або десятковий SAS у вашому Matrix client і підтвердити там "They match", щоб завершити верифікацію. -OpenClaw не приймає наосліп дубльовані self-initiated потоки автоматично. Під час запуску пропускається створення нового запиту, якщо запит self-verification уже очікує. +OpenClaw не приймає сліпо дублікати власноруч ініційованих сценаріїв. Під час startup не створюється новий запит, якщо self-verification request уже очікує. -Повідомлення системи/протоколу верифікації не пересилаються в конвеєр чату агента, тому вони не створюють `NO_REPLY`. +Повідомлення протоколу/системи верифікації не передаються в конвеєр чату агента, тож вони не призводять до `NO_REPLY`. ### Гігієна пристроїв Старі пристрої Matrix, якими керував OpenClaw, можуть накопичуватися в обліковому записі й ускладнювати розуміння довіри в зашифрованих кімнатах. -Переглянути їх можна так: +Перелічіть їх за допомогою: ```bash openclaw matrix devices list ``` -Видалити застарілі пристрої Matrix, якими керував OpenClaw: +Видаліть застарілі пристрої Matrix, якими керував OpenClaw, за допомогою: ```bash openclaw matrix devices prune-stale @@ -505,13 +655,13 @@ openclaw matrix devices prune-stale ### Відновлення Direct Room -Якщо стан direct-message виходить із синхронізації, OpenClaw може отримати застарілі зіставлення `m.direct`, які вказують на старі окремі кімнати замість активного DM. Перегляньте поточне зіставлення для співрозмовника за допомогою: +Якщо стан direct-message виходить із синхронізації, OpenClaw може отримати застарілі мапінги `m.direct`, які вказують на старі окремі кімнати замість живого DM. Перевірте поточне зіставлення для співрозмовника за допомогою: ```bash openclaw matrix direct inspect --user-id @alice:example.org ``` -Відновіть його так: +Виправте його за допомогою: ```bash openclaw matrix direct repair --user-id @alice:example.org @@ -519,51 +669,51 @@ openclaw matrix direct repair --user-id @alice:example.org Відновлення зберігає логіку, специфічну для Matrix, усередині плагіна: -- воно надає перевагу суворому 1:1 DM, який уже відображено в `m.direct` -- інакше воно переходить до будь-якого поточного приєднаного суворого 1:1 DM із цим користувачем -- якщо здорового DM не існує, воно створює нову direct room і переписує `m.direct`, щоб вона вказувала на неї +- воно надає перевагу суворому DM 1:1, який уже відображено в `m.direct` +- інакше повертається до будь-якого поточно приєднаного суворого DM 1:1 із цим користувачем +- якщо здорового DM не існує, створює нову direct room і переписує `m.direct`, щоб вона вказувала на неї -Потік відновлення не видаляє старі кімнати автоматично. Він лише вибирає здоровий DM і оновлює зіставлення, щоб нові надсилання Matrix, сповіщення верифікації та інші потоки direct-message знову націлювалися на правильну кімнату. +Сценарій відновлення не видаляє старі кімнати автоматично. Він лише обирає здоровий DM і оновлює мапінг, щоб нові надсилання Matrix, сповіщення про верифікацію та інші direct-message сценарії знову спрямовувалися до правильної кімнати. ## Треди -Matrix підтримує нативні треди Matrix як для автоматичних відповідей, так і для надсилань інструментом повідомлень. +Matrix підтримує нативні треди Matrix як для автоматичних відповідей, так і для надсилань через message-tool. -- `dm.sessionScope: "per-user"` (за замовчуванням) зберігає маршрутизацію Matrix DM на рівні відправника, тож кілька DM-кімнат можуть спільно використовувати одну сесію, якщо вони відповідають тому самому співрозмовнику. -- `dm.sessionScope: "per-room"` ізолює кожну Matrix DM-кімнату у власний ключ сесії, водночас використовуючи звичайні перевірки автентифікації та allowlist для DM. -- Явні прив’язки розмов Matrix усе одно мають пріоритет над `dm.sessionScope`, тож прив’язані кімнати й треди зберігають свою вибрану цільову сесію. -- `threadReplies: "off"` залишає відповіді верхнього рівня й зберігає вхідні тредові повідомлення в батьківській сесії. +- `dm.sessionScope: "per-user"` (за замовчуванням) зберігає маршрутизацію Matrix DM із прив’язкою до відправника, тож кілька кімнат DM можуть ділити одну сесію, якщо вони визначаються як той самий співрозмовник. +- `dm.sessionScope: "per-room"` ізолює кожну кімнату Matrix DM у власний ключ сесії, водночас і далі використовуючи звичайну автентифікацію DM та перевірки allowlist. +- Явні прив’язки розмов Matrix усе одно мають пріоритет над `dm.sessionScope`, тому прив’язані кімнати й треди зберігають свою вибрану цільову сесію. +- `threadReplies: "off"` залишає відповіді на верхньому рівні й зберігає вхідні threaded messages у батьківській сесії. - `threadReplies: "inbound"` відповідає всередині треду лише тоді, коли вхідне повідомлення вже було в цьому треді. -- `threadReplies: "always"` зберігає відповіді в кімнаті в треді, коренем якого є повідомлення-тригер, і маршрутизує цю розмову через відповідну сесію з областю треду від першого тригерного повідомлення. -- `dm.threadReplies` перевизначає параметр верхнього рівня лише для DM. Наприклад, ви можете зберегти ізоляцію тредів у кімнатах, залишивши DM пласкими. -- Вхідні повідомлення в тредах включають кореневе повідомлення треду як додатковий контекст агента. -- Надсилання інструментом повідомлень тепер автоматично успадковують поточний тред Matrix, коли ціль — та сама кімната або та сама ціль користувача 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` тепер працюють у кімнатах і DM Matrix. -- Верхньорівневий `/focus` у кімнаті/DM Matrix створює новий тред Matrix і прив’язує його до цільової сесії, коли `threadBindings.spawnSubagentSessions=true`. -- Виконання `/focus` або `/acp spawn --thread here` усередині наявного треду Matrix натомість прив’язує цей поточний тред. +- `threadReplies: "always"` зберігає відповіді в кімнаті в треді, що починається від повідомлення-тригера, і маршрутизує цю розмову через відповідну сесію з прив’язкою до треду від першого повідомлення-тригера. +- `dm.threadReplies` перевизначає налаштування верхнього рівня лише для DM. Наприклад, ви можете ізолювати треди в кімнатах, залишивши DM плоскими. +- Вхідні threaded messages включають кореневе повідомлення треду як додатковий контекст для агента. +- Надсилання через message-tool тепер автоматично успадковують поточний тред Matrix, коли ціллю є та сама кімната або той самий DM-користувач, якщо не задано явний `threadId`. +- Повторне використання цілі DM-користувача в тій самій сесії спрацьовує лише тоді, коли метадані поточної сесії підтверджують того самого DM-співрозмовника в тому самому обліковому записі Matrix; інакше OpenClaw повертається до звичайної маршрутизації з областю користувача. +- Коли OpenClaw бачить, що Matrix DM room конфліктує з іншою DM room у межах тієї самої спільної Matrix DM session, він публікує одноразове `m.notice` у цій кімнаті з escape hatch `/focus`, якщо прив’язки тредів увімкнено, і з підказкою `dm.sessionScope`. +- Runtime-прив’язки тредів підтримуються для Matrix. `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язаний до треду `/acp spawn` тепер працюють у кімнатах і DM Matrix. +- `/focus` у Matrix room/DM верхнього рівня створює новий тред Matrix і прив’язує його до цільової сесії, коли `threadBindings.spawnSubagentSessions=true`. +- Запуск `/focus` або `/acp spawn --thread here` всередині наявного треду Matrix натомість прив’язує цей поточний тред. ## Прив’язки розмов ACP -Кімнати Matrix, DM та наявні треди Matrix можна перетворювати на довговічні робочі простори ACP без зміни поверхні чату. +Кімнати Matrix, DM і наявні треди Matrix можна перетворити на довговічні робочі простори ACP без зміни поверхні чату. -Швидкий робочий потік оператора: +Швидкий сценарій для оператора: -- Виконайте `/acp spawn codex --bind here` у DM Matrix, кімнаті або наявному треді, який ви хочете й надалі використовувати. -- У верхньорівневому DM Matrix або кімнаті поточний DM/кімната залишається поверхнею чату, а майбутні повідомлення маршрутизуються до створеної ACP-сесії. +- Виконайте `/acp spawn codex --bind here` всередині Matrix DM, кімнати або наявного треду, яким хочете продовжувати користуватися. +- У Matrix DM або кімнаті верхнього рівня поточний DM/кімната залишається поверхнею чату, а майбутні повідомлення маршрутизуються до створеної сесії ACP. - Усередині наявного треду Matrix `--bind here` прив’язує цей поточний тред на місці. -- `/new` і `/reset` скидають ту саму прив’язану ACP-сесію на місці. -- `/acp close` закриває ACP-сесію та видаляє прив’язку. +- `/new` і `/reset` скидають ту саму прив’язану сесію ACP на місці. +- `/acp close` закриває сесію ACP і видаляє прив’язку. Примітки: - `--bind here` не створює дочірній тред Matrix. -- `threadBindings.spawnAcpSessions` потрібен лише для `/acp spawn --thread auto|here`, коли OpenClaw має створити або прив’язати дочірній тред Matrix. +- `threadBindings.spawnAcpSessions` потрібен лише для `/acp spawn --thread auto|here`, де OpenClaw має створити або прив’язати дочірній тред Matrix. ### Конфігурація прив’язки тредів -Matrix успадковує глобальні значення за замовчуванням із `session.threadBindings`, а також підтримує перевизначення для конкретного каналу: +Matrix успадковує глобальні значення за замовчуванням із `session.threadBindings`, а також підтримує перевизначення для окремого каналу: - `threadBindings.enabled` - `threadBindings.idleHours` @@ -571,29 +721,29 @@ Matrix успадковує глобальні значення за замов - `threadBindings.spawnSubagentSessions` - `threadBindings.spawnAcpSessions` -Прапорці створення з прив’язкою до треду для Matrix вмикаються за бажанням: +Прапорці spawn для thread-bound у Matrix є opt-in: -- Установіть `threadBindings.spawnSubagentSessions: true`, щоб дозволити верхньорівневому `/focus` створювати й прив’язувати нові треди Matrix. -- Установіть `threadBindings.spawnAcpSessions: true`, щоб дозволити `/acp spawn --thread auto|here` прив’язувати ACP-сесії до тредів Matrix. +- Установіть `threadBindings.spawnSubagentSessions: true`, щоб дозволити `/focus` верхнього рівня створювати та прив’язувати нові треди Matrix. +- Установіть `threadBindings.spawnAcpSessions: true`, щоб дозволити `/acp spawn --thread auto|here` прив’язувати сесії ACP до тредів Matrix. ## Реакції -Matrix підтримує вихідні дії реакцій, вхідні сповіщення про реакції та вхідні реакції-підтвердження. +Matrix підтримує вихідні дії з реакціями, вхідні сповіщення про реакції та вхідні ack reactions. -- Інструменти вихідних реакцій контролюються через `channels["matrix"].actions.reactions`. -- `react` додає реакцію до конкретної події Matrix. -- `reactions` показує поточне зведення реакцій для конкретної події Matrix. +- Інструментарій вихідних реакцій контролюється через `channels["matrix"].actions.reactions`. +- `react` додає реакцію до певної події Matrix. +- `reactions` перелічує поточне зведення реакцій для певної події Matrix. - `emoji=""` видаляє власні реакції облікового запису бота на цій події. -- `remove: true` видаляє лише вказану реакцію emoji з облікового запису бота. +- `remove: true` видаляє з облікового запису бота лише реакцію з указаним emoji. -Область реакцій-підтверджень визначається у стандартному порядку OpenClaw: +Область ack reactions визначається в такому порядку: - `channels["matrix"].accounts..ackReaction` - `channels["matrix"].ackReaction` - `messages.ackReaction` -- резервне emoji ідентичності агента +- fallback до emoji ідентичності агента -Область дії реакції-підтвердження визначається в такому порядку: +Область дії ack reaction визначається в такому порядку: - `channels["matrix"].accounts..ackReactionScope` - `channels["matrix"].ackReactionScope` @@ -603,33 +753,33 @@ Matrix підтримує вихідні дії реакцій, вхідні с - `channels["matrix"].accounts..reactionNotifications` - `channels["matrix"].reactionNotifications` -- значення за замовчуванням: `own` +- за замовчуванням: `own` Поточна поведінка: -- `reactionNotifications: "own"` пересилає додані події `m.reaction`, коли вони націлені на повідомлення Matrix, створені ботом. +- `reactionNotifications: "own"` передає додані події `m.reaction`, коли вони спрямовані на повідомлення Matrix, створені ботом. - `reactionNotifications: "off"` вимикає системні події реакцій. -- Видалення реакцій усе ще не синтезуються в системні події, тому що Matrix показує їх як redaction, а не як окремі видалення `m.reaction`. +- Видалення реакцій досі не синтезуються в системні події, тому що Matrix представляє їх як redaction-и, а не як окремі видалення `m.reaction`. ## Контекст історії -- `channels.matrix.historyLimit` керує тим, скільки нещодавніх повідомлень кімнати включаються як `InboundHistory`, коли повідомлення Matrix у кімнаті запускає агента. -- Використовується fallback на `messages.groupChat.historyLimit`. Установіть `0`, щоб вимкнути. -- Історія кімнати Matrix стосується лише кімнати. DM і далі використовують звичайну історію сесії. -- Історія кімнати Matrix є лише відкладеною: OpenClaw буферизує повідомлення кімнати, які ще не викликали відповіді, а потім фіксує це вікно, коли надходить згадка або інший тригер. -- Поточне тригерне повідомлення не включається в `InboundHistory`; воно залишається в основному вхідному тілі для цього ходу. -- Повторні спроби для тієї самої події Matrix повторно використовують початковий snapshot історії замість зсуву вперед до новіших повідомлень кімнати. +- `channels.matrix.historyLimit` визначає, скільки останніх повідомлень кімнати включається як `InboundHistory`, коли повідомлення кімнати Matrix активує агента. +- Використовується fallback до `messages.groupChat.historyLimit`. Установіть `0`, щоб вимкнути. +- Історія кімнати Matrix — лише для кімнати. DM і далі використовують звичайну історію сесії. +- Історія кімнати Matrix є pending-only: OpenClaw буферизує повідомлення кімнати, які ще не викликали відповідь, а потім робить snapshot цього вікна, коли надходить згадка або інший тригер. +- Поточне повідомлення-тригер не включається в `InboundHistory`; воно залишається в основному вхідному тілі для цього ходу. +- Повторні спроби для тієї самої події Matrix повторно використовують оригінальний snapshot історії замість зміщення вперед до новіших повідомлень кімнати. ## Видимість контексту -Matrix підтримує спільний елемент керування `contextVisibility` для додаткового контексту кімнати, такого як отриманий текст відповіді, корені тредів і відкладена історія. +Matrix підтримує спільний контроль `contextVisibility` для додаткового контексту кімнати, як-от отриманий текст відповіді, корені тредів і незавершена історія. - `contextVisibility: "all"` — значення за замовчуванням. Додатковий контекст зберігається як отримано. - `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників, дозволених активними перевірками allowlist кімнати/користувача. -- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явну процитовану відповідь. +- `contextVisibility: "allowlist_quote"` працює як `allowlist`, але все одно зберігає одну явну цитовану відповідь. -Цей параметр впливає на видимість додаткового контексту, а не на те, чи може саме вхідне повідомлення викликати відповідь. -Авторизація тригера й надалі визначається через `groupPolicy`, `groups`, `groupAllowFrom` і параметри політики DM. +Це налаштування впливає на видимість додаткового контексту, а не на те, чи може саме вхідне повідомлення викликати відповідь. +Авторизація тригера, як і раніше, походить із `groupPolicy`, `groups`, `groupAllowFrom` і налаштувань політики DM. ## Приклад політики для DM і кімнат @@ -654,7 +804,7 @@ Matrix підтримує спільний елемент керування `co } ``` -Див. [Groups](/uk/channels/groups) щодо поведінки згадок і allowlist. +Див. [Groups](/uk/channels/groups) щодо керування згадками й поведінки allowlist. Приклад pairing для Matrix DM: @@ -663,53 +813,53 @@ openclaw pairing list matrix openclaw pairing approve matrix ``` -Якщо непідтверджений користувач Matrix продовжує писати вам до схвалення, OpenClaw повторно використовує той самий очікуваний код pairing і може знову надіслати відповідь-нагадування після короткого cooldown замість створення нового коду. +Якщо непідтверджений користувач Matrix продовжує писати вам до схвалення, OpenClaw повторно використовує той самий pending pairing code і може знову надіслати нагадування після короткого cooldown замість створення нового коду. -Див. [Pairing](/uk/channels/pairing) щодо спільного потоку pairing для DM і структури сховища. +Див. [Pairing](/uk/channels/pairing) для спільного сценарію pairing у DM і структури сховища. -## Підтвердження exec +## Погодження exec -Matrix може виступати клієнтом підтвердження exec для облікового запису Matrix. +Matrix може діяти як клієнт погодження exec для облікового запису Matrix. - `channels.matrix.execApprovals.enabled` -- `channels.matrix.execApprovals.approvers` (необов’язково; використовується fallback на `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"`, і принаймні одного approver можна визначити або з `execApprovals.approvers`, або з `channels.matrix.dm.allowFrom`. Установіть `enabled: false`, щоб явно вимкнути Matrix як нативний клієнт підтвердження. Інакше запити на підтвердження використовують fallback на інші налаштовані маршрути підтвердження або політику fallback для підтверджень exec. +Approvers мають бути Matrix user ID, наприклад `@owner:example.org`. Matrix автоматично вмикає нативні exec approvals, коли `enabled` не задано або дорівнює `"auto"` і можна визначити принаймні одного approver, або з `execApprovals.approvers`, або з `channels.matrix.dm.allowFrom`. Установіть `enabled: false`, щоб явно вимкнути Matrix як нативний клієнт погодження. Інакше запити на погодження переходять до інших налаштованих маршрутів погодження або до fallback policy для exec approval. Нативна маршрутизація Matrix наразі стосується лише exec: -- `channels.matrix.execApprovals.*` керує нативною маршрутизацією DM/каналу лише для підтверджень exec. -- Підтвердження плагінів і далі використовують спільний `/approve` у тому самому чаті плюс будь-яке налаштоване пересилання `approvals.plugin`. -- Matrix усе ще може повторно використовувати `channels.matrix.dm.allowFrom` для авторизації підтвердження плагінів, коли може безпечно визначити approvers, але не надає окремий нативний шлях fanout DM/каналу для підтверджень плагінів. +- `channels.matrix.execApprovals.*` керує нативною маршрутизацією DM/channel лише для exec approvals. +- Погодження плагінів і далі використовують спільний `/approve` у тому ж чаті плюс будь-яке налаштоване пересилання `approvals.plugin`. +- Matrix усе ще може повторно використовувати `channels.matrix.dm.allowFrom` для авторизації погоджень плагінів, коли може безпечно визначити approver-ів, але не надає окремого нативного шляху fanout DM/channel для погоджень плагінів. -Правила доставлення: +Правила доставки: -- `target: "dm"` надсилає запити на підтвердження в DM approver’ів -- `target: "channel"` надсилає запит назад у вихідну кімнату або DM Matrix -- `target: "both"` надсилає в DM approver’ів і у вихідну кімнату або DM Matrix +- `target: "dm"` надсилає запити на погодження в DM approver-ів +- `target: "channel"` надсилає запит назад у вихідну кімнату Matrix або DM +- `target: "both"` надсилає в DM approver-ів і у вихідну кімнату Matrix або DM -Підказки підтвердження Matrix ініціалізують ярлики реакцій у первинному повідомленні підтвердження: +Запити на погодження Matrix ініціалізують shortcut-реакції на основному повідомленні погодження: - `✅` = дозволити один раз - `❌` = відхилити -- `♾️` = дозволити завжди, коли таке рішення дозволено ефективною політикою exec +- `♾️` = дозволити завжди, якщо таке рішення дозволене ефективною політикою exec -Approver’и можуть реагувати на це повідомлення або використовувати резервні slash-команди: `/approve allow-once`, `/approve allow-always` або `/approve deny`. +Approver-и можуть реагувати на це повідомлення або використовувати fallback slash-команди: `/approve allow-once`, `/approve allow-always` або `/approve deny`. -Лише визначені approver’и можуть підтверджувати або відхиляти. Доставлення в канал включає текст команди, тому вмикайте `channel` або `both` лише в довірених кімнатах. +Лише визначені approver-и можуть дозволяти або відхиляти. Доставка в канал включає текст команди, тому вмикайте `channel` або `both` лише в довірених кімнатах. -Підказки підтвердження Matrix повторно використовують спільний core approval planner. Нативна поверхня, специфічна для Matrix, є лише транспортом для підтверджень exec: маршрутизація кімната/DM і поведінка надсилання/оновлення/видалення повідомлень. +Запити на погодження Matrix повторно використовують спільний core approval planner. Нативна поверхня Matrix — це лише транспорт для exec approvals: маршрутизація кімнат/DM і поведінка надсилання/оновлення/видалення повідомлень. -Перевизначення для облікового запису: +Перевизначення для окремого облікового запису: - `channels.matrix.accounts..execApprovals` Пов’язана документація: [Exec approvals](/uk/tools/exec-approvals) -## Приклад кількох облікових записів +## Приклад із кількома обліковими записами ```json5 { @@ -740,20 +890,20 @@ Approver’и можуть реагувати на це повідомлення ``` Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для іменованих облікових записів, якщо обліковий запис не перевизначає їх. -Ви можете обмежити успадкований запис кімнати одним обліковим записом Matrix за допомогою `groups..account` (або застарілого `rooms..account`). -Записи без `account` залишаються спільними для всіх облікових записів Matrix, а записи з `account: "default"` усе ще працюють, коли обліковий запис за замовчуванням налаштовано безпосередньо на верхньому рівні `channels.matrix.*`. -Часткові спільні значення автентифікації за замовчуванням самі по собі не створюють окремий неявний обліковий запис за замовчуванням. OpenClaw синтезує верхньорівневий обліковий запис `default` лише тоді, коли цей обліковий запис за замовчуванням має актуальну автентифікацію (`homeserver` плюс `accessToken` або `homeserver` плюс `userId` і `password`); іменовані облікові записи все ще можуть залишатися виявлюваними через `homeserver` плюс `userId`, якщо кешовані облікові дані пізніше задовольнять автентифікацію. -Якщо в Matrix уже є рівно один іменований обліковий запис або `defaultAccount` вказує на наявний ключ іменованого облікового запису, відновлення/налаштування з переходом від одного облікового запису до кількох зберігає цей обліковий запис замість створення нового запису `accounts.default`. Лише ключі автентифікації/bootstrap Matrix переносяться до цього підвищеного облікового запису; спільні ключі політики доставлення залишаються на верхньому рівні. -Установіть `defaultAccount`, якщо хочете, щоб OpenClaw надавав перевагу одному іменованому обліковому запису Matrix для неявної маршрутизації, probe і операцій CLI. -Якщо ви налаштували кілька іменованих облікових записів, установіть `defaultAccount` або передавайте `--account ` для команд CLI, які покладаються на неявний вибір облікового запису. +Ви можете обмежити успадковані записи кімнат одним обліковим записом Matrix за допомогою `groups..account` (або legacy `rooms..account`). +Записи без `account` залишаються спільними для всіх облікових записів Matrix, а записи з `account: "default"` і далі працюють, коли обліковий запис за замовчуванням налаштовано безпосередньо на верхньому рівні `channels.matrix.*`. +Часткові спільні значення автентифікації за замовчуванням самі по собі не створюють окремий неявний обліковий запис за замовчуванням. OpenClaw синтезує верхньорівневий обліковий запис `default` лише тоді, коли цей обліковий запис має актуальну автентифікацію (`homeserver` плюс `accessToken`, або `homeserver` плюс `userId` і `password`); іменовані облікові записи все одно можуть залишатися доступними через `homeserver` плюс `userId`, коли пізніше автентифікація задовольняється кешованими обліковими даними. +Якщо Matrix уже має рівно один іменований обліковий запис або `defaultAccount` вказує на наявний ключ іменованого облікового запису, просування від single-account до multi-account під час відновлення/налаштування зберігає цей обліковий запис замість створення нового запису `accounts.default`. У цей просунутий обліковий запис переміщуються лише ключі Matrix auth/bootstrap; спільні ключі політики доставки залишаються на верхньому рівні. +Установіть `defaultAccount`, якщо хочете, щоб OpenClaw віддавав перевагу одному іменованому обліковому запису Matrix для неявної маршрутизації, probing і операцій 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 або внутрішньому імені хоста, увімкніть `allowPrivateNetwork` для цього облікового запису Matrix: ```json5 @@ -778,12 +928,12 @@ openclaw matrix account add \ --access-token syt_ops_xxx ``` -Це явне ввімкнення дозволяє лише довірені приватні/внутрішні цілі. Публічні незашифровані homeserver, наприклад -`http://matrix.example.org:8008`, і далі блокуються. За можливості надавайте перевагу `https://`. +Ця opt-in опція дозволяє лише довірені приватні/внутрішні цілі. Публічні homeserver-и без шифрування, наприклад +`http://matrix.example.org:8008`, і далі блокуються. За можливості віддавайте перевагу `https://`. ## Проксіювання трафіку Matrix -Якщо ваше розгортання Matrix потребує явного вихідного HTTP(S) proxy, установіть `channels.matrix.proxy`: +Якщо вашому розгортанню Matrix потрібен явний вихідний HTTP(S) proxy, задайте `channels.matrix.proxy`: ```json5 { @@ -797,86 +947,86 @@ openclaw matrix account add \ } ``` -Іменовані облікові записи можуть перевизначати значення верхнього рівня за замовчуванням через `channels.matrix.accounts..proxy`. -OpenClaw використовує те саме налаштування proxy і для runtime-трафіку Matrix, і для probes стану облікового запису. +Іменовані облікові записи можуть перевизначати верхньорівневе значення за замовчуванням через `channels.matrix.accounts..proxy`. +OpenClaw використовує той самий параметр proxy для runtime-трафіку Matrix і перевірок стану облікового запису. -## Визначення цілі +## Визначення цілей -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:server`, `channel:#alias:server` або `matrix:channel:#alias:server` -Живий пошук у директорії використовує обліковий запис Matrix, під яким виконано вхід: +Живий пошук у каталозі використовує обліковий запис Matrix, у який виконано вхід: -- Пошук користувачів звертається до директорії користувачів Matrix на цьому homeserver. -- Пошук кімнат напряму приймає явні ID кімнат і аліаси, а потім використовує fallback до пошуку назв приєднаних кімнат для цього облікового запису. -- Пошук за назвою приєднаної кімнати виконується за принципом best-effort. Якщо назву кімнати не вдається зіставити з ID або аліасом, під час виконання її буде проігноровано в allowlist. +- Пошук користувачів виконує запити до каталогу користувачів Matrix на цьому homeserver. +- Пошук кімнат безпосередньо приймає явні ID кімнат і псевдоніми, а потім переходить до пошуку серед назв приєднаних кімнат цього облікового запису. +- Пошук за назвами приєднаних кімнат є best-effort. Якщо назву кімнати не вдається визначити як ID або псевдонім, вона ігнорується під час runtime-розв’язання allowlist. -## Довідка з конфігурації +## Довідник конфігурації - `enabled`: увімкнути або вимкнути канал. - `name`: необов’язкова мітка для облікового запису. - `defaultAccount`: бажаний ID облікового запису, коли налаштовано кілька облікових записів Matrix. - `homeserver`: URL homeserver, наприклад `https://matrix.example.org`. -- `allowPrivateNetwork`: дозволити цьому обліковому запису Matrix підключатися до приватних/внутрішніх homeserver. Увімкніть це, якщо homeserver визначається як `localhost`, LAN/Tailscale IP або внутрішній хост, наприклад `matrix-synapse`. -- `proxy`: необов’язковий URL HTTP(S) proxy для трафіку Matrix. Іменовані облікові записи можуть перевизначити значення верхнього рівня за замовчуванням власним `proxy`. +- `allowPrivateNetwork`: дозволити цьому обліковому запису Matrix підключатися до приватних/внутрішніх homeserver-ів. Увімкніть це, коли homeserver визначається як `localhost`, LAN/Tailscale IP або внутрішній хост, наприклад `matrix-synapse`. +- `proxy`: необов’язковий URL HTTP(S) proxy для трафіку Matrix. Іменовані облікові записи можуть перевизначати верхньорівневе значення за замовчуванням власним `proxy`. - `userId`: повний Matrix user ID, наприклад `@bot:example.org`. -- `accessToken`: токен доступу для автентифікації на основі токена. Для `channels.matrix.accessToken` і `channels.matrix.accounts..accessToken` підтримуються як відкриті значення, так і значення SecretRef у постачальниках env/file/exec. Див. [Secrets Management](/uk/gateway/secrets). -- `password`: пароль для входу на основі пароля. Підтримуються відкриті значення та значення SecretRef. +- `accessToken`: токен доступу для автентифікації на основі токена. Для `channels.matrix.accessToken` і `channels.matrix.accounts..accessToken` підтримуються значення plaintext і SecretRef у провайдерах env/file/exec. Див. [Secrets Management](/uk/gateway/secrets). +- `password`: пароль для входу на основі пароля. Підтримуються значення plaintext і SecretRef. - `deviceId`: явний Matrix device ID. - `deviceName`: відображувана назва пристрою для входу за паролем. -- `avatarUrl`: збережений self-avatar URL для синхронізації профілю та оновлень `set-profile`. +- `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`: максимальна кількість повідомлень кімнати, що включаються як контекст історії групи. Використовує fallback на `messages.groupChat.historyLimit`. Установіть `0`, щоб вимкнути. +- Записи `groupAllowFrom` мають бути повними Matrix user ID. Нерозпізнані імена ігноруються під час runtime. +- `historyLimit`: максимальна кількість повідомлень кімнати для включення як контекст історії групи. Використовує fallback до `messages.groupChat.historyLimit`. Установіть `0`, щоб вимкнути. - `replyToMode`: `off`, `first` або `all`. - `markdown`: необов’язкова конфігурація рендерингу Markdown для вихідного тексту Matrix. -- `streaming`: `off` (за замовчуванням), `partial`, `true` або `false`. `partial` і `true` вмикають попередній перегляд чернетки одним повідомленням з оновленнями редагування на місці. -- `blockStreaming`: `true` вмикає окремі повідомлення прогресу для завершених блоків помічника, поки активне потокове передавання чернетки попереднього перегляду. +- `streaming`: `off` (за замовчуванням), `partial`, `quiet`, `true` або `false`. `partial` і `true` вмикають оновлення чернеток із попереднім preview через звичайні текстові повідомлення Matrix. `quiet` використовує preview notices без сповіщень для self-hosted конфігурацій із push rules. +- `blockStreaming`: `true` вмикає окремі повідомлення про прогрес для завершених блоків асистента, поки активний draft preview streaming. - `threadReplies`: `off`, `inbound` або `always`. -- `threadBindings`: перевизначення для конкретного каналу для маршрутизації та життєвого циклу сесій, прив’язаних до тредів. +- `threadBindings`: перевизначення для окремого каналу щодо маршрутизації та життєвого циклу сесій, прив’язаних до тредів. - `startupVerification`: режим автоматичного запиту self-verification під час запуску (`if-unverified`, `off`). -- `startupVerificationCooldownHours`: cooldown перед повторними спробами автоматичних запитів верифікації під час запуску. -- `textChunkLimit`: розмір фрагмента вихідного повідомлення. +- `startupVerificationCooldownHours`: cooldown перед повторною спробою автоматичних запитів верифікації під час запуску. +- `textChunkLimit`: розмір chunk вихідного повідомлення. - `chunkMode`: `length` або `newline`. - `responsePrefix`: необов’язковий префікс повідомлення для вихідних відповідей. -- `ackReaction`: необов’язкове перевизначення реакції-підтвердження для цього каналу/облікового запису. -- `ackReactionScope`: необов’язкове перевизначення області реакції-підтвердження (`group-mentions`, `group-all`, `direct`, `all`, `none`, `off`). +- `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`. -- `autoJoinAllowlist`: кімнати/аліаси, дозволені, коли `autoJoin` має значення `allowlist`. Записи аліасів під час обробки запрошення перетворюються на ID кімнат; OpenClaw не довіряє стану аліаса, заявленому запрошеною кімнатою. +- `mediaMaxMb`: обмеження розміру медіа в МБ для обробки медіа Matrix. Застосовується до вихідного надсилання та обробки вхідних медіа. +- `autoJoin`: політика автоматичного приєднання до запрошень (`always`, `allowlist`, `off`). За замовчуванням: `off`. +- `autoJoinAllowlist`: кімнати/псевдоніми, дозволені, коли `autoJoin` має значення `allowlist`. Псевдоніми визначаються як room ID під час обробки запрошення; OpenClaw не довіряє стану псевдоніма, який заявляє запрошена кімната. - `dm`: блок політики DM (`enabled`, `policy`, `allowFrom`, `sessionScope`, `threadReplies`). -- Записи `dm.allowFrom` мають бути повними Matrix user ID, якщо тільки ви вже не розпізнали їх через живий пошук у директорії. -- `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-запити. Необов’язково, якщо approver’ів уже визначає `dm.allowFrom`. +- Записи `dm.allowFrom` мають бути повними Matrix user ID, якщо тільки ви вже не визначили їх через живий пошук у каталозі. +- `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 кімнати, тоді як людиночитані мітки й надалі походять із назв кімнат. +- `accounts`: іменовані перевизначення для окремих облікових записів. Значення верхнього рівня `channels.matrix` діють як значення за замовчуванням для цих записів. +- `groups`: мапа політик для окремих кімнат. Віддавайте перевагу room ID або псевдонімам; нерозпізнані назви кімнат ігноруються під час runtime. Ідентичність сесії/групи після визначення використовує стабільний room ID, тоді як людськочитані мітки все ще походять із назв кімнат. - `groups..account`: обмежити один успадкований запис кімнати конкретним обліковим записом Matrix у конфігураціях із кількома обліковими записами. -- `groups..allowBots`: перевизначення на рівні кімнати для відправників із налаштованих ботів (`true` або `"mentions"`). -- `groups..users`: allowlist відправників для конкретної кімнати. -- `groups..tools`: перевизначення allow/deny інструментів для конкретної кімнати. -- `groups..autoReply`: перевизначення вимоги згадки на рівні кімнати. `true` вимикає вимоги щодо згадки для цієї кімнати; `false` знову примусово вмикає їх. +- `groups..allowBots`: перевизначення на рівні кімнати для відправників-ботів із конфігурації (`true` або `"mentions"`). +- `groups..users`: allowlist відправників для окремої кімнати. +- `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`). +- `rooms`: legacy-псевдонім для `groups`. +- `actions`: контроль доступу до інструментів для окремих дій (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`). ## Пов’язане - [Channels Overview](/uk/channels) — усі підтримувані канали -- [Pairing](/uk/channels/pairing) — автентифікація DM і потік pairing -- [Groups](/uk/channels/groups) — поведінка групового чату та керування згадками +- [Pairing](/uk/channels/pairing) — автентифікація DM і сценарій pairing +- [Groups](/uk/channels/groups) — поведінка групового чату й керування згадками - [Channel Routing](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень -- [Security](/uk/gateway/security) — модель доступу та посилення безпеки +- [Security](/uk/gateway/security) — модель доступу та посилення захисту diff --git a/docs/uk/channels/qa-channel.md b/docs/uk/channels/qa-channel.md new file mode 100644 index 000000000..91da52931 --- /dev/null +++ b/docs/uk/channels/qa-channel.md @@ -0,0 +1,113 @@ +--- +read_when: + - Ви підключаєте синтетичний транспорт QA до локального або CI тестового запуску + - Вам потрібна поверхня конфігурації вбудованого qa-channel + - Ви працюєте над наскрізною автоматизацією QA +summary: Синтетичний плагін каналу класу Slack для детермінованих сценаріїв QA OpenClaw +title: Канал QA +x-i18n: + generated_at: "2026-04-05T22:36:40Z" + model: gpt-5.4 + provider: openai + source_hash: 3b88cd73df2f61b34ad1eb83c3450f8fe15a51ac69fbb5a9eca0097564d67a06 + source_path: channels/qa-channel.md + workflow: 15 +--- + +# Канал QA + +`qa-channel` — це вбудований синтетичний транспорт повідомлень для автоматизованого QA OpenClaw. + +Це не production-канал. Він існує, щоб задіяти ту саму межу плагіна каналу, +яку використовують реальні транспорти, водночас зберігаючи стан детермінованим +і повністю доступним для перевірки. + +## Що він робить сьогодні + +- Граматика цілей класу Slack: + - `dm:` + - `channel:` + - `thread:/` +- Синтетична шина на базі HTTP для: + - інʼєкції вхідних повідомлень + - захоплення вихідних транскриптів + - створення потоків + - реакцій + - редагувань + - видалень + - дій пошуку та читання +- Вбудований запуск self-check на стороні хоста, який записує звіт Markdown + +## Конфігурація + +```json +{ + "channels": { + "qa-channel": { + "baseUrl": "http://127.0.0.1:43123", + "botUserId": "openclaw", + "botDisplayName": "OpenClaw QA", + "allowFrom": ["*"], + "pollTimeoutMs": 1000 + } + } +} +``` + +Підтримувані ключі облікового запису: + +- `baseUrl` +- `botUserId` +- `botDisplayName` +- `pollTimeoutMs` +- `allowFrom` +- `defaultTo` +- `actions.messages` +- `actions.reactions` +- `actions.search` +- `actions.threads` + +## Runner + +Поточний вертикальний зріз: + +```bash +pnpm qa:e2e +``` + +Тепер це маршрутизується через вбудоване розширення `qa-lab`. Воно запускає +внутрішньорепозиторну шину QA, завантажує вбудований runtime-зріз +`qa-channel`, виконує детермінований self-check і записує звіт Markdown у +`.artifacts/qa-e2e/`. + +Приватний UI налагоджувача: + +```bash +pnpm qa:lab:build +pnpm openclaw qa ui +``` + +Повний набір QA із прив’язкою до репозиторію: + +```bash +pnpm openclaw qa suite +``` + +Це запускає приватний налагоджувач QA за локальною URL-адресою, окремо від +постачуваного пакета Control UI. + +## Область застосування + +Поточна область застосування навмисно вузька: + +- шина + транспорт плагіна +- граматика маршрутизації потоків +- дії з повідомленнями, що належать каналу +- звітність у Markdown + +Подальша робота додасть: + +- Dockerized оркестрацію OpenClaw +- виконання матриці provider/model +- багатше виявлення сценаріїв +- пізніше — оркестрацію, нативну для OpenClaw diff --git a/docs/uk/concepts/qa-e2e-automation.md b/docs/uk/concepts/qa-e2e-automation.md new file mode 100644 index 000000000..dc88b7bf9 --- /dev/null +++ b/docs/uk/concepts/qa-e2e-automation.md @@ -0,0 +1,73 @@ +--- +read_when: + - Розширення qa-lab або qa-channel + - Додавання QA-сценаріїв, підкріплених репозиторієм + - Побудова реалістичнішої автоматизації QA навколо інформаційної панелі Gateway +summary: Форма приватної автоматизації QA для qa-lab, qa-channel, початково підготовлених сценаріїв і звітів за протоколом +title: Автоматизація QA E2E +x-i18n: + generated_at: "2026-04-05T22:36:39Z" + model: gpt-5.4 + provider: openai + source_hash: df35f353d5ab0e0432e6a828c82772f9a88edb41c20ec5037315b7ba310b28e6 + source_path: concepts/qa-e2e-automation.md + workflow: 15 +--- + +# Автоматизація QA E2E + +Приватний стек QA призначений для перевірки OpenClaw у реалістичніший, +орієнтований на канали спосіб, ніж це може зробити один модульний тест. + +Поточні складові: + +- `extensions/qa-channel`: синтетичний канал повідомлень із поверхнями для DM, каналів, тредів, + реакцій, редагування та видалення. +- `extensions/qa-lab`: інтерфейс налагодження та QA-шина для спостереження за транскриптом, + впровадження вхідних повідомлень і експорту звіту у форматі Markdown. +- `qa/`: початкові ресурси, підкріплені репозиторієм, для стартового завдання та базових QA- + сценаріїв. + +Довгострокова мета — двопанельний сайт QA: + +- Ліворуч: інформаційна панель Gateway (Control UI) з агентом. +- Праворуч: QA Lab, що показує транскрипт у стилі Slack і план сценарію. + +Це дає оператору або циклу автоматизації змогу поставити агенту місію QA, спостерігати +реальну поведінку каналу та фіксувати, що спрацювало, що не спрацювало або що лишилося заблокованим. + +## Початкові дані, підкріплені репозиторієм + +Початкові ресурси зберігаються в `qa/`: + +- `qa/QA_KICKOFF_TASK.md` +- `qa/seed-scenarios.json` + +Їх навмисно зберігають у git, щоб план QA був видимий і людям, і +агенту. Базовий список має залишатися достатньо широким, щоб охоплювати: + +- чат у DM і каналах +- поведінку тредів +- життєвий цикл дій із повідомленнями +- зворотні виклики cron +- відтворення з пам’яті +- перемикання моделей +- передавання підзадачі субагенту +- читання репозиторію та документації +- одне невелике завдання зі збірки, наприклад Lobster Invaders + +## Звітування + +`qa-lab` експортує звіт за протоколом у форматі Markdown на основі спостережуваної часової шкали шини. +Звіт має відповідати на такі запитання: + +- Що спрацювало +- Що не спрацювало +- Що лишилося заблокованим +- Які сценарії для подальшого опрацювання варто додати + +## Пов’язана документація + +- [Тестування](/uk/help/testing) +- [QA Channel](/channels/qa-channel) +- [Інформаційна панель](/web/dashboard) diff --git a/docs/uk/help/debugging.md b/docs/uk/help/debugging.md index 506f2ff57..498b4efe8 100644 --- a/docs/uk/help/debugging.md +++ b/docs/uk/help/debugging.md @@ -1,15 +1,15 @@ --- read_when: - - Вам потрібно перевірити сирий вивід моделі на витік reasoning + - Вам потрібно перевірити сирий вивід моделі на витік міркувань - Ви хочете запускати Gateway у режимі watch під час ітерацій - Вам потрібен відтворюваний робочий процес налагодження -summary: 'Інструменти налагодження: режим watch, сирі потоки моделі та трасування витоку reasoning' +summary: 'Інструменти налагодження: режим watch, сирі потоки моделі та відстеження витоку міркувань' title: Налагодження x-i18n: - generated_at: "2026-04-05T18:05:26Z" + generated_at: "2026-04-05T22:36:52Z" model: gpt-5.4 provider: openai - source_hash: f90d944ecc2e846ca0b26a162126ceefb3a3c6cf065c99b731359ec79d4289e3 + source_hash: 4bc72e8d6cad3a1acaad066f381c82309583fabf304c589e63885f2685dc704e source_path: help/debugging.md workflow: 15 --- @@ -17,13 +17,13 @@ x-i18n: # Налагодження Ця сторінка описує допоміжні засоби налагодження для потокового виводу, особливо коли -провайдер змішує reasoning зі звичайним текстом. +провайдер змішує міркування зі звичайним текстом. -## Перевизначення runtime для налагодження +## Перевизначення налагодження під час виконання -Використовуйте `/debug` у чаті, щоб задавати перевизначення config **лише для runtime** (у пам’яті, не на диску). -`/debug` типово вимкнено; увімкніть його через `commands.debug: true`. -Це зручно, коли потрібно перемкнути малопомітні налаштування без редагування `openclaw.json`. +Використовуйте `/debug` у чаті, щоб задавати перевизначення конфігурації **лише на час виконання** (у пам’яті, не на диску). +`/debug` вимкнено за замовчуванням; увімкніть його за допомогою `commands.debug: true`. +Це зручно, коли потрібно перемкнути маловідомі налаштування без редагування `openclaw.json`. Приклади: @@ -34,42 +34,43 @@ x-i18n: /debug reset ``` -`/debug reset` очищає всі перевизначення і повертає до config на диску. +`/debug reset` очищує всі перевизначення та повертає конфігурацію з диска. ## Режим watch для Gateway -Для швидких ітерацій запускайте gateway під файловим watcher: +Для швидких ітерацій запускайте gateway під наглядом засобу відстеження файлів: ```bash pnpm gateway:watch ``` -Це відповідає: +Це відповідає такому: ```bash node scripts/watch-node.mjs gateway --force ``` -Watcher перезапускається на файлах, важливих для збірки, у `src/`, вихідних файлах extension, -метаданих extension `package.json` і `openclaw.plugin.json`, `tsconfig.json`, -`package.json` і `tsdown.config.ts`. Зміни в метаданих extension перезапускають -gateway без примусового `tsdown` rebuild; зміни у вихідних файлах і config, як і раніше, +Засіб відстеження перезапускається при змінах у важливих для збірки файлах у `src/`, вихідних файлах розширень, +метаданих розширень `package.json` і `openclaw.plugin.json`, `tsconfig.json`, +`package.json` і `tsdown.config.ts`. Зміни в метаданих розширень перезапускають +gateway без примусового перебудування `tsdown`; зміни у вихідних файлах і конфігурації, як і раніше, спочатку перебудовують `dist`. -Додавайте будь-які прапорці CLI для gateway після `gateway:watch`, і вони передаватимуться -при кожному перезапуску. +Додайте будь-які прапорці CLI для gateway після `gateway:watch`, і вони передаватимуться під час +кожного перезапуску. Повторний запуск тієї самої команди watch для того самого репозиторію/набору прапорців тепер +замінює старіший засіб відстеження, замість того щоб залишати дубльовані батьківські процеси спостерігача. -## Dev-профіль і dev gateway (`--dev`) +## Профіль dev + dev gateway (--dev) -Використовуйте dev-профіль, щоб ізолювати стан і підняти безпечну тимчасову конфігурацію для +Використовуйте профіль dev, щоб ізолювати стан і підняти безпечне, тимчасове середовище для налагодження. Існує **два** прапорці `--dev`: - **Глобальний `--dev` (профіль):** ізолює стан у `~/.openclaw-dev` і - типово встановлює порт gateway на `19001` (похідні порти зсуваються разом із ним). -- **`gateway --dev`: вказує Gateway автоматично створювати типові config + - workspace**, якщо їх немає (і пропускати `BOOTSTRAP.md`). + за замовчуванням встановлює порт gateway на `19001` (похідні порти зміщуються разом із ним). +- **`gateway --dev`:** вказує Gateway автоматично створити типову конфігурацію + + робочу область, якщо вони відсутні (і пропустити BOOTSTRAP.md). -Рекомендований процес (dev profile + dev bootstrap): +Рекомендований процес (профіль dev + dev bootstrap): ```bash pnpm gateway:dev @@ -84,16 +85,16 @@ OPENCLAW_PROFILE=dev openclaw tui - `OPENCLAW_PROFILE=dev` - `OPENCLAW_STATE_DIR=~/.openclaw-dev` - `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json` - - `OPENCLAW_GATEWAY_PORT=19001` (browser/canvas зсуваються відповідно) + - `OPENCLAW_GATEWAY_PORT=19001` (порти browser/canvas відповідно зміщуються) 2. **Dev bootstrap** (`gateway --dev`) - - Записує мінімальний config, якщо його немає (`gateway.mode=local`, bind loopback). - - Встановлює `agent.workspace` на dev workspace. - - Встановлює `agent.skipBootstrap=true` (без `BOOTSTRAP.md`). - - Заповнює файли workspace, якщо їх немає: + - Записує мінімальну конфігурацію, якщо її немає (`gateway.mode=local`, прив’язка до loopback). + - Встановлює `agent.workspace` на dev-робочу область. + - Встановлює `agent.skipBootstrap=true` (без BOOTSTRAP.md). + - Ініціалізує файли робочої області, якщо їх немає: `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`. - - Типова identity: **C3‑PO** (protocol droid). - - Пропускає channel providers у dev mode (`OPENCLAW_SKIP_CHANNELS=1`). + - Типова ідентичність: **C3‑PO** (протокольний дроїд). + - Пропускає провайдери каналів у режимі dev (`OPENCLAW_SKIP_CHANNELS=1`). Процес скидання (чистий старт): @@ -101,17 +102,17 @@ OPENCLAW_PROFILE=dev openclaw tui pnpm gateway:dev:reset ``` -Примітка: `--dev` — це **глобальний** прапорець профілю, і деякі runners його перехоплюють. -Якщо потрібно вказати його явно, використовуйте форму через env var: +Примітка: `--dev` — це **глобальний** прапорець профілю, і деякі засоби запуску його поглинають. +Якщо потрібно вказати його явно, використовуйте форму зі змінною середовища: ```bash OPENCLAW_PROFILE=dev openclaw gateway --dev --reset ``` -`--reset` очищає config, credentials, sessions і dev workspace (із використанням -`trash`, а не `rm`), а потім заново створює типову dev-конфігурацію. +`--reset` очищує конфігурацію, облікові дані, сесії та dev-робочу область (з використанням +`trash`, а не `rm`), а потім заново створює типове dev-середовище. -Порада: якщо вже працює не-dev gateway (launchd/systemd), спочатку зупиніть його: +Порада: якщо вже запущено gateway не в режимі dev (launchd/systemd), спочатку зупиніть його: ```bash openclaw gateway stop @@ -119,9 +120,9 @@ openclaw gateway stop ## Логування сирого потоку (OpenClaw) -OpenClaw може логувати **сирий потік асистента** до будь-якої фільтрації/форматування. -Це найкращий спосіб побачити, чи reasoning надходить як звичайні текстові delta -(або як окремі thinking blocks). +OpenClaw може журналювати **сирий потік помічника** до будь-якої фільтрації/форматування. +Це найкращий спосіб побачити, чи надходять міркування як звичайні текстові дельти +(або як окремі блоки thinking). Увімкнення через CLI: @@ -135,7 +136,7 @@ pnpm gateway:watch --raw-stream pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl ``` -Еквівалентні env vars: +Еквівалентні змінні середовища: ```bash OPENCLAW_RAW_STREAM=1 @@ -146,10 +147,10 @@ OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl `~/.openclaw/logs/raw-stream.jsonl` -## Логування сирих chunks (pi-mono) +## Логування сирих чанків (pi-mono) -Щоб захоплювати **сирі chunks OpenAI-compat** до того, як вони розбиратимуться на blocks, -pi-mono надає окремий logger: +Щоб захопити **сирі OpenAI-сумісні чанки** до того, як вони буде розібрано на блоки, +pi-mono надає окремий журналювальник: ```bash PI_RAW_STREAM=1 @@ -165,11 +166,11 @@ PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl `~/.pi-mono/logs/raw-openai-completions.jsonl` -> Примітка: це виводиться лише процесами, які використовують провайдера -> `openai-completions` з pi-mono. +> Примітка: це виводиться лише процесами, які використовують провайдер +> `openai-completions` у pi-mono. ## Примітки щодо безпеки -- Сирі логи потоку можуть містити повні prompts, вивід інструментів і дані користувача. -- Зберігайте логи локально та видаляйте їх після налагодження. -- Якщо ділитеся логами, спочатку приберіть секрети та PII. +- Журнали сирого потоку можуть містити повні запити, вивід інструментів і дані користувача. +- Зберігайте журнали локально та видаляйте їх після налагодження. +- Якщо ви ділитеся журналами, спочатку очистьте з них секрети та персональні дані. diff --git a/docs/uk/plugins/architecture.md b/docs/uk/plugins/architecture.md index 8723da881..d01cb2c1c 100644 --- a/docs/uk/plugins/architecture.md +++ b/docs/uk/plugins/architecture.md @@ -1,182 +1,183 @@ --- read_when: - - Створення або налагодження нативних plugin OpenClaw - - Розуміння моделі можливостей plugin або меж володіння - - Робота над конвеєром завантаження plugin або реєстром - - Реалізація runtime-хуків провайдера або channel plugins + - Створення або налагодження нативних плагінів OpenClaw + - Розуміння моделі можливостей плагінів або меж володіння + - Робота над конвеєром завантаження плагінів або реєстром + - Реалізація runtime-хуків постачальників або канальних плагінів sidebarTitle: Internals -summary: 'Внутрішні компоненти plugin: модель можливостей, межі володіння, контракти, конвеєр завантаження та допоміжні засоби runtime' -title: Внутрішні компоненти Plugin +summary: 'Внутрішні механізми плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби часу виконання' +title: Внутрішні механізми плагінів x-i18n: - generated_at: "2026-04-05T18:52:03Z" + generated_at: "2026-04-05T22:50:55Z" model: gpt-5.4 provider: openai - source_hash: 70424e2745e6e289aa2e7ff899d33bea4b04f5c18bd3f73de38287f788bd939b + source_hash: d6e53a71b18d12cde81acac040c2110693dd2586b8888ff6104467ddd81ce22e source_path: plugins/architecture.md workflow: 15 --- -# Внутрішні компоненти Plugin +# Внутрішні механізми плагінів - Це **довідник з глибокої архітектури**. Практичні посібники дивіться тут: - - [Встановлення та використання 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 реєстрації + Це **довідник із глибокої архітектури**. Практичні посібники див. тут: + - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник користувача + - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний посібник зі створення плагіна + - [Канальні плагіни](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями + - [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) — створення постачальника моделей + - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпорту та API реєстрації -Ця сторінка описує внутрішню архітектуру системи plugin OpenClaw. +Ця сторінка описує внутрішню архітектуру системи плагінів OpenClaw. ## Публічна модель можливостей -Можливості — це публічна модель **нативних plugin** всередині OpenClaw. Кожен -нативний plugin OpenClaw реєструється для одного або кількох типів можливостей: +Можливості — це публічна модель **нативних плагінів** всередині OpenClaw. Кожен +нативний плагін OpenClaw реєструється для одного або кількох типів можливостей: -| Можливість | Метод реєстрації | Приклади plugin | -| --------------------- | ---------------------------------------------- | ----------------------------------- | -| Текстовий inference | `api.registerProvider(...)` | `openai`, `anthropic` | -| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | -| Транскрипція в realtime | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | -| Голос у realtime | `api.registerRealtimeVoiceProvider(...)` | `openai` | -| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | -| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | -| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | -| Отримання вебданих | `api.registerWebFetchProvider(...)` | `firecrawl` | -| Вебпошук | `api.registerWebSearchProvider(...)` | `google` | -| Канал / повідомлення | `api.registerChannel(...)` | `msteams`, `matrix` | +| Можливість | Метод реєстрації | Приклади плагінів | +| --------------------- | ----------------------------------------------- | ------------------------------------ | +| Текстовий інференс | `api.registerProvider(...)` | `openai`, `anthropic` | +| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` | +| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` | +| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` | +| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` | +| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` | +| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` | +| Веб-отримання | `api.registerWebFetchProvider(...)` | `firecrawl` | +| Веб-пошук | `api.registerWebSearchProvider(...)` | `google` | +| Канал / повідомлення | `api.registerChannel(...)` | `msteams`, `matrix` | -Plugin, який не реєструє жодної можливості, але надає hooks, tools або -services, є **застарілим plugin лише з hooks**. Цей шаблон і далі повністю підтримується. +Плагін, який реєструє нуль можливостей, але надає hooks, інструменти або +сервіси, є **застарілим hook-only** плагіном. Цей шаблон досі повністю підтримується. ### Позиція щодо зовнішньої сумісності -Модель можливостей уже впроваджена в core і сьогодні використовується -вбудованими/нативними plugins, але сумісність із зовнішніми plugins усе ще -потребує вищої планки, ніж "це експортується, отже це вже зафіксовано." +Модель можливостей уже впроваджена в core і використовується в комплектних/нативних плагінах +сьогодні, але сумісність із зовнішніми плагінами все ще потребує жорсткішого критерію, ніж «це +експортується, отже воно заморожене». Поточні рекомендації: -- **наявні зовнішні plugins:** зберігайте працездатність інтеграцій на основі hooks; вважайте - це базовим рівнем сумісності -- **нові вбудовані/нативні plugins:** віддавайте перевагу явній реєстрації можливостей, а не - vendor-специфічним прямим зверненням або новим дизайнам лише з hooks -- **зовнішні plugins, що переходять на реєстрацію можливостей:** це дозволено, але - capability-специфічні допоміжні поверхні слід вважати такими, що еволюціонують, якщо в документації контракт явно не позначено як стабільний +- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі hooks; розглядайте + це як базовий рівень сумісності +- **нові комплектні/нативні плагіни:** віддавайте перевагу явній реєстрації можливостей замість + специфічних для постачальника звернень усередину або нових hook-only дизайнів +- **зовнішні плагіни, що переходять на реєстрацію можливостей:** дозволено, але + вважайте специфічні допоміжні поверхні можливостей такими, що еволюціонують, якщо в документації + контракт явно не позначений як стабільний Практичне правило: -- API реєстрації можливостей — це бажаний напрямок -- застарілі hooks залишаються найбезпечнішим шляхом без зламів для зовнішніх plugins під час +- API реєстрації можливостей — це цільовий напрямок +- застарілі hooks залишаються найбезпечнішим шляхом без поломок для зовнішніх плагінів під час переходу -- не всі експортовані допоміжні subpaths однакові; віддавайте перевагу вузькому задокументованому - контракту, а не випадковим допоміжним експортам +- не всі експортовані допоміжні підшляхи рівнозначні; надавайте перевагу вузькому документованому + контракту, а не випадковим helper-експортам -### Форми plugin +### Форми плагінів -OpenClaw класифікує кожен завантажений plugin за формою на основі його фактичної +OpenClaw класифікує кожен завантажений плагін за формою на основі його фактичної поведінки реєстрації (а не лише статичних метаданих): - **plain-capability** -- реєструє рівно один тип можливості (наприклад, - plugin лише для провайдера, як-от `mistral`) + плагін лише постачальника, як-от `mistral`) - **hybrid-capability** -- реєструє кілька типів можливостей (наприклад, - `openai` володіє текстовим inference, мовленням, розумінням медіа та - генерацією зображень) + `openai` володіє текстовим інференсом, мовленням, розумінням медіа та генерацією + зображень) - **hook-only** -- реєструє лише hooks (типізовані або custom), без можливостей, - tools, commands чи services -- **non-capability** -- реєструє tools, commands, services або routes, але не можливості + інструментів, команд чи сервісів +- **non-capability** -- реєструє інструменти, команди, сервіси або маршрути, але не можливості -Використовуйте `openclaw plugins inspect `, щоб побачити форму plugin і -розподіл можливостей. Докладніше див. у [довіднику CLI](/cli/plugins#inspect). +Використовуйте `openclaw plugins inspect `, щоб побачити форму плагіна та +розбивку можливостей. Докладніше див. [довідку CLI](/cli/plugins#inspect). ### Застарілі hooks -Hook `before_agent_start` залишається підтримуваним як шлях сумісності для -plugin лише з hooks. Реальні застарілі plugins усе ще залежать від нього. +Хук `before_agent_start` залишається підтримуваним як шлях сумісності для +hook-only плагінів. Застарілі реальні плагіни все ще залежать від нього. Напрямок: -- зберігати його працездатним +- зберігати його працездатність - документувати його як застарілий -- для перевизначення моделі/провайдера віддавати перевагу `before_model_resolve` -- для мутації prompt віддавати перевагу `before_prompt_build` -- видаляти лише після зниження реального використання та після того, як покриття fixture підтвердить безпеку міграції +- для перевизначення моделі/постачальника надавати перевагу `before_model_resolve` +- для модифікації prompt надавати перевагу `before_prompt_build` +- видаляти лише після зменшення реального використання і коли покриття fixture підтвердить безпеку міграції ### Сигнали сумісності Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете побачити -один із цих маркерів: +одну з таких міток: -| Сигнал | Значення | -| -------------------------- | ----------------------------------------------------------- | -| **config valid** | Конфігурація успішно парситься, і plugins коректно визначаються | -| **compatibility advisory** | Plugin використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | -| **legacy warning** | Plugin використовує `before_agent_start`, який вважається застарілим | -| **hard error** | Конфігурація недійсна або plugin не вдалося завантажити | +| Сигнал | Значення | +| ------------------------- | ------------------------------------------------------------ | +| **config valid** | Конфігурація коректно парситься, і плагіни успішно визначаються | +| **compatibility advisory** | Плагін використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) | +| **legacy warning** | Плагін використовує `before_agent_start`, який застарів | +| **hard error** | Конфігурація некоректна або плагін не вдалося завантажити | -Ні `hook-only`, ні `before_agent_start` не зламають ваш plugin сьогодні -- +Ані `hook-only`, ані `before_agent_start` сьогодні не зламають ваш плагін -- `hook-only` є рекомендаційним сигналом, а `before_agent_start` лише спричиняє попередження. Ці -сигнали також з’являються в `openclaw status --all` і `openclaw plugins doctor`. +сигнали також відображаються в `openclaw status --all` і `openclaw plugins doctor`. ## Огляд архітектури -Система plugin OpenClaw має чотири шари: +Система плагінів OpenClaw має чотири шари: 1. **Маніфест + виявлення** - OpenClaw знаходить потенційні plugins у налаштованих шляхах, коренях workspace, - глобальних коренях extension і серед вбудованих extension. Виявлення спочатку читає нативні + OpenClaw знаходить кандидатів у плагіни у налаштованих шляхах, коренях workspace, + глобальних коренях розширень і комплектних розширеннях. Виявлення спочатку читає нативні маніфести `openclaw.plugin.json` разом із підтримуваними маніфестами bundle. 2. **Увімкнення + валідація** - Core вирішує, чи є знайдений plugin увімкненим, вимкненим, заблокованим або - вибраним для ексклюзивного слота, наприклад memory. -3. **Runtime-завантаження** - Нативні plugins OpenClaw завантажуються in-process через jiti і реєструють - можливості в центральному реєстрі. Сумісні bundles нормалізуються в записи - реєстру без імпорту runtime-коду. -4. **Використання поверхонь** - Решта OpenClaw читає реєстр, щоб надавати tools, channels, налаштування provider, - hooks, HTTP routes, CLI commands і services. + Core вирішує, чи знайдений плагін увімкнений, вимкнений, заблокований або + вибраний для ексклюзивного слота, такого як пам’ять. +3. **Завантаження часу виконання** + Нативні плагіни OpenClaw завантажуються в межах процесу через jiti та реєструють + можливості в центральному реєстрі. Сумісні bundle нормалізуються в + записи реєстру без імпорту коду часу виконання. +4. **Споживання поверхонь** + Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування постачальників, + hooks, HTTP-маршрути, CLI-команди та сервіси. -Для CLI plugin зокрема, виявлення кореневих команд розділено на дві фази: +Зокрема для CLI плагінів, виявлення кореневих команд поділено на дві фази: -- метадані під час парсингу походять із `registerCli(..., { descriptors: [...] })` -- реальний модуль CLI plugin може залишатися lazy і реєструватися лише під час першого виклику +- метадані під час парсингу надходять із `registerCli(..., { descriptors: [...] })` +- реальний модуль CLI плагіна може залишатися lazy і реєструватися при першому виклику -Це дозволяє утримувати код CLI, що належить plugin, всередині plugin, при цьому OpenClaw -може резервувати імена кореневих команд до початку парсингу. +Це дозволяє зберігати CLI-код, що належить плагіну, всередині плагіна, водночас даючи OpenClaw +можливість резервувати імена кореневих команд до парсингу. -Важлива межа проєктування: +Важлива межа дизайну: -- виявлення + валідація config мають працювати на основі **метаданих маніфесту/схеми** - без виконання коду plugin -- нативна runtime-поведінка походить із шляху `register(api)` модуля plugin +- виявлення + валідація конфігурації мають працювати з **метаданих маніфесту/схеми** + без виконання коду плагіна +- нативна поведінка часу виконання надходить зі шляху `register(api)` модуля плагіна -Такий поділ дозволяє OpenClaw перевіряти config, пояснювати відсутні/вимкнені plugins і -будувати підказки UI/схеми до повної активації runtime. +Такий поділ дозволяє OpenClaw перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни та +будувати підказки для UI/схеми ще до повної активації runtime. -### Channel plugins і спільний tool повідомлень +### Канальні плагіни та спільний інструмент повідомлень -Channel plugins не повинні реєструвати окремий tool send/edit/react для -звичайних дій у чаті. OpenClaw підтримує один спільний core tool `message`, а -channel plugins володіють channel-специфічним виявленням і виконанням за ним. +Канальним плагінам не потрібно реєструвати окремий інструмент send/edit/react для +звичайних чат-дій. OpenClaw зберігає один спільний інструмент `message` у core, а +канальні плагіни володіють специфічним для каналу виявленням і виконанням за ним. Поточна межа така: -- core володіє спільним host tool `message`, підключенням prompt, - обліком session/thread і диспетчеризацією виконання -- channel plugins володіють виявленням дій в межах scope, виявленням можливостей - і будь-якими channel-специфічними фрагментами schema -- channel plugins володіють provider-специфічною граматикою conversation session, зокрема - тим, як ідентифікатори conversation кодують ідентифікатори thread або успадковуються від батьківських conversations -- channel plugins виконують фінальну дію через свій action adapter +- core володіє хостом спільного інструмента `message`, підключенням до prompt, веденням + сесій/потоків і диспетчеризацією виконання +- канальні плагіни володіють виявленням дій у межах scope, виявленням можливостей і будь-якими + специфічними для каналу фрагментами схеми +- канальні плагіни володіють специфічною для постачальника граматикою сесійної розмови, наприклад, + тим, як conversation id кодують thread id або успадковуються від батьківських розмов +- канальні плагіни виконують фінальну дію через свій адаптер дій -Для channel plugins поверхнею SDK є -`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик -виявлення дозволяє plugin повертати видимі дії, можливості та внески до schema -разом, щоб ці частини не розходилися між собою. +Для канальних плагінів поверхнею SDK є +`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик виявлення +дозволяє плагіну разом повертати видимі дії, можливості та внески до схеми, +щоб ці частини не розходилися. -Core передає runtime scope в цей крок виявлення. Важливі поля включають: +Core передає runtime scope на цей етап виявлення. Важливі поля включають: - `accountId` - `currentChannelId` @@ -187,121 +188,122 @@ Core передає runtime scope в цей крок виявлення. Важ - `agentId` - довірений вхідний `requesterSenderId` -Це важливо для context-sensitive plugins. Канал може приховувати або показувати -дії повідомлень залежно від активного облікового запису, поточної кімнати/thread/message або -довіреної ідентичності запитувача без жорсткого channel-специфічного branching у core tool `message`. +Це важливо для плагінів, чутливих до контексту. Канал може приховувати або показувати +дії повідомлень залежно від активного облікового запису, поточної кімнати/потоку/повідомлення або +довіреної ідентичності запитувача без жорстко закодованих каналоспецифічних гілок у +core-інструменті `message`. -Саме тому зміни маршрутизації embedded-runner усе ще є роботою plugin: runner -відповідає за передавання поточної ідентичності chat/session до межі -виявлення plugin, щоб спільний tool `message` показував правильну channel-власну -поверхню для поточного кроку. +Саме тому зміни маршрутизації embedded-runner і далі залишаються роботою плагіна: runner +відповідає за передавання поточної ідентичності чату/сесії в межу виявлення плагіна, щоб +спільний інструмент `message` показував правильну поверхню, що належить каналу, для +поточного ходу. -Для channel-власних допоміжних засобів виконання вбудовані plugins повинні -зберігати runtime виконання всередині своїх власних модулів extension. Core більше не володіє Discord, -Slack, Telegram або WhatsApp runtime дій повідомлень у `src/agents/tools`. -Ми не публікуємо окремі subpaths `plugin-sdk/*-action-runtime`, а вбудовані -plugins повинні імпортувати власний локальний runtime-код безпосередньо зі своїх -модулів extension. +Для допоміжних засобів виконання, що належать каналу, комплектні плагіни мають зберігати runtime +виконання всередині власних модулів розширення. Core більше не володіє runtime +дій повідомлень Discord, Slack, Telegram або WhatsApp у `src/agents/tools`. +Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, і комплектні +плагіни мають напряму імпортувати власний локальний runtime-код зі своїх +модулів розширення. -Та сама межа застосовується до provider-іменованих швів SDK загалом: core не повинен -імпортувати channel-специфічні допоміжні barrels для Slack, Discord, Signal, -WhatsApp або подібних extension. Якщо core потрібна певна поведінка, або -використовуйте власний barrel `api.ts` / `runtime-api.ts` вбудованого plugin, або -підніміть цю потребу до вузької загальної можливості в спільному SDK. +Та сама межа застосовується і до SDK-швів, названих на честь постачальника, загалом: core не повинен +імпортувати специфічні для каналу convenience barrel для Slack, Discord, Signal, +WhatsApp або подібних розширень. Якщо core потрібна певна поведінка, або використовуйте +власний barrel `api.ts` / `runtime-api.ts` комплектного плагіна, або підніміть потребу +до вузької узагальненої можливості у спільному SDK. -Зокрема для poll існує два шляхи виконання: +Зокрема для опитувань існують два шляхи виконання: -- `outbound.sendPoll` — спільна базова лінія для каналів, які вписуються в загальну модель - poll -- `actions.handleAction("poll")` — бажаний шлях для channel-специфічної семантики - poll або додаткових параметрів poll +- `outbound.sendPoll` — це спільна базова лінія для каналів, які відповідають загальній + моделі опитувань +- `actions.handleAction("poll")` — це бажаний шлях для специфічної для каналу + семантики опитувань або додаткових параметрів опитувань -Тепер core відкладає спільний парсинг poll до моменту, коли plugin-диспетчеризація poll -відхиляє дію, щоб handlers poll, що належать plugin, могли приймати channel-специфічні -поля poll без блокування з боку загального parser poll. +Тепер core відкладає спільний парсинг опитувань до того моменту, коли диспетчеризація опитувань плагіна +відхилить дію, щоб обробники опитувань, що належать плагіну, могли приймати специфічні для каналу поля +опитувань і не блокувалися спочатку узагальненим парсером опитувань. Повну послідовність запуску див. у [Конвеєрі завантаження](#load-pipeline). ## Модель володіння можливостями -OpenClaw розглядає нативний plugin як межу володіння для **компанії** або -**функції**, а не як набір несумісних між собою інтеграцій. +OpenClaw розглядає нативний плагін як межу володіння для **компанії** або +**функції**, а не як набір не пов’язаних інтеграцій. Це означає: -- plugin компанії зазвичай повинен володіти всіма surfaces цієї компанії, орієнтованими на OpenClaw -- plugin функції зазвичай повинен володіти повною surface запроваджуваної ним функції -- channels повинні використовувати спільні можливості core замість випадкового повторного - впровадження provider-поведінки +- плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, що належать цій компанії +- плагін функції зазвичай має володіти повною поверхнею функції, яку він додає +- канали мають споживати спільні можливості core замість того, щоб довільно заново реалізовувати + поведінку постачальників Приклади: -- вбудований plugin `openai` володіє поведінкою провайдера моделей OpenAI і - поведінкою OpenAI для speech + realtime-voice + media-understanding + image-generation -- вбудований plugin `elevenlabs` володіє поведінкою мовлення ElevenLabs -- вбудований plugin `microsoft` володіє поведінкою мовлення Microsoft -- вбудований plugin `google` володіє поведінкою провайдера моделей Google плюс - поведінкою Google для media-understanding + image-generation + web-search -- вбудований plugin `firecrawl` володіє поведінкою web-fetch Firecrawl -- вбудовані plugins `minimax`, `mistral`, `moonshot` і `zai` володіють своїми - backend для media-understanding -- plugin `voice-call` є plugin функції: він володіє transport дзвінків, tools, - CLI, routes і bridgеing медіапотоків Twilio, але використовує спільні можливості speech - плюс realtime-transcription і realtime-voice замість прямого імпорту vendor plugins +- комплектний плагін `openai` володіє поведінкою постачальника моделей OpenAI та поведінкою OpenAI + для мовлення + голосу реального часу + розуміння медіа + генерації зображень +- комплектний плагін `elevenlabs` володіє поведінкою ElevenLabs для мовлення +- комплектний плагін `microsoft` володіє поведінкою Microsoft для мовлення +- комплектний плагін `google` володіє поведінкою постачальника моделей Google, а також поведінкою Google + для розуміння медіа + генерації зображень + веб-пошуку +- комплектний плагін `firecrawl` володіє поведінкою Firecrawl для веб-отримання +- комплектні плагіни `minimax`, `mistral`, `moonshot` і `zai` володіють своїми + бекендами розуміння медіа +- плагін `voice-call` є плагіном функції: він володіє транспортом викликів, інструментами, + CLI, маршрутами та Twilio media-stream bridging, але споживає спільні можливості мовлення, + а також транскрипції й голосу реального часу замість прямого імпорту плагінів постачальників Бажаний кінцевий стан: -- OpenAI живе в одному plugin, навіть якщо охоплює текстові моделі, мовлення, зображення і +- OpenAI живе в одному плагіні, навіть якщо він охоплює текстові моделі, мовлення, зображення та майбутнє відео -- інший vendor може робити те саме для своєї власної surface -- channels не зважають на те, який plugin vendor володіє provider; вони використовують - спільний capability-контракт, який надає core +- інший постачальник може так само охоплювати власну поверхню в одному плагіні +- каналам неважливо, який плагін постачальника володіє провайдером; вони споживають + спільний контракт можливостей, який надає core Ось ключова відмінність: - **plugin** = межа володіння -- **capability** = контракт core, який кілька plugins можуть реалізовувати або використовувати +- **capability** = контракт core, який кілька плагінів можуть реалізовувати або споживати -Отже, якщо OpenClaw додає новий домен, наприклад відео, перше питання — -не "який provider має жорстко кодувати обробку відео?" Перше питання — -"який core-контракт можливості відео?" Щойно такий контракт з’являється, -plugins vendor можуть реєструватися для нього, а channel/feature plugins можуть його використовувати. +Тож якщо OpenClaw додає нову доменну область, наприклад відео, перше питання не +«який постачальник має жорстко закодувати обробку відео?». Перше питання — +«який основний контракт можливості відео?». Щойно цей контракт існує, плагіни постачальників +можуть реєструватися для нього, а канальні/функціональні плагіни можуть його споживати. -Якщо можливості ще не існує, правильний крок зазвичай такий: +Якщо можливість ще не існує, правильним кроком зазвичай є: 1. визначити відсутню можливість у core -2. відкрити її через API/runtime plugin у типізованому вигляді -3. підключити channels/features до цієї можливості -4. дозволити plugins vendor реєструвати реалізації +2. відкрити її через API/runtime плагіна у типізований спосіб +3. підключити канали/функції до цієї можливості +4. дозволити плагінам постачальників реєструвати реалізації -Це зберігає явне володіння і водночас уникає поведінки core, яка залежить від -одного vendor або одноразового plugin-специфічного шляху коду. +Це зберігає явне володіння та водночас уникає поведінки core, яка залежить від +одного постачальника або одноразового специфічного для плагіна шляху коду. ### Шарування можливостей -Користуйтеся цією ментальною моделлю, коли вирішуєте, де має бути код: +Використовуйте таку ментальну модель, коли вирішуєте, де має бути код: -- **шар можливостей core**: спільна orchestration, policy, fallback, правила - злиття config, семантика доставки та типізовані контракти -- **шар plugin vendor**: vendor-специфічні API, auth, catalogs моделей, speech - synthesis, image generation, майбутні backend відео, endpoints usage -- **шар channel/feature plugin**: інтеграції Slack/Discord/voice-call тощо, - які використовують можливості core і представляють їх на surface +- **шар можливостей core**: спільна оркестрація, політика, fallback, правила + злиття конфігурації, семантика доставки та типізовані контракти +- **шар плагіна постачальника**: специфічні для постачальника API, auth, каталоги моделей, синтез + мовлення, генерація зображень, майбутні відеобекенди, endpoint-и використання +- **шар канального/функціонального плагіна**: інтеграція Slack/Discord/voice-call тощо, + яка споживає можливості core і подає їх на своїй поверхні Наприклад, TTS має таку форму: -- core володіє policy TTS під час відповіді, порядком fallback, prefs і доставкою в channels -- `openai`, `elevenlabs` і `microsoft` володіють реалізаціями synthesis -- `voice-call` використовує допоміжний засіб runtime TTS для telephony +- core володіє політикою TTS під час відповіді, порядком fallback, налаштуваннями та доставкою в канал +- `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу +- `voice-call` споживає допоміжний runtime TTS для телефонії -Той самий шаблон слід віддавати перевагу і для майбутніх можливостей. +Того ж шаблону слід дотримуватися і для майбутніх можливостей. -### Приклад company plugin з кількома можливостями +### Приклад багатоможливісного плагіна компанії -Plugin компанії повинен виглядати цілісно ззовні. Якщо OpenClaw має спільні -контракти для моделей, мовлення, транскрипції в realtime, голосу в realtime, розуміння медіа, -генерації зображень, генерації відео, web fetch і web search, vendor може -володіти всіма своїми surfaces в одному місці: +Плагін компанії має сприйматися цілісно ззовні. Якщо OpenClaw має спільні +контракти для моделей, мовлення, транскрипції реального часу, голосу реального часу, розуміння медіа, +генерації зображень, генерації відео, веб-отримання і веб-пошуку, +постачальник може володіти всіма своїми поверхнями в одному місці: ```ts import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry"; @@ -321,7 +323,7 @@ const plugin: OpenClawPluginDefinition = { api.registerSpeechProvider({ id: "exampleai", - // vendor speech config — directly implement the SpeechProviderPlugin interface + // vendor speech config — implement the SpeechProviderPlugin interface directly }); api.registerMediaUnderstandingProvider({ @@ -355,221 +357,223 @@ const plugin: OpenClawPluginDefinition = { export default plugin; ``` -Важливі не точні назви helpers. Важлива форма: +Важливі не точні назви helper-ів. Важлива форма: -- один plugin володіє surface vendor +- один плагін володіє поверхнею постачальника - core усе ще володіє контрактами можливостей -- channels і feature plugins використовують helpers `api.runtime.*`, а не vendor-код -- тести контрактів можуть перевіряти, що plugin зареєстрував можливості, якими +- канали й функціональні плагіни споживають helper-и `api.runtime.*`, а не код постачальника +- тести контрактів можуть перевіряти, що плагін зареєстрував ті можливості, якими він заявляє, що володіє ### Приклад можливості: розуміння відео -OpenClaw вже розглядає розуміння зображень/аудіо/відео як одну спільну +OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну можливість. Та сама модель володіння застосовується і тут: -1. core визначає контракт media-understanding -2. plugins vendor реєструють `describeImage`, `transcribeAudio` і +1. core визначає контракт розуміння медіа +2. плагіни постачальників реєструють `describeImage`, `transcribeAudio` та `describeVideo` за потреби -3. channels і feature plugins використовують спільну поведінку core замість - прямого підключення до vendor-коду +3. канали й функціональні плагіни споживають спільну поведінку core замість + прямого підключення до коду постачальника -Це запобігає вбудовуванню припущень одного провайдера про відео в core. Plugin володіє -surface vendor; core володіє capability-контрактом і поведінкою fallback. +Це дозволяє уникнути закладання припущень одного постачальника щодо відео в core. Плагін володіє +поверхнею постачальника; core володіє контрактом можливості та fallback-поведінкою. Генерація відео вже використовує ту саму послідовність: core володіє типізованим -capability-контрактом і runtime helper, а plugins vendor реєструють +контрактом можливості та runtime-helper-ом, а плагіни постачальників реєструють реалізації `api.registerVideoGenerationProvider(...)` для нього. -Потрібен конкретний контрольний список впровадження? Див. +Потрібен конкретний контрольний список упровадження? Див. [Capability Cookbook](/uk/plugins/architecture). -## Контракти та контроль +## Контракти та примусове дотримання -Поверхня API plugin навмисно типізована й централізована в +Поверхня API плагіна навмисно типізована й централізована в `OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та -runtime helpers, на які plugin може покладатися. +runtime-helper-и, на які плагін може покладатися. Чому це важливо: -- автори plugin отримують єдиний стабільний внутрішній стандарт -- core може відхиляти дублювання володіння, наприклад коли два plugins реєструють один і той самий - id provider -- під час запуску можна показувати діагностику, придатну до дій, для хибної реєстрації -- тести контрактів можуть забезпечувати володіння вбудованими plugins і запобігати тихому дрейфу +- автори плагінів отримують один стабільний внутрішній стандарт +- core може відхиляти дублювання володіння, наприклад якщо два плагіни реєструють той самий + provider id +- під час запуску можна показувати діагностику, придатну до дії, для некоректної реєстрації +- тести контрактів можуть забезпечувати володіння комплектними плагінами і запобігати тихому дрейфу -Є два шари контролю: +Є два шари примусового дотримання: -1. **контроль runtime-реєстрації** - Реєстр plugin перевіряє реєстрації під час завантаження plugins. Приклади: - дубльовані id provider, дубльовані id провайдерів мовлення та хибні - реєстрації породжують діагностику plugin замість невизначеної поведінки. +1. **примусове дотримання під час runtime-реєстрації** + Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Приклади: + дублікати provider id, дублікати id постачальників мовлення та некоректні + реєстрації породжують діагностику плагіна замість невизначеної поведінки. 2. **тести контрактів** - Вбудовані plugins фіксуються в реєстрах контрактів під час запусків тестів, щоб - OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для model - providers, speech providers, web search providers і володіння реєстрацією вбудованих компонентів. + Комплектні плагіни фіксуються в реєстрах контрактів під час прогону тестів, щоб + OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для + постачальників моделей, постачальників мовлення, постачальників веб-пошуку та володіння + комплектними реєстраціями. -Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який plugin -володіє якою surface. Це дозволяє core і channels композиційно працювати, бо -володіння оголошене, типізоване й перевіряється тестами, а не є неявним. +Практичний ефект полягає в тому, що OpenClaw наперед знає, який плагін якою +поверхнею володіє. Це дозволяє core і каналам безшовно компонуватися, тому що володіння +декларується, типізується і перевіряється тестами, а не є неявним. -### Що має належати контракту +### Що має входити до контракту -Хороші контракти plugin є: +Добрі контракти плагінів є: - типізованими -- малими -- capability-специфічними +- невеликими +- специфічними для можливості - такими, що належать core -- повторно використовуваними кількома plugins -- придатними до використання channels/features без знань про vendor +- придатними до повторного використання кількома плагінами +- придатними до споживання каналами/функціями без знання постачальника -Погані контракти plugin є: +Погані контракти плагінів — це: -- vendor-специфічною policy, прихованою в core -- одноразовими лазівками plugin, які обходять реєстр -- кодом channel, що напряму лізе у реалізацію vendor -- ad hoc runtime-об’єктами, які не є частиною `OpenClawPluginApi` або +- специфічна для постачальника політика, прихована в core +- одноразові escape hatch для плагіна, які оминають реєстр +- код каналу, що напряму звертається до реалізації постачальника +- довільні runtime-об’єкти, які не є частиною `OpenClawPluginApi` або `api.runtime` -Якщо сумніваєтеся, піднімайте рівень абстракції: спочатку визначте можливість, а -потім дозвольте plugins підключатися до неї. +Якщо сумніваєтеся, підніміть рівень абстракції: спочатку визначте можливість, а потім +дозвольте плагінам підключатися до неї. ## Модель виконання -Нативні plugins OpenClaw працюють **in-process** із Gateway. Вони не -ізольовані. Завантажений нативний plugin має ту саму межу довіри на рівні процесу, -що й код core. +Нативні плагіни OpenClaw працюють **у межах процесу** разом із Gateway. Вони не +ізольовані. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що й +код core. Наслідки: -- нативний plugin може реєструвати tools, network handlers, hooks і services -- помилка в нативному plugin може аварійно завершити роботу gateway або дестабілізувати його -- шкідливий нативний plugin еквівалентний довільному виконанню коду всередині +- нативний плагін може реєструвати інструменти, мережеві обробники, hooks і сервіси +- помилка в нативному плагіні може зламати або дестабілізувати gateway +- зловмисний нативний плагін еквівалентний довільному виконанню коду всередині процесу OpenClaw -Сумісні bundles безпечніші за замовчуванням, оскільки OpenClaw наразі розглядає їх -як metadata/content packs. У поточних релізах це здебільшого означає вбудовані +Сумісні bundle безпечніші за замовчуванням, тому що OpenClaw наразі розглядає їх +як metadata/content packs. У поточних релізах це здебільшого означає комплектні Skills. -Для невбудованих plugins використовуйте allowlists і явні шляхи install/load. Розглядайте -plugins workspace як код для часу розробки, а не як production-типові значення. +Використовуйте allowlist-и та явні шляхи встановлення/завантаження для некомплектних плагінів. Розглядайте +workspace-плагіни як код часу розробки, а не як виробничі значення за замовчуванням. -Для назв пакетів у workspace, що містять вбудовані plugins, зберігайте прив’язку plugin id у назві npm: -`@openclaw/` за замовчуванням або затверджений типізований suffix на кшталт +Для назв комплектних workspace-пакетів зберігайте plugin id прив’язаним до npm-імені: +`@openclaw/` за замовчуванням або затверджений типізований суфікс, як-от `-provider`, `-plugin`, `-speech`, `-sandbox` або `-media-understanding`, коли -пакет навмисно надає вужчу роль plugin. +пакет навмисно відкриває вужчу роль плагіна. Важлива примітка щодо довіри: -- `plugins.allow` довіряє **id plugin**, а не походженню джерела. -- Plugin workspace з тим самим id, що й вбудований plugin, навмисно затіняє - вбудовану копію, коли цей plugin workspace увімкнено/додано в allowlist. -- Це нормально і корисно для локальної розробки, тестування патчів і hotfix. +- `plugins.allow` довіряє **plugin id**, а не походженню джерела. +- Workspace-плагін з тим самим id, що й у комплектного плагіна, навмисно затіняє + комплектну копію, коли цей workspace-плагін увімкнено/додано до allowlist. +- Це нормально і корисно для локальної розробки, тестування патчів і hotfix-ів. ## Межа експорту -OpenClaw експортує можливості, а не зручні реалізаційні шари. +OpenClaw експортує можливості, а не зручності реалізації. -Реєстрацію можливостей слід залишати публічною. Неекспортовані допоміжні зручності слід обрізати: +Зберігайте публічною реєстрацію можливостей. Скорочуйте експорти helper-ів, які не є контрактом: -- допоміжні subpaths, специфічні для вбудованих plugins -- subpaths runtime plumbing, які не призначені бути публічним API -- vendor-специфічні convenience helpers -- helpers setup/onboarding, які є деталями реалізації +- підшляхи helper-ів, специфічні для комплектного плагіна +- підшляхи runtime plumbing, які не призначені бути публічним API +- специфічні для постачальника convenience helper-и +- helper-и налаштування/onboarding, які є деталями реалізації -Деякі допоміжні subpaths вбудованих plugins усе ще присутні в згенерованій карті -експорту SDK з міркувань сумісності та підтримки вбудованих plugins. Поточні приклади включають +Деякі підшляхи helper-ів комплектних плагінів усе ще залишаються в згенерованій мапі експорту SDK +для сумісності та супроводу комплектних плагінів. Поточні приклади включають `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і кілька швів `plugin-sdk/matrix*`. Розглядайте їх як -зарезервовані implementation-detail exports, а не як рекомендований шаблон SDK для -нових сторонніх plugins. +зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для +нових сторонніх плагінів. ## Конвеєр завантаження Під час запуску OpenClaw приблизно робить таке: -1. виявляє корені потенційних plugin -2. читає нативні або сумісні маніфести bundle та метадані package +1. виявляє корені кандидатів у плагіни +2. читає нативні або сумісні bundle-маніфести та метадані пакетів 3. відхиляє небезпечних кандидатів -4. нормалізує config plugin (`plugins.enabled`, `allow`, `deny`, `entries`, +4. нормалізує конфігурацію плагінів (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) 5. вирішує стан увімкнення для кожного кандидата -6. завантажує увімкнені нативні modules через jiti -7. викликає нативні hooks `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру plugin -8. відкриває реєстр для surfaces commands/runtime +6. завантажує увімкнені нативні модулі через jiti +7. викликає нативні hooks `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру плагінів +8. відкриває реєстр для поверхонь команд/runtime -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що з них присутнє (`def.register ?? def.activate`), і викликає в тій самій точці. Усі вбудовані plugins використовують `register`; для нових plugins віддавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що з них присутнє (`def.register ?? def.activate`), і викликає в тій самій точці. Усі комплектні плагіни використовують `register`; для нових плагінів надавайте перевагу `register`. -Перевірки безпеки виконуються **до** виконання runtime. Кандидати блокуються, -коли entry виходить за межі кореня plugin, шлях має права запису для всіх, або -власність шляху виглядає підозріло для невбудованих plugins. +Бар’єри безпеки спрацьовують **до** виконання runtime-коду. Кандидати блокуються, +якщо entry виходить за межі кореня плагіна, шлях доступний на запис для всіх або +володіння шляхом виглядає підозрілим для некомплектних плагінів. ### Поведінка manifest-first -Маніфест — це джерело істини для control plane. OpenClaw використовує його, щоб: +Маніфест — це джерело істини control-plane. OpenClaw використовує його, щоб: -- ідентифікувати plugin -- виявляти оголошені channels/skills/config schema або можливості bundle +- ідентифікувати плагін +- виявляти оголошені канали/Skills/схему конфігурації або можливості bundle - перевіряти `plugins.entries..config` -- доповнювати labels/placeholders у Control UI -- показувати metadata install/catalog +- доповнювати мітки/placeholder-и Control UI +- показувати метадані встановлення/каталогу -Для нативних plugins модуль runtime є частиною data plane. Він реєструє -фактичну поведінку, таку як hooks, tools, commands або provider flows. +Для нативних плагінів runtime-модуль є частиною data-plane. Він реєструє +фактичну поведінку, таку як hooks, інструменти, команди або потоки постачальників. ### Що кешує завантажувач -OpenClaw зберігає короткі in-process кеші для: +OpenClaw зберігає короткі кеші в межах процесу для: - результатів виявлення - даних реєстру маніфестів -- завантажених реєстрів plugin +- завантажених реєстрів плагінів -Ці кеші зменшують пікові витрати під час запуску та повторних викликів commands. Їх безпечно -сприймати як короткоживучі кеші продуктивності, а не як persistence. +Ці кеші зменшують пікове навантаження під час запуску та повторних викликів команд. Їх безпечно +сприймати як короткоживучі кеші продуктивності, а не як постійне сховище. Примітка щодо продуктивності: -- Установіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або +- Встановіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, щоб вимкнути ці кеші. -- Налаштовуйте вікна кешування через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і +- Налаштуйте вікна кешу через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Модель реєстру -Завантажені plugins не змінюють безпосередньо випадкові глобальні стани core. Вони -реєструються в центральному реєстрі plugin. +Завантажені плагіни не мутують напряму випадкові глобальні об’єкти core. Вони реєструються у +центральний реєстр плагінів. Реєстр відстежує: -- записи plugin (ідентичність, джерело, походження, статус, діагностика) -- tools +- записи плагінів (ідентичність, джерело, походження, статус, діагностика) +- інструменти - застарілі hooks і типізовані hooks -- channels -- providers -- handlers Gateway RPC -- HTTP routes -- CLI registrars -- background services -- commands, що належать plugin +- канали +- постачальників +- обробники Gateway RPC +- HTTP-маршрути +- реєстратори CLI +- фонові сервіси +- команди, що належать плагіну -Потім функції core читають із цього реєстру, а не звертаються до модулів plugin -безпосередньо. Це зберігає односпрямованість завантаження: +Потім функції core читають із цього реєстру замість прямої взаємодії з модулями плагінів. +Це підтримує односпрямованість завантаження: -- модуль plugin -> реєстрація в реєстрі -- runtime core -> використання реєстру +- модуль плагіна -> реєстрація в реєстрі +- runtime core -> споживання реєстру Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь core -потрібна лише одна точка інтеграції: "читати реєстр", а не "робити special-case для кожного модуля plugin". +потрібна лише одна точка інтеграції: «читати реєстр», а не «окремо обробляти кожен +модуль плагіна». -## Callbacks прив’язки conversation +## Колбеки прив’язки розмов -Plugins, які прив’язують conversation, можуть реагувати, коли approval вирішено. +Плагіни, які прив’язують розмову, можуть реагувати, коли схвалення буде вирішено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати callback після того, як запит на bind буде схвалено або відхилено: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати callback після того, як запит на прив’язку буде схвалено або відхилено: ```ts export default { @@ -589,26 +593,26 @@ export default { }; ``` -Поля payload callback: +Поля payload callback-а: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` - `binding`: визначена прив’язка для схвалених запитів -- `request`: початкове резюме запиту, підказка detach, id відправника та - metadata conversation +- `request`: зведення початкового запиту, підказка від’єднання, id відправника та + метадані розмови -Цей callback лише сповіщує. Він не змінює того, кому дозволено прив’язувати -conversation, і запускається після завершення обробки approval у core. +Цей callback слугує лише для сповіщення. Він не змінює того, кому дозволено прив’язувати +розмову, і запускається після завершення обробки схвалення в core. -## Runtime-хуки провайдера +## Runtime-хуки постачальника -Тепер provider plugins мають два шари: +Тепер плагіни постачальників мають два шари: -- metadata маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth до - завантаження runtime, плюс `providerAuthChoices` для дешевих labels onboarding/auth-choice - і metadata CLI flags до завантаження runtime -- hooks часу config: `catalog` / застарілий `discovery` плюс `applyConfigDefaults` -- runtime hooks: `normalizeModelId`, `normalizeTransport`, +- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth до + завантаження runtime, а також `providerAuthChoices` для дешевих міток onboarding/auth-choice + і метаданих CLI-прапорців до завантаження runtime +- hooks часу конфігурації: `catalog` / застарілий `discovery` плюс `applyConfigDefaults` +- runtime-хуки: `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, @@ -627,81 +631,83 @@ conversation, і запускається після завершення обр `buildReplayPolicy`, `sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected` -OpenClaw і далі володіє загальним agent loop, failover, обробкою transcript і -policy tools. Ці hooks — це surface розширення для provider-специфічної поведінки без -потреби в повністю custom inference transport. +OpenClaw усе ще володіє загальним agent loop, failover, обробкою transcript-ів та +політикою інструментів. Ці hooks є поверхнею розширення для специфічної для постачальника поведінки без +необхідності створювати повністю custom inference transport. -Використовуйте manifest `providerAuthEnvVars`, коли provider має credentials на основі env, -які загальні шляхи auth/status/model-picker повинні бачити без завантаження runtime plugin. -Використовуйте manifest `providerAuthChoices`, коли surfaces CLI onboarding/auth-choice -мають знати id choice провайдера, labels груп і просту прив’язку auth одним flag без завантаження runtime provider. -Залишайте `envVars` runtime provider для operator-facing підказок, таких як labels onboarding або -OAuth client-id/client-secret setup vars. +Використовуйте маніфестний `providerAuthEnvVars`, коли постачальник має облікові дані на основі env, +які мають бути видимі узагальненим шляхам auth/status/model-picker без завантаження runtime плагіна. +Використовуйте маніфестний `providerAuthChoices`, коли поверхні onboarding/auth-choice CLI +мають знати choice id постачальника, мітки груп і просту прив’язку auth одним +прапорцем без завантаження runtime постачальника. Зберігайте runtime `envVars` постачальника +для орієнтованих на оператора підказок, таких як onboarding-мітки або +змінні налаштування OAuth client-id/client-secret. ### Порядок hooks і використання -Для model/provider plugins OpenClaw викликає hooks приблизно в такому порядку. -Стовпець "Коли використовувати" — це короткий орієнтир для вибору. +Для плагінів моделей/постачальників OpenClaw викликає hooks приблизно в такому порядку. +Стовпець «Коли використовувати» — це швидкий довідник для прийняття рішень. -| # | Hook | Що він робить | Коли використовувати | -| --- | --------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує config provider у `models.providers` під час генерації `models.json` | Провайдер володіє catalog або типовими значеннями base URL | -| 2 | `applyConfigDefaults` | Застосовує global config defaults, що належать provider, під час materialization config | Типові значення залежать від режиму auth, env або семантики сімейства моделей provider | -| -- | _(built-in model lookup)_ | OpenClaw спочатку пробує звичайний шлях registry/catalog | _(це не hook plugin)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview alias model-id до пошуку | Провайдер володіє очищенням alias до канонічного визначення моделі | -| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства provider до загального складання моделі | Провайдер володіє очищенням transport для custom id provider у тому ж сімействі transport | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` до визначення runtime/provider | Провайдеру потрібне очищення config, яке має жити разом із plugin; вбудовані helpers Google-family також підтримують сумісні записи Google config | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-перезаписи використання нативного streaming до config providers | Провайдеру потрібні endpoint-керовані виправлення metadata нативного streaming usage | -| 7 | `resolveConfigApiKey` | Визначає env-marker auth для config providers до завантаження runtime auth | Провайдер має власне визначення API key через env-marker; `amazon-bedrock` також має тут вбудований AWS env-marker resolver | -| 8 | `resolveSyntheticAuth` | Показує local/self-hosted або auth на основі config без збереження plaintext | Провайдер може працювати із synthetic/local marker credentials | -| 9 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених synthetic placeholder profiles порівняно з auth через env/config | Провайдер зберігає synthetic placeholder profiles, які не повинні мати вищий пріоритет | -| 10 | `resolveDynamicModel` | Синхронний fallback для model id, що належать provider, але ще відсутні в локальному registry | Провайдер приймає довільні upstream model id | -| 11 | `prepareDynamicModel` | Асинхронний прогрів, після якого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві metadata до визначення невідомих id | -| 12 | `normalizeResolvedModel` | Фінальний перезапис до того, як embedded runner використає визначену модель | Провайдеру потрібні перезаписи transport, але він усе ще використовує core transport | -| 13 | `contributeResolvedModelCompat` | Додає compat-flags для vendor-моделей за сумісним transport іншого типу | Провайдер розпізнає власні моделі на proxy transports без перехоплення всього provider | -| 14 | `capabilities` | Метадані transcript/tooling, що належать provider і використовуються спільною логікою core | Провайдеру потрібні особливості transcript/provider-family | -| 15 | `normalizeToolSchemas` | Нормалізує schema tools до того, як їх побачить embedded runner | Провайдеру потрібне очищення schema для сімейства transport | -| 16 | `inspectToolSchemas` | Показує provider-owned діагностику schema після нормалізації | Провайдер хоче попередження про keywords, не навчаючи core provider-специфічних правил | -| 17 | `resolveReasoningOutputMode` | Вибирає нативний або tagged контракт reasoning-output | Провайдеру потрібен tagged reasoning/final output замість нативних полів | -| 18 | `prepareExtraParams` | Нормалізація параметрів запиту до загальних wrappers параметрів stream | Провайдеру потрібні типові параметри запиту або очищення параметрів per-provider | -| 19 | `createStreamFn` | Повністю замінює звичайний шлях stream custom transport | Провайдеру потрібен custom wire protocol, а не просто wrapper | -| 20 | `wrapStreamFn` | Wrapper stream після застосування загальних wrappers | Провайдеру потрібні wrappers заголовків/тіла/compat моделі запиту без custom transport | -| 21 | `resolveTransportTurnState` | Додає нативні заголовки або metadata transport для конкретного turn | Провайдер хоче, щоб загальні transports передавали provider-native turn identity | -| 22 | `resolveWebSocketSessionPolicy` | Додає нативні заголовки WebSocket або policy cool-down session | Провайдер хоче, щоб загальні WS transports налаштовували заголовки session або policy fallback | -| 23 | `formatApiKey` | Форматер auth-profile: збережений profile стає runtime-рядком `apiKey` | Провайдер зберігає додаткові metadata auth і потребує custom форми runtime token | -| 24 | `refreshOAuth` | Перевизначення оновлення OAuth для custom endpoints refresh або policy помилок refresh | Провайдер не вписується у спільні refreshers `pi-ai` | -| 25 | `buildAuthDoctorHint` | Підказка для виправлення, що додається при помилці оновлення OAuth | Провайдеру потрібна власна підказка щодо відновлення auth після помилки refresh | -| 26 | `matchesContextOverflowError` | Matcher переповнення context window, що належить provider | Провайдер має сирі помилки overflow, які загальні heuristics пропустять | -| 27 | `classifyFailoverReason` | Класифікація причин failover, що належить provider | Провайдер може зіставити сирі API/transport errors із rate-limit/overload тощо | -| 28 | `isCacheTtlEligible` | Policy prompt-cache для proxy/backhaul providers | Провайдеру потрібне proxy-специфічне керування TTL кешу | -| 29 | `buildMissingAuthMessage` | Заміна загального recovery message для відсутньої auth | Провайдеру потрібна provider-специфічна підказка відновлення при відсутній auth | -| 30 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей плюс необов’язкова user-facing підказка помилки | Провайдеру потрібно приховувати застарілі upstream rows або замінювати їх підказкою vendor | -| 31 | `augmentModelCatalog` | Додає synthetic/final rows catalog після виявлення | Провайдеру потрібні synthetic rows для forward-compat у `models list` і pickers | -| 32 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для binary-thinking providers | Провайдер відкриває лише бінарне thinking on/off | -| 33 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для підмножини моделей | -| 34 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Провайдер володіє типовою policy `/think` для сімейства моделей | -| 35 | `isModernModelRef` | Matcher modern-model для live filters профілів і вибору smoke | Провайдер володіє зіставленням preferred моделей для live/smoke | -| 36 | `prepareRuntimeAuth` | Обмінює налаштовані credentials на фактичний runtime token/key перед inference | Провайдеру потрібен обмін token або short-lived credentials для запиту | -| 37 | `resolveUsageAuth` | Визначає credentials usage/billing для `/usage` і пов’язаних surfaces status | Провайдеру потрібен custom парсинг token usage/quota або інші credentials usage | -| 38 | `fetchUsageSnapshot` | Отримує та нормалізує provider-специфічні snapshots usage/quota після визначення auth | Провайдеру потрібен provider-специфічний endpoint usage або parser payload | -| 39 | `createEmbeddingProvider` | Створює embedding adapter, що належить provider, для memory/search | Поведінка embedding memory має належати plugin provider | -| 40 | `buildReplayPolicy` | Повертає policy replay, яка керує обробкою transcript для provider | Провайдеру потрібна custom policy transcript (наприклад, видалення блоків thinking) | -| 41 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення transcript | Провайдеру потрібні provider-специфічні перезаписи replay понад спільні helpers compact | -| 42 | `validateReplayTurns` | Фінальна валідація або зміна форми turns replay до embedded runner | Transport провайдера потребує суворішої валідації turn після загальної санітизації | -| 43 | `onModelSelected` | Запускає побічні ефекти після вибору моделі, що належать provider | Провайдеру потрібна telemetry або provider-owned стан, коли модель стає активною | +| # | Hook | Що він робить | Коли використовувати | +| --- | --------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Публікує конфігурацію постачальника в `models.providers` під час генерації `models.json` | Постачальник володіє каталогом або базовими значеннями `base URL` | +| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації постачальника під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей постачальника | +| -- | _(built-in model lookup)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(не є hook-ом плагіна)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми id моделей перед пошуком | Постачальник володіє очищенням псевдонімів перед канонічним визначенням моделі | +| 4 | `normalizeTransport` | Нормалізує сімейство постачальника `api` / `baseUrl` перед загальним складанням моделі | Постачальник володіє очищенням transport для custom id постачальників у тому самому сімействі transport | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед runtime/визначенням постачальника | Постачальнику потрібно очищення конфігурації, яке має жити разом із плагіном; комплектні helper-и сімейства Google також страхують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування native streaming-usage до конфігурованих постачальників | Постачальнику потрібні виправлення метаданих native streaming usage, залежні від endpoint-ів | +| 7 | `resolveConfigApiKey` | Визначає auth через env-marker для постачальників конфігурації до завантаження runtime auth | Постачальник має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований resolver AWS env-marker | +| 8 | `resolveSyntheticAuth` | Показує локальний/self-hosted або оснований на конфігурації auth без збереження plaintext | Постачальник може працювати із synthetic/local marker облікових даних | +| 9 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених synthetic placeholder profile на користь auth на основі env/config | Постачальник зберігає synthetic placeholder profile, які не мають переважати | +| 10 | `resolveDynamicModel` | Синхронний fallback для id моделей постачальника, яких ще немає в локальному реєстрі | Постачальник приймає довільні upstream id моделей | +| 11 | `prepareDynamicModel` | Асинхронний warm-up, після чого `resolveDynamicModel` запускається знову | Постачальнику потрібні мережеві метадані перед визначенням невідомих id | +| 12 | `normalizeResolvedModel` | Фінальне переписування перед тим, як embedded runner використає визначену модель | Постачальнику потрібні переписування transport, але він усе ще використовує core transport | +| 13 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей постачальника за іншим сумісним transport | Постачальник розпізнає власні моделі на proxy transport-ах, не перебираючи на себе постачальника | +| 14 | `capabilities` | Метадані transcript/tooling, що належать постачальнику та використовуються спільною логікою core | Постачальнику потрібні особливості transcript/provider-family | +| 15 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить embedded runner | Постачальнику потрібне очищення схем для сімейства transport | +| 16 | `inspectToolSchemas` | Показує діагностику схем, що належить постачальнику, після нормалізації | Постачальник хоче попередження щодо ключових слів, не навчаючи core правилам, специфічним для постачальника | +| 17 | `resolveReasoningOutputMode` | Вибирає native чи tagged контракт reasoning-output | Постачальнику потрібен tagged reasoning/final output замість native полів | +| 18 | `prepareExtraParams` | Нормалізація параметрів запиту перед узагальненими обгортками stream options | Постачальнику потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного постачальника | +| 19 | `createStreamFn` | Повністю замінює звичайний шлях stream custom transport-ом | Постачальнику потрібен custom wire protocol, а не лише обгортка | +| 20 | `wrapStreamFn` | Обгортка stream після застосування узагальнених обгорток | Постачальнику потрібні обгортки заголовків/тіла/compat моделей запиту без custom transport | +| 21 | `resolveTransportTurnState` | Додає native заголовки або метадані transport для кожного ходу | Постачальник хоче, щоб узагальнені transport-и надсилали native turn identity постачальника | +| 22 | `resolveWebSocketSessionPolicy` | Додає native заголовки WebSocket або політику охолодження сесії | Постачальник хоче, щоб узагальнені WS transport-и налаштовували заголовки сесії або політику fallback | +| 23 | `formatApiKey` | Форматувач auth-profile: збережений profile стає runtime-рядком `apiKey` | Постачальник зберігає додаткові auth-метадані й потребує custom форми runtime token | +| 24 | `refreshOAuth` | Перевизначення оновлення OAuth для custom endpoint-ів оновлення або політики помилок оновлення | Постачальник не відповідає спільним оновлювачам `pi-ai` | +| 25 | `buildAuthDoctorHint` | Підказка відновлення, що додається при помилці оновлення OAuth | Постачальнику потрібні власні вказівки з відновлення auth після помилки оновлення | +| 26 | `matchesContextOverflowError` | Матчер переповнення context window, що належить постачальнику | У постачальника є сирі помилки переповнення, які узагальнені евристики не знайдуть | +| 27 | `classifyFailoverReason` | Класифікація причин failover, що належить постачальнику | Постачальник може зіставляти сирі API/transport помилки з rate-limit/overload тощо | +| 28 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul постачальників | Постачальнику потрібне керування TTL кешу, специфічне для proxy | +| 29 | `buildMissingAuthMessage` | Замінник узагальненого повідомлення відновлення при відсутності auth | Постачальнику потрібна підказка відновлення при відсутності auth, специфічна для нього | +| 30 | `suppressBuiltInModel` | Приховування застарілої upstream-моделі плюс необов’язкова користувацька підказка про помилку | Постачальнику потрібно приховувати застарілі upstream-рядки або замінювати їх підказкою постачальника | +| 31 | `augmentModelCatalog` | Додає synthetic/final рядки каталогу після виявлення | Постачальнику потрібні synthetic рядки прямої сумісності в `models list` і picker-ах | +| 32 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для постачальників binary-thinking | Постачальник підтримує лише binary thinking увімк./вимк. | +| 33 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для окремих моделей | Постачальник хоче `xhigh` лише для частини моделей | +| 34 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Постачальник володіє політикою типового `/think` для сімейства моделей | +| 35 | `isModernModelRef` | Матчер modern-model для live profile filter-ів і вибору smoke | Постачальник володіє зіставленням бажаних live/smoke-моделей | +| 36 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime token/key безпосередньо перед inference | Постачальнику потрібен обмін токена або короткоживучі облікові дані запиту | +| 37 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` та пов’язаних статусних поверхонь | Постачальнику потрібен custom розбір токенів usage/quota або інші usage-облікові дані | +| 38 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для постачальника знімки usage/quota після визначення auth | Постачальнику потрібен специфічний endpoint usage або парсер payload | +| 39 | `createEmbeddingProvider` | Будує embedding-адаптер, що належить постачальнику, для пам’яті/пошуку | Поведінка memory embedding має належати плагіну постачальника | +| 40 | `buildReplayPolicy` | Повертає replay policy, що керує обробкою transcript для постачальника | Постачальнику потрібна custom transcript policy (наприклад, видалення thinking-блоків) | +| 41 | `sanitizeReplayHistory` | Переписує replay history після узагальненого очищення transcript | Постачальнику потрібні власні переписування replay, що виходять за межі спільних helper-ів compaction | +| 42 | `validateReplayTurns` | Фінальна валідація або переформування replay-turn перед embedded runner | Transport постачальника потребує суворішої валідації turn після узагальненого очищення | +| 43 | `onModelSelected` | Запускає побічні ефекти після вибору моделі, що належать постачальнику | Постачальнику потрібна телеметрія або власний стан постачальника, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -відповідний plugin provider, а потім переходять до інших provider plugins, здатних на hooks, -доки один із них справді не змінить model id або transport/config. Це дозволяє -shim providers для alias/compat працювати без потреби, щоб викликаюча сторона знала, який -вбудований plugin володіє цим перезаписом. Якщо жоден provider hook не переписує -підтримуваний запис Google-family config, все одно застосовується вбудований нормалізатор Google config. +відповідний плагін постачальника, а потім переходять до інших плагінів постачальників, здатних +працювати з hook-ами, доки один із них справді не змінить model id або transport/config. Це зберігає +роботу shim-ів псевдонімів/compat-постачальників без потреби для викликача знати, який +комплектний плагін володіє переписуванням. Якщо жоден hook постачальника не перепише +підтримуваний запис конфігурації сімейства Google, комплектний нормалізатор конфігурації Google +усе одно застосує це очищення сумісності. -Якщо provider потрібен повністю custom wire protocol або custom виконавець запитів, -це вже інший клас extension. Ці hooks призначені для поведінки provider, яка -все ще працює на звичайному inference loop OpenClaw. +Якщо постачальнику потрібен повністю custom wire protocol або custom request executor, +це інший клас розширення. Ці hooks призначені для поведінки постачальника, +яка все ще працює на звичайному inference loop OpenClaw. -### Приклад provider +### Приклад постачальника ```ts api.registerProvider({ @@ -760,112 +766,112 @@ api.registerProvider({ - Anthropic використовує `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`, `resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, - і `wrapStreamFn`, оскільки володіє forward-compat для Claude 4.6, - підказками сімейства provider, інструкціями відновлення auth, інтеграцією з endpoint usage, - відповідністю prompt-cache, типовими значеннями config з урахуванням auth, типовою/адаптивною policy thinking Claude, - а також Anthropic-специфічним формуванням stream для - beta headers, `/fast` / `serviceTier` і `context1m`. -- Claude-специфічні helpers stream Anthropic поки що залишаються у власному - публічному шві `api.ts` / `contract-api.ts` вбудованого plugin. Ця package surface + і `wrapStreamFn`, тому що володіє прямою сумісністю Claude 4.6, + підказками для сімейства постачальника, вказівками з відновлення auth, + інтеграцією endpoint-ів usage, допустимістю prompt-cache, типовими налаштуваннями конфігурації з урахуванням auth, політикою thinking за замовчуванням/адаптивною для Claude + та специфічним для Anthropic формуванням stream для + beta-заголовків, `/fast` / `serviceTier` і `context1m`. +- Claude-специфічні stream-helper-и Anthropic поки що залишаються у власному + публічному шві `api.ts` / `contract-api.ts` комплектного плагіна. Ця поверхня пакета експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і нижчорівневі - builders wrappers Anthropic замість розширення загального SDK навколо правил - beta-header одного provider. + builder-и обгорток Anthropic замість розширення узагальненого SDK навколо правил beta-header одного постачальника. - OpenAI використовує `resolveDynamicModel`, `normalizeResolvedModel` і - `capabilities` плюс `buildMissingAuthMessage`, `suppressBuiltInModel`, + `capabilities`, а також `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `supportsXHighThinking` і `isModernModelRef`, - оскільки володіє GPT-5.4 forward-compat, прямою нормалізацією OpenAI - `openai-completions` -> `openai-responses`, підказками auth з урахуванням Codex, - приховуванням Spark, synthetic rows списку OpenAI і політикою thinking / live-model GPT-5; - сімейство stream `openai-responses-defaults` володіє - спільними нативними wrappers OpenAI Responses для - attribution headers, `/fast`/`serviceTier`, verbosity тексту, нативного web search Codex, - формуванням payload reasoning-compat і керуванням context у Responses. -- OpenRouter використовує `catalog` плюс `resolveDynamicModel` і - `prepareDynamicModel`, оскільки provider є pass-through і може відкривати нові - model id ще до оновлення статичного catalog OpenClaw; він також використовує + тому що володіє прямою сумісністю GPT-5.4, + прямою нормалізацією OpenAI `openai-completions` -> `openai-responses`, + підказками auth з урахуванням Codex, приховуванням Spark, synthetic рядками списку OpenAI та політикою thinking / + live-model для GPT-5; сімейство stream `openai-responses-defaults` володіє + спільними native wrappers OpenAI Responses для + attribution headers, `/fast`/`serviceTier`, verbosity тексту, native веб-пошуку Codex, + формування payload reasoning-compat і керуванням контекстом Responses. +- OpenRouter використовує `catalog`, а також `resolveDynamicModel` і + `prepareDynamicModel`, тому що постачальник є pass-through і може відкривати нові + model id до того, як оновиться статичний каталог OpenClaw; він також використовує `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб тримати - provider-специфічні заголовки запитів, metadata маршрутизації, патчі reasoning і - policy prompt-cache поза core. Його policy replay походить із сімейства - `passthrough-gemini`, тоді як сімейство stream `openrouter-thinking` - володіє ін’єкцією proxy reasoning і пропусками для непідтримуваних моделей / `auto`. + специфічні для постачальника заголовки запитів, метадані маршрутизації, патчі reasoning і + політику prompt-cache поза core. Його replay policy походить із + сімейства `passthrough-gemini`, а сімейство stream `openrouter-thinking` + володіє proxy-injection reasoning і пропусками для непідтримуваних моделей / `auto`. - GitHub Copilot використовує `catalog`, `auth`, `resolveDynamicModel` і - `capabilities` плюс `prepareRuntimeAuth` і `fetchUsageSnapshot`, оскільки йому - потрібні device login, що належать provider, fallback-поведінка моделей, особливості transcript Claude, - обмін токена GitHub на токен Copilot і endpoint usage, що належить provider. + `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, тому що йому + потрібні device login, що належить постачальнику, поведінка fallback моделі, + особливості transcript Claude, обмін токена GitHub -> токен Copilot та endpoint usage, що належить постачальнику. - OpenAI Codex використовує `catalog`, `resolveDynamicModel`, - `normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog` плюс - `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки він - усе ще працює на core transports OpenAI, але володіє своєю нормалізацією - transport/base URL, policy fallback оновлення OAuth, типовим вибором transport, - synthetic rows catalog Codex і інтеграцією з endpoint usage ChatGPT; він + `normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog`, а також + `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, тому що він + усе ще працює на core-транспорті OpenAI, але володіє нормалізацією transport/base URL, + політикою fallback для оновлення OAuth, вибором типового transport, + synthetic рядками каталогу Codex та інтеграцією endpoint-а використання ChatGPT; він використовує те саме сімейство stream `openai-responses-defaults`, що й прямий OpenAI. - Google AI Studio і Gemini CLI OAuth використовують `resolveDynamicModel`, `buildReplayPolicy`, `sanitizeReplayHistory`, - `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, оскільки - сімейство replay `google-gemini` володіє fallback для forward-compat Gemini 3.1, - нативною валідацією replay Gemini, санітизацією replay під час bootstrap, режимом - tagged reasoning-output і зіставленням modern-model, тоді як + `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, тому що + сімейство replay `google-gemini` володіє fallback-ом прямої сумісності Gemini 3.1, + native валідацією replay Gemini, очищенням bootstrap replay, tagged + режимом reasoning-output і зіставленням modern-model, тоді як сімейство stream `google-thinking` володіє нормалізацією payload thinking Gemini; Gemini CLI OAuth також використовує `formatApiKey`, `resolveUsageAuth` і - `fetchUsageSnapshot` для форматування токена, парсингу токена та - підключення endpoint quota. + `fetchUsageSnapshot` для форматування токена, розбору токена та + підключення endpoint-а квот. - Anthropic Vertex використовує `buildReplayPolicy` через - сімейство replay `anthropic-by-model`, щоб Claude-специфічне очищення replay - залишалося прив’язаним до id Claude, а не до кожного transport `anthropic-messages`. + сімейство replay `anthropic-by-model`, щоб очищення replay, специфічне для Claude, залишалося + обмеженим id Claude, а не всім transport-ам `anthropic-messages`. - Amazon Bedrock використовує `buildReplayPolicy`, `matchesContextOverflowError`, - `classifyFailoverReason` і `resolveDefaultThinkingLevel`, оскільки володіє - класифікацією помилок throttle/not-ready/context-overflow, специфічною для Bedrock, - для трафіку Anthropic-on-Bedrock; його policy replay все ще використовує той самий - захист лише для Claude `anthropic-by-model`. + `classifyFailoverReason` і `resolveDefaultThinkingLevel`, тому що володіє + класифікацією помилок throttle/not-ready/context-overflow, специфічних для Bedrock, + для трафіку Anthropic-on-Bedrock; його replay policy все ще використовує той самий + guard лише для Claude `anthropic-by-model`. - OpenRouter, Kilocode, Opencode і Opencode Go використовують `buildReplayPolicy` - через сімейство replay `passthrough-gemini`, оскільки вони проксіюють моделі Gemini - через transports, сумісні з OpenAI, і потребують санітизації - thought-signature Gemini без нативної валідації replay Gemini або bootstrap-перезаписів. + через сімейство replay `passthrough-gemini`, тому що вони проксіюють моделі Gemini + через OpenAI-сумісні transport-и і потребують очищення thought-signature Gemini + без native replay-валідації Gemini або bootstrap-переписувань. - MiniMax використовує `buildReplayPolicy` через - сімейство replay `hybrid-anthropic-openai`, оскільки один provider володіє і - семантикою Anthropic-message, і семантикою OpenAI-compatible; він - зберігає видалення blocks thinking лише для Claude з боку Anthropic, одночасно перевизначаючи - режим reasoning output назад на нативний, а сімейство stream `minimax-fast-mode` - володіє перезаписами моделі fast-mode на спільному шляху stream. -- Moonshot використовує `catalog` плюс `wrapStreamFn`, оскільки все ще використовує - спільний OpenAI transport, але потребує provider-owned нормалізації payload thinking; сімейство - stream `moonshot-thinking` відображає config плюс стан `/think` на - його нативний бінарний payload thinking. + сімейство replay `hybrid-anthropic-openai`, тому що один постачальник володіє і + семантикою Anthropic-message, і OpenAI-compatible; він зберігає видалення + thinking-block лише для Claude на боці Anthropic, водночас перевизначаючи режим reasoning + назад на native, а сімейство stream `minimax-fast-mode` володіє + переписуванням fast-mode моделей на спільному шляху stream. +- Moonshot використовує `catalog` і `wrapStreamFn`, тому що він усе ще використовує спільний + transport OpenAI, але потребує нормалізації payload thinking, що належить постачальнику; сімейство + stream `moonshot-thinking` зіставляє config плюс стан `/think` зі своїм + native payload binary thinking. - Kilocode використовує `catalog`, `capabilities`, `wrapStreamFn` і - `isCacheTtlEligible`, оскільки потребує provider-owned заголовків запитів, - нормалізації payload reasoning, підказок transcript Gemini та керування - TTL кешу Anthropic; сімейство stream `kilocode-thinking` зберігає ін’єкцію Kilo thinking - на спільному proxy stream, пропускаючи `kilo/auto` та + `isCacheTtlEligible`, тому що йому потрібні заголовки запитів, специфічні для постачальника, + нормалізація payload reasoning, підказки transcript Gemini і керування TTL кешу Anthropic; сімейство + stream `kilocode-thinking` зберігає injection thinking Kilo + на спільному proxy-stream шляху, водночас пропускаючи `kilo/auto` та інші proxy model id, які не підтримують явні payload reasoning. - Z.AI використовує `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`, `isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`, - `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки володіє fallback GLM-5, - типовими значеннями `tool_stream`, UX бінарного thinking, зіставленням modern-model, - а також auth для usage + отриманням quota; сімейство stream `tool-stream-default-on` - тримає wrapper `tool_stream`, увімкнений за замовчуванням, поза handwritten glue для кожного provider. + `resolveUsageAuth` і `fetchUsageSnapshot`, тому що володіє fallback-ом GLM-5, + значеннями за замовчуванням `tool_stream`, UX binary thinking, зіставленням modern-model, а також + і auth для usage, і отриманням квоти; сімейство stream `tool-stream-default-on` + тримає обгортку `tool_stream`, увімкнену за замовчуванням, поза рукописним glue для кожного постачальника. - xAI використовує `normalizeResolvedModel`, `normalizeTransport`, `contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`, `resolveSyntheticAuth`, `resolveDynamicModel` і `isModernModelRef`, - оскільки володіє нативною нормалізацією transport Responses xAI, перезаписами alias fast-mode Grok, - типовим `tool_stream`, очищенням strict-tool / reasoning-payload, - повторним використанням fallback auth для tools, що належать plugin, forward-compat - визначенням моделей Grok і compat-патчами, що належать provider, такими як профіль schema tools xAI, - непідтримувані keywords schema, нативний `web_search` і декодування аргументів викликів tools з HTML entities. + тому що володіє нормалізацією native xAI Responses transport, переписуванням + псевдонімів fast-mode Grok, типовим `tool_stream`, очищенням strict-tool / reasoning-payload, + повторним використанням fallback auth для інструментів, що належать плагіну, прямим визначенням + моделей Grok і compat-патчами, що належать постачальнику, такими як профіль схем інструментів xAI, + непідтримувані ключові слова схеми, native `web_search` і декодування + аргументів виклику інструментів із HTML-entity. - Mistral, OpenCode Zen і OpenCode Go використовують лише `capabilities`, щоб тримати особливості transcript/tooling поза core. -- Вбудовані providers лише з catalog, такі як `byteplus`, `cloudflare-ai-gateway`, +- Комплектні постачальники лише з каталогом, такі як `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і `volcengine`, використовують лише `catalog`. -- Qwen використовує `catalog` для свого текстового provider плюс спільні реєстрації - media-understanding і video-generation для своїх мультимодальних surfaces. -- MiniMax і Xiaomi використовують `catalog` плюс hooks usage, оскільки їхня поведінка `/usage` - належить plugin, хоча inference і далі виконується через спільні transports. +- Qwen використовує `catalog` для свого текстового постачальника, а також спільні реєстрації + розуміння медіа і генерації відео для своїх мультимодальних поверхонь. +- MiniMax і Xiaomi використовують `catalog` плюс hooks usage, тому що їхня поведінка `/usage` + належить плагіну, хоча інференс усе ще виконується через спільні transport-и. -## Runtime helpers +## Runtime-helper-и -Plugins можуть отримувати доступ до вибраних helpers core через `api.runtime`. Для TTS: +Плагіни можуть отримувати доступ до вибраних helper-ів core через `api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -886,14 +892,14 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайний payload виводу TTS core для surfaces файлів/voice-note. -- Використовує core-конфігурацію `messages.tts` і вибір provider. -- Повертає буфер аудіо PCM + sample rate. Plugins повинні виконувати ресемплінг/кодування для provider. -- `listVoices` є необов’язковим для кожного provider. Використовуйте його для voice pickers або setup flows, що належать vendor. -- Списки голосів можуть включати багатші metadata, такі як locale, стать і теги personality для provider-aware pickers. -- OpenAI і ElevenLabs сьогодні підтримують telephony. Microsoft — ні. +- `textToSpeech` повертає звичайний payload виводу TTS core для поверхонь файлів/voice-note. +- Використовує конфігурацію core `messages.tts` і вибір постачальника. +- Повертає PCM audio buffer + sample rate. Плагіни мають ресемплювати/кодувати для постачальників. +- `listVoices` є необов’язковим для кожного постачальника. Використовуйте його для picker-ів голосів або setup-потоків, що належать постачальнику. +- Списки голосів можуть містити багатші метадані, такі як locale, gender і теги personality для picker-ів з урахуванням постачальника. +- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. -Plugins також можуть реєструвати speech providers через `api.registerSpeechProvider(...)`. +Плагіни також можуть реєструвати постачальників мовлення через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -913,15 +919,15 @@ api.registerSpeechProvider({ Примітки: -- Залишайте policy TTS, fallback і доставку відповідей у core. -- Використовуйте speech providers для поведінки synthesis, що належить vendor. -- Застаріле значення вводу Microsoft `edge` нормалізується до id provider `microsoft`. -- Бажана модель володіння — орієнтована на компанію: один plugin vendor може володіти - text, speech, image і майбутніми media providers у міру того, як OpenClaw додає ці - capability-контракти. +- Зберігайте політику TTS, fallback і доставку відповіді в core. +- Використовуйте постачальників мовлення для поведінки синтезу, що належить постачальнику. +- Застарілий ввід Microsoft `edge` нормалізується до provider id `microsoft`. +- Бажана модель володіння орієнтована на компанію: один плагін постачальника може володіти + текстовими, голосовими, зображувальними та майбутніми медіапостачальниками, коли OpenClaw додає ці + контракти можливостей. -Для розуміння зображень/аудіо/відео plugins реєструють один типізований -provider media-understanding замість загального key/value bag: +Для розуміння зображень/аудіо/відео плагіни реєструють одного типізованого +постачальника media-understanding, а не узагальнений мішок key/value: ```ts api.registerMediaUnderstandingProvider({ @@ -935,16 +941,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Залишайте orchestration, fallback, config і підключення channels у core. -- Залишайте поведінку vendor у plugin provider. -- Розширення шляхом додавання повинно залишатися типізованим: нові необов’язкові methods, нові необов’язкові - поля result, нові необов’язкові capabilities. +- Зберігайте оркестрацію, fallback, конфігурацію і підключення до каналу в core. +- Зберігайте поведінку постачальника в плагіні постачальника. +- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові + поля результату, нові необов’язкові можливості. - Генерація відео вже дотримується того самого шаблону: - - core володіє capability-контрактом і runtime helper - - plugins vendor реєструють `api.registerVideoGenerationProvider(...)` - - feature/channel plugins використовують `api.runtime.videoGeneration.*` + - core володіє контрактом можливості та runtime-helper-ом + - плагіни постачальників реєструють `api.registerVideoGenerationProvider(...)` + - функціональні/канальні плагіни споживають `api.runtime.videoGeneration.*` -Для runtime helpers media-understanding plugins можуть викликати: +Для runtime-helper-ів media-understanding плагіни можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -959,7 +965,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрипції аудіо plugins можуть використовувати або runtime media-understanding, +Для аудіотранскрипції плагіни можуть використовувати або runtime media-understanding, або старіший псевдонім STT: ```ts @@ -973,13 +979,13 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ Примітки: -- `api.runtime.mediaUnderstanding.*` — це бажана спільна surface для +- `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для розуміння зображень/аудіо/відео. -- Використовує core-конфігурацію аудіо media-understanding (`tools.media.audio`) і порядок fallback provider. -- Повертає `{ text: undefined }`, коли вихід транскрипції не створюється (наприклад, для пропущеного/непідтримуваного вводу). -- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності. +- Використовує конфігурацію аудіо core media-understanding (`tools.media.audio`) і порядок fallback постачальників. +- Повертає `{ text: undefined }`, коли вихід транскрипції не було отримано (наприклад, для пропущеного/непідтримуваного вводу). +- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом сумісності. -Plugins також можуть запускати фонові виконання subagent через `api.runtime.subagent`: +Плагіни також можуть запускати фонові запуски subagent через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -993,14 +999,14 @@ const result = await api.runtime.subagent.run({ Примітки: -- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни session. -- OpenClaw враховує ці поля перевизначення лише для довірених викликачів. -- Для fallback-запусків, що належать plugin, оператори повинні явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugins конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. -- Запуски subagent для недовірених plugins усе ще працюють, але запити на перевизначення відхиляються, а не тихо повертаються до fallback. +- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. +- OpenClaw застосовує ці поля перевизначення лише для довірених викликачів. +- Для fallback-запусків, що належать плагіну, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. +- Запуски subagent недовірених плагінів усе ще працюють, але запити на перевизначення відхиляються замість тихого fallback. -Для web search plugins можуть використовувати спільний runtime helper замість -прямого звернення до підключення tool агента: +Для веб-пошуку плагіни можуть використовувати спільний runtime-helper замість +звернення до підключення інструмента агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -1016,14 +1022,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Plugins також можуть реєструвати providers web-search через +Плагіни також можуть реєструвати постачальників веб-пошуку через `api.registerWebSearchProvider(...)`. Примітки: -- Залишайте вибір provider, визначення credentials і спільну семантику запитів у core. -- Використовуйте web-search providers для vendor-специфічних transports пошуку. -- `api.runtime.webSearch.*` — це бажана спільна surface для feature/channel plugins, яким потрібна поведінка пошуку без залежності від wrapper tool агента. +- Зберігайте вибір постачальника, визначення облікових даних і спільну семантику запитів у core. +- Використовуйте постачальників веб-пошуку для транспортів пошуку, що належать постачальнику. +- `api.runtime.webSearch.*` — це бажана спільна поверхня для функціональних/канальних плагінів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. ### `api.runtime.imageGeneration` @@ -1038,12 +1044,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: згенерувати зображення, використовуючи налаштований ланцюжок providers генерації зображень. -- `listProviders(...)`: перелічити доступних providers генерації зображень і їхні можливості. +- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка постачальників генерації зображень. +- `listProviders(...)`: виводить доступних постачальників генерації зображень і їхні можливості. -## HTTP routes Gateway +## HTTP-маршрути Gateway -Plugins можуть відкривати HTTP endpoints через `api.registerHttpRoute(...)`. +Плагіни можуть відкривати HTTP-endpoint-и через `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -1058,36 +1064,36 @@ api.registerHttpRoute({ }); ``` -Поля route: +Поля маршруту: -- `path`: шлях route у межах HTTP server gateway. -- `auth`: обов’язкове. Використовуйте `"gateway"` для вимоги звичайної auth gateway, або `"plugin"` для auth/перевірки webhook, якими керує plugin. -- `match`: необов’язкове. `"exact"` (типово) або `"prefix"`. -- `replaceExisting`: необов’язкове. Дозволяє тому самому plugin замінити власну наявну реєстрацію route. -- `handler`: повертає `true`, коли route обробив запит. +- `path`: шлях маршруту під HTTP-сервером gateway. +- `auth`: обов’язкове. Використовуйте `"gateway"`, щоб вимагати звичайний auth gateway, або `"plugin"` для auth/перевірки webhook-ів, якими керує плагін. +- `match`: необов’язкове. `"exact"` (типове значення) або `"prefix"`. +- `replaceExisting`: необов’язкове. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту. +- `handler`: повертає `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` видалено і спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`. -- Routes plugin повинні явно оголошувати `auth`. -- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінити route іншого plugin. -- Routes, що перекриваються, з різними рівнями `auth` відхиляються. Зберігайте ланцюжки fallthrough `exact`/`prefix` лише в межах одного рівня auth. -- Routes `auth: "plugin"` **не** отримують автоматично operator runtime scopes. Вони призначені для webhook/signature verification, якими керує plugin, а не для привілейованих helper-викликів Gateway. -- Routes `auth: "gateway"` працюють усередині runtime scope запиту Gateway, але цей scope навмисно консервативний: - - bearer auth із shared-secret (`gateway.auth.mode = "token"` / `"password"`) утримує runtime scopes route plugin прив’язаними до `operator.write`, навіть якщо викликаюча сторона надсилає `x-openclaw-scopes` - - довірені режими HTTP з ідентичністю (наприклад `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких identity-bearing запитах route plugin, runtime scope повертається до `operator.write` -- Практичне правило: не припускайте, що route plugin з auth gateway є неявною admin-surface. Якщо вашому route потрібна поведінка лише для admin, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. +- `api.registerHttpHandler(...)` видалено, і він спричинить помилку завантаження плагіна. Використовуйте натомість `api.registerHttpRoute(...)`. +- Маршрути плагіна мають явно оголошувати `auth`. +- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна. +- Перекривні маршрути з різними рівнями `auth` відхиляються. Тримайте ланцюжки fallthrough `exact`/`prefix` лише на одному рівні auth. +- Маршрути `auth: "plugin"` **не** отримують автоматично runtime scope оператора. Вони призначені для webhook-ів/перевірки підписів, якими керує плагін, а не для привілейованих helper-викликів Gateway. +- Маршрути `auth: "gateway"` працюють у межах runtime scope запиту Gateway, але цей scope навмисно обмежений: + - bearer auth через shared-secret (`gateway.auth.mode = "token"` / `"password"`) утримує runtime scope маршрутів плагінів на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` + - довірені HTTP-режими з переданою ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише коли заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту плагіна з переданою ідентичністю, runtime scope повертається до `operator.write` +- Практичне правило: не припускайте, що маршрут плагіна з gateway-auth є неявною admin-поверхнею. Якщо вашому маршруту потрібна поведінка лише для admin, вимагайте режим auth із переданою ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK -Під час створення plugins використовуйте subpaths SDK замість монолітного імпорту `openclaw/plugin-sdk`: +Під час створення плагінів використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`: -- `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації plugin. -- `openclaw/plugin-sdk/core` для загального спільного контракту, орієнтованого на plugin. -- `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod schema `openclaw.json` +- `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації плагінів. +- `openclaw/plugin-sdk/core` для узагальненого спільного контракту, орієнтованого на плагіни. +- `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`). -- Стабільні channel-примітиви, такі як `openclaw/plugin-sdk/channel-setup`, +- Стабільні канальні примітиви, такі як `openclaw/plugin-sdk/channel-setup`, `openclaw/plugin-sdk/setup-runtime`, `openclaw/plugin-sdk/setup-adapter-runtime`, `openclaw/plugin-sdk/setup-tools`, @@ -1098,18 +1104,18 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/channel-lifecycle`, `openclaw/plugin-sdk/channel-reply-pipeline`, `openclaw/plugin-sdk/command-auth`, - `openclaw/plugin-sdk/secret-input` і + `openclaw/plugin-sdk/secret-input` та `openclaw/plugin-sdk/webhook-ingress` для спільного підключення - setup/auth/reply/webhook. `channel-inbound` — це спільне місце для - debounce, mention matching, форматування envelope і helpers контексту inbound envelope. - `channel-setup` — вузький шов setup для необов’язкового install. - `setup-runtime` — runtime-safe surface setup, яка використовується `setupEntry` / - відкладеним запуском, включно з import-safe адаптерами патчів setup. - `setup-adapter-runtime` — це env-aware шов adapter setup облікового запису. - `setup-tools` — це малий шов CLI/archive/docs helper (`formatCliCommand`, + setup/auth/reply/webhook. `channel-inbound` — це спільний дім для debounce, mention matching, + форматування envelope та helper-ів контексту вхідного envelope. + `channel-setup` — це вузький setup-шов для необов’язкового встановлення. + `setup-runtime` — це безпечна для runtime setup-поверхня, яка використовується `setupEntry` / + відкладеним запуском, включно з import-safe setup patch adapters. + `setup-adapter-runtime` — це env-aware шов адаптера налаштування облікового запису. + `setup-tools` — це малий шов helper-ів для CLI/archive/docs (`formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR`). -- Domain subpaths, такі як `openclaw/plugin-sdk/channel-config-helpers`, +- Доменні підшляхи, такі як `openclaw/plugin-sdk/channel-config-helpers`, `openclaw/plugin-sdk/allow-from`, `openclaw/plugin-sdk/channel-config-schema`, `openclaw/plugin-sdk/telegram-command-config`, @@ -1123,188 +1129,189 @@ api.registerHttpRoute({ `openclaw/plugin-sdk/routing`, `openclaw/plugin-sdk/status-helpers`, `openclaw/plugin-sdk/text-runtime`, - `openclaw/plugin-sdk/runtime-store` і - `openclaw/plugin-sdk/directory-runtime` для спільних helpers runtime/config. - `telegram-command-config` — це вузький публічний шов для нормалізації/валідації custom-команд Telegram і він залишається доступним, навіть якщо вбудована contract-surface Telegram тимчасово недоступна. - `text-runtime` — це спільний шов text/markdown/logging, включно з - видаленням assistant-visible-text, helpers render/chunking markdown, helpers редагування, - helpers directive-tag і utilities безпечного тексту. -- Для approval-специфічних швів channel слід віддавати перевагу одному контракту - `approvalCapability` на plugin. Потім core читає auth approval, доставку, render і - native-routing behavior через цю одну capability замість змішування - поведінки approval з не пов’язаними полями plugin. -- `openclaw/plugin-sdk/channel-runtime` є застарілим і залишається лише як - compatibility shim для старіших plugins. Новий код повинен імпортувати вужчі - загальні примітиви, а код repo не повинен додавати нові імпорти цього shim. -- Внутрішні компоненти вбудованих extension залишаються приватними. Зовнішні plugins повинні використовувати лише subpaths `openclaw/plugin-sdk/*`. Core/test код OpenClaw може використовувати - публічні точки входу repo під коренем package plugin, такі як `index.js`, `api.js`, - `runtime-api.js`, `setup-entry.js`, а також вузькі файли, наприклад - `login-qr-api.js`. Ніколи не імпортуйте `src/*` package plugin з core або з - іншого extension. -- Поділ точок входу repo: - `/api.js` — це barrel helpers/types, + `openclaw/plugin-sdk/runtime-store` та + `openclaw/plugin-sdk/directory-runtime` для спільних helper-ів runtime/config. + `telegram-command-config` — це вузький публічний шов для нормалізації/валідації custom-команд Telegram і залишається доступним навіть якщо контрактна поверхня комплектного Telegram тимчасово недоступна. + `text-runtime` — це спільний шов для тексту/markdown/логування, включно з + видаленням тексту, видимого помічнику, helper-ами render/chunking markdown, helper-ами редагування, + helper-ами directive-tag і утилітами безпечного тексту. +- Канальні шви, специфічні для approval, мають надавати перевагу одному контракту `approvalCapability` + на плагіні. Тоді core читає auth approval, доставку, render і native-routing + через цю одну можливість замість змішування поведінки approval з не пов’язаними полями плагіна. +- `openclaw/plugin-sdk/channel-runtime` застарів і залишається лише як + compat-shim для старіших плагінів. Новий код має імпортувати вужчі + узагальнені примітиви, а код репозиторію не повинен додавати нові імпорти цього shim. +- Внутрішні механізми комплектних розширень залишаються приватними. Зовнішні плагіни мають використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код core/тестів OpenClaw може використовувати публічні entry point-и репозиторію в корені пакета плагіна, такі як `index.js`, `api.js`, + `runtime-api.js`, `setup-entry.js`, а також вузькоспрямовані файли, наприклад + `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з core або з + іншого розширення. +- Поділ entry point-ів репозиторію: + `/api.js` — це barrel helper-ів/типів, `/runtime-api.js` — це barrel лише для runtime, - `/index.js` — це entry вбудованого plugin, - а `/setup-entry.js` — це entry plugin setup. -- Поточні приклади вбудованих providers: - - Anthropic використовує `api.js` / `contract-api.js` для helpers stream Claude, таких - як `wrapAnthropicProviderStream`, helpers beta-header і парсинг `service_tier`. - - OpenAI використовує `api.js` для builders provider, helpers типової моделі та - builders provider realtime. - - OpenRouter використовує `api.js` для свого builder provider плюс helpers - onboarding/config, тоді як `register.runtime.js` усе ще може реекспортувати загальні - helpers `plugin-sdk/provider-stream` для локального використання в repo. -- Публічні точки входу, завантажені через facade, надають перевагу активному snapshot config runtime, - якщо він існує, а потім повертаються до визначеного config-файлу на диску, - коли OpenClaw ще не надає runtime snapshot. -- Загальні спільні примітиви залишаються бажаним публічним контрактом SDK. Невеликий - зарезервований набір branded helper-швів вбудованих channels усе ще існує. Розглядайте їх як - шви підтримки/сумісності вбудованих компонентів, а не нові цілі імпорту для сторонніх рішень; нові міжканальні контракти, як і раніше, мають з’являтися в - загальних subpaths `plugin-sdk/*` або в локальних barrels `api.js` / - `runtime-api.js` plugin. + `/index.js` — це entry комплектного плагіна, + а `/setup-entry.js` — це entry setup-плагіна. +- Поточні приклади комплектних постачальників: + - Anthropic використовує `api.js` / `contract-api.js` для helper-ів stream Claude, таких + як `wrapAnthropicProviderStream`, helper-и beta-header і парсинг `service_tier`. + - OpenAI використовує `api.js` для builder-ів постачальника, helper-ів моделі за замовчуванням і + builder-ів постачальників realtime. + - OpenRouter використовує `api.js` для builder-а свого постачальника, а також helper-ів onboarding/config, + тоді як `register.runtime.js` усе ще може повторно експортувати узагальнені + helper-и `plugin-sdk/provider-stream` для локального використання в репозиторії. +- Публічні entry point-и, завантажені через facade, віддають перевагу активному snapshot конфігурації runtime, + якщо він існує, а потім переходять до визначеного файла конфігурації на диску, коли + OpenClaw ще не обслуговує runtime snapshot. +- Узагальнені спільні примітиви залишаються бажаним публічним контрактом SDK. Невеликий + зарезервований набір сумісності branded helper-швів комплектних каналів усе ще + існує. Розглядайте їх як шви для супроводу комплектних плагінів/сумісності, а не як нові + цілі імпорту для сторонніх плагінів; нові міжканальні контракти й надалі мають + потрапляти до узагальнених підшляхів `plugin-sdk/*` або локальних barrel-ів `api.js` / + `runtime-api.js` плагіна. Примітка щодо сумісності: -- Уникайте кореневого barrel `openclaw/plugin-sdk` у новому коді. -- Спочатку віддавайте перевагу вузьким стабільним примітивам. Новіші subpaths - setup/pairing/reply/feedback/contract/inbound/threading/command/secret-input/webhook/infra/ - allowlist/status/message-tool — це бажаний контракт для нової роботи - із вбудованими та зовнішніми plugins. - Парсинг/зіставлення targets належить до `openclaw/plugin-sdk/channel-targets`. - Gating дій повідомлень і helpers message-id реакцій належать до +- Для нового коду уникайте кореневого barrel `openclaw/plugin-sdk`. +- Спочатку надавайте перевагу вузьким стабільним примітивам. Новіші підшляхи setup/pairing/reply/ + feedback/contract/inbound/threading/command/secret-input/webhook/infra/ + allowlist/status/message-tool є цільовим контрактом для нової роботи над + комплектними і зовнішніми плагінами. + Парсинг/зіставлення target має належати `openclaw/plugin-sdk/channel-targets`. + Бар’єри дій повідомлень і helper-и message-id для реакцій мають належати `openclaw/plugin-sdk/channel-actions`. -- Допоміжні barrels, специфічні для вбудованих extension, не є стабільними за замовчуванням. Якщо - helper потрібен лише вбудованому extension, залишайте його за локальним швом `api.js` або `runtime-api.js` цього extension замість просування до +- Helper-barrel-и, специфічні для комплектних розширень, не є стабільними за замовчуванням. Якщо + helper потрібен лише комплектному розширенню, тримайте його за локальним швом + `api.js` або `runtime-api.js` цього розширення замість просування до `openclaw/plugin-sdk/`. -- Нові спільні helper-шви мають бути загальними, а не branded за channel. Спільний парсинг - targets належить до `openclaw/plugin-sdk/channel-targets`; channel-специфічні - внутрішні компоненти залишаються за локальним швом `api.js` або `runtime-api.js` plugin-власника. -- Capability-специфічні subpaths, такі як `image-generation`, - `media-understanding` і `speech`, існують, тому що вбудовані/нативні plugins використовують - їх сьогодні. Їхня наявність сама по собі не означає, що кожен експортований helper є - довгостроковим зафіксованим зовнішнім контрактом. +- Нові спільні helper-шви мають бути узагальненими, а не branded за каналом. Спільний парсинг target + належить `openclaw/plugin-sdk/channel-targets`; внутрішні механізми, специфічні для каналу, + залишаються за локальним швом `api.js` або `runtime-api.js` відповідного плагіна. +- Підшляхи, специфічні для можливостей, такі як `image-generation`, + `media-understanding` і `speech`, існують, тому що комплектні/нативні плагіни використовують + їх сьогодні. Їх наявність сама по собі не означає, що кожен експортований helper є + довгостроковим замороженим зовнішнім контрактом. -## Schema tools повідомлень +## Схеми інструмента повідомлень -Plugins повинні володіти channel-специфічними внесками до schema в `describeMessageTool(...)`. -Зберігайте provider-специфічні поля в plugin, а не в спільному core. +Плагіни мають володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу. +Тримайте поля, специфічні для постачальника, у плагіні, а не в спільному core. -Для спільних portable fragments schema використовуйте загальні helpers, що експортуються через +Для спільних переносних фрагментів схеми повторно використовуйте узагальнені helper-и, експортовані через `openclaw/plugin-sdk/channel-actions`: -- `createMessageToolButtonsSchema()` для payload у стилі grid кнопок +- `createMessageToolButtonsSchema()` для payload у стилі сітки кнопок - `createMessageToolCardSchema()` для структурованих payload карток -Якщо форма schema має сенс лише для одного provider, визначайте її у -власному джерелі цього plugin замість просування до спільного SDK. +Якщо форма схеми має сенс лише для одного постачальника, визначайте її у вихідному коді +цього плагіна замість просування до спільного SDK. -## Визначення channel target +## Визначення канальних target -Channel plugins повинні володіти channel-специфічною семантикою target. Зберігайте спільний -outbound host загальним і використовуйте surface messaging adapter для правил provider: +Канальні плагіни мають володіти семантикою target, специфічною для каналу. Тримайте спільний +outbound host узагальненим і використовуйте поверхню адаптера повідомлень для правил постачальника: -- `messaging.inferTargetChatType({ to })` вирішує, чи слід нормалізований target - трактувати як `direct`, `group` або `channel` до lookup у directory. +- `messaging.inferTargetChatType({ to })` вирішує, чи нормалізований target + слід розглядати як `direct`, `group` або `channel` до пошуку в directory. - `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи - слід пропустити одразу до визначення за id-подібним значенням, а не виконувати пошук у directory. -- `messaging.targetResolver.resolveTarget(...)` — це fallback plugin, коли - core потребує фінального provider-owned визначення після нормалізації або - після невдалого пошуку в directory. -- `messaging.resolveOutboundSessionRoute(...)` володіє provider-специфічною побудовою - route session після того, як target визначено. + слід для вводу одразу перейти до визначення за id-подібним значенням замість пошуку в directory. +- `messaging.targetResolver.resolveTarget(...)` — це fallback плагіна, коли + core потребує фінального визначення, що належить постачальнику, після нормалізації або після + промаху в directory. +- `messaging.resolveOutboundSessionRoute(...)` володіє специфічним для постачальника конструюванням + route сесії після визначення target. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для категорійних рішень, які повинні відбуватися до - пошуку peer/group. -- Використовуйте `looksLikeId` для перевірок "сприймати це як явний/нативний id target". -- Використовуйте `resolveTarget` для provider-специфічного fallback нормалізації, а не для +- Використовуйте `inferTargetChatType` для категорійних рішень, які мають ухвалюватися до + пошуку peers/groups. +- Використовуйте `looksLikeId` для перевірок на кшталт «розглядати це як явний/native target id». +- Використовуйте `resolveTarget` для fallback-нормалізації, специфічної для постачальника, а не для широкого пошуку в directory. -- Зберігайте provider-native ids, як-от ids chat, ids thread, JIDs, handles і ids room, - у значеннях `target` або provider-специфічних params, а не в загальних полях SDK. +- Тримайте native id постачальника, такі як chat id, thread id, JID, handle і room + id, усередині значень `target` або параметрів, специфічних для постачальника, а не в узагальнених полях SDK. -## Directories на основі config +## Directory на основі конфігурації -Plugins, які формують entries directory з config, повинні тримати цю логіку в -plugin і повторно використовувати спільні helpers із +Плагіни, які виводять записи directory з конфігурації, мають тримати цю логіку в +плагіні і повторно використовувати спільні helper-и з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли channel потребує peers/groups на основі config, таких як: +Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, такі як: -- DM peers на основі allowlist -- налаштовані карти channels/groups -- статичні fallback-и directory з урахуванням scope облікового запису +- DM peers, керовані allowlist +- налаштовані мапи каналів/груп +- статичні fallback-и directory в межах облікового запису -Спільні helpers у `directory-runtime` обробляють лише загальні операції: +Спільні helper-и в `directory-runtime` обробляють лише узагальнені операції: -- фільтрацію query -- застосування limit -- helpers dedupe/normalization +- фільтрацію запитів +- застосування лімітів +- helper-и deduping/normalization - побудову `ChannelDirectoryEntry[]` -Channel-специфічна перевірка облікового запису та нормалізація id повинні залишатися в реалізації plugin. +Специфічні для каналу перевірка облікового запису та нормалізація id мають залишатися в +реалізації плагіна. -## Catalogs provider +## Каталоги постачальників -Provider plugins можуть визначати catalogs моделей для inference через +Плагіни постачальників можуть визначати каталоги моделей для інференсу через `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує до `models.providers`: -- `{ provider }` для одного запису provider -- `{ providers }` для кількох записів provider +- `{ provider }` для одного запису постачальника +- `{ providers }` для кількох записів постачальників -Використовуйте `catalog`, коли plugin володіє provider-специфічними model ids, типовими -значеннями base URL або metadata моделей, які залежать від auth. +Використовуйте `catalog`, коли плагін володіє специфічними для постачальника model id, базовими значеннями `base URL` або auth-залежними метаданими моделей. -`catalog.order` керує тим, коли catalog plugin зливається відносно вбудованих -неявних providers OpenClaw: +`catalog.order` керує тим, коли каталог плагіна зливається відносно вбудованих +неявних постачальників OpenClaw: -- `simple`: прості providers на основі API key або env -- `profile`: providers, які з’являються, коли існують auth profiles -- `paired`: providers, які синтезують кілька пов’язаних записів provider -- `late`: останній прохід після інших неявних providers +- `simple`: звичайні постачальники на основі API-ключа або env +- `profile`: постачальники, які з’являються, коли існують auth-profile +- `paired`: постачальники, які синтезують кілька пов’язаних записів постачальників +- `late`: останній прохід після інших неявних постачальників -Пізніші providers перемагають у разі конфлікту key, тож plugins можуть навмисно -перевизначати вбудований запис provider з тим самим id provider. +Пізніші постачальники перемагають при колізії ключів, тому плагіни можуть навмисно +перевизначати вбудований запис постачальника з тим самим provider id. Сумісність: - `discovery` усе ще працює як застарілий псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Канальний огляд лише для читання +## Канальна інспекція лише для читання -Якщо ваш plugin реєструє channel, віддавайте перевагу реалізації +Якщо ваш плагін реєструє канал, надавайте перевагу реалізації `plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це runtime-шлях. Він може припускати, що credentials - повністю materialized, і швидко помилятися, якщо обов’язкових secrets бракує. -- Шляхи commands лише для читання, такі як `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` і потоки doctor/config - repair, не повинні потребувати materialization runtime credentials лише для - опису конфігурації. +- `resolveAccount(...)` — це шлях runtime. Він може припускати, що облікові дані + повністю матеріалізовані, і швидко завершуватися помилкою, якщо потрібні секрети відсутні. +- Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`, + `openclaw channels status`, `openclaw channels resolve` та потоки doctor/config + repair, не повинні потребувати матеріалізації runtime-облікових даних лише для того, щоб + описати конфігурацію. Рекомендована поведінка `inspectAccount(...)`: - Повертає лише описовий стан облікового запису. - Зберігає `enabled` і `configured`. -- Включає поля джерела/стану credentials, коли це доречно, такі як: +- Включає поля джерела/стану облікових даних за потреби, такі як: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність лише для читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле source) для commands у стилі status. -- Використовуйте `configured_unavailable`, коли credential налаштовано через SecretRef, але він недоступний у поточному шляху command. +- Вам не потрібно повертати сирі значення токенів лише для звіту про доступність у режимі лише читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). +- Використовуйте `configured_unavailable`, коли облікові дані налаштовані через SecretRef, але + недоступні в поточному шляху команди. -Це дозволяє commands лише для читання повідомляти "налаштовано, але недоступно в цьому шляху command" замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. +Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або неправильного повідомлення, що обліковий запис не налаштовано. -## Package packs +## Пакетні набори -Directory plugin може містити `package.json` з `openclaw.extensions`: +Каталог плагіна може містити `package.json` з `openclaw.extensions`: ```json { @@ -1316,61 +1323,62 @@ Directory plugin може містити `package.json` з `openclaw.extensions` } ``` -Кожен entry стає plugin. Якщо pack перелічує кілька extension, id plugin +Кожен запис стає плагіном. Якщо набір містить кілька розширень, id плагіна стає `name/`. -Якщо ваш plugin імпортує залежності npm, установіть їх у цій directory, щоб +Якщо ваш плагін імпортує npm-залежності, встановіть їх у цьому каталозі, щоб `node_modules` був доступний (`npm install` / `pnpm install`). -Захисне правило безпеки: кожен entry `openclaw.extensions` повинен залишатися в межах directory plugin -після визначення symlink. Entries, які виходять за межі directory package, відхиляються. +Бар’єр безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу плагіна +після визначення symlink. Записи, які виходять за межі каталогу пакета, відхиляються. -Примітка щодо безпеки: `openclaw plugins install` установлює залежності plugin через -`npm install --omit=dev --ignore-scripts` (без lifecycle scripts і без dev dependencies у runtime). Зберігайте дерева залежностей plugin як "pure JS/TS" і уникайте package, які потребують збірок через `postinstall`. +Примітка щодо безпеки: `openclaw plugins install` встановлює залежності плагіна через +`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей у runtime). Тримайте дерева залежностей плагіна «чистими JS/TS» й уникайте пакетів, яким потрібні `postinstall`-збирання. -Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup. -Коли OpenClaw потребує surfaces setup для вимкненого channel plugin або -коли channel plugin увімкнений, але ще не налаштований, він завантажує `setupEntry` -замість повного entry plugin. Це робить запуск і setup легшими, -коли ваш основний entry plugin також підключає tools, hooks чи інший код лише для runtime. +Необов’язково: `openclaw.setupEntry` може вказувати на полегшений модуль лише для setup. +Коли OpenClaw потребує setup-поверхонь для вимкненого канального плагіна або +коли канальний плагін увімкнений, але ще не налаштований, він завантажує `setupEntry` +замість повного entry плагіна. Це робить запуск і setup легшими, +коли основний entry плагіна також підключає інструменти, hooks або інший код лише для runtime. Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести channel plugin на той самий шлях `setupEntry` під час фази -запуску gateway до listen, навіть якщо channel уже налаштовано. +може перевести канальний плагін на той самий шлях `setupEntry` під час +фази запуску gateway до `listen`, навіть коли канал уже налаштований. -Використовуйте це лише тоді, коли `setupEntry` повністю покриває startup-surface, яка має існувати +Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати до того, як gateway почне слухати. На практиці це означає, що entry setup -повинен реєструвати всі можливості channel-власника, від яких залежить запуск, такі як: +має реєструвати всі можливості каналу, від яких залежить запуск, наприклад: -- сама реєстрація channel -- будь-які HTTP routes, які мають бути доступні до того, як gateway почне слухати -- будь-які methods, tools або services gateway, які мають існувати в тому ж вікні часу +- саму реєстрацію каналу +- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне слухати +- будь-які методи gateway, інструменти або сервіси, які мають існувати в тому ж вікні -Якщо ваш повний entry усе ще володіє будь-якою обов’язковою startup-можливістю, не вмикайте -цей flag. Залишайте plugin на типовій поведінці й дозвольте OpenClaw завантажити +Якщо будь-яка потрібна для запуску можливість усе ще належить повному entry, не вмикайте +цей прапорець. Залишайте плагін на типовій поведінці й дозвольте OpenClaw завантажити повний entry під час запуску. -Вбудовані channels також можуть публікувати helpers contract-surface лише для setup, до яких core -може звертатися до завантаження повного runtime channel. Поточна surface setup promotion така: +Комплектні канали також можуть публікувати helper-и поверхні контракту лише для setup, до яких core +може звертатися до завантаження повного runtime каналу. Поточна поверхня підвищення setup така: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Core використовує цю surface, коли йому потрібно підвищити застарілу -конфігурацію single-account channel до `channels..accounts.*` без завантаження -повного entry plugin. Matrix — поточний вбудований приклад: він переносить лише -keys auth/bootstrap до іменованого підвищеного облікового запису, коли іменовані облікові записи вже існують, і -може зберігати налаштований неканонічний key default-account замість того, щоб завжди створювати +Core використовує цю поверхню, коли йому потрібно підвищити застарілу конфігурацію +одноканального облікового запису до `channels..accounts.*` без завантаження повного entry плагіна. +Поточний комплектний приклад — Matrix: він переносить лише ключі auth/bootstrap до +іменованого підвищеного облікового запису, коли іменовані облікові записи вже існують, і може +зберегти налаштований неканонічний ключ default-account замість того, щоб завжди створювати `accounts.default`. -Ці adapters патчів setup зберігають lazy-виявлення contract-surface вбудованих компонентів. Час import -залишається малим; surface promotion завантажується лише під час першого використання замість повторного входу у startup вбудованого channel при import module. +Ці setup patch adapters зберігають lazy-виявлення поверхні контракту комплектного плагіна. +Час імпорту залишається малим; поверхня підвищення завантажується лише при першому +використанні замість повторного входу в запуск комплектного каналу під час імпорту модуля. -Коли ці startup surfaces включають methods Gateway RPC, зберігайте їх під -plugin-специфічним prefix. Простори імен admin core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди визначаються -як `operator.admin`, навіть якщо plugin запитує вужчий scope. +Коли ці поверхні запуску містять методи Gateway RPC, тримайте їх у +префіксі, специфічному для плагіна. Простори імен admin у core (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються +як `operator.admin`, навіть якщо плагін запитує вужчий scope. Приклад: @@ -1387,10 +1395,10 @@ plugin-специфічним prefix. Простори імен admin core (`con } ``` -### Metadata catalog channel +### Метадані каталогу каналів -Channel plugins можуть оголошувати metadata setup/discovery через `openclaw.channel` і -підказки install через `openclaw.install`. Це дозволяє залишати data-free у core catalog. +Канальні плагіни можуть оголошувати метадані setup/discovery через `openclaw.channel`, а +підказки встановлення — через `openclaw.install`. Це дозволяє core залишатися без даних каталогу. Приклад: @@ -1418,38 +1426,41 @@ Channel plugins можуть оголошувати metadata setup/discovery ч } ``` -Корисні поля `openclaw.channel` поза мінімальним прикладом: +Корисні поля `openclaw.channel`, окрім мінімального прикладу: -- `detailLabel`: вторинний label для багатших surfaces catalog/status -- `docsLabel`: перевизначення тексту посилання на docs -- `preferOver`: ids plugin/channel нижчого пріоритету, які цей запис catalog має випереджати -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: керування copy для surfaces selection -- `markdownCapable`: позначає channel як сумісний із markdown для рішень щодо outbound formatting -- `showConfigured`: приховує channel із surfaces списку налаштованих channels, якщо встановлено `false` -- `quickstartAllowFrom`: включає channel до стандартного потоку quickstart `allowFrom` -- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть якщо існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: віддає перевагу lookup session під час визначення announce targets +- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу +- `docsLabel`: перевизначає текст посилання на docs +- `preferOver`: id плагінів/каналів нижчого пріоритету, які цей запис каталогу має випереджати +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування копією поверхні вибору +- `markdownCapable`: позначає канал як сумісний із markdown для рішень форматування outbound +- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` +- `exposure.setup`: приховує канал з інтерактивних picker-ів setup/configure, якщо встановлено `false` +- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації docs +- `showConfigured` / `showInSetup`: застарілі псевдоніми все ще приймаються для сумісності; віддавайте перевагу `exposure` +- `quickstartAllowFrom`: підключає канал до стандартного потоку quickstart `allowFrom` +- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення announce-target -OpenClaw також може зливати **зовнішні catalogs channels** (наприклад, експорт реєстру MPM). -Помістіть JSON-файл в одне з таких місць: +OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт +реєстру MPM). Помістіть JSON-файл в один із шляхів: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на -один чи кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл повинен -містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Parser також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для key `"entries"`. +один чи кілька JSON-файлів (розділених комами/крапками з комою/`PATH`). Кожен файл має +містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. -## Plugins context engine +## Плагіни рушія контексту -Plugins context engine володіють orchestration контексту session для ingest, assembly -і compaction. Реєструйте їх зі свого plugin через -`api.registerContextEngine(id, factory)`, а потім вибирайте активний engine через +Плагіни рушія контексту володіють оркестрацією контексту сесії для ingest, assemble +та compaction. Реєструйте їх зі свого плагіна через +`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через `plugins.slots.contextEngine`. -Використовуйте це, коли вашому plugin потрібно замінити або розширити типову -конвеєрну обробку context, а не просто додати memory search або hooks. +Використовуйте це, коли вашому плагіну потрібно замінити або розширити типовий +конвеєр контексту, а не просто додати пошук у пам’яті чи hooks. ```ts export default function (api) { @@ -1468,7 +1479,7 @@ export default function (api) { } ``` -Якщо ваш engine **не** володіє алгоритмом compaction, залишайте `compact()` +Якщо ваш рушій **не** володіє алгоритмом compaction, залишайте `compact()` реалізованим і явно делегуйте його: ```ts @@ -1496,46 +1507,46 @@ export default function (api) { ## Додавання нової можливості -Коли plugin потребує поведінки, яка не вписується в поточний API, не обходьте -систему plugin приватним прямим зверненням. Додайте відсутню можливість. +Коли плагіну потрібна поведінка, яка не вписується в поточний API, не оминайте +систему плагінів приватним зверненням усередину. Додайте відсутню можливість. Рекомендована послідовність: 1. визначити контракт core - Вирішіть, якою спільною поведінкою має володіти core: policy, fallback, злиття config, - lifecycle, channel-facing semantics і форма runtime helper. -2. додати типізовані surfaces реєстрації/runtime plugin - Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною - типізованою surface можливості. -3. підключити core + споживачів channels/features - Channels і feature plugins повинні використовувати нову можливість через core, - а не напряму імпортувати реалізацію vendor. -4. зареєструвати реалізації vendor - Потім plugins vendor реєструють свої backend для цієї можливості. + Вирішіть, якою спільною поведінкою має володіти core: політика, fallback, злиття config, + життєвий цикл, семантика для каналів і форма runtime-helper-ів. +2. додати типізовані поверхні реєстрації/runtime для плагінів + Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною + типізованою поверхнею можливості. +3. підключити core та споживачів каналів/функцій + Канали й функціональні плагіни мають споживати нову можливість через core, + а не через прямий імпорт реалізації постачальника. +4. зареєструвати реалізації постачальників + Тоді плагіни постачальників реєструють свої бекенди для цієї можливості. 5. додати покриття контракту - Додайте тести, щоб володіння і форма реєстрації з часом залишалися явними. + Додайте тести, щоб володіння та форма реєстрації з часом залишалися явними. -Саме так OpenClaw залишається виразним, не стаючи жорстко прив’язаним до -світогляду одного provider. Див. [Capability Cookbook](/uk/plugins/architecture) -для конкретного контрольного списку файлів і пропрацьованого прикладу. +Саме так OpenClaw залишається opinionated, не стаючи жорстко прив’язаним до +світогляду одного постачальника. Див. [Capability Cookbook](/uk/plugins/architecture) +для конкретного списку файлів і готового прикладу. ### Контрольний список можливості -Коли ви додаєте нову можливість, реалізація зазвичай повинна одночасно торкатися -таких surfaces: +Коли ви додаєте нову можливість, реалізація зазвичай має разом охоплювати такі +поверхні: - типи контрактів core у `src//types.ts` -- runner/runtime helper core у `src//runtime.ts` -- surface реєстрації API plugin у `src/plugins/types.ts` -- підключення реєстру plugin у `src/plugins/registry.ts` -- відкриття runtime plugin у `src/plugins/runtime/*`, коли feature/channel - plugins мають її використовувати -- helpers capture/test у `src/test-utils/plugin-registration.ts` -- перевірки володіння/контрактів у `src/plugins/contracts/registry.ts` -- docs для операторів/plugin у `docs/` +- core-runner/runtime-helper у `src//runtime.ts` +- поверхню реєстрації API плагіна у `src/plugins/types.ts` +- підключення реєстру плагінів у `src/plugins/registry.ts` +- відкриття runtime плагінів у `src/plugins/runtime/*`, коли її мають споживати функціональні/канальні + плагіни +- helper-и capture/test у `src/test-utils/plugin-registration.ts` +- перевірки володіння/контракту в `src/plugins/contracts/registry.ts` +- документацію для операторів/плагінів у `docs/` -Якщо якоїсь із цих surfaces бракує, це зазвичай означає, що можливість -ще не повністю інтегрована. +Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість ще не +повністю інтегрована. ### Шаблон можливості @@ -1571,9 +1582,9 @@ const clip = await api.runtime.videoGeneration.generate({ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); ``` -Це зберігає просте правило: +Це зберігає правило простим: -- core володіє capability-контрактом + orchestration -- plugins vendor володіють vendor-реалізаціями -- feature/channel plugins використовують runtime helpers -- тести контрактів зберігають явність володіння +- core володіє контрактом можливості + оркестрацією +- плагіни постачальників володіють реалізаціями постачальників +- функціональні/канальні плагіни споживають runtime-helper-и +- тести контрактів зберігають явне володіння diff --git a/docs/uk/plugins/sdk-migration.md b/docs/uk/plugins/sdk-migration.md index a779c9b1b..2c8f549ab 100644 --- a/docs/uk/plugins/sdk-migration.md +++ b/docs/uk/plugins/sdk-migration.md @@ -2,91 +2,83 @@ read_when: - Ви бачите попередження OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - Ви бачите попередження OPENCLAW_EXTENSION_API_DEPRECATED - - Ви оновлюєте плагін до сучасної архітектури плагінів - - Ви підтримуєте зовнішній плагін OpenClaw + - Ви оновлюєте plugin до сучасної архітектури plugin + - Ви підтримуєте зовнішній plugin OpenClaw sidebarTitle: Migrate to SDK -summary: Перейдіть із застарілого шару зворотної сумісності на сучасний SDK плагінів -title: Міграція SDK плагінів +summary: Перейдіть із застарілого шару зворотної сумісності на сучасний Plugin SDK +title: Міграція Plugin SDK x-i18n: - generated_at: "2026-04-05T21:47:20Z" + generated_at: "2026-04-05T22:37:55Z" model: gpt-5.4 provider: openai - source_hash: d2a0f2501484b224a1f5b87dc66e9bef1dcb9d3225aaeefe711ed94bf70b6a16 + source_hash: 23fd97ccf58e626ea4be4ae36d060cb963e13f14036cd82d2a86b7dc631ec8f1 source_path: plugins/sdk-migration.md workflow: 15 --- -# Міграція SDK плагінів +# Міграція Plugin SDK OpenClaw перейшов від широкого шару зворотної сумісності до сучасної -архітектури плагінів зі сфокусованими, задокументованими імпортами. Якщо ваш -плагін було створено до появи нової архітектури, цей посібник допоможе вам -виконати міграцію. +архітектури plugin із цільовими, задокументованими імпортами. Якщо ваш plugin +було створено до появи нової архітектури, цей посібник допоможе вам +перейти на неї. ## Що змінюється -Стара система плагінів надавала дві надто широкі поверхні, які дозволяли -плагінам імпортувати все, що їм потрібно, з єдиної точки входу: +Стара система plugin надавала дві широко відкриті поверхні, які дозволяли plugin +імпортувати все, що їм потрібно, з однієї точки входу: -- **`openclaw/plugin-sdk/compat`** — єдиний імпорт, який повторно експортував - десятки допоміжних засобів. Його було запроваджено, щоб старі плагіни на - основі хуків продовжували працювати, поки будувалася нова архітектура - плагінів. -- **`openclaw/extension-api`** — міст, який надавав плагінам прямий доступ до - допоміжних засобів на стороні хоста, як-от вбудований запускальник агента. +- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки + допоміжних засобів. Його було введено, щоб старі plugin на основі hook + продовжували працювати, поки створювалася нова архітектура plugin. +- **`openclaw/extension-api`** — міст, який надавав plugin прямий доступ до + допоміжних засобів на стороні хоста, як-от вбудований засіб запуску agent. -Обидві поверхні тепер **застарілі**. Вони досі працюють під час виконання, але -нові плагіни не повинні їх використовувати, а наявним плагінам слід -перейти на нові механізми до того, як у наступному великому випуску їх буде -видалено. +Обидві поверхні тепер **застарілі**. Вони все ще працюють під час виконання, але нові +plugin не повинні їх використовувати, а наявним plugin слід перейти на нові +механізми до того, як наступний мажорний реліз їх видалить. - Шар зворотної сумісності буде видалено в одному з майбутніх великих випусків. - Плагіни, які все ще імпортують із цих поверхонь, перестануть працювати, - коли це станеться. + Шар зворотної сумісності буде видалено в одному з майбутніх мажорних релізів. + Plugin, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться. ## Чому це змінилося -Старий підхід спричиняв проблеми: +Старий підхід створював проблеми: -- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки - не пов’язаних між собою модулів -- **Циклічні залежності** — широкі повторні експорти спрощували створення - циклів імпорту -- **Неясна поверхня API** — не було способу зрозуміти, які експорти є - стабільними, а які внутрішніми +- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки не пов’язаних між собою модулів +- **Циклічні залежності** — широкі повторні експорти спрощували створення циклів імпорту +- **Нечітка поверхня API** — не було способу зрозуміти, які експорти є стабільними, а які внутрішніми -Сучасний SDK плагінів вирішує це: кожен шлях імпорту (`openclaw/plugin-sdk/\`) -є невеликим, самодостатнім модулем із чітким призначенням і задокументованим -контрактом. +Сучасний Plugin SDK вирішує це: кожен шлях імпорту (`openclaw/plugin-sdk/\`) +є невеликим, самодостатнім модулем із чітким призначенням і задокументованим контрактом. -Застарілі зручні шви провайдера для вбудованих каналів також зникли. Імпорти +Застарілі зручні шви provider для вбудованих каналів також зникли. Імпорти на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, -допоміжні шви з брендингом каналів і -`openclaw/plugin-sdk/telegram-core` були приватними скороченнями для -монорепозиторію, а не стабільними контрактами плагінів. Натомість -використовуйте вузькі загальні підшляхи SDK. Усередині вбудованого робочого -простору плагінів зберігайте допоміжні засоби, що належать провайдеру, у -власному `api.ts` або `runtime-api.ts` цього плагіна. +канально-брендовані допоміжні шви та +`openclaw/plugin-sdk/telegram-core` були приватними скороченнями монорепозиторію, а не +стабільними контрактами plugin. Натомість використовуйте вузькі загальні підшляхи SDK. Усередині +робочого простору вбудованих plugin зберігайте допоміжні засоби, що належать provider, у власних +`api.ts` або `runtime-api.ts` цього plugin. -Поточні приклади вбудованих провайдерів: +Поточні приклади вбудованих provider: -- Anthropic зберігає допоміжні засоби потокової передачі, специфічні для - Claude, у власному шві `api.ts` / `contract-api.ts` -- OpenAI зберігає конструктори провайдерів, допоміжні засоби для моделей за - замовчуванням і конструктори провайдерів реального часу у власному `api.ts` -- OpenRouter зберігає конструктор провайдера та допоміжні засоби для - онбордингу/конфігурації у власному `api.ts` +- Anthropic зберігає допоміжні засоби потоків, специфічні для Claude, у власному шві `api.ts` / + `contract-api.ts` +- OpenAI зберігає білдери provider, допоміжні засоби моделей за замовчуванням і білдери realtime provider + у власному `api.ts` +- OpenRouter зберігає білдер provider та допоміжні засоби onboarding/config у власному + `api.ts` ## Як виконати міграцію - - Якщо ваш плагін використовує `openclaw/plugin-sdk/windows-spawn`, невизначені - обгортки Windows `.cmd`/`.bat` тепер завершуються без резервного варіанта, - якщо ви явно не передасте `allowShellFallback: true`. + + Якщо ваш plugin використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані Windows- + обгортки `.cmd`/`.bat` тепер завершуються у закритому режимі, якщо ви явно не передасте + `allowShellFallback: true`. ```typescript // Before @@ -101,14 +93,13 @@ OpenClaw перейшов від широкого шару зворотної с }); ``` - Якщо ваш викликаючий код не покладається навмисно на резервний варіант - через оболонку, не встановлюйте `allowShellFallback` і натомість обробіть - викинуту помилку. + Якщо ваш викликаючий код не покладається навмисно на резервний перехід через оболонку, не встановлюйте + `allowShellFallback` і натомість обробляйте викинуту помилку. - Знайдіть у своєму плагіні імпорти з будь-якої із застарілих поверхонь: + Знайдіть у своєму plugin імпорти з будь-якої з двох застарілих поверхонь: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -117,7 +108,7 @@ OpenClaw перейшов від широкого шару зворотної с - + Кожен експорт зі старої поверхні відповідає певному сучасному шляху імпорту: ```typescript @@ -134,8 +125,8 @@ OpenClaw перейшов від широкого шару зворотної с import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Для допоміжних засобів на стороні хоста використовуйте впроваджене - середовище виконання плагіна замість прямого імпорту: + Для допоміжних засобів на стороні хоста використовуйте інжектований runtime plugin замість + прямого імпорту: ```typescript // Before (deprecated extension-api bridge) @@ -146,8 +137,7 @@ OpenClaw перейшов від широкого шару зворотної с const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Такий самий шаблон застосовується до інших застарілих допоміжних засобів - мосту: + Такий самий шаблон застосовується й до інших застарілих допоміжних засобів bridge: | Старий імпорт | Сучасний еквівалент | | --- | --- | @@ -157,7 +147,7 @@ OpenClaw перейшов від широкого шару зворотної с | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | допоміжні засоби сховища сесій | `api.runtime.agent.session.*` | + | допоміжні засоби сховища session | `api.runtime.agent.session.*` | @@ -174,164 +164,163 @@ OpenClaw перейшов від широкого шару зворотної с | Шлях імпорту | Призначення | Ключові експорти | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу плагіна | `definePluginEntry` | - | `plugin-sdk/core` | Застарілий узагальнений повторний експорт для визначень/конструкторів точок входу каналів | `defineChannelPluginEntry`, `createChatChannelPlugin` | - | `plugin-sdk/config-schema` | Експорт кореневої схеми конфігурації | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного провайдера | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Сфокусовані визначення та конструктори точок входу каналів | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Запити списку дозволених, конструктори стану налаштування | - | `plugin-sdk/setup-runtime` | Допоміжні засоби середовища виконання для етапу налаштування | Безпечні для імпорту адаптери патчів налаштування, допоміжні засоби приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | + | `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу plugin | `definePluginEntry` | + | `plugin-sdk/core` | Застарілий зонтичний повторний експорт для визначень/білдерів точок входу каналів | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/config-schema` | Експорт кореневої схеми config | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного provider | `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` | Допоміжні засоби для ідентифікатора облікового запису | `DEFAULT_ACCOUNT_ID`, нормалізація ідентифікатора облікового запису | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису | Допоміжні засоби пошуку облікового запису + резервного значення за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для облікових записів | Допоміжні засоби списку облікових записів/дій з обліковими записами | + | `plugin-sdk/account-core` | Допоміжні засоби для багатьох облікових записів | Допоміжні засоби списку облікових записів/config/шлюзу дій | + | `plugin-sdk/account-id` | Допоміжні засоби ідентифікатора облікового запису | `DEFAULT_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 | `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-pairing` | Примітиви pair для DM | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | Префікс відповіді + логіка індикації набору | `createChannelReplyPipeline` | + | `plugin-sdk/channel-config-helpers` | Фабрики адаптерів config | `createHybridChannelConfigAdapter` | + | `plugin-sdk/channel-config-schema` | Білдери схем config | Типи схем config каналу | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби config команд Telegram | Нормалізація назв команд, обрізання описів, валідація дублікатів/конфліктів | | `plugin-sdk/channel-policy` | Визначення політики груп/DM | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | Відстеження стану облікового запису | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Допоміжні засоби для вхідного конверта | Спільні допоміжні засоби маршруту + побудови конверта | + | `plugin-sdk/inbound-envelope` | Допоміжні засоби вхідного 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/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти середовища виконання каналу | + | `plugin-sdk/messaging-targets` | Аналіз цілей повідомлень | Допоміжні засоби аналізу/зіставлення цілей | + | `plugin-sdk/outbound-media` | Допоміжні засоби вихідного media | Спільне завантаження вихідного media | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідного runtime | Допоміжні засоби ідентичності вихідних повідомлень/делегування надсилання | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби прив’язки thread | Життєвий цикл прив’язки thread та допоміжні засоби адаптера | + | `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби media payload | Білдер media payload agent для застарілих макетів полів | + | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти runtime каналу | | `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів відповіді | - | `plugin-sdk/runtime-store` | Постійне сховище плагіна | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Широкі допоміжні засоби середовища виконання | Допоміжні засоби runtime/логування/резервного копіювання/встановлення плагіна | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби оточення runtime | Допоміжні засоби логера/оточення runtime, таймаутів, повторів і backoff | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби runtime плагіна | Допоміжні засоби команд/хуків/http/інтерактивної взаємодії плагіна | - | `plugin-sdk/hook-runtime` | Допоміжні засоби конвеєра хуків | Спільні допоміжні засоби конвеєра webhook/внутрішніх хуків | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби відкладеного runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/runtime-store` | Постійне сховище plugin | `createPluginRuntimeStore` | + | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime | Допоміжні засоби runtime/logging/backup/інсталяції plugin | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби середовища runtime | Logger/runtime env, допоміжні засоби timeout, retry і backoff | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби runtime plugin | Допоміжні засоби plugin для command/hooks/http/interactive | + | `plugin-sdk/hook-runtime` | Допоміжні засоби конвеєра hook | Спільні допоміжні засоби конвеєра webhook/внутрішнього 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 і допоміжні засоби патчів стану каналу | - | `plugin-sdk/config-runtime` | Допоміжні засоби конфігурації | Допоміжні засоби завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби перевірки команд Telegram зі стабільним резервним варіантом, коли поверхня контракту вбудованого Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні засоби запитів на погодження | Навантаження погодження exec/плагіна, допоміжні засоби можливостей/профілю погодження, нативна маршрутизація/середовище виконання погодження | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби автентифікації погодження | Визначення затверджувача, автентифікація дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта погодження | Допоміжні засоби профілю/фільтра нативного погодження exec | - | `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби доставки погодження | Адаптери можливостей/доставки нативного погодження | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей погодження | Допоміжні засоби прив’язування цілей/облікових записів нативного погодження | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби відповідей на погодження | Допоміжні засоби навантаження відповіді погодження exec/плагіна | - | `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби довіри, шлюзування DM, зовнішнього вмісту та збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Допоміжні засоби списку дозволених хостів і політики приватної мережі | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби SSRF runtime | Закріплений dispatcher, guarded fetch, допоміжні засоби політики SSRF | - | `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого кешу | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби шлюзування діагностики | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби gateway | Клієнт gateway і допоміжні засоби patch стану каналу | + | `plugin-sdk/config-runtime` | Допоміжні засоби config | Допоміжні засоби завантаження/запису config | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби валідації команд Telegram зі стабільним резервним режимом, коли поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/approval-runtime` | Допоміжні засоби запиту approval | Допоміжні засоби payload approval exec/plugin, можливостей/профілів approval, нативної маршрутизації/runtime approval | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби auth для approval | Визначення approver, auth дій у тому самому chat | + | `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта approval | Допоміжні засоби профілів/фільтрів нативного approval exec | + | `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби доставки approval | Адаптери можливостей/доставки нативного approval | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей approval | Допоміжні засоби прив’язки цілей/облікових записів нативного approval | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби відповідей approval | Допоміжні засоби payload відповідей approval exec/plugin | + | `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби trust, шлюзування DM, зовнішнього контенту та збирання secret | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Допоміжні засоби allowlist хостів і політики приватної мережі | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби SSRF runtime | Допоміжні засоби pinned-dispatcher, guarded fetch, SSRF policy | + | `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого cache | `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` | Допоміжні засоби повтору | `RetryConfig`, `retryAsync`, виконавці політик | - | `plugin-sdk/allow-from` | Форматування списку дозволених | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Мапування вхідних даних списку дозволених | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Допоміжні засоби шлюзування команд і поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд | - | `plugin-sdk/secret-input` | Розбір секретного вводу | Допоміжні засоби секретного вводу | + | `plugin-sdk/retry-runtime` | Допоміжні засоби retry | `RetryConfig`, `retryAsync`, виконавці політик | + | `plugin-sdk/allow-from` | Форматування allowlist | `formatAllowFromLowercase` | + | `plugin-sdk/allowlist-resolution` | Зіставлення вхідних даних allowlist | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Шлюзування command і допоміжні засоби поверхні command | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру command | + | `plugin-sdk/secret-input` | Аналіз введення secret | Допоміжні засоби введення secret | | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів webhook | Утиліти цілей webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби захисту запитів webhook | Допоміжні засоби читання/обмеження тіла запиту | - | `plugin-sdk/reply-runtime` | Спільне середовище виконання відповіді | Вхідна диспетчеризація, heartbeat, планувальник відповіді, розбиття на частини | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації відповіді | Допоміжні засоби фіналізації + диспетчеризації провайдера | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби guard для тіла webhook | Допоміжні засоби читання/обмеження тіла запиту | + | `plugin-sdk/reply-runtime` | Спільний runtime відповідей | Вхідна диспетчеризація, heartbeat, планувальник відповідей, chunking | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації відповідей | Допоміжні засоби завершення + диспетчеризації provider | | `plugin-sdk/reply-history` | Допоміжні засоби історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | Планування посилань на відповіді | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Допоміжні засоби розбиття відповіді | Допоміжні засоби розбиття тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій | Допоміжні засоби шляху сховища + updated-at | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів стану | Допоміжні засоби каталогів стану та OAuth | - | `plugin-sdk/routing` | Допоміжні засоби маршрутизації/ключів сесії | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні засоби нормалізації ключа сесії | - | `plugin-sdk/status-helpers` | Допоміжні засоби стану каналу | Конструктори зведень стану каналу/облікового запису, типові значення runtime-state, допоміжні засоби метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Допоміжні засоби визначення цілей | Спільні допоміжні засоби визначення цілей | + | `plugin-sdk/reply-reference` | Планування посилань відповіді | `createReplyReferencePlanner` | + | `plugin-sdk/reply-chunking` | Допоміжні засоби chunk відповіді | Допоміжні засоби chunking тексту/markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища session | Допоміжні засоби шляхів сховища + updated-at | + | `plugin-sdk/state-paths` | Допоміжні засоби шляхів state | Допоміжні засоби каталогів state та OAuth | + | `plugin-sdk/routing` | Допоміжні засоби routing/ключів session | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні засоби нормалізації ключів session | + | `plugin-sdk/status-helpers` | Допоміжні засоби стану каналу | Білдери підсумків стану каналу/облікового запису, значення runtime-state за замовчуванням, допоміжні засоби метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Допоміжні засоби визначення цілі | Спільні допоміжні засоби визначення цілі | | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації рядків | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Допоміжні засоби URL запитів | Витяг рядкових URL із request-подібних вхідних даних | - | `plugin-sdk/run-command` | Допоміжні засоби команд із таймаутом | Виконавець команд із таймаутом і нормалізованими stdout/stderr | - | `plugin-sdk/param-readers` | Зчитувачі параметрів | Поширені зчитувачі параметрів інструментів/CLI | - | `plugin-sdk/tool-send` | Витягування надсилання інструмента | Витяг канонічних полів цілі надсилання з аргументів інструмента | - | `plugin-sdk/temp-path` | Допоміжні засоби тимчасових шляхів | Спільні допоміжні засоби шляху тимчасового завантаження | - | `plugin-sdk/logging-core` | Допоміжні засоби логування | Логер підсистеми й допоміжні засоби редагування | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби markdown-таблиць | Допоміжні засоби режиму markdown-таблиць | - | `plugin-sdk/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` | Допоміжні засоби runtime-автентифікації провайдера | Допоміжні засоби визначення API-ключа під час виконання | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключа провайдера | Допоміжні засоби онбордингу/запису профілю API-ключа | - | `plugin-sdk/provider-auth-result` | Допоміжні засоби результату автентифікації провайдера | Стандартний конструктор результату OAuth-автентифікації | - | `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу провайдера | Спільні допоміжні засоби інтерактивного входу | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби змінних середовища провайдера | Допоміжні засоби пошуку auth env vars провайдера | - | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделі/повторного відтворення провайдера | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політики повторного відтворення, допоміжні засоби endpoint провайдера та нормалізації ідентифікатора моделі | - | `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` | Допоміжні засоби web-search провайдера | Допоміжні засоби реєстрації/кешу/конфігурації провайдера web-search | - | `plugin-sdk/provider-tools` | Допоміжні засоби сумісності інструментів/схем провайдера | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Допоміжні засоби використання провайдера | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби використання провайдера | - | `plugin-sdk/provider-stream` | Допоміжні засоби обгортки потоку провайдера | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоку та спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/keyed-async-queue` | Упорядкована асинхронна черга | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби медіа | Допоміжні засоби отримання/перетворення/зберігання медіа плюс конструктори медіанавантаження | - | `plugin-sdk/media-understanding` | Допоміжні засоби media-understanding | Типи провайдера media understanding плюс орієнтовані на провайдера експорти допоміжних засобів зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення видимого для асистента тексту, рендеринг/розбиття/таблиці markdown, редагування, допоміжні засоби тегів директив, утиліти безпечного тексту та пов’язані допоміжні засоби тексту/логування | - | `plugin-sdk/text-chunking` | Допоміжні засоби розбиття тексту | Допоміжний засіб розбиття вихідного тексту | - | `plugin-sdk/speech` | Допоміжні засоби speech | Типи speech-провайдера плюс орієнтовані на провайдера допоміжні засоби директив, реєстру та перевірки | - | `plugin-sdk/speech-core` | Спільне ядро speech | Типи speech-провайдера, реєстр, директиви, нормалізація | - | `plugin-sdk/realtime-transcription` | Допоміжні засоби транскрипції в реальному часі | Типи провайдера та допоміжні засоби реєстру | - | `plugin-sdk/realtime-voice` | Допоміжні засоби голосу в реальному часі | Типи провайдера та допоміжні засоби реєстру | - | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Допоміжні засоби типів, failover, auth і реєстру для генерації зображень | - | `plugin-sdk/video-generation` | Допоміжні засоби генерації відео | Типи провайдера/запиту/результату генерації відео | - | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Допоміжні засоби типів генерації відео, failover, пошуку провайдера та розбору model-ref | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивних відповідей | Нормалізація/скорочення навантаження інтерактивних відповідей | - | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви schema конфігурації каналу | - | `plugin-sdk/channel-config-writes` | Допоміжні засоби запису конфігурації каналу | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільна преамбула каналу | Експорти спільної преамбули плагіна каналу | - | `plugin-sdk/channel-status` | Допоміжні засоби стану каналу | Спільні допоміжні засоби знімка/зведення стану каналу | - | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби конфігурації списку дозволених | Допоміжні засоби редагування/читання конфігурації списку дозволених | - | `plugin-sdk/group-access` | Допоміжні засоби доступу до груп | Спільні допоміжні засоби рішень щодо доступу до груп | - | `plugin-sdk/direct-dm` | Допоміжні засоби прямих DM | Спільні допоміжні засоби auth/guard для прямих DM | - | `plugin-sdk/extension-shared` | Спільні допоміжні засоби розширення | Примітиви допоміжних засобів пасивного каналу/стану | + | `plugin-sdk/request-url` | Допоміжні засоби URL запиту | Отримання рядкових URL з вхідних даних, подібних до request | + | `plugin-sdk/run-command` | Допоміжні засоби timed command | Виконавець timed command із нормалізованими stdout/stderr | + | `plugin-sdk/param-readers` | Зчитувачі param | Загальні зчитувачі param для tool/CLI | + | `plugin-sdk/tool-send` | Витягування надсилання tool | Витягування канонічних полів цілі надсилання з аргументів tool | + | `plugin-sdk/temp-path` | Допоміжні засоби тимчасових шляхів | Спільні допоміжні засоби шляхів тимчасового завантаження | + | `plugin-sdk/logging-core` | Допоміжні засоби logging | Logger підсистеми та допоміжні засоби редагування | + | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби таблиць Markdown | Допоміжні засоби режимів таблиць Markdown | + | `plugin-sdk/reply-payload` | Типи payload відповіді | Типи payload відповіді | + | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локального/self-hosted provider | Допоміжні засоби виявлення/config self-hosted provider | + | `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні засоби налаштування self-hosted provider, сумісного з OpenAI | Ті самі допоміжні засоби виявлення/config self-hosted provider | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби auth runtime provider | Допоміжні засоби визначення API-ключа під час runtime | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключа provider | Допоміжні засоби onboarding/запису профілю для API-ключа | + | `plugin-sdk/provider-auth-result` | Допоміжні засоби результатів auth provider | Стандартний білдер результату auth OAuth | + | `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу provider | Спільні допоміжні засоби інтерактивного входу | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби env var provider | Допоміжні засоби пошуку env var auth provider | + | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделей/replay provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні білдери політик replay, допоміжні засоби endpoint provider та допоміжні засоби нормалізації model-id | + | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Patch onboarding provider | Допоміжні засоби config onboarding | + | `plugin-sdk/provider-http` | Допоміжні засоби HTTP provider | Загальні допоміжні засоби можливостей HTTP/endpoint provider | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch provider | Допоміжні засоби реєстрації/cache provider web-fetch | + | `plugin-sdk/provider-web-search` | Допоміжні засоби web-search provider | Допоміжні засоби реєстрації/cache/config provider web-search | + | `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`, типи обгорток потоків і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/keyed-async-queue` | Впорядкована асинхронна черга | `KeyedAsyncQueue` | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби media | Допоміжні засоби отримання/перетворення/зберігання media та білдери media payload | + | `plugin-sdk/media-understanding` | Допоміжні засоби media-understanding | Типи provider media understanding та експорти допоміжних засобів зображень/аудіо для provider | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення видимого для assistant тексту, допоміжні засоби render/chunking/table для markdown, редагування, допоміжні засоби тегів директив, утиліти безпечного тексту та пов’язані допоміжні засоби text/logging | + | `plugin-sdk/text-chunking` | Допоміжні засоби chunking тексту | Допоміжний засіб chunking вихідного тексту | + | `plugin-sdk/speech` | Допоміжні засоби speech | Типи provider speech та експорти допоміжних засобів директив, реєстру й валідації для provider | + | `plugin-sdk/speech-core` | Спільне ядро speech | Типи provider speech, реєстр, директиви, нормалізація | + | `plugin-sdk/realtime-transcription` | Допоміжні засоби realtime transcription | Типи provider та допоміжні засоби реєстру | + | `plugin-sdk/realtime-voice` | Допоміжні засоби realtime voice | Типи provider та допоміжні засоби реєстру | + | `plugin-sdk/image-generation-core` | Спільне ядро image-generation | Типи image-generation, failover, auth та допоміжні засоби реєстру | + | `plugin-sdk/video-generation` | Допоміжні засоби video-generation | Типи provider/request/result для video-generation | + | `plugin-sdk/video-generation-core` | Спільне ядро video-generation | Типи video-generation, допоміжні засоби failover, пошук provider і аналіз model-ref | + | `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивних відповідей | Нормалізація/скорочення payload інтерактивних відповідей | + | `plugin-sdk/channel-config-primitives` | Примітиви config каналу | Вузькі примітиви schema config каналу | + | `plugin-sdk/channel-config-writes` | Допоміжні засоби запису config каналу | Допоміжні засоби авторизації запису config каналу | + | `plugin-sdk/channel-plugin-common` | Спільна преамбула каналу | Експорти спільної преамбули plugin каналу | + | `plugin-sdk/channel-status` | Допоміжні засоби стану каналу | Спільні допоміжні засоби snapshot/summary стану каналу | + | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби config allowlist | Допоміжні засоби редагування/читання config allowlist | + | `plugin-sdk/group-access` | Допоміжні засоби доступу груп | Спільні допоміжні засоби рішень щодо доступу груп | + | `plugin-sdk/direct-dm` | Допоміжні засоби direct-DM | Спільні допоміжні засоби auth/guard для direct-DM | + | `plugin-sdk/extension-shared` | Спільні допоміжні засоби extension | Примітиви допоміжних засобів passive-channel/status | | `plugin-sdk/webhook-targets` | Допоміжні засоби цілей webhook | Реєстр цілей webhook і допоміжні засоби встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні засоби шляху webhook | Допоміжні засоби нормалізації шляху webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби web media | Допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для споживачів SDK плагінів | - | `plugin-sdk/memory-core` | Вбудовані допоміжні засоби memory-core | Поверхня допоміжних засобів memory manager/config/file/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime рушія memory | Фасад runtime індексування/пошуку memory | - | `plugin-sdk/memory-core-host-engine-foundation` | Базовий рушій memory для хоста | Експорти базового рушія memory для хоста | - | `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embeddings memory для хоста | Експорти рушія embeddings memory для хоста | - | `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD memory для хоста | Експорти рушія QMD memory для хоста | - | `plugin-sdk/memory-core-host-engine-storage` | Рушій зберігання memory для хоста | Експорти рушія зберігання memory для хоста | - | `plugin-sdk/memory-core-host-multimodal` | Багатомодальні допоміжні засоби memory для хоста | Багатомодальні допоміжні засоби memory для хоста | - | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів memory для хоста | Допоміжні засоби запитів memory для хоста | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів memory для хоста | Допоміжні засоби секретів memory для хоста | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби стану memory для хоста | Допоміжні засоби стану memory для хоста | - | `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime memory для хоста | Допоміжні засоби CLI runtime memory для хоста | - | `plugin-sdk/memory-core-host-runtime-core` | Базовий runtime memory для хоста | Допоміжні засоби базового runtime memory для хоста | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime memory для хоста | Допоміжні засоби файлів/runtime memory для хоста | - | `plugin-sdk/memory-lancedb` | Вбудовані допоміжні засоби memory-lancedb | Поверхня допоміжних засобів memory-lancedb | - | `plugin-sdk/testing` | Утиліти тестування | Допоміжні засоби тестування та mock-об’єкти | + | `plugin-sdk/webhook-path` | Допоміжні засоби шляхів webhook | Допоміжні засоби нормалізації шляхів webhook | + | `plugin-sdk/web-media` | Спільні допоміжні засоби web media | Допоміжні засоби завантаження віддаленого/локального 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 рушія пам’яті | Фасад runtime індексації/пошуку пам’яті | + | `plugin-sdk/memory-core-host-engine-foundation` | Базовий рушій host пам’яті | Експорти базового рушія host пам’яті | + | `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embedding host пам’яті | Експорти рушія embedding host пам’яті | + | `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD host пам’яті | Експорти рушія QMD host пам’яті | + | `plugin-sdk/memory-core-host-engine-storage` | Рушій сховища host пам’яті | Експорти рушія сховища host пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби host пам’яті | Мультимодальні допоміжні засоби host пам’яті | + | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів host пам’яті | Допоміжні засоби запитів host пам’яті | + | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret host пам’яті | Допоміжні засоби secret host пам’яті | + | `plugin-sdk/memory-core-host-status` | Допоміжні засоби стану host пам’яті | Допоміжні засоби стану host пам’яті | + | `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime host пам’яті | Допоміжні засоби CLI runtime host пам’яті | + | `plugin-sdk/memory-core-host-runtime-core` | Основний runtime host пам’яті | Основні допоміжні засоби runtime host пам’яті | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime host пам’яті | Допоміжні засоби файлів/runtime host пам’яті | + | `plugin-sdk/memory-lancedb` | Допоміжні засоби вбудованого memory-lancedb | Поверхня допоміжних засобів memory-lancedb | + | `plugin-sdk/testing` | Утиліти тестування | Допоміжні засоби тестування та mocks | -Ця таблиця навмисно містить поширену підмножину для міграції, а не повну +Ця таблиця навмисно охоплює поширену підмножину для міграції, а не всю поверхню SDK. Повний список із понад 200 точок входу міститься у `scripts/lib/plugin-sdk-entrypoints.json`. -Цей список усе ще містить деякі допоміжні шви вбудованих плагінів, як-от +Цей список усе ще містить деякі допоміжні шви вбудованих 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-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-profiles`, `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-sdk/googlechat`, +- поверхні вбудованих 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`, @@ -340,22 +329,22 @@ OpenClaw перейшов від широкого шару зворотної с `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`, +`plugin-sdk/github-copilot-token` наразі надає вузьку +поверхню допоміжних засобів token: `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken`. -Використовуйте найвужчий імпорт, який відповідає задачі. Якщо ви не можете -знайти експорт, перегляньте джерело в `src/plugin-sdk/` або запитайте в Discord. +Використовуйте найвужчий імпорт, який відповідає вашому завданню. Якщо ви не можете знайти експорт, +перевірте вихідний код у `src/plugin-sdk/` або запитайте в Discord. ## Хронологія видалення -| Коли | Що відбувається | +| Коли | Що відбувається | | ---------------------- | ----------------------------------------------------------------------- | -| **Зараз** | Застарілі поверхні видають попередження під час виконання | -| **Наступний великий випуск** | Застарілі поверхні буде видалено; плагіни, які все ще їх використовують, перестануть працювати | +| **Зараз** | Застарілі поверхні виводять попередження під час runtime | +| **Наступний мажорний реліз** | Застарілі поверхні буде видалено; plugin, які все ще їх використовують, перестануть працювати | -Усі основні плагіни вже мігрували. Зовнішнім плагінам слід виконати міграцію -до наступного великого випуску. +Усі core plugin уже мігровано. Зовнішнім plugin слід перейти на нові механізми +до наступного мажорного релізу. ## Тимчасове приглушення попереджень @@ -370,9 +359,9 @@ OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ## Пов’язане -- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший плагін +- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший plugin - [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів за підшляхами -- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення плагінів каналів -- [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення плагінів провайдерів -- [Внутрішня будова плагінів](/uk/plugins/architecture) — детальний розбір архітектури -- [Маніфест плагіна](/uk/plugins/manifest) — довідник схеми маніфесту +- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення plugin каналів +- [Плагіни provider](/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 a08483a02..c6b1b6bc3 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,16 +1,16 @@ --- read_when: - - Потрібно знати, з якого підшляху SDK імпортувати - - Потрібен довідник для всіх методів реєстрації в OpenClawPluginApi + - Вам потрібно знати, з якого підшляху SDK імпортувати + - Ви хочете отримати довідник для всіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK Overview summary: Карта імпортів, довідник API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-05T21:47:19Z" + generated_at: "2026-04-05T22:38:04Z" model: gpt-5.4 provider: openai - source_hash: d70ea8cc1343b2dc1b4243b0562d19bebb1fdf7eb5065220b17e87cfd8aecc3e + source_hash: 0e023cf1ca8a35a437e27fdebde66d955771d50a3db5ffeef335c174873b1867 source_path: plugins/sdk-overview.md workflow: 15 --- @@ -18,16 +18,16 @@ x-i18n: # Огляд Plugin SDK Plugin SDK — це типізований контракт між плагінами та ядром. Ця сторінка є -довідником для **що імпортувати** і **що можна реєструвати**. +довідником щодо **що імпортувати** і **що можна реєструвати**. **Шукаєте покроковий посібник?** - - Перший плагін? Почніть із [Getting Started](/uk/plugins/building-plugins) - - Плагін каналу? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins) - - Плагін провайдера? Див. [Provider Plugins](/uk/plugins/sdk-provider-plugins) + - Перший плагін? Почніть із [Початок роботи](/uk/plugins/building-plugins) + - Плагін каналу? Див. [Плагіни каналів](/uk/plugins/sdk-channel-plugins) + - Плагін провайдера? Див. [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) -## Правило імпорту +## Угода щодо імпорту Завжди імпортуйте з конкретного підшляху: @@ -36,25 +36,24 @@ 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` залишайте для -ширшої парасолькової поверхні та спільних допоміжних засобів, таких як +Кожен підшлях — це невеликий самодостатній модуль. Це зберігає швидкий запуск і +запобігає проблемам із циклічними залежностями. Для допоміжних засобів +входу/збирання, специфічних для каналу, надавайте перевагу `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, якщо потреба справді є міжканальною. +допоміжні шари з брендингом каналів. Вбудовані плагіни мають компонувати узагальнені +підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а ядро +має або використовувати ці локальні barrel-файли плагінів, або додавати вузький узагальнений контракт SDK, коли потреба справді є міжканальною. -Згенерована карта експортів усе ще містить невеликий набір допоміжних -шарів для вбудованих плагінів, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, +Згенерована карта експортів усе ще містить невеликий набір +допоміжних шарів для вбудованих плагінів, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці -підшляхи існують лише для підтримки вбудованих плагінів і сумісності; їх -навмисно пропущено в основній таблиці нижче, і вони не є рекомендованим +підшляхи існують лише для супроводу та сумісності вбудованих плагінів; вони +навмисно не включені до основної таблиці нижче і не є рекомендованим шляхом імпорту для нових сторонніх плагінів. ## Довідник підшляхів @@ -62,11 +61,11 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. -Зарезервовані допоміжні підшляхи вбудованих плагінів усе ще з’являються в цьому -згенерованому списку. Розглядайте їх як поверхні деталей реалізації/сумісності, якщо сторінка документації -явно не просуває якийсь із них як публічний. +Зарезервовані підшляхи допоміжних засобів для вбудованих плагінів усе ще з’являються в цьому згенерованому списку. +Розглядайте їх як поверхні деталей реалізації/сумісності, якщо лише якась сторінка документації +явно не позначає одну з них як публічну. -### Вхідна точка плагіна +### Точка входу плагіна | Підшлях | Ключові експорти | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | @@ -76,74 +75,74 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - + | Підшлях | Ключові експорти | | --- | --- | | `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` | Спільні допоміжні засоби майстра налаштування, запити allowlist, конструктори стану налаштування | | `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` | Допоміжні засоби багатооблікової конфігурації/action-gate, допоміжні засоби fallback для облікового запису за замовчуванням | + | `plugin-sdk/account-core` | Допоміжні засоби конфігурації/контролю дій для кількох облікових записів, допоміжні засоби резервного облікового запису за замовчуванням | | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації ID облікового запису | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису + fallback за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку облікових записів/дій облікового запису | + | `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 із fallback на вбудований контракт | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервним варіантом вбудованого контракту | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби для route вхідних повідомлень + побудови 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` | Допоміжні засоби для вихідної ідентичності/send delegate | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідної ідентичності/делегування надсилання | | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптерів | - | `plugin-sdk/agent-media-payload` | Застарілий конструктор медіапейлоаду агента | - | `plugin-sdk/conversation-runtime` | Допоміжні засоби для прив’язки розмови/потоку, pairing і configured-binding | + | `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` | Вузькі примітиви схеми конфігурації каналу | | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільні прелюд-експорти плагіна каналу | + | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти плагінів каналів | | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Спільні допоміжні засоби прийняття рішень щодо групового доступу | - | `plugin-sdk/direct-dm` | Спільні допоміжні засоби автентифікації/захисту direct-DM | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби нормалізації/скорочення пейлоадів інтерактивних відповідей | + | `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` | Підключення feedback/reaction | + | `plugin-sdk/channel-feedback` | Логіка зворотного зв’язку/реакцій | - + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Добірні допоміжні засоби налаштування локального/self-hosted провайдера | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдера, сумісного з OpenAI | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключа в runtime для плагінів провайдерів | + | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення runtime API-ключів для плагінів провайдерів | | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-ключа | | `plugin-sdk/provider-auth-result` | Стандартний конструктор результату OAuth-автентифікації | | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для плагінів провайдерів | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env vars для автентифікації провайдера | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env vars автентифікації провайдера | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори replay-policy, допоміжні засоби endpoint провайдера та нормалізації ID моделей, як-от `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політики replay, допоміжні засоби endpoint провайдера та допоміжні засоби нормалізації ID моделей, такі як `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint провайдера | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешу провайдера web-fetch | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешу/конфігурації провайдера web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Узагальнені допоміжні засоби HTTP/можливостей endpoint провайдера | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешу провайдерів web-fetch | + | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешу/конфігурації провайдерів 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-onboard` | Допоміжні засоби латання конфігурації онбордингу | | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | @@ -152,96 +151,96 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | --- | --- | | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, допоміжні засоби авторизації відправника | | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення approver і action-auth у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтрів native exec approval | - | `plugin-sdk/approval-delivery-runtime` | Адаптери native approval capability/delivery | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби target і прив’язки облікового запису для native approval | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби пейлоаду відповіді exec/plugin approval | + | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval | + | `plugin-sdk/approval-delivery-runtime` | Адаптери можливостей/доставки native approval | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілі native approval + прив’язки облікового запису | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби пейлоада відповіді для approval exec/плагіна | | `plugin-sdk/command-auth-native` | Допоміжні засоби native command auth + native session-target | | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команди та command-surface | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/security-runtime` | Спільні допоміжні засоби для довіри, DM gating, external-content і збору секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики host allowlist і SSRF для приватних мереж | + | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, обмеження DM, зовнішнього контенту та збирання секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж | | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF і політики SSRF | | `plugin-sdk/secret-input` | Допоміжні засоби розбору секретного вводу | | `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілі webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби для розміру body/timeout запиту | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту/таймауту | - + | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/logging/backup/plugin-install | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env runtime, logger, timeout, retry і backoff | + | `plugin-sdk/runtime` | Широка поверхня допоміжних засобів runtime/логування/резервного копіювання/встановлення плагінів | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби runtime env, logger, timeout, retry і backoff | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби для команд/hook/http/interactive плагіна | - | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби для конвеєра webhook/internal hook | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy import/binding у runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/хуків/http/інтерактивності плагінів | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби конвеєра webhook/внутрішніх хуків | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби ледачого імпорту/прив’язки runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів | | `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` | Допоміжні засоби exec/plugin approval, конструктори approval-capability, допоміжні засоби auth/profile, native routing/runtime | - | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime для вхідних повідомлень/відповідей, chunking, dispatch, heartbeat, planner відповіді | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповіді | - | `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window reply-history, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/telegram-command-config` | Нормалізація назви/опису команди Telegram і перевірки дублювання/конфліктів, навіть коли поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/approval-runtime` | Допоміжні засоби approval exec/плагіна, конструктори можливостей approval, допоміжні засоби auth/profile, native routing/runtime helpers | + | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби inbound/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 для text/markdown | + | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown | | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій + 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/state-paths` | Допоміжні засоби шляхів каталогів state/OAuth | + | `plugin-sdk/routing` | Допоміжні засоби прив’язки маршруту/ключа сесії/облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку стану каналу/облікового запису, типові значення стану runtime та допоміжні засоби метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілей | | `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` | Витягування канонічних полів цілі send з аргументів інструмента | - | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляху тимчасового завантаження | - | `plugin-sdk/logging-core` | Допоміжні засоби журналювання підсистеми та редагування конфіденційних даних | + | `plugin-sdk/param-readers` | Поширені зчитувачі параметрів tool/CLI | + | `plugin-sdk/tool-send` | Видобування канонічних полів цілі надсилання з аргументів tool | + | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляху тимчасових завантажень | + | `plugin-sdk/logging-core` | Допоміжні засоби subsystem logger і redaction | | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму таблиць Markdown | | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON | - | `plugin-sdk/file-lock` | Допоміжні засоби re-entrant file-lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні засоби дискового dedupe-кешу | - | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/session ACP і dispatch відповіді | + | `plugin-sdk/file-lock` | Повторно вхідні допоміжні засоби file-lock | + | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу дедуплікації з дисковою підтримкою | + | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/сесій ACP і dispatch відповідей | | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента | - | `plugin-sdk/boolean-param` | Гнучкий засіб читання булевих параметрів | - | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення небезпечних назв | - | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів pairing | - | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel і status | - | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді команди `/models`/провайдера | + | `plugin-sdk/boolean-param` | Нестрогий зчитувач булевих параметрів | + | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення зіставлення небезпечних імен | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби початкового налаштування пристрою та токенів pairing | + | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів пасивних каналів і стану | + | `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/infra-runtime` | Допоміжні засоби системних подій/heartbeat | - | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби bounded cache | + | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців і подій | | `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби wrapped fetch, proxy і pinned lookup | - | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і хостів SCP | - | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry та запуску retry | + | `plugin-sdk/fetch-runtime` | Обгорнутий fetch, proxy і pinned lookup helpers | + | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host | + | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і запуску retry | | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/workspace агента | - | `plugin-sdk/directory-runtime` | Query/dedup каталогів на основі конфігурації | + | `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також конструктори медіапейлоадів | - | `plugin-sdk/media-understanding` | Типи провайдера media understanding і орієнтовані на провайдера експорти допоміжних засобів для зображень/аудіо | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби для text/markdown/logging, такі як видалення тексту, видимого асистенту, допоміжні засоби render/chunking/table для markdown, редагування конфіденційних даних, допоміжні засоби directive-tag і безпечного тексту | - | `plugin-sdk/text-chunking` | Допоміжний засіб chunking для вихідного тексту | - | `plugin-sdk/speech` | Типи провайдера мовлення, а також орієнтовані на провайдера допоміжні засоби directive, registry і validation | - | `plugin-sdk/speech-core` | Спільні типи провайдера мовлення, допоміжні засоби registry, directive і normalizaton | - | `plugin-sdk/realtime-transcription` | Типи провайдера транскрипції в реальному часі та допоміжні засоби реєстру | - | `plugin-sdk/realtime-voice` | Типи провайдера голосу в реальному часі та допоміжні засоби реєстру | - | `plugin-sdk/image-generation` | Типи провайдера генерації зображень | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store медіа, а також конструктори медіапейлоадів | + | `plugin-sdk/media-understanding` | Типи провайдерів media understanding, а також provider-facing експорти допоміжних засобів для зображень/аудіо | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту/markdown/логування, такі як видалення видимого для асистента тексту, допоміжні засоби render/chunking/table для markdown, допоміжні засоби redaction, directive-tag та safe-text utilities | + | `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту | + | `plugin-sdk/speech` | Типи провайдерів мовлення, а також provider-facing допоміжні засоби directive, registry і validation | + | `plugin-sdk/speech-core` | Спільні типи провайдерів мовлення, допоміжні засоби registry, directive і normalization | + | `plugin-sdk/realtime-transcription` | Типи провайдерів транскрибування в реальному часі та допоміжні засоби registry | + | `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та допоміжні засоби registry | + | `plugin-sdk/image-generation` | Типи провайдерів генерації зображень | | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і registry | - | `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео | + | `plugin-sdk/video-generation` | Типи провайдерів/запитів/результатів генерації відео | | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошуку провайдера та розбору model-ref | - | `plugin-sdk/webhook-targets` | Реєстр цілей webhook і допоміжні засоби встановлення route | + | `plugin-sdk/webhook-targets` | Реєстр цілей webhook і допоміжні засоби встановлення маршрутів | | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху webhook | | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | @@ -251,7 +250,7 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для manager/config/file/CLI | + | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для менеджера/конфігурації/файлів/CLI | | `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 хоста пам’яті | @@ -261,78 +260,78 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; | `plugin-sdk/memory-core-host-query` | Допоміжні засоби query хоста пам’яті | | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста пам’яті | | `plugin-sdk/memory-core-host-status` | Допоміжні засоби 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-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb | - - | Сімейство | Поточні підшляхи | Призначення | + + | Сімейство | Поточні підшляхи | Призначене використання | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки вбудованого плагіна браузера | - | 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` | Поверхня допоміжних засобів/runtime для вбудованого Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime для вбудованого LINE | + | 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` | Поверхня допоміжних засобів/runtime вбудованого Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/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-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` | + | Допоміжні засоби, специфічні для каналів | `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-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` | ## API реєстрації -Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` із такими +Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` із такими методами: ### Реєстрація можливостей -| Метод | Що реєструє | +| Метод | Що він реєструє | | ------------------------------------------------ | ------------------------------ | -| `api.registerProvider(...)` | Текстову інференцію (LLM) | -| `api.registerChannel(...)` | Канал повідомлень | -| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | -| `api.registerRealtimeTranscriptionProvider(...)` | Потокову транскрипцію в реальному часі | -| `api.registerRealtimeVoiceProvider(...)` | Двобічні голосові сесії в реальному часі | +| `api.registerProvider(...)` | Текстовий inference (LLM) | +| `api.registerChannel(...)` | Канал обміну повідомленнями | +| `api.registerSpeechProvider(...)` | Text-to-speech / STT synthesis | +| `api.registerRealtimeTranscriptionProvider(...)` | Потокове транскрибування в реальному часі | +| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі | | `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерацію зображень | -| `api.registerVideoGenerationProvider(...)` | Генерацію відео | -| `api.registerWebFetchProvider(...)` | Провайдера web fetch / scrape | +| `api.registerImageGenerationProvider(...)` | Генерація зображень | +| `api.registerVideoGenerationProvider(...)` | Генерація відео | +| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | | `api.registerWebSearchProvider(...)` | Вебпошук | -### Інструменти та команди +### Інструменти і команди -| Метод | Що реєструє | -| ------------------------------- | ------------------------------------------- | +| Метод | Що він реєструє | +| ------------------------------ | -------------------------------------------- | | `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацьку команду (оминає LLM) | +| `api.registerCommand(def)` | Користувацька команда (оминає LLM) | ### Інфраструктура -| Метод | Що реєструє | -| ---------------------------------------------- | -------------------- | -| `api.registerHook(events, handler, opts?)` | Хук події | -| `api.registerHttpRoute(params)` | HTTP-ендпоінт Gateway | -| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | -| `api.registerCli(registrar, opts?)` | Підкоманду CLI | -| `api.registerService(service)` | Фоновий сервіс | +| Метод | Що він реєструє | +| --------------------------------------------- | --------------------- | +| `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)` | Інтерактивний обробник | -Зарезервовані простори імен core admin (`config.*`, `exec.approvals.*`, `wizard.*`, +Зарезервовані простори імен адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити -вужчу область дії методу gateway. Для методів, що належать -плагіну, віддавайте перевагу специфічним для плагіна префіксам. +вужчу область gateway method. Для методів, що належать плагіну, надавайте перевагу +префіксам, специфічним для плагіна. ### Метадані реєстрації CLI -`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: +`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня: -- `commands`: явні корені команд, якими володіє registrar -- `descriptors`: дескриптори команд на етапі парсингу, які використовуються для кореневої довідки CLI, - маршрутизації та лінивої реєстрації CLI плагіна +- `commands`: явні корені команд, якими володіє реєстратор +- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для кореневої довідки CLI, + маршрутизації та ледачої реєстрації CLI плагіна -Якщо ви хочете, щоб команда плагіна залишалася ліниво завантажуваною у -звичайному кореневому шляху CLI, надайте `descriptors`, які охоплюють кожен -корінь команди верхнього рівня, що експонує цей registrar. +Якщо ви хочете, щоб команда плагіна залишалася ледачо завантажуваною у звичайному кореневому шляху CLI, +надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що надається +цим реєстратором. ```typescript api.registerCli( @@ -352,117 +351,117 @@ api.registerCli( ); ``` -Використовуйте лише `commands`, коли вам не потрібна лінива реєстрація кореневого CLI. -Цей сумісний eager-шлях і далі підтримується, але він не встановлює -placeholders із підтримкою descriptors для лінивого завантаження на етапі парсингу. +Використовуйте лише `commands`, якщо вам не потрібна ледача реєстрація кореневого CLI. +Цей eager-шлях сумісності й надалі підтримується, але він не встановлює +заповнювачі на основі descriptor для ледачого завантаження на етапі парсингу. ### Ексклюзивні слоти -| Метод | Що реєструє | -| ------------------------------------------ | ------------------------------------- | +| Метод | Що він реєструє | +| ----------------------------------------- | -------------------------------------- | | `api.registerContextEngine(id, factory)` | Контекстний рушій (одночасно активний лише один) | -| `api.registerMemoryPromptSection(builder)` | Конструктор секції prompt для пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану flush для пам’яті | -| `api.registerMemoryRuntime(runtime)` | Адаптер runtime для пам’яті | +| `api.registerMemoryPromptSection(builder)` | Конструктор секції prompt пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану flush пам’яті | +| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | -### Адаптери embedding для пам’яті +### Адаптери embedding пам’яті -| Метод | Що реєструє | -| ---------------------------------------------- | --------------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для пам’яті для активного плагіна | +| Метод | Що він реєструє | +| --------------------------------------------- | ------------------------------------------------ | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding пам’яті для активного плагіна | - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і `registerMemoryRuntime` є ексклюзивними для плагінів пам’яті. -- `registerMemoryEmbeddingProvider` дозволяє активному плагіну пам’яті реєструвати один - або кілька ID адаптерів embedding (наприклад `openai`, `gemini` або - спеціальний ID, визначений плагіном). +- `registerMemoryEmbeddingProvider` дозволяє активному плагіну пам’яті зареєструвати один + або кілька ID адаптерів embedding (наприклад, `openai`, `gemini` або + власний ID, визначений плагіном). - Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і `agents.defaults.memorySearch.fallback`, визначається відносно цих зареєстрованих ID адаптерів. ### Події та життєвий цикл -| Метод | Що робить | -| -------------------------------------------- | ------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | -| `api.onConversationBindingResolved(handler)` | Колбек визначення прив’язки розмови | +| Метод | Що він робить | +| ------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | +| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови | ### Семантика рішень хуків -- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник задає це значення, обробники з нижчим пріоритетом пропускаються. -- `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. -- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник задає це значення, обробники з нижчим пріоритетом пропускаються. -- `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як пропуск `block`), а не перевизначенням. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере dispatch на себе, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються. -- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник задає це значення, обробники з нижчим пріоритетом пропускаються. -- `message_sending`: повернення `{ cancel: false }` вважається відсутністю рішення (так само, як пропуск `cancel`), а не перевизначенням. +- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_tool_call`: повернення `{ block: false }` вважається відсутністю рішення (так само, як і пропуск `block`), а не перевизначенням. +- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_install`: повернення `{ block: false }` вважається відсутністю рішення (так само, як і пропуск `block`), а не перевизначенням. +- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник перехоплює диспетчеризацію, обробники з нижчим пріоритетом і типовий шлях диспетчеризації моделі пропускаються. +- `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` | Поточний знімок конфігурації (активний знімок in-memory 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` | Визначення шляху відносно кореня плагіна | +| Поле | Тип | Опис | +| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- | +| `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"` — це легковагоме вікно запуску/налаштування до повного входу | +| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня плагіна | -## Внутрішня домовленість про модулі +## Угода щодо внутрішніх модулів Усередині вашого плагіна використовуйте локальні barrel-файли для внутрішніх імпортів: ``` my-plugin/ api.ts # Публічні експорти для зовнішніх споживачів - runtime-api.ts # Лише внутрішні експорти runtime + runtime-api.ts # Лише внутрішні runtime-експорти index.ts # Точка входу плагіна - setup-entry.ts # Полегшений entry лише для налаштування (необов’язково) + setup-entry.ts # Легка точка входу лише для налаштування (необов’язково) ``` Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/` - у production-коді. Для внутрішніх імпортів використовуйте `./api.ts` або - `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. + у production-коді. Для внутрішніх імпортів використовуйте + `./api.ts` або `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. -Публічні поверхні вбудованих плагінів, завантажувані через facade (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), тепер віддають перевагу -активному знімку конфігурації runtime, коли OpenClaw уже запущено. Якщо знімка runtime -ще не існує, вони використовують fallback до визначеного файла конфігурації на диску. +Фасадно завантажувані публічні поверхні вбудованих плагінів (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` та подібні публічні файли входу) тепер надають перевагу +активному знімку конфігурації runtime, коли OpenClaw уже запущено. Якщо знімок runtime +ще не існує, вони повертаються до визначеного конфігураційного файла на диску. -Плагіни провайдерів також можуть експортувати вузький локальний контрактний barrel плагіна, коли -певний допоміжний засіб навмисно є специфічним для провайдера й поки що не належить до -загального підшляху SDK. Поточний вбудований приклад: провайдер Anthropic тримає свої -допоміжні засоби потоків Claude у власному публічному шарі `api.ts` / `contract-api.ts`, замість -того щоб просувати логіку бета-заголовків Anthropic і `service_tier` до загального +Плагіни провайдерів також можуть надавати вузький локальний barrel-файл контракту плагіна, коли +певний допоміжний засіб навмисно є специфічним для провайдера і ще не належить до узагальненого +підшляху SDK. Поточний вбудований приклад: провайдер Anthropic зберігає свої допоміжні засоби +потоків Claude у власному публічному шарі `api.ts` / `contract-api.ts` замість того, щоб +просувати логіку beta-header і `service_tier` Anthropic до узагальненого контракту `plugin-sdk/*`. Інші поточні вбудовані приклади: - `@openclaw/openai-provider`: `api.ts` експортує конструктори провайдерів, допоміжні засоби моделей за замовчуванням і конструктори realtime-провайдерів -- `@openclaw/openrouter-provider`: `api.ts` експортує конструктор провайдера, а також +- `@openclaw/openrouter-provider`: `api.ts` експортує конструктор провайдера та допоміжні засоби онбордингу/конфігурації Production-код розширень також має уникати імпортів `openclaw/plugin-sdk/`. - Якщо допоміжний засіб справді спільний, перемістіть його до нейтрального підшляху SDK, + Якщо допоміжний засіб справді спільний, винесіть його до нейтрального підшляху SDK, такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - поверхні, орієнтованої на можливості, замість жорсткого зв’язування двох плагінів. + поверхні, орієнтованої на можливість, замість того щоб зчіплювати два плагіни між собою. ## Пов’язане -- [Entry Points](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` і `defineChannelPluginEntry` -- [Runtime Helpers](/uk/plugins/sdk-runtime) — повний довідник простору імен `api.runtime` -- [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації -- [Testing](/uk/plugins/sdk-testing) — утиліти тестування та правила lint -- [SDK Migration](/uk/plugins/sdk-migration) — міграція із застарілих поверхонь -- [Plugin Internals](/uk/plugins/architecture) — детальна архітектура та модель можливостей +- [Точки входу](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` і `defineChannelPluginEntry` +- [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) — повний довідник простору імен `api.runtime` +- [Налаштування і конфігурація](/uk/plugins/sdk-setup) — пакування, маніфести, схеми конфігурації +- [Тестування](/uk/plugins/sdk-testing) — утиліти тестування і правила lint +- [Міграція SDK](/uk/plugins/sdk-migration) — міграція із застарілих поверхонь +- [Внутрішня будова плагінів](/uk/plugins/architecture) — глибока архітектура та модель можливостей diff --git a/docs/uk/plugins/sdk-setup.md b/docs/uk/plugins/sdk-setup.md index d633e5773..4df26a331 100644 --- a/docs/uk/plugins/sdk-setup.md +++ b/docs/uk/plugins/sdk-setup.md @@ -2,33 +2,33 @@ read_when: - Ви додаєте майстер налаштування до плагіна - Вам потрібно зрозуміти різницю між setup-entry.ts і index.ts - - Ви визначаєте schema конфігурації плагіна або метадані openclaw у package.json + - Ви визначаєте схеми конфігурації плагіна або метадані openclaw у package.json sidebarTitle: Setup and Config -summary: Майстри налаштування, setup-entry.ts, schema конфігурації та метадані package.json -title: Налаштування та конфігурація плагіна +summary: Майстри налаштування, setup-entry.ts, схеми конфігурації та метадані package.json +title: Налаштування плагінів і конфігурація x-i18n: - generated_at: "2026-04-05T18:13:31Z" + generated_at: "2026-04-05T22:37:37Z" model: gpt-5.4 provider: openai - source_hash: 68fda27be1c89ea6ba906833113e9190ddd0ab358eb024262fb806746d54f7bf + source_hash: eac2586516d27bcd94cc4c259fe6274c792b3f9938c7ddd6dbf04a6dbb988dc9 source_path: plugins/sdk-setup.md workflow: 15 --- -# Налаштування та конфігурація плагіна +# Налаштування плагінів і конфігурація -Довідник із пакування плагінів (метадані `package.json`), маніфестів -(`openclaw.plugin.json`), setup entries і schema конфігурації. +Довідник щодо пакування плагінів (метадані `package.json`), маніфестів +(`openclaw.plugin.json`), точок входу налаштування та схем конфігурації. - **Шукаєте покрокове пояснення?** У посібниках how-to розглядається пакування в контексті: - [Плагіни каналів](/plugins/sdk-channel-plugins#step-1-package-and-manifest) і - [Плагіни провайдерів](/plugins/sdk-provider-plugins#step-1-package-and-manifest). + **Шукаєте покроковий посібник?** Практичні інструкції розглядають пакування в контексті: + [Channel Plugins](/uk/plugins/sdk-channel-plugins#step-1-package-and-manifest) і + [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-1-package-and-manifest). ## Метадані пакета -Ваш `package.json` має містити поле `openclaw`, яке повідомляє системі плагінів, що +Вашому `package.json` потрібне поле `openclaw`, яке повідомляє системі плагінів, що саме надає ваш плагін: **Плагін каналу:** @@ -50,7 +50,7 @@ x-i18n: } ``` -**Плагін провайдера / базовий варіант для публікації в ClawHub:** +**Плагін провайдера / базовий варіант для публікації ClawHub:** ```json openclaw-clawhub-package.json { @@ -71,47 +71,47 @@ x-i18n: } ``` -Якщо ви публікуєте плагін зовні в ClawHub, ці поля `compat` і `build` -є обов’язковими. Канонічні фрагменти для публікації розміщено в +Якщо ви публікуєте плагін зовнішньо в ClawHub, поля `compat` і `build` +є обов’язковими. Канонічні фрагменти для публікації знаходяться в `docs/snippets/plugin-publish/`. ### Поля `openclaw` -| Поле | Тип | Опис | -| ----------- | ---------- | ------------------------------------------------------------------------------------------------------ | -| `extensions` | `string[]` | Файли entry point'ів (відносно кореня пакета) | -| `setupEntry` | `string` | Полегшений запис лише для налаштування (необов’язково) | -| `channel` | `object` | Метадані каталогу каналів для налаштування, пікера, quickstart і поверхонь статусу | -| `providers` | `string[]` | Id провайдерів, які реєструє цей плагін | +| Поле | Тип | Опис | +| ------------ | ---------- | -------------------------------------------------------------------------------------------------------------- | +| `extensions` | `string[]` | Файли точок входу (відносно кореня пакета) | +| `setupEntry` | `string` | Легка точка входу лише для налаштування (необов’язково) | +| `channel` | `object` | Метадані каталогу каналів для налаштування, вибору, швидкого старту та поверхонь стану | +| `providers` | `string[]` | Ідентифікатори провайдерів, зареєстрованих цим плагіном | | `install` | `object` | Підказки для встановлення: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `allowInvalidConfigRecovery` | -| `startup` | `object` | Прапорці поведінки під час запуску | +| `startup` | `object` | Прапорці поведінки під час запуску | ### `openclaw.channel` -`openclaw.channel` — це недорогі метадані пакета для виявлення каналу і поверхонь -налаштування до завантаження середовища виконання. +`openclaw.channel` — це недорогі метадані пакета для виявлення каналів і +поверхонь налаштування до завантаження середовища виконання. -| Поле | Тип | Що це означає | -| -------------------------------------- | ---------- | --------------------------------------------------------------------------- | -| `id` | `string` | Канонічний id каналу. | -| `label` | `string` | Основна мітка каналу. | -| `selectionLabel` | `string` | Мітка для пікера/налаштування, якщо вона має відрізнятися від `label`. | -| `detailLabel` | `string` | Додаткова мітка для докладніших каталогів каналів і поверхонь статусу. | -| `docsPath` | `string` | Шлях до документації для посилань у налаштуванні та виборі. | -| `docsLabel` | `string` | Заміна мітки для посилань на документацію, якщо вона має відрізнятися від id каналу. | -| `blurb` | `string` | Короткий опис для онбордингу/каталогу. | -| `order` | `number` | Порядок сортування в каталогах каналів. | -| `aliases` | `string[]` | Додаткові псевдоніми для пошуку каналу. | -| `preferOver` | `string[]` | Менш пріоритетні id плагінів/каналів, які цей канал має перевершувати. | -| `systemImage` | `string` | Необов’язкова назва icon/system-image для каталогів UI каналів. | -| `selectionDocsPrefix` | `string` | Префіксний текст перед посиланнями на документацію на поверхнях вибору. | -| `selectionDocsOmitLabel` | `boolean` | Показує шлях до документації напряму замість підписаного посилання в тексті вибору. | -| `selectionExtras` | `string[]` | Додаткові короткі рядки, що додаються до тексту вибору. | -| `markdownCapable` | `boolean` | Позначає канал як такий, що підтримує markdown для вихідного форматування. | -| `showConfigured` | `boolean` | Керує тим, чи показують поверхні списку налаштованих каналів цей канал. | -| `quickstartAllowFrom` | `boolean` | Додає цей канал до стандартного потоку налаштування quickstart `allowFrom`. | -| `forceAccountBinding` | `boolean` | Вимагає явної прив’язки облікового запису, навіть якщо існує лише один запис. | -| `preferSessionLookupForAnnounceTarget` | `boolean` | Віддає перевагу пошуку сесії під час визначення announce targets для цього каналу. | +| Поле | Тип | Що це означає | +| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- | +| `id` | `string` | Канонічний ідентифікатор каналу. | +| `label` | `string` | Основна мітка каналу. | +| `selectionLabel` | `string` | Мітка у виборі/налаштуванні, якщо вона має відрізнятися від `label`. | +| `detailLabel` | `string` | Додаткова мітка для багатших каталогів каналів і поверхонь стану. | +| `docsPath` | `string` | Шлях до документації для посилань налаштування й вибору. | +| `docsLabel` | `string` | Перевизначення мітки для посилань на документацію, якщо вона має відрізнятися від ідентифікатора каналу. | +| `blurb` | `string` | Короткий опис для онбордингу/каталогу. | +| `order` | `number` | Порядок сортування в каталогах каналів. | +| `aliases` | `string[]` | Додаткові псевдоніми пошуку для вибору каналу. | +| `preferOver` | `string[]` | Ідентифікатори плагінів/каналів нижчого пріоритету, які цей канал має випереджати. | +| `systemImage` | `string` | Необов’язкова назва значка/system-image для UI-каталогів каналів. | +| `selectionDocsPrefix` | `string` | Текст-префікс перед посиланнями на документацію в поверхнях вибору. | +| `selectionDocsOmitLabel` | `boolean` | Показувати шлях до документації напряму замість підписаного посилання в тексті вибору. | +| `selectionExtras` | `string[]` | Додаткові короткі рядки, додані в тексті вибору. | +| `markdownCapable` | `boolean` | Позначає канал як сумісний із Markdown для рішень щодо вихідного форматування. | +| `exposure` | `object` | Керування видимістю каналу для налаштування, списків налаштованих каналів і поверхонь документації. | +| `quickstartAllowFrom` | `boolean` | Вмикає для цього каналу стандартний потік налаштування quickstart `allowFrom`. | +| `forceAccountBinding` | `boolean` | Вимагає явної прив’язки облікового запису, навіть якщо існує лише один обліковий запис. | +| `preferSessionLookupForAnnounceTarget` | `boolean` | Надає перевагу пошуку сесії під час визначення announce-target для цього каналу. | Приклад: @@ -132,12 +132,26 @@ x-i18n: "selectionDocsPrefix": "Guide:", "selectionExtras": ["Markdown"], "markdownCapable": true, + "exposure": { + "configured": true, + "setup": true, + "docs": true + }, "quickstartAllowFrom": true } } } ``` +`exposure` підтримує: + +- `configured`: включати канал до поверхонь переліку налаштованих каналів/стану +- `setup`: включати канал до інтерактивних засобів вибору налаштування/конфігурації +- `docs`: позначати канал як публічний у поверхнях документації/навігації + +`showConfigured` і `showInSetup` залишаються підтримуваними як застарілі псевдоніми. Рекомендується +`exposure`. + ### `openclaw.install` `openclaw.install` — це метадані пакета, а не метадані маніфесту. @@ -145,25 +159,24 @@ x-i18n: | Поле | Тип | Що це означає | | ---------------------------- | -------------------- | -------------------------------------------------------------------------------- | | `npmSpec` | `string` | Канонічна npm-специфікація для потоків встановлення/оновлення. | -| `localPath` | `string` | Локальний шлях встановлення для розробки або вбудованого пакета. | -| `defaultChoice` | `"npm"` \| `"local"` | Бажане джерело встановлення, якщо доступні обидва варіанти. | +| `localPath` | `string` | Локальний шлях для розробки або вбудованого встановлення. | +| `defaultChoice` | `"npm"` \| `"local"` | Бажане джерело встановлення, коли доступні обидва варіанти. | | `minHostVersion` | `string` | Мінімальна підтримувана версія OpenClaw у формі `>=x.y.z`. | -| `allowInvalidConfigRecovery` | `boolean` | Дозволяє потокам перевстановлення вбудованих плагінів відновлюватися після певних збоїв застарілої конфігурації. | +| `allowInvalidConfigRecovery` | `boolean` | Дає змогу потокам перевстановлення вбудованих плагінів відновлюватися після окремих збоїв через застарілу конфігурацію. | -Якщо задано `minHostVersion`, його перевіряють і потоки встановлення, і -завантаження реєстру маніфестів. Старіші хости пропускають плагін; некоректні -рядки версій відхиляються. +Якщо задано `minHostVersion`, його перевіряють як під час встановлення, так і +під час завантаження реєстру маніфестів. Старіші хости пропускають плагін; +некоректні рядки версій відхиляються. -`allowInvalidConfigRecovery` не є загальним обходом для зламаних конфігурацій. Це -лише вузький механізм відновлення для вбудованих плагінів, щоб перевстановлення/налаштування -могло виправити відомі залишки після оновлення, як-от відсутній шлях до -вбудованого плагіна або застарілий запис `channels.` для цього ж плагіна. -Якщо конфігурація зламана з непов’язаних причин, встановлення все одно завершується fail-closed і -радить оператору запустити `openclaw doctor --fix`. +`allowInvalidConfigRecovery` — це не загальний обхід для зламаних конфігурацій. Він +призначений лише для вузького відновлення вбудованих плагінів, щоб перевстановлення/налаштування +могло виправити відомі залишки після оновлення, як-от відсутній шлях до вбудованого плагіна або застарілий запис `channels.` +для цього самого плагіна. Якщо конфігурація зламана з інших причин, встановлення +все одно завершується із закритою відмовою та пропонує оператору виконати `openclaw doctor --fix`. ### Відкладене повне завантаження -Плагіни каналів можуть увімкнути відкладене завантаження так: +Плагіни каналів можуть увімкнути відкладене завантаження за допомогою: ```json { @@ -177,26 +190,26 @@ x-i18n: } ``` -Коли це ввімкнено, OpenClaw під час фази запуску до початку прослуховування -завантажує лише `setupEntry`, навіть для вже налаштованих каналів. Повний entry +Якщо цю можливість увімкнено, OpenClaw завантажує лише `setupEntry` під час +передслуховувальної фази запуску, навіть для вже налаштованих каналів. Повна точка входу завантажується після того, як gateway починає слухати. Вмикайте відкладене завантаження лише тоді, коли ваш `setupEntry` реєструє все, - що gateway потребує до початку прослуховування (реєстрацію каналу, HTTP-маршрути, - методи gateway). Якщо необхідні можливості запуску належать повному entry, - залишайте типову поведінку. + що gateway потрібно до початку прослуховування (реєстрацію каналів, HTTP-маршрути, + методи gateway). Якщо повна точка входу володіє необхідними можливостями запуску, залиште + поведінку за замовчуванням. -Якщо ваш setup/full entry реєструє gateway RPC methods, використовуйте для них -префікс, специфічний для плагіна. Зарезервовані простори імен основного admin (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються у власності core і завжди -визначаються як `operator.admin`. +Якщо ваш setup/full entry реєструє RPC-методи gateway, залишайте їх на +префіксі, специфічному для плагіна. Зарезервовані простори імен основного адміністратора (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) належать ядру й завжди зіставляються +з `operator.admin`. ## Маніфест плагіна -Кожен власний плагін має постачатися з `openclaw.plugin.json` у корені пакета. -OpenClaw використовує цей файл для валідації конфігурації без виконання коду плагіна. +Кожен нативний плагін має постачатися з `openclaw.plugin.json` у корені пакета. +OpenClaw використовує його для перевірки конфігурації без виконання коду плагіна. ```json { @@ -231,7 +244,7 @@ OpenClaw використовує цей файл для валідації ко } ``` -Навіть плагіни без конфігурації мають постачатися зі schema. Порожня schema є коректною: +Навіть плагіни без конфігурації мають постачатися зі схемою. Порожня схема є коректною: ```json { @@ -243,25 +256,25 @@ OpenClaw використовує цей файл для валідації ко } ``` -Повний довідник schema див. у [Маніфесті плагіна](/plugins/manifest). +Див. [Plugin Manifest](/uk/plugins/manifest), щоб отримати повний довідник зі схеми. ## Публікація в ClawHub -Для пакетів плагінів використовуйте команду ClawHub, специфічну для пакетів: +Для пакетів плагінів використовуйте команду ClawHub, специфічну для пакета: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Застарілий псевдонім публікації лише для Skills призначений для Skills. Пакети плагінів +Застарілий псевдонім публікації лише для skills призначений для Skills. Пакети плагінів завжди мають використовувати `clawhub package publish`. -## Setup entry +## Точка входу налаштування -Файл `setup-entry.ts` — це полегшена альтернатива `index.ts`, яку +Файл `setup-entry.ts` — це легка альтернатива `index.ts`, яку OpenClaw завантажує, коли йому потрібні лише поверхні налаштування (онбординг, відновлення конфігурації, -перевірка вимкненого каналу). +перевірка вимкнених каналів). ```typescript // setup-entry.ts @@ -271,10 +284,10 @@ import { myChannelPlugin } from "./src/channel.js"; export default defineSetupPluginEntry(myChannelPlugin); ``` -Це дозволяє уникнути завантаження важкого коду runtime (криптобібліотек, CLI-реєстрацій, +Це дає змогу уникнути завантаження важкого runtime-коду (криптографічних бібліотек, реєстрацій CLI, фонових сервісів) під час потоків налаштування. -**Коли OpenClaw використовує `setupEntry` замість повного entry:** +**Коли OpenClaw використовує `setupEntry` замість повної точки входу:** - Канал вимкнено, але потрібні поверхні налаштування/онбордингу - Канал увімкнено, але не налаштовано @@ -286,61 +299,61 @@ export default defineSetupPluginEntry(myChannelPlugin); - Будь-які HTTP-маршрути, потрібні до початку прослуховування gateway - Будь-які методи gateway, потрібні під час запуску -Ці стартові методи gateway усе одно мають уникати зарезервованих просторів імен -основного admin, таких як `config.*` або `update.*`. +Ці методи gateway для запуску все одно мають уникати зарезервованих +просторів імен основного адміністратора, як-от `config.*` або `update.*`. **Що НЕ має містити `setupEntry`:** -- CLI-реєстрації +- Реєстрації CLI - Фонові сервіси -- Важкі runtime-імпорти (crypto, SDK) +- Важкі імпорти runtime (криптографія, SDK) - Методи gateway, потрібні лише після запуску -### Вузькі імпорти setup helpers +### Вузькі імпорти допоміжних засобів налаштування -Для гарячих шляхів лише для налаштування віддавайте перевагу вузьким seams setup helper'ів замість ширшого -umbrella `plugin-sdk/setup`, коли вам потрібна лише частина поверхні налаштування: +Для гарячих шляхів лише налаштування віддавайте перевагу вузьким швам допоміжних засобів налаштування замість ширшої +парасольки `plugin-sdk/setup`, коли вам потрібна лише частина поверхні налаштування: -| Шлях імпорту | Для чого використовувати | Ключові експорти | -| --------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/setup-runtime` | runtime helpers на етапі налаштування, які лишаються доступними в `setupEntry` / під час відкладеного запуску каналу | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | -| `plugin-sdk/setup-adapter-runtime` | environment-aware account setup adapters | `createEnvPatchedAccountSetupAdapter` | -| `plugin-sdk/setup-tools` | CLI/archive/docs helpers для setup/install | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | +| Шлях імпорту | Використовуйте для | Ключові експорти | +| ---------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `plugin-sdk/setup-runtime` | допоміжні засоби runtime під час налаштування, які залишаються доступними в `setupEntry` / відкладеному запуску каналу | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | +| `plugin-sdk/setup-adapter-runtime` | адаптери налаштування облікових записів, що враховують середовище | `createEnvPatchedAccountSetupAdapter` | +| `plugin-sdk/setup-tools` | допоміжні засоби CLI/архівів/документації для налаштування/встановлення | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | -Використовуйте ширший seam `plugin-sdk/setup`, коли вам потрібен повний спільний -набір інструментів для налаштування, зокрема helpers для patch конфігурації, як-от +Використовуйте ширший шов `plugin-sdk/setup`, коли вам потрібен повний спільний +набір інструментів налаштування, включно з допоміжними засобами patch-конфігурації, такими як `moveSingleAccountChannelSectionToDefaultAccount(...)`. -Адаптери patch налаштування лишаються безпечними для імпорту на гарячому шляху. Їхній вбудований -лінивий пошук contract surface для підвищення single-account не виконується завчасно, тому імпорт -`plugin-sdk/setup-runtime` не призводить до раннього завантаження виявлення bundled contract-surface -до фактичного використання адаптера. +Адаптери patch для налаштування залишаються безпечними для імпорту на гарячому шляху. Їхня вбудована +ледача перевірка contract-surface для підвищення одного облікового запису +є лінивою, тому імпорт `plugin-sdk/setup-runtime` не завантажує завчасно +виявлення вбудованої contract-surface до фактичного використання адаптера. -### Підвищення single-account, що належить каналу +### Підвищення одного облікового запису, яке належить каналу -Коли канал оновлюється з top-level конфігурації одного облікового запису до -`channels..accounts.*`, типова спільна поведінка полягає в перенесенні значень -на рівні облікового запису до `accounts.default`. +Коли канал оновлюється з верхньорівневої конфігурації одного облікового запису до +`channels..accounts.*`, типовою спільною поведінкою є переміщення значень, +що належать обліковому запису, до `accounts.default`. -Вбудовані канали можуть звузити або перевизначити це підвищення через свій -setup contract surface: +Вбудовані канали можуть звузити або перевизначити це підвищення через свою +contract-surface налаштування: -- `singleAccountKeysToMove`: додаткові top-level ключі, які слід перенести до +- `singleAccountKeysToMove`: додаткові верхньорівневі ключі, які слід перемістити до підвищеного облікового запису - `namedAccountPromotionKeys`: коли іменовані облікові записи вже існують, лише ці - ключі переносяться до підвищеного облікового запису; спільні policy/delivery ключі лишаються на - корені каналу + ключі переміщуються до підвищеного облікового запису; спільні ключі політики/доставки залишаються в корені + каналу - `resolveSingleAccountPromotionTarget(...)`: вибір наявного облікового запису, - який має отримати підвищені значення + який отримує підвищені значення -Поточний вбудований приклад — Matrix. Якщо вже існує рівно один іменований обліковий запис Matrix, -або якщо `defaultAccount` вказує на наявний неканонічний ключ, наприклад `Ops`, -підвищення зберігає цей обліковий запис замість створення нового запису +Matrix — поточний вбудований приклад. Якщо вже існує рівно один іменований обліковий запис Matrix +або якщо `defaultAccount` вказує на наявний неканонічний ключ, наприклад +`Ops`, підвищення зберігає цей обліковий запис замість створення нового запису `accounts.default`. -## Schema конфігурації +## Схема конфігурації -Конфігурація плагіна проходить валідацію за JSON Schema у вашому маніфесті. Користувачі +Конфігурація плагіна перевіряється відповідно до JSON Schema у вашому маніфесті. Користувачі налаштовують плагіни через: ```json5 @@ -372,10 +385,10 @@ setup contract surface: } ``` -### Побудова schema конфігурації каналу +### Побудова схем конфігурації каналу Використовуйте `buildChannelConfigSchema` з `openclaw/plugin-sdk/core`, щоб перетворити -schema Zod на обгортку `ChannelConfigSchema`, яку валідує OpenClaw: +схему Zod на обгортку `ChannelConfigSchema`, яку перевіряє OpenClaw: ```typescript import { z } from "zod"; @@ -428,12 +441,13 @@ const setupWizard: ChannelSetupWizard = { ``` Тип `ChannelSetupWizard` підтримує `credentials`, `textInputs`, -`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` та інше. -Повні приклади див. у пакетах вбудованих плагінів (наприклад, у Discord plugin `src/channel.setup.ts`). +`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` та інші можливості. +Див. пакети вбудованих плагінів (наприклад, плагін Discord `src/channel.setup.ts`) для +повних прикладів. -Для prompt'ів списку дозволів DM, яким потрібен лише стандартний потік -`note -> prompt -> parse -> merge -> patch`, віддавайте перевагу спільним setup -helper'ам з `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`, +Для запитів списку дозволених DM, яким потрібен лише стандартний +потік `note -> prompt -> parse -> merge -> patch`, віддавайте перевагу спільним допоміжним засобам налаштування +з `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`, `createTopLevelChannelParsedAllowFromPrompt(...)` і `createNestedChannelParsedAllowFromPrompt(...)`. @@ -457,67 +471,67 @@ const setupSurface = createOptionalChannelSetupSurface({ // Returns { setupAdapter, setupWizard } ``` -`plugin-sdk/channel-setup` також надає нижчорівневі конструктори -`createOptionalChannelSetupAdapter(...)` і +`plugin-sdk/channel-setup` також надає низькорівневі +конструктори `createOptionalChannelSetupAdapter(...)` і `createOptionalChannelSetupWizard(...)`, коли вам потрібна лише одна половина цієї необов’язкової поверхні встановлення. -Згенеровані необов’язкові adapter/wizard працюють у режимі fail-closed під час реального запису конфігурації. Вони +Згенеровані необов’язкові adapter/wizard відмовляють у закритому режимі під час реальних записів конфігурації. Вони повторно використовують одне повідомлення про необхідність встановлення у `validateInput`, `applyAccountConfig` і `finalize`, а також додають посилання на документацію, якщо задано `docsPath`. -Для UI налаштування на основі бінарних файлів віддавайте перевагу спільним delegated helper'ам замість -копіювання однакової логіки binary/status у кожен канал: +Для UI налаштування, що спираються на бінарні файли, віддавайте перевагу спільним делегованим допоміжним засобам замість +копіювання однакового glue-коду бінарних файлів/стану в кожен канал: -- `createDetectedBinaryStatus(...)` для блоків статусу, що відрізняються лише мітками, - підказками, оцінками та виявленням бінарного файлу -- `createCliPathTextInput(...)` для текстових полів, прив’язаних до шляху +- `createDetectedBinaryStatus(...)` для блоків стану, що відрізняються лише мітками, + підказками, оцінками та виявленням бінарного файла +- `createCliPathTextInput(...)` для текстових полів на основі шляху - `createDelegatedSetupWizardStatusResolvers(...)`, `createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` і - `createDelegatedResolveConfigured(...)`, коли `setupEntry` має ліниво переспрямовувати - до важчого повного wizard + `createDelegatedResolveConfigured(...)`, коли `setupEntry` має ліниво переспрямовувати до + важчого повного майстра - `createDelegatedTextInputShouldPrompt(...)`, коли `setupEntry` потрібно лише делегувати рішення `textInputs[*].shouldPrompt` ## Публікація та встановлення -**Зовнішні плагіни:** опублікуйте в [ClawHub](/tools/clawhub) або npm, а потім установіть: +**Зовнішні плагіни:** опублікуйте в [ClawHub](/uk/tools/clawhub) або npm, а потім встановіть: ```bash openclaw plugins install @myorg/openclaw-my-plugin ``` -OpenClaw спочатку пробує ClawHub і автоматично переходить до npm. Ви також можете -явно примусово використовувати ClawHub: +OpenClaw спочатку намагається використати ClawHub і автоматично переходить до npm у разі невдачі. Ви також можете +явно примусово використати ClawHub: ```bash -openclaw plugins install clawhub:@myorg/openclaw-my-plugin # лише ClawHub +openclaw plugins install clawhub:@myorg/openclaw-my-plugin # Лише ClawHub ``` -Відповідного перевизначення `npm:` немає. Використовуйте звичайну npm-spec пакета, коли -хочете шлях npm після fallback з ClawHub: +Відповідного перевизначення `npm:` не існує. Використовуйте звичайну специфікацію npm-пакета, коли +вам потрібен шлях npm після резервного переходу з ClawHub: ```bash openclaw plugins install @myorg/openclaw-my-plugin ``` -**Плагіни в репозиторії:** розміщуйте їх у дереві workspace вбудованих плагінів, і вони автоматично -виявлятимуться під час збирання. +**Плагіни в репозиторії:** розмістіть їх у дереві workspace вбудованих плагінів, і вони +автоматично виявлятимуться під час збірки. -**Користувачі можуть установлювати:** +**Користувачі можуть встановлювати:** ```bash openclaw plugins install ``` - Для встановлень із npm `openclaw plugins install` виконує - `npm install --ignore-scripts` (без lifecycle scripts). Зберігайте дерева - залежностей плагіна чистими JS/TS і уникайте пакетів, які потребують збирання через `postinstall`. + Для встановлень із джерела npm `openclaw plugins install` виконує + `npm install --ignore-scripts` (без lifecycle-скриптів). Зберігайте дерева залежностей плагіна + чистими JS/TS і уникайте пакетів, які потребують збірок через `postinstall`. ## Пов’язане -- [Точки входу SDK](/plugins/sdk-entrypoints) -- `definePluginEntry` і `defineChannelPluginEntry` -- [Маніфест плагіна](/plugins/manifest) -- повний довідник schema маніфесту -- [Створення плагінів](/plugins/building-plugins) -- покроковий посібник для початку роботи +- [SDK Entry Points](/uk/plugins/sdk-entrypoints) -- `definePluginEntry` і `defineChannelPluginEntry` +- [Plugin Manifest](/uk/plugins/manifest) -- повний довідник зі схемою маніфесту +- [Building Plugins](/uk/plugins/building-plugins) -- покроковий посібник для початку роботи diff --git a/docs/uk/providers/alibaba.md b/docs/uk/providers/alibaba.md index 4f12602e0..9599874e5 100644 --- a/docs/uk/providers/alibaba.md +++ b/docs/uk/providers/alibaba.md @@ -1,21 +1,21 @@ --- read_when: - Ви хочете використовувати генерацію відео Alibaba Wan в OpenClaw - - Вам потрібно налаштувати API-ключ Model Studio або DashScope для генерації відео + - Вам потрібно налаштувати ключ API Model Studio або DashScope для генерації відео summary: Генерація відео Wan в Alibaba Model Studio в OpenClaw title: Alibaba Model Studio x-i18n: - generated_at: "2026-04-05T22:22:55Z" + generated_at: "2026-04-05T22:36:47Z" model: gpt-5.4 provider: openai - source_hash: dca1ddd91e884773c3835eebda2da3da2994f82f940bdd26fe94e55cac149058 + source_hash: 97a1eddc7cbd816776b9368f2a926b5ef9ee543f08d151a490023736f67dc635 source_path: providers/alibaba.md workflow: 15 --- # Alibaba Model Studio -OpenClaw постачається з вбудованим провайдером генерації відео `alibaba` для моделей Wan в +OpenClaw постачається з вбудованим провайдером генерації відео `alibaba` для моделей Wan у Alibaba Model Studio / DashScope. - Провайдер: `alibaba` @@ -25,7 +25,7 @@ Alibaba Model Studio / DashScope. ## Швидкий старт -1. Установіть API-ключ: +1. Установіть ключ API: ```bash openclaw onboard --auth-choice qwen-standard-api-key @@ -61,20 +61,19 @@ openclaw onboard --auth-choice qwen-standard-api-key - До **1** вхідного зображення - До **4** вхідних відео - Тривалість до **10 секунд** -- Підтримує `size`, `aspectRatio`, `resolution`, `audio` і `watermark` -- Режим з еталонним зображенням/відео наразі вимагає **віддалені URL-адреси http(s)** +- Підтримуються `size`, `aspectRatio`, `resolution`, `audio` і `watermark` +- Режим еталонного зображення/відео наразі потребує **віддалених URL-адрес http(s)** ## Зв’язок із Qwen -Вбудований провайдер `qwen` також використовує розміщені в Alibaba кінцеві точки DashScope для +Вбудований провайдер `qwen` також використовує розміщені Alibaba кінцеві точки DashScope для генерації відео Wan. Використовуйте: - `qwen/...`, якщо вам потрібна канонічна поверхня провайдера Qwen -- `alibaba/...`, якщо вам потрібна пряма поверхня відео Wan від постачальника +- `alibaba/...`, якщо вам потрібна пряма поверхня генерації відео Wan від постачальника ## Пов’язане - [Генерація відео](/uk/tools/video-generation) - [Qwen](/uk/providers/qwen) -- [Qwen / Model Studio](/uk/providers/qwen_modelstudio) - [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) diff --git a/docs/uk/providers/index.md b/docs/uk/providers/index.md index 79ae18267..d6378d7b8 100644 --- a/docs/uk/providers/index.md +++ b/docs/uk/providers/index.md @@ -1,28 +1,28 @@ --- read_when: - - Ви хочете вибрати провайдера моделі + - Ви хочете вибрати постачальника моделей - Вам потрібен короткий огляд підтримуваних бекендів LLM -summary: Провайдери моделей (LLM), які підтримує OpenClaw -title: Каталог провайдерів +summary: Постачальники моделей (LLM), які підтримує OpenClaw +title: Каталог постачальників x-i18n: - generated_at: "2026-04-05T22:22:59Z" + generated_at: "2026-04-05T22:36:52Z" model: gpt-5.4 provider: openai - source_hash: a13202fc20a64c68e9c7de4f2cd8ad11908029f3fe3300a8e6d69fcb0b6080ba + source_hash: 83911cf9bba0d0711fd49081529becf4eb1eea08b61079d71eac927a1d069061 source_path: providers/index.md workflow: 15 --- -# Провайдери моделей +# Постачальники моделей -OpenClaw може використовувати багато провайдерів LLM. Виберіть провайдера, пройдіть автентифікацію, а потім задайте модель за замовчуванням як `provider/model`. +OpenClaw може використовувати багато постачальників LLM. Виберіть постачальника, пройдіть автентифікацію, а потім установіть модель за замовчуванням у форматі `provider/model`. -Шукаєте документацію щодо каналів чату (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/тощо)? Див. [Канали](/uk/channels). +Шукаєте документацію про канали чату (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/тощо)? Див. [Channels](/uk/channels). ## Швидкий старт -1. Пройдіть автентифікацію у провайдера (зазвичай через `openclaw onboard`). -2. Задайте модель за замовчуванням: +1. Пройдіть автентифікацію у постачальника (зазвичай через `openclaw onboard`). +2. Установіть модель за замовчуванням: ```json5 { @@ -30,22 +30,22 @@ OpenClaw може використовувати багато провайдер } ``` -## Документація провайдерів +## Документація постачальників -- [Alibaba Model Studio](/providers/alibaba) +- [Alibaba Model Studio](/uk/providers/alibaba) - [Amazon Bedrock](/uk/providers/bedrock) - [Anthropic (API + Claude CLI)](/uk/providers/anthropic) -- [BytePlus (міжнародний)](/uk/concepts/model-providers#byteplus-international) +- [BytePlus (Міжнародний)](/uk/concepts/model-providers#byteplus-international) - [Chutes](/uk/providers/chutes) - [Cloudflare AI Gateway](/uk/providers/cloudflare-ai-gateway) - [DeepSeek](/uk/providers/deepseek) -- [fal](/providers/fal) +- [fal](/uk/providers/fal) - [Fireworks](/uk/providers/fireworks) - [GitHub Copilot](/uk/providers/github-copilot) - [Моделі GLM](/uk/providers/glm) - [Google (Gemini)](/uk/providers/google) -- [Groq (LPU-інференс)](/uk/providers/groq) -- [Hugging Face (інференс)](/uk/providers/huggingface) +- [Groq (LPU inference)](/uk/providers/groq) +- [Hugging Face (Inference)](/uk/providers/huggingface) - [Kilocode](/uk/providers/kilocode) - [LiteLLM (уніфікований шлюз)](/uk/providers/litellm) - [MiniMax](/uk/providers/minimax) @@ -60,12 +60,11 @@ OpenClaw може використовувати багато провайдер - [Perplexity (вебпошук)](/uk/providers/perplexity-provider) - [Qianfan](/uk/providers/qianfan) - [Qwen Cloud](/uk/providers/qwen) -- [Qwen / Model Studio (деталі endpoint; `qwen-*` canonical, `modelstudio-*` legacy)](/uk/providers/qwen_modelstudio) - [SGLang (локальні моделі)](/uk/providers/sglang) - [StepFun](/uk/providers/stepfun) - [Synthetic](/uk/providers/synthetic) - [Together AI](/uk/providers/together) -- [Venice (Venice AI, з фокусом на приватність)](/uk/providers/venice) +- [Venice (Venice AI, орієнтований на конфіденційність)](/uk/providers/venice) - [Vercel AI Gateway](/uk/providers/vercel-ai-gateway) - [vLLM (локальні моделі)](/uk/providers/vllm) - [Volcengine (Doubao)](/uk/providers/volcengine) @@ -73,18 +72,18 @@ OpenClaw може використовувати багато провайдер - [Xiaomi](/uk/providers/xiaomi) - [Z.AI](/uk/providers/zai) -## Спільні оглядові сторінки +## Спільні сторінки огляду -- [Додаткові вбудовані варіанти](/uk/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy та Gemini CLI OAuth -- [Генерація зображень](/uk/tools/image-generation) - Спільний інструмент `image_generate`, вибір провайдера та failover -- [Генерація відео](/uk/tools/video-generation) - Спільний інструмент `video_generate`, вибір провайдера та failover +- [Додаткові вбудовані варіанти](/uk/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy і Gemini CLI OAuth +- [Генерація зображень](/uk/tools/image-generation) - Спільний інструмент `image_generate`, вибір постачальника та failover +- [Генерація відео](/uk/tools/video-generation) - Спільний інструмент `video_generate`, вибір постачальника та failover -## Провайдери транскрибування +## Постачальники транскрипції -- [Deepgram (транскрибування аудіо)](/uk/providers/deepgram) +- [Deepgram (транскрипція аудіо)](/uk/providers/deepgram) ## Інструменти спільноти -- [Claude Max API Proxy](/uk/providers/claude-max-api-proxy) - Проксі від спільноти для облікових даних підписки Claude (перед використанням перевірте політику/умови Anthropic) +- [Claude Max API Proxy](/uk/providers/claude-max-api-proxy) - Проксі спільноти для облікових даних підписки Claude (перед використанням перевірте політику/умови Anthropic) -Повний каталог провайдерів (xAI, Groq, Mistral тощо) і розширену конфігурацію див. у розділі [Провайдери моделей](/uk/concepts/model-providers). +Для повного каталогу постачальників (xAI, Groq, Mistral тощо) і розширеної конфігурації див. [Model providers](/uk/concepts/model-providers). diff --git a/docs/uk/providers/qwen.md b/docs/uk/providers/qwen.md index 9ab9de474..a8b06b724 100644 --- a/docs/uk/providers/qwen.md +++ b/docs/uk/providers/qwen.md @@ -5,10 +5,10 @@ read_when: summary: Використовуйте Qwen Cloud через вбудований провайдер qwen в OpenClaw title: Qwen x-i18n: - generated_at: "2026-04-05T22:23:05Z" + generated_at: "2026-04-05T22:37:14Z" model: gpt-5.4 provider: openai - source_hash: c1e1022a368513fd09474a2c2b8394911787a6bc5e325868da590a3d32446a34 + source_hash: f175793693ab6a4c3f1f4d42040e673c15faf7603a500757423e9e06977c989d source_path: providers/qwen.md workflow: 15 --- @@ -18,46 +18,46 @@ x-i18n: **Qwen OAuth було видалено.** Інтеграція OAuth безкоштовного рівня -(`qwen-portal`), яка використовувала ендпоінти `portal.qwen.ai`, більше недоступна. +(`qwen-portal`), яка використовувала кінцеві точки `portal.qwen.ai`, більше недоступна. Див. [Issue #49557](https://github.com/openclaw/openclaw/issues/49557) для -додаткового контексту. +довідки. ## Рекомендовано: Qwen Cloud -Тепер OpenClaw розглядає Qwen як вбудований провайдер першого класу з канонічним id -`qwen`. Вбудований провайдер націлено на ендпоінти Qwen Cloud / Alibaba DashScope і -Coding Plan та зберігає роботу застарілих id `modelstudio` як -аліаса сумісності. +Тепер OpenClaw розглядає Qwen як першокласного вбудованого провайдера з канонічним ідентифікатором +`qwen`. Вбудований провайдер націлений на кінцеві точки Qwen Cloud / Alibaba DashScope та +Coding Plan і зберігає роботу застарілих ідентифікаторів `modelstudio` як +псевдонім сумісності. - Провайдер: `qwen` - Бажана змінна середовища: `QWEN_API_KEY` - Також приймаються для сумісності: `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY` - Стиль API: сумісний з OpenAI -Якщо ви хочете використовувати `qwen3.6-plus`, надавайте перевагу ендпоінту **Standard (оплата за використання)**. +Якщо вам потрібен `qwen3.6-plus`, надавайте перевагу кінцевій точці **Standard (pay-as-you-go)**. Підтримка Coding Plan може відставати від публічного каталогу. ```bash -# Глобальний ендпоінт Coding Plan +# Глобальна кінцева точка Coding Plan openclaw onboard --auth-choice qwen-api-key -# Китайський ендпоінт Coding Plan +# Китайська кінцева точка Coding Plan openclaw onboard --auth-choice qwen-api-key-cn -# Глобальний ендпоінт Standard (оплата за використання) +# Глобальна кінцева точка Standard (pay-as-you-go) openclaw onboard --auth-choice qwen-standard-api-key -# Китайський ендпоінт Standard (оплата за використання) +# Китайська кінцева точка Standard (pay-as-you-go) openclaw onboard --auth-choice qwen-standard-api-key-cn ``` -Застарілі id `auth-choice` у форматі `modelstudio-*` і посилання на моделі `modelstudio/...` досі -працюють як аліаси сумісності, але в нових сценаріях налаштування слід надавати перевагу канонічним -id `auth-choice` у форматі `qwen-*` і посиланням на моделі `qwen/...`. +Застарілі ідентифікатори `auth-choice` у форматі `modelstudio-*` і посилання на моделі `modelstudio/...` усе ще +працюють як псевдоніми сумісності, але в нових потоках налаштування слід надавати перевагу канонічним +ідентифікаторам `auth-choice` у форматі `qwen-*` і посиланням на моделі `qwen/...`. -Після онбордингу встановіть типову модель: +Після онбордингу встановіть модель за замовчуванням: ```json5 { @@ -69,48 +69,110 @@ id `auth-choice` у форматі `qwen-*` і посиланням на мод } ``` +## Типи планів і кінцеві точки + +| План | Регіон | Вибір автентифікації | Кінцева точка | +| -------------------------- | ------ | -------------------------- | ------------------------------------------------ | +| Standard (pay-as-you-go) | China | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` | +| Standard (pay-as-you-go) | Global | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` | +| Coding Plan (subscription) | China | `qwen-api-key-cn` | `coding.dashscope.aliyuncs.com/v1` | +| Coding Plan (subscription) | Global | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` | + +Провайдер автоматично вибирає кінцеву точку на основі вашого вибору автентифікації. Канонічні +варіанти використовують сімейство `qwen-*`; `modelstudio-*` залишається лише для сумісності. +Ви можете перевизначити це за допомогою власного `baseUrl` у конфігурації. + +Нативні кінцеві точки Model Studio оголошують сумісність використання потокового передавання на +спільному транспорті `openai-completions`. Тепер OpenClaw прив’язує це до можливостей кінцевої точки, тож +користувацькі ідентифікатори провайдера, сумісні з DashScope, які націлені на ті самі нативні хости, +успадковують ту саму поведінку потокового використання замість того, +щоб вимагати саме вбудований ідентифікатор провайдера `qwen`. + +## Отримайте свій ключ API + +- **Керування ключами**: [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys) +- **Документація**: [docs.qwencloud.com](https://docs.qwencloud.com/developer-guides/getting-started/introduction) + +## Вбудований каталог + +Наразі OpenClaw постачається з таким вбудованим каталогом Qwen: + +| Посилання на модель | Вхідні дані | Контекст | Примітки | +| --------------------------- | ----------- | --------- | -------------------------------------------------- | +| `qwen/qwen3.5-plus` | text, image | 1,000,000 | Модель за замовчуванням | +| `qwen/qwen3.6-plus` | text, image | 1,000,000 | Надавайте перевагу кінцевим точкам Standard, коли потрібна ця модель | +| `qwen/qwen3-max-2026-01-23` | text | 262,144 | Лінійка Qwen Max | +| `qwen/qwen3-coder-next` | text | 262,144 | Для кодування | +| `qwen/qwen3-coder-plus` | text | 1,000,000 | Для кодування | +| `qwen/MiniMax-M2.5` | text | 1,000,000 | Увімкнено міркування | +| `qwen/glm-5` | text | 202,752 | GLM | +| `qwen/glm-4.7` | text | 202,752 | GLM | +| `qwen/kimi-k2.5` | text, image | 262,144 | Moonshot AI через Alibaba | + +Доступність усе ще може відрізнятися залежно від кінцевої точки та тарифного плану, навіть якщо модель +є у вбудованому каталозі. + +Сумісність використання нативного потокового передавання застосовується як до хостів Coding Plan, так і +до сумісних із DashScope хостів Standard: + +- `https://coding.dashscope.aliyuncs.com/v1` +- `https://coding-intl.dashscope.aliyuncs.com/v1` +- `https://dashscope.aliyuncs.com/compatible-mode/v1` +- `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` + +## Доступність Qwen 3.6 Plus + +`qwen3.6-plus` доступна на кінцевих точках Model Studio Standard (pay-as-you-go): + +- China: `dashscope.aliyuncs.com/compatible-mode/v1` +- Global: `dashscope-intl.aliyuncs.com/compatible-mode/v1` + +Якщо кінцеві точки Coding Plan повертають помилку "unsupported model" для +`qwen3.6-plus`, перейдіть на Standard (pay-as-you-go) замість пари +кінцевої точки/ключа Coding Plan. + ## План можливостей -Розширення `qwen` позиціонується як основне середовище постачальника для всієї поверхні Qwen +Розширення `qwen` позиціонується як дім постачальника для повної поверхні Qwen Cloud, а не лише для моделей кодування/тексту. - Текстові/чат-моделі: уже вбудовано -- Виклик інструментів, структурований вивід, thinking: успадковуються від сумісного з OpenAI транспорту +- Виклик інструментів, структурований вивід, міркування: успадковано від транспорту, сумісного з OpenAI - Генерація зображень: заплановано на рівні плагіна провайдера -- Розуміння зображень/відео: уже вбудовано в ендпоінті Standard +- Розуміння зображень/відео: уже вбудовано на кінцевій точці Standard - Мовлення/аудіо: заплановано на рівні плагіна провайдера -- Ембеддинги пам’яті/переранжування: заплановано через поверхню адаптера ембеддингів +- Вбудовування пам’яті/переранжування: заплановано через поверхню адаптера embeddings - Генерація відео: уже вбудовано через спільну можливість генерації відео ## Мультимодальні доповнення -Розширення `qwen` тепер також надає: +Тепер розширення `qwen` також надає: - Розуміння відео через `qwen-vl-max-latest` - Генерацію відео Wan через: - - `wan2.6-t2v` (типово) + - `wan2.6-t2v` (за замовчуванням) - `wan2.6-i2v` - `wan2.6-r2v` - `wan2.6-r2v-flash` - `wan2.7-r2v` -Ці мультимодальні поверхні використовують ендпоінти DashScope **Standard**, а не -ендпоінти Coding Plan. +Ці мультимодальні поверхні використовують кінцеві точки DashScope **Standard**, а не +кінцеві точки Coding Plan. -- Базовий URL Global/Intl Standard: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` -- Базовий URL China Standard: `https://dashscope.aliyuncs.com/compatible-mode/v1` +- Базовий URL Standard Global/Intl: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` +- Базовий URL Standard China: `https://dashscope.aliyuncs.com/compatible-mode/v1` -Для генерації відео OpenClaw зіставляє налаштований регіон Qwen з відповідним +Для генерації відео OpenClaw зіставляє налаштований регіон Qwen із відповідним хостом DashScope AIGC перед надсиланням завдання: - Global/Intl: `https://dashscope-intl.aliyuncs.com` - China: `https://dashscope.aliyuncs.com` -Це означає, що звичайний `models.providers.qwen.baseUrl`, який вказує або на -хости Qwen Coding Plan, або на Standard, усе одно забезпечує генерацію відео через правильний -регіональний відеоендпоінт DashScope. +Це означає, що звичайний `models.providers.qwen.baseUrl`, який вказує на будь-який із +хостів Qwen для Coding Plan або Standard, усе одно зберігає генерацію відео на правильній +регіональній кінцевій точці відео DashScope. -Для генерації відео явно встановіть типову модель: +Для генерації відео явно встановіть модель за замовчуванням: ```json5 { @@ -128,13 +190,16 @@ Cloud, а не лише для моделей кодування/тексту. - До **1** вхідного зображення - До **4** вхідних відео - Тривалість до **10 секунд** -- Підтримує `size`, `aspectRatio`, `resolution`, `audio` і `watermark` -- Режим еталонного зображення/відео наразі вимагає **віддалених URL http(s)**. Локальні - шляхи до файлів відхиляються одразу, оскільки відеоендпоінт DashScope не - приймає завантажені локальні буфери для таких еталонів. +- Підтримуються `size`, `aspectRatio`, `resolution`, `audio` і `watermark` +- Режим еталонного зображення/відео наразі потребує **віддалених URL-адрес http(s)**. Локальні + шляхи до файлів відхиляються одразу, оскільки кінцева точка відео DashScope не + приймає завантажені локальні буфери для цих еталонів. -Див. [Video Generation](/uk/tools/video-generation) щодо спільних параметрів -інструмента, вибору провайдера та поведінки перемикання при збоях. +Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні параметри +інструмента, вибір провайдера та поведінку failover. -Див. [Qwen / Model Studio](/uk/providers/qwen_modelstudio) щодо деталей на рівні ендпоінтів -і приміток щодо сумісності. +## Примітка щодо середовища + +Якщо Gateway працює як демон (launchd/systemd), переконайтеся, що `QWEN_API_KEY` +доступний цьому процесу (наприклад, у `~/.openclaw/.env` або через +`env.shellEnv`). diff --git a/docs/uk/providers/qwen_modelstudio.md b/docs/uk/providers/qwen_modelstudio.md index 564f24214..8c3d46ddd 100644 --- a/docs/uk/providers/qwen_modelstudio.md +++ b/docs/uk/providers/qwen_modelstudio.md @@ -1,149 +1,18 @@ --- read_when: - - Вам потрібні деталі на рівні кінцевих точок для Qwen Cloud / Alibaba DashScope - - Вам потрібна інформація про сумісність змінних середовища для провайдера qwen - - Ви хочете використовувати кінцеву точку Standard (pay-as-you-go) або Coding Plan -summary: Деталі кінцевих точок для вбудованого провайдера qwen і його застарілої поверхні сумісності modelstudio + - Ви перейшли за старішим посиланням Model Studio + - Ви хочете відкрити канонічну сторінку постачальника Qwen +summary: Перенаправлення до /providers/qwen title: Qwen / Model Studio x-i18n: - generated_at: "2026-04-05T22:23:16Z" + generated_at: "2026-04-05T22:36:55Z" model: gpt-5.4 provider: openai - source_hash: f21bf55e7acf51131027a1c1faf5fa85a00757ee40995ea4e1d24935cd310e24 + source_hash: 9397492125a033586a432faed8e6d667e6bfd12c5b34ab98e665abf6491c8f7d source_path: providers/qwen_modelstudio.md workflow: 15 --- -# Qwen / Model Studio (Alibaba Cloud) +# Qwen / Model Studio -На цій сторінці описано зіставлення кінцевих точок, яке використовується у вбудованому провайдері `qwen` в OpenClaw. Провайдер зберігає ідентифікатори провайдера `modelstudio`, ідентифікатори вибору автентифікації та посилання на моделі в робочому стані як псевдоніми сумісності, тоді як `qwen` стає канонічною поверхнею. - - - -Якщо вам потрібна **`qwen3.6-plus`**, віддавайте перевагу **Standard (pay-as-you-go)**. Доступність у Coding Plan може відставати від публічного каталогу Model Studio, а API Coding Plan може відхиляти модель, доки вона не з’явиться в списку підтримуваних моделей вашого плану. - - - -- Провайдер: `qwen` (застарілий псевдонім: `modelstudio`) -- Автентифікація: `QWEN_API_KEY` -- Також приймаються: `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY` -- API: сумісний з OpenAI - -## Швидкий початок - -### Standard (pay-as-you-go) - -```bash -# China endpoint -openclaw onboard --auth-choice qwen-standard-api-key-cn - -# Global/Intl endpoint -openclaw onboard --auth-choice qwen-standard-api-key -``` - -### Coding Plan (subscription) - -```bash -# China endpoint -openclaw onboard --auth-choice qwen-api-key-cn - -# Global/Intl endpoint -openclaw onboard --auth-choice qwen-api-key -``` - -Застарілі ідентифікатори вибору автентифікації `modelstudio-*` усе ще працюють як псевдоніми сумісності, але канонічними ідентифікаторами для онбордингу є варіанти `qwen-*`, показані вище. - -Після онбордингу встановіть типову модель: - -```json5 -{ - agents: { - defaults: { - model: { primary: "qwen/qwen3.5-plus" }, - }, - }, -} -``` - -## Типи планів і кінцеві точки - -| План | Регіон | Вибір автентифікації | Кінцева точка | -| -------------------------- | ------ | ------------------------- | ------------------------------------------------ | -| Standard (pay-as-you-go) | China | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` | -| Standard (pay-as-you-go) | Global | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` | -| Coding Plan (subscription) | China | `qwen-api-key-cn` | `coding.dashscope.aliyuncs.com/v1` | -| Coding Plan (subscription) | Global | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` | - -Провайдер автоматично вибирає кінцеву точку на основі вашого вибору автентифікації. Канонічні варіанти використовують сімейство `qwen-*`; `modelstudio-*` залишається лише для сумісності. Ви можете перевизначити це за допомогою власного `baseUrl` у конфігурації. - -Нативні кінцеві точки Model Studio повідомляють про сумісність використання потокового режиму на спільному транспорті `openai-completions`. Тепер OpenClaw визначає це за можливостями кінцевої точки, тому сумісні з DashScope власні ідентифікатори провайдерів, націлені на ті самі нативні хости, успадковують ту саму поведінку потокового використання, замість того щоб вимагати саме вбудований ідентифікатор провайдера `qwen`. - -## Отримайте свій API-ключ - -- **Керування ключами**: [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys) -- **Документація**: [docs.qwencloud.com](https://docs.qwencloud.com/developer-guides/getting-started/introduction) - -## Вбудований каталог - -Зараз OpenClaw постачається з таким вбудованим каталогом Qwen: - -| Посилання на модель | Вхідні дані | Контекст | Примітки | -| --------------------------- | ----------- | --------- | -------------------------------------------------- | -| `qwen/qwen3.5-plus` | text, image | 1,000,000 | Типова модель | -| `qwen/qwen3.6-plus` | text, image | 1,000,000 | Віддавайте перевагу кінцевим точкам Standard, якщо вам потрібна ця модель | -| `qwen/qwen3-max-2026-01-23` | text | 262,144 | Лінійка Qwen Max | -| `qwen/qwen3-coder-next` | text | 262,144 | Програмування | -| `qwen/qwen3-coder-plus` | text | 1,000,000 | Програмування | -| `qwen/MiniMax-M2.5` | text | 1,000,000 | Логічне міркування увімкнено | -| `qwen/glm-5` | text | 202,752 | GLM | -| `qwen/glm-4.7` | text | 202,752 | GLM | -| `qwen/kimi-k2.5` | text, image | 262,144 | Moonshot AI через Alibaba | - -Доступність усе ще може відрізнятися залежно від кінцевої точки та тарифного плану, навіть якщо модель присутня у вбудованому каталозі. - -Сумісність використання нативного потокового режиму застосовується як до хостів Coding Plan, так і до сумісних зі Standard DashScope хостів: - -- `https://coding.dashscope.aliyuncs.com/v1` -- `https://coding-intl.dashscope.aliyuncs.com/v1` -- `https://dashscope.aliyuncs.com/compatible-mode/v1` -- `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` - -## Доступність Qwen 3.6 Plus - -`qwen3.6-plus` доступна на кінцевих точках Model Studio Standard (pay-as-you-go): - -- China: `dashscope.aliyuncs.com/compatible-mode/v1` -- Global: `dashscope-intl.aliyuncs.com/compatible-mode/v1` - -Якщо кінцеві точки Coding Plan повертають помилку "unsupported model" для `qwen3.6-plus`, перейдіть на Standard (pay-as-you-go) замість пари кінцева точка/ключ Coding Plan. - -## Примітка щодо середовища - -Якщо Gateway працює як демон (launchd/systemd), переконайтеся, що `QWEN_API_KEY` доступний для цього процесу (наприклад, у `~/.openclaw/.env` або через `env.shellEnv`). - -## Генерація відео Wan - -Поверхня Standard DashScope також лежить в основі вбудованих провайдерів генерації відео Wan. - -Ви можете звертатися до тієї самої сім’ї Wan через будь-який із префіксів: - -- канонічні посилання Qwen: - - `qwen/wan2.6-t2v` - - `qwen/wan2.6-i2v` - - `qwen/wan2.6-r2v` - - `qwen/wan2.6-r2v-flash` - - `qwen/wan2.7-r2v` -- прямі посилання Alibaba: - - `alibaba/wan2.6-t2v` - - `alibaba/wan2.6-i2v` - - `alibaba/wan2.6-r2v` - - `alibaba/wan2.6-r2v-flash` - - `alibaba/wan2.7-r2v` - -Усі режими посилань Wan наразі вимагають **віддалені URL-адреси http(s)** для посилань на зображення або відео. Локальні шляхи до файлів відхиляються до завантаження, оскільки кінцева точка відео DashScope не приймає еталонні ресурси з локальних буферів для цих режимів. - -## Пов’язане - -- [Qwen](/uk/providers/qwen) -- [Alibaba Model Studio](/providers/alibaba) -- [Генерація відео](/uk/tools/video-generation) +Цю сторінку перенесено до [Qwen](/uk/providers/qwen). Див. [Qwen](/uk/providers/qwen), щоб дізнатися про канонічне налаштування постачальника, подробиці endpoint, псевдоніми сумісності та примітки щодо генерації відео Wan. diff --git a/docs/uk/tools/video-generation.md b/docs/uk/tools/video-generation.md index c1567f5f9..729433ed2 100644 --- a/docs/uk/tools/video-generation.md +++ b/docs/uk/tools/video-generation.md @@ -1,15 +1,15 @@ --- read_when: - - Генерація відео через агента + - Створення відео через агента - Налаштування провайдерів і моделей генерації відео - - Розуміння параметрів інструмента video_generate -summary: Генеруйте відео за допомогою налаштованих провайдерів, таких як Alibaba, OpenAI, Google, Qwen і MiniMax + - Розуміння параметрів інструмента `video_generate` +summary: Створюйте відео за допомогою налаштованих провайдерів, таких як Alibaba, OpenAI, Google, Qwen і MiniMax title: Генерація відео x-i18n: - generated_at: "2026-04-05T22:23:33Z" + generated_at: "2026-04-05T22:37:17Z" model: gpt-5.4 provider: openai - source_hash: 6bcaf4adf187254d1c9fac8a7e3578b863c736149beffb2517381ebe101bffb8 + source_hash: 138de16fae7c0f00d1e2be55e62ccd6d8ea9e6364dc7f0159a68f9b00a2902eb source_path: tools/video-generation.md workflow: 15 --- @@ -19,13 +19,13 @@ x-i18n: Інструмент `video_generate` дає змогу агенту створювати відео за допомогою ваших налаштованих провайдерів. Згенеровані відео автоматично доставляються як медіавкладення у відповіді агента. -Інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації відео. Якщо ви не бачите `video_generate` в інструментах свого агента, налаштуйте `agents.defaults.videoGenerationModel` або задайте API-ключ провайдера. +Інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації відео. Якщо ви не бачите `video_generate` серед інструментів агента, налаштуйте `agents.defaults.videoGenerationModel` або встановіть API-ключ провайдера. ## Швидкий старт 1. Установіть API-ключ принаймні для одного провайдера (наприклад, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `MODELSTUDIO_API_KEY` або `QWEN_API_KEY`). -2. За бажанням установіть бажану модель: +2. За потреби задайте бажану модель: ```json5 { @@ -39,23 +39,23 @@ x-i18n: } ``` -3. Попросіть агента: _"Згенеруй 5-секундне кінематографічне відео з дружнім лобстером, який займається серфінгом на заході сонця."_ +3. Попросіть агента: _"Створи 5-секундне кінематографічне відео з дружнім лобстером, який катається на серфі на заході сонця."_ -Агент автоматично викликає `video_generate`. Додавати інструмент до списку дозволених не потрібно — він увімкнений типово, коли доступний провайдер. +Агент автоматично викликає `video_generate`. Жодного allow-list для інструмента не потрібно — його увімкнено за замовчуванням, коли доступний провайдер. ## Підтримувані провайдери -| Провайдер | Типова модель | Еталонні входи | API-ключ | -| --------- | ------------------------------ | ------------------- | ---------------------------------------------------------- | -| Alibaba | `wan2.6-t2v` | Так, віддалені URL | `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY`, `QWEN_API_KEY` | -| BytePlus | `seedance-1-0-lite-t2v-250428` | 1 зображення | `BYTEPLUS_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | 1 зображення | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview`| 1 зображення або 1 відео | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | 1 зображення | `MINIMAX_API_KEY` | -| OpenAI | `sora-2` | 1 зображення або 1 відео | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | Так, віддалені URL | `QWEN_API_KEY`, `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | 1 зображення | `TOGETHER_API_KEY` | -| xAI | `grok-imagine-video` | 1 зображення або 1 відео | `XAI_API_KEY` | +| Провайдер | Типова модель | Еталонні вхідні дані | API-ключ | +| --------- | ------------------------------ | -------------------- | ---------------------------------------------------------- | +| Alibaba | `wan2.6-t2v` | Так, віддалені URL | `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY`, `QWEN_API_KEY` | +| BytePlus | `seedance-1-0-lite-t2v-250428` | 1 зображення | `BYTEPLUS_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | 1 зображення | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | 1 зображення або 1 відео | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | 1 зображення | `MINIMAX_API_KEY` | +| OpenAI | `sora-2` | 1 зображення або 1 відео | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | Так, віддалені URL | `QWEN_API_KEY`, `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | 1 зображення | `TOGETHER_API_KEY` | +| xAI | `grok-imagine-video` | 1 зображення або 1 відео | `XAI_API_KEY` | Використовуйте `action: "list"`, щоб переглянути доступні провайдери та моделі під час виконання: @@ -67,20 +67,20 @@ x-i18n: | Параметр | Тип | Опис | | ---------------- | -------- | ------------------------------------------------------------------------------------- | -| `prompt` | string | Запит для генерації відео (обов’язковий для `action: "generate"`) | -| `action` | string | `"generate"` (типово) або `"list"` для перегляду провайдерів | -| `model` | string | Перевизначення провайдера/моделі, наприклад `qwen/wan2.6-t2v` | -| `image` | string | Шлях або URL одного еталонного зображення | -| `images` | string[] | Кілька еталонних зображень (до 5) | -| `video` | string | Шлях або URL одного еталонного відео | -| `videos` | string[] | Кілька еталонних відео (до 4) | -| `size` | string | Підказка щодо розміру, якщо провайдер це підтримує | +| `prompt` | string | Запит для генерації відео (обов’язковий для `action: "generate"`) | +| `action` | string | `"generate"` (типово) або `"list"` для перегляду провайдерів | +| `model` | string | Перевизначення провайдера/моделі, наприклад `qwen/wan2.6-t2v` | +| `image` | string | Шлях або URL одного еталонного зображення | +| `images` | string[] | Кілька еталонних зображень (до 5) | +| `video` | string | Шлях або URL одного еталонного відео | +| `videos` | string[] | Кілька еталонних відео (до 4) | +| `size` | string | Підказка щодо розміру, якщо провайдер це підтримує | | `aspectRatio` | string | Співвідношення сторін: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` | -| `resolution` | string | Підказка щодо роздільної здатності: `480P`, `720P` або `1080P` | -| `durationSeconds`| number | Цільова тривалість у секундах | -| `audio` | boolean | Увімкнути згенероване аудіо, якщо провайдер це підтримує | -| `watermark` | boolean | Увімкнути або вимкнути водяний знак провайдера, якщо це підтримується | -| `filename` | string | Підказка щодо імені вихідного файлу | +| `resolution` | string | Підказка щодо роздільної здатності: `480P`, `720P` або `1080P` | +| `durationSeconds`| number | Цільова тривалість у секундах | +| `audio` | boolean | Увімкнути згенероване аудіо, якщо провайдер це підтримує | +| `watermark` | boolean | Увімкнути або вимкнути водяні знаки провайдера, якщо це підтримується | +| `filename` | string | Підказка для імені вихідного файла | Не всі провайдери підтримують усі параметри. Інструмент перевіряє обмеження можливостей провайдера перед надсиланням запиту. @@ -103,40 +103,39 @@ x-i18n: ### Порядок вибору провайдера -Під час генерації відео OpenClaw пробує провайдери в такому порядку: +Під час генерації відео OpenClaw пробує провайдерів у такому порядку: -1. **Параметр `model`** із виклику інструмента (якщо агент його вказує) -2. **`videoGenerationModel.primary`** із конфігурації -3. **`videoGenerationModel.fallbacks`** по черзі -4. **Автовиявлення** — використовує лише типові значення провайдерів, підкріплені автентифікацією: +1. **Параметр `model`** з виклику інструмента (якщо агент його вказує) +2. **`videoGenerationModel.primary`** з конфігурації +3. **`videoGenerationModel.fallbacks`** по порядку +4. **Автовизначення** — використовує лише типові значення провайдерів, підкріплені автентифікацією: - спочатку поточний типовий провайдер - - потім решта зареєстрованих провайдерів генерації відео в порядку id провайдера + - решта зареєстрованих провайдерів генерації відео в порядку `provider-id` -Якщо провайдер завершується з помилкою, автоматично пробується наступний кандидат. Якщо помиляються всі, помилка міститиме деталі кожної спроби. +Якщо провайдер завершується з помилкою, автоматично пробується наступний кандидат. Якщо помиляються всі, помилка містить подробиці кожної спроби. ## Примітки щодо провайдерів -- Alibaba використовує асинхронний відеоендпоінт DashScope / Model Studio і наразі вимагає віддалені URL `http(s)` для еталонних ресурсів. -- Google використовує Gemini/Veo і підтримує один еталонний вхід зображення або відео. -- MiniMax, Together, BytePlus і fal наразі підтримують один еталонний вхід зображення. -- OpenAI використовує нативний відеоендпоінт і наразі типово використовує `sora-2`. -- Qwen підтримує еталонні зображення/відео, але вихідний відеоендпоінт DashScope наразі вимагає віддалені URL `http(s)` для цих еталонів. -- xAI використовує нативний відео-API xAI і підтримує сценарії text-to-video, image-to-video та віддалене редагування/розширення відео. +- Alibaba використовує асинхронний відеоендпойнт DashScope / Model Studio і наразі вимагає віддалені URL `http(s)` для еталонних ресурсів. +- Google використовує Gemini/Veo та підтримує одне еталонне зображення або одне еталонне відео. +- MiniMax, Together, BytePlus і fal наразі підтримують одне еталонне зображення. +- OpenAI використовує нативний відеоендпойнт і наразі за замовчуванням використовує `sora-2`. +- Qwen підтримує еталонні зображення/відео, але висхідний відеоендпойнт DashScope наразі вимагає віддалені URL `http(s)` для цих еталонів. +- xAI використовує нативний відео-API xAI та підтримує сценарії text-to-video, image-to-video і віддалене редагування/розширення відео. -## Еталонні входи Qwen +## Еталонні вхідні дані Qwen -Вбудований провайдер Qwen підтримує text-to-video, а також режими з еталонними зображеннями/відео, але вихідний відеоендпоінт DashScope наразі вимагає **віддалені URL `http(s)`** для еталонних входів. Локальні шляхи до файлів і завантажені буфери відхиляються одразу, а не ігноруються непомітно. +Вбудований провайдер Qwen підтримує text-to-video, а також режими з еталонними зображеннями/відео, але висхідний відеоендпойнт DashScope наразі вимагає **віддалені URL `http(s)`** для еталонних вхідних даних. Шляхи до локальних файлів і завантажені буфери відхиляються одразу, а не ігноруються безшумно. ## Пов’язане - [Огляд інструментів](/uk/tools) — усі доступні інструменти агента -- [Alibaba Model Studio](/providers/alibaba) — пряме налаштування провайдера Wan +- [Alibaba Model Studio](/uk/providers/alibaba) — безпосереднє налаштування провайдера Wan - [Google (Gemini)](/uk/providers/google) — налаштування провайдера Veo - [MiniMax](/uk/providers/minimax) — налаштування провайдера Hailuo - [OpenAI](/uk/providers/openai) — налаштування провайдера Sora - [Qwen](/uk/providers/qwen) — налаштування та обмеження, специфічні для Qwen -- [Qwen / Model Studio](/uk/providers/qwen_modelstudio) — деталі DashScope на рівні ендпоінтів -- [Together AI](/uk/providers/together) — налаштування провайдера Wan у Together -- [xAI](/uk/providers/xai) — налаштування відеопровайдера Grok -- [Довідник з конфігурації](/uk/gateway/configuration-reference#agent-defaults) — конфігурація `videoGenerationModel` -- [Моделі](/uk/concepts/models) — конфігурація моделей і перемикання при збоях +- [Together AI](/uk/providers/together) — налаштування провайдера Wan для Together +- [xAI](/uk/providers/xai) — налаштування провайдера відео Grok +- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) — конфігурація `videoGenerationModel` +- [Моделі](/uk/concepts/models) — конфігурація моделей і failover