openclaw devices

管理设备配对请求和设备级 token。

命令详解

openclaw devices list

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

openclaw devices list
openclaw devices list --json

待处理请求的输出包含所请求的角色和权限范围，方便在批准前审查。

openclaw devices remove <deviceId>

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

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

openclaw devices clear --yes [--pending]

批量清除已配对设备。

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

openclaw devices approve [requestId] [--latest]

批准待处理的设备配对请求。省略 requestId 时，OpenClaw 自动批准最新的待处理请求。

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

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

openclaw devices reject <requestId>

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

openclaw devices reject <requestId>

openclaw devices rotate --device <id> --role <role> [--scope <scope...>]

为指定设备的特定角色轮换 token（可选更新权限范围）。

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

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

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

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

通用选项

• --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）权限范围。
• devices clear 需要显式传入 --yes 确认。
• 如果本地回环上没有 pairing 权限范围（且未传入显式 --url），list/approve 可使用本地 pairing 回退。

Token 漂移恢复清单

当 Control UI 或其他客户端持续出现 AUTH_TOKEN_MISMATCH 或 AUTH_DEVICE_TOKEN_MISMATCH 时，按以下步骤修复——这种问题经常出现在重新部署龙虾后客户端 token 没有同步更新的场景：

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/密码重试客户端连接。

相关文档：

• Dashboard 认证排障
• Gateway 排障