添加新能力（贡献者指南）

概述

OpenClaw 核心开发者向插件系统添加新共享能力的标准流程。适用于需要新增图像生成、视频生成等厂商支持领域时的架构决策和实现步骤。

核心要点

何时创建新能力（三个条件同时满足）：

1. 多个厂商都可能实现它
2. Channel、工具或功能插件应消费它而无需关心厂商
3. 核心需要拥有回退、策略、配置或交付行为

标准实现序列（7步）：

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

代码归属原则：

• 核心：请求/响应类型、Provider 注册表+解析、回退行为、配置 schema、运行时助手表面
• 厂商插件：厂商 API 调用、认证处理、厂商特定请求规范化、能力实现注册
• 功能/Channel 插件：调用 api.runtime.* 或 plugin-sdk/*-runtime 助手，绝不直接调用厂商实现

Provider 与 Harness 钩子的区别：

• Provider 钩子：行为属于模型 Provider 契约（请求参数、认证偏好、提示覆盖）
• Agent Harness 钩子：行为属于执行 turn 的运行时（分类成功但不可用的尝试结果）

需要修改的文件清单：

• src/<capability>/types.ts
• src/<capability>/registry/runtime.ts
• src/plugins/types.ts 和 registry.ts
• src/plugin-sdk/<capability>.ts 和 <capability>-runtime.ts
• 一个或多个 bundled 插件包
• 配置、文档、测试

配置/使用

能力模板（最小模式）：

// 核心契约
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};
 
// 厂商插件注册
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) { return await generateOpenAiVideo(req); },
});
 
// 功能/Channel 插件消费
const clip = await api.runtime.videoGeneration.generate({ prompt: "...", cfg });

契约测试模式：

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

相关页面

• concepts/plugin-architecture — 能力模型、所有权、加载流水线
• concepts/plugin-building — 外部插件开发指南
• concepts/plugin-architecture-internals — 内部机制深度参考