diff --git a/docs/uk/cli/directory.md b/docs/uk/cli/directory.md index 4af9072e9..4bbdc08ea 100644 --- a/docs/uk/cli/directory.md +++ b/docs/uk/cli/directory.md @@ -1,33 +1,34 @@ --- read_when: - - Ви хочете знайти контакти, групи або ідентифікатори self для каналу - - Ви розробляєте адаптер каталогу каналу -summary: Довідник CLI для `openclaw directory` (self, peers, groups) + - Ви хочете знайти ідентифікатори контактів/груп/власного облікового запису для каналу + - Ви розробляєте адаптер каталогу каналів +summary: Довідник CLI для `openclaw directory` (себе, однорангових учасників, груп) title: Каталог x-i18n: - generated_at: "2026-04-24T04:12:06Z" - model: gpt-5.4 + generated_at: "2026-05-02T05:25:24Z" + model: gpt-5.5 provider: openai - source_hash: f63ed92469738501ae1f8f08aec3edf01d1f0f46008571ed38ccd9c77e5ba15e + source_hash: dcd0be284c0ec1aa347084d84f7001f1e2f47977ec5198025ba303297858aaab source_path: cli/directory.md - workflow: 15 + workflow: 16 --- # `openclaw directory` -Пошук у каталозі для каналів, які це підтримують (контакти/peers, групи та “me”). +Пошук у каталозі для каналів, які це підтримують (контакти/співрозмовники, групи та «me»). -## Загальні прапорці +## Спільні прапорці -- `--channel `: id/псевдонім каналу (обов’язково, якщо налаштовано кілька каналів; автоматично, якщо налаштовано лише один) -- `--account `: id облікового запису (типово: типовий для каналу) -- `--json`: вивід JSON +- `--channel `: ідентифікатор/псевдонім каналу (обов’язково, коли налаштовано кілька каналів; автоматично, коли налаштовано лише один) +- `--account `: ідентифікатор облікового запису (типово: стандартний для каналу) +- `--json`: вивести JSON ## Примітки -- `directory` призначено для того, щоб допомогти вам знайти ID, які можна вставити в інші команди (особливо `openclaw message send --target ...`). -- Для багатьох каналів результати беруться з конфігурації (allowlist / налаштовані групи), а не з живого каталогу провайдера. -- Типовий вивід — це `id` (а іноді й `name`), розділені табуляцією; для сценаріїв використовуйте `--json`. +- `directory` призначено, щоб допомогти вам знайти ідентифікатори, які можна вставити в інші команди (особливо `openclaw message send --target ...`). +- Для багатьох каналів результати базуються на конфігурації (списки дозволених / налаштовані групи), а не на живому каталозі провайдера. +- Установлені Plugin каналів усе ще можуть не підтримувати каталог; у такому разі команда повідомляє про непідтримувану операцію каталогу замість перевстановлення Plugin. +- Типовий вивід — це `id` (а іноді `name`), розділені табуляцією; використовуйте `--json` для сценаріїв. ## Використання результатів із `message send` @@ -36,24 +37,24 @@ openclaw directory peers list --channel slack --query "U0" openclaw message send --channel slack --target user:U012ABCDEF --message "hello" ``` -## Формати ID (за каналами) +## Формати ідентифікаторів (за каналом) - WhatsApp: `+15551234567` (DM), `1234567890-1234567890@g.us` (група) -- Telegram: `@username` або числовий id чату; групи — це числові id +- Telegram: `@username` або числовий ідентифікатор чату; групи мають числові ідентифікатори - Slack: `user:U…` і `channel:C…` - Discord: `user:` і `channel:` - Matrix (Plugin): `user:@user:server`, `room:!roomId:server` або `#alias:server` - Microsoft Teams (Plugin): `user:` і `conversation:` -- Zalo (Plugin): id користувача (Bot API) -- Zalo Personal / `zalouser` (Plugin): id потоку (DM/група) з `zca` (`me`, `friend list`, `group list`) +- Zalo (Plugin): ідентифікатор користувача (Bot API) +- Zalo Personal / `zalouser` (Plugin): ідентифікатор потоку (DM/група) з `zca` (`me`, `friend list`, `group list`) -## Self ("me") +## Себе ("me") ```bash openclaw directory self --channel zalouser ``` -## Peers (контакти/користувачі) +## Співрозмовники (контакти/користувачі) ```bash openclaw directory peers list --channel zalouser diff --git a/docs/uk/plugins/building-plugins.md b/docs/uk/plugins/building-plugins.md index d2eb1343b..b8e5377ba 100644 --- a/docs/uk/plugins/building-plugins.md +++ b/docs/uk/plugins/building-plugins.md @@ -1,65 +1,65 @@ --- read_when: - - Ви хочете створити новий Plugin OpenClaw - - Вам потрібен короткий посібник для швидкого старту з розробки Plugin - - Ви додаєте новий канал, провайдера, інструмент або іншу можливість в OpenClaw + - Ви хочете створити новий Plugin для OpenClaw + - Вам потрібен короткий посібник із розробки Plugin + - Ви додаєте до OpenClaw новий канал, провайдера, інструмент або іншу можливість sidebarTitle: Getting Started -summary: Створіть свій перший Plugin OpenClaw за лічені хвилини +summary: Створіть свій перший Plugin для OpenClaw за кілька хвилин title: Створення плагінів x-i18n: - generated_at: "2026-05-02T01:11:04Z" + generated_at: "2026-05-02T05:25:37Z" model: gpt-5.5 provider: openai - source_hash: e05c82cd810ed400a293cf0c336efeb6e5a6e081b144eb89150407754a98bc19 + source_hash: 2cf85c1c1c1f6ae6752f7fb8d842a420bffac6ebaf4d64803fb8bb8ab9f6f83c source_path: plugins/building-plugins.md workflow: 16 --- -Plugins розширюють OpenClaw новими можливостями: канали, постачальники моделей, -мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння -медіа, генерація зображень, генерація відео, web fetch, web search, інструменти агента або будь-яка -комбінація. +Плагіни розширюють OpenClaw новими можливостями: каналами, провайдерами моделей, +мовленням, транскрипцією в реальному часі, голосом у реальному часі, розумінням медіа, генерацією зображень, +генерацією відео, вебзавантаженням, вебпошуком, інструментами агента або будь-якою +комбінацією. -Вам не потрібно додавати свій plugin до репозиторію OpenClaw. Опублікуйте в -[ClawHub](/uk/tools/clawhub), і користувачі встановлять його через -`openclaw plugins install `. OpenClaw спочатку пробує ClawHub і -автоматично повертається до npm для пакетів, які все ще використовують дистрибуцію npm. +Вам не потрібно додавати свій плагін до репозиторію OpenClaw. Опублікуйте його в +[ClawHub](/uk/tools/clawhub), і користувачі встановлять його за допомогою +`openclaw plugins install `. OpenClaw спершу пробує ClawHub і +автоматично повертається до npm для пакетів, які все ще використовують розповсюдження через npm. ## Передумови - Node >= 22 і менеджер пакетів (npm або pnpm) - Знайомство з TypeScript (ESM) -- Для plugins у репозиторії: репозиторій клоновано й виконано `pnpm install`. Розробка plugin із - checkout вихідного коду підтримує лише pnpm, бо OpenClaw завантажує bundled - plugins з пакетів workspace `extensions/*`. +- Для плагінів у репозиторії: репозиторій клоновано й виконано `pnpm install`. Розробка плагінів + із checkout вихідного коду підтримує лише pnpm, оскільки OpenClaw завантажує вбудовані + плагіни з workspace-пакетів `extensions/*`. -## Який тип plugin? +## Який тип плагіна? - + Підключіть OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо) - - Додайте постачальника моделей (LLM, proxy або власний endpoint) + + Додайте провайдера моделей (LLM, проксі або власний endpoint) - + Зареєструйте інструменти агента, event hooks або сервіси — продовжуйте нижче -Для channel plugin, який не гарантовано буде встановлено під час onboarding/setup, +Для плагіна каналу, який не гарантовано буде встановлено під час запуску onboarding/setup, використовуйте `createOptionalChannelSetupSurface(...)` з `openclaw/plugin-sdk/channel-setup`. Він створює пару setup adapter + wizard, -яка повідомляє про вимогу встановлення й завершується закрито під час реальних записів конфігурації, -доки plugin не буде встановлено. +яка повідомляє про вимогу встановлення й завершується без змін під час реальних записів конфігурації, +доки плагін не встановлено. -## Швидкий старт: tool plugin +## Швидкий старт: плагін інструмента -Цей посібник створює мінімальний plugin, який реєструє інструмент агента. Для channel -і provider plugins є окремі посібники за посиланнями вище. +Цей walkthrough створює мінімальний плагін, який реєструє інструмент агента. Для плагінів каналів +і провайдерів є окремі посібники, посилання на які наведено вище. - + ```json package.json { @@ -85,6 +85,9 @@ Plugins розширюють OpenClaw новими можливостями: к "id": "my-plugin", "name": "My Plugin", "description": "Adds a custom tool to OpenClaw", + "contracts": { + "tools": ["my_tool"] + }, "activation": { "onStartup": true }, @@ -96,15 +99,16 @@ Plugins розширюють OpenClaw новими можливостями: к ``` - Кожному plugin потрібен manifest, навіть без конфігурації, і кожен plugin має - свідомо оголошувати `activation.onStartup`. Інструментам, зареєстрованим під час runtime, - потрібен імпорт під час startup, тому в цьому прикладі встановлено `true`. Див. - [Manifest](/uk/plugins/manifest) для повної схеми. Канонічні фрагменти публікації ClawHub + Кожному плагіну потрібен manifest, навіть без конфігурації. Інструменти, зареєстровані під час виконання, + мають бути перелічені в `contracts.tools`, щоб OpenClaw міг визначити відповідальний + плагін без завантаження runtime кожного плагіна. Плагіни також мають свідомо оголошувати + `activation.onStartup`. У цьому прикладі встановлено значення `true`. Див. + [Manifest](/uk/plugins/manifest) для повної схеми. Канонічні snippets публікації ClawHub містяться в `docs/snippets/plugin-publish/`. - + ```typescript // index.ts @@ -128,15 +132,15 @@ Plugins розширюють OpenClaw новими можливостями: к }); ``` - `definePluginEntry` призначений для plugins, що не є channel plugins. Для channels використовуйте - `defineChannelPluginEntry` — див. [Channel Plugins](/uk/plugins/sdk-channel-plugins). + `definePluginEntry` призначений для плагінів, що не є каналами. Для каналів використовуйте + `defineChannelPluginEntry` — див. [Плагіни каналів](/uk/plugins/sdk-channel-plugins). Повні параметри entry point див. у [Entry Points](/uk/plugins/sdk-entrypoints). - + - **Зовнішні plugins:** перевірте й опублікуйте через ClawHub, потім встановіть: + **Зовнішні плагіни:** перевірте та опублікуйте через ClawHub, потім встановіть: ```bash clawhub package publish your-org/your-plugin --dry-run @@ -144,11 +148,11 @@ Plugins розширюють OpenClaw новими можливостями: к openclaw plugins install clawhub:@myorg/openclaw-my-plugin ``` - OpenClaw також перевіряє ClawHub перед npm для bare package specs на кшталт + OpenClaw також перевіряє ClawHub перед npm для простих специфікацій пакетів, як-от `@myorg/openclaw-my-plugin`; npm залишається fallback для пакетів, які ще не мігрували до ClawHub. - **Plugins у репозиторії:** розмістіть під bundled plugin workspace tree — буде виявлено автоматично. + **Плагіни в репозиторії:** розмістіть у дереві workspace вбудованих плагінів — їх буде автоматично виявлено. ```bash pnpm test -- /my-plugin/ @@ -157,70 +161,70 @@ Plugins розширюють OpenClaw новими можливостями: к -## Можливості Plugin +## Можливості плагіна -Один plugin може зареєструвати будь-яку кількість можливостей через об'єкт `api`: +Один плагін може зареєструвати будь-яку кількість можливостей через об’єкт `api`: -| Можливість | Метод реєстрації | Докладний посібник | +| Можливість | Метод реєстрації | Детальний посібник | | ---------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- | -| Text inference (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) | -| CLI inference backend | `api.registerCliBackend(...)` | [CLI Backends](/uk/gateway/cli-backends) | -| Channel / messaging | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) | -| Speech (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) | -| Middleware результатів інструментів | `api.registerAgentToolResultMiddleware(...)` | [SDK Overview](/uk/plugins/sdk-overview#registration-api) | -| Інструменти агента | `api.registerTool(...)` | Нижче | -| Власні команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -| Plugin hooks | `api.on(...)` | [Plugin hooks](/uk/plugins/hooks) | -| Internal event hooks | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -| HTTP routes | `api.registerHttpRoute(...)` | [Internals](/uk/plugins/architecture-internals#gateway-http-routes) | -| CLI subcommands | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| Текстовий inference (LLM) | `api.registerProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) | +| Backend inference для CLI | `api.registerCliBackend(...)` | [Backends CLI](/uk/gateway/cli-backends) | +| Канал / повідомлення | `api.registerChannel(...)` | [Плагіни каналів](/uk/plugins/sdk-channel-plugins) | +| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Вебзавантаження | `api.registerWebFetchProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Вебпошук | `api.registerWebSearchProvider(...)` | [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Middleware результатів інструментів | `api.registerAgentToolResultMiddleware(...)` | [Огляд SDK](/uk/plugins/sdk-overview#registration-api) | +| Інструменти агента | `api.registerTool(...)` | Нижче | +| Власні команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| Hooks плагіна | `api.on(...)` | [Hooks плагіна](/uk/plugins/hooks) | +| Внутрішні event hooks | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| HTTP-маршрути | `api.registerHttpRoute(...)` | [Внутрішня архітектура](/uk/plugins/architecture-internals#gateway-http-routes) | +| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -Повний registration API див. у [SDK Overview](/uk/plugins/sdk-overview#registration-api). +Повний API реєстрації див. в [Огляді SDK](/uk/plugins/sdk-overview#registration-api). -Bundled plugins можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли їм -потрібне асинхронне переписування результату інструмента до того, як модель побачить вивід. Оголосіть +Вбудовані плагіни можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли їм +потрібне асинхронне переписування результату інструмента до того, як модель побачить output. Оголошуйте цільові runtimes у `contracts.agentToolResultMiddleware`, наприклад -`["pi", "codex"]`. Це довірений seam для bundled-plugin; зовнішнім -plugins варто надавати перевагу звичайним OpenClaw plugin hooks, доки OpenClaw не отримає -явну trust policy для цієї можливості. +`["pi", "codex"]`. Це довірений seam для вбудованих плагінів; зовнішнім +плагінам варто надавати перевагу звичайним hooks плагінів OpenClaw, доки OpenClaw не матиме +явної політики довіри для цієї можливості. -Якщо ваш plugin реєструє власні gateway RPC methods, тримайте їх на -префіксі, специфічному для plugin. Core admin namespaces (`config.*`, +Якщо ваш плагін реєструє власні RPC-методи Gateway, тримайте їх у +префіксі, специфічному для плагіна. Простори імен core admin (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди resolve до -`operator.admin`, навіть якщо plugin просить вужчий scope. +`operator.admin`, навіть якщо плагін просить вужчий scope. -Семантика hook guard, яку варто пам'ятати: +Семантика guard для hooks, яку варто пам’ятати: -- `before_tool_call`: `{ block: true }` є terminal і зупиняє handlers з нижчим пріоритетом. -- `before_tool_call`: `{ block: false }` обробляється як відсутність рішення. -- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує підтвердження користувача через exec approval overlay, кнопки Telegram, взаємодії Discord або команду `/approve` у будь-якому channel. -- `before_install`: `{ block: true }` є terminal і зупиняє handlers з нижчим пріоритетом. -- `before_install`: `{ block: false }` обробляється як відсутність рішення. -- `message_sending`: `{ cancel: true }` є terminal і зупиняє handlers з нижчим пріоритетом. -- `message_sending`: `{ cancel: false }` обробляється як відсутність рішення. -- `message_received`: надавайте перевагу типізованому полю `threadId`, коли потрібна inbound thread/topic routing. Залишайте `metadata` для channel-specific extras. -- `message_sending`: надавайте перевагу типізованим routing fields `replyToId` / `threadId` замість channel-specific metadata keys. +- `before_tool_call`: `{ block: true }` є terminal і зупиняє handlers із нижчим пріоритетом. +- `before_tool_call`: `{ block: false }` розглядається як відсутність рішення. +- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує в користувача схвалення через exec approval overlay, кнопки Telegram, Discord interactions або команду `/approve` на будь-якому каналі. +- `before_install`: `{ block: true }` є terminal і зупиняє handlers із нижчим пріоритетом. +- `before_install`: `{ block: false }` розглядається як відсутність рішення. +- `message_sending`: `{ cancel: true }` є terminal і зупиняє handlers із нижчим пріоритетом. +- `message_sending`: `{ cancel: false }` розглядається як відсутність рішення. +- `message_received`: надавайте перевагу типізованому полю `threadId`, коли потрібна маршрутизація вхідних thread/topic. Залишайте `metadata` для додаткових даних, специфічних для каналу. +- `message_sending`: надавайте перевагу типізованим полям маршрутизації `replyToId` / `threadId` замість ключів metadata, специфічних для каналу. -Команда `/approve` обробляє як exec, так і plugin approvals з обмеженим fallback: коли exec approval id не знайдено, OpenClaw повторює той самий id через plugin approvals. Пересилання plugin approval можна налаштувати незалежно через `approvals.plugin` у config. +Команда `/approve` обробляє як exec approvals, так і approvals плагінів із bounded fallback: коли id exec approval не знайдено, OpenClaw повторює той самий id через approvals плагінів. Forwarding approvals плагінів можна налаштовувати незалежно через `approvals.plugin` у конфігурації. -Якщо власна approval plumbing має виявити той самий випадок bounded fallback, +Якщо власний approval plumbing має виявляти той самий bounded fallback-випадок, надавайте перевагу `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime` замість ручного зіставлення рядків про expiry approval. -Приклади й довідник hooks див. у [Plugin hooks](/uk/plugins/hooks). +Приклади й довідник hooks див. у [Hooks плагіна](/uk/plugins/hooks). ## Реєстрація інструментів агента -Tools — це типізовані функції, які може викликати LLM. Вони можуть бути required (завжди -доступні) або optional (opt-in користувача): +Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути обов’язковими (завжди +доступними) або опціональними (користувач вмикає їх сам): ```typescript register(api) { @@ -249,7 +253,18 @@ register(api) { } ``` -Користувачі вмикають optional tools у config: +Кожен інструмент, зареєстрований через `api.registerTool(...)`, також має бути оголошений у +manifest плагіна: + +```json +{ + "contracts": { + "tools": ["my_tool", "workflow_tool"] + } +} +``` + +Користувачі вмикають опціональні інструменти в конфігурації: ```json5 { @@ -257,16 +272,16 @@ register(api) { } ``` -- Імена tools не мають конфліктувати з core tools (конфлікти пропускаються) -- Tools з некоректними registration objects, зокрема без `parameters`, пропускаються й повідомляються в plugin diagnostics замість того, щоб ламати agent runs -- Використовуйте `optional: true` для tools із побічними ефектами або додатковими binary requirements -- Користувачі можуть увімкнути всі tools з plugin, додавши plugin id до `tools.allow` +- Назви інструментів не повинні конфліктувати з основними інструментами (конфліктні пропускаються) +- Інструменти з некоректно сформованими об’єктами реєстрації, зокрема без `parameters`, пропускаються й повідомляються в діагностиці plugin замість того, щоб ламати запуски агента +- Використовуйте `optional: true` для інструментів із побічними ефектами або додатковими вимогами до бінарних файлів +- Користувачі можуть увімкнути всі інструменти з plugin, додавши ідентифікатор plugin до `tools.allow` -## Реєстрація CLI commands +## Реєстрація команд CLI -Plugins можуть додавати кореневі групи команд `openclaw` через `api.registerCli`. Надайте -`descriptors` для кожного top-level command root, щоб OpenClaw міг показувати й route -команду без eager loading кожного plugin runtime. +Plugins можуть додавати кореневі групи команд `openclaw` за допомогою `api.registerCli`. Надавайте +`descriptors` для кожного кореня команди верхнього рівня, щоб OpenClaw міг показувати й маршрутизувати +команду без завчасного завантаження кожного середовища виконання plugin. ```typescript register(api) { @@ -296,7 +311,7 @@ register(api) { } ``` -Після встановлення перевірте реєстрацію runtime і виконайте команду: +Після встановлення перевірте реєстрацію середовища виконання та виконайте команду: ```bash openclaw plugins inspect demo-plugin --runtime --json @@ -317,56 +332,56 @@ import { ... } from "openclaw/plugin-sdk"; Повний довідник підшляхів див. у [Огляді SDK](/uk/plugins/sdk-overview). -У межах вашого plugin використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для +Усередині свого plugin використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для внутрішніх імпортів — ніколи не імпортуйте власний plugin через його шлях SDK. -Для provider plugins тримайте допоміжні засоби, специфічні для постачальника, у цих package-root -barrels, якщо seam не є справді універсальним. Поточні вбудовані приклади: +Для provider plugins тримайте специфічні для провайдера допоміжні засоби в цих barrel-файлах кореня пакета, +якщо межа не є справді узагальненою. Поточні вбудовані приклади: -- Anthropic: обгортки потоків Claude і допоміжні засоби `service_tier` / beta -- OpenAI: конструктори постачальників, допоміжні засоби моделей за замовчуванням, постачальники realtime -- OpenRouter: конструктор постачальника плюс допоміжні засоби onboarding/config +- Anthropic: обгортки потоків Claude та допоміжні засоби `service_tier` / beta +- OpenAI: конструктори провайдера, допоміжні засоби моделей за замовчуванням, realtime-провайдери +- OpenRouter: конструктор провайдера та допоміжні засоби onboarding/конфігурації -Якщо допоміжний засіб корисний лише всередині одного вбудованого пакета постачальника, залиште його на цьому -package-root seam замість просування до `openclaw/plugin-sdk/*`. +Якщо допоміжний засіб корисний лише всередині одного вбудованого пакета провайдера, залишайте його на цій +межі кореня пакета замість просування в `openclaw/plugin-sdk/*`. -Деякі згенеровані допоміжні seams `openclaw/plugin-sdk/` усе ще існують для -супроводу bundled-plugin, коли для них відстежується використання власником. Розглядайте їх як -зарезервовані поверхні, а не як типовий шаблон для нових third-party plugins. +Деякі згенеровані допоміжні межі `openclaw/plugin-sdk/` досі існують для +супроводу вбудованих plugin, коли для них відстежується використання власником. Вважайте їх +зарезервованими поверхнями, а не типовим шаблоном для нових сторонніх plugins. ## Контрольний список перед поданням -**package.json** має правильні метадані `openclaw` -Маніфест **openclaw.plugin.json** присутній і валідний +**package.json** має коректні метадані `openclaw` +Маніфест **openclaw.plugin.json** наявний і валідний Точка входу використовує `defineChannelPluginEntry` або `definePluginEntry` Усі імпорти використовують сфокусовані шляхи `plugin-sdk/` -Внутрішні імпорти використовують локальні модулі, а не self-imports SDK +Внутрішні імпорти використовують локальні модулі, а не самоімпорти SDK Тести проходять (`pnpm test -- /my-plugin/`) -`pnpm check` проходить (для in-repo plugins) +`pnpm check` проходить (для plugins у репозиторії) ## Тестування beta-релізу -1. Стежте за тегами релізів GitHub на [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Beta-теги мають вигляд `v2026.3.N-beta.1`. Також можна ввімкнути сповіщення для офіційного акаунта OpenClaw в X [@openclaw](https://x.com/openclaw), щоб отримувати оголошення про релізи. -2. Протестуйте свій plugin із beta-тегом щойно він з'явиться. Вікно до stable зазвичай триває лише кілька годин. -3. Після тестування напишіть у гілці свого plugin у каналі Discord `plugin-forum`: або `all good`, або що саме зламалося. Якщо у вас ще немає гілки, створіть її. -4. Якщо щось зламалося, відкрийте або оновіть issue із заголовком `Beta blocker: - ` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свою гілку. -5. Відкрийте PR до `main` із заголовком `fix(): beta blocker - ` і додайте посилання на issue як у PR, так і у своїй гілці Discord. Contributors не можуть ставити мітки на PR, тому заголовок є сигналом з боку PR для maintainers і automation. Blockers із PR буде змерджено; blockers без PR можуть усе одно потрапити в реліз. Maintainers стежать за цими гілками під час beta-тестування. -6. Мовчання означає зелений статус. Якщо ви пропустите це вікно, ваше виправлення, ймовірно, потрапить у наступний цикл. +1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Beta-теги мають вигляд `v2026.3.N-beta.1`. Також можна ввімкнути сповіщення для офіційного X-акаунта OpenClaw [@openclaw](https://x.com/openclaw), щоб отримувати оголошення про релізи. +2. Тестуйте свій plugin з beta-тегом щойно він з’явиться. Вікно до stable зазвичай становить лише кілька годин. +3. Після тестування напишіть у гілці свого plugin у каналі Discord `plugin-forum` або `all good`, або що саме зламалося. Якщо гілки ще немає, створіть її. +4. Якщо щось зламалося, відкрийте або оновіть issue з назвою `Beta blocker: - ` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свою гілку. +5. Відкрийте PR до `main` з назвою `fix(): beta blocker - ` і додайте посилання на issue і в PR, і у свою гілку Discord. Contributors не можуть ставити мітки на PR, тому назва є сигналом на боці PR для maintainers та автоматизації. Блокери з PR зливаються; блокери без PR можуть усе одно потрапити в реліз. Maintainers стежать за цими гілками під час beta-тестування. +6. Мовчання означає зелений статус. Якщо ви пропустите це вікно, ваше виправлення, імовірно, потрапить у наступний цикл. ## Наступні кроки - Створіть plugin каналу обміну повідомленнями + Створити plugin каналу повідомлень - Створіть plugin постачальника моделей + Створити plugin провайдера моделей - Карта імпортів і довідник API реєстрації + Мапа імпортів і довідник API реєстрації - - TTS, пошук, subagent через api.runtime + + TTS, пошук, субагент через api.runtime Тестові утиліти й шаблони @@ -376,10 +391,10 @@ package-root seam замість просування до `openclaw/plugin-sdk/ -## Пов'язане +## Пов’язане -- [Архітектура Plugin](/uk/plugins/architecture) — глибокий огляд внутрішньої архітектури +- [Архітектура Plugin](/uk/plugins/architecture) — докладний огляд внутрішньої архітектури - [Огляд SDK](/uk/plugins/sdk-overview) — довідник Plugin SDK - [Маніфест](/uk/plugins/manifest) — формат маніфесту plugin -- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення channel plugins -- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення provider plugins +- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення plugins каналів +- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення plugins провайдерів diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 5f157757b..d5de693dc 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,14 +1,14 @@ --- read_when: - - Ви створюєте Plugin для OpenClaw - - Вам потрібно випустити схему конфігурації Plugin або налагодити помилки валідації Plugin -summary: Маніфест Plugin + вимоги до JSON-схеми (сувора перевірка конфігурації) + - Ви створюєте Plugin OpenClaw + - Потрібно постачити схему конфігурації Plugin або діагностувати помилки валідації Plugin +summary: Вимоги до маніфесту Plugin + JSON-схеми (сувора валідація конфігурації) title: Маніфест Plugin x-i18n: - generated_at: "2026-05-02T02:49:18Z" + generated_at: "2026-05-02T05:25:29Z" model: gpt-5.5 provider: openai - source_hash: 83fb98614783b679d6b49d2237148765708e5c5fc2ee40162d3ddd4752f763c2 + source_hash: 371a7364374df57c0b4a55229b86beea24140d0b352a54e8281e103bf66f5662 source_path: plugins/manifest.md workflow: 16 --- @@ -20,20 +20,20 @@ x-i18n: Сумісні формати бандлів використовують інші файли маніфестів: - Бандл Codex: `.codex-plugin/plugin.json` -- Бандл Claude: `.claude-plugin/plugin.json` або стандартна структура компонентів Claude +- Бандл Claude: `.claude-plugin/plugin.json` або типова структура компонента Claude без маніфесту - Бандл Cursor: `.cursor-plugin/plugin.json` OpenClaw також автоматично виявляє ці структури бандлів, але вони не перевіряються за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних бандлів OpenClaw зараз читає метадані бандла плюс оголошені -корені skill, корені команд Claude, стандартні значення `settings.json` бандла Claude, -стандартні значення LSP бандла Claude та підтримувані набори хуків, коли структура відповідає -очікуванням середовища виконання OpenClaw. +Для сумісних бандлів OpenClaw наразі читає метадані бандла, а також оголошені +корені skill, корені команд Claude, типові значення `settings.json` бандла Claude, +типові значення LSP бандла Claude і підтримувані пакети hook, коли структура відповідає +очікуванням runtime OpenClaw. Кожен нативний Plugin OpenClaw **повинен** постачати файл `openclaw.plugin.json` у -**корені Plugin**. OpenClaw використовує цей маніфест для перевірки конфігурації +**корені Plugin**. OpenClaw використовує цей маніфест, щоб перевіряти конфігурацію **без виконання коду Plugin**. Відсутні або недійсні маніфести вважаються помилками Plugin і блокують перевірку конфігурації. @@ -43,22 +43,22 @@ OpenClaw також автоматично виявляє ці структур ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw читає **перед завантаженням вашого -коду Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску -середовища виконання Plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження вашого +коду Plugin**. Усе нижче має бути достатньо дешевим для перевірки без запуску +runtime Plugin. **Використовуйте його для:** - ідентичності Plugin, перевірки конфігурації та підказок UI конфігурації -- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоматичне ввімкнення, змінні середовища провайдера, варіанти автентифікації) -- підказок активації для поверхонь площини керування +- метаданих автентифікації, onboarding і налаштування (alias, auto-enable, змінні середовища провайдера, варіанти автентифікації) +- підказок активації для поверхонь control-plane - скороченого володіння сімейством моделей - статичних знімків володіння можливостями (`contracts`) -- метаданих запуску QA, які спільний хост `openclaw qa` може перевіряти -- метаданих конфігурації для окремих каналів, об'єднаних у каталог і поверхні перевірки +- метаданих QA runner, які може перевіряти спільний хост `openclaw qa` +- метаданих конфігурації, специфічних для каналів, об’єднаних у каталог і поверхні перевірки -**Не використовуйте його для:** реєстрації поведінки середовища виконання, оголошення точок входу коду -або метаданих встановлення npm. Вони належать до вашого коду Plugin і `package.json`. +**Не використовуйте його для:** реєстрації runtime-поведінки, оголошення entrypoint коду +або метаданих npm install. Вони належать до вашого коду Plugin і `package.json`. ## Мінімальний приклад @@ -152,74 +152,212 @@ OpenClaw також автоматично виявляє ці структур ## Довідник полів верхнього рівня -| Поле | Обов'язкове | Тип | Що це означає | -| ------------------------------------ | ----------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Це ідентифікатор, що використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | -| `enabledByDefault` | Ні | `true` | Позначає bundled Plugin як увімкнений за замовчуванням. Опустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб залишити Plugin вимкненим за замовчуванням. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, що нормалізуються до цього канонічного ідентифікатора Plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей Plugin, коли auth, config або refs моделей згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, що використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей Plugin. Використовується для виявлення та перевірки конфігурації. | -| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей Plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Полегшений шлях до модуля виявлення провайдера, відносно кореня Plugin, для метаданих каталогу провайдерів у межах manifest, які можна завантажити без активації повного runtime Plugin. | -| `modelSupport` | Ні | `object` | Стислі метадані родини моделей, що належать manifest і використовуються для автоматичного завантаження Plugin перед runtime. | -| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт control plane для майбутнього read-only переліку, onboarding, вибору моделей, aliases і suppression без завантаження runtime Plugin. | -| `modelPricing` | Ні | `object` | Належна провайдеру політика зовнішнього пошуку цін. Використовуйте її, щоб виключити локальних/self-hosted провайдерів із віддалених каталогів цін або зіставити refs провайдера з ідентифікаторами каталогів OpenRouter/LiteLLM без hardcoding ідентифікаторів провайдерів у core. | -| `modelIdNormalization` | Ні | `object` | Належне провайдеру очищення alias/prefix ідентифікаторів моделей, яке має виконуватися до завантаження runtime провайдера. | -| `providerEndpoints` | Ні | `object[]` | Належні manifest метадані endpoint host/baseUrl для маршрутів провайдера, які core має класифікувати до завантаження runtime провайдера. | -| `providerRequest` | Ні | `object` | Дешеві метадані родини провайдера та сумісності запитів, які використовуються generic політикою запитів до завантаження runtime провайдера. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори CLI inference backend, якими володіє цей Plugin. Використовується для автоматичної активації під час запуску з явних refs конфігурації. | -| `syntheticAuthRefs` | Ні | `string[]` | Refs провайдера або CLI backend, для яких належний Plugin synthetic auth hook має перевірятися під час холодного виявлення моделей до завантаження runtime. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Належні bundled Plugin placeholder-значення API key, що представляють несекретний локальний, OAuth або ambient credential стан. | -| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей Plugin і які мають створювати діагностику конфігурації та CLI з урахуванням Plugin до завантаження runtime. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні env-метадані для пошуку auth/status провайдера. Для нових Plugin віддавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це під час періоду deprecation. | -| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для auth lookup, наприклад coding provider, що спільно використовує API key базового провайдера та auth profiles. | -| `channelEnvVars` | Ні | `Record` | Дешеві env-метадані каналу, які OpenClaw може перевірити без завантаження коду Plugin. Використовуйте це для env-driven налаштування каналу або auth surfaces, які мають бачити generic startup/config helpers. | -| `providerAuthChoices` | Ні | `object[]` | Дешеві метадані auth-choice для onboarding pickers, preferred-provider resolution і простого wiring CLI flags. | -| `activation` | Ні | `object` | Дешеві метадані activation planner для завантаження, спричиненого startup, provider, command, channel, route і capability. Лише метадані; runtime Plugin усе ще володіє фактичною поведінкою. | -| `setup` | Ні | `object` | Дешеві дескриптори setup/onboarding, які discovery і setup surfaces можуть перевіряти без завантаження runtime Plugin. | -| `qaRunners` | Ні | `object[]` | Дешеві дескриптори QA runner, що використовуються спільним host `openclaw qa` до завантаження runtime Plugin. | -| `contracts` | Ні | `object` | Статичний знімок bundled capability для external auth hooks, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і tool ownership. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Дешеві media-understanding defaults для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Належні manifest метадані конфігурації каналу, об'єднані в discovery і validation surfaces до завантаження runtime. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. | -| `name` | Ні | `string` | Зрозуміла для людини назва Plugin. | -| `description` | Ні | `string` | Короткий підсумок, що відображається на поверхнях Plugin. | -| `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | UI labels, placeholders і sensitivity hints для полів конфігурації. | +| Поле | Обов'язкове | Тип | Що це означає | +| ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Канонічний id Plugin. Це id, що використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Пропустіть це поле або задайте будь-яке значення, відмінне від `true`, щоб залишити Plugin вимкненим за замовчуванням. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі ids, що нормалізуються до цього канонічного id Plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | ids провайдерів, які мають автоматично вмикати цей Plugin, коли auth, config або model refs згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, що використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | ids каналів, якими володіє цей Plugin. Використовується для виявлення та перевірки конфігурації. | +| `providers` | Ні | `string[]` | ids провайдерів, якими володіє цей Plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковажного модуля виявлення провайдерів, відносний до кореня Plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного runtime Plugin. | +| `modelSupport` | Ні | `object` | Скорочені метадані сімейств моделей, що належать маніфесту й використовуються для автозавантаження Plugin перед runtime. | +| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт control-plane для майбутнього спискування лише для читання, onboarding, вибору моделей, alias і suppression без завантаження runtime Plugin. | +| `modelPricing` | Ні | `object` | Політика пошуку зовнішніх цін, що належить провайдеру. Використовуйте її, щоб виключити локальних/self-hosted провайдерів із віддалених каталогів цін або зіставити provider refs з ids каталогів OpenRouter/LiteLLM без hardcoding ids провайдерів у core. | +| `modelIdNormalization` | Ні | `object` | Очищення alias/prefix model-id, що належить провайдеру й має виконуватися перед завантаженням runtime провайдера. | +| `providerEndpoints` | Ні | `object[]` | Метадані endpoint host/baseUrl, що належать маніфесту, для маршрутів провайдера, які core має класифікувати перед завантаженням runtime провайдера. | +| `providerRequest` | Ні | `object` | Дешеві метадані сімейства провайдера та сумісності запиту, що використовуються загальною політикою запитів перед завантаженням runtime провайдера. | +| `cliBackends` | Ні | `string[]` | ids бекендів інференсу CLI, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних config refs. | +| `syntheticAuthRefs` | Ні | `string[]` | refs провайдера або бекенда CLI, чий synthetic auth hook, що належить Plugin, має перевірятися під час холодного виявлення моделей перед завантаженням runtime. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення placeholder API key, що належать вбудованому Plugin і представляють несекретний локальний, OAuth або ambient стан облікових даних. | +| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які мають створювати Plugin-aware діагностику конфігурації та CLI перед завантаженням runtime. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні env-метадані для пошуку auth/status провайдера. Для нових plugins віддавайте перевагу `setup.providers[].envVars`; OpenClaw досі читає це під час періоду вилучення. | +| `providerAuthAliases` | Ні | `Record` | ids провайдерів, які мають повторно використовувати інший id провайдера для auth lookup, наприклад coding provider, що спільно використовує API key базового провайдера та auth profiles. | +| `channelEnvVars` | Ні | `Record` | Дешеві env-метадані каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для env-driven налаштування каналу або auth surfaces, які мають бачити загальні startup/config helpers. | +| `providerAuthChoices` | Ні | `object[]` | Дешеві метадані auth-choice для onboarding pickers, preferred-provider resolution і простого підключення прапорців CLI. | +| `activation` | Ні | `object` | Дешеві метадані планувальника активації для завантаження, ініційованого запуском, провайдером, командою, каналом, маршрутом і capability. Лише метадані; фактична поведінка все ще належить runtime Plugin. | +| `setup` | Ні | `object` | Дешеві дескриптори setup/onboarding, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime Plugin. | +| `qaRunners` | Ні | `object[]` | Дешеві дескриптори QA runner, що використовуються спільним хостом `openclaw qa` перед завантаженням runtime Plugin. | +| `contracts` | Ні | `object` | Статичний знімок ownership можливостей для зовнішніх auth hooks, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і tool ownership. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Дешеві типові налаштування media-understanding для ids провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `imageGenerationProviderMetadata` | Ні | `Record` | Дешеві auth-метадані image-generation для ids провайдерів, оголошених у `contracts.imageGenerationProviders`, включно з auth aliases і base-url guards, що належать провайдеру. | +| `videoGenerationProviderMetadata` | Ні | `Record` | Дешеві auth-метадані video-generation для ids провайдерів, оголошених у `contracts.videoGenerationProviders`, включно з auth aliases і base-url guards, що належать провайдеру. | +| `musicGenerationProviderMetadata` | Ні | `Record` | Дешеві auth-метадані music-generation для ids провайдерів, оголошених у `contracts.musicGenerationProviders`, включно з auth aliases і base-url guards, що належать провайдеру. | +| `toolMetadata` | Ні | `Record` | Дешеві метадані доступності для інструментів, що належать Plugin і оголошені в `contracts.tools`. Використовуйте їх, коли інструмент не має завантажувати runtime без доказів config, env або auth. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту, об'єднані з поверхнями виявлення та перевірки перед завантаженням runtime. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореня Plugin. | +| `name` | Ні | `string` | Зрозуміла для людини назва Plugin. | +| `description` | Ні | `string` | Короткий опис, що відображається в поверхнях Plugin. | +| `version` | Ні | `string` | Інформаційна версія Plugin. | +| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки щодо чутливості для конфігураційних полів. | -## Довідка providerAuthChoices +## Довідник метаданих постачальників генерації -Кожен запис `providerAuthChoices` описує один onboarding або auth choice. -OpenClaw читає це до завантаження runtime провайдера. -Списки налаштування провайдера використовують ці manifest choices, setup choices, -отримані з descriptor, і install-catalog metadata без завантаження runtime провайдера. +Поля метаданих постачальника генерації описують статичні сигнали автентифікації для +постачальників, оголошених у відповідному списку `contracts.*GenerationProviders`. +OpenClaw читає ці поля до завантаження runtime постачальника, щоб основні інструменти могли +визначати, чи доступний постачальник генерації, без імпорту кожного +Plugin постачальника. -| Поле | Обов’язково | Тип | Що це означає | -| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Ідентифікатор провайдера, якому належить цей вибір. | -| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого потрібно спрямувати виконання. | -| `choiceId` | Так | `string` | Стабільний ідентифікатор вибору автентифікації, який використовують потоки онбордингу та CLI. | -| `choiceLabel` | Ні | `string` | Мітка, яку бачить користувач. Якщо її пропущено, OpenClaw повертається до `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | -| `assistantPriority` | Ні | `number` | Нижчі значення сортуються раніше в інтерактивних засобах вибору, керованих асистентом. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує вибір із засобів вибору асистента, але й далі дозволяє ручний вибір у CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори вибору, які мають перенаправляти користувачів до цього замінного вибору. | -| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних виборів. | -| `groupLabel` | Ні | `string` | Мітка для цієї групи, яку бачить користувач. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків автентифікації з одним прапорцем. | -| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, який використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | Визначає, на яких поверхнях онбордингу має з’являтися цей вибір. Якщо пропущено, типово використовується `["text-inference"]`. | +Використовуйте ці поля лише для недорогих декларативних фактів. Транспорт, перетворення +запитів, оновлення токенів, перевірка облікових даних і фактична поведінка генерації +залишаються в runtime Plugin. + +```json +{ + "contracts": { + "imageGenerationProviders": ["example-image"] + }, + "imageGenerationProviderMetadata": { + "example-image": { + "aliases": ["example-image-oauth"], + "authProviders": ["example-image"], + "configSignals": [ + { + "rootPath": "plugins.entries.example-image.config", + "overlayPath": "image", + "mode": { + "path": "mode", + "default": "local", + "allowed": ["local"] + }, + "requiredAny": ["workflow", "workflowPath"], + "required": ["promptNodeId"] + } + ], + "authSignals": [ + { + "provider": "example-image" + }, + { + "provider": "example-image-oauth", + "providerBaseUrl": { + "provider": "example-image", + "defaultBaseUrl": "https://api.example.com/v1", + "allowedBaseUrls": ["https://api.example.com/v1"] + } + } + ] + } + } +} +``` + +Кожен запис метаданих підтримує: + +| Поле | Обов'язково | Тип | Що це означає | +| --------------- | ----------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `aliases` | Ні | `string[]` | Додаткові ідентифікатори постачальників, які мають враховуватися як статичні псевдоніми автентифікації для постачальника генерації. | +| `authProviders` | Ні | `string[]` | Ідентифікатори постачальників, чиї налаштовані профілі автентифікації мають враховуватися як автентифікація для цього постачальника генерації. | +| `configSignals` | Ні | `object[]` | Недорогі сигнали доступності лише за конфігурацією для локальних або самостійно розміщених постачальників, які можна налаштувати без профілів автентифікації чи змінних env. | +| `authSignals` | Ні | `object[]` | Явні сигнали автентифікації. Якщо вони присутні, вони замінюють типовий набір сигналів з ідентифікатора постачальника, `aliases` і `authProviders`. | + +Кожен запис `configSignals` підтримує: + +| Поле | Обов'язково | Тип | Що це означає | +| ------------- | ----------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `rootPath` | Так | `string` | Dot path до об'єкта конфігурації, яким володіє Plugin, що потрібно перевірити, наприклад `plugins.entries.example.config`. | +| `overlayPath` | Ні | `string` | Dot path усередині кореневої конфігурації, об'єкт якого має накладатися на кореневий об'єкт перед оцінюванням сигналу. Використовуйте це для конфігурації конкретної можливості, як-от `image`, `video` або `music`. | +| `required` | Ні | `string[]` | Dot paths усередині ефективної конфігурації, які повинні мати налаштовані значення. Рядки мають бути непорожніми; об'єкти та масиви не мають бути порожніми. | +| `requiredAny` | Ні | `string[]` | Dot paths усередині ефективної конфігурації, де принаймні один має мати налаштоване значення. | +| `mode` | Ні | `object` | Необов'язковий захист рядкового режиму всередині ефективної конфігурації. Використовуйте це, коли доступність лише за конфігурацією застосовується тільки до одного режиму. | + +Кожен захист `mode` підтримує: + +| Поле | Обов'язково | Тип | Що це означає | +| ------------ | ----------- | ---------- | ----------------------------------------------------------------------------- | +| `path` | Ні | `string` | Dot path усередині ефективної конфігурації. За замовчуванням `mode`. | +| `default` | Ні | `string` | Значення режиму, яке слід використовувати, коли конфігурація пропускає шлях. | +| `allowed` | Ні | `string[]` | Якщо присутнє, сигнал проходить лише тоді, коли ефективний режим є одним із цих значень. | +| `disallowed` | Ні | `string[]` | Якщо присутнє, сигнал не проходить, коли ефективний режим є одним із цих значень. | + +Кожен запис `authSignals` підтримує: + +| Поле | Обов'язково | Тип | Що це означає | +| ---------------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор постачальника для перевірки в налаштованих профілях автентифікації. | +| `providerBaseUrl` | Ні | `object` | Необов'язковий захист, через який сигнал враховується лише тоді, коли зазначений налаштований постачальник використовує дозволений базовий URL. Використовуйте це, коли псевдонім автентифікації чинний лише для певних API. | + +Кожен захист `providerBaseUrl` підтримує: + +| Поле | Обов'язково | Тип | Що це означає | +| ----------------- | ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `provider` | Так | `string` | Ідентифікатор конфігурації постачальника, чий `baseUrl` потрібно перевірити. | +| `defaultBaseUrl` | Ні | `string` | Базовий URL, який слід припускати, коли конфігурація постачальника пропускає `baseUrl`. | +| `allowedBaseUrls` | Так | `string[]` | Дозволені базові URL для цього сигналу автентифікації. Сигнал ігнорується, коли налаштований або типовий базовий URL не збігається з одним із цих нормалізованих значень. | + +## Довідник метаданих інструментів + +`toolMetadata` використовує ті самі форми `configSignals` і `authSignals`, що й +метадані постачальника генерації, з ключами за назвою інструмента. `contracts.tools` оголошує +володіння. `toolMetadata` оголошує недорогі докази доступності, щоб OpenClaw міг +уникати імпорту runtime Plugin лише для того, щоб фабрика інструмента повернула `null`. + +```json +{ + "providerAuthEnvVars": { + "example": ["EXAMPLE_API_KEY"] + }, + "contracts": { + "tools": ["example_search"] + }, + "toolMetadata": { + "example_search": { + "authSignals": [ + { + "provider": "example" + } + ], + "configSignals": [ + { + "rootPath": "plugins.entries.example.config", + "overlayPath": "search", + "required": ["apiKey"] + } + ] + } + } +} +``` + +Якщо інструмент не має `toolMetadata`, OpenClaw зберігає наявну поведінку та +завантажує Plugin-власник, коли контракт інструмента відповідає політиці. Для інструментів +на гарячому шляху, фабрика яких залежить від автентифікації/конфігурації, автори Plugin мають оголошувати +`toolMetadata` замість того, щоб змушувати core імпортувати runtime для запиту. + +## Довідник providerAuthChoices + +Кожен запис `providerAuthChoices` описує один вибір онбордингу або автентифікації. +OpenClaw читає це до завантаження runtime постачальника. +Списки налаштування постачальника використовують ці вибори маніфесту, вибори налаштування, +отримані з дескрипторів, і метадані каталогу встановлення без завантаження runtime постачальника. + +| Поле | Обов'язково | Тип | Що це означає | +| --------------------- | ----------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | Ідентифікатор постачальника, якому належить цей вибір. | +| `method` | Так | `string` | Ідентифікатор методу автентифікації для диспетчеризації. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор вибору автентифікації, який використовується потоками онбордингу та CLI. | +| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо пропущено, OpenClaw повертається до `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для вибирача. | +| `assistantPriority` | Ні | `number` | Нижчі значення сортуються раніше в інтерактивних вибирачах, керованих асистентом. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховати вибір із вибирачів асистента, водночас дозволяючи ручний вибір у CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори вибору, які мають перенаправляти користувачів до цього вибору-замінника. | +| `groupId` | Ні | `string` | Необов'язковий ідентифікатор групи для групування пов'язаних виборів. | +| `groupLabel` | Ні | `string` | Мітка для користувача для цієї групи. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма опції CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях онбордингу має з'являтися цей вибір. Якщо пропущено, типовим є `["text-inference"]`. | ## Довідник commandAliases -Використовуйте `commandAliases`, коли Plugin володіє назвою команди середовища виконання, яку користувачі можуть -помилково додати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw -використовує ці метадані для діагностики без імпортування коду середовища виконання Plugin. +Використовуйте `commandAliases`, коли Plugin володіє назвою команди часу виконання, яку користувачі можуть +помилково додати в `plugins.allow` або спробувати запустити як кореневу CLI-команду. OpenClaw +використовує ці метадані для діагностики без імпорту runtime-коду Plugin. ```json { @@ -233,43 +371,43 @@ OpenClaw читає це до завантаження runtime провайде } ``` -| Поле | Обов’язково | Тип | Що це означає | -| ------------ | ----------- | ----------------- | -------------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, яка належить цьому Plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як слеш-команду чату, а не кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку можна запропонувати для операцій CLI, якщо така існує. | +| Поле | Обов'язкове | Тип | Що це означає | +| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, що належить цьому Plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу CLI-команду. | +| `cliCommand` | Ні | `string` | Пов'язана коренева CLI-команда, яку варто запропонувати для CLI-операцій, якщо вона існує. | -## Довідник activation +## Довідник з activation Використовуйте `activation`, коли Plugin може дешево оголосити, які події площини керування мають включати його до плану активації/завантаження. -Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє -поведінку середовища виконання, не замінює `register(...)` і не гарантує, що +Цей блок є метаданими планувальника, а не lifecycle API. Він не реєструє +поведінку часу виконання, не замінює `register(...)` і не обіцяє, що код Plugin уже виконався. Планувальник активації використовує ці поля, щоб -звузити список кандидатів Plugin перед поверненням до наявних метаданих володіння в маніфесті, -як-от `providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і хуків. +звузити список кандидатних Plugin перед поверненням до наявних метаданих володіння +з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і hooks. Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте -`providers`, `channels`, `commandAliases`, дескриптори налаштування або `contracts`, -коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових -підказок планувальнику, які неможливо представити цими полями володіння. -Використовуйте верхньорівневий `cliBackends` для псевдонімів середовища виконання CLI, як-от `claude-cli`, -`codex-cli` або `google-gemini-cli`; `activation.onAgentHarnesses` призначений лише для -вбудованих ідентифікаторів агентних обв’язок, які ще не мають поля володіння. +`providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, +коли ці поля виражають зв'язок. Використовуйте `activation` для додаткових підказок +планувальнику, які неможливо представити цими полями володіння. +Використовуйте верхньорівневе `cliBackends` для CLI runtime-псевдонімів, таких як `claude-cli`, +`codex-cli` або `google-gemini-cli`; `activation.onAgentHarnesses` призначено лише для +вбудованих ідентифікаторів agent harness, які ще не мають поля володіння. -Цей блок є лише метаданими. Він не реєструє поведінку середовища виконання і не -замінює `register(...)`, `setupEntry` чи інші точки входу середовища виконання/Plugin. +Цей блок містить лише метадані. Він не реєструє поведінку часу виконання і не +замінює `register(...)`, `setupEntry` чи інші точки входу runtime/Plugin. Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому -відсутність метаданих активації не під час запуску зазвичай впливає лише на продуктивність; це -не має змінювати коректність, доки ще існують резервні варіанти володіння з маніфесту. +відсутність метаданих активації, не пов'язаних із запуском, зазвичай коштує лише продуктивності; це +не має змінювати коректність, доки все ще існують резервні механізми володіння з маніфесту. -Кожен Plugin має навмисно встановлювати `activation.onStartup`. Установіть його в `true` -лише тоді, коли Plugin має запускатися під час запуску Gateway. Установіть його в `false`, коли -Plugin неактивний під час запуску й має завантажуватися лише за вужчими тригерами. -Пропуск `onStartup` більше не завантажує Plugin під час запуску неявно; використовуйте явні -метадані активації для запуску, каналу, конфігурації, агентної обв’язки, пам’яті або +Кожен Plugin має встановлювати `activation.onStartup` навмисно. Установлюйте його в `true` +лише тоді, коли Plugin повинен запускатися під час старту Gateway. Установлюйте його в `false`, коли +Plugin інертний під час старту і має завантажуватися лише за вужчими тригерами. +Пропуск `onStartup` більше не завантажує Plugin під час старту неявно; використовуйте явні +метадані активації для старту, каналу, конфігурації, agent harness, пам'яті або інших вужчих тригерів активації. ```json @@ -286,45 +424,45 @@ Plugin неактивний під час запуску й має завант } ``` -| Поле | Обов’язково | Тип | Що це означає | -| ------------------ | ----------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `onStartup` | Ні | `boolean` | Явна активація під час запуску Gateway. Кожен Plugin має встановлювати це поле. `true` імпортує Plugin під час запуску; `false` залишає його ледачим щодо запуску, якщо інший відповідний тригер не вимагає завантаження. | -| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження. | -| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори середовища виконання вбудованих агентних обв’язок, які мають включати цей Plugin до планів активації/завантаження. Використовуйте верхньорівневий `cliBackends` для псевдонімів бекендів CLI. | -| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Види маршрутів, які мають включати цей Plugin до планів активації/завантаження. | -| `onConfigPaths` | Ні | `string[]` | Шляхи конфігурації відносно кореня, які мають включати цей Plugin до планів запуску/завантаження, коли шлях присутній і не вимкнений явно. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки щодо можливостей, які використовує планування активації площини керування. Коли можливо, надавайте перевагу вужчим полям. | +| Поле | Обов'язкове | Тип | Що це означає | +| ------------------ | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `onStartup` | Ні | `boolean` | Явна активація під час старту Gateway. Кожен Plugin має встановлювати це поле. `true` імпортує Plugin під час старту; `false` залишає його лінивим щодо старту, якщо інший збіг тригера не потребує завантаження. | +| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження. | +| `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори часу виконання вбудованих agent harness, які мають включати цей Plugin до планів активації/завантаження. Використовуйте верхньорівневе `cliBackends` для псевдонімів CLI-бекендів. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Види маршрутів, які мають включати цей Plugin до планів активації/завантаження. | +| `onConfigPaths` | Ні | `string[]` | Шляхи конфігурації відносно кореня, які мають включати цей Plugin до планів старту/завантаження, коли шлях присутній і не вимкнений явно. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки щодо можливостей, які використовуються плануванням активації площини керування. За можливості надавайте перевагу вужчим полям. | Поточні активні споживачі: -- Планування запуску Gateway використовує `activation.onStartup` для явного імпорту - під час запуску +- планування старту Gateway використовує `activation.onStartup` для явного імпорту + під час старту - планування CLI, ініційоване командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` -- планування запуску середовища виконання агента використовує `activation.onAgentHarnesses` для - вбудованих обв’язок і верхньорівневий `cliBackends[]` для псевдонімів середовища виконання CLI -- планування налаштування/каналу, ініційоване каналом, повертається до застарілого володіння +- планування старту agent-runtime використовує `activation.onAgentHarnesses` для + вбудованих harness і верхньорівневе `cliBackends[]` для CLI runtime-псевдонімів +- планування setup/каналів, ініційоване каналом, повертається до застарілого володіння `channels[]`, коли явні метадані активації каналу відсутні -- планування Plugin під час запуску використовує `activation.onConfigPaths` для неканальних кореневих - поверхонь конфігурації, як-от блок `browser` вбудованого браузерного Plugin -- планування налаштування/середовища виконання, ініційоване провайдером, повертається до застарілого - володіння `providers[]` і верхньорівневого `cliBackends[]`, коли явні метадані - активації провайдера відсутні +- планування Plugin під час старту використовує `activation.onConfigPaths` для неканальних кореневих + поверхонь конфігурації, таких як блок `browser` у вбудованому browser Plugin +- планування setup/runtime, ініційоване провайдером, повертається до застарілого володіння + `providers[]` і верхньорівневого `cliBackends[]`, коли явні метадані активації провайдера + відсутні Діагностика планувальника може відрізняти явні підказки активації від резервного володіння з маніфесту. Наприклад, `activation-command-hint` означає, що -`activation.onCommands` збігся, тоді як `manifest-command-alias` означає, що +збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що планувальник використав володіння `commandAliases` натомість. Ці мітки причин призначені для -діагностики хоста й тестів; автори Plugin мають продовжувати оголошувати метадані, +діагностики хоста і тестів; автори Plugin мають продовжувати оголошувати метадані, які найкраще описують володіння. -## Довідник qaRunners +## Довідник з qaRunners -Використовуйте `qaRunners`, коли Plugin додає один або кілька транспортних раннерів під -спільним коренем `openclaw qa`. Залишайте ці метадані дешевими й статичними; середовище -виконання Plugin і далі володіє фактичною реєстрацією CLI через легку +Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runners під +спільним коренем `openclaw qa`. Зберігайте ці метадані дешевими і статичними; runtime Plugin +усе одно володіє фактичною реєстрацією CLI через легковагову поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json @@ -338,15 +476,15 @@ Plugin неактивний під час запуску й має завант } ``` -| Поле | Обов’язково | Тип | Що це означає | -| ------------- | ----------- | -------- | ----------------------------------------------------------------------------- | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | -| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна команда-заглушка. | +| Поле | Обов'язкове | Тип | Що це означає | +| ------------- | -------- | -------- | ------------------------------------------------------------------ | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. | -## Довідник setup +## Довідник з setup -Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні дешеві метадані, що належать Plugin, -перед завантаженням середовища виконання. +Використовуйте `setup`, коли поверхням налаштування та початкового налаштування потрібні дешеві метадані, +що належать Plugin, до завантаження runtime. ```json { @@ -374,53 +512,81 @@ Plugin неактивний під час запуску й має завант } ``` -Верхньорівневий `cliBackends` залишається чинним і далі описує бекенди виведення CLI. `setup.cliBackends` — це специфічна для налаштування поверхня дескрипторів для потоків площини керування/налаштування, які мають залишатися лише метаданими. +Верхньорівневе `cliBackends` залишається чинним і продовжує описувати бекенди +виведення CLI. `setup.cliBackends` — це специфічна для setup поверхня дескрипторів для +потоків площини керування/setup, які мають залишатися лише метаданими. -Коли наявні `setup.providers` і `setup.cliBackends`, вони є бажаною поверхнею пошуку за дескрипторами для виявлення налаштування. Якщо дескриптор лише звужує кандидатний Plugin, а налаштування все ще потребує багатших runtime-хуків під час налаштування, задайте `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. +Коли вони присутні, `setup.providers` і `setup.cliBackends` є бажаною +descriptor-first поверхнею пошуку для виявлення setup. Якщо дескриптор лише +звужує кандидатний Plugin, а setup все ще потребує багатших runtime hooks під час setup, +установіть `requiresRuntime: true` і залиште `setup-api` як +резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` до загальних пошуків автентифікації провайдера та env-var. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом вікна застарівання, але не вбудовані plugins, які все ще його використовують, отримують діагностику маніфесту. Нові plugins мають розміщувати метадані env для налаштування/статусу в `setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` до загальної автентифікації провайдерів і +пошуку env vars. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності +протягом вікна застарівання, але невбудовані Plugin, які все ще використовують його, +отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані env для setup/status +у `setup.providers[].envVars`. -OpenClaw також може виводити прості варіанти налаштування з `setup.providers[].authMethods`, коли запис налаштування відсутній або коли `setup.requiresRuntime: false` оголошує, що runtime налаштування не потрібний. Явні записи `providerAuthChoices` залишаються бажаними для власних міток, прапорців CLI, області onboarding і метаданих асистента. +OpenClaw також може виводити прості варіанти setup з `setup.providers[].authMethods`, +коли запис setup недоступний або коли `setup.requiresRuntime: false` +оголошує, що runtime для setup не потрібен. Явні записи `providerAuthChoices` залишаються +бажаними для власних міток, CLI-прапорів, області початкового налаштування і метаданих асистента. -Задавайте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні налаштування. OpenClaw розглядає явне `false` як контракт лише на основі дескрипторів і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку налаштування. Якщо Plugin лише з дескрипторами все одно постачає один із цих runtime-записів налаштування, OpenClaw повідомляє додаткову діагностику й далі його ігнорує. Пропущений `requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні plugins, які додали дескриптори без прапорця, не ламалися. +Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для +поверхні setup. OpenClaw трактує явне `false` як descriptor-only контракт +і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо +descriptor-only Plugin усе ще постачає один із цих runtime-записів setup, +OpenClaw повідомляє додаткову діагностику і продовжує ігнорувати його. Пропущене +`requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні Plugin, які додали +дескриптори без цього прапора, не зламалися. -Оскільки пошук налаштування може виконувати належний Plugin код `setup-api`, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед виявлених plugins. Неоднозначне володіння завершується закритою помилкою замість вибору переможця за порядком виявлення. +Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, нормалізовані +значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед +виявлених Plugin. Неоднозначне володіння завершується відмовою замість вибору +переможця з порядку виявлення. -Коли runtime налаштування виконується, діагностика реєстру налаштування повідомляє про розбіжність дескрипторів, якщо `setup-api` реєструє провайдера або бекенд CLI, який не оголошено в дескрипторах маніфесту, або якщо дескриптор не має відповідної runtime-реєстрації. Ці діагностики є додатковими й не відхиляють застарілі plugins. +Коли runtime setup виконується, діагностика реєстру setup повідомляє про дрейф дескрипторів, +якщо `setup-api` реєструє провайдера або CLI-бекенд, який дескриптори маніфесту +не оголошують, або якщо дескриптор не має відповідної runtime-реєстрації. +Ці діагностики є додатковими і не відхиляють застарілі Plugin. -### Довідник setup.providers +### Довідник з setup.providers -| Поле | Обов'язково | Тип | Що це означає | -| ------------- | ----------- | ---------- | ---------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Ідентифікатор провайдера, відкритий під час налаштування або onboarding. Тримайте нормалізовані ідентифікатори глобально унікальними. | -| `authMethods` | Ні | `string[]` | Ідентифікатори методів налаштування/автентифікації, які цей провайдер підтримує без завантаження повного runtime. | -| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні налаштування/статусу можуть перевіряти до завантаження runtime Plugin. | -| `authEvidence` | Ні | `object[]` | Дешеві локальні перевірки доказів автентифікації для провайдерів, які можуть автентифікуватися через несекретні маркери. | +| Поле | Обов'язкове | Тип | Що це означає | +| -------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------ | +| `id` | Так | `string` | Ідентифікатор провайдера, відкритий під час setup або початкового налаштування. Зберігайте нормалізовані ідентифікатори глобально унікальними. | +| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/auth, які цей провайдер підтримує без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/status можуть перевіряти до завантаження runtime Plugin. | +| `authEvidence` | Ні | `object[]` | Дешеві локальні перевірки доказів auth для провайдерів, які можуть автентифікуватися через несекретні маркери. | -`authEvidence` призначено для належних провайдеру локальних маркерів облікових даних, які можна перевірити без завантаження runtime-коду. Ці перевірки мають залишатися дешевими й локальними: без мережевих викликів, без читання keychain або secret-manager, без shell-команд і без перевірок API провайдера. +`authEvidence` призначено для локальних маркерів облікових даних, якими володіє провайдер і які можна +перевірити без завантаження runtime-коду. Ці перевірки мають залишатися дешевими й локальними: +без мережевих викликів, без читання keychain або менеджера секретів, без команд shell і без +перевірок API провайдера. Підтримувані записи доказів: -| Поле | Обов'язково | Тип | Що це означає | -| ----------------- | ----------- | ---------- | --------------------------------------------------------------------------------------------------------------- | -| `type` | Так | `string` | Наразі `local-file-with-env`. | -| `fileEnvVar` | Ні | `string` | Env var, що містить явний шлях до файлу облікових даних. | -| `fallbackPaths` | Ні | `string[]` | Локальні шляхи до файлів облікових даних, які перевіряються, коли `fileEnvVar` відсутня або порожня. Підтримує `${HOME}` і `${APPDATA}`. | -| `requiresAnyEnv` | Ні | `string[]` | Принаймні одна з перелічених env var має бути непорожньою, перш ніж доказ стане чинним. | -| `requiresAllEnv` | Ні | `string[]` | Кожна з перелічених env var має бути непорожньою, перш ніж доказ стане чинним. | -| `credentialMarker` | Так | `string` | Несекретний маркер, що повертається, коли доказ наявний. | -| `source` | Ні | `string` | Видима користувачу мітка джерела для виводу автентифікації/статусу. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------------ | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------- | +| `type` | Так | `string` | Наразі `local-file-with-env`. | +| `fileEnvVar` | Ні | `string` | Env var, що містить явний шлях до файлу облікових даних. | +| `fallbackPaths` | Ні | `string[]` | Локальні шляхи до файлів облікових даних, які перевіряються, коли `fileEnvVar` відсутній або порожній. Підтримує `${HOME}` і `${APPDATA}`. | +| `requiresAnyEnv` | Ні | `string[]` | Принаймні одна із перелічених env var має бути непорожньою, перш ніж доказ буде дійсним. | +| `requiresAllEnv` | Ні | `string[]` | Кожна перелічена env var має бути непорожньою, перш ніж доказ буде дійсним. | +| `credentialMarker` | Так | `string` | Несекретний маркер, що повертається, коли доказ присутній. | +| `source` | Ні | `string` | Зручна для користувача мітка джерела для виводу автентифікації/стану. | -### Поля setup +### поля setup -| Поле | Обов'язково | Тип | Що це означає | -| ----------------- | ----------- | ---------- | ------------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори налаштування провайдера, відкриті під час налаштування та onboarding. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів під час налаштування, що використовуються для пошуку налаштування спершу за дескрипторами. Тримайте нормалізовані ідентифікатори глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, що належать поверхні налаштування цього Plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи налаштуванню все ще потрібне виконання `setup-api` після пошуку за дескрипторами. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------------ | -------- | ---------- | ---------------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори налаштування провайдера, доступні під час setup і onboarding. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори backend для часу setup, що використовуються для пошуку setup спочатку за дескриптором. Тримайте нормалізовані ідентифікатори глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи все ще потребує setup виконання `setup-api` після пошуку дескриптора. | -## Довідник uiHints +## довідка uiHints `uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу. @@ -439,18 +605,19 @@ 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 +## довідка contracts -Використовуйте `contracts` лише для статичних метаданих володіння capability, які OpenClaw може читати без імпорту runtime Plugin. +Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може +читати без імпорту runtime plugin. ```json { @@ -472,34 +639,53 @@ OpenClaw також може виводити прості варіанти на } ``` -Кожен список є необов'язковим: +Кожен список є необов’язковим: -| Поле | Тип | Що це означає | -| -------------------------------- | ---------- | ----------------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик розширень app-server Codex, наразі `codex-app-server`. | -| `agentToolResultMiddleware` | `string[]` | Runtime-ідентифікатори, для яких вбудований Plugin може реєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, чиїм хуком зовнішнього профілю автентифікації володіє цей Plugin. | -| `speechProviders` | `string[]` | Ідентифікатори провайдерів мовлення, якими володіє цей Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime-транскрипції, якими володіє цей Plugin. | -| `realtimeVoiceProviders` | `string[]` | Ідентифікатори realtime-voice провайдерів, якими володіє цей Plugin. | -| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів memory embedding, якими володіє цей Plugin. | -| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори media-understanding провайдерів, якими володіє цей Plugin. | -| `imageGenerationProviders` | `string[]` | Ідентифікатори image-generation провайдерів, якими володіє цей Plugin. | -| `videoGenerationProviders` | `string[]` | Ідентифікатори video-generation провайдерів, якими володіє цей Plugin. | -| `webFetchProviders` | `string[]` | Ідентифікатори web-fetch провайдерів, якими володіє цей Plugin. | -| `webSearchProviders` | `string[]` | Ідентифікатори web-search провайдерів, якими володіє цей Plugin. | -| `migrationProviders` | `string[]` | Ідентифікатори провайдерів імпорту, якими цей Plugin володіє для `openclaw migrate`. | -| `tools` | `string[]` | Назви інструментів агента, якими цей Plugin володіє для перевірок вбудованих контрактів. | +| Поле | Тип | Що це означає | +| -------------------------------- | ---------- | ----------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик розширень сервера застосунку Codex, наразі `codex-app-server`. | +| `agentToolResultMiddleware` | `string[]` | Runtime-ідентифікатори, для яких bundled plugin може реєструвати middleware результатів інструментів. | +| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, hook зовнішнього auth-профілю яких належить цьому plugin. | +| `speechProviders` | `string[]` | Ідентифікатори провайдерів мовлення, якими володіє цей plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів транскрипції в реальному часі, якими володіє цей plugin. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів голосу в реальному часі, якими володіє цей plugin. | +| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів embedding пам’яті, якими володіє цей plugin. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів розуміння медіа, якими володіє цей plugin. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації зображень, якими володіє цей plugin. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів генерації відео, якими володіє цей plugin. | +| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей plugin. | +| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web-search, якими володіє цей plugin. | +| `migrationProviders` | `string[]` | Ідентифікатори провайдерів імпорту, якими цей plugin володіє для `openclaw migrate`. | +| `tools` | `string[]` | Назви інструментів агента, якими володіє цей plugin. | -`contracts.embeddedExtensionFactories` збережено для вбудованих фабрик розширень лише для app-server Codex. Вбудовані трансформації результатів інструментів натомість мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися через `api.registerAgentToolResultMiddleware(...)`. Зовнішні plugins не можуть реєструвати middleware результатів інструментів, бо ця межа може переписувати високодостовірний вивід інструментів до того, як його побачить модель. +`contracts.embeddedExtensionFactories` збережено для bundled фабрик розширень +лише сервера застосунку Codex. Bundled перетворення результатів інструментів мають +оголошувати `contracts.agentToolResultMiddleware` і натомість реєструватися через +`api.registerAgentToolResultMiddleware(...)`. Зовнішні plugins не можуть +реєструвати middleware результатів інструментів, бо цей seam може переписувати +високодовірений вивід інструменту до того, як модель його побачить. -Plugins провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати `contracts.externalAuthProviders`. Plugins без цього оголошення все ще проходять через застарілий резервний шлях сумісності, але цей резервний шлях повільніший і буде вилучений після вікна міграції. +Runtime-реєстрації `api.registerTool(...)` мають відповідати `contracts.tools`. +Виявлення інструментів використовує цей список, щоб завантажувати лише runtime тих plugins, які можуть володіти +запитаними інструментами. -Вбудовані провайдери memory embedding мають оголошувати `contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони відкривають, включно з вбудованими адаптерами, такими як `local`. Автономні шляхи CLI використовують цей контракт маніфесту, щоб завантажити лише належний Plugin до того, як повний runtime Gateway зареєструє провайдерів. +Provider plugins, які реалізують `resolveExternalAuthProfiles`, мають оголошувати +`contracts.externalAuthProviders`. Plugins без такого оголошення все ще проходять +через застарілий compatibility fallback, але цей fallback повільніший і +буде видалений після міграційного вікна. -## Довідник mediaUnderstandingProviderMetadata +Bundled провайдери memory embedding мають оголошувати +`contracts.memoryEmbeddingProviders` для кожного ідентифікатора adapter, який вони надають, зокрема +вбудованих adapters, таких як `local`. Автономні CLI-шляхи використовують цей manifest +contract, щоб завантажити лише власний plugin до того, як повний runtime Gateway +зареєструє провайдерів. -Використовуйте `mediaUnderstandingProviderMetadata`, коли media-understanding провайдер має стандартні моделі, пріоритет резервного auto-auth або нативну підтримку документів, які загальним core-помічникам потрібні до завантаження runtime. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. +## довідка mediaUnderstandingProviderMetadata + +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має +моделі за замовчуванням, пріоритет fallback для автоматичної автентифікації або нативну підтримку документів, які +потрібні generic core helpers до завантаження runtime. Ключі також мають бути оголошені в +`contracts.mediaUnderstandingProviders`. ```json { @@ -524,41 +710,41 @@ Plugins провайдерів, які реалізують `resolveExternalAuth Кожен запис провайдера може містити: -| Поле | Тип | Що це означає | -| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | -| `defaultModels` | `Record` | Типові відповідності можливостей моделям, що використовуються, коли конфігурація не задає модель. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні документи, які підтримує провайдер. | +| Поле | Тип | Що це означає | +| ---------------------- | ----------------------------------- | -------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | +| `defaultModels` | `Record` | Значення capability-to-model за замовчуванням, які використовуються, коли config не задає модель. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback провайдера на основі облікових даних. | +| `nativeDocumentInputs` | `"pdf"[]` | Нативні document inputs, які підтримує провайдер. | -## Довідник channelConfigs +## довідка channelConfigs -Використовуйте `channelConfigs`, коли Plugin каналу потребує дешевих метаданих конфігурації до -завантаження runtime. Виявлення налаштування/стану каналу лише для читання може використовувати ці метадані -безпосередньо для налаштованих зовнішніх каналів, коли запис налаштування недоступний, або -коли `setup.requiresRuntime: false` оголошує, що runtime налаштування не потрібен. +Використовуйте `channelConfigs`, коли channel plugin потребує дешевих метаданих config до +завантаження runtime. Виявлення setup/status лише для читання може використовувати ці метадані +безпосередньо для налаштованих зовнішніх каналів, коли запис setup недоступний, або +коли `setup.requiresRuntime: false` оголошує, що runtime setup не потрібен. -`channelConfigs` — це метадані маніфесту Plugin, а не новий розділ користувацької конфігурації -верхнього рівня. Користувачі все ще налаштовують екземпляри каналів у `channels.`. -OpenClaw читає метадані маніфесту, щоб вирішити, який Plugin володіє цим налаштованим -каналом, до виконання runtime-коду Plugin. +`channelConfigs` — це метадані manifest plugin, а не новий top-level розділ користувацької config. +Користувачі й надалі налаштовують екземпляри каналів у `channels.`. +OpenClaw читає метадані manifest, щоб вирішити, якому plugin належить цей налаштований +канал до виконання runtime-коду plugin. -Для Plugin каналу `configSchema` і `channelConfigs` описують різні +Для channel plugin `configSchema` і `channelConfigs` описують різні шляхи: - `configSchema` перевіряє `plugins.entries..config` - `channelConfigs..schema` перевіряє `channels.` -Небандловані Plugins, які оголошують `channels[]`, також мають оголошувати відповідні -записи `channelConfigs`. Без них OpenClaw все ще може завантажити Plugin, але -схема конфігурації холодного шляху, налаштування та поверхні Control UI не можуть знати -форму параметрів, що належать каналу, доки не виконається runtime Plugin. +Non-bundled plugins, які оголошують `channels[]`, також мають оголошувати відповідні +записи `channelConfigs`. Без них OpenClaw все ще може завантажити plugin, але +cold-path schema config, setup і поверхні Control UI не можуть знати +форму параметрів, що належать каналу, доки runtime plugin не виконається. `channelConfigs..commands.nativeCommandsAutoEnabled` і -`nativeSkillsAutoEnabled` можуть оголошувати статичні типові значення `auto` для перевірок конфігурації команд, -які виконуються до завантаження runtime каналу. Бандловані канали також можуть публікувати -ті самі типові значення через `package.json#openclaw.channel.commands` поряд з -іншими метаданими каталогу каналів, що належать пакету. +`nativeSkillsAutoEnabled` можуть оголошувати статичні значення `auto` за замовчуванням для перевірок config команд, +які запускаються до завантаження runtime каналу. Bundled канали також можуть публікувати +ті самі значення за замовчуванням через `package.json#openclaw.channel.commands` разом +з іншими метаданими каталогу каналів, що належать package. ```json { @@ -591,20 +777,20 @@ OpenClaw читає метадані маніфесту, щоб вирішити Кожен запис каналу може містити: -| Поле | Тип | Що це означає | -| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- | +| Поле | Тип | Що це означає | +| ------------- | ------------------------ | --------------------------------------------------------------------------------------- | | `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові мітки UI, заповнювачі та підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, що додається до поверхонь вибору й інспекції, коли runtime-метадані ще не готові. | -| `description` | `string` | Короткий опис каналу для поверхонь інспекції та каталогу. | -| `commands` | `object` | Статичні типові значення auto для нативних команд і нативних Skills у перевірках конфігурації до runtime. | -| `preferOver` | `string[]` | Ідентифікатори застарілих або нижчопріоритетних Plugins, які цей канал має випереджати на поверхнях вибору. | +| `uiHints` | `Record` | Необов’язкові UI-мітки/заповнювачі/підказки щодо чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Мітка каналу, що додається до поверхонь вибору й інспектування, коли метадані runtime ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь інспектування та каталогу. | +| `commands` | `object` | Статична нативна команда та автоматичні значення за замовчуванням для нативних skill для перевірок конфігурації до runtime. | +| `preferOver` | `string[]` | Ідентифікатори застарілих або нижчопріоритетних plugin, які цей канал має випереджати на поверхнях вибору. | -### Заміна іншого Plugin каналу +### Заміна іншого channel plugin -Використовуйте `preferOver`, коли ваш Plugin є бажаним власником для ідентифікатора каналу, який -також може надавати інший Plugin. Поширені випадки — перейменований ідентифікатор Plugin, -окремий Plugin, що замінює бандлований Plugin, або підтримуваний форк, який +Використовуйте `preferOver`, коли ваш plugin є бажаним власником для ідентифікатора каналу, який +також може надати інший plugin. Типові випадки — перейменований ідентифікатор plugin, +окремий plugin, що замінює вбудований plugin, або підтримуваний fork, який зберігає той самий ідентифікатор каналу для сумісності конфігурації. ```json @@ -626,22 +812,22 @@ OpenClaw читає метадані маніфесту, щоб вирішити } ``` -Коли `channels.chat` налаштовано, OpenClaw розглядає і ідентифікатор каналу, і -ідентифікатор бажаного Plugin. Якщо нижчопріоритетний Plugin був вибраний лише тому, що -він бандлований або ввімкнений за замовчуванням, OpenClaw вимикає його в ефективній -runtime-конфігурації, щоб один Plugin володів каналом і його інструментами. Явний вибір користувача -все одно має перевагу: якщо користувач явно вмикає обидва Plugins, OpenClaw +Коли налаштовано `channels.chat`, OpenClaw враховує ідентифікатор каналу та +ідентифікатор бажаного plugin. Якщо plugin нижчого пріоритету було вибрано лише тому, +що він вбудований або ввімкнений за замовчуванням, OpenClaw вимикає його в ефективній +runtime-конфігурації, щоб один plugin володів каналом і його інструментами. Явний вибір +користувача все одно має перевагу: якщо користувач явно вмикає обидва plugin, OpenClaw зберігає цей вибір і повідомляє діагностику дубльованих каналів/інструментів замість -мовчазної зміни запитаного набору Plugins. +тихої зміни запитаного набору plugin. -Обмежуйте `preferOver` ідентифікаторами Plugins, які справді можуть надавати той самий канал. -Це не загальне поле пріоритету і воно не перейменовує ключі користувацької конфігурації. +Обмежуйте `preferOver` ідентифікаторами plugin, які справді можуть надавати той самий канал. +Це не загальне поле пріоритету, і воно не перейменовує ключі користувацької конфігурації. ## Довідник modelSupport -Використовуйте `modelSupport`, коли OpenClaw має визначати ваш провайдерський Plugin з -коротких ідентифікаторів моделей, як-от `gpt-5.5` або `claude-sonnet-4.6`, до завантаження runtime -Plugin. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш provider plugin із +скорочених ідентифікаторів моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження +runtime plugin. ```json { @@ -655,25 +841,25 @@ Plugin. OpenClaw застосовує такий пріоритет: - явні посилання `provider/model` використовують метадані маніфесту `providers` власника -- `modelPatterns` мають пріоритет над `modelPrefixes` -- якщо збігаються один небандлований Plugin і один бандлований Plugin, перемагає небандлований - Plugin -- решта неоднозначностей ігнорується, доки користувач або конфігурація не задасть провайдера +- `modelPatterns` мають перевагу над `modelPrefixes` +- якщо збігаються один невбудований plugin і один вбудований plugin, перемагає невбудований + plugin +- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже provider Поля: -| Поле | Тип | Що це означає | -| --------------- | ---------- | ------------------------------------------------------------------------------ | -| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` із короткими ідентифікаторами моделей. | -| `modelPatterns` | `string[]` | Джерела Regex, що зіставляються з короткими ідентифікаторами моделей після вилучення суфікса профілю. | +| Поле | Тип | Що це означає | +| --------------- | ---------- | -------------------------------------------------------------------------------- | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | ## Довідник modelCatalog -Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до -завантаження runtime Plugin. Це джерело, що належить маніфесту, для фіксованих рядків каталогу, -псевдонімів провайдера, правил придушення та режиму виявлення. Runtime-оновлення -все ще належить runtime-коду провайдера, але маніфест повідомляє ядру, коли runtime -потрібен. +Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей provider до +завантаження runtime plugin. Це джерело, яким володіє маніфест, для фіксованих рядків каталогу, +псевдонімів provider, правил пригнічення та режиму виявлення. Оновлення runtime +все ще належить коду runtime provider, але маніфест повідомляє ядру, коли runtime +є обов’язковим. ```json { @@ -724,79 +910,71 @@ OpenClaw застосовує такий пріоритет: Поля верхнього рівня: -| Поле | Тип | Що це означає | -| -------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | Рядки каталогу для ідентифікаторів провайдерів, що належать цьому Plugin. Ключі також мають бути в `providers` верхнього рівня. | -| `aliases` | `Record` | Псевдоніми провайдерів, які мають розв’язуватися у власний провайдер для планування каталогу або придушення. | -| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin придушує з причини, специфічної для провайдера. | -| `discovery` | `Record` | Чи можна читати каталог провайдера з метаданих маніфесту, оновлювати його в кеш або чи потрібен runtime. | +| Поле | Тип | Що це означає | +| -------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| `providers` | `Record` | Рядки каталогу для ідентифікаторів provider, якими володіє цей plugin. Ключі також мають бути в `providers` верхнього рівня. | +| `aliases` | `Record` | Псевдоніми provider, які мають розв’язуватися у власного provider для планування каталогу або пригнічення. | +| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей plugin пригнічує з причини, специфічної для provider. | +| `discovery` | `Record` | Чи можна читати каталог provider з метаданих маніфесту, оновлювати його в cache, чи потрібен runtime. | -`aliases` бере участь у пошуку власника провайдера для планування каталогу моделей. -Цілі псевдонімів мають бути провайдерами верхнього рівня, що належать тому самому Plugin. Коли -список, відфільтрований за провайдером, використовує псевдонім, OpenClaw може прочитати маніфест власника і -застосувати перевизначення API/base URL псевдоніма без завантаження runtime провайдера. -Псевдоніми не розгортають нефільтровані списки каталогу; широкі списки виводять лише -рядки канонічного провайдера-власника. +`aliases` бере участь у пошуку власника provider для планування model-catalog. +Цілі псевдонімів мають бути provider верхнього рівня, якими володіє той самий plugin. Коли +відфільтрований за provider список використовує псевдонім, OpenClaw може прочитати маніфест власника та +застосувати перевизначення API/base URL псевдоніма без завантаження runtime provider. +Псевдоніми не розгортають нефільтровані списки каталогу; широкі списки виводять лише рядки +канонічного provider-власника. -`suppressions` замінює старий runtime-хук провайдера `suppressBuiltInModel`. -Записи придушення враховуються лише тоді, коли провайдер належить Plugin або -оголошений як ключ `modelCatalog.aliases`, що вказує на власного провайдера. Runtime-хуки -придушення більше не викликаються під час розв’язання моделі. +`suppressions` замінює старий runtime-хук provider `suppressBuiltInModel`. +Записи пригнічення враховуються лише тоді, коли provider належить plugin або +оголошений як ключ `modelCatalog.aliases`, що вказує на власний provider. Runtime +хуки пригнічення більше не викликаються під час розв’язання моделей. -Поля провайдера: +Поля provider: -| Поле | Тип | Що це означає | -| --------- | ------------------------ | ----------------------------------------------------------------- | -| `baseUrl` | `string` | Необов’язковий типовий базовий URL для моделей у цьому каталозі провайдера. | -| `api` | `ModelApi` | Необов’язковий типовий API-адаптер для моделей у цьому каталозі провайдера. | -| `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до цього каталогу провайдера. | -| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | +| Поле | Тип | Що це означає | +| --------- | ------------------------ | ------------------------------------------------------------------- | +| `baseUrl` | `string` | Необов’язковий базовий URL за замовчуванням для моделей у цьому каталозі provider. | +| `api` | `ModelApi` | Необов’язковий API-адаптер за замовчуванням для моделей у цьому каталозі provider. | +| `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до цього каталогу provider. | +| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | Поля моделі: -| Поле | Тип | Що це означає | -| --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| `id` | `string` | Локальний для провайдера ідентифікатор моделі, без префікса `provider/`. | -| `name` | `string` | Необов’язкова відображувана назва. | -| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | -| `baseUrl` | `string` | Необов’язкове перевизначення базової URL-адреси для окремої моделі. | -| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | -| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | -| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | -| `contextWindow` | `number` | Нативне контекстне вікно провайдера. | -| `contextTokens` | `number` | Необов’язкове ефективне обмеження контексту під час виконання, якщо воно відрізняється від `contextWindow`. | -| `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | -| `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, зокрема необов’язкове `tieredPricing`. | +| Поле | Тип | Що це означає | +| --------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- | +| `id` | `string` | Локальний для provider ідентифікатор моделі, без префікса `provider/`. | +| `name` | `string` | Необов’язкова відображувана назва. | +| `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | +| `baseUrl` | `string` | Необов’язкове перевизначення базового URL для окремої моделі. | +| `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | +| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | +| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | +| `contextWindow` | `number` | Нативне вікно контексту provider. | +| `contextTokens` | `number` | Необов’язкове ефективне обмеження контексту runtime, коли воно відрізняється від `contextWindow`. | +| `maxTokens` | `number` | Максимальна кількість вихідних токенів, коли вона відома. | +| `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, зокрема необов’язковий `tieredPricing`. | | `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделей OpenClaw. | | `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Пригнічуйте лише тоді, коли рядок узагалі не має з’являтися. | -| `statusReason` | `string` | Необов’язкова причина, що показується зі статусом, відмінним від available. | -| `replaces` | `string[]` | Старіші локальні для провайдера ідентифікатори моделей, які ця модель замінює. | -| `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-замінника для застарілих рядків. | -| `tags` | `string[]` | Стабільні теги, які використовують засоби вибору й фільтри. | +| `statusReason` | `string` | Необов’язкова причина, що показується зі статусом, відмінним від available. | +| `replaces` | `string[]` | Старіші локальні для provider ідентифікатори моделей, які ця модель замінює. | +| `replacedBy` | `string` | Локальний для provider ідентифікатор моделі-замінника для deprecated-рядків. | +| `tags` | `string[]` | Стабільні теги, що використовуються засобами вибору та фільтрами. | Поля пригнічення: -| Поле | Тип | Що це означає | -| -------------------------- | ---------- | -------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | Ідентифікатор провайдера для upstream-рядка, який треба пригнітити. Має належати цьому plugin або бути оголошеним як належний alias. | -| `model` | `string` | Локальний для провайдера ідентифікатор моделі, який треба пригнітити. | +| Поле | Тип | Що це означає | +| -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- | +| `provider` | `string` | Ідентифікатор provider для upstream-рядка, який потрібно пригнітити. Має належати цьому plugin або бути оголошеним як власний псевдонім. | +| `model` | `string` | Локальний для provider ідентифікатор моделі, який потрібно пригнітити. | | `reason` | `string` | Необов’язкове повідомлення, що показується, коли пригнічений рядок запитують напряму. | -| `when.baseUrlHosts` | `string[]` | Необов’язковий список ефективних хостів базової URL-адреси провайдера, потрібних для застосування пригнічення. | -| `when.providerConfigApiIn` | `string[]` | Необов’язковий список точних значень `api` конфігурації провайдера, потрібних для застосування пригнічення. | +| `when.baseUrlHosts` | `string[]` | Необов’язковий список ефективних хостів базового URL provider, потрібних до застосування пригнічення. | +| `when.providerConfigApiIn` | `string[]` | Необов’язковий список точних значень `api` конфігурації provider, потрібних до застосування пригнічення. | -Не розміщуйте дані лише часу виконання в `modelCatalog`. Використовуйте `static` лише тоді, коли -рядки маніфесту достатньо повні, щоб поверхні списків із фільтрацією за провайдером і засоби вибору могли пропускати -виявлення registry/runtime. Використовуйте `refreshable`, коли рядки маніфесту корисні -як початкові елементи списку або доповнення, але оновлення/кеш може додати більше рядків пізніше; -рядки refreshable самі по собі не є авторитетними. Використовуйте `runtime`, коли OpenClaw -має завантажити runtime провайдера, щоб знати список. +Не розміщуйте дані, призначені лише для середовища виконання, у `modelCatalog`. Використовуйте `static` лише тоді, коли рядки маніфесту достатньо повні, щоб поверхні списку та вибору, відфільтровані за провайдером, могли пропускати виявлення через реєстр/середовище виконання. Використовуйте `refreshable`, коли рядки маніфесту корисні як перелічувані початкові дані або доповнення, але оновлення/кеш зможе додати більше рядків пізніше; рядки `refreshable` самі по собі не є авторитетними. Використовуйте `runtime`, коли OpenClaw має завантажити середовище виконання провайдера, щоб дізнатися список. -## Довідник modelIdNormalization +## Довідка з modelIdNormalization -Використовуйте `modelIdNormalization` для дешевого очищення ідентифікаторів моделей, що належить провайдеру і має -відбутися до завантаження runtime провайдера. Це зберігає alias-и, як-от короткі назви моделей, -локальні для провайдера legacy-ідентифікатори та правила префіксів проксі, у маніфесті plugin-власника -замість таблиць вибору моделей у core. +Використовуйте `modelIdNormalization` для дешевого очищення ідентифікаторів моделей, що належить провайдеру й має відбутися до завантаження середовища виконання провайдера. Це залишає псевдоніми, як-от короткі назви моделей, застарілі локальні для провайдера ідентифікатори та правила префіксів проксі, у маніфесті власного plugin, а не в таблицях вибору моделей ядра. ```json { @@ -818,35 +996,31 @@ OpenClaw застосовує такий пріоритет: Поля провайдера: -| Поле | Тип | Що це означає | -| ------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------- | -| `aliases` | `Record` | Точні alias-и ідентифікаторів моделей без урахування регістру. Значення повертаються як записані. | -| `stripPrefixes` | `string[]` | Префікси, які треба вилучити перед пошуком alias; корисно для legacy-дублювання provider/model. | -| `prefixWhenBare` | `string` | Префікс, який треба додати, коли нормалізований ідентифікатор моделі ще не містить `/`. | -| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префіксів для bare-ідентифікаторів після пошуку alias, ключовані за `modelPrefix` і `prefix`. | +| Поле | Тип | Що це означає | +| ------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------------------- | +| `aliases` | `Record` | Точні псевдоніми ідентифікаторів моделей без урахування регістру. Значення повертаються як написані. | +| `stripPrefixes` | `string[]` | Префікси для видалення перед пошуком псевдоніма, корисно для застарілого дублювання провайдер/модель. | +| `prefixWhenBare` | `string` | Префікс для додавання, коли нормалізований ідентифікатор моделі ще не містить `/`. | +| `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префіксів для простих ідентифікаторів після пошуку псевдоніма, задані `modelPrefix` і `prefix`. | -## Довідник providerEndpoints +## Довідка з providerEndpoints -Використовуйте `providerEndpoints` для класифікації endpoint-ів, яку загальна політика запитів -має знати до завантаження runtime провайдера. Core усе ще визначає значення кожного -`endpointClass`; маніфести plugin володіють метаданими хоста й базової URL-адреси. +Використовуйте `providerEndpoints` для класифікації кінцевих точок, яку загальна політика запитів має знати до завантаження середовища виконання провайдера. Ядро все ще визначає значення кожного `endpointClass`; маніфести plugin визначають метадані хоста й базової URL-адреси. -Поля endpoint-а: +Поля кінцевої точки: -| Поле | Тип | Що це означає | -| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------- | -| `endpointClass` | `string` | Відомий core-клас endpoint-а, наприклад `openrouter`, `moonshot-native` або `google-vertex`. | -| `hosts` | `string[]` | Точні імена хостів, що відповідають класу endpoint-а. | -| `hostSuffixes` | `string[]` | Суфікси хостів, що відповідають класу endpoint-а. Додавайте префікс `.` для зіставлення лише суфікса домену. | -| `baseUrls` | `string[]` | Точні нормалізовані базові HTTP(S) URL-адреси, що відповідають класу endpoint-а. | -| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | -| `googleVertexRegionHostSuffix` | `string` | Суфікс, який треба вилучити з відповідних хостів, щоб відкрити префікс регіону Google Vertex. | +| Поле | Тип | Що це означає | +| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------- | +| `endpointClass` | `string` | Відомий клас кінцевої точки ядра, як-от `openrouter`, `moonshot-native` або `google-vertex`. | +| `hosts` | `string[]` | Точні імена хостів, що зіставляються з класом кінцевої точки. | +| `hostSuffixes` | `string[]` | Суфікси хостів, що зіставляються з класом кінцевої точки. Додайте префікс `.` для зіставлення лише суфіксів доменів. | +| `baseUrls` | `string[]` | Точні нормалізовані базові HTTP(S) URL-адреси, що зіставляються з класом кінцевої точки. | +| `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | +| `googleVertexRegionHostSuffix` | `string` | Суфікс, який потрібно прибрати з відповідних хостів, щоб відкрити префікс регіону Google Vertex. | -## Довідник providerRequest +## Довідка з providerRequest -Використовуйте `providerRequest` для дешевих метаданих сумісності запитів, потрібних загальній -політиці запитів без завантаження runtime провайдера. Залишайте специфічне для поведінки -переписування payload у runtime hooks провайдера або спільних helper-ах родини провайдерів. +Використовуйте `providerRequest` для дешевих метаданих сумісності запитів, потрібних загальній політиці запитів без завантаження середовища виконання провайдера. Переписування payload, специфічне для поведінки, залишайте в хуках середовища виконання провайдера або спільних допоміжних засобах сімейства провайдерів. ```json { @@ -866,17 +1040,15 @@ OpenClaw застосовує такий пріоритет: Поля провайдера: -| Поле | Тип | Що це означає | -| --------------------- | ------------ | ------------------------------------------------------------------------------------ | -| `family` | `string` | Мітка родини провайдера, яку використовують загальні рішення й діагностика сумісності запитів. | -| `compatibilityFamily` | `"moonshot"` | Необов’язковий bucket сумісності родини провайдера для спільних helper-ів запитів. | -| `openAICompletions` | `object` | Прапорці запитів completions, сумісних з OpenAI, наразі `supportsStreamingUsage`. | +| Поле | Тип | Що це означає | +| --------------------- | ------------ | ------------------------------------------------------------------------------------------------- | +| `family` | `string` | Мітка сімейства провайдера, яку використовують загальні рішення щодо сумісності запитів і діагностика. | +| `compatibilityFamily` | `"moonshot"` | Необов’язкова група сумісності сімейства провайдера для спільних допоміжних засобів запитів. | +| `openAICompletions` | `object` | Прапорці запитів завершень, сумісних з OpenAI, наразі `supportsStreamingUsage`. | -## Довідник modelPricing +## Довідка з modelPricing -Використовуйте `modelPricing`, коли провайдеру потрібна поведінка ціноутворення control plane до -завантаження runtime. Кеш цін Gateway читає ці метадані без імпорту -runtime-коду провайдера. +Використовуйте `modelPricing`, коли провайдеру потрібна поведінка ціноутворення на рівні control plane до завантаження середовища виконання. Кеш ціноутворення Gateway читає ці метадані без імпорту коду середовища виконання провайдера. ```json { @@ -899,139 +1071,119 @@ runtime-коду провайдера. Поля провайдера: -| Поле | Тип | Що це означає | -| ------------ | ----------------- | -------------------------------------------------------------------------------------------------- | -| `external` | `boolean` | Установіть `false` для локальних/self-hosted провайдерів, які ніколи не мають отримувати ціни OpenRouter або LiteLLM. | -| `openRouter` | `false \| object` | Відображення для пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера. | -| `liteLLM` | `false \| object` | Відображення для пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера. | +| Поле | Тип | Що це означає | +| ------------ | ----------------- | -------------------------------------------------------------------------------------------------------------- | +| `external` | `boolean` | Установіть `false` для локальних/самостійно розміщених провайдерів, які ніколи не повинні отримувати ціни OpenRouter або LiteLLM. | +| `openRouter` | `false \| object` | Зіставлення для пошуку цін OpenRouter. `false` вимикає пошук OpenRouter для цього провайдера. | +| `liteLLM` | `false \| object` | Зіставлення для пошуку цін LiteLLM. `false` вимикає пошук LiteLLM для цього провайдера. | Поля джерела: -| Поле | Тип | Що це означає | -| -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------- | -| `provider` | `string` | Ідентифікатор провайдера в зовнішньому каталозі, коли він відрізняється від ідентифікатора провайдера OpenClaw, наприклад `z-ai` для провайдера `zai`. | -| `passthroughProviderModel` | `boolean` | Розглядайте ідентифікатори моделей зі скісною рискою як вкладені посилання provider/model; корисно для проксі-провайдерів, як-от OpenRouter. | +| Поле | Тип | Що це означає | +| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------ | +| `provider` | `string` | Ідентифікатор провайдера зовнішнього каталогу, коли він відрізняється від ідентифікатора провайдера OpenClaw, наприклад `z-ai` для провайдера `zai`. | +| `passthroughProviderModel` | `boolean` | Розглядати ідентифікатори моделей, що містять slash, як вкладені посилання провайдер/модель; корисно для проксі-провайдерів, таких як OpenRouter. | | `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти ідентифікаторів моделей зовнішнього каталогу. `version-dots` пробує ідентифікатори версій із крапками, як-от `claude-opus-4.6`. | -### OpenClaw Provider Index +### Індекс провайдерів OpenClaw -OpenClaw Provider Index — це preview-метадані, що належать OpenClaw, для провайдерів, -чиї plugins можуть ще не бути встановлені. Він не є частиною маніфесту plugin. -Маніфести plugin залишаються авторитетним джерелом для встановлених plugin. Provider Index — це -внутрішній fallback-контракт, який майбутні поверхні installable-provider і pre-install -model picker використовуватимуть, коли plugin провайдера не встановлено. +Індекс провайдерів OpenClaw — це попередні метадані, якими володіє OpenClaw, для провайдерів, чиї plugins можуть ще не бути встановлені. Він не є частиною маніфесту plugin. Маніфести plugin залишаються авторитетним джерелом для встановлених plugin. Індекс провайдерів — це внутрішній резервний контракт, який майбутні поверхні встановлюваних провайдерів і вибору моделей до встановлення використовуватимуть, коли plugin провайдера не встановлено. Порядок авторитетності каталогу: 1. Конфігурація користувача. -2. Маніфест установленого plugin `modelCatalog`. +2. `modelCatalog` маніфесту встановленого plugin. 3. Кеш каталогу моделей після явного оновлення. -4. Preview-рядки OpenClaw Provider Index. +4. Попередні рядки Індексу провайдерів OpenClaw. -Індекс провайдерів не повинен містити секрети, увімкнений стан, runtime hooks або -актуальні дані моделей, специфічні для облікового запису. Його preview-каталоги використовують ту саму -форму рядка провайдера `modelCatalog`, що й маніфести Plugin, але мають залишатися обмеженими -стабільними метаданими відображення, якщо поля runtime adapter, як-от `api`, -`baseUrl`, ціни або прапорці сумісності, не підтримуються навмисно узгодженими з -маніфестом установленого Plugin. Провайдери з актуальним виявленням `/models` мають -записувати оновлені рядки через явний шлях кешу каталогу моделей, а не -змушувати звичайний listing або onboarding викликати API провайдера. +Індекс провайдерів не повинен містити секрети, увімкнений стан, хуки середовища виконання або живі дані моделей, специфічні для облікового запису. Його попередні каталоги використовують ту саму форму рядка провайдера `modelCatalog`, що й маніфести plugin, але мають залишатися обмеженими стабільними метаданими відображення, якщо поля адаптера середовища виконання, як-от `api`, `baseUrl`, ціноутворення або прапорці сумісності, не підтримуються навмисно узгодженими з маніфестом встановленого plugin. Провайдери з живим виявленням `/models` мають записувати оновлені рядки через явний шлях кешу каталогу моделей, а не змушувати звичайне виведення списку чи onboarding викликати API провайдера. -Записи Індексу провайдерів також можуть містити метадані installable-plugin для провайдерів, -чий Plugin переміщено з core або який інакше ще не встановлено. Ці -метадані віддзеркалюють патерн каталогу каналів: назви пакета, npm install spec, -очікуваної цілісності та дешевих міток вибору автентифікації достатньо, щоб показати -опцію installable setup. Після встановлення Plugin його маніфест перемагає, а -запис Індексу провайдерів ігнорується для цього провайдера. +Записи Індексу провайдерів також можуть містити метадані встановлюваного plugin для провайдерів, чий plugin було винесено з ядра або який інакше ще не встановлено. Ці метадані віддзеркалюють шаблон каталогу каналів: назви пакета, специфікації встановлення npm, очікуваної цілісності та дешевих міток вибору автентифікації достатньо, щоб показати встановлюваний варіант налаштування. Після встановлення plugin його маніфест має пріоритет, а запис Індексу провайдерів для цього провайдера ігнорується. -Застарілі capability-ключі верхнього рівня вважаються deprecated. Використовуйте `openclaw doctor --fix`, щоб -перемістити `speechProviders`, `realtimeTranscriptionProviders`, -`realtimeVoiceProviders`, `mediaUnderstandingProviders`, -`imageGenerationProviders`, `videoGenerationProviders`, -`webFetchProviders` і `webSearchProviders` під `contracts`; звичайне -завантаження маніфесту більше не трактує ці поля верхнього рівня як ownership -capability. +Застарілі capability-ключі верхнього рівня застаріли. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під `contracts`; звичайне завантаження маніфесту більше не розглядає ці поля верхнього рівня як ownership capability. -## Маніфест проти package.json +## Маніфест порівняно з package.json Ці два файли виконують різні завдання: -| Файл | Для чого використовувати | -| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані вибору автентифікації та UI-підказки, які мають існувати до запуску коду Plugin | -| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoints, install gating, setup або метаданих каталогу | +| Файл | Для чого використовувати | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.plugin.json` | Виявлення, перевірка конфігурації, метадані вибору автентифікації та підказки UI, які мають існувати до запуску коду plugin | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для entrypoints, обмеження встановлення, налаштування або метаданих каталогу | -Якщо ви не впевнені, де мають бути певні метадані, користуйтеся таким правилом: +Якщо ви не впевнені, де має бути певний фрагмент метаданих, використовуйте це правило: -- якщо OpenClaw має знати це перед завантаженням коду Plugin, помістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, entry files або поведінки npm install, помістіть це в `package.json` +- якщо OpenClaw має знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json` +- якщо це стосується пакування, entry files або поведінки встановлення npm, помістіть це в `package.json` -### Поля package.json, які впливають на виявлення +### Поля package.json, що впливають на виявлення -Деякі pre-runtime метадані Plugin навмисно розміщуються в `package.json` у -блоці `openclaw`, а не в `openclaw.plugin.json`. +Деякі метадані plugin до середовища виконання навмисно зберігаються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | +| Поле | Що це означає | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | Оголошує native entrypoints Plugin. Має залишатися всередині директорії пакета Plugin. | -| `openclaw.runtimeExtensions` | Оголошує built JavaScript runtime entrypoints для встановлених пакетів. Має залишатися всередині директорії пакета Plugin. | -| `openclaw.setupEntry` | Легкий setup-only entrypoint, що використовується під час onboarding, відкладеного запуску каналу та read-only статусу каналу/виявлення SecretRef. Має залишатися всередині директорії пакета Plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript setup entrypoint для встановлених пакетів. Потребує `setupEntry`, має існувати й має залишатися всередині директорії пакета Plugin. | -| `openclaw.channel` | Дешеві метадані каталогу каналів, як-от labels, docs paths, aliases і selection copy. | -| `openclaw.channel.commands` | Статичні native command і native skill auto-default метадані, які використовуються поверхнями config, audit і command-list до завантаження channel runtime. | -| `openclaw.channel.configuredState` | Легкі метадані перевірки configured-state, що можуть відповісти, «чи вже існує env-only setup?» без завантаження повного channel runtime. | -| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки persisted-auth, що можуть відповісти, «чи вже є щось авторизоване?» без завантаження повного channel runtime. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки install/update для bundled і зовні опублікованих Plugins. | -| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія OpenClaw host, з semver floor на кшталт `>=2026.3.22` або `>=2026.5.1-beta.1`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; install і update flows перевіряють отриманий артефакт за ним. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях recovery з перевстановленням bundled-plugin, коли конфігурація недійсна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дає змогу setup-only поверхням каналу завантажуватися перед повним Plugin каналу під час запуску. | +| `openclaw.extensions` | Оголошує нативні точки входу Plugin. Має залишатися всередині каталогу пакета Plugin. | +| `openclaw.runtimeExtensions` | Оголошує зібрані JavaScript-точки входу runtime для встановлених пакетів. Має залишатися всередині каталогу пакета Plugin. | +| `openclaw.setupEntry` | Легка точка входу лише для налаштування, що використовується під час онбордингу, відкладеного запуску каналу та read-only виявлення стану каналу/SecretRef. Має залишатися всередині каталогу пакета Plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує зібрану JavaScript-точку входу налаштування для встановлених пакетів. Потребує `setupEntry`, має існувати та має залишатися всередині каталогу пакета Plugin. | +| `openclaw.channel` | Дешеві метадані каталогу каналів, як-от мітки, шляхи документації, псевдоніми та текст вибору. | +| `openclaw.channel.commands` | Статичні нативні метадані команд і нативних skill auto-default, що використовуються конфігурацією, аудитом і поверхнями списку команд до завантаження runtime каналу. | +| `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти "чи вже існує env-only налаштування?" без завантаження повного runtime каналу. | +| `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти "чи вже хтось увійшов?" без завантаження повного runtime каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для bundled і зовнішньо опублікованих plugins. | +| `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | +| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw із semver-нижньою межею на кшталт `>=2026.3.22` або `>=2026.5.1-beta.1`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт відносно нього. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення bundled-plugin, коли конфігурація недійсна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє завантажувати поверхні каналу лише для налаштування перед повним Plugin каналу під час запуску. | Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в -onboarding перед завантаженням runtime. `package.json#openclaw.install` повідомляє -onboarding, як отримати або увімкнути цей Plugin, коли користувач вибирає один із цих -варіантів. Не переміщуйте install hints у `openclaw.plugin.json`. +онбордингу до завантаження runtime. `package.json#openclaw.install` повідомляє +онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із +цих варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`. -`openclaw.install.minHostVersion` застосовується під час install і завантаження -реєстру маніфестів для non-bundled джерел Plugin. Недійсні значення відхиляються; -новіші, але дійсні значення пропускають external Plugins на старіших hosts. Bundled source -Plugins вважаються co-versioned із checkout host. +`openclaw.install.minHostVersion` застосовується під час встановлення та +завантаження реєстру маніфестів для джерел Plugin, що не є bundled. Недійсні +значення відхиляються; новіші, але дійсні значення пропускають зовнішні plugins +на старіших хостах. Bundled source plugins вважаються співверсійними з checkout +хоста. -Точне закріплення npm-версії вже міститься в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні external catalog -entries мають поєднувати точні specs з `expectedIntegrity`, щоб update flows fail -closed, якщо отриманий npm artifact більше не відповідає pinned release. -Interactive onboarding досі пропонує trusted registry npm specs, включно з bare -package names і dist-tags, для сумісності. Catalog diagnostics можуть -розрізняти exact, floating, integrity-pinned, missing-integrity, package-name -mismatch і invalid default-choice sources. Вони також попереджають, коли -`expectedIntegrity` присутній, але немає дійсного npm source, який він може pin. -Коли `expectedIntegrity` присутній, -install/update flows застосовують його; коли його пропущено, registry resolution -записується без integrity pin. +Точне закріплення версії npm уже міститься в `npmSpec`, наприклад +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього +каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки +оновлення завершувалися закрито, якщо отриманий npm-артефакт більше не +відповідає закріпленому релізу. Інтерактивний онбординг досі пропонує довірені +npm-специфікації реєстру, включно з голими назвами пакетів і dist-tags, для +сумісності. Діагностика каталогу може розрізняти точні, плаваючі, +integrity-pinned, missing-integrity, невідповідність назви пакета та недійсні +джерела default-choice. Вона також попереджає, коли `expectedIntegrity` наявний, +але немає дійсного npm-джерела, яке він може закріпити. Коли +`expectedIntegrity` наявний, потоки встановлення/оновлення застосовують його; +коли його пропущено, розв’язання реєстру записується без закріплення цілісності. -Channel Plugins мають надавати `openclaw.setupEntry`, коли status, channel list -або SecretRef scans мають ідентифікувати налаштовані облікові записи без завантаження повного -runtime. Setup entry має надавати метадані каналу разом із setup-safe config, -status і secrets adapters; залишайте network clients, gateway listeners і -transport runtimes у головному extension entrypoint. +Channel plugins мають надавати `openclaw.setupEntry`, коли сканування стану, +списку каналів або SecretRef має визначити налаштовані облікові записи без +завантаження повного runtime. Точка входу налаштування має експортувати метадані +каналу, а також setup-safe адаптери конфігурації, стану та секретів; тримайте +мережеві клієнти, слухачі Gateway і transport runtimes у головній точці входу +розширення. -Поля runtime entrypoint не перевизначають перевірки меж пакета для source -entrypoint fields. Наприклад, `openclaw.runtimeExtensions` не може зробити -escaping path `openclaw.extensions` придатним для завантаження. +Поля точок входу runtime не перевизначають перевірки меж пакета для полів +source entrypoint. Наприклад, `openclaw.runtimeExtensions` не може зробити +завантажуваним шлях `openclaw.extensions`, що виходить назовні. -`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не -робить довільні зламані configs installable. Наразі він лише дозволяє install -flows відновлюватися після конкретних застарілих помилок upgrade bundled-plugin, як-от -відсутній шлях bundled Plugin або застарілий запис `channels.` для того самого -bundled Plugin. Непов’язані помилки config все одно блокують install і спрямовують операторів -до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не робить +довільні зламані конфігурації встановлюваними. Сьогодні він лише дозволяє +потокам встановлення відновлюватися після конкретних застарілих збоїв +оновлення bundled-plugin, як-от відсутній шлях bundled Plugin або застарілий +запис `channels.` для того самого bundled Plugin. Непов’язані помилки +конфігурації все одно блокують встановлення та скеровують операторів до +`openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це metadata пакета для крихітного checker -module: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного +модуля перевірки: ```json { @@ -1047,15 +1199,16 @@ module: } ``` -Використовуйте це, коли setup, doctor, status або read-only presence flows потребують дешевої -yes/no auth probe до завантаження повного Plugin каналу. Persisted auth state — -це не configured channel state: не використовуйте ці метадані для auto-enable Plugins, -repair runtime dependencies або вирішення, чи має завантажуватися channel runtime. -Target export має бути невеликою функцією, що читає лише persisted state; не -спрямовуйте її через повний channel runtime barrel. +Використовуйте це, коли потокам setup, doctor, status або read-only presence +потрібна дешева yes/no перевірка автентифікації до завантаження повного Plugin +каналу. Збережений стан автентифікації не є налаштованим станом каналу: не +використовуйте ці метадані для автоматичного ввімкнення plugins, ремонту +runtime-залежностей або рішення, чи має завантажуватися runtime каналу. Цільовий +експорт має бути невеликою функцією, яка читає лише збережений стан; не +пропускайте її через повний runtime barrel каналу. `openclaw.channel.configuredState` має таку саму форму для дешевих env-only -configured checks: +перевірок налаштованості: ```json { @@ -1071,66 +1224,67 @@ configured checks: } ``` -Використовуйте це, коли канал може відповісти configured-state з env або інших невеликих -non-runtime inputs. Якщо перевірка потребує повного config resolution або справжнього -channel runtime, залишайте цю логіку в hook Plugin `config.hasConfiguredState`. +Використовуйте це, коли канал може відповісти про налаштований стан з env або +інших крихітних non-runtime вхідних даних. Якщо перевірка потребує повного +розв’язання конфігурації або справжнього runtime каналу, залиште цю логіку в +хуку Plugin `config.hasConfiguredState`. ## Пріоритет виявлення (дублікати ідентифікаторів Plugin) -OpenClaw виявляє Plugins з кількох roots (bundled, global install, workspace, явні config-selected paths). Якщо два виявлені елементи мають той самий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. +OpenClaw виявляє plugins з кількох коренів (bundled, глобальне встановлення, workspace, явні шляхи, вибрані конфігурацією). Якщо два виявлені елементи мають той самий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати нижчого пріоритету відкидаються замість завантаження поруч із ним. Пріоритет, від найвищого до найнижчого: -1. **Config-selected** — шлях, явно закріплений у `plugins.entries.` -2. **Bundled** — Plugins, що постачаються з OpenClaw -3. **Global install** — Plugins, встановлені в глобальний корінь Plugin OpenClaw -4. **Workspace** — Plugins, виявлені відносно поточного workspace +1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` +2. **Bundled** — plugins, що постачаються з OpenClaw +3. **Глобальне встановлення** — plugins, установлені в глобальний корінь Plugin OpenClaw +4. **Workspace** — plugins, виявлені відносно поточного workspace Наслідки: -- Forked або застаріла копія bundled Plugin, що лежить у workspace, не shadow bundled build. -- Щоб справді перевизначити bundled Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на workspace discovery. -- Відкидання дублікатів логуються, щоб Doctor і startup diagnostics могли вказати на відкинуту копію. +- Форкована або застаріла копія bundled Plugin, що лежить у workspace, не затінить bundled збірку. +- Щоб справді перевизначити bundled Plugin локальним, закріпіть його через `plugins.entries.`, щоб він виграв за пріоритетом, а не покладайтеся на виявлення workspace. +- Відкидання дублікатів логуються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. ## Вимоги JSON Schema -- **Кожен Plugin має постачати JSON Schema**, навіть якщо він не приймає config. -- Порожня schema прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Schemas валідуються під час читання/запису config, а не під час runtime. +- **Кожен Plugin має постачати JSON Schema**, навіть якщо він не приймає конфігурації. +- Порожня схема прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми перевіряються під час читання/запису конфігурації, а не під час runtime. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено в - маніфесті plugin. +- Невідомі ключі `channels.*` є **помилками**, якщо ідентифікатор каналу не оголошено + маніфестом Plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - мають посилатися на **виявлювані** ідентифікатори plugin. Невідомі ідентифікатори є **помилками**. -- Якщо plugin встановлено, але він має пошкоджений або відсутній маніфест чи схему, - валідація завершується невдало, а Doctor повідомляє про помилку plugin. -- Якщо конфігурація plugin існує, але plugin **вимкнено**, конфігурація зберігається, а - **попередження** відображається в Doctor і журналах. + мають посилатися на **discoverable** ідентифікатори Plugin. Невідомі ідентифікатори є **помилками**. +- Якщо Plugin встановлено, але він має зламаний або відсутній маніфест чи схему, + валідація завершується з помилкою, а Doctor повідомляє про помилку Plugin. +- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається, а + **попередження** показується в Doctor + logs. -Див. [довідник із конфігурації](/uk/gateway/configuration), щоб переглянути повну схему `plugins.*`. +Див. [довідник конфігурації](/uk/gateway/configuration) для повної схеми `plugins.*`. ## Примітки -- Маніфест є **обов’язковим для нативних plugin OpenClaw**, зокрема для завантажень із локальної файлової системи. Runtime все одно завантажує модуль plugin окремо; маніфест потрібен лише для виявлення й валідації. -- Нативні маніфести розбираються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок приймаються, якщо підсумкове значення все одно є об’єктом. -- Завантажувач маніфестів читає лише документовані поля маніфесту. Уникайте власних ключів верхнього рівня. -- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо plugin вони не потрібні. -- `providerDiscoveryEntry` має залишатися легковагим і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час запиту. -- Ексклюзивні види plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (за замовчуванням `legacy`). -- Оголошуйте ексклюзивний вид plugin у цьому маніфесті. Runtime-запис `OpenClawPluginDefinition.kind` застарів і залишається лише як резервний варіант сумісності для старіших plugin. -- Метадані змінних середовища (`setup.providers[].envVars`, застарілі `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставки cron та інші поверхні лише для читання все одно застосовують довіру до plugin і політику ефективної активації, перш ніж вважати змінну середовища налаштованою. -- Для runtime-метаданих майстра, яким потрібен код провайдера, див. [runtime-хуки провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш plugin залежить від нативних модулів, задокументуйте кроки збирання та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Маніфест є **обов’язковим для нативних OpenClaw plugins**, включно з локальними завантаженнями з файлової системи. Runtime все одно завантажує модуль Plugin окремо; маніфест потрібен лише для виявлення + валідації. +- Нативні маніфести розбираються як JSON5, тому коментарі, кінцеві коми та ключі без лапок приймаються, доки фінальне значення все ще є об’єктом. +- Завантажувач маніфестів читає лише задокументовані поля маніфесту. Уникайте кастомних ключів верхнього рівня. +- `channels`, `providers`, `cliBackends` і `skills` можна всі пропустити, коли Plugin не потребує їх. +- `providerDiscoveryEntry` має залишатися легким і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу provider або вузьких дескрипторів виявлення, а не для виконання під час запиту. +- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (default `legacy`). +- Оголошуйте ексклюзивний тип Plugin у цьому маніфесті. Runtime-entry `OpenClawPluginDefinition.kind` застарілий і залишається лише як fallback сумісності для старіших plugins. +- Метадані env-var (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Status, audit, cron delivery validation та інші read-only поверхні все одно застосовують довіру до Plugin і effective activation policy перед тим, як вважати env var налаштованою. +- Для runtime wizard metadata, що потребує коду provider, див. [runtime-хуки provider](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш Plugin залежить від нативних модулів, задокументуйте кроки збірки та будь-які вимоги allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане - - Початок роботи з plugin. + + Початок роботи з plugins. - + Внутрішня архітектура та модель можливостей.