跳转至

传输与帧

在任何方法调用之前,线上格式的样子:已发布的软件包、帧形状、负载限制,以及由 Gateway 控制的 WebRTC Talk 契约。

npm 软件包

请按照 安装软件包 获取经过验证的稳定版本、精确版本命令以及兼容性指导。软件包发布版本与线上协议版本以及根 openclaw CLI 发布版本相互独立。

  • @openclaw/gateway-protocol 发布模式、校验器、TypeScript 类型、轻量级帧和错误辅助函数,以及版本常量。其 tarball 包含生成的 protocol.schema.json 机器可读契约,作为可下载文件提供,而不是导出的导入子路径。
  • @openclaw/gateway-client 发布参考 Node 客户端,以及位于 @openclaw/gateway-client/browser 的浏览器安全入口。

有关应用生命周期指导,请参阅 构建 Gateway 客户端。对于将 Gateway 作为子进程进行监管的应用,请参阅 嵌入 OpenClaw。

传输与分帧

  • WebSocket、文本帧、JSON 负载。
  • 第一帧必须是 connect 请求。
  • 默认预算允许每个解析后的客户端 IP 有 128 个未认证的未决连接。成功认证或关闭会释放该槽位。 有关共享 NAT 行为和环境变量覆盖,请参阅 预认证连接限制。
  • 预连接帧的上限为 64 KiB(MAX_PREAUTH_PAYLOAD_BYTES)。握手后,遵循 hello-ok.policy.maxPayload 和 hello-ok.policy.maxBufferedBytes。启用诊断时,在 Gateway 关闭或丢弃帧之前,超大的 入站帧和缓慢的出站缓冲区会发出 payload.large 事件。这些事件携带 surface、字节 大小、限制值和一个安全原因代码,绝不携带消息正文、附件内容、原始帧字节、令牌、Cookie 或机密。
  • Gateway 不协商 permessage-deflate。启用该扩展时,浏览器甚至可以压缩极小的请求;随后串行解压会在处理程序调度之前,使每个请求滞留在繁忙的事件循环轮次之后。 未压缩帧以更大的历史数据和名册消耗更多带宽为代价,保持突发请求的响应性。负载限制保持不变。

帧形状:

  • 请求:{type:"req", id, method, params, traceparent?, expectedProfileId?}
  • 响应:{type:"res", id, ok, payload|error}
  • 事件:{type:"event", event, payload, seq?, stateVersion?, recipientProfileId?}

实时文本在初始接收方快照之后使用追加增量。chat.history 字段 inFlightRun.text 仅恢复当前运行中未持久化的助手尾部。静默回复抑制使用全部可用源;尾部保留现有的指令和媒体规范化,而不会被再次分类为静默回复。如果上限驱逐了源上下文,保留的尾部文本会保守地保持可见。恢复被实时缓冲区上限驱逐文本的累积快照或替换,在所有权未知时可能会重新显示已提交文本,以保留未保存的输出。 当持久历史或带键的评注项接管实时文本的所有权时,Gateway 会在后续追加增量之前发送一个现有的 replace: true 帧。终端结果快照在 message.content 中保留其完整结果。由缓冲区支持的终端还可以提供现有的 message.openclawDisplayContent 投影:用于显示的同一未持久化尾部,包括显式空尾部和任何 Canvas 块。Control UI 在存储其实时视图之前应用该投影;投递消费者保留完整内容。外层事件序列间隙意味着客户端可能丢失了该基线的一部分:在应用更多增量之前,应退役连接并重新连接。如果揭示该间隙的帧是 chat 最终、中止或错误事件,则应在间隙回调退役连接之前,投递其权威终端结果和所提供的完整快照。这使得已完成的运行能够稳定,即使之后没有更多实时文本可供重放。 重新连接后更新会话订阅;Gateway 会为每个观察到的运行随下一个文本帧发送完整快照。运行本地负载序列可以跳过编号,因为文本经过节奏控制和合并;它们不是外层连接序列。

规范 agent 事件带有 stream: "item" 和 data.kind: "preamble",包含可选的 preamble 元数据。当该条目替换实时预览时,preamble.retainedText 提供生产者剩余答案投影,包括在没有剩余答案前缀时的空字符串。空的 preamble 对象表示该事件不携带新的退役投影。较早的预览信用仍可覆盖后续的条目 ID 和完成回显。仅追加客户端可以保留其已投递的预览,将其信用跨这些身份传递,并重新基线其最终答案状态。聊天和原始助手帧独立进行节奏控制;它们的到达顺序和负载序列号不是重新分类身份。旧客户端可以忽略此附加元数据。ACP 评注协调需要更新的 Gateway 和桥接。

退役使用助手出现身份,绝不使用文本前缀匹配。生产者将实时出现与已提交转录的幂等键或主机的精确源回执进行关联。持久化仍在流式传输的条目部分的原生框架保留其文本合并 itemId,并单独使用 occurrenceId 标识每个捕获区间。未标识文本保留在实时尾部,直到其获得携带身份的提交或运行终止;仅凭相等的持久文本无法隐藏它。

在多个视图之间共享一个连接的客户端,必须将其重建保留在本地流所有者中。新的本地监听器可能在线上快照已投递到另一个视图之后加入。应从该所有者的当前状态为其播种,或投递重建的本地快照,并在其连接或运行退役时清除该状态。仅凭持久历史并不构成有序的实时文本基线。

After authentication, a client may include a W3C traceparent string on each request frame. The Gateway continues a valid value as a child trace context for that request. Missing or syntactically malformed values within the 128-character field limit keep the default fresh request trace and do not fail the RPC; longer values make the request frame invalid. The initial connect request never establishes trace context for later frames. Use a separate traceparent for each logical request on a long-lived connection; do not treat the WebSocket itself as one trace.

Response errors use { code, message, details?, retryable?, retryAfterMs? }. Authenticated operator requests share a bounded queue for starting RPC handlers. Ordinary requests have both aggregate and per-connection waiting limits, so concurrent Control UI setup can queue without giving one connection the entire request allowance. The aggregate serialized-byte bound still applies. Small sessions.messages.subscribe requests without approval replay and sessions.messages.unsubscribe requests have separate bounded waiting capacity, including a per-connection limit. All requests share the same yielding budget. Roster subscriptions, catalog reads, and message subscriptions with approval replay share four preparation slots. A slot remains occupied until its request settles, and each start yields to ready socket I/O. A request waiting for a preparation slot stays in the bounded queue while eligible requests start: chat.history and sessions.list reads can pass waiting preparations, as can ordinary requests on other connections. Other starts preserve FIFO order within each connection, including subscriptions and their later unsubscribe requests. WebSocket handshakes bypass the request queue, so reconnecting tabs cannot start an unbounded replay wave ahead of other clients' handshakes. When waiting capacity is exhausted, the Gateway returns retryable UNAVAILABLE before the method runs; retry within the request's budget. Starts still waiting after 30 seconds also return retryable UNAVAILABLE, with details.reason: "request-start-timeout". The deadline runs when the event loop can next make progress; it does not interrupt an already-started handler. Gateway RPC queue-wait diagnostics include the entire wait, including preparation capacity and timed-out starts. Started requests complete concurrently, so responses can arrive out of order.

During cooperative suspension, identity reads (agent.identity.get) wait in the shared browser/CLI client for gateway.suspension with phase accepting. A retryable UNAVAILABLE with details.reason: "gateway-suspending" also parks the read, using retryAfterMs (60 seconds) as a fallback if the resume event is missed. The original request deadline and cancellation still apply. Disconnects settle pending reads normally and use the existing reconnect backoff. Writes are neither parked nor replayed by this identity-read policy.

Ordinary UI/SDK requests may outlive a socket disconnect, but cannot start a handler in a retiring Gateway instance. Shutdown fences new request entry and joins pending handler loading and authorization before releasing their runtime. Already-started methods retain their own shutdown behavior; shutdown does not wait for every RPC to finish. Exact pending node progress and result replies remain available during node cleanup, until transport shutdown seals entry.

Clients should branch on code and details.code; message remains human-readable and can change except where a compatibility note says otherwise. Method-level authorization failures use top-level code: "FORBIDDEN" with structured missing-scope details:

  • Missing scope: { code: "MISSING_SCOPE", missingScope, requiredScopes }. requiredScopes is the complete known scope set for the requested operation. The legacy missing scope: <scope> message is retained for older clients.

Clients should read details first and use the legacy message only as a compatibility fallback. readMissingScopeError and readMissingScopeErrorDetails are exported from @openclaw/gateway-protocol/gateway-error-details; the browser-safe gateway client re-exports them from @openclaw/gateway-client/browser.

The schemas are exported as GatewayErrorDetailsSchema, MissingScopeErrorDetailsSchema from @openclaw/gateway-protocol/schema. HTTP scope failures mirror the MISSING_SCOPE object under error.details and use HTTP status 403.

Side-effecting methods require idempotency keys (see schema).

配置文件绑定

Use profile binding only when hello-ok.features.capabilities includes profile-binding-v1. A client that requires this contract must report it as unavailable when the capability is absent, rather than silently sending an unbound action. Requests that omit expectedProfileId retain existing behavior.

expectedProfileId is an optional opaque string of 1 to 128 characters on an authenticated request frame. The Gateway compares it exactly with the current canonical profile ID of the authenticated principal. It does not trim, fold case, or follow merge aliases on the expected value. Obtain the ID from users.self; a Gateway URL, account label, agent ID, or session key is not a profile ID. A missing authenticated profile cannot satisfy the precondition.

A server advertising the capability checks the precondition at RPC entry and before returning a response payload. Commit-time revalidation is method-specific; the capability does not promise atomicity inside arbitrary methods or plugins. An entry check followed by asynchronous work is not itself a commit guarantee.

The structured error sets error.details.reason to EXPECTED_PROFILE_MISMATCH and carries a per-attempt classification in error.details.execution:

  • not_started: no execution was started by this attempt.
  • may_have_executed: the method may have run before the mismatch was detected; the error is not evidence of rollback.

Neither classification clears uncertainty from an earlier attempt or overrides a known acknowledgment (ACK). Preserve the original idempotency key and reconcile the earlier outcome before retrying uncertain work. Ordinary socket disconnects do not cancel already-accepted work.

在已认证的操作员广播中,可选的 recipientProfileId 在发布时标识接收方的规范配置文件。它是按接收方划分的帧事实,而不是事件来源、运行所有者身份或授权许可。现有事件权限和订阅仍然控制投递。将消费者同时绑定到其物理 Gateway 连接和所选配置文件;如果接收方字段缺失或不一致,停止将该事件应用于该绑定视图或操作,并暴露绑定失败。

本契约不涵盖预认证事件、节点事件投递、APNs 通知或进程内发布。它不会撤销提供商直连媒体或已签发的 WebRTC 凭据,也不承诺立即撤销保留的会话。

连接保活

已认证的控制连接使用 WebSocket ping/pong 保活。它们与定时代理心跳相互独立;禁用代理心跳不会禁用连接监控。

排在出站数据后面的 ping 受传输层不活动控制,包括部分写入进度和入站流量。一旦其写入完成,对端将获得完整的 25 秒 pong 窗口;无关的入站消息不会延长该窗口。周期性检查会关闭过期连接并释放其所有者。传输层不活动不是独立的仅写入截止时间:发送流量的对端可以保持排队写入存活。现有慢消费者缓冲区限制仍然适用。流式传输保留其流所有者生命周期策略。

网关控制的 WebRTC Talk

talk.client.create 接受附加能力 gateway-control-v1。已发布的浏览器/Gateway 拥有的 WebRTC 路由会先尝试 OAuth,然后回退到 Platform API 密钥认证。直接后端套接字以及未列出或私有的实时路由要求 Platform API 密钥认证。成功结果包括 clientControl: { owner: "gateway" }、clientSecret 中的 60 秒一次性 Gateway broker 令牌,以及相对路径 offerUrl: "/plugins/openai/realtime/calls"。

客户端仅向该路由发送带有 broker 令牌的 application/sdp。它不得创建提供商控制数据通道。Gateway 创建通话,在返回 answer SDP 之前附加提供商侧带,并拥有工具、转录、转向、取消和关闭生命周期。省略该能力的客户端保留现有浏览器会话行为。无法提供所请求所有者的 Gateway 或已配置认证路径返回 UNAVAILABLE;它永远不会将请求降级为客户端拥有的控制。

如果 Gateway 连接丢失,或者其当前 voiceSessionId 的 talk.event 包含 talkEvent.type: "session.closed",客户端必须关闭其本地媒体对等体。忽略其他通话的终止事件;单独的可恢复 session.error 不是关闭通知。

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