OpenClaw插件开发的 manifest 怎么写：字段含义和配置检查

写 OpenClaw插件开发的 manifest，别把它当 README 的缩略版。openclaw.plugin.json 更像一张冷启动检查表：系统先读它，再决定配置能不能通过、能力归谁、插件是否值得加载。字段写得漂亮没用，关键是能和 package.json、入口文件、运行时代码互相对上。

id 是后续配置的锚点

id 最好短、稳定、不要随版本变化。它会出现在启用配置、诊断输出、插件索引和工具归属里。改 id 等于换了一个插件，旧配置可能变成悬空引用。排查时看到 unknown plugin id、stale config reference 这类提示，先查 id 是否和安装后的 manifest 一致，再查 allowlist 或 entries 里是否还写着旧名字。

name、description、version 更偏展示和包管理，不能代替 id 的判断。发布前建议把 package.json 的包名、version、openclaw 元数据和 manifest 里的 id、version 放在一张检查清单里，避免包已经升级，manifest 仍停在旧版本。

configSchema 决定配置能不能过门

很多加载失败并不是代码坏了，而是配置根本没进运行时。configSchema 用来描述插件允许哪些配置字段。没有配置的插件也建议写严格空对象：type 为 object，additionalProperties 为 false。这样用户误加字段时能尽早报错，而不是让插件带着无效配置运行。

有配置时，schema 要和代码读取路径一一对应。代码读取 config.apiKey，schema 里就要有 apiKey；代码后来加了 baseUrl，schema 也要更新。判断是否写对，看两类证据：校验命令没有 unknown field，运行时 inspect 能看到配置状态符合预期。敏感值不要硬编码进示例文件，改用配置、环境变量或 SecretRef 这类可替换入口。

contracts 要和注册代码互相咬合

contracts 是 manifest 里最容易被低估的字段。工具插件要声明 contracts.tools，Channel 或其他能力也应声明自己的归属。系统靠这些冷元数据发现能力，不必为了看一眼工具名就加载运行时代码。这里漏一项，插件可能已经安装，却不会按你预期暴露能力。

• 运行时代码注册了 tool，contracts.tools 里要有同名项。

• 可选工具还要把 toolMetadata 和注册选项对齐。

• 能力名冲突时，诊断输出比业务日志更可靠。

配置检查不要只盯 JSON 是否合法。JSON 合法只说明能解析，不能说明字段被系统接受。更有价值的检查是：manifest schema 通过、package 入口存在、contracts 与注册结果一致、插件启用状态可见。

activation 和入口路径别凭习惯写

activation.onStartup 适合需要启动时注册能力的插件；纯可选能力要看是否真的需要开机加载。入口路径则要区分开发态和发布态。本地开发可能指向源码或构建输出，给别人安装时更应该指向 dist 里的 JavaScript。路径不存在时，报错通常会直指 entrypoint missing 或 plugin entry not found。

我的检查顺序是从冷到热：先读 manifest，确认 id、schema、contracts；再看 package.json 的 openclaw.extensions 和 compat；接着跑 validate 或 build；成功后才启动 Gateway 做运行时 inspect。这样能把“字段写错”和“代码执行失败”分开处理，少走很多弯路。