From ad0338084442cf489b5f506e27dfc38d081fd119 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Tue, 28 Apr 2026 01:45:53 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/plugins/architecture-internals.md | 799 +++++++++--------- docs/uk/plugins/manifest.md | 973 +++++++++++----------- docs/uk/plugins/sdk-provider-plugins.md | 291 +++---- docs/uk/plugins/sdk-subpaths.md | 404 ++++----- 4 files changed, 1238 insertions(+), 1229 deletions(-) diff --git a/docs/uk/plugins/architecture-internals.md b/docs/uk/plugins/architecture-internals.md index ebbaf91c7..532f7a356 100644 --- a/docs/uk/plugins/architecture-internals.md +++ b/docs/uk/plugins/architecture-internals.md @@ -3,112 +3,111 @@ read_when: - Реалізація хуків середовища виконання провайдера, життєвого циклу каналу або пакетних наборів - Налагодження порядку завантаження plugin або стану реєстру - Додавання нової можливості plugin або plugin рушія контексту -summary: 'Внутрішня архітектура Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці' -title: Внутрішня архітектура Plugin +summary: 'Внутрішні компоненти архітектури Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці' +title: Внутрішні компоненти архітектури Plugin x-i18n: - generated_at: "2026-04-27T20:08:47Z" + generated_at: "2026-04-28T01:41:57Z" model: gpt-5.4 provider: openai - source_hash: 2258835c881bf83d090898c0276f81b74d0a1ec471a85ab9d8f96125eb9cba6a + source_hash: 6a32b52a2a817596d39a0281d4eeeb3820c8cecc1e7d2d93ab280fd967228bc3 source_path: plugins/architecture-internals.md workflow: 15 --- -Щодо публічної моделі можливостей, форм plugin і контрактів -володіння/виконання див. [Архітектура Plugin](/uk/plugins/architecture). Ця сторінка — -довідник щодо внутрішньої механіки: конвеєра завантаження, реєстру, хуків -середовища виконання, HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем. +Щоб дізнатися про публічну модель можливостей, форми plugin, а також контракти +володіння/виконання, див. [Архітектура Plugin](/uk/plugins/architecture). Ця сторінка — +довідник із внутрішньої механіки: конвеєр завантаження, реєстр, хуки середовища виконання, +HTTP-маршрути Gateway, шляхи імпорту та таблиці схем. ## Конвеєр завантаження Під час запуску OpenClaw приблизно виконує таке: -1. виявляє кандидатні корені plugin -2. зчитує маніфести native або сумісних збірок і метадані пакетів -3. відхиляє небезпечні кандидати +1. виявляє кореневі каталоги кандидатів на plugin +2. зчитує маніфести рідних або сумісних пакетів і метадані пакетів +3. відхиляє небезпечних кандидатів 4. нормалізує конфігурацію plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) 5. визначає, чи вмикати кожного кандидата -6. завантажує ввімкнені native модулі: зібрані вбудовані модулі використовують native loader; - незібрані native plugin використовують jiti -7. викликає native хуки `register(api)` і збирає реєстрації до реєстру plugin +6. завантажує ввімкнені рідні модулі: зібрані вбудовані модулі використовують рідний завантажувач; + незібрані рідні plugins використовують jiti +7. викликає рідні хуки `register(api)` і збирає реєстрації до реєстру plugin 8. робить реєстр доступним для поверхонь команд/середовища виконання -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це на тому самому етапі. Усі вбудовані plugin використовують `register`; для нових plugin надавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані plugins використовують `register`; для нових plugins надавайте перевагу `register`. Перевірки безпеки відбуваються **до** виконання в середовищі виконання. Кандидати блокуються, -коли точка входу виходить за межі кореня plugin, шлях -доступний для запису всім, або право власності на шлях -виглядає підозріло для невбудованих plugin. +коли точка входу виходить за межі кореня plugin, шлях доступний для запису всім, або +володіння шляхом виглядає підозрілим для невбудованих plugins. ### Поведінка з пріоритетом маніфесту -Маніфест є джерелом істини для контрольної площини. OpenClaw використовує його, щоб: +Маніфест є джерелом істини для керівного рівня. OpenClaw використовує його, щоб: - ідентифікувати plugin -- виявляти оголошені канали/Skills/схему конфігурації або можливості збірки +- виявляти оголошені канали/Skills/схему конфігурації або можливості пакета - перевіряти `plugins.entries..config` -- доповнювати підписи/заповнювачі в Control UI +- доповнювати мітки/заповнювачі Control UI - показувати метадані встановлення/каталогу - зберігати дешеві дескриптори активації та налаштування без завантаження середовища виконання plugin -Для native plugin модуль середовища виконання є частиною площини даних. Він реєструє -фактичну поведінку, як-от хуки, інструменти, команди або потоки провайдера. +Для рідних plugins модуль середовища виконання є частиною рівня даних. Він реєструє +фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера. -Необов’язкові блоки маніфесту `activation` і `setup` залишаються в контрольній площині. -Це лише дескриптори метаданих для планування активації та виявлення налаштування; +Необов’язкові блоки маніфесту `activation` і `setup` залишаються на керівному рівні. +Це лише метадані-дескриптори для планування активації та виявлення налаштування; вони не замінюють реєстрацію в середовищі виконання, `register(...)` або `setupEntry`. -Перші споживачі живої активації тепер використовують підказки команд, каналів і провайдерів у маніфесті, +Перші живі споживачі активації тепер використовують підказки маніфесту для команд, каналів і провайдерів, щоб звузити завантаження plugin до ширшої матеріалізації реєстру: -- завантаження CLI звужується до plugin, які володіють запитаною основною командою -- налаштування каналу/визначення plugin звужується до plugin, які володіють запитаним +- завантаження CLI звужується до plugins, які володіють запитаною основною командою +- розв’язання налаштування каналу/plugin звужується до plugins, які володіють запитаним id каналу -- явне визначення налаштування/середовища виконання провайдера звужується до plugin, які володіють +- явне розв’язання налаштування/середовища виконання провайдера звужується до plugins, які володіють запитаним id провайдера -Планувальник активації надає як API лише з ідентифікаторами для наявних викликачів, так і -API плану для нової діагностики. Записи плану повідомляють, чому plugin було вибрано, -відокремлюючи явні підказки планувальника `activation.*` від резервного варіанта володіння з маніфесту, -такого як `providers`, `channels`, `commandAliases`, `setup.providers`, +Планувальник активації надає як API лише з id для наявних викликачів, так і +API плану для нової діагностики. Записи плану повідомляють, чому було вибрано plugin, +відокремлюючи явні підказки планувальника `activation.*` від резервного володіння +маніфестом, такого як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і хуки. Це розділення причин є межею сумісності: -наявні метадані plugin продовжують працювати, а новий код може виявляти широкі підказки +наявні метадані plugin і далі працюють, а новий код може виявляти широкі підказки або резервну поведінку без зміни семантики завантаження середовища виконання. -Виявлення налаштування тепер надає перевагу id, що належать дескриптору, таким як `setup.providers` і -`setup.cliBackends`, щоб звузити кандидатні plugin до того, як воно повернеться до -`setup-api` для plugin, яким усе ще потрібні хуки середовища виконання на етапі налаштування. Списки налаштування провайдера -використовують маніфест `providerAuthChoices`, варіанти налаштування, похідні від дескриптора, +Виявлення налаштування тепер надає перевагу id, що належать дескрипторам, таким як `setup.providers` і +`setup.cliBackends`, щоб звужувати plugins-кандидати до переходу до +`setup-api` для plugins, яким усе ще потрібні хуки середовища виконання на етапі налаштування. Списки налаштування провайдера +використовують маніфест `providerAuthChoices`, варіанти налаштування, виведені з дескриптора, і метадані каталогу встановлення без завантаження середовища виконання провайдера. Явне -`setup.requiresRuntime: false` є межею лише для дескриптора; пропущене -`requiresRuntime` зберігає застарілий резервний варіант `setup-api` для сумісності. Якщо більше -ніж один виявлений plugin заявляє той самий нормалізований id провайдера налаштування або бекенда CLI, -пошук налаштування відхиляє неоднозначного власника замість покладання на -порядок виявлення. Коли середовище виконання налаштування все ж виконується, діагностика реєстру повідомляє -про розбіжності між `setup.providers` / `setup.cliBackends` і провайдерами або бекендами CLI, -зареєстрованими через setup-api, не блокуючи застарілі plugin. +`setup.requiresRuntime: false` є межою лише на рівні дескриптора; якщо +`requiresRuntime` пропущено, для сумісності зберігається застарілий резервний перехід до setup-api. Якщо більше +ніж один виявлений plugin заявляє про той самий нормалізований id провайдера налаштування або +CLI-бекенда, пошук налаштування відхиляє неоднозначного власника замість покладання на +порядок виявлення. Коли середовище виконання налаштування все ж запускається, діагностика реєстру повідомляє про +розбіжність між `setup.providers` / `setup.cliBackends` і провайдерами або +CLI-бекендами, зареєстрованими через setup-api, не блокуючи застарілі plugins. ### Що кешує завантажувач -OpenClaw зберігає короткочасні внутрішньопроцесні кеші для: +OpenClaw зберігає короткі внутрішньопроцесні кеші для: - результатів виявлення - даних реєстру маніфестів - завантажених реєстрів plugin -Ці кеші зменшують імпульсні витрати під час запуску та накладні витрати повторних команд. Їх безпечно -сприймати як короткочасні кеші продуктивності, а не як сховище стану. +Ці кеші зменшують сплески під час запуску та накладні витрати повторних команд. Їх безпечно +сприймати як короткоживучі кеші продуктивності, а не як постійне зберігання. Гарячі шляхи запуску Gateway мають надавати перевагу поточному `PluginMetadataSnapshot`, -похідному `PluginLookUpTable` або явному реєстру маніфестів, переданому далі -ланцюжком викликів. Перевірка конфігурації, автоматичне ввімкнення під час запуску та bootstrap plugin використовують +похідному `PluginLookUpTable` або явному реєстру маніфестів, переданому вздовж +ланцюжка викликів. Перевірка конфігурації, автоматичне ввімкнення під час запуску та bootstrap plugin використовують той самий знімок, коли він доступний. Для викликачів, які все ще перебудовують метадані маніфесту -з постійного індексу встановлених plugin, OpenClaw також зберігає невеликий -обмежений резервний кеш, ключами якого є встановлений індекс, форма запиту, -політика конфігурації, корені середовища виконання та сигнатури файлів маніфесту/пакета. Цей кеш є лише -резервним варіантом для повторної реконструкції з установленого індексу; це не змінюваний реєстр +зі збереженого індексу встановлених plugins, OpenClaw також зберігає невеликий +обмежений резервний кеш, ключем для якого є встановлений індекс, форма запиту, політика +конфігурації, корені середовища виконання та сигнатури файлів маніфесту/пакета. Цей кеш є лише +резервом для повторної реконструкції маніфестного реєстру з установленого індексу; це не змінюваний реєстр plugin середовища виконання. Примітка щодо продуктивності: @@ -116,42 +115,43 @@ plugin середовища виконання. - Установіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, щоб вимкнути ці кеші. - Установіть `OPENCLAW_DISABLE_INSTALLED_PLUGIN_MANIFEST_REGISTRY_CACHE=1`, щоб вимкнути - лише резервний кеш реєстру маніфестів встановленого індексу. + лише резервний кеш маніфестного реєстру для встановленого індексу. - Налаштуйте вікна кешу за допомогою `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Модель реєстру -Завантажені plugin не змінюють безпосередньо довільні глобальні змінні core. Вони реєструються в +Завантажені plugins не змінюють напряму довільні глобальні об’єкти ядра. Вони реєструються в центральному реєстрі plugin. Реєстр відстежує: -- записи plugin (ідентичність, джерело, походження, статус, діагностика) +- записи plugin (ідентичність, джерело, походження, стан, діагностика) - інструменти - застарілі хуки й типізовані хуки - канали -- провайдерів +- провайдери - обробники Gateway RPC - HTTP-маршрути - реєстратори CLI -- фонові сервіси +- фонові служби - команди, що належать plugin -Потім функції core читають із цього реєстру замість прямої взаємодії з модулями plugin. +Потім основні можливості читають із цього реєстру замість прямої взаємодії з модулями plugin. Це зберігає односпрямованість завантаження: - модуль plugin -> реєстрація в реєстрі -- середовище виконання core -> споживання реєстру +- ядро середовища виконання -> споживання реєстру -Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь core -потрібна лише одна точка інтеграції: «читати реєстр», а не «робити особливу обробку для кожного модуля plugin». +Це розділення важливе для супроводу. Воно означає, що більшості поверхонь ядра потрібна +лише одна точка інтеграції: «прочитати реєстр», а не «створити окрему логіку для кожного модуля plugin». -## Зворотні виклики прив’язування розмови +## Колбеки прив’язки розмови -Plugin, які прив’язують розмову, можуть реагувати, коли погодження вирішено. +Plugins, які прив’язують розмову, можуть реагувати, коли погодження вирішено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, як запит на прив’язування схвалено або відхилено: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек після схвалення +або відхилення запиту на прив’язку: ```ts export default { @@ -159,128 +159,128 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // Тепер для цього plugin + розмови існує прив’язування. + // Тепер для цього plugin + розмови існує прив’язка. console.log(event.binding?.conversationId); return; } - // Запит було відхилено; очистіть будь-який локальний стан очікування. + // Запит було відхилено; очистьте будь-який локальний стан очікування. console.log(event.request.conversation.conversationId); }); }, }; ``` -Поля корисного навантаження зворотного виклику: +Поля корисного навантаження колбека: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` -- `binding`: вирішене прив’язування для схвалених запитів -- `request`: підсумок початкового запиту, підказка від’єднання, id відправника та +- `binding`: розв’язана прив’язка для схвалених запитів +- `request`: зведення початкового запиту, підказка від’єднання, id відправника та метадані розмови -Цей зворотний виклик призначений лише для сповіщення. Він не змінює того, кому дозволено прив’язувати -розмову, і виконується після завершення обробки погодження в core. +Цей колбек призначений лише для сповіщення. Він не змінює, кому дозволено прив’язувати +розмову, і виконується після завершення обробки погодження ядром. ## Хуки середовища виконання провайдера -Plugin провайдера мають три шари: +Plugins провайдера мають три шари: -- **Метадані маніфесту** для дешевого пошуку до запуску середовища виконання: - `setup.providers[].envVars`, застарілий шар сумісності `providerAuthEnvVars`, +- **Метадані маніфесту** для дешевого пошуку до середовища виконання: + `setup.providers[].envVars`, застарілий сумісний `providerAuthEnvVars`, `providerAuthAliases`, `providerAuthChoices` і `channelEnvVars`. - **Хуки часу конфігурації**: `catalog` (застарілий `discovery`) плюс `applyConfigDefaults`. -- **Хуки середовища виконання**: понад 40 необов’язкових хуків, що охоплюють auth, визначення моделі, - обгортання потоку, рівні thinking, політику відтворення та кінцеві точки використання. Див. - повний список у розділі [Порядок і використання хуків](#hook-order-and-usage). +- **Хуки середовища виконання**: понад 40 необов’язкових хуків, що охоплюють + автентифікацію, розв’язання моделей, обгортання потоків, рівні мислення, політику повторного відтворення та + кінцеві точки використання. Повний список див. в розділі [Порядок і використання хуків](#hook-order-and-usage). -OpenClaw, як і раніше, володіє загальним циклом агента, failover, обробкою транскриптів і -політикою інструментів. Ці хуки є поверхнею розширення для специфічної для провайдера -поведінки без потреби в цілком окремому транспорті інференсу. +OpenClaw, як і раніше, володіє загальним циклом агента, перемиканням на резерв, +обробкою транскриптів і політикою інструментів. Ці хуки є поверхнею розширення для +специфічної для провайдера поведінки без потреби у повністю власному транспорті інференсу. -Використовуйте маніфест `setup.providers[].envVars`, коли провайдер має облікові дані на основі env, -які мають бачити загальні шляхи auth/status/model-picker без -завантаження середовища виконання plugin. Застарілий `providerAuthEnvVars` усе ще зчитується адаптером сумісності -протягом перехідного вікна, а невбудовані plugin, які його використовують, отримують -діагностику маніфесту. Використовуйте маніфест `providerAuthAliases`, коли один id провайдера -має повторно використовувати env vars, профілі auth, auth на основі конфігурації та -варіант онбордингу API-ключа іншого id провайдера. Використовуйте маніфест -`providerAuthChoices`, коли поверхні CLI для онбордингу/вибору auth мають знати -id варіанта провайдера, підписи груп і просту прив’язку auth через один прапорець без -завантаження середовища виконання провайдера. Зберігайте в середовищі виконання провайдера -`envVars` для підказок, орієнтованих на операторів, як-от підписи онбордингу або змінні налаштування -OAuth client-id/client-secret. +Використовуйте маніфест `setup.providers[].envVars`, коли провайдер має облікові дані, керовані змінними середовища, +які загальні шляхи автентифікації/стану/вибору моделі мають бачити без +завантаження середовища виконання plugin. Застарілий `providerAuthEnvVars` усе ще зчитується +адаптером сумісності протягом періоду застарівання, а невбудовані plugins, які +його використовують, отримують діагностику маніфесту. Використовуйте маніфест `providerAuthAliases`, +коли один id провайдера має повторно використовувати змінні середовища іншого id провайдера, профілі автентифікації, +автентифікацію на основі конфігурації та варіант онбордингу з API-ключем. Використовуйте маніфест +`providerAuthChoices`, коли поверхні CLI для онбордингу/вибору автентифікації повинні знати +id варіанта провайдера, мітки груп і просте налаштування автентифікації з одним прапорцем без +завантаження середовища виконання провайдера. Залишайте у середовищі виконання провайдера +`envVars` для підказок, орієнтованих на оператора, таких як мітки онбордингу або +змінні налаштування OAuth client-id/client-secret. -Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування, керовані env, які -загальний резервний шлях shell-env, перевірки config/status або підказки налаштування мають бачити -без завантаження середовища виконання каналу. +Використовуйте маніфест `channelEnvVars`, коли канал має автентифікацію або налаштування, керовані змінними середовища, +які загальний резервний механізм shell-env, перевірки конфігурації/стану або підказки налаштування +мають бачити без завантаження середовища виконання каналу. ### Порядок і використання хуків -Для plugin моделі/провайдера OpenClaw викликає хуки приблизно в такому порядку. -Стовпець «Коли використовувати» — це короткий посібник для вибору. +Для plugins моделі/провайдера OpenClaw викликає хуки приблизно в такому порядку. +Стовпець «Коли використовувати» — це короткий орієнтир для вибору. -| # | Хук | Що він робить | Коли використовувати | +| # | Хук | Що він робить | Коли використовувати | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або значеннями `base URL` за замовчуванням | -| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації за замовчуванням, що належать провайдеру, під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей провайдера | -| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(це не хук plugin)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або попередні псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним визначенням моделі | -| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для користувацьких id провайдера в тому самому сімействі транспортів | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням конфігурації/провайдера в середовищі виконання | Провайдеру потрібне очищення конфігурації, яке має жити разом із plugin; вбудовані помічники сімейства Google також страхують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування native streaming-usage до провайдерів конфігурації | Провайдеру потрібні виправлення метаданих native streaming usage, що залежать від кінцевої точки | -| 7 | `resolveConfigApiKey` | Визначає auth з маркером env для провайдерів конфігурації перед завантаженням auth у середовищі виконання | Провайдер має власне визначення API-ключа з маркером env; `amazon-bedrock` також має тут вбудований резолвер маркера AWS env | -| 8 | `resolveSyntheticAuth` | Показує локальний/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | -| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth-профілі, що належать провайдеру; типове значення `persistence` — `runtime-only` для облікових даних, що належать CLI/застосунку | Провайдер повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті | -| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених заповнювачів синтетичного профілю порівняно з auth на основі env/конфігурації | Провайдер зберігає синтетичні профілі-заповнювачі, які не повинні мати вищий пріоритет | -| 11 | `resolveDynamicModel` | Синхронний резервний шлях для model id, що належать провайдеру, але ще відсутні в локальному реєстрі | Провайдер приймає довільні upstream model id | -| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | -| 13 | `normalizeResolvedModel` | Фінальне переписування перед тим, як вбудований раннер використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт core | -| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для моделей вендора, що працюють через інший сумісний транспорт | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе роль провайдера | -| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру й використовуються спільною логікою core | Провайдеру потрібні особливості транскрипту/сімейства провайдера | -| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований раннер | Провайдеру потрібне очищення схем для сімейства транспортів | -| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження щодо ключових слів без додавання до core специфічних для провайдера правил | -| 18 | `resolveReasoningOutputMode` | Вибирає native чи tagged контракт виводу reasoning | Провайдеру потрібен tagged reasoning/фінальний вивід замість native полів | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного провайдера | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдеру потрібен користувацький wire protocol, а не просто обгортка | -| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки заголовків/тіла запиту/сумісності моделі без користувацького транспорту | -| 22 | `resolveTransportTurnState` | Додає native заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали native ідентичність ходу провайдера | -| 23 | `resolveWebSocketSessionPolicy` | Додає native заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику резервного шляху | -| 24 | `formatApiKey` | Форматер auth-профілю: збережений профіль перетворюється на рядок `apiKey` у середовищі виконання | Провайдер зберігає додаткові метадані auth і потребує користувацької форми токена в середовищі виконання | -| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для користувацьких кінцевих точок оновлення або політики помилок оновлення | Провайдер не підходить під спільні засоби оновлення `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка щодо виправлення, яка додається, коли оновлення OAuth завершується помилкою | Провайдеру потрібні власні рекомендації з виправлення auth після помилки оновлення | -| 27 | `matchesContextOverflowError` | Матчер переповнення контекстного вікна, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики не помітять | -| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з перевищенням ліміту, перевантаженням тощо | -| 29 | `isCacheTtlEligible` | Політика TTL кешу промптів для proxy/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для proxy | -| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення при відсутності auth | Провайдеру потрібна власна підказка відновлення для випадків відсутності auth | -| 31 | `suppressBuiltInModel` | Приховування застарілих upstream моделей плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі upstream записи або замінити їх підказкою вендора | -| 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-профілів і вибору для smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke | -| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед інференсом | Провайдеру потрібен обмін токена або короткоживучі облікові дані для запиту | -| 39 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` і пов’язаних поверхонь статусу | Провайдеру потрібен користувацький розбір токенів usage/quota або інші облікові дані usage | -| 40 | `fetchUsageSnapshot` | Отримує та нормалізує специфічні для провайдера знімки usage/quota після визначення auth | Провайдеру потрібна специфічна для провайдера кінцева точка usage або парсер корисного навантаження | -| 41 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка memory embedding має належати plugin провайдера | -| 42 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна користувацька політика транскрипту (наприклад, видалення блоків thinking) | -| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні специфічні для провайдера переписування replay понад спільні допоміжні засоби Compaction | -| 44 | `validateReplayTurns` | Фінальна перевірка або переформування ходів replay перед вбудованим раннером | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санітизації | -| 45 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | +| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями `base URL` | +| 2 | `applyConfigDefaults` | Застосовує типові глобальні значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму автентифікації, середовища або семантики сімейства моделей провайдера | +| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку намагається використати звичайний шлях через реєстр/каталог | _(це не хук plugin)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми `model-id` перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним розв’язанням моделі | +| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдерів перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для власних id провайдера в межах того самого сімейства транспорту | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед розв’язанням середовища виконання/провайдера | Провайдеру потрібно очищення конфігурації, яке має жити разом із plugin; вбудовані помічники сімейства Google також страхують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування native streaming-usage до конфігурацій провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, зумовлені кінцевою точкою | +| 7 | `resolveConfigApiKey` | Розв’язує автентифікацію 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, що належать провайдеру, але ще відсутні в локальному реєстрі | Провайдер приймає довільні upstream model id | +| 12 | `prepareDynamicModel` | Асинхронний розігрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед розв’язанням невідомих id | +| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як вбудований runner використає розв’язану модель | Провайдеру потрібні переписування транспорту, але він і далі використовує транспорт ядра | +| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для моделей вендора за іншим сумісним транспортом | Провайдер розпізнає власні моделі на проксі-транспортах, не перебираючи на себе керування провайдером | +| 15 | `capabilities` | Метадані транскрипту/інструментарію, що належать провайдеру та використовуються спільною логікою ядра | Провайдеру потрібні особливості транскрипту/сімейства провайдера | +| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований runner | Провайдеру потрібне очищення схем для сімейства транспорту | +| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження щодо ключових слів без додавання до ядра специфічних для провайдера правил | +| 18 | `resolveReasoningOutputMode` | Вибирає контракт виводу reasoning: native чи tagged | Провайдеру потрібен tagged reasoning/final output замість native-полів | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку власним транспортом | Провайдеру потрібен власний wire protocol, а не лише обгортка | +| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності заголовків/тіла/model запиту без власного транспорту | +| 22 | `resolveTransportTurnState` | Додає native-заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали native-ідентифікатор ходу, властивий провайдеру | +| 23 | `resolveWebSocketSessionPolicy` | Додає native-заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або резервну політику | +| 24 | `formatApiKey` | Форматувач профілю автентифікації: збережений профіль стає рядком `apiKey` у середовищі виконання | Провайдер зберігає додаткові метадані автентифікації та потребує власної форми токена для середовища виконання | +| 25 | `refreshOAuth` | Перевизначення OAuth refresh для власних кінцевих точок оновлення або політики збоїв під час оновлення | Провайдер не відповідає спільним засобам оновлення `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка для виправлення, що додається, коли оновлення OAuth завершується невдачею | Провайдеру потрібні власні рекомендації з відновлення автентифікації після помилки оновлення | +| 27 | `matchesContextOverflowError` | Зіставлення переповнення контекстного вікна, що належить провайдеру | Провайдер має сирі помилки переповнення, які пропустять загальні евристики | +| 28 | `classifyFailoverReason` | Класифікація причин перемикання на резерв, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/перевантаженням тощо | +| 29 | `isCacheTtlEligible` | Політика TTL кешу промптів для проксі/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для проксі | +| 30 | `buildMissingAuthMessage` | Замінник загального повідомлення відновлення при відсутній автентифікації | Провайдеру потрібна специфічна для нього підказка відновлення при відсутній автентифікації | +| 31 | `suppressBuiltInModel` | Застаріло. Хук середовища виконання більше не викликається; використовуйте маніфест `modelCatalog.suppressions` | Історичний хук для приховування застарілих upstream-рядків; нові дані приглушення слід зберігати в маніфесті plugin | +| 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 для фільтрів живих профілів і вибору smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke | +| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед інференсом | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | +| 39 | `resolveUsageAuth` | Розв’язує облікові дані використання/білінгу для `/usage` і пов’язаних поверхонь стану | Провайдеру потрібен власний синтаксичний аналіз токена використання/квоти або інші облікові дані використання | +| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки використання/квоти, специфічні для провайдера, після розв’язання автентифікації | Провайдеру потрібна специфічна для нього кінцева точка використання або парсер корисного навантаження | +| 41 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті має належати plugin провайдера | +| 42 | `buildReplayPolicy` | Повертає політику відтворення, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна власна політика транскрипту (наприклад, вилучення блоків thinking) | +| 43 | `sanitizeReplayHistory` | Переписує історію відтворення після загального очищення транскрипту | Провайдеру потрібні специфічні для нього переписування відтворення понад спільні допоміжні засоби Compaction | +| 44 | `validateReplayTurns` | Остаточна перевірка або переформування ходів відтворення перед вбудованим runner | Транспорту провайдера потрібна суворіша перевірка ходів після загального очищення | +| 45 | `onModelSelected` | Виконує побічні ефекти після вибору, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -відповідний plugin провайдера, а потім переходять до інших plugin провайдерів, здатних до хуків, -доки один із них справді не змінить id моделі або transport/config. Це зберігає -працездатність shim для alias/compat провайдерів без вимоги, щоб викликач знав, який -вбудований plugin володіє цим переписуванням. Якщо жоден хук провайдера не переписує підтримуваний +зіставлений plugin провайдера, а потім переходять до інших plugins провайдера, здатних до хуків, +доки один із них справді не змінить id моделі або transport/config. Це дозволяє +аліасам і сумісним shim-провайдерам працювати без вимоги, щоб викликач знав, +який саме вбудований plugin володіє цим переписуванням. Якщо жоден хук провайдера не переписує підтримуваний запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно застосовує це очищення сумісності. -Якщо провайдеру потрібен повністю користувацький wire protocol або користувацький виконавець запитів, +Якщо провайдеру потрібен повністю власний wire protocol або власний виконавець запитів, це вже інший клас розширення. Ці хуки призначені для поведінки провайдера, -яка все ще працює в межах звичайного циклу інференсу OpenClaw. +яка все ще виконується в межах звичайного циклу інференсу OpenClaw. ### Приклад провайдера @@ -338,35 +338,35 @@ api.registerProvider({ ### Вбудовані приклади -Вбудовані plugin провайдерів поєднують наведені вище хуки, щоб відповідати потребам кожного вендора -щодо каталогу, auth, thinking, replay і usage. Авторитетний набір хуків живе разом +Вбудовані plugins провайдерів поєднують наведені вище хуки, щоб відповідати потребам кожного вендора +щодо каталогу, автентифікації, thinking, відтворення та використання. Авторитетний набір хуків розміщено разом із кожним plugin у `extensions/`; ця сторінка ілюструє форми, а не віддзеркалює список. - OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` разом із + OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` плюс `resolveDynamicModel` / `prepareDynamicModel`, щоб вони могли показувати upstream - model id раніше за статичний каталог OpenClaw. + id моделей раніше за статичний каталог OpenClaw. - + GitHub Copilot, Gemini CLI, ChatGPT Codex, MiniMax, Xiaomi, z.ai поєднують `prepareRuntimeAuth` або `formatApiKey` з `resolveUsageAuth` + - `fetchUsageSnapshot`, щоб володіти обміном токенів та інтеграцією `/usage`. + `fetchUsageSnapshot`, щоб володіти обміном токенів та інтеграцією з `/usage`. - + Спільні іменовані сімейства (`google-gemini`, `passthrough-gemini`, - `anthropic-by-model`, `hybrid-anthropic-openai`) дають змогу провайдерам - підключатися до політики транскриптів через `buildReplayPolicy` замість того, щоб кожен plugin - повторно реалізовував очищення. + `anthropic-by-model`, `hybrid-anthropic-openai`) дозволяють провайдерам підключатися до + політики транскрипту через `buildReplayPolicy`, замість того щоб кожен plugin + перевпроваджував очищення. - + `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і - `volcengine` реєструють лише `catalog` і використовують спільний цикл інференсу. + `volcengine` реєструють лише `catalog` і працюють на спільному циклі інференсу. - - Бета-заголовки, `/fast` / `serviceTier` і `context1m` знаходяться в + + Бета-заголовки, `/fast` / `serviceTier` і `context1m` розміщені в публічному seam `api.ts` / `contract-api.ts` plugin Anthropic (`wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`), а не в @@ -376,7 +376,7 @@ api.registerProvider({ ## Допоміжні засоби середовища виконання -Plugin можуть отримувати доступ до вибраних допоміжних засобів core через `api.runtime`. Для TTS: +Plugins можуть отримувати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -397,14 +397,14 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайне корисне навантаження виводу TTS із core для поверхонь файлів/голосових нотаток. -- Використовує конфігурацію core `messages.tts` і вибір провайдера. -- Повертає буфер PCM-аудіо + частоту дискретизації. Plugin повинні виконувати ресемплінг/кодування для провайдерів. +- `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових нотаток. +- Використовує конфігурацію ядра `messages.tts` і вибір провайдера. +- Повертає PCM-аудіобуфер + частоту дискретизації. Plugins мають виконувати ресемплінг/кодування для провайдерів. - `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать вендору. -- Списки голосів можуть містити багатші метадані, наприклад locale, gender і теги personality для засобів вибору, обізнаних про провайдера. -- Сьогодні телефонію підтримують OpenAI та ElevenLabs. Microsoft — ні. +- Списки голосів можуть містити розширені метадані, як-от локаль, стать і теги характеру для засобів вибору, обізнаних про провайдера. +- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. -Plugin також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. +Plugins також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -424,15 +424,15 @@ api.registerSpeechProvider({ Примітки: -- Зберігайте політику TTS, fallback і доставку відповіді в core. +- Зберігайте політику TTS, резервний механізм і доставку відповіді в ядрі. - Використовуйте провайдерів мовлення для поведінки синтезу, що належить вендору. - Застарілий вхід Microsoft `edge` нормалізується до id провайдера `microsoft`. - Бажана модель володіння орієнтована на компанію: один plugin вендора може володіти - текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами, коли OpenClaw додаватиме ці + текстовими, голосовими, графічними та майбутніми медіапровайдерами, у міру того як OpenClaw додає ці контракти можливостей. -Для розуміння зображень/аудіо/відео plugin реєструють один типізований -провайдер media-understanding замість узагальненого сховища ключ/значення: +Для розуміння зображень/аудіо/відео plugins реєструють один типізований +провайдер розуміння медіа замість загального набору ключ/значення: ```ts api.registerMediaUnderstandingProvider({ @@ -446,16 +446,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Зберігайте оркестрацію, fallback, config і прив’язку каналів у core. +- Зберігайте оркестрацію, резервний механізм, конфігурацію та підключення каналів у ядрі. - Зберігайте поведінку вендора в plugin провайдера. - Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові поля результату, нові необов’язкові можливості. -- Генерація відео вже дотримується тієї самої схеми: - - core володіє контрактом можливості та допоміжним засобом середовища виконання - - plugin вендора реєструють `api.registerVideoGenerationProvider(...)` - - plugin функцій/каналів споживають `api.runtime.videoGeneration.*` +- Генерація відео вже використовує той самий шаблон: + - ядро володіє контрактом можливості та допоміжним засобом середовища виконання + - plugins вендорів реєструють `api.registerVideoGenerationProvider(...)` + - plugins можливостей/каналів споживають `api.runtime.videoGeneration.*` -Для допоміжних засобів середовища виконання media-understanding plugin можуть викликати: +Для допоміжних засобів середовища виконання розуміння медіа plugins можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -470,7 +470,7 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрибування аудіо plugin можуть використовувати або середовище виконання media-understanding, +Для транскрибування аудіо plugins можуть використовувати або середовище виконання розуміння медіа, або старіший псевдонім STT: ```ts @@ -484,13 +484,13 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ Примітки: -- `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для +- `api.runtime.mediaUnderstanding.*` є бажаною спільною поверхнею для розуміння зображень/аудіо/відео. -- Використовує конфігурацію аудіо media-understanding із core (`tools.media.audio`) та порядок fallback провайдерів. -- Повертає `{ text: undefined }`, коли вихід транскрибування не створено (наприклад, вхід пропущено/не підтримується). +- Використовує аудіоконфігурацію розуміння медіа ядра (`tools.media.audio`) і порядок резервного вибору провайдерів. +- Повертає `{ text: undefined }`, коли вивід транскрибування не створено (наприклад, якщо вхід пропущено або не підтримується). - `api.runtime.stt.transcribeAudioFile(...)` залишається як псевдонім сумісності. -Plugin також можуть запускати фонові запуски субагента через `api.runtime.subagent`: +Plugins також можуть запускати фонові виконання субагентів через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -504,15 +504,15 @@ const result = await api.runtime.subagent.run({ Примітки: -- `provider` і `model` є необов’язковими перевизначеннями для окремого запуску, а не постійними змінами сесії. +- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. - OpenClaw враховує ці поля перевизначення лише для довірених викликачів. -- Для fallback-запусків, що належать plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugin конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі. -- Запуски субагента з недовірених plugin усе ще працюють, але запити на перевизначення відхиляються, а не тихо переходять у fallback. -- Сесії субагента, створені plugin, позначаються id plugin, який їх створив. Fallback `api.runtime.subagent.deleteSession(...)` може видаляти лише такі сесії, що належать власнику; довільне видалення сесій, як і раніше, потребує запиту Gateway з адміністраторською областю дії. +- Для резервних запусків, що належать plugin, оператори повинні явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugins конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. +- Запуски субагентів із недовірених plugins усе ще працюють, але запити на перевизначення відхиляються замість мовчазного переходу до резервного механізму. +- Сесії субагентів, створені plugin, позначаються id plugin, який їх створив. Резервний `api.runtime.subagent.deleteSession(...)` може видаляти лише ці сесії-власники; довільне видалення сесій, як і раніше, потребує запиту Gateway з областю admin. -Для вебпошуку plugin можуть використовувати спільний допоміжний засіб середовища виконання замість -занурення у прив’язку інструментів агента: +Для вебпошуку plugins можуть використовувати спільний допоміжний засіб середовища виконання замість +звернення безпосередньо до підключення інструментів агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -528,14 +528,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Plugin також можуть реєструвати провайдерів web-search через +Plugins також можуть реєструвати провайдерів вебпошуку через `api.registerWebSearchProvider(...)`. Примітки: -- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у core. -- Використовуйте провайдерів web-search для специфічних для вендора пошукових транспортів. -- `api.runtime.webSearch.*` — це бажана спільна поверхня для plugin функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструментів агента. +- Зберігайте вибір провайдера, розв’язання облікових даних і спільну семантику запитів у ядрі. +- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для вендора. +- `api.runtime.webSearch.*` є бажаною спільною поверхнею для plugins можливостей/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструментів агента. ### `api.runtime.imageGeneration` @@ -550,12 +550,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. -- `listProviders(...)`: показує доступних провайдерів генерації зображень і їхні можливості. +- `generate(...)`: згенерувати зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. +- `listProviders(...)`: вивести список доступних провайдерів генерації зображень та їхніх можливостей. ## HTTP-маршрути Gateway -Plugin можуть відкривати HTTP-ендпойнти через `api.registerHttpRoute(...)`. +Plugins можуть відкривати HTTP-кінцеві точки через `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -573,163 +573,164 @@ api.registerHttpRoute({ Поля маршруту: - `path`: шлях маршруту під HTTP-сервером gateway. -- `auth`: обов’язкове. Використовуйте `"gateway"`, щоб вимагати звичайну auth gateway, або `"plugin"` для auth/перевірки Webhook, якими керує plugin. -- `match`: необов’язкове. `"exact"` (типово) або `"prefix"`. -- `replaceExisting`: необов’язкове. Дає змогу тому самому plugin замінити власну наявну реєстрацію маршруту. -- `handler`: повертайте `true`, коли маршрут обробив запит. +- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайну автентифікацію gateway, або `"plugin"` для автентифікації/перевірки Webhook, якими керує plugin. +- `match`: необов’язкове поле. `"exact"` (типово) або `"prefix"`. +- `replaceExisting`: необов’язкове поле. Дозволяє тому самому plugin замінити власну наявну реєстрацію маршруту. +- `handler`: повертає `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` було видалено, і його використання спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`. -- Маршрути plugin мають явно оголошувати `auth`. +- `api.registerHttpHandler(...)` було вилучено, і воно спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`. +- Маршрути plugin повинні явно оголошувати `auth`. - Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin. -- Перекривні маршрути з різними рівнями `auth` відхиляються. Ланцюжки переходу `exact`/`prefix` мають бути лише на одному й тому самому рівні auth. -- Маршрути `auth: "plugin"` **не** отримують автоматично області дії середовища виконання оператора. Вони призначені для Webhook/перевірки підписів, якими керує plugin, а не для привілейованих допоміжних викликів Gateway. -- Маршрути `auth: "gateway"` працюють в межах області дії середовища виконання запиту Gateway, але ця область навмисно консервативна: - - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області дії середовища виконання маршрутів plugin зафіксованими на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` - - довірені HTTP-режими з носієм ідентичності (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes`, лише коли цей заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах до маршрутів plugin із носієм ідентичності, область дії середовища виконання повертається до `operator.write` -- Практичне правило: не припускайте, що маршрут plugin з auth gateway є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з носієм ідентичності та задокументуйте явний контракт заголовка `x-openclaw-scopes`. +- Перекривні маршрути з різними рівнями `auth` відхиляються. Підтримуйте ланцюжки проходження `exact`/`prefix` лише в межах одного рівня 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 неявною поверхнею admin. Якщо вашому маршруту потрібна поведінка лише для admin, вимагайте режим автентифікації з передаванням ідентичності та документуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK -Під час розробки нових plugin використовуйте вузькі підшляхи SDK замість монолітного +Під час створення нових plugins використовуйте вузькі підшляхи SDK замість монолітного кореневого barrel `openclaw/plugin-sdk`. Основні підшляхи: -| Підшлях | Призначення | -| ----------------------------------- | -------------------------------------------------- | -| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації plugin | -| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби для входу/побудови каналу | -| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella contract | +| Підшлях | Призначення | +| ---------------------------------- | -------------------------------------------------- | +| `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`) | -Плагіни каналів вибирають із сімейства вузьких seam — `channel-setup`, +Plugins каналів вибирають із сімейства вузьких seam — `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. Див. [Плагіни каналів](/uk/plugins/sdk-channel-plugins). +`channel-targets` і `channel-actions`. Поведінка погодження має консолідуватися +в одному контракті `approvalCapability`, а не змішуватися між не пов’язаними +полями plugin. Див. [Plugins каналів](/uk/plugins/sdk-channel-plugins). -Допоміжні засоби середовища виконання та конфігурації розміщені у відповідних сфокусованих підшляхах `*-runtime` +Допоміжні засоби середовища виконання та конфігурації розміщені під відповідними вузькоспрямованими підшляхами `*-runtime` (`approval-runtime`, `agent-runtime`, `lazy-runtime`, `directory-runtime`, `text-runtime`, `runtime-store`, `system-event-runtime`, `heartbeat-runtime`, -`channel-activity-runtime` тощо). Віддавайте перевагу `config-types`, +`channel-activity-runtime` тощо). Надавайте перевагу `config-types`, `plugin-config-runtime`, `runtime-config-snapshot` і `config-mutation` замість -широкого barrel сумісності `config-runtime`. +широкого сумісного barrel `config-runtime`. `openclaw/plugin-sdk/channel-runtime`, `openclaw/plugin-sdk/config-runtime` і `openclaw/plugin-sdk/infra-runtime` — це застарілі shim сумісності для -старіших plugin. Новий код має імпортувати вужчі загальні примітиви. +старіших plugins. Новий код має імпортувати натомість вужчі загальні примітиви. -Внутрішні для репозиторію точки входу (для кореня пакета кожного вбудованого plugin): +Внутрішні для репозиторію точки входу (для кожного кореня пакета вбудованого plugin): - `index.js` — точка входу вбудованого plugin - `api.js` — barrel допоміжних засобів/типів - `runtime-api.js` — barrel лише для середовища виконання - `setup-entry.js` — точка входу plugin для налаштування -Зовнішні plugin мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи -не імпортуйте `src/*` іншого пакета plugin із core або з іншого plugin. -Точки входу, завантажені через facade, надають перевагу активному знімку конфігурації середовища виконання, якщо він -існує, а потім повертаються до визначеного файлу конфігурації на диску. +Зовнішні plugins повинні імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи +не імпортуйте `src/*` іншого пакета plugin із ядра або з іншого plugin. +Точки входу, завантажені через facade, надають перевагу активному знімку конфігурації середовища виконання, якщо він існує, +а потім повертаються до розв’язаної конфігурації на диску. Підшляхи, специфічні для можливостей, такі як `image-generation`, `media-understanding` -і `speech`, існують, бо вбудовані plugin використовують їх уже сьогодні. Це не -автоматично довгостроково зафіксовані зовнішні контракти — перевіряйте відповідну довідкову -сторінку SDK, коли покладаєтеся на них. +і `speech`, існують, тому що вбудовані plugins використовують їх уже сьогодні. Вони не є +автоматично зовнішніми контрактами, замороженими на довгий термін — перевіряйте відповідну +довідкову сторінку SDK, коли покладаєтеся на них. ## Схеми інструментів повідомлень -Plugin мають володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу, -для немеседжних примітивів, таких як реакції, читання та опитування. -Спільне подання надсилання має використовувати загальний контракт `MessagePresentation` -замість native полів кнопок, компонентів, блоків або карток, специфічних для провайдера. -Див. [Message Presentation](/uk/plugins/message-presentation), щоб ознайомитися з контрактом, -правилами fallback, зіставленням провайдерів і контрольним списком для авторів plugin. +Plugins повинні володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу, +для немеседжних примітивів, таких як реакції, позначення прочитаного та опитування. +Спільне представлення надсилання має використовувати загальний контракт `MessagePresentation` +замість власних для провайдера полів кнопок, компонентів, блоків або карток. +Див. [Message Presentation](/uk/plugins/message-presentation), щоб дізнатися про контракт, +правила резервного механізму, зіставлення провайдерів і контрольний список автора plugin. -Plugin із підтримкою надсилання оголошують, що вони можуть відтворювати, через можливості повідомлень: +Plugins, здатні надсилати, оголошують, що саме вони можуть відображати, через можливості повідомлень: -- `presentation` для семантичних блоків подання (`text`, `context`, `divider`, `buttons`, `select`) +- `presentation` для блоків семантичного представлення (`text`, `context`, `divider`, `buttons`, `select`) - `delivery-pin` для запитів закріпленої доставки -Core вирішує, чи відтворювати подання native способом, чи деградувати його до тексту. -Не відкривайте обхідні шляхи native UI, специфічні для провайдера, із загального інструмента повідомлень. -Застарілі допоміжні засоби SDK для старих native схем залишаються експортованими для наявних -сторонніх plugin, але нові plugin не повинні їх використовувати. +Ядро вирішує, чи відображати представлення нативно, чи деградувати його до тексту. +Не відкривайте власні для провайдера шляхи обходу UI через загальний інструмент повідомлень. +Застарілі допоміжні засоби SDK для старих нативних схем усе ще експортуються для наявних +сторонніх plugins, але нові plugins не повинні їх використовувати. -## Визначення цілей каналу +## Розв’язання цілей каналу -Плагіни каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний -хост вихідного трафіку загальним і використовуйте поверхню messaging adapter для правил провайдера: +Plugins каналів повинні володіти семантикою цілей, специфічною для каналу. Зберігайте спільний +вихідний хост узагальненим і використовуйте поверхню адаптера повідомлень для правил провайдера: -- `messaging.inferTargetChatType({ to })` вирішує, чи слід нормалізовану ціль - трактувати як `direct`, `group` або `channel` до пошуку в каталозі. -- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє core, чи - слід входу одразу перейти до визначення id-подібної цілі замість пошуку в каталозі. -- `messaging.targetResolver.resolveTarget(...)` — це резервний шлях plugin, коли - core потрібне фінальне визначення, що належить провайдеру, після нормалізації або - після промаху в каталозі. -- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, - специфічною для провайдера, після того як ціль визначено. +- `messaging.inferTargetChatType({ to })` вирішує, чи нормалізовану ціль + слід трактувати як `direct`, `group` або `channel` до пошуку в каталозі. +- `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи + вхід слід одразу передати до розв’язання як id-подібний замість пошуку в каталозі. +- `messaging.targetResolver.resolveTarget(...)` — це резервний механізм plugin, коли + ядру потрібне фінальне розв’язання, що належить провайдеру, після нормалізації або після + пропуску в каталозі. +- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту вихідної сесії, + специфічною для провайдера, після розв’язання цілі. -Рекомендований поділ: +Рекомендований розподіл: -- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають ухвалюватися до - пошуку peer/group. -- Використовуйте `looksLikeId` для перевірок на кшталт «трактувати це як явний/native id цілі». +- Використовуйте `inferTargetChatType` для рішень щодо категорій, які мають відбуватися до + пошуку серед peer/group. +- Використовуйте `looksLikeId` для перевірок «трактувати це як явний/native id цілі». - Використовуйте `resolveTarget` для резервної нормалізації, специфічної для провайдера, а не для широкого пошуку в каталозі. -- Зберігайте native id провайдера, як-от chat id, thread id, JID, handle і room - id, всередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK. +- Зберігайте власні для провайдера id, такі як chat id, thread id, JID, handle і room + id, усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних + полях SDK. ## Каталоги на основі конфігурації -Plugin, які формують записи каталогу з конфігурації, мають тримати цю логіку в +Plugins, які виводять записи каталогу з конфігурації, повинні тримати цю логіку в plugin і повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні peer/group на основі конфігурації, такі як: +Використовуйте це, коли каналу потрібні peer/group на основі конфігурації, наприклад: -- peer DM, керовані allowlist -- налаштовані мапи каналів/груп -- статичні резервні варіанти каталогу з областю дії облікового запису +- DM peer, керовані allowlist +- налаштовані зіставлення каналів/group +- статичні резервні каталоги в межах облікового запису Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: - фільтрацію запитів -- застосування лімітів +- застосування ліміту - допоміжні засоби дедуплікації/нормалізації - побудову `ChannelDirectoryEntry[]` -Специфічні для каналу перевірка облікового запису та нормалізація id мають залишатися в -реалізації plugin. +Перевірка облікового запису та нормалізація id, специфічні для каналу, повинні залишатися в реалізації +plugin. ## Каталоги провайдерів -Plugin провайдерів можуть визначати каталоги моделей для інференсу через +Plugins провайдерів можуть визначати каталоги моделей для інференсу за допомогою `registerProvider({ catalog: { run(...) { ... } } })`. -`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в +`catalog.run(...)` повертає ту саму форму, яку OpenClaw записує до `models.providers`: - `{ provider }` для одного запису провайдера - `{ providers }` для кількох записів провайдера -Використовуйте `catalog`, коли plugin володіє специфічними для провайдера model id, значеннями `base URL` -за замовчуванням або метаданими моделей, що залежать від auth. +Використовуйте `catalog`, коли plugin володіє model id, специфічними для провайдера, типовими +значеннями base URL або метаданими моделі, що залежать від автентифікації. -`catalog.order` визначає, коли каталог plugin зливається відносно вбудованих -неявних провайдерів OpenClaw: +`catalog.order` керує тим, коли каталог plugin зливається відносно неявних +вбудованих провайдерів OpenClaw: -- `simple`: звичайні провайдери на основі API-ключа або env -- `profile`: провайдери, які з’являються, коли існують auth-профілі -- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів -- `late`: останній прохід, після інших неявних провайдерів +- `simple`: прості провайдери, керовані API-ключем або змінними середовища +- `profile`: провайдери, які з’являються, коли існують профілі автентифікації +- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдера +- `late`: останній прохід після інших неявних провайдерів -Пізніші провайдери перемагають у разі колізії ключів, тож plugin можуть навмисно перевизначати +Пізніші провайдери виграють у разі колізії ключів, тож plugins можуть навмисно перевизначати вбудований запис провайдера з тим самим id провайдера. Сумісність: @@ -737,7 +738,7 @@ Plugin провайдерів можуть визначати каталоги - `discovery` усе ще працює як застарілий псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Інспектування каналу лише для читання +## Інспекція каналу лише для читання Якщо ваш plugin реєструє канал, надавайте перевагу реалізації `plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`. @@ -745,7 +746,7 @@ Plugin провайдерів можуть визначати каталоги Чому: - `resolveAccount(...)` — це шлях середовища виконання. Він може припускати, що облікові дані - повністю матеріалізовано, і швидко завершуватися з помилкою, якщо потрібні секрети відсутні. + повністю матеріалізовані, і може швидко завершуватися з помилкою, коли потрібні секрети відсутні. - Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`, `openclaw channels status`, `openclaw channels resolve` і потоки doctor/config repair, не повинні вимагати матеріалізації облікових даних середовища виконання лише для @@ -755,20 +756,21 @@ Plugin провайдерів можуть визначати каталоги - Повертає лише описовий стан облікового запису. - Зберігає `enabled` і `configured`. -- Містить поля джерела/статусу облікових даних, коли це доречно, наприклад: +- Додає поля джерела/стану облікових даних, коли це доречно, наприклад: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі лише читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). +- Не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі лише читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела) для команд у стилі status. - Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але вони недоступні в поточному шляху команди. -Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або помилкового повідомлення, що обліковий запис не налаштовано. +Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому +шляху команди» замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. ## Пакетні набори -Каталог plugin може містити `package.json` із `openclaw.extensions`: +Каталог plugin може містити `package.json` з `openclaw.extensions`: ```json { @@ -780,67 +782,67 @@ Plugin провайдерів можуть визначати каталоги } ``` -Кожен запис стає plugin. Якщо пакет перераховує кілька extensions, id plugin +Кожен запис стає plugin. Якщо набір містить кілька extensions, id plugin стає `name/`. -Якщо ваш plugin імпортує npm-залежності, установіть їх у цьому каталозі, щоб +Якщо ваш plugin імпортує залежності npm, установіть їх у цьому каталозі, щоб `node_modules` був доступний (`npm install` / `pnpm install`). -Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу plugin -після визначення symlink. Записи, що виходять за межі каталогу пакета, +Захисне обмеження безпеки: кожен запис `openclaw.extensions` повинен залишатися в межах каталогу plugin +після розв’язання symlink. Записи, що виходять за межі каталогу пакета, відхиляються. -Примітка щодо безпеки: `openclaw plugins install` установлює залежності plugin за допомогою +Примітка щодо безпеки: `openclaw plugins install` встановлює залежності plugin за допомогою локального для проєкту `npm install --omit=dev --ignore-scripts` (без lifecycle scripts, -без dev dependencies у середовищі виконання), ігноруючи успадковані глобальні налаштування встановлення npm. -Зберігайте дерева залежностей plugin як "pure JS/TS" і уникайте пакетів, яким потрібні +без dev dependencies під час виконання), ігноруючи успадковані глобальні параметри встановлення npm. +Підтримуйте дерева залежностей plugin «чистими JS/TS» і уникайте пакетів, які вимагають збирання через `postinstall`. Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування. -Коли OpenClaw потребує поверхонь налаштування для вимкненого plugin каналу або -коли plugin каналу ввімкнено, але його ще не налаштовано, він завантажує `setupEntry` +Коли OpenClaw потрібні поверхні налаштування для вимкненого plugin каналу або +коли plugin каналу ввімкнений, але ще не налаштований, він завантажує `setupEntry` замість повної точки входу plugin. Це робить запуск і налаштування легшими, -коли ваша основна точка входу plugin також підключає інструменти, хуки або інший код -лише для середовища виконання. +коли основна точка входу plugin також підключає інструменти, хуки або інший код лише для середовища виконання. Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести plugin каналу на той самий шлях `setupEntry` під час -фази запуску gateway до початку прослуховування, навіть коли канал уже налаштовано. +може перевести plugin каналу на той самий шлях `setupEntry` під час фази запуску gateway до початку прослуховування, +навіть якщо канал уже налаштовано. Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати до того, як gateway почне прослуховування. На практиці це означає, що точка входу налаштування -має реєструвати кожну можливість, що належить каналу й від якої залежить запуск, наприклад: +повинна реєструвати кожну можливість, що належить каналу і від якої залежить запуск, наприклад: -- власне реєстрацію каналу -- будь-які HTTP-маршрути, які мають бути доступними до того, як gateway почне прослуховування -- будь-які методи gateway, інструменти або сервіси, які мають існувати в тому самому вікні +- саму реєстрацію каналу +- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне прослуховування +- будь-які методи gateway, інструменти або служби, які мають існувати в тому самому вікні Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте -цей прапорець. Залиште plugin із типовою поведінкою й дозвольте OpenClaw завантажити +цей прапорець. Залишайте для plugin типову поведінку й дозвольте OpenClaw завантажити повну точку входу під час запуску. -Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, які core -може використовувати до завантаження повного середовища виконання каналу. Поточна поверхня просування налаштування: +Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, з якими ядро +може працювати до завантаження повного середовища виконання каналу. Поточна поверхня +просування налаштування: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Core використовує цю поверхню, коли йому потрібно підвищити застарілу конфігурацію +Ядро використовує цю поверхню, коли йому потрібно підвищити застарілу конфігурацію каналу з одним обліковим записом до `channels..accounts.*` без завантаження повної точки входу plugin. -Поточний вбудований приклад — Matrix: він переносить лише ключі auth/bootstrap до -іменованого підвищеного облікового запису, коли іменовані облікові записи вже існують, і може зберегти -налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати +Поточний вбудований приклад — Matrix: він переміщує лише ключі auth/bootstrap до +іменованого підвищеного облікового запису, коли іменовані облікові записи вже існують, і може зберігати +налаштований неканонічний ключ типового облікового запису замість того, щоб завжди створювати `accounts.default`. -Ці адаптери патчів налаштування зберігають ліниве виявлення поверхні контракту вбудованих каналів. Час -імпорту залишається малим; поверхня підвищення завантажується лише під час першого використання, а не -повторно входить у запуск вбудованого каналу під час імпорту модуля. +Ці адаптери патчів налаштування зберігають ліниве виявлення поверхні контракту для вбудованих пакетів. +Час імпорту залишається малим; поверхня підвищення завантажується лише під час першого використання +замість повторного входу до запуску вбудованого каналу під час імпорту модуля. -Коли ці поверхні запуску включають Gateway RPC methods, залишайте їх на -префіксі, специфічному для plugin. Простори назв адміністратора core (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються -до `operator.admin`, навіть якщо plugin запитує вужчу область дії. +Коли ці поверхні запуску містять RPC-методи gateway, зберігайте їх на +специфічному для plugin префіксі. Простори імен admin ядра (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди +розв’язуються до `operator.admin`, навіть якщо plugin запитує вужчу область. Приклад: @@ -857,10 +859,10 @@ Core використовує цю поверхню, коли йому потр } ``` -### Метадані каталогу каналу +### Метадані каталогу каналів -Плагіни каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` та -підказки встановлення через `openclaw.install`. Це дозволяє core не містити даних каталогу. +Plugins каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel`, а +підказки встановлення — через `openclaw.install`. Це дозволяє ядру залишатися без даних каталогу. Приклад: @@ -875,7 +877,7 @@ Core використовує цю поверхню, коли йому потр "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Самостійно розгорнутий чат через webhook-ботів Nextcloud Talk.", + "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -891,65 +893,64 @@ Core використовує цю поверхню, коли йому потр Корисні поля `openclaw.channel` поза мінімальним прикладом: - `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу -- `docsLabel`: перевизначає текст посилання для посилання на документацію -- `preferOver`: id plugin/каналу з нижчим пріоритетом, які цей запис каталогу має перевершувати +- `docsLabel`: перевизначення тексту посилання для посилання на документацію +- `preferOver`: id plugin/каналу з нижчим пріоритетом, які цей запис каталогу має випереджати - `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору -- `markdownCapable`: позначає канал як здатний до Markdown для рішень щодо форматування вихідних повідомлень +- `markdownCapable`: позначає канал як здатний до markdown для рішень про вихідне форматування - `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` - `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено `false` -- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації +- `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документацією - `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure` -- `quickstartAllowFrom`: підключає канал до стандартного потоку швидкого старту `allowFrom` -- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення цілей announce +- `quickstartAllowFrom`: підключає канал до стандартного потоку `allowFrom` quickstart +- `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`). Кожен файл має -містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми ключа `"entries"`. +один або більше файлів JSON (розділених комою/крапкою з комою/форматом `PATH`). Кожен файл має +містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. -Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів показують -нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Нормалізовані -факти визначають, чи є npm spec точною версією чи плаваючим селектором, -чи присутні очікувані метадані цілісності, і чи також доступний локальний шлях до джерела. -Коли ідентичність каталогу/пакета відома, нормалізовані факти попереджають, якщо розібране ім’я -npm-пакета відхиляється від цієї ідентичності. Вони також попереджають, коли `defaultChoice` недійсний -або вказує на джерело, яке недоступне, і коли метадані цілісності npm присутні без дійсного -джерела npm. Споживачі мають трактувати `installSource` як адитивне необов’язкове поле, щоб -записи, створені вручну, і shim каталогу не мусили його синтезувати. -Це дає змогу онбордингу та діагностиці пояснювати стан площини джерела без +Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів відкривають +нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Ці +нормалізовані факти визначають, чи npm-специфікація є точною версією або плаваючим +селектором, чи присутні очікувані метадані цілісності та чи доступний також локальний +вихідний шлях. Коли ідентичність каталогу/пакета відома, нормалізовані факти попереджають, +якщо розібране ім’я пакета npm відхиляється від цієї ідентичності. Вони також попереджають, +коли `defaultChoice` є недійсним або вказує на джерело, яке недоступне, а також коли +метадані цілісності npm присутні без дійсного джерела npm. Споживачі повинні трактувати +`installSource` як адитивне необов’язкове поле, щоб записи, створені вручну, і shim каталогу +не були змушені його синтезувати. +Це дозволяє онбордингу та діагностиці пояснювати стан площини джерел без імпорту середовища виконання plugin. -Офіційні зовнішні записи npm мають віддавати перевагу точному `npmSpec` разом із -`expectedIntegrity`. Голі назви пакетів і dist-tag усе ще працюють для -сумісності, але вони показують попередження площини джерела, щоб каталог міг рухатися -до закріплених установлень із перевіркою цілісності, не ламаючи наявні plugin. -Коли онбординг установлює з локального шляху каталогу, він записує керований plugin -запис індексу plugin із `source: "path"` і відносним до робочого простору -`sourcePath`, коли це можливо. Абсолютний робочий шлях завантаження залишається в -`plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів файлової системи -робочої станції в довготривалій конфігурації. Це зберігає локальні встановлення для розробки видимими для -діагностики площини джерела без додавання другої сирої поверхні розкриття шляхів -файлової системи. Постійний індекс plugin `plugins/installs.json` є джерелом істини для встановлення -і може бути оновлений без завантаження модулів середовища виконання plugin. -Його мапа `installRecords` є довговічною навіть коли маніфест plugin відсутній або -недійсний; його масив `plugins` є перебудовуваним представленням маніфесту/кешу. +Офіційні зовнішні записи npm повинні надавати перевагу точному `npmSpec` плюс +`expectedIntegrity`. Прості імена пакетів і dist-tag усе ще працюють для +сумісності, але вони показують попередження на площині джерел, щоб каталог міг рухатися +до pinned-установлень із перевіркою цілісності без порушення роботи наявних plugins. +Коли онбординг встановлює з локального шляху каталогу, він записує керований запис +plugin у plugin-індекс із `source: "path"` і `sourcePath`, відносним до workspace, +коли це можливо. Абсолютний робочий шлях завантаження залишається в +`plugins.load.paths`; запис установлення уникає дублювання локальних шляхів робочої станції +в довгоживучій конфігурації. Це зберігає видимість локальних установлень для розробки в діагностиці площини джерел без додавання другої сирої поверхні розкриття шляхів файлової системи. +Збережений plugin-індекс `plugins/installs.json` є джерелом істини для джерел установлення, і його можна оновлювати без завантаження модулів середовища виконання plugin. +Його карта `installRecords` є довговічною, навіть коли маніфест plugin відсутній або +недійсний; його масив `plugins` — це відтворюване подання маніфесту/кешу. -## Plugin рушія контексту +## Plugins рушія контексту -Plugin рушія контексту володіють оркестрацією контексту сесії для ingest, assembly -і Compaction. Реєструйте їх зі свого plugin через +Plugins рушія контексту володіють оркестрацією контексту сесії для поглинання, збирання +та Compaction. Реєструйте їх зі свого plugin за допомогою `api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через `plugins.slots.contextEngine`. -Використовуйте це, коли вашому plugin потрібно замінити або розширити типовий -конвеєр контексту, а не просто додати пошук у пам’яті або хуки. +Використовуйте це, коли вашому plugin потрібно замінити або розширити типовий конвеєр +контексту, а не просто додати пошук у пам’яті або хуки. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -977,7 +978,7 @@ export default function (api) { } ``` -Якщо ваш рушій **не** володіє алгоритмом Compaction, залиште `compact()` +Якщо ваш рушій **не** володіє алгоритмом Compaction, залишайте `compact()` реалізованим і явно делегуйте його: ```ts @@ -1015,45 +1016,45 @@ export default function (api) { ## Додавання нової можливості -Коли plugin потребує поведінки, яка не вкладається в поточний API, не обходьте -систему plugin приватним глибоким доступом. Додайте відсутню можливість. +Коли plugin потребує поведінки, яка не вписується в поточний API, не обходьте +систему plugin через приватне внутрішнє звернення. Додайте відсутню можливість. Рекомендована послідовність: -1. визначте контракт core - Вирішіть, якою спільною поведінкою має володіти core: policy, fallback, злиття config, - lifecycle, семантика, видима для каналу, і форма допоміжного засобу середовища виконання. -2. додайте типізовані поверхні реєстрації plugin/середовища виконання +1. визначте контракт ядра + Вирішіть, якою спільною поведінкою має володіти ядро: політика, резервний механізм, злиття конфігурації, + життєвий цикл, семантика для каналу та форма допоміжного засобу середовища виконання. +2. додайте типізовані поверхні реєстрації/runtime plugin Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною типізованою поверхнею можливості. -3. підключіть core + споживачів каналів/функцій - Канали й plugin функцій мають споживати нову можливість через core, +3. підключіть ядро + споживачів каналу/можливості + Канали та plugins можливостей повинні споживати нову можливість через ядро, а не імпортувати реалізацію вендора напряму. -4. зареєструйте реалізації вендора - Потім plugin вендора реєструють свої бекенди для цієї можливості. +4. зареєструйте реалізації вендорів + Потім plugins вендорів реєструють свої бекенди для цієї можливості. 5. додайте покриття контракту - Додайте тести, щоб володіння і форма реєстрації з часом залишалися явними. + Додайте тести, щоб з часом володіння та форма реєстрації залишалися явними. -Саме так OpenClaw залишається системою з чіткою позицією, не стаючи жорстко прив’язаною до -світогляду одного провайдера. Див. [Кулінарна книга можливостей](/uk/plugins/architecture), -щоб побачити конкретний перелік файлів і готовий приклад. +Саме так OpenClaw зберігає чітку позицію, не стаючи при цьому жорстко прив’язаним до +світогляду одного провайдера. Див. [Capability Cookbook](/uk/plugins/architecture), +щоб отримати конкретний контрольний список файлів і робочий приклад. ### Контрольний список можливості -Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих -поверхонь разом: +Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися таких +поверхонь: -- типів контракту core у `src//types.ts` -- раннера/допоміжного засобу середовища виконання core у `src//runtime.ts` -- поверхні реєстрації API plugin у `src/plugins/types.ts` +- типи контракту ядра в `src//types.ts` +- runner/допоміжний засіб середовища виконання ядра в `src//runtime.ts` +- поверхня реєстрації API plugin у `src/plugins/types.ts` - підключення реєстру plugin у `src/plugins/registry.ts` -- експонування середовища виконання plugin у `src/plugins/runtime/*`, коли plugin функцій/каналів - мають це споживати -- допоміжних засобів capture/test у `src/test-utils/plugin-registration.ts` -- перевірок володіння/контракту в `src/plugins/contracts/registry.ts` -- документації для операторів/plugin у `docs/` +- відкриття середовища виконання plugin у `src/plugins/runtime/*`, коли plugins можливостей/каналів + мають її споживати +- допоміжні засоби capture/test у `src/test-utils/plugin-registration.ts` +- перевірки володіння/контракту в `src/plugins/contracts/registry.ts` +- документація для операторів/plugin у `docs/` -Якщо однієї з цих поверхонь бракує, це зазвичай означає, що можливість +Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість ще не повністю інтегрована. ### Шаблон можливості @@ -1061,7 +1062,7 @@ export default function (api) { Мінімальний шаблон: ```ts -// контракт core +// контракт ядра export type VideoGenerationProviderPlugin = { id: string; label: string; @@ -1077,7 +1078,7 @@ api.registerVideoGenerationProvider({ }, }); -// спільний допоміжний засіб середовища виконання для plugin функцій/каналів +// спільний допоміжний засіб середовища виконання для plugins можливостей/каналів const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, @@ -1092,9 +1093,9 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Це зберігає правило простим: -- core володіє контрактом можливості + оркестрацією -- plugin вендора володіють реалізаціями вендора -- plugin функцій/каналів споживають допоміжні засоби середовища виконання +- ядро володіє контрактом можливості + оркестрацією +- plugins вендорів володіють реалізаціями вендорів +- plugins можливостей/каналів споживають допоміжні засоби середовища виконання - тести контракту зберігають явність володіння ## Пов’язане @@ -1102,4 +1103,4 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); - [Архітектура Plugin](/uk/plugins/architecture) — публічна модель можливостей і форми - [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths) - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення plugin](/uk/plugins/building-plugins) +- [Створення plugins](/uk/plugins/building-plugins) diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 5efeed746..75baea839 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,64 +1,64 @@ --- read_when: - - Ви створюєте Plugin для OpenClaw - - Вам потрібно надати схему конфігурації plugin або налагодити помилки перевірки plugin -summary: Вимоги до маніфесту Plugin + схеми JSON (сувора перевірка конфігурації) + - Ви створюєте плагін OpenClaw + - Вам потрібно постачати схему конфігурації плагіна або налагоджувати помилки валідації плагіна +summary: Вимоги до маніфесту Plugin + схеми JSON (сувора валідація конфігурації) title: маніфест Plugin x-i18n: - generated_at: "2026-04-27T19:39:02Z" + generated_at: "2026-04-28T01:41:58Z" model: gpt-5.4 provider: openai - source_hash: 4a700ecd97b16735e415814731841c686490f12d0e303c09800afe664880ec3e + source_hash: f19c39220215b72341b89540ee952642c3387effb8f32cbc5a623571e4f9afd1 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 +- Пакет Codex: `.codex-plugin/plugin.json` +- Пакет Claude: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude без маніфесту -- пакет Cursor: `.cursor-plugin/plugin.json` +- Пакет Cursor: `.cursor-plugin/plugin.json` -OpenClaw також автоматично визначає ці макети пакетів, але вони не проходять перевірку +OpenClaw також автоматично визначає ці компонування пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі зчитує метадані пакета разом з оголошеними -коренями Skills, коренями команд Claude, типовими значеннями `settings.json` у пакетах Claude, -типовими значеннями LSP у пакетах Claude та підтримуваними наборами хуків, коли макет відповідає -очікуванням середовища виконання OpenClaw. +Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені +кореневі каталоги Skills, кореневі каталоги команд 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). -Про власну модель можливостей і поточні рекомендації щодо зовнішньої сумісності: +Повний посібник із системи Plugin дивіться тут: [Plugins](/uk/tools/plugin). +Про рідну модель можливостей і актуальні вказівки щодо зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду -вашого plugin**. Усе нижче має бути достатньо легким для перевірки без запуску -середовища виконання plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду вашого +Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску рантайму +Plugin. **Використовуйте його для:** -- ідентифікації plugin, перевірки конфігурації та підказок для UI конфігурації -- метаданих автентифікації, онбордингу й налаштування (псевдонім, автоувімкнення, змінні середовища provider, варіанти автентифікації) +- ідентичності Plugin, валідації конфігурації та підказок UI для конфігурації +- метаданих автентифікації, онбордингу й налаштування (аліас, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) - підказок активації для поверхонь control-plane -- скороченого визначення належності до сімейства моделей -- статичних знімків належності можливостей (`contracts`) -- метаданих QA runner, які може перевіряти спільний хост `openclaw qa` -- метаданих конфігурації, специфічних для channel, що об’єднуються в каталог і поверхні перевірки +- скороченого володіння сімейством моделей +- статичних знімків володіння можливостями (`contracts`) +- метаданих запуску QA, які може перевіряти спільний хост `openclaw qa` +- метаданих конфігурації, специфічних для каналу, об’єднаних у каталог і поверхні валідації -**Не використовуйте його для:** реєстрації поведінки під час виконання, оголошення -точок входу коду або метаданих встановлення npm. Вони належать вашому коду plugin і `package.json`. +**Не використовуйте його для:** реєстрації поведінки рантайму, оголошення +точок входу коду або метаданих встановлення npm. Для цього призначені код вашого Plugin і `package.json`. ## Мінімальний приклад @@ -121,19 +121,19 @@ OpenClaw також автоматично визначає ці макети п "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", - "choiceLabel": "Ключ API OpenRouter", + "choiceLabel": "OpenRouter API key", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", - "cliDescription": "Ключ API OpenRouter", + "cliDescription": "OpenRouter API key", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { - "label": "Ключ API", + "label": "API key", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -154,73 +154,72 @@ OpenClaw також автоматично визначає ці макети п | Поле | Обов’язкове | Тип | Що воно означає | | ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний ідентифікатор plugin. Саме цей ідентифікатор використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована схема JSON для конфігурації цього plugin. | -| `enabledByDefault` | Ні | `true` | Позначає пакетний plugin як увімкнений типово. Опустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб plugin за замовчуванням залишався вимкненим. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори provider, які мають автоматично вмикати цей plugin, коли згадуються автентифікація, конфігурація або посилання на моделі. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип plugin, який використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Ідентифікатори channel, що належать цьому plugin. Використовуються для виявлення та перевірки конфігурації. | -| `providers` | Ні | `string[]` | Ідентифікатори provider, що належать цьому plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Шлях до полегшеного модуля виявлення provider, відносно кореня plugin, для метаданих каталогу provider в межах маніфесту, які можна завантажити без активації повного середовища виконання plugin. | -| `modelSupport` | Ні | `object` | Короткі метадані сімейства моделей, що належать маніфесту та використовуються для автоматичного завантаження plugin до запуску середовища виконання. | -| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для provider, що належать цьому plugin. Це контракт control-plane для майбутнього доступного лише для читання переліку, онбордингу, вибору моделей, псевдонімів і придушення без завантаження середовища виконання plugin. | -| `modelPricing` | Ні | `object` | Політика зовнішнього пошуку цін, що належить provider. Використовуйте її, щоб виключати локальні/self-hosted provider з віддалених каталогів цін або зіставляти посилання provider з ідентифікаторами каталогів OpenRouter/LiteLLM без жорсткого кодування ідентифікаторів provider у ядрі. | -| `modelIdNormalization` | Ні | `object` | Очищення псевдонімів/префіксів ідентифікаторів моделей, що належить provider і має виконуватися до завантаження середовища виконання provider. | -| `providerEndpoints` | Ні | `object[]` | Метадані хоста/baseUrl кінцевих точок, що належать маніфесту, для маршрутів provider, які ядро має класифікувати до завантаження середовища виконання provider. | -| `providerRequest` | Ні | `object` | Легкі метадані сімейства provider і сумісності запитів, що використовуються загальною політикою запитів до завантаження середовища виконання provider. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI inference, що належать цьому plugin. Використовуються для автоактивації під час запуску на основі явних посилань у конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на provider або backend CLI, для яких слід перевіряти власний synthetic auth hook plugin під час холодного виявлення моделей до завантаження середовища виконання. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі ключів API, що належать пакетному plugin і представляють несекретний локальний стан, стан OAuth або ambient credential state. | -| `commandAliases` | Ні | `object[]` | Назви команд, що належать цьому plugin і мають створювати діагностику конфігурації та CLI з урахуванням plugin до завантаження середовища виконання. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/статусу provider. Для нових plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це протягом вікна зворотної сумісності. | -| `providerAuthAliases` | Ні | `Record` | Ідентифікатори provider, які мають повторно використовувати інший ідентифікатор provider для пошуку автентифікації, наприклад provider для кодування, який ділить ключ API базового provider і профілі автентифікації. | -| `channelEnvVars` | Ні | `Record` | Легкі метадані env для channel, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для налаштування channel через env або поверхонь автентифікації, які мають бачити загальні помічники запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для вибору під час онбордингу, визначення пріоритетного provider і простого зв’язування з прапорцями CLI. | -| `activation` | Ні | `object` | Легкі метадані планувальника активації для завантаження, що ініціюється provider, командою, channel, маршрутом і можливістю. Лише метадані; фактична поведінка, як і раніше, належить середовищу виконання plugin. | -| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання plugin. | -| `qaRunners` | Ні | `object[]` | Легкі дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження середовища виконання plugin. | -| `contracts` | Ні | `object` | Статичний знімок пакетних можливостей для зовнішніх auth hook, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і належності інструментів. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легкі типові значення media-understanding для ідентифікаторів provider, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації channel, що належать маніфесту та об’єднуються в поверхні виявлення і перевірки до завантаження середовища виконання. | -| `skills` | Ні | `string[]` | Каталоги Skill для завантаження, відносно кореня plugin. | -| `name` | Ні | `string` | Людинозрозуміла назва plugin. | -| `description` | Ні | `string` | Короткий опис, що показується в поверхнях plugin. | -| `version` | Ні | `string` | Інформаційна версія plugin. | -| `uiHints` | Ні | `Record` | Підписи UI, placeholder-и та підказки щодо чутливості для полів конфігурації. | +| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Саме цей ідентифікатор використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Щоб залишити Plugin вимкненим за замовчуванням, не вказуйте це поле або встановіть будь-яке значення, відмінне від `true`. | +| `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 до рантайму. | +| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт control-plane для майбутнього read-only переліку, онбордингу, засобів вибору моделей, аліасів і придушення без завантаження рантайму Plugin. | +| `modelPricing` | Ні | `object` | Політика зовнішнього пошуку цін, якою володіє провайдер. Використовуйте її, щоб виключити локальні/self-hosted провайдери з віддалених каталогів цін або зіставити посилання на провайдерів з ідентифікаторами каталогів OpenRouter/LiteLLM без жорсткого кодування ідентифікаторів провайдерів у ядрі. | +| `modelIdNormalization` | Ні | `object` | Очищення аліасів/префіксів ідентифікаторів моделей, яким володіє провайдер і яке має виконуватися до завантаження рантайму провайдера. | +| `providerEndpoints` | Ні | `object[]` | Метадані хоста/baseUrl кінцевих точок, що належать маніфесту, для маршрутів провайдера, які ядро має класифікувати до завантаження рантайму провайдера. | +| `providerRequest` | Ні | `object` | Легкі метадані сімейства провайдерів і сумісності запитів, які використовуються загальною політикою запитів до завантаження рантайму провайдера. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI inference, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдерів або backend CLI, для яких хук синтетичної автентифікації, що належить Plugin, має перевірятися під час cold discovery моделей до завантаження рантайму. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, якими володіє вбудований Plugin і які представляють не секретний локальний стан, OAuth або ambient credential. | +| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які мають створювати діагностику конфігурації та CLI з урахуванням Plugin до завантаження рантайму. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/стану провайдера. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це під час перехідного періоду депрекейту. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер кодування, який спільно використовує базовий API key провайдера та профілі автентифікації. | +| `channelEnvVars` | Ні | `Record` | Легкі метадані env каналу, які OpenClaw може перевірити без завантаження коду Plugin. Використовуйте це для налаштування каналів через env або поверхонь автентифікації, які мають бачити загальні помічники запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення пріоритетного провайдера та простого підключення прапорців CLI. | +| `activation` | Ні | `object` | Легкі метадані планувальника активації для завантаження, що ініціюється провайдерами, командами, каналами, маршрутами та можливостями. Лише метадані; фактичною поведінкою все одно володіє рантайм Plugin. | +| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження рантайму Plugin. | +| `qaRunners` | Ні | `object[]` | Легкі дескриптори запуску QA, які використовує спільний хост `openclaw qa` до завантаження рантайму Plugin. | +| `contracts` | Ні | `object` | Статичний знімок можливостей вбудованого компонента для зовнішніх хуків автентифікації, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, web search і володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легкі типові значення розуміння медіа для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту і об’єднуються в поверхні виявлення та валідації до завантаження рантайму. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореневого каталогу Plugin. | +| `name` | Ні | `string` | Людинозрозуміла назва Plugin. | +| `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. | +| `version` | Ні | `string` | Інформаційна версія Plugin. | +| `uiHints` | Ні | `Record` | Мітки UI, placeholders і підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. -OpenClaw зчитує це до завантаження середовища виконання provider. -Списки налаштування provider використовують ці варіанти маніфесту, варіанти -налаштування, похідні від дескрипторів, і метадані каталогу встановлення без -завантаження середовища виконання provider. +OpenClaw зчитує це до завантаження рантайму провайдера. +Списки налаштування провайдера використовують ці варіанти з маніфесту, варіанти налаштування, +похідні від дескрипторів, і метадані каталогу встановлення без завантаження рантайму провайдера. -| Поле | Обов’язкове | Тип | Що воно означає | -| -------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------ | -| `provider` | Так | `string` | Ідентифікатор provider, до якого належить цей варіант. | -| `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"]`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| -------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. | +| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід спрямувати. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується в онбордингу та CLI-потоках. | +| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються вище в інтерактивних засобах вибору, керованих асистентом. | +| `assistantVisibility`| Ні | `"visible"` \| `"manual-only"` | Приховує варіант у засобах вибору асистента, але все ще дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds`| Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають переспрямовувати користувачів на цей варіант-заміну. | +| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли plugin володіє назвою команди середовища виконання, яку користувачі можуть -помилково помістити в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw -використовує ці метадані для діагностики без імпорту коду середовища виконання plugin. +Використовуйте `commandAliases`, коли Plugin володіє назвою runtime-команди, яку користувачі можуть +помилково додати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw +використовує ці метадані для діагностики без імпорту коду рантайму Plugin. ```json { @@ -234,37 +233,37 @@ OpenClaw зчитує це до завантаження середовища в } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------ | -| `name` | Так | `string` | Назва команди, що належить цьому plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду 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. +поведінку рантайму, не замінює `register(...)` і не гарантує, що код +Plugin уже було виконано. Планувальник активації використовує ці поля, щоб +звузити набір кандидатів Plugin перед поверненням до наявних метаданих володіння маніфесту, таких як +`providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і хуки. -Надавайте перевагу найвужчим метаданим, які вже описують належність. Використовуйте +Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, -коли ці поля виражають цей зв’язок. Використовуйте `activation` для додаткових підказок планувальнику, -які неможливо подати через ці поля належності. -Використовуйте верхньорівневий `cliBackends` для псевдонімів середовища виконання CLI, таких як `claude-cli`, +коли ці поля виражають відповідний зв’язок. Використовуйте `activation` для додаткових +підказок планувальника, які не можна подати через ці поля володіння. +Використовуйте верхньорівневий `cliBackends` для аліасів runtime CLI, таких як `claude-cli`, `codex-cli` або `google-gemini-cli`; `activation.onAgentHarnesses` призначений лише для -ідентифікаторів вбудованих agent harness, які ще не мають поля належності. +вбудованих ідентифікаторів harness агента, які ще не мають поля володіння. -Цей блок містить лише метадані. Він не реєструє поведінку під час виконання й не -замінює `register(...)`, `setupEntry` або інші точки входу runtime/plugin. -Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням plugin, тож -відсутність метаданих активації зазвичай лише впливає на продуктивність; вона не повинна -змінювати коректність, доки ще існують застарілі fallback-механізми належності в маніфесті. +Цей блок містить лише метадані. Він не реєструє поведінку рантайму та не +замінює `register(...)`, `setupEntry` або інші точки входу runtime/Plugin. +Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому +відсутність метаданих активації зазвичай впливає лише на продуктивність; вона не має +змінювати коректність, доки все ще існують застарілі fallback-варіанти володіння маніфестом. ```json { @@ -279,64 +278,64 @@ plugin уже було виконано. Планувальник активац } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Ідентифікатори provider, які мають включати цей plugin до планів активації/завантаження. | -| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори середовища виконання вбудованих agent harness, які мають включати цей plugin до планів активації/завантаження. Для псевдонімів backend CLI використовуйте верхньорівневий `cliBackends`. | -| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Ідентифікатори channel, які мають включати цей plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей plugin до планів активації/завантаження. | -| `onConfigPaths` | Ні | `string[]` | Відносні до кореня шляхи конфігурації, які мають включати цей plugin до планів запуску/завантаження, коли шлях присутній і не вимкнений явно. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються плануванням активації control-plane. Коли можливо, надавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження. | +| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори runtime вбудованих harness агента, які мають включати цей Plugin до планів активації/завантаження. Для аліасів backend CLI використовуйте верхньорівневий `cliBackends`. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Види маршрутів, які мають включати цей Plugin до планів активації/завантаження. | +| `onConfigPaths` | Ні | `string[]` | Відносні до кореня шляхи конфігурації, які мають включати цей Plugin до планів запуску/завантаження, коли шлях присутній і не вимкнений явно. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються плануванням активації control-plane. За можливості надавайте перевагу вужчим полям. | -Поточні активні споживачі: +Поточні споживачі в продакшені: -- планування CLI, ініційоване командою, повертається до застарілих +- планування CLI, що запускається командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` - планування запуску agent-runtime використовує `activation.onAgentHarnesses` для - вбудованих harness і верхньорівневий `cliBackends[]` для псевдонімів середовища виконання CLI -- планування setup/channel, ініційоване channel, повертається до застарілої - належності `channels[]`, коли явні метадані активації channel відсутні -- планування plugin під час запуску використовує `activation.onConfigPaths` для некaнальних кореневих - поверхонь конфігурації, таких як блок `browser` пакетного browser plugin -- планування setup/runtime, ініційоване provider, повертається до застарілої - належності `providers[]` і верхньорівневого `cliBackends[]`, коли явні метадані активації provider - відсутні + вбудованих harness і верхньорівневий `cliBackends[]` для аліасів runtime CLI +- планування setup/каналу, що запускається каналом, повертається до застарілого володіння `channels[]`, + коли явні метадані активації каналу відсутні +- планування Plugin під час запуску використовує `activation.onConfigPaths` для некональних кореневих + поверхонь конфігурації, таких як блок `browser` у вбудованому Plugin браузера +- планування setup/runtime, що запускається провайдером, повертається до застарілого + володіння `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 runners під +спільним коренем `openclaw qa`. Зберігайте ці метадані легкими та статичними; фактичною +реєстрацією CLI все одно володіє рантайм Plugin через легку поверхню +`runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { "qaRunners": [ { "commandName": "matrix", - "description": "Запускає Docker-backed Matrix live QA lane на одноразовому homeserver" + "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver" } ] } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | -------- | ------------------------------------------------------------------ | -| `commandName` | Так | `string` | Підкоманда, що монтується під `openclaw qa`, наприклад `matrix`. | -| `description` | Ні | `string` | Запасний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | -------- | ------------------------------------------------------------------- | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. | ## Довідник `setup` -Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні легкі метадані, що належать plugin, -до завантаження середовища виконання. +Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні легкі метадані Plugin +до завантаження рантайму. ```json { @@ -355,65 +354,65 @@ plugin уже було виконано. Планувальник активац } ``` -Верхньорівневий `cliBackends` залишається чинним і надалі описує +Верхньорівневий `cliBackends` залишається валідним і надалі описує backend CLI inference. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків control-plane/setup, які мають залишатися лише метаданими. -Коли присутні, `setup.providers` і `setup.cliBackends` є бажаною -поверхнею пошуку setup у стилі descriptor-first. Якщо дескриптор лише -звужує коло кандидатів plugin і setup усе ще потребує багатших runtime hook під час налаштування, +Якщо `setup.providers` і `setup.cliBackends` присутні, вони є бажаною +поверхнею пошуку setup на основі дескрипторів. Якщо дескриптор лише +звужує кандидатний Plugin, а для setup усе ще потрібні багатші runtime-хуки часу налаштування, встановіть `requiresRuntime: true` і залиште `setup-api` як -fallback-шлях виконання. +резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` у загальні пошуки автентифікації provider і -env var. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом -періоду застарівання, але небандловані plugin, які все ще його використовують, -отримують діагностику маніфесту. Нові plugin повинні розміщувати метадані env для setup/статусу -в `setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` до загальних пошуків автентифікації провайдера та +env vars. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності +під час перехідного періоду депрекейту, але небудовані Plugin, які досі його використовують, +отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані env для +setup/status у `setup.providers[].envVars`. OpenClaw також може виводити прості варіанти setup з `setup.providers[].authMethods`, коли запис setup недоступний або коли `setup.requiresRuntime: false` -вказує, що runtime для setup не потрібен. Явні записи `providerAuthChoices` залишаються -бажаними для спеціальних підписів, прапорців CLI, області онбордингу й метаданих асистента. +вказує, що runtime setup не потрібен. Явні записи `providerAuthChoices` і надалі є +бажаними для власних міток, прапорців CLI, області онбордингу та метаданих асистента. -Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для -поверхні setup. OpenClaw трактує явне `false` як контракт лише на рівні дескрипторів +Встановлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для +поверхні setup. OpenClaw трактує явне `false` як контракт лише на дескриптори і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо -plugin лише з дескрипторами все ж постачає один із цих runtime-записів setup, -OpenClaw повідомляє додаткову діагностику й продовжує його ігнорувати. Якщо -`requiresRuntime` пропущено, зберігається застаріла fallback-поведінка, щоб наявні plugin, -які додали дескриптори без цього прапорця, не ламалися. +Plugin, що працює лише на дескрипторах, усе ж постачає один із цих runtime-записів setup, +OpenClaw повідомляє додаткову діагностику й надалі його ігнорує. Якщо +`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` реєструє provider або backend CLI, які не оголошені -в дескрипторах маніфесту, або якщо дескриптор не має відповідної runtime-реєстрації. -Ця діагностика є додатковою й не відхиляє застарілі plugin. +Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про розходження дескрипторів, +якщо `setup-api` реєструє провайдера або backend CLI, які не оголошені +в дескрипторах маніфесту, або якщо для дескриптора немає відповідної runtime-реєстрації. +Ця діагностика є додатковою і не відхиляє застарілі Plugin. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------ | -| `id` | Так | `string` | Ідентифікатор provider, який показується під час setup або онбордингу. Нормалізовані ідентифікатори мають бути глобально унікальними. | -| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей provider підтримує без завантаження повного runtime. | -| `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні setup/статусу можуть перевіряти до завантаження runtime plugin. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------- | +| `id` | Так | `string` | Ідентифікатор провайдера, який показується під час setup або онбордингу. Нормалізовані ідентифікатори мають бути глобально унікальними. | +| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей провайдер підтримує без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження рантайму Plugin. | ### Поля `setup` | Поле | Обов’язкове | Тип | Що воно означає | | ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори setup provider, які показуються під час setup та онбордингу. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend, що використовуються під час setup для пошуку setup у стилі descriptor-first. Нормалізовані ідентифікатори мають бути глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, що належать поверхні setup цього plugin. | +| `providers` | Ні | `object[]` | Дескриптори setup провайдерів, які показуються під час setup та онбордингу. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend часу setup, які використовуються для пошуку setup спочатку за дескрипторами. Нормалізовані ідентифікатори мають бути глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього Plugin. | | `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескрипторами. | ## Довідник `uiHints` -`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для відображення. +`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу. ```json { @@ -430,19 +429,19 @@ OpenClaw повідомляє додаткову діагностику й пр Кожна підказка для поля може містити: -| Поле | Тип | Що воно означає | -| ------------- | ---------- | --------------------------------------- | -| `label` | `string` | Підпис поля для користувача. | -| `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові теги UI. | -| `advanced` | `boolean` | Позначає поле як розширене. | -| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст placeholder для полів форми. | +| Поле | Тип | Що воно означає | +| ------------- | ---------- | ----------------------------------------- | +| `label` | `string` | Мітка поля для користувача. | +| `help` | `string` | Короткий допоміжний текст. | +| `tags` | `string[]` | Необов’язкові теги UI. | +| `advanced` | `boolean` | Позначає поле як розширене. | +| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | +| `placeholder` | `string` | Текст-заповнювач для полів форми. | ## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих належності можливостей, які OpenClaw може -зчитувати без імпорту runtime plugin. +Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може +зчитувати без імпорту рантайму Plugin. ```json { @@ -466,46 +465,46 @@ OpenClaw повідомляє додаткову діагностику й пр Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | ------------------------------------------------------------------------- | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | ---------------------------------------------------------------------- | | `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик розширень app-server Codex, наразі `codex-app-server`. | -| `agentToolResultMiddleware` | `string[]` | Ідентифікатори runtime, для яких пакетний plugin може реєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | Ідентифікатори provider, чиї hooks зовнішнього профілю автентифікації належать цьому plugin. | -| `speechProviders` | `string[]` | Ідентифікатори provider мовлення, що належать цьому plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори provider транскрипції в реальному часі, що належать цьому plugin. | -| `realtimeVoiceProviders` | `string[]` | Ідентифікатори voice provider у реальному часі, що належать цьому plugin. | -| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори provider embedding для пам’яті, що належать цьому plugin. | -| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори provider media-understanding, що належать цьому plugin. | -| `imageGenerationProviders` | `string[]` | Ідентифікатори provider генерації зображень, що належать цьому plugin. | -| `videoGenerationProviders` | `string[]` | Ідентифікатори provider генерації відео, що належать цьому plugin. | -| `webFetchProviders` | `string[]` | Ідентифікатори provider web-fetch, що належать цьому plugin. | -| `webSearchProviders` | `string[]` | Ідентифікатори provider web search, що належать цьому plugin. | -| `migrationProviders` | `string[]` | Ідентифікатори import provider, що належать цьому plugin для `openclaw migrate`. | -| `tools` | `string[]` | Назви агентських інструментів, що належать цьому plugin для перевірок пакетних контрактів. | +| `agentToolResultMiddleware` | `string[]` | Ідентифікатори runtime, для яких вбудований Plugin може реєструвати middleware результатів інструментів. | +| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, чий хук профілю зовнішньої автентифікації належить цьому Plugin. | +| `speechProviders` | `string[]` | Ідентифікатори провайдерів мовлення, якими володіє цей Plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів транскрипції в реальному часі, якими володіє цей Plugin. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів голосу в реальному часі, якими володіє цей Plugin. | +| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів ембедингів пам’яті, якими володіє цей Plugin. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів розуміння медіа, якими володіє цей Plugin. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації зображень, якими володіє цей Plugin. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації відео, якими володіє цей Plugin. | +| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей Plugin. | +| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, якими володіє цей Plugin. | +| `migrationProviders` | `string[]` | Ідентифікатори провайдерів імпорту, якими володіє цей Plugin для `openclaw migrate`. | +| `tools` | `string[]` | Назви інструментів агента, якими володіє цей Plugin, для перевірок контрактів вбудованих компонентів. | -`contracts.embeddedExtensionFactories` збережено для пакетних фабрик розширень -лише для app-server Codex. Пакетні трансформації результатів інструментів повинні +`contracts.embeddedExtensionFactories` збережено для фабрик розширень +лише для вбудованого app-server Codex. Вбудовані трансформації результатів інструментів мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися через -`api.registerAgentToolResultMiddleware(...)`. Зовнішні plugin не можуть -реєструвати middleware результатів інструментів, оскільки цей seam може переписувати -високодовірений вивід інструмента до того, як модель його побачить. +`api.registerAgentToolResultMiddleware(...)`. Зовнішні Plugin не можуть +реєструвати middleware результатів інструментів, оскільки цей стик може переписувати вивід +інструментів високої довіри до того, як його побачить модель. -Plugin provider, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати +Plugin провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють -через застарілий fallback-механізм сумісності, але він повільніший і -буде видалений після вікна міграції. +через застарілий fallback сумісності, але він повільніший і +буде видалений після завершення міграційного вікна. -Пакетні provider embedding для пам’яті повинні оголошувати +Вбудовані провайдери ембедингів пам’яті мають оголошувати `contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони надають, включно з вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей контракт маніфесту, -щоб завантажувати лише plugin-власник до того, як повний runtime Gateway зареєструє -provider. +щоб завантажувати лише Plugin-власник до того, як повний рантайм Gateway зареєструє +провайдерів. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли provider media-understanding має -типові моделі, пріоритет fallback-автентифікації або вбудовану підтримку документів, які -потрібні загальним допоміжним засобам ядра до завантаження runtime. Ключі також мають бути оголошені в +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має +типові моделі, пріоритет fallback автоматичної автентифікації або нативну підтримку документів, які +загальним допоміжним засобам ядра потрібні до завантаження рантайму. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json @@ -529,43 +528,43 @@ provider. } ``` -Кожен запис provider може містити: +Кожен запис провайдера може містити: -| Поле | Тип | Що воно означає | -| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей provider. | -| `defaultModels` | `Record` | Типові значення модель-для-можливості, що використовуються, коли конфігурація не вказує модель. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback provider на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Вбудовані входи документів, які підтримує provider. | +| Поле | Тип | Що воно означає | +| ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | +| `defaultModels` | `Record` | Типові значення відповідності можливість-модель, які використовуються, коли в конфігурації не вказано модель. | +| `autoPriority` | `Record` | Менші числа сортуються вище для автоматичного fallback провайдера на основі облікових даних. | +| `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує провайдер. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли channel plugin потребує легких метаданих конфігурації до -завантаження runtime. Виявлення налаштування/статусу channel лише для читання може використовувати ці метадані -безпосередньо для налаштованих зовнішніх channel, коли запис setup недоступний або +Використовуйте `channelConfigs`, коли Plugin каналу потребує легких метаданих конфігурації до +завантаження рантайму. Read-only виявлення setup/status каналу може використовувати ці метадані +безпосередньо для налаштованих зовнішніх каналів, коли запис setup недоступний, або коли `setup.requiresRuntime: false` вказує, що runtime setup не потрібен. -`channelConfigs` — це метадані маніфесту plugin, а не новий користувацький розділ -конфігурації верхнього рівня. Користувачі, як і раніше, налаштовують екземпляри channel у `channels.`. -OpenClaw зчитує метадані маніфесту, щоб визначити, якому plugin належить цей налаштований -channel, до виконання коду runtime plugin. +`channelConfigs` — це метадані маніфесту Plugin, а не новий верхньорівневий розділ +конфігурації користувача. Користувачі, як і раніше, налаштовують екземпляри каналів у `channels.`. +OpenClaw зчитує метадані маніфесту, щоб визначити, який Plugin володіє цим налаштованим +каналом, до виконання коду рантайму Plugin. -Для channel plugin `configSchema` і `channelConfigs` описують різні +Для Plugin каналу `configSchema` і `channelConfigs` описують різні шляхи: -- `configSchema` перевіряє `plugins.entries..config` -- `channelConfigs..schema` перевіряє `channels.` +- `configSchema` валідує `plugins.entries..config` +- `channelConfigs..schema` валідує `channels.` -Небандловані plugin, які оголошують `channels[]`, також повинні оголошувати відповідні -записи `channelConfigs`. Без них OpenClaw усе ще може завантажити plugin, але поверхні -схеми конфігурації холодного шляху, setup і Control UI не знатимуть форми параметрів, -що належать channel, доки не виконається runtime plugin. +Небудовані Plugin, які оголошують `channels[]`, також мають оголошувати відповідні +записи `channelConfigs`. Без них OpenClaw все ще може завантажити Plugin, але поверхні +схеми конфігурації cold-path, setup і Control UI не можуть знати форму параметрів, +які належать каналу, доки не виконається рантайм Plugin. `channelConfigs..commands.nativeCommandsAutoEnabled` і `nativeSkillsAutoEnabled` можуть оголошувати статичні типові значення `auto` для перевірок конфігурації команд, -які виконуються до завантаження runtime channel. Пакетні channel також можуть публікувати -ті самі типові значення через `package.json#openclaw.channel.commands` поряд з іншими -метаданими каталогу channel, що належать пакету. +які виконуються до завантаження рантайму каналу. Вбудовані канали також можуть публікувати +ті самі типові значення через `package.json#openclaw.channel.commands` разом з іншими +метаданими каталогу каналу, що належать пакету. ```json { @@ -580,12 +579,12 @@ channel, до виконання коду runtime plugin. }, "uiHints": { "homeserverUrl": { - "label": "URL homeserver", + "label": "Homeserver URL", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Підключення до homeserver Matrix", + "description": "Matrix homeserver connection", "commands": { "nativeCommandsAutoEnabled": true, "nativeSkillsAutoEnabled": true @@ -596,23 +595,23 @@ channel, до виконання коду runtime plugin. } ``` -Кожен запис channel може містити: +Кожен запис каналу може містити: -| Поле | Тип | Що воно означає | -| ------------ | ------------------------ | ---------------------------------------------------------------------------------------- | -| `schema` | `object` | Схема JSON для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації channel. | -| `uiHints` | `Record` | Необов’язкові підписи UI/placeholder-и/підказки чутливості для цього розділу конфігурації channel. | -| `label` | `string` | Підпис channel, який об’єднується в поверхні вибору та інспектування, коли runtime-метадані ще не готові. | -| `description`| `string` | Короткий опис channel для поверхонь інспектування та каталогу. | -| `commands` | `object` | Статичні авто-типові значення native command і native Skill для перевірок конфігурації до запуску runtime. | -| `preferOver` | `string[]` | Ідентифікатори застарілих або нижчопріоритетних plugin, які цей channel має випереджати в поверхнях вибору. | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | -------------------------------------------------------------------------------------- | +| `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації каналу. | +| `uiHints` | `Record` | Необов’язкові мітки UI/placeholders/підказки чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Мітка каналу, яка об’єднується з поверхнями вибору та перегляду, коли метадані рантайму ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь перегляду та каталогу. | +| `commands` | `object` | Статичні auto-типові значення native command і native skill для перевірок конфігурації до рантайму. | +| `preferOver` | `string[]` | Застарілі або менш пріоритетні ідентифікатори Plugin, які цей канал має випереджати на поверхнях вибору. | -### Заміна іншого channel plugin +### Заміна іншого Plugin каналу -Використовуйте `preferOver`, коли ваш plugin є бажаним власником для ідентифікатора channel, який -також може надавати інший plugin. Типові випадки — перейменований ідентифікатор plugin, -окремий plugin, що замінює пакетний plugin, або підтримуваний fork, який -зберігає той самий ідентифікатор channel для сумісності конфігурації. +Використовуйте `preferOver`, коли ваш Plugin є бажаним власником ідентифікатора каналу, який +також може надавати інший Plugin. Типові випадки: перейменований ідентифікатор Plugin, окремий +Plugin, який замінює вбудований Plugin, або підтримуваний fork, який зберігає той самий +ідентифікатор каналу для сумісності конфігурації. ```json { @@ -633,22 +632,21 @@ channel, до виконання коду runtime plugin. } ``` -Коли налаштовано `channels.chat`, OpenClaw враховує і ідентифікатор channel, і -ідентифікатор бажаного plugin. Якщо plugin нижчого пріоритету було вибрано лише тому, -що він є пакетним або увімкнений типово, OpenClaw вимикає його в ефективній -runtime-конфігурації, щоб один plugin володів channel та його інструментами. Явний -вибір користувача все одно має перевагу: якщо користувач явно вмикає обидва plugin, OpenClaw -зберігає цей вибір і повідомляє діагностику дубльованих channel/інструментів замість -тихого змінення запитаного набору plugin. +Коли налаштовано `channels.chat`, OpenClaw враховує і ідентифікатор каналу, і +бажаний ідентифікатор Plugin. Якщо менш пріоритетний Plugin було вибрано лише тому, +що він вбудований або увімкнений за замовчуванням, OpenClaw вимикає його в ефективній +конфігурації рантайму, щоб один Plugin володів каналом і його інструментами. Явний вибір користувача +все одно має перевагу: якщо користувач явно вмикає обидва Plugin, OpenClaw +зберігає цей вибір і повідомляє діагностику дубльованого каналу/інструменту, а не +тихо змінює запитаний набір Plugin. -Тримайте `preferOver` обмеженим ідентифікаторами plugin, які справді можуть надавати той самий channel. -Це не загальне поле пріоритету, і воно не перейменовує ключі користувацької конфігурації. +Обмежуйте `preferOver` ідентифікаторами Plugin, які справді можуть надавати той самий канал. +Це не загальне поле пріоритету і воно не перейменовує ключі конфігурації користувача. ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має виводити ваш provider plugin з -скорочених ідентифікаторів моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження runtime -plugin. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера з +скорочених ідентифікаторів моделей, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження рантайму Plugin. ```json { @@ -661,25 +659,25 @@ plugin. OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers` власника -- `modelPatterns` мають перевагу над `modelPrefixes` -- якщо збігаються і небандлований plugin, і пакетний plugin, перемагає небандлований - plugin -- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкаже provider +- явні посилання `provider/model` використовують метадані маніфесту `providers`, якими володіє Plugin +- `modelPatterns` мають пріоритет над `modelPrefixes` +- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований + Plugin +- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть провайдера Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | ---------------------------------------------------------------------------- | +| Поле | Тип | Що воно означає | +| --------------- | ---------- | -------------------------------------------------------------------------------- | | `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | | `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | ## Довідник `modelCatalog` -Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей provider до -завантаження runtime plugin. Це джерело на рівні маніфесту для фіксованих -рядків каталогу, псевдонімів provider, правил придушення та режиму виявлення. Оновлення runtime -і далі належить коду runtime provider, але маніфест повідомляє ядру, коли runtime +Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до +завантаження рантайму Plugin. Це джерело, яким володіє маніфест, для фіксованих +рядків каталогу, аліасів провайдерів, правил придушення та режиму виявлення. Оновлення в runtime +і далі належить коду рантайму провайдера, але маніфест повідомляє ядру, коли рантайм потрібен. ```json @@ -719,7 +717,7 @@ OpenClaw застосовує такий пріоритет: { "provider": "azure-openai-responses", "model": "gpt-5.3-codex-spark", - "reason": "недоступно в Azure OpenAI Responses" + "reason": "not available on Azure OpenAI Responses" } ], "discovery": { @@ -731,65 +729,74 @@ OpenClaw застосовує такий пріоритет: Поля верхнього рівня: -| Поле | Тип | Що воно означає | -| -------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | Рядки каталогу для ідентифікаторів provider, що належать цьому plugin. Ключі також мають бути присутні у верхньорівневому `providers`. | -| `aliases` | `Record` | Псевдоніми provider, які мають зіставлятися з provider-власником для планування каталогу або придушення. | -| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей plugin пригнічує з причини, специфічної для provider. | -| `discovery` | `Record` | Чи можна читати каталог provider з метаданих маніфесту, оновлювати в кеш або чи він потребує runtime. | +| Поле | Тип | Що воно означає | +| -------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `providers` | `Record` | Рядки каталогу для ідентифікаторів провайдерів, якими володіє цей Plugin. Ключі також мають бути вказані у верхньорівневому `providers`. | +| `aliases` | `Record` | Аліаси провайдерів, які мають резолвитися до провайдера-власника для планування каталогу або придушення. | +| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin придушує з причини, специфічної для провайдера. | +| `discovery` | `Record` | Чи можна читати каталог провайдера з метаданих маніфесту, оновлювати в кеш або чи він потребує runtime. | -`aliases` бере участь у пошуку належності provider для планування model catalog. -Цілі псевдонімів мають бути верхньорівневими provider, що належать тому самому plugin. Коли -відфільтрований за provider список використовує псевдонім, OpenClaw може прочитати маніфест власника і -застосувати перевизначення API/base URL псевдоніма без завантаження runtime provider. +`aliases` бере участь у пошуку володіння провайдером для планування model-catalog. +Цілі аліасів мають бути верхньорівневими провайдерами, якими володіє той самий Plugin. Коли +список, відфільтрований за провайдером, використовує аліас, OpenClaw може прочитати маніфест-власник і +застосувати перевизначення API/base URL аліаса без завантаження рантайму провайдера. -`suppressions` є бажаною статичною заміною для runtime hook -`suppressBuiltInModel` provider. Записи придушення враховуються лише тоді, коли -provider належить plugin або оголошений як ключ `modelCatalog.aliases`, що -вказує на provider-власник. Runtime hooks придушення все ще виконуються як застарілий -fallback-механізм сумісності для plugin, які ще не мігрували. +`suppressions` замінює старий хук runtime провайдера `suppressBuiltInModel`. +Записи придушення враховуються лише тоді, коли провайдер належить Plugin або +оголошений як ключ `modelCatalog.aliases`, який вказує на провайдера-власника. Runtime-хуки +придушення більше не викликаються під час резолвингу моделей. -Поля provider: +Поля провайдера: -| Поле | Тип | Що воно означає | -| --------- | ------------------------ | ------------------------------------------------------------------- | -| `baseUrl` | `string` | Необов’язковий типовий base URL для моделей у каталозі цього provider. | -| `api` | `ModelApi` | Необов’язковий типовий адаптер API для моделей у каталозі цього provider. | -| `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до каталогу цього provider. | -| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | +| Поле | Тип | Що воно означає | +| --------- | ------------------------ | ------------------------------------------------------------------ | +| `baseUrl` | `string` | Необов’язковий типовий base URL для моделей у цьому каталозі провайдера. | +| `api` | `ModelApi` | Необов’язковий типовий адаптер API для моделей у цьому каталозі провайдера. | +| `headers` | `Record` | Необов’язкові статичні заголовки, які застосовуються до цього каталогу провайдера. | +| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | Поля моделі: | Поле | Тип | Що воно означає | | --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| `id` | `string` | Локальний для provider ідентифікатор моделі, без префікса `provider/`. | +| `id` | `string` | Локальний для провайдера ідентифікатор моделі без префікса `provider/`. | | `name` | `string` | Необов’язкова відображувана назва. | -| `api` | `ModelApi` | Необов’язкове перевизначення API на рівні моделі. | -| `baseUrl` | `string` | Необов’язкове перевизначення base URL на рівні моделі. | -| `headers` | `Record` | Необов’язкові статичні заголовки на рівні моделі. | +| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | +| `baseUrl` | `string` | Необов’язкове перевизначення base URL для окремої моделі. | +| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | | `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | | `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | -| `contextWindow` | `number` | Рідне вікно контексту provider. | -| `contextTokens` | `number` | Необов’язкове ефективне runtime-обмеження контексту, якщо воно відрізняється від `contextWindow`. | +| `contextWindow` | `number` | Нативне context window провайдера. | +| `contextTokens` | `number` | Необов’язкова ефективна runtime-межа контексту, якщо вона відрізняється від `contextWindow`. | | `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | -| `cost` | `object` | Необов’язкове ціноутворення в USD за мільйон токенів, включно з необов’язковим `tieredPricing`. | +| `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, включно з необов’язковим `tieredPricing`. | | `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделей OpenClaw. | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Пригнічуйте лише тоді, коли рядок узагалі не повинен з’являтися. | -| `statusReason` | `string` | Необов’язкова причина, що показується разом зі статусом недоступності. | -| `replaces` | `string[]` | Старіші локальні для provider ідентифікатори моделей, які ця модель замінює. | -| `replacedBy` | `string` | Локальний для provider ідентифікатор моделі-замінника для застарілих рядків. | -| `tags` | `string[]` | Стабільні теги, що використовуються засобами вибору та фільтрами. | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Використовуйте придушення лише тоді, коли рядок взагалі не має з’являтися. | +| `statusReason` | `string` | Необов’язкова причина, що показується для недоступного статусу. | +| `replaces` | `string[]` | Старіші локальні для провайдера ідентифікатори моделей, які ця модель замінює. | +| `replacedBy` | `string` | Ідентифікатор локальної для провайдера моделі-заміни для застарілих рядків. | +| `tags` | `string[]` | Стабільні теги, які використовуються засобами вибору та фільтрами. | -Не розміщуйте в `modelCatalog` дані, доступні лише під час runtime. Якщо provider потребує стану -облікового запису, API-запиту або виявлення локального процесу, щоб знати повний набір моделей, -оголосіть цей provider як `refreshable` або `runtime` у `discovery`. +Поля придушення: + +| Поле | Тип | Що воно означає | +| -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | Ідентифікатор провайдера для upstream-рядка, який треба придушити. Має належати цьому Plugin або бути оголошеним як аліас-власник. | +| `model` | `string` | Локальний для провайдера ідентифікатор моделі, яку треба придушити. | +| `reason` | `string` | Необов’язкове повідомлення, яке показується, коли придушений рядок запитується напряму. | +| `when.baseUrlHosts` | `string[]` | Необов’язковий список хостів ефективного base URL провайдера, які мають збігтися, перш ніж придушення буде застосовано. | +| `when.providerConfigApiIn` | `string[]` | Необов’язковий список точних значень `api` конфігурації провайдера, які мають збігтися, перш ніж придушення буде застосовано. | + +Не розміщуйте в `modelCatalog` дані, які існують лише в runtime. Якщо провайдеру потрібен стан +облікового запису, API-запит або виявлення локального процесу, щоб визначити повний набір моделей, +оголосіть цього провайдера як `refreshable` або `runtime` у `discovery`. ## Довідник `modelIdNormalization` -Використовуйте `modelIdNormalization` для легкого очищення ідентифікаторів моделей, що належить provider і має -відбуватися до завантаження runtime provider. Це дозволяє тримати псевдоніми на кшталт коротких назв моделей, -застарілих локальних ідентифікаторів provider і правил префіксів proxy у маніфесті -plugin-власника, а не в таблицях вибору моделей ядра. +Використовуйте `modelIdNormalization` для легкого очищення ідентифікаторів моделей, яким володіє провайдер і яке має +відбуватися до завантаження рантайму провайдера. Це дозволяє зберігати аліаси, такі як короткі назви +моделей, застарілі локальні ідентифікатори провайдера та правила префіксів проксі, у маніфесті +Plugin-власника, а не в таблицях вибору моделей ядра. ```json { @@ -809,37 +816,37 @@ plugin-власника, а не в таблицях вибору моделей } ``` -Поля provider: +Поля провайдера: -| Поле | Тип | Що воно означає | -| ------------------------------------ | ----------------------- | ------------------------------------------------------------------------------------------ | -| `aliases` | `Record` | Точні псевдоніми ідентифікаторів моделей без урахування регістру. Значення повертаються як записані. | -| `stripPrefixes` | `string[]` | Префікси, які слід видаляти перед пошуком псевдоніма; корисно для застарілого дублювання provider/model. | -| `prefixWhenBare` | `string` | Префікс, який додається, коли нормалізований ідентифікатор моделі ще не містить `/`. | -| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префікса для bare id після пошуку псевдоніма, з ключами `modelPrefix` і `prefix`. | +| Поле | Тип | Що воно означає | +| ------------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------- | +| `aliases` | `Record` | Точні аліаси ідентифікаторів моделей без урахування регістру. Значення повертаються в тому вигляді, як записані. | +| `stripPrefixes` | `string[]` | Префікси, які слід видалити перед пошуком аліаса; корисно для застарілого дублювання provider/model. | +| `prefixWhenBare` | `string` | Префікс, який додається, коли нормалізований ідентифікатор моделі ще не містить `/`. | +| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префіксів для bare-id після пошуку аліаса з ключами `modelPrefix` і `prefix`. | ## Довідник `providerEndpoints` Використовуйте `providerEndpoints` для класифікації кінцевих точок, яку загальна політика запитів -має знати до завантаження runtime provider. Ядро, як і раніше, визначає значення кожного -`endpointClass`; маніфести plugin визначають метадані хостів і base URL. +має знати до завантаження рантайму провайдера. Ядро, як і раніше, володіє значенням кожного +`endpointClass`; маніфести Plugin володіють метаданими хоста та base URL. Поля кінцевої точки: -| Поле | Тип | Що воно означає | -| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------- | +| Поле | Тип | Що воно означає | +| ------------------------------ | ---------- | ----------------------------------------------------------------------------------------- | | `endpointClass` | `string` | Відомий ядру клас кінцевої точки, наприклад `openrouter`, `moonshot-native` або `google-vertex`. | -| `hosts` | `string[]` | Точні імена хостів, які зіставляються з класом кінцевої точки. | -| `hostSuffixes` | `string[]` | Суфікси хостів, які зіставляються з класом кінцевої точки. Додавайте префікс `.` для зіставлення лише суфікса домену. | -| `baseUrls` | `string[]` | Точні нормалізовані HTTP(S) base URL, які зіставляються з класом кінцевої точки. | -| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | -| `googleVertexRegionHostSuffix` | `string` | Суфікс, який слід видалити зі збіжних хостів, щоб отримати префікс регіону Google Vertex. | +| `hosts` | `string[]` | Точні імена хостів, які зіставляються з класом кінцевої точки. | +| `hostSuffixes` | `string[]` | Суфікси хостів, які зіставляються з класом кінцевої точки. Додайте префікс `.` для зіставлення лише за суфіксом домену. | +| `baseUrls` | `string[]` | Точні нормалізовані HTTP(S) base URL, які зіставляються з класом кінцевої точки. | +| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | +| `googleVertexRegionHostSuffix` | `string` | Суфікс, який слід видалити зі збіжних хостів, щоб отримати префікс регіону Google Vertex. | ## Довідник `providerRequest` -Використовуйте `providerRequest` для легких метаданих сумісності запитів, які загальна -політика запитів потребує без завантаження runtime provider. Переписування payload, специфічне -для поведінки, залишайте в runtime hooks provider або спільних допоміжних засобах сімейства provider. +Використовуйте `providerRequest` для легких метаданих сумісності запитів, які загальній +політиці запитів потрібні без завантаження рантайму провайдера. Переписування payload, специфічне для +поведінки, залишайте в runtime-хуках провайдера або спільних допоміжних засобах сімейства провайдерів. ```json { @@ -857,19 +864,19 @@ plugin-власника, а не в таблицях вибору моделей } ``` -Поля provider: +Поля провайдера: -| Поле | Тип | Що воно означає | -| --------------------- | ------------ | ------------------------------------------------------------------------------------- | -| `family` | `string` | Мітка сімейства provider, що використовується загальними рішеннями й діагностикою сумісності запитів. | -| `compatibilityFamily` | `"moonshot"` | Необов’язковий bucket сумісності сімейства provider для спільних допоміжних засобів запитів. | -| `openAICompletions` | `object` | Прапорці запитів completions, сумісних з OpenAI; наразі це `supportsStreamingUsage`. | +| Поле | Тип | Що воно означає | +| --------------------- | ------------ | --------------------------------------------------------------------------------------- | +| `family` | `string` | Мітка сімейства провайдерів, яка використовується для загальних рішень і діагностики сумісності запитів. | +| `compatibilityFamily` | `"moonshot"` | Необов’язковий бакет сумісності сімейства провайдерів для спільних допоміжних засобів запитів. | +| `openAICompletions` | `object` | Прапорці запитів completions, сумісних з OpenAI; наразі це `supportsStreamingUsage`. | ## Довідник `modelPricing` -Використовуйте `modelPricing`, коли provider потребує поведінки ціноутворення control-plane до -завантаження runtime. Кеш ціноутворення Gateway зчитує ці метадані без імпорту -коду runtime provider. +Використовуйте `modelPricing`, коли провайдеру потрібна поведінка ціноутворення control-plane до +завантаження рантайму. Кеш ціноутворення Gateway зчитує ці метадані без імпорту коду +рантайму провайдера. ```json { @@ -890,136 +897,136 @@ plugin-власника, а не в таблицях вибору моделей } ``` -Поля provider: +Поля провайдера: | Поле | Тип | Що воно означає | | ------------ | ----------------- | --------------------------------------------------------------------------------------------------- | -| `external` | `boolean` | Установіть `false` для локальних/self-hosted provider, які ніколи не повинні отримувати ціни з OpenRouter або LiteLLM. | -| `openRouter` | `false \| object` | Мапування пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього provider. | -| `liteLLM` | `false \| object` | Мапування пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього provider. | +| `external` | `boolean` | Встановіть `false` для локальних/self-hosted провайдерів, які ніколи не повинні отримувати ціни з OpenRouter або LiteLLM. | +| `openRouter` | `false \| object` | Відображення пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера. | +| `liteLLM` | `false \| object` | Відображення пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера. | Поля джерела: | Поле | Тип | Що воно означає | | -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | Ідентифікатор provider зовнішнього каталогу, коли він відрізняється від ідентифікатора provider OpenClaw, наприклад `z-ai` для provider `zai`. | -| `passthroughProviderModel` | `boolean` | Розглядати ідентифікатори моделей, що містять слеш, як вкладені посилання provider/model; корисно для proxy provider, таких як OpenRouter. | -| `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти ідентифікаторів моделей для зовнішнього каталогу. `version-dots` пробує крапкові ідентифікатори версій, як-от `claude-opus-4.6`. | +| `provider` | `string` | Ідентифікатор провайдера у зовнішньому каталозі, якщо він відрізняється від ідентифікатора провайдера OpenClaw, наприклад `z-ai` для провайдера `zai`. | +| `passthroughProviderModel` | `boolean` | Розглядати ідентифікатори моделей, що містять слеш, як вкладені посилання provider/model; корисно для проксі-провайдерів, таких як OpenRouter. | +| `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти ідентифікаторів моделей у зовнішньому каталозі. `version-dots` пробує версійні ідентифікатори з крапками, такі як `claude-opus-4.6`. | -### Індекс Provider OpenClaw +### Індекс провайдерів OpenClaw -Індекс Provider OpenClaw — це preview-метадані, що належать OpenClaw, для provider, -plugin яких можуть бути ще не встановлені. Він не є частиною маніфесту plugin. -Маніфести plugin залишаються авторитетним джерелом для встановлених plugin. Індекс Provider — -це внутрішній fallback-контракт, який використовуватимуть майбутні поверхні -installable-provider і вибору моделей до встановлення, коли plugin provider ще не встановлено. +Індекс провайдерів OpenClaw — це preview-метадані, якими володіє OpenClaw, для провайдерів, +Plugin яких, можливо, ще не встановлено. Він не є частиною маніфесту Plugin. +Маніфести Plugin залишаються авторитетним джерелом для встановлених Plugin. Індекс провайдерів — це +внутрішній fallback-контракт, який у майбутньому використовуватимуть поверхні +встановлюваних провайдерів і вибору моделей до встановлення, коли Plugin провайдера не встановлено. Порядок авторитетності каталогу: 1. Конфігурація користувача. -2. `modelCatalog` маніфесту встановленого plugin. +2. `modelCatalog` маніфесту встановленого Plugin. 3. Кеш каталогу моделей після явного оновлення. -4. preview-рядки Індексу Provider OpenClaw. +4. Preview-рядки індексу провайдерів OpenClaw. -Індекс Provider не повинен містити секретів, стану ввімкнення, runtime hooks або -живих специфічних для облікового запису даних моделей. Його preview-каталоги використовують ту саму -форму рядка provider `modelCatalog`, що й маніфести plugin, але мають залишатися обмеженими -стабільними метаданими відображення, якщо тільки поля runtime-адаптера, як-от `api`, -`baseUrl`, ціноутворення або прапорці сумісності, не підтримуються навмисно в узгодженому стані -з маніфестом встановленого plugin. Provider із живим виявленням `/models` повинні -записувати оновлені рядки через явний шлях кешу model catalog, а не змушувати -звичайний перелік чи онбординг викликати API provider. +Індекс провайдерів не повинен містити секрети, стан увімкнення, runtime-хуки або +актуальні дані моделей, специфічні для облікового запису. Його preview-каталоги використовують ту саму +форму рядка провайдера `modelCatalog`, що й маніфести Plugin, але мають обмежуватися +стабільними метаданими відображення, якщо лише поля runtime-адаптера, такі як `api`, +`baseUrl`, ціноутворення або прапорці сумісності, не підтримуються навмисно узгодженими +з маніфестом встановленого Plugin. Провайдери з живим виявленням `/models` мають +записувати оновлені рядки через явний шлях кешу каталогу моделей замість +того, щоб під час звичайного переліку або онбордингу викликати API провайдера. -Записи Індексу Provider також можуть містити метадані installable-plugin для provider, -plugin яких було винесено з ядра або які ще не встановлено з інших причин. Ці -метадані наслідують шаблон каталогу channel: назви пакета, специфікації встановлення npm, -очікувана цілісність і легкі підписи варіантів автентифікації достатні, щоб показати -варіант налаштування встановлюваного plugin. Щойно plugin встановлено, його маніфест має перевагу, і -запис Індексу Provider для цього provider ігнорується. +Записи індексу провайдерів також можуть містити метадані встановлюваного Plugin для провайдерів, +чий Plugin було винесено з ядра або який інакше ще не встановлено. Ці +метадані повторюють шаблон каталогу каналів: назви пакета, специфікації npm install, +очікувана цілісність і легкі мітки варіантів автентифікації достатні, щоб показати +встановлюваний варіант setup. Після встановлення Plugin його маніфест має перевагу, і +запис індексу провайдера для цього провайдера ігнорується. -Застарілі ключі можливостей верхнього рівня є deprecated. Використовуйте `openclaw doctor --fix`, щоб +Застарілі верхньорівневі ключі можливостей є deprecated. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне -завантаження маніфесту більше не трактує ці поля верхнього рівня як -належність можливостей. +`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне +завантаження маніфесту більше не трактує ці верхньорівневі поля як +володіння можливостями. ## Маніфест і `package.json` -Ці два файли виконують різні завдання: +Ці два файли виконують різні ролі: -| Файл | Використовуйте для | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, перевірка конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду plugin | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для точок входу, обмеження встановлення, setup або метаданих каталогу | +| Файл | Для чого використовувати | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду Plugin | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, gating встановлення, setup або метаданих каталогу | -Якщо ви не впевнені, де має бути певний елемент метаданих, користуйтеся таким правилом: +Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило: -- якщо OpenClaw повинен знати це до завантаження коду plugin, розміщуйте це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json` +- якщо OpenClaw має знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json` +- якщо це стосується пакування, файлів точок входу або поведінки npm install, розміщуйте це в `package.json` ### Поля `package.json`, які впливають на виявлення -Деякі метадані plugin до запуску runtime навмисно зберігаються в `package.json` у блоці +Деякі метадані Plugin до рантайму навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: | Поле | Що воно означає | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | Оголошує точки входу власного Plugin. Має залишатися в межах каталогу пакета plugin. | -| `openclaw.runtimeExtensions` | Оголошує точки входу built JavaScript runtime для встановлених пакетів. Має залишатися в межах каталогу пакета plugin. | -| `openclaw.setupEntry` | Полегшена точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску channel і виявлення status/SecretRef channel лише для читання. Має залишатися в межах каталогу пакета plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript точку входу setup для встановлених пакетів. Має залишатися в межах каталогу пакета plugin. | -| `openclaw.channel` | Легкі метадані каталогу channel, такі як підписи, шляхи до документації, псевдоніми й текст для вибору. | -| `openclaw.channel.commands` | Статичні метадані авто-типових значень native command і native Skill, які використовуються поверхнями config, audit і списку команд до завантаження runtime channel. | -| `openclaw.channel.configuredState` | Полегшені метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного runtime channel. | -| `openclaw.channel.persistedAuthState` | Полегшені метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного runtime channel. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення пакетних і зовнішньо опублікованих plugin. | +| `openclaw.extensions` | Оголошує точки входу рідного Plugin. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeExtensions` | Оголошує зібрані точки входу рантайму JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.setupEntry` | Легка точка входу лише для setup, яка використовується під час онбордингу, відкладеного запуску каналу та read-only виявлення стану каналу/SecretRef. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує зібрану точку входу setup JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | +| `openclaw.channel` | Легкі метадані каталогу каналу, такі як мітки, шляхи до документації, аліаси та текст для вибору. | +| `openclaw.channel.commands` | Статичні метадані auto-типових значень native command і native skill, що використовуються конфігурацією, аудитом і поверхнями списку команд до завантаження рантайму каналу. | +| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через 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` | Дозволяє поверхням channel лише для setup завантажуватися до повного channel plugin під час запуску. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із semver-нижньою межею, наприклад `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого Plugin, коли конфігурація невалідна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в -онбордингу до завантаження runtime. `package.json#openclaw.install` повідомляє -онбордингу, як отримати або ввімкнути цей plugin, коли користувач вибирає один із цих -варіантів. Не переносіть підказки для встановлення в `openclaw.plugin.json`. +онбордингу до завантаження рантайму. `package.json#openclaw.install` повідомляє +онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих +варіантів. Не переносіть підказки встановлення до `openclaw.plugin.json`. `openclaw.install.minHostVersion` застосовується під час встановлення та -завантаження реєстру маніфестів. Недійсні значення відхиляються; новіші, але коректні значення -пропускають plugin на старіших хостах. +завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають +Plugin на старіших хостах. -Точне закріплення версії npm уже зберігається в `npmSpec`, наприклад +Точне закріплення версії npm уже міститься в `npmSpec`, наприклад `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу -повинні поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення -закривалися безпечно, якщо отриманий артефакт npm більше не відповідає закріпленому релізу. -Інтерактивний онбординг і далі пропонує довірені npm-специфікації реєстру, зокрема прості -назви пакетів і dist-tag, для сумісності. Діагностика каталогу може -розрізняти точні, плаваючі, закріплені цілісністю, без цілісності, із невідповідністю назви пакета -та недійсні джерела default-choice. Вона також попереджає, коли -`expectedIntegrity` присутній, але немає коректного джерела npm, яке можна ним закріпити. -Коли `expectedIntegrity` присутній, -потоки встановлення/оновлення застосовують його; коли його пропущено, розв’язання реєстру +мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення безпечно завершувалися помилкою, +якщо отриманий артефакт npm більше не відповідає закріпленому релізу. +Інтерактивний онбординг усе ще пропонує довірені специфікації npm реєстру, включно з +простими назвами пакетів і dist-tag, для сумісності. Діагностика каталогу може +розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, із невідповідністю назви пакета та +невалідні джерела default-choice. Вона також попереджає, коли +`expectedIntegrity` присутнє, але немає валідного джерела npm, яке воно може закріпити. +Коли `expectedIntegrity` присутнє, +потоки встановлення/оновлення застосовують його; коли його пропущено, резолвинг реєстру записується без закріплення цілісності. -Channel plugin повинні надавати `openclaw.setupEntry`, коли для status, списку channel +Plugin каналів мають надавати `openclaw.setupEntry`, коли для статусу, списку каналів або сканування SecretRef потрібно визначати налаштовані облікові записи без завантаження повного -runtime. Точка входу setup має надавати метадані channel разом із безпечною для setup config, -status і адаптерами secrets; мережеві клієнти, Gateway listener і transport runtime -залишайте в основній точці входу extension. +рантайму. Запис setup має надавати метадані каналу разом із безпечною для setup конфігурацією, +статусом і адаптерами секретів; мережеві клієнти, слухачі gateway і +transport runtimes слід залишати в основній точці входу розширення. Поля точки входу runtime не перевизначають перевірки меж пакета для полів -точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити +точки входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити завантажуваним шлях `openclaw.extensions`, що виходить за межі пакета. -`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він -не робить довільні зламані конфігурації придатними до встановлення. Наразі він лише дозволяє потокам встановлення -відновлюватися після конкретних збоїв оновлення застарілого пакетного plugin, наприклад -відсутнього шляху пакетного plugin або застарілого запису `channels.` для цього самого -пакетного plugin. Не пов’язані помилки конфігурації все одно блокують встановлення і спрямовують операторів +`openclaw.install.allowInvalidConfigRecovery` навмисно обмежене. Воно не +робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам встановлення +відновлюватися після конкретних застарілих збоїв оновлення вбудованих Plugin, таких як +відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для того самого +вбудованого Plugin. Непов’язані помилки конфігурації все одно блокують встановлення і спрямовують операторів до `openclaw doctor --fix`. `openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля @@ -1039,15 +1046,15 @@ status і адаптерами secrets; мережеві клієнти, Gateway } ``` -Використовуйте це, коли потокам setup, doctor, status або лише для читання присутності потрібна легка -перевірка автентифікації типу так/ні до завантаження повного channel plugin. Persisted auth state — -це не configured channel state: не використовуйте ці метадані для автоувімкнення plugin, -відновлення runtime-залежностей або вирішення, чи слід завантажувати runtime channel. -Цільовий export має бути невеликою функцією, що читає лише persisted state; не -спрямовуйте його через повний barrel runtime channel. +Використовуйте це, коли потокам setup, doctor, status або read-only перевірки присутності потрібна дешева +перевірка автентифікації так/ні до завантаження повного Plugin каналу. Збережений стан автентифікації — +це не налаштований стан каналу: не використовуйте ці метадані для автоувімкнення Plugin, +відновлення залежностей runtime або вирішення, чи має завантажуватися рантайм каналу. +Цільовий експорт має бути невеликою функцією, яка зчитує лише збережений стан; не +спрямовуйте його через повний barrel рантайму каналу. -`openclaw.channel.configuredState` має ту саму форму для легких -перевірок configured state лише через env: +`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок +налаштованого стану лише через env: ```json { @@ -1063,68 +1070,68 @@ status і адаптерами secrets; мережеві клієнти, Gateway } ``` -Використовуйте це, коли channel може визначити configured state через env або інші -невеликі нерuntime-входи. Якщо перевірка потребує повного розв’язання config або справжнього -runtime channel, залишайте цю логіку в hook plugin `config.hasConfiguredState`. +Використовуйте це, коли канал може визначити налаштований стан на основі env або інших невеликих +нерuntime-входів. Якщо для перевірки потрібне повне резолвлення конфігурації або справжній +рантайм каналу, залишайте цю логіку в хуку Plugin `config.hasConfiguredState`. -## Пріоритет виявлення (дубльовані ідентифікатори plugin) +## Пріоритет виявлення (дубльовані ідентифікатори Plugin) -OpenClaw виявляє plugin з кількох коренів (пакетні, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються, а не завантажуються поруч. +OpenClaw виявляє Plugin із кількох коренів (вбудовані, глобальне встановлення, workspace, шляхи, явно вибрані конфігурацією). Якщо два виявлені Plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поряд із ним. -Пріоритет від найвищого до найнижчого: +Пріоритет, від найвищого до найнижчого: -1. **Вибрані конфігурацією** — шлях, явно закріплений у `plugins.entries.` -2. **Пакетні** — plugin, що постачаються з OpenClaw -3. **Глобальне встановлення** — plugin, установлені в глобальний корінь plugin OpenClaw -4. **Workspace** — plugin, виявлені відносно поточного workspace +1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` +2. **Вбудований** — Plugin, що постачаються з OpenClaw +3. **Глобальне встановлення** — Plugin, установлені в глобальний корінь Plugin OpenClaw +4. **Workspace** — Plugin, виявлені відносно поточного workspace Наслідки: -- Форк або застаріла копія пакетного plugin у workspace не затьмарить пакетну збірку. -- Щоб справді перевизначити пакетний plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтесь на виявлення у workspace. +- Fork або застаріла копія вбудованого Plugin у workspace не затьмарить вбудовану збірку. +- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтесь на виявлення у workspace. - Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. -## Вимоги до схеми JSON +## Вимоги до JSON Schema -- **Кожен plugin повинен постачатися зі схемою JSON**, навіть якщо він не приймає конфігурацію. -- Порожня схема припустима (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми перевіряються під час читання/запису конфігурації, а не під час runtime. +- **Кожен Plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію. +- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми проходять валідацію під час читання/запису конфігурації, а не в runtime. -## Поведінка перевірки +## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор channel не оголошений - маніфестом plugin. +- Невідомі ключі `channels.*` — це **помилки**, якщо тільки ідентифікатор каналу не оголошено + маніфестом Plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - повинні посилатися на **виявлювані** ідентифікатори plugin. Невідомі ідентифікатори є **помилками**. -- Якщо plugin встановлено, але він має зламаний або відсутній маніфест чи схему, - перевірка завершується помилкою, а Doctor повідомляє про помилку plugin. -- Якщо конфігурація plugin існує, але plugin **вимкнений**, конфігурація зберігається, і - в Doctor + журналах відображається **попередження**. + мають посилатися на **доступні для виявлення** ідентифікатори Plugin. Невідомі ідентифікатори — це **помилки**. +- Якщо Plugin встановлено, але його маніфест або схема зламані чи відсутні, + валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. +- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається і + у Doctor + логах з’являється **попередження**. Повну схему `plugins.*` див. у [Довіднику з конфігурації](/uk/gateway/configuration). ## Примітки -- Маніфест **обов’язковий для власних Plugin OpenClaw**, включно із завантаженням з локальної файлової системи. Runtime, як і раніше, завантажує модуль plugin окремо; маніфест потрібен лише для виявлення + перевірки. -- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок приймаються, якщо фінальне значення все ще є об’єктом. -- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте користувацьких ключів верхнього рівня. -- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, коли plugin їх не потребує. -- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу provider або вузьких дескрипторів виявлення, а не для виконання під час запиту. -- Ексклюзивні типи plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типове значення `legacy`). -- Метадані env var (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Status, audit, перевірка доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до plugin і ефективної активації, перш ніж вважати env var налаштованою. -- Метадані runtime wizard, які потребують коду provider, див. у [Runtime hooks provider](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш plugin залежить від native module, задокументуйте кроки збірки й будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Маніфест є **обов’язковим для рідних Plugin OpenClaw**, включно з локальними завантаженнями з файлової системи. Runtime і далі завантажує модуль Plugin окремо; маніфест призначений лише для виявлення + валідації. +- Рідні маніфести розбираються як JSON5, тому коментарі, кінцеві коми та ключі без лапок приймаються, якщо кінцеве значення все одно є об’єктом. +- Завантажувач маніфесту зчитує лише задокументовані поля маніфесту. Уникайте користувацьких верхньорівневих ключів. +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує. +- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий код runtime; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час запиту. +- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). +- Метадані env vars (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Status, audit, валідація доставки Cron та інші read-only поверхні все одно застосовують політику довіри до Plugin і ефективної активації, перш ніж вважати env var налаштованою. +- Метадані runtime wizard, які потребують коду провайдера, див. у [Runtime-хуках провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш Plugin залежить від native modules, задокументуйте кроки збірки та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане - - Початок роботи з plugin. + + Початок роботи з Plugin. - - Внутрішня архітектура й модель можливостей. + + Внутрішня архітектура та модель можливостей. - Довідник SDK plugin та імпорти підшляхів. + Довідник SDK Plugin та імпорти підшляхів. diff --git a/docs/uk/plugins/sdk-provider-plugins.md b/docs/uk/plugins/sdk-provider-plugins.md index 35681afb0..b104f7192 100644 --- a/docs/uk/plugins/sdk-provider-plugins.md +++ b/docs/uk/plugins/sdk-provider-plugins.md @@ -1,38 +1,38 @@ --- read_when: - - Ви створюєте новий Plugin постачальника моделей - - Ви хочете додати OpenAI-сумісний проксі або власну LLM до OpenClaw + - Ви створюєте новий plugin постачальника моделей + - Ви хочете додати сумісний з OpenAI проксі або власну LLM до OpenClaw - Вам потрібно зрозуміти автентифікацію постачальника, каталоги та runtime-хуки sidebarTitle: Provider plugins -summary: Покроковий посібник зі створення Plugin постачальника моделей для OpenClaw -title: Створення Plugin постачальників моделей +summary: Покроковий посібник зі створення plugin постачальника моделей для OpenClaw +title: Створення plugin постачальників моделей x-i18n: - generated_at: "2026-04-27T20:43:56Z" + generated_at: "2026-04-28T01:41:57Z" model: gpt-5.4 provider: openai - source_hash: 9a4f0d0bed655ccda7ce2731270999d46d83f29b89d5e8ba80832992161eb993 + source_hash: 4f28bc56347cca1259959444e086a3c6ea1b9f00e3a7d68332add962dfcac2d3 source_path: plugins/sdk-provider-plugins.md workflow: 15 --- -Цей посібник описує створення Plugin постачальника, який додає постачальника -моделей (LLM) до OpenClaw. Наприкінці ви матимете постачальника з каталогом моделей, +Цей посібник пояснює, як створити plugin постачальника, який додає постачальника моделей +(LLM) до OpenClaw. Наприкінці у вас буде постачальник із каталогом моделей, автентифікацією через API-ключ і динамічним визначенням моделей. - Якщо ви раніше не створювали жодного Plugin для OpenClaw, спочатку прочитайте - [Початок роботи](/uk/plugins/building-plugins), щоб ознайомитися з базовою - структурою пакета та налаштуванням маніфесту. + Якщо ви раніше не створювали жодного plugin для OpenClaw, спершу прочитайте + [Початок роботи](/uk/plugins/building-plugins) щодо базової структури + пакета та налаштування маніфесту. - Plugin постачальників додають моделі до стандартного циклу інференсу OpenClaw. Якщо модель - має працювати через нативний демон агента, який керує потоками, Compaction або - подіями інструментів, поєднайте постачальника з [обв’язкою агента](/uk/plugins/sdk-agent-harness), + Plugins постачальників додають моделі до звичайного циклу інференсу OpenClaw. Якщо модель + має працювати через нативний демон агента, який керує потоками, Compaction або подіями + інструментів, поєднайте постачальника з [agent harness](/uk/plugins/sdk-agent-harness), а не виносьте деталі протоколу демона в core. -## Покроковий посібник +## Покроковий розбір @@ -94,12 +94,12 @@ x-i18n: Маніфест оголошує `providerAuthEnvVars`, щоб OpenClaw міг виявляти - облікові дані без завантаження runtime вашого Plugin. Додавайте `providerAuthAliases`, + облікові дані без завантаження runtime вашого plugin. Додайте `providerAuthAliases`, коли варіант постачальника має повторно використовувати автентифікацію іншого id постачальника. `modelSupport` - є необов’язковим і дає OpenClaw змогу автоматично завантажити ваш Plugin постачальника зі скорочених + є необов’язковим і дозволяє OpenClaw автоматично завантажувати ваш plugin постачальника зі скорочених id моделей, таких як `acme-large`, ще до появи runtime-хуків. Якщо ви публікуєте - постачальника в ClawHub, поля `openclaw.compat` і `openclaw.build` - у `package.json` є обов’язковими. + постачальника в ClawHub, ці поля `openclaw.compat` і `openclaw.build` + обов’язкові в `package.json`. @@ -113,7 +113,7 @@ x-i18n: export default definePluginEntry({ id: "acme-ai", name: "Acme AI", - description: "Acme AI model provider", + description": "Acme AI model provider", register(api) { api.registerProvider({ id: "acme-ai", @@ -175,12 +175,12 @@ x-i18n: }); ``` - Це вже робочий постачальник. Тепер користувачі можуть виконати - `openclaw onboard --acme-ai-api-key ` і вибрати + Це вже робочий постачальник. Тепер користувачі можуть + `openclaw onboard --acme-ai-api-key ` і вибирати `acme-ai/acme-large` як свою модель. - Якщо постачальник upstream використовує інші керувальні токени, ніж OpenClaw, додайте - невелике двонапрямне текстове перетворення замість заміни шляху потоку: + Якщо постачальник вище за потоком використовує інші керівні токени, ніж OpenClaw, додайте + невелике двоспрямоване текстове перетворення замість заміни шляху потоку: ```typescript api.registerTextTransforms({ @@ -198,12 +198,12 @@ x-i18n: ``` `input` переписує фінальний системний prompt і вміст текстових повідомлень перед - передаванням. `output` переписує текстові дельти асистента та фінальний текст перед тим, як - OpenClaw розбере власні керувальні маркери або доставку каналу. + передаванням. `output` переписує текстові дельти асистента та фінальний текст до того, як + OpenClaw розбере власні керівні маркери або доставку через канал. - Для вбудованих постачальників, які реєструють лише одного текстового постачальника з - автентифікацією через API-ключ і одним runtime на основі каталогу, надавайте перевагу - вужчому helper `defineSingleProviderPluginEntry(...)`: + Для вбудованих постачальників, які реєструють лише одного текстового постачальника з автентифікацією + через API-ключ плюс один runtime на основі каталогу, віддавайте перевагу + вужчому хелперу `defineSingleProviderPluginEntry(...)`: ```typescript import { defineSingleProviderPluginEntry } from "openclaw/plugin-sdk/provider-entry"; @@ -244,32 +244,32 @@ x-i18n: ``` `buildProvider` — це шлях живого каталогу, який використовується, коли OpenClaw може визначити реальну - автентифікацію постачальника. Він може виконувати специфічне для постачальника виявлення. - Використовуйте `buildStaticProvider` лише для офлайн-рядків, які безпечно показувати до налаштування - автентифікації; він не повинен вимагати облікових даних або виконувати мережеві запити. - Поточне відображення OpenClaw `models list --all` виконує статичні каталоги - лише для вбудованих Plugin постачальників, з порожньою конфігурацією, порожнім env і без + автентифікацію постачальника. Він може виконувати специфічне для постачальника виявлення. Використовуйте + `buildStaticProvider` лише для офлайн-рядків, які безпечно показувати до налаштування автентифікації; + він не повинен вимагати облікових даних або виконувати мережеві запити. + Поточне відображення `models list --all` в OpenClaw виконує статичні каталоги + лише для вбудованих plugin постачальників, з порожньою конфігурацією, порожнім env і без шляхів агента/робочого простору. - Якщо вашому процесу автентифікації також потрібно оновлювати `models.providers.*`, - псевдоніми та модель агента за замовчуванням під час onboarding, використовуйте готові helper-и з - `openclaw/plugin-sdk/provider-onboard`. Найвужчі helper-и: + Якщо вашому потоку автентифікації також потрібно змінювати `models.providers.*`, аліаси + та модель агента за замовчуванням під час онбордингу, використовуйте preset-хелпери з + `openclaw/plugin-sdk/provider-onboard`. Найвужчі хелпери — `createDefaultModelPresetAppliers(...)`, `createDefaultModelsPresetAppliers(...)` і `createModelCatalogPresetAppliers(...)`. - Коли нативний endpoint постачальника підтримує потокові блоки використання в - звичайному транспорті `openai-completions`, надавайте перевагу спільним helper-ам каталогу з + Коли нативна кінцева точка постачальника підтримує потокові блоки використання на + звичайному транспорті `openai-completions`, віддавайте перевагу спільним хелперам каталогу з `openclaw/plugin-sdk/provider-catalog-shared`, а не жорстко прописуйте перевірки provider-id. `supportsNativeStreamingUsageCompat(...)` і - `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку за мапою можливостей endpoint, - тож нативні endpoint-и на кшталт Moonshot/DashScope усе одно можуть бути ввімкнені, навіть коли Plugin використовує - власний id постачальника. + `applyProviderNativeStreamingUsageCompat(...)` визначають підтримку з мапи можливостей + кінцевої точки, тому нативні кінцеві точки у стилі Moonshot/DashScope усе одно вмикаються, + навіть коли plugin використовує власний provider id. - - Якщо ваш постачальник приймає довільні id моделей (наприклад, проксі або маршрутизатор), + + Якщо ваш постачальник приймає довільні id моделей (наприклад, проксі або роутер), додайте `resolveDynamicModel`: ```typescript @@ -292,16 +292,16 @@ x-i18n: ``` Якщо для визначення потрібен мережевий виклик, використовуйте `prepareDynamicModel` для асинхронного - прогріву — після його завершення `resolveDynamicModel` буде виконано знову. + прогріву — після його завершення `resolveDynamicModel` запуститься знову. Більшості постачальників потрібні лише `catalog` + `resolveDynamicModel`. Додавайте хуки - поступово, у міру того як цього вимагатиме ваш постачальник. + поступово, залежно від потреб вашого постачальника. - Спільні builder-helper-и тепер охоплюють найпоширеніші сімейства replay/tool-compat, - тому Plugin зазвичай не потрібно вручну підключати кожен хук окремо: + Спільні builder-хелпери тепер покривають найпоширеніші сімейства replay/tool-compat, + тож plugins зазвичай не потрібно вручну під’єднувати кожен хук окремо: ```typescript import { buildProviderReplayFamilyHooks } from "openclaw/plugin-sdk/provider-model-shared"; @@ -321,38 +321,38 @@ x-i18n: }); ``` - Наразі доступні такі сімейства replay: + Доступні на сьогодні сімейства replay: | Сімейство | Що воно підключає | Вбудовані приклади | | --- | --- | --- | - | `openai-compatible` | Спільна політика replay у стилі OpenAI для OpenAI-сумісних транспортів, включно з очищенням tool-call-id, виправленням порядку assistant-first і загальною валідацією Gemini-turn там, де це потрібно транспорту | `moonshot`, `ollama`, `xai`, `zai` | - | `anthropic-by-model` | Політика replay з урахуванням Claude, що вибирається за `modelId`, тож транспорти повідомлень Anthropic отримують очищення thinking-block, специфічне для Claude, лише коли визначена модель справді є id Claude | `amazon-bedrock`, `anthropic-vertex` | - | `google-gemini` | Нативна політика replay Gemini плюс початкове очищення replay і режим тегованого reasoning-output | `google`, `google-gemini-cli` | - | `passthrough-gemini` | Очищення thought-signature Gemini для моделей Gemini, що працюють через OpenAI-сумісні проксі-транспорти; не вмикає нативну валідацію replay Gemini або початкові переписування | `openrouter`, `kilocode`, `opencode`, `opencode-go` | - | `hybrid-anthropic-openai` | Гібридна політика для постачальників, які поєднують поверхні моделей Anthropic-message і OpenAI-compatible в одному Plugin; необов’язкове відкидання thinking-block лише для Claude залишається обмеженим стороною Anthropic | `minimax` | + | `openai-compatible` | Спільна політика replay у стилі OpenAI для транспортів, сумісних з OpenAI, включно з очищенням tool-call-id, виправленнями порядку assistant-first і загальною валідацією Gemini-turn там, де це потрібно транспорту | `moonshot`, `ollama`, `xai`, `zai` | + | `anthropic-by-model` | Політика replay з урахуванням Claude, яка вибирається за `modelId`, тож транспорти повідомлень Anthropic отримують специфічне очищення thinking-block для Claude лише тоді, коли визначена модель справді є id Claude | `amazon-bedrock`, `anthropic-vertex` | + | `google-gemini` | Нативна політика replay для Gemini плюс початкове очищення replay і режим тегованого reasoning-output | `google`, `google-gemini-cli` | + | `passthrough-gemini` | Очищення thought-signature Gemini для моделей Gemini, що працюють через проксі-транспорти, сумісні з OpenAI; не вмикає нативну валідацію replay Gemini або початкові переписування | `openrouter`, `kilocode`, `opencode`, `opencode-go` | + | `hybrid-anthropic-openai` | Гібридна політика для постачальників, які змішують поверхні моделей Anthropic-message і OpenAI-compatible в одному plugin; необов’язкове відкидання thinking-block лише для Claude залишається обмеженим стороною Anthropic | `minimax` | - Наразі доступні такі сімейства потоків: + Доступні на сьогодні сімейства потоків: | Сімейство | Що воно підключає | Вбудовані приклади | | --- | --- | --- | - | `google-thinking` | Нормалізація payload thinking Gemini у спільному шляху потоку | `google`, `google-gemini-cli` | - | `kilocode-thinking` | Обгортка reasoning Kilo у спільному шляху проксі-потоку, де `kilo/auto` і непідтримувані proxy reasoning id пропускають ін’єкцію thinking | `kilocode` | - | `moonshot-thinking` | Мапінг бінарного payload native-thinking Moonshot із config + рівня `/think` | `moonshot` | - | `minimax-fast-mode` | Переписування моделі MiniMax fast-mode у спільному шляху потоку | `minimax`, `minimax-portal` | - | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: заголовки атрибуції, `/fast`/`serviceTier`, текстова verbosity, нативний вебпошук Codex, формування payload reasoning-compat і керування контекстом Responses | `openai`, `openai-codex` | - | `openrouter-thinking` | Обгортка reasoning OpenRouter для proxy-маршрутів, із централізованою обробкою пропусків unsupported-model/`auto` | `openrouter` | - | `tool-stream-default-on` | Обгортка `tool_stream`, увімкнена за замовчуванням, для постачальників на кшталт Z.AI, які хочуть потокову передачу інструментів, якщо її явно не вимкнено | `zai` | + | `google-thinking` | Нормалізація payload thinking Gemini на спільному шляху потоку | `google`, `google-gemini-cli` | + | `kilocode-thinking` | Обгортка reasoning Kilo на спільному шляху потоку проксі, де `kilo/auto` та непідтримувані id reasoning проксі пропускають ін’єкцію thinking | `kilocode` | + | `moonshot-thinking` | Відображення бінарного payload native-thinking Moonshot з конфігурації + рівня `/think` | `moonshot` | + | `minimax-fast-mode` | Переписування моделі MiniMax fast-mode на спільному шляху потоку | `minimax`, `minimax-portal` | + | `openai-responses-defaults` | Спільні нативні обгортки OpenAI/Codex Responses: заголовки атрибуції, `/fast`/`serviceTier`, детальність тексту, нативний вебпошук Codex, формування payload для сумісності reasoning і керування контекстом Responses | `openai`, `openai-codex` | + | `openrouter-thinking` | Обгортка reasoning OpenRouter для маршрутів проксі, з централізованою обробкою пропусків для непідтримуваних моделей/`auto` | `openrouter` | + | `tool-stream-default-on` | Увімкнена за замовчуванням обгортка `tool_stream` для постачальників на кшталт Z.AI, яким потрібен потік інструментів, якщо його явно не вимкнено | `zai` | - - Кожен builder сімейства складається з публічних helper-ів нижчого рівня, експортованих із того самого пакета, до яких можна звернутися, коли постачальнику потрібно вийти за межі типового шаблону: + + Кожен builder сімейства складається з публічних низькорівневих хелперів, експортованих із того самого пакета, до яких можна звернутися, коли постачальнику потрібно вийти за межі типового шаблону: - - `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`, `buildProviderReplayFamilyHooks(...)` і необроблені builder-и replay (`buildOpenAICompatibleReplayPolicy`, `buildAnthropicReplayPolicyForModel`, `buildGoogleGeminiReplayPolicy`, `buildHybridAnthropicOrOpenAIReplayPolicy`). Також експортує helper-и replay Gemini (`sanitizeGoogleGeminiReplayHistory`, `resolveTaggedReasoningOutputMode`) і helper-и endpoint/моделей (`resolveProviderEndpoint`, `normalizeProviderId`, `normalizeGooglePreviewModelId`, `normalizeNativeXaiModelId`). - - `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`, `buildProviderStreamFamilyHooks(...)`, `composeProviderStreamWrappers(...)`, а також спільні обгортки OpenAI/Codex (`createOpenAIAttributionHeadersWrapper`, `createOpenAIFastModeWrapper`, `createOpenAIServiceTierWrapper`, `createOpenAIResponsesContextManagementWrapper`, `createCodexNativeWebSearchWrapper`), OpenAI-compatible-обгортка DeepSeek V4 (`createDeepSeekV4OpenAICompatibleThinkingWrapper`), очищення prefill payload thinking для Anthropic Messages (`createAnthropicThinkingPrefillPayloadWrapper`) і спільні обгортки proxy/постачальників (`createOpenRouterWrapper`, `createToolStreamWrapper`, `createMinimaxFastModeWrapper`). - - `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks("gemini")`, базові helper-и схем Gemini (`normalizeGeminiToolSchemas`, `inspectGeminiToolSchemas`) і helper-и сумісності xAI (`resolveXaiModelCompatPatch()`, `applyXaiModelCompat(model)`). Вбудований Plugin xAI використовує `normalizeResolvedModel` + `contributeResolvedModelCompat` разом із ними, щоб правила xAI залишалися у власності постачальника. + - `openclaw/plugin-sdk/provider-model-shared` — `ProviderReplayFamily`, `buildProviderReplayFamilyHooks(...)` і сирі builder-и replay (`buildOpenAICompatibleReplayPolicy`, `buildAnthropicReplayPolicyForModel`, `buildGoogleGeminiReplayPolicy`, `buildHybridAnthropicOrOpenAIReplayPolicy`). Також експортує хелпери replay для Gemini (`sanitizeGoogleGeminiReplayHistory`, `resolveTaggedReasoningOutputMode`) і хелпери для endpoint/моделей (`resolveProviderEndpoint`, `normalizeProviderId`, `normalizeGooglePreviewModelId`, `normalizeNativeXaiModelId`). + - `openclaw/plugin-sdk/provider-stream` — `ProviderStreamFamily`, `buildProviderStreamFamilyHooks(...)`, `composeProviderStreamWrappers(...)`, а також спільні обгортки OpenAI/Codex (`createOpenAIAttributionHeadersWrapper`, `createOpenAIFastModeWrapper`, `createOpenAIServiceTierWrapper`, `createOpenAIResponsesContextManagementWrapper`, `createCodexNativeWebSearchWrapper`), сумісна з OpenAI обгортка thinking для DeepSeek V4 (`createDeepSeekV4OpenAICompatibleThinkingWrapper`), очищення prefill payload thinking для Anthropic Messages (`createAnthropicThinkingPrefillPayloadWrapper`) і спільні обгортки проксі/постачальників (`createOpenRouterWrapper`, `createToolStreamWrapper`, `createMinimaxFastModeWrapper`). + - `openclaw/plugin-sdk/provider-tools` — `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks("gemini")`, базові хелпери схем Gemini (`normalizeGeminiToolSchemas`, `inspectGeminiToolSchemas`) і хелпери сумісності xAI (`resolveXaiModelCompatPatch()`, `applyXaiModelCompat(model)`). Вбудований plugin xAI використовує `normalizeResolvedModel` + `contributeResolvedModelCompat` разом із ними, щоб правила xAI залишалися у володінні постачальника. - Деякі helper-и потоку навмисно залишаються локальними для постачальника. `@openclaw/anthropic-provider` тримає `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і builder-и обгорток Anthropic нижчого рівня у власному публічному шві `api.ts` / `contract-api.ts`, оскільки вони кодують обробку Claude OAuth beta і gating `context1m`. Plugin xAI так само зберігає нативне формування xAI Responses у власному `wrapStreamFn` (псевдоніми `/fast`, `tool_stream` за замовчуванням, очищення unsupported strict-tool, видалення payload reasoning, специфічне для xAI). + Деякі хелпери потоків навмисно залишаються локальними для постачальника. `@openclaw/anthropic-provider` зберігає `wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier` і низькорівневі builder-и обгорток Anthropic у власному публічному seam `api.ts` / `contract-api.ts`, оскільки вони кодують обробку Claude OAuth beta і gating `context1m`. Plugin xAI аналогічно зберігає формування нативних xAI Responses у власному `wrapStreamFn` (аліаси `/fast`, `tool_stream` за замовчуванням, очищення unsupported strict-tool, видалення payload reasoning, специфічного для xAI). - Такий самий шаблон на рівні кореня пакета також лежить в основі `@openclaw/openai-provider` (builder-и постачальників, helper-и моделей за замовчуванням, builder-и realtime-постачальників) і `@openclaw/openrouter-provider` (builder постачальника плюс helper-и onboarding/config). + Той самий шаблон на рівні кореня пакета також лежить в основі `@openclaw/openai-provider` (builder-и постачальника, хелпери моделей за замовчуванням, builder-и realtime provider) і `@openclaw/openrouter-provider` (builder постачальника плюс хелпери онбордингу/конфігурації). @@ -370,8 +370,8 @@ x-i18n: }, ``` - - Для постачальників, яким потрібні власні заголовки запиту або зміни тіла: + + Для постачальників, яким потрібні користувацькі заголовки запиту або зміни тіла запиту: ```typescript // wrapStreamFn returns a StreamFn derived from ctx.streamFn @@ -389,8 +389,8 @@ x-i18n: ``` - Для постачальників, яким потрібні нативні заголовки або метадані запиту/сесії в - узагальнених транспортних механізмах HTTP або WebSocket: + Для постачальників, яким потрібні нативні заголовки запиту/сеансу або метадані на + узагальнених HTTP- або WebSocket-транспортних рівнях: ```typescript resolveTransportTurnState: (ctx) => ({ @@ -431,71 +431,71 @@ x-i18n: | # | Хук | Коли використовувати | | --- | --- | --- | | 1 | `catalog` | Каталог моделей або значення `baseUrl` за замовчуванням | - | 2 | `applyConfigDefaults` | Глобальні значення за замовчуванням, що належать постачальнику, під час materialization конфігурації | - | 3 | `normalizeModelId` | Очищення застарілих/preview псевдонімів model-id перед пошуком | - | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` для сімейства постачальника перед загальним збиранням моделі | - | 5 | `normalizeConfig` | Нормалізація config `models.providers.` | - | 6 | `applyNativeStreamingUsageCompat` | Переписування сумісності native streaming-usage для config-постачальників | - | 7 | `resolveConfigApiKey` | Визначення автентифікації env-marker, що належить постачальнику | - | 8 | `resolveSyntheticAuth` | Синтетична автентифікація для локального/self-hosted або config-backed сценарію | - | 9 | `shouldDeferSyntheticProfileAuth` | Пониження пріоритету synthetic placeholder-ів збереженого профілю нижче за автентифікацію env/config | - | 10 | `resolveDynamicModel` | Прийом довільних upstream model id | + | 2 | `applyConfigDefaults` | Глобальні значення за замовчуванням, що належать постачальнику, під час матеріалізації конфігурації | + | 3 | `normalizeModelId` | Очищення застарілих/preview аліасів model-id перед пошуком | + | 4 | `normalizeTransport` | Очищення `api` / `baseUrl` для сімейства постачальників перед збиранням узагальненої моделі | + | 5 | `normalizeConfig` | Нормалізація конфігурації `models.providers.` | + | 6 | `applyNativeStreamingUsageCompat` | Переписування для сумісності native streaming-usage для конфігурованих постачальників | + | 7 | `resolveConfigApiKey` | Визначення автентифікації з env-marker, що належить постачальнику | + | 8 | `resolveSyntheticAuth` | Синтетична автентифікація для local/self-hosted або на основі конфігурації | + | 9 | `shouldDeferSyntheticProfileAuth` | Занижувати пріоритет синтетичних placeholder-ів збереженого профілю порівняно з env/config auth | + | 10 | `resolveDynamicModel` | Приймати довільні id моделей з upstream | | 11 | `prepareDynamicModel` | Асинхронне отримання метаданих перед визначенням | | 12 | `normalizeResolvedModel` | Переписування транспорту перед runner | - | 13 | `contributeResolvedModelCompat` | Прапорці сумісності для моделей постачальника, що працюють через інший сумісний транспорт | + | 13 | `contributeResolvedModelCompat` | Прапорці сумісності для моделей постачальника за іншим сумісним транспортом | | 14 | `capabilities` | Застарілий статичний набір можливостей; лише для сумісності | | 15 | `normalizeToolSchemas` | Очищення схем інструментів, що належить постачальнику, перед реєстрацією | | 16 | `inspectToolSchemas` | Діагностика схем інструментів, що належить постачальнику | - | 17 | `resolveReasoningOutputMode` | Контракт tagged vs native reasoning-output | + | 17 | `resolveReasoningOutputMode` | Контракт тегованого чи нативного reasoning-output | | 18 | `prepareExtraParams` | Параметри запиту за замовчуванням | - | 19 | `createStreamFn` | Повністю власний транспорт StreamFn | - | 20 | `wrapStreamFn` | Обгортки власних заголовків/тіла у звичайному шляху потоку | + | 19 | `createStreamFn` | Повністю користувацький транспорт `StreamFn` | + | 20 | `wrapStreamFn` | Користувацькі обгортки заголовків/тіла на звичайному шляху потоку | | 21 | `resolveTransportTurnState` | Нативні заголовки/метадані для кожного turn | - | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сесії WS / cooldown | - | 23 | `formatApiKey` | Власна форма runtime-токена | - | 24 | `refreshOAuth` | Власне оновлення OAuth | - | 25 | `buildAuthDoctorHint` | Підказка для виправлення автентифікації | - | 26 | `matchesContextOverflowError` | Визначення переповнення, що належить постачальнику | + | 22 | `resolveWebSocketSessionPolicy` | Нативні заголовки сеансу WS / час cool-down | + | 23 | `formatApiKey` | Користувацька форма runtime-токена | + | 24 | `refreshOAuth` | Користувацьке оновлення OAuth | + | 25 | `buildAuthDoctorHint` | Підказка щодо виправлення автентифікації | + | 26 | `matchesContextOverflowError` | Визначення переповнення контексту, що належить постачальнику | | 27 | `classifyFailoverReason` | Класифікація rate-limit/overload, що належить постачальнику | - | 28 | `isCacheTtlEligible` | Гейтинг TTL кешу prompt-ів | - | 29 | `buildMissingAuthMessage` | Власна підказка про відсутню автентифікацію | - | 30 | `suppressBuiltInModel` | Приховування застарілих upstream-рядків | - | 31 | `augmentModelCatalog` | Синтетичні рядки прямої сумісності з майбутніми версіями | - | 32 | `resolveThinkingProfile` | Набір опцій `/think`, специфічний для моделі | - | 33 | `isBinaryThinking` | Сумісність із двійковим thinking увімк./вимк. | - | 34 | `supportsXHighThinking` | Сумісність із reasoning `xhigh` | - | 35 | `resolveDefaultThinkingLevel` | Сумісність із політикою `/think` за замовчуванням | + | 28 | `isCacheTtlEligible` | Gating TTL кешу prompt | + | 29 | `buildMissingAuthMessage` | Користувацька підказка про відсутню автентифікацію | + | 30 | `suppressBuiltInModel` | Застаріло. Runtime-хук більше не викликається; використовуйте `modelCatalog.suppressions` у маніфесті | + | 31 | `augmentModelCatalog` | Синтетичні рядки forward-compat | + | 32 | `resolveThinkingProfile` | Набір параметрів `/think` для конкретної моделі | + | 33 | `isBinaryThinking` | Сумісність бінарного увімкнення/вимкнення thinking | + | 34 | `supportsXHighThinking` | Сумісність підтримки reasoning `xhigh` | + | 35 | `resolveDefaultThinkingLevel` | Сумісність політики `/think` за замовчуванням | | 36 | `isModernModelRef` | Відповідність моделі для live/smoke | | 37 | `prepareRuntimeAuth` | Обмін токенами перед інференсом | - | 38 | `resolveUsageAuth` | Власний розбір облікових даних використання | - | 39 | `fetchUsageSnapshot` | Власний endpoint використання | + | 38 | `resolveUsageAuth` | Користувацький розбір облікових даних використання | + | 39 | `fetchUsageSnapshot` | Користувацька кінцева точка використання | | 40 | `createEmbeddingProvider` | Адаптер embedding, що належить постачальнику, для пам’яті/пошуку | - | 41 | `buildReplayPolicy` | Власна політика replay/Compaction транскрипту | - | 42 | `sanitizeReplayHistory` | Специфічні для постачальника переписування replay після загального очищення | - | 43 | `validateReplayTurns` | Сувора валідація turn-ів replay перед вбудованим runner | - | 44 | `onModelSelected` | Зворотний виклик після вибору моделі (наприклад, телеметрія) | + | 41 | `buildReplayPolicy` | Користувацька політика replay/Compaction транскрипту | + | 42 | `sanitizeReplayHistory` | Переписування replay, специфічні для постачальника, після узагальненого очищення | + | 43 | `validateReplayTurns` | Сувора валідація turn replay перед вбудованим runner | + | 44 | `onModelSelected` | Колбек після вибору моделі (наприклад, телеметрія) | Примітки щодо runtime fallback: - - `normalizeConfig` спочатку перевіряє відповідний постачальник, потім інші Plugin постачальників із підтримкою хуків, доки якийсь із них справді не змінить config. Якщо жоден хук постачальника не перепише підтримуваний запис config сімейства Google, усе ще застосовується вбудований normalizer config Google. - - `resolveConfigApiKey` використовує хук постачальника, якщо він доступний. Вбудований шлях `amazon-bedrock` також має тут вбудований resolver AWS env-marker, хоча runtime-автентифікація Bedrock досі використовує стандартний ланцюжок AWS SDK. - - `resolveSystemPromptContribution` дозволяє постачальнику ін’єктувати підказки системного prompt, чутливі до кешу, для сімейства моделей. Надавайте йому перевагу над `before_prompt_build`, коли поведінка належить одному постачальнику/сімейству моделей і має зберігати стабільний/динамічний поділ кешу. + - `normalizeConfig` спочатку перевіряє відповідного постачальника, а потім інші plugin постачальників із підтримкою хуків, доки один із них справді не змінить конфігурацію. Якщо жоден хук постачальника не переписує підтримуваний запис конфігурації сімейства Google, усе ще застосовується вбудований нормалізатор конфігурації Google. + - `resolveConfigApiKey` використовує хук постачальника, якщо він наданий. Вбудований шлях `amazon-bedrock` також має тут вбудований resolver AWS env-marker, хоча сама runtime-автентифікація Bedrock, як і раніше, використовує стандартний ланцюжок AWS SDK. + - `resolveSystemPromptContribution` дозволяє постачальнику інжектувати cache-aware інструкції системного prompt для сімейства моделей. Віддавайте йому перевагу над `before_prompt_build`, коли поведінка належить одному сімейству постачальника/моделей і має зберігати стабільний/динамічний поділ кешу. - Докладні описи та приклади з реального світу дивіться в [Внутрішня архітектура: runtime-хуки постачальників](/uk/plugins/architecture-internals#provider-runtime-hooks). + Докладні описи та приклади з реального світу дивіться в [Внутрішні механізми: Runtime-хуки постачальників](/uk/plugins/architecture-internals#provider-runtime-hooks). - Plugin постачальника може реєструвати мовлення, realtime-транскрипцію, realtime-голос, - розуміння медіа, генерацію зображень, генерацію відео, web fetch + Plugin постачальника може реєструвати розпізнавання мовлення, транскрипцію realtime, realtime + голос, розуміння медіа, генерацію зображень, генерацію відео, web fetch і web search поряд із текстовим інференсом. OpenClaw класифікує це як - Plugin **hybrid-capability** — рекомендований шаблон для корпоративних Plugin - (один Plugin на постачальника). Див. - [Внутрішня архітектура: володіння можливостями](/uk/plugins/architecture#capability-ownership-model). + plugin **hybrid-capability** — рекомендований шаблон для корпоративних plugins + (один plugin на постачальника). Див. + [Внутрішні механізми: Володіння можливостями](/uk/plugins/architecture#capability-ownership-model). - Реєструйте кожну можливість усередині `register(api)` поруч із вашим наявним - викликом `api.registerProvider(...)`. Обирайте лише ті вкладки, які вам потрібні: + Зареєструйте кожну можливість у `register(api)` поруч із вашим наявним + викликом `api.registerProvider(...)`. Виберіть лише ті вкладки, які вам потрібні: @@ -534,13 +534,14 @@ x-i18n: ``` Використовуйте `assertOkOrThrowProviderError(...)` для HTTP-збоїв постачальника, щоб - Plugin спільно використовували обмежене читання тіла помилки, розбір JSON-помилок і + plugins спільно використовували обмежене читання тіла помилки, розбір помилок JSON і суфікси request-id. - - Надавайте перевагу `createRealtimeTranscriptionWebSocketSession(...)` — цей спільний - helper обробляє захоплення проксі, backoff повторного підключення, flush під час закриття, ready-handshake, постановку аудіо в чергу та діагностику подій закриття. Ваш Plugin - лише зіставляє upstream-події. + + Віддавайте перевагу `createRealtimeTranscriptionWebSocketSession(...)` — спільний + хелпер обробляє перехоплення проксі, backoff для повторного підключення, flush під час закриття, handshake готовності, + постановку аудіо в чергу та діагностику подій закриття. Ваш plugin + лише відображає події upstream. ```typescript api.registerRealtimeTranscriptionProvider({ @@ -578,13 +579,13 @@ x-i18n: }); ``` - Пакетні STT-постачальники, які надсилають multipart-аудіо через POST, мають використовувати + Постачальники пакетного STT, які надсилають multipart-аудіо через POST, повинні використовувати `buildAudioTranscriptionFormData(...)` з - `openclaw/plugin-sdk/provider-http`. Цей helper нормалізує - імена файлів для завантаження, зокрема AAC-завантаження, яким потрібне ім’я файлу у стилі M4A для + `openclaw/plugin-sdk/provider-http`. Хелпер нормалізує + імена файлів для завантаження, зокрема завантаження AAC, яким потрібне ім’я файлу у стилі M4A для сумісних API транскрипції. - + ```typescript api.registerRealtimeVoiceProvider({ id: "acme-ai", @@ -617,10 +618,10 @@ x-i18n: ``` - Можливості відео використовують форму з **урахуванням режиму**: `generate`, + Можливості відео використовують **mode-aware** форму: `generate`, `imageToVideo` і `videoToVideo`. Плоских агрегованих полів на кшталт `maxInputImages` / `maxInputVideos` / `maxDurationSeconds` недостатньо, - щоб коректно оголошувати підтримку режиму transform або чисто вимикати режими. + щоб коректно оголосити підтримку режиму трансформації або чисто вимкнені режими. Генерація музики дотримується того самого шаблону з явними блоками `generate` / `edit`. @@ -654,7 +655,7 @@ x-i18n: api.registerWebFetchProvider({ id: "acme-ai-fetch", label: "Acme Fetch", - hint: "Fetch pages through Acme's rendering backend.", + hint: "Отримуйте сторінки через backend рендерингу Acme.", envVars: ["ACME_FETCH_API_KEY"], placeholder: "acme-...", signupUrl: "https://acme.example.com/fetch", @@ -665,7 +666,7 @@ x-i18n: acme.apiKey = value; }, createTool: () => ({ - description: "Fetch a page through Acme Fetch.", + description: "Отримати сторінку через Acme Fetch.", parameters: {}, execute: async (args) => ({ content: [] }), }), @@ -718,14 +719,14 @@ x-i18n: ## Публікація в ClawHub -Plugin постачальників публікуються так само, як і будь-який інший зовнішній Plugin коду: +Plugins постачальників публікуються так само, як і будь-який інший зовнішній code plugin: ```bash clawhub package publish your-org/your-plugin --dry-run clawhub package publish your-org/your-plugin ``` -Не використовуйте тут застарілий псевдонім публікації лише для Skills; пакети Plugin повинні використовувати +Не використовуйте тут застарілий alias публікації лише для Skills; пакети plugin слід публікувати через `clawhub package publish`. ## Структура файлів @@ -737,30 +738,30 @@ clawhub package publish your-org/your-plugin ├── index.ts # definePluginEntry + registerProvider └── src/ ├── provider.test.ts # Тести - └── usage.ts # Endpoint використання (необов’язково) + └── usage.ts # Кінцева точка використання (необов’язково) ``` -## Довідник порядку каталогів +## Довідник порядку каталогу -`catalog.order` визначає, коли ваш каталог буде об’єднано відносно вбудованих +`catalog.order` керує тим, коли ваш каталог зливається відносно вбудованих постачальників: -| Порядок | Коли | Випадок використання | +| Порядок | Коли | Випадок використання | | --------- | ------------- | ----------------------------------------------- | -| `simple` | Перший прохід | Звичайні постачальники з API-ключем | -| `profile` | Після simple | Постачальники, обмежені профілями автентифікації | -| `paired` | Після profile | Синтез кількох пов’язаних записів | -| `late` | Останній прохід | Перевизначення наявних постачальників (перемагає при конфлікті) | +| `simple` | Перший прохід | Звичайні постачальники з API-ключем | +| `profile` | Після simple | Постачальники, обмежені профілями автентифікації | +| `paired` | Після profile | Синтез кількох пов’язаних записів | +| `late` | Останній прохід | Перевизначення наявних постачальників (перемагає при колізії) | ## Наступні кроки -- [Plugin каналів](/uk/plugins/sdk-channel-plugins) — якщо ваш Plugin також надає канал -- [SDK Runtime](/uk/plugins/sdk-runtime) — helper-и `api.runtime` (TTS, search, subagent) -- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпорту subpath -- [Внутрішня архітектура Plugin](/uk/plugins/architecture-internals#provider-runtime-hooks) — подробиці про хуки та вбудовані приклади +- [Plugins каналів](/uk/plugins/sdk-channel-plugins) — якщо ваш plugin також надає канал +- [SDK Runtime](/uk/plugins/sdk-runtime) — хелпери `api.runtime` (TTS, search, subagent) +- [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпорту підшляхів +- [Внутрішні механізми plugin](/uk/plugins/architecture-internals#provider-runtime-hooks) — подробиці про хуки та вбудовані приклади ## Пов’язане - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення Plugin](/uk/plugins/building-plugins) -- [Створення Plugin каналів](/uk/plugins/sdk-channel-plugins) +- [Створення plugins](/uk/plugins/building-plugins) +- [Створення plugin каналів](/uk/plugins/sdk-channel-plugins) diff --git a/docs/uk/plugins/sdk-subpaths.md b/docs/uk/plugins/sdk-subpaths.md index 8833d5b27..eab2355c1 100644 --- a/docs/uk/plugins/sdk-subpaths.md +++ b/docs/uk/plugins/sdk-subpaths.md @@ -5,232 +5,232 @@ read_when: summary: 'Каталог підшляхів Plugin SDK: які імпорти де розміщені, згруповано за областями' title: Підшляхи Plugin SDK x-i18n: - generated_at: "2026-04-28T01:34:53Z" + generated_at: "2026-04-28T01:41:53Z" model: gpt-5.4 provider: openai - source_hash: 40dbd7010153dc65dcad3c227152c6274cdf01c832b53ab0e00ad59916c43a02 + source_hash: ac30c28c643e6f1a8488ece14f2f8a77c182370b1eb831de4b6f9e1b4d807fbd source_path: plugins/sdk-subpaths.md workflow: 15 --- Plugin SDK представлено як набір вузьких підшляхів у `openclaw/plugin-sdk/`. - На цій сторінці каталогізовано найуживаніші підшляхи, згруповані за призначенням. Згенерований - повний список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`; - зарезервовані допоміжні підшляхи bundled-plugin також наведені там, але є деталями - реалізації, якщо лише сторінка документації явно не просуває їх. + Ця сторінка містить каталог найуживаніших підшляхів, згрупованих за призначенням. Згенерований + повний список із понад 200 підшляхів розміщено в `scripts/lib/plugin-sdk-entrypoints.json`; + зарезервовані допоміжні підшляхи bundled-plugin також наведено там, але вони є деталлю + реалізації, якщо лише сторінка документації не просуває їх явно. - Посібник з написання Plugin див. у [Огляд Plugin SDK](/uk/plugins/sdk-overview). + Посібник з розробки Plugin див. у [Огляд Plugin SDK](/uk/plugins/sdk-overview). ## Точка входу Plugin - | Підшлях | Ключові експорти | - | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | - | `plugin-sdk/plugin-entry` | `definePluginEntry` | - | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | - | `plugin-sdk/config-schema` | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/testing` | Широкий сумісний barrel для застарілих тестів Plugin; для нових тестів extension віддавайте перевагу сфокусованим тестовим підшляхам | - | `plugin-sdk/plugin-test-api` | Мінімальний конструктор моків `OpenClawPluginApi` для модульних тестів безпосередньої реєстрації Plugin | - | `plugin-sdk/channel-test-helpers` | Допоміжні засоби для тестування життєвого циклу облікових записів каналу, каталогу, send-config, мока runtime, hook і загального контракту каналу | - | `plugin-sdk/channel-target-testing` | Спільний набір тестів випадків помилок визначення цілі каналу | - | `plugin-sdk/plugin-test-contracts` | Допоміжні засоби для контрактів реєстрації Plugin, маніфесту пакета, публічного артефакту, runtime API, побічного ефекту імпорту та прямого імпорту | - | `plugin-sdk/plugin-test-runtime` | Фікстури для тестів runtime Plugin, реєстру, реєстрації provider, майстра налаштування та runtime TaskFlow | - | `plugin-sdk/provider-test-contracts` | Допоміжні засоби для контрактів runtime provider, auth, discovery, onboard, catalog, web-search/fetch і wizard | - | `plugin-sdk/test-env` | Фікстури для тестового середовища, fetch/network, live-test, тимчасової файлової системи та керування часом | - | `plugin-sdk/test-fixtures` | Загальні тестові фікстури для CLI, sandbox, skill, agent-message, system-event, terminal, chunking, auth-token і typed-case | - | `plugin-sdk/migration` | Допоміжні засоби для елементів provider міграції, як-от `createMigrationItem`, константи причин, маркери стану елементів, засоби редагування та `summarizeMigrationItems` | - | `plugin-sdk/migration-runtime` | Допоміжні засоби runtime міграції, як-от `copyMigrationFileItem` і `writeMigrationReport` | + | Підшлях | Ключові експорти | + | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | + | `plugin-sdk/plugin-entry` | `definePluginEntry` | + | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | + | `plugin-sdk/config-schema` | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | + | `plugin-sdk/testing` | Широкий сумісний barrel для застарілих тестів Plugin; для нових тестів extension надавайте перевагу вузькоспрямованим тестовим підшляхам | + | `plugin-sdk/plugin-test-api` | Мінімальний конструктор мока `OpenClawPluginApi` для unit-тестів прямої реєстрації Plugin | + | `plugin-sdk/channel-test-helpers` | Допоміжні засоби для тестів життєвого циклу облікового запису каналу, каталогу, send-config, мока runtime, hook і загального контракту каналу | + | `plugin-sdk/channel-target-testing` | Спільний набір тестів для помилкових сценаріїв визначення цілі каналу | + | `plugin-sdk/plugin-test-contracts` | Допоміжні засоби контрактів для реєстрації Plugin, package manifest, публічного артефакту, runtime API, побічних ефектів імпорту та прямого імпорту | + | `plugin-sdk/plugin-test-runtime` | Фікстури для тестів runtime Plugin, реєстру, реєстрації провайдера, майстра налаштування і runtime TaskFlow | + | `plugin-sdk/provider-test-contracts` | Допоміжні засоби контрактів runtime провайдера, auth, discovery, onboard, catalog, web-search/fetch і майстра | + | `plugin-sdk/test-env` | Фікстури тестового середовища, fetch/network, live-тестів, тимчасової файлової системи та керування часом | + | `plugin-sdk/test-fixtures` | Загальні тестові фікстури для CLI, sandbox, skill, agent-message, system-event, terminal, chunking, auth-token і typed-case | + | `plugin-sdk/migration` | Допоміжні засоби елементів провайдера міграції, як-от `createMigrationItem`, константи причин, маркери статусу елементів, helpers для редагування і `summarizeMigrationItems` | + | `plugin-sdk/migration-runtime` | Допоміжні засоби runtime міграції, як-от `copyMigrationFileItem` і `writeMigrationReport` | - + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | | `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Спільні допоміжні засоби для майстра налаштування, підказок allowlist і побудови стану налаштування | + | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити allowlist, конструктори статусу налаштування | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Допоміжні засоби для багатокористувацької конфігурації/шлюзів дій і резервного використання облікового запису за замовчуванням | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації account-id | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису + резервного використання значення за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку облікових записів/дій з обліковими записами | + | `plugin-sdk/account-core` | Допоміжні засоби багатокористувацької конфігурації/контролю дій і fallback для облікового запису за замовчуванням | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації ідентифікатора облікового запису | + | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису + fallback до значення за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькоспрямовані допоміжні засоби для списку облікових записів/дій з обліковими записами | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу та загальний конструктор | - | `plugin-sdk/bundled-channel-config-schema` | Схеми конфігурації каналу bundled OpenClaw лише для підтримуваних bundled Plugin | - | `plugin-sdk/channel-config-schema-legacy` | Застарілий сумісний псевдонім для bundled-channel config schemas | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною підтримкою bundled-contract | - | `plugin-sdk/command-gating` | Вузькі допоміжні засоби для шлюзів авторизації команд | + | `plugin-sdk/channel-config-schema` | Спільні примітиви схеми конфігурації каналу і загальний конструктор | + | `plugin-sdk/bundled-channel-config-schema` | Вбудовані схеми конфігурації каналів OpenClaw для підтримуваних bundled Plugin | + | `plugin-sdk/channel-config-schema-legacy` | Застарілий сумісний alias для bundled-channel config schemas | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram з fallback до вбудованого контракту | + | `plugin-sdk/command-gating` | Вузькоспрямовані допоміжні засоби контролю авторизації команд | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації потоку чернеток | - | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних даних + побудови envelope | - | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних відповідей | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/завершення draft stream | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних повідомлень і побудови envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису і dispatch для вхідних повідомлень | | `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей | | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа | - | `plugin-sdk/outbound-send-deps` | Полегшений пошук залежностей вихідного надсилання для адаптерів каналу | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідної доставки, ідентифікації, делегата надсилання, сесії, форматування та планування payload | - | `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації poll | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу та адаптера для прив’язок потоків | - | `plugin-sdk/agent-media-payload` | Застарілий конструктор payload медіа агента | - | `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки розмов/потоків, pairing і налаштованих прив’язок | - | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації runtime | + | `plugin-sdk/outbound-send-deps` | Полегшений пошук залежностей надсилання вихідних повідомлень для адаптерів каналів | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби доставки вихідних повідомлень, identity, send delegate, session, форматування та планування payload | + | `plugin-sdk/poll-runtime` | Вузькоспрямовані допоміжні засоби нормалізації poll | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу thread-binding і адаптерів | + | `plugin-sdk/agent-media-payload` | Застарілий конструктор media payload агента | + | `plugin-sdk/conversation-runtime` | Допоміжні засоби conversation/thread binding, pairing і configured-binding | + | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб snapshot конфігурації runtime | | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення group-policy у runtime | - | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку стану каналу | - | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу | + | `plugin-sdk/channel-status` | Спільні допоміжні засоби snapshot/summary стану каналу | + | `plugin-sdk/channel-config-primitives` | Вузькоспрямовані примітиви схеми конфігурації каналу | | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу | | `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти Plugin каналу | | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Спільні допоміжні засоби для рішень щодо group-access | - | `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для прямого DM | + | `plugin-sdk/group-access` | Спільні допоміжні засоби рішень щодо group-access | + | `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для прямих DM | | `plugin-sdk/interactive-runtime` | Допоміжні засоби семантичного представлення повідомлень, доставки та застарілих інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | Сумісний barrel для debounce вхідних даних, зіставлення згадок, допоміжних засобів mention-policy і допоміжних засобів envelope | - | `plugin-sdk/channel-inbound-debounce` | Вузькі допоміжні засоби debounce вхідних даних | - | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби mention-policy, маркерів згадок і тексту згадок без ширшої поверхні inbound runtime | - | `plugin-sdk/channel-envelope` | Вузькі допоміжні засоби форматування вхідного envelope | - | `plugin-sdk/channel-location` | Допоміжні засоби контексту й форматування розташування каналу | - | `plugin-sdk/channel-logging` | Допоміжні засоби журналювання каналу для скидання вхідних даних і збоїв typing/ack | + | `plugin-sdk/channel-inbound` | Сумісний barrel для допоміжних засобів debounce вхідних повідомлень, зіставлення згадок, політики згадок і envelope | + | `plugin-sdk/channel-inbound-debounce` | Вузькоспрямовані допоміжні засоби debounce для вхідних повідомлень | + | `plugin-sdk/channel-mention-gating` | Вузькоспрямовані допоміжні засоби політики згадок, маркерів згадок і тексту згадок без ширшої поверхні inbound runtime | + | `plugin-sdk/channel-envelope` | Вузькоспрямовані допоміжні засоби форматування inbound envelope | + | `plugin-sdk/channel-location` | Допоміжні засоби контексту і форматування розташування каналу | + | `plugin-sdk/channel-logging` | Допоміжні засоби логування каналу для відкинутих вхідних повідомлень і збоїв typing/ack | | `plugin-sdk/channel-send-result` | Типи результатів відповіді | - | `plugin-sdk/channel-actions` | Допоміжні засоби для message-action каналу, а також застарілі допоміжні засоби native schema, збережені для сумісності Plugin | - | `plugin-sdk/channel-route` | Спільні допоміжні засоби нормалізації маршрутів, визначення цілей на основі parser, перетворення thread-id на рядок, dedupe/compact ключів маршруту, типів parsed-target і порівняння маршруту/цілі | - | `plugin-sdk/channel-targets` | Допоміжні засоби розбору цілей; виклики порівняння маршрутів мають використовувати `plugin-sdk/channel-route` | + | `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями каналу, а також застарілі допоміжні засоби native schema, збережені для сумісності Plugin | + | `plugin-sdk/channel-route` | Спільні допоміжні засоби нормалізації маршрутів, визначення цілей на основі parser, перетворення thread-id на рядок, dedupe/compact ключів маршруту, типів parsed-target, а також порівняння маршрутів/цілей | + | `plugin-sdk/channel-targets` | Допоміжні засоби розбору цілей; виклики порівняння маршрутів слід спрямовувати до `plugin-sdk/channel-route` | | `plugin-sdk/channel-contract` | Типи контракту каналу | | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби secret-contract, як-от `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret target | + | `plugin-sdk/channel-secret-runtime` | Вузькоспрямовані допоміжні засоби secret contract, як-от `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret target | - + | Підшлях | Ключові експорти | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/lmstudio` | Підтримуваний фасад provider LM Studio для налаштування, виявлення каталогу та підготовки моделей у runtime | - | `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад runtime LM Studio для локальних типових налаштувань сервера, виявлення моделей, заголовків запитів і допоміжних засобів для завантажених моделей | - | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локального/self-hosted provider | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted provider, сумісного з OpenAI | - | `plugin-sdk/cli-backend` | Типові налаштування backend для CLI + константи watchdog | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-key у runtime для provider Plugin | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-key, як-от `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний конструктор результату auth OAuth | - | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для provider Plugin | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env var для auth provider | + | `plugin-sdk/lmstudio` | Підтримуваний фасад провайдера LM Studio для налаштування, виявлення каталогу та підготовки моделі в runtime | + | `plugin-sdk/lmstudio-runtime` | Підтримуваний фасад runtime LM Studio для типових параметрів локального сервера, виявлення моделей, заголовків запитів і допоміжних засобів для завантажених моделей | + | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted провайдерів | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдерів, сумісних з OpenAI | + | `plugin-sdk/cli-backend` | Типові параметри бекенда CLI + константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключа в runtime для Plugin провайдерів | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-ключа, такі як `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний конструктор результату OAuth auth | + | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для Plugin провайдерів | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку auth env var для провайдерів | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори replay-policy, допоміжні засоби endpoint provider і засоби нормалізації model-id, як-от `normalizeNativeXaiModelId` | - | `plugin-sdk/provider-catalog-runtime` | Хуки runtime каталогу provider і межі реєстру plugin-provider для контрактних тестів | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори replay-policy, допоміжні засоби endpoint провайдера та нормалізації model-id, такі як `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-catalog-runtime` | Хук runtime для розширення каталогу провайдера та межі реєстру plugin-provider для контрактних тестів | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint provider, помилки HTTP provider і допоміжні засоби multipart form для транскрипції аудіо | - | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту config/selection для web-fetch, як-от `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешу provider для web-fetch | - | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби config/credential для web-search для provider, яким не потрібне підключення enable Plugin | - | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту config/credential для web-search, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped-засоби встановлення/отримання credential | - | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешу/runtime provider для web-search | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика і допоміжні засоби сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-http` | Загальні допоміжні засоби можливостей HTTP/endpoint провайдерів, HTTP-помилки провайдерів і допоміжні засоби multipart form для транскрибування аудіо | + | `plugin-sdk/provider-web-fetch-contract` | Вузькоспрямовані допоміжні засоби контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування провайдера web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Вузькоспрямовані допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення увімкнення Plugin | + | `plugin-sdk/provider-web-search-contract` | Вузькоспрямовані допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped сетери/гетери облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime для провайдера web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток stream і спільні допоміжні засоби обгорток для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Власні допоміжні засоби transport provider, як-от guarded fetch, перетворення повідомлень transport і потоки подій transport із можливістю запису | - | `plugin-sdk/provider-onboard` | Допоміжні засоби патчів config для онбордингу | - | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | - | `plugin-sdk/group-activation` | Вузькі допоміжні засоби для режиму активації групи та розбору команд | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні допоміжні засоби wrapper для Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Власні допоміжні засоби transport провайдера, такі як guarded fetch, перетворення повідомлень transport і потоки подій transport із можливістю запису | + | `plugin-sdk/provider-onboard` | Допоміжні засоби внесення змін до конфігурації онбордингу | + | `plugin-sdk/global-singleton` | Допоміжні засоби singleton/map/cache, локальні для процесу | + | `plugin-sdk/group-activation` | Вузькоспрямовані допоміжні засоби режиму активації груп і розбору команд | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, зокрема форматування меню динамічних аргументів, допоміжні засоби авторизації відправника | - | `plugin-sdk/command-status` | Конструктори повідомлень команд/довідки, як-от `buildCommandsMessagePaginated` і `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення схвалювача та auth дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Власні допоміжні засоби профілю/фільтра схвалення exec | - | `plugin-sdk/approval-delivery-runtime` | Власні адаптери можливостей/доставки схвалення | - | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення Gateway схвалення | - | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження власного адаптера схвалення для гарячих точок входу каналу | - | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime обробника схвалення; віддавайте перевагу вужчим межам adapter/gateway, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Власні допоміжні засоби цілі схвалення + прив’язки облікового запису | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді на схвалення exec/Plugin | - | `plugin-sdk/approval-runtime` | Допоміжні засоби payload схвалення exec/Plugin, власні допоміжні засоби маршрутизації/runtime схвалення та допоміжні засоби структурованого відображення схвалення, як-от `formatApprovalDisplayPath` | - | `plugin-sdk/reply-dedupe` | Вузькі допоміжні засоби скидання dedupe для вхідних відповідей | - | `plugin-sdk/channel-contract-testing` | Вузькі допоміжні засоби тестування контракту каналу без широкого тестового barrel | - | `plugin-sdk/command-auth-native` | Власні допоміжні засоби auth команд, форматування меню динамічних аргументів і допоміжні засоби native session-target | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, включно з форматуванням меню динамічних аргументів, допоміжні засоби авторизації відправника | + | `plugin-sdk/command-status` | Конструктори повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення затверджувача та auth дій у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Власні допоміжні засоби профілю/фільтра затвердження exec | + | `plugin-sdk/approval-delivery-runtime` | Власні адаптери можливостей/доставки затвердження | + | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення Gateway затвердження | + | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження власного адаптера затвердження для гарячих entrypoint каналу | + | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime для обробника затвердження; віддавайте перевагу вужчим межам adapter/gateway, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Власні допоміжні засоби цілей затвердження + прив’язки облікових записів | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді для затвердження exec/Plugin | + | `plugin-sdk/approval-runtime` | Допоміжні засоби payload затвердження exec/Plugin, власні допоміжні засоби маршрутизації/runtime затвердження та структурованого відображення затвердження, такі як `formatApprovalDisplayPath` | + | `plugin-sdk/reply-dedupe` | Вузькоспрямовані допоміжні засоби скидання дедуплікації вхідних відповідей | + | `plugin-sdk/channel-contract-testing` | Вузькоспрямовані допоміжні засоби тестування контракту каналу без широкого тестового barrel | + | `plugin-sdk/command-auth-native` | Власні допоміжні засоби auth команд, форматування меню динамічних аргументів і власні допоміжні засоби session-target | | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | | `plugin-sdk/command-primitives-runtime` | Полегшені предикати тексту команд для гарячих шляхів каналу | - | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команди та поверхні команд | + | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команди і command-surface | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь секретів каналу/Plugin | - | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору secret-contract/config | - | `plugin-sdk/security-runtime` | Спільні допоміжні засоби trust, DM gating, external-content, редагування чутливого тексту, порівняння секретів у сталий час і збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж | - | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні infra runtime | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF, помилка SSRF і допоміжні засоби політики SSRF | - | `plugin-sdk/secret-input` | Допоміжні засоби розбору вводу секретів | + | `plugin-sdk/channel-secret-runtime` | Вузькоспрямовані допоміжні засоби збирання secret contract для поверхонь секретів каналу/Plugin | + | `plugin-sdk/secret-ref-runtime` | Вузькоспрямовані допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору secret contract/config | + | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, зовнішнього вмісту, редагування чутливого тексту, порівняння секретів у сталий час і збирання секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби host allowlist і політики SSRF для приватної мережі | + | `plugin-sdk/ssrf-dispatcher` | Вузькоспрямовані pinned-dispatcher helpers без широкої інфраструктурної поверхні runtime | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF, помилок SSRF і політики SSRF | + | `plugin-sdk/secret-input` | Допоміжні засоби розбору secret input | | `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілі Webhook і приведення raw websocket/body | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби для розміру body/timeout запиту | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру body/timeout запиту | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/runtime` | Широкі допоміжні засоби для runtime/журналювання/резервного копіювання/встановлення Plugin | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби для env runtime, logger, timeout, retry і backoff | - | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових налаштувань, розбору URL CDP і допоміжних засобів auth для керування браузером | + | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/логування/резервного копіювання/встановлення Plugin | + | `plugin-sdk/runtime-env` | Вузькоспрямовані допоміжні засоби env runtime, logger, timeout, retry і backoff | + | `plugin-sdk/browser-config` | Підтримуваний фасад конфігурації браузера для нормалізованого профілю/типових параметрів, розбору URL CDP і допоміжних засобів auth керування браузером | | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку runtime-context каналу | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/hook/http/interactive для Plugin | - | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби конвеєра Webhook/внутрішніх hook | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy import/binding для runtime, як-от `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline для Webhook/внутрішніх hook | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy import/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | | `plugin-sdk/process-runtime` | Допоміжні засоби exec процесів | - | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версії, виклику аргументів і lazy груп команд | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта Gateway, CLI RPC Gateway, помилок протоколу Gateway і патчів channel-status | - | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації Plugin, як-от `OpenClawConfig` і типи конфігурації каналу/provider | - | `plugin-sdk/plugin-config-runtime` | Допоміжні засоби пошуку plugin-config у runtime, як-от `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | - | `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної мутації config, як-от `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | - | `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби знімка config поточного процесу, як-от `getRuntimeConfig`, `getRuntimeConfigSnapshot` і тестові сетери знімків | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня bundled-контракту Telegram недоступна | + | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування, версій, виклику аргументів і lazy command-group | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта Gateway, Gateway CLI RPC, помилок протоколу Gateway і внесення змін до статусу каналу | + | `plugin-sdk/config-types` | Поверхня конфігурації лише для типів для форм конфігурації Plugin, таких як `OpenClawConfig` і типи конфігурації каналів/провайдерів | + | `plugin-sdk/plugin-config-runtime` | Допоміжні засоби пошуку plugin-config у runtime, такі як `requireRuntimeConfig`, `resolvePluginConfigObject` і `resolveLivePluginConfigObject` | + | `plugin-sdk/config-mutation` | Допоміжні засоби транзакційної зміни конфігурації, такі як `mutateConfigFile`, `replaceConfigFile` і `logConfigUpdated` | + | `plugin-sdk/runtime-config-snapshot` | Допоміжні засоби snapshot конфігурації поточного процесу, такі як `getRuntimeConfig`, `getRuntimeConfigSnapshot` і сетери test snapshot | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня вбудованого контракту Telegram недоступна | | `plugin-sdk/text-autolink-runtime` | Виявлення autolink посилань на файли без широкого barrel `text-runtime` | - | `plugin-sdk/approval-runtime` | Допоміжні засоби схвалення exec/Plugin, конструктори можливостей схвалення, допоміжні засоби auth/профілів, власні допоміжні засоби маршрутизації/runtime і форматування шляху структурованого відображення схвалення | - | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime для inbound/reply, chunking, dispatch, Heartbeat, планувальник reply | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize для reply і допоміжні засоби міток розмов | - | `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window history reply і маркери, як-от `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/approval-runtime` | Допоміжні засоби затвердження exec/Plugin, конструктори можливостей затвердження, допоміжні засоби auth/профілів, власні допоміжні засоби маршрутизації/runtime і форматування структурованого шляху відображення затвердження | + | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби inbound/reply runtime, chunking, dispatch, Heartbeat, планувальник відповідей | + | `plugin-sdk/reply-dispatch-runtime` | Вузькоспрямовані допоміжні засоби dispatch/finalize відповідей і міток conversation | + | `plugin-sdk/reply-history` | Спільні допоміжні засоби коротковіконної історії відповідей і маркери, такі як `buildHistoryContext`, `HISTORY_CONTEXT_MARKER`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking для тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби для шляху сховища сесій, session-key, updated-at і мутації сховища | - | `plugin-sdk/cron-store-runtime` | Допоміжні засоби для шляху/завантаження/збереження сховища Cron | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів для каталогів стану/OAuth | - | `plugin-sdk/routing` | Допоміжні засоби для маршрутів/session-key/прив’язки облікового запису, як-от `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку стану каналу/облікового запису, типові значення стану runtime і допоміжні засоби метаданих проблем | - | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілі | + | `plugin-sdk/reply-chunking` | Вузькоспрямовані допоміжні засоби chunking тексту/markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища сесій, session-key, updated-at і зміни сховища | + | `plugin-sdk/cron-store-runtime` | Допоміжні засоби шляху/load/save сховища Cron | + | `plugin-sdk/state-paths` | Допоміжні засоби шляхів до каталогів стану/OAuth | + | `plugin-sdk/routing` | Допоміжні засоби route/session-key/account binding, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумків статусу каналу/облікового запису, типових параметрів runtime-state і метаданих issue | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілей | | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків | - | `plugin-sdk/request-url` | Витягування рядкових URL із вхідних даних, подібних до fetch/request | - | `plugin-sdk/run-command` | Запускач команд із таймером і нормалізованими результатами stdout/stderr | - | `plugin-sdk/param-readers` | Загальні зчитувачі параметрів tool/CLI | + | `plugin-sdk/request-url` | Витягування рядкових URL з fetch/request-подібних вхідних даних | + | `plugin-sdk/run-command` | Виконавець команд із таймером і нормалізованими результатами stdout/stderr | + | `plugin-sdk/param-readers` | Типові читачі параметрів tool/CLI | | `plugin-sdk/tool-payload` | Витягування нормалізованих payload з об’єктів результатів tool | | `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів tool | | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів для тимчасових завантажень | - | `plugin-sdk/logging-core` | Допоміжні засоби logger підсистеми та редагування | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму й перетворення таблиць Markdown | - | `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення model/session, як-от `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | - | `plugin-sdk/talk-config-runtime` | Допоміжні засоби визначення конфігурації provider для Talk | - | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON | - | `plugin-sdk/file-lock` | Допоміжні засоби реентерабельного file-lock | - | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу dedupe на диску | - | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/session і reply-dispatch для ACP | - | `plugin-sdk/acp-binding-resolve-runtime` | Визначення прив’язки ACP лише для читання без імпортів запуску життєвого циклу | - | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента | - | `plugin-sdk/boolean-param` | Зчитувач слабко типізованих boolean-параметрів | + | `plugin-sdk/logging-core` | Допоміжні засоби logger підсистеми і редагування | + | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму і перетворення таблиць Markdown | + | `plugin-sdk/model-session-runtime` | Допоміжні засоби перевизначення моделі/сесії, такі як `applyModelOverrideToSessionEntry` і `resolveAgentMaxConcurrent` | + | `plugin-sdk/talk-config-runtime` | Допоміжні засоби визначення конфігурації провайдера talk | + | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON-стану | + | `plugin-sdk/file-lock` | Допоміжні засоби повторно вхідного file-lock | + | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу дедуплікації з дисковим зберіганням | + | `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/сесій ACP і dispatch відповідей | + | `plugin-sdk/acp-binding-resolve-runtime` | Визначення прив’язок ACP лише для читання без імпортів запуску життєвого циклу | + | `plugin-sdk/agent-config-primitives` | Вузькоспрямовані примітиви schema конфігурації runtime агента | + | `plugin-sdk/boolean-param` | Читач булевих параметрів із м’яким приведенням | | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів небезпечних назв | - | `plugin-sdk/device-bootstrap` | Допоміжні засоби початкового налаштування пристрою та токенів pairing | - | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів для passive-channel, статусу й ambient proxy | - | `plugin-sdk/models-provider-runtime` | Допоміжні засоби для відповіді command/provider `/models` | - | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби списку команд skill | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою і токенів pairing | + | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy | + | `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповідей для команди `/models`/провайдера | + | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби переліку команд skill | | `plugin-sdk/native-command-registry` | Власні допоміжні засоби реєстру/побудови/серіалізації команд | - | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness агента: типи harness, допоміжні засоби steer/abort для active-run, допоміжні засоби мосту tool OpenClaw, допоміжні засоби політики tool для runtime-plan, класифікація результатів terminal, допоміжні засоби форматування/деталей прогресу tool і утиліти результатів спроб | - | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI | - | `plugin-sdk/async-lock-runtime` | Допоміжний засіб process-local async lock для невеликих файлів стану runtime | + | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness агента: типи harness, допоміжні засоби steer/abort для active-run, допоміжні засоби bridge tool OpenClaw, допоміжні засоби політики tools runtime-plan, класифікація результатів terminal, допоміжні засоби форматування/деталізації прогресу tools і утиліти результатів спроб | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби визначення endpoint Z.A.I | + | `plugin-sdk/async-lock-runtime` | Допоміжний засіб асинхронного lock, локального для процесу, для невеликих файлів стану runtime | | `plugin-sdk/channel-activity-runtime` | Допоміжний засіб телеметрії активності каналу | | `plugin-sdk/concurrency-runtime` | Допоміжний засіб обмеженої конкурентності асинхронних завдань | - | `plugin-sdk/dedupe-runtime` | Допоміжні засоби кешу dedupe в пам’яті | + | `plugin-sdk/dedupe-runtime` | Допоміжні засоби кешу дедуплікації в пам’яті | | `plugin-sdk/delivery-queue-runtime` | Допоміжний засіб очищення черги очікуваної вихідної доставки | | `plugin-sdk/file-access-runtime` | Допоміжні засоби безпечних шляхів до локальних файлів і джерел медіа | - | `plugin-sdk/heartbeat-runtime` | Допоміжні засоби подій і видимості Heartbeat | + | `plugin-sdk/heartbeat-runtime` | Допоміжні засоби подій Heartbeat і видимості | | `plugin-sdk/number-runtime` | Допоміжний засіб числового приведення | | `plugin-sdk/secure-random-runtime` | Допоміжні засоби безпечних токенів/UUID | | `plugin-sdk/system-event-runtime` | Допоміжні засоби черги системних подій | @@ -240,61 +240,61 @@ x-i18n: | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців, подій і trace-context | | `plugin-sdk/error-runtime` | Допоміжні засоби графа помилок, форматування, спільної класифікації помилок, `isApprovalNotFoundError` | | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy і pinned lookup | - | `plugin-sdk/runtime-fetch` | Fetch runtime з урахуванням dispatcher без імпортів proxy/guarded-fetch | - | `plugin-sdk/response-limit-runtime` | Зчитувач body відповіді з обмеженням без широкої поверхні media runtime | - | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без маршрутизації налаштованих прив’язок або сховищ pairing | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій без широких імпортів запису/обслуговування config | - | `plugin-sdk/context-visibility-runtime` | Допоміжні засоби визначення видимості контексту й фільтрації додаткового контексту без широких імпортів config/security | - | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення та нормалізації примітивних record/рядків без імпортів markdown/logging | + | `plugin-sdk/runtime-fetch` | Runtime fetch з урахуванням dispatcher без імпортів proxy/guarded-fetch | + | `plugin-sdk/response-limit-runtime` | Читач обмеженого body відповіді без широкої поверхні media runtime | + | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки conversation без маршрутизації configured binding або сховищ pairing | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби session-store без широких імпортів запису/обслуговування конфігурації | + | `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту і фільтрація додаткового контексту без широких імпортів config/security | + | `plugin-sdk/string-coerce-runtime` | Вузькоспрямовані допоміжні засоби приведення і нормалізації primitive record/string без імпортів markdown/logging | | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і хоста SCP | - | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і запуску retry | - | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогів/ідентичності/робочого простору агента | - | `plugin-sdk/directory-runtime` | Пошук/усунення дублікатів каталогів на основі config | + | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконавця retry | + | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/робочого простору агента | + | `plugin-sdk/directory-runtime` | Запит/dedup каталогу на основі конфігурації | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також конструктори payload медіа | - | `plugin-sdk/media-store` | Вузькі допоміжні засоби медіасховища, як-от `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибір кандидатів і повідомлення про відсутню модель | - | `plugin-sdk/media-understanding` | Типи provider для розуміння медіа, а також експорти допоміжних засобів для зображень/аудіо, орієнтованих на provider | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби для тексту/markdown/logging, як-от видалення тексту, видимого асистенту, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти безпечного тексту | - | `plugin-sdk/text-chunking` | Допоміжний засіб chunking для вихідного тексту | - | `plugin-sdk/speech` | Типи provider для мовлення, а також експорти допоміжних засобів директив, реєстру, валідації та мовлення, орієнтованих на provider | - | `plugin-sdk/speech-core` | Спільні типи provider для мовлення, а також експорти допоміжних засобів реєстру, директив, нормалізації та мовлення | - | `plugin-sdk/realtime-transcription` | Типи provider для транскрипції в реальному часі, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket | - | `plugin-sdk/realtime-voice` | Типи provider для голосу в реальному часі та допоміжні засоби реєстру | - | `plugin-sdk/image-generation` | Типи provider для генерації зображень | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також конструктори media payload | + | `plugin-sdk/media-store` | Вузькоспрямовані допоміжні засоби media store, такі як `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації медіа, вибору кандидатів і повідомлень про відсутню модель | + | `plugin-sdk/media-understanding` | Типи провайдера розуміння медіа, а також орієнтовані на провайдера експорти допоміжних засобів для зображень/аудіо | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як вилучення тексту, видимого асистенту, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти безпечного тексту | + | `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту | + | `plugin-sdk/speech` | Типи провайдера мовлення, а також орієнтовані на провайдера експорти директив, реєстру, валідації та допоміжних засобів мовлення | + | `plugin-sdk/speech-core` | Спільні типи провайдера мовлення, експорти реєстру, директив, нормалізації та допоміжних засобів мовлення | + | `plugin-sdk/realtime-transcription` | Типи провайдера транскрибування в реальному часі, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket | + | `plugin-sdk/realtime-voice` | Типи провайдера голосу в реальному часі та допоміжні засоби реєстру | + | `plugin-sdk/image-generation` | Типи провайдера генерації зображень | | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і реєстру | - | `plugin-sdk/music-generation` | Типи provider/request/result для генерації музики | - | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук provider і розбір model-ref | - | `plugin-sdk/video-generation` | Типи provider/request/result для генерації відео | - | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук provider і розбір model-ref | + | `plugin-sdk/music-generation` | Типи провайдера/запиту/результату генерації музики | + | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошуку провайдера та розбору model-ref | + | `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео | + | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошуку провайдера та розбору model-ref | | `plugin-sdk/webhook-targets` | Допоміжні засоби реєстру цілей Webhook і встановлення маршрутів | | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook | | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | - | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK | - | `plugin-sdk/testing` | Широкий сумісний barrel для застарілих тестів Plugin. Нові тести extension повинні натомість імпортувати сфокусовані підшляхи SDK, як-от `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/test-env` або `plugin-sdk/test-fixtures` | - | `plugin-sdk/plugin-test-api` | Мінімальний допоміжний засіб `createTestPluginApi` для модульних тестів безпосередньої реєстрації Plugin без імпорту мостів допоміжних засобів тестування репозиторію | - | `plugin-sdk/channel-test-helpers` | Допоміжні засоби тестування, орієнтовані на канали, для загальних контрактів actions/setup/status, перевірок каталогу, життєвого циклу запуску облікового запису, threading send-config, моків runtime, проблем статусу, вихідної доставки та реєстрації hook | - | `plugin-sdk/channel-target-testing` | Спільний набір перевірок випадків помилок визначення цілі для тестів каналу | - | `plugin-sdk/plugin-test-contracts` | Допоміжні засоби контрактів для пакета Plugin, реєстрації, публічного артефакту, прямого імпорту, runtime API та побічних ефектів імпорту | - | `plugin-sdk/provider-test-contracts` | Допоміжні засоби контрактів для runtime provider, auth, discovery, onboard, catalog, wizard, web-search/fetch і stream | - | `plugin-sdk/test-fixtures` | Загальні фікстури для захоплення runtime CLI, контексту sandbox, записувача skill, agent-message, system-event, terminal-text, chunking, auth-token і typed-case | + | `plugin-sdk/zod` | Повторно експортований `zod` для користувачів Plugin SDK | + | `plugin-sdk/testing` | Широкий сумісний barrel для застарілих тестів Plugin. Нові тести extension мають імпортувати натомість вузькоспрямовані підшляхи SDK, як-от `plugin-sdk/plugin-test-runtime`, `plugin-sdk/channel-test-helpers`, `plugin-sdk/test-env` або `plugin-sdk/test-fixtures` | + | `plugin-sdk/plugin-test-api` | Мінімальний допоміжний засіб `createTestPluginApi` для unit-тестів прямої реєстрації Plugin без імпорту мостів допоміжних засобів тестування репозиторію | + | `plugin-sdk/channel-test-helpers` | Допоміжні засоби тестування, орієнтовані на канали, для загальних контрактів actions/setup/status, перевірок каталогу, життєвого циклу запуску облікового запису, зв’язування send-config, mock runtime, проблем статусу, вихідної доставки і реєстрації hook | + | `plugin-sdk/channel-target-testing` | Спільний набір сценаріїв помилок визначення цілі для тестів каналів | + | `plugin-sdk/plugin-test-contracts` | Допоміжні засоби контрактів package Plugin, реєстрації, публічного артефакту, прямого імпорту, runtime API і побічних ефектів імпорту | + | `plugin-sdk/provider-test-contracts` | Допоміжні засоби контрактів runtime провайдера, auth, discovery, onboard, catalog, wizard, web-search/fetch і stream | + | `plugin-sdk/test-fixtures` | Загальні фікстури захоплення runtime CLI, sandbox context, записувача skill, agent-message, system-event, terminal-text, chunking, auth-token і typed-case | | Підшлях | Ключові експорти | | --- | --- | - | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для manager/config/file/CLI | + | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled memory-core для helpers менеджера/конфігурації/файлів/CLI | | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексації/пошуку пам’яті | | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста пам’яті, доступ до реєстру, local provider і загальні допоміжні засоби batch/remote | - | `plugin-sdk/memory-core-host-engine-qmd` | Експорти engine QMD хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-storage` | Експорти engine сховища хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста пам’яті, доступ до реєстру, локальний провайдер і загальні batch/remote helpers | + | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Багатомодальні допоміжні засоби хоста пам’яті | | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | @@ -302,24 +302,24 @@ x-i18n: | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI хоста пам’яті | | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста пам’яті | | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Vendor-neutral псевдонім для допоміжних засобів core runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Vendor-neutral псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Vendor-neutral псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби managed-markdown для Plugin, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до менеджера пошуку | - | `plugin-sdk/memory-host-status` | Vendor-neutral псевдонім для допоміжних засобів статусу хоста пам’яті | + | `plugin-sdk/memory-host-core` | Нейтральний до вендора alias для допоміжних засобів core runtime хоста пам’яті | + | `plugin-sdk/memory-host-events` | Нейтральний до вендора alias для допоміжних засобів журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Нейтральний до вендора alias для допоміжних засобів файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для Plugin, суміжних із пам’яттю | + | `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до search-manager | + | `plugin-sdk/memory-host-status` | Нейтральний до вендора alias для допоміжних засобів статусу хоста пам’яті | | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled memory-lancedb | | Сімейство | Поточні підшляхи | Призначення | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser Plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `browser-support` залишається сумісним barrel. | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних засобів/runtime bundled Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime bundled LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів bundled IRC | - | Допоміжні засоби для конкретних каналів | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі межі сумісності/допоміжних засобів bundled-каналів. Нові Plugin повинні імпортувати загальні підшляхи SDK або локальні barrel Plugin. | - | Допоміжні засоби для auth/специфічних Plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Межі допоміжних засобів bundled-функцій/Plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser Plugin. `browser-profiles` експортує `resolveBrowserConfig`, `resolveProfile`, `ResolvedBrowserConfig`, `ResolvedBrowserProfile` і `ResolvedBrowserTabCleanupConfig` для нормалізованої форми `browser.tabCleanup`. `browser-support` залишається barrel сумісності. | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня bundled helper/runtime для Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня bundled helper/runtime для LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня bundled helper для IRC | + | Допоміжні засоби, специфічні для каналів | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | Застарілі межі сумісності/допоміжних засобів для bundled каналів. Нові Plugin мають імпортувати загальні підшляхи SDK або локальні barrel-файли Plugin. | + | Допоміжні засоби, специфічні для auth/Plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Межі bundled feature/Plugin helper; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |