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

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

架构关键点解析

1. 单一网关原则：每个主机仅运行一个 Gateway 实例，它是唯一打开 WhatsApp 会话的入口点。这种设计避免了多实例状态冲突，简化了会话管理 (docs/concepts/architecture.md:14-21)。
2. 统一接入层：无论是控制平面还是边缘节点，均使用 WebSocket 连接到同一服务端点（默认 127.0.0.1:18789）。节点通过在握手时声明 role: node 来区分身份 (docs/concepts/architecture.md:14-21)。
3. 静态资源集成：Gateway 内置 HTTP 服务器，用于托管 Canvas（可编辑的 HTML/CSS/JS）和 A2UI 界面，路径分别为 /__openclaw__/canvas/ 和 /__openclaw__/a2ui/，复用网关端口 (docs/concepts/architecture.md:22-26)。
4. 多提供商适配：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 Connect1{type:"connect", params:{auth:{token}}}2Validate Token & Schema3Close Socket4WS Connect5{type:"connect", role:"node", caps:[...]}6Register Node Caps7{type:"req", method:"agent.run", params:{...}}8Dedupe Check (Idempotency Key)9Forward Command (e.g., canvas.render)10Execution Result11Send Message12Receipt / Update13{type:"res", id, ok:true, payload:{...}}14{type:"event", event:"agent", payload:{...}}15

交互流程关键点

1. 强制握手：无论客户端还是节点，连接后的第一帧必须是 connect，否则 Gateway 会强制关闭连接 (docs/concepts/architecture.md:83-84)。
2. 幂等性保障：对于具有副作用的请求（如 send, agent），必须包含幂等性键。Gateway 维护一个短时的去重缓存，以安全处理重试 (docs/concepts/architecture.md:89-90)。
3. 事件不重放：服务端推送的事件（如 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)。

系统不变性

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

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

核心设计决策与取舍

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

技术选型