chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
f8f2d1ab01
commit
fe64db0020
File diff suppressed because it is too large
Load Diff
@ -1,65 +1,81 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви створюєте плагін OpenClaw
|
||||
- Вам потрібно постачати схему конфігурації плагіна або налагоджувати помилки валідації плагіна
|
||||
summary: Вимоги до маніфесту Plugin + схеми JSON (сувора валідація конфігурації)
|
||||
- Ви створюєте Plugin для OpenClaw
|
||||
- Вам потрібно постачати схему конфігурації Plugin або налагоджувати помилки валідації Plugin
|
||||
summary: Вимоги до маніфесту Plugin і схеми JSON (сувора валідація конфігурації)
|
||||
title: Маніфест Plugin
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T06:24:10Z"
|
||||
generated_at: "2026-04-23T07:42:09Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: de71b9d556c2696d3279f202b66d57aa8014e9c89d81e3f453602744120d1675
|
||||
source_hash: d48810f604aa0c3ff8553528cfa4cb735d1d5e7a15b1bbca6152070d6c8f9cce
|
||||
source_path: plugins/manifest.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Маніфест Plugin (`openclaw.plugin.json`)
|
||||
|
||||
Ця сторінка стосується лише **власного маніфесту плагіна OpenClaw**.
|
||||
Ця сторінка стосується лише **власного маніфесту Plugin OpenClaw**.
|
||||
|
||||
Сумісні компонування пакетів описано в [Пакети Plugin](/uk/plugins/bundles).
|
||||
Сумісні макети пакетів описано в [Пакети Plugin](/uk/plugins/bundles).
|
||||
|
||||
Сумісні формати пакетів використовують інші файли маніфесту:
|
||||
|
||||
- пакет Codex: `.codex-plugin/plugin.json`
|
||||
- пакет Claude: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude без маніфесту
|
||||
- пакет Claude: `.claude-plugin/plugin.json` або стандартний макет компонента Claude
|
||||
без маніфесту
|
||||
- пакет Cursor: `.cursor-plugin/plugin.json`
|
||||
|
||||
OpenClaw також автоматично виявляє ці компонування пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут.
|
||||
OpenClaw також автоматично визначає ці макети пакетів, але вони не проходять валідацію
|
||||
за схемою `openclaw.plugin.json`, описаною тут.
|
||||
|
||||
Для сумісних пакетів OpenClaw наразі зчитує метадані пакета, а також оголошені корені skills, корені команд Claude, значення за замовчуванням `settings.json` пакета Claude, значення LSP за замовчуванням пакета Claude та підтримувані набори хуків, коли компонування відповідає очікуванням середовища виконання OpenClaw.
|
||||
Для сумісних пакетів OpenClaw наразі зчитує метадані пакета разом з оголошеними
|
||||
коренями Skills, коренями команд Claude, значеннями за замовчуванням `settings.json` у пакеті Claude,
|
||||
значеннями LSP за замовчуванням у пакеті Claude та підтримуваними наборами хуків, коли макет відповідає
|
||||
очікуванням середовища виконання OpenClaw.
|
||||
|
||||
Кожен власний плагін OpenClaw **повинен** містити файл `openclaw.plugin.json` у **корені плагіна**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду плагіна**. Відсутні або невалідні маніфести вважаються помилками плагіна й блокують валідацію конфігурації.
|
||||
Кожен власний Plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у
|
||||
**корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації
|
||||
**без виконання коду Plugin**. Відсутні або невалідні маніфести вважаються
|
||||
помилками Plugin і блокують валідацію конфігурації.
|
||||
|
||||
Повний посібник із системи плагінів див. у розділі [Plugins](/uk/tools/plugin).
|
||||
Для власної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності:
|
||||
Дивіться повний посібник із системи Plugin: [Plugins](/uk/tools/plugin).
|
||||
Щодо власної моделі можливостей і поточних рекомендацій із зовнішньої сумісності:
|
||||
[Модель можливостей](/uk/plugins/architecture#public-capability-model).
|
||||
|
||||
## Що робить цей файл
|
||||
|
||||
`openclaw.plugin.json` — це метадані, які OpenClaw зчитує перед завантаженням коду вашого плагіна.
|
||||
`openclaw.plugin.json` — це метадані, які OpenClaw зчитує перед завантаженням коду
|
||||
вашого Plugin.
|
||||
|
||||
Використовуйте його для:
|
||||
|
||||
- ідентифікації плагіна
|
||||
- ідентичності Plugin
|
||||
- валідації конфігурації
|
||||
- метаданих автентифікації та онбордингу, які мають бути доступні без запуску середовища виконання плагіна
|
||||
- недорогих підказок активації, які поверхні control plane можуть перевіряти до завантаження середовища виконання
|
||||
- недорогих дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до завантаження середовища виконання
|
||||
- метаданих псевдонімів та автоувімкнення, які мають визначатися до завантаження середовища виконання плагіна
|
||||
- скорочених метаданих належності до сімейства моделей, які мають автоматично активувати плагін до завантаження середовища виконання
|
||||
- статичних знімків належності можливостей, що використовуються для вбудованої сумісної прив’язки та покриття контрактів
|
||||
- недорогих метаданих засобу запуску QA, які спільний хост `openclaw qa` може перевіряти до завантаження середовища виконання плагіна
|
||||
- метаданих конфігурації, специфічних для каналу, які мають об’єднуватися в поверхні каталогу та валідації без завантаження середовища виконання
|
||||
- метаданих автентифікації та онбордингу, які мають бути доступні без запуску
|
||||
середовища виконання Plugin
|
||||
- недорогих підказок активації, які поверхні control plane можуть перевіряти до
|
||||
завантаження середовища виконання
|
||||
- недорогих дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до
|
||||
завантаження середовища виконання
|
||||
- метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження середовища виконання Plugin
|
||||
- метаданих скороченого володіння сімейством моделей, які мають автоматично активувати
|
||||
Plugin до завантаження середовища виконання
|
||||
- статичних знімків володіння можливостями, що використовуються для сумісного вбудованого з’єднання та
|
||||
покриття контрактів
|
||||
- недорогих метаданих запускальника QA, які спільний хост `openclaw qa` може перевіряти
|
||||
до завантаження середовища виконання Plugin
|
||||
- метаданих конфігурації, специфічних для каналу, які мають об’єднуватися в поверхні каталогу та валідації
|
||||
без завантаження середовища виконання
|
||||
- підказок UI конфігурації
|
||||
|
||||
Не використовуйте його для:
|
||||
|
||||
- реєстрації поведінки середовища виконання
|
||||
- реєстрації поведінки під час виконання
|
||||
- оголошення точок входу коду
|
||||
- метаданих встановлення npm
|
||||
|
||||
Це належить вашому коду плагіна та `package.json`.
|
||||
Це належить до коду вашого Plugin і `package.json`.
|
||||
|
||||
## Мінімальний приклад
|
||||
|
||||
@ -139,65 +155,67 @@ OpenClaw також автоматично виявляє ці компонув
|
||||
|
||||
## Довідник полів верхнього рівня
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Канонічний ідентифікатор плагіна. Це ідентифікатор, який використовується в `plugins.entries.<id>`. |
|
||||
| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього плагіна. |
|
||||
| `enabledByDefault` | Ні | `true` | Позначає вбудований плагін як увімкнений за замовчуванням. Пропустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб плагін залишався вимкненим за замовчуванням. |
|
||||
| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора плагіна. |
|
||||
| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей плагін, коли автентифікація, конфігурація або посилання на моделі згадують їх. |
|
||||
| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип плагіна, який використовується `plugins.slots.*`. |
|
||||
| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей плагін. Використовується для виявлення та валідації конфігурації. |
|
||||
| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей плагін. |
|
||||
| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, якими володіє маніфест і які використовуються для автозавантаження плагіна до завантаження середовища виконання. |
|
||||
| `providerEndpoints` | Ні | `object[]` | Метадані хостів/`baseUrl` кінцевих точок, якими володіє маніфест, для маршрутів провайдерів, які ядро має класифікувати до завантаження середовища виконання провайдера. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI inference, якими володіє цей плагін. Використовується для автоактивації під час запуску з явних посилань конфігурації. |
|
||||
| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або backend CLI, для яких синтетичний хук автентифікації, що належить плагіну, має перевірятися під час холодного виявлення моделей до завантаження середовища виконання. |
|
||||
| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, що належать вбудованому плагіну й представляють не секретний локальний стан, OAuth або ambient credential state. |
|
||||
| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей плагін і які мають видавати обізнані про плагін діагностики конфігурації та CLI до завантаження середовища виконання. |
|
||||
| `providerAuthEnvVars` | Ні | `Record<string, string[]>` | Недорогі метадані env автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду плагіна. |
|
||||
| `providerAuthAliases` | Ні | `Record<string, string>` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад провайдер для кодування, який спільно використовує API-ключ базового провайдера та профілі автентифікації. |
|
||||
| `channelEnvVars` | Ні | `Record<string, string[]>` | Недорогі метадані env каналу, які OpenClaw може перевіряти без завантаження коду плагіна. Використовуйте це для налаштування каналу через env або поверхонь автентифікації, які мають бути видимі загальним helper запуску/конфігурації. |
|
||||
| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані вибору автентифікації для засобів вибору в онбордингу, визначення пріоритетного провайдера та простого зв’язування CLI flags. |
|
||||
| `activation` | Ні | `object` | Недорогі підказки активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактична поведінка, як і раніше, належить середовищу виконання плагіна. |
|
||||
| `setup` | Ні | `object` | Недорогі дескриптори налаштування/онбордингу, які поверхні виявлення й налаштування можуть перевіряти без завантаження середовища виконання плагіна. |
|
||||
| `qaRunners` | Ні | `object[]` | Недорогі дескриптори засобів запуску QA, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання плагіна. |
|
||||
| `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`. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Канонічний id Plugin. Це id, який використовується в `plugins.entries.<id>`. |
|
||||
| `configSchema` | Так | `object` | Вбудована схема JSON для конфігурації цього 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. |
|
||||
| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, якими володіє маніфест і які використовуються для автоматичного завантаження Plugin до запуску середовища виконання. |
|
||||
| `providerEndpoints` | Ні | `object[]` | Метадані хостів/`baseUrl` кінцевих точок, якими володіє маніфест, для маршрутів провайдера, які ядро повинно класифікувати до завантаження середовища виконання провайдера. |
|
||||
| `cliBackends` | Ні | `string[]` | Id backend-ів інференсу CLI, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних посилань у конфігурації. |
|
||||
| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдери або backend-и CLI, для яких під час холодного виявлення моделей до завантаження середовища виконання слід перевіряти синтетичний хук автентифікації, що належить Plugin. |
|
||||
| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API-ключів, що належать вбудованому Plugin і представляють несекретний локальний стан, OAuth або ambient credential state. |
|
||||
| `commandAliases` | Ні | `object[]` | Імена команд, що належать цьому Plugin і мають видавати діагностику конфігурації та CLI з урахуванням Plugin до завантаження середовища виконання. |
|
||||
| `providerAuthEnvVars` | Ні | `Record<string, string[]>` | Недорогі метадані env для автентифікації провайдера, які OpenClaw може перевіряти без завантаження коду Plugin. |
|
||||
| `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, які використовує спільний хост `openclaw qa` до завантаження середовища виконання Plugin. |
|
||||
| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, мовлення, транскрибування в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, web search і володіння інструментами. |
|
||||
| `mediaUnderstandingProviderMetadata` | Ні | `Record<string, object>` | Недорогі значення за замовчуванням для розуміння медіа для id провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. |
|
||||
| `channelConfigs` | Ні | `Record<string, object>` | Метадані конфігурації каналу, якими володіє маніфест і які об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. |
|
||||
| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня плагіна. |
|
||||
| `name` | Ні | `string` | Людинозрозуміла назва плагіна. |
|
||||
| `description` | Ні | `string` | Короткий опис, що показується на поверхнях плагіна. |
|
||||
| `version` | Ні | `string` | Інформаційна версія плагіна. |
|
||||
| `uiHints` | Ні | `Record<string, object>` | Мітки UI, заповнювачі та підказки чутливості для полів конфігурації. |
|
||||
| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. |
|
||||
| `name` | Ні | `string` | Зрозуміла людині назва Plugin. |
|
||||
| `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. |
|
||||
| `version` | Ні | `string` | Інформаційна версія Plugin. |
|
||||
| `uiHints` | Ні | `Record<string, object>` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. |
|
||||
|
||||
## Довідник `providerAuthChoices`
|
||||
|
||||
Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації.
|
||||
OpenClaw зчитує це до завантаження середовища виконання провайдера.
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `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`. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `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"]`. |
|
||||
| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. |
|
||||
| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо пропущено, за замовчуванням це `["text-inference"]`. |
|
||||
|
||||
## Довідник `commandAliases`
|
||||
|
||||
Використовуйте `commandAliases`, коли плагіну належить ім’я команди середовища виконання, яке користувачі можуть помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду середовища виконання плагіна.
|
||||
Використовуйте `commandAliases`, коли Plugin володіє іменем команди середовища виконання, яке користувачі можуть
|
||||
помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw
|
||||
використовує ці метадані для діагностики без імпорту коду середовища виконання Plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -211,19 +229,23 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------ | ----------- | ----------------- | --------------------------------------------------------------------------- |
|
||||
| `name` | Так | `string` | Ім’я команди, яка належить цьому плагіну. |
|
||||
| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. |
|
||||
| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо вона існує. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------- |
|
||||
| `name` | Так | `string` | Ім’я команди, яке належить цьому Plugin. |
|
||||
| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. |
|
||||
| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід підказати для операцій CLI, якщо вона існує. |
|
||||
|
||||
## Довідник `activation`
|
||||
|
||||
Використовуйте `activation`, коли плагін може недорого оголосити, які події control plane мають активувати його пізніше.
|
||||
Використовуйте `activation`, коли Plugin може недорого оголосити, які події control plane
|
||||
мають активувати його пізніше.
|
||||
|
||||
## Довідник `qaRunners`
|
||||
|
||||
Використовуйте `qaRunners`, коли плагін додає один або кілька транспортних засобів запуску під спільним коренем `openclaw qa`. Зберігайте ці метадані недорогими й статичними; фактична реєстрація CLI, як і раніше, належить середовищу виконання плагіна через легковагову поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`.
|
||||
Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner-ів під спільним
|
||||
коренем `openclaw qa`. Зберігайте ці метадані легкими та статичними; середовище виконання Plugin
|
||||
як і раніше володіє фактичною реєстрацією CLI через легку поверхню
|
||||
`runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -236,13 +258,16 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | -------- | ----------------------------------------------------------------------- |
|
||||
| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. |
|
||||
| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | -------- | --------------------------------------------------------------------- |
|
||||
| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. |
|
||||
| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. |
|
||||
|
||||
Цей блок є лише метаданими. Він не реєструє поведінку середовища виконання і не замінює `register(...)`, `setupEntry` або інші точки входу середовища виконання/плагіна.
|
||||
Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням плагіна, тому відсутність метаданих активації зазвичай впливає лише на продуктивність; вона не має змінювати коректність, доки ще існують застарілі резервні механізми володіння маніфестом.
|
||||
Цей блок є лише метаданими. Він не реєструє поведінку під час виконання і не
|
||||
замінює `register(...)`, `setupEntry` або інші точки входу runtime/Plugin.
|
||||
Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому
|
||||
відсутність метаданих активації зазвичай лише впливає на продуктивність; вона не має
|
||||
змінювати коректність, доки все ще існують застарілі резервні механізми володіння маніфестом.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -256,23 +281,28 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
}
|
||||
```
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
|
||||
| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають активувати цей плагін на запит. |
|
||||
| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають активувати цей плагін. |
|
||||
| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають активувати цей плагін. |
|
||||
| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей плагін. |
|
||||
| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються під час планування активації control plane. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ---------------- | ----------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| `onProviders` | Ні | `string[]` | Id провайдерів, які мають активувати цей Plugin за запитом. |
|
||||
| `onCommands` | Ні | `string[]` | Id команд, які мають активувати цей Plugin. |
|
||||
| `onChannels` | Ні | `string[]` | Id каналів, які мають активувати цей Plugin. |
|
||||
| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей Plugin. |
|
||||
| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки можливостей, що використовуються плануванням активації control plane. |
|
||||
|
||||
Поточні активні споживачі:
|
||||
Поточні живі споживачі:
|
||||
|
||||
- планування CLI, що запускається командою, повертається до застарілого `commandAliases[].cliCommand` або `commandAliases[].name`
|
||||
- планування налаштування/каналу, що запускається каналом, повертається до застарілого володіння `channels[]`, якщо явні метадані активації каналу відсутні
|
||||
- планування налаштування/середовища виконання, що запускається провайдером, повертається до застарілого володіння `providers[]` і верхньорівневого `cliBackends[]`, якщо явні метадані активації провайдера відсутні
|
||||
- планування CLI, що запускається командою, повертається до застарілого
|
||||
`commandAliases[].cliCommand` або `commandAliases[].name`
|
||||
- планування налаштування/каналу, що запускається каналом, повертається до застарілого володіння
|
||||
`channels[]`, коли явні метадані активації каналу відсутні
|
||||
- планування налаштування/runtime, що запускається провайдером, повертається до застарілого
|
||||
володіння `providers[]` і `cliBackends[]` верхнього рівня, коли явні метадані активації провайдера
|
||||
відсутні
|
||||
|
||||
## Довідник `setup`
|
||||
|
||||
Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні недорогі метадані, що належать плагіну, до завантаження середовища виконання.
|
||||
Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні легкі метадані Plugin
|
||||
до завантаження середовища виконання.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -291,32 +321,41 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
}
|
||||
```
|
||||
|
||||
Верхньорівневе `cliBackends` залишається валідним і надалі описує backend CLI inference. `setup.cliBackends` — це поверхня дескрипторів, специфічна для налаштування, для потоків control plane/налаштування, які мають залишатися лише метаданими.
|
||||
`cliBackends` верхнього рівня залишається валідним і надалі описує backend-и інференсу CLI.
|
||||
`setup.cliBackends` — це поверхня дескрипторів, специфічна для налаштування, для потоків
|
||||
control plane/налаштування, які мають залишатися лише на рівні метаданих.
|
||||
|
||||
Якщо вони присутні, `setup.providers` і `setup.cliBackends` є пріоритетною поверхнею пошуку за принципом descriptor-first для виявлення налаштування. Якщо дескриптор лише звужує кандидатний плагін, а для налаштування все ще потрібні багатші хуки середовища виконання часу налаштування, установіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання.
|
||||
Якщо присутні `setup.providers` і `setup.cliBackends`, вони є бажаною
|
||||
поверхнею пошуку setup за принципом descriptor-first для виявлення налаштування. Якщо дескриптор лише
|
||||
звужує кандидатний Plugin, а налаштуванню все ще потрібні багатші runtime-хуки часу налаштування,
|
||||
встановіть `requiresRuntime: true` і залиште `setup-api` як
|
||||
резервний шлях виконання.
|
||||
|
||||
Оскільки пошук налаштування може виконувати код `setup-api`, що належить плагіну, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед виявлених плагінів. Неоднозначне володіння завершується в безпечному закритому стані замість вибору переможця за порядком виявлення.
|
||||
Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin,
|
||||
нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися
|
||||
унікальними серед виявлених Plugin. Неоднозначне володіння завершується закритою відмовою замість вибору
|
||||
переможця за порядком виявлення.
|
||||
|
||||
### Довідник `setup.providers`
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Ідентифікатор провайдера, який відкривається під час налаштування або онбордингу. Нормалізовані ідентифікатори мають бути глобально унікальними. |
|
||||
| `authMethods` | Ні | `string[]` | Ідентифікатори методів налаштування/автентифікації, які цей провайдер підтримує без завантаження повного середовища виконання. |
|
||||
| `envVars` | Ні | `string[]` | Змінні env, які загальні поверхні налаштування/стану можуть перевіряти до завантаження середовища виконання плагіна. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------- | ----------- | ---------- | ----------------------------------------------------------------------------------- |
|
||||
| `id` | Так | `string` | Id провайдера, що надається під час налаштування або онбордингу. Зберігайте нормалізовані id глобально унікальними. |
|
||||
| `authMethods` | Ні | `string[]` | Id методів налаштування/автентифікації, які цей провайдер підтримує без завантаження повного середовища виконання. |
|
||||
| `envVars` | Ні | `string[]` | Env vars, які універсальні поверхні налаштування/статусу можуть перевіряти до завантаження середовища виконання Plugin. |
|
||||
|
||||
### Поля `setup`
|
||||
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | Ні | `object[]` | Дескриптори налаштування провайдерів, що відкриваються під час налаштування та онбордингу. |
|
||||
| `cliBackends` | Ні | `string[]` | Ідентифікатори backend часу налаштування, що використовуються для пошуку налаштування за принципом descriptor-first. Нормалізовані ідентифікатори мають бути глобально унікальними. |
|
||||
| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, які належать поверхні налаштування цього плагіна. |
|
||||
| `requiresRuntime` | Ні | `boolean` | Чи потребує налаштування виконання `setup-api` після пошуку за дескриптором. |
|
||||
| Поле | Обов’язкове | Тип | Що воно означає |
|
||||
| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | Ні | `object[]` | Дескриптори налаштування провайдера, що надаються під час налаштування та онбордингу. |
|
||||
| `cliBackends` | Ні | `string[]` | Id backend-ів часу налаштування, що використовуються для пошуку setup за принципом descriptor-first. Зберігайте нормалізовані id глобально унікальними. |
|
||||
| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, якими володіє поверхня setup цього Plugin. |
|
||||
| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` навіть після пошуку за дескриптором. |
|
||||
|
||||
## Довідник `uiHints`
|
||||
|
||||
`uiHints` — це відображення від назв полів конфігурації до невеликих підказок рендерингу.
|
||||
`uiHints` — це мапа від імен полів конфігурації до невеликих підказок рендерингу.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -331,20 +370,21 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
}
|
||||
```
|
||||
|
||||
Кожна підказка для поля може містити:
|
||||
Кожна підказка поля може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ---------- | ----------------------------------------- |
|
||||
| `label` | `string` | Мітка поля для користувача. |
|
||||
| `help` | `string` | Короткий допоміжний текст. |
|
||||
| `tags` | `string[]` | Необов’язкові теги UI. |
|
||||
| `advanced` | `boolean` | Позначає поле як розширене. |
|
||||
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
|
||||
| `placeholder` | `string` | Текст-заповнювач для полів форми. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ---------- | --------------------------------------- |
|
||||
| `label` | `string` | Мітка поля для користувача. |
|
||||
| `help` | `string` | Короткий допоміжний текст. |
|
||||
| `tags` | `string[]` | Необов’язкові теги UI. |
|
||||
| `advanced` | `boolean` | Позначає поле як розширене. |
|
||||
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
|
||||
| `placeholder` | `string` | Текст-заповнювач для полів форми. |
|
||||
|
||||
## Довідник `contracts`
|
||||
|
||||
Використовуйте `contracts` лише для статичних метаданих належності можливостей, які OpenClaw може зчитати без імпорту середовища виконання плагіна.
|
||||
Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може
|
||||
зчитати без імпорту середовища виконання Plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -366,25 +406,31 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
|
||||
Кожен список є необов’язковим:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| -------------------------------- | ---------- | ------------------------------------------------------------------- |
|
||||
| `embeddedExtensionFactories` | `string[]` | Ідентифікатори вбудованого середовища виконання, для яких вбудований плагін може реєструвати фабрики. |
|
||||
| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, хук зовнішнього профілю автентифікації яких належить цьому плагіну. |
|
||||
| `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[]` | Назви інструментів агента, які належать цьому плагіну для перевірок контрактів вбудованих пакетів. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| -------------------------------- | ---------- | -------------------------------------------------------------------- |
|
||||
| `embeddedExtensionFactories` | `string[]` | Id вбудованого runtime, для яких вбудований Plugin може реєструвати фабрики. |
|
||||
| `externalAuthProviders` | `string[]` | Id провайдерів, чий зовнішній хук профілю автентифікації належить цьому Plugin. |
|
||||
| `speechProviders` | `string[]` | Id провайдерів мовлення, якими володіє цей Plugin. |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | Id провайдерів транскрибування в реальному часі, якими володіє цей Plugin. |
|
||||
| `realtimeVoiceProviders` | `string[]` | Id провайдерів голосу в реальному часі, якими володіє цей Plugin. |
|
||||
| `mediaUnderstandingProviders` | `string[]` | Id провайдерів розуміння медіа, якими володіє цей Plugin. |
|
||||
| `imageGenerationProviders` | `string[]` | Id провайдерів генерації зображень, якими володіє цей Plugin. |
|
||||
| `videoGenerationProviders` | `string[]` | Id провайдерів генерації відео, якими володіє цей Plugin. |
|
||||
| `webFetchProviders` | `string[]` | Id провайдерів web-fetch, якими володіє цей Plugin. |
|
||||
| `webSearchProviders` | `string[]` | Id провайдерів web search, якими володіє цей Plugin. |
|
||||
| `tools` | `string[]` | Імена інструментів агента, якими володіє цей Plugin для перевірок вбудованих контрактів. |
|
||||
|
||||
Плагіни провайдерів, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати `contracts.externalAuthProviders`. Плагіни без цього оголошення все ще працюють через застарілий резервний механізм сумісності, але він повільніший і буде видалений після завершення вікна міграції.
|
||||
Plugin провайдера, які реалізують `resolveExternalAuthProfiles`, повинні оголошувати
|
||||
`contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють
|
||||
через застарілий резервний механізм сумісності, але цей механізм повільніший і
|
||||
буде видалений після завершення вікна міграції.
|
||||
|
||||
## Довідник `mediaUnderstandingProviderMetadata`
|
||||
|
||||
Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має моделі за замовчуванням, пріоритет резервної auto-auth або власну підтримку документів, які потрібні загальним helper ядра до завантаження середовища виконання. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`.
|
||||
Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має
|
||||
моделі за замовчуванням, пріоритет резервного автоавтентифікації або власну підтримку документів, які
|
||||
універсальним допоміжним засобам ядра потрібні до завантаження runtime. Ключі також мають бути оголошені в
|
||||
`contracts.mediaUnderstandingProviders`.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -409,16 +455,17 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
|
||||
Кожен запис провайдера може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------ |
|
||||
| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. |
|
||||
| `defaultModels` | `Record<string, string>` | Значення моделей за замовчуванням для можливостей, що використовуються, коли конфігурація не вказує модель. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ---------------------- | ----------------------------------- | --------------------------------------------------------------------------- |
|
||||
| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості медіа, які надає цей провайдер. |
|
||||
| `defaultModels` | `Record<string, string>` | Типові значення зіставлення можливостей із моделями, які використовуються, коли конфігурація не задає модель. |
|
||||
| `autoPriority` | `Record<string, number>` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. |
|
||||
| `nativeDocumentInputs` | `"pdf"[]` | Власні вхідні дані документів, які підтримує провайдер. |
|
||||
| `nativeDocumentInputs` | `"pdf"[]` | Власні вхідні дані документів, які підтримує провайдер. |
|
||||
|
||||
## Довідник `channelConfigs`
|
||||
|
||||
Використовуйте `channelConfigs`, коли плагіну каналу потрібні недорогі метадані конфігурації до завантаження середовища виконання.
|
||||
Використовуйте `channelConfigs`, коли Plugin каналу потребує легких метаданих конфігурації до
|
||||
завантаження runtime.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -447,17 +494,18 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
|
||||
Кожен запис каналу може містити:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
|
||||
| `schema` | `object` | JSON Schema для `channels.<id>`. Обов’язкове для кожного оголошеного запису конфігурації каналу. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| ------------- | ------------------------ | ------------------------------------------------------------------------------- |
|
||||
| `schema` | `object` | Схема JSON для `channels.<id>`. Обов’язкова для кожного оголошеного запису конфігурації каналу. |
|
||||
| `uiHints` | `Record<string, object>` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. |
|
||||
| `label` | `string` | Мітка каналу, яка об’єднується в поверхні вибору та перегляду, коли метадані середовища виконання ще не готові. |
|
||||
| `description` | `string` | Короткий опис каналу для поверхонь перегляду та каталогу. |
|
||||
| `preferOver` | `string[]` | Ідентифікатори застарілих або нижчопріоритетних плагінів, які цей канал має перевершувати на поверхнях вибору. |
|
||||
| `label` | `string` | Мітка каналу, що об’єднується в поверхні вибору та інспектування, коли метадані runtime ще не готові. |
|
||||
| `description` | `string` | Короткий опис каналу для поверхонь інспектування та каталогу. |
|
||||
| `preferOver` | `string[]` | Id застарілих або менш пріоритетних Plugin, які цей канал має перевершувати в поверхнях вибору. |
|
||||
|
||||
## Довідник `modelSupport`
|
||||
|
||||
Використовуйте `modelSupport`, коли OpenClaw має визначати ваш плагін провайдера за скороченими ідентифікаторами моделей на кшталт `gpt-5.4` або `claude-sonnet-4.6` до завантаження середовища виконання плагіна.
|
||||
Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера з
|
||||
скорочених id моделей, таких як `gpt-5.4` або `claude-sonnet-4.6`, до завантаження runtime Plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -470,69 +518,100 @@ OpenClaw зчитує це до завантаження середовища в
|
||||
|
||||
OpenClaw застосовує такий пріоритет:
|
||||
|
||||
- явні посилання `provider/model` використовують метадані маніфесту `providers`, якому належить провайдер
|
||||
- `modelPatterns` мають пріоритет над `modelPrefixes`
|
||||
- якщо збігаються один невбудований плагін і один вбудований плагін, перемагає невбудований плагін
|
||||
- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть провайдера
|
||||
- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать власнику
|
||||
- `modelPatterns` мають вищий пріоритет за `modelPrefixes`
|
||||
- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований
|
||||
Plugin
|
||||
- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера
|
||||
|
||||
Поля:
|
||||
|
||||
| Поле | Тип | Що воно означає |
|
||||
| --------------- | ---------- | -------------------------------------------------------------------------------- |
|
||||
| `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. |
|
||||
| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. |
|
||||
| Поле | Тип | Що воно означає |
|
||||
| --------------- | ---------- | ------------------------------------------------------------------------------ |
|
||||
| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id моделей. |
|
||||
| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id моделей після видалення суфікса профілю. |
|
||||
|
||||
Застарілі ключі можливостей верхнього рівня не рекомендуються до використання. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` до `contracts`; звичайне завантаження маніфесту більше не розглядає ці поля верхнього рівня як належність можливостей.
|
||||
Застарілі ключі можливостей верхнього рівня застаріли. Використовуйте `openclaw doctor --fix`, щоб
|
||||
перемістити `speechProviders`, `realtimeTranscriptionProviders`,
|
||||
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
|
||||
`imageGenerationProviders`, `videoGenerationProviders`,
|
||||
`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне
|
||||
завантаження маніфесту більше не розглядає ці поля верхнього рівня як
|
||||
володіння можливостями.
|
||||
|
||||
## Маніфест versus package.json
|
||||
## Маніфест і `package.json`
|
||||
|
||||
Ці два файли виконують різні завдання:
|
||||
Ці два файли виконують різні ролі:
|
||||
|
||||
| Файл | Для чого використовувати |
|
||||
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду плагіна |
|
||||
| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для точок входу, обмежень встановлення, налаштування або метаданих каталогу |
|
||||
| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані вибору автентифікації та підказки UI, які мають існувати до запуску коду Plugin |
|
||||
| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для точок входу, обмеження встановлення, налаштування або метаданих каталогу |
|
||||
|
||||
Якщо ви не впевнені, куди має належати певний фрагмент метаданих, використовуйте таке правило:
|
||||
Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило:
|
||||
|
||||
- якщо OpenClaw має знати про нього до завантаження коду плагіна, розміщуйте його в `openclaw.plugin.json`
|
||||
- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json`
|
||||
- якщо OpenClaw має знати це до завантаження коду Plugin, помістіть це в `openclaw.plugin.json`
|
||||
- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, помістіть це в `package.json`
|
||||
|
||||
### Поля `package.json`, які впливають на виявлення
|
||||
|
||||
Деякі метадані плагіна до запуску середовища виконання навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`.
|
||||
Деякі метадані Plugin до запуску runtime навмисно розміщено в `package.json` у блоці
|
||||
`openclaw`, а не в `openclaw.plugin.json`.
|
||||
|
||||
Важливі приклади:
|
||||
|
||||
| Поле | Що воно означає |
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `openclaw.extensions` | Оголошує точки входу власного плагіна. Вони мають залишатися в межах каталогу пакета плагіна. |
|
||||
| `openclaw.runtimeExtensions` | Оголошує точки входу зібраного середовища виконання JavaScript для встановлених пакетів. Вони мають залишатися в межах каталогу пакета плагіна. |
|
||||
| `openclaw.setupEntry` | Легковагова точка входу лише для налаштування, що використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Вона має залишатися в межах каталогу пакета плагіна. |
|
||||
| `openclaw.runtimeSetupEntry` | Оголошує точку входу зібраного JavaScript для налаштування для встановлених пакетів. Вона має залишатися в межах каталогу пакета плагіна. |
|
||||
| `openclaw.channel` | Недорогі метадані каталогу каналу, як-от мітки, шляхи документації, псевдоніми та текст для вибору. |
|
||||
| `openclaw.channel.configuredState` | Метадані легковагового засобу перевірки налаштованого стану, який може відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного середовища виконання каналу. |
|
||||
| `openclaw.channel.persistedAuthState` | Метадані легковагового засобу перевірки збереженого стану автентифікації, який може відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного середовища виконання каналу. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих плагінів. |
|
||||
| `openclaw.install.defaultChoice` | Пріоритетний шлях встановлення, коли доступно кілька джерел встановлення. |
|
||||
| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw з використанням нижньої межі semver, наприклад `>=2026.3.22`. |
|
||||
| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення звіряють із ним отриманий артефакт. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого плагіна, коли конфігурація невалідна. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для налаштування завантажуватися під час запуску раніше, ніж повний плагін каналу. |
|
||||
| `openclaw.extensions` | Оголошує власні точки входу Plugin. Повинні залишатися всередині каталогу пакета Plugin. |
|
||||
| `openclaw.runtimeExtensions` | Оголошує точки входу built JavaScript runtime для встановлених пакетів. Повинні залишатися всередині каталогу пакета Plugin. |
|
||||
| `openclaw.setupEntry` | Легка точка входу лише для setup, яка використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Повинна залишатися всередині каталогу пакета Plugin. |
|
||||
| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript точку входу setup для встановлених пакетів. Повинна залишатися всередині каталогу пакета Plugin. |
|
||||
| `openclaw.channel` | Легкі метадані каталогу каналу, такі як мітки, шляхи до документації, псевдоніми та текст для вибору. |
|
||||
| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного runtime каналу. |
|
||||
| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже виконано вхід кудись?» без завантаження повного runtime каналу. |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих Plugin. |
|
||||
| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
|
||||
| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, із використанням нижньої межі semver, як-от `>=2026.3.22`. |
|
||||
| `openclaw.install.expectedIntegrity` | Очікуваний рядок npm dist integrity, наприклад `sha512-...`; потоки встановлення та оновлення звіряють із ним завантажений артефакт. |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого Plugin, коли конфігурація невалідна. |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. |
|
||||
|
||||
Метадані маніфесту визначають, які варіанти провайдера/каналу/налаштування з’являються в онбордингу до завантаження середовища виконання. `package.json#openclaw.install` повідомляє онбордингу, як отримати або ввімкнути цей плагін, коли користувач обирає один із цих варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`.
|
||||
Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в
|
||||
онбордингу до завантаження runtime. `package.json#openclaw.install` повідомляє
|
||||
онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих
|
||||
варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`.
|
||||
|
||||
`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають плагін на старіших хостах.
|
||||
`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження
|
||||
реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають
|
||||
Plugin на старіших хостах.
|
||||
|
||||
Точне закріплення версії npm вже міститься в `npmSpec`, наприклад `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Поєднуйте це з `expectedIntegrity`, якщо хочете, щоб потоки оновлення завершувалися в безпечному закритому стані, коли отриманий артефакт npm більше не відповідає закріпленому релізу. Інтерактивний онбординг пропонує варіанти встановлення npm лише з довірених метаданих каталогу, коли `npmSpec` є точною версією і присутній `expectedIntegrity`; інакше він повертається до локального джерела або пропуску.
|
||||
Точне закріплення версії npm уже живе в `npmSpec`, наприклад
|
||||
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Поєднуйте це з
|
||||
`expectedIntegrity`, якщо хочете, щоб потоки оновлення завершувалися закритою відмовою, коли завантажений
|
||||
артефакт npm більше не відповідає закріпленому релізу. Інтерактивний онбординг
|
||||
пропонує довірені npm-специфікації реєстру, зокрема прості назви пакетів і dist-tag. Коли
|
||||
`expectedIntegrity` присутній, потоки встановлення/оновлення застосовують його; коли його
|
||||
пропущено, дозвіл реєстру записується без закріплення цілісності.
|
||||
|
||||
Плагіни каналів повинні надавати `openclaw.setupEntry`, коли статус, список каналів або сканування SecretRef мають визначати налаштовані облікові записи без завантаження повного середовища виконання. Точка входу налаштування має надавати метадані каналу разом із безпечними для налаштування адаптерами конфігурації, статусу та секретів; мережеві клієнти, слухачі Gateway і середовища виконання транспорту слід залишати в основній точці входу розширення.
|
||||
Plugin каналу повинні надавати `openclaw.setupEntry`, коли статус, список каналів
|
||||
або сканування SecretRef мають визначати налаштовані облікові записи без завантаження повного
|
||||
runtime. Точка входу setup має надавати метадані каналу разом із безпечною для setup конфігурацією,
|
||||
статусом і адаптерами секретів; зберігайте мережеві клієнти, слухачі Gateway і
|
||||
transport runtime у головній точці входу extension.
|
||||
|
||||
Поля точок входу середовища виконання не скасовують перевірки меж пакета для полів вихідних точок входу. Наприклад, `openclaw.runtimeExtensions` не може зробити придатним до завантаження шлях `openclaw.extensions`, що виходить за межі.
|
||||
Поля точки входу runtime не перевизначають перевірки меж пакета для полів
|
||||
точки входу вихідного коду. Наприклад, `openclaw.runtimeExtensions` не може зробити
|
||||
завантажуваним шлях `openclaw.extensions`, що виходить за межі.
|
||||
|
||||
`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке застосування. Воно не робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам встановлення відновлюватися після певних застарілих збоїв оновлення вбудованого плагіна, наприклад відсутнього шляху до вбудованого плагіна або застарілого запису `channels.<id>` для того самого вбудованого плагіна. Не пов’язані помилки конфігурації й далі блокують встановлення та спрямовують операторів до `openclaw doctor --fix`.
|
||||
`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не
|
||||
робить довільні зламані конфігурації встановлюваними. Сьогодні він лише дозволяє потокам встановлення
|
||||
відновлюватися після певних застарілих збоїв оновлення вбудованого Plugin, таких як
|
||||
відсутній шлях до вбудованого Plugin або застарілий запис `channels.<id>` для того самого
|
||||
вбудованого Plugin. Непов’язані помилки конфігурації все одно блокують встановлення і спрямовують операторів
|
||||
до `openclaw doctor --fix`.
|
||||
|
||||
`openclaw.channel.persistedAuthState` — це метадані пакета для маленького модуля перевірки:
|
||||
`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля
|
||||
перевірки:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -548,9 +627,13 @@ OpenClaw застосовує такий пріоритет:
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте це, коли потоки налаштування, doctor або configured-state потребують недорогої перевірки автентифікації з відповіддю так/ні до завантаження повного плагіна каналу. Цільовий експорт має бути невеликою функцією, яка лише зчитує збережений стан; не маршрутизуйте її через повний barrel середовища виконання каналу.
|
||||
Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка
|
||||
автентифікації «так/ні» до завантаження повного Plugin каналу. Цільовий експорт має бути невеликою
|
||||
функцією, яка читає лише збережений стан; не спрямовуйте її через повний barrel runtime
|
||||
каналу.
|
||||
|
||||
`openclaw.channel.configuredState` має ту саму форму для недорогих перевірок налаштованого стану лише через env:
|
||||
`openclaw.channel.configuredState` використовує ту саму форму для дешевих перевірок
|
||||
налаштованого стану лише через env:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -566,62 +649,95 @@ OpenClaw застосовує такий пріоритет:
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте це, коли канал може визначити налаштований стан за env або іншими невеликими невиконуваними в середовищі виконання вхідними даними. Якщо перевірка потребує повного визначення конфігурації або реального середовища виконання каналу, залиште цю логіку в хуку плагіна `config.hasConfiguredState`.
|
||||
Використовуйте це, коли канал може відповідати про налаштований стан через env або інші малі
|
||||
входи, не пов’язані з runtime. Якщо перевірка потребує повного розв’язання конфігурації або справжнього
|
||||
runtime каналу, зберігайте цю логіку натомість у хуку Plugin `config.hasConfiguredState`.
|
||||
|
||||
## Пріоритет виявлення (дубльовані ідентифікатори плагінів)
|
||||
## Пріоритет виявлення (дублікати id Plugin)
|
||||
|
||||
OpenClaw виявляє плагіни з кількох коренів (вбудовані, глобальне встановлення, робочий простір, шляхи, явно вибрані в конфігурації). Якщо два виявлені плагіни мають однаковий `id`, зберігається лише маніфест **з найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним.
|
||||
OpenClaw виявляє Plugin з кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлення мають спільний `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч.
|
||||
|
||||
Пріоритет від найвищого до найнижчого:
|
||||
Пріоритет, від найвищого до найнижчого:
|
||||
|
||||
1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.<id>`
|
||||
2. **Вбудований** — плагіни, що постачаються з OpenClaw
|
||||
3. **Глобальне встановлення** — плагіни, встановлені в глобальний корінь плагінів OpenClaw
|
||||
4. **Робочий простір** — плагіни, виявлені відносно поточного робочого простору
|
||||
2. **Вбудований** — Plugin, що постачаються разом з OpenClaw
|
||||
3. **Глобальне встановлення** — Plugin, встановлені в глобальний корінь Plugin OpenClaw
|
||||
4. **Workspace** — Plugin, виявлені відносно поточного workspace
|
||||
|
||||
Наслідки:
|
||||
|
||||
- Форк або застаріла копія вбудованого плагіна, що лежить у робочому просторі, не перекриє вбудовану збірку.
|
||||
- Щоб справді перевизначити вбудований плагін локальним, закріпіть його через `plugins.entries.<id>`, щоб він переміг за пріоритетом, а не покладався на виявлення в робочому просторі.
|
||||
- Відкидання дублікатів записується в журнал, щоб Doctor і діагностика під час запуску могли вказати на відкинуту копію.
|
||||
- Розгалужена або застаріла копія вбудованого Plugin, що лежить у workspace, не затьмарить вбудовану збірку.
|
||||
- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.<id>`, щоб він переміг за пріоритетом, а не покладався на виявлення у workspace.
|
||||
- Відкидання дублікатів записується в журнал, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
|
||||
|
||||
## Вимоги до JSON Schema
|
||||
## Вимоги до схеми JSON
|
||||
|
||||
- **Кожен плагін повинен містити JSON Schema**, навіть якщо він не приймає конфігурації.
|
||||
- Порожня схема є припустимою (наприклад, `{ "type": "object", "additionalProperties": false }`).
|
||||
- **Кожен Plugin повинен постачати схему JSON**, навіть якщо він не приймає конфігурацію.
|
||||
- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
|
||||
- Схеми проходять валідацію під час читання/запису конфігурації, а не під час виконання.
|
||||
|
||||
## Поведінка валідації
|
||||
|
||||
- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено в маніфесті плагіна.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` повинні посилатися на **виявлювані** ідентифікатори плагінів. Невідомі ідентифікатори є **помилками**.
|
||||
- Якщо плагін встановлено, але він має зламаний або відсутній маніфест чи схему, валідація завершується помилкою, а Doctor повідомляє про помилку плагіна.
|
||||
- Якщо конфігурація плагіна існує, але сам плагін **вимкнено**, конфігурація зберігається, і в Doctor + журналах показується **попередження**.
|
||||
- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошено
|
||||
маніфестом Plugin.
|
||||
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` і `plugins.slots.*`
|
||||
повинні посилатися на id Plugin, які **можна виявити**. Невідомі id є **помилками**.
|
||||
- Якщо Plugin встановлено, але він має зламаний або відсутній маніфест чи схему,
|
||||
валідація завершується помилкою, а Doctor повідомляє про помилку Plugin.
|
||||
- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається і
|
||||
в Doctor + журналах показується **попередження**.
|
||||
|
||||
Повну схему `plugins.*` див. у [Довіднику з конфігурації](/uk/gateway/configuration).
|
||||
Повну схему `plugins.*` дивіться в [Довідник конфігурації](/uk/gateway/configuration).
|
||||
|
||||
## Примітки
|
||||
|
||||
- Маніфест **є обов’язковим для власних плагінів OpenClaw**, включно із завантаженням із локальної файлової системи.
|
||||
- Середовище виконання все одно окремо завантажує модуль плагіна; маніфест використовується лише для виявлення + валідації.
|
||||
- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок допускаються, якщо підсумкове значення все ще є об’єктом.
|
||||
- Завантажувач маніфесту зчитує лише задокументовані поля маніфесту. Уникайте додавання сюди власних ключів верхнього рівня.
|
||||
- `providerAuthEnvVars` — це недорогий шлях метаданих для перевірок автентифікації, валідації маркерів env та подібних поверхонь автентифікації провайдера, які не повинні запускати середовище виконання плагіна лише для перевірки назв env.
|
||||
- `providerAuthAliases` дозволяє варіантам провайдера повторно використовувати env vars автентифікації, профілі автентифікації, автентифікацію на основі конфігурації та варіант онбордингу API-ключа іншого провайдера без жорсткого кодування цього зв’язку в ядрі.
|
||||
- `providerEndpoints` дозволяє плагінам провайдерів володіти простими метаданими зіставлення хоста кінцевої точки/`baseUrl`. Використовуйте це лише для класів кінцевих точок, які ядро вже підтримує; поведінка середовища виконання, як і раніше, належить плагіну.
|
||||
- `syntheticAuthRefs` — це недорогий шлях метаданих для синтетичних хуків автентифікації, що належать провайдеру й мають бути видимими для холодного виявлення моделей до появи реєстру середовища виконання. Вказуйте лише ті посилання, чий провайдер середовища виконання або backend CLI справді реалізує `resolveSyntheticAuth`.
|
||||
- `nonSecretAuthMarkers` — це недорогий шлях метаданих для значень-заповнювачів API-ключів, що належать вбудованому плагіну, наприклад локальних маркерів, OAuth або маркерів ambient credential. Ядро трактує їх як не секретні для відображення автентифікації та аудиту секретів без жорсткого кодування провайдера-власника.
|
||||
- `channelEnvVars` — це недорогий шлях метаданих для резервного використання env оболонки, запитів налаштування та подібних поверхонь каналу, які не повинні запускати середовище виконання плагіна лише для перевірки назв env. Імена env є метаданими, а не активацією самі по собі: статус, аудит, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до плагіна й ефективної активації, перш ніж вважати env var налаштованим каналом.
|
||||
- `providerAuthChoices` — це недорогий шлях метаданих для засобів вибору варіантів автентифікації, визначення `--auth-choice`, зіставлення пріоритетного провайдера та простої реєстрації CLI flags онбордингу до завантаження середовища виконання провайдера. Метадані wizard середовища виконання, для яких потрібен код провайдера, див. у [Хуках середовища виконання провайдера](/uk/plugins/architecture#provider-runtime-hooks).
|
||||
- Ексклюзивні типи плагінів вибираються через `plugins.slots.*`.
|
||||
- Маніфест **обов’язковий для власних Plugin OpenClaw**, зокрема для локальних завантажень із файлової системи.
|
||||
- Runtime усе одно завантажує модуль Plugin окремо; маніфест використовується лише для
|
||||
виявлення + валідації.
|
||||
- Власні маніфести розбираються через JSON5, тому коментарі, кінцеві коми та
|
||||
ключі без лапок приймаються, якщо фінальне значення все ще є об’єктом.
|
||||
- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання
|
||||
тут власних ключів верхнього рівня.
|
||||
- `providerAuthEnvVars` — це шлях дешевих метаданих для перевірок автентифікації, валідації
|
||||
env-marker та подібних поверхонь автентифікації провайдера, які не повинні запускати runtime Plugin
|
||||
лише для перевірки імен env.
|
||||
- `providerAuthAliases` дозволяє варіантам провайдера повторно використовувати env vars
|
||||
автентифікації, профілі автентифікації, автентифікацію на основі конфігурації та варіант
|
||||
онбордингу з API-ключем іншого провайдера без жорсткого кодування цього зв’язку в ядрі.
|
||||
- `providerEndpoints` дозволяє Plugin провайдера володіти простими метаданими
|
||||
зіставлення хостів/`baseUrl` кінцевих точок. Використовуйте це лише для класів кінцевих точок, які ядро вже підтримує;
|
||||
поведінкою runtime як і раніше володіє Plugin.
|
||||
- `syntheticAuthRefs` — це шлях дешевих метаданих для синтетичних
|
||||
хуків автентифікації, що належать провайдеру, які мають бути видимими для холодного виявлення моделей до того, як реєстр
|
||||
runtime почне існувати. Вказуйте лише посилання, чий runtime-провайдер або backend CLI справді
|
||||
реалізує `resolveSyntheticAuth`.
|
||||
- `nonSecretAuthMarkers` — це шлях дешевих метаданих для значень-заповнювачів API-ключів,
|
||||
що належать вбудованому Plugin, таких як локальні маркери, OAuth або ambient credential.
|
||||
Ядро розглядає їх як несекретні для відображення автентифікації та аудитів секретів без
|
||||
жорсткого кодування провайдера-власника.
|
||||
- `channelEnvVars` — це шлях дешевих метаданих для резервного використання shell-env, підказок setup
|
||||
та подібних поверхонь каналів, які не повинні запускати runtime Plugin
|
||||
лише для перевірки імен env. Імена env — це метадані, а не активація самі по
|
||||
собі: статус, аудит, перевірка доставки Cron та інші поверхні лише для читання все одно
|
||||
застосовують довіру до Plugin і політику ефективної активації, перш ніж
|
||||
розглядати env var як налаштований канал.
|
||||
- `providerAuthChoices` — це шлях дешевих метаданих для селекторів варіантів автентифікації,
|
||||
розв’язання `--auth-choice`, зіставлення пріоритетного провайдера та простої
|
||||
реєстрації прапорців CLI онбордингу до завантаження runtime провайдера. Для метаданих
|
||||
wizard runtime, які потребують коду провайдера, див.
|
||||
[Хуки runtime провайдера](/uk/plugins/architecture#provider-runtime-hooks).
|
||||
- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`.
|
||||
- `kind: "memory"` вибирається через `plugins.slots.memory`.
|
||||
- `kind: "context-engine"` вибирається через `plugins.slots.contextEngine` (типово: вбудований `legacy`).
|
||||
- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо плагіну вони не потрібні.
|
||||
- Якщо ваш плагін залежить від native modules, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts`
|
||||
- `kind: "context-engine"` вибирається через `plugins.slots.contextEngine`
|
||||
(типово: вбудований `legacy`).
|
||||
- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, коли
|
||||
Plugin їх не потребує.
|
||||
- Якщо ваш Plugin залежить від власних модулів, задокументуйте кроки збірки та всі
|
||||
вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts`
|
||||
- `pnpm rebuild <package>`).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з плагінами
|
||||
- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з Plugins
|
||||
- [Архітектура Plugin](/uk/plugins/architecture) — внутрішня архітектура
|
||||
- [Огляд SDK](/uk/plugins/sdk-overview) — довідник SDK Plugin
|
||||
|
||||
@ -1,27 +1,27 @@
|
||||
---
|
||||
read_when:
|
||||
- Ви додаєте майстер налаштування до Plugin
|
||||
- Вам потрібно зрозуміти різницю між `setup-entry.ts` та `index.ts`
|
||||
- Ви визначаєте схеми конфігурації plugin або метадані `openclaw` у `package.json`
|
||||
- Вам потрібно зрозуміти різницю між setup-entry.ts і index.ts
|
||||
- Ви визначаєте схеми конфігурації plugin або метадані openclaw у package.json
|
||||
sidebarTitle: Setup and Config
|
||||
summary: Майстри налаштування, `setup-entry.ts`, схеми конфігурації та метадані `package.json`
|
||||
title: Налаштування Plugin та конфігурація
|
||||
summary: Майстри налаштування, setup-entry.ts, схеми конфігурації та метадані package.json
|
||||
title: Налаштування Plugin і конфігурація
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T05:16:42Z"
|
||||
generated_at: "2026-04-23T07:42:05Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: ccdafb9a562353a7851fcd47bbc382961a449f5d645362c800f64c60579ce7b2
|
||||
source_hash: 110cf9aa1bfaeb286d38963cfba2006502e853dd603a126d1c179cbc9b60aea1
|
||||
source_path: plugins/sdk-setup.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Налаштування Plugin та конфігурація
|
||||
# Налаштування Plugin і конфігурація
|
||||
|
||||
Довідник щодо пакування plugin (`package.json` metadata), маніфестів
|
||||
(`openclaw.plugin.json`), записів налаштування та схем конфігурації.
|
||||
Довідник із пакування plugin (`package.json` метадані), маніфестів
|
||||
(`openclaw.plugin.json`), точок входу налаштування та схем конфігурації.
|
||||
|
||||
<Tip>
|
||||
**Шукаєте покроковий посібник?** Практичні інструкції охоплюють пакування в контексті:
|
||||
**Шукаєте покроковий приклад?** Покрокові інструкції описують пакування в контексті:
|
||||
[Channel Plugins](/uk/plugins/sdk-channel-plugins#step-1-package-and-manifest) і
|
||||
[Provider Plugins](/uk/plugins/sdk-provider-plugins#step-1-package-and-manifest).
|
||||
</Tip>
|
||||
@ -50,7 +50,7 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
**Provider plugin / базовий варіант публікації в ClawHub:**
|
||||
**Provider plugin / базовий варіант публікації ClawHub:**
|
||||
|
||||
```json openclaw-clawhub-package.json
|
||||
{
|
||||
@ -71,47 +71,47 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Якщо ви публікуєте plugin зовні в ClawHub, поля `compat` і `build`
|
||||
є обов’язковими. Канонічні фрагменти для публікації знаходяться в
|
||||
Якщо ви публікуєте plugin зовнішньо в ClawHub, ці поля `compat` і `build`
|
||||
є обов’язковими. Канонічні фрагменти для публікації розміщені в
|
||||
`docs/snippets/plugin-publish/`.
|
||||
|
||||
### Поля `openclaw`
|
||||
|
||||
| Поле | Тип | Опис |
|
||||
| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `extensions` | `string[]` | Файли точок входу (відносно кореня пакета) |
|
||||
| `setupEntry` | `string` | Полегшений запис лише для налаштування (необов’язково) |
|
||||
| `channel` | `object` | Метадані каталогу каналів для налаштування, вибору, швидкого старту та поверхонь статусу |
|
||||
| `providers` | `string[]` | Ідентифікатори провайдерів, зареєстровані цим plugin |
|
||||
| `install` | `object` | Підказки для встановлення: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `expectedIntegrity`, `allowInvalidConfigRecovery` |
|
||||
| `startup` | `object` | Прапорці поведінки під час запуску |
|
||||
| Поле | Тип | Опис |
|
||||
| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `extensions` | `string[]` | Файли точок входу (відносно кореня пакета) |
|
||||
| `setupEntry` | `string` | Полегшена точка входу лише для налаштування (необов’язково) |
|
||||
| `channel` | `object` | Метадані каталогу channel для налаштування, вибору, швидкого старту та поверхонь статусу |
|
||||
| `providers` | `string[]` | Ідентифікатори provider, зареєстрованих цим plugin |
|
||||
| `install` | `object` | Підказки встановлення: `npmSpec`, `localPath`, `defaultChoice`, `minHostVersion`, `expectedIntegrity`, `allowInvalidConfigRecovery` |
|
||||
| `startup` | `object` | Прапорці поведінки під час запуску |
|
||||
|
||||
### `openclaw.channel`
|
||||
|
||||
`openclaw.channel` — це недорогі метадані пакета для виявлення каналів і
|
||||
поверхонь налаштування до завантаження runtime.
|
||||
`openclaw.channel` — це недорогі метадані пакета для виявлення channel і поверхонь
|
||||
налаштування до завантаження runtime.
|
||||
|
||||
| Поле | Тип | Що це означає |
|
||||
| -------------------------------------- | ---------- | --------------------------------------------------------------------------- |
|
||||
| `id` | `string` | Канонічний ідентифікатор каналу. |
|
||||
| `label` | `string` | Основна назва каналу. |
|
||||
| `selectionLabel` | `string` | Назва у виборі/налаштуванні, якщо вона має відрізнятися від `label`. |
|
||||
| `detailLabel` | `string` | Додаткова детальна назва для багатших каталогів каналів і поверхонь статусу. |
|
||||
| `docsPath` | `string` | Шлях до документації для посилань у налаштуванні та виборі. |
|
||||
| `docsLabel` | `string` | Назва для посилань на документацію, якщо вона має відрізнятися від ідентифікатора каналу. |
|
||||
| `id` | `string` | Канонічний ідентифікатор channel. |
|
||||
| `label` | `string` | Основний ярлик channel. |
|
||||
| `selectionLabel` | `string` | Ярлик у засобі вибору/налаштування, якщо він має відрізнятися від `label`. |
|
||||
| `detailLabel` | `string` | Вторинний ярлик деталей для багатших каталогів channel і поверхонь статусу. |
|
||||
| `docsPath` | `string` | Шлях до документації для посилань із налаштування та вибору. |
|
||||
| `docsLabel` | `string` | Ярлик для посилань на документацію, якщо він має відрізнятися від id channel. |
|
||||
| `blurb` | `string` | Короткий опис для онбордингу/каталогу. |
|
||||
| `order` | `number` | Порядок сортування в каталогах каналів. |
|
||||
| `aliases` | `string[]` | Додаткові псевдоніми для пошуку каналу. |
|
||||
| `preferOver` | `string[]` | Ідентифікатори plugin/каналів із нижчим пріоритетом, які цей канал має випереджати. |
|
||||
| `systemImage` | `string` | Необов’язкова назва піктограми/system-image для каталогів UI каналу. |
|
||||
| `selectionDocsPrefix` | `string` | Текст-префікс перед посиланнями на документацію в поверхнях вибору. |
|
||||
| `selectionDocsOmitLabel` | `boolean` | Показувати шлях до документації безпосередньо замість підписаного посилання в тексті вибору. |
|
||||
| `selectionExtras` | `string[]` | Додаткові короткі рядки, що додаються в тексті вибору. |
|
||||
| `markdownCapable` | `boolean` | Позначає канал як сумісний із markdown для рішень щодо вихідного форматування. |
|
||||
| `exposure` | `object` | Керування видимістю каналу для налаштування, списків налаштованих елементів і поверхонь документації. |
|
||||
| `quickstartAllowFrom` | `boolean` | Вмикає цей канал у стандартний потік налаштування quickstart `allowFrom`. |
|
||||
| `forceAccountBinding` | `boolean` | Вимагає явної прив’язки облікового запису, навіть коли існує лише один обліковий запис. |
|
||||
| `preferSessionLookupForAnnounceTarget` | `boolean` | Надає перевагу пошуку сесії під час визначення цілей оголошення для цього каналу. |
|
||||
| `order` | `number` | Порядок сортування в каталогах channel. |
|
||||
| `aliases` | `string[]` | Додаткові псевдоніми для пошуку під час вибору channel. |
|
||||
| `preferOver` | `string[]` | Ідентифікатори plugin/channel з нижчим пріоритетом, які цей channel має випереджати. |
|
||||
| `systemImage` | `string` | Необов’язкова назва піктограми/system-image для каталогів UI channel. |
|
||||
| `selectionDocsPrefix` | `string` | Префіксний текст перед посиланнями на документацію в поверхнях вибору. |
|
||||
| `selectionDocsOmitLabel` | `boolean` | Показувати шлях документації напряму замість підписаного посилання в тексті вибору. |
|
||||
| `selectionExtras` | `string[]` | Додаткові короткі рядки, додані до тексту вибору. |
|
||||
| `markdownCapable` | `boolean` | Позначає channel як такий, що підтримує markdown, для рішень щодо вихідного форматування. |
|
||||
| `exposure` | `object` | Керування видимістю channel для налаштування, списків налаштованих елементів і поверхонь документації. |
|
||||
| `quickstartAllowFrom` | `boolean` | Додає цей channel до стандартного потоку швидкого старту `allowFrom`. |
|
||||
| `forceAccountBinding` | `boolean` | Вимагає явного прив’язування облікового запису, навіть якщо існує лише один обліковий запис. |
|
||||
| `preferSessionLookupForAnnounceTarget` | `boolean` | Надає перевагу пошуку session під час визначення announce target для цього channel. |
|
||||
|
||||
Приклад:
|
||||
|
||||
@ -145,41 +145,40 @@ x-i18n:
|
||||
|
||||
`exposure` підтримує:
|
||||
|
||||
- `configured`: включати канал до поверхонь переліку налаштованих елементів/статусу
|
||||
- `setup`: включати канал до інтерактивних засобів вибору налаштування/конфігурації
|
||||
- `docs`: позначати канал як публічно видимий у поверхнях документації/навігації
|
||||
- `configured`: включати channel до поверхонь списків налаштованих елементів/стану
|
||||
- `setup`: включати channel до інтерактивних засобів вибору налаштування/конфігурації
|
||||
- `docs`: позначати channel як публічно видимий на поверхнях документації/навігації
|
||||
|
||||
`showConfigured` і `showInSetup` усе ще підтримуються як застарілі псевдоніми. Надавайте перевагу
|
||||
`showConfigured` і `showInSetup` залишаються підтримуваними як застарілі псевдоніми. Надавайте перевагу
|
||||
`exposure`.
|
||||
|
||||
### `openclaw.install`
|
||||
|
||||
`openclaw.install` — це метадані пакета, а не метадані маніфесту.
|
||||
|
||||
| Поле | Тип | Що це означає |
|
||||
| ---------------------------- | -------------------- | ------------------------------------------------------------------------------ |
|
||||
| `npmSpec` | `string` | Канонічний npm spec для потоків встановлення/оновлення. |
|
||||
| `localPath` | `string` | Локальний шлях встановлення для розробки або вбудованого plugin. |
|
||||
| `defaultChoice` | `"npm"` \| `"local"` | Бажане джерело встановлення, коли доступні обидва варіанти. |
|
||||
| `minHostVersion` | `string` | Мінімальна підтримувана версія OpenClaw у формі `>=x.y.z`. |
|
||||
| `expectedIntegrity` | `string` | Очікуваний рядок цілісності npm dist, зазвичай `sha512-...`, для фіксованих встановлень. |
|
||||
| `allowInvalidConfigRecovery` | `boolean` | Дозволяє потокам перевстановлення вбудованих plugin відновлюватися після окремих збоїв через застарілу конфігурацію. |
|
||||
| Поле | Тип | Що це означає |
|
||||
| ---------------------------- | -------------------- | -------------------------------------------------------------------------------- |
|
||||
| `npmSpec` | `string` | Канонічна специфікація npm для потоків встановлення/оновлення. |
|
||||
| `localPath` | `string` | Локальний шлях для розробки або вбудованого встановлення. |
|
||||
| `defaultChoice` | `"npm"` \| `"local"` | Бажане джерело встановлення, коли доступні обидва варіанти. |
|
||||
| `minHostVersion` | `string` | Мінімально підтримувана версія OpenClaw у формі `>=x.y.z`. |
|
||||
| `expectedIntegrity` | `string` | Очікуваний рядок цілісності npm dist, зазвичай `sha512-...`, для зафіксованих встановлень. |
|
||||
| `allowInvalidConfigRecovery` | `boolean` | Дозволяє потокам перевстановлення вбудованих plugin відновлюватися після певних збоїв застарілої конфігурації. |
|
||||
|
||||
Інтерактивний онбординг також використовує `openclaw.install` для поверхонь
|
||||
встановлення на вимогу. Якщо ваш plugin показує варіанти авторизації провайдера або
|
||||
метадані налаштування/каталогу каналу до завантаження runtime,
|
||||
онбординг може показати цей вибір, запропонувати npm чи локальне встановлення,
|
||||
встановити або ввімкнути plugin, а потім продовжити вибраний
|
||||
потік. Варіанти онбордингу через npm вимагають довірених метаданих каталогу з точним
|
||||
значенням `npmSpec` версії та `expectedIntegrity`; нефіксовані назви пакетів і dist-tags
|
||||
не пропонуються для автоматичного встановлення під час онбордингу. Зберігайте метадані
|
||||
«що показувати» в `openclaw.plugin.json`, а метадані «як це встановити» — у
|
||||
`package.json`.
|
||||
встановлення на вимогу. Якщо ваш plugin надає варіанти автентифікації provider або метадані
|
||||
налаштування/каталогу channel до завантаження runtime, онбординг може показати цей вибір,
|
||||
запропонувати npm чи локальне встановлення, встановити або ввімкнути plugin, а потім продовжити вибраний
|
||||
потік. Варіанти онбордингу npm потребують довірених метаданих каталогу з реєстровим
|
||||
`npmSpec`; точні версії та `expectedIntegrity` — необов’язкові фіксації. Якщо
|
||||
`expectedIntegrity` присутній, потоки встановлення/оновлення примусово перевіряють його. Зберігайте метадані «що
|
||||
показувати» в `openclaw.plugin.json`, а метадані «як це встановити» —
|
||||
у `package.json`.
|
||||
|
||||
Якщо задано `minHostVersion`, і встановлення, і завантаження реєстру маніфестів
|
||||
застосовують цю вимогу. Старіші хости пропускають plugin; недійсні рядки версій відхиляються.
|
||||
примусово застосовують його. Старіші host пропускають plugin; некоректні рядки версій відхиляються.
|
||||
|
||||
Для фіксованих npm-встановлень зберігайте точну версію в `npmSpec` і додавайте
|
||||
Для зафіксованих npm-встановлень зберігайте точну версію в `npmSpec` і додавайте
|
||||
очікувану цілісність артефакту:
|
||||
|
||||
```json
|
||||
@ -194,11 +193,11 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
`allowInvalidConfigRecovery` не є загальним обходом для зламаних конфігурацій. Це
|
||||
призначено лише для вузьких сценаріїв відновлення вбудованих plugin, щоб перевстановлення/налаштування
|
||||
могло виправити відомі залишки після оновлення, як-от відсутній шлях до вбудованого plugin або застарілий запис `channels.<id>`
|
||||
`allowInvalidConfigRecovery` не є загальним обхідним шляхом для зламаних конфігурацій. Воно призначене
|
||||
лише для вузького відновлення вбудованих plugin, щоб перевстановлення/налаштування могли виправити відомі
|
||||
залишки після оновлення, як-от відсутній шлях до вбудованого plugin або застарілий запис `channels.<id>`
|
||||
для цього самого plugin. Якщо конфігурація зламана з не пов’язаних причин, встановлення
|
||||
усе одно завершується безпечною відмовою та повідомляє оператору виконати `openclaw doctor --fix`.
|
||||
усе одно завершується з відмовою та повідомляє оператору запустити `openclaw doctor --fix`.
|
||||
|
||||
### Відкладене повне завантаження
|
||||
|
||||
@ -216,26 +215,25 @@ Channel plugins можуть увімкнути відкладене заван
|
||||
}
|
||||
```
|
||||
|
||||
Коли цю опцію ввімкнено, OpenClaw завантажує лише `setupEntry` на фазі запуску
|
||||
до початку прослуховування, навіть для вже налаштованих каналів. Повний запис завантажується після того,
|
||||
як Gateway починає прослуховування.
|
||||
Коли це ввімкнено, OpenClaw завантажує лише `setupEntry` під час фази запуску до початку прослуховування,
|
||||
навіть для вже налаштованих channel. Повна точка входу завантажується після того, як Gateway починає прослуховування.
|
||||
|
||||
<Warning>
|
||||
Вмикайте відкладене завантаження лише тоді, коли ваш `setupEntry` реєструє все,
|
||||
що потрібно Gateway до початку прослуховування (реєстрація каналу, HTTP-маршрути,
|
||||
методи Gateway). Якщо повний запис володіє необхідними можливостями запуску, зберігайте
|
||||
стандартну поведінку.
|
||||
Увімкнюйте відкладене завантаження лише тоді, коли ваш `setupEntry` реєструє все, що
|
||||
потрібно Gateway до початку прослуховування (реєстрація channel, HTTP-маршрути, методи
|
||||
Gateway). Якщо повна точка входу володіє потрібними можливостями запуску, зберігайте
|
||||
поведінку за замовчуванням.
|
||||
</Warning>
|
||||
|
||||
Якщо ваш запис налаштування/повний запис реєструє RPC-методи Gateway, залишайте їх на
|
||||
префіксі, специфічному для plugin. Зарезервовані простори назв адміністратора ядра (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються під контролем ядра й завжди зіставляються
|
||||
Якщо ваша точка входу налаштування/повна точка входу реєструє методи Gateway RPC, зберігайте їх
|
||||
на префіксі, специфічному для plugin. Зарезервовані простори імен базового адміністратора (`config.*`,
|
||||
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються у володінні core і завжди зіставляються
|
||||
з `operator.admin`.
|
||||
|
||||
## Маніфест plugin
|
||||
|
||||
Кожен native plugin має постачати `openclaw.plugin.json` у корені пакета.
|
||||
OpenClaw використовує його для валідації конфігурації без виконання коду plugin.
|
||||
Кожен нативний plugin має постачатися з `openclaw.plugin.json` у корені пакета.
|
||||
OpenClaw використовує його для перевірки конфігурації без виконання коду plugin.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -270,7 +268,7 @@ OpenClaw використовує його для валідації конфі
|
||||
}
|
||||
```
|
||||
|
||||
Навіть plugins без конфігурації мають постачати схему. Порожня схема є валідною:
|
||||
Навіть plugins без конфігурації мають постачатися зі схемою. Порожня схема є допустимою:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -282,25 +280,25 @@ OpenClaw використовує його для валідації конфі
|
||||
}
|
||||
```
|
||||
|
||||
Див. [Plugin Manifest](/uk/plugins/manifest), щоб ознайомитися з повним довідником щодо схеми.
|
||||
Див. [Plugin Manifest](/uk/plugins/manifest) для повного довідника зі схеми.
|
||||
|
||||
## Публікація в ClawHub
|
||||
|
||||
Для пакетів plugin використовуйте команду ClawHub, призначену саме для пакетів:
|
||||
Для пакетів plugin використовуйте команду ClawHub, специфічну для пакетів:
|
||||
|
||||
```bash
|
||||
clawhub package publish your-org/your-plugin --dry-run
|
||||
clawhub package publish your-org/your-plugin
|
||||
```
|
||||
|
||||
Застарілий псевдонім публікації лише для skills призначений для Skills. Пакети plugin
|
||||
Застарілий псевдонім публікації лише для Skills призначений для Skills. Пакети plugin
|
||||
завжди мають використовувати `clawhub package publish`.
|
||||
|
||||
## Запис налаштування
|
||||
## Точка входу налаштування
|
||||
|
||||
Файл `setup-entry.ts` — це полегшена альтернатива `index.ts`, яку
|
||||
OpenClaw завантажує, коли йому потрібні лише поверхні налаштування (онбординг, відновлення конфігурації,
|
||||
перевірка вимкнених каналів).
|
||||
перевірка вимкнених channel).
|
||||
|
||||
```typescript
|
||||
// setup-entry.ts
|
||||
@ -310,19 +308,19 @@ import { myChannelPlugin } from "./src/channel.js";
|
||||
export default defineSetupPluginEntry(myChannelPlugin);
|
||||
```
|
||||
|
||||
Це дає змогу уникнути завантаження важкого runtime-коду (криптобібліотек, CLI-реєстрацій,
|
||||
Це дає змогу уникнути завантаження важкого runtime-коду (криптобібліотек, реєстрацій CLI,
|
||||
фонових сервісів) під час потоків налаштування.
|
||||
|
||||
Вбудовані workspace-канали, які тримають безпечні для налаштування експорти в sidecar-модулях, можуть
|
||||
Вбудовані workspace channel, які зберігають безпечні для налаштування експорти в sidecar-модулях, можуть
|
||||
використовувати `defineBundledChannelSetupEntry(...)` з
|
||||
`openclaw/plugin-sdk/channel-entry-contract` замість
|
||||
`defineSetupPluginEntry(...)`. Цей вбудований контракт також підтримує необов’язковий
|
||||
експорт `runtime`, щоб wiring runtime під час налаштування залишався легким і явним.
|
||||
експорт `runtime`, тож прив’язування runtime під час налаштування може залишатися легким і явним.
|
||||
|
||||
**Коли OpenClaw використовує `setupEntry` замість повного запису:**
|
||||
**Коли OpenClaw використовує `setupEntry` замість повної точки входу:**
|
||||
|
||||
- Канал вимкнено, але потрібні поверхні налаштування/онбордингу
|
||||
- Канал увімкнено, але не налаштовано
|
||||
- Channel вимкнений, але потребує поверхонь налаштування/онбордингу
|
||||
- Channel увімкнений, але не налаштований
|
||||
- Увімкнено відкладене завантаження (`deferConfiguredChannelFullLoadUntilAfterListen`)
|
||||
|
||||
**Що має реєструвати `setupEntry`:**
|
||||
@ -331,60 +329,59 @@ export default defineSetupPluginEntry(myChannelPlugin);
|
||||
- Будь-які HTTP-маршрути, потрібні до початку прослуховування Gateway
|
||||
- Будь-які методи Gateway, потрібні під час запуску
|
||||
|
||||
Ці методи Gateway для запуску все одно мають уникати зарезервованих просторів
|
||||
назв адміністратора ядра, таких як `config.*` або `update.*`.
|
||||
Ці методи Gateway для запуску все одно мають уникати зарезервованих просторів імен
|
||||
базового адміністратора, таких як `config.*` або `update.*`.
|
||||
|
||||
**Що НЕ має містити `setupEntry`:**
|
||||
**Що НЕ має включати `setupEntry`:**
|
||||
|
||||
- CLI-реєстрації
|
||||
- Реєстрації CLI
|
||||
- Фонові сервіси
|
||||
- Важкі runtime-імпорти (crypto, SDK)
|
||||
- Методи Gateway, потрібні лише після запуску
|
||||
|
||||
### Вузькі імпорти допоміжних засобів налаштування
|
||||
|
||||
Для гарячих шляхів лише налаштування надавайте перевагу вузьким seam-допоміжним засобам налаштування замість ширшого
|
||||
парасолькового `plugin-sdk/setup`, коли вам потрібна лише частина поверхні налаштування:
|
||||
Для гарячих шляхів лише налаштування надавайте перевагу вузьким швам допоміжних засобів налаштування замість ширшого
|
||||
узагальненого `plugin-sdk/setup`, коли вам потрібна лише частина поверхні налаштування:
|
||||
|
||||
| Шлях імпорту | Використовуйте для | Ключові експорти |
|
||||
| ---------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/setup-runtime` | допоміжні runtime-засоби для часу налаштування, які лишаються доступними в `setupEntry` / під час відкладеного запуску каналу | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | адаптери налаштування облікових записів із урахуванням середовища | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | допоміжні CLI/archive/docs-засоби для налаштування/встановлення | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| Шлях імпорту | Для чого використовувати | Ключові експорти |
|
||||
| --------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `plugin-sdk/setup-runtime` | допоміжні засоби runtime під час налаштування, які лишаються доступними в `setupEntry` / відкладеному запуску channel | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
|
||||
| `plugin-sdk/setup-adapter-runtime` | адаптери налаштування облікових записів з урахуванням середовища | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | допоміжні засоби налаштування/встановлення CLI/архівів/документації | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
|
||||
Використовуйте ширший seam `plugin-sdk/setup`, коли вам потрібен повний спільний
|
||||
набір інструментів налаштування, включно з допоміжними засобами для латання конфігурації, такими як
|
||||
Використовуйте ширший шов `plugin-sdk/setup`, коли вам потрібен повний спільний
|
||||
набір інструментів налаштування, включно з допоміжними засобами patch-конфігурації, такими як
|
||||
`moveSingleAccountChannelSectionToDefaultAccount(...)`.
|
||||
|
||||
Адаптери латання налаштування лишаються безпечними для імпорту на гарячому шляху. Їхній вбудований
|
||||
відкладений пошук поверхні контракту просування одного облікового запису є lazy, тому імпорт
|
||||
`plugin-sdk/setup-runtime` не виконує завчасне завантаження виявлення поверхні вбудованого контракту до того, як адаптер фактично буде використано.
|
||||
Адаптери patch для налаштування залишаються безпечними для гарячого шляху під час імпорту. Їхній вбудований
|
||||
ледачий пошук поверхні контракту для просування single-account, тож імпорт
|
||||
`plugin-sdk/setup-runtime` не завантажує передчасно виявлення поверхні вбудованого контракту до того, як адаптер справді буде використано.
|
||||
|
||||
### Просування одного облікового запису, кероване каналом
|
||||
### Просування single-account, що належить channel
|
||||
|
||||
Коли канал оновлюється з верхньорівневої конфігурації одного облікового запису до
|
||||
`channels.<id>.accounts.*`, типовою спільною поведінкою є переміщення значень
|
||||
області облікового запису, що просуваються, у `accounts.default`.
|
||||
Коли channel оновлюється з однокористувацької конфігурації верхнього рівня до
|
||||
`channels.<id>.accounts.*`, типова спільна поведінка полягає в тому, щоб перемістити просунуті
|
||||
значення з областю облікового запису в `accounts.default`.
|
||||
|
||||
Вбудовані канали можуть звузити або перевизначити це просування через свою поверхню
|
||||
контракту налаштування:
|
||||
Вбудовані channel можуть звузити або перевизначити це просування через свою поверхню контракту налаштування:
|
||||
|
||||
- `singleAccountKeysToMove`: додаткові ключі верхнього рівня, які слід перемістити до
|
||||
просунутого облікового запису
|
||||
- `namedAccountPromotionKeys`: якщо іменовані облікові записи вже існують, лише ці
|
||||
ключі переміщуються до просунутого облікового запису; спільні ключі policy/delivery залишаються в корені
|
||||
каналу
|
||||
- `resolveSingleAccountPromotionTarget(...)`: вибір наявного облікового запису,
|
||||
який отримає просунуті значення
|
||||
- `singleAccountKeysToMove`: додаткові ключі верхнього рівня, які слід перемістити в
|
||||
просунутий обліковий запис
|
||||
- `namedAccountPromotionKeys`: коли іменовані облікові записи вже існують, лише ці
|
||||
ключі переміщуються в просунутий обліковий запис; спільні ключі policy/delivery залишаються в корені
|
||||
channel
|
||||
- `resolveSingleAccountPromotionTarget(...)`: вибирає, який наявний обліковий запис
|
||||
отримає просунуті значення
|
||||
|
||||
Matrix є поточним вбудованим прикладом. Якщо вже існує рівно один іменований обліковий запис Matrix,
|
||||
або якщо `defaultAccount` вказує на наявний неканонічний ключ, наприклад
|
||||
`Ops`, просування зберігає цей обліковий запис замість створення нового запису
|
||||
Matrix — поточний вбудований приклад. Якщо вже існує рівно один іменований обліковий запис Matrix,
|
||||
або якщо `defaultAccount` вказує на наявний неканонічний ключ, такий як `Ops`,
|
||||
просування зберігає цей обліковий запис замість створення нового запису
|
||||
`accounts.default`.
|
||||
|
||||
## Схема конфігурації
|
||||
|
||||
Конфігурація plugin проходить валідацію за JSON Schema у вашому маніфесті. Користувачі
|
||||
Конфігурація Plugin перевіряється за JSON Schema у вашому маніфесті. Користувачі
|
||||
налаштовують plugins через:
|
||||
|
||||
```json5
|
||||
@ -401,9 +398,9 @@ Matrix є поточним вбудованим прикладом. Якщо в
|
||||
}
|
||||
```
|
||||
|
||||
Під час реєстрації ваш plugin отримує цю конфігурацію як `api.pluginConfig`.
|
||||
Ваш plugin отримує цю конфігурацію як `api.pluginConfig` під час реєстрації.
|
||||
|
||||
Для конфігурації, специфічної для каналу, використовуйте натомість розділ конфігурації каналу:
|
||||
Для конфігурації, специфічної для channel, використовуйте натомість розділ конфігурації channel:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -416,10 +413,10 @@ Matrix є поточним вбудованим прикладом. Якщо в
|
||||
}
|
||||
```
|
||||
|
||||
### Побудова схем конфігурації каналу
|
||||
### Побудова схем конфігурації channel
|
||||
|
||||
Використовуйте `buildChannelConfigSchema` з `openclaw/plugin-sdk/core`, щоб перетворити
|
||||
схему Zod на обгортку `ChannelConfigSchema`, яку OpenClaw валідує:
|
||||
схему Zod на обгортку `ChannelConfigSchema`, яку перевіряє OpenClaw:
|
||||
|
||||
```typescript
|
||||
import { z } from "zod";
|
||||
@ -472,19 +469,19 @@ const setupWizard: ChannelSetupWizard = {
|
||||
```
|
||||
|
||||
Тип `ChannelSetupWizard` підтримує `credentials`, `textInputs`,
|
||||
`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` та інші можливості.
|
||||
Див. пакети вбудованих plugin (наприклад, plugin Discord `src/channel.setup.ts`), щоб ознайомитися з
|
||||
повними прикладами.
|
||||
`dmPolicy`, `allowFrom`, `groupAccess`, `prepare`, `finalize` тощо.
|
||||
Дивіться вбудовані пакети plugin (наприклад, plugin Discord `src/channel.setup.ts`) для
|
||||
повних прикладів.
|
||||
|
||||
Для запитів allowlist у DM, яким потрібен лише стандартний потік
|
||||
Для запитів щодо allowlist у DM, яким потрібен лише стандартний потік
|
||||
`note -> prompt -> parse -> merge -> patch`, надавайте перевагу спільним допоміжним засобам налаштування
|
||||
з `openclaw/plugin-sdk/setup`: `createPromptParsedAllowFromForAccount(...)`,
|
||||
`createTopLevelChannelParsedAllowFromPrompt(...)` і
|
||||
`createNestedChannelParsedAllowFromPrompt(...)`.
|
||||
|
||||
Для блоків статусу налаштування каналу, які відрізняються лише назвами, оцінками та необов’язковими
|
||||
Для блоків статусу налаштування channel, які відрізняються лише ярликами, оцінками та необов’язковими
|
||||
додатковими рядками, надавайте перевагу `createStandardChannelSetupStatus(...)` з
|
||||
`openclaw/plugin-sdk/setup` замість ручного створення того самого об’єкта `status` у
|
||||
`openclaw/plugin-sdk/setup` замість ручного відтворення того самого об’єкта `status` у
|
||||
кожному plugin.
|
||||
|
||||
Для необов’язкових поверхонь налаштування, які мають з’являтися лише в певних контекстах, використовуйте
|
||||
@ -499,28 +496,28 @@ const setupSurface = createOptionalChannelSetupSurface({
|
||||
npmSpec: "@myorg/openclaw-my-channel",
|
||||
docsPath: "/channels/my-channel",
|
||||
});
|
||||
// Returns { setupAdapter, setupWizard }
|
||||
// Повертає { setupAdapter, setupWizard }
|
||||
```
|
||||
|
||||
`plugin-sdk/channel-setup` також надає lower-level
|
||||
білдери `createOptionalChannelSetupAdapter(...)` і
|
||||
`plugin-sdk/channel-setup` також надає нижчорівневі
|
||||
будівники `createOptionalChannelSetupAdapter(...)` і
|
||||
`createOptionalChannelSetupWizard(...)`, коли вам потрібна лише одна половина
|
||||
цієї необов’язкової поверхні встановлення.
|
||||
|
||||
Згенеровані необов’язкові adapter/wizard завершуються безпечною відмовою на реальних записах конфігурації. Вони
|
||||
Згенеровані необов’язкові адаптер/майстер завершуються з відмовою на реальних записах конфігурації. Вони
|
||||
повторно використовують одне повідомлення про необхідність встановлення в `validateInput`,
|
||||
`applyAccountConfig` і `finalize`, а також додають посилання на документацію, якщо задано `docsPath`.
|
||||
`applyAccountConfig` і `finalize`, а також додають посилання на документацію, якщо встановлено `docsPath`.
|
||||
|
||||
Для UI налаштування, що працюють із двійковими файлами, надавайте перевагу спільним делегованим допоміжним засобам замість
|
||||
копіювання тієї самої логіки двійкових файлів/статусу в кожен канал:
|
||||
Для UI налаштування, що працюють через binary, надавайте перевагу спільним делегованим допоміжним засобам замість
|
||||
копіювання однакової логіки binary/status у кожний channel:
|
||||
|
||||
- `createDetectedBinaryStatus(...)` для блоків статусу, які відрізняються лише назвами,
|
||||
підказками, оцінками та визначенням двійкового файла
|
||||
- `createDetectedBinaryStatus(...)` для блоків статусу, що відрізняються лише ярликами,
|
||||
підказками, оцінками та виявленням binary
|
||||
- `createCliPathTextInput(...)` для текстових полів на основі шляху
|
||||
- `createDelegatedSetupWizardStatusResolvers(...)`,
|
||||
`createDelegatedPrepare(...)`, `createDelegatedFinalize(...)` і
|
||||
`createDelegatedResolveConfigured(...)`, коли `setupEntry` має ліниво передавати керування
|
||||
важчому повному майстру
|
||||
`createDelegatedResolveConfigured(...)`, коли `setupEntry` має ліниво пересилати до
|
||||
важчого повного майстра
|
||||
- `createDelegatedTextInputShouldPrompt(...)`, коли `setupEntry` має лише
|
||||
делегувати рішення `textInputs[*].shouldPrompt`
|
||||
|
||||
@ -532,15 +529,15 @@ const setupSurface = createOptionalChannelSetupSurface({
|
||||
openclaw plugins install @myorg/openclaw-my-plugin
|
||||
```
|
||||
|
||||
OpenClaw спочатку намагається використати ClawHub і автоматично переходить до npm у разі невдачі. Ви також можете
|
||||
явно примусово використати ClawHub:
|
||||
OpenClaw спочатку пробує ClawHub і автоматично переходить на npm у разі невдачі. Ви також можете
|
||||
явно примусово використовувати ClawHub:
|
||||
|
||||
```bash
|
||||
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # лише ClawHub
|
||||
openclaw plugins install clawhub:@myorg/openclaw-my-plugin # Лише ClawHub
|
||||
```
|
||||
|
||||
Відповідного перевизначення `npm:` не існує. Використовуйте звичайний npm package spec, коли
|
||||
потрібен шлях npm після переходу з ClawHub:
|
||||
Відповідного перевизначення `npm:` не існує. Використовуйте звичайну специфікацію npm-пакета, коли
|
||||
вам потрібен шлях npm після переходу з ClawHub:
|
||||
|
||||
```bash
|
||||
openclaw plugins install @myorg/openclaw-my-plugin
|
||||
@ -556,19 +553,19 @@ openclaw plugins install <package-name>
|
||||
```
|
||||
|
||||
<Info>
|
||||
Для встановлень із npm `openclaw plugins install` виконує
|
||||
`npm install --ignore-scripts` (без lifecycle scripts). Підтримуйте дерева залежностей plugin
|
||||
чистими JS/TS і уникайте пакетів, які потребують збірок через `postinstall`.
|
||||
Для встановлень із джерела npm `openclaw plugins install` запускає
|
||||
`npm install --ignore-scripts` (без lifecycle scripts). Зберігайте дерево залежностей plugin
|
||||
чистим JS/TS і уникайте пакетів, які потребують збірок `postinstall`.
|
||||
</Info>
|
||||
|
||||
Вбудовані plugins, якими володіє OpenClaw, — єдиний виняток для відновлення під час запуску: коли
|
||||
пакетне встановлення бачить один із них увімкненим через конфігурацію plugin, застарілу конфігурацію каналу або
|
||||
його вбудований маніфест із увімкненням за замовчуванням, запуск встановлює відсутні
|
||||
runtime-залежності цього plugin перед імпортом. Сторонні plugins не повинні покладатися на
|
||||
встановлення під час запуску; і далі використовуйте явний інсталятор plugin.
|
||||
Вбудовані plugins, що належать OpenClaw, — єдиний виняток для відновлення під час запуску: коли
|
||||
пакетне встановлення бачить один із них увімкненим через конфігурацію plugin, застарілу конфігурацію channel або
|
||||
його вбудований маніфест із увімкненням за замовчуванням, під час запуску встановлюються відсутні
|
||||
runtime-залежності цього plugin до імпорту. Сторонні plugins не повинні покладатися на
|
||||
встановлення під час запуску; продовжуйте використовувати явний інсталятор plugin.
|
||||
|
||||
## Пов’язане
|
||||
## Пов’язані матеріали
|
||||
|
||||
- [SDK Entry Points](/uk/plugins/sdk-entrypoints) -- `definePluginEntry` і `defineChannelPluginEntry`
|
||||
- [Plugin Manifest](/uk/plugins/manifest) -- повний довідник щодо схеми маніфесту
|
||||
- [Plugin Manifest](/uk/plugins/manifest) -- повний довідник зі схемою маніфесту
|
||||
- [Building Plugins](/uk/plugins/building-plugins) -- покроковий посібник для початку роботи
|
||||
|
||||
Loading…
Reference in New Issue
Block a user