Gateway 网关协议

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/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 限制。启用诊断后，过大的入站帧和缓慢的出站缓冲区会在 Gateway 网关关闭连接或丢弃受影响帧之前发出 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?}

​

角色 + 作用域

​

角色

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

​

作用域（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：细粒度开关（例如 screen.record、camera.capture）。

​

在线状态

• system-presence 返回按设备身份键控的条目。
• 在线状态条目包含 deviceId、roles 和 scopes，因此即使设备同时以 operator 和 node 身份连接，UI 也能为每个设备显示一行。
• 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 事件和工具调用结果）至少需要 operator.read。没有 operator.read 的会话会完全跳过这些帧。
• 插件定义的 plugin.* 广播会根据插件注册方式，被门控到 operator.write 或 operator.admin。
• Status 和传输事件（heartbeat、presence、tick、连接/断开连接生命周期等）保持不受限制，以便每个已认证会话都能观察传输健康状态。
• 未知广播事件族默认受作用域门控（失败关闭），除非已注册处理程序明确放宽它们。

​

常见 RPC 方法族

​

常见事件系列

• chat：UI 聊天更新，例如 chat.inject 和其他仅 transcript 的聊天事件。
• session.message 和 session.tool：已订阅会话的 transcript/事件流更新。
• 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：插件审批生命周期。

​

节点辅助方法

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

​

操作员辅助方法

• 操作者可以调用 commands.list（operator.read）来获取某个智能体的运行时命令清单。
  • agentId 是可选的；省略它会读取默认智能体工作区。
  • 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 网关会从服务器端的会话派生可信运行时上下文，而不是接受调用方提供的认证或投递上下文。
  • 响应按会话限定范围，并反映当前活动对话现在可使用的内容，包括核心、插件和渠道工具。
• 操作者可以调用 tools.invoke（operator.write）通过与 /tools/invoke 相同的 Gateway 网关策略路径调用一个可用工具。
  • name 是必需的。args、sessionKey、agentId、confirm 和 idempotencyKey 是可选的。
  • 如果同时存在 sessionKey 和 agentId，解析出的会话智能体必须与 agentId 匹配。
  • 响应是面向 SDK 的信封，包含 ok、toolName、可选的 output，以及带类型的 error 字段。批准或策略拒绝会在载荷中返回 ok:false，而不是绕过 Gateway 网关工具策略管线。
• 操作者可以调用 skills.status（operator.read）来获取某个智能体的可见 Skills 清单。
  • agentId 是可选的；省略它会读取默认智能体工作区。
  • 响应包含资格、缺失要求、配置检查，以及经过清理的安装选项，不会暴露原始密钥值。
• 操作者可以调用 skills.search 和 skills.detail（operator.read）获取 ClawHub 发现元数据。
• 操作者可以通过两种模式调用 skills.install（operator.admin）：
  • ClawHub 模式：{ source: "clawhub", slug, version?, force? } 将一个 Skill 文件夹安装到默认智能体工作区的 skills/ 目录中。
  • Gateway 网关安装器模式：{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } 在 Gateway 网关主机上运行声明的 metadata.openclaw.install 操作。
• 操作者可以通过两种模式调用 skills.update（operator.admin）：
  • ClawHub 模式会更新一个已跟踪的 slug，或更新默认智能体工作区中所有已跟踪的 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 请求需要批准时，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 会话或含糊的多渠道配置）。

​

版本控制

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

​

客户端常量

​

认证

• 共享密钥 Gateway 网关认证使用 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 网关会颁发一个限定到连接 role + scopes 的设备令牌。 它会在 hello-ok.auth.deviceToken 中返回，并应由客户端持久化以供未来连接使用。
• 客户端应在任何成功连接后持久化主 hello-ok.auth.deviceToken。
• 使用该已存储设备令牌重新连接时，也应复用为该令牌存储的已批准 scope 集合。 这会保留已经授予的读取/探测/Status 访问，并避免将重新连接静默收缩为 更窄的隐式仅管理员 scope。
• 客户端连接认证组装（src/gateway/client.ts 中的 selectConnectAuth）：
  • auth.password 是正交的，设置后始终会转发。
  • auth.token 按优先级填充：先是显式共享令牌， 然后是显式 deviceToken，再然后是存储的单设备令牌（按 deviceId + role 作为键）。
  • 仅当以上都没有解析出 auth.token 时，才会发送 auth.bootstrapToken。 共享令牌或任何已解析的设备令牌都会抑制它。
  • 在一次性 AUTH_TOKEN_MISMATCH 重试中自动提升已存储设备令牌， 仅限于可信端点 — 回环，或带有固定 tlsFingerprint 的 wss://。 未固定指纹的公开 wss:// 不符合条件。
• 额外的 hello-ok.auth.deviceTokens 条目是 bootstrap 交接令牌。 仅当连接在可信传输（例如 wss:// 或回环/local pairing）上使用 bootstrap 认证时才持久化它们。
• 如果客户端提供显式 deviceToken 或显式 scopes，则调用方请求的 scope 集合仍然是权威来源；只有在客户端复用已存储的单设备令牌时， 才会复用缓存的 scopes。
• 设备令牌可以通过 device.token.rotate 和 device.token.revoke 轮换/吊销（需要 operator.pairing scope）。
• device.token.rotate 返回轮换元数据。只有在同一设备调用且已使用该设备令牌完成认证时， 它才会回显替换的 bearer token，以便仅令牌客户端可在重新连接前持久化替换令牌。 共享/管理员轮换不会回显 bearer token。
• 令牌颁发、轮换和吊销始终限定在该设备配对条目中记录的已批准 role 集合内； 令牌变更不能扩展或指向配对批准从未授予的设备 role。
• 对于已配对设备令牌会话，除非调用方也拥有 operator.admin， 否则设备管理是自限定的：非管理员调用方只能移除/吊销/轮换其自己的设备条目。
• device.token.rotate 和 device.token.revoke 还会根据调用方当前会话 scopes 检查目标 operator token scope 集合。非管理员调用方不能轮换或吊销比自己已持有范围更广的 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 的客户端行为：
  • 可信客户端可尝试一次有界重试，使用缓存的单设备令牌。
  • 如果该重试失败，客户端应停止自动重新连接循环，并显示 operator 操作指引。

​

设备身份 + 配对

• 节点应包含一个稳定的设备身份 (device.id)，派生自密钥对指纹。
• Gateway 网关会按设备 + role 颁发令牌。
• 除非启用了本地自动批准，否则新的设备 ID 需要配对批准。
• 配对自动批准以直接 local loopback 连接为中心。
• OpenClaw 还有一个狭窄的后端/container-local 自连接路径， 用于可信共享密钥辅助流程。
• 同主机 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 网关令牌/密码认证的 direct-loopback gateway-client 后端 RPC。
• 所有连接都必须对服务器提供的 connect.challenge nonce 签名。

​

设备认证迁移诊断

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

​

TLS + 固定

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

​

范围

​

相关

• Bridge protocol
• Gateway 网关运行手册