CLI commands
デバイス
openclaw devices
デバイスのペアリング要求とデバイススコープのトークンを管理します。
コマンド
openclaw devices list
保留中のペアリング要求とペアリング済みデバイスを一覧表示します。
openclaw devices listopenclaw devices list --json保留中の要求の出力では、デバイスがすでにペアリング済みの場合、要求されたアクセス権がデバイスの現在承認済みのアクセス権の横に表示されます。これにより、スコープ/ロールのアップグレードが、ペアリングが失われたように見えるのではなく、明示的に示されます。
openclaw devices remove <deviceId>
ペアリング済みデバイスのエントリを1つ削除します。
ペアリング済みデバイストークンで認証されている場合、管理者でない呼び出し元は自分自身のデバイスエントリのみ削除できます。別のデバイスを削除するには operator.admin が必要です。
openclaw devices remove <deviceId>openclaw devices remove <deviceId> --jsonopenclaw devices clear --yes [--pending]
ペアリング済みデバイスを一括でクリアします。
openclaw devices clear --yesopenclaw devices clear --yes --pendingopenclaw devices clear --yes --pending --jsonopenclaw devices approve [requestId] [--latest]
正確な requestId で保留中のデバイスペアリング要求を承認します。requestId が省略された場合、または --latest が渡された場合、OpenClaw は選択された保留中の要求だけを表示して終了します。詳細を確認した後、正確な要求 ID で承認を再実行してください。
デバイスがすでにペアリング済みで、より広いスコープまたはより広いロールを要求した場合、OpenClaw は既存の承認を維持し、新しい保留中のアップグレード要求を作成します。openclaw devices list の Requested 列と Approved 列を確認するか、openclaw devices approve --latest を使用して、承認前に正確なアップグレード内容をプレビューしてください。
Gateway が gateway.nodes.pairing.autoApproveCidrs で明示的に構成されている場合、一致するクライアント IP からの初回の role: node 要求は、この一覧に表示される前に承認されることがあります。このポリシーはデフォルトでは無効であり、オペレーター/ブラウザークライアントやアップグレード要求には適用されません。
openclaw devices approveopenclaw devices approve <requestId>openclaw devices approve --latestopenclaw devices reject <requestId>
保留中のデバイスペアリング要求を拒否します。
openclaw devices reject <requestId>openclaw devices rotate --device <id> --role <role> [--scope <scope...>]
特定のロールのデバイストークンをローテーションします（必要に応じてスコープも更新します）。
対象ロールは、そのデバイスの承認済みペアリング契約内にすでに存在している必要があります。ローテーションで未承認の新しいロールを発行することはできません。
--scope を省略した場合、保存されたローテーション済みトークンで後から再接続すると、そのトークンのキャッシュ済み承認スコープが再利用されます。明示的な --scope 値を渡した場合、それらが今後のキャッシュ済みトークン再接続で保存されるスコープセットになります。
管理者でないペアリング済みデバイスの呼び出し元は、自分自身のデバイストークンのみローテーションできます。
対象トークンのスコープセットは、呼び出し元セッション自身のオペレータースコープ内に収まっている必要があります。ローテーションによって、呼び出し元がすでに持っているものより広いオペレータートークンを発行または保持することはできません。
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.writeローテーションのメタデータを JSON として返します。呼び出し元がそのデバイストークンで認証された状態で自分自身のトークンをローテーションしている場合、レスポンスには置き換え用トークンも含まれるため、クライアントは再接続前にそれを永続化できます。共有/管理者によるローテーションではベアラートークンは返されません。
openclaw devices revoke --device <id> --role <role>
特定のロールのデバイストークンを取り消します。
管理者でないペアリング済みデバイスの呼び出し元は、自分自身のデバイストークンのみ取り消せます。
別のデバイスのトークンを取り消すには operator.admin が必要です。
対象トークンのスコープセットも、呼び出し元セッション自身のオペレータースコープ内に収まっている必要があります。ペアリングのみの呼び出し元は、管理者/書き込みオペレータートークンを取り消せません。
openclaw devices revoke --device <deviceId> --role node取り消し結果を JSON として返します。
共通オプション
--url <url>: Gateway WebSocket URL（構成されている場合はデフォルトでgateway.remote.url）。--token <token>: Gateway トークン（必要な場合）。--password <password>: Gateway パスワード（パスワード認証）。--timeout <ms>: RPC タイムアウト。--json: JSON 出力（スクリプト用途に推奨）。
注記
- トークンローテーションは新しいトークン（機密）を返します。シークレットとして扱ってください。
- これらのコマンドには
operator.pairing（またはoperator.admin）スコープが必要です。一部の承認では、対象デバイスが発行または継承するオペレータースコープを呼び出し元が保持していることも必要です。オペレータースコープを参照してください。 gateway.nodes.pairing.autoApproveCidrsは、新規 Node デバイスペアリング専用のオプトイン Gateway ポリシーです。CLI の承認権限は変更しません。- トークンのローテーションと取り消しは、そのデバイスの承認済みペアリングロールセットおよび承認済みスコープベースラインの内側に留まります。迷い込んだキャッシュ済みトークンエントリによって、トークン管理対象が付与されることはありません。
- ペアリング済みデバイストークンのセッションでは、デバイスをまたいだ管理は管理者専用です。呼び出し元が
operator.adminを持っていない限り、remove、rotate、revokeは自分自身のみが対象です。 - トークン変更も呼び出し元スコープ内に制限されます。ペアリングのみのセッションでは、現在
operator.adminまたはoperator.writeを持つトークンをローテーションまたは取り消しできません。 devices clearは意図的に--yesで保護されています。- local loopback でペアリングスコープが利用できない場合（かつ明示的な
--urlが渡されていない場合）、list/approve はローカルのペアリングフォールバックを使用できます。 devices approveは、トークンを発行する前に明示的な要求 ID を必要とします。requestIdを省略するか--latestを渡した場合は、最新の保留中要求をプレビューするだけです。
トークンドリフト復旧チェックリスト
Control UI やその他のクライアントが AUTH_TOKEN_MISMATCH、AUTH_DEVICE_TOKEN_MISMATCH、または AUTH_SCOPE_MISMATCH で失敗し続ける場合に使用します。
- 現在の Gateway トークンソースを確認します。
openclaw config get gateway.auth.token- ペアリング済みデバイスを一覧表示し、影響を受けているデバイス ID を特定します。
openclaw devices list- 影響を受けているデバイスのオペレータートークンをローテーションします。
openclaw devices rotate --device <deviceId> --role operator- ローテーションで十分でない場合は、古いペアリングを削除して再度承認します。
openclaw devices remove <deviceId>openclaw devices listopenclaw devices approve <requestId>- 現在の共有トークン/パスワードでクライアント接続を再試行します。
注記:
- 通常の再接続時の認証優先順位は、明示的な共有トークン/パスワード、明示的な
deviceToken、保存済みデバイストークン、ブートストラップトークンの順です。 - 信頼済みの
AUTH_TOKEN_MISMATCH復旧では、1回の限定された再試行のために、共有トークンと保存済みデバイストークンの両方を一時的にまとめて送信できます。 AUTH_SCOPE_MISMATCHは、デバイストークンは認識されたものの、要求されたスコープセットを持っていないことを意味します。共有 Gateway 認証を変更する前に、ペアリング/スコープ承認契約を修正してください。
関連: