构建 Gateway 客户端

使用已发布的 Gateway 网关软件包构建操作员仪表板、WebChat 客户端 及其他第三方应用。本指南介绍围绕线协议的客户端生命周期： 身份验证、能力、重连恢复、历史记录、订阅和版本升级。

有关帧结构、握手、错误和完整方法列表，请阅读 Gateway 网关协议规范。

安装软件包

npm install @openclaw/gateway-client @openclaw/gateway-protocol

• @openclaw/gateway-protocol 提供 schema、运行时验证器、TypeScript 类型、客户端身份和 能力注册表、结构化错误读取器以及协议版本常量。 其 npm tarball 还包含生成的 protocol.schema.json 机器可读协议。
• @openclaw/gateway-client 是参考连接实现。导入软件包根入口以使用 Node 客户端，并导入 @openclaw/gateway-client/browser 以使用浏览器安全的协议、 设备身份验证和重连辅助程序。

Node 入口自行管理 WebSocket 传输。浏览器宿主需提供 WebSocket 适配器，以及用于设备身份和设备令牌的持久化存储与签名回调。

选择权限范围并配对设备

同时呈现审批提示的完整交互式聊天客户端应请求 role: "operator"，并包含以下权限范围：

仅当客户端处理交互式问题时添加 operator.questions； 仅当客户端管理已配对设备或节点时添加 operator.pairing； 仅针对 config.patch 等管理操作添加 operator.admin。 操作员权限范围参考 定义了完整的方法和审批时规则。

不要通过手动编辑 openclaw.json 来创建每客户端 bearer 令牌。使用 openclaw configure --section gateway 或 openclaw onboard --gateway-auth ... 选项配置 Gateway 网关的共享引导身份验证，然后让设备 配对签发客户端令牌：

1. 在客户端中持久化 Ed25519 设备身份。
2. 等待 connect.challenge，签署与质询绑定的设备负载，然后发送 connect，其中包含请求的操作员角色、权限范围，以及用于引导身份验证的共享 Gateway 网关令牌 或密码。
3. 如果 Gateway 网关返回结构化的 PAIRING_REQUIRED 详细信息，请显示请求 ID，并根据 error.details.recommendedNextStep 暂停或重试。
4. 在 Gateway 网关主机上，使用 openclaw devices list 审查请求，然后 使用 openclaw devices approve <requestId> 批准该确切的当前请求。
5. 重新连接，并将 hello-ok.auth.deviceToken 与协商后的角色和 权限范围一起持久化。后续连接使用该设备令牌。

升级权限范围或角色会创建新的待处理配对请求。令牌轮换无法 扩大已批准的配对协议。有关批准、轮换和 撤销命令，请参阅设备 CLI。

声明客户端能力

connect.params.caps 描述客户端可以使用的可选行为。它 不授予授权。应从 GATEWAY_CLIENT_CAPS 导入名称，而不要 重复字符串字面量：

 const caps = [GATEWAY_CLIENT_CAPS.TOOL_EVENTS];

当前注册表包含 approvals、exec-approvals、inline-widgets、 run-tool-bindings、session-scoped-events、plugin-approvals、 task-suggestions、terminal-offset-seq、tool-events 和 ui-commands。 仅声明客户端实际实现的能力。

受能力限制的智能体工具是同一声明的另一种用途。如果某个 智能体工具需要客户端能力，除非发起请求的客户端声明了所有必需能力， 否则 Gateway 网关会省略该工具。

重连后恢复状态

将每次成功重连视为基于持久历史记录和 当前内存中运行状态的新投影：

1. 重新建立 sessions.subscribe 和所选会话的 sessions.messages.subscribe 订阅。
2. 针对所选 sessionKey 调用 chat.history，并用返回的 messages 投影替换本地持久化行。
3. 如果存在 inFlightRun，采用其 runId、缓冲的 text 和可选的 plan。即使 text 为空，也要采用该运行。
4. 读取 sessionInfo.hasActiveRun 和 sessionInfo.activeRunIds。判断保留的运行是否仍拥有 流式 UI 时，优先采用 activeRunIds 中的精确成员关系。 hasActiveRun 为 true 但未列出 ID 时，可能表示另一个 活跃的运行时投影。
5. 按 payload.runId 和 payload.seq 协调后续 agent 事件。 为每次运行分别维护已接受的最高序列，忽略 已见过或更低的序列，并将向前的序列缺口视为重新加载 权威历史记录的理由。

外层事件帧还有可选的 seq，用于对 当前 WebSocket 连接上的事件排序。建立新连接后它会重置。 agent 事件负载中的 seq 按运行分配，用于对该运行的生命周期、 助手、计划、工具和其他流式事件排序。

使用历史元数据和稳定锚点

chat.history 返回的行可以携带 __openclaw 元数据封装：

• id 是转录条目的身份标识。将其用于锚定历史记录请求， 但不要将其用作唯一的显示行键。
• seq 是正数的转录记录序列。一个存储记录可以投影 为多个显示行，因此应将具有相同 id 和序列的同级行 保持在一起。
• kind 标识合成行。压缩边界使用 kind: "compaction"；如果匹配的检查点记录了相关指标，还可能包含 tokensBefore 和 tokensAfter。

使用响应中的 hasMore 和 nextOffset 值向后翻页。数字 偏移量描述当前转录投影，因此不要将其作为 跨重置或压缩的长期书签持久化。应改为持久化 __openclaw.id。 要恢复到已知行附近，请使用 messageId 和返回该值的 sessionId 调用 chat.history。Gateway 网关可以从重置 归档历史记录中解析该锚点；锚定响应会有意省略数字分页元数据。

订阅而非轮询用量

使用 sessions.list 加载初始目录，然后每个连接调用一次 sessions.subscribe。按 sessionKey 合并 sessions.changed 事件。会话变更 负载可以携带实时 inputTokens、outputTokens、totalTokens、 totalTokensFresh、contextTokens、estimatedCostUsd、响应用量设置 和活跃运行状态。

某些变更通知只是失效信号。如果事件省略了视图所需的 行字段，请刷新 sessions.list。不要通过轮询 usage.cost 或 sessions.usage 来保持实时会话列表为最新状态；这些方法仅用于 按需聚合报告或详细报告。

回填 Exec 审批

具有 operator.approvals 的客户端应在 hello-ok 完成后立即安装事件监听器，然后调用 exec.approval.list 回填连接建立前的请求。按审批 ID 协调列表与实时 exec.approval.requested / exec.approval.resolved 事件，确保与列表请求并发的 状态转换既不会丢失，也不会被重新恢复。

跟踪协议版本

当前线协议版本为 4。通用操作员和 WebChat 客户端必须 使用 minProtocol: 4 和 maxProtocol: 4 协商完全匹配的当前版本。 只有经过身份验证的节点客户端和轻量级探针具有 N-1 接受 窗口，目前支持协议 3 到 4。

协议变更优先采用增量方式。protocol.schema.json 包含 since 发布版本元数据和核心方法所需的权限范围元数据，但线协议 版本提升对第三方客户端而言仍是明确的破坏性事件。固定 测试过的软件包版本，在线协议版本变化时同步升级客户端和 Gateway 网关，并在 每次升级前查看 OpenClaw 变更日志。

相关内容

• Gateway 网关协议
• 嵌入 OpenClaw
• Gateway RPC 参考
• 面向外部应用的 Gateway 网关集成