diff --git a/docs/uk/plugins/building-plugins.md b/docs/uk/plugins/building-plugins.md index 0bb4bc371..b666d1650 100644 --- a/docs/uk/plugins/building-plugins.md +++ b/docs/uk/plugins/building-plugins.md @@ -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 `. OpenClaw спочатку намагається знайти -його в ClawHub, а потім автоматично переходить до npm. +Вам не потрібно додавати свій Plugin до репозиторію OpenClaw. Опублікуйте його в +[ClawHub](/uk/tools/clawhub) або npm, і користувачі встановлять його за допомогою +`openclaw plugins install `. OpenClaw спочатку намагається використати ClawHub і +автоматично переходить до npm, якщо це потрібно. ## Передумови - Node >= 22 і менеджер пакетів (npm або pnpm) - Знайомство з TypeScript (ESM) -- Для plugin у репозиторії: клонований репозиторій і виконаний `pnpm install` +- Для Plugin-ів у репозиторії: клонований репозиторій і виконаний `pnpm install` -## Який саме plugin? +## Який тип Plugin-а? - Підключіть OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо) + Підключає OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо) - Додайте провайдера моделей (LLM, проксі або користувацьку кінцеву точку) + Додає провайдера моделей (LLM, проксі або власну кінцеву точку) - - Зареєструйте інструменти агента, hooks подій або сервіси — продовжуйте нижче + + Реєструє інструменти агента, хуки подій або сервіси — продовжуйте нижче -Якщо plugin каналу є необов’язковим і може бути не встановлений під час -onboarding/налаштування, використовуйте `createOptionalChannelSetupSurface(...)` з -`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптер налаштування + -майстер, яка повідомляє про вимогу встановлення й безпечно блокує реальний запис -конфігурації, доки plugin не буде встановлено. +Якщо Plugin каналу є необов’язковим і може бути не встановлений під час виконання +онбордингу/налаштування, використовуйте `createOptionalChannelSetupSurface(...)` з +`openclaw/plugin-sdk/channel-setup`. Це створює пару адаптера налаштування та майстра, +яка повідомляє про вимогу встановлення та безпечно відхиляє реальні записи конфігурації, +доки Plugin не буде встановлено. -## Швидкий старт: plugin інструмента +## Швидкий старт: Plugin інструменту -У цьому прикладі створюється мінімальний plugin, який реєструє інструмент -агента. Для plugin каналів і провайдерів є окремі посібники за посиланнями -вище. +У цьому прикладі створюється мінімальний Plugin, який реєструє інструмент агента. Для Plugin-ів +каналів і провайдерів є окремі посібники за посиланнями вище. @@ -94,9 +93,9 @@ onboarding/налаштування, використовуйте `createOptiona ``` - Кожному plugin потрібен маніфест, навіть без конфігурації. Повну схему див. - у [Manifest](/uk/plugins/manifest). Канонічні фрагменти для публікації в ClawHub - містяться в `docs/snippets/plugin-publish/`. + Кожному Plugin-у потрібен маніфест, навіть без конфігурації. Повну схему дивіться в + [Manifest](/uk/plugins/manifest). Канонічні фрагменти для публікації в ClawHub + розміщені в `docs/snippets/plugin-publish/`. @@ -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). - + - **Зовнішні 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 -- /my-plugin/ @@ -153,65 +151,65 @@ onboarding/налаштування, використовуйте `createOptiona -## Можливості 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/`: +Завжди імпортуйте з цільових шляхів `openclaw/plugin-sdk/`: ```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-plugin, наприклад -`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Сприймайте їх як -зарезервовані поверхні, а не як типовий шаблон для нових сторонніх plugins. +Деякі згенеровані інтерфейси допоміжних засобів `openclaw/plugin-sdk/` усе ще існують для +підтримки й сумісності вбудованих Plugin-ів, наприклад +`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Розглядайте їх як зарезервовані +поверхні, а не як типовий шаблон для нових сторонніх Plugin-ів. -## Контрольний список перед надсиланням +## Контрольний список перед поданням -**package.json** містить правильні метадані `openclaw` +У **package.json** вказано правильні метадані `openclaw` Маніфест **openclaw.plugin.json** присутній і валідний Точка входу використовує `defineChannelPluginEntry` або `definePluginEntry` -Усі імпорти використовують вузькоспрямовані шляхи `plugin-sdk/` -Внутрішні імпорти використовують локальні модулі, а не self-imports через SDK +Усі імпорти використовують цільові шляхи `plugin-sdk/` +Внутрішні імпорти використовують локальні модулі, а не self-import-и через SDK Тести проходять (`pnpm test -- /my-plugin/`) -`pnpm check` проходить (для plugin у репозиторії) +`pnpm check` проходить (для Plugin-ів у репозиторії) ## Тестування бета-релізів -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: - ` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свою гілку. -5. Відкрийте PR до `main` з назвою `fix(): beta blocker - ` і додайте посилання на 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: - ` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свій тред. +5. Відкрийте PR до `main` з назвою `fix(): beta blocker - ` і додайте посилання на issue і в PR, і у свій Discord-тред. Учасники не можуть додавати мітки до PR, тому назва є сигналом на боці PR для мейнтейнерів та автоматизації. Блокери з PR будуть злиті; блокери без PR можуть усе одно потрапити в реліз. Мейнтейнери стежать за цими тредами під час бета-тестування. +6. Відсутність повідомлень означає, що все гаразд. Якщо ви пропустите це вікно, ваше виправлення, найімовірніше, потрапить до наступного циклу. ## Наступні кроки - Створіть plugin каналу обміну повідомленнями + Створіть Plugin каналу обміну повідомленнями - Створіть plugin провайдера моделей + Створіть Plugin провайдера моделей - Довідник карти імпортів і API реєстрації + Карта імпортів і довідник API реєстрації - TTS, пошук, підлеглий агент через api.runtime + TTS, пошук, subagent через api.runtime - Утиліти та шаблони тестування + Утиліти й шаблони тестування Повний довідник схеми маніфесту @@ -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-ів провайдерів diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 31d66c7ea..7ce9015cf 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -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 ", - "cliDescription": "OpenRouter API key", + "cliDescription": "API key OpenRouter", "onboardingScopes": ["text-inference"] } ], @@ -158,64 +158,64 @@ OpenClaw також автоматично виявляє ці компонув | Поле | Обов’язкове | Тип | Що воно означає | | ------------------------------------ | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | Так | `string` | Канонічний id plugin. Це id, який використовується в `plugins.entries.`. | +| `id` | Так | `string` | Канонічний ідентифікатор plugin. Це ідентифікатор, який використовується в `plugins.entries.`. | | `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` | Недорогі env-метадані автентифікації provider, які OpenClaw може перевіряти без завантаження коду plugin. | -| `providerAuthAliases` | Ні | `Record` | Id provider, які мають повторно використовувати інший id provider для пошуку автентифікації, наприклад coding provider, що ділить API key базового provider і профілі автентифікації. | -| `channelEnvVars` | Ні | `Record` | Недорогі env-метадані каналу, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для керованого через env налаштування каналу або поверхонь автентифікації, які мають бачити загальні помічники запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Недорогі метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення preferred-provider і простого підключення CLI flags. | -| `activation` | Ні | `object` | Недорогі підказки активації для завантаження, що запускається provider, командами, каналами, маршрутами та можливостями. Лише метадані; фактична поведінка все одно належить середовищу виконання plugin. | +| `providerAuthEnvVars` | Ні | `Record` | Недорогі метадані env для автентифікації provider, які OpenClaw може перевіряти без завантаження коду plugin. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори provider, які мають повторно використовувати інший ідентифікатор provider для пошуку автентифікації, наприклад provider для кодування, який ділить API key і профілі автентифікації з базовим provider. | +| `channelEnvVars` | Ні | `Record` | Недорогі метадані 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` | Недорогі типові значення media-understanding для id provider, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту та об’єднуються з поверхнями виявлення й валідації до завантаження середовища виконання. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження відносно кореня plugin. | -| `name` | Ні | `string` | Людинозрозуміла назва plugin. | -| `description` | Ні | `string` | Короткий опис, що показується в поверхнях plugin. | -| `version` | Ні | `string` | Інформаційна версія plugin. | -| `uiHints` | Ні | `Record` | Підписи 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` | Недорогі типові значення media-understanding для ідентифікаторів provider, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації channel, що належать маніфесту, об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня plugin. | +| `name` | Ні | `string` | Зрозуміла людині назва plugin. | +| `description` | Ні | `string` | Короткий підсумок, що показується в поверхнях plugin. | +| `version` | Ні | `string` | Інформаційна версія plugin. | +| `uiHints` | Ні | `Record` | Мітки 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 `. | -| `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 `. | +| `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` | Типові значення відповідності можливість-модель, які використовуються, коли конфігурація не задає модель. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору provider на основі credential. | -| `nativeDocumentInputs` | `"pdf"[]` | Вбудовані формати документів, які підтримує provider. | +| Поле | Тип | Що воно означає | +| ---------------------- | ----------------------------------- | --------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості медіа, які надає цей provider. | +| `defaultModels` | `Record` | Типові відповідності можливість-модель, які використовуються, коли конфігурація не вказує модель. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору 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.`. Обов’язкове для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові підписи UI/placeholders/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Підпис каналу, який об’єднується з поверхнями вибору та перегляду, коли метадані середовища виконання ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь перегляду та каталогу. | -| `preferOver` | `string[]` | Id застарілих plugin або plugin з нижчим пріоритетом, які цей канал має випереджати в поверхнях вибору. | +| Поле | Тип | Що воно означає | +| ------------- | ------------------------ | --------------------------------------------------------------------------------------- | +| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації channel. | +| `uiHints` | `Record` | Необов’язкові мітки 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.` для того самого -bundled plugin. Несуміжні помилки конфігурації все одно блокують встановлення й спрямовують операторів +не робить довільно зламані конфігурації придатними до встановлення. Наразі воно лише дозволяє +процесам встановлення відновлюватися після конкретних застарілих збоїв оновлення вбудованих plugin, +наприклад відсутнього шляху до вбудованого plugin або застарілого запису `channels.` для того самого +вбудованого 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.` -2. **Bundled** — plugin, що постачаються з OpenClaw +1. **Вибраний у конфігурації** — шлях, явно закріплений у `plugins.entries.` +2. **Вбудований** — plugin, які постачаються разом з OpenClaw 3. **Глобальне встановлення** — plugin, встановлені в глобальний корінь plugin OpenClaw 4. **Workspace** — plugin, виявлені відносно поточного workspace Наслідки: -- Розгалужена або застаріла копія bundled plugin, що лежить у workspace, не замінить bundled-збірку. -- Щоб справді перевизначити bundled plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладався на виявлення в workspace. -- Відкидання дублікатів журналюється, щоб Doctor і діагностика під час запуску могли вказати на відкинуту копію. +- Форк або застаріла копія вбудованого plugin, що лежить у workspace, не зможе затінити вбудовану збірку. +- Щоб справді перевизначити вбудований plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення у 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.`, `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 `). ## Пов’язане -- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з plugins +- [Створення Plugins](/uk/plugins/building-plugins) — початок роботи з plugin - [Архітектура Plugin](/uk/plugins/architecture) — внутрішня архітектура - [Огляд SDK](/uk/plugins/sdk-overview) — довідник по SDK Plugin diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index d65198215..074ab02f2 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -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 і ядром. Ця сторінка є +довідником щодо **що імпортувати** і **що можна реєструвати**. - **Шукаєте практичний посібник?** + **Шукаєте покроковий посібник?** - Перший 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) ## Угода щодо імпорту @@ -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"; - | 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 секретів | - | 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 | - | 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` | Допоміжні засоби розміру тіла запиту/тайм-ауту | - | 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` | - | 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` | - | 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` | - - | Family | Current subpaths | Intended use | + + | 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` | ## 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.`. -- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.` поверх - типового значення plugin перед запуском CLI. -- Використовуйте `normalizeConfig`, коли backend потребує переписувань сумісності після злиття - (наприклад, для нормалізації старих форм flags). +- Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх + значення за замовчуванням 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` | Конфігурація, специфічна для plugin, з `plugins.entries..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/ Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/` - у production code. Спрямовуйте внутрішні імпорти через `./api.ts` або + у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. -Публічні поверхні вбудованих 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 - Production code extension також має уникати імпортів `openclaw/plugin-sdk/`. + Production-код extension також має уникати імпортів `openclaw/plugin-sdk/`. Якщо допоміжний засіб справді є спільним, перенесіть його до нейтрального підшляху SDK, такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - поверхні, орієнтованої на можливості, замість зв’язування двох plugins між собою. + поверхні, орієнтованої на можливості, замість жорсткого зв’язування двох plugins. -## Пов’язані матеріали +## Пов’язане -- [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) — глибока архітектура та модель можливостей