本指南面向 OpenClaw 核心贡献者，用于在插件系统中新增一个需要多供应商支持且核心层负责回退、策略或配置行为的共享能力。如果工作仅涉及单一供应商且尚无共享契约，请先定义契约。标准流程包括：定义类型化核心契约、添加插件注册点、创建共享运行时代理、接入真实供应商插件、迁移消费者、添加契约测试，并编写面向运维的配置和所有权文档。

OpenClaw 新增共享能力：贡献者实现指南

INFO

本文是 OpenClaw 核心开发者的贡献者指南。如果你在构建外部插件，请参考构建插件。关于深层架构参考（能力模型、所有权、加载管道、运行时代理），请参阅插件内部机制。

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

核心原则：

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

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

什么时候需要创建新能力

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

1. 有多个供应商可以合理地实现此能力。
2. 渠道、工具或功能插件应该消费此能力，而不关心具体是哪个供应商。
3. 核心需要控制回退、策略、配置或交付行为。

如果工作只涉及单一供应商且尚无共享契约，请停止并先定义契约。

标准实现流程

1. 定义类型化的核心契约（types）。
2. 为该契约添加插件注册点（registry）。
3. 添加一个共享的运行时代理（runtime helper）。
4. 接入一个真实的供应商插件作为验证。
5. 将功能/渠道的消费者迁移到运行时代理。
6. 添加契约测试（contract tests）。
7. 编写面向运维的配置和所有权文档。

代码归属原则

核心层（Core）:

• 请求/响应类型。
• 供应商注册与解析。
• 回退行为。
• 配置模式（包含嵌套对象、通配符、数组项和组合节点上的 title / description 文档元数据传播）。
• 运行时代理接口。

供应商插件（Vendor plugin）:

• 供应商 API 调用。
• 供应商认证处理。
• 供应商特定的请求归一化。
• 能力实现的注册。

功能/渠道插件（Feature/Channel plugin）:

• 调用 api.runtime.* 或对应的 plugin-sdk/*-runtime 代理。
• 永远不直接调用供应商实现。

提供者钩子与执行器钩子

当行为属于模型提供者契约（而非通用智能体循环）时，使用提供者钩子（Provider hooks）。例如：传输选择后的提供者特定请求参数、认证配置文件偏好、提示覆盖、以及模型/配置文件故障切换后的后续回退路由。

当行为属于执行一次回合的运行时时，使用智能体执行器钩子（Agent harness hooks）。执行器可以对成功但不可用的尝试结果进行分类（如空响应、仅推理响应、仅规划响应），以便外部模型回退策略能做重试决策。

保持两个接缝狭窄：

• 核心层拥有重试/回退策略。
• 提供者插件拥有提供者特定的请求/认证/路由提示。
• 执行器插件拥有运行时特定的尝试结果分类。
• 第三方插件返回提示，而不是直接修改核心状态。

新增文件清单

对于新能力，需要处理以下文件区域：

• 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 plugin packages）。
• 配置、文档和测试。

实战示例：图像生成

图像生成遵循标准模式：

1. 核心定义 ImageGenerationProvider。
2. 核心暴露 registerImageGenerationProvider(...)。
3. 核心暴露 runtime.imageGeneration.generate(...)。
4. openai、google、fal 和 minimax 插件注册供应商实现的版本。
5. 未来供应商无需改动渠道和工具即可注册同一契约。

配置键与视觉分析路由是故意分开的：

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

保持分离，以便回退和策略保持清晰。

嵌入提供者

使用 embeddingProviders 进行可复用的向量嵌入提供者。此契约的适用范围比内存更广：工具、搜索、检索、导入器或未来的功能插件都可以消费嵌入，而无需依赖内存引擎。

对于内存引擎特定的适配器，继续使用 memoryEmbeddingProviders。这些适配器拥有内存索引细节，例如查询/文档拆分、运行时元数据和本地内存引擎设置。除非提供者仅能被内存使用，否则不要使通用嵌入提供者依赖于内存拥有的模块。

交付前检查清单

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

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

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

常见问题

我想接入一个新的图像生成模型，需要从创建新能力开始吗？

是的。如果该模型属于一个新的共享领域（例如视频生成、音频生成等），并且存在多个供应商都能提供，那么必须先定义能力契约。如果只是为现有能力（如图像生成）添加一个新供应商插件，则只需注册该契约的实现即可。

如何判断代码应该放在核心层、供应商插件还是功能插件里？

核心层负责类型定义、注册、回退策略和运行时代理。供应商插件负责该供应商特有的 API 调用、认证和请求归一化。功能/渠道插件只能通过核心层提供的运行时代理来消费能力，绝对不能直接执行供应商代码。

外部插件开发者需要看这篇指南吗？

不需要。如果你是构建外部插件，请参考构建插件教程。这篇指南是为需要新增 OpenClaw 核心能力契约的贡献者准备的。