OpenClaw 能力开发手册：为 OpenClaw 新增领域能力的标准流程、分层规则与开发清单

当 OpenClaw 需要新增一个新的领域，比如图像生成、视频生成，或是未来的其他厂商支持的功能领域时，你可以使用本指南。 核心规则：

• 插件 = 所有权边界
• 能力 = 共享的核心契约

这意味着你不应该一开始就直接将某个厂商的代码硬编码到通道或工具中，而是要先定义能力。

什么时候需要创建能力

当以下所有条件都满足时，你就需要创建一个新的能力：

1. 存在多个厂商都有可能实现该功能
2. 通道、工具或功能插件应该可以在不关心具体厂商的情况下消费该功能
3. 核心层需要拥有降级、策略、配置或交付行为

如果当前的工作仅针对单个厂商，且还没有共享的契约，那么请先停下来，先定义契约。

标准开发流程

1. 定义类型化的核心契约
2. 为该契约添加插件注册接口
3. 添加共享的运行时辅助工具
4. 接入一个真实的厂商插件作为验证
5. 将功能 / 通道消费者迁移到运行时辅助工具上
6. 添加契约测试
7. 编写面向运维的配置与所有权模型文档

代码分层规则

核心层负责：

• 请求 / 响应类型
• 提供商注册中心与解析
• 降级行为
• 配置 Schema 以及标签 / 帮助说明
• 运行时辅助工具接口

厂商插件负责：

• 厂商 API 调用
• 厂商鉴权处理
• 厂商专属的请求标准化
• 能力实现的注册

功能 / 通道插件负责：

• 调用 api.runtime.* 或对应的 plugin-sdk/*-runtime 辅助工具
• 永远不要直接调用厂商的实现代码

文件清单

新增一个能力时，你需要修改这些文件：

• src/<capability>/types.ts
• src/<capability>/...registry/runtime.ts
• src/plugins/types.ts
• src/plugins/registry.ts
• src/plugins/captured-registration.ts
• src/plugins/contracts/registry.ts
• src/plugins/runtime/types-core.ts
• src/plugins/runtime/index.ts
• src/plugin-sdk/<capability>.ts
• src/plugin-sdk/<capability>-runtime.ts
• 一个或多个 extensions/<vendor>/...（厂商插件）
• 配置、文档与测试

示例：图像生成

图像生成遵循标准的结构：

1. 核心层定义 ImageGenerationProvider
2. 核心层暴露 registerImageGenerationProvider(...)
3. 核心层暴露 runtime.imageGeneration.generate(...)
4. openai 和 google 插件注册厂商支持的实现
5. 未来的厂商可以注册相同的契约，无需修改通道 / 工具

配置键与视觉分析的路由是相互独立的：

• agents.defaults.imageModel = 分析图像
• agents.defaults.imageGenerationModel = 生成图像

请保持这两者分离，这样降级和策略才能保持明确。

审核清单

在发布新能力之前，请确认：

• 没有通道 / 工具直接导入厂商代码
• 运行时辅助工具是共享的接入路径
• 至少有一个契约测试，用于断言内置的所有权
• 配置文档中说明了新的模型 / 配置键
• 插件文档中解释了所有权边界

如果有 PR 跳过了能力层，直接将厂商行为硬编码到通道 / 工具中，请打回该 PR，先定义契约。