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, система считывает метаданные пакета, объявленные корневые каталоги Skills, корневые каталоги команд Claude, значения Claude settings.json по умолчанию, значения LSP Claude по умолчанию и поддерживаемые наборы хуков.
Каждый нативный плагин 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, когда плагину принадлежит имя команды среды выполнения, которое пользователи могут по ошибке указать в plugins.allow или попытаться выполнить как корневую команду CLI. OpenClaw использует эти метаданные для диагностики, не импортируя код среды выполнения плагина.
Справочник activation
Используйтеactivation, когда плагин может без существенных затрат объявить, при каких событиях плоскости управления его следует включать в план активации и загрузки.
Этот блок представляет собой метаданные планировщика, а не API жизненного цикла. Он не регистрирует поведение среды выполнения, не заменяет register(...) и не гарантирует, что код плагина уже выполнялся. Планировщик активации использует эти поля для сужения списка плагинов-кандидатов, прежде чем прибегнуть к существующим метаданным владения из манифеста, таким как providers, channels, commandAliases, setup.providers, contracts.tools и хуки.
Отдавайте предпочтение наиболее узким метаданным, которые уже описывают владение. Используйте providers, channels, commandAliases, дескрипторы настройки или contracts, когда эти поля выражают соответствующую связь. Используйте activation для дополнительных подсказок планировщику, которые невозможно представить этими полями владения. Используйте cliBackends верхнего уровня для псевдонимов среды выполнения CLI, таких как claude-cli, my-cli или google-gemini-cli; activation.onAgentHarnesses предназначен только для идентификаторов встроенных сред агента, для которых ещё не предусмотрено поле владения.
Каждый плагин должен явно задавать activation.onStartup. Устанавливайте значение true только в том случае, если плагин должен выполняться во время запуска Gateway. Устанавливайте значение false, когда плагин неактивен при запуске и должен загружаться только по более узким триггерам. Отсутствие onStartup больше не приводит к неявной загрузке плагина при запуске; используйте явные метаданные активации для запуска, канала, конфигурации, среды агента, памяти или других более узких триггеров активации.
Текущие активные потребители:
- Планирование запуска Gateway использует
activation.onStartupдля явного импорта при запуске. - Планирование CLI, инициированное командой, использует в качестве резервного варианта устаревшие
commandAliases[].cliCommandилиcommandAliases[].name. - Планирование запуска среды выполнения агента использует
activation.onAgentHarnessesдля встроенных тестовых обвязок и верхнеуровневыйcliBackends[]для псевдонимов среды выполнения CLI. - Планирование настройки или канала, инициированное каналом, использует в качестве резервного варианта устаревшее владение
channels[], когда отсутствуют явные метаданные активации канала. - Планирование плагинов при запуске использует
activation.onConfigPathsдля корневых поверхностей конфигурации, не относящихся к каналам, например блокаbrowserвстроенного плагина браузера. - Планирование настройки или среды выполнения, инициированное провайдером, использует в качестве резервного варианта устаревшее владение
providers[]и верхнеуровневое владениеcliBackends[], когда отсутствуют явные метаданные активации провайдера.
activation-command-hint означает, что совпал activation.onCommands, а manifest-command-alias — что планировщик вместо этого использовал владение commandAliases. Эти метки причин предназначены для диагностики хоста и тестов; авторам плагинов следует продолжать указывать метаданные, которые лучше всего описывают владение.
Справочник qaRunners
ИспользуйтеqaRunners, когда плагин предоставляет один или несколько транспортных обработчиков под
общим корнем openclaw qa. Эти метаданные должны оставаться легковесными и статическими; среда
выполнения плагина по-прежнему отвечает за фактическую регистрацию CLI через легковесную
поверхность runtime-api.ts, которая экспортирует соответствующие qaRunnerCliRegistrations. Необязательный
adapterFactory предоставляет транспорт общим сценариям контроля качества, не
изменяя обработчик зарегистрированной команды.
Идентификатор
adapterFactory должен совпадать с commandName. Не экспортируйте регистрации
для команд, отсутствующих в манифесте.
Справочник setup
Используйтеsetup, когда поверхностям настройки и первоначальной подготовки нужны легковесные метаданные, принадлежащие плагину, до загрузки среды выполнения.
cliBackends остаётся допустимым и продолжает описывать серверные части логического вывода CLI. setup.cliBackends — это поверхность дескрипторов для настройки, предназначенная для потоков уровня управления и настройки, которые должны использовать только метаданные.
При наличии setup.providers и setup.cliBackends являются предпочтительной поверхностью поиска на основе дескрипторов для обнаружения настройки. Если дескриптор лишь сужает выбор плагина-кандидата, а настройке всё ещё нужны более функциональные перехватчики среды выполнения на этапе настройки, задайте requiresRuntime: true и оставьте setup-api в качестве резервного пути выполнения.
OpenClaw также включает setup.providers[].envVars в общие операции поиска аутентификации провайдеров и переменных среды. providerAuthEnvVars продолжает поддерживаться через адаптер совместимости в течение периода прекращения поддержки, однако сторонние плагины, которые всё ещё его используют, получают диагностическое сообщение манифеста. Новым плагинам следует помещать метаданные переменных среды для настройки и состояния в 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 для поиска настройки. Если плагин, использующий только дескрипторы, всё же предоставляет одну из этих записей среды выполнения настройки, OpenClaw сообщает дополнительное диагностическое сообщение и продолжает её игнорировать. Если requiresRuntime не указан, сохраняется устаревшее резервное поведение, чтобы существующие плагины, добавившие дескрипторы без этого флага, не перестали работать.
Поскольку поиск настройки может выполнять принадлежащий плагину код setup-api, нормализованные значения setup.providers[].id и setup.cliBackends[] должны оставаться уникальными среди обнаруженных плагинов. При неоднозначном владении операция завершается отказом вместо выбора победителя на основе порядка обнаружения.
При выполнении среды настройки диагностика реестра настройки сообщает о расхождении дескрипторов, если setup-api регистрирует провайдера или серверную часть CLI, не объявленную дескрипторами манифеста, либо если дескриптору не соответствует регистрация среды выполнения. Эти диагностические сообщения являются дополнительными и не приводят к отклонению устаревших плагинов.
Справочник setup.providers
authEvidence предназначен для принадлежащих провайдеру маркеров локальных учётных данных, которые можно проверить без загрузки кода среды выполнения. Эти проверки должны оставаться легковесными и локальными: без сетевых вызовов, чтения связки ключей или диспетчера секретов, команд оболочки и запросов к API провайдера.
Поддерживаемые записи признаков:
Поля setup
Справочник uiHints
uiHints — это сопоставление имён полей конфигурации с небольшими подсказками по отображению. Ключи могут использовать точки для вложенных полей конфигурации, однако ни один сегмент пути не может быть __proto__, constructor или prototype; настройка отклоняет такие имена.
Справочник contracts
Используйтеcontracts только для статических метаданных владения возможностями, которые OpenClaw может прочитать без импорта среды выполнения плагина.
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 — это метаданные манифеста плагина, а не новый раздел пользовательской конфигурации верхнего уровня. Пользователи по-прежнему настраивают экземпляры каналов в channels.<channel-id>. OpenClaw считывает метаданные манифеста, чтобы определить, какой плагин владеет настроенным каналом, до выполнения кода среды выполнения плагина.
Для плагина канала configSchema и channelConfigs описывают разные пути:
configSchemaпроверяетplugins.entries.<plugin-id>.configchannelConfigs.<channel-id>.schemaпроверяетchannels.<channel-id>
channels[], также должны объявлять соответствующие записи channelConfigs. Без них OpenClaw всё равно может загрузить плагин, но схема конфигурации холодного пути, настройка и поверхности Control UI не смогут определить форму параметров, принадлежащих каналу, пока не выполнится среда выполнения плагина.
channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled и nativeSkillsAutoEnabled могут объявлять статические значения auto по умолчанию для проверок конфигурации команд, выполняемых до загрузки среды выполнения канала. Встроенные каналы также могут публиковать те же значения по умолчанию через package.json#openclaw.channel.commands вместе с другими принадлежащими пакету метаданными каталога каналов.
Замена другого плагина канала
ИспользуйтеpreferOver, если ваш плагин является предпочтительным владельцем идентификатора канала, который также может предоставляться другим плагином. Типичные случаи: переименованный идентификатор плагина, автономный плагин, заменяющий встроенный, или поддерживаемый форк, сохраняющий тот же идентификатор канала для совместимости конфигурации.
channels.chat, OpenClaw учитывает как идентификатор канала, так и идентификатор предпочтительного плагина. Если менее приоритетный плагин был выбран только потому, что он встроен или включён по умолчанию, OpenClaw отключает его в фактической конфигурации среды выполнения, чтобы каналом и его инструментами владел один плагин. Явный выбор пользователя по-прежнему имеет приоритет: если пользователь явно включает оба плагина (через plugins.allow или содержательную конфигурацию plugins.entries), OpenClaw сохраняет этот выбор и сообщает диагностические сведения о дублировании каналов и инструментов вместо скрытого изменения запрошенного набора плагинов.
Ограничивайте область действия preferOver идентификаторами плагинов, которые действительно могут предоставлять тот же канал. Это не общее поле приоритета, и оно не переименовывает ключи пользовательской конфигурации.
Справочник modelSupport
ИспользуйтеmodelSupport, если OpenClaw должен определять ваш плагин провайдера по сокращённым идентификаторам моделей, таким как gpt-5.6-sol или claude-sonnet-4.6, до загрузки среды выполнения плагина.
- явные ссылки
provider/modelиспользуют метаданные манифеста владельцаproviders modelPatternsимеют приоритет надmodelPrefixes- если совпадают один невстроенный и один встроенный плагин, побеждает невстроенный
- оставшаяся неоднозначность игнорируется, пока пользователь или конфигурация не укажет провайдера
Записи
modelPatterns компилируются через compileSafeRegex, который отклоняет шаблоны с вложенным повторением (например, (a+)+$). Шаблоны, не прошедшие проверку безопасности, без уведомления пропускаются, как и синтаксически недопустимые регулярные выражения. Используйте простые шаблоны и избегайте вложенных квантификаторов.
Справочник modelCatalog
ИспользуйтеmodelCatalog, если OpenClaw должен знать метаданные моделей провайдера до загрузки среды выполнения плагина. Это принадлежащий манифесту источник фиксированных строк каталога, псевдонимов провайдеров, правил подавления и режима обнаружения. Обновление во время выполнения по-прежнему относится к коду среды выполнения провайдера, но манифест сообщает ядру, когда требуется среда выполнения.
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 проверяет только объявленный псевдоним, ограничения которого в lock-файле соответствуют текущему хосту. Если 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
- Каждый плагин должен поставляться с JSON Schema, даже если он не принимает конфигурацию.
- Допускается пустая схема (например,
{ "type": "object", "additionalProperties": false }). - Схемы проверяются при чтении и записи конфигурации, а не во время выполнения.
- При расширении или создании форка встроенного плагина с новыми ключами конфигурации одновременно обновите
openclaw.plugin.jsonconfigSchemaэтого плагина. Схемы встроенных плагинов строгие, поэтому добавлениеplugins.entries.<id>.config.myNewKeyв пользовательскую конфигурацию без добавленияmyNewKeyвconfigSchema.propertiesбудет отклонено до загрузки среды выполнения плагина.
Поведение при проверке
- Неизвестные ключи
channels.*считаются ошибками, если идентификатор канала не объявлен в манифесте плагина. Если тот же идентификатор также присутствует вplugins.allow,plugins.entriesилиplugins.installs(упомянутый в конфигурации плагин, который в данный момент невозможно обнаружить), OpenClaw вместо этого понижает уровень проблемы до предупреждения. - Ссылки на неизвестные идентификаторы плагинов в
plugins.entries.<id>,plugins.allowиplugins.denyсчитаются предупреждениями («устаревшая запись конфигурации проигнорирована»), а не ошибками, поэтому обновления и удалённые или переименованные плагины не блокируют запуск Gateway. - Ссылка на неизвестный идентификатор плагина в
plugins.slots.memoryсчитается ошибкой, за исключением известного официального внешнего плагинаmemory-lancedb, для которого вместо этого выдаётся предупреждение. - Если плагин установлен, но его манифест или схема повреждены либо отсутствуют, проверка завершается ошибкой, а Doctor сообщает об ошибке плагина.
- Если конфигурация плагина существует, но плагин отключён, конфигурация сохраняется, а в Doctor и журналах отображается предупреждение.
plugins.* см. в справочнике по конфигурации.
Примечания
- Манифест обязателен для нативных плагинов OpenClaw, включая загружаемые из локальной файловой системы. Среда выполнения по-прежнему загружает модуль плагина отдельно; манифест используется только для обнаружения и проверки.
- Нативные манифесты разбираются как JSON5, поэтому допускаются комментарии, завершающие запятые и ключи без кавычек, если итоговое значение остаётся объектом.
- Загрузчик манифестов считывает только документированные поля манифеста. Не используйте нестандартные ключи верхнего уровня.
channels,providers,cliBackendsиskillsможно не указывать, если они не нужны плагину.providerCatalogEntryдолжен оставаться легковесным и не должен импортировать обширный код среды выполнения; используйте его для статических метаданных каталога провайдера или узкоспециализированных дескрипторов обнаружения, а не для выполнения во время обработки запросов.- Взаимоисключающие типы плагинов выбираются через
plugins.slots.*:kind: "memory"черезplugins.slots.memory(по умолчаниюmemory-core),kind: "context-engine"черезplugins.slots.contextEngine(по умолчаниюlegacy). - Объявляйте взаимоисключающий тип плагина в этом манифесте.
OpenClawPluginDefinition.kindв точке входа среды выполнения устарел и сохраняется только как резервный механизм совместимости со старыми плагинами. - Метаданные переменных среды (
setup.providers[].envVars, устаревшийproviderAuthEnvVarsиchannelEnvVars) носят исключительно декларативный характер. Состояние, аудит, проверка доставки Cron и другие поверхности только для чтения по-прежнему применяют политику доверия к плагину и его фактической активации, прежде чем считать переменную среды настроенной. - Метаданные мастера среды выполнения, для которых требуется код провайдера, описаны в разделе Перехватчики среды выполнения провайдера.
- Если плагин зависит от нативных модулей, документируйте этапы сборки и все требования к списку разрешений менеджера пакетов (например, pnpm
allow-build-scripts+pnpm rebuild <package>).
Связанные материалы
Создание плагинов
Начало работы с плагинами.
Архитектура плагинов
Внутренняя архитектура и модель возможностей.
Обзор SDK
Справочник по SDK плагинов и импорту подпутей.