英文 Architecture
- 原始链接：https://docs.openclaw.ai/concepts/architecture
- 来源章节：4. 官方文档：核心概念、模型与安全
- 来源小节：无
- 抓取方式：jina:https://r.jina.ai/http://docs.openclaw.ai/concepts/architecture
- 抓取时间：2026-04-05 13:47:10
- 状态：ok
中文内容
网关架构 - OpenClaw
[OpenClaw主页！图片1：深色徽标！图片2：深色徽标](http://docs.openclaw.ai/)
英语
搜索...
⌘K
搜索...
导航
基础知识
网关架构
基础知识
会话和内存
多代理
消息和传递
在此页面上
- 网关架构
- 概述
- 组件和流程
- 网关（守护进程）
- 客户端（mac 应用程序 / CLI / Web 管理）
- 节点（macOS / iOS / Android / headless）
- 网络聊天
- 连接生命周期（单客户端）
- Wire 协议（摘要）
- 配对+本地信任
- 协议类型和代码生成
- 远程访问
- [O
操作快照](http://docs.openclaw.ai/concepts/architecture#operations-snapshot)
基础知识
网关架构
网关架构
概述
- 一个长期存在的 Gateway 拥有所有消息传递界面（通过 Baileys 的 WhatsApp、通过 grammY 的 Telegram、Slack、Discord、Signal、iMessage、WebChat）。
- 控制平面客户端（macOS 应用程序、CLI、Web UI、自动化）通过配置的绑定主机（默认“127.0.0.1:18789”）上的 WebSocket 连接到网关。
- 节点 (macOS/iOS/Android/headless) 也通过 WebSocket 连接，但使用显式的 caps/command 声明
role: node。 - 每台主机一个网关；这是唯一打开 WhatsApp 会话的地方。
- canvas 主机 由网关 HTTP 服务器提供服务：
/__openclaw__/canvas/（代理可编辑 HTML/CSS/JS）/__openclaw__/a2ui/（A2UI 主机）它使用与网关相同的端口（默认18789）。
组件和流程
网关（守护进程）
- 维护提供商连接。
- 公开类型化的 WS API（请求、响应、服务器推送事件）。
- 根据 JSON 模式验证入站帧。
- 发出“agent”、“chat”、“presence”、“health”、“heartbeat”、“cron”等事件。
客户端（mac 应用程序/CLI/Web 管理）
- 每个客户端一个 WS 连接。
- 发送请求（“health”、“status”、“send”、“agent”、“system-presence”）。
- 订阅事件（
tick、agent、presence、shutdown）。
节点（macOS / iOS / Android / 无头）
- 使用“角色：节点”连接到同一 WS 服务器。
- 在
connect中提供设备标识；配对是基于设备（角色“节点”），批准存在于设备配对存储中。 - 公开“canvas.”、“camera.”、“screen.record”、“location.get”等命令。
协议详细信息：
网络聊天
- 使用 Gateway WS API 进行聊天历史记录和发送的静态 UI。
- 在远程设置中，通过与其他客户端相同的 SSH/Tailscale 隧道进行连接。
连接生命周期（单个客户端）
有线协议（摘要）
-
传输：WebSocket、带有 JSON 有效负载的文本帧。
-
第一帧必须是
connect。 -
握手后：
- 请求：
{type:"req", id, method, params}→{type:"res", id, ok, Payload|error} - 事件：
{type:"event", event, payload, seq?, stateVersion?}
- 请求：
-
hello-ok.features.methods/events是发现元数据，而不是每个可调用帮助器路由的生成转储。 -
共享秘密身份验证使用
connect.params.auth.token或connect.params.auth.password，具体取决于配置的网关身份验证模式。 -
身份承载模式，例如 Tailscale Serve (
gateway.auth.allowTailscale: true) 或非环回gateway.auth.mode: "trusted-proxy"满足请求标头的身份验证，而不是connect.params.auth.*。 -
Private-ingress
gateway.auth.mode: "none"完全禁用共享秘密身份验证；保持该模式远离公共/不受信任的入口。 -
副作用方法（
send、agent）需要幂等密钥才能安全重试；服务器保留短暂的重复数据删除缓存。 -
节点必须包含
role: "node"以及connect中的上限/命令/权限。
配对+本地信任
- 所有 WS 客户端（操作员 + 节点）都在“连接”上包含设备身份。
- 新设备ID需要配对批准；网关为后续连接颁发设备令牌。
- 直接本地环回连接可以自动批准，以保持同一主机的用户体验流畅。
- OpenClaw 还具有用于可信共享秘密帮助程序流的狭窄后端/容器本地自连接路径。
- Tailnet 和 LAN 连接（包括同一主机 tailnet 绑定）仍然需要明确的配对批准。
- 所有连接都必须签署“connect.challenge”随机数。
- 签名负载
v3还绑定了platform+deviceFamily；网关在重新连接时固定配对元数据，并需要针对元数据更改进行修复配对。 - 非本地连接仍需要明确批准。
- 网关身份验证（
gateway.auth.*）仍然适用于所有连接，本地或远程。
协议类型和代码生成
- TypeBox 模式定义协议。
- JSON 模式是从这些模式生成的。
- Swift 模型是从 JSON Schema 生成的。
远程访问
- 首选：Tailscale 或 VPN。
- 替代方案：SSH 隧道``` ssh -N -L 18789:127.0.0.1:18789 用户@主机
* 相同的握手 + 身份验证令牌适用于隧道。
* 可以在远程设置中为 WS 启用 TLS + 可选固定。
## [](http://docs.openclaw.ai/concepts/architecture#operations-snapshot)
运营快照
* 开始：`openclaw gateway`（前台，记录到标准输出）。
* 健康：WS 上的“健康”（也包含在“hello-ok”中）。
* 监督：launchd/systemd 用于自动重启。
## [](http://docs.openclaw.ai/concepts/architecture#invariants)
不变量
* 每个主机只有一个网关控制一个 Baileys 会话。
* 握手是强制性的；任何非 JSON 或非连接第一帧都是硬关闭。
* 事件不会重播；客户必须刷新空白。
## [](http://docs.openclaw.ai/concepts/architecture#lated)
相关
* [Agent Loop](http://docs.openclaw.ai/concepts/agent-loop) — 详细的代理执行周期
* [网关协议](http://docs.openclaw.ai/gateway/protocol) — WebSocket协议合约
* [Queue](http://docs.openclaw.ai/concepts/queue) — 命令队列和并发
* [Security](http://docs.openclaw.ai/gateway/security) — 信任模型和强化
[代理运行时](http://docs.openclaw.ai/concepts/agent)
⌘我
[技术支持 本文档是在开发人员文档平台 Mintlify 上构建和托管的](https://www.mintlify.com/?utm_campaign=poweredBy&utm_medium=referral&utm_source=clawdhub)