diff --git a/docs/uk/plugins/architecture-internals.md b/docs/uk/plugins/architecture-internals.md
index 777502df2..30fee6729 100644
--- a/docs/uk/plugins/architecture-internals.md
+++ b/docs/uk/plugins/architecture-internals.md
@@ -1,96 +1,96 @@
---
read_when:
- Реалізація хуків середовища виконання провайдера, життєвого циклу каналу або пакетних наборів
- - Налагодження порядку завантаження plugin або стану реєстру
- - Додавання нової можливості plugin або plugin для рушія контексту
+ - Налагодження порядку завантаження Plugin або стану реєстру
+ - Додавання нової можливості Plugin або Plugin механізму контексту
summary: 'Внутрішні компоненти архітектури Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці'
title: Внутрішні компоненти архітектури Plugin
x-i18n:
- generated_at: "2026-04-24T16:00:13Z"
+ generated_at: "2026-04-24T16:05:26Z"
model: gpt-5.4
provider: openai
- source_hash: 10120a0e05be6bb414339e83ed846001cfe31b491bd8ce9a4bcf340d4b8186d5
+ source_hash: 19018f885f2a8a5f49d5603e122f8b6c7053e28a27a5ac3a4fd315d2cf9be2ac
source_path: plugins/architecture-internals.md
workflow: 15
---
-Щоб дізнатися про публічну модель можливостей, форми plugin, а також контракти
-власності/виконання, див. [Архітектура Plugin](/uk/plugins/architecture). Ця сторінка —
-довідник з внутрішньої механіки: конвеєр завантаження, реєстр, хуки середовища виконання,
-HTTP-маршрути Gateway, шляхи імпорту та таблиці схем.
+Для публічної моделі можливостей, форм Plugin і контрактів
+володіння/виконання див. [Архітектура Plugin](/uk/plugins/architecture). Ця сторінка —
+довідник із внутрішньої механіки: конвеєра завантаження, реєстру, хуків середовища виконання,
+HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем.
## Конвеєр завантаження
-Під час запуску OpenClaw приблизно робить таке:
+Під час запуску OpenClaw приблизно виконує таке:
-1. виявляє кореневі каталоги потенційних plugin
-2. читає маніфести native або сумісних збірок і метадані пакунків
-3. відхиляє небезпечні кандидати
-4. нормалізує конфігурацію plugin (`plugins.enabled`, `allow`, `deny`, `entries`,
+1. виявляє кандидатні корені Plugin
+2. зчитує маніфести нативних або сумісних збірок і метадані пакетів
+3. відхиляє небезпечних кандидатів
+4. нормалізує конфігурацію Plugin (`plugins.enabled`, `allow`, `deny`, `entries`,
`slots`, `load.paths`)
-5. визначає, чи ввімкнено кожного кандидата
-6. завантажує ввімкнені native-модулі: зібрані вбудовані модулі використовують native-завантажувач;
- незібрані native plugin використовують jiti
-7. викликає native-хуки `register(api)` і збирає реєстрації до реєстру plugin
-8. відкриває реєстр для команд/поверхонь середовища виконання
+5. визначає, чи буде ввімкнено кожного кандидата
+6. завантажує ввімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач;
+ незібрані нативні Plugin використовують jiti
+7. викликає нативні хуки `register(api)` і збирає реєстрації в реєстр Plugin
+8. відкриває реєстр для команд і поверхонь середовища виконання
-`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це на тому самому етапі. Усі вбудовані plugin використовують `register`; для нових plugin віддавайте перевагу `register`.
+`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані Plugin використовують `register`; для нових Plugin надавайте перевагу `register`.
Перевірки безпеки відбуваються **до** виконання в середовищі виконання. Кандидати блокуються,
-коли точка входу виходить за межі кореня plugin, шлях є доступним для запису всім, або
-власник шляху виглядає підозріло для невбудованих plugin.
+коли точка входу виходить за межі кореня Plugin, шлях доступний для запису всім, або
+власність шляху виглядає підозріло для невбудованих Plugin.
-### Поведінка manifest-first
+### Поведінка з пріоритетом маніфесту
-Маніфест — це джерело істини для площини керування. OpenClaw використовує його, щоб:
+Маніфест — це джерело істини для контрольної площини. OpenClaw використовує його, щоб:
-- ідентифікувати plugin
-- знаходити оголошені канали/Skills/схему конфігурації або можливості збірки
+- ідентифікувати Plugin
+- виявляти оголошені канали/Skills/схему конфігурації або можливості збірки
- перевіряти `plugins.entries..config`
-- доповнювати мітки/заповнювачі в Control UI
+- доповнювати мітки/заповнювачі інтерфейсу керування
- показувати метадані встановлення/каталогу
-- зберігати дешеві дескриптори активації та налаштування без завантаження середовища виконання plugin
+- зберігати дешеві дескриптори активації та налаштування без завантаження середовища виконання Plugin
-Для native plugin модуль середовища виконання є частиною площини даних. Він реєструє
-фактичну поведінку, як-от хуки, інструменти, команди або потоки провайдера.
+Для нативних Plugin модуль середовища виконання — це частина площини даних. Він реєструє
+фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера.
-Необов’язкові блоки маніфесту `activation` і `setup` залишаються в площині керування.
+Необов’язкові блоки маніфесту `activation` і `setup` залишаються на контрольній площині.
Це лише дескриптори метаданих для планування активації та виявлення налаштування;
вони не замінюють реєстрацію в середовищі виконання, `register(...)` або `setupEntry`.
-Перші споживачі живої активації тепер використовують підказки маніфесту для команд, каналів і провайдерів,
-щоб звузити завантаження plugin до ширшої матеріалізації реєстру:
+Перші активні споживачі активації тепер використовують підказки маніфесту для команд, каналів і провайдерів,
+щоб звузити завантаження Plugin до ширшої матеріалізації реєстру:
-- завантаження CLI звужується до plugin, яким належить запитана основна команда
-- налаштування каналу/визначення plugin звужується до plugin, яким належить
- запитаний ідентифікатор каналу
-- явне визначення налаштування/середовища виконання провайдера звужується до plugin, яким належить
- запитаний ідентифікатор провайдера
+- завантаження CLI звужується до Plugin, яким належить запитана основна команда
+- налаштування каналу/визначення Plugin звужується до Plugin, яким належить запитаний
+ id каналу
+- явне визначення налаштування/середовища виконання провайдера звужується до Plugin, яким належить
+ запитаний id провайдера
-Планувальник активації надає і API лише з ідентифікаторами для наявних викликів, і
-API плану для нової діагностики. Записи плану повідомляють, чому було вибрано plugin,
-відокремлюючи явні підказки планувальника `activation.*` від резервного визначення власності за маніфестом,
-як-от `providers`, `channels`, `commandAliases`, `setup.providers`,
-`contracts.tools` і хуки. Це розділення причин є межею сумісності:
-наявні метадані plugin продовжують працювати, а новий код може виявляти широкі підказки
-або резервну поведінку без зміни семантики завантаження в середовищі виконання.
+Планувальник активації надає як API лише з id для наявних викликачів, так і
+API плану для нової діагностики. Записи плану повідомляють, чому Plugin було вибрано,
+відокремлюючи явні підказки планувальника `activation.*` від резервного визначення власника через маніфест,
+такого як `providers`, `channels`, `commandAliases`, `setup.providers`,
+`contracts.tools` і хуки. Це розділення причин — межа сумісності:
+наявні метадані Plugin продовжують працювати, тоді як новий код може виявляти широкі підказки
+або резервну поведінку без зміни семантики завантаження середовища виконання.
-Виявлення налаштування тепер надає перевагу ідентифікаторам, що належать дескрипторам, як-от `setup.providers` і
-`setup.cliBackends`, щоб звузити коло кандидатів plugin, перш ніж воно повернеться до
-`setup-api` для plugin, яким усе ще потрібні хуки середовища виконання на етапі налаштування. Якщо більше ніж
-один виявлений plugin заявляє права на той самий нормалізований ідентифікатор провайдера налаштування
-або бекенда CLI, пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на порядок виявлення.
+Виявлення налаштування тепер надає перевагу id, що належать дескриптору, таким як `setup.providers` і
+`setup.cliBackends`, щоб звузити кандидатні Plugin до того, як воно повернеться до
+`setup-api` для Plugin, яким усе ще потрібні хуки середовища виконання на етапі налаштування. Якщо більше ніж
+один виявлений Plugin заявляє про той самий нормалізований id провайдера налаштування або CLI backend,
+пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на порядок виявлення.
### Що кешує завантажувач
-OpenClaw зберігає короткоживучі внутрішньопроцесні кеші для:
+OpenClaw зберігає короткочасні внутрішньопроцесні кеші для:
- результатів виявлення
- даних реєстру маніфестів
-- завантажених реєстрів plugin
+- завантажених реєстрів Plugin
-Ці кеші зменшують стрибкоподібні витрати під час запуску та накладні витрати від повторних команд. Їх безпечно
+Ці кеші зменшують стрибкоподібне навантаження під час запуску та повторні накладні витрати команд. Їх безпечно
сприймати як короткочасні кеші продуктивності, а не як постійне зберігання.
Примітка щодо продуктивності:
@@ -102,36 +102,36 @@ OpenClaw зберігає короткоживучі внутрішньопро
## Модель реєстру
-Завантажені plugin не змінюють напряму довільні глобальні змінні ядра. Вони реєструються в
-центральному реєстрі plugin.
+Завантажені Plugin не змінюють безпосередньо довільні глобальні змінні ядра. Вони реєструються в
+центральному реєстрі Plugin.
Реєстр відстежує:
-- записи plugin (ідентичність, джерело, походження, стан, діагностика)
+- записи Plugin (ідентичність, джерело, походження, стан, діагностика)
- інструменти
-- застарілі хуки й типізовані хуки
+- застарілі хуки та типізовані хуки
- канали
-- провайдерів
+- провайдери
- обробники Gateway RPC
- HTTP-маршрути
- реєстратори CLI
- фонові служби
-- команди, що належать plugin
+- команди, що належать Plugin
-Потім можливості ядра читають із цього реєстру замість того, щоб звертатися до модулів plugin
-безпосередньо. Це зберігає односпрямоване завантаження:
+Потім можливості ядра зчитують дані з цього реєстру, а не звертаються до модулів Plugin
+безпосередньо. Це зберігає односторонність завантаження:
-- модуль plugin -> реєстрація в реєстрі
-- ядро середовища виконання -> споживання реєстру
+- модуль Plugin -> реєстрація в реєстрі
+- середовище виконання ядра -> споживання реєстру
-Таке розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра потрібна
-лише одна точка інтеграції: «читати реєстр», а не «створювати спеціальні випадки для кожного модуля plugin».
+Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра потрібна
+лише одна точка інтеграції: «зчитати реєстр», а не «робити спеціальну обробку для кожного модуля Plugin».
-## Колбеки прив’язування розмови
+## Зворотні виклики прив’язки розмови
Plugin, які прив’язують розмову, можуть реагувати, коли схвалення вирішено.
-Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек після того, як запит на прив’язування буде схвалено або відхилено:
+Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, як запит на прив’язку схвалено або відхилено:
```ts
export default {
@@ -139,124 +139,124 @@ 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);
});
},
};
```
-Поля корисного навантаження колбека:
+Поля корисного навантаження зворотного виклику:
- `status`: `"approved"` або `"denied"`
- `decision`: `"allow-once"`, `"allow-always"` або `"deny"`
-- `binding`: визначене прив’язування для схвалених запитів
-- `request`: підсумок початкового запиту, підказка від’єднання, ідентифікатор відправника та
+- `binding`: визначена прив’язка для схвалених запитів
+- `request`: підсумок початкового запиту, підказка від’єднання, id відправника та
метадані розмови
-Цей колбек лише сповіщає. Він не змінює те, кому дозволено прив’язувати
-розмову, і запускається після завершення обробки схвалення в ядрі.
+Цей зворотний виклик призначений лише для сповіщення. Він не змінює, кому дозволено прив’язувати
+розмову, і виконується після завершення обробки схвалення ядром.
## Хуки середовища виконання провайдера
-Plugin провайдера мають три шари:
+Plugin провайдера мають три рівні:
-- **Метадані маніфесту** для дешевого пошуку до запуску середовища виконання: `providerAuthEnvVars`,
+- **Метадані маніфесту** для дешевого пошуку до етапу середовища виконання: `providerAuthEnvVars`,
`providerAuthAliases`, `providerAuthChoices` і `channelEnvVars`.
-- **Хуки часу конфігурації**: `catalog` (застаріле `discovery`) плюс
+- **Хуки часу конфігурації**: `catalog` (застарілий `discovery`) плюс
`applyConfigDefaults`.
-- **Хуки середовища виконання**: понад 40 необов’язкових хуків, що охоплюють auth, визначення моделей,
- обгортання потоку, рівні thinking, політику повторного відтворення та
- кінцеві точки usage. Див. повний список у [Порядок і використання хуків](#hook-order-and-usage).
+- **Хуки середовища виконання**: понад 40 необов’язкових хуків, що охоплюють auth, визначення моделі,
+ обгортання потоку, рівні thinking, політику replay та кінцеві точки usage. Див.
+ повний список у розділі [Порядок і використання хуків](#hook-order-and-usage).
-OpenClaw, як і раніше, володіє загальним циклом агента, failover, обробкою стенограм і
-політикою інструментів. Ці хуки є поверхнею розширення для специфічної для провайдера
-поведінки без потреби в повністю власному транспорті inference.
+OpenClaw, як і раніше, володіє загальним циклом агента, failover, обробкою транскриптів і
+політикою інструментів. Ці хуки є поверхнею розширення для поведінки, специфічної для провайдера,
+без потреби у повністю спеціальному транспорті inference.
-Використовуйте маніфест `providerAuthEnvVars`, коли провайдер має облікові дані на основі env,
-які мають бачити загальні шляхи auth/status/model-picker без завантаження середовища виконання plugin.
-Використовуйте маніфест `providerAuthAliases`, коли один ідентифікатор провайдера має повторно використовувати env vars,
-профілі auth, auth на основі конфігурації та варіант онбордингу API-ключа іншого ідентифікатора провайдера.
-Використовуйте маніфест `providerAuthChoices`, коли поверхні CLI онбордингу/вибору auth
-мають знати ідентифікатор вибору провайдера, мітки груп і просту прив’язку auth через один прапорець без
-завантаження середовища виконання провайдера. Залишайте `envVars` у середовищі виконання провайдера для
-операторських підказок, таких як мітки онбордингу або змінні налаштування OAuth
-client-id/client-secret.
+Використовуйте маніфест `providerAuthEnvVars`, коли провайдер має облікові дані на основі змінних середовища,
+які мають бути видимі загальним шляхам auth/status/model-picker без завантаження середовища виконання Plugin.
+Використовуйте маніфест `providerAuthAliases`, коли один id провайдера має повторно використовувати
+змінні середовища, профілі auth, auth на основі конфігурації та вибір онбордингу API-ключа
+іншого id провайдера. Використовуйте маніфест `providerAuthChoices`, коли поверхні CLI для онбордингу/вибору auth
+мають знати id вибору провайдера, мітки груп і просту прив’язку auth через один прапорець
+без завантаження середовища виконання провайдера. Залишайте `envVars` середовища виконання провайдера для
+підказок, орієнтованих на операторів, таких як мітки онбордингу або змінні налаштування
+client-id/client-secret для OAuth.
-Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування на основі env,
-які загальний резервний shell-env, перевірки config/status або підказки налаштування мають бачити
+Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування на основі змінних середовища, які
+мають бути видимі загальному резервному шляху shell-env, перевіркам config/status або підказкам налаштування
без завантаження середовища виконання каналу.
### Порядок і використання хуків
-Для plugin моделі/провайдера OpenClaw викликає хуки приблизно в такому порядку.
-Стовпець «Коли використовувати» — це короткий посібник для вибору.
+Для Plugin моделі/провайдера OpenClaw викликає хуки приблизно в такому порядку.
+Стовпець «Коли використовувати» — це короткий довідник для прийняття рішень.
-| # | Хук | Що він робить | Коли використовувати |
+| # | Хук | Що він робить | Коли використовувати |
| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або базовими значеннями `base URL` |
-| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації за замовчуванням, що належать провайдеру, під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей провайдера |
-| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку намагається використати звичайний шлях реєстру/каталогу | _(не є хуком plugin)_ |
-| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним визначенням моделі |
-| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для користувацьких ідентифікаторів провайдера в межах того самого сімейства транспорту |
-| 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 |
-| 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/конфігурації | Провайдер зберігає synthetic-профілі-заповнювачі, які не повинні мати вищий пріоритет |
-| 11 | `resolveDynamicModel` | Синхронний резервний шлях для model ids, що належать провайдеру, яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream model ids |
-| 12 | `prepareDynamicModel` | Асинхронний розігрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих ids |
-| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як вбудований runner використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра |
-| 14 | `contributeResolvedModelCompat` | Додає прапорці compat для моделей вендора за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе провайдера |
-| 15 | `capabilities` | Метадані стенограми/інструментів, що належать провайдеру, які використовує спільна логіка ядра | Провайдеру потрібні особливості стенограми/сімейства провайдера |
-| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований runner | Провайдеру потрібне очищення схем для сімейства транспорту |
-| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження про ключові слова без навчання ядра правил, специфічних для провайдера |
-| 18 | `resolveReasoningOutputMode` | Вибирає native чи tagged-контракт reasoning-output | Провайдеру потрібен 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 refresh для користувацьких кінцевих точок оновлення або політики збоїв оновлення | Провайдер не вписується у спільні механізми оновлення `pi-ai` |
-| 26 | `buildAuthDoctorHint` | Підказка з відновлення, що додається, коли OAuth refresh завершується помилкою | Провайдеру потрібні власні рекомендації з відновлення auth після збою оновлення |
-| 27 | `matchesContextOverflowError` | Матчер переповнення контекстного вікна, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики пропустили б |
-| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з перевищенням ліміту, перевантаженням тощо |
-| 29 | `isCacheTtlEligible` | Політика prompt-cache для провайдерів proxy/backhaul | Провайдеру потрібне керування TTL кешу, специфічне для proxy |
-| 30 | `buildMissingAuthMessage` | Замінник загального повідомлення про відновлення при відсутності auth | Провайдеру потрібна підказка відновлення при відсутності auth, специфічна для провайдера |
-| 31 | `suppressBuiltInModel` | Приховування застарілої upstream-моделі плюс необов’язкова підказка про помилку для користувача | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх підказкою вендора |
-| 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-профілю та вибору smoke | Провайдер володіє зіставленням бажаної live/smoke-моделі |
-| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед inference | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту |
-| 39 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` і пов’язаних поверхонь стану | Провайдеру потрібен користувацький розбір токена usage/quota або інші облікові дані usage |
-| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки usage/quota, специфічні для провайдера, після визначення auth | Провайдеру потрібна кінцева точка usage або парсер корисного навантаження, специфічні для провайдера |
-| 41 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті належить plugin провайдера |
-| 42 | `buildReplayPolicy` | Повертає політику replay, що керує обробкою стенограми для провайдера | Провайдеру потрібна користувацька політика стенограми (наприклад, видалення thinking-блоків) |
-| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення стенограми | Провайдеру потрібні переписування replay, специфічні для провайдера, понад спільні допоміжні засоби Compaction |
-| 44 | `validateReplayTurns` | Остаточна перевірка або переформування ходів replay перед вбудованим runner | Транспорту провайдера потрібна суворіша перевірка ходів після загального очищення |
-| 45 | `onModelSelected` | Запускає побічні ефекти після вибору, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною |
+| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями base URL |
+| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму auth, середовища або семантики сімейства моделей провайдера |
+| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку намагається використати звичайний шлях реєстру/каталогу | _(не є хуком Plugin)_ |
+| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед визначенням канонічної моделі |
+| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним складанням моделі | Провайдер володіє очищенням транспорту для користувацьких id провайдера в тому самому сімействі транспорту |
+| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням конфігурації/провайдера в середовищі виконання | Провайдеру потрібне очищення конфігурації, яке має жити разом із Plugin; вбудовані помічники сімейства Google також страхують підтримувані записи конфігурації Google |
+| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-перетворення 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/app | Провайдер повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті |
+| 10 | `shouldDeferSyntheticProfileAuth` | Понижує пріоритет збережених synthetic-заповнювачів профілю порівняно з auth на основі env/config | Провайдер зберігає synthetic-профілі-заповнювачі, які не повинні мати вищий пріоритет |
+| 11 | `resolveDynamicModel` | Синхронний резервний шлях для model id, що належать провайдеру, яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream model id |
+| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id |
+| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як вбудований runner використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра |
+| 14 | `contributeResolvedModelCompat` | Додає прапорці compat для моделей постачальника, що працюють через інший сумісний транспорт | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе роль провайдера |
+| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру й використовуються спільною логікою ядра | Провайдеру потрібні особливості транскрипту/сімейства провайдера |
+| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований runner | Провайдеру потрібне очищення схем для сімейства транспорту |
+| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження про ключові слова без додавання до ядра правил, специфічних для провайдера |
+| 18 | `resolveReasoningOutputMode` | Вибирає native або tagged-контракт reasoning-output | Провайдеру потрібні tagged reasoning/final output замість native-полів |
+| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера |
+| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку на користувацький транспорт | Провайдеру потрібен користувацький wire protocol, а не просто обгортка |
+| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки заголовків/тіла запиту/сумісності моделі без користувацького транспорту |
+| 22 | `resolveTransportTurnState` | Прикріплює native заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали native ідентичність ходу провайдера |
+| 23 | `resolveWebSocketSessionPolicy` | Прикріплює native заголовки WebSocket або політику cooldown сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику резервного шляху |
+| 24 | `formatApiKey` | Форматувальник auth-профілю: збережений профіль стає рядком `apiKey` у середовищі виконання | Провайдер зберігає додаткові метадані auth і потребує користувацької форми токена для середовища виконання |
+| 25 | `refreshOAuth` | Перевизначення OAuth refresh для користувацьких кінцевих точок refresh або політики помилок refresh | Провайдер не вписується у спільні refreshers `pi-ai` |
+| 26 | `buildAuthDoctorHint` | Підказка з виправлення, що додається, коли OAuth refresh завершується помилкою | Провайдеру потрібні власні вказівки з відновлення auth після збою refresh |
+| 27 | `matchesContextOverflowError` | Засіб зіставлення переповнення вікна контексту, що належить провайдеру | Провайдер має сирі помилки переповнення, які пропустять загальні евристики |
+| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо |
+| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для proxy |
+| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення для відсутнього auth | Провайдеру потрібна підказка відновлення для відсутнього auth, специфічна для провайдера |
+| 31 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей плюс необов’язкова підказка про помилку для користувача | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх підказкою постачальника |
+| 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 | Провайдер володіє зіставленням бажаних моделей для live/smoke |
+| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед inference | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту |
+| 39 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` і пов’язаних поверхонь стану | Провайдеру потрібен користувацький розбір токена usage/quota або інші облікові дані для usage |
+| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки usage/quota, специфічні для провайдера, після визначення auth | Провайдеру потрібна кінцева точка usage або парсер корисного навантаження, специфічні для провайдера |
+| 41 | `createEmbeddingProvider` | Створює адаптер embeddings, що належить провайдеру, для memory/search | Поведінка embeddings для memory має належати Plugin провайдера |
+| 42 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна користувацька політика транскрипту (наприклад, видалення блоків thinking) |
+| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні переписування replay, специфічні для провайдера, понад спільні помічники Compaction |
+| 44 | `validateReplayTurns` | Остаточна перевірка або переформатування ходів replay перед вбудованим runner | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санітизації |
+| 45 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною |
`normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють
-відповідний plugin провайдера, а потім переходять до інших plugin провайдера, що підтримують хуки,
-доки один із них фактично не змінить ідентифікатор моделі або transport/config. Це дозволяє
-shim провайдера для alias/compat працювати без вимоги, щоб викликач знав, який саме
-вбудований plugin володіє переписуванням. Якщо жоден хук провайдера не переписує підтримуваний
-запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google усе одно застосовує
-це очищення сумісності.
+відповідний Plugin провайдера, а потім переходять до інших Plugin провайдерів, що підтримують хуки,
+доки один із них фактично не змінить id моделі або транспорт/конфігурацію. Це зберігає
+працездатність shim-провайдерів для псевдонімів/compat без потреби для викликача знати, який
+вбудований Plugin володіє цим переписуванням. Якщо жоден хук провайдера не перепише підтримуваний
+запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно застосує
+це compat-очищення.
Якщо провайдеру потрібен повністю користувацький wire protocol або користувацький виконавець запитів,
-це вже інший клас розширення. Ці хуки призначені для поведінки провайдера,
-яка все ще працює в межах звичайного циклу inference OpenClaw.
+це вже інший клас розширення. Ці хуки призначені для поведінки провайдера, яка все ще працює
+в межах звичайного циклу inference OpenClaw.
### Приклад провайдера
@@ -314,27 +314,27 @@ api.registerProvider({
### Вбудовані приклади
-Вбудовані plugin провайдера поєднують наведені вище хуки відповідно до потреб кожного вендора щодо каталогу,
-auth, thinking, replay і usage. Авторитетний набір хуків живе разом із
-кожним plugin у `extensions/`; ця сторінка ілюструє форми, а не
-дзеркалить перелік.
+Вбудовані Plugin провайдерів комбінують наведені вище хуки, щоб відповідати потребам кожного постачальника щодо каталогу,
+auth, thinking, replay і usage. Авторитетний набір хуків знаходиться разом із
+кожним Plugin у `extensions/`; ця сторінка ілюструє форми, а не
+віддзеркалює список.
-
- OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` разом із
+
+ OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` плюс
`resolveDynamicModel` / `prepareDynamicModel`, щоб вони могли показувати upstream
- model ids раніше за статичний каталог OpenClaw.
+ id моделей раніше за статичний каталог OpenClaw.
GitHub Copilot, Gemini CLI, ChatGPT Codex, MiniMax, Xiaomi, z.ai поєднують
`prepareRuntimeAuth` або `formatApiKey` з `resolveUsageAuth` +
- `fetchUsageSnapshot`, щоб керувати обміном токенів та інтеграцією `/usage`.
+ `fetchUsageSnapshot`, щоб володіти обміном токенів та інтеграцією `/usage`.
-
+
Спільні іменовані сімейства (`google-gemini`, `passthrough-gemini`,
- `anthropic-by-model`, `hybrid-anthropic-openai`) дають провайдерам змогу підключатися до
- політики стенограми через `buildReplayPolicy` замість того, щоб кожен plugin
- заново реалізовував очищення.
+ `anthropic-by-model`, `hybrid-anthropic-openai`) дозволяють провайдерам підключатися до
+ політики транскриптів через `buildReplayPolicy` замість того, щоб кожен Plugin
+ повторно реалізовував очищення.
`byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`,
@@ -342,8 +342,8 @@ auth, thinking, replay і usage. Авторитетний набір хуків
`volcengine` реєструють лише `catalog` і використовують спільний цикл inference.
- Beta-заголовки, `/fast` / `serviceTier` і `context1m` живуть усередині
- публічного шва `api.ts` / `contract-api.ts` plugin Anthropic
+ Бета-заголовки, `/fast` / `serviceTier` і `context1m` живуть усередині
+ публічного шва `api.ts` / `contract-api.ts` Plugin Anthropic
(`wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
`resolveAnthropicFastMode`, `resolveAnthropicServiceTier`), а не в
загальному SDK.
@@ -375,12 +375,12 @@ const voices = await api.runtime.tts.listVoices({
- `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових нотаток.
- Використовує конфігурацію ядра `messages.tts` і вибір провайдера.
-- Повертає буфер PCM-аудіо + частоту дискретизації. Plugin мають виконувати ресемплінг/кодування для провайдерів.
-- `listVoices` є необов’язковим залежно від провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать вендору.
-- Списки голосів можуть містити багатші метадані, як-от locale, стать і теги характеру для засобів вибору, обізнаних про провайдера.
-- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні.
+- Повертає PCM audio buffer + sample rate. Plugin мають виконувати ресемплінг/кодування для провайдерів.
+- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать постачальнику.
+- Списки голосів можуть містити багатші метадані, такі як locale, gender і теги personality для засобів вибору, обізнаних про провайдера.
+- OpenAI і ElevenLabs сьогодні підтримують telephony. Microsoft — ні.
-Plugin також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`.
+Plugin також можуть реєструвати мовленнєвих провайдерів через `api.registerSpeechProvider(...)`.
```ts
api.registerSpeechProvider({
@@ -400,15 +400,15 @@ api.registerSpeechProvider({
Примітки:
-- Політику TTS, fallback і доставку відповіді залишайте в ядрі.
-- Використовуйте провайдерів мовлення для поведінки синтезу, що належить вендору.
-- Застарілий вхід Microsoft `edge` нормалізується до ідентифікатора провайдера `microsoft`.
-- Бажана модель власності — орієнтована на компанію: один plugin вендора може володіти
- текстовими, голосовими, графічними та майбутніми медіапровайдерами, коли OpenClaw додаватиме ці
+- Зберігайте політику TTS, резервний шлях і доставку відповіді в ядрі.
+- Використовуйте мовленнєвих провайдерів для поведінки синтезу, що належить постачальнику.
+- Застаріле значення вводу Microsoft `edge` нормалізується до id провайдера `microsoft`.
+- Бажана модель володіння орієнтована на компанію: один Plugin постачальника може володіти
+ текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами в міру того, як OpenClaw додає ці
контракти можливостей.
-Для розуміння зображень/аудіо/відео plugin реєструють один типізований
-провайдер media-understanding замість загального контейнера ключ/значення:
+Для розуміння зображень/аудіо/відео Plugin реєструють одного типізованого
+провайдера розуміння медіа замість загальної сумки key/value:
```ts
api.registerMediaUnderstandingProvider({
@@ -422,16 +422,16 @@ api.registerMediaUnderstandingProvider({
Примітки:
-- Оркестрацію, fallback, конфігурацію та прив’язку каналів залишайте в ядрі.
-- Поведінку вендора залишайте в plugin провайдера.
+- Зберігайте оркестрацію, резервний шлях, конфігурацію та прив’язку каналів у ядрі.
+- Зберігайте поведінку постачальника в Plugin провайдера.
- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові
- поля результату, нові необов’язкові можливості.
-- Генерація відео вже дотримується тієї ж схеми:
+ поля результатів, нові необов’язкові можливості.
+- Генерація відео вже дотримується того самого шаблону:
- ядро володіє контрактом можливості та допоміжним засобом середовища виконання
- - plugin вендора реєструють `api.registerVideoGenerationProvider(...)`
- - plugin функцій/каналів споживають `api.runtime.videoGeneration.*`
+ - Plugin постачальників реєструють `api.registerVideoGenerationProvider(...)`
+ - Plugin можливостей/каналів споживають `api.runtime.videoGeneration.*`
-Для допоміжних засобів середовища виконання media-understanding plugin можуть викликати:
+Для допоміжних засобів середовища виконання розуміння медіа Plugin можуть викликати:
```ts
const image = await api.runtime.mediaUnderstanding.describeImageFile({
@@ -446,27 +446,27 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({
});
```
-Для транскрибування аудіо plugin можуть використовувати або середовище виконання media-understanding,
-або старий псевдонім STT:
+Для транскрибування аудіо Plugin можуть використовувати або середовище виконання розуміння медіа,
+або старіший псевдонім 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.*` — це бажана спільна поверхня для
+- `api.runtime.mediaUnderstanding.*` є бажаною спільною поверхнею для
розуміння зображень/аудіо/відео.
-- Використовує аудіоконфігурацію media-understanding ядра (`tools.media.audio`) і порядок fallback провайдера.
-- Повертає `{ text: undefined }`, коли вихід транскрибування не створено (наприклад, вхід пропущено/не підтримується).
-- `api.runtime.stt.transcribeAudioFile(...)` залишається як псевдонім сумісності.
+- Використовує конфігурацію аудіо розуміння медіа ядра (`tools.media.audio`) і порядок резервних провайдерів.
+- Повертає `{ text: undefined }`, коли вивід транскрибування не створено (наприклад, для пропущеного/непідтримуваного вводу).
+- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності.
-Plugin також можуть запускати фонові запуски субагента через `api.runtime.subagent`:
+Plugin також можуть запускати фонові виконання subagent через `api.runtime.subagent`:
```ts
const result = await api.runtime.subagent.run({
@@ -482,12 +482,12 @@ const result = await api.runtime.subagent.run({
- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії.
- OpenClaw враховує ці поля перевизначення лише для довірених викликачів.
-- Для fallback-запусків, що належать plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`.
-- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugin конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі.
-- Запуски субагента від недовірених plugin усе ще працюють, але запити на перевизначення відхиляються замість тихого переходу на fallback.
+- Для резервних запусків, що належать Plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`.
+- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені Plugin конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль.
+- Запуски subagent для недовірених Plugin також працюють, але запити на перевизначення відхиляються, а не тихо переходять на резервний шлях.
-Для вебпошуку plugin можуть використовувати спільний допоміжний засіб середовища виконання замість
-звернення до прив’язки інструмента агента:
+Для вебпошуку Plugin можуть використовувати спільний допоміжний засіб середовища виконання замість
+звернення до прив’язки інструментів агента:
```ts
const providers = api.runtime.webSearch.listProviders({
@@ -508,9 +508,9 @@ Plugin також можуть реєструвати провайдерів в
Примітки:
-- Вибір провайдера, визначення облікових даних і спільну семантику запитів залишайте в ядрі.
-- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для вендора.
-- `api.runtime.webSearch.*` — це бажана спільна поверхня для plugin функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента.
+- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у ядрі.
+- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для постачальника.
+- `api.runtime.webSearch.*` є бажаною спільною поверхнею для Plugin можливостей/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструментів агента.
### `api.runtime.imageGeneration`
@@ -525,8 +525,8 @@ const providers = api.runtime.imageGeneration.listProviders({
});
```
-- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень.
-- `listProviders(...)`: перелічує доступних провайдерів генерації зображень і їхні можливості.
+- `generate(...)`: згенерувати зображення, використовуючи налаштований ланцюжок провайдерів генерації зображень.
+- `listProviders(...)`: вивести список доступних провайдерів генерації зображень і їхніх можливостей.
## HTTP-маршрути Gateway
@@ -548,123 +548,124 @@ api.registerHttpRoute({
Поля маршруту:
- `path`: шлях маршруту під HTTP-сервером gateway.
-- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайний auth Gateway, або `"plugin"` для auth/перевірки Webhook, якими керує plugin.
-- `match`: необов’язкове поле. `"exact"` (типово) або `"prefix"`.
-- `replaceExisting`: необов’язкове поле. Дозволяє тому самому plugin замінити власну наявну реєстрацію маршруту.
-- `handler`: поверніть `true`, коли маршрут обробив запит.
+- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайний auth Gateway, або `"plugin"` для auth/webhook verification, якими керує Plugin.
+- `match`: необов’язкове поле. `"exact"` (типове значення) або `"prefix"`.
+- `replaceExisting`: необов’язкове поле. Дозволяє тому самому Plugin замінити власну наявну реєстрацію маршруту.
+- `handler`: повертайте `true`, коли маршрут обробив запит.
Примітки:
-- `api.registerHttpHandler(...)` було видалено, і воно спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`.
-- Маршрути plugin мають явно оголошувати `auth`.
-- Конфлікти точного `path + match` відхиляються, якщо не встановлено `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin.
-- Маршрути, що перекриваються та мають різні рівні `auth`, відхиляються. Ланцюжки fallthrough для `exact`/`prefix` тримайте лише в межах одного рівня auth.
-- Маршрути `auth: "plugin"` **не** отримують автоматично операторські області середовища виконання. Вони призначені для Webhook/перевірки підпису, якими керує plugin, а не для привілейованих допоміжних викликів Gateway.
-- Маршрути `auth: "gateway"` виконуються в межах області середовища виконання запиту Gateway, але ця область навмисно консервативна:
- - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області середовища виконання маршруту plugin на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes`
- - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній
- - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту plugin з ідентичністю, область середовища виконання повертається до `operator.write`
-- Практичне правило: не припускайте, що маршрут plugin з gateway-auth є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`.
+- `api.registerHttpHandler(...)` було видалено і воно спричинить помилку завантаження Plugin. Натомість використовуйте `api.registerHttpRoute(...)`.
+- Маршрути Plugin повинні явно оголошувати `auth`.
+- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один Plugin не може замінити маршрут іншого Plugin.
+- Маршрути, що перекриваються, з різними рівнями `auth` відхиляються. Залишайте ланцюги переходу `exact`/`prefix` лише в межах одного рівня auth.
+- Маршрути `auth: "plugin"` **не** отримують автоматично області runtime оператора. Вони призначені для webhook/signature verification, якими керує Plugin, а не для привілейованих допоміжних викликів Gateway.
+- Маршрути `auth: "gateway"` працюють усередині області runtime запиту Gateway, але ця область навмисно консервативна:
+ - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області runtime маршрутів Plugin зафіксованими на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes`
+ - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` у приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній
+ - якщо `x-openclaw-scopes` відсутній у таких запитах маршрутів Plugin з ідентичністю, область runtime повертається до `operator.write`
+- Практичне правило: не припускайте, що маршрут Plugin з gateway-auth є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`.
## Шляхи імпорту Plugin SDK
Використовуйте вузькі підшляхи SDK замість монолітного кореневого
-barrel `openclaw/plugin-sdk`, коли створюєте нові plugin. Основні підшляхи:
+barrel `openclaw/plugin-sdk` під час створення нових Plugin. Основні підшляхи:
-| Підшлях | Призначення |
-| ---------------------------------- | -------------------------------------------------- |
-| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації plugin |
-| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/побудови каналу |
-| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella contract |
-| `openclaw/plugin-sdk/config-schema` | Коренева схема Zod для `openclaw.json` (`OpenClawSchema`) |
+| Підшлях | Призначення |
+| ----------------------------------- | -------------------------------------------------- |
+| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin |
+| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/побудови каналу |
+| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella contract |
+| `openclaw/plugin-sdk/config-schema` | Коренева Zod-схема `openclaw.json` (`OpenClawSchema`) |
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. Див. [Plugin каналів](/uk/plugins/sdk-channel-plugins).
+`channel-targets` і `channel-actions`. Поведінка схвалення має консолідуватися
+навколо одного контракту `approvalCapability`, а не змішуватися між
+непов’язаними полями Plugin. Див. [Plugin каналів](/uk/plugins/sdk-channel-plugins).
-Допоміжні засоби середовища виконання та конфігурації розміщуються у відповідних підшляхах
-`*-runtime` (`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`,
+Допоміжні засоби середовища виконання й конфігурації розміщено у відповідних підшляхах
+`*-runtime`
+(`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`,
`lazy-runtime`, `directory-runtime`, `text-runtime`, `runtime-store` тощо).
`openclaw/plugin-sdk/channel-runtime` застарів — це shim сумісності для
-старіших plugin. Новий код має імпортувати вужчі загальні примітиви.
+старіших Plugin. Новий код має імпортувати вужчі загальні примітиви.
-Внутрішні для репозиторію точки входу (для кореня кожного пакунка вбудованого plugin):
+Внутрішні точки входу репозиторію (для кореня пакета кожного вбудованого Plugin):
-- `index.js` — точка входу вбудованого plugin
+- `index.js` — точка входу вбудованого Plugin
- `api.js` — barrel допоміжних засобів/типів
- `runtime-api.js` — barrel лише для середовища виконання
-- `setup-entry.js` — точка входу plugin налаштування
+- `setup-entry.js` — точка входу Plugin налаштування
-Зовнішні plugin повинні імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи
-не імпортуйте `src/*` іншого пакунка plugin з ядра або з іншого plugin.
-Точки входу, завантажені через facade, віддають перевагу активному знімку конфігурації середовища виконання, якщо він існує,
-а потім повертаються до визначеного файлу конфігурації на диску.
+Зовнішні Plugin мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи
+не імпортуйте `src/*` іншого пакета Plugin із ядра або з іншого Plugin.
+Точки входу, завантажені через facade, надають перевагу активному знімку конфігурації середовища виконання, якщо він існує,
+а інакше повертаються до визначеного файла конфігурації на диску.
-Підшляхи, специфічні для можливостей, як-от `image-generation`, `media-understanding`
-і `speech`, існують, оскільки вбудовані plugin використовують їх уже сьогодні. Вони не є
-автоматично зовнішніми контрактами, замороженими на довгий термін — перевіряйте відповідну
-довідкову сторінку SDK, коли покладаєтеся на них.
+Підшляхи, специфічні для можливостей, такі як `image-generation`, `media-understanding`
+і `speech`, існують, бо вбудовані Plugin використовують їх уже сьогодні. Вони не є
+автоматично довгостроково замороженими зовнішніми контрактами — перевіряйте відповідну сторінку
+довідника SDK, коли покладаєтеся на них.
## Схеми інструментів повідомлень
-Plugin повинні володіти внесками схем `describeMessageTool(...)`, специфічними для каналу,
-для немеседжевих примітивів, таких як реакції, прочитання та опитування.
+Plugin мають володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу,
+для немеседжевих примітивів, таких як reactions, reads і polls.
Спільне представлення надсилання має використовувати загальний контракт `MessagePresentation`
-замість native-полів кнопок, компонентів, блоків або карток, специфічних для провайдера.
+замість нативних для провайдера полів button, component, block або card.
Див. [Message Presentation](/uk/plugins/message-presentation), щоб ознайомитися з контрактом,
-правилами fallback, мапінгом провайдерів і контрольним списком для авторів plugin.
+правилами резервного шляху, зіставленням провайдерів і контрольним списком для авторів Plugin.
-Plugin, здатні надсилати, оголошують, що вони можуть рендерити, через можливості повідомлень:
+Plugin, що підтримують надсилання, оголошують, що саме вони можуть відображати, через можливості повідомлень:
-- `presentation` для блоків семантичного представлення (`text`, `context`, `divider`, `buttons`, `select`)
-- `delivery-pin` для запитів на закріплену доставку
+- `presentation` для семантичних блоків представлення (`text`, `context`, `divider`, `buttons`, `select`)
+- `delivery-pin` для запитів закріпленої доставки
-Ядро вирішує, чи рендерити представлення native-способом, чи деградувати його до тексту.
-Не відкривайте native-обхідні шляхи UI, специфічні для провайдера, із загального
-інструмента повідомлень. Застарілі допоміжні засоби SDK для старих native-схем і надалі експортуються для наявних
-сторонніх plugin, але нові plugin не повинні їх використовувати.
+Ядро вирішує, чи відображати представлення нативно, чи деградувати його до тексту.
+Не відкривайте шляхи обходу до нативного UI провайдера з загального інструмента повідомлень.
+Застарілі допоміжні засоби SDK для старих нативних схем усе ще експортуються для наявних
+сторонніх Plugin, але нові Plugin не повинні їх використовувати.
## Визначення цілі каналу
-Plugin каналів повинні володіти семантикою цілей, специфічною для каналу. Залишайте спільний
-вихідний host загальним і використовуйте поверхню адаптера повідомлень для правил провайдера:
+Plugin каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний
+вихідний хост загальним і використовуйте поверхню messaging adapter для правил провайдера:
-- `messaging.inferTargetChatType({ to })` визначає, чи слід нормалізовану ціль
- трактувати як `direct`, `group` або `channel` до пошуку в каталозі.
+- `messaging.inferTargetChatType({ to })` визначає, чи нормалізовану ціль
+ слід трактувати як `direct`, `group` або `channel` до пошуку в каталозі.
- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи
- слід для введення відразу переходити до визначення в стилі id, а не до пошуку в каталозі.
-- `messaging.targetResolver.resolveTarget(...)` — це резервний шлях plugin, коли
+ слід вводу одразу переходити до визначення як id-подібного значення замість пошуку в каталозі.
+- `messaging.targetResolver.resolveTarget(...)` — це резервний шлях Plugin, коли
ядру потрібне остаточне визначення, що належить провайдеру, після нормалізації або після
- промаху в каталозі.
-- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, специфічного для провайдера,
- щойно ціль визначено.
+ відсутності збігу в каталозі.
+- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту
+ вихідної сесії, специфічною для провайдера, щойно ціль визначено.
-Рекомендований поділ:
+Рекомендоване розділення:
-- Використовуйте `inferTargetChatType` для рішень за категоріями, які мають відбуватися до
- пошуку серед peer/group.
-- Використовуйте `looksLikeId` для перевірок на кшталт «трактувати це як явний/native target id».
+- Використовуйте `inferTargetChatType` для категоріальних рішень, які мають відбуватися до
+ пошуку peer/group.
+- Використовуйте `looksLikeId` для перевірок на кшталт «трактувати це як явний/нативний id цілі».
- Використовуйте `resolveTarget` для резервної нормалізації, специфічної для провайдера, а не для
широкого пошуку в каталозі.
-- Зберігайте native ids провайдера, як-от chat ids, thread ids, JIDs, handles і room
- ids, усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK.
+- Зберігайте нативні id провайдера, такі як chat id, thread id, JID, handle і room
+ id, усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK.
## Каталоги на основі конфігурації
-Plugin, які виводять записи каталогу з конфігурації, повинні залишати цю логіку в
-plugin і повторно використовувати спільні допоміжні засоби з
+Plugin, які формують записи каталогу з конфігурації, мають тримати цю логіку в
+Plugin і повторно використовувати спільні допоміжні засоби з
`openclaw/plugin-sdk/directory-runtime`.
Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, наприклад:
-- DM peers на основі allowlist
+- DM peers, що керуються allowlist
- налаштовані мапи channel/group
- статичні резервні каталоги в межах облікового запису
@@ -675,12 +676,12 @@ plugin і повторно використовувати спільні доп
- допоміжні засоби дедуплікації/нормалізації
- побудову `ChannelDirectoryEntry[]`
-Перевірка облікового запису та нормалізація id, специфічні для каналу, мають залишатися
-в реалізації plugin.
+Інспекція облікового запису й нормалізація id, специфічні для каналу, мають залишатися в
+реалізації Plugin.
## Каталоги провайдерів
-Plugin провайдера можуть визначати каталоги моделей для inference за допомогою
+Plugin провайдерів можуть визначати каталоги моделей для inference за допомогою
`registerProvider({ catalog: { run(...) { ... } } })`.
`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в
@@ -689,38 +690,38 @@ Plugin провайдера можуть визначати каталоги м
- `{ provider }` для одного запису провайдера
- `{ providers }` для кількох записів провайдера
-Використовуйте `catalog`, коли plugin володіє model ids, специфічними для провайдера, типовими
-значеннями base URL або метаданими моделей, захищеними auth.
+Використовуйте `catalog`, коли Plugin володіє model id, специфічними для провайдера, типовими
+значеннями base URL або метаданими моделей, що залежать від auth.
-`catalog.order` керує тим, коли каталог plugin об’єднується відносно
-вбудованих неявних провайдерів OpenClaw:
+`catalog.order` керує тим, коли каталог Plugin зливається відносно вбудованих
+неявних провайдерів OpenClaw:
-- `simple`: звичайні провайдери на основі API-ключа або env
-- `profile`: провайдери, що з’являються, коли існують профілі auth
+- `simple`: прості провайдери на основі API-ключа або env
+- `profile`: провайдери, які з’являються за наявності профілів auth
- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдера
-- `late`: останній прохід після інших неявних провайдерів
+- `late`: останній прохід, після інших неявних провайдерів
-Пізніші провайдери перемагають у разі конфлікту ключів, тому plugin можуть навмисно
-перевизначати вбудований запис провайдера з тим самим ідентифікатором провайдера.
+Пізніші провайдери перемагають у разі колізії ключів, тож Plugin можуть навмисно перевизначати
+вбудований запис провайдера з тим самим id провайдера.
Сумісність:
- `discovery` усе ще працює як застарілий псевдонім
- якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog`
-## Інспекція каналу лише для читання
+## Лише для читання: інспекція каналу
-Якщо ваш plugin реєструє канал, віддавайте перевагу реалізації
-`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`.
+Якщо ваш Plugin реєструє канал, надавайте перевагу реалізації
+`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`.
Чому:
- `resolveAccount(...)` — це шлях середовища виконання. Він може припускати, що облікові дані
- повністю матеріалізовані, і швидко завершуватися помилкою, коли потрібні секрети відсутні.
-- Шляхи команд лише для читання, як-от `openclaw status`, `openclaw status --all`,
- `openclaw channels status`, `openclaw channels resolve` і потоки відновлення doctor/config,
- не повинні вимагати матеріалізації облікових даних середовища виконання лише для
- опису конфігурації.
+ повністю матеріалізовані, і швидко завершуватися помилкою, коли потрібних секретів бракує.
+- Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`,
+ `openclaw channels status`, `openclaw channels resolve` і потоки
+ repair для doctor/config не повинні вимагати матеріалізації облікових даних середовища виконання лише для того,
+ щоб описати конфігурацію.
Рекомендована поведінка `inspectAccount(...)`:
@@ -731,15 +732,17 @@ Plugin провайдера можуть визначати каталоги м
- `botTokenSource`, `botTokenStatus`
- `appTokenSource`, `appTokenStatus`
- `signingSecretSource`, `signingSecretStatus`
-- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі тільки читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела).
+- Вам не потрібно повертати сирі значення токенів лише для звіту про доступність
+ лише для читання. Повернути `tokenStatus: "available"` (і відповідне поле джерела)
+ достатньо для команд у стилі status.
- Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але
вони недоступні в поточному шляху команди.
-Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано.
+Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або помилкового повідомлення, що обліковий запис не налаштовано.
## Пакетні набори
-Каталог plugin може містити `package.json` із `openclaw.extensions`:
+Каталог Plugin може містити `package.json` з `openclaw.extensions`:
```json
{
@@ -751,45 +754,44 @@ Plugin провайдера можуть визначати каталоги м
}
```
-Кожен запис стає plugin. Якщо пакетний набір містить кілька extensions, ідентифікатор plugin
+Кожен запис стає Plugin. Якщо набір містить кілька extensions, id Plugin
стає `name/`.
-Якщо ваш plugin імпортує npm-залежності, установіть їх у цьому каталозі, щоб
+Якщо ваш Plugin імпортує npm-залежності, встановіть їх у цьому каталозі, щоб
`node_modules` був доступний (`npm install` / `pnpm install`).
-Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу plugin
-після визначення symlink. Записи, що виходять за межі каталогу пакунка,
+Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу Plugin
+після визначення symlink. Записи, що виходять за межі каталогу пакета,
відхиляються.
-Примітка щодо безпеки: `openclaw plugins install` установлює залежності plugin за допомогою
-`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей у середовищі виконання). Зберігайте дерева залежностей plugin
-«чистими JS/TS» й уникайте пакунків, які потребують збирання через `postinstall`.
+Примітка щодо безпеки: `openclaw plugins install` встановлює залежності Plugin за допомогою
+`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей у середовищі виконання). Тримайте дерева залежностей Plugin «чистими JS/TS» і уникайте пакетів, які вимагають збірок `postinstall`.
Необов’язково: `openclaw.setupEntry` може вказувати на полегшений модуль лише для налаштування.
-Коли OpenClaw потребує поверхонь налаштування для вимкненого plugin каналу, або
-коли plugin каналу ввімкнено, але ще не налаштовано, він завантажує `setupEntry`
-замість повної точки входу plugin. Це робить запуск і налаштування легшими,
-коли основна точка входу plugin також підключає інструменти, хуки чи інший код,
-призначений лише для середовища виконання.
+Коли OpenClaw потребує поверхонь налаштування для вимкненого Plugin каналу, або
+коли Plugin каналу ввімкнено, але він усе ще не налаштований, він завантажує `setupEntry`
+замість повної точки входу Plugin. Це робить запуск і налаштування легшими,
+коли основна точка входу Plugin також підключає інструменти, хуки або інший код
+лише для середовища виконання.
Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`
-може перевести plugin каналу на той самий шлях `setupEntry` під час
-фази запуску gateway до `listen`, навіть якщо канал уже налаштовано.
+може підключити Plugin каналу до того самого шляху `setupEntry` під час
+передслухового етапу запуску gateway, навіть якщо канал уже налаштований.
Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати
-до того, як gateway почне слухати. На практиці це означає, що запис налаштування
-має зареєструвати кожну можливість, що належить каналу, від якої залежить запуск, наприклад:
+до того, як gateway почне слухати. На практиці це означає, що точка входу налаштування
+має реєструвати кожну можливість, що належить каналу та від якої залежить запуск, наприклад:
- саму реєстрацію каналу
- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне слухати
-- будь-які методи gateway, інструменти чи служби, які мають існувати впродовж того самого вікна
+- будь-які методи gateway, інструменти або служби, які мають існувати в це саме вікно
Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте
-цей прапорець. Залиште plugin на типовій поведінці й дозвольте OpenClaw завантажити
+цей прапорець. Залиште Plugin на типовій поведінці й дозвольте OpenClaw завантажити
повну точку входу під час запуску.
-Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, з якими ядро
-може консультуватися до завантаження повного середовища виконання каналу. Поточна поверхня
+Вбудовані канали також можуть публікувати допоміжні засоби контрактної поверхні лише для налаштування, з якими ядро
+може звірятися до завантаження повного середовища виконання каналу. Поточна поверхня
просування налаштування така:
- `singleAccountKeysToMove`
@@ -797,20 +799,20 @@ Plugin провайдера можуть визначати каталоги м
- `resolveSingleAccountPromotionTarget(...)`
Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію каналу з одним обліковим записом
-у `channels..accounts.*` без завантаження повної точки входу plugin.
-Matrix — поточний вбудований приклад: він переносить лише ключі auth/bootstrap до
-іменованого просунутого облікового запису, коли іменовані облікові записи вже існують, і може
-зберігати налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати
+у `channels..accounts.*` без завантаження повної точки входу Plugin.
+Matrix — поточний вбудований приклад: він переміщує лише ключі auth/bootstrap у
+іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може зберегти
+налаштований неканонічний ключ default-account замість того, щоб завжди створювати
`accounts.default`.
-Ці адаптери патчів налаштування підтримують ледаче виявлення поверхні контракту вбудованого коду. Час
-імпорту залишається малим; поверхня просування завантажується лише під час першого використання, замість
+Ці адаптери латок налаштування зберігають ліниве виявлення контрактної поверхні вбудованих компонентів. Час
+імпорту залишається легким; поверхня просування завантажується лише за першої потреби, замість
повторного входу в запуск вбудованого каналу під час імпорту модуля.
-Коли ці поверхні запуску включають методи Gateway RPC, зберігайте їх у
-префіксі, специфічному для plugin. Простори імен адміністратора ядра (`config.*`,
+Коли ці поверхні запуску включають методи Gateway RPC, тримайте їх на
+префіксі, специфічному для Plugin. Простори імен адміністратора ядра (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються
-як `operator.admin`, навіть якщо plugin запитує вужчу область.
+як `operator.admin`, навіть якщо Plugin запитує вужчу область.
Приклад:
@@ -827,10 +829,10 @@ Matrix — поточний вбудований приклад: він пере
}
```
-### Метадані каталогу каналу
+### Метадані каталогу каналів
Plugin каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і
-підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити даних каталогу.
+підказки встановлення через `openclaw.install`. Це дозволяє ядру залишатися без даних каталогу.
Приклад:
@@ -845,7 +847,7 @@ Plugin каналів можуть оголошувати метадані на
"selectionLabel": "Nextcloud Talk (self-hosted)",
"docsPath": "/channels/nextcloud-talk",
"docsLabel": "nextcloud-talk",
- "blurb": "Self-hosted чат через Webhook-ботів Nextcloud Talk.",
+ "blurb": "Самостійно розміщений чат через webhook-ботів Nextcloud Talk.",
"order": 65,
"aliases": ["nc-talk", "nc"]
},
@@ -858,62 +860,64 @@ Plugin каналів можуть оголошувати метадані на
}
```
-Корисні поля `openclaw.channel` понад мінімальний приклад:
+Корисні поля `openclaw.channel`, окрім мінімального прикладу:
- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/стану
- `docsLabel`: перевизначення тексту посилання для посилання на документацію
-- `preferOver`: ідентифікатори plugin/каналів нижчого пріоритету, які цей запис каталогу має випереджати
+- `preferOver`: id Plugin/каналів нижчого пріоритету, які цей запис каталогу має випереджати
- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом для поверхонь вибору
-- `markdownCapable`: позначає канал як здатний працювати з markdown для рішень щодо вихідного форматування
+- `markdownCapable`: позначає канал як здатний до markdown для рішень щодо вихідного форматування
- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false`
- `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено `false`
- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації
-- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure`
+- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure`
- `quickstartAllowFrom`: підключає канал до стандартного потоку quickstart `allowFrom`
-- `forceAccountBinding`: вимагає явного прив’язування облікового запису, навіть коли існує лише один обліковий запис
-- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення цілей announce
+- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть якщо існує лише один обліковий запис
+- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення announce target
-OpenClaw також може об’єднувати **зовнішні каталоги каналів** (наприклад, експорт
-реєстру MPM). Помістіть JSON-файл в один із таких шляхів:
+OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт
+реєстру MPM). Помістіть JSON-файл в одне з таких місць:
- `~/.openclaw/mpm/plugins.json`
- `~/.openclaw/mpm/catalog.json`
- `~/.openclaw/plugins/catalog.json`
Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на
-один чи кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл має
+один або кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл має
містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`.
Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів відкривають
нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Ці
-нормалізовані факти визначають, чи є npm spec точною версією чи плаваючим
-селектором, чи присутні очікувані метадані цілісності, і чи доступний також
-локальний шлях джерела. Вони також попереджають, коли `defaultChoice` є недійсним
-або вказує на джерело, яке недоступне. Споживачі повинні трактувати
-`installSource` як додаткове необов’язкове поле, щоб старі записи, створені вручну, і
-shim сумісності не мусили синтезувати його. Це дозволяє онбордингу та
-діагностиці пояснювати стан площини джерела без імпорту середовища виконання plugin.
+нормалізовані факти визначають, чи є npm spec точною версією або плаваючим
+селектором, чи присутні очікувані метадані цілісності, а також чи доступний
+локальний вихідний шлях. Вони також попереджають, коли `defaultChoice` недійсний
+або вказує на недоступне джерело, і коли метадані цілісності npm присутні
+без дійсного npm-джерела. Споживачі мають трактувати `installSource` як
+адитивне необов’язкове поле, щоб старіші вручну зібрані записи й shim сумісності
+не мусили його синтезувати. Це дозволяє онбордингу та діагностиці пояснювати
+стан площини джерел без імпорту середовища виконання Plugin.
-Офіційні зовнішні записи npm мають віддавати перевагу точному `npmSpec` разом із
-`expectedIntegrity`. Прості назви пакунків і dist-tag все ще працюють для
-сумісності, але вони показують попередження площини джерела, щоб каталог міг рухатися
-в бік pin-встановлень із перевіркою цілісності без ламання наявних plugin.
-Коли онбординг установлює з локального шляху каталогу, він записує запис
-`plugins.installs` із `source: "path"` і `sourcePath`, відносним до workspace,
+Офіційні зовнішні npm-записи мають надавати перевагу точному `npmSpec` плюс
+`expectedIntegrity`. Прості назви пакетів і dist-tag усе ще працюють для
+сумісності, але вони створюють попередження площини джерел, щоб каталог міг
+рухатися до зафіксованих установлень із перевіркою цілісності без порушення
+роботи наявних Plugin. Коли онбординг виконує встановлення з локального шляху каталогу, він записує
+запис `plugins.installs` із `source: "path"` і `sourcePath`, відносним до робочого простору,
коли це можливо. Абсолютний робочий шлях завантаження залишається в
-`plugins.load.paths`; запис встановлення уникає дублювання шляхів локальної робочої станції
-в довгоживучій конфігурації. Це робить локальні встановлення для розробки видимими для
-діагностики площини джерела без додавання другої сирої поверхні розкриття шляхів файлової системи.
+`plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів
+робочої станції в довготривалій конфігурації. Це зберігає видимість локальних
+встановлень для розробки для діагностики площини джерел, не додаючи другої
+поверхні розкриття сирих шляхів файлової системи.
-## Plugin рушія контексту
+## Plugin механізму контексту
-Plugin рушія контексту володіють оркестрацією контексту сесії для ingest, assembly
-і Compaction. Реєструйте їх зі свого plugin через
-`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій за допомогою
+Plugin механізму контексту володіють оркестрацією контексту сесії для ingest, assembly
+і Compaction. Реєструйте їх із вашого Plugin за допомогою
+`api.registerContextEngine(id, factory)`, а потім вибирайте активний механізм через
`plugins.slots.contextEngine`.
-Використовуйте це, коли вашому plugin потрібно замінити або розширити типовий конвеєр
-контексту, а не просто додати пошук у пам’яті чи хуки.
+Використовуйте це, коли вашому Plugin потрібно замінити або розширити типовий
+конвеєр контексту, а не просто додати пошук у пам’яті чи хуки.
```ts
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
@@ -941,7 +945,7 @@ export default function (api) {
}
```
-Якщо ваш рушій **не** володіє алгоритмом Compaction, залишайте `compact()`
+Якщо ваш механізм **не** володіє алгоритмом Compaction, залиште `compact()`
реалізованим і явно делегуйте його:
```ts
@@ -979,60 +983,60 @@ export default function (api) {
## Додавання нової можливості
-Коли plugin потребує поведінки, яка не вписується в поточний API, не обходьте
-систему plugin через приватне проникнення всередину. Додайте відсутню можливість.
+Коли Plugin потребує поведінки, яка не вписується в поточний API, не обходьте
+систему Plugin через приватне проникнення. Додайте відсутню можливість.
Рекомендована послідовність:
1. визначте контракт ядра
- Вирішіть, якою спільною поведінкою має володіти ядро: policy, fallback, злиття config,
- lifecycle, семантика для каналів і форма допоміжних засобів середовища виконання.
-2. додайте типізовані поверхні реєстрації plugin/середовища виконання
- Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною
+ Вирішіть, якою спільною поведінкою має володіти ядро: політика, резервний шлях, злиття конфігурації,
+ життєвий цикл, семантика для каналів і форма допоміжного засобу середовища виконання.
+2. додайте типізовані поверхні реєстрації/середовища виконання Plugin
+ Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною
типізованою поверхнею можливості.
-3. підключіть ядро + споживачів каналів/функцій
- Канали й plugin функцій повинні споживати нову можливість через ядро,
- а не імпортувати реалізацію вендора безпосередньо.
-4. зареєструйте реалізації вендора
- Потім plugin вендора реєструють свої бекенди для цієї можливості.
+3. підключіть ядро + споживачів каналів/можливостей
+ Канали і Plugin можливостей мають споживати нову можливість через ядро,
+ а не імпортувати реалізацію постачальника безпосередньо.
+4. зареєструйте реалізації постачальників
+ Потім Plugin постачальників реєструють свої backend проти цієї можливості.
5. додайте покриття контракту
- Додайте тести, щоб форма власності та реєстрації з часом залишалася явною.
+ Додайте тести, щоб володіння і форма реєстрації з часом залишалися явними.
-Саме так OpenClaw зберігає власну позицію, не стаючи жорстко прив’язаним до
-світогляду одного провайдера. Див. [Кулінарна книга можливостей](/uk/plugins/architecture),
-щоб ознайомитися з конкретним списком файлів і готовим прикладом.
+Саме так OpenClaw залишається виразним, не стаючи жорстко закодованим під
+світогляд одного провайдера. Див. [Збірник рецептів можливостей](/uk/plugins/architecture),
+щоб переглянути конкретний контрольний список файлів і робочий приклад.
-### Контрольний список можливості
+### Контрольний список можливостей
-Коли ви додаєте нову можливість, реалізація зазвичай має разом торкатися таких
-поверхонь:
+Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих
+поверхонь разом:
- типи контракту ядра в `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/`
+- поверхня реєстрації API Plugin у `src/plugins/types.ts`
+- підключення реєстру Plugin у `src/plugins/registry.ts`
+- відкриття середовища виконання Plugin у `src/plugins/runtime/*`, коли Plugin можливостей/каналів
+ мають це споживати
+- допоміжні засоби захоплення/тестування в `src/test-utils/plugin-registration.ts`
+- перевірки володіння/контракту в `src/plugins/contracts/registry.ts`
+- документація для операторів/Plugin у `docs/`
-Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість
+Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість
ще не повністю інтегрована.
### Шаблон можливості
-Мінімальна схема:
+Мінімальний шаблон:
```ts
-// контракт ядра
+// core contract
export type VideoGenerationProviderPlugin = {
id: string;
label: string;
generateVideo: (req: VideoGenerationRequest) => Promise;
};
-// API plugin
+// plugin API
api.registerVideoGenerationProvider({
id: "openai",
label: "OpenAI",
@@ -1041,14 +1045,14 @@ api.registerVideoGenerationProvider({
},
});
-// спільний допоміжний засіб середовища виконання для plugin функцій/каналів
+// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
prompt: "Show the robot walking through the lab.",
cfg,
});
```
-Схема тесту контракту:
+Шаблон контрактного тесту:
```ts
expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
@@ -1057,13 +1061,13 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
Це зберігає правило простим:
- ядро володіє контрактом можливості + оркестрацією
-- plugin вендора володіють реалізаціями вендора
-- plugin функцій/каналів споживають допоміжні засоби середовища виконання
-- тести контракту зберігають власність явною
+- Plugin постачальників володіють реалізаціями постачальників
+- Plugin можливостей/каналів споживають допоміжні засоби середовища виконання
+- контрактні тести зберігають явність володіння
-## Пов’язані матеріали
+## Пов’язане
- [Архітектура Plugin](/uk/plugins/architecture) — публічна модель можливостей і форми
- [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths)
- [Налаштування Plugin SDK](/uk/plugins/sdk-setup)
-- [Створення plugin](/uk/plugins/building-plugins)
+- [Створення Plugin](/uk/plugins/building-plugins)
diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md
index 6f88172a3..d1697df49 100644
--- a/docs/uk/plugins/manifest.md
+++ b/docs/uk/plugins/manifest.md
@@ -1,64 +1,65 @@
---
read_when:
- - Ви створюєте Plugin для OpenClaw
- - Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin
+ - Ви створюєте плагін OpenClaw
+ - Вам потрібно надати схему конфігурації плагіна або налагодити помилки валідації плагіна
summary: Вимоги до маніфесту Plugin і схеми JSON (сувора валідація конфігурації)
title: Маніфест Plugin
x-i18n:
- generated_at: "2026-04-24T16:00:11Z"
+ generated_at: "2026-04-24T16:05:24Z"
model: gpt-5.4
provider: openai
- source_hash: 3ad8f4d82624420f97f38ba5f7b1de12dbf88d4cc4fb37a52ae31cbb838ebabf
+ source_hash: 44eca8a54f22735ae657efde088a7951eeb79dfbb48a25d478c7e9a3f699cce0
source_path: plugins/manifest.md
workflow: 15
---
-Ця сторінка призначена лише для **власного маніфесту Plugin OpenClaw**.
+Ця сторінка призначена лише для **власного маніфесту плагіна OpenClaw**.
-Для сумісних макетів пакетів див. [Пакети Plugin](/uk/plugins/bundles).
+Сумісні макети bundle дивіться в [Plugin bundles](/uk/plugins/bundles).
-Сумісні формати пакетів використовують інші файли маніфесту:
+Сумісні формати bundle використовують інші файли маніфесту:
-- Пакет Codex: `.codex-plugin/plugin.json`
-- Пакет Claude: `.claude-plugin/plugin.json` або типовий макет компонента Claude
+- bundle Codex: `.codex-plugin/plugin.json`
+- bundle Claude: `.claude-plugin/plugin.json` або типовий макет компонента Claude
без маніфесту
-- Пакет Cursor: `.cursor-plugin/plugin.json`
+- bundle Cursor: `.cursor-plugin/plugin.json`
-OpenClaw також автоматично виявляє ці макети пакетів, але вони не проходять валідацію
+OpenClaw також автоматично визначає ці макети bundle, але вони не проходять валідацію
за схемою `openclaw.plugin.json`, описаною тут.
-Для сумісних пакетів OpenClaw наразі зчитує метадані пакета разом із оголошеними
-коренями skill, коренями команд Claude, типовими значеннями Claude-пакета з
-`settings.json`, типовими значеннями LSP для Claude-пакета та підтримуваними
-наборами хуків, якщо макет відповідає очікуванням середовища виконання OpenClaw.
+Для сумісних bundle OpenClaw наразі читає метадані bundle разом з оголошеними
+коренями Skills, коренями команд Claude, типовими значеннями Claude bundle `settings.json`,
+типовими значеннями Claude bundle LSP і підтримуваними пакетами хуків, коли макет відповідає
+очікуванням рантайму OpenClaw.
-Кожен власний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у
-**корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації
-**без виконання коду plugin**. Відсутні або недійсні маніфести вважаються
-помилками plugin і блокують валідацію конфігурації.
+Кожен власний плагін OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у
+**корені плагіна**. OpenClaw використовує цей маніфест для валідації конфігурації
+**без виконання коду плагіна**. Відсутні або невалідні маніфести вважаються
+помилками плагіна і блокують валідацію конфігурації.
-Див. повний посібник по системі plugin: [Plugins](/uk/tools/plugin).
+Дивіться повний посібник із системи плагінів: [Plugins](/uk/tools/plugin).
Щодо власної моделі можливостей і поточних рекомендацій із зовнішньої сумісності:
-[Модель можливостей](/uk/plugins/architecture#public-capability-model).
+[Capability model](/uk/plugins/architecture#public-capability-model).
## Що робить цей файл
`openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження коду
-вашого plugin**. Усе нижче має бути достатньо легким для перевірки без запуску
-середовища виконання plugin.
+вашого плагіна**. Усе нижче має бути достатньо легким для перевірки без запуску
+рантайму плагіна.
**Використовуйте його для:**
-- ідентифікації plugin, валідації конфігурації та підказок UI для конфігурації
-- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища provider, варіанти автентифікації)
-- підказок активації для поверхонь control-plane
+- ідентичності плагіна, валідації конфігурації та підказок для UI конфігурації
+- метаданих автентифікації, онбордингу та налаштування (аліас, автоувімкнення, змінні середовища провайдера, варіанти автентифікації)
+- підказок активації для поверхонь control plane
- скороченого володіння сімействами моделей
- статичних знімків володіння можливостями (`contracts`)
- метаданих QA runner, які може перевіряти спільний хост `openclaw qa`
-- метаданих конфігурації, специфічних для channel, що об’єднуються в поверхнях каталогу та валідації
+- метаданих конфігурації, специфічних для каналу, які об’єднуються в поверхні каталогу та валідації
-**Не використовуйте його для:** реєстрації поведінки під час виконання, оголошення
-точок входу коду або метаданих встановлення npm. Це має належати до коду вашого plugin і `package.json`.
+**Не використовуйте його для:** реєстрації поведінки рантайму, оголошення
+точок входу коду або метаданих встановлення npm. Це належить коду вашого плагіна
+та `package.json`.
## Мінімальний приклад
@@ -73,7 +74,7 @@ OpenClaw також автоматично виявляє ці макети па
}
```
-## Розгорнутий приклад
+## Розширений приклад
```json
{
@@ -138,68 +139,68 @@ OpenClaw також автоматично виявляє ці макети па
## Довідник полів верхнього рівня
-| Поле | Обов’язкове | Тип | Що воно означає |
-| ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id` | Так | `string` | Канонічний id plugin. Це id, який використовується в `plugins.entries.`. |
-| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього plugin. |
-| `enabledByDefault` | Ні | `true` | Позначає вбудований plugin як увімкнений за замовчуванням. Пропустіть його або встановіть будь-яке значення, відмінне від `true`, щоб plugin залишався вимкненим за замовчуванням. |
-| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id plugin. |
-| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id provider, які мають автоматично вмикати цей plugin, коли згадуються автентифікація, конфігурація або посилання на моделі. |
-| `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[]` | Метадані хостів endpoint/baseUrl, що належать маніфесту, для маршрутів provider, які ядро повинно класифікувати до завантаження середовища виконання provider. |
-| `cliBackends` | Ні | `string[]` | Id backend CLI, якими володіє цей plugin. Використовується для автоактивації під час запуску на основі явних посилань у конфігурації. |
-| `syntheticAuthRefs` | Ні | `string[]` | Посилання на provider або backend CLI, для яких синтетичний хук автентифікації, що належить plugin, слід перевіряти під час холодного виявлення моделей до завантаження середовища виконання. |
-| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, що належать вбудованому plugin і представляють несекретний локальний стан, OAuth або ambient credential state. |
-| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей plugin і які мають створювати діагностику конфігурації та CLI з урахуванням plugin до завантаження середовища виконання. |
-| `providerAuthEnvVars` | Ні | `Record` | Полегшені метадані змінних середовища автентифікації provider, які OpenClaw може перевіряти без завантаження коду plugin. |
-| `providerAuthAliases` | Ні | `Record` | Id provider, які мають повторно використовувати інший id provider для пошуку автентифікації, наприклад coding provider, що використовує той самий API-ключ базового provider і профілі автентифікації. |
-| `channelEnvVars` | Ні | `Record` | Полегшені метадані змінних середовища channel, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для налаштування channel через env або поверхонь автентифікації, які мають бачити типові помічники запуску/конфігурації. |
-| `providerAuthChoices` | Ні | `object[]` | Полегшені метадані варіантів автентифікації для селекторів онбордингу, вибору preferred provider та простого зв’язування прапорців CLI. |
-| `activation` | Ні | `object` | Полегшені метадані планувальника активації для завантаження, що запускається provider, командою, channel, маршрутом і можливостями. Лише метадані; фактичною поведінкою як і раніше володіє середовище виконання plugin. |
-| `setup` | Ні | `object` | Полегшені дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання plugin. |
-| `qaRunners` | Ні | `object[]` | Полегшені дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання plugin. |
-| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. |
-| `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, заповнювачі та підказки чутливості для полів конфігурації. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------------------------------ | ----------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id` | Так | `string` | Канонічний ідентифікатор плагіна. Саме цей ідентифікатор використовується в `plugins.entries.`. |
+| `configSchema` | Так | `object` | Вбудована схема JSON Schema для конфігурації цього плагіна. |
+| `enabledByDefault` | Ні | `true` | Позначає вбудований плагін як увімкнений за замовчуванням. Не вказуйте його або встановіть будь-яке значення, відмінне від `true`, щоб плагін за замовчуванням залишався вимкненим. |
+| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора плагіна. |
+| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей плагін, коли автентифікація, конфігурація або посилання на моделі згадують їх. |
+| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип плагіна, який використовується `plugins.slots.*`. |
+| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей плагін. Використовуються для виявлення та валідації конфігурації. |
+| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей плагін. |
+| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення провайдера, відносний до кореня плагіна, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного рантайму плагіна. |
+| `modelSupport` | Ні | `object` | Скорочені метадані сімейств моделей, якими володіє маніфест, що використовуються для автозавантаження плагіна до запуску рантайму. |
+| `providerEndpoints` | Ні | `object[]` | Метадані хостів endpoint/baseUrl, якими володіє маніфест, для маршрутів провайдерів, які ядро має класифікувати до завантаження рантайму провайдера. |
+| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI, якими володіє цей плагін. Використовуються для автоактивації під час запуску на основі явних посилань у конфігурації. |
+| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або backend CLI, для яких під час холодного виявлення моделей до завантаження рантайму слід перевіряти синтетичний хук автентифікації, що належить плагіну. |
+| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать вбудованому плагіну і представляють несекретний локальний стан, OAuth або ambient credentials. |
+| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей плагін і які мають створювати діагностику конфігурації та CLI з урахуванням плагіна до завантаження рантайму. |
+| `providerAuthEnvVars` | Ні | `Record` | Легковагові метадані змінних середовища автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. |
+| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер кодування, який спільно використовує API key базового провайдера та профілі автентифікації. |
+| `channelEnvVars` | Ні | `Record` | Легковагові метадані змінних середовища каналу, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналів через env або поверхонь автентифікації, які мають бачити загальні помічники запуску/конфігурації. |
+| `providerAuthChoices` | Ні | `object[]` | Легковагові метадані варіантів автентифікації для вибору під час онбордингу, визначення бажаного провайдера та простого зв’язування з прапорцями CLI. |
+| `activation` | Ні | `object` | Легковагові метадані планувальника активації для завантаження, що запускається провайдерами, командами, каналами, маршрутами та можливостями. Лише метадані; фактичною поведінкою все одно володіє рантайм плагіна. |
+| `setup` | Ні | `object` | Легковагові дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження рантайму плагіна. |
+| `qaRunners` | Ні | `object[]` | Легковагові дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження рантайму плагіна. |
+| `contracts` | Ні | `object` | Статичний знімок можливостей вбудованого плагіна для зовнішніх хуків автентифікації, мовлення, транскрибування в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, вебпошуку та володіння інструментами. |
+| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легковагові типові значення для розуміння медіа для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. |
+| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, якими володіє маніфест і які об’єднуються в поверхні виявлення та валідації до завантаження рантайму. |
+| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореня плагіна. |
+| `name` | Ні | `string` | Людинозрозуміла назва плагіна. |
+| `description` | Ні | `string` | Короткий опис, що показується в поверхнях плагіна. |
+| `version` | Ні | `string` | Інформаційна версія плагіна. |
+| `uiHints` | Ні | `Record` | Підписи UI, placeholders і підказки щодо чутливості для полів конфігурації. |
## Довідник `providerAuthChoices`
Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації.
-OpenClaw читає це до завантаження середовища виконання provider.
+OpenClaw читає це до завантаження рантайму провайдера.
-| Поле | Обов’язкове | Тип | Що воно означає |
-| --------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `provider` | Так | `string` | Id provider, до якого належить цей варіант. |
-| `method` | Так | `string` | Id методу автентифікації, до якого слід маршрутизувати. |
-| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, який використовується в потоках онбордингу та CLI. |
-| `choiceLabel` | Ні | `string` | Підпис для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. |
-| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. |
-| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих помічником. |
-| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із селекторів помічника, але все ще дозволяє ручний вибір через CLI. |
-| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів на цей варіант-заміну. |
-| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. |
-| `groupLabel` | Ні | `string` | Підпис цієї групи для користувача. |
-| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
-| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. |
-| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. |
-| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. |
-| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. |
-| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має показуватися цей варіант. Якщо не вказано, типовим значенням є `["text-inference"]`. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. |
+| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід маршрутизувати. |
+| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, що використовується в потоках онбордингу та CLI. |
+| `choiceLabel` | Ні | `string` | Підпис для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. |
+| `choiceHint` | Ні | `string` | Короткий допоміжний текст для списку вибору. |
+| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних списках вибору, керованих асистентом. |
+| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант зі списків вибору асистента, але все ще дозволяє ручний вибір через CLI. |
+| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають переспрямовувати користувачів на цей варіант-заміну. |
+| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. |
+| `groupLabel` | Ні | `string` | Підпис для користувача для цієї групи. |
+| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
+| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. |
+| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. |
+| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. |
+| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. |
+| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. |
## Довідник `commandAliases`
-Використовуйте `commandAliases`, коли plugin володіє назвою команди під час виконання, яку користувачі можуть
-помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw
-використовує ці метадані для діагностики без імпорту коду середовища виконання plugin.
+Використовуйте `commandAliases`, коли плагін володіє назвою команди рантайму, яку користувачі можуть
+помилково додати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw
+використовує ці метадані для діагностики без імпорту коду рантайму плагіна.
```json
{
@@ -213,35 +214,34 @@ OpenClaw читає це до завантаження середовища ви
}
```
-| Поле | Обов’язкове | Тип | Що воно означає |
-| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------- |
-| `name` | Так | `string` | Назва команди, що належить цьому plugin. |
-| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------------ |
+| `name` | Так | `string` | Назва команди, яка належить цьому плагіну. |
+| `kind` | Ні | `"runtime-slash"` | Позначає аліас як chat slash command, а не як кореневу команду CLI. |
| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо вона існує. |
## Довідник `activation`
-Використовуйте `activation`, коли plugin може недорого оголосити, які події control-plane
+Використовуйте `activation`, коли плагін може дешево оголосити, які події control plane
мають включати його в план активації/завантаження.
Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє
-поведінку під час виконання, не замінює `register(...)` і не гарантує, що
-код plugin уже було виконано. Планувальник активації використовує ці поля для
-звуження списку кандидатів plugin перед поверненням до наявних метаданих
-володіння з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`,
+поведінку рантайму, не замінює `register(...)` і не гарантує, що
+код плагіна вже було виконано. Планувальник активації використовує ці поля, щоб
+звузити коло кандидатів на плагіни, перш ніж повертатися до наявних
+метаданих володіння в маніфесті, таких як `providers`, `channels`, `commandAliases`, `setup.providers`,
`contracts.tools` і хуки.
Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте
`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`,
-коли ці поля виражають відповідний зв’язок. Використовуйте `activation` для додаткових підказок
-планувальника, які не можуть бути представлені цими полями володіння.
+коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальника,
+які не можна подати через ці поля володіння.
-Цей блок містить лише метадані. Він не реєструє поведінку під час виконання і
-не замінює `register(...)`, `setupEntry` або інші точки входу runtime/plugin.
-Поточні споживачі використовують його як підказку для звуження перед ширшим
-завантаженням plugin, тому відсутність метаданих активації зазвичай лише впливає на продуктивність;
-це не має змінювати коректність, доки ще існують застарілі fallback-механізми
-володіння з маніфесту.
+Цей блок є лише метаданими. Він не реєструє поведінку рантайму і не
+замінює `register(...)`, `setupEntry` або інші точки входу рантайму/плагіна.
+Поточні споживачі використовують його як підказку для звуження кола кандидатів перед ширшим завантаженням плагінів, тож
+відсутність метаданих активації зазвичай впливає лише на продуктивність; вона не повинна
+змінювати коректність, поки все ще існують застарілі fallback-механізми володіння через маніфест.
```json
{
@@ -255,36 +255,35 @@ OpenClaw читає це до завантаження середовища ви
}
```
-| Поле | Обов’язкове | Тип | Що воно означає |
-| ---------------- | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `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. За можливості надавайте перевагу вужчим полям. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей плагін у плани активації/завантаження. |
+| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей плагін у плани активації/завантаження. |
+| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей плагін у плани активації/завантаження. |
+| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей плагін у плани активації/завантаження. |
+| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, які використовуються плануванням активації control plane. Коли можливо, надавайте перевагу вужчим полям. |
-Поточні активні споживачі:
+Поточні live-споживачі:
-- планування CLI, запущене командою, повертається до застарілих
+- планування CLI, що запускається командою, повертається до застарілих
`commandAliases[].cliCommand` або `commandAliases[].name`
-- планування setup/channel, запущене channel, повертається до застарілого
- володіння `channels[]`, якщо явні метадані активації channel відсутні
-- планування setup/runtime, запущене provider, повертається до застарілого
- володіння `providers[]` і `cliBackends[]` верхнього рівня, якщо явні метадані
- активації provider відсутні
+- планування setup/каналів, що запускається каналом, повертається до застарілого
+ володіння `channels[]`, коли явні метадані активації каналу відсутні
+- планування setup/рантайму, що запускається провайдером, повертається до застарілого
+ володіння `providers[]` і `cliBackends[]` верхнього рівня, коли явні метадані активації провайдера відсутні
-Діагностика планувальника може розрізняти явні підказки активації та fallback
-до володіння з маніфесту. Наприклад, `activation-command-hint` означає, що
+Діагностика планувальника може розрізняти явні підказки активації та fallback до
+володіння через маніфест. Наприклад, `activation-command-hint` означає, що
спрацювало `activation.onCommands`, тоді як `manifest-command-alias` означає, що
-планувальник натомість використав володіння через `commandAliases`. Ці мітки причин
-призначені для діагностики хоста та тестів; авторам plugin слід і надалі оголошувати ті метадані,
+планувальник замість цього використав володіння через `commandAliases`. Ці мітки причин призначені для
+діагностики хоста та тестів; авторам плагінів слід і надалі оголошувати ті метадані,
які найкраще описують володіння.
## Довідник `qaRunners`
-Використовуйте `qaRunners`, коли plugin додає один або кілька транспортних runner
-під спільним коренем `openclaw qa`. Зберігайте ці метадані легкими та статичними; фактичною
-реєстрацією CLI як і раніше володіє середовище виконання plugin через полегшену
+Використовуйте `qaRunners`, коли плагін додає один або кілька транспортних runner під
+спільним коренем `openclaw qa`. Зберігайте ці метадані легковаговими та статичними; фактичною логікою CLI
+все одно володіє рантайм плагіна через легковагову
поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`.
```json
@@ -292,7 +291,7 @@ OpenClaw читає це до завантаження середовища ви
"qaRunners": [
{
"commandName": "matrix",
- "description": "Запустити Docker-backed Matrix live QA lane на одноразовому homeserver"
+ "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
}
]
}
@@ -301,12 +300,12 @@ OpenClaw читає це до завантаження середовища ви
| Поле | Обов’язкове | Тип | Що воно означає |
| ------------- | ----------- | -------- | ------------------------------------------------------------------------- |
| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. |
-| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. |
+| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. |
## Довідник `setup`
-Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні легкі метадані plugin,
-що належать plugin, до завантаження runtime.
+Використовуйте `setup`, коли поверхням setup та онбордингу потрібні легковагові метадані плагіна
+до завантаження рантайму.
```json
{
@@ -325,47 +324,48 @@ OpenClaw читає це до завантаження середовища ви
}
```
-`cliBackends` верхнього рівня залишається чинним і продовжує описувати backend CLI для інференсу.
-`setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків
-control-plane/setup, які мають залишатися лише метаданими.
+`cliBackends` верхнього рівня залишається валідним і надалі описує
+backend виведення CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup,
+для потоків control-plane/setup, які мають залишатися лише на рівні метаданих.
-За наявності `setup.providers` і `setup.cliBackends` є бажаною поверхнею пошуку
-на основі дескрипторів для виявлення setup. Якщо дескриптор лише звужує список
-plugin-кандидатів, а setup усе ще потребує більш багатих runtime-хуків на етапі налаштування,
-встановіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання.
+Коли вони присутні, `setup.providers` і `setup.cliBackends` є пріоритетною
+поверхнею пошуку setup у стилі descriptor-first для виявлення setup. Якщо дескриптор лише
+звужує коло кандидатів на плагін, а setup все ще потребує багатших runtime-хуків часу setup,
+встановіть `requiresRuntime: true` і залиште `setup-api` як
+резервний шлях виконання.
-Оскільки пошук setup може виконувати код `setup-api`, що належить plugin,
-нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися
-унікальними серед виявлених plugin. Неоднозначне володіння завершується без вибору,
-замість того щоб обирати переможця за порядком виявлення.
+Оскільки пошук setup може виконувати код `setup-api`, що належить плагіну,
+нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед
+виявлених плагінів. Неоднозначне володіння завершується закритою відмовою замість вибору
+переможця на основі порядку виявлення.
### Довідник `setup.providers`
| Поле | Обов’язкове | Тип | Що воно означає |
| ------------- | ----------- | ---------- | ---------------------------------------------------------------------------------- |
-| `id` | Так | `string` | Id provider, що відкривається під час setup або онбордингу. Зберігайте нормалізовані id глобально унікальними. |
-| `authMethods` | Ні | `string[]` | Id методів setup/автентифікації, які цей provider підтримує без завантаження повного runtime. |
-| `envVars` | Ні | `string[]` | Змінні середовища, які типові поверхні setup/status можуть перевіряти до завантаження runtime plugin. |
+| `id` | Так | `string` | Ідентифікатор провайдера, який відкривається під час setup або онбордингу. Зберігайте нормалізовані ідентифікатори глобально унікальними. |
+| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей провайдер підтримує без завантаження повного рантайму. |
+| `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні setup/status можуть перевіряти до завантаження рантайму плагіна. |
### Поля `setup`
-| Поле | Обов’язкове | Тип | Що воно означає |
-| ------------------ | ----------- | ---------- | -------------------------------------------------------------------------------------------------------- |
-| `providers` | Ні | `object[]` | Дескриптори setup provider, що відкриваються під час setup та онбордингу. |
-| `cliBackends` | Ні | `string[]` | Id backend для setup, що використовуються для пошуку setup на основі дескрипторів. Зберігайте нормалізовані id глобально унікальними. |
-| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє поверхня setup цього plugin. |
-| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. |
+| Поле | Обов’язкове | Тип | Що воно означає |
+| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------ |
+| `providers` | Ні | `object[]` | Дескриптори setup провайдерів, які відкриваються під час setup та онбордингу. |
+| `cliBackends` | Ні | `string[]` | Ідентифікатори backend часу setup, що використовуються для пошуку setup у стилі descriptor-first. Зберігайте нормалізовані ідентифікатори глобально унікальними. |
+| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього плагіна. |
+| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку дескриптора. |
## Довідник `uiHints`
-`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для рендерингу.
+`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу.
```json
{
"uiHints": {
"apiKey": {
"label": "API key",
- "help": "Used for OpenRouter requests",
+ "help": "Використовується для запитів OpenRouter",
"placeholder": "sk-or-v1-...",
"sensitive": true
}
@@ -373,7 +373,7 @@ plugin-кандидатів, а setup усе ще потребує більш б
}
```
-Кожна підказка для поля може містити:
+Кожна підказка поля може містити:
| Поле | Тип | Що воно означає |
| ------------- | ---------- | -------------------------------------- |
@@ -382,12 +382,12 @@ plugin-кандидатів, а setup усе ще потребує більш б
| `tags` | `string[]` | Необов’язкові теги UI. |
| `advanced` | `boolean` | Позначає поле як розширене. |
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
-| `placeholder` | `string` | Текст-заповнювач для полів форми. |
+| `placeholder` | `string` | Текст placeholder для полів форми. |
## Довідник `contracts`
Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може
-читати без імпорту середовища виконання plugin.
+читати без імпорту рантайму плагіна.
```json
{
@@ -410,37 +410,37 @@ plugin-кандидатів, а setup усе ще потребує більш б
Кожен список є необов’язковим:
-| Поле | Тип | Що воно означає |
-| -------------------------------- | ---------- | --------------------------------------------------------------------- |
-| `embeddedExtensionFactories` | `string[]` | Id вбудованого runtime, для яких вбудований plugin може реєструвати фабрики. |
-| `externalAuthProviders` | `string[]` | Id provider, хуком зовнішнього профілю автентифікації яких володіє цей plugin. |
-| `speechProviders` | `string[]` | Id provider speech, якими володіє цей plugin. |
-| `realtimeTranscriptionProviders` | `string[]` | Id provider realtime-transcription, якими володіє цей plugin. |
-| `realtimeVoiceProviders` | `string[]` | Id provider realtime-voice, якими володіє цей plugin. |
-| `memoryEmbeddingProviders` | `string[]` | Id provider memory embedding, якими володіє цей plugin. |
-| `mediaUnderstandingProviders` | `string[]` | Id provider media-understanding, якими володіє цей plugin. |
-| `imageGenerationProviders` | `string[]` | Id provider image-generation, якими володіє цей plugin. |
-| `videoGenerationProviders` | `string[]` | Id provider video-generation, якими володіє цей plugin. |
-| `webFetchProviders` | `string[]` | Id provider web-fetch, якими володіє цей plugin. |
-| `webSearchProviders` | `string[]` | Id provider web search, якими володіє цей plugin. |
-| `tools` | `string[]` | Назви інструментів агента, якими володіє цей plugin для перевірок вбудованого контракту. |
+| Поле | Тип | Що воно означає |
+| -------------------------------- | ---------- | ------------------------------------------------------------------- |
+| `embeddedExtensionFactories` | `string[]` | Ідентифікатори вбудованого рантайму, для яких вбудований плагін може реєструвати фабрики. |
+| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, чий хук профілю зовнішньої автентифікації належить цьому плагіну. |
+| `speechProviders` | `string[]` | Ідентифікатори провайдерів мовлення, якими володіє цей плагін. |
+| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів транскрибування в реальному часі, якими володіє цей плагін. |
+| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів голосу в реальному часі, якими володіє цей плагін. |
+| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів embedding для пам’яті, якими володіє цей плагін. |
+| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів розуміння медіа, якими володіє цей плагін. |
+| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації зображень, якими володіє цей плагін. |
+| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації відео, якими володіє цей плагін. |
+| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей плагін. |
+| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів вебпошуку, якими володіє цей плагін. |
+| `tools` | `string[]` | Назви інструментів агента, якими володіє цей плагін для перевірок контрактів вбудованих плагінів. |
-Plugin provider, які реалізують `resolveExternalAuthProfiles`, мають оголошувати
-`contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють
-через застарілий сумісний fallback, але він повільніший і
-буде вилучений після завершення вікна міграції.
+Плагіни провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати
+`contracts.externalAuthProviders`. Плагіни без цього оголошення все ще працюють
+через застарілий сумісний fallback, але цей fallback повільніший і
+буде видалений після завершення вікна міграції.
-Вбудовані provider memory embedding мають оголошувати
-`contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони надають, включно з
-вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей контракт
-маніфесту, щоб завантажувати лише plugin-власник до того, як повне середовище виконання Gateway
-зареєструє provider.
+Вбудовані провайдери embedding для пам’яті мають оголошувати
+`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони надають, зокрема
+для вбудованих адаптерів, таких як `local`. Автономні шляхи CLI використовують цей контракт маніфесту,
+щоб завантажувати лише плагін-власник до того, як повний рантайм Gateway
+зареєструє провайдерів.
## Довідник `mediaUnderstandingProviderMetadata`
-Використовуйте `mediaUnderstandingProviderMetadata`, коли provider media-understanding має
-типові моделі, пріоритет fallback для автоматичної автентифікації або власну підтримку документів,
-які потрібні типовим допоміжникам ядра до завантаження runtime. Ключі також мають бути оголошені в
+Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має
+типові моделі, пріоритет fallback для автоавтентифікації або нативну підтримку документів, які
+потрібні загальним помічникам ядра до завантаження рантайму. Ключі також мають бути оголошені в
`contracts.mediaUnderstandingProviders`.
```json
@@ -464,19 +464,19 @@ Plugin provider, які реалізують `resolveExternalAuthProfiles`, ма
}
```
-Кожен запис provider може містити:
+Кожен запис провайдера може містити:
-| Поле | Тип | Що воно означає |
-| ---------------------- | ----------------------------------- | -------------------------------------------------------------------------------- |
-| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей provider. |
-| `defaultModels` | `Record` | Типові відповідності можливість-модель, що використовуються, коли конфігурація не задає модель. |
-| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback provider на основі облікових даних. |
-| `nativeDocumentInputs` | `"pdf"[]` | Власні входи документів, які підтримує provider. |
+| Поле | Тип | Що воно означає |
+| ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- |
+| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості роботи з медіа, які надає цей провайдер. |
+| `defaultModels` | `Record` | Типові відповідності можливостей до моделей, що використовуються, коли в конфігурації не вказано модель. |
+| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback до провайдера на основі облікових даних. |
+| `nativeDocumentInputs` | `"pdf"[]` | Нативні типи документів, які підтримує провайдер. |
## Довідник `channelConfigs`
-Використовуйте `channelConfigs`, коли channel plugin потребує легких метаданих конфігурації до
-завантаження runtime.
+Використовуйте `channelConfigs`, коли плагіну каналу потрібні легковагові метадані конфігурації до
+завантаження рантайму.
```json
{
@@ -491,32 +491,33 @@ Plugin provider, які реалізують `resolveExternalAuthProfiles`, ма
},
"uiHints": {
"homeserverUrl": {
- "label": "Homeserver URL",
+ "label": "URL homeserver",
"placeholder": "https://matrix.example.com"
}
},
"label": "Matrix",
- "description": "Підключення до homeserver Matrix",
+ "description": "Підключення до Matrix homeserver",
"preferOver": ["matrix-legacy"]
}
}
}
```
-Кожен запис channel може містити:
+Кожен запис каналу може містити:
-| Поле | Тип | Що воно означає |
-| ------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
-| `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації channel. |
-| `uiHints` | `Record` | Необов’язкові підписи UI/заповнювачі/підказки чутливості для цього розділу конфігурації channel. |
-| `label` | `string` | Підпис channel, що об’єднується в поверхнях вибору та перегляду, коли метадані runtime ще не готові. |
-| `description` | `string` | Короткий опис channel для поверхонь перегляду та каталогу. |
-| `preferOver` | `string[]` | Id застарілих або менш пріоритетних plugin, які цей channel має випереджати в поверхнях вибору. |
+| Поле | Тип | Що воно означає |
+| ------------- | ------------------------ | -------------------------------------------------------------------------------------- |
+| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. |
+| `uiHints` | `Record` | Необов’язкові підписи UI/placeholders/підказки щодо чутливості для цього розділу конфігурації каналу. |
+| `label` | `string` | Підпис каналу, що об’єднується в поверхні вибору та перевірки, коли метадані рантайму ще не готові. |
+| `description` | `string` | Короткий опис каналу для поверхонь перевірки та каталогу. |
+| `preferOver` | `string[]` | Ідентифікатори застарілих або менш пріоритетних плагінів, які цей канал має перевершувати в поверхнях вибору. |
## Довідник `modelSupport`
-Використовуйте `modelSupport`, коли OpenClaw має визначати ваш provider plugin за
-скороченими id моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження runtime plugin.
+Використовуйте `modelSupport`, коли OpenClaw має визначати ваш плагін провайдера за
+скороченими ідентифікаторами моделей, такими як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження
+рантайму плагіна.
```json
{
@@ -529,102 +530,104 @@ Plugin provider, які реалізують `resolveExternalAuthProfiles`, ма
OpenClaw застосовує такий пріоритет:
-- явні посилання `provider/model` використовують метадані маніфесту `providers` plugin-власника
-- `modelPatterns` мають вищий пріоритет, ніж `modelPrefixes`
-- якщо збігаються один невбудований plugin і один вбудований plugin, перемагає невбудований
- plugin
-- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть provider
+- явні посилання `provider/model` використовують метадані маніфесту `providers` плагіна-власника
+- `modelPatterns` мають вищий пріоритет за `modelPrefixes`
+- якщо збігаються і один невбудований плагін, і один вбудований плагін, перемагає невбудований
+ плагін
+- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкаже провайдера
Поля:
-| Поле | Тип | Що воно означає |
-| --------------- | ---------- | -------------------------------------------------------------------------------- |
-| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id моделей. |
-| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id моделей після видалення суфікса профілю. |
+| Поле | Тип | Що воно означає |
+| --------------- | ---------- | ---------------------------------------------------------------------------- |
+| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. |
+| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. |
-Застарілі ключі можливостей верхнього рівня не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб
+Застарілі ключі можливостей верхнього рівня є deprecated. Використовуйте `openclaw doctor --fix`, щоб
перемістити `speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`,
-`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне
+`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне
завантаження маніфесту більше не розглядає ці поля верхнього рівня як
володіння можливостями.
## Маніфест і `package.json`
-Ці два файли виконують різні завдання:
+Ці два файли виконують різні задачі:
-| Файл | Для чого використовувати |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду plugin |
-| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, обмежень встановлення, setup або метаданих каталогу |
+| Файл | Використовуйте його для |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `openclaw.plugin.json` | Виявлення, валідації конфігурації, метаданих варіантів автентифікації та підказок UI, які мають існувати до запуску коду плагіна |
+| `package.json` | Метаданих npm, встановлення залежностей і блоку `openclaw`, який використовується для точок входу, обмежень встановлення, setup або метаданих каталогу |
-Якщо ви не впевнені, куди належить певний фрагмент метаданих, користуйтеся таким правилом:
+Якщо ви не впевнені, куди має належати певний фрагмент метаданих, користуйтеся таким правилом:
-- якщо OpenClaw має знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json`
+- якщо OpenClaw має знати це до завантаження коду плагіна, помістіть це в `openclaw.plugin.json`
- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, помістіть це в `package.json`
### Поля `package.json`, які впливають на виявлення
-Деякі метадані plugin до виконання навмисно зберігаються в `package.json` у блоці
+Деякі метадані плагіна до запуску рантайму навмисно зберігаються в `package.json` у блоці
`openclaw`, а не в `openclaw.plugin.json`.
Важливі приклади:
-| Поле | Що воно означає |
-| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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` | Полегшені метадані каталогу channel, як-от підписи, шляхи до документації, псевдоніми та тексти для вибору. |
-| `openclaw.channel.configuredState` | Полегшені метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного runtime channel. |
-| `openclaw.channel.persistedAuthState` | Полегшені метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже виконано вхід хоч десь?» без завантаження повного runtime channel. |
-| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення вбудованих і зовнішньо опублікованих plugin. |
-| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
-| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. |
-| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення звіряють завантажений артефакт із ним. |
-| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого plugin, коли конфігурація недійсна. |
-| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного plugin channel під час запуску. |
+| Поле | Що воно означає |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `openclaw.extensions` | Оголошує точки входу власного плагіна. Вони мають залишатися в межах каталогу пакета плагіна. |
+| `openclaw.runtimeExtensions` | Оголошує точки входу рантайму зібраного JavaScript для встановлених пакетів. Вони мають залишатися в межах каталогу пакета плагіна. |
+| `openclaw.setupEntry` | Легковагова точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та read-only виявлення channel status/SecretRef. Має залишатися в межах каталогу пакета плагіна. |
+| `openclaw.runtimeSetupEntry` | Оголошує точку входу setup зібраного JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета плагіна. |
+| `openclaw.channel` | Легковагові метадані каталогу каналу, як-от підписи, шляхи до документації, аліаси та текст для вибору. |
+| `openclaw.channel.configuredState` | Легковагові метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного рантайму каналу. |
+| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного рантайму каналу. |
+| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих плагінів. |
+| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
+| `openclaw.install.minHostVersion` | Мінімально підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. |
+| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. |
+| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого плагіна, коли конфігурація невалідна. |
+| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного плагіна каналу під час запуску. |
-Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в
-онбордингу до завантаження runtime. `package.json#openclaw.install` повідомляє
-онбордингу, як отримати або ввімкнути цей plugin, коли користувач вибирає один із цих
-варіантів. Не переносіть підказки встановлення до `openclaw.plugin.json`.
+Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в
+онбордингу до завантаження рантайму. `package.json#openclaw.install` повідомляє
+онбордингу, як отримати або ввімкнути цей плагін, коли користувач вибирає один із цих
+варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`.
-`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження
-реєстру маніфестів. Недійсні значення відхиляються; новіші, але коректні значення
-пропускають plugin на старіших хостах.
+`openclaw.install.minHostVersion` застосовується під час встановлення та
+завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення
+пропускають плагін на старіших хостах.
-Точне закріплення версії npm уже зберігається в `npmSpec`, наприклад
+Точне закріплення версії npm уже міститься в `npmSpec`, наприклад
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу
мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення
-завершувалися без вибору, якщо завантажений npm-артефакт більше не відповідає
-закріпленому релізу. Інтерактивний онбординг і надалі пропонує довірені npm-специфікації
-реєстру, зокрема прості назви пакетів і dist-tags, для сумісності. Діагностика каталогу
-може розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності та недійсні
-джерела default-choice. Коли `expectedIntegrity` присутній, потоки встановлення/оновлення
-застосовують його; коли його пропущено, розв’язання через реєстр записується
-без закріплення цілісності.
+завершувалися закритою відмовою, якщо отриманий артефакт npm більше не відповідає закріпленому релізу.
+Інтерактивний онбординг усе ще пропонує довірені npm-специфікації реєстру, включно з
+простими назвами пакетів і dist-tag, для сумісності. Діагностика каталогу може
+розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності та невалідні
+джерела default-choice. Вона також попереджає, коли `expectedIntegrity` присутній, але
+немає валідного джерела npm, яке можна ним закріпити. Коли `expectedIntegrity` присутній,
+потоки встановлення/оновлення застосовують його; коли він пропущений, розв’язання реєстру
+фіксується без закріплення за цілісністю.
-Channel plugin мають надавати `openclaw.setupEntry`, коли статус, список channel
+Плагіни каналів мають надавати `openclaw.setupEntry`, коли status, список каналів
або сканування SecretRef повинні визначати налаштовані облікові записи без завантаження повного
-runtime. Точка входу setup має надавати метадані channel разом із безпечними для setup
-адаптерами конфігурації, статусу й секретів; мережеві клієнти, слухачі Gateway і
-transport runtime слід залишати в основній точці входу extension.
+рантайму. Точка входу setup має надавати метадані каналу разом із безпечними для setup
+адаптерами конфігурації, status і secret; мережеві клієнти, слухачі Gateway та
+транспортні рантайми слід тримати в основній точці входу extension.
-Поля точок входу runtime не скасовують перевірки меж пакета для
-полів точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити
-придатним до завантаження шлях `openclaw.extensions`, що виходить за межі.
+Поля точок входу рантайму не перевизначають перевірки меж пакета для полів
+точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити
+шлях `openclaw.extensions`, що виходить за межі, доступним для завантаження.
-`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він
-не робить довільні зламані конфігурації придатними для встановлення. Наразі він лише дозволяє
-потокам встановлення відновлюватися після певних застарілих збоїв оновлення вбудованого plugin,
-наприклад відсутнього шляху до вбудованого plugin або застарілого запису `channels.` для цього ж
-вбудованого plugin. Несуміжні помилки конфігурації, як і раніше, блокують встановлення та спрямовують операторів
+`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно
+не робить довільно зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам встановлення
+відновлюватися після певних застарілих збоїв оновлення вбудованих плагінів, наприклад
+відсутнього шляху до вбудованого плагіна або застарілого запису `channels.` для того самого
+вбудованого плагіна. Непов’язані помилки конфігурації, як і раніше, блокують встановлення та спрямовують операторів
до `openclaw doctor --fix`.
-`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки:
+`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля
+перевірки:
```json
{
@@ -640,13 +643,13 @@ transport runtime слід залишати в основній точці вх
}
```
-Використовуйте це, коли потоки setup, doctor або configured-state потребують дешевого
-yes/no-зонду автентифікації до завантаження повного channel plugin. Цільовий експорт має бути
-невеликою функцією, що читає лише збережений стан; не маршрутизуйте його через повний
-barrel runtime channel.
+Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка
+автентифікації типу так/ні до завантаження повного плагіна каналу. Цільовий експорт має бути невеликою
+функцією, яка читає лише збережений стан; не маршрутизуйте її через широкий barrel повного
+рантайму каналу.
-`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок
-configured-state лише через env:
+`openclaw.channel.configuredState` має таку саму форму для дешевих перевірок
+налаштованого стану лише через env:
```json
{
@@ -662,68 +665,68 @@ configured-state лише через env:
}
```
-Використовуйте це, коли channel може визначити configured-state з env або інших малих
-невиконуваних вхідних даних. Якщо перевірка потребує повного розв’язання конфігурації або реального
-runtime channel, натомість залиште цю логіку в хуку plugin `config.hasConfiguredState`.
+Використовуйте це, коли канал може відповісти про налаштований стан на основі env або інших невеликих
+вхідних даних, не пов’язаних із рантаймом. Якщо перевірка потребує повного розв’язання конфігурації або реального
+рантайму каналу, залиште цю логіку в хуку плагіна `config.hasConfiguredState`.
-## Пріоритет виявлення (дублікати id plugin)
+## Пріоритет виявлення (дубльовані ідентифікатори плагінів)
-OpenClaw виявляє plugin з кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним.
+OpenClaw виявляє плагіни з кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два результати виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються, а не завантажуються поруч із ним.
Пріоритет, від найвищого до найнижчого:
1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.`
-2. **Вбудований** — plugin, що постачаються з OpenClaw
-3. **Глобальне встановлення** — plugin, встановлені до глобального кореня plugin OpenClaw
-4. **Workspace** — plugin, виявлені відносно поточного workspace
+2. **Вбудований** — плагіни, що постачаються з OpenClaw
+3. **Глобальне встановлення** — плагіни, встановлені в глобальний корінь плагінів OpenClaw
+4. **Workspace** — плагіни, виявлені відносно поточного workspace
Наслідки:
-- Форкнута або застаріла копія вбудованого plugin у workspace не зможе затінити вбудовану збірку.
-- Щоб справді перевизначити вбудований plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення у workspace.
-- Відкидання дублікатів записується в лог, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
+- Форк або застаріла копія вбудованого плагіна, що лежить у workspace, не перекриє вбудовану збірку.
+- Щоб справді перевизначити вбудований плагін локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтесь на виявлення у workspace.
+- Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
## Вимоги до JSON Schema
-- **Кожен plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію.
-- Порожня схема прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`).
-- Схеми проходять валідацію під час читання/запису конфігурації, а не під час runtime.
+- **Кожен плагін повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію.
+- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
+- Схеми проходять валідацію під час читання/запису конфігурації, а не в рантаймі.
## Поведінка валідації
-- Невідомі ключі `channels.*` є **помилками**, якщо тільки id channel не оголошено
- маніфестом plugin.
+- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено в
+ маніфесті плагіна.
- `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*`
- мають посилатися на **виявлювані** id plugin. Невідомі id є **помилками**.
-- Якщо plugin встановлено, але він має зламаний або відсутній маніфест чи схему,
- валідація завершується помилкою, а Doctor повідомляє про помилку plugin.
-- Якщо конфігурація plugin існує, але plugin **вимкнено**, конфігурація зберігається, і
- у Doctor + логах відображається **попередження**.
+ мають посилатися на **виявлювані** ідентифікатори плагінів. Невідомі ідентифікатори є **помилками**.
+- Якщо плагін установлено, але він має зламаний або відсутній маніфест чи схему,
+ валідація завершується помилкою, а Doctor повідомляє про помилку плагіна.
+- Якщо конфігурація плагіна існує, але сам плагін **вимкнений**, конфігурація зберігається, а
+ в Doctor + логах показується **попередження**.
-Див. [Довідник конфігурації](/uk/gateway/configuration) для повної схеми `plugins.*`.
+Повну схему `plugins.*` дивіться в [Configuration reference](/uk/gateway/configuration).
## Примітки
-- Маніфест **обов’язковий для власних Plugin OpenClaw**, зокрема для локальних завантажень із файлової системи. Runtime, як і раніше, завантажує модуль plugin окремо; маніфест використовується лише для виявлення + валідації.
-- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, якщо кінцеве значення все ще є об’єктом.
-- Завантажувач маніфесту читає лише документовані поля маніфесту. Уникайте власних ключів верхнього рівня.
-- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо plugin їх не потребує.
-- `providerDiscoveryEntry` має залишатися полегшеним і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу provider або вузьких дескрипторів виявлення, а не для виконання під час запиту.
-- Ексклюзивні типи plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`).
-- Метадані змінних середовища (`providerAuthEnvVars`, `channelEnvVars`) є лише декларативними. Поверхні статусу, аудиту, валідації доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до plugin і ефективної активації, перш ніж вважати змінну середовища налаштованою.
-- Для метаданих wizard runtime, які потребують коду provider, див. [Хуки runtime provider](/uk/plugins/architecture-internals#provider-runtime-hooks).
-- Якщо ваш plugin залежить від native-модулів, задокументуйте кроки збирання та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `).
+- Маніфест є **обов’язковим для власних плагінів OpenClaw**, включно із завантаженням із локальної файлової системи. Рантайм, як і раніше, завантажує модуль плагіна окремо; маніфест використовується лише для виявлення + валідації.
+- Власні маніфести парсяться за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, доки кінцеве значення все ще залишається об’єктом.
+- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте користувацьких ключів верхнього рівня.
+- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо плагін їх не потребує.
+- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широкий код рантайму; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час обробки запитів.
+- Ексклюзивні типи плагінів вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`).
+- Метадані змінних середовища (`providerAuthEnvVars`, `channelEnvVars`) є лише декларативними. Status, audit, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до плагіна та ефективної активації, перш ніж вважати змінну середовища налаштованою.
+- Метадані runtime wizard, які потребують коду провайдера, дивіться в [Provider runtime hooks](/uk/plugins/architecture-internals#provider-runtime-hooks).
+- Якщо ваш плагін залежить від native modules, задокументуйте кроки збірки та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `).
-## Пов’язані матеріали
+## Пов’язане
-
- Початок роботи з plugin.
+
+ Початок роботи з плагінами.
-
+
Внутрішня архітектура та модель можливостей.
- Довідник по SDK plugin і імпортам підшляхів.
+ Довідник Plugin SDK і імпорти підшляхів.