插件 Manifest 格式

概述

openclaw.plugin.json 是每个原生 OpenClaw 插件必须提供的 manifest 文件，OpenClaw 在执行插件代码之前用它进行配置验证、发现和 UI 提示。

核心要点

两个文件的职责分工：

openclaw.plugin.json：发现、配置验证、认证选择元数据、UI 提示（插件代码运行前必须知道的内容）
package.json：npm 元数据、依赖安装、入口点、安装门控

必填字段：

id：规范插件 id（用于 plugins.entries.<id>）
configSchema：插件配置的 JSON Schema（即使无配置也必须提供空 schema）

重要可选字段：

providers / channels / cliBackends：插件拥有的 Provider/Channel/CLI 后端 id
contracts：静态能力所有权快照（工具、语音、图像生成等）
activation：激活规划器元数据（onStartup、onProviders、onChannels 等）
setup：设置/引导描述符（providers、cliBackends、requiresRuntime）
modelCatalog：声明式模型目录元数据（静态/可刷新/运行时三种发现模式）
modelSupport：模型前缀/模式匹配，用于运行时前推断 Provider
toolMetadata：工具可用性元数据（避免加载运行时）
channelConfigs：Channel 配置 schema 和 UI 提示
uiHints：配置字段的 UI 标签、占位符、敏感性提示

发现优先级（高到低）：

Config 选定（plugins.entries.<id> 显式指定路径）
Bundled（随 OpenClaw 发布）
全局安装（全局插件根目录）
Workspace（当前工作区发现）

activation 字段语义：

onStartup: true — Gateway 启动时加载
onStartup: false — 启动时惰性，仅通过更窄触发器加载
onProviders / onChannels / onCommands — 按需触发加载

contracts 字段（静态能力所有权）：

{
  "contracts": {
    "tools": ["my_tool"],
    "speechProviders": ["my-speech"],
    "imageGenerationProviders": ["my-image"],
    "webSearchProviders": ["my-search"]
  }
}

配置/使用

最小 manifest：

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

验证行为：

未知 channels.* 键是错误
plugins.entries.<id>、plugins.allow、plugins.deny 必须引用可发现的插件 id
插件 manifest 损坏或缺失时验证失败，Doctor 报告插件错误
插件被禁用但配置存在时，保留配置并在 Doctor+日志中显示警告

相关页面

concepts/plugin-building — 插件开发快速上手
concepts/plugin-architecture — 插件能力模型
concepts/plugin-architecture-internals — 内部加载流水线
concepts/plugin-compatibility — 兼容性策略和废弃路径