跳转到主要内容

插件清单(openclaw.plugin.json

本页仅适用于原生 OpenClaw 插件清单 关于兼容的 bundle 布局,请参见 Plugin bundles 兼容的 bundle 格式使用不同的清单文件:
  • Codex bundle:.codex-plugin/plugin.json
  • Claude bundle:.claude-plugin/plugin.json,或不带清单的默认 Claude 组件布局
  • Cursor bundle:.cursor-plugin/plugin.json
OpenClaw 也会自动检测这些 bundle 布局,但不会根据此处描述的 openclaw.plugin.json 模式对它们进行校验。 对于兼容的 bundle,只要布局符合 OpenClaw 运行时预期,OpenClaw 当前会读取 bundle 元数据,以及已声明的 skill 根目录、Claude 命令根目录、Claude bundle 的 settings.json 默认值、Claude bundle 的 LSP 默认值,以及受支持的 hook 包。 每个原生 OpenClaw 插件必须插件根目录中提供一个 openclaw.plugin.json 文件。OpenClaw 使用此清单在不执行插件代码的情况下校验配置。缺失或无效的清单会被视为插件错误,并阻止配置校验。 完整的插件系统指南请参见:Plugins。 关于原生能力模型以及当前的外部兼容性指导,请参见: Capability model

这个文件的作用

openclaw.plugin.json 是 OpenClaw 在加载你的插件代码之前读取的元数据。 用途包括:
  • 插件身份标识
  • 配置校验
  • 无需启动插件运行时即可使用的凭证和新手引导元数据
  • 控制平面界面可在运行时加载前检查的轻量激活提示
  • 设置 / 新手引导界面可在运行时加载前检查的轻量设置描述符
  • 应在插件运行时加载前解析的别名和自动启用元数据
  • 应在运行时加载前自动激活插件的模型族简写归属元数据
  • 用于内置兼容性接线和契约覆盖的静态能力归属快照
  • 共享 openclaw qa 主机可在插件运行时加载前检查的轻量 QA 运行器元数据
  • 应在不加载运行时的情况下合并到目录和校验界面中的渠道专用配置元数据
  • 配置 UI 提示
不要用于:
  • 注册运行时行为
  • 声明代码入口点
  • npm 安装元数据
这些应放在你的插件代码和 package.json 中。

最小示例

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

完整示例

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter 提供商插件",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "cliBackends": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["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 密钥",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API 密钥",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API 密钥",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

顶层字段参考

FieldRequiredType含义
idstring规范插件 id。这是在 plugins.entries.<id> 中使用的 id。
configSchemaobject该插件配置的内联 JSON Schema。
enabledByDefaulttrue将内置插件标记为默认启用。省略此字段,或设置为任何非 true 的值,都会使插件默认保持禁用。
legacyPluginIdsstring[]会规范化为此规范插件 id 的旧版 id。
autoEnableWhenConfiguredProvidersstring[]当凭证、配置或模型引用提到这些 provider id 时,应自动启用此插件。
kind"memory" | "context-engine"声明一个供 plugins.slots.* 使用的排他性插件类型。
channelsstring[]由此插件拥有的渠道 id。用于设备发现和配置校验。
providersstring[]由此插件拥有的 provider id。
modelSupportobject由清单拥有的模型族简写元数据,用于在运行时之前自动加载插件。
cliBackendsstring[]由此插件拥有的 CLI 推理后端 id。用于基于显式配置引用的启动自动激活。
commandAliasesobject[]由此插件拥有的命令名称,应在运行时加载前生成具备插件感知能力的配置和 CLI 诊断信息。
providerAuthEnvVarsRecord<string, string[]>OpenClaw 可在不加载插件代码的情况下检查的轻量 provider 凭证环境变量元数据。
providerAuthAliasesRecord<string, string>应复用另一个 provider id 进行凭证查找的 provider id,例如与基础 provider 共享 API 密钥和凭证配置文件的编码 provider。
channelEnvVarsRecord<string, string[]>OpenClaw 可在不加载插件代码的情况下检查的轻量渠道环境变量元数据。用于基于环境变量的渠道设置或凭证界面,以便通用启动 / 配置辅助逻辑能够识别。
providerAuthChoicesobject[]适用于新手引导选择器、首选 provider 解析和简单 CLI 标志接线的轻量凭证选项元数据。
activationobject面向 provider、命令、渠道、路由和能力触发加载的轻量激活提示。仅为元数据;实际行为仍由插件运行时负责。
setupobject设备发现和设置界面可在不加载插件运行时的情况下检查的轻量设置 / 新手引导描述符。
qaRunnersobject[]共享 openclaw qa 主机在插件运行时加载前使用的轻量 QA 运行器描述符。
contractsobject针对语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、web 抓取、web 搜索和工具归属的静态内置能力快照。
channelConfigsRecord<string, object>由清单拥有的渠道配置元数据,会在运行时加载前合并到设备发现和校验界面中。
skillsstring[]要加载的 Skills 目录,相对于插件根目录。
namestring人类可读的插件名称。
descriptionstring显示在插件界面中的简短摘要。
versionstring仅供参考的插件版本。
uiHintsRecord<string, object>配置字段的 UI 标签、占位符和敏感性提示。

providerAuthChoices 参考

每个 providerAuthChoices 条目描述一个新手引导或凭证选项。 OpenClaw 会在 provider 运行时加载前读取这些内容。
FieldRequiredType含义
providerstring此选项所属的 provider id。
methodstring要分发到的凭证方法 id。
choiceIdstring供新手引导和 CLI 流程使用的稳定凭证选项 id。
choiceLabelstring面向用户的标签。如果省略,OpenClaw 会回退到 choiceId
choiceHintstring选择器中的简短辅助文本。
assistantPrioritynumber在智能体驱动的交互式选择器中,值越小排序越靠前。
assistantVisibility"visible" | "manual-only"在智能体选择器中隐藏此选项,但仍允许通过手动 CLI 选择。
deprecatedChoiceIdsstring[]应将用户重定向到此替代选项的旧版选项 id。
groupIdstring用于对相关选项进行分组的可选组 id。
groupLabelstring该分组面向用户的标签。
groupHintstring该分组的简短辅助文本。
optionKeystring用于简单单标志凭证流程的内部选项键。
cliFlagstringCLI 标志名称,例如 --openrouter-api-key
cliOptionstring完整的 CLI 选项形式,例如 --openrouter-api-key <key>
cliDescriptionstringCLI 帮助中使用的描述。
onboardingScopesArray<"text-inference" | "image-generation">此选项应出现在哪些新手引导界面中。如果省略,默认值为 ["text-inference"]

commandAliases 参考

当插件拥有一个运行时命令名称,而用户可能错误地将其放入 plugins.allow,或尝试将其作为根 CLI 命令运行时,请使用 commandAliases。OpenClaw 使用这些元数据进行诊断,而无需导入插件运行时代码。
{
  "commandAliases": [
    {
      "name": "dreaming",
      "kind": "runtime-slash",
      "cliCommand": "memory"
    }
  ]
}
FieldRequiredType含义
namestring属于此插件的命令名称。
kind"runtime-slash"将该别名标记为聊天斜杠命令,而不是根 CLI 命令。
cliCommandstring如存在,用于建议 CLI 操作的相关根 CLI 命令。

activation 参考

当插件可以低成本地声明哪些控制平面事件应在稍后激活它时,请使用 activation

qaRunners 参考

当插件在共享的 openclaw qa 根命令下贡献一个或多个传输运行器时,请使用 qaRunners。保持这些元数据轻量且静态;插件运行时仍然通过轻量的 runtime-api.ts 接口导出的 qaRunnerCliRegistrations 来负责实际的 CLI 注册。
{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "针对一次性 homeserver 运行由 Docker 支持的 Matrix 实时 QA 通道"
    }
  ]
}
FieldRequiredType含义
commandNamestring挂载在 openclaw qa 下的子命令,例如 matrix
descriptionstring当共享主机需要一个占位命令时使用的回退帮助文本。
此块仅为元数据。它不会注册运行时行为,也不会替代 register(...)setupEntry 或其他运行时 / 插件入口点。当前使用方将其作为更广泛插件加载之前的收窄提示,因此缺少激活元数据通常只会带来性能成本;在旧版清单归属回退机制仍然存在时,它不应改变正确性。
{
  "activation": {
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onCapabilities": ["provider", "tool"]
  }
}
FieldRequiredType含义
onProvidersstring[]请求这些 provider id 时应激活此插件。
onCommandsstring[]应激活此插件的命令 id。
onChannelsstring[]应激活此插件的渠道 id。
onRoutesstring[]应激活此插件的路由类型。
onCapabilitiesArray<"provider" | "channel" | "tool" | "hook">控制平面激活规划使用的宽泛能力提示。
当前的实际使用方:
  • 由命令触发的 CLI 规划会回退到旧版的 commandAliases[].cliCommandcommandAliases[].name
  • 由渠道触发的设置 / 渠道规划在缺少显式渠道激活元数据时,会回退到旧版 channels[] 归属
  • 由 provider 触发的设置 / 运行时规划在缺少显式 provider 激活元数据时,会回退到旧版 providers[] 和顶层 cliBackends[] 归属

setup 参考

当设置和新手引导界面需要在运行时加载前读取由插件拥有的轻量元数据时,请使用 setup
{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}
顶层的 cliBackends 仍然有效,并继续描述 CLI 推理后端。setup.cliBackends 是面向控制平面 / 设置流程的、专用于设置的描述符界面,应保持为纯元数据。 当存在时,setup.providerssetup.cliBackends 是用于设置发现的首选“描述符优先”查找界面。如果描述符只能将候选插件范围缩小,而设置流程仍需要更丰富的设置期运行时 hook,请设置 requiresRuntime: true,并保留 setup-api 作为回退执行路径。 由于设置查找可能会执行由插件拥有的 setup-api 代码,因此,规范化后的 setup.providers[].idsetup.cliBackends[] 值在所有已发现插件之间必须保持唯一。归属不明确时会以安全关闭方式失败,而不是根据发现顺序选出一个“胜者”。

setup.providers 参考

FieldRequiredType含义
idstring在设置或新手引导期间暴露的 provider id。请保持规范化 id 在全局唯一。
authMethodsstring[]此 provider 在不加载完整运行时的情况下支持的设置 / 凭证方法 id。
envVarsstring[]通用设置 / 状态界面可在插件运行时加载前检查的环境变量。

setup 字段

FieldRequiredType含义
providersobject[]在设置和新手引导期间暴露的 provider 设置描述符。
cliBackendsstring[]用于“描述符优先”设置查找的设置期后端 id。请保持规范化 id 在全局唯一。
configMigrationsstring[]由此插件设置界面拥有的配置迁移 id。
requiresRuntimeboolean在完成描述符查找后,设置流程是否仍需要执行 setup-api

uiHints 参考

uiHints 是从配置字段名称到小型渲染提示的映射。
{
  "uiHints": {
    "apiKey": {
      "label": "API 密钥",
      "help": "用于 OpenRouter 请求",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}
每个字段提示可包含:
FieldType含义
labelstring面向用户的字段标签。
helpstring简短辅助文本。
tagsstring[]可选的 UI 标签。
advancedboolean将该字段标记为高级项。
sensitiveboolean将该字段标记为密钥或敏感项。
placeholderstring表单输入框的占位文本。

contracts 参考

仅在 OpenClaw 可以在不导入插件运行时的情况下读取静态能力归属元数据时,才使用 contracts
{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}
每个列表都是可选的:
FieldType含义
speechProvidersstring[]此插件拥有的语音 provider id。
realtimeTranscriptionProvidersstring[]此插件拥有的实时转录 provider id。
realtimeVoiceProvidersstring[]此插件拥有的实时语音 provider id。
mediaUnderstandingProvidersstring[]此插件拥有的媒体理解 provider id。
imageGenerationProvidersstring[]此插件拥有的图像生成 provider id。
videoGenerationProvidersstring[]此插件拥有的视频生成 provider id。
webFetchProvidersstring[]此插件拥有的 web 抓取 provider id。
webSearchProvidersstring[]此插件拥有的 web 搜索 provider id。
toolsstring[]此插件拥有的智能体工具名称,用于内置契约检查。

channelConfigs 参考

当渠道插件需要在运行时加载前提供轻量配置元数据时,请使用 channelConfigs
{
  "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 连接",
      "preferOver": ["matrix-legacy"]
    }
  }
}
每个渠道条目可以包含:
FieldType含义
schemaobjectchannels.<id> 的 JSON Schema。每个已声明的渠道配置条目都必须提供。
uiHintsRecord<string, object>该渠道配置区块可选的 UI 标签 / 占位符 / 敏感性提示。
labelstring当运行时元数据尚未准备好时,合并到选择器和检查界面中的渠道标签。
descriptionstring用于检查和目录界面的简短渠道描述。
preferOverstring[]在选择界面中,此渠道应优先于其后的旧版或较低优先级插件 id。

modelSupport 参考

当 OpenClaw 应在插件运行时加载前,根据简写模型 id(如 gpt-5.4claude-sonnet-4.6)推断你的 provider 插件时,请使用 modelSupport
{
  "modelSupport": {
    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],
    "modelPatterns": ["^computer-use-preview"]
  }
}
OpenClaw 按以下优先级处理:
  • 显式的 provider/model 引用使用所属 providers 清单元数据
  • modelPatterns 优先于 modelPrefixes
  • 如果一个非内置插件和一个内置插件都匹配,则非内置插件优先
  • 剩余的歧义会被忽略,直到用户或配置明确指定 provider
字段:
FieldType含义
modelPrefixesstring[]使用 startsWith 对简写模型 id 进行匹配的前缀。
modelPatternsstring[]在移除 profile 后缀后,用于匹配简写模型 id 的正则表达式源码。
旧版顶层能力键已弃用。请使用 openclaw doctor --fixspeechProvidersrealtimeTranscriptionProvidersrealtimeVoiceProvidersmediaUnderstandingProvidersimageGenerationProvidersvideoGenerationProviderswebFetchProviderswebSearchProviders 移动到 contracts 下;正常的清单加载不再将这些顶层字段视为能力归属。

清单与 package.json 的区别

这两个文件承担不同职责:
File用途
openclaw.plugin.json设备发现、配置校验、凭证选项元数据,以及必须在插件代码运行前存在的 UI 提示
package.jsonnpm 元数据、依赖安装,以及用于入口点、安装门控、设置或目录元数据的 openclaw 配置块
如果你不确定某条元数据应该放在哪里,请使用以下规则:
  • 如果 OpenClaw 必须在加载插件代码之前知道它,就放在 openclaw.plugin.json
  • 如果它与打包、入口文件或 npm 安装行为有关,就放在 package.json

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

某些运行时前的插件元数据,刻意放在 package.jsonopenclaw 配置块下,而不是 openclaw.plugin.json 中。 重要示例:
Field含义
openclaw.extensions声明原生插件入口点。
openclaw.setupEntry在新手引导和延迟渠道启动期间使用的轻量、仅设置入口点。
openclaw.channel轻量渠道目录元数据,如标签、文档路径、别名和选择说明文本。
openclaw.channel.configuredState轻量“已配置状态”检查器元数据,可在不加载完整渠道运行时的情况下回答“是否已存在仅基于环境变量的设置?”。
openclaw.channel.persistedAuthState轻量持久化凭证检查器元数据,可在不加载完整渠道运行时的情况下回答“是否已经有任何登录状态?”。
openclaw.install.npmSpec / openclaw.install.localPath内置和外部已发布插件的安装 / 更新提示。
openclaw.install.defaultChoice当存在多个安装来源时的首选安装路径。
openclaw.install.minHostVersion最低支持的 OpenClaw 主机版本,使用如 >=2026.3.22 的 semver 下限。
openclaw.install.allowInvalidConfigRecovery当配置无效时,允许一个狭义的内置插件重装恢复路径。
openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen允许仅设置用的渠道界面在启动期间先于完整渠道插件加载。
openclaw.install.minHostVersion 会在安装和清单注册表加载期间强制执行。无效值会被拒绝;值有效但要求更高版本时,该插件会在较旧主机上被跳过。 openclaw.install.allowInvalidConfigRecovery 的适用范围被刻意限制。它不会让任意损坏的配置变得可安装。当前,它只允许安装流程从特定的陈旧内置插件升级失败中恢复,例如缺失的内置插件路径,或同一个内置插件的陈旧 channels.<id> 条目。无关的配置错误仍会阻止安装,并将操作人员引导至 openclaw doctor --fix openclaw.channel.persistedAuthState 是针对一个微型检查模块的包元数据:
{
  "openclaw": {
    "channel": {
      "id": "whatsapp",
      "persistedAuthState": {
        "specifier": "./auth-presence",
        "exportName": "hasAnyWhatsAppAuth"
      }
    }
  }
}
当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前进行轻量的“是 / 否”凭证探测时,请使用它。目标导出应是一个只读取持久化状态的小函数;不要通过完整渠道运行时 barrel 导出它。 openclaw.channel.configuredState 对基于环境变量的轻量已配置检查采用相同的结构:
{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "specifier": "./configured-state",
        "exportName": "hasTelegramConfiguredState"
      }
    }
  }
}
当一个渠道可以通过环境变量或其他轻量、非运行时输入回答已配置状态时,请使用它。如果检查需要完整配置解析或真实渠道运行时,请将该逻辑保留在插件 config.hasConfiguredState hook 中。

JSON Schema 要求

  • 每个插件都必须提供一个 JSON Schema,即使它不接受任何配置。
  • 空 schema 也是可以接受的(例如 { "type": "object", "additionalProperties": false })。
  • Schema 会在配置读取 / 写入时校验,而不是在运行时校验。

校验行为

  • 未知的 channels.* 键会被视为错误,除非该渠道 id 已由某个插件清单声明。
  • plugins.entries.<id>plugins.allowplugins.denyplugins.slots.* 必须引用可发现的插件 id。未知 id 会被视为错误
  • 如果插件已安装,但其清单或 schema 缺失或损坏,校验会失败,Doctor 会报告该插件错误。
  • 如果插件配置存在,但插件处于禁用状态,配置会被保留,并在 Doctor + 日志中显示警告
完整的 plugins.* schema 请参见 Configuration reference

说明

  • 对于原生 OpenClaw 插件,清单是必需的,包括本地文件系统加载的插件。
  • 运行时仍会单独加载插件模块;清单仅用于设备发现和校验。
  • 原生清单使用 JSON5 解析,因此支持注释、尾随逗号和未加引号的键,只要最终值仍然是一个对象即可。
  • 清单加载器只会读取文档中列出的清单字段。避免在这里添加自定义顶层键。
  • providerAuthEnvVars 是用于凭证探测、环境变量标记校验以及类似 provider 凭证界面的轻量元数据路径,这些场景不应仅为了检查环境变量名称而启动插件运行时。
  • providerAuthAliases 允许 provider 变体复用另一个 provider 的凭证环境变量、凭证配置文件、基于配置的凭证和 API 密钥新手引导选项,而无需在核心中硬编码这种关系。
  • channelEnvVars 是用于 shell 环境变量回退、设置提示以及类似渠道界面的轻量元数据路径,这些场景不应仅为了检查环境变量名称而启动插件运行时。
  • providerAuthChoices 是用于凭证选项选择器、--auth-choice 解析、首选 provider 映射以及在 provider 运行时加载前进行简单新手引导 CLI 标志注册的轻量元数据路径。关于需要 provider 代码的运行时向导元数据,请参见 Provider runtime hooks
  • 排他性插件类型通过 plugins.slots.* 进行选择。
    • kind: "memory"plugins.slots.memory 选择。
    • kind: "context-engine"plugins.slots.contextEngine 选择(默认值:内置 legacy)。
  • 当插件不需要 channelsproviderscliBackendsskills 时,可以省略它们。
  • 如果你的插件依赖原生模块,请记录构建步骤以及任何包管理器允许列表要求(例如 pnpm allow-build-scripts
    • pnpm rebuild <package>)。

相关内容