添加能力（贡献者指南）

当 OpenClaw 需要嵌入、图像生成、视频生成或未来某种由供应商支持的新共享领域时，请采用此方法。

规则：

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

不要将供应商直接接入渠道或工具。应先定义能力。

何时创建能力

仅当以下条件全部满足时，才创建新能力：

1. 可能有多个供应商能够实现它。
2. 渠道、工具或功能插件应当无需关注供应商即可使用它。
3. 核心需要负责回退、策略、配置或交付行为。

如果相关工作仅适用于某个供应商，并且尚不存在共享契约，请先定义契约。

标准流程

1. 定义类型化的核心契约。
2. 为该契约添加插件注册机制。
3. 添加共享运行时辅助函数。
4. 接入一个真实的供应商插件作为验证。
5. 将功能/渠道使用方迁移到运行时辅助函数。
6. 添加契约测试。
7. 记录面向操作员的配置和所有权模型。

各层职责

提供商和 harness 接缝

当行为属于模型提供商契约而非通用 Agent loop 时，使用提供商钩子。示例包括选择传输方式后的提供商特定请求参数、身份验证配置文件偏好、提示词叠加，以及模型/配置文件故障转移后的后续回退路由。

当行为属于执行某一轮次的运行时时，使用 agent harness 钩子。Harness 可以对明确的协议结果进行分类，例如空输出、只有推理而没有可见输出，或只有结构化计划而没有最终答案，以便外层模型回退策略决定是否重试。

保持这两个接缝精简：

• 核心负责重试/回退策略。
• 提供商插件负责提供商特定的请求、身份验证和路由提示。
• Harness 插件负责运行时特定的尝试分类。
• 第三方插件返回提示，而不直接修改核心状态。

文件检查清单

对于一项新能力，通常需要修改以下区域：

• 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
• 一个或多个内置插件包。
• 配置、文档和测试。

完整示例：图像生成

图像生成遵循标准结构：

1. 核心定义 ImageGenerationProvider。
2. 核心公开 registerImageGenerationProvider(...)。
3. 核心公开 api.runtime.imageGeneration.generate(...) 和 .listProviders(...)。
4. 供应商插件（comfy、deepinfra、fal、google、litellm、microsoft-foundry、minimax、openai、openrouter、vydra、xai）注册由供应商支持的实现。
5. 未来的供应商可以注册同一契约，而无需更改渠道/工具。

该配置键有意与视觉分析路由分开：

• agents.defaults.imageModel 用于分析图像。
• agents.defaults.mediaModels.image 用于生成图像。

应将二者分开，以确保回退和策略保持明确。

嵌入提供商

对于可复用的向量嵌入提供商，请使用 registerEmbeddingProvider(...) / 契约 embeddingProviders。 此契约的适用范围有意设计得比记忆更广： 工具、搜索、检索、导入器或未来的功能插件 都可以使用嵌入，而无需依赖记忆引擎。记忆搜索 也使用通用的 embeddingProviders。

旧版记忆专用注册 API 和 memoryEmbeddingProviders 契约已弃用。所有新的嵌入提供商都应使用 registerEmbeddingProvider 和 embeddingProviders。

审查清单

发布新能力之前，请验证：

• 没有渠道/工具直接导入供应商代码。
• 运行时辅助函数是共享路径。
• 至少有一项契约测试对内置所有权作出断言。
• 配置文档注明了新的模型/配置键。
• 插件文档解释了所有权边界。

如果某个 PR 跳过能力层，并将供应商行为硬编码到渠道/工具中，请退回该 PR，并要求先定义契约。

相关内容

• 插件内部机制 — 能力模型、所有权、加载流水线和运行时辅助函数。
• 构建插件 — 首个插件教程。
• 插件 SDK 概览 — 导入映射和注册 API 参考。
• 创建技能 — 配套的贡献者接口。