OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

裝置

openclaw devices

管理裝置配對請求與裝置範圍權杖。

常用選項

  • --url <url>：閘道 WebSocket URL（設定後預設為 gateway.remote.url）
  • --token <token>：閘道權杖（若需要）
  • --password <password>：閘道密碼（密碼驗證）
  • --timeout <ms>：RPC 逾時
  • --json：JSON 輸出（建議用於指令碼）

命令

openclaw devices list

列出待處理的配對請求與已配對裝置。

bash
openclaw devices listopenclaw devices list --json

若已配對的裝置有待處理請求，輸出會在裝置目前已核准的存取權旁顯示所請求的存取權，讓範圍／角色升級清楚可見，而不會看起來像配對遺失。

已配對裝置顯示名稱的優先順序如下：操作者標籤（來自 devices rename 的 operatorLabel）、用戶端 displayName、clientId，最後是 deviceId。

openclaw devices approve [requestId] [--latest]

依確切的 requestId 核准待處理的配對請求。省略 requestId 或傳入 --latest，只會預覽最新的待處理請求並結束（結束代碼 1）；請使用確切的請求 ID 重新執行以核准。

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

核准行為：

  • 若裝置已配對並請求更廣的範圍或角色，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>

拒絕待處理的裝置配對請求。

bash
openclaw devices reject <requestId>

openclaw devices remove <deviceId>

移除一筆已配對裝置項目。

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

以已配對裝置權杖驗證的呼叫者只能移除其自己的裝置項目。移除其他裝置需要 operator.admin。

openclaw devices rename --device <id> --name <label>

為已配對裝置指派操作者標籤。標籤是擁有者端狀態：配對修復及角色重新核准後仍會保留，且不會變更穩定的 deviceId。

bash
openclaw devices rename --device <deviceId> --name "Kitchen Mac"openclaw devices rename --device <deviceId> --name "Kitchen Mac" --json
  • --name 為必填，會移除前後空白、不得為空，且上限為 64 個字元。
  • 顯示介面（命令列介面清單、Control UI 裝置清冊）會優先採用操作者標籤，而非用戶端回報的顯示名稱。
  • 非管理員的已配對裝置呼叫者只能重新命名其自己的裝置。重新命名其他裝置需要 operator.admin。

openclaw devices clear --yes [--pending]

批次清除已配對裝置。受 --yes 限制。

bash
openclaw devices clear --yesopenclaw devices clear --yes --pendingopenclaw devices clear --yes --pending --json

--pending 也會拒絕所有待處理的配對請求。

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

輪替某個角色的裝置權杖，並可選擇更新其範圍。

bash
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
  • 目標角色必須已存在於該裝置已核准的配對合約中；輪替無法簽發未經核准的新角色。
  • 省略 --scope 時，後續重新連線會沿用已儲存權杖中快取的已核准範圍。傳入明確的 --scope 值，會取代已儲存的範圍集，供日後使用快取權杖重新連線。
  • 非管理員的已配對裝置呼叫者只能輪替其自己的裝置權杖，且目標範圍集不得超出呼叫者本身的操作者範圍；輪替無法簽發或保留比呼叫者既有權限更廣的權杖。

以 JSON 傳回輪替中繼資料。若呼叫者使用該裝置權杖進行驗證並輪替自己的權杖，回應會包含替代權杖，讓用戶端能在重新連線前保存。共用／管理員輪替絕不會回傳持有人權杖。

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

撤銷某個角色的裝置權杖。

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

非管理員的已配對裝置呼叫者只能撤銷其自己的裝置權杖。撤銷其他裝置的權杖需要 operator.admin。目標範圍集也必須在呼叫者本身的操作者範圍內；僅有配對權限的呼叫者無法撤銷管理員／寫入操作者權杖。

注意事項

  • 這些命令需要 operator.pairing（或 operator.admin）範圍。非操作者裝置角色一律需要 operator.admin；請參閱操作者範圍。
  • 權杖輪替與撤銷僅限於裝置已核准的配對角色集與範圍基準。零散的快取權杖項目不會授予權杖管理目標的權限。
  • 對於已配對裝置權杖工作階段，跨裝置管理（remove、rename、rotate、revoke）僅限自身，除非呼叫者具有 operator.admin。
  • 權杖輪替會傳回新的權杖（敏感資訊）——請將其視為機密資訊。
  • 若本機回送介面無法使用配對範圍，且未明確傳入 --url，list/approve 可改用本機配對狀態。

權杖偏移復原檢查清單

當 Control UI 或其他用戶端持續因 AUTH_TOKEN_MISMATCH、AUTH_DEVICE_TOKEN_MISMATCH 或 AUTH_SCOPE_MISMATCH 而失敗時，請使用此清單。

  1. 確認目前的閘道權杖來源：

    bash
    openclaw config get gateway.auth.token

  2. 列出已配對裝置並找出受影響的裝置 ID：

    bash
    openclaw devices list

  3. 輪替受影響裝置的操作者權杖：

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

  4. 若輪替仍不足以解決問題，請移除過時的配對並重新核准：

    bash
    openclaw devices remove <deviceId>openclaw devices listopenclaw devices approve <requestId>

  5. 使用目前的共用權杖／密碼重試用戶端連線。

注意事項：

  • 一般重新連線的驗證優先順序：明確指定的共用權杖／密碼優先，其次是明確指定的 deviceToken、已儲存的裝置權杖，最後是啟動權杖。
  • 受信任的 AUTH_TOKEN_MISMATCH 復原可在一次有限制的重試中，暫時同時傳送共用權杖與已儲存的裝置權杖。
  • AUTH_SCOPE_MISMATCH 表示裝置權杖已被辨識，但不具備所請求的範圍集；請先修正配對／範圍核准合約，再變更共用閘道驗證。

相關內容：

Paperclip／openclaw_gateway 首次執行核准

透過 openclaw_gateway 介面卡連線的 Paperclip 代理程式，會像其他任何新用戶端一樣，經過首次執行裝置配對核准。若 Paperclip 回報 openclaw_gateway_pairing_required，請核准待處理的裝置後重試。

bash
openclaw devices approve --latest

預覽會輸出確切的 openclaw devices approve <requestId> 命令；請確認詳細資料，然後使用請求 ID 重新執行該命令以核准。若使用遠端閘道或明確認證資訊，請在預覽與核准時傳入相同選項：

bash
openclaw devices approve --latest --url <gateway-ws-url> --token <gateway-token>

為避免每次重新啟動後都必須再次核准，請在 Paperclip 中設定持久的 adapterConfig.devicePrivateKeyPem，而不要讓它每次執行時產生新的暫時裝置身分：

json
{  "adapterConfig": {    "devicePrivateKeyPem": "<ed25519-private-key-pkcs8-pem>"  }}

若核准持續失敗，請先執行 openclaw devices list，確認待處理的請求確實存在。

相關內容

Was this useful?
On this page

On this page