OpenClaw Gateway 架构深度解析

核心需求：AI 流式输出（逐字推送）+ 客户端实时发命令，必须双向实时通信。这是 AI Agent 交互的核心特征。

• HTTP 长轮询：延迟高（每次轮询 1~5 秒），连接开销大，无法满足流式推送场景 ❌。即使用多个长轮询连接，也无法实现真正的实时性。
• SSE（Server-sent Events）：只能服务端单向推送，客户端无法同时发命令（如：中断 Agent 执行、修改参数）。对于需要交互式控制的 AI Agent 场景，这是致命缺陷 ❌
• WebSocket ✅：持久双向连接，服务端可主动推送，客户端可随时发命令，延迟极低（< 50ms），完美匹配 AI 交互需求 ✅。同时，WebSocket 协议成熟，所有主流编程语言和平台都有稳定的实现。

重要说明：HTTP 并未消失——浏览器访问 Web UI、Slack Webhook 回调、OpenAI 兼容接口仍使用 HTTP。WebSocket 仅用于 Gateway 与客户端/节点之间的实时双向通信。这种混合设计兼顾了实时性和兼容性。

设计启示：技术选型应该由核心需求驱动，而非跟风。WebSocket 不是"最时髦"的选择，但是"最合适"的选择。

把「能不能连进来」「你是谁」「能做什么」分成三层，粒度从粗到细，职责清晰，互不干扰。这种设计使得每层可以独立演化，不影响其他层。

• 第一层 · Token（能不能连）：HTTP Upgrade 时通过 Authorization: Bearer <token> 验证，不合法直接断开连接。这是网络层的认证，在 WebSocket 握手阶段完成。即使后续 WebSocket 帧中没有 HTTP 头，Token 已经验证过了。
• 第二层 · Role（你是谁）：WebSocket 握手后的 connect 帧中声明 role 字段。operator（人类操作者）和 node（设备节点）的可调用方法完全隔离。即使 iPhone 拿到合法 Token，也无法调用 config.set 等管理接口。这是架构层的隔离。
• 第三层 · Scope（能做什么）：在 Role 基础上进一步细分：read（只读，查看日志和状态）、write（写操作，触发 Agent、修改配置）、admin（全部权限，管理用户和设备）。给团队成员只分配 read 权限，他们能看日志但无法触发 Agent。这是应用层的细粒度授权。

设计价值：三层分离使得每层可以独立演化。例如：未来可以更换 Token 机制为 OAuth2 或 OIDC，而不影响 Role 和 Scope 的逻辑。也可以在不改变 Token 和 Role 的情况下，新增 Scope 类型（如 audit 仅用于审计）。这种分层解耦是安全系统设计的最佳实践。

原因：HTTP 头只在建立连接时传递一次，WebSocket 帧中没有 HTTP 头，因此需要在 WebSocket 层再做一次认证握手。这个设计确保了双因子认证：网络层（Token）+ 应用层（Role/Scope）。

• Step 1（网络层认证）：客户端先通过 HTTP Upgrade 携带 Token（第一层认证），服务端返回 101 Switching Protocols。如果 Token 不合法，连接直接拒绝，不会进入 WebSocket 层。
• Step 2（应用层认证）：WebSocket 连接建立后，客户端必须立即发送 { "type":"req", "method":"connect", "params": { "role", "scopes", "clientId" } }（第二+三层认证）。只有 connect 成功后，客户端才能调用其他方法。
• Step 3（能力发现）：服务端返回 hello-ok，其中包含动态能力清单（gatewayMethods），插件安装后会自动出现在列表中。客户端无需硬编码服务端能力，实现了动态服务发现。
• 强制规范：任何非 JSON 或首帧非 connect 的连接直接强制关闭，从协议层面杜绝非法状态。这种设计称为"Fail-Fast 协议"，错误越早发现，系统越稳定。

设计哲学："把错误消灭在摇篮里"。强制 connect 为首帧，确保了所有后续通信都在已认证的上下文中进行。相比之下，如果允许任意顺序发送消息，就会出现"未认证就调用方法"的边界情况，增加系统复杂度和安全风险。

Gateway 暴露约 90 个方法，采用扁平哈希表管理，查找复杂度 O(1)，比路由树更简单高效。这种设计体现了"简单即美"的工程哲学。

• 核心 Handler 按功能分组：connectHandlers、healthHandlers、agentHandlers、sessionsHandlers、configHandlers 等约 30 个组，每组 export 一个字典。分组是为了代码组织清晰，而不是为了运行时路由。最终所有 Handler 合并到一个扁平 Map 中。
• 插件扩展机制：extraHandlers 优先级高于核心 Handler，插件只需 export 同类型对象即可注册新方法，甚至可覆盖内置行为（用于调试或特殊场景）。这种设计实现了开闭原则：对扩展开放，对修改封闭。
• 插件热插拔：新插件安装后，hello-ok 响应中的 gatewayMethods 会自动包含新方法，客户端无需靠文档猜测服务端能力。这是自描述协议的实践，大大提高了系统的可维护性。

设计哲学：「极简核心 + 弹性扩展」——核心保持小而稳定，扩展通过插件机制实现，不修改核心即可新增能力。对比常见的"微服务架构"，这种单体+插件的设计更简单、更高效，避免了微服务带来的分布式复杂性。

对比：如果采用路由树（如 Express.js 的路由系统），需要定义路由规则、处理路由冲突、管理中间件顺序，复杂度大大增加。而扁平 Handler Map 的设计，让每个方法的注册和查找都极其简单，性能也更可预测。

每次状态变化，版本号 +1；客户端重连时携带最后记住的版本号；若服务端版本更新，直接发送完整状态快照（而非增量）。这个设计体现了"可靠性优先于效率"的原则。

• 设计哲学：不补漏更新，直接发最新全量状态——简单可靠，彻底避免状态不一致。在分布式系统中，状态同步是最大的难题之一。增量同步需要维护操作日志、处理乱序、处理丢失，复杂度极高且容易出错。
• 对比增量同步：增量需要维护操作日志、处理乱序、处理丢失，复杂度极高且容易出错；全量快照虽然流量稍大，但逻辑简单、可靠性高。对于 AI Agent 系统来说，可靠性远比流量效率重要。
• 实际影响：重连时用户可能会看到一次「闪断」，但状态绝对正确，不会出现「消息发送了但 UI 没更新」的诡异 bug。这种"可预测的行为"对于用户体验来说，比"完美的动画过渡"更重要。
• 实现细节：广播事件时携带 stateVersion 字段，客户端保存最新版本号，重连时在 connect 帧中带回。如果版本号匹配，服务端无需发送快照；如果不匹配，发送完整快照。这种条件同步设计，在效率和可靠性之间取得了很好的平衡。

设计启示：在关键路径上（如状态同步），优先选择简单可靠的设计，而不是复杂高效的设计。因为复杂的设计会带来复杂的 bug，而简单的设计更容易验证正确性。"Make it work, make it right, make it fast." —— 先保证正确，再优化性能。