chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
9c71964216
commit
df09e3cdb9
File diff suppressed because it is too large
Load Diff
@ -2,52 +2,63 @@
|
||||
read_when:
|
||||
- Ви створюєте Plugin для OpenClaw
|
||||
- Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin
|
||||
summary: Вимоги до маніфесту Plugin + JSON schema (сувора валідація конфігурації)
|
||||
summary: Вимоги до маніфесту Plugin і JSON schema (сувора валідація конфігурації)
|
||||
title: Маніфест Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T20:11:32Z"
|
||||
generated_at: "2026-04-24T20:18:19Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: ac25782f26abe79875c25abcd6f7b53fbe7a3c7b139c80c8a1a6675e69d6529c
|
||||
source_hash: 6b2849737f9d785ff15a7988cfaf6515cbabce2901e2da4f2c72007d302f41f2
|
||||
source_path: plugins/manifest.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Ця сторінка призначена лише для **рідного маніфесту Plugin OpenClaw**.
|
||||
Ця сторінка стосується лише **власного маніфесту Plugin OpenClaw**.
|
||||
|
||||
Сумісні компонування бандлів див. у [бандлах Plugin](/uk/plugins/bundles).
|
||||
Сумісні компонування пакетів описано тут: [Пакети Plugin](/uk/plugins/bundles).
|
||||
|
||||
Сумісні формати бандлів використовують інші файли маніфесту:
|
||||
Сумісні формати пакетів використовують інші файли маніфесту:
|
||||
|
||||
- бандл Codex: `.codex-plugin/plugin.json`
|
||||
- бандл Claude: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude без маніфесту
|
||||
- бандл Cursor: `.cursor-plugin/plugin.json`
|
||||
- Пакет Codex: `.codex-plugin/plugin.json`
|
||||
- Пакет Claude: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude
|
||||
без маніфесту
|
||||
- Пакет Cursor: `.cursor-plugin/plugin.json`
|
||||
|
||||
OpenClaw також автоматично виявляє ці компонування бандлів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут.
|
||||
OpenClaw також автоматично визначає ці компонування пакетів, але вони не проходять валідацію
|
||||
за схемою `openclaw.plugin.json`, описаною тут.
|
||||
|
||||
Для сумісних бандлів OpenClaw наразі зчитує метадані бандла, а також оголошені корені навичок, корені команд Claude, типові значення `settings.json` бандла Claude, типові значення LSP бандла Claude і підтримувані набори хуків, якщо компонування відповідає очікуванням рантайму OpenClaw.
|
||||
Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені
|
||||
корені навичок, корені команд Claude, типові значення `settings.json` пакета Claude,
|
||||
типові значення LSP пакета Claude та підтримувані набори хуків, коли компонування
|
||||
відповідає очікуванням рантайму OpenClaw.
|
||||
|
||||
Кожен рідний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у **корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду Plugin**. Відсутні або невалідні маніфести розглядаються як помилки Plugin і блокують валідацію конфігурації.
|
||||
Кожен власний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у
|
||||
**корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації
|
||||
**без виконання коду Plugin**. Відсутні або некоректні маніфести вважаються
|
||||
помилками Plugin і блокують валідацію конфігурації.
|
||||
|
||||
Повний посібник із системи Plugin див. тут: [Plugins](/uk/tools/plugin).
|
||||
Щодо рідної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності див.:
|
||||
[модель можливостей](/uk/plugins/architecture#public-capability-model).
|
||||
Про власну модель можливостей і поточні рекомендації щодо зовнішньої сумісності:
|
||||
[Модель можливостей](/uk/plugins/architecture#public-capability-model).
|
||||
|
||||
## Що робить цей файл
|
||||
|
||||
`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду вашого Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску рантайму Plugin.
|
||||
`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду
|
||||
вашого Plugin**. Усе нижче має бути достатньо недорогим для перевірки без запуску
|
||||
рантайму Plugin.
|
||||
|
||||
**Використовуйте його для:**
|
||||
|
||||
- ідентичності Plugin, валідації конфігурації та підказок для UI конфігурації
|
||||
- метаданих автентифікації, онбордингу та налаштування (аліас, автоувімкнення, змінні середовища провайдера, варіанти автентифікації)
|
||||
- підказок активації для поверхонь control-plane
|
||||
- володіння скороченими сімействами моделей
|
||||
- скороченого володіння сімействами моделей
|
||||
- статичних знімків володіння можливостями (`contracts`)
|
||||
- метаданих QA runner, які може перевіряти спільний хост `openclaw qa`
|
||||
- метаданих конфігурації, специфічних для каналу, що об’єднуються в surfaces каталогу та валідації
|
||||
- метаданих конфігурації, специфічних для каналу, що об’єднуються в каталог і поверхні валідації
|
||||
|
||||
**Не використовуйте його для:** реєстрації поведінки рантайму, оголошення точок входу коду або метаданих встановлення npm. Для цього призначені код вашого Plugin і `package.json`.
|
||||
**Не використовуйте його для:** реєстрації поведінки рантайму, оголошення точок входу коду
|
||||
або метаданих встановлення npm. Це належить до коду вашого Plugin і `package.json`.
|
||||
|
||||
## Мінімальний приклад
|
||||
|
||||
@ -129,64 +140,68 @@ OpenClaw також автоматично виявляє ці компонув
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Канонічний id Plugin. Це id, який використовується в `plugins.entries.<id>`. |
|
||||
| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. |
|
||||
| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Не вказуйте це поле або встановіть будь-яке значення, відмінне від `true`, щоб Plugin лишався вимкненим за замовчуванням. |
|
||||
| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id Plugin. |
|
||||
| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які повинні автоматично вмикати цей Plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. |
|
||||
| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. |
|
||||
| `channels` | Ні | `string[]` | Id каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. |
|
||||
| `providers` | Ні | `string[]` | Id провайдерів, якими володіє цей Plugin. |
|
||||
| `providerDiscoveryEntry` | Ні | `string` | Шлях до легкого модуля виявлення провайдера, відносний до кореня Plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного рантайму Plugin. |
|
||||
| `modelSupport` | Ні | `object` | Метадані скорочених сімейств моделей, якими володіє маніфест і які використовуються для автозавантаження Plugin до запуску рантайму. |
|
||||
| `providerEndpoints` | Ні | `object[]` | Метадані хостів endpoint/baseUrl, якими володіє маніфест, для маршрутів провайдерів, які ядро має класифікувати до завантаження рантайму провайдера. |
|
||||
| `cliBackends` | Ні | `string[]` | Id CLI-бекендів інференсу, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних посилань у конфігурації. |
|
||||
| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або CLI-бекенди, для яких слід перевіряти синтетичний хук автентифікації, яким володіє Plugin, під час холодного виявлення моделей до завантаження рантайму. |
|
||||
| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, якими володіє вбудований Plugin і які представляють не секретний локальний стан, OAuth або стан ambient credentials. |
|
||||
| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які повинні формувати діагностику конфігурації та CLI з урахуванням Plugin до завантаження рантайму. |
|
||||
| `providerAuthEnvVars` | Ні | `Record<string, string[]>` | Застарілі сумісні метадані env для пошуку автентифікації/статусу провайдера. Для нових Plugin віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це під час вікна депрекації. |
|
||||
| `providerAuthAliases` | Ні | `Record<string, string>` | Id провайдерів, які повинні повторно використовувати id іншого провайдера для пошуку автентифікації, наприклад провайдер для кодування, який використовує той самий API-ключ базового провайдера та профілі автентифікації. |
|
||||
| `channelEnvVars` | Ні | `Record<string, string[]>` | Легкі метадані env каналу, які OpenClaw може перевірити без завантаження коду Plugin. Використовуйте це для налаштування каналів через env або поверхонь автентифікації, які мають бачити загальні допоміжні засоби запуску/конфігурації. |
|
||||
| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для селекторів онбордингу, визначення бажаного провайдера та простого зв’язування CLI-прапорців. |
|
||||
| `activation` | Ні | `object` | Легкі метадані планувальника активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактичною поведінкою, як і раніше, володіє рантайм Plugin. |
|
||||
| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження рантайму Plugin. |
|
||||
| `qaRunners` | Ні | `object[]` | Легкі дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження рантайму Plugin. |
|
||||
| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, вебпошуку та володіння інструментами. |
|
||||
| `mediaUnderstandingProviderMetadata` | Ні | `Record<string, object>` | Легкі типові значення для розуміння медіа для id провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. |
|
||||
| `channelConfigs` | Ні | `Record<string, object>` | Метадані конфігурації каналів, якими володіє маніфест і які об’єднуються в поверхні виявлення та валідації до завантаження рантайму. |
|
||||
| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореня Plugin. |
|
||||
| `name` | Ні | `string` | Зрозуміла людині назва Plugin. |
|
||||
| `description` | Ні | `string` | Короткий опис, який показується в поверхнях Plugin. |
|
||||
| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Це ідентифікатор, що використовується в `plugins.entries.<id>`. |
|
||||
| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. |
|
||||
| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений типово. Не вказуйте це поле або задайте будь-яке значення, відмінне від `true`, щоб Plugin залишався вимкненим типово. |
|
||||
| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора Plugin. |
|
||||
| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей Plugin, коли на них посилаються автентифікація, конфігурація або посилання на моделі. |
|
||||
| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, що використовується `plugins.slots.*`. |
|
||||
| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. |
|
||||
| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей Plugin. |
|
||||
| `providerDiscoveryEntry` | Ні | `string` | Полегшений шлях до модуля виявлення провайдера, відносно кореня Plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного рантайму Plugin. |
|
||||
| `modelSupport` | Ні | `object` | Короткі метадані сімейств моделей, що належать маніфесту та використовуються для автоматичного завантаження Plugin до запуску рантайму. |
|
||||
| `providerEndpoints` | Ні | `object[]` | Метадані хостів endpoint/baseUrl, що належать маніфесту, для маршрутів провайдера, які ядро має класифікувати до завантаження рантайму провайдера. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів інференсу CLI, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних посилань у конфігурації. |
|
||||
| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдер або бекенд CLI, для яких слід перевіряти синтетичний хук автентифікації, що належить Plugin, під час холодного виявлення моделей до завантаження рантайму. |
|
||||
| `nonSecretAuthMarkers` | Ні | `string[]` | Значення API-ключів-заповнювачів, що належать вбудованому Plugin і позначають несекретний локальний стан, стан OAuth або стан ambient credentials. |
|
||||
| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які мають формувати діагностику конфігурації та CLI з урахуванням Plugin до завантаження рантайму. |
|
||||
| `providerAuthEnvVars` | Ні | `Record<string, string[]>` | Застарілі сумісні метадані env для пошуку автентифікації/статусу провайдера. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це під час вікна знецінення. |
|
||||
| `providerAuthAliases` | Ні | `Record<string, string>` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер кодування, який використовує той самий API-ключ базового провайдера й auth profiles. |
|
||||
| `channelEnvVars` | Ні | `Record<string, string[]>` | Легкі метадані env каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналу через env або поверхонь автентифікації, які мають бачити типові хелпери запуску/конфігурації. |
|
||||
| `providerAuthChoices` | Ні | `object[]` | Легкі метадані варіантів автентифікації для селекторів онбордингу, визначення пріоритетного провайдера та простого зв’язування прапорців CLI. |
|
||||
| `activation` | Ні | `object` | Легкі метадані планувальника активації для завантаження, що запускається провайдером, командою, каналом, маршрутом або можливістю. Лише метадані; фактичною поведінкою все одно володіє рантайм Plugin. |
|
||||
| `setup` | Ні | `object` | Легкі дескриптори налаштування/онбордингу, які поверхні виявлення й налаштування можуть перевіряти без завантаження рантайму Plugin. |
|
||||
| `qaRunners` | Ні | `object[]` | Легкі дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження рантайму Plugin. |
|
||||
| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. |
|
||||
| `mediaUnderstandingProviderMetadata` | Ні | `Record<string, object>` | Легкі типові значення media-understanding для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. |
|
||||
| `channelConfigs` | Ні | `Record<string, object>` | Метадані конфігурації каналу, що належать маніфесту й об’єднуються в поверхні виявлення та валідації до завантаження рантайму. |
|
||||
| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. |
|
||||
| `name` | Ні | `string` | Людинозрозуміла назва Plugin. |
|
||||
| `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. |
|
||||
| `version` | Ні | `string` | Інформаційна версія Plugin. |
|
||||
| `uiHints` | Ні | `Record<string, object>` | UI-мітки, плейсхолдери та підказки щодо чутливості для полів конфігурації. |
|
||||
| `uiHints` | Ні | `Record<string, object>` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. |
|
||||
|
||||
## Довідник `providerAuthChoices`
|
||||
|
||||
Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації.
|
||||
OpenClaw зчитує це до завантаження рантайму провайдера.
|
||||
Потік налаштування провайдера надає перевагу цим варіантам із маніфесту, а потім для сумісності
|
||||
переходить до метаданих майстра рантайму та варіантів каталогу встановлення.
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| --------------------- | ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | Так | `string` | Id провайдера, до якого належить цей варіант. |
|
||||
| `method` | Так | `string` | Id методу автентифікації, до якого слід спрямувати обробку. |
|
||||
| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, який використовується в потоках онбордингу та CLI. |
|
||||
| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. |
|
||||
| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. |
|
||||
| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих асистентом. |
|
||||
| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із селекторів асистента, але все ще дозволяє ручний вибір через CLI. |
|
||||
| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів до цього варіанта-заміни. |
|
||||
| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. |
|
||||
| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. |
|
||||
| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
|
||||
| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. |
|
||||
| `cliFlag` | Ні | `string` | Назва CLI-прапорця, наприклад `--openrouter-api-key`. |
|
||||
| `cliOption` | Ні | `string` | Повна форма CLI-опції, наприклад `--openrouter-api-key <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 <key>`. |
|
||||
| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. |
|
||||
| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. |
|
||||
|
||||
## Довідник `commandAliases`
|
||||
|
||||
Використовуйте `commandAliases`, коли Plugin володіє іменем runtime-команди, яке користувачі можуть помилково вказати в `plugins.allow` або спробувати запустити як кореневу CLI-команду. OpenClaw використовує ці метадані для діагностики без імпорту коду рантайму Plugin.
|
||||
Використовуйте `commandAliases`, коли Plugin володіє назвою команди рантайму, яку користувачі можуть
|
||||
помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw
|
||||
використовує ці метадані для діагностики без імпорту коду рантайму Plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -200,21 +215,34 @@ OpenClaw зчитує це до завантаження рантайму про
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------ | ----------- | ----------------- | -------------------------------------------------------------------------- |
|
||||
| `name` | Так | `string` | Назва команди, яка належить цьому Plugin. |
|
||||
| `kind` | Ні | `"runtime-slash"` | Позначає аліас як slash-команду чату, а не кореневу CLI-команду. |
|
||||
| `cliCommand` | Ні | `string` | Пов’язана коренева CLI-команда, яку слід рекомендувати для CLI-операцій, якщо така існує. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------- |
|
||||
| `name` | Так | `string` | Назва команди, що належить цьому Plugin. |
|
||||
| `kind` | Ні | `"runtime-slash"` | Позначає аліас як slash-команду чату, а не як кореневу команду CLI. |
|
||||
| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід підказати для операцій CLI, якщо вона існує. |
|
||||
|
||||
## Довідник `activation`
|
||||
|
||||
Використовуйте `activation`, коли Plugin може дешево оголосити, які події control-plane повинні включати його до плану активації/завантаження.
|
||||
Використовуйте `activation`, коли Plugin може з низькими витратами оголосити, які події control-plane
|
||||
мають включати його до плану активації/завантаження.
|
||||
|
||||
Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку рантайму, не замінює `register(...)` і не гарантує, що код Plugin уже був виконаний. Планувальник активації використовує ці поля, щоб звузити коло кандидатів Plugin, перш ніж перейти до наявних метаданих володіння з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hooks.
|
||||
Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє
|
||||
поведінку рантайму, не замінює `register(...)` і не обіцяє, що код
|
||||
Plugin уже виконувався. Планувальник активації використовує ці поля для звуження
|
||||
кандидатів Plugin перед переходом до наявних метаданих володіння з маніфесту, таких як
|
||||
`providers`, `channels`, `commandAliases`, `setup.providers`,
|
||||
`contracts.tools` і хуки.
|
||||
|
||||
Віддавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальника, які не можна представити цими полями володіння.
|
||||
Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте
|
||||
`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`,
|
||||
коли ці поля виражають відповідний зв’язок. Використовуйте `activation` для додаткових підказок планувальника,
|
||||
які не можна представити цими полями володіння.
|
||||
|
||||
Цей блок містить лише метадані. Він не реєструє поведінку рантайму і не замінює `register(...)`, `setupEntry` або інші runtime/Plugin entrypoints. Поточні споживачі використовують його як підказку для звуження вибору перед ширшим завантаженням Plugin, тож відсутність метаданих активації зазвичай впливає лише на продуктивність; це не повинно змінювати коректність, доки ще існують застарілі fallback-механізми володіння з маніфесту.
|
||||
Цей блок є лише метаданими. Він не реєструє поведінку рантайму і не
|
||||
замінює `register(...)`, `setupEntry` або інші точки входу рантайму/Plugin.
|
||||
Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому
|
||||
відсутність метаданих активації зазвичай впливає лише на продуктивність; це не має
|
||||
змінювати коректність, поки ще існують застарілі fallback-механізми володіння з маніфесту.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -228,27 +256,37 @@ OpenClaw зчитує це до завантаження рантайму про
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ---------------- | ----------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `onProviders` | Ні | `string[]` | Id провайдерів, які повинні включати цей Plugin до планів активації/завантаження. |
|
||||
| `onCommands` | Ні | `string[]` | Id команд, які повинні включати цей Plugin до планів активації/завантаження. |
|
||||
| `onChannels` | Ні | `string[]` | Id каналів, які повинні включати цей Plugin до планів активації/завантаження. |
|
||||
| `onRoutes` | Ні | `string[]` | Типи маршрутів, які повинні включати цей Plugin до планів активації/завантаження. |
|
||||
| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки щодо можливостей, які використовуються під час планування активації control-plane. Якщо можливо, віддавайте перевагу вужчим полям. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ---------------- | ----------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження. |
|
||||
| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. |
|
||||
| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження. |
|
||||
| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. |
|
||||
| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки можливостей, що використовуються плануванням активації control-plane. Якщо можливо, надавайте перевагу вужчим полям. |
|
||||
|
||||
Поточні активні споживачі:
|
||||
|
||||
- планування CLI, що запускається командою, використовує fallback до застарілих
|
||||
- планування CLI, що запускається командою, повертається до застарілих
|
||||
`commandAliases[].cliCommand` або `commandAliases[].name`
|
||||
- планування setup/каналів, що запускається каналом, використовує fallback до застарілого володіння `channels[]`, якщо явні метадані активації каналу відсутні
|
||||
- планування setup/runtime, що запускається провайдером, використовує fallback до застарілого володіння
|
||||
`providers[]` і верхньорівневого `cliBackends[]`, якщо явні метадані активації провайдера відсутні
|
||||
- планування setup/каналу, що запускається каналом, повертається до застарілого володіння
|
||||
`channels[]`, якщо явні метадані активації каналу відсутні
|
||||
- планування setup/рантайму, що запускається провайдером, повертається до застарілого
|
||||
володіння `providers[]` і `cliBackends[]` верхнього рівня, якщо явні метадані активації
|
||||
провайдера відсутні
|
||||
|
||||
Діагностика планувальника може розрізняти явні підказки активації та fallback на володіння з маніфесту. Наприклад, `activation-command-hint` означає, що збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для діагностики хоста та тестів; авторам Plugin слід і надалі оголошувати метадані, які найкраще описують володіння.
|
||||
Діагностика планувальника може відрізняти явні підказки активації від fallback-механізму
|
||||
володіння з маніфесту. Наприклад, `activation-command-hint` означає, що
|
||||
збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що
|
||||
планувальник натомість використав володіння з `commandAliases`. Ці мітки причин призначені для
|
||||
діагностики хоста та тестів; авторам Plugin слід і надалі оголошувати метадані,
|
||||
які найкраще описують володіння.
|
||||
|
||||
## Довідник `qaRunners`
|
||||
|
||||
Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner під спільним коренем `openclaw qa`. Зберігайте ці метадані легкими та статичними; фактичною реєстрацією CLI, як і раніше, володіє рантайм Plugin через легку поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`.
|
||||
Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner під спільний
|
||||
корінь `openclaw qa`. Зберігайте ці метадані легкими та статичними; фактичною реєстрацією CLI
|
||||
усе одно володіє рантайм Plugin через полегшену поверхню
|
||||
`runtime-api.ts`, що експортує `qaRunnerCliRegistrations`.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -261,14 +299,15 @@ OpenClaw зчитує це до завантаження рантайму про
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | -------- | --------------------------------------------------------------------------- |
|
||||
| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | -------- | ---------------------------------------------------------------------- |
|
||||
| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. |
|
||||
| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. |
|
||||
|
||||
## Довідник `setup`
|
||||
|
||||
Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні легкі метадані Plugin до завантаження рантайму.
|
||||
Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні легкі метадані,
|
||||
що належать Plugin, до завантаження рантайму.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -287,34 +326,54 @@ OpenClaw зчитує це до завантаження рантайму про
|
||||
}
|
||||
```
|
||||
|
||||
Верхньорівневе `cliBackends` залишається валідним і надалі описує CLI-бекенди інференсу. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків control-plane/setup, які мають залишатися лише на рівні метаданих.
|
||||
`cliBackends` верхнього рівня залишається допустимим і й надалі описує
|
||||
бекенди інференсу CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup,
|
||||
для потоків control-plane/setup, які мають залишатися лише метаданими.
|
||||
|
||||
Якщо вказано `setup.providers` і `setup.cliBackends`, вони є бажаною поверхнею пошуку для виявлення setup у підході descriptor-first. Якщо дескриптор лише звужує коло кандидатів Plugin, а setup усе ще потребує багатших runtime-хуків на етапі налаштування, встановіть `requiresRuntime: true` і збережіть `setup-api` як резервний шлях виконання.
|
||||
Якщо присутні, `setup.providers` і `setup.cliBackends` є пріоритетною
|
||||
поверхнею пошуку для виявлення setup на основі дескрипторів. Якщо дескриптор лише
|
||||
звужує кандидата Plugin, а setup усе ще потребує багатших хуків рантайму на етапі setup,
|
||||
задайте `requiresRuntime: true` і залиште `setup-api` як
|
||||
fallback-шлях виконання.
|
||||
|
||||
OpenClaw також включає `setup.providers[].envVars` у загальні пошуки автентифікації провайдера та env vars. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності впродовж вікна депрекації, але небудовані Plugin, які все ще використовують його, отримують діагностику маніфесту. Нові Plugin повинні розміщувати метадані env для налаштування/статусу в `setup.providers[].envVars`.
|
||||
OpenClaw також включає `setup.providers[].envVars` до загальних пошуків автентифікації провайдера та
|
||||
env vars. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом
|
||||
періоду знецінення, але невбудовані Plugin, які все ще його використовують,
|
||||
отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані env для setup/статусу
|
||||
в `setup.providers[].envVars`.
|
||||
|
||||
Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише на рівні дескрипторів і не виконуватиме `setup-api` для пошуку setup. Якщо `requiresRuntime` не вказано, зберігається застаріла fallback-поведінка, щоб наявні Plugin, які додали дескриптори без цього прапорця, не зламалися.
|
||||
Задавайте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для
|
||||
поверхні setup. OpenClaw трактує явне `false` як контракт лише на дескриптори
|
||||
і не виконуватиме `setup-api` для пошуку setup. Якщо `requiresRuntime`
|
||||
не вказано, зберігається застаріла fallback-поведінка, щоб наявні Plugin, які додали дескриптори
|
||||
без цього прапорця, не зламалися.
|
||||
|
||||
Оскільки пошук setup може виконувати код `setup-api`, яким володіє Plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` повинні залишатися глобально унікальними серед виявлених Plugin. Неоднозначне володіння завершується безпечною відмовою замість вибору переможця за порядком виявлення.
|
||||
Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin,
|
||||
нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися
|
||||
унікальними серед виявлених Plugin. Неоднозначне володіння призводить до безпечної відмови,
|
||||
замість вибору переможця за порядком виявлення.
|
||||
|
||||
Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про дрейф дескрипторів, якщо `setup-api` реєструє провайдера або CLI-бекенд, який не оголошено в дескрипторах маніфесту, або якщо для дескриптора немає відповідної runtime-реєстрації. Ці діагностики є додатковими й не відхиляють застарілі Plugin.
|
||||
Коли рантайм setup усе ж виконується, діагностика реєстру setup повідомляє про дрейф дескрипторів,
|
||||
якщо `setup-api` реєструє провайдера або бекенд CLI, який не оголошено в дескрипторах
|
||||
маніфесту, або якщо для дескриптора немає відповідної реєстрації в рантаймі.
|
||||
Ця діагностика є додатковою і не відхиляє застарілі Plugin.
|
||||
|
||||
### Довідник `setup.providers`
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Id провайдера, який відкривається під час setup або онбордингу. Підтримуйте нормалізовані id глобально унікальними. |
|
||||
| `authMethods` | Ні | `string[]` | Id методів setup/автентифікації, які цей провайдер підтримує без завантаження повного рантайму. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | ---------- | --------------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Ідентифікатор провайдера, що відкривається під час setup або онбордингу. Підтримуйте глобальну унікальність нормалізованих ідентифікаторів. |
|
||||
| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей провайдер підтримує без завантаження повного рантайму. |
|
||||
| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/статусу можуть перевіряти до завантаження рантайму Plugin. |
|
||||
|
||||
### Поля `setup`
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------ | ----------- | ---------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, доступні під час setup та онбордингу. |
|
||||
| `cliBackends` | Ні | `string[]` | Id бекендів часу setup, які використовуються для пошуку setup у підході descriptor-first. Підтримуйте нормалізовані id глобально унікальними. |
|
||||
| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє поверхня setup цього Plugin. |
|
||||
| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, доступні під час setup та онбордингу. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів для етапу setup, що використовуються для пошуку setup спочатку за дескрипторами. Підтримуйте глобальну унікальність нормалізованих ідентифікаторів. |
|
||||
| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, що належать поверхні setup цього Plugin. |
|
||||
| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескрипторами. |
|
||||
|
||||
## Довідник `uiHints`
|
||||
|
||||
@ -333,20 +392,21 @@ OpenClaw також включає `setup.providers[].envVars` у загальн
|
||||
}
|
||||
```
|
||||
|
||||
Кожна підказка поля може містити:
|
||||
Кожна підказка для поля може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ---------- | --------------------------------------- |
|
||||
| `label` | `string` | Мітка поля для користувача. |
|
||||
| `help` | `string` | Короткий допоміжний текст. |
|
||||
| `tags` | `string[]` | Необов’язкові UI-теґи. |
|
||||
| `tags` | `string[]` | Необов’язкові теги UI. |
|
||||
| `advanced` | `boolean` | Позначає поле як розширене. |
|
||||
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
|
||||
| `placeholder` | `string` | Текст плейсхолдера для полів форми. |
|
||||
| `placeholder` | `string` | Текст-заповнювач для полів форми. |
|
||||
|
||||
## Довідник `contracts`
|
||||
|
||||
Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може зчитати без імпорту рантайму Plugin.
|
||||
Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може
|
||||
зчитувати без імпорту рантайму Plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -369,31 +429,44 @@ OpenClaw також включає `setup.providers[].envVars` у загальн
|
||||
|
||||
Кожен список є необов’язковим:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| -------------------------------- | ---------- | --------------------------------------------------------------------- |
|
||||
| `embeddedExtensionFactories` | `string[]` | Застарілі id фабрик вбудованих extension. |
|
||||
| `agentToolResultMiddleware` | `string[]` | Id harness, для яких цей Plugin може реєструвати middleware результатів інструментів. |
|
||||
| `externalAuthProviders` | `string[]` | Id провайдерів, хуком зовнішнього профілю автентифікації яких володіє цей Plugin. |
|
||||
| `speechProviders` | `string[]` | Id мовленнєвих провайдерів, якими володіє цей Plugin. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів транскрипції в реальному часі, якими володіє цей Plugin. |
|
||||
| `realtimeVoiceProviders` | `string[]` | Id голосових провайдерів у реальному часі, якими володіє цей Plugin. |
|
||||
| `memoryEmbeddingProviders` | `string[]` | Id провайдерів embedding для пам’яті, якими володіє цей Plugin. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | Id провайдерів розуміння медіа, якими володіє цей Plugin. |
|
||||
| `imageGenerationProviders` | `string[]` | Id провайдерів генерації зображень, якими володіє цей Plugin. |
|
||||
| `videoGenerationProviders` | `string[]` | Id провайдерів генерації відео, якими володіє цей Plugin. |
|
||||
| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей Plugin. |
|
||||
| `webSearchProviders` | `string[]` | Id провайдерів вебпошуку, якими володіє цей Plugin. |
|
||||
| `tools` | `string[]` | Назви інструментів агента, якими володіє цей Plugin для перевірок вбудованих контрактів. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| -------------------------------- | ---------- | ------------------------------------------------------------------ |
|
||||
| `embeddedExtensionFactories` | `string[]` | Застарілі ідентифікатори фабрик вбудованих розширень. |
|
||||
| `agentToolResultMiddleware` | `string[]` | Ідентифікатори harness, для яких цей Plugin може реєструвати middleware результатів інструментів. |
|
||||
| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, хуком зовнішнього auth profile яких володіє цей Plugin. |
|
||||
| `speechProviders` | `string[]` | Ідентифікатори speech-провайдерів, якими володіє цей Plugin. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime transcription, якими володіє цей Plugin. |
|
||||
| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів realtime voice, якими володіє цей Plugin. |
|
||||
| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів memory embedding, якими володіє цей Plugin. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, якими володіє цей Plugin. |
|
||||
| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів image-generation, якими володіє цей Plugin. |
|
||||
| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів video-generation, якими володіє цей Plugin. |
|
||||
| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей Plugin. |
|
||||
| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, якими володіє цей Plugin. |
|
||||
| `tools` | `string[]` | Назви agent tools, якими володіє цей Plugin для перевірок вбудованих контрактів. |
|
||||
|
||||
`contracts.embeddedExtensionFactories` збережено для коду сумісності вбудованих компонентів, якому все ще потрібні прямі події вбудованого runner для Pi. Нові трансформації результатів інструментів повинні оголошувати `contracts.agentToolResultMiddleware` і натомість реєструватися через `api.registerAgentToolResultMiddleware(...)`.
|
||||
`contracts.embeddedExtensionFactories` збережено для вбудованого коду сумісності,
|
||||
якому все ще потрібні прямі події вбудованого runner Pi. Нові трансформації
|
||||
результатів інструментів мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися
|
||||
через `api.registerAgentToolResultMiddleware(...)`.
|
||||
|
||||
Plugin провайдерів, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють через застарілий fallback сумісності, але цей fallback повільніший і буде вилучений після завершення вікна міграції.
|
||||
Plugins провайдерів, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати
|
||||
`contracts.externalAuthProviders`. Plugins без цього оголошення все ще працюють
|
||||
через застарілий fallback-механізм сумісності, але він повільніший і
|
||||
буде видалений після завершення періоду міграції.
|
||||
|
||||
Вбудовані провайдери embedding для пам’яті повинні оголошувати `contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони надають, включно з вбудованими адаптерами, такими як `local`. Автономні CLI-шляхи використовують цей контракт маніфесту, щоб завантажити лише Plugin-власник до того, як повний рантайм Gateway зареєструє провайдерів.
|
||||
Вбудовані провайдери memory embedding повинні оголошувати
|
||||
`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони відкривають, включно з
|
||||
вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей контракт маніфесту,
|
||||
щоб завантажувати лише Plugin-власник до того, як повний рантайм Gateway зареєструє
|
||||
провайдерів.
|
||||
|
||||
## Довідник `mediaUnderstandingProviderMetadata`
|
||||
|
||||
Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має типові моделі, пріоритет fallback для автоавтентифікації або нативну підтримку документів, які потрібні загальним допоміжним засобам ядра до завантаження рантайму. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`.
|
||||
Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має
|
||||
типові моделі, пріоритет fallback-автентифікації або нативну підтримку документів, які
|
||||
потрібні загальним хелперам ядра до завантаження рантайму. Ключі також мають бути оголошені в
|
||||
`contracts.mediaUnderstandingProviders`.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -418,16 +491,17 @@ Plugin провайдерів, які реалізують `resolveExternalAuthP
|
||||
|
||||
Кожен запис провайдера може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- |
|
||||
| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості медіа, які надає цей провайдер. |
|
||||
| `defaultModels` | `Record<string, string>` | Типові значення зіставлення можливості з моделлю, які використовуються, коли в конфігурації не вказано модель. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ---------------------- | ----------------------------------- | --------------------------------------------------------------------------- |
|
||||
| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які відкриває цей провайдер. |
|
||||
| `defaultModels` | `Record<string, string>` | Типові значення моделей за можливістю, які використовуються, коли в конфігурації не вказано модель. |
|
||||
| `autoPriority` | `Record<string, number>` | Менші числа сортуються раніше для автоматичного fallback провайдера на основі облікових даних. |
|
||||
| `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує провайдер. |
|
||||
| `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує провайдер. |
|
||||
|
||||
## Довідник `channelConfigs`
|
||||
|
||||
Використовуйте `channelConfigs`, коли Plugin каналу потребує легких метаданих конфігурації до завантаження рантайму.
|
||||
Використовуйте `channelConfigs`, коли Plugin каналу потребує легких метаданих конфігурації до
|
||||
завантаження рантайму.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -456,17 +530,19 @@ Plugin провайдерів, які реалізують `resolveExternalAuthP
|
||||
|
||||
Кожен запис каналу може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------ |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
|
||||
| `schema` | `object` | JSON Schema для `channels.<id>`. Обов’язкове для кожного оголошеного запису конфігурації каналу. |
|
||||
| `uiHints` | `Record<string, object>` | Необов’язкові UI-мітки/плейсхолдери/підказки чутливості для цього розділу конфігурації каналу. |
|
||||
| `label` | `string` | Мітка каналу, яка об’єднується в поверхнях вибору та inspect, коли runtime-метадані ще не готові. |
|
||||
| `description` | `string` | Короткий опис каналу для поверхонь inspect і каталогу. |
|
||||
| `preferOver` | `string[]` | Id застарілих або менш пріоритетних Plugin, які цей канал має перевершувати в поверхнях вибору. |
|
||||
| `uiHints` | `Record<string, object>` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. |
|
||||
| `label` | `string` | Мітка каналу, що об’єднується в поверхні вибору й інспекції, коли метадані рантайму ще не готові. |
|
||||
| `description` | `string` | Короткий опис каналу для поверхонь інспекції та каталогу. |
|
||||
| `preferOver` | `string[]` | Ідентифікатори застарілих або менш пріоритетних Plugin, які цей канал має випереджати в поверхнях вибору. |
|
||||
|
||||
## Довідник `modelSupport`
|
||||
|
||||
Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера зі скорочених id моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження рантайму Plugin.
|
||||
Використовуйте `modelSupport`, коли OpenClaw має визначати ваш Plugin провайдера за
|
||||
скороченими ідентифікаторами моделей, такими як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження
|
||||
рантайму Plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -479,72 +555,104 @@ Plugin провайдерів, які реалізують `resolveExternalAuthP
|
||||
|
||||
OpenClaw застосовує такий пріоритет:
|
||||
|
||||
- явні посилання `provider/model` використовують метадані маніфесту `providers`, якими володіє Plugin
|
||||
- `modelPatterns` мають пріоритет над `modelPrefixes`
|
||||
- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований Plugin
|
||||
- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера
|
||||
- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать власнику
|
||||
- `modelPatterns` мають вищий пріоритет за `modelPrefixes`
|
||||
- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований
|
||||
Plugin
|
||||
- решта неоднозначностей ігноруються, доки користувач або конфігурація не вкажуть провайдера
|
||||
|
||||
Поля:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| --------------- | ---------- | ------------------------------------------------------------------------------ |
|
||||
| `modelPrefixes` | `string[]` | Префікси, що перевіряються через `startsWith` проти скорочених id моделей. |
|
||||
| `modelPatterns` | `string[]` | Джерела regex, що перевіряються проти скорочених id моделей після видалення суфікса профілю. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| --------------- | ---------- | ---------------------------------------------------------------------------- |
|
||||
| `modelPrefixes` | `string[]` | Префікси, що звіряються через `startsWith` зі скороченими ідентифікаторами моделей. |
|
||||
| `modelPatterns` | `string[]` | Джерела regex, що звіряються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. |
|
||||
|
||||
Застарілі ключі можливостей верхнього рівня позначені як deprecated. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` до `contracts`; звичайне завантаження маніфесту більше не трактує ці поля верхнього рівня як володіння можливостями.
|
||||
Застарілі ключі можливостей верхнього рівня не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб
|
||||
перемістити `speechProviders`, `realtimeTranscriptionProviders`,
|
||||
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
|
||||
`imageGenerationProviders`, `videoGenerationProviders`,
|
||||
`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне
|
||||
завантаження маніфесту більше не трактує ці поля верхнього рівня як
|
||||
володіння можливостями.
|
||||
|
||||
## Маніфест проти package.json
|
||||
## Маніфест у порівнянні з package.json
|
||||
|
||||
Ці два файли виконують різні завдання:
|
||||
Ці два файли виконують різні ролі:
|
||||
|
||||
| Файл | Для чого використовувати |
|
||||
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та UI-підказки, які мають існувати до запуску коду Plugin |
|
||||
| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для entrypoints, обмежень встановлення, setup або метаданих каталогу |
|
||||
| Файл | Для чого використовувати |
|
||||
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду Plugin |
|
||||
| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для точок входу, обмежень встановлення, setup або метаданих каталогу |
|
||||
|
||||
Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило:
|
||||
Якщо ви не впевнені, куди належить певний фрагмент метаданих, користуйтеся таким правилом:
|
||||
|
||||
- якщо OpenClaw повинен знати це до завантаження коду Plugin, розмістіть це в `openclaw.plugin.json`
|
||||
- якщо це стосується пакування, файлів входу або поведінки встановлення npm, розмістіть це в `package.json`
|
||||
- якщо OpenClaw має знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json`
|
||||
- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json`
|
||||
|
||||
### Поля package.json, які впливають на виявлення
|
||||
### Поля `package.json`, які впливають на виявлення
|
||||
|
||||
Деякі метадані Plugin до запуску рантайму навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`.
|
||||
Деякі метадані Plugin до запуску рантайму навмисно зберігаються в `package.json` у блоці
|
||||
`openclaw`, а не в `openclaw.plugin.json`.
|
||||
|
||||
Важливі приклади:
|
||||
|
||||
| Поле | Що воно означає |
|
||||
| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.extensions` | Оголошує рідні entrypoints Plugin. Має залишатися в межах каталогу пакета Plugin. |
|
||||
| `openclaw.runtimeExtensions` | Оголошує зібрані JavaScript runtime entrypoints для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. |
|
||||
| `openclaw.setupEntry` | Легкий entrypoint лише для setup, який використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef у режимі лише читання. Має залишатися в межах каталогу пакета Plugin. |
|
||||
| `openclaw.runtimeSetupEntry` | Оголошує зібраний JavaScript entrypoint setup для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. |
|
||||
| `openclaw.channel` | Легкі метадані каталогу каналів, як-от мітки, шляхи до документації, аліаси та тексти для вибору. |
|
||||
| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує setup лише через env?» без завантаження повного рантайму каналу. |
|
||||
| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного рантайму каналу. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих Plugin. |
|
||||
| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
|
||||
| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із semver-нижньою межею на кшталт `>=2026.3.22`. |
|
||||
| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення та оновлення звіряють із ним отриманий артефакт. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого Plugin, коли конфігурація невалідна. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. |
|
||||
| Поле | Що воно означає |
|
||||
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.extensions` | Оголошує точки входу власного Plugin. Має залишатися в межах каталогу пакета Plugin. |
|
||||
| `openclaw.runtimeExtensions` | Оголошує точки входу рантайму built JavaScript для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. |
|
||||
| `openclaw.setupEntry` | Полегшена точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та пошуку стану каналу/SecretRef лише для читання. Має залишатися в межах каталогу пакета Plugin. |
|
||||
| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript точку входу setup для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. |
|
||||
| `openclaw.channel` | Легкі метадані каталогу каналу, такі як мітки, шляхи до документації, аліаси та текст для вибору. |
|
||||
| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного рантайму каналу. |
|
||||
| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже виконано вхід хоч кудись?» без завантаження повного рантайму каналу. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих Plugin і Plugin, опублікованих зовні. |
|
||||
| `openclaw.install.defaultChoice` | Пріоритетний шлях встановлення, коли доступно кілька джерел встановлення. |
|
||||
| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. |
|
||||
| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють завантажений артефакт на відповідність йому. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого Plugin, коли конфігурація некоректна. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. |
|
||||
|
||||
Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються під час онбордингу до завантаження рантайму. `package.json#openclaw.install` повідомляє онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих варіантів. Не переміщуйте підказки встановлення до `openclaw.plugin.json`.
|
||||
Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в
|
||||
онбордингу до завантаження рантайму. `package.json#openclaw.install` повідомляє
|
||||
онбордингу, як отримати або ввімкнути цей Plugin, коли користувач обирає один із цих
|
||||
варіантів. Не переносіть підказки встановлення до `openclaw.plugin.json`.
|
||||
|
||||
`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають Plugin на старіших хостах.
|
||||
`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження
|
||||
реєстру маніфестів. Некоректні значення відхиляються; новіші, але коректні значення
|
||||
пропускають Plugin на старіших хостах.
|
||||
|
||||
Точне закріплення версії npm уже зберігається в `npmSpec`, наприклад
|
||||
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу повинні поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення безпечно завершувалися відмовою, якщо отриманий npm-артефакт більше не відповідає закріпленому релізу.
|
||||
Інтерактивний онбординг для сумісності все ще пропонує npm-специфікації довіреного реєстру, включно з простими назвами пакетів і dist-tags. Діагностика каталогу може розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю назви пакета та невалідні джерела default-choice. Вона також попереджає, коли `expectedIntegrity` присутній, але немає валідного npm-джерела, яке можна ним закріпити.
|
||||
Коли `expectedIntegrity` присутній, потоки встановлення/оновлення застосовують його; коли його опущено, дозвіл реєстру фіксується без закріплення цілісності.
|
||||
Точне закріплення версії npm уже міститься в `npmSpec`, наприклад
|
||||
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу
|
||||
мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення безпечно
|
||||
завершувалися помилкою, якщо завантажений npm-артефакт більше не відповідає закріпленому релізу.
|
||||
Інтерактивний онбординг для сумісності все ще пропонує npm-специфікації довіреного реєстру,
|
||||
включно з голими назвами пакетів і dist-tags. Діагностика каталогу може
|
||||
розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю
|
||||
назви пакета та некоректні джерела default-choice. Вона також попереджає, коли
|
||||
`expectedIntegrity` наявний, але немає коректного джерела npm, яке можна ним закріпити.
|
||||
Коли `expectedIntegrity` наявний,
|
||||
потоки встановлення/оновлення примусово застосовують його; коли його не вказано, розв’язання реєстру
|
||||
фіксується без закріплення цілісності.
|
||||
|
||||
Plugin каналів повинні надавати `openclaw.setupEntry`, коли сканам статусу, списку каналів або SecretRef потрібно визначити налаштовані облікові записи без завантаження повного рантайму. Entrypoint setup має надавати метадані каналу, а також безпечні для setup адаптери конфігурації, статусу та секретів; мережеві клієнти, listeners Gateway і транспортні рантайми залишайте в основному entrypoint extension.
|
||||
Plugins каналів повинні надавати `openclaw.setupEntry`, коли для статусу, списку каналів
|
||||
або перевірок SecretRef потрібно визначати налаштовані облікові записи без завантаження повного
|
||||
рантайму. Точка входу setup має відкривати метадані каналу разом із безпечними для setup адаптерами
|
||||
конфігурації, статусу та секретів; мережеві клієнти, слухачі gateway та
|
||||
рантайми транспорту залишайте в основній точці входу розширення.
|
||||
|
||||
Поля runtime entrypoint не скасовують перевірки меж пакета для полів source entrypoint. Наприклад, `openclaw.runtimeExtensions` не може зробити завантажуваним шлях `openclaw.extensions`, що виходить за межі пакета.
|
||||
Поля точок входу рантайму не перевизначають перевірки меж пакетів для полів
|
||||
точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити
|
||||
завантажуваним шлях `openclaw.extensions`, що виходить за межі пакета.
|
||||
|
||||
`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно не робить довільно зламані конфігурації придатними до встановлення. Сьогодні воно дозволяє потокам встановлення відновлюватися лише після конкретних застарілих збоїв оновлення вбудованих Plugin, як-от відсутній шлях до вбудованого Plugin або застарілий запис `channels.<id>` для того самого вбудованого Plugin. Непов’язані помилки конфігурації все одно блокують встановлення та спрямовують операторів до `openclaw doctor --fix`.
|
||||
`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно
|
||||
не робить довільно зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам встановлення
|
||||
відновлюватися після певних застарілих збоїв оновлення вбудованого Plugin, таких як
|
||||
відсутній шлях до вбудованого Plugin або застарілий запис `channels.<id>` для того самого
|
||||
вбудованого Plugin. Непов’язані помилки конфігурації, як і раніше, блокують встановлення й спрямовують операторів
|
||||
до `openclaw doctor --fix`.
|
||||
|
||||
`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки:
|
||||
`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля-перевірки:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -560,9 +668,13 @@ Plugin каналів повинні надавати `openclaw.setupEntry`, к
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте це, коли потокам setup, doctor або configured-state потрібна легка перевірка автентифікації типу так/ні до завантаження повного Plugin каналу. Цільовий export має бути невеликою функцією, яка лише читає збережений стан; не спрямовуйте її через повний barrel рантайму каналу.
|
||||
Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка
|
||||
автентифікації типу так/ні до завантаження повного Plugin каналу. Цільовий експорт має бути невеликою
|
||||
функцією, яка лише читає збережений стан; не маршрутизуйте її через повний barrel рантайму
|
||||
каналу.
|
||||
|
||||
`openclaw.channel.configuredState` має таку саму форму для легких перевірок налаштованого стану лише через env:
|
||||
`openclaw.channel.configuredState` використовує ту саму форму для дешевих перевірок
|
||||
налаштованого стану лише через env:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -578,52 +690,56 @@ Plugin каналів повинні надавати `openclaw.setupEntry`, к
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте це, коли канал може відповісти щодо налаштованого стану на основі env або інших невеликих нерuntime-входів. Якщо перевірка потребує повного розв’язання конфігурації або реального рантайму каналу, залиште цю логіку в хуку Plugin `config.hasConfiguredState`.
|
||||
Використовуйте це, коли канал може відповісти про налаштований стан на основі env або інших невеликих
|
||||
невиконавчих входів. Якщо перевірка потребує повного розв’язання конфігурації або реального
|
||||
рантайму каналу, залишайте цю логіку в хуку Plugin `config.hasConfiguredState`.
|
||||
|
||||
## Пріоритет виявлення (дублікати id Plugin)
|
||||
## Пріоритет виявлення (дублікати ідентифікаторів Plugin)
|
||||
|
||||
OpenClaw виявляє Plugin із кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним.
|
||||
OpenClaw виявляє Plugins із кількох коренів (вбудовані, глобально встановлені, робочий простір, явно вибрані конфігурацією шляхи). Якщо два виявлені Plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч.
|
||||
|
||||
Пріоритет, від найвищого до найнижчого:
|
||||
Пріоритет від найвищого до найнижчого:
|
||||
|
||||
1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.<id>`
|
||||
2. **Вбудований** — Plugin, що постачаються з OpenClaw
|
||||
3. **Глобальне встановлення** — Plugin, установлені в глобальний корінь Plugin OpenClaw
|
||||
4. **Workspace** — Plugin, виявлені відносно поточного workspace
|
||||
1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.<id>`
|
||||
2. **Вбудований** — Plugins, що постачаються з OpenClaw
|
||||
3. **Глобальне встановлення** — Plugins, установлені в глобальний корінь Plugin OpenClaw
|
||||
4. **Робочий простір** — Plugins, виявлені відносно поточного робочого простору
|
||||
|
||||
Наслідки:
|
||||
|
||||
- Форк або застаріла копія вбудованого Plugin у workspace не затьмарить вбудовану збірку.
|
||||
- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.<id>`, щоб він переміг за пріоритетом, а не покладався на виявлення у workspace.
|
||||
- Відкидання дублікатів логуються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
|
||||
- Форк або застаріла копія вбудованого Plugin у робочому просторі не зможе затінити вбудовану збірку.
|
||||
- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.<id>`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення в робочому просторі.
|
||||
- Відкинуті дублікати журналюються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
|
||||
|
||||
## Вимоги до JSON Schema
|
||||
|
||||
- **Кожен Plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурації.
|
||||
- Порожня схема є допустимою (наприклад, `{ "type": "object", "additionalProperties": false }`).
|
||||
- Схеми проходять валідацію під час читання/запису конфігурації, а не під час рантайму.
|
||||
- **Кожен Plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію.
|
||||
- Порожня схема припустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
|
||||
- Схеми проходять валідацію під час читання/запису конфігурації, а не в рантаймі.
|
||||
|
||||
## Поведінка валідації
|
||||
|
||||
- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошено в маніфесті Plugin.
|
||||
- Невідомі ключі `channels.*` — це **помилки**, якщо тільки ідентифікатор каналу не оголошений
|
||||
у маніфесті Plugin.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` і `plugins.slots.*`
|
||||
повинні посилатися на id Plugin, які **можна виявити**. Невідомі id є **помилками**.
|
||||
- Якщо Plugin установлено, але його маніфест або схема пошкоджені чи відсутні,
|
||||
мають посилатися на **виявлювані** ідентифікатори Plugin. Невідомі ідентифікатори — це **помилки**.
|
||||
- Якщо Plugin установлено, але він має зламаний або відсутній маніфест чи схему,
|
||||
валідація завершується помилкою, а Doctor повідомляє про помилку Plugin.
|
||||
- Якщо конфігурація Plugin існує, але Plugin **вимкнений**, конфігурація зберігається, а в Doctor + logs відображається **попередження**.
|
||||
- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається і
|
||||
у Doctor та журналах з’являється **попередження**.
|
||||
|
||||
Повну схему `plugins.*` див. у [довіднику конфігурації](/uk/gateway/configuration).
|
||||
Повну схему `plugins.*` див. у [Довіднику з конфігурації](/uk/gateway/configuration).
|
||||
|
||||
## Примітки
|
||||
|
||||
- Маніфест є **обов’язковим для рідних Plugin OpenClaw**, включно із завантаженнями з локальної файлової системи. Рантайм усе одно окремо завантажує модуль Plugin; маніфест використовується лише для виявлення + валідації.
|
||||
- Рідні маніфести парсяться за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок дозволені, якщо кінцеве значення все ще є об’єктом.
|
||||
- Маніфест **обов’язковий для власних Plugin OpenClaw**, включно із завантаженням із локальної файлової системи. Рантайм, як і раніше, завантажує модуль Plugin окремо; маніфест призначений лише для виявлення + валідації.
|
||||
- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми й ключі без лапок допускаються, якщо кінцеве значення все одно є об’єктом.
|
||||
- Завантажувач маніфесту зчитує лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня.
|
||||
- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує.
|
||||
- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час запиту.
|
||||
- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий код рантайму; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час обробки запитів.
|
||||
- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`).
|
||||
- Метадані env vars (`setup.providers[].envVars`, застаріле `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставлення Cron та інші поверхні лише для читання все одно застосовують політику довіри до Plugin та ефективної активації, перш ніж вважати env var налаштованою.
|
||||
- Метадані runtime wizard, які потребують коду провайдера, див. у [runtime hooks провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks).
|
||||
- Метадані env vars (`setup.providers[].envVars`, застаріле `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до Plugin і ефективної активації, перш ніж вважати env var налаштованою.
|
||||
- Метадані wizard рантайму, які потребують коду провайдера, описано в [Хуках рантайму провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks).
|
||||
- Якщо ваш Plugin залежить від native modules, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild <package>`).
|
||||
|
||||
## Пов’язане
|
||||
@ -636,6 +752,6 @@ OpenClaw виявляє Plugin із кількох коренів (вбудов
|
||||
Внутрішня архітектура та модель можливостей.
|
||||
</Card>
|
||||
<Card title="Огляд SDK" href="/uk/plugins/sdk-overview" icon="book">
|
||||
Довідник SDK Plugin та імпорти підшляхів.
|
||||
Довідник SDK Plugin і імпорти підшляхів.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user