diff --git a/docs/uk/plugins/architecture.md b/docs/uk/plugins/architecture.md
index 529c55808..e5d3e0f13 100644
--- a/docs/uk/plugins/architecture.md
+++ b/docs/uk/plugins/architecture.md
@@ -1,186 +1,188 @@
---
read_when:
- - Створення або налагодження власних плагінів OpenClaw
- - Розуміння моделі можливостей плагінів або меж володіння
- - Робота над конвеєром завантаження плагінів або реєстром
- - Реалізація хуків середовища виконання провайдера або плагінів каналів
+ - Створення або налагодження нативних Plugin для OpenClaw
+ - Розуміння моделі можливостей Plugin або меж володіння
+ - Робота над конвеєром завантаження Plugin або реєстром
+ - Реалізація хуків середовища виконання провайдера або каналів Plugin
sidebarTitle: Internals
-summary: 'Внутрішні компоненти плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби середовища виконання'
-title: Внутрішні компоненти плагінів
+summary: 'Внутрішні механізми Plugin: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби середовища виконання'
+title: Внутрішні механізми Plugin
x-i18n:
- generated_at: "2026-04-12T08:09:15Z"
+ generated_at: "2026-04-12T09:53:30Z"
model: gpt-5.4
provider: openai
- source_hash: 6f4f8e6bcb14358b3aaa698d03faf456bbeebc04a6d70d1ae6451b02ab17cf09
+ source_hash: 5bf11fc59b5e201837708ea1ac6ef4bbbdc6f1f6e853fb888fff08ed5d38a370
source_path: plugins/architecture.md
workflow: 15
---
-# Внутрішні компоненти плагінів
+# Внутрішні механізми Plugin
- Це **поглиблений довідник з архітектури**. Практичні посібники дивіться тут:
- - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник користувача
- - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний посібник зі створення плагіна
- - [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями
- - [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення провайдера моделей
- - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпорту та API реєстрації
+ Це **поглиблений довідник з архітектури**. Практичні посібники див. тут:
+ - [Встановлення та використання Plugin](/uk/tools/plugin) — посібник для користувача
+ - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний посібник зі створення Plugin
+ - [Канальні Plugin](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями
+ - [Plugin провайдерів](/uk/plugins/sdk-provider-plugins) — створення провайдера моделей
+ - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпортів і API реєстрації
-На цій сторінці описано внутрішню архітектуру системи плагінів OpenClaw.
+На цій сторінці описано внутрішню архітектуру системи Plugin OpenClaw.
## Публічна модель можливостей
-Можливості — це публічна модель **власних плагінів** усередині OpenClaw. Кожен
-власний плагін OpenClaw реєструється для одного або кількох типів можливостей:
+Можливості — це публічна модель **нативних Plugin** всередині OpenClaw. Кожен
+нативний Plugin OpenClaw реєструється для одного або кількох типів можливостей:
-| Можливість | Метод реєстрації | Приклади плагінів |
-| --------------------- | ----------------------------------------------- | ------------------------------------ |
-| Текстовий висновок | `api.registerProvider(...)` | `openai`, `anthropic` |
-| Серверна частина CLI для висновку | `api.registerCliBackend(...)` | `openai`, `anthropic` |
-| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` |
+| Можливість | Метод реєстрації | Приклади Plugin |
+| --------------------- | ---------------------------------------------- | ------------------------------------ |
+| Текстова інференція | `api.registerProvider(...)` | `openai`, `anthropic` |
+| Бекенд CLI-інференції | `api.registerCliBackend(...)` | `openai`, `anthropic` |
+| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` |
| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` |
-| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` |
-| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` |
-| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` |
-| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` |
-| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` |
-| Веботримання | `api.registerWebFetchProvider(...)` | `firecrawl` |
-| Вебпошук | `api.registerWebSearchProvider(...)` | `google` |
-| Канал / обмін повідомленнями | `api.registerChannel(...)` | `msteams`, `matrix` |
+| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | `openai` |
+| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | `openai`, `google` |
+| Генерація зображень | `api.registerImageGenerationProvider(...)` | `openai`, `google`, `fal`, `minimax` |
+| Генерація музики | `api.registerMusicGenerationProvider(...)` | `google`, `minimax` |
+| Генерація відео | `api.registerVideoGenerationProvider(...)` | `qwen` |
+| Веб-отримання | `api.registerWebFetchProvider(...)` | `firecrawl` |
+| Веб-пошук | `api.registerWebSearchProvider(...)` | `google` |
+| Канал / повідомлення | `api.registerChannel(...)` | `msteams`, `matrix` |
-Плагін, який не реєструє жодної можливості, але надає хуки, інструменти або
-сервіси, є **застарілим плагіном лише з хуками**. Цей шаблон досі повністю
-підтримується.
+Plugin, який не реєструє жодної можливості, але надає хуки, інструменти або
+сервіси, є **застарілим hook-only** Plugin. Цей шаблон і далі повністю підтримується.
### Позиція щодо зовнішньої сумісності
-Модель можливостей уже інтегрована в ядро та сьогодні використовується
-вбудованими/власними плагінами, але сумісність зовнішніх плагінів усе ще
-потребує вищої планки, ніж «це експортується, отже це незмінне».
+Модель можливостей реалізована в core і вже сьогодні використовується
+bundled/native Plugin, але сумісність із зовнішніми Plugin усе ще потребує
+вищого стандарту, ніж «це експортується, отже це заморожено».
Поточні рекомендації:
-- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі хуків; вважайте це базовим рівнем сумісності
-- **нові вбудовані/власні плагіни:** надавайте перевагу явній реєстрації можливостей замість vendor-specific звернень усередину або нових рішень лише з хуками
-- **зовнішні плагіни, що переходять на реєстрацію можливостей:** це дозволено, але вважайте допоміжні поверхні, специфічні для можливостей, такими, що еволюціонують, якщо в документації контракт явно не позначено як стабільний
+- **наявні зовнішні Plugin:** зберігайте працездатність інтеграцій на основі hook;
+ вважайте це базовим рівнем сумісності
+- **нові bundled/native Plugin:** віддавайте перевагу явній реєстрації можливостей
+ замість vendor-specific доступу до внутрішніх механізмів або нових дизайнів лише з hook
+- **зовнішні Plugin, що переходять на реєстрацію можливостей:** це дозволено, але
+ допоміжні поверхні, специфічні для можливостей, слід вважати такими, що еволюціонують,
+ якщо в документації контракт не позначено явно як стабільний
Практичне правило:
-- API реєстрації можливостей — це бажаний напрям розвитку
-- застарілі хуки залишаються найбезпечнішим шляхом без порушення сумісності для зовнішніх плагінів під час переходу
-- не всі експортовані допоміжні підшляхи однаково важливі; надавайте перевагу вузькому документованому контракту, а не випадковим експортам допоміжних засобів
+- API реєстрації можливостей — це цільовий напрямок
+- застарілі hooks залишаються найбезпечнішим шляхом без порушення сумісності
+ для зовнішніх Plugin під час переходу
+- не всі експортовані допоміжні підшляхи однаково значущі; віддавайте перевагу
+ вузькому задокументованому контракту, а не випадково експортованим допоміжним елементам
-### Форми плагінів
+### Форми Plugin
-OpenClaw класифікує кожен завантажений плагін за формою на основі його
-фактичної поведінки під час реєстрації (а не лише статичних метаданих):
+OpenClaw класифікує кожен завантажений Plugin за формою на основі фактичної
+поведінки реєстрації (а не лише статичних метаданих):
- **plain-capability** -- реєструє рівно один тип можливості (наприклад,
- плагін лише провайдера, як-от `mistral`)
+ Plugin лише провайдера, як-от `mistral`)
- **hybrid-capability** -- реєструє кілька типів можливостей (наприклад,
- `openai` володіє текстовим висновком, мовленням, розумінням медіа та
+ `openai` володіє текстовою інференцією, мовленням, розумінням медіа та
генерацією зображень)
-- **hook-only** -- реєструє лише хуки (типізовані або користувацькі), без
+- **hook-only** -- реєструє лише hooks (типізовані або користувацькі), без
можливостей, інструментів, команд або сервісів
- **non-capability** -- реєструє інструменти, команди, сервіси або маршрути,
але не можливості
-Скористайтеся `openclaw plugins inspect `, щоб побачити форму плагіна та
-розподіл його можливостей. Докладніше дивіться в [довіднику CLI](/cli/plugins#inspect).
+Використовуйте `openclaw plugins inspect `, щоб побачити форму Plugin і
+розподіл можливостей. Докладніше див. [довідку CLI](/cli/plugins#inspect).
-### Застарілі хуки
+### Застарілі hooks
-Хук `before_agent_start` залишається підтримуваним як шлях сумісності для
-плагінів лише з хуками. Реальні застарілі плагіни все ще залежать від нього.
+Хук `before_agent_start` і далі підтримується як шлях сумісності для
+Plugin типу hook-only. Реальні застарілі Plugin усе ще залежать від нього.
Напрямок:
-- зберігати його працездатність
+- зберігати його працездатним
- документувати його як застарілий
-- для перевизначення моделі/провайдера надавати перевагу `before_model_resolve`
-- для модифікації запиту надавати перевагу `before_prompt_build`
-- видаляти лише після зниження реального використання та коли покриття фікстурами підтвердить безпечність міграції
+- для роботи з перевизначенням моделі/провайдера віддавати перевагу `before_model_resolve`
+- для змін підказок віддавати перевагу `before_prompt_build`
+- видаляти лише після зниження реального використання і підтвердження
+ безпечності міграції покриттям фікстур
### Сигнали сумісності
Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви
-можете побачити одну з цих позначок:
+можете побачити одну з таких позначок:
-| Сигнал | Значення |
-| ------------------------- | ------------------------------------------------------------ |
-| **config valid** | Конфігурація коректно розбирається, і плагіни успішно визначаються |
-| **compatibility advisory** | Плагін використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) |
-| **legacy warning** | Плагін використовує `before_agent_start`, який є застарілим |
-| **hard error** | Конфігурація недійсна або плагін не вдалося завантажити |
+| Сигнал | Значення |
+| -------------------------- | ------------------------------------------------------------ |
+| **config valid** | Конфігурація коректно розбирається, а Plugin успішно визначаються |
+| **compatibility advisory** | Plugin використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) |
+| **legacy warning** | Plugin використовує `before_agent_start`, який є застарілим |
+| **hard error** | Конфігурація некоректна або Plugin не вдалося завантажити |
-Ні `hook-only`, ні `before_agent_start` сьогодні не зламають ваш плагін --
-`hook-only` має рекомендаційний характер, а `before_agent_start` лише
-спричиняє попередження. Ці сигнали також відображаються в
-`openclaw status --all` і `openclaw plugins doctor`.
+Ані `hook-only`, ані `before_agent_start` сьогодні не зламають ваш Plugin --
+`hook-only` є рекомендаційним сигналом, а `before_agent_start` лише викликає
+попередження. Ці сигнали також з’являються в `openclaw status --all` і
+`openclaw plugins doctor`.
## Огляд архітектури
-Система плагінів OpenClaw має чотири шари:
+Система Plugin OpenClaw має чотири рівні:
1. **Маніфест + виявлення**
- OpenClaw знаходить кандидатів у плагіни в налаштованих шляхах, коренях
- робочих просторів, глобальних коренях розширень і вбудованих розширеннях.
- Під час виявлення спочатку зчитуються власні маніфести
- `openclaw.plugin.json` і підтримувані маніфести пакетів.
+ OpenClaw знаходить потенційні Plugin із налаштованих шляхів, коренів workspace,
+ глобальних коренів розширень і bundled extensions. Під час виявлення спочатку
+ читаються нативні маніфести `openclaw.plugin.json` та підтримувані маніфести збірок.
2. **Увімкнення + валідація**
- Ядро визначає, чи виявлений плагін увімкнено, вимкнено, заблоковано або
- вибрано для ексклюзивного слота, наприклад пам’яті.
+ Core визначає, чи знайдений Plugin увімкнено, вимкнено, заблоковано або
+ вибрано для ексклюзивного слота, такого як пам’ять.
3. **Завантаження середовища виконання**
- Власні плагіни OpenClaw завантажуються в межах процесу через jiti і
- реєструють можливості в центральному реєстрі. Сумісні пакети
- нормалізуються в записи реєстру без імпорту коду середовища виконання.
+ Нативні Plugin OpenClaw завантажуються в межах процесу через jiti і
+ реєструють можливості в центральному реєстрі. Сумісні збірки нормалізуються
+ в записи реєстру без імпорту коду середовища виконання.
4. **Використання поверхонь**
- Решта OpenClaw зчитує реєстр, щоб надавати інструменти, канали,
- налаштування провайдерів, хуки, HTTP-маршрути, команди CLI та сервіси.
+ Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування
+ провайдерів, hooks, HTTP-маршрути, CLI-команди та сервіси.
-Зокрема для CLI плагінів, виявлення кореневих команд поділяється на дві фази:
+Для CLI Plugin зокрема виявлення кореневих команд розділено на дві фази:
-- метадані під час розбору надходять із `registerCli(..., { descriptors: [...] })`
-- реальний модуль CLI плагіна може залишатися лінивим і реєструватися під час першого виклику
+- метадані на етапі розбору надходять із `registerCli(..., { descriptors: [...] })`
+- реальний модуль CLI Plugin може залишатися лінивим і реєструватися під час першого виклику
-Це дозволяє зберігати код CLI, що належить плагіну, всередині плагіна, і
-водночас дає OpenClaw змогу резервувати імена кореневих команд до початку
-розбору.
+Це дозволяє зберігати код CLI, що належить Plugin, усередині Plugin, водночас даючи OpenClaw
+можливість резервувати назви кореневих команд до початку розбору.
-Важлива межа дизайну:
+Важлива межа проєктування:
-- виявлення + валідація конфігурації мають працювати на основі **метаданих маніфесту/схеми** без виконання коду плагіна
-- власна поведінка середовища виконання походить зі шляху `register(api)` модуля плагіна
+- виявлення + валідація конфігурації мають працювати на основі **метаданих маніфесту/схеми**
+ без виконання коду Plugin
+- нативна поведінка середовища виконання походить зі шляху `register(api)` модуля Plugin
-Цей поділ дозволяє OpenClaw перевіряти конфігурацію, пояснювати відсутні/вимкнені
-плагіни та будувати підказки для UI/схеми до того, як повне середовище
-виконання стане активним.
+Цей поділ дає OpenClaw змогу перевіряти конфігурацію, пояснювати відсутні/вимкнені Plugin
+і будувати підказки для UI/схеми до повної активації середовища виконання.
-### Плагіни каналів і спільний інструмент повідомлень
+### Канальні Plugin і спільний інструмент повідомлень
-Плагінам каналів не потрібно реєструвати окремий інструмент надсилання /
-редагування / реакцій для звичайних дій у чаті. OpenClaw зберігає один спільний
-інструмент `message` у ядрі, а плагіни каналів володіють виявленням і
-виконанням, специфічними для каналу, за його межами.
+Канальним Plugin не потрібно реєструвати окремий інструмент send/edit/react для
+звичайних дій у чаті. OpenClaw зберігає один спільний інструмент `message` у core,
+а канальні Plugin володіють специфічним для каналу виявленням і виконанням за ним.
Поточна межа така:
-- ядро володіє хостом спільного інструмента `message`, підключенням до запитів,
+- core володіє хостом спільного інструмента `message`, підключенням до prompt,
обліком сесій/потоків і диспетчеризацією виконання
-- плагіни каналів володіють виявленням дій з урахуванням області видимості,
- виявленням можливостей і будь-якими фрагментами схеми, специфічними для каналу
-- плагіни каналів володіють граматикою розмов сесій, специфічною для провайдера,
- наприклад тим, як ідентифікатори розмов кодують ідентифікатори потоків або
- успадковуються від батьківських розмов
-- плагіни каналів виконують остаточну дію через свій адаптер дій
+- канальні Plugin володіють scoped-виявленням дій, виявленням можливостей і будь-якими
+ фрагментами схеми, специфічними для каналу
+- канальні Plugin володіють граматикою розмови сесії, специфічною для провайдера, наприклад
+ тим, як id розмов кодують id потоків або успадковуються від батьківських розмов
+- канальні Plugin виконують фінальну дію через свій адаптер дій
-Для плагінів каналів поверхнею SDK є
+Для канальних Plugin поверхнею SDK є
`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик
-виявлення дозволяє плагіну повернути видимі дії, можливості та внески у схему
-разом, щоб ці частини не розходилися між собою.
+виявлення дає Plugin змогу разом повертати видимі дії, можливості та внески до схеми,
+щоб ці частини не розходилися між собою.
-Ядро передає область виконання в цей крок виявлення. Важливі поля:
+Core передає scope середовища виконання в цей крок виявлення. Важливі поля містять:
- `accountId`
- `currentChannelId`
@@ -191,129 +193,125 @@ OpenClaw класифікує кожен завантажений плагін
- `agentId`
- довірений вхідний `requesterSenderId`
-Це важливо для контекстно-чутливих плагінів. Канал може приховувати або
-показувати дії з повідомленнями залежно від активного облікового запису,
-поточної кімнати/потоку/повідомлення або довіреної ідентичності запитувача без
-жорстко закодованих гілок, специфічних для каналу, в основному інструменті
-`message`.
+Це важливо для Plugin, чутливих до контексту. Канал може приховувати або показувати
+дії з повідомленнями залежно від активного облікового запису, поточної кімнати/потоку/повідомлення
+або довіреної ідентичності запитувача без жорсткого кодування специфічних для каналу розгалужень
+у core-інструменті `message`.
-Саме тому зміни маршрутизації embedded-runner усе ще залишаються роботою
-плагіна: runner відповідає за передавання поточної ідентичності чату/сесії до
-межі виявлення плагіна, щоб спільний інструмент `message` відкривав правильну
-поверхню, що належить каналу, для поточного ходу.
+Саме тому зміни маршрутизації embedded-runner і далі є роботою Plugin: runner
+відповідає за передавання поточної ідентичності чату/сесії в межу виявлення Plugin,
+щоб спільний інструмент `message` відкривав правильну поверхню, що належить каналу,
+для поточного ходу.
-Щодо допоміжних засобів виконання, які належать каналу, вбудовані плагіни мають
-зберігати середовище виконання всередині власних модулів розширення. Ядро більше
-не володіє середовищами виконання дій із повідомленнями Discord, Slack, Telegram
-чи WhatsApp у `src/agents/tools`. Ми не публікуємо окремі підшляхи
-`plugin-sdk/*-action-runtime`, і вбудовані плагіни мають імпортувати власний
-локальний код середовища виконання безпосередньо зі своїх модулів, що належать
-розширенню.
+Щодо допоміжних засобів виконання, що належать каналу, bundled Plugin мають
+зберігати runtime виконання всередині власних модулів розширення. Core більше не
+володіє runtime дій повідомлень Discord, Slack, Telegram або WhatsApp у `src/agents/tools`.
+Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, і bundled Plugin
+мають імпортувати власний локальний runtime-код безпосередньо зі своїх модулів,
+що належать розширенню.
-Та сама межа застосовується і до іменованих за провайдером швів SDK загалом:
-ядро не повинно імпортувати зручні панелі, специфічні для каналів, для Slack,
-Discord, Signal, WhatsApp або подібних розширень. Якщо ядру потрібна певна
-поведінка, воно має або споживати власну панель `api.ts` / `runtime-api.ts`
-вбудованого плагіна, або винести потребу у вузьку загальну можливість у
-спільному SDK.
+Та сама межа застосовується до іменованих SDK-seam провайдерів загалом: core не повинен
+імпортувати зручні barrels, специфічні для каналів Slack, Discord, Signal, WhatsApp
+або подібних розширень. Якщо core потрібна певна поведінка, або використовуйте
+власний barrel `api.ts` / `runtime-api.ts` bundled Plugin, або підніміть цю потребу
+до вузької узагальненої можливості в спільному SDK.
-Зокрема для опитувань існують два шляхи виконання:
+Для опитувань зокрема є два шляхи виконання:
-- `outbound.sendPoll` — це спільна базова лінія для каналів, які відповідають загальній моделі опитувань
-- `actions.handleAction("poll")` — це бажаний шлях для семантики опитувань, специфічної для каналу, або додаткових параметрів опитування
+- `outbound.sendPoll` — це спільна базова лінія для каналів, які відповідають загальній
+ моделі опитувань
+- `actions.handleAction("poll")` — це бажаний шлях для специфічної для каналу семантики
+ опитувань або додаткових параметрів опитування
-Тепер ядро відкладає спільний розбір опитувань до моменту, коли диспетчеризація
-опитування плагіна відхилить дію, щоб обробники опитувань, що належать плагіну,
-могли приймати поля опитувань, специфічні для каналу, не блокуючись спочатку
-загальним парсером опитувань.
+Тепер Core відкладає спільний розбір опитувань до моменту, коли dispatch опитування Plugin
+відхилить дію, тому обробники опитувань, що належать Plugin, можуть приймати специфічні
+для каналу поля опитування, не блокуючись спочатку узагальненим парсером опитувань.
-Повну послідовність запуску дивіться в [Конвеєрі завантаження](#load-pipeline).
+Повну послідовність запуску див. в [Конвеєр завантаження](#load-pipeline).
## Модель володіння можливостями
-OpenClaw розглядає власний плагін як межу володіння для **компанії** або
+OpenClaw розглядає нативний Plugin як межу володіння для **компанії** або
**функції**, а не як набір не пов’язаних між собою інтеграцій.
Це означає:
-- плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, що стосуються цієї компанії
-- плагін функції зазвичай має володіти всією поверхнею функції, яку він додає
-- канали мають споживати спільні можливості ядра замість того, щоб наново реалізовувати поведінку провайдера довільним чином
+- Plugin компанії зазвичай має володіти всіма поверхнями OpenClaw, що стосуються цієї компанії
+- Plugin функції зазвичай має володіти повною поверхнею функції, яку він додає
+- канали мають використовувати спільні можливості core замість того, щоб довільно
+ повторно реалізовувати поведінку провайдера
Приклади:
-- вбудований плагін `openai` володіє поведінкою провайдера моделей OpenAI, а
- також поведінкою OpenAI для мовлення + голосу в реальному часі + розуміння
- медіа + генерації зображень
-- вбудований плагін `elevenlabs` володіє поведінкою мовлення ElevenLabs
-- вбудований плагін `microsoft` володіє поведінкою мовлення Microsoft
-- вбудований плагін `google` володіє поведінкою провайдера моделей Google, а
- також поведінкою Google для розуміння медіа + генерації зображень + вебпошуку
-- вбудований плагін `firecrawl` володіє поведінкою Firecrawl для веботримання
-- вбудовані плагіни `minimax`, `mistral`, `moonshot` і `zai` володіють своїми
- серверними частинами розуміння медіа
-- вбудований плагін `qwen` володіє поведінкою текстового провайдера Qwen, а
- також поведінкою розуміння медіа та генерації відео
-- плагін `voice-call` є плагіном функції: він володіє транспортом викликів,
- інструментами, CLI, маршрутами та мостом медіапотоку Twilio, але споживає
- спільні можливості мовлення, а також транскрипції в реальному часі і голосу
- в реальному часі замість безпосереднього імпорту плагінів постачальників
+- bundled Plugin `openai` володіє поведінкою провайдера моделей OpenAI і поведінкою
+ OpenAI для мовлення + голосу в реальному часі + розуміння медіа + генерації зображень
+- bundled Plugin `elevenlabs` володіє поведінкою мовлення ElevenLabs
+- bundled Plugin `microsoft` володіє поведінкою мовлення Microsoft
+- bundled Plugin `google` володіє поведінкою провайдера моделей Google, а також
+ поведінкою Google для розуміння медіа + генерації зображень + веб-пошуку
+- bundled Plugin `firecrawl` володіє поведінкою веб-отримання Firecrawl
+- bundled Plugin `minimax`, `mistral`, `moonshot` і `zai` володіють своїми
+ бекендами розуміння медіа
+- bundled Plugin `qwen` володіє поведінкою текстового провайдера Qwen, а також
+ поведінкою розуміння медіа і генерації відео
+- Plugin `voice-call` — це Plugin функції: він володіє транспортом дзвінків, інструментами,
+ CLI, маршрутами та мостом медіапотоку Twilio, але використовує спільні можливості
+ мовлення, а також транскрипції в реальному часі й голосу в реальному часі замість
+ прямого імпорту vendor Plugin
-Бажаний кінцевий стан:
+Цільовий кінцевий стан:
-- OpenAI розміщується в одному плагіні, навіть якщо він охоплює текстові моделі, мовлення, зображення та майбутнє відео
-- інший постачальник може робити те саме для власної області поверхонь
-- канали не повинні зважати, який плагін постачальника володіє провайдером; вони споживають спільний контракт можливостей, який надає ядро
+- OpenAI розміщується в одному Plugin, навіть якщо він охоплює текстові моделі, мовлення, зображення та
+ майбутнє відео
+- інший постачальник може зробити те саме для власної зони відповідальності
+- канали не мають значення, який саме Plugin постачальника володіє провайдером; вони використовують
+ спільний контракт можливостей, який надає core
-Це ключове розрізнення:
+Ось ключова відмінність:
- **plugin** = межа володіння
-- **capability** = контракт ядра, який кілька плагінів можуть реалізовувати або споживати
+- **capability** = контракт core, який можуть реалізовувати або використовувати кілька Plugin
-Тож якщо OpenClaw додає нову область, наприклад відео, перше питання не таке:
-«який провайдер має жорстко закодувати обробку відео?» Перше питання таке:
-«який контракт можливості відео має бути в ядрі?» Щойно такий контракт
-з’являється, плагіни постачальників можуть реєструватися для нього, а плагіни
-каналів/функцій можуть його споживати.
+Тому, якщо OpenClaw додає нову область, наприклад відео, перше запитання не таке:
+«який провайдер має жорстко кодувати обробку відео?» Перше запитання таке: «який
+контракт core для можливості відео?» Щойно такий контракт з’являється, vendor Plugin
+можуть реєструватися для нього, а канальні/функціональні Plugin можуть його використовувати.
-Якщо можливості ще не існує, правильний крок зазвичай такий:
+Якщо можливість іще не існує, правильний крок зазвичай такий:
-1. визначити відсутню можливість у ядрі
-2. типізовано відкрити її через API/середовище виконання плагінів
-3. під’єднати канали/функції до цієї можливості
-4. дати плагінам постачальників зареєструвати реалізації
+1. визначити відсутню можливість у core
+2. надати її через API/runtime Plugin у типізований спосіб
+3. підключити канали/функції до цієї можливості
+4. дозволити vendor Plugin реєструвати реалізації
-Це зберігає явне володіння та водночас уникає поведінки ядра, яка залежить від
-одного постачальника або одноразового шляху коду, специфічного для плагіна.
+Це зберігає явне володіння і водночас дає змогу уникати поведінки core, яка залежить від
+одного постачальника або одноразового специфічного для Plugin шляху коду.
-### Нашарування можливостей
+### Шарування можливостей
-Використовуйте таку ментальну модель, коли вирішуєте, де має бути код:
+Використовуйте таку ментальну модель, коли визначаєте, де має розміщуватися код:
-- **рівень можливостей ядра**: спільна оркестрація, політика, резервні
- варіанти, правила злиття конфігурації, семантика доставки та типізовані
- контракти
-- **рівень плагінів постачальника**: API, автентифікація, каталоги моделей,
- синтез мовлення, генерація зображень, майбутні серверні частини для відео,
- кінцеві точки використання, специфічні для постачальника
-- **рівень плагінів каналів/функцій**: інтеграції Slack/Discord/voice-call
- тощо, які споживають можливості ядра та подають їх на своїй поверхні
+- **рівень можливостей core**: спільна оркестрація, політика, fallback, правила
+ злиття конфігурації, семантика доставки та типізовані контракти
+- **рівень vendor Plugin**: API, автентифікація, каталоги моделей, синтез мовлення,
+ генерація зображень, майбутні відеобекенди, точки обліку використання, специфічні для постачальника
+- **рівень канальних/функціональних Plugin**: інтеграції Slack/Discord/voice-call тощо,
+ які використовують можливості core і представляють їх на своїй поверхні
Наприклад, TTS має таку форму:
-- ядро володіє політикою TTS під час відповіді, порядком резервних варіантів, налаштуваннями та доставкою в канал
+- core володіє політикою TTS під час відповіді, порядком fallback, налаштуваннями та доставкою каналом
- `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу
-- `voice-call` споживає допоміжний засіб середовища виконання TTS для телефонії
+- `voice-call` використовує допоміжний runtime TTS для телефонії
-Для майбутніх можливостей слід надавати перевагу саме такому шаблону.
+Тому самому шаблону слід віддавати перевагу і для майбутніх можливостей.
-### Приклад плагіна компанії з кількома можливостями
+### Приклад Plugin компанії з кількома можливостями
-Плагін компанії має виглядати цілісно ззовні. Якщо OpenClaw має спільні
-контракти для моделей, мовлення, транскрипції в реальному часі, голосу в
-реальному часі, розуміння медіа, генерації зображень, генерації відео,
-веботримання та вебпошуку, постачальник може володіти всіма своїми поверхнями
-в одному місці:
+Plugin компанії зовні має сприйматися цілісно. Якщо OpenClaw має спільні
+контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа,
+генерації зображень, генерації відео, веб-отримання та веб-пошуку,
+постачальник може володіти всіма своїми поверхнями в одному місці:
```ts
import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
@@ -369,244 +367,238 @@ export default plugin;
Важливі не точні назви допоміжних засобів. Важлива форма:
-- один плагін володіє поверхнею постачальника
-- ядро, як і раніше, володіє контрактами можливостей
-- канали та плагіни функцій споживають допоміжні засоби `api.runtime.*`, а не код постачальника
-- тести контрактів можуть підтвердити, що плагін зареєстрував можливості, якими, за його твердженням, він володіє
+- один Plugin володіє поверхнею постачальника
+- core і далі володіє контрактами можливостей
+- канальні та функціональні Plugin використовують допоміжні засоби `api.runtime.*`, а не vendor-код
+- контрактні тести можуть перевіряти, що Plugin зареєстрував ті можливості,
+ якими, за його твердженням, володіє
### Приклад можливості: розуміння відео
OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну
-можливість. Тут застосовується та сама модель володіння:
+можливість. Там застосовується та сама модель володіння:
-1. ядро визначає контракт розуміння медіа
-2. плагіни постачальників реєструють `describeImage`, `transcribeAudio` і
- `describeVideo`, де це доречно
-3. канали та плагіни функцій споживають спільну поведінку ядра замість
- прямого підключення до коду постачальника
+1. core визначає контракт media-understanding
+2. vendor Plugin реєструють `describeImage`, `transcribeAudio` і
+ `describeVideo`, де це застосовно
+3. канальні та функціональні Plugin використовують спільну поведінку core замість
+ прямого підключення до vendor-коду
-Це запобігає вбудовуванню в ядро припущень одного провайдера щодо відео.
-Плагін володіє поверхнею постачальника; ядро володіє контрактом можливості та
-поведінкою резервних варіантів.
+Це дає змогу уникнути вбудовування припущень одного провайдера щодо відео в core. Plugin володіє
+поверхнею постачальника; core володіє контрактом можливості та поведінкою fallback.
-Генерація відео вже використовує таку саму послідовність: ядро володіє
-типізованим контрактом можливості та допоміжним засобом середовища виконання, а
-плагіни постачальників реєструють реалізації
-`api.registerVideoGenerationProvider(...)` для нього.
+Генерація відео вже використовує ту саму послідовність: core володіє типізованим
+контрактом можливості та допоміжним runtime-засобом, а vendor Plugin реєструють
+реалізації `api.registerVideoGenerationProvider(...)` для цієї можливості.
-Потрібен конкретний контрольний список розгортання? Дивіться
+Потрібен конкретний контрольний список розгортання? Див.
[Практичний посібник із можливостей](/uk/plugins/architecture).
-## Контракти та забезпечення виконання
+## Контракти та контроль
-Поверхня API плагінів навмисно типізована та централізована в
+Поверхня API Plugin навмисно типізована й централізована в
`OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та
-допоміжні засоби середовища виконання, на які може спиратися плагін.
+допоміжні засоби runtime, на які може покладатися Plugin.
Чому це важливо:
-- автори плагінів отримують один стабільний внутрішній стандарт
-- ядро може відхиляти дубльоване володіння, наприклад коли два плагіни
- реєструють один і той самий id провайдера
-- під час запуску можна показати діагностику з чіткими діями для некоректної реєстрації
-- тести контрактів можуть забезпечувати володіння вбудованими плагінами та запобігати тихому дрейфу
+- автори Plugin отримують один стабільний внутрішній стандарт
+- core може відхиляти дубльоване володіння, наприклад коли два Plugin реєструють той самий
+ id провайдера
+- під час запуску можна показувати практичні діагностичні повідомлення для некоректної реєстрації
+- контрактні тести можуть забезпечувати дотримання володіння bundled Plugin і запобігати тихому дрейфу
-Є два рівні забезпечення виконання:
+Є два рівні контролю:
-1. **забезпечення виконання реєстрації під час виконання**
- Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Приклади:
- дубльовані id провайдерів, дубльовані id провайдерів мовлення та
- некоректні реєстрації створюють діагностику плагіна замість невизначеної поведінки.
-2. **тести контрактів**
- Вбудовані плагіни фіксуються в реєстрах контрактів під час тестових запусків,
- щоб OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для
- провайдерів моделей, провайдерів мовлення, провайдерів вебпошуку та володіння реєстрацією вбудованих плагінів.
+1. **контроль реєстрації під час виконання**
+ Реєстр Plugin перевіряє реєстрації під час завантаження Plugin. Приклади:
+ дублікати id провайдерів, дублікати id провайдерів мовлення та некоректні
+ реєстрації породжують діагностику Plugin замість невизначеної поведінки.
+2. **контрактні тести**
+ Bundled Plugin фіксуються в контрактних реєстрах під час запуску тестів, щоб
+ OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для
+ провайдерів моделей, провайдерів мовлення, провайдерів веб-пошуку та володіння
+ реєстрацією bundled Plugin.
-Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який плагін якою
-поверхнею володіє. Це дозволяє ядру й каналам безшовно компонуватися, оскільки
-володіння оголошене, типізоване й придатне до тестування, а не неявне.
+Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який Plugin якою
+поверхнею володіє. Це дає core і каналам змогу безшовно компонуватися, бо володіння
+задеклароване, типізоване та придатне для тестування, а не неявне.
### Що має входити до контракту
-Хороші контракти плагінів:
+Хороші контракти Plugin є:
-- типізовані
-- невеликі
-- специфічні для можливості
-- належать ядру
-- повторно використовуються кількома плагінами
-- споживаються каналами/функціями без знання про постачальника
+- типізованими
+- невеликими
+- специфічними для можливості
+- такими, що належать core
+- придатними до повторного використання кількома Plugin
+- придатними до використання каналами/функціями без знання про постачальника
-Погані контракти плагінів:
+Погані контракти Plugin — це:
-- політика, специфічна для постачальника, прихована в ядрі
-- одноразові лазівки для плагіна, які обходять реєстр
+- політика, специфічна для постачальника, прихована в core
+- одноразові лазівки для Plugin, які обходять реєстр
- код каналу, що напряму звертається до реалізації постачальника
-- довільні об’єкти середовища виконання, які не є частиною `OpenClawPluginApi` або `api.runtime`
+- ad hoc runtime-об’єкти, які не є частиною `OpenClawPluginApi` або
+ `api.runtime`
-Якщо є сумніви, підніміть рівень абстракції: спочатку визначте можливість, а
-потім дайте плагінам підключатися до неї.
+Якщо сумніваєтеся, підніміть рівень абстракції: спочатку визначте можливість, а вже потім
+дозвольте Plugin підключатися до неї.
## Модель виконання
-Власні плагіни OpenClaw працюють **у межах процесу** разом із Gateway. Вони не
-ізольовані. Завантажений власний плагін має ту саму межу довіри на рівні
-процесу, що й код ядра.
+Нативні Plugin OpenClaw виконуються **в межах процесу** разом із Gateway. Вони не
+ізольовані в пісочниці. Завантажений нативний Plugin має ту саму межу довіри на рівні процесу, що й
+код core.
Наслідки:
-- власний плагін може реєструвати інструменти, мережеві обробники, хуки та сервіси
-- помилка у власному плагіні може призвести до збою або дестабілізації gateway
-- зловмисний власний плагін еквівалентний довільному виконанню коду всередині процесу OpenClaw
+- нативний Plugin може реєструвати інструменти, мережеві обробники, hooks і сервіси
+- помилка в нативному Plugin може аварійно завершити роботу gateway або дестабілізувати його
+- зловмисний нативний Plugin еквівалентний довільному виконанню коду в процесі OpenClaw
-Сумісні пакети за замовчуванням безпечніші, оскільки OpenClaw наразі розглядає
-їх як пакети метаданих/контенту. У поточних випусках це здебільшого означає
-вбудовані Skills.
+Сумісні збірки за замовчуванням безпечніші, оскільки наразі OpenClaw розглядає їх
+як пакети метаданих/вмісту. У поточних випусках це переважно означає bundled
+Skills.
-Для невбудованих плагінів використовуйте allowlist-и та явні шляхи
-встановлення/завантаження. Розглядайте плагіни робочого простору як код для
-етапу розробки, а не як виробничі значення за замовчуванням.
+Для небандлованих Plugin використовуйте allowlist і явні шляхи встановлення/завантаження. Розглядайте
+workspace Plugin як код для етапу розробки, а не як виробничі типові значення.
-Для імен пакетів вбудованого робочого простору тримайте id плагіна прив’язаним
-до імені npm: за замовчуванням `@openclaw/` або зі схваленим типізованим
-суфіксом, таким як `-provider`, `-plugin`, `-speech`, `-sandbox` або
-`-media-understanding`, коли пакет навмисно відкриває вужчу роль плагіна.
+Для bundled назв пакетів workspace прив’язуйте id Plugin до імені npm:
+`@openclaw/` за замовчуванням або затверджений типізований суфікс, такий як
+`-provider`, `-plugin`, `-speech`, `-sandbox` чи `-media-understanding`, якщо
+пакет навмисно відкриває вужчу роль Plugin.
Важлива примітка щодо довіри:
-- `plugins.allow` довіряє **id плагінів**, а не походженню джерела.
-- Плагін робочого простору з тим самим id, що й у вбудованого плагіна,
- навмисно затіняє вбудовану копію, коли цей плагін робочого простору увімкнено/додано до allowlist.
-- Це нормально та корисно для локальної розробки, тестування виправлень і hotfix-ів.
+- `plugins.allow` довіряє **id Plugin**, а не походженню джерела.
+- Workspace Plugin з тим самим id, що й bundled Plugin, навмисно затіняє
+ bundled копію, коли такий workspace Plugin увімкнено/додано до allowlist.
+- Це нормально й корисно для локальної розробки, тестування патчів і hotfix.
## Межа експорту
-OpenClaw експортує можливості, а не зручні реалізації.
+OpenClaw експортує можливості, а не зручні засоби реалізації.
-Зберігайте реєстрацію можливостей публічною. Скорочуйте експорти допоміжних
-засобів, які не є контрактними:
+Зберігайте публічною реєстрацію можливостей. Скорочуйте експорти допоміжних засобів, що не є контрактами:
-- підшляхи допоміжних засобів, специфічні для вбудованого плагіна
-- підшляхи інфраструктури середовища виконання, не призначені як публічний API
-- зручні допоміжні засоби, специфічні для постачальника
-- допоміжні засоби налаштування/онбордингу, які є деталями реалізації
+- підшляхи допоміжних засобів, специфічних для bundled Plugin
+- підшляхи plumbing runtime, які не призначені як публічний API
+- зручні засоби, специфічні для постачальника
+- допоміжні засоби setup/onboarding, які є деталями реалізації
-Деякі підшляхи допоміжних засобів вбудованих плагінів усе ще залишаються в
-згенерованій карті експорту SDK для сумісності та супроводу вбудованих
-плагінів. Поточні приклади включають `plugin-sdk/feishu`,
-`plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і
-кілька швів `plugin-sdk/matrix*`. Розглядайте їх як зарезервовані експорти
-деталей реалізації, а не як рекомендований шаблон SDK для нових сторонніх
-плагінів.
+Деякі підшляхи допоміжних засобів bundled Plugin іще залишаються в згенерованій карті
+експорту SDK з міркувань сумісності та для супроводу bundled Plugin. Поточні приклади:
+`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
+`plugin-sdk/zalo-setup` і кілька seam `plugin-sdk/matrix*`. Розглядайте їх як
+зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для
+нових сторонніх Plugin.
## Конвеєр завантаження
-Під час запуску OpenClaw приблизно робить таке:
+Під час запуску OpenClaw приблизно виконує таке:
-1. виявляє корені кандидатів у плагіни
-2. зчитує власні маніфести або маніфести сумісних пакетів і метадані пакетів
+1. виявляє корені потенційних Plugin
+2. читає нативні маніфести або маніфести сумісних збірок і метадані пакетів
3. відхиляє небезпечних кандидатів
-4. нормалізує конфігурацію плагінів (`plugins.enabled`, `allow`, `deny`, `entries`,
+4. нормалізує конфігурацію Plugin (`plugins.enabled`, `allow`, `deny`, `entries`,
`slots`, `load.paths`)
5. визначає стан увімкнення для кожного кандидата
-6. завантажує увімкнені власні модулі через jiti
-7. викликає власні хуки `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру плагінів
-8. відкриває реєстр для команд/поверхонь середовища виконання
+6. завантажує увімкнені нативні модулі через jiti
+7. викликає нативні hooks `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру Plugin
+8. відкриває реєстр для поверхонь команд/runtime
-`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів надавайте перевагу `register`.
+`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що доступно (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі bundled Plugin використовують `register`; для нових Plugin віддавайте перевагу `register`.
-Перевірки безпеки відбуваються **до** виконання середовища виконання. Кандидати
-блокуються, якщо точка входу виходить за межі кореня плагіна, шлях доступний
-для запису всім користувачам або володіння шляхом виглядає підозрілим для
-невбудованих плагінів.
+Перевірки безпеки відбуваються **до** виконання runtime. Кандидати блокуються,
+коли точка входу виходить за межі кореня Plugin, шлях доступний для запису всім, або
+для небандлованих Plugin підозріло виглядає володіння шляхом.
-### Поведінка з пріоритетом маніфесту
+### Поведінка manifest-first
Маніфест — це джерело істини для control plane. OpenClaw використовує його, щоб:
-- ідентифікувати плагін
-- виявляти оголошені канали/Skills/схему конфігурації або можливості пакетів
+- ідентифікувати Plugin
+- виявляти оголошені канали/Skills/схему конфігурації або можливості збірки
- перевіряти `plugins.entries..config`
-- доповнювати мітки/заповнювачі Control UI
+- доповнювати підписи/плейсхолдери в Control UI
- показувати метадані встановлення/каталогу
-- зберігати дешеві дескриптори активації та налаштування без завантаження середовища виконання плагіна
+- зберігати недорогі дескриптори активації та setup без завантаження runtime Plugin
-Для власних плагінів модуль середовища виконання є частиною data plane. Він
-реєструє фактичну поведінку, таку як хуки, інструменти, команди або потоки
-провайдерів.
+Для нативних Plugin модуль runtime є частиною data plane. Він реєструє
+фактичну поведінку, таку як hooks, інструменти, команди або потоки провайдерів.
Необов’язкові блоки маніфесту `activation` і `setup` залишаються в control plane.
-Це дескриптори лише з метаданими для планування активації та виявлення
-налаштування; вони не замінюють реєстрацію середовища виконання,
-`register(...)` або `setupEntry`.
-Перший споживач активації тепер використовує підказки команд із маніфесту, щоб
-звузити завантаження плагінів CLI, коли відома основна команда, замість того,
-щоб завжди наперед завантажувати кожен плагін із підтримкою CLI.
+Це лише metadata-descriptor для планування активації та виявлення setup;
+вони не замінюють реєстрацію runtime, `register(...)` або `setupEntry`.
+Перші живі споживачі активації тепер використовують підказки команд і провайдерів із маніфесту,
+щоб звузити завантаження Plugin до ширшої матеріалізації реєстру:
-Виявлення налаштування тепер надає перевагу id, що належать дескрипторам, як-от
-`setup.providers` і `setup.cliBackends`, щоб звузити коло кандидатів у плагіни,
-перш ніж повертатися до `setup-api` для плагінів, яким усе ще потрібні хуки
-середовища виконання під час налаштування. Якщо більше ніж один виявлений
-плагін заявляє про один і той самий нормалізований id провайдера налаштування
-або серверної частини CLI, пошук налаштування відмовляється від неоднозначного
-власника замість того, щоб покладатися на порядок виявлення.
+- завантаження CLI звужується до Plugin, які володіють запитаною основною командою
+- явне визначення setup/runtime провайдера звужується до Plugin, які володіють
+ запитаним id провайдера
+
+Виявлення setup тепер надає перевагу id, що належать descriptor, таким як `setup.providers` і
+`setup.cliBackends`, щоб звузити коло Plugin-кандидатів до переходу на
+`setup-api` для Plugin, яким усе ще потрібні runtime hooks на етапі setup. Якщо більше ніж
+один знайдений Plugin заявляє про той самий нормалізований id провайдера setup або CLI backend,
+пошук setup відхиляє неоднозначного власника замість того, щоб покладатися на порядок виявлення.
### Що кешує завантажувач
-OpenClaw зберігає короткоживучі кеші в межах процесу для:
+OpenClaw зберігає короткочасні кеші в межах процесу для:
- результатів виявлення
- даних реєстру маніфестів
-- завантажених реєстрів плагінів
+- реєстрів завантажених Plugin
-Ці кеші зменшують навантаження від імпульсних запусків і повторних команд. Їх
-можна безпечно сприймати як короткоживучі кеші продуктивності, а не як
-постійне сховище.
+Ці кеші зменшують пікове навантаження під час запуску та витрати на повторні команди. Їх безпечно
+сприймати як короткочасні кеші продуктивності, а не як постійне сховище.
Примітка щодо продуктивності:
-- Установіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або
+- Встановіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або
`OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, щоб вимкнути ці кеші.
-- Налаштовуйте вікна кешування за допомогою `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і
+- Налаштовуйте вікна кешу за допомогою `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і
`OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`.
## Модель реєстру
-Завантажені плагіни не змінюють напряму довільні глобальні об’єкти ядра. Вони
-реєструються в центральному реєстрі плагінів.
+Завантажені Plugin не змінюють напряму довільні глобальні об’єкти core. Вони реєструються
+в центральному реєстрі Plugin.
Реєстр відстежує:
-- записи плагінів (ідентичність, джерело, походження, стан, діагностика)
+- записи Plugin (ідентичність, джерело, походження, статус, діагностика)
- інструменти
-- застарілі хуки та типізовані хуки
+- застарілі hooks і типізовані hooks
- канали
- провайдери
- обробники Gateway RPC
- HTTP-маршрути
- реєстратори CLI
- фонові сервіси
-- команди, що належать плагінам
+- команди, що належать Plugin
-Потім функції ядра зчитують дані з цього реєстру замість безпосереднього
-звернення до модулів плагінів. Це зберігає завантаження односпрямованим:
+Потім функції core читають із цього реєстру замість прямої взаємодії з модулями Plugin.
+Це зберігає односпрямованість завантаження:
-- модуль плагіна -> реєстрація в реєстрі
-- середовище виконання ядра -> споживання реєстру
+- модуль Plugin -> реєстрація в реєстрі
+- runtime core -> споживання реєстру
-Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь
-ядра потрібна лише одна точка інтеграції: «зчитати реєстр», а не
-«створити спеціальний випадок для кожного модуля плагіна».
+Це розділення важливе для супроводу. Воно означає, що більшості поверхонь core
+потрібна лише одна точка інтеграції: «читати реєстр», а не «додавати окрему
+спеціальну обробку для кожного модуля Plugin».
-## Колбеки прив’язування розмов
+## Зворотні виклики прив’язки розмови
-Плагіни, які прив’язують розмову, можуть реагувати, коли погодження
-врегульовано.
+Plugin, які прив’язують розмову, можуть реагувати, коли рішення щодо схвалення буде прийнято.
-Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек
-після схвалення або відхилення запиту на прив’язування:
+Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик
+після схвалення або відхилення запиту на прив’язку:
```ts
export default {
@@ -626,29 +618,28 @@ export default {
};
```
-Поля корисного навантаження колбека:
+Поля корисного навантаження зворотного виклику:
- `status`: `"approved"` або `"denied"`
- `decision`: `"allow-once"`, `"allow-always"` або `"deny"`
-- `binding`: визначене прив’язування для схвалених запитів
-- `request`: підсумок початкового запиту, підказка від’єднання, id відправника
- та метадані розмови
+- `binding`: визначена прив’язка для схвалених запитів
+- `request`: зведення початкового запиту, підказка від’єднання, id відправника та
+ метадані розмови
-Цей колбек призначений лише для сповіщення. Він не змінює того, кому дозволено
-прив’язувати розмову, і виконується після завершення обробки схвалення ядром.
+Цей зворотний виклик призначений лише для сповіщення. Він не змінює, кому
+дозволено прив’язувати розмову, і виконується після завершення обробки схвалення в core.
## Хуки середовища виконання провайдера
-Плагіни провайдерів тепер мають два шари:
+Plugin провайдерів тепер мають два рівні:
-- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-автентифікації провайдера
- до завантаження середовища виконання, `providerAuthAliases` для варіантів
- провайдера, які використовують спільну автентифікацію, `channelEnvVars` для
- дешевого пошуку env/налаштування каналу до завантаження середовища виконання,
- а також `providerAuthChoices` для дешевих міток онбордингу/вибору
- автентифікації та метаданих прапорців CLI до завантаження середовища виконання
-- хуки під час налаштування конфігурації: `catalog` / застарілий `discovery` та `applyConfigDefaults`
-- хуки середовища виконання: `normalizeModelId`, `normalizeTransport`,
+- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-auth провайдера
+ до завантаження runtime, `providerAuthAliases` для варіантів провайдера, які використовують
+ спільну автентифікацію, `channelEnvVars` для дешевого пошуку env/setup каналу до
+ завантаження runtime, а також `providerAuthChoices` для дешевих міток onboarding/вибору автентифікації та
+ метаданих CLI-прапорців до завантаження runtime
+- hooks часу конфігурації: `catalog` / застарілий `discovery` плюс `applyConfigDefaults`
+- hooks runtime: `normalizeModelId`, `normalizeTransport`,
`normalizeConfig`,
`applyNativeStreamingUsageCompat`, `resolveConfigApiKey`,
`resolveSyntheticAuth`, `resolveExternalAuthProfiles`,
@@ -668,96 +659,88 @@ export default {
`buildReplayPolicy`,
`sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected`
-OpenClaw, як і раніше, володіє загальним циклом агента, перемиканням на
-резервний варіант, обробкою транскриптів і політикою інструментів. Ці хуки є
-поверхнею розширення для поведінки, специфічної для провайдера, без потреби в
-повністю власному транспорті висновку.
+OpenClaw і далі володіє загальним циклом агента, failover, обробкою транскриптів і
+політикою інструментів. Ці hooks є поверхнею розширення для поведінки, специфічної для провайдера, без
+потреби в повністю власному транспорті інференції.
-Використовуйте `providerAuthEnvVars` у маніфесті, коли провайдер має облікові
-дані на основі env, які загальні шляхи автентифікації/статусу/вибору моделі
-повинні бачити без завантаження середовища виконання плагіна. Використовуйте
-`providerAuthAliases` у маніфесті, коли один id провайдера має повторно
-використовувати env-змінні, профілі автентифікації, автентифікацію на основі
-конфігурації та варіант онбордингу API-ключа іншого id провайдера.
-Використовуйте `providerAuthChoices` у маніфесті, коли поверхні CLI для
-онбордингу/вибору автентифікації мають знати id варіанта провайдера, мітки
-груп і просту схему автентифікації з одним прапорцем без завантаження
-середовища виконання провайдера. Зберігайте `envVars` у середовищі виконання
-провайдера для підказок для операторів, таких як мітки онбордингу або змінні
+Використовуйте маніфест `providerAuthEnvVars`, коли провайдер має облікові дані на основі env,
+які загальні шляхи auth/status/model-picker мають бачити без завантаження runtime Plugin.
+Використовуйте маніфест `providerAuthAliases`, коли один id провайдера має повторно використовувати
+env-змінні, профілі автентифікації, автентифікацію на основі конфігурації та вибір onboarding API-key
+іншого id провайдера. Використовуйте маніфест `providerAuthChoices`, коли поверхні CLI onboarding/вибору автентифікації
+мають знати id вибору провайдера, мітки груп і просту прив’язку автентифікації одним прапорцем
+без завантаження runtime провайдера. Зберігайте runtime `envVars` провайдера для
+підказок, орієнтованих на операторів, таких як мітки onboarding або змінні
налаштування OAuth client-id/client-secret.
-Використовуйте `channelEnvVars` у маніфесті, коли канал має автентифікацію або
-налаштування, керовані через env, які загальний резервний механізм shell-env,
-перевірки config/status або підказки налаштування повинні бачити без
-завантаження середовища виконання каналу.
+Використовуйте маніфест `channelEnvVars`, коли канал має автентифікацію або setup, керовані env,
+які загальний shell-env fallback, перевірки config/status або підказки setup мають бачити
+без завантаження runtime каналу.
-### Порядок хуків і використання
+### Порядок hooks і їх використання
-Для плагінів моделі/провайдера OpenClaw викликає хуки приблизно в такому
-порядку.
-Стовпець «Коли використовувати» — це короткий посібник для прийняття рішень.
+Для Plugin моделей/провайдерів OpenClaw викликає hooks приблизно в такому порядку.
+Стовпець «Коли використовувати» є коротким посібником для вибору.
-| # | Хук | Що він робить | Коли використовувати |
-| --- | --------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або базовими значеннями `base URL` |
-| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації за замовчуванням, що належать провайдеру, під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму автентифікації, env або семантики сімейства моделей провайдера |
-| -- | _(built-in model lookup)_ | OpenClaw спочатку намагається використати звичайний шлях через реєстр/каталог | _(не є хуком плагіна)_ |
-| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми id моделей перед пошуком | Провайдер володіє очищенням псевдонімів до канонічного визначення моделі |
-| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` для сімейства провайдера перед загальним складанням моделі | Провайдер володіє очищенням транспорту для власних id провайдерів у межах того самого сімейства транспорту |
-| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням середовища виконання/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із плагіном; вбудовані допоміжні засоби сімейства Google також страхують підтримувані записи конфігурації Google |
-| 6 | `applyNativeStreamingUsageCompat` | Застосовує переписування сумісності використання нативного потокового режиму до провайдерів конфігурації | Провайдеру потрібні виправлення метаданих використання нативного потокового режиму, що залежать від кінцевої точки |
-| 7 | `resolveConfigApiKey` | Визначає автентифікацію env-marker для провайдерів конфігурації до завантаження автентифікації середовища виконання | Провайдер має власне визначення API-ключа env-marker; `amazon-bedrock` також має тут вбудований резолвер AWS env-marker |
-| 8 | `resolveSyntheticAuth` | Виводить локальну/self-hosted або засновану на конфігурації автентифікацію без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних |
-| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, що належать провайдеру; значення `persistence` за замовчуванням — `runtime-only` для облікових даних, що належать CLI/застосунку | Провайдер повторно використовує облікові дані зовнішньої автентифікації без збереження скопійованих refresh token-ів |
-| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілю порівняно з автентифікацією на основі env/конфігурації | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет |
-| 11 | `resolveDynamicModel` | Синхронний резервний варіант для id моделей, що належать провайдеру, яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream id моделей |
-| 12 | `prepareDynamicModel` | Асинхронний розігрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id |
-| 13 | `normalizeResolvedModel` | Остаточне переписування до того, як embedded runner використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра |
-| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для моделей постачальника за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспортах, не перехоплюючи контроль над провайдером |
-| 15 | `capabilities` | Метадані транскриптів/інструментів, що належать провайдеру й використовуються спільною логікою ядра | Провайдеру потрібні особливості транскриптів/сімейства провайдерів |
-| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить embedded runner | Провайдеру потрібне очищення схем для сімейства транспорту |
-| 17 | `inspectToolSchemas` | Виводить діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче мати попередження про ключові слова, не навчаючи ядро правилам, специфічним для провайдера |
-| 18 | `resolveReasoningOutputMode` | Вибирає нативний або тегований контракт виводу reasoning | Провайдеру потрібен тегований reasoning/кінцевий вивід замість нативних полів |
-| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного провайдера |
-| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним транспортом | Провайдеру потрібен власний wire protocol, а не просто обгортка |
-| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності заголовків/тіла запиту/моделі без власного транспорту |
-| 22 | `resolveTransportTurnState` | Додає нативні заголовки транспорту на хід або метадані | Провайдер хоче, щоб загальні транспорти надсилали нативну для провайдера ідентичність ходу |
-| 23 | `resolveWebSocketSessionPolicy` | Додає нативні заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику резервного варіанта |
-| 24 | `formatApiKey` | Форматер профілю автентифікації: збережений профіль стає рядком `apiKey` середовища виконання | Провайдер зберігає додаткові метадані автентифікації і потребує власної форми токена середовища виконання |
-| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для власних кінцевих точок оновлення або політики збоїв оновлення | Провайдер не відповідає спільним refresher-ам `pi-ai` |
-| 26 | `buildAuthDoctorHint` | Підказка виправлення, що додається, коли оновлення OAuth завершується з помилкою | Провайдеру потрібні власні рекомендації щодо відновлення автентифікації після помилки оновлення |
-| 27 | `matchesContextOverflowError` | Засіб зіставлення переповнення контекстного вікна, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики не виявлять |
-| 28 | `classifyFailoverReason` | Класифікація причин перемикання на резервний варіант, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/перевантаженням тощо |
-| 29 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul-провайдерів | Провайдеру потрібне обмеження TTL кешу, специфічне для проксі |
-| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення про відновлення після відсутності автентифікації | Провайдеру потрібна власна підказка відновлення після відсутності автентифікації |
-| 31 | `suppressBuiltInModel` | Приховування застарілої upstream-моделі плюс необов’язкова підказка про помилку для користувача | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх підказкою постачальника |
-| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, що додаються після виявлення | Провайдеру потрібні синтетичні рядки прямої сумісності в майбутньому в `models list` і засобах вибору |
-| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для провайдерів із двійковим thinking | Провайдер відкриває лише двійковий режим thinking увімк./вимк. |
-| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для підмножини моделей |
-| 35 | `resolveDefaultThinkingLevel` | Рівень `/think` за замовчуванням для конкретного сімейства моделей | Провайдер володіє політикою `/think` за замовчуванням для сімейства моделей |
-| 36 | `isModernModelRef` | Засіб зіставлення сучасної моделі для фільтрів live-профілів і вибору smoke | Провайдер володіє зіставленням бажаної моделі для live/smoke |
-| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед висновком | Провайдеру потрібен обмін токенів або короткоживучі облікові дані запиту |
-| 38 | `resolveUsageAuth` | Визначає облікові дані використання/білінгу для `/usage` та пов’язаних поверхонь статусу | Провайдеру потрібен власний розбір токена використання/квоти або інші облікові дані використання |
-| 39 | `fetchUsageSnapshot` | Отримує та нормалізує знімки використання/квоти, специфічні для провайдера, після визначення автентифікації | Провайдеру потрібна кінцева точка використання або парсер корисного навантаження, специфічні для провайдера |
-| 40 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті має належати плагіну провайдера |
-| 41 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна власна політика транскрипту (наприклад, видалення блоків thinking) |
-| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні переписування replay, специфічні для провайдера, понад спільні допоміжні засоби компакції |
-| 43 | `validateReplayTurns` | Виконує остаточну перевірку або зміну форми ходів replay перед embedded runner | Транспорту провайдера потрібна суворіша перевірка ходів після загального очищення |
-| 44 | `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.` перед визначенням runtime/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із Plugin; допоміжні засоби bundled сімейства Google також підстраховують підтримувані записи конфігурації Google |
+| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування використання нативного streaming до конфігурації провайдерів | Провайдеру потрібні виправлення метаданих використання нативного streaming, що залежать від endpoint |
+| 7 | `resolveConfigApiKey` | Визначає env-marker-автентифікацію для конфігураційних провайдерів до завантаження runtime-auth | Провайдер має визначення API-key через env-marker, що належить провайдеру; `amazon-bedrock` також має тут вбудований AWS env-marker resolver |
+| 8 | `resolveSyntheticAuth` | Відкриває локальну/self-hosted або засновану на конфігурації автентифікацію без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних |
+| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, що належать провайдеру; типове значення `persistence` — `runtime-only` для облікових даних, що належать CLI/app | Провайдер повторно використовує зовнішні облікові дані автентифікації без збереження скопійованих refresh token |
+| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілю порівняно з env-/config-based автентифікацією | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет |
+| 11 | `resolveDynamicModel` | Синхронний fallback для id моделей, що належать провайдеру, але ще відсутні в локальному реєстрі | Провайдер приймає довільні upstream id моделей |
+| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id |
+| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як embedded runner використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт core |
+| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для vendor-моделей за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе володіння провайдером |
+| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру і використовуються спільною логікою core | Провайдеру потрібні особливості транскрипту/сімейства провайдера |
+| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить embedded runner | Провайдеру потрібне очищення схем для сімейства транспорту |
+| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження щодо ключових слів, не навчаючи core специфічних для провайдера правил |
+| 18 | `resolveReasoningOutputMode` | Вибирає контракт вихідних даних reasoning: native чи tagged | Провайдеру потрібен tagged reasoning/final output замість нативних полів |
+| 19 | `prepareExtraParams` | Нормалізація параметрів запиту до застосування загальних обгорток параметрів stream | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера |
+| 20 | `createStreamFn` | Повністю замінює звичайний шлях stream власним транспортом | Провайдеру потрібен власний wire protocol, а не просто обгортка |
+| 21 | `wrapStreamFn` | Обгортка stream після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності заголовків/тіла запиту/моделі без власного транспорту |
+| 22 | `resolveTransportTurnState` | Додає нативні заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали нативну для провайдера ідентичність ходу |
+| 23 | `resolveWebSocketSessionPolicy` | Додає нативні заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або fallback-політику |
+| 24 | `formatApiKey` | Форматувач профілю автентифікації: збережений профіль стає рядком runtime `apiKey` | Провайдер зберігає додаткові метадані автентифікації та потребує власної форми runtime-токена |
+| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для власних endpoint оновлення або політики помилок оновлення | Провайдер не відповідає спільним засобам оновлення `pi-ai` |
+| 26 | `buildAuthDoctorHint` | Підказка виправлення, яка додається при збої оновлення OAuth | Провайдеру потрібні власні рекомендації з відновлення автентифікації після помилки оновлення |
+| 27 | `matchesContextOverflowError` | Засіб зіставлення переповнення контекстного вікна, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики не виявлять |
+| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо |
+| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для proxy |
+| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення при відсутній автентифікації | Провайдеру потрібна власна підказка відновлення при відсутній автентифікації |
+| 31 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей плюс необов’язкова підказка про помилку для користувача | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх vendor-підказкою |
+| 32 | `augmentModelCatalog` | Синтетичні/остаточні рядки каталогу, що додаються після виявлення | Провайдеру потрібні синтетичні рядки forward-compat у `models list` і засобах вибору |
+| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для провайдерів із binary-thinking | Провайдер підтримує лише двійкове вмикання/вимикання thinking |
+| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для окремих моделей | Провайдер хоче підтримку `xhigh` лише для частини моделей |
+| 35 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для конкретного сімейства моделей | Провайдер володіє типовою політикою `/think` для сімейства моделей |
+| 36 | `isModernModelRef` | Засіб зіставлення modern-model для фільтрів live-профілів і вибору smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke |
+| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime-токен/ключ безпосередньо перед інференцією | Провайдеру потрібен обмін токена або короткоживучі облікові дані для запиту |
+| 38 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` і пов’язаних поверхонь статусу | Провайдеру потрібен власний розбір токенів usage/quota або інші облікові дані для usage |
+| 39 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для провайдера знімки usage/quota після визначення автентифікації | Провайдеру потрібен специфічний для провайдера endpoint usage або парсер корисного навантаження |
+| 40 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті має належати Plugin провайдера |
+| 41 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна власна політика транскрипту (наприклад, видалення блоків thinking) |
+| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні специфічні для провайдера переписування replay понад спільні допоміжні засоби Compaction |
+| 43 | `validateReplayTurns` | Остаточна перевірка або переформатування ходів replay перед embedded runner | Транспорт провайдера потребує суворішої перевірки ходів після загальної санітизації |
+| 44 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною |
-`normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку
-перевіряють відповідний плагін провайдера, а потім переходять до інших
-плагінів провайдерів, які підтримують хуки, доки один із них справді не змінить
-id моделі або транспорт/конфігурацію. Це дозволяє shim-рішенням для
-псевдонімів/сумісності провайдерів працювати без вимоги, щоб викликач знав,
-який саме вбудований плагін володіє цим переписуванням. Якщо жоден хук
-провайдера не переписує підтримуваний запис конфігурації сімейства Google, усе
-одно застосовується вбудований нормалізатор конфігурації Google для цього
-очищення сумісності.
+`normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють
+відповідний Plugin провайдера, а потім переходять до інших Plugin провайдерів,
+які підтримують hooks, доки якийсь із них справді не змінить id моделі або транспорт/конфігурацію.
+Це дає змогу alias/compat shim провайдерів працювати без потреби для викликуча знати,
+який bundled Plugin володіє цим переписуванням. Якщо жоден hook провайдера не переписує
+підтримуваний запис конфігурації сімейства Google, bundled нормалізатор конфігурації Google
+усе одно застосовує це очищення сумісності.
-Якщо провайдеру потрібен повністю власний wire protocol або власний виконавець
-запитів, це вже інший клас розширення. Ці хуки призначені для поведінки
-провайдера, яка все ще працює в межах звичайного циклу висновку OpenClaw.
+Якщо провайдеру потрібен повністю власний wire protocol або власний виконавець запитів,
+це вже інший клас розширення. Ці hooks призначені для поведінки провайдера, яка все ще
+працює в межах звичайного циклу інференції OpenClaw.
### Приклад провайдера
@@ -818,131 +801,115 @@ api.registerProvider({
- Anthropic використовує `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`,
`resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`,
`resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`
- і `wrapStreamFn`, оскільки він володіє прямою сумісністю вперед для Claude 4.6,
- підказками сімейства провайдера, рекомендаціями з відновлення
- автентифікації, інтеграцією кінцевої точки використання, правом на
- використання prompt-cache, значеннями конфігурації за замовчуванням з
- урахуванням автентифікації, політикою default/adaptive thinking для Claude
- та Anthropic-специфічним формуванням потоку для beta-заголовків,
+ і `wrapStreamFn`, оскільки він володіє forward-compat для Claude 4.6,
+ підказками для сімейства провайдера, рекомендаціями з відновлення автентифікації,
+ інтеграцією з endpoint usage, eligibility prompt-cache, типовими значеннями конфігурації,
+ що залежать від автентифікації, типовою/адаптивною політикою thinking для Claude
+ та Anthropic-специфічним формуванням stream для beta-заголовків,
`/fast` / `serviceTier` і `context1m`.
-- Допоміжні засоби потоку Anthropic, специфічні для Claude, поки що
- залишаються у власному публічному шві `api.ts` / `contract-api.ts`
- вбудованого плагіна. Ця поверхня пакета експортує
- `wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
- `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і допоміжні
- побудовники обгорток Anthropic нижчого рівня замість розширення загального
- SDK навколо правил beta-заголовків одного провайдера.
+- Допоміжні засоби stream, специфічні для Claude в Anthropic, поки що залишаються
+ у власному публічному seam `api.ts` / `contract-api.ts` bundled Plugin. Ця поверхня пакета
+ експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
+ `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і нижчорівневі
+ засоби побудови обгорток Anthropic замість розширення загального SDK під правила beta-заголовків
+ лише одного провайдера.
- OpenAI використовує `resolveDynamicModel`, `normalizeResolvedModel` і
`capabilities`, а також `buildMissingAuthMessage`, `suppressBuiltInModel`,
`augmentModelCatalog`, `supportsXHighThinking` і `isModernModelRef`,
- оскільки він володіє прямою сумісністю вперед для GPT-5.4, прямою
- нормалізацією OpenAI `openai-completions` -> `openai-responses`,
- підказками автентифікації з урахуванням Codex, приховуванням Spark,
- синтетичними рядками списку OpenAI та політикою thinking / live-model для
- GPT-5; сімейство потоків `openai-responses-defaults` володіє спільними
- нативними обгортками OpenAI Responses для заголовків атрибуції,
- `/fast`/`serviceTier`, детальності тексту, нативного вебпошуку Codex,
- формуванням корисного навантаження reasoning-compat і керуванням контекстом Responses.
-- OpenRouter використовує `catalog`, а також `resolveDynamicModel` і
- `prepareDynamicModel`, оскільки провайдер є наскрізним і може відкривати нові
+ оскільки він володіє forward-compat для GPT-5.4, прямою нормалізацією OpenAI
+ `openai-completions` -> `openai-responses`, підказками автентифікації з урахуванням Codex,
+ приховуванням Spark, синтетичними рядками списку OpenAI та політикою GPT-5 thinking /
+ live-model; сімейство stream `openai-responses-defaults` володіє
+ спільними нативними обгортками OpenAI Responses для заголовків attribution,
+ `/fast`/`serviceTier`, багатослівності тексту, нативного веб-пошуку Codex,
+ формування payload reasoning-compat і керування контекстом Responses.
+- OpenRouter використовує `catalog` разом із `resolveDynamicModel` і
+ `prepareDynamicModel`, оскільки провайдер є pass-through і може відкривати нові
id моделей до оновлення статичного каталогу OpenClaw; він також використовує
- `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб заголовки
- запитів, метадані маршрутизації, патчі reasoning та політика prompt-cache,
- специфічні для провайдера, не потрапляли в ядро. Його політика replay
- походить із сімейства `passthrough-gemini`, тоді як сімейство потоків
- `openrouter-thinking` володіє ін’єкцією proxy reasoning і пропусками для
- непідтримуваних моделей / `auto`.
+ `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб
+ винести з core специфічні для провайдера заголовки запитів, метадані маршрутизації, патчі reasoning і
+ політику prompt-cache. Його політика replay походить із сімейства
+ `passthrough-gemini`, тоді як сімейство stream `openrouter-thinking`
+ володіє проксі-вставкою reasoning і пропусками unsupported-model / `auto`.
- GitHub Copilot використовує `catalog`, `auth`, `resolveDynamicModel` і
- `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`,
- оскільки йому потрібні device login, що належить провайдеру, поведінка
- резервного вибору моделі, особливості транскриптів Claude, обмін токена
- GitHub на токен Copilot і кінцева точка використання, що належить провайдеру.
+ `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, оскільки йому
+ потрібні device login, що належить провайдеру, поведінка fallback моделей,
+ особливості транскриптів Claude, обмін GitHub token -> Copilot token
+ і endpoint usage, що належить провайдеру.
- OpenAI Codex використовує `catalog`, `resolveDynamicModel`,
`normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog`, а також
- `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки
- він усе ще працює на транспорті ядра OpenAI, але володіє нормалізацією
- транспорту/base URL, резервною політикою оновлення OAuth, вибором
- транспорту за замовчуванням, синтетичними рядками каталогу Codex та
- інтеграцією кінцевої точки використання ChatGPT; він використовує те саме
- сімейство потоків `openai-responses-defaults`, що й прямий OpenAI.
-- Google AI Studio і Gemini CLI OAuth використовують `resolveDynamicModel`,
+ `prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки він
+ усе ще працює на транспортах core OpenAI, але володіє нормалізацією
+ транспорту/base URL, fallback-політикою оновлення OAuth, типовим вибором транспорту,
+ синтетичними рядками каталогу Codex і інтеграцією з endpoint usage ChatGPT; він
+ використовує те саме сімейство stream `openai-responses-defaults`, що й прямий OpenAI.
+- Google AI Studio та Gemini CLI OAuth використовують `resolveDynamicModel`,
`buildReplayPolicy`, `sanitizeReplayHistory`,
`resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, оскільки
- сімейство replay `google-gemini` володіє резервним механізмом прямої
- сумісності вперед для Gemini 3.1, нативною перевіркою replay Gemini,
- очищенням bootstrap replay, режимом тегованого виводу reasoning і
- зіставленням сучасних моделей, тоді як сімейство потоків
- `google-thinking` володіє нормалізацією корисного навантаження thinking для
- Gemini; Gemini CLI OAuth також використовує `formatApiKey`,
- `resolveUsageAuth` і `fetchUsageSnapshot` для форматування токенів,
- розбору токенів і підключення кінцевої точки квот.
-- Anthropic Vertex використовує `buildReplayPolicy` через сімейство replay
- `anthropic-by-model`, щоб очищення replay, специфічне для Claude,
- залишалося обмеженим id Claude, а не кожним транспортом `anthropic-messages`.
+ сімейство replay `google-gemini` володіє fallback forward-compat для Gemini 3.1,
+ нативною перевіркою replay Gemini, санітизацією bootstrap replay, режимом
+ tagged reasoning-output і зіставленням modern-model, тоді як
+ сімейство stream `google-thinking` володіє нормалізацією payload thinking Gemini;
+ Gemini CLI OAuth також використовує `formatApiKey`, `resolveUsageAuth` і
+ `fetchUsageSnapshot` для форматування токенів, розбору токенів і підключення
+ endpoint quota.
+- Anthropic Vertex використовує `buildReplayPolicy` через
+ сімейство replay `anthropic-by-model`, щоб специфічне для Claude очищення replay залишалося
+ обмеженим id Claude, а не кожним транспортом `anthropic-messages`.
- Amazon Bedrock використовує `buildReplayPolicy`, `matchesContextOverflowError`,
- `classifyFailoverReason` і `resolveDefaultThinkingLevel`, оскільки він
- володіє класифікацією помилок throttle/not-ready/context-overflow,
- специфічною для Bedrock, для трафіку Anthropic-on-Bedrock; його політика
- replay усе ще використовує той самий захист `anthropic-by-model` лише для Claude.
+ `classifyFailoverReason` і `resolveDefaultThinkingLevel`, оскільки він володіє
+ специфічною для Bedrock класифікацією помилок throttle/not-ready/context-overflow
+ для трафіку Anthropic-on-Bedrock; його політика replay усе ще використовує той самий
+ guard лише для Claude `anthropic-by-model`.
- OpenRouter, Kilocode, Opencode і Opencode Go використовують `buildReplayPolicy`
- через сімейство replay `passthrough-gemini`, оскільки вони проксіюють моделі
- Gemini через транспорти, сумісні з OpenAI, і потребують очищення
- thought-signature Gemini без нативної перевірки replay Gemini або
- переписувань bootstrap.
-- MiniMax використовує `buildReplayPolicy` через сімейство replay
- `hybrid-anthropic-openai`, оскільки один провайдер володіє як семантикою
- повідомлень Anthropic, так і семантикою, сумісною з OpenAI; він зберігає
- видалення блоків thinking лише для Claude на боці Anthropic, водночас
- перевизначаючи режим виводу reasoning назад на нативний, а сімейство потоків
- `minimax-fast-mode` володіє переписуваннями моделей fast-mode на спільному
- шляху потоку.
-- Moonshot використовує `catalog` і `wrapStreamFn`, оскільки він усе ще
- використовує спільний транспорт OpenAI, але потребує нормалізації корисного
- навантаження thinking, що належить провайдеру; сімейство потоків
- `moonshot-thinking` зіставляє конфігурацію та стан `/think` із його
- нативним двійковим корисним навантаженням thinking.
+ через сімейство replay `passthrough-gemini`, оскільки вони проксіюють моделі Gemini
+ через транспорти, сумісні з OpenAI, і потребують санітизації
+ thought-signature Gemini без нативної перевірки replay Gemini або bootstrap-переписувань.
+- MiniMax використовує `buildReplayPolicy` через
+ сімейство replay `hybrid-anthropic-openai`, оскільки один провайдер володіє як
+ семантикою повідомлень Anthropic, так і семантикою, сумісною з OpenAI; він зберігає
+ скидання блоків thinking лише для Claude на боці Anthropic, водночас перевизначаючи
+ режим вихідних даних reasoning назад на native, а сімейство stream `minimax-fast-mode`
+ володіє переписуваннями моделей fast-mode на спільному шляху stream.
+- Moonshot використовує `catalog` разом із `wrapStreamFn`, оскільки він усе ще використовує
+ спільний транспорт OpenAI, але потребує нормалізації payload thinking, що належить провайдеру;
+ сімейство stream `moonshot-thinking` зіставляє стан config плюс `/think`
+ із його нативним binary payload thinking.
- Kilocode використовує `catalog`, `capabilities`, `wrapStreamFn` і
- `isCacheTtlEligible`, оскільки йому потрібні заголовки запитів, що належать
- провайдеру, нормалізація корисного навантаження reasoning, підказки для
- транскриптів Gemini та обмеження cache-TTL для Anthropic; сімейство потоків
- `kilocode-thinking` зберігає ін’єкцію Kilo thinking на спільному шляху
- proxy-потоку, пропускаючи `kilo/auto` та інші proxy id моделей, які не
- підтримують явне корисне навантаження reasoning.
+ `isCacheTtlEligible`, оскільки йому потрібні специфічні для провайдера заголовки запитів,
+ нормалізація payload reasoning, підказки для транскриптів Gemini та керування
+ TTL-кешем Anthropic; сімейство stream `kilocode-thinking` зберігає вставку thinking Kilo
+ на спільному проксі-шляху stream, водночас пропускаючи `kilo/auto` та
+ інші проксі-id моделей, які не підтримують явні payload reasoning.
- Z.AI використовує `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`,
`isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`,
- `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки він володіє резервним
- механізмом GLM-5, значеннями `tool_stream` за замовчуванням, UX двійкового
- thinking, зіставленням сучасних моделей, а також автентифікацією
- використання + отриманням квот; сімейство потоків `tool-stream-default-on`
- тримає обгортку `tool_stream`, увімкнену за замовчуванням, поза ручним клеєм
- для кожного окремого провайдера.
+ `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки володіє fallback GLM-5,
+ типовими значеннями `tool_stream`, UX binary thinking, зіставленням modern-model, а також
+ і auth для usage, і отриманням quota; сімейство stream `tool-stream-default-on`
+ утримує обгортку `tool_stream`, увімкнену за замовчуванням, поза рукописним кодом окремих провайдерів.
- xAI використовує `normalizeResolvedModel`, `normalizeTransport`,
`contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`,
`resolveSyntheticAuth`, `resolveDynamicModel` і `isModernModelRef`,
- оскільки він володіє нативною нормалізацією транспорту xAI Responses,
- переписуванням псевдонімів fast-mode для Grok, значенням `tool_stream` за
- замовчуванням, очищенням strict-tool / reasoning-payload, повторним
- використанням резервної автентифікації для інструментів, що належать
- плагіну, визначенням моделей Grok із прямою сумісністю вперед і
- патчами сумісності, що належать провайдеру, такими як профіль схеми
- інструментів xAI, непідтримувані ключові слова схеми, нативний `web_search`
- та декодування аргументів виклику інструментів з HTML-сутностей.
+ оскільки володіє нормалізацією нативного транспорту xAI Responses, переписуваннями псевдонімів
+ fast-mode для Grok, типовим `tool_stream`, очищенням strict-tool / reasoning-payload,
+ повторним використанням fallback-auth для інструментів, що належать Plugin, визначенням
+ forward-compat моделей Grok і compat-патчами, що належать провайдеру, такими як профіль схем інструментів xAI,
+ непідтримувані ключові слова схеми, нативний `web_search` і декодування аргументів виклику інструментів
+ з HTML-entity.
- Mistral, OpenCode Zen і OpenCode Go використовують лише `capabilities`, щоб
- винести особливості транскриптів/інструментів за межі ядра.
-- Вбудовані провайдери лише з каталогом, такі як `byteplus`,
- `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`,
- `synthetic`, `together`, `venice`, `vercel-ai-gateway` і `volcengine`,
- використовують лише `catalog`.
-- Qwen використовує `catalog` для свого текстового провайдера, а також спільні
- реєстрації розуміння медіа та генерації відео для своїх мультимодальних поверхонь.
-- MiniMax і Xiaomi використовують `catalog` разом із хуками використання,
- оскільки їхня поведінка `/usage` належить плагіну, хоча висновок усе ще
- виконується через спільні транспорти.
+ винести особливості транскриптів/інструментів із core.
+- Bundled провайдери лише з каталогом, такі як `byteplus`, `cloudflare-ai-gateway`,
+ `huggingface`, `kimi-coding`, `nvidia`, `qianfan`,
+ `synthetic`, `together`, `venice`, `vercel-ai-gateway` і `volcengine`, використовують
+ лише `catalog`.
+- Qwen використовує `catalog` для свого текстового провайдера, а також спільні реєстрації
+ media-understanding і video-generation для своїх мультимодальних поверхонь.
+- MiniMax і Xiaomi використовують `catalog` разом із hooks usage, оскільки їхня поведінка `/usage`
+ належить Plugin, хоча інференція все ще виконується через спільні транспорти.
-## Допоміжні засоби середовища виконання
+## Допоміжні засоби runtime
-Плагіни можуть отримувати доступ до вибраних допоміжних засобів ядра через
-`api.runtime`. Для TTS:
+Plugin можуть отримувати доступ до вибраних допоміжних засобів core через `api.runtime`. Для TTS:
```ts
const clip = await api.runtime.tts.textToSpeech({
@@ -963,14 +930,14 @@ const voices = await api.runtime.tts.listVoices({
Примітки:
-- `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових нотаток.
-- Використовує конфігурацію ядра `messages.tts` і вибір провайдера.
-- Повертає буфер PCM-аудіо + частоту дискретизації. Плагіни мають виконувати ресемплінг/кодування для провайдерів.
-- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать постачальнику.
-- Списки голосів можуть містити багатші метадані, як-от локаль, стать і теги характеру для засобів вибору з урахуванням провайдера.
+- `textToSpeech` повертає звичайне корисне навантаження виводу TTS core для поверхонь файлів/голосових нотаток.
+- Використовує конфігурацію core `messages.tts` і вибір провайдера.
+- Повертає PCM-буфер аудіо + частоту дискретизації. Plugin повинні виконувати ресемплінг/кодування для провайдерів.
+- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для voice picker або потоків setup, що належать постачальнику.
+- Списки голосів можуть містити багатші метадані, такі як локаль, стать і теги особистості для picker, що враховують провайдера.
- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні.
-Плагіни також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`.
+Plugin також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`.
```ts
api.registerSpeechProvider({
@@ -990,15 +957,15 @@ api.registerSpeechProvider({
Примітки:
-- Зберігайте політику TTS, резервні варіанти та доставку відповідей у ядрі.
+- Зберігайте політику TTS, fallback і доставку відповідей у core.
- Використовуйте провайдерів мовлення для поведінки синтезу, що належить постачальнику.
- Застарілий вхід Microsoft `edge` нормалізується до id провайдера `microsoft`.
-- Бажана модель володіння є орієнтованою на компанію: один плагін постачальника
- може володіти текстом, мовленням, зображенням і майбутніми медіапровайдерами,
- коли OpenClaw додає ці контракти можливостей.
+- Бажана модель володіння орієнтована на компанію: один vendor Plugin може володіти
+ текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами, коли OpenClaw додає
+ відповідні контракти можливостей.
-Для розуміння зображень/аудіо/відео плагіни реєструють один типізований
-провайдер розуміння медіа замість універсального набору ключ/значення:
+Для розуміння зображень/аудіо/відео Plugin реєструють один типізований
+провайдер media-understanding замість узагальненого key/value-набору:
```ts
api.registerMediaUnderstandingProvider({
@@ -1012,15 +979,16 @@ api.registerMediaUnderstandingProvider({
Примітки:
-- Зберігайте оркестрацію, резервні варіанти, конфігурацію та підключення каналів у ядрі.
-- Зберігайте поведінку постачальника в плагіні провайдера.
-- Розширення мають залишатися типізованими та додатковими: нові необов’язкові методи, нові необов’язкові поля результату, нові необов’язкові можливості.
+- Зберігайте оркестрацію, fallback, конфігурацію та підключення каналів у core.
+- Зберігайте поведінку постачальника в Plugin провайдера.
+- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові
+ поля результату, нові необов’язкові можливості.
- Генерація відео вже дотримується того самого шаблону:
- - ядро володіє контрактом можливості та допоміжним засобом середовища виконання
- - плагіни постачальників реєструють `api.registerVideoGenerationProvider(...)`
- - плагіни функцій/каналів споживають `api.runtime.videoGeneration.*`
+ - core володіє контрактом можливості та допоміжним runtime-засобом
+ - vendor Plugin реєструють `api.registerVideoGenerationProvider(...)`
+ - функціональні/канальні Plugin використовують `api.runtime.videoGeneration.*`
-Для допоміжних засобів середовища виконання media-understanding плагіни можуть викликати:
+Для допоміжних засобів runtime media-understanding Plugin можуть викликати:
```ts
const image = await api.runtime.mediaUnderstanding.describeImageFile({
@@ -1035,7 +1003,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({
});
```
-Для транскрипції аудіо плагіни можуть використовувати або середовище виконання
+Для транскрипції аудіо Plugin можуть використовувати або runtime
media-understanding, або старіший псевдонім STT:
```ts
@@ -1051,11 +1019,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
- `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для
розуміння зображень/аудіо/відео.
-- Використовує конфігурацію аудіо media-understanding ядра (`tools.media.audio`) і порядок резервних варіантів провайдерів.
-- Повертає `{ text: undefined }`, коли вивід транскрипції не створено (наприклад, для пропущеного/непідтримуваного вводу).
-- `api.runtime.stt.transcribeAudioFile(...)` залишається як псевдонім сумісності.
+- Використовує конфігурацію аудіо media-understanding core (`tools.media.audio`) і порядок fallback провайдерів.
+- Повертає `{ text: undefined }`, коли вихід транскрипції не створюється (наприклад, через пропущені/непідтримувані вхідні дані).
+- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом сумісності.
-Плагіни також можуть запускати фонові запуски підлеглих агентів через `api.runtime.subagent`:
+Plugin також можуть запускати фонові виконання subagent через `api.runtime.subagent`:
```ts
const result = await api.runtime.subagent.run({
@@ -1070,13 +1038,13 @@ const result = await api.runtime.subagent.run({
Примітки:
- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії.
-- OpenClaw враховує ці поля перевизначення лише для довірених викликачів.
-- Для резервних запусків, що належать плагіну, оператори мають явно надати згоду через `plugins.entries..subagent.allowModelOverride: true`.
-- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль.
-- Запуски підлеглих агентів із недовірених плагінів усе одно працюють, але запити на перевизначення відхиляються замість тихого переходу на резервний варіант.
+- OpenClaw враховує ці поля перевизначення лише для довірених викликувачів.
+- Для fallback-запусків, що належать Plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`.
+- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені Plugin конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль.
+- Запуски subagent із недовірених Plugin також працюють, але запити на перевизначення відхиляються замість тихого переходу до fallback.
-Для вебпошуку плагіни можуть споживати спільний допоміжний засіб середовища
-виконання замість звернення безпосередньо до підключення інструмента агента:
+Для веб-пошуку Plugin можуть використовувати спільний допоміжний runtime-засіб замість
+звернення до підключення інструмента агента:
```ts
const providers = api.runtime.webSearch.listProviders({
@@ -1092,14 +1060,14 @@ const result = await api.runtime.webSearch.search({
});
```
-Плагіни також можуть реєструвати провайдерів вебпошуку через
+Plugin також можуть реєструвати провайдерів веб-пошуку через
`api.registerWebSearchProvider(...)`.
Примітки:
-- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у ядрі.
-- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для постачальника.
-- `api.runtime.webSearch.*` — це бажана спільна поверхня для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента.
+- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у core.
+- Використовуйте провайдерів веб-пошуку для транспортів пошуку, специфічних для постачальника.
+- `api.runtime.webSearch.*` — це бажана спільна поверхня для функціональних/канальних Plugin, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента.
### `api.runtime.imageGeneration`
@@ -1114,12 +1082,12 @@ const providers = api.runtime.imageGeneration.listProviders({
});
```
-- `generate(...)`: генерує зображення з використанням налаштованого ланцюжка провайдерів генерації зображень.
-- `listProviders(...)`: показує доступних провайдерів генерації зображень і їхні можливості.
+- `generate(...)`: генерує зображення, використовуючи налаштований ланцюжок провайдерів генерації зображень.
+- `listProviders(...)`: перелічує доступних провайдерів генерації зображень та їхні можливості.
## HTTP-маршрути Gateway
-Плагіни можуть відкривати HTTP-кінцеві точки через `api.registerHttpRoute(...)`.
+Plugin можуть відкривати HTTP endpoint через `api.registerHttpRoute(...)`.
```ts
api.registerHttpRoute({
@@ -1137,34 +1105,33 @@ api.registerHttpRoute({
Поля маршруту:
- `path`: шлях маршруту під HTTP-сервером gateway.
-- `auth`: обов’язкове поле. Використовуйте `"gateway"` для звичайної автентифікації gateway або `"plugin"` для керованої плагіном автентифікації/перевірки webhook.
+- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайну автентифікацію gateway, або `"plugin"` для автентифікації/перевірки Webhook, якою керує Plugin.
- `match`: необов’язкове поле. `"exact"` (типово) або `"prefix"`.
-- `replaceExisting`: необов’язкове поле. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту.
-- `handler`: має повертати `true`, коли маршрут обробив запит.
+- `replaceExisting`: необов’язкове поле. Дозволяє тому самому Plugin замінити власну наявну реєстрацію маршруту.
+- `handler`: повертає `true`, якщо маршрут обробив запит.
Примітки:
-- `api.registerHttpHandler(...)` видалено, і його використання спричинить помилку завантаження плагіна. Натомість використовуйте `api.registerHttpRoute(...)`.
-- Маршрути плагінів мають явно оголошувати `auth`.
-- Конфлікти точних `path + match` відхиляються, якщо тільки не вказано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна.
-- Перекривні маршрути з різними рівнями `auth` відхиляються. Ланцюжки переходу `exact`/`prefix` мають бути лише на одному рівні `auth`.
-- Маршрути `auth: "plugin"` **не** отримують автоматично області середовища виконання оператора. Вони призначені для webhook-ів/перевірки підписів, якими керує плагін, а не для привілейованих допоміжних викликів Gateway.
-- Маршрути `auth: "gateway"` виконуються в межах області середовища виконання запиту Gateway, але ця область навмисно консервативна:
- - bearer-автентифікація зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області середовища виконання маршрутів плагіна на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes`
- - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному вході) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній
- - якщо `x-openclaw-scopes` відсутній у таких запитах маршрутів плагіна з ідентичністю, область середовища виконання повертається до `operator.write`
-- Практичне правило: не припускайте, що маршрут плагіна з gateway-auth є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністраторів, вимагайте режим автентифікації з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`.
+- `api.registerHttpHandler(...)` було видалено, і він спричинить помилку завантаження Plugin. Використовуйте натомість `api.registerHttpRoute(...)`.
+- Маршрути Plugin мають явно оголошувати `auth`.
+- Конфлікти точних `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один Plugin не може замінити маршрут іншого Plugin.
+- Перекривні маршрути з різними рівнями `auth` відхиляються. Зберігайте ланцюжки fallthrough `exact`/`prefix` лише в межах одного рівня auth.
+- Маршрути `auth: "plugin"` **не** отримують автоматично області runtime оператора. Вони призначені для Webhook/перевірки підпису, якими керує Plugin, а не для привілейованих допоміжних викликів Gateway.
+- Маршрути `auth: "gateway"` виконуються в межах області runtime запиту Gateway, але ця область навмисно консервативна:
+ - bearer-автентифікація зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області runtime маршрутів Plugin на рівні `operator.write`, навіть якщо викликувач надсилає `x-openclaw-scopes`
+ - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній
+ - якщо `x-openclaw-scopes` відсутній у таких запитах до маршрутів Plugin з ідентичністю, область runtime повертається до `operator.write`
+- Практичне правило: не вважайте маршрут Plugin із gateway-auth неявною адміністративною поверхнею. Якщо вашому маршруту потрібна поведінка лише для адміністраторів, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`.
## Шляхи імпорту Plugin SDK
-Під час створення плагінів використовуйте підшляхи SDK замість монолітного
-імпорту `openclaw/plugin-sdk`:
+Під час написання Plugin використовуйте підшляхи SDK замість монолітного імпорту `openclaw/plugin-sdk`:
-- `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації плагінів.
-- `openclaw/plugin-sdk/core` для загального спільного контракту для плагінів.
-- `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod-схеми
- `openclaw.json` (`OpenClawSchema`).
-- Стабільні примітиви каналів, такі як `openclaw/plugin-sdk/channel-setup`,
+- `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації Plugin.
+- `openclaw/plugin-sdk/core` для узагальненого спільного контракту, орієнтованого на Plugin.
+- `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod-схеми `openclaw.json`
+ (`OpenClawSchema`).
+- Стабільні канальні примітиви, такі як `openclaw/plugin-sdk/channel-setup`,
`openclaw/plugin-sdk/setup-runtime`,
`openclaw/plugin-sdk/setup-adapter-runtime`,
`openclaw/plugin-sdk/setup-tools`,
@@ -1176,19 +1143,15 @@ api.registerHttpRoute({
`openclaw/plugin-sdk/channel-reply-pipeline`,
`openclaw/plugin-sdk/command-auth`,
`openclaw/plugin-sdk/secret-input` і
- `openclaw/plugin-sdk/webhook-ingress` для спільного підключення
- налаштування/автентифікації/відповідей/webhook. `channel-inbound` — це
- спільне місце для debounce, зіставлення згадок, допоміжних засобів політики
- вхідних згадок, форматування envelope та допоміжних засобів контексту
- вхідного envelope.
- `channel-setup` — це вузький шов налаштування з необов’язковим встановленням.
- `setup-runtime` — це безпечна для середовища виконання поверхня налаштування,
- яка використовується `setupEntry` / відкладеним запуском, включно з безпечними
- для імпорту адаптерами патчів налаштування.
- `setup-adapter-runtime` — це шов адаптера налаштування облікового запису з
- урахуванням env.
- `setup-tools` — це малий шов для допоміжних засобів CLI/архіву/документації
- (`formatCliCommand`,
+ `openclaw/plugin-sdk/webhook-ingress` для спільного
+ підключення setup/auth/reply/Webhook. `channel-inbound` — це спільний дім для debounce, зіставлення згадок,
+ допоміжних засобів політики вхідних згадок, форматування envelope та
+ допоміжних засобів контексту вхідного envelope.
+ `channel-setup` — це вузький seam setup необов’язкового встановлення.
+ `setup-runtime` — це безпечна для runtime поверхня setup, яка використовується `setupEntry` /
+ відкладеним запуском, зокрема безпечними для імпорту адаптерами patch setup.
+ `setup-adapter-runtime` — це seam адаптера setup облікового запису з урахуванням env.
+ `setup-tools` — це невеликий seam допоміжних засобів CLI/архіву/документації (`formatCliCommand`,
`detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`,
`CONFIG_DIR`).
- Підшляхи доменів, такі як `openclaw/plugin-sdk/channel-config-helpers`,
@@ -1209,211 +1172,193 @@ api.registerHttpRoute({
`openclaw/plugin-sdk/status-helpers`,
`openclaw/plugin-sdk/text-runtime`,
`openclaw/plugin-sdk/runtime-store` і
- `openclaw/plugin-sdk/directory-runtime` для спільних допоміжних засобів
- середовища виконання/конфігурації.
- `telegram-command-config` — це вузький публічний шов для нормалізації/
- перевірки користувацьких команд Telegram і залишається доступним, навіть якщо
- поверхня контракту вбудованого Telegram тимчасово недоступна.
- `text-runtime` — це спільний шов тексту/markdown/журналювання, включно з
- видаленням тексту, видимого асистенту, допоміжними засобами рендерингу/
- розбиття markdown, допоміжними засобами редагування, допоміжними засобами
- тегів директив і утилітами безпечного тексту.
-- Специфічні для погодження шви каналів мають надавати перевагу одному
- контракту `approvalCapability` у плагіні. Потім ядро зчитує автентифікацію
- погодження, доставку, рендеринг, нативну маршрутизацію та поведінку лінивого
- нативного обробника через цю одну можливість замість змішування поведінки
- погодження з іншими полями плагіна.
-- `openclaw/plugin-sdk/channel-runtime` застарів і залишається лише як
- shim сумісності для старих плагінів. Новий код має імпортувати вужчі
- загальні примітиви, а код репозиторію не повинен додавати нові імпорти цього shim.
-- Внутрішні компоненти вбудованих розширень залишаються приватними. Зовнішні
- плагіни мають використовувати лише підшляхи `openclaw/plugin-sdk/*`. Ядро/тести
- OpenClaw можуть використовувати публічні точки входу репозиторію в корені
- пакета плагіна, такі як `index.js`, `api.js`, `runtime-api.js`, `setup-entry.js`
- і вузькоспрямовані файли, такі як `login-qr-api.js`. Ніколи не імпортуйте
- `src/*` пакета плагіна з ядра або з іншого розширення.
-- Розділення точок входу репозиторію:
- `/api.js` — це панель допоміжних засобів/типів,
- `/runtime-api.js` — це панель лише для середовища виконання,
- `/index.js` — це точка входу вбудованого плагіна,
- а `/setup-entry.js` — це точка входу плагіна налаштування.
-- Поточні приклади вбудованих провайдерів:
- - Anthropic використовує `api.js` / `contract-api.js` для допоміжних засобів
- потоку Claude, таких як `wrapAnthropicProviderStream`, допоміжні засоби
- beta-заголовків і розбір `service_tier`.
- - OpenAI використовує `api.js` для побудовників провайдерів, допоміжних
- засобів моделей за замовчуванням і побудовників провайдерів реального часу.
- - OpenRouter використовує `api.js` для свого побудовника провайдера разом із
- допоміжними засобами онбордингу/конфігурації, тоді як `register.runtime.js`
- усе ще може повторно експортувати загальні допоміжні засоби
- `plugin-sdk/provider-stream` для локального використання в репозиторії.
-- Публічні точки входу, завантажені через фасад, надають перевагу активному
- знімку конфігурації середовища виконання, якщо він існує, а потім
- повертаються до визначеного файлу конфігурації на диску, коли OpenClaw ще не
- обслуговує знімок середовища виконання.
-- Загальні спільні примітиви залишаються бажаним публічним контрактом SDK.
- Невеликий зарезервований набір допоміжних швів із брендингом вбудованих
- каналів усе ще існує. Розглядайте їх як шви для супроводу вбудованих рішень/
- сумісності, а не як нові цілі імпорту для сторонніх рішень; нові
- міжканальні контракти, як і раніше, мають потрапляти до загальних підшляхів
- `plugin-sdk/*` або до локальних панелей плагіна `api.js` /
+ `openclaw/plugin-sdk/directory-runtime` для спільних допоміжних засобів runtime/конфігурації.
+ `telegram-command-config` — це вузький публічний seam для нормалізації/валідації користувацьких
+ команд Telegram і він залишається доступним навіть якщо поверхня контракту bundled
+ Telegram тимчасово недоступна.
+ `text-runtime` — це спільний seam тексту/Markdown/логування, зокрема
+ видалення тексту, видимого асистенту, допоміжні засоби рендерингу/розбиття Markdown, засоби редагування,
+ допоміжні засоби directive-tag і утиліти safe-text.
+- Канальним seam, специфічним для approval, слід віддавати перевагу одному контракту
+ `approvalCapability` у Plugin. Тоді Core читає auth, доставку, рендеринг,
+ native-routing і поведінку lazy native-handler для approval через цю одну можливість
+ замість змішування поведінки approval з не пов’язаними полями Plugin.
+- `openclaw/plugin-sdk/channel-runtime` є застарілим і залишається лише як
+ shim сумісності для старіших Plugin. Новий код має імпортувати вужчі
+ узагальнені примітиви натомість, а код репозиторію не повинен додавати нові імпорти цього shim.
+- Внутрішні механізми bundled extension залишаються приватними. Зовнішні Plugin мають використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код core/test OpenClaw може використовувати
+ публічні точки входу репозиторію в корені пакета Plugin, такі як `index.js`, `api.js`,
+ `runtime-api.js`, `setup-entry.js`, і вузькоспрямовані файли, такі як
+ `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета Plugin із core або з
+ іншого extension.
+- Поділ точок входу репозиторію:
+ `/api.js` — це barrel допоміжних засобів/типів,
+ `/runtime-api.js` — це barrel лише для runtime,
+ `/index.js` — це точка входу bundled Plugin,
+ а `/setup-entry.js` — це точка входу Plugin setup.
+- Поточні приклади bundled провайдерів:
+ - Anthropic використовує `api.js` / `contract-api.js` для допоміжних засобів stream Claude, таких
+ як `wrapAnthropicProviderStream`, допоміжні засоби beta-заголовків і розбір `service_tier`.
+ - OpenAI використовує `api.js` для побудовників провайдерів, допоміжних засобів типових моделей і
+ побудовників провайдерів реального часу.
+ - OpenRouter використовує `api.js` для свого побудовника провайдера, а також допоміжних засобів onboarding/config,
+ тоді як `register.runtime.js` усе ще може повторно експортувати узагальнені
+ допоміжні засоби `plugin-sdk/provider-stream` для локального використання в репозиторії.
+- Публічні точки входу, завантажені через facade, надають перевагу активному знімку конфігурації runtime,
+ якщо він існує, а потім повертаються до визначеного файлу конфігурації на диску, якщо
+ OpenClaw іще не обслуговує знімок runtime.
+- Узагальнені спільні примітиви залишаються бажаним публічним контрактом SDK. Невеликий
+ зарезервований сумісний набір channel-branded допоміжних seam bundled іще існує. Розглядайте їх як seam для супроводу bundled/сумісності, а не як нові цілі імпорту для сторонніх рішень; нові міжканальні контракти й далі мають з’являтися в узагальнених підшляхах `plugin-sdk/*` або в локальних barrels Plugin `api.js` /
`runtime-api.js`.
Примітка щодо сумісності:
-- Уникайте кореневої панелі `openclaw/plugin-sdk` у новому коді.
-- Спочатку надавайте перевагу вузьким стабільним примітивам. Новіші підшляхи setup/pairing/reply/
+- Уникайте кореневого barrel `openclaw/plugin-sdk` у новому коді.
+- Спочатку віддавайте перевагу вузьким стабільним примітивам. Новіші підшляхи setup/pairing/reply/
feedback/contract/inbound/threading/command/secret-input/webhook/infra/
- allowlist/status/message-tool є бажаним контрактом для нової роботи з
- вбудованими та зовнішніми плагінами.
- Розбір/зіставлення цілей має належати до `openclaw/plugin-sdk/channel-targets`.
- Обмежувачі дій повідомлень і допоміжні засоби для id повідомлень реакцій мають
- належати до `openclaw/plugin-sdk/channel-actions`.
-- Панелі допоміжних засобів, специфічні для вбудованих розширень, за
- замовчуванням не є стабільними. Якщо допоміжний засіб потрібен лише
- вбудованому розширенню, тримайте його за локальним швом `api.js` або
- `runtime-api.js` цього розширення замість просування до
+ allowlist/status/message-tool є цільовим контрактом для нової
+ роботи з bundled і зовнішніми Plugin.
+ Розбір/зіставлення цілей має належати `openclaw/plugin-sdk/channel-targets`.
+ Гейти дій повідомлень і допоміжні засоби для message-id реакцій мають належати
+ `openclaw/plugin-sdk/channel-actions`.
+- Допоміжні barrel-модулі, специфічні для bundled extension, за замовчуванням не є стабільними. Якщо
+ допоміжний засіб потрібен лише bundled extension, зберігайте його за локальним
+ seam `api.js` або `runtime-api.js` цього extension замість просування до
`openclaw/plugin-sdk/`.
-- Нові спільні шви допоміжних засобів мають бути загальними, а не брендованими
- під канал. Спільний розбір цілей має належати до
- `openclaw/plugin-sdk/channel-targets`; внутрішні компоненти, специфічні для
- каналу, залишаються за локальним швом `api.js` або `runtime-api.js` плагіна-власника.
+- Нові seam спільних допоміжних засобів мають бути узагальненими, а не брендовими для каналу. Спільний розбір
+ цілей має належати `openclaw/plugin-sdk/channel-targets`; внутрішні механізми, специфічні для каналу,
+ залишаються за локальним seam `api.js` або `runtime-api.js` Plugin-власника.
- Підшляхи, специфічні для можливостей, такі як `image-generation`,
- `media-understanding` і `speech`, існують, оскільки вбудовані/власні плагіни
- вже використовують їх сьогодні. Їхня наявність сама по собі не означає, що
- кожен експортований допоміжний засіб є довгостроковим замороженим зовнішнім контрактом.
+ `media-understanding` і `speech`, існують, бо bundled/native Plugin
+ вже сьогодні їх використовують. Їхня наявність сама по собі не означає, що кожен експортований допоміжний засіб є
+ довгостроковим замороженим зовнішнім контрактом.
## Схеми інструмента повідомлень
-Плагіни мають володіти внесками в схему `describeMessageTool(...)`, специфічними
-для каналу. Тримайте поля, специфічні для провайдера, у плагіні, а не в
-спільному ядрі.
+Plugin мають володіти внесками до схем канально-специфічного `describeMessageTool(...)`.
+Зберігайте поля, специфічні для провайдера, у Plugin, а не в спільному core.
-Для спільних переносимих фрагментів схеми повторно використовуйте загальні
-допоміжні засоби, експортовані через `openclaw/plugin-sdk/channel-actions`:
+Для спільних переносних фрагментів схем повторно використовуйте узагальнені допоміжні засоби, експортовані через
+`openclaw/plugin-sdk/channel-actions`:
-- `createMessageToolButtonsSchema()` для корисного навантаження у стилі сітки кнопок
-- `createMessageToolCardSchema()` для структурованого корисного навантаження карток
+- `createMessageToolButtonsSchema()` для payload у стилі сітки кнопок
+- `createMessageToolCardSchema()` для payload структурованих карток
-Якщо форма схеми має сенс лише для одного провайдера, визначайте її у власному
-джерелі цього плагіна замість просування до спільного SDK.
+Якщо певна форма схеми має сенс лише для одного провайдера, визначайте її у
+власному коді цього Plugin замість просування до спільного SDK.
## Визначення цілей каналу
-Плагіни каналів мають володіти семантикою цілей, специфічною для каналу.
-Тримайте спільний outbound host загальним і використовуйте поверхню адаптера
-обміну повідомленнями для правил провайдера:
+Канальні Plugin мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний
+хост outbound узагальненим і використовуйте поверхню адаптера повідомлень для правил провайдера:
-- `messaging.inferTargetChatType({ to })` визначає, чи слід розглядати
- нормалізовану ціль як `direct`, `group` або `channel` до пошуку в каталозі.
-- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру,
- чи слід вводу відразу перейти до визначення за схожістю з id замість пошуку
- в каталозі.
-- `messaging.targetResolver.resolveTarget(...)` — це резервний варіант
- плагіна, коли ядру потрібне остаточне визначення, що належить провайдеру,
- після нормалізації або після промаху в каталозі.
-- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії,
+- `messaging.inferTargetChatType({ to })` визначає, чи слід нормалізовану ціль
+ трактувати як `direct`, `group` або `channel` до пошуку в довіднику.
+- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи
+ має вхід одразу переходити до визначення за схожістю з id замість пошуку в довіднику.
+- `messaging.targetResolver.resolveTarget(...)` — це fallback Plugin, коли
+ core потрібне фінальне визначення, що належить провайдеру, після нормалізації або
+ після промаху в довіднику.
+- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту outbound-сесії,
специфічною для провайдера, щойно ціль визначено.
Рекомендований поділ:
-- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають
- прийматися до пошуку серед контактів/груп.
-- Використовуйте `looksLikeId` для перевірок типу «розглядати це як явний/нативний id цілі».
-- Використовуйте `resolveTarget` для резервної нормалізації, специфічної для провайдера, а не для широкого пошуку в каталозі.
-- Тримайте нативні для провайдера id, такі як chat id, thread id, JID, handle
- і room id, усередині значень `target` або параметрів, специфічних для
- провайдера, а не в загальних полях SDK.
+- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають прийматися до
+ пошуку серед peer/group.
+- Використовуйте `looksLikeId` для перевірок «трактувати це як явний/native id цілі».
+- Використовуйте `resolveTarget` для fallback-нормалізації, специфічної для провайдера, а не для
+ широкого пошуку в довіднику.
+- Зберігайте native id провайдера, такі як id чатів, id потоків, JID, handle та id кімнат,
+ усередині значень `target` або параметрів, специфічних для провайдера, а не в узагальнених полях SDK.
-## Каталоги на основі конфігурації
+## Довідники на основі конфігурації
-Плагіни, які формують записи каталогу з конфігурації, мають тримати цю логіку
-в плагіні та повторно використовувати спільні допоміжні засоби з
+Plugin, які виводять записи довідника з конфігурації, мають зберігати цю логіку в
+Plugin і повторно використовувати спільні допоміжні засоби з
`openclaw/plugin-sdk/directory-runtime`.
-Використовуйте це, коли каналу потрібні каталоги контактів/груп на основі
-конфігурації, наприклад:
+Використовуйте це, коли каналу потрібні peer/group на основі конфігурації, наприклад:
-- контакти DM, керовані allowlist
-- налаштовані відображення каналів/груп
-- статичні резервні варіанти каталогу в межах облікового запису
+- DM peer, керовані allowlist
+- налаштовані мапи каналів/груп
+- статичні fallback довідника в межах облікового запису
Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції:
- фільтрацію запитів
-- застосування обмежень
+- застосування ліміту
- допоміжні засоби дедуплікації/нормалізації
- побудову `ChannelDirectoryEntry[]`
-Перевірка облікового запису та нормалізація id, специфічні для каналу, мають
-залишатися в реалізації плагіна.
+Інспекція облікового запису та нормалізація id, специфічні для каналу, мають
+залишатися в реалізації Plugin.
## Каталоги провайдерів
-Плагіни провайдерів можуть визначати каталоги моделей для висновку за
-допомогою `registerProvider({ catalog: { run(...) { ... } } })`.
+Plugin провайдерів можуть визначати каталоги моделей для інференції за допомогою
+`registerProvider({ catalog: { run(...) { ... } } })`.
`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в
`models.providers`:
- `{ provider }` для одного запису провайдера
-- `{ providers }` для кількох записів провайдерів
+- `{ providers }` для кількох записів провайдера
-Використовуйте `catalog`, коли плагін володіє id моделей, значеннями `base URL`
-за замовчуванням або метаданими моделей, обмеженими автентифікацією.
+Використовуйте `catalog`, коли Plugin володіє специфічними для провайдера id моделей, типовими
+значеннями base URL або метаданими моделей, захищеними автентифікацією.
-`catalog.order` керує тим, коли каталог плагіна зливається відносно вбудованих
-неявних провайдерів OpenClaw:
+`catalog.order` керує тим, коли каталог Plugin зливається відносно
+вбудованих неявних провайдерів OpenClaw:
-- `simple`: прості провайдери на основі API-ключа або env
-- `profile`: провайдери, які з’являються за наявності профілів автентифікації
+- `simple`: прості провайдери на основі API-key або env
+- `profile`: провайдери, які з’являються, коли існують профілі автентифікації
- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів
-- `late`: останній прохід після інших неявних провайдерів
+- `late`: останній прохід, після інших неявних провайдерів
-Пізніші провайдери перемагають при конфлікті ключів, тому плагіни можуть
-свідомо перевизначати вбудований запис провайдера з тим самим id провайдера.
+Пізніші провайдери перемагають у разі колізії ключів, тому Plugin можуть навмисно
+перевизначати вбудований запис провайдера з тим самим id провайдера.
Сумісність:
- `discovery` усе ще працює як застарілий псевдонім
- якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog`
-## Канали лише для читання
+## Інспекція каналу в режимі лише читання
-Якщо ваш плагін реєструє канал, надавайте перевагу реалізації
-`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`.
+Якщо ваш Plugin реєструє канал, віддавайте перевагу реалізації
+`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`.
Чому:
-- `resolveAccount(...)` — це шлях середовища виконання. Він може припускати,
- що облікові дані повністю матеріалізовані, і швидко завершуватися помилкою,
- якщо потрібних секретів бракує.
-- Шляхи команд лише для читання, такі як `openclaw status`,
- `openclaw status --all`, `openclaw channels status`,
- `openclaw channels resolve` і потоки відновлення doctor/config, не повинні
- матеріалізувати облікові дані середовища виконання лише для опису конфігурації.
+- `resolveAccount(...)` — це шлях runtime. Він може виходити з припущення, що облікові дані
+ повністю матеріалізовані, і швидко завершуватися помилкою, коли потрібні секрети відсутні.
+- Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`,
+ `openclaw channels status`, `openclaw channels resolve` і потоки doctor/config
+ repair, не повинні потребувати матеріалізації runtime-облікових даних лише для
+ опису конфігурації.
Рекомендована поведінка `inspectAccount(...)`:
- Повертайте лише описовий стан облікового запису.
- Зберігайте `enabled` і `configured`.
-- За потреби включайте поля джерела/стану облікових даних, наприклад:
+- Включайте поля джерела/статусу облікових даних, коли це доречно, наприклад:
- `tokenSource`, `tokenStatus`
- `botTokenSource`, `botTokenStatus`
- `appTokenSource`, `appTokenStatus`
- `signingSecretSource`, `signingSecretStatus`
-- Вам не потрібно повертати сирі значення токенів лише для повідомлення про
- доступність у режимі лише читання. Повернення `tokenStatus: "available"`
- (і відповідного поля джерела) достатньо для команд на кшталт status.
-- Використовуйте `configured_unavailable`, коли облікові дані налаштовані через SecretRef, але недоступні в поточному шляху команди.
+- Вам не потрібно повертати сирі значення токенів лише для звітування про доступність у режимі лише читання.
+ Повернути `tokenStatus: "available"` (і відповідне поле джерела)
+ достатньо для команд у стилі status.
+- Використовуйте `configured_unavailable`, коли облікові дані налаштовані через SecretRef, але
+ недоступні в поточному шляху команди.
-Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно
-в цьому шляху команди» замість аварійного завершення або хибного повідомлення,
-що обліковий запис не налаштовано.
+Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди»
+замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано.
-## Package packs
+## Package pack
-Каталог плагіна може містити `package.json` з `openclaw.extensions`:
+Каталог Plugin може містити `package.json` з `openclaw.extensions`:
```json
{
@@ -1425,71 +1370,65 @@ api.registerHttpRoute({
}
```
-Кожен запис стає плагіном. Якщо пакет перераховує кілька розширень, id плагіна
+Кожен запис стає Plugin. Якщо pack перелічує кілька extension, id Plugin
стає `name/`.
-Якщо ваш плагін імпортує залежності npm, установіть їх у цьому каталозі, щоб
+Якщо ваш Plugin імпортує npm-залежності, встановіть їх у цьому каталозі, щоб
`node_modules` був доступний (`npm install` / `pnpm install`).
-Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися
-всередині каталогу плагіна після визначення символічних посилань. Записи, що
-виходять за межі каталогу пакета, відхиляються.
+Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу Plugin
+після розв’язання symlink. Записи, які виходять за межі каталогу пакета,
+відхиляються.
-Примітка щодо безпеки: `openclaw plugins install` встановлює залежності плагіна
-за допомогою `npm install --omit=dev --ignore-scripts` (без lifecycle scripts і
-без dev-залежностей у середовищі виконання). Зберігайте дерева залежностей
-плагінів «чистими JS/TS» і уникайте пакетів, які потребують збірок `postinstall`.
+Примітка щодо безпеки: `openclaw plugins install` встановлює залежності Plugin за допомогою
+`npm install --omit=dev --ignore-scripts` (без lifecycle script, без dev-залежностей у runtime). Зберігайте дерева залежностей Plugin «чистими JS/TS» і уникайте пакетів, які потребують збірок `postinstall`.
-Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для
-налаштування. Коли OpenClaw потребує поверхонь налаштування для вимкненого
-плагіна каналу або коли плагін каналу увімкнено, але ще не налаштовано, він
-завантажує `setupEntry` замість повної точки входу плагіна. Це робить запуск і
-налаштування легшими, коли основна точка входу плагіна також підключає
-інструменти, хуки чи інший код лише для середовища виконання.
+Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup.
+Коли OpenClaw потребує поверхонь setup для вимкненого канального Plugin, або
+коли канальний Plugin увімкнено, але ще не налаштовано, він завантажує `setupEntry`
+замість повної точки входу Plugin. Це робить запуск і setup легшими,
+коли головна точка входу Plugin також підключає інструменти, hooks або інший код
+лише для runtime.
Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`
-може перевести плагін каналу на той самий шлях `setupEntry` під час передслухової
-фази запуску gateway, навіть якщо канал уже налаштовано.
+може підключити канальний Plugin до того самого шляху `setupEntry` під час
+передпрослуховувального етапу запуску gateway, навіть якщо канал уже налаштовано.
-Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню
-запуску, яка має існувати до того, як gateway почне слухати. На практиці це
-означає, що точка входу налаштування має реєструвати кожну можливість каналу,
-від якої залежить запуск, зокрема:
+Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати
+до того, як gateway почне слухати. На практиці це означає, що точка входу setup
+має реєструвати кожну можливість, що належить каналу і від якої залежить запуск, наприклад:
- саму реєстрацію каналу
- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне слухати
-- будь-які методи gateway, інструменти або сервіси, які мають існувати в цей самий проміжок часу
+- будь-які методи Gateway, інструменти або сервіси, які мають існувати в той самий період
-Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю
-запуску, не вмикайте цей прапорець. Залиште плагін на типовій поведінці й
-дозвольте OpenClaw завантажити повну точку входу під час запуску.
+Якщо ваша повна точка входу все ще володіє будь-якою обов’язковою можливістю запуску, не вмикайте
+цей прапорець. Залишайте для Plugin типову поведінку і дозвольте OpenClaw завантажити
+повну точку входу під час запуску.
-Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту
-лише для налаштування, з якими ядро може звірятися до завантаження повного
-середовища виконання каналу. Поточна поверхня просування налаштування така:
+Bundled канали також можуть публікувати допоміжні засоби contract-surface лише для setup, з якими core
+може звірятися до завантаження повного runtime каналу. Поточна поверхня
+просування setup така:
- `singleAccountKeysToMove`
- `namedAccountPromotionKeys`
- `resolveSingleAccountPromotionTarget(...)`
-Ядро використовує цю поверхню, коли йому потрібно просунути застарілу
-конфігурацію каналу з одним обліковим записом у `channels..accounts.*`
-без завантаження повної точки входу плагіна. Поточний вбудований приклад —
-Matrix: він переносить лише ключі auth/bootstrap до іменованого просунутого
-облікового запису, коли іменовані облікові записи вже існують, і може
-зберегти налаштований неканонічний ключ облікового запису за замовчуванням
-замість того, щоб завжди створювати `accounts.default`.
+Core використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію
+одноканального облікового запису до `channels..accounts.*` без завантаження повної точки входу Plugin.
+Поточний bundled приклад — Matrix: він переносить лише ключі auth/bootstrap до
+іменованого просунутого облікового запису, коли іменовані облікові записи вже існують, і може
+зберігати налаштований неканонічний ключ default-account замість того, щоб завжди створювати
+`accounts.default`.
-Ці адаптери патчів налаштування зберігають ліниве виявлення поверхні контракту
-вбудованих рішень. Час імпорту залишається малим; поверхня просування
-завантажується лише під час першого використання замість повторного входу в
-запуск вбудованого каналу під час імпорту модуля.
+Ці адаптери patch setup зберігають ліниве виявлення contract-surface bundled. Час імпорту
+залишається малим; поверхня просування завантажується лише під час першого використання
+замість повторного входу в запуск bundled каналу під час імпорту модуля.
-Коли ці поверхні запуску включають методи Gateway RPC, тримайте їх під
-префіксом, специфічним для плагіна. Простори імен адміністратора ядра
-(`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються
-зарезервованими й завжди визначаються як `operator.admin`, навіть якщо плагін
-запитує вужчу область.
+Коли ці поверхні запуску містять Gateway RPC methods, зберігайте їх у
+специфічному для Plugin префіксі. Простори імен адміністрування core (`config.*`,
+`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди визначаються
+як `operator.admin`, навіть якщо Plugin запитує вужчу область.
Приклад:
@@ -1508,8 +1447,8 @@ Matrix: він переносить лише ключі auth/bootstrap до ім
### Метадані каталогу каналів
-Плагіни каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel`, а
-підказки встановлення — через `openclaw.install`. Це дозволяє ядру не містити даних каталогу.
+Канальні Plugin можуть оголошувати метадані setup/discovery через `openclaw.channel` і
+підказки встановлення через `openclaw.install`. Це дозволяє не зберігати дані каталогу в core.
Приклад:
@@ -1537,44 +1476,41 @@ Matrix: він переносить лише ключі auth/bootstrap до ім
}
```
-Корисні поля `openclaw.channel` понад мінімальний приклад:
+Корисні поля `openclaw.channel`, окрім мінімального прикладу:
-- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу
-- `docsLabel`: перевизначає текст посилання на документацію
-- `preferOver`: id плагінів/каналів з нижчим пріоритетом, які цей запис каталогу має випереджати
+- `detailLabel`: вторинний підпис для багатших поверхонь каталогу/status
+- `docsLabel`: перевизначає текст посилання для посилання на документацію
+- `preferOver`: id Plugin/каналу з нижчим пріоритетом, які цей запис каталогу має випереджати
- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору
-- `markdownCapable`: позначає канал як здатний працювати з markdown для рішень щодо форматування вихідних даних
-- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false`
-- `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено `false`
+- `markdownCapable`: позначає канал як такий, що підтримує Markdown, для рішень щодо outbound-форматування
+- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, коли значення дорівнює `false`
+- `exposure.setup`: приховує канал із інтерактивних picker setup/configure, коли значення дорівнює `false`
- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації
-- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure`
-- `quickstartAllowFrom`: додає канал до стандартного потоку quickstart `allowFrom`
-- `forceAccountBinding`: вимагає явного прив’язування облікового запису, навіть якщо існує лише один обліковий запис
-- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення announce target
+- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure`
+- `quickstartAllowFrom`: підключає канал до стандартного потоку quickstart `allowFrom`
+- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть якщо існує лише один обліковий запис
+- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення цілей announce
-OpenClaw також може об’єднувати **зовнішні каталоги каналів** (наприклад, експорт
-реєстру MPM). Помістіть JSON-файл в один із таких шляхів:
+OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт реєстру MPM).
+Помістіть JSON-файл в один із таких шляхів:
- `~/.openclaw/mpm/plugins.json`
- `~/.openclaw/mpm/catalog.json`
- `~/.openclaw/plugins/catalog.json`
Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на
-один або кілька JSON-файлів (розділених комою/крапкою з комою/роздільником `PATH`).
-Кожен файл має містити
-`{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`.
-Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для
-ключа `"entries"`.
+один або кілька JSON-файлів (розділених комою/крапкою з комою/як у `PATH`). Кожен файл має
+містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`.
-## Плагіни рушія контексту
+## Plugin контекстного рушія
-Плагіни рушія контексту володіють оркестрацією контексту сесії для поглинання,
-збирання та компакції. Реєструйте їх із вашого плагіна через
+Plugin контекстного рушія володіють оркестрацією контексту сесії для ingest, assembly
+і Compaction. Реєструйте їх зі свого Plugin за допомогою
`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через
`plugins.slots.contextEngine`.
-Використовуйте це, коли вашому плагіну потрібно замінити або розширити типовий
-конвеєр контексту, а не просто додати пошук у пам’яті або хуки.
+Використовуйте це, коли вашому Plugin потрібно замінити або розширити типовий
+конвеєр контексту, а не просто додати пошук у пам’яті або hooks.
```ts
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
@@ -1602,8 +1538,8 @@ export default function (api) {
}
```
-Якщо ваш рушій **не** володіє алгоритмом компакції, залиште `compact()`
-реалізованим і явно делегуйте її:
+Якщо ваш рушій **не** володіє алгоритмом Compaction, залиште `compact()`
+реалізованим і явно делегуйте його:
```ts
import {
@@ -1640,48 +1576,46 @@ export default function (api) {
## Додавання нової можливості
-Коли плагіну потрібна поведінка, яка не вписується в поточний API, не обходьте
-систему плагінів через приватне звернення всередину. Додайте відсутню
-можливість.
+Коли Plugin потребує поведінки, яка не вписується в поточний API, не обходьте
+систему Plugin приватним зверненням до внутрішніх механізмів. Додайте відсутню можливість.
Рекомендована послідовність:
-1. визначте контракт ядра
- Визначте, якою спільною поведінкою має володіти ядро: політикою, резервними
- варіантами, злиттям конфігурації, життєвим циклом, семантикою для каналів і
- формою допоміжних засобів середовища виконання.
-2. додайте типізовані поверхні реєстрації/середовища виконання плагінів
- Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною
+1. визначте контракт core
+ Вирішіть, якою спільною поведінкою має володіти core: політика, fallback, злиття конфігурації,
+ життєвий цикл, семантика для каналів і форма допоміжних засобів runtime.
+2. додайте типізовані поверхні реєстрації/runtime Plugin
+ Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною
типізованою поверхнею можливості.
-3. під’єднайте споживачів із ядра + каналів/функцій
- Канали та плагіни функцій мають споживати нову можливість через ядро, а не
- через прямий імпорт реалізації постачальника.
+3. підключіть core + споживачів каналів/функцій
+ Канали та функціональні Plugin мають використовувати нову можливість через core,
+ а не через прямий імпорт реалізації постачальника.
4. зареєструйте реалізації постачальників
- Потім плагіни постачальників реєструють свої серверні частини для цієї можливості.
-5. додайте покриття контрактів
- Додайте тести, щоб володіння та форма реєстрації з часом залишалися явними.
+ Потім vendor Plugin реєструють свої бекенди для цієї можливості.
+5. додайте контрактне покриття
+ Додайте тести, щоб володіння і форма реєстрації з часом залишалися явними.
-Саме так OpenClaw зберігає чіткий підхід, не стаючи жорстко прив’язаним до
-світогляду одного провайдера. Конкретний контрольний список файлів і
-покроковий приклад дивіться в [Практичному посібнику із можливостей](/uk/plugins/architecture).
+Саме так OpenClaw залишається цілеспрямованим, не стаючи жорстко прив’язаним до
+бачення одного провайдера. Див. [Практичний посібник із можливостей](/uk/plugins/architecture)
+для конкретного списку файлів і опрацьованого прикладу.
-### Контрольний список можливостей
+### Контрольний список можливості
-Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися
-цих поверхонь:
+Коли ви додаєте нову можливість, реалізація зазвичай має охоплювати ці
+поверхні разом:
-- типів контракту ядра в `src//types.ts`
-- runner-а/допоміжного засобу середовища виконання ядра в `src//runtime.ts`
-- поверхні реєстрації API плагінів у `src/plugins/types.ts`
-- підключення реєстру плагінів у `src/plugins/registry.ts`
-- відкриття середовища виконання плагінів у `src/plugins/runtime/*`, коли
- плагінам функцій/каналів потрібно це споживати
-- допоміжних засобів capture/test у `src/test-utils/plugin-registration.ts`
-- перевірок володіння/контрактів у `src/plugins/contracts/registry.ts`
-- документації для операторів/плагінів у `docs/`
+- типи контрактів core у `src//types.ts`
+- runner/runtime-засіб core у `src//runtime.ts`
+- поверхню реєстрації API Plugin у `src/plugins/types.ts`
+- підключення реєстру Plugin у `src/plugins/registry.ts`
+- відкриття runtime Plugin у `src/plugins/runtime/*`, коли функціональним/канальним
+ Plugin потрібно це використовувати
+- допоміжні засоби capture/test у `src/test-utils/plugin-registration.ts`
+- перевірки володіння/контракту в `src/plugins/contracts/registry.ts`
+- документацію для операторів/Plugin у `docs/`
-Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість ще
-не повністю інтегрована.
+Якщо одна з цих поверхонь відсутня, це зазвичай означає, що можливість
+іще не повністю інтегрована.
### Шаблон можливості
@@ -1711,7 +1645,7 @@ const clip = await api.runtime.videoGeneration.generate({
});
```
-Шаблон тесту контракту:
+Шаблон контрактного тесту:
```ts
expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
@@ -1719,7 +1653,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
Це зберігає правило простим:
-- ядро володіє контрактом можливості + оркестрацією
-- плагіни постачальників володіють реалізаціями постачальників
-- плагіни функцій/каналів споживають допоміжні засоби середовища виконання
-- тести контрактів зберігають володіння явним
+- core володіє контрактом можливості + оркестрацією
+- vendor Plugin володіють реалізаціями постачальників
+- функціональні/канальні Plugin використовують допоміжні засоби runtime
+- контрактні тести зберігають явність володіння
diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md
index 0f8b21b42..4c19dec6d 100644
--- a/docs/uk/plugins/manifest.md
+++ b/docs/uk/plugins/manifest.md
@@ -1,73 +1,77 @@
---
read_when:
- - Ви створюєте плагін OpenClaw
- - Вам потрібно постачати схему конфігурації плагіна або налагоджувати помилки валідації плагіна
-summary: Маніфест плагіна + вимоги до JSON schema (сувора валідація конфігурації)
-title: Маніфест плагіна
+ - Ви створюєте plugin для OpenClaw
+ - Вам потрібно надати схему конфігурації plugin або налагодити помилки валідації plugin
+summary: Вимоги до маніфесту Plugin + JSON schema (сувора валідація конфігурації)
+title: Маніфест Plugin
x-i18n:
- generated_at: "2026-04-12T08:09:11Z"
+ generated_at: "2026-04-12T09:53:31Z"
model: gpt-5.4
provider: openai
- source_hash: 4074b3639bf24606d6087597f28e29afc85f4ea628a713e9d984b441a16f1c13
+ source_hash: 08745ead2c2ab83e56dc041ec3187deead6f0439cb8c8423db03c2e3f5c78e9e
source_path: plugins/manifest.md
workflow: 15
---
-# Маніфест плагіна (`openclaw.plugin.json`)
+# Маніфест Plugin (`openclaw.plugin.json`)
-Ця сторінка стосується лише **власного маніфесту плагіна OpenClaw**.
+Ця сторінка стосується лише **власного маніфесту Plugin для OpenClaw**.
-Щоб дізнатися про сумісні макети пакетів, див. [Пакети плагінів](/uk/plugins/bundles).
+Сумісні компонування пакетів описано в [Plugin bundles](/uk/plugins/bundles).
Сумісні формати пакетів використовують інші файли маніфесту:
- Пакет Codex: `.codex-plugin/plugin.json`
-- Пакет Claude: `.claude-plugin/plugin.json` або стандартний макет компонента Claude
+- Пакет Claude: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude
без маніфесту
- Пакет Cursor: `.cursor-plugin/plugin.json`
-OpenClaw також автоматично виявляє ці макети пакетів, але вони не проходять валідацію
-за схемою `openclaw.plugin.json`, описаною тут.
+OpenClaw також автоматично виявляє ці компонування пакетів, але вони не проходять валідацію
+відповідно до схеми `openclaw.plugin.json`, описаної тут.
-Для сумісних пакетів OpenClaw наразі читає метадані пакета, а також оголошені
-кореневі каталоги skills, кореневі каталоги команд Claude, стандартні значення `settings.json` пакета Claude,
-стандартні значення LSP пакета Claude та підтримувані набори hooks, коли макет відповідає
+Для сумісних пакетів OpenClaw наразі читає метадані пакета разом з оголошеними
+коренями skill, коренями команд Claude, типовими значеннями `settings.json` для пакетів Claude,
+типовими значеннями LSP для пакетів Claude та підтримуваними наборами hook, коли компонування відповідає
очікуванням середовища виконання OpenClaw.
-Кожен власний плагін OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у
-**корені плагіна**. OpenClaw використовує цей маніфест для валідації конфігурації
-**без виконання коду плагіна**. Відсутні або недійсні маніфести вважаються
-помилками плагіна й блокують валідацію конфігурації.
+Кожен власний Plugin для OpenClaw **повинен** містити файл `openclaw.plugin.json` у
+**корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації
+**без виконання коду plugin**. Відсутні або невалідні маніфести вважаються
+помилками plugin і блокують валідацію конфігурації.
-Див. повний посібник із системи плагінів: [Плагіни](/uk/tools/plugin).
-Щодо власної моделі можливостей і поточних вказівок щодо зовнішньої сумісності:
-[Модель можливостей](/uk/plugins/architecture#public-capability-model).
+Дивіться повний посібник із системи plugin: [Plugins](/uk/tools/plugin).
+Для власної моделі capability та поточних вказівок щодо зовнішньої сумісності:
+[Модель capability](/uk/plugins/architecture#public-capability-model).
## Що робить цей файл
-`openclaw.plugin.json` — це метадані, які OpenClaw читає до завантаження коду
-вашого плагіна.
+`openclaw.plugin.json` — це метадані, які OpenClaw читає перед завантаженням коду
+вашого plugin.
Використовуйте його для:
-- ідентичності плагіна
+- ідентифікації plugin
- валідації конфігурації
-- метаданих автентифікації та онбордингу, які мають бути доступні без запуску середовища виконання плагіна
-- легких підказок активації, які поверхні control-plane можуть перевіряти до завантаження середовища виконання
-- легких дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до завантаження середовища виконання
-- метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження середовища виконання плагіна
-- скорочених метаданих володіння сімействами моделей, які мають автоматично активувати плагін до завантаження середовища виконання
-- статичних знімків володіння можливостями, що використовуються для wiring сумісності пакетів і покриття контрактів
-- метаданих конфігурації каналів, які мають об’єднуватися з поверхнями каталогу та валідації без завантаження середовища виконання
+- метаданих auth і onboarding, які мають бути доступні без запуску середовища виконання plugin
+- недорогих підказок активації, які поверхні control-plane можуть перевіряти до завантаження runtime
+- недорогих дескрипторів налаштування, які поверхні setup/onboarding можуть перевіряти до
+ завантаження runtime
+- метаданих alias та auto-enable, які мають визначатися до завантаження runtime plugin
+- скорочених метаданих володіння сімействами моделей, які мають автоматично активувати
+ plugin до завантаження runtime
+- статичних знімків володіння capability, що використовуються для вбудованої compat-обв’язки та
+ перевірки контрактів
+- метаданих конфігурації, специфічних для channel, які мають об’єднуватися в каталог і поверхні
+ валідації без завантаження runtime
- підказок UI для конфігурації
Не використовуйте його для:
-- реєстрації поведінки середовища виконання
-- оголошення кодових entrypoint
+- реєстрації поведінки runtime
+- оголошення entrypoint коду
- метаданих встановлення npm
-Це належить коду вашого плагіна та `package.json`.
+Для цього призначені код вашого plugin і `package.json`.
## Мінімальний приклад
@@ -88,7 +92,7 @@ OpenClaw також автоматично виявляє ці макети па
{
"id": "openrouter",
"name": "OpenRouter",
- "description": "Плагін провайдера OpenRouter",
+ "description": "OpenRouter provider plugin",
"version": "1.0.0",
"providers": ["openrouter"],
"modelSupport": {
@@ -109,19 +113,19 @@ OpenClaw також автоматично виявляє ці макети па
"provider": "openrouter",
"method": "api-key",
"choiceId": "openrouter-api-key",
- "choiceLabel": "Ключ API OpenRouter",
+ "choiceLabel": "OpenRouter API key",
"groupId": "openrouter",
"groupLabel": "OpenRouter",
"optionKey": "openrouterApiKey",
"cliFlag": "--openrouter-api-key",
"cliOption": "--openrouter-api-key ",
- "cliDescription": "Ключ API OpenRouter",
+ "cliDescription": "OpenRouter API key",
"onboardingScopes": ["text-inference"]
}
],
"uiHints": {
"apiKey": {
- "label": "Ключ API",
+ "label": "API key",
"placeholder": "sk-or-v1-...",
"sensitive": true
}
@@ -142,60 +146,60 @@ OpenClaw також автоматично виявляє ці макети па
| Поле | Обов’язкове | Тип | Що воно означає |
| ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `id` | Так | `string` | Канонічний ідентифікатор плагіна. Це ідентифікатор, який використовується в `plugins.entries.`. |
-| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього плагіна. |
-| `enabledByDefault` | Ні | `true` | Позначає пакетний плагін як увімкнений за замовчуванням. Пропустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб залишити плагін вимкненим за замовчуванням. |
-| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора плагіна. |
-| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей плагін, коли автентифікація, конфігурація або посилання на моделі згадують їх. |
-| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип плагіна, що використовується в `plugins.slots.*`. |
-| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей плагін. Використовується для виявлення та валідації конфігурації. |
-| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей плагін. |
-| `modelSupport` | Ні | `object` | Скорочені метадані сімейств моделей, що належать маніфесту та використовуються для автоматичного завантаження плагіна до запуску середовища виконання. |
-| `cliBackends` | Ні | `string[]` | Ідентифікатори backend виведення CLI, якими володіє цей плагін. Використовуються для автоматичної активації під час запуску з явних посилань конфігурації. |
-| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей плагін і які мають створювати діагностику конфігурації та CLI з урахуванням плагіна до завантаження середовища виконання. |
-| `providerAuthEnvVars` | Ні | `Record` | Легкі метадані змінних середовища для автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. |
-| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер кодування, що спільно використовує ключ API базового провайдера та профілі автентифікації. |
-| `channelEnvVars` | Ні | `Record` | Легкі метадані змінних середовища каналу, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для поверхонь налаштування або автентифікації каналів через змінні середовища, які мають бачити загальні допоміжні засоби запуску/конфігурації. |
-| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для селекторів онбордингу, визначення пріоритетного провайдера та простого wiring прапорців CLI. |
-| `activation` | Ні | `object` | Легкі підказки активації для завантаження, яке запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактичною поведінкою все одно володіє середовище виконання плагіна. |
-| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання плагіна. |
-| `contracts` | Ні | `object` | Статичний знімок можливостей пакетного плагіна для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. |
-| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналів, що належать маніфесту та об’єднуються з поверхнями виявлення та валідації до завантаження середовища виконання. |
-| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня плагіна. |
-| `name` | Ні | `string` | Людинозрозуміла назва плагіна. |
-| `description` | Ні | `string` | Короткий опис, що показується на поверхнях плагіна. |
-| `version` | Ні | `string` | Інформаційна версія плагіна. |
-| `uiHints` | Ні | `Record` | Підписи UI, заповнювачі та підказки щодо чутливості для полів конфігурації. |
+| `id` | Так | `string` | Канонічний id plugin. Це id, який використовується в `plugins.entries.`. |
+| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього plugin. |
+| `enabledByDefault` | Ні | `true` | Позначає вбудований plugin як увімкнений за замовчуванням. Пропустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб plugin залишався вимкненим за замовчуванням. |
+| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id plugin. |
+| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | id provider, які мають автоматично вмикати цей plugin, коли auth, config або посилання на модель згадують їх. |
+| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип plugin, що використовується `plugins.slots.*`. |
+| `channels` | Ні | `string[]` | id channel, якими володіє цей plugin. Використовується для виявлення та валідації конфігурації. |
+| `providers` | Ні | `string[]` | id provider, якими володіє цей plugin. |
+| `modelSupport` | Ні | `object` | Скорочені метадані сімейств моделей, якими володіє маніфест і які використовуються для автоматичного завантаження plugin до runtime. |
+| `cliBackends` | Ні | `string[]` | id backend CLI, якими володіє цей plugin. Використовується для автоматичної активації під час запуску на основі явних посилань у config. |
+| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей plugin і які мають формувати діагностику config і CLI з урахуванням plugin до завантаження runtime. |
+| `providerAuthEnvVars` | Ні | `Record` | Недорогі метадані змінних середовища для auth provider, які OpenClaw може перевіряти без завантаження коду plugin. |
+| `providerAuthAliases` | Ні | `Record` | id provider, які мають повторно використовувати інший id provider для пошуку auth, наприклад coding-provider, який спільно використовує базовий API key provider та профілі auth. |
+| `channelEnvVars` | Ні | `Record` | Недорогі метадані змінних середовища для channel, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для setup channel через env або поверхонь auth, які мають бачити загальні helpers startup/config. |
+| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані варіантів auth для засобів вибору в onboarding, визначення preferred-provider і простої обв’язки прапорців CLI. |
+| `activation` | Ні | `object` | Недорогі підказки активації для завантаження, яке запускається provider, командою, channel, маршрутом або capability. Лише метадані; фактична поведінка, як і раніше, належить runtime plugin. |
+| `setup` | Ні | `object` | Недорогі дескриптори setup/onboarding, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime plugin. |
+| `contracts` | Ні | `object` | Статичний знімок вбудованих capability для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння tools. |
+| `channelConfigs` | Ні | `Record` | Метадані конфігурації channel, якими володіє маніфест і які об’єднуються в поверхні виявлення та валідації до завантаження runtime. |
+| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. |
+| `name` | Ні | `string` | Зрозуміла людині назва plugin. |
+| `description` | Ні | `string` | Короткий опис, що показується в поверхнях plugin. |
+| `version` | Ні | `string` | Інформаційна версія plugin. |
+| `uiHints` | Ні | `Record` | Підписи UI, placeholders і підказки щодо чутливості для полів конфігурації. |
## Довідник `providerAuthChoices`
-Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації.
-OpenClaw читає це до завантаження середовища виконання провайдера.
+Кожен запис `providerAuthChoices` описує один варіант onboarding або auth.
+OpenClaw читає це до завантаження runtime provider.
-| Поле | Обов’язкове | Тип | Що воно означає |
-| --------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. |
-| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід диспетчеризувати. |
-| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується в потоках онбордингу та CLI. |
-| `choiceLabel` | Ні | `string` | Підпис для користувача. Якщо пропущено, OpenClaw використовує `choiceId`. |
-| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. |
-| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих асистентом. |
-| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант у селекторах асистента, але все ще дозволяє ручний вибір через CLI. |
-| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів на цей варіант-заміну. |
-| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. |
-| `groupLabel` | Ні | `string` | Підпис цієї групи для користувача. |
-| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
-| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним прапорцем. |
-| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. |
-| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. |
-| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. |
-| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо пропущено, за замовчуванням це `["text-inference"]`. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `provider` | Так | `string` | id provider, до якого належить цей варіант. |
+| `method` | Так | `string` | id методу auth, до якого слід маршрутизувати. |
+| `choiceId` | Так | `string` | Стабільний id варіанта auth, який використовується в потоках onboarding і CLI. |
+| `choiceLabel` | Ні | `string` | Підпис для користувача. Якщо поле пропущено, OpenClaw використовує `choiceId`. |
+| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. |
+| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих асистентом. |
+| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант у засобах вибору асистента, але все одно дозволяє ручний вибір через CLI. |
+| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів на цей варіант-заміну. |
+| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. |
+| `groupLabel` | Ні | `string` | Підпис цієї групи для користувача. |
+| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
+| `optionKey` | Ні | `string` | Внутрішній ключ option для простих потоків auth з одним прапорцем. |
+| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. |
+| `cliOption` | Ні | `string` | Повна форма option CLI, наприклад `--openrouter-api-key `. |
+| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. |
+| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях onboarding має показуватися цей варіант. Якщо поле пропущено, використовується `["text-inference"]` за замовчуванням. |
## Довідник `commandAliases`
-Використовуйте `commandAliases`, коли плагін володіє назвою команди середовища виконання, яку користувачі можуть
-помилково додати до `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw
-використовує ці метадані для діагностики без імпорту коду середовища виконання плагіна.
+Використовуйте `commandAliases`, коли plugin володіє назвою runtime-команди, яку користувачі можуть
+помилково помістити в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw
+використовує ці метадані для діагностики без імпорту коду runtime plugin.
```json
{
@@ -209,22 +213,22 @@ OpenClaw читає це до завантаження середовища ви
}
```
-| Поле | Обов’язкове | Тип | Що воно означає |
-| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------- |
-| `name` | Так | `string` | Назва команди, яка належить цьому плагіну. |
-| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду CLI. |
-| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід рекомендувати для операцій CLI, якщо вона існує. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------ |
+| `name` | Так | `string` | Назва команди, яка належить цьому plugin. |
+| `kind` | Ні | `"runtime-slash"` | Позначає alias як чат-команду slash, а не кореневу команду CLI. |
+| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку можна запропонувати для операцій CLI, якщо вона існує. |
## Довідник `activation`
-Використовуйте `activation`, коли плагін може з невеликими витратами оголосити, які події control-plane
+Використовуйте `activation`, коли plugin може недорого оголосити, які події control-plane
мають активувати його пізніше.
-Цей блок містить лише метадані. Він не реєструє поведінку середовища виконання і не
-замінює `register(...)`, `setupEntry` або інші entrypoint середовища виконання/плагіна.
-Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням плагіна, тому
-відсутність метаданих активації лише впливає на продуктивність; це не повинно змінювати
-коректність.
+Цей блок містить лише метадані. Він не реєструє поведінку runtime і не
+замінює `register(...)`, `setupEntry` або інші entrypoint runtime/plugin.
+Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням plugin, тому
+відсутність метаданих активації зазвичай впливає лише на продуктивність; вона не має
+змінювати коректність, поки ще існують застарілі fallback-и володіння маніфестом.
```json
{
@@ -238,22 +242,26 @@ OpenClaw читає це до завантаження середовища ви
}
```
-| Поле | Обов’язкове | Тип | Що воно означає |
-| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------ |
-| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають активувати цей плагін на запит. |
-| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають активувати цей плагін. |
-| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають активувати цей плагін. |
-| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей плагін. |
-| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються в плануванні активації control-plane. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
+| `onProviders` | Ні | `string[]` | id provider, які мають активувати цей plugin за запитом. |
+| `onCommands` | Ні | `string[]` | id команд, які мають активувати цей plugin. |
+| `onChannels` | Ні | `string[]` | id channel, які мають активувати цей plugin. |
+| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей plugin. |
+| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки capability, що використовуються для планування активації control-plane. |
-Зокрема для планування, що запускається командами, OpenClaw усе ще повертається до
-застарілих `commandAliases[].cliCommand` або `commandAliases[].name`, коли плагін
-ще не додав явні метадані `activation.onCommands`.
+Поточні активні споживачі:
+
+- планування CLI, що запускається командою, використовує як fallback застарілі
+ `commandAliases[].cliCommand` або `commandAliases[].name`
+- планування setup/runtime, що запускається provider, використовує як fallback застаріле
+ володіння `providers[]` і верхньорівневим `cliBackends[]`, коли явні
+ метадані активації provider відсутні
## Довідник `setup`
-Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні легкі метадані, що належать плагіну,
-до завантаження середовища виконання.
+Використовуйте `setup`, коли поверхням setup та onboarding потрібні недорогі метадані plugin,
+що належать plugin, до завантаження runtime.
```json
{
@@ -272,40 +280,41 @@ OpenClaw читає це до завантаження середовища ви
}
```
-Верхньорівневе `cliBackends` залишається дійсним і далі описує backend виведення CLI.
-`setup.cliBackends` — це поверхня дескрипторів, специфічна для налаштування, для
-потоків control-plane/налаштування, які мають залишатися лише метаданими.
+Верхньорівневе `cliBackends` залишається валідним і надалі описує backend-и
+інференсу CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup,
+для потоків control-plane/setup, які мають залишатися лише метаданими.
-Якщо присутні, `setup.providers` і `setup.cliBackends` є бажаною
-поверхнею пошуку на основі дескрипторів для виявлення налаштування. Якщо дескриптор лише
-звужує кандидатний плагін, а налаштуванню все ще потрібні багатші хуки середовища виконання під час налаштування,
-установіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання.
+Якщо вони присутні, `setup.providers` і `setup.cliBackends` є бажаною
+поверхнею пошуку setup у стилі descriptor-first для виявлення setup. Якщо дескриптор лише
+звужує кандидатний plugin, а setup все ще потребує багатших hook runtime на етапі setup,
+встановіть `requiresRuntime: true` і залиште `setup-api` як
+fallback-шлях виконання.
-Оскільки пошук налаштування може виконувати код `setup-api`, що належить плагіну,
-нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` повинні залишатися унікальними серед
-виявлених плагінів. Неоднозначне володіння призводить до безпечної відмови замість вибору
-переможця за порядком виявлення.
+Оскільки пошук setup може виконувати код `setup-api`, що належить plugin,
+нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед
+виявлених plugin. Неоднозначне володіння завершується без вибору замість того, щоб
+обирати переможця за порядком виявлення.
### Довідник `setup.providers`
-| Поле | Обов’язкове | Тип | Що воно означає |
-| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------------- |
-| `id` | Так | `string` | Ідентифікатор провайдера, доступний під час налаштування або онбордингу. Зберігайте нормалізовані ідентифікатори глобально унікальними. |
-| `authMethods` | Ні | `string[]` | Ідентифікатори методів налаштування/автентифікації, які цей провайдер підтримує без завантаження повного середовища виконання. |
-| `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні налаштування/статусу можуть перевіряти до завантаження середовища виконання плагіна. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------- | ----------- | ---------- | ---------------------------------------------------------------------------------------- |
+| `id` | Так | `string` | id provider, який відкривається під час setup або onboarding. Зберігайте нормалізовані id глобально унікальними. |
+| `authMethods` | Ні | `string[]` | id методів setup/auth, які цей provider підтримує без завантаження повного runtime. |
+| `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні setup/status можуть перевіряти до завантаження runtime plugin. |
### Поля `setup`
-| Поле | Обов’язкове | Тип | Що воно означає |
-| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------ |
-| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, доступні під час налаштування та онбордингу. |
-| `cliBackends` | Ні | `string[]` | Ідентифікатори backend часу налаштування, що використовуються для пошуку налаштування на основі дескрипторів. Зберігайте нормалізовані ідентифікатори глобально унікальними. |
-| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня налаштування цього плагіна. |
-| `requiresRuntime` | Ні | `boolean` | Чи потребує налаштування виконання `setup-api` після пошуку за дескриптором. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- |
+| `providers` | Ні | `object[]` | Дескриптори setup provider, що відкриваються під час setup та onboarding. |
+| `cliBackends` | Ні | `string[]` | id backend-ів на етапі setup, що використовуються для пошуку setup у стилі descriptor-first. Зберігайте нормалізовані id глобально унікальними. |
+| `configMigrations` | Ні | `string[]` | id міграцій config, які належать поверхні setup цього plugin. |
+| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` навіть після пошуку за дескриптором. |
## Довідник `uiHints`
-`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу.
+`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для відображення.
```json
{
@@ -320,21 +329,21 @@ OpenClaw читає це до завантаження середовища ви
}
```
-Кожна підказка поля може містити:
+Кожна підказка для поля може містити:
-| Поле | Тип | Що воно означає |
+| Поле | Тип | Що воно означає |
| ------------- | ---------- | -------------------------------------- |
| `label` | `string` | Підпис поля для користувача. |
| `help` | `string` | Короткий допоміжний текст. |
-| `tags` | `string[]` | Необов’язкові теги UI. |
+| `tags` | `string[]` | Необов’язкові UI-теги. |
| `advanced` | `boolean` | Позначає поле як розширене. |
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
-| `placeholder` | `string` | Текст-заповнювач для полів форми. |
+| `placeholder` | `string` | Текст placeholder для полів форми. |
## Довідник `contracts`
-Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може
-читати без імпорту середовища виконання плагіна.
+Використовуйте `contracts` лише для статичних метаданих володіння capability, які OpenClaw може
+читати без імпорту runtime plugin.
```json
{
@@ -354,22 +363,22 @@ OpenClaw читає це до завантаження середовища ви
Кожен список є необов’язковим:
-| Поле | Тип | Що воно означає |
-| -------------------------------- | ---------- | -------------------------------------------------------------- |
-| `speechProviders` | `string[]` | Ідентифікатори speech-провайдерів, якими володіє цей плагін. |
-| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime transcription, якими володіє цей плагін. |
-| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів realtime voice, якими володіє цей плагін. |
-| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, якими володіє цей плагін. |
-| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів image-generation, якими володіє цей плагін. |
-| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів video-generation, якими володіє цей плагін. |
-| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей плагін. |
-| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, якими володіє цей плагін. |
-| `tools` | `string[]` | Назви інструментів агента, якими володіє цей плагін, для перевірок контрактів пакетів. |
+| Поле | Тип | Що воно означає |
+| -------------------------------- | ---------- | ------------------------------------------------------------- |
+| `speechProviders` | `string[]` | id speech-provider, якими володіє цей plugin. |
+| `realtimeTranscriptionProviders` | `string[]` | id provider для realtime-transcription, якими володіє цей plugin. |
+| `realtimeVoiceProviders` | `string[]` | id provider для realtime-voice, якими володіє цей plugin. |
+| `mediaUnderstandingProviders` | `string[]` | id provider для media-understanding, якими володіє цей plugin. |
+| `imageGenerationProviders` | `string[]` | id provider для image-generation, якими володіє цей plugin. |
+| `videoGenerationProviders` | `string[]` | id provider для video-generation, якими володіє цей plugin. |
+| `webFetchProviders` | `string[]` | id provider для web-fetch, якими володіє цей plugin. |
+| `webSearchProviders` | `string[]` | id provider для web-search, якими володіє цей plugin. |
+| `tools` | `string[]` | Назви agent tool, якими володіє цей plugin для перевірок вбудованих контрактів. |
## Довідник `channelConfigs`
-Використовуйте `channelConfigs`, коли плагіну каналу потрібні легкі метадані конфігурації до
-завантаження середовища виконання.
+Використовуйте `channelConfigs`, коли plugin channel потребує недорогих метаданих конфігурації до
+завантаження runtime.
```json
{
@@ -389,28 +398,27 @@ OpenClaw читає це до завантаження середовища ви
}
},
"label": "Matrix",
- "description": "Підключення до homeserver Matrix",
+ "description": "Matrix homeserver connection",
"preferOver": ["matrix-legacy"]
}
}
}
```
-Кожен запис каналу може містити:
+Кожен запис channel може містити:
-| Поле | Тип | Що воно означає |
-| ------------- | ------------------------ | ---------------------------------------------------------------------------------------- |
-| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. |
-| `uiHints` | `Record` | Необов’язкові підписи UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. |
-| `label` | `string` | Підпис каналу, що об’єднується з поверхнями селектора та інспектування, коли метадані середовища виконання ще не готові. |
-| `description` | `string` | Короткий опис каналу для поверхонь інспектування та каталогу. |
-| `preferOver` | `string[]` | Застарілі або менш пріоритетні ідентифікатори плагінів, які цей канал має випереджати на поверхнях вибору. |
+| Поле | Тип | Що воно означає |
+| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
+| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації channel. |
+| `uiHints` | `Record` | Необов’язкові підписи UI/placeholders/підказки чутливості для цього розділу конфігурації channel. |
+| `label` | `string` | Підпис channel, що об’єднується в поверхні вибору та inspect, коли метадані runtime ще не готові. |
+| `description` | `string` | Короткий опис channel для поверхонь inspect і catalog. |
+| `preferOver` | `string[]` | id застарілих plugin або plugin з нижчим пріоритетом, які цей channel має випереджати в поверхнях вибору. |
## Довідник `modelSupport`
-Використовуйте `modelSupport`, коли OpenClaw має визначати ваш плагін провайдера за
-скороченими ідентифікаторами моделей, як-от `gpt-5.4` або `claude-sonnet-4.6`, до завантаження
-середовища виконання плагіна.
+Використовуйте `modelSupport`, коли OpenClaw має визначати ваш plugin provider за
+скороченими id моделей на кшталт `gpt-5.4` або `claude-sonnet-4.6` до завантаження runtime plugin.
```json
{
@@ -423,73 +431,73 @@ OpenClaw читає це до завантаження середовища ви
OpenClaw застосовує такий пріоритет:
-- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать власнику
+- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать відповідному provider
- `modelPatterns` мають вищий пріоритет за `modelPrefixes`
-- якщо збігаються один непакетний плагін і один пакетний плагін, перемагає непакетний
- плагін
-- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкажуть провайдера
+- якщо збігаються один невбудований plugin і один вбудований plugin, перемагає невбудований
+ plugin
+- решта неоднозначностей ігнорується, доки користувач або config не вкаже provider
Поля:
-| Поле | Тип | Що воно означає |
-| --------------- | ---------- | -------------------------------------------------------------------------------- |
-| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. |
-| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. |
+| Поле | Тип | Що воно означає |
+| --------------- | ---------- | ----------------------------------------------------------------------------------- |
+| `modelPrefixes` | `string[]` | Префікси, які звіряються через `startsWith` зі скороченими id моделей. |
+| `modelPatterns` | `string[]` | Джерела regex, які звіряються зі скороченими id моделей після видалення суфікса профілю. |
-Застарілі ключі можливостей верхнього рівня не рекомендовані. Використовуйте `openclaw doctor --fix`, щоб
+Застарілі ключі capability верхнього рівня застаріли. Використовуйте `openclaw doctor --fix`, щоб
перемістити `speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`,
-`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне
-завантаження маніфесту більше не розглядає ці поля верхнього рівня як
-володіння можливостями.
+`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне
+завантаження маніфесту більше не трактує ці поля верхнього рівня як
+володіння capability.
## Маніфест порівняно з package.json
-Ці два файли виконують різні завдання:
+Ці два файли виконують різні задачі:
-| Файл | Для чого його використовувати |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду плагіна |
-| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoint, обмежень встановлення, налаштування або метаданих каталогу |
+| Файл | Для чого його використовувати |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `openclaw.plugin.json` | Виявлення, валідація config, метадані варіантів auth і підказки UI, які мають існувати до запуску коду plugin |
+| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для entrypoint, обмежень встановлення, setup або метаданих catalog |
-Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило:
+Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте таке правило:
-- якщо OpenClaw повинен знати це до завантаження коду плагіна, помістіть це в `openclaw.plugin.json`
-- якщо це стосується пакування, файлів entrypoint або поведінки встановлення npm, помістіть це в `package.json`
+- якщо OpenClaw має знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json`
+- якщо це стосується пакування, entry-файлів або поведінки встановлення npm, помістіть це в `package.json`
-### Поля package.json, які впливають на виявлення
+### Поля `package.json`, які впливають на виявлення
-Деякі метадані плагіна до запуску середовища виконання навмисно зберігаються в `package.json` у блоці
+Деякі метадані plugin до запуску runtime навмисно зберігаються в `package.json` у блоці
`openclaw`, а не в `openclaw.plugin.json`.
Важливі приклади:
-| Поле | Що воно означає |
-| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `openclaw.extensions` | Оголошує власні entrypoint плагіна. |
-| `openclaw.setupEntry` | Легкий entrypoint лише для налаштування, який використовується під час онбордингу та відкладеного запуску каналу. |
-| `openclaw.channel` | Легкі метадані каталогу каналів, як-от підписи, шляхи до документації, псевдоніми та текст для вибору. |
-| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного середовища виконання каналу. |
-| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже є хоч один активний вхід?» без завантаження повного середовища виконання каналу. |
-| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення пакетних і зовнішньо опублікованих плагінів. |
-| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
-| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, із semver-нижньою межею на кшталт `>=2026.3.22`. |
-| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення пакетного плагіна, коли конфігурація недійсна. |
-| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для налаштування завантажуватися до повного плагіна каналу під час запуску. |
+| Поле | Що воно означає |
+| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `openclaw.extensions` | Оголошує власні entrypoint plugin. |
+| `openclaw.setupEntry` | Легковаговий entrypoint лише для setup, який використовується під час onboarding і відкладеного запуску channel. |
+| `openclaw.channel` | Недорогі метадані catalog channel, як-от підписи, шляхи до документації, alias і текст для вибору. |
+| `openclaw.channel.configuredState` | Легковагові метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного runtime channel. |
+| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного runtime channel. |
+| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих plugin. |
+| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
+| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із semver-нижньою межею на кшталт `>=2026.3.22`. |
+| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого plugin, коли config невалідний. |
+| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє завантажувати поверхні channel лише для setup до повного plugin channel під час startup. |
`openclaw.install.minHostVersion` застосовується під час встановлення та
-завантаження реєстру маніфестів. Недійсні значення відхиляються; новіші, але дійсні значення пропускають
-плагін на старіших хостах.
+завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають
+plugin на старіших хостах.
-`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке призначення. Воно
-не робить довільно зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам встановлення
-відновлюватися після певних застарілих збоїв оновлення пакетних плагінів, наприклад
-відсутнього шляху до пакетного плагіна або застарілого запису `channels.` для того самого
-пакетного плагіна. Непов’язані помилки конфігурації все одно блокують встановлення та спрямовують операторів
+`openclaw.install.allowInvalidConfigRecovery` є навмисно вузьким. Воно
+не робить довільно зламані config придатними до встановлення. Наразі воно лише дозволяє
+потокам встановлення відновлюватися після певних застарілих збоїв оновлення вбудованих plugin, таких як
+відсутній шлях до вбудованого plugin або застарілий запис `channels.` для цього ж
+вбудованого plugin. Не пов’язані помилки config, як і раніше, блокують встановлення та спрямовують операторів
до `openclaw doctor --fix`.
-`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки:
+`openclaw.channel.persistedAuthState` — це метадані пакета для маленького модуля перевірки:
```json
{
@@ -505,13 +513,13 @@ OpenClaw застосовує такий пріоритет:
}
```
-Використовуйте це, коли потокам налаштування, doctor або configured-state потрібна легка
-перевірка автентифікації «так/ні» до завантаження повного плагіна каналу. Цільовий експорт має бути невеликою
-функцією, яка читає лише збережений стан; не спрямовуйте його через повний barrel середовища виконання
-каналу.
+Використовуйте це, коли потоки setup, doctor або configured-state потребують недорогої перевірки auth
+у форматі так/ні до завантаження повного plugin channel. Цільовий export має бути невеликою
+функцією, яка читає лише збережений стан; не спрямовуйте її через повний barrel runtime
+channel.
-`openclaw.channel.configuredState` має ту саму форму для легких перевірок
-налаштованого стану лише через env:
+`openclaw.channel.configuredState` використовує ту саму форму для недорогих перевірок
+configured лише через env:
```json
{
@@ -527,65 +535,64 @@ OpenClaw застосовує такий пріоритет:
}
```
-Використовуйте це, коли канал може визначити налаштований стан за env або іншими невеликими
-вхідними даними, що не належать середовищу виконання. Якщо перевірка потребує повного визначення конфігурації або реального
-середовища виконання каналу, залиште цю логіку в hook `config.hasConfiguredState`
-плагіна.
+Використовуйте це, коли channel може визначити configured-state через env або інші невеликі
+вхідні дані, не пов’язані з runtime. Якщо перевірка потребує повного визначення config або реального
+runtime channel, залиште цю логіку в hook plugin `config.hasConfiguredState`.
## Вимоги до JSON Schema
-- **Кожен плагін повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію.
-- Порожня схема є допустимою (наприклад, `{ "type": "object", "additionalProperties": false }`).
-- Схеми проходять валідацію під час читання/запису конфігурації, а не під час виконання.
+- **Кожен plugin повинен містити JSON Schema**, навіть якщо він не приймає config.
+- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
+- Схеми проходять валідацію під час читання/запису config, а не під час runtime.
## Поведінка валідації
-- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено
- в маніфесті плагіна.
+- Невідомі ключі `channels.*` є **помилками**, якщо тільки id channel не оголошено
+ в маніфесті plugin.
- `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*`
- повинні посилатися на **доступні для виявлення** ідентифікатори плагінів. Невідомі ідентифікатори є **помилками**.
-- Якщо плагін установлено, але він має зламаний або відсутній маніфест чи схему,
- валідація завершується помилкою, а Doctor повідомляє про помилку плагіна.
-- Якщо конфігурація плагіна існує, але сам плагін **вимкнений**, конфігурація зберігається, і
- попередження **відображається** в Doctor та журналах.
+ мають посилатися на id plugin, які **можна виявити**. Невідомі id є **помилками**.
+- Якщо plugin встановлено, але він має зламаний або відсутній маніфест чи схему,
+ валідація завершується помилкою, а Doctor повідомляє про помилку plugin.
+- Якщо config plugin існує, але plugin **вимкнено**, config зберігається, і
+ у Doctor + логах відображається **попередження**.
-Повну схему `plugins.*` див. у [Довіднику з конфігурації](/uk/gateway/configuration).
+Дивіться [Довідник конфігурації](/uk/gateway/configuration) для повної схеми `plugins.*`.
## Примітки
-- Маніфест **обов’язковий для власних плагінів OpenClaw**, зокрема для локальних завантажень із файлової системи.
-- Середовище виконання все одно завантажує модуль плагіна окремо; маніфест використовується лише для
+- Маніфест **обов’язковий для власних Plugin OpenClaw**, зокрема для завантаження з локальної файлової системи.
+- Runtime, як і раніше, окремо завантажує модуль plugin; маніфест використовується лише для
виявлення + валідації.
-- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та
- ключі без лапок дозволені, якщо кінцеве значення все одно є об’єктом.
-- Завантажувач маніфестів читає лише задокументовані поля маніфесту. Уникайте додавання
- власних ключів верхнього рівня тут.
-- `providerAuthEnvVars` — це легкий шлях метаданих для перевірок автентифікації, валідації
- env-маркерів та подібних поверхонь автентифікації провайдерів, які не повинні запускати середовище виконання плагіна
+- Власні маніфести розбираються за допомогою JSON5, тому коментарі, завершальні коми та
+ ключі без лапок допускаються, якщо кінцеве значення все одно є об’єктом.
+- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання
+ власних ключів верхнього рівня.
+- `providerAuthEnvVars` — це недорогий шлях метаданих для перевірок auth, валідації
+ env-маркерів та подібних поверхонь auth provider, які не повинні запускати runtime plugin
лише для перевірки назв env.
-- `providerAuthAliases` дозволяє варіантам провайдерів повторно використовувати env vars автентифікації іншого провайдера,
- профілі автентифікації, автентифікацію на основі конфігурації та варіант
- онбордингу з API-ключем без жорсткого кодування цього зв’язку в core.
-- `channelEnvVars` — це легкий шлях метаданих для резервного використання shell-env, підказок
- налаштування та подібних поверхонь каналів, які не повинні запускати середовище виконання плагіна
+- `providerAuthAliases` дозволяє варіантам provider повторно використовувати auth
+ env vars, профілі auth, auth на основі config та варіант onboarding API key іншого provider
+ без жорсткого кодування цього зв’язку в core.
+- `channelEnvVars` — це недорогий шлях метаданих для fallback через shell-env, запитів setup
+ та подібних поверхонь channel, які не повинні запускати runtime plugin
лише для перевірки назв env.
-- `providerAuthChoices` — це легкий шлях метаданих для селекторів варіантів автентифікації,
- визначення `--auth-choice`, зіставлення пріоритетного провайдера та простої реєстрації
- прапорців CLI онбордингу до завантаження середовища виконання провайдера. Щодо метаданих
- майстра середовища виконання, які потребують коду провайдера, див.
- [Хуки середовища виконання провайдера](/uk/plugins/architecture#provider-runtime-hooks).
-- Ексклюзивні типи плагінів вибираються через `plugins.slots.*`.
+- `providerAuthChoices` — це недорогий шлях метаданих для засобів вибору варіантів auth,
+ визначення `--auth-choice`, зіставлення preferred-provider і простої реєстрації
+ прапорців CLI для onboarding до завантаження runtime provider. Для метаданих wizard runtime,
+ які потребують коду provider, див.
+ [Hook runtime provider](/uk/plugins/architecture#provider-runtime-hooks).
+- Ексклюзивні типи plugin вибираються через `plugins.slots.*`.
- `kind: "memory"` вибирається через `plugins.slots.memory`.
- `kind: "context-engine"` вибирається через `plugins.slots.contextEngine`
(типово: вбудований `legacy`).
-- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, коли
- плагіну вони не потрібні.
-- Якщо ваш плагін залежить від власних модулів, задокументуйте кроки збирання та всі
+- `channels`, `providers`, `cliBackends` і `skills` можна пропустити, якщо
+ plugin їх не потребує.
+- Якщо ваш plugin залежить від native-модулів, задокументуйте кроки збирання та всі
вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts`
- `pnpm rebuild `).
## Пов’язане
-- [Створення плагінів](/uk/plugins/building-plugins) — початок роботи з плагінами
-- [Архітектура плагінів](/uk/plugins/architecture) — внутрішня архітектура
-- [Огляд SDK](/uk/plugins/sdk-overview) — довідник Plugin SDK
+- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з plugins
+- [Архітектура Plugin](/uk/plugins/architecture) — внутрішня архітектура
+- [Огляд SDK](/uk/plugins/sdk-overview) — довідник SDK Plugin