身份验证与设备身份
客户端如何证明自己的身份:握手认证路径、设备身份与配对签名,以及 TLS 固定。
认证¶
所属页面:网关认证 — 认证模式、令牌/密码设置,以及此线上契约所强制执行的面向操作员的策略。
- 共享密钥网关认证接受在
connect.params.auth.token或connect.params.auth.password中配置的密钥。gateway.auth.mode: "token"选择gateway.auth.token;"password"选择gateway.auth.password。该模式选择的是已配置的密钥,而不是所需的线上字段。 - 身份承载模式(如 Tailscale Serve(
gateway.auth.allowTailscale: true)或非回环的gateway.auth.mode: "trusted-proxy")通过请求头满足连接认证检查,而不是通过connect.params.auth.*。 - 私有入口
gateway.auth.mode: "none"完全跳过共享密钥连接认证;不要在公共/不受信任的入口上暴露该模式。 - 配对完成后,网关会签发一个设备令牌,其作用域限定为连接角色 + 已批准的授权,并通过
hello-ok.auth.deviceToken返回。当令牌是新的或与已存储令牌不同时,客户端应在成功连接后将它与hello-ok.auth.scopes一起持久化。 hello-ok.auth.scopes是当前套接字的实时权限,并且与 RPC 分发所强制执行的作用域一致。- 当
hello-ok.auth.deviceToken与已为同一网关、设备、客户端和角色存储的令牌完全匹配时,保留该记录中已存储的作用域,而不是用更窄的实时作用域集替换它们。新签发或轮换的令牌使用hello-ok.auth.scopes;其已批准的授权在签发时与该连接匹配。 - 使用该已存储设备令牌重新连接时,也应复用该令牌已存储的已批准作用域集。这可以保留已经授予的读取/检查/状态访问权限,并避免将重连静默收缩为更窄的隐式仅管理员作用域。
- 客户端连接认证组装(
packages/gateway-client/src/client.ts中的selectConnectAuth): auth.password在设置后始终会被转发。任一共享密钥字段都可以携带已配置的密钥;当两者都提供时,网关会使用与其认证模式匹配的字段。auth.token按优先级顺序填充:首先是显式共享令牌,然后是显式deviceToken,最后是存储的按设备令牌(以deviceId+role为键)。- 仅当以上各项都无法解析出
auth.token时,才发送auth.bootstrapToken。共享令牌或任何已解析的设备令牌都会抑制它的发送。 - 在一次性
AUTH_TOKEN_MISMATCH重试中,存储设备令牌的自动提升仅限受信任端点:回环,或带固定tlsFingerprint的wss://。没有固定证书的公网wss://不符合条件。 - 内置设置码引导返回主节点
hello-ok.auth.deviceToken,并在hello-ok.auth.deviceTokens中附带一个受限的操作员令牌,用于受信任的移动端交接。该操作员令牌包含operator.talk.secrets,用于原生 Talk 配置读取,但排除配对变更作用域和operator.admin。 hello-ok.auth.deviceTokens仅包含额外的引导交接令牌。不要将其用作主deviceToken重连记录的元数据。- 当非基线设置码引导等待批准时,
PAIRING_REQUIRED详情包含recommendedNextStep: "wait_then_retry"、retryable: true和pauseReconnect: false。持续使用同一个引导令牌重连,直到请求被批准或令牌失效。 - 仅当连接在受信任传输(如
wss://或回环/本地配对)上使用引导认证时,才持久化hello-ok.auth.deviceTokens。 - 如果客户端提供了显式
deviceToken或显式scopes,该调用方请求的作用域集对实时连接保持权威,并会在hello-ok.auth.scopes中报告;只有客户端复用已存储的按设备令牌时,才会复用缓存的令牌授权作用域。 - 设备令牌可以通过
device.token.rotate和device.token.revoke进行轮换/撤销(需要operator.pairing)。轮换或撤销节点或其他非操作员角色的令牌还需要operator.admin。 device.token.rotate返回轮换元数据。它仅对已经使用该设备令牌认证的同设备调用回显替换持有者令牌,以便仅使用令牌的客户端在重连前持久化其替换令牌。共享/管理员轮换不会回显持有者令牌。- 令牌签发、轮换和撤销始终受限于该设备配对条目中记录的已批准角色集;令牌变更不能扩展或针对配对批准从未授予过的设备角色。
- 对于已配对设备令牌会话,设备管理为自限作用域,除非调用方还拥有
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的行为: - 原生 Apple 客户端必须先将
canRetryWithDeviceToken=true,然后才允许在受信任端点上使用缓存的按设备令牌进行一次有限重试。如果该标志为 false 或缺失,将暂停自动重试,并使存储的设备令牌不会用于后续的共享令牌连接。 - 如果该重试失败,请停止自动重连循环,并显示操作员操作指引。
AUTH_SCOPE_MISMATCH表示设备令牌已被识别,但不覆盖所请求的角色/作用域。不要将此作为无效令牌处理;提示操作员重新配对或批准更窄/更宽的作用域契约。OPERATOR_ACCESS_DENIED表示人员已通过认证,但网关的操作员访问策略(例如绑定到accessPolicyPlugin的角色)当前未授予任何访问权限。这不是凭据问题。请以退避方式持续重连,以便新授予的访问权限无需用户操作即可生效,并向管理员显示分配角色或授予访问权限的指引。
设备身份与配对¶
负责人页面:网关配对 — 这些字段背后的审批流程、设备记录和 CLI 界面。
- 节点应包含一个稳定的设备身份(
device.id),该身份由密钥对指纹派生。 - 网关按设备 + 角色签发令牌。
- 除非启用了本地自动审批,否则新的设备 ID 需要配对审批。
- Control UI 操作员客户端可以保持其预审批套接字打开。带有
details.code: "PAIRING_REQUIRED"和details.waitForResolution: true的NOT_PAIRED连接响应会将等待绑定到details.requestId和details.deviceId。 这不是一个已准入会话:没有可用的 RPC、订阅或其他客户端的配对事件。 网关仅针对该确切请求/设备发送现有的device.pair.resolved事件,并将decision设置为approved、rejected或expired,然后关闭套接字。 被取代的请求仅关闭其等待套接字,而不报告审批或拒绝。审批或被取代请求的 关闭会触发新的已认证连接;事件本身从不授予访问权限。拒绝和过期会停止自动 重连,直到明确的用户操作。浏览器将这些终止结果暴露为PAIRING_REJECTED和PAIRING_EXPIRED错误详细代码。等待器是连接本地的,并在断开连接时移除; 不会持久化拒绝历史。未处理waitForResolution的客户端仍可在失败的连接 响应后关闭。这些是附加的详细信息和事件语义,而不是协议版本变更。 - 如果审批与重连重叠,网关会在完成握手之前检查当前已配对的设备。已批准的 密钥、角色、作用域和固定的客户端元数据必须授权该连接;仅凭一个已消费请求 不会授予访问权限。
- 配对自动审批以直接本地回环连接为中心。
- 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随机数进行签名。
设备身份验证迁移诊断¶
对于仍使用挑战前签名行为的旧版客户端,connect 会在 error.details.code
下返回 DEVICE_AUTH_* 详细代码,并附带稳定的 error.details.reason。
常见迁移失败:
| 消息 | details.code | details.reason | 含义 |
|---|---|---|---|
device nonce required |
DEVICE_AUTH_NONCE_REQUIRED |
device-nonce-missing |
客户端省略了 device.nonce(或发送了空值)。 |
device nonce mismatch |
DEVICE_AUTH_NONCE_MISMATCH |
device-nonce-mismatch |
客户端使用过期/错误的随机数进行了签名。 |
device signature invalid |
DEVICE_AUTH_SIGNATURE_INVALID |
device-signature |
签名负载与 v2 负载不匹配。 |
device signature expired |
DEVICE_AUTH_SIGNATURE_EXPIRED |
device-signature-stale |
签名时间戳超出允许的偏差范围。 |
device identity mismatch |
DEVICE_AUTH_DEVICE_ID_MISMATCH |
device-id-mismatch |
device.id 与公钥指纹不匹配。 |
device public key invalid |
DEVICE_AUTH_PUBLIC_KEY_INVALID |
device-public-key |
公钥格式/规范化失败。 |
迁移目标:
- 始终等待
connect.challenge。 - 将
connect.challenge.payload.ts用作connect.params.device.signedAt。 - 对包含服务器随机数的 v2 负载进行签名。
- 在
connect.params.device.nonce中发送相同的随机数。 - 首选签名负载为
v3(packages/gateway-client/src/device-auth.ts中的buildDeviceAuthPayloadV3), 除设备/客户端/角色/作用域/令牌/随机数字段外,它还绑定platform和deviceFamily。 - 旧版
v2签名仍被接受以保持兼容性,但配对设备元数据固定仍会在重连时控制 命令策略。
TLS 与证书固定¶
负责人页面:远程访问 — 配置 gateway.tls 并获取客户端固定的指纹。
- WS 连接支持 TLS(
gateway.tls配置)。 - 客户端可选择通过
gateway.remote.tlsFingerprint或 CLI--tls-fingerprint固定网关证书指纹。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw