Маніфест Plugin

Ця сторінка призначена лише для нативного маніфесту Plugin OpenClaw.

Сумісні схеми пакетів див. у розділі Пакети Plugin.

Сумісні формати пакетів використовують інші файли маніфестів:

• Пакет 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. Про нативну модель можливостей і поточні настанови щодо зовнішньої сумісності: Модель можливостей.

Що робить цей файл

openclaw.plugin.json — це метадані, які OpenClaw читає до завантаження коду вашого Plugin. Усе нижче має бути достатньо дешевим для перевірки без запуску середовища виконання Plugin.

Використовуйте його для:

• ідентифікації Plugin, перевірки конфігурації та підказок інтерфейсу конфігурації
• метаданих автентифікації, адаптації та налаштування (псевдонім, автоматичне ввімкнення, змінні середовища провайдера, варіанти автентифікації)
• підказок активації для поверхонь площини керування
• скороченого володіння сімейством моделей
• статичних знімків володіння можливостями (contracts)
• метаданих засобу виконання QA, які може перевіряти спільний хост openclaw qa
• метаданих конфігурації для окремих каналів, об’єднаних у каталог і поверхні перевірки

Не використовуйте його для: реєстрації поведінки під час виконання, оголошення точок входу коду або метаданих встановлення npm. Вони належать до коду вашого Plugin і package.json.

Мінімальний приклад

{  "id": "voice-call",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Розширений приклад

{  "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 <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"      }    }  }}

Довідник полів верхнього рівня

Довідник метаданих постачальників генерації

Поля метаданих постачальника генерації описують статичні сигнали автентифікації для постачальників, оголошених у відповідному списку contracts.*GenerationProviders. OpenClaw читає ці поля до завантаження середовища виконання постачальника, щоб основні інструменти могли визначити, чи доступний постачальник генерації, без імпорту кожного плагіна постачальника.

Використовуйте ці поля лише для дешевих декларативних фактів. Транспорт, перетворення запитів, оновлення токенів, перевірка облікових даних і фактична поведінка генерації залишаються в середовищі виконання плагіна.

{  "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"]          }        }      ]    }  }}

Кожен запис метаданих підтримує:

Кожен запис configSignals підтримує:

Кожна перевірка mode підтримує:

Кожен запис authSignals підтримує:

Кожна перевірка providerBaseUrl підтримує:

Довідник метаданих інструментів

toolMetadata використовує ті самі форми configSignals і authSignals, що й метадані постачальника генерації, з ключами за назвою інструмента. contracts.tools оголошує власність. toolMetadata оголошує дешеві докази доступності, щоб OpenClaw міг уникнути імпорту середовища виконання плагіна лише для того, щоб фабрика інструментів повернула null.

{  "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 читає це до завантаження середовища виконання постачальника. Списки налаштування постачальників використовують ці вибори маніфесту, варіанти налаштування, отримані з дескриптора, і метадані каталогу встановлення без завантаження середовища виконання постачальника.

Довідник commandAliases

Використовуйте commandAliases, коли Plugin володіє назвою runtime-команди, яку користувачі можуть помилково додати в plugins.allow або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпортування runtime-коду Plugin.

{  "commandAliases": [    {      "name": "dreaming",      "kind": "runtime-slash",      "cliCommand": "memory"    }  ]}

Довідник 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 або інших вужчих тригерів активації.

{  "activation": {    "onStartup": false,    "onProviders": ["openai"],    "onCommands": ["models"],    "onChannels": ["web"],    "onRoutes": ["gateway-webhook"],    "onConfigPaths": ["browser"],    "onCapabilities": ["provider", "tool"]  }}

Поточні 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.

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"    }  ]}

Довідник setup

Використовуйте setup, коли поверхням налаштування та первинного налаштування потрібні дешеві метадані, що належать Plugin, до завантаження середовища виконання.

{  "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

authEvidence призначено для локальних маркерів облікових даних, що належать провайдеру й можуть бути перевірені без завантаження runtime-коду. Ці перевірки мають залишатися дешевими й локальними: без мережевих викликів, без читання keychain або менеджера секретів, без shell-команд і без проб API провайдера.

Підтримувані записи доказів:

Поля setup

Довідник uiHints

uiHints — це мапа від назв полів конфігурації до невеликих підказок рендерингу.

{  "uiHints": {    "apiKey": {      "label": "API key",      "help": "Used for OpenRouter requests",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

Кожна підказка поля може містити:

Довідник contracts

Використовуйте contracts лише для статичних метаданих володіння можливостями, які OpenClaw може читати без імпорту runtime Plugin.

{  "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"]  }}

Кожен список є необов’язковим:

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.

{  "contracts": {    "mediaUnderstandingProviders": ["example"]  },  "mediaUnderstandingProviderMetadata": {    "example": {      "capabilities": ["image", "audio"],      "defaultModels": {        "image": "example-vision-latest",        "audio": "example-transcribe-latest"      },      "autoPriority": {        "image": 40      },      "nativeDocumentInputs": ["pdf"]    }  }}

Кожен запис провайдера може містити:

Довідник channelConfigs

Використовуйте channelConfigs, коли channel plugin потребує дешевих метаданих config до завантаження середовища виконання. Read-only виявлення setup/status каналу може використовувати ці метадані безпосередньо для налаштованих зовнішніх каналів, коли запис setup недоступний, або коли setup.requiresRuntime: false оголошує, що середовище виконання setup не потрібне.

channelConfigs — це метадані маніфесту plugin, а не новий top-level розділ користувацького config. Користувачі й надалі налаштовують екземпляри каналів у channels.<channel-id>. OpenClaw читає метадані маніфесту, щоб вирішити, який plugin володіє цим налаштованим каналом, до виконання коду середовища виконання plugin.

Для channel plugin configSchema і channelConfigs описують різні шляхи:

• configSchema перевіряє plugins.entries.<plugin-id>.config
• channelConfigs.<channel-id>.schema перевіряє channels.<channel-id>

Non-bundled plugins, які оголошують channels[], також мають оголошувати відповідні записи channelConfigs. Без них OpenClaw усе ще може завантажити plugin, але cold-path схема config, setup і поверхні Control UI не можуть знати форму параметрів, якими володіє канал, доки не виконається середовище виконання plugin.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled і nativeSkillsAutoEnabled можуть оголошувати статичні стандартні значення auto для перевірок config команд, які виконуються до завантаження середовища виконання каналу. Вбудовані канали також можуть публікувати ті самі стандартні значення через package.json#openclaw.channel.commands разом з іншими метаданими каталогу каналів, якими володіє їхній package.

{  "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"]    }  }}

Кожен запис каналу може містити:

Заміна іншого channel plugin

Використовуйте preferOver, коли ваш plugin є бажаним власником для ідентифікатора каналу, який також може надавати інший plugin. Типові випадки — перейменований ідентифікатор plugin, standalone plugin, що замінює вбудований plugin, або підтримуваний fork, який зберігає той самий ідентифікатор каналу для сумісності config.

{  "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.

{  "modelSupport": {    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],    "modelPatterns": ["^computer-use-preview"]  }}

OpenClaw застосовує такий пріоритет:

• явні посилання provider/model використовують метадані маніфесту providers власника
• modelPatterns мають перевагу над modelPrefixes
• якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований Plugin
• решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера

Поля:

Записи modelPatterns компілюються через compileSafeRegex, який відхиляє шаблони з вкладеним повторенням (наприклад, (a+)+$). Шаблони, що не проходять перевірку безпеки, тихо пропускаються, так само як синтаксично недійсний regex. Тримайте шаблони простими й уникайте вкладених квантифікаторів.

Довідка modelCatalog

Використовуйте modelCatalog, коли OpenClaw має знати метадані моделей провайдера до завантаження середовища виконання Plugin. Це джерело, власником якого є маніфест, для фіксованих рядків каталогу, псевдонімів провайдерів, правил приглушення та режиму виявлення. Оновлення під час виконання досі належить коду середовища виконання провайдера, але маніфест повідомляє ядру, коли потрібне середовище виконання.

{  "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"    }  }}

Поля верхнього рівня:

aliases бере участь у пошуку власника провайдера для планування каталогу моделей. Цілі псевдонімів мають бути провайдерами верхнього рівня, власником яких є той самий Plugin. Коли відфільтрований за провайдером список використовує псевдонім, OpenClaw може прочитати маніфест власника та застосувати перевизначення API/base URL псевдоніма без завантаження середовища виконання провайдера. Псевдоніми не розгортають нефільтровані списки каталогу; широкі списки виводять лише рядки канонічного провайдера-власника.

suppressions замінює старий hook середовища виконання провайдера suppressBuiltInModel. Записи приглушення враховуються лише тоді, коли провайдер належить Plugin або оголошений як ключ modelCatalog.aliases, що вказує на власний провайдер. Hooks приглушення середовища виконання більше не викликаються під час розв'язання моделі.

Поля провайдера:

Поля моделі:

Поля приглушення:

Не розміщуйте в modelCatalog дані, призначені лише для середовища виконання. Використовуйте static лише тоді, коли рядки маніфесту достатньо повні, щоб поверхні списку й вибору, відфільтровані за провайдером, могли пропустити виявлення через реєстр/середовище виконання. Використовуйте refreshable, коли рядки маніфесту є корисними початковими або додатковими рядками для списку, але оновлення/кеш може додати більше рядків пізніше; рядки refreshable самі по собі не є авторитетними. Використовуйте runtime, коли OpenClaw має завантажити середовище виконання провайдера, щоб знати список.

Довідка modelIdNormalization

Використовуйте modelIdNormalization для дешевого, керованого провайдером очищення ідентифікатора моделі, яке має відбутися до завантаження середовища виконання провайдера. Це зберігає псевдоніми, як-от короткі назви моделей, локальні для провайдера застарілі ідентифікатори та правила префіксів проксі, у маніфесті Plugin власника, а не в таблицях вибору моделей ядра.

{  "providers": ["anthropic", "openrouter"],  "modelIdNormalization": {    "providers": {      "anthropic": {        "aliases": {          "sonnet-4.6": "claude-sonnet-4-6"        }      },      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  }}

Поля провайдера:

Довідка providerEndpoints

Використовуйте providerEndpoints для класифікації endpoint, яку загальна політика запитів має знати до завантаження середовища виконання провайдера. Ядро досі володіє значенням кожного endpointClass; маніфести Plugin володіють метаданими хоста та базового URL.

Поля кінцевої точки:

Довідка providerRequest

Використовуйте providerRequest для дешевих метаданих сумісності запитів, які потрібні загальній політиці запитів без завантаження runtime постачальника. Залишайте переписування payload, специфічне для поведінки, у runtime-хуках постачальника або спільних допоміжних функціях сімейства постачальників.

{  "providers": ["vllm"],  "providerRequest": {    "providers": {      "vllm": {        "family": "vllm",        "openAICompletions": {          "supportsStreamingUsage": true        }      }    }  }}

Поля постачальника:

Довідка secretProviderIntegrations

Використовуйте secretProviderIntegrations, коли plugin може опублікувати повторно використовуваний попередньо налаштований exec-постачальник SecretRef. OpenClaw читає ці метадані до завантаження runtime plugin, зберігає належність plugin у secrets.providers.<alias>.pluginIntegration і залишає фактичне розв’язання секретів runtime SecretRef. Попередні налаштування доступні лише для вбудованих plugins і встановлених plugins, виявлених із керованих коренів встановлення plugin, як-от встановлення з git і ClawHub.

{  "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 записує посилання на постачальника такого вигляду:

{  "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-коду постачальника.

{  "providers": ["ollama", "openrouter"],  "modelPricing": {    "providers": {      "ollama": {        "external": false      },      "openrouter": {        "openRouter": {          "passthroughProviderModel": true        },        "liteLLM": false      }    }  }}

Поля постачальника:

Поля джерела:

Індекс постачальників 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, помістіть це в 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 нижче.

Важливі приклади:

Метадані маніфесту визначають, які варіанти провайдера/каналу/налаштування з’являються в початковому налаштуванні до завантаження середовища виконання. 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.<id> для того самого вбудованого плагіна. Непов’язані помилки конфігурації все ще блокують встановлення й скеровують операторів до openclaw doctor --fix.

openclaw.channel.persistedAuthState — це метадані пакета для крихітного модуля перевірки:

{  "openclaw": {    "channel": {      "id": "whatsapp",      "persistedAuthState": {        "specifier": "./auth-presence",        "exportName": "hasAnyWhatsAppAuth"      }    }  }}

Використовуйте його, коли потокам налаштування, doctor, статусу або наявності лише для читання потрібна дешева перевірка автентифікації так/ні до завантаження повного плагіна каналу. Збережений стан автентифікації не є налаштованим станом каналу: не використовуйте ці метадані для автоматичного ввімкнення плагінів, відновлення залежностей середовища виконання або рішення, чи має завантажуватися середовище виконання каналу. Цільовий export має бути невеликою функцією, яка читає лише збережений стан; не маршрутизуйте її через повний barrel середовища виконання каналу.

openclaw.channel.configuredState має таку саму форму для дешевих перевірок налаштованості лише через env:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "specifier": "./configured-state",        "exportName": "hasTelegramConfiguredState"      }    }  }}

Використовуйте його, коли канал може відповісти про налаштований стан з env або інших крихітних нерuntime-вхідних даних. Якщо перевірці потрібне повне розв’язання конфігурації або справжнє середовище виконання каналу, залиште цю логіку в хуку плагіна config.hasConfiguredState.

Пріоритет виявлення (дублікати ідентифікаторів плагінів)

OpenClaw виявляє плагіни з кількох коренів. Сирий порядок сканування файлової системи див. у Порядок сканування плагінів. Якщо два виявлення мають той самий id, зберігається лише маніфест із найвищим пріоритетом; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним.

Пріоритет, від найвищого до найнижчого:

1. Вибраний конфігурацією — шлях, явно закріплений у plugins.entries.<id>
2. Вбудований — плагіни, що постачаються з OpenClaw
3. Глобальне встановлення — плагіни, встановлені в глобальний корінь плагінів OpenClaw
4. Робочий простір — плагіни, виявлені відносно поточного робочого простору

Наслідки:

• Форкнута або застаріла копія вбудованого плагіна, що лежить у робочому просторі, не затінятиме вбудовану збірку.
• Щоб справді перевизначити вбудований плагін локальним, закріпіть його через plugins.entries.<id>, щоб він переміг за пріоритетом, а не покладайтеся на виявлення в робочому просторі.
• Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
• Перевизначення дублікатів, вибрані конфігурацією, формулюються в діагностиці як явні перевизначення, але все одно попереджають, щоб застарілі форки й випадкові затінення залишалися видимими.

Вимоги JSON Schema

• Кожен Plugin має постачатися з JSON-схемою, навіть якщо він не приймає конфігурацію.
• Порожня схема прийнятна (наприклад, { "type": "object", "additionalProperties": false }).
• Схеми перевіряються під час читання/запису конфігурації, а не під час виконання.
• Під час розширення або форку вбудованого Plugin новими ключами конфігурації одночасно оновіть configSchema у openclaw.plugin.json цього Plugin. Схеми вбудованих Plugin є строгими, тому додавання plugins.entries.<id>.config.myNewKey у конфігурацію користувача без додавання myNewKey до configSchema.properties буде відхилено до завантаження середовища виконання Plugin.

Приклад розширення схеми:

{  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "myNewKey": {        "type": "string"      }    }  }}

Поведінка перевірки

• Невідомі ключі channels.* є помилками, якщо ідентифікатор каналу не оголошено в маніфесті Plugin.
• plugins.entries.<id>, plugins.allow, plugins.deny і plugins.slots.* мають посилатися на доступні для виявлення ідентифікатори Plugin. Невідомі ідентифікатори є помилками.
• Якщо Plugin встановлено, але він має пошкоджений або відсутній маніфест чи схему, перевірка не проходить, а Doctor повідомляє про помилку Plugin.
• Якщо конфігурація Plugin існує, але Plugin вимкнено, конфігурація зберігається, а попередження відображається в Doctor і журналах.

Повну схему plugins.* див. у довіднику з конфігурації.

Примітки

• Маніфест обов’язковий для нативних 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 і політику фактичної активації, перш ніж вважати змінну середовища налаштованою.
• Для метаданих майстра середовища виконання, яким потрібен код провайдера, див. хуки середовища виконання провайдера.
• Якщо ваш Plugin залежить від нативних модулів, задокументуйте кроки збирання та будь-які вимоги до списку дозволів менеджера пакетів (наприклад, pnpm allow-build-scripts + pnpm rebuild <package>).

Пов’язане