OpenClaw 的 Capability Cookbook 是给核心开发者看的架构指南，但它对理解 OpenClaw 插件系统非常有价值。核心原则只有一句：plugin 是所有权边界，capability 是共享 core contract。
为什么需要 Capability？
假设要加入图像生成能力。错误做法是：某个 channel 或 tool 直接调用 OpenAI、Google 或其他供应商 API。
这样会导致：
- 供应商逻辑散落在各处
- 后续替换模型困难
- 配置和 fallback 不统一
- 权限和审计难集中管理
- 插件之间互相耦合
正确做法是先定义 capability，再让不同 vendor plugin 实现它。
判断是否该创建 Capability
满足这些条件时应创建 capability：
- 未来可能有多个供应商实现
- channel/tool/feature plugin 都可能消费它
- core 需要统一 fallback、policy、config 或 delivery 行为
如果只是单一供应商的私有功能，可以先放在 vendor plugin 中；一旦出现通用需求，就应该抽象成 capability。
标准开发顺序
- 定义 typed core contract
- 增加 plugin registration
- 增加 shared runtime helper
- 接入一个真实 vendor plugin 作为 proof
- 让 feature/channel consumer 调 runtime helper
- 增加 contract tests
- 补充 operator-facing 文档和配置说明
这套顺序能防止“先写死一个供应商，之后再艰难重构”。
三层分工
Core
负责：
- request/response 类型
- provider registry
- fallback 和 policy
- config schema
- runtime helper
Vendor Plugin
负责：
- 调供应商 API
- 处理供应商认证
- 做 vendor-specific normalization
- 注册 capability provider
Feature/Channel Plugin
负责：
- 调用 runtime helper
- 不直接 import vendor code
- 专注自己的交互和业务场景
image generation 示例
图像生成能力的正确形态：
- core 定义
ImageGenerationProvider - core 提供 provider registry
- runtime 暴露
imageGeneration.generate - OpenAI/Google 插件分别注册实现
- 频道或工具只调用 runtime，不关心供应商是谁
这样未来新增供应商，不需要改频道代码。
架构审查清单
如果一个 PR 新增能力，应检查：
- channel/tool 是否直接 import vendor code
- 是否有共享 contract
- 是否有 runtime helper
- 是否有 provider registry
- 配置项是否清晰
- 是否有 contract tests
- 文档是否说明所有权边界
如果直接把供应商行为写进 channel/tool，应该退回重构。
来源：OpenClaw 官方文档 - Adding Capabilities | 整理：ClaudeEagle