OpenClaw 架构全景

Architecture layers

系统分层

按职责拆开，OpenClaw 可以看成 6 层：外部消息面、Gateway 控制平面、客户端、节点、插件/SDK、协议与运维设施。

L1

Channels · 外部消息渠道

WhatsApp、Telegram、Slack、Discord、Signal、iMessage、WebChat 等都不是各自独立 bot 进程，而是被 Gateway 统一收口成 messaging surfaces。

Bot API / grammY

Slack

Bolt SDK

Discord

Bot API + Gateway

Signal

signal-cli

Feishu / Matrix / LINE...

plugin-installed separately

L2

Gateway · 控制平面核心

Gateway 是长期运行 daemon，负责维护 provider connections、暴露 typed WS API、按 JSON Schema 校验 inbound frames，并持续发出 agent/chat/presence/health/heartbeat/cron 等事件。

Channels / Nodes / Clients
      ↓
Gateway (daemon, ws://127.0.0.1:18789)
      ├─ typed WS requests / responses
      ├─ server-push events
      ├─ provider connections
      └─ canvas / A2UI / web surfaces

Gateway responsibilities

维护各渠道和 provider 的长连接
承载单一控制面 WS server
对请求协议做 schema-level 验证
广播 presence / tick / agent / shutdown 等事件
提供 canvas host 与控制 UI 的 HTTP 面

L3

Clients · 操作与交互入口

CLI

每个 client 一条 WS 连接，可发 health、status、send、agent、system-presence 等请求。

macOS app

菜单栏控制面，适合本机常驻、远程 gateway 管理、语音入口和调试。

Web admin / Control UI

由 Gateway 直接提供，查看状态、操作会话、连接远端实例。

WebChat

静态 UI，经同一个 WS API 读取 chat history 并发送消息。

L4

Nodes · 设备侧执行层

role = node

macOS / iOS / Android / headless 节点连接到同一个 WS server，但在 connect 阶段声明 role: node 和设备能力。节点暴露的不是聊天 surface，而是设备能力面。

canvas.*

agent-driven visual workspace

camera.*

拍照 / 录像入口

screen.record

屏幕录制

location.get

设备位置能力

节点采用 device-based pairing，审批信息存放在 device pairing store。也就是说，它们被当成具身份的执行设备，而不是普通聊天客户端。

L5

Plugin SDK · 扩展层

从已安装包结构看，OpenClaw 明确导出了大块 ./plugin-sdk/* 能力，包括 core、runtime、routing、provider-setup、account helpers、compat 等，说明插件扩展不是边角功能，而是正式架构面。

plugin-sdk/core plugin-sdk/runtime plugin-sdk/routing plugin-sdk/account-helpers plugin-sdk/compat

这层的意义

渠道接入、provider 适配、运行时共用逻辑、账户解析与路由能力，都被设计成可复用的 SDK 面。也因此 Feishu、Matrix、LINE、Mattermost 这类渠道常以“插件单独安装”的形式存在。

System map

总架构图

这张图把 OpenClaw 的主干关系压到一页里：消息面、控制面、客户端、节点和扩展面都围着 Gateway 组织。

External messaging surfaces

Slack

Discord

Signal

Feishu / Matrix / More

Center

Gateway

Provider connections

维护模型与渠道连接

Typed WS API

req / res / events

Schema validation

JSON Schema 校验

Canvas host / Web UI

同端口提供可视化界面

Clients

CLI

macOS App

Web Admin / Control UI

WebChat

Nodes

macOS node

iOS node

Android node

Headless node

Extension + runtime surfaces

Plugin SDK

Agents

Canvas Host

Control UI

Gateway CLI

Connection lifecycle

连接生命周期

OpenClaw 的控制面连接是严肃协议，不是“连上就发消息”的松散 websocket。先握手，再订阅，再请求，再收流式事件。

1. req:connect：client 首帧必须先 connect。
2. res(ok)：Gateway 返回 hello-ok，并附 presence + health snapshot。
3. event push：之后持续推送 presence、tick 等事件。
4. req:agent：客户端发起 agent 请求。
5. res:agent ack：先回 accepted，再通过 event:agent 流式发过程。
6. final：最终返回包含 runId、status、summary 的完成结果。

Client -> Gateway : req:connect Gateway -> Client : res(ok) + hello-ok Gateway -> Client : event:presence Gateway -> Client : event:tick Client -> Gateway : req:agent Gateway -> Client : res:agent ack { runId, status: accepted } Gateway -> Client : event:agent (streaming) Gateway -> Client : res:agent final { runId, status, summary }

Protocol model

协议与类型系统

TypeBox schemas 定义协议。
JSON Schema 从这些 schema 自动生成。
Swift models 再由 JSON Schema 生成。
握手是 mandatory；首帧不是 connect 就 hard close。

Invariants

架构硬约束

Exactly one Gateway controls a single Baileys session per host。
Handshake is mandatory；非 JSON 或非 connect 首帧直接关闭。
Events are not replayed；客户端错过事件后必须主动刷新状态。

Channels + platforms

渠道与平台面

文档明确写了：每个 channel 都是通过 Gateway 连接。核心是统一路由和统一控制面，而不是为每个应用单独造一套 runtime。

支持的主要聊天渠道

BlueBubbles

运行平台

核心：TypeScript 编写，推荐 Node 运行。
不推荐：Bun 跑 Gateway，尤其 WhatsApp / Telegram 有 bug。
Companion apps：macOS 菜单栏应用，iOS / Android 移动节点。
部署：Gateway 在 macOS / Linux / WSL2 都可常驻。

系统服务模型

macOS：LaunchAgent（ai.openclaw.gateway）
Linux / WSL2：systemd user service
远程接入：优先 Tailscale / VPN，次选 SSH tunnel

What OpenClaw really is

一句话总结

OpenClaw 本体更像一个多入口、多设备、多渠道共享的 agent control plane：Gateway 在中心，聊天应用只是外部 surface，客户端只是操作入口，节点是设备能力执行体，插件 SDK 则把渠道和 runtime 扩展正式化。

一页看懂 OpenClaw 本体架构

核心判断