openclaw devices¶
管理设备配对请求和设备范围令牌。
常用选项¶
--url <url>：网关 WebSocket URL（配置时默认为gateway.remote.url）--token <token>：网关令牌（如需要）--password <password>：网关密码（密码身份验证）--timeout <ms>：RPC 超时--json：JSON 输出（脚本推荐）
Warning
当你设置 --url 时，CLI 不会回退到配置或环境凭据。请显式传入 --token 或 --password，否则命令会报错。
命令¶
openclaw devices list¶
列出待处理配对请求和已配对设备。
对于已配对设备上的待处理请求，输出会将请求的访问权限显示在该设备当前已批准访问权限旁边，因此范围/角色升级可见，而不会看起来像配对丢失。
已配对设备的显示名称使用以下优先级：操作员标签（来自 devices rename 的 operatorLabel），然后是客户端 displayName，然后是 clientId，然后是 deviceId。当设置了操作员标签时，devices 命令打印的节点审批通知会使用操作员标签。
openclaw devices approve [requestId] [--latest]¶
通过精确的 requestId 批准待处理配对请求。省略 requestId 或传入 --latest 只会预览最新的待处理请求并退出（代码 1）；请使用精确的请求 ID 重新运行以批准。
打印的批准命令会保留你当前激活的 profile 或容器、显式网关 URL、非默认超时以及 JSON 输出模式。令牌和密码选项值会被省略；当预览提示你重用这些选项时，请再次提供相同的凭据。
Note
如果设备使用更改后的身份验证详情（角色、范围或公钥）重试配对，OpenClaw 会用新的 requestId 取代之前的待处理条目。在批准前立即运行 openclaw devices list 以获取当前 ID。
批准行为：
- 如果设备已配对并请求更宽泛的范围或角色，OpenClaw 会保留现有批准并创建新的待处理升级请求。在批准前，请在
openclaw devices list中比较Requested与Approved，或使用--latest预览。 - 批准
node角色或其他非操作员角色需要operator.admin。对于操作员设备批准，operator.pairing足够，但仅当请求的操作员范围保持在调用者自身范围内时。参见 操作员范围。 - 如果配置了
gateway.nodes.pairing.autoApproveCidrs，来自匹配客户端 IP 的首次role: node请求可以在出现在此列表之前被自动批准。默认禁用；从不适用于操作员/浏览器客户端或升级请求。 gateway.nodes.pairing.sshVerify（默认开启）会在网关通过 SSH 到节点主机验证设备密钥时，自动批准首次role: node请求。因此，请求可能在出现后不久即变为已批准。设置sshVerify: false可禁用 SSH 验证；这与autoApproveCidrs相互独立，因此如果仅手动配对，也请取消设置该项。
openclaw devices reject <requestId>¶
拒绝待处理设备配对请求。
openclaw devices join-code¶
生成一个具有网关管理员访问权限的一次性节点入网 URL。在目标机器上粘贴打印出的 npx openclaw connect <url> 命令以注册。此加入 URL 不是移动应用设置代码；对于 Android/iOS，请改用 openclaw qr。
加入代码的创建和兑换是核心网关操作；无需启用配对插件。该 URL 必须可从加入机器访问。远程加入 URL 需要 TLS 网关端点。显式配置的环回端点可以使用 HTTP，前提是加入机器能够访问该环回端点，例如通过本地隧道。
如果只有默认环回绑定且没有通告端点，URL 发现会拒绝生成链接。对于位于公共 HTTPS 入口后面的环回网关，请将 gateway.publicOrigin 设置为代理的裸 HTTPS 源，并将代理的源地址包含在 gateway.trustedProxies 中。
加入代码、/pair 和 QR 设置会保留现有端点选择：plugins.entries.device-pair.config.publicUrl、显式优先的 gateway.remote.url、Tailscale Serve/Funnel、非优先远程 URL，然后是绑定派生地址。gateway.publicOrigin 仅作为环回专用错误之前的最终回退；它不会替换现有路由。目标为本地网关的调用者省略远程 URL。HTTP(S) URL 会变为匹配的 ws:/wss: 配对端点。
加入代码会保留完全限定 publicUrl 的上下文路径：对于 https://pair.example/extra，加入 URL 以 https://pair.example/extra/j/ 开头。device-pair 插件的 /pair 命令则保留其历史性的仅源 WebSocket 端点，wss://pair.example。
云节点注册 使用相同的解析器，并具有显式的公共入口优先设置：配对专用覆盖仍然优先，然后对于新配置的 worker，gateway.publicOrigin 优先于发现。
有关其他部署前提条件，请参见 无法托管节点的网关部署。明文局域网配对可以直接使用设置代码，而不是 HTTP 加入 URL。参见 连接一台机器。
openclaw devices remove <deviceId>¶
删除一个已配对设备条目。
使用已配对设备令牌进行身份验证的调用者只能删除其自己的设备条目。删除其他设备需要 operator.admin。
openclaw devices rename --device <id> --name <label>¶
为已配对的设备分配一个操作者标签。标签属于所有者侧状态：它们会在配对修复和角色重新批准后保留，并且不会改变稳定的 deviceId。
openclaw devices rename --device <deviceId> --name "Kitchen Mac"
openclaw devices rename --device <deviceId> --name "Kitchen Mac" --json
--name必填，会去除首尾空白，不能为空，且长度上限为 64 个字符。- 显示界面（CLI 列表、Control UI 清单）优先使用操作者标签，而不是客户端报告的显示名称。
- 非管理员的已配对设备调用方只能重命名其自己的设备。重命名其他设备需要
operator.admin。
openclaw devices clear --yes [--pending]¶
批量清除已配对设备。该操作受 --yes 门控。
openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json
--pending 还会拒绝所有待处理的配对请求。
openclaw devices rotate --device <id> --role <role> [--scope <scope...>]¶
为某个角色轮换设备 token，并可选择更新其作用域。
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
- 目标角色必须已存在于该设备的已批准配对契约中；轮换不能签发新的未批准角色。
- 省略
--scope会保留目标 token 的当前作用域。传入显式--scope值会在设备已批准基线范围内替换该作用域集合，用于后续基于缓存 token 的重连。 - 传入
--no-scopes以请求空作用域集合。它不能与--scope一起使用。 - 非管理员的已配对设备调用方只能轮换其自己的设备 token，并且目标作用域集合必须保持在调用方自身的操作者作用域内；轮换不能签发或保留比调用方已有 token 更宽泛的 token。
以 JSON 形式返回轮换元数据。如果调用方在已使用该设备 token 进行身份验证的情况下轮换自己的 token，响应会包含替换 token，以便客户端在重连前将其持久化。使用共享密钥的调用方以及轮换其他设备的调用方都不会收到 bearer token。
当 Doctor 报告某个携带操作者作用域的旧版节点 token 时，请使用其明确给出的恢复命令：
此恢复操作需要 operator.admin，并保留该设备的操作者配对和已批准作用域。Gateway 只会在与轮换相同的提交中，移除与已退役旧版 token 匹配的本地缓存节点 token。对于使用独立状态目录的节点主机，请提供有效的共享 Gateway 身份验证，并重启节点以刷新其缓存。仅凭已退役的设备 token 无法完成重连身份验证。
openclaw devices revoke --device <id> --role <role>¶
撤销某个角色的设备 token。
非管理员的已配对设备调用方只能撤销其自己的设备 token。撤销其他设备的 token 需要 operator.admin。目标作用域集合还必须落在调用方自身的操作者作用域内；仅具备配对权限的调用方不能撤销管理员/写入操作者 token。
说明¶
- 这些命令需要
operator.pairing（或operator.admin）作用域。非操作者设备角色始终需要operator.admin；参见 操作者作用域。 - token 轮换和撤销始终限制在该设备已批准的配对角色集合和作用域基线内。孤立的缓存 token 条目不会授予 token 管理目标。
- 轮换和撤销还会使匹配设备和角色的 Dashboard 读取权限以及已接纳回合保留的 Cron 调用方权限失效，断开连接后也一样。仅断开连接不会撤销这些权限。已提交的 Cron 变更会保留其结果，撤销创建者的 token 不会取消现有计划。
- 移除设备或撤销其节点 token 也会清除节点运行时状态。工作进程清理错误不会使受影响的连接保持已授权或打开状态。
- 对于操作者 token，CLI 会先读取配对列表，然后请求配对权限加上目标 token 的作用域（或显式轮换作用域）。如果目标不可见，它会请求管理员权限以进行跨设备管理。收窄后的 token 不会继承更宽泛的设备批准基线；调用方必须已经获得所请求作用域的授权。
- 对于已配对设备 token 会话，跨设备管理（
remove、rename、rotate、revoke）仅限自身，除非调用方具有operator.admin。 - token 轮换会返回一个新 token（敏感信息）——请将其视为秘密。
- 如果本地回环上无法使用配对作用域，且未显式传入
--url，list/approve可以回退到本地配对状态。
Token 漂移恢复检查清单¶
当 Control UI 或其他客户端持续因 AUTH_TOKEN_MISMATCH、AUTH_DEVICE_TOKEN_MISMATCH 或 AUTH_SCOPE_MISMATCH 失败时，使用此流程。
- 确认当前 gateway token 来源：
在 Gateway 主机上的交互式终端中运行该命令，并将其输出视为秘密。
- 列出已配对设备，并确定受影响的设备 id：
- 为受影响的设备轮换操作者 token：
- 如果轮换不够，请移除过期的配对并重新批准：
- 使用当前共享 token/密码重试客户端连接。
说明：
- 正常重连身份验证优先级：首先使用显式共享 token/密码，然后是显式
deviceToken，接着是已存储的设备 token，最后是 bootstrap token。 - 受信任的
AUTH_TOKEN_MISMATCH恢复可以暂时将共享 token 和已存储的设备 token 一起发送，用于一次有界重试。 AUTH_SCOPE_MISMATCH表示设备 token 已被识别，但不携带所请求的作用域集合；在更改共享 gateway 身份验证之前，请先修复配对/作用域批准契约。
相关：
Paperclip / openclaw_gateway 首次运行审批¶
通过 openclaw_gateway 适配器连接的 Paperclip 代理会经历与其他任何新客户端相同的首次运行设备配对审批。如果 Paperclip 报告 openclaw_gateway_pairing_required，请批准待处理的设备并重试。
预览会打印确切的 openclaw devices approve <requestId> 命令；请核对详细信息，然后使用请求 ID 重新运行该命令以批准它。对于远程网关或显式凭据，在预览和批准时传入相同选项：
为避免每次重启后都需要重新批准，请在 Paperclip 中配置持久的 adapterConfig.devicePrivateKeyPem，而不是让它在每次运行时生成新的临时设备身份：
如果批准持续失败，请先运行 openclaw devices list 以确认存在待处理请求。
相关¶
- CLI 参考
- 节点
openclaw qr— 生成移动节点引导二维码和设置代码
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw