Plugin manifest | Fivey Can Read OpenClaw

先讲这一页到底在解决什么

插件启动前，OpenClaw 先读这个文件

`openclaw.plugin.json` 是 OpenClaw 加载插件代码前必须读的元数据文件。先看 `id` 和 `configSchema`，这是唯二必填字段；最容易漏的是 `providerAuthEnvVars` 和 `providerAuthAliases`——它们让 OpenClaw 在没加载插件代码时就能知道环境变量和认证关系，不配好会导致启动时认证失败。

原文共 33 节，先看 Start Here 路径：/plugins/manifest 查看官方原文

第一站

先分清：卡片负责“认人”，代码负责“干活”

OpenClaw 不想为了问一句“你是不是会图片生成”，就把每个插件的代码都启动一遍。manifest 就像贴在工具箱外面的标签，先让系统便宜、快速、安全地看懂。

manifest 适合放

插件 id、名字、配置 schema、工具和 provider 的所有权、认证提示、模型目录、UI 提示等静态信息。

manifest 不适合放

网络请求、令牌刷新、真实调用模型、复杂转换、读取密钥库这些会“动起来”的工作。

最小例子

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

一句话判断

如果 OpenClaw 需要“还没打开插件盒子”就知道它，那多半属于 manifest。

第二站

顶层字段像一张入园登记表

官方长表其实可以先按用途分成几篮子。这样读 manifest 时，不会被几十个字段吓住。

1

身份

id、name、description、version 像姓名牌和自我介绍。

2

配置

configSchema、uiHints 像表格和填表说明，告诉用户哪些格子能填。

3

能力

contracts、tools、providers、channels 像“我会这些事”的贴纸。

4

接线

activation、preferOver、commandAliases 像把按钮接到正确房间。

第三站

configSchema 是“不能乱填”的格子纸

每个原生插件都要带 JSON Schema，哪怕它没有配置。这样 OpenClaw 在读配置时就能先检查，避免运行时才发现用户多写了奇怪字段。

空配置也要写

没有配置时也写一个严格的空对象 schema，意思是“这里暂时没有可填格子”。

新增配置要同步

如果 fork 或扩展了 bundled plugin，加了 myNewKey 这种新配置，也要同时更新 manifest 的 schema。

为什么严格

严格 schema 像门口尺子：多出来的字段不会偷偷溜进系统，Doctor 也能更早报错。

JSON5

原生 manifest 可以用 JSON5 解析，所以注释、尾逗号这些写法能被接受，但最终必须还是一个对象。

第四站

contracts 像“这件事归我管”的认领牌

很多能力不能靠运行时代码临时宣布，因为系统在选择插件前就要知道谁可能负责。contracts 把这种所有权写成静态清单。

工具

contracts.tools 告诉系统这个插件拥有哪些 agent tool；热路径工具还可以配 toolMetadata，避免为了判断可用性而加载运行时。

生成能力

图片、音频、视频、语音等 provider 可以有 metadata，提前声明认证信号、别名、默认模型和可用线索。

媒体理解

mediaUnderstandingProviderMetadata 说明它能看图片、听音频、读文档，核心工具不用先启动插件。

小朋友版

像班级值日表：扫地、擦黑板、发作业各有负责人，老师不用每次把全班叫醒再问。

第五站

认证和 setup metadata 像“钥匙在哪里”的提示牌

manifest 可以告诉 setup、onboarding 和控制台：这个 provider 可能需要什么认证方式，哪些环境变量能证明它已经准备好。但它不能真的去联网验钥匙。

A

`providerAuthChoices`

给用户看“你可以怎么登录或提供凭据”的选项。

B

`providerAuthEnvVars`

告诉系统哪些环境变量像钥匙挂钩，但不在这里读取秘密内容。

C

`setup.providers`

给安装和首次配置流程用的便宜描述，帮助用户少走弯路。

D

`authEvidence`

只能做本地、便宜、无网络的证据检查，不能调用 provider API。

第六站

模型相关字段，是给“选模型”铺的路标

当用户写 gpt-5.5、sonnet-4.6 或某个代理模型名时，OpenClaw 要尽早判断可能该找哪个 provider。manifest 里的模型字段就是这些路标。

modelSupport

用前缀或正则提示“哪些模型名大概归我”。

modelCatalog

放固定模型目录、别名、隐藏规则和发现模式，运行时刷新仍由 provider 代码负责。

modelIdNormalization

把短名、旧名、代理前缀整理成 provider 真正认识的名字。

modelPricing

给 Gateway 定价缓存提供便宜元数据，让价格行为不用依赖 provider 运行时先加载。

第七站

channelConfigs 和 preferOver，像给频道安排唯一负责人

频道插件经常有配置、替换、迁移问题。manifest 可以提前说明某个 channel id 应该由谁负责，避免两个插件同时抢同一扇门。

channelConfigs

描述频道实例配置的形状。用户仍然在 channels.<channel-id> 下配置，manifest 只是告诉系统谁能读懂它。

preferOver

当新插件替代旧插件、fork 保持同一 channel id、或 standalone 插件优先于 bundled 插件时，用它说明优先级。

显式配置优先

如果用户明确启用了某个插件，系统会尊重这个选择；manifest 只帮助默认和自动选择更稳。

记忆钩子

这像两位老师都能管同一间教室时，校门口名单先写清今天到底谁值班。

第八站

发现顺序决定“同名卡片谁算数”

如果多个地方发现了同一个 plugin id，OpenClaw 不会把它们混成一锅，而是保留优先级最高的那张 manifest。

1

Config-selected

用户在 plugins.entries.<id> 明确钉住的路径优先级最高。

2

Bundled

OpenClaw 自带插件排在全局安装和工作区发现之前。

3

Global install

全局插件根目录里的安装包排在工作区插件之前。

4

Workspace

相对当前工作区发现的插件优先级最低，适合开发和本地实验。

最后记住

写 manifest 的检查口诀

把官方长参考压成一张小抄，可以这样过一遍：

先写身份

id 稳定、全局唯一，描述清楚，不要靠 package 名字猜。

再写格子

configSchema 必须存在，新增配置时同步更新，敏感字段配 UI 提示。

认领能力

工具、provider、channel、hook、setup、QA runner 等 ownership 放到正确字段。

守住边界

manifest 只放便宜静态事实；任何会联网、会读秘密、会真正执行行为的事，都回到运行时代码。