02|控制平面:WS connect / event / call

02|控制平面:WS connect / event / call

OpenClaw 的 Control UI 与 CLI 的核心交互方式是 Gateway WebSocket。把它拆成三件事,会让你排障速度提升一个量级:

  1. connect:握手与鉴权
  2. event:持续事件流(订阅/广播)
  3. call:方法调用(通常快速 ACK,结果走事件流)

1) connect:第一帧为什么必须是 connect?

关键点(只记结论):

  • 连接建立后,客户端第一帧必须完成握手与身份声明
  • 远程/多设备场景下,鉴权与配对会决定“能不能连上、能不能调用有副作用的方法”

入口:

2) event:为什么 reply 不直接跟在 call 的响应里?

常见体验是:你调用 chat.send 会立刻得到一个 runId,但真正的回复通过事件流逐步返回。

这种设计的价值在于:

  • 流式输出天然适配多端 UI(Control UI/CLI/移动端)
  • 长任务可以持续上报状态(进度/工具调用/错误)
  • 失败恢复(重试/回退)可以在同一 runId 语义下被追踪

入口:

3) call:如何把一次调用“缩到最小可复现”?

当你怀疑问题发生在“方法调用层”,建议优先做到:

  • 用 CLI 走同一条 WS 调用链路,避免 UI 变量干扰
  • 固定一次调用的输入,观察同一个 runId 的事件序列

入口: