获课：shanxueit.com/13640/

Gateway 是什么？一句话说清楚

如果把OpenClaw比作一家公司，Gateway就是那个“前台+项目经理”——消息从各个平台涌进来，它负责接住、判断谁来谁不来、分给哪个Agent干活、活干完了再把结果送回去。整个过程中，它自己不动脑（推理交给Agent），但所有流程调度都绕不开它。

理解了这个定位，我们再来拆解它的运作机制。

一、“控制平面”的设计哲学

Gateway本质上是一个控制平面。这个概念来自网络工程——控制平面负责决策，数据平面负责执行。在OpenClaw里，Gateway就是那个“做决策”的角色：收到一条消息后，它要决定由哪个Agent处理、用哪个会话、需不需要人工审批、回复走哪条渠道。

核心设计有一个明确约束：每台主机只允许运行一个Gateway实例。这主要受限于WhatsApp的协议——Baileys库只允许同一个账号维持一个活跃Web会话，两个进程同时开会被踢下线。OpenClaw通过端口独占和文件锁来强制执行这个约束。

二、两套连接，两种逻辑

Gateway维护着两种根本不同的连接，理解这个区别很关键：

一种是渠道（Channel）——它们是嵌入在Gateway进程内部的插件/适配器，不是通过网络连进来的外部服务。启动时Gateway会初始化所有配置好的渠道，比如Telegram用grammY走HTTP长轮询、WhatsApp用Baileys走WebSocket。渠道和Gateway之间是进程内函数调用，没有网络延迟。

另一种是客户端（Client）——通过WebSocket协议远程连到Gateway的外部程序，监听默认端口18789。客户端分两种角色：操作员（Operator）负责监控执行状态、审批命令、管理会话；节点（Node）暴露设备能力给Agent使用，比如相机、屏幕录制、定位、Canvas画布。

一个容易混淆的点：简单的消息问答场景里，客户端完全不参与。用户从Telegram发消息进来，经过渠道进入Gateway、路由给Agent、Agent生成回复、回复原路返回——全程在Gateway进程内部完成。客户端只有在Agent需要执行危险命令（需操作员审批）、调用设备能力（需节点配合）、或操作员主动查看状态时才会介入。

三、握手与认证：安全的第一道防线

所有WebSocket客户端连接Gateway时，都要经过一套严格的握手流程。

第一步是挑战-应答。Gateway先给客户端发一个connect.challenge事件，里面带一个nonce随机数。客户端收到后，必须把nonce、设备身份、角色等信息打包签名，在connect请求里回传给Gateway。

第二步是角色与作用域声明。客户端在握手时就要声明自己是operator（控制平面）还是node（能力宿主），以及申请哪些scopes权限范围。常见作用域包括operator.read（读）、operator.write（写）、operator.admin（管理员）、operator.approvals（审批）、operator.pairing（配对）。

第三步是Token验证与设备配对。如果启动时设置了OPENCLAW_GATEWAY_TOKEN，客户端必须提供匹配的Token；配对通过后Gateway会签发一个设备Token，后续连接时客户端带上这个Token即可跳过重复配对。注意：绑定非本地地址时必须开启认证，否则等于把服务器控制权拱手让人。

四、广播与事件推送：让所有客户端“看到”发生了什么

Gateway通过WebSocket向所有已连接客户端推送实时事件。广播事件是有权限控制的——聊天、Agent执行、工具调用等事件至少需要operator.read权限才能收到；插件定义的plugin.*广播默认门控到operator.write或operator.admin；而心跳、在线状态等传输健康事件则不受限制，每个已认证会话都能看到。

每个客户端连接都有自己的序列号，确保事件在同一个socket上单调有序——即使不同客户端因权限不同看到了过滤后的事件子集，也不会出现乱序。

五、节点后台存活：设备休眠了，但Gateway知道它还在

iOS/Android节点可能在后台休眠，没法保持长连接。Gateway支持节点后台存活事件——节点可以在后台唤醒时调用node.event，传event: "node.presence.alive"，告诉Gateway“我还活着，虽然没连着”。这样Gateway就知道这台设备仍然可被调用，不会被标记为离线。

六、安全红线：网关绝不是“开个端口就行”

Gateway默认绑在127.0.0.1:18789（仅本机可访问），这是刻意设计的。如果通过配置bind改成了lan或0.0.0.0来对外开放，必须有强Token认证，否则有严重安全风险。

远程访问的推荐做法不是直接暴露端口，而是通过Tailscale Serve或SSH隧道做加密转发。在云上部署时，把Gateway放在VPC内、用安全组禁止公网访问端口、Token存储在密钥管理服务里——这些才是正确的打开方式。

写在最后

Gateway机制的底层逻辑，说到底就是把“连接”这件事系统化管理起来。它不负责思考，但负责让思考能发生——消息进来有人接、决策做了有人执行、设备离线了有人知道、权限越界了有人拦。理解这套机制，你就理解了数字员工真正的“交互底座”长什么样。