三位一体架构详解 —— 网关层、协议层、智能体系如何协同工作

关键词：分层架构｜ACP 协议｜解耦设计｜Monorepo｜数据流

在第 1 篇中，我们明确了 OpenClaw 的使命：成为连接 AI 大脑与现实世界的工业级智能体网关。但一个系统能否真正支撑复杂生产场景，关键在于其架构是否清晰、模块是否解耦、扩展是否灵活。

OpenClaw 采用了一种被称为“三位一体”（Trinity Architecture）的设计范式，将整个系统划分为三个正交层次：

• 网关层（Gateway Layer）—— 对外连接的“神经末梢”
• 协议层（Protocol Layer）—— 内外通信的“通用语言”
• 智能体系（Agent System）—— 自主决策的“中央大脑”

这三层各司其职、互不耦合，共同构成了一个高内聚、低耦合、可水平扩展的 AI 基础设施。

一、整体数据流：一条消息的旅程

让我们以一条来自 WhatsApp 的用户消息为例，看它如何穿越 OpenClaw 的三层架构：

41f1d8ccc2f7b3310f924fd19ed36a10

🔁 关键点：每一层只与相邻层交互，渠道不知道模型，模型不关心渠道。

二、第一层：网关层（Gateway Layer）—— 多渠道接入中枢

职责

• 监听外部消息（WhatsApp、Telegram、微信等）
• 将原始协议（如 Baileys 事件）标准化
• 提供 RPC 接口供 UI/CLI 调用（如 chat.history, agent.abort）

核心模块

image

设计亮点

• 插件化：每个渠道是一个独立插件，新增 Discord 只需实现 startAccount 接口
• 多账号支持：一个 WhatsApp 插件可同时运行 3 个不同号码
• 状态快照：UI 可实时查看“账号 A 已连接，账号 B 正在重试”

🌐 网关层是 OpenClaw 的“外交官”——它不懂 AI，但能和全世界对话。

三、第二层：协议层（Protocol Layer）—— ACP：智能体的通用语言

为什么需要自研协议？

市面上已有 gRPC、GraphQL、REST，但它们：

• 缺乏对 流式响应（streaming）的原生支持
• 难以表达 工具调用（tool_call）与 人类干预（approval）等 AI 特有语义
• 无法统一 多端（Web/iOS/Android/CLI）

因此，OpenClaw 定义了 ACP（Agent Client Protocol）——一种专为 AI Agent 设计的轻量级 JSON-RPC 变体。

ACP 核心特性

• 双向通信：客户端可发送请求，服务端可主动推送事件（如 agent.lifecycle）
• 强类型 Schema：使用 TypeBox 定义参数结构，前后端共享类型
• 流式支持：assistant.text.delta 事件实现打字机效果
• 幂等性：idempotencyKey 防止重复提交

示例：一条 ACP 消息

{
  "jsonrpc": "2.0",
  "method": "chat.send",
  "params": {
    "sessionKey": "wa:1234567890",
    "message": "列出当前进程",
    "attachments": [],
    "timeoutMs": 60000
  },
  "id": "req_abc123"
}　

📜 协议层是 OpenClaw 的“翻译官”——它让不同方言（渠道）和不同思维（模型）能无障碍沟通。

四、第三层：智能体系（Agent System）—— 自主决策的大脑

职责

• 接收标准化请求
• 调度 LLM 进行推理
• 执行工具调用（Function Calling）
• 管理长期记忆（RAG）
• 处理错误与降级

核心模块

image

设计亮点

• 嵌入式运行：智能体直接运行在网关进程中，零网络延迟
• 弹性推理：自动压缩上下文、切换模型、重试失败
• 工具即能力：AI 通过阅读 SKILL.md 学会使用新工具

🧠 智能体系是 OpenClaw 的“指挥官”——它不碰网络，但能指挥千军万马。

五、Monorepo 结构：支撑三位一体的工程底座

OpenClaw 采用 pnpm workspace + Monorepo 组织代码，清晰分离关注点：

image

这种结构带来三大优势：

1. 共享类型：src/acp/types.ts 可被 ui/ 和 apps/ios/ 同时引用
2. 原子发布：修改协议层，自动触发所有客户端 CI
3. 本地开发：pnpm run dev 同时启动网关 + Web UI

六、解耦的价值：为什么三层架构至关重要？

image

✅ 解耦不是为了复杂，而是为了简单——让每个开发者只需关注自己的一层。

结语：架构即战略

OpenClaw 的“三位一体”架构，本质上是一种面向未来的防御性设计：

• 当 WhatsApp 协议变更，只需更新网关层；
• 当 Claude 停服，智能体系自动切换；
• 当用户要求 Discord 支持，社区可贡献插件而不碰核心。

这种架构不仅支撑了当前的功能，更为十年后的扩展预留了空间。

在下一篇文章中，我们将深入 ACP 协议本身，解析其消息格式、错误码设计与类型安全机制。

✅ 下一篇预告： 第 3 篇：ACP 协议设计哲学 —— 为什么 OpenClaw 选择自研 Agent Client Protocol