插件清单

此页面介绍原生 OpenClaw 插件清单 openclaw.plugin.json。有关兼容的捆绑包布局（Codex、Claude、Cursor），请参阅插件捆绑包。

兼容的捆绑包格式改用各自的清单文件：

• Codex 捆绑包：.codex-plugin/plugin.json
• Claude 捆绑包：.claude-plugin/plugin.json，或不含清单的默认 Claude 组件布局
• Cursor 捆绑包：.cursor-plugin/plugin.json

OpenClaw 会自动检测这些布局，但不会使用下方的 openclaw.plugin.json schema 验证它们。对于兼容的捆绑包，当布局符合 OpenClaw 的运行时要求时，OpenClaw 会读取捆绑包元数据、声明的 Skills 根目录、Claude 命令根目录、Claude settings.json 默认值、Claude LSP 默认值以及受支持的钩子包。

每个原生 OpenClaw 插件都必须在插件根目录中提供 openclaw.plugin.json。OpenClaw 会读取该文件，以便在不执行插件代码的情况下验证配置。清单缺失或无效会阻止配置验证，并被视为插件错误。

有关完整的插件系统指南，请参阅插件；有关原生能力模型和当前的外部兼容性指南，请参阅能力模型。

此文件的作用

openclaw.plugin.json 是 OpenClaw 在加载你的插件代码之前读取的元数据。其中的所有内容都必须足够轻量，无需启动插件运行时即可检查。

用于：

• 插件标识、配置验证和配置 UI 提示
• 身份验证、新手引导和设置元数据（别名、自动启用、提供商环境变量、身份验证选项）
• 控制平面界面的激活提示
• 模型系列所有权的简写形式
• 静态能力所有权快照（contracts）
• 共享 openclaw qa 主机可检查的 QA 运行程序元数据
• 合并到目录和验证界面中的渠道特定配置元数据

**请勿用于：**注册运行时行为、声明代码入口点或 npm 安装元数据。这些内容应放在你的插件代码和 package.json 中。

最小示例

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

完整示例

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

顶层字段参考

目录参考

catalog 为插件浏览器提供可选的显示提示。宿主可以忽略这些提示。它们绝不会安装或启用插件，也不会改变插件的运行时行为或信任级别。

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

生成提供商元数据参考

生成提供商元数据字段描述匹配的 contracts.*GenerationProviders 列表中所声明提供商的静态身份验证信号。OpenClaw 会在提供商运行时加载之前读取这些字段，使核心工具无需导入每个提供商插件即可判断生成提供商是否可用。

这些字段仅用于成本低廉的声明式事实。传输、请求转换、令牌刷新、凭据验证和实际生成行为仍由插件运行时负责。

{  "contracts": {    "imageGenerationProviders": ["example-image"]  },  "imageGenerationProviderMetadata": {    "example-image": {      "aliases": ["example-image-oauth"],      "authProviders": ["example-image"],      "configSignals": [        {          "rootPath": "plugins.entries.example-image.config",          "overlayPath": "image",          "mode": {            "path": "mode",            "default": "local",            "allowed": ["local"]          },          "requiredAny": ["workflow", "workflowPath"],          "required": ["promptNodeId"]        }      ],      "authSignals": [        {          "provider": "example-image"        },        {          "provider": "example-image-oauth",          "providerBaseUrl": {            "provider": "example-image",            "defaultBaseUrl": "https://api.example.com/v1",            "allowedBaseUrls": ["https://api.example.com/v1"]          }        }      ]    }  }}

每个元数据条目支持：

每个 configSignals 条目支持：

每个 mode 约束支持：

每个 authSignals 条目支持：

每个 providerBaseUrl 约束支持：

工具元数据参考

toolMetadata 使用与生成提供商元数据相同的 configSignals 和 authSignals 结构，并以工具名称作为键。contracts.tools 声明所有权。toolMetadata 声明低成本的可用性证据，使 OpenClaw 不必仅仅为了让工具工厂返回 null 而导入插件运行时。

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

除上述共享的 configSignals/authSignals 字段外，toolMetadata 条目还接受 optional（将工具标记为插件激活时的非必需项）和 replaySafe（将工具执行标记为可在未完成的模型轮次后安全重复）。

如果工具没有 toolMetadata，OpenClaw 会保留现有行为，并在工具契约符合策略时加载所属插件。对于工具工厂依赖身份验证或配置的热路径工具，插件作者应声明 toolMetadata，而不是让核心导入运行时进行询问。

providerAuthChoices 参考

每个 providerAuthChoices 条目描述一个新手引导或身份验证选项。OpenClaw 会在提供商运行时加载之前读取它。提供商设置列表会使用这些清单选项、从描述符派生的设置选项以及安装目录元数据，而无需加载提供商运行时。

commandAliases 参考

当插件拥有一个运行时命令名称，而用户可能误将其放入 plugins.allow 或尝试将其作为根 CLI 命令运行时，请使用 commandAliases。OpenClaw 使用此元数据进行诊断，无需导入插件运行时代码。

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

activation 参考

当插件能够以较低成本声明哪些控制平面事件应将其纳入激活/加载计划时，请使用 activation。

此块是规划器元数据，而不是生命周期 API。它不会注册运行时行为，不会取代 register(...)，也不保证插件代码已经执行。激活规划器使用这些字段缩小候选插件范围，然后才回退到现有的清单所有权元数据，例如 providers、channels、commandAliases、setup.providers、contracts.tools 和钩子。

优先使用已能描述所有权的最精确元数据。当 providers、channels、commandAliases、设置描述符或 contracts 能表达这种关系时，请使用这些字段。对于无法由这些所有权字段表示的额外规划器提示，请使用 activation。对于 claude-cli、my-cli 或 google-gemini-cli 等 CLI 运行时别名，请使用顶层 cliBackends；activation.onAgentHarnesses 仅用于尚无所有权字段的嵌入式 Agent harness ID。

每个插件都应有意设置 activation.onStartup。仅当插件必须在 Gateway 网关启动期间运行时，才将其设置为 true。当插件在启动时处于非活动状态，并且只应由更精确的触发器加载时，将其设置为 false。省略 onStartup 不再隐式地在启动时加载插件；请为启动、渠道、配置、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。
• Agent 运行时启动规划对嵌入式 harness 使用 activation.onAgentHarnesses，对 CLI 运行时别名使用顶层 cliBackends[]。
• 当缺少显式渠道激活元数据时，渠道触发的设置/渠道规划会回退到旧版 channels[] 所有权。
• 启动插件规划对非渠道根配置界面使用 activation.onConfigPaths，例如内置浏览器插件的 browser 块。
• 当缺少显式提供商激活元数据时，提供商触发的设置/运行时规划会回退到旧版 providers[] 和顶层 cliBackends[] 所有权。

规划器诊断可以区分显式激活提示与清单所有权回退。例如，activation-command-hint 表示匹配了 activation.onCommands，而 manifest-command-alias 表示规划器改用了 commandAliases 所有权。这些原因标签用于宿主诊断和测试；插件作者应继续声明最能描述所有权的元数据。

qaRunners 参考

当插件在共享的 openclaw qa 根命令下提供一个或多个传输运行器时，请使用 qaRunners。请保持此元数据轻量且静态；插件运行时仍通过轻量级 runtime-api.ts 界面负责实际的 CLI 注册，该界面导出匹配的 qaRunnerCliRegistrations。可选的 adapterFactory 可将传输方式暴露给共享 QA 场景，而无需更改已注册命令的运行器。

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

adapterFactory id 必须与 commandName 匹配。不要为清单中不存在的命令导出注册项。

设置参考

当设置和新手引导界面需要在运行时加载前获取开销较低且由插件所有的元数据时，请使用 setup。

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

顶层 cliBackends 仍然有效，并继续描述 CLI 推理后端。setup.cliBackends 是特用于设置的描述符界面，供应保持仅使用元数据的控制平面和设置流程使用。

当 setup.providers 和 setup.cliBackends 存在时，它们是设置发现中首选的描述符优先查找界面。如果描述符只能缩小候选插件范围，而设置仍需要更丰富的设置阶段运行时钩子，请设置 requiresRuntime: true，并保留 setup-api 作为回退执行路径。

OpenClaw 还会将 setup.providers[].envVars 纳入通用提供商身份验证和环境变量查找。弃用期内仍通过兼容适配器支持 providerAuthEnvVars，但仍使用它的非内置插件会收到清单诊断。新插件应将设置和状态环境变量元数据放在 setup.providers[].envVars 中。

当计费或组织级凭据必须激活 resolveUsageAuth，但不应成为推理凭据时，请使用 providerUsageAuthEnvVars。这些名称会加入工作区 dotenv 阻止列表、ACP 子进程剥离、沙箱机密过滤和广泛的机密清理。提供商运行时仍会在 resolveUsageAuth 内读取并分类该值。

如果没有设置入口，或者 setup.requiresRuntime: false 声明不需要设置运行时，OpenClaw 也可以从 setup.providers[].authMethods 推导简单的设置选项。对于自定义标签、CLI 标志、新手引导范围和助手元数据，仍优先使用显式的 providerAuthChoices 条目。

仅当这些描述符足以满足设置界面的需求时，才设置 requiresRuntime: false。OpenClaw 将显式的 false 视为仅使用描述符的契约，不会为设置查找执行 setup-api 或 openclaw.setupEntry。如果仅使用描述符的插件仍提供其中一个设置运行时入口，OpenClaw 会报告附加诊断，并继续忽略该入口。省略 requiresRuntime 会保留旧版回退行为，因此，已经添加描述符但未添加此标志的现有插件不会中断。

由于设置查找可能执行插件所有的 setup-api 代码，因此规范化后的 setup.providers[].id 和 setup.cliBackends[] 值必须在发现的所有插件中保持唯一。所有权不明确时会采用失败关闭策略，而不是按照发现顺序选择一个胜出者。

当设置运行时确实执行时，如果 setup-api 注册了清单描述符未声明的提供商或 CLI 后端，或者描述符没有匹配的运行时注册项，设置注册表诊断会报告描述符漂移。这些诊断是附加的，不会拒绝旧版插件。

setup.providers 参考

authEvidence 用于由提供商所有、无需加载运行时代码即可验证的本地凭据标记。这些检查必须保持低开销且仅限本地：不得进行网络调用、读取钥匙串或机密管理器、执行 shell 命令或探测提供商 API。

支持的证据条目：

setup 字段

uiHints 参考

uiHints 是从配置字段名称到简短渲染提示的映射。键可以使用点号表示嵌套配置字段，但任何路径段都不得为 __proto__、constructor 或 prototype；设置流程会拒绝这些名称。

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

每个字段提示可以包括：

contracts 参考

仅将 contracts 用于 OpenClaw 无需导入插件运行时即可读取的静态能力所有权元数据。

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

每个列表都是可选的：

contracts.embeddedExtensionFactories 保留用于内置的 Codex app-server 专用扩展工厂。内置工具结果转换应改为声明 contracts.agentToolResultMiddleware，并通过 api.registerAgentToolResultMiddleware(...) 注册。仅当显式启用且仅针对其在 contracts.agentToolResultMiddleware 中声明的运行时，已安装插件才可使用同一中间件接入点。

需要宿主可信工具前策略层级的已安装插件，必须在 contracts.trustedToolPolicies 中声明每个已注册的本地 ID，并且必须被显式启用。内置插件保留现有可信策略路径，但策略 ID 未声明的已安装插件会在注册前被拒绝。策略 ID 的作用域限定于注册该 ID 的插件，因此两个插件均可声明并注册 workflow-budget；但单个插件不得重复注册同一本地 ID。

运行时 api.registerTool(...) 注册必须与 contracts.tools 匹配。工具发现使用此列表，仅加载能够拥有所请求工具的插件运行时。

实现 resolveExternalAuthProfiles 的提供商插件应声明 contracts.externalAuthProviders；未声明的外部身份验证钩子会被忽略。

同时实现 resolveUsageAuth 和 fetchUsageSnapshot 的提供商插件，应在 contracts.usageProviders 中声明每个自动发现的提供商 ID。用量发现会在加载运行时代码前读取此契约，然后仅加载声明的所有者，并在加载后验证这两个钩子。

通用嵌入提供商应为通过 api.registerEmbeddingProvider(...) 注册的每个适配器声明 contracts.embeddingProviders。可复用向量生成应使用通用契约，包括供记忆搜索使用的提供商。contracts.memoryEmbeddingProviders 是已弃用的记忆专用兼容机制，仅在现有提供商迁移到通用嵌入提供商接入点期间保留。

工作节点提供商必须在 contracts.workerProviders 中声明每个 api.registerWorkerProvider(...) ID。核心在调用 provision 前持久化长期意图；提供商在分配外部资源前验证其设置，并且使用同一操作 ID 的重复调用必须采用同一租约。核心还会持久化经过验证的设置快照，并将其与 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"。它是面向原生插件 HTTP 路由的 API 规范门控，这些路由有意在进程内分派 Gateway 网关控制平面方法；它并非用于防范恶意原生插件的沙箱。仅应将其用于经过严格审核、且已要求 Gateway 网关 HTTP 身份验证的内置或操作员界面。当 Gateway 网关根工作准入关闭时，获得授权的路由仅在同时声明 auth: "gateway" 和路由专用的 gatewayRuntimeScopeSurface: "trusted-operator" 时仍可访问；同一插件中的普通同级路由仍受准入边界限制。这样可以在不向整个插件授予准入绕过权限的情况下，确保暂停状态和恢复功能仍可访问。分派之外的解析和响应塑形应保持范围受限；实质性工作或变更性工作必须通过 Gateway 网关方法分派执行，由其负责准入和权限范围强制执行。

configContracts 参考

对于通用核心辅助函数无需导入插件运行时即可使用的、由清单拥有的配置行为，请使用 configContracts：危险标志检测、SecretRef 迁移目标以及旧版配置路径收窄。

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

每个 dangerousFlags 条目支持：

secretInputs 支持：

mediaUnderstandingProviderMetadata 参考

当媒体理解提供商具有默认模型、自动身份验证回退优先级或原生文档支持，且通用核心辅助函数需要在运行时加载前获知这些信息时，请使用 mediaUnderstandingProviderMetadata。相关键还必须在 contracts.mediaUnderstandingProviders 中声明。

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

每个提供商条目可包含：

channelConfigs 参考

当渠道插件需要在运行时加载前获取低成本的配置元数据时，请使用 channelConfigs。对于已配置的外部渠道，如果没有可用的设置入口，或者 setup.requiresRuntime: false 声明设置不需要运行时，只读渠道设置/状态发现功能可以直接使用此元数据。

channelConfigs 是插件清单元数据，而不是新的顶层用户配置部分。用户仍在 channels.<channel-id> 下配置渠道实例。OpenClaw 会读取清单元数据，以便在插件运行时代码执行前确定哪个插件拥有已配置的渠道。

对于渠道插件，configSchema 和 channelConfigs 描述不同的路径：

• configSchema 验证 plugins.entries.<plugin-id>.config
• channelConfigs.<channel-id>.schema 验证 channels.<channel-id>

声明了 channels[] 的非内置插件还应声明对应的 channelConfigs 条目。缺少这些条目时，OpenClaw 仍可加载插件，但在插件运行时执行前，冷路径配置架构、设置和 Control UI 表面无法获知该渠道所拥有的选项结构。

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled 和 nativeSkillsAutoEnabled 可以为渠道运行时加载前执行的命令配置检查声明静态 auto 默认值。内置渠道也可以通过 package.json#openclaw.channel.commands 发布相同的默认值，并与其由软件包拥有的其他渠道目录元数据放在一起。

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

每个渠道条目可包含：

替换另一个渠道插件

当另一个插件也可以提供同一个渠道 ID，而你的插件应成为该渠道的首选所有者时，请使用 preferOver。常见情况包括插件 ID 已重命名、独立插件取代内置插件，或者维护中的分支为了配置兼容性而保留相同的渠道 ID。

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

配置 channels.chat 后，OpenClaw 会同时考虑渠道 ID 和首选插件 ID。如果低优先级插件仅因其为内置插件或默认启用而被选中，OpenClaw 会在有效运行时配置中禁用该插件，从而确保由一个插件拥有该渠道及其工具。显式用户选择仍然优先：如果用户显式启用了两个插件（通过 plugins.allow 或实质性的 plugins.entries 配置），OpenClaw 会保留该选择并报告渠道/工具重复诊断，而不会静默更改请求的插件集合。

请将 preferOver 的范围限制为确实能提供相同渠道的插件 ID。它不是通用优先级字段，也不会重命名用户配置键。

modelSupport 参考

当 OpenClaw 应在插件运行时加载前，根据 gpt-5.6-sol 或 claude-sonnet-4.6 等简写模型 ID 推断你的提供商插件时，请使用 modelSupport。

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

OpenClaw 按以下优先级处理：

• 显式 provider/model 引用使用所属插件的 providers 清单元数据
• modelPatterns 优先于 modelPrefixes
• 如果一个非内置插件和一个内置插件均匹配，则非内置插件优先
• 剩余的歧义会被忽略，直到用户或配置指定提供商

字段：

modelPatterns 条目通过 compileSafeRegex 编译，该函数会拒绝包含嵌套重复的模式（例如 (a+)+$）。未通过安全检查的模式会被静默跳过，与语法无效的正则表达式相同。请保持模式简单，并避免使用嵌套量词。

modelCatalog 参考

当 OpenClaw 应在加载插件运行时前获知提供商模型元数据时，请使用 modelCatalog。它是固定目录行、提供商别名、抑制规则和发现模式的清单所属来源。运行时刷新仍由提供商运行时代码负责，但清单会告知核心何时需要运行时。

{  "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 参与模型目录规划中的提供商归属查找。别名目标必须是由同一插件拥有的顶层提供商。当按提供商筛选的列表使用别名时，OpenClaw 无需加载提供商运行时，即可读取归属清单并应用别名的 API/基础 URL 覆盖。别名不会扩展未筛选的目录列表；宽泛列表只会输出归属方的规范提供商条目。

suppressions 取代旧的提供商运行时 suppressBuiltInModel 钩子。仅当提供商归此插件所有，或被声明为指向已归属提供商的 modelCatalog.aliases 键时，抑制条目才会生效。在模型解析期间，不再调用运行时抑制钩子。

提供商字段：

模型字段：

抑制字段：

不要在 modelCatalog 中放置仅供运行时使用的数据。仅当清单条目足够完整，使按提供商筛选的列表和选择器界面可以跳过注册表/运行时发现时，才使用 static。当清单条目可作为有用的可列出种子或补充，但后续刷新/缓存还可添加更多条目时，使用 refreshable；可刷新条目本身并非权威数据。当 OpenClaw 必须加载提供商运行时才能获知列表时，使用 runtime。

modelIdNormalization 参考

使用 modelIdNormalization 执行开销较低且由提供商负责的模型 ID 清理，并且必须在提供商运行时加载前完成。这样可将短模型名称、提供商本地旧版 ID 和代理前缀规则等别名保留在归属插件的清单中，而不是放入核心模型选择表。

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

提供商字段：

providerEndpoints 参考

使用 providerEndpoints 进行端点分类，这是通用请求策略在提供商运行时加载前必须获知的信息。核心仍负责定义每个 endpointClass 的含义；插件清单负责主机和基础 URL 元数据。

已正式外置的提供商插件不包含在核心发行包中，因此在安装前无法看到它们的清单。它们的 providerEndpoints 还必须镜像到 scripts/lib/official-external-provider-catalog.json，以便在没有插件时端点分类仍可正常工作；契约测试会强制校验此镜像。

端点字段：

providerRequest 参考

当通用请求策略需要低开销的请求兼容性元数据，而又不希望加载提供商运行时时，请使用 providerRequest。特定于行为的载荷重写应保留在提供商运行时钩子或共享的提供商系列辅助函数中。

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

提供商字段：

secretProviderIntegrations 参考

当插件可以发布可复用的 SecretRef Exec 提供商预设时，请使用 secretProviderIntegrations。OpenClaw 会在插件运行时加载之前读取此元数据，将插件所有权存储在 secrets.providers.<alias>.pluginIntegration 中，并将实际的密钥解析交给 SecretRef 运行时。预设仅对内置插件以及从托管插件安装根目录中发现的已安装插件公开，例如通过 git 和 ClawHub 安装的插件。

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

映射键是集成 ID。如果省略 providerAlias，OpenClaw 会使用集成 ID 作为 SecretRef 提供商别名。提供商别名必须符合常规的 SecretRef 提供商别名模式，例如 team-secrets 或 onepassword-work。

当操作员选择该预设时，OpenClaw 会写入类似以下内容的提供商引用：

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

在启动或重新加载时，OpenClaw 会通过加载当前插件清单元数据来解析该提供商，检查所属插件是否已安装且处于活动状态，并根据清单具体化 Exec 命令。禁用或移除插件会撤销活动 SecretRef 所使用的该提供商。需要独立 Exec 配置的操作员仍可直接编写包含手动 command/args 的提供商。

目前仅支持 source: "exec" 预设。command 必须为 ${node}，且 args[0] 必须是以 ./ 开头、相对于插件根目录的解析器脚本。OpenClaw 会在启动或重新加载时，将其具体化为当前 Node 可执行文件和插件内脚本的绝对路径。--require、--import、--loader、--env-file、--eval 和 --print 等 Node 选项不属于清单预设契约。需要非 Node 命令的操作员可以直接配置独立的手动 Exec 提供商。

对于清单预设，OpenClaw 会根据插件根目录派生 trustedDirs；对于 ${node} 预设，还会包含当前 Node 可执行文件所在目录。清单中编写的 trustedDirs 会被忽略。timeoutMs、noOutputTimeoutMs、maxOutputBytes、jsonOnly、env、passEnv 和 allowInsecurePath 等其他 Exec 提供商选项会原样传递给常规 SecretRef Exec 提供商配置。

modelPricing 参考

当提供商需要在运行时加载之前控制控制平面的定价行为时，请使用 modelPricing。Gateway 网关定价缓存无需导入提供商运行时代码即可读取此元数据。

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

提供商字段：

来源字段：

OpenClaw 提供商索引

OpenClaw 提供商索引是由 OpenClaw 管理的预览元数据，适用于插件可能尚未安装的提供商。它不属于插件清单。插件清单仍是已安装插件的权威来源。提供商索引是一项内部回退契约；当提供商插件未安装时，未来的可安装提供商界面和安装前模型选择器界面将使用它。

目录权威顺序：

1. 用户配置。
2. 已安装插件清单中的 modelCatalog。
3. 通过显式刷新生成的模型目录缓存。
4. OpenClaw 提供商索引预览行。

提供商索引不得包含密钥、启用状态、运行时钩子或实时的账户特定模型数据。其预览目录使用与插件清单相同的 modelCatalog 提供商行结构，但应仅包含稳定的显示元数据；除非有意让 api、baseUrl、定价或兼容性标志等运行时适配器字段与已安装插件清单保持一致。支持实时 /models 发现的提供商应通过显式模型目录缓存路径写入刷新的行，而不是让常规列表展示或新手引导调用提供商 API。

对于插件已移出核心或因其他原因尚未安装的提供商，提供商索引条目也可以携带可安装插件元数据。此元数据沿用渠道目录模式：包名称、npm 安装规范、预期完整性值以及低开销的身份验证选项标签，足以显示一个可安装的设置选项。插件安装后，其清单具有优先权，并会忽略该提供商的提供商索引条目。

openclaw doctor --fix 会将一小组封闭的旧版顶层清单能力键迁移到 contracts.*：speechProviders、mediaUnderstandingProviders、imageGenerationProviders 和 tools。这些键以及任何其他能力列表都不再作为顶层清单字段读取；常规清单加载仅识别 contracts 下的这些字段。

清单与 package.json 的区别

这两个文件承担不同的职责：

如果不确定某项元数据应放在哪里，请遵循以下规则：

• 如果 OpenClaw 必须在加载插件代码之前了解它，请将其放入 openclaw.plugin.json
• 如果它涉及打包、入口文件或 npm 安装行为，请将其放入 package.json

影响设备发现的 package.json 字段

部分运行前插件元数据有意放在 package.json 的 openclaw 块中，而不是 openclaw.plugin.json 中。openclaw.bundle 和 openclaw.bundle.json 并非 OpenClaw 插件契约；原生插件必须使用 openclaw.plugin.json 以及下方受支持的 package.json#openclaw 字段。

重要示例：

清单元数据决定运行时加载前，新手引导中会显示哪些提供商/渠道/设置选项。package.json#openclaw.install 告诉新手引导，当用户选择其中某个选项时应如何获取或启用该插件。不要将安装提示移入 openclaw.plugin.json。

对于非内置插件来源，安装和清单注册表加载期间会强制执行 openclaw.install.minHostVersion。无效值会被拒绝；较新但有效的值会使较旧主机跳过外部插件。内置源插件视为与主机检出版本保持一致。

openclaw.install.requiredPlatformPackages 适用于通过可选的平台特定别名提供必需原生二进制文件的 npm 包。请列出每个受支持平台别名对应的裸 npm 包名。在 npm 安装期间，OpenClaw 仅验证锁文件约束与当前主机匹配的已声明别名。如果 npm 报告成功但遗漏了该别名，OpenClaw 会使用全新缓存重试一次；如果别名仍然缺失，则回滚安装。

对于非内置插件来源，包安装期间会强制执行 openclaw.compat.pluginApi。使用它指定构建该包时所依赖的 OpenClaw 插件 SDK/运行时 API 下限。当插件包需要较新的 API，但仍为其他流程保留较低的安装提示时，它可以比 minHostVersion 更严格。默认情况下，OpenClaw 官方版本同步会将现有官方插件的 API 下限提升到对应的 OpenClaw 发布版本，但如果插件包有意支持较旧主机，仅发布插件的版本可以保留较低下限。不要仅将包版本用作兼容性契约。peerDependencies.openclaw 仍是 npm 包元数据；OpenClaw 使用 openclaw.compat.pluginApi 契约作出安装兼容性决策。

如果插件已发布到 ClawHub，官方按需安装元数据应使用 clawhubSpec；新手引导会将其视为首选远程来源，并在安装后记录 ClawHub 制品信息。对于尚未迁移到 ClawHub 的包，npmSpec 仍作为兼容性回退方案。

npm 精确版本固定已由 npmSpec 承担，例如 "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"。官方外部目录条目应将精确规格与 expectedIntegrity 配对，以便当获取的 npm 制品不再与固定版本匹配时，更新流程以失败关闭方式终止。为保持兼容性，交互式新手引导仍提供可信注册表中的 npm 规格，包括裸包名和 dist-tag。目录诊断可以区分精确来源、浮动来源、完整性固定来源、缺少完整性的来源、包名不匹配来源和无效默认选项来源。当存在 expectedIntegrity，但没有可供其固定的有效 npm 来源时，诊断也会发出警告。存在 expectedIntegrity 时，安装/更新流程会强制执行它；省略时，则记录注册表解析结果，但不设置完整性固定值。

当状态、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账户时，渠道插件应提供 openclaw.setupEntry。设置入口应公开渠道元数据，以及可安全用于设置流程的配置、状态和机密信息适配器；网络客户端、Gateway 网关监听器和传输运行时应保留在主扩展入口点中。

运行时入口点字段不会覆盖源入口点字段的包边界检查。例如，openclaw.runtimeExtensions 无法使逃逸到包目录之外的 openclaw.extensions 路径变为可加载。

openclaw.install.allowInvalidConfigRecovery 的适用范围有意保持狭窄。它不会让任意损坏的配置变得可安装。目前，它仅允许安装流程从特定的陈旧内置插件升级故障中恢复，例如缺少内置插件路径，或存在属于同一内置插件的陈旧 channels.<id> 条目。无关的配置错误仍会阻止安装，并引导操作员运行 openclaw doctor --fix。

openclaw.channel.persistedAuthState 是用于微型检查器模块的包元数据：

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

当设置、Doctor、状态或只读存在性流程需要在完整渠道插件加载前进行低开销的是/否身份验证探测时，请使用它。持久化身份验证状态不等同于已配置渠道状态：不要使用此元数据自动启用插件、修复运行时依赖项，或决定是否应加载渠道运行时。目标导出应是一个仅读取持久化状态的小型函数；不要通过完整的渠道运行时桶形导出文件调用它。

openclaw.channel.configuredState 对低开销的仅环境变量已配置检查采用相同结构：

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

当渠道能够根据环境变量或其他少量非运行时输入判断已配置状态时，请使用它。如果检查需要完整的配置解析或实际渠道运行时，请改为将该逻辑保留在插件的 config.hasConfiguredState 钩子中。

设备发现优先级（重复的插件 ID）

OpenClaw 从三个根目录发现插件，并按以下顺序检查：随 OpenClaw 一起提供的内置插件、全局安装根目录（~/.openclaw/extensions）和当前工作区根目录（<workspace>/.openclaw/extensions），此外还包括所有显式的 plugins.load.paths 条目。

如果两个发现结果具有相同的 id，则仅保留优先级最高的清单；优先级较低的重复项会被丢弃，而不会与其并行加载。优先级从高到低如下：

1. 配置选定 — 在 plugins.entries.<id> 中显式固定的路径
2. 与跟踪安装记录匹配的全局安装 — 通过 openclaw plugin install/openclaw plugin update 安装，且 OpenClaw 的安装跟踪能够识别为同一 ID 的插件，即使该 ID 也属于内置插件
3. 内置 — 随 OpenClaw 一起提供的插件
4. 工作区 — 相对于当前工作区发现的插件
5. 任何其他发现的候选项

影响：

• 工作区或全局根目录中未经跟踪的内置插件分叉副本或陈旧副本不会遮蔽内置构建。
• 要覆盖内置插件，可以针对该 ID 运行 openclaw plugin install，使受跟踪的全局安装优先于内置副本；也可以通过 plugins.entries.<id> 固定特定路径，使其凭借配置选定优先级胜出。
• 重复项丢弃操作会记录到日志中，以便 Doctor 和启动诊断指出被丢弃的副本。
• 在诊断中，配置选定的重复项覆盖会被表述为显式覆盖，但仍会发出警告，以确保陈旧分叉和意外遮蔽保持可见。

JSON Schema 要求

• 每个插件都必须提供 JSON Schema，即使它不接受任何配置。
• 可以使用空 Schema（例如 { "type": "object", "additionalProperties": false }）。
• Schema 在读取/写入配置时验证，而不是在运行时验证。
• 使用新配置键扩展或派生内置插件时，请同时更新该插件的 openclaw.plugin.json 中的 configSchema。内置插件的 Schema 采用严格模式，因此，如果在用户配置中添加 plugins.entries.<id>.config.myNewKey，却未将 myNewKey 添加到 configSchema.properties，则会在插件运行时加载前被拒绝。

Schema 扩展示例：

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

验证行为

• 未知的 channels.* 键是错误，除非插件清单声明了该渠道 ID。如果同一 ID 还出现在 plugins.allow、plugins.entries 或 plugins.installs 中（即插件已被引用，但当前无法发现），OpenClaw 会将其降级为警告。
• plugins.entries.<id>、plugins.allow 和 plugins.deny 引用未知插件 ID 时会产生警告（“已忽略过时的配置条目”），而不是错误，因此升级以及插件被删除或重命名不会阻止 Gateway 网关启动。
• plugins.slots.memory 引用未知插件 ID 时是错误，但已知的官方外部插件 memory-lancedb 除外，对它只会发出警告。
• 如果插件已安装，但其清单或 Schema 损坏或缺失，验证将失败，并且 Doctor 会报告该插件错误。
• 如果插件配置存在，但插件已被禁用，配置会保留，并且 Doctor 和日志中会显示警告。

有关完整的 plugins.* Schema，请参阅配置参考。

注意事项

• 原生 OpenClaw 插件必须提供清单，包括从本地文件系统加载的插件。运行时仍会单独加载插件模块；清单仅用于设备发现和验证。
• 原生清单使用 JSON5 解析，因此只要最终值仍是对象，就允许使用注释、尾随逗号和不带引号的键。
• 清单加载器只会读取已记录的清单字段。请避免使用自定义顶层键。
• 插件不需要 channels、providers、cliBackends 或 skills 时，可以省略这些字段。
• providerCatalogEntry 必须保持轻量，不应导入大范围的运行时代码；请将其用于静态提供商目录元数据或范围明确的设备发现描述符，而不是请求时执行。
• 互斥插件类型通过 plugins.slots.* 选择：通过 plugins.slots.memory 选择 kind: "memory"（默认为 memory-core），通过 plugins.slots.contextEngine 选择 kind: "context-engine"（默认为 legacy）。
• 请在此清单中声明互斥插件类型。运行时入口的 OpenClawPluginDefinition.kind 已弃用，仅作为旧版插件的兼容性回退保留。
• 环境变量元数据（setup.providers[].envVars、已弃用的 providerAuthEnvVars 和 channelEnvVars）仅用于声明。状态、审计、cron 投递验证及其他只读界面在将环境变量视为已配置之前，仍会应用插件信任和有效激活策略。
• 对于需要提供商代码的运行时向导元数据，请参阅提供商运行时钩子。
• 如果你的插件依赖原生模块，请记录构建步骤以及包管理器的所有允许列表要求（例如 pnpm allow-build-scripts + pnpm rebuild <package>）。

相关内容