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

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

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

• docs/concepts/architecture.md

系统架构总览

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

核心架构图

#mermaid-svg-FIwRVbfb4Q7ec55O{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-FIwRVbfb4Q7ec55O .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-FIwRVbfb4Q7ec55O .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-FIwRVbfb4Q7ec55O .error-icon{fill:#552222;}#mermaid-svg-FIwRVbfb4Q7ec55O .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-FIwRVbfb4Q7ec55O .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-FIwRVbfb4Q7ec55O .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-FIwRVbfb4Q7ec55O .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-FIwRVbfb4Q7ec55O .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-FIwRVbfb4Q7ec55O .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-FIwRVbfb4Q7ec55O .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-FIwRVbfb4Q7ec55O .marker{fill:#333333;stroke:#333333;}#mermaid-svg-FIwRVbfb4Q7ec55O .marker.cross{stroke:#333333;}#mermaid-svg-FIwRVbfb4Q7ec55O svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-FIwRVbfb4Q7ec55O p{margin:0;}#mermaid-svg-FIwRVbfb4Q7ec55O .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-FIwRVbfb4Q7ec55O .cluster-label text{fill:#333;}#mermaid-svg-FIwRVbfb4Q7ec55O .cluster-label span{color:#333;}#mermaid-svg-FIwRVbfb4Q7ec55O .cluster-label span p{background-color:transparent;}#mermaid-svg-FIwRVbfb4Q7ec55O .label text,#mermaid-svg-FIwRVbfb4Q7ec55O span{fill:#333;color:#333;}#mermaid-svg-FIwRVbfb4Q7ec55O .node rect,#mermaid-svg-FIwRVbfb4Q7ec55O .node circle,#mermaid-svg-FIwRVbfb4Q7ec55O .node ellipse,#mermaid-svg-FIwRVbfb4Q7ec55O .node polygon,#mermaid-svg-FIwRVbfb4Q7ec55O .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-FIwRVbfb4Q7ec55O .rough-node .label text,#mermaid-svg-FIwRVbfb4Q7ec55O .node .label text,#mermaid-svg-FIwRVbfb4Q7ec55O .image-shape .label,#mermaid-svg-FIwRVbfb4Q7ec55O .icon-shape .label{text-anchor:middle;}#mermaid-svg-FIwRVbfb4Q7ec55O .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-FIwRVbfb4Q7ec55O .rough-node .label,#mermaid-svg-FIwRVbfb4Q7ec55O .node .label,#mermaid-svg-FIwRVbfb4Q7ec55O .image-shape .label,#mermaid-svg-FIwRVbfb4Q7ec55O .icon-shape .label{text-align:center;}#mermaid-svg-FIwRVbfb4Q7ec55O .node.clickable{cursor:pointer;}#mermaid-svg-FIwRVbfb4Q7ec55O .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-FIwRVbfb4Q7ec55O .arrowheadPath{fill:#333333;}#mermaid-svg-FIwRVbfb4Q7ec55O .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-FIwRVbfb4Q7ec55O .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-FIwRVbfb4Q7ec55O .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-FIwRVbfb4Q7ec55O .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-FIwRVbfb4Q7ec55O .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-FIwRVbfb4Q7ec55O .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-FIwRVbfb4Q7ec55O .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-FIwRVbfb4Q7ec55O .cluster text{fill:#333;}#mermaid-svg-FIwRVbfb4Q7ec55O .cluster span{color:#333;}#mermaid-svg-FIwRVbfb4Q7ec55O div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-FIwRVbfb4Q7ec55O .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-FIwRVbfb4Q7ec55O rect.text{fill:none;stroke-width:0;}#mermaid-svg-FIwRVbfb4Q7ec55O .icon-shape,#mermaid-svg-FIwRVbfb4Q7ec55O .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-FIwRVbfb4Q7ec55O .icon-shape p,#mermaid-svg-FIwRVbfb4Q7ec55O .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-FIwRVbfb4Q7ec55O .icon-shape rect,#mermaid-svg-FIwRVbfb4Q7ec55O .image-shape rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-FIwRVbfb4Q7ec55O .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-FIwRVbfb4Q7ec55O .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-FIwRVbfb4Q7ec55O :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

外部消息服务

Gateway 核心服务

执行节点

控制平面客户端

WebSocket

WebSocket

WebSocket

WebSocketrole: node

WebSocketrole: node

WebSocketrole: node

WebSocketrole: 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 守护进程、客户端和节点三大核心角色构成，它们之间通过严格的 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)。

• 关键调用链：

• 建立 WS 连接。
• 发送 connect 帧进行握手。
• 发送 type:\\"req\\" 调用方法。
• 监听 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)

#mermaid-svg-L3RZahwsuGOSVsHQ{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-L3RZahwsuGOSVsHQ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-L3RZahwsuGOSVsHQ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-L3RZahwsuGOSVsHQ .error-icon{fill:#552222;}#mermaid-svg-L3RZahwsuGOSVsHQ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-L3RZahwsuGOSVsHQ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-L3RZahwsuGOSVsHQ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-L3RZahwsuGOSVsHQ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-L3RZahwsuGOSVsHQ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-L3RZahwsuGOSVsHQ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-L3RZahwsuGOSVsHQ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-L3RZahwsuGOSVsHQ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-L3RZahwsuGOSVsHQ .marker.cross{stroke:#333333;}#mermaid-svg-L3RZahwsuGOSVsHQ svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-L3RZahwsuGOSVsHQ p{margin:0;}#mermaid-svg-L3RZahwsuGOSVsHQ .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-L3RZahwsuGOSVsHQ text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-L3RZahwsuGOSVsHQ .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-L3RZahwsuGOSVsHQ .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-L3RZahwsuGOSVsHQ .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-L3RZahwsuGOSVsHQ .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-L3RZahwsuGOSVsHQ #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-L3RZahwsuGOSVsHQ .sequenceNumber{fill:white;}#mermaid-svg-L3RZahwsuGOSVsHQ #sequencenumber{fill:#333;}#mermaid-svg-L3RZahwsuGOSVsHQ #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-L3RZahwsuGOSVsHQ .messageText{fill:#333;stroke:none;}#mermaid-svg-L3RZahwsuGOSVsHQ .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-L3RZahwsuGOSVsHQ .labelText,#mermaid-svg-L3RZahwsuGOSVsHQ .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-L3RZahwsuGOSVsHQ .loopText,#mermaid-svg-L3RZahwsuGOSVsHQ .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-L3RZahwsuGOSVsHQ .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-L3RZahwsuGOSVsHQ .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-L3RZahwsuGOSVsHQ .noteText,#mermaid-svg-L3RZahwsuGOSVsHQ .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-L3RZahwsuGOSVsHQ .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-L3RZahwsuGOSVsHQ .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-L3RZahwsuGOSVsHQ .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-L3RZahwsuGOSVsHQ .actorPopupMenu{position:absolute;}#mermaid-svg-L3RZahwsuGOSVsHQ .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-L3RZahwsuGOSVsHQ .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-L3RZahwsuGOSVsHQ .actor-man circle,#mermaid-svg-L3RZahwsuGOSVsHQ line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-L3RZahwsuGOSVsHQ :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

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

交互流程关键点

通信协议与鉴权

系统使用自定义的 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)。

系统不变性

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

核心设计决策与取舍

技术选型