diff --git a/docs/uk/plugins/architecture.md b/docs/uk/plugins/architecture.md
index c6a9d1b7c..cd25a87a8 100644
--- a/docs/uk/plugins/architecture.md
+++ b/docs/uk/plugins/architecture.md
@@ -3,183 +3,173 @@ read_when:
- Створення або налагодження нативних плагінів OpenClaw
- Розуміння моделі можливостей плагінів або меж володіння
- Робота над конвеєром завантаження плагінів або реєстром
- - Реалізація хуків середовища виконання постачальника або плагінів каналів
+ - Реалізація хуків середовища виконання провайдера або плагінів каналів
sidebarTitle: Internals
-summary: 'Внутрішня структура плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби середовища виконання'
-title: Внутрішня структура плагінів
+summary: 'Внутрішні компоненти плагінів: модель можливостей, володіння, контракти, конвеєр завантаження та допоміжні засоби середовища виконання'
+title: Внутрішні компоненти плагінів
x-i18n:
- generated_at: "2026-04-11T11:37:27Z"
+ generated_at: "2026-04-12T02:30:58Z"
model: gpt-5.4
provider: openai
- source_hash: 7cac67984d0d729c0905bcf5c18372fb0d9b02bbd3a531580b7e2ef483ef40a6
+ source_hash: 6165a9da8b40de3bb7334fcb16023da5515deb83c4897ca1df1726f4a97db9e0
source_path: plugins/architecture.md
workflow: 15
---
-# Внутрішня структура плагінів
+# Внутрішні компоненти плагінів
- Це **довідник із глибокої архітектури**. Практичні посібники дивіться тут:
- - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник для користувача
- - [Початок роботи](/uk/plugins/building-plugins) — перший посібник зі створення плагіна
+ Це **поглиблений довідник з архітектури**. Практичні посібники дивіться тут:
+ - [Встановлення та використання плагінів](/uk/tools/plugin) — посібник для користувачів
+ - [Початок роботи](/uk/plugins/building-plugins) — перший навчальний матеріал зі створення плагіна
- [Плагіни каналів](/uk/plugins/sdk-channel-plugins) — створення каналу обміну повідомленнями
- - [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) — створення постачальника моделей
- - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпортів і API реєстрації
+ - [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) — створення провайдера моделей
+ - [Огляд SDK](/uk/plugins/sdk-overview) — карта імпорту та API реєстрації
-Ця сторінка описує внутрішню архітектуру системи плагінів OpenClaw.
+На цій сторінці описано внутрішню архітектуру системи плагінів OpenClaw.
## Публічна модель можливостей
-Можливості — це публічна модель **нативних плагінів** усередині OpenClaw. Кожен
+Можливості — це публічна модель **нативних плагінів** всередині OpenClaw. Кожен
нативний плагін OpenClaw реєструється для одного або кількох типів можливостей:
-| Можливість | Метод реєстрації | Приклади плагінів |
-| --------------------- | ---------------------------------------------- | ------------------------------------ |
-| Текстовий інференс | `api.registerProvider(...)` | `openai`, `anthropic` |
-| CLI-бекенд інференсу | `api.registerCliBackend(...)` | `openai`, `anthropic` |
-| Мовлення | `api.registerSpeechProvider(...)` | `elevenlabs`, `microsoft` |
-| Транскрибування в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | `openai` |
+| Можливість | Метод реєстрації | Приклади плагінів |
+| ---------------------- | --------------------------------------------- | ------------------------------------ |
+| Текстовий висновок | `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.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` |
Плагін, який не реєструє жодної можливості, але надає хуки, інструменти або
-служби, є **застарілим плагіном лише з хуками**. Цей шаблон усе ще повністю підтримується.
+сервіси, є **застарілим плагіном лише з хуками**. Цей шаблон і далі повністю підтримується.
### Позиція щодо зовнішньої сумісності
-Модель можливостей уже впроваджена в core і сьогодні використовується
+Модель можливостей уже впроваджена в ядрі та сьогодні використовується
вбудованими/нативними плагінами, але сумісність із зовнішніми плагінами все ще
-потребує вищої планки, ніж «це експортується, отже це зафіксовано».
+потребує вищої планки, ніж «це експортується, отже це вже незмінний контракт».
Поточні рекомендації:
-- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі хуків; розглядайте
- це як базовий рівень сумісності
-- **нові вбудовані/нативні плагіни:** надавайте перевагу явній реєстрації можливостей замість
- vendor-specific доступу до внутрішніх частин або нових рішень лише з хуками
-- **зовнішні плагіни, що переходять на реєстрацію можливостей:** це дозволено, але
- вважайте допоміжні поверхні, специфічні для можливостей, такими, що еволюціонують, якщо в документації контракт явно не позначено як стабільний
+- **наявні зовнішні плагіни:** зберігайте працездатність інтеграцій на основі хуків; вважайте це базовим рівнем сумісності
+- **нові вбудовані/нативні плагіни:** надавайте перевагу явній реєстрації можливостей замість vendor-специфічних проникнень усередину або нових дизайнів лише з хуками
+- **зовнішні плагіни, що переходять на реєстрацію можливостей:** це дозволено, але вважайте допоміжні поверхні, специфічні для можливостей, такими, що ще розвиваються, якщо в документації контракт не позначено явно як стабільний
Практичне правило:
-- API реєстрації можливостей — це цільовий напрямок
-- застарілі хуки залишаються найбезпечнішим шляхом без поломок для зовнішніх плагінів під час
- переходу
-- не всі експортовані підшляхи однакові; віддавайте перевагу вузькому документованому
- контракту, а не випадковим допоміжним експортам
+- API реєстрації можливостей — це бажаний напрям
+- застарілі хуки залишаються найбезпечнішим шляхом без порушення сумісності для зовнішніх плагінів під час переходу
+- не всі експортовані допоміжні підшляхи однаково важливі; віддавайте перевагу вузькому задокументованому контракту, а не випадковим допоміжним експортам
### Форми плагінів
OpenClaw класифікує кожен завантажений плагін за формою на основі його фактичної
-поведінки під час реєстрації, а не лише статичних метаданих:
+поведінки реєстрації (а не лише статичних метаданих):
-- **plain-capability** -- реєструє рівно один тип можливості (наприклад,
- плагін лише постачальника, як-от `mistral`)
-- **hybrid-capability** -- реєструє кілька типів можливостей (наприклад,
- `openai` володіє текстовим інференсом, мовленням, розумінням медіа та
- генерацією зображень)
-- **hook-only** -- реєструє лише хуки (типізовані або власні), без можливостей,
- інструментів, команд чи служб
-- **non-capability** -- реєструє інструменти, команди, служби або маршрути, але без
- можливостей
+- **plain-capability** -- реєструє рівно один тип можливості (наприклад, плагін лише провайдера, такий як `mistral`)
+- **hybrid-capability** -- реєструє кілька типів можливостей (наприклад, `openai` володіє текстовим висновком, мовленням, розумінням медіа та генерацією зображень)
+- **hook-only** -- реєструє лише хуки (типізовані або користувацькі), без можливостей, інструментів, команд чи сервісів
+- **non-capability** -- реєструє інструменти, команди, сервіси або маршрути, але не можливості
-Використовуйте `openclaw plugins inspect `, щоб переглянути форму плагіна та
-розподіл можливостей. Докладніше дивіться в [довіднику CLI](/cli/plugins#inspect).
+Використовуйте `openclaw plugins inspect `, щоб побачити форму плагіна та
+розподіл за можливостями. Докладніше дивіться у [довідці CLI](/cli/plugins#inspect).
### Застарілі хуки
-Хук `before_agent_start` і далі підтримується як шлях сумісності для
-плагінів лише з хуками. На нього досі спираються реальні застарілі плагіни.
+Хук `before_agent_start` і далі підтримується як шлях сумісності для плагінів
+лише з хуками. Від нього все ще залежать застарілі реальні плагіни.
Напрямок:
- зберігати його працездатність
- документувати його як застарілий
-- для роботи з перевизначенням моделі/постачальника надавати перевагу `before_model_resolve`
-- для зміни prompt надавати перевагу `before_prompt_build`
-- видаляти лише після падіння реального використання та коли покриття фікстурами підтвердить безпечність міграції
+- надавати перевагу `before_model_resolve` для роботи з перевизначенням моделі/провайдера
+- надавати перевагу `before_prompt_build` для роботи з мутацією промпта
+- видаляти лише після зниження реального використання та підтвердження безпечності міграції покриттям через фікстури
### Сигнали сумісності
-Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете
-побачити одну з таких позначок:
+Коли ви запускаєте `openclaw doctor` або `openclaw plugins inspect `, ви можете побачити
+одну з таких міток:
| Сигнал | Значення |
| -------------------------- | ------------------------------------------------------------ |
-| **config valid** | Конфігурація коректно розбирається, а плагіни успішно визначаються |
+| **config valid** | Конфігурація успішно розбирається, а плагіни коректно визначаються |
| **compatibility advisory** | Плагін використовує підтримуваний, але старіший шаблон (наприклад, `hook-only`) |
-| **legacy warning** | Плагін використовує `before_agent_start`, який є застарілим |
-| **hard error** | Конфігурація некоректна або плагін не вдалося завантажити |
+| **legacy warning** | Плагін використовує `before_agent_start`, який є застарілим |
+| **hard error** | Конфігурація недійсна або не вдалося завантажити плагін |
-Ані `hook-only`, ані `before_agent_start` не зламають ваш плагін сьогодні --
-`hook-only` має дорадчий характер, а `before_agent_start` лише викликає попередження. Ці
+Ані `hook-only`, ані `before_agent_start` сьогодні не зламають ваш плагін --
+`hook-only` є рекомендаційним сигналом, а `before_agent_start` лише спричиняє попередження. Ці
сигнали також з’являються в `openclaw status --all` і `openclaw plugins doctor`.
## Огляд архітектури
-Система плагінів OpenClaw має чотири рівні:
+Система плагінів OpenClaw має чотири шари:
1. **Маніфест + виявлення**
- OpenClaw знаходить кандидатів у плагіни за налаштованими шляхами, коренями workspace,
- глобальними коренями розширень і вбудованими розширеннями. Під час виявлення спочатку читаються
- нативні маніфести `openclaw.plugin.json` і підтримувані маніфести bundle.
+ OpenClaw знаходить потенційні плагіни в налаштованих шляхах, коренях робочих просторів,
+ глобальних коренях розширень і вбудованих розширеннях. Виявлення спочатку зчитує
+ нативні маніфести `openclaw.plugin.json` разом із підтримуваними маніфестами збірок.
2. **Увімкнення + валідація**
- Core вирішує, чи знайдений плагін увімкнено, вимкнено, заблоковано, чи
+ Ядро визначає, чи виявлений плагін увімкнено, вимкнено, заблоковано, чи
вибрано для ексклюзивного слота, наприклад пам’яті.
-3. **Завантаження в середовищі виконання**
+3. **Завантаження під час виконання**
Нативні плагіни OpenClaw завантажуються в межах процесу через jiti і реєструють
- можливості в центральному реєстрі. Сумісні bundle нормалізуються в записи
+ можливості в центральному реєстрі. Сумісні збірки нормалізуються в записи
реєстру без імпорту коду середовища виконання.
4. **Споживання поверхонь**
- Решта OpenClaw читає реєстр, щоб надати інструменти, канали, налаштування постачальників,
- хуки, HTTP-маршрути, команди CLI та служби.
+ Решта OpenClaw читає реєстр, щоб надавати інструменти, канали, налаштування провайдерів,
+ хуки, HTTP-маршрути, команди CLI та сервіси.
-Для CLI плагінів зокрема виявлення кореневих команд поділено на дві фази:
+Спеціально для CLI плагінів виявлення кореневих команд розділено на дві фази:
-- метадані часу розбору надходять із `registerCli(..., { descriptors: [...] })`
-- справжній модуль CLI плагіна може залишатися ледачим і реєструватися під час першого виклику
+- метадані під час розбору надходять із `registerCli(..., { descriptors: [...] })`
+- реальний модуль CLI плагіна може залишатися лінивим і реєструватися під час першого виклику
-Це дозволяє зберігати CLI-код, що належить плагіну, всередині плагіна й водночас дає OpenClaw
-змогу зарезервувати імена кореневих команд до початку розбору.
+Це дозволяє зберігати код CLI, що належить плагіну, всередині самого плагіна,
+водночас даючи змогу OpenClaw резервувати імена кореневих команд до початку розбору.
Важлива межа проєктування:
-- виявлення + валідація конфігурації мають працювати на основі **метаданих маніфесту/схеми**
+- виявлення та валідація конфігурації мають працювати з **метаданих маніфесту/схеми**
без виконання коду плагіна
-- нативна поведінка середовища виконання надходить із шляху `register(api)` модуля плагіна
+- нативна поведінка під час виконання надходить зі шляху `register(api)` модуля плагіна
-Таке розділення дає OpenClaw змогу валідовувати конфігурацію, пояснювати відсутні/вимкнені плагіни та
-будувати підказки для UI/схеми ще до повної активації середовища виконання.
+Такий поділ дає OpenClaw змогу перевіряти конфігурацію, пояснювати відсутні/вимкнені плагіни та
+будувати підказки для UI/схеми до активації повного середовища виконання.
### Плагіни каналів і спільний інструмент повідомлень
-Плагінам каналів не потрібно реєструвати окремий інструмент надсилання/редагування/реакції для
-звичайних дій у чаті. OpenClaw зберігає один спільний інструмент `message` у core, а
-плагіни каналів володіють специфічними для каналу виявленням і виконанням за ним.
+Плагінам каналів не потрібно реєструвати окремий інструмент send/edit/react для
+звичайних дій у чаті. OpenClaw підтримує один спільний інструмент `message` у ядрі,
+а плагіни каналів володіють специфічним для каналу виявленням і виконанням за ним.
Поточна межа така:
-- core володіє хостом спільного інструмента `message`, підключенням до prompt,
- обліком сесій/тредів і диспетчеризацією виконання
-- плагіни каналів володіють виявленням дій у межах області, виявленням
- можливостей і будь-якими фрагментами схеми, специфічними для каналу
-- плагіни каналів володіють граматикою розмов сесії, специфічною для постачальника, зокрема
- тим, як id розмов кодують id тредів або успадковуються від батьківських розмов
-- плагіни каналів виконують фінальну дію через свій адаптер дій
+- ядро володіє хостом спільного інструмента `message`, прив’язкою до промпта, обліком сесій/гілок
+ і диспетчеризацією виконання
+- плагіни каналів володіють виявленням дій в обмеженій області, виявленням можливостей і будь-якими
+ фрагментами схеми, специфічними для каналу
+- плагіни каналів володіють граматикою сесійної розмови, специфічною для провайдера, наприклад тим,
+ як ідентифікатори розмов кодують ідентифікатори гілок або успадковуються від батьківських розмов
+- плагіни каналів виконують кінцеву дію через свій адаптер дій
-Для плагінів каналів поверхнею SDK є
-`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик виявлення
-дозволяє плагіну повертати свої видимі дії, можливості та внески в схему
+Для плагінів каналів поверхня SDK — це
+`ChannelMessageActionAdapter.describeMessageTool(...)`. Цей уніфікований виклик
+виявлення дає плагіну змогу повертати його видимі дії, можливості та внески в схему
разом, щоб ці частини не розходилися.
-Core передає область середовища виконання на цей крок виявлення. Важливі поля включають:
+Ядро передає область виконання в цей крок виявлення. Важливі поля включають:
- `accountId`
- `currentChannelId`
@@ -190,124 +180,124 @@ Core передає область середовища виконання на
- `agentId`
- довірений вхідний `requesterSenderId`
-Це важливо для контекстно-чутливих плагінів. Канал може приховувати або відкривати
-дії з повідомленнями залежно від активного облікового запису, поточної кімнати/треду/повідомлення або
-довіреної ідентичності запитувача без жорстко закодованих гілок, специфічних для каналу, у
-core-інструменті `message`.
+Це важливо для контекстно-залежних плагінів. Канал може приховувати або показувати
+дії з повідомленнями залежно від активного облікового запису, поточної кімнати/гілки/повідомлення або
+довіреної ідентичності запитувача без жорстко закодованих розгалужень, специфічних для каналу,
+в основному інструменті `message`.
-Саме тому зміни маршрутизації embedded-runner усе ще залишаються роботою плагіна: runner
-відповідає за передавання поточної ідентичності чату/сесії в межу виявлення плагіна, щоб
-спільний інструмент `message` відкривав правильну поверхню, що належить каналу,
-для поточного ходу.
+Саме тому зміни маршрутизації embedded-runner усе ще є роботою плагінів: виконавець
+відповідає за пересилання поточної ідентичності чату/сесії до межі виявлення плагіна, щоб
+спільний інструмент `message` надавав правильну поверхню, що належить каналу,
+для поточного кроку.
-Для допоміжних засобів виконання, що належать каналу, вбудовані плагіни мають зберігати
-runtime виконання всередині власних модулів розширення. Core більше не володіє
-runtime дій повідомлень Discord, Slack, Telegram або WhatsApp у `src/agents/tools`.
-Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, а вбудовані
-плагіни мають імпортувати свій локальний runtime-код безпосередньо зі своїх
+Для допоміжних засобів виконання, що належать каналу, вбудовані плагіни мають
+тримати середовище виконання всередині власних модулів розширення. Ядро більше не володіє
+середовищами виконання дій з повідомленнями Discord, Slack, Telegram або WhatsApp у `src/agents/tools`.
+Ми не публікуємо окремі підшляхи `plugin-sdk/*-action-runtime`, і вбудовані
+плагіни мають імпортувати свій локальний код середовища виконання безпосередньо зі своїх
модулів, що належать розширенню.
-Та сама межа застосовується і до SDK-швів із назвами постачальників загалом: core не має
-імпортувати зручні barrel-модулі, специфічні для каналів Slack, Discord, Signal,
-WhatsApp або подібних розширень. Якщо core потрібна певна поведінка, слід або
-використати власний barrel `api.ts` / `runtime-api.ts` вбудованого плагіна, або підняти цю потребу
-до вузької загальної можливості в спільному SDK.
+Та сама межа застосовується до іменованих за провайдерами поверхонь SDK загалом: ядро не повинно
+імпортувати зручні барелі, специфічні для каналу, для Slack, Discord, Signal,
+WhatsApp або подібних розширень. Якщо ядру потрібна певна поведінка, воно має або
+використовувати власний барель `api.ts` / `runtime-api.ts` вбудованого плагіна, або
+підняти цю потребу до вузької загальної можливості в спільному SDK.
-Зокрема для опитувань є два шляхи виконання:
+Спеціально для опитувань є два шляхи виконання:
-- `outbound.sendPoll` — спільна базова лінія для каналів, які відповідають загальній
+- `outbound.sendPoll` — це спільна базова лінія для каналів, які відповідають загальній
моделі опитувань
-- `actions.handleAction("poll")` — пріоритетний шлях для специфічної для каналу
- семантики опитувань або додаткових параметрів опитування
+- `actions.handleAction("poll")` — це бажаний шлях для семантики опитувань,
+ специфічної для каналу, або додаткових параметрів опитувань
-Тепер Core відкладає спільний розбір опитувань до моменту, коли диспетчеризація опитування плагіна
-відхиляє дію, тож обробники опитувань, що належать плагіну, можуть приймати специфічні для каналу
-поля опитувань, не блокуючись спершу загальним парсером опитувань.
+Тепер ядро відкладає спільний розбір опитувань доти, доки диспетчеризація опитувань плагіна
+не відхилить дію, щоб обробники опитувань, що належать плагіну, могли приймати
+специфічні для каналу поля опитувань без блокування з боку загального розбірника опитувань.
-Повну послідовність запуску дивіться в [Конвеєр завантаження](#load-pipeline).
+Повну послідовність запуску дивіться в [Конвеєрі завантаження](#load-pipeline).
## Модель володіння можливостями
OpenClaw розглядає нативний плагін як межу володіння для **компанії** або
-**функції**, а не як набір не пов’язаних між собою інтеграцій.
+**функціональності**, а не як набір не пов’язаних між собою інтеграцій.
-Це означає:
+Це означає, що:
-- плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, пов’язаними з цією компанією
-- плагін функції зазвичай має володіти повною поверхнею функції, яку він додає
-- канали мають споживати спільні можливості core, а не перевпроваджувати
- поведінку постачальника ситуативно
+- плагін компанії зазвичай має володіти всіма поверхнями OpenClaw, що стосуються цієї компанії
+- плагін функціональності зазвичай має володіти всією поверхнею цієї функціональності, яку він вводить
+- канали мають споживати спільні можливості ядра, а не довільно повторно реалізовувати
+ поведінку провайдера
Приклади:
-- вбудований плагін `openai` володіє поведінкою постачальника моделей OpenAI і поведінкою OpenAI для
- мовлення + голосу в реальному часі + розуміння медіа + генерації зображень
-- вбудований плагін `elevenlabs` володіє поведінкою мовлення ElevenLabs
-- вбудований плагін `microsoft` володіє поведінкою мовлення Microsoft
-- вбудований плагін `google` володіє поведінкою постачальника моделей Google, а також поведінкою Google для
- розуміння медіа + генерації зображень + вебпошуку
-- вбудований плагін `firecrawl` володіє поведінкою Firecrawl для веботримання
+- вбудований плагін `openai` володіє поведінкою провайдера моделей OpenAI та поведінкою OpenAI
+ для мовлення + голосу в реальному часі + розуміння медіа + генерації зображень
+- вбудований плагін `elevenlabs` володіє поведінкою ElevenLabs для мовлення
+- вбудований плагін `microsoft` володіє поведінкою Microsoft для мовлення
+- вбудований плагін `google` володіє поведінкою провайдера моделей Google, а також поведінкою Google
+ для розуміння медіа + генерації зображень + вебпошуку
+- вбудований плагін `firecrawl` володіє поведінкою Firecrawl для отримання вебданих
- вбудовані плагіни `minimax`, `mistral`, `moonshot` і `zai` володіють своїми
- бекендами розуміння медіа
-- вбудований плагін `qwen` володіє поведінкою текстового постачальника Qwen, а також
- поведінкою розуміння медіа і генерації відео
-- плагін `voice-call` — це плагін функції: він володіє транспортом викликів, інструментами,
+ серверними частинами розуміння медіа
+- вбудований плагін `qwen` володіє поведінкою текстового провайдера Qwen, а також
+ поведінкою для розуміння медіа та генерації відео
+- плагін `voice-call` — це плагін функціональності: він володіє транспортом викликів, інструментами,
CLI, маршрутами та мостом Twilio media-stream, але споживає спільні можливості мовлення,
- а також транскрибування і голосу в реальному часі, замість прямого імпорту vendor-плагінів
+ а також транскрипції в реальному часі і голосу в реальному часі замість прямого імпорту vendor-плагінів
-Цільовий кінцевий стан такий:
+Бажаний кінцевий стан:
-- OpenAI знаходиться в одному плагіні, навіть якщо він охоплює текстові моделі, мовлення, зображення та
+- OpenAI розміщується в одному плагіні, навіть якщо він охоплює текстові моделі, мовлення, зображення та
майбутнє відео
-- інший вендор може зробити те саме для власної області поверхонь
-- канали не цікавить, який саме плагін вендора володіє постачальником; вони споживають
- спільний контракт можливостей, який надає core
+- інший постачальник може зробити те саме для своєї власної поверхні
+- канали не зважають на те, який плагін постачальника володіє провайдером; вони споживають
+ спільний контракт можливості, який надає ядро
-Це ключова відмінність:
+Ось ключова відмінність:
- **plugin** = межа володіння
-- **capability** = контракт core, який можуть реалізовувати або споживати кілька плагінів
+- **capability** = контракт ядра, який можуть реалізовувати або споживати кілька плагінів
-Тому, якщо OpenClaw додає нову доменну область, наприклад відео, перше запитання не
-«який постачальник має жорстко закодувати обробку відео?» Перше запитання — «яким є
-контракт core для можливості відео?» Щойно такий контракт з’являється, плагіни вендорів
-можуть реєструватися для нього, а плагіни каналів/функцій — споживати його.
+Тому якщо OpenClaw додає нову область, наприклад відео, перше запитання не
+«який провайдер має жорстко закодувати обробку відео?» Перше запитання таке: «який
+контракт можливості відео в ядрі?» Щойно такий контракт з’являється, плагіни постачальників
+можуть реєструватися для нього, а плагіни каналів/функцій можуть його споживати.
-Якщо можливість ще не існує, зазвичай правильний крок такий:
+Якщо можливість ще не існує, правильний крок зазвичай такий:
-1. визначити відсутню можливість у core
-2. відкрити її через API/runtime плагінів у типізований спосіб
-3. підключити канали/функції до цієї можливості
-4. дати плагінам вендорів зареєструвати реалізації
+1. визначити відсутню можливість у ядрі
+2. відкрити її через API/середовище виконання плагінів у типізований спосіб
+3. під’єднати канали/функції до цієї можливості
+4. дозволити плагінам постачальників реєструвати реалізації
-Це зберігає явне володіння й водночас уникає поведінки core, яка залежить від
-одного вендора або одноразового специфічного шляху коду плагіна.
+Це робить володіння явним і водночас уникає поведінки ядра, яка залежить від
+одного постачальника або одноразового шляху коду, специфічного для плагіна.
### Шарування можливостей
-Використовуйте цю ментальну модель, коли вирішуєте, де має розміщуватися код:
+Використовуйте цю ментальну модель, коли вирішуєте, де має бути код:
-- **рівень можливостей core**: спільна оркестрація, політики, резервна логіка, правила
- злиття конфігурації, семантика доставки та типізовані контракти
-- **рівень плагіна вендора**: API вендора, автентифікація, каталоги моделей, синтез
- мовлення, генерація зображень, майбутні відеобекенди, endpoints використання
-- **рівень плагіна каналу/функції**: інтеграція Slack/Discord/voice-call тощо,
- яка споживає можливості core і представляє їх на певній поверхні
+- **шар можливостей ядра**: спільна оркестрація, політики, резервні механізми, правила
+ об’єднання конфігурації, семантика доставки та типізовані контракти
+- **шар плагіна постачальника**: API постачальника, автентифікація, каталоги моделей, синтез мовлення,
+ генерація зображень, майбутні серверні частини відео, кінцеві точки використання
+- **шар плагіна каналу/функції**: інтеграція Slack/Discord/voice-call тощо,
+ яка споживає можливості ядра та відображає їх на певній поверхні
Наприклад, TTS має таку форму:
-- core володіє політикою TTS під час відповіді, порядком резервного вибору, налаштуваннями й доставкою в канали
+- ядро володіє політикою TTS під час відповіді, порядком резервування, налаштуваннями та доставкою в канали
- `openai`, `elevenlabs` і `microsoft` володіють реалізаціями синтезу
-- `voice-call` споживає допоміжний засіб runtime для TTS у телефонії
+- `voice-call` споживає допоміжний засіб середовища виконання телефонного TTS
-Для майбутніх можливостей слід надавати перевагу саме цьому шаблону.
+Того самого шаблону слід надавати перевагу й для майбутніх можливостей.
### Приклад плагіна компанії з кількома можливостями
-Плагін компанії має виглядати цілісно ззовні. Якщо в OpenClaw є спільні
-контракти для моделей, мовлення, транскрибування в реальному часі, голосу в реальному часі, розуміння медіа,
-генерації зображень, генерації відео, веботримання та вебпошуку,
-вендор може володіти всіма своїми поверхнями в одному місці:
+Плагін компанії має виглядати цілісно ззовні. Якщо OpenClaw має спільні
+контракти для моделей, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа,
+генерації зображень, генерації відео, отримання вебданих і вебпошуку,
+постачальник може володіти всіма своїми поверхнями в одному місці:
```ts
import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
@@ -363,130 +353,132 @@ export default plugin;
Важливі не точні назви допоміжних засобів. Важлива форма:
-- один плагін володіє поверхнею вендора
-- core усе ще володіє контрактами можливостей
-- канали та плагіни функцій споживають допоміжні засоби `api.runtime.*`, а не код вендора
+- один плагін володіє поверхнею постачальника
+- ядро, як і раніше, володіє контрактами можливостей
+- канали та плагіни функцій споживають допоміжні засоби `api.runtime.*`, а не код постачальника
- контрактні тести можуть перевіряти, що плагін зареєстрував можливості, якими
він стверджує, що володіє
### Приклад можливості: розуміння відео
OpenClaw уже розглядає розуміння зображень/аудіо/відео як одну спільну
-можливість. До неї застосовується та сама модель володіння:
+можливість. Та сама модель володіння застосовується й тут:
-1. core визначає контракт розуміння медіа
-2. плагіни вендорів реєструють `describeImage`, `transcribeAudio` та
+1. ядро визначає контракт media-understanding
+2. плагіни постачальників реєструють `describeImage`, `transcribeAudio` і
`describeVideo`, де це застосовно
-3. канали та плагіни функцій споживають спільну поведінку core замість
- прямого підключення до коду вендора
+3. канали та плагіни функцій споживають спільну поведінку ядра замість
+ прямого підключення до коду постачальника
-Це запобігає вбудовуванню в core відеоприпущень одного постачальника. Плагін володіє
-поверхнею вендора; core володіє контрактом можливості та резервною поведінкою.
+Це не дає вбудувати в ядро припущення одного провайдера щодо відео. Плагін володіє
+поверхнею постачальника; ядро володіє контрактом можливості та резервною поведінкою.
-Генерація відео вже використовує ту саму послідовність: core володіє типізованим
-контрактом можливості та допоміжним засобом runtime, а плагіни вендорів реєструють
+Генерація відео вже використовує ту саму послідовність: ядро володіє типізованим
+контрактом можливості та допоміжним засобом середовища виконання, а плагіни постачальників реєструють
реалізації `api.registerVideoGenerationProvider(...)` для цього контракту.
-Потрібен конкретний контрольний список для впровадження? Дивіться
-[Збірник рецептів для можливостей](/uk/plugins/architecture).
+Потрібен конкретний контрольний список розгортання? Дивіться
+[Збірник рецептів можливостей](/uk/plugins/architecture).
-## Контракти та забезпечення їх дотримання
+## Контракти та контроль
-Поверхня API плагінів навмисно типізована й централізована в
+Поверхня API плагінів навмисно типізована та централізована в
`OpenClawPluginApi`. Цей контракт визначає підтримувані точки реєстрації та
-допоміжні засоби runtime, на які може спиратися плагін.
+допоміжні засоби середовища виконання, на які може покладатися плагін.
Чому це важливо:
- автори плагінів отримують один стабільний внутрішній стандарт
-- core може відхиляти дубльоване володіння, наприклад коли два плагіни реєструють однаковий id постачальника
-- під час запуску можна показувати діагностику з практичними підказками для некоректної реєстрації
+- ядро може відхиляти дублювання володіння, наприклад коли два плагіни реєструють однаковий
+ id провайдера
+- під час запуску можна показувати придатні до дії діагностичні повідомлення для хибної реєстрації
- контрактні тести можуть забезпечувати володіння вбудованих плагінів і запобігати тихому дрейфу
-Є два рівні забезпечення дотримання:
+Є два рівні контролю:
-1. **забезпечення під час реєстрації в runtime**
- Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Наприклад:
- дубльовані id постачальників, дубльовані id постачальників мовлення та некоректні
- реєстрації породжують діагностику плагіна замість невизначеної поведінки.
+1. **контроль реєстрації під час виконання**
+ Реєстр плагінів перевіряє реєстрації під час завантаження плагінів. Приклади:
+ дубльовані id провайдерів, дубльовані id провайдерів мовлення та хибні
+ реєстрації спричиняють діагностику плагінів замість невизначеної поведінки.
2. **контрактні тести**
- Вбудовані плагіни фіксуються в контрактних реєстрах під час тестових запусків, щоб
- OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для модельних
- постачальників, постачальників мовлення, постачальників вебпошуку та володіння
+ Вбудовані плагіни фіксуються в контрактних реєстрах під час виконання тестів, щоб
+ OpenClaw міг явно перевіряти володіння. Сьогодні це використовується для
+ провайдерів моделей, провайдерів мовлення, провайдерів вебпошуку та володіння
реєстрацією вбудованих плагінів.
-Практичний ефект полягає в тому, що OpenClaw заздалегідь знає, який плагін якою
-поверхнею володіє. Це дає core і каналам змогу безшовно компонуватися, бо володіння
-задеклароване, типізоване та перевірюване, а не неявне.
+Практичний ефект полягає в тому, що OpenClaw наперед знає, який плагін якою
+поверхнею володіє. Це дозволяє ядру та каналам безшовно компонуватися, адже
+володіння оголошене, типізоване й придатне до перевірки, а не неявне.
-### Що має належати до контракту
+### Що має належати контракту
Хороші контракти плагінів:
- типізовані
- невеликі
- специфічні для можливості
-- належать core
-- придатні для повторного використання кількома плагінами
-- можуть споживатися каналами/функціями без знання вендора
+- належать ядру
+- придатні до повторного використання кількома плагінами
+- можуть споживатися каналами/функціями без знання постачальника
Погані контракти плагінів:
-- специфічна для вендора політика, прихована в core
-- одноразові лазівки для плагінів, які обходять реєстр
-- код каналу, що напряму звертається до реалізації вендора
-- ситуативні об’єкти runtime, які не є частиною `OpenClawPluginApi` або
+- політика, специфічна для постачальника, прихована в ядрі
+- одноразові аварійні виходи для плагіна, які обходять реєстр
+- код каналу, який напряму звертається до реалізації постачальника
+- довільні об’єкти середовища виконання, які не є частиною `OpenClawPluginApi` або
`api.runtime`
-Якщо є сумніви, підніміть рівень абстракції: спочатку визначте можливість, а вже потім
+Якщо сумніваєтеся, підніміть рівень абстракції: спочатку визначте можливість, а вже потім
дозвольте плагінам підключатися до неї.
## Модель виконання
Нативні плагіни OpenClaw працюють **у межах процесу** разом із Gateway. Вони не
ізольовані. Завантажений нативний плагін має ту саму межу довіри на рівні процесу, що
-й код core.
+й код ядра.
Наслідки:
-- нативний плагін може реєструвати інструменти, мережеві обробники, хуки та служби
-- помилка нативного плагіна може аварійно завершити роботу gateway або дестабілізувати її
-- зловмисний нативний плагін еквівалентний довільному виконанню коду всередині процесу OpenClaw
+- нативний плагін може реєструвати інструменти, мережеві обробники, хуки та сервіси
+- помилка нативного плагіна може аварійно завершити роботу gateway або дестабілізувати його
+- зловмисний нативний плагін еквівалентний довільному виконанню коду всередині
+ процесу OpenClaw
-Сумісні bundle за замовчуванням безпечніші, тому що OpenClaw наразі розглядає їх
-як пакети метаданих/контенту. У поточних релізах це переважно означає
+Сумісні збірки безпечніші за замовчуванням, оскільки OpenClaw наразі розглядає їх
+як пакети метаданих/контенту. У поточних випусках це здебільшого означає
вбудовані Skills.
-Для невбудованих плагінів використовуйте allowlist і явні шляхи встановлення/завантаження. Розглядайте
-workspace-плагіни як код для часу розробки, а не як виробничі значення за замовчуванням.
+Використовуйте списки дозволу та явні шляхи встановлення/завантаження для невбудованих плагінів. Розглядайте
+плагіни робочого простору як код для часу розробки, а не як типовий варіант для продакшну.
-Для назв пакетів вбудованого workspace зберігайте прив’язку id плагіна в назві npm:
-`@openclaw/` за замовчуванням або із затвердженим типізованим суфіксом, як-от
+Для назв пакетів вбудованого робочого простору тримайте id плагіна прив’язаним у npm-назві:
+`@openclaw/` за замовчуванням або схвалений типізований суфікс, такий як
`-provider`, `-plugin`, `-speech`, `-sandbox` чи `-media-understanding`, коли
пакет навмисно відкриває вужчу роль плагіна.
-Важлива примітка щодо довіри:
+Важлива примітка про довіру:
- `plugins.allow` довіряє **id плагінів**, а не походженню джерела.
-- Workspace-плагін із тим самим id, що й вбудований плагін, навмисно затіняє
- вбудовану копію, коли цей workspace-плагін увімкнено/додано до allowlist.
-- Це нормально й корисно для локальної розробки, тестування патчів і hotfix.
+- Плагін робочого простору з тим самим id, що й у вбудованого плагіна, навмисно затіняє
+ вбудовану копію, коли цей плагін робочого простору увімкнено/додано до списку дозволу.
+- Це нормально й корисно для локальної розробки, тестування патчів та термінових виправлень.
## Межа експорту
OpenClaw експортує можливості, а не зручні засоби реалізації.
-Зберігайте публічність реєстрації можливостей. Скорочуйте експорти допоміжних засобів, що не є контрактами:
+Тримайте реєстрацію можливостей публічною. Скорочуйте експорти допоміжних засобів, які не є контрактами:
-- підшляхи допоміжних засобів, специфічних для вбудованих плагінів
-- підшляхи внутрішньої plumbing runtime, не призначені як публічний API
-- зручні допоміжні засоби, специфічні для вендора
-- допоміжні засоби setup/onboarding, які є деталями реалізації
+- підшляхи допоміжних засобів, специфічні для вбудованих плагінів
+- підшляхи інфраструктури середовища виконання, не призначені як публічний API
+- зручні засоби, специфічні для постачальника
+- допоміжні засоби налаштування/онбордингу, які є деталями реалізації
-Деякі підшляхи допоміжних засобів вбудованих плагінів усе ще лишаються в згенерованій
-карті експортів SDK для сумісності та підтримки вбудованих плагінів. Поточні приклади включають
+Деякі підшляхи допоміжних засобів вбудованих плагінів усе ще залишаються в згенерованій
+карті експорту SDK задля сумісності та підтримки вбудованих плагінів. Поточні приклади:
`plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`,
-`plugin-sdk/zalo-setup` і кілька швів `plugin-sdk/matrix*`. Розглядайте їх як
+`plugin-sdk/zalo-setup` і кілька меж `plugin-sdk/matrix*`. Розглядайте їх як
зарезервовані експорти деталей реалізації, а не як рекомендований шаблон SDK для
нових сторонніх плагінів.
@@ -495,51 +487,57 @@ OpenClaw експортує можливості, а не зручні засо
Під час запуску OpenClaw приблизно робить таке:
1. виявляє корені кандидатів у плагіни
-2. читає нативні або сумісні маніфести bundle та метадані пакетів
+2. читає нативні маніфести або маніфести сумісних збірок і метадані пакетів
3. відхиляє небезпечних кандидатів
4. нормалізує конфігурацію плагінів (`plugins.enabled`, `allow`, `deny`, `entries`,
`slots`, `load.paths`)
-5. вирішує, чи ввімкнено кожного кандидата
-6. завантажує ввімкнені нативні модулі через jiti
-7. викликає нативні хуки `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації до реєстру плагінів
-8. відкриває реєстр для поверхонь команд/runtime
+5. вирішує питання увімкнення для кожного кандидата
+6. завантажує увімкнені нативні модулі через jiti
+7. викликає нативні хуки `register(api)` (або `activate(api)` — застарілий псевдонім) і збирає реєстрації в реєстр плагінів
+8. відкриває реєстр для поверхонь команд/середовища виконання
-`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що з них присутнє (`def.register ?? def.activate`), і викликає в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів надавайте перевагу `register`.
+`activate` — це застарілий псевдонім для `register` — завантажувач визначає, який із них присутній (`def.register ?? def.activate`), і викликає його в тій самій точці. Усі вбудовані плагіни використовують `register`; для нових плагінів надавайте перевагу `register`.
-Перевірки безпеки відбуваються **до** виконання в runtime. Кандидати блокуються,
-коли entry виходить за межі кореня плагіна, шлях доступний для запису всім, або
-володіння шляхом виглядає підозріло для невбудованих плагінів.
+Перевірки безпеки відбуваються **до** виконання коду під час виконання. Кандидати блокуються,
+коли точка входу виходить за межі кореня плагіна, шлях доступний на запис для всіх або
+право власності на шлях виглядає підозрілим для невбудованих плагінів.
### Поведінка з пріоритетом маніфесту
-Маніфест є джерелом істини для control plane. OpenClaw використовує його, щоб:
+Маніфест є джерелом істини для керівної площини. OpenClaw використовує його, щоб:
- ідентифікувати плагін
-- виявляти оголошені канали/Skills/схему конфігурації або можливості bundle
-- валідовувати `plugins.entries..config`
-- доповнювати мітки/заповнювачі Control UI
+- виявляти оголошені канали/Skills/схему конфігурації або можливості збірки
+- перевіряти `plugins.entries..config`
+- доповнювати мітки/заповнювачі в Control UI
- показувати метадані встановлення/каталогу
-- зберігати дешеві дескриптори активації та setup без завантаження runtime плагіна
+- зберігати легкі дескриптори активації та налаштування без завантаження середовища виконання плагіна
-Для нативних плагінів модуль runtime є частиною data plane. Він реєструє
-фактичну поведінку, як-от хуки, інструменти, команди або потоки постачальників.
+Для нативних плагінів модуль середовища виконання є частиною площини даних. Він реєструє
+фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера.
-Необов’язкові блоки маніфесту `activation` і `setup` залишаються в control plane.
-Це лише дескриптори метаданих для планування активації та виявлення setup;
-вони не замінюють реєстрацію runtime, `register(...)` або `setupEntry`.
+Необов’язкові блоки маніфесту `activation` і `setup` залишаються в керівній площині.
+Це лише дескриптори метаданих для планування активації та виявлення налаштування;
+вони не замінюють реєстрацію під час виконання, `register(...)` або `setupEntry`.
+
+Тепер виявлення налаштування віддає перевагу id, що належать дескрипторам, таким як
+`setup.providers` і `setup.cliBackends`, щоб звузити коло кандидатів у плагіни до того, як воно повернеться до
+`setup-api` для плагінів, яким усе ще потрібні хуки середовища виконання на етапі налаштування. Якщо більше
+ніж один виявлений плагін заявляє той самий нормалізований id провайдера налаштування або серверної частини CLI,
+пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на порядок виявлення.
### Що кешує завантажувач
-OpenClaw зберігає короткоживучі кеші в межах процесу для:
+OpenClaw підтримує короткоживучі кеші в межах процесу для:
- результатів виявлення
- даних реєстру маніфестів
-- завантажених реєстрів плагінів
+- реєстрів завантажених плагінів
-Ці кеші зменшують пікове навантаження під час запуску та накладні витрати від повторних команд. Їх безпечно
-розглядати як короткоживучі кеші продуктивності, а не як постійне сховище.
+Ці кеші зменшують стрибкоподібне навантаження під час запуску та накладні витрати від повторних команд. Їх безпечно
+розглядати як короткоживучі кеші продуктивності, а не як механізм збереження стану.
Примітка щодо продуктивності:
@@ -550,7 +548,7 @@ OpenClaw зберігає короткоживучі кеші в межах пр
## Модель реєстру
-Завантажені плагіни не змінюють напряму довільні глобальні змінні core. Вони реєструються в
+Завантажені плагіни не змінюють напряму випадкові глобальні об’єкти ядра. Вони реєструються в
центральному реєстрі плагінів.
Реєстр відстежує:
@@ -559,28 +557,27 @@ OpenClaw зберігає короткоживучі кеші в межах пр
- інструменти
- застарілі хуки та типізовані хуки
- канали
-- постачальників
+- провайдерів
- обробники Gateway RPC
- HTTP-маршрути
- реєстратори CLI
-- фонові служби
+- фонові сервіси
- команди, що належать плагіну
-Потім можливості core читають із цього реєстру, а не звертаються до модулів плагінів
-напряму. Це зберігає завантаження односпрямованим:
+Після цього можливості ядра читають із цього реєстру замість прямої взаємодії з модулями плагінів.
+Це зберігає завантаження односпрямованим:
- модуль плагіна -> реєстрація в реєстрі
-- runtime core -> споживання реєстру
+- середовище виконання ядра -> споживання з реєстру
-Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь core
-потрібна лише одна точка інтеграції: «читати реєстр», а не «створювати спеціальний випадок для кожного модуля плагіна».
+Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра
+потрібна лише одна точка інтеграції: «читати реєстр», а не «робити окремий випадок для кожного модуля плагіна».
## Зворотні виклики прив’язки розмови
-Плагіни, які прив’язують розмову, можуть реагувати, коли схвалення отримує розв’язання.
+Плагіни, які прив’язують розмову, можуть реагувати, коли схвалення вирішено.
-Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, як запит на прив’язку
-буде схвалено або відхилено:
+Використовуйте `api.onConversationBindingResolved(...)`, щоб отримувати зворотний виклик після того, як запит на прив’язку схвалено або відхилено:
```ts
export default {
@@ -600,28 +597,28 @@ export default {
};
```
-Поля payload зворотного виклику:
+Поля корисного навантаження зворотного виклику:
- `status`: `"approved"` або `"denied"`
- `decision`: `"allow-once"`, `"allow-always"` або `"deny"`
-- `binding`: розв’язана прив’язка для схвалених запитів
-- `request`: підсумок початкового запиту, підказка для відв’язування, id відправника та
+- `binding`: визначена прив’язка для схвалених запитів
+- `request`: підсумок початкового запиту, підказка від’єднання, id відправника та
метадані розмови
-Цей зворотний виклик призначений лише для сповіщення. Він не змінює того, кому
-дозволено прив’язувати розмову, і виконується після завершення обробки схвалення в core.
+Цей зворотний виклик є лише сповіщенням. Він не змінює того, кому дозволено прив’язувати
+розмову, і виконується після завершення обробки схвалення ядром.
-## Хуки runtime постачальника
+## Хуки середовища виконання провайдера
-Тепер плагіни постачальників мають два рівні:
+Плагіни провайдерів тепер мають два шари:
-- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-автентифікації постачальника
- до завантаження runtime, `providerAuthAliases` для варіантів постачальника, які
- спільно використовують автентифікацію, `channelEnvVars` для дешевого пошуку env/setup каналу до
- завантаження runtime, а також `providerAuthChoices` для дешевих міток onboarding/вибору автентифікації та
- метаданих прапорців CLI до завантаження runtime
+- метадані маніфесту: `providerAuthEnvVars` для дешевого пошуку env-автентифікації провайдера
+ до завантаження середовища виконання, `providerAuthAliases` для варіантів провайдера, які спільно використовують
+ автентифікацію, `channelEnvVars` для дешевого пошуку env/налаштування каналу до
+ завантаження середовища виконання, а також `providerAuthChoices` для дешевих міток вибору онбордингу/автентифікації та
+ метаданих прапорців CLI до завантаження середовища виконання
- хуки часу конфігурації: `catalog` / застарілий `discovery` плюс `applyConfigDefaults`
-- хуки runtime: `normalizeModelId`, `normalizeTransport`,
+- хуки середовища виконання: `normalizeModelId`, `normalizeTransport`,
`normalizeConfig`,
`applyNativeStreamingUsageCompat`, `resolveConfigApiKey`,
`resolveSyntheticAuth`, `resolveExternalAuthProfiles`,
@@ -641,90 +638,90 @@ export default {
`buildReplayPolicy`,
`sanitizeReplayHistory`, `validateReplayTurns`, `onModelSelected`
-OpenClaw і далі володіє загальним циклом агента, failover, обробкою transcript і
-політикою інструментів. Ці хуки є поверхнею розширення для специфічної поведінки постачальника без
-потреби в цілком власному транспорті інференсу.
+OpenClaw, як і раніше, володіє загальним циклом агента, failover, обробкою транскриптів і
+політикою інструментів. Ці хуки є поверхнею розширення для специфічної для провайдера поведінки без
+потреби в повністю власному транспорті висновку.
-Використовуйте маніфест `providerAuthEnvVars`, коли постачальник має облікові дані на основі env,
-які загальні шляхи auth/status/model-picker мають бачити без завантаження runtime плагіна.
-Використовуйте маніфест `providerAuthAliases`, коли один id постачальника має повторно використовувати
-env vars, auth profiles, auth на основі конфігурації та вибір onboarding API-key
-іншого id постачальника. Використовуйте маніфест `providerAuthChoices`, коли поверхні CLI для onboarding/вибору auth
-мають знати id вибору постачальника, мітки груп і просту
-однопрапорцеву прив’язку auth без завантаження runtime постачальника. Зберігайте в runtime постачальника
-`envVars` для операторських підказок, таких як мітки onboarding або vars налаштування
-OAuth client-id/client-secret.
+Використовуйте `providerAuthEnvVars` у маніфесті, коли провайдер має облікові дані на основі env,
+які загальні шляхи автентифікації/стану/вибору моделі мають бачити без завантаження середовища виконання плагіна.
+Використовуйте `providerAuthAliases` у маніфесті, коли один id провайдера має повторно використовувати
+env-змінні, профілі автентифікації, автентифікацію на основі конфігурації та варіант онбордингу API-ключа
+іншого id провайдера. Використовуйте `providerAuthChoices` у маніфесті, коли поверхні CLI
+для онбордингу/вибору автентифікації мають знати id вибору провайдера, мітки груп і просту
+схему автентифікації з одним прапорцем без завантаження середовища виконання провайдера. Зберігайте
+`envVars` у середовищі виконання провайдера для підказок, орієнтованих на оператора, таких як мітки онбордингу або
+змінні налаштування `client-id`/`client-secret` для OAuth.
-Використовуйте маніфест `channelEnvVars`, коли канал має auth або setup, керовані env, які
-загальний резервний шлях shell-env, перевірки config/status або setup prompts мають бачити
-без завантаження runtime каналу.
+Використовуйте `channelEnvVars` у маніфесті, коли канал має автентифікацію або налаштування, керовані env,
+які загальний резервний механізм shell-env, перевірки конфігурації/стану або запити налаштування
+мають бачити без завантаження середовища виконання каналу.
### Порядок хуків і використання
-Для плагінів моделей/постачальників OpenClaw викликає хуки приблизно в такому порядку.
-Стовпець «When to use» — це короткий посібник для вибору.
+Для плагінів моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку.
+Стовпець «Коли використовувати» — це короткий посібник для вибору.
-| # | Хук | Що він робить | Коли використовувати |
-| --- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1 | `catalog` | Публікує конфігурацію постачальника в `models.providers` під час генерації `models.json` | Постачальник володіє каталогом або значеннями base URL за замовчуванням |
-| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації за замовчуванням, що належать постачальнику, під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей постачальника |
-| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку намагається пройти звичайним шляхом реєстру/каталогу | _(це не хук плагіна)_ |
-| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Постачальник володіє очищенням псевдонімів перед канонічним розв’язанням моделі |
-| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства постачальника перед загальним складанням моделі | Постачальник володіє очищенням транспорту для власних id постачальників у межах того самого сімейства транспорту |
-| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед розв’язанням runtime/постачальника | Постачальнику потрібне очищення конфігурації, яке має жити разом із плагіном; вбудовані допоміжні засоби сімейства Google також підтримують підтримувані записи конфігурації Google |
-| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування native streaming-usage до конфігурованих постачальників | Постачальнику потрібні виправлення метаданих native streaming usage на основі endpoint |
-| 7 | `resolveConfigApiKey` | Розв’язує auth з env-marker для конфігурованих постачальників до завантаження auth у runtime | Постачальник має власне розв’язання API-key з env-marker; `amazon-bedrock` також має тут вбудований AWS-розв’язувач env-marker |
-| 8 | `resolveSyntheticAuth` | Показує локальну/self-hosted або auth на основі конфігурації без збереження plaintext | Постачальник може працювати із синтетичним/локальним маркером облікових даних |
-| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі auth, що належать постачальнику; типове `persistence` — `runtime-only` для creds, що належать CLI/застосунку | Постачальник повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token |
-| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілю порівняно з auth на основі env/config | Постачальник зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет |
-| 11 | `resolveDynamicModel` | Синхронний резервний шлях для id моделей постачальника, яких ще немає в локальному реєстрі | Постачальник приймає довільні id моделей із зовнішнього джерела |
-| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` викликається знову | Постачальнику потрібні мережеві метадані перед розв’язанням невідомих id |
-| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як embedded runner використає розв’язану модель | Постачальнику потрібні переписування транспорту, але він усе ще використовує транспорт core |
-| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей вендора за іншим сумісним транспортом | Постачальник розпізнає власні моделі на проксі-транспортах, не перебираючи на себе володіння постачальником |
-| 15 | `capabilities` | Метадані transcript/tooling, що належать постачальнику та використовуються спільною логікою core | Постачальнику потрібні особливості transcript або сімейства постачальника |
-| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як embedded runner їх побачить | Постачальнику потрібне очищення схем для сімейства транспорту |
-| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить постачальнику, після нормалізації | Постачальник хоче попередження щодо ключових слів без навчання core специфічних правил постачальника |
-| 18 | `resolveReasoningOutputMode` | Вибирає контракт виводу reasoning: native чи tagged | Постачальнику потрібен tagged reasoning/final output замість native-полів |
-| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Постачальнику потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного постачальника |
-| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним транспортом | Постачальнику потрібен власний wire protocol, а не просто обгортка |
-| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Постачальнику потрібні обгортки сумісності заголовків/тіла/model запиту без власного транспорту |
-| 22 | `resolveTransportTurnState` | Додає native заголовки або метадані транспорту для кожного ходу | Постачальник хоче, щоб загальні транспорти надсилали native ідентичність ходу постачальника |
-| 23 | `resolveWebSocketSessionPolicy` | Додає native WebSocket-заголовки або політику cool-down сесії | Постачальник хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або резервну політику |
-| 24 | `formatApiKey` | Форматувач профілю auth: збережений профіль стає рядком `apiKey` для runtime | Постачальник зберігає додаткові метадані auth і потребує власної форми токена для runtime |
-| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для власних endpoint оновлення або політики збоїв оновлення | Постачальник не вписується в спільні засоби оновлення `pi-ai` |
-| 26 | `buildAuthDoctorHint` | Підказка для виправлення, що додається у разі збою оновлення OAuth | Постачальнику потрібні власні вказівки з відновлення auth після збою оновлення |
-| 27 | `matchesContextOverflowError` | Засіб зіставлення переповнення контекстного вікна, що належить постачальнику | Постачальник має сирі помилки переповнення, які загальні евристики не зможуть виявити |
-| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить постачальнику | Постачальник може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо |
-| 29 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul-постачальників | Постачальнику потрібне власне обмеження cache TTL для проксі |
-| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення за відсутності auth | Постачальнику потрібна власна підказка з відновлення за відсутності auth |
-| 31 | `suppressBuiltInModel` | Приховування застарілих моделей із зовнішнього джерела плюс необов’язкова підказка про помилку для користувача | Постачальнику потрібно приховати застарілі рядки з upstream або замінити їх підказкою від вендора |
-| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, що додаються після виявлення | Постачальнику потрібні синтетичні рядки для прямої сумісності в `models list` і вибирачах |
-| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для постачальників із binary-thinking | Постачальник підтримує лише binary thinking увімк./вимк. |
-| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для окремих моделей | Постачальник хоче `xhigh` лише для підмножини моделей |
-| 35 | `resolveDefaultThinkingLevel` | Типовий рівень `/think` для певного сімейства моделей | Постачальник володіє типовою політикою `/think` для сімейства моделей |
-| 36 | `isModernModelRef` | Засіб зіставлення modern-model для фільтрів live profile і вибору smoke | Постачальник володіє зіставленням пріоритетних моделей для live/smoke |
-| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime-токен/ключ безпосередньо перед інференсом | Постачальнику потрібен обмін токена або короткоживучі облікові дані для запиту |
-| 38 | `resolveUsageAuth` | Розв’язує облікові дані usage/billing для `/usage` і пов’язаних поверхонь статусу | Постачальнику потрібен власний розбір usage/quota-токена або інші облікові дані для usage |
-| 39 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для постачальника usage/quota-знімки після розв’язання auth | Постачальнику потрібен специфічний для нього endpoint usage або парсер payload |
-| 40 | `createEmbeddingProvider` | Створює адаптер embedding, що належить постачальнику, для memory/search | Поведінка embedding для memory має належати плагіну постачальника |
-| 41 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою transcript для постачальника | Постачальнику потрібна власна політика transcript (наприклад, видалення thinking-block) |
-| 42 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення transcript | Постачальнику потрібні специфічні для нього переписування replay понад спільні допоміжні засоби компактування |
-| 43 | `validateReplayTurns` | Остаточна валідація або переформування ходів replay перед embedded runner | Транспорту постачальника потрібна суворіша валідація ходів після загального очищення |
-| 44 | `onModelSelected` | Виконує побічні дії після вибору моделі, що належать постачальнику | Постачальнику потрібна телеметрія або стан, що належить постачальнику, коли модель стає активною |
+| # | Хук | Що він робить | Коли використовувати |
+| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або стандартними значеннями `base URL` |
+| 2 | `applyConfigDefaults` | Застосовує глобальні стандартні значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Стандартні значення залежать від режиму автентифікації, env або семантики сімейства моделей провайдера |
+| -- | _(пошук вбудованої моделі)_ | OpenClaw спочатку намагається використати звичайний шлях реєстру/каталогу | _(це не хук плагіна)_ |
+| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми `model-id` перед пошуком | Провайдер володіє очищенням псевдонімів до канонічного визначення моделі |
+| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для користувацьких id провайдерів у тій самій транспортній сім’ї |
+| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням середовища виконання/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із плагіном; вбудовані допоміжні засоби сімейства Google також страхують підтримувані записи конфігурації Google |
+| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування native streaming-usage до конфігурації провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, керовані кінцевими точками |
+| 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 моделей, що належать провайдеру, яких ще немає в локальному реєстрі | Провайдер приймає довільні id моделей верхнього рівня |
+| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id |
+| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як embedded runner використовує визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра |
+| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для моделей постачальника за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспорті, не перехоплюючи самого провайдера |
+| 15 | `capabilities` | Метадані транскриптів/інструментів, що належать провайдеру та використовуються спільною логікою ядра | Провайдеру потрібні особливості транскриптів/сімейства провайдера |
+| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить embedded runner | Провайдеру потрібне очищення схем для транспортної сім’ї |
+| 17 | `inspectToolSchemas` | Виводить діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче отримувати попередження щодо ключових слів без навчання ядра правилам, специфічним для провайдера |
+| 18 | `resolveReasoningOutputMode` | Вибирає native або tagged-контракт виводу reasoning | Провайдеру потрібен tagged reasoning/final output замість native-полів |
+| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні стандартні параметри запиту або очищення параметрів для конкретного провайдера |
+| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним транспортом | Провайдеру потрібен власний wire protocol, а не просто обгортка |
+| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності для заголовків/тіла/моделі запиту без власного транспорту |
+| 22 | `resolveTransportTurnState` | Прикріплює native-заголовки або метадані транспорту для кожного кроку | Провайдер хоче, щоб загальні транспорти надсилали native-ідентичність кроку провайдера |
+| 23 | `resolveWebSocketSessionPolicy` | Прикріплює native-заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або резервну політику |
+| 24 | `formatApiKey` | Форматувальник профілю автентифікації: збережений профіль стає рядком `apiKey` у середовищі виконання | Провайдер зберігає додаткові метадані автентифікації та потребує власної форми токена під час виконання |
+| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких кінцевих точок оновлення або політики помилки оновлення | Провайдер не відповідає спільним засобам оновлення `pi-ai` |
+| 26 | `buildAuthDoctorHint` | Підказка виправлення, яка додається, коли оновлення OAuth завершується помилкою | Провайдеру потрібні власні вказівки щодо виправлення автентифікації після збою оновлення |
+| 27 | `matchesContextOverflowError` | Засіб зіставлення переповнення вікна контексту, що належить провайдеру | Провайдер має сирі помилки переповнення, які не помітять загальні евристики |
+| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/перевантаженням тощо |
+| 29 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для проксі |
+| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення для відсутньої автентифікації | Провайдеру потрібна власна підказка відновлення для відсутньої автентифікації |
+| 31 | `suppressBuiltInModel` | Приховування застарілих моделей верхнього рівня плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі рядки верхнього рівня або замінити їх підказкою постачальника |
+| 32 | `augmentModelCatalog` | Синтетичні/підсумкові рядки каталогу, додані після виявлення | Провайдеру потрібні синтетичні рядки прямої сумісності в `models list` і засобах вибору |
+| 33 | `isBinaryThinking` | Перемикач reasoning увімк./вимк. для провайдерів із двійковим thinking | Провайдер надає лише двійковий режим thinking увімк./вимк. |
+| 34 | `supportsXHighThinking` | Підтримка reasoning `xhigh` для вибраних моделей | Провайдер хоче `xhigh` лише для підмножини моделей |
+| 35 | `resolveDefaultThinkingLevel` | Стандартний рівень `/think` для конкретного сімейства моделей | Провайдер володіє стандартною політикою `/think` для сімейства моделей |
+| 36 | `isModernModelRef` | Засіб зіставлення modern-model для фільтрів live profile і вибору smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke |
+| 37 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед висновком | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту |
+| 38 | `resolveUsageAuth` | Визначає облікові дані використання/білінгу для `/usage` та пов’язаних поверхонь статусу | Провайдеру потрібен власний розбір токена використання/квоти або інші облікові дані використання |
+| 39 | `fetchUsageSnapshot` | Отримує та нормалізує знімки використання/квоти, специфічні для провайдера, після визначення автентифікації | Провайдеру потрібна кінцева точка використання або аналізатор корисного навантаження, специфічні для провайдера |
+| 40 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті має належати плагіну провайдера |
+| 41 | `buildReplayPolicy` | Повертає політику повторного відтворення, що керує обробкою транскриптів для провайдера | Провайдеру потрібна власна політика транскриптів (наприклад, видалення блоків thinking) |
+| 42 | `sanitizeReplayHistory` | Переписує історію повторного відтворення після загального очищення транскрипту | Провайдеру потрібні переписування повторного відтворення, специфічні для провайдера, понад спільні допоміжні засоби ущільнення |
+| 43 | `validateReplayTurns` | Остаточна перевірка або переформування кроків повторного відтворення перед embedded runner | Транспорт провайдера потребує суворішої перевірки кроків після загального очищення |
+| 44 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною |
`normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють
-плагін постачальника, який збігся, а потім переходять до інших плагінів постачальників, здатних обробляти хуки,
-доки один із них справді не змінить id моделі або transport/config. Це дозволяє
-shim-рішенням для псевдонімів/сумісності постачальників працювати без потреби, щоб викликач знав, який
-саме вбудований плагін володіє переписуванням. Якщо жоден хук постачальника не перепише підтримуваний
-запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно застосує
-це очищення сумісності.
+плагін провайдера, що збігся, а потім переходять до інших плагінів провайдерів, здатних до хуків,
+доки один із них фактично не змінить id моделі або транспорт/конфігурацію. Це зберігає
+працездатність shim-провайдерів для псевдонімів/сумісності без вимоги до виклику знати, який
+вбудований плагін володіє переписуванням. Якщо жоден хук провайдера не переписує підтримуваний
+запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно
+застосовує це очищення сумісності.
-Якщо постачальнику потрібен повністю власний wire protocol або власний виконавець запитів,
-це вже інший клас розширення. Ці хуки призначені для поведінки постачальника, яка все ще
-працює в межах звичайного циклу інференсу OpenClaw.
+Якщо провайдеру потрібен повністю власний wire protocol або власний виконавець запитів,
+це вже інший клас розширення. Ці хуки призначені для поведінки провайдера, яка все ще
+працює в межах звичайного циклу висновку OpenClaw.
-### Приклад постачальника
+### Приклад провайдера
```ts
api.registerProvider({
@@ -783,113 +780,113 @@ api.registerProvider({
- Anthropic використовує `resolveDynamicModel`, `capabilities`, `buildAuthDoctorHint`,
`resolveUsageAuth`, `fetchUsageSnapshot`, `isCacheTtlEligible`,
`resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`
- і `wrapStreamFn`, оскільки він володіє прямою сумісністю з Claude 4.6,
- підказками для сімейства постачальника, вказівками з відновлення auth, інтеграцією з
- endpoint usage, правомірністю prompt-cache, значеннями конфігурації за замовчуванням з урахуванням auth, типовою/адаптивною
- політикою thinking для Claude та специфічним для Anthropic формуванням потоку для
+ і `wrapStreamFn`, оскільки він володіє прямою сумісністю Claude 4.6,
+ підказками сімейства провайдера, вказівками щодо відновлення автентифікації, інтеграцією
+ кінцевої точки використання, придатністю prompt-cache, стандартними значеннями конфігурації з урахуванням автентифікації, стандартною/адаптивною політикою thinking
+ для Claude та специфічним для Anthropic формуванням потоку для
beta-заголовків, `/fast` / `serviceTier` і `context1m`.
-- Допоміжні засоби потоку Anthropic, специфічні для Claude, поки що залишаються у власному
- публічному шві `api.ts` / `contract-api.ts` вбудованого плагіна. Ця поверхня пакета
+- Допоміжні засоби потоку Anthropic, специфічні для Claude, наразі залишаються у
+ власній публічній межі `api.ts` / `contract-api.ts` вбудованого плагіна. Ця поверхня пакета
експортує `wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
- `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і низькорівневі
- конструктори обгорток Anthropic замість розширення загального SDK навколо правил beta-заголовків
- одного постачальника.
+ `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і нижчорівневі
+ конструктори обгорток Anthropic замість розширення загального SDK навколо правил
+ beta-заголовків одного провайдера.
- OpenAI використовує `resolveDynamicModel`, `normalizeResolvedModel` і
`capabilities`, а також `buildMissingAuthMessage`, `suppressBuiltInModel`,
`augmentModelCatalog`, `supportsXHighThinking` і `isModernModelRef`,
- оскільки він володіє прямою сумісністю з GPT-5.4, прямою нормалізацією OpenAI
- `openai-completions` -> `openai-responses`, підказками auth з урахуванням Codex,
- приховуванням Spark, синтетичними рядками списку OpenAI та політикою thinking /
- live-model для GPT-5; сімейство потоків `openai-responses-defaults` володіє
- спільними native-обгортками OpenAI Responses для заголовків attribution,
- `/fast`/`serviceTier`, деталізації тексту, native вебпошуку Codex,
- формування payload для сумісності reasoning та керування контекстом Responses.
-- OpenRouter використовує `catalog` плюс `resolveDynamicModel` і
- `prepareDynamicModel`, тому що цей постачальник є pass-through і може відкривати нові
+ оскільки він володіє прямою сумісністю GPT-5.4, прямою нормалізацією OpenAI
+ `openai-completions` -> `openai-responses`, підказками автентифікації з урахуванням Codex,
+ приховуванням Spark, синтетичними рядками списку OpenAI і політикою GPT-5 thinking /
+ live-model; сімейство потоків `openai-responses-defaults` володіє
+ спільними native-обгортками OpenAI Responses для заголовків атрибуції,
+ `/fast`/`serviceTier`, деталізації тексту, native-вебпошуку Codex,
+ формуванням корисного навантаження reasoning-compat і керуванням контекстом Responses.
+- OpenRouter використовує `catalog`, а також `resolveDynamicModel` і
+ `prepareDynamicModel`, оскільки цей провайдер є наскрізним і може відкривати нові
id моделей до оновлення статичного каталогу OpenClaw; він також використовує
- `capabilities`, `wrapStreamFn` та `isCacheTtlEligible`, щоб
- специфічні для постачальника заголовки запитів, метадані маршрутизації, патчі reasoning і
- політика prompt-cache не потрапляли в core. Його політика replay надходить із
+ `capabilities`, `wrapStreamFn` і `isCacheTtlEligible`, щоб утримувати
+ специфічні для провайдера заголовки запиту, метадані маршрутизації, патчі reasoning і
+ політику prompt-cache поза ядром. Його політика повторного відтворення походить із
сімейства `passthrough-gemini`, тоді як сімейство потоків `openrouter-thinking`
- володіє ін’єкцією proxy reasoning і пропусками для непідтримуваних моделей / `auto`.
+ володіє ін’єкцією reasoning проксі та пропусками unsupported-model / `auto`.
- GitHub Copilot використовує `catalog`, `auth`, `resolveDynamicModel` і
- `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, тому що йому
- потрібні device login, що належить постачальнику, поведінка резервного вибору моделі,
- особливості transcript Claude, обмін токена GitHub на токен Copilot і endpoint usage,
- що належить постачальнику.
+ `capabilities`, а також `prepareRuntimeAuth` і `fetchUsageSnapshot`, оскільки йому
+ потрібні device login, що належать провайдеру, поведінка резервування моделі, особливості транскриптів Claude,
+ обмін токена GitHub на токен Copilot і кінцева точка використання, що належить провайдеру.
- OpenAI Codex використовує `catalog`, `resolveDynamicModel`,
`normalizeResolvedModel`, `refreshOAuth` і `augmentModelCatalog`, а також
`prepareExtraParams`, `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки він
- усе ще працює на core-транспортах OpenAI, але володіє своєю нормалізацією
- transport/base URL, резервною політикою оновлення OAuth, типовим вибором транспорту,
- синтетичними рядками каталогу Codex та інтеграцією з endpoint usage ChatGPT; він
+ усе ще працює на транспорті OpenAI ядра, але володіє нормалізацією свого
+ транспорту/`base URL`, резервною політикою оновлення OAuth, стандартним вибором транспорту,
+ синтетичними рядками каталогу Codex і інтеграцією кінцевої точки використання ChatGPT; він
використовує те саме сімейство потоків `openai-responses-defaults`, що й прямий OpenAI.
- Google AI Studio і Gemini CLI OAuth використовують `resolveDynamicModel`,
`buildReplayPolicy`, `sanitizeReplayHistory`,
- `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, тому що
- сімейство replay `google-gemini` володіє резервним шляхом прямої сумісності з Gemini 3.1,
- native-валідацією replay Gemini, санітизацією bootstrap replay, режимом
- tagged reasoning-output і зіставленням modern-model, тоді як
- сімейство потоків `google-thinking` володіє нормалізацією payload thinking Gemini;
+ `resolveReasoningOutputMode`, `wrapStreamFn` і `isModernModelRef`, оскільки
+ сімейство повторного відтворення `google-gemini` володіє резервним механізмом прямої сумісності Gemini 3.1,
+ native-перевіркою повторного відтворення Gemini, очищенням bootstrap replay,
+ tagged-режимом виводу reasoning і зіставленням modern-model, тоді як
+ сімейство потоків `google-thinking` володіє нормалізацією payload thinking для Gemini;
Gemini CLI OAuth також використовує `formatApiKey`, `resolveUsageAuth` і
- `fetchUsageSnapshot` для форматування токена, розбору токена та
- підключення endpoint quota.
+ `fetchUsageSnapshot` для форматування токенів, розбору токенів і
+ підключення кінцевої точки квот.
- Anthropic Vertex використовує `buildReplayPolicy` через
- сімейство replay `anthropic-by-model`, щоб очищення replay, специфічне для Claude, залишалося
+ сімейство повторного відтворення `anthropic-by-model`, щоб очищення replay, специфічне для Claude, залишалося
обмеженим id Claude, а не кожним транспортом `anthropic-messages`.
- Amazon Bedrock використовує `buildReplayPolicy`, `matchesContextOverflowError`,
- `classifyFailoverReason` і `resolveDefaultThinkingLevel`, тому що він володіє
+ `classifyFailoverReason` і `resolveDefaultThinkingLevel`, оскільки він володіє
специфічною для Bedrock класифікацією помилок throttle/not-ready/context-overflow
- для трафіку Anthropic-on-Bedrock; його політика replay все ще спільно використовує той самий
- guard `anthropic-by-model`, призначений лише для Claude.
+ для трафіку Anthropic-on-Bedrock; його політика повторного відтворення все ще використовує той самий
+ захист `anthropic-by-model`, що стосується лише Claude.
- OpenRouter, Kilocode, Opencode і Opencode Go використовують `buildReplayPolicy`
- через сімейство replay `passthrough-gemini`, тому що вони проксують моделі Gemini
- через транспорти, сумісні з OpenAI, і потребують санітизації
- thought-signature Gemini без native-валідації replay Gemini або переписувань bootstrap.
+ через сімейство повторного відтворення `passthrough-gemini`, оскільки вони проксіюють моделі Gemini
+ через транспорти, сумісні з OpenAI, і потребують очищення thought-signature
+ Gemini без native-перевірки replay Gemini або bootstrap-переписувань.
- MiniMax використовує `buildReplayPolicy` через
- сімейство replay `hybrid-anthropic-openai`, тому що один постачальник володіє як
- семантикою Anthropic-message, так і OpenAI-compatible; він зберігає видалення
- thinking-block, призначене лише для Claude, на боці Anthropic, водночас перевизначаючи режим виводу reasoning назад на native, а
- сімейство потоків `minimax-fast-mode` володіє переписуванням моделей fast-mode на спільному шляху потоку.
-- Moonshot використовує `catalog` плюс `wrapStreamFn`, тому що він усе ще використовує
- спільний транспорт OpenAI, але потребує нормалізації payload thinking, що належить постачальнику; сімейство потоків
- `moonshot-thinking` відображає config плюс стан `/think` на його
- native payload binary thinking.
+ сімейство повторного відтворення `hybrid-anthropic-openai`, оскільки один провайдер володіє і семантикою
+ повідомлень Anthropic, і семантикою, сумісною з OpenAI; він зберігає видалення
+ блоків thinking лише для Claude на стороні Anthropic, одночасно перевизначаючи режим виводу reasoning назад на native, а сімейство потоків `minimax-fast-mode` володіє
+ переписуваннями моделей fast-mode на спільному шляху потоку.
+- Moonshot використовує `catalog` і `wrapStreamFn`, оскільки він усе ще використовує спільний
+ транспорт OpenAI, але потребує нормалізації payload thinking, що належить провайдеру; сімейство
+ потоків `moonshot-thinking` відображає конфігурацію та стан `/think` на його
+ native-бінарний payload thinking.
- Kilocode використовує `catalog`, `capabilities`, `wrapStreamFn` і
- `isCacheTtlEligible`, тому що йому потрібні заголовки запитів, що належать постачальнику,
- нормалізація payload reasoning, підказки transcript Gemini та обмеження
- cache-TTL Anthropic; сімейство потоків `kilocode-thinking` зберігає ін’єкцію thinking Kilo
- на спільному шляху proxy-потоку, пропускаючи `kilo/auto` та
- інші proxy-id моделей, які не підтримують явні payload reasoning.
+ `isCacheTtlEligible`, оскільки йому потрібні заголовки запиту, що належать провайдеру,
+ нормалізація payload reasoning, підказки транскриптів Gemini та керування
+ TTL кешу Anthropic; сімейство потоків `kilocode-thinking` зберігає ін’єкцію thinking Kilo
+ на спільному шляху проксі-потоку, водночас пропускаючи `kilo/auto` та
+ інші id проксі-моделей, які не підтримують явні payload reasoning.
- Z.AI використовує `resolveDynamicModel`, `prepareExtraParams`, `wrapStreamFn`,
`isCacheTtlEligible`, `isBinaryThinking`, `isModernModelRef`,
- `resolveUsageAuth` і `fetchUsageSnapshot`, тому що він володіє резервним шляхом GLM-5,
- значеннями `tool_stream` за замовчуванням, UX binary thinking, зіставленням modern-model, а також
- auth для usage і отриманням quota; сімейство потоків `tool-stream-default-on` зберігає
- обгортку `tool_stream`, увімкнену за замовчуванням, поза межами рукописного glue-коду для кожного постачальника.
+ `resolveUsageAuth` і `fetchUsageSnapshot`, оскільки він володіє резервуванням GLM-5,
+ стандартними значеннями `tool_stream`, UX двійкового thinking, зіставленням modern-model
+ і як автентифікацією використання, так і отриманням квот; сімейство потоків `tool-stream-default-on`
+ утримує обгортку `tool_stream`, увімкнену за замовчуванням, поза рукописним glue-кодом
+ окремих провайдерів.
- xAI використовує `normalizeResolvedModel`, `normalizeTransport`,
`contributeResolvedModelCompat`, `prepareExtraParams`, `wrapStreamFn`,
`resolveSyntheticAuth`, `resolveDynamicModel` і `isModernModelRef`,
- тому що він володіє нормалізацією native xAI Responses transport, переписуванням
- псевдонімів fast-mode Grok, типовим `tool_stream`, очищенням strict-tool / reasoning-payload,
- повторним використанням резервного auth для інструментів, що належать плагіну, прямим розв’язанням моделей Grok
- та compat-патчами, що належать постачальнику, як-от профіль схеми інструментів xAI,
- непідтримувані ключові слова схеми, native `web_search` і декодування HTML-entity
- аргументів виклику інструмента.
+ оскільки він володіє нормалізацією native-транспорту xAI Responses, переписуванням
+ псевдонімів fast-mode для Grok, стандартним `tool_stream`, очищенням
+ strict-tool / payload reasoning, повторним використанням резервної автентифікації для інструментів, що належать плагіну,
+ визначенням моделей Grok із прямою сумісністю та патчами сумісності, що належать провайдеру, такими як профіль схем інструментів xAI,
+ непідтримувані ключові слова схеми, native `web_search` і декодування аргументів
+ виклику інструментів у HTML-сутностях.
- Mistral, OpenCode Zen і OpenCode Go використовують лише `capabilities`, щоб
- особливості transcript/tooling не потрапляли в core.
-- Вбудовані постачальники лише з каталогом, як-от `byteplus`, `cloudflare-ai-gateway`,
+ винести особливості транскриптів/інструментів за межі ядра.
+- Вбудовані провайдери лише з каталогом, такі як `byteplus`, `cloudflare-ai-gateway`,
`huggingface`, `kimi-coding`, `nvidia`, `qianfan`,
`synthetic`, `together`, `venice`, `vercel-ai-gateway` і `volcengine`, використовують
лише `catalog`.
-- Qwen використовує `catalog` для свого текстового постачальника, а також спільні реєстрації
- розуміння медіа і генерації відео для своїх мультимодальних поверхонь.
-- MiniMax і Xiaomi використовують `catalog` плюс хуки usage, оскільки їхня поведінка `/usage`
- належить плагіну, хоча сам інференс усе ще працює через спільні транспорти.
+- Qwen використовує `catalog` для свого текстового провайдера, а також спільні реєстрації
+ media-understanding і video-generation для своїх мультимодальних поверхонь.
+- MiniMax і Xiaomi використовують `catalog`, а також хуки використання, оскільки їхня поведінка `/usage`
+ належить плагіну, навіть якщо висновок усе ще проходить через спільні транспорти.
-## Допоміжні засоби runtime
+## Допоміжні засоби середовища виконання
-Плагіни можуть отримувати доступ до вибраних допоміжних засобів core через `api.runtime`. Для TTS:
+Плагіни можуть отримувати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS:
```ts
const clip = await api.runtime.tts.textToSpeech({
@@ -910,14 +907,14 @@ const voices = await api.runtime.tts.listVoices({
Примітки:
-- `textToSpeech` повертає звичайний payload виводу TTS із core для поверхонь файлів/голосових нотаток.
-- Використовує конфігурацію core `messages.tts` і вибір постачальника.
-- Повертає PCM-аудіобуфер + частоту дискретизації. Плагіни мають виконувати ресемплінг/кодування для постачальників.
-- `listVoices` є необов’язковим для кожного постачальника. Використовуйте його для вибирачів голосів або потоків setup, що належать вендору.
-- Списки голосів можуть включати багатші метадані, такі як локаль, стать і теги особистості для вибирачів з урахуванням постачальника.
+- `textToSpeech` повертає звичайний payload виводу TTS ядра для поверхонь файлів/голосових нотаток.
+- Використовує конфігурацію `messages.tts` ядра та вибір провайдера.
+- Повертає буфер аудіо PCM + частоту дискретизації. Плагіни мають виконувати повторну дискретизацію/кодування для провайдерів.
+- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать постачальнику.
+- Списки голосів можуть містити розширені метадані, такі як локаль, стать і теги характеру для засобів вибору з урахуванням провайдера.
- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні.
-Плагіни також можуть реєструвати постачальників мовлення через `api.registerSpeechProvider(...)`.
+Плагіни також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`.
```ts
api.registerSpeechProvider({
@@ -937,15 +934,15 @@ api.registerSpeechProvider({
Примітки:
-- Зберігайте політику TTS, резервний вибір і доставку відповідей у core.
-- Використовуйте постачальників мовлення для поведінки синтезу, що належить вендору.
-- Застарілий вхід Microsoft `edge` нормалізується до id постачальника `microsoft`.
-- Бажана модель володіння орієнтована на компанію: один плагін вендора може володіти
- постачальниками тексту, мовлення, зображень і майбутніх медіа, коли OpenClaw додає
+- Зберігайте політику TTS, резервування та доставку відповідей у ядрі.
+- Використовуйте провайдерів мовлення для поведінки синтезу, що належить постачальнику.
+- Застарілий вхід Microsoft `edge` нормалізується до id провайдера `microsoft`.
+- Бажана модель володіння орієнтована на компанію: один плагін постачальника може володіти
+ текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами, коли OpenClaw додає
ці контракти можливостей.
-Для розуміння зображень/аудіо/відео плагіни реєструють одного типізованого
-постачальника розуміння медіа замість загального key/value-набору:
+Для розуміння зображень/аудіо/відео плагіни реєструють один типізований
+провайдер media-understanding замість загального набору key/value:
```ts
api.registerMediaUnderstandingProvider({
@@ -959,16 +956,16 @@ api.registerMediaUnderstandingProvider({
Примітки:
-- Зберігайте оркестрацію, резервний вибір, конфігурацію та підключення каналів у core.
-- Зберігайте поведінку вендора в плагіні постачальника.
-- Розширення шляхом додавання має залишатися типізованим: нові необов’язкові методи, нові необов’язкові
+- Зберігайте оркестрацію, резервні механізми, конфігурацію та підключення каналів у ядрі.
+- Зберігайте поведінку постачальника в плагіні провайдера.
+- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові
поля результату, нові необов’язкові можливості.
- Генерація відео вже дотримується того самого шаблону:
- - core володіє контрактом можливості та допоміжним засобом runtime
- - плагіни вендорів реєструють `api.registerVideoGenerationProvider(...)`
+ - ядро володіє контрактом можливості та допоміжним засобом середовища виконання
+ - плагіни постачальників реєструють `api.registerVideoGenerationProvider(...)`
- плагіни функцій/каналів споживають `api.runtime.videoGeneration.*`
-Для допоміжних засобів runtime розуміння медіа плагіни можуть викликати:
+Для допоміжних засобів середовища виконання media-understanding плагіни можуть викликати:
```ts
const image = await api.runtime.mediaUnderstanding.describeImageFile({
@@ -983,8 +980,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({
});
```
-Для транскрибування аудіо плагіни можуть використовувати або runtime
-розуміння медіа, або старіший псевдонім STT:
+Для транскрипції аудіо плагіни можуть використовувати або середовище виконання media-understanding,
+або старіший псевдонім STT:
```ts
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
@@ -997,13 +994,13 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
Примітки:
-- `api.runtime.mediaUnderstanding.*` — це пріоритетна спільна поверхня для
+- `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для
розуміння зображень/аудіо/відео.
-- Використовує конфігурацію аудіо розуміння медіа з core (`tools.media.audio`) і порядок резервного вибору постачальників.
-- Повертає `{ text: undefined }`, коли результат транскрибування не створено (наприклад, для пропущеного/непідтримуваного вводу).
+- Використовує конфігурацію аудіо media-understanding ядра (`tools.media.audio`) і порядок резервування провайдерів.
+- Повертає `{ text: undefined }`, коли вихід транскрипції не створено (наприклад, для пропущеного/непідтримуваного вводу).
- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності.
-Плагіни також можуть запускати фонові запуски subagent через `api.runtime.subagent`:
+Плагіни також можуть запускати фонові виконання підлеглих агентів через `api.runtime.subagent`:
```ts
const result = await api.runtime.subagent.run({
@@ -1018,13 +1015,13 @@ const result = await api.runtime.subagent.run({
Примітки:
- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії.
-- OpenClaw враховує ці поля перевизначення лише для довірених викликачів.
+- OpenClaw враховує ці поля перевизначення лише для довірених викликів.
- Для резервних запусків, що належать плагіну, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`.
- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені плагіни конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль.
-- Запуски subagent із недовірених плагінів теж працюють, але запити на перевизначення відхиляються замість тихого переходу на резервний варіант.
+- Запуски підлеглих агентів із недовірених плагінів також працюють, але запити на перевизначення відхиляються замість тихого переходу до резервного варіанта.
-Для вебпошуку плагіни можуть використовувати спільний допоміжний засіб runtime замість
-прямого доступу до підключення інструмента агента:
+Для вебпошуку плагіни можуть споживати спільний допоміжний засіб середовища виконання замість
+звернення до підключення інструмента агента:
```ts
const providers = api.runtime.webSearch.listProviders({
@@ -1040,14 +1037,14 @@ const result = await api.runtime.webSearch.search({
});
```
-Плагіни також можуть реєструвати постачальників вебпошуку через
+Плагіни також можуть реєструвати провайдерів вебпошуку через
`api.registerWebSearchProvider(...)`.
Примітки:
-- Зберігайте вибір постачальника, розв’язання облікових даних і спільну семантику запитів у core.
-- Використовуйте постачальників вебпошуку для транспортів пошуку, специфічних для вендора.
-- `api.runtime.webSearch.*` — це пріоритетна спільна поверхня для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента.
+- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у ядрі.
+- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для постачальника.
+- `api.runtime.webSearch.*` — це бажана спільна поверхня для плагінів функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента.
### `api.runtime.imageGeneration`
@@ -1062,12 +1059,12 @@ const providers = api.runtime.imageGeneration.listProviders({
});
```
-- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка постачальників генерації зображень.
-- `listProviders(...)`: перелічує доступних постачальників генерації зображень і їхні можливості.
+- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень.
+- `listProviders(...)`: виводить список доступних провайдерів генерації зображень та їхніх можливостей.
## HTTP-маршрути Gateway
-Плагіни можуть відкривати HTTP-endpoint через `api.registerHttpRoute(...)`.
+Плагіни можуть відкривати HTTP-кінцеві точки через `api.registerHttpRoute(...)`.
```ts
api.registerHttpRoute({
@@ -1084,24 +1081,24 @@ api.registerHttpRoute({
Поля маршруту:
-- `path`: шлях маршруту в HTTP-сервері gateway.
-- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайну auth gateway, або `"plugin"` для auth/перевірки webhook, якими керує плагін.
-- `match`: необов’язкове. `"exact"` (типово) або `"prefix"`.
-- `replaceExisting`: необов’язкове. Дозволяє тому самому плагіну замінити власну наявну реєстрацію маршруту.
+- `path`: шлях маршруту під HTTP-сервером gateway.
+- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайну автентифікацію gateway, або `"plugin"` для автентифікації/перевірки вебхуків, якими керує плагін.
+- `match`: необов’язкове поле. `"exact"` (типово) або `"prefix"`.
+- `replaceExisting`: необов’язкове поле. Дозволяє тому самому плагіну замінювати власну наявну реєстрацію маршруту.
- `handler`: повертайте `true`, коли маршрут обробив запит.
Примітки:
-- `api.registerHttpHandler(...)` було видалено, і його використання спричинить помилку завантаження плагіна. Замість нього використовуйте `api.registerHttpRoute(...)`.
+- `api.registerHttpHandler(...)` було видалено, і його використання спричинить помилку завантаження плагіна. Натомість використовуйте `api.registerHttpRoute(...)`.
- Маршрути плагінів мають явно оголошувати `auth`.
- Конфлікти точних `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна.
-- Перекривні маршрути з різними рівнями `auth` відхиляються. Ланцюжки переходу `exact`/`prefix` мають бути лише в межах одного рівня `auth`.
-- Маршрути `auth: "plugin"` **не** отримують автоматично області runtime оператора. Вони призначені для webhook/перевірки підписів, якими керує плагін, а не для привілейованих викликів допоміжних засобів Gateway.
-- Маршрути `auth: "gateway"` виконуються в межах області runtime запиту Gateway, але ця область навмисно консервативна:
- - bearer-auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області runtime маршрутів плагіна на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes`
- - довірені HTTP-режими з передаванням ідентичності (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` у приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній
- - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту плагіна з передаванням ідентичності, область runtime повертається до `operator.write`
-- Практичне правило: не вважайте маршрут плагіна з auth gateway неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth із передаванням ідентичності та документуйте явний контракт заголовка `x-openclaw-scopes`.
+- Перекривні маршрути з різними рівнями `auth` відхиляються. Тримайте ланцюги переходу `exact`/`prefix` лише в межах одного рівня auth.
+- Маршрути з `auth: "plugin"` **не** отримують автоматично операторські області середовища виконання. Вони призначені для вебхуків/перевірки підписів, якими керує плагін, а не для привілейованих викликів допоміжних засобів Gateway.
+- Маршрути з `auth: "gateway"` працюють усередині області середовища виконання запиту Gateway, але ця область навмисно консервативна:
+ - bearer-автентифікація через спільний секрет (`gateway.auth.mode = "token"` / `"password"`) утримує області середовища виконання маршруту плагіна на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes`
+ - довірені HTTP-режими з носієм ідентичності (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній
+ - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту плагіна з носієм ідентичності, область середовища виконання повертається до `operator.write`
+- Практичне правило: не припускайте, що маршрут плагіна з автентифікацією gateway автоматично є поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим автентифікації з носієм ідентичності та задокументуйте явний контракт заголовка `x-openclaw-scopes`.
## Шляхи імпорту Plugin SDK
@@ -1109,7 +1106,7 @@ api.registerHttpRoute({
- `openclaw/plugin-sdk/plugin-entry` для примітивів реєстрації плагінів.
- `openclaw/plugin-sdk/core` для загального спільного контракту, орієнтованого на плагіни.
-- `openclaw/plugin-sdk/config-schema` для експорту кореневої Zod-схеми `openclaw.json`
+- `openclaw/plugin-sdk/config-schema` для експорту кореневої схеми Zod `openclaw.json`
(`OpenClawSchema`).
- Стабільні примітиви каналів, такі як `openclaw/plugin-sdk/channel-setup`,
`openclaw/plugin-sdk/setup-runtime`,
@@ -1123,18 +1120,18 @@ api.registerHttpRoute({
`openclaw/plugin-sdk/channel-reply-pipeline`,
`openclaw/plugin-sdk/command-auth`,
`openclaw/plugin-sdk/secret-input` і
- `openclaw/plugin-sdk/webhook-ingress` для спільного підключення setup/auth/reply/webhook.
- `channel-inbound` — це спільний дім для debounce, зіставлення згадок,
- допоміжних засобів політики вхідних згадок, форматування envelope і
- допоміжних засобів контексту вхідного envelope.
- `channel-setup` — це вузький шов setup для необов’язкового встановлення.
- `setup-runtime` — це безпечна для runtime поверхня setup, що використовується `setupEntry` /
- відкладеним запуском, включно з безпечними для імпорту адаптерами patch setup.
- `setup-adapter-runtime` — це env-aware шов адаптера налаштування облікового запису.
- `setup-tools` — це малий шов допоміжних засобів CLI/архівів/документації (`formatCliCommand`,
+ `openclaw/plugin-sdk/webhook-ingress` для спільного підключення
+ налаштування/автентифікації/відповідей/вебхуків. `channel-inbound` — це спільне місце для debounce, зіставлення згадок,
+ допоміжних засобів політики вхідних згадок, форматування конвертів і допоміжних засобів
+ контексту вхідних конвертів.
+ `channel-setup` — це вузька межа налаштування для необов’язкового встановлення.
+ `setup-runtime` — це безпечна для середовища виконання поверхня налаштування, яку використовують `setupEntry` /
+ відкладений запуск, включно з безпечними для імпорту адаптерами патчів налаштування.
+ `setup-adapter-runtime` — це межа адаптера налаштування облікового запису з урахуванням env.
+ `setup-tools` — це мала межа допоміжних засобів для CLI/архівів/документації (`formatCliCommand`,
`detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`,
`CONFIG_DIR`).
-- Предметні підшляхи, як-от `openclaw/plugin-sdk/channel-config-helpers`,
+- Підшляхи доменів, такі як `openclaw/plugin-sdk/channel-config-helpers`,
`openclaw/plugin-sdk/allow-from`,
`openclaw/plugin-sdk/channel-config-schema`,
`openclaw/plugin-sdk/telegram-command-config`,
@@ -1152,194 +1149,191 @@ api.registerHttpRoute({
`openclaw/plugin-sdk/status-helpers`,
`openclaw/plugin-sdk/text-runtime`,
`openclaw/plugin-sdk/runtime-store` і
- `openclaw/plugin-sdk/directory-runtime` для спільних допоміжних засобів runtime/config.
- `telegram-command-config` — це вузький публічний шов для нормалізації/валідації власних
- команд Telegram і залишається доступним навіть якщо поверхня контракту вбудованого
+ `openclaw/plugin-sdk/directory-runtime` для спільних допоміжних засобів середовища виконання/конфігурації.
+ `telegram-command-config` — це вузька публічна межа для нормалізації/валідації користувацьких
+ команд Telegram і залишається доступною навіть якщо поверхня контракту вбудованого
Telegram тимчасово недоступна.
- `text-runtime` — це спільний шов text/markdown/logging, включно з
- видаленням тексту, видимого асистенту, допоміжними засобами рендерингу/чанкування markdown, засобами редагування
- та безпечними текстовими утилітами.
-- Для специфічних для схвалення швів каналів слід надавати перевагу одному контракту `approvalCapability`
- на плагіні. Потім core читає auth, доставку, рендеринг,
- native-routing і ледачу поведінку native-handler для схвалення через цю одну можливість
- замість змішування поведінки схвалення з не пов’язаними полями плагіна.
+ `text-runtime` — це спільна межа тексту/markdown/логування, включно з
+ видаленням тексту, видимого асистенту, допоміжними засобами рендерингу/розбиття markdown, допоміжними засобами редагування,
+ допоміжними засобами тегів директив і утилітами безпечного тексту.
+- Для меж каналів, специфічних для погодження, слід надавати перевагу одному контракту
+ `approvalCapability` на плагіні. Тоді ядро читає auth, доставку, рендеринг,
+ native-routing і поведінку lazy native-handler для погодження через одну цю можливість
+ замість змішування поведінки погодження з не пов’язаними полями плагіна.
- `openclaw/plugin-sdk/channel-runtime` є застарілим і залишається лише як
shim сумісності для старіших плагінів. Новий код має імпортувати вужчі
загальні примітиви, а код репозиторію не повинен додавати нові імпорти цього shim.
-- Внутрішні частини вбудованих розширень залишаються приватними. Зовнішні плагіни повинні використовувати лише підшляхи `openclaw/plugin-sdk/*`. Код core/test OpenClaw може використовувати
- публічні точки входу репозиторію в корені пакета плагіна, такі як `index.js`, `api.js`,
- `runtime-api.js`, `setup-entry.js`, а також вузько спрямовані файли, такі як
- `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з core або з
+- Внутрішні компоненти вбудованих розширень залишаються приватними. Зовнішні плагіни мають використовувати лише
+ підшляхи `openclaw/plugin-sdk/*`. Код ядра/тестів OpenClaw може використовувати
+ публічні точки входу репозиторію під коренем пакета плагіна, такі як `index.js`, `api.js`,
+ `runtime-api.js`, `setup-entry.js` і вузькоспрямовані файли, наприклад
+ `login-qr-api.js`. Ніколи не імпортуйте `src/*` пакета плагіна з ядра або з
іншого розширення.
-- Поділ точки входу репозиторію:
- `/api.js` — це barrel допоміжних засобів/типів,
- `/runtime-api.js` — це barrel лише для runtime,
+- Розділення точок входу репозиторію:
+ `/api.js` — це барель допоміжних засобів/типів,
+ `/runtime-api.js` — це барель лише для середовища виконання,
`/index.js` — це точка входу вбудованого плагіна,
- а `/setup-entry.js` — це точка входу setup-плагіна.
-- Поточні приклади вбудованих постачальників:
+ а `/setup-entry.js` — це точка входу плагіна налаштування.
+- Поточні приклади вбудованих провайдерів:
- Anthropic використовує `api.js` / `contract-api.js` для допоміжних засобів потоку Claude, таких
- як `wrapAnthropicProviderStream`, допоміжні засоби beta-заголовків і парсинг `service_tier`.
- - OpenAI використовує `api.js` для конструкторів постачальників, допоміжних засобів типової моделі та
- конструкторів постачальників realtime.
- - OpenRouter використовує `api.js` для свого конструктора постачальника плюс допоміжних засобів
- onboarding/config, тоді як `register.runtime.js` і далі може повторно експортувати загальні
+ як `wrapAnthropicProviderStream`, допоміжні засоби beta-заголовків і розбір `service_tier`.
+ - OpenAI використовує `api.js` для конструкторів провайдера, допоміжних засобів стандартних моделей і
+ конструкторів провайдерів реального часу.
+ - OpenRouter використовує `api.js` для свого конструктора провайдера та допоміжних засобів
+ онбордингу/конфігурації, тоді як `register.runtime.js` усе ще може повторно експортувати загальні
допоміжні засоби `plugin-sdk/provider-stream` для локального використання в репозиторії.
-- Публічні точки входу, завантажені через facade, віддають перевагу активному знімку конфігурації runtime,
- якщо він існує, а тоді повертаються до розв’язаного файлу конфігурації на диску, коли
- OpenClaw ще не надає знімок runtime.
-- Загальні спільні примітиви залишаються пріоритетним публічним контрактом SDK. Невеликий
- зарезервований сумісний набір branded helper-швів вбудованих каналів усе ще існує. Розглядайте їх як
- шви для підтримки вбудованих рішень/сумісності, а не як нові цілі імпорту для сторонніх рішень; нові міжканальні контракти й далі мають з’являтися в
- загальних підшляхах `plugin-sdk/*` або в локальних barrel `api.js` /
- `runtime-api.js` плагіна.
+- Публічні точки входу, завантажені через фасад, віддають перевагу активному знімку конфігурації середовища виконання,
+ якщо він існує, а потім повертаються до визначеного файла конфігурації на диску, коли
+ OpenClaw ще не обслуговує знімок середовища виконання.
+- Загальні спільні примітиви залишаються бажаним публічним контрактом SDK. Невеликий
+ зарезервований набір меж допоміжних засобів із брендингом вбудованих каналів усе ще існує. Розглядайте їх як межі для підтримки вбудованих компонентів/сумісності, а не як нові цілі імпорту для сторонніх рішень; нові міжканальні контракти й надалі мають потрапляти до
+ загальних підшляхів `plugin-sdk/*` або до локальних барелів плагіна `api.js` /
+ `runtime-api.js`.
Примітка щодо сумісності:
-- Уникайте кореневого barrel `openclaw/plugin-sdk` у новому коді.
+- Уникайте кореневого бареля `openclaw/plugin-sdk` у новому коді.
- Спочатку надавайте перевагу вузьким стабільним примітивам. Новіші підшляхи setup/pairing/reply/
feedback/contract/inbound/threading/command/secret-input/webhook/infra/
- allowlist/status/message-tool — це цільовий контракт для нової роботи з
+ allowlist/status/message-tool є бажаним контрактом для нової роботи з
вбудованими та зовнішніми плагінами.
Розбір/зіставлення цілей має розміщуватися в `openclaw/plugin-sdk/channel-targets`.
- Обмеження дій повідомлень і допоміжні засоби message-id для реакцій мають розміщуватися в
+ Обмеження дій повідомлень і допоміжні засоби для id повідомлень реакцій мають розміщуватися в
`openclaw/plugin-sdk/channel-actions`.
-- Barrel-модулі допоміжних засобів, специфічні для вбудованих розширень, за замовчуванням не є стабільними. Якщо
- допоміжний засіб потрібен лише вбудованому розширенню, залишайте його за локальним
- швом `api.js` або `runtime-api.js` цього розширення замість просування в
+- Барелі допоміжних засобів, специфічні для вбудованих розширень, не є стабільними за замовчуванням. Якщо
+ допоміжний засіб потрібен лише вбудованому розширенню, тримайте його за локальною
+ межею `api.js` або `runtime-api.js` цього розширення замість просування його до
`openclaw/plugin-sdk/`.
-- Нові спільні шви допоміжних засобів мають бути загальними, а не брендованими під конкретний канал. Спільний розбір
- цілей має розміщуватися в `openclaw/plugin-sdk/channel-targets`; внутрішні частини, специфічні для каналу,
- мають залишатися за локальним швом `api.js` або `runtime-api.js`
- плагіна-власника.
+- Нові спільні межі допоміжних засобів мають бути загальними, а не брендованими під канал. Спільний розбір
+ цілей має належати `openclaw/plugin-sdk/channel-targets`; внутрішні компоненти, специфічні для каналу,
+ мають залишатися за локальною межею `api.js` або `runtime-api.js` плагіна-власника.
- Підшляхи, специфічні для можливостей, такі як `image-generation`,
- `media-understanding` і `speech`, існують, тому що вбудовані/нативні плагіни використовують
- їх уже сьогодні. Їхня наявність сама по собі не означає, що кожен експортований допоміжний засіб є
- довгостроковим зафіксованим зовнішнім контрактом.
+ `media-understanding` і `speech`, існують, оскільки вбудовані/нативні плагіни використовують
+ їх сьогодні. Їхня наявність сама по собі не означає, що кожен експортований допоміжний засіб є
+ довгостроковим замороженим зовнішнім контрактом.
## Схеми інструмента повідомлень
-Плагіни мають володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу.
-Зберігайте поля, специфічні для постачальника, у плагіні, а не в спільному core.
+Плагіни мають володіти внесками в схему `describeMessageTool(...)`, специфічними для каналу.
+Тримайте поля, специфічні для провайдера, у плагіні, а не в спільному ядрі.
-Для спільних переносних фрагментів схеми повторно використовуйте загальні допоміжні засоби, експортовані через
-`openclaw/plugin-sdk/channel-actions`:
+Для спільних переносимих фрагментів схеми повторно використовуйте загальні допоміжні засоби,
+експортовані через `openclaw/plugin-sdk/channel-actions`:
- `createMessageToolButtonsSchema()` для payload у стилі сітки кнопок
- `createMessageToolCardSchema()` для payload структурованих карток
-Якщо форма схеми має сенс лише для одного постачальника, визначайте її у власному
-коді цього плагіна замість просування до спільного SDK.
+Якщо форма схеми має сенс лише для одного провайдера, визначайте її у власному
+вихідному коді цього плагіна замість просування до спільного SDK.
-## Розв’язання цілей каналу
+## Визначення цілей каналу
-Плагіни каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний
-outbound host загальним і використовуйте поверхню адаптера повідомлень для правил постачальника:
+Плагіни каналів мають володіти семантикою цілей, специфічною для каналу. Тримайте спільний
+вихідний хост загальним і використовуйте поверхню адаптера обміну повідомленнями для правил провайдера:
-- `messaging.inferTargetChatType({ to })` визначає, чи нормалізовану ціль
- слід трактувати як `direct`, `group` або `channel` до пошуку в директорії.
-- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи
- вхідні дані слід одразу спрямувати до розв’язання за схожістю з id, а не до пошуку в директорії.
-- `messaging.targetResolver.resolveTarget(...)` — це резервний шлях плагіна, коли
- core потребує фінального розв’язання, що належить постачальнику, після нормалізації або
- після пропуску в директорії.
-- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту outbound-сесії,
- специфічною для постачальника, щойно ціль розв’язано.
+- `messaging.inferTargetChatType({ to })` визначає, чи слід трактувати нормалізовану ціль
+ як `direct`, `group` або `channel` до пошуку в каталозі.
+- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи
+ слід для вводу одразу перейти до визначення за схожістю з id замість пошуку в каталозі.
+- `messaging.targetResolver.resolveTarget(...)` — це резервний механізм плагіна, коли
+ ядру потрібне остаточне визначення, що належить провайдеру, після нормалізації або
+ після промаху пошуку в каталозі.
+- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту вихідної сесії, специфічною для провайдера,
+ після того як ціль визначено.
Рекомендований поділ:
-- Використовуйте `inferTargetChatType` для рішень щодо категорії, які мають відбуватися до
- пошуку серед peer/group.
-- Використовуйте `looksLikeId` для перевірок типу «обробляти це як явний/native id цілі».
-- Використовуйте `resolveTarget` для резервної нормалізації, специфічної для постачальника, а не для
- широкого пошуку в директорії.
-- Зберігайте native id постачальника, такі як id чатів, id тредів, JID, handles та id кімнат,
- усередині значень `target` або параметрів, специфічних для постачальника, а не в загальних полях SDK.
+- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають відбуватися до
+ пошуку серед співрозмовників/груп.
+- Використовуйте `looksLikeId` для перевірок «трактувати це як явний/native id цілі».
+- Використовуйте `resolveTarget` для резервної нормалізації, специфічної для провайдера, а не для
+ широкого пошуку в каталозі.
+- Тримайте native id провайдера, такі як chat id, thread id, JID, handles і room
+ ids, усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK.
-## Директорії на основі конфігурації
+## Каталоги на основі конфігурації
-Плагіни, які виводять записи директорії з конфігурації, мають зберігати цю логіку в
+Плагіни, які виводять записи каталогу з конфігурації, мають тримати цю логіку в
плагіні та повторно використовувати спільні допоміжні засоби з
`openclaw/plugin-sdk/directory-runtime`.
-Використовуйте це, коли каналу потрібні peer/group на основі конфігурації, наприклад:
+Використовуйте це, коли каналу потрібні каталоги співрозмовників/груп на основі конфігурації, такі як:
-- DM-peer на основі allowlist
-- налаштовані мапи каналів/груп
-- статичні резервні варіанти директорії в межах облікового запису
+- DM-співрозмовники, керовані списком дозволу
+- налаштовані відображення каналів/груп
+- статичні резервні варіанти каталогу в межах облікового запису
Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції:
- фільтрацію запитів
- застосування обмежень
-- видалення дублікатів/нормалізацію
+- допоміжні засоби усунення дублікатів/нормалізації
- побудову `ChannelDirectoryEntry[]`
-Перевірка облікового запису та нормалізація id, специфічні для каналу, мають залишатися в
-реалізації плагіна.
+Інспекція облікових записів і нормалізація id, специфічні для каналу, мають залишатися
+в реалізації плагіна.
-## Каталоги постачальників
+## Каталоги провайдерів
-Плагіни постачальників можуть визначати каталоги моделей для інференсу через
+Плагіни провайдерів можуть визначати каталоги моделей для висновку через
`registerProvider({ catalog: { run(...) { ... } } })`.
`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в
`models.providers`:
-- `{ provider }` для одного запису постачальника
-- `{ providers }` для кількох записів постачальників
+- `{ provider }` для одного запису провайдера
+- `{ providers }` для кількох записів провайдера
-Використовуйте `catalog`, коли плагін володіє специфічними для постачальника id моделей, значеннями base URL
-за замовчуванням або метаданими моделей, закритими auth.
+Використовуйте `catalog`, коли плагін володіє id моделей, специфічними для провайдера, стандартними значеннями base URL або метаданими моделей, обмеженими автентифікацією.
-`catalog.order` керує тим, коли каталог плагіна зливається відносно
-вбудованих неявних постачальників OpenClaw:
+`catalog.order` контролює, коли каталог плагіна об’єднується відносно
+вбудованих неявних провайдерів OpenClaw:
-- `simple`: звичайні постачальники на основі API-key або env
-- `profile`: постачальники, які з’являються, коли існують профілі auth
-- `paired`: постачальники, які синтезують кілька пов’язаних записів постачальників
-- `late`: останній прохід, після інших неявних постачальників
+- `simple`: звичайні провайдери з API-ключем або керовані env
+- `profile`: провайдери, які з’являються, коли існують профілі автентифікації
+- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдера
+- `late`: останній прохід, після інших неявних провайдерів
-Пізніші постачальники перемагають у разі конфлікту ключів, тож плагіни можуть навмисно
-перевизначати вбудований запис постачальника з тим самим id постачальника.
+Пізніші провайдери перемагають у разі колізії ключів, тому плагіни можуть навмисно
+перевизначати вбудований запис провайдера з тим самим id провайдера.
Сумісність:
-- `discovery` і далі працює як застарілий псевдонім
+- `discovery` усе ще працює як застарілий псевдонім
- якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog`
## Інспекція каналу лише для читання
-Якщо ваш плагін реєструє канал, краще реалізувати
-`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`.
+Якщо ваш плагін реєструє канал, надавайте перевагу реалізації
+`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`.
Чому:
-- `resolveAccount(...)` — це шлях runtime. Він може припускати, що облікові дані
- повністю матеріалізовані, і швидко завершуватися з помилкою, якщо потрібні секрети відсутні.
+- `resolveAccount(...)` — це шлях середовища виконання. Він може припускати, що облікові дані
+ повністю матеріалізовані, і швидко завершуватися з помилкою, коли бракує потрібних секретів.
- Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`,
- `openclaw channels status`, `openclaw channels resolve` і потоки
- doctor/config repair не повинні потребувати матеріалізації runtime-облікових даних лише для
- опису конфігурації.
+ `openclaw channels status`, `openclaw channels resolve` і потоки виправлення doctor/config,
+ не повинні потребувати матеріалізації облікових даних середовища виконання лише для опису конфігурації.
Рекомендована поведінка `inspectAccount(...)`:
-- Повертає лише описовий стан облікового запису.
-- Зберігає `enabled` і `configured`.
-- За потреби включає поля джерела/стану облікових даних, наприклад:
+- Повертайте лише описовий стан облікового запису.
+- Зберігайте `enabled` і `configured`.
+- Додавайте поля джерела/статусу облікових даних, коли це доречно, наприклад:
- `tokenSource`, `tokenStatus`
- `botTokenSource`, `botTokenStatus`
- `appTokenSource`, `appTokenStatus`
- `signingSecretSource`, `signingSecretStatus`
-- Вам не потрібно повертати сирі значення токенів лише для звітування про доступність у режимі лише читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела).
+- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі тільки читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела).
- Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але
вони недоступні в поточному шляху команди.
Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди»
замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано.
-## Package packs
+## Набори пакетів
-Директорія плагіна може містити `package.json` з `openclaw.extensions`:
+Каталог плагіна може містити `package.json` з `openclaw.extensions`:
```json
{
@@ -1351,64 +1345,63 @@ outbound host загальним і використовуйте поверхн
}
```
-Кожен запис стає плагіном. Якщо pack містить кілька розширень, id плагіна
+Кожен запис стає плагіном. Якщо набір перелічує кілька розширень, id плагіна
стає `name/`.
-Якщо ваш плагін імпортує npm-залежності, установіть їх у цій директорії, щоб
+Якщо ваш плагін імпортує npm-залежності, встановіть їх у цьому каталозі, щоб
`node_modules` був доступний (`npm install` / `pnpm install`).
-Запобіжний захід безпеки: кожен запис `openclaw.extensions` має залишатися в межах директорії плагіна
-після розв’язання symlink. Записи, які виходять за межі директорії пакета,
-відхиляються.
+Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу плагіна
+після визначення символьних посилань. Записи, які виходять за межі каталогу пакета, відхиляються.
-Примітка щодо безпеки: `openclaw plugins install` установлює залежності плагіна через
-`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей у runtime). Зберігайте дерева залежностей плагінів «чистими JS/TS» і уникайте пакетів, які потребують `postinstall`-збірок.
+Примітка щодо безпеки: `openclaw plugins install` встановлює залежності плагіна через
+`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей під час виконання). Тримайте дерева залежностей плагіна «чистими JS/TS» і уникайте пакетів, які потребують збирання через `postinstall`.
-Необов’язково: `openclaw.setupEntry` може вказувати на полегшений модуль лише для setup.
-Коли OpenClaw потребує поверхонь setup для вимкненого плагіна каналу або
-коли плагін каналу ввімкнено, але він іще не налаштований, OpenClaw завантажує `setupEntry`
-замість повної точки входу плагіна. Це робить запуск і setup легшими,
-коли головна точка входу плагіна також підключає інструменти, хуки або інший код лише для runtime.
+Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування.
+Коли OpenClaw потребує поверхонь налаштування для вимкненого плагіна каналу, або
+коли плагін каналу увімкнено, але він усе ще не налаштований, він завантажує `setupEntry`
+замість повної точки входу плагіна. Це зберігає запуск і налаштування легшими,
+коли ваша основна точка входу плагіна також підключає інструменти, хуки або інший код,
+призначений лише для середовища виконання.
Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`
-може перевести плагін каналу на той самий шлях `setupEntry` під час
-передпрослуховувальної фази запуску gateway, навіть коли канал уже налаштовано.
+може перевести плагін каналу на той самий шлях `setupEntry` під час фази запуску gateway
+до початку прослуховування, навіть коли канал уже налаштовано.
Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати
-до того, як gateway почне прослуховування. На практиці це означає, що точка входу setup
-має зареєструвати кожну можливість, що належить каналу й від якої залежить запуск, зокрема:
+до того, як gateway почне прослуховування. На практиці це означає, що точка входу налаштування
+має зареєструвати всі можливості, що належать каналу та від яких залежить запуск, зокрема:
- саму реєстрацію каналу
- будь-які HTTP-маршрути, які мають бути доступні до початку прослуховування gateway
-- будь-які методи gateway, інструменти або служби, які мають існувати в тому самому вікні
+- будь-які методи gateway, інструменти або сервіси, які мають існувати протягом цього самого вікна
-Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте
-цей прапорець. Залиште для плагіна типову поведінку й дозвольте OpenClaw завантажити
+Якщо ваша повна точка входу все ще володіє будь-якою необхідною можливістю запуску, не вмикайте
+цей прапорець. Залишайте плагін на стандартній поведінці та дозвольте OpenClaw завантажити
повну точку входу під час запуску.
-Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для setup, які core
-може використовувати до завантаження повного runtime каналу. Поточна поверхня
-просування setup така:
+Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, з якими ядро
+може консультуватися до завантаження повного середовища виконання каналу. Поточна поверхня
+просування налаштування така:
- `singleAccountKeysToMove`
- `namedAccountPromotionKeys`
- `resolveSingleAccountPromotionTarget(...)`
-Core використовує цю поверхню, коли потрібно підвищити застарілу конфігурацію каналу з одним обліковим записом до
+Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію каналу з одним обліковим записом до
`channels..accounts.*` без завантаження повної точки входу плагіна.
-Поточний вбудований приклад — Matrix: він переносить лише ключі auth/bootstrap до
-іменованого підвищеного облікового запису, коли іменовані облікові записи вже існують, і може
-зберегти налаштований неканонічний ключ типового облікового запису замість того, щоб завжди створювати
+Matrix є поточним вбудованим прикладом: він переносить лише ключі auth/bootstrap у
+іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може
+зберігати налаштований неканонічний ключ default-account замість того, щоб завжди створювати
`accounts.default`.
-Ці адаптери patch setup зберігають ледаче виявлення поверхні контракту вбудованих рішень. Час
-імпорту залишається малим; поверхня просування завантажується лише під час першого використання, а не
-повторно входить у запуск вбудованого каналу під час імпорту модуля.
+Ці адаптери патчів налаштування зберігають ледаче виявлення поверхні контракту вбудованих компонентів. Час
+імпорту залишається малим; поверхня просування завантажується лише під час першого використання, а не через повторний вхід у запуск вбудованого каналу під час імпорту модуля.
-Коли ці поверхні запуску включають методи Gateway RPC, зберігайте їх на
-специфічному для плагіна префіксі. Простори імен адміністратора core (`config.*`,
-`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди розв’язуються
-до `operator.admin`, навіть якщо плагін запитує вужчу область.
+Коли ці поверхні запуску включають методи Gateway RPC, тримайте їх на
+префіксі, специфічному для плагіна. Простори імен адміністратора ядра (`config.*`,
+`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими та завжди визначаються
+як `operator.admin`, навіть якщо плагін запитує вужчу область.
Приклад:
@@ -1427,8 +1420,8 @@ Core використовує цю поверхню, коли потрібно
### Метадані каталогу каналів
-Плагіни каналів можуть оголошувати метадані setup/discovery через `openclaw.channel`, а
-підказки щодо встановлення — через `openclaw.install`. Це дозволяє core не містити даних каталогу.
+Плагіни каналів можуть рекламувати метадані налаштування/виявлення через `openclaw.channel` і
+підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити даних каталогу.
Приклад:
@@ -1443,7 +1436,7 @@ Core використовує цю поверхню, коли потрібно
"selectionLabel": "Nextcloud Talk (self-hosted)",
"docsPath": "/channels/nextcloud-talk",
"docsLabel": "nextcloud-talk",
- "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
+ "blurb": "Самостійно розгорнутий чат через ботів вебхуків Nextcloud Talk.",
"order": 65,
"aliases": ["nc-talk", "nc"]
},
@@ -1459,38 +1452,38 @@ Core використовує цю поверхню, коли потрібно
Корисні поля `openclaw.channel` понад мінімальний приклад:
- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу
-- `docsLabel`: перевизначає текст посилання на документацію
+- `docsLabel`: перевизначення тексту посилання для посилання на документацію
- `preferOver`: id плагінів/каналів із нижчим пріоритетом, які цей запис каталогу має випереджати
- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору
-- `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо outbound-форматування
+- `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо вихідного форматування
- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false`
-- `exposure.setup`: приховує канал з інтерактивних вибирачів setup/configure, якщо встановлено `false`
+- `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено `false`
- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації
-- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; краще використовувати `exposure`
-- `quickstartAllowFrom`: додає канал до стандартного потоку quickstart `allowFrom`
-- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис
-- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час розв’язання цілей оголошення
+- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure`
+- `quickstartAllowFrom`: додає канал до стандартного потоку `allowFrom` для швидкого старту
+- `forceAccountBinding`: вимагає явного прив’язування облікового запису, навіть якщо існує лише один обліковий запис
+- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення цілей оголошення
-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"`.
-## Плагіни контекстного рушія
+## Плагіни механізму контексту
-Плагіни контекстного рушія володіють оркестрацією контексту сесії для ingest, assembly
-та compaction. Реєструйте їх із вашого плагіна через
-`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через
+Плагіни механізму контексту володіють оркестрацією контексту сесії для поглинання, збирання
+та ущільнення. Реєструйте їх із вашого плагіна через
+`api.registerContextEngine(id, factory)`, а потім вибирайте активний механізм через
`plugins.slots.contextEngine`.
-Використовуйте це, коли вашому плагіну потрібно замінити або розширити типовий
-конвеєр контексту, а не просто додати memory search або хуки.
+Використовуйте це, коли вашому плагіну потрібно замінити або розширити стандартний
+конвеєр контексту, а не просто додати пошук у пам’яті або хуки.
```ts
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
@@ -1518,7 +1511,7 @@ export default function (api) {
}
```
-Якщо ваш рушій **не** володіє алгоритмом compaction, залиште `compact()`
+Якщо ваш механізм **не** володіє алгоритмом ущільнення, залишайте `compact()`
реалізованим і явно делегуйте його:
```ts
@@ -1557,40 +1550,40 @@ export default function (api) {
## Додавання нової можливості
Коли плагіну потрібна поведінка, яка не вписується в поточний API, не обходьте
-систему плагінів через приватний доступ до внутрішніх частин. Додайте відсутню можливість.
+систему плагінів через приватне проникнення всередину. Додайте відсутню можливість.
Рекомендована послідовність:
-1. визначте контракт core
- Вирішіть, якою спільною поведінкою має володіти core: політика, резервний вибір, злиття конфігурації,
- життєвий цикл, семантика для каналів і форма допоміжного засобу runtime.
-2. додайте типізовані поверхні реєстрації/runtime плагіна
+1. визначте контракт ядра
+ Вирішіть, якою спільною поведінкою має володіти ядро: політика, резервні механізми, об’єднання конфігурації,
+ життєвий цикл, семантика, орієнтована на канали, і форма допоміжних засобів середовища виконання.
+2. додайте типізовані поверхні реєстрації/середовища виконання плагінів
Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною
типізованою поверхнею можливості.
-3. підключіть споживачів core + каналів/функцій
- Канали та плагіни функцій мають споживати нову можливість через core,
- а не імпортувати реалізацію вендора напряму.
-4. зареєструйте реалізації вендорів
- Потім плагіни вендорів реєструють свої бекенди для цієї можливості.
+3. під’єднайте споживачів ядра + каналів/функцій
+ Канали та плагіни функцій мають споживати нову можливість через ядро,
+ а не шляхом прямого імпорту реалізації постачальника.
+4. зареєструйте реалізації постачальників
+ Потім плагіни постачальників реєструють свої серверні частини для цієї можливості.
5. додайте покриття контракту
- Додайте тести, щоб володіння та форма реєстрації з часом залишалися явними.
+ Додайте тести, щоб володіння і форма реєстрації з часом залишалися явними.
-Саме так OpenClaw залишається концептуально цілісним, не стаючи жорстко прив’язаним до
-бачення одного постачальника. Дивіться [Збірник рецептів для можливостей](/uk/plugins/architecture),
-щоб побачити конкретний контрольний список файлів і опрацьований приклад.
+Саме так OpenClaw зберігає визначеність, не стаючи жорстко прив’язаним до
+світогляду одного провайдера. Дивіться [Збірник рецептів можливостей](/uk/plugins/architecture)
+для конкретного контрольного списку файлів і готового прикладу.
-### Контрольний список можливості
+### Контрольний список можливостей
-Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися таких
-поверхонь:
+Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих
+поверхонь разом:
-- типи контрактів core у `src//types.ts`
-- helper runner/runtime у core в `src//runtime.ts`
+- типи контракту ядра в `src//types.ts`
+- засіб виконання/допоміжний засіб ядра в `src//runtime.ts`
- поверхня реєстрації API плагінів у `src/plugins/types.ts`
- підключення реєстру плагінів у `src/plugins/registry.ts`
-- відкриття runtime плагінів у `src/plugins/runtime/*`, коли плагінам функцій/каналів
- потрібно це споживати
-- helper для capture/test у `src/test-utils/plugin-registration.ts`
+- відкриття середовища виконання плагінів у `src/plugins/runtime/*`, коли плагіни функцій/каналів
+ мають це споживати
+- допоміжні засоби захоплення/тестування в `src/test-utils/plugin-registration.ts`
- перевірки володіння/контракту в `src/plugins/contracts/registry.ts`
- документація для операторів/плагінів у `docs/`
@@ -1633,7 +1626,7 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
Це зберігає правило простим:
-- core володіє контрактом можливості + оркестрацією
-- плагіни вендорів володіють реалізаціями вендорів
-- плагіни функцій/каналів споживають допоміжні засоби runtime
-- контрактні тести зберігають явність володіння
+- ядро володіє контрактом можливості + оркестрацією
+- плагіни постачальників володіють реалізаціями постачальників
+- плагіни функцій/каналів споживають допоміжні засоби середовища виконання
+- контрактні тести зберігають володіння явним
diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md
index 502434769..a253ce2e5 100644
--- a/docs/uk/plugins/manifest.md
+++ b/docs/uk/plugins/manifest.md
@@ -2,13 +2,13 @@
read_when:
- Ви створюєте плагін OpenClaw
- Вам потрібно постачати схему конфігурації плагіна або налагоджувати помилки валідації плагіна
-summary: Маніфест плагіна + вимоги до JSON schema (сувора валідація конфігурації)
+summary: Вимоги до маніфесту плагіна + JSON schema (сувора валідація конфігурації)
title: Маніфест плагіна
x-i18n:
- generated_at: "2026-04-11T11:37:24Z"
+ generated_at: "2026-04-12T02:30:56Z"
model: gpt-5.4
provider: openai
- source_hash: 42d454b560a8f6bf714c5d782f34216be1216d83d0a319d08d7349332c91a9e4
+ source_hash: bf666b0f41f07641375a248f52e29ba6a68c3ec20404bedb6b52a20a5cd92e91
source_path: plugins/manifest.md
workflow: 15
---
@@ -17,35 +17,35 @@ x-i18n:
Ця сторінка стосується лише **власного маніфесту плагіна OpenClaw**.
-Сумісні макети пакетів описано в [Пакети плагінів](/uk/plugins/bundles).
+Сумісні макети пакунків описано в [Пакунки плагінів](/uk/plugins/bundles).
-Сумісні формати пакетів використовують інші файли маніфесту:
+Сумісні формати пакунків використовують інші файли маніфесту:
-- Пакет Codex: `.codex-plugin/plugin.json`
-- Пакет Claude: `.claude-plugin/plugin.json` або стандартний макет компонента Claude
+- Пакунок Codex: `.codex-plugin/plugin.json`
+- Пакунок Claude: `.claude-plugin/plugin.json` або типовий макет компонентів Claude
без маніфесту
-- Пакет Cursor: `.cursor-plugin/plugin.json`
+- Пакунок Cursor: `.cursor-plugin/plugin.json`
-OpenClaw також автоматично виявляє ці макети пакетів, але вони не проходять валідацію
+OpenClaw також автоматично виявляє ці макети пакунків, але вони не проходять валідацію
за схемою `openclaw.plugin.json`, описаною тут.
-Для сумісних пакетів OpenClaw наразі читає метадані пакета, а також оголошені
-кореневі каталоги Skills, кореневі каталоги команд Claude, типові значення `settings.json` пакета Claude,
-типові значення LSP пакета Claude та підтримувані набори хуків, якщо макет відповідає
+Для сумісних пакунків OpenClaw наразі зчитує метадані пакунка, а також оголошені
+кореневі каталоги skill, кореневі каталоги команд Claude, типові значення `settings.json` у пакунку Claude,
+типові значення LSP у пакунку Claude та підтримувані набори hooks, якщо макет відповідає
очікуванням середовища виконання OpenClaw.
-Кожен власний плагін OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у
+Кожен власний плагін OpenClaw **має** постачатися з файлом `openclaw.plugin.json` у
**корені плагіна**. OpenClaw використовує цей маніфест для валідації конфігурації
**без виконання коду плагіна**. Відсутні або невалідні маніфести вважаються
-помилками плагіна і блокують валідацію конфігурації.
+помилками плагіна та блокують валідацію конфігурації.
-Повний посібник із системи плагінів див. у [Плагіни](/uk/tools/plugin).
-Для власної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності:
+Дивіться повний посібник із системи плагінів: [Плагіни](/uk/tools/plugin).
+Щодо власної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності:
[Модель можливостей](/uk/plugins/architecture#public-capability-model).
-## Для чого потрібен цей файл
+## Що робить цей файл
-`openclaw.plugin.json` — це метадані, які OpenClaw читає до завантаження коду
+`openclaw.plugin.json` — це метадані, які OpenClaw зчитує перед завантаженням коду
вашого плагіна.
Використовуйте його для:
@@ -54,27 +54,25 @@ OpenClaw також автоматично виявляє ці макети па
- валідації конфігурації
- метаданих автентифікації та онбордингу, які мають бути доступні без запуску
середовища виконання плагіна
-- легких підказок активації, які поверхні control-plane можуть перевіряти до
- завантаження середовища виконання
-- легких дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до
- завантаження середовища виконання
-- метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження
- середовища виконання плагіна
-- скорочених метаданих належності до сімейства моделей, які мають автоматично активувати
- плагін до завантаження середовища виконання
-- статичних знімків належності можливостей, що використовуються для сумісної обв’язки
- bundled-плагінів і покриття контрактів
-- метаданих конфігурації каналу, специфічних для каналу, які мають зливатися в поверхні
- каталогу та валідації без завантаження середовища виконання
+- легковагих підказок активації, які поверхні control plane можуть перевіряти до завантаження runtime
+- легковагих дескрипторів налаштування, які поверхні setup/onboarding можуть перевіряти до завантаження
+ runtime
+- метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження runtime плагіна
+- скорочених метаданих належності до сімейств моделей, які мають автоматично активувати
+ плагін до завантаження runtime
+- статичних знімків належності можливостей, які використовуються для bundled compat wiring і
+ покриття контрактів
+- метаданих конфігурації каналу, специфічних для каналу, які мають об’єднуватися в поверхні каталогу та валідації
+ без завантаження runtime
- підказок UI для конфігурації
Не використовуйте його для:
-- реєстрації поведінки під час виконання
-- оголошення кодових entrypoint
+- реєстрації поведінки runtime
+- оголошення entrypoint коду
- метаданих встановлення npm
-Це належить до коду вашого плагіна та `package.json`.
+Це належить вашому коду плагіна та `package.json`.
## Мінімальний приклад
@@ -145,64 +143,64 @@ OpenClaw також автоматично виявляє ці макети па
}
```
-## Довідка щодо полів верхнього рівня
+## Довідник полів верхнього рівня
-| Поле | Обов’язкове | Тип | Що це означає |
+| Поле | Обов’язкове | Тип | Що воно означає |
| ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | Так | `string` | Канонічний id плагіна. Це id, який використовується в `plugins.entries.`. |
| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього плагіна. |
-| `enabledByDefault` | Ні | `true` | Позначає bundled-плагін як увімкнений типово. Пропустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб залишити плагін вимкненим типово. |
+| `enabledByDefault` | Ні | `true` | Позначає bundled plugin як увімкнений за замовчуванням. Опустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб плагін залишався вимкненим за замовчуванням. |
| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id плагіна. |
-| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які мають автоматично вмикати цей плагін, коли автентифікація, конфігурація або посилання на моделі згадують їх. |
-| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує винятковий вид плагіна, який використовується `plugins.slots.*`. |
-| `channels` | Ні | `string[]` | Id каналів, якими володіє цей плагін. Використовується для виявлення та валідації конфігурації. |
+| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які мають автоматично вмикати цей плагін, коли на них посилаються auth, config або model refs. |
+| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує виключний тип плагіна, який використовується `plugins.slots.*`. |
+| `channels` | Ні | `string[]` | Id каналів, якими володіє цей плагін. Використовуються для виявлення та валідації конфігурації. |
| `providers` | Ні | `string[]` | Id провайдерів, якими володіє цей плагін. |
-| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, якими володіє маніфест, що використовуються для автоматичного завантаження плагіна до середовища виконання. |
-| `cliBackends` | Ні | `string[]` | Id backend у CLI, якими володіє цей плагін. Використовується для автоактивації під час запуску з явних посилань у конфігурації. |
-| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей плагін, що мають створювати діагностику конфігурації й CLI з урахуванням плагіна до завантаження середовища виконання. |
-| `providerAuthEnvVars` | Ні | `Record` | Легкі метадані env для автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. |
-| `providerAuthAliases` | Ні | `Record` | Id провайдерів, які мають повторно використовувати інший id провайдера для пошуку автентифікації, наприклад coding-провайдер, що ділить API key і профілі автентифікації з базовим провайдером. |
-| `channelEnvVars` | Ні | `Record` | Легкі метадані env каналу, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналу через env або поверхонь автентифікації, які мають бачити типові помічники запуску/конфігурації. |
-| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для picker онбордингу, визначення бажаного провайдера та простого зв’язування прапорців CLI. |
-| `activation` | Ні | `object` | Легкі підказки активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактична поведінка як і раніше належить середовищу виконання плагіна. |
-| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання плагіна. |
-| `contracts` | Ні | `object` | Статичний bundled-знімок можливостей для 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, placeholders і підказки чутливості для полів конфігурації. |
+| `modelSupport` | Ні | `object` | Скорочені метадані сімейств моделей, якими володіє маніфест, що використовуються для автоматичного завантаження плагіна до runtime. |
+| `cliBackends` | Ні | `string[]` | Id backend для висновування в CLI, якими володіє цей плагін. Використовуються для автоматичної активації під час запуску з явних посилань у config. |
+| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей плагін, і які мають створювати діагностику конфігурації та CLI з урахуванням плагіна до завантаження runtime. |
+| `providerAuthEnvVars` | Ні | `Record` | Легковагі метадані env для auth провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. |
+| `providerAuthAliases` | Ні | `Record` | Id провайдерів, які мають повторно використовувати інший id провайдера для пошуку auth, наприклад coding provider, що спільно використовує API key базового провайдера та профілі auth. |
+| `channelEnvVars` | Ні | `Record` | Легковагі метадані env каналу, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналів через env або поверхонь auth, які мають бачити загальні helpers запуску/config. |
+| `providerAuthChoices` | Ні | `object[]` | Легковагі метадані вибору auth для picker-ів онбордингу, визначення preferred provider і простого зв’язування прапорців CLI. |
+| `activation` | Ні | `object` | Легковагі підказки активації для завантаження, що запускається провайдером, командою, каналом, маршрутом або можливістю. Лише метадані; фактичною поведінкою як і раніше володіє runtime плагіна. |
+| `setup` | Ні | `object` | Легковагі дескриптори setup/onboarding, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime плагіна. |
+| `contracts` | Ні | `object` | Статичний знімок bundled capability для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і належності tool. |
+| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, якими володіє маніфест, що об’єднуються в поверхні виявлення та валідації до завантаження runtime. |
+| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня плагіна. |
+| `name` | Ні | `string` | Людинозрозуміла назва плагіна. |
+| `description` | Ні | `string` | Короткий опис, що показується в поверхнях плагіна. |
+| `version` | Ні | `string` | Інформаційна версія плагіна. |
+| `uiHints` | Ні | `Record` | Мітки UI, placeholders і підказки щодо чутливості для полів конфігурації. |
-## Довідка щодо `providerAuthChoices`
+## Довідник `providerAuthChoices`
-Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації.
-OpenClaw читає це до завантаження середовища виконання провайдера.
+Кожен запис `providerAuthChoices` описує один варіант онбордингу або auth.
+OpenClaw зчитує це до завантаження runtime провайдера.
-| Поле | Обов’язкове | Тип | Що це означає |
-| --------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `provider` | Так | `string` | Id провайдера, до якого належить цей варіант. |
-| `method` | Так | `string` | Id методу автентифікації, до якого слід спрямувати запит. |
-| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, який використовується в онбордингу та потоках CLI. |
-| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо пропущено, OpenClaw використовує `choiceId`. |
-| `choiceHint` | Ні | `string` | Короткий допоміжний текст для picker. |
-| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних picker, керованих асистентом. |
-| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із picker асистента, але все одно дозволяє ручний вибір через CLI. |
-| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів до цього варіанта-заміни. |
-| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. |
-| `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 провайдера, до якого належить цей варіант. |
+| `method` | Так | `string` | Id методу auth, до якого слід диспетчеризувати. |
+| `choiceId` | Так | `string` | Стабільний id варіанта auth, який використовується в потоках онбордингу та CLI. |
+| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо її не вказано, OpenClaw використовує `choiceId`. |
+| `choiceHint` | Ні | `string` | Короткий допоміжний текст для picker-а. |
+| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних picker-ах, керованих асистентом. |
+| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із picker-ів асистента, але все ще дозволяє ручний вибір через CLI. |
+| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів на цей варіант-заміну. |
+| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. |
+| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. |
+| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
+| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків auth з одним прапорцем. |
+| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. |
+| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. |
+| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. |
+| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, використовується `["text-inference"]`. |
-## Довідка щодо `commandAliases`
+## Довідник `commandAliases`
Використовуйте `commandAliases`, коли плагін володіє назвою runtime-команди, яку користувачі можуть
помилково помістити в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw
-використовує ці метадані для діагностики без імпорту коду середовища виконання плагіна.
+використовує ці метадані для діагностики без імпорту коду runtime плагіна.
```json
{
@@ -216,19 +214,19 @@ OpenClaw читає це до завантаження середовища ви
}
```
-| Поле | Обов’язкове | Тип | Що це означає |
-| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------ |
-| `name` | Так | `string` | Назва команди, яка належить цьому плагіну. |
-| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду CLI. |
-| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо вона існує. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------ | ----------- | ----------------- | --------------------------------------------------------------------------- |
+| `name` | Так | `string` | Назва команди, яка належить цьому плагіну. |
+| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. |
+| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід рекомендувати для операцій CLI, якщо вона існує. |
-## Довідка щодо `activation`
+## Довідник `activation`
-Використовуйте `activation`, коли плагін може дешево оголосити, які події control-plane
+Використовуйте `activation`, коли плагін може дешево оголосити, які події control plane
мають активувати його пізніше.
-Цей блок містить лише метадані. Він не реєструє поведінку під час виконання і
-не замінює `register(...)`, `setupEntry` чи інші entrypoint runtime/плагіна.
+Цей блок містить лише метадані. Він не реєструє поведінку runtime і не
+замінює `register(...)`, `setupEntry` або інші runtime/plugin entrypoint-и.
```json
{
@@ -242,18 +240,18 @@ OpenClaw читає це до завантаження середовища ви
}
```
-| Поле | Обов’язкове | Тип | Що це означає |
-| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------ |
-| `onProviders` | Ні | `string[]` | Id провайдерів, які мають активувати цей плагін за запитом. |
-| `onCommands` | Ні | `string[]` | Id команд, які мають активувати цей плагін. |
-| `onChannels` | Ні | `string[]` | Id каналів, які мають активувати цей плагін. |
-| `onRoutes` | Ні | `string[]` | Види маршрутів, які мають активувати цей плагін. |
-| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються в плануванні активації control-plane. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ---------------- | ----------- | ---------------------------------------------------- | --------------------------------------------------------------- |
+| `onProviders` | Ні | `string[]` | Id провайдерів, які мають активувати цей плагін за запитом. |
+| `onCommands` | Ні | `string[]` | Id команд, які мають активувати цей плагін. |
+| `onChannels` | Ні | `string[]` | Id каналів, які мають активувати цей плагін. |
+| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей плагін. |
+| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються в плануванні активації control plane. |
-## Довідка щодо `setup`
+## Довідник `setup`
-Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні дешеві метадані, якими володіє плагін,
-до завантаження середовища виконання.
+Використовуйте `setup`, коли поверхням setup та онбордингу потрібні дешеві метадані,
+якими володіє плагін, до завантаження runtime.
```json
{
@@ -272,30 +270,40 @@ OpenClaw читає це до завантаження середовища ви
}
```
-Поле верхнього рівня `cliBackends` залишається валідним і надалі описує backend інференсу CLI.
-`setup.cliBackends` — це поверхня дескриптора, специфічна для налаштування,
-для потоків control-plane/налаштування, яка має залишатися лише метаданими.
+`cliBackends` верхнього рівня залишається валідним і надалі описує backend-и
+висновування CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup,
+для потоків control plane/setup, яка має залишатися лише метаданими.
-### Довідка щодо `setup.providers`
+Якщо вони присутні, `setup.providers` і `setup.cliBackends` є бажаною
+поверхнею пошуку на основі дескрипторів для виявлення setup. Якщо дескриптор лише
+звужує коло плагінів-кандидатів, а setup все ще потребує багатших runtime hooks під час setup,
+встановіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання.
-| Поле | Обов’язкове | Тип | Що це означає |
-| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------- |
-| `id` | Так | `string` | Id провайдера, який показується під час налаштування або онбордингу. |
-| `authMethods` | Ні | `string[]` | Id методів налаштування/автентифікації, які цей провайдер підтримує без завантаження повного runtime. |
-| `envVars` | Ні | `string[]` | Env vars, які типові поверхні налаштування/статусу можуть перевіряти до завантаження runtime плагіна. |
+Оскільки пошук setup може виконувати код `setup-api`, яким володіє плагін, нормалізовані
+значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед
+виявлених плагінів. Неоднозначна належність завершується без вибору замість того, щоб
+обирати переможця за порядком виявлення.
+
+### Довідник `setup.providers`
+
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------------- |
+| `id` | Так | `string` | Id провайдера, який надається під час setup або онбордингу. Нормалізовані id мають бути глобально унікальними. |
+| `authMethods` | Ні | `string[]` | Id методів setup/auth, які цей провайдер підтримує без завантаження повного runtime. |
+| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження runtime плагіна. |
### Поля `setup`
-| Поле | Обов’язкове | Тип | Що це означає |
-| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------ |
-| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, які показуються під час налаштування та онбордингу. |
-| `cliBackends` | Ні | `string[]` | Id backend, доступних під час налаштування без повної активації runtime. |
-| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє поверхня налаштування цього плагіна. |
-| `requiresRuntime` | Ні | `boolean` | Чи потребує налаштування виконання runtime плагіна після пошуку дескриптора. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------------ | ----------- | ---------- | ----------------------------------------------------------------------------------------------------- |
+| `providers` | Ні | `object[]` | Дескриптори setup провайдерів, доступні під час setup та онбордингу. |
+| `cliBackends` | Ні | `string[]` | Id backend-ів для часу setup, які використовуються для пошуку setup за принципом descriptor-first. Нормалізовані id мають бути глобально унікальними. |
+| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє поверхня setup цього плагіна. |
+| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. |
-## Довідка щодо `uiHints`
+## Довідник `uiHints`
-`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу.
+`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для відображення.
```json
{
@@ -310,9 +318,9 @@ OpenClaw читає це до завантаження середовища ви
}
```
-Кожна підказка поля може містити:
+Кожна підказка для поля може містити:
-| Поле | Тип | Що це означає |
+| Поле | Тип | Що воно означає |
| ------------- | ---------- | --------------------------------------- |
| `label` | `string` | Мітка поля для користувача. |
| `help` | `string` | Короткий допоміжний текст. |
@@ -321,10 +329,10 @@ OpenClaw читає це до завантаження середовища ви
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
| `placeholder` | `string` | Текст placeholder для полів форми. |
-## Довідка щодо `contracts`
+## Довідник `contracts`
Використовуйте `contracts` лише для статичних метаданих належності можливостей, які OpenClaw може
-читати без імпорту runtime плагіна.
+зчитувати без імпорту runtime плагіна.
```json
{
@@ -344,22 +352,22 @@ OpenClaw читає це до завантаження середовища ви
Кожен список є необов’язковим:
-| Поле | Тип | Що це означає |
-| -------------------------------- | ---------- | -------------------------------------------------------------- |
-| `speechProviders` | `string[]` | Id speech-провайдерів, якими володіє цей плагін. |
-| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів realtime transcription, якими володіє цей плагін. |
-| `realtimeVoiceProviders` | `string[]` | Id провайдерів realtime voice, якими володіє цей плагін. |
-| `mediaUnderstandingProviders` | `string[]` | Id провайдерів media-understanding, якими володіє цей плагін. |
-| `imageGenerationProviders` | `string[]` | Id провайдерів image-generation, якими володіє цей плагін. |
-| `videoGenerationProviders` | `string[]` | Id провайдерів video-generation, якими володіє цей плагін. |
-| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей плагін. |
-| `webSearchProviders` | `string[]` | Id провайдерів web search, якими володіє цей плагін. |
-| `tools` | `string[]` | Назви інструментів агента, якими володіє цей плагін, для bundled-перевірок контрактів. |
+| Поле | Тип | Що воно означає |
+| -------------------------------- | ---------- | ------------------------------------------------------------- |
+| `speechProviders` | `string[]` | Id speech-провайдерів, якими володіє цей плагін. |
+| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів realtime-transcription, якими володіє цей плагін. |
+| `realtimeVoiceProviders` | `string[]` | Id провайдерів realtime-voice, якими володіє цей плагін. |
+| `mediaUnderstandingProviders` | `string[]` | Id провайдерів media-understanding, якими володіє цей плагін. |
+| `imageGenerationProviders` | `string[]` | Id провайдерів image-generation, якими володіє цей плагін. |
+| `videoGenerationProviders` | `string[]` | Id провайдерів video-generation, якими володіє цей плагін. |
+| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей плагін. |
+| `webSearchProviders` | `string[]` | Id провайдерів web-search, якими володіє цей плагін. |
+| `tools` | `string[]` | Назви agent tool, якими володіє цей плагін, для bundled перевірок контрактів. |
-## Довідка щодо `channelConfigs`
+## Довідник `channelConfigs`
-Використовуйте `channelConfigs`, коли плагіну каналу потрібні дешеві метадані конфігурації
-до завантаження runtime.
+Використовуйте `channelConfigs`, коли плагіну каналу потрібні дешеві метадані конфігурації до
+завантаження runtime.
```json
{
@@ -379,7 +387,7 @@ OpenClaw читає це до завантаження середовища ви
}
},
"label": "Matrix",
- "description": "Підключення до homeserver Matrix",
+ "description": "Matrix homeserver connection",
"preferOver": ["matrix-legacy"]
}
}
@@ -388,18 +396,19 @@ OpenClaw читає це до завантаження середовища ви
Кожен запис каналу може містити:
-| Поле | Тип | Що це означає |
-| ------------ | ------------------------ | --------------------------------------------------------------------------------------------- |
-| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. |
-| `uiHints` | `Record` | Необов’язкові мітки UI/placeholders/підказки чутливості для цього розділу конфігурації каналу. |
-| `label` | `string` | Мітка каналу, що зливається в поверхні picker та inspect, коли метадані runtime ще не готові. |
-| `description`| `string` | Короткий опис каналу для поверхонь inspect і каталогу. |
-| `preferOver` | `string[]` | Id застарілих або нижчопріоритетних плагінів, які цей канал має випереджати в поверхнях вибору. |
+| Поле | Тип | Що воно означає |
+| ------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
+| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. |
+| `uiHints` | `Record` | Необов’язкові мітки UI/placeholders/підказки чутливості для цього розділу конфігурації каналу. |
+| `label` | `string` | Мітка каналу, що об’єднується в picker та inspect surfaces, коли метадані runtime ще не готові. |
+| `description` | `string` | Короткий опис каналу для поверхонь inspect і catalog. |
+| `preferOver` | `string[]` | Застарілі або нижчопріоритетні id плагінів, які цей канал має випереджати в поверхнях вибору. |
-## Довідка щодо `modelSupport`
+## Довідник `modelSupport`
Використовуйте `modelSupport`, коли OpenClaw має визначати ваш плагін провайдера з
-коротких id моделей, таких як `gpt-5.4` або `claude-sonnet-4.6`, до завантаження runtime плагіна.
+коротких id моделей, таких як `gpt-5.4` або `claude-sonnet-4.6`, до завантаження runtime
+плагіна.
```json
{
@@ -410,75 +419,75 @@ OpenClaw читає це до завантаження середовища ви
}
```
-OpenClaw застосовує такий пріоритет:
+OpenClaw застосовує таку пріоритетність:
-- явні посилання `provider/model` використовують метадані маніфесту власника `providers`
-- `modelPatterns` мають пріоритет над `modelPrefixes`
-- якщо збігаються один не-bundled плагін і один bundled-плагін, перемагає не-bundled
+- явні посилання `provider/model` використовують метадані маніфесту `providers`, якими володіє плагін
+- `modelPatterns` мають вищий пріоритет за `modelPrefixes`
+- якщо збігаються один небандлований плагін і один bundled plugin, перемагає небандлований
плагін
-- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть провайдера
+- решта неоднозначностей ігноруються, доки користувач або config не вкаже провайдера
Поля:
-| Поле | Тип | Що це означає |
-| --------------- | ---------- | ------------------------------------------------------------------------------ |
-| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` із короткими id моделей. |
-| `modelPatterns` | `string[]` | Джерела regex, що зіставляються з короткими id моделей після видалення суфікса профілю. |
+| Поле | Тип | Що воно означає |
+| --------------- | ---------- | ------------------------------------------------------------------------------------- |
+| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` із короткими id моделей. |
+| `modelPatterns` | `string[]` | Джерела regex, які зіставляються з короткими id моделей після видалення суфікса профілю. |
-Застарілі ключі можливостей верхнього рівня не рекомендовані. Використовуйте `openclaw doctor --fix`, щоб
+Застарілі ключі можливостей верхнього рівня не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб
перемістити `speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`,
-`webFetchProviders` і `webSearchProviders` у `contracts`; звичайне
+`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне
завантаження маніфесту більше не трактує ці поля верхнього рівня як
належність можливостей.
-## Маніфест і package.json
+## Маніфест проти package.json
-Ці два файли виконують різні завдання:
+Ці два файли виконують різні ролі:
-| Файл | Для чого його використовувати |
+| Файл | Використовуйте його для |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду плагіна |
-| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoint, обмежень встановлення, налаштування або метаданих каталогу |
+| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані вибору auth і підказки UI, які мають існувати до запуску коду плагіна |
+| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для entrypoint-ів, обмежень установлення, setup або метаданих каталогу |
Якщо ви не впевнені, куди має належати певний фрагмент метаданих, користуйтеся таким правилом:
-- якщо OpenClaw повинен знати це до завантаження коду плагіна, помістіть це в `openclaw.plugin.json`
-- якщо це стосується пакування, entry-файлів або поведінки встановлення npm, помістіть це в `package.json`
+- якщо OpenClaw має знати це до завантаження коду плагіна, помістіть це в `openclaw.plugin.json`
+- якщо це стосується пакування, файлів входу або поведінки встановлення npm, помістіть це в `package.json`
-### Поля `package.json`, які впливають на виявлення
+### Поля package.json, які впливають на виявлення
Частина метаданих плагіна до runtime навмисно зберігається в `package.json` у блоці
`openclaw`, а не в `openclaw.plugin.json`.
Важливі приклади:
-| Поле | Що це означає |
-| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
-| `openclaw.extensions` | Оголошує entrypoint власних плагінів. |
-| `openclaw.setupEntry` | Легкий entrypoint лише для налаштування, який використовується під час онбордингу та відкладеного запуску каналу. |
-| `openclaw.channel` | Легкі метадані каталогу каналів, такі як мітки, шляхи до документації, псевдоніми та текст для вибору. |
-| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного runtime каналу. |
-| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже щось увійшло в систему?» без завантаження повного runtime каналу. |
-| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для bundled-плагінів і зовнішньо опублікованих плагінів. |
-| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
-| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із нижньою межею semver, наприклад `>=2026.3.22`. |
-| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення bundled-плагіна, коли конфігурація невалідна. |
-| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє завантажувати поверхні каналу лише для налаштування до повного плагіна каналу під час запуску. |
+| Поле | Що воно означає |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `openclaw.extensions` | Оголошує entrypoint-и власних плагінів. |
+| `openclaw.setupEntry` | Легковагий entrypoint лише для setup, який використовується під час онбордингу та відкладеного запуску каналу. |
+| `openclaw.channel` | Легковагі метадані каталогу каналів, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. |
+| `openclaw.channel.configuredState` | Легковагі метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного runtime каналу. |
+| `openclaw.channel.persistedAuthState` | Легковагі метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного runtime каналу. |
+| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для bundled і зовнішньо опублікованих плагінів. |
+| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
+| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, із нижньою межею semver на кшталт `>=2026.3.22`. |
+| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення bundled plugin, коли конфігурація невалідна. |
+| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного плагіна каналу під час запуску. |
-`openclaw.install.minHostVersion` перевіряється під час встановлення та
+`openclaw.install.minHostVersion` застосовується під час встановлення та
завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають
плагін на старіших хостах.
`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке застосування. Воно
-не робить довільно зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам встановлення
-відновлюватися після певних застарілих збоїв оновлення bundled-плагінів, наприклад відсутнього шляху до bundled-плагіна
-або застарілого запису `channels.` для того самого
-bundled-плагіна. Непов’язані помилки конфігурації все одно блокують встановлення та спрямовують операторів
+не робить довільні зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам встановлення
+відновлюватися після певних застарілих збоїв оновлення bundled plugin, наприклад
+відсутнього шляху bundled plugin або застарілого запису `channels.` для того самого
+bundled plugin. Непов’язані помилки конфігурації все одно блокують встановлення та спрямовують операторів
до `openclaw doctor --fix`.
-`openclaw.channel.persistedAuthState` — це метадані пакета для маленького модуля перевірки:
+`openclaw.channel.persistedAuthState` — це метадані пакунка для маленького модуля перевірки:
```json
{
@@ -494,12 +503,11 @@ bundled-плагіна. Непов’язані помилки конфігур
}
```
-Використовуйте це, коли потокам налаштування, doctor або configured-state потрібна дешева перевірка автентифікації
-так/ні до завантаження повного плагіна каналу. Цільовий експорт має бути невеликою
-функцією, що лише читає збережений стан; не спрямовуйте її через повний barrel runtime каналу.
+Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка auth
+типу так/ні до завантаження повного плагіна каналу. Цільовий export має бути невеликою
+функцією, яка лише читає збережений стан; не спрямовуйте її через повний barrel runtime каналу.
-`openclaw.channel.configuredState` має таку саму форму для дешевих перевірок
-налаштованого стану лише через env:
+`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок configured-state лише через env:
```json
{
@@ -515,63 +523,63 @@ bundled-плагіна. Непов’язані помилки конфігур
}
```
-Використовуйте це, коли канал може визначити налаштований стан за env або іншими невеликими
-не-runtime входами. Якщо перевірка потребує повного визначення конфігурації або реального
-runtime каналу, залиште цю логіку в хуку плагіна `config.hasConfiguredState`.
+Використовуйте це, коли канал може визначити configured-state через env або інші невеликі
+входи, не пов’язані з runtime. Якщо перевірка потребує повного розв’язання config або справжнього
+runtime каналу, залиште цю логіку в hook `config.hasConfiguredState` плагіна.
## Вимоги до JSON Schema
-- **Кожен плагін повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію.
-- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
-- Схеми проходять валідацію під час читання/запису конфігурації, а не під час runtime.
+- **Кожен плагін має постачатися з JSON Schema**, навіть якщо він не приймає конфігурації.
+- Порожня схема припустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
+- Схеми проходять валідацію під час читання/запису config, а не під час runtime.
## Поведінка валідації
-- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошено
- маніфестом плагіна.
+- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошений
+ у маніфесті плагіна.
- `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*`
- повинні посилатися на **виявлювані** id плагінів. Невідомі id є **помилками**.
-- Якщо плагін встановлено, але він має зламаний або відсутній маніфест чи схему,
+ мають посилатися на id плагінів, які **можна виявити**. Невідомі id є **помилками**.
+- Якщо плагін установлено, але він має зламаний або відсутній маніфест чи схему,
валідація завершується помилкою, а Doctor повідомляє про помилку плагіна.
-- Якщо конфігурація плагіна існує, але сам плагін **вимкнений**, конфігурація зберігається, і
- у Doctor + журналах відображається **попередження**.
+- Якщо конфігурація плагіна існує, але сам плагін **вимкнено**, конфігурація зберігається, і
+ у Doctor + logs відображається **попередження**.
-Повну схему `plugins.*` див. у [Довідник конфігурації](/uk/gateway/configuration).
+Дивіться [Довідник конфігурації](/uk/gateway/configuration) для повної схеми `plugins.*`.
## Примітки
- Маніфест **обов’язковий для власних плагінів OpenClaw**, включно із завантаженням із локальної файлової системи.
-- Runtime і далі завантажує модуль плагіна окремо; маніфест використовується лише для
+- Runtime, як і раніше, завантажує модуль плагіна окремо; маніфест призначений лише для
виявлення + валідації.
- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та
- ключі без лапок допускаються, якщо кінцеве значення все одно є об’єктом.
-- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання
- тут власних ключів верхнього рівня.
-- `providerAuthEnvVars` — це шлях дешевих метаданих для перевірок автентифікації, валідації
- env-маркерів та подібних поверхонь автентифікації провайдера, які не повинні запускати runtime плагіна
+ ключі без лапок допускаються, якщо кінцеве значення все ще є об’єктом.
+- Завантажувач маніфестів читає лише задокументовані поля маніфесту. Уникайте додавання
+ власних ключів верхнього рівня сюди.
+- `providerAuthEnvVars` — це дешевий шлях метаданих для перевірок auth, валідації
+ env-marker та подібних поверхонь auth провайдера, які не повинні запускати runtime плагіна
лише для перевірки назв env.
-- `providerAuthAliases` дозволяє варіантам провайдерів повторно використовувати vars env автентифікації,
- профілі автентифікації, автентифікацію на основі конфігурації та варіант онбордингу з API key іншого провайдера
+- `providerAuthAliases` дозволяє варіантам провайдерів повторно використовувати auth
+ env vars, auth profiles, auth на основі config та варіант онбордингу API key іншого провайдера
без жорсткого кодування цього зв’язку в core.
-- `channelEnvVars` — це шлях дешевих метаданих для fallback через shell-env, підказок налаштування
+- `channelEnvVars` — це дешевий шлях метаданих для резервного використання shell-env, підказок setup
та подібних поверхонь каналів, які не повинні запускати runtime плагіна
лише для перевірки назв env.
-- `providerAuthChoices` — це шлях дешевих метаданих для picker варіантів автентифікації,
- визначення `--auth-choice`, мапінгу бажаного провайдера та простої реєстрації
- прапорців CLI для онбордингу до завантаження runtime провайдера. Для метаданих wizard runtime,
- які потребують коду провайдера, див.
- [Хуки runtime провайдера](/uk/plugins/architecture#provider-runtime-hooks).
-- Виняткові види плагінів вибираються через `plugins.slots.*`.
+- `providerAuthChoices` — це дешевий шлях метаданих для picker-ів вибору auth,
+ розв’язання `--auth-choice`, мапінгу preferred provider і простої реєстрації прапорців CLI
+ під час онбордингу до завантаження runtime провайдера. Для метаданих wizard runtime,
+ які потребують коду провайдера, дивіться
+ [Runtime hooks провайдера](/uk/plugins/architecture#provider-runtime-hooks).
+- Виключні типи плагінів вибираються через `plugins.slots.*`.
- `kind: "memory"` вибирається через `plugins.slots.memory`.
- `kind: "context-engine"` вибирається через `plugins.slots.contextEngine`
- (типово: вбудований `legacy`).
+ (типове значення: вбудований `legacy`).
- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо
плагіну вони не потрібні.
-- Якщо ваш плагін залежить від native-модулів, задокументуйте кроки збирання та будь-які
- вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts`
+- Якщо ваш плагін залежить від native modules, задокументуйте кроки збірки та всі
+ вимоги до allowlist менеджера пакунків (наприклад, pnpm `allow-build-scripts`
- `pnpm rebuild `).
-## Пов’язане
+## Пов’язані матеріали
- [Створення плагінів](/uk/plugins/building-plugins) — початок роботи з плагінами
- [Архітектура плагінів](/uk/plugins/architecture) — внутрішня архітектура