Маніфест Plugin

Ця сторінка описує маніфест нативного плагіна OpenClaw — openclaw.plugin.json. Про сумісні структури пакунків (Codex, Claude, Cursor) див. у розділі Пакунки плагінів.

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

• Пакунок Codex: .codex-plugin/plugin.json
• Пакунок Claude: .claude-plugin/plugin.json або стандартна структура компонентів Claude без маніфесту
• Пакунок Cursor: .cursor-plugin/plugin.json

OpenClaw автоматично виявляє ці структури, але не перевіряє їх за наведеною нижче схемою openclaw.plugin.json. Для сумісного пакунка OpenClaw зчитує метадані пакунка, оголошені кореневі каталоги Skills, кореневі каталоги команд Claude, стандартні значення Claude з settings.json, стандартні налаштування LSP Claude та підтримувані набори хуків, якщо структура відповідає вимогам середовища виконання OpenClaw.

Кожен нативний плагін OpenClaw повинен містити openclaw.plugin.json у кореневому каталозі плагіна. OpenClaw зчитує його для перевірки конфігурації без виконання коду плагіна. Відсутній або недійсний маніфест блокує перевірку конфігурації та вважається помилкою плагіна.

Повний посібник із системи плагінів див. у розділі Плагіни, а опис нативної моделі можливостей і актуальні рекомендації щодо зовнішньої сумісності — у розділі Модель можливостей.

Призначення цього файлу

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

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

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

Не використовуйте його для: реєстрації поведінки під час виконання, оголошення точок входу коду або метаданих встановлення npm. Вони мають бути у коді вашого плагіна та 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"      }    }  }}

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

довідка щодо catalog

catalog надає необов’язкові підказки щодо відображення для браузерів плагінів. Хости можуть ігнорувати ці підказки. Вони ніколи не встановлюють і не вмикають плагін, а також не змінюють його поведінку під час виконання чи рівень довіри.

{  "catalog": {    "featured": true,    "order": 10  }}

довідка щодо метаданих постачальника генерування

Поля метаданих постачальника генерування описують статичні сигнали автентифікації для постачальників, оголошених у відповідному списку 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 також приймають optional (позначає інструмент як необов’язковий для активації плагіна) і replaySafe (позначає виконання інструмента як безпечне для повторення після незавершеного ходу моделі), на додачу до спільних полів configSignals/authSignals, описаних вище.

Якщо інструмент не має toolMetadata, OpenClaw зберігає наявну поведінку та завантажує плагін-власник, коли контракт інструмента відповідає політиці. Для інструментів на гарячому шляху, фабрика яких залежить від автентифікації або конфігурації, авторам плагінів слід оголошувати toolMetadata, а не змушувати ядро імпортувати середовище виконання для перевірки.

довідка щодо providerAuthChoices

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

Довідка щодо commandAliases

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

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

Довідка щодо activation

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

Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку середовища виконання, не замінює register(...) і не гарантує, що код плагіна вже було виконано. Планувальник активації використовує ці поля, щоб звузити перелік плагінів-кандидатів, перш ніж повернутися до наявних метаданих власності маніфесту, як-от providers, channels, commandAliases, setup.providers, contracts.tools і хуки.

Віддавайте перевагу найвужчим метаданим, які вже описують власність. Використовуйте providers, channels, commandAliases, дескриптори налаштування або contracts, коли ці поля виражають відповідний зв’язок. Використовуйте activation для додаткових підказок планувальнику, які неможливо представити цими полями власності. Використовуйте cliBackends верхнього рівня для псевдонімів середовища виконання CLI, як-от claude-cli, my-cli або google-gemini-cli; activation.onAgentHarnesses призначено лише для ідентифікаторів вбудованих оболонок агентів, для яких ще немає поля власності.

Кожен плагін має навмисно задавати activation.onStartup. Установлюйте значення true, лише коли плагін має виконуватися під час запуску Gateway. Установлюйте значення false, коли плагін неактивний під час запуску й має завантажуватися лише за вужчими тригерами. Якщо onStartup не вказано, це більше не спричиняє неявного завантаження плагіна під час запуску; використовуйте явні метадані активації для запуску, каналу, конфігурації, оболонки агента, пам’яті або інших вужчих тригерів активації.

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

Поточні активні споживачі:

• Планування запуску Gateway використовує activation.onStartup для явного імпорту під час запуску.
• Планування CLI, ініційоване командою, повертається до застарілих commandAliases[].cliCommand або commandAliases[].name.
• Планування запуску середовища виконання агента використовує activation.onAgentHarnesses для вбудованих оболонок і cliBackends[] верхнього рівня для псевдонімів середовища виконання CLI.
• Планування налаштування або каналу, ініційоване каналом, повертається до застарілої власності channels[], якщо явні метадані активації каналу відсутні.
• Планування плагінів під час запуску використовує activation.onConfigPaths для неканальних кореневих розділів конфігурації, як-от блок browser вбудованого браузерного плагіна.
• Планування налаштування або середовища виконання, ініційоване постачальником, повертається до застарілої власності providers[] і cliBackends[] верхнього рівня, якщо явні метадані активації постачальника відсутні.

Діагностика планувальника може розрізняти явні підказки активації та резервне використання власності маніфесту. Наприклад, activation-command-hint означає, що збіглося activation.onCommands, а manifest-command-alias означає, що натомість планувальник використав власність commandAliases. Ці мітки причин призначені для діагностики хоста й тестів; автори плагінів мають і надалі оголошувати метадані, які найкраще описують власність.

Довідка щодо qaRunners

Використовуйте qaRunners, коли плагін надає один або кілька транспортних засобів запуску під спільною кореневою командою openclaw qa. Зберігайте ці метадані простими й статичними; середовище виконання плагіна й надалі відповідає за фактичну реєстрацію CLI через легку поверхню runtime-api.ts, яка експортує відповідні qaRunnerCliRegistrations. Необов’язкова adapterFactory надає транспорт спільним сценаріям контролю якості, не змінюючи засіб запуску зареєстрованої команди.

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

Ідентифікатор adapterFactory має збігатися з commandName. Не експортуйте реєстрації для команд, відсутніх у маніфесті.

Довідник 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, а налаштуванню все ще потрібні розширені перехоплювачі середовища виконання під час налаштування, установіть requiresRuntime: true і залиште setup-api як резервний шлях виконання.

OpenClaw також включає setup.providers[].envVars у загальні пошуки автентифікації постачальника та змінних середовища. providerAuthEnvVars залишається підтримуваним через адаптер сумісності протягом періоду відмови, але не вбудовані Plugin, які досі його використовують, отримують діагностичне повідомлення маніфесту. Нові Plugin мають розміщувати метадані середовища для налаштування та стану в setup.providers[].envVars.

Використовуйте providerUsageAuthEnvVars, коли облікові дані рівня білінгу або організації мають активувати resolveUsageAuth, не стаючи обліковими даними для виведення. Ці назви додаються до блокування dotenv робочого простору, видалення зі дочірніх процесів ACP, фільтрації секретів у пісочниці та широкого очищення секретів. Середовище виконання постачальника все одно читає та класифікує значення всередині resolveUsageAuth.

OpenClaw також може визначати прості варіанти налаштування з setup.providers[].authMethods, коли точка входу налаштування недоступна або коли setup.requiresRuntime: false оголошує середовище виконання налаштування непотрібним. Явні записи providerAuthChoices залишаються пріоритетними для власних міток, прапорців CLI, області початкового налаштування та метаданих асистента.

Установлюйте requiresRuntime: false лише тоді, коли цих дескрипторів достатньо для поверхні налаштування. OpenClaw трактує явне значення false як контракт лише на основі дескрипторів і не виконуватиме setup-api або openclaw.setupEntry для пошуку налаштувань. Якщо Plugin лише з дескрипторами все одно постачає один із цих записів середовища виконання налаштування, OpenClaw повідомляє додаткове діагностичне повідомлення та продовжує його ігнорувати. Відсутність requiresRuntime зберігає застарілу резервну поведінку, щоб не порушувати роботу наявних Plugin, які додали дескриптори без цього прапорця.

Оскільки пошук налаштувань може виконувати код setup-api, яким володіє Plugin, нормалізовані значення setup.providers[].id і setup.cliBackends[] мають бути унікальними серед виявлених Plugin. За неоднозначного володіння операція безпечно завершується помилкою замість вибору переможця за порядком виявлення.

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

Довідник setup.providers

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

Підтримувані записи підтвердження:

Поля setup

Довідник uiHints

uiHints — це відображення назв полів конфігурації на невеликі підказки щодо відтворення. Ключі можуть використовувати крапки для вкладених полів конфігурації, але жоден сегмент шляху не може бути __proto__, constructor або prototype; налаштування відхиляє такі назви.

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

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

Довідник contracts

Використовуйте contracts лише для статичних метаданих володіння можливостями, які OpenClaw може прочитати без імпорту середовища виконання 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"],    "musicGenerationProviders": ["stability-audio"],    "documentExtractors": ["example-docs"],    "webContentExtractors": ["firecrawl"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "workerProviders": ["example-worker"],    "usageProviders": ["acme-ai"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

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

contracts.embeddedExtensionFactories збережено для вбудованих фабрик розширень, призначених лише для сервера застосунків Codex. Натомість вбудовані перетворення результатів інструментів мають оголошувати contracts.agentToolResultMiddleware і реєструватися за допомогою api.registerAgentToolResultMiddleware(...). Встановлені плагіни можуть використовувати той самий механізм проміжного ПЗ лише за явного ввімкнення та лише для середовищ виконання, оголошених ними в contracts.agentToolResultMiddleware.

Встановлені плагіни, яким потрібен довірений хостом рівень політик перед виконанням інструментів, мають оголосити кожен зареєстрований локальний ідентифікатор у contracts.trustedToolPolicies і бути явно ввімкненими. Вбудовані плагіни зберігають наявний шлях довірених політик, але встановлені плагіни з неоголошеними ідентифікаторами політик відхиляються до реєстрації. Ідентифікатори політик обмежені областю Plugin, який їх реєструє, тому два плагіни можуть оголосити й зареєструвати workflow-budget; один Plugin не може двічі зареєструвати той самий локальний ідентифікатор.

Реєстрації api.registerTool(...) під час виконання мають відповідати contracts.tools. Виявлення інструментів використовує цей список, щоб завантажувати лише середовища виконання плагінів, які можуть володіти запитуваними інструментами.

Плагіни постачальників, які реалізують resolveExternalAuthProfiles, мають оголошувати contracts.externalAuthProviders; неоголошені обробники зовнішньої автентифікації ігноруються.

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

Постачальники загальних векторних представлень мають оголошувати contracts.embeddingProviders для кожного адаптера, зареєстрованого за допомогою api.registerEmbeddingProvider(...). Використовуйте загальний контракт для повторно використовуваного створення векторів, зокрема для постачальників, яких використовує пошук у пам’яті. contracts.memoryEmbeddingProviders — це застарілий механізм сумісності, специфічний для векторних представлень пам’яті; він зберігається лише на час переходу наявних постачальників до загального механізму постачальників векторних представлень.

Постачальники виконавців мають оголошувати в contracts.workerProviders кожен ідентифікатор api.registerWorkerProvider(...). Ядро зберігає довготривалий намір перед викликом provision; постачальники перевіряють свої налаштування до зовнішнього виділення ресурсів, а повторні виклики з тим самим ідентифікатором операції мають приймати ту саму оренду. Ядро також зберігає знімок перевірених налаштувань і передає його разом із leaseId до inspect({ leaseId, profile }) та destroy({ leaseId, profile }), зокрема після зміни або видалення іменованого профілю. Знищення є ідемпотентним, перевірка повертає закрите об’єднання станів active / destroyed / unknown, а матеріали приватного ключа SSH зазначаються лише через SecretRef. Підготовлені кінцеві точки SSH також мають містити відкритий hostKey із довіреного результату підготовки ресурсів у точному форматі algorithm base64, без імені хоста чи коментаря, щоб ядро могло закріпити ключ хоста перед підключенням. Постачальники, які створюють динамічні посилання на ідентичності, можуть реалізувати авторитетний метод resolveSshIdentity({ leaseId, profile, keyRef }); для постачальників без нього використовується універсальний механізм ядра для розв’язання секретів. Авторитетний стан unknown робить активний локальний запис осиротілим; після збереженого запиту на знищення він підтверджує демонтаж.

contracts.gatewayMethodDispatch наразі приймає "authenticated-request". Це запобіжник чистоти API для нативних HTTP-маршрутів Plugin, які навмисно диспетчеризують методи площини керування Gateway у межах процесу, а не ізольоване середовище для захисту від шкідливих нативних плагінів. Використовуйте його лише для ретельно перевірених вбудованих або операторських поверхонь, які вже потребують HTTP-автентифікації Gateway. Маршрут із таким правом залишається доступним, коли допуск кореневих робіт Gateway закрито, лише якщо він також оголошує auth: "gateway" і специфічне для маршруту gatewayRuntimeScopeSurface: "trusted-operator"; звичайні споріднені маршрути того самого Plugin залишаються за межею допуску. Це дає змогу зберегти доступ до стану призупинення та відновлення, не надаючи всьому Plugin обхід допуску. Обмежуйте синтаксичний аналіз і формування відповіді поза диспетчеризацією; змістовна робота або робота зі зміною стану має виконуватися через диспетчеризацію методів Gateway, яка відповідає за допуск і застосування обмежень області.

Довідка configContracts

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

{  "configContracts": {    "compatibilityMigrationPaths": ["legacyProvider"],    "compatibilityRuntimePaths": ["legacyProvider.webhook"],    "dangerousFlags": [      {        "path": "accounts.*.allowUnverifiedSenders",        "equals": true      }    ],    "secretInputs": {      "bundledDefaultEnabled": false,      "paths": [        {          "path": "apiKey",          "expected": "string"        }      ]    }  }}

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

secretInputs підтримує:

Довідка щодо mediaUnderstandingProviderMetadata

Використовуйте mediaUnderstandingProviderMetadata, коли постачальник розуміння медіа має стандартні моделі, пріоритет автоматичного резервного вибору автентифікації або вбудовану підтримку документів, потрібну універсальним допоміжним засобам ядра до завантаження середовища виконання. Ключі також мають бути оголошені в contracts.mediaUnderstandingProviders.

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

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

Довідка щодо channelConfigs

Використовуйте channelConfigs, коли плагіну каналу потрібні легкі метадані конфігурації до завантаження середовища виконання. Виявлення налаштувань і стану каналу лише для читання може безпосередньо використовувати ці метадані для налаштованих зовнішніх каналів, коли запис налаштування недоступний або коли setup.requiresRuntime: false указує, що середовище виконання для налаштування не потрібне.

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

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

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

Невбудовані плагіни, які оголошують channels[], також мають оголошувати відповідні записи channelConfigs. Без них OpenClaw усе одно може завантажити плагін, але поверхні схеми конфігурації холодного шляху, налаштування та інтерфейсу керування не знатимуть форми параметрів, що належать каналу, доки не виконається середовище виконання плагіна.

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

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

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

Заміна іншого плагіна каналу

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

{  "id": "acme-chat",  "channels": ["chat"],  "channelConfigs": {    "chat": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "webhookUrl": { "type": "string" }        }      },      "preferOver": ["chat"]    }  }}

Коли channels.chat налаштовано, OpenClaw враховує як ідентифікатор каналу, так і бажаний ідентифікатор плагіна. Якщо плагін із нижчим пріоритетом було вибрано лише тому, що він вбудований або стандартно ввімкнений, OpenClaw вимикає його в ефективній конфігурації середовища виконання, щоб каналом і його інструментами володів один плагін. Явний вибір користувача все одно має перевагу: якщо користувач явно вмикає обидва плагіни (через plugins.allow або змістовну конфігурацію plugins.entries), OpenClaw зберігає цей вибір і повідомляє діагностичні дані про дублікати каналів та інструментів замість непомітної зміни запитаного набору плагінів.

Обмежуйте preferOver ідентифікаторами плагінів, які справді можуть надавати той самий канал. Це не універсальне поле пріоритету, і воно не перейменовує ключі користувацької конфігурації.

Довідка щодо modelSupport

Використовуйте modelSupport, коли OpenClaw має визначати ваш плагін постачальника за скороченими ідентифікаторами моделей, як-от gpt-5.6-sol або claude-sonnet-4.6, до завантаження середовища виконання плагіна.

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

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

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

Поля:

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

Довідка щодо modelCatalog

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

{  "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/базової URL-адреси псевдоніма без завантаження середовища виконання провайдера. Псевдоніми не розширюють невідфільтровані списки каталогу; широкі списки містять лише рядки канонічного провайдера-власника.

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

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

Поля моделі:

Поля приховування:

Не додавайте до modelCatalog дані, доступні лише під час виконання. Використовуйте static, лише коли рядки маніфесту достатньо повні, щоб списки, відфільтровані за провайдером, і засоби вибору могли пропустити виявлення реєстру/середовища виконання. Використовуйте 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 для класифікації кінцевих точок, яку загальна політика запитів має знати до завантаження середовища виконання провайдера. Ядро й надалі визначає значення кожного endpointClass; маніфести Plugin володіють метаданими хостів і базових URL-адрес.

Офіційно винесені назовні Plugin провайдерів виключені з основного дистрибутива, тому їхні маніфести невидимі до встановлення. Їхні providerEndpoints також потрібно дублювати в scripts/lib/official-external-provider-catalog.json, щоб класифікація кінцевих точок продовжувала працювати без Plugin; дотримання відповідності копії забезпечує контрактний тест.

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

Довідник providerRequest

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

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

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

Довідник secretProviderIntegrations

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

{  "secretProviderIntegrations": {    "secret-store": {      "providerAlias": "team-secrets",      "displayName": "Team secrets",      "source": "exec",      "command": "${node}",      "args": ["./bin/resolve-secrets.mjs"]    }  }}

Ключ мапи є ідентифікатором інтеграції. Якщо providerAlias пропущено, OpenClaw використовує ідентифікатор інтеграції як псевдонім провайдера SecretRef. Псевдоніми провайдерів мають відповідати звичайному шаблону псевдонімів провайдера SecretRef, наприклад team-secrets або onepassword-work.

Коли оператор вибирає попередньо налаштовану конфігурацію, OpenClaw записує посилання на провайдера такого вигляду:

{  "secrets": {    "providers": {      "team-secrets": {        "source": "exec",        "pluginIntegration": {          "pluginId": "acme-secrets",          "integrationId": "secret-store"        }      }    }  }}

Під час запуску або перезавантаження OpenClaw визначає цього провайдера, завантажуючи поточні метадані маніфесту Plugin, перевіряючи, що Plugin-власник встановлено й активовано, і формуючи команду exec із маніфесту. Вимкнення або видалення Plugin відкликає провайдера для активних SecretRef. Оператори, яким потрібна автономна конфігурація 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, noOutputTimeoutMs, maxOutputBytes, jsonOnly, env, passEnv і allowInsecurePath, передаються до звичайної конфігурації exec-провайдера SecretRef.

Довідник modelPricing

Використовуйте modelPricing, коли провайдеру потрібно керувати ціноутворенням на рівні площини керування до завантаження середовища виконання. Кеш ціноутворення Gateway читає ці метадані без імпорту коду середовища виконання провайдера.

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

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

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

Індекс провайдерів OpenClaw

Індекс провайдерів OpenClaw — це попередні метадані провайдерів, якими керує OpenClaw і чиї Plugin можуть бути ще не встановлені. Він не є частиною маніфесту Plugin. Маніфести Plugin залишаються авторитетним джерелом для встановлених Plugin. Індекс провайдерів — це внутрішній резервний контракт, який майбутні інтерфейси встановлюваних провайдерів і вибору моделей до встановлення використовуватимуть, коли Plugin провайдера не встановлено.

Порядок пріоритетності джерел каталогу:

1. Конфігурація користувача.
2. modelCatalog маніфесту встановленого Plugin.
3. Кеш каталогу моделей після явного оновлення.
4. Рядки попереднього перегляду Індексу провайдерів OpenClaw.

Індекс провайдерів не повинен містити секрети, стан увімкнення, хуки середовища виконання або актуальні дані моделей, специфічні для облікового запису. Його каталоги попереднього перегляду використовують ту саму структуру рядка провайдера modelCatalog, що й маніфести Plugin, але мають обмежуватися стабільними метаданими відображення, якщо тільки поля адаптера середовища виконання, як-от api, baseUrl, ціни або прапорці сумісності, навмисно не синхронізуються з маніфестом установленого Plugin. Провайдери з динамічним виявленням через /models мають записувати оновлені рядки через явний шлях кешу каталогу моделей, а не звертатися до API провайдера під час звичайного формування списку або початкового налаштування.

Записи Індексу провайдерів також можуть містити метадані встановлюваного Plugin для провайдерів, чий Plugin було винесено з ядра або ще не встановлено з іншої причини. Ці метадані повторюють шаблон каталогу каналів: назви пакета, специфікації встановлення npm, очікуваної цілісності та коротких позначок варіантів автентифікації достатньо, щоб показати варіант налаштування зі встановленням. Після встановлення Plugin пріоритет отримує його маніфест, а запис Індексу провайдерів для цього провайдера ігнорується.

openclaw doctor --fix переносить невеликий закритий набір застарілих ключів можливостей верхнього рівня маніфесту до contracts.*: speechProviders, mediaUnderstandingProviders, imageGenerationProviders і tools. Жоден із них — як і будь-який інший список можливостей — більше не читається як поле верхнього рівня маніфесту; звичайне завантаження маніфесту розпізнає їх лише в contracts.

Маніфест порівняно з package.json

Ці два файли виконують різні завдання:

Якщо ви не впевнені, де мають міститися певні метадані, скористайтеся таким правилом:

• якщо OpenClaw має знати їх до завантаження коду Plugin, розмістіть їх у openclaw.plugin.json
• якщо вони стосуються пакування, файлів точок входу або поведінки встановлення npm, розмістіть їх у package.json

Поля package.json, що впливають на виявлення

Деякі метадані Plugin, потрібні до запуску середовища виконання, навмисно містяться в блоці openclaw файла package.json, а не в openclaw.plugin.json. openclaw.bundle і openclaw.bundle.json не є контрактами Plugin OpenClaw; нативні Plugin мають використовувати openclaw.plugin.json разом із підтримуваними полями package.json#openclaw, наведеними нижче.

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

Метадані маніфесту визначають, які варіанти провайдера/каналу/налаштування відображаються під час початкового налаштування до завантаження середовища виконання. package.json#openclaw.install повідомляє процесу початкового налаштування, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих варіантів. Не переносьте підказки щодо встановлення до openclaw.plugin.json.

openclaw.install.minHostVersion перевіряється під час встановлення та завантаження реєстру маніфестів для невбудованих джерел Plugin. Недійсні значення відхиляються; новіші, але дійсні значення призводять до пропуску зовнішніх Plugin на старіших хостах. Вважається, що версії вбудованих Plugin із вихідного коду узгоджені з версією робочої копії хоста.

openclaw.install.requiredPlatformPackages призначено для пакетів npm, які надають потрібні нативні виконувані файли через необов’язкові платформні псевдоніми. Укажіть базову назву пакета npm для кожного підтримуваного платформного псевдоніма. Під час встановлення через npm OpenClaw перевіряє лише оголошений псевдонім, обмеження якого у файлі блокування відповідають поточному хосту. Якщо npm повідомляє про успіх, але не додає цей псевдонім, OpenClaw повторює спробу один раз із новим кешем і відкочує встановлення, якщо псевдонім усе ще відсутній.

openclaw.compat.pluginApi перевіряється під час встановлення пакета для невбудованих джерел Plugin. Використовуйте його для нижньої межі API SDK/середовища виконання Plugin OpenClaw, для якої зібрано пакет. Вона може бути суворішою за minHostVersion, коли пакет Plugin потребує новішого API, але зберігає нижчу підказку щодо встановлення для інших процесів. Офіційна синхронізація випусків OpenClaw типово підвищує наявні нижні межі API офіційних Plugin до версії випуску OpenClaw, але випуски лише Plugin можуть зберігати нижчу межу, коли пакет навмисно підтримує старіші хости. Не використовуйте лише версію пакета як контракт сумісності. peerDependencies.openclaw залишається метаданими пакета npm; OpenClaw використовує контракт openclaw.compat.pluginApi для рішень щодо сумісності встановлення.

Офіційні метадані встановлення на вимогу мають використовувати clawhubSpec, коли Plugin опубліковано на ClawHub; початкове налаштування вважає його бажаним віддаленим джерелом і записує відомості про артефакт ClawHub після встановлення. npmSpec залишається резервним варіантом сумісності для пакетів, які ще не переміщено до ClawHub.

Точна фіксація версії npm уже міститься в npmSpec, наприклад "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Офіційні записи зовнішнього каталогу мають поєднувати точні специфікації з expectedIntegrity, щоб процеси оновлення завершувалися помилкою, якщо отриманий артефакт npm більше не відповідає зафіксованому випуску. Інтерактивне початкове налаштування заради сумісності й надалі пропонує довірені специфікації npm із реєстру, зокрема базові назви пакетів і теги дистрибутивів. Діагностика каталогу може розрізняти точні, плаваючі, зафіксовані за цілісністю, без цілісності, з невідповідною назвою пакета та з недійсним типовим вибором джерела. Вона також попереджає, коли expectedIntegrity наявний, але немає дійсного джерела npm, до якого його можна прив’язати. Коли expectedIntegrity наявний, процеси встановлення/оновлення забезпечують його дотримання; коли його пропущено, результат визначення версії з реєстру записується без фіксації цілісності.

Plugin каналів мають надавати openclaw.setupEntry, коли перевірки стану, списку каналів або SecretRef мають ідентифікувати налаштовані облікові записи без завантаження повного середовища виконання. Точка входу налаштування має надавати метадані каналу, а також безпечні для налаштування адаптери конфігурації, стану й секретів; мережеві клієнти, слухачі Gateway і транспортні середовища виконання залишайте в основній точці входу розширення.

Поля точок входу середовища виконання не скасовують перевірки меж пакета для полів точок входу вихідного коду. Наприклад, openclaw.runtimeExtensions не може зробити доступним для завантаження шлях openclaw.extensions, що виходить за межі пакета.

openclaw.install.allowInvalidConfigRecovery навмисно має вузьку сферу дії. Він не робить довільні пошкоджені конфігурації придатними для встановлення. Наразі він лише дає процесам встановлення змогу відновлюватися після певних застарілих помилок оновлення вбудованого Plugin, як-от відсутній шлях до вбудованого Plugin або застарілий запис channels.<id> для того самого вбудованого Plugin. Непов’язані помилки конфігурації й надалі блокують встановлення та спрямовують операторів до openclaw doctor --fix.

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

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

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

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

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

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

Пріоритет виявлення (повторювані ідентифікатори Plugin)

OpenClaw виявляє Plugin у трьох кореневих каталогах, перевіряючи їх у такому порядку: вбудовані Plugin, що постачаються з OpenClaw, глобальний корінь встановлення (~/.openclaw/extensions) і корінь поточного робочого простору (<workspace>/.openclaw/extensions), а також усі явні записи plugins.load.paths.

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

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

Наслідки:

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

Вимоги JSON Schema

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

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

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

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

• Невідомі ключі channels.* є помилками, якщо ідентифікатор каналу не оголошено в маніфесті плагіна. Якщо той самий ідентифікатор також наявний у plugins.allow, plugins.entries або plugins.installs (плагін, на який є посилання, але який наразі неможливо виявити), OpenClaw натомість знижує рівень цієї проблеми до попередження.
• Посилання на невідомі ідентифікатори плагінів у plugins.entries.<id>, plugins.allow і plugins.deny є попередженнями («застарілий запис конфігурації проігноровано»), а не помилками, тому оновлення та видалені або перейменовані плагіни не блокують запуск Gateway.
• Посилання на невідомий ідентифікатор плагіна в plugins.slots.memory є помилкою, крім відомого офіційного зовнішнього плагіна memory-lancedb, для якого натомість виводиться попередження.
• Якщо плагін установлено, але його маніфест або схема пошкоджені чи відсутні, перевірка завершується невдало, а Doctor повідомляє про помилку плагіна.
• Якщо конфігурація плагіна існує, але плагін вимкнено, конфігурація зберігається, а в Doctor і журналах відображається попередження.

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

Примітки

• Маніфест обов’язковий для нативних плагінів OpenClaw, зокрема для завантаження з локальної файлової системи. Середовище виконання все одно завантажує модуль плагіна окремо; маніфест використовується лише для виявлення та перевірки.
• Нативні маніфести аналізуються за допомогою JSON5, тому коментарі, кінцеві коми та ключі без лапок дозволені, якщо кінцеве значення залишається об’єктом.
• Завантажувач маніфестів читає лише документовані поля маніфесту. Уникайте власних ключів верхнього рівня.
• channels, providers, cliBackends і skills можна не вказувати, якщо вони не потрібні плагіну.
• providerCatalogEntry має залишатися легким і не повинен імпортувати значні частини коду середовища виконання; використовуйте його для статичних метаданих каталогу постачальників або вузьких дескрипторів виявлення, а не для виконання під час обробки запитів.
• Взаємовиключні типи плагінів вибираються через plugins.slots.*: kind: "memory" — через plugins.slots.memory (типове значення — memory-core), kind: "context-engine" — через plugins.slots.contextEngine (типове значення — legacy).
• Оголошуйте взаємовиключний тип плагіна в цьому маніфесті. OpenClawPluginDefinition.kind у точці входу середовища виконання застарів і зберігається лише як резервний механізм сумісності зі старими плагінами.
• Метадані змінних середовища (setup.providers[].envVars, застаріле providerAuthEnvVars і channelEnvVars) мають лише декларативний характер. Стан, аудит, перевірка доставлення Cron та інші поверхні лише для читання все одно застосовують політику довіри до плагінів і фактичної активації, перш ніж вважати змінну середовища налаштованою.
• Метадані майстра середовища виконання, для яких потрібен код постачальника, описано в розділі Перехоплювачі середовища виконання постачальника.
• Якщо ваш плагін залежить від нативних модулів, задокументуйте кроки збирання та всі вимоги до списку дозволів менеджера пакетів (наприклад, pnpm allow-build-scripts + pnpm rebuild <package>).

Пов’язані матеріали