插件清单（clawdbot.plugin.json）

适用范围

在以下情况使用本页：

• 您正在构建 Clawdbot 插件
• 您需要提供插件配置架构或调试插件验证错误

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

查看完整插件系统指南：插件。

必需字段

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

必需键：

• id（字符串）：规范插件 ID。
• configSchema（对象）：插件配置的 JSON Schema（内联）。

可选键：

• kind（字符串）：插件类型（例如："memory"）。
• channels（数组）：由此插件注册的渠道 ID（例如：["matrix"]）。
• providers（数组）：由此插件注册的提供商 ID。
• skills（数组）：要加载的技能目录（相对于插件根目录）。
• name（字符串）：插件的显示名称。
• description（字符串）：简短插件摘要。
• uiHints（对象）：用于 UI 呈现的配置字段标签/占位符/敏感标志。
• version（字符串）：插件版本（信息性）。

JSON Schema 要求

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

验证行为

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

注意事项

• 清单对于所有插件都是必需的，包括本地文件系统加载。
• 运行时仍然单独加载插件模块；清单仅用于发现 + 验证。
• 如果您的插件依赖于本机模块，请记录构建步骤和任何 包管理器白名单要求（例如，pnpm allow-build-scripts
  • pnpm rebuild <package>）。