Phase 5 / Ep 24: Plugin 管道架构 —— 消息处理的洋葱模型

⏱ 预计阅读 3 分钟 更新于 2026/4/13

🎯 学习目标：理解 Plugin 在消息管道中的"洋葱模型"。

1. 洋葱模型

消息在到达 Agent 之前和响应返回给用户之前，会依次通过所有已注册的 Plugin：

sequenceDiagram
    participant User as 🧑 用户消息
    participant P1 as Plugin A\n📝 日志记录
    participant P2 as Plugin B\n🛡️ 敏感词过滤
    participant P3 as Plugin C\n🏷️ 意图分类
    participant Agent as 🤖 Agent
    participant P4 as Plugin D\n🎨 响应格式化

    User->>P1: ① 消息进入管道
    P1->>P2: ② 记录后传递
    P2->>P2: ③ 检查敏感词
    P2->>P3: ④ 通过后传递
    P3->>Agent: ⑤ 附加意图标签
    Agent->>P4: ⑥ Agent 响应
    P4->>User: ⑦ 格式化后返回用户

2. 管道执行顺序

Plugin 按注册顺序（openclaw.json 中的数组顺序）依次执行：

{
  "plugins": {
    "pipeline": [
      "logger",           // 第 1 个执行
      "content-filter",   // 第 2 个
      "intent-classifier", // 第 3 个
      "response-formatter" // 最后（响应阶段）
    ]
  }
}

3. Plugin Hook 类型

Hook 触发时机 典型用途
onMessage 用户消息到达时 日志、过滤、前处理
beforeAgent 发送给 Agent 前 意图分类、上下文注入
afterAgent Agent 响应后 格式化、翻译、审核
onError 处理出错时 错误日志、降级处理

4. 管道控制

Plugin 可以决定是否将消息继续传递：

  • next()：传递给下一个 Plugin
  • block()：拦截消息，不再传递
  • modify(msg)：修改消息后传递

下节预告： Ep 25，从零开发你的第一个 Plugin——"消息计数器"。