2.1 架构全景图：Gateway、Agent、Channels、Tools
OpenClaw 的整体架构可以概括为"一个中心，多层协作"：
┌──────────────────────────────────────────────────────────────────┐
│ 用户界面层 │
│ WhatsApp │ Telegram │ Discord │ 微信 │ Slack │ WebChat │
└──────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ Gateway 网关（守护进程） │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 消息路由 │ │ 会话管理 │ │ 认证授权 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 协议转换 │ │ 事件推送 │ │ 节点管理 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└──────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ Agent 运行时 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 上下文组装 │ │ LLM 调用 │ │ 工具执行 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 流式输出 │ │ 会话持久化 │ │ 记忆管理 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└──────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 工具层 │
│ 文件操作 │ 命令执行 │ 网络请求 │ 浏览器控制 │ 消息发送 │
└──────────────────────────────────────────────────────────────────┘
2.2 组件职责与交互关系
Gateway 网关（守护进程）
Gateway 是 OpenClaw 的核心枢纽，作为长期运行的守护进程存在：
主要职责：
- 维护平台连接：管理 WhatsApp、Telegram、Discord 等消息平台的长连接
- 消息路由：将收到的消息路由到正确的 Agent
- 会话管理：维护多渠道、多用户的会话状态
- 认证授权：验证客户端和节点的身份
- 事件推送：向客户端推送消息、状态变更等事件
关键设计：
- 每台主机只有一个 Gateway 实例
- 通过 WebSocket 暴露 API
- 支持 Token 认证和设备配对
Agent 运行时
Agent 运行时是"大脑"的执行引擎：
主要职责：
- 上下文组装：收集系统提示、历史消息、Skills 等构建 LLM 输入
- LLM 调用：与各种 LLM API 交互，支持流式输出
- 工具执行：解析 LLM 的工具调用请求并执行
- 记忆管理：管理短期和长期记忆
Channels 渠道层
渠道是消息的"入口"和"出口"：
interface Channel {
// 渠道标识
id: string;
provider: 'whatsapp' | 'telegram' | 'discord' | 'slack' | ...;
// 发送消息
send(to: string, message: Message): Promise<void>;
// 接收消息（通过 Gateway 推送）
onMessage(callback: (msg: InboundMessage) => void): void;
}
2.3 数据流向：消息如何从用户到 AI 再返回
完整的消息流程
用户在 WhatsApp 发送消息
│
▼
┌───────────────────┐
│ WhatsApp 服务器 │
└───────────────────┘
│ Baileys (WhatsApp Web 协议)
▼
┌───────────────────┐
│ Gateway 网关 │ ← 接收原始消息
└───────────────────┘
│ 解析、转换、路由
▼
┌───────────────────┐
│ 会话管理器 │ ← 查找/创建会话
└───────────────────┘
│
▼
┌───────────────────┐
│ Agent 运行时 │ ← 组装上下文
└───────────────────┘
│
▼
┌───────────────────┐
│ LLM API │ ← 模型推理
└───────────────────┘
│ 可能调用工具
▼
┌───────────────────┐
│ 工具执行器 │ ← 执行工具
└───────────────────┘
│
▼
┌───────────────────┐
│ Agent 运行时 │ ← 处理结果，生成回复
└───────────────────┘
│
▼
┌───────────────────┐
│ Gateway 网关 │ ← 发送回复
└───────────────────┘
│
▼
┌───────────────────┐
│ WhatsApp 服务器 │
└───────────────────┘
│
▼
用户收到回复
2.4 进程模型：Gateway 守护进程、客户端、节点
单进程 vs 多进程
OpenClaw 采用混合进程模型：
| 组件 | 进程类型 | 说明 |
|---|---|---|
| Gateway | 守护进程 | 长期运行，管理所有平台连接 |
| Agent Runtime | 线程/协程 | 在 Gateway 进程内或独立进程 |
| 客户端 | 独立进程 | macOS 应用、CLI、Web 界面 |
| 节点 | 独立进程 | iOS/Android 应用、无头设备 |
客户端连接生命周期
Client Gateway
| |
|──── req:connect ────────>| 首帧必须是 connect
|<───── res (ok) ──────────| 或 res error + close
| |
|<───── event:presence ────| 状态同步
|<───── event:tick ────────| 心跳
| |
|────── req:agent ────────>| 发起 AI 请求
|<───── res:agent ─────────| 确认接受
|<───── event:agent ───────| 流式输出
|<───── res:agent ─────────| 完成
| |
2.5 部署模式：本地、远程、多主机
本地部署（最简单）
# 安装
npm install -g openclaw
# 启动
openclaw gateway start
# 连接 WhatsApp（扫码）
openclaw whatsapp connect
适用于个人使用，所有组件在同一台机器上。
远程部署（服务器）
┌─────────────────┐ ┌─────────────────┐
│ 用户设备 │ │ 云服务器 │
│ (macOS/iOS) │ │ (Gateway) │
│ │ Tailscale │
│ 客户端 ────────┼─────────┼─► Gateway │
│ │ │ │
│ │ │ WhatsApp 连接 │
└─────────────────┘ └─────────────────┘
安全考虑：
- 使用 Tailscale 或 VPN 加密传输
- 配置
OPENCLAW_GATEWAY_TOKEN认证 - 启用设备配对机制
多主机部署
┌─────────────────────────────────────────────────────┐
│ 主控节点 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Gateway │ │ Agent │ │ Canvas │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ 节点 A (手机) │ │ 节点 B (平板) │
│ - 相机 │ │ - 屏幕共享 │
│ - 定位 │ │ - 通知 │
└─────────────────┘ └─────────────────┘
2.6 WebSocket 协议详解
协议格式
所有通信使用 JSON 格式的 WebSocket 帧：
// 请求
interface Request {
type: "req";
id: string; // 唯一标识，用于匹配响应
method: string; // 方法名
params: object; // 参数
}
// 响应
interface Response {
type: "res";
id: string; // 对应请求的 id
ok: boolean; // 是否成功
payload?: object; // 成功时的数据
error?: string; // 失败时的错误信息
}
// 事件
interface Event {
type: "event";
event: string; // 事件名
payload: object; // 事件数据
seq?: number; // 序列号（可选）
}
常用方法
| 方法 | 说明 |
|---|---|
health | 健康检查 |
status | 获取状态 |
send | 发送消息 |
agent | 调用 Agent |
system-presence | 设置在线状态 |
常用事件
| 事件 | 说明 |
|---|---|
tick | 心跳 |
agent | Agent 状态变更 |
presence | 用户在线状态 |
chat | 新消息 |
shutdown | 网关关闭 |
总结
本章介绍了 OpenClaw 的整体架构：
| 组件 | 职责 |
|---|---|
| Gateway | 消息中枢，管理平台连接、路由、认证 |
| Agent Runtime | 执行引擎，处理 LLM 调用和工具执行 |
| Channels | 消息入口/出口，连接各种平台 |
| Tools | 能力扩展，让 Agent 能"做事" |
🦞 下一章预告：我们将深入 Agent 运行时的实现细节，了解上下文组装、工具执行循环和记忆管理的具体机制。
