--- read_when: - Ви створюєте плагін OpenClaw - Вам потрібно випустити схему конфігурації Plugin або налагодити помилки перевірки Plugin summary: Маніфест Plugin + вимоги до JSON-схеми (сувора валідація конфігурації) title: Маніфест Plugin x-i18n: generated_at: "2026-06-27T17:53:58Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 62f6684ab074e4f14ce5c833fe8c8c624a2750f80215bdeffd972e27dd6bfc9c source_path: plugins/manifest.md workflow: 16 --- Ця сторінка призначена лише для **нативного маніфесту Plugin OpenClaw**. Сумісні схеми пакетів див. у розділі [Пакети Plugin](/uk/plugins/bundles). Сумісні формати пакетів використовують інші файли маніфестів: - Пакет Codex: `.codex-plugin/plugin.json` - Пакет Claude: `.claude-plugin/plugin.json` або типова схема компонентів Claude без маніфесту - Пакет Cursor: `.cursor-plugin/plugin.json` OpenClaw також автоматично виявляє ці схеми пакетів, але їх не перевіряють за схемою `openclaw.plugin.json`, описаною тут. Для сумісних пакетів OpenClaw наразі читає метадані пакета, а також оголошені корені навичок, корені команд Claude, типові значення `settings.json` пакета Claude, типові значення LSP пакета Claude і підтримувані пакети хуків, коли схема відповідає очікуванням середовища виконання OpenClaw. Кожен нативний Plugin OpenClaw **має** постачати файл `openclaw.plugin.json` у **корені Plugin**. OpenClaw використовує цей маніфест для перевірки конфігурації **без виконання коду Plugin**. Відсутні або недійсні маніфести вважаються помилками Plugin і блокують перевірку конфігурації. Див. повний посібник із системи Plugin: [Plugin](/uk/tools/plugin). Про нативну модель можливостей і поточні настанови щодо зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл `openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження коду вашого Plugin**. Усе нижче має бути достатньо дешевим для перевірки без запуску середовища виконання Plugin. **Використовуйте його для:** - ідентифікації Plugin, перевірки конфігурації та підказок інтерфейсу конфігурації - метаданих автентифікації, адаптації та налаштування (псевдонім, автоматичне ввімкнення, змінні середовища провайдера, варіанти автентифікації) - підказок активації для поверхонь площини керування - скороченого володіння сімейством моделей - статичних знімків володіння можливостями (`contracts`) - метаданих засобу виконання QA, які може перевіряти спільний хост `openclaw qa` - метаданих конфігурації для окремих каналів, об’єднаних у каталог і поверхні перевірки **Не використовуйте його для:** реєстрації поведінки під час виконання, оголошення точок входу коду або метаданих встановлення npm. Вони належать до коду вашого Plugin і `package.json`. ## Мінімальний приклад ```json { "id": "voice-call", "configSchema": { "type": "object", "additionalProperties": false, "properties": {} } } ``` ## Розширений приклад ```json { "id": "openrouter", "name": "OpenRouter", "description": "OpenRouter provider plugin", "version": "1.0.0", "providers": ["openrouter"], "modelSupport": { "modelPrefixes": ["router-"] }, "modelIdNormalization": { "providers": { "openrouter": { "prefixWhenBare": "openrouter" } } }, "providerEndpoints": [ { "endpointClass": "openrouter", "hostSuffixes": ["openrouter.ai"] } ], "providerRequest": { "providers": { "openrouter": { "family": "openrouter" } } }, "cliBackends": ["openrouter-cli"], "syntheticAuthRefs": ["openrouter-cli"], "setup": { "providers": [ { "id": "openrouter", "envVars": ["OPENROUTER_API_KEY"] } ] }, "providerAuthAliases": { "openrouter-coding": "openrouter" }, "channelEnvVars": { "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"] }, "providerAuthChoices": [ { "provider": "openrouter", "method": "api-key", "choiceId": "openrouter-api-key", "choiceLabel": "OpenRouter API key", "groupId": "openrouter", "groupLabel": "OpenRouter", "optionKey": "openrouterApiKey", "cliFlag": "--openrouter-api-key", "cliOption": "--openrouter-api-key ", "cliDescription": "OpenRouter API key", "onboardingScopes": ["text-inference"] } ], "uiHints": { "apiKey": { "label": "API key", "placeholder": "sk-or-v1-...", "sensitive": true } }, "configSchema": { "type": "object", "additionalProperties": false, "properties": { "apiKey": { "type": "string" } } } } ``` ## Довідник полів верхнього рівня | Поле | Обов’язково | Тип | Що означає | | ------------------------------------ | ----------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Так | `string` | Канонічний id Plugin. Це id, що використовується в `plugins.entries.`. | | `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | | `requiresPlugins` | Ні | `string[]` | Id Plugin, які також мають бути встановлені, щоб цей Plugin мав ефект. Виявлення залишає Plugin доступним для завантаження, але попереджає, якщо бракує будь-якого обов’язкового Plugin. | | `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Опустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб залишити Plugin вимкненим за замовчуванням. | | `enabledByDefaultOnPlatforms` | Ні | `string[]` | Позначає вбудований Plugin як увімкнений за замовчуванням лише на перелічених платформах Node.js, наприклад `["darwin"]`. Явна конфігурація все одно має пріоритет. | | `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id Plugin. | | `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Id провайдерів, які мають автоматично вмикати цей Plugin, коли auth, config або посилання на моделі згадують їх. | | `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, що використовується `plugins.slots.*`. | | `channels` | Ні | `string[]` | Id каналів, якими володіє цей Plugin. Використовується для виявлення та перевірки конфігурації. | | `providers` | Ні | `string[]` | Id провайдерів, якими володіє цей Plugin. | | `providerCatalogEntry` | Ні | `string` | Полегшений шлях до модуля каталогу провайдерів, відносний до кореня Plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного runtime Plugin. | | `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, якими володіє маніфест, що використовуються для автоматичного завантаження Plugin перед runtime. | | `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт control plane для майбутнього read-only переліку, onboarding, вибору моделей, псевдонімів і придушення без завантаження runtime Plugin. | | `modelPricing` | Ні | `object` | Політика зовнішнього пошуку цін, якою володіє провайдер. Використовуйте її, щоб виключити локальних/self-hosted провайдерів із віддалених каталогів цін або зіставити посилання провайдерів з id каталогів OpenRouter/LiteLLM без hardcoding id провайдерів у core. | | `modelIdNormalization` | Ні | `object` | Очищення псевдонімів/префіксів id моделей, яким володіє провайдер і яке має виконуватися до завантаження runtime провайдера. | | `providerEndpoints` | Ні | `object[]` | Метадані endpoint host/baseUrl, якими володіє маніфест, для маршрутів провайдерів, які core має класифікувати до завантаження runtime провайдера. | | `providerRequest` | Ні | `object` | Дешеві метадані сімейства провайдера та сумісності запитів, що використовуються загальною політикою запитів до завантаження runtime провайдера. | | `secretProviderIntegrations` | Ні | `Record` | Декларативні presets для SecretRef exec provider, які setup або поверхні встановлення можуть пропонувати без hardcoding інтеграцій, специфічних для провайдера, у core. | | `cliBackends` | Ні | `string[]` | Id backend для CLI inference, якими володіє цей Plugin. Використовується для автоматичної активації під час запуску з явних посилань конфігурації. | | `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдера або CLI backend, для яких synthetic auth hook, що належить Plugin, має перевірятися під час холодного виявлення моделей до завантаження runtime. | | `nonSecretAuthMarkers` | Ні | `string[]` | Placeholder-значення API key, якими володіє вбудований Plugin і які представляють несекретний локальний, OAuth або ambient стан облікових даних. | | `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які мають створювати конфігурацію з урахуванням Plugin та діагностику CLI до завантаження runtime. | | `providerAuthEnvVars` | Ні | `Record` | Застарілі метадані env сумісності для пошуку auth/status провайдера. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це під час періоду deprecation. | | `providerAuthAliases` | Ні | `Record` | Id провайдерів, які мають повторно використовувати інший id провайдера для пошуку auth, наприклад coding provider, що спільно використовує API key базового провайдера та профілі auth. | | `channelEnvVars` | Ні | `Record` | Дешеві метадані env каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналу через env або auth surfaces, які мають бачити загальні startup/config helpers. | | `providerAuthChoices` | Ні | `object[]` | Дешеві метадані auth-choice для onboarding pickers, preferred-provider resolution і простого підключення CLI flags. | | `activation` | Ні | `object` | Дешеві метадані планувальника активації для запуску, провайдера, команди, каналу, маршруту та завантаження, спричиненого capability. Лише метадані; runtime Plugin усе ще володіє фактичною поведінкою. | | `setup` | Ні | `object` | Дешеві descriptors для setup/onboarding, які discovery та setup surfaces можуть перевіряти без завантаження runtime Plugin. | | `qaRunners` | Ні | `object[]` | Дешеві descriptors QA runner, що використовуються спільним хостом `openclaw qa` до завантаження runtime Plugin. | | `contracts` | Ні | `object` | Статичний snapshot володіння capability для external auth hooks, embeddings, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння tools. | | `mediaUnderstandingProviderMetadata` | Ні | `Record` | Дешеві defaults для media-understanding для id провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | | `imageGenerationProviderMetadata` | Ні | `Record` | Дешеві auth metadata для image-generation для id провайдерів, оголошених у `contracts.imageGenerationProviders`, включно з auth aliases і base-url guards, якими володіє провайдер. | | `videoGenerationProviderMetadata` | Ні | `Record` | Дешеві auth metadata для video-generation для id провайдерів, оголошених у `contracts.videoGenerationProviders`, включно з auth aliases і base-url guards, якими володіє провайдер. | | `musicGenerationProviderMetadata` | Ні | `Record` | Дешеві auth metadata для music-generation для id провайдерів, оголошених у `contracts.musicGenerationProviders`, включно з auth aliases і base-url guards, якими володіє провайдер. | | `toolMetadata` | Ні | `Record` | Легкі метадані доступності для інструментів, що належать плагіну й оголошені в `contracts.tools`. Використовуйте їх, коли інструмент не має завантажувати середовище виконання, якщо немає доказів конфігурації, env або auth. | | `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, що належать маніфесту й об’єднуються з поверхнями виявлення та валідації до завантаження середовища виконання. | | `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня плагіна. | | `name` | Ні | `string` | Зручна для людини назва плагіна. | | `description` | Ні | `string` | Короткий підсумок, що відображається на поверхнях плагіна. | | `icon` | Ні | `string` | URL зображення HTTPS для карток marketplace/каталогу. ClawHub приймає будь-який дійсний URL `https://` і повертається до стандартної іконки плагіна, коли його пропущено або він недійсний. | | `version` | Ні | `string` | Інформаційна версія плагіна. | | `uiHints` | Ні | `Record` | UI-мітки, заповнювачі та підказки щодо чутливості для полів конфігурації. | ## Довідник метаданих постачальників генерації Поля метаданих постачальника генерації описують статичні сигнали автентифікації для постачальників, оголошених у відповідному списку `contracts.*GenerationProviders`. OpenClaw читає ці поля до завантаження середовища виконання постачальника, щоб основні інструменти могли визначити, чи доступний постачальник генерації, без імпорту кожного плагіна постачальника. Використовуйте ці поля лише для дешевих декларативних фактів. Транспорт, перетворення запитів, оновлення токенів, перевірка облікових даних і фактична поведінка генерації залишаються в середовищі виконання плагіна. ```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[]` | Дешеві сигнали доступності лише з конфігурації для локальних або самостійно розгорнутих постачальників, які можна налаштувати без профілів автентифікації або змінних середовища. | | `authSignals` | Ні | `object[]` | Явні сигнали автентифікації. Якщо вони присутні, вони замінюють типовий набір сигналів з ідентифікатора постачальника, `aliases` і `authProviders`. | | `referenceAudioInputs` | Ні | `boolean` | Лише для генерації відео. Установіть `true`, коли постачальник приймає еталонні аудіоресурси; інакше `video_generate` приховує параметри еталонного аудіо. | Кожен запис `configSignals` підтримує: | Поле | Обов’язкове | Тип | Що означає | | ---------------- | -------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rootPath` | Так | `string` | Dot path до об’єкта конфігурації, що належить плагіну, який потрібно перевірити, наприклад `plugins.entries.example.config`. | | `overlayPath` | Ні | `string` | Dot path усередині кореневої конфігурації, об’єкт якого має накластися на кореневий об’єкт перед оцінюванням сигналу. Використовуйте це для конфігурації, специфічної для можливості, як-от `image`, `video` або `music`. | | `overlayMapPath` | Ні | `string` | Dot path усередині кореневої конфігурації, значення об’єкта якого мають кожне накластися на кореневий об’єкт. Використовуйте це для іменованих мап облікових записів, як-от `accounts`, де будь-який налаштований обліковий запис має підходити. | | `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 міг уникнути імпорту середовища виконання плагіна лише для того, щоб фабрика інструментів повернула `null`. ```json { "setup": { "providers": [ { "id": "example", "envVars": ["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 зберігає наявну поведінку та завантажує плагін-власник, коли контракт інструмента відповідає політиці. Для інструментів гарячого шляху, фабрика яких залежить від автентифікації/конфігурації, автори плагінів мають оголошувати `toolMetadata` замість того, щоб змушувати core імпортувати середовище виконання для запиту. ## Довідник providerAuthChoices Кожен запис `providerAuthChoices` описує один вибір для онбордингу або автентифікації. OpenClaw читає це до завантаження середовища виконання постачальника. Списки налаштування постачальників використовують ці вибори маніфесту, варіанти налаштування, отримані з дескриптора, і метадані каталогу встановлення без завантаження середовища виконання постачальника. | Поле | Обов’язково | Тип | Що це означає | | --------------------- | -------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `provider` | Так | `string` | Ідентифікатор провайдера, якому належить цей вибір. | | `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого потрібно виконати dispatch. | | `choiceId` | Так | `string` | Стабільний ідентифікатор вибору автентифікації, який використовують потоки onboarding і CLI. | | `choiceLabel` | Ні | `string` | Видима користувачу мітка. Якщо не вказано, OpenClaw використовує `choiceId` як fallback. | | `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" \| "music-generation">` | У яких поверхнях onboarding має з’являтися цей вибір. Якщо не вказано, типове значення — `["text-inference"]`. | ## Довідник commandAliases Використовуйте `commandAliases`, коли Plugin володіє назвою runtime-команди, яку користувачі можуть помилково додати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпортування runtime-коду Plugin. ```json { "commandAliases": [ { "name": "dreaming", "kind": "runtime-slash", "cliCommand": "memory" } ] } ``` | Поле | Обов’язково | Тип | Що це означає | | ------------ | -------- | ----------------- | ----------------------------------------------------------------------- | | `name` | Так | `string` | Назва команди, що належить цьому Plugin. | | `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не як кореневу команду CLI. | | `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку варто запропонувати для CLI-операцій, якщо вона існує. | ## Довідник activation Використовуйте `activation`, коли Plugin може дешево оголосити, які події control-plane мають включати його в план активації/завантаження. Цей блок є метаданими планувальника, а не lifecycle API. Він не реєструє runtime-поведінку, не замінює `register(...)` і не обіцяє, що код Plugin уже виконано. Планувальник активації використовує ці поля, щоб звузити кандидатні Plugins перед fallback до наявних метаданих володіння в маніфесті, як-от `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hooks. Віддавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальнику, які неможливо представити цими полями володіння. Використовуйте top-level `cliBackends` для псевдонімів runtime CLI, як-от `claude-cli`, `my-cli` або `google-gemini-cli`; `activation.onAgentHarnesses` призначено лише для вбудованих ідентифікаторів agent harness, які ще не мають поля володіння. Цей блок містить лише метадані. Він не реєструє runtime-поведінку та не замінює `register(...)`, `setupEntry` або інші runtime/Plugin entrypoints. Поточні споживачі використовують його як звужувальну підказку перед ширшим завантаженням Plugin, тому відсутні метадані активації не для startup зазвичай впливають лише на продуктивність; це не має змінювати коректність, доки існують fallback механізми володіння з маніфесту. Кожен Plugin має встановлювати `activation.onStartup` навмисно. Встановіть його в `true` лише тоді, коли Plugin має запускатися під час startup Gateway. Встановіть його в `false`, коли Plugin інертний під час startup і має завантажуватися лише за вужчими тригерами. Пропуск `onStartup` більше не виконує startup-завантаження Plugin неявно; використовуйте явні метадані активації для startup, channel, config, agent-harness, memory або інших вужчих тригерів активації. ```json { "activation": { "onStartup": false, "onProviders": ["openai"], "onCommands": ["models"], "onChannels": ["web"], "onRoutes": ["gateway-webhook"], "onConfigPaths": ["browser"], "onCapabilities": ["provider", "tool"] } } ``` | Поле | Обов’язково | Тип | Що це означає | | ------------------ | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `onStartup` | Ні | `boolean` | Явна startup-активація Gateway. Кожен Plugin має встановлювати це поле. `true` імпортує Plugin під час startup; `false` зберігає його лінивим під час startup, якщо інший відповідний тригер не потребує завантаження. | | `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin у плани активації/завантаження. | | `onAgentHarnesses` | Ні | `string[]` | Ідентифікатори runtime вбудованих agent harness, які мають включати цей Plugin у плани активації/завантаження. Використовуйте top-level `cliBackends` для псевдонімів backend CLI. | | `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin у плани активації/завантаження. | | `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin у плани активації/завантаження. | | `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin у плани активації/завантаження. | | `onConfigPaths` | Ні | `string[]` | Шляхи конфігурації відносно кореня, які мають включати цей Plugin у плани startup/завантаження, коли шлях присутній і не вимкнений явно. | | `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки про можливості, які використовуються плануванням активації control-plane. За можливості віддавайте перевагу вужчим полям. | Поточні live-споживачі: - Планування startup Gateway використовує `activation.onStartup` для явного startup імпорту - Планування CLI, ініційоване командою, виконує fallback до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` - Планування startup agent-runtime використовує `activation.onAgentHarnesses` для вбудованих harness і top-level `cliBackends[]` для псевдонімів runtime CLI - Планування setup/channel, ініційоване каналом, виконує fallback до застарілого володіння `channels[]`, коли явні метадані активації каналу відсутні - Планування Plugin під час startup використовує `activation.onConfigPaths` для неканальних кореневих поверхонь config, як-от блок `browser` у bundled browser Plugin - Планування setup/runtime, ініційоване провайдером, виконує fallback до застарілого володіння `providers[]` і top-level `cliBackends[]`, коли явні метадані активації провайдера відсутні Діагностика планувальника може відрізняти явні підказки активації від fallback володіння з маніфесту. Наприклад, `activation-command-hint` означає, що `activation.onCommands` збігся, тоді як `manifest-command-alias` означає, що планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для діагностики host і тестів; автори Plugin мають продовжувати оголошувати метадані, які найкраще описують володіння. ## Довідник qaRunners Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runners під спільним коренем `openclaw qa`. Зберігайте ці метадані дешевими й статичними; runtime Plugin усе ще володіє фактичною реєстрацією CLI через легку поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { "qaRunners": [ { "commandName": "matrix", "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver" } ] } ``` | Поле | Обов’язкове | Тип | Що це означає | | ------------- | ----------- | -------- | --------------------------------------------------------------------- | | `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | | `description` | Ні | `string` | Резервний довідковий текст, коли спільному хосту потрібна заглушка команди. | ## Довідник `setup` Використовуйте `setup`, коли поверхням налаштування та первинного налаштування потрібні дешеві метадані, що належать Plugin, до завантаження середовища виконання. ```json { "setup": { "providers": [ { "id": "openai", "authMethods": ["api-key"], "envVars": ["OPENAI_API_KEY"], "authEvidence": [ { "type": "local-file-with-env", "fileEnvVar": "OPENAI_CREDENTIALS_FILE", "requiresAllEnv": ["OPENAI_PROJECT"], "credentialMarker": "openai-local-credentials", "source": "openai local credentials" } ] } ], "cliBackends": ["openai-cli"], "configMigrations": ["legacy-openai-auth"], "requiresRuntime": false } } ``` Верхньорівневий `cliBackends` залишається чинним і далі описує бекенди виведення CLI. `setup.cliBackends` є специфічною для налаштування поверхнею дескрипторів для потоків керування/налаштування, які мають залишатися лише метаданими. За наявності `setup.providers` і `setup.cliBackends` є пріоритетною поверхнею пошуку спочатку за дескрипторами для виявлення налаштування. Якщо дескриптор лише звужує кандидатний Plugin, а налаштуванню все ще потрібні багатші runtime-хуки під час налаштування, встановіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. OpenClaw також включає `setup.providers[].envVars` у загальні перевірки автентифікації провайдера та змінних середовища. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом періоду вилучення, але не вбудовані plugins, які все ще його використовують, отримують діагностику маніфесту. Нові plugins мають розміщувати метадані середовища для налаштування/статусу в `setup.providers[].envVars`. OpenClaw також може виводити прості варіанти налаштування з `setup.providers[].authMethods`, коли запис налаштування відсутній або коли `setup.requiresRuntime: false` оголошує runtime для налаштування непотрібним. Явні записи `providerAuthChoices` залишаються пріоритетними для власних міток, прапорців CLI, області первинного налаштування та метаданих асистента. Встановлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні налаштування. OpenClaw трактує явне `false` як контракт лише на дескрипторах і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку налаштування. Якщо Plugin лише з дескрипторами все ще постачає один із цих runtime-записів налаштування, OpenClaw повідомляє додаткову діагностику й далі ігнорує його. Пропущений `requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні plugins, які додали дескриптори без цього прапорця, не ламалися. Оскільки пошук налаштування може виконувати код `setup-api`, що належить Plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед виявлених plugins. Неоднозначне володіння завершується закритою відмовою замість вибору переможця за порядком виявлення. Коли runtime налаштування виконується, діагностика реєстру налаштування повідомляє про дрейф дескрипторів, якщо `setup-api` реєструє провайдера або бекенд CLI, який дескриптори маніфесту не оголошують, або якщо дескриптор не має відповідної runtime-реєстрації. Ці діагностики є додатковими й не відхиляють застарілі plugins. ### Довідник `setup.providers` | Поле | Обов’язкове | Тип | Що це означає | | -------------- | ----------- | ---------- | ------------------------------------------------------------------------------------------------------ | | `id` | Так | `string` | Ідентифікатор провайдера, відкритий під час налаштування або первинного налаштування. Тримайте нормалізовані ідентифікатори глобально унікальними. | | `authMethods` | Ні | `string[]` | Ідентифікатори методів налаштування/автентифікації, які цей провайдер підтримує без завантаження повного runtime. | | `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні налаштування/статусу можуть перевіряти до завантаження runtime Plugin. | | `authEvidence` | Ні | `object[]` | Дешеві локальні перевірки доказів автентифікації для провайдерів, які можуть автентифікуватися через несекретні маркери. | `authEvidence` призначено для локальних маркерів облікових даних, що належать провайдеру й можуть бути перевірені без завантаження runtime-коду. Ці перевірки мають залишатися дешевими й локальними: без мережевих викликів, без читання keychain або менеджера секретів, без shell-команд і без проб API провайдера. Підтримувані записи доказів: | Поле | Обов’язкове | Тип | Що це означає | | ------------------ | ----------- | ---------- | -------------------------------------------------------------------------------------------------------------- | | `type` | Так | `string` | Наразі `local-file-with-env`. | | `fileEnvVar` | Ні | `string` | Змінна середовища, що містить явний шлях до файла облікових даних. | | `fallbackPaths` | Ні | `string[]` | Локальні шляхи до файлів облікових даних, які перевіряються, коли `fileEnvVar` відсутня або порожня. Підтримує `${HOME}` і `${APPDATA}`. | | `requiresAnyEnv` | Ні | `string[]` | Принаймні одна перелічена змінна середовища має бути непорожньою, перш ніж доказ стане чинним. | | `requiresAllEnv` | Ні | `string[]` | Кожна перелічена змінна середовища має бути непорожньою, перш ніж доказ стане чинним. | | `credentialMarker` | Так | `string` | Несекретний маркер, що повертається, коли доказ присутній. | | `source` | Ні | `string` | Звернена до користувача мітка джерела для виводу автентифікації/статусу. | ### Поля `setup` | Поле | Обов’язкове | Тип | Що це означає | | ------------------ | ----------- | ---------- | ----------------------------------------------------------------------------------------------------- | | `providers` | Ні | `object[]` | Дескриптори налаштування провайдера, відкриті під час налаштування та первинного налаштування. | | `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів під час налаштування, які використовуються для пошуку налаштування спочатку за дескрипторами. Тримайте нормалізовані ідентифікатори глобально унікальними. | | `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, що належать поверхні налаштування цього Plugin. | | `requiresRuntime` | Ні | `boolean` | Чи налаштуванню все ще потрібне виконання `setup-api` після пошуку за дескрипторами. | ## Довідник `uiHints` `uiHints` — це мапа від назв полів конфігурації до невеликих підказок рендерингу. ```json { "uiHints": { "apiKey": { "label": "API key", "help": "Used for OpenRouter requests", "placeholder": "sk-or-v1-...", "sensitive": true } } } ``` Кожна підказка поля може містити: | Поле | Тип | Що це означає | | ------------- | ---------- | -------------------------------------------- | | `label` | `string` | Звернена до користувача мітка поля. | | `help` | `string` | Короткий допоміжний текст. | | `tags` | `string[]` | Необов’язкові теги UI. | | `advanced` | `boolean` | Позначає поле як розширене. | | `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | | `placeholder` | `string` | Текст заповнювача для полів форми. | ## Довідник `contracts` Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може читати без імпорту runtime Plugin. ```json { "contracts": { "agentToolResultMiddleware": ["openclaw", "codex"], "trustedToolPolicies": ["workflow-budget"], "externalAuthProviders": ["acme-ai"], "embeddingProviders": ["openai-compatible"], "speechProviders": ["openai"], "realtimeTranscriptionProviders": ["openai"], "realtimeVoiceProviders": ["openai"], "memoryEmbeddingProviders": ["local"], "mediaUnderstandingProviders": ["openai"], "imageGenerationProviders": ["openai"], "videoGenerationProviders": ["qwen"], "webFetchProviders": ["firecrawl"], "webSearchProviders": ["gemini"], "migrationProviders": ["hermes"], "gatewayMethodDispatch": ["authenticated-request"], "tools": ["firecrawl_search", "firecrawl_scrape"] } } ``` Кожен список є необов’язковим: | Поле | Тип | Що це означає | | -------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик розширень app-server Codex, наразі `codex-app-server`. | | `agentToolResultMiddleware` | `string[]` | Ідентифікатори середовищ виконання, для яких цей plugin може реєструвати middleware результатів інструментів. | | `trustedToolPolicies` | `string[]` | Локальні для plugin ідентифікатори довірених політик перед інструментами, які встановлений plugin може реєструвати. Вбудовані plugins можуть реєструвати політики без цього поля. | | `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, чиїм hook профілю зовнішньої автентифікації володіє цей plugin. | | `embeddingProviders` | `string[]` | Ідентифікатори загальних провайдерів embedding, якими володіє цей plugin для повторно використовуваних vector embedding, зокрема пам’яті. | | `speechProviders` | `string[]` | Ідентифікатори провайдерів мовлення, якими володіє цей plugin. | | `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime-transcription, якими володіє цей plugin. | | `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів realtime-voice, якими володіє цей plugin. | | `memoryEmbeddingProviders` | `string[]` | Застарілі ідентифікатори провайдерів embedding, специфічних для пам’яті, якими володіє цей plugin. | | `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, якими володіє цей plugin. | | `transcriptSourceProviders` | `string[]` | Ідентифікатори провайдерів джерел transcript, якими володіє цей 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`. | | `gatewayMethodDispatch` | `string[]` | Зарезервоване право для автентифікованих HTTP-маршрутів plugin, які диспетчеризують методи Gateway всередині процесу. | | `tools` | `string[]` | Назви інструментів агента, якими володіє цей plugin. | `contracts.embeddedExtensionFactories` збережено для вбудованих фабрик розширень Codex, призначених лише для app-server. Вбудовані трансформації результатів інструментів натомість мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися через `api.registerAgentToolResultMiddleware(...)`. Встановлені plugins можуть використовувати ту саму точку інтеграції middleware лише коли це явно ввімкнено і лише для середовищ виконання, які вони оголошують у `contracts.agentToolResultMiddleware`. Встановлені plugins, яким потрібен довірений хостом рівень політик перед інструментами, мають оголошувати кожен зареєстрований локальний ідентифікатор у `contracts.trustedToolPolicies` і бути явно ввімкненими. Вбудовані plugins зберігають наявний шлях довірених політик, але встановлені plugins із неоголошеними ідентифікаторами політик відхиляються до реєстрації. Ідентифікатори політик обмежені plugin, що їх реєструє, тому два plugins можуть обидва оголосити й зареєструвати `workflow-budget`; один plugin не може зареєструвати той самий локальний ідентифікатор двічі. Реєстрації `api.registerTool(...)` у середовищі виконання мають відповідати `contracts.tools`. Виявлення інструментів використовує цей список, щоб завантажувати лише ті середовища виконання plugin, які можуть володіти запитаними інструментами. Provider plugins, що реалізують `resolveExternalAuthProfiles`, мають оголошувати `contracts.externalAuthProviders`; неоголошені hooks зовнішньої автентифікації ігноруються. Загальні провайдери embedding мають оголошувати `contracts.embeddingProviders` для кожного адаптера, зареєстрованого через `api.registerEmbeddingProvider(...)`. Використовуйте загальний контракт для повторно використовуваної генерації векторів, зокрема для провайдерів, які споживає пошук у пам’яті. `contracts.memoryEmbeddingProviders` є застарілою специфічною для пам’яті сумісністю і залишається лише доки наявні провайдери мігрують на загальну точку інтеграції провайдерів embedding. `contracts.gatewayMethodDispatch` наразі приймає `"authenticated-request"`. Це запобіжник чистоти API для нативних HTTP-маршрутів plugin, які навмисно диспетчеризують методи площини керування Gateway всередині процесу, а не sandbox проти зловмисних нативних plugins. Використовуйте його лише для ретельно перевірених вбудованих/операторських поверхонь, які вже вимагають HTTP-автентифікації Gateway. ## Довідник mediaUnderstandingProviderMetadata Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має стандартні моделі, пріоритет fallback автоматичної автентифікації або нативну підтримку документів, потрібну загальним core helpers до завантаження середовища виконання. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json { "contracts": { "mediaUnderstandingProviders": ["example"] }, "mediaUnderstandingProviderMetadata": { "example": { "capabilities": ["image", "audio"], "defaultModels": { "image": "example-vision-latest", "audio": "example-transcribe-latest" }, "autoPriority": { "image": 40 }, "nativeDocumentInputs": ["pdf"] } } } ``` Кожен запис провайдера може містити: | Поле | Тип | Що це означає | | ---------------------- | ----------------------------------- | ----------------------------------------------------------------------------- | | `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які надає цей провайдер. | | `defaultModels` | `Record` | Стандартні зіставлення capability-to-model, що використовуються, коли config не задає модель. | | `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback провайдера на основі облікових даних. | | `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні документи, які підтримує провайдер. | ## Довідник channelConfigs Використовуйте `channelConfigs`, коли channel plugin потребує дешевих метаданих config до завантаження середовища виконання. Read-only виявлення setup/status каналу може використовувати ці метадані безпосередньо для налаштованих зовнішніх каналів, коли запис setup недоступний, або коли `setup.requiresRuntime: false` оголошує, що середовище виконання setup не потрібне. `channelConfigs` — це метадані маніфесту plugin, а не новий top-level розділ користувацького config. Користувачі й надалі налаштовують екземпляри каналів у `channels.`. OpenClaw читає метадані маніфесту, щоб вирішити, який plugin володіє цим налаштованим каналом, до виконання коду середовища виконання plugin. Для channel plugin `configSchema` і `channelConfigs` описують різні шляхи: - `configSchema` перевіряє `plugins.entries..config` - `channelConfigs..schema` перевіряє `channels.` Non-bundled plugins, які оголошують `channels[]`, також мають оголошувати відповідні записи `channelConfigs`. Без них OpenClaw усе ще може завантажити plugin, але cold-path схема config, setup і поверхні Control UI не можуть знати форму параметрів, якими володіє канал, доки не виконається середовище виконання plugin. `channelConfigs..commands.nativeCommandsAutoEnabled` і `nativeSkillsAutoEnabled` можуть оголошувати статичні стандартні значення `auto` для перевірок config команд, які виконуються до завантаження середовища виконання каналу. Вбудовані канали також можуть публікувати ті самі стандартні значення через `package.json#openclaw.channel.commands` разом з іншими метаданими каталогу каналів, якими володіє їхній package. ```json { "channelConfigs": { "matrix": { "schema": { "type": "object", "additionalProperties": false, "properties": { "homeserverUrl": { "type": "string" } } }, "uiHints": { "homeserverUrl": { "label": "Homeserver URL", "placeholder": "https://matrix.example.com" } }, "label": "Matrix", "description": "Matrix homeserver connection", "commands": { "nativeCommandsAutoEnabled": true, "nativeSkillsAutoEnabled": true }, "preferOver": ["matrix-legacy"] } } } ``` Кожен запис каналу може містити: | Поле | Тип | Що це означає | | ------------ | ------------------------ | ----------------------------------------------------------------------------- | | `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису config каналу. | | `uiHints` | `Record` | Необов’язкові UI labels/placeholders/sensitive hints для цього розділу config каналу. | | `label` | `string` | Позначка каналу, що об’єднується з picker і поверхнями inspect, коли метадані середовища виконання ще не готові. | | `description` | `string` | Короткий опис каналу для поверхонь inspect і catalog. | | `commands` | `object` | Статичні auto-defaults для нативних команд і native skill для перевірок config до запуску середовища виконання. | | `preferOver` | `string[]` | Ідентифікатори legacy або нижчопріоритетних plugins, які цей канал має випереджати в поверхнях вибору. | ### Заміна іншого channel plugin Використовуйте `preferOver`, коли ваш plugin є бажаним власником для ідентифікатора каналу, який також може надавати інший plugin. Типові випадки — перейменований ідентифікатор plugin, standalone plugin, що замінює вбудований plugin, або підтримуваний fork, який зберігає той самий ідентифікатор каналу для сумісності config. ```json { "id": "acme-chat", "channels": ["chat"], "channelConfigs": { "chat": { "schema": { "type": "object", "additionalProperties": false, "properties": { "webhookUrl": { "type": "string" } } }, "preferOver": ["chat"] } } } ``` Коли `channels.chat` налаштовано, OpenClaw розглядає і ідентифікатор каналу, і ідентифікатор бажаного plugin. Якщо нижчопріоритетний plugin було вибрано лише тому, що він вбудований або ввімкнений за замовчуванням, OpenClaw вимикає його в ефективному config середовища виконання, щоб один plugin володів каналом і його інструментами. Явний вибір користувача все ще має перевагу: якщо користувач явно вмикає обидва plugins, OpenClaw зберігає цей вибір і повідомляє діагностику дубльованих каналів/інструментів замість того, щоб мовчки змінювати запитаний набір plugins. Обмежуйте `preferOver` ідентифікаторами plugins, які справді можуть надавати той самий канал. Це не загальне поле пріоритету, і воно не перейменовує ключі користувацького config. ## Довідник modelSupport Використовуйте `modelSupport`, коли OpenClaw має визначати ваш Plugin провайдера з коротких ідентифікаторів моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження середовища виконання Plugin. ```json { "modelSupport": { "modelPrefixes": ["gpt-", "o1", "o3", "o4"], "modelPatterns": ["^computer-use-preview"] } } ``` OpenClaw застосовує такий пріоритет: - явні посилання `provider/model` використовують метадані маніфесту `providers` власника - `modelPatterns` мають перевагу над `modelPrefixes` - якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований Plugin - решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера Поля: | Поле | Тип | Що це означає | | --------------- | ---------- | ----------------------------------------------------------------------------- | | `modelPrefixes` | `string[]` | Префікси, які зіставляються через `startsWith` із короткими ідентифікаторами моделей. | | `modelPatterns` | `string[]` | Джерела regex, які зіставляються з короткими ідентифікаторами моделей після видалення суфікса профілю. | Записи `modelPatterns` компілюються через `compileSafeRegex`, який відхиляє шаблони з вкладеним повторенням (наприклад, `(a+)+$`). Шаблони, що не проходять перевірку безпеки, тихо пропускаються, так само як синтаксично недійсний regex. Тримайте шаблони простими й уникайте вкладених квантифікаторів. ## Довідка modelCatalog Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до завантаження середовища виконання Plugin. Це джерело, власником якого є маніфест, для фіксованих рядків каталогу, псевдонімів провайдерів, правил приглушення та режиму виявлення. Оновлення під час виконання досі належить коду середовища виконання провайдера, але маніфест повідомляє ядру, коли потрібне середовище виконання. ```json { "providers": ["openai"], "modelCatalog": { "providers": { "openai": { "baseUrl": "https://api.openai.com/v1", "api": "openai-responses", "models": [ { "id": "gpt-5.4", "name": "GPT-5.4", "input": ["text", "image"], "reasoning": true, "contextWindow": 256000, "maxTokens": 128000, "cost": { "input": 1.25, "output": 10, "cacheRead": 0.125 }, "status": "available", "tags": ["default"] } ] } }, "aliases": { "azure-openai-responses": { "provider": "openai", "api": "azure-openai-responses" } }, "suppressions": [ { "provider": "azure-openai-responses", "model": "gpt-5.3-codex-spark", "reason": "not available on Azure OpenAI Responses" } ], "discovery": { "openai": "static" } } } ``` Поля верхнього рівня: | Поле | Тип | Що це означає | | ---------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `providers` | `Record` | Рядки каталогу для ідентифікаторів провайдерів, власником яких є цей Plugin. Ключі також мають бути в `providers` верхнього рівня. | | `aliases` | `Record` | Псевдоніми провайдерів, які мають зіставлятися з власним провайдером для планування каталогу або приглушення. | | `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin приглушує з причини, специфічної для провайдера. | | `discovery` | `Record` | Чи каталог провайдера можна прочитати з метаданих маніфесту, оновити в кеш, чи він потребує середовища виконання. | | `runtimeAugment` | `boolean` | Установлюйте `true` лише тоді, коли середовище виконання провайдера має додавати рядки каталогу після планування маніфесту/конфігурації. | `aliases` бере участь у пошуку власника провайдера для планування каталогу моделей. Цілі псевдонімів мають бути провайдерами верхнього рівня, власником яких є той самий Plugin. Коли відфільтрований за провайдером список використовує псевдонім, OpenClaw може прочитати маніфест власника та застосувати перевизначення API/base URL псевдоніма без завантаження середовища виконання провайдера. Псевдоніми не розгортають нефільтровані списки каталогу; широкі списки виводять лише рядки канонічного провайдера-власника. `suppressions` замінює старий hook середовища виконання провайдера `suppressBuiltInModel`. Записи приглушення враховуються лише тоді, коли провайдер належить Plugin або оголошений як ключ `modelCatalog.aliases`, що вказує на власний провайдер. Hooks приглушення середовища виконання більше не викликаються під час розв'язання моделі. Поля провайдера: | Поле | Тип | Що це означає | | --------- | ------------------------ | ----------------------------------------------------------------- | | `baseUrl` | `string` | Необов'язковий базовий URL за замовчуванням для моделей у цьому каталозі провайдера. | | `api` | `ModelApi` | Необов'язковий адаптер API за замовчуванням для моделей у цьому каталозі провайдера. | | `headers` | `Record` | Необов'язкові статичні заголовки, що застосовуються до цього каталогу провайдера. | | `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`. | | `compat` | `object` | Необов'язкові прапорці сумісності, що відповідають сумісності конфігурації моделі OpenClaw. | | `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Приглушуйте лише тоді, коли рядок взагалі не має з'являтися. | | `statusReason` | `string` | Необов'язкова причина, що показується зі статусом, відмінним від available. | | `replaces` | `string[]` | Старі локальні для провайдера ідентифікатори моделей, які ця модель замінює. | | `replacedBy` | `string` | Локальний для провайдера ідентифікатор моделі-заміни для застарілих рядків. | | `tags` | `string[]` | Стабільні теги, які використовуються засобами вибору та фільтрами. | Поля приглушення: | Поле | Тип | Що це означає | | -------------------------- | ---------- | --------------------------------------------------------------------------------------------------------- | | `provider` | `string` | Ідентифікатор провайдера для upstream-рядка, який треба приглушити. Має належати цьому Plugin або бути оголошеним як власний псевдонім. | | `model` | `string` | Локальний для провайдера ідентифікатор моделі, який треба приглушити. | | `reason` | `string` | Необов'язкове повідомлення, що показується, коли приглушений рядок запитують напряму. | | `when.baseUrlHosts` | `string[]` | Необов'язковий список ефективних хостів базового URL провайдера, потрібних для застосування приглушення. | | `when.providerConfigApiIn` | `string[]` | Необов'язковий список точних значень `api` конфігурації провайдера, потрібних для застосування приглушення. | Не розміщуйте в `modelCatalog` дані, призначені лише для середовища виконання. Використовуйте `static` лише тоді, коли рядки маніфесту достатньо повні, щоб поверхні списку й вибору, відфільтровані за провайдером, могли пропустити виявлення через реєстр/середовище виконання. Використовуйте `refreshable`, коли рядки маніфесту є корисними початковими або додатковими рядками для списку, але оновлення/кеш може додати більше рядків пізніше; рядки refreshable самі по собі не є авторитетними. Використовуйте `runtime`, коли OpenClaw має завантажити середовище виконання провайдера, щоб знати список. ## Довідка modelIdNormalization Використовуйте `modelIdNormalization` для дешевого, керованого провайдером очищення ідентифікатора моделі, яке має відбутися до завантаження середовища виконання провайдера. Це зберігає псевдоніми, як-от короткі назви моделей, локальні для провайдера застарілі ідентифікатори та правила префіксів проксі, у маніфесті Plugin власника, а не в таблицях вибору моделей ядра. ```json { "providers": ["anthropic", "openrouter"], "modelIdNormalization": { "providers": { "anthropic": { "aliases": { "sonnet-4.6": "claude-sonnet-4-6" } }, "openrouter": { "prefixWhenBare": "openrouter" } } } } ``` Поля провайдера: | Поле | Тип | Що це означає | | ------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------- | | `aliases` | `Record` | Точні псевдоніми ідентифікаторів моделей без урахування регістру. Значення повертаються як записано. | | `stripPrefixes` | `string[]` | Префікси, які треба видалити перед пошуком псевдоніма; корисно для застарілого дублювання provider/model. | | `prefixWhenBare` | `string` | Префікс, який треба додати, коли нормалізований ідентифікатор моделі ще не містить `/`. | | `prefixWhenBareAfterAliasStartsWith` | `object[]` | Умовні правила префікса для bare-id після пошуку псевдоніма, ключовані за `modelPrefix` і `prefix`. | ## Довідка providerEndpoints Використовуйте `providerEndpoints` для класифікації endpoint, яку загальна політика запитів має знати до завантаження середовища виконання провайдера. Ядро досі володіє значенням кожного `endpointClass`; маніфести Plugin володіють метаданими хоста та базового URL. Поля кінцевої точки: | Поле | Тип | Що це означає | | ------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------- | | `endpointClass` | `string` | Відомий клас кінцевої точки ядра, як-от `openrouter`, `moonshot-native` або `google-vertex`. | | `hosts` | `string[]` | Точні імена хостів, які зіставляються з класом кінцевої точки. | | `hostSuffixes` | `string[]` | Суфікси хостів, які зіставляються з класом кінцевої точки. Додавайте префікс `.` для збігу лише за суфіксом домену. | | `baseUrls` | `string[]` | Точні нормалізовані базові URL HTTP(S), які зіставляються з класом кінцевої точки. | | `googleVertexRegion` | `string` | Статичний регіон Google Vertex для точних глобальних хостів. | | `googleVertexRegionHostSuffix` | `string` | Суфікс, який потрібно вилучити зі збіжних хостів, щоб відкрити префікс регіону Google Vertex. | ## Довідка providerRequest Використовуйте `providerRequest` для дешевих метаданих сумісності запитів, які потрібні загальній політиці запитів без завантаження runtime постачальника. Залишайте переписування payload, специфічне для поведінки, у runtime-хуках постачальника або спільних допоміжних функціях сімейства постачальників. ```json { "providers": ["vllm"], "providerRequest": { "providers": { "vllm": { "family": "vllm", "openAICompletions": { "supportsStreamingUsage": true } } } } } ``` Поля постачальника: | Поле | Тип | Що це означає | | --------------------- | ------------ | ----------------------------------------------------------------------------------------------------- | | `family` | `string` | Мітка сімейства постачальника, яку використовують загальні рішення сумісності запитів і діагностика. | | `compatibilityFamily` | `"moonshot"` | Необов’язковий бакет сумісності сімейства постачальників для спільних допоміжних функцій запитів. | | `openAICompletions` | `object` | Прапорці запитів completions, сумісних з OpenAI; наразі `supportsStreamingUsage`. | ## Довідка secretProviderIntegrations Використовуйте `secretProviderIntegrations`, коли plugin може опублікувати повторно використовуваний попередньо налаштований exec-постачальник SecretRef. OpenClaw читає ці метадані до завантаження runtime plugin, зберігає належність plugin у `secrets.providers..pluginIntegration` і залишає фактичне розв’язання секретів runtime SecretRef. Попередні налаштування доступні лише для вбудованих plugins і встановлених plugins, виявлених із керованих коренів встановлення plugin, як-от встановлення з git і ClawHub. ```json { "secretProviderIntegrations": { "secret-store": { "providerAlias": "team-secrets", "displayName": "Team secrets", "source": "exec", "command": "${node}", "args": ["./bin/resolve-secrets.mjs"] } } } ``` Ключ мапи — це id інтеграції. Якщо `providerAlias` пропущено, OpenClaw використовує id інтеграції як alias постачальника SecretRef. Alias постачальників мають відповідати звичайному шаблону alias постачальника SecretRef, наприклад `team-secrets` або `onepassword-work`. Коли оператор вибирає попереднє налаштування, OpenClaw записує посилання на постачальника такого вигляду: ```json { "secrets": { "providers": { "team-secrets": { "source": "exec", "pluginIntegration": { "pluginId": "acme-secrets", "integrationId": "secret-store" } } } } } ``` Під час запуску або перезавантаження OpenClaw розв’язує цього постачальника, завантажуючи поточні метадані маніфесту plugin, перевіряючи, що plugin-власник встановлений і активний, та матеріалізуючи exec-команду з маніфесту. Вимкнення або видалення plugin відкликає постачальника для активних SecretRefs. Оператори, яким потрібна автономна exec-конфігурація, все ще можуть напряму записувати ручних постачальників `command`/`args`. Наразі підтримуються лише попередні налаштування `source: "exec"`. `command` має бути `${node}`, а `args[0]` має бути скриптом-розв’язувачем відносно кореня plugin з префіксом `./`. OpenClaw матеріалізує його під час запуску або перезавантаження в поточний виконуваний файл Node і абсолютний шлях до скрипта всередині plugin. Параметри Node, як-от `--require`, `--import`, `--loader`, `--env-file`, `--eval` і `--print`, не є частиною контракту попереднього налаштування маніфесту. Оператори, яким потрібні команди не на Node, можуть напряму налаштувати автономних ручних exec-постачальників. OpenClaw виводить `trustedDirs` для попередніх налаштувань маніфесту з кореня plugin і, для попередніх налаштувань `${node}`, з каталогу поточного виконуваного файла Node. Задані в маніфесті `trustedDirs` ігноруються. Інші параметри exec-постачальника, як-от `timeoutMs`, `maxOutputBytes`, `jsonOnly`, `env`, `passEnv` і `allowInsecurePath`, передаються до звичайної конфігурації exec-постачальника SecretRef. ## Довідка modelPricing Використовуйте `modelPricing`, коли постачальнику потрібна поведінка pricing у площині керування до завантаження runtime. Pricing-кеш Gateway читає ці метадані без імпорту runtime-коду постачальника. ```json { "providers": ["ollama", "openrouter"], "modelPricing": { "providers": { "ollama": { "external": false }, "openrouter": { "openRouter": { "passthroughProviderModel": true }, "liteLLM": false } } } } ``` Поля постачальника: | Поле | Тип | Що це означає | | ------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------ | | `external` | `boolean` | Установіть `false` для локальних або self-hosted постачальників, які ніколи не мають отримувати pricing OpenRouter або LiteLLM. | | `openRouter` | `false \| object` | Зіставлення для пошуку pricing OpenRouter. `false` вимикає пошук OpenRouter для цього постачальника. | | `liteLLM` | `false \| object` | Зіставлення для пошуку pricing LiteLLM. `false` вимикає пошук LiteLLM для цього постачальника. | Поля джерела: | Поле | Тип | Що це означає | | -------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------- | | `provider` | `string` | id постачальника зовнішнього каталогу, коли він відрізняється від id постачальника OpenClaw, наприклад `z-ai` для постачальника `zai`. | | `passthroughProviderModel` | `boolean` | Розглядати id моделей зі скісною рискою як вкладені посилання постачальник/модель, корисно для proxy-постачальників, як-от OpenRouter. | | `modelIdTransforms` | `"version-dots"[]` | Додаткові варіанти id моделей зовнішнього каталогу. `version-dots` пробує id версій із крапками, як-от `claude-opus-4.6`. | ### Індекс постачальників OpenClaw Індекс постачальників OpenClaw — це належні OpenClaw preview-метадані для постачальників, чиї plugins можуть ще не бути встановлені. Він не є частиною маніфесту plugin. Маніфести plugins залишаються авторитетним джерелом для встановлених plugins. Індекс постачальників — це внутрішній fallback-контракт, який майбутні поверхні встановлюваних постачальників і вибору моделей до встановлення споживатимуть, коли plugin постачальника не встановлений. Порядок авторитетності каталогу: 1. Конфігурація користувача. 2. Маніфест встановленого plugin `modelCatalog`. 3. Кеш каталогу моделей з явного оновлення. 4. Preview-рядки Індексу постачальників OpenClaw. Індекс постачальників не має містити секретів, увімкненого стану, runtime-хуків або live-даних моделей, специфічних для облікового запису. Його preview-каталоги використовують таку саму форму рядка постачальника `modelCatalog`, як і маніфести plugins, але мають лишатися обмеженими стабільними display-метаданими, якщо поля runtime-адаптера, як-от `api`, `baseUrl`, pricing або прапорці сумісності, не підтримуються навмисно узгодженими з маніфестом встановленого plugin. Постачальники з live-виявленням `/models` мають записувати оновлені рядки через явний шлях кешу каталогу моделей замість того, щоб звичайний listing або onboarding викликав API постачальника. Записи Індексу постачальників також можуть містити метадані встановлюваного plugin для постачальників, чий plugin було винесено з ядра або який інакше ще не встановлений. Ці метадані віддзеркалюють шаблон каталогу каналів: назви пакета, npm install spec, очікуваної цілісності та дешевих міток вибору автентифікації достатньо, щоб показати варіант встановлюваного налаштування. Щойно plugin встановлено, його маніфест перемагає, а запис Індексу постачальників ігнорується для цього постачальника. Застарілі ключі можливостей верхнього рівня deprecated. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під `contracts`; звичайне завантаження маніфесту більше не розглядає ці поля верхнього рівня як володіння можливостями. ## Маніфест і package.json Ці два файли виконують різні завдання: | Файл | Для чого використовувати | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані вибору автентифікації та підказки UI, які мають існувати до запуску коду plugin | | `package.json` | npm-метадані, встановлення залежностей і блок `openclaw`, який використовується для entrypoints, install gating, setup або метаданих каталогу | Якщо ви не впевнені, де має бути частина метаданих, скористайтеся цим правилом: - якщо OpenClaw має знати це до завантаження коду plugin, помістіть це в `openclaw.plugin.json` - якщо це стосується пакування, entry-файлів або поведінки npm install, помістіть це в `package.json` ### Поля package.json, які впливають на виявлення Деякі pre-runtime метадані plugin навмисно живуть у `package.json` під блоком `openclaw`, а не в `openclaw.plugin.json`. `openclaw.bundle` і `openclaw.bundle.json` не є контрактами plugin OpenClaw; native plugins мають використовувати `openclaw.plugin.json` плюс підтримувані поля `package.json#openclaw` нижче. Важливі приклади: | Поле | Що воно означає | | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `openclaw.extensions` | Оголошує нативні точки входу плагіна. Має залишатися всередині каталогу пакета плагіна. | | `openclaw.runtimeExtensions` | Оголошує зібрані точки входу середовища виконання JavaScript для встановлених пакетів. Має залишатися всередині каталогу пакета плагіна. | | `openclaw.setupEntry` | Легка точка входу лише для налаштування, що використовується під час початкового налаштування, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Має залишатися всередині каталогу пакета плагіна. | | `openclaw.runtimeSetupEntry` | Оголошує зібрану точку входу налаштування JavaScript для встановлених пакетів. Потребує `setupEntry`, має існувати й має залишатися всередині каталогу пакета плагіна. | | `openclaw.channel` | Дешеві метадані каталогу каналів, як-от мітки, шляхи документації, псевдоніми та текст для вибору. | | `openclaw.channel.commands` | Статичні метадані нативних команд і автоматичних стандартних значень нативних Skills, що використовуються конфігурацією, аудитом і поверхнями списку команд до завантаження середовища виконання каналу. | | `openclaw.channel.configuredState` | Легкі метадані перевірки налаштованого стану, які можуть відповісти на запитання «чи вже існує налаштування лише через env?» без завантаження повного середовища виконання каналу. | | `openclaw.channel.persistedAuthState` | Легкі метадані перевірки збереженого стану автентифікації, які можуть відповісти на запитання «чи вже виконано вхід у щось?» без завантаження повного середовища виконання каналу. | | `openclaw.install.clawhubSpec` / `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для вбудованих і зовнішньо опублікованих плагінів. | | `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | | `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw з використанням нижньої межі semver, як-от `>=2026.3.22` або `>=2026.5.1-beta.1`. | | `openclaw.compat.pluginApi` | Мінімальний діапазон API плагінів OpenClaw, потрібний цьому пакету, з використанням нижньої межі semver, як-от `>=2026.5.27`. | | `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm-дистрибутива, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт за ним. | | `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення вбудованого плагіна, коли конфігурація недійсна. | | `openclaw.install.requiredPlatformPackages` | Псевдоніми пакетів npm, які мають матеріалізуватися, коли їхні платформні обмеження lockfile відповідають поточному хосту. | | `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу середовища виконання налаштування завантажуватися перед початком прослуховування, а потім відкладає повний налаштований плагін каналу до активації після прослуховування. | Метадані маніфесту визначають, які варіанти провайдера/каналу/налаштування з’являються в початковому налаштуванні до завантаження середовища виконання. `package.json#openclaw.install` повідомляє початковому налаштуванню, як отримати або ввімкнути цей плагін, коли користувач вибирає один із цих варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`. `openclaw.install.minHostVersion` застосовується під час встановлення та завантаження реєстру маніфестів для невбудованих джерел плагінів. Недійсні значення відхиляються; новіші, але дійсні значення пропускають зовнішні плагіни на старіших хостах. Вбудовані вихідні плагіни вважаються співверсійними з checkout хоста. `openclaw.install.requiredPlatformPackages` призначений для пакетів npm, які надають потрібні нативні бінарні файли через опціональні платформні псевдоніми. Укажіть просту назву пакета npm для кожного підтримуваного платформного псевдоніма. Під час встановлення npm OpenClaw перевіряє лише оголошений псевдонім, чиї обмеження lockfile відповідають поточному хосту. Якщо npm повідомляє про успіх, але пропускає цей псевдонім, OpenClaw повторює спробу один раз зі свіжим кешем і відкочує встановлення, якщо псевдонім досі відсутній. `openclaw.compat.pluginApi` застосовується під час встановлення пакета для невбудованих джерел плагінів. Використовуйте його для нижньої межі API SDK/середовища виконання плагінів OpenClaw, під яку було зібрано пакет. Вона може бути суворішою за `minHostVersion`, коли пакету плагіна потрібен новіший API, але він усе ще зберігає нижчу підказку встановлення для інших потоків. Офіційна синхронізація релізу OpenClaw типово піднімає наявні офіційні нижні межі API плагінів до версії релізу OpenClaw, але релізи лише плагінів можуть зберігати нижчу межу, коли пакет навмисно підтримує старіші хости. Не використовуйте лише версію пакета як контракт сумісності. `peerDependencies.openclaw` залишається метаданими пакета npm; OpenClaw використовує контракт `openclaw.compat.pluginApi` для рішень щодо сумісності встановлення. Офіційні метадані встановлення за потреби мають використовувати `clawhubSpec`, коли плагін опубліковано на ClawHub; початкове налаштування трактує це як бажане віддалене джерело й записує факти артефакта ClawHub після встановлення. `npmSpec` залишається резервним варіантом сумісності для пакетів, які ще не перейшли на ClawHub. Точне закріплення версії npm уже міститься в `npmSpec`, наприклад `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні зовнішні записи каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися закритою помилкою, якщо отриманий артефакт npm більше не відповідає закріпленому релізу. Інтерактивне початкове налаштування все ще пропонує довірені npm-специфікації реєстру, зокрема прості назви пакетів і dist-tags, для сумісності. Діагностика каталогу може розрізняти точні, плаваючі, закріплені цілісністю, без цілісності, з невідповідністю назви пакета та недійсні джерела стандартного вибору. Вона також попереджає, коли `expectedIntegrity` присутній, але немає дійсного джерела npm, яке він може закріпити. Коли `expectedIntegrity` присутній, потоки встановлення/оновлення примусово його застосовують; коли його пропущено, розв’язання реєстру записується без закріплення цілісності. Плагіни каналів мають надавати `openclaw.setupEntry`, коли статус, список каналів або сканування SecretRef мають ідентифікувати налаштовані облікові записи без завантаження повного середовища виконання. Точка входу налаштування має надавати метадані каналу, а також безпечні для налаштування адаптери конфігурації, статусу й секретів; тримайте мережеві клієнти, слухачі Gateway і транспортні середовища виконання в основній точці входу розширення. Поля точок входу середовища виконання не перевизначають перевірки меж пакета для полів вихідних точок входу. Наприклад, `openclaw.runtimeExtensions` не може зробити шлях `openclaw.extensions`, що виходить за межі, придатним до завантаження. `openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не робить довільні зламані конфігурації придатними до встановлення. Сьогодні він лише дозволяє потокам встановлення відновлюватися після конкретних застарілих збоїв оновлення вбудованого плагіна, як-от відсутній шлях вбудованого плагіна або застарілий запис `channels.` для того самого вбудованого плагіна. Непов’язані помилки конфігурації все ще блокують встановлення й скеровують операторів до `openclaw doctor --fix`. `openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки: ```json { "openclaw": { "channel": { "id": "whatsapp", "persistedAuthState": { "specifier": "./auth-presence", "exportName": "hasAnyWhatsAppAuth" } } } } ``` Використовуйте його, коли потокам налаштування, doctor, статусу або наявності лише для читання потрібна дешева перевірка автентифікації так/ні до завантаження повного плагіна каналу. Збережений стан автентифікації не є налаштованим станом каналу: не використовуйте ці метадані для автоматичного ввімкнення плагінів, відновлення залежностей середовища виконання або рішення, чи має завантажуватися середовище виконання каналу. Цільовий export має бути невеликою функцією, яка читає лише збережений стан; не маршрутизуйте її через повний barrel середовища виконання каналу. `openclaw.channel.configuredState` має таку саму форму для дешевих перевірок налаштованості лише через env: ```json { "openclaw": { "channel": { "id": "telegram", "configuredState": { "specifier": "./configured-state", "exportName": "hasTelegramConfiguredState" } } } } ``` Використовуйте його, коли канал може відповісти про налаштований стан з env або інших крихітних нерuntime-вхідних даних. Якщо перевірці потрібне повне розв’язання конфігурації або справжнє середовище виконання каналу, залиште цю логіку в хуку плагіна `config.hasConfiguredState`. ## Пріоритет виявлення (дублікати ідентифікаторів плагінів) OpenClaw виявляє плагіни з кількох коренів. Сирий порядок сканування файлової системи див. у [Порядок сканування плагінів](/uk/gateway/configuration-reference#plugin-scan-order). Якщо два виявлення мають той самий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. Пріоритет, від найвищого до найнижчого: 1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` 2. **Вбудований** — плагіни, що постачаються з OpenClaw 3. **Глобальне встановлення** — плагіни, встановлені в глобальний корінь плагінів OpenClaw 4. **Робочий простір** — плагіни, виявлені відносно поточного робочого простору Наслідки: - Форкнута або застаріла копія вбудованого плагіна, що лежить у робочому просторі, не затінятиме вбудовану збірку. - Щоб справді перевизначити вбудований плагін локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення в робочому просторі. - Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. - Перевизначення дублікатів, вибрані конфігурацією, формулюються в діагностиці як явні перевизначення, але все одно попереджають, щоб застарілі форки й випадкові затінення залишалися видимими. ## Вимоги JSON Schema - **Кожен Plugin має постачатися з JSON-схемою**, навіть якщо він не приймає конфігурацію. - Порожня схема прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`). - Схеми перевіряються під час читання/запису конфігурації, а не під час виконання. - Під час розширення або форку вбудованого Plugin новими ключами конфігурації одночасно оновіть `configSchema` у `openclaw.plugin.json` цього Plugin. Схеми вбудованих Plugin є строгими, тому додавання `plugins.entries..config.myNewKey` у конфігурацію користувача без додавання `myNewKey` до `configSchema.properties` буде відхилено до завантаження середовища виконання Plugin. Приклад розширення схеми: ```json { "configSchema": { "type": "object", "additionalProperties": false, "properties": { "myNewKey": { "type": "string" } } } } ``` ## Поведінка перевірки - Невідомі ключі `channels.*` є **помилками**, якщо ідентифікатор каналу не оголошено в маніфесті Plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` мають посилатися на **доступні для виявлення** ідентифікатори Plugin. Невідомі ідентифікатори є **помилками**. - Якщо Plugin встановлено, але він має пошкоджений або відсутній маніфест чи схему, перевірка не проходить, а Doctor повідомляє про помилку Plugin. - Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається, а **попередження** відображається в Doctor і журналах. Повну схему `plugins.*` див. у [довіднику з конфігурації](/uk/gateway/configuration). ## Примітки - Маніфест **обов’язковий для нативних Plugin OpenClaw**, включно із завантаженнями з локальної файлової системи. Середовище виконання все одно завантажує модуль Plugin окремо; маніфест потрібен лише для виявлення та перевірки. - Нативні маніфести обробляються як JSON5, тому коментарі, кінцеві коми й ключі без лапок приймаються, якщо кінцеве значення все ще є об’єктом. - Завантажувач маніфестів читає лише документовані поля маніфесту. Уникайте власних ключів верхнього рівня. - `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin вони не потрібні. - `providerCatalogEntry` має залишатися легковагим і не повинен імпортувати широкий код середовища виконання; використовуйте його для статичних метаданих каталогу провайдерів або вузьких дескрипторів виявлення, а не для виконання під час запиту. - Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (за замовчуванням `legacy`). - Оголошуйте ексклюзивний тип Plugin у цьому маніфесті. `OpenClawPluginDefinition.kind` у точці входу середовища виконання застарів і залишається лише як резерв сумісності для старіших Plugin. - Метадані змінних середовища (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Стан, аудит, перевірка доставки Cron та інші поверхні лише для читання все одно застосовують довіру до Plugin і політику фактичної активації, перш ніж вважати змінну середовища налаштованою. - Для метаданих майстра середовища виконання, яким потрібен код провайдера, див. [хуки середовища виконання провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). - Якщо ваш Plugin залежить від нативних модулів, задокументуйте кроки збирання та будь-які вимоги до списку дозволів менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане Початок роботи з Plugin. Внутрішня архітектура та модель можливостей. Довідник Plugin SDK та імпорти підшляхів.