Gateway 网关协议

Documentation Index

Fetch the complete documentation index at: https://docs2.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": 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": {
    "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": 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": "…"
    }
  }
}

​

成帧

• 请求：{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.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：高级能力类别，例如 camera、canvas、screen、location、voice 和 talk。
• commands：用于调用的命令允许列表。
• permissions：细粒度开关（例如 screen.record、camera.capture）。

​

在线状态

• system-presence 返回按设备身份键控的条目。
• 在线状态条目包含 deviceId、roles 和 scopes，这样即使设备同时以操作员和节点身份连接，UI 也可以为每台设备显示单独一行。
• node.list 包含可选的 lastSeenAtMs 和 lastSeenReason 字段。已连接的节点会以原因 connect 将其当前连接时间报告为 lastSeenAtMs；当受信任的节点事件更新其配对元数据时，已配对节点也可以报告持久的后台在线状态。

​

节点后台存活事件

{
  "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 和其他仅用于转录的聊天 事件。
• session.message 和 session.tool：已订阅会话的转录/事件流更新。
• sessions.changed：会话索引或元数据已更改。
• presence：系统在线状态快照更新。
• tick：周期性 keepalive / 存活事件。
• 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 来获取当前技能可执行文件列表， 用于自动允许检查。

​

任务台账 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 报告运行时是否接受或记录了取消。

​

操作员辅助方法

• 操作员可以调用 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 网关会从服务端会话派生可信运行时上下文，而不是接受 调用方提供的认证或投递上下文。
  • 响应限定在会话范围内，并反映当前活跃对话现在可以使用的内容， 包括核心、插件和渠道工具。
• 操作员可以调用 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）来获取某个智能体的可见 技能清单。
  • 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, dangerouslyForceUnsafeInstall?, timeoutMs? } 在 Gateway 网关主机上运行声明的 metadata.openclaw.install 操作。
• 操作员可以通过两种模式调用 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/* 条目的提供商范围发现。如果没有允许列表，响应会使用显式 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 投递回退

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

​

版本控制

• PROTOCOL_VERSION 位于 src/gateway/protocol/version.ts。
• 客户端发送 minProtocol + maxProtocol；服务端会拒绝不包含其当前协议的范围。 原生客户端使用 v3 下界，因此增量式 v4 客户端仍可访问 v3 Gateway 网关。
• Schema + 模型从 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 网关会签发一个限定到连接角色 + 范围的设备令牌。 它会在 hello-ok.auth.deviceToken 中返回，客户端应将其持久化以供后续连接使用。
• 客户端应在任何成功连接后持久化主 hello-ok.auth.deviceToken。
• 使用该已存储设备令牌重新连接时，也应复用为该令牌存储的已批准范围集。 这会保留已授予的读取/探测/状态访问权限，并避免重连被静默收窄为 更窄的隐式仅管理员范围。
• 客户端连接认证组装（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 条目是引导交接令牌。 只有当连接在可信传输（例如 wss:// 或环回/本地配对）上使用引导认证时， 才持久化它们。
• 如果客户端提供了显式 deviceToken 或显式 scopes， 该调用方请求的范围集仍然是权威来源；只有在客户端复用已存储的每设备令牌时， 才会复用缓存范围。
• 设备令牌可以通过 device.token.rotate 和 device.token.revoke 轮换/撤销（需要 operator.pairing 范围）。
• device.token.rotate 返回轮换元数据。它只会在同设备调用且该调用已使用 该设备令牌完成认证时回显替换用 bearer 令牌，因此仅令牌客户端可以在重连前 持久化替换令牌。共享/管理员轮换不会回显 bearer 令牌。
• 令牌签发、轮换和撤销会受限于该设备配对条目中记录的已批准角色集； 令牌变更不能扩展或指向配对审批从未授予的设备角色。
• 对于已配对设备令牌会话，除非调用方还拥有 operator.admin， 否则设备管理仅限自身范围：非管理员调用方只能移除/撤销/轮换 自己的设备条目。
• device.token.rotate 和 device.token.revoke 还会根据调用方当前会话范围 检查目标 operator 令牌范围集。非管理员调用方不能轮换或撤销比自己已持有范围 更广的 operator 令牌。
• 认证失败包含 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 操作指导。
• AUTH_SCOPE_MISMATCH 表示设备令牌已被识别，但不覆盖 请求的角色/范围。客户端不应将其呈现为错误令牌； 应提示 operator 重新配对或批准更窄/更宽的范围契约。

​

设备身份 + 配对

• 节点应包含一个稳定设备身份 (device.id)，该身份派生自 密钥对指纹。
• Gateway 网关按设备 + 角色签发令牌。
• 除非启用了本地自动批准，否则新的设备 ID 需要配对批准。
• 配对自动批准以直接 local loopback 连接为中心。
• OpenClaw 还有一条狭窄的后端/容器本地自连接路径，用于 可信共享密钥辅助流程。
• 同主机 tailnet 或 LAN 连接在配对时仍被视为远程连接， 并需要批准。
• WS 客户端通常在 connect 期间包含 device 身份（operator + 节点）。唯一无设备 operator 例外是显式信任路径：
  • gateway.controlUi.allowInsecureAuth=true，用于仅 localhost 的不安全 HTTP 兼容性。
  • 成功的 gateway.auth.mode: "trusted-proxy" operator Control UI 认证。
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true（破窗选项，严重安全降级）。
  • 直接环回的 gateway-client 后端 RPC，使用共享 Gateway 网关令牌/密码认证。
• 所有连接都必须签名服务器提供的 connect.challenge nonce。

​

设备认证迁移诊断

• 始终等待 connect.challenge。
• 签名包含服务器 nonce 的 v2 载荷。
• 在 connect.params.device.nonce 中发送相同 nonce。
• 首选签名载荷是 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 网关运行手册