插件架构内部机制

概述

OpenClaw 插件系统的内部实现细节，包括加载流水线、注册表模型、Provider 运行时钩子（40+个）、Gateway HTTP 路由、SDK 导入路径和上下文引擎插件。

核心要点

加载流水线（8步）：

1. 发现候选插件根目录
2. 读取 manifest 和包元数据
3. 拒绝不安全候选（路径逃逸、全局可写、所有权可疑）
4. 规范化插件配置
5. 决定每个候选的启用状态
6. 加载原生模块（bundled 用原生加载器，第三方 TS 用 Jiti 回退）
7. 调用 register(api) 钩子，收集注册到插件注册表
8. 向命令/运行时表面暴露注册表

Manifest 优先行为：

• Manifest 是控制平面的真相来源
• 运行时模块是数据平面（注册实际行为）
• 激活规划器使用 manifest 元数据在加载前缩小候选范围

注册表追踪内容：

• 插件记录（身份、来源、状态、诊断）
• 工具、钩子、Channel、Provider
• Gateway RPC 处理器、HTTP 路由、CLI 注册器
• 后台服务、插件拥有的命令

Provider 运行时钩子（按调用顺序，共 43 个）：

• catalog / applyConfigDefaults — 配置时
• normalizeModelId / normalizeTransport / normalizeConfig — 模型规范化
• resolveConfigApiKey / resolveSyntheticAuth / resolveExternalAuthProfiles — 认证解析
• resolveDynamicModel / prepareDynamicModel — 动态模型解析
• createStreamFn / wrapStreamFn — 流式传输
• prepareRuntimeAuth / refreshOAuth — 运行时认证
• fetchUsageSnapshot — 用量快照
• buildReplayPolicy / sanitizeReplayHistory — 重放策略
• onModelSelected — 模型选中后副作用

缓存边界规则：

• 不缓存：发现结果、manifest 注册表、Provider 所有权查找
• 可缓存：运行时加载器状态、jiti/模块缓存、已安装插件制品

配置/使用

Gateway HTTP 路由注册：

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",  // 或 "gateway"
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

上下文引擎插件注册：

api.registerContextEngine("my-engine", (ctx) => ({
  info: { id: "my-engine", name: "My Engine", ownsCompaction: true },
  async ingest() { return { ingested: true }; },
  async assemble({ messages }) { return { messages, estimatedTokens: 0 }; },
  async compact() { return { ok: true, compacted: false }; },
}));

SDK 核心导入路径：

• openclaw/plugin-sdk/plugin-entry — 插件注册原语
• openclaw/plugin-sdk/channel-core — Channel 入口/构建助手
• openclaw/plugin-sdk/core — 通用共享助手
• openclaw/plugin-sdk/config-schema — 根配置 Zod schema

相关页面

• concepts/plugin-architecture — 公共能力模型和所有权边界
• concepts/plugin-building — 插件开发快速上手
• concepts/plugin-hooks — 插件钩子完整参考
• concepts/plugin-manifest — Manifest 格式参考