openclaw devices¶
管理设备配对请求和设备范围的 Token。
常用选项¶
--url <url>:Gateway WebSocket URL(配置时默认为gateway.remote.url)--token <token>:Gateway Token(如需要)--password <password>:Gateway 密码(密码认证)--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 或容器、显式 Gateway URL、非默认超时以及 JSON 输出模式。Token 和密码选项值会被省略;当预览要求你重用这些选项时,请再次提供相同的凭据。
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(默认开启)会在 Gateway 通过 SSH 向节点主机验证设备密钥时,自动批准首次role: node请求。因此,请求可能在出现后不久即解析为已批准。设置sshVerify: false可禁用 SSH 验证;这与autoApproveCidrs相互独立,因此如果仅手动配对,也请取消设置该项。
openclaw devices reject <requestId>¶
拒绝待处理的设备配对请求。
已连接并等待的 Control UI 浏览器会显示 访问请求已拒绝,并自动停止重试。它可以使用 重新请求 提交新请求;重新加载页面也可以再次请求。拒绝不会持久化设备封禁。
openclaw devices join-code¶
生成一个具有 Gateway 管理员访问权限的一次性节点入网 URL。在机器上粘贴打印的 npx openclaw connect <url> 命令以注册。此加入 URL 不是移动应用设置代码;对于 Android/iOS,请改用 openclaw qr。
加入代码的创建和兑换是核心 Gateway 操作;无需启用配对插件。该 URL 必须可从加入机器访问。远程加入 URL 需要 TLS Gateway 端点。显式配置的回环端点可以使用 HTTP,前提是加入机器能够访问该回环端点,例如通过本地隧道。
如果只有默认回环绑定且没有通告端点,URL 发现会拒绝生成链接。对于位于公共 HTTPS 入口后面的回环 Gateway,请将 gateway.publicOrigin 设置为代理的裸 HTTPS 源,并将代理的源地址包含在 gateway.trustedProxies 中。
加入代码、/pair 和 QR 设置保留现有端点选择:plugins.entries.device-pair.config.publicUrl、显式首选的 gateway.remote.url、Tailscale Serve/Funnel、非首选远程 URL,然后是绑定派生地址。gateway.publicOrigin 仅用作回环专用错误之前的最终回退;它不会替换现有路由。目标为本地 Gateway 的调用方省略远程 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 先于发现。
有关其他部署前提条件,请参见 无法托管节点的 Gateway 部署。明文 LAN 配对可以直接使用设置代码,而不是 HTTP 加入 URL。参见 连接一台机器。
openclaw devices remove <deviceId>¶
移除一个已配对设备条目。
使用已配对设备令牌进行身份验证的调用方只能删除其自己的设备条目。删除其他设备需要 operator.admin。
openclaw devices rename --device <id> --name <label>¶
为已配对设备分配 operator 标签。标签属于所有者侧状态:它们会在配对修复和角色重新批准后保留,并且不会改变稳定的 deviceId。
openclaw devices rename --device <deviceId> --name "Kitchen Mac"
openclaw devices rename --device <deviceId> --name "Kitchen Mac" --json
--name为必填项,会去除首尾空格,不能为空,且最多 64 个字符。- 显示界面(CLI 列表、Control UI 清单)优先使用 operator 标签,而不是客户端报告的显示名称。
- 非管理员的已配对设备调用方只能重命名其自己的设备。重命名其他设备需要
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...>]¶
轮换某个角色的设备令牌,并可选择更新其作用域。
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
- 目标角色必须已存在于该设备的已批准配对合同中;轮换不能创建新的未批准角色。
- 省略
--scope会保留目标令牌的当前作用域。显式传入--scope值会在设备已批准基线内替换该作用域集合,用于后续缓存令牌重连。 - 传入
--no-scopes可请求空作用域集合。它不能与--scope同时使用。 - 非管理员的已配对设备调用方只能轮换其自己的设备令牌,并且目标作用域集合必须保持在调用方自身的 operator 作用域内;轮换不能创建或保留比调用方已有令牌更宽的令牌。
以 JSON 形式返回轮换元数据。如果调用方在使用该设备令牌进行身份验证时轮换自己的令牌,响应会包含替换令牌,以便客户端在重连前持久化它。共享密钥调用方以及轮换其他设备的调用方都不会收到 bearer token。
当 Doctor 报告某个旧版 node 令牌携带 operator 作用域时,使用其明确的恢复命令:
此恢复操作需要 operator.admin,并保留该设备的 operator 配对和已批准作用域。Gateway 只会在与轮换相同的提交中,移除与已退役旧版令牌匹配的本地缓存 node 令牌。对于使用独立状态目录的 node 主机,请提供有效的共享 Gateway 身份验证并重启 node,以刷新其缓存。仅凭已退役的设备令牌无法完成重连身份验证。
openclaw devices revoke --device <id> --role <role>¶
撤销某个角色的设备令牌。
非管理员的已配对设备调用方只能撤销其自己的设备令牌。撤销其他设备的令牌需要 operator.admin。目标作用域集合还必须位于调用方自身的 operator 作用域内;仅具有配对权限的调用方不能撤销 admin/write operator 令牌。
说明¶
- 这些命令需要
operator.pairing(或operator.admin)作用域。非 operator 设备角色始终需要operator.admin;参见 operator 作用域。 - 令牌轮换和撤销始终限制在设备已批准的配对角色集合和作用域基线内。孤立的缓存令牌条目不会授予令牌管理目标。
- 轮换和撤销还会使匹配设备和角色的 Dashboard 读取权限,以及已接纳回合保留的 Cron 调用方权限失效,包括断开连接后。仅断开连接不会撤销这些权限。已提交的 Cron 更改会保留其结果,撤销创建者令牌不会取消现有计划。
- 删除设备或撤销其 node 令牌也会清除 node 运行时状态。worker 清理错误不会使受影响的连接保持已授权或打开状态。
- 对于 operator 令牌,CLI 会先读取配对列表,然后请求配对权限加上目标令牌的作用域(或显式轮换作用域)。如果目标不可见,它会请求管理员权限以进行跨设备管理。收窄的令牌不会继承更宽的设备批准基线;调用方必须已被授权请求的作用域。
- 对于已配对设备令牌会话,跨设备管理(
remove、rename、rotate、revoke)仅限自身,除非调用方具有operator.admin。 - 令牌轮换会返回一个新令牌(敏感信息)——请将其视为机密。
- 如果本地回环上配对作用域不可用,且未显式传入
--url,list可以读取本地配对状态。批准操作绝不会绕过正在运行的 Gateway 进行写入:请使用已授权设备或共享 Gateway 凭据,或者通过其服务所有者停止 Gateway,然后重新运行确切的批准命令。当本地 Gateway 停止时,list读取现有状态,approve在写入和清理期间保持独占的离线所有权。显式 URL 和结果不确定的请求绝不会在本地重放。
Token 漂移恢复检查清单¶
当 Control UI 或其他客户端持续因 AUTH_TOKEN_MISMATCH、AUTH_DEVICE_TOKEN_MISMATCH 或 AUTH_SCOPE_MISMATCH 失败时,使用此流程。
- 确认当前 Gateway 令牌来源:
在 Gateway 主机上的交互式终端中运行该命令,并将其输出视为机密。
- 列出已配对设备并确定受影响的设备 id:
- 轮换受影响设备的 operator 令牌:
openclaw devices rotate --device <deviceId> --role operator
```
4. 如果轮换不够,请移除过期的配对并再次批准:
```bash
openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>
```
5. 使用当前共享 token/密码重试客户端连接。
注意:
- 正常重连身份验证优先级:首先使用显式共享 token/密码,然后是显式 `deviceToken`,接着是已存储的设备 token,最后是 bootstrap token。
- 受信任的 `AUTH_TOKEN_MISMATCH` 恢复机制可以临时将共享 token 和已存储的设备 token 一起发送,用于一次有限重试。
- `AUTH_SCOPE_MISMATCH` 表示设备 token 已被识别,但不包含所请求的 scope 集合;在更改共享网关身份验证之前,先修复配对/scope 审批契约。
相关:
- [仪表盘身份验证故障排查](../web/dashboard.md#if-you-see-unauthorized-1008)
- [网关故障排查](../gateway/troubleshooting.md#dashboard-control-ui-connectivity)
## Paperclip / `openclaw_gateway` 首次运行审批 {#paperclip-openclaw_gateway-first-run-approval}
通过 `openclaw_gateway` 适配器连接的 Paperclip 代理会经历与其他任何新客户端相同的首次运行设备配对审批。如果 Paperclip 报告 `openclaw_gateway_pairing_required`,请批准待处理设备并重试。
```bash
openclaw devices approve --latest
预览会打印确切的 openclaw devices approve <requestId> 命令;请核实详细信息,然后使用请求 ID 重新运行该命令以批准它。对于远程网关或显式凭据,在预览和批准时传入相同的选项:
为避免每次重启后重新批准,请在 Paperclip 中配置持久化的 adapterConfig.devicePrivateKeyPem,而不是让它在每次运行时生成新的临时设备身份:
如果批准持续失败,请先运行 openclaw devices list 以确认存在待处理请求。
相关¶
- CLI 参考
- 节点
openclaw qr— 生成移动节点 bootstrap QR 和设置代码
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw