AI大模型深度分析后总结的OpenClaw大龙虾系统架构概览

更多OpenClaw技术文章请阅读原文

本页面内容基于以下源文件生成：

docs/concepts/architecture.md

系统架构总览

Openclaw 采用中心化网关架构，所有消息表面（WhatsApp、Telegram、Slack 等）均由单一长生命周期的 Gateway 守护进程统一管理。控制平面客户端（macOS 应用、CLI、Web UI）与执行节点（macOS/iOS/Android/Headless）均通过 WebSocket 协议接入该网关，实现指令下发、状态同步与事件上报。

核心架构图

外部消息服务
Gateway 核心服务
执行节点
控制平面客户端
WebSocket
WebSocket
WebSocket
WebSocket

role: node
WebSocket

role: node
/openclaw/canvas
/openclaw/a2ui
macOS App
CLI 工具
Web Admin UI
macOS Node
iOS Node
Android Node
Headless Node
WebSocket 服务器

Bind: 127.0.0.1:18789
HTTP 静态服务

Canvas / A2UI
提供商连接管理

Baileys / grammY
事件总线

agent / chat / presence
帧校验器

JSON Schema
WhatsApp
Telegram
Slack
Discord

架构关键点解析

单一网关原则 ：每个主机仅运行一个 Gateway 实例，它是唯一打开 WhatsApp 会话的入口点。这种设计避免了多实例状态冲突，简化了会话管理 (docs/concepts/architecture.md:14-21)。
统一接入层 ：无论是控制平面还是边缘节点，均使用 WebSocket 连接到同一服务端点（默认 127.0.0.1:18789）。节点通过在握手时声明 role: node 来区分身份 (docs/concepts/architecture.md:14-21)。
静态资源集成 ：Gateway 内置 HTTP 服务器，用于托管 Canvas（可编辑的 HTML/CSS/JS）和 A2UI 界面，路径分别为 /__openclaw__/canvas/ 和 /__openclaw__/a2ui/，复用网关端口 (docs/concepts/architecture.md:22-26)。
多提供商适配：Gateway 内部维护与不同消息平台的连接（如 WhatsApp via Baileys, Telegram via grammY），并将这些外部事件统一转换为内部事件流。

核心组件与交互流程

系统由 Gateway 守护进程、客户端和节点三大核心角色构成，它们之间通过严格的 WebSocket 协议进行交互。

Gateway 守护进程

Gateway 是系统的中枢神经，承担了连接维护、协议转换与事件分发的职责。

职责边界：
- 连接维护：持有并管理所有第三方消息平台的会话（如 WhatsApp Socket）。
- API 暴露：提供基于类型的 WebSocket API，支持请求-响应模式与服务端推送事件。
- 安全校验：对入站帧进行 JSON Schema 校验，确保数据格式合法。
- 事件发射 ：主动推送 agent、chat、presence、health、heartbeat、cron 等生命周期与业务事件 (docs/concepts/architecture.md:29-35)。
关键数据结构：
- 请求帧 ：{type:\"req\", id, method, params}
- 响应帧 ：{type:\"res\", id, ok, payload|error}
- 事件帧 ：{type:\"event\", event, payload, seq?, stateVersion?} (docs/concepts/architecture.md:82-87)。
错误处理：
- 首帧非 connect 或非 JSON 格式：直接硬关闭连接。
- Token 校验失败：若配置了 OPENCLAW_GATEWAY_TOKEN，握手时 Token 不匹配则立即断开 (docs/concepts/architecture.md:87-88)。

客户端

客户端包括 macOS 应用、CLI 工具和 Web 管理界面，它们是控制指令的发起者。

职责边界：
- 维护单一 WebSocket 长连接。
- 发起业务请求（如 health, status, send, agent, system-presence）。
- 订阅并处理服务端推送的事件（如 tick, agent, presence, shutdown） (docs/concepts/architecture.md:36-41)。
关键调用链：
1. 建立 WS 连接。
2. 发送 connect 帧进行握手。
3. 发送 type:\"req\" 调用方法。
4. 监听 type:\"event\" 处理异步更新。

节点

节点是执行具体任务的代理，运行在各类设备上。

职责边界：
- 以 role: node 身份连接到 Gateway。
- 在握手时提供设备身份，并声明其 capabilities（能力）和 commands（命令）。
- 执行 Gateway 下发的具体指令，如 canvas.*（画布操作）、camera.*（摄像头控制）、screen.record（录屏）、location.get（定位获取） (docs/concepts/architecture.md:42-48)。
配对机制：
- 配对基于设备身份，审批记录存储在设备配对存储中。这意味着节点必须经过授权才能执行受保护的操作 (docs/concepts/architecture.md:44-46)。

交互时序图

下图展示了客户端、节点与 Gateway 之间的典型交互流程，包括握手、鉴权、请求执行及事件推送。
Provider (WhatsApp/Telegram) Node (Device) Gateway (Daemon) Client (macOS/CLI) Provider (WhatsApp/Telegram) Node (Device) Gateway (Daemon) Client (macOS/CLI) alt $Token Invalid$ WS Connect 1 {type:"connect", params:{auth:{token}}} 2 Validate Token & Schema 3 Close Socket 4 WS Connect 5 {type:"connect", role:"node", caps: $...$ } 6 Register Node Caps 7 {type:"req", method:"agent.run", params:{...}} 8 Dedupe Check (Idempotency Key) 9 Forward Command (e.g., canvas.render) 10 Execution Result 11 Send Message 12 Receipt / Update 13 {type:"res", id, ok:true, payload:{...}} 14 {type:"event", event:"agent", payload:{...}} 15

交互流程关键点

强制握手 ：无论客户端还是节点，连接后的第一帧必须是 connect，否则 Gateway 会强制关闭连接 (docs/concepts/architecture.md:83-84)。
幂等性保障 ：对于具有副作用的请求（如 send, agent），必须包含幂等性键。Gateway 维护一个短时的去重缓存，以安全处理重试 (docs/concepts/architecture.md:89-90)。
事件不重放 ：服务端推送的事件（如 chat, presence）不会重放。如果客户端断连，必须自行处理状态刷新与数据填补 (docs/concepts/architecture.md:138)。

通信协议与鉴权

系统使用自定义的 WebSocket 文本协议，基于 JSON 进行数据交换，并内置了鉴权与校验机制。

线协议规范

传输层：WebSocket 文本帧，Payload 为 JSON。
首帧握手 ：必须发送 connect 指令，包含认证信息（如 Token）。
请求-响应 ：
- 请求：{type:\"req\", id, method, params}
- 响应：{type:\"res\", id, ok, payload|error}
服务端事件 ：{type:\"event\", event, payload, seq?, stateVersion?} (docs/concepts/architecture.md:82-87)。

鉴权与安全

Token 校验 ：若环境变量 OPENCLAW_GATEWAY_TOKEN 或启动参数 --token 被设置，客户端必须在 connect.params.auth.token 中提供匹配的 Token，否则连接会被拒绝 (docs/concepts/architecture.md:87-88)。
节点声明 ：节点连接时必须在 connect 帧中显式声明 role: \"node\"，并列出其 capabilities 和 permissions (docs/concepts/architecture.md:91)。

数据完整性

Schema 校验 ：Gateway 对所有入站帧进行 JSON Schema 校验，防止非法数据导致内部状态异常 (docs/concepts/architecture.md:33)。
去重机制 ：服务端针对写操作维护短生命周期缓存，利用幂等性键防止重复操作 (docs/concepts/architecture.md:89-90)。

远程访问与系统约束

Openclaw 支持通过隧道技术进行远程访问，同时遵循严格的系统不变性以确保稳定性。

远程访问方案

首选方案 ：使用 Tailscale 或 VPN 建立安全网络，客户端直接连接内网 Gateway 地址。
备选方案 ：使用 SSH 隧道 端口转发。
- 示例命令：ssh -N -L 18789:127.0.0.1:18789 user@host
- 该命令将本地 18789 端口映射到远程主机的 Gateway 端口 (docs/concepts/architecture.md:119-124)。
安全增强 ：在远程场景下，建议启用 TLS 及可选的证书固定，以防止中间人攻击 (docs/concepts/architecture.md:127)。

系统不变性

架构设计遵循以下不可违背的原则：

单主机单网关 ：每个主机（Host）必须且只能有一个 Gateway 实例控制 Baileys 会话 (docs/concepts/architecture.md:137)。
强制握手 ：连接建立后的首帧必须是 connect，任何非 JSON 或非 connect 的首帧都会导致连接被硬关闭 (docs/concepts/architecture.md:138)。
事件不重放 ：系统不负责历史事件的缓存与重放，客户端需自行处理断线期间的状态丢失 (docs/concepts/architecture.md:138)。

核心设计决策与取舍

WebSocket 作为唯一传输层：
- 理由：相比 HTTP 轮询，WebSocket 提供了全双工、低延迟的通信通道，非常适合实时消息推送和高频指令交互。
- 取舍：增加了连接管理的复杂性（需处理断线重连），但显著提升了实时性。
单一 Gateway 守护进程模式：
- 理由：集中管理所有第三方会话（如 WhatsApp），避免多客户端竞争导致的会话冲突，简化状态管理。
- 取舍：Gateway 成为单点故障，需通过进程守护（如 systemd/supervisord）保证高可用。
基于角色的连接声明：
- 理由：通过 role: node 区分控制端与执行端，使得 Gateway 可以对节点应用不同的权限策略和配对逻辑。
- 取舍：增加了握手协议的复杂度，但提升了系统的安全性和扩展性。
事件不重放策略：
- 理由：服务端不维护事件历史缓存，极大降低了内存占用和状态管理复杂度。
- 取舍：客户端必须实现状态同步逻辑（如断线后请求全量状态更新），增加了客户端开发负担。
幂等性键强制要求：
- 理由：在网络不稳定的环境下，客户端可能会重发请求。强制要求幂等性键允许服务端去重，保证操作仅执行一次。
- 取舍：客户端需生成并管理唯一 ID，但有效防止了重复发送消息等危险操作。

技术选型

技术组件	用途	选型理由	替代方案
WebSocket	客户端-服务端通信	提供持久化、全双工连接，支持服务端主动推送	HTTP Long Polling, gRPC
Baileys	WhatsApp 适配	无需官方 API，直接操作 WhatsApp Web 协议	Official WhatsApp Business API
grammY	Telegram 适配	现代化的 TypeScript Bot 框架，类型安全	Telegraf, node-telegram-bot-api
JSON Schema	数据校验	标准化的 JSON 结构校验，易于维护和扩展	Protobuf, TypeScript Interfaces
Tailscale	远程组网	零配置、基于 WireGuard 的内网穿透，安全性高	OpenVPN, ZeroTier
SSH Tunnel	远程端口转发	通用性强，无需安装额外客户端，适合临时调试	Ngrok, Frp
Node.js / TS	运行时环境	生态丰富，异步 I/O 模型适合高并发网关	Go, Rust, Python
Canvas Host	动态 UI 托管	允许 Agent 动态生成和修改 HTML/CSS/JS 界面	React Server Components, Static HTML