Gateway 网关协议

​

传输和帧格式

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

​

握手

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

{
  "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": "…"
    }
  }
}

{
  "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
    }
  }
}

{
  "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"]
      }
    ]
  }
}

​

节点连接示例

{
  "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）。

​

角色和权限范围

• operator：控制平面客户端（CLI/UI/自动化）。
• node：能力宿主（camera/screen/canvas/system.run）。

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

​

在线状态

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

​

节点后台存活事件

{
  "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\"}"
}

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

​

广播事件作用域

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

​

RPC 方法族

​

常见事件族

• chat：UI 聊天更新，例如 chat.inject 和其他仅用于转录的聊天事件。在协议 v4 中，增量载荷携带 deltaText；message 仍是累计的助手快照。非前缀替换会设置 replace=true，并使用 deltaText 作为替换文本。
• session.message、session.operation、session.tool：已订阅会话的转录、进行中的会话操作，以及事件流更新。
• sessions.changed：会话索引或元数据已更改。
• presence：系统在线状态快照更新。
• tick：周期性 keepalive/liveness 事件。
• health：Gateway 健康快照更新。
• heartbeat：Heartbeat 事件流更新。
• cron：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：插件审批生命周期。

​

节点辅助方法

​

审计账本 RPC

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

​

任务账本 RPC

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

​

操作员辅助方法

• 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 服务器工具。
  • 对于 MCP，tools.effective 是只读的：它可以通过最终工具策略投影已预热会话的 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 视图

• 省略或 "default"：如果配置了 agents.defaults.models，响应就是允许的目录，包括为 provider/* 条目动态发现的模型。否则，响应就是完整 Gateway 网关目录。
• "configured"：适合选择器大小的行为。如果配置了 agents.defaults.models，它仍然优先生效，包括为 provider/* 条目进行提供商范围的发现。没有 allowlist 时，响应使用显式 models.providers.<provider>.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

​

客户端常量

​

认证

• 共享密钥 Gateway 网关认证使用 connect.params.auth.token 或 connect.params.auth.password，具体取决于配置的 gateway.auth.mode（"none" | "token" | "password" | "trusted-proxy"）。
• 带身份的模式，例如 Tailscale Serve（gateway.auth.allowTailscale: true） 或非 loopback 的 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.bootstrapToken 仅在上述内容均未解析出 auth.token 时发送。共享令牌或任何已解析设备令牌都会抑制它。
  • 对已存储设备令牌的一次性 AUTH_TOKEN_MISMATCH 重试自动提升仅限受信任端点：loopback， 或带有固定 tlsFingerprint 的 wss://。未固定的公共 wss:// 不符合条件。
• 内置设置码 bootstrap 返回主节点 hello-ok.auth.deviceToken，并在 hello-ok.auth.deviceTokens 中返回一个有界操作员令牌，用于受信任的移动端移交。该操作员令牌 包含 operator.talk.secrets，用于原生 Talk 配置读取，但 排除配对变更权限范围和 operator.admin。
• 当非基线设置码 bootstrap 等待审批时， PAIRING_REQUIRED 详情包含 recommendedNextStep: "wait_then_retry"、 retryable: true 和 pauseReconnect: false。继续使用相同的 bootstrap 令牌重连，直到请求获批或令牌失效。
• 仅当连接在受信任传输（例如 wss:// 或 loopback/本地配对）上使用 bootstrap 认证时，才持久化 hello-ok.auth.deviceTokens。
• 如果客户端提供显式 deviceToken 或显式 scopes，该 调用方请求的权限范围集合仍然具有权威性；仅当客户端复用已存储的按设备令牌时， 才复用缓存的权限范围。
• 设备令牌可通过 device.token.rotate 和 device.token.revoke 轮换/撤销（需要 operator.pairing）。轮换或撤销 节点或其他非操作员角色还需要 operator.admin。
• device.token.rotate 返回轮换元数据。它仅对已使用该 设备令牌认证的同设备调用回显替换 bearer 令牌，因此仅令牌客户端可以在 重连前持久化其替换令牌。共享/管理员轮换不会回显 bearer 令牌。
• 令牌签发、轮换和撤销都被限定在该设备配对条目中记录的已批准角色 集合内；令牌变更无法扩展或指向配对审批从未授予的设备角色。
• 对于已配对设备令牌会话，设备管理默认为自作用域，除非 调用方还拥有 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（应急破例，严重 安全降级）。
  • 预留内部辅助路径上的 direct-loopback gateway-client 后端 RPC。
• 省略设备身份会带来权限范围后果。当无设备 操作员连接通过显式信任路径获准时，OpenClaw 仍会将自声明权限范围清空为空集合，除非该路径具备 具名权限范围保留例外。受权限范围控制的方法随后会因 missing scope 失败。
• gateway.controlUi.dangerouslyDisableDeviceAuth=true 是 Control UI 应急权限范围保留路径。它不会向任意 自定义后端或 CLI 形态的 WebSocket 客户端授予权限范围。
• 预留的 direct-loopback gateway-client 后端辅助路径仅为内部本地控制平面 RPC 保留权限范围；自定义后端 ID 不会获得此例外。
• 所有连接都必须签名服务器提供的 connect.challenge nonce。

​

设备认证迁移诊断

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

​

TLS 和固定

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

​

范围

​

相关

• Bridge protocol（旧版节点，历史参考）
• Gateway 网关运行手册