添加能力（贡献者指南）

当 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.imageGenerationModel 用于生成图像。

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

嵌入提供商

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

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

审查检查清单

发布新能力前，请验证：

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

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

相关内容

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