diff --git a/docs/uk/plugins/architecture-internals.md b/docs/uk/plugins/architecture-internals.md
index ee3ca15be..355287190 100644
--- a/docs/uk/plugins/architecture-internals.md
+++ b/docs/uk/plugins/architecture-internals.md
@@ -1,26 +1,26 @@
---
read_when:
- Реалізація хуків середовища виконання провайдера, життєвого циклу каналу або пакетних наборів
- - Налагодження порядку завантаження плагінів або стану реєстру
+ - Налагодження порядку завантаження Plugin або стану реєстру
- Додавання нової можливості Plugin або Plugin рушія контексту
-summary: 'Внутрішні механізми архітектури Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці'
-title: Внутрішня архітектура Plugin
+summary: 'Внутрішні аспекти архітектури Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці'
+title: Внутрішні механізми архітектури Plugin
x-i18n:
- generated_at: "2026-05-01T22:48:18Z"
+ generated_at: "2026-05-02T14:59:49Z"
model: gpt-5.5
provider: openai
- source_hash: 2de741c4b496c7c3dd31dafebf39c4b9a32c5edd71bdd201c14037d9de31718f
+ source_hash: fec593518e51f68ce617d5bc4e55cede2188e9247f863364a9ea956e50ca2675
source_path: plugins/architecture-internals.md
workflow: 16
---
-Для публічної моделі можливостей, форм Plugin і контрактів володіння/виконання див. [архітектуру Plugin](/uk/plugins/architecture). Ця сторінка є довідником щодо внутрішньої механіки: конвеєра завантаження, реєстру, runtime-хуків, HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем.
+Для публічної моделі можливостей, форм Plugin і контрактів володіння/виконання див. [Архітектура Plugin](/uk/plugins/architecture). Ця сторінка є довідником щодо внутрішніх механізмів: конвеєра завантаження, реєстру, runtime-хуків, HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем.
## Конвеєр завантаження
Під час запуску OpenClaw приблизно виконує таке:
-1. виявляє корені кандидатів Plugin
+1. виявляє корені Plugin-кандидатів
2. читає нативні або сумісні маніфести бандлів і метадані пакетів
3. відхиляє небезпечних кандидатів
4. нормалізує конфігурацію Plugin (`plugins.enabled`, `allow`, `deny`, `entries`,
@@ -29,102 +29,108 @@ x-i18n:
6. завантажує ввімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач;
сторонній локальний вихідний TypeScript використовує аварійний fallback Jiti
7. викликає нативні хуки `register(api)` і збирає реєстрації в реєстр Plugin
-8. надає реєстр командам і runtime-поверхням
+8. відкриває реєстр для команд/runtime-поверхонь
-`activate` — це застарілий псевдонім для `register`: завантажувач визначає наявний варіант (`def.register ?? def.activate`) і викликає його в тій самій точці. Усі вбудовані Plugin використовують `register`; для нових Plugin надавайте перевагу `register`.
+`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що доступне (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані Plugin використовують `register`; для нових Plugin надавайте перевагу `register`.
-Запобіжні перевірки виконуються **до** runtime-виконання. Кандидатів блокують,
-коли точка входу виходить за межі кореня Plugin, шлях доступний для запису всім
-користувачам або володіння шляхом виглядає підозрілим для не вбудованих Plugin.
+Запобіжні перевірки виконуються **до** runtime-виконання. Кандидати блокуються,
+коли точка входу виходить за межі кореня Plugin, шлях доступний для запису всім користувачам або
+володіння шляхом виглядає підозріло для невбудованих Plugin.
### Поведінка з пріоритетом маніфесту
Маніфест є джерелом істини для площини керування. OpenClaw використовує його, щоб:
- ідентифікувати Plugin
-- виявляти оголошені канали/Skills/схему конфігурації або можливості бандла
+- виявляти оголошені канали/skills/схему конфігурації або можливості бандла
- перевіряти `plugins.entries..config`
- доповнювати мітки/заповнювачі Control UI
- показувати метадані встановлення/каталогу
- зберігати дешеві дескриптори активації та налаштування без завантаження runtime Plugin
Для нативних Plugin runtime-модуль є частиною площини даних. Він реєструє
-фактичну поведінку, як-от хуки, інструменти, команди або потоки провайдерів.
+фактичну поведінку, як-от хуки, інструменти, команди або provider-потоки.
-Необов’язкові блоки маніфесту `activation` і `setup` залишаються в площині керування.
-Вони є лише метаданими-дескрипторами для планування активації та виявлення налаштування;
+Необов’язкові блоки маніфесту `activation` і `setup` залишаються на площині керування.
+Це лише метадані-дескриптори для планування активації та виявлення налаштування;
вони не замінюють runtime-реєстрацію, `register(...)` або `setupEntry`.
-Перші live-споживачі активації тепер використовують підказки маніфесту щодо команд, каналів і провайдерів,
+Перші споживачі live-активації тепер використовують підказки маніфесту щодо команд, каналів і providers,
щоб звузити завантаження Plugin перед ширшою матеріалізацією реєстру:
- завантаження CLI звужується до Plugin, які володіють запитаною основною командою
- налаштування каналу/розв’язання Plugin звужується до Plugin, які володіють запитаним
id каналу
-- явне налаштування/розв’язання runtime провайдера звужується до Plugin, які володіють
- запитаним id провайдера
-- планування запуску Gateway використовує `activation.onStartup` для явних
- імпортів під час запуску та відмов від запуску; Plugin без метаданих запуску завантажуються лише
+- явне налаштування provider/розв’язання runtime звужується до Plugin, які володіють запитаним
+ id provider
+- планування запуску Gateway використовує `activation.onStartup` для явних startup-імпортів
+ і відмов від запуску; Plugin без startup-метаданих завантажуються лише
через вужчі тригери активації
-Планувальник активації надає як API лише з ids для наявних викликачів, так і
-API плану для нової діагностики. Записи плану повідомляють, чому було вибрано Plugin,
-відокремлюючи явні підказки планувальника `activation.*` від fallback володіння маніфестом,
+Runtime-попередні завантаження під час запиту, які просять широкий scope `all`, усе ще виводять
+явний ефективний набір id Plugin з конфігурації, планування запуску, налаштованих
+каналів, слотів і правил автоввімкнення. Якщо цей виведений набір порожній, OpenClaw
+завантажує порожній runtime-реєстр замість розширення до кожного доступного для виявлення
+Plugin.
+
+Планувальник активації відкриває як API лише з ids для наявних викликачів, так і
+API плану для нової діагностики. Записи плану повідомляють, чому Plugin було вибрано,
+відокремлюючи явні підказки планувальника `activation.*` від fallback-володіння маніфесту,
як-от `providers`, `channels`, `commandAliases`, `setup.providers`,
-`contracts.tools` і хуки. Такий поділ причин є межею сумісності:
+`contracts.tools` і хуки. Це розділення причин є межею сумісності:
наявні метадані Plugin продовжують працювати, а новий код може виявляти широкі підказки
або fallback-поведінку без зміни семантики runtime-завантаження.
Виявлення налаштування тепер надає перевагу id, якими володіють дескриптори, як-от `setup.providers` і
-`setup.cliBackends`, щоб звузити Plugin-кандидати перед fallback до
-`setup-api` для Plugin, яким досі потрібні runtime-хуки під час налаштування. Списки
-налаштування провайдерів використовують `providerAuthChoices` маніфесту, варіанти налаштування,
-похідні від дескрипторів, і метадані каталогу встановлення без завантаження runtime провайдера. Явне
-`setup.requiresRuntime: false` є дескрипторним-only відсіканням; пропущене
-`requiresRuntime` зберігає застарілий fallback `setup-api` для сумісності. Якщо більш
-ніж один виявлений Plugin заявляє той самий нормалізований id провайдера налаштування або CLI
-backend, пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на
-порядок виявлення. Коли runtime налаштування все ж виконується, діагностика реєстру повідомляє
-про розбіжності між `setup.providers` / `setup.cliBackends` і провайдерами або CLI
-backends, зареєстрованими через setup-api, не блокуючи застарілі Plugin.
+`setup.cliBackends`, щоб звузити Plugin-кандидати, перш ніж fallback-перехід до
+`setup-api` для Plugin, яким усе ще потрібні runtime-хуки під час налаштування. Списки
+налаштування provider використовують маніфестні `providerAuthChoices`, виведені з дескрипторів варіанти
+налаштування та метадані інсталяційного каталогу без завантаження runtime provider. Явне
+`setup.requiresRuntime: false` є descriptor-only межею; пропущене
+`requiresRuntime` зберігає застарілий fallback до setup-api для сумісності. Якщо більше
+ніж один виявлений Plugin заявляє той самий нормалізований id setup provider або CLI
+backend, пошук налаштування відхиляє неоднозначного власника замість покладання на
+порядок виявлення. Коли setup runtime виконується, діагностика реєстру повідомляє
+про розбіжності між `setup.providers` / `setup.cliBackends` і providers або CLI
+backends, зареєстрованими setup-api, без блокування застарілих Plugin.
### Межа кешу Plugin
OpenClaw не кешує результати виявлення Plugin або прямі дані реєстру маніфестів
-за часовими вікнами wall-clock. Встановлення, редагування маніфестів і зміни шляхів завантаження
-мають ставати видимими під час наступного явного читання метаданих або перебудови знімка.
-Парсер файлів маніфестів може тримати обмежений кеш файлових сигнатур із ключем за
-відкритим шляхом маніфесту, inode, розміром і часовими мітками; цей кеш лише уникає
-повторного парсингу незмінених байтів і не має кешувати відповіді щодо виявлення, реєстру, власника або
-політики.
+за часовими вікнами настінного годинника. Встановлення, редагування маніфестів і зміни load-path
+мають ставати видимими під час наступного явного читання метаданих або перебудови snapshot.
+Парсер файлу маніфесту може зберігати обмежений кеш сигнатур файлів, прив’язаний до
+відкритого шляху маніфесту, inode, розміру й часових міток; цей кеш лише уникає
+повторного парсингу незмінених байтів і не повинен кешувати відповіді щодо виявлення,
+реєстру, власника або політики.
Безпечний швидкий шлях метаданих — це явне володіння об’єктом, а не прихований кеш.
-Гарячі шляхи запуску Gateway мають передавати поточний `PluginMetadataSnapshot`,
-похідний `PluginLookUpTable` або явний реєстр маніфестів через ланцюжок викликів.
-Перевірка конфігурації, автозапуск, bootstrap Plugin і вибір провайдера
+Гарячі шляхи запуску Gateway мають передавати поточний `PluginMetadataSnapshot`, виведену
+`PluginLookUpTable` або явний реєстр маніфестів через ланцюжок викликів.
+Перевірка конфігурації, startup auto-enable, bootstrap Plugin і вибір provider
можуть повторно використовувати ці об’єкти, доки вони представляють поточну конфігурацію та
-інвентар Plugin. Пошук налаштування досі реконструює метадані маніфестів на вимогу,
-якщо конкретний шлях налаштування не отримує явний реєстр маніфестів; тримайте це
-як fallback холодного шляху замість додавання прихованих кешів пошуку. Коли вхідні дані
-змінюються, перебудовуйте й замінюйте знімок замість того, щоб мутувати його або зберігати
-історичні копії.
-Представлення активного реєстру Plugin і допоміжні засоби bootstrap вбудованих каналів
-мають переобчислюватися з поточного реєстру/кореня. Короткоживучі мапи прийнятні
-в межах одного виклику для усунення дублювання роботи або захисту від повторного входу; вони не мають ставати процесними
-кешами метаданих.
+інвентар Plugin. Пошук налаштування все ще реконструює метадані маніфесту на вимогу,
+якщо конкретний шлях налаштування не отримує явний реєстр маніфестів; зберігайте це
+як fallback холодного шляху замість додавання прихованих кешів lookup. Коли вхідні дані
+змінюються, перебудовуйте й замінюйте snapshot замість його мутації або збереження
+історичних копій.
+Подання над активним реєстром Plugin і helpers bootstrap для вбудованих каналів
+мають переобчислюватися з поточного реєстру/кореня. Короткоживучі мапи допустимі
+всередині одного виклику для дедуплікації роботи або захисту від повторного входу; вони не повинні ставати process
+metadata caches.
Для завантаження Plugin постійний шар кешу — це runtime-завантаження. Він може повторно використовувати
-стан завантажувача, коли код або встановлені артефакти фактично завантажені, як-от:
+стан завантажувача, коли код або встановлені артефакти справді завантажуються, як-от:
- `PluginLoaderCacheState` і сумісні активні runtime-реєстри
-- кеші jiti/модулів і кеші завантажувача публічної поверхні, що використовуються, щоб уникнути імпорту
- тієї самої runtime-поверхні повторно
-- кеші файлової системи для встановлених артефактів Plugin
-- короткоживучі мапи на виклик для нормалізації шляхів або розв’язання дублікатів
+- кеші jiti/module і кеші завантажувача public-surface, що використовуються, щоб уникати повторного імпорту
+ тієї самої runtime-поверхні
+- файлові кеші для встановлених артефактів Plugin
+- короткоживучі per-call мапи для нормалізації шляхів або розв’язання дублікатів
-Ці кеші є деталями реалізації площини даних. Вони не мають відповідати
-на запитання площини керування, як-от "якому Plugin належить цей провайдер?", якщо викликач
+Ці кеші є деталями реалізації площини даних. Вони не повинні відповідати на
+питання площини керування, як-от "який Plugin володіє цим provider?", якщо викликач
навмисно не попросив runtime-завантаження.
Не додавайте постійні або wall-clock кеші для:
@@ -132,18 +138,17 @@ OpenClaw не кешує результати виявлення Plugin або
- результатів виявлення
- прямих реєстрів маніфестів
- реєстрів маніфестів, реконструйованих зі встановленого індексу Plugin
-- пошуку власника провайдера, пригнічення моделей, політики провайдера або метаданих
- публічних артефактів
-- будь-якої іншої відповіді, похідної від маніфесту, де змінений маніфест, встановлений індекс
- або шлях завантаження має бути видимим під час наступного читання метаданих
+- lookup власника provider, приглушення моделей, політики provider або метаданих public-artifact
+- будь-якої іншої відповіді, виведеної з маніфесту, де змінений маніфест, встановлений індекс
+ або load path має бути видимим під час наступного читання метаданих
-Викликачі, які перебудовують метадані маніфестів зі збереженого встановленого індексу Plugin,
-реконструюють цей реєстр на вимогу. Встановлений індекс є довговічним
-станом площини джерела; це не прихований внутрішньопроцесний кеш метаданих.
+Викликачі, які перебудовують метадані маніфесту зі збереженого встановленого індексу Plugin,
+реконструюють цей реєстр на вимогу. Встановлений індекс є довготривалим
+станом source-plane; це не прихований in-process кеш метаданих.
## Модель реєстру
-Завантажені Plugin не мутують напряму випадкові глобальні об’єкти ядра. Вони реєструються в
+Завантажені Plugin не мутують напряму випадкові core globals. Вони реєструються в
центральному реєстрі Plugin.
Реєстр відстежує:
@@ -152,28 +157,28 @@ OpenClaw не кешує результати виявлення Plugin або
- інструменти
- застарілі хуки та типізовані хуки
- канали
-- провайдерів
-- обробники Gateway RPC
+- providers
+- RPC-обробники Gateway
- HTTP-маршрути
- реєстратори CLI
- фонові сервіси
- команди, якими володіють Plugin
-Потім функції ядра читають із цього реєстру замість того, щоб напряму звертатися до модулів Plugin.
+Потім core-функції читають із цього реєстру замість прямої взаємодії з модулями Plugin.
Це зберігає завантаження односпрямованим:
- модуль Plugin -> реєстрація в реєстрі
-- runtime ядра -> споживання реєстру
+- core runtime -> споживання реєстру
-Це розділення важливе для супроводу. Воно означає, що більшості поверхонь ядра потрібна лише
-одна точка інтеграції: "читати реєстр", а не "обробляти кожен модуль Plugin окремо".
+Це розділення важливе для підтримуваності. Воно означає, що більшості core-поверхонь потрібна лише
+одна точка інтеграції: "прочитати реєстр", а не "спеціально обробляти кожен модуль Plugin".
-## Callback-и прив’язки розмови
+## Callback-и прив’язування розмови
-Plugin, які прив’язують розмову, можуть реагувати, коли схвалення вирішено.
+Plugin, які прив’язують розмову, можуть реагувати, коли approval розв’язано.
Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати callback після того, як запит
-на прив’язку схвалено або відхилено:
+на bind схвалено або відхилено:
```ts
export default {
@@ -193,117 +198,117 @@ export default {
};
```
-Поля payload callback:
+Поля payload callback-а:
- `status`: `"approved"` або `"denied"`
- `decision`: `"allow-once"`, `"allow-always"` або `"deny"`
- `binding`: розв’язана прив’язка для схвалених запитів
-- `request`: початковий підсумок запиту, підказка від’єднання, id відправника та
+- `request`: початковий підсумок запиту, підказка detach, id відправника та
метадані розмови
-Цей callback призначений лише для сповіщення. Він не змінює, кому дозволено прив’язувати
-розмову, і виконується після завершення обробки схвалення ядром.
+Цей callback є лише сповіщенням. Він не змінює, кому дозволено прив’язувати
+розмову, і виконується після завершення core-обробки approval.
-## Runtime-хуки провайдера
+## Runtime-хуки provider
Provider Plugin мають три шари:
-- **Метадані маніфесту** для дешевого pre-runtime пошуку:
- `setup.providers[].envVars`, застаріле сумісне `providerAuthEnvVars`,
+- **Метадані маніфесту** для дешевого pre-runtime lookup:
+ `setup.providers[].envVars`, застарілий compatibility `providerAuthEnvVars`,
`providerAuthAliases`, `providerAuthChoices` і `channelEnvVars`.
-- **Хуки під час конфігурації**: `catalog` (застаріле `discovery`) плюс
+- **Хуки часу конфігурації**: `catalog` (застарілий `discovery`) плюс
`applyConfigDefaults`.
-- **Runtime-хуки**: понад 40 необов’язкових хуків, що охоплюють автентифікацію, розв’язання моделей,
- обгортання потоків, рівні мислення, політику replay і endpoints використання. Див.
- повний список у розділі [Порядок і використання хуків](#hook-order-and-usage).
+- **Runtime-хуки**: понад 40 необов’язкових хуків, що охоплюють auth, розв’язання моделей,
+ обгортання stream, рівні thinking, replay policy і usage endpoints. Повний список див.
+ у розділі [Порядок хуків і використання](#hook-order-and-usage).
-OpenClaw досі володіє загальним циклом агента, failover, обробкою transcript і
-політикою інструментів. Ці хуки є поверхнею розширення для специфічної для провайдера
-поведінки без потреби в повністю власному транспорті інференсу.
+OpenClaw усе ще володіє загальним agent loop, failover, обробкою transcript і
+tool policy. Ці хуки є поверхнею extension для provider-specific
+поведінки без потреби в повністю кастомному inference transport.
-Використовуйте `setup.providers[].envVars` маніфесту, коли провайдер має облікові дані на основі env,
-які загальні шляхи auth/status/model-picker мають бачити без
-завантаження runtime Plugin. Застаріле `providerAuthEnvVars` досі читається
-адаптером сумісності протягом вікна депрекації, а не вбудовані Plugin,
-які його використовують, отримують діагностику маніфесту. Використовуйте
-`providerAuthAliases` маніфесту, коли один id провайдера має повторно використовувати env vars,
-auth profiles, auth із конфігурації та варіант onboarding для API-ключа іншого id провайдера.
-Використовуйте `providerAuthChoices` маніфесту, коли CLI-поверхні onboarding/auth-choice мають знати
-id варіанта провайдера, мітки груп і просте auth-підключення одним прапорцем без
-завантаження runtime провайдера. Зберігайте runtime
-`envVars` провайдера для підказок, орієнтованих на оператора, як-от мітки onboarding або OAuth
+Використовуйте маніфестний `setup.providers[].envVars`, коли provider має env-based
+облікові дані, які generic auth/status/model-picker шляхи мають бачити без
+завантаження runtime Plugin. Застарілий `providerAuthEnvVars` усе ще читається
+compatibility adapter протягом deprecation window, а невбудовані Plugin,
+які його використовують, отримують діагностику маніфесту. Використовуйте маніфестний `providerAuthAliases`,
+коли один id provider має повторно використовувати env vars, auth profiles,
+config-backed auth і вибір onboarding з API key іншого id provider. Використовуйте маніфестний
+`providerAuthChoices`, коли onboarding/auth-choice CLI surfaces мають знати
+choice id provider, group labels і просте one-flag auth wiring без
+завантаження runtime provider. Зберігайте runtime
+`envVars` provider для operator-facing підказок, як-от onboarding labels або OAuth
client-id/client-secret setup vars.
-Використовуйте `channelEnvVars` маніфесту, коли канал має auth або налаштування на основі env, які
-загальний shell-env fallback, перевірки config/status або prompts налаштування мають бачити
-без завантаження runtime каналу.
+Використовуйте маніфестний `channelEnvVars`, коли канал має env-driven auth або setup, які
+generic shell-env fallback, config/status checks або setup prompts мають бачити
+без завантаження channel runtime.
-### Порядок і використання хуків
+### Порядок хуків і використання
-Для model/provider Plugin OpenClaw викликає хуки приблизно в такому порядку.
-Стовпець "Коли використовувати" є коротким посібником для ухвалення рішення.
-Compatibility-only поля провайдера, які OpenClaw більше не викликає, як-от
+Для Plugin моделей/provider OpenClaw викликає хуки приблизно в такому порядку.
+Стовпець "Коли використовувати" — це короткий посібник для ухвалення рішення.
+Compatibility-only поля provider, які OpenClaw більше не викликає, як-от
`ProviderPlugin.capabilities` і `suppressBuiltInModel`, навмисно не
-перелічено тут.
+перелічені тут.
-| # | Хук | Що робить | Коли використовувати |
-| --- | --------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або стандартними значеннями базової URL |
-| 2 | `applyConfigDefaults` | Застосовує глобальні стандартні значення конфігурації, якими володіє провайдер, під час матеріалізації конфігурації | Стандартні значення залежать від режиму автентифікації, env або семантики сімейства моделей провайдера |
-| -- | _(вбудований пошук моделі)_ | OpenClaw спершу пробує звичайний шлях реєстру/каталогу | _(не хук Plugin)_ |
-| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми ідентифікаторів моделей перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним розв’язанням моделі |
-| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдерів перед загальним складанням моделі | Провайдер володіє очищенням транспорту для користувацьких ідентифікаторів провайдерів у тому самому транспортному сімействі |
-| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед розв’язанням runtime/провайдера | Провайдер потребує очищення конфігурації, яке має жити з Plugin; вбудовані помічники сімейства Google також підстраховують підтримувані записи конфігурації Google |
-| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-перезаписи нативного streaming-usage до провайдерів конфігурації | Провайдер потребує виправлень метаданих нативного streaming usage, керованих endpoint |
-| 7 | `resolveConfigApiKey` | Розв’язує автентифікацію env-marker для провайдерів конфігурації перед завантаженням автентифікації runtime | Провайдер має власне розв’язання API-ключа env-marker; `amazon-bedrock` також має тут вбудований resolver AWS env-marker |
-| 8 | `resolveSyntheticAuth` | Показує локальну/самостійно розміщену або підкріплену конфігурацією автентифікацію без збереження plaintext | Провайдер може працювати із синтетичним/локальним маркером облікових даних |
-| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, якими володіє провайдер; стандартне `persistence` — `runtime-only` для облікових даних, якими володіє CLI/застосунок | Провайдер повторно використовує зовнішні облікові дані автентифікації без збереження скопійованих refresh-токенів; оголосіть `contracts.externalAuthProviders` у маніфесті |
-| 10 | `shouldDeferSyntheticProfileAuth` | Понижує збережені синтетичні заповнювачі профілю після автентифікації, підкріпленої env/config | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати пріоритет |
-| 11 | `resolveDynamicModel` | Синхронний fallback для ідентифікаторів моделей, якими володіє провайдер і яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream-ідентифікатори моделей |
-| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдер потребує мережевих метаданих перед розв’язанням невідомих ідентифікаторів |
-| 13 | `normalizeResolvedModel` | Фінальний перезапис перед тим, як вбудований runner використає розв’язану модель | Провайдер потребує транспортних перезаписів, але все ще використовує транспорт ядра |
-| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей постачальника за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy-транспортах без перебирання контролю над провайдером |
-| 15 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить вбудований runner | Провайдер потребує очищення схем транспортного сімейства |
-| 16 | `inspectToolSchemas` | Показує діагностику схем, якою володіє провайдер, після нормалізації | Провайдер хоче попередження щодо ключових слів без навчання ядра правилам, специфічним для провайдера |
-| 17 | `resolveReasoningOutputMode` | Вибирає нативний або тегований контракт reasoning-output | Провайдер потребує тегованого reasoning/final output замість нативних полів |
-| 18 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками опцій stream | Провайдер потребує стандартних параметрів запиту або очищення параметрів для окремого провайдера |
-| 19 | `createStreamFn` | Повністю замінює звичайний шлях stream користувацьким транспортом | Провайдер потребує користувацького wire-протоколу, а не лише обгортки |
-| 20 | `wrapStreamFn` | Обгортка stream після застосування загальних обгорток | Провайдер потребує compat-обгорток заголовків/тіла/моделі запиту без користувацького транспорту |
-| 21 | `resolveTransportTurnState` | Прикріплює нативні транспортні заголовки або метадані для окремого turn | Провайдер хоче, щоб загальні транспорти надсилали нативну для провайдера ідентичність turn |
-| 22 | `resolveWebSocketSessionPolicy` | Прикріплює нативні WebSocket-заголовки або політику cool-down сеансу | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сеансу або fallback-політику |
-| 23 | `formatApiKey` | Форматер профілю автентифікації: збережений профіль стає runtime-рядком `apiKey` | Провайдер зберігає додаткові метадані автентифікації та потребує користувацької форми runtime-токена |
-| 24 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких endpoint оновлення або політики помилки оновлення | Провайдер не вписується у спільні оновлювачі `pi-ai` |
-| 25 | `buildAuthDoctorHint` | Підказка для відновлення, додана після збою оновлення OAuth | Провайдер потребує власних порад з виправлення автентифікації після збою оновлення |
-| 26 | `matchesContextOverflowError` | Власний для провайдера matcher переповнення context-window | Провайдер має сирі помилки переповнення, які загальні евристики пропустили б |
-| 27 | `classifyFailoverReason` | Власна для провайдера класифікація причини failover | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо |
-| 28 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-провайдерів | Провайдер потребує специфічного для proxy обмеження cache TTL |
-| 29 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення для відсутньої автентифікації | Провайдер потребує специфічної для провайдера підказки відновлення відсутньої автентифікації |
-| 30 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після discovery | Провайдер потребує синтетичних forward-compat рядків у `models list` і picker-ах |
-| 31 | `resolveThinkingProfile` | Набір рівнів `/think` для моделі, відображувані мітки та стандартне значення | Провайдер надає користувацьку шкалу thinking або бінарну мітку для вибраних моделей |
-| 32 | `isBinaryThinking` | Compat-хук перемикача reasoning увімк./вимк. | Провайдер надає лише бінарне thinking увімк./вимк. |
-| 33 | `supportsXHighThinking` | Compat-хук підтримки reasoning `xhigh` | Провайдер хоче `xhigh` лише для підмножини моделей |
-| 34 | `resolveDefaultThinkingLevel` | Compat-хук стандартного рівня `/think` | Провайдер володіє стандартною політикою `/think` для сімейства моделей |
-| 35 | `isModernModelRef` | Matcher сучасної моделі для фільтрів live-профілю та вибору smoke | Провайдер володіє зіставленням бажаних live/smoke моделей |
-| 36 | `prepareRuntimeAuth` | Обмін налаштованих облікових даних на фактичний runtime-токен/ключ безпосередньо перед inference | Провайдер потребує обміну токена або короткоживучих облікових даних запиту |
-| 37 | `resolveUsageAuth` | Визначити облікові дані використання/білінгу для `/usage` і пов’язаних поверхонь стану | Провайдеру потрібен власний розбір токена використання/квоти або інші облікові дані використання |
-| 38 | `fetchUsageSnapshot` | Отримати й нормалізувати специфічні для провайдера знімки використання/квоти після визначення автентифікації | Провайдеру потрібна специфічна для провайдера кінцева точка використання або парсер корисного навантаження |
-| 39 | `createEmbeddingProvider` | Побудувати належний провайдеру адаптер векторних представлень для пам’яті/пошуку | Поведінка векторних представлень пам’яті належить Plugin провайдера |
-| 40 | `buildReplayPolicy` | Повернути політику повторного відтворення, що керує обробкою транскрипта для провайдера | Провайдеру потрібна власна політика транскрипта (наприклад, вилучення блоків мислення) |
-| 41 | `sanitizeReplayHistory` | Переписати історію повторного відтворення після загального очищення транскрипта | Провайдеру потрібні специфічні для провайдера переписування повторного відтворення поза спільними допоміжними засобами Compaction |
-| 42 | `validateReplayTurns` | Остаточна перевірка або переформування ходів повторного відтворення перед вбудованим runner | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санітизації |
-| 43 | `onModelSelected` | Виконати належні провайдеру побічні ефекти після вибору | Провайдеру потрібна телеметрія або належний провайдеру стан, коли модель стає активною |
+| # | Хук | Що він робить | Коли використовувати |
+| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями базової URL-адреси |
+| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму автентифікації, середовища або семантики родини моделей провайдера |
+| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях реєстру/каталогу | _(не хук plugin)_ |
+| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним розпізнаванням моделі |
+| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` родини провайдера перед загальним складанням моделі | Провайдер володіє очищенням транспорту для користувацьких ідентифікаторів провайдера в тій самій родині транспорту |
+| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед розпізнаванням runtime/провайдера | Провайдер потребує очищення конфігурації, яке має жити разом із plugin; вбудовані допоміжні засоби родини Google також підстраховують підтримувані записи конфігурації Google |
+| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування нативного використання потокового передавання до провайдерів конфігурації | Провайдер потребує виправлень метаданих нативного використання потокового передавання, керованих endpoint |
+| 7 | `resolveConfigApiKey` | Розпізнає автентифікацію через env-маркер для провайдерів конфігурації перед завантаженням runtime-автентифікації | Провайдер має власне для провайдера розпізнавання API-ключа через env-маркер; `amazon-bedrock` також має тут вбудований розпізнавач AWS env-маркера |
+| 8 | `resolveSyntheticAuth` | Надає локальну/самостійно розгорнуту або конфігураційно підкріплену автентифікацію без збереження plaintext | Провайдер може працювати із синтетичним/локальним маркером облікових даних |
+| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, що належать провайдеру; типове `persistence` — `runtime-only` для облікових даних, якими володіє CLI/app | Провайдер повторно використовує зовнішні облікові дані автентифікації без збереження скопійованих refresh tokens; оголосіть `contracts.externalAuthProviders` у manifest |
+| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілю за автентифікацією, підкріпленою env/config | Провайдер зберігає синтетичні профілі-заповнювачі, які не мають перемагати за пріоритетом |
+| 11 | `resolveDynamicModel` | Синхронний fallback для ідентифікаторів моделей, що належать провайдеру й ще не є в локальному реєстрі | Провайдер приймає довільні upstream-ідентифікатори моделей |
+| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдер потребує мережевих метаданих перед розпізнаванням невідомих ідентифікаторів |
+| 13 | `normalizeResolvedModel` | Фінальне переписування перед тим, як вбудований runner використає розпізнану модель | Провайдер потребує переписувань транспорту, але все ще використовує core-транспорт |
+| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей постачальника за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспортах без перебирання ролі провайдера |
+| 15 | `normalizeToolSchemas` | Нормалізує схеми інструментів перед тим, як їх побачить вбудований runner | Провайдер потребує очищення схем родини транспорту |
+| 16 | `inspectToolSchemas` | Надає діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження щодо ключових слів без навчання core правилам, специфічним для провайдера |
+| 17 | `resolveReasoningOutputMode` | Вибирає контракт виводу reasoning: нативний або tagged | Провайдер потребує tagged reasoning/фінального виводу замість нативних полів |
+| 18 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками опцій потоку | Провайдер потребує типових параметрів запиту або очищення параметрів для окремого провайдера |
+| 19 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдер потребує користувацького wire-протоколу, а не лише обгортки |
+| 20 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдер потребує compat-обгорток заголовків/тіла/моделі запиту без користувацького транспорту |
+| 21 | `resolveTransportTurnState` | Додає нативні per-turn транспортні заголовки або метадані | Провайдер хоче, щоб загальні транспорти надсилали нативну для провайдера ідентичність turn |
+| 22 | `resolveWebSocketSessionPolicy` | Додає нативні WebSocket-заголовки або політику cool-down сеансу | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сеансу або fallback-політику |
+| 23 | `formatApiKey` | Форматер профілю автентифікації: збережений профіль стає runtime-рядком `apiKey` | Провайдер зберігає додаткові метадані автентифікації та потребує користувацької форми runtime-токена |
+| 24 | `refreshOAuth` | Перевизначення OAuth refresh для користувацьких endpoint refresh або політики refresh-failure | Провайдер не вписується у спільні refreshers `pi-ai` |
+| 25 | `buildAuthDoctorHint` | Підказка для виправлення, що додається, коли OAuth refresh зазнає невдачі | Провайдер потребує власних для провайдера вказівок з відновлення автентифікації після невдачі refresh |
+| 26 | `matchesContextOverflowError` | Matcher переповнення context-window, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики пропустили б |
+| 27 | `classifyFailoverReason` | Класифікація причини failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload/тощо |
+| 28 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul провайдерів | Провайдер потребує проксі-специфічного обмеження cache TTL |
+| 29 | `buildMissingAuthMessage` | Заміна для загального повідомлення відновлення при відсутній автентифікації | Провайдер потребує специфічної для провайдера підказки відновлення при відсутній автентифікації |
+| 30 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Провайдер потребує синтетичних forward-compat рядків у `models list` і picker |
+| 31 | `resolveThinkingProfile` | Набір рівнів `/think` для конкретної моделі, мітки відображення та типове значення | Провайдер надає користувацьку драбину thinking або бінарну мітку для вибраних моделей |
+| 32 | `isBinaryThinking` | Compat-хук перемикача reasoning увімкнено/вимкнено | Провайдер надає лише бінарне thinking увімкнено/вимкнено |
+| 33 | `supportsXHighThinking` | Compat-хук підтримки reasoning `xhigh` | Провайдер хоче `xhigh` лише для підмножини моделей |
+| 34 | `resolveDefaultThinkingLevel` | Compat-хук типового рівня `/think` | Провайдер володіє типовою політикою `/think` для родини моделей |
+| 35 | `isModernModelRef` | Matcher сучасної моделі для фільтрів live-профілю та вибору smoke | Провайдер володіє зіставленням бажаних live/smoke моделей |
+| 36 | `prepareRuntimeAuth` | Обмін налаштованих облікових даних на фактичний runtime-токен/ключ безпосередньо перед inference | Провайдер потребує обміну токена або короткочасних облікових даних запиту |
+| 37 | `resolveUsageAuth` | Визначити облікові дані використання/білінгу для `/usage` і пов’язаних поверхонь стану | Постачальнику потрібен користувацький розбір токена використання/квоти або інші облікові дані використання |
+| 38 | `fetchUsageSnapshot` | Отримати й нормалізувати специфічні для постачальника знімки використання/квоти після визначення автентифікації | Постачальнику потрібна специфічна для постачальника кінцева точка використання або парсер корисного навантаження |
+| 39 | `createEmbeddingProvider` | Побудувати належний постачальнику адаптер ембедингів для пам’яті/пошуку | Поведінка ембедингів пам’яті належить Plugin постачальника |
+| 40 | `buildReplayPolicy` | Повернути політику повторного відтворення, що керує обробкою транскрипту для постачальника | Постачальнику потрібна користувацька політика транскрипту (наприклад, вилучення блоків мислення) |
+| 41 | `sanitizeReplayHistory` | Переписати історію повторного відтворення після загального очищення транскрипту | Постачальнику потрібні специфічні для постачальника переписування повторного відтворення поза спільними допоміжними засобами Compaction |
+| 42 | `validateReplayTurns` | Остаточна валідація або зміна форми ходів повторного відтворення перед вбудованим runner | Транспорт постачальника потребує суворішої валідації ходів після загальної санітизації |
+| 43 | `onModelSelected` | Виконати належні постачальнику побічні ефекти після вибору | Постачальнику потрібна телеметрія або належний постачальнику стан, коли модель стає активною |
`normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють
відповідний Plugin постачальника, а потім переходять до інших Plugin постачальників,
-здатних до хуків, доки один із них фактично не змінить ідентифікатор моделі або
-транспорт/конфігурацію. Це зберігає роботу alias/compat-шимів постачальників
-без потреби для викликача знати, який bundled Plugin відповідає за переписування.
-Якщо жоден хук постачальника не переписує підтримуваний запис конфігурації
-сімейства Google, bundled нормалізатор конфігурації Google усе одно застосовує
-це очищення сумісності.
+здатних працювати з хуками, доки один із них фактично не змінить ідентифікатор
+моделі або транспорт/конфігурацію. Це дає змогу shim-сумісності
+alias/compat постачальників працювати без вимоги до викликача знати, який
+вбудований Plugin володіє переписуванням. Якщо жоден хук постачальника не
+переписує підтримуваний запис конфігурації Google-родини, вбудований нормалізатор
+конфігурації Google усе одно застосує це очищення сумісності.
-Якщо постачальнику потрібен повністю власний дротовий протокол або власний
-виконавець запитів, це інший клас розширення. Ці хуки призначені для поведінки
+Якщо постачальнику потрібен повністю власний wire protocol або власний виконавець
+запитів, це інший клас розширення. Ці хуки призначені для поведінки
постачальника, яка все ще працює у звичайному циклі інференсу OpenClaw.
### Приклад постачальника
@@ -362,27 +367,27 @@ api.registerProvider({
### Вбудовані приклади
-Bundled Plugin постачальників поєднують наведені вище хуки, щоб відповідати
-потребам каталогу, автентифікації, мислення, повторного відтворення та usage
-кожного вендора. Авторитетний набір хуків розташований у кожному Plugin під
-`extensions/`; ця сторінка ілюструє форми, а не дзеркально відтворює список.
+Вбудовані Plugin постачальників поєднують наведені вище хуки, щоб відповідати
+потребам каталогу, автентифікації, міркування, відтворення та використання кожного
+постачальника. Авторитетний набір хуків міститься з кожним Plugin у `extensions/`;
+ця сторінка ілюструє форми, а не дублює список.
-
+
OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` разом із
`resolveDynamicModel` / `prepareDynamicModel`, щоб показувати upstream
- ідентифікатори моделей до статичного каталогу OpenClaw.
+ ідентифікатори моделей раніше за статичний каталог OpenClaw.
-
+
GitHub Copilot, Gemini CLI, ChatGPT Codex, MiniMax, Xiaomi, z.ai поєднують
`prepareRuntimeAuth` або `formatApiKey` з `resolveUsageAuth` +
`fetchUsageSnapshot`, щоб володіти обміном токенів та інтеграцією `/usage`.
-
- Спільні іменовані сімейства (`google-gemini`, `passthrough-gemini`,
+
+ Спільні іменовані родини (`google-gemini`, `passthrough-gemini`,
`anthropic-by-model`, `hybrid-anthropic-openai`) дають постачальникам змогу
- підключатися до політики транскриптів через `buildReplayPolicy`, замість
- того щоб кожен Plugin повторно реалізовував очищення.
+ підключатися до політики transcript через `buildReplayPolicy`, замість того
+ щоб кожен Plugin повторно реалізовував очищення.
`byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`,
@@ -390,18 +395,19 @@ Bundled Plugin постачальників поєднують наведені
`volcengine` реєструють лише `catalog` і використовують спільний цикл
інференсу.
-
- Beta-заголовки, `/fast` / `serviceTier` і `context1m` живуть усередині
- публічного шва `api.ts` / `contract-api.ts` Plugin Anthropic
+
+ Beta-заголовки, `/fast` / `serviceTier` і `context1m` містяться всередині
+ публічної межі `api.ts` / `contract-api.ts` Plugin Anthropic
(`wrapAnthropicProviderStream`, `resolveAnthropicBetas`,
`resolveAnthropicFastMode`, `resolveAnthropicServiceTier`), а не в
загальному SDK.
-## Runtime-помічники
+## Допоміжні засоби runtime
-Plugin можуть отримувати доступ до вибраних core-помічників через `api.runtime`. Для TTS:
+Plugin можуть отримувати доступ до вибраних допоміжних засобів ядра через
+`api.runtime`. Для TTS:
```ts
const clip = await api.runtime.tts.textToSpeech({
@@ -422,11 +428,11 @@ const voices = await api.runtime.tts.listVoices({
Примітки:
-- `textToSpeech` повертає звичайний core payload виводу TTS для поверхонь файлів/голосових нотаток.
-- Використовує core конфігурацію `messages.tts` і вибір постачальника.
-- Повертає PCM аудіобуфер + частоту дискретизації. Plugin мають виконати resample/encode для постачальників.
-- `listVoices` є необов’язковим для кожного постачальника. Використовуйте його для voice picker або setup flows, якими володіє вендор.
-- Списки голосів можуть містити багатші метадані, як-от локаль, стать і теги особистості, для picker, обізнаних про постачальника.
+- `textToSpeech` повертає звичайний payload виводу TTS ядра для поверхонь файлів/голосових нотаток.
+- Використовує конфігурацію ядра `messages.tts` і вибір постачальника.
+- Повертає аудіобуфер PCM + частоту дискретизації. Plugin мають виконувати ресемплінг/кодування для постачальників.
+- `listVoices` є необов’язковим для кожного постачальника. Використовуйте його для засобів вибору голосу або потоків налаштування, якими володіє постачальник.
+- Списки голосів можуть містити багатші метадані, як-от локаль, стать і теги особистості для засобів вибору, обізнаних про постачальника.
- OpenAI та ElevenLabs сьогодні підтримують телефонію. Microsoft не підтримує.
Plugin також можуть реєструвати постачальників мовлення через `api.registerSpeechProvider(...)`.
@@ -449,15 +455,15 @@ api.registerSpeechProvider({
Примітки:
-- Тримайте політику TTS, fallback і доставлення відповіді в core.
-- Використовуйте постачальників мовлення для синтезу, яким володіє вендор.
-- Legacy вхід Microsoft `edge` нормалізується до ідентифікатора постачальника `microsoft`.
-- Бажана модель володіння орієнтована на компанію: один Plugin вендора може володіти
+- Залишайте політику TTS, fallback і доставку відповідей у ядрі.
+- Використовуйте постачальників мовлення для поведінки синтезу, якою володіє постачальник.
+- Застарілий вхід Microsoft `edge` нормалізується до ідентифікатора постачальника `microsoft`.
+- Бажана модель володіння орієнтована на компанію: один Plugin постачальника може володіти
постачальниками тексту, мовлення, зображень і майбутніх медіа, коли OpenClaw додає ці
контракти можливостей.
Для розуміння зображень/аудіо/відео Plugin реєструють одного типізованого
-постачальника media-understanding замість generic key/value bag:
+постачальника media-understanding замість загального набору ключ/значення:
```ts
api.registerMediaUnderstandingProvider({
@@ -471,16 +477,16 @@ api.registerMediaUnderstandingProvider({
Примітки:
-- Тримайте оркестрацію, fallback, конфігурацію та прив’язку каналів у core.
-- Тримайте поведінку вендора в Plugin постачальника.
-- Additive розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові
- поля результатів, нові необов’язкові можливості.
+- Залишайте оркестрацію, fallback, конфігурацію та підключення каналів у ядрі.
+- Залишайте поведінку постачальника в Plugin постачальника.
+- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові
+ поля результату, нові необов’язкові можливості.
- Генерація відео вже дотримується того самого патерну:
- - core володіє контрактом можливості та runtime-помічником
- - Plugin вендорів реєструють `api.registerVideoGenerationProvider(...)`
- - Plugin функцій/каналів споживають `api.runtime.videoGeneration.*`
+ - ядро володіє контрактом можливості та допоміжним засобом runtime
+ - Plugin постачальників реєструють `api.registerVideoGenerationProvider(...)`
+ - Plugin функцій/каналів використовують `api.runtime.videoGeneration.*`
-Для runtime-помічників media-understanding Plugin можуть викликати:
+Для допоміжних засобів runtime media-understanding Plugin можуть викликати:
```ts
const image = await api.runtime.mediaUnderstanding.describeImageFile({
@@ -495,8 +501,8 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({
});
```
-Для транскрипції аудіо Plugin можуть використовувати або runtime media-understanding,
-або старіший alias STT:
+Для транскрибування аудіо Plugin можуть використовувати або runtime
+media-understanding, або старіший alias STT:
```ts
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
@@ -511,11 +517,11 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
- `api.runtime.mediaUnderstanding.*` є бажаною спільною поверхнею для
розуміння зображень/аудіо/відео.
-- Використовує core аудіоконфігурацію media-understanding (`tools.media.audio`) і порядок fallback постачальників.
-- Повертає `{ text: undefined }`, коли транскрипційний вивід не створено (наприклад, пропущений/непідтримуваний вхід).
-- `api.runtime.stt.transcribeAudioFile(...)` залишається compatibility alias.
+- Використовує аудіоконфігурацію ядра media-understanding (`tools.media.audio`) і порядок fallback постачальників.
+- Повертає `{ text: undefined }`, коли вихід транскрипції не створено (наприклад, пропущений/непідтримуваний вхід).
+- `api.runtime.stt.transcribeAudioFile(...)` залишається alias сумісності.
-Plugin також можуть запускати фонові subagent runs через `api.runtime.subagent`:
+Plugin також можуть запускати фонові виконання subagent через `api.runtime.subagent`:
```ts
const result = await api.runtime.subagent.run({
@@ -529,15 +535,15 @@ const result = await api.runtime.subagent.run({
Примітки:
-- `provider` і `model` є необов’язковими override для кожного run, а не постійними змінами сесії.
-- OpenClaw враховує ці override-поля лише для trusted callers.
-- Для fallback runs, якими володіє Plugin, оператори мають увімкнути `plugins.entries..subagent.allowModelOverride: true`.
-- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити trusted Plugin конкретними canonical цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль.
-- Untrusted subagent runs Plugin усе ще працюють, але override-запити відхиляються замість silent fallback.
-- Subagent-сесії, створені Plugin, позначаються ідентифікатором Plugin, що їх створив. Fallback `api.runtime.subagent.deleteSession(...)` може видаляти лише ці owned sessions; довільне видалення сесій усе ще потребує admin-scoped запиту Gateway.
+- `provider` і `model` є необов’язковими перевизначеннями для окремого запуску, а не постійними змінами сесії.
+- OpenClaw враховує ці поля перевизначення лише для довірених викликачів.
+- Для fallback-запусків, якими володіє Plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`.
+- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені Plugin конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль.
+- Недовірені subagent-запуски Plugin усе ще працюють, але запити перевизначення відхиляються, а не тихо переходять до fallback.
+- Створені Plugin subagent-сесії позначаються ідентифікатором Plugin, який їх створив. Fallback `api.runtime.subagent.deleteSession(...)` може видаляти лише ці власні сесії; довільне видалення сесій усе ще потребує admin-scoped запиту Gateway.
-Для вебпошуку Plugin можуть споживати спільний runtime-помічник замість того,
-щоб звертатися до прив’язки інструментів агента:
+Для вебпошуку Plugin можуть використовувати спільний допоміжний засіб runtime замість
+доступу до підключення інструментів агента:
```ts
const providers = api.runtime.webSearch.listProviders({
@@ -558,8 +564,8 @@ Plugin також можуть реєструвати постачальникі
Примітки:
-- Тримайте вибір постачальника, розв’язання облікових даних і спільну семантику запитів у core.
-- Використовуйте постачальників вебпошуку для специфічних для вендора пошукових транспортів.
+- Залишайте вибір постачальника, розв’язання облікових даних і спільну семантику запитів у ядрі.
+- Використовуйте постачальників вебпошуку для специфічних для постачальника транспортів пошуку.
- `api.runtime.webSearch.*` є бажаною спільною поверхнею для Plugin функцій/каналів, яким потрібна пошукова поведінка без залежності від wrapper інструмента агента.
### `api.runtime.imageGeneration`
@@ -575,12 +581,12 @@ const providers = api.runtime.imageGeneration.listProviders({
});
```
-- `generate(...)`: згенерувати зображення за допомогою налаштованого ланцюга постачальників image-generation.
-- `listProviders(...)`: перелічити доступних постачальників image-generation та їхні можливості.
+- `generate(...)`: згенерувати зображення за допомогою налаштованого ланцюга постачальників генерації зображень.
+- `listProviders(...)`: перелічити доступних постачальників генерації зображень та їхні можливості.
## HTTP-маршрути Gateway
-Plugin можуть відкривати HTTP endpoints за допомогою `api.registerHttpRoute(...)`.
+Plugin можуть відкривати HTTP endpoint за допомогою `api.registerHttpRoute(...)`.
```ts
api.registerHttpRoute({
@@ -597,206 +603,206 @@ api.registerHttpRoute({
Поля маршруту:
-- `path`: шлях маршруту під HTTP-сервером Gateway.
-- `auth`: обов’язкове. Використовуйте `"gateway"`, щоб вимагати звичайну автентифікацію Gateway, або `"plugin"` для керованої Plugin автентифікації/перевірки Webhook.
+- `path`: шлях маршруту під HTTP-сервером gateway.
+- `auth`: обов’язкове. Використовуйте `"gateway"`, щоб вимагати звичайну автентифікацію gateway, або `"plugin"` для керованої Plugin автентифікації/перевірки webhook.
- `match`: необов’язкове. `"exact"` (типово) або `"prefix"`.
- `replaceExisting`: необов’язкове. Дозволяє тому самому Plugin замінити власну наявну реєстрацію маршруту.
-- `handler`: повертайте `true`, коли маршрут обробив запит.
+- `handler`: поверніть `true`, коли маршрут обробив запит.
Примітки:
-- `api.registerHttpHandler(...)` було вилучено й спричинить помилку завантаження плагіна. Натомість використовуйте `api.registerHttpRoute(...)`.
+- `api.registerHttpHandler(...)` видалено, і це спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`.
- Маршрути Plugin мають явно оголошувати `auth`.
-- Точні конфлікти `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один плагін не може замінити маршрут іншого плагіна.
-- Перекривні маршрути з різними рівнями `auth` відхиляються. Ланцюжки переходу `exact`/`prefix` тримайте лише на одному рівні автентифікації.
-- Маршрути `auth: "plugin"` **не** отримують автоматично операторські runtime-області. Вони призначені для керованих плагіном webhooks/перевірки підписів, а не для привілейованих допоміжних викликів Gateway.
-- Маршрути `auth: "gateway"` виконуються всередині runtime-області запиту Gateway, але ця область навмисно консервативна:
- - автентифікація bearer зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) фіксує runtime-області маршрутів плагіна на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes`
- - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному вході) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній
- - якщо `x-openclaw-scopes` відсутній у таких запитах маршрутів плагіна з ідентичністю, runtime-область повертається до `operator.write`
-- Практичне правило: не припускайте, що маршрут плагіна з gateway-auth є неявною адміністративною поверхнею. Якщо вашому маршруту потрібна поведінка лише для адміністраторів, вимагайте режим автентифікації з ідентичністю та задокументуйте явний контракт заголовка `x-openclaw-scopes`.
+- Точні конфлікти `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin.
+- Перекривні маршрути з різними рівнями `auth` відхиляються. Залишайте ланцюжки переходу `exact`/`prefix` лише на одному рівні auth.
+- Маршрути `auth: "plugin"` **не** отримують автоматично операторські runtime scopes. Вони призначені для webhook/перевірки підписів, керованих plugin, а не для привілейованих допоміжних викликів Gateway.
+- Маршрути `auth: "gateway"` виконуються в межах runtime scope запиту Gateway, але цей scope навмисно консервативний:
+ - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) залишає runtime scopes маршрутів plugin прив'язаними до `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes`
+ - довірені HTTP-режими з ідентифікацією (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній
+ - якщо `x-openclaw-scopes` відсутній у таких запитах до маршруту plugin з ідентифікацією, runtime scope повертається до `operator.write`
+- Практичне правило: не вважайте plugin route з gateway-auth неявною адміністративною поверхнею. Якщо вашому маршруту потрібна поведінка лише для адміністраторів, вимагайте auth-режим з ідентифікацією та задокументуйте явний контракт заголовка `x-openclaw-scopes`.
## Шляхи імпорту Plugin SDK
-Під час створення нових плагінів використовуйте вузькі підшляхи SDK замість монолітного кореневого
-barrel `openclaw/plugin-sdk`. Основні підшляхи:
+Під час створення нових plugins використовуйте вузькі підшляхи SDK замість монолітного root barrel `openclaw/plugin-sdk`.
+Основні підшляхи:
-| Підшлях | Призначення |
+| Підшлях | Призначення |
| ----------------------------------- | -------------------------------------------------- |
-| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin |
-| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/збирання каналів |
-| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби й парасольковий контракт |
-| `openclaw/plugin-sdk/config-schema` | Схема Zod кореневого `openclaw.json` (`OpenClawSchema`) |
+| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin |
+| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби entry/build для каналу |
+| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella-контракт |
+| `openclaw/plugin-sdk/config-schema` | Коренева Zod-схема `openclaw.json` (`OpenClawSchema`) |
-Плагіни каналів вибирають із сімейства вузьких швів — `channel-setup`,
+Канальні plugins вибирають із сімейства вузьких меж — `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`, а не змішувати непов’язані
-поля плагіна. Див. [Плагіни каналів](/uk/plugins/sdk-channel-plugins).
+`channel-targets` і `channel-actions`. Поведінку схвалення слід консолідувати
+на одному контракті `approvalCapability`, а не змішувати між непов'язаними
+полями plugin. Див. [Канальні plugins](/uk/plugins/sdk-channel-plugins).
Допоміжні засоби runtime і конфігурації містяться у відповідних сфокусованих підшляхах `*-runtime`
(`approval-runtime`, `agent-runtime`, `lazy-runtime`, `directory-runtime`,
`text-runtime`, `runtime-store`, `system-event-runtime`, `heartbeat-runtime`,
-`channel-activity-runtime` тощо). Надавайте перевагу `config-types`,
+`channel-activity-runtime` тощо). Віддавайте перевагу `config-types`,
`plugin-config-runtime`, `runtime-config-snapshot` і `config-mutation`
-замість широкого сумісного barrel `config-runtime`.
+замість широкого compatibility barrel `config-runtime`.
`openclaw/plugin-sdk/channel-runtime`, `openclaw/plugin-sdk/config-runtime`
-і `openclaw/plugin-sdk/infra-runtime` — це застарілі сумісні прошарки для
-старіших плагінів. Новий код має імпортувати вужчі загальні примітиви.
+і `openclaw/plugin-sdk/infra-runtime` є застарілими compatibility shims для
+старіших plugins. Новий код має імпортувати вужчі загальні примітиви.
-Внутрішні точки входу репозиторію (для кореня кожного вбудованого пакета плагіна):
+Внутрішні entry points репозиторію (для кореня кожного bundled plugin package):
-- `index.js` — точка входу вбудованого плагіна
+- `index.js` — entry bundled plugin
- `api.js` — barrel допоміжних засобів/типів
- `runtime-api.js` — barrel лише для runtime
-- `setup-entry.js` — точка входу плагіна налаштування
+- `setup-entry.js` — entry setup plugin
-Зовнішні плагіни мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи
-не імпортуйте `src/*` іншого пакета плагіна з core або з іншого плагіна.
-Точки входу, завантажені через фасад, надають перевагу активному знімку runtime-конфігурації, коли він
-існує, а потім повертаються до розв’язаного конфігураційного файлу на диску.
+Зовнішні plugins мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи
+не імпортуйте `src/*` іншого plugin package з core або з іншого plugin.
+Entry points, завантажені через facade, віддають перевагу активному знімку runtime config, якщо він
+існує, а потім повертаються до розв'язаного config file на диску.
-Підшляхи для конкретних можливостей, як-от `image-generation`, `media-understanding`
-і `speech`, існують, бо вбудовані плагіни використовують їх сьогодні. Вони не є
-автоматично довгостроково замороженими зовнішніми контрактами — перевіряйте відповідну довідкову сторінку
-SDK, коли покладаєтеся на них.
+Підшляхи, специфічні для capabilities, як-от `image-generation`, `media-understanding`
+і `speech`, існують, бо bundled plugins використовують їх сьогодні. Вони не є
+автоматично довгостроково замороженими зовнішніми контрактами — перевіряйте відповідну сторінку довідки SDK,
+коли покладаєтеся на них.
-## Схеми інструментів повідомлень
+## Схеми message tool
-Плагіни мають володіти специфічними для каналу внесками схеми `describeMessageTool(...)`
-для примітивів, що не є повідомленнями, як-от реакції, прочитання й опитування.
-Спільне подання надсилання має використовувати загальний контракт `MessagePresentation`
-замість нативних для провайдера полів кнопок, компонентів, блоків або карток.
-Див. [Подання повідомлення](/uk/plugins/message-presentation) щодо контракту,
-правил fallback, зіставлення провайдерів і контрольного списку автора плагіна.
+Plugins мають володіти внесками до channel-specific схеми `describeMessageTool(...)`
+для не-message примітивів, як-от reactions, reads і polls.
+Спільна presentation для надсилання має використовувати загальний контракт `MessagePresentation`
+замість provider-native полів button, component, block або card.
+Див. [Message Presentation](/uk/plugins/message-presentation) щодо контракту,
+правил fallback, provider mapping і checklist для автора plugin.
-Плагіни з можливістю надсилання оголошують, що вони можуть рендерити, через можливості повідомлень:
+Plugins, здатні надсилати повідомлення, оголошують, що вони можуть відтворювати, через message capabilities:
-- `presentation` для семантичних блоків подання (`text`, `context`, `divider`, `buttons`, `select`)
-- `delivery-pin` для запитів закріпленої доставки
+- `presentation` для semantic presentation blocks (`text`, `context`, `divider`, `buttons`, `select`)
+- `delivery-pin` для запитів pinned-delivery
-Core вирішує, чи рендерити подання нативно, чи деградувати його до тексту.
-Не відкривайте нативні для провайдера UI-обхідні шляхи з загального інструмента повідомлень.
-Застарілі допоміжні засоби SDK для застарілих нативних схем залишаються експортованими для наявних
-сторонніх плагінів, але нові плагіни не повинні їх використовувати.
+Core вирішує, чи відтворювати presentation нативно, чи деградувати її до тексту.
+Не відкривайте provider-native UI escape hatches із загального message tool.
+Застарілі допоміжні засоби SDK для legacy native schemas залишаються експортованими для наявних
+сторонніх plugins, але нові plugins не повинні їх використовувати.
-## Розв’язання цілі каналу
+## Розв'язання цілі каналу
-Плагіни каналів мають володіти специфічною для каналу семантикою цілей. Тримайте спільний
-outbound host загальним і використовуйте поверхню адаптера обміну повідомленнями для правил провайдера:
+Канальні plugins мають володіти channel-specific семантикою цілей. Залишайте спільний
+outbound host загальним і використовуйте поверхню messaging adapter для правил provider:
- `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль
- слід трактувати як `direct`, `group` або `channel` перед пошуком у каталозі.
+ слід трактувати як `direct`, `group` або `channel` перед пошуком у directory.
- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи
- введення має одразу перейти до id-подібного розв’язання замість пошуку в каталозі.
-- `messaging.targetResolver.resolveTarget(...)` — це fallback плагіна, коли
- core потребує остаточного розв’язання, що належить провайдеру, після нормалізації або після
- промаху в каталозі.
-- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії,
- специфічною для провайдера, після розв’язання цілі.
+ input має одразу перейти до id-like resolution замість directory search.
+- `messaging.targetResolver.resolveTarget(...)` є fallback plugin, коли
+ core потребує остаточного provider-owned resolution після нормалізації або після
+ directory miss.
+- `messaging.resolveOutboundSessionRoute(...)` володіє provider-specific побудовою маршруту сесії,
+ коли ціль розв'язано.
Рекомендований поділ:
-- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають відбуватися перед
+- Використовуйте `inferTargetChatType` для category decisions, які мають відбуватися перед
пошуком peers/groups.
-- Використовуйте `looksLikeId` для перевірок "трактувати це як явний/нативний id цілі".
-- Використовуйте `resolveTarget` для fallback нормалізації, специфічної для провайдера, а не для
- широкого пошуку в каталозі.
-- Тримайте нативні для провайдера id, як-от chat ids, thread ids, JIDs, handles і room
- ids, усередині значень `target` або специфічних для провайдера параметрів, а не в загальних полях SDK.
+- Використовуйте `looksLikeId` для перевірок "трактувати це як explicit/native target id".
+- Використовуйте `resolveTarget` для provider-specific normalization fallback, а не для
+ широкого directory search.
+- Зберігайте provider-native ids, як-от chat ids, thread ids, JIDs, handles і room
+ ids, усередині значень `target` або provider-specific params, а не в загальних полях SDK.
-## Каталоги на основі конфігурації
+## Довідники на основі конфігурації
-Плагіни, які виводять записи каталогу з конфігурації, мають тримати цю логіку в
-плагіні та повторно використовувати спільні допоміжні засоби з
+Plugins, які виводять directory entries з конфігурації, мають тримати цю логіку в
+plugin і повторно використовувати спільні допоміжні засоби з
`openclaw/plugin-sdk/directory-runtime`.
Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, як-от:
-- DM peers, керовані allowlist
-- налаштовані мапи каналів/груп
-- статичні fallback каталогу в межах облікового запису
+- peers для DM, керовані allowlist
+- налаштовані channel/group maps
+- account-scoped static directory fallbacks
Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції:
-- фільтрація запитів
-- застосування ліміту
-- допоміжні засоби дедуплікації/нормалізації
-- побудова `ChannelDirectoryEntry[]`
+- фільтрацію запитів
+- застосування limit
+- допоміжні засоби deduping/normalization
+- побудову `ChannelDirectoryEntry[]`
-Специфічна для каналу перевірка облікового запису й нормалізація id мають залишатися в
-реалізації плагіна.
+Channel-specific inspection облікового запису та нормалізація id мають залишатися в
+реалізації plugin.
-## Каталоги провайдерів
+## Каталоги provider
-Плагіни провайдерів можуть визначати каталоги моделей для inference за допомогою
+Provider plugins можуть визначати каталоги моделей для inference за допомогою
`registerProvider({ catalog: { run(...) { ... } } })`.
`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в
`models.providers`:
-- `{ provider }` для одного запису провайдера
-- `{ providers }` для кількох записів провайдера
+- `{ provider }` для одного provider entry
+- `{ providers }` для кількох provider entries
-Використовуйте `catalog`, коли плагін володіє специфічними для провайдера id моделей, типовими значеннями
-base URL або метаданими моделей, обмеженими автентифікацією.
+Використовуйте `catalog`, коли plugin володіє provider-specific model ids, base URL
+defaults або auth-gated model metadata.
-`catalog.order` керує тим, коли каталог плагіна зливається відносно вбудованих
-неявних провайдерів OpenClaw:
+`catalog.order` керує тим, коли каталог plugin об'єднується відносно
+вбудованих implicit providers OpenClaw:
-- `simple`: прості провайдери на основі API-ключа або env
-- `profile`: провайдери, що з’являються, коли існують профілі автентифікації
-- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів
-- `late`: останній прохід, після інших неявних провайдерів
+- `simple`: звичайні providers, керовані API key або env
+- `profile`: providers, що з'являються, коли існують auth profiles
+- `paired`: providers, що синтезують кілька пов'язаних provider entries
+- `late`: останній прохід, після інших implicit providers
-Пізніші провайдери перемагають під час колізії ключів, тож плагіни можуть навмисно перевизначити
-вбудований запис провайдера з тим самим id провайдера.
+Пізніші providers перемагають під час key collision, тому plugins можуть навмисно перевизначати
+вбудований provider entry з тим самим provider id.
Сумісність:
-- `discovery` досі працює як застарілий псевдонім
+- `discovery` досі працює як legacy alias
- якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog`
-## Read-only перевірка каналу
+## Read-only inspection каналу
-Якщо ваш плагін реєструє канал, надавайте перевагу реалізації
-`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`.
+Якщо ваш plugin реєструє канал, віддавайте перевагу реалізації
+`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`.
Чому:
-- `resolveAccount(...)` — це runtime-шлях. Йому дозволено припускати, що облікові дані
+- `resolveAccount(...)` — це runtime path. Він може припускати, що credentials
повністю матеріалізовані, і швидко завершуватися помилкою, коли потрібні secrets відсутні.
-- Read-only шляхи команд, як-от `openclaw status`, `openclaw status --all`,
- `openclaw channels status`, `openclaw channels resolve`, а також потоки doctor/відновлення конфігурації
- не повинні матеріалізувати runtime-облікові дані лише для того, щоб
- описати конфігурацію.
+- Read-only command paths, як-от `openclaw status`, `openclaw status --all`,
+ `openclaw channels status`, `openclaw channels resolve`, а також потоки doctor/config
+ repair, не повинні матеріалізувати runtime credentials лише для
+ опису конфігурації.
Рекомендована поведінка `inspectAccount(...)`:
- Повертайте лише описовий стан облікового запису.
- Зберігайте `enabled` і `configured`.
-- Додавайте поля джерела/стану облікових даних, коли доречно, як-от:
+- Додавайте поля source/status для credentials, коли доречно, як-от:
- `tokenSource`, `tokenStatus`
- `botTokenSource`, `botTokenStatus`
- `appTokenSource`, `appTokenStatus`
- `signingSecretSource`, `signingSecretStatus`
-- Не потрібно повертати сирі значення токенів лише для звітування про read-only
- доступність. Повернення `tokenStatus: "available"` (і відповідного поля джерела)
- достатньо для команд у стилі status.
-- Використовуйте `configured_unavailable`, коли облікові дані налаштовані через SecretRef, але
- недоступні в поточному шляху команди.
+- Вам не потрібно повертати сирі значення token лише для повідомлення read-only
+ availability. Повернення `tokenStatus: "available"` (і відповідного поля source)
+ достатньо для status-style commands.
+- Використовуйте `configured_unavailable`, коли credential налаштовано через SecretRef, але
+ він недоступний у поточному command path.
-Це дає змогу read-only командам повідомляти "налаштовано, але недоступно в цьому шляху
-команди" замість аварійного завершення або помилкового повідомлення, що обліковий запис не налаштовано.
+Це дає read-only commands змогу повідомляти "configured but unavailable in this command
+path" замість аварійного завершення або помилкового повідомлення, що обліковий запис не налаштований.
-## Пакети пакетів
+## Пакети package
-Каталог плагіна може містити `package.json` з `openclaw.extensions`:
+Каталог plugin може містити `package.json` з `openclaw.extensions`:
```json
{
@@ -808,58 +814,58 @@ base URL або метаданими моделей, обмеженими авт
}
```
-Кожен запис стає плагіном. Якщо пакет перелічує кілька extensions, id плагіна
+Кожен entry стає plugin. Якщо pack перелічує кілька extensions, plugin id
стає `name/`.
-Якщо ваш плагін імпортує npm-залежності, установіть їх у цьому каталозі, щоб
+Якщо ваш plugin імпортує npm deps, установіть їх у цьому каталозі, щоб
`node_modules` був доступний (`npm install` / `pnpm install`).
-Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу плагіна
-після розв’язання symlink. Записи, що виходять за межі каталогу пакета,
+Security guardrail: кожен entry `openclaw.extensions` має залишатися всередині каталогу plugin
+після розв'язання symlink. Entries, що виходять за межі package directory,
відхиляються.
-Примітка щодо безпеки: `openclaw plugins install` встановлює залежності плагіна за допомогою
-локального для проєкту `npm install --omit=dev --ignore-scripts` (без lifecycle scripts,
-без dev dependencies під час runtime), ігноруючи успадковані глобальні налаштування npm install.
-Тримайте дерева залежностей плагінів "чистими JS/TS" і уникайте пакетів, які потребують
-збірок `postinstall`.
+Security note: `openclaw plugins install` встановлює залежності plugin за допомогою
+project-local `npm install --omit=dev --ignore-scripts` (без lifecycle scripts,
+без dev dependencies під час runtime), ігноруючи успадковані global npm install settings.
+Тримайте дерева залежностей plugin "pure JS/TS" і уникайте package, які потребують
+`postinstall` builds.
-Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування.
-Коли OpenClaw потребує поверхонь налаштування для вимкненого плагіна каналу або
-коли плагін каналу ввімкнений, але ще не налаштований, він завантажує `setupEntry`
-замість повної точки входу плагіна. Це робить запуск і налаштування легшими,
-коли основна точка входу вашого плагіна також під’єднує інструменти, hooks або інший runtime-only
-код.
+Необов'язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для setup.
+Коли OpenClaw потребує setup surfaces для вимкненого channel plugin або
+коли channel plugin увімкнений, але ще не налаштований, він завантажує `setupEntry`
+замість повного plugin entry. Це полегшує startup і setup,
+коли ваш main plugin entry також під'єднує tools, hooks або інший runtime-only
+code.
-Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`
-може перевести плагін каналу на той самий шлях `setupEntry` під час фази запуску Gateway
-до початку прослуховування, навіть коли канал уже налаштований.
+Необов'язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen`
+може перевести channel plugin на той самий шлях `setupEntry` під час pre-listen startup phase
+gateway, навіть коли канал уже налаштований.
-Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати
-до того, як Gateway почне слухати. На практиці це означає, що точка входу налаштування
-має зареєструвати кожну належну каналу можливість, від якої залежить запуск, як-от:
+Використовуйте це лише тоді, коли `setupEntry` повністю покриває startup surface, яка має існувати
+до того, як gateway почне слухати. На практиці це означає, що setup entry
+має зареєструвати кожну channel-owned capability, від якої залежить startup, як-от:
- сама реєстрація каналу
-- будь-які HTTP-маршрути, які мають бути доступні до того, як Gateway почне слухати
-- будь-які методи Gateway, інструменти або сервіси, які мають існувати протягом того самого вікна
+- будь-які HTTP routes, які мають бути доступні до того, як gateway почне слухати
+- будь-які gateway methods, tools або services, які мають існувати протягом того самого вікна
-Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте
-цей прапорець. Залиште плагін на стандартній поведінці й дозвольте OpenClaw завантажувати
-повну точку входу під час запуску.
+Якщо ваш full entry досі володіє будь-якою required startup capability, не вмикайте
+цей flag. Залиште plugin на default behavior і дозвольте OpenClaw завантажити
+full entry під час startup.
-Вбудовані канали також можуть публікувати setup-only допоміжні засоби контрактної поверхні, які core
-може консультувати до завантаження повного runtime каналу. Поточна поверхня просування налаштування:
+Bundled channels також можуть публікувати setup-only contract-surface helpers, до яких core
+може звертатися до завантаження повного channel runtime. Поточна setup
+promotion surface така:
- `singleAccountKeysToMove`
- `namedAccountPromotionKeys`
- `resolveSingleAccountPromotionTarget(...)`
-Core використовує цю поверхню, коли потрібно підвищити застарілу конфігурацію каналу з одним обліковим записом до `channels..accounts.*` без завантаження повного входу Plugin.
-Matrix є поточним вбудованим прикладом: він переміщує лише ключі автентифікації/bootstrap у названий підвищений обліковий запис, коли названі облікові записи вже існують, і може зберегти налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати `accounts.default`.
+Core використовує цю поверхню, коли потрібно підвищити застарілу конфігурацію каналу з одним обліковим записом до `channels..accounts.*` без завантаження повного входу плагіна. Matrix є поточним вбудованим прикладом: він переносить лише ключі автентифікації/початкового завантаження до іменованого підвищеного облікового запису, коли іменовані облікові записи вже існують, і може зберегти налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати `accounts.default`.
-Ці адаптери патчів налаштування залишають виявлення вбудованої контрактної поверхні лінивим. Час імпорту залишається легким; поверхня підвищення завантажується лише під час першого використання, замість повторного входу в запуск вбудованого каналу під час імпорту модуля.
+Ці адаптери патчів налаштування зберігають виявлення вбудованої поверхні контракту лінивим. Час імпорту залишається малим; поверхня підвищення завантажується лише під час першого використання, замість повторного входу в запуск вбудованого каналу під час імпорту модуля.
-Коли ці поверхні запуску містять методи RPC Gateway, тримайте їх на префіксі, специфічному для Plugin. Простори імен адміністратора Core (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди розв’язуються в `operator.admin`, навіть якщо Plugin запитує вужчу область.
+Коли ці стартові поверхні містять RPC-методи Gateway, тримайте їх на префіксі, специфічному для плагіна. Простори імен адміністрування Core (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди розв’язуються до `operator.admin`, навіть якщо плагін запитує вужчу область.
Приклад:
@@ -878,7 +884,7 @@ Matrix є поточним вбудованим прикладом: він пе
### Метадані каталогу каналів
-Plugins каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і підказки встановлення через `openclaw.install`. Це залишає каталог Core без даних.
+Плагіни каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і підказки встановлення через `openclaw.install`. Це дає змогу Core не містити даних каталогу.
Приклад:
@@ -908,18 +914,18 @@ Plugins каналів можуть оголошувати метадані на
Корисні поля `openclaw.channel` поза мінімальним прикладом:
-- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/стану
-- `docsLabel`: перевизначити текст посилання для посилання на документацію
-- `preferOver`: ідентифікатори Plugin/каналів нижчого пріоритету, які цей запис каталогу має випереджати
+- `detailLabel`: вторинна мітка для насиченіших поверхонь каталогу/стану
+- `docsLabel`: перевизначає текст посилання для посилання на документацію
+- `preferOver`: ідентифікатори плагінів/каналів із нижчим пріоритетом, які цей запис каталогу має випереджати
- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору
-- `markdownCapable`: позначає канал як здатний працювати з Markdown для рішень щодо вихідного форматування
-- `exposure.configured`: приховати канал із поверхонь списку налаштованих каналів, коли встановлено `false`
-- `exposure.setup`: приховати канал з інтерактивних засобів вибору налаштування/конфігурування, коли встановлено `false`
-- `exposure.docs`: позначити канал як внутрішній/приватний для поверхонь навігації документації
+- `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо вихідного форматування
+- `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, коли встановлено `false`
+- `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурування, коли встановлено `false`
+- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації
- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure`
-- `quickstartAllowFrom`: увімкнути канал у стандартний потік швидкого старту `allowFrom`
-- `forceAccountBinding`: вимагати явного прив’язування облікового запису, навіть коли існує лише один обліковий запис
-- `preferSessionLookupForAnnounceTarget`: віддавати перевагу пошуку сеансу під час розв’язання цілей оголошення
+- `quickstartAllowFrom`: вмикає канал у стандартний потік швидкого старту `allowFrom`
+- `forceAccountBinding`: вимагає явного прив’язування облікового запису, навіть коли існує лише один обліковий запис
+- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сеансу під час розв’язання цілей оголошень
OpenClaw також може об’єднувати **зовнішні каталоги каналів** (наприклад, експорт реєстру MPM). Помістіть JSON-файл в одне з таких місць:
@@ -927,19 +933,17 @@ OpenClaw також може об’єднувати **зовнішні ката
- `~/.openclaw/mpm/catalog.json`
- `~/.openclaw/plugins/catalog.json`
-Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (чи `OPENCLAW_MPM_CATALOG_PATHS`) на один або кілька JSON-файлів (розділених комами/крапками з комою/`PATH`). Кожен файл має містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`.
+Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на один чи кілька JSON-файлів (розділених комами/крапками з комою/`PATH`). Кожен файл має містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`.
-Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів надають нормалізовані факти джерела встановлення поруч із сирим блоком `openclaw.install`. Нормалізовані факти визначають, чи npm-специфікація є точною версією або плаваючим селектором, чи наявні очікувані метадані цілісності, і чи також доступний локальний шлях джерела. Коли ідентичність каталогу/пакета відома, нормалізовані факти попереджають, якщо розібрана назва npm-пакета відхиляється від цієї ідентичності. Вони також попереджають, коли `defaultChoice` недійсний або вказує на недоступне джерело, і коли метадані цілісності npm наявні без дійсного джерела npm. Споживачі мають трактувати `installSource` як додаткове необов’язкове поле, щоб записи, створені вручну, і прокладки каталогу не мусили його синтезувати.
-Це дає онбордингу та діагностиці змогу пояснювати стан площини джерел без імпортування runtime Plugin.
+Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів показують нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Нормалізовані факти визначають, чи є npm-специфікація точною версією або плаваючим селектором, чи присутні очікувані метадані цілісності та чи доступний також локальний шлях джерела. Коли ідентичність каталогу/пакета відома, нормалізовані факти попереджають, якщо розібране ім’я npm-пакета відхиляється від цієї ідентичності. Вони також попереджають, коли `defaultChoice` недійсний або вказує на недоступне джерело, а також коли метадані цілісності npm присутні без дійсного джерела npm. Споживачі мають розглядати `installSource` як додаткове необов’язкове поле, щоб записи, створені вручну, і прокладки каталогу не мусили його синтезувати. Це дає змогу онбордингу й діагностиці пояснювати стан площини джерел без імпорту середовища виконання плагіна.
-Офіційні зовнішні npm-записи мають віддавати перевагу точному `npmSpec` разом із `expectedIntegrity`. Голі назви пакетів і dist-tags усе ще працюють для сумісності, але вони показують попередження площини джерел, щоб каталог міг рухатися до закріплених встановлень із перевіркою цілісності без порушення наявних Plugins.
-Коли онбординг встановлює з локального шляху каталогу, він записує керований запис індексу Plugin із `source: "path"` і відносним до робочого простору `sourcePath`, коли це можливо. Абсолютний операційний шлях завантаження залишається в `plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів робочої станції в довготривалу конфігурацію. Це залишає локальні встановлення для розробки видимими для діагностики площини джерел без додавання другої поверхні розкриття сирого шляху файлової системи. Збережений індекс Plugin `plugins/installs.json` є джерелом істини для джерела встановлення і може оновлюватися без завантаження runtime-модулів Plugin. Його мапа `installRecords` є довговічною, навіть коли маніфест Plugin відсутній або недійсний; його масив `plugins` є відновлюваним представленням маніфестів.
+Офіційні зовнішні npm-записи мають віддавати перевагу точному `npmSpec` разом із `expectedIntegrity`. Голі імена пакетів і dist-tag-и все ще працюють для сумісності, але вони показують попередження площини джерел, щоб каталог міг рухатися до закріплених встановлень із перевіркою цілісності без ламання наявних плагінів. Коли онбординг встановлює з локального шляху каталогу, він записує керований запис індексу плагіна з `source: "path"` і відносним до робочої області `sourcePath`, коли це можливо. Абсолютний робочий шлях завантаження залишається в `plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів робочої станції в довготривалу конфігурацію. Це зберігає встановлення для локальної розробки видимими для діагностики площини джерел без додавання другої сирої поверхні розкриття шляху файлової системи. Збережений індекс плагінів `plugins/installs.json` є джерелом істини для встановлення й може оновлюватися без завантаження модулів середовища виконання плагінів. Його мапа `installRecords` є довговічною навіть тоді, коли маніфест плагіна відсутній або недійсний; його масив `plugins` є перебудовуваним поданням маніфесту.
-## Plugins контекстного рушія
+## Плагіни контекстного рушія
-Plugins контекстного рушія володіють оркестрацією контексту сеансу для приймання, складання та Compaction. Зареєструйте їх зі свого Plugin через `api.registerContextEngine(id, factory)`, а потім виберіть активний рушій за допомогою `plugins.slots.contextEngine`.
+Плагіни контекстного рушія відповідають за оркестрацію контексту сеансу для приймання, збирання та Compaction. Зареєструйте їх зі свого плагіна через `api.registerContextEngine(id, factory)`, а потім виберіть активний рушій за допомогою `plugins.slots.contextEngine`.
-Використовуйте це, коли вашому Plugin потрібно замінити або розширити типовий конвеєр контексту, а не просто додати пошук у пам’яті чи hooks.
+Використовуйте це, коли вашому плагіну потрібно замінити або розширити стандартний конвеєр контексту, а не просто додати пошук пам’яті чи хуки.
```ts
import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
@@ -967,9 +971,9 @@ export default function (api) {
}
```
-Фабрика `ctx` надає необов’язкові значення `config`, `agentDir` і `workspaceDir` для ініціалізації під час конструювання.
+Фабрика `ctx` надає необов’язкові значення `config`, `agentDir` і `workspaceDir` для ініціалізації під час створення.
-Якщо ваш рушій **не** володіє алгоритмом Compaction, залиште `compact()` реалізованим і делегуйте його явно:
+Якщо ваш рушій **не** володіє алгоритмом Compaction, залиште `compact()` реалізованим і явно делегуйте його:
```ts
import {
@@ -1006,41 +1010,41 @@ export default function (api) {
## Додавання нової можливості
-Коли Plugin потребує поведінки, яка не вписується в поточний API, не обходьте систему Plugin приватним проникненням усередину. Додайте відсутню можливість.
+Коли плагіну потрібна поведінка, яка не вкладається в поточний API, не обходьте систему плагінів приватним проникненням усередину. Додайте відсутню можливість.
Рекомендована послідовність:
1. визначте контракт Core
- Вирішіть, якою спільною поведінкою має володіти Core: політикою, fallback, злиттям конфігурації, життєвим циклом, семантикою для каналів і формою runtime helper.
-2. додайте типізовані поверхні реєстрації/runtime Plugin
+ Вирішіть, яку спільну поведінку має контролювати Core: політику, резервний шлях, об’єднання конфігурації, життєвий цикл, семантику для каналів і форму допоміжного засобу середовища виконання.
+2. додайте типізовані поверхні реєстрації/середовища виконання плагіна
Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною типізованою поверхнею можливості.
-3. з’єднайте Core + споживачів каналів/функцій
- Канали та функціональні Plugins мають споживати нову можливість через Core, а не шляхом прямого імпорту реалізації постачальника.
+3. під’єднайте споживачів Core + каналів/функцій
+ Канали й функціональні плагіни мають споживати нову можливість через Core, а не імпортувати реалізацію постачальника напряму.
4. зареєструйте реалізації постачальників
- Plugins постачальників потім реєструють свої бекенди для цієї можливості.
+ Потім плагіни постачальників реєструють свої бекенди для цієї можливості.
5. додайте покриття контракту
- Додайте тести, щоб володіння та форма реєстрації з часом залишалися явними.
+ Додайте тести, щоб форма володіння й реєстрації з часом залишалася явною.
-Так OpenClaw залишається принциповим, не стаючи жорстко закодованим під світогляд одного провайдера. Див. [кулінарну книгу можливостей](/uk/plugins/architecture) для конкретного контрольного списку файлів і пропрацьованого прикладу.
+Саме так OpenClaw залишається принциповим, не стаючи жорстко прив’язаним до світогляду одного провайдера. Див. [Кулінарну книгу можливостей](/uk/plugins/architecture) для конкретного контрольного списку файлів і опрацьованого прикладу.
### Контрольний список можливості
-Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих поверхонь разом:
+Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися таких поверхонь:
- типи контракту Core у `src//types.ts`
-- runner/runtime helper Core у `src//runtime.ts`
-- поверхня реєстрації API Plugin у `src/plugins/types.ts`
-- підключення реєстру Plugin у `src/plugins/registry.ts`
-- runtime-експозиція Plugin у `src/plugins/runtime/*`, коли функціональні/канальні Plugins мають її споживати
-- helpers захоплення/тестів у `src/test-utils/plugin-registration.ts`
-- твердження володіння/контракту в `src/plugins/contracts/registry.ts`
-- документація оператора/Plugin у `docs/`
+- допоміжний засіб запуску/середовища виконання Core у `src//runtime.ts`
+- поверхня реєстрації API плагіна у `src/plugins/types.ts`
+- під’єднання реєстру плагінів у `src/plugins/registry.ts`
+- експонування середовища виконання плагіна у `src/plugins/runtime/*`, коли функціональним/канальним плагінам потрібно його споживати
+- допоміжні засоби захоплення/тестування у `src/test-utils/plugin-registration.ts`
+- твердження про володіння/контракт у `src/plugins/contracts/registry.ts`
+- документація для оператора/плагіна у `docs/`
-Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість ще не повністю інтегрована.
+Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість ще не повністю інтегрована.
### Шаблон можливості
-Мінімальний патерн:
+Мінімальний шаблон:
```ts
// core contract
@@ -1066,22 +1070,22 @@ const clip = await api.runtime.videoGeneration.generate({
});
```
-Патерн тесту контракту:
+Шаблон тесту контракту:
```ts
expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);
```
-Це залишає правило простим:
+Це зберігає правило простим:
- Core володіє контрактом можливості + оркестрацією
-- Plugins постачальників володіють реалізаціями постачальників
-- функціональні/канальні Plugins споживають runtime helpers
-- тести контракту залишають володіння явним
+- плагіни постачальників володіють реалізаціями постачальників
+- функціональні/канальні плагіни споживають допоміжні засоби середовища виконання
+- тести контракту зберігають володіння явним
## Пов’язане
-- [Архітектура Plugin](/uk/plugins/architecture) — публічна модель можливостей і форми
-- [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths)
-- [Налаштування Plugin SDK](/uk/plugins/sdk-setup)
-- [Створення Plugins](/uk/plugins/building-plugins)
+- [Архітектура плагінів](/uk/plugins/architecture) — публічна модель і форми можливостей
+- [Підшляхи SDK плагінів](/uk/plugins/sdk-subpaths)
+- [Налаштування SDK плагінів](/uk/plugins/sdk-setup)
+- [Створення плагінів](/uk/plugins/building-plugins)