添加能力

当 OpenClaw 需要一个新的共享领域（例如嵌入（embeddings）、图像生成、视频生成，或某个未来的供应商支持的功能领域）时，请使用本指南。

规则：

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

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

何时创建能力¶

仅当所有以下条件都成立时，才创建新的能力：

1. 可能有多个供应商能够实现它。
2. 渠道、工具或功能插件应直接消费它，而无需关心供应商是谁。
3. 核心需要负责回退、策略、配置或交付行为。

如果工作仅涉及供应商本身，且尚不存在共享契约，请先定义契约。

标准流程¶

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

各部分职责¶

Provider 与 harness 接缝¶

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

当行为属于执行轮次（turn）的运行时，请使用 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
• 一个或多个捆绑（bundled）插件包。
• 配置、文档、测试。

示例：图像生成¶

图像生成遵循标准结构：

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

保持这两者分离，以便回退和策略保持明确。

Embedding 提供方¶

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

旧的记忆专用注册 API 和 memoryEmbeddingProviders 契约在其 2026 年 8 月迁移窗口之后已被移除。对于每个 embedding 提供方，请使用 registerEmbeddingProvider 和 embeddingProviders。

审查清单¶

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

• 没有渠道/工具直接导入供应商代码。
• 运行时辅助工具是共享路径。
• 至少有一个契约测试断言捆绑（bundled）所有权。
• 配置文档指明新的模型/配置键名称。
• 插件文档解释所有权边界。

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

相关文档¶

• 插件内部机制 — 能力模型、所有权、加载管道、运行时辅助工具。
• 构建插件 — 第一个插件教程。
• SDK 概述 — 导入映射与注册 API 参考。
• 创建技能 — 配套的贡献者接口。
• 插件架构内部机制 — 加载管道、注册表模型，以及添加能力的指南。