9.2 WebSocket 握手、鉴权与连接生命周期

本节从可运维角度讲清长连接的三类问题：握手阶段要把身份与协议上下文一次建好；连接生命周期要有心跳与关闭原因；重连与恢复要能对账，避免重复订阅与事件丢失。并给出一组可直接使用的诊断命令与日志筛选方法，用于定位断线发生在鉴权、网络还是服务端背压。

9.2.1 握手阶段：身份与协议上下文必须明确

WebSocket 握手的工程意义不是建立一条通道，而是建立可验证的身份与协议上下文。

• 身份校验：令牌是否有效，是否与预期来源绑定，是否需要配对审批。

• 协议协商：客户端能力与服务端能力是否一致，例如是否支持进度流与压缩。

• 上下文初始化：会话键与订阅范围如何确定。

握手失败应尽早拒绝并记录拒绝原因。把失败拖到执行阶段，会把问题伪装成模型或工具异常。

9.2.2 生命周期：心跳、背压与关闭原因

长连接的难点在长期。生命周期需要三个可观测信号。

• 心跳：用于发现半开连接与僵尸连接。

• 背压：当客户端处理不过来时，服务端必须限速、分级丢弃或断开，避免内存膨胀。

• 关闭原因：关闭码与原因必须落盘，才能复盘“谁先断、为什么断”。

官方 Gateway 与安全章节提供了对连接与鉴权边界的说明：https://docs.openclaw.ai/gateway 与 https://docs.openclaw.ai/gateway/security。

9.2.3 重连与恢复：防重复订阅与防丢事件

重连要解决两个问题。

• 防重复订阅：重连后重复订阅同一流会导致重复处理与重复副作用。

• 防丢事件：断线期间错过的关键事件需要能恢复或至少能对账。

实现方式取决于具体客户端，但验收点一致：重连后系统状态可查询，且不会出现“同一输入触发两次写入”。

9.2.4 时序图：握手、订阅与恢复

下面展示一个最小握手与恢复序列。

图 9-1：最小握手与恢复序列

9.2.5 诊断命令：先确认服务健康，再看断线分布

操作示例：先确认服务是否健康与依赖是否可用，再结合日志分布定位断线原因。

openclaw health --json
openclaw status --deep
openclaw logs --follow --json

操作示例：从结构化日志中汇总连接关闭原因分布。字段名以实际日志为准。

cat runtime.log | jq -r 'select(.event=="ws_close") | .close_reason' | sort | uniq -c | sort -nr | head