新增能力（贡献者指南）

这是面向 OpenClaw 核心开发者的贡献者指南。如果你在构建外部插件，请参阅 构建插件。

当 OpenClaw 需要一个新领域（如图像生成、视频生成或未来的厂商支持功能）时，使用本指南。

核心规则：

• plugin = 所有权边界
• capability = 共享核心契约

这意味着你不应该从把某个厂商直接接入某个 channel 或 tool 开始——而要从定义 capability 开始。

何时创建新 Capability

当以下所有条件均成立时，才创建新 capability：

1. 多个厂商都可能合理地实现它
2. channels、tools 或 feature plugins 应该能够消费它，而无需关心具体厂商
3. core 需要拥有回退、策略、配置或交付行为

如果工作仅限于单一厂商且尚无共享契约，先停下来定义契约。

标准开发顺序

1. 定义有类型的 core 契约。
2. 为该契约添加插件注册。
3. 添加共享运行时辅助函数。
4. 接入一个真实厂商插件作为验证。
5. 将 feature/channel 消费者迁移到运行时辅助函数。
6. 添加契约测试。
7. 编写面向运维者的配置文档和所有权模型说明。

代码归属

Core：

• 请求/响应类型
• Provider 注册表 + 解析
• 回退行为
• 配置 schema 及标签/帮助文本
• 运行时辅助函数接口

Vendor plugin：

• 厂商 API 调用
• 厂商认证处理
• 厂商特定的请求规范化
• capability 实现的注册

Feature/channel plugin：

• 调用 api.runtime.* 或对应的 plugin-sdk/*-runtime 辅助函数
• 绝不直接调用厂商实现

文件清单

新增 capability 时，预计需要涉及以下区域：

• 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. core 定义 ImageGenerationProvider
2. core 暴露 registerImageGenerationProvider(...)
3. core 暴露 runtime.imageGeneration.generate(...)
4. openai 和 google 插件注册各自的厂商实现
5. 未来的厂商可以注册相同契约，无需修改 channels/tools

配置 key 与视觉分析路由相互独立：

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

保持两者独立，使回退和策略保持明确。

审查清单

在发布新 capability 之前，请验证：

• 没有 channel/tool 直接导入厂商代码
• 运行时辅助函数是唯一的共享路径
• 至少有一个契约测试断言了捆绑所有权
• 配置文档列出了新的 model/config key
• 插件文档说明了所有权边界

如果 PR 跳过 capability 层，直接将厂商行为硬编码到 channel/tool 中，请退回并先定义契约。