Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw devices
デバイスのペアリング要求とデバイススコープのトークンを管理します。
コマンド
openclaw devices list
保留中のペアリング要求とペアリング済みデバイスを一覧表示します。
openclaw devices remove <deviceId>
ペアリング済みデバイスのエントリを1つ削除します。
ペアリング済みデバイストークンで認証されている場合、管理者でない呼び出し元は自分自身のデバイスエントリのみ削除できます。別のデバイスを削除するには operator.admin が必要です。
openclaw devices clear --yes [--pending]
ペアリング済みデバイスを一括でクリアします。
openclaw devices approve [requestId] [--latest]
正確な requestId で保留中のデバイスペアリング要求を承認します。requestId が省略された場合、または --latest が渡された場合、OpenClaw は選択された保留中の要求だけを表示して終了します。詳細を確認した後、正確な要求 ID で承認を再実行してください。
デバイスが認証の詳細（ロール、スコープ、または公開鍵）を変更してペアリングを再試行した場合、OpenClaw は以前の保留中エントリを置き換え、新しい
requestId を発行します。承認直前に openclaw devices list を実行して、現在の ID を使用してください。openclaw devices list の Requested 列と Approved 列を確認するか、openclaw devices approve --latest を使用して、承認前に正確なアップグレード内容をプレビューしてください。
Gateway が gateway.nodes.pairing.autoApproveCidrs で明示的に構成されている場合、一致するクライアント IP からの初回の role: node 要求は、この一覧に表示される前に承認されることがあります。このポリシーはデフォルトでは無効であり、オペレーター/ブラウザークライアントやアップグレード要求には適用されません。
openclaw devices reject <requestId>
保留中のデバイスペアリング要求を拒否します。
openclaw devices rotate --device <id> --role <role> [--scope <scope...>]
特定のロールのデバイストークンをローテーションします（必要に応じてスコープも更新します）。
対象ロールは、そのデバイスの承認済みペアリング契約内にすでに存在している必要があります。ローテーションで未承認の新しいロールを発行することはできません。
--scope を省略した場合、保存されたローテーション済みトークンで後から再接続すると、そのトークンのキャッシュ済み承認スコープが再利用されます。明示的な --scope 値を渡した場合、それらが今後のキャッシュ済みトークン再接続で保存されるスコープセットになります。
管理者でないペアリング済みデバイスの呼び出し元は、自分自身のデバイストークンのみローテーションできます。
対象トークンのスコープセットは、呼び出し元セッション自身のオペレータースコープ内に収まっている必要があります。ローテーションによって、呼び出し元がすでに持っているものより広いオペレータートークンを発行または保持することはできません。
openclaw devices revoke --device <id> --role <role>
特定のロールのデバイストークンを取り消します。
管理者でないペアリング済みデバイスの呼び出し元は、自分自身のデバイストークンのみ取り消せます。
別のデバイスのトークンを取り消すには operator.admin が必要です。
対象トークンのスコープセットも、呼び出し元セッション自身のオペレータースコープ内に収まっている必要があります。ペアリングのみの呼び出し元は、管理者/書き込みオペレータートークンを取り消せません。
共通オプション
--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 トークンソースを確認します。
- ペアリング済みデバイスを一覧表示し、影響を受けているデバイス ID を特定します。
- 影響を受けているデバイスのオペレータートークンをローテーションします。
- ローテーションで十分でない場合は、古いペアリングを削除して再度承認します。
- 現在の共有トークン/パスワードでクライアント接続を再試行します。
- 通常の再接続時の認証優先順位は、明示的な共有トークン/パスワード、明示的な
deviceToken、保存済みデバイストークン、ブートストラップトークンの順です。 - 信頼済みの
AUTH_TOKEN_MISMATCH復旧では、1回の限定された再試行のために、共有トークンと保存済みデバイストークンの両方を一時的にまとめて送信できます。 AUTH_SCOPE_MISMATCHは、デバイストークンは認識されたものの、要求されたスコープセットを持っていないことを意味します。共有 Gateway 認証を変更する前に、ペアリング/スコープ承認契約を修正してください。