diff --git a/docs/uk/plugins/architecture-internals.md b/docs/uk/plugins/architecture-internals.md
index 2a25c7dc9..4f7fae59a 100644
--- a/docs/uk/plugins/architecture-internals.md
+++ b/docs/uk/plugins/architecture-internals.md
@@ -1,100 +1,102 @@
---
read_when:
- - Реалізація runtime hooks постачальника, життєвого циклу каналу або package packs
- - Налагодження порядку завантаження Plugin або стану registry
- - Додавання нової можливості Plugin або Plugin рушія контексту
-summary: 'Внутрішня архітектура Plugin: конвеєр завантаження, registry, runtime hooks, HTTP routes і довідкові таблиці'
+ - Реалізація хуків середовища виконання провайдера, життєвого циклу каналу або пакетних наборів
+ - Налагодження порядку завантаження Plugin або стану реєстру
+ - Додавання нової можливості Plugin або Plugin для механізму контексту
+summary: 'Внутрішня архітектура Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці'
title: Внутрішня архітектура Plugin
x-i18n:
- generated_at: "2026-04-24T18:11:29Z"
+ generated_at: "2026-04-24T18:19:01Z"
model: gpt-5.4
provider: openai
- source_hash: 71dbdc066ed9e37fe5d051a5cd5ebbf5bdb951115612a344cccc21cab60405a9
+ source_hash: 5e2401a211505fbcda0e855572f53af74b6441c931509a2f45a1ac174a48d6ac
source_path: plugins/architecture-internals.md
workflow: 15
---
-Щодо публічної моделі можливостей, форм Plugin і контрактів
-власності/виконання див. [Архітектура Plugin](/uk/plugins/architecture). Ця сторінка —
-це довідник щодо внутрішньої механіки: конвеєр завантаження, registry, runtime hooks,
-Gateway HTTP routes, шляхи імпорту та таблиці схем.
+Модель публічних можливостей, форми Plugin, а також контракти
+володіння/виконання описано в [архітектурі Plugin](/uk/plugins/architecture). Ця сторінка є
+довідником щодо внутрішньої механіки: конвеєра завантаження, реєстру, хуків середовища виконання,
+HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем.
## Конвеєр завантаження
Під час запуску OpenClaw приблизно виконує таке:
-1. виявляє корені кандидатів Plugin
-2. читає маніфести native або сумісних bundle і метадані package
+1. виявляє кандидатні корені Plugin
+2. зчитує маніфести нативних або сумісних збірок і метадані пакунків
3. відхиляє небезпечних кандидатів
4. нормалізує конфігурацію Plugin (`plugins.enabled`, `allow`, `deny`, `entries`,
`slots`, `load.paths`)
-5. визначає, чи увімкнено кожного кандидата
-6. завантажує увімкнені native modules: зібрані bundled modules використовують native loader;
- незібрані native Plugins використовують jiti
-7. викликає native hooks `register(api)` і збирає реєстрації в registry Plugin
-8. відкриває registry для команд/поверхонь runtime
+5. визначає, чи буде ввімкнено кожного кандидата
+6. завантажує ввімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач;
+ незібрані нативні Plugin використовують jiti
+7. викликає нативні хуки `register(api)` і збирає реєстрації в реєстр Plugin
+8. робить реєстр доступним для команд і поверхонь середовища виконання
-`activate` — це застарілий псевдонім для `register` — loader визначає, що з них наявне (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі bundled Plugins використовують `register`; для нових Plugins віддавайте перевагу `register`.
+`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це на тому самому етапі. Усі вбудовані Plugin використовують `register`; для нових Plugin віддавайте перевагу `register`.
-Перевірки безпеки виконуються **до** runtime execution. Кандидати блокуються,
-якщо entry виходить за межі кореня Plugin, шлях є world-writable або
-право власності на шлях виглядає підозрілим для небандлованих Plugins.
+Перевірки безпеки відбуваються **до** виконання середовища виконання. Кандидати блокуються,
+коли точка входу виходить за межі кореня Plugin, шлях є доступним для запису всім, або
+власник шляху виглядає підозріло для невбудованих Plugin.
-### Поведінка manifest-first
+### Поведінка з пріоритетом маніфесту
Маніфест є джерелом істини для control plane. OpenClaw використовує його, щоб:
- ідентифікувати Plugin
-- виявляти оголошені channels/Skills/schema конфігурації або можливості bundle
+- виявляти оголошені канали/Skills/схему конфігурації або можливості збірки
- перевіряти `plugins.entries..config`
- доповнювати мітки/заповнювачі Control UI
- показувати метадані встановлення/каталогу
-- зберігати дешеві дескриптори активації та налаштування без завантаження runtime Plugin
+- зберігати недорогі дескриптори активації та налаштування без завантаження середовища виконання Plugin
-Для native Plugins runtime module є частиною data plane. Вона реєструє
-фактичну поведінку, таку як hooks, tools, commands або потоки provider.
+Для нативних Plugin модуль середовища виконання є частиною data plane. Він реєструє
+фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера.
-Необов’язкові блоки маніфесту `activation` і `setup` залишаються в control plane.
+Необов’язкові блоки маніфесту `activation` і `setup` залишаються на control plane.
Це лише дескриптори метаданих для планування активації та виявлення налаштування;
-вони не замінюють runtime registration, `register(...)` або `setupEntry`.
-Перші живі споживачі активації тепер використовують підказки маніфесту про command, channel і provider,
-щоб звузити завантаження Plugin до ширшої матеріалізації registry:
+вони не замінюють реєстрацію середовища виконання, `register(...)` або `setupEntry`.
+Перші споживачі живої активації тепер використовують підказки з маніфесту щодо команд, каналів і провайдерів,
+щоб звузити завантаження Plugin до ширшої матеріалізації реєстру:
-- завантаження CLI звужується до Plugins, які володіють запитаною primary command
-- налаштування channel/визначення Plugin звужується до Plugins, які володіють запитаним
- id channel
-- явне визначення setup/runtime provider звужується до Plugins, які володіють
- запитаним id provider
+- завантаження CLI звужується до Plugin, які володіють запитаною основною командою
+- налаштування каналу/визначення Plugin звужується до Plugin, які володіють
+ запитаним id каналу
+- явне визначення налаштування/середовища виконання провайдера звужується до Plugin, які володіють
+ запитаним id провайдера
-Планувальник активації надає як API лише для ids для наявних викликачів, так і
-plan API для нової діагностики. Записи plan повідомляють, чому Plugin було вибрано,
-відокремлюючи явні підказки планувальника `activation.*` від резервних варіантів володіння маніфесту,
-таких як `providers`, `channels`, `commandAliases`, `setup.providers`,
-`contracts.tools` і hooks. Це розділення причин є межею сумісності:
+Планувальник активації надає як API лише з id для наявних викликачів, так і
+API плану для нової діагностики. Записи плану повідомляють, чому Plugin було вибрано,
+відокремлюючи явні підказки планувальника `activation.*` від резервного
+володіння з маніфесту, такого як `providers`, `channels`, `commandAliases`, `setup.providers`,
+`contracts.tools` і хуки. Це розділення причин є межею сумісності:
наявні метадані Plugin продовжують працювати, а новий код може виявляти широкі підказки
-або резервну поведінку без зміни семантики завантаження runtime.
+або резервну поведінку без зміни семантики завантаження середовища виконання.
-Виявлення setup тепер віддає перевагу id, що належать дескрипторам, таким як `setup.providers` і
-`setup.cliBackends`, щоб звужувати кандидатів Plugin, перш ніж повертатися до
-`setup-api` для Plugins, яким усе ще потрібні runtime hooks під час setup. Явне
-`setup.requiresRuntime: false` є лише межею для дескриптора; пропущений
-`requiresRuntime` зберігає застарілий резервний варіант `setup-api` для сумісності. Якщо більше
-ніж один виявлений Plugin заявляє однаковий нормалізований id setup provider або CLI
-backend, пошук setup відхиляє неоднозначного власника замість покладання на
-порядок виявлення.
+Виявлення налаштування тепер віддає перевагу id, що належать дескриптору, таким як `setup.providers` і
+`setup.cliBackends`, щоб звузити коло кандидатних Plugin до переходу до
+`setup-api` для Plugin, яким усе ще потрібні хуки середовища виконання на етапі налаштування. Явне
+`setup.requiresRuntime: false` є межею лише на рівні дескриптора; якщо
+`requiresRuntime` опущено, зберігається застарілий резервний перехід до `setup-api` для сумісності. Якщо
+більше ніж один виявлений Plugin заявляє той самий нормалізований id провайдера налаштування або
+CLI backend, пошук налаштування відхиляє неоднозначного власника замість покладатися на
+порядок виявлення. Коли середовище виконання налаштування все ж запускається, діагностика реєстру повідомляє про
+розбіжності між `setup.providers` / `setup.cliBackends` і провайдерами або CLI backend,
+зареєстрованими через setup-api, не блокуючи застарілі Plugin.
-### Що кешує loader
+### Що кешує завантажувач
-OpenClaw зберігає короткі кеші в межах процесу для:
+OpenClaw зберігає короткочасні внутрішньопроцесні кеші для:
- результатів виявлення
-- даних registry маніфестів
-- registry завантажених Plugins
+- даних реєстру маніфестів
+- завантажених реєстрів Plugin
-Ці кеші зменшують пікові витрати під час запуску й повторних викликів команд. Їх безпечно
-сприймати як короткочасні кеші продуктивності, а не як постійне сховище.
+Ці кеші зменшують навантаження під час сплесків запуску та повторного виконання команд. Їх безпечно
+сприймати як короткочасні кеші продуктивності, а не як постійне зберігання.
Примітка щодо продуктивності:
@@ -103,39 +105,38 @@ OpenClaw зберігає короткі кеші в межах процесу
- Налаштовуйте вікна кешу через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і
`OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`.
-## Модель registry
+## Модель реєстру
-Завантажені Plugins не змінюють напряму довільні глобальні об’єкти core. Вони реєструються в
-центральний registry Plugin.
+Завантажені Plugin не змінюють напряму довільні глобальні об’єкти ядра. Вони реєструються в
+центральному реєстрі Plugin.
-Registry відстежує:
+Реєстр відстежує:
- записи Plugin (ідентичність, джерело, походження, статус, діагностика)
-- tools
-- застарілі hooks і типізовані hooks
-- channels
-- providers
+- інструменти
+- застарілі хуки й типізовані хуки
+- канали
+- провайдери
- обробники Gateway RPC
-- HTTP routes
+- HTTP-маршрути
- реєстратори CLI
- фонові сервіси
-- commands, що належать Plugin
+- команди, що належать Plugin
-Функції core далі читають із цього registry замість прямої взаємодії з modules Plugin.
-Це робить завантаження односпрямованим:
+Потім можливості ядра читають із цього реєстру замість прямої взаємодії з модулями Plugin.
+Це зберігає односторонню модель завантаження:
-- module Plugin -> реєстрація в registry
-- runtime core -> споживання registry
+- модуль Plugin -> реєстрація в реєстрі
+- середовище виконання ядра -> споживання реєстру
-Це розділення важливе для супроводу. Воно означає, що більшості поверхонь core потрібна лише
-одна точка інтеграції: «прочитати registry», а не «робити special-case для кожного module Plugin».
+Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра
+потрібна лише одна точка інтеграції: «читати реєстр», а не «робити спеціальний випадок для кожного модуля Plugin».
-## Зворотні виклики прив’язки розмов
+## Зворотні виклики прив’язки розмови
-Plugins, які прив’язують розмову, можуть реагувати, коли підтвердження вирішено.
+Plugin, які прив’язують розмову, можуть реагувати, коли погодження вирішено.
-Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, як запит прив’язки
-підтверджено або відхилено:
+Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, як запит на прив’язку схвалено або відхилено:
```ts
export default {
@@ -143,126 +144,126 @@ export default {
register(api) {
api.onConversationBindingResolved(async (event) => {
if (event.status === "approved") {
- // Тепер для цього Plugin + розмови існує прив’язка.
+ // A binding now exists for this plugin + conversation.
console.log(event.binding?.conversationId);
return;
}
- // Запит було відхилено; очистіть будь-який локальний стан очікування.
+ // The request was denied; clear any local pending state.
console.log(event.request.conversation.conversationId);
});
},
};
```
-Поля payload зворотного виклику:
+Поля корисного навантаження зворотного виклику:
- `status`: `"approved"` або `"denied"`
- `decision`: `"allow-once"`, `"allow-always"` або `"deny"`
-- `binding`: вирішена прив’язка для підтверджених запитів
-- `request`: підсумок початкового запиту, підказка від’єднання, id відправника та
+- `binding`: визначена прив’язка для схвалених запитів
+- `request`: початкове резюме запиту, підказка про від’єднання, id відправника та
метадані розмови
-Цей зворотний виклик призначений лише для сповіщення. Він не змінює те, кому дозволено прив’язувати
-розмову, і виконується після завершення обробки підтвердження в core.
+Цей зворотний виклик є лише сповіщенням. Він не змінює, кому дозволено прив’язувати
+розмову, і запускається після завершення обробки погодження ядром.
-## Runtime hooks provider
+## Хуки середовища виконання провайдера
-Plugins provider мають три шари:
+Plugin провайдера мають три рівні:
-- **Метадані маніфесту** для дешевого пошуку до runtime: `providerAuthEnvVars`,
+- **Метадані маніфесту** для недорогого пошуку до середовища виконання: `providerAuthEnvVars`,
`providerAuthAliases`, `providerAuthChoices` і `channelEnvVars`.
-- **Hooks на етапі конфігурації**: `catalog` (застаріле `discovery`) плюс
+- **Хуки часу конфігурації**: `catalog` (застарілий `discovery`) плюс
`applyConfigDefaults`.
-- **Runtime hooks**: понад 40 необов’язкових hooks, що охоплюють auth, визначення моделі,
- обгортання stream, рівні thinking, політику replay і endpoints використання. Див.
- повний список у розділі [Порядок hooks і використання](#hook-order-and-usage).
+- **Хуки середовища виконання**: понад 40 необов’язкових хуків для auth, визначення моделей,
+ обгортання потоків, рівнів thinking, політики повторного відтворення та
+ кінцевих точок usage. Повний список наведено в розділі [Порядок і використання хуків](#hook-order-and-usage).
-OpenClaw і далі володіє загальним циклом агента, failover, обробкою transcript і
-політикою tool. Ці hooks є поверхнею розширення для специфічної для provider
-поведінки без потреби в цілому власному inference transport.
+OpenClaw, як і раніше, відповідає за загальний цикл агента, failover, обробку транскриптів і
+політику інструментів. Ці хуки є поверхнею розширення для специфічної поведінки провайдера
+без потреби в повністю власному транспорті інференсу.
-Використовуйте `providerAuthEnvVars` маніфесту, коли provider має облікові дані на основі env,
-які мають бути видимі загальним шляхам auth/status/model-picker без завантаження runtime Plugin.
-Використовуйте `providerAuthAliases` маніфесту, коли один id provider має повторно використовувати
-env vars, профілі auth, auth на основі конфігурації та вибір API-ключа для onboarding
-іншого id provider. Використовуйте `providerAuthChoices` маніфесту, коли поверхні onboarding/auth-choice
-CLI мають знати id вибору provider, мітки груп і просту однопрапорцеву auth wiring
-без завантаження runtime provider. Зберігайте `envVars` runtime provider для
-підказок, видимих оператору, таких як мітки onboarding або змінні налаштування
+Використовуйте маніфест `providerAuthEnvVars`, коли провайдер має облікові дані на основі env,
+які загальні шляхи auth/status/model-picker повинні бачити без завантаження середовища виконання Plugin.
+Використовуйте маніфест `providerAuthAliases`, коли один id провайдера має повторно використовувати env vars,
+профілі auth, auth на основі конфігурації та варіант онбордингу API-ключа іншого id провайдера.
+Використовуйте маніфест `providerAuthChoices`, коли поверхні CLI для онбордингу/вибору auth
+мають знати id варіанта провайдера, мітки груп і просту однопрапорцеву схему auth без
+завантаження середовища виконання провайдера. Залишайте `envVars` у середовищі виконання провайдера для
+підказок, орієнтованих на операторів, таких як мітки онбордингу або змінні налаштування
OAuth client-id/client-secret.
-Використовуйте `channelEnvVars` маніфесту, коли channel має auth або setup на основі env, які
-мають бути видимі загальному резервному shell-env, перевіркам config/status або підказкам setup
-без завантаження runtime channel.
+Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування на основі env, які
+загальний резервний механізм shell-env, перевірки config/status або запити налаштування повинні бачити
+без завантаження середовища виконання каналу.
-### Порядок hooks і використання
+### Порядок і використання хуків
-Для Plugins model/provider OpenClaw викликає hooks приблизно в такому порядку.
-Стовпець «Коли використовувати» — це короткий орієнтир для вибору.
+Для Plugin моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку.
+Стовпчик «Коли використовувати» — це короткий довідник для вибору.
-| # | Hook | Що робить | Коли використовувати |
+| # | Хук | Що він робить | Коли використовувати |
| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1 | `catalog` | Публікує конфігурацію provider у `models.providers` під час генерації `models.json` | Provider володіє каталогом або типовими значеннями base URL |
-| 2 | `applyConfigDefaults` | Застосовує типові глобальні значення конфігурації provider під час матеріалізації конфігурації | Типові значення залежать від режиму auth, env або семантики сімейства моделей provider |
-| -- | _(built-in model lookup)_ | OpenClaw спочатку пробує звичайний шлях registry/catalog | _(не є hook Plugin)_ |
-| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Provider володіє очищенням псевдонімів перед визначенням канонічної моделі |
-| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства provider перед загальним збиранням моделі | Provider володіє очищенням транспорту для власних id provider у межах того самого сімейства транспорту |
-| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням runtime/provider | Provider потребує очищення конфігурації, яке має жити разом із Plugin; bundled helper-и сімейства Google також резервно підтримують записи конфігурації Google |
-| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування native streaming-usage до provider-ів у конфігурації | Provider потребує виправлень метаданих native streaming usage, що залежать від endpoint |
-| 7 | `resolveConfigApiKey` | Визначає auth через env-marker для provider-ів у конфігурації перед завантаженням runtime auth | Provider має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований resolver AWS env-marker |
-| 8 | `resolveSyntheticAuth` | Показує локальну/self-hosted або auth на основі конфігурації без збереження plaintext | Provider може працювати із synthetic/local маркером облікових даних |
-| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі auth, що належать provider; типове `persistence` — `runtime-only` для creds, якими володіє CLI/app | Provider повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті |
-| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет synthetic placeholders збережених профілів відносно auth на основі env/config | Provider зберігає synthetic placeholder-профілі, які не повинні мати вищий пріоритет |
-| 11 | `resolveDynamicModel` | Синхронний резервний варіант для model id provider, яких ще немає в локальному registry | Provider приймає довільні upstream model id |
-| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Provider потребує мережевих метаданих перед визначенням невідомих id |
-| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як embedded runner використовує визначену модель | Provider потребує переписувань транспорту, але все ще використовує транспорт core |
-| 14 | `contributeResolvedModelCompat` | Додає прапорці compat для vendor-моделей за іншим сумісним транспортом | Provider розпізнає власні моделі на proxy-транспортах, не перебираючи на себе provider |
-| 15 | `capabilities` | Метадані transcript/tooling, що належать provider і використовуються спільною логікою core | Provider потребує особливостей transcript/provider family |
-| 16 | `normalizeToolSchemas` | Нормалізує схеми tool перед тим, як їх побачить embedded runner | Provider потребує очищення схем для сімейства транспорту |
-| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить provider, після нормалізації | Provider хоче попередження про ключові слова без навчання core правилам, специфічним для provider |
-| 18 | `resolveReasoningOutputMode` | Вибирає native чи tagged-контракт reasoning-output | Provider потребує tagged reasoning/final output замість native полів |
-| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів stream | Provider потребує типових параметрів запиту або очищення параметрів для конкретного provider |
-| 20 | `createStreamFn` | Повністю замінює звичайний шлях stream власним транспортом | Provider потребує власного wire protocol, а не лише обгортки |
-| 21 | `wrapStreamFn` | Обгортка stream після застосування загальних обгорток | Provider потребує обгорток сумісності заголовків/тіла запиту/моделі без власного транспорту |
-| 22 | `resolveTransportTurnState` | Додає native заголовки або метадані транспорту для кожного turn | Provider хоче, щоб загальні транспорти надсилали native ідентичність turn для provider |
-| 23 | `resolveWebSocketSessionPolicy` | Додає native заголовки WebSocket або політику cool-down для сесії | Provider хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або резервну політику |
-| 24 | `formatApiKey` | Форматувач auth-profile: збережений профіль стає runtime-рядком `apiKey` | Provider зберігає додаткові метадані auth і потребує власної форми runtime token |
-| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для власних endpoint-ів оновлення або політики помилок оновлення | Provider не відповідає спільним механізмам оновлення `pi-ai` |
-| 26 | `buildAuthDoctorHint` | Підказка для виправлення, що додається, коли оновлення OAuth завершується помилкою | Provider потребує власних рекомендацій щодо виправлення auth після помилки оновлення |
-| 27 | `matchesContextOverflowError` | Засіб зіставлення переповнення context window, що належить provider | Provider має сирі помилки переповнення, які загальні евристики не виявляють |
-| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить provider | Provider може зіставляти сирі помилки API/транспорту з rate-limit/перевантаженням тощо |
-| 29 | `isCacheTtlEligible` | Політика prompt-cache для provider-ів proxy/backhaul | Provider потребує керування TTL кешу, специфічного для proxy |
-| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення при відсутній auth | Provider потребує підказки відновлення при відсутній auth, специфічної для provider |
-| 31 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей плюс необов’язкова підказка помилки для користувача | Provider потребує приховувати застарілі upstream-рядки або замінювати їх підказкою vendor |
-| 32 | `augmentModelCatalog` | Synthetic/final рядки каталогу, додані після виявлення | Provider потребує synthetic рядків прямої сумісності в `models list` і вибирачах |
-| 33 | `resolveThinkingProfile` | Набір рівнів `/think`, мітки відображення та типове значення для конкретної моделі | Provider відкриває власну шкалу thinking або бінарну мітку для вибраних моделей |
-| 34 | `isBinaryThinking` | Hook сумісності для вмикання/вимикання reasoning | Provider підтримує лише бінарне thinking увімк./вимк. |
-| 35 | `supportsXHighThinking` | Hook сумісності для підтримки reasoning `xhigh` | Provider хоче `xhigh` лише для підмножини моделей |
-| 36 | `resolveDefaultThinkingLevel` | Hook сумісності для типового рівня `/think` | Provider володіє типовою політикою `/think` для сімейства моделей |
-| 37 | `isModernModelRef` | Засіб зіставлення modern-model для фільтрів live profile і вибору smoke | Provider володіє зіставленням бажаних моделей для live/smoke |
-| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime token/key безпосередньо перед inference | Provider потребує обміну токена або короткоживучих облікових даних запиту |
-| 39 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` і пов’язаних поверхонь статусу | Provider потребує власного розбору usage/quota token або інших облікових даних usage |
-| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки usage/quota, специфічні для provider, після визначення auth | Provider потребує власного endpoint usage або парсера payload |
-| 41 | `createEmbeddingProvider` | Створює embedding adapter, що належить provider, для пам’яті/пошуку | Поведінка embedding для пам’яті має належати Plugin provider |
-| 42 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою transcript для provider | Provider потребує власної політики transcript (наприклад, видалення thinking-block) |
-| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення transcript | Provider потребує власних переписувань replay, специфічних для provider, понад спільні helper-и Compaction |
-| 44 | `validateReplayTurns` | Фінальна перевірка або зміна форми turn replay перед embedded runner | Транспорт provider потребує суворішої перевірки turn після загального очищення |
-| 45 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать provider | Provider потребує телеметрії або стану, що належить provider, коли модель стає активною |
+| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями `base URL` |
+| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму auth, env або семантики сімейства моделей провайдера |
+| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(це не хук Plugin)_ |
+| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми `model-id` перед пошуком | Провайдер володіє очищенням псевдонімів до канонічного визначення моделі |
+| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера до загального складання моделі | Провайдер володіє очищенням транспорту для нестандартних id провайдерів у межах того самого сімейства транспорту |
+| 5 | `normalizeConfig` | Нормалізує `models.providers.` до визначення провайдера/середовища виконання | Провайдеру потрібне очищення конфігурації, яке має жити разом із Plugin; вбудовані допоміжні засоби сімейства Google також страхують підтримувані записи конфігурації Google |
+| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні перезаписи native streaming-usage до провайдерів конфігурації | Провайдеру потрібні виправлення метаданих native streaming usage, що залежать від кінцевої точки |
+| 7 | `resolveConfigApiKey` | Визначає auth env-marker для провайдерів конфігурації до завантаження auth середовища виконання | Провайдер має власне визначення API-ключа env-marker; `amazon-bedrock` також має тут вбудований AWS env-marker resolver |
+| 8 | `resolveSyntheticAuth` | Виводить local/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Провайдер може працювати із synthetic/local маркером облікових даних |
+| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі auth, що належать провайдеру; типове `persistence` — `runtime-only` для облікових даних CLI/застосунку | Провайдер повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті |
+| 10 | `shouldDeferSyntheticProfileAuth` | Опускає збережені synthetic-заповнювачі профілів нижче за auth на основі env/config | Провайдер зберігає synthetic-профілі-заповнювачі, які не повинні мати вищий пріоритет |
+| 11 | `resolveDynamicModel` | Синхронний резерв для id моделей провайдера, яких ще немає в локальному реєстрі | Провайдер приймає довільні id моделей верхнього рівня |
+| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані до визначення невідомих id |
+| 13 | `normalizeResolvedModel` | Остаточний перезапис до того, як вбудований runner використає визначену модель | Провайдеру потрібні перезаписи транспорту, але він усе ще використовує транспорт ядра |
+| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для vendor-моделей за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспортах, не перебираючи на себе провайдера |
+| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру й використовуються спільною логікою ядра | Провайдеру потрібні особливості транскрипту/сімейства провайдера |
+| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований 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` | Форматувач профілю auth: збережений профіль стає рядком `apiKey` у середовищі виконання | Провайдер зберігає додаткові метадані auth і потребує власної форми токена в середовищі виконання |
+| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для нестандартних кінцевих точок оновлення або політики збоїв оновлення | Провайдер не вкладається в спільні засоби оновлення `pi-ai` |
+| 26 | `buildAuthDoctorHint` | Підказка з виправлення, що додається, коли оновлення OAuth завершується помилкою | Провайдеру потрібні власні вказівки з відновлення auth після помилки оновлення |
+| 27 | `matchesContextOverflowError` | Засіб зіставлення переповнення вікна контексту, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики пропустили б |
+| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо |
+| 29 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для проксі |
+| 30 | `buildMissingAuthMessage` | Замінник загального повідомлення відновлення для відсутнього auth | Провайдеру потрібна власна підказка з відновлення для відсутнього auth |
+| 31 | `suppressBuiltInModel` | Пригнічення застарілих моделей верхнього рівня плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі рядки верхнього рівня або замінити їх підказкою про vendor |
+| 32 | `augmentModelCatalog` | Synthetic/фінальні рядки каталогу, додані після виявлення | Провайдеру потрібні synthetic-ряди для прямої сумісності в `models list` і засобах вибору |
+| 33 | `resolveThinkingProfile` | Набір рівнів `/think`, мітки відображення та типове значення для конкретної моделі | Провайдер надає власну шкалу thinking або бінарну мітку для вибраних моделей |
+| 34 | `isBinaryThinking` | Хук сумісності для перемикача reasoning увімкнено/вимкнено | Провайдер підтримує лише бінарний режим thinking: увімкнено/вимкнено |
+| 35 | `supportsXHighThinking` | Хук сумісності для підтримки reasoning `xhigh` | Провайдер хоче `xhigh` лише для підмножини моделей |
+| 36 | `resolveDefaultThinkingLevel` | Хук сумісності для типового рівня `/think` | Провайдер володіє типовою політикою `/think` для сімейства моделей |
+| 37 | `isModernModelRef` | Засіб зіставлення modern-model для фільтрів live profile і вибору smoke | Провайдер володіє зіставленням preferred-model для live/smoke |
+| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед інференсом | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту |
+| 39 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` та пов’язаних поверхонь статусу | Провайдеру потрібен власний розбір токена usage/quota або інші облікові дані usage |
+| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки usage/quota, специфічні для провайдера, після визначення auth | Провайдеру потрібна власна кінцева точка usage або парсер корисного навантаження |
+| 41 | `createEmbeddingProvider` | Створює embedding-адаптер, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті належить Plugin провайдера |
+| 42 | `buildReplayPolicy` | Повертає політику повторного відтворення, що керує обробкою транскрипту для провайдера | Провайдеру потрібна власна політика транскрипту (наприклад, видалення блоків thinking) |
+| 43 | `sanitizeReplayHistory` | Перезаписує історію повторного відтворення після загального очищення транскрипту | Провайдеру потрібні специфічні для нього перезаписи повторного відтворення понад спільні допоміжні засоби Compaction |
+| 44 | `validateReplayTurns` | Остаточна перевірка або перебудова ходів повторного відтворення перед вбудованим runner | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санітизації |
+| 45 | `onModelSelected` | Виконує побічні ефекти після вибору, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною |
`normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють
-підібраний Plugin provider, а потім переходять до інших Plugin provider, які підтримують hooks,
+відповідний Plugin провайдера, а потім переходять до інших Plugin провайдерів, що підтримують хуки,
доки один із них фактично не змінить id моделі або transport/config. Це дозволяє
-shim-ам alias/compat provider працювати без потреби, щоб викликач знав, який bundled Plugin
-володіє цим переписуванням. Якщо жоден hook provider не переписує підтримуваний запис конфігурації
-сімейства Google, bundled normalizer конфігурації Google все одно застосовує
-це очищення сумісності.
+shim-шарам alias/compat провайдерів працювати без вимоги, щоб викликач знав, який
+саме вбудований Plugin володіє перезаписом. Якщо жоден хук провайдера не переписує
+підтримуваний запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google
+усе одно застосовує це очищення сумісності.
-Якщо provider потребує повністю власного wire protocol або власного виконавця запитів,
-це вже інший клас розширення. Ці hooks призначені для поведінки provider, яка
-все ще працює на звичайному циклі inference OpenClaw.
+Якщо провайдеру потрібен повністю власний wire protocol або власний виконавець запитів,
+це вже інший клас розширення. Ці хуки призначені для поведінки провайдера,
+яка все ще працює в межах звичайного циклу інференсу OpenClaw.
-### Приклад provider
+### Приклад провайдера
```ts
api.registerProvider({
@@ -318,44 +319,45 @@ api.registerProvider({
### Вбудовані приклади
-Bundled Plugins provider комбінують наведені вище hooks відповідно до потреб кожного постачальника щодо catalog,
-auth, thinking, replay і usage. Авторитетний набір hooks міститься в кожному
-Plugin у `extensions/`; ця сторінка ілюструє форми, а не дзеркально відтворює список.
+Вбудовані Plugin провайдерів поєднують наведені вище хуки, щоб відповідати потребам
+кожного постачальника щодо каталогу, auth, thinking, повторного відтворення та usage. Авторитетний
+набір хуків міститься в кожному Plugin у `extensions/`; ця сторінка ілюструє форми,
+а не дублює список.
-
+
OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` разом із
- `resolveDynamicModel` / `prepareDynamicModel`, щоб показувати upstream
- model id раніше за статичний catalog OpenClaw.
+ `resolveDynamicModel` / `prepareDynamicModel`, щоб показувати id моделей верхнього рівня
+ раніше за статичний каталог OpenClaw.
-
+
GitHub Copilot, Gemini CLI, ChatGPT Codex, MiniMax, Xiaomi, z.ai поєднують
`prepareRuntimeAuth` або `formatApiKey` з `resolveUsageAuth` +
`fetchUsageSnapshot`, щоб керувати обміном токенів та інтеграцією `/usage`.
-
+
Спільні іменовані сімейства (`google-gemini`, `passthrough-gemini`,
- `anthropic-by-model`, `hybrid-anthropic-openai`) дозволяють provider-ам підключатися до
- політики transcript через `buildReplayPolicy`, замість того щоб кожен Plugin
- повторно реалізовував очищення.
+ `anthropic-by-model`, `hybrid-anthropic-openai`) дозволяють провайдерам
+ підключати політику транскрипту через `buildReplayPolicy` замість того, щоб кожен Plugin
+ наново реалізовував очищення.
-
+
`byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`,
`qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і
- `volcengine` реєструють лише `catalog` і працюють на спільному циклі inference.
+ `volcengine` реєструють лише `catalog` і працюють на спільному циклі інференсу.
-
- Beta headers, `/fast` / `serviceTier` і `context1m` розміщені всередині
- публічного seam `api.ts` / `contract-api.ts` Plugin Anthropic
+
+ Beta-заголовки, `/fast` / `serviceTier` і `context1m` знаходяться в
+ публічному шві `api.ts` / `contract-api.ts` Plugin Anthropic
(`wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
`resolveAnthropicFastMode`, `resolveAnthropicServiceTier`), а не в
загальному SDK.
-## Runtime helpers
+## Допоміжні засоби середовища виконання
-Plugins можуть отримувати доступ до вибраних helper-ів core через `api.runtime`. Для TTS:
+Plugin можуть отримувати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS:
```ts
const clip = await api.runtime.tts.textToSpeech({
@@ -376,14 +378,14 @@ const voices = await api.runtime.tts.listVoices({
Примітки:
-- `textToSpeech` повертає звичайний payload виводу TTS core для поверхонь файлів/голосових нотаток.
-- Використовує конфігурацію core `messages.tts` і вибір provider.
-- Повертає PCM audio buffer + sample rate. Plugins мають виконувати ресемплінг/кодування для provider-ів.
-- `listVoices` є необов’язковим для кожного provider. Використовуйте його для голосових вибирачів або потоків setup, що належать постачальнику.
-- Списки голосів можуть містити багатші метадані, такі як locale, gender і personality tags для вибирачів, обізнаних про provider.
-- OpenAI і ElevenLabs сьогодні підтримують telephony. Microsoft — ні.
+- `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових нотаток.
+- Використовує конфігурацію ядра `messages.tts` і вибір провайдера.
+- Повертає буфер PCM-аудіо + частоту дискретизації. Plugin мають виконувати ресемплінг/кодування для провайдерів.
+- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для voice picker, що належать постачальнику, або потоків налаштування.
+- Списки голосів можуть містити ширші метадані, такі як locale, gender і personality tags для picker-ів, обізнаних про провайдера.
+- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні.
-Plugins також можуть реєструвати speech provider-ів через `api.registerSpeechProvider(...)`.
+Plugin також можуть реєструвати speech-провайдерів через `api.registerSpeechProvider(...)`.
```ts
api.registerSpeechProvider({
@@ -403,15 +405,15 @@ api.registerSpeechProvider({
Примітки:
-- Зберігайте політику TTS, резервну поведінку й доставку відповідей у core.
-- Використовуйте speech provider-ів для поведінки синтезу, що належить постачальнику.
-- Застарілий ввід Microsoft `edge` нормалізується до id provider `microsoft`.
+- Зберігайте політику TTS, fallback і доставку відповідей у ядрі.
+- Використовуйте speech-провайдерів для поведінки синтезу, що належить постачальнику.
+- Застарілий вхід Microsoft `edge` нормалізується до id провайдера `microsoft`.
- Бажана модель володіння є орієнтованою на компанію: один Plugin постачальника може володіти
- text, speech, image і майбутніми media provider-ами в міру того, як OpenClaw додає ці
+ текстовими, мовленнєвими, графічними та майбутніми media-провайдерами, коли OpenClaw додаватиме ці
контракти можливостей.
-Для розуміння image/audio/video Plugins реєструють один типізований
-provider media understanding замість узагальненого набору ключ/значення:
+Для розуміння зображень/аудіо/відео Plugin реєструють один типізований
+media-understanding provider замість загального набору ключ/значення:
```ts
api.registerMediaUnderstandingProvider({
@@ -425,16 +427,16 @@ api.registerMediaUnderstandingProvider({
Примітки:
-- Зберігайте orchestration, резервну поведінку, конфігурацію й wiring channel у core.
-- Зберігайте поведінку постачальника в Plugin provider.
+- Зберігайте оркестрацію, fallback, конфігурацію та підключення каналу в ядрі.
+- Зберігайте поведінку постачальника в Plugin провайдера.
- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові
- поля результату, нові необов’язкові можливості.
+ поля результатів, нові необов’язкові можливості.
- Генерація відео вже дотримується того самого шаблону:
- - core володіє контрактом можливості й runtime helper-ом
- - Plugins постачальників реєструють `api.registerVideoGenerationProvider(...)`
- - Plugins функцій/channel споживають `api.runtime.videoGeneration.*`
+ - ядро володіє контрактом можливості та допоміжним засобом середовища виконання
+ - Plugin постачальників реєструють `api.registerVideoGenerationProvider(...)`
+ - Plugin можливостей/каналів споживають `api.runtime.videoGeneration.*`
-Для runtime helper-ів media understanding Plugins можуть викликати:
+Для допоміжних засобів середовища виконання media-understanding Plugin можуть викликати:
```ts
const image = await api.runtime.mediaUnderstanding.describeImageFile({
@@ -449,27 +451,27 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({
});
```
-Для транскрибування audio Plugins можуть використовувати або runtime media understanding,
+Для транскрибування аудіо Plugin можуть використовувати або середовище виконання media-understanding,
або старіший псевдонім STT:
```ts
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
filePath: "/tmp/inbound-audio.ogg",
cfg: api.config,
- // Необов’язково, коли MIME неможливо надійно визначити:
+ // Optional when MIME cannot be inferred reliably:
mime: "audio/ogg",
});
```
Примітки:
-- `api.runtime.mediaUnderstanding.*` — це бажана спільна surface для
- розуміння image/audio/video.
-- Використовує конфігурацію audio для media understanding у core (`tools.media.audio`) і резервний порядок provider-ів.
-- Повертає `{ text: undefined }`, якщо не створено жодного результату транскрибування (наприклад, вхід пропущено/не підтримується).
+- `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для
+ розуміння зображень/аудіо/відео.
+- Використовує конфігурацію аудіо media-understanding ядра (`tools.media.audio`) і порядок fallback провайдерів.
+- Повертає `{ text: undefined }`, коли вихід транскрибування не створюється (наприклад, для пропущеного/непідтримуваного вводу).
- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності.
-Plugins також можуть запускати фонові прогони subagent через `api.runtime.subagent`:
+Plugin також можуть запускати фонові виконання subagent через `api.runtime.subagent`:
```ts
const result = await api.runtime.subagent.run({
@@ -485,12 +487,12 @@ const result = await api.runtime.subagent.run({
- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії.
- OpenClaw враховує ці поля перевизначення лише для довірених викликачів.
-- Для резервних прогонів, що належать Plugin, оператори мають явно увімкнути `plugins.entries..subagent.allowModelOverride: true`.
-- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені Plugins конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль.
-- Прогони subagent для недовірених Plugins усе ще працюють, але запити на перевизначення відхиляються, а не тихо переходять до резервної поведінки.
+- Для запусків fallback, що належать Plugin, оператори мають явно ввімкнути `plugins.entries..subagent.allowModelOverride: true`.
+- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені Plugin конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі.
+- Запуски subagent від недовірених Plugin теж працюють, але запити на перевизначення відхиляються замість тихого fallback.
-Для web search Plugins можуть використовувати спільний runtime helper замість
-прямого доступу до wiring tool агента:
+Для вебпошуку Plugin можуть використовувати спільний допоміжний засіб середовища виконання
+замість звернення до підключення інструмента агента:
```ts
const providers = api.runtime.webSearch.listProviders({
@@ -506,14 +508,14 @@ const result = await api.runtime.webSearch.search({
});
```
-Plugins також можуть реєструвати provider-ів web search через
+Plugin також можуть реєструвати провайдерів вебпошуку через
`api.registerWebSearchProvider(...)`.
Примітки:
-- Зберігайте вибір provider, визначення облікових даних і спільну семантику запитів у core.
-- Використовуйте provider-ів web search для транспортів пошуку, специфічних для постачальника.
-- `api.runtime.webSearch.*` — це бажана спільна surface для Plugins функцій/channel, яким потрібна поведінка пошуку без залежності від обгортки tool агента.
+- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запиту в ядрі.
+- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для постачальника.
+- `api.runtime.webSearch.*` — це бажана спільна поверхня для Plugin можливостей/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента.
### `api.runtime.imageGeneration`
@@ -528,12 +530,12 @@ const providers = api.runtime.imageGeneration.listProviders({
});
```
-- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка provider-ів генерації зображень.
-- `listProviders(...)`: показує доступних provider-ів генерації зображень і їхні можливості.
+- `generate(...)`: згенерувати зображення за допомогою налаштованого ланцюга провайдерів генерації зображень.
+- `listProviders(...)`: перелічити доступних провайдерів генерації зображень і їхні можливості.
-## Gateway HTTP routes
+## HTTP-маршрути Gateway
-Plugins можуть відкривати HTTP endpoints через `api.registerHttpRoute(...)`.
+Plugin можуть відкривати HTTP-кінцеві точки за допомогою `api.registerHttpRoute(...)`.
```ts
api.registerHttpRoute({
@@ -548,202 +550,204 @@ api.registerHttpRoute({
});
```
-Поля route:
+Поля маршруту:
-- `path`: шлях route під HTTP server Gateway.
-- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайну auth Gateway, або `"plugin"` для auth/webhook verification під керуванням Plugin.
-- `match`: необов’язково. `"exact"` (типово) або `"prefix"`.
-- `replaceExisting`: необов’язково. Дозволяє тому самому Plugin замінити власну наявну реєстрацію route.
-- `handler`: повертає `true`, якщо route обробив запит.
+- `path`: шлях маршруту в HTTP-сервері gateway.
+- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайний auth Gateway, або `"plugin"` для auth/webhook verification, якими керує Plugin.
+- `match`: необов’язкове поле. `"exact"` (типово) або `"prefix"`.
+- `replaceExisting`: необов’язкове поле. Дозволяє тому самому Plugin замінити власну наявну реєстрацію маршруту.
+- `handler`: повертайте `true`, якщо маршрут обробив запит.
Примітки:
-- `api.registerHttpHandler(...)` вилучено, і це спричинить помилку завантаження Plugin. Натомість використовуйте `api.registerHttpRoute(...)`.
-- Routes Plugin мають явно оголошувати `auth`.
-- Конфлікти точного `path + match` відхиляються, якщо не задано `replaceExisting: true`, і один Plugin не може замінити route іншого Plugin.
-- Перекривні routes з різними рівнями `auth` відхиляються. Тримайте ланцюжки переходу `exact`/`prefix` лише в межах одного рівня auth.
-- Routes `auth: "plugin"` **не** отримують автоматично runtime scopes оператора. Вони призначені для webhook-ів/signature verification під керуванням Plugin, а не для привілейованих helper-викликів Gateway.
-- Routes `auth: "gateway"` працюють у runtime scope запиту Gateway, але цей scope навмисно консервативний:
- - bearer auth на спільному секреті (`gateway.auth.mode = "token"` / `"password"`) утримує runtime scopes route Plugin на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes`
- - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` у приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній
- - якщо `x-openclaw-scopes` відсутній у таких запитах route Plugin з ідентичністю, runtime scope резервно переходить до `operator.write`
-- Практичне правило: не припускайте, що route Plugin з auth gateway є неявною admin surface. Якщо вашому route потрібна поведінка лише для admin, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`.
+- `api.registerHttpHandler(...)` вилучено, і він спричинить помилку завантаження Plugin. Замість нього використовуйте `api.registerHttpRoute(...)`.
+- Маршрути Plugin мають явно оголошувати `auth`.
+- Конфлікти точних `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один Plugin не може замінити маршрут іншого Plugin.
+- Перекривні маршрути з різними рівнями `auth` відхиляються. Залишайте ланцюги fallthrough для `exact`/`prefix` лише на одному рівні `auth`.
+- Маршрути `auth: "plugin"` **не** отримують автоматично operator runtime scopes. Вони призначені для Webhook, якими керує Plugin, і перевірки підписів, а не для привілейованих допоміжних викликів Gateway.
+- Маршрути `auth: "gateway"` виконуються в межах runtime scope запиту Gateway, але цей scope навмисно консервативний:
+ - bearer auth на спільному секреті (`gateway.auth.mode = "token"` / `"password"`) утримує plugin-route runtime scopes на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes`
+ - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній
+ - якщо `x-openclaw-scopes` відсутній у таких plugin-route запитах з ідентичністю, runtime scope повертається до `operator.write`
+- Практичне правило: не припускайте, що маршрут Plugin з gateway auth є неявною поверхнею адміністратора. Якщо ваш маршрут потребує поведінки лише для адміністратора, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`.
-## Шляхи імпорту SDK Plugin
+## Шляхи імпорту Plugin SDK
-Використовуйте вузькі підшляхи SDK замість монолітного root
-barrel `openclaw/plugin-sdk` під час створення нових Plugins. Підшляхи core:
+Під час написання нових Plugin використовуйте вузькі підшляхи SDK замість монолітного
+кореневого barrel `openclaw/plugin-sdk`. Основні підшляхи:
-| Підшлях | Призначення |
-| ---------------------------------- | -------------------------------------------------- |
-| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin |
-| `openclaw/plugin-sdk/channel-core` | Helper-и входу/збирання channel |
-| `openclaw/plugin-sdk/core` | Загальні спільні helper-и та umbrella contract |
-| `openclaw/plugin-sdk/config-schema` | Zod schema кореневого `openclaw.json` (`OpenClawSchema`) |
+| Підшлях | Призначення |
+| ---------------------------------- | --------------------------------------------------- |
+| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin |
+| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/побудови каналу |
+| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella-контракт |
+| `openclaw/plugin-sdk/config-schema` | Коренева схема Zod для `openclaw.json` (`OpenClawSchema`) |
-Plugins channel обирають із сімейства вузьких seam-ів — `channel-setup`,
+Plugin каналів вибирають із сімейства вузьких швів — `channel-setup`,
`setup-runtime`, `setup-adapter-runtime`, `setup-tools`, `channel-pairing`,
`channel-contract`, `channel-feedback`, `channel-inbound`, `channel-lifecycle`,
`channel-reply-pipeline`, `command-auth`, `secret-input`, `webhook-ingress`,
-`channel-targets` і `channel-actions`. Поведінку підтвердження слід зводити
-до одного контракту `approvalCapability`, а не змішувати її між не пов’язаними
-полями Plugin. Див. [Plugins channel](/uk/plugins/sdk-channel-plugins).
+`channel-targets` і `channel-actions`. Поведінку погодження слід зводити
+до одного контракту `approvalCapability`, а не змішувати між непов’язаними
+полями Plugin. Див. [Plugin каналів](/uk/plugins/sdk-channel-plugins).
-Runtime і helper-и конфігурації розміщуються у відповідних підшляхах
-`*-runtime` (`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`,
+Допоміжні засоби середовища виконання й конфігурації знаходяться у відповідних підшляхах
+`*-runtime`
+(`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`,
`lazy-runtime`, `directory-runtime`, `text-runtime`, `runtime-store` тощо).
`openclaw/plugin-sdk/channel-runtime` є застарілим — це shim сумісності для
-старіших Plugins. Новий код має імпортувати натомість вужчі загальні примітиви.
+старіших Plugin. Новий код має імпортувати натомість вужчі загальні примітиви.
-Точки входу, внутрішні для репозиторію (для кореня package кожного bundled Plugin):
+Внутрішні для репозиторію точки входу (для кореня пакунка кожного вбудованого Plugin):
-- `index.js` — точка входу bundled Plugin
-- `api.js` — barrel helper-ів/типів
-- `runtime-api.js` — barrel лише для runtime
-- `setup-entry.js` — точка входу setup Plugin
+- `index.js` — точка входу вбудованого Plugin
+- `api.js` — barrel допоміжних засобів/типів
+- `runtime-api.js` — barrel лише для середовища виконання
+- `setup-entry.js` — точка входу Plugin налаштування
-Зовнішні Plugins повинні імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи
-не імпортуйте `src/*` іншого package Plugin із core або з іншого Plugin.
-Точки входу, завантажені через facade, віддають перевагу активному знімку конфігурації runtime, якщо такий
-існує, а потім резервно використовують визначений файл конфігурації на диску.
+Зовнішні Plugin мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи
+не імпортуйте `src/*` іншого пакунка Plugin із ядра або з іншого Plugin.
+Точки входу, завантажені через facade, віддають перевагу активному знімку конфігурації середовища виконання, коли він існує,
+а потім повертаються до визначеного файла конфігурації на диску.
-Підшляхи, специфічні для можливостей, такі як `image-generation`, `media-understanding`
-і `speech`, існують, оскільки bundled Plugins уже використовують їх сьогодні. Вони
-не є автоматично довгостроково замороженими зовнішніми контрактами — перевіряйте
-відповідну сторінку довідника SDK, коли покладаєтеся на них.
+Підшляхи, специфічні для можливостей, як-от `image-generation`, `media-understanding`
+і `speech`, існують, оскільки вбудовані Plugin уже використовують їх сьогодні. Вони не є
+автоматично зовнішніми контрактами, назавжди зафіксованими на довгий термін — перевіряйте відповідну
+довідкову сторінку SDK, якщо спираєтеся на них.
-## Схеми tool повідомлень
+## Схеми інструментів повідомлень
-Plugins повинні володіти внесками у схему `describeMessageTool(...)`, специфічними для channel,
-для примітивів, відмінних від повідомлень, таких як реакції, прочитання та опитування.
+Plugin мають володіти внесками до схем каналоспецифічних `describeMessageTool(...)`
+для немеседжних примітивів, таких як реакції, позначення прочитаного та опитування.
Спільне представлення надсилання має використовувати загальний контракт `MessagePresentation`
-замість native полів provider для button, component, block або card.
-Див. [Message Presentation](/uk/plugins/message-presentation) щодо контракту,
-резервних правил, зіставлення provider і контрольного списку для авторів Plugin.
+замість native-полів постачальника для button, component, block або card.
+Контракт, правила fallback, зіставлення провайдерів і контрольний список для авторів Plugin описано в
+[Message Presentation](/uk/plugins/message-presentation).
-Plugins із можливістю надсилання оголошують, що вони можуть відтворювати, через message capabilities:
+Plugin, які підтримують надсилання, оголошують, що саме вони можуть відтворювати, через можливості повідомлень:
-- `presentation` для семантичних блоків представлення (`text`, `context`, `divider`, `buttons`, `select`)
+- `presentation` для блоків семантичного представлення (`text`, `context`, `divider`, `buttons`, `select`)
- `delivery-pin` для запитів закріпленої доставки
-Core вирішує, чи відтворювати представлення нативно, чи деградувати його до тексту.
-Не відкривайте шляхи обходу нативного UI provider із загального message tool.
-Застарілі helper-и SDK для старих native схем залишаються експортованими для наявних
-сторонніх Plugins, але нові Plugins не повинні їх використовувати.
+Ядро вирішує, чи відтворювати представлення нативно, чи деградувати його до тексту.
+Не відкривайте escape hatch до native UI постачальника через загальний інструмент повідомлень.
+Застарілі допоміжні засоби SDK для старих native-схем і далі експортуються для наявних
+сторонніх Plugin, але нові Plugin не повинні їх використовувати.
-## Визначення цілі channel
+## Визначення цілей каналу
-Plugins channel повинні володіти семантикою цілей, специфічною для channel. Зберігайте спільний
-хост вихідного трафіку узагальненим і використовуйте surface messaging adapter для правил provider:
+Plugin каналів мають володіти каналоспецифічною семантикою цілей. Зберігайте спільний
+вихідний host загальним і використовуйте поверхню messaging adapter для правил провайдера:
-- `messaging.inferTargetChatType({ to })` визначає, чи нормалізовану ціль
- слід трактувати як `direct`, `group` або `channel` до пошуку в directory.
-- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи
- вхідні дані слід одразу передавати до визначення за id-подібним значенням замість пошуку в directory.
-- `messaging.targetResolver.resolveTarget(...)` — це резервний варіант Plugin, коли
- core потрібне остаточне визначення, що належить provider, після нормалізації або
+- `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль
+ слід трактувати як `direct`, `group` чи `channel` до пошуку в directory.
+- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи
+ слід одразу перейти до визначення за id-подібним значенням замість пошуку в directory.
+- `messaging.targetResolver.resolveTarget(...)` — це резервний шлях Plugin, коли
+ ядру потрібне остаточне визначення, що належить провайдеру, після нормалізації або
після промаху в directory.
- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії,
- специфічною для provider, після того як ціль визначено.
+ специфічною для провайдера, після визначення цілі.
Рекомендований поділ:
- Використовуйте `inferTargetChatType` для рішень за категоріями, які мають відбуватися до
пошуку peer/group.
-- Використовуйте `looksLikeId` для перевірок виду «обробляти це як явний/native id цілі».
-- Використовуйте `resolveTarget` для резервної нормалізації, специфічної для provider, а не для
+- Використовуйте `looksLikeId` для перевірок на кшталт «трактувати це як явний/native id цілі».
+- Використовуйте `resolveTarget` для резервної нормалізації, специфічної для провайдера, а не для
широкого пошуку в directory.
-- Зберігайте native id provider, такі як chat id, thread id, JID, handle і room
- id, усередині значень `target` або параметрів, специфічних для provider, а не в загальних
+- Зберігайте native id провайдера, як-от id чату, id потоку, JID, handle та id кімнати,
+ усередині значень `target` або в специфічних для провайдера параметрах, а не в загальних
полях SDK.
## Directory на основі конфігурації
-Plugins, які виводять записи directory з конфігурації, мають зберігати цю логіку в
-Plugin і повторно використовувати спільні helper-и з
+Plugin, які виводять записи directory з конфігурації, мають зберігати цю логіку в
+Plugin і повторно використовувати спільні допоміжні засоби з
`openclaw/plugin-sdk/directory-runtime`.
-Використовуйте це, коли channel потребує peer/group на основі конфігурації, наприклад:
+Використовуйте це, коли каналу потрібні peer/group на основі конфігурації, такі як:
-- DM-peer-и на основі allowlist
-- налаштовані зіставлення channel/group
-- статичні резервні варіанти directory для окремих облікових записів
+- DM peer, що визначаються allowlist
+- налаштовані відображення channel/group
+- статичні резервні directory на рівні облікового запису
-Спільні helper-и в `directory-runtime` обробляють лише загальні операції:
+Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції:
-- фільтрацію запитів
-- застосування лімітів
-- helper-и дедуплікації/нормалізації
+- фільтрацію запиту
+- застосування ліміту
+- допоміжні засоби дедуплікації/нормалізації
- побудову `ChannelDirectoryEntry[]`
-Перевірка channel-специфічних облікових записів і нормалізація id мають залишатися в
-реалізації Plugin.
+Перевірка облікового запису та нормалізація id, специфічні для каналу, мають залишатися
+в реалізації Plugin.
-## Каталоги provider
+## Каталоги провайдерів
-Plugins provider можуть визначати каталоги моделей для inference за допомогою
+Plugin провайдерів можуть визначати каталоги моделей для інференсу через
`registerProvider({ catalog: { run(...) { ... } } })`.
`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в
`models.providers`:
-- `{ provider }` для одного запису provider
-- `{ providers }` для кількох записів provider
+- `{ provider }` для одного запису провайдера
+- `{ providers }` для кількох записів провайдерів
-Використовуйте `catalog`, коли Plugin володіє model id, специфічними для provider, типовими
-значеннями base URL або метаданими моделей, залежними від auth.
+Використовуйте `catalog`, коли Plugin володіє id моделей, специфічними для провайдера, типовими
+значеннями base URL або метаданими моделей, захищеними auth.
`catalog.order` керує тим, коли каталог Plugin зливається відносно
-вбудованих неявних provider-ів OpenClaw:
+вбудованих неявних провайдерів OpenClaw:
-- `simple`: звичайні provider-и на API-ключах або env
-- `profile`: provider-и, які з’являються, коли існують профілі auth
-- `paired`: provider-и, які синтезують кілька пов’язаних записів provider
-- `late`: останній прохід, після інших неявних provider-ів
+- `simple`: звичайні провайдери на API-ключах або на основі env
+- `profile`: провайдери, які з’являються, коли існують профілі auth
+- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів
+- `late`: останній прохід, після інших неявних провайдерів
-Пізніші provider-и перемагають у разі колізії ключів, тому Plugins можуть навмисно
-перевизначати вбудований запис provider з тим самим id provider.
+Пізніші провайдери перемагають у разі конфлікту ключів, тож Plugin можуть навмисно
+перевизначати вбудований запис провайдера з тим самим id провайдера.
Сумісність:
-- `discovery` усе ще працює як застарілий псевдонім
+- `discovery` і далі працює як застарілий псевдонім
- якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog`
-## Лише для читання: перевірка channel
+## Інспекція каналу лише для читання
-Якщо ваш Plugin реєструє channel, краще реалізувати
+Якщо ваш Plugin реєструє канал, віддавайте перевагу реалізації
`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`.
Чому:
-- `resolveAccount(...)` — це шлях runtime. Він може припускати, що облікові дані
- повністю матеріалізовані, і може швидко завершуватися помилкою, якщо потрібні секрети відсутні.
-- Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`,
- `openclaw channels status`, `openclaw channels resolve` і потоки doctor/repair конфігурації,
- не повинні матеріалізовувати облікові дані runtime лише для того,
+- `resolveAccount(...)` — це шлях середовища виконання. Він може припускати, що облікові дані
+ повністю матеріалізовані, і швидко завершуватися помилкою, коли потрібні секрети відсутні.
+- Командні шляхи лише для читання, такі як `openclaw status`, `openclaw status --all`,
+ `openclaw channels status`, `openclaw channels resolve` і потоки doctor/config
+ repair, не повинні потребувати матеріалізації runtime credentials лише для того,
щоб описати конфігурацію.
Рекомендована поведінка `inspectAccount(...)`:
-- Повертає лише описовий стан облікового запису.
-- Зберігає `enabled` і `configured`.
-- Включає поля джерела/статусу облікових даних, коли це доречно, наприклад:
+- Повертайте лише описовий стан облікового запису.
+- Зберігайте `enabled` і `configured`.
+- Додавайте поля джерела/статусу облікових даних, коли це доречно, наприклад:
- `tokenSource`, `tokenStatus`
- `botTokenSource`, `botTokenStatus`
- `appTokenSource`, `appTokenStatus`
- `signingSecretSource`, `signingSecretStatus`
-- Не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі лише читання.
- Для команд у стилі status достатньо повертати `tokenStatus: "available"` (і відповідне поле джерела).
+- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність
+ в режимі лише для читання. Для команд у стилі status достатньо повернути `tokenStatus: "available"`
+ (і відповідне поле джерела).
- Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але
- вони недоступні в поточному шляху команди.
+ вони недоступні в поточному командному шляху.
-Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди»
-замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштований.
+Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому командному
+шляху» замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано.
-## Package packs
+## Пакетні набори
Каталог Plugin може містити `package.json` з `openclaw.extensions`:
@@ -757,64 +761,64 @@ Plugins provider можуть визначати каталоги моделей
}
```
-Кожен запис стає Plugin. Якщо pack перелічує кілька extensions, id Plugin
+Кожен запис стає Plugin. Якщо набір містить кілька extensions, id Plugin
стає `name/`.
-Якщо ваш Plugin імпортує залежності npm, установіть їх у цьому каталозі, щоб
+Якщо ваш Plugin імпортує npm-залежності, встановлюйте їх у цьому каталозі, щоб
`node_modules` був доступний (`npm install` / `pnpm install`).
-Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу Plugin
-після визначення symlink. Записи, які виходять за межі каталогу package,
+Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу Plugin
+після визначення symlink. Записи, які виходять за межі каталогу пакунка,
відхиляються.
-Примітка щодо безпеки: `openclaw plugins install` установлює залежності Plugin через
-`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev dependencies під час runtime). Зберігайте дерева залежностей Plugin
-«чистими JS/TS» і уникайте package-ів, які потребують збірок через `postinstall`.
+Примітка щодо безпеки: `openclaw plugins install` встановлює залежності Plugin через
+`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev dependencies під час виконання). Зберігайте дерева залежностей Plugin
+як «чисті JS/TS» і уникайте пакунків, яким потрібні збірки через `postinstall`.
-Необов’язково: `openclaw.setupEntry` може вказувати на легкий module лише для setup.
-Коли OpenClaw потребує поверхонь setup для вимкненого Plugin channel або
-коли Plugin channel увімкнено, але ще не налаштовано, він завантажує `setupEntry`
-замість повної точки входу Plugin. Це робить запуск і setup легшими,
-коли ваша основна точка входу Plugin також підключає tools, hooks або інший код
-лише для runtime.
+Необов’язково: `openclaw.setupEntry` може вказувати на легковаговий модуль лише для налаштування.
+Коли OpenClaw потребує поверхонь налаштування для вимкненого Plugin каналу або
+коли Plugin каналу ввімкнено, але його ще не налаштовано, він завантажує `setupEntry`
+замість повної точки входу Plugin. Це робить запуск і налаштування легшими,
+коли ваша основна точка входу Plugin також підключає інструменти, хуки або інший код,
+призначений лише для середовища виконання.
Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`
-може перевести Plugin channel на той самий шлях `setupEntry` під час
-фази запуску gateway до початку прослуховування, навіть якщо channel уже налаштовано.
+може перевести Plugin каналу на той самий шлях `setupEntry` під час
+передслухового етапу запуску gateway, навіть коли канал уже налаштовано.
Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати
-до того, як gateway почне прослуховування. На практиці це означає, що точка входу setup
-має реєструвати всі можливості, що належать channel і від яких залежить запуск, наприклад:
+до того, як gateway почне слухати. На практиці це означає, що точка входу налаштування
+має реєструвати кожну можливість, що належить каналу й від якої залежить запуск, наприклад:
-- власне реєстрацію channel
-- будь-які HTTP routes, які мають бути доступні до того, як gateway почне прослуховування
-- будь-які методи Gateway, tools або сервіси, які мають існувати в тому самому вікні
+- саму реєстрацію каналу
+- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне слухати
+- будь-які методи gateway, інструменти або сервіси, які мають існувати в той самий проміжок часу
-Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте
-цей прапорець. Залиште Plugin на типовій поведінці й дозвольте OpenClaw завантажити
+Якщо ваша повна точка входу все ще володіє будь-якою обов’язковою можливістю запуску, не вмикайте
+цей прапорець. Залиште Plugin у типовій поведінці й дозвольте OpenClaw завантажити
повну точку входу під час запуску.
-Bundled channels також можуть публікувати helper-и contract-surface лише для setup, до яких core
-може звертатися до завантаження повного runtime channel. Поточна surface
-просування setup:
+Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, які ядро
+може перевіряти до завантаження повного середовища виконання каналу. Поточна поверхня
+просування налаштування така:
- `singleAccountKeysToMove`
- `namedAccountPromotionKeys`
- `resolveSingleAccountPromotionTarget(...)`
-Core використовує цю surface, коли потрібно просунути застарілу конфігурацію
-одиночного облікового запису channel у `channels..accounts.*` без завантаження повної точки входу Plugin.
-Matrix — поточний bundled приклад: він переміщує лише auth/bootstrap-ключі в
-іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може зберегти
-налаштований неканонічний ключ default-account замість того, щоб завжди створювати
+Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію каналу з одним обліковим записом
+у `channels..accounts.*` без завантаження повної точки входу Plugin.
+Matrix — поточний вбудований приклад: він переносить лише ключі auth/bootstrap у
+іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може
+зберегти налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати
`accounts.default`.
-Ці setup patch adapter-и зберігають lazy-виявлення bundled contract-surface. Час імпорту залишається
-легким; surface просування завантажується лише під час першого використання, а не через
-повторний вхід у запуск bundled channel під час імпорту module.
+Ці адаптери патчів налаштування зберігають lazy-виявлення поверхні контракту вбудованих каналів. Час
+імпорту залишається легким; поверхня просування завантажується лише під час першого використання замість
+повторного входу в запуск вбудованого каналу під час імпорту модуля.
-Коли ці surface запуску включають методи Gateway RPC, зберігайте їх на
-префіксі, специфічному для Plugin. Простори назв admin core (`config.*`,
+Коли ці поверхні запуску включають Gateway RPC methods, зберігайте їх на
+специфічному для Plugin префіксі. Простори імен адміністратора ядра (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються
як `operator.admin`, навіть якщо Plugin запитує вужчий scope.
@@ -833,10 +837,10 @@ Matrix — поточний bundled приклад: він переміщує л
}
```
-### Метадані каталогу channel
+### Метадані каталогу каналів
-Plugins channel можуть оголошувати метадані setup/discovery через `openclaw.channel` і
-підказки встановлення через `openclaw.install`. Це дозволяє core не містити даних каталогу.
+Plugin каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і
+підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити даних каталогу.
Приклад:
@@ -851,7 +855,7 @@ Plugins channel можуть оголошувати метадані setup/disco
"selectionLabel": "Nextcloud Talk (self-hosted)",
"docsPath": "/channels/nextcloud-talk",
"docsLabel": "nextcloud-talk",
- "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
+ "blurb": "Self-hosted chat через webhook-ботів Nextcloud Talk.",
"order": 65,
"aliases": ["nc-talk", "nc"]
},
@@ -864,65 +868,65 @@ Plugins channel можуть оголошувати метадані setup/disco
}
```
-Корисні поля `openclaw.channel` поза мінімальним прикладом:
+Корисні поля `openclaw.channel` понад мінімальний приклад:
- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу
-- `docsLabel`: перевизначення тексту посилання для посилання на документацію
-- `preferOver`: id Plugin/channel з нижчим пріоритетом, які цей запис каталогу має перевершувати
-- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: керування текстом поверхні вибору
-- `markdownCapable`: позначає channel як сумісний із Markdown для рішень щодо форматування вихідних повідомлень
-- `exposure.configured`: приховує channel із поверхонь списку налаштованих channel, коли встановлено `false`
-- `exposure.setup`: приховує channel з інтерактивних вибирачів setup/configure, коли встановлено `false`
-- `exposure.docs`: позначає channel як внутрішній/приватний для поверхонь навігації документації
+- `docsLabel`: перевизначити текст посилання для посилання на документацію
+- `preferOver`: id Plugin/каналів нижчого пріоритету, які цей запис каталогу має випереджати
+- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору
+- `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо форматування вихідних повідомлень
+- `exposure.configured`: приховати канал із поверхонь списку налаштованих каналів, якщо встановлено `false`
+- `exposure.setup`: приховати канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено `false`
+- `exposure.docs`: позначити канал як внутрішній/приватний для поверхонь навігації документацією
- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure`
-- `quickstartAllowFrom`: підключає channel до стандартного потоку quickstart `allowFrom`
-- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис
-- `preferSessionLookupForAnnounceTarget`: віддає перевагу пошуку сесії під час визначення цілей announce
+- `quickstartAllowFrom`: додає канал до стандартного потоку quickstart `allowFrom`
+- `forceAccountBinding`: вимагати явну прив’язку облікового запису, навіть якщо існує лише один обліковий запис
+- `preferSessionLookupForAnnounceTarget`: віддавати перевагу пошуку сесії під час визначення цілей оголошення
-OpenClaw також може зливати **зовнішні каталоги channel** (наприклад, експорт registry
-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`). Кожен файл повинен
+Або вкажіть у `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`)
+один або кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл має
містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`.
-Згенеровані записи каталогу channel і записи каталогу встановлення provider-ів відкривають
-нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Ці
-нормалізовані факти визначають, чи є npm spec точною версією чи плаваючим
-селектором, чи присутні очікувані метадані цілісності та чи доступне також локальне
-джерело. Коли ідентичність каталогу/package відома, нормалізовані факти попереджають, якщо
-розібрана назва npm package відхиляється від цієї ідентичності.
-Вони також попереджають, коли `defaultChoice` є недійсним або вказує на джерело, яке
-недоступне, і коли метадані цілісності npm присутні без дійсного джерела
-npm. Споживачі мають трактувати `installSource` як адитивне необов’язкове поле, щоб
-старі записи, зібрані вручну, і compatibility shim-и не мусили його синтезувати.
-Це дозволяє onboarding і діагностиці пояснювати стан plane джерел без
-імпорту runtime Plugin.
+Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів показують
+нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Нормалізовані
+факти визначають, чи є npm spec точною версією чи плаваючим селектором,
+чи присутні очікувані метадані цілісності, а також чи доступний локальний
+шлях джерела. Коли ідентичність каталогу/пакунка відома, нормалізовані
+факти попереджають, якщо розібране ім’я npm-пакунка відхиляється від цієї ідентичності.
+Вони також попереджають, коли `defaultChoice` є недійсним або вказує на джерело,
+яке недоступне, а також коли метадані цілісності npm присутні без дійсного npm-
+джерела. Споживачі мають трактувати `installSource` як адитивне необов’язкове поле, щоб
+старі записи, зібрані вручну, і shim-и сумісності не мусили його синтезувати.
+Це дає змогу онбордингу й діагностиці пояснювати стан source plane без
+імпорту середовища виконання Plugin.
-Офіційні зовнішні записи npm повинні віддавати перевагу точному `npmSpec` плюс
-`expectedIntegrity`. Прості назви package і dist-tag-и все ще працюють для
-сумісності, але вони показують попередження plane джерел, щоб каталог міг рухатися
-до встановлень із фіксованими версіями та перевіркою цілісності без порушення наявних Plugins.
-Коли onboarding встановлює з локального шляху каталогу, він записує
-запис `plugins.installs` із `source: "path"` і шляхом `sourcePath`, відносним до workspace,
-коли це можливо. Абсолютний робочий шлях завантаження залишається в
-`plugins.load.paths`; запис встановлення уникає дублювання локальних робочих
-шляхів станції у довготривалу конфігурацію. Це робить локальні встановлення для розробки видимими для
-діагностики plane джерел без додавання другої surface розкриття сирих шляхів файлової системи.
+Офіційні зовнішні npm-записи мають віддавати перевагу точному `npmSpec` плюс
+`expectedIntegrity`. Прості імена пакунків і dist-tags і далі працюють для
+сумісності, але вони показують попередження source plane, щоб каталог міг рухатися
+в бік зафіксованих установлень із перевіркою цілісності без порушення роботи наявних Plugin.
+Коли онбординг виконує встановлення з локального шляху каталогу, він записує
+запис `plugins.installs` із `source: "path"` і відносним до workspace
+`sourcePath`, коли це можливо. Абсолютний робочий шлях завантаження залишається в
+`plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів робочої станції
+в довготривалій конфігурації. Це зберігає видимість локальних установлень для розробки для
+діагностики source plane без додавання другої сирої поверхні розкриття шляхів файлової системи.
-## Plugins рушія контексту
+## Plugin механізму контексту
-Plugins рушія контексту володіють orchestration контексту сесії для ingest, assembly
-і Compaction. Реєструйте їх зі свого Plugin за допомогою
-`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через
+Plugin механізму контексту володіють оркестрацією контексту сесії для поглинання, збирання
+та Compaction. Реєструйте їх зі свого Plugin через
+`api.registerContextEngine(id, factory)`, а потім вибирайте активний механізм через
`plugins.slots.contextEngine`.
-Використовуйте це, коли ваш Plugin має замінити або розширити типовий конвеєр
-контексту, а не просто додати пошук у пам’яті або hooks.
+Використовуйте це, коли вашому Plugin потрібно замінити або розширити типовий
+конвеєр контексту, а не просто додати пошук у пам’яті чи хуки.
```ts
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
@@ -950,8 +954,8 @@ export default function (api) {
}
```
-Якщо ваш рушій **не** володіє алгоритмом Compaction, залиште `compact()`
-реалізованим і явно делегуйте його:
+Якщо ваш механізм **не** володіє алгоритмом Compaction, збережіть реалізацію `compact()`
+і явно делегуйте її:
```ts
import {
@@ -988,45 +992,45 @@ export default function (api) {
## Додавання нової можливості
-Коли Plugin потребує поведінки, яка не вкладається в поточний API, не обходьте
-систему Plugin через приватний доступ усередину. Додайте відсутню можливість.
+Коли Plugin потрібна поведінка, яка не вписується в поточний API, не обходьте
+систему Plugin через приватне внутрішнє звернення. Додайте відсутню можливість.
Рекомендована послідовність:
-1. визначте контракт core
- Вирішіть, якою спільною поведінкою має володіти core: політика, резервна поведінка, злиття конфігурації,
- життєвий цикл, семантика для channel і форма runtime helper-а.
-2. додайте типізовані поверхні реєстрації/runtime Plugin
- Розширте `OpenClawPluginApi` та/або `api.runtime` мінімально корисною
- типізованою surface можливості.
-3. підключіть споживачів core + channel/feature
- Channels і Plugins функцій повинні споживати нову можливість через core,
- а не імпортувати напряму реалізацію постачальника.
+1. визначте контракт ядра
+ Вирішіть, якою спільною поведінкою має володіти ядро: policy, fallback, об’єднання config,
+ lifecycle, семантика для каналів і форма допоміжних засобів середовища виконання.
+2. додайте типізовані поверхні реєстрації/runtime для Plugin
+ Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною
+ типізованою поверхнею можливості.
+3. підключіть ядро + споживачів каналів/можливостей
+ Канали та Plugin можливостей мають споживати нову можливість через ядро,
+ а не імпортувати реалізацію постачальника напряму.
4. зареєструйте реалізації постачальників
- Потім Plugins постачальників реєструють свої бекенди для цієї можливості.
+ Потім Plugin постачальників реєструють свої бекенди для цієї можливості.
5. додайте покриття контракту
- Додайте тести, щоб володіння й форма реєстрації з часом залишалися явними.
+ Додайте тести, щоб форма володіння й реєстрації з часом залишалася явною.
-Саме так OpenClaw залишається виразним, не стаючи жорстко прив’язаним до
-світогляду одного постачальника. Див. [Збірник рецептів можливостей](/uk/plugins/architecture)
-для конкретного списку файлів і готового прикладу.
+Саме так OpenClaw зберігає власну архітектурну позицію, не стаючи жорстко
+прив’язаним до світогляду одного провайдера. Див. [Capability Cookbook](/uk/plugins/architecture)
+для конкретного контрольного списку файлів і готового прикладу.
### Контрольний список можливості
-Коли ви додаєте нову можливість, реалізація зазвичай повинна разом торкатися
+Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися
таких поверхонь:
-- типи контрактів core у `src//types.ts`
-- runner/runtime helper core у `src//runtime.ts`
-- surface реєстрації API Plugin у `src/plugins/types.ts`
-- wiring registry Plugin у `src/plugins/registry.ts`
-- відкриття runtime Plugin у `src/plugins/runtime/*`, коли Plugins функцій/channel
- мають його споживати
-- helper-и захоплення/тестування в `src/test-utils/plugin-registration.ts`
+- типи контракту ядра в `src//types.ts`
+- runner/допоміжний засіб середовища виконання ядра в `src//runtime.ts`
+- поверхня реєстрації API Plugin у `src/plugins/types.ts`
+- підключення реєстру Plugin в `src/plugins/registry.ts`
+- відкриття середовища виконання Plugin у `src/plugins/runtime/*`, коли Plugin можливостей/каналів
+ мають це споживати
+- допоміжні засоби capture/test у `src/test-utils/plugin-registration.ts`
- перевірки володіння/контракту в `src/plugins/contracts/registry.ts`
- документація для операторів/Plugin у `docs/`
-Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість
+Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість
ще не повністю інтегрована.
### Шаблон можливості
@@ -1034,7 +1038,7 @@ export default function (api) {
Мінімальний шаблон:
```ts
-// контракт core
+// контракт ядра
export type VideoGenerationProviderPlugin = {
id: string;
label: string;
@@ -1050,7 +1054,7 @@ api.registerVideoGenerationProvider({
},
});
-// спільний runtime helper для Plugins функцій/channel
+// спільний допоміжний засіб середовища виконання для Plugin можливостей/каналів
const clip = await api.runtime.videoGeneration.generate({
prompt: "Show the robot walking through the lab.",
cfg,
@@ -1063,16 +1067,16 @@ const clip = await api.runtime.videoGeneration.generate({
expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
```
-Це зберігає правило простим:
+Це зберігає просте правило:
-- core володіє контрактом можливості + orchestration
-- Plugins постачальників володіють реалізаціями постачальників
-- Plugins функцій/channel споживають runtime helper-и
-- тести контракту зберігають володіння явним
+- ядро володіє контрактом можливості + оркестрацією
+- Plugin постачальників володіють реалізаціями постачальника
+- Plugin можливостей/каналів споживають допоміжні засоби середовища виконання
+- тести контракту зберігають явність володіння
-## Пов’язане
+## Пов’язані сторінки
-- [Архітектура Plugin](/uk/plugins/architecture) — публічна модель і форми можливостей
-- [Підшляхи SDK Plugin](/uk/plugins/sdk-subpaths)
-- [Налаштування SDK Plugin](/uk/plugins/sdk-setup)
-- [Створення Plugins](/uk/plugins/building-plugins)
+- [Архітектура Plugin](/uk/plugins/architecture) — модель публічних можливостей і форми
+- [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths)
+- [Налаштування Plugin SDK](/uk/plugins/sdk-setup)
+- [Створення Plugin](/uk/plugins/building-plugins)
diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md
index 82425df24..34797ac73 100644
--- a/docs/uk/plugins/manifest.md
+++ b/docs/uk/plugins/manifest.md
@@ -1,64 +1,65 @@
---
read_when:
- - Ви створюєте Plugin для OpenClaw
- - Вам потрібно постачати schema конфігурації Plugin або налагоджувати помилки валідації Plugin
-summary: Маніфест Plugin + вимоги до JSON schema (сувора валідація конфігурації)
+ - Ви створюєте Plugin OpenClaw
+ - Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin
+summary: Вимоги до маніфесту Plugin та JSON schema (сувора валідація конфігурації)
title: Маніфест Plugin
x-i18n:
- generated_at: "2026-04-24T18:12:11Z"
+ generated_at: "2026-04-24T18:19:00Z"
model: gpt-5.4
provider: openai
- source_hash: 9118ed34fc7bb8923aff6b7f0ac795a1d637d255ef5f6ce0b37293e9a3812253
+ source_hash: bbef814f015b285ada8e656050d85e3113c218017840a5d1002e04348587dd5d
source_path: plugins/manifest.md
workflow: 15
---
-Ця сторінка стосується лише **нативного маніфесту Plugin OpenClaw**.
+Ця сторінка призначена лише для **нативного маніфесту Plugin OpenClaw**.
-Сумісні макети bundle див. у [Plugin bundles](/uk/plugins/bundles).
+Для сумісних макетів bundle дивіться [Plugin bundles](/uk/plugins/bundles).
Сумісні формати bundle використовують інші файли маніфесту:
- Codex bundle: `.codex-plugin/plugin.json`
-- Claude bundle: `.claude-plugin/plugin.json` або типовий макет компонента Claude
+- Claude bundle: `.claude-plugin/plugin.json` або стандартний макет компонента Claude
без маніфесту
- Cursor bundle: `.cursor-plugin/plugin.json`
OpenClaw також автоматично визначає ці макети bundle, але вони не проходять валідацію
-за schema `openclaw.plugin.json`, описаною тут.
+за схемою `openclaw.plugin.json`, описаною тут.
-Для сумісних bundle OpenClaw наразі читає метадані bundle плюс оголошені
-корені Skills, корені команд Claude, типові значення `settings.json` bundle Claude,
-типові значення LSP bundle Claude та підтримувані пакети hook, коли макет відповідає
-очікуванням runtime OpenClaw.
+Для сумісних bundle OpenClaw наразі зчитує метадані bundle, а також оголошені
+корені skill, корені команд Claude, значення за замовчуванням `settings.json` для Claude bundle,
+значення за замовчуванням LSP для Claude bundle та підтримувані набори hook, коли макет відповідає
+очікуванням середовища виконання OpenClaw.
-Кожен нативний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у
+Кожен нативний Plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у
**корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації
**без виконання коду Plugin**. Відсутні або невалідні маніфести вважаються
помилками Plugin і блокують валідацію конфігурації.
-Повний посібник по системі Plugin див.: [Plugins](/uk/tools/plugin).
-Для нативної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності:
+Дивіться повний посібник із системи Plugin: [Plugins](/uk/tools/plugin).
+Щодо нативної моделі можливостей і поточних рекомендацій із зовнішньої сумісності:
[Модель можливостей](/uk/plugins/architecture#public-capability-model).
## Що робить цей файл
-`openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження коду
-вашого Plugin**. Усе нижче має бути достатньо недорогим для перевірки без запуску
-runtime Plugin.
+`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду
+вашого Plugin**. Усе нижче має бути достатньо дешевим для перевірки без запуску
+середовища виконання Plugin.
**Використовуйте його для:**
-- ідентичності Plugin, валідації конфігурації та підказок для UI конфігурації
-- метаданих auth, onboarding і налаштування (alias, auto-enable, env vars провайдера, варіанти auth)
-- підказок активації для поверхонь control-plane
-- володіння скороченими сімействами моделей
+- ідентичності Plugin, валідації конфігурації та підказок UI для конфігурації
+- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища provider, варіанти автентифікації)
+- підказок активації для поверхонь control plane
+- скороченого володіння сімейством моделей
- статичних знімків володіння можливостями (`contracts`)
- метаданих QA runner, які може перевіряти спільний хост `openclaw qa`
-- метаданих конфігурації, специфічних для каналу, які об’єднуються в surfaces каталогу та валідації
+- метаданих конфігурації, специфічних для channel, які об’єднуються в каталог і поверхні валідації
-**Не використовуйте його для:** реєстрації поведінки runtime, оголошення code entrypoints,
-або метаданих встановлення npm. Це належить до коду вашого Plugin і `package.json`.
+**Не використовуйте його для:** реєстрації поведінки під час виконання, оголошення
+точок входу коду або метаданих встановлення npm. Це належить до коду вашого Plugin
+і `package.json`.
## Мінімальний приклад
@@ -79,7 +80,7 @@ runtime Plugin.
{
"id": "openrouter",
"name": "OpenRouter",
- "description": "Plugin провайдера OpenRouter",
+ "description": "OpenRouter provider plugin",
"version": "1.0.0",
"providers": ["openrouter"],
"modelSupport": {
@@ -107,19 +108,19 @@ runtime Plugin.
"provider": "openrouter",
"method": "api-key",
"choiceId": "openrouter-api-key",
- "choiceLabel": "Ключ API OpenRouter",
+ "choiceLabel": "OpenRouter API key",
"groupId": "openrouter",
"groupLabel": "OpenRouter",
"optionKey": "openrouterApiKey",
"cliFlag": "--openrouter-api-key",
"cliOption": "--openrouter-api-key ",
- "cliDescription": "Ключ API OpenRouter",
+ "cliDescription": "OpenRouter API key",
"onboardingScopes": ["text-inference"]
}
],
"uiHints": {
"apiKey": {
- "label": "Ключ API",
+ "label": "API key",
"placeholder": "sk-or-v1-...",
"sensitive": true
}
@@ -136,70 +137,70 @@ runtime Plugin.
}
```
-## Довідка щодо полів верхнього рівня
+## Довідник полів верхнього рівня
-| Field | Required | Type | What it means |
-| ------------------------------------ | -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id` | Так | `string` | Канонічний id Plugin. Саме цей id використовується в `plugins.entries.`. |
-| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. |
-| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Опустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб Plugin лишався вимкненим за замовчуванням. |
-| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id Plugin. |
-| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які мають автоматично вмикати цей Plugin, коли auth, конфігурація або посилання на моделі згадують їх. |
-| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. |
-| `channels` | Ні | `string[]` | Id каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. |
-| `providers` | Ні | `string[]` | Id провайдерів, якими володіє цей Plugin. |
-| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення провайдера, відносний до кореня Plugin, для метаданих каталогу провайдера в межах маніфесту, які можна завантажити без активації повного runtime Plugin. |
-| `modelSupport` | Ні | `object` | Керовані маніфестом метадані скорочених сімейств моделей, які використовуються для автозавантаження Plugin до запуску runtime. |
-| `providerEndpoints` | Ні | `object[]` | Керовані маніфестом метадані host/baseUrl endpoint-ів для маршрутів провайдера, які core має класифікувати до завантаження runtime провайдера. |
-| `cliBackends` | Ні | `string[]` | Id CLI backend-ів інференсу, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних посилань у конфігурації. |
-| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдер або CLI backend, для яких слід перевіряти synthetic auth hook, що належить Plugin, під час cold discovery моделей до завантаження runtime. |
-| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать вбудованому Plugin і представляють несекретний локальний, OAuth або ambient-стан облікових даних. |
-| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які мають створювати обізнану щодо Plugin діагностику конфігурації та CLI до завантаження runtime. |
-| `providerAuthEnvVars` | Ні | `Record` | Недорогі метадані env для auth провайдера, які OpenClaw може перевіряти без завантаження коду Plugin. |
-| `providerAuthAliases` | Ні | `Record` | Id провайдерів, які мають повторно використовувати id іншого провайдера для пошуку auth, наприклад provider coding, що використовує спільний API key і профілі auth базового провайдера. |
-| `channelEnvVars` | Ні | `Record` | Недорогі метадані env каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналу через env або поверхонь auth, які мають бачити узагальнені helper-и запуску/конфігурації. |
-| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані варіантів auth для picker-ів onboarding, визначення бажаного провайдера та простого зв’язування CLI flags. |
-| `activation` | Ні | `object` | Недорогі метадані планувальника активації для завантаження, що запускається провайдером, командою, каналом, маршрутом або можливістю. Лише метадані; фактичною поведінкою все одно володіє runtime Plugin. |
-| `setup` | Ні | `object` | Недорогі дескриптори setup/onboarding, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime Plugin. |
-| `qaRunners` | Ні | `object[]` | Недорогі дескриптори QA runner-ів, які спільний хост `openclaw qa` використовує до завантаження runtime Plugin. |
-| `contracts` | Ні | `object` | Статичний знімок можливостей вбудованого Plugin для зовнішніх auth hook-ів, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. |
-| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Недорогі типові значення media-understanding для id провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. |
-| `channelConfigs` | Ні | `Record` | Керовані маніфестом метадані конфігурації каналу, які об’єднуються в поверхнях виявлення й валідації до завантаження runtime. |
-| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореня Plugin. |
-| `name` | Ні | `string` | Людинозрозуміла назва Plugin. |
-| `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. |
-| `version` | Ні | `string` | Інформаційна версія Plugin. |
-| `uiHints` | Ні | `Record` | Мітки UI, placeholders і підказки щодо чутливості для полів конфігурації. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id` | Так | `string` | Канонічний id Plugin. Це id, який використовується в `plugins.entries.`. |
+| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. |
+| `enabledByDefault` | Ні | `true` | Позначає bundle Plugin як увімкнений за замовчуванням. Пропустіть це поле або вкажіть будь-яке значення, відмінне від `true`, щоб залишити Plugin вимкненим за замовчуванням. |
+| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id Plugin. |
+| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | id provider, які мають автоматично вмикати цей Plugin, коли автентифікація, конфігурація або посилання на модель згадують їх. |
+| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. |
+| `channels` | Ні | `string[]` | id channel, що належать цьому Plugin. Використовується для виявлення та валідації конфігурації. |
+| `providers` | Ні | `string[]` | id provider, що належать цьому Plugin. |
+| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення provider, відносний до кореня Plugin, для метаданих каталогу provider в межах маніфесту, які можна завантажити без активації повного середовища виконання Plugin. |
+| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту та використовуються для автоматичного завантаження Plugin до запуску середовища виконання. |
+| `providerEndpoints` | Ні | `object[]` | Метадані host/baseUrl кінцевих точок, що належать маніфесту, для маршрутів provider, які ядро має класифікувати до завантаження середовища виконання provider. |
+| `cliBackends` | Ні | `string[]` | id backend CLI, що належать цьому Plugin. Використовується для автоматичної активації під час запуску з явних посилань у конфігурації. |
+| `syntheticAuthRefs` | Ні | `string[]` | Посилання provider або backend CLI, для яких слід перевіряти синтетичний hook автентифікації, що належить Plugin, під час холодного виявлення моделей до завантаження середовища виконання. |
+| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать bundle Plugin і представляють не секретний локальний стан, OAuth або ambient credential state. |
+| `commandAliases` | Ні | `object[]` | Назви команд, що належать цьому Plugin і мають формувати діагностику конфігурації та CLI з урахуванням Plugin до завантаження середовища виконання. |
+| `providerAuthEnvVars` | Ні | `Record` | Легковагові env-метадані автентифікації provider, які OpenClaw може перевіряти без завантаження коду Plugin. |
+| `providerAuthAliases` | Ні | `Record` | id provider, які мають повторно використовувати id іншого provider для пошуку автентифікації, наприклад provider для кодування, який спільно використовує API key базового provider і профілі автентифікації. |
+| `channelEnvVars` | Ні | `Record` | Легковагові env-метадані channel, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для setup channel на основі env або поверхонь автентифікації, які мають бачити узагальнені допоміжні засоби запуску/конфігурації. |
+| `providerAuthChoices` | Ні | `object[]` | Легковагові метадані варіантів автентифікації для picker під час онбордингу, визначення пріоритетного provider і простого зв’язування прапорців CLI. |
+| `activation` | Ні | `object` | Легковагові метадані планувальника активації для завантаження за provider, командою, channel, маршрутом і можливістю. Лише метадані; фактична поведінка, як і раніше, належить середовищу виконання Plugin. |
+| `setup` | Ні | `object` | Легковагові дескриптори setup/онбордингу, які поверхні виявлення та setup можуть перевіряти без завантаження середовища виконання Plugin. |
+| `qaRunners` | Ні | `object[]` | Легковагові дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання Plugin. |
+| `contracts` | Ні | `object` | Статичний знімок bundle capability для зовнішніх hook автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння tool. |
+| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легковагові значення за замовчуванням media-understanding для id provider, оголошених у `contracts.mediaUnderstandingProviders`. |
+| `channelConfigs` | Ні | `Record` | Метадані конфігурації channel, що належать маніфесту та об’єднуються з поверхнями виявлення й валідації до завантаження середовища виконання. |
+| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореня Plugin. |
+| `name` | Ні | `string` | Зрозуміла людині назва Plugin. |
+| `description` | Ні | `string` | Короткий опис, що показується на поверхнях Plugin. |
+| `version` | Ні | `string` | Інформаційна версія Plugin. |
+| `uiHints` | Ні | `Record` | Мітки UI, placeholders і підказки щодо чутливості для полів конфігурації. |
-## Довідка щодо `providerAuthChoices`
+## Довідник `providerAuthChoices`
-Кожен запис `providerAuthChoices` описує один варіант onboarding або auth.
-OpenClaw читає це до завантаження runtime провайдера.
+Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації.
+OpenClaw зчитує це до завантаження середовища виконання provider.
-| Field | Required | Type | What it means |
-| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `provider` | Так | `string` | Id провайдера, до якого належить цей варіант. |
-| `method` | Так | `string` | Id методу auth, до якого треба диспетчеризувати. |
-| `choiceId` | Так | `string` | Стабільний id варіанта auth, який використовується в onboarding і 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">` | У яких поверхнях onboarding має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `provider` | Так | `string` | id provider, до якого належить цей варіант. |
+| `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"]`. |
-## Довідка щодо `commandAliases`
+## Довідник `commandAliases`
-Використовуйте `commandAliases`, коли Plugin володіє назвою runtime-команди, яку користувачі можуть
-помилково додати в `plugins.allow` або спробувати запустити як кореневу CLI-команду. OpenClaw
-використовує ці метадані для діагностики без імпорту коду runtime Plugin.
+Використовуйте `commandAliases`, коли Plugin володіє назвою команди середовища виконання, яку користувачі можуть
+помилково додати до `plugins.allow` або спробувати виконати як кореневу команду CLI. OpenClaw
+використовує ці метадані для діагностики без імпорту коду середовища виконання Plugin.
```json
{
@@ -213,32 +214,34 @@ OpenClaw читає це до завантаження runtime провайде
}
```
-| Field | Required | Type | What it means |
-| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- |
-| `name` | Так | `string` | Назва команди, яка належить цьому Plugin. |
-| `kind` | Ні | `"runtime-slash"` | Позначає alias як slash-команду чату, а не кореневу CLI-команду. |
-| `cliCommand` | Ні | `string` | Пов’язана коренева CLI-команда, яку слід пропонувати для CLI-операцій, якщо вона існує. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------ | ----------- | ----------------- | ----------------------------------------------------------------------- |
+| `name` | Так | `string` | Назва команди, що належить цьому Plugin. |
+| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. |
+| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для CLI-операцій, якщо така існує. |
-## Довідка щодо `activation`
+## Довідник `activation`
-Використовуйте `activation`, коли Plugin може недорого оголосити, які події control-plane
-мають включати його в план активації/завантаження.
+Використовуйте `activation`, коли Plugin може дешево оголосити, які події control plane
+мають включати його до плану активації/завантаження.
Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє
-поведінку runtime, не замінює `register(...)` і не гарантує, що
-код Plugin уже виконувався. Планувальник активації використовує ці поля, щоб
-звузити коло кандидатів Plugin, перш ніж переходити до наявних метаданих
-володіння з маніфесту, таких як `providers`, `channels`, `commandAliases`,
-`setup.providers`, `contracts.tools` і hook-и.
+поведінку під час виконання, не замінює `register(...)` і не гарантує, що
+код Plugin уже був виконаний. Планувальник активації використовує ці поля для
+звуження набору кандидатів Plugin, перш ніж повертатися до наявних
+метаданих володіння з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`,
+`contracts.tools` і hooks.
Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте
`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`,
-коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальника, які не можна представити цими полями володіння.
+коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальника,
+які не можна представити через ці поля володіння.
-Цей блок містить лише метадані. Він не реєструє поведінку runtime і не
-замінює `register(...)`, `setupEntry` або інші entrypoint-и runtime/Plugin.
-Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому відсутність метаданих activation зазвичай впливає лише на продуктивність; вона не повинна
-впливати на коректність, доки ще існують застарілі резервні механізми володіння з маніфесту.
+Цей блок — лише метадані. Він не реєструє поведінку під час виконання та не
+замінює `register(...)`, `setupEntry` або інші точки входу середовища виконання/Plugin.
+Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому
+відсутність метаданих активації зазвичай лише впливає на продуктивність; це не повинно
+змінювати коректність, доки ще існують застарілі fallback-механізми володіння в маніфесті.
```json
{
@@ -252,56 +255,58 @@ OpenClaw читає це до завантаження runtime провайде
}
```
-| Field | Required | Type | What it means |
-| ---------------- | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `onProviders` | Ні | `string[]` | Id провайдерів, які мають включати цей Plugin у плани активації/завантаження. |
-| `onCommands` | Ні | `string[]` | Id команд, які мають включати цей Plugin у плани активації/завантаження. |
-| `onChannels` | Ні | `string[]` | Id каналів, які мають включати цей Plugin у плани активації/завантаження. |
-| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin у плани активації/завантаження. |
-| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки можливостей, що використовуються плануванням активації control-plane. Коли можливо, віддавайте перевагу вужчим полям. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `onProviders` | Ні | `string[]` | id provider, які мають включати цей Plugin до планів активації/завантаження. |
+| `onCommands` | Ні | `string[]` | id команд, які мають включати цей Plugin до планів активації/завантаження. |
+| `onChannels` | Ні | `string[]` | id channel, які мають включати цей Plugin до планів активації/завантаження. |
+| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. |
+| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються в плануванні активації control plane. За можливості надавайте перевагу вужчим полям. |
-Поточні live-споживачі:
+Поточні активні споживачі:
-- планування CLI, що запускається командою, використовує резервний перехід до застарілих
+- планування CLI, ініційоване командою, повертається до застарілих
`commandAliases[].cliCommand` або `commandAliases[].name`
-- планування setup/каналу, що запускається каналом, використовує резервний перехід до застарілого володіння `channels[]`, коли явні метадані активації каналу відсутні
-- планування setup/runtime, що запускається провайдером, використовує резервний перехід до застарілого
- володіння `providers[]` і `cliBackends[]` верхнього рівня, коли явні метадані активації провайдера відсутні
+- планування setup/channel, ініційоване channel, повертається до застарілого володіння `channels[]`,
+ коли явні метадані активації channel відсутні
+- планування setup/середовища виконання, ініційоване provider, повертається до застарілого
+ володіння `providers[]` і верхньорівневого `cliBackends[]`, коли явні метадані активації provider
+ відсутні
-Діагностика планувальника може відрізняти явні підказки activation від
-резервного володіння з маніфесту. Наприклад, `activation-command-hint` означає, що
-збіглося `activation.onCommands`, а `manifest-command-alias` означає, що
+Діагностика планувальника може розрізняти явні підказки активації та fallback на
+володіння з маніфесту. Наприклад, `activation-command-hint` означає, що
+збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що
планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для
-діагностики хоста й тестів; авторам Plugin слід і далі оголошувати метадані,
+діагностики хоста та тестів; авторам Plugin слід і надалі оголошувати метадані,
які найкраще описують володіння.
-## Довідка щодо `qaRunners`
+## Довідник `qaRunners`
-Використовуйте `qaRunners`, коли Plugin додає один або більше transport runner-ів під
-спільним коренем `openclaw qa`. Зберігайте ці метадані недорогими й статичними; фактичною
-реєстрацією CLI все одно володіє runtime Plugin через легковагову surface
-`runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`.
+Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner під
+спільним коренем `openclaw qa`. Зберігайте ці метадані легковаговими та статичними; фактичною
+реєстрацією CLI, як і раніше, керує середовище виконання Plugin через легковагову
+поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`.
```json
{
"qaRunners": [
{
"commandName": "matrix",
- "description": "Запустити live QA lane Matrix на базі Docker проти тимчасового homeserver"
+ "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
}
]
}
```
-| Field | Required | Type | What it means |
-| ------------- | -------- | -------- | ------------------------------------------------------------------ |
-| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. |
-| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------- | ----------- | -------- | ------------------------------------------------------------------- |
+| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. |
+| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. |
-## Довідка щодо `setup`
+## Довідник `setup`
-Використовуйте `setup`, коли поверхням setup і onboarding потрібні недорогі метадані Plugin
-до завантаження runtime.
+Використовуйте `setup`, коли поверхням setup та онбордингу потрібні дешеві метадані, що належать Plugin,
+до завантаження середовища виконання.
```json
{
@@ -320,52 +325,58 @@ OpenClaw читає це до завантаження runtime провайде
}
```
-`cliBackends` верхнього рівня лишається валідним і далі описує CLI backend-и
-інференсу. `setup.cliBackends` — це surface дескрипторів, специфічна для setup,
-для control-plane/setup-сценаріїв, які мають залишатися лише метаданими.
+Верхньорівневе `cliBackends` залишається валідним і надалі описує backend інференсу CLI.
+`setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для
+потоків control plane/setup, які мають залишатися лише метаданими.
-Коли вони присутні, `setup.providers` і `setup.cliBackends` є бажаною
-surface пошуку setup за принципом descriptor-first для виявлення setup. Якщо дескриптор лише звужує коло кандидата Plugin, а setup усе ще потребує багатших runtime hook-ів на етапі setup, встановіть `requiresRuntime: true` і залиште `setup-api` як
+Якщо присутні, `setup.providers` і `setup.cliBackends` є пріоритетною
+поверхнею пошуку descriptor-first для виявлення setup. Якщо дескриптор лише
+звужує candidate Plugin, а setup усе ще потребує багатших hook під час setup, встановіть `requiresRuntime: true` і залиште `setup-api` як
резервний шлях виконання.
-Встановлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для
+Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для
поверхні setup. OpenClaw трактує явне `false` як контракт лише на дескриптори
-і не виконуватиме `setup-api` для пошуку setup. Якщо `requiresRuntime`
-пропущено, зберігається застаріла резервна поведінка, щоб наявні Plugin, які додали дескриптори
+і не виконуватиме `setup-api` для пошуку setup. Пропущений `requiresRuntime`
+зберігає застарілу fallback-поведінку, щоб наявні Plugin, які додали дескриптори
без цього прапорця, не зламалися.
Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, нормалізовані
-значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися глобально унікальними серед
-виявлених Plugin. Неоднозначне володіння закривається в безпечний спосіб замість вибору
+значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними
+серед виявлених Plugin. Неоднозначне володіння завершується безпечною відмовою, а не вибором
переможця за порядком виявлення.
-### Довідка щодо `setup.providers`
+Коли середовище виконання setup усе ж виконується, діагностика реєстру setup повідомляє про
+розбіжність дескрипторів, якщо `setup-api` реєструє provider або backend CLI, які
+не оголошені дескрипторами маніфесту, або якщо дескриптор не має відповідної
+реєстрації під час виконання. Ця діагностика є додатковою і не відхиляє застарілі Plugin.
-| Field | Required | Type | What it means |
-| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ |
-| `id` | Так | `string` | Id провайдера, що показується під час setup або onboarding. Нормалізовані id мають бути глобально унікальними. |
-| `authMethods` | Ні | `string[]` | Id методів setup/auth, які цей провайдер підтримує без завантаження повного runtime. |
-| `envVars` | Ні | `string[]` | Env vars, які узагальнені поверхні setup/status можуть перевіряти до завантаження runtime Plugin. |
+### Довідник `setup.providers`
+
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------- |
+| `id` | Так | `string` | id provider, що надається під час setup або онбордингу. Зберігайте нормалізовані id глобально унікальними. |
+| `authMethods` | Ні | `string[]` | id методів setup/автентифікації, які цей provider підтримує без завантаження повного середовища виконання. |
+| `envVars` | Ні | `string[]` | Env vars, які узагальнені поверхні setup/status можуть перевіряти до завантаження середовища виконання Plugin. |
### Поля `setup`
-| Field | Required | Type | What it means |
-| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- |
-| `providers` | Ні | `object[]` | Дескриптори setup провайдерів, що показуються під час setup та onboarding. |
-| `cliBackends` | Ні | `string[]` | Id backend-ів на етапі setup, що використовуються для descriptor-first пошуку setup. Нормалізовані id мають залишатися глобально унікальними. |
-| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє surface setup цього Plugin. |
-| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------ |
+| `providers` | Ні | `object[]` | Дескриптори setup provider, доступні під час setup та онбордингу. |
+| `cliBackends` | Ні | `string[]` | id backend для setup, що використовуються для descriptor-first пошуку setup. Зберігайте нормалізовані id глобально унікальними. |
+| `configMigrations` | Ні | `string[]` | id міграцій конфігурації, що належать поверхні setup цього Plugin. |
+| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. |
-## Довідка щодо `uiHints`
+## Довідник `uiHints`
-`uiHints` — це мапа від імен полів конфігурації до невеликих підказок рендерингу.
+`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для рендерингу.
```json
{
"uiHints": {
"apiKey": {
- "label": "Ключ API",
- "help": "Використовується для запитів OpenRouter",
+ "label": "API key",
+ "help": "Used for OpenRouter requests",
"placeholder": "sk-or-v1-...",
"sensitive": true
}
@@ -373,9 +384,9 @@ surface пошуку setup за принципом descriptor-first для ви
}
```
-Кожна підказка поля може містити:
+Кожна підказка для поля може містити:
-| Field | Type | What it means |
+| Поле | Тип | Що воно означає |
| ------------- | ---------- | --------------------------------------- |
| `label` | `string` | Мітка поля для користувача. |
| `help` | `string` | Короткий допоміжний текст. |
@@ -384,10 +395,10 @@ surface пошуку setup за принципом descriptor-first для ви
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
| `placeholder` | `string` | Текст placeholder для полів форми. |
-## Довідка щодо `contracts`
+## Довідник `contracts`
Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може
-прочитати без імпорту runtime Plugin.
+зчитати без імпорту середовища виконання Plugin.
```json
{
@@ -410,37 +421,37 @@ surface пошуку setup за принципом descriptor-first для ви
Кожен список є необов’язковим:
-| Field | Type | What it means |
-| -------------------------------- | ---------- | ----------------------------------------------------------------- |
-| `embeddedExtensionFactories` | `string[]` | Id вбудованого runtime, для яких вбудований Plugin може реєструвати factories. |
-| `externalAuthProviders` | `string[]` | Id провайдерів, чий hook зовнішнього auth profile належить цьому Plugin. |
-| `speechProviders` | `string[]` | Id провайдерів speech, якими володіє цей Plugin. |
-| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів realtime transcription, якими володіє цей Plugin. |
-| `realtimeVoiceProviders` | `string[]` | Id провайдерів realtime voice, якими володіє цей Plugin. |
-| `memoryEmbeddingProviders` | `string[]` | Id провайдерів memory embedding, якими володіє цей Plugin. |
-| `mediaUnderstandingProviders` | `string[]` | Id провайдерів media-understanding, якими володіє цей Plugin. |
-| `imageGenerationProviders` | `string[]` | Id провайдерів image-generation, якими володіє цей Plugin. |
-| `videoGenerationProviders` | `string[]` | Id провайдерів video-generation, якими володіє цей Plugin. |
-| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей Plugin. |
-| `webSearchProviders` | `string[]` | Id провайдерів web search, якими володіє цей Plugin. |
-| `tools` | `string[]` | Імена інструментів агента, якими володіє цей Plugin, для перевірок контрактів вбудованих Plugin. |
+| Поле | Тип | Що воно означає |
+| -------------------------------- | ---------- | ------------------------------------------------------------------- |
+| `embeddedExtensionFactories` | `string[]` | id вбудованого середовища виконання, для яких bundle Plugin може реєструвати factory. |
+| `externalAuthProviders` | `string[]` | id provider, чий зовнішній hook профілю автентифікації належить цьому Plugin. |
+| `speechProviders` | `string[]` | id provider мовлення, які належать цьому Plugin. |
+| `realtimeTranscriptionProviders` | `string[]` | id provider транскрипції в реальному часі, які належать цьому Plugin. |
+| `realtimeVoiceProviders` | `string[]` | id provider голосу в реальному часі, які належать цьому Plugin. |
+| `memoryEmbeddingProviders` | `string[]` | id provider embedding для пам’яті, які належать цьому Plugin. |
+| `mediaUnderstandingProviders` | `string[]` | id provider media-understanding, які належать цьому Plugin. |
+| `imageGenerationProviders` | `string[]` | id provider генерації зображень, які належать цьому Plugin. |
+| `videoGenerationProviders` | `string[]` | id provider генерації відео, які належать цьому Plugin. |
+| `webFetchProviders` | `string[]` | id provider web-fetch, які належать цьому Plugin. |
+| `webSearchProviders` | `string[]` | id provider web search, які належать цьому Plugin. |
+| `tools` | `string[]` | Назви tool агента, які належать цьому Plugin для bundle-перевірок контрактів. |
-Plugin провайдера, які реалізують `resolveExternalAuthProfiles`, мають оголошувати
+Plugin provider, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати
`contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють
-через застарілий резервний механізм сумісності, але цей механізм повільніший і
-буде видалений після завершення вікна міграції.
+через застарілий fallback-механізм сумісності, але він повільніший і
+буде вилучений після вікна міграції.
-Вбудовані провайдери memory embedding мають оголошувати
-`contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони надають, включно з
-вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей контракт
-маніфесту, щоб завантажувати лише Plugin-власник до того, як повний runtime Gateway
-зареєструє провайдерів.
+Bundle Plugin provider embedding для пам’яті повинні оголошувати
+`contracts.memoryEmbeddingProviders` для кожного id adapter, який вони надають, включно з
+вбудованими adapter, такими як `local`. Автономні шляхи CLI використовують цей контракт маніфесту,
+щоб завантажувати лише Plugin-власник до того, як повне середовище виконання Gateway
+зареєструє provider.
-## Довідка щодо `mediaUnderstandingProviderMetadata`
+## Довідник `mediaUnderstandingProviderMetadata`
-Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має
-типові моделі, пріоритет резервного auto-auth або нативну підтримку документів, які
-узагальненим helper-ам core потрібні до завантаження runtime. Ключі також мають бути оголошені в
+Використовуйте `mediaUnderstandingProviderMetadata`, коли provider media-understanding має
+моделі за замовчуванням, пріоритет fallback автоматичної автентифікації або нативну підтримку документів,
+які потрібні узагальненим допоміжним засобам ядра до завантаження середовища виконання. Ключі також мають бути оголошені в
`contracts.mediaUnderstandingProviders`.
```json
@@ -464,19 +475,19 @@ Plugin провайдера, які реалізують `resolveExternalAuthPro
}
```
-Кожен запис провайдера може містити:
+Кожен запис provider може містити:
-| Field | Type | What it means |
-| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- |
-| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. |
-| `defaultModels` | `Record` | Типові значення відповідності можливість→модель, що використовуються, коли в конфігурації не вказано модель. |
-| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. |
-| `nativeDocumentInputs` | `"pdf"[]` | Нативні формати документів, які підтримує провайдер. |
+| Поле | Тип | Що воно означає |
+| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------ |
+| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей provider. |
+| `defaultModels` | `Record` | Значення моделей за замовчуванням для можливостей, які використовуються, коли конфігурація не вказує модель. |
+| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback provider на основі облікових даних. |
+| `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує provider. |
-## Довідка щодо `channelConfigs`
+## Довідник `channelConfigs`
-Використовуйте `channelConfigs`, коли канальному Plugin потрібні недорогі метадані конфігурації
-до завантаження runtime.
+Використовуйте `channelConfigs`, коли Plugin channel потребує дешевих метаданих конфігурації до
+завантаження середовища виконання.
```json
{
@@ -491,32 +502,32 @@ Plugin провайдера, які реалізують `resolveExternalAuthPro
},
"uiHints": {
"homeserverUrl": {
- "label": "URL homeserver",
+ "label": "Homeserver URL",
"placeholder": "https://matrix.example.com"
}
},
"label": "Matrix",
- "description": "Підключення до homeserver Matrix",
+ "description": "Matrix homeserver connection",
"preferOver": ["matrix-legacy"]
}
}
}
```
-Кожен запис каналу може містити:
+Кожен запис channel може містити:
-| Field | Type | What it means |
-| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
-| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. |
-| `uiHints` | `Record` | Необов’язкові мітки UI/placeholders/підказки чутливості для цього розділу конфігурації каналу. |
-| `label` | `string` | Мітка каналу, що об’єднується в surfaces picker та inspect, коли метадані runtime ще не готові. |
-| `description` | `string` | Короткий опис каналу для surfaces inspect і catalog. |
-| `preferOver` | `string[]` | Id застарілих або менш пріоритетних Plugin, які цей канал має випереджати в surfaces вибору. |
+| Поле | Тип | Що воно означає |
+| ------------- | ------------------------ | ------------------------------------------------------------------------------------- |
+| `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації channel. |
+| `uiHints` | `Record` | Необов’язкові мітки UI/placeholders/підказки чутливості для цього розділу конфігурації channel. |
+| `label` | `string` | Мітка channel, що об’єднується з поверхнями picker та inspect, коли метадані середовища виконання ще не готові. |
+| `description` | `string` | Короткий опис channel для поверхонь inspect і catalog. |
+| `preferOver` | `string[]` | id застарілих або менш пріоритетних Plugin, які цей channel має випереджати на поверхнях вибору. |
-## Довідка щодо `modelSupport`
+## Довідник `modelSupport`
-Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера з
-скорочених id моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження runtime Plugin.
+Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin provider із
+скорочених id моделей, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження середовища виконання Plugin.
```json
{
@@ -529,98 +540,105 @@ Plugin провайдера, які реалізують `resolveExternalAuthPro
OpenClaw застосовує такий пріоритет:
-- явні посилання `provider/model` використовують метадані маніфесту `providers` власника
-- `modelPatterns` мають пріоритет над `modelPrefixes`
-- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований
+- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать власнику
+- `modelPatterns` мають вищий пріоритет, ніж `modelPrefixes`
+- якщо збігаються один небандлований Plugin і один bundle Plugin, перемагає небандлований
Plugin
-- решта неоднозначностей ігноруються, доки користувач або конфігурація не задасть провайдера
+- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкажуть provider
Поля:
-| Field | Type | What it means |
-| --------------- | ---------- | ------------------------------------------------------------------------------- |
-| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id моделей. |
-| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id моделей після видалення суфікса профілю. |
+| Поле | Тип | Що воно означає |
+| --------------- | ---------- | ----------------------------------------------------------------------------- |
+| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими id моделей. |
+| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими id моделей після видалення суфікса профілю. |
Застарілі ключі можливостей верхнього рівня є deprecated. Використовуйте `openclaw doctor --fix`, щоб
перемістити `speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`,
-`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне
+`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне
завантаження маніфесту більше не трактує ці поля верхнього рівня як
володіння можливостями.
-## Маніфест проти package.json
+## Маніфест і `package.json`
Ці два файли виконують різні завдання:
-| File | Use it for |
-| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів auth і підказки UI, які мають існувати до запуску коду Plugin |
-| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoints, обмежень встановлення, setup або метаданих каталогу |
+| Файл | Для чого використовувати |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду Plugin |
+| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, обмеження встановлення, setup або метаданих catalog |
-Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте таке правило:
+Якщо ви не впевнені, де має належати певний фрагмент метаданих, використовуйте таке правило:
-- якщо OpenClaw повинен знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json`
-- якщо це стосується пакування, entry-файлів або поведінки встановлення npm, розміщуйте це в `package.json`
+- якщо OpenClaw має знати це до завантаження коду Plugin, помістіть це в `openclaw.plugin.json`
+- якщо це стосується пакування, файлів входу або поведінки встановлення npm, помістіть це в `package.json`
### Поля `package.json`, які впливають на виявлення
-Деякі метадані Plugin до запуску runtime навмисно зберігаються в `package.json` у блоці
+Деякі метадані Plugin до запуску середовища виконання навмисно зберігаються в `package.json` у блоці
`openclaw`, а не в `openclaw.plugin.json`.
Важливі приклади:
-| Field | What it means |
+| Поле | Що воно означає |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `openclaw.extensions` | Оголошує native entrypoint-и Plugin. Вони мають залишатися всередині каталогу пакета Plugin. |
-| `openclaw.runtimeExtensions` | Оголошує entrypoint-и built JavaScript runtime для встановлених пакетів. Вони мають залишатися всередині каталогу пакета Plugin. |
-| `openclaw.setupEntry` | Легковаговий entrypoint лише для setup, який використовується під час onboarding, відкладеного запуску каналу та read-only виявлення channel status/SecretRef. Має залишатися всередині каталогу пакета Plugin. |
-| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript entrypoint setup для встановлених пакетів. Має залишатися всередині каталогу пакета Plugin. |
-| `openclaw.channel` | Недорогі метадані каталогу каналу, такі як labels, шляхи до документації, alias-и та текст для вибору. |
-| `openclaw.channel.configuredState` | Недорогі метадані перевірки configured-state, які можуть відповісти на питання «чи вже існує налаштування лише через env?» без завантаження повного runtime каналу. |
-| `openclaw.channel.persistedAuthState` | Недорогі метадані перевірки persisted-auth, які можуть відповісти на питання «чи вже є якийсь активний вхід?» без завантаження повного runtime каналу. |
-| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення вбудованих і зовнішньо опублікованих Plugin. |
-| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
-| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із нижньою межею semver, наприклад `>=2026.3.22`. |
-| `openclaw.install.expectedIntegrity` | Очікуваний рядок integrity для npm dist, наприклад `sha512-...`; сценарії встановлення й оновлення перевіряють отриманий артефакт щодо нього. |
-| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого Plugin, коли конфігурація невалідна. |
-| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дає змогу поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. |
+| `openclaw.extensions` | Оголошує точки входу нативного Plugin. Має залишатися в межах каталогу пакета Plugin. |
+| `openclaw.runtimeExtensions` | Оголошує точки входу built JavaScript runtime для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. |
+| `openclaw.setupEntry` | Легковагова точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску channel і виявлення статусу channel/SecretRef у режимі лише читання. Має залишатися в межах каталогу пакета Plugin. |
+| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript точку входу setup для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. |
+| `openclaw.channel` | Легковагові метадані catalog channel, такі як мітки, шляхи до документації, псевдоніми та текст для вибору. |
+| `openclaw.channel.configuredState` | Легковагові метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує setup лише через env?» без завантаження повного середовища виконання channel. |
+| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже є хтось увійшов у систему?» без завантаження повного середовища виконання channel. |
+| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для bundle Plugin і Plugin, опублікованих зовні. |
+| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
+| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. |
+| `openclaw.install.expectedIntegrity` | Очікуваний рядок integrity npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. |
+| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення bundle Plugin, коли конфігурація невалідна. |
+| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного Plugin channel під час запуску. |
Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в
-onboarding до завантаження runtime. `package.json#openclaw.install` повідомляє
-onboarding, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих
-варіантів. Не переносіть підказки встановлення до `openclaw.plugin.json`.
+онбордингу до завантаження середовища виконання. `package.json#openclaw.install` повідомляє
+онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих
+варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`.
-`openclaw.install.minHostVersion` примусово застосовується під час встановлення та
-завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають
+`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження
+реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають
Plugin на старіших хостах.
Точне закріплення версії npm уже міститься в `npmSpec`, наприклад
-`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу
-мають поєднувати точні специфікації з `expectedIntegrity`, щоб сценарії оновлення завершувалися безпечно, якщо отриманий npm-артефакт більше не відповідає закріпленому релізу.
-Інтерактивний onboarding усе ще пропонує довірені npm-специфікації реєстру, включно з простими назвами пакетів і dist-tag, для сумісності. Діагностика каталогу може
-розрізняти точні, плаваючі, закріплені integrity, без integrity, з невідповідністю назви пакета та невалідні джерела default-choice. Вона також попереджає, коли
-`expectedIntegrity` присутній, але немає валідного npm-джерела, яке можна ним закріпити.
+`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього catalog
+повинні поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися
+безпечним відхиленням, якщо отриманий npm-артефакт більше не відповідає закріпленому релізу.
+Інтерактивний онбординг, як і раніше, пропонує npm-специфікації довіреного реєстру, включно з
+простими назвами пакетів і dist-tag, для сумісності. Діагностика catalog може
+розрізняти точні, плаваючі, закріплені integrity, без integrity, із невідповідністю
+назви пакета та з невалідним default-choice джерела. Вона також попереджає, коли
+`expectedIntegrity` присутній, але немає валідного джерела npm, яке можна ним закріпити.
Коли `expectedIntegrity` присутній,
-сценарії встановлення/оновлення примусово його перевіряють; коли його пропущено, результат розв’язання реєстру
+потоки встановлення/оновлення застосовують його; коли його пропущено, розв’язання реєстру
фіксується без закріплення integrity.
-Канальні Plugin мають надавати `openclaw.setupEntry`, коли status, список каналів
-або сканування SecretRef мають визначити налаштовані акаунти без завантаження повного
-runtime. Entry setup має надавати метадані каналу плюс безпечні для setup адаптери конфігурації,
-status і секретів; клієнти мережі, слухачі gateway і runtime транспорту слід залишати в основному entrypoint extension.
+Plugin channel мають надавати `openclaw.setupEntry`, коли статус, список channel
+або сканування SecretRef мають ідентифікувати налаштовані облікові записи без завантаження повного
+середовища виконання. Точка входу setup має надавати метадані channel разом із безпечними для setup adapter
+конфігурації, статусу та секретів; мережеві клієнти, слухачі Gateway і
+транспортні середовища виконання залишайте в основній точці входу розширення.
-Поля entrypoint runtime не перевизначають перевірки меж пакета для полів
-entrypoint вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити
+Поля точки входу runtime не скасовують перевірки меж пакета для полів
+вихідної точки входу. Наприклад, `openclaw.runtimeExtensions` не може зробити
завантажуваним шлях `openclaw.extensions`, що виходить за межі.
`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно не
-робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно дозволяє лише сценаріям встановлення відновлюватися після конкретних збоїв оновлення застарілих вбудованих Plugin, таких як
-відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для того самого
-вбудованого Plugin. Непов’язані помилки конфігурації, як і раніше, блокують встановлення і спрямовують операторів до `openclaw doctor --fix`.
+робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє
+потокам встановлення відновлюватися після певних застарілих збоїв оновлення bundle Plugin,
+таких як відсутній шлях bundle Plugin або застарілий запис `channels.` для того самого
+bundle Plugin. Непов’язані помилки конфігурації, як і раніше, блокують встановлення та спрямовують операторів
+до `openclaw doctor --fix`.
-`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки:
+`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля
+перевірки:
```json
{
@@ -636,12 +654,12 @@ entrypoint вихідного коду. Наприклад, `openclaw.runtimeExt
}
```
-Використовуйте це, коли сценаріям setup, doctor або configured-state потрібна недорога перевірка auth
-типу так/ні до завантаження повного Plugin каналу. Цільовий export має бути невеликою
-функцією, яка лише читає збережений стан; не маршрутизуйте її через повний barrel
-runtime каналу.
+Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка
+автентифікації у форматі так/ні до завантаження повного Plugin channel. Цільовий export має бути невеликою
+функцією, яка читає лише persisted state; не спрямовуйте її через повний barrel
+середовища виконання channel.
-`openclaw.channel.configuredState` використовує ту саму форму для недорогих перевірок
+`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок
configured-state лише через env:
```json
@@ -658,57 +676,58 @@ configured-state лише через env:
}
```
-Використовуйте це, коли канал може відповісти на configured-state на основі env або інших невеликих
-вхідних даних, не пов’язаних із runtime. Якщо перевірка потребує повного розв’язання конфігурації або реального
-runtime каналу, залишайте цю логіку в hook `config.hasConfiguredState` Plugin.
+Використовуйте це, коли channel може визначити configured-state через env або інші невеликі
+вхідні дані без середовища виконання. Якщо перевірка потребує повного розв’язання конфігурації або реального
+середовища виконання channel, натомість залиште цю логіку в hook `config.hasConfiguredState`
+Plugin.
## Пріоритет виявлення (дубльовані id Plugin)
-OpenClaw виявляє Plugin з кількох коренів (вбудовані, глобальне встановлення, workspace, явні шляхи, вибрані конфігурацією). Якщо два виявлені Plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість паралельного завантаження.
+OpenClaw виявляє Plugin із кількох коренів (bundle, global install, workspace, явні шляхи, вибрані конфігурацією). Якщо два знайдені Plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним.
Пріоритет, від найвищого до найнижчого:
-1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.`
-2. **Вбудований** — Plugin, що постачаються з OpenClaw
-3. **Глобальне встановлення** — Plugin, встановлені в глобальний корінь Plugin OpenClaw
+1. **Config-selected** — шлях, явно закріплений у `plugins.entries.`
+2. **Bundled** — Plugin, що постачаються разом з OpenClaw
+3. **Global install** — Plugin, установлені в глобальний корінь Plugin OpenClaw
4. **Workspace** — Plugin, виявлені відносно поточного workspace
Наслідки:
-- Форкнута або застаріла копія вбудованого Plugin у workspace не зможе затінити вбудовану збірку.
-- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтесь на виявлення у workspace.
-- Відкидання дублікатів записується в лог, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
+- Форкована або застаріла копія bundle Plugin у workspace не перекриє bundle-збірку.
+- Щоб справді перевизначити bundle Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення у workspace.
+- Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
## Вимоги до JSON Schema
-- **Кожен Plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію.
-- Порожня schema прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`).
-- Schema проходять валідацію під час читання/запису конфігурації, а не під час runtime.
+- **Кожен Plugin повинен містити JSON Schema**, навіть якщо він не приймає конфігурацію.
+- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
+- Схеми перевіряються під час читання/запису конфігурації, а не під час виконання.
## Поведінка валідації
-- Невідомі ключі `channels.*` — це **помилки**, якщо тільки id каналу не оголошено в
- маніфесті Plugin.
+- Невідомі ключі `channels.*` — це **помилки**, якщо тільки id channel не оголошено
+ в маніфесті Plugin.
- `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*`
- мають посилатися на **виявлювані** id Plugin. Невідомі id — це **помилки**.
-- Якщо Plugin встановлено, але він має зламаний або відсутній маніфест чи schema,
+ повинні посилатися на **виявлювані** id Plugin. Невідомі id — це **помилки**.
+- Якщо Plugin установлено, але він має зламаний або відсутній маніфест чи схему,
валідація завершується помилкою, а Doctor повідомляє про помилку Plugin.
-- Якщо конфігурація Plugin існує, але Plugin **вимкнений**, конфігурація зберігається, і
- в Doctor + логах з’являється **попередження**.
+- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається, і
+ у Doctor + журналах показується **попередження**.
-Повну schema `plugins.*` див. у [Configuration reference](/uk/gateway/configuration).
+Дивіться [Configuration reference](/uk/gateway/configuration) для повної схеми `plugins.*`.
## Примітки
-- Маніфест **обов’язковий для нативних Plugin OpenClaw**, включно з локальними завантаженнями з файлової системи. Runtime, як і раніше, завантажує модуль Plugin окремо; маніфест потрібен лише для виявлення + валідації.
-- Нативні маніфести парсяться за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок дозволені, якщо фінальне значення все одно є об’єктом.
-- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня.
+- Маніфест **обов’язковий для нативних Plugin OpenClaw**, включно із завантаженням із локальної файлової системи. Середовище виконання, як і раніше, завантажує модуль Plugin окремо; маніфест використовується лише для виявлення + валідації.
+- Нативні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, якщо кінцеве значення все одно є об’єктом.
+- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте користувацьких ключів верхнього рівня.
- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує.
-- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час запиту.
+- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широке середовище виконання; використовуйте його для статичних метаданих catalog provider або вузьких дескрипторів виявлення, а не для виконання під час запиту.
- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`).
-- Метадані env vars (`providerAuthEnvVars`, `channelEnvVars`) мають лише декларативний характер. Status, audit, валідація доставки Cron та інші read-only surfaces усе одно застосовують довіру до Plugin і політику ефективної активації, перш ніж вважати env var налаштованою.
-- Для метаданих runtime wizard, які потребують коду провайдера, див. [Provider runtime hooks](/uk/plugins/architecture-internals#provider-runtime-hooks).
-- Якщо ваш Plugin залежить від native module, задокументуйте кроки збірки та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `).
+- Env-метадані (`providerAuthEnvVars`, `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставлення Cron та інші поверхні лише для читання, як і раніше, застосовують політику довіри до Plugin та ефективної активації, перш ніж вважати env var налаштованою.
+- Для метаданих wizard під час виконання, які потребують коду provider, дивіться [Provider runtime hooks](/uk/plugins/architecture-internals#provider-runtime-hooks).
+- Якщо ваш Plugin залежить від нативних модулів, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `).
## Пов’язане
@@ -720,6 +739,6 @@ OpenClaw виявляє Plugin з кількох коренів (вбудова
Внутрішня архітектура та модель можливостей.
- Довідка по SDK Plugin і імпортах subpath.
+ Довідник SDK Plugin та імпорти підшляхів.