openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh uk translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-22 07:03:00 +00:00
parent 32c63dc3f2
commit 898f10c14b
3 changed files with 687 additions and 679 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

250
docs/uk/plugins/building-plugins.md
View File

@ -1,63 +1,62 @@
---
read_when:
- Ви хочете створити новий plugin для OpenClaw
- Вам потрібен швидкий старт для розробки plugin
- Ви хочете створити новий Plugin для OpenClaw
- Вам потрібен швидкий старт для розробки Plugin-ів
- Ви додаєте до OpenClaw новий канал, провайдера, інструмент або іншу можливість
sidebarTitle: Getting Started
summary: Створіть свій перший plugin для OpenClaw за лічені хвилини
title: Розробка Plugins
summary: Створіть свій перший Plugin для OpenClaw за лічені хвилини
title: Створення Plugin-ів
x-i18n:
generated_at: "2026-04-06T12:43:45Z"
generated_at: "2026-04-22T07:00:23Z"
model: gpt-5.4
provider: openai
source_hash: 509c1f5abe1a0a74966054ed79b71a1a7ee637a43b1214c424acfe62ddf48eef
source_hash: 67368be311537f984f14bea9239b88c3eccf72a76c9dd1347bb041e02697ae24
source_path: plugins/building-plugins.md
workflow: 15
---
# Розробка Plugins
# Створення Plugin-ів
Plugins розширюють OpenClaw новими можливостями: канали, провайдери моделей,
мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння
медіа, генерація зображень, генерація відео, web fetch, web search, інструменти
агента або будь-яка комбінація цього.
Plugin-и розширюють OpenClaw новими можливостями: каналами, провайдерами моделей,
мовленням, транскрибуванням у реальному часі, голосом у реальному часі, розумінням медіа, генерацією зображень,
генерацією відео, веб-отриманням, веб-пошуком, інструментами агентів або будь-якою
комбінацією.
Вам не потрібно додавати свій plugin до репозиторію OpenClaw. Опублікуйте його в
[ClawHub](/uk/tools/clawhub) або npm, а користувачі встановлять його за допомогою
`openclaw plugins install <package-name>`. OpenClaw спочатку намагається знайти
його в ClawHub, а потім автоматично переходить до npm.
Вам не потрібно додавати свій Plugin до репозиторію OpenClaw. Опублікуйте його в
[ClawHub](/uk/tools/clawhub) або npm, і користувачі встановлять його за допомогою
`openclaw plugins install <package-name>`. OpenClaw спочатку намагається використати ClawHub і
автоматично переходить до npm, якщо це потрібно.
## Передумови
- Node >= 22 і менеджер пакетів (npm або pnpm)
- Знайомство з TypeScript (ESM)
- Для plugin у репозиторії: клонований репозиторій і виконаний `pnpm install`
- Для Plugin-ів у репозиторії: клонований репозиторій і виконаний `pnpm install`
## Який саме plugin?
## Який тип Plugin-а?
<CardGroup cols={3}>
<Card title="Plugin каналу" icon="messages-square" href="/uk/plugins/sdk-channel-plugins">
Підключіть OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо)
Підключає OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо)
</Card>
<Card title="Plugin провайдера" icon="cpu" href="/uk/plugins/sdk-provider-plugins">
Додайте провайдера моделей (LLM, проксі або користувацьку кінцеву точку)
Додає провайдера моделей (LLM, проксі або власну кінцеву точку)
</Card>
<Card title="Plugin інструмента / hook" icon="wrench">
Зареєструйте інструменти агента, hooks подій або сервіси — продовжуйте нижче
<Card title="Plugin інструментів / хуків" icon="wrench">
Реєструє інструменти агента, хуки подій або сервіси — продовжуйте нижче
</Card>
</CardGroup>
Якщо plugin каналу є необов’язковим і може бути не встановлений під час
onboarding/налаштування, використовуйте `createOptionalChannelSetupSurface(...)` з
`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптер налаштування +
майстер, яка повідомляє про вимогу встановлення й безпечно блокує реальний запис
конфігурації, доки plugin не буде встановлено.
Якщо Plugin каналу є необов’язковим і може бути не встановлений під час виконання
онбордингу/налаштування, використовуйте `createOptionalChannelSetupSurface(...)` з
`openclaw/plugin-sdk/channel-setup`. Це створює пару адаптера налаштування та майстра,
яка повідомляє про вимогу встановлення та безпечно відхиляє реальні записи конфігурації,
доки Plugin не буде встановлено.
## Швидкий старт: plugin інструмента
## Швидкий старт: Plugin інструменту
У цьому прикладі створюється мінімальний plugin, який реєструє інструмент
агента. Для plugin каналів і провайдерів є окремі посібники за посиланнями
вище.
У цьому прикладі створюється мінімальний Plugin, який реєструє інструмент агента. Для Plugin-ів
каналів і провайдерів є окремі посібники за посиланнями вище.
<Steps>
<Step title="Створіть пакет і маніфест">
@ -94,9 +93,9 @@ onboarding/налаштування, використовуйте `createOptiona
```
</CodeGroup>
Кожному plugin потрібен маніфест, навіть без конфігурації. Повну схему див.
у [Manifest](/uk/plugins/manifest). Канонічні фрагменти для публікації в ClawHub
містяться в `docs/snippets/plugin-publish/`.
Кожному Plugin-у потрібен маніфест, навіть без конфігурації. Повну схему дивіться в
[Manifest](/uk/plugins/manifest). Канонічні фрагменти для публікації в ClawHub
розміщені в `docs/snippets/plugin-publish/`.
</Step>
@ -124,16 +123,15 @@ onboarding/налаштування, використовуйте `createOptiona
});
```
`definePluginEntry` використовується для plugin, які не є каналами. Для
каналів використовуйте `defineChannelPluginEntry` — див.
[Channel Plugins](/uk/plugins/sdk-channel-plugins). Повний перелік параметрів
точки входу див. у [Entry Points](/uk/plugins/sdk-entrypoints).
`definePluginEntry` призначений для Plugin-ів, що не є каналами. Для каналів використовуйте
`defineChannelPluginEntry` — див. [Channel Plugins](/uk/plugins/sdk-channel-plugins).
Повний перелік параметрів точки входу дивіться в [Entry Points](/uk/plugins/sdk-entrypoints).
</Step>
<Step title="Протестуйте й опублікуйте">
<Step title="Протестуйте та опублікуйте">
**Зовнішні plugins:** перевірте й опублікуйте через ClawHub, потім установіть:
**Зовнішні Plugin-и:** перевірте й опублікуйте в ClawHub, а потім встановіть:
```bash
clawhub package publish your-org/your-plugin --dry-run
@ -141,10 +139,10 @@ onboarding/налаштування, використовуйте `createOptiona
openclaw plugins install clawhub:@myorg/openclaw-my-plugin
```
OpenClaw також перевіряє ClawHub перед npm для звичайних специфікацій
пакетів, таких як `@myorg/openclaw-my-plugin`.
OpenClaw також перевіряє ClawHub перед npm для звичайних специфікацій пакетів, таких як
`@myorg/openclaw-my-plugin`.
**Plugins у репозиторії:** розміщуйте їх у дереві робочого простору bundled plugin — вони виявляються автоматично.
**Plugin-и в репозиторії:** розмістіть їх у дереві робочого простору вбудованих Plugin-ів — вони будуть виявлені автоматично.
```bash
pnpm test -- <bundled-plugin-root>/my-plugin/
@ -153,65 +151,65 @@ onboarding/налаштування, використовуйте `createOptiona
</Step>
</Steps>
## Можливості plugin
## Можливості Plugin-ів
Один plugin може зареєструвати будь-яку кількість можливостей через об’єкт `api`:
Один Plugin може зареєструвати будь-яку кількість можливостей через об’єкт `api`:
| Можливість | Метод реєстрації | Детальний посібник |
| ---------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------- |
| Текстовий inference (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) |
| Бекенд CLI inference | `api.registerCliBackend(...)` | [CLI Backends](/gateway/cli-backends) |
| Канал / обмін повідомленнями | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) |
| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Можливість | Метод реєстрації | Детальний посібник |
| --------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------- |
| Текстовий inference (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) |
| Backend CLI для inference | `api.registerCliBackend(...)` | [CLI Backends](/uk/gateway/cli-backends) |
| Канал / повідомлення | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) |
| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Транскрибування в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Web fetch | `api.registerWebFetchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Web search | `api.registerWebSearchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Інструменти агента | `api.registerTool(...)` | Нижче |
| Користувацькі команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
| Hooks подій | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
| HTTP-маршрути | `api.registerHttpRoute(...)` | [Internals](/uk/plugins/architecture#gateway-http-routes) |
| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Веб-отримання | `api.registerWebFetchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Веб-пошук | `api.registerWebSearchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) |
| Вбудоване розширення Pi | `api.registerEmbeddedExtensionFactory(...)` | [SDK Overview](/uk/plugins/sdk-overview#registration-api) |
| Інструменти агентів | `api.registerTool(...)` | Нижче |
| Користувацькі команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
| Хуки подій | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
| HTTP-маршрути | `api.registerHttpRoute(...)` | [Internals](/uk/plugins/architecture#gateway-http-routes) |
| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) |
Повний API реєстрації див. у [SDK Overview](/uk/plugins/sdk-overview#registration-api).
Повний API реєстрації дивіться в [SDK Overview](/uk/plugins/sdk-overview#registration-api).
Якщо ваш plugin реєструє користувацькі методи gateway RPC, залишайте їх у
префіксі, специфічному для plugin. Простори імен адміністрування ядра (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди
зіставляються з `operator.admin`, навіть якщо plugin запитує вужчу область
доступу.
Використовуйте `api.registerEmbeddedExtensionFactory(...)`, коли Plugin-у потрібні
Pi-native хуки embedded-runner, наприклад асинхронне переписування `tool_result` перед тим, як буде надіслано
остаточне повідомлення з результатом інструменту. Віддавайте перевагу звичайним хукам Plugin-ів OpenClaw, якщо
робота не потребує таймінгу розширення Pi.
Варто пам’ятати про семантику захисту hooks:
Якщо ваш Plugin реєструє власні RPC-методи Gateway, використовуйте для них
префікс, специфічний для Plugin-а. Простори імен адміністрування ядра (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди зіставляються з
`operator.admin`, навіть якщо Plugin запитує вужчу область дії.
- `before_tool_call`: `{ block: true }` є термінальним рішенням і зупиняє обробники з нижчим пріоритетом.
- `before_tool_call`: `{ block: false }` розглядається як відсутність рішення.
- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує схвалення користувача через накладку схвалення exec, кнопки Telegram, інтеракції Discord або команду `/approve` на будь-якому каналі.
- `before_install`: `{ block: true }` є термінальним рішенням і зупиняє обробники з нижчим пріоритетом.
- `before_install`: `{ block: false }` розглядається як відсутність рішення.
- `message_sending`: `{ cancel: true }` є термінальним рішенням і зупиняє обробники з нижчим пріоритетом.
- `message_sending`: `{ cancel: false }` розглядається як відсутність рішення.
Семантика захисту хуків, яку варто пам’ятати:
Команда `/approve` обробляє і схвалення exec, і схвалення plugin із обмеженим
fallback: коли ідентифікатор схвалення exec не знайдено, OpenClaw повторно
пробує той самий ідентифікатор через схвалення plugin. Переспрямування
схвалення plugin можна налаштувати окремо через `approvals.plugin` у конфігурації.
- `before_tool_call`: `{ block: true }` є термінальним результатом і зупиняє обробники з нижчим пріоритетом.
- `before_tool_call`: `{ block: false }` вважається відсутністю рішення.
- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує підтвердження користувача через оверлей exec approval, кнопки Telegram, інтеракції Discord або команду `/approve` в будь-якому каналі.
- `before_install`: `{ block: true }` є термінальним результатом і зупиняє обробники з нижчим пріоритетом.
- `before_install`: `{ block: false }` вважається відсутністю рішення.
- `message_sending`: `{ cancel: true }` є термінальним результатом і зупиняє обробники з нижчим пріоритетом.
- `message_sending`: `{ cancel: false }` вважається відсутністю рішення.
Якщо користувацька логіка схвалення має виявляти цей самий випадок обмеженого
fallback, використовуйте `isApprovalNotFoundError` з
`openclaw/plugin-sdk/error-runtime` замість ручного зіставлення рядків
про завершення строку дії схвалення.
Команда `/approve` обробляє як підтвердження exec, так і підтвердження Plugin-ів із обмеженим fallback: якщо ідентифікатор підтвердження exec не знайдено, OpenClaw повторно пробує той самий ідентифікатор через підтвердження Plugin-ів. Переспрямування підтверджень Plugin-ів можна налаштувати окремо через `approvals.plugin` у конфігурації.
Докладніше див. у [SDK Overview hook decision semantics](/uk/plugins/sdk-overview#hook-decision-semantics).
Якщо користувацькі механізми підтвердження мають виявляти той самий випадок
обмеженого fallback, надавайте перевагу `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime`
замість ручного зіставлення рядків завершення строку дії підтвердження.
## Реєстрація інструментів агента
Докладніше дивіться в [SDK Overview hook decision semantics](/uk/plugins/sdk-overview#hook-decision-semantics).
Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути
обов’язковими (завжди доступними) або необов’язковими (користувач вмикає їх за
бажанням):
## Реєстрація інструментів агентів
Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути обов’язковими (завжди
доступними) або необов’язковими (користувач сам вмикає їх):
```typescript
register(api) {
@ -250,11 +248,11 @@ register(api) {
- Назви інструментів не повинні конфліктувати з інструментами ядра (конфлікти пропускаються)
- Використовуйте `optional: true` для інструментів із побічними ефектами або додатковими вимогами до бінарних файлів
- Користувачі можуть увімкнути всі інструменти plugin, додавши ідентифікатор plugin до `tools.allow`
- Користувачі можуть увімкнути всі інструменти з Plugin-а, додавши ідентифікатор Plugin-а до `tools.allow`
## Правила імпорту
Завжди імпортуйте з вузькоспрямованих шляхів `openclaw/plugin-sdk/<subpath>`:
Завжди імпортуйте з цільових шляхів `openclaw/plugin-sdk/<subpath>`:
```typescript
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
@ -264,64 +262,62 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
import { ... } from "openclaw/plugin-sdk";
```
Повний довідник підшляхів див. у [SDK Overview](/uk/plugins/sdk-overview).
Повний довідник підшляхів дивіться в [SDK Overview](/uk/plugins/sdk-overview).
У межах вашого plugin використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для
внутрішніх імпортів — ніколи не імпортуйте власний plugin через його шлях SDK.
У межах вашого Plugin-а використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для
внутрішніх імпортів — ніколи не імпортуйте власний Plugin через його шлях SDK.
Для plugin провайдерів зберігайте допоміжні функції, специфічні для провайдера,
у цих barrel-файлах на рівні кореня пакета, якщо лише цей шов не є справді
загальним. Поточні bundled-приклади:
Для Plugin-ів провайдерів зберігайте допоміжні засоби, специфічні для провайдера, у цих barrel-файлах
на рівні кореня пакета, якщо лише цей інтерфейс не є справді універсальним. Поточні вбудовані приклади:
- Anthropic: обгортки потоків Claude і допоміжні функції `service_tier` / beta
- OpenAI: збирачі провайдерів, допоміжні функції моделей за замовчуванням, провайдери realtime
- OpenRouter: збирач провайдера плюс допоміжні функції onboarding/конфігурації
- Anthropic: обгортки потоків Claude та допоміжні засоби `service_tier` / beta
- OpenAI: конструктори провайдерів, допоміжні засоби моделей за замовчуванням, провайдери реального часу
- OpenRouter: конструктор провайдера плюс допоміжні засоби онбордингу/конфігурації
Якщо допоміжна функція корисна лише в межах одного bundled-пакета провайдера,
залишайте її на цьому шві рівня кореня пакета замість того, щоб переносити її в
`openclaw/plugin-sdk/*`.
Якщо допоміжний засіб корисний лише всередині одного вбудованого пакета провайдера, залишайте його на
цьому інтерфейсі кореня пакета замість того, щоб переносити його до `openclaw/plugin-sdk/*`.
Деякі згенеровані шви допоміжних функцій `openclaw/plugin-sdk/<bundled-id>` усе
ще існують для підтримки й сумісності bundled-plugin, наприклад
`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Сприймайте їх як
зарезервовані поверхні, а не як типовий шаблон для нових сторонніх plugins.
Деякі згенеровані інтерфейси допоміжних засобів `openclaw/plugin-sdk/<bundled-id>` усе ще існують для
підтримки й сумісності вбудованих Plugin-ів, наприклад
`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Розглядайте їх як зарезервовані
поверхні, а не як типовий шаблон для нових сторонніх Plugin-ів.
## Контрольний список перед надсиланням
## Контрольний список перед поданням
<Check>**package.json** містить правильні метадані `openclaw`</Check>
<Check>У **package.json** вказано правильні метадані `openclaw`</Check>
<Check>Маніфест **openclaw.plugin.json** присутній і валідний</Check>
<Check>Точка входу використовує `defineChannelPluginEntry` або `definePluginEntry`</Check>
<Check>Усі імпорти використовують вузькоспрямовані шляхи `plugin-sdk/<subpath>`</Check>
<Check>Внутрішні імпорти використовують локальні модулі, а не self-imports через SDK</Check>
<Check>Усі імпорти використовують цільові шляхи `plugin-sdk/<subpath>`</Check>
<Check>Внутрішні імпорти використовують локальні модулі, а не self-import-и через SDK</Check>
<Check>Тести проходять (`pnpm test -- <bundled-plugin-root>/my-plugin/`)</Check>
<Check>`pnpm check` проходить (для plugin у репозиторії)</Check>
<Check>`pnpm check` проходить (для Plugin-ів у репозиторії)</Check>
## Тестування бета-релізів
1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Бета-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw) для оголошень про релізи.
2. Протестуйте свій plugin на бета-тезі щойно він з’явиться. Вікно до стабільного релізу зазвичай становить лише кілька годин.
3. Після тестування напишіть у гілці свого plugin в Discord-каналі `plugin-forum`: або `all good`, або що саме зламалося. Якщо у вас ще немає гілки, створіть її.
4. Якщо щось зламалося, створіть або оновіть issue з назвою `Beta blocker: <plugin-name> - <summary>` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свою гілку.
5. Відкрийте PR до `main` з назвою `fix(<plugin-id>): beta blocker - <summary>` і додайте посилання на issue і в PR, і у свою Discord-гілку. Учасники не можуть ставити мітки PR, тому назва є сигналом на боці PR для мейнтейнерів та автоматизації. Blockers із PR зливаються; blockers без PR можуть вийти в реліз попри це. Мейнтейнери стежать за цими гілками під час бета-тестування.
6. Відсутність повідомлень означає, що все добре. Якщо ви пропустите це вікно, ваш виправлення, імовірно, потрапить до наступного циклу.
1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Бета-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw) про анонси релізів.
2. Протестуйте свій Plugin на бета-тезі, щойно він з’явиться. Вікно до стабільного релізу зазвичай триває лише кілька годин.
3. Після тестування напишіть у треді вашого Plugin-а в Discord-каналі `plugin-forum`: `all good` або що саме зламалося. Якщо у вас ще немає треду, створіть його.
4. Якщо щось зламалося, створіть або оновіть issue з назвою `Beta blocker: <plugin-name> - <summary>` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свій тред.
5. Відкрийте PR до `main` з назвою `fix(<plugin-id>): beta blocker - <summary>` і додайте посилання на issue і в PR, і у свій Discord-тред. Учасники не можуть додавати мітки до PR, тому назва є сигналом на боці PR для мейнтейнерів та автоматизації. Блокери з PR будуть злиті; блокери без PR можуть усе одно потрапити в реліз. Мейнтейнери стежать за цими тредами під час бета-тестування.
6. Відсутність повідомлень означає, що все гаразд. Якщо ви пропустите це вікно, ваше виправлення, найімовірніше, потрапить до наступного циклу.
## Наступні кроки
<CardGroup cols={2}>
<Card title="Channel Plugins" icon="messages-square" href="/uk/plugins/sdk-channel-plugins">
Створіть plugin каналу обміну повідомленнями
Створіть Plugin каналу обміну повідомленнями
</Card>
<Card title="Provider Plugins" icon="cpu" href="/uk/plugins/sdk-provider-plugins">
Створіть plugin провайдера моделей
Створіть Plugin провайдера моделей
</Card>
<Card title="SDK Overview" icon="book-open" href="/uk/plugins/sdk-overview">
Довідник карти імпортів і API реєстрації
Карта імпортів і довідник API реєстрації
</Card>
<Card title="Runtime Helpers" icon="settings" href="/uk/plugins/sdk-runtime">
TTS, пошук, підлеглий агент через api.runtime
TTS, пошук, subagent через api.runtime
</Card>
<Card title="Testing" icon="test-tubes" href="/uk/plugins/sdk-testing">
Утиліти та шаблони тестування
Утиліти й шаблони тестування
</Card>
<Card title="Plugin Manifest" icon="file-json" href="/uk/plugins/manifest">
Повний довідник схеми маніфесту
@ -330,8 +326,8 @@ import { ... } from "openclaw/plugin-sdk";
## Пов’язане
- [Архітектура plugin](/uk/plugins/architecture) — поглиблений розбір внутрішньої архітектури
- [Plugin Architecture](/uk/plugins/architecture) — поглиблений огляд внутрішньої архітектури
- [SDK Overview](/uk/plugins/sdk-overview) — довідник Plugin SDK
- [Manifest](/uk/plugins/manifest) — формат маніфесту plugin
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — розробка plugin каналів
- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — розробка plugin провайдерів
- [Manifest](/uk/plugins/manifest) — формат маніфесту plugin-а
- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення Plugin-ів каналів
- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення Plugin-ів провайдерів

559
docs/uk/plugins/manifest.md
View File

@ -1,46 +1,46 @@
---
read_when:
- Ви створюєте Plugin для OpenClaw
- Вам потрібно постачати schema конфігурації plugin або налагоджувати помилки валідації plugin
summary: Вимоги до маніфесту Plugin та JSON schema (сувора валідація конфігурації)
- Ви створюєте plugin для OpenClaw
- Вам потрібно надати схему конфігурації plugin або налагодити помилки валідації plugin
summary: Вимоги до маніфесту Plugin і JSON schema (сувора валідація конфігурації)
title: Маніфест Plugin
x-i18n:
generated_at: "2026-04-22T05:13:52Z"
generated_at: "2026-04-22T07:00:23Z"
model: gpt-5.4
provider: openai
source_hash: b80735690799682939e8c8c27b6a364caa3ceadcf6319155ddeb20eb0538c313
source_hash: 085c1baccb96b8e6bd4033ad11bdd5f79bdb0daec470e977fce723c3ae38cc99
source_path: plugins/manifest.md
workflow: 15
---
# Маніфест Plugin (`openclaw.plugin.json`)
Ця сторінка стосується лише **власного маніфесту Plugin для OpenClaw**.
Ця сторінка стосується лише **власного маніфесту plugin OpenClaw**.
Сумісні компонування пакетів описано в [Пакети Plugin](/uk/plugins/bundles).
Сумісні макети пакетів дивіться в [Пакети Plugin](/uk/plugins/bundles).
Сумісні формати пакетів використовують інші файли маніфесту:
- Пакет Codex: `.codex-plugin/plugin.json`
- Пакет Claude: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude
- пакет Codex: `.codex-plugin/plugin.json`
- пакет Claude: `.claude-plugin/plugin.json` або стандартний макет компонента Claude
без маніфесту
- Пакет Cursor: `.cursor-plugin/plugin.json`
- пакет Cursor: `.cursor-plugin/plugin.json`
OpenClaw також автоматично виявляє ці компонування пакетів, але вони не проходять валідацію
за schema `openclaw.plugin.json`, описаною тут.
OpenClaw також автоматично виявляє ці макети пакетів, але вони не проходять валідацію
за схемою `openclaw.plugin.json`, описаною тут.
Для сумісних пакетів OpenClaw зараз зчитує метадані пакета разом з оголошеними
коренями skills, коренями команд Claude, типовими значеннями `settings.json` пакета Claude,
типовими значеннями Claude bundle LSP і підтримуваними пакетами hook, коли компонування відповідає
Для сумісних пакетів OpenClaw наразі читає метадані пакета разом з оголошеними
коренями skill, коренями команд Claude, типовими значеннями Claude package `settings.json`,
типовими значеннями Claude package LSP та підтримуваними наборами hook, коли макет відповідає
очікуванням середовища виконання OpenClaw.
Кожен власний Plugin для OpenClaw **має** постачатися з файлом `openclaw.plugin.json` у
Кожен власний plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у
**корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації
**без виконання коду plugin**. Відсутні або невалідні маніфести вважаються
**без виконання коду plugin**. Відсутні або некоректні маніфести вважаються
помилками plugin і блокують валідацію конфігурації.
Див. повний посібник по системі plugin: [Plugins](/uk/tools/plugin).
Щодо власної моделі можливостей і поточних вказівок із зовнішньої сумісності:
Дивіться повний посібник із системи plugin: [Plugins](/uk/tools/plugin).
Щодо власної моделі можливостей і поточних рекомендацій із зовнішньої сумісності:
[Модель можливостей](/uk/plugins/architecture#public-capability-model).
## Що робить цей файл
@ -56,27 +56,27 @@ OpenClaw також автоматично виявляє ці компонув
середовища виконання plugin
- недорогих підказок активації, які поверхні control-plane можуть перевіряти до
завантаження середовища виконання
- недорогих дескрипторів налаштування, які поверхні налаштування/онбордингу можуть перевіряти до
завантаження середовища виконання
- метаданих псевдонімів і автоувімкнення, які мають визначатися до завантаження
- недорогих дескрипторів налаштування, які поверхні налаштування/онбордингу можуть
перевіряти до завантаження середовища виконання
- метаданих псевдонімів та автоувімкнення, які мають визначатися до завантаження
середовища виконання plugin
- скорочених метаданих володіння сімейством моделей, які мають автоматично активувати
plugin до завантаження середовища виконання
- статичних знімків володіння можливостями, що використовуються для сумісного підключення bundled-елементів і
покриття контрактів
- скорочених метаданих належності до сімейства моделей, які мають автоматично
активувати plugin до завантаження середовища виконання
- статичних знімків належності можливостей, що використовуються для сумісної
інтеграції вбудованих компонентів і покриття контрактів
- недорогих метаданих QA runner, які спільний хост `openclaw qa` може перевіряти
до завантаження середовища виконання plugin
- метаданих конфігурації, специфічних для каналу, які мають об’єднуватися в
поверхнях каталогу та валідації без завантаження середовища виконання
- підказок для UI конфігурації
- метаданих конфігурації, специфічних для каналу, які мають об’єднуватися в каталог
і поверхні валідації без завантаження середовища виконання
- підказок UI для конфігурації
Не використовуйте його для:
- реєстрації поведінки середовища виконання
- оголошення entrypoint коду
- оголошення точок входу коду
- метаданих встановлення npm
Це має належати коду вашого plugin і `package.json`.
Вони мають належати коду вашого plugin і `package.json`.
## Мінімальний приклад
@ -91,7 +91,7 @@ OpenClaw також автоматично виявляє ці компонув
}
```
## Розгорнутий приклад
## Розширений приклад
```json
{
@ -125,13 +125,13 @@ OpenClaw також автоматично виявляє ці компонув
"provider": "openrouter",
"method": "api-key",
"choiceId": "openrouter-api-key",
"choiceLabel": "OpenRouter API key",
"choiceLabel": "API key OpenRouter",
"groupId": "openrouter",
"groupLabel": "OpenRouter",
"optionKey": "openrouterApiKey",
"cliFlag": "--openrouter-api-key",
"cliOption": "--openrouter-api-key <key>",
"cliDescription": "OpenRouter API key",
"cliDescription": "API key OpenRouter",
"onboardingScopes": ["text-inference"]
}
],
@ -158,64 +158,64 @@ OpenClaw також автоматично виявляє ці компонув
| Поле | Обов’язкове | Тип | Що воно означає |
| ------------------------------------ | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | Так | `string` | Канонічний id plugin. Це id, який використовується в `plugins.entries.<id>`. |
| `id` | Так | `string` | Канонічний ідентифікатор plugin. Це ідентифікатор, який використовується в `plugins.entries.<id>`. |
| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього plugin. |
| `enabledByDefault` | Ні | `true` | Позначає bundled plugin як увімкнений за замовчуванням. Пропустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб plugin залишався вимкненим за замовчуванням. |
| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id plugin. |
| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id provider, які мають автоматично вмикати цей plugin, коли на них посилаються автентифікація, конфігурація або посилання на моделі. |
| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує виключний тип plugin, який використовується `plugins.slots.*`. |
| `channels` | Ні | `string[]` | Id каналів, якими володіє цей plugin. Використовується для виявлення та валідації конфігурації. |
| `providers` | Ні | `string[]` | Id provider, якими володіє цей plugin. |
| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту та використовуються для автоматичного завантаження plugin до запуску середовища виконання. |
| `providerEndpoints` | Ні | `object[]` | Метадані хостів/`baseUrl` кінцевих точок, що належать маніфесту, для маршрутів provider, які ядро має класифікувати до завантаження середовища виконання provider. |
| `cliBackends` | Ні | `string[]` | Id CLI backend, якими володіє цей plugin. Використовується для автоактивації під час запуску на основі явних посилань у конфігурації. |
| `syntheticAuthRefs` | Ні | `string[]` | Посилання на provider або CLI backend, для яких належний plugin synthetic auth hook слід перевіряти під час холодного виявлення моделей до завантаження середовища виконання. |
| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать bundled plugin і представляють локальний стан без секретів, OAuth або ambient credential state. |
| `enabledByDefault` | Ні | `true` | Позначає вбудований plugin як увімкнений за замовчуванням. Не вказуйте це поле або встановіть будь-яке значення, відмінне від `true`, щоб plugin залишався вимкненим за замовчуванням. |
| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора plugin. |
| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори provider, які мають автоматично вмикати цей plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. |
| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує винятковий тип plugin, який використовується `plugins.slots.*`. |
| `channels` | Ні | `string[]` | Ідентифікатори channel, якими володіє цей plugin. Використовується для виявлення та валідації конфігурації. |
| `providers` | Ні | `string[]` | Ідентифікатори provider, якими володіє цей plugin. |
| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, що належать маніфесту, і використовуються для автоматичного завантаження plugin до запуску середовища виконання. |
| `providerEndpoints` | Ні | `object[]` | Метадані хостів endpoint/baseUrl, що належать маніфесту, для маршрутів provider, які ядро має класифікувати до завантаження середовища виконання provider. |
| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI inference, якими володіє цей plugin. Використовується для автоактивації під час запуску з явних посилань у конфігурації. |
| `syntheticAuthRefs` | Ні | `string[]` | Посилання на provider або backend CLI, для яких слід перевіряти синтетичний hook автентифікації, що належить plugin, під час холодного виявлення моделей до завантаження середовища виконання. |
| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать вбудованому plugin і представляють не секретний локальний стан, OAuth або стан облікових даних середовища. |
| `commandAliases` | Ні | `object[]` | Імена команд, що належать цьому plugin і мають створювати діагностику конфігурації та CLI з урахуванням plugin до завантаження середовища виконання. |
| `providerAuthEnvVars` | Ні | `Record<string, string[]>` | Недорогі env-метадані автентифікації provider, які OpenClaw може перевіряти без завантаження коду plugin. |
| `providerAuthAliases` | Ні | `Record<string, string>` | Id provider, які мають повторно використовувати інший id provider для пошуку автентифікації, наприклад coding provider, що ділить API key базового provider і профілі автентифікації. |
| `channelEnvVars` | Ні | `Record<string, string[]>` | Недорогі env-метадані каналу, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для керованого через env налаштування каналу або поверхонь автентифікації, які мають бачити загальні помічники запуску/конфігурації. |
| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення preferred-provider і простого підключення CLI flags. |
| `activation` | Ні | `object` | Недорогі підказки активації для завантаження, що запускається provider, командами, каналами, маршрутами та можливостями. Лише метадані; фактична поведінка все одно належить середовищу виконання plugin. |
| `providerAuthEnvVars` | Ні | `Record<string, string[]>` | Недорогі метадані env для автентифікації provider, які OpenClaw може перевіряти без завантаження коду plugin. |
| `providerAuthAliases` | Ні | `Record<string, string>` | Ідентифікатори provider, які мають повторно використовувати інший ідентифікатор provider для пошуку автентифікації, наприклад provider для кодування, який ділить API key і профілі автентифікації з базовим provider. |
| `channelEnvVars` | Ні | `Record<string, string[]>` | Недорогі метадані env для channel, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для налаштування channel або поверхонь автентифікації, керованих env, які мають бачити загальні допоміжні засоби запуску/конфігурації. |
| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення бажаного provider і простого підключення прапорців CLI. |
| `activation` | Ні | `object` | Недорогі підказки активації для завантаження, ініційованого provider, командою, channel, маршрутом і можливістю. Лише метадані; фактична поведінка все одно належить середовищу виконання plugin. |
| `setup` | Ні | `object` | Недорогі дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання plugin. |
| `qaRunners` | Ні | `object[]` | Недорогі дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження середовища виконання plugin. |
| `contracts` | Ні | `object` | Статичний bundled-знімок можливостей для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння tools. |
| `mediaUnderstandingProviderMetadata` | Ні | `Record<string, object>` | Недорогі типові значення media-understanding для id provider, оголошених у `contracts.mediaUnderstandingProviders`. |
| `channelConfigs` | Ні | `Record<string, object>` | Метадані конфігурації каналу, що належать маніфесту та об’єднуються з поверхнями виявлення й валідації до завантаження середовища виконання. |
| `skills` | Ні | `string[]` | Каталоги Skills для завантаження відносно кореня plugin. |
| `name` | Ні | `string` | Людинозрозуміла назва plugin. |
| `description` | Ні | `string` | Короткий опис, що показується в поверхнях plugin. |
| `version` | Ні | `string` | Інформаційна версія plugin. |
| `uiHints` | Ні | `Record<string, object>` | Підписи UI, placeholders і підказки чутливості для полів конфігурації. |
| `qaRunners` | Ні | `object[]` | Недорогі дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання plugin. |
| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. |
| `mediaUnderstandingProviderMetadata` | Ні | `Record<string, object>` | Недорогі типові значення media-understanding для ідентифікаторів provider, оголошених у `contracts.mediaUnderstandingProviders`. |
| `channelConfigs` | Ні | `Record<string, object>` | Метадані конфігурації channel, що належать маніфесту, об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. |
| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. |
| `name` | Ні | `string` | Зрозуміла людині назва plugin. |
| `description` | Ні | `string` | Короткий підсумок, що показується в поверхнях plugin. |
| `version` | Ні | `string` | Інформаційна версія plugin. |
| `uiHints` | Ні | `Record<string, object>` | Мітки UI, placeholders і підказки чутливості для полів конфігурації. |
## Довідник `providerAuthChoices`
Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації.
OpenClaw зчитує це до завантаження середовища виконання provider.
| Поле | Обов’язкове | Тип | Що воно означає |
| --------------------- | ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `provider` | Так | `string` | Id provider, до якого належить цей варіант. |
| `method` | Так | `string` | Id методу автентифікації, до якого слід спрямувати обробку. |
| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, який використовують потоки онбордингу та CLI. |
| `choiceLabel` | Ні | `string` | Підпис для користувача. Якщо його пропущено, OpenClaw використовує `choiceId`. |
| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. |
| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих асистентом. |
| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із засобів вибору асистента, але все одно дозволяє ручний вибір через CLI. |
| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які мають перенаправляти користувачів до цього варіанта-заміни. |
| `groupId` | Ні | `string` | Необов’язковий id групи для пов’язаних варіантів. |
| `groupLabel` | Ні | `string` | Підпис цієї групи для користувача. |
| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним flag. |
| `cliFlag` | Ні | `string` | Назва CLI flag, наприклад `--openrouter-api-key`. |
| `cliOption` | Ні | `string` | Повна форма CLI option, наприклад `--openrouter-api-key <key>`. |
| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. |
| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо поле пропущене, за замовчуванням використовується `["text-inference"]`. |
| Поле | Обов’язкове | Тип | Що воно означає |
| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `provider` | Так | `string` | Ідентифікатор provider, до якого належить цей варіант. |
| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід спрямовувати. |
| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується під час онбордингу та в CLI. |
| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. |
| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. |
| `assistantPriority` | Ні | `number` | Менші значення сортуються вище в інтерактивних засобах вибору, керованих помічником. |
| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує цей варіант із засобів вибору помічника, але все ще дозволяє ручний вибір через CLI. |
| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів до цього варіанта-заміни. |
| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для пов’язаних варіантів. |
| `groupLabel` | Ні | `string` | Мітка для цієї групи, видима користувачу. |
| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. |
| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих сценаріїв автентифікації з одним прапорцем. |
| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. |
| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key <key>`. |
| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. |
| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. |
## Довідник `commandAliases`
Використовуйте `commandAliases`, коли plugin володіє назвою команди середовища виконання, яку користувачі можуть
помилково додати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw
помилково вказати в `plugins.allow` або спробувати виконати як кореневу команду CLI. OpenClaw
використовує ці метадані для діагностики без імпорту коду середовища виконання plugin.
```json
@ -230,10 +230,10 @@ OpenClaw зчитує це до завантаження середовища в
}
```
| Поле | Обов’язкове | Тип | Що воно означає |
| ------------ | ----------- | ----------------- | ---------------------------------------------------------------------------- |
| `name` | Так | `string` | Назва команди, яка належить цьому plugin. |
| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду CLI. |
| Поле | Обов’язкове | Тип | Що воно означає |
| ------------ | ----------- | ----------------- | ------------------------------------------------------------------------------ |
| `name` | Так | `string` | Назва команди, яка належить цьому plugin. |
| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду CLI. |
| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо вона існує. |
## Довідник `activation`
@ -243,9 +243,9 @@ OpenClaw зчитує це до завантаження середовища в
## Довідник `qaRunners`
Використовуйте `qaRunners`, коли plugin додає один або кілька transport runner під
спільним коренем `openclaw qa`. Зберігайте ці метадані простими й статичними; фактичне
середовище виконання plugin усе одно відповідає за реєстрацію CLI через легку поверхню
Використовуйте `qaRunners`, коли plugin додає один або кілька transport runner у межах
спільного кореня `openclaw qa`. Зберігайте ці метадані недорогими та статичними; фактична
реєстрація CLI все одно належить середовищу виконання plugin через легку поверхню
`runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`.
```json
@ -253,22 +253,22 @@ OpenClaw зчитує це до завантаження середовища в
"qaRunners": [
{
"commandName": "matrix",
"description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
"description": "Запустити живий QA lane Matrix на основі Docker проти тимчасового homeserver"
}
]
}
```
| Поле | Обов’язкове | Тип | Що воно означає |
| ------------- | ----------- | -------- | --------------------------------------------------------------------- |
| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. |
| Поле | Обов’язкове | Тип | Що воно означає |
| ------------- | ----------- | -------- | ------------------------------------------------------------------------ |
| `commandName` | Так | `string` | Підкоманда, змонтована в `openclaw qa`, наприклад `matrix`. |
| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна stub-команда. |
Цей блок містить лише метадані. Він не реєструє поведінку середовища виконання і
не замінює `register(...)`, `setupEntry` або інші entrypoint середовища виконання/plugin.
Цей блок є лише метаданими. Він не реєструє поведінку середовища виконання і не
замінює `register(...)`, `setupEntry` чи інші точки входу середовища виконання/plugin.
Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням plugin, тому
відсутність метаданих активації зазвичай впливає лише на продуктивність; це не має
змінювати коректність, поки все ще існують застарілі резервні механізми володіння маніфестом.
відсутність метаданих активації зазвичай впливає лише на продуктивність; це не повинно
змінювати коректність, доки все ще існують застарілі резервні механізми володіння маніфестом.
```json
{
@ -282,28 +282,28 @@ OpenClaw зчитує це до завантаження середовища в
}
```
| Поле | Обов’язкове | Тип | Що воно означає |
| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
| `onProviders` | Ні | `string[]` | Id provider, які мають активувати цей plugin за запитом. |
| `onCommands` | Ні | `string[]` | Id команд, які мають активувати цей plugin. |
| `onChannels` | Ні | `string[]` | Id каналів, які мають активувати цей plugin. |
| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають активувати цей plugin. |
| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, які використовуються при плануванні активації control-plane. |
| Поле | Обов’язкове | Тип | Що воно означає |
| ---------------- | ----------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
| `onProviders` | Ні | `string[]` | Ідентифікатори provider, які мають активувати цей plugin за запитом. |
| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають активувати цей plugin. |
| `onChannels` | Ні | `string[]` | Ідентифікатори channel, які мають активувати цей plugin. |
| `onRoutes` | Ні | `string[]` | Типи route, які мають активувати цей plugin. |
| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються під час планування активації control-plane. |
Поточні живі споживачі:
Поточні активні споживачі:
- планування CLI, запущене командою, повертається до застарілих
`commandAliases[].cliCommand` або `commandAliases[].name`
- планування налаштування/каналу, запущене каналом, повертається до застарілого володіння
`channels[]`, якщо явні метадані активації каналу відсутні
- планування налаштування/середовища виконання, запущене provider, повертається до застарілого
володіння `providers[]` і верхньорівневого `cliBackends[]`, якщо явні метадані активації provider
відсутні
- планування CLI, ініційоване командою, використовує як резервний варіант
застарілі `commandAliases[].cliCommand` або `commandAliases[].name`
- планування setup/channel, ініційоване channel, використовує як резервний варіант
застаріле володіння `channels[]`, коли явні метадані активації channel відсутні
- планування setup/runtime, ініційоване provider, використовує як резервний варіант
застаріле володіння `providers[]` і верхньорівневими `cliBackends[]`, коли явні метадані
активації provider відсутні
## Довідник `setup`
Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні недорогі метадані plugin до
завантаження середовища виконання.
Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні недорогі метадані plugin
до завантаження середовища виконання.
```json
{
@ -322,48 +322,47 @@ OpenClaw зчитує це до завантаження середовища в
}
```
Верхньорівневе `cliBackends` залишається валідним і надалі описує CLI backend
для інференсу. `setup.cliBackends` — це поверхня дескрипторів, специфічна для налаштування,
для потоків control-plane/налаштування, яка має залишатися лише метаданими.
Верхньорівневий `cliBackends` залишається коректним і надалі описує backend CLI inference.
`setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків
control-plane/setup, яка має залишатися лише метаданими.
Якщо присутні, `setup.providers` і `setup.cliBackends` є пріоритетною
поверхнею пошуку для виявлення налаштування за принципом descriptor-first. Якщо дескриптор лише
звужує кандидатний plugin, а налаштуванню все ще потрібні багатші runtime hooks на етапі налаштування,
встановіть `requiresRuntime: true` і залиште `setup-api` як
резервний шлях виконання.
Якщо вони присутні, `setup.providers` і `setup.cliBackends` є бажаною поверхнею пошуку
на основі дескрипторів для виявлення setup. Якщо дескриптор лише звужує коло кандидатів plugin, а для setup
усе ще потрібні багатші hook середовища виконання на етапі налаштування, установіть `requiresRuntime: true`
і збережіть `setup-api` як резервний шлях виконання.
Оскільки пошук налаштування може виконувати код `setup-api`, що належить plugin,
нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед
Оскільки пошук setup може виконувати код `setup-api`, що належить plugin, нормалізовані значення
`setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед усіх
виявлених plugin. Неоднозначне володіння призводить до безпечної відмови замість вибору
переможця за порядком виявлення.
### Довідник `setup.providers`
| Поле | Обов’язкове | Тип | Що воно означає |
| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------------ |
| `id` | Так | `string` | Id provider, який надається під час налаштування або онбордингу. Зберігайте нормалізовані id глобально унікальними. |
| `authMethods` | Ні | `string[]` | Id методів налаштування/автентифікації, які цей provider підтримує без завантаження повного середовища виконання. |
| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні налаштування/статусу можуть перевіряти до завантаження середовища виконання plugin. |
| Поле | Обов’язкове | Тип | Що воно означає |
| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------------- |
| `id` | Так | `string` | Ідентифікатор provider, який показується під час setup або онбордингу. Зберігайте нормалізовані ідентифікатори глобально унікальними. |
| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/auth, які цей provider підтримує без завантаження повного середовища виконання. |
| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження середовища виконання plugin. |
### Поля `setup`
| Поле | Обов’язкове | Тип | Що воно означає |
| ------------------ | ----------- | ---------- | ------------------------------------------------------------------------------------------------------- |
| `providers` | Ні | `object[]` | Дескриптори налаштування provider, які надаються під час налаштування та онбордингу. |
| `cliBackends` | Ні | `string[]` | Id backend для етапу налаштування, які використовуються для descriptor-first пошуку налаштування. Зберігайте нормалізовані id глобально унікальними. |
| `configMigrations` | Ні | `string[]` | Id міграцій конфігурації, що належать поверхні налаштування цього plugin. |
| `requiresRuntime` | Ні | `boolean` | Чи потребує налаштування виконання `setup-api` після пошуку за дескриптором. |
| Поле | Обов’язкове | Тип | Що воно означає |
| ------------------ | ----------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| `providers` | Ні | `object[]` | Дескриптори setup provider, доступні під час setup та онбордингу. |
| `cliBackends` | Ні | `string[]` | Ідентифікатори backend для етапу setup, що використовуються для пошуку setup на основі дескрипторів. Зберігайте нормалізовані ідентифікатори глобально унікальними. |
| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього plugin. |
| `requiresRuntime` | Ні | `boolean` | Чи все ще потрібне виконання `setup-api` після пошуку за дескриптором. |
## Довідник `uiHints`
`uiHints` — це мапа від назв полів конфігурації до невеликих підказок для рендерингу.
`uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу.
```json
{
"uiHints": {
"apiKey": {
"label": "API key",
"help": "Used for OpenRouter requests",
"help": "Використовується для запитів OpenRouter",
"placeholder": "sk-or-v1-...",
"sensitive": true
}
@ -371,16 +370,16 @@ OpenClaw зчитує це до завантаження середовища в
}
```
Кожна підказка поля може містити:
Кожна підказка для поля може містити:
| Поле | Тип | Що воно означає |
| ------------- | ---------- | -------------------------------------- |
| `label` | `string` | Підпис поля для користувача. |
| `help` | `string` | Короткий допоміжний текст. |
| `tags` | `string[]` | Необов’язкові теги UI. |
| `advanced` | `boolean` | Позначає поле як розширене. |
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
| `placeholder` | `string` | Текст placeholder для полів форми. |
| Поле | Тип | Що воно означає |
| ------------- | ---------- | --------------------------------------- |
| `label` | `string` | Мітка поля, видима користувачу. |
| `help` | `string` | Короткий допоміжний текст. |
| `tags` | `string[]` | Необов’язкові теги UI. |
| `advanced` | `boolean` | Позначає поле як розширене. |
| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. |
| `placeholder` | `string` | Текст placeholder для полів форми. |
## Довідник `contracts`
@ -390,6 +389,7 @@ OpenClaw зчитує це до завантаження середовища в
```json
{
"contracts": {
"embeddedExtensionFactories": ["pi"],
"speechProviders": ["openai"],
"realtimeTranscriptionProviders": ["openai"],
"realtimeVoiceProviders": ["openai"],
@ -405,23 +405,24 @@ OpenClaw зчитує це до завантаження середовища в
Кожен список необов’язковий:
| Поле | Тип | Що воно означає |
| -------------------------------- | ---------- | ------------------------------------------------------------ |
| `speechProviders` | `string[]` | Id speech provider, якими володіє цей plugin. |
| `realtimeTranscriptionProviders` | `string[]` | Id provider для транскрипції в реальному часі, якими володіє цей plugin. |
| `realtimeVoiceProviders` | `string[]` | Id provider голосу в реальному часі, якими володіє цей plugin. |
| `mediaUnderstandingProviders` | `string[]` | Id provider для розуміння медіа, якими володіє цей plugin. |
| `imageGenerationProviders` | `string[]` | Id provider генерації зображень, якими володіє цей plugin. |
| `videoGenerationProviders` | `string[]` | Id provider генерації відео, якими володіє цей plugin. |
| `webFetchProviders` | `string[]` | Id provider для web-fetch, якими володіє цей plugin. |
| `webSearchProviders` | `string[]` | Id provider для web search, якими володіє цей plugin. |
| `tools` | `string[]` | Назви tools агента, якими володіє цей plugin, для перевірок bundled-контрактів. |
| Поле | Тип | Що воно означає |
| -------------------------------- | ---------- | ------------------------------------------------------------------------- |
| `embeddedExtensionFactories` | `string[]` | Ідентифікатори вбудованого середовища виконання, для яких вбудований plugin може реєструвати фабрики. |
| `speechProviders` | `string[]` | Ідентифікатори speech provider, якими володіє цей plugin. |
| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори provider для realtime transcription, якими володіє цей plugin. |
| `realtimeVoiceProviders` | `string[]` | Ідентифікатори provider для realtime voice, якими володіє цей plugin. |
| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори provider для media-understanding, якими володіє цей plugin. |
| `imageGenerationProviders` | `string[]` | Ідентифікатори provider для image-generation, якими володіє цей plugin. |
| `videoGenerationProviders` | `string[]` | Ідентифікатори provider для video-generation, якими володіє цей plugin. |
| `webFetchProviders` | `string[]` | Ідентифікатори provider для web-fetch, якими володіє цей plugin. |
| `webSearchProviders` | `string[]` | Ідентифікатори provider для web search, якими володіє цей plugin. |
| `tools` | `string[]` | Назви agent tool, якими володіє цей plugin, для перевірок контрактів вбудованих компонентів. |
## Довідник `mediaUnderstandingProviderMetadata`
Використовуйте `mediaUnderstandingProviderMetadata`, коли provider для розуміння медіа має
типові моделі, пріоритет резервного auto-auth або вбудовану підтримку документів, які
загальним helper ядра потрібні до завантаження середовища виконання. Ключі також мають бути оголошені в
Використовуйте `mediaUnderstandingProviderMetadata`, коли provider для media-understanding має
типові моделі, пріоритет резервного автоавтентифікування або нативну підтримку документів,
які потрібні загальним допоміжним засобам ядра до завантаження середовища виконання. Ключі також мають бути оголошені в
`contracts.mediaUnderstandingProviders`.
```json
@ -447,17 +448,17 @@ OpenClaw зчитує це до завантаження середовища в
Кожен запис provider може містити:
| Поле | Тип | Що воно означає |
| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------- |
| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей provider. |
| `defaultModels` | `Record<string, string>` | Типові значення відповідності можливість-модель, які використовуються, коли конфігурація не задає модель. |
| `autoPriority` | `Record<string, number>` | Менші числа сортуються раніше для автоматичного резервного вибору provider на основі credential. |
| `nativeDocumentInputs` | `"pdf"[]` | Вбудовані формати документів, які підтримує provider. |
| Поле | Тип | Що воно означає |
| ---------------------- | ----------------------------------- | --------------------------------------------------------------------------- |
| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості медіа, які надає цей provider. |
| `defaultModels` | `Record<string, string>` | Типові відповідності можливість-модель, які використовуються, коли конфігурація не вказує модель. |
| `autoPriority` | `Record<string, number>` | Менші числа сортуються раніше для автоматичного резервного вибору provider на основі облікових даних. |
| `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні формати документів, які підтримує provider. |
## Довідник `channelConfigs`
Використовуйте `channelConfigs`, коли plugin каналу потребує недорогих метаданих конфігурації до
завантаження середовища виконання.
Використовуйте `channelConfigs`, коли channel plugin потребує недорогих метаданих конфігурації
до завантаження середовища виконання.
```json
{
@ -477,27 +478,28 @@ OpenClaw зчитує це до завантаження середовища в
}
},
"label": "Matrix",
"description": "Matrix homeserver connection",
"description": "Підключення до homeserver Matrix",
"preferOver": ["matrix-legacy"]
}
}
}
```
Кожен запис каналу може містити:
Кожен запис channel може містити:
| Поле | Тип | Що воно означає |
| ------------- | ------------------------ | ---------------------------------------------------------------------------------------------- |
| `schema` | `object` | JSON Schema для `channels.<id>`. Обов’язкове для кожного оголошеного запису конфігурації каналу. |
| `uiHints` | `Record<string, object>` | Необов’язкові підписи UI/placeholders/підказки чутливості для цього розділу конфігурації каналу. |
| `label` | `string` | Підпис каналу, який об’єднується з поверхнями вибору та перегляду, коли метадані середовища виконання ще не готові. |
| `description` | `string` | Короткий опис каналу для поверхонь перегляду та каталогу. |
| `preferOver` | `string[]` | Id застарілих plugin або plugin з нижчим пріоритетом, які цей канал має випереджати в поверхнях вибору. |
| Поле | Тип | Що воно означає |
| ------------- | ------------------------ | --------------------------------------------------------------------------------------- |
| `schema` | `object` | JSON Schema для `channels.<id>`. Обов’язкова для кожного оголошеного запису конфігурації channel. |
| `uiHints` | `Record<string, object>` | Необов’язкові мітки UI/placeholders/підказки чутливості для цього розділу конфігурації channel. |
| `label` | `string` | Мітка channel, яка об’єднується в поверхні вибору та інспекції, коли метадані середовища виконання ще не готові. |
| `description` | `string` | Короткий опис channel для поверхонь інспекції та каталогу. |
| `preferOver` | `string[]` | Ідентифікатори застарілих або менш пріоритетних plugin, які цей channel має перевершувати на поверхнях вибору. |
## Довідник `modelSupport`
Використовуйте `modelSupport`, коли OpenClaw має визначати ваш provider plugin із
скорочених id моделей на кшталт `gpt-5.4` або `claude-sonnet-4.6` до завантаження середовища виконання plugin.
Використовуйте `modelSupport`, коли OpenClaw має визначати ваш provider plugin за
скороченими ідентифікаторами моделей, як-от `gpt-5.4` або `claude-sonnet-4.6`, до завантаження
середовища виконання plugin.
```json
{
@ -511,85 +513,84 @@ OpenClaw зчитує це до завантаження середовища в
OpenClaw застосовує такий пріоритет:
- явні посилання `provider/model` використовують метадані маніфесту `providers`, що належать власнику
- `modelPatterns` мають пріоритет над `modelPrefixes`
- якщо збігаються один небандлований plugin і один bundled plugin, перемагає небандлований
- `modelPatterns` мають вищий пріоритет за `modelPrefixes`
- якщо збігаються один невбудований plugin і один вбудований plugin, перемагає невбудований
plugin
- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть provider
- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже provider
Поля:
| Поле | Тип | Що воно означає |
| --------------- | ---------- | -------------------------------------------------------------------------------- |
| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id моделей. |
| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id моделей після видалення суфікса профілю. |
| Поле | Тип | Що воно означає |
| --------------- | ---------- | ------------------------------------------------------------------------------ |
| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. |
| `modelPatterns` | `string[]` | Джерела regex, які зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. |
Застарілі ключі можливостей верхнього рівня більше не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб
перемістити `speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`,
`webFetchProviders` і `webSearchProviders` до `contracts`; звичайне
завантаження маніфесту більше не вважає ці поля верхнього рівня
власниками можливостей.
`webFetchProviders` і `webSearchProviders` у `contracts`; звичайне
завантаження маніфесту більше не розглядає ці поля верхнього рівня як
володіння можливостями.
## Маніфест порівняно з package.json
## Маніфест проти package.json
Ці два файли виконують різні завдання:
| Файл | Для чого використовувати |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду plugin |
| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoint, обмежень встановлення, налаштування або метаданих каталогу |
| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, який використовується для точок входу, обмежень встановлення, setup або метаданих каталогу |
Якщо ви не впевнені, куди належить певний фрагмент метаданих, користуйтеся таким правилом:
- якщо OpenClaw має знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json`
- якщо це стосується пакування, файлів entrypoint або поведінки встановлення npm, помістіть це в `package.json`
- якщо OpenClaw має знати це до завантаження коду plugin, розмістіть це в `openclaw.plugin.json`
- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розмістіть це в `package.json`
### Поля `package.json`, що впливають на виявлення
### Поля package.json, які впливають на виявлення
Деякі метадані plugin до запуску середовища виконання навмисно розміщені в `package.json` у блоці
Деякі метадані plugin до запуску середовища виконання навмисно зберігаються в `package.json` у блоці
`openclaw`, а не в `openclaw.plugin.json`.
Важливі приклади:
| Поле | Що воно означає |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions` | Оголошує власні entrypoint plugin. Має залишатися всередині каталогу пакета plugin. |
| `openclaw.runtimeExtensions` | Оголошує entrypoint built JavaScript runtime для встановлених пакетів. Має залишатися всередині каталогу пакета plugin. |
| `openclaw.setupEntry` | Легкий entrypoint лише для налаштування, що використовується під час онбордингу, відкладеного запуску каналу та read-only виявлення стану каналу/SecretRef. Має залишатися всередині каталогу пакета plugin. |
| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript entrypoint налаштування для встановлених пакетів. Має залишатися всередині каталогу пакета plugin. |
| `openclaw.channel` | Недорогі метадані каталогу каналу, як-от підписи, шляхи до документації, псевдоніми та текст для вибору. |
| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного середовища виконання каналу. |
| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже виконано вхід?» без завантаження повного середовища виконання каналу. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для bundled plugin і externally published plugin. |
| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із використанням нижньої межі semver, наприклад `>=2026.3.22`. |
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення bundled plugin, коли конфігурація невалідна. |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для налаштування завантажуватися до повного plugin каналу під час запуску. |
| Поле | Що воно означає |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `openclaw.extensions` | Оголошує точки входу власних plugin. Має залишатися в каталозі пакета plugin. |
| `openclaw.runtimeExtensions` | Оголошує точки входу built JavaScript runtime для встановлених пакетів. Має залишатися в каталозі пакета plugin. |
| `openclaw.setupEntry` | Легка точка входу лише для setup, яка використовується під час онбордингу, відкладеного запуску channel і виявлення status/SecretRef channel лише для читання. Має залишатися в каталозі пакета plugin. |
| `openclaw.runtimeSetupEntry` | Оголошує точку входу built JavaScript setup для встановлених пакетів. Має залишатися в каталозі пакета plugin. |
| `openclaw.channel` | Недорогі метадані каталогу channel, як-от мітки, шляхи до документації, псевдоніми та текст для вибору. |
| `openclaw.channel.configuredState` | Недорогі метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного середовища виконання channel. |
| `openclaw.channel.persistedAuthState` | Недорогі метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже є якийсь активний вхід?» без завантаження повного середовища виконання channel. |
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення вбудованих і зовнішньо опублікованих plugin. |
| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. |
| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw з використанням нижньої межі semver, наприклад `>=2026.3.22`. |
| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення вбудованого plugin, коли конфігурація некоректна. |
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного channel plugin під час запуску. |
`openclaw.install.minHostVersion` застосовується під час встановлення та
завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні значення пропускають
завантаження реєстру маніфестів. Некоректні значення відхиляються; новіші, але коректні значення пропускають
plugin на старіших хостах.
Plugin каналів мають надавати `openclaw.setupEntry`, коли перевірки статусу, списку каналів
або SecretRef повинні визначати налаштовані акаунти без завантаження повного
середовища виконання. Entrypoint налаштування має надавати метадані каналу разом із безпечними для налаштування
адаптерами конфігурації, статусу та секретів; мережеві клієнти, слухачі Gateway і
transport runtime слід залишати в основному entrypoint розширення.
Channel plugin мають надавати `openclaw.setupEntry`, коли сканування status, списку channel
або SecretRef має визначати налаштовані облікові записи без завантаження повного
середовища виконання. Точка входу setup має надавати метадані channel разом із безпечними для setup адаптерами
конфігурації, status і secrets; мережеві клієнти, слухачі Gateway і
transport runtime слід залишати в основній точці входу extension.
Поля runtime entrypoint не скасовують перевірки меж пакета для полів
source entrypoint. Наприклад, `openclaw.runtimeExtensions` не може зробити
придатним до завантаження шлях `openclaw.extensions`, що виходить за межі пакета.
Поля точки входу runtime не обходять перевірки меж пакета для полів
вихідної точки входу. Наприклад, `openclaw.runtimeExtensions` не може зробити
доступним для завантаження шлях `openclaw.extensions`, що виходить за межі.
`openclaw.install.allowInvalidConfigRecovery` навмисно має вузьке призначення. Воно
не робить довільні зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє потокам встановлення
відновлюватися після певних збоїв оновлення застарілого bundled plugin, таких як
відсутній шлях bundled plugin або застарілий запис `channels.<id>` для того самого
bundled plugin. Несуміжні помилки конфігурації все одно блокують встановлення й спрямовують операторів
не робить довільно зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє
процесам встановлення відновлюватися після конкретних застарілих збоїв оновлення вбудованих plugin,
наприклад відсутнього шляху до вбудованого plugin або застарілого запису `channels.<id>` для того самого
вбудованого plugin. Непов’язані помилки конфігурації й надалі блокують встановлення та спрямовують операторів
до `openclaw doctor --fix`.
`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля
перевірки:
`openclaw.channel.persistedAuthState` — це метадані пакета для маленького модуля перевірки:
```json
{
@ -605,12 +606,12 @@ bundled plugin. Несуміжні помилки конфігурації вс
}
```
Використовуйте це, коли потоки налаштування, doctor або configured-state потребують
недорогої перевірки автентифікації типу так/ні до завантаження повного plugin каналу.
Цільовий експорт має бути невеликою функцією, яка лише зчитує збережений стан; не
спрямовуйте її через повний barrel середовища виконання каналу.
Використовуйте це, коли потокам setup, doctor або configured-state потрібна недорога
перевірка автентифікації типу yes/no до завантаження повного channel plugin. Цільовий export має бути невеликою
функцією, яка лише читає збережений стан; не спрямовуйте її через повний barrel
середовища виконання channel.
`openclaw.channel.configuredState` має ту саму форму для недорогих перевірок
`openclaw.channel.configuredState` має таку саму форму для недорогих перевірок
configured-state лише через env:
```json
@ -627,96 +628,96 @@ configured-state лише через env:
}
```
Використовуйте це, коли канал може визначити configured-state через env або інші
невеликі вхідні дані без середовища виконання. Якщо перевірці потрібне повне
розв’язання конфігурації або справжнє середовище виконання каналу, залиште цю логіку
в hook `config.hasConfiguredState` plugin.
Використовуйте це, коли channel може визначити configured-state з env або інших малих
не-runtime входів. Якщо перевірці потрібне повне визначення конфігурації або реальне
середовище виконання channel, залишайте цю логіку в hook `config.hasConfiguredState`
plugin.
## Пріоритет виявлення (дубльовані id plugin)
## Пріоритет виявлення (дубльовані ідентифікатори plugin)
OpenClaw виявляє plugin із кількох коренів (bundled, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлені plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним.
OpenClaw виявляє plugin із кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два знайдені plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним.
Пріоритет, від найвищого до найнижчого:
1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.<id>`
2. **Bundled** — plugin, що постачаються з OpenClaw
1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.<id>`
2. **Вбудований** — plugin, які постачаються разом з OpenClaw
3. **Глобальне встановлення** — plugin, встановлені в глобальний корінь plugin OpenClaw
4. **Workspace** — plugin, виявлені відносно поточного workspace
Наслідки:
- Розгалужена або застаріла копія bundled plugin, що лежить у workspace, не замінить bundled-збірку.
- Щоб справді перевизначити bundled plugin локальним, закріпіть його через `plugins.entries.<id>`, щоб він переміг за пріоритетом, а не покладався на виявлення в workspace.
- Відкидання дублікатів журналюється, щоб Doctor і діагностика під час запуску могли вказати на відкинуту копію.
- Форк або застаріла копія вбудованого plugin, що лежить у workspace, не зможе затінити вбудовану збірку.
- Щоб справді перевизначити вбудований plugin локальним, закріпіть його через `plugins.entries.<id>`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення у workspace.
- Відкидання дублікатів логуються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
## Вимоги до JSON Schema
- **Кожен plugin має постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію.
- Порожня schema припустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
- Schemas проходять валідацію під час читання/запису конфігурації, а не під час виконання.
- **Кожен plugin повинен містити JSON Schema**, навіть якщо він не приймає конфігурацію.
- Порожня схема допустима (наприклад, `{ "type": "object", "additionalProperties": false }`).
- Схеми проходять валідацію під час читання/запису конфігурації, а не під час runtime.
## Поведінка валідації
- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошено
маніфестом plugin.
- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор channel не оголошений
у маніфесті plugin.
- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny` і `plugins.slots.*`
мають посилатися на **виявлювані** id plugin. Невідомі id є **помилками**.
- Якщо plugin встановлено, але має зламаний або відсутній маніфест чи schema,
мають посилатися на **виявлювані** ідентифікатори plugin. Невідомі ідентифікатори є **помилками**.
- Якщо plugin встановлено, але він має зламаний або відсутній маніфест чи schema,
валідація завершується помилкою, а Doctor повідомляє про помилку plugin.
- Якщо конфігурація plugin існує, але plugin **вимкнений**, конфігурація зберігається, і
в Doctor + журналах з’являється **попередження**.
- Якщо конфігурація plugin існує, але plugin **вимкнено**, конфігурація зберігається, і
в Doctor + логах з’являється **попередження**.
Повну schema `plugins.*` див. у [Довіднику з конфігурації](/uk/gateway/configuration).
Повну схему `plugins.*` дивіться в [Довіднику з конфігурації](/uk/gateway/configuration).
## Примітки
- Маніфест **обов’язковий для власних Plugin OpenClaw**, включно із завантаженням із локальної файлової системи.
- Середовище виконання все одно окремо завантажує модуль plugin; маніфест призначений лише для
- Маніфест є **обов’язковим для власних plugin OpenClaw**, зокрема для локальних завантажень із файлової системи.
- Runtime все одно завантажує модуль plugin окремо; маніфест використовується лише для
виявлення + валідації.
- Власні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та
ключі без лапок допускаються, якщо фінальне значення все ще є об’єктом.
- Завантажувач маніфесту зчитує лише документовані поля маніфесту. Уникайте додавання
тут користувацьких ключів верхнього рівня.
- Власні маніфести парсяться за допомогою JSON5, тому коментарі, кінцеві коми та
ключі без лапок дозволені, якщо підсумкове значення все ще є об’єктом.
- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте додавання
тут власних ключів верхнього рівня.
- `providerAuthEnvVars` — це недорогий шлях метаданих для перевірок автентифікації, валідації
env-marker і подібних поверхонь автентифікації provider, які не повинні запускати
середовище виконання plugin лише для перевірки назв env.
- `providerAuthAliases` дозволяє варіантам provider повторно використовувати env vars автентифікації,
профілі автентифікації, автентифікацію через конфігурацію та варіант онбордингу з API key
іншого provider без жорсткого кодування цього зв’язку в ядрі.
- `providerEndpoints` дозволяє plugin provider володіти простими метаданими
зіставлення хоста/baseUrl кінцевих точок. Використовуйте це лише для класів кінцевих точок, які ядро вже підтримує;
фактична поведінка середовища виконання все одно належить plugin.
- `syntheticAuthRefs` — це недорогий шлях метаданих для synthetic auth hook, що належать provider,
які мають бути видимими для холодного виявлення моделей до існування реєстру
середовища виконання. Перелічуйте лише ті refs, чий provider середовища виконання або CLI backend
- `providerAuthAliases` дозволяє варіантам provider повторно використовувати env vars
автентифікації, профілі автентифікації, автентифікацію на основі конфігурації та варіант
онбордингу API key іншого provider без жорсткого кодування цього зв’язку в ядрі.
- `providerEndpoints` дозволяє plugin provider володіти простими метаданими зіставлення
хостів endpoint/baseUrl. Використовуйте це лише для класів endpoint, які ядро вже підтримує;
поведінка runtime все одно належить plugin.
- `syntheticAuthRefs` — це недорогий шлях метаданих для синтетичних hook автентифікації,
що належать provider і мають бути видимі для холодного виявлення моделей до появи
реєстру runtime. Перелічуйте лише ті посилання, чий runtime provider або backend CLI
справді реалізує `resolveSyntheticAuth`.
- `nonSecretAuthMarkers` — це недорогий шлях метаданих для значень-заповнювачів API key,
що належать bundled plugin, наприклад для локальних, OAuth або ambient credential marker.
Ядро трактує їх як не-секрети для відображення автентифікації та аудиту секретів без
що належать вбудованому plugin, як-от маркери локальних, OAuth або середовищних облікових даних.
Ядро трактує їх як не секретні для відображення автентифікації та аудитів секретів без
жорсткого кодування provider-власника.
- `channelEnvVars` — це недорогий шлях метаданих для shell-env fallback, підказок
налаштування та подібних поверхонь каналу, які не повинні запускати середовище виконання plugin
лише для перевірки назв env. Назви env — це метадані, а не активація самі по
собі: статус, аудит, валідація доставки Cron лише для читання та інші
поверхні все одно застосовують політику довіри до plugin та ефективної активації, перш ніж
розглядати env var як налаштований канал.
- `channelEnvVars` — це недорогий шлях метаданих для shell-env fallback, підказок setup
та подібних поверхонь channel, які не повинні запускати середовище виконання plugin
лише для перевірки назв env. Назви env — це метадані, а не активація
самі по собі: status, audit, валідація доставки Cron та інші поверхні
лише для читання все одно застосовують політику довіри plugin і ефективної активації, перш ніж
трактувати env var як налаштований channel.
- `providerAuthChoices` — це недорогий шлях метаданих для засобів вибору варіантів автентифікації,
визначення `--auth-choice`, зіставлення preferred-provider і простої реєстрації
CLI flag для онбордингу до завантаження середовища виконання provider. Для метаданих runtime wizard,
що потребують коду provider, див.
[Runtime hooks provider](/uk/plugins/architecture#provider-runtime-hooks).
- Виключні типи plugin вибираються через `plugins.slots.*`.
визначення `--auth-choice`, мапінгу бажаного provider і простої реєстрації
прапорців CLI для онбордингу до завантаження середовища виконання provider. Для метаданих
runtime wizard, які потребують коду provider, дивіться
[hook середовища виконання Provider](/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` можна пропустити, якщо
plugin вони не потрібні.
- Якщо ваш plugin залежить від власних модулів, задокументуйте кроки збірки та всі
- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо
plugin їх не потребує.
- Якщо ваш plugin залежить від нативних модулів, задокументуйте кроки збірки та всі
вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts`
- `pnpm rebuild <package>`).
## Пов’язане
- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з plugins
- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з plugin
- [Архітектура Plugin](/uk/plugins/architecture) — внутрішня архітектура
- [Огляд SDK](/uk/plugins/sdk-overview) — довідник по SDK Plugin

557
docs/uk/plugins/sdk-overview.md
View File

@ -1,30 +1,30 @@
---
read_when:
- Вам потрібно знати, з якого підшляху SDK імпортувати
- Потрібно знати, з якого підшляху SDK імпортувати
- Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi
- Ви шукаєте конкретний експорт SDK
sidebarTitle: SDK Overview
summary: Карта імпорту, довідник API реєстрації та архітектура SDK
summary: Карта імпортів, довідник API реєстрації та архітектура SDK
title: Огляд Plugin SDK
x-i18n:
generated_at: "2026-04-22T01:34:41Z"
generated_at: "2026-04-22T07:00:23Z"
model: gpt-5.4
provider: openai
source_hash: 8045c11976bbda6afe3303a0aab08caf0d0a86ebcf1aaaf927943b90cc517673
source_hash: e57019e6f9a7fed7842ac575e025b6db41d125f5fa9d0d1de03923fdb1f6bcc3
source_path: plugins/sdk-overview.md
workflow: 15
---
# Огляд Plugin SDK
Plugin SDK — це типізований контракт між plugin і ядром. Ця сторінка —
довідник щодо **що імпортувати** і **що можна реєструвати**.
Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка є
довідником щодо **що імпортувати** і **що можна реєструвати**.
<Tip>
**Шукаєте практичний посібник?**
**Шукаєте покроковий посібник?**
- Перший plugin? Почніть із [Getting Started](/uk/plugins/building-plugins)
- Channel plugin? Див. [Channel Plugins](/uk/plugins/sdk-channel-plugins)
- Provider plugin? Див. [Provider Plugins](/uk/plugins/sdk-provider-plugins)
- Channel plugin? Дивіться [Channel Plugins](/uk/plugins/sdk-channel-plugins)
- Provider plugin? Дивіться [Provider Plugins](/uk/plugins/sdk-provider-plugins)
</Tip>
## Угода щодо імпорту
@ -37,38 +37,38 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
Кожен підшлях — це невеликий самодостатній модуль. Це забезпечує швидкий
запуск і запобігає проблемам із циклічними залежностями. Для специфічних до channel
запуск і запобігає проблемам із циклічними залежностями. Для специфічних для channel
допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core`
залишайте для ширшої поверхні-парасольки та спільних допоміжних засобів, таких як
залишайте для ширшої поверхні-парасолі та спільних допоміжних засобів, таких як
`buildChannelConfigSchema`.
Не додавайте й не використовуйте зручні шви з назвами provider, такі як
Не додавайте і не використовуйте зручні шви з назвами provider, такі як
`openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`,
`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, або
допоміжні шви з брендуванням channel. Вбудовані plugins мають компонувати загальні
допоміжні шви з брендингом channel. Вбудовані plugins мають компонувати узагальнені
підшляхи SDK у власних barrel-файлах `api.ts` або `runtime-api.ts`, а ядро
має або використовувати ці локальні barrel-файли plugin, або додавати вузький загальний SDK
контракт, коли потреба справді є міжchannel-ною.
має або використовувати ці локальні для plugin barrel-файли, або додавати вузький узагальнений SDK
контракт, коли потреба справді є міжканальною.
Згенерована карта експорту все ще містить невеликий набір допоміжних
швів для вбудованих plugin, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
Згенерована карта експортів усе ще містить невеликий набір допоміжних
швів вбудованих plugins, таких як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`,
`plugin-sdk/zalo`, `plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Ці
підшляхи існують лише для підтримки вбудованих plugins і сумісності; їх
навмисно не включено до загальної таблиці нижче, і вони не є
рекомендованим шляхом імпорту для нових сторонніх plugins.
підшляхи існують лише для супроводу вбудованих plugins і сумісності; вони
навмисно пропущені в загальній таблиці нижче і не є рекомендованим
шляхом імпорту для нових сторонніх plugins.
## Довідник підшляхів
Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список із
понад 200 підшляхів розміщено в `scripts/lib/plugin-sdk-entrypoints.json`.
Найуживаніші підшляхи, згруповані за призначенням. Згенерований повний список
із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`.
Зарезервовані допоміжні підшляхи для вбудованих plugins усе ще з’являються в цьому
згенерованому списку. Розглядайте їх як поверхні деталей реалізації/сумісності,
якщо лише якась сторінка документації явно не просуває один із них як публічний.
Зарезервовані допоміжні підшляхи вбудованих plugins усе ще з’являються в цьому згенерованому списку.
Ставтеся до них як до поверхонь деталей реалізації/сумісності, якщо тільки сторінка документації
явно не позначає одну з них як публічну.
### Вхід plugin
### Точка входу plugin
| Subpath | Key exports |
| Subpath | Ключові експорти |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/plugin-entry` | `definePluginEntry` |
| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
@ -77,306 +77,316 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
<AccordionGroup>
<Accordion title="Підшляхи channel">
| Subpath | Key exports |
| Subpath | Ключові експорти |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/config-schema` | Кореневий експорт Zod-схеми `openclaw.json` (`OpenClawSchema`) |
| `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити allowlist, будівники статусу налаштування |
| `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити allowlist, побудовники статусу налаштування |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | Допоміжні засоби для багатoакаунтної конфігурації/шлюзів дій, допоміжні засоби резервного переходу до облікового запису за замовчуванням |
| `plugin-sdk/account-core` | Допоміжні засоби багатооблікового запису для конфігурації/воріт дій, допоміжні засоби запасного використання облікового запису за замовчуванням |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації account-id |
| `plugin-sdk/account-resolution` | Пошук облікового запису + допоміжні засоби резервного переходу до типового значення |
| `plugin-sdk/account-resolution` | Пошук облікового запису + допоміжні засоби запасного використання значення за замовчуванням |
| `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку облікових записів/дій з обліковими записами |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | Типи схеми конфігурації channel |
| `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із резервною підтримкою контракту вбудованого plugin |
| `plugin-sdk/command-gating` | Вузькі допоміжні засоби шлюзу авторизації команд |
| `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/валідації користувацьких команд Telegram із запасним використанням контракту вбудованого plugin |
| `plugin-sdk/command-gating` | Вузькі допоміжні засоби шлюзування авторизації команд |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації потоку чернеток |
| `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації inbound і побудови envelope |
| `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису й dispatch для inbound |
| `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей |
| `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження outbound media |
| `plugin-sdk/outbound-runtime` | Допоміжні засоби outbound-ідентичності, делегата надсилання та планування payload |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації чернетки потоку |
| `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних даних + побудови envelope |
| `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних відповідей |
| `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення target |
| `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа |
| `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідної ідентичності, делегата надсилання та планування payload |
| `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації poll |
| `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу thread-binding та адаптерів |
| `plugin-sdk/agent-media-payload` | Застарілий будівник agent media payload |
| `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок thread і адаптера |
| `plugin-sdk/agent-media-payload` | Застарілий побудовник медіа-payload агента |
| `plugin-sdk/conversation-runtime` | Допоміжні засоби conversation/thread binding, pairing і configured-binding |
| `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації runtime |
| `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення group-policy у runtime |
| `plugin-sdk/runtime-group-policy` | Допоміжні засоби розв’язання групових політик runtime |
| `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку статусу channel |
| `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації channel |
| `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації channel |
| `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти plugin channel |
| `plugin-sdk/channel-plugin-common` | Спільні prelude-експорти channel plugin |
| `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist |
| `plugin-sdk/group-access` | Спільні допоміжні засоби ухвалення рішень щодо group-access |
| `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для прямого DM |
| `plugin-sdk/interactive-runtime` | Семантичне представлення повідомлень, доставка та застарілі допоміжні засоби інтерактивних відповідей. Див. [Message Presentation](/uk/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | Compatibility barrel для debounce inbound, зіставлення згадок, допоміжних засобів mention-policy та допоміжних засобів envelope |
| `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби mention-policy без ширшої поверхні inbound runtime |
| `plugin-sdk/channel-location` | Допоміжні засоби контексту та форматування розташування channel |
| `plugin-sdk/channel-logging` | Допоміжні засоби логування channel для відкидання inbound і збоїв typing/ack |
| `plugin-sdk/group-access` | Спільні допоміжні засоби ухвалення рішень щодо доступу груп |
| `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для прямих DM |
| `plugin-sdk/interactive-runtime` | Допоміжні засоби семантичного подання повідомлень, доставки та застарілих інтерактивних відповідей. Дивіться [Message Presentation](/uk/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | Barrel сумісності для debounce вхідних даних, зіставлення згадок, допоміжних засобів політики згадок і допоміжних засобів envelope |
| `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби політики згадок без ширшої поверхні runtime вхідних даних |
| `plugin-sdk/channel-location` | Допоміжні засоби контексту й форматування розташування channel |
| `plugin-sdk/channel-logging` | Допоміжні засоби логування channel для відкидання вхідних даних і збоїв typing/ack |
| `plugin-sdk/channel-send-result` | Типи результату відповіді |
| `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями channel, а також застарілі нативні допоміжні засоби schema, збережені для сумісності plugin |
| `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей |
| `plugin-sdk/channel-contract` | Типи контрактів channel |
| `plugin-sdk/channel-actions` | Допоміжні засоби дій із повідомленнями channel, а також застарілі допоміжні засоби нативної схеми, збережені для сумісності plugin |
| `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення target |
| `plugin-sdk/channel-contract` | Типи контракту channel |
| `plugin-sdk/channel-feedback` | Підключення feedback/reaction |
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби secret-contract, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей secret |
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби контракту секретів, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи target секретів |
</Accordion>
<Accordion title="Підшляхи provider">
| Subpath | Key exports |
| Subpath | Ключові експорти |
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локальних/self-hosted provider |
| `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted provider, сумісних з OpenAI |
| `plugin-sdk/cli-backend` | Типові значення CLI backend + константи watchdog |
| `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-key у runtime для provider plugins |
| `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу/запису профілю API-key, такі як `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | Стандартний будівник OAuth auth-result |
| `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локального/self-hosted provider |
| `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted provider, сумісного з OpenAI |
| `plugin-sdk/cli-backend` | Значення за замовчуванням для бекенда CLI + константи watchdog |
| `plugin-sdk/provider-auth-runtime` | Допоміжні засоби runtime для розв’язання API-key для provider plugins |
| `plugin-sdk/provider-auth-api-key` | Допоміжні засоби onboarding/profile-write для API-key, такі як `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | Стандартний побудовник результату auth OAuth |
| `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для provider plugins |
| `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку auth env var для provider |
| `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку env var auth provider |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні будівники replay-policy, допоміжні засоби endpoint provider і допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні побудовники політик replay, допоміжні засоби endpoint provider і допоміжні засоби нормалізації model-id, такі як `normalizeNativeXaiModelId` |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint для provider |
| `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту config/selection для web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування provider для web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби config/credential для web-search для provider, яким не потрібне підключення enable plugin |
| `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту config/credential для web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і setter/getter облікових даних з обмеженою областю дії |
| `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime provider для web-search |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика, а також допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-http` | Узагальнені допоміжні засоби HTTP/можливостей endpoint provider |
| `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешу provider web-fetch |
| `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для provider, яким не потрібне підключення enable plugin |
| `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter облікових даних |
| `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешу/runtime provider web-search |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток stream і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Нативні допоміжні засоби transport для provider, такі як guarded fetch, трансформації transport message і writable потоки transport event |
| `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток stream і спільні допоміжні засоби обгорток для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot |
| `plugin-sdk/provider-transport-runtime` | Допоміжні засоби нативного транспорту provider, такі як guarded fetch, перетворення транспортних повідомлень і потоки подій транспорту з можливістю запису |
| `plugin-sdk/provider-onboard` | Допоміжні засоби виправлення конфігурації onboarding |
| `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache |
</Accordion>
<Accordion title="Підшляхи auth і безпеки">
| Subpath | Key exports |
| Subpath | Ключові експорти |
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, допоміжні засоби авторизації відправника |
| `plugin-sdk/command-status` | Будівники повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення approver і auth дій у межах того самого чату |
| `plugin-sdk/command-status` | Побудовники повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | Допоміжні засоби розв’язання approver і auth дій у тому самому chat |
| `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра native exec approval |
| `plugin-sdk/approval-delivery-runtime` | Адаптери native approval capability/delivery |
| `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення approval Gateway |
| `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження native approval adapter для гарячих entrypoint channel |
| `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби approval handler runtime; віддавайте перевагу вужчим швам adapter/gateway, коли їх достатньо |
| `plugin-sdk/approval-native-runtime` | Допоміжні засоби native approval target + account-binding |
| `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді для exec/plugin approval |
| `plugin-sdk/command-auth-native` | Native command auth + допоміжні засоби native session-target |
| `plugin-sdk/approval-delivery-runtime` | Адаптери можливостей/доставки native approval |
| `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб розв’язання gateway approval |
| `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження адаптера native approval для гарячих точок входу channel |
| `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime для обробника approval; віддавайте перевагу вужчим швам adapter/gateway, коли їх достатньо |
| `plugin-sdk/approval-native-runtime` | Допоміжні засоби target native approval + прив’язки облікового запису |
| `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді на exec/plugin approval |
| `plugin-sdk/command-auth-native` | Native command auth + допоміжні засоби target native session |
| `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд |
| `plugin-sdk/command-surface` | Допоміжні засоби нормалізації command-body і command-surface |
| `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команди та surface команди |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збору secret-contract для поверхонь secret channel/plugin |
| `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для парсингу secret-contract/config |
| `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, шлюзування DM, зовнішнього контенту та збору secret |
| `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж |
| `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні infra runtime |
| `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF і політики SSRF |
| `plugin-sdk/secret-input` | Допоміжні засоби парсингу secret input |
| `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів/цілей Webhook |
| `plugin-sdk/webhook-request-guards` | Допоміжні засоби для розміру body/timeout запиту |
| `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання secret-contract для поверхонь secret channel/plugin |
| `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби типізації `coerceSecretRef` і SecretRef для розбору secret-contract/config |
| `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, DM gating, зовнішнього вмісту та збирання секретів |
| `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватної мережі |
| `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні runtime інфраструктури |
| `plugin-sdk/ssrf-runtime` | Pinned-dispatcher, fetch із захистом SSRF і допоміжні засоби політики SSRF |
| `plugin-sdk/secret-input` | Допоміжні засоби розбору secret input |
| `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/target Webhook |
| `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту/тайм-ауту |
</Accordion>
<Accordion title="Підшляхи runtime і сховища">
| Subpath | Key exports |
| Subpath | Ключові експорти |
| --- | --- |
| `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/logging/backup/встановлення plugin |
| `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env runtime, logger, timeout, retry і backoff |
| `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку runtime-context channel |
| `plugin-sdk/runtime-env` | Вузькі допоміжні засоби середовища runtime, logger, timeout, retry і backoff |
| `plugin-sdk/channel-runtime-context` | Узагальнені допоміжні засоби реєстрації та пошуку runtime-context channel |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/hook/http/interactive для plugin |
| `plugin-sdk/hook-runtime` | Спільні допоміжні засоби pipeline для Webhook/внутрішніх hook |
| `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy import/binding runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
| `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/hook/http/interactive plugin |
| `plugin-sdk/hook-runtime` | Спільні допоміжні засоби конвеєра Webhook/внутрішніх hook |
| `plugin-sdk/lazy-runtime` | Допоміжні засоби lazy імпорту/прив’язки runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` |
| `plugin-sdk/process-runtime` | Допоміжні засоби exec процесів |
| `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування та версій |
| `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта Gateway і patch статусу channel |
| `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування та версії |
| `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта Gateway і виправлення статусу channel |
| `plugin-sdk/config-runtime` | Допоміжні засоби завантаження/запису config |
| `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня контракту вбудованого Telegram недоступна |
| `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації назви/опису команди Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня контракту вбудованого Telegram недоступна |
| `plugin-sdk/text-autolink-runtime` | Виявлення автопосилань на файлові посилання без широкого barrel `text-runtime` |
| `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, будівники approval capability, допоміжні засоби auth/profile, native routing/runtime helpers |
| `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime для inbound/reply, чанкування, dispatch, Heartbeat, planner відповіді |
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize для відповіді |
| `plugin-sdk/reply-history` | Спільні допоміжні засоби історії відповідей для короткого вікна, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/approval-runtime` | Допоміжні засоби exec/plugin approval, побудовники можливостей approval, допоміжні засоби auth/profile, native routing/runtime |
| `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime для вхідних даних/відповідей, chunking, dispatch, Heartbeat, planner відповіді |
| `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповіді |
| `plugin-sdk/reply-history` | Спільні допоміжні засоби коротковіконної історії відповідей, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби чанкування text/markdown |
| `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху до session store + `updated-at` |
| `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown |
| `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху сховища session + `updated-at` |
| `plugin-sdk/state-paths` | Допоміжні засоби шляхів до каталогів state/OAuth |
| `plugin-sdk/routing` | Допоміжні засоби route/session-key/account binding, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку статусу channel/account, типові значення runtime-state і допоміжні засоби метаданих проблем |
| `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби resolver цілей |
| `plugin-sdk/routing` | Допоміжні засоби route/session-key/прив’язки облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | Спільні допоміжні засоби зведення статусу channel/account, значення runtime-state за замовчуванням і допоміжні засоби метаданих issue |
| `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби розв’язання target |
| `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків |
| `plugin-sdk/request-url` | Витягування рядкових URL з fetch/request-подібних входів |
| `plugin-sdk/run-command` | Runner команд із таймуванням і нормалізованими результатами stdout/stderr |
| `plugin-sdk/param-readers` | Загальні читачі параметрів tool/CLI |
| `plugin-sdk/tool-payload` | Витягування нормалізованих payload з об’єктів результатів tool |
| `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів tool |
| `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів для тимчасових завантажень |
| `plugin-sdk/logging-core` | Допоміжні засоби логера підсистем і редагування чутливих даних |
| `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму Markdown-таблиць |
| `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису JSON state |
| `plugin-sdk/request-url` | Витягування рядкових URL із fetch/request-подібних вхідних даних |
| `plugin-sdk/run-command` | Запускач команд із таймінгом і нормалізованими результатами stdout/stderr |
| `plugin-sdk/param-readers` | Поширені читачі параметрів tool/CLI |
| `plugin-sdk/tool-payload` | Витягування нормалізованих payload із об’єктів результатів tool |
| `plugin-sdk/tool-send` | Витягування канонічних полів target надсилання з аргументів tool |
| `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів до тимчасових завантажень |
| `plugin-sdk/logging-core` | Допоміжні засоби logger підсистеми та редагування |
| `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму таблиць Markdown |
| `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON |
| `plugin-sdk/file-lock` | Допоміжні засоби повторно вхідного file-lock |
| `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу dedupe з дисковим збереженням |
| `plugin-sdk/acp-runtime` | Допоміжні засоби ACP runtime/session і dispatch відповіді |
| `plugin-sdk/acp-binding-resolve-runtime` | Визначення ACP binding лише для читання без імпортів запуску життєвого циклу |
| `plugin-sdk/agent-config-primitives` | Вузькі примітиви schema config runtime для agent |
| `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу dedupe з бекінгом на диску |
| `plugin-sdk/acp-runtime` | Допоміжні засоби runtime/session ACP і dispatch відповідей |
| `plugin-sdk/acp-binding-resolve-runtime` | Лише читання для розв’язання прив’язок ACP без імпортів запуску життєвого циклу |
| `plugin-sdk/agent-config-primitives` | Вузькі примітиви config-schema runtime агента |
| `plugin-sdk/boolean-param` | Нестрогий читач boolean-параметрів |
| `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів небезпечних назв |
| `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та pairing token |
| `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби розв’язання збігів небезпечних назв |
| `plugin-sdk/device-bootstrap` | Допоміжні засоби початкового запуску пристрою та токенів pairing |
| `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy |
| `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді для команди `/models`/provider |
| `plugin-sdk/skill-commands-runtime` | Допоміжні засоби лістингу команд Skills |
| `plugin-sdk/models-provider-runtime` | Допоміжні засоби відповіді command/provider для `/models` |
| `plugin-sdk/skill-commands-runtime` | Допоміжні засоби переліку команд Skill |
| `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/build/serialize native command |
| `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness agent: типи harness, допоміжні засоби steer/abort для active-run, допоміжні засоби мосту tool OpenClaw і утиліти результатів attempt |
| `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.A.I |
| `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness агента: типи harness, допоміжні засоби steer/abort активного запуску, міст інструментів OpenClaw і утиліти результатів спроб |
| `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI |
| `plugin-sdk/infra-runtime` | Допоміжні засоби системних подій/Heartbeat |
| `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу |
| `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців і подій |
| `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні допоміжні засоби класифікації помилок, `isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch, proxy і pinned lookup |
| `plugin-sdk/runtime-fetch` | Dispatcher-aware runtime fetch без імпортів proxy/guarded-fetch |
| `plugin-sdk/response-limit-runtime` | Читач body відповіді з обмеженням без широкої поверхні media runtime |
| `plugin-sdk/session-binding-runtime` | Поточний стан binding розмови без configured binding routing або pairing store |
| `plugin-sdk/fetch-runtime` | Обгорнутий fetch, proxy і допоміжні засоби pinned lookup |
| `plugin-sdk/runtime-fetch` | Runtime fetch з урахуванням dispatcher без імпортів proxy/guarded-fetch |
| `plugin-sdk/response-limit-runtime` | Читач тіла відповіді з обмеженням без широкої поверхні runtime медіа |
| `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки conversation без routing configured binding або сховищ pairing |
| `plugin-sdk/session-store-runtime` | Допоміжні засоби читання session-store без широких імпортів запису/обслуговування config |
| `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту та фільтрація додаткового контексту без широких імпортів config/security |
| `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення та нормалізації primitive record/string без імпортів markdown/logging |
| `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації імен хостів і хостів SCP |
| `plugin-sdk/retry-runtime` | Допоміжні засоби config retry і runner retry |
| `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/workspace для agent |
| `plugin-sdk/directory-runtime` | Запит/dedup каталогів на основі config |
| `plugin-sdk/context-visibility-runtime` | Розв’язання видимості контексту та фільтрація додаткового контексту без широких імпортів config/security |
| `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення й нормалізації примітивних record/рядків без імпортів markdown/logging |
| `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і хоста SCP |
| `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і запуску retry |
| `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/workspace агента |
| `plugin-sdk/directory-runtime` | Запит/усунення дублікатів каталогів із бекінгом на config |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
<Accordion title="Підшляхи можливостей і тестування">
| Subpath | Key exports |
| Subpath | Ключові експорти |
| --- | --- |
| `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для media, а також будівники media payload |
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover для генерації media, вибір кандидатів і повідомлення про відсутню model |
| `plugin-sdk/media-understanding` | Типи provider для розуміння media, а також provider-oriented експорти допоміжних засобів для зображень/аудіо |
| `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як видалення тексту, видимого assistant, допоміжні засоби рендерингу/чанкування/таблиць markdown, редагування чутливих даних, допоміжні засоби тегів directive і утиліти безпечного text |
| `plugin-sdk/text-chunking` | Допоміжний засіб чанкування outbound text |
| `plugin-sdk/speech` | Типи provider для мовлення, а також provider-oriented допоміжні засоби directive, registry і validation |
| `plugin-sdk/speech-core` | Спільні типи provider для мовлення, а також допоміжні засоби registry, directive і normalization |
| `plugin-sdk/realtime-transcription` | Типи provider для транскрипції в реальному часі та допоміжні засоби registry |
| `plugin-sdk/realtime-voice` | Типи provider для голосу в реальному часі та допоміжні засоби registry |
| `plugin-sdk/image-generation` | Типи provider для генерації зображень |
| `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, а також допоміжні засоби failover, auth і registry |
| `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store медіа, а також побудовники payload медіа |
| `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover медіагенерації, вибору кандидатів і повідомлень про відсутню модель |
| `plugin-sdk/media-understanding` | Типи provider media understanding, а також орієнтовані на provider експорти допоміжних засобів для зображень/аудіо |
| `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як видалення тексту, видимого асистенту, допоміжні засоби render/chunking/table для markdown, допоміжні засоби редагування, допоміжні засоби тегів директив і утиліти безпечного тексту |
| `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту |
| `plugin-sdk/speech` | Типи speech provider, а також орієнтовані на provider допоміжні засоби директив, реєстру та валідації |
| `plugin-sdk/speech-core` | Спільні допоміжні засоби типів, реєстру, директив і нормалізації для speech provider |
| `plugin-sdk/realtime-transcription` | Типи provider транскрибування в реальному часі та допоміжні засоби реєстру |
| `plugin-sdk/realtime-voice` | Типи provider голосу в реальному часі та допоміжні засоби реєстру |
| `plugin-sdk/image-generation` | Типи provider генерації зображень |
| `plugin-sdk/image-generation-core` | Спільні допоміжні засоби типів, failover, auth і реєстру для генерації зображень |
| `plugin-sdk/music-generation` | Типи provider/request/result для генерації музики |
| `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, lookup provider і парсинг model-ref |
| `plugin-sdk/music-generation-core` | Спільні допоміжні засоби типів генерації музики, failover, пошуку provider і розбору model-ref |
| `plugin-sdk/video-generation` | Типи provider/request/result для генерації відео |
| `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, lookup provider і парсинг model-ref |
| `plugin-sdk/webhook-targets` | Допоміжні засоби реєстру цілей Webhook і встановлення маршрутів |
| `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляхів Webhook |
| `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних media |
| `plugin-sdk/zod` | Повторно експортований `zod` для споживачів Plugin SDK |
| `plugin-sdk/video-generation-core` | Спільні допоміжні засоби типів генерації відео, failover, пошуку provider і розбору model-ref |
| `plugin-sdk/webhook-targets` | Допоміжні засоби реєстру target Webhook і встановлення route |
| `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook |
| `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа |
| `plugin-sdk/zod` | Повторно експортований `zod` для користувачів plugin SDK |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
</Accordion>
<Accordion title="Підшляхи Memory">
| Subpath | Key exports |
| Subpath | Ключові експорти |
| --- | --- |
| `plugin-sdk/memory-core` | Поверхня допоміжних засобів вбудованого `memory-core` для manager/config/file/CLI |
| `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled `memory-core` для допоміжних засобів manager/config/file/CLI |
| `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексації/пошуку Memory |
| `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста Memory |
| `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста Memory, доступ до registry, локальний provider і загальні допоміжні засоби batch/remote |
| `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста Memory, доступ до реєстру, локальний provider і узагальнені пакетні/віддалені допоміжні засоби |
| `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста Memory |
| `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста Memory |
| `plugin-sdk/memory-core-host-multimodal` | Мультимодальні допоміжні засоби хоста Memory |
| `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста Memory |
| `plugin-sdk/memory-core-host-secret` | Допоміжні засоби secret хоста Memory |
| `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста Memory |
| `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста Memory |
| `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста Memory |
| `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби CLI runtime хоста Memory |
| `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста Memory |
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби file/runtime хоста Memory |
| `plugin-sdk/memory-host-core` | Нейтральний до постачальника псевдонім для допоміжних засобів core runtime хоста Memory |
| `plugin-sdk/memory-host-events` | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій хоста Memory |
| `plugin-sdk/memory-host-files` | Нейтральний до постачальника псевдонім для допоміжних засобів file/runtime хоста Memory |
| `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста Memory |
| `plugin-sdk/memory-host-core` | Вендорно-нейтральний псевдонім для допоміжних засобів core runtime хоста Memory |
| `plugin-sdk/memory-host-events` | Вендорно-нейтральний псевдонім для допоміжних засобів журналу подій хоста Memory |
| `plugin-sdk/memory-host-files` | Вендорно-нейтральний псевдонім для допоміжних засобів файлів/runtime хоста Memory |
| `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для plugins, суміжних із memory |
| `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до менеджера пошуку |
| `plugin-sdk/memory-host-status` | Нейтральний до постачальника псевдонім для допоміжних засобів статусу хоста Memory |
| `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів вбудованого `memory-lancedb` |
| `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до search-manager |
| `plugin-sdk/memory-host-status` | Вендорно-нейтральний псевдонім для допоміжних засобів статусу хоста Memory |
| `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled `memory-lancedb` |
</Accordion>
<Accordion title="Зарезервовані підшляхи вбудованих helper">
| Family | Current subpaths | Intended use |
<Accordion title="Зарезервовані підшляхи bundled-helper">
| Family | Поточні підшляхи | Призначене використання |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки вбудованого browser plugin (`browser-support` залишається compatibility barrel) |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня helper/runtime вбудованого Matrix |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня helper/runtime вбудованого LINE |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня helper вбудованого IRC |
| Допоміжні засоби, специфічні для channel | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжних засобів вбудованих channel |
| Допоміжні засоби, специфічні для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви helper для вбудованих функцій/plugins; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser plugin (`browser-support` залишається barrel сумісності) |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних засобів/runtime bundled Matrix |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime bundled LINE |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів bundled IRC |
| Допоміжні засоби, специфічні для channel | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжні шви bundled channel |
| Допоміжні засоби, специфічні для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних засобів bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>
## API реєстрації
Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими
методами:
### Реєстрація можливостей
| Method | What it registers |
| Method | Що реєструє |
| ------------------------------------------------ | ------------------------------------- |
| `api.registerProvider(...)` | Текстове inference (LLM) |
| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець agent |
| `api.registerCliBackend(...)` | Локальний backend inference CLI |
| `api.registerProvider(...)` | Виведення тексту (LLM) |
| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента |
| `api.registerCliBackend(...)` | Локальний backend виведення CLI |
| `api.registerChannel(...)` | Канал обміну повідомленнями |
| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT |
| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі |
| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі |
| `api.registerRealtimeTranscriptionProvider(...)` | Потокове транскрибування в реальному часі |
| `api.registerRealtimeVoiceProvider(...)` | Двоспрямовані голосові сесії в реальному часі |
| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео |
| `api.registerImageGenerationProvider(...)` | Генерація зображень |
| `api.registerMusicGenerationProvider(...)` | Генерація музики |
| `api.registerVideoGenerationProvider(...)` | Генерація відео |
| `api.registerWebFetchProvider(...)` | Provider Web fetch / scrape |
| `api.registerWebFetchProvider(...)` | Provider web fetch / scrape |
| `api.registerWebSearchProvider(...)` | Вебпошук |
### Інструменти й команди
| Method | What it registers |
| ------------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | Інструмент agent (обов’язковий або `{ optional: true }`) |
| `api.registerCommand(def)` | Користувацька команда (обходить LLM) |
| Method | Що реєструє |
| ------------------------------- | -------------------------------------------- |
| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) |
| `api.registerCommand(def)` | Користувацька команда (обходить LLM) |
### Інфраструктура
| Method | What it registers |
| ---------------------------------------------- | --------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Hook події |
| `api.registerHttpRoute(params)` | HTTP endpoint Gateway |
| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway |
| `api.registerCli(registrar, opts?)` | Підкоманда CLI |
| `api.registerService(service)` | Фонова служба |
| `api.registerInteractiveHandler(registration)` | Інтерактивний handler |
| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із memory |
| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання memory |
| Method | Що реєструє |
| ----------------------------------------------- | -------------------------------------- |
| `api.registerHook(events, handler, opts?)` | Hook події |
| `api.registerHttpRoute(params)` | HTTP endpoint Gateway |
| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway |
| `api.registerCli(registrar, opts?)` | Підкоманда CLI |
| `api.registerService(service)` | Фонова служба |
| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник |
| `api.registerEmbeddedExtensionFactory(factory)` | Фабрика розширень embedded-runner для Pi |
| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із memory |
| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання memory |
Зарезервовані простори імен адміністратора ядра (`config.*`, `exec.approvals.*`, `wizard.*`,
Зарезервовані простори імен core admin (`config.*`, `exec.approvals.*`, `wizard.*`,
`update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається призначити
вужчу область дії методу Gateway. Для методів, що належать plugin,
вужчу область дії методу gateway. Для методів, що належать plugin,
віддавайте перевагу префіксам, специфічним для plugin.
Використовуйте `api.registerEmbeddedExtensionFactory(...)`, коли plugin потрібен
власний для Pi таймінг подій під час embedded-запусків OpenClaw, наприклад асинхронні
переписування `tool_result`, які мають відбутися до того, як буде виведено
остаточне повідомлення результату інструмента.
Наразі це шов bundled-plugin: лише bundled plugins можуть реєструвати такий factory, і
вони мають оголосити `contracts.embeddedExtensionFactories: ["pi"]` у
`openclaw.plugin.json`. Для всього, що не потребує цього нижчорівневого шва,
залишайте звичайні hook plugin OpenClaw.
### Метадані реєстрації CLI
`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня:
- `commands`: явні корені команд, що належать registrar
- `descriptors`: дескриптори команд на етапі парсингу, які використовуються для кореневої довідки CLI,
- `descriptors`: дескриптори команд на етапі розбору, що використовуються для кореневої довідки CLI,
маршрутизації та lazy-реєстрації CLI plugin
Якщо ви хочете, щоб команда plugin залишалася lazy-loaded у звичайному кореневому шляху CLI,
надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що відкривається цим
registrar.
Якщо ви хочете, щоб команда plugin залишалася lazy-loaded у звичайному шляху кореневого CLI,
надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що експонується
цим registrar.
```typescript
api.registerCli(
@ -397,88 +407,88 @@ api.registerCli(
```
Використовуйте `commands` окремо лише тоді, коли вам не потрібна lazy-реєстрація кореневого CLI.
Цей eager-сумісний шлях і надалі підтримується, але він не встановлює
плейсхолдери на основі descriptor для lazy-loading під час парсингу.
Цей eager-шлях сумісності залишається підтримуваним, але він не встановлює
плейсхолдери на основі descriptor для lazy loading на етапі розбору.
### Реєстрація backend CLI
`api.registerCliBackend(...)` дозволяє plugin володіти типовою config для локального
backend CLI AI, такого як `codex-cli`.
`api.registerCliBackend(...)` дає plugin змогу володіти конфігурацією за замовчуванням для локального
AI CLI backend, такого як `codex-cli`.
- `id` backend стає префіксом provider у model ref, як-от `codex-cli/gpt-5`.
- `id` backend стає префіксом provider у посиланнях на моделі, таких як `codex-cli/gpt-5`.
- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.<id>`.
- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.<id>` поверх
типового значення plugin перед запуском CLI.
- Використовуйте `normalizeConfig`, коли backend потребує переписувань сумісності після злиття
(наприклад, для нормалізації старих форм flags).
- Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.<id>` поверх
значення за замовчуванням plugin перед запуском CLI.
- Використовуйте `normalizeConfig`, коли backend потребує переписувань сумісності після об’єднання
(наприклад, нормалізації старих форм прапорців).
### Ексклюзивні слоти
| Method | What it registers |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Механізм контексту (одночасно активний лише один). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб механізм міг адаптувати доповнення до prompt. |
| `api.registerMemoryCapability(capability)` | Єдина можливість memory |
| `api.registerMemoryPromptSection(builder)` | Будівник розділу prompt для memory |
| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush для memory |
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime для memory |
| Method | Що реєструє |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | Context engine (одночасно активний лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб engine міг налаштувати доповнення prompt. |
| `api.registerMemoryCapability(capability)` | Уніфіковану можливість memory |
| `api.registerMemoryPromptSection(builder)` | Побудовник розділу prompt для memory |
| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush для memory |
| `api.registerMemoryRuntime(runtime)` | Адаптер runtime для memory |
### Адаптери embedding для memory
| Method | What it registers |
| Method | Що реєструє |
| ---------------------------------------------- | ---------------------------------------------- |
| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для memory для активного plugin |
- `registerMemoryCapability` — це рекомендований API ексклюзивного plugin memory.
- `registerMemoryCapability` також може відкривати `publicArtifacts.listArtifacts(...)`,
щоб супутні plugins могли споживати експортовані артефакти memory через
- `registerMemoryCapability` — це рекомендований API ексклюзивного plugin для memory.
- `registerMemoryCapability` також може експонувати `publicArtifacts.listArtifacts(...)`,
щоб plugins-компаньйони могли споживати експортовані артефакти memory через
`openclaw/plugin-sdk/memory-host-core` замість звернення до приватного
компонування конкретного plugin memory.
layout конкретного plugin memory.
- `registerMemoryPromptSection`, `registerMemoryFlushPlan` і
`registerMemoryRuntime` — це застаріло-сумісні API ексклюзивного plugin memory.
- `registerMemoryEmbeddingProvider` дозволяє активному plugin memory реєструвати один
або кілька id адаптерів embedding (наприклад, `openai`, `gemini` або користувацький
id, визначений plugin).
`registerMemoryRuntime` — це застарілі, але сумісні API ексклюзивного plugin для memory.
- `registerMemoryEmbeddingProvider` дає активному plugin memory змогу зареєструвати один
або кілька id адаптерів embedding (наприклад, `openai`, `gemini` або користувацький id,
визначений plugin).
- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і
`agents.defaults.memorySearch.fallback`, визначається відносно цих зареєстрованих
`agents.defaults.memorySearch.fallback`, розв’язується відносно цих зареєстрованих
id адаптерів.
### Події та життєвий цикл
| Method | What it does |
| -------------------------------------------- | ----------------------------- |
| `api.on(hookName, handler, opts?)` | Типізований lifecycle hook |
| `api.onConversationBindingResolved(handler)` | Зворотний виклик binding розмови |
| Method | Що робить |
| -------------------------------------------- | ---------------------------- |
| `api.on(hookName, handler, opts?)` | Типізований hook життєвого циклу |
| `api.onConversationBindingResolved(handler)` | Колбек розв’язання прив’язки conversation |
### Семантика рішень hook
- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и з нижчим пріоритетом пропускаються.
- `before_tool_call`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропуск `block`), а не як перевизначення.
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и з нижчим пріоритетом пропускаються.
- `before_install`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як і пропуск `block`), а не як перевизначення.
- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який handler бере на себе dispatch, handler-и з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються.
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и з нижчим пріоритетом пропускаються.
- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як і пропуск `cancel`), а не як перевизначення.
- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
- `before_tool_call`: повернення `{ block: false }` трактується як відсутність рішення (так само, як і пропуск `block`), а не як перевизначення.
- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
- `before_install`: повернення `{ block: false }` трактується як відсутність рішення (так само, як і пропуск `block`), а не як перевизначення.
- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник перехоплює dispatch, обробники з нижчим пріоритетом і стандартний шлях dispatch моделі пропускаються.
- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються.
- `message_sending`: повернення `{ cancel: false }` трактується як відсутність рішення (так само, як і пропуск `cancel`), а не як перевизначення.
### Поля об’єкта API
| Field | Type | Description |
| Field | Type | Опис |
| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- |
| `api.id` | `string` | Ідентифікатор plugin |
| `api.id` | `string` | ID plugin |
| `api.name` | `string` | Відображувана назва |
| `api.version` | `string?` | Версія plugin (необов’язково) |
| `api.description` | `string?` | Опис plugin (необов’язково) |
| `api.source` | `string` | Шлях до джерела plugin |
| `api.rootDir` | `string?` | Кореневий каталог plugin (необов’язково) |
| `api.config` | `OpenClawConfig` | Поточний знімок config (активний знімок runtime в пам’яті, коли доступний) |
| `api.config` | `OpenClawConfig` | Поточний знімок config (активний внутрішньопам’ятний знімок runtime, коли доступний) |
| `api.pluginConfig` | `Record<string, unknown>` | Конфігурація, специфічна для plugin, з `plugins.entries.<id>.config` |
| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | Logger з областю дії (`debug`, `info`, `warn`, `error`) |
| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) |
| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного entry |
| `api.resolvePath(input)` | `(string) => string` | Визначити шлях відносно кореня plugin |
| `api.resolvePath(input)` | `(string) => string` | Розв’язати шлях відносно кореня plugin |
## Угода щодо внутрішніх модулів
У межах вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів:
Усередині вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів:
```
my-plugin/
@ -490,40 +500,41 @@ my-plugin/
<Warning>
Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/<your-plugin>`
у production code. Спрямовуйте внутрішні імпорти через `./api.ts` або
у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або
`./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт.
</Warning>
Публічні поверхні вбудованих plugins, завантажувані через фасад (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), тепер віддають перевагу
активному знімку config runtime, коли OpenClaw уже працює. Якщо знімок runtime
ще не існує, вони повертаються до визначеного файла config на диску.
Завантажувані через facade публічні поверхні bundled plugin (`api.ts`, `runtime-api.ts`,
`index.ts`, `setup-entry.ts` та подібні публічні entry-файли) тепер віддають перевагу
активному знімку config runtime, коли OpenClaw уже запущено. Якщо знімок runtime
ще не існує, вони повертаються до розв’язаного config-файлу на диску.
Plugins provider також можуть відкривати вузький локальний barrel контракту plugin, коли
допоміжний засіб навмисно є специфічним для provider і ще не належить до загального підшляху SDK.
Поточний вбудований приклад: provider Anthropic зберігає свої допоміжні засоби потоку Claude
у власному публічному шві `api.ts` / `contract-api.ts` замість просування логіки
beta-header Anthropic і `service_tier` до загального контракту `plugin-sdk/*`.
Plugins provider також можуть експонувати вузький локальний для plugin barrel контракту, коли
допоміжний засіб навмисно є специфічним для provider і ще не належить до узагальненого
підшляху SDK. Поточний bundled-приклад: provider Anthropic тримає свої
допоміжні засоби потоку Claude у власному публічному шві `api.ts` / `contract-api.ts` замість
просування логіки Anthropic beta-header і `service_tier` в узагальнений
контракт `plugin-sdk/*`.
Інші поточні вбудовані приклади:
Інші поточні bundled-приклади:
- `@openclaw/openai-provider`: `api.ts` експортує будівники provider,
допоміжні засоби типових моделей і будівники provider для реального часу
- `@openclaw/openrouter-provider`: `api.ts` експортує будівник provider, а також
допоміжні засоби онбордингу/config
- `@openclaw/openai-provider`: `api.ts` експортує побудовники provider,
допоміжні засоби моделей за замовчуванням і побудовники provider реального часу
- `@openclaw/openrouter-provider`: `api.ts` експортує побудовник provider, а також
допоміжні засоби onboarding/config
<Warning>
Production code extension також має уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
Production-код extension також має уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
Якщо допоміжний засіб справді є спільним, перенесіть його до нейтрального підшляху SDK,
такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
поверхні, орієнтованої на можливості, замість зв’язування двох plugins між собою.
поверхні, орієнтованої на можливості, замість жорсткого зв’язування двох plugins.
</Warning>
## Пов’язані матеріали
## Пов’язане
- [Entry Points](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` і `defineChannelPluginEntry`
- [Runtime Helpers](/uk/plugins/sdk-runtime) — повний довідник простору імен `api.runtime`
- [Setup and Config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми config
- [Testing](/uk/plugins/sdk-testing) — утиліти тестування та правила lint
- [SDK Migration](/uk/plugins/sdk-migration) — міграція із застарілих поверхонь
- [Plugin Internals](/uk/plugins/architecture) — поглиблена архітектура та модель можливостей plugin
- [Точки входу](/uk/plugins/sdk-entrypoints) — параметри `definePluginEntry` і `defineChannelPluginEntry`
- [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) — повний довідник простору імен `api.runtime`
- [Налаштування та config](/uk/plugins/sdk-setup) — пакування, маніфести, схеми config
- [Тестування](/uk/plugins/sdk-testing) — тестові утиліти та правила lint
- [Міграція SDK](/uk/plugins/sdk-migration) — міграція із застарілих поверхонь
- [Внутрішня будова plugin](/uk/plugins/architecture) — глибока архітектура та модель можливостей