本页内容
本页内容
构建插件
添加能力(贡献者指南)
当 OpenClaw 需要新的共享领域时使用,例如 embeddings、图像生成、视频生成,或某个未来的供应商支持功能领域。
规则如下:
- plugin = 所有权边界
- capability = 共享的核心契约
不要直接将某个供应商接入通道或工具。请先定义能力。
何时创建能力
仅当以下全部条件都成立时,才创建新的能力:
- 有不止一个供应商很可能实现它。
- 通道、工具或功能插件应当消费它,而无需关心供应商是谁。
- Core 需要拥有回退、策略、配置或交付行为。
如果这项工作仅限于某个供应商,且尚不存在共享契约,则应先定义契约。
标准顺序
- 定义带类型的核心契约。
- 为该契约添加插件注册。
- 添加共享运行时辅助函数。
- 接入一个真实的供应商插件作为证明。
- 将 feature/channel 使用者移至运行时助手上。
- 添加契约测试。
- 记录面向运维的配置和所有权模型。
什么去哪儿
| 层 | 负责内容 |
|---|---|
| 核心 | Request/response型;提供商注册和解析;后备行为;配置模式,其中包含嵌套对象、通配符、数组项和组合节点上传播的 title/description 文档元数据;运行时辅助表面。 |
| 供应商插件 | 厂商 API 调用、厂商认证处理、厂商特定的请求规范化,以及能力实现的注册。 |
| Feature/channel 插件 | 调用 api.runtime.* 或匹配的 plugin-sdk/*-runtime 辅助函数。绝不直接调用厂商实现。 |
Provider 和harness挂钩
当行为属于模型提供者合约而不是通用代理循环时,请使用 provider hooks。示例包括传输选择后特定于提供商的请求参数、身份验证配置文件首选项、提示覆盖以及 model/profile 故障转移后的后续回退路由。
当行为属于执行某个回合的运行时时,请使用 agent harness hooks。harness 可以对显式协议结果进行分类,例如空输出、无可见输出的推理,或没有最终答案的结构化计划,这样外层模型回退策略就可以做出重试决定。
保持两个钩子较窄:
- Core 拥有 retry/fallback 策略。
- Provider 插件拥有特定于提供者的 request/auth/routing 提示。
- Harness 插件负责运行时特定的尝试分类。
- 第三方插件只返回提示信息,而不是直接修改 core 状态。
文件清单
对于新的能力,预计会涉及以下区域:
src/<capability>/types.tssrc/<capability>/...registry/runtime.tssrc/plugins/types.tssrc/plugins/registry.tssrc/plugins/captured-registration.tssrc/plugins/contracts/registry.tssrc/plugins/runtime/types-core.tssrc/plugins/runtime/index.tssrc/plugin-sdk/<capability>.tssrc/plugin-sdk/<capability>-runtime.ts- 一个或多个内置插件包。
- 配置、文档、测试。
工作示例:图像生成
图像生成遵循标准形状:
- Core 定义了
ImageGenerationProvider。 - Core 公开了
registerImageGenerationProvider(...)。 - Core 公开了
api.runtime.imageGeneration.generate(...)和.listProviders(...)。 - 供应商插件(
comfy、deepinfra、fal、google、litellm、microsoft-foundry、minimax、openai、openrouter、vydra、xai)注册供应商支持的实现。 - 未来的供应商注册相同的合同而不改变channels/tools.
配置键有意与视觉分析路由分开:
agents.defaults.imageModel分析图像。agents.defaults.mediaModels.image生成图像。
将它们分开,以便后备方案和策略保持明确。
嵌入提供器
使用 registerEmbeddingProvider(...) / 合约 embeddingProviders 来实现可复用的向量嵌入提供器。该合约的范围有意设计得比 memory 更广:工具、搜索、检索、导入器或未来的功能插件都可以在不依赖 memory 引擎的情况下使用嵌入。Memory 搜索也会使用通用的 embeddingProviders。
旧的内存特定注册 API 和 memoryEmbeddingProviders 合约在 2026 年 8 月迁移窗口后被删除。对每个嵌入提供程序使用 registerEmbeddingProvider 和 embeddingProviders。
审查清单
在发布新的能力之前,请确认:
- 否 channel/tool 直接导入供应商代码。
- 没有通道/工具直接导入供应商代码。
- 运行时辅助函数是共享路径。
- 配置文档命名新的model/config钥匙。
- 插件文档解释了所有权边界。
如果 PR 跳过功能层并将供应商行为硬编码到 channel/tool 中,请将其发回并首先定义合同。