OpenClaw 设备配对和 token 管理通过 openclaw devices 子命令完成。要处理待审批请求，先用 openclaw devices list 查看当前 ID，再用 openclaw devices approve <requestId> 精确批准（省略 ID 或 --latest 仅预览，不会自动签发 token）。如果遇到 AUTH_TOKEN_MISMATCH 或 AUTH_DEVICE_TOKEN_MISMATCH，按“token 漂移恢复清单”依次检查 token 来源、轮换设备 token 或重新配对。autoApproveCidrs 策略仅对首次 role: node 请求生效，默认关闭，不用于 operator/browser 或升级请求。

openclaw devices 设备配对与 token 管理

命令详解

openclaw devices list

列出待处理的配对请求和已配对设备。

openclaw devices list
openclaw devices list --json

待处理请求的输出会显示设备请求的角色/权限范围，并与当前已批准的权限范围并列展示。这样角色/权限升级时能明确看出变化，而不是让用户误以为配对丢失了。

openclaw devices remove <deviceId>

移除单个已配对设备条目。

使用配对设备 token 认证时，非管理员调用者只能移除 自己的 设备条目。移除其他设备需要 operator.admin 权限。

openclaw devices remove <deviceId>
openclaw devices remove <deviceId> --json

openclaw devices clear --yes [--pending]

批量清除已配对设备。需显式传入 --yes 确认。

• 不加 --pending：清除所有已配对设备（不含待审批请求）。
• 加 --pending：仅清除待审批请求，不清除已配对设备。

openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json

openclaw devices approve [requestId] [--latest]

批准待处理的设备配对请求。

• 如果省略 requestId 或传了 --latest，OpenClaw 仅打印 最新的待审批请求信息并退出；不会自动签发 token。你需要先验证请求详情，然后带上精确的 requestId 再次运行审批。
• 如果设备已配对且请求更宽的权限范围（升级请求），OpenClaw 会保留现有批准状态，同时创建一个新的待审批升级请求。请用 openclaw devices list 查看 Requested vs Approved 列，或用 openclaw devices approve --latest 预览升级内容后再批准。

注意：如果设备以更改的认证信息（角色、权限范围或公钥）重试配对，OpenClaw 会取代之前的待审批条目并生成新的 requestId。批准前请先运行 openclaw devices list 确认当前 ID。

如果 Gateway 显式配置了 gateway.nodes.pairing.autoApproveCidrs，首次 role: node 请求且客户端 IP 匹配该 CIDR 时，可以自动批准而无需出现在审批列表中。该策略默认关闭，且不应用于 operator/browser 客户端或升级请求。

openclaw devices approve
openclaw devices approve <requestId>
openclaw devices approve --latest

openclaw devices reject <requestId>

拒绝待处理的设备配对请求。

openclaw devices reject <requestId>

openclaw devices rotate --device &lt;id&gt; --role &lt;role&gt; [--scope <scope...>]

为指定设备的特定角色轮换 token，同时可更新该角色的权限范围。

• 目标角色必须已在设备已批准的配对合约中存在；轮换不能创建未批准的角色。
• 如果省略 --scope，后续重连时使用该 token 缓存的已批准范围。如果显式传入 --scope，则成为将来缓存 token 重连时的存储范围集合。
• 非管理员配对设备调用者只能轮换 自己的 token。
• 目标 token 的权限范围必须在调用者会话自身的 operator 范围之内；轮换不能创建或保留比调用者已有 operator 更宽的范围。

openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write

返回旋转元数据的 JSON。如果调用者在用该设备 token 认证时旋转自己的 token，响应会同时包含替换后的新 token（以便客户端在重连前持久化）。共享/管理员发起的轮换不返回 bearer token。

openclaw devices revoke --device <id> --role <role>

吊销指定设备的特定角色 token。

• 非管理员配对设备调用者只能吊销 自己的 token。吊销其他设备的 token 需要 operator.admin。
• 目标 token 的权限范围必须在调用者会话自身的 operator 范围之内；仅配对权限的调用者不能吊销 admin/write 级别的 operator token。

openclaw devices revoke --device <deviceId> --role node

返回吊销结果的 JSON。

通用选项

• --url <url>：Gateway WebSocket URL（已配置 gateway.remote.url 时默认使用）。
• --token <token>：Gateway token（需要时传入）。
• --password <password>：Gateway 密码（密码认证）。
• --timeout <ms>：RPC 超时时间。
• --json：JSON 格式输出（推荐用于脚本场景）。

警告：设置 --url 时，CLI 不会回退到配置或环境变量中的凭证，必须显式传入 --token 或 --password，否则报错。

注意事项

• Token 轮换会返回新 token（敏感信息），请像对待 secret 一样妥善保管。
• 这些命令需要 operator.pairing（或 operator.admin）权限范围。某些审批操作还要求调用者持有目标设备将要生成或继承的 operator 范围；参见 Operator scopes。
• gateway.nodes.pairing.autoApproveCidrs 是可选启用的 Gateway 策略，仅适用于全新的 node 设备配对；不改变 CLI 审批权限。
• Token 轮换和吊销都限制在设备已批准的配对角色集和已批准的基础权限范围内。任何缓存的 token 条目本身不赋予 token 管理目标。
• 对于配对设备 token 会话，跨设备管理仅限管理员：remove、rotate、revoke 默认只能操作自己的设备，除非调用者有 operator.admin。
• Token 变更也受调用者范围限制：仅配对权限的 session 不能轮换或吊销当前携带 operator.admin 或 operator.write 的 token。
• devices clear 强制要求 --yes 确认。
• 如果本地 loopback 上无法使用 pairing 范围（且未传入显式 --url），list 和 approve 可使用本地 pairing 回退。
• devices approve 在签发 token 前必须指定精确的 requestId；省略 requestId 或 --latest 仅预览最新待审批请求。

Token 漂移恢复清单

当 Control UI 或其他客户端持续出现以下错误之一时，按步骤修复：

• AUTH_TOKEN_MISMATCH
• AUTH_DEVICE_TOKEN_MISMATCH
• AUTH_SCOPE_MISMATCH

1. 确认当前 gateway token 来源：

openclaw config get gateway.auth.token

2. 列出已配对设备，找到受影响的设备 ID：

openclaw devices list

3. 为受影响的设备轮换 operator token：

openclaw devices rotate --device <deviceId> --role operator

4. 如果轮换不够，移除旧配对并重新批准：

openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>

5. 用当前共享 token/password 重试客户端连接。

补充说明：

• 正常重连时的 token 优先级依次为：显式共享 token/password > 显式 deviceToken > 存储的设备 token > bootstrap token。
• 受信任的 AUTH_TOKEN_MISMATCH 恢复可临时在受限的重试中同时发送共享 token 和存储的设备 token。
• AUTH_SCOPE_MISMATCH 表示设备 token 被识别，但不携带请求的权限范围；需要先修复配对/权限批准合约，而不是改共享 gateway auth。

相关文档：

• Dashboard 认证排障
• Gateway 排障

常见问题

openclaw devices approve 为什么总是预览而不真正批准？

openclaw devices approve 在不带 requestId 或使用 --latest 时只会显示最新的待审批请求详情并退出。想要真正批准，需要先用 openclaw devices list 拿到精确的 requestId，再运行 openclaw devices approve <requestId>。

AUTH_TOKEN_MISMATCH 怎么解决？

按照“Token 漂移恢复清单”步骤操作：先用 openclaw config get gateway.auth.token 确认 token 来源，再用 openclaw devices list 找到设备 ID，然后 openclaw devices rotate --device <deviceId> --role operator。如果不行，移除旧配对并用 openclaw devices approve <requestId> 重新配对。

openclaw devices rotate 报错“role not approved”怎么办？

旋转 token 的目标角色必须已在设备已批准的配对合约中存在。先运行 openclaw devices list 查看该设备已批准的 roles。如果角色不存在，需要先通过 openclaw devices approve 完成该角色的配对请求（请求中需包含该角色）。注意，轮换不能创建未批准的角色。