跳转至

构建 Gateway 客户端

使用已发布的 Gateway 包来构建操作员仪表盘、WebChat 客户端以及其他第三方应用。本指南涵盖围绕线路契约的客户端生命周期:身份验证、能力、重连恢复、历史记录、订阅和版本升级。

关于帧结构、握手、错误以及完整的方法面,请阅读 Gateway 协议规范。

安装包

安装经过验证的稳定版本 2026.8.1,并使用精确版本固定:

npm install --save-exact @openclaw/gateway-client@2026.8.1 @openclaw/gateway-protocol@2026.8.1

如果现有 lockfile 仍将任一包固定到保留的 0.0.0 产物,请重新运行上述命令以替换它。这些保留产物没有可运行入口点或 TypeScript 声明。

包版本遵循 OpenClaw 发布列车,并且独立于线路协议版本。2026.8.1 包导出线路版本 4;这并不保证与每个 Gateway 发布版本兼容。根 openclaw CLI 有自己的包版本和 dist-tags。请一起固定并测试客户端与 Gateway 版本,并在升级前查看 线路版本规则。2026.8.1 客户端精确固定协议包 2026.8.1。

  • @openclaw/gateway-protocol 提供模式、运行时验证器、TypeScript 类型、客户端身份和能力注册表、结构化错误读取器以及协议版本常量。 其 npm tarball 还包含生成的 protocol.schema.json 机器可读契约。请将其作为文件下载;它不是导出的包导入子路径。
  • @openclaw/gateway-client 是参考连接实现。导入包根以使用 Node 客户端,导入 @openclaw/gateway-client/browser 以使用浏览器安全的协议、设备身份验证和重连辅助函数。

这些包版本声明 Node.js >=22.19.0。Node 入口包含 ws 传输;设备身份、签名和 device token 存储通过 GatewayClientHostDeps 仍由宿主管理。浏览器宿主需要提供 WebSocket 适配器,以及用于设备身份和 device token 的持久存储和签名回调。

选择权限范围并配对设备

一个完整的交互式聊天客户端,如果还需要渲染 approval prompt,应请求 role: "operator" 并带有以下权限范围:

权限范围 用途
operator.read chat.history、sessions.list、sessions.subscribe、模型状态和只读事件
operator.write chat.send 以及常规会话变更
operator.approvals 列出、显示和解决 exec 或插件审批

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

不要通过手动编辑 openclaw.json 来为每个客户端创建 bearer token。使用 openclaw configure --section gateway 或 openclaw onboard --gateway-auth ... 选项配置 Gateway 的共享引导身份验证,然后让设备 配对生成 client token:

  1. 在客户端中持久化一个 Ed25519 设备身份。
  2. 等待 connect.challenge,将其 ts 用作设备证明的 signedAt, 对与质询绑定的设备负载进行签名,并发送 connect,其中包含请求的操作员角色、权限范围以及用于引导身份验证的共享 Gateway token 或密码。收到的 WebSocket 质询如果没有非负整数 ts,则无效。明确支持 connect.challenge 出现之前的 Gateway 的客户端,仅可在其无质询路径上使用本地时间。
  3. 如果 Gateway 返回结构化的 PAIRING_REQUIRED 详细信息,请显示请求 ID,并根据 error.details.recommendedNextStep 暂停或重试。
  4. 在 Gateway 宿主上,使用 openclaw devices list 审查该请求,然后 使用 openclaw devices approve <requestId> 批准该确切的当前请求。
  5. 重新连接,并持久化 hello-ok.auth.deviceToken 以及协商的角色和权限范围。在后续连接中使用该 device token。

权限范围或角色升级会创建一个新的待处理配对请求。token 轮换不能扩大已批准的配对契约。有关批准、轮换和撤销命令,请参阅 Devices CLI。

connect.params.caps 描述客户端可消费的可选行为。它不授予授权。请从 GATEWAY_CLIENT_CAPS 导入名称,而不是重复字符串字面量:

import { GATEWAY_CLIENT_CAPS } from "@openclaw/gateway-protocol/client-info";

const caps = [GATEWAY_CLIENT_CAPS.TOOL_EVENTS];

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

usage-refreshing 允许冷 usage.status 请求立即返回 refreshing: true 和空提供商列表。声明该能力的客户端必须保持该负载的缓存为冷状态,并在短而有界的调度周期上重新获取。其他客户端保留阻塞式冷读取。

Warning

tool-events 控制实时工具执行流。Gateway 仅将声明此能力的连接注册为某次运行的结构化工具事件的接收方。如果没有它,连接不会收到实时工具事件,并且握手不会报告错误。

Capability-gated agent tools are a separate use of the same declaration. If an agent tool requires a client capability, the Gateway omits that tool unless the originating client advertised every required capability.

发送前验证附件

附件限制可由操作员调整,因此不要硬编码。读取 hello-ok.policy.attachments,并在上传前在本地进行验证:

const attachments = hello.policy.attachments;
if (attachments) {
  const ceiling = isImage ? attachments.maxImageBytes : attachments.maxBytes;
  if (file.byteLength > ceiling) rejectLocally();
}

这两个值都是解码后的每个附件上限。仍应根据 policy.maxPayload 检查序列化后的 请求:附件以 base64 传输,因此接近 maxBytes 的文件本身就可能超过帧限制。较旧的 网关会省略 policy.attachments;当它不存在时,发送请求并处理服务器返回的结果。 由于可接受的 MIME 类型和逐消息处理取决于入口点以及解析后的模型,因此不会通告 这些信息。网关可以返回带类型的拒绝,而仅文本模型运行可以在其卸载上限之后省略 额外图片,并仍然完成请求。这些值是连接时的快照,因此每次重新连接时都应重新读取。

重新连接后恢复状态

将每次成功的重新连接视为对持久化历史和当前内存中运行状态的新投影:

  1. 使用你的列表参数重新建立 sessions.subscribe,以便在同一响应中接收当前名册, 如下文所述。同时重新建立所选 会话的 sessions.messages.subscribe 订阅。
  2. 针对所选 sessionKey 调用 chat.history,并用返回的 messages 投影替换本地 持久化的行。
  3. 如果存在 inFlightRun,则采用其 runId、已缓冲的 text 以及可选的 plan。 即使 text 为空,也要采用该运行。
  4. 将 sessionInfo.hasActiveRun 视为直接会话的聚合活动。activeRunIds 存在时, 表示完整且精确的活动集合;因此空数组可证明会话处于空闲状态。当 hasActiveRun 为 true 且 activeRunIds 被省略时,表示另一个运行时所有者处于活动状态,但其 精确的运行标识不可用。在增量合并事件中,省略表示无变化,null 是仅用于事件的 墓碑,用于将缓存的精确 ID 清除为不可用,而数组会替换缓存(包括用于证明空闲的 [])。只关联客户端本地拥有或从请求、历史响应或事件中接收到的运行 ID,并且 永远不要选择列表中的第一个条目作为所有者。
  5. 只有当观察者摘要的精确 runId 存在于 activeRunIds 中时,才显示观察者标题或 运行检查器链接。仅凭聚合活动并不能使保留的摘要变为当前状态。
  6. 根据 payload.runId 和 payload.seq 协调后续的 agent 事件。为每个运行独立 维护已接受的最高序列号,忽略已见过或更低的序列号,并将前向间隙视为重新加载 权威历史的原因。

活动运行缓存矩阵

在应用 activeRunIds 之前,先对来源进行分类;相同的省略在完整快照和增量差异中 具有不同含义。

客户端缓存 读取路径 类别 必需行为
Web 会话名册 sessions.list、重新连接水合 快照 替换该行;省略会将缓存的精确 ID 清除为不可用。
Web 所选会话 chat.history.sessionInfo 快照 替换该行投影;省略会清除缓存的精确 ID。
Web 会话事件 sessions.changed、session.message、生命周期快照 增量 省略无效;null 清除;数组替换。
Android 会话名册 sessions.list、重新连接水合 快照 替换列表行;省略会清除缓存的精确 ID。
Android 所选会话 chat.history.sessionInfo、重新连接恢复 快照 即使其他部分历史字段正在合并,也要替换 activeRunIds。
Android 会话事件 sessions.changed、session.message、生命周期快照 增量 字段存在性控制替换;null 清除,省略无效。
Apple 会话名册 sessions.list、重新连接水合 快照 替换实时行;离线缓存会剥离瞬态活动运行事实。
Apple 所选会话 chat.history.sessionInfo、重新连接恢复 快照 同时替换当前行及其运行 ID 投影;省略会清除两者。
Apple 会话事件 sessions.changed、session.message、生命周期快照 增量 在解码过程中保留字段存在性;省略无效,null 清除,数组替换。

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

渲染生成的图像工件

助手生成的图像以规范的 type: "image" 内容块到达。受管块包含稳定的 artifactId、 相对于 Gateway 的 url、MIME 类型、尺寸、大小以及可访问的替代文本。在转录缓存中 保留该引用;不要持久化下载的字节或临时下载 URL。

通过已认证的 WebSocket 连接解析图像:

  1. 使用当前 sessionKey、可选的 agentId 以及该块的 artifactId 调用 artifacts.download。
  2. 在 expiresAt 之前使用返回的短期 url。该 URL 仅作用于该精确的基于 transcript 的 artifact,并且不包含可重用的 Gateway 或设备凭据。
  3. 从 Gateway 源使用与活动连接相同的 TLS pin 和反向代理请求头获取它。将响应验证为图像,并强制 12 MiB 源大小限制,同时限制解码后的缩略图大小。
  4. 如果 URL 过期,重复一次 artifacts.download。重新连接或路由更改会取消旧加载,而不是将其重新指向另一个 Gateway。

没有 artifactId 的旧图像块仍可由现有 Control UI 客户端显示,但原生客户端应显示可读的附件回退,而不是转发共享的所有者凭据。

通过 HTTPS 下载内联 artifact

对于嵌入在 transcript 中的 artifact,artifacts.download 通常通过现有连接返回 encoding: "base64" 和 data。能够访问 Gateway HTTPS 路由的客户端可以传入 transport: "http",以改为接收 Gateway 相对的 url 和 expiresAt,然后使用 GET 获取原始字节。该路由还支持 HEAD 和单个字节范围。托管媒体保留其现有 URL 下载路径。

在内联 HTTPS 下载 URL 后追加 ?variant=thumbnail,以获取尽力而为的 PNG 预览,其最长边限制为 1200 像素,且不会放大。只有已识别的静态 PNG、JPEG 和 WebP 图像符合条件。GIF、APNG、动画 WebP、其他格式、未知变体以及编码失败都会保留原始字节;如果 PNG 预览不比源文件小,也会保留原始字节。检查响应 MIME 类型:即使 artifact 使用其他图像格式,缩略图也是 image/png。全尺寸下载时省略查询参数;RPC schema 和 WebSocket base64 响应保持不变。

使用活动 Gateway 的 HTTPS 源和已配置的 Control UI 基础路径。TLS 可以在 Gateway 或其反向代理处终止;代理必须转发 /api/artifacts/download/ 以及 WebSocket 升级。仅有 wss:// 端点并不能建立 HTTP 可达性。仅使用 WebSocket 的客户端应省略 transport;HTTP 路由不可用的客户端可以不带 transport 重复相同的 RPC,同时保留所有 session、run、task 和 role 过滤器。

内联下载链接在五分钟过期,并属于发出该链接的活动连接和精确 artifact。读取时会重新检查访问权限、transcript 成员关系、session 代次和内容标识。过期、断开连接、吊销或替换会使链接不可用。应重新连接并请求新的下载,而不是跨连接保留链接。链接不包含可重用的 Gateway 凭据,并且响应会禁用缓存和活动文档执行。

Control UI 在从活动 Gateway 的 HTTPS 源提供时,会启用图像和文本预览。如果 HTTP 获取失败,它会通过同一连接上的内联 RPC 重试。其他连接保留其现有传输行为。二进制 artifact 预览保留 Download 操作,而不是使用会过期的链接。每次点击都会请求新的下载权限;更改连接或关闭预览会取消进行中的下载。

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

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

  • id 是 transcript 条目标识。将其用于锚定历史请求,但不要将其用作唯一的显示行键。
  • seq 是正的 transcript 记录序列。一条存储记录可以投影到多个显示行,因此将具有相同 id 和序列的兄弟行保持在一起。
  • kind 标识合成行。压缩边界使用 kind: "compaction",当匹配的 checkpoint 记录了这些指标时,可能包含 tokensBefore 和 tokensAfter。

会话重置边界使用 kind: "reset"。它没有 checkpoint token 指标。

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

使用订阅而不是轮询使用情况

安装 sessions.changed 监听器,然后每个连接调用一次 sessions.subscribe,并传入你的 sessions.list 参数,例如 { limit: 60, ownerFirst: true }。响应为 { subscribed: true, list },其中 list 是常规的 SessionsListResult 快照。传入 {} 会激活订阅,但只返回 { subscribed: true },不包含列表。

Gateway 在读取快照之前激活订阅。因此事件可能在响应之前到达。跟踪在引导期间接收到的更改,并在需要时跟随响应执行 sessions.list 刷新;不要让快照静默覆盖更新的事件。每次重新连接后重新建立此流程。

ownerFirst: true 会将最多 60 个由已认证查看者拥有的匹配会话前置到常规第一页,并移除该响应内的重复项。它仅在 offset 为零或省略时适用。Gateway 从已认证连接派生查看者身份,而不是客户端提供的身份。共享页面的分页元数据保持不变,因此加载另一页时使用 nextOffset,而不是返回的行数,并按 session key 合并行。参见 会话列表引导。

从后续带键的 sessions.changed 事件的嵌套 session 行中合并,同时使用 agent、session key 和 session ID,以避免将旧生命周期应用到其替换项。快照针对接收连接呈现,并携带当前行元数据、用量和活动运行状态。

在本地将快照应用于现有名册成员。当某行缺失或通知是宽泛的无键失效时,刷新 sessions.list。 删除事件保留被移除的会话 ID,且不携带替换行。 同一会话的别名通知共享发布顺序。快速替换可能会合并中间通知;宽泛失效会跟随压缩后的更新,以便客户端刷新权威名册。当无法准备行元数据时,也会发送相同的刷新通知。 不要轮询 usage.cost 或 sessions.usage 来保持实时会话列表最新;将这些方法保留用于按需的汇总或详细报告。

回填执行审批

具有 operator.approvals 的客户端应在 hello-ok 完成后立即安装其事件监听器,然后调用 exec.approval.list 以回填早于该连接存在的请求。按审批 ID 协调列表和实时的 exec.approval.requested / exec.approval.resolved 事件,确保与列表请求竞争的状态转换既不会丢失,也不会被重新激活。

跟踪协议版本

当前线路版本为 4。通用 operator 和 WebChat 客户端必须使用 minProtocol: 4 和 maxProtocol: 4 协商确切的当前版本。只有已认证的 node 客户端和轻量级检查具有 N-1 接受窗口,当前为协议 3 到 4。

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw