Plugin Manifest（openclaw.plugin.json）

本页仅介绍原生 OpenClaw 插件 manifest。

关于兼容 bundle 布局，请参阅 Plugin Bundles。

兼容 bundle 格式使用不同的 manifest 文件：

• Codex bundle：.codex-plugin/plugin.json
• Claude bundle：.claude-plugin/plugin.json 或默认 Claude 组件布局（无 manifest）
• Cursor bundle：.cursor-plugin/plugin.json

OpenClaw 也会自动检测这些 bundle 布局，但不会对其验证 openclaw.plugin.json schema。

对于兼容 bundle，OpenClaw 目前会读取 bundle 元数据，以及已声明的 skill 根目录、Claude command 根目录、Claude bundle 的 settings.json 默认值，以及与 OpenClaw 运行时期望匹配的 hook pack。

每个原生 OpenClaw 插件必须在插件根目录下提供 openclaw.plugin.json 文件。OpenClaw 使用此 manifest 在不执行插件代码的前提下校验配置。缺失或无效的 manifest 会被视为插件错误，并阻断配置校验。

完整插件系统指南：Plugins。

这个文件的作用

openclaw.plugin.json 是 OpenClaw 在加载插件代码之前读取的元数据。

适合放在这里的内容：

• 插件身份标识
• 配置校验
• 无需启动插件运行时即可获取的认证和引导元数据
• 用于 bundle 兼容接线和契约覆盖的静态能力归属快照
• 配置 UI 提示

不适合放在这里的内容：

• 注册运行时行为
• 声明代码入口点
• 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"],
  "cliBackends": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "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"
      }
    }
  }
}

顶级字段参考

字段	必填	类型	说明
id	是	string	插件的规范 ID，即 plugins.entries.<id> 中使用的 ID。
configSchema	是	object	此插件配置的内联 JSON Schema。
enabledByDefault	否	true	将捆绑插件标记为默认启用。省略或设为非 true 值则默认禁用。
kind	否	"memory" | "context-engine"	声明由 plugins.slots.* 使用的排他性插件种类。
channels	否	string[]	此插件拥有的渠道 ID，用于发现和配置校验。
providers	否	string[]	此插件拥有的 Provider ID。
cliBackends	否	string[]	此插件拥有的 CLI 推理后端 ID，用于从显式配置引用启动时自动激活。
providerAuthEnvVars	否	Record<string, string[]>	不需要加载插件代码即可检查的廉价 Provider 认证环境变量元数据。
providerAuthChoices	否	object[]	用于引导选择器、首选 Provider 解析和简单 CLI flag 接线的廉价认证选择元数据。
contracts	否	object	语音、媒体理解、图像生成、网络搜索和工具归属的静态捆绑能力快照。
skills	否	string[]	要加载的 skill 目录，相对于插件根目录。
name	否	string	可读的插件名称。
description	否	string	在插件界面中显示的简短摘要。
version	否	string	仅供参考的插件版本。
uiHints	否	Record<string, object>	配置字段的 UI 标签、占位符和敏感性提示。

providerAuthChoices 字段参考

每个 providerAuthChoices 条目描述一个引导或认证选择。OpenClaw 在 Provider 运行时加载前读取此内容。

字段	必填	类型	说明
provider	是	string	此选择所属的 Provider ID。
method	是	string	要分发的认证方法 ID。
choiceId	是	string	引导和 CLI 流程使用的稳定认证选择 ID。
choiceLabel	否	string	用户可见标签。省略时回退到 choiceId。
choiceHint	否	string	选择器的简短提示文本。
groupId	否	string	用于分组相关选择的可选组 ID。
groupLabel	否	string	该组的用户可见标签。
groupHint	否	string	该组的简短提示文本。
optionKey	否	string	简单单 flag 认证流程的内部选项键。
cliFlag	否	string	CLI flag 名称，例如 --openrouter-api-key。
cliOption	否	string	完整 CLI 选项格式，例如 --openrouter-api-key <key>。
cliDescription	否	string	CLI 帮助中使用的描述。
onboardingScopes	否	Array<"text-inference" | "image-generation">	此选择应出现在哪些引导界面中。省略时默认为 ["text-inference"]。

uiHints 字段参考

uiHints 是从配置字段名到渲染提示的映射。

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

每个字段提示可包含：

字段	类型	说明
label	string	用户可见的字段标签。
help	string	简短的帮助文本。
tags	string[]	可选的 UI 标签。
advanced	boolean	将字段标记为高级。
sensitive	boolean	将字段标记为密钥或敏感信息。
placeholder	string	表单输入的占位文本。

contracts 字段参考

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

{
  "contracts": {
    "speechProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}

各列表均为可选：

字段	类型	说明
speechProviders	string[]	此插件拥有的语音 Provider ID。
mediaUnderstandingProviders	string[]	此插件拥有的媒体理解 Provider ID。
imageGenerationProviders	string[]	此插件拥有的图像生成 Provider ID。
webSearchProviders	string[]	此插件拥有的网络搜索 Provider ID。
tools	string[]	此插件拥有的 agent 工具名称，用于捆绑契约检查。

顶级的 speechProviders、mediaUnderstandingProviders 和 imageGenerationProviders 已弃用。使用 openclaw doctor --fix 将其移动到 contracts 下；普通 manifest 加载不再将其视为能力归属。

Manifest 与 package.json 的区别

两个文件各司其职：

文件	适合放什么
openclaw.plugin.json	插件代码运行前必须存在的发现、配置校验、认证选择元数据和 UI 提示
package.json	npm 元数据、依赖安装，以及用于入口点、安装或目录元数据的 openclaw 块

不确定某段元数据放哪里时，参考此规则：

• 如果 OpenClaw 在加载插件代码前就需要它，放在 openclaw.plugin.json
• 如果它关于打包、入口文件或 npm 安装行为，放在 package.json

JSON Schema 要求

• 每个插件必须提供 JSON Schema，即使它不接受任何配置。
• 空 schema 是允许的（例如 { "type": "object", "additionalProperties": false }）。
• Schema 在配置读写时校验，不在运行时校验。

校验行为

• 未知的 channels.* 键是错误，除非渠道 ID 已由插件 manifest 声明。
• plugins.entries.<id>、plugins.allow、plugins.deny 和 plugins.slots.* 必须引用可发现的插件 ID。未知 ID 是错误。
• 如果插件已安装但 manifest 或 schema 损坏或缺失，校验失败，Doctor 会报告插件错误。
• 如果插件配置存在但插件已禁用，配置被保留，Doctor 和日志中会出现警告。

完整 plugins.* schema 见配置参考。

注意事项

• Manifest 对原生 OpenClaw 插件是必须的，包括本地文件系统加载。
• 运行时仍单独加载插件模块；manifest 仅用于发现和校验。
• manifest 加载器只读取已记录的 manifest 字段。避免在这里添加自定义顶级键。
• providerAuthEnvVars 是认证探测、env 标记校验等不应为检查 env 名称而启动插件运行时的廉价元数据路径。
• providerAuthChoices 是认证选择选择器、--auth-choice 解析、首选 Provider 映射和简单引导 CLI flag 注册在 Provider 运行时加载前的廉价元数据路径。对于需要 Provider 代码的运行时 wizard 元数据，见Provider 运行时 hooks。
• 排他性插件种类通过 plugins.slots.* 选择。
  • kind: "memory" 由 plugins.slots.memory 选择。
  • kind: "context-engine" 由 plugins.slots.contextEngine 选择（默认：内置 legacy）。
• 当插件不需要时，channels、providers、cliBackends 和 skills 可省略。
• 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器白名单要求（例如 pnpm 的 allow-build-scripts / pnpm rebuild <package>）。