Gateway 网关协议

Gateway 网关 WS 协议是 OpenClaw 的唯一控制平面和节点传输协议。操作员和节点客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无头节点）通过 WebSocket 连接，并在握手时声明角色和权限范围。

npm 软件包

这些软件包随 OpenClaw 发布系列一同交付。在初始推出期间，在首个包含软件包的版本发布之前，npm 可能返回 E404。

• @openclaw/gateway-protocol 发布架构、验证器、TypeScript 类型、轻量级帧和错误辅助工具以及版本常量。其 tarball 包含生成的 protocol.schema.json 机器可读契约。
• @openclaw/gateway-client 发布参考 Node 客户端，以及位于 @openclaw/gateway-client/browser 的浏览器安全入口。

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

传输和帧结构

• WebSocket、文本帧、JSON 载荷。
• 第一帧必须是 connect 请求。
• 连接前帧大小上限为 64 KiB（MAX_PREAUTH_PAYLOAD_BYTES）。握手后， 遵循 hello-ok.policy.maxPayload 和 hello-ok.policy.maxBufferedBytes。启用诊断后，过大的入站帧和缓慢的出站缓冲区会在 Gateway 网关关闭或丢弃帧之前发出 payload.large 事件。这些事件携带 surface、字节 大小、限制和安全原因代码，绝不包含消息正文、附件 内容、原始帧字节、令牌、Cookie 或密钥。

帧结构：

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

响应错误使用 { code, message, details?, retryable?, retryAfterMs? }。 客户端应根据 code 和 details.code 进行分支处理；message 保持人类可读， 除非兼容性说明另有规定，否则可能发生变化。方法级 授权失败使用顶层 code: "FORBIDDEN"，并包含结构化的 缺失权限范围详情：

• 缺失权限范围：{ code: "MISSING_SCOPE", missingScope, requiredScopes }。 requiredScopes 是所请求操作的完整已知权限范围集合。 为兼容旧版客户端，保留旧版 missing scope: <scope> 消息。

客户端应首先读取 details，仅将旧版消息用作兼容性 回退。readMissingScopeError 和 readMissingScopeErrorDetails 从 @openclaw/gateway-protocol/gateway-error-details 导出；浏览器安全的 Gateway 网关客户端 从 @openclaw/gateway-client/browser 重新导出它们。

架构从 @openclaw/gateway-protocol/schema 导出为 GatewayErrorDetailsSchema、 MissingScopeErrorDetailsSchema。 HTTP 权限范围失败会在 error.details 下镜像 MISSING_SCOPE 对象，并 使用 HTTP 状态码 403。

具有副作用的方法需要幂等键（参见架构）。

握手

Gateway 网关发送连接前质询：

{  "type": "event",  "event": "connect.challenge",  "payload": { "nonce": "…", "ts": 1737264000000 }}

客户端使用 connect 响应：

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 4,    "maxProtocol": 4,    "client": {      "id": "cli",      "version": "1.2.3",      "platform": "macos",      "mode": "operator"    },    "role": "operator",    "scopes": ["operator.read", "operator.write"],    "caps": [],    "commands": [],    "permissions": {},    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-cli/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

Gateway 网关使用 hello-ok 响应：

{  "type": "res",  "id": "…",  "ok": true,  "payload": {    "type": "hello-ok",    "protocol": 4,    "server": { "version": "…", "connId": "…" },    "features": { "methods": ["…"], "events": ["…"] },    "snapshot": { "…": "…" },    "auth": {      "role": "operator",      "scopes": ["operator.read", "operator.write"]    },    "policy": {      "maxPayload": 26214400,      "maxBufferedBytes": 52428800,      "tickIntervalMs": 15000    }  }}

server、features、snapshot、policy 和 auth 均为 HelloOkSchema（packages/gateway-protocol/src/schema/frames.ts）的必填项。即使未签发设备令牌，auth 也会报告协商后的角色/权限范围（结构如上）。pluginSurfaceUrls 是可选项，用于将插件界面名称（例如 canvas）映射到有权限范围限制的托管 URL；它可能过期，因此节点使用 { "surface": "canvas" } 调用 node.pluginSurface.refresh 以获取新的条目。 已弃用的 canvasHostUrl / canvasCapability / node.canvas.capability.refresh 路径不受支持；请使用插件界面。 快照中可选的 appliedConfigHash 是活动 Gateway 网关运行时接受的已解析源配置修订版本。客户端可将其与 config.get.configRevisionHash 比较，以确定较新的已保存配置是否仍 需要重启。config.get.hash 仍是配置写入冲突防护所使用的 原始根文件修订版本。

当 Gateway 网关仍在完成启动辅助进程时，connect 可能返回 可重试的 UNAVAILABLE 错误，其中包含 details.reason: "startup-sidecars" 和 retryAfterMs。应在连接预算内重试，而不是将其视为 终止性的握手失败。

签发设备令牌时，hello-ok.auth 会添加该令牌：

{  "auth": {    "deviceToken": "…",    "role": "operator",    "scopes": ["operator.read", "operator.write"]  }}

内置二维码/设置代码引导是移动端交接路径。成功的 基准设置代码连接会返回一个主节点令牌和一个受限的 操作员令牌：

{  "auth": {    "deviceToken": "…",    "role": "node",    "scopes": [],    "deviceTokens": [      {        "deviceToken": "…",        "role": "operator",        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]      }    ]  }}

此操作员交接是有意限制的：足以启动移动端 操作员循环和原生设置，包括用于读取 Talk 模式 配置的 operator.talk.secrets，但不包含配对变更权限范围，也不包含 operator.admin。更广泛的 配对/管理员访问需要单独批准的配对或令牌流程。仅当引导身份验证通过受信任的 传输（wss:// 或环回/本地配对）运行时，才持久化 hello-ok.auth.deviceTokens。

受信任的同进程后端客户端（client.id: "gateway-client"、 client.mode: "backend"）在使用共享 Gateway 网关令牌/密码进行身份验证时，可在直接环回连接上省略 device。 此路径仅供内部控制平面 RPC 使用（例如子智能体会话更新），并避免 过时的 CLI/设备配对基准阻止本地后端工作。远程、 浏览器来源、节点以及显式设备令牌/设备身份客户端仍 需要经过常规配对和权限范围升级检查。

工作节点角色和封闭协议

云端工作节点通过 Gateway 网关所有、绑定主机密钥的 SSH 隧道使用专用环回入口。它仅接受工作节点身份， 绝不分派通用身份验证、节点事件、操作员 RPC 或插件方法。严格的 connect 会验证静态哈希存储的短期凭据，该凭据绑定到环境、软件包 哈希、所有者纪元、RPC 集版本、过期时间和一个可为空的会话；它还会 分别检查当前版本和功能集。成功时返回最小化的 worker-hello-ok；功能协商独立于通用协议 版本。帧大小保持在 64 KiB 以下，但经协商的 worker.inference.start 帧最大可达 25 MiB。封闭允许列表包含 worker.heartbeat、 worker.transcript.commit、worker.live-event、worker.inference.start 和 worker.inference.cancel。

转录提交使用所有者纪元隔离、Gateway 网关所有的会话绑定、 基叶比较并交换以及持久序列重放；Gateway 网关通过常规会话写入器生成 转录条目和父级 ID。每次 RPC 都会重新检查所有权和 过期时间。

客户端能力

操作员客户端可以在 connect.params.caps 中声明可选能力：

• tool-events：接受结构化工具生命周期事件。
• inline-widgets：可以渲染托管的内联小组件工具结果。

客户端能力描述的是已连接的客户端，而非授权。智能体工具可以声明所需能力；除非每项要求都出现在发起请求的客户端的 caps 中，否则 Gateway 网关会省略这些工具。由渠道发起的运行没有 Gateway 网关客户端能力，因此即使工具策略明确允许，能力受限的工具也不可用。

节点连接示例

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 4,    "maxProtocol": 4,    "client": {      "id": "ios-node",      "version": "1.2.3",      "platform": "ios",      "mode": "node"    },    "role": "node",    "scopes": [],    "caps": ["camera", "canvas", "screen", "location", "voice"],    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],    "permissions": { "camera.capture": true, "screen.record": false },    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-ios/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

节点在连接时声明能力：

• caps：高级类别，例如 camera、canvas、screen、 location、voice、talk。
• commands：用于调用的命令允许列表。
• permissions：细粒度开关（例如 screen.record、camera.capture）。

Gateway 网关将这些视为声明，并在服务器端强制执行允许列表。

角色和权限范围

有关完整的操作员权限范围模型、批准时检查和共享密钥 语义，请参阅操作员权限范围。

角色：

• operator：控制平面客户端（CLI/UI/自动化）。
• node：能力宿主（摄像头/屏幕/画布/system.run）。
• worker：专用封闭工作节点协议上的云端执行宿主。

操作员权限范围（src/gateway/operator-scopes.ts），完整封闭集合：

• operator.read
• operator.write
• operator.admin
• operator.approvals
• operator.pairing
• operator.talk.secrets

带有 includeSecrets: true 的 talk.config 需要 operator.talk.secrets（或 operator.admin）。包含密钥时，从 talk.resolved.config.apiKey 读取活动 Talk 模式提供商 凭据；talk.providers.<id>.apiKey 保持源结构，可能是 SecretRef 对象或经过遮盖的字符串。

插件注册的 Gateway 网关 RPC 方法可以请求自己的操作员权限范围， 但以下保留的核心前缀始终解析为 operator.admin （src/shared/gateway-method-policy.ts）：config.*、exec.approvals.*、 wizard.*、update.*。

方法权限范围只是第一道关卡。通过 chat.send 访问的部分斜杠命令会执行更严格的命令级检查：即使 Gateway 网关客户端 已持有较低的操作员权限范围，持久化 /config set 和 /config unset 写入仍需要 operator.admin。

除基础方法权限范围（operator.pairing）外，node.pair.approve 还会在批准时根据待处理请求声明的 commands（src/infra/node-pairing-authz.ts）执行额外的权限范围检查：

能力/命令/权限（节点）

节点在连接时声明能力：

• caps：高级能力类别，例如 camera、canvas、screen、 location、voice 和 talk。
• commands：调用命令的允许列表。
• permissions：细粒度开关（例如 screen.record、camera.capture）。

Gateway 网关将这些视为声明，并在服务器端强制执行允许列表。 成功连接或重新连接后，已连接的节点可以通过 node.pluginTools.update 发布可选的、对智能体可见的插件或 MCP 工具 描述符。无头节点主机需要重启才能应用声明式 MCP 清单 更改。此更新方法是唯一的发布路径；connect 参数不接受插件工具描述符。每个描述符必须使用提供商安全的工具 name，并指定 节点当前命令允许列表中的 command。Gateway 网关信任已配对节点提供的描述符 元数据，过滤超出已批准命令 范围的描述符，在节点断开连接时移除这些描述符，并拒绝操作员 尝试修改其他节点目录的操作。设置 gateway.nodes.pluginTools.enabled: false 可忽略节点发布的描述符。

已连接的节点主机通过 node.skills.update 发布其完整的技能替换目录。此节点角色方法是唯一的节点技能发布 路径；connect 参数不接受技能。每个描述符均包含安全的 名称、描述和有界的 SKILL.md 内容。Gateway 网关使用常规技能加载器解析该 内容，在节点连接期间将其纳入智能体技能快照， 并在断开连接时将其移除。设置 gateway.nodes.allowSkills: false 可忽略节点发布的技能。

在线状态

• system-presence 返回按设备身份标识的条目，其中包括 deviceId、roles 和 scopes，因此即使设备同时以操作员和节点身份连接， UI 也能为每台设备显示一行。
• node.list 包含可选的 lastSeenAtMs 和 lastSeenReason。已连接的 节点使用原因 connect 报告当前连接时间；已配对节点还可以 通过受信任的节点事件报告持久的后台在线状态。

原生 macOS 节点还可以发送经过身份验证的 node.presence.activity 事件， 其中包含有界的输入空闲时间。Gateway 网关使用自身时钟推导活动时间戳， 通过 node.list 和 node.describe 公开最近活跃的已连接 Mac，并向具有读取权限范围的客户端广播 node.presence 更新。 用户禁用活动共享时，应用会发送 { "action": "clear" }； Gateway 网关仅清除该经过身份验证的确切节点连接的时间戳。 早于这一已确认操作的 Gateway 网关会将其作为未处理操作返回，因此 Mac 节点会重新连接一次，并让断开连接清理移除旧的连接状态。 有关选择、隐私、模型上下文和通知路由行为，请参阅活动计算机在线状态。

节点后台存活事件

节点调用带有 event: "node.presence.alive" 的 node.event，以记录 已配对节点在后台唤醒期间处于存活状态，但不将其标记为已连接：

{  "event": "node.presence.alive",  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"}

trigger 是封闭枚举：background、silent_push、bg_app_refresh、 significant_location、manual、connect。未知值会规范化为 background（src/shared/node-presence.ts）。该事件仅对 经过身份验证的节点设备会话持久化；无设备或未配对的会话返回 handled: false。

成功的 Gateway 网关会返回结构化结果：

{  "ok": true,  "event": "node.presence.alive",  "handled": true,  "reason": "persisted"}

较旧的 Gateway 网关针对 node.event 可能仅返回 { "ok": true }；应将其视为已确认的 RPC，而不是持久化在线状态。

广播事件作用域

服务器推送的广播事件受作用域限制，因此仅限配对作用域或仅限节点的会话不会被动接收会话内容（src/gateway/server-broadcast.ts）：

• 聊天、智能体和工具结果帧（流式 agent 事件、工具结果事件）至少需要 operator.read。没有该作用域的会话会完全跳过这些帧。
• 插件定义的 plugin.* 广播默认仅限 operator.write 或 operator.admin；plugin.approval.requested / plugin.approval.resolved 等显式条目则改用 operator.approvals。
• 状态/传输事件（heartbeat、presence、tick、连接/断开连接生命周期）不受限制，因此每个已通过身份验证的会话都可以观察传输健康状况。
• 未知的广播事件系列默认受作用域限制（失败时关闭），除非已注册的处理程序明确放宽限制。

每个客户端连接都维护各自的每客户端序列号，因此即使不同客户端看到事件流中经作用域过滤的不同子集，广播在相应套接字上仍保持单调有序。

RPC 方法系列

hello-ok.features.methods 是一个保守的发现列表，由 src/gateway/server-methods-list.ts 加上已加载的插件/渠道方法导出构成——它不是每个方法的自动生成转储，并且某些方法（例如 push.test、web.login.start、web.login.wait、sessions.usage）即使是真实且可调用的方法，也会被有意排除在发现范围之外。应将其视为功能发现，而不是 src/gateway/server-methods/*.ts 的完整枚举。

常见事件类别

• chat：UI 聊天更新，例如 chat.inject 和其他仅限聊天记录的聊天 事件。在协议 v4 中，增量载荷携带 deltaText；message 仍是 累积的助手快照。非前缀替换会设置 replace=true，并使用 deltaText 作为替换文本。
• session.message、session.operation、session.tool：已订阅会话的聊天记录、进行中的 会话操作和事件流更新。
• session.approval：面向明确选择加入的精确会话订阅者，提供经过清理的待处理和终态审批事实。 子级审批使用持久化的祖先受众；事件绝不会修改聊天记录或唤醒智能体。
• sessions.changed：会话索引或元数据已更改。
• presence：系统在线状态快照更新。
• tick：定期保活/存活事件。
• health：Gateway 健康快照更新。
• heartbeat：Heartbeat 事件流更新。
• cron：定时任务运行/任务变更事件。
• shutdown：Gateway 网关关闭通知。
• node.pair.requested / node.pair.resolved：节点配对生命周期。
• node.invoke.request：节点调用请求广播。
• device.pair.requested / device.pair.resolved：已配对设备生命周期。
• voicewake.changed：唤醒词触发器配置已更改。
• config.changed：配置写入已持久化（载荷携带配置路径、 新快照哈希和时间戳，但绝不包含配置内容）。仅限操作员读取 权限范围；客户端通过 config.get 刷新。
• exec.approval.requested / exec.approval.resolved：Exec 审批 生命周期。
• plugin.approval.requested / plugin.approval.resolved：插件审批 生命周期。

节点辅助方法

节点可以调用 skills.bins，以获取用于自动允许检查的当前技能可执行文件列表。

审计账本 RPC

audit.activity.list 为操作员客户端提供稳定的最新优先视图，其中包含智能体 运行、工具操作和选择加入的消息生命周期元数据。它要求 operator.read。查询会排除超过 30 天的记录，共享 SQLite 账本最多容纳 100,000 条记录。过期行会在 Gateway 网关启动、每小时维护以及后续写入期间删除。有关数据模型和隐私语义，请参阅 审计历史。

• 参数：可选的精确 agentId、sessionKey 或 runId；可选的 kind （"agent_run"、"tool_action" 或 "message"）；可选的 status （"started"、"succeeded"、"failed"、"cancelled"、"timed_out"、 "blocked" 或 "unknown"）；可选的消息 direction（"inbound" 或 "outbound"）和精确的 channel；可选的包含端点的 after / before Unix 毫秒边界；可选的 limit，范围为 1 到 500；以及可选的 字符串 cursor，取自上一页。
• 结果：{ "events": AuditActivityEventV1[], "nextCursor"?: string }。

具名 V1 结果联合为智能体运行、工具操作、入站消息 和出站消息分别定义了独立的架构。eventType 判别字段分别为 agent_run、tool_action、inbound_message 或 outbound_message；kind 和 消息 direction 仍可用于筛选和显示。每个事件都有 整数 schemaVersion: 1。消息身份引用使用精确的 hmac-sha256:v1:<32 hex key id>:<64 hex digest> 格式；渠道发送者的参与者 ID 使用相同格式。

所有变体都要求 eventType、schemaVersion、eventId、sequence、 sourceSequence、occurredAt、kind、action、status、actor 和 redaction。变体字段如下：

封闭的消息枚举如下：

• conversationKind：direct、group、channel 或 unknown。
• 入站 outcome：completed、skipped 或 failed；可选的 reasonCode：duplicate、reply_operation_active、 reply_operation_aborted、fast_abort、plugin_bound_handled、 plugin_bound_unavailable、plugin_bound_declined、plugin_bound_error、 before_dispatch_handled、acp_dispatch_completed、acp_dispatch_failed、 acp_dispatch_empty 或 acp_dispatch_aborted。
• 出站 outcome：sent、suppressed、failed 或 unknown；可选的 reasonCode：cancelled_by_message_sending_hook、 cancelled_by_reply_payload_sending_hook、 empty_after_message_sending_hook、empty_after_reply_payload_sending_hook 或 no_visible_payload。如果适配器未返回平台身份，则为 unknown，因为无法证明外部副作用未发生。
• deliveryKind：text、media 或 other；failureStage： platform_send、queue 或 unknown。

终态字段相互关联，而非各自独立可选：

每个活动事件都包含稳定的事件 ID、单调递增的账本序列、 源事件序列、时间戳、参与者、操作、状态、整数 schemaVersion: 1 和 redaction: "metadata_only"。运行和工具记录 要求提供智能体和运行来源，并且可以包含会话来源。消息 记录可以包含智能体和运行 ID，但有意绝不包含 sessionKey 或 sessionId；因此，sessionKey 查询筛选器仅适用于 运行和工具行。工具事件可以包含工具调用 ID 和工具名称。

消息记录使用 message.inbound.processed 或 message.outbound.finished，并添加方向、渠道、会话类型、 规范化结果，以及可选的交付类型、失败阶段、持续时间、 结果数量、原因代码和安装本地加密键生成的 账户/会话/消息/目标伪标识符。这些伪标识符有助于 关联，但并非匿名化：状态数据库包含其密钥， 而 RPC 和 CLI 导出不包含。账本不存储提示词、消息 正文、工具参数、工具结果、命令输出或原始错误文本。 运行/工具的 sessionKey 值仍是原始关联元数据，其中可能嵌入 平台账户或对端 ID；消息记录不包含会话键。

对于入站行，durationMs 测量核心分派到其终止状态的耗时， resultCount 统计最终确定的排队工具、分块和回复负载。对于 出站行，durationMs 涵盖从取得交付所有权到确认、 死信或协调完成的时间（包括排队等待时间），而 resultCount 统计已识别的物理平台发送次数。deliveryKind（如果存在） 描述经过钩子和渲染后的有效负载；被抑制或 崩溃状态不明确的行不包含该字段。

当前消息覆盖范围包括到达核心 分派的已接受入站消息，包括核心重复/终止结果。对于到达共享持久 交付的每个原始逻辑回复负载，出站覆盖范围会写入 一条终止行；分块和适配器扇出汇总在 resultCount 中。排队的 可重试或状态不明确的发送仅在确认、进入死信 或协调后记录。绕过这些 共享边界的插件本地和直接发送路径目前尚未覆盖。有界工作队列采用尽力而为方式， 在发生故障或饱和时可能丢弃记录，因此此表面并非 无损的合规性归档。

记录功能默认启用，并由 audit.enabled 控制。消息记录 由 audit.messages 单独控制，默认值为 "off"。禁用 记录后，audit.activity.list 仍会提供此前写入的记录， 直到这些记录过期。

已发布的 audit.list 请求、结果和 AuditEvent 架构保持 不变，并且仅返回智能体运行和工具操作记录。新的操作员 客户端应在 Gateway 网关公布 audit.activity.list 时调用它。旧版 Gateway 网关可能报告 unknown method: audit.activity.list，也可能因为 已发布版本先执行授权、后查找方法，而对只读权限范围的请求报告 missing scope: operator.admin。仅当该方法未被公布时，才将后者视为方法不存在。随后，只有当过滤器不需要消息类型、方向或渠道 支持时，客户端才能重试 audit.list。

使用 openclaw audit 执行文本查询和有界 JSON 导出。

任务账本 RPC

操作员客户端通过 任务账本 RPC（packages/gateway-protocol/src/schema/tasks.ts）检查和取消 Gateway 网关后台任务记录。这些 RPC 返回经过清理的任务摘要，而非原始运行时状态。

• tasks.list 需要 operator.read。
  • 参数：可选的 status（"queued"、"running"、"completed"、 "failed"、"cancelled" 或 "timed_out"）或由这些状态组成的数组， 可选的 agentId、可选的 sessionKey、从 1 到 500 的可选 limit，以及可选字符串 cursor。
  • 结果：{ "tasks": TaskSummary[], "nextCursor"?: string }。
• tasks.get 需要 operator.read。
  • 参数：{ "taskId": string }。
  • 结果：{ "task": TaskSummary }。
  • 任务 ID 不存在时，返回 Gateway 网关的未找到错误结构。
• tasks.cancel 需要 operator.write。
  • 参数：{ "taskId": string, "reason"?: string }。
  • 结果：{ "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }。
  • found 表示账本中是否存在匹配的任务。cancelled 表示运行时是否接受或记录了取消操作。

TaskSummary 包含 id、status 以及可选元数据：kind、 runtime、title、agentId、sessionKey、childSessionKey、ownerKey、 runId、taskId、flowId、parentTaskId、sourceId、时间戳、进度、 终止摘要和经过清理的错误文本。agentId 标识执行任务的智能体； sessionKey 和 ownerKey 保留请求者和控制 上下文。

操作员辅助方法

• commands.list（operator.read）获取智能体的运行时命令清单。
  • agentId 是可选的；省略它可读取默认的 Agent 工作区。
  • scope 控制主要 name 所针对的表面：text 返回 不带前导 / 的主要文本命令令牌；native 和默认 both 路径在可用时返回可感知提供商的原生命令名称。
  • textAliases 包含 /model 和 /m 等精确的斜杠别名。
  • nativeName 在存在时包含可感知提供商的原生命令名称。
  • provider 是可选的，仅影响原生命名和原生插件 命令的可用性。
  • includeArgs=false 从响应中省略序列化参数元数据。
• tools.catalog（operator.read）获取智能体的运行时工具目录。 响应包含分组工具和来源元数据：
  • source：core 或 plugin
  • pluginId：当值为 source="plugin" 时表示插件所有者
  • optional：插件工具是否为可选工具
• tools.effective（operator.read）获取会话的运行时有效工具 清单。
  • sessionKey 为必填项。
  • Gateway 网关从服务器端会话中派生可信运行时上下文， 而不接受调用方提供的身份验证或交付上下文。
  • 响应是服务器派生的、限定于会话范围的活跃 清单投影，包括核心、插件、渠道以及已发现的 MCP 服务器工具。
  • tools.effective 对 MCP 是只读的：它可以通过最终工具策略投影热会话的 MCP 目录，但不会创建 MCP 运行时、 连接传输协议或发出 tools/list。如果不存在匹配的热目录， 响应可能包含 mcp-not-yet-connected、 mcp-not-yet-listed 或 mcp-stale-catalog 等通知。
  • 有效工具条目使用 source="core"、source="plugin"、 source="channel" 或 source="mcp"。
• tools.invoke（operator.write）通过与 /tools/invoke 相同的 Gateway 网关策略路径调用一个可用工具。
  • name 为必填项。args、sessionKey、agentId、confirm 和 idempotencyKey 为可选项。
  • 如果 sessionKey 和 agentId 同时存在，解析出的会话智能体 必须与 agentId 匹配。
  • 仅限所有者使用的核心包装器（如 cron、gateway 和 nodes）需要 所有者/管理员身份（operator.admin），即使 tools.invoke 本身 是 operator.write。
  • 响应是面向 SDK 的封装，包含 ok、toolName、可选的 output 和有类型的 error 字段。审批或策略拒绝会在 负载中返回 ok:false，而不会绕过 Gateway 网关工具策略 流水线。
• skills.status（operator.read）获取智能体可见的技能清单。
  • agentId 是可选的；省略它可读取默认的 Agent 工作区。
  • 响应包含资格信息、缺失的要求、配置检查 和经过清理的安装选项，且不会暴露原始密钥值。
• skills.search 和 skills.detail（operator.read）返回 ClawHub 发现元数据。
• skills.upload.begin、skills.upload.chunk 和 skills.upload.commit （operator.admin）会在安装私有技能归档前暂存该归档。这是供可信客户端使用的独立管理员上传路径， 不是常规 ClawHub 技能安装流程，并且默认禁用，除非启用 skills.install.allowUploadedArchives。
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) 创建绑定到该 slug 和 force 值的上传。
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) 在 精确的解码后偏移量处追加字节。
  • skills.upload.commit({ uploadId, sha256? }) 验证最终大小和 SHA-256。提交只会完成上传；不会安装技能。
  • 上传的技能归档是包含 SKILL.md 根目录的 zip 归档。归档的内部目录名称绝不会选择安装目标。
• skills.install（operator.admin）有三种模式：
  • ClawHub 模式：{ source: "clawhub", slug, version?, force? } 将 技能文件夹安装到默认 Agent 工作区的 skills/ 目录中。
  • 上传模式：{ source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } 将已提交的上传内容安装到默认 Agent 工作区的 skills/<slug> 目录中。slug 和 force 值必须与 原始 skills.upload.begin 请求匹配。除非启用 skills.install.allowUploadedArchives，否则请求会被拒绝；该设置不 影响 ClawHub 安装。
  • Gateway 网关安装程序模式：{ name, installId, timeoutMs? } 在 Gateway 网关主机上运行声明的 metadata.openclaw.install 操作。旧版客户端可能 仍会发送 dangerouslyForceUnsafeInstall；此字段已弃用， 仅为协议兼容性而接受，并会被忽略。对于 操作员负责的安装决策，请使用 security.installPolicy。
• skills.update（operator.admin）有两种模式：
  • ClawHub 模式更新默认 Agent 工作区中的一个已跟踪 slug 或所有已跟踪的 ClawHub 安装。
  • 配置模式修补 skills.entries.<skillKey> 值，例如 enabled、 apiKey 和 env。

models.list 视图

models.list 接受可选的 view 参数 （src/agents/model-catalog-visibility.ts）：

• 省略或设为 "default"：如果已配置 agents.defaults.modelPolicy.allow，则 响应为允许的目录，包括为 provider/* 条目动态发现的模型。否则，响应为完整的 Gateway 网关 目录。
• "configured"：适合选择器规模的行为。如果已配置 agents.defaults.modelPolicy.allow， 它仍然优先，包括为 provider/* 条目执行限定于提供商范围的发现。没有允许列表时，响应使用显式 models.providers.<provider>.models 条目；仅当不存在已配置的模型行时，才回退到完整 目录。
• "provider-config"：由来源定义的 models.providers.*.models 清单， 独立于选择器允许列表。行中包含公开的模型能力和 可感知路由的可用性，但不包含提供商端点、身份验证材料和 运行时请求配置。
• "all"：完整的 Gateway 网关目录，绕过 agents.defaults.modelPolicy.allow。用于 诊断/发现 UI，而不是常规模型选择器。

Exec 审批

• 当 Exec 请求需要审批时，Gateway 网关会广播 exec.approval.requested。
• 操作员客户端通过调用 exec.approval.resolve 来处理（需要 operator.approvals）。
• 对于 host=node，exec.approval.request 必须包含 systemRunPlan （规范的 argv/cwd/rawCommand/会话元数据）。缺少 systemRunPlan 的请求会被拒绝。
• 审批后，转发的 node.invoke system.run 调用会复用该规范 systemRunPlan，将其作为权威的命令/cwd/会话上下文。
• 如果调用方在准备阶段与最终获批的 system.run 转发之间修改了 command、rawCommand、cwd、agentId 或 sessionKey，Gateway 网关会拒绝运行，而不是信任修改后的载荷。

Agent 投递回退

• agent 请求可以包含 deliver=true，以请求出站投递。
• bestEffortDeliver=false（默认值）保持严格行为：无法解析或 仅限内部的投递目标会返回 INVALID_REQUEST。
• bestEffortDeliver=true 允许在无法解析出任何外部可投递路由时， 回退为仅在会话中执行（例如内部/webchat 会话或存在歧义的多渠道配置）。
• 请求投递时，最终的 agent 结果可能包含 result.deliveryStatus， 使用与 openclaw agent --json --deliver 中记录的相同 sent、suppressed、partial_failed 和 failed 状态。

版本控制

• PROTOCOL_VERSION、MIN_CLIENT_PROTOCOL_VERSION、 MIN_NODE_PROTOCOL_VERSION 和 MIN_PROBE_PROTOCOL_VERSION 位于 packages/gateway-protocol/src/version.ts 中。
• 客户端发送 minProtocol + maxProtocol。操作员和 UI 客户端必须 在该范围内包含当前协议；当前客户端和服务器运行 v4 协议。
• 同时具有 role: "node" 和 client.mode: "node" 的已认证客户端可以使用 N-1 节点协议（当前为 v3）。轻量级重启探测使用 相同的 N-1 窗口。设备身份验证、配对、权限范围、命令策略和 Exec 审批不受此兼容性窗口影响。插件所有的节点 能力和命令会被禁用，直到节点升级到当前 协议，因为其托管接口不属于 N-1 合约的一部分。
• 架构和模型由 TypeBox 定义生成：
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

客户端常量

参考客户端实现位于 packages/gateway-client/src/ （OpenClaw 通过轻量级 src/gateway/client.ts 门面封装它）。这些 默认值在 v4 协议中保持稳定，是第三方客户端的预期基线。

服务器在 hello-ok 中公布实际生效的 policy.tickIntervalMs、 policy.maxPayload 和 policy.maxBufferedBytes；客户端 应遵循这些值，而不是握手前的默认值。

当每个待处理请求都有截止时间时，参考客户端允许有限时请求使用各自配置的截止时间。 没有有限 timeoutMs 的 expectFinal 请求、 任何带有 timeoutMs: null 的请求，或有限时请求与 无界请求的混合，都会使 tick 看门狗保持活动状态。如果入站事件和 响应持续静默并超过 tick 超时阈值，客户端会使用代码 4000 关闭 套接字、拒绝所有待处理请求并重新连接。重新连接后，它不会 重放被拒绝的请求。

身份验证

• 共享密钥 Gateway 网关身份验证使用 connect.params.auth.token 或 connect.params.auth.password，具体取决于所配置的 gateway.auth.mode（"none" | "token" | "password" | "trusted-proxy"）。
• Tailscale Serve（gateway.auth.allowTailscale: true）等携带身份信息的模式 或非环回 gateway.auth.mode: "trusted-proxy" 会根据请求标头通过连接 身份验证检查，而不是使用 connect.params.auth.*。
• 私有入口 gateway.auth.mode: "none" 会完全跳过共享密钥连接身份验证； 请勿将该模式暴露在公共或不受信任的入口上。
• 配对后，Gateway 网关会签发一个作用域限定为连接 角色 + 权限范围的设备令牌，并在 hello-ok.auth.deviceToken 中返回。客户端应在 每次成功连接后持久保存该令牌。
• 使用已存储的设备令牌重新连接时，也应复用该令牌已获批准并存储的 权限范围集。这样可以保留已授予的读取、探测和状态访问权限， 并避免重新连接时无提示地收窄为隐式的仅管理员 权限范围。
• 客户端连接身份验证组装（packages/gateway-client/src/client.ts 中的 selectConnectAuth）：
  • auth.password 与其他身份验证方式相互独立，设置后始终会被转发。
  • auth.token 按以下优先顺序填充：首先是显式共享令牌， 然后是显式 deviceToken，最后是已存储的单设备令牌（以 deviceId + role 为键）。
  • 仅当上述方式均未解析出 auth.token 时，才会发送 auth.bootstrapToken。共享令牌或任何已解析的设备令牌都会抑制它。
  • 在一次性 AUTH_TOKEN_MISMATCH 重试时自动提升已存储设备令牌，仅限受信任端点：环回， 或使用固定 tlsFingerprint 的 wss://。未固定指纹的公共 wss:// 不符合条件。
• 内置设置代码引导会返回主节点 hello-ok.auth.deviceToken，以及 hello-ok.auth.deviceTokens 中一个权限受限的操作员令牌， 供受信任的移动端交接使用。该操作员令牌包含用于原生 Talk 配置读取的 operator.talk.secrets，但不包含配对变更权限范围和 operator.admin。
• 当非基线设置代码引导等待批准时， PAIRING_REQUIRED 详细信息包含 recommendedNextStep: "wait_then_retry"、 retryable: true 和 pauseReconnect: false。继续使用同一 引导令牌重新连接，直到请求获得批准或令牌失效。
• 仅当连接通过 wss:// 或环回/本地配对等受信任传输 使用引导身份验证时，才持久保存 hello-ok.auth.deviceTokens。
• 如果客户端提供显式 deviceToken 或显式 scopes，则 调用方请求的权限范围集仍具有决定权；仅当客户端复用已存储的单设备令牌时， 才会复用缓存的权限范围。
• 可以通过 device.token.rotate 和 device.token.revoke 轮换或撤销设备令牌（需要 operator.pairing）。轮换或撤销 节点或其他非操作员角色还需要 operator.admin。
• device.token.rotate 返回轮换元数据。仅当同一设备的调用已经使用该 设备令牌完成身份验证时，它才会回传替换后的不记名令牌，以便仅使用令牌的客户端 在重新连接前持久保存替换令牌。共享/管理员轮换不会回传不记名令牌。
• 令牌签发、轮换和撤销始终受限于该设备配对条目中记录的已批准角色 集；令牌变更无法扩展到或指定配对批准从未授予的设备角色。
• 对于已配对设备的令牌会话，设备管理仅限自身，除非 调用方还具有 operator.admin：非管理员调用方只能管理 自己设备条目的操作员令牌。节点和其他非操作员令牌 仅限管理员管理，即使是调用方自己的设备也不例外。
• device.token.rotate 和 device.token.revoke 还会根据调用方当前会话的权限范围， 检查目标操作员令牌的权限范围集。 非管理员调用方无法轮换或撤销权限范围比其现有权限更广的操作员令牌。
• 身份验证失败包括 error.details.code 以及恢复提示：
  • error.details.canRetryWithDeviceToken（布尔值）
  • error.details.recommendedNextStep：以下之一：retry_with_device_token、 update_auth_configuration、update_auth_credentials、 wait_then_retry、review_auth_configuration （packages/gateway-protocol/src/connect-error-details.ts）。
• 针对 AUTH_TOKEN_MISMATCH 的客户端行为：
  • 受信任客户端可以尝试一次有界重试，并使用缓存的单设备 令牌。
  • 如果该重试失败，请停止自动重新连接循环，并显示操作员 操作指引。
• AUTH_SCOPE_MISMATCH 表示设备令牌已被识别，但未涵盖 所请求的角色/权限范围。不要将其显示为令牌错误；应提示 操作员重新配对，或批准更窄/更宽的权限范围约定。

设备身份与配对

• 节点应包含由密钥对指纹派生的稳定设备身份（device.id）。
• Gateway 网关按设备 + 角色签发令牌。
• 除非启用了本地自动批准，否则新的设备 ID 需要获得 配对批准。
• 配对自动批准以直接 local loopback 连接为核心。
• OpenClaw 还为受信任的共享密钥辅助流程提供一条范围狭窄的 后端/容器本地自连接路径。
• 同一主机上的 tailnet 或 LAN 连接在配对时仍视为远程连接， 并且需要批准。
• WS 客户端通常会在 connect 期间包含 device 身份（操作员 + 节点）。唯一不带设备身份的操作员例外是以下显式信任路径：
  • 成功通过 gateway.auth.mode: "trusted-proxy" 完成操作员 Control UI 身份验证。
  • 保留内部辅助路径上通过直接环回 gateway-client 发起的后端 RPC。
• 省略设备身份会影响权限范围。当不带设备身份的 操作员连接通过显式信任路径被允许时，除非该路径具有 指定的权限范围保留例外，否则 OpenClaw 仍会将自行声明的权限范围清空。 此后，受权限范围限制的方法会以 missing scope 失败。
• 保留的直接环回 gateway-client 后端辅助路径仅为内部本地控制平面 RPC 保留权限范围；自定义后端 ID 不享有此例外。
• 所有连接都必须签署服务器提供的 connect.challenge nonce。

设备身份验证迁移诊断

对于仍使用质询前签名行为的旧版客户端，connect 会在 error.details.code 下返回 DEVICE_AUTH_* 详细代码，并带有稳定的 error.details.reason。

常见迁移失败：

迁移目标：

• 始终等待 connect.challenge。
• 签署包含服务器 nonce 的 v2 载荷。
• 在 connect.params.device.nonce 中发送同一 nonce。
• 首选签名载荷为 v3 （packages/gateway-client/src/device-auth.ts 中的 buildDeviceAuthPayloadV3）， 除设备/客户端/角色/权限范围/令牌/nonce 字段外，它还绑定 platform 和 deviceFamily。
• 为保持兼容性，仍接受旧版 v2 签名，但已配对设备 元数据固定仍会控制重新连接时的命令策略。

TLS 与固定

• WS 连接支持 TLS（gateway.tls 配置）。
• 客户端可以选择通过 gateway.remote.tlsFingerprint 或 CLI --tls-fingerprint 固定 Gateway 网关证书指纹。

范围

此协议公开完整的 Gateway 网关 API：状态、渠道、模型、聊天、 智能体、会话、节点、审批等。确切的接口范围由从 packages/gateway-protocol/src/schema.ts 重新导出的 TypeBox 模式定义。

相关内容

• 构建 Gateway 客户端
• 嵌入 OpenClaw
• Bridge protocol
• Gateway 运行手册