Gateway 网关协议

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

传输和帧格式

• 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?}

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

握手

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；它可能会过期，因此节点使用 node.pluginSurface.refresh 并传入 { "surface": "canvas" } 来获取新条目。 已弃用的 canvasHostUrl / canvasCapability / node.canvas.capability.refresh 路径不受支持；请使用插件界面。

当 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 会验证一项以哈希形式静态存储的短期凭据；该凭据绑定到环境、软件包哈希、所有者 epoch、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。

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

客户端能力

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

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

客户端能力描述已连接的客户端，而非授权。Agent 工具可以声明所需能力；除非每项要求都出现在发起请求的客户端的 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 发布可选的、对 Agent 可见的插件或 MCP 工具描述符。无头节点宿主需要重启才能应用声明式 MCP 清单变更。 此更新方法是唯一的发布路径；connect 参数不接受插件工具描述符。每个描述符都必须使用提供商安全的工具 name，并指定节点当前命令允许列表中的 command。Gateway 网关信任来自已配对节点的 描述符元数据，过滤已批准命令范围之外的描述符，在节点断开连接时移除这些描述符，并拒绝操作员更改其他节点目录的尝试。 将 gateway.nodes.pluginTools.enabled: false 设置为忽略节点发布的描述符。

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

在线状态

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

原生 macOS 节点还可以发送经过身份验证的 node.presence.activity 事件， 其中包含有界的输入空闲时间。Gateway 网关根据自身时钟推导活动时间戳， 通过 node.list 和 node.describe 公开最近活跃的已连接 Mac， 并向具有读取权限范围的客户端广播 node.presence 更新。 有关选择、隐私、模型上下文和通知路由行为，请参阅活动计算机在线状态。

节点后台存活事件

节点使用 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：唤醒词触发器配置已更改。
• 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.models， 响应将是允许的目录，包括为 provider/* 条目动态发现的模型。 否则，响应将是完整的 Gateway 网关目录。
• "configured"：适合选择器大小的行为。如果已配置 agents.defaults.models， 它仍然优先，包括针对 provider/* 条目按提供商限定的发现。 如果没有允许列表，响应会使用显式的 models.providers.<provider>.models 条目； 仅当不存在任何已配置的模型行时，才回退到完整目录。
• "provider-config"：由来源定义的 models.providers.*.models 清单， 独立于选择器允许列表。各行包含公开的模型能力和感知路由的可用性， 但省略提供商端点、身份验证材料和运行时请求配置。
• "all"：完整的 Gateway 网关目录，绕过 agents.defaults.models。 用于诊断/发现 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 请求可以包含 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.controlUi.allowInsecureAuth=true，用于仅限 localhost 的不安全 HTTP 兼容性。
  • 成功的 gateway.auth.mode: "trusted-proxy" 操作员 Control UI 身份验证。
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true（紧急手段，严重降低 安全性）。
  • 保留的内部辅助路径上直接回环的 gateway-client 后端 RPC。
• 省略设备身份会影响权限范围。当通过显式信任路径允许 无设备操作员连接时，OpenClaw 仍会将自行声明的权限范围清空为空集， 除非该路径具有具名的权限范围保留例外。之后，受权限范围限制的方法会以 missing scope 失败。
• gateway.controlUi.dangerouslyDisableDeviceAuth=true 是一条 Control UI 紧急权限范围保留路径。它不会向任意自定义后端或 CLI 形式的 WebSocket 客户端授予权限范围。
• 保留的直接回环 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 schema 定义。

相关内容

• 桥接协议
• Gateway 网关运行手册