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

Коли appGuidedDiscovery має значення true, відповідний метод автентифікації провайдера повинен надавати appGuidedSetup.detect і appGuidedSetup.prepare. Виявлення має виконуватися лише для читання: без входу, отримання моделі, завантаження чи запису конфігурації. Підготовка повторно перевіряє точно вибрану модель і повертає пропозицію конфігурації; OpenClaw виконує оперативне тестування цієї пропозиції ізольовано та фіксує її лише після успішного завершення.

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

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

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

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

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

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

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

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

{  "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[], коли немає явних метаданих активації каналу.
• Планування Plugin під час запуску використовує activation.onConfigPaths для поверхонь кореневої конфігурації, не пов’язаних із каналами, як-от блок browser вбудованого Plugin браузера.
• Планування налаштування або середовища виконання, ініційоване постачальником, повертається до застарілого володіння providers[] і cliBackends[] верхнього рівня, коли немає явних метаданих активації постачальника.

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

Довідник qaRunners

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

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Запустити підтримуваний Docker інтерактивний маршрут контролю якості Matrix із тимчасовим домашнім сервером"    }  ]}

Ідентифікатор 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"          }        ]      }    ],    "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",      "help": "Використовується для запитів OpenRouter",      "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 і бути явно ввімкненими. Вбудовані плагіни зберігають наявний шлях довірених політик, але встановлені плагіни з неоголошеними ідентифікаторами політик відхиляються до реєстрації. Ідентифікатори політик обмежені областю плагіна, який їх реєструє, тому два плагіни можуть оголосити й зареєструвати workflow-budget; один плагін не може двічі зареєструвати той самий локальний ідентифікатор.

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

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

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

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

Провайдери виконавців мають оголошувати кожен ідентифікатор api.registerWorkerProvider(...) у contracts.workerProviders. Ядро зберігає довготривалий намір до виклику 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-маршрутів плагінів, які навмисно диспетчеризують методи площини керування Gateway у межах процесу, а не пісочниця проти зловмисних нативних плагінів. Використовуйте його лише для ретельно перевірених вбудованих або операторських поверхонь, які вже потребують HTTP-автентифікації Gateway. Маршрут із таким правом залишається доступним, коли допуск кореневих завдань Gateway закритий, лише якщо він також оголошує auth: "gateway" і специфічний для маршруту gatewayRuntimeScopeSurface: "trusted-operator"; звичайні сусідні маршрути того самого плагіна залишаються за межею допуску. Завдяки цьому стан призупинення та відновлення залишаються доступними без надання всьому плагіну права обходити допуск. Обмежуйте синтаксичний аналіз і формування відповіді поза диспетчеризацією; істотна робота або робота зі зміною стану має виконуватися через диспетчеризацію методів Gateway, яка відповідає за допуск і дотримання областей доступу.

Довідник configContracts

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

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

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

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

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": "URL домашнього сервера",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Підключення до домашнього сервера Matrix",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

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

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

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

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

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

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

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

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

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

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

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

Поля:

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

Довідка щодо 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": "недоступно в Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

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

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

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

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

Поля моделі:

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

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

Довідка modelIdNormalization

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

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

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

Довідка providerEndpoints

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

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

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

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

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

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

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

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

Використовуйте secretProviderIntegrations, коли плагін може опублікувати багаторазово використовуваний попередньо налаштований exec-постачальник SecretRef. OpenClaw зчитує ці метадані до завантаження середовища виконання плагіна, зберігає належність плагіну в secrets.providers.<alias>.pluginIntegration і залишає фактичне отримання секретів середовищу виконання SecretRef. Попередні налаштування доступні лише для вбудованих плагінів і встановлених плагінів, виявлених у керованих кореневих каталогах установлення плагінів, як-от установлення з 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 визначає цього постачальника, завантажуючи поточні метадані маніфесту плагіна, перевіряючи, що плагін-власник встановлений і активний, та формуючи exec-команду з маніфесту. Вимкнення або видалення плагіна відкликає постачальника для активних SecretRef. Оператори, яким потрібна автономна конфігурація exec, як і раніше можуть безпосередньо записувати постачальників command/args вручну.

Наразі підтримуються лише попередні налаштування source: "exec". command має бути ${node}, а args[0] — сценарієм визначення ./ із шляхом відносно кореневого каталогу плагіна. Під час запуску або перезавантаження OpenClaw перетворює їх на поточний виконуваний файл Node та абсолютний шлях до сценарію всередині плагіна. Параметри Node, як-от --require, --import, --loader, --env-file, --eval і --print, не є частиною контракту попереднього налаштування маніфесту. Оператори, яким потрібні команди не на основі Node, можуть безпосередньо налаштувати автономні exec-постачальники вручну.

OpenClaw визначає trustedDirs для попередніх налаштувань маніфесту з кореневого каталогу плагіна, а для попередніх налаштувань ${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 попередні метадані для постачальників, плагіни яких, можливо, ще не встановлено. Він не є частиною маніфесту плагіна. Маніфести плагінів залишаються авторитетним джерелом для встановлених плагінів. Індекс постачальників — це внутрішній резервний контракт, який використовуватимуть майбутні інтерфейси встановлюваних постачальників і засобу вибору моделей перед установленням, коли плагін постачальника не встановлено.

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

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

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

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

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

Маніфест і package.json

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

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

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

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

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

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

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

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

openclaw.install.requiredPlatformPackages призначено для пакетів npm, які надають необхідні нативні двійкові файли через необов’язкові платформні псевдоніми. Укажіть базове ім’я пакета npm для кожного підтримуваного платформного псевдоніма. Під час встановлення через npm OpenClaw перевіряє лише оголошений псевдонім, обмеження якого у файлі блокування відповідають поточному хосту. Якщо 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-теги. Діагностика каталогу може розрізняти точні, плаваючі, зафіксовані за цілісністю, без цілісності, з невідповідністю імені пакета та недійсні джерела вибору за замовчуванням. Вона також попереджає, коли наявний 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, стану або перевірки наявності в режимі лише для читання потрібна швидка перевірка автентифікації з відповіддю «так/ні» до завантаження повного плагіна каналу. Збережений стан автентифікації не є налаштованим станом каналу: не використовуйте ці метадані для автоматичного ввімкнення плагінів, виправлення залежностей середовища виконання або визначення того, чи має завантажуватися середовище виконання каналу. Цільовий експорт має бути невеликою функцією, яка читає лише збережений стан; не спрямовуйте його через повний модуль експорту середовища виконання каналу.

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

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "env": {          "allOf": ["TELEGRAM_BOT_TOKEN"]        }      }    }  }}

Використовуйте env.allOf, коли потрібна кожна перелічена змінна, і env.anyOf, коли достатньо будь-якої однієї непорожньої змінної. Якщо невелика перевірка без середовища виконання потребує більше, ніж метадані середовища, використовуйте specifier разом із exportName, як показано для persistedAuthState; коли наявний env, OpenClaw використовує його без завантаження цього модуля. Якщо перевірка потребує повного визначення конфігурації або справжнього середовища виконання каналу, залиште цю логіку в хуку config.hasConfiguredState плагіна.

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

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

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

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

Наслідки:

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

Вимоги JSON Schema

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

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

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

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

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

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