OpenClaw 插件系统架构解析：Agent 工具注册、配置验证、审批钩子的工程实现

OpenClaw 插件系统架构解析：Agent 工具注册、配置验证、审批钩子的工程实现

OpenClaw 的插件系统在 2026.3.28 版本有了几个关键更新。本文从工程角度分析插件的设计思路、工具注册机制、以及新增的 requireApproval 审批钩子。

插件发现与验证

OpenClaw 插件必须包含 openclaw.plugin.json 清单文件。验证流程：

1. 发现：扫描 ~/.openclaw/plugins/ 目录下的子目录
2. 清单解析：读取 openclaw.plugin.json，提取 id、configSchema、channels、providers
3. Schema 验证：用 JSON Schema 验证配置，发生在配置读写时（不是运行时）
4. 冲突检测：检查工具名、channel ID、plugin ID 是否和内置的冲突

如果清单缺失或 Schema 无效，openclaw doctor 会报错，插件不会加载。

工具注册机制

export default function (api) {
  // 必选工具：所有 Agent 可用
  api.registerTool({
    name: "my_tool",
    description: "描述",
    parameters: { type: "object", properties: { input: { type: "string" } } },
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // 可选工具：需要 allowlist 启用
  api.registerTool(
    { name: "dangerous_op", description: "有副作用", parameters: { type: "object" },
      async execute() { return { content: [{ type: "text", text: "done" }] }; }
    },
    { optional: true }
  );
}

Allowlist 支持三种粒度：

• 工具名："allow": ["dangerous_op"]
• 插件 ID："allow": ["my-plugin"]（启用该插件所有工具）
• 工具组："allow": ["group:plugins"]（启用所有插件工具）

requireApproval 钩子

2026.3.28 新增的 before_tool_call 钩子支持异步审批：

api.hook("before_tool_call", async (context) => {
  if (isDangerous(context.toolName)) {
    await context.requireApproval({
      reason: `将执行 ${context.toolName}(${JSON.stringify(context.params)})`,
      timeout: 60000, // 毫秒
    });
  }
});

工程要点：

• 审批是异步阻塞的，工具执行暂停直到用户确认或超时
• 不同渠道有不同的确认 UI（Telegram 按钮、Discord 交互、/approve 命令）
• /approve 命令同时处理 exec 审批和插件审批，自动 fallback
• 超时后工具调用被取消，不会静默执行

CLI Backend 插件的自动加载

这个版本把 Claude CLI、Codex CLI、Gemini CLI 的推理默认值移到了插件层面。配置 provider 引用后自动发现和加载对应的 CLI Backend 插件，不再需要手动写 plugins.allow。

减少了配置步骤，但代价是插件和 provider 的耦合更紧了。

---

OpenClaw 插件文档：https://docs.openclaw.ai/plugins/manifest
GitHub Release Notes：https://github.com/openclaw/openclaw/releases