chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
3d14c04a86
commit
fbf4fb6ec3
@ -1,77 +1,65 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви створюєте Plugin для OpenClaw
|
||||
- Вам потрібно постачати схему конфігурації plugin або налагоджувати помилки валідації plugin
|
||||
summary: Вимоги до маніфесту Plugin та JSON schema (сувора валідація конфігурації)
|
||||
- Ви створюєте плагін OpenClaw
|
||||
- Вам потрібно постачати схему конфігурації плагіна або налагоджувати помилки валідації плагіна
|
||||
summary: Вимоги до маніфесту Plugin і JSON schema (сувора валідація конфігурації)
|
||||
title: Маніфест Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-21T20:37:38Z"
|
||||
generated_at: "2026-04-22T00:14:04Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3664a984ac283378e11a76a68dfa320dc4d5a2aa40d973c731eb31e87d6eeeef
|
||||
source_hash: e558aa86bbc5001c322e656dbb9f89374d4fe9d312833572f9dcf2878bbc2b15
|
||||
source_path: plugins/manifest.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Маніфест Plugin (`openclaw.plugin.json`)
|
||||
|
||||
Ця сторінка стосується лише **власного маніфесту Plugin OpenClaw**.
|
||||
Ця сторінка стосується лише **рідного маніфесту плагіна OpenClaw**.
|
||||
|
||||
Сумісні компонування bundle описано в [Plugin bundles](/uk/plugins/bundles).
|
||||
Сумісні макети bundle описано в [Plugin bundles](/uk/plugins/bundles).
|
||||
|
||||
Сумісні формати bundle використовують інші файли маніфесту:
|
||||
|
||||
- bundle Codex: `.codex-plugin/plugin.json`
|
||||
- bundle Claude: `.claude-plugin/plugin.json` або стандартне компонування компонента Claude
|
||||
без маніфесту
|
||||
- bundle Claude: `.claude-plugin/plugin.json` або стандартний макет компонентів Claude без маніфесту
|
||||
- bundle Cursor: `.cursor-plugin/plugin.json`
|
||||
|
||||
OpenClaw також автоматично виявляє ці компонування bundle, але вони не проходять валідацію
|
||||
за схемою `openclaw.plugin.json`, описаною тут.
|
||||
OpenClaw також автоматично виявляє ці макети bundle, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут.
|
||||
|
||||
Для сумісних bundle OpenClaw наразі читає метадані bundle разом з оголошеними
|
||||
коренями skill, коренями команд Claude, типовими значеннями `settings.json` bundle Claude,
|
||||
типовими значеннями LSP bundle Claude та підтримуваними наборами hook, коли компонування відповідає
|
||||
очікуванням середовища виконання OpenClaw.
|
||||
Для сумісних bundle OpenClaw наразі читає метадані bundle, а також оголошені кореневі каталоги Skills, кореневі каталоги команд Claude, типові значення `settings.json` для bundle Claude, типові значення LSP для bundle Claude та підтримувані пакети hook-ів, якщо макет відповідає очікуванням середовища виконання OpenClaw.
|
||||
|
||||
Кожен власний Plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у
|
||||
**корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації
|
||||
**без виконання коду plugin**. Відсутні або невалідні маніфести вважаються
|
||||
помилками plugin і блокують валідацію конфігурації.
|
||||
Кожен рідний плагін OpenClaw **має** постачатися з файлом `openclaw.plugin.json` у **корені плагіна**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду плагіна**. Відсутні або невалідні маніфести вважаються помилками плагіна і блокують валідацію конфігурації.
|
||||
|
||||
Повний посібник із системи plugin див. у: [Plugins](/uk/tools/plugin).
|
||||
Про власну модель можливостей і поточні рекомендації щодо зовнішньої сумісності:
|
||||
Дивіться повний посібник із системи плагінів: [Plugins](/uk/tools/plugin).
|
||||
Щодо рідної моделі можливостей і поточних рекомендацій із зовнішньої сумісності:
|
||||
[Модель можливостей](/uk/plugins/architecture#public-capability-model).
|
||||
|
||||
## Що робить цей файл
|
||||
|
||||
`openclaw.plugin.json` — це метадані, які OpenClaw читає перед завантаженням
|
||||
коду вашого plugin.
|
||||
`openclaw.plugin.json` — це метадані, які OpenClaw читає до завантаження коду вашого плагіна.
|
||||
|
||||
Використовуйте його для:
|
||||
|
||||
- ідентичності plugin
|
||||
- ідентичності плагіна
|
||||
- валідації конфігурації
|
||||
- метаданих auth та onboarding, які мають бути доступні без запуску середовища виконання plugin
|
||||
- недорогих підказок активації, які поверхні control-plane можуть перевіряти до завантаження runtime
|
||||
- недорогих дескрипторів налаштування, які поверхні setup/onboarding можуть перевіряти до завантаження runtime
|
||||
- метаданих alias та auto-enable, які мають розв’язуватися до завантаження runtime plugin
|
||||
- скорочених метаданих про належність до сімейства моделей, які мають автоматично активувати
|
||||
plugin до завантаження runtime
|
||||
- статичних знімків належності можливостей, що використовуються для вбудованого compat-зв’язування та
|
||||
покриття контрактів
|
||||
- недорогих метаданих QA runner, які спільний хост `openclaw qa` може перевіряти
|
||||
до завантаження runtime plugin
|
||||
- метаданих конфігурації, специфічних для channel, які мають об’єднуватися з поверхнями каталогу та валідації без завантаження runtime
|
||||
- метаданих автентифікації та онбордингу, які мають бути доступні без запуску середовища виконання плагіна
|
||||
- недорогих підказок активації, які поверхні control plane можуть перевіряти до завантаження середовища виконання
|
||||
- недорогих дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до завантаження середовища виконання
|
||||
- метаданих псевдонімів і автоувімкнення, які мають розв’язуватися до завантаження середовища виконання плагіна
|
||||
- скорочених метаданих належності до сімейства моделей, які мають автоматично активувати плагін до завантаження середовища виконання
|
||||
- статичних знімків належності можливостей, що використовуються для сумісної проводки bundled-форматів і покриття контрактів
|
||||
- недорогих метаданих QA runner, які спільний хост `openclaw qa` може перевіряти до завантаження середовища виконання плагіна
|
||||
- метаданих конфігурації, специфічних для каналу, які мають об’єднуватися в поверхні каталогу та валідації без завантаження середовища виконання
|
||||
- підказок UI для конфігурації
|
||||
|
||||
Не використовуйте його для:
|
||||
|
||||
- реєстрації поведінки runtime
|
||||
- оголошення code entrypoint
|
||||
- реєстрації поведінки середовища виконання
|
||||
- оголошення точок входу коду
|
||||
- метаданих встановлення npm
|
||||
|
||||
Це належить до коду вашого plugin та `package.json`.
|
||||
Це належить вашому коду плагіна та `package.json`.
|
||||
|
||||
## Мінімальний приклад
|
||||
|
||||
@ -92,7 +80,7 @@ OpenClaw також автоматично виявляє ці компонув
|
||||
{
|
||||
"id": "openrouter",
|
||||
"name": "OpenRouter",
|
||||
"description": "OpenRouter provider plugin",
|
||||
"description": "Плагін провайдера OpenRouter",
|
||||
"version": "1.0.0",
|
||||
"providers": ["openrouter"],
|
||||
"modelSupport": {
|
||||
@ -120,19 +108,19 @@ OpenClaw також автоматично виявляє ці компонув
|
||||
"provider": "openrouter",
|
||||
"method": "api-key",
|
||||
"choiceId": "openrouter-api-key",
|
||||
"choiceLabel": "OpenRouter API key",
|
||||
"choiceLabel": "Ключ API OpenRouter",
|
||||
"groupId": "openrouter",
|
||||
"groupLabel": "OpenRouter",
|
||||
"optionKey": "openrouterApiKey",
|
||||
"cliFlag": "--openrouter-api-key",
|
||||
"cliOption": "--openrouter-api-key <key>",
|
||||
"cliDescription": "OpenRouter API key",
|
||||
"cliDescription": "Ключ API OpenRouter",
|
||||
"onboardingScopes": ["text-inference"]
|
||||
}
|
||||
],
|
||||
"uiHints": {
|
||||
"apiKey": {
|
||||
"label": "API key",
|
||||
"label": "Ключ API",
|
||||
"placeholder": "sk-or-v1-...",
|
||||
"sensitive": true
|
||||
}
|
||||
@ -151,66 +139,64 @@ OpenClaw також автоматично виявляє ці компонув
|
||||
|
||||
## Довідник полів верхнього рівня
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Канонічний ідентифікатор plugin. Це ідентифікатор, що використовується в `plugins.entries.<id>`. |
|
||||
| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього plugin. |
|
||||
| `enabledByDefault` | Ні | `true` | Позначає вбудований plugin як увімкнений типово. Не вказуйте це поле або задайте будь-яке значення, відмінне від `true`, щоб plugin залишався типово вимкненим. |
|
||||
| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора plugin. |
|
||||
| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори provider, які мають автоматично вмикати цей plugin, коли auth, конфігурація або посилання на моделі згадують їх. |
|
||||
| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний вид plugin, який використовується в `plugins.slots.*`. |
|
||||
| `channels` | Ні | `string[]` | Ідентифікатори channel, якими володіє цей plugin. Використовується для виявлення та валідації конфігурації. |
|
||||
| `providers` | Ні | `string[]` | Ідентифікатори provider, якими володіє цей plugin. |
|
||||
| `modelSupport` | Ні | `object` | Скорочені метадані про сімейство моделей, що належать маніфесту й використовуються для автоматичного завантаження plugin до запуску runtime. |
|
||||
| `providerEndpoints` | Ні | `object[]` | Метадані хостів/`baseUrl` endpoint, що належать маніфесту, для маршрутів provider, які core має класифікувати до завантаження runtime provider. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI, якими володіє цей plugin. Використовується для автоактивації під час запуску на основі явних посилань у конфігурації. |
|
||||
| `syntheticAuthRefs` | Ні | `string[]` | Посилання на provider або backend CLI, для яких слід перевіряти синтетичний hook auth, що належить plugin, під час холодного виявлення моделей до завантаження runtime. |
|
||||
| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать вбудованому plugin і представляють не секретний локальний стан, OAuth або ambient credential state. |
|
||||
| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей plugin і які мають формувати діагностику конфігурації та CLI, обізнану про plugin, до завантаження runtime. |
|
||||
| `providerAuthEnvVars` | Ні | `Record<string, string[]>` | Недорогі метадані env для auth provider, які OpenClaw може перевіряти без завантаження коду plugin. |
|
||||
| `providerAuthAliases` | Ні | `Record<string, string>` | Ідентифікатори provider, які мають повторно використовувати інший ідентифікатор provider для пошуку auth, наприклад provider для кодування, що спільно використовує API key і профілі auth базового provider. |
|
||||
| `channelEnvVars` | Ні | `Record<string, string[]>` | Недорогі метадані env для channel, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для поверхонь налаштування channel або auth, керованих env, які мають бачити типові допоміжні засоби запуску/конфігурації. |
|
||||
| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані вибору auth для picker під час onboarding, визначення бажаного provider та простого зв’язування прапорців CLI. |
|
||||
| `activation` | Ні | `object` | Недорогі підказки активації для завантаження, що запускається provider, командою, channel, маршрутом або можливістю. Лише метадані; фактична поведінка все одно належить runtime plugin. |
|
||||
| `setup` | Ні | `object` | Недорогі дескриптори setup/onboarding, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime plugin. |
|
||||
| `qaRunners` | Ні | `object[]` | Недорогі дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження runtime plugin. |
|
||||
| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і належності tool. |
|
||||
| `channelConfigs` | Ні | `Record<string, object>` | Метадані конфігурації channel, що належать маніфесту та об’єднуються з поверхнями виявлення й валідації до завантаження runtime. |
|
||||
| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. |
|
||||
| `name` | Ні | `string` | Людинозрозуміла назва plugin. |
|
||||
| `description` | Ні | `string` | Короткий опис, що показується в поверхнях plugin. |
|
||||
| `version` | Ні | `string` | Інформаційна версія plugin. |
|
||||
| `uiHints` | Ні | `Record<string, object>` | Мітки UI, placeholders і підказки щодо чутливості для полів конфігурації. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ----------------------------------- | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `id` | Так | `string` | Канонічний ідентифікатор плагіна. Це ідентифікатор, який використовується в `plugins.entries.<id>`. |
|
||||
| `configSchema` | Так | `object` | Вбудована JSON schema для конфігурації цього плагіна. |
|
||||
| `enabledByDefault` | Ні | `true` | Позначає bundled-плагін як увімкнений типово. Не вказуйте це поле або встановіть будь-яке значення, відмінне від `true`, щоб плагін залишався типово вимкненим. |
|
||||
| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора плагіна. |
|
||||
| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей плагін, коли автентифікація, конфігурація або посилання на моделі згадують їх. |
|
||||
| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип плагіна, який використовується `plugins.slots.*`. |
|
||||
| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей плагін. Використовується для виявлення та валідації конфігурації. |
|
||||
| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей плагін. |
|
||||
| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту, і використовуються для автоматичного завантаження плагіна до запуску середовища виконання. |
|
||||
| `providerEndpoints` | Ні | `object[]` | Метадані хостів/baseUrl кінцевих точок, що належать маніфесту, для маршрутів провайдерів, які ядро має класифікувати до завантаження середовища виконання провайдера. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори backend-ів CLI, якими володіє цей плагін. Використовується для автоматичної активації під час запуску на основі явних посилань у конфігурації. |
|
||||
| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або backend-и CLI, для яких під час холодного виявлення моделей до завантаження середовища виконання слід перевіряти синтетичний hook автентифікації, що належить плагіну. |
|
||||
| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, що належать bundled-плагіну та представляють несекретний локальний стан, OAuth або ambient credentials. |
|
||||
| `commandAliases` | Ні | `object[]` | Імена команд, що належать цьому плагіну та мають видавати діагностику конфігурації та CLI з урахуванням плагіна до завантаження середовища виконання. |
|
||||
| `providerAuthEnvVars` | Ні | `Record<string, string[]>` | Недорогі метадані env для автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. |
|
||||
| `providerAuthAliases` | Ні | `Record<string, string>` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад coding-провайдер, що спільно використовує API-ключ і профілі автентифікації базового провайдера. |
|
||||
| `channelEnvVars` | Ні | `Record<string, string[]>` | Недорогі метадані env для каналу, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналу через env або поверхонь автентифікації, які мають бачити загальні допоміжні засоби запуску/конфігурації. |
|
||||
| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані варіантів автентифікації для селекторів онбордингу, визначення пріоритетного провайдера та простого зв’язування прапорців CLI. |
|
||||
| `activation` | Ні | `object` | Недорогі підказки активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактична поведінка, як і раніше, належить середовищу виконання плагіна. |
|
||||
| `setup` | Ні | `object` | Недорогі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання плагіна. |
|
||||
| `qaRunners` | Ні | `object[]` | Недорогі дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання плагіна. |
|
||||
| `contracts` | Ні | `object` | Статичний знімок bundled-можливостей для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. |
|
||||
| `channelConfigs` | Ні | `Record<string, object>` | Метадані конфігурації каналу, що належать маніфесту та об’єднуються в поверхні виявлення й валідації до завантаження середовища виконання. |
|
||||
| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня плагіна. |
|
||||
| `name` | Ні | `string` | Людинозрозуміла назва плагіна. |
|
||||
| `description` | Ні | `string` | Короткий опис, що показується в поверхнях плагіна. |
|
||||
| `version` | Ні | `string` | Інформаційна версія плагіна. |
|
||||
| `uiHints` | Ні | `Record<string, object>` | Мітки UI, placeholders і підказки щодо чутливості для полів конфігурації. |
|
||||
|
||||
## Довідник `providerAuthChoices`
|
||||
|
||||
Кожен запис `providerAuthChoices` описує один варіант onboarding або auth.
|
||||
OpenClaw читає це до завантаження runtime provider.
|
||||
Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації.
|
||||
OpenClaw читає це до завантаження середовища виконання провайдера.
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | Так | `string` | Ідентифікатор provider, до якого належить цей варіант. |
|
||||
| `method` | Так | `string` | Ідентифікатор методу auth, до якого слід виконати диспетчеризацію. |
|
||||
| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта auth, який використовується в потоках onboarding і CLI. |
|
||||
| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId` як запасний варіант. |
|
||||
| `choiceHint` | Ні | `string` | Короткий допоміжний текст для picker. |
|
||||
| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних picker, керованих асистентом. |
|
||||
| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із picker асистента, але все ще дозволяє ручний вибір через CLI. |
|
||||
| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають переспрямовувати користувачів до цього варіанта-заміни. |
|
||||
| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. |
|
||||
| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. |
|
||||
| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
|
||||
| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків auth з одним прапорцем. |
|
||||
| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. |
|
||||
| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key <key>`. |
|
||||
| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. |
|
||||
| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях onboarding має з’являтися цей варіант. Якщо не вказано, типово використовується `["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
|
||||
використовує ці метадані для діагностики без імпорту коду runtime plugin.
|
||||
Використовуйте `commandAliases`, коли плагін володіє назвою команди середовища виконання, яку користувачі можуть помилково додати до `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду середовища виконання плагіна.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -224,45 +210,38 @@ OpenClaw читає це до завантаження runtime provider.
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------ |
|
||||
| `name` | Так | `string` | Назва команди, яка належить цьому plugin. |
|
||||
| `kind` | Ні | `"runtime-slash"` | Позначає alias як slash-команду чату, а не кореневу команду CLI. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------ | ----------- | ----------------- | ----------------------------------------------------------------------------- |
|
||||
| `name` | Так | `string` | Назва команди, яка належить цьому плагіну. |
|
||||
| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. |
|
||||
| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо вона існує. |
|
||||
|
||||
## Довідник `activation`
|
||||
|
||||
Використовуйте `activation`, коли plugin може дешево оголосити, які події control-plane
|
||||
мають активувати його пізніше.
|
||||
Використовуйте `activation`, коли плагін може з низькими витратами оголосити, які події control plane мають активувати його пізніше.
|
||||
|
||||
## Довідник `qaRunners`
|
||||
|
||||
Використовуйте `qaRunners`, коли plugin додає один або більше transport runner у межах
|
||||
спільного кореня `openclaw qa`. Зберігайте ці метадані дешевими й статичними; runtime plugin
|
||||
усе одно володіє фактичною реєстрацією CLI через легку поверхню
|
||||
`runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`.
|
||||
Використовуйте `qaRunners`, коли плагін додає один або більше transport runner-ів під спільним коренем `openclaw qa`. Зберігайте ці метадані легкими й статичними; фактичною реєстрацією CLI, як і раніше, володіє середовище виконання плагіна через легковагову поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`.
|
||||
|
||||
```json
|
||||
{
|
||||
"qaRunners": [
|
||||
{
|
||||
"commandName": "matrix",
|
||||
"description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
|
||||
"description": "Запускає live QA lane на базі Docker для Matrix на disposable homeserver"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | -------- | ------------------------------------------------------------------- |
|
||||
| `commandName` | Так | `string` | Підкоманда, змонтована в `openclaw qa`, наприклад `matrix`. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | -------- | ----------------------------------------------------------------------- |
|
||||
| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. |
|
||||
| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. |
|
||||
|
||||
Цей блок є лише метаданими. Він не реєструє поведінку runtime і не
|
||||
замінює `register(...)`, `setupEntry` чи інші entrypoint runtime/plugin.
|
||||
Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням plugin, тож
|
||||
відсутність метаданих activation зазвичай лише погіршує продуктивність; вона не має
|
||||
змінювати коректність, поки все ще існують резервні варіанти на основі застарілого володіння маніфестом.
|
||||
Цей блок є лише метаданими. Він не реєструє поведінку середовища виконання і не замінює `register(...)`, `setupEntry` або інші точки входу середовища виконання/плагіна.
|
||||
Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням плагінів, тому відсутність метаданих активації зазвичай впливає лише на продуктивність; це не повинно змінювати коректність, доки все ще існують застарілі резервні механізми володіння маніфестом.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -276,28 +255,23 @@ OpenClaw читає це до завантаження runtime provider.
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `onProviders` | Ні | `string[]` | Ідентифікатори provider, які мають активувати цей plugin за запитом. |
|
||||
| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають активувати цей plugin. |
|
||||
| `onChannels` | Ні | `string[]` | Ідентифікатори channel, які мають активувати цей plugin. |
|
||||
| `onRoutes` | Ні | `string[]` | Види маршрутів, які мають активувати цей plugin. |
|
||||
| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються під час планування активації control-plane. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ---------------- | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------- |
|
||||
| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають активувати цей плагін за запитом. |
|
||||
| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають активувати цей плагін. |
|
||||
| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають активувати цей плагін. |
|
||||
| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей плагін. |
|
||||
| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються під час планування активації control plane. |
|
||||
|
||||
Поточні активні споживачі:
|
||||
Поточні live-споживачі:
|
||||
|
||||
- планування CLI, запущене командою, використовує резервний варіант із застарілих
|
||||
`commandAliases[].cliCommand` або `commandAliases[].name`
|
||||
- планування setup/channel, запущене channel, використовує резервний варіант із застарілого володіння
|
||||
`channels[]`, якщо явні метадані активації channel відсутні
|
||||
- планування setup/runtime, запущене provider, використовує резервний варіант із застарілого
|
||||
володіння `providers[]` і `cliBackends[]` верхнього рівня, якщо явні метадані
|
||||
активації provider відсутні
|
||||
- планування CLI, ініційоване командою, використовує як резервний варіант застарілі `commandAliases[].cliCommand` або `commandAliases[].name`
|
||||
- планування налаштування/каналу, ініційоване каналом, використовує як резервний варіант застаріле володіння `channels[]`, якщо явні метадані активації каналу відсутні
|
||||
- планування налаштування/середовища виконання, ініційоване провайдером, використовує як резервний варіант застаріле володіння `providers[]` і верхньорівневе `cliBackends[]`, якщо явні метадані активації провайдера відсутні
|
||||
|
||||
## Довідник `setup`
|
||||
|
||||
Використовуйте `setup`, коли поверхням setup та onboarding потрібні дешеві метадані, що належать plugin,
|
||||
до завантаження runtime.
|
||||
Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні недорогі метадані, що належать плагіну, до завантаження середовища виконання.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -316,48 +290,39 @@ OpenClaw читає це до завантаження runtime provider.
|
||||
}
|
||||
```
|
||||
|
||||
`cliBackends` верхнього рівня залишається валідним і далі описує inference-backend CLI.
|
||||
`setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для
|
||||
потоків control-plane/setup, які мають залишатися лише метаданими.
|
||||
Верхньорівневе `cliBackends` залишається валідним і надалі описує backend-и inference CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для налаштування, для потоків control plane/налаштування, яка має залишатися лише метаданими.
|
||||
|
||||
Якщо вони присутні, `setup.providers` і `setup.cliBackends` є бажаною
|
||||
поверхнею пошуку для виявлення setup за принципом descriptor-first. Якщо дескриптор лише
|
||||
звужує кандидатний plugin, а setup все ще потребує більш насичених hook runtime на етапі setup,
|
||||
установіть `requiresRuntime: true` і збережіть `setup-api` як
|
||||
резервний шлях виконання.
|
||||
Якщо `setup.providers` і `setup.cliBackends` присутні, вони є пріоритетною поверхнею пошуку на основі дескрипторів для виявлення налаштування. Якщо дескриптор лише звужує кандидатний плагін, а для налаштування все ще потрібні багатші hook-и середовища виконання на етапі налаштування, установіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання.
|
||||
|
||||
Оскільки пошук setup може виконувати код `setup-api`, що належить plugin,
|
||||
нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед
|
||||
виявлених plugin. Неоднозначне володіння завершується безпечною відмовою замість вибору
|
||||
переможця за порядком виявлення.
|
||||
Оскільки пошук налаштування може виконувати код `setup-api`, що належить плагіну, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед усіх виявлених плагінів. Неоднозначне володіння призводить до закритої відмови замість вибору переможця за порядком виявлення.
|
||||
|
||||
### Довідник `setup.providers`
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Ідентифікатор provider, який показується під час setup або onboarding. Зберігайте нормалізовані ідентифікатори глобально унікальними. |
|
||||
| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/auth, які цей provider підтримує без завантаження повного runtime. |
|
||||
| `envVars` | Ні | `string[]` | Змінні env, які типові поверхні setup/status можуть перевіряти до завантаження runtime plugin. |
|
||||
| `id` | Так | `string` | Ідентифікатор провайдера, що надається під час налаштування або онбордингу. Зберігайте нормалізовані ідентифікатори глобально унікальними. |
|
||||
| `authMethods` | Ні | `string[]` | Ідентифікатори методів налаштування/автентифікації, які цей провайдер підтримує без завантаження повного середовища виконання. |
|
||||
| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні налаштування/статусу можуть перевіряти до завантаження середовища виконання плагіна. |
|
||||
|
||||
### Поля `setup`
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | Ні | `object[]` | Дескриптори setup provider, які показуються під час setup та onboarding. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори backend для етапу setup, які використовуються для пошуку setup за принципом descriptor-first. Зберігайте нормалізовані ідентифікатори глобально унікальними. |
|
||||
| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього plugin. |
|
||||
| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. |
|
||||
| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, що надаються під час налаштування та онбордингу. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори backend-ів часу налаштування, що використовуються для пошуку налаштування на основі дескрипторів. Зберігайте нормалізовані ідентифікатори глобально унікальними. |
|
||||
| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, що належать поверхні налаштування цього плагіна. |
|
||||
| `requiresRuntime` | Ні | `boolean` | Чи потребує налаштування все ще виконання `setup-api` після пошуку за дескриптором. |
|
||||
|
||||
## Довідник `uiHints`
|
||||
|
||||
`uiHints` — це мапа від імен полів конфігурації до невеликих підказок рендерингу.
|
||||
`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для відображення.
|
||||
|
||||
```json
|
||||
{
|
||||
"uiHints": {
|
||||
"apiKey": {
|
||||
"label": "API key",
|
||||
"help": "Used for OpenRouter requests",
|
||||
"label": "Ключ API",
|
||||
"help": "Використовується для запитів OpenRouter",
|
||||
"placeholder": "sk-or-v1-...",
|
||||
"sensitive": true
|
||||
}
|
||||
@ -367,19 +332,18 @@ OpenClaw читає це до завантаження runtime provider.
|
||||
|
||||
Кожна підказка для поля може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ---------- | --------------------------------------- |
|
||||
| `label` | `string` | Мітка поля для користувача. |
|
||||
| `help` | `string` | Короткий допоміжний текст. |
|
||||
| `tags` | `string[]` | Необов’язкові теги UI. |
|
||||
| `advanced` | `boolean` | Позначає поле як розширене. |
|
||||
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
|
||||
| `placeholder` | `string` | Текст placeholder для полів форми. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ---------- | ---------------------------------------- |
|
||||
| `label` | `string` | Мітка поля для користувача. |
|
||||
| `help` | `string` | Короткий допоміжний текст. |
|
||||
| `tags` | `string[]` | Необов’язкові теги UI. |
|
||||
| `advanced` | `boolean` | Позначає поле як розширене. |
|
||||
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
|
||||
| `placeholder` | `string` | Текст placeholder для полів форми. |
|
||||
|
||||
## Довідник `contracts`
|
||||
|
||||
Використовуйте `contracts` лише для статичних метаданих про належність можливостей, які OpenClaw може
|
||||
читати без імпорту runtime plugin.
|
||||
Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може читати без імпорту середовища виконання плагіна.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -399,22 +363,21 @@ OpenClaw читає це до завантаження runtime provider.
|
||||
|
||||
Кожен список є необов’язковим:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| -------------------------------- | ---------- | -------------------------------------------------------------- |
|
||||
| `speechProviders` | `string[]` | Ідентифікатори speech provider, якими володіє цей plugin. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори provider для realtime transcription, якими володіє цей plugin. |
|
||||
| `realtimeVoiceProviders` | `string[]` | Ідентифікатори provider для realtime voice, якими володіє цей plugin. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори provider для media-understanding, якими володіє цей plugin. |
|
||||
| `imageGenerationProviders` | `string[]` | Ідентифікатори provider для image-generation, якими володіє цей plugin. |
|
||||
| `videoGenerationProviders` | `string[]` | Ідентифікатори provider для video-generation, якими володіє цей plugin. |
|
||||
| `webFetchProviders` | `string[]` | Ідентифікатори provider для web-fetch, якими володіє цей plugin. |
|
||||
| `webSearchProviders` | `string[]` | Ідентифікатори provider для web search, якими володіє цей plugin. |
|
||||
| `tools` | `string[]` | Назви agent tool, якими володіє цей plugin, для перевірок контрактів вбудованих plugin. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| -------------------------------- | ---------- | ------------------------------------------------------------ |
|
||||
| `speechProviders` | `string[]` | Ідентифікатори speech-провайдерів, якими володіє цей плагін. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime-transcription, якими володіє цей плагін. |
|
||||
| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів realtime-voice, якими володіє цей плагін. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, якими володіє цей плагін. |
|
||||
| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів image-generation, якими володіє цей плагін. |
|
||||
| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів video-generation, якими володіє цей плагін. |
|
||||
| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей плагін. |
|
||||
| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, якими володіє цей плагін. |
|
||||
| `tools` | `string[]` | Назви інструментів агента, якими володіє цей плагін, для bundled-перевірок контрактів. |
|
||||
|
||||
## Довідник `channelConfigs`
|
||||
|
||||
Використовуйте `channelConfigs`, коли plugin channel потребує дешевих метаданих конфігурації
|
||||
до завантаження runtime.
|
||||
Використовуйте `channelConfigs`, коли плагіну каналу потрібні недорогі метадані конфігурації до завантаження середовища виконання.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -429,33 +392,31 @@ OpenClaw читає це до завантаження runtime provider.
|
||||
},
|
||||
"uiHints": {
|
||||
"homeserverUrl": {
|
||||
"label": "Homeserver URL",
|
||||
"label": "URL homeserver",
|
||||
"placeholder": "https://matrix.example.com"
|
||||
}
|
||||
},
|
||||
"label": "Matrix",
|
||||
"description": "Matrix homeserver connection",
|
||||
"description": "Підключення до homeserver Matrix",
|
||||
"preferOver": ["matrix-legacy"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Кожен запис channel може містити:
|
||||
Кожен запис каналу може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
|
||||
| `schema` | `object` | JSON Schema для `channels.<id>`. Обов’язкове для кожного оголошеного запису конфігурації channel. |
|
||||
| `uiHints` | `Record<string, object>` | Необов’язкові мітки UI/placeholders/підказки щодо чутливості для цього розділу конфігурації channel. |
|
||||
| `label` | `string` | Мітка channel, що об’єднується з поверхнями picker та inspect, коли метадані runtime ще не готові. |
|
||||
| `description` | `string` | Короткий опис channel для поверхонь inspect і каталогу. |
|
||||
| `preferOver` | `string[]` | Ідентифікатори застарілих або менш пріоритетних plugin, які цей channel має випереджати в поверхнях вибору. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ------------------------ | -------------------------------------------------------------------------------------- |
|
||||
| `schema` | `object` | JSON Schema для `channels.<id>`. Обов’язкове для кожного оголошеного запису конфігурації каналу. |
|
||||
| `uiHints` | `Record<string, object>` | Необов’язкові мітки UI/placeholders/підказки чутливості для цього розділу конфігурації каналу. |
|
||||
| `label` | `string` | Мітка каналу, яка об’єднується в поверхні вибору та перевірки, коли метадані середовища виконання ще не готові. |
|
||||
| `description` | `string` | Короткий опис каналу для поверхонь перевірки та каталогу. |
|
||||
| `preferOver` | `string[]` | Застарілі або нижчопріоритетні ідентифікатори плагінів, які цей канал має випереджати в поверхнях вибору. |
|
||||
|
||||
## Довідник `modelSupport`
|
||||
|
||||
Використовуйте `modelSupport`, коли OpenClaw має виводити ваш provider plugin із
|
||||
скорочених ідентифікаторів моделей на кшталт `gpt-5.4` або `claude-sonnet-4.6` до завантаження
|
||||
runtime plugin.
|
||||
Використовуйте `modelSupport`, коли OpenClaw має виводити ваш плагін провайдера зі скорочених ідентифікаторів моделей на кшталт `gpt-5.4` або `claude-sonnet-4.6` до завантаження середовища виконання плагіна.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -468,11 +429,10 @@ runtime plugin.
|
||||
|
||||
OpenClaw застосовує такий пріоритет:
|
||||
|
||||
- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать відповідному plugin
|
||||
- `modelPatterns` мають вищий пріоритет за `modelPrefixes`
|
||||
- якщо збігаються один невбудований plugin і один вбудований plugin, перемагає невбудований
|
||||
plugin
|
||||
- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже provider
|
||||
- явні посилання `provider/model` використовують метадані маніфесту `providers`, якими володіє відповідний плагін
|
||||
- `modelPatterns` мають пріоритет над `modelPrefixes`
|
||||
- якщо збігаються один небандлований плагін і один bundled-плагін, перемагає небандлований плагін
|
||||
- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера
|
||||
|
||||
Поля:
|
||||
|
||||
@ -481,64 +441,50 @@ OpenClaw застосовує такий пріоритет:
|
||||
| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. |
|
||||
| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. |
|
||||
|
||||
Застарілі ключі можливостей верхнього рівня не рекомендуються до використання. Використовуйте `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` | Виявлення, валідація конфігурації, метадані вибору auth і підказки UI, які мають існувати до запуску коду plugin |
|
||||
| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoint, обмежень встановлення, setup або метаданих каталогу |
|
||||
| Файл | Використовуйте для |
|
||||
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | Виявлення, валідації конфігурації, метаданих варіантів автентифікації та підказок UI, які мають існувати до запуску коду плагіна |
|
||||
| `package.json` | Метаданих npm, встановлення залежностей і блока `openclaw`, який використовується для точок входу, обмежень установлення, налаштування або метаданих каталогу |
|
||||
|
||||
Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте таке правило:
|
||||
Якщо ви не впевнені, куди належить певний фрагмент метаданих, користуйтеся таким правилом:
|
||||
|
||||
- якщо OpenClaw має знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json`
|
||||
- якщо це стосується пакування, файлів entrypoint або поведінки встановлення npm, помістіть це в `package.json`
|
||||
- якщо OpenClaw має знати це до завантаження коду плагіна, помістіть це в `openclaw.plugin.json`
|
||||
- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, помістіть це в `package.json`
|
||||
|
||||
### Поля package.json, які впливають на виявлення
|
||||
|
||||
Деякі метадані plugin до запуску runtime навмисно зберігаються в `package.json` у блоці
|
||||
`openclaw`, а не в `openclaw.plugin.json`.
|
||||
Деякі метадані плагіна до запуску середовища виконання навмисно зберігаються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`.
|
||||
|
||||
Важливі приклади:
|
||||
|
||||
| Поле | Що воно означає |
|
||||
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.extensions` | Оголошує власні entrypoint plugin. |
|
||||
| `openclaw.setupEntry` | Легкий entrypoint лише для setup, що використовується під час onboarding, відкладеного запуску channel і discovery статусу/SecretRef лише для читання. |
|
||||
| `openclaw.channel` | Дешеві метадані каталогу channel, як-от мітки, шляхи до документації, alias і текст для вибору. |
|
||||
| `openclaw.channel.configuredState` | Легкі метадані перевірки configured-state, які можуть відповісти на питання «чи вже існує налаштування лише через env?» без завантаження повного runtime channel. |
|
||||
| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки persisted-auth, які можуть відповісти на питання «чи вже виконано вхід кудись?» без завантаження повного runtime channel. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих plugin. |
|
||||
| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
|
||||
| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого plugin, коли конфігурація невалідна. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного plugin channel під час запуску. |
|
||||
| Поле | Що воно означає |
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.extensions` | Оголошує рідні точки входу плагіна. Має залишатися в межах каталогу пакета плагіна. |
|
||||
| `openclaw.runtimeExtensions` | Оголошує зібрані JavaScript-точки входу середовища виконання для встановлених пакетів. Має залишатися в межах каталогу пакета плагіна. |
|
||||
| `openclaw.setupEntry` | Легковагова точка входу лише для налаштування, що використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef у режимі лише читання. Має залишатися в межах каталогу пакета плагіна. |
|
||||
| `openclaw.runtimeSetupEntry` | Оголошує зібрану JavaScript-точку входу налаштування для встановлених пакетів. Має залишатися в межах каталогу пакета плагіна. |
|
||||
| `openclaw.channel` | Недорогі метадані каталогу каналу, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. |
|
||||
| `openclaw.channel.configuredState` | Легковагові метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного середовища виконання каналу. |
|
||||
| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже є щось авторизоване?» без завантаження повного середовища виконання каналу. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для bundled-плагінів і зовнішньо опублікованих плагінів. |
|
||||
| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел установлення. |
|
||||
| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, із semver-нижньою межею на кшталт `>=2026.3.22`. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення bundled-плагіна, коли конфігурація невалідна. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для налаштування завантажуватися до повного плагіна каналу під час запуску. |
|
||||
|
||||
`openclaw.install.minHostVersion` застосовується під час встановлення та
|
||||
завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення
|
||||
пропускають plugin на старіших хостах.
|
||||
`openclaw.install.minHostVersion` перевіряється під час встановлення та завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають плагін на старіших хостах.
|
||||
|
||||
Plugin channel мають надавати `openclaw.setupEntry`, коли status, список channel
|
||||
або сканування SecretRef мають визначати налаштовані облікові записи без завантаження повного
|
||||
runtime. Entrypoint setup має відкривати метадані channel разом із безпечними для setup адаптерами
|
||||
конфігурації, status і secrets; зберігайте мережеві клієнти, слухачі Gateway і transport runtime
|
||||
в основному entrypoint extension.
|
||||
Плагіни каналів мають надавати `openclaw.setupEntry`, коли перевіркам статусу, списку каналів або скануванням SecretRef потрібно визначати налаштовані облікові записи без завантаження повного середовища виконання. Точка входу налаштування має надавати метадані каналу разом із безпечними для налаштування адаптерами конфігурації, статусу та секретів; мережеві клієнти, слухачі Gateway і transport runtime слід залишати в основній точці входу extension.
|
||||
|
||||
`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке застосування. Воно
|
||||
не робить довільно зламані конфігурації придатними для встановлення. Наразі воно лише дозволяє потокам встановлення
|
||||
відновлюватися після конкретних застарілих збоїв оновлення вбудованого plugin, наприклад
|
||||
відсутнього шляху до вбудованого plugin або застарілого запису `channels.<id>` для того самого
|
||||
вбудованого plugin. Непов’язані помилки конфігурації все одно блокують встановлення і спрямовують операторів
|
||||
до `openclaw doctor --fix`.
|
||||
Поля точок входу середовища виконання не скасовують перевірки меж пакета для полів точок входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити придатним до завантаження шлях `openclaw.extensions`, що виходить за межі пакета.
|
||||
|
||||
`openclaw.install.allowInvalidConfigRecovery` є навмисно вузьким. Воно не робить довільно зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам установлення відновлюватися після певних застарілих збоїв оновлення bundled-плагінів, наприклад відсутнього шляху до bundled-плагіна або застарілого запису `channels.<id>` для того самого bundled-плагіна. Непов’язані помилки конфігурації все одно блокують установлення і спрямовують операторів до `openclaw doctor --fix`.
|
||||
|
||||
`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки:
|
||||
|
||||
@ -556,12 +502,9 @@ runtime. Entrypoint setup має відкривати метадані channel
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева
|
||||
перевірка auth у форматі так/ні до завантаження повного plugin channel. Цільовий export має бути
|
||||
невеликою функцією, що читає лише збережений стан; не спрямовуйте її через повний barrel runtime channel.
|
||||
Використовуйте це, коли потокам налаштування, doctor або configured-state потрібна недорога перевірка автентифікації типу yes/no до завантаження повного плагіна каналу. Цільовий експорт має бути невеликою функцією, яка лише читає збережений стан; не спрямовуйте її через повний barrel середовища виконання каналу.
|
||||
|
||||
`openclaw.channel.configuredState` має таку саму форму для дешевих перевірок
|
||||
configured state лише через env:
|
||||
`openclaw.channel.configuredState` використовує ту саму форму для недорогих перевірок configured-state лише через env:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -577,92 +520,62 @@ configured state лише через env:
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте це, коли channel може визначати configured state через env або інші малі
|
||||
вхідні дані, не пов’язані з runtime. Якщо перевірка потребує повного розв’язання конфігурації або реального
|
||||
runtime channel, залиште цю логіку в hook `config.hasConfiguredState` plugin.
|
||||
Використовуйте це, коли канал може визначити configured-state через env або інші невеликі невиконувані входи. Якщо перевірка потребує повного розв’язання конфігурації або реального середовища виконання каналу, залиште цю логіку в hook `config.hasConfiguredState` плагіна.
|
||||
|
||||
## Пріоритет виявлення (дубльовані ідентифікатори plugin)
|
||||
## Пріоритет виявлення (дублікати ідентифікаторів плагінів)
|
||||
|
||||
OpenClaw виявляє plugin із кількох коренів (вбудовані, глобальне встановлення, робочий простір, явні шляхи, вибрані в конфігурації). Якщо два виявлені plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість паралельного завантаження.
|
||||
OpenClaw виявляє плагіни з кількох коренів (bundled, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два результати виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість паралельного завантаження.
|
||||
|
||||
Пріоритет від найвищого до найнижчого:
|
||||
Пріоритет, від найвищого до найнижчого:
|
||||
|
||||
1. **Вибраний у конфігурації** — шлях, явно зафіксований у `plugins.entries.<id>`
|
||||
2. **Вбудований** — plugin, що постачаються з OpenClaw
|
||||
3. **Глобальне встановлення** — plugin, встановлені в глобальний корінь plugin OpenClaw
|
||||
4. **Робочий простір** — plugin, виявлені відносно поточного робочого простору
|
||||
1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.<id>`
|
||||
2. **Bundled** — плагіни, що постачаються разом з OpenClaw
|
||||
3. **Глобальне встановлення** — плагіни, встановлені в глобальний корінь плагінів OpenClaw
|
||||
4. **Workspace** — плагіни, виявлені відносно поточного workspace
|
||||
|
||||
Наслідки:
|
||||
|
||||
- Розгалужена або застаріла копія вбудованого plugin, що лежить у робочому просторі, не затьмарить вбудовану збірку.
|
||||
- Щоб справді перевизначити вбудований plugin локальним, зафіксуйте його через `plugins.entries.<id>`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення в робочому просторі.
|
||||
- Розгалужена або застаріла копія bundled-плагіна, що лежить у workspace, не затьмарить bundled-збірку.
|
||||
- Щоб справді перевизначити bundled-плагін локальним, закріпіть його через `plugins.entries.<id>`, щоб він перемагав за пріоритетом, а не покладайтеся на виявлення у workspace.
|
||||
- Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
|
||||
|
||||
## Вимоги до JSON Schema
|
||||
|
||||
- **Кожен plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію.
|
||||
- Порожня схема припустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
|
||||
- Схеми проходять валідацію під час читання/запису конфігурації, а не під час runtime.
|
||||
- **Кожен плагін має постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію.
|
||||
- Порожня схема є прийнятною (наприклад, `{ "type": "object", "additionalProperties": false }`).
|
||||
- Схеми проходять валідацію під час читання/запису конфігурації, а не під час виконання.
|
||||
|
||||
## Поведінка валідації
|
||||
|
||||
- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор channel не оголошено
|
||||
в маніфесті plugin.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` і `plugins.slots.*`
|
||||
мають посилатися на **такі ідентифікатори plugin, які можна виявити**. Невідомі ідентифікатори є **помилками**.
|
||||
- Якщо plugin встановлено, але він має зламаний або відсутній маніфест чи схему,
|
||||
валідація завершується з помилкою, а Doctor повідомляє про помилку plugin.
|
||||
- Якщо конфігурація plugin існує, але plugin **вимкнено**, конфігурація зберігається, і
|
||||
у Doctor + журналах з’являється **попередження**.
|
||||
- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено в маніфесті плагіна.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` мають посилатися на **доступні для виявлення** ідентифікатори плагінів. Невідомі ідентифікатори є **помилками**.
|
||||
- Якщо плагін встановлено, але він має зламаний або відсутній маніфест чи схему, валідація завершується помилкою, а Doctor повідомляє про помилку плагіна.
|
||||
- Якщо конфігурація плагіна існує, але плагін **вимкнений**, конфігурація зберігається, а в Doctor + журналах відображається **попередження**.
|
||||
|
||||
Повну схему `plugins.*` див. у [Довідник конфігурації](/uk/gateway/configuration).
|
||||
Дивіться [Configuration reference](/uk/gateway/configuration) для повної схеми `plugins.*`.
|
||||
|
||||
## Примітки
|
||||
|
||||
- Маніфест **обов’язковий для власних Plugin OpenClaw**, включно із завантаженнями з локальної файлової системи.
|
||||
- Runtime і далі окремо завантажує модуль plugin; маніфест використовується лише для
|
||||
виявлення + валідації.
|
||||
- Власні маніфести парсяться за допомогою JSON5, тому коментарі, кінцеві коми та
|
||||
ключі без лапок допускаються, якщо фінальне значення все ще є об’єктом.
|
||||
- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання
|
||||
власних ключів верхнього рівня тут.
|
||||
- `providerAuthEnvVars` — це дешевий шлях метаданих для перевірок auth, валідації
|
||||
env-marker і подібних поверхонь auth provider, які не повинні запускати runtime plugin
|
||||
лише для перевірки назв env.
|
||||
- `providerAuthAliases` дає змогу варіантам provider повторно використовувати auth
|
||||
env vars, профілі auth, auth на основі конфігурації та варіант onboarding API key іншого provider
|
||||
без жорсткого кодування цього зв’язку в core.
|
||||
- `providerEndpoints` дає plugin provider змогу володіти простими метаданими зіставлення
|
||||
host/baseUrl endpoint. Використовуйте це лише для класів endpoint, які core вже підтримує;
|
||||
поведінка runtime все одно належить plugin.
|
||||
- `syntheticAuthRefs` — це дешевий шлях метаданих для синтетичних hook auth, що належать provider
|
||||
і мають бути видимими для холодного виявлення моделей до появи реєстру runtime.
|
||||
Перелічуйте лише ті посилання, чий runtime provider або backend CLI справді
|
||||
реалізує `resolveSyntheticAuth`.
|
||||
- `nonSecretAuthMarkers` — це дешевий шлях метаданих для значень-заповнювачів API key, що належать
|
||||
вбудованому plugin, як-от маркери локальних, OAuth або ambient credential.
|
||||
Core трактує їх як не секретні для відображення auth і аудиту секретів без
|
||||
жорсткого кодування власника provider.
|
||||
- `channelEnvVars` — це дешевий шлях метаданих для shell-env fallback, запитів setup
|
||||
і подібних поверхонь channel, які не повинні запускати runtime plugin
|
||||
лише для перевірки назв env.
|
||||
- `providerAuthChoices` — це дешевий шлях метаданих для picker вибору auth,
|
||||
розв’язання `--auth-choice`, мапінгу бажаного provider і простої реєстрації
|
||||
прапорців CLI для onboarding до завантаження runtime provider. Метадані wizard runtime,
|
||||
які потребують коду provider, див. у
|
||||
[Хуки runtime provider](/uk/plugins/architecture#provider-runtime-hooks).
|
||||
- Ексклюзивні види plugin вибираються через `plugins.slots.*`.
|
||||
- Маніфест є **обов’язковим для рідних плагінів OpenClaw**, включно з локальними завантаженнями з файлової системи.
|
||||
- Середовище виконання все одно завантажує модуль плагіна окремо; маніфест використовується лише для виявлення + валідації.
|
||||
- Рідні маніфести аналізуються через JSON5, тож коментарі, кінцеві коми й не взяті в лапки ключі допускаються, доки кінцеве значення все ще є об’єктом.
|
||||
- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання тут користувацьких ключів верхнього рівня.
|
||||
- `providerAuthEnvVars` — це недорогий шлях метаданих для перевірок автентифікації, валідації env-marker та подібних поверхонь автентифікації провайдера, які не повинні запускати середовище виконання плагіна лише для перевірки назв env.
|
||||
- `providerAuthAliases` дозволяє варіантам провайдера повторно використовувати env vars автентифікації, профілі автентифікації, автентифікацію на основі конфігурації та варіант онбордингу з API-ключем іншого провайдера без жорсткого кодування цього зв’язку в ядрі.
|
||||
- `providerEndpoints` дозволяє плагінам провайдерів володіти простими метаданими зіставлення хостів/baseUrl кінцевих точок. Використовуйте це лише для класів кінцевих точок, які ядро вже підтримує; поведінкою під час виконання все одно володіє плагін.
|
||||
- `syntheticAuthRefs` — це недорогий шлях метаданих для синтетичних hook-ів автентифікації, що належать провайдеру і мають бути видимими для холодного виявлення моделей до того, як з’явиться реєстр середовища виконання. Перелічуйте лише ті посилання, чий runtime-провайдер або backend CLI справді реалізує `resolveSyntheticAuth`.
|
||||
- `nonSecretAuthMarkers` — це недорогий шлях метаданих для значень-заповнювачів API-ключів, що належать bundled-плагіну, наприклад маркерів локальних, OAuth або ambient credentials. Ядро розглядає їх як несекретні для відображення автентифікації та аудитів секретів без жорсткого кодування провайдера-власника.
|
||||
- `channelEnvVars` — це недорогий шлях метаданих для резервного використання shell-env, підказок налаштування та подібних поверхонь каналу, які не повинні запускати середовище виконання плагіна лише для перевірки назв env.
|
||||
- `providerAuthChoices` — це недорогий шлях метаданих для селекторів варіантів автентифікації, розв’язання `--auth-choice`, мапінгу пріоритетного провайдера та простої реєстрації прапорців CLI для онбордингу до завантаження середовища виконання провайдера. Для метаданих runtime wizard, що потребують коду провайдера, дивіться [Provider runtime hooks](/uk/plugins/architecture#provider-runtime-hooks).
|
||||
- Ексклюзивні типи плагінів вибираються через `plugins.slots.*`.
|
||||
- `kind: "memory"` вибирається через `plugins.slots.memory`.
|
||||
- `kind: "context-engine"` вибирається через `plugins.slots.contextEngine`
|
||||
(типово: вбудований `legacy`).
|
||||
- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо plugin
|
||||
їх не потребує.
|
||||
- Якщо ваш plugin залежить від власних модулів, задокументуйте кроки збірки та всі
|
||||
вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts`
|
||||
- `kind: "context-engine"` вибирається через `plugins.slots.contextEngine` (типово: вбудований `legacy`).
|
||||
- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо плагін їх не потребує.
|
||||
- Якщо ваш плагін залежить від native modules, задокументуйте кроки збірки та всі вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts`
|
||||
- `pnpm rebuild <package>`).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з plugin
|
||||
- [Архітектура Plugin](/uk/plugins/architecture) — внутрішня архітектура
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — довідник SDK Plugin
|
||||
- [Building Plugins](/uk/plugins/building-plugins) — початок роботи з плагінами
|
||||
- [Plugin Architecture](/uk/plugins/architecture) — внутрішня архітектура
|
||||
- [SDK Overview](/uk/plugins/sdk-overview) — довідник Plugin SDK
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
---
|
||||
read_when:
|
||||
- Вам потрібен точний сигнатурний тип definePluginEntry або defineChannelPluginEntry
|
||||
- Ви хочете зрозуміти режим реєстрації (повний vs setup vs метадані CLI)
|
||||
- Вам потрібен точний сигнатурний тип для definePluginEntry або defineChannelPluginEntry
|
||||
- Ви хочете зрозуміти режим реєстрації (повний, setup чи метадані CLI)
|
||||
- Ви шукаєте параметри точки входу
|
||||
sidebarTitle: Entry Points
|
||||
summary: Довідка для definePluginEntry, defineChannelPluginEntry і defineSetupPluginEntry
|
||||
summary: Довідка щодо definePluginEntry, defineChannelPluginEntry та defineSetupPluginEntry
|
||||
title: Точки входу Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-21T22:18:59Z"
|
||||
generated_at: "2026-04-22T00:13:58Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 304501849aa835b775f9b7b85c507aaeb532f90bf6473d7644f0e41144d9a914
|
||||
source_hash: b794e1a880e4a32318236fab515f5fd395a0c8c2d1a0e6a4ea388eef447975a7
|
||||
source_path: plugins/sdk-entrypoints.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -20,7 +20,7 @@ x-i18n:
|
||||
Кожен plugin експортує типовий об’єкт точки входу. SDK надає три допоміжні функції для
|
||||
їх створення.
|
||||
|
||||
Для встановлених plugin-ів `package.json` має спрямовувати завантаження під час виконання на зібраний
|
||||
Для встановлених plugin `package.json` має вказувати завантаженню під час виконання на зібраний
|
||||
JavaScript, коли він доступний:
|
||||
|
||||
```json
|
||||
@ -34,19 +34,23 @@ JavaScript, коли він доступний:
|
||||
}
|
||||
```
|
||||
|
||||
`extensions` і `setupEntry` залишаються чинними записами вихідного коду для розробки у workspace та git
|
||||
checkout. `runtimeExtensions` і `runtimeSetupEntry` мають пріоритет, коли OpenClaw завантажує встановлений package, і дають змогу npm package-ам уникати компіляції TypeScript під час виконання. Якщо встановлений package оголошує лише запис вихідного коду TypeScript, OpenClaw використає відповідний зібраний `dist/*.js` peer, якщо він існує, а потім повернеться до вихідного коду TypeScript.
|
||||
`extensions` і `setupEntry` залишаються чинними вихідними точками входу для розробки у workspace та з git checkout.
|
||||
`runtimeExtensions` і `runtimeSetupEntry` мають пріоритет, коли OpenClaw завантажує встановлений пакет, і дають змогу npm-пакетам уникати компіляції TypeScript під час виконання. Якщо встановлений пакет оголошує лише вихідну точку входу TypeScript, OpenClaw використає відповідний зібраний peer `dist/*.js`, якщо він існує, а потім повернеться до вихідного TypeScript-коду.
|
||||
|
||||
Усі шляхи точок входу мають залишатися в межах каталогу пакета plugin. Точки входу під час виконання
|
||||
та виведені з них зібрані peer JavaScript не роблять коректним вихідний шлях `extensions` або
|
||||
`setupEntry`, що виходить за ці межі.
|
||||
|
||||
<Tip>
|
||||
**Шукаєте покрокове пояснення?** Дивіться [Channel Plugins](/uk/plugins/sdk-channel-plugins)
|
||||
або [Provider Plugins](/uk/plugins/sdk-provider-plugins) для покрокових інструкцій.
|
||||
**Шукаєте покрокову інструкцію?** Дивіться [Channel Plugins](/uk/plugins/sdk-channel-plugins)
|
||||
або [Provider Plugins](/uk/plugins/sdk-provider-plugins) для покрокових посібників.
|
||||
</Tip>
|
||||
|
||||
## `definePluginEntry`
|
||||
|
||||
**Імпорт:** `openclaw/plugin-sdk/plugin-entry`
|
||||
|
||||
Для plugin-ів провайдерів, plugin-ів інструментів, plugin-ів хуків і всього, що **не є**
|
||||
Для plugin провайдерів, plugin інструментів, plugin хуків та всього, що **не** є
|
||||
каналом обміну повідомленнями.
|
||||
|
||||
```typescript
|
||||
@ -67,7 +71,7 @@ export default definePluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
| Поле | Тип | Обов’язкове | Типове значення |
|
||||
| Поле | Тип | Обов’язкове | Типово |
|
||||
| -------------- | ---------------------------------------------------------------- | ----------- | ------------------- |
|
||||
| `id` | `string` | Так | — |
|
||||
| `name` | `string` | Так | — |
|
||||
@ -78,8 +82,8 @@ export default definePluginEntry({
|
||||
|
||||
- `id` має збігатися з вашим маніфестом `openclaw.plugin.json`.
|
||||
- `kind` призначене для ексклюзивних слотів: `"memory"` або `"context-engine"`.
|
||||
- `configSchema` може бути функцією для лінивого обчислення.
|
||||
- OpenClaw розв’язує та мемоізує цю схему під час першого доступу, тому дорогі
|
||||
- `configSchema` може бути функцією для лінивої обробки.
|
||||
- OpenClaw визначає та мемоїзує цю схему при першому зверненні, тож витратні
|
||||
побудовники схем виконуються лише один раз.
|
||||
|
||||
## `defineChannelPluginEntry`
|
||||
@ -87,8 +91,8 @@ export default definePluginEntry({
|
||||
**Імпорт:** `openclaw/plugin-sdk/channel-core`
|
||||
|
||||
Обгортає `definePluginEntry` логікою, специфічною для каналів. Автоматично викликає
|
||||
`api.registerChannel({ plugin })`, надає необов’язковий seam метаданих CLI для кореневої довідки та
|
||||
обмежує `registerFull` відповідно до режиму реєстрації.
|
||||
`api.registerChannel({ plugin })`, надає необов’язковий шов метаданих CLI для кореневої довідки
|
||||
та керує `registerFull` залежно від режиму реєстрації.
|
||||
|
||||
```typescript
|
||||
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
@ -108,7 +112,7 @@ export default defineChannelPluginEntry({
|
||||
});
|
||||
```
|
||||
|
||||
| Поле | Тип | Обов’язкове | Типове значення |
|
||||
| Поле | Тип | Обов’язкове | Типово |
|
||||
| --------------------- | ---------------------------------------------------------------- | ----------- | ------------------- |
|
||||
| `id` | `string` | Так | — |
|
||||
| `name` | `string` | Так | — |
|
||||
@ -120,32 +124,33 @@ export default defineChannelPluginEntry({
|
||||
| `registerFull` | `(api: OpenClawPluginApi) => void` | Ні | — |
|
||||
|
||||
- `setRuntime` викликається під час реєстрації, тож ви можете зберегти посилання на runtime
|
||||
(зазвичай через `createPluginRuntimeStore`). Воно пропускається під час захоплення
|
||||
(зазвичай через `createPluginRuntimeStore`). Вона пропускається під час збирання
|
||||
метаданих CLI.
|
||||
- `registerCliMetadata` виконується як під час `api.registrationMode === "cli-metadata"`,
|
||||
так і під час `api.registrationMode === "full"`.
|
||||
Використовуйте його як канонічне місце для дескрипторів CLI, що належать каналу, щоб
|
||||
коренева довідка залишалася без активації, а звичайна реєстрація команд CLI залишалася сумісною
|
||||
з повним завантаженням plugin-ів.
|
||||
- `registerFull` виконується лише коли `api.registrationMode === "full"`. Воно пропускається
|
||||
Використовуйте її як канонічне місце для дескрипторів CLI, що належать каналу, щоб
|
||||
коренева довідка не активувала plugin, а звичайна реєстрація команд CLI залишалася
|
||||
сумісною з повним завантаженням plugin.
|
||||
- `registerFull` виконується лише коли `api.registrationMode === "full"`. Вона пропускається
|
||||
під час завантаження лише для setup.
|
||||
- Як і у `definePluginEntry`, `configSchema` може бути лінивою фабрикою, а OpenClaw
|
||||
мемоізує розв’язану схему під час першого доступу.
|
||||
- Для кореневих команд CLI, що належать plugin-у, віддавайте перевагу `api.registerCli(..., { descriptors: [...] })`,
|
||||
якщо хочете, щоб команда залишалася ліниво завантажуваною без зникнення з
|
||||
дерева розбору кореневого CLI. Для channel plugin-ів краще реєструвати ці дескриптори
|
||||
з `registerCliMetadata(...)`, а `registerFull(...)` зосередити на роботі, потрібній лише під час виконання.
|
||||
- Якщо `registerFull(...)` також реєструє методи Gateway RPC, залишайте їх на
|
||||
префіксі, специфічному для plugin-а. Зарезервовані простори імен core admin (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) завжди примусово приводяться до
|
||||
мемоїзує визначену схему при першому зверненні.
|
||||
- Для кореневих команд CLI, що належать plugin, надавайте перевагу `api.registerCli(..., { descriptors: [...] })`,
|
||||
якщо хочете, щоб команда залишалася ліниво завантажуваною, але не зникала з
|
||||
дерева розбору кореневого CLI. Для channel plugin надавайте перевагу реєстрації
|
||||
цих дескрипторів із `registerCliMetadata(...)`, а `registerFull(...)` залишайте
|
||||
зосередженим на роботі лише під час виконання.
|
||||
- Якщо `registerFull(...)` також реєструє RPC-методи Gateway, зберігайте для них
|
||||
префікс, специфічний для plugin. Зарезервовані простори назв адміністрування ядра (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) завжди примусово переводяться до
|
||||
`operator.admin`.
|
||||
|
||||
## `defineSetupPluginEntry`
|
||||
|
||||
**Імпорт:** `openclaw/plugin-sdk/channel-core`
|
||||
|
||||
Для полегшеного файлу `setup-entry.ts`. Повертає лише `{ plugin }` без
|
||||
логіки runtime або CLI.
|
||||
Для полегшеного файла `setup-entry.ts`. Повертає лише `{ plugin }` без
|
||||
логіки runtime чи CLI.
|
||||
|
||||
```typescript
|
||||
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
@ -153,27 +158,27 @@ import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
|
||||
export default defineSetupPluginEntry(myChannelPlugin);
|
||||
```
|
||||
|
||||
OpenClaw завантажує це замість повної точки входу, коли канал вимкнено,
|
||||
не налаштовано або коли ввімкнено відкладене завантаження. Див.
|
||||
OpenClaw завантажує це замість повної точки входу, коли канал вимкнений,
|
||||
не налаштований або коли ввімкнено відкладене завантаження. Див.
|
||||
[Setup and Config](/uk/plugins/sdk-setup#setup-entry), щоб зрозуміти, коли це має значення.
|
||||
|
||||
На практиці поєднуйте `defineSetupPluginEntry(...)` із вузькими сімействами
|
||||
допоміжних функцій setup:
|
||||
|
||||
- `openclaw/plugin-sdk/setup-runtime` для безпечних для runtime допоміжних функцій setup, таких як
|
||||
import-safe адаптери патчів setup, вивід lookup-note,
|
||||
безпечні для імпорту адаптери patch setup, виведення приміток пошуку,
|
||||
`promptResolvedAllowFrom`, `splitSetupEntries` і делеговані проксі setup
|
||||
- `openclaw/plugin-sdk/channel-setup` для поверхонь setup з необов’язковим встановленням
|
||||
- `openclaw/plugin-sdk/setup-tools` для допоміжних функцій setup/install CLI/archive/docs
|
||||
- `openclaw/plugin-sdk/setup-tools` для допоміжних засобів setup/install CLI/archive/docs
|
||||
|
||||
Тримайте важкі SDK, реєстрацію CLI та довгоживучі runtime-сервіси в повній
|
||||
Залишайте важкі SDK, реєстрацію CLI та довготривалі сервіси runtime у повній
|
||||
точці входу.
|
||||
|
||||
Вбудовані workspace-канали, які розділяють поверхні setup і runtime, можуть
|
||||
замість цього використовувати `defineBundledChannelSetupEntry(...)` з
|
||||
`openclaw/plugin-sdk/channel-entry-contract`. Цей контракт дає змогу
|
||||
точці входу setup зберігати безпечні для setup експорти plugin/secrets, водночас надаючи
|
||||
setter runtime:
|
||||
використовувати `defineBundledChannelSetupEntry(...)` з
|
||||
`openclaw/plugin-sdk/channel-entry-contract` замість цього. Цей контракт дає змогу
|
||||
точці входу setup зберігати безпечні для setup експорти plugin/secrets, водночас
|
||||
усе ще надаючи сетер runtime:
|
||||
|
||||
```typescript
|
||||
import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";
|
||||
@ -191,19 +196,19 @@ export default defineBundledChannelSetupEntry({
|
||||
});
|
||||
```
|
||||
|
||||
Використовуйте цей вбудований контракт лише тоді, коли потокам setup справді потрібен полегшений
|
||||
setter runtime до завантаження повної точки входу каналу.
|
||||
Використовуйте цей вбудований контракт лише тоді, коли потокам setup справді потрібен
|
||||
полегшений сетер runtime до завантаження повної точки входу каналу.
|
||||
|
||||
## Режим реєстрації
|
||||
|
||||
`api.registrationMode` повідомляє вашому plugin-у, як саме його було завантажено:
|
||||
`api.registrationMode` повідомляє вашому plugin, як саме його було завантажено:
|
||||
|
||||
| Режим | Коли | Що реєструвати |
|
||||
| ---------------- | --------------------------------- | --------------------------------------------------------------------------------------- |
|
||||
| `"full"` | Звичайний запуск Gateway | Усе |
|
||||
| `"setup-only"` | Вимкнений/неналаштований канал | Лише реєстрацію каналу |
|
||||
| `"setup-runtime"`| Потік setup із доступним runtime | Реєстрацію каналу плюс лише полегшений runtime, потрібний до завантаження повної точки входу |
|
||||
| `"cli-metadata"` | Коренева довідка / захоплення метаданих CLI | Лише дескриптори CLI |
|
||||
| Режим | Коли | Що реєструвати |
|
||||
| ----------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `"full"` | Звичайний запуск Gateway | Усе |
|
||||
| `"setup-only"` | Вимкнений/не налаштований канал | Лише реєстрацію каналу |
|
||||
| `"setup-runtime"` | Потік setup з доступним runtime | Реєстрацію каналу плюс лише полегшений runtime, потрібний до завантаження повної точки входу |
|
||||
| `"cli-metadata"` | Коренева довідка / збирання метаданих CLI | Лише дескриптори CLI |
|
||||
|
||||
`defineChannelPluginEntry` обробляє це розділення автоматично. Якщо ви використовуєте
|
||||
`definePluginEntry` безпосередньо для каналу, перевіряйте режим самостійно:
|
||||
@ -223,37 +228,37 @@ register(api) {
|
||||
}
|
||||
```
|
||||
|
||||
Розглядайте `"setup-runtime"` як вікно, у якому поверхні запуску лише для setup
|
||||
мають існувати без повторного входу в повний вбудований runtime каналу. Добре підходять
|
||||
Сприймайте `"setup-runtime"` як проміжок, у якому поверхні запуску лише для setup мають
|
||||
існувати без повторного входу до повного вбудованого runtime каналу. Доречні варіанти —
|
||||
реєстрація каналу, безпечні для setup HTTP-маршрути, безпечні для setup методи Gateway і
|
||||
делеговані допоміжні функції setup. Важкі фонові сервіси, реєстратори CLI та
|
||||
завантаження SDK провайдерів/клієнтів, як і раніше, мають належати `"full"`.
|
||||
запуск SDK провайдерів/клієнтів, як і раніше, належать до `"full"`.
|
||||
|
||||
Зокрема для реєстраторів CLI:
|
||||
|
||||
- використовуйте `descriptors`, коли реєстратор володіє однією або кількома кореневими командами і ви
|
||||
хочете, щоб OpenClaw ліниво завантажував справжній модуль CLI під час першого виклику
|
||||
- переконайтеся, що ці дескриптори охоплюють кожний корінь команди верхнього рівня, який відкриває
|
||||
хочете, щоб OpenClaw ліниво завантажував справжній модуль CLI при першому виклику
|
||||
- переконайтеся, що ці дескриптори охоплюють кожен корінь команди верхнього рівня, який надає
|
||||
реєстратор
|
||||
- використовуйте лише `commands` тільки для шляхів сумісності з eager-завантаженням
|
||||
|
||||
## Форми plugin-ів
|
||||
## Форми plugin
|
||||
|
||||
OpenClaw класифікує завантажені plugin-и за їхньою поведінкою під час реєстрації:
|
||||
OpenClaw класифікує завантажені plugin за їхньою поведінкою під час реєстрації:
|
||||
|
||||
| Форма | Опис |
|
||||
| --------------------- | ------------------------------------------------- |
|
||||
| **plain-capability** | Один тип capability (наприклад, лише provider) |
|
||||
| **hybrid-capability** | Кілька типів capability (наприклад, provider + speech) |
|
||||
| **hook-only** | Лише hooks, без capabilities |
|
||||
| **non-capability** | Tools/commands/services, але без capabilities |
|
||||
| Форма | Опис |
|
||||
| -------------------- | ------------------------------------------------- |
|
||||
| **plain-capability** | Один тип можливостей (наприклад, лише провайдер) |
|
||||
| **hybrid-capability** | Кілька типів можливостей (наприклад, провайдер + мовлення) |
|
||||
| **hook-only** | Лише хуки, без можливостей |
|
||||
| **non-capability** | Інструменти/команди/сервіси, але без можливостей |
|
||||
|
||||
Використовуйте `openclaw plugins inspect <id>`, щоб побачити форму plugin-а.
|
||||
Використовуйте `openclaw plugins inspect <id>`, щоб побачити форму plugin.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [SDK Overview](/uk/plugins/sdk-overview) — API реєстрації та довідка щодо subpath
|
||||
- [SDK Overview](/uk/plugins/sdk-overview) — API реєстрації та довідник підшляхів
|
||||
- [Runtime Helpers](/uk/plugins/sdk-runtime) — `api.runtime` і `createPluginRuntimeStore`
|
||||
- [Setup and Config](/uk/plugins/sdk-setup) — маніфест, точка входу setup, відкладене завантаження
|
||||
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — побудова об’єкта `ChannelPlugin`
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — реєстрація провайдерів і hooks
|
||||
- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — реєстрація провайдерів і хуків
|
||||
|
||||
Loading…
Reference in New Issue
Block a user