插件清单 (openclaw.plugin.json)

每个插件必须在插件根目录中提供一个 openclaw.plugin.json 文件。 OpenClaw 使用此清单来验证配置,无需执行插件代码。缺失或无效的清单会被视为插件错误,并阻止配置验证。

查看完整的插件系统指南:插件。

必需字段

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

必需的键:

• id (string): 规范的插件 id。
• configSchema (object): 插件配置的 JSON Schema(内联)。

可选的键:

• kind (string): 插件类型(例如:"memory")。
• channels (array): 此插件注册的频道 id(例如:["matrix"])。
• providers (array): 此插件注册的提供者 id。
• skills (array): 要加载的技能目录(相对于插件根目录)。
• name (string): 插件的显示名称。
• description (string): 插件简短描述。
• uiHints (object): 用于 UI 渲染的配置字段标签/占位符/敏感标志。
• version (string): 插件版本(信息性)。

JSON Schema 要求

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

验证行为

• 未知的 channels.* 键是错误,除非频道 id 由插件清单声明。
• plugins.entries.<id>、plugins.allow、plugins.deny 和 plugins.slots.* 必须引用可发现的插件 id。未知 id 是错误。
• 如果插件已安装但其清单或 schema 损坏或缺失,验证将失败,Doctor 会报告插件错误。
• 如果插件配置存在但插件被禁用,配置将被保留,并在 Doctor + 日志中显示警告。

注意事项

• 清单对所有插件都是必需的,包括本地文件系统加载的插件。
• 运行时仍会单独加载插件模块;清单仅用于发现 + 验证。
• 如果您的插件依赖原生模块,请记录构建步骤和任何包管理器允许列表要求(例如,pnpm allow-build-scripts - pnpm rebuild <package>)。