08 插件系统

模块目标

理解 OpenClaw 如何在不改核心代码的前提下扩展通道、工具、命令和网关能力。

步骤一：实现拆解（执行链路）

最新版要按“两段式”理解：

1. 元数据阶段：先读 openclaw.plugin.json，建立 manifest registry / metadata snapshot。
2. 规划阶段：根据配置、启用状态、能力归属和 activation hints，决定这次需要哪些插件。
3. 加载阶段：只加载被选中的插件运行时代码。
4. 注册阶段：插件通过 SDK 注册 provider、channel、tool、hook、route、service 等能力。
5. 消费阶段：Gateway、CLI、Agent、通道层从 registry / lookup table 读取能力。

核心入口：

1. 插件发现与 manifest 元数据：src/plugins/manifest-registry.ts
2. 插件加载与运行时计划：src/plugins/loader.ts
3. 插件能力注册：src/plugins/registry.ts
4. 运行时上下文：src/plugins/runtime/index.ts
5. 插件服务生命周期：src/plugins/services.ts
6. 网关整合点：src/gateway/server.impl.ts（loadGatewayPlugins + sidecars）

步骤二：细粒度讲解（小白版）

1. manifest 先做“自我介绍”

• 插件先通过 openclaw.plugin.json 说明：我是谁、我能做什么、我需要什么配置。
• 这一步不应该依赖执行插件业务代码。
• 好处是：配置校验、诊断、UI 展示、启用决策都可以先做。

2. loader 再做“发现 + 验证 + 计划加载”

• 扫描候选插件
• 读取 manifest
• 校验配置 schema
• 处理启用/禁用与来源优先级
• 根据当前命令、通道、模型或 Gateway 启动场景，尽量只加载需要的插件

3. registry 是“能力总线”

• 插件可注册:
  • tools
  • hooks
  • channels
  • providers
  • gateway methods
  • HTTP 路由
  • CLI 命令
  • services
• 重名/冲突会写入 diagnostics

4. runtime 给插件提供“安全可控工具箱”

• 统一提供 config/media/channel/session 等能力
• 插件不直接乱 import 核心内部，减少耦合

5. metadata snapshot 是“当前插件地图”

• Gateway 启动时会构建当前配置对应的插件元数据快照。
• 它记录已安装插件、manifest 诊断、能力归属、owner map 等信息。
• 注意：它是元数据，不是插件运行时代码缓存。

6. services 提供后台能力

• 插件可以有 start/stop
• 网关启动时启动，关闭时逆序停止

你要记住的边界

1. 核心只认通用能力，不应该写死某个插件 ID。
2. 插件生产代码通过 openclaw/plugin-sdk/*、manifest 元数据和公开 barrel 进入核心。
3. 通道、模型、语音、媒体等 owner-specific 行为，优先放在自己的插件里。
4. 旧 hook 仍兼容，但新能力优先用明确 capability registration。