Plugin manifest

Эта страница предназначена только для нативного манифеста Plugin OpenClaw.

Совместимые макеты пакетов см. в разделе Пакеты Plugin.

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

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

OpenClaw также автоматически обнаруживает эти макеты пакетов, но они не проходят проверку по схеме openclaw.plugin.json, описанной здесь.

Для совместимых пакетов OpenClaw сейчас считывает метаданные пакета, объявленные корни Skills, корни команд Claude, стандартные значения settings.json пакета Claude, стандартные значения LSP пакета Claude и поддерживаемые наборы хуков, когда макет соответствует ожиданиям среды выполнения OpenClaw.

Каждый нативный Plugin OpenClaw должен поставляться с файлом openclaw.plugin.json в корне Plugin. OpenClaw использует этот манифест для проверки конфигурации без выполнения кода Plugin. Отсутствующие или недействительные манифесты считаются ошибками Plugin и блокируют проверку конфигурации.

См. полное руководство по системе Plugin: Plugin. Нативная модель возможностей и текущие рекомендации по внешней совместимости: Модель возможностей.

Что делает этот файл

openclaw.plugin.json — это метаданные, которые OpenClaw считывает до загрузки вашего кода Plugin. Все ниже должно быть достаточно легковесным для проверки без запуска среды выполнения Plugin.

Используйте его для:

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

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

Минимальный пример

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

Расширенный пример

{  "id": "openrouter",  "name": "OpenRouter",  "description": "OpenRouter provider plugin",  "version": "1.0.0",  "providers": ["openrouter"],  "modelSupport": {    "modelPrefixes": ["router-"]  },  "modelIdNormalization": {    "providers": {      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  },  "providerEndpoints": [    {      "endpointClass": "openrouter",      "hostSuffixes": ["openrouter.ai"]    }  ],  "providerRequest": {    "providers": {      "openrouter": {        "family": "openrouter"      }    }  },  "cliBackends": ["openrouter-cli"],  "syntheticAuthRefs": ["openrouter-cli"],  "setup": {    "providers": [      {        "id": "openrouter",        "envVars": ["OPENROUTER_API_KEY"]      }    ]  },  "providerAuthAliases": {    "openrouter-coding": "openrouter"  },  "channelEnvVars": {    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "OpenRouter API key",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter API key",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API key",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

Справочник полей верхнего уровня

Справочник метаданных провайдеров генерации

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

Используйте эти поля только для дешевых декларативных фактов. Транспорт, преобразования запросов, обновление токенов, проверка учетных данных и фактическое поведение генерации остаются в среде выполнения Plugin.

{  "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 мог избежать импорта среды выполнения Plugin только для того, чтобы фабрика инструмента вернула null.

{  "setup": {    "providers": [      {        "id": "example",        "envVars": ["EXAMPLE_API_KEY"]      }    ]  },  "contracts": {    "tools": ["example_search"]  },  "toolMetadata": {    "example_search": {      "authSignals": [        {          "provider": "example"        }      ],      "configSignals": [        {          "rootPath": "plugins.entries.example.config",          "overlayPath": "search",          "required": ["apiKey"]        }      ]    }  }}

Если у инструмента нет toolMetadata, OpenClaw сохраняет существующее поведение и загружает владеющий Plugin, когда контракт инструмента соответствует политике. Для инструментов на горячем пути, фабрика которых зависит от аутентификации или конфигурации, авторам Plugin следует объявлять toolMetadata вместо того, чтобы заставлять ядро импортировать среду выполнения для запроса.

Справочник providerAuthChoices

Каждая запись providerAuthChoices описывает один вариант онбординга или аутентификации. 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 и hooks.

Предпочитайте самые узкие метаданные, которые уже описывают владение. Используйте providers, channels, commandAliases, дескрипторы setup или contracts, когда эти поля выражают связь. Используйте activation для дополнительных подсказок планировщика, которые нельзя представить этими полями владения. Используйте верхнеуровневый cliBackends для псевдонимов среды выполнения CLI, таких как claude-cli, my-cli или google-gemini-cli; activation.onAgentHarnesses предназначен только для идентификаторов встроенных агентских harness, у которых еще нет поля владения.

Этот блок содержит только метаданные. Он не регистрирует поведение среды выполнения и не заменяет register(...), setupEntry или другие точки входа среды выполнения/Plugin. Текущие потребители используют его как сужающую подсказку перед более широкой загрузкой Plugin, поэтому отсутствие метаданных активации не для запуска обычно влияет только на производительность; оно не должно менять корректность, пока по-прежнему существуют откаты к владению из манифеста.

Каждый Plugin должен задавать activation.onStartup намеренно. Установите true только тогда, когда Plugin должен запускаться во время старта Gateway. Установите false, когда Plugin инертен при запуске и должен загружаться только по более узким триггерам. Если onStartup опущен, Plugin больше не загружается при запуске неявно; используйте явные метаданные активации для запуска, канала, конфигурации, agent-harness, памяти или других более узких триггеров активации.

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

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

Справочник qaRunners

Используйте qaRunners, когда Plugin добавляет один или несколько транспортных runner под общим корнем openclaw qa. Держите эти метаданные легковесными и статическими; среда выполнения Plugin по-прежнему владеет фактической регистрацией CLI через легковесную поверхность runtime-api.ts, которая экспортирует qaRunnerCliRegistrations.

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

Справочник setup

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

{  "setup": {    "providers": [      {        "id": "openai",        "authMethods": ["api-key"],        "envVars": ["OPENAI_API_KEY"],        "authEvidence": [          {            "type": "local-file-with-env",            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",            "requiresAllEnv": ["OPENAI_PROJECT"],            "credentialMarker": "openai-local-credentials",            "source": "openai local credentials"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

Верхнеуровневое cliBackends остается допустимым и продолжает описывать backend-ы вывода CLI. setup.cliBackends — это специфичная для настройки поверхность дескрипторов для потоков control-plane/setup, которые должны оставаться только метаданными.

Если они присутствуют, setup.providers и setup.cliBackends являются предпочтительной поверхностью поиска по принципу descriptor-first для обнаружения настройки. Если дескриптор только сужает plugin-кандидат, а настройке все еще нужны более богатые runtime-хуки времени настройки, задайте requiresRuntime: true и оставьте setup-api на месте как резервный путь выполнения.

OpenClaw также включает setup.providers[].envVars в общие проверки аутентификации provider и поиски env-переменных. providerAuthEnvVars остается поддерживаемым через адаптер совместимости в течение окна устаревания, но не входящие в комплект plugins, которые все еще используют его, получают диагностическое сообщение manifest. Новые plugins должны помещать env-метаданные настройки/статуса в setup.providers[].envVars.

OpenClaw также может выводить простые варианты настройки из setup.providers[].authMethods, когда запись setup недоступна или когда setup.requiresRuntime: false объявляет, что setup runtime не нужен. Явные записи providerAuthChoices остаются предпочтительными для пользовательских меток, флагов CLI, области онбординга и метаданных assistant.

Задавайте requiresRuntime: false только когда этих дескрипторов достаточно для поверхности setup. OpenClaw трактует явное false как контракт только на дескрипторах и не будет выполнять setup-api или openclaw.setupEntry для поиска setup. Если plugin, работающий только по дескрипторам, все еще поставляет одну из этих runtime-записей setup, OpenClaw сообщает добавочную диагностику и продолжает игнорировать ее. Отсутствующее requiresRuntime сохраняет legacy-поведение fallback, чтобы существующие plugins, которые добавили дескрипторы без этого флага, не ломались.

Поскольку поиск setup может выполнять код setup-api, принадлежащий plugin, нормализованные значения setup.providers[].id и setup.cliBackends[] должны оставаться уникальными среди обнаруженных plugins. Неоднозначное владение завершается закрытым отказом вместо выбора победителя по порядку обнаружения.

Когда setup runtime действительно выполняется, диагностика реестра setup сообщает о расхождении дескрипторов, если setup-api регистрирует provider или backend CLI, который дескрипторы manifest не объявляют, или если у дескриптора нет соответствующей runtime-регистрации. Эта диагностика является добавочной и не отклоняет legacy plugins.

Справочник setup.providers

authEvidence предназначен для принадлежащих provider локальных маркеров учетных данных, которые можно проверять без загрузки runtime-кода. Эти проверки должны оставаться дешевыми и локальными: без сетевых вызовов, без чтения keychain или secret-manager, без shell-команд и без проб provider API.

Поддерживаемые записи доказательств:

Поля setup

Справочник uiHints

uiHints — это отображение имен полей config в небольшие подсказки рендеринга.

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

Подсказка каждого поля может включать:

Справочник contracts

Используйте contracts только для статических метаданных владения capability, которые OpenClaw может читать без импорта runtime plugin.

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"],    "trustedToolPolicies": ["workflow-budget"],    "externalAuthProviders": ["acme-ai"],    "embeddingProviders": ["openai-compatible"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Каждый список необязателен:

contracts.embeddedExtensionFactories сохраняется для встроенных фабрик расширений Codex, предназначенных только для app-server. Встроенные преобразования результатов инструментов должны объявлять contracts.agentToolResultMiddleware и вместо этого регистрироваться через api.registerAgentToolResultMiddleware(...). Установленные плагины могут использовать тот же стык middleware только при явном включении и только для runtime, которые они объявляют в contracts.agentToolResultMiddleware.

Установленные плагины, которым нужен host-trusted уровень pre-tool policy, должны объявить каждый зарегистрированный локальный идентификатор в contracts.trustedToolPolicies и быть явно включены. Встроенные плагины сохраняют существующий путь доверенных политик, но установленные плагины с необъявленными идентификаторами политик отклоняются до регистрации. Идентификаторы политик ограничены регистрирующим плагином, поэтому два плагина могут оба объявить и зарегистрировать workflow-budget; один плагин не может зарегистрировать один и тот же локальный идентификатор дважды.

Регистрации runtime api.registerTool(...) должны соответствовать contracts.tools. Обнаружение инструментов использует этот список, чтобы загружать только runtime плагинов, которые могут владеть запрошенными инструментами.

Плагины провайдеров, реализующие resolveExternalAuthProfiles, должны объявлять contracts.externalAuthProviders; необъявленные hooks внешней аутентификации игнорируются.

Общие embedding-провайдеры должны объявлять contracts.embeddingProviders для каждого адаптера, зарегистрированного через api.registerEmbeddingProvider(...). Используйте общий контракт для переиспользуемой генерации векторов, включая провайдеров, используемых поиском по памяти. contracts.memoryEmbeddingProviders является устаревшей совместимостью, специфичной для памяти, и остается только на время миграции существующих провайдеров на общий стык embedding-провайдера.

contracts.gatewayMethodDispatch сейчас принимает "authenticated-request". Это гейт гигиены API для нативных HTTP-маршрутов плагина, которые намеренно dispatch-ят методы control-plane Gateway внутри процесса, а не sandbox против вредоносных нативных плагинов. Используйте его только для тщательно проверенных встроенных/operator поверхностей, которые уже требуют HTTP-аутентификацию Gateway.

Справочник mediaUnderstandingProviderMetadata

Используйте mediaUnderstandingProviderMetadata, когда у провайдера понимания медиа есть модели по умолчанию, приоритет fallback для auto-auth или нативная поддержка документов, которые нужны общим core helpers до загрузки runtime. Ключи также должны быть объявлены в contracts.mediaUnderstandingProviders.

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

Каждая запись провайдера может включать:

Справочник channelConfigs

Используйте channelConfigs, когда плагину канала нужны дешевые метаданные config до загрузки runtime. Обнаружение настройки/статуса канала только для чтения может использовать эти метаданные напрямую для настроенных внешних каналов, когда запись настройки недоступна или когда setup.requiresRuntime: false объявляет runtime настройки ненужным.

channelConfigs — это метаданные манифеста плагина, а не новый пользовательский раздел config верхнего уровня. Пользователи по-прежнему настраивают экземпляры каналов в channels.<channel-id>. OpenClaw читает метаданные манифеста, чтобы решить, какому плагину принадлежит этот настроенный канал, до выполнения runtime-кода плагина.

Для плагина канала configSchema и channelConfigs описывают разные пути:

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

Невстроенные плагины, которые объявляют channels[], также должны объявлять соответствующие записи channelConfigs. Без них OpenClaw все равно может загрузить плагин, но cold-path схема config, настройка и поверхности Control UI не смогут узнать форму опций, принадлежащих каналу, пока не выполнится runtime плагина.

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

{  "channelConfigs": {    "matrix": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "homeserverUrl": { "type": "string" }        }      },      "uiHints": {        "homeserverUrl": {          "label": "Homeserver URL",          "placeholder": "https://matrix.example.com"        }      },      "label": "Matrix",      "description": "Matrix homeserver connection",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

Каждая запись канала может включать:

Замена другого плагина канала

Используйте preferOver, когда ваш плагин является предпочтительным владельцем для идентификатора канала, который также может предоставлять другой плагин. Типичные случаи — переименованный идентификатор плагина, автономный плагин, который заменяет встроенный плагин, или поддерживаемый форк, сохраняющий тот же идентификатор канала для совместимости config.

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

Когда channels.chat настроен, OpenClaw учитывает и идентификатор канала, и предпочтительный идентификатор плагина. Если менее приоритетный плагин был выбран только потому, что он встроен или включен по умолчанию, OpenClaw отключает его в эффективном runtime config, чтобы каналом и его инструментами владел один плагин. Явный выбор пользователя все равно имеет приоритет: если пользователь явно включает оба плагина, OpenClaw сохраняет этот выбор и сообщает диагностику дублирования канала/инструмента вместо молчаливого изменения запрошенного набора плагинов.

Ограничивайте preferOver идентификаторами плагинов, которые действительно могут предоставлять тот же канал. Это не общее поле приоритета, и оно не переименовывает пользовательские ключи config.

Справочник modelSupport

Используйте modelSupport, когда OpenClaw должен определить ваш Plugin поставщика по сокращенным id моделей, таким как gpt-5.5 или claude-sonnet-4.6, до загрузки среды выполнения Plugin.

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

OpenClaw применяет такой приоритет:

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

Поля:

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

Справочник modelCatalog

Используйте modelCatalog, когда OpenClaw должен знать метаданные моделей поставщика до загрузки среды выполнения Plugin. Это источник, принадлежащий манифесту, для фиксированных строк каталога, псевдонимов поставщиков, правил подавления и режима обнаружения. Обновление во время выполнения по-прежнему принадлежит коду среды выполнения поставщика, но манифест сообщает ядру, когда требуется среда выполнения.

{  "providers": ["openai"],  "modelCatalog": {    "providers": {      "openai": {        "baseUrl": "https://api.openai.com/v1",        "api": "openai-responses",        "models": [          {            "id": "gpt-5.4",            "name": "GPT-5.4",            "input": ["text", "image"],            "reasoning": true,            "contextWindow": 256000,            "maxTokens": 128000,            "cost": {              "input": 1.25,              "output": 10,              "cacheRead": 0.125            },            "status": "available",            "tags": ["default"]          }        ]      }    },    "aliases": {      "azure-openai-responses": {        "provider": "openai",        "api": "azure-openai-responses"      }    },    "suppressions": [      {        "provider": "azure-openai-responses",        "model": "gpt-5.3-codex-spark",        "reason": "not available on Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

Поля верхнего уровня:

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

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

Поля поставщика:

Поля модели:

Поля подавления:

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

Справочник modelIdNormalization

Используйте modelIdNormalization для дешевой очистки id моделей, принадлежащей поставщику, которая должна выполняться до загрузки среды выполнения поставщика. Это держит псевдонимы, такие как короткие имена моделей, локальные для поставщика устаревшие id и правила префиксов прокси, в манифесте Plugin владельца вместо таблиц выбора моделей в ядре.

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

Поля поставщика:

Справочник providerEndpoints

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

Поля конечной точки:

Справочник providerRequest

Используйте providerRequest для недорогих метаданных совместимости запросов, которые нужны общей политике запросов без загрузки среды выполнения провайдера. Переписывание полезной нагрузки, зависящее от поведения, оставляйте в хуках среды выполнения провайдера или общих помощниках семейства провайдеров.

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

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

Справочник secretProviderIntegrations

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

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

Ключ карты — это идентификатор интеграции. Если providerAlias опущен, OpenClaw использует идентификатор интеграции как псевдоним провайдера SecretRef. Псевдонимы провайдеров должны соответствовать обычному шаблону псевдонима провайдера SecretRef, например team-secrets или onepassword-work.

Когда оператор выбирает пресет, OpenClaw записывает ссылку на провайдера, например:

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

При запуске или перезагрузке OpenClaw разрешает этого провайдера, загружая текущие метаданные манифеста plugin, проверяя, что владеющий plugin установлен и активен, и материализуя exec-команду из манифеста. Отключение или удаление plugin отзывает провайдера для активных SecretRefs. Операторы, которым нужна автономная exec-конфигурация, по-прежнему могут напрямую записывать ручных провайдеров command/args.

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

OpenClaw выводит trustedDirs для пресетов манифеста из корня plugin и, для пресетов ${node}, из каталога текущего исполняемого файла Node. Указанные в манифесте trustedDirs игнорируются. Другие параметры exec-провайдера, такие как timeoutMs, maxOutputBytes, jsonOnly, env, passEnv и allowInsecurePath, передаются в обычную конфигурацию exec-провайдера SecretRef.

Справочник modelPricing

Используйте modelPricing, когда провайдеру нужно поведение ценообразования control plane до загрузки среды выполнения. Кэш цен Gateway читает эти метаданные без импорта кода среды выполнения провайдера.

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

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

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

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

Индекс провайдеров OpenClaw — это принадлежащие OpenClaw предварительные метаданные для провайдеров, чьи plugins могут еще не быть установлены. Он не является частью манифеста plugin. Манифесты plugins остаются источником истины для установленных plugins. Индекс провайдеров — это внутренний резервный контракт, который будущие поверхности установки провайдеров и выбора модели до установки будут использовать, когда plugin провайдера не установлен.

Порядок источников истины каталога:

1. Конфигурация пользователя.
2. Манифест установленного plugin modelCatalog.
3. Кэш каталога моделей из явного обновления.
4. Предварительные строки Индекса провайдеров OpenClaw.

Индекс провайдеров не должен содержать секреты, включенное состояние, хуки среды выполнения или живые данные моделей, специфичные для аккаунта. Его предварительные каталоги используют ту же форму строки провайдера modelCatalog, что и манифесты plugins, но должны оставаться ограниченными стабильными отображаемыми метаданными, если только поля адаптера среды выполнения, такие как api, baseUrl, цены или флаги совместимости, намеренно не поддерживаются согласованными с манифестом установленного plugin. Провайдеры с живым обнаружением /models должны записывать обновленные строки через явный путь кэша каталога моделей, а не вызывать API провайдеров при обычном листинге или онбординге.

Записи Индекса провайдеров также могут содержать метаданные устанавливаемого plugin для провайдеров, чей plugin был вынесен из ядра или иначе еще не установлен. Эти метаданные повторяют шаблон каталога каналов: имени пакета, npm-спецификации установки, ожидаемой целостности и недорогих меток выбора аутентификации достаточно, чтобы показать вариант устанавливаемой настройки. После установки plugin его манифест получает приоритет, а запись Индекса провайдеров для этого провайдера игнорируется.

Устаревшие ключи возможностей верхнего уровня считаются deprecated. Используйте openclaw doctor --fix, чтобы переместить speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders и webSearchProviders в contracts; обычная загрузка манифеста больше не рассматривает эти поля верхнего уровня как владение возможностями.

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

Эти два файла выполняют разные задачи:

Если вы не уверены, где должны находиться конкретные метаданные, используйте это правило:

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

Поля package.json, влияющие на обнаружение

Некоторые метаданные plugin до запуска среды выполнения намеренно находятся в package.json в блоке openclaw, а не в openclaw.plugin.json. openclaw.bundle и openclaw.bundle.json не являются контрактами plugin OpenClaw; нативные plugins должны использовать openclaw.plugin.json плюс поддерживаемые поля package.json#openclaw ниже.

Важные примеры:

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

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

openclaw.install.requiredPlatformPackages предназначен для пакетов npm, которые предоставляют требуемые нативные бинарные файлы через необязательные, платформенно-специфичные псевдонимы. Укажите простое имя пакета npm для каждого поддерживаемого платформенного псевдонима. Во время установки npm OpenClaw проверяет только объявленный псевдоним, ограничения lockfile которого соответствуют текущему хосту. Если npm сообщает об успехе, но опускает этот псевдоним, OpenClaw один раз повторяет попытку со свежим кешем и откатывает установку, если псевдоним все еще отсутствует.

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

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

Точная фиксация версии npm уже находится в npmSpec, например "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Официальные записи внешнего каталога должны сочетать точные спецификации с expectedIntegrity, чтобы потоки обновления завершались закрыто, если полученный артефакт npm больше не соответствует зафиксированному релизу. Интерактивный онбординг по-прежнему предлагает доверенные спецификации npm из registry, включая простые имена пакетов и dist-tags, для совместимости. Диагностика каталога может различать точные, плавающие, закрепленные по целостности, без целостности, с несовпадением имени пакета и недействительные источники выбора по умолчанию. Она также предупреждает, когда expectedIntegrity присутствует, но нет допустимого источника npm, который он может закрепить. Когда expectedIntegrity присутствует, потоки установки/обновления принудительно применяют его; когда он опущен, разрешение registry записывается без закрепления целостности.

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

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

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

openclaw.channel.persistedAuthState — это метаданные пакета для крошечного модуля проверки:

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

Используйте их, когда настройке, doctor, статусу или потокам присутствия только для чтения нужна дешевая проверка аутентификации да/нет до загрузки полного Plugin канала. Сохраненное состояние аутентификации не является настроенным состоянием канала: не используйте эти метаданные для автоматического включения plugins, исправления зависимостей среды выполнения или решения о том, должна ли загружаться среда выполнения канала. Целевой export должен быть небольшой функцией, которая читает только сохраненное состояние; не проводите ее через полный barrel среды выполнения канала.

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

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

Используйте это, когда канал может ответить о настроенном состоянии из env или других маленьких не-runtime входов. Если проверке нужно полное разрешение конфигурации или настоящая среда выполнения канала, оставьте эту логику в хуке Plugin config.hasConfiguredState.

Приоритет обнаружения (повторяющиеся id plugins)

OpenClaw обнаруживает plugins из нескольких корней. Порядок сырого сканирования файловой системы см. в разделе Порядок сканирования Plugin. Если два обнаружения имеют один и тот же id, сохраняется только манифест с наивысшим приоритетом; дубликаты с более низким приоритетом отбрасываются вместо загрузки рядом с ним.

Приоритет, от высшего к низшему:

1. Выбранный конфигурацией — путь, явно закрепленный в plugins.entries.<id>
2. Встроенный — plugins, поставляемые с OpenClaw
3. Глобальная установка — plugins, установленные в глобальный корень plugins OpenClaw
4. Workspace — plugins, обнаруженные относительно текущего workspace

Следствия:

• Ответвленная или устаревшая копия встроенного Plugin, находящаяся в workspace, не затмит встроенную сборку.
• Чтобы действительно переопределить встроенный Plugin локальным, закрепите его через plugins.entries.<id>, чтобы он победил по приоритету, а не полагайтесь на обнаружение workspace.
• Отбрасывания дубликатов логируются, чтобы Doctor и диагностика запуска могли указать на отброшенную копию.
• Переопределения дубликатов, выбранные конфигурацией, формулируются в диагностике как явные переопределения, но все равно предупреждают, чтобы устаревшие форки и случайные затенения оставались видимыми.

Требования JSON Schema

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

Пример расширения схемы:

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

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

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

См. Справочник по конфигурации для полной схемы plugins.*.

Примечания

• Манифест обязателен для нативных plugin OpenClaw, включая загрузки из локальной файловой системы. Среда выполнения по-прежнему загружает модуль plugin отдельно; манифест нужен только для обнаружения и проверки.
• Нативные манифесты анализируются с помощью JSON5, поэтому комментарии, завершающие запятые и ключи без кавычек принимаются, если итоговое значение остается объектом.
• Загрузчик манифестов читает только документированные поля манифеста. Избегайте пользовательских ключей верхнего уровня.
• channels, providers, cliBackends и skills можно опустить, если они не нужны plugin.
• providerCatalogEntry должен оставаться легковесным и не должен импортировать обширный код среды выполнения; используйте его для статических метаданных каталога провайдеров или узких дескрипторов обнаружения, а не для выполнения во время запроса.
• Эксклюзивные виды plugin выбираются через plugins.slots.*: kind: "memory" через plugins.slots.memory, kind: "context-engine" через plugins.slots.contextEngine (по умолчанию legacy).
• Объявляйте эксклюзивный вид plugin в этом манифесте. OpenClawPluginDefinition.kind во входной точке среды выполнения устарел и остается только как резервная совместимость для старых plugin.
• Метаданные переменных окружения (setup.providers[].envVars, устаревшие providerAuthEnvVars и channelEnvVars) имеют только декларативный характер. Статус, аудит, проверка доставки cron и другие поверхности только для чтения по-прежнему применяют доверие к plugin и эффективную политику активации, прежде чем считать переменную окружения настроенной.
• Метаданные мастера настройки среды выполнения, которым требуется код провайдера, см. в хуках среды выполнения провайдера.
• Если ваш plugin зависит от нативных модулей, задокументируйте шаги сборки и все требования к спискам разрешений пакетного менеджера (например, pnpm allow-build-scripts + pnpm rebuild <package>).

Связанные материалы