From 338db644def08473f5673988bfb6638ab723a67a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Fri, 24 Apr 2026 22:24:27 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/plugins/manifest.md | 457 ++++++++++++++++++------------------ 1 file changed, 229 insertions(+), 228 deletions(-) diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 3e7ab3deb..af3dca3ea 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,53 +1,53 @@ --- read_when: - Ви створюєте Plugin для OpenClaw - - Вам потрібно надати схему конфігурації Plugin або налагодити помилки валідації Plugin -summary: Вимоги до маніфесту Plugin + JSON schema (сувора валідація конфігурації) + - Вам потрібно надати schema конфігурації Plugin або налагодити помилки валідації Plugin +summary: Вимоги до маніфесту Plugin та JSON schema (сувора валідація конфігурації) title: маніфест Plugin x-i18n: - generated_at: "2026-04-24T21:26:31Z" + generated_at: "2026-04-24T22:21:56Z" model: gpt-5.4 provider: openai - source_hash: b487d60a8645cca338b5b5a88f9a1f2b15b03e0905f6f541fe97be605c8297d6 + source_hash: ddabd562db22a82ff9c46094248350ac30565c9c10c9d87d3c0e85d49e7044a9 source_path: plugins/manifest.md workflow: 15 --- Ця сторінка призначена лише для **власного маніфесту Plugin OpenClaw**. -Сумісні макети bundle описані тут: [Plugin bundles](/uk/plugins/bundles). +Сумісні компонування bundle дивіться в [Plugin bundles](/uk/plugins/bundles). Сумісні формати bundle використовують інші файли маніфесту: - Codex bundle: `.codex-plugin/plugin.json` -- Claude bundle: `.claude-plugin/plugin.json` або стандартний макет компонента Claude без маніфесту +- Claude bundle: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude без маніфесту - Cursor bundle: `.cursor-plugin/plugin.json` -OpenClaw також автоматично виявляє ці макети bundle, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. +OpenClaw також автоматично визначає ці компонування bundle, але вони не проходять валідацію за schema `openclaw.plugin.json`, описаною тут. -Для сумісних bundle OpenClaw наразі зчитує метадані bundle, а також оголошені корені skill, корені команд Claude, значення за замовчуванням `settings.json` для Claude bundle, значення LSP за замовчуванням для Claude bundle і підтримувані набори hook, коли макет відповідає очікуванням середовища виконання OpenClaw. +Для сумісних bundle OpenClaw наразі зчитує метадані bundle, а також оголошені корені skills, корені команд Claude, типові значення `settings.json` для Claude bundle, типові значення LSP для Claude bundle і підтримувані набори hook, коли компонування відповідає очікуванням середовища виконання OpenClaw. -Кожен власний Plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у **корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду plugin**. Відсутні або невалідні маніфести вважаються помилками plugin і блокують валідацію конфігурації. +Кожен власний Plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у **корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду Plugin**. Відсутні або некоректні маніфести вважаються помилками Plugin і блокують валідацію конфігурації. -Повний посібник із системи plugin дивіться тут: [Plugins](/uk/tools/plugin). -Щодо власної моделі capability і поточних рекомендацій щодо зовнішньої сумісності: +Дивіться повний посібник по системі Plugin: [Plugins](/uk/tools/plugin). +Щодо власної моделі capability та поточних рекомендацій із зовнішньої сумісності: [Модель capability](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду вашого plugin**. Усе нижче має бути достатньо легким для перевірки без запуску середовища виконання plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду вашого Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску runtime Plugin. **Використовуйте його для:** -- ідентичності plugin, валідації конфігурації та підказок для UI конфігурації -- метаданих автентифікації, онбордингу й налаштування (псевдонім, автоувімкнення, змінні середовища provider, варіанти автентифікації) +- ідентичності Plugin, валідації конфігурації та підказок для UI конфігурації +- метаданих auth, onboarding і setup (alias, auto-enable, змінні середовища provider, варіанти auth) - підказок активації для поверхонь control plane -- скороченого визначення належності до сімейства моделей -- статичних знімків належності capability (`contracts`) +- скороченого володіння model-family +- статичних знімків володіння capability (`contracts`) - метаданих QA runner, які може перевіряти спільний хост `openclaw qa` -- метаданих конфігурації, специфічних для channel, що об’єднуються в catalog і поверхні валідації +- метаданих конфігурації для конкретних channel, що об’єднуються в поверхні каталогу та валідації -**Не використовуйте його для:** реєстрації поведінки під час виконання, оголошення точок входу коду або метаданих встановлення npm. Це належить до коду вашого plugin і `package.json`. +**Не використовуйте його для:** реєстрації поведінки runtime, оголошення code entrypoint або метаданих встановлення npm. Це належить до коду вашого Plugin і `package.json`. ## Мінімальний приклад @@ -127,67 +127,67 @@ OpenClaw також автоматично виявляє ці макети bund ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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, для метаданих catalog provider в області маніфесту, які можна завантажити без активації повного середовища виконання plugin. | -| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту, які використовуються для автозавантаження plugin до запуску середовища виконання. | -| `providerEndpoints` | Ні | `object[]` | Метадані хостів endpoint/baseUrl, що належать маніфесту, для маршрутів provider, які ядро має класифікувати до завантаження середовища виконання provider. | -| `cliBackends` | Ні | `string[]` | Id backend CLI, якими володіє цей plugin. Використовуються для автоактивації під час запуску з явних посилань конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на provider або backend CLI, для яких слід перевіряти синтетичний hook автентифікації, що належить plugin, під час холодного виявлення моделей до завантаження середовища виконання. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать вбудованому plugin і представляють не секретний локальний стан, OAuth або стан облікових даних середовища. | -| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей plugin і які повинні формувати діагностику конфігурації та CLI з урахуванням plugin до завантаження середовища виконання. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/статусу provider. Для нових plugin віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це поле протягом періоду застарівання. | -| `providerAuthAliases` | Ні | `Record` | Id provider, які мають повторно використовувати інший id provider для пошуку автентифікації, наприклад provider для кодування, який спільно використовує API key і профілі автентифікації базового provider. | -| `channelEnvVars` | Ні | `Record` | Полегшені метадані env для channel, які OpenClaw може перевірити без завантаження коду plugin. Використовуйте це для налаштування channel на основі env або поверхонь автентифікації, які мають бачити універсальні допоміжні засоби запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Полегшені метадані варіантів автентифікації для селекторів онбордингу, визначення пріоритетного provider та простого зв’язування прапорців CLI. | -| `activation` | Ні | `object` | Полегшені метадані планувальника активації для завантаження, яке запускається provider, командою, channel, маршрутом і capability. Лише метадані; фактична поведінка все ще належить середовищу виконання plugin. | -| `setup` | Ні | `object` | Полегшені дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання plugin. | -| `qaRunners` | Ні | `object[]` | Полегшені дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання plugin. | -| `contracts` | Ні | `object` | Статичний знімок вбудованих capability для зовнішніх hook автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і належності tool. | -| `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` | Канонічний 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, коли auth, config або посилання на моделі згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, що використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | id channel, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | id provider, якими володіє цей Plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагого модуля виявлення provider, відносно кореня Plugin, для метаданих каталогу provider в межах маніфесту, які можна завантажити без активації повного runtime Plugin. | +| `modelSupport` | Ні | `object` | Короткі метадані model-family, що належать маніфесту і використовуються для автозавантаження Plugin до запуску runtime. | +| `providerEndpoints` | Ні | `object[]` | Метадані host/baseUrl endpoint, що належать маніфесту, для маршрутів provider, які core має класифікувати до завантаження runtime provider. | +| `cliBackends` | Ні | `string[]` | id backend CLI, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних посилань у config. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на provider або backend CLI, для яких слід перевіряти синтетичний hook auth, що належить Plugin, під час cold discovery моделей до завантаження runtime. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать вбудованому Plugin і представляють несекретний локальний стан, OAuth або ambient credential state. | +| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які повинні формувати діагностику config та CLI з урахуванням Plugin до завантаження runtime. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку auth/status provider. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це протягом періоду deprecation. | +| `providerAuthAliases` | Ні | `Record` | id provider, які повинні повторно використовувати інший id provider для пошуку auth, наприклад provider для кодування, що використовує той самий API key базового provider і профілі auth. | +| `channelEnvVars` | Ні | `Record` | Легковагі метадані env для channel, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для setup channel на основі env або поверхонь auth, які мають бачити загальні helper запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Легковагі метадані варіантів auth для селекторів onboarding, визначення preferred provider і простого зв’язування прапорців CLI. | +| `activation` | Ні | `object` | Легковагі метадані планувальника активації для завантаження за тригерами provider, command, channel, route і capability. Лише метадані; фактичною поведінкою все ще володіє runtime Plugin. | +| `setup` | Ні | `object` | Легковагі дескриптори setup/onboarding, які поверхні discovery та setup можуть перевіряти без завантаження runtime Plugin. | +| `qaRunners` | Ні | `object[]` | Легковагі дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження runtime Plugin. | +| `contracts` | Ні | `object` | Статичний знімок bundled capability для зовнішніх hook auth, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння tool. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легковагі типові значення media-understanding для id provider, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації channel, що належать маніфесту і об’єднуються в поверхні discovery та валідації до завантаження runtime. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. | +| `name` | Ні | `string` | Зрозуміла людині назва Plugin. | +| `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. | +| `version` | Ні | `string` | Інформаційна версія Plugin. | +| `uiHints` | Ні | `Record` | UI-мітки, placeholders і підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` -Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. -OpenClaw зчитує це до завантаження середовища виконання provider. -Потік налаштування provider спочатку віддає перевагу цим варіантам із маніфесту, а потім для сумісності повертається до метаданих wizard під час виконання та варіантів install catalog. +Кожен запис `providerAuthChoices` описує один варіант onboarding або auth. +OpenClaw зчитує це до завантаження runtime provider. +Потік setup provider надає перевагу цим варіантам із маніфесту, а потім для сумісності повертається до метаданих wizard runtime і варіантів install-catalog. | Поле | Обов’язкове | Тип | Що воно означає | | --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Id provider, якому належить цей варіант. | -| `method` | Так | `string` | Id методу автентифікації, до якого слід спрямувати. | -| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, що використовується потоками онбордингу та CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо поле не вказано, OpenClaw використовує `choiceId`. | +| `provider` | Так | `string` | id provider, до якого належить цей варіант. | +| `method` | Так | `string` | id методу auth, до якого слід спрямувати. | +| `choiceId` | Так | `string` | Стабільний id варіанта auth, який використовується потоками onboarding і CLI. | +| `choiceLabel` | Ні | `string` | Видима для користувача мітка. Якщо пропущено, OpenClaw використовує `choiceId`. | | `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих помічником. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант від селекторів помічника, але все одно дозволяє ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які повинні перенаправляти користувачів до цього варіанта-заміни. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих асистентом. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із селекторів асистента, але все ще дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які повинні перенаправляти користувачів до цього варіанта-замінника. | | `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Мітка для цієї групи, видима користувачу. | +| `groupLabel` | Ні | `string` | Видима для користувача мітка цієї групи. | | `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | +| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків auth з одним прапорцем. | | `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо поле не вказано, за замовчуванням це `["text-inference"]`. | +| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях onboarding має з’являтися цей варіант. Якщо пропущено, типово використовується `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли plugin володіє назвою команди під час виконання, яку користувачі можуть помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду середовища виконання plugin. +Використовуйте `commandAliases`, коли Plugin володіє назвою runtime-команди, яку користувачі можуть помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду runtime Plugin. ```json { @@ -201,21 +201,22 @@ OpenClaw зчитує це до завантаження середовища в } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, яка належить цьому plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash command чату, а не як кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід рекомендувати для операцій CLI, якщо така існує. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------ | ----------- | ----------------- | -------------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, що належить цьому Plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає alias як slash-команду чату, а не кореневу команду CLI. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід підказати для операцій CLI, якщо вона існує. | ## Довідник `activation` -Використовуйте `activation`, коли plugin може дешево оголосити, які події control plane повинні включати його в план активації/завантаження. +Використовуйте `activation`, коли Plugin може з мінімальними витратами оголосити, які події control plane мають включати його до плану активації/завантаження. -Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку під час виконання, не замінює `register(...)` і не гарантує, що код plugin уже був виконаний. Планувальник активації використовує ці поля, щоб звузити коло кандидатів серед plugin, перш ніж перейти до наявних метаданих належності з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hooks. +Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку runtime, не замінює `register(...)` і не гарантує, що код Plugin уже був виконаний. Планувальник активації використовує ці поля, щоб звузити коло кандидатів Plugin, перш ніж повертатися до наявних метаданих володіння з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hook. -Віддавайте перевагу найвужчим метаданим, які вже описують належність. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають цей зв’язок. Використовуйте `activation` для додаткових підказок планувальника, які не можна представити цими полями належності. +Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають цей зв’язок. Використовуйте `activation` для додаткових підказок планувальника, які неможливо подати через ці поля володіння. -Цей блок — лише метадані. Він не реєструє поведінку під час виконання й не замінює `register(...)`, `setupEntry` або інші точки входу runtime/plugin. Поточні споживачі використовують його як підказку для звуження кола кандидатів перед ширшим завантаженням plugin, тому відсутність метаданих `activation` зазвичай впливає лише на продуктивність; це не повинно змінювати коректність, доки ще існують застарілі резервні механізми належності маніфесту. +Цей блок містить лише метадані. Він не реєструє поведінку runtime і не замінює `register(...)`, `setupEntry` чи інші runtime/entrypoint Plugin. +Поточні споживачі використовують його як підказку для звуження кола перед ширшим завантаженням Plugin, тому відсутність метаданих активації зазвичай впливає лише на продуктивність; це не повинно змінювати коректність, доки все ще існують застарілі fallback-механізми володіння з маніфесту. ```json { @@ -231,27 +232,27 @@ OpenClaw зчитує це до завантаження середовища в | Поле | Обов’язкове | Тип | Що воно означає | | ---------------- | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Id provider, які повинні включати цей plugin до планів активації/завантаження. | -| `onCommands` | Ні | `string[]` | Id команд, які повинні включати цей plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Id channel, які повинні включати цей plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які повинні включати цей plugin до планів активації/завантаження. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки capability, що використовуються плануванням активації control plane. Якщо можливо, віддавайте перевагу вужчим полям. | +| `onProviders` | Ні | `string[]` | id provider, які повинні включати цей Plugin до планів активації/завантаження. | +| `onCommands` | Ні | `string[]` | id команд, які повинні включати цей Plugin до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | id channel, які повинні включати цей Plugin до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи route, які повинні включати цей Plugin до планів активації/завантаження. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки capability, що використовуються плануванням активації control plane. Коли можливо, надавайте перевагу вужчим полям. | -Поточні активні споживачі: +Поточні live-споживачі: - планування CLI, запущене командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` -- планування setup/channel, запущене channel, повертається до застарілої - належності `channels[]`, коли явні метадані активації channel відсутні -- планування setup/runtime, запущене provider, повертається до застарілої - належності `providers[]` і верхньорівневої `cliBackends[]`, коли явні метадані - активації provider відсутні +- setup/channel planning, запущене channel, повертається до застарілого + володіння `channels[]`, коли явні метадані активації channel відсутні +- setup/runtime planning, запущене provider, повертається до застарілого + володіння `providers[]` і `cliBackends[]` верхнього рівня, коли явні + метадані активації provider відсутні -Діагностика планувальника може розрізняти явні підказки активації та резервне використання належності маніфесту. Наприклад, `activation-command-hint` означає, що збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що планувальник натомість використав належність `commandAliases`. Ці мітки причин призначені для діагностики хоста та тестів; авторам plugin слід і надалі оголошувати метадані, які найкраще описують належність. +Діагностика планувальника може розрізняти явні підказки активації та fallback за володінням у маніфесті. Наприклад, `activation-command-hint` означає, що спрацював збіг `activation.onCommands`, тоді як `manifest-command-alias` означає, що планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для діагностики хоста і тестів; авторам Plugin слід і надалі оголошувати метадані, які найкраще описують володіння. ## Довідник `qaRunners` -Використовуйте `qaRunners`, коли plugin додає один або більше transport runner під спільним коренем `openclaw qa`. Зберігайте ці метадані легкими та статичними; фактичною реєстрацією CLI під час виконання все одно керує поверхня `runtime-api.ts`, що експортує `qaRunnerCliRegistrations`. +Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner у спільному корені `openclaw qa`. Зберігайте ці метадані легковагими та статичними; фактичною реєстрацією CLI все ще володіє runtime Plugin через легковагу поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { @@ -267,11 +268,11 @@ OpenClaw зчитує це до завантаження середовища в | Поле | Обов’язкове | Тип | Що воно означає | | ------------- | ----------- | -------- | ------------------------------------------------------------------- | | `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | -| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub command. | +| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. | ## Довідник `setup` -Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні легкі метадані plugin до завантаження runtime. +Використовуйте `setup`, коли поверхням setup і onboarding потрібні легковагі метадані Plugin до завантаження runtime. ```json { @@ -290,38 +291,38 @@ OpenClaw зчитує це до завантаження середовища в } ``` -Верхньорівневе `cliBackends` залишається валідним і далі описує backend CLI для inference. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків control plane/setup, які мають залишатися лише метаданими. +`cliBackends` верхнього рівня залишається чинним і далі описує backend CLI inference. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків control-plane/setup, які повинні залишатися лише метаданими. -Якщо `setup.providers` і `setup.cliBackends` присутні, вони є пріоритетною поверхнею пошуку на основі дескрипторів для виявлення setup. Якщо дескриптор лише звужує коло кандидатів plugin, а setup усе ще потребує багатших hook часу налаштування під час виконання, встановіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. +За наявності `setup.providers` і `setup.cliBackends` є бажаною поверхнею пошуку setup у стилі descriptor-first для discovery setup. Якщо дескриптор лише звужує коло кандидатів Plugin, а setup усе ще потребує багатших runtime-hook на етапі setup, встановіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` у загальні пошуки автентифікації provider і змінних середовища. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом періоду застарівання, але невбудовані plugin, які все ще його використовують, отримують діагностику маніфесту. Нові plugin повинні розміщувати метадані env для setup/статусу в `setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` у загальні пошуки auth provider і env var. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом періоду deprecation, але невбудовані Plugin, які все ще його використовують, отримують діагностику маніфесту. Нові Plugin повинні розміщувати метадані env для setup/status у `setup.providers[].envVars`. -Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише на дескриптори й не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо plugin, що має працювати лише через дескриптори, усе ж постачає один із цих runtime entry setup, OpenClaw повідомляє додаткову діагностику й продовжує ігнорувати його. Якщо `requiresRuntime` не вказано, зберігається застаріла резервна поведінка, щоб наявні plugin, які додали дескриптори без цього прапорця, не ламалися. +Встановлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише на рівні дескрипторів і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо Plugin, що працює лише на дескрипторах, усе ж містить один із цих runtime-entry setup, OpenClaw повідомляє про додаткову діагностику і продовжує його ігнорувати. Пропущене `requiresRuntime` зберігає застарілу fallback-поведінку, щоб не ламати наявні Plugin, які додали дескриптори без цього прапорця. -Оскільки пошук setup може виконувати код `setup-api`, що належить plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` повинні залишатися унікальними серед виявлених plugin. Неоднозначна належність завершується закритою відмовою замість вибору переможця за порядком виявлення. +Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед виявлених Plugin. Неоднозначне володіння закривається з відмовою, замість того щоб обирати переможця за порядком discovery. -Коли runtime setup усе ж виконується, діагностика реєстру setup повідомляє про розходження дескрипторів, якщо `setup-api` реєструє provider або backend CLI, яких не оголошують дескриптори маніфесту, або якщо дескриптор не має відповідної runtime-реєстрації. Ці діагностики є додатковими й не відхиляють застарілі plugin. +Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про розходження descriptor, якщо `setup-api` реєструє provider або backend CLI, який не оголошено в дескрипторах маніфесту, або якщо для дескриптора немає відповідної runtime-реєстрації. Ці діагностики є додатковими й не призводять до відхилення застарілих Plugin. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | ---------- | ---------------------------------------------------------------------------------- | -| `id` | Так | `string` | Id provider, який надається під час setup або онбордингу. Нормалізовані id мають бути глобально унікальними. | -| `authMethods` | Ні | `string[]` | Id методів setup/автентифікації, які цей provider підтримує без завантаження повного runtime. | -| `envVars` | Ні | `string[]` | Змінні середовища, які універсальні поверхні setup/статусу можуть перевіряти до завантаження runtime plugin. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------------- | +| `id` | Так | `string` | id provider, доступний під час setup або onboarding. Зберігайте нормалізовані id глобально унікальними. | +| `authMethods` | Ні | `string[]` | id методів setup/auth, які цей provider підтримує без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Env var, які загальні поверхні setup/status можуть перевіряти до завантаження runtime Plugin. | ### Поля `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 provider, доступні під час setup та onboarding. | +| `cliBackends` | Ні | `string[]` | id backend, що використовуються під час setup для пошуку setup у стилі descriptor-first. Зберігайте нормалізовані id глобально унікальними. | +| `configMigrations` | Ні | `string[]` | id міграцій config, якими володіє поверхня setup цього Plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. | ## Довідник `uiHints` -`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу. +`uiHints` — це мапа від назв полів config до невеликих підказок для рендерингу. ```json { @@ -338,18 +339,18 @@ OpenClaw також включає `setup.providers[].envVars` у загальн Кожна підказка для поля може містити: -| Поле | Тип | Що воно означає | -| ------------- | ---------- | --------------------------------------- | -| `label` | `string` | Мітка поля для користувача. | -| `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові теги UI. | -| `advanced` | `boolean` | Позначає поле як розширене. | -| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст-заповнювач для полів форми. | +| Поле | Тип | Що воно означає | +| ------------- | ---------- | ---------------------------------------- | +| `label` | `string` | Видима для користувача мітка поля. | +| `help` | `string` | Короткий допоміжний текст. | +| `tags` | `string[]` | Необов’язкові UI-теги. | +| `advanced` | `boolean` | Позначає поле як розширене. | +| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | +| `placeholder` | `string` | Текст placeholder для полів форми. | ## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих належності capability, які OpenClaw може зчитати без імпорту runtime plugin. +Використовуйте `contracts` лише для статичних метаданих володіння capability, які OpenClaw може зчитати без імпорту runtime Plugin. ```json { @@ -372,32 +373,31 @@ OpenClaw також включає `setup.providers[].envVars` у загальн Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | -------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Застарілі id фабрик вбудованих extension. | -| `agentToolResultMiddleware` | `string[]` | Id harness, для яких вбудований plugin може зареєструвати middleware результатів tool. | -| `externalAuthProviders` | `string[]` | Id provider, зовнішнім hook профілю автентифікації яких володіє цей 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 embedding для memory, якими володіє цей 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[]` | Назви agent tool, якими володіє цей plugin для перевірок bundled contract. | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | ----------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Застарілі id embedded extension factory. | +| `agentToolResultMiddleware` | `string[]` | id harness, для яких bundled Plugin може реєструвати middleware результатів tool. | +| `externalAuthProviders` | `string[]` | id provider, hook зовнішніх профілів auth яких належить цьому 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[]` | Назви agent tool, якими володіє цей Plugin для bundled-перевірок contract. | -`contracts.embeddedExtensionFactories` збережено для коду сумісності bundled, якому все ще потрібні прямі події вбудованого runner для Pi. Нові bundled-перетворення результатів tool повинні оголошувати `contracts.agentToolResultMiddleware` і натомість реєструватися через `api.registerAgentToolResultMiddleware(...)`. -Зовнішні plugin не можуть реєструвати middleware результатів tool, оскільки цей seam може переписувати високодовірений вивід tool до того, як його побачить модель. +`contracts.embeddedExtensionFactories` збережено для bundled-коду сумісності, якому все ще потрібні прямі події embedded-runner Pi. Нові bundled-перетворення результатів tool повинні оголошувати `contracts.agentToolResultMiddleware` і реєструватися через `api.registerAgentToolResultMiddleware(...)`. Зовнішні Plugin не можуть реєструвати middleware результатів tool, оскільки ця поверхня може переписувати high-trust-вивід tool до того, як модель його побачить. -Plugin provider, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють через застарілий резервний механізм сумісності, але він повільніший і буде видалений після завершення вікна міграції. +Plugin provider, що реалізують `resolveExternalAuthProfiles`, повинні оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють через застарілий fallback сумісності, але цей fallback повільніший і буде видалений після вікна міграції. -Bundled provider embedding для memory повинні оголошувати `contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони надають, включно з вбудованими адаптерами, такими як `local`. Автономні шляхи CLI використовують цей контракт маніфесту, щоб завантажувати лише plugin-власник до того, як повний runtime Gateway зареєструє provider. +Bundled provider memory embedding повинні оголошувати `contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони надають, включно з вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей contract маніфесту, щоб завантажувати лише Plugin-власник до того, як повний runtime Gateway зареєструє provider. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли provider media-understanding має моделі за замовчуванням, пріоритет резервної автоавтентифікації або нативну підтримку документів, які потрібні універсальним допоміжним засобам ядра до завантаження runtime. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. +Використовуйте `mediaUnderstandingProviderMetadata`, коли provider media-understanding має типові моделі, пріоритет fallback auto-auth або нативну підтримку документів, які потрібні загальним helper core до завантаження runtime. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json { @@ -422,16 +422,16 @@ Bundled provider embedding для memory повинні оголошувати ` Кожен запис provider може містити: -| Поле | Тип | Що воно означає | -| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------ | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості медіа, які надає цей provider. | -| `defaultModels` | `Record` | Значення моделей за замовчуванням для capability, які використовуються, коли конфігурація не задає модель. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору provider на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує provider. | +| Поле | Тип | Що воно означає | +| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості media, які надає цей provider. | +| `defaultModels` | `Record` | Типові значення model для capability, які використовуються, коли config не задає model. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback provider на основі credential. | +| `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні дані документів, які підтримує provider. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли plugin channel потребує легких метаданих конфігурації до завантаження runtime. +Використовуйте `channelConfigs`, коли Plugin channel потребує легковагих метаданих config до завантаження runtime. Discovery setup/status channel лише для читання може використовувати ці метадані безпосередньо для налаштованих зовнішніх channel, коли запис setup недоступний або коли `setup.requiresRuntime: false` оголошує runtime setup непотрібним. ```json { @@ -460,17 +460,17 @@ Bundled provider embedding для memory повинні оголошувати ` Кожен запис channel може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | --------------------------------------------------------------------------------------- | -| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації channel. | -| `uiHints` | `Record` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації channel. | -| `label` | `string` | Мітка channel, яка об’єднується в поверхні вибору та інспекції, коли метадані runtime ще не готові. | -| `description` | `string` | Короткий опис channel для поверхонь інспекції та catalog. | -| `preferOver` | `string[]` | Id застарілих plugin або plugin із нижчим пріоритетом, які цей channel має випереджати в поверхнях вибору. | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ | +| `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису config channel. | +| `uiHints` | `Record` | Необов’язкові UI-мітки/placeholders/підказки чутливості для цього розділу config channel. | +| `label` | `string` | Мітка channel, що об’єднується в поверхнях вибору та inspect, коли метадані runtime ще не готові. | +| `description` | `string` | Короткий опис channel для поверхонь inspect і catalog. | +| `preferOver` | `string[]` | id застарілих або менш пріоритетних Plugin, які цей channel має перевершувати в поверхнях вибору. | ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має виводити ваш plugin provider із скорочених id моделей, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження runtime plugin. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin provider із скорочених id model, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження runtime Plugin. ```json { @@ -483,71 +483,70 @@ Bundled provider embedding для memory повинні оголошувати ` OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers` plugin-власника -- `modelPatterns` мають пріоритет над `modelPrefixes` -- якщо збігаються один невбудований plugin і один вбудований plugin, перемагає невбудований plugin -- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже provider +- явні посилання `provider/model` використовують метадані маніфесту `providers` Plugin-власника +- `modelPatterns` мають вищий пріоритет за `modelPrefixes` +- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований Plugin +- решта неоднозначностей ігноруються, доки користувач або config не вкаже provider Поля: -| Поле | Тип | Що воно означає | -| --------------- | ---------- | ------------------------------------------------------------------------------------ | -| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id моделей. | -| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id моделей після видалення суфікса профілю. | +| Поле | Тип | Що воно означає | +| --------------- | ---------- | -------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id model. | +| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id model після видалення суфікса profile. | -Застарілі ключі capability верхнього рівня не рекомендуються до використання. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` у `contracts`; звичайне завантаження маніфесту більше не розглядає ці поля верхнього рівня як належність capability. +Застарілі ключі capability верхнього рівня не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб перенести `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під `contracts`; звичайне завантаження маніфесту більше не розглядає ці поля верхнього рівня як володіння capability. -## Маніфест і `package.json` +## Маніфест проти package.json Ці два файли виконують різні завдання: -| Файл | Для чого використовувати | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду plugin | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, обмежень встановлення, setup або метаданих catalog | +| Файл | Використовуйте його для | +| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Discovery, валідації config, метаданих варіантів auth і підказок UI, які мають існувати до запуску коду Plugin | +| `package.json` | Метаданих npm, встановлення залежностей і блока `openclaw`, який використовується для entrypoint, обмежень встановлення, setup або метаданих catalog | -Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте таке правило: +Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило: -- якщо OpenClaw повинен знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів входу або поведінки встановлення npm, помістіть це в `package.json` +- якщо OpenClaw має знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json` +- якщо це стосується пакування, файлів entrypoint або поведінки встановлення npm, розміщуйте це в `package.json` -### Поля `package.json`, які впливають на виявлення +### Поля `package.json`, що впливають на discovery -Деякі метадані plugin до запуску runtime навмисно розміщено в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. +Деякі метадані Plugin до запуску runtime навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: | Поле | Що воно означає | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | Оголошує власні точки входу plugin. Має залишатися в межах каталогу пакета plugin. | -| `openclaw.runtimeExtensions` | Оголошує зібрані точки входу runtime JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета plugin. | -| `openclaw.setupEntry` | Полегшена точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску channel та виявлення status/SecretRef channel тільки для читання. Має залишатися в межах каталогу пакета plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує зібрану точку входу setup JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета plugin. | -| `openclaw.channel` | Полегшені метадані catalog channel, як-от мітки, шляхи до docs, псевдоніми та текст для вибору. | -| `openclaw.channel.configuredState` | Полегшені метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує setup лише через env?» без завантаження повного runtime channel. | -| `openclaw.channel.persistedAuthState` | Полегшені метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже є якийсь вхід у систему?» без завантаження повного 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` | Оголошує entrypoint власного Plugin. Має залишатися в каталозі пакета Plugin. | +| `openclaw.runtimeExtensions` | Оголошує entrypoint runtime built JavaScript для встановлених пакетів. Має залишатися в каталозі пакета Plugin. | +| `openclaw.setupEntry` | Легковагий entrypoint лише для setup, який використовується під час onboarding, відкладеного запуску channel і discovery статусу channel/SecretRef лише для читання. Має залишатися в каталозі пакета Plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript entrypoint setup для встановлених пакетів. Має залишатися в каталозі пакета Plugin. | +| `openclaw.channel` | Легковагі метадані каталогу channel, такі як мітки, шляхи до документації, alias і текст для вибору. | +| `openclaw.channel.configuredState` | Легковагі метадані перевірки configured-state, які можуть відповісти на питання «чи вже існує setup лише через env?» без завантаження повного runtime channel. | +| `openclaw.channel.persistedAuthState` | Легковагі метадані перевірки persisted-auth, які можуть відповісти на питання «чи вже є якийсь виконаний вхід?» без завантаження повного runtime channel. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для bundled і зовнішньо опублікованих Plugin. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, із нижньою межею semver на кшталт `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт відносно нього. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення bundled Plugin, коли config некоректний. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного Plugin channel під час запуску. | -Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в онбордингу до завантаження runtime. `package.json#openclaw.install` повідомляє онбордингу, як отримати або ввімкнути цей plugin, коли користувач вибирає один із цих варіантів. -Не переміщуйте підказки встановлення в `openclaw.plugin.json`. +Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в onboarding до завантаження runtime. `package.json#openclaw.install` повідомляє onboarding, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`. -`openclaw.install.minHostVersion` перевіряється під час встановлення та завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають plugin на старіших хостах. +`openclaw.install.minHostVersion` застосовується під час встановлення і завантаження реєстру маніфесту. Некоректні значення відхиляються; новіші, але коректні значення пропускають Plugin на старіших хостах. -Точне закріплення версії npm уже міститься в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього catalog повинні поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися закритою відмовою, якщо отриманий npm-артефакт більше не відповідає закріпленому релізу. -Для сумісності інтерактивний онбординг усе ще пропонує npm-специфікації довіреного реєстру, включно з простими назвами пакетів і dist-tag. Діагностика catalog може розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю назви пакета та невалідні джерела default-choice. Вона також попереджає, коли `expectedIntegrity` присутній, але немає валідного джерела npm, яке можна ним закріпити. -Коли `expectedIntegrity` присутній, потоки встановлення/оновлення примусово його застосовують; коли його не вказано, результат розв’язання реєстру фіксується без закріплення цілісності. +Точне закріплення версії npm уже розміщується в `npmSpec`, наприклад +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися відмовою, якщо отриманий npm-артефакт більше не відповідає закріпленому релізу. +Інтерактивний onboarding усе ще пропонує npm-специфікації довіреного реєстру, зокрема прості назви пакетів і dist-tag, для сумісності. Діагностика каталогу може розрізняти точні, плаваючі, закріплені за цілісністю, без закріплення цілісності, з невідповідністю імені пакета та некоректні джерела default-choice. Вона також попереджає, коли `expectedIntegrity` присутній, але немає коректного джерела npm, яке можна ним закріпити. +Коли `expectedIntegrity` присутній, потоки встановлення/оновлення застосовують його; коли його пропущено, визначення реєстру записується без закріплення цілісності. -Plugin channel повинні надавати `openclaw.setupEntry`, коли перевіркам status, списку channel або SecretRef потрібно визначати налаштовані облікові записи без завантаження повного runtime. Точка входу setup повинна надавати метадані channel разом із безпечними для setup адаптерами конфігурації, status і secrets; мережеві клієнти, слухачі Gateway та transport runtime слід залишати в основній точці входу extension. +Plugin channel повинні надавати `openclaw.setupEntry`, коли статус, список channel або сканування SecretRef мають визначати налаштовані акаунти без завантаження повного runtime. Запис setup повинен надавати метадані channel разом із безпечними для setup адаптерами config, status і secrets; мережеві клієнти, listener Gateway і transport runtime залишайте в основному entrypoint extension. -Поля точок входу runtime не скасовують перевірки меж пакета для полів точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити завантажуваним шлях `openclaw.extensions`, що виходить за межі пакета. +Поля runtime entrypoint не перевизначають перевірки меж пакета для полів source entrypoint. Наприклад, `openclaw.runtimeExtensions` не може зробити придатним до завантаження шлях `openclaw.extensions`, що виходить за межі пакета. -`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке призначення. Воно не робить довільні зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам встановлення відновлюватися після конкретних застарілих збоїв оновлення вбудованого plugin, таких як відсутній шлях до вбудованого plugin або застарілий запис `channels.` для того самого вбудованого plugin. Непов’язані помилки конфігурації все одно блокують встановлення й спрямовують операторів до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не робить довільні зламані config придатними до встановлення. Наразі він лише дозволяє потокам встановлення відновлюватися після певних застарілих збоїв оновлення bundled Plugin, наприклад відсутнього шляху bundled Plugin або застарілого запису `channels.` для того самого bundled Plugin. Непов’язані помилки config усе ще блокують встановлення й спрямовують операторів до `openclaw doctor --fix`. `openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки: @@ -565,9 +564,9 @@ Plugin channel повинні надавати `openclaw.setupEntry`, коли } ``` -Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка автентифікації типу так/ні до завантаження повного plugin channel. Цільовий export має бути невеликою функцією, яка читає лише збережений стан; не спрямовуйте її через повний barrel runtime channel. +Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка auth типу так/ні до завантаження повного Plugin channel. Цільовий export має бути невеликою функцією, яка читає лише збережений стан; не спрямовуйте її через широкий barrel повного runtime channel. -`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок налаштованого стану лише через env: +`openclaw.channel.configuredState` має таку саму форму для дешевих перевірок configured-state лише через env: ```json { @@ -583,62 +582,64 @@ Plugin channel повинні надавати `openclaw.setupEntry`, коли } ``` -Використовуйте це, коли channel може визначити налаштований стан через env або інші малі невruntime-входи. Якщо перевірка потребує повного розв’язання конфігурації або справжнього runtime channel, залишайте цю логіку в hook plugin `config.hasConfiguredState`. +Використовуйте це, коли channel може визначити configured-state з env або інших невеликих нерuntime-вхідних даних. Якщо перевірка потребує повного визначення config або реального runtime channel, залишайте цю логіку в hook Plugin `config.hasConfiguredState`. -## Пріоритет виявлення (дублікати id plugin) +## Пріоритет discovery (дублікати id Plugin) -OpenClaw виявляє plugin із кількох коренів (вбудовані, глобальне встановлення, workspace, шляхи, явно вибрані конфігурацією). Якщо два виявлені plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. +OpenClaw виявляє Plugin з кількох коренів (bundled, global install, workspace, явно вибрані в config шляхи). Якщо два результати discovery мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч. Пріоритет від найвищого до найнижчого: -1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` -2. **Вбудований** — plugin, які постачаються разом з OpenClaw -3. **Глобальне встановлення** — plugin, встановлені в глобальний корінь plugin OpenClaw -4. **Workspace** — plugin, виявлені відносно поточного workspace +1. **Config-selected** — шлях, явно закріплений у `plugins.entries.` +2. **Bundled** — Plugin, що постачаються з OpenClaw +3. **Global install** — Plugin, встановлені в глобальний корінь Plugin OpenClaw +4. **Workspace** — Plugin, виявлені відносно поточного workspace Наслідки: -- Розгалужена або застаріла копія вбудованого plugin у workspace не затьмарить вбудовану збірку. -- Щоб справді перевизначити вбудований plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення у workspace. -- Відкидання дублікатів фіксується в журналі, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. +- Форк або застаріла копія bundled Plugin, що лежить у workspace, не затьмарить bundled-збірку. +- Щоб справді перевизначити bundled Plugin локальним, закріпіть його через `plugins.entries.`, щоб він виграв за пріоритетом, а не покладайтеся на discovery workspace. +- Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказувати на відкинуту копію. ## Вимоги до JSON Schema -- **Кожен plugin повинен містити JSON Schema**, навіть якщо він не приймає конфігурацію. -- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Схеми перевіряються під час читання/запису конфігурації, а не під час виконання. +- **Кожен Plugin повинен містити JSON Schema**, навіть якщо він не приймає config. +- Порожня schema допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Schema проходять валідацію під час читання/запису config, а не під час runtime. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки id channel не оголошено в маніфесті plugin. -- `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` повинні посилатися на id plugin, які **можна виявити**. Невідомі id є **помилками**. -- Якщо plugin установлено, але його маніфест або схема зламані чи відсутні, валідація завершується помилкою, а Doctor повідомляє про помилку plugin. -- Якщо конфігурація plugin існує, але сам plugin **вимкнений**, конфігурація зберігається, а в Doctor + журналах показується **попередження**. +- Невідомі ключі `channels.*` є **помилками**, якщо тільки id channel не оголошено в маніфесті Plugin. +- `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` + повинні посилатися на **доступні для discovery** id Plugin. Невідомі id є **помилками**. +- Якщо Plugin встановлено, але він має зламаний або відсутній маніфест чи schema, + валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. +- Якщо config Plugin існує, але Plugin **вимкнено**, config зберігається, а в Doctor і логах з’являється **попередження**. -Повну схему `plugins.*` дивіться тут: [Довідник конфігурації](/uk/gateway/configuration). +Дивіться [Довідник з конфігурації](/uk/gateway/configuration) для повної schema `plugins.*`. ## Примітки -- Маніфест **обов’язковий для власних Plugin OpenClaw**, включно із завантаженням із локальної файлової системи. Runtime усе одно завантажує модуль plugin окремо; маніфест потрібен лише для виявлення + валідації. -- Власні маніфести парсяться за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, якщо фінальне значення все одно залишається об’єктом. -- Завантажувач маніфесту читає лише документовані поля маніфесту. Уникайте власних ключів верхнього рівня. -- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо plugin їх не потребує. -- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих catalog provider або вузьких дескрипторів виявлення, а не для виконання під час обробки запитів. -- Ексклюзивні типи plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (за замовчуванням `legacy`). -- Метадані змінних середовища (`setup.providers[].envVars`, застаріле `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Status, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до plugin і ефективної активації, перш ніж вважати змінну середовища налаштованою. -- Для метаданих runtime wizard, які потребують коду provider, дивіться [Runtime hooks provider](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш plugin залежить від native modules, задокументуйте кроки збірки та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Маніфест є **обов’язковим для власних Plugin OpenClaw**, зокрема для локальних завантажень із файлової системи. Runtime усе ще завантажує модуль Plugin окремо; маніфест використовується лише для discovery + валідації. +- Власні маніфести розбираються через JSON5, тож коментарі, завершальні коми й ключі без лапок приймаються, якщо кінцеве значення все одно є об’єктом. +- Завантажувач маніфесту зчитує лише документовані поля маніфесту. Уникайте власних ключів верхнього рівня. +- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує. +- `providerDiscoveryEntry` має залишатися легковагим і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу provider або вузьких дескрипторів discovery, а не для виконання під час обробки запитів. +- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). +- Метадані env var (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Status, audit, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до Plugin і ефективної активації, перш ніж вважати env var налаштованою. +- Для метаданих runtime wizard, які потребують коду provider, дивіться [Runtime-hook provider](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш Plugin залежить від native modules, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). -## Пов’язані матеріали +## Пов’язане - - Початок роботи з plugin. + + Початок роботи з Plugin. - + Внутрішня архітектура та модель capability. - Довідник SDK plugin та імпорти підшляхів. + Довідник SDK Plugin та імпорти підшляхів.