网关协议

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

传输

• WebSocket，使用 JSON 负载的文本帧。
• 第一帧必须是 connect 请求。
• 连接前的帧上限为 64 KiB。成功完成握手后，客户端应遵循 hello-ok.policy.maxPayload 和 hello-ok.policy.maxBufferedBytes 限制。启用诊断后，过大的入站帧和过慢的出站缓冲会在网关关闭或丢弃受影响帧之前发出 payload.large 事件。这些事件会保留大小、限制、表面和安全原因代码。它们不会保留消息正文、附件内容、原始帧正文、令牌、cookie 或密钥值。

​

握手（connect）

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

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "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": 3,
    "server": { "version": "…", "connId": "…" },
    "features": { "methods": ["…"], "events": ["…"] },
    "snapshot": { "…": "…" },
    "auth": {
      "role": "operator",
      "scopes": ["operator.read", "operator.write"]
    },
    "policy": {
      "maxPayload": 26214400,
      "maxBufferedBytes": 52428800,
      "tickIntervalMs": 15000
    }
  }
}

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

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

​

帧格式

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

​

角色 + scopes

​

Roles

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

​

Scopes（operator）

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

• 无命令请求：operator.pairing
• 带有非 exec 节点命令的请求：operator.pairing + operator.write
• 包含 system.run、system.run.prepare 或 system.which 的请求： operator.pairing + operator.admin

​

Caps/commands/permissions（node）

• caps：高层级能力类别。
• commands：invoke 的命令 allowlist。
• permissions：细粒度开关（例如 screen.record、camera.capture）。

​

在线状态

• system-presence 返回以设备身份为键的条目。
• 在线状态条目包含 deviceId、roles 和 scopes，因此 UI 即使在同一设备同时以operator和node身份连接时，也能显示单行。
• node.list 包含可选的 lastSeenAtMs 和 lastSeenReason 字段。已连接的节点会将其当前连接时间作为 lastSeenAtMs 并以 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 和 tool-result 帧（包括流式 agent 事件和工具调用结果）至少需要 operator.read。没有 operator.read 的会话会完全跳过这些帧。
• 插件定义的 plugin.* 广播 会根据插件注册方式，被门控为 operator.write 或 operator.admin。
• 状态和传输事件（heartbeat、presence、tick、连接/断开生命周期等）保持不受限制，以便每个已认证会话都能观察传输健康状况。
• 未知的广播事件族 默认进行 scope 门控（fail-closed），除非注册的处理器显式放宽它们。

​

常见 RPC 方法族

​

常见事件族

• chat：如 chat.inject 和其他仅 transcript 的 chat 事件等 UI chat 更新。
• session.message 和 session.tool：已订阅会话的 transcript/event-stream 更新。
• sessions.changed：会话索引或元数据已变更。
• presence：系统 presence 快照更新。
• tick：周期性 keepalive / liveness 事件。
• health：网关健康状态快照更新。
• heartbeat：heartbeat 事件流更新。
• cron：cron 运行/作业变更事件。
• shutdown：网关关闭通知。
• node.pair.requested / node.pair.resolved：节点配对生命周期。
• node.invoke.request：节点 invoke 请求广播。
• device.pair.requested / device.pair.resolved：已配对设备生命周期。
• voicewake.changed：唤醒词触发配置已变更。
• exec.approval.requested / exec.approval.resolved：exec 审批生命周期。
• plugin.approval.requested / plugin.approval.resolved：插件审批生命周期。

​

节点助手方法

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

​

Operator 助手方法

• 操作员可以调用 commands.list（operator.read）来获取某个 agent 的运行时命令清单。
  • agentId 是可选的；省略它即可读取默认 agent 工作区。
  • scope 控制主 name 目标的表面：
    • text 返回不带前导 / 的主文本命令 token
    • native 和默认的 both 路径在可用时返回具备提供方感知的原生名称
  • textAliases 包含精确的斜杠别名，例如 /model 和 /m。
  • nativeName 在存在时携带提供方感知的原生命令名。
  • provider 是可选的，仅影响原生命名以及原生插件命令可用性。
  • includeArgs=false 会从响应中省略序列化的参数元数据。
• 操作员可以调用 tools.catalog（operator.read）来获取某个 agent 的运行时工具目录。响应包含分组后的工具和来源元数据：
  • source：core 或 plugin
  • pluginId：当 source="plugin" 时的插件所有者
  • optional：某个插件工具是否可选
• 操作员可以调用 tools.effective（operator.read）来获取某个会话的运行时生效工具清单。
  • sessionKey 是必需的。
  • Gateway 会在服务器端从会话派生受信任的运行时上下文，而不是接受调用方提供的 auth 或传递上下文。
  • 响应按会话作用域返回，并反映当前活动对话此刻可以使用的内容，包括 core、plugin 和 channel 工具。
• 操作员可以调用 tools.invoke（operator.write）通过与 /tools/invoke 相同的网关策略路径调用一个可用工具。
  • name 是必需的。args、sessionKey、agentId、confirm 和 idempotencyKey 是可选的。
  • 如果同时存在 sessionKey 和 agentId，则解析后的会话 agent 必须与 agentId 匹配。
  • 响应是面向 SDK 的信封，包含 ok、toolName、可选的 output 以及类型化 error 字段。审批或策略拒绝会在 payload 中返回 ok:false，而不是绕过网关工具策略管道。
• 操作员可以调用 skills.status（operator.read）来获取某个 agent 的可见技能清单。
  • agentId 是可选的；省略它即可读取默认 agent 工作区。
  • 响应包含资格、缺失的要求、配置检查，以及不暴露原始 secret 值的已清理安装选项。
• 操作员可以调用 skills.search 和 skills.detail（operator.read）来获取 ClawHub 发现元数据。
• 操作员可以调用 skills.install（operator.admin）并支持两种模式：
  • ClawHub 模式：{ source: "clawhub", slug, version?, force? } 将 skill 文件夹安装到默认 agent 工作区的 skills/ 目录。
  • Gateway 安装器模式：{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } 在网关主机上运行声明的 metadata.openclaw.install 动作。
• 操作员可以调用 skills.update（operator.admin）并支持两种模式：
  • ClawHub 模式更新一个已跟踪的 slug，或默认 agent 工作区中所有已跟踪的 ClawHub 安装。
  • 配置模式修补 skills.entries.<skillKey> 值，例如 enabled、apiKey 和 env。

​

models.list 视图

• 省略或 "default"：当前运行时行为。如果配置了 agents.defaults.models，响应就是允许的目录；否则响应就是完整的 Gateway 目录。
• "configured"：适合选择器大小的行为。如果配置了 agents.defaults.models，它仍然优先生效。否则响应使用显式的 models.providers.*.models 条目，只有在不存在任何已配置模型行时才回退到完整目录。
• "all"：完整的 Gateway 目录，绕过 agents.defaults.models。将其用于诊断和发现 UI，而不是普通模型选择器。

​

Exec 审批

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

​

Agent 投递回退

• agent 请求可以包含 deliver=true 来请求外发投递。
• bestEffortDeliver=false 保持严格行为：未解析或仅内部可用的投递目标会返回 INVALID_REQUEST。
• bestEffortDeliver=true 允许在无法解析到外部可投递路径时回退到仅会话执行（例如内部/webchat 会话或歧义的多通道配置）。

​

版本管理

• PROTOCOL_VERSION 位于 src/gateway/protocol/schema/protocol-schemas.ts。
• 客户端发送 minProtocol + maxProtocol；服务端会拒绝不匹配的情况。
• Schema + 模型由 TypeBox 定义生成：
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

客户端常量

​

认证

• 共享密钥网关认证使用 connect.params.auth.token 或 connect.params.auth.password，具体取决于配置的认证模式。
• 具有身份的模式，例如 Tailscale Serve（gateway.auth.allowTailscale: true）或非回环的 gateway.auth.mode: "trusted-proxy"，会基于请求头而不是 connect.params.auth.* 来满足连接认证检查。
• 私有入口的 gateway.auth.mode: "none" 会完全跳过共享密钥连接认证；不要在公共/不受信任的入口上暴露该模式。
• 配对后，Gateway 会发放一个按连接角色 + 范围限定的 device token。它会在 hello-ok.auth.deviceToken 中返回，客户端应将其持久化以供后续连接使用。
• 客户端应在任何成功连接后持久化主 hello-ok.auth.deviceToken。
• 使用该 已存储 的 device token 重新连接时，也应复用该 token 已存储的已批准范围集合。这可以保留已授予的读取/probe/status 访问权限，并避免在重连时悄悄收缩为更窄的隐式仅管理员范围。
• 客户端侧连接认证组装（src/gateway/client.ts 中的 selectConnectAuth）：
  • auth.password 是正交的，只要设置就会始终转发。
  • auth.token 按优先级填充：先显式共享令牌，然后显式 deviceToken，再到按设备存储的 token（以 deviceId + role 为键）。
  • auth.bootstrapToken 仅在以上都未解析出 auth.token 时发送。共享令牌或任何已解析的 device token 都会抑制它。
  • 在一次性的 AUTH_TOKEN_MISMATCH 重试中，自动提升存储的 device token 仅限于 受信任端点 —— 回环，或带有固定 tlsFingerprint 的 wss://。未固定指纹的公共 wss:// 不符合条件。
• 额外的 hello-ok.auth.deviceTokens 条目是引导交接 token。仅当连接使用了 bootstrap 认证，且传输位于受信任通道（如 wss:// 或回环/本地配对）时，才应持久化它们。
• 如果客户端提供了 显式 deviceToken 或显式 scopes，则该调用方请求的范围集仍具有权威性；只有当客户端复用已存储的按设备 token 时，才会重用缓存的 scopes。
• Device token 可通过 device.token.rotate 和 device.token.revoke 进行轮换/撤销（需要 operator.pairing 范围）。
• device.token.rotate 会返回轮换元数据。只有对于已用该 device token认证过的同设备调用，它才会回显替换后的 bearer token，因此仅凭 token 的客户端可以在重新连接前持久化其替换值。共享/管理员轮换不会回显 bearer token。
• 令牌签发、轮换和撤销都限制在该设备配对条目中记录的已批准角色集合内；令牌变更不能扩展到配对批准从未授予的设备角色，也不能指向该角色。
• 对于已配对设备的 token 会话，设备管理默认是自我范围限定的，除非调用方同时具有 operator.admin：非管理员调用方只能移除/撤销/轮换属于 自己的 设备条目。
• device.token.rotate 和 device.token.revoke 还会检查目标 operator token 的范围集合与调用方当前会话范围是否一致。非管理员调用方不能轮换或撤销比其自身所持有范围更宽的 operator token。
• 认证失败会包含 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）
• AUTH_TOKEN_MISMATCH 的客户端行为：
  • 受信任客户端可以尝试一次受限重试，使用缓存的按设备 token。
  • 如果该重试失败，客户端应停止自动重连循环，并向操作员提供操作指导。

​

设备身份 + 配对

• 节点应包含稳定的设备身份（device.id），其来源于密钥对指纹。
• Gateway 按设备 + 角色签发 token。
• 新设备 ID 需要配对批准，除非启用了本地自动批准。
• 配对自动批准主要针对直接本地回环连接。
• OpenClaw 还有一条狭窄的后端/容器本地自连接路径，用于受信任的共享密钥辅助流程。
• 同主机 tailnet 或 LAN 连接在配对时仍被视为远程连接，并且需要批准。
• WS 客户端通常会在 connect 时包含 device 身份（operator + node）。唯一的无设备 operator 例外是明确的信任路径：
  • gateway.controlUi.allowInsecureAuth=true，用于仅 localhost 的不安全 HTTP 兼容。
  • 成功的 gateway.auth.mode: "trusted-proxy" operator Control UI 认证。
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true（紧急开关，严重降低安全性）。
  • 使用共享 gateway token/password 认证的直接回环 gateway-client 后端 RPC。
• 所有连接都必须对服务器提供的 connect.challenge nonce 进行签名。

​

设备认证迁移诊断

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

​

TLS + pinning

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

​

范围

​

相关

• Bridge protocol
• Gateway runbook