diff --git a/docs/uk/plugins/architecture-internals.md b/docs/uk/plugins/architecture-internals.md index 2a7bfe48e..dd42f16d1 100644 --- a/docs/uk/plugins/architecture-internals.md +++ b/docs/uk/plugins/architecture-internals.md @@ -1,142 +1,144 @@ --- read_when: - - Реалізація runtime-хуків провайдера, життєвого циклу каналу або пакетних наборів - - Налагодження порядку завантаження Plugin або стану реєстру - - Додавання нової можливості Plugin або Plugin рушія контексту -summary: 'Внутрішні аспекти архітектури Plugin: конвеєр завантаження, реєстр, runtime-хуки, HTTP-маршрути та довідкові таблиці' + - Реалізація хуків середовища виконання провайдера, життєвого циклу каналу або пакетних наборів + - Налагодження порядку завантаження plugin або стану реєстру + - Додавання нової можливості plugin або plugin рушія контексту +summary: 'Внутрішні аспекти архітектури Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці' title: Внутрішні аспекти архітектури Plugin x-i18n: - generated_at: "2026-04-24T20:11:17Z" + generated_at: "2026-04-24T20:18:23Z" model: gpt-5.4 provider: openai - source_hash: 4926ca8b020752da694749f8fc43a246c7f4499a404192408dfdc9611f721ebb + source_hash: 0e505155ee2acc84f7f26fa81b62121f03a998b249886d74f798c0f258bd8da4 source_path: plugins/architecture-internals.md workflow: 15 --- -Щодо публічної моделі можливостей, форм Plugin, а також контрактів -володіння/виконання, див. [Архітектура Plugin](/uk/plugins/architecture). Ця сторінка є -довідником щодо внутрішньої механіки: конвеєра завантаження, реєстру, runtime-хуків, +Для загальнодоступної моделі можливостей, форм plugin, а також контрактів +володіння/виконання див. [Plugin architecture](/uk/plugins/architecture). Ця сторінка — +довідник щодо внутрішньої механіки: конвеєра завантаження, реєстру, хуків середовища виконання, HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем. ## Конвеєр завантаження Під час запуску OpenClaw приблизно виконує таке: -1. виявляє кореневі каталоги потенційних Plugin -2. зчитує маніфести нативних або сумісних пакетів і метадані пакетів -3. відхиляє небезпечні кандидати -4. нормалізує конфігурацію Plugin (`plugins.enabled`, `allow`, `deny`, `entries`, +1. виявляє корені кандидатів plugin +2. зчитує маніфести нативних або сумісних збірок і метадані пакетів +3. відхиляє небезпечних кандидатів +4. нормалізує конфігурацію plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. вирішує, чи вмикати кожного кандидата -6. завантажує ввімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач; - незібрані нативні Plugin використовують jiti -7. викликає нативні хуки `register(api)` і збирає реєстрації в реєстр Plugin -8. надає реєстр поверхням команд/runtime +5. визначає, чи увімкнено кожного кандидата +6. завантажує увімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач; + незібрані нативні plugin використовують jiti +7. викликає нативні хуки `register(api)` і збирає реєстрації до реєстру plugin +8. надає реєстр поверхням команд/середовища виконання -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це на тій самій стадії. Усі вбудовані Plugin використовують `register`; для нових Plugin слід надавати перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає його в тій самій точці. Усі вбудовані plugin використовують `register`; для нових plugin надавайте перевагу `register`. -Перевірки безпеки відбуваються **до** виконання runtime. Кандидати блокуються, -коли точка входу виходить за межі кореня Plugin, шлях доступний для запису всім, або -володіння шляхом виглядає підозрілим для невбудованих Plugin. +Перевірки безпеки відбуваються **до** виконання в середовищі виконання. Кандидати блокуються, +коли точка входу виходить за межі кореня plugin, шлях доступний для запису всім, або +володіння шляхом виглядає підозрілим для невбудованих plugin. ### Поведінка з пріоритетом маніфесту -Маніфест є джерелом істини для control plane. OpenClaw використовує його, щоб: +Маніфест — це джерело істини для control plane. OpenClaw використовує його, щоб: -- ідентифікувати Plugin -- виявляти оголошені канали/Skills/схему конфігурації або можливості пакета +- ідентифікувати plugin +- виявляти оголошені канали/Skills/схему конфігурації або можливості збірки - перевіряти `plugins.entries..config` -- доповнювати мітки/placeholder-и Control UI +- доповнювати мітки/заповнювачі Control UI - показувати метадані встановлення/каталогу -- зберігати дешеві дескриптори активації та налаштування без завантаження runtime Plugin +- зберігати дешеві дескриптори активації та налаштування без завантаження середовища виконання plugin -Для нативних Plugin runtime-модуль є частиною data plane. Він реєструє -фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдерів. +Для нативних plugin модуль середовища виконання є частиною data plane. Він реєструє +фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера. Необов’язкові блоки маніфесту `activation` і `setup` залишаються в control plane. -Це лише дескриптори метаданих для планування активації та виявлення налаштування; -вони не замінюють реєстрацію runtime, `register(...)` або `setupEntry`. -Перші споживачі живої активації тепер використовують підказки маніфесту щодо команд, каналів і провайдерів, -щоб звузити завантаження Plugin до ширшої матеріалізації реєстру: +Це дескриптори лише з метаданими для планування активації та виявлення налаштування; +вони не замінюють реєстрацію в середовищі виконання, `register(...)` або `setupEntry`. +Перші активні споживачі активації тепер використовують підказки маніфесту щодо команд, каналів і провайдерів, +щоб звузити завантаження plugin до ширшої матеріалізації реєстру: -- завантаження CLI звужується до Plugin, яким належить запитана основна команда -- налаштування каналу/визначення Plugin звужується до Plugin, яким належить - запитаний id каналу -- явне визначення налаштування/runtime провайдера звужується до Plugin, яким належить - запитаний id провайдера +- завантаження CLI звужується до plugin, які володіють запитаною основною командою +- налаштування каналу/визначення plugin звужується до plugin, які володіють запитаним + ідентифікатором каналу +- явне визначення налаштування/середовища виконання провайдера звужується до plugin, які володіють + запитаним ідентифікатором провайдера -Планувальник активації надає як API лише з id для наявних викликачів, так і -API плану для нової діагностики. Записи плану повідомляють, чому Plugin було вибрано, -відокремлюючи явні підказки планувальника `activation.*` від запасного варіанта -володіння через маніфест, такого як `providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і хуки. Це розділення причин є межею сумісності: -наявні метадані Plugin продовжують працювати, тоді як новий код може виявляти широкі підказки -або запасну поведінку без зміни семантики завантаження runtime. +Планувальник активації надає як API лише з ідентифікаторами для наявних викликів, так і +API плану для нової діагностики. Записи плану повідомляють, чому plugin було вибрано, +відокремлюючи явні підказки планувальника `activation.*` від резервного +володіння за маніфестом, такого як `providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і хуки. Цей поділ причин є межею сумісності: +наявні метадані plugin і далі працюють, водночас новий код може виявляти широкі підказки +або резервну поведінку без зміни семантики завантаження середовища виконання. -Виявлення налаштування тепер надає перевагу id, що належать дескрипторам, таким як `setup.providers` і -`setup.cliBackends`, щоб звузити кандидатів Plugin, перш ніж воно повернеться до -`setup-api` для Plugin, яким усе ще потрібні runtime-хуки на етапі налаштування. Явне -`setup.requiresRuntime: false` є межею лише для дескриптора; пропущене -`requiresRuntime` зберігає застарілий запасний варіант `setup-api` для сумісності. Якщо більше -ніж один виявлений Plugin заявляє про той самий нормалізований id провайдера налаштування або -CLI backend, пошук налаштування відхиляє неоднозначного власника замість покладатися на -порядок виявлення. Коли runtime налаштування все ж виконується, діагностика реєстру повідомляє про -розходження між `setup.providers` / `setup.cliBackends` і провайдерами або CLI -backend-ами, зареєстрованими через setup-api, не блокуючи застарілі Plugin. +Виявлення налаштування тепер надає перевагу ідентифікаторам, якими володіє дескриптор, таким як `setup.providers` і +`setup.cliBackends`, щоб звузити кандидатів plugin до того, як воно повернеться до +`setup-api` для plugin, яким усе ще потрібні хуки середовища виконання під час налаштування. Потік +налаштування провайдера спочатку використовує маніфест `providerAuthChoices`, а потім +повертається до виборів майстра середовища виконання і виборів каталогу встановлення для сумісності. Явне +`setup.requiresRuntime: false` є відсіканням лише на рівні дескриптора; пропущене +`requiresRuntime` зберігає застарілий резервний перехід до setup-api для сумісності. Якщо більше +ніж один виявлений plugin заявляє права на той самий нормалізований ідентифікатор провайдера налаштування або +бекенда CLI, пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на +порядок виявлення. Коли середовище виконання налаштування все ж запускається, діагностика реєстру повідомляє про +розбіжності між `setup.providers` / `setup.cliBackends` і провайдерами або +бекендами CLI, зареєстрованими через setup-api, не блокуючи застарілі plugin. ### Що кешує завантажувач -OpenClaw зберігає короткоживучі кеші в межах процесу для: +OpenClaw зберігає короткочасні внутрішньопроцесні кеші для: - результатів виявлення - даних реєстру маніфестів -- завантажених реєстрів Plugin +- завантажених реєстрів plugin -Ці кеші зменшують сплески навантаження під час запуску та накладні витрати на повторні команди. Їх безпечно -сприймати як короткоживучі кеші продуктивності, а не як сховище. +Ці кеші зменшують сплески під час запуску та накладні витрати повторних команд. Їх безпечно +сприймати як короткоживучі кеші продуктивності, а не як постійне зберігання. Примітка щодо продуктивності: -- Установіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або +- Встановіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, щоб вимкнути ці кеші. -- Налаштовуйте вікна кешу через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і +- Налаштовуйте часові вікна кешу за допомогою `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Модель реєстру -Завантажені Plugin не змінюють напряму довільні глобальні об’єкти ядра. Вони реєструються в -центральному реєстрі Plugin. +Завантажені plugin не змінюють безпосередньо довільні глобальні об’єкти ядра. Вони реєструються в +центральному реєстрі plugin. Реєстр відстежує: -- записи Plugin (ідентичність, джерело, походження, статус, діагностика) +- записи plugin (ідентичність, джерело, походження, статус, діагностика) - інструменти -- застарілі хуки та типізовані хуки +- застарілі хуки й типізовані хуки - канали - провайдерів - обробники Gateway RPC - HTTP-маршрути -- CLI-реєстратори -- фонові сервіси -- команди, що належать Plugin +- реєстратори CLI +- фонові служби +- команди, що належать plugin -Потім можливості ядра зчитують дані з цього реєстру замість прямої взаємодії з модулями Plugin. -Це зберігає односпрямованість завантаження: +Потім можливості ядра читають із цього реєстру замість прямої взаємодії з модулями plugin. +Це підтримує одностороннє завантаження: -- модуль Plugin -> реєстрація в реєстрі -- runtime ядра -> споживання реєстру +- модуль plugin -> реєстрація в реєстрі +- середовище виконання ядра -> споживання реєстру -Це розділення важливе для зручності підтримки. Воно означає, що більшості поверхонь ядра потрібна -лише одна точка інтеграції: «прочитати реєстр», а не «окремо обробляти кожен модуль Plugin». +Це розділення важливе для супроводу. Воно означає, що більшості поверхонь ядра потрібна +лише одна точка інтеграції: «читати реєстр», а не «створювати окрему логіку для кожного модуля plugin». -## Колбеки прив’язування розмов +## Колбеки прив’язки розмови -Plugin, які прив’язують розмову, можуть реагувати, коли погодження завершено. +Plugin, які прив’язують розмову, можуть реагувати, коли погодження вирішено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек після того, як запит на прив’язування буде схвалено або відхилено: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек після того, як запит на прив’язку буде схвалено або відхилено: ```ts export default { @@ -144,7 +146,7 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // Для цього Plugin + розмови тепер існує прив’язування. + // Тепер для цього plugin + розмови існує прив’язка. console.log(event.binding?.conversationId); return; } @@ -160,112 +162,111 @@ export default { - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` -- `binding`: вирішене прив’язування для схвалених запитів -- `request`: підсумок початкового запиту, підказка від’єднання, id відправника та +- `binding`: визначена прив’язка для схвалених запитів +- `request`: початковий підсумок запиту, підказка від’єднання, ідентифікатор відправника та метадані розмови -Цей колбек призначений лише для сповіщення. Він не змінює, хто має право прив’язувати -розмову, і виконується після завершення обробки погодження ядром. +Цей колбек призначений лише для сповіщення. Він не змінює те, кому дозволено прив’язувати +розмову, і виконується після завершення обробки погодження в ядрі. -## Runtime-хуки провайдера +## Хуки середовища виконання провайдера -Plugin провайдерів мають три шари: +Plugin провайдера мають три шари: -- **Метадані маніфесту** для дешевого пошуку до runtime: +- **Метадані маніфесту** для дешевого пошуку до запуску середовища виконання: `setup.providers[].envVars`, застарілий сумісний `providerAuthEnvVars`, `providerAuthAliases`, `providerAuthChoices` і `channelEnvVars`. - **Хуки часу конфігурації**: `catalog` (застарілий `discovery`) плюс `applyConfigDefaults`. -- **Runtime-хуки**: понад 40 необов’язкових хуків для auth, визначення моделі, - обгортання потоку, рівнів thinking, політики повторного відтворення та - кінцевих точок usage. Повний список див. у [Порядок і використання хуків](#hook-order-and-usage). +- **Хуки середовища виконання**: понад 40 необов’язкових хуків, що охоплюють автентифікацію, визначення моделей, + обгортання потоків, рівні thinking, політику відтворення та кінцеві точки використання. Див. + повний список у розділі [Порядок і використання хуків](#hook-order-and-usage). -OpenClaw, як і раніше, відповідає за загальний цикл агента, failover, обробку transcript і -політику інструментів. Ці хуки є поверхнею розширення для поведінки, специфічної для провайдера, -без потреби в цілком власному транспорті inference. +OpenClaw, як і раніше, володіє загальним циклом агента, failover, обробкою транскриптів і +політикою інструментів. Ці хуки є поверхнею розширення для поведінки, специфічної для провайдера, +без потреби в цілому користувацькому транспорті інференсу. -Використовуйте маніфест `setup.providers[].envVars`, коли провайдер має облікові дані на основі env, -які загальні шляхи auth/status/model-picker мають бачити без -завантаження runtime Plugin. Застарілий `providerAuthEnvVars` усе ще зчитується -адаптером сумісності протягом періоду знецінення, а невбудовані Plugin, -які його використовують, отримують діагностику маніфесту. Використовуйте маніфест `providerAuthAliases`, -коли один id провайдера має повторно використовувати env vars, профілі auth, -auth на основі конфігурації та варіант onboarding API-ключа іншого id провайдера. Використовуйте маніфест -`providerAuthChoices`, коли поверхні CLI onboarding/вибору auth мають знати -id вибору провайдера, мітки груп і просте auth-підключення з одним прапорцем без -завантаження runtime провайдера. Залишайте runtime -`envVars` провайдера для підказок, орієнтованих на операторів, таких як мітки onboarding або змінні -налаштування OAuth client-id/client-secret. +Використовуйте маніфест `setup.providers[].envVars`, коли провайдер має облікові дані на основі змінних середовища, які повинні бути видимими для загальних шляхів автентифікації/стану/вибору моделі без +завантаження середовища виконання plugin. Застарілий `providerAuthEnvVars` усе ще зчитується +адаптером сумісності протягом вікна застарівання, а невбудовані plugin, які його використовують, +отримують діагностику маніфесту. Використовуйте маніфест `providerAuthAliases`, коли один +ідентифікатор провайдера має повторно використовувати env vars, профілі автентифікації, +автентифікацію на основі конфігурації та варіант онбордингу з API-ключем іншого ідентифікатора провайдера. Використовуйте маніфест +`providerAuthChoices`, коли поверхні CLI онбордингу/вибору автентифікації повинні знати +ідентифікатор вибору провайдера, мітки групи та просте підключення автентифікації одним прапорцем без +завантаження середовища виконання провайдера. Залишайте `envVars` у середовищі виконання провайдера +для підказок, орієнтованих на операторів, таких як мітки онбордингу або змінні налаштування +client-id/client-secret OAuth. -Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування на основі env, які -загальний запасний варіант shell-env, перевірки config/status або запити налаштування мають бачити -без завантаження runtime каналу. +Використовуйте маніфест `channelEnvVars`, коли канал має автентифікацію або налаштування, керовані env, +які повинні бути видимими загальному резервному шляху shell-env, перевіркам config/status або підказкам налаштування +без завантаження середовища виконання каналу. ### Порядок і використання хуків -Для Plugin моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку. -Стовпець «Коли використовувати» — це короткий довідник для вибору. +Для plugin моделі/провайдера OpenClaw викликає хуки приблизно в такому порядку. +Стовпець «Коли використовувати» — це короткий посібник для вибору. -| # | Хук | Що він робить | Коли використовувати | -| --- | --------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями `base URL` | -| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму auth, env або семантики сімейства моделей провайдера | -| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(не є хуком Plugin)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним визначенням моделі | -| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдерів перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для користувацьких id провайдерів у тому самому сімействі транспортів | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням runtime/провайдера | Провайдеру потрібне очищення конфігурації, яке має бути в Plugin; вбудовані помічники сімейства Google також підстраховують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-перезаписи native streaming-usage до конфігурацій провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, керовані кінцевими точками | -| 7 | `resolveConfigApiKey` | Визначає auth з env-marker для конфігурацій провайдерів до завантаження runtime auth | Провайдер має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований AWS-резолвер env-marker | -| 8 | `resolveSyntheticAuth` | Показує локальний/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | -| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth-профілі, що належать провайдеру; типове значення `persistence` — `runtime-only` для облікових даних CLI/додатка | Провайдер повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті | -| 10 | `shouldDeferSyntheticProfileAuth` | Опускає збережені заповнювачі синтетичних профілів нижче auth на основі env/конфігурації | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет | -| 11 | `resolveDynamicModel` | Синхронний запасний варіант для id моделей провайдера, яких ще немає в локальному реєстрі | Провайдер приймає довільні id моделей від зовнішнього джерела | -| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | -| 13 | `normalizeResolvedModel` | Остаточний перезапис перед тим, як вбудований runner використовує визначену модель | Провайдеру потрібні перезаписи транспорту, але він усе ще використовує транспорт ядра | -| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей постачальника за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспортах, не перебираючи на себе роль провайдера | -| 15 | `capabilities` | Метадані transcript/інструментів, що належать провайдеру та використовуються спільною логікою ядра | Провайдеру потрібні особливості transcript/сімейства провайдерів | -| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований runner | Провайдеру потрібне очищення схем для сімейства транспортів | -| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження щодо ключових слів без навчання ядра правилам, специфічним для провайдера | -| 18 | `resolveReasoningOutputMode` | Вибирає контракт виводу reasoning: native чи tagged | Провайдеру потрібен tagged reasoning/final output замість native-полів | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним транспортом | Провайдеру потрібен власний wire protocol, а не просто обгортка | -| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності заголовків/тіла запиту/моделі без власного транспорту | -| 22 | `resolveTransportTurnState` | Прикріплює native-заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали native-ідентичність ходу, специфічну для провайдера | -| 23 | `resolveWebSocketSessionPolicy` | Прикріплює native-заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику запасного варіанта | -| 24 | `formatApiKey` | Форматувач auth-профілю: збережений профіль стає рядком runtime `apiKey` | Провайдер зберігає додаткові метадані auth і потребує власної форми runtime-токена | -| 25 | `refreshOAuth` | Перевизначення OAuth refresh для користувацьких кінцевих точок refresh або політики збоїв refresh | Провайдер не відповідає спільним refresher-ам `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка для виправлення, що додається, коли збій стається під час OAuth refresh | Провайдеру потрібні власні вказівки щодо відновлення auth після збою refresh | -| 27 | `matchesContextOverflowError` | Матчер переповнення context window, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики не помічають | -| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо | -| 29 | `isCacheTtlEligible` | Політика prompt-cache для проксі/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для проксі | -| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення про відсутній auth | Провайдеру потрібна підказка відновлення після відсутнього auth, специфічна для провайдера | -| 31 | `suppressBuiltInModel` | Приховування застарілих моделей зовнішнього джерела плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі рядки зовнішнього джерела або замінити їх підказкою постачальника | -| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Провайдеру потрібні синтетичні рядки прямої сумісності в `models list` і засобах вибору | -| 33 | `resolveThinkingProfile` | Набір рівнів `/think`, мітки відображення та типове значення для конкретної моделі | Провайдер надає власну шкалу thinking або двійкову мітку для вибраних моделей | -| 34 | `isBinaryThinking` | Хук сумісності для перемикача reasoning увімк./вимк. | Провайдер підтримує лише двійкове thinking: увімк./вимк. | -| 35 | `supportsXHighThinking` | Хук сумісності для підтримки reasoning `xhigh` | Провайдер хоче мати `xhigh` лише для підмножини моделей | -| 36 | `resolveDefaultThinkingLevel` | Хук сумісності для типового рівня `/think` | Провайдер володіє типовою політикою `/think` для сімейства моделей | -| 37 | `isModernModelRef` | Матчер сучасних моделей для фільтрів live-профілів і вибору smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke | -| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime-токен/ключ безпосередньо перед inference | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | -| 39 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` і пов’язаних поверхонь статусу | Провайдеру потрібен користувацький розбір usage/quota-токена або інші облікові дані usage | -| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки usage/quota, специфічні для провайдера, після визначення auth | Провайдеру потрібна кінцева точка usage або парсер корисного навантаження, специфічні для провайдера | -| 41 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для memory/search | Поведінка memory embedding має належати Plugin провайдера | -| 42 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою transcript для провайдера | Провайдеру потрібна користувацька політика transcript (наприклад, видалення блоків thinking) | -| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення transcript | Провайдеру потрібні специфічні для провайдера перезаписи replay понад спільні помічники Compaction | -| 44 | `validateReplayTurns` | Остаточна перевірка або переформування ходів replay перед вбудованим runner | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санітизації | -| 45 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан провайдера, коли модель стає активною | +| # | Хук | Що він робить | Коли використовувати | +| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями base URL | +| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму автентифікації, env або семантики сімейства моделей провайдера | +| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(не хук plugin)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним визначенням моделі | +| 4 | `normalizeTransport` | Нормалізує сімейство провайдера `api` / `baseUrl` перед загальним складанням моделі | Провайдер володіє очищенням транспорту для користувацьких ідентифікаторів провайдера в тому самому сімействі транспорту | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням середовища виконання/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із plugin; вбудовані помічники сімейства Google також страхують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування використання нативного потокового режиму до конфігурованих провайдерів | Провайдеру потрібні виправлення метаданих використання нативного потокового режиму, що залежать від кінцевої точки | +| 7 | `resolveConfigApiKey` | Визначає автентифікацію через env-marker для конфігурованих провайдерів до завантаження автентифікації середовища виконання | Провайдер має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований AWS-розпізнавач env-marker | +| 8 | `resolveSyntheticAuth` | Показує локальну/self-hosted або засновану на конфігурації автентифікацію без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | +| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі автентифікації, що належать провайдеру; типове значення `persistence` — `runtime-only` для облікових даних, що належать CLI/застосунку | Провайдер повторно використовує зовнішні облікові дані автентифікації без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті | +| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених синтетичних заповнювачів профілю порівняно з автентифікацією на основі env/конфігурації | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет | +| 11 | `resolveDynamicModel` | Синхронний резервний шлях для model id, що належать провайдеру, яких ще немає в локальному реєстрі | Провайдер приймає довільні ідентифікатори моделей верхнього рівня | +| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих ідентифікаторів | +| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як вбудований раннер використає визначену модель | Провайдеру потрібні переписування транспорту, але він і далі використовує транспорт ядра | +| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для моделей вендора за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспортах, не перехоплюючи керування провайдером | +| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру та використовуються спільною логікою ядра | Провайдеру потрібні особливості транскрипту/сімейства провайдера | +| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований раннер | Провайдеру потрібне очищення схем для сімейства транспорту | +| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження щодо ключових слів без навчання ядра правилам, специфічним для провайдера | +| 18 | `resolveReasoningOutputMode` | Вибирає нативний або тегований контракт виводу reasoning | Провайдеру потрібен тегований reasoning/фінальний вивід замість нативних полів | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдеру потрібен користувацький wire protocol, а не просто обгортка | +| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки заголовків/тіла запиту/сумісності моделі без користувацького транспорту | +| 22 | `resolveTransportTurnState` | Додає нативні заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали нативну для провайдера ідентичність ходу | +| 23 | `resolveWebSocketSessionPolicy` | Додає нативні заголовки WebSocket або політику cool-down сеансу | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сеансу або резервну політику | +| 24 | `formatApiKey` | Форматувальник профілю автентифікації: збережений профіль стає рядком `apiKey` у середовищі виконання | Провайдер зберігає додаткові метадані автентифікації й потребує користувацької форми токена для середовища виконання | +| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких кінцевих точок оновлення або політики збоїв оновлення | Провайдер не відповідає спільним механізмам оновлення `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка для виправлення, що додається, коли не вдається оновлення OAuth | Провайдеру потрібна власна підказка щодо відновлення автентифікації після збою оновлення | +| 27 | `matchesContextOverflowError` | Власний для провайдера розпізнавач переповнення вікна контексту | Провайдер має сирі помилки переповнення, які загальні евристики не виявлять | +| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з обмеженням швидкості/перевантаженням тощо | +| 29 | `isCacheTtlEligible` | Політика prompt-cache для провайдерів proxy/backhaul | Провайдеру потрібне керування TTL кешу, специфічне для proxy | +| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення про відсутню автентифікацію | Провайдеру потрібна власна підказка щодо відновлення при відсутній автентифікації | +| 31 | `suppressBuiltInModel` | Пригнічення застарілої моделі верхнього рівня плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі рядки верхнього рівня або замінити їх підказкою вендора | +| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, що додаються після виявлення | Провайдеру потрібні синтетичні рядки для прямої сумісності в майбутньому в `models list` і засобах вибору | +| 33 | `resolveThinkingProfile` | Набір рівнів `/think`, мітки відображення та типове значення для конкретної моделі | Провайдер надає користувацьку шкалу thinking або двійкову мітку для вибраних моделей | +| 34 | `isBinaryThinking` | Хук сумісності для перемикача reasoning увімк./вимк. | Провайдер підтримує лише двійковий режим thinking увімк./вимк. | +| 35 | `supportsXHighThinking` | Хук сумісності підтримки reasoning `xhigh` | Провайдер хоче `xhigh` лише для частини моделей | +| 36 | `resolveDefaultThinkingLevel` | Хук сумісності типового рівня `/think` | Провайдер володіє типовою політикою `/think` для сімейства моделей | +| 37 | `isModernModelRef` | Розпізнавач modern-model для фільтрів live profile і вибору smoke | Провайдер володіє зіставленням бажаної моделі для live/smoke | +| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед інференсом | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | +| 39 | `resolveUsageAuth` | Визначає облікові дані використання/білінгу для `/usage` і пов’язаних поверхонь статусу | Провайдеру потрібен користувацький розбір токена використання/квоти або інші облікові дані використання | +| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки використання/квоти, специфічні для провайдера, після визначення автентифікації | Провайдеру потрібна специфічна для провайдера кінцева точка використання або парсер корисного навантаження | +| 41 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті належить plugin провайдера | +| 42 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна користувацька політика транскрипту (наприклад, видалення блоків thinking) | +| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні специфічні для провайдера переписування replay понад спільні помічники Compaction | +| 44 | `validateReplayTurns` | Остаточна перевірка або переформування ходів replay перед вбудованим раннером | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санітизації | +| 45 | `onModelSelected` | Виконує побічні ефекти після вибору, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -відповідний Plugin провайдера, а потім послідовно переходять до інших Plugin провайдерів, -які підтримують хуки, доки один із них справді не змінить id моделі або transport/config. Це зберігає -працездатність shim-ів alias/compat провайдерів без потреби, щоб викликач знав, який саме -вбудований Plugin володіє цим перезаписом. Якщо жоден хук провайдера не переписує підтримуваний -запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google усе одно застосує -це сумісне очищення. +відповідний plugin провайдера, а потім переходять до інших plugin провайдерів, що підтримують хуки, +доки один із них фактично не змінить id моделі або transport/config. Це дозволяє +працювати shim-плагінам для псевдонімів/сумісності провайдерів без потреби, щоб викликач знав, який +саме вбудований plugin володіє цим переписуванням. Якщо жоден хук провайдера не переписує підтримуваний +запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно застосує +це очищення для сумісності. Якщо провайдеру потрібен повністю користувацький wire protocol або користувацький виконавець запитів, -це вже інший клас розширення. Ці хуки призначені для поведінки провайдера, яка -все ще працює в межах звичайного циклу inference OpenClaw. +це вже інший клас розширення. Ці хуки призначені для поведінки провайдера, яка все ще +працює в межах звичайного циклу інференсу OpenClaw. ### Приклад провайдера @@ -323,45 +324,45 @@ api.registerProvider({ ### Вбудовані приклади -Вбудовані Plugin провайдерів поєднують наведені вище хуки відповідно до потреб кожного постачальника щодо каталогу, -auth, thinking, replay і usage. Авторитетний набір хуків розміщується разом -з кожним Plugin у `extensions/`; ця сторінка ілюструє форми, а не -дзеркально відтворює список. +Вбудовані plugin провайдерів поєднують наведені вище хуки, щоб відповідати потребам кожного вендора щодо каталогу, +автентифікації, thinking, replay і використання. Авторитетний набір хуків живе разом +із кожним plugin у `extensions/`; ця сторінка ілюструє форми, а не +дзеркалить список. OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` разом із - `resolveDynamicModel` / `prepareDynamicModel`, щоб вони могли показувати id - моделей із зовнішнього джерела раніше за статичний каталог OpenClaw. + `resolveDynamicModel` / `prepareDynamicModel`, щоб показувати верхньорівневі + id моделей раніше за статичний каталог OpenClaw. - + GitHub Copilot, Gemini CLI, ChatGPT Codex, MiniMax, Xiaomi, z.ai поєднують `prepareRuntimeAuth` або `formatApiKey` з `resolveUsageAuth` + - `fetchUsageSnapshot`, щоб керувати обміном токенів та інтеграцією з `/usage`. + `fetchUsageSnapshot`, щоб керувати обміном токенів і інтеграцією `/usage`. - + Спільні іменовані сімейства (`google-gemini`, `passthrough-gemini`, - `anthropic-by-model`, `hybrid-anthropic-openai`) дають змогу провайдерам підключати - політику transcript через `buildReplayPolicy`, замість того щоб кожен Plugin - заново реалізовував очищення. + `anthropic-by-model`, `hybrid-anthropic-openai`) дають змогу провайдерам + підключатися до політики транскрипту через `buildReplayPolicy` замість того, щоб кожен plugin + повторно реалізовував очищення. `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і - `volcengine` реєструють лише `catalog` і працюють у спільному циклі inference. + `volcengine` реєструють лише `catalog` і працюють на спільному циклі інференсу. - - Beta-заголовки, `/fast` / `serviceTier` і `context1m` розміщені всередині - публічного seam `api.ts` / `contract-api.ts` Plugin Anthropic + + Бета-заголовки, `/fast` / `serviceTier` і `context1m` живуть усередині + публічного шва `api.ts` / `contract-api.ts` plugin Anthropic (`wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`), а не в загальному SDK. -## Runtime-помічники +## Допоміжні засоби середовища виконання -Plugin можуть отримувати доступ до окремих помічників ядра через `api.runtime`. Для TTS: +Plugin можуть отримувати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -382,14 +383,14 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових повідомлень. +- `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових нотаток. - Використовує конфігурацію ядра `messages.tts` і вибір провайдера. -- Повертає PCM-аудіобуфер + частоту дискретизації. Plugin мають самі виконувати ресемплінг/кодування для провайдерів. -- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосів або потоків налаштування, що належать постачальнику. -- Списки голосів можуть містити багатші метадані, такі як locale, стать і теги характеру для засобів вибору, обізнаних про провайдера. +- Повертає буфер PCM-аудіо + частоту дискретизації. Plugin мають виконувати ресемплінг/кодування для провайдерів. +- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу, що належать вендору, або для потоків налаштування. +- Списки голосів можуть містити багатші метадані, як-от locale, gender і теги personality для засобів вибору, обізнаних про провайдера. - OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. -Plugin також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. +Plugin також можуть реєструвати мовленнєвих провайдерів через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -409,15 +410,15 @@ api.registerSpeechProvider({ Примітки: -- Зберігайте політику TTS, запасний варіант і доставку відповіді в ядрі. -- Використовуйте провайдерів мовлення для поведінки синтезу, що належить постачальнику. -- Застарілий ввід Microsoft `edge` нормалізується до id провайдера `microsoft`. -- Бажана модель володіння орієнтована на компанію: один Plugin постачальника може керувати - текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами в міру того, як OpenClaw додає ці +- Зберігайте політику TTS, резервний перехід і доставку відповіді в ядрі. +- Використовуйте мовленнєвих провайдерів для поведінки синтезу, що належить вендору. +- Застарілий вхід Microsoft `edge` нормалізується до ідентифікатора провайдера `microsoft`. +- Бажана модель володіння орієнтована на компанію: один plugin вендора може володіти + текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами, коли OpenClaw додаватиме ці контракти можливостей. -Для розуміння зображень/аудіо/відео Plugin реєструють один типізований -media-understanding-провайдер замість узагальненого набору ключ/значення: +Для розуміння зображень/аудіо/відео plugin реєструють одного типізованого +провайдера розуміння медіа замість універсального мішка ключ/значення: ```ts api.registerMediaUnderstandingProvider({ @@ -431,16 +432,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Зберігайте оркестрацію, запасний варіант, конфігурацію і прив’язку каналів у ядрі. -- Зберігайте поведінку постачальника в Plugin провайдера. +- Зберігайте оркестрацію, резервний перехід, конфігурацію та прив’язку каналу в ядрі. +- Зберігайте поведінку вендора в plugin провайдера. - Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові поля результату, нові необов’язкові можливості. - Генерація відео вже дотримується того самого шаблону: - - ядро володіє контрактом можливості та runtime-помічником - - Plugin постачальників реєструють `api.registerVideoGenerationProvider(...)` - - Plugin можливостей/каналів використовують `api.runtime.videoGeneration.*` + - ядро володіє контрактом можливості та допоміжним засобом середовища виконання + - plugin вендора реєструють `api.registerVideoGenerationProvider(...)` + - plugin можливостей/каналів споживають `api.runtime.videoGeneration.*` -Для runtime-помічників media-understanding Plugin можуть викликати: +Для допоміжних засобів середовища виконання розуміння медіа plugin можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -455,14 +456,14 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрибування аудіо Plugin можуть використовувати або runtime -media-understanding, або старіший псевдонім STT: +Для транскрибування аудіо plugin можуть використовувати або середовище виконання +розуміння медіа, або старіший псевдонім STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Необов’язково, коли MIME не вдається надійно визначити: + // Необов’язково, коли MIME не можна надійно визначити: mime: "audio/ogg", }); ``` @@ -471,9 +472,9 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ - `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для розуміння зображень/аудіо/відео. -- Використовує конфігурацію аудіо media-understanding ядра (`tools.media.audio`) і порядок запасних варіантів провайдерів. -- Повертає `{ text: undefined }`, коли вихід транскрибування не створено (наприклад, вхід пропущено/не підтримується). -- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом сумісності. +- Використовує конфігурацію аудіо розуміння медіа ядра (`tools.media.audio`) і порядок резервного вибору провайдера. +- Повертає `{ text: undefined }`, коли вихід транскрибування не створено (наприклад, для пропущеного/непідтримуваного вводу). +- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності. Plugin також можуть запускати фонові виконання субагента через `api.runtime.subagent`: @@ -491,12 +492,12 @@ const result = await api.runtime.subagent.run({ - `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. - OpenClaw враховує ці поля перевизначення лише для довірених викликачів. -- Для запасних запусків, що належать Plugin, оператори мають явно ввімкнути `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені Plugin конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. -- Запуски субагента від недовірених Plugin усе ще працюють, але запити на перевизначення відхиляються, а не тихо переходять до запасного варіанта. +- Для резервних запусків, що належать plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugin конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. +- Запуски субагента з недовірених plugin усе ще працюють, але запити на перевизначення відхиляються замість тихого резервного переходу. -Для вебпошуку Plugin можуть використовувати спільний runtime-помічник замість -прямого доступу до прив’язки інструмента агента: +Для вебпошуку plugin можуть використовувати спільний допоміжний засіб середовища виконання замість +звернення до прив’язки інструментів агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -518,8 +519,8 @@ Plugin також можуть реєструвати провайдерів в Примітки: - Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у ядрі. -- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для постачальника. -- `api.runtime.webSearch.*` — це бажана спільна поверхня для Plugin можливостей/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. +- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для вендора. +- `api.runtime.webSearch.*` — це бажана спільна поверхня для plugin можливостей/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструментів агента. ### `api.runtime.imageGeneration` @@ -534,12 +535,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. -- `listProviders(...)`: перелічує доступних провайдерів генерації зображень і їхні можливості. +- `generate(...)`: створити зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. +- `listProviders(...)`: перелічити доступних провайдерів генерації зображень і їхні можливості. ## HTTP-маршрути Gateway -Plugin можуть відкривати HTTP-ендпоінти за допомогою `api.registerHttpRoute(...)`. +Plugin можуть відкривати HTTP-кінцеві точки за допомогою `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -557,201 +558,198 @@ api.registerHttpRoute({ Поля маршруту: - `path`: шлях маршруту під HTTP-сервером gateway. -- `auth`: обов’язкове. Використовуйте `"gateway"`, щоб вимагати звичайний auth gateway, або `"plugin"` для auth/перевірки webhook, якими керує Plugin. +- `auth`: обов’язкове. Використовуйте `"gateway"` для звичайної автентифікації gateway або `"plugin"` для автентифікації/перевірки Webhook, якими керує plugin. - `match`: необов’язкове. `"exact"` (типово) або `"prefix"`. -- `replaceExisting`: необов’язкове. Дозволяє тому самому Plugin замінити власну наявну реєстрацію маршруту. -- `handler`: поверніть `true`, якщо маршрут обробив запит. +- `replaceExisting`: необов’язкове. Дозволяє тому самому plugin замінити власну наявну реєстрацію маршруту. +- `handler`: повертайте `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` вилучено, і він спричинить помилку завантаження Plugin. Замість нього використовуйте `api.registerHttpRoute(...)`. -- Маршрути Plugin мають явно оголошувати `auth`. -- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один Plugin не може замінити маршрут іншого Plugin. -- Маршрути, що перекриваються та мають різні рівні `auth`, відхиляються. Залишайте ланцюги проходження `exact`/`prefix` лише в межах одного рівня auth. -- Маршрути `auth: "plugin"` **не** отримують автоматично області доступу runtime оператора. Вони призначені для webhook/перевірки підписів, якими керує Plugin, а не для привілейованих допоміжних викликів Gateway. -- Маршрути `auth: "gateway"` працюють у межах області runtime запиту Gateway, але ця область навмисно консервативна: - - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області runtime маршруту Plugin на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` - - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту Plugin з ідентичністю, область runtime повертається до `operator.write` -- Практичне правило: не припускайте, що маршрут Plugin з auth gateway є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. +- `api.registerHttpHandler(...)` було видалено і воно спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`. +- Маршрути plugin мають явно оголошувати `auth`. +- Конфлікти точних `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin. +- Маршрути, що перекриваються, з різними рівнями `auth` відхиляються. Тримайте ланцюжки переходу `exact`/`prefix` fallthrough лише в межах одного рівня auth. +- Маршрути `auth: "plugin"` **не** отримують автоматично області доступу середовища виконання оператора. Вони призначені для Webhook/перевірки підпису, якими керує plugin, а не для привілейованих допоміжних викликів Gateway. +- Маршрути `auth: "gateway"` працюють усередині області середовища виконання запиту Gateway, але ця область навмисно консервативна: + - bearer-автентифікація зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області середовища виконання маршрутів plugin на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` + - довірені HTTP-режими з передачею ідентичності (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` у приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах до маршрутів plugin із передачею ідентичності, область середовища виконання повертається до `operator.write` +- Практичне правило: не припускайте, що маршрут plugin з gateway-auth є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим автентифікації з передачею ідентичності та задокументуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK -Використовуйте вузькі підшляхи SDK замість монолітного кореневого -barrel `openclaw/plugin-sdk`, коли створюєте нові Plugin. Основні підшляхи: +Під час створення нових plugin використовуйте вузькі підшляхи SDK замість монолітного +кореневого barrel `openclaw/plugin-sdk`. Основні підшляхи: | Підшлях | Призначення | | ---------------------------------- | -------------------------------------------------- | -| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin | -| `openclaw/plugin-sdk/channel-core` | Помічники входу/побудови каналу | -| `openclaw/plugin-sdk/core` | Загальні спільні помічники та umbrella-контракт | -| `openclaw/plugin-sdk/config-schema` | Коренева Zod-схема `openclaw.json` (`OpenClawSchema`) | +| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації plugin | +| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/побудови каналу | +| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella contract | +| `openclaw/plugin-sdk/config-schema` | Коренева схема Zod `openclaw.json` (`OpenClawSchema`) | -Plugin каналів вибирають із сімейства вузьких seam-ів — `channel-setup`, +Plugin каналів обирають із сімейства вузьких швів — `channel-setup`, `setup-runtime`, `setup-adapter-runtime`, `setup-tools`, `channel-pairing`, `channel-contract`, `channel-feedback`, `channel-inbound`, `channel-lifecycle`, `channel-reply-pipeline`, `command-auth`, `secret-input`, `webhook-ingress`, `channel-targets` і `channel-actions`. Поведінку погодження слід консолідувати -в одному контракті `approvalCapability`, а не змішувати між не пов’язаними -полями Plugin. Див. [Plugin каналів](/uk/plugins/sdk-channel-plugins). +на одному контракті `approvalCapability`, а не змішувати між не пов’язаними +полями plugin. Див. [Channel plugins](/uk/plugins/sdk-channel-plugins). -Runtime- і config-помічники розміщуються у відповідних підшляхах `*-runtime` +Допоміжні засоби середовища виконання і конфігурації розміщені у відповідних підшляхах `*-runtime` (`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`, `lazy-runtime`, `directory-runtime`, `text-runtime`, `runtime-store` тощо). -`openclaw/plugin-sdk/channel-runtime` застарів — це shim сумісності для -старіших Plugin. Новий код має імпортувати вужчі загальні примітиви. +`openclaw/plugin-sdk/channel-runtime` є застарілим — це shim сумісності для +старіших plugin. Новий код має імпортувати натомість вужчі загальні примітиви. -Внутрішні для репозиторію точки входу (для кореня кожного пакета вбудованого Plugin): +Внутрішні для репозиторію точки входу (для кореня пакета кожного вбудованого plugin): -- `index.js` — точка входу вбудованого Plugin -- `api.js` — barrel помічників/типів -- `runtime-api.js` — barrel лише для runtime -- `setup-entry.js` — точка входу Plugin налаштування +- `index.js` — точка входу вбудованого plugin +- `api.js` — barrel допоміжних засобів/типів +- `runtime-api.js` — barrel лише для середовища виконання +- `setup-entry.js` — точка входу plugin налаштування -Зовнішні Plugin мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи -не імпортуйте `src/*` іншого пакета Plugin з ядра або з іншого Plugin. -Точки входу, завантажені через facade, надають перевагу активному знімку конфігурації runtime, якщо він -існує, а потім повертаються до визначеного файла конфігурації на диску. +Зовнішні plugin мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи +не імпортуйте `src/*` іншого пакета plugin з ядра або з іншого plugin. +Точки входу, завантажені через facade, надають перевагу активному знімку конфігурації середовища виконання, коли він є, +а потім повертаються до визначеного файлу конфігурації на диску. -Підшляхи, специфічні для можливостей, такі як `image-generation`, `media-understanding` -і `speech`, існують тому, що вбудовані Plugin уже використовують їх сьогодні. Вони не є -автоматично зовнішніми контрактами, назавжди зафіксованими на довгий термін — перегляньте -відповідну довідкову сторінку SDK, якщо покладаєтеся на них. +Підшляхи, специфічні для можливостей, як-от `image-generation`, `media-understanding` +і `speech`, існують, тому що вбудовані plugin уже використовують їх сьогодні. Вони не є +автоматично зовнішніми контрактами, остаточно зафіксованими на довгий строк — перевіряйте відповідну +довідкову сторінку SDK, коли покладаєтеся на них. ## Схеми інструментів повідомлень -Plugin мають володіти внесками до схем `describeMessageTool(...)`, специфічних для каналів, -для немеседжевих примітивів, таких як реакції, прочитання й опитування. +Plugin мають володіти внесками до схем `describeMessageTool(...)`, специфічними для каналу, +для немовних примітивів, таких як реакції, прочитання і опитування. Спільне подання надсилання має використовувати загальний контракт `MessagePresentation` -замість native-полів кнопок, компонентів, блоків або карток, специфічних для провайдера. +замість нативних для провайдера полів button, component, block або card. Див. [Message Presentation](/uk/plugins/message-presentation) щодо контракту, -правил запасного варіанта, зіставлення провайдерів і контрольного списку автора Plugin. +правил резервного переходу, зіставлення провайдерів і контрольного списку автора plugin. -Plugin, здатні надсилати повідомлення, оголошують, що саме вони можуть рендерити, через можливості повідомлень: +Plugin із можливістю надсилання оголошують, що вони можуть відтворювати, через можливості повідомлень: -- `presentation` для семантичних блоків подання (`text`, `context`, `divider`, `buttons`, `select`) -- `delivery-pin` для запитів закріпленої доставки +- `presentation` для блоків семантичного подання (`text`, `context`, `divider`, `buttons`, `select`) +- `delivery-pin` для запитів pinned-delivery -Ядро вирішує, чи рендерити подання нативно, чи деградувати його до тексту. -Не відкривайте шлюзи до native UI, специфічного для провайдера, із загального -інструмента повідомлень. Застарілі помічники SDK для legacy native-схем і далі експортуються для наявних -сторонніх Plugin, але нові Plugin не повинні їх використовувати. +Ядро вирішує, чи відтворювати подання нативно, чи деградувати його до тексту. +Не відкривайте нативні для провайдера шляхи обходу UI із загального інструмента повідомлень. +Застарілі допоміжні засоби SDK для старих нативних схем і далі експортуються для наявних +сторонніх plugin, але нові plugin не повинні їх використовувати. -## Визначення цільового каналу +## Визначення цілей каналу -Plugin каналів мають володіти семантикою цілей, специфічною для каналів. Зберігайте спільний -вихідний хост узагальненим і використовуйте поверхню messaging adapter для правил провайдера: +Plugin каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний +вихідний хост загальним і використовуйте поверхню адаптера повідомлень для правил провайдера: - `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль - слід трактувати як `direct`, `group` або `channel` до пошуку в директорії. + слід трактувати як `direct`, `group` або `channel` до пошуку в каталозі. - `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи - слід одразу перейти до визначення за схожістю з id замість пошуку в директорії. -- `messaging.targetResolver.resolveTarget(...)` — це запасний варіант Plugin, коли + вхідні дані слід одразу передати до визначення, подібного до id, замість пошуку в каталозі. +- `messaging.targetResolver.resolveTarget(...)` — це резервний шлях plugin, коли ядру потрібне остаточне визначення, що належить провайдеру, після нормалізації або після - промаху в директорії. -- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сеансу, - специфічною для провайдера, після того як ціль визначено. + промаху в каталозі. +- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту + сеансу вихідних повідомлень, специфічною для провайдера, після визначення цілі. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають ухвалюватися до - пошуку peer/group. -- Використовуйте `looksLikeId` для перевірок на кшталт «трактувати це як явний/native id цілі». -- Використовуйте `resolveTarget` для специфічного для провайдера запасного варіанта нормалізації, а не для - широкого пошуку в директорії. -- Зберігайте native-id провайдера, такі як chat id, thread id, JID, handle та room +- Використовуйте `inferTargetChatType` для категорійних рішень, які мають відбутися до + пошуку peers/groups. +- Використовуйте `looksLikeId` для перевірок типу «сприймати це як явний/нативний id цілі». +- Використовуйте `resolveTarget` для резервної нормалізації, специфічної для провайдера, а не для + широкого пошуку в каталозі. +- Зберігайте нативні для провайдера id, такі як chat id, thread id, JID, handle і room id, усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK. -## Директорії на основі конфігурації +## Каталоги на основі конфігурації -Plugin, які виводять записи директорії з конфігурації, мають зберігати цю логіку в -Plugin і повторно використовувати спільні помічники з +Plugin, які виводять записи каталогу з конфігурації, мають зберігати цю логіку в +plugin і повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні peer/group на основі конфігурації, наприклад: +Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, наприклад: -- DM peer-и, керовані allowlist -- налаштовані відображення каналів/group -- статичні запасні варіанти директорії в межах облікового запису +- DM-peers, керовані allowlist +- налаштовані мапи каналів/груп +- статичні резервні варіанти каталогу в межах облікового запису -Спільні помічники в `directory-runtime` обробляють лише загальні операції: +Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: -- фільтрацію запитів +- фільтрування запитів - застосування обмежень -- помічники дедуплікації/нормалізації +- допоміжні засоби дедуплікації/нормалізації - побудову `ChannelDirectoryEntry[]` -Перевірка облікового запису та нормалізація id, специфічні для каналу, мають залишатися в -реалізації Plugin. +Перевірка облікового запису і нормалізація id, специфічні для каналу, мають залишатися в +реалізації plugin. ## Каталоги провайдерів -Plugin провайдерів можуть визначати каталоги моделей для inference через +Plugin провайдерів можуть визначати каталоги моделей для інференсу за допомогою `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в `models.providers`: - `{ provider }` для одного запису провайдера -- `{ providers }` для кількох записів провайдерів +- `{ providers }` для кількох записів провайдера -Використовуйте `catalog`, коли Plugin володіє id моделей, специфічними для провайдера, типовими -значеннями base URL або метаданими моделей, керованими auth. +Використовуйте `catalog`, коли plugin володіє id моделей, специфічними для провайдера, типовими +значеннями base URL або метаданими моделей, захищеними автентифікацією. -`catalog.order` визначає, коли каталог Plugin зливається відносно +`catalog.order` керує тим, коли каталог plugin зливається відносно вбудованих неявних провайдерів OpenClaw: -- `simple`: прості провайдери з API-ключем або env -- `profile`: провайдери, які з’являються, коли існують auth-профілі -- `paired`: провайдери, що синтезують кілька пов’язаних записів провайдерів +- `simple`: звичайні провайдери з API-ключем або на основі env +- `profile`: провайдери, які з’являються, коли існують профілі автентифікації +- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів - `late`: останній прохід, після інших неявних провайдерів -Пізніші провайдери перемагають у разі конфлікту ключів, тож Plugin можуть навмисно перевизначати -вбудований запис провайдера з тим самим id провайдера. +Пізніші провайдери перемагають у разі конфлікту ключів, тому plugin можуть навмисно +перевизначати вбудований запис провайдера з тим самим id провайдера. Сумісність: -- `discovery` усе ще працює як застарілий псевдонім +- `discovery` і далі працює як застарілий псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Канал лише для читання: перевірка стану +## Інспекція каналу лише для читання -Якщо ваш Plugin реєструє канал, краще реалізувати -`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`. +Якщо ваш plugin реєструє канал, надавайте перевагу реалізації +`plugin.config.inspectAccount(cfg, accountId)` поруч із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це шлях runtime. Він може припускати, що облікові дані - повністю матеріалізовані, і може швидко завершитися з помилкою, якщо потрібні секрети відсутні. +- `resolveAccount(...)` — це шлях середовища виконання. Він може припускати, що облікові дані + повністю матеріалізовані, і швидко завершуватися з помилкою, коли потрібних секретів бракує. - Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve`, а також потоки doctor/config - repair, не повинні потребувати матеріалізації облікових даних runtime лише для того, - щоб описати конфігурацію. + `openclaw channels status`, `openclaw channels resolve` і потоки + відновлення doctor/config, не повинні потребувати матеріалізації облікових даних середовища виконання лише для + опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: - Повертає лише описовий стан облікового запису. - Зберігає `enabled` і `configured`. -- Додає поля джерела/статусу облікових даних, коли це доречно, наприклад: +- Включає поля джерела/статусу облікових даних, коли це доречно, наприклад: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Не потрібно повертати сирі значення токенів лише для повідомлення про доступність лише для читання. - Достатньо повернути `tokenStatus: "available"` (і відповідне поле - джерела) для команд у стилі status. +- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність тільки для читання. Повернення `tokenStatus: "available"` (і відповідного поля джерела) достатньо для команд на кшталт status. - Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але вони недоступні в поточному шляху команди. -Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» -замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. +Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. ## Пакетні набори -Каталог Plugin може містити `package.json` з `openclaw.extensions`: +Каталог plugin може містити `package.json` з `openclaw.extensions`: ```json { @@ -763,64 +761,64 @@ Plugin провайдерів можуть визначати каталоги } ``` -Кожен запис стає Plugin. Якщо набір містить кілька extensions, id Plugin +Кожен запис стає plugin. Якщо набір перелічує кілька extensions, id plugin стає `name/`. -Якщо ваш Plugin імпортує npm-залежності, установіть їх у цьому каталозі, щоб +Якщо ваш plugin імпортує npm-залежності, встановіть їх у цьому каталозі, щоб `node_modules` був доступний (`npm install` / `pnpm install`). -Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу Plugin +Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу plugin після визначення symlink. Записи, які виходять за межі каталогу пакета, відхиляються. -Примітка щодо безпеки: `openclaw plugins install` установлює залежності Plugin за допомогою -`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей у runtime). Підтримуйте дерева залежностей Plugin -«чистими JS/TS» й уникайте пакетів, які потребують збирання через `postinstall`. +Примітка щодо безпеки: `openclaw plugins install` встановлює залежності plugin за допомогою +`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev dependencies у середовищі виконання). Тримайте дерева залежностей plugin +«чистими JS/TS» і уникайте пакетів, які потребують збірок через `postinstall`. -Необов’язково: `openclaw.setupEntry` може вказувати на полегшений модуль лише для налаштування. -Коли OpenClaw потребує поверхонь налаштування для вимкненого Plugin каналу або -коли Plugin каналу ввімкнений, але ще не налаштований, він завантажує `setupEntry` -замість повної точки входу Plugin. Це робить запуск і налаштування легшими, -коли основна точка входу Plugin також підключає інструменти, хуки або інший код лише для runtime. +Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування. +Коли OpenClaw потребує поверхонь налаштування для вимкненого plugin каналу або +коли plugin каналу увімкнено, але ще не налаштовано, він завантажує `setupEntry` +замість повної точки входу plugin. Це робить запуск і налаштування легшими, +коли основна точка входу вашого plugin також підключає інструменти, хуки або інший код +лише для середовища виконання. Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести Plugin каналу на той самий шлях `setupEntry` під час фази -запуску gateway до початку прослуховування, навіть якщо канал уже налаштований. +може перевести plugin каналу на той самий шлях `setupEntry` під час +передпрослуховувальної фази запуску gateway, навіть якщо канал уже налаштовано. Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати до того, як gateway почне прослуховування. На практиці це означає, що точка входу налаштування -має реєструвати всі можливості, що належать каналу й від яких залежить запуск, зокрема: +має реєструвати кожну можливість, що належить каналу і від якої залежить запуск, наприклад: - саму реєстрацію каналу - будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне прослуховування -- будь-які методи gateway, інструменти або сервіси, які мають існувати в це саме вікно часу +- будь-які методи gateway, інструменти або служби, які мають існувати в той самий проміжок часу Якщо ваша повна точка входу все ще володіє будь-якою обов’язковою можливістю запуску, не вмикайте -цей прапорець. Залиште для Plugin типову поведінку й дозвольте OpenClaw завантажити +цей прапорець. Залиште plugin на стандартній поведінці й дозвольте OpenClaw завантажити повну точку входу під час запуску. -Вбудовані канали також можуть публікувати помічники contract-surface лише для налаштування, які ядро -може використовувати до завантаження повного runtime каналу. Поточна поверхня +Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, які ядро +може перевіряти до завантаження повного середовища виконання каналу. Поточна поверхня просування налаштування така: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію каналу з одним обліковим записом -у `channels..accounts.*` без завантаження повної точки входу Plugin. -Matrix — поточний вбудований приклад: він переміщує лише ключі auth/bootstrap до -іменованого просунутого облікового запису, коли іменовані облікові записи вже існують, і може -зберігати налаштований неканонічний ключ облікового запису за замовчуванням, замість того щоб завжди створювати +Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію каналу +з одним обліковим записом у `channels..accounts.*` без завантаження повної точки входу plugin. +Matrix — поточний вбудований приклад: він переносить лише ключі auth/bootstrap в +іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може +зберегти налаштований неканонічний ключ default-account замість того, щоб завжди створювати `accounts.default`. -Ці адаптери латок налаштування зберігають discovery вбудованої contract-surface лінивим. Час імпорту залишається легким; поверхня -просування завантажується лише під час першого використання, а не через повторний вхід у запуск вбудованого каналу під час імпорту модуля. +Ці адаптери patch налаштування зберігають ліниве виявлення поверхні контракту вбудованих каналів. Час імпорту залишається легким; поверхня просування завантажується лише під час першого використання замість повторного входу в запуск вбудованого каналу при імпорті модуля. -Коли ці поверхні запуску містять Gateway RPC-методи, зберігайте їх на -префіксі, специфічному для Plugin. Простори імен адміністратора ядра (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються -як `operator.admin`, навіть якщо Plugin запитує вужчу область. +Коли ці поверхні запуску включають методи Gateway RPC, тримайте їх на +префіксі, специфічному для plugin. Простори імен адміністратора ядра (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди визначаються +як `operator.admin`, навіть якщо plugin запитує вужчу область. Приклад: @@ -837,10 +835,10 @@ Matrix — поточний вбудований приклад: він пере } ``` -### Метадані каталогу каналів +### Метадані каталогу каналу -Plugin каналів можуть оголошувати метадані налаштування/discovery через `openclaw.channel` і -підказки встановлення через `openclaw.install`. Це дає змогу ядру не містити даних каталогу. +Plugin каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і +підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити даних каталогу. Приклад: @@ -855,7 +853,7 @@ Plugin каналів можуть оголошувати метадані на "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Self-hosted чат через webhook-ботів Nextcloud Talk.", + "blurb": "Самостійно розгорнутий чат через Webhook-ботів Nextcloud Talk.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -868,65 +866,65 @@ Plugin каналів можуть оголошувати метадані на } ``` -Корисні поля `openclaw.channel` понад мінімальний приклад: +Корисні поля `openclaw.channel`, окрім мінімального прикладу: -- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/status +- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу - `docsLabel`: перевизначає текст посилання для посилання на документацію -- `preferOver`: id Plugin/каналів нижчого пріоритету, які цей запис каталогу має перевершувати -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування копією поверхні вибору -- `markdownCapable`: позначає канал як такий, що підтримує markdown, для рішень щодо форматування вихідних повідомлень +- `preferOver`: id plugin/каналу з нижчим пріоритетом, які цей запис каталогу має випереджати +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору +- `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо форматування вихідних повідомлень - `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` - `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено `false` - `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації - `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure` - `quickstartAllowFrom`: підключає канал до стандартного потоку quickstart `allowFrom` -- `forceAccountBinding`: вимагає явного прив’язування облікового запису, навіть якщо існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення цілей announce +- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сеансу під час визначення цілей announce -OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт -реєстру MPM). Помістіть JSON-файл в один із таких шляхів: +OpenClaw також може об’єднувати **зовнішні каталоги каналів** (наприклад, експорт +реєстру MPM). Помістіть JSON-файл в одне з таких місць: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на -один чи кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл має +один або кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл має містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів відкривають -нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Ці -нормалізовані факти вказують, чи є npm-специфікація точною версією або плаваючим -селектором, чи присутні очікувані метадані цілісності, і чи також доступний локальний -шлях до джерела. Коли ідентичність каталогу/пакета відома, нормалізовані факти +нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Нормалізовані +факти визначають, чи npm spec є точною версією або плаваючим селектором, +чи присутні очікувані метадані цілісності, і чи також доступний локальний +шлях джерела. Коли ідентичність каталогу/пакета відома, нормалізовані факти попереджають, якщо розібране ім’я npm-пакета відхиляється від цієї ідентичності. -Вони також попереджають, коли `defaultChoice` недійсний або вказує на джерело, яке -недоступне, і коли метадані цілісності npm присутні без дійсного джерела -npm. Споживачі повинні трактувати `installSource` як адитивне необов’язкове поле, щоб -старішим вручну створеним записам і shim-ам сумісності не доводилося його синтезувати. -Це дає змогу onboarding і діагностиці пояснювати стан площини джерел без -імпорту runtime Plugin. +Вони також попереджають, коли `defaultChoice` є недійсним або вказує на джерело, яке +недоступне, і коли метадані цілісності npm присутні без дійсного npm- +джерела. Споживачі мають розглядати `installSource` як адитивне необов’язкове поле, щоб +старі вручну створені записи та shim сумісності не мусили його синтезувати. +Це дає змогу онбордингу й діагностиці пояснювати стан source plane без +імпорту середовища виконання plugin. -Офіційні зовнішні записи npm мають надавати перевагу точному `npmSpec` разом із -`expectedIntegrity`. Голі імена пакетів і dist-tag-и все ще працюють для -сумісності, але вони показують попередження площини джерел, щоб каталог міг рухатися -до зафіксованих, перевірених за цілісністю встановлень без порушення роботи наявних Plugin. -Коли onboarding встановлює з локального шляху каталогу, він записує -запис `plugins.installs` із `source: "path"` і шляхом `sourcePath`, відносним до workspace, -коли це можливо. Абсолютний операційний шлях завантаження залишається в -`plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів робочої станції -в довготривалій конфігурації. Це зберігає локальні встановлення для розробки видимими для -діагностики площини джерел без додавання другої сирої поверхні розкриття шляхів файлової системи. +Офіційні зовнішні записи npm мають надавати перевагу точному `npmSpec` плюс +`expectedIntegrity`. Голі імена пакетів і dist-tag усе ще працюють для +сумісності, але вони показують попередження source plane, щоб каталог міг рухатися +до зафіксованих, перевірених за цілісністю встановлень без порушення роботи наявних plugin. +Коли онбординг виконує встановлення з локального шляху каталогу, він записує +запис `plugins.installs` із `source: "path"` і відносним до робочого простору +`sourcePath`, коли це можливо. Абсолютний операційний шлях завантаження залишається в +`plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів +робочої станції в довгоживучій конфігурації. Це зберігає видимість локальних установлень для розробки для +діагностики source plane без додавання другої сирої поверхні розкриття шляхів файлової системи. ## Plugin рушія контексту -Plugin рушія контексту володіють оркестрацією контексту сесії для ingest, assembly -і Compaction. Реєструйте їх зі свого Plugin за допомогою +Plugin рушія контексту володіють оркестрацією контексту сеансу для ingest, assembly +і Compaction. Реєструйте їх зі свого plugin через `api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через `plugins.slots.contextEngine`. -Використовуйте це, коли вашому Plugin потрібно замінити або розширити типовий -конвеєр контексту, а не просто додати пошук у memory або хуки. +Використовуйте це, коли вашому plugin потрібно замінити або розширити стандартний конвеєр +контексту, а не просто додати пошук у пам’яті або хуки. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -954,7 +952,7 @@ export default function (api) { } ``` -Якщо ваш рушій **не** володіє алгоритмом Compaction, залиште `compact()` +Якщо ваш рушій **не** володіє алгоритмом Compaction, залишайте `compact()` реалізованим і явно делегуйте його: ```ts @@ -992,45 +990,45 @@ export default function (api) { ## Додавання нової можливості -Коли Plugin потребує поведінки, яка не вписується в поточний API, не обходьте -систему Plugin через приватне глибоке звернення. Додайте відсутню можливість. +Коли plugin потребує поведінки, яка не вписується в поточний API, не обходьте +систему plugin через приватне глибоке втручання. Додайте відсутню можливість. Рекомендована послідовність: 1. визначте контракт ядра - Вирішіть, якою спільною поведінкою має володіти ядро: політика, запасний варіант, злиття конфігурації, - життєвий цикл, семантика для каналів і форма runtime-помічника. -2. додайте типізовані поверхні реєстрації/runtime Plugin + Вирішіть, якою спільною поведінкою має володіти ядро: політикою, резервним переходом, злиттям конфігурації, + життєвим циклом, семантикою для каналу та формою допоміжних засобів середовища виконання. +2. додайте типізовані поверхні реєстрації plugin/середовища виконання Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною типізованою поверхнею можливості. 3. підключіть ядро + споживачів каналів/можливостей - Канали й Plugin можливостей мають використовувати нову можливість через ядро, - а не імпортувати реалізацію постачальника безпосередньо. -4. зареєструйте реалізації постачальників - Потім Plugin постачальників реєструють свої backend-и для цієї можливості. + Канали і plugin можливостей мають споживати нову можливість через ядро, + а не імпортувати реалізацію вендора напряму. +4. зареєструйте реалізації вендора + Потім plugin вендора реєструють свої бекенди для цієї можливості. 5. додайте покриття контракту - Додайте тести, щоб володіння та форма реєстрації з часом залишалися явними. + Додайте тести, щоб із часом володіння і форма реєстрації залишалися явними. -Саме так OpenClaw залишається принциповим, не перетворюючись на жорстко -закодований продукт під світогляд одного провайдера. Див. [Capability Cookbook](/uk/plugins/architecture) -для конкретного контрольного списку файлів і готового прикладу. +Саме так OpenClaw зберігає власну позицію, не стаючи жорстко прив’язаним до +світогляду одного провайдера. Див. [Capability Cookbook](/uk/plugins/architecture) +для конкретного контрольного списку файлів і робочого прикладу. ### Контрольний список можливості -Коли ви додаєте нову можливість, реалізація зазвичай має разом зачіпати такі -поверхні: +Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих +поверхонь разом: -- типи контракту ядра в `src//types.ts` -- runner/runtime-помічник ядра в `src//runtime.ts` -- поверхню реєстрації API Plugin в `src/plugins/types.ts` -- підключення реєстру Plugin в `src/plugins/registry.ts` -- відкриття runtime Plugin у `src/plugins/runtime/*`, коли Plugin можливостей/каналів - мають її використовувати -- помічники capture/test у `src/test-utils/plugin-registration.ts` +- типи контрактів ядра в `src//types.ts` +- раннер/допоміжний засіб середовища виконання ядра в `src//runtime.ts` +- поверхня реєстрації API plugin в `src/plugins/types.ts` +- підключення реєстру plugin в `src/plugins/registry.ts` +- відкриття середовища виконання plugin в `src/plugins/runtime/*`, коли plugin можливостей/каналів + мають його споживати +- допоміжні засоби capture/test в `src/test-utils/plugin-registration.ts` - перевірки володіння/контракту в `src/plugins/contracts/registry.ts` -- документацію для операторів/Plugin у `docs/` +- документація для операторів/plugin в `docs/` -Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість +Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість ще не повністю інтегрована. ### Шаблон можливості @@ -1045,7 +1043,7 @@ export type VideoGenerationProviderPlugin = { generateVideo: (req: VideoGenerationRequest) => Promise; }; -// API Plugin +// API plugin api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1054,9 +1052,9 @@ api.registerVideoGenerationProvider({ }, }); -// спільний runtime-помічник для Plugin можливостей/каналів +// спільний допоміжний засіб середовища виконання для plugin можливостей/каналів const clip = await api.runtime.videoGeneration.generate({ - prompt: "Покажи робота, що йде лабораторією.", + prompt: "Покажи, як робот іде через лабораторію.", cfg, }); ``` @@ -1070,13 +1068,13 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Це зберігає правило простим: - ядро володіє контрактом можливості + оркестрацією -- Plugin постачальників володіють реалізаціями постачальників -- Plugin можливостей/каналів використовують runtime-помічники -- тести контрактів зберігають володіння явним +- plugin вендора володіють реалізаціями вендора +- plugin можливостей/каналів споживають допоміжні засоби середовища виконання +- тести контракту зберігають явність володіння -## Пов’язане +## Пов’язані матеріали -- [Архітектура Plugin](/uk/plugins/architecture) — публічна модель і форми можливостей -- [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths) -- [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення Plugin](/uk/plugins/building-plugins) +- [Plugin architecture](/uk/plugins/architecture) — загальнодоступна модель можливостей і форми +- [Plugin SDK subpaths](/uk/plugins/sdk-subpaths) +- [Plugin SDK setup](/uk/plugins/sdk-setup) +- [Building plugins](/uk/plugins/building-plugins) diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 45e370538..02c41c07c 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -2,52 +2,63 @@ read_when: - Ви створюєте Plugin для OpenClaw - Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin -summary: Вимоги до маніфесту Plugin + JSON schema (сувора валідація конфігурації) +summary: Вимоги до маніфесту Plugin і JSON schema (сувора валідація конфігурації) title: Маніфест Plugin x-i18n: - generated_at: "2026-04-24T20:11:32Z" + generated_at: "2026-04-24T20:18:19Z" model: gpt-5.4 provider: openai - source_hash: ac25782f26abe79875c25abcd6f7b53fbe7a3c7b139c80c8a1a6675e69d6529c + source_hash: 6b2849737f9d785ff15a7988cfaf6515cbabce2901e2da4f2c72007d302f41f2 source_path: plugins/manifest.md workflow: 15 --- -Ця сторінка призначена лише для **рідного маніфесту Plugin OpenClaw**. +Ця сторінка стосується лише **власного маніфесту Plugin OpenClaw**. -Сумісні компонування бандлів див. у [бандлах Plugin](/uk/plugins/bundles). +Сумісні компонування пакетів описано тут: [Пакети Plugin](/uk/plugins/bundles). -Сумісні формати бандлів використовують інші файли маніфесту: +Сумісні формати пакетів використовують інші файли маніфесту: -- бандл Codex: `.codex-plugin/plugin.json` -- бандл Claude: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude без маніфесту -- бандл Cursor: `.cursor-plugin/plugin.json` +- Пакет Codex: `.codex-plugin/plugin.json` +- Пакет Claude: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude + без маніфесту +- Пакет Cursor: `.cursor-plugin/plugin.json` -OpenClaw також автоматично виявляє ці компонування бандлів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. +OpenClaw також автоматично визначає ці компонування пакетів, але вони не проходять валідацію +за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних бандлів OpenClaw наразі зчитує метадані бандла, а також оголошені корені навичок, корені команд Claude, типові значення `settings.json` бандла Claude, типові значення LSP бандла Claude і підтримувані набори хуків, якщо компонування відповідає очікуванням рантайму OpenClaw. +Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені +корені навичок, корені команд Claude, типові значення `settings.json` пакета Claude, +типові значення LSP пакета Claude та підтримувані набори хуків, коли компонування +відповідає очікуванням рантайму OpenClaw. -Кожен рідний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у **корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду Plugin**. Відсутні або невалідні маніфести розглядаються як помилки Plugin і блокують валідацію конфігурації. +Кожен власний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у +**корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації +**без виконання коду Plugin**. Відсутні або некоректні маніфести вважаються +помилками Plugin і блокують валідацію конфігурації. Повний посібник із системи Plugin див. тут: [Plugins](/uk/tools/plugin). -Щодо рідної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності див.: -[модель можливостей](/uk/plugins/architecture#public-capability-model). +Про власну модель можливостей і поточні рекомендації щодо зовнішньої сумісності: +[Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду вашого Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску рантайму Plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду +вашого Plugin**. Усе нижче має бути достатньо недорогим для перевірки без запуску +рантайму Plugin. **Використовуйте його для:** - ідентичності Plugin, валідації конфігурації та підказок для UI конфігурації - метаданих автентифікації, онбордингу та налаштування (аліас, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) - підказок активації для поверхонь control-plane -- володіння скороченими сімействами моделей +- скороченого володіння сімействами моделей - статичних знімків володіння можливостями (`contracts`) - метаданих QA runner, які може перевіряти спільний хост `openclaw qa` -- метаданих конфігурації, специфічних для каналу, що об’єднуються в surfaces каталогу та валідації +- метаданих конфігурації, специфічних для каналу, що об’єднуються в каталог і поверхні валідації -**Не використовуйте його для:** реєстрації поведінки рантайму, оголошення точок входу коду або метаданих встановлення npm. Для цього призначені код вашого Plugin і `package.json`. +**Не використовуйте його для:** реєстрації поведінки рантайму, оголошення точок входу коду +або метаданих встановлення npm. Це належить до коду вашого Plugin і `package.json`. ## Мінімальний приклад @@ -129,64 +140,68 @@ OpenClaw також автоматично виявляє ці компонув | Поле | Обов’язкове | Тип | Що воно означає | | ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний id Plugin. Це id, який використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | -| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Не вказуйте це поле або встановіть будь-яке значення, відмінне від `true`, щоб Plugin лишався вимкненим за замовчуванням. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id Plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які повинні автоматично вмикати цей Plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Id каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Id провайдерів, якими володіє цей Plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Шлях до легкого модуля виявлення провайдера, відносний до кореня Plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного рантайму Plugin. | -| `modelSupport` | Ні | `object` | Метадані скорочених сімейств моделей, якими володіє маніфест і які використовуються для автозавантаження Plugin до запуску рантайму. | -| `providerEndpoints` | Ні | `object[]` | Метадані хостів endpoint/baseUrl, якими володіє маніфест, для маршрутів провайдерів, які ядро має класифікувати до завантаження рантайму провайдера. | -| `cliBackends` | Ні | `string[]` | Id CLI-бекендів інференсу, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних посилань у конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або CLI-бекенди, для яких слід перевіряти синтетичний хук автентифікації, яким володіє Plugin, під час холодного виявлення моделей до завантаження рантайму. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, якими володіє вбудований Plugin і які представляють не секретний локальний стан, OAuth або стан ambient credentials. | -| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які повинні формувати діагностику конфігурації та CLI з урахуванням Plugin до завантаження рантайму. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/статусу провайдера. Для нових Plugin віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це під час вікна депрекації. | -| `providerAuthAliases` | Ні | `Record` | Id провайдерів, які повинні повторно використовувати id іншого провайдера для пошуку автентифікації, наприклад провайдер для кодування, який використовує той самий API-ключ базового провайдера та профілі автентифікації. | -| `channelEnvVars` | Ні | `Record` | Легкі метадані env каналу, які OpenClaw може перевірити без завантаження коду Plugin. Використовуйте це для налаштування каналів через env або поверхонь автентифікації, які мають бачити загальні допоміжні засоби запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для селекторів онбордингу, визначення бажаного провайдера та простого зв’язування CLI-прапорців. | -| `activation` | Ні | `object` | Легкі метадані планувальника активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактичною поведінкою, як і раніше, володіє рантайм Plugin. | -| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження рантайму Plugin. | -| `qaRunners` | Ні | `object[]` | Легкі дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження рантайму Plugin. | -| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, вебпошуку та володіння інструментами. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легкі типові значення для розуміння медіа для id провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналів, якими володіє маніфест і які об’єднуються в поверхні виявлення та валідації до завантаження рантайму. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореня Plugin. | -| `name` | Ні | `string` | Зрозуміла людині назва Plugin. | -| `description` | Ні | `string` | Короткий опис, який показується в поверхнях Plugin. | +| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Це ідентифікатор, що використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений типово. Не вказуйте це поле або задайте будь-яке значення, відмінне від `true`, щоб Plugin залишався вимкненим типово. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора Plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей Plugin, коли на них посилаються автентифікація, конфігурація або посилання на моделі. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, що використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей Plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Полегшений шлях до модуля виявлення провайдера, відносно кореня Plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного рантайму Plugin. | +| `modelSupport` | Ні | `object` | Короткі метадані сімейств моделей, що належать маніфесту та використовуються для автоматичного завантаження Plugin до запуску рантайму. | +| `providerEndpoints` | Ні | `object[]` | Метадані хостів endpoint/baseUrl, що належать маніфесту, для маршрутів провайдера, які ядро має класифікувати до завантаження рантайму провайдера. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів інференсу CLI, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдер або бекенд CLI, для яких слід перевіряти синтетичний хук автентифікації, що належить Plugin, під час холодного виявлення моделей до завантаження рантайму. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення API-ключів-заповнювачів, що належать вбудованому Plugin і позначають несекретний локальний стан, стан OAuth або стан ambient credentials. | +| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які мають формувати діагностику конфігурації та CLI з урахуванням Plugin до завантаження рантайму. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/статусу провайдера. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це під час вікна знецінення. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер кодування, який використовує той самий API-ключ базового провайдера й auth profiles. | +| `channelEnvVars` | Ні | `Record` | Легкі метадані env каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналу через env або поверхонь автентифікації, які мають бачити типові хелпери запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для селекторів онбордингу, визначення пріоритетного провайдера та простого зв’язування прапорців CLI. | +| `activation` | Ні | `object` | Легкі метадані планувальника активації для завантаження, що запускається провайдером, командою, каналом, маршрутом або можливістю. Лише метадані; фактичною поведінкою все одно володіє рантайм Plugin. | +| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення й налаштування можуть перевіряти без завантаження рантайму Plugin. | +| `qaRunners` | Ні | `object[]` | Легкі дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження рантайму Plugin. | +| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легкі типові значення media-understanding для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту й об’єднуються в поверхні виявлення та валідації до завантаження рантайму. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. | +| `name` | Ні | `string` | Людинозрозуміла назва Plugin. | +| `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. | | `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | UI-мітки, плейсхолдери та підказки щодо чутливості для полів конфігурації. | +| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. OpenClaw зчитує це до завантаження рантайму провайдера. +Потік налаштування провайдера надає перевагу цим варіантам із маніфесту, а потім для сумісності +переходить до метаданих майстра рантайму та варіантів каталогу встановлення. -| Поле | Обов’язкове | Тип | Що воно означає | -| --------------------- | ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Id провайдера, до якого належить цей варіант. | -| `method` | Так | `string` | Id методу автентифікації, до якого слід спрямувати обробку. | -| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, який використовується в потоках онбордингу та CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих асистентом. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із селекторів асистента, але все ще дозволяє ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів до цього варіанта-заміни. | -| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | -| `cliFlag` | Ні | `string` | Назва CLI-прапорця, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма CLI-опції, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має відображатися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. | +| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід спрямувати. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, що використовується потоками онбордингу та CLI. | +| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих асистентом. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант у селекторах асистента, але все одно дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів до цього варіанта-замінника. | +| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли Plugin володіє іменем runtime-команди, яке користувачі можуть помилково вказати в `plugins.allow` або спробувати запустити як кореневу CLI-команду. OpenClaw використовує ці метадані для діагностики без імпорту коду рантайму Plugin. +Використовуйте `commandAliases`, коли Plugin володіє назвою команди рантайму, яку користувачі можуть +помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw +використовує ці метадані для діагностики без імпорту коду рантайму Plugin. ```json { @@ -200,21 +215,34 @@ OpenClaw зчитує це до завантаження рантайму про } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | -------------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, яка належить цьому Plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає аліас як slash-команду чату, а не кореневу CLI-команду. | -| `cliCommand` | Ні | `string` | Пов’язана коренева CLI-команда, яку слід рекомендувати для CLI-операцій, якщо така існує. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, що належить цьому Plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає аліас як slash-команду чату, а не як кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід підказати для операцій CLI, якщо вона існує. | ## Довідник `activation` -Використовуйте `activation`, коли Plugin може дешево оголосити, які події control-plane повинні включати його до плану активації/завантаження. +Використовуйте `activation`, коли Plugin може з низькими витратами оголосити, які події control-plane +мають включати його до плану активації/завантаження. -Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку рантайму, не замінює `register(...)` і не гарантує, що код Plugin уже був виконаний. Планувальник активації використовує ці поля, щоб звузити коло кандидатів Plugin, перш ніж перейти до наявних метаданих володіння з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hooks. +Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє +поведінку рантайму, не замінює `register(...)` і не обіцяє, що код +Plugin уже виконувався. Планувальник активації використовує ці поля для звуження +кандидатів Plugin перед переходом до наявних метаданих володіння з маніфесту, таких як +`providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і хуки. -Віддавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальника, які не можна представити цими полями володіння. +Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте +`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, +коли ці поля виражають відповідний зв’язок. Використовуйте `activation` для додаткових підказок планувальника, +які не можна представити цими полями володіння. -Цей блок містить лише метадані. Він не реєструє поведінку рантайму і не замінює `register(...)`, `setupEntry` або інші runtime/Plugin entrypoints. Поточні споживачі використовують його як підказку для звуження вибору перед ширшим завантаженням Plugin, тож відсутність метаданих активації зазвичай впливає лише на продуктивність; це не повинно змінювати коректність, доки ще існують застарілі fallback-механізми володіння з маніфесту. +Цей блок є лише метаданими. Він не реєструє поведінку рантайму і не +замінює `register(...)`, `setupEntry` або інші точки входу рантайму/Plugin. +Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому +відсутність метаданих активації зазвичай впливає лише на продуктивність; це не має +змінювати коректність, поки ще існують застарілі fallback-механізми володіння з маніфесту. ```json { @@ -228,27 +256,37 @@ OpenClaw зчитує це до завантаження рантайму про } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ---------------- | ----------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Id провайдерів, які повинні включати цей Plugin до планів активації/завантаження. | -| `onCommands` | Ні | `string[]` | Id команд, які повинні включати цей Plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Id каналів, які повинні включати цей Plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які повинні включати цей Plugin до планів активації/завантаження. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки щодо можливостей, які використовуються під час планування активації control-plane. Якщо можливо, віддавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ---------------- | ----------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки можливостей, що використовуються плануванням активації control-plane. Якщо можливо, надавайте перевагу вужчим полям. | Поточні активні споживачі: -- планування CLI, що запускається командою, використовує fallback до застарілих +- планування CLI, що запускається командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` -- планування setup/каналів, що запускається каналом, використовує fallback до застарілого володіння `channels[]`, якщо явні метадані активації каналу відсутні -- планування setup/runtime, що запускається провайдером, використовує fallback до застарілого володіння - `providers[]` і верхньорівневого `cliBackends[]`, якщо явні метадані активації провайдера відсутні +- планування setup/каналу, що запускається каналом, повертається до застарілого володіння + `channels[]`, якщо явні метадані активації каналу відсутні +- планування setup/рантайму, що запускається провайдером, повертається до застарілого + володіння `providers[]` і `cliBackends[]` верхнього рівня, якщо явні метадані активації + провайдера відсутні -Діагностика планувальника може розрізняти явні підказки активації та fallback на володіння з маніфесту. Наприклад, `activation-command-hint` означає, що збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для діагностики хоста та тестів; авторам Plugin слід і надалі оголошувати метадані, які найкраще описують володіння. +Діагностика планувальника може відрізняти явні підказки активації від fallback-механізму +володіння з маніфесту. Наприклад, `activation-command-hint` означає, що +збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що +планувальник натомість використав володіння з `commandAliases`. Ці мітки причин призначені для +діагностики хоста та тестів; авторам Plugin слід і надалі оголошувати метадані, +які найкраще описують володіння. ## Довідник `qaRunners` -Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner під спільним коренем `openclaw qa`. Зберігайте ці метадані легкими та статичними; фактичною реєстрацією CLI, як і раніше, володіє рантайм Plugin через легку поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. +Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner під спільний +корінь `openclaw qa`. Зберігайте ці метадані легкими та статичними; фактичною реєстрацією CLI +усе одно володіє рантайм Plugin через полегшену поверхню +`runtime-api.ts`, що експортує `qaRunnerCliRegistrations`. ```json { @@ -261,14 +299,15 @@ OpenClaw зчитує це до завантаження рантайму про } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | -------- | --------------------------------------------------------------------------- | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | -------- | ---------------------------------------------------------------------- | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | | `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. | ## Довідник `setup` -Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні легкі метадані Plugin до завантаження рантайму. +Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні легкі метадані, +що належать Plugin, до завантаження рантайму. ```json { @@ -287,34 +326,54 @@ OpenClaw зчитує це до завантаження рантайму про } ``` -Верхньорівневе `cliBackends` залишається валідним і надалі описує CLI-бекенди інференсу. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків control-plane/setup, які мають залишатися лише на рівні метаданих. +`cliBackends` верхнього рівня залишається допустимим і й надалі описує +бекенди інференсу CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, +для потоків control-plane/setup, які мають залишатися лише метаданими. -Якщо вказано `setup.providers` і `setup.cliBackends`, вони є бажаною поверхнею пошуку для виявлення setup у підході descriptor-first. Якщо дескриптор лише звужує коло кандидатів Plugin, а setup усе ще потребує багатших runtime-хуків на етапі налаштування, встановіть `requiresRuntime: true` і збережіть `setup-api` як резервний шлях виконання. +Якщо присутні, `setup.providers` і `setup.cliBackends` є пріоритетною +поверхнею пошуку для виявлення setup на основі дескрипторів. Якщо дескриптор лише +звужує кандидата Plugin, а setup усе ще потребує багатших хуків рантайму на етапі setup, +задайте `requiresRuntime: true` і залиште `setup-api` як +fallback-шлях виконання. -OpenClaw також включає `setup.providers[].envVars` у загальні пошуки автентифікації провайдера та env vars. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності впродовж вікна депрекації, але небудовані Plugin, які все ще використовують його, отримують діагностику маніфесту. Нові Plugin повинні розміщувати метадані env для налаштування/статусу в `setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` до загальних пошуків автентифікації провайдера та +env vars. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом +періоду знецінення, але невбудовані Plugin, які все ще його використовують, +отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані env для setup/статусу +в `setup.providers[].envVars`. -Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише на рівні дескрипторів і не виконуватиме `setup-api` для пошуку setup. Якщо `requiresRuntime` не вказано, зберігається застаріла fallback-поведінка, щоб наявні Plugin, які додали дескриптори без цього прапорця, не зламалися. +Задавайте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для +поверхні setup. OpenClaw трактує явне `false` як контракт лише на дескриптори +і не виконуватиме `setup-api` для пошуку setup. Якщо `requiresRuntime` +не вказано, зберігається застаріла fallback-поведінка, щоб наявні Plugin, які додали дескриптори +без цього прапорця, не зламалися. -Оскільки пошук setup може виконувати код `setup-api`, яким володіє Plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` повинні залишатися глобально унікальними серед виявлених Plugin. Неоднозначне володіння завершується безпечною відмовою замість вибору переможця за порядком виявлення. +Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, +нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися +унікальними серед виявлених Plugin. Неоднозначне володіння призводить до безпечної відмови, +замість вибору переможця за порядком виявлення. -Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про дрейф дескрипторів, якщо `setup-api` реєструє провайдера або CLI-бекенд, який не оголошено в дескрипторах маніфесту, або якщо для дескриптора немає відповідної runtime-реєстрації. Ці діагностики є додатковими й не відхиляють застарілі Plugin. +Коли рантайм setup усе ж виконується, діагностика реєстру setup повідомляє про дрейф дескрипторів, +якщо `setup-api` реєструє провайдера або бекенд CLI, який не оголошено в дескрипторах +маніфесту, або якщо для дескриптора немає відповідної реєстрації в рантаймі. +Ця діагностика є додатковою і не відхиляє застарілі Plugin. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Id провайдера, який відкривається під час setup або онбордингу. Підтримуйте нормалізовані id глобально унікальними. | -| `authMethods` | Ні | `string[]` | Id методів setup/автентифікації, які цей провайдер підтримує без завантаження повного рантайму. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Ідентифікатор провайдера, що відкривається під час setup або онбордингу. Підтримуйте глобальну унікальність нормалізованих ідентифікаторів. | +| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей провайдер підтримує без завантаження повного рантайму. | | `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/статусу можуть перевіряти до завантаження рантайму Plugin. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | --------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, доступні під час setup та онбордингу. | -| `cliBackends` | Ні | `string[]` | Id бекендів часу setup, які використовуються для пошуку setup у підході descriptor-first. Підтримуйте нормалізовані id глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє поверхня setup цього Plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, доступні під час setup та онбордингу. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів для етапу setup, що використовуються для пошуку setup спочатку за дескрипторами. Підтримуйте глобальну унікальність нормалізованих ідентифікаторів. | +| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, що належать поверхні setup цього Plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескрипторами. | ## Довідник `uiHints` @@ -333,20 +392,21 @@ OpenClaw також включає `setup.providers[].envVars` у загальн } ``` -Кожна підказка поля може містити: +Кожна підказка для поля може містити: | Поле | Тип | Що воно означає | | ------------- | ---------- | --------------------------------------- | | `label` | `string` | Мітка поля для користувача. | | `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові UI-теґи. | +| `tags` | `string[]` | Необов’язкові теги UI. | | `advanced` | `boolean` | Позначає поле як розширене. | | `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст плейсхолдера для полів форми. | +| `placeholder` | `string` | Текст-заповнювач для полів форми. | ## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може зчитати без імпорту рантайму Plugin. +Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може +зчитувати без імпорту рантайму Plugin. ```json { @@ -369,31 +429,44 @@ OpenClaw також включає `setup.providers[].envVars` у загальн Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | --------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Застарілі id фабрик вбудованих extension. | -| `agentToolResultMiddleware` | `string[]` | Id harness, для яких цей Plugin може реєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | Id провайдерів, хуком зовнішнього профілю автентифікації яких володіє цей Plugin. | -| `speechProviders` | `string[]` | Id мовленнєвих провайдерів, якими володіє цей Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів транскрипції в реальному часі, якими володіє цей Plugin. | -| `realtimeVoiceProviders` | `string[]` | Id голосових провайдерів у реальному часі, якими володіє цей Plugin. | -| `memoryEmbeddingProviders` | `string[]` | Id провайдерів embedding для пам’яті, якими володіє цей Plugin. | -| `mediaUnderstandingProviders` | `string[]` | Id провайдерів розуміння медіа, якими володіє цей Plugin. | -| `imageGenerationProviders` | `string[]` | Id провайдерів генерації зображень, якими володіє цей Plugin. | -| `videoGenerationProviders` | `string[]` | Id провайдерів генерації відео, якими володіє цей Plugin. | -| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей Plugin. | -| `webSearchProviders` | `string[]` | Id провайдерів вебпошуку, якими володіє цей Plugin. | -| `tools` | `string[]` | Назви інструментів агента, якими володіє цей Plugin для перевірок вбудованих контрактів. | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | ------------------------------------------------------------------ | +| `embeddedExtensionFactories` | `string[]` | Застарілі ідентифікатори фабрик вбудованих розширень. | +| `agentToolResultMiddleware` | `string[]` | Ідентифікатори harness, для яких цей Plugin може реєструвати middleware результатів інструментів. | +| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, хуком зовнішнього auth profile яких володіє цей Plugin. | +| `speechProviders` | `string[]` | Ідентифікатори speech-провайдерів, якими володіє цей Plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime transcription, якими володіє цей Plugin. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів realtime voice, якими володіє цей Plugin. | +| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів memory embedding, якими володіє цей Plugin. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, якими володіє цей Plugin. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів image-generation, якими володіє цей Plugin. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів video-generation, якими володіє цей Plugin. | +| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей Plugin. | +| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, якими володіє цей Plugin. | +| `tools` | `string[]` | Назви agent tools, якими володіє цей Plugin для перевірок вбудованих контрактів. | -`contracts.embeddedExtensionFactories` збережено для коду сумісності вбудованих компонентів, якому все ще потрібні прямі події вбудованого runner для Pi. Нові трансформації результатів інструментів повинні оголошувати `contracts.agentToolResultMiddleware` і натомість реєструватися через `api.registerAgentToolResultMiddleware(...)`. +`contracts.embeddedExtensionFactories` збережено для вбудованого коду сумісності, +якому все ще потрібні прямі події вбудованого runner Pi. Нові трансформації +результатів інструментів мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися +через `api.registerAgentToolResultMiddleware(...)`. -Plugin провайдерів, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють через застарілий fallback сумісності, але цей fallback повільніший і буде вилучений після завершення вікна міграції. +Plugins провайдерів, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати +`contracts.externalAuthProviders`. Plugins без цього оголошення все ще працюють +через застарілий fallback-механізм сумісності, але він повільніший і +буде видалений після завершення періоду міграції. -Вбудовані провайдери embedding для пам’яті повинні оголошувати `contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони надають, включно з вбудованими адаптерами, такими як `local`. Автономні CLI-шляхи використовують цей контракт маніфесту, щоб завантажити лише Plugin-власник до того, як повний рантайм Gateway зареєструє провайдерів. +Вбудовані провайдери memory embedding повинні оголошувати +`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони відкривають, включно з +вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей контракт маніфесту, +щоб завантажувати лише Plugin-власник до того, як повний рантайм Gateway зареєструє +провайдерів. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має типові моделі, пріоритет fallback для автоавтентифікації або нативну підтримку документів, які потрібні загальним допоміжним засобам ядра до завантаження рантайму. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має +типові моделі, пріоритет fallback-автентифікації або нативну підтримку документів, які +потрібні загальним хелперам ядра до завантаження рантайму. Ключі також мають бути оголошені в +`contracts.mediaUnderstandingProviders`. ```json { @@ -418,16 +491,17 @@ Plugin провайдерів, які реалізують `resolveExternalAuthP Кожен запис провайдера може містити: -| Поле | Тип | Що воно означає | -| ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості медіа, які надає цей провайдер. | -| `defaultModels` | `Record` | Типові значення зіставлення можливості з моделлю, які використовуються, коли в конфігурації не вказано модель. | +| Поле | Тип | Що воно означає | +| ---------------------- | ----------------------------------- | --------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які відкриває цей провайдер. | +| `defaultModels` | `Record` | Типові значення моделей за можливістю, які використовуються, коли в конфігурації не вказано модель. | | `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback провайдера на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує провайдер. | +| `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує провайдер. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли Plugin каналу потребує легких метаданих конфігурації до завантаження рантайму. +Використовуйте `channelConfigs`, коли Plugin каналу потребує легких метаданих конфігурації до +завантаження рантайму. ```json { @@ -456,17 +530,19 @@ Plugin провайдерів, які реалізують `resolveExternalAuthP Кожен запис каналу може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------ | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- | | `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові UI-мітки/плейсхолдери/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, яка об’єднується в поверхнях вибору та inspect, коли runtime-метадані ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь inspect і каталогу. | -| `preferOver` | `string[]` | Id застарілих або менш пріоритетних Plugin, які цей канал має перевершувати в поверхнях вибору. | +| `uiHints` | `Record` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Мітка каналу, що об’єднується в поверхні вибору й інспекції, коли метадані рантайму ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь інспекції та каталогу. | +| `preferOver` | `string[]` | Ідентифікатори застарілих або менш пріоритетних Plugin, які цей канал має випереджати в поверхнях вибору. | ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера зі скорочених id моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження рантайму Plugin. +Використовуйте `modelSupport`, коли OpenClaw має визначати ваш Plugin провайдера за +скороченими ідентифікаторами моделей, такими як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження +рантайму Plugin. ```json { @@ -479,72 +555,104 @@ Plugin провайдерів, які реалізують `resolveExternalAuthP OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers`, якими володіє Plugin -- `modelPatterns` мають пріоритет над `modelPrefixes` -- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований Plugin -- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера +- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать власнику +- `modelPatterns` мають вищий пріоритет за `modelPrefixes` +- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований + Plugin +- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкажуть провайдера Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | ------------------------------------------------------------------------------ | -| `modelPrefixes` | `string[]` | Префікси, що перевіряються через `startsWith` проти скорочених id моделей. | -| `modelPatterns` | `string[]` | Джерела regex, що перевіряються проти скорочених id моделей після видалення суфікса профілю. | +| Поле | Тип | Що воно означає | +| --------------- | ---------- | ---------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, що звіряються через `startsWith` зі скороченими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що звіряються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | -Застарілі ключі можливостей верхнього рівня позначені як deprecated. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` до `contracts`; звичайне завантаження маніфесту більше не трактує ці поля верхнього рівня як володіння можливостями. +Застарілі ключі можливостей верхнього рівня не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб +перемістити `speechProviders`, `realtimeTranscriptionProviders`, +`realtimeVoiceProviders`, `mediaUnderstandingProviders`, +`imageGenerationProviders`, `videoGenerationProviders`, +`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне +завантаження маніфесту більше не трактує ці поля верхнього рівня як +володіння можливостями. -## Маніфест проти package.json +## Маніфест у порівнянні з package.json -Ці два файли виконують різні завдання: +Ці два файли виконують різні ролі: -| Файл | Для чого використовувати | -| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та UI-підказки, які мають існувати до запуску коду Plugin | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для entrypoints, обмежень встановлення, setup або метаданих каталогу | +| Файл | Для чого використовувати | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду Plugin | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для точок входу, обмежень встановлення, setup або метаданих каталогу | -Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило: +Якщо ви не впевнені, куди належить певний фрагмент метаданих, користуйтеся таким правилом: -- якщо OpenClaw повинен знати це до завантаження коду Plugin, розмістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів входу або поведінки встановлення npm, розмістіть це в `package.json` +- якщо OpenClaw має знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json` +- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json` -### Поля package.json, які впливають на виявлення +### Поля `package.json`, які впливають на виявлення -Деякі метадані Plugin до запуску рантайму навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. +Деякі метадані Plugin до запуску рантайму навмисно зберігаються в `package.json` у блоці +`openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує рідні entrypoints Plugin. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeExtensions` | Оголошує зібрані JavaScript runtime entrypoints для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.setupEntry` | Легкий entrypoint лише для setup, який використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef у режимі лише читання. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує зібраний JavaScript entrypoint setup для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.channel` | Легкі метадані каталогу каналів, як-от мітки, шляхи до документації, аліаси та тексти для вибору. | -| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує setup лише через env?» без завантаження повного рантайму каналу. | -| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного рантайму каналу. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих Plugin. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із semver-нижньою межею на кшталт `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення та оновлення звіряють із ним отриманий артефакт. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого Plugin, коли конфігурація невалідна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | +| Поле | Що воно означає | +| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Оголошує точки входу власного Plugin. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeExtensions` | Оголошує точки входу рантайму built JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.setupEntry` | Полегшена точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та пошуку стану каналу/SecretRef лише для читання. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript точку входу setup для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.channel` | Легкі метадані каталогу каналу, такі як мітки, шляхи до документації, аліаси та текст для вибору. | +| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного рантайму каналу. | +| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже виконано вхід хоч кудись?» без завантаження повного рантайму каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих Plugin і Plugin, опублікованих зовні. | +| `openclaw.install.defaultChoice` | Пріоритетний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють завантажений артефакт на відповідність йому. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого Plugin, коли конфігурація некоректна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | -Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються під час онбордингу до завантаження рантайму. `package.json#openclaw.install` повідомляє онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих варіантів. Не переміщуйте підказки встановлення до `openclaw.plugin.json`. +Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в +онбордингу до завантаження рантайму. `package.json#openclaw.install` повідомляє +онбордингу, як отримати або ввімкнути цей Plugin, коли користувач обирає один із цих +варіантів. Не переносіть підказки встановлення до `openclaw.plugin.json`. -`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають Plugin на старіших хостах. +`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження +реєстру маніфестів. Некоректні значення відхиляються; новіші, але коректні значення +пропускають Plugin на старіших хостах. -Точне закріплення версії npm уже зберігається в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу повинні поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення безпечно завершувалися відмовою, якщо отриманий npm-артефакт більше не відповідає закріпленому релізу. -Інтерактивний онбординг для сумісності все ще пропонує npm-специфікації довіреного реєстру, включно з простими назвами пакетів і dist-tags. Діагностика каталогу може розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю назви пакета та невалідні джерела default-choice. Вона також попереджає, коли `expectedIntegrity` присутній, але немає валідного npm-джерела, яке можна ним закріпити. -Коли `expectedIntegrity` присутній, потоки встановлення/оновлення застосовують його; коли його опущено, дозвіл реєстру фіксується без закріплення цілісності. +Точне закріплення версії npm уже міститься в `npmSpec`, наприклад +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу +мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення безпечно +завершувалися помилкою, якщо завантажений npm-артефакт більше не відповідає закріпленому релізу. +Інтерактивний онбординг для сумісності все ще пропонує npm-специфікації довіреного реєстру, +включно з голими назвами пакетів і dist-tags. Діагностика каталогу може +розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю +назви пакета та некоректні джерела default-choice. Вона також попереджає, коли +`expectedIntegrity` наявний, але немає коректного джерела npm, яке можна ним закріпити. +Коли `expectedIntegrity` наявний, +потоки встановлення/оновлення примусово застосовують його; коли його не вказано, розв’язання реєстру +фіксується без закріплення цілісності. -Plugin каналів повинні надавати `openclaw.setupEntry`, коли сканам статусу, списку каналів або SecretRef потрібно визначити налаштовані облікові записи без завантаження повного рантайму. Entrypoint setup має надавати метадані каналу, а також безпечні для setup адаптери конфігурації, статусу та секретів; мережеві клієнти, listeners Gateway і транспортні рантайми залишайте в основному entrypoint extension. +Plugins каналів повинні надавати `openclaw.setupEntry`, коли для статусу, списку каналів +або перевірок SecretRef потрібно визначати налаштовані облікові записи без завантаження повного +рантайму. Точка входу setup має відкривати метадані каналу разом із безпечними для setup адаптерами +конфігурації, статусу та секретів; мережеві клієнти, слухачі gateway та +рантайми транспорту залишайте в основній точці входу розширення. -Поля runtime entrypoint не скасовують перевірки меж пакета для полів source entrypoint. Наприклад, `openclaw.runtimeExtensions` не може зробити завантажуваним шлях `openclaw.extensions`, що виходить за межі пакета. +Поля точок входу рантайму не перевизначають перевірки меж пакетів для полів +точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити +завантажуваним шлях `openclaw.extensions`, що виходить за межі пакета. -`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно не робить довільно зламані конфігурації придатними до встановлення. Сьогодні воно дозволяє потокам встановлення відновлюватися лише після конкретних застарілих збоїв оновлення вбудованих Plugin, як-от відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для того самого вбудованого Plugin. Непов’язані помилки конфігурації все одно блокують встановлення та спрямовують операторів до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно +не робить довільно зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам встановлення +відновлюватися після певних застарілих збоїв оновлення вбудованого Plugin, таких як +відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для того самого +вбудованого Plugin. Непов’язані помилки конфігурації, як і раніше, блокують встановлення й спрямовують операторів +до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля-перевірки: ```json { @@ -560,9 +668,13 @@ Plugin каналів повинні надавати `openclaw.setupEntry`, к } ``` -Використовуйте це, коли потокам setup, doctor або configured-state потрібна легка перевірка автентифікації типу так/ні до завантаження повного Plugin каналу. Цільовий export має бути невеликою функцією, яка лише читає збережений стан; не спрямовуйте її через повний barrel рантайму каналу. +Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка +автентифікації типу так/ні до завантаження повного Plugin каналу. Цільовий експорт має бути невеликою +функцією, яка лише читає збережений стан; не маршрутизуйте її через повний barrel рантайму +каналу. -`openclaw.channel.configuredState` має таку саму форму для легких перевірок налаштованого стану лише через env: +`openclaw.channel.configuredState` використовує ту саму форму для дешевих перевірок +налаштованого стану лише через env: ```json { @@ -578,52 +690,56 @@ Plugin каналів повинні надавати `openclaw.setupEntry`, к } ``` -Використовуйте це, коли канал може відповісти щодо налаштованого стану на основі env або інших невеликих нерuntime-входів. Якщо перевірка потребує повного розв’язання конфігурації або реального рантайму каналу, залиште цю логіку в хуку Plugin `config.hasConfiguredState`. +Використовуйте це, коли канал може відповісти про налаштований стан на основі env або інших невеликих +невиконавчих входів. Якщо перевірка потребує повного розв’язання конфігурації або реального +рантайму каналу, залишайте цю логіку в хуку Plugin `config.hasConfiguredState`. -## Пріоритет виявлення (дублікати id Plugin) +## Пріоритет виявлення (дублікати ідентифікаторів Plugin) -OpenClaw виявляє Plugin із кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. +OpenClaw виявляє Plugins із кількох коренів (вбудовані, глобально встановлені, робочий простір, явно вибрані конфігурацією шляхи). Якщо два виявлені Plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч. -Пріоритет, від найвищого до найнижчого: +Пріоритет від найвищого до найнижчого: -1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.` -2. **Вбудований** — Plugin, що постачаються з OpenClaw -3. **Глобальне встановлення** — Plugin, установлені в глобальний корінь Plugin OpenClaw -4. **Workspace** — Plugin, виявлені відносно поточного workspace +1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` +2. **Вбудований** — Plugins, що постачаються з OpenClaw +3. **Глобальне встановлення** — Plugins, установлені в глобальний корінь Plugin OpenClaw +4. **Робочий простір** — Plugins, виявлені відносно поточного робочого простору Наслідки: -- Форк або застаріла копія вбудованого Plugin у workspace не затьмарить вбудовану збірку. -- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладався на виявлення у workspace. -- Відкидання дублікатів логуються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. +- Форк або застаріла копія вбудованого Plugin у робочому просторі не зможе затінити вбудовану збірку. +- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення в робочому просторі. +- Відкинуті дублікати журналюються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. ## Вимоги до JSON Schema -- **Кожен Plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурації. -- Порожня схема є допустимою (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми проходять валідацію під час читання/запису конфігурації, а не під час рантайму. +- **Кожен Plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію. +- Порожня схема припустима (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми проходять валідацію під час читання/запису конфігурації, а не в рантаймі. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошено в маніфесті Plugin. +- Невідомі ключі `channels.*` — це **помилки**, якщо тільки ідентифікатор каналу не оголошений + у маніфесті Plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - повинні посилатися на id Plugin, які **можна виявити**. Невідомі id є **помилками**. -- Якщо Plugin установлено, але його маніфест або схема пошкоджені чи відсутні, + мають посилатися на **виявлювані** ідентифікатори Plugin. Невідомі ідентифікатори — це **помилки**. +- Якщо Plugin установлено, але він має зламаний або відсутній маніфест чи схему, валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. -- Якщо конфігурація Plugin існує, але Plugin **вимкнений**, конфігурація зберігається, а в Doctor + logs відображається **попередження**. +- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається і + у Doctor та журналах з’являється **попередження**. -Повну схему `plugins.*` див. у [довіднику конфігурації](/uk/gateway/configuration). +Повну схему `plugins.*` див. у [Довіднику з конфігурації](/uk/gateway/configuration). ## Примітки -- Маніфест є **обов’язковим для рідних Plugin OpenClaw**, включно із завантаженнями з локальної файлової системи. Рантайм усе одно окремо завантажує модуль Plugin; маніфест використовується лише для виявлення + валідації. -- Рідні маніфести парсяться за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок дозволені, якщо кінцеве значення все ще є об’єктом. +- Маніфест **обов’язковий для власних Plugin OpenClaw**, включно із завантаженням із локальної файлової системи. Рантайм, як і раніше, завантажує модуль Plugin окремо; маніфест призначений лише для виявлення + валідації. +- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми й ключі без лапок допускаються, якщо кінцеве значення все одно є об’єктом. - Завантажувач маніфесту зчитує лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня. - `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує. -- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час запиту. +- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий код рантайму; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час обробки запитів. - Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). -- Метадані env vars (`setup.providers[].envVars`, застаріле `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставлення Cron та інші поверхні лише для читання все одно застосовують політику довіри до Plugin та ефективної активації, перш ніж вважати env var налаштованою. -- Метадані runtime wizard, які потребують коду провайдера, див. у [runtime hooks провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Метадані env vars (`setup.providers[].envVars`, застаріле `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до Plugin і ефективної активації, перш ніж вважати env var налаштованою. +- Метадані wizard рантайму, які потребують коду провайдера, описано в [Хуках рантайму провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). - Якщо ваш Plugin залежить від native modules, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане @@ -636,6 +752,6 @@ OpenClaw виявляє Plugin із кількох коренів (вбудов Внутрішня архітектура та модель можливостей. - Довідник SDK Plugin та імпорти підшляхів. + Довідник SDK Plugin і імпорти підшляхів.