单个 Gateway
一台主机上通常只放一个总机房。这样 WhatsApp Web 会话和各类通道不会互相打架。
Concepts 导读
一张图看懂 Gateway：谁连谁、谁管谁、谁开 WhatsApp 会话
整个系统只有一个 Gateway 进程，它独占 WhatsApp 会话，所有消息表面（WhatsApp、Telegram、Slack 等）都挂在它下面。控制面客户端（mac 应用、CLI、Web UI）和节点设备（手机、电脑、无头设备）都通过 WebSocket 连到同一个端口（默认 18789），但角色不同：客户端发请求、订阅事件，节点声明 `role: node` 并暴露设备命令。最容易搞错的是——节点配对基于设备身份，配对审批存在设备配对存储里，不是 Gateway 管的。
先讲这一页到底在解决什么
一张图看懂 Gateway：谁连谁、谁管谁、谁开 WhatsApp 会话
整个系统只有一个 Gateway 进程，它独占 WhatsApp 会话，所有消息表面（WhatsApp、Telegram、Slack 等）都挂在它下面。控制面客户端（mac 应用、CLI、Web UI）和节点设备（手机、电脑、无头设备）都通过 WebSocket 连到同一个端口（默认 18789），但角色不同：客户端发请求、订阅事件，节点声明 `role: node` 并暴露设备命令。最容易搞错的是——节点配对基于设备身份，配对审批存在设备配对存储里，不是 Gateway 管的。
第一眼
🌉 一台长住的 Gateway，像楼里的总控机房
官方开头用的词很多，但真正的意思很简单：这是一台长期值班的总机房，消息通道都从这里过。
长寿进程
它不是临时跑一下的脚本，而是一直站岗的门卫室。
控制平面
CLI、mac app、web UI、automations，都是沿着 WebSocket 这条桥跟它说话。
一句话
Gateway 是楼心脏，不是边角插件。
谁连进来
📡 这栋楼里，进门的角色主要分两种
一类是管事的，一类是带能力上门干活的。它们都要先过 Gateway 这一关。
Control-plane clients
像 macOS app、CLI、网页控制台。它们是来下命令、看状态、管流程的。
Nodes
像 iOS、Android、headless 设备。它们不是来管流程的，而是来带着摄像头、屏幕、定位这些能力上场的。
role: node节点一进门就报工种，像胸牌上直接写“我是设备节点”。
同一扇门，不同工种
管事的和干活的都走同一个总机房，但报到方式不一样，权限也不一样。
Gateway 里面有什么
🧰 Gateway 像一间满墙开关的机房
它不只是一条桥，而是把连接、验证、事件、健康、心跳、Cron 都放进同一个调度中心。
Provider connections
像给 WhatsApp、Telegram、Slack、Discord 这些通道各拉一根线。
WS API
像前台收发请求、广播事件、回状态的统一喇叭口。
JSON Schema
像每个纸条都有固定格式，乱写的就不收。
health / heartbeat / cron
像门卫的体检、定时巡逻和定时广播都在同一间机房里协调。
连接流程
🤝 一次连接，其实像一段很完整的握手
官方把它画成 sequenceDiagram。翻成人话，就是门口报到、门卫确认、广播状态、继续办事。
Client 先发
connect像把开门申请单递进去。没有这一步，后面的事都别想开始。
Gateway 回
hello-ok像门卫盖章：“我认得你了，协议对上了，继续吧。”
随后推送
presence / tick像大厅里开始滚动显示谁在线、什么时候轮到下一次动作。
agent 请求像你开始正式递交一张工作单，Gateway 再把它送去后场。
关键规则
🔐 这栋楼有几条死规矩，官方写得很明白
这些不是装饰，是系统真正在执行的规则。
Handshake 必须先来
第一帧不是 connect，门直接关。
一栋楼一台主机房
尤其 WhatsApp Web，不允许多个 Gateway 随便共用同一条大门。
事件不回放
广播过去就过去了，掉线了就要重新看状态，不会自动给你补旧广播。
远程要带门卡
走 tailnet、SSH、TLS 时，门卡和认证都不能省。
远程门路
🚪 如果不是本地门口，就走更远但更稳的路
官方把远程访问讲得很实在：优先用 Tailscale 或 VPN，不行再 SSH tunnel，TLS 也可以开。
Tailscale / VPN
像把楼里总机房和外面的路接成一条私密内线。
SSH tunnel
像临时打通一条专门的暗道。
openclaw gateway --bind tailnet --token ...像把门开到外面时，顺手把门卡也挂上去，不让陌生人白进。
📌 一句话
越远的门路，越不能没有认证。
最后总结
🎈 把这页压成一句最短的话
Gateway architecture 讲的就是这栋楼怎么运转：一个总机房管住所有通道，客户端和节点都沿着它规定的门和桥进来，握手、验证、广播、调度都集中在这里。
如果你想看“这栋楼里不同消息到底怎么一路跑完”，下一页就去 /concepts/messages。