网关协议

​

npm 软件包

• @openclaw/gateway-protocol 发布架构、验证器、TypeScript 类型、轻量级帧和错误辅助工具以及版本常量。其 tarball 包含生成的 protocol.schema.json 机器可读契约。
• @openclaw/gateway-client 发布参考 Node 客户端，以及浏览器安全入口 @openclaw/gateway-client/browser。

​

传输与帧

• WebSocket、文本帧、JSON 载荷。
• 第一帧必须是 connect 请求。
• 连接建立前的帧上限为 64 KiB（MAX_PREAUTH_PAYLOAD_BYTES）。握手完成后，遵循 hello-ok.policy.maxPayload 和 hello-ok.policy.maxBufferedBytes。启用诊断后，超大的入站帧和缓慢的出站缓冲区会在网关关闭或丢弃帧之前发出 payload.large 事件。这些事件包含 surface、字节大小、限制和安全原因代码，绝不包含消息正文、附件内容、原始帧字节、令牌、Cookie 或密钥。

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

• 缺失范围：{ code: "MISSING_SCOPE", missingScope, requiredScopes }。 requiredScopes 是请求操作的完整已知范围集合。 为兼容旧客户端，保留旧版 missing scope: <scope> 消息。

​

Gateway 控制的 WebRTC 对话

​

握手

{
  "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,
      "attachments": { "maxBytes": 20971520, "maxImageBytes": 6291456 }
    }
  }
}

1. 检查每个文件的解码后大小：图像对照 maxImageBytes，其他内容对照 maxBytes。
2. 序列化整个请求，并检查其编码后大小是否不超过 policy.maxPayload。 policy.attachments 是每个附件的上限，绝不意味着整个帧一定能够容纳该附件： 附件会以 base64 传输，因此一个 20 MB 的文件在线上传输时约为 26.7 MB， 单独就会超过默认的 25 MiB 帧上限。
3. 其他所有事项以服务器为准。可接受的 MIME 类型和每条消息的处理方式不会被主动公布， 因为它们取决于入口点、解析后的模型和载荷嗅探。Gateway 可以返回类型化拒绝； 而纯文本模型运行可能会在达到其卸载上限后省略额外图像，但仍然完成请求。
4. 每次重新连接时重新读取这些值。它们是连接时快照，因此对正在运行的 mediaMaxMb 编辑，只有在重新连接后才会传达到现有连接。

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

{
  "auth": {
    "deviceToken": "…",
    "role": "node",
    "scopes": [],
    "deviceTokens": [
      {
        "deviceToken": "…",
        "role": "operator",
        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]
      }
    ]
  }
}

​

Worker 角色与封闭协议

​

客户端能力

• tool-events：接受结构化的工具生命周期事件。
• inline-widgets：能够渲染托管的内联 widget 工具结果。

​

Node 连接示例

{
  "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：用于 invoke 的命令允许列表。
• permissions：细粒度开关（例如 screen.record、camera.capture）。

​

角色和作用域

• operator：控制平面客户端（CLI/UI/自动化）。
• node：能力主机（camera/screen/canvas/system.run）。
• worker：在专用、封闭的 worker protocol 上运行的云执行主机。

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

​

能力／命令／权限（node）

• caps：高层能力类别，例如 camera、canvas、screen、 location、voice 和 talk。
• commands：用于 invoke 的命令允许列表。
• permissions：细粒度开关（例如 screen.record、camera.capture）。

​

在线状态

• system-presence 返回按设备身份键控的条目，包括 deviceId、roles 和 scopes，因此即使设备同时以 operator 和 node 身份连接， 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 以及其他仅限聊天记录的 事件。在 protocol v4 中，增量负载携带 deltaText；message 仍然是 累积的 assistant 快照。非前缀替换会设置 replace=true，并使用 deltaText 作为替换文本。
• session.message、session.operation、session.tool：已订阅会话的聊天记录、进行中的 会话操作以及事件流更新。
• session.approval：针对明确选择加入的精确会话订阅者，提供经过清理的待处理和终止审批事实。子审批使用 持久化的祖先受众；事件不会修改聊天记录或唤醒代理。
• session.observer：安全的实时会话标题和状态摘要。模型编写的 前导文本可以立即更新标题；实用模型的评估结果可用后会替换该标题。Web、iOS 和 Android 使用相同的运行范围摘要。
• sessions.changed：会话索引或元数据已更改。
• presence：系统在线状态快照更新。
• tick：定期的保活／存活事件。
• health：网关健康状态快照更新。
• heartbeat：心跳事件流更新。
• cron：cron 运行／作业变更事件。
• shutdown：网关关闭通知。
• node.pair.requested／node.pair.resolved：节点配对生命周期。
• node.invoke.request：节点调用请求广播。
• device.pair.requested／device.pair.resolved：已配对设备生命周期。
• voicewake.changed：唤醒词触发配置已更改。
• config.changed：配置写入已持久化（负载携带配置路径、新快照哈希和时间戳——从不携带配置内容）。按操作员读取范围限定；客户端通过 config.get 刷新。
• skills.changed：网关使其技能快照失效后，连接状态、技能目录、配置或资格状态发生了变化。负载中的 reason 可以是 watch、watch-targets、manual、remote-node、 config-change 或 workshop。按操作员读取范围限定；客户端通过 skills.status 刷新。
• exec.approval.requested／exec.approval.resolved：exec 审批 生命周期。
• plugin.approval.requested／plugin.approval.resolved：plugin 审批 生命周期。

​

节点助手方法

​

审计账本 RPC

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

• 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。

​

任务账本 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 会返回网关的未找到错误结构。
• tasks.cancel 需要 operator.write。
  • 参数：{ "taskId": string, "reason"?: string }。
  • 结果：{ "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }。
  • found 表示账本中是否存在匹配的任务。cancelled 表示运行时是否接受或记录了取消操作。

​

Operator 辅助方法

• commands.list（operator.read）获取某个 agent 的运行时命令清单。
  • agentId 可选；省略后读取默认 agent 工作区。
  • scope 控制主 name 所指向的界面：text 返回不带前导 / 的主文本命令令牌；native 和默认的 both 路径在可用时返回 provider 感知的原生命令名称。
  • textAliases 携带准确的斜杠别名，例如 /model 和 /m。
  • nativeName 携带 provider 感知的原生命令名称（如果存在）。
  • provider 可选，仅影响原生命名以及原生插件命令的可用性。
  • includeArgs=false 会从响应中省略序列化的参数元数据。
• tools.catalog（operator.read）获取某个 agent 的运行时工具目录。响应包括分组工具和来源元数据：
  • source：core 或 plugin
  • pluginId：当 source="plugin" 时的插件所有者
  • optional：插件工具是否为可选工具
• tools.effective（operator.read）获取某个会话的运行时有效工具清单。
  • 必须提供 sessionKey。
  • 网关在服务端从会话中派生可信的运行时上下文，而不是接受调用方提供的身份验证或传递上下文。
  • 响应是会话范围内、由服务端派生的活动工具清单投影，其中包括核心工具、插件工具、频道工具，以及已发现的 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 相同的网关策略路径调用一个可用工具。
  • 必须提供 name。args、sessionKey、agentId、confirm 和 idempotencyKey 可选。
  • 如果同时提供了 sessionKey 和 agentId，解析出的会话 agent 必须与 agentId 匹配。
  • 仅所有者可用的核心包装器，例如 cron、gateway 和 nodes，要求所有者／管理员身份（operator.admin），即使 tools.invoke 本身是 operator.write。
  • 响应是面向 SDK 的信封，包含 ok、toolName、可选的 output 以及类型化的 error 字段。审批或策略拒绝会在载荷中返回 ok:false，而不是绕过网关工具策略管道。
• skills.status（operator.read）获取某个 agent 可见的技能清单。
  • 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 安装。
  • 网关安装器模式：{ name, installId, timeoutMs? } 在网关主机上运行声明的 metadata.openclaw.install 操作。旧版客户端可能仍会发送 dangerouslyForceUnsafeInstall；此字段已弃用，仅为协议兼容而接受，并会被忽略。请使用 security.installPolicy 处理由 Operator 所有的安装决策。
• skills.update（operator.admin）有两种模式：
  • ClawHub 模式更新默认 agent 工作区中一个受跟踪的 slug，或所有受跟踪的 ClawHub 安装。
  • 配置模式修改 skills.entries.<skillKey> 值，例如 enabled、apiKey 和 env。

​

models.list 视图

• 省略或使用 "default"：如果配置了 agents.defaults.modelPolicy.allow，响应就是允许的目录，其中包括针对 provider/* 条目的动态发现模型。否则，响应就是完整的网关目录。
• "configured"：选择器大小的行为。如果配置了 agents.defaults.modelPolicy.allow，它仍然优先，包括针对 provider/* 条目的 provider 范围发现。没有允许列表时，响应使用显式的 models.providers.<provider>.models 条目；仅当不存在已配置的模型行时，才回退到完整目录。
• "provider-config"：由来源编写的 models.providers.*.models 清单，独立于选择器允许列表。行中包括公开的模型能力和路由感知的可用性，但省略 provider 端点、身份验证材料以及运行时请求配置。
• "all"：完整的网关目录，绕过 agents.defaults.modelPolicy.allow。用于诊断／发现界面，不用于常规模型选择器。

​

Exec 审批

• 当 Exec 请求需要审批时，网关会广播 exec.approval.requested。
• Operator 客户端通过调用 exec.approval.resolve（需要 operator.approvals）来完成处理。
• 对于 host=node，exec.approval.request 必须包含 systemRunPlan（规范的 argv／cwd／rawCommand／session metadata）。缺少 systemRunPlan 的请求会被拒绝。
• 审批通过后，转发的 node.invoke system.run 调用会将该规范的 systemRunPlan 重新用作权威的命令／cwd／会话上下文。
• 如果调用方在准备阶段与最终获批的 system.run 转发之间修改了 command、rawCommand、cwd、agentId 或 sessionKey，网关会拒绝运行，而不是信任已被修改的负载。

​

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、MIN_CLIENT_PROTOCOL_VERSION、 MIN_NODE_PROTOCOL_VERSION 和 MIN_PROBE_PROTOCOL_VERSION 位于 packages/gateway-protocol/src/version.ts。
• 客户端发送 minProtocol + maxProtocol。Operator 和 UI 客户端必须将当前协议包含在该范围内；当前客户端和服务器运行协议 v4。
• 同时具有 role: "node" 和 client.mode: "node" 的已认证客户端可以使用 N-1 节点协议（当前为 v3）。轻量级重启探针使用相同的 N-1 窗口。设备认证、配对、作用域、命令策略和 exec 审批不会因该兼容性窗口而改变。在节点升级到当前协议之前，会暂缓提供插件拥有的节点能力和命令，因为其托管表面不属于 N-1 合约。
• Schema 和模型由 TypeBox 定义生成：
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

客户端常量

​

身份验证

• 共享密钥网关身份验证根据配置的 gateway.auth.mode（"none" | "token" | "password" | "trusted-proxy"），使用 connect.params.auth.token 或 connect.params.auth.password。
• 带有身份信息的模式，例如 Tailscale Serve（gateway.auth.allowTailscale: true） 或非 loopback 的 gateway.auth.mode: "trusted-proxy"，会通过请求标头而不是 connect.params.auth.* 满足 connect 身份验证检查。
• 私有入口的 gateway.auth.mode: "none" 会完全跳过共享密钥 connect 身份验证；不要在公共／不受信任的入口上暴露该模式。
• 配对后，网关会签发一个限定于连接角色＋已批准授权的设备令牌，并在 hello-ok.auth.deviceToken 中返回。成功 connect 后，如果该令牌是新的或不同于已存储的令牌，客户端应将其与 hello-ok.auth.scopes 一起持久化。
• hello-ok.auth.scopes 是当前 socket 的实时权限，并与 RPC 分发所执行的 scopes 相匹配。
• 当 hello-ok.auth.deviceToken 与同一网关、设备、客户端和角色已存储的令牌完全匹配时，应保留该记录中存储的 scopes，而不是将其替换为更窄的实时 scope 集合。新签发或轮换后的令牌使用 hello-ok.auth.scopes；该令牌签发时，其已批准授权与该连接相匹配。
• 使用已存储的设备令牌重新连接时，也应复用该令牌已存储的已批准 scope 集合。这样可以保留已授予的读取／探测／状态访问权限，并避免将重新连接静默收缩为更窄的隐式管理员专属 scope。
• 客户端侧的 connect 身份验证组装（packages/gateway-client/src/client.ts 中的 selectConnectAuth）：
  • auth.password 是正交的，只要设置就始终转发。
  • auth.token 按以下优先顺序填充：首先是显式共享令牌，然后是显式 deviceToken，最后是按 deviceId＋role 索引的已存储每设备令牌。
  • 只有在上述选项都未解析出 auth.token 时，才会发送 auth.bootstrapToken。共享令牌或任何已解析的设备令牌都会抑制它。
  • 在一次性的 AUTH_TOKEN_MISMATCH 重试中，已存储设备令牌的自动提升仅对受信任端点开放：loopback，或带有固定 tlsFingerprint 的 wss://。未固定指纹的公共 wss:// 不符合条件。
• 内置设置码 bootstrap 会返回主节点的 hello-ok.auth.deviceToken，以及一个用于受信任移动端交接的有界 operator 令牌，并在 hello-ok.auth.deviceTokens 中返回。该 operator 令牌包含用于原生 Talk 配置读取的 operator.talk.secrets，但排除配对变更 scopes 和 operator.admin。
• hello-ok.auth.deviceTokens 仅包含额外的 bootstrap 交接令牌。不要将其用作主要 deviceToken 重连记录的元数据。
• 当非 baseline 设置码 bootstrap 等待批准时， PAIRING_REQUIRED 详情会包含 recommendedNextStep: "wait_then_retry"、 retryable: true 和 pauseReconnect: false。使用相同的 bootstrap 令牌持续重新连接，直到请求获批或令牌失效。
• 仅当 connect 使用了受信任传输上的 bootstrap 身份验证时，才持久化 hello-ok.auth.deviceTokens，例如 wss:// 或 loopback／本地配对。
• 如果客户端提供了显式 deviceToken 或显式 scopes，则调用方请求的 scope 集合在实时连接中保持权威，并在 hello-ok.auth.scopes 中报告；仅当客户端复用已存储的每设备令牌时，才会复用缓存的令牌授权 scopes。
• 设备令牌可以通过 device.token.rotate 和 device.token.revoke 进行轮换／撤销（需要 operator.pairing）。轮换或撤销 node 或其他非 operator 角色还需要 operator.admin。
• device.token.rotate 会返回轮换元数据。只有对于已经使用该设备令牌完成身份验证的同设备调用，才会回显替换后的 bearer 令牌，以便仅使用令牌的客户端在重新连接前持久化替换令牌。共享／管理员轮换不会回显 bearer 令牌。
• 令牌签发、轮换和撤销始终受限于该设备配对条目中记录的已批准角色集合；令牌变更不能扩展到或针对配对批准从未授予的设备角色。
• 对于已配对设备令牌会话，设备管理的范围限定于自身，除非调用方还具有 operator.admin：非管理员调用方只能管理其自身设备条目的 operator 令牌。Node 和其他非 operator 令牌的管理仅限管理员，即使是针对调用方自己的设备也一样。
• device.token.rotate 和 device.token.revoke 还会根据调用方当前会话 scopes 检查目标 operator 令牌的 scope 集合。 非管理员调用方不能轮换或撤销 scope 范围比其自身已持有权限更广的 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 （packages/gateway-protocol/src/connect-error-details.ts）。
• AUTH_TOKEN_MISMATCH 的客户端行为：
  • 受信任客户端可以使用缓存的每设备令牌尝试一次有界重试。
  • 如果该重试失败，则停止自动重连循环，并向操作员显示操作指引。
• AUTH_SCOPE_MISMATCH 表示设备令牌已被识别，但未覆盖所请求的角色／scopes。不要将其显示为令牌错误；应提示操作员重新配对，或批准范围更窄／更宽的 scope 合约。

​

设备身份与配对

• 节点应包含稳定的设备身份（device.id），该身份由密钥对指纹派生。
• 网关按设备和角色签发令牌。
• 除非启用了本地自动批准，否则新设备 ID 必须经过配对批准。
• 配对自动批准以直接本地回环连接为中心。
• OpenClaw 还为受信任的共享密钥辅助流程提供了一条范围狭窄的后端／容器本地自连接路径。
• 同主机 tailnet 或 LAN 连接在配对时仍被视为远程连接，并且需要批准。
• WS 客户端通常会在 connect 期间包含 device 身份（操作员 + 节点）。唯一不包含设备身份的操作员例外是明确的信任路径：
  • 成功通过 gateway.auth.mode: "trusted-proxy" 进行操作员 Control UI 身份验证。
  • 保留的内部辅助路径上的直接回环 gateway-client 后端 RPC。
• 省略设备身份会产生范围影响。当无设备身份的操作员连接通过明确的信任路径获准时，除非该路径具有具名的范围保留例外，OpenClaw 仍会将自行声明的范围清除为空集。随后，受范围限制的方法会失败，并返回 missing scope。
• 保留的直接回环 gateway-client 后端辅助路径仅为内部本地控制平面 RPC 保留范围；自定义后端 ID 不享有此例外。
• 所有连接都必须对服务器提供的 connect.challenge nonce 进行签名。

​

设备认证迁移诊断

• 始终等待 connect.challenge。
• 使用 connect.challenge.payload.ts 作为 connect.params.device.signedAt。
• 对包含服务器 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 客户端
• 嵌入 OpenClaw
• Bridge 协议
• Gateway 运行手册。