概述
这是 OpenClaw 核心开发者的贡献者指南，说明如何为插件系统添加新的共享能力（capability）。核心原则：plugin = 所有权边界，capability = 共享核心契约。不要直接将 vendor 实现硬编码到 channel 或 tool 中，而是先定义能力契约。
核心功能
- 能力创建判断标准：多个 vendor 可实现、channel/tool/feature 插件需消费、core 需拥有 fallback/policy/config/delivery 行为
- 标准七步流程：定义契约 → 插件注册 → 共享 runtime helper → 实现一个 vendor 插件 → 迁移消费者 → 合约测试 → 文档
- 职责分层：Core 拥有请求/响应类型、provider 注册表、fallback 行为、config schema、runtime helper；Vendor 插件拥有 API 调用、auth、请求归一化；Feature/channel 插件只调用
api.runtime.*，不直接调用 vendor - Provider hooks vs Agent harness hooks：provider hooks 用于模型提供商契约（请求参数、auth profile、prompt overlay）；harness hooks 用于运行时执行 turn（分类 empty/reasoning-only 等结果）
- 典型案例：图像生成能力（
ImageGenerationProvider、registerImageGenerationProvider、runtime.imageGeneration.generate，openai/google/fal/minimax 各自注册实现）
配置/使用
新能力需要修改的文件
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
发布前检查清单
- 无 channel/tool 直接 import vendor 代码
- runtime helper 是共享路径
- 至少一个合约测试断言 bundled 所有权
- config 文档命名新的 model/config key
- 插件文档说明所有权边界
关键设计原则
- Core 拥有重试/fallback 策略
- Provider 插件拥有 provider 特定的请求/auth/路由提示
- Harness 插件拥有运行时特定的 attempt 分类
- 第三方插件返回 hints，不直接修改 core 状态
相关页面
- concepts/tool-plugin — 插件系统安装、配置、Plugin API 完整参考
- concepts/tool-creating-skills — 伴随的 Skill 贡献者指南
- agent-runtimes — Agent 运行时类型，harness 概念