From ad50d77d93891978e32aa31bc2fb704cd1440b2b Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 24 Apr 2026 16:09:52 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/plugins/architecture-internals.md | 786 +++++++++++----------- docs/uk/plugins/manifest.md | 607 ++++++++--------- 2 files changed, 700 insertions(+), 693 deletions(-) diff --git a/docs/uk/plugins/architecture-internals.md b/docs/uk/plugins/architecture-internals.md index 777502df2..30fee6729 100644 --- a/docs/uk/plugins/architecture-internals.md +++ b/docs/uk/plugins/architecture-internals.md @@ -1,96 +1,96 @@ --- read_when: - Реалізація хуків середовища виконання провайдера, життєвого циклу каналу або пакетних наборів - - Налагодження порядку завантаження plugin або стану реєстру - - Додавання нової можливості plugin або plugin для рушія контексту + - Налагодження порядку завантаження Plugin або стану реєстру + - Додавання нової можливості Plugin або Plugin механізму контексту summary: 'Внутрішні компоненти архітектури Plugin: конвеєр завантаження, реєстр, хуки середовища виконання, HTTP-маршрути та довідкові таблиці' title: Внутрішні компоненти архітектури Plugin x-i18n: - generated_at: "2026-04-24T16:00:13Z" + generated_at: "2026-04-24T16:05:26Z" model: gpt-5.4 provider: openai - source_hash: 10120a0e05be6bb414339e83ed846001cfe31b491bd8ce9a4bcf340d4b8186d5 + source_hash: 19018f885f2a8a5f49d5603e122f8b6c7053e28a27a5ac3a4fd315d2cf9be2ac source_path: plugins/architecture-internals.md workflow: 15 --- -Щоб дізнатися про публічну модель можливостей, форми plugin, а також контракти -власності/виконання, див. [Архітектура Plugin](/uk/plugins/architecture). Ця сторінка — -довідник з внутрішньої механіки: конвеєр завантаження, реєстр, хуки середовища виконання, -HTTP-маршрути Gateway, шляхи імпорту та таблиці схем. +Для публічної моделі можливостей, форм Plugin і контрактів +володіння/виконання див. [Архітектура Plugin](/uk/plugins/architecture). Ця сторінка — +довідник із внутрішньої механіки: конвеєра завантаження, реєстру, хуків середовища виконання, +HTTP-маршрутів Gateway, шляхів імпорту та таблиць схем. ## Конвеєр завантаження -Під час запуску OpenClaw приблизно робить таке: +Під час запуску OpenClaw приблизно виконує таке: -1. виявляє кореневі каталоги потенційних plugin -2. читає маніфести native або сумісних збірок і метадані пакунків -3. відхиляє небезпечні кандидати -4. нормалізує конфігурацію plugin (`plugins.enabled`, `allow`, `deny`, `entries`, +1. виявляє кандидатні корені Plugin +2. зчитує маніфести нативних або сумісних збірок і метадані пакетів +3. відхиляє небезпечних кандидатів +4. нормалізує конфігурацію Plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. визначає, чи ввімкнено кожного кандидата -6. завантажує ввімкнені native-модулі: зібрані вбудовані модулі використовують native-завантажувач; - незібрані native plugin використовують jiti -7. викликає native-хуки `register(api)` і збирає реєстрації до реєстру plugin -8. відкриває реєстр для команд/поверхонь середовища виконання +5. визначає, чи буде ввімкнено кожного кандидата +6. завантажує ввімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач; + незібрані нативні Plugin використовують jiti +7. викликає нативні хуки `register(api)` і збирає реєстрації в реєстр Plugin +8. відкриває реєстр для команд і поверхонь середовища виконання -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це на тому самому етапі. Усі вбудовані plugin використовують `register`; для нових plugin віддавайте перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані Plugin використовують `register`; для нових Plugin надавайте перевагу `register`. Перевірки безпеки відбуваються **до** виконання в середовищі виконання. Кандидати блокуються, -коли точка входу виходить за межі кореня plugin, шлях є доступним для запису всім, або -власник шляху виглядає підозріло для невбудованих plugin. +коли точка входу виходить за межі кореня Plugin, шлях доступний для запису всім, або +власність шляху виглядає підозріло для невбудованих Plugin. -### Поведінка manifest-first +### Поведінка з пріоритетом маніфесту -Маніфест — це джерело істини для площини керування. OpenClaw використовує його, щоб: +Маніфест — це джерело істини для контрольної площини. OpenClaw використовує його, щоб: -- ідентифікувати plugin -- знаходити оголошені канали/Skills/схему конфігурації або можливості збірки +- ідентифікувати Plugin +- виявляти оголошені канали/Skills/схему конфігурації або можливості збірки - перевіряти `plugins.entries..config` -- доповнювати мітки/заповнювачі в Control UI +- доповнювати мітки/заповнювачі інтерфейсу керування - показувати метадані встановлення/каталогу -- зберігати дешеві дескриптори активації та налаштування без завантаження середовища виконання plugin +- зберігати дешеві дескриптори активації та налаштування без завантаження середовища виконання Plugin -Для native plugin модуль середовища виконання є частиною площини даних. Він реєструє -фактичну поведінку, як-от хуки, інструменти, команди або потоки провайдера. +Для нативних Plugin модуль середовища виконання — це частина площини даних. Він реєструє +фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера. -Необов’язкові блоки маніфесту `activation` і `setup` залишаються в площині керування. +Необов’язкові блоки маніфесту `activation` і `setup` залишаються на контрольній площині. Це лише дескриптори метаданих для планування активації та виявлення налаштування; вони не замінюють реєстрацію в середовищі виконання, `register(...)` або `setupEntry`. -Перші споживачі живої активації тепер використовують підказки маніфесту для команд, каналів і провайдерів, -щоб звузити завантаження plugin до ширшої матеріалізації реєстру: +Перші активні споживачі активації тепер використовують підказки маніфесту для команд, каналів і провайдерів, +щоб звузити завантаження Plugin до ширшої матеріалізації реєстру: -- завантаження CLI звужується до plugin, яким належить запитана основна команда -- налаштування каналу/визначення plugin звужується до plugin, яким належить - запитаний ідентифікатор каналу -- явне визначення налаштування/середовища виконання провайдера звужується до plugin, яким належить - запитаний ідентифікатор провайдера +- завантаження CLI звужується до Plugin, яким належить запитана основна команда +- налаштування каналу/визначення Plugin звужується до Plugin, яким належить запитаний + id каналу +- явне визначення налаштування/середовища виконання провайдера звужується до Plugin, яким належить + запитаний id провайдера -Планувальник активації надає і API лише з ідентифікаторами для наявних викликів, і -API плану для нової діагностики. Записи плану повідомляють, чому було вибрано plugin, -відокремлюючи явні підказки планувальника `activation.*` від резервного визначення власності за маніфестом, -як-от `providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і хуки. Це розділення причин є межею сумісності: -наявні метадані plugin продовжують працювати, а новий код може виявляти широкі підказки -або резервну поведінку без зміни семантики завантаження в середовищі виконання. +Планувальник активації надає як API лише з id для наявних викликачів, так і +API плану для нової діагностики. Записи плану повідомляють, чому Plugin було вибрано, +відокремлюючи явні підказки планувальника `activation.*` від резервного визначення власника через маніфест, +такого як `providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і хуки. Це розділення причин — межа сумісності: +наявні метадані Plugin продовжують працювати, тоді як новий код може виявляти широкі підказки +або резервну поведінку без зміни семантики завантаження середовища виконання. -Виявлення налаштування тепер надає перевагу ідентифікаторам, що належать дескрипторам, як-от `setup.providers` і -`setup.cliBackends`, щоб звузити коло кандидатів plugin, перш ніж воно повернеться до -`setup-api` для plugin, яким усе ще потрібні хуки середовища виконання на етапі налаштування. Якщо більше ніж -один виявлений plugin заявляє права на той самий нормалізований ідентифікатор провайдера налаштування -або бекенда CLI, пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на порядок виявлення. +Виявлення налаштування тепер надає перевагу id, що належать дескриптору, таким як `setup.providers` і +`setup.cliBackends`, щоб звузити кандидатні Plugin до того, як воно повернеться до +`setup-api` для Plugin, яким усе ще потрібні хуки середовища виконання на етапі налаштування. Якщо більше ніж +один виявлений Plugin заявляє про той самий нормалізований id провайдера налаштування або CLI backend, +пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на порядок виявлення. ### Що кешує завантажувач -OpenClaw зберігає короткоживучі внутрішньопроцесні кеші для: +OpenClaw зберігає короткочасні внутрішньопроцесні кеші для: - результатів виявлення - даних реєстру маніфестів -- завантажених реєстрів plugin +- завантажених реєстрів Plugin -Ці кеші зменшують стрибкоподібні витрати під час запуску та накладні витрати від повторних команд. Їх безпечно +Ці кеші зменшують стрибкоподібне навантаження під час запуску та повторні накладні витрати команд. Їх безпечно сприймати як короткочасні кеші продуктивності, а не як постійне зберігання. Примітка щодо продуктивності: @@ -102,36 +102,36 @@ OpenClaw зберігає короткоживучі внутрішньопро ## Модель реєстру -Завантажені plugin не змінюють напряму довільні глобальні змінні ядра. Вони реєструються в -центральному реєстрі plugin. +Завантажені Plugin не змінюють безпосередньо довільні глобальні змінні ядра. Вони реєструються в +центральному реєстрі Plugin. Реєстр відстежує: -- записи plugin (ідентичність, джерело, походження, стан, діагностика) +- записи Plugin (ідентичність, джерело, походження, стан, діагностика) - інструменти -- застарілі хуки й типізовані хуки +- застарілі хуки та типізовані хуки - канали -- провайдерів +- провайдери - обробники Gateway RPC - HTTP-маршрути - реєстратори CLI - фонові служби -- команди, що належать plugin +- команди, що належать Plugin -Потім можливості ядра читають із цього реєстру замість того, щоб звертатися до модулів plugin -безпосередньо. Це зберігає односпрямоване завантаження: +Потім можливості ядра зчитують дані з цього реєстру, а не звертаються до модулів Plugin +безпосередньо. Це зберігає односторонність завантаження: -- модуль plugin -> реєстрація в реєстрі -- ядро середовища виконання -> споживання реєстру +- модуль Plugin -> реєстрація в реєстрі +- середовище виконання ядра -> споживання реєстру -Таке розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра потрібна -лише одна точка інтеграції: «читати реєстр», а не «створювати спеціальні випадки для кожного модуля plugin». +Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра потрібна +лише одна точка інтеграції: «зчитати реєстр», а не «робити спеціальну обробку для кожного модуля Plugin». -## Колбеки прив’язування розмови +## Зворотні виклики прив’язки розмови Plugin, які прив’язують розмову, можуть реагувати, коли схвалення вирішено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек після того, як запит на прив’язування буде схвалено або відхилено: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, як запит на прив’язку схвалено або відхилено: ```ts export default { @@ -139,124 +139,124 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // Тепер для цього plugin + розмови існує прив’язування. + // A binding now exists for this plugin + conversation. console.log(event.binding?.conversationId); return; } - // Запит було відхилено; очистьте будь-який локальний стан очікування. + // The request was denied; clear any local pending state. console.log(event.request.conversation.conversationId); }); }, }; ``` -Поля корисного навантаження колбека: +Поля корисного навантаження зворотного виклику: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` -- `binding`: визначене прив’язування для схвалених запитів -- `request`: підсумок початкового запиту, підказка від’єднання, ідентифікатор відправника та +- `binding`: визначена прив’язка для схвалених запитів +- `request`: підсумок початкового запиту, підказка від’єднання, id відправника та метадані розмови -Цей колбек лише сповіщає. Він не змінює те, кому дозволено прив’язувати -розмову, і запускається після завершення обробки схвалення в ядрі. +Цей зворотний виклик призначений лише для сповіщення. Він не змінює, кому дозволено прив’язувати +розмову, і виконується після завершення обробки схвалення ядром. ## Хуки середовища виконання провайдера -Plugin провайдера мають три шари: +Plugin провайдера мають три рівні: -- **Метадані маніфесту** для дешевого пошуку до запуску середовища виконання: `providerAuthEnvVars`, +- **Метадані маніфесту** для дешевого пошуку до етапу середовища виконання: `providerAuthEnvVars`, `providerAuthAliases`, `providerAuthChoices` і `channelEnvVars`. -- **Хуки часу конфігурації**: `catalog` (застаріле `discovery`) плюс +- **Хуки часу конфігурації**: `catalog` (застарілий `discovery`) плюс `applyConfigDefaults`. -- **Хуки середовища виконання**: понад 40 необов’язкових хуків, що охоплюють auth, визначення моделей, - обгортання потоку, рівні thinking, політику повторного відтворення та - кінцеві точки usage. Див. повний список у [Порядок і використання хуків](#hook-order-and-usage). +- **Хуки середовища виконання**: понад 40 необов’язкових хуків, що охоплюють auth, визначення моделі, + обгортання потоку, рівні thinking, політику replay та кінцеві точки usage. Див. + повний список у розділі [Порядок і використання хуків](#hook-order-and-usage). -OpenClaw, як і раніше, володіє загальним циклом агента, failover, обробкою стенограм і -політикою інструментів. Ці хуки є поверхнею розширення для специфічної для провайдера -поведінки без потреби в повністю власному транспорті inference. +OpenClaw, як і раніше, володіє загальним циклом агента, failover, обробкою транскриптів і +політикою інструментів. Ці хуки є поверхнею розширення для поведінки, специфічної для провайдера, +без потреби у повністю спеціальному транспорті inference. -Використовуйте маніфест `providerAuthEnvVars`, коли провайдер має облікові дані на основі env, -які мають бачити загальні шляхи auth/status/model-picker без завантаження середовища виконання plugin. -Використовуйте маніфест `providerAuthAliases`, коли один ідентифікатор провайдера має повторно використовувати env vars, -профілі auth, auth на основі конфігурації та варіант онбордингу API-ключа іншого ідентифікатора провайдера. -Використовуйте маніфест `providerAuthChoices`, коли поверхні CLI онбордингу/вибору auth -мають знати ідентифікатор вибору провайдера, мітки груп і просту прив’язку auth через один прапорець без -завантаження середовища виконання провайдера. Залишайте `envVars` у середовищі виконання провайдера для -операторських підказок, таких як мітки онбордингу або змінні налаштування OAuth -client-id/client-secret. +Використовуйте маніфест `providerAuthEnvVars`, коли провайдер має облікові дані на основі змінних середовища, +які мають бути видимі загальним шляхам auth/status/model-picker без завантаження середовища виконання Plugin. +Використовуйте маніфест `providerAuthAliases`, коли один id провайдера має повторно використовувати +змінні середовища, профілі auth, auth на основі конфігурації та вибір онбордингу API-ключа +іншого id провайдера. Використовуйте маніфест `providerAuthChoices`, коли поверхні CLI для онбордингу/вибору auth +мають знати id вибору провайдера, мітки груп і просту прив’язку auth через один прапорець +без завантаження середовища виконання провайдера. Залишайте `envVars` середовища виконання провайдера для +підказок, орієнтованих на операторів, таких як мітки онбордингу або змінні налаштування +client-id/client-secret для OAuth. -Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування на основі env, -які загальний резервний shell-env, перевірки config/status або підказки налаштування мають бачити +Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування на основі змінних середовища, які +мають бути видимі загальному резервному шляху shell-env, перевіркам config/status або підказкам налаштування без завантаження середовища виконання каналу. ### Порядок і використання хуків -Для plugin моделі/провайдера OpenClaw викликає хуки приблизно в такому порядку. -Стовпець «Коли використовувати» — це короткий посібник для вибору. +Для Plugin моделі/провайдера OpenClaw викликає хуки приблизно в такому порядку. +Стовпець «Коли використовувати» — це короткий довідник для прийняття рішень. -| # | Хук | Що він робить | Коли використовувати | +| # | Хук | Що він робить | Коли використовувати | | --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або базовими значеннями `base URL` | -| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації за замовчуванням, що належать провайдеру, під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей провайдера | -| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку намагається використати звичайний шлях реєстру/каталогу | _(не є хуком plugin)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед канонічним визначенням моделі | -| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для користувацьких ідентифікаторів провайдера в межах того самого сімейства транспорту | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням конфігурації/провайдера в середовищі виконання | Провайдеру потрібне очищення конфігурації, яке має жити разом із plugin; вбудовані допоміжні засоби сімейства Google також страхують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування native streaming-usage до провайдерів конфігурації | Провайдеру потрібні виправлення метаданих native streaming usage, що залежать від кінцевої точки | -| 7 | `resolveConfigApiKey` | Визначає auth env-marker для провайдерів конфігурації перед завантаженням auth у середовищі виконання | Провайдер має власне визначення API-ключа env-marker; `amazon-bedrock` також має тут вбудований резолвер AWS env-marker | -| 8 | `resolveSyntheticAuth` | Відкриває local/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Провайдер може працювати із synthetic/local-маркером облікових даних | -| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth-профілі, що належать провайдеру; типове значення `persistence` — `runtime-only` для облікових даних, що належать CLI/застосунку | Провайдер повторно використовує зовнішні auth-облікові дані без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті | -| 10 | `shouldDeferSyntheticProfileAuth` | Знижує пріоритет збережених synthetic-заповнювачів профілю порівняно з auth на основі env/конфігурації | Провайдер зберігає synthetic-профілі-заповнювачі, які не повинні мати вищий пріоритет | -| 11 | `resolveDynamicModel` | Синхронний резервний шлях для model ids, що належать провайдеру, яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream model ids | -| 12 | `prepareDynamicModel` | Асинхронний розігрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих ids | -| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як вбудований runner використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра | -| 14 | `contributeResolvedModelCompat` | Додає прапорці compat для моделей вендора за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе провайдера | -| 15 | `capabilities` | Метадані стенограми/інструментів, що належать провайдеру, які використовує спільна логіка ядра | Провайдеру потрібні особливості стенограми/сімейства провайдера | -| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований runner | Провайдеру потрібне очищення схем для сімейства транспорту | -| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження про ключові слова без навчання ядра правил, специфічних для провайдера | -| 18 | `resolveReasoningOutputMode` | Вибирає native чи tagged-контракт reasoning-output | Провайдеру потрібен tagged reasoning/final output замість native-полів | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні параметри запиту за замовчуванням або очищення параметрів для кожного провайдера | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдеру потрібен користувацький wire protocol, а не просто обгортка | -| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки заголовків/тіла запиту/сумісності моделі без користувацького транспорту | -| 22 | `resolveTransportTurnState` | Додає native-заголовки транспорту або метадані для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали native-ідентичність ходу провайдера | -| 23 | `resolveWebSocketSessionPolicy` | Додає native-заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або резервну політику | -| 24 | `formatApiKey` | Форматер auth-профілю: збережений профіль стає рядком `apiKey` у середовищі виконання | Провайдер зберігає додаткові auth-метадані й потребує користувацької форми токена в середовищі виконання | -| 25 | `refreshOAuth` | Перевизначення OAuth refresh для користувацьких кінцевих точок оновлення або політики збоїв оновлення | Провайдер не вписується у спільні механізми оновлення `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка з відновлення, що додається, коли OAuth refresh завершується помилкою | Провайдеру потрібні власні рекомендації з відновлення auth після збою оновлення | -| 27 | `matchesContextOverflowError` | Матчер переповнення контекстного вікна, що належить провайдеру | Провайдер має сирі помилки переповнення, які загальні евристики пропустили б | -| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з перевищенням ліміту, перевантаженням тощо | -| 29 | `isCacheTtlEligible` | Політика prompt-cache для провайдерів proxy/backhaul | Провайдеру потрібне керування TTL кешу, специфічне для proxy | -| 30 | `buildMissingAuthMessage` | Замінник загального повідомлення про відновлення при відсутності auth | Провайдеру потрібна підказка відновлення при відсутності auth, специфічна для провайдера | -| 31 | `suppressBuiltInModel` | Приховування застарілої upstream-моделі плюс необов’язкова підказка про помилку для користувача | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх підказкою вендора | -| 32 | `augmentModelCatalog` | Synthetic/фінальні рядки каталогу, додані після виявлення | Провайдеру потрібні synthetic-рядки для прямої сумісності в `models list` і засобах вибору | -| 33 | `resolveThinkingProfile` | Набір рівнів `/think`, мітки відображення та значення за замовчуванням для певної моделі | Провайдер надає користувацьку шкалу thinking або двійкову мітку для вибраних моделей | -| 34 | `isBinaryThinking` | Хук сумісності для перемикача reasoning увімк./вимк. | Провайдер підтримує лише двійковий режим thinking увімк./вимк. | -| 35 | `supportsXHighThinking` | Хук сумісності для підтримки reasoning `xhigh` | Провайдер хоче підтримку `xhigh` лише для підмножини моделей | -| 36 | `resolveDefaultThinkingLevel` | Хук сумісності для рівня `/think` за замовчуванням | Провайдер володіє політикою `/think` за замовчуванням для сімейства моделей | -| 37 | `isModernModelRef` | Матчер modern-model для фільтрів live-профілю та вибору smoke | Провайдер володіє зіставленням бажаної live/smoke-моделі | -| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед inference | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | -| 39 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` і пов’язаних поверхонь стану | Провайдеру потрібен користувацький розбір токена usage/quota або інші облікові дані usage | -| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки usage/quota, специфічні для провайдера, після визначення auth | Провайдеру потрібна кінцева точка usage або парсер корисного навантаження, специфічні для провайдера | -| 41 | `createEmbeddingProvider` | Створює адаптер embedding, що належить провайдеру, для пам’яті/пошуку | Поведінка embedding для пам’яті належить plugin провайдера | -| 42 | `buildReplayPolicy` | Повертає політику replay, що керує обробкою стенограми для провайдера | Провайдеру потрібна користувацька політика стенограми (наприклад, видалення thinking-блоків) | -| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення стенограми | Провайдеру потрібні переписування replay, специфічні для провайдера, понад спільні допоміжні засоби Compaction | -| 44 | `validateReplayTurns` | Остаточна перевірка або переформування ходів replay перед вбудованим runner | Транспорту провайдера потрібна суворіша перевірка ходів після загального очищення | -| 45 | `onModelSelected` | Запускає побічні ефекти після вибору, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | +| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями base URL | +| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму auth, середовища або семантики сімейства моделей провайдера | +| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку намагається використати звичайний шлях реєстру/каталогу | _(не є хуком Plugin)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів перед визначенням канонічної моделі | +| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним складанням моделі | Провайдер володіє очищенням транспорту для користувацьких id провайдера в тому самому сімействі транспорту | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням конфігурації/провайдера в середовищі виконання | Провайдеру потрібне очищення конфігурації, яке має жити разом із Plugin; вбудовані помічники сімейства Google також страхують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-перетворення native streaming-usage до конфігурованих провайдерів | Провайдеру потрібні виправлення метаданих native streaming usage, зумовлені кінцевою точкою | +| 7 | `resolveConfigApiKey` | Визначає auth env-marker для конфігурованих провайдерів перед завантаженням auth у середовищі виконання | Провайдер має власне визначення API-ключа env-marker; `amazon-bedrock` також має тут вбудований AWS env-marker resolver | +| 8 | `resolveSyntheticAuth` | Відкриває local/self-hosted або auth на основі конфігурації без збереження відкритого тексту | Провайдер може працювати із synthetic/local маркером облікових даних | +| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні профілі auth, що належать провайдеру; типове значення `persistence` — `runtime-only` для облікових даних, що належать CLI/app | Провайдер повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token; оголосіть `contracts.externalAuthProviders` у маніфесті | +| 10 | `shouldDeferSyntheticProfileAuth` | Понижує пріоритет збережених synthetic-заповнювачів профілю порівняно з auth на основі env/config | Провайдер зберігає synthetic-профілі-заповнювачі, які не повинні мати вищий пріоритет | +| 11 | `resolveDynamicModel` | Синхронний резервний шлях для model id, що належать провайдеру, яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream model id | +| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | +| 13 | `normalizeResolvedModel` | Остаточне переписування перед тим, як вбудований runner використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра | +| 14 | `contributeResolvedModelCompat` | Додає прапорці compat для моделей постачальника, що працюють через інший сумісний транспорт | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе роль провайдера | +| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру й використовуються спільною логікою ядра | Провайдеру потрібні особливості транскрипту/сімейства провайдера | +| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований runner | Провайдеру потрібне очищення схем для сімейства транспорту | +| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження про ключові слова без додавання до ядра правил, специфічних для провайдера | +| 18 | `resolveReasoningOutputMode` | Вибирає native або tagged-контракт reasoning-output | Провайдеру потрібні tagged reasoning/final output замість native-полів | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками параметрів потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку на користувацький транспорт | Провайдеру потрібен користувацький wire protocol, а не просто обгортка | +| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки заголовків/тіла запиту/сумісності моделі без користувацького транспорту | +| 22 | `resolveTransportTurnState` | Прикріплює native заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали native ідентичність ходу провайдера | +| 23 | `resolveWebSocketSessionPolicy` | Прикріплює native заголовки WebSocket або політику cooldown сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або політику резервного шляху | +| 24 | `formatApiKey` | Форматувальник auth-профілю: збережений профіль стає рядком `apiKey` у середовищі виконання | Провайдер зберігає додаткові метадані auth і потребує користувацької форми токена для середовища виконання | +| 25 | `refreshOAuth` | Перевизначення OAuth refresh для користувацьких кінцевих точок refresh або політики помилок refresh | Провайдер не вписується у спільні refreshers `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка з виправлення, що додається, коли OAuth refresh завершується помилкою | Провайдеру потрібні власні вказівки з відновлення auth після збою refresh | +| 27 | `matchesContextOverflowError` | Засіб зіставлення переповнення вікна контексту, що належить провайдеру | Провайдер має сирі помилки переповнення, які пропустять загальні евристики | +| 28 | `classifyFailoverReason` | Класифікація причин failover, що належить провайдеру | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо | +| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для proxy | +| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення для відсутнього auth | Провайдеру потрібна підказка відновлення для відсутнього auth, специфічна для провайдера | +| 31 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей плюс необов’язкова підказка про помилку для користувача | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх підказкою постачальника | +| 32 | `augmentModelCatalog` | Synthetic/фінальні рядки каталогу, що додаються після виявлення | Провайдеру потрібні synthetic-ряди прямої сумісності в `models list` і засобах вибору | +| 33 | `resolveThinkingProfile` | Набір рівнів `/think`, мітки відображення та типове значення для конкретної моделі | Провайдер надає користувацьку шкалу thinking або бінарну мітку для вибраних моделей | +| 34 | `isBinaryThinking` | Хук сумісності для перемикача reasoning увімкнено/вимкнено | Провайдер надає лише бінарний режим thinking увімкнено/вимкнено | +| 35 | `supportsXHighThinking` | Хук сумісності для підтримки reasoning `xhigh` | Провайдер хоче `xhigh` лише для підмножини моделей | +| 36 | `resolveDefaultThinkingLevel` | Хук сумісності типового рівня `/think` | Провайдер володіє типовою політикою `/think` для сімейства моделей | +| 37 | `isModernModelRef` | Засіб зіставлення modern-model для фільтрів live profile і вибору smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke | +| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний токен/ключ середовища виконання безпосередньо перед inference | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | +| 39 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` і пов’язаних поверхонь стану | Провайдеру потрібен користувацький розбір токена usage/quota або інші облікові дані для usage | +| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки usage/quota, специфічні для провайдера, після визначення auth | Провайдеру потрібна кінцева точка usage або парсер корисного навантаження, специфічні для провайдера | +| 41 | `createEmbeddingProvider` | Створює адаптер embeddings, що належить провайдеру, для memory/search | Поведінка embeddings для memory має належати Plugin провайдера | +| 42 | `buildReplayPolicy` | Повертає політику replay, яка керує обробкою транскрипту для провайдера | Провайдеру потрібна користувацька політика транскрипту (наприклад, видалення блоків thinking) | +| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні переписування replay, специфічні для провайдера, понад спільні помічники Compaction | +| 44 | `validateReplayTurns` | Остаточна перевірка або переформатування ходів replay перед вбудованим runner | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санітизації | +| 45 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -відповідний plugin провайдера, а потім переходять до інших plugin провайдера, що підтримують хуки, -доки один із них фактично не змінить ідентифікатор моделі або transport/config. Це дозволяє -shim провайдера для alias/compat працювати без вимоги, щоб викликач знав, який саме -вбудований plugin володіє переписуванням. Якщо жоден хук провайдера не переписує підтримуваний -запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google усе одно застосовує -це очищення сумісності. +відповідний Plugin провайдера, а потім переходять до інших Plugin провайдерів, що підтримують хуки, +доки один із них фактично не змінить id моделі або транспорт/конфігурацію. Це зберігає +працездатність shim-провайдерів для псевдонімів/compat без потреби для викликача знати, який +вбудований Plugin володіє цим переписуванням. Якщо жоден хук провайдера не перепише підтримуваний +запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно застосує +це compat-очищення. Якщо провайдеру потрібен повністю користувацький wire protocol або користувацький виконавець запитів, -це вже інший клас розширення. Ці хуки призначені для поведінки провайдера, -яка все ще працює в межах звичайного циклу inference OpenClaw. +це вже інший клас розширення. Ці хуки призначені для поведінки провайдера, яка все ще працює +в межах звичайного циклу inference OpenClaw. ### Приклад провайдера @@ -314,27 +314,27 @@ api.registerProvider({ ### Вбудовані приклади -Вбудовані plugin провайдера поєднують наведені вище хуки відповідно до потреб кожного вендора щодо каталогу, -auth, thinking, replay і usage. Авторитетний набір хуків живе разом із -кожним plugin у `extensions/`; ця сторінка ілюструє форми, а не -дзеркалить перелік. +Вбудовані Plugin провайдерів комбінують наведені вище хуки, щоб відповідати потребам кожного постачальника щодо каталогу, +auth, thinking, replay і usage. Авторитетний набір хуків знаходиться разом із +кожним Plugin у `extensions/`; ця сторінка ілюструє форми, а не +віддзеркалює список. - - OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` разом із + + OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` плюс `resolveDynamicModel` / `prepareDynamicModel`, щоб вони могли показувати upstream - model ids раніше за статичний каталог OpenClaw. + id моделей раніше за статичний каталог OpenClaw. GitHub Copilot, Gemini CLI, ChatGPT Codex, MiniMax, Xiaomi, z.ai поєднують `prepareRuntimeAuth` або `formatApiKey` з `resolveUsageAuth` + - `fetchUsageSnapshot`, щоб керувати обміном токенів та інтеграцією `/usage`. + `fetchUsageSnapshot`, щоб володіти обміном токенів та інтеграцією `/usage`. - + Спільні іменовані сімейства (`google-gemini`, `passthrough-gemini`, - `anthropic-by-model`, `hybrid-anthropic-openai`) дають провайдерам змогу підключатися до - політики стенограми через `buildReplayPolicy` замість того, щоб кожен plugin - заново реалізовував очищення. + `anthropic-by-model`, `hybrid-anthropic-openai`) дозволяють провайдерам підключатися до + політики транскриптів через `buildReplayPolicy` замість того, щоб кожен Plugin + повторно реалізовував очищення. `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, @@ -342,8 +342,8 @@ auth, thinking, replay і usage. Авторитетний набір хуків `volcengine` реєструють лише `catalog` і використовують спільний цикл inference. - Beta-заголовки, `/fast` / `serviceTier` і `context1m` живуть усередині - публічного шва `api.ts` / `contract-api.ts` plugin Anthropic + Бета-заголовки, `/fast` / `serviceTier` і `context1m` живуть усередині + публічного шва `api.ts` / `contract-api.ts` Plugin Anthropic (`wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`), а не в загальному SDK. @@ -375,12 +375,12 @@ const voices = await api.runtime.tts.listVoices({ - `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових нотаток. - Використовує конфігурацію ядра `messages.tts` і вибір провайдера. -- Повертає буфер PCM-аудіо + частоту дискретизації. Plugin мають виконувати ресемплінг/кодування для провайдерів. -- `listVoices` є необов’язковим залежно від провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать вендору. -- Списки голосів можуть містити багатші метадані, як-от locale, стать і теги характеру для засобів вибору, обізнаних про провайдера. -- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. +- Повертає PCM audio buffer + sample rate. Plugin мають виконувати ресемплінг/кодування для провайдерів. +- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для засобів вибору голосу або потоків налаштування, що належать постачальнику. +- Списки голосів можуть містити багатші метадані, такі як locale, gender і теги personality для засобів вибору, обізнаних про провайдера. +- OpenAI і ElevenLabs сьогодні підтримують telephony. Microsoft — ні. -Plugin також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. +Plugin також можуть реєструвати мовленнєвих провайдерів через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -400,15 +400,15 @@ api.registerSpeechProvider({ Примітки: -- Політику TTS, fallback і доставку відповіді залишайте в ядрі. -- Використовуйте провайдерів мовлення для поведінки синтезу, що належить вендору. -- Застарілий вхід Microsoft `edge` нормалізується до ідентифікатора провайдера `microsoft`. -- Бажана модель власності — орієнтована на компанію: один plugin вендора може володіти - текстовими, голосовими, графічними та майбутніми медіапровайдерами, коли OpenClaw додаватиме ці +- Зберігайте політику TTS, резервний шлях і доставку відповіді в ядрі. +- Використовуйте мовленнєвих провайдерів для поведінки синтезу, що належить постачальнику. +- Застаріле значення вводу Microsoft `edge` нормалізується до id провайдера `microsoft`. +- Бажана модель володіння орієнтована на компанію: один Plugin постачальника може володіти + текстовими, мовленнєвими, графічними та майбутніми медіапровайдерами в міру того, як OpenClaw додає ці контракти можливостей. -Для розуміння зображень/аудіо/відео plugin реєструють один типізований -провайдер media-understanding замість загального контейнера ключ/значення: +Для розуміння зображень/аудіо/відео Plugin реєструють одного типізованого +провайдера розуміння медіа замість загальної сумки key/value: ```ts api.registerMediaUnderstandingProvider({ @@ -422,16 +422,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Оркестрацію, fallback, конфігурацію та прив’язку каналів залишайте в ядрі. -- Поведінку вендора залишайте в plugin провайдера. +- Зберігайте оркестрацію, резервний шлях, конфігурацію та прив’язку каналів у ядрі. +- Зберігайте поведінку постачальника в Plugin провайдера. - Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові - поля результату, нові необов’язкові можливості. -- Генерація відео вже дотримується тієї ж схеми: + поля результатів, нові необов’язкові можливості. +- Генерація відео вже дотримується того самого шаблону: - ядро володіє контрактом можливості та допоміжним засобом середовища виконання - - plugin вендора реєструють `api.registerVideoGenerationProvider(...)` - - plugin функцій/каналів споживають `api.runtime.videoGeneration.*` + - Plugin постачальників реєструють `api.registerVideoGenerationProvider(...)` + - Plugin можливостей/каналів споживають `api.runtime.videoGeneration.*` -Для допоміжних засобів середовища виконання media-understanding plugin можуть викликати: +Для допоміжних засобів середовища виконання розуміння медіа Plugin можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -446,27 +446,27 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрибування аудіо plugin можуть використовувати або середовище виконання media-understanding, -або старий псевдонім STT: +Для транскрибування аудіо Plugin можуть використовувати або середовище виконання розуміння медіа, +або старіший псевдонім STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Необов’язково, коли MIME неможливо надійно визначити: + // Optional when MIME cannot be inferred reliably: mime: "audio/ogg", }); ``` Примітки: -- `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для +- `api.runtime.mediaUnderstanding.*` є бажаною спільною поверхнею для розуміння зображень/аудіо/відео. -- Використовує аудіоконфігурацію media-understanding ядра (`tools.media.audio`) і порядок fallback провайдера. -- Повертає `{ text: undefined }`, коли вихід транскрибування не створено (наприклад, вхід пропущено/не підтримується). -- `api.runtime.stt.transcribeAudioFile(...)` залишається як псевдонім сумісності. +- Використовує конфігурацію аудіо розуміння медіа ядра (`tools.media.audio`) і порядок резервних провайдерів. +- Повертає `{ text: undefined }`, коли вивід транскрибування не створено (наприклад, для пропущеного/непідтримуваного вводу). +- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності. -Plugin також можуть запускати фонові запуски субагента через `api.runtime.subagent`: +Plugin також можуть запускати фонові виконання subagent через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -482,12 +482,12 @@ const result = await api.runtime.subagent.run({ - `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. - OpenClaw враховує ці поля перевизначення лише для довірених викликачів. -- Для fallback-запусків, що належать plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugin конкретними канонічними цілями `provider/model`, або `"*"` для явного дозволу будь-якої цілі. -- Запуски субагента від недовірених plugin усе ще працюють, але запити на перевизначення відхиляються замість тихого переходу на fallback. +- Для резервних запусків, що належать Plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені Plugin конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. +- Запуски subagent для недовірених Plugin також працюють, але запити на перевизначення відхиляються, а не тихо переходять на резервний шлях. -Для вебпошуку plugin можуть використовувати спільний допоміжний засіб середовища виконання замість -звернення до прив’язки інструмента агента: +Для вебпошуку Plugin можуть використовувати спільний допоміжний засіб середовища виконання замість +звернення до прив’язки інструментів агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -508,9 +508,9 @@ Plugin також можуть реєструвати провайдерів в Примітки: -- Вибір провайдера, визначення облікових даних і спільну семантику запитів залишайте в ядрі. -- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для вендора. -- `api.runtime.webSearch.*` — це бажана спільна поверхня для plugin функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструмента агента. +- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у ядрі. +- Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для постачальника. +- `api.runtime.webSearch.*` є бажаною спільною поверхнею для Plugin можливостей/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструментів агента. ### `api.runtime.imageGeneration` @@ -525,8 +525,8 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. -- `listProviders(...)`: перелічує доступних провайдерів генерації зображень і їхні можливості. +- `generate(...)`: згенерувати зображення, використовуючи налаштований ланцюжок провайдерів генерації зображень. +- `listProviders(...)`: вивести список доступних провайдерів генерації зображень і їхніх можливостей. ## HTTP-маршрути Gateway @@ -548,123 +548,124 @@ api.registerHttpRoute({ Поля маршруту: - `path`: шлях маршруту під HTTP-сервером gateway. -- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайний auth Gateway, або `"plugin"` для auth/перевірки Webhook, якими керує plugin. -- `match`: необов’язкове поле. `"exact"` (типово) або `"prefix"`. -- `replaceExisting`: необов’язкове поле. Дозволяє тому самому plugin замінити власну наявну реєстрацію маршруту. -- `handler`: поверніть `true`, коли маршрут обробив запит. +- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайний auth Gateway, або `"plugin"` для auth/webhook verification, якими керує Plugin. +- `match`: необов’язкове поле. `"exact"` (типове значення) або `"prefix"`. +- `replaceExisting`: необов’язкове поле. Дозволяє тому самому Plugin замінити власну наявну реєстрацію маршруту. +- `handler`: повертайте `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` було видалено, і воно спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`. -- Маршрути plugin мають явно оголошувати `auth`. -- Конфлікти точного `path + match` відхиляються, якщо не встановлено `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin. -- Маршрути, що перекриваються та мають різні рівні `auth`, відхиляються. Ланцюжки fallthrough для `exact`/`prefix` тримайте лише в межах одного рівня auth. -- Маршрути `auth: "plugin"` **не** отримують автоматично операторські області середовища виконання. Вони призначені для Webhook/перевірки підпису, якими керує plugin, а не для привілейованих допоміжних викликів Gateway. -- Маршрути `auth: "gateway"` виконуються в межах області середовища виконання запиту Gateway, але ця область навмисно консервативна: - - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області середовища виконання маршруту plugin на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` - - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` на приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту plugin з ідентичністю, область середовища виконання повертається до `operator.write` -- Практичне правило: не припускайте, що маршрут plugin з gateway-auth є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. +- `api.registerHttpHandler(...)` було видалено і воно спричинить помилку завантаження Plugin. Натомість використовуйте `api.registerHttpRoute(...)`. +- Маршрути Plugin повинні явно оголошувати `auth`. +- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один Plugin не може замінити маршрут іншого Plugin. +- Маршрути, що перекриваються, з різними рівнями `auth` відхиляються. Залишайте ланцюги переходу `exact`/`prefix` лише в межах одного рівня auth. +- Маршрути `auth: "plugin"` **не** отримують автоматично області runtime оператора. Вони призначені для webhook/signature verification, якими керує Plugin, а не для привілейованих допоміжних викликів Gateway. +- Маршрути `auth: "gateway"` працюють усередині області runtime запиту Gateway, але ця область навмисно консервативна: + - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує області runtime маршрутів Plugin зафіксованими на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` + - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` у приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах маршрутів Plugin з ідентичністю, область runtime повертається до `operator.write` +- Практичне правило: не припускайте, що маршрут Plugin з gateway-auth є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK Використовуйте вузькі підшляхи SDK замість монолітного кореневого -barrel `openclaw/plugin-sdk`, коли створюєте нові plugin. Основні підшляхи: +barrel `openclaw/plugin-sdk` під час створення нових Plugin. Основні підшляхи: -| Підшлях | Призначення | -| ---------------------------------- | -------------------------------------------------- | -| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації plugin | -| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/побудови каналу | -| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella contract | -| `openclaw/plugin-sdk/config-schema` | Коренева схема Zod для `openclaw.json` (`OpenClawSchema`) | +| Підшлях | Призначення | +| ----------------------------------- | -------------------------------------------------- | +| `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin | +| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/побудови каналу | +| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella contract | +| `openclaw/plugin-sdk/config-schema` | Коренева Zod-схема `openclaw.json` (`OpenClawSchema`) | Plugin каналів обирають із сімейства вузьких швів — `channel-setup`, `setup-runtime`, `setup-adapter-runtime`, `setup-tools`, `channel-pairing`, `channel-contract`, `channel-feedback`, `channel-inbound`, `channel-lifecycle`, `channel-reply-pipeline`, `command-auth`, `secret-input`, `webhook-ingress`, -`channel-targets` і `channel-actions`. Поведінку схвалення слід консолідувати -в межах одного контракту `approvalCapability`, а не змішувати між не пов’язаними -полями plugin. Див. [Plugin каналів](/uk/plugins/sdk-channel-plugins). +`channel-targets` і `channel-actions`. Поведінка схвалення має консолідуватися +навколо одного контракту `approvalCapability`, а не змішуватися між +непов’язаними полями Plugin. Див. [Plugin каналів](/uk/plugins/sdk-channel-plugins). -Допоміжні засоби середовища виконання та конфігурації розміщуються у відповідних підшляхах -`*-runtime` (`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`, +Допоміжні засоби середовища виконання й конфігурації розміщено у відповідних підшляхах +`*-runtime` +(`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`, `lazy-runtime`, `directory-runtime`, `text-runtime`, `runtime-store` тощо). `openclaw/plugin-sdk/channel-runtime` застарів — це shim сумісності для -старіших plugin. Новий код має імпортувати вужчі загальні примітиви. +старіших Plugin. Новий код має імпортувати вужчі загальні примітиви. -Внутрішні для репозиторію точки входу (для кореня кожного пакунка вбудованого plugin): +Внутрішні точки входу репозиторію (для кореня пакета кожного вбудованого Plugin): -- `index.js` — точка входу вбудованого plugin +- `index.js` — точка входу вбудованого Plugin - `api.js` — barrel допоміжних засобів/типів - `runtime-api.js` — barrel лише для середовища виконання -- `setup-entry.js` — точка входу plugin налаштування +- `setup-entry.js` — точка входу Plugin налаштування -Зовнішні plugin повинні імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи -не імпортуйте `src/*` іншого пакунка plugin з ядра або з іншого plugin. -Точки входу, завантажені через facade, віддають перевагу активному знімку конфігурації середовища виконання, якщо він існує, -а потім повертаються до визначеного файлу конфігурації на диску. +Зовнішні Plugin мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи +не імпортуйте `src/*` іншого пакета Plugin із ядра або з іншого Plugin. +Точки входу, завантажені через facade, надають перевагу активному знімку конфігурації середовища виконання, якщо він існує, +а інакше повертаються до визначеного файла конфігурації на диску. -Підшляхи, специфічні для можливостей, як-от `image-generation`, `media-understanding` -і `speech`, існують, оскільки вбудовані plugin використовують їх уже сьогодні. Вони не є -автоматично зовнішніми контрактами, замороженими на довгий термін — перевіряйте відповідну -довідкову сторінку SDK, коли покладаєтеся на них. +Підшляхи, специфічні для можливостей, такі як `image-generation`, `media-understanding` +і `speech`, існують, бо вбудовані Plugin використовують їх уже сьогодні. Вони не є +автоматично довгостроково замороженими зовнішніми контрактами — перевіряйте відповідну сторінку +довідника SDK, коли покладаєтеся на них. ## Схеми інструментів повідомлень -Plugin повинні володіти внесками схем `describeMessageTool(...)`, специфічними для каналу, -для немеседжевих примітивів, таких як реакції, прочитання та опитування. +Plugin мають володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу, +для немеседжевих примітивів, таких як reactions, reads і polls. Спільне представлення надсилання має використовувати загальний контракт `MessagePresentation` -замість native-полів кнопок, компонентів, блоків або карток, специфічних для провайдера. +замість нативних для провайдера полів button, component, block або card. Див. [Message Presentation](/uk/plugins/message-presentation), щоб ознайомитися з контрактом, -правилами fallback, мапінгом провайдерів і контрольним списком для авторів plugin. +правилами резервного шляху, зіставленням провайдерів і контрольним списком для авторів Plugin. -Plugin, здатні надсилати, оголошують, що вони можуть рендерити, через можливості повідомлень: +Plugin, що підтримують надсилання, оголошують, що саме вони можуть відображати, через можливості повідомлень: -- `presentation` для блоків семантичного представлення (`text`, `context`, `divider`, `buttons`, `select`) -- `delivery-pin` для запитів на закріплену доставку +- `presentation` для семантичних блоків представлення (`text`, `context`, `divider`, `buttons`, `select`) +- `delivery-pin` для запитів закріпленої доставки -Ядро вирішує, чи рендерити представлення native-способом, чи деградувати його до тексту. -Не відкривайте native-обхідні шляхи UI, специфічні для провайдера, із загального -інструмента повідомлень. Застарілі допоміжні засоби SDK для старих native-схем і надалі експортуються для наявних -сторонніх plugin, але нові plugin не повинні їх використовувати. +Ядро вирішує, чи відображати представлення нативно, чи деградувати його до тексту. +Не відкривайте шляхи обходу до нативного UI провайдера з загального інструмента повідомлень. +Застарілі допоміжні засоби SDK для старих нативних схем усе ще експортуються для наявних +сторонніх Plugin, але нові Plugin не повинні їх використовувати. ## Визначення цілі каналу -Plugin каналів повинні володіти семантикою цілей, специфічною для каналу. Залишайте спільний -вихідний host загальним і використовуйте поверхню адаптера повідомлень для правил провайдера: +Plugin каналів мають володіти семантикою цілей, специфічною для каналу. Зберігайте спільний +вихідний хост загальним і використовуйте поверхню messaging adapter для правил провайдера: -- `messaging.inferTargetChatType({ to })` визначає, чи слід нормалізовану ціль - трактувати як `direct`, `group` або `channel` до пошуку в каталозі. +- `messaging.inferTargetChatType({ to })` визначає, чи нормалізовану ціль + слід трактувати як `direct`, `group` або `channel` до пошуку в каталозі. - `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи - слід для введення відразу переходити до визначення в стилі id, а не до пошуку в каталозі. -- `messaging.targetResolver.resolveTarget(...)` — це резервний шлях plugin, коли + слід вводу одразу переходити до визначення як id-подібного значення замість пошуку в каталозі. +- `messaging.targetResolver.resolveTarget(...)` — це резервний шлях Plugin, коли ядру потрібне остаточне визначення, що належить провайдеру, після нормалізації або після - промаху в каталозі. -- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, специфічного для провайдера, - щойно ціль визначено. + відсутності збігу в каталозі. +- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту + вихідної сесії, специфічною для провайдера, щойно ціль визначено. -Рекомендований поділ: +Рекомендоване розділення: -- Використовуйте `inferTargetChatType` для рішень за категоріями, які мають відбуватися до - пошуку серед peer/group. -- Використовуйте `looksLikeId` для перевірок на кшталт «трактувати це як явний/native target id». +- Використовуйте `inferTargetChatType` для категоріальних рішень, які мають відбуватися до + пошуку peer/group. +- Використовуйте `looksLikeId` для перевірок на кшталт «трактувати це як явний/нативний id цілі». - Використовуйте `resolveTarget` для резервної нормалізації, специфічної для провайдера, а не для широкого пошуку в каталозі. -- Зберігайте native ids провайдера, як-от chat ids, thread ids, JIDs, handles і room - ids, усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK. +- Зберігайте нативні id провайдера, такі як chat id, thread id, JID, handle і room + id, усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK. ## Каталоги на основі конфігурації -Plugin, які виводять записи каталогу з конфігурації, повинні залишати цю логіку в -plugin і повторно використовувати спільні допоміжні засоби з +Plugin, які формують записи каталогу з конфігурації, мають тримати цю логіку в +Plugin і повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. Використовуйте це, коли каналу потрібні peers/groups на основі конфігурації, наприклад: -- DM peers на основі allowlist +- DM peers, що керуються allowlist - налаштовані мапи channel/group - статичні резервні каталоги в межах облікового запису @@ -675,12 +676,12 @@ plugin і повторно використовувати спільні доп - допоміжні засоби дедуплікації/нормалізації - побудову `ChannelDirectoryEntry[]` -Перевірка облікового запису та нормалізація id, специфічні для каналу, мають залишатися -в реалізації plugin. +Інспекція облікового запису й нормалізація id, специфічні для каналу, мають залишатися в +реалізації Plugin. ## Каталоги провайдерів -Plugin провайдера можуть визначати каталоги моделей для inference за допомогою +Plugin провайдерів можуть визначати каталоги моделей для inference за допомогою `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в @@ -689,38 +690,38 @@ Plugin провайдера можуть визначати каталоги м - `{ provider }` для одного запису провайдера - `{ providers }` для кількох записів провайдера -Використовуйте `catalog`, коли plugin володіє model ids, специфічними для провайдера, типовими -значеннями base URL або метаданими моделей, захищеними auth. +Використовуйте `catalog`, коли Plugin володіє model id, специфічними для провайдера, типовими +значеннями base URL або метаданими моделей, що залежать від auth. -`catalog.order` керує тим, коли каталог plugin об’єднується відносно -вбудованих неявних провайдерів OpenClaw: +`catalog.order` керує тим, коли каталог Plugin зливається відносно вбудованих +неявних провайдерів OpenClaw: -- `simple`: звичайні провайдери на основі API-ключа або env -- `profile`: провайдери, що з’являються, коли існують профілі auth +- `simple`: прості провайдери на основі API-ключа або env +- `profile`: провайдери, які з’являються за наявності профілів auth - `paired`: провайдери, які синтезують кілька пов’язаних записів провайдера -- `late`: останній прохід після інших неявних провайдерів +- `late`: останній прохід, після інших неявних провайдерів -Пізніші провайдери перемагають у разі конфлікту ключів, тому plugin можуть навмисно -перевизначати вбудований запис провайдера з тим самим ідентифікатором провайдера. +Пізніші провайдери перемагають у разі колізії ключів, тож Plugin можуть навмисно перевизначати +вбудований запис провайдера з тим самим id провайдера. Сумісність: - `discovery` усе ще працює як застарілий псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` -## Інспекція каналу лише для читання +## Лише для читання: інспекція каналу -Якщо ваш plugin реєструє канал, віддавайте перевагу реалізації -`plugin.config.inspectAccount(cfg, accountId)` поряд із `resolveAccount(...)`. +Якщо ваш Plugin реєструє канал, надавайте перевагу реалізації +`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`. Чому: - `resolveAccount(...)` — це шлях середовища виконання. Він може припускати, що облікові дані - повністю матеріалізовані, і швидко завершуватися помилкою, коли потрібні секрети відсутні. -- Шляхи команд лише для читання, як-от `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve` і потоки відновлення doctor/config, - не повинні вимагати матеріалізації облікових даних середовища виконання лише для - опису конфігурації. + повністю матеріалізовані, і швидко завершуватися помилкою, коли потрібних секретів бракує. +- Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`, + `openclaw channels status`, `openclaw channels resolve` і потоки + repair для doctor/config не повинні вимагати матеріалізації облікових даних середовища виконання лише для того, + щоб описати конфігурацію. Рекомендована поведінка `inspectAccount(...)`: @@ -731,15 +732,17 @@ Plugin провайдера можуть визначати каталоги м - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Вам не потрібно повертати сирі значення токенів лише для повідомлення про доступність у режимі тільки читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела). +- Вам не потрібно повертати сирі значення токенів лише для звіту про доступність + лише для читання. Повернути `tokenStatus: "available"` (і відповідне поле джерела) + достатньо для команд у стилі status. - Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але вони недоступні в поточному шляху команди. -Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. +Це дозволяє командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» замість аварійного завершення або помилкового повідомлення, що обліковий запис не налаштовано. ## Пакетні набори -Каталог plugin може містити `package.json` із `openclaw.extensions`: +Каталог Plugin може містити `package.json` з `openclaw.extensions`: ```json { @@ -751,45 +754,44 @@ Plugin провайдера можуть визначати каталоги м } ``` -Кожен запис стає plugin. Якщо пакетний набір містить кілька extensions, ідентифікатор plugin +Кожен запис стає Plugin. Якщо набір містить кілька extensions, id Plugin стає `name/`. -Якщо ваш plugin імпортує npm-залежності, установіть їх у цьому каталозі, щоб +Якщо ваш Plugin імпортує npm-залежності, встановіть їх у цьому каталозі, щоб `node_modules` був доступний (`npm install` / `pnpm install`). -Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу plugin -після визначення symlink. Записи, що виходять за межі каталогу пакунка, +Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися всередині каталогу Plugin +після визначення symlink. Записи, що виходять за межі каталогу пакета, відхиляються. -Примітка щодо безпеки: `openclaw plugins install` установлює залежності plugin за допомогою -`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей у середовищі виконання). Зберігайте дерева залежностей plugin -«чистими JS/TS» й уникайте пакунків, які потребують збирання через `postinstall`. +Примітка щодо безпеки: `openclaw plugins install` встановлює залежності Plugin за допомогою +`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей у середовищі виконання). Тримайте дерева залежностей Plugin «чистими JS/TS» і уникайте пакетів, які вимагають збірок `postinstall`. Необов’язково: `openclaw.setupEntry` може вказувати на полегшений модуль лише для налаштування. -Коли OpenClaw потребує поверхонь налаштування для вимкненого plugin каналу, або -коли plugin каналу ввімкнено, але ще не налаштовано, він завантажує `setupEntry` -замість повної точки входу plugin. Це робить запуск і налаштування легшими, -коли основна точка входу plugin також підключає інструменти, хуки чи інший код, -призначений лише для середовища виконання. +Коли OpenClaw потребує поверхонь налаштування для вимкненого Plugin каналу, або +коли Plugin каналу ввімкнено, але він усе ще не налаштований, він завантажує `setupEntry` +замість повної точки входу Plugin. Це робить запуск і налаштування легшими, +коли основна точка входу Plugin також підключає інструменти, хуки або інший код +лише для середовища виконання. Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести plugin каналу на той самий шлях `setupEntry` під час -фази запуску gateway до `listen`, навіть якщо канал уже налаштовано. +може підключити Plugin каналу до того самого шляху `setupEntry` під час +передслухового етапу запуску gateway, навіть якщо канал уже налаштований. Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати -до того, як gateway почне слухати. На практиці це означає, що запис налаштування -має зареєструвати кожну можливість, що належить каналу, від якої залежить запуск, наприклад: +до того, як gateway почне слухати. На практиці це означає, що точка входу налаштування +має реєструвати кожну можливість, що належить каналу та від якої залежить запуск, наприклад: - саму реєстрацію каналу - будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне слухати -- будь-які методи gateway, інструменти чи служби, які мають існувати впродовж того самого вікна +- будь-які методи gateway, інструменти або служби, які мають існувати в це саме вікно Якщо ваша повна точка входу все ще володіє будь-якою потрібною можливістю запуску, не вмикайте -цей прапорець. Залиште plugin на типовій поведінці й дозвольте OpenClaw завантажити +цей прапорець. Залиште Plugin на типовій поведінці й дозвольте OpenClaw завантажити повну точку входу під час запуску. -Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, з якими ядро -може консультуватися до завантаження повного середовища виконання каналу. Поточна поверхня +Вбудовані канали також можуть публікувати допоміжні засоби контрактної поверхні лише для налаштування, з якими ядро +може звірятися до завантаження повного середовища виконання каналу. Поточна поверхня просування налаштування така: - `singleAccountKeysToMove` @@ -797,20 +799,20 @@ Plugin провайдера можуть визначати каталоги м - `resolveSingleAccountPromotionTarget(...)` Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію каналу з одним обліковим записом -у `channels..accounts.*` без завантаження повної точки входу plugin. -Matrix — поточний вбудований приклад: він переносить лише ключі auth/bootstrap до -іменованого просунутого облікового запису, коли іменовані облікові записи вже існують, і може -зберігати налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати +у `channels..accounts.*` без завантаження повної точки входу Plugin. +Matrix — поточний вбудований приклад: він переміщує лише ключі auth/bootstrap у +іменований просунутий обліковий запис, коли іменовані облікові записи вже існують, і може зберегти +налаштований неканонічний ключ default-account замість того, щоб завжди створювати `accounts.default`. -Ці адаптери патчів налаштування підтримують ледаче виявлення поверхні контракту вбудованого коду. Час -імпорту залишається малим; поверхня просування завантажується лише під час першого використання, замість +Ці адаптери латок налаштування зберігають ліниве виявлення контрактної поверхні вбудованих компонентів. Час +імпорту залишається легким; поверхня просування завантажується лише за першої потреби, замість повторного входу в запуск вбудованого каналу під час імпорту модуля. -Коли ці поверхні запуску включають методи Gateway RPC, зберігайте їх у -префіксі, специфічному для plugin. Простори імен адміністратора ядра (`config.*`, +Коли ці поверхні запуску включають методи Gateway RPC, тримайте їх на +префіксі, специфічному для Plugin. Простори імен адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються -як `operator.admin`, навіть якщо plugin запитує вужчу область. +як `operator.admin`, навіть якщо Plugin запитує вужчу область. Приклад: @@ -827,10 +829,10 @@ Matrix — поточний вбудований приклад: він пере } ``` -### Метадані каталогу каналу +### Метадані каталогу каналів Plugin каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і -підказки встановлення через `openclaw.install`. Це дозволяє ядру не містити даних каталогу. +підказки встановлення через `openclaw.install`. Це дозволяє ядру залишатися без даних каталогу. Приклад: @@ -845,7 +847,7 @@ Plugin каналів можуть оголошувати метадані на "selectionLabel": "Nextcloud Talk (self-hosted)", "docsPath": "/channels/nextcloud-talk", "docsLabel": "nextcloud-talk", - "blurb": "Self-hosted чат через Webhook-ботів Nextcloud Talk.", + "blurb": "Самостійно розміщений чат через webhook-ботів Nextcloud Talk.", "order": 65, "aliases": ["nc-talk", "nc"] }, @@ -858,62 +860,64 @@ Plugin каналів можуть оголошувати метадані на } ``` -Корисні поля `openclaw.channel` понад мінімальний приклад: +Корисні поля `openclaw.channel`, окрім мінімального прикладу: - `detailLabel`: вторинна мітка для багатших поверхонь каталогу/стану - `docsLabel`: перевизначення тексту посилання для посилання на документацію -- `preferOver`: ідентифікатори plugin/каналів нижчого пріоритету, які цей запис каталогу має випереджати +- `preferOver`: id Plugin/каналів нижчого пріоритету, які цей запис каталогу має випереджати - `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом для поверхонь вибору -- `markdownCapable`: позначає канал як здатний працювати з markdown для рішень щодо вихідного форматування +- `markdownCapable`: позначає канал як здатний до markdown для рішень щодо вихідного форматування - `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` - `exposure.setup`: приховує канал з інтерактивних засобів вибору налаштування/конфігурації, якщо встановлено `false` - `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації -- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure` +- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; надавайте перевагу `exposure` - `quickstartAllowFrom`: підключає канал до стандартного потоку quickstart `allowFrom` -- `forceAccountBinding`: вимагає явного прив’язування облікового запису, навіть коли існує лише один обліковий запис -- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення цілей announce +- `forceAccountBinding`: вимагає явної прив’язки облікового запису, навіть якщо існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення announce target -OpenClaw також може об’єднувати **зовнішні каталоги каналів** (наприклад, експорт -реєстру MPM). Помістіть JSON-файл в один із таких шляхів: +OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт +реєстру MPM). Помістіть JSON-файл в одне з таких місць: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на -один чи кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл має +один або кілька JSON-файлів (розділених комою/крапкою з комою/`PATH`). Кожен файл має містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів відкривають нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Ці -нормалізовані факти визначають, чи є npm spec точною версією чи плаваючим -селектором, чи присутні очікувані метадані цілісності, і чи доступний також -локальний шлях джерела. Вони також попереджають, коли `defaultChoice` є недійсним -або вказує на джерело, яке недоступне. Споживачі повинні трактувати -`installSource` як додаткове необов’язкове поле, щоб старі записи, створені вручну, і -shim сумісності не мусили синтезувати його. Це дозволяє онбордингу та -діагностиці пояснювати стан площини джерела без імпорту середовища виконання plugin. +нормалізовані факти визначають, чи є npm spec точною версією або плаваючим +селектором, чи присутні очікувані метадані цілісності, а також чи доступний +локальний вихідний шлях. Вони також попереджають, коли `defaultChoice` недійсний +або вказує на недоступне джерело, і коли метадані цілісності npm присутні +без дійсного npm-джерела. Споживачі мають трактувати `installSource` як +адитивне необов’язкове поле, щоб старіші вручну зібрані записи й shim сумісності +не мусили його синтезувати. Це дозволяє онбордингу та діагностиці пояснювати +стан площини джерел без імпорту середовища виконання Plugin. -Офіційні зовнішні записи npm мають віддавати перевагу точному `npmSpec` разом із -`expectedIntegrity`. Прості назви пакунків і dist-tag все ще працюють для -сумісності, але вони показують попередження площини джерела, щоб каталог міг рухатися -в бік pin-встановлень із перевіркою цілісності без ламання наявних plugin. -Коли онбординг установлює з локального шляху каталогу, він записує запис -`plugins.installs` із `source: "path"` і `sourcePath`, відносним до workspace, +Офіційні зовнішні npm-записи мають надавати перевагу точному `npmSpec` плюс +`expectedIntegrity`. Прості назви пакетів і dist-tag усе ще працюють для +сумісності, але вони створюють попередження площини джерел, щоб каталог міг +рухатися до зафіксованих установлень із перевіркою цілісності без порушення +роботи наявних Plugin. Коли онбординг виконує встановлення з локального шляху каталогу, він записує +запис `plugins.installs` із `source: "path"` і `sourcePath`, відносним до робочого простору, коли це можливо. Абсолютний робочий шлях завантаження залишається в -`plugins.load.paths`; запис встановлення уникає дублювання шляхів локальної робочої станції -в довгоживучій конфігурації. Це робить локальні встановлення для розробки видимими для -діагностики площини джерела без додавання другої сирої поверхні розкриття шляхів файлової системи. +`plugins.load.paths`; запис встановлення уникає дублювання локальних шляхів +робочої станції в довготривалій конфігурації. Це зберігає видимість локальних +встановлень для розробки для діагностики площини джерел, не додаючи другої +поверхні розкриття сирих шляхів файлової системи. -## Plugin рушія контексту +## Plugin механізму контексту -Plugin рушія контексту володіють оркестрацією контексту сесії для ingest, assembly -і Compaction. Реєструйте їх зі свого plugin через -`api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій за допомогою +Plugin механізму контексту володіють оркестрацією контексту сесії для ingest, assembly +і Compaction. Реєструйте їх із вашого Plugin за допомогою +`api.registerContextEngine(id, factory)`, а потім вибирайте активний механізм через `plugins.slots.contextEngine`. -Використовуйте це, коли вашому plugin потрібно замінити або розширити типовий конвеєр -контексту, а не просто додати пошук у пам’яті чи хуки. +Використовуйте це, коли вашому Plugin потрібно замінити або розширити типовий +конвеєр контексту, а не просто додати пошук у пам’яті чи хуки. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -941,7 +945,7 @@ export default function (api) { } ``` -Якщо ваш рушій **не** володіє алгоритмом Compaction, залишайте `compact()` +Якщо ваш механізм **не** володіє алгоритмом Compaction, залиште `compact()` реалізованим і явно делегуйте його: ```ts @@ -979,60 +983,60 @@ export default function (api) { ## Додавання нової можливості -Коли plugin потребує поведінки, яка не вписується в поточний API, не обходьте -систему plugin через приватне проникнення всередину. Додайте відсутню можливість. +Коли Plugin потребує поведінки, яка не вписується в поточний API, не обходьте +систему Plugin через приватне проникнення. Додайте відсутню можливість. Рекомендована послідовність: 1. визначте контракт ядра - Вирішіть, якою спільною поведінкою має володіти ядро: policy, fallback, злиття config, - lifecycle, семантика для каналів і форма допоміжних засобів середовища виконання. -2. додайте типізовані поверхні реєстрації plugin/середовища виконання - Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною + Вирішіть, якою спільною поведінкою має володіти ядро: політика, резервний шлях, злиття конфігурації, + життєвий цикл, семантика для каналів і форма допоміжного засобу середовища виконання. +2. додайте типізовані поверхні реєстрації/середовища виконання Plugin + Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною типізованою поверхнею можливості. -3. підключіть ядро + споживачів каналів/функцій - Канали й plugin функцій повинні споживати нову можливість через ядро, - а не імпортувати реалізацію вендора безпосередньо. -4. зареєструйте реалізації вендора - Потім plugin вендора реєструють свої бекенди для цієї можливості. +3. підключіть ядро + споживачів каналів/можливостей + Канали і Plugin можливостей мають споживати нову можливість через ядро, + а не імпортувати реалізацію постачальника безпосередньо. +4. зареєструйте реалізації постачальників + Потім Plugin постачальників реєструють свої backend проти цієї можливості. 5. додайте покриття контракту - Додайте тести, щоб форма власності та реєстрації з часом залишалася явною. + Додайте тести, щоб володіння і форма реєстрації з часом залишалися явними. -Саме так OpenClaw зберігає власну позицію, не стаючи жорстко прив’язаним до -світогляду одного провайдера. Див. [Кулінарна книга можливостей](/uk/plugins/architecture), -щоб ознайомитися з конкретним списком файлів і готовим прикладом. +Саме так OpenClaw залишається виразним, не стаючи жорстко закодованим під +світогляд одного провайдера. Див. [Збірник рецептів можливостей](/uk/plugins/architecture), +щоб переглянути конкретний контрольний список файлів і робочий приклад. -### Контрольний список можливості +### Контрольний список можливостей -Коли ви додаєте нову можливість, реалізація зазвичай має разом торкатися таких -поверхонь: +Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих +поверхонь разом: - типи контракту ядра в `src//types.ts` - runner/допоміжний засіб середовища виконання ядра в `src//runtime.ts` -- поверхня реєстрації API plugin в `src/plugins/types.ts` -- підключення реєстру plugin в `src/plugins/registry.ts` -- відкриття середовища виконання plugin в `src/plugins/runtime/*`, коли plugin функцій/каналів - мають його споживати -- допоміжні засоби capture/test в `src/test-utils/plugin-registration.ts` -- перевірки власності/контракту в `src/plugins/contracts/registry.ts` -- документація для операторів/plugin в `docs/` +- поверхня реєстрації API Plugin у `src/plugins/types.ts` +- підключення реєстру Plugin у `src/plugins/registry.ts` +- відкриття середовища виконання Plugin у `src/plugins/runtime/*`, коли Plugin можливостей/каналів + мають це споживати +- допоміжні засоби захоплення/тестування в `src/test-utils/plugin-registration.ts` +- перевірки володіння/контракту в `src/plugins/contracts/registry.ts` +- документація для операторів/Plugin у `docs/` -Якщо однієї з цих поверхонь бракує, це зазвичай ознака того, що можливість +Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість ще не повністю інтегрована. ### Шаблон можливості -Мінімальна схема: +Мінімальний шаблон: ```ts -// контракт ядра +// core contract export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// API plugin +// plugin API api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1041,14 +1045,14 @@ api.registerVideoGenerationProvider({ }, }); -// спільний допоміжний засіб середовища виконання для plugin функцій/каналів +// shared runtime helper for feature/channel plugins const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, }); ``` -Схема тесту контракту: +Шаблон контрактного тесту: ```ts expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); @@ -1057,13 +1061,13 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Це зберігає правило простим: - ядро володіє контрактом можливості + оркестрацією -- plugin вендора володіють реалізаціями вендора -- plugin функцій/каналів споживають допоміжні засоби середовища виконання -- тести контракту зберігають власність явною +- Plugin постачальників володіють реалізаціями постачальників +- Plugin можливостей/каналів споживають допоміжні засоби середовища виконання +- контрактні тести зберігають явність володіння -## Пов’язані матеріали +## Пов’язане - [Архітектура Plugin](/uk/plugins/architecture) — публічна модель можливостей і форми - [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths) - [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення plugin](/uk/plugins/building-plugins) +- [Створення Plugin](/uk/plugins/building-plugins) diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 6f88172a3..d1697df49 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,64 +1,65 @@ --- read_when: - - Ви створюєте Plugin для OpenClaw - - Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin + - Ви створюєте плагін OpenClaw + - Вам потрібно надати схему конфігурації плагіна або налагодити помилки валідації плагіна summary: Вимоги до маніфесту Plugin і схеми JSON (сувора валідація конфігурації) title: Маніфест Plugin x-i18n: - generated_at: "2026-04-24T16:00:11Z" + generated_at: "2026-04-24T16:05:24Z" model: gpt-5.4 provider: openai - source_hash: 3ad8f4d82624420f97f38ba5f7b1de12dbf88d4cc4fb37a52ae31cbb838ebabf + source_hash: 44eca8a54f22735ae657efde088a7951eeb79dfbb48a25d478c7e9a3f699cce0 source_path: plugins/manifest.md workflow: 15 --- -Ця сторінка призначена лише для **власного маніфесту Plugin OpenClaw**. +Ця сторінка призначена лише для **власного маніфесту плагіна OpenClaw**. -Для сумісних макетів пакетів див. [Пакети Plugin](/uk/plugins/bundles). +Сумісні макети bundle дивіться в [Plugin bundles](/uk/plugins/bundles). -Сумісні формати пакетів використовують інші файли маніфесту: +Сумісні формати bundle використовують інші файли маніфесту: -- Пакет Codex: `.codex-plugin/plugin.json` -- Пакет Claude: `.claude-plugin/plugin.json` або типовий макет компонента Claude +- bundle Codex: `.codex-plugin/plugin.json` +- bundle Claude: `.claude-plugin/plugin.json` або типовий макет компонента Claude без маніфесту -- Пакет Cursor: `.cursor-plugin/plugin.json` +- bundle Cursor: `.cursor-plugin/plugin.json` -OpenClaw також автоматично виявляє ці макети пакетів, але вони не проходять валідацію +OpenClaw також автоматично визначає ці макети bundle, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакетів OpenClaw наразі зчитує метадані пакета разом із оголошеними -коренями skill, коренями команд Claude, типовими значеннями Claude-пакета з -`settings.json`, типовими значеннями LSP для Claude-пакета та підтримуваними -наборами хуків, якщо макет відповідає очікуванням середовища виконання OpenClaw. +Для сумісних bundle OpenClaw наразі читає метадані bundle разом з оголошеними +коренями Skills, коренями команд Claude, типовими значеннями Claude bundle `settings.json`, +типовими значеннями Claude bundle LSP і підтримуваними пакетами хуків, коли макет відповідає +очікуванням рантайму OpenClaw. -Кожен власний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у -**корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації -**без виконання коду plugin**. Відсутні або недійсні маніфести вважаються -помилками plugin і блокують валідацію конфігурації. +Кожен власний плагін OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у +**корені плагіна**. OpenClaw використовує цей маніфест для валідації конфігурації +**без виконання коду плагіна**. Відсутні або невалідні маніфести вважаються +помилками плагіна і блокують валідацію конфігурації. -Див. повний посібник по системі plugin: [Plugins](/uk/tools/plugin). +Дивіться повний посібник із системи плагінів: [Plugins](/uk/tools/plugin). Щодо власної моделі можливостей і поточних рекомендацій із зовнішньої сумісності: -[Модель можливостей](/uk/plugins/architecture#public-capability-model). +[Capability model](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл `openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження коду -вашого plugin**. Усе нижче має бути достатньо легким для перевірки без запуску -середовища виконання plugin. +вашого плагіна**. Усе нижче має бути достатньо легким для перевірки без запуску +рантайму плагіна. **Використовуйте його для:** -- ідентифікації plugin, валідації конфігурації та підказок UI для конфігурації -- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища provider, варіанти автентифікації) -- підказок активації для поверхонь control-plane +- ідентичності плагіна, валідації конфігурації та підказок для UI конфігурації +- метаданих автентифікації, онбордингу та налаштування (аліас, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) +- підказок активації для поверхонь control plane - скороченого володіння сімействами моделей - статичних знімків володіння можливостями (`contracts`) - метаданих QA runner, які може перевіряти спільний хост `openclaw qa` -- метаданих конфігурації, специфічних для channel, що об’єднуються в поверхнях каталогу та валідації +- метаданих конфігурації, специфічних для каналу, які об’єднуються в поверхні каталогу та валідації -**Не використовуйте його для:** реєстрації поведінки під час виконання, оголошення -точок входу коду або метаданих встановлення npm. Це має належати до коду вашого plugin і `package.json`. +**Не використовуйте його для:** реєстрації поведінки рантайму, оголошення +точок входу коду або метаданих встановлення npm. Це належить коду вашого плагіна +та `package.json`. ## Мінімальний приклад @@ -73,7 +74,7 @@ OpenClaw також автоматично виявляє ці макети па } ``` -## Розгорнутий приклад +## Розширений приклад ```json { @@ -138,68 +139,68 @@ OpenClaw також автоматично виявляє ці макети па ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний id plugin. Це id, який використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього plugin. | -| `enabledByDefault` | Ні | `true` | Позначає вбудований plugin як увімкнений за замовчуванням. Пропустіть його або встановіть будь-яке значення, відмінне від `true`, щоб plugin залишався вимкненим за замовчуванням. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id provider, які мають автоматично вмикати цей plugin, коли згадуються автентифікація, конфігурація або посилання на моделі. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип plugin, що використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Id channel, якими володіє цей plugin. Використовується для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Id provider, якими володіє цей plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Полегшений шлях до модуля виявлення provider, відносно кореня plugin, для метаданих каталогу provider в межах маніфесту, які можна завантажити без активації повного середовища виконання plugin. | -| `modelSupport` | Ні | `object` | Скорочені метадані сімейств моделей, що належать маніфесту та використовуються для автозавантаження plugin до виконання. | -| `providerEndpoints` | Ні | `object[]` | Метадані хостів endpoint/baseUrl, що належать маніфесту, для маршрутів provider, які ядро повинно класифікувати до завантаження середовища виконання provider. | -| `cliBackends` | Ні | `string[]` | Id backend CLI, якими володіє цей plugin. Використовується для автоактивації під час запуску на основі явних посилань у конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на provider або backend CLI, для яких синтетичний хук автентифікації, що належить plugin, слід перевіряти під час холодного виявлення моделей до завантаження середовища виконання. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, що належать вбудованому plugin і представляють несекретний локальний стан, OAuth або ambient credential state. | -| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей plugin і які мають створювати діагностику конфігурації та CLI з урахуванням plugin до завантаження середовища виконання. | -| `providerAuthEnvVars` | Ні | `Record` | Полегшені метадані змінних середовища автентифікації provider, які OpenClaw може перевіряти без завантаження коду plugin. | -| `providerAuthAliases` | Ні | `Record` | Id provider, які мають повторно використовувати інший id provider для пошуку автентифікації, наприклад coding provider, що використовує той самий API-ключ базового provider і профілі автентифікації. | -| `channelEnvVars` | Ні | `Record` | Полегшені метадані змінних середовища channel, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для налаштування channel через env або поверхонь автентифікації, які мають бачити типові помічники запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Полегшені метадані варіантів автентифікації для селекторів онбордингу, вибору preferred provider та простого зв’язування прапорців CLI. | -| `activation` | Ні | `object` | Полегшені метадані планувальника активації для завантаження, що запускається provider, командою, channel, маршрутом і можливостями. Лише метадані; фактичною поведінкою як і раніше володіє середовище виконання plugin. | -| `setup` | Ні | `object` | Полегшені дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання plugin. | -| `qaRunners` | Ні | `object[]` | Полегшені дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання plugin. | -| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Полегшені типові значення media-understanding для id provider, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації channel, що належать маніфесту та об’єднуються в поверхнях виявлення та валідації до завантаження середовища виконання. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. | -| `name` | Ні | `string` | Людинозрозуміла назва plugin. | -| `description` | Ні | `string` | Короткий опис, що показується в поверхнях plugin. | -| `version` | Ні | `string` | Інформаційна версія plugin. | -| `uiHints` | Ні | `Record` | Підписи UI, заповнювачі та підказки чутливості для полів конфігурації. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------------------------ | ----------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Канонічний ідентифікатор плагіна. Саме цей ідентифікатор використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована схема JSON Schema для конфігурації цього плагіна. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований плагін як увімкнений за замовчуванням. Не вказуйте його або встановіть будь-яке значення, відмінне від `true`, щоб плагін за замовчуванням залишався вимкненим. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора плагіна. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей плагін, коли автентифікація, конфігурація або посилання на моделі згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип плагіна, який використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей плагін. Використовуються для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей плагін. | +| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення провайдера, відносний до кореня плагіна, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного рантайму плагіна. | +| `modelSupport` | Ні | `object` | Скорочені метадані сімейств моделей, якими володіє маніфест, що використовуються для автозавантаження плагіна до запуску рантайму. | +| `providerEndpoints` | Ні | `object[]` | Метадані хостів endpoint/baseUrl, якими володіє маніфест, для маршрутів провайдерів, які ядро має класифікувати до завантаження рантайму провайдера. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI, якими володіє цей плагін. Використовуються для автоактивації під час запуску на основі явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або backend CLI, для яких під час холодного виявлення моделей до завантаження рантайму слід перевіряти синтетичний хук автентифікації, що належить плагіну. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать вбудованому плагіну і представляють несекретний локальний стан, OAuth або ambient credentials. | +| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей плагін і які мають створювати діагностику конфігурації та CLI з урахуванням плагіна до завантаження рантайму. | +| `providerAuthEnvVars` | Ні | `Record` | Легковагові метадані змінних середовища автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер кодування, який спільно використовує API key базового провайдера та профілі автентифікації. | +| `channelEnvVars` | Ні | `Record` | Легковагові метадані змінних середовища каналу, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналів через env або поверхонь автентифікації, які мають бачити загальні помічники запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Легковагові метадані варіантів автентифікації для вибору під час онбордингу, визначення бажаного провайдера та простого зв’язування з прапорцями CLI. | +| `activation` | Ні | `object` | Легковагові метадані планувальника активації для завантаження, що запускається провайдерами, командами, каналами, маршрутами та можливостями. Лише метадані; фактичною поведінкою все одно володіє рантайм плагіна. | +| `setup` | Ні | `object` | Легковагові дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження рантайму плагіна. | +| `qaRunners` | Ні | `object[]` | Легковагові дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження рантайму плагіна. | +| `contracts` | Ні | `object` | Статичний знімок можливостей вбудованого плагіна для зовнішніх хуків автентифікації, мовлення, транскрибування в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, вебпошуку та володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легковагові типові значення для розуміння медіа для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, якими володіє маніфест і які об’єднуються в поверхні виявлення та валідації до завантаження рантайму. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореня плагіна. | +| `name` | Ні | `string` | Людинозрозуміла назва плагіна. | +| `description` | Ні | `string` | Короткий опис, що показується в поверхнях плагіна. | +| `version` | Ні | `string` | Інформаційна версія плагіна. | +| `uiHints` | Ні | `Record` | Підписи UI, placeholders і підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. -OpenClaw читає це до завантаження середовища виконання provider. +OpenClaw читає це до завантаження рантайму провайдера. -| Поле | Обов’язкове | Тип | Що воно означає | -| --------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Id provider, до якого належить цей варіант. | -| `method` | Так | `string` | Id методу автентифікації, до якого слід маршрутизувати. | -| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, який використовується в потоках онбордингу та CLI. | -| `choiceLabel` | Ні | `string` | Підпис для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих помічником. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із селекторів помічника, але все ще дозволяє ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів на цей варіант-заміну. | -| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Підпис цієї групи для користувача. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | -| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має показуватися цей варіант. Якщо не вказано, типовим значенням є `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. | +| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід маршрутизувати. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, що використовується в потоках онбордингу та CLI. | +| `choiceLabel` | Ні | `string` | Підпис для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для списку вибору. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних списках вибору, керованих асистентом. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант зі списків вибору асистента, але все ще дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають переспрямовувати користувачів на цей варіант-заміну. | +| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Підпис для користувача для цієї групи. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли plugin володіє назвою команди під час виконання, яку користувачі можуть -помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw -використовує ці метадані для діагностики без імпорту коду середовища виконання plugin. +Використовуйте `commandAliases`, коли плагін володіє назвою команди рантайму, яку користувачі можуть +помилково додати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw +використовує ці метадані для діагностики без імпорту коду рантайму плагіна. ```json { @@ -213,35 +214,34 @@ OpenClaw читає це до завантаження середовища ви } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, що належить цьому plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------------ | +| `name` | Так | `string` | Назва команди, яка належить цьому плагіну. | +| `kind` | Ні | `"runtime-slash"` | Позначає аліас як chat slash command, а не як кореневу команду CLI. | | `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо вона існує. | ## Довідник `activation` -Використовуйте `activation`, коли plugin може недорого оголосити, які події control-plane +Використовуйте `activation`, коли плагін може дешево оголосити, які події control plane мають включати його в план активації/завантаження. Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє -поведінку під час виконання, не замінює `register(...)` і не гарантує, що -код plugin уже було виконано. Планувальник активації використовує ці поля для -звуження списку кандидатів plugin перед поверненням до наявних метаданих -володіння з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, +поведінку рантайму, не замінює `register(...)` і не гарантує, що +код плагіна вже було виконано. Планувальник активації використовує ці поля, щоб +звузити коло кандидатів на плагіни, перш ніж повертатися до наявних +метаданих володіння в маніфесті, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і хуки. Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, -коли ці поля виражають відповідний зв’язок. Використовуйте `activation` для додаткових підказок -планувальника, які не можуть бути представлені цими полями володіння. +коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальника, +які не можна подати через ці поля володіння. -Цей блок містить лише метадані. Він не реєструє поведінку під час виконання і -не замінює `register(...)`, `setupEntry` або інші точки входу runtime/plugin. -Поточні споживачі використовують його як підказку для звуження перед ширшим -завантаженням plugin, тому відсутність метаданих активації зазвичай лише впливає на продуктивність; -це не має змінювати коректність, доки ще існують застарілі fallback-механізми -володіння з маніфесту. +Цей блок є лише метаданими. Він не реєструє поведінку рантайму і не +замінює `register(...)`, `setupEntry` або інші точки входу рантайму/плагіна. +Поточні споживачі використовують його як підказку для звуження кола кандидатів перед ширшим завантаженням плагінів, тож +відсутність метаданих активації зазвичай впливає лише на продуктивність; вона не повинна +змінювати коректність, поки все ще існують застарілі fallback-механізми володіння через маніфест. ```json { @@ -255,36 +255,35 @@ OpenClaw читає це до завантаження середовища ви } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ---------------- | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Id provider, які мають включати цей plugin у плани активації/завантаження. | -| `onCommands` | Ні | `string[]` | Id команд, які мають включати цей plugin у плани активації/завантаження. | -| `onChannels` | Ні | `string[]` | Id channel, які мають включати цей plugin у плани активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей plugin у плани активації/завантаження. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються в плануванні активації control-plane. За можливості надавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей плагін у плани активації/завантаження. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей плагін у плани активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей плагін у плани активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей плагін у плани активації/завантаження. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, які використовуються плануванням активації control plane. Коли можливо, надавайте перевагу вужчим полям. | -Поточні активні споживачі: +Поточні live-споживачі: -- планування CLI, запущене командою, повертається до застарілих +- планування CLI, що запускається командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` -- планування setup/channel, запущене channel, повертається до застарілого - володіння `channels[]`, якщо явні метадані активації channel відсутні -- планування setup/runtime, запущене provider, повертається до застарілого - володіння `providers[]` і `cliBackends[]` верхнього рівня, якщо явні метадані - активації provider відсутні +- планування setup/каналів, що запускається каналом, повертається до застарілого + володіння `channels[]`, коли явні метадані активації каналу відсутні +- планування setup/рантайму, що запускається провайдером, повертається до застарілого + володіння `providers[]` і `cliBackends[]` верхнього рівня, коли явні метадані активації провайдера відсутні -Діагностика планувальника може розрізняти явні підказки активації та fallback -до володіння з маніфесту. Наприклад, `activation-command-hint` означає, що +Діагностика планувальника може розрізняти явні підказки активації та fallback до +володіння через маніфест. Наприклад, `activation-command-hint` означає, що спрацювало `activation.onCommands`, тоді як `manifest-command-alias` означає, що -планувальник натомість використав володіння через `commandAliases`. Ці мітки причин -призначені для діагностики хоста та тестів; авторам plugin слід і надалі оголошувати ті метадані, +планувальник замість цього використав володіння через `commandAliases`. Ці мітки причин призначені для +діагностики хоста та тестів; авторам плагінів слід і надалі оголошувати ті метадані, які найкраще описують володіння. ## Довідник `qaRunners` -Використовуйте `qaRunners`, коли plugin додає один або кілька транспортних runner -під спільним коренем `openclaw qa`. Зберігайте ці метадані легкими та статичними; фактичною -реєстрацією CLI як і раніше володіє середовище виконання plugin через полегшену +Використовуйте `qaRunners`, коли плагін додає один або кілька транспортних runner під +спільним коренем `openclaw qa`. Зберігайте ці метадані легковаговими та статичними; фактичною логікою CLI +все одно володіє рантайм плагіна через легковагову поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json @@ -292,7 +291,7 @@ OpenClaw читає це до завантаження середовища ви "qaRunners": [ { "commandName": "matrix", - "description": "Запустити Docker-backed Matrix live QA lane на одноразовому homeserver" + "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver" } ] } @@ -301,12 +300,12 @@ OpenClaw читає це до завантаження середовища ви | Поле | Обов’язкове | Тип | Що воно означає | | ------------- | ----------- | -------- | ------------------------------------------------------------------------- | | `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | -| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. | +| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. | ## Довідник `setup` -Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні легкі метадані plugin, -що належать plugin, до завантаження runtime. +Використовуйте `setup`, коли поверхням setup та онбордингу потрібні легковагові метадані плагіна +до завантаження рантайму. ```json { @@ -325,47 +324,48 @@ OpenClaw читає це до завантаження середовища ви } ``` -`cliBackends` верхнього рівня залишається чинним і продовжує описувати backend CLI для інференсу. -`setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків -control-plane/setup, які мають залишатися лише метаданими. +`cliBackends` верхнього рівня залишається валідним і надалі описує +backend виведення CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, +для потоків control-plane/setup, які мають залишатися лише на рівні метаданих. -За наявності `setup.providers` і `setup.cliBackends` є бажаною поверхнею пошуку -на основі дескрипторів для виявлення setup. Якщо дескриптор лише звужує список -plugin-кандидатів, а setup усе ще потребує більш багатих runtime-хуків на етапі налаштування, -встановіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. +Коли вони присутні, `setup.providers` і `setup.cliBackends` є пріоритетною +поверхнею пошуку setup у стилі descriptor-first для виявлення setup. Якщо дескриптор лише +звужує коло кандидатів на плагін, а setup все ще потребує багатших runtime-хуків часу setup, +встановіть `requiresRuntime: true` і залиште `setup-api` як +резервний шлях виконання. -Оскільки пошук setup може виконувати код `setup-api`, що належить plugin, -нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися -унікальними серед виявлених plugin. Неоднозначне володіння завершується без вибору, -замість того щоб обирати переможця за порядком виявлення. +Оскільки пошук setup може виконувати код `setup-api`, що належить плагіну, +нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед +виявлених плагінів. Неоднозначне володіння завершується закритою відмовою замість вибору +переможця на основі порядку виявлення. ### Довідник `setup.providers` | Поле | Обов’язкове | Тип | Що воно означає | | ------------- | ----------- | ---------- | ---------------------------------------------------------------------------------- | -| `id` | Так | `string` | Id provider, що відкривається під час setup або онбордингу. Зберігайте нормалізовані id глобально унікальними. | -| `authMethods` | Ні | `string[]` | Id методів setup/автентифікації, які цей provider підтримує без завантаження повного runtime. | -| `envVars` | Ні | `string[]` | Змінні середовища, які типові поверхні setup/status можуть перевіряти до завантаження runtime plugin. | +| `id` | Так | `string` | Ідентифікатор провайдера, який відкривається під час setup або онбордингу. Зберігайте нормалізовані ідентифікатори глобально унікальними. | +| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей провайдер підтримує без завантаження повного рантайму. | +| `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні setup/status можуть перевіряти до завантаження рантайму плагіна. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | -------------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори setup provider, що відкриваються під час setup та онбордингу. | -| `cliBackends` | Ні | `string[]` | Id backend для setup, що використовуються для пошуку setup на основі дескрипторів. Зберігайте нормалізовані id глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє поверхня setup цього plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------ | +| `providers` | Ні | `object[]` | Дескриптори setup провайдерів, які відкриваються під час setup та онбордингу. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend часу setup, що використовуються для пошуку setup у стилі descriptor-first. Зберігайте нормалізовані ідентифікатори глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього плагіна. | +| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку дескриптора. | ## Довідник `uiHints` -`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для рендерингу. +`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу. ```json { "uiHints": { "apiKey": { "label": "API key", - "help": "Used for OpenRouter requests", + "help": "Використовується для запитів OpenRouter", "placeholder": "sk-or-v1-...", "sensitive": true } @@ -373,7 +373,7 @@ plugin-кандидатів, а setup усе ще потребує більш б } ``` -Кожна підказка для поля може містити: +Кожна підказка поля може містити: | Поле | Тип | Що воно означає | | ------------- | ---------- | -------------------------------------- | @@ -382,12 +382,12 @@ plugin-кандидатів, а setup усе ще потребує більш б | `tags` | `string[]` | Необов’язкові теги UI. | | `advanced` | `boolean` | Позначає поле як розширене. | | `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст-заповнювач для полів форми. | +| `placeholder` | `string` | Текст placeholder для полів форми. | ## Довідник `contracts` Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може -читати без імпорту середовища виконання plugin. +читати без імпорту рантайму плагіна. ```json { @@ -410,37 +410,37 @@ plugin-кандидатів, а setup усе ще потребує більш б Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | --------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Id вбудованого runtime, для яких вбудований plugin може реєструвати фабрики. | -| `externalAuthProviders` | `string[]` | Id provider, хуком зовнішнього профілю автентифікації яких володіє цей plugin. | -| `speechProviders` | `string[]` | Id provider speech, якими володіє цей plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Id provider realtime-transcription, якими володіє цей plugin. | -| `realtimeVoiceProviders` | `string[]` | Id provider realtime-voice, якими володіє цей plugin. | -| `memoryEmbeddingProviders` | `string[]` | Id provider memory embedding, якими володіє цей plugin. | -| `mediaUnderstandingProviders` | `string[]` | Id provider media-understanding, якими володіє цей plugin. | -| `imageGenerationProviders` | `string[]` | Id provider image-generation, якими володіє цей plugin. | -| `videoGenerationProviders` | `string[]` | Id provider video-generation, якими володіє цей plugin. | -| `webFetchProviders` | `string[]` | Id provider web-fetch, якими володіє цей plugin. | -| `webSearchProviders` | `string[]` | Id provider web search, якими володіє цей plugin. | -| `tools` | `string[]` | Назви інструментів агента, якими володіє цей plugin для перевірок вбудованого контракту. | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | ------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Ідентифікатори вбудованого рантайму, для яких вбудований плагін може реєструвати фабрики. | +| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, чий хук профілю зовнішньої автентифікації належить цьому плагіну. | +| `speechProviders` | `string[]` | Ідентифікатори провайдерів мовлення, якими володіє цей плагін. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів транскрибування в реальному часі, якими володіє цей плагін. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів голосу в реальному часі, якими володіє цей плагін. | +| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів embedding для пам’яті, якими володіє цей плагін. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів розуміння медіа, якими володіє цей плагін. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації зображень, якими володіє цей плагін. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації відео, якими володіє цей плагін. | +| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей плагін. | +| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів вебпошуку, якими володіє цей плагін. | +| `tools` | `string[]` | Назви інструментів агента, якими володіє цей плагін для перевірок контрактів вбудованих плагінів. | -Plugin provider, які реалізують `resolveExternalAuthProfiles`, мають оголошувати -`contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють -через застарілий сумісний fallback, але він повільніший і -буде вилучений після завершення вікна міграції. +Плагіни провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати +`contracts.externalAuthProviders`. Плагіни без цього оголошення все ще працюють +через застарілий сумісний fallback, але цей fallback повільніший і +буде видалений після завершення вікна міграції. -Вбудовані provider memory embedding мають оголошувати -`contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони надають, включно з -вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей контракт -маніфесту, щоб завантажувати лише plugin-власник до того, як повне середовище виконання Gateway -зареєструє provider. +Вбудовані провайдери embedding для пам’яті мають оголошувати +`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони надають, зокрема +для вбудованих адаптерів, таких як `local`. Автономні шляхи CLI використовують цей контракт маніфесту, +щоб завантажувати лише плагін-власник до того, як повний рантайм Gateway +зареєструє провайдерів. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли provider media-understanding має -типові моделі, пріоритет fallback для автоматичної автентифікації або власну підтримку документів, -які потрібні типовим допоміжникам ядра до завантаження runtime. Ключі також мають бути оголошені в +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має +типові моделі, пріоритет fallback для автоавтентифікації або нативну підтримку документів, які +потрібні загальним помічникам ядра до завантаження рантайму. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json @@ -464,19 +464,19 @@ Plugin provider, які реалізують `resolveExternalAuthProfiles`, ма } ``` -Кожен запис provider може містити: +Кожен запис провайдера може містити: -| Поле | Тип | Що воно означає | -| ---------------------- | ----------------------------------- | -------------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей provider. | -| `defaultModels` | `Record` | Типові відповідності можливість-модель, що використовуються, коли конфігурація не задає модель. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback provider на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Власні входи документів, які підтримує provider. | +| Поле | Тип | Що воно означає | +| ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості роботи з медіа, які надає цей провайдер. | +| `defaultModels` | `Record` | Типові відповідності можливостей до моделей, що використовуються, коли в конфігурації не вказано модель. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback до провайдера на основі облікових даних. | +| `nativeDocumentInputs` | `"pdf"[]` | Нативні типи документів, які підтримує провайдер. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли channel plugin потребує легких метаданих конфігурації до -завантаження runtime. +Використовуйте `channelConfigs`, коли плагіну каналу потрібні легковагові метадані конфігурації до +завантаження рантайму. ```json { @@ -491,32 +491,33 @@ Plugin provider, які реалізують `resolveExternalAuthProfiles`, ма }, "uiHints": { "homeserverUrl": { - "label": "Homeserver URL", + "label": "URL homeserver", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", - "description": "Підключення до homeserver Matrix", + "description": "Підключення до Matrix homeserver", "preferOver": ["matrix-legacy"] } } } ``` -Кожен запис channel може містити: +Кожен запис каналу може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | ----------------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації channel. | -| `uiHints` | `Record` | Необов’язкові підписи UI/заповнювачі/підказки чутливості для цього розділу конфігурації channel. | -| `label` | `string` | Підпис channel, що об’єднується в поверхнях вибору та перегляду, коли метадані runtime ще не готові. | -| `description` | `string` | Короткий опис channel для поверхонь перегляду та каталогу. | -| `preferOver` | `string[]` | Id застарілих або менш пріоритетних plugin, які цей channel має випереджати в поверхнях вибору. | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | -------------------------------------------------------------------------------------- | +| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | +| `uiHints` | `Record` | Необов’язкові підписи UI/placeholders/підказки щодо чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Підпис каналу, що об’єднується в поверхні вибору та перевірки, коли метадані рантайму ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь перевірки та каталогу. | +| `preferOver` | `string[]` | Ідентифікатори застарілих або менш пріоритетних плагінів, які цей канал має перевершувати в поверхнях вибору. | ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має визначати ваш provider plugin за -скороченими id моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження runtime plugin. +Використовуйте `modelSupport`, коли OpenClaw має визначати ваш плагін провайдера за +скороченими ідентифікаторами моделей, такими як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження +рантайму плагіна. ```json { @@ -529,102 +530,104 @@ Plugin provider, які реалізують `resolveExternalAuthProfiles`, ма OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers` plugin-власника -- `modelPatterns` мають вищий пріоритет, ніж `modelPrefixes` -- якщо збігаються один невбудований plugin і один вбудований plugin, перемагає невбудований - plugin -- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть provider +- явні посилання `provider/model` використовують метадані маніфесту `providers` плагіна-власника +- `modelPatterns` мають вищий пріоритет за `modelPrefixes` +- якщо збігаються і один невбудований плагін, і один вбудований плагін, перемагає невбудований + плагін +- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкаже провайдера Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | -------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id моделей. | -| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id моделей після видалення суфікса профілю. | +| Поле | Тип | Що воно означає | +| --------------- | ---------- | ---------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | -Застарілі ключі можливостей верхнього рівня не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб +Застарілі ключі можливостей верхнього рівня є deprecated. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне +`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне завантаження маніфесту більше не розглядає ці поля верхнього рівня як володіння можливостями. ## Маніфест і `package.json` -Ці два файли виконують різні завдання: +Ці два файли виконують різні задачі: -| Файл | Для чого використовувати | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду plugin | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, обмежень встановлення, setup або метаданих каталогу | +| Файл | Використовуйте його для | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Виявлення, валідації конфігурації, метаданих варіантів автентифікації та підказок UI, які мають існувати до запуску коду плагіна | +| `package.json` | Метаданих npm, встановлення залежностей і блоку `openclaw`, який використовується для точок входу, обмежень встановлення, setup або метаданих каталогу | -Якщо ви не впевнені, куди належить певний фрагмент метаданих, користуйтеся таким правилом: +Якщо ви не впевнені, куди має належати певний фрагмент метаданих, користуйтеся таким правилом: -- якщо OpenClaw має знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json` +- якщо OpenClaw має знати це до завантаження коду плагіна, помістіть це в `openclaw.plugin.json` - якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, помістіть це в `package.json` ### Поля `package.json`, які впливають на виявлення -Деякі метадані plugin до виконання навмисно зберігаються в `package.json` у блоці +Деякі метадані плагіна до запуску рантайму навмисно зберігаються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує точки входу власного Plugin. Має залишатися в межах каталогу пакета plugin. | -| `openclaw.runtimeExtensions` | Оголошує точки входу built JavaScript runtime для встановлених пакетів. Має залишатися в межах каталогу пакета plugin. | -| `openclaw.setupEntry` | Полегшена точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску channel і виявлення статусу channel/SecretRef у режимі лише читання. Має залишатися в межах каталогу пакета plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript точку входу setup для встановлених пакетів. Має залишатися в межах каталогу пакета plugin. | -| `openclaw.channel` | Полегшені метадані каталогу channel, як-от підписи, шляхи до документації, псевдоніми та тексти для вибору. | -| `openclaw.channel.configuredState` | Полегшені метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного runtime channel. | -| `openclaw.channel.persistedAuthState` | Полегшені метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже виконано вхід хоч десь?» без завантаження повного runtime channel. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення вбудованих і зовнішньо опублікованих plugin. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення звіряють завантажений артефакт із ним. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого plugin, коли конфігурація недійсна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного plugin channel під час запуску. | +| Поле | Що воно означає | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `openclaw.extensions` | Оголошує точки входу власного плагіна. Вони мають залишатися в межах каталогу пакета плагіна. | +| `openclaw.runtimeExtensions` | Оголошує точки входу рантайму зібраного JavaScript для встановлених пакетів. Вони мають залишатися в межах каталогу пакета плагіна. | +| `openclaw.setupEntry` | Легковагова точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та read-only виявлення channel status/SecretRef. Має залишатися в межах каталогу пакета плагіна. | +| `openclaw.runtimeSetupEntry` | Оголошує точку входу setup зібраного JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета плагіна. | +| `openclaw.channel` | Легковагові метадані каталогу каналу, як-от підписи, шляхи до документації, аліаси та текст для вибору. | +| `openclaw.channel.configuredState` | Легковагові метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного рантайму каналу. | +| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного рантайму каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих плагінів. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімально підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого плагіна, коли конфігурація невалідна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного плагіна каналу під час запуску. | -Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в -онбордингу до завантаження runtime. `package.json#openclaw.install` повідомляє -онбордингу, як отримати або ввімкнути цей plugin, коли користувач вибирає один із цих -варіантів. Не переносіть підказки встановлення до `openclaw.plugin.json`. +Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в +онбордингу до завантаження рантайму. `package.json#openclaw.install` повідомляє +онбордингу, як отримати або ввімкнути цей плагін, коли користувач вибирає один із цих +варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`. -`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження -реєстру маніфестів. Недійсні значення відхиляються; новіші, але коректні значення -пропускають plugin на старіших хостах. +`openclaw.install.minHostVersion` застосовується під час встановлення та +завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення +пропускають плагін на старіших хостах. -Точне закріплення версії npm уже зберігається в `npmSpec`, наприклад +Точне закріплення версії npm уже міститься в `npmSpec`, наприклад `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення -завершувалися без вибору, якщо завантажений npm-артефакт більше не відповідає -закріпленому релізу. Інтерактивний онбординг і надалі пропонує довірені npm-специфікації -реєстру, зокрема прості назви пакетів і dist-tags, для сумісності. Діагностика каталогу -може розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності та недійсні -джерела default-choice. Коли `expectedIntegrity` присутній, потоки встановлення/оновлення -застосовують його; коли його пропущено, розв’язання через реєстр записується -без закріплення цілісності. +завершувалися закритою відмовою, якщо отриманий артефакт npm більше не відповідає закріпленому релізу. +Інтерактивний онбординг усе ще пропонує довірені npm-специфікації реєстру, включно з +простими назвами пакетів і dist-tag, для сумісності. Діагностика каталогу може +розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності та невалідні +джерела default-choice. Вона також попереджає, коли `expectedIntegrity` присутній, але +немає валідного джерела npm, яке можна ним закріпити. Коли `expectedIntegrity` присутній, +потоки встановлення/оновлення застосовують його; коли він пропущений, розв’язання реєстру +фіксується без закріплення за цілісністю. -Channel plugin мають надавати `openclaw.setupEntry`, коли статус, список channel +Плагіни каналів мають надавати `openclaw.setupEntry`, коли status, список каналів або сканування SecretRef повинні визначати налаштовані облікові записи без завантаження повного -runtime. Точка входу setup має надавати метадані channel разом із безпечними для setup -адаптерами конфігурації, статусу й секретів; мережеві клієнти, слухачі Gateway і -transport runtime слід залишати в основній точці входу extension. +рантайму. Точка входу setup має надавати метадані каналу разом із безпечними для setup +адаптерами конфігурації, status і secret; мережеві клієнти, слухачі Gateway та +транспортні рантайми слід тримати в основній точці входу extension. -Поля точок входу runtime не скасовують перевірки меж пакета для -полів точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити -придатним до завантаження шлях `openclaw.extensions`, що виходить за межі. +Поля точок входу рантайму не перевизначають перевірки меж пакета для полів +точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити +шлях `openclaw.extensions`, що виходить за межі, доступним для завантаження. -`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він -не робить довільні зламані конфігурації придатними для встановлення. Наразі він лише дозволяє -потокам встановлення відновлюватися після певних застарілих збоїв оновлення вбудованого plugin, -наприклад відсутнього шляху до вбудованого plugin або застарілого запису `channels.` для цього ж -вбудованого plugin. Несуміжні помилки конфігурації, як і раніше, блокують встановлення та спрямовують операторів +`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно +не робить довільно зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам встановлення +відновлюватися після певних застарілих збоїв оновлення вбудованих плагінів, наприклад +відсутнього шляху до вбудованого плагіна або застарілого запису `channels.` для того самого +вбудованого плагіна. Непов’язані помилки конфігурації, як і раніше, блокують встановлення та спрямовують операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля +перевірки: ```json { @@ -640,13 +643,13 @@ transport runtime слід залишати в основній точці вх } ``` -Використовуйте це, коли потоки setup, doctor або configured-state потребують дешевого -yes/no-зонду автентифікації до завантаження повного channel plugin. Цільовий експорт має бути -невеликою функцією, що читає лише збережений стан; не маршрутизуйте його через повний -barrel runtime channel. +Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка +автентифікації типу так/ні до завантаження повного плагіна каналу. Цільовий експорт має бути невеликою +функцією, яка читає лише збережений стан; не маршрутизуйте її через широкий barrel повного +рантайму каналу. -`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок -configured-state лише через env: +`openclaw.channel.configuredState` має таку саму форму для дешевих перевірок +налаштованого стану лише через env: ```json { @@ -662,68 +665,68 @@ configured-state лише через env: } ``` -Використовуйте це, коли channel може визначити configured-state з env або інших малих -невиконуваних вхідних даних. Якщо перевірка потребує повного розв’язання конфігурації або реального -runtime channel, натомість залиште цю логіку в хуку plugin `config.hasConfiguredState`. +Використовуйте це, коли канал може відповісти про налаштований стан на основі env або інших невеликих +вхідних даних, не пов’язаних із рантаймом. Якщо перевірка потребує повного розв’язання конфігурації або реального +рантайму каналу, залиште цю логіку в хуку плагіна `config.hasConfiguredState`. -## Пріоритет виявлення (дублікати id plugin) +## Пріоритет виявлення (дубльовані ідентифікатори плагінів) -OpenClaw виявляє plugin з кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. +OpenClaw виявляє плагіни з кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два результати виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються, а не завантажуються поруч із ним. Пріоритет, від найвищого до найнижчого: 1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` -2. **Вбудований** — plugin, що постачаються з OpenClaw -3. **Глобальне встановлення** — plugin, встановлені до глобального кореня plugin OpenClaw -4. **Workspace** — plugin, виявлені відносно поточного workspace +2. **Вбудований** — плагіни, що постачаються з OpenClaw +3. **Глобальне встановлення** — плагіни, встановлені в глобальний корінь плагінів OpenClaw +4. **Workspace** — плагіни, виявлені відносно поточного workspace Наслідки: -- Форкнута або застаріла копія вбудованого plugin у workspace не зможе затінити вбудовану збірку. -- Щоб справді перевизначити вбудований plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення у workspace. -- Відкидання дублікатів записується в лог, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. +- Форк або застаріла копія вбудованого плагіна, що лежить у workspace, не перекриє вбудовану збірку. +- Щоб справді перевизначити вбудований плагін локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтесь на виявлення у workspace. +- Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. ## Вимоги до JSON Schema -- **Кожен plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію. -- Порожня схема прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми проходять валідацію під час читання/запису конфігурації, а не під час runtime. +- **Кожен плагін повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію. +- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми проходять валідацію під час читання/запису конфігурації, а не в рантаймі. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки id channel не оголошено - маніфестом plugin. +- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено в + маніфесті плагіна. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - мають посилатися на **виявлювані** id plugin. Невідомі id є **помилками**. -- Якщо plugin встановлено, але він має зламаний або відсутній маніфест чи схему, - валідація завершується помилкою, а Doctor повідомляє про помилку plugin. -- Якщо конфігурація plugin існує, але plugin **вимкнено**, конфігурація зберігається, і - у Doctor + логах відображається **попередження**. + мають посилатися на **виявлювані** ідентифікатори плагінів. Невідомі ідентифікатори є **помилками**. +- Якщо плагін установлено, але він має зламаний або відсутній маніфест чи схему, + валідація завершується помилкою, а Doctor повідомляє про помилку плагіна. +- Якщо конфігурація плагіна існує, але сам плагін **вимкнений**, конфігурація зберігається, а + в Doctor + логах показується **попередження**. -Див. [Довідник конфігурації](/uk/gateway/configuration) для повної схеми `plugins.*`. +Повну схему `plugins.*` дивіться в [Configuration reference](/uk/gateway/configuration). ## Примітки -- Маніфест **обов’язковий для власних Plugin OpenClaw**, зокрема для локальних завантажень із файлової системи. Runtime, як і раніше, завантажує модуль plugin окремо; маніфест використовується лише для виявлення + валідації. -- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, якщо кінцеве значення все ще є об’єктом. -- Завантажувач маніфесту читає лише документовані поля маніфесту. Уникайте власних ключів верхнього рівня. -- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо plugin їх не потребує. -- `providerDiscoveryEntry` має залишатися полегшеним і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу provider або вузьких дескрипторів виявлення, а не для виконання під час запиту. -- Ексклюзивні типи plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). -- Метадані змінних середовища (`providerAuthEnvVars`, `channelEnvVars`) є лише декларативними. Поверхні статусу, аудиту, валідації доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до plugin і ефективної активації, перш ніж вважати змінну середовища налаштованою. -- Для метаданих wizard runtime, які потребують коду provider, див. [Хуки runtime provider](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш plugin залежить від native-модулів, задокументуйте кроки збирання та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Маніфест є **обов’язковим для власних плагінів OpenClaw**, включно із завантаженням із локальної файлової системи. Рантайм, як і раніше, завантажує модуль плагіна окремо; маніфест використовується лише для виявлення + валідації. +- Власні маніфести парсяться за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, доки кінцеве значення все ще залишається об’єктом. +- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте користувацьких ключів верхнього рівня. +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо плагін їх не потребує. +- `providerDiscoveryEntry` має залишатися легковаговим і не повинен імпортувати широкий код рантайму; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час обробки запитів. +- Ексклюзивні типи плагінів вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). +- Метадані змінних середовища (`providerAuthEnvVars`, `channelEnvVars`) є лише декларативними. Status, audit, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до плагіна та ефективної активації, перш ніж вважати змінну середовища налаштованою. +- Метадані runtime wizard, які потребують коду провайдера, дивіться в [Provider runtime hooks](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш плагін залежить від native modules, задокументуйте кроки збірки та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). -## Пов’язані матеріали +## Пов’язане - - Початок роботи з plugin. + + Початок роботи з плагінами. - + Внутрішня архітектура та модель можливостей. - Довідник по SDK plugin і імпортам підшляхів. + Довідник Plugin SDK і імпорти підшляхів.