OpenClaw 核心技术深度解析(五):Gateway 网关架构

OpenClaw 不只是一个 AI Agent——它是一个多通道 AI Agent 网关。Gateway 是这个网关的中央协调器，负责将来自 Telegram、Discord、Slack、WhatsApp、Signal、iMessage 等多个平台的消息，统一路由到同一个 Agent 大脑。

Gateway 的核心职责

Gateway（src/gateway/）是 OpenClaw 的控制面，承担四大核心职责：

职责	模块	说明
会话路由	Session Router	根据绑定策略确定消息归属的会话
并发控制	Lane Queue	管理会话级和全局级并发，防止请求冲突
协议服务	WebSocket + HTTP	双协议支持，方法级授权
服务发现	mDNS / WAN / Tailscale	多种发现机制，支持本地和远程部署

会话路由：消息归属的决策树

当一条消息到达时，Session Router 需要决定它属于哪个会话。路由策略按优先级排列：

peer（直接对话者）
    → parent peer（父级对话者）
    → guild（群组/服务器）
    → team（团队）
    → account（账号）
    → channel（通道）
    → default（默认会话）

这个路由链确保了：

同一个用户在不同平台的消息可以路由到同一个会话
群组消息和私聊消息自动分离
多账号场景下的消息正确归属

并发控制：Lane Queue

AI Agent 的一个常见问题是并发冲突：如果两条消息同时到达，Agent 可能在处理第一条消息时收到第二条，导致上下文混乱。

Lane Queue 解决了这个问题：

级别	控制方式	说明
会话级	每个会话一个队列	同一会话的消息严格串行处理
全局级	全局并发限制	防止过多会话同时执行，保护系统资源
优先级	主会话优先	所有者的直接消息优先于群组消息

双协议架构：WebSocket + HTTP

Gateway 同时提供 WebSocket 和 HTTP 两种协议：

WebSocket（主协议）

用途：Agent 与 Gateway 之间的实时通信
特性：双向流、事件推送、会话状态同步
监听地址：默认 127.0.0.1:18789（仅回环地址，安全考虑）
认证：基于 token 的认证

HTTP（辅助协议）

用途：管理 API、健康检查、插件扩展
特性：RESTful 接口、方法级授权
授权模型：role（角色）+ scope（作用域）双维度

方法级授权

Gateway 的每个方法都有独立的授权要求：

# 示例：不同方法的授权级别
gateway.status:# 无需认证
auth:none
gateway.sessions:# 需要 owner 角色
auth:role:owner
gateway.exec:# 需要 owner 角色 + elevated scope
auth:role:owner,scope:elevated

多通道接入：统一的消息管道

Gateway 的最大价值在于多通道统一接入。OpenClaw 支持的通道包括：

通道	协议	特性
Telegram	Bot API + MTProto	支持流式输出、内联键盘、文件传输
Discord	Discord.js	支持斜杠命令、嵌入消息、语音通道
Slack	Bolt SDK	支持 App Home、消息线程、交互组件
WhatsApp	Baileys (非官方)	支持多设备、媒体消息、群组管理
Signal	signal-cli	端到端加密、群组消息
iMessage	AppleScript bridge	macOS 专属，需要 Mac 运行
WebChat	内置 Web UI	浏览器访问，开箱即用
Matrix	matrix-js-sdk	去中心化协议，自托管

所有通道通过通道适配器接入 Gateway：

用户消息 → 通道适配器（格式标准化）→ Gateway → Agent
Agent 回复 → Gateway → 通道适配器（格式化输出）→ 用户

通道适配器的职责：

将平台特定的消息格式转换为 OpenClaw 内部格式
处理平台特定的功能（如 Telegram 的内联键盘）
管理平台连接的生命周期
处理媒体文件的上传和下载

服务发现：从本地到远程

Gateway 支持多种服务发现机制，适应不同的部署场景：

机制	适用场景	说明
本地回环	单机部署	默认 `127.0.0.1:18789`，最安全
mDNS	局域网	自动发现同一网络内的 Gateway 实例
WAN	公网部署	通过公网 IP 或域名访问
Tailscale	安全远程	通过 Tailscale VPN 网络访问，零配置安全

Tailscale 集成是社区最推荐的远程访问方案——它提供了端到端加密的 VPN 隧道，无需暴露公网端口，无需配置防火墙规则。

插件扩展

Gateway 的方法表是可扩展的。插件可以：

注册新的 Gateway 方法
扩展 HTTP 路由
添加新的通道适配器
注入中间件

这使得 OpenClaw 的通信能力可以无限扩展，而不需要修改核心代码。

总结

Gateway 是 OpenClaw 从"单通道聊天机器人"进化为"多通道 AI Agent 平台"的关键架构。它通过统一的会话路由、精细的并发控制、双协议支持和灵活的服务发现，让一个 Agent 大脑可以同时服务多个平台的用户。

参考链接

Substack - OpenClaw Control Plane, Sessions, and the Event Loop
Valletta Software - OpenClaw Architecture Diagram 2026
Macaron - OpenClaw Chrome Extension: Browser Relay Setup
AIFreeAPI - OpenClaw Browser Relay Guide 2026
Moely - OpenClaw Source Code Review