diff --git a/docs/uk/plugins/architecture-internals.md b/docs/uk/plugins/architecture-internals.md
index 69377a78a..8fc61f709 100644
--- a/docs/uk/plugins/architecture-internals.md
+++ b/docs/uk/plugins/architecture-internals.md
@@ -1,142 +1,142 @@
---
read_when:
- - Реалізація хуків середовища виконання провайдера, життєвого циклу каналу або пакетних наборів
- - Налагодження порядку завантаження plugin або стану реєстру
- - Додавання нової можливості Plugin або plugin рушія контексту
-summary: 'Внутрішні аспекти архітектури Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці'
-title: Внутрішні аспекти архітектури Plugin
+ - Реалізація хуків середовища виконання провайдера, життєвого циклу каналу або пакетних збірок пакунків
+ - Налагодження порядку завантаження Plugin або стану реєстру
+ - Додавання нової можливості Plugin або Plugin рушія контексту
+summary: 'Внутрішні компоненти архітектури Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, маршрути HTTP та довідкові таблиці'
+title: Внутрішні компоненти архітектури Plugin
x-i18n:
- generated_at: "2026-04-25T18:41:27Z"
+ generated_at: "2026-04-25T19:49:11Z"
model: gpt-5.4
provider: openai
- source_hash: 074b0a0fb1678b73a2c9236fb9fbc208d8e39dcbba39c904b2bd7b5ceac473b6
+ source_hash: 2a653dfdf6c3f81872b72e246ea5e760da4ce8d643767c38663da18025e5842a
source_path: plugins/architecture-internals.md
workflow: 15
---
-Щоб дізнатися про публічну модель можливостей, форми plugin, а також контракти
-власності/виконання, див. [Plugin architecture](/uk/plugins/architecture). Ця сторінка є
+Для публічної моделі можливостей, форм Plugin і контрактів
+власності/виконання дивіться [Plugin architecture](/uk/plugins/architecture). Ця сторінка є
довідником щодо внутрішньої механіки: конвеєра завантаження, реєстру, хуків середовища виконання,
-HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем.
+маршрутів Gateway HTTP, шляхів імпорту та таблиць схем.
## Конвеєр завантаження
-Під час запуску OpenClaw приблизно виконує таке:
+Під час запуску OpenClaw приблизно робить таке:
-1. виявляє кореневі каталоги потенційних plugin
-2. зчитує маніфести нативних або сумісних збірок і метадані пакетів
+1. виявляє кандидатні корені Plugin
+2. зчитує маніфести нативних або сумісних збірок і метадані пакунків
3. відхиляє небезпечні кандидати
-4. нормалізує конфігурацію plugin (`plugins.enabled`, `allow`, `deny`, `entries`,
+4. нормалізує конфігурацію Plugin (`plugins.enabled`, `allow`, `deny`, `entries`,
`slots`, `load.paths`)
5. визначає, чи ввімкнено кожного кандидата
6. завантажує ввімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач;
- незібрані нативні plugin використовують jiti
-7. викликає нативні хуки `register(api)` і збирає реєстрації до реєстру plugin
-8. надає реєстр командам/поверхням середовища виконання
+ незібрані нативні Plugin використовують jiti
+7. викликає нативні хуки `register(api)` і збирає реєстрації до реєстру Plugin
+8. відкриває реєстр для команд/поверхонь середовища виконання
-`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані plugin використовують `register`; для нових plugin віддавайте перевагу `register`.
+`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що з них наявне (`def.register ?? def.activate`), і викликає його в тій самій точці. Усі вбудовані Plugin використовують `register`; для нових Plugin віддавайте перевагу `register`.
Перевірки безпеки відбуваються **до** виконання в середовищі виконання. Кандидати блокуються,
-коли точка входу виходить за межі кореня plugin, шлях має права на запис для всіх, або
-власність шляху виглядає підозріло для невбудованих plugin.
+коли точка входу виходить за межі кореня Plugin, шлях доступний для запису всім, або
+власність шляху виглядає підозрілою для невбудованих Plugin.
### Поведінка з пріоритетом маніфесту
-Маніфест є джерелом істини для контрольної площини. OpenClaw використовує його, щоб:
+Маніфест є джерелом істини для площини керування. OpenClaw використовує його, щоб:
-- ідентифікувати plugin
+- ідентифікувати Plugin
- виявляти оголошені канали/Skills/схему конфігурації або можливості збірки
-- перевіряти `plugins.entries..config`
-- доповнювати мітки/заповнювачі Control UI
+- валідувати `plugins.entries..config`
+- доповнювати мітки/заповнювачі в Control UI
- показувати метадані встановлення/каталогу
-- зберігати дешеві дескриптори активації та налаштування без завантаження середовища виконання plugin
+- зберігати дешеві дескриптори активації та налаштування без завантаження середовища виконання Plugin
-Для нативних plugin модуль середовища виконання є частиною площини даних. Він реєструє
+Для нативних Plugin модуль середовища виконання є частиною площини даних. Він реєструє
фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера.
-Необов’язкові блоки маніфесту `activation` і `setup` залишаються в контрольній площині.
-Це лише дескриптори метаданих для планування активації та виявлення налаштування;
+Необов’язкові блоки маніфесту `activation` і `setup` залишаються в площині керування.
+Це лише метадані-дескриптори для планування активації та виявлення налаштування;
вони не замінюють реєстрацію в середовищі виконання, `register(...)` або `setupEntry`.
Перші споживачі живої активації тепер використовують підказки маніфесту щодо команд, каналів і провайдерів,
-щоб звузити завантаження plugin до ширшої матеріалізації реєстру:
+щоб звузити завантаження Plugin до ширшої матеріалізації реєстру:
-- завантаження CLI звужується до plugin, яким належить запитана основна команда
-- налаштування каналу/визначення plugin звужується до plugin, яким належить запитаний
+- завантаження CLI звужується до Plugin, яким належить запитана основна команда
+- визначення налаштування/Plugin каналу звужується до Plugin, яким належить запитаний
id каналу
-- явне визначення налаштування/середовища виконання провайдера звужується до plugin, яким належить
+- явне визначення налаштування/середовища виконання провайдера звужується до Plugin, яким належить
запитаний id провайдера
Планувальник активації надає як API лише для id для наявних викликачів, так і
-API плану для нової діагностики. Записи плану повідомляють, чому було вибрано plugin,
+API плану для нової діагностики. Записи плану повідомляють, чому Plugin було вибрано,
відокремлюючи явні підказки планувальника `activation.*` від резервного
визначення власності через маніфест, такого як `providers`, `channels`, `commandAliases`, `setup.providers`,
`contracts.tools` і хуки. Це розділення причин є межею сумісності:
-наявні метадані plugin і далі працюють, тоді як новий код може виявляти широкі підказки
+наявні метадані Plugin продовжують працювати, тоді як новий код може виявляти широкі підказки
або резервну поведінку без зміни семантики завантаження в середовищі виконання.
-Виявлення налаштування тепер надає перевагу id, якими володіють дескриптори, як-от `setup.providers` і
-`setup.cliBackends`, щоб звузити кандидатів plugin, перш ніж переходити до
-`setup-api` для plugin, яким усе ще потрібні хуки середовища виконання на етапі налаштування. Потік
+Виявлення налаштування тепер надає перевагу id, що належать дескрипторам, таким як `setup.providers` і
+`setup.cliBackends`, щоб звузити кандидатні Plugin, перш ніж переходити до
+`setup-api` для Plugin, яким усе ще потрібні хуки середовища виконання на етапі налаштування. Потік
налаштування провайдера спочатку використовує маніфест `providerAuthChoices`, а потім
-для сумісності повертається до варіантів майстра середовища виконання та варіантів каталогу встановлення. Явне
-`setup.requiresRuntime: false` є межею лише для дескриптора; пропущений
-`requiresRuntime` зберігає застарілий резервний варіант `setup-api` для сумісності. Якщо більше
-ніж один виявлений plugin заявляє права на той самий нормалізований id провайдера налаштування або
-backend CLI, пошук налаштування відмовляється від неоднозначного власника замість покладання на
-порядок виявлення. Коли середовище виконання налаштування все ж виконується, діагностика реєстру повідомляє
-про розбіжності між `setup.providers` / `setup.cliBackends` і провайдерами або backend CLI,
-зареєстрованими через setup-api, не блокуючи застарілі plugin.
+переходить до виборів майстра середовища виконання та виборів каталогу встановлення для сумісності. Явне
+`setup.requiresRuntime: false` є лише дескрипторним порогом; якщо
+`requiresRuntime` пропущено, для сумісності зберігається застарілий резервний шлях через setup-api. Якщо більше ніж
+один виявлений Plugin заявляє той самий нормалізований id провайдера налаштування або CLI backend,
+пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на
+порядок виявлення. Коли середовище виконання налаштування все ж виконується, діагностика реєстру повідомляє про
+розходження між `setup.providers` / `setup.cliBackends` і провайдерами або CLI backends,
+зареєстрованими через setup-api, не блокуючи застарілі Plugin.
### Що кешує завантажувач
-OpenClaw зберігає короткочасні внутрішньопроцесні кеші для:
+OpenClaw підтримує короткі внутрішньопроцесні кеші для:
- результатів виявлення
- даних реєстру маніфестів
-- завантажених реєстрів plugin
+- завантажених реєстрів Plugin
-Ці кеші зменшують навантаження від пікового запуску та повторного виконання команд. Їх безпечно
-розглядати як короткоживучі кеші продуктивності, а не як постійне зберігання.
+Ці кеші зменшують пікове навантаження під час запуску та накладні витрати повторних команд. Їх безпечно
+сприймати як короткоживучі кеші продуктивності, а не як постійне збереження.
Примітка щодо продуктивності:
- Установіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або
`OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, щоб вимкнути ці кеші.
-- Налаштовуйте вікна кешу за допомогою `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і
+- Налаштовуйте вікна кешу через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і
`OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`.
## Модель реєстру
-Завантажені plugin не змінюють напряму довільні глобальні змінні ядра. Вони реєструються в
-центральному реєстрі plugin.
+Завантажені Plugin не змінюють безпосередньо довільні глобальні змінні ядра. Вони реєструються в
+центральному реєстрі Plugin.
Реєстр відстежує:
-- записи plugin (ідентичність, джерело, походження, стан, діагностика)
+- записи Plugin (ідентичність, джерело, походження, статус, діагностика)
- інструменти
- застарілі хуки та типізовані хуки
- канали
- провайдерів
- обробники Gateway RPC
-- HTTP-маршрути
-- реєстратори CLI
+- маршрути HTTP
+- CLI registrars
- фонові служби
-- команди, що належать plugin
+- команди, що належать Plugin
-Потім функції ядра читають з цього реєстру замість прямої взаємодії з модулями plugin.
-Це робить завантаження односпрямованим:
+Потім функції ядра читають із цього реєстру замість прямої взаємодії з модулями Plugin.
+Це зберігає односпрямованість завантаження:
-- модуль plugin -> реєстрація в реєстрі
+- модуль Plugin -> реєстрація в реєстрі
- середовище виконання ядра -> споживання реєстру
-Це розділення важливе для супроводу. Воно означає, що більшості поверхонь ядра потрібна лише
-одна точка інтеграції: «читати реєстр», а не «робити спеціальні випадки для кожного модуля plugin».
+Це розділення важливе для супровідності. Воно означає, що більшості поверхонь ядра потрібна
+лише одна точка інтеграції: «читати реєстр», а не «обробляти особливим чином кожен модуль Plugin».
## Зворотні виклики прив’язування розмови
-Plugin, які прив’язують розмову, можуть реагувати, коли затвердження вирішено.
+Plugin, які прив’язують розмову, можуть реагувати, коли підтвердження вирішено.
Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, як запит на прив’язування буде схвалено або відхилено:
@@ -146,12 +146,12 @@ export default {
register(api) {
api.onConversationBindingResolved(async (event) => {
if (event.status === "approved") {
- // A binding now exists for this plugin + conversation.
+ // Тепер для цього Plugin + розмови існує прив’язка.
console.log(event.binding?.conversationId);
return;
}
- // The request was denied; clear any local pending state.
+ // Запит було відхилено; очистіть будь-який локальний стан очікування.
console.log(event.request.conversation.conversationId);
});
},
@@ -162,111 +162,112 @@ export default {
- `status`: `"approved"` або `"denied"`
- `decision`: `"allow-once"`, `"allow-always"` або `"deny"`
-- `binding`: вирішене прив’язування для схвалених запитів
-- `request`: підсумок початкового запиту, підказка від’єднання, id відправника та
+- `binding`: розв’язана прив’язка для схвалених запитів
+- `request`: початкове резюме запиту, підказка від’єднання, id відправника та
метадані розмови
-Цей зворотний виклик призначений лише для сповіщення. Він не змінює, хто має право прив’язувати
-розмову, і виконується після завершення обробки схвалення ядром.
+Цей зворотний виклик призначений лише для сповіщення. Він не змінює того, кому дозволено прив’язувати
+розмову, і виконується після завершення обробки схвалення в ядрі.
## Хуки середовища виконання провайдера
-Plugin провайдерів мають три рівні:
+Plugin провайдерів мають три шари:
- **Метадані маніфесту** для дешевого пошуку до середовища виконання:
- `setup.providers[].envVars`, застарілий сумісний варіант `providerAuthEnvVars`,
+ `setup.providers[].envVars`, застарілий сумісний `providerAuthEnvVars`,
`providerAuthAliases`, `providerAuthChoices` і `channelEnvVars`.
-- **Хуки часу конфігурації**: `catalog` (застарілий `discovery`) плюс
+- **Хуки під час конфігурації**: `catalog` (застарілий `discovery`) плюс
`applyConfigDefaults`.
-- **Хуки середовища виконання**: понад 40 необов’язкових хуків для auth, визначення моделі,
- обгортання потоку, рівнів thinking, політики повтору та кінцевих точок використання. Див.
- повний список у [Порядок і використання хуків](#hook-order-and-usage).
+- **Хуки середовища виконання**: понад 40 необов’язкових хуків, що охоплюють
+ автентифікацію, визначення моделі, обгортання потоків, рівні мислення, політику повторного відтворення та кінцеві точки використання. Дивіться
+ повний список у розділі [Порядок і використання хуків](#hook-order-and-usage).
-OpenClaw і далі володіє загальним циклом агента, failover, обробкою транскрипту та
+OpenClaw, як і раніше, володіє загальним циклом агента, failover, обробкою транскриптів і
політикою інструментів. Ці хуки є поверхнею розширення для поведінки, специфічної для провайдера,
-без потреби у повністю власному транспорті inference.
+без потреби в цілому власному транспорті інференсу.
-Використовуйте маніфест `setup.providers[].envVars`, коли провайдер має облікові дані на основі env, які
-загальні шляхи auth/status/вибору моделі повинні бачити без завантаження середовища виконання plugin. Застарілий
-`providerAuthEnvVars` усе ще зчитується адаптером сумісності під час вікна
-депрецiації, і невбудовані plugin, які його використовують, отримують діагностику маніфесту. Використовуйте маніфест `providerAuthAliases`, коли один id провайдера має
-повторно використовувати env vars, auth-профілі, auth на основі конфігурації та варіант
-онбордингу API-ключа іншого id провайдера. Використовуйте маніфест
-`providerAuthChoices`, коли поверхні CLI для онбордингу/вибору auth повинні знати
-про id вибору провайдера, мітки груп і просте налаштування auth з одним прапорцем без
-завантаження середовища виконання провайдера. Залишайте в середовищі виконання провайдера
+Використовуйте маніфест `setup.providers[].envVars`, коли провайдер має облікові дані на основі env,
+які мають бути видимі для загальних шляхів автентифікації/статусу/вибору моделі без
+завантаження середовища виконання Plugin. Застарілий `providerAuthEnvVars` усе ще читається
+адаптером сумісності впродовж періоду застарівання, а невбудовані Plugin,
+які його використовують, отримують діагностику маніфесту. Використовуйте маніфест `providerAuthAliases`,
+коли один id провайдера має повторно використовувати env vars іншого id провайдера, профілі автентифікації,
+автентифікацію на основі конфігурації та вибір онбордингу API-ключа. Використовуйте маніфест
+`providerAuthChoices`, коли поверхні CLI для онбордингу/вибору автентифікації мають знати
+id вибору провайдера, мітки груп і просте підключення автентифікації одним прапорцем без
+завантаження середовища виконання провайдера. Зберігайте в середовищі виконання провайдера
`envVars` для підказок, орієнтованих на операторів, таких як мітки онбордингу або змінні налаштування
-ідентифікатора/секрета клієнта OAuth.
+OAuth client-id/client-secret.
-Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування, керовані env, які
-загальний резервний варіант shell-env, перевірки config/status або підказки налаштування повинні бачити
+Використовуйте маніфест `channelEnvVars`, коли канал має автентифікацію або налаштування на основі env, які
+мають бути видимі для загального резервного шляху shell-env, перевірок config/status або підказок налаштування
без завантаження середовища виконання каналу.
### Порядок і використання хуків
-Для plugin моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку.
-Стовпець «Коли використовувати» є коротким довідником для вибору.
+Для Plugin моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку.
+Стовпець «Коли використовувати» — це короткий посібник для вибору.
-| # | Хук | Що він робить | Коли використовувати |
+| # | Хук | Що він робить | Коли використовувати |
| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями `base URL` |
-| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму auth, env або семантики сімейства моделей провайдера |
-| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(це не хук plugin)_ |
-| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми `model-id` перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним визначенням моделі |
-| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для власних id провайдера в межах того самого сімейства транспорту |
-| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням конфігурації/провайдера в середовищі виконання | Провайдеру потрібне очищення конфігурації, яке має жити разом із plugin; вбудовані допоміжні засоби сімейства Google також страхують підтримувані записи конфігурації Google |
-| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування нативного використання потокової передачі до конфігурованих провайдерів | Провайдеру потрібні виправлення метаданих нативного використання потокової передачі, керовані кінцевою точкою |
-| 7 | `resolveConfigApiKey` | Визначає auth маркера env для конфігурованих провайдерів перед завантаженням auth у середовищі виконання | Провайдер має власне визначення API-ключа маркера env; `amazon-bedrock` також має тут вбудований AWS-визначник маркера env |
-| 8 | `resolveSyntheticAuth` | Відображає локальний/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних |
-| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth-профілі, що належать провайдеру; типове значення `persistence` — `runtime-only` для облікових даних, що належать CLI/застосунку | Провайдер повторно використовує зовнішні auth-облікові дані без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті |
-| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених заповнювачів синтетичного профілю відносно auth на основі env/конфігурації | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет |
-| 11 | `resolveDynamicModel` | Синхронний резервний варіант для model id, що належать провайдеру, але яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream id моделей |
-| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id |
-| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як вбудований виконавець використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра |
-| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для vendor-моделей за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспортах, не перебираючи на себе керування провайдером |
-| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру, і використовуються спільною логікою ядра | Провайдеру потрібні особливості транскрипту/сімейства провайдера |
-| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить вбудований виконавець | Провайдеру потрібне очищення схем для сімейства транспорту |
-| 17 | `inspectToolSchemas` | Відображає діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження про ключові слова без навчання ядра правилам, специфічним для провайдера |
-| 18 | `resolveReasoningOutputMode` | Вибирає нативний чи тегований контракт виводу reasoning | Провайдеру потрібен тегований reasoning/фінальний вивід замість нативних полів |
-| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера |
-| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдеру потрібен власний wire protocol, а не просто обгортка |
-| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності заголовків/тіла/моделі запиту без власного транспорту |
-| 22 | `resolveTransportTurnState` | Додає нативні заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали нативну для провайдера ідентичність ходу |
-| 23 | `resolveWebSocketSessionPolicy` | Додає нативні заголовки WebSocket або політику затримки session | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки session або політику резервного варіанта |
-| 24 | `formatApiKey` | Форматувач auth-профілю: збережений профіль стає рядком `apiKey` середовища виконання | Провайдер зберігає додаткові auth-метадані й потребує власної форми токена для середовища виконання |
-| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких кінцевих точок оновлення або політики збоїв оновлення | Провайдер не відповідає спільним механізмам оновлення `pi-ai` |
-| 26 | `buildAuthDoctorHint` | Підказка з виправлення, яка додається, коли оновлення OAuth завершується збоєм | Провайдеру потрібні власні рекомендації з виправлення auth після збою оновлення |
-| 27 | `matchesContextOverflowError` | Власний засіб зіставлення переповнення контекстного вікна для провайдера | Провайдер має сирі помилки переповнення, які загальні евристики не виявлять |
-| 28 | `classifyFailoverReason` | Власна класифікація причин failover для провайдера | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/перевантаженням тощо |
-| 29 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для проксі |
-| 30 | `buildMissingAuthMessage` | Заміна для загального повідомлення про відновлення у разі відсутнього auth | Провайдеру потрібна власна підказка відновлення у разі відсутнього auth |
-| 31 | `suppressBuiltInModel` | Пригнічення застарілої upstream-моделі плюс необов’язкова користувацька підказка про помилку | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх vendor-підказкою |
-| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, що додаються після виявлення | Провайдеру потрібні синтетичні рядки для прямої сумісності в майбутньому в `models list` і засобах вибору |
-| 33 | `resolveThinkingProfile` | Набір рівнів `/think`, мітки відображення та типове значення для конкретної моделі | Провайдер надає власну шкалу thinking або двійкову мітку для вибраних моделей |
-| 34 | `isBinaryThinking` | Хук сумісності для перемикача reasoning увімкнено/вимкнено | Провайдер надає лише двійковий режим thinking увімкнено/вимкнено |
-| 35 | `supportsXHighThinking` | Хук сумісності для підтримки reasoning `xhigh` | Провайдер хоче `xhigh` лише для підмножини моделей |
-| 36 | `resolveDefaultThinkingLevel` | Хук сумісності для типового рівня `/think` | Провайдер володіє типовою політикою `/think` для сімейства моделей |
-| 37 | `isModernModelRef` | Засіб зіставлення modern-model для фільтрів live-профілю та вибору smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke |
-| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед inference | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту |
-| 39 | `resolveUsageAuth` | Визначає облікові дані використання/білінгу для `/usage` і пов’язаних поверхонь стану | Провайдеру потрібен користувацький розбір токена використання/квоти або інші облікові дані використання |
-| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки використання/квоти, специфічні для провайдера, після визначення auth | Провайдеру потрібна кінцева точка використання або парсер корисного навантаження, специфічні для провайдера |
-| 41 | `createEmbeddingProvider` | Створює адаптер ембедингів, що належить провайдеру, для пам’яті/пошуку | Поведінка memory-ембедингів має належати plugin провайдера |
-| 42 | `buildReplayPolicy` | Повертає політику повтору, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна користувацька політика транскрипту (наприклад, вилучення блоків thinking) |
-| 43 | `sanitizeReplayHistory` | Переписує історію повтору після загального очищення транскрипту | Провайдеру потрібні переписування повтору, специфічні для провайдера, понад спільні допоміжні засоби Compaction |
-| 44 | `validateReplayTurns` | Остаточна перевірка або переформування ходів повтору перед вбудованим виконавцем | Транспорту провайдера потрібна суворіша перевірка ходів після загального очищення |
-| 45 | `onModelSelected` | Виконує побічні ефекти після вибору, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною |
+| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або значеннями `base URL` за замовчуванням |
+| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації за замовчуванням, що належать провайдеру, під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму автентифікації, env або семантики сімейства моделей провайдера |
+| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку намагається використати звичайний шлях через реєстр/каталог | _(це не хук Plugin)_ |
+| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми `model-id` перед пошуком | Провайдер володіє очищенням псевдонімів до канонічного визначення моделі |
+| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним складанням моделі | Провайдер володіє очищенням транспорту для власних id провайдерів у межах того самого сімейства транспорту |
+| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням середовища виконання/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із Plugin; вбудовані помічники сімейства Google також страхують підтримувані записи конфігурації Google |
+| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування нативного використання потокового режиму до провайдерів конфігурації | Провайдеру потрібні виправлення метаданих нативного використання потокового режиму, зумовлені кінцевими точками |
+| 7 | `resolveConfigApiKey` | Визначає автентифікацію через env-marker для провайдерів конфігурації до завантаження автентифікації середовища виконання | Провайдер має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований AWS-резолвер env-marker |
+| 8 | `resolveSyntheticAuth` | Показує локальну/self-hosted або конфігураційну автентифікацію без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних |
+| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, що належать провайдеру; типове значення `persistence` — `runtime-only` для облікових даних, що належать CLI/app | Провайдер повторно використовує зовнішні облікові дані автентифікації без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті |
+| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілю порівняно з автентифікацією через env/конфігурацію | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет |
+| 11 | `resolveDynamicModel` | Синхронний резервний шлях для id моделей провайдера, яких ще немає в локальному реєстрі | Провайдер приймає довільні id вищерівневих моделей |
+| 12 | `prepareDynamicModel` | Виконує асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id |
+| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як вбудований runner використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра |
+| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для моделей постачальника, які працюють через інший сумісний транспорт | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе роль провайдера |
+| 15 | `capabilities` | Метадані транскриптів/інструментів, що належать провайдеру й використовуються спільною логікою ядра | Провайдеру потрібні особливості сімейства транскриптів/провайдера |
+| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований runner | Провайдеру потрібне очищення схем для сімейства транспорту |
+| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження щодо ключових слів без навчання ядра правилам, специфічним для провайдера |
+| 18 | `resolveReasoningOutputMode` | Вибирає нативний контракт виводу міркування або контракт із тегами | Провайдеру потрібне міркування/фінальний вивід із тегами замість нативних полів |
+| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного провайдера |
+| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним транспортом | Провайдеру потрібен власний wire protocol, а не просто обгортка |
+| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності заголовків/тіла/model запиту без власного транспорту |
+| 22 | `resolveTransportTurnState` | Додає нативні заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали нативну для провайдера ідентичність ходу |
+| 23 | `resolveWebSocketSessionPolicy` | Додає нативні заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику резервного шляху |
+| 24 | `formatApiKey` | Форматер профілю автентифікації: збережений профіль перетворюється на рядок `apiKey` для середовища виконання | Провайдер зберігає додаткові метадані автентифікації і потребує власної форми токена для середовища виконання |
+| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для власних кінцевих точок оновлення або політики помилок оновлення | Провайдер не вписується в спільні механізми оновлення `pi-ai` |
+| 26 | `buildAuthDoctorHint` | Підказка виправлення, що додається, коли оновлення OAuth завершується помилкою | Провайдеру потрібні власні рекомендації з відновлення автентифікації після збою оновлення |
+| 27 | `matchesContextOverflowError` | Визначник переповнення контекстного вікна, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики можуть пропустити |
+| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/перевантаженням тощо |
+| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для proxy |
+| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення у разі відсутності автентифікації | Провайдеру потрібна специфічна для провайдера підказка з відновлення у разі відсутності автентифікації |
+| 31 | `suppressBuiltInModel` | Пригнічення застарілих вищерівневих моделей плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі вищерівневі рядки або замінити їх підказкою постачальника |
+| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Провайдеру потрібні синтетичні рядки прямої сумісності в `models list` і засобах вибору |
+| 33 | `resolveThinkingProfile` | Набір рівнів `/think`, мітки відображення та значення за замовчуванням для конкретної моделі | Провайдер надає власну шкалу thinking або двійкову мітку для вибраних моделей |
+| 34 | `isBinaryThinking` | Хук сумісності для двійкового перемикача міркування увімк./вимк. | Провайдер підтримує лише двійковий режим thinking увімк./вимк. |
+| 35 | `supportsXHighThinking` | Хук сумісності підтримки міркування `xhigh` | Провайдер хоче, щоб `xhigh` був доступний лише для підмножини моделей |
+| 36 | `resolveDefaultThinkingLevel` | Хук сумісності рівня `/think` за замовчуванням | Провайдер володіє політикою `/think` за замовчуванням для сімейства моделей |
+| 37 | `isModernModelRef` | Засіб зіставлення modern-model для фільтрів live-профілів і вибору smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke |
+| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ для середовища виконання безпосередньо перед інференсом | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту |
+| 39 | `resolveUsageAuth` | Визначає облікові дані використання/білінгу для `/usage` і пов’язаних поверхонь стану | Провайдеру потрібен власний розбір токена використання/квоти або інші облікові дані використання |
+| 40 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для провайдера знімки використання/квоти після визначення автентифікації | Провайдеру потрібна специфічна для провайдера кінцева точка використання або парсер корисного навантаження |
+| 41 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті має належати Plugin провайдера |
+| 42 | `buildReplayPolicy` | Повертає політику повторного відтворення, що керує обробкою транскрипту для провайдера | Провайдеру потрібна власна політика транскрипту (наприклад, видалення блоків thinking) |
+| 43 | `sanitizeReplayHistory` | Переписує історію повторного відтворення після загального очищення транскрипту | Провайдеру потрібні специфічні для провайдера переписування повторного відтворення понад спільні помічники Compaction |
+| 44 | `validateReplayTurns` | Остаточна валідація або переформування ходів повторного відтворення перед вбудованим runner | Транспорту провайдера потрібна суворіша валідація ходів після загальної санітизації |
+| 45 | `onModelSelected` | Виконує побічні ефекти після вибору, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною |
`normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють
-відповідний plugin провайдера, а потім переходять до інших plugin провайдерів, які підтримують хуки,
-доки один із них справді не змінить id моделі або транспорт/конфігурацію. Це дозволяє
-працювати shim-провайдерам для псевдонімів/сумісності без потреби, щоб викликач знав, який
-вбудований plugin володіє цим переписуванням. Якщо жоден хук провайдера не перепише підтримуваний
-запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google усе одно застосує
+відповідний Plugin провайдера, а потім переходять до інших Plugin провайдерів, які підтримують хуки,
+доки один із них справді не змінить id моделі або transport/config. Це зберігає
+працездатність shim-Plugin для псевдонімів/сумісності без вимоги, щоб викликач знав, який
+саме вбудований Plugin володіє цим переписуванням. Якщо жоден хук провайдера не переписує підтримуваний
+запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно застосовує
це очищення сумісності.
Якщо провайдеру потрібен повністю власний wire protocol або власний виконавець запитів,
-це інший клас розширення. Ці хуки призначені для поведінки провайдера, яка
-все ще працює в межах звичайного циклу inference OpenClaw.
+це інший клас розширення. Ці хуки призначені для поведінки провайдера,
+яка все ще працює в межах звичайного циклу інференсу OpenClaw.
### Приклад провайдера
@@ -324,45 +325,45 @@ api.registerProvider({
### Вбудовані приклади
-Вбудовані plugin провайдерів поєднують наведені вище хуки відповідно до потреб
-кожного постачальника щодо каталогу, auth, thinking, повтору та використання. Авторитетний набір хуків
-зберігається в кожному plugin у `extensions/`; ця сторінка ілюструє форми, а не
-дзеркально відтворює список.
+Вбудовані Plugin провайдерів поєднують наведені вище хуки відповідно до потреб
+кожного постачальника щодо каталогу, автентифікації, thinking, replay і usage. Авторитетний набір хуків міститься
+в кожному Plugin у `extensions/`; ця сторінка ілюструє форми, а не
+відтворює список.
-
+
OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` разом із
- `resolveDynamicModel` / `prepareDynamicModel`, щоб відображати upstream
+ `resolveDynamicModel` / `prepareDynamicModel`, щоб мати змогу показувати вищерівневі
id моделей раніше за статичний каталог OpenClaw.
-
+
GitHub Copilot, Gemini CLI, ChatGPT Codex, MiniMax, Xiaomi, z.ai поєднують
`prepareRuntimeAuth` або `formatApiKey` з `resolveUsageAuth` +
`fetchUsageSnapshot`, щоб керувати обміном токенів та інтеграцією `/usage`.
-
+
Спільні іменовані сімейства (`google-gemini`, `passthrough-gemini`,
- `anthropic-by-model`, `hybrid-anthropic-openai`) дозволяють провайдерам
- підключати політику транскрипту через `buildReplayPolicy` замість того, щоб
- кожен plugin наново реалізовував очищення.
+ `anthropic-by-model`, `hybrid-anthropic-openai`) дають провайдерам змогу
+ підключати політику транскриптів через `buildReplayPolicy` замість того, щоб кожен Plugin
+ повторно реалізовував очищення.
`byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`,
`qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і
- `volcengine` реєструють лише `catalog` і використовують спільний цикл inference.
+ `volcengine` реєструють лише `catalog` і використовують спільний цикл інференсу.
-
- Бета-заголовки, `/fast` / `serviceTier` і `context1m` знаходяться в
- публічному шві `api.ts` / `contract-api.ts` plugin Anthropic
+
+ Beta-заголовки, `/fast` / `serviceTier` і `context1m` містяться в
+ публічному шві `api.ts` / `contract-api.ts` Plugin Anthropic
(`wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
`resolveAnthropicFastMode`, `resolveAnthropicServiceTier`), а не в
- загальному SDK.
+ узагальненому SDK.
-## Допоміжні засоби середовища виконання
+## Помічники середовища виконання
-Plugin можуть отримувати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS:
+Plugin можуть отримувати доступ до вибраних помічників ядра через `api.runtime`. Для TTS:
```ts
const clip = await api.runtime.tts.textToSpeech({
@@ -383,14 +384,14 @@ const voices = await api.runtime.tts.listVoices({
Примітки:
-- `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових нотаток.
+- `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових повідомлень.
- Використовує конфігурацію ядра `messages.tts` і вибір провайдера.
-- Повертає PCM-буфер аудіо + частоту дискретизації. Plugin мають виконувати ресемплінг/кодування для провайдерів.
+- Повертає PCM-буфер аудіо + частоту дискретизації. Plugin повинні виконувати ресемплінг/кодування для провайдерів.
- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать постачальнику.
-- Списки голосів можуть містити багатші метадані, як-от локаль, стать і теги особистості для засобів вибору, обізнаних про провайдера.
-- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні.
+- Списки голосів можуть містити багатші метадані, такі як locale, gender і теги personality для засобів вибору, обізнаних про провайдера.
+- OpenAI і ElevenLabs сьогодні підтримують telephony. Microsoft — ні.
-Plugin також можуть реєструвати мовленнєвих провайдерів через `api.registerSpeechProvider(...)`.
+Plugin також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`.
```ts
api.registerSpeechProvider({
@@ -410,15 +411,15 @@ api.registerSpeechProvider({
Примітки:
-- Зберігайте політику TTS, резервний варіант і доставку відповіді в ядрі.
-- Використовуйте мовленнєвих провайдерів для поведінки синтезу, що належить постачальнику.
-- Застаріле значення `edge` для Microsoft нормалізується до id провайдера `microsoft`.
-- Бажана модель володіння орієнтована на компанію: один plugin постачальника може
- володіти текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами в міру того,
- як OpenClaw додає ці контракти можливостей.
+- Політика TTS, резервний шлях і доставка відповіді мають залишатися в ядрі.
+- Використовуйте провайдерів мовлення для поведінки синтезу, що належить постачальнику.
+- Застарілий вхід Microsoft `edge` нормалізується до id провайдера `microsoft`.
+- Бажана модель володіння є орієнтованою на компанію: один Plugin постачальника може володіти
+ текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами в міру того, як OpenClaw додає ці
+ контракти можливостей.
-Для розуміння зображень/аудіо/відео plugin реєструють одного типізованого
-провайдера розуміння медіа замість загального сховища ключ/значення:
+Для розуміння зображень/аудіо/відео Plugin реєструють одного типізованого
+провайдера media-understanding замість узагальненого сховища ключ/значення:
```ts
api.registerMediaUnderstandingProvider({
@@ -432,16 +433,16 @@ api.registerMediaUnderstandingProvider({
Примітки:
-- Зберігайте оркестрацію, резервний варіант, конфігурацію та зв’язування каналів у ядрі.
-- Зберігайте поведінку постачальника в plugin провайдера.
+- Оркестрація, резервний шлях, конфігурація та підключення каналів мають залишатися в ядрі.
+- Поведінка постачальника має залишатися в Plugin провайдера.
- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові
поля результату, нові необов’язкові можливості.
- Генерація відео вже дотримується тієї самої схеми:
- - ядро володіє контрактом можливості та допоміжним засобом середовища виконання
- - plugin постачальника реєструють `api.registerVideoGenerationProvider(...)`
- - feature/channel plugin споживають `api.runtime.videoGeneration.*`
+ - ядро володіє контрактом можливості та помічником середовища виконання
+ - Plugin постачальників реєструють `api.registerVideoGenerationProvider(...)`
+ - Plugin функцій/каналів використовують `api.runtime.videoGeneration.*`
-Для допоміжних засобів середовища виконання розуміння медіа plugin можуть викликати:
+Для помічників середовища виконання media-understanding Plugin можуть викликати:
```ts
const image = await api.runtime.mediaUnderstanding.describeImageFile({
@@ -456,14 +457,14 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({
});
```
-Для транскрибування аудіо plugin можуть використовувати або середовище виконання розуміння медіа,
+Для транскрибування аудіо Plugin можуть використовувати або середовище виконання media-understanding,
або старіший псевдонім STT:
```ts
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
filePath: "/tmp/inbound-audio.ogg",
cfg: api.config,
- // Optional when MIME cannot be inferred reliably:
+ // Необов’язково, коли MIME не вдається надійно визначити:
mime: "audio/ogg",
});
```
@@ -472,11 +473,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
- `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для
розуміння зображень/аудіо/відео.
-- Використовує конфігурацію аудіо розуміння медіа ядра (`tools.media.audio`) і порядок резервних провайдерів.
-- Повертає `{ text: undefined }`, коли вивід транскрибування не створюється (наприклад, для пропущеного/непідтримуваного вводу).
+- Використовує конфігурацію аудіо media-understanding ядра (`tools.media.audio`) і порядок резервного вибору провайдерів.
+- Повертає `{ text: undefined }`, коли вихід транскрибування не створено (наприклад, якщо введення пропущено/не підтримується).
- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом сумісності.
-Plugin також можуть запускати фонові виконання subagent через `api.runtime.subagent`:
+Plugin також можуть запускати фонові виконання субагентів через `api.runtime.subagent`:
```ts
const result = await api.runtime.subagent.run({
@@ -490,14 +491,14 @@ const result = await api.runtime.subagent.run({
Примітки:
-- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сеансу.
+- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії.
- OpenClaw враховує ці поля перевизначення лише для довірених викликачів.
-- Для резервних запусків, що належать plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`.
-- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugin конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль.
-- Запуски subagent від недовірених plugin усе ще працюють, але запити на перевизначення відхиляються замість тихого переходу до резервного варіанта.
+- Для резервних запусків, що належать Plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`.
+- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені Plugin конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі.
+- Запуски субагентів із недовірених Plugin усе ще працюють, але запити на перевизначення відхиляються замість тихого переходу до резервного варіанту.
-Для вебпошуку plugin можуть використовувати спільний допоміжний засіб середовища виконання замість
-доступу до зв’язування інструментів агента:
+Для вебпошуку Plugin можуть використовувати спільний помічник середовища виконання замість
+занурення в підключення інструментів агента:
```ts
const providers = api.runtime.webSearch.listProviders({
@@ -518,9 +519,9 @@ Plugin також можуть реєструвати провайдерів в
Примітки:
-- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запиту в ядрі.
-- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для постачальника.
-- `api.runtime.webSearch.*` — це бажана спільна поверхня для feature/channel plugin, яким потрібна поведінка пошуку без залежності від обгортки інструментів агента.
+- Вибір провайдера, визначення облікових даних і спільна семантика запитів мають залишатися в ядрі.
+- Використовуйте провайдерів вебпошуку для специфічних транспортів пошуку постачальника.
+- `api.runtime.webSearch.*` — це бажана спільна поверхня для Plugin функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструментів агента.
### `api.runtime.imageGeneration`
@@ -535,12 +536,12 @@ const providers = api.runtime.imageGeneration.listProviders({
});
```
-- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень.
+- `generate(...)`: генерує зображення, використовуючи налаштований ланцюжок провайдерів генерації зображень.
- `listProviders(...)`: перелічує доступних провайдерів генерації зображень та їхні можливості.
-## HTTP-маршрути Gateway
+## Маршрути Gateway HTTP
-Plugin можуть відкривати HTTP-ендпоїнти за допомогою `api.registerHttpRoute(...)`.
+Plugin можуть відкривати кінцеві точки HTTP за допомогою `api.registerHttpRoute(...)`.
```ts
api.registerHttpRoute({
@@ -558,198 +559,198 @@ api.registerHttpRoute({
Поля маршруту:
- `path`: шлях маршруту під HTTP-сервером gateway.
-- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайний auth gateway, або `"plugin"` для auth/webhook-перевірки, якими керує plugin.
+- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайну автентифікацію gateway, або `"plugin"` для автентифікації/перевірки Webhook, якою керує Plugin.
- `match`: необов’язкове поле. `"exact"` (типово) або `"prefix"`.
-- `replaceExisting`: необов’язкове поле. Дозволяє тому самому plugin замінити власну наявну реєстрацію маршруту.
+- `replaceExisting`: необов’язкове поле. Дозволяє тому самому Plugin замінити власну наявну реєстрацію маршруту.
- `handler`: повертайте `true`, коли маршрут обробив запит.
Примітки:
-- `api.registerHttpHandler(...)` було видалено, і воно спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`.
-- Маршрути plugin мають явно оголошувати `auth`.
-- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin.
+- `api.registerHttpHandler(...)` було вилучено, і воно спричинить помилку завантаження Plugin. Натомість використовуйте `api.registerHttpRoute(...)`.
+- Маршрути Plugin повинні явно оголошувати `auth`.
+- Конфлікти точного `path + match` відхиляються, якщо не задано `replaceExisting: true`, і один Plugin не може замінити маршрут іншого Plugin.
- Перекривні маршрути з різними рівнями `auth` відхиляються. Ланцюжки переходу `exact`/`prefix` мають бути лише в межах одного рівня auth.
-- Маршрути `auth: "plugin"` **не** отримують автоматично області runtime оператора. Вони призначені для webhook або перевірки підпису, якими керує plugin, а не для привілейованих допоміжних викликів Gateway.
-- Маршрути `auth: "gateway"` працюють у межах області runtime запиту Gateway, але ця область навмисно є консервативною:
- - bearer-auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області runtime маршрутів plugin зафіксованими на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes`
- - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` у приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній
- - якщо `x-openclaw-scopes` відсутній у таких запитах маршрутів plugin з ідентичністю, область runtime повертається до `operator.write`
-- Практичне правило: не припускайте, що маршрут plugin із gateway-auth є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth із ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`.
+- Маршрути `auth: "plugin"` **не** отримують автоматично runtime scopes оператора. Вони призначені для Webhook і перевірки підписів, якими керує Plugin, а не для привілейованих викликів допоміжних функцій Gateway.
+- Маршрути `auth: "gateway"` працюють у межах runtime scope запиту Gateway, але цей scope навмисно консервативний:
+ - bearer-автентифікація зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) фіксує runtime scopes маршрутів Plugin на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes`
+ - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes`, лише коли цей заголовок явно присутній
+ - якщо `x-openclaw-scopes` відсутній у таких запитах маршрутів Plugin з ідентичністю, runtime scope повертається до `operator.write`
+- Практичне правило: не вважайте маршрут Plugin з gateway-auth неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим автентифікації з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`.
## Шляхи імпорту Plugin SDK
Використовуйте вузькі підшляхи SDK замість монолітного кореневого
-barrel `openclaw/plugin-sdk` під час створення нових plugin. Основні підшляхи:
+barrel `openclaw/plugin-sdk` під час створення нових Plugin. Основні підшляхи:
-| Підшлях | Призначення |
-| ----------------------------------- | ------------------------------------------------------ |
-| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації plugin |
-| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/побудови каналу |
-| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella-контракт |
-| `openclaw/plugin-sdk/config-schema` | Коренева схема Zod для `openclaw.json` (`OpenClawSchema`) |
+| Підшлях | Призначення |
+| ---------------------------------- | -------------------------------------------------- |
+| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin |
+| `openclaw/plugin-sdk/channel-core` | Помічники входу/побудови каналу |
+| `openclaw/plugin-sdk/core` | Загальні спільні помічники та umbrella-контракт |
+| `openclaw/plugin-sdk/config-schema` | Коренева схема Zod `openclaw.json` (`OpenClawSchema`) |
-Plugin каналів вибирають із сімейства вузьких швів — `channel-setup`,
+Плагіни каналів обирають із сімейства вузьких швів — `channel-setup`,
`setup-runtime`, `setup-adapter-runtime`, `setup-tools`, `channel-pairing`,
`channel-contract`, `channel-feedback`, `channel-inbound`, `channel-lifecycle`,
`channel-reply-pipeline`, `command-auth`, `secret-input`, `webhook-ingress`,
-`channel-targets` і `channel-actions`. Поведінка затвердження має консолідуватися
-в одному контракті `approvalCapability`, а не змішуватися між не пов’язаними
-полями plugin. Див. [Channel plugins](/uk/plugins/sdk-channel-plugins).
+`channel-targets` і `channel-actions`. Поведінку підтвердження слід зводити
+до одного контракту `approvalCapability`, а не змішувати між не пов’язаними
+полями Plugin. Див. [Channel plugins](/uk/plugins/sdk-channel-plugins).
-Допоміжні засоби середовища виконання та конфігурації розміщені під відповідними підшляхами `*-runtime`
-(`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`,
+Помічники середовища виконання та конфігурації розміщуються у відповідних підшляхах
+`*-runtime` (`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`,
`lazy-runtime`, `directory-runtime`, `text-runtime`, `runtime-store` тощо).
`openclaw/plugin-sdk/channel-runtime` є застарілим — це shim сумісності для
-старіших plugin. Новий код має імпортувати вужчі загальні примітиви.
+старіших Plugin. Новий код має імпортувати вужчі узагальнені примітиви.
-Внутрішні точки входу репозиторію (для кореня пакета кожного вбудованого plugin):
+Внутрішні для репозиторію точки входу (для кореня кожного пакунка вбудованого Plugin):
-- `index.js` — точка входу вбудованого plugin
-- `api.js` — barrel допоміжних засобів/типів
+- `index.js` — точка входу вбудованого Plugin
+- `api.js` — barrel помічників/типів
- `runtime-api.js` — barrel лише для середовища виконання
-- `setup-entry.js` — точка входу plugin налаштування
+- `setup-entry.js` — точка входу Plugin налаштування
-Зовнішні plugin мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи
-не імпортуйте `src/*` іншого пакета plugin з ядра або з іншого plugin.
-Точки входу, завантажені через фасад, надають перевагу активному знімку конфігурації середовища виконання, якщо він
-існує, а потім повертаються до визначеного файлу конфігурації на диску.
+Зовнішні Plugin повинні імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи
+не імпортуйте `src/*` іншого пакунка Plugin з ядра або з іншого Plugin.
+Точки входу, завантажені через facade, надають перевагу активному знімку конфігурації середовища виконання, якщо він
+існує, а потім переходять до визначеного файлу конфігурації на диску.
-Підшляхи для конкретних можливостей, такі як `image-generation`, `media-understanding`
-і `speech`, існують, бо вбудовані plugin використовують їх уже сьогодні. Вони не є
-автоматично довгостроково замороженими зовнішніми контрактами — перевіряйте відповідну
+Специфічні для можливостей підшляхи, такі як `image-generation`, `media-understanding`,
+і `speech`, існують, оскільки вбудовані Plugin використовують їх уже сьогодні. Вони не є
+автоматично довгостроково зафіксованими зовнішніми контрактами — перевіряйте відповідну
довідкову сторінку SDK, коли покладаєтеся на них.
## Схеми інструментів повідомлень
-Plugin мають володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу,
-для немеседжевих примітивів, таких як реакції, прочитання та опитування.
-Спільне представлення надсилання має використовувати загальний контракт `MessagePresentation`,
-а не нативні для провайдера поля кнопок, компонентів, блоків або карток.
-Див. [Message Presentation](/uk/plugins/message-presentation), щоб ознайомитися з контрактом,
-правилами резервного варіанта, зіставленням провайдерів і контрольним списком автора plugin.
+Plugin мають володіти внесками в схему `describeMessageTool(...)`, специфічними для каналу,
+для примітивів, що не є повідомленнями, таких як реакції, прочитання та опитування.
+Спільне представлення надсилання має використовувати узагальнений контракт `MessagePresentation`
+замість нативних для провайдера полів button, component, block або card.
+Див. [Message Presentation](/uk/plugins/message-presentation) щодо контракту,
+правил резервного шляху, зіставлення провайдерів і контрольного списку для авторів Plugin.
Plugin, здатні до надсилання, оголошують, що вони можуть відтворювати, через можливості повідомлень:
-- `presentation` для блоків семантичного представлення (`text`, `context`, `divider`, `buttons`, `select`)
-- `delivery-pin` для запитів закріпленої доставки
+- `presentation` для семантичних блоків представлення (`text`, `context`, `divider`, `buttons`, `select`)
+- `delivery-pin` для запитів на закріплену доставку
Ядро вирішує, чи відтворювати представлення нативно, чи деградувати його до тексту.
-Не відкривайте нативні для провайдера обхідні шляхи UI із загального інструмента повідомлень.
-Застарілі допоміжні засоби SDK для застарілих нативних схем залишаються експортованими для наявних
-сторонніх plugin, але нові plugin не повинні їх використовувати.
+Не відкривайте нативні для провайдера лазівки UI з узагальненого інструмента повідомлень.
+Застарілі помічники SDK для старих нативних схем залишаються експортованими для наявних
+сторонніх Plugin, але нові Plugin не повинні їх використовувати.
## Визначення цілі каналу
-Plugin каналів мають володіти семантикою цілі, специфічною для каналу. Зберігайте спільний
-хост вихідних повідомлень загальним і використовуйте поверхню адаптера обміну повідомленнями для правил провайдера:
+Plugin каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний
+хост вихідних повідомлень узагальненим і використовуйте поверхню адаптера повідомлень для правил провайдера:
-- `messaging.inferTargetChatType({ to })` визначає, чи слід нормалізовану ціль
- трактувати як `direct`, `group` або `channel` перед пошуком у каталозі.
+- `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль
+ слід трактувати як `direct`, `group` або `channel` до пошуку в директорії.
- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи
- слід вводу одразу перейти до визначення, подібного до id, замість пошуку в каталозі.
-- `messaging.targetResolver.resolveTarget(...)` є резервним варіантом plugin, коли
- ядру потрібно остаточне визначення, що належить провайдеру, після нормалізації або
- після промаху в каталозі.
-- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, специфічною для провайдера,
- після того як ціль визначено.
+ слід введення одразу спрямувати до визначення, подібного до id, замість пошуку в директорії.
+- `messaging.targetResolver.resolveTarget(...)` — це резервний шлях Plugin, коли
+ ядру потрібне остаточне визначення, що належить провайдеру, після нормалізації або після
+ пропуску в директорії.
+- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії,
+ специфічною для провайдера, щойно ціль визначено.
-Рекомендований розподіл:
+Рекомендований поділ:
-- Використовуйте `inferTargetChatType` для рішень щодо категорії, які мають відбуватися до
- пошуку серед контактів/груп.
-- Використовуйте `looksLikeId` для перевірок «трактувати це як явний/нативний id цілі».
-- Використовуйте `resolveTarget` для резервного варіанта нормалізації, специфічного для провайдера, а не для
- широкого пошуку в каталозі.
-- Зберігайте нативні для провайдера id, такі як id чату, id потоку, JID, handle і id кімнати,
- усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK.
+- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають відбуватися до
+ пошуку peers/groups.
+- Використовуйте `looksLikeId` для перевірок «розглядати це як явний/нативний id цілі».
+- Використовуйте `resolveTarget` для резервної нормалізації, специфічної для провайдера, а не для
+ широкого пошуку в директорії.
+- Зберігайте нативні для провайдера id, такі як chat ids, thread ids, JIDs, handles і room
+ ids, усередині значень `target` або параметрів, специфічних для провайдера, а не в узагальнених полях SDK.
-## Каталоги на основі конфігурації
+## Директорії на основі конфігурації
-Plugin, які виводять записи каталогу з конфігурації, мають зберігати цю логіку в
-plugin і повторно використовувати спільні допоміжні засоби з
+Plugin, які виводять записи директорії з конфігурації, мають зберігати цю логіку в
+Plugin і повторно використовувати спільні помічники з
`openclaw/plugin-sdk/directory-runtime`.
-Використовуйте це, коли каналу потрібні контакти/групи на основі конфігурації, такі як:
+Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, наприклад:
-- контакти DM на основі allowlist
-- налаштовані відповідності каналів/груп
-- статичні резервні варіанти каталогу в межах облікового запису
+- DM peers, керовані allowlist
+- налаштовані карти channel/group
+- статичні резервні директорії в межах облікового запису
-Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції:
+Спільні помічники в `directory-runtime` обробляють лише узагальнені операції:
-- фільтрація запиту
-- застосування ліміту
-- усунення дублікатів/допоміжні засоби нормалізації
-- побудова `ChannelDirectoryEntry[]`
+- фільтрування запитів
+- застосування обмежень
+- помічники для усунення дублікатів/нормалізації
+- побудову `ChannelDirectoryEntry[]`
Перевірка облікового запису та нормалізація id, специфічні для каналу, мають залишатися в
-реалізації plugin.
+реалізації Plugin.
## Каталоги провайдерів
-Plugin провайдерів можуть визначати каталоги моделей для inference за допомогою
+Plugin провайдерів можуть визначати каталоги моделей для інференсу за допомогою
`registerProvider({ catalog: { run(...) { ... } } })`.
`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в
`models.providers`:
- `{ provider }` для одного запису провайдера
-- `{ providers }` для кількох записів провайдера
+- `{ providers }` для кількох записів провайдерів
-Використовуйте `catalog`, коли plugin володіє model id, типовими значеннями base URL
-або метаданими моделей, захищеними auth, специфічними для провайдера.
+Використовуйте `catalog`, коли Plugin володіє id моделей, специфічними для провайдера, значеннями `base URL`
+за замовчуванням або метаданими моделей, захищеними автентифікацією.
-`catalog.order` керує тим, коли каталог plugin зливається відносно вбудованих
+`catalog.order` керує тим, коли каталог Plugin зливається відносно вбудованих
неявних провайдерів OpenClaw:
-- `simple`: звичайні провайдери з API-ключем або на основі env
-- `profile`: провайдери, які з’являються, коли існують auth-профілі
-- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдера
+- `simple`: звичайні провайдери на основі API-ключа або env
+- `profile`: провайдери, які з’являються, коли існують профілі автентифікації
+- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів
- `late`: останній прохід, після інших неявних провайдерів
-Пізніші провайдери перемагають у разі конфлікту ключів, тож plugin можуть навмисно
-перевизначати вбудований запис провайдера з тим самим id провайдера.
+Пізніші провайдери перемагають у разі конфлікту ключів, тому Plugin можуть навмисно перевизначати
+вбудований запис провайдера з тим самим id провайдера.
Сумісність:
- `discovery` усе ще працює як застарілий псевдонім
- якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog`
-## Інспектування каналу лише для читання
+## Канал лише для читання: перевірка стану
-Якщо ваш plugin реєструє канал, віддавайте перевагу реалізації
-`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`.
+Якщо ваш Plugin реєструє канал, надавайте перевагу реалізації
+`plugin.config.inspectAccount(cfg, accountId)` поруч із `resolveAccount(...)`.
Чому:
- `resolveAccount(...)` — це шлях середовища виконання. Він може припускати, що облікові дані
- повністю матеріалізовані, і може швидко завершуватися з помилкою, коли потрібних секретів бракує.
-- Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`,
+ повністю матеріалізовані, і може швидко завершуватися з помилкою, коли потрібні секрети відсутні.
+- Командні шляхи лише для читання, такі як `openclaw status`, `openclaw status --all`,
`openclaw channels status`, `openclaw channels resolve` і потоки doctor/config
- repair, не повинні потребувати матеріалізації облікових даних середовища виконання лише для
- опису конфігурації.
+ repair, не повинні потребувати матеріалізації облікових даних середовища виконання лише для того,
+ щоб описати конфігурацію.
Рекомендована поведінка `inspectAccount(...)`:
-- Повертає лише описовий стан облікового запису.
-- Зберігає `enabled` і `configured`.
-- За потреби включає поля джерела/стану облікових даних, наприклад:
+- Повертайте лише описовий стан облікового запису.
+- Зберігайте `enabled` і `configured`.
+- Додавайте поля джерела/стану облікових даних, коли це доречно, наприклад:
- `tokenSource`, `tokenStatus`
- `botTokenSource`, `botTokenStatus`
- `appTokenSource`, `appTokenStatus`
- `signingSecretSource`, `signingSecretStatus`
-- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі лише читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела) для команд типу status.
+- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі лише читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела).
- Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але
- вони недоступні в поточному шляху команди.
+ недоступно в поточному шляху команди.
-Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано.
+Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або помилкового повідомлення, що обліковий запис не налаштовано.
-## Пакетні набори
+## Пакетні збірки пакунків
-Каталог plugin може містити `package.json` з `openclaw.extensions`:
+Каталог Plugin може містити `package.json` з `openclaw.extensions`:
```json
{
@@ -761,64 +762,66 @@ Plugin провайдерів можуть визначати каталоги
}
```
-Кожен запис стає plugin. Якщо пакет перелічує кілька extensions, id plugin
+Кожна точка входу стає Plugin. Якщо збірка перелічує кілька extensions, id Plugin
стає `name/`.
-Якщо ваш plugin імпортує npm-залежності, установіть їх у цьому каталозі, щоб
+Якщо ваш Plugin імпортує npm-залежності, установіть їх у цьому каталозі, щоб
`node_modules` був доступний (`npm install` / `pnpm install`).
-Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу plugin
-після визначення симлінків. Записи, які виходять за межі каталогу пакета,
+Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу Plugin
+після визначення symlink. Записи, що виходять за межі каталогу пакунка,
відхиляються.
-Примітка щодо безпеки: `openclaw plugins install` установлює залежності plugin через
-`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей у середовищі виконання). Підтримуйте дерева залежностей plugin
-«чистими JS/TS» і уникайте пакетів, які потребують збирання через `postinstall`.
+Примітка щодо безпеки: `openclaw plugins install` установлює залежності Plugin за допомогою
+`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev dependencies у середовищі виконання). Підтримуйте дерева залежностей Plugin
+«чистими JS/TS» і уникайте пакунків, які потребують збірок `postinstall`.
Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування.
-Коли OpenClaw потребує поверхонь налаштування для вимкненого plugin каналу або
-коли plugin каналу ввімкнено, але ще не налаштовано, він завантажує `setupEntry`
-замість повної точки входу plugin. Це робить запуск і налаштування легшими,
-коли основна точка входу plugin також підключає інструменти, хуки або інший код
-лише для середовища виконання.
+Коли OpenClaw потребує поверхонь налаштування для вимкненого Plugin каналу, або
+коли Plugin каналу ввімкнено, але ще не налаштовано, він завантажує `setupEntry`
+замість повної точки входу Plugin. Це робить запуск і налаштування легшими,
+коли ваша основна точка входу Plugin також підключає інструменти, хуки або інший код,
+призначений лише для середовища виконання.
Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`
-може підключити plugin каналу до того самого шляху `setupEntry` під час
-передслухової фази запуску gateway, навіть якщо канал уже налаштовано.
+може перевести Plugin каналу на той самий шлях `setupEntry` під час фази
+запуску gateway до початку прослуховування, навіть якщо канал уже налаштовано.
Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати
-до того, як gateway почне слухати. На практиці це означає, що точка входу налаштування
-має реєструвати кожну можливість, що належить каналу, від якої залежить запуск, зокрема:
+до того, як gateway почне прослуховування. На практиці це означає, що точка входу налаштування
+має реєструвати кожну можливість, що належить каналу, від якої залежить запуск, наприклад:
- саму реєстрацію каналу
-- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне слухати
+- будь-які маршрути HTTP, які мають бути доступні до того, як gateway почне прослуховування
- будь-які методи gateway, інструменти або служби, які мають існувати в той самий проміжок часу
-Якщо ваша повна точка входу все ще володіє будь-якою необхідною можливістю запуску, не вмикайте
-цей прапорець. Залишайте plugin у типовій поведінці й дозвольте OpenClaw завантажити
+Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте
+цей прапорець. Залиште Plugin на типовій поведінці й дозвольте OpenClaw завантажити
повну точку входу під час запуску.
-Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, які ядро
-може консультувати до завантаження повного середовища виконання каналу. Поточна поверхня
-просування налаштування така:
+Вбудовані канали також можуть публікувати помічники поверхні контракту лише для налаштування, які ядро
+може використовувати до завантаження повного середовища виконання каналу. Поточна
+поверхня просування налаштування така:
- `singleAccountKeysToMove`
- `namedAccountPromotionKeys`
- `resolveSingleAccountPromotionTarget(...)`
-Ядро використовує цю поверхню, коли потрібно просунути застарілу конфігурацію
-каналу з одним обліковим записом до `channels..accounts.*` без завантаження повної точки входу plugin.
-Matrix є поточним вбудованим прикладом: він переносить лише ключі auth/bootstrap до
+Ядро використовує цю поверхню, коли потрібно просунути застарілу конфігурацію каналу з одним обліковим записом
+до `channels..accounts.*` без завантаження повної точки входу Plugin.
+Matrix — поточний вбудований приклад: він переміщує лише ключі auth/bootstrap до
іменованого просунутого облікового запису, коли іменовані облікові записи вже існують, і може
-зберегти налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати
+зберегти налаштований неканонічний ключ default-account замість того, щоб завжди створювати
`accounts.default`.
-Ці адаптери патчів налаштування зберігають ледаче виявлення поверхні контракту вбудованих каналів. Час імпорту залишається легким; поверхня просування завантажується лише під час першого використання замість повторного входу у запуск вбудованого каналу під час імпорту модуля.
+Ці адаптери патчів налаштування зберігають ліниве виявлення поверхні контракту вбудованих пакетів. Час імпорту
+залишається легким; поверхня просування завантажується лише під час першого використання, а не
+повторно входить у запуск вбудованого каналу під час імпорту модуля.
-Коли ці поверхні запуску містять методи Gateway RPC, зберігайте їх на
-префіксі, специфічному для plugin. Простори імен адміністратора ядра (`config.*`,
+Коли ці поверхні запуску включають методи Gateway RPC, зберігайте їх на
+специфічному для Plugin префіксі. Простори імен адміністратора ядра (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються
-як `operator.admin`, навіть якщо plugin запитує вужчу область.
+як `operator.admin`, навіть якщо Plugin запитує вужчу область.
Приклад:
@@ -835,10 +838,10 @@ Matrix є поточним вбудованим прикладом: він пе
}
```
-### Метадані каталогу каналів
+### Метадані каталогу каналу
-Plugin каналів можуть рекламувати метадані налаштування/виявлення через `openclaw.channel` і
-підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити даних каталогу.
+Plugin каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і
+підказки встановлення через `openclaw.install`. Це дає змогу ядру не містити жорстко закодованих даних каталогу.
Приклад:
@@ -853,7 +856,7 @@ Plugin каналів можуть рекламувати метадані на
"selectionLabel": "Nextcloud Talk (self-hosted)",
"docsPath": "/channels/nextcloud-talk",
"docsLabel": "nextcloud-talk",
- "blurb": "Self-hosted чат через webhook-ботів Nextcloud Talk.",
+ "blurb": "Самостійно розміщений чат через webhook-ботів Nextcloud Talk.",
"order": 65,
"aliases": ["nc-talk", "nc"]
},
@@ -866,68 +869,70 @@ Plugin каналів можуть рекламувати метадані на
}
```
-Корисні поля `openclaw.channel`, окрім мінімального прикладу:
+Корисні поля `openclaw.channel` поза мінімальним прикладом:
-- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/стану
+- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу
- `docsLabel`: перевизначає текст посилання для посилання на документацію
-- `preferOver`: id plugin/каналу з нижчим пріоритетом, які цей запис каталогу має перевершувати
-- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору
-- `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо форматування вихідних повідомлень
-- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false`
+- `preferOver`: id Plugin/каналу з нижчим пріоритетом, які цей запис каталогу має випереджати
+- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування копією для поверхонь вибору
+- `markdownCapable`: позначає канал як здатний до markdown для рішень щодо форматування вихідних повідомлень
+- `exposure.configured`: приховує канал із поверхонь списків налаштованих каналів, якщо встановлено `false`
- `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено `false`
- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації
-- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure`
-- `quickstartAllowFrom`: підключає канал до стандартного потоку quickstart `allowFrom`
+- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure`
+- `quickstartAllowFrom`: додає канал до стандартного потоку quickstart `allowFrom`
- `forceAccountBinding`: вимагає явного прив’язування облікового запису, навіть якщо існує лише один обліковий запис
-- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення цілей announce
+- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення announce targets
OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт
-реєстру MPM). Помістіть JSON-файл в один із таких шляхів:
+реєстру MPM). Помістіть файл JSON в одне з таких місць:
- `~/.openclaw/mpm/plugins.json`
- `~/.openclaw/mpm/catalog.json`
- `~/.openclaw/plugins/catalog.json`
Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на
-один чи кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл має
+один чи кілька файлів JSON (розділених комою/крапкою з комою/`PATH`). Кожен файл має
містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`.
-Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів містять
-нормалізовані факти джерела встановлення поруч із сирим блоком `openclaw.install`. Ці
-нормалізовані факти вказують, чи є специфікація npm точною версією чи плаваючим
+Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів відкривають
+нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Ці
+нормалізовані факти визначають, чи є npm spec точною версією чи плаваючим
селектором, чи присутні очікувані метадані цілісності, і чи також доступний
-локальний шлях джерела. Коли відома ідентичність каталогу/пакета, нормалізовані
-факти попереджають, якщо розібране ім’я пакета npm відхиляється від цієї ідентичності.
+локальний шлях джерела. Коли відома ідентичність каталогу/пакунка, нормалізовані
+факти попереджають, якщо розібране ім’я npm-пакунка відхиляється від цієї ідентичності.
Вони також попереджають, коли `defaultChoice` є недійсним або вказує на джерело, яке
-недоступне, а також коли метадані цілісності npm присутні без дійсного джерела
-npm. Споживачі мають розглядати `installSource` як адитивне необов’язкове поле, щоб
-старі записи, зібрані вручну, і shim сумісності не мусили його синтезувати.
+недоступне, і коли метадані цілісності npm присутні без дійсного джерела npm.
+Споживачі мають розглядати `installSource` як адитивне необов’язкове поле, щоб
+старі записи, створені вручну, і shim сумісності не мусили синтезувати його.
Це дає змогу онбордингу та діагностиці пояснювати стан площини джерел без
-імпортування середовища виконання plugin.
+імпортування середовища виконання Plugin.
-Офіційні зовнішні записи npm мають надавати перевагу точному `npmSpec` разом із
-`expectedIntegrity`. Голі імена пакетів і dist-tag усе ще працюють для
-сумісності, але вони породжують попередження площини джерел, щоб каталог міг
-рухатися до закріплених інсталяцій із перевіркою цілісності без порушення роботи
-наявних plugin. Коли онбординг виконує встановлення з локального шляху каталогу, він записує керований
-запис реєстру встановлення plugin з `source: "path"` і
-`sourcePath`, відносним до робочого простору, коли це можливо. Абсолютний робочий шлях завантаження залишається в
-`plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів
-робочої станції в довготривалій конфігурації. Це зберігає видимість локальних інсталяцій для розробки для
-діагностики площини джерел без додавання другої сирої поверхні розкриття
-шляху файлової системи. Застарілі записи конфігурації `plugins.installs` усе ще читаються як
-резервний варіант сумісності, тоді як керований станом реєстр `plugins/installs.json`
+Офіційні зовнішні npm-записи мають надавати перевагу точному `npmSpec` разом із
+`expectedIntegrity`. Голі назви пакунків і dist-tags усе ще працюють для
+сумісності, але вони створюють попередження площини джерел, щоб каталог міг рухатися
+до закріплених установлень із перевіркою цілісності без порушення роботи наявних Plugin.
+Коли онбординг установлює з локального шляху каталогу, він записує запис журналу
+керованого встановлення Plugin із `source: "path"` і `sourcePath`, відносним до workspace,
+коли це можливо. Абсолютний робочий шлях завантаження залишається в
+`plugins.load.paths`; запис установлення уникає дублювання локальних робочих
+шляхів у довготривалій конфігурації. Це зберігає видимість локальних установлень для розробки в
+діагностиці площини джерел без додавання другої сирої поверхні розкриття шляхів файлової системи.
+Застарілі записи конфігурації `plugins.installs` усе ще зчитуються як
+резервний шлях сумісності, поки керований станом журнал `plugins/installs.json`
стає джерелом істини для встановлень.
+`openclaw doctor --fix` переносить ці застарілі записи конфігурації до керованого
+журналу та оновлює холодний індекс реєстру без завантаження модулів середовища виконання Plugin.
## Plugin рушія контексту
-Plugin рушія контексту володіють оркестрацією контексту сесії для приймання, збирання
-та Compaction. Реєструйте їх зі свого plugin за допомогою
+Plugin рушія контексту володіють оркестрацією контексту сесії для поглинання, збирання
+та Compaction. Реєструйте їх зі свого Plugin за допомогою
`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через
`plugins.slots.contextEngine`.
-Використовуйте це, коли ваш plugin має замінити або розширити типовий конвеєр
-контексту, а не просто додати пошук у пам’яті чи хуки.
+Використовуйте це, коли вашому Plugin потрібно замінити або розширити типовий
+конвеєр контексту, а не просто додати пошук у пам’яті або хуки.
```ts
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
@@ -955,7 +960,7 @@ export default function (api) {
}
```
-Якщо ваш рушій **не** володіє алгоритмом Compaction, залишайте `compact()`
+Якщо ваш рушій **не** володіє алгоритмом Compaction, залиште `compact()`
реалізованим і явно делегуйте його:
```ts
@@ -993,28 +998,28 @@ export default function (api) {
## Додавання нової можливості
-Коли plugin потрібна поведінка, яка не вписується в поточний API, не обходьте
-систему plugin через приватне проникнення всередину. Додайте відсутню можливість.
+Коли Plugin потребує поведінки, яка не вписується в поточний API, не обходьте
+систему Plugin через приватне внутрішнє звернення. Додайте відсутню можливість.
Рекомендована послідовність:
1. визначте контракт ядра
- Вирішіть, якою спільною поведінкою має володіти ядро: політикою, резервним варіантом, злиттям конфігурації,
- життєвим циклом, семантикою для каналів і формою допоміжного засобу середовища виконання.
-2. додайте типізовані поверхні реєстрації plugin/середовища виконання
+ Вирішіть, якою спільною поведінкою має володіти ядро: політикою, резервним шляхом, злиттям конфігурації,
+ життєвим циклом, семантикою для каналів і формою помічника середовища виконання.
+2. додайте типізовані поверхні реєстрації/runtime для Plugin
Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною
типізованою поверхнею можливості.
3. підключіть ядро + споживачів каналів/функцій
- Канали та feature plugin мають споживати нову можливість через ядро,
- а не через прямий імпорт реалізації постачальника.
+ Канали та Plugin функцій мають використовувати нову можливість через ядро,
+ а не імпортувати реалізацію постачальника напряму.
4. зареєструйте реалізації постачальників
- Потім plugin постачальників реєструють свої backend відносно цієї можливості.
+ Потім Plugin постачальників реєструють свої бекенди для цієї можливості.
5. додайте покриття контракту
- Додайте тести, щоб форма володіння та реєстрації з часом залишалася явною.
+ Додайте тести, щоб володіння й форма реєстрації з часом залишалися явними.
-Саме так OpenClaw зберігає свою виразну позицію, не стаючи жорстко
-прив’язаним до світогляду одного провайдера. Див. [Capability Cookbook](/uk/plugins/architecture),
-щоб отримати конкретний контрольний список файлів і готовий приклад.
+Саме так OpenClaw зберігає власну думку, не стаючи жорстко прив’язаним до
+світогляду одного провайдера. Див. [Capability Cookbook](/uk/plugins/architecture)
+для конкретного контрольного списку файлів і готового прикладу.
### Контрольний список можливості
@@ -1022,14 +1027,14 @@ export default function (api) {
таких поверхонь:
- типи контракту ядра в `src//types.ts`
-- виконавець ядра/допоміжний засіб середовища виконання в `src//runtime.ts`
-- поверхня реєстрації API plugin в `src/plugins/types.ts`
-- підключення реєстру plugin в `src/plugins/registry.ts`
-- відкриття в середовищі виконання plugin у `src/plugins/runtime/*`, коли feature/channel
- plugin мають це споживати
-- допоміжні засоби capture/test в `src/test-utils/plugin-registration.ts`
+- runner/помічник середовища виконання ядра в `src//runtime.ts`
+- поверхня реєстрації API Plugin у `src/plugins/types.ts`
+- підключення реєстру Plugin у `src/plugins/registry.ts`
+- відкриття середовища виконання Plugin у `src/plugins/runtime/*`, коли Plugin функцій/каналів
+ мають її використовувати
+- помічники захоплення/тестування в `src/test-utils/plugin-registration.ts`
- перевірки володіння/контракту в `src/plugins/contracts/registry.ts`
-- документація для операторів/plugin у `docs/`
+- документація для операторів/Plugin у `docs/`
Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість
ще не повністю інтегрована.
@@ -1046,7 +1051,7 @@ export type VideoGenerationProviderPlugin = {
generateVideo: (req: VideoGenerationRequest) => Promise;
};
-// API plugin
+// API Plugin
api.registerVideoGenerationProvider({
id: "openai",
label: "OpenAI",
@@ -1055,7 +1060,7 @@ api.registerVideoGenerationProvider({
},
});
-// спільний допоміжний засіб середовища виконання для feature/channel plugin
+// спільний помічник середовища виконання для Plugin функцій/каналів
const clip = await api.runtime.videoGeneration.generate({
prompt: "Show the robot walking through the lab.",
cfg,
@@ -1068,14 +1073,14 @@ const clip = await api.runtime.videoGeneration.generate({
expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
```
-Це зберігає просте правило:
+Це зберігає правило простим:
- ядро володіє контрактом можливості + оркестрацією
-- plugin постачальників володіють реалізаціями постачальників
-- feature/channel plugin споживають допоміжні засоби середовища виконання
-- тести контракту зберігають явність володіння
+- Plugin постачальників володіють реалізаціями постачальників
+- Plugin функцій/каналів використовують помічники середовища виконання
+- тести контракту зберігають володіння явним
-## Пов’язані матеріали
+## Пов’язане
- [Plugin architecture](/uk/plugins/architecture) — публічна модель можливостей і форми
- [Plugin SDK subpaths](/uk/plugins/sdk-subpaths)
diff --git a/docs/uk/tools/plugin.md b/docs/uk/tools/plugin.md
index cbb69e53a..f1e0474e3 100644
--- a/docs/uk/tools/plugin.md
+++ b/docs/uk/tools/plugin.md
@@ -4,37 +4,38 @@ read_when:
- Розуміння правил виявлення та завантаження плагінів
- Робота з сумісними з Codex/Claude пакетами плагінів
sidebarTitle: Install and Configure
-summary: Встановлюйте, налаштовуйте та керуйте плагінами OpenClaw
+summary: Встановлення, налаштування та керування плагінами OpenClaw
title: Плагіни
x-i18n:
- generated_at: "2026-04-25T17:39:20Z"
+ generated_at: "2026-04-25T19:49:09Z"
model: gpt-5.4
provider: openai
- source_hash: 82e272b1b59006b1f40b4acc3f21a8bca8ecacc1a8b7fb577ad3d874b9a8e326
+ source_hash: bbc819fc29f0bf58fce83223e43e2ddba3f199c71c6536e900ac6032f181d770
source_path: tools/plugin.md
workflow: 15
---
Плагіни розширюють OpenClaw новими можливостями: канали, постачальники моделей,
-обв’язки агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, голос
-у реальному часі, розуміння медіа, генерація зображень, генерація відео, отримання даних з вебу, вебпошук та інше. Деякі плагіни є **core** (постачаються разом з OpenClaw), інші
-є **external** (публікуються спільнотою в npm).
+середовища агентів, інструменти, Skills, мовлення, транскрипція в реальному часі, голос у реальному
+часі, розуміння медіа, генерація зображень, генерація відео, веб-отримання, веб-
+пошук тощо. Деякі плагіни є **core** (постачаються з OpenClaw), інші —
+**external** (опубліковані спільнотою в npm).
## Швидкий старт
-
+
```bash
openclaw plugins list
```
-
+
```bash
- # From npm
+ # З npm
openclaw plugins install @openclaw/voice-call
- # From a local directory or archive
+ # З локального каталогу або архіву
openclaw plugins install ./my-plugin
openclaw plugins install ./my-plugin.tgz
```
@@ -59,52 +60,52 @@ x-i18n:
/plugin enable voice-call
```
-Шлях установлення використовує той самий механізм визначення джерела, що й CLI: локальний
-шлях/архів, явний `clawhub:` або специфікація пакета без префікса (спочатку ClawHub, потім резервне звернення до npm).
+Шлях встановлення використовує той самий механізм розв’язання, що й CLI: локальний
+шлях/архів, явний `clawhub:` або специфікація пакета без префікса (спочатку ClawHub, потім резервний перехід на npm).
-Якщо конфігурація некоректна, установлення зазвичай безпечно завершується з відмовою та вказує вам на
-`openclaw doctor --fix`. Єдиний виняток для відновлення — це вузький шлях
-перевстановлення вбудованого плагіна для плагінів, які погоджуються на
+Якщо конфігурація некоректна, встановлення зазвичай безпечно завершується відмовою і пропонує
+скористатися `openclaw doctor --fix`. Єдиний виняток для відновлення — це вузький шлях
+перевстановлення вбудованого плагіна для плагінів, які підтримують
`openclaw.install.allowInvalidConfigRecovery`.
-Пакетні встановлення OpenClaw не встановлюють заздалегідь усе дерево
-залежностей середовища виконання кожного вбудованого плагіна. Коли вбудований плагін, що належить OpenClaw, активний через
-конфігурацію плагіна, застарілу конфігурацію каналу або маніфест із увімкненням за замовчуванням, під час запуску
-відновлюються лише оголошені залежності середовища виконання цього плагіна перед його імпортом.
+Пакетні встановлення OpenClaw не встановлюють завчасно все дерево залежностей середовища виконання кожного вбудованого плагіна.
+Коли вбудований плагін, що належить OpenClaw, активний через
+конфігурацію плагіна, застарілу конфігурацію каналу або маніфест, увімкнений за замовчуванням,
+під час запуску відновлюються лише оголошені цим плагіном залежності середовища виконання перед його імпортом.
Явне вимкнення все одно має пріоритет: `plugins.entries..enabled: false`,
`plugins.deny`, `plugins.enabled: false` і `channels..enabled: false`
-запобігають автоматичному відновленню залежностей середовища виконання вбудованого плагіна для цього плагіна/каналу.
-External плагіни та власні шляхи завантаження все одно потрібно встановлювати через
+запобігають автоматичному відновленню залежностей середовища виконання для цього плагіна/каналу.
+External-плагіни та користувацькі шляхи завантаження, як і раніше, потрібно встановлювати через
`openclaw plugins install`.
## Типи плагінів
OpenClaw розпізнає два формати плагінів:
-| Формат | Як це працює | Приклади |
-| ---------- | ----------------------------------------------------------------- | ------------------------------------------------------ |
-| **Native** | `openclaw.plugin.json` + модуль середовища виконання; виконується в межах процесу | Офіційні плагіни, npm-пакети спільноти |
-| **Bundle** | Сумісне з Codex/Claude/Cursor компонування; зіставляється з можливостями OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
+| Формат | Як це працює | Приклади |
+| ---------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
+| **Native** | `openclaw.plugin.json` + модуль середовища виконання; виконується в тому ж процесі | Офіційні плагіни, пакети npm від спільноти |
+| **Bundle** | Сумісне з Codex/Claude/Cursor компонування; відображається на можливості OpenClaw | `.codex-plugin/`, `.claude-plugin/`, `.cursor-plugin/` |
-Обидва відображаються в `openclaw plugins list`. Докладніше про пакети див. у [Пакети плагінів](/uk/plugins/bundles).
+Обидва відображаються в `openclaw plugins list`. Докладніше про пакети див. у [Plugin Bundles](/uk/plugins/bundles).
-Якщо ви пишете native плагін, почніть із [Створення плагінів](/uk/plugins/building-plugins)
-і [Огляд Plugin SDK](/uk/plugins/sdk-overview).
+Якщо ви пишете native-плагін, почніть із [Building Plugins](/uk/plugins/building-plugins)
+та [Plugin SDK Overview](/uk/plugins/sdk-overview).
## Офіційні плагіни
-### Доступні для встановлення (npm)
+### Встановлювані (npm)
| Плагін | Пакет | Документація |
| --------------- | --------------------- | ------------------------------------ |
| Matrix | `@openclaw/matrix` | [Matrix](/uk/channels/matrix) |
| Microsoft Teams | `@openclaw/msteams` | [Microsoft Teams](/uk/channels/msteams) |
| Nostr | `@openclaw/nostr` | [Nostr](/uk/channels/nostr) |
-| Voice Call | `@openclaw/voice-call` | [Voice Call](/uk/plugins/voice-call) |
+| Voice Call | `@openclaw/voice-call`| [Voice Call](/uk/plugins/voice-call) |
| Zalo | `@openclaw/zalo` | [Zalo](/uk/channels/zalo) |
| Zalo Personal | `@openclaw/zalouser` | [Zalo Personal](/uk/plugins/zalouser) |
-### Core (постачаються разом з OpenClaw)
+### Core (постачаються з OpenClaw)
@@ -117,7 +118,7 @@ OpenClaw розпізнає два формати плагінів:
- `memory-core` — вбудований пошук у пам’яті (типово через `plugins.slots.memory`)
- - `memory-lancedb` — довготривала пам’ять із встановленням за потреби, автоматичним пригадуванням/захопленням (установіть `plugins.slots.memory = "memory-lancedb"`)
+ - `memory-lancedb` — довгострокова пам’ять із встановленням за потреби та автоматичним пригадуванням/захопленням (встановіть `plugins.slots.memory = "memory-lancedb"`)
@@ -125,12 +126,12 @@ OpenClaw розпізнає два формати плагінів:
- - `browser` — вбудований браузерний плагін для інструмента браузера, CLI `openclaw browser`, методу Gateway `browser.request`, середовища виконання браузера та служби керування браузером за замовчуванням (увімкнений за замовчуванням; вимкніть його перед заміною)
+ - `browser` — вбудований browser-плагін для browser tool, CLI `openclaw browser`, методу Gateway `browser.request`, browser runtime та служби керування браузером за замовчуванням (увімкнений за замовчуванням; вимкніть його перед заміною)
- `copilot-proxy` — міст VS Code Copilot Proxy (вимкнений за замовчуванням)
-Шукаєте сторонні плагіни? Див. [Плагіни спільноти](/uk/plugins/community).
+Шукаєте сторонні плагіни? Див. [Community Plugins](/uk/plugins/community).
## Конфігурація
@@ -152,35 +153,35 @@ OpenClaw розпізнає два формати плагінів:
| ---------------- | --------------------------------------------------------- |
| `enabled` | Головний перемикач (типово: `true`) |
| `allow` | Список дозволених плагінів (необов’язково) |
-| `deny` | Список заборонених плагінів (необов’язково; заборона має пріоритет) |
+| `deny` | Список заборонених плагінів (необов’язково; deny має пріоритет) |
| `load.paths` | Додаткові файли/каталоги плагінів |
| `slots` | Селектори ексклюзивних слотів (наприклад, `memory`, `contextEngine`) |
| `entries.\` | Перемикачі та конфігурація для окремого плагіна |
-Зміни конфігурації **потребують перезапуску Gateway**. Якщо Gateway працює з
-відстеженням конфігурації та внутрішньопроцесним перезапуском (стандартний шлях `openclaw gateway`), цей
-перезапуск зазвичай виконується автоматично невдовзі після запису змін у конфігурацію.
-Підтримуваного шляху гарячого перезавантаження для native коду середовища виконання плагіна або його
-хуків життєвого циклу немає; перезапустіть процес Gateway, який обслуговує активний канал, перш ніж
+Зміни конфігурації **потребують перезапуску Gateway**. Якщо Gateway запущено з
+відстеженням конфігурації та перезапуском у процесі (типовий шлях `openclaw gateway`),
+такий перезапуск зазвичай виконується автоматично невдовзі після запису конфігурації.
+Підтримуваного шляху hot-reload для коду native-плагінів або хуків життєвого циклу немає;
+перезапустіть процес Gateway, який обслуговує активний канал, перш ніж
очікувати, що оновлений код `register(api)`, хуки `api.on(...)`, інструменти, служби або
-хуки постачальника/середовища виконання почнуть працювати.
+хуки постачальника/runtime почнуть виконуватися.
-`openclaw plugins list` — це локальний знімок реєстру/конфігурації плагінів. Позначка
-`enabled` там означає, що збережений реєстр і поточна конфігурація дозволяють
-плагіну брати участь у роботі. Це не доводить, що вже запущений віддалений дочірній процес Gateway
-перезапустився з тим самим кодом плагіна. У середовищах VPS/контейнерів із
-процесами-обгортками надсилайте перезапуск до фактичного процесу `openclaw gateway run`,
+`openclaw plugins list` — це локальний знімок реєстру/конфігурації плагінів. Плагін зі
+станом `enabled` там означає, що збережений реєстр і поточна конфігурація дозволяють
+йому брати участь. Це не доводить, що вже запущений дочірній процес віддаленого Gateway
+перезапустився з тим самим кодом плагіна. У VPS/контейнерних конфігураціях із
+процесами-обгортками надсилайте перезапуск фактичному процесу `openclaw gateway run`,
або використовуйте `openclaw gateway restart` для запущеного Gateway.
-
- - **Disabled**: плагін існує, але правила ввімкнення його вимкнули. Конфігурація зберігається.
- - **Missing**: конфігурація посилається на ідентифікатор плагіна, який механізм виявлення не знайшов.
+
+ - **Disabled**: плагін існує, але правила увімкнення його вимкнули. Конфігурація зберігається.
+ - **Missing**: конфігурація посилається на ідентифікатор плагіна, який не було знайдено під час виявлення.
- **Invalid**: плагін існує, але його конфігурація не відповідає оголошеній схемі.
## Виявлення та пріоритет
-OpenClaw сканує плагіни в такому порядку (перше збігле входження має пріоритет):
+OpenClaw сканує плагіни в такому порядку (перше збіг — пріоритетний):
@@ -196,96 +197,97 @@ OpenClaw сканує плагіни в такому порядку (перше
- Постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (постачальники моделей, мовлення).
+ Постачаються з OpenClaw. Багато з них увімкнено за замовчуванням (постачальники моделей, мовлення).
Інші потребують явного ввімкнення.
-### Правила ввімкнення
+### Правила увімкнення
- `plugins.enabled: false` вимикає всі плагіни
- `plugins.deny` завжди має пріоритет над allow
- `plugins.entries.\.enabled: false` вимикає цей плагін
-- Плагіни з робочого простору **вимкнені за замовчуванням** (їх треба явно ввімкнути)
-- Вбудовані плагіни дотримуються вбудованого набору, увімкненого за замовчуванням, якщо не перевизначено
+- Плагіни з робочого простору **вимкнені за замовчуванням** (їх потрібно явно ввімкнути)
+- Вбудовані плагіни дотримуються вбудованого набору, увімкненого за замовчуванням, якщо його не перевизначено
- Ексклюзивні слоти можуть примусово ввімкнути вибраний для цього слота плагін
-- Деякі вбудовані плагіни з добровільним ввімкненням автоматично вмикаються, коли конфігурація вказує поверхню, що належить плагіну,
- наприклад посилання на модель постачальника, конфігурацію каналу або середовище виконання
- обв’язки
-- Маршрути Codex сімейства OpenAI зберігають окремі межі плагінів:
+- Деякі вбудовані плагіни з режимом opt-in вмикаються автоматично, коли конфігурація вказує поверхню, що належить плагіну,
+ наприклад посилання на модель постачальника, конфігурацію каналу або
+ runtime середовища
+- Маршрути Codex родини OpenAI зберігають окремі межі плагінів:
`openai-codex/*` належить плагіну OpenAI, тоді як вбудований плагін
- сервера застосунку Codex вибирається через `embeddedHarness.runtime: "codex"` або застарілі
+ app-server Codex вибирається через `embeddedHarness.runtime: "codex"` або застарілі
посилання на моделі `codex/*`
## Усунення проблем із хуками середовища виконання
-Якщо плагін відображається в `plugins list`, але побічні ефекти або хуки `register(api)`
-не спрацьовують у трафіку активного чату, спочатку перевірте таке:
+Якщо плагін з’являється в `plugins list`, але побічні ефекти `register(api)` або хуки
+не виконуються в трафіку живого чату, спочатку перевірте таке:
- Запустіть `openclaw gateway status --deep --require-rpc` і підтвердьте, що активні
URL Gateway, профіль, шлях до конфігурації та процес — саме ті, які ви редагуєте.
-- Перезапустіть активний Gateway після змін установлення/конфігурації/коду плагіна. У контейнерах
- з обгорткою PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому
+- Перезапустіть активний Gateway після встановлення/зміни конфігурації/зміни коду плагіна. У контейнерах
+ з обгортками PID 1 може бути лише супервізором; перезапустіть або надішліть сигнал дочірньому
процесу `openclaw gateway run`.
-- Використовуйте `openclaw plugins inspect --json`, щоб підтвердити реєстрацію хуків і
- діагностику. Невбудовані хуки розмови, як-от `llm_input`,
- `llm_output` і `agent_end`, потребують
+- Використовуйте `openclaw plugins inspect --json`, щоб підтвердити реєстрації хуків і
+ діагностику. Для невбудованих розмовних хуків, таких як `llm_input`,
+ `llm_output` і `agent_end`, потрібен
`plugins.entries..hooks.allowConversationAccess=true`.
-- Для перемикання моделей надавайте перевагу `before_model_resolve`. Він спрацьовує перед визначенням моделі
- для ходів агента; `llm_output` спрацьовує лише після того, як спроба роботи моделі
- створює вивід помічника.
+- Для перемикання моделей надавайте перевагу `before_model_resolve`. Цей хук виконується до
+ розв’язання моделі для ходів агента; `llm_output` виконується лише після того, як спроба
+ моделі створить відповідь асистента.
- Щоб підтвердити фактичну модель сеансу, використовуйте `openclaw sessions` або
- поверхні сеансу/стану Gateway, а під час налагодження корисного навантаження постачальника запускайте
+ поверхні сеансу/стану Gateway, а під час налагодження навантажень постачальника запускайте
Gateway з `--raw-stream --raw-stream-path `.
## Слоти плагінів (ексклюзивні категорії)
-Деякі категорії є ексклюзивними (одночасно може бути активним лише один плагін):
+Деякі категорії є ексклюзивними (одночасно може бути активним лише один):
```json5
{
plugins: {
slots: {
- memory: "memory-core", // or "none" to disable
- contextEngine: "legacy", // or a plugin id
+ memory: "memory-core", // або "none", щоб вимкнути
+ contextEngine: "legacy", // або id плагіна
},
},
}
```
-| Слот | Що він контролює | Типово |
-| --------------- | ----------------------- | ------------------- |
-| `memory` | Active Memory плагін | `memory-core` |
-| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) |
+| Слот | Що він контролює | Типове значення |
+| --------------- | ------------------------- | ------------------- |
+| `memory` | Active Memory плагін | `memory-core` |
+| `contextEngine` | Активний рушій контексту | `legacy` (вбудований) |
-## Довідка CLI
+## Довідник CLI
```bash
-openclaw plugins list # compact inventory
-openclaw plugins list --enabled # only enabled plugins
-openclaw plugins list --verbose # per-plugin detail lines
-openclaw plugins list --json # machine-readable inventory
-openclaw plugins inspect # deep detail
-openclaw plugins inspect --json # machine-readable
-openclaw plugins inspect --all # fleet-wide table
-openclaw plugins info # inspect alias
-openclaw plugins doctor # diagnostics
-openclaw plugins registry # inspect persisted registry state
-openclaw plugins registry --refresh # rebuild persisted registry
+openclaw plugins list # компактний список
+openclaw plugins list --enabled # лише увімкнені плагіни
+openclaw plugins list --verbose # докладні рядки для кожного плагіна
+openclaw plugins list --json # машиночитаний список
+openclaw plugins inspect # докладна інформація
+openclaw plugins inspect --json # машиночитаний формат
+openclaw plugins inspect --all # таблиця для всіх
+openclaw plugins info # псевдонім для inspect
+openclaw plugins doctor # діагностика
+openclaw plugins registry # перевірка збереженого стану реєстру
+openclaw plugins registry --refresh # перебудувати збережений реєстр
+openclaw doctor --fix # виправити стан міграції реєстру/журналу
-openclaw plugins install # install (ClawHub first, then npm)
-openclaw plugins install clawhub: # install from ClawHub only
-openclaw plugins install --force # overwrite existing install
-openclaw plugins install # install from local path
-openclaw plugins install -l # link (no copy) for dev
+openclaw plugins install # встановити (спочатку ClawHub, потім npm)
+openclaw plugins install clawhub: # встановити лише з ClawHub
+openclaw plugins install --force # перезаписати наявне встановлення
+openclaw plugins install # встановити з локального шляху
+openclaw plugins install -l # підключити (без копіювання) для розробки
openclaw plugins install --marketplace
openclaw plugins install --marketplace https://github.com//
-openclaw plugins install --pin # record exact resolved npm spec
+openclaw plugins install --pin # зберегти точну розв’язану npm-специфікацію
openclaw plugins install --dangerously-force-unsafe-install
-openclaw plugins update # update one plugin
+openclaw plugins update # оновити один плагін
openclaw plugins update --dangerously-force-unsafe-install
-openclaw plugins update --all # update all
-openclaw plugins uninstall # remove config/install records
+openclaw plugins update --all # оновити всі
+openclaw plugins uninstall # видалити записи конфігурації та журналу встановлення
openclaw plugins uninstall --keep-files
openclaw plugins marketplace list
openclaw plugins marketplace list --json
@@ -295,65 +297,68 @@ openclaw plugins disable
```
Вбудовані плагіни постачаються разом з OpenClaw. Багато з них увімкнені за замовчуванням (наприклад,
-вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований браузерний
-плагін). Інші вбудовані плагіни все одно потребують `openclaw plugins enable `.
+вбудовані постачальники моделей, вбудовані постачальники мовлення та вбудований browser-
+плагін). Інші вбудовані плагіни все ще потребують `openclaw plugins enable `.
-`--force` перезаписує наявний установлений плагін або пакет хуків на місці. Для
+`--force` перезаписує наявний встановлений плагін або набір хуків на місці. Для
звичайних оновлень відстежуваних npm-плагінів використовуйте
-`openclaw plugins update `. Цей параметр не підтримується разом із `--link`, який повторно використовує вихідний шлях
-замість копіювання в цільовий каталог керованого встановлення.
+`openclaw plugins update `. Цей параметр не підтримується з `--link`, який повторно використовує вихідний шлях
+замість копіювання в керовану ціль встановлення.
-Коли `plugins.allow` уже задано, `openclaw plugins install` додає
-ідентифікатор встановленого плагіна до цього списку дозволених перед його ввімкненням, щоб після
-перезапуску встановлені плагіни можна було відразу завантажувати.
+Коли `plugins.allow` уже встановлено, `openclaw plugins install` додає
+ідентифікатор встановленого плагіна до цього списку дозволених перед його ввімкненням, тож встановлені плагіни
+можна завантажувати одразу після перезапуску.
OpenClaw зберігає локальний реєстр плагінів як модель холодного читання для
-інвентаризації плагінів, визначення власника внесків і планування запуску. Потоки встановлення, оновлення,
-видалення, ввімкнення та вимкнення оновлюють цей реєстр після зміни стану
-плагіна. Якщо реєстр відсутній, застарілий або недійсний, `openclaw plugins registry
---refresh` перебудовує його з надійного журналу встановлень, політики конфігурації та
-метаданих маніфесту/пакета без завантаження модулів середовища виконання плагінів.
+інвентаризації плагінів, володіння внесками та планування запуску. Потоки встановлення, оновлення,
+видалення, увімкнення та вимкнення оновлюють цей реєстр після зміни стану
+плагіна. Якщо реєстр відсутній, застарів або некоректний, `openclaw plugins registry
+--refresh` перебудовує його на основі довговічного журналу встановлень, політики конфігурації та
+метаданих маніфесту/пакета без завантаження модулів середовища виконання плагіна.
+Якщо на машині все ще є застарілі записи `plugins.installs` у конфігурації, виконайте
+`openclaw doctor --fix`, щоб перемістити їх у керований
+журнал `plugins/installs.json` і видалити копію з конфігурації.
`openclaw plugins update ` застосовується до відстежуваних встановлень. Передавання
-специфікації npm-пакета з dist-tag або точною версією зіставляє назву пакета
-назад із записом відстежуваного плагіна та зберігає нову специфікацію для майбутніх оновлень.
-Передавання назви пакета без версії переводить точно зафіксоване встановлення назад на
-стандартну лінію випуску реєстру. Якщо встановлений npm-плагін уже відповідає
-визначеній версії та ідентичності збереженого артефакту, OpenClaw пропускає оновлення
-без завантаження, перевстановлення або перезапису конфігурації.
+npm-специфікації пакета з dist-tag або точною версією розв’язує назву пакета
+назад до запису відстежуваного плагіна та зберігає нову специфікацію для майбутніх оновлень.
+Передавання назви пакета без версії переводить точно закріплене встановлення назад на
+типову лінію релізів реєстру. Якщо встановлений npm-плагін уже відповідає
+розв’язаній версії та збереженій ідентичності артефакту, OpenClaw пропускає оновлення
+без завантаження, перевстановлення чи перезапису конфігурації.
-`--pin` стосується лише npm. Він не підтримується з `--marketplace`, оскільки
-встановлення з marketplace зберігають метадані джерела marketplace замість специфікації npm.
+`--pin` призначений лише для npm. Він не підтримується з `--marketplace`, оскільки
+встановлення з marketplace зберігають метадані джерела marketplace замість npm-специфікації.
`--dangerously-force-unsafe-install` — це аварійне перевизначення для хибнопозитивних
-спрацювань вбудованого сканера небезпечного коду. Воно дозволяє встановленню
-та оновленню плагінів продовжуватися попри вбудовані результати рівня `critical`, але все одно
-не обходить блокування політики плагіна `before_install` або блокування через помилки сканування.
+спрацювань вбудованого сканера небезпечного коду. Воно дозволяє встановленням і оновленням плагінів
+продовжуватися попри вбудовані результати `critical`, але все одно
+не обходить блокування політики плагіна `before_install` або блокування через помилку сканування.
-Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Установлення залежностей Skills через Gateway
-натомість використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install` залишається окремим потоком завантаження/встановлення Skills із ClawHub.
+Цей прапорець CLI застосовується лише до потоків встановлення/оновлення плагінів. Встановлення залежностей Skills
+через Gateway натомість використовують відповідне перевизначення запиту `dangerouslyForceUnsafeInstall`, тоді як `openclaw skills install`
+залишається окремим потоком завантаження/встановлення Skills з ClawHub.
-Сумісні пакети беруть участь у тих самих потоках list/inspect/enable/disable
-для плагінів. Поточна підтримка середовища виконання включає Skills у пакетах, command-skills для Claude,
-значення за замовчуванням Claude `settings.json`, Claude `.lsp.json` і оголошені в маніфесті
-значення за замовчуванням `lspServers`, command-skills для Cursor та сумісні каталоги
-хуків Codex.
+Сумісні пакети беруть участь у тому самому потоці list/inspect/enable/disable
+для плагінів. Поточна підтримка середовища виконання включає bundle Skills, Claude command-skills,
+типові значення Claude `settings.json`, типові значення Claude `.lsp.json` і оголошених у маніфесті
+`lspServers`, Cursor command-skills і сумісні каталоги хуків Codex.
-`openclaw plugins inspect ` також повідомляє про виявлені можливості пакетів, а також
+`openclaw plugins inspect ` також повідомляє про виявлені можливості пакета, а також
підтримувані або непідтримувані записи серверів MCP і LSP для плагінів на основі пакетів.
-Джерелами marketplace можуть бути відома назва marketplace Claude з
+Джерелами marketplace можуть бути відома назва Claude marketplace з
`~/.claude/plugins/known_marketplaces.json`, локальний корінь marketplace або шлях до
-`marketplace.json`, скорочений запис GitHub на кшталт `owner/repo`, URL репозиторію GitHub
-або git URL. Для віддалених marketplace записи плагінів мають залишатися в межах
-клонованого репозиторію marketplace і використовувати лише відносні джерела шляхів.
+`marketplace.json`, скорочення GitHub на кшталт `owner/repo`, URL GitHub-репозиторію або URL git. Для віддалених marketplace
+записи плагінів мають залишатися всередині клонованого репозиторію marketplace і використовувати лише
+відносні шляхи як джерела.
-Повні відомості див. у [довідці CLI `openclaw plugins`](/uk/cli/plugins).
+Повні відомості див. у [довіднику CLI `openclaw plugins`](/uk/cli/plugins).
-## Огляд Plugin API
+## Огляд API плагінів
-Native плагіни експортують об’єкт входу, який надає `register(api)`. Старіші
-плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові плагіни повинні
+Native-плагіни експортують об’єкт входу, який надає `register(api)`. Старіші
+плагіни все ще можуть використовувати `activate(api)` як застарілий псевдонім, але нові плагіни мають
використовувати `register`.
```typescript
@@ -375,74 +380,74 @@ export default definePluginEntry({
```
OpenClaw завантажує об’єкт входу та викликає `register(api)` під час
-активації плагіна. Завантажувач і далі використовує `activate(api)` як резервний варіант для старіших плагінів,
-але вбудовані плагіни та нові external плагіни повинні розглядати `register` як
+активації плагіна. Завантажувач усе ще повертається до `activate(api)` для старіших плагінів,
+але вбудовані плагіни та нові external-плагіни мають розглядати `register` як
публічний контракт.
-`api.registrationMode` повідомляє плагіну, чому завантажується його запис:
+`api.registrationMode` повідомляє плагіну, чому завантажується його об’єкт входу:
-| Режим | Значення |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `full` | Активація середовища виконання. Реєструє інструменти, хуки, служби, команди, маршрути та інші побічні ефекти активної роботи. |
-| `discovery` | Виявлення можливостей лише для читання. Реєструє постачальників і метадані; код входу довіреного плагіна може завантажуватися, але слід пропускати активні побічні ефекти. |
-| `setup-only` | Завантаження метаданих налаштування каналу через спрощений запис налаштування. |
-| `setup-runtime`| Завантаження налаштування каналу, якому також потрібен запис середовища виконання. |
-| `cli-metadata` | Лише збирання метаданих команд CLI. |
+| Режим | Значення |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `full` | Активація середовища виконання. Реєструйте інструменти, хуки, служби, команди, маршрути та інші побічні ефекти в реальному часі. |
+| `discovery` | Виявлення можливостей лише для читання. Реєструйте постачальників і метадані; код входу довіреного плагіна може завантажуватися, але пропускайте побічні ефекти реального часу. |
+| `setup-only` | Завантаження метаданих налаштування каналу через полегшений об’єкт входу налаштування. |
+| `setup-runtime` | Завантаження налаштування каналу, яке також потребує об’єкта входу середовища виконання. |
+| `cli-metadata` | Лише збирання метаданих команди CLI. |
-Записи плагінів, які відкривають сокети, бази даних, фонові працівники або довгоживучі
-клієнти, повинні захищати ці побічні ефекти перевіркою `api.registrationMode === "full"`.
-Завантаження для виявлення кешуються окремо від активаційних завантажень і не замінюють
+Об’єкти входу плагінів, які відкривають сокети, бази даних, фонові воркери або довготривалі
+клієнти, повинні захищати ці побічні ефекти умовою `api.registrationMode === "full"`.
+Завантаження для виявлення кешуються окремо від завантажень активації та не замінюють
реєстр запущеного Gateway. Виявлення не активує, але й не є вільним від імпорту:
-OpenClaw може виконувати trusted запис плагіна або модуль плагіна каналу, щоб побудувати
-знімок. Робіть верхній рівень модуля легким і без побічних ефектів, а мережеві клієнти,
-підпроцеси, слухачі, зчитування облікових даних і запуск служб переносьте
-за межі повного шляху середовища виконання.
+OpenClaw може обчислювати довірений об’єкт входу плагіна або модуль плагіна каналу, щоб побудувати
+знімок. Тримайте верхні рівні модулів легкими та без побічних ефектів і переносьте
+мережевих клієнтів, підпроцеси, слухачі, читання облікових даних і запуск служб
+за шляхи повного середовища виконання.
Поширені методи реєстрації:
-| Метод | Що він реєструє |
-| -------------------------------------- | --------------------------- |
-| `registerProvider` | Постачальник моделі (LLM) |
-| `registerChannel` | Чат-канал |
-| `registerTool` | Інструмент агента |
-| `registerHook` / `on(...)` | Хуки життєвого циклу |
+| Метод | Що він реєструє |
+| -------------------------------------- | -------------------------- |
+| `registerProvider` | Постачальник моделей (LLM) |
+| `registerChannel` | Канал чату |
+| `registerTool` | Інструмент агента |
+| `registerHook` / `on(...)` | Хуки життєвого циклу |
| `registerSpeechProvider` | Перетворення тексту на мовлення / STT |
-| `registerRealtimeTranscriptionProvider`| Потоковий STT |
-| `registerRealtimeVoiceProvider` | Двобічний голос у реальному часі |
-| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
-| `registerImageGenerationProvider` | Генерація зображень |
-| `registerMusicGenerationProvider` | Генерація музики |
-| `registerVideoGenerationProvider` | Генерація відео |
-| `registerWebFetchProvider` | Постачальник отримання/скрейпінгу вебданих |
-| `registerWebSearchProvider` | Вебпошук |
-| `registerHttpRoute` | HTTP-ендпойнт |
-| `registerCommand` / `registerCli` | Команди CLI |
-| `registerContextEngine` | Рушій контексту |
-| `registerService` | Фонова служба |
+| `registerRealtimeTranscriptionProvider`| Потоковий STT |
+| `registerRealtimeVoiceProvider` | Двоспрямований голос у реальному часі |
+| `registerMediaUnderstandingProvider` | Аналіз зображень/аудіо |
+| `registerImageGenerationProvider` | Генерація зображень |
+| `registerMusicGenerationProvider` | Генерація музики |
+| `registerVideoGenerationProvider` | Генерація відео |
+| `registerWebFetchProvider` | Постачальник веб-отримання / скрапінгу |
+| `registerWebSearchProvider` | Веб-пошук |
+| `registerHttpRoute` | HTTP-ендпойнт |
+| `registerCommand` / `registerCli` | Команди CLI |
+| `registerContextEngine` | Рушій контексту |
+| `registerService` | Фонова служба |
-Поведінка захисних механізмів хуків для типізованих хуків життєвого циклу:
+Поведінка захисту хуків для типізованих хуків життєвого циклу:
-- `before_tool_call`: `{ block: true }` є фінальним; обробники з нижчим пріоритетом пропускаються.
-- `before_tool_call`: `{ block: false }` нічого не змінює та не скасовує попереднє блокування.
-- `before_install`: `{ block: true }` є фінальним; обробники з нижчим пріоритетом пропускаються.
-- `before_install`: `{ block: false }` нічого не змінює та не скасовує попереднє блокування.
-- `message_sending`: `{ cancel: true }` є фінальним; обробники з нижчим пріоритетом пропускаються.
-- `message_sending`: `{ cancel: false }` нічого не змінює та не скасовує попереднє скасування.
+- `before_tool_call`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
+- `before_tool_call`: `{ block: false }` нічого не робить і не скасовує попереднє блокування.
+- `before_install`: `{ block: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
+- `before_install`: `{ block: false }` нічого не робить і не скасовує попереднє блокування.
+- `message_sending`: `{ cancel: true }` є термінальним; обробники з нижчим пріоритетом пропускаються.
+- `message_sending`: `{ cancel: false }` нічого не робить і не скасовує попереднє скасування.
-Native сервер застосунку Codex повертає власні події інструментів Codex назад у цю
-поверхню хуків через міст. Плагіни можуть блокувати native інструменти Codex через `before_tool_call`,
-спостерігати за результатами через `after_tool_call` і брати участь у затвердженнях
-Codex `PermissionRequest`. Міст поки що не переписує аргументи native інструментів Codex.
-Точна межа підтримки середовища виконання Codex визначена в
+Native app-server Codex повертає події інструментів Codex-native назад у цю
+поверхню хуків через міст. Плагіни можуть блокувати native-інструменти Codex через `before_tool_call`,
+спостерігати за результатами через `after_tool_call` і брати участь у погодженнях
+`PermissionRequest` Codex. Міст поки що не переписує аргументи
+інструментів Codex-native. Точна межа підтримки середовища виконання Codex визначена в
[контракті підтримки Codex harness v1](/uk/plugins/codex-harness#v1-support-contract).
-Докладно про типізовану поведінку хуків див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics).
+Повну інформацію про типізовану поведінку хуків див. в [огляді SDK](/uk/plugins/sdk-overview#hook-decision-semantics).
-## Пов’язані матеріали
+## Пов’язане
-- [Створення плагінів](/uk/plugins/building-plugins) — створіть власний плагін
-- [Пакети плагінів](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor
-- [Маніфест плагіна](/uk/plugins/manifest) — схема маніфесту
-- [Реєстрація інструментів](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента в плагіні
-- [Внутрішня будова плагінів](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження
-- [Плагіни спільноти](/uk/plugins/community) — сторонні добірки
+- [Building plugins](/uk/plugins/building-plugins) — створення власного плагіна
+- [Plugin bundles](/uk/plugins/bundles) — сумісність пакетів Codex/Claude/Cursor
+- [Plugin manifest](/uk/plugins/manifest) — схема маніфесту
+- [Registering tools](/uk/plugins/building-plugins#registering-agent-tools) — додавання інструментів агента до плагіна
+- [Plugin internals](/uk/plugins/architecture) — модель можливостей і конвеєр завантаження
+- [Community plugins](/uk/plugins/community) — списки сторонніх плагінів