如何使用 openclaw devices 管理裝置與 Token
每次處理裝置配對或 Token 過期都讓人頭大，尤其是當你有多個裝置需要管理時，手動操作不僅麻煩還容易出錯。OpenClaw 提供的 devices 指令就是為了幫你搞定這些瑣事，讓裝置管理變得直覺又安全。
如果你曾經遇過 Token 失效或是想快速清理舊的裝置連線，這篇指南會告訴你如何利用 CLI 工具精準掌控每一個裝置的存取權限。
openclaw devices
Section titled “openclaw devices”管理裝置配對請求與裝置範圍的 Token。
指令 (Commands)
Section titled “指令 (Commands)”openclaw devices list
Section titled “openclaw devices list”列出待處理的配對請求以及已配對的裝置。
openclaw devices listopenclaw devices list --json待處理請求的輸出內容會包含請求的角色（role）與範圍（scopes），讓你在核准之前可以先仔細檢查。
openclaw devices remove <deviceId>
Section titled “openclaw devices remove <deviceId>”移除單一已配對的裝置項目。
當你使用已配對裝置的 Token 進行驗證時，非管理員（non-admin）呼叫者只能移除自己的裝置項目。若要移除其他裝置，則需要 operator.admin 權限。
openclaw devices remove <deviceId>openclaw devices remove <deviceId> --jsonopenclaw devices clear --yes [--pending]
Section titled “openclaw devices clear --yes [--pending]”批量清理已配對的裝置。
openclaw devices clear --yesopenclaw devices clear --yes --pendingopenclaw devices clear --yes --pending --jsonopenclaw devices approve [requestId] [--latest]
Section titled “openclaw devices approve [requestId] [--latest]”透過精確的 requestId 核准待處理的裝置配對請求。如果省略 requestId 或傳入了 --latest，OpenClaw 只會印出選定的待處理請求並退出；請在確認細節後，使用精確的請求 ID 重新執行核准。
注意：如果裝置使用變更後的驗證資訊（角色/範圍/公鑰）重試配對，OpenClaw 會取代先前的待處理項目並核發新的 requestId。請在核准前執行 openclaw devices list 以取得目前的 ID。
openclaw devices approveopenclaw devices approve <requestId>openclaw devices approve --latestopenclaw devices reject <requestId>
Section titled “openclaw devices reject <requestId>”拒絕待處理的裝置配對請求。
openclaw devices reject <requestId>openclaw devices rotate --device <id> --role <role> [--scope <scope...>]
Section titled “openclaw devices rotate --device <id> --role <role> [--scope <scope...>]”針對特定角色輪換裝置 Token（可選擇性更新範圍）。
目標角色必須已經存在於該裝置已核准的配對合約中；輪換功能無法產生新的未核准角色。
如果你省略 --scope，之後使用儲存的輪換 Token 重新連線時，會沿用該 Token 快取中已核准的範圍。如果你傳入了明確的 --scope 值，這些值將成為未來快取 Token 重新連線時儲存的範圍集。
非管理員的已配對裝置呼叫者只能輪換自己的裝置 Token。此外，任何明確的 --scope 值都必須在呼叫者工作階段（session）原有的 operator 範圍內；輪換功能無法產生比呼叫者現有權限更廣的 operator Token。
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write以 JSON 格式回傳新的 Token 內容。
openclaw devices revoke --device <id> --role <role>
Section titled “openclaw devices revoke --device <id> --role <role>”撤銷特定角色的裝置 Token。
非管理員的已配對裝置呼叫者只能撤銷自己的裝置 Token。撤銷其他裝置的 Token 需要 operator.admin 權限。
openclaw devices revoke --device <deviceId> --role node以 JSON 格式回傳撤銷結果。
通用選項 (Common options)
Section titled “通用選項 (Common options)”--url <url>: Gateway WebSocket URL（設定後預設為gateway.remote.url）。--token <token>: Gateway Token（如果需要）。--password <password>: Gateway 密碼（密碼驗證）。--timeout <ms>: RPC 超時時間。--json: JSON 輸出（建議用於腳本編寫）。
注意：當你設定了 --url 時，CLI 不會回退（fallback）到設定檔或環境變數中的憑證。請明確傳入 --token 或 --password。缺少明確憑證將會導致錯誤。
注意事項 (Notes)
Section titled “注意事項 (Notes)”- Token 輪換會回傳新的 Token（敏感資訊）。請將其視為秘密妥善保管。
- 這些指令需要
operator.pairing（或operator.admin）範圍。 - Token 輪換會維持在該裝置已核准的配對角色集與範圍基準內。殘留的快取 Token 項目不會授予新的輪換目標。
- 對於已配對裝置的 Token 工作階段，跨裝置管理僅限管理員：除非呼叫者擁有
operator.admin，否則remove、rotate和revoke僅限對自身操作。 devices clear刻意設計了--yes門檻。- 如果本地 loopback 無法使用配對範圍（且未傳入明確的
--url），list/approve 可以使用本地配對回退方案。 devices approve在產生 Token 之前需要明確的請求 ID；省略requestId或傳入--latest僅會預覽最新的待處理請求。
Token 偏移恢復清單 (Token drift recovery checklist)
Section titled “Token 偏移恢復清單 (Token drift recovery checklist)”當 Control UI 或其他用戶端持續出現 AUTH_TOKEN_MISMATCH 或 AUTH_DEVICE_TOKEN_MISMATCH 錯誤時，請使用此清單。
- 確認目前的 Gateway Token 來源：
openclaw config get gateway.auth.token- 列出已配對裝置並識別受影響的裝置 ID：
openclaw devices list- 為受影響的裝置輪換 operator Token：
openclaw devices rotate --device <deviceId> --role operator- 如果輪換還不夠，請移除舊的配對並重新核准：
openclaw devices remove <deviceId>openclaw devices listopenclaw devices approve <requestId>- 使用目前的共享 Token/密碼重試用戶端連線。
備註：
- 一般重新連線的驗證優先順序為：明確的共享 Token/密碼優先，接著是明確的
deviceToken，然後是儲存的裝置 Token，最後是 bootstrap Token。 - 受信任的
AUTH_TOKEN_MISMATCH恢復機制可以在單次受限的重試中，暫時同時發送共享 Token 與儲存的裝置 Token。
下一步：
OpenClaw Expert
還是卡住了？
如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。