openclaw.plugin.json. Відомості про сумісні структури пакетів (Codex, Claude, Cursor) див. у розділі Пакети плагінів.
Сумісні формати пакетів натомість використовують власні файли маніфестів:
- Пакет Codex:
.codex-plugin/plugin.json - Пакет Claude:
.claude-plugin/plugin.jsonабо типова структура компонентів Claude без маніфесту - Пакет Cursor:
.cursor-plugin/plugin.json
openclaw.plugin.json. Для сумісного пакета OpenClaw зчитує метадані пакета, оголошені кореневі каталоги навичок, кореневі каталоги команд Claude, типові значення Claude settings.json, типові значення LSP Claude і підтримувані набори хуків, якщо структура відповідає вимогам середовища виконання OpenClaw.
Кожен нативний плагін OpenClaw повинен містити openclaw.plugin.json у кореневому каталозі плагіна. OpenClaw зчитує його для перевірки конфігурації без виконання коду плагіна. Відсутній або недійсний маніфест блокує перевірку конфігурації та вважається помилкою плагіна.
Повний посібник із системи плагінів див. у розділі Плагіни, а опис нативної моделі можливостей і поточні рекомендації щодо зовнішньої сумісності — у розділі Модель можливостей.
Призначення цього файлу
openclaw.plugin.json — це метадані, які OpenClaw зчитує до завантаження коду вашого плагіна. Усе в ньому має бути достатньо легким для перевірки без запуску середовища виконання плагіна.
Використовуйте його для:
- ідентифікації плагіна, перевірки конфігурації та підказок інтерфейсу конфігурації
- метаданих автентифікації, початкового налаштування та конфігурування (псевдонім, автоматичне ввімкнення, змінні середовища постачальника, варіанти автентифікації)
- підказок щодо активації для поверхонь площини керування
- скороченого визначення належності сімейств моделей
- статичних знімків належності можливостей (
contracts) - метаданих засобу запуску QA, доступних для перевірки спільному хосту
openclaw qa - метаданих конфігурації для окремих каналів, об’єднаних із каталогом і поверхнями перевірки
package.json.
Мінімальний приклад
Розширений приклад
Довідник полів верхнього рівня
Довідник каталогу
catalog надає необов’язкові підказки щодо відображення для засобів перегляду плагінів. Хости можуть ігнорувати ці підказки. Вони ніколи не встановлюють і не вмикають плагін, а також не змінюють його поведінку під час виконання чи рівень довіри.
Довідник метаданих постачальника генерування
Поля метаданих постачальника генерування описують статичні сигнали автентифікації для постачальників, оголошених у відповідному спискуcontracts.*GenerationProviders. OpenClaw зчитує ці поля до завантаження середовища виконання постачальника, щоб основні інструменти могли визначити доступність постачальника генерування без імпорту кожного плагіна постачальника.
Використовуйте ці поля лише для простих декларативних фактів, перевірка яких не потребує значних ресурсів. Транспорт, перетворення запитів, оновлення токенів, перевірка облікових даних і фактична поведінка генерування залишаються в середовищі виконання плагіна.
Кожен запис
configSignals підтримує:
Кожна перевірка
mode підтримує:
Кожен запис
authSignals підтримує:
Кожна перевірка
providerBaseUrl підтримує:
Довідник метаданих інструментів
toolMetadata використовує ті самі форми configSignals та authSignals, що й метадані постачальника генерування, із ключами за назвою інструмента. contracts.tools оголошує належність. toolMetadata оголошує просте свідчення доступності, щоб OpenClaw міг не імпортувати середовище виконання плагіна лише для того, щоб його фабрика інструментів повернула null.
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.
Довідка щодо 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 під час запуску; використовуйте явні метадані активації для запуску, каналу, конфігурації, середовища агента, пам’яті чи інших вужчих тригерів активації.
Поточні активні споживачі:
- Планування запуску 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 надає транспорт спільним сценаріям контролю якості, не
змінюючи засіб запуску зареєстрованої команди.
Ідентифікатор
adapterFactory має відповідати commandName. Не експортуйте реєстрації
для команд, яких немає в маніфесті.
Довідник setup
Використовуйтеsetup, коли поверхням налаштування та початкової конфігурації потрібні легкі метадані, якими володіє Plugin, ще до завантаження середовища виконання.
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; налаштування відхиляє такі назви.
Довідник contracts
Використовуйтеcontracts лише для статичних метаданих володіння можливостями, які OpenClaw може прочитати без імпорту середовища виконання Plugin.
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 і звуження застарілих шляхів конфігурації.
Кожен запис
dangerousFlags підтримує:
secretInputs підтримує:
Довідка щодо mediaUnderstandingProviderMetadata
ВикористовуйтеmediaUnderstandingProviderMetadata, коли постачальник розпізнавання медіа має типові моделі, пріоритет автоматичного резервного вибору автентифікації або вбудовану підтримку документів, які потрібні загальним допоміжним засобам ядра до завантаження середовища виконання. Ключі також мають бути оголошені в contracts.mediaUnderstandingProviders.
Довідка щодо channelConfigs
ВикористовуйтеchannelConfigs, коли плагіну каналу потрібні легкодоступні метадані конфігурації до завантаження середовища виконання. Виявлення налаштування й стану каналу в режимі лише читання може використовувати ці метадані безпосередньо для налаштованих зовнішніх каналів, коли запис налаштування недоступний або коли setup.requiresRuntime: false оголошує, що середовище виконання налаштування не потрібне.
channelConfigs — це метадані маніфесту Plugin, а не новий розділ користувацької конфігурації верхнього рівня. Користувачі й надалі налаштовують екземпляри каналів у channels.<channel-id>. OpenClaw читає метадані маніфесту, щоб визначити, який Plugin володіє налаштованим каналом, до виконання коду середовища виконання Plugin.
Для плагіна каналу configSchema і channelConfigs описують різні шляхи:
configSchemaперевіряєplugins.entries.<plugin-id>.configchannelConfigs.<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 разом з іншими метаданими каталогу каналів, якими володіє їхній пакет.
Заміна іншого плагіна каналу
ВикористовуйтеpreferOver, коли ваш Plugin є бажаним власником ідентифікатора каналу, який також може надавати інший Plugin. Поширені випадки: перейменований ідентифікатор Plugin, окремий Plugin, що замінює вбудований Plugin, або підтримуване відгалуження, яке зберігає той самий ідентифікатор каналу для сумісності конфігурації.
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.
- явні посилання
provider/modelвикористовують метадані маніфесту власникаproviders modelPatternsмають перевагу надmodelPrefixes- якщо відповідність є одночасно в одного невбудованого й одного вбудованого Plugin, перемагає невбудований Plugin
- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже постачальника
Записи
modelPatterns компілюються через compileSafeRegex, який відхиляє шаблони з вкладеним повторенням (наприклад, (a+)+$). Шаблони, які не проходять перевірку безпеки, непомітно пропускаються, так само як синтаксично недійсні регулярні вирази. Використовуйте прості шаблони й уникайте вкладених квантифікаторів.
Довідка щодо modelCatalog
ВикористовуйтеmodelCatalog, коли OpenClaw має знати метадані моделей постачальника до завантаження середовища виконання Plugin. Це джерело під керуванням маніфесту для фіксованих рядків каталогу, псевдонімів постачальників, правил приховування та режиму виявлення. Оновлення під час виконання й надалі належить коду середовища виконання постачальника, але маніфест повідомляє ядру, коли середовище виконання необхідне.
aliases бере участь у пошуку власника провайдера під час планування каталогу моделей. Цілі псевдонімів мають бути верхньорівневими провайдерами, що належать тому самому плагіну. Коли відфільтрований за провайдером список використовує псевдонім, OpenClaw може прочитати маніфест власника та застосувати перевизначення API/базової URL-адреси псевдоніма без завантаження середовища виконання провайдера. Псевдоніми не розширюють невідфільтровані списки каталогу; загальні списки містять лише канонічні рядки провайдера-власника.
suppressions замінює старий хук середовища виконання провайдера suppressBuiltInModel. Записи приховування враховуються лише тоді, коли провайдер належить плагіну або оголошений як ключ modelCatalog.aliases, що вказує на належного плагіну провайдера. Хуки приховування середовища виконання більше не викликаються під час визначення моделі.
Поля провайдера:
Поля моделі:
Поля приховування:
Не розміщуйте в
modelCatalog дані, доступні лише в середовищі виконання. Використовуйте static лише тоді, коли рядки маніфесту достатньо повні, щоб списки, відфільтровані за провайдером, і засоби вибору могли пропустити виявлення реєстру/середовища виконання. Використовуйте refreshable, коли рядки маніфесту є корисними доступними для переліку початковими даними або доповненнями, але оновлення/кеш згодом може додати інші рядки; оновлювані рядки самі по собі не є авторитетними. Використовуйте runtime, коли OpenClaw має завантажити середовище виконання провайдера, щоб отримати список.
Довідка modelIdNormalization
ВикористовуйтеmodelIdNormalization для нескладного очищення ідентифікаторів моделей, що належать провайдеру, яке має відбутися до завантаження середовища виконання провайдера. Завдяки цьому такі псевдоніми, як короткі назви моделей, застарілі локальні ідентифікатори провайдера та правила префіксів проксі, зберігаються в маніфесті плагіна-власника, а не в основних таблицях вибору моделей.
Довідка providerEndpoints
ВикористовуйтеproviderEndpoints для класифікації кінцевих точок, яку загальна політика запитів має знати до завантаження середовища виконання провайдера. Ядро й надалі визначає значення кожного endpointClass; маніфести плагінів визначають метадані хоста й базової URL-адреси.
Офіційно винесені в зовнішні модулі плагіни провайдерів виключені з основного дистрибутива, тому
їхні маніфести невидимі до встановлення. Їхні providerEndpoints також мають
бути віддзеркалені в scripts/lib/official-external-provider-catalog.json, щоб
класифікація кінцевих точок продовжувала працювати без плагіна; контрактний тест
забезпечує відповідність віддзеркалення.
Поля кінцевої точки:
Довідка щодо providerRequest
ВикористовуйтеproviderRequest для недорогих метаданих сумісності запитів, потрібних загальній політиці запитів без завантаження середовища виконання постачальника. Переписування корисного навантаження, специфічне для поведінки, залишайте в перехоплювачах середовища виконання постачальника або спільних допоміжних засобах сімейства постачальників.
Довідка щодо secretProviderIntegrations
ВикористовуйтеsecretProviderIntegrations, коли плагін може опублікувати багаторазово використовуваний попередньо налаштований exec-постачальник SecretRef. OpenClaw зчитує ці метадані до завантаження середовища виконання плагіна, зберігає належність плагіну в secrets.providers.<alias>.pluginIntegration і залишає фактичне отримання секретів середовищу виконання SecretRef. Попередні налаштування доступні лише для вбудованих плагінів і встановлених плагінів, виявлених у керованих кореневих каталогах установлення плагінів, як-от установлення з git і ClawHub.
providerAlias пропущено, OpenClaw використовує ідентифікатор інтеграції як псевдонім постачальника SecretRef. Псевдоніми постачальників мають відповідати звичайному шаблону псевдонімів постачальників SecretRef, наприклад team-secrets або onepassword-work.
Коли оператор вибирає попереднє налаштування, OpenClaw записує посилання на постачальника такого вигляду:
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 зчитує ці метадані без імпорту коду середовища виконання постачальника.
Поля джерела:
Індекс постачальників OpenClaw
Індекс постачальників OpenClaw — це належні OpenClaw попередні метадані для постачальників, плагіни яких, можливо, ще не встановлено. Він не є частиною маніфесту плагіна. Маніфести плагінів залишаються авторитетним джерелом для встановлених плагінів. Індекс постачальників — це внутрішній резервний контракт, який використовуватимуть майбутні інтерфейси встановлюваних постачальників і засобу вибору моделей перед установленням, коли плагін постачальника не встановлено. Порядок пріоритетності каталогів:- Конфігурація користувача.
- Маніфест установленого плагіна
modelCatalog. - Кеш каталогу моделей після явного оновлення.
- Рядки попереднього перегляду Індексу постачальників 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.configuredState підтримує швидкі перевірки налаштованості. Надавайте перевагу декларативним метаданим середовища, коли змінних середовища достатньо:
env.allOf, коли потрібна кожна перелічена змінна, і env.anyOf, коли достатньо будь-якої однієї непорожньої змінної. Якщо невелика перевірка без середовища виконання потребує більше, ніж метадані середовища, використовуйте specifier разом із exportName, як показано для persistedAuthState; коли наявний env, OpenClaw використовує його без завантаження цього модуля. Якщо перевірка потребує повного визначення конфігурації або справжнього середовища виконання каналу, залиште цю логіку в хуку config.hasConfiguredState плагіна.
Пріоритет виявлення (повторювані ідентифікатори плагінів)
OpenClaw виявляє плагіни з трьох кореневих каталогів, які перевіряються в такому порядку: вбудовані плагіни, що постачаються з OpenClaw, глобальний корінь установлення (~/.openclaw/extensions) і корінь поточного робочого простору (<workspace>/.openclaw/extensions), а також усі явні записи plugins.load.paths.
Якщо два виявлені об’єкти мають однаковий id, зберігається лише маніфест із найвищим пріоритетом; дублікати з нижчим пріоритетом відкидаються, а не завантажуються разом із ним. Пріоритет від найвищого до найнижчого:
- Вибраний конфігурацією — шлях, явно зафіксований у
plugins.entries.<id> - Глобальне встановлення, що відповідає відстежуваному запису встановлення — плагін, установлений через
openclaw plugin install/openclaw plugin update, який механізм відстеження встановлень OpenClaw розпізнає для того самого ідентифікатора, навіть якщо цей ідентифікатор також належить вбудованому плагіну - Вбудований — плагіни, що постачаються з OpenClaw
- Робочий простір — плагіни, виявлені відносно поточного робочого простору
- Будь-який інший виявлений кандидат
- Відгалужена або застаріла копія вбудованого плагіна, яка не відстежується й розташована в робочому просторі або глобальному корені, не замінить вбудовану збірку.
- Щоб перевизначити вбудований плагін, або виконайте
openclaw plugin installдля цього ідентифікатора, щоб відстежуване глобальне встановлення мало вищий пріоритет за вбудовану копію, або зафіксуйте конкретний шлях черезplugins.entries.<id>, щоб він переміг завдяки пріоритету вибраного конфігурацією шляху. - Відкидання дублікатів записуються в журнал, щоб Doctor і діагностика запуску могли вказати на відкинуту копію.
- Перевизначення дублікатів, вибрані конфігурацією, у діагностиці описуються як явні перевизначення, але все одно супроводжуються попередженням, щоб застарілі відгалуження й випадкові затінення залишалися видимими.
Вимоги JSON Schema
- Кожен plugin повинен містити JSON Schema, навіть якщо він не приймає конфігурацію.
- Порожня схема є допустимою (наприклад,
{ "type": "object", "additionalProperties": false }). - Схеми перевіряються під час читання/запису конфігурації, а не під час виконання.
- Розширюючи або створюючи форк вбудованого plugin із новими ключами конфігурації, одночасно оновіть
openclaw.plugin.jsonconfigSchemaцього plugin. Схеми вбудованих plugin є строгими, тому додаванняplugins.entries.<id>.config.myNewKeyдо конфігурації користувача без додаванняmyNewKeyдоconfigSchema.propertiesбуде відхилено до завантаження середовища виконання plugin.
Поведінка перевірки
- Невідомі ключі
channels.*є помилками, якщо ідентифікатор каналу не оголошено в маніфесті plugin. Якщо той самий ідентифікатор також є вplugins.allow,plugins.entriesабоplugins.installs(plugin, на який є посилання, але який наразі неможливо виявити), OpenClaw натомість знижує рівень цієї проблеми до попередження. plugins.entries.<id>,plugins.allowтаplugins.deny, які посилаються на невідомі ідентифікатори plugin, є попередженнями («застарілий запис конфігурації проігноровано»), а не помилками, тому оновлення та видалені/перейменовані plugin не блокують запуск Gateway.plugins.slots.memory, що посилається на невідомий ідентифікатор plugin, є помилкою, за винятком відомого офіційного зовнішнього pluginmemory-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>).
Пов’язані матеріали
Створення plugin
Початок роботи з plugin.
Архітектура plugin
Внутрішня архітектура та модель можливостей.
Огляд SDK
Довідник SDK plugin та імпорти підшляхів.