openclaw devices
デバイスのペアリングリクエストとデバイススコープのトークンを管理します。
共通オプション
--url <url>: Gateway WebSocket URL（設定されている場合はデフォルトでgateway.remote.url）--token <token>: Gateway トークン（必要な場合）--password <password>: Gateway パスワード（パスワード認証）--timeout <ms>: RPC タイムアウト--json: JSON 出力（スクリプトでは推奨）
コマンド
openclaw devices list
保留中のペアリングリクエストとペアリング済みデバイスを一覧表示します。
openclaw devices approve [requestId] [--latest]
正確な requestId で保留中のペアリングリクエストを承認します。requestId を省略するか、--latest を渡した場合は、最新の保留中リクエストをプレビューするだけで終了します（コード 1）。承認するには、正確なリクエスト ID を指定して再実行してください。
デバイスが変更された認証詳細（ロール、スコープ、または公開鍵）でペアリングを再試行すると、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リクエストは、この一覧に表示される前に自動承認されることがあります。デフォルトでは無効です。オペレーター/ブラウザクライアントやアップグレードリクエストには適用されません。
openclaw devices reject <requestId>
保留中のデバイスペアリングリクエストを拒否します。
openclaw devices remove <deviceId>
ペアリング済みデバイスのエントリを 1 件削除します。
operator.admin が必要です。
openclaw devices clear --yes [--pending]
ペアリング済みデバイスを一括でクリアします。--yes によって保護されています。
--pending は、保留中のすべてのペアリングリクエストも拒否します。
openclaw devices rotate --device <id> --role <role> [--scope <scope...>]
ロールのデバイストークンをローテーションし、必要に応じてスコープを更新します。
- 対象ロールは、そのデバイスの承認済みペアリング契約にすでに存在している必要があります。ローテーションで未承認の新しいロールを発行することはできません。
--scopeを省略すると、以降の再接続で保存済みトークンのキャッシュされた承認済みスコープが再利用されます。明示的な--scope値を渡すと、今後のキャッシュ済みトークン再接続で使用される保存済みスコープセットが置き換えられます。- 管理者ではないペアリング済みデバイスの呼び出し元は、自分自身のデバイストークンのみローテーションできます。また、対象スコープセットは呼び出し元自身のオペレータースコープ内に収まる必要があります。ローテーションで、呼び出し元がすでに持っている範囲より広いトークンを発行または保持することはできません。
openclaw devices revoke --device <id> --role <role>
ロールのデバイストークンを取り消します。
operator.admin が必要です。対象スコープセットも呼び出し元自身のオペレータースコープ内に収まる必要があります。ペアリング専用の呼び出し元は、管理者/書き込みオペレータートークンを取り消すことはできません。
メモ
- これらのコマンドには
operator.pairing（またはoperator.admin）スコープが必要です。非オペレーターデバイスロールには常にoperator.adminが必要です。オペレータースコープを参照してください。 - トークンのローテーションと取り消しは、デバイスの承認済みペアリングロールセットとスコープベースラインの範囲内にとどまります。無関係なキャッシュ済みトークンエントリによって、トークン管理の対象が付与されることはありません。
- ペアリング済みデバイストークンセッションでは、クロスデバイス管理（
remove、rotate、revoke）は、呼び出し元がoperator.adminを持たない限り自分自身のみです。 - トークンのローテーションは新しいトークン（機密情報）を返します。シークレットとして扱ってください。
- local loopback でペアリングスコープを利用できず、明示的な
--urlが渡されていない場合、list/approveはローカルのペアリング状態にフォールバックできます。
トークンドリフト復旧チェックリスト
Control UI やその他のクライアントがAUTH_TOKEN_MISMATCH、AUTH_DEVICE_TOKEN_MISMATCH、または AUTH_SCOPE_MISMATCH で失敗し続ける場合に使用します。
-
現在の Gateway トークンソースを確認します。
-
ペアリング済みデバイスを一覧表示し、影響を受けているデバイス id を特定します。
-
影響を受けているデバイスのオペレータートークンをローテーションします。
-
ローテーションだけでは不十分な場合は、古いペアリングを削除して再度承認します。
- 現在の共有トークン/パスワードでクライアント接続を再試行します。
- 通常の再接続認証の優先順位: 明示的な共有トークン/パスワード、次に明示的な
deviceToken、次に保存済みデバイストークン、次にブートストラップトークン。 - 信頼済みの
AUTH_TOKEN_MISMATCH復旧では、1 回の限定的な再試行のために共有トークンと保存済みデバイストークンの両方を一時的に同時送信できます。 AUTH_SCOPE_MISMATCHは、デバイストークンは認識されたものの、要求されたスコープセットを持っていないことを意味します。共有 Gateway 認証を変更する前に、ペアリング/スコープ承認契約を修正してください。
Paperclip / openclaw_gateway 初回実行時の承認
openclaw_gateway アダプターを通じて接続する Paperclip エージェントは、他の新しいクライアントと同じ初回実行時のデバイスペアリング承認を行います。Paperclip が openclaw_gateway_pairing_required を報告した場合は、保留中のデバイスを承認して再試行してください。
openclaw devices approve <requestId> コマンドが出力されます。詳細を確認し、その後リクエスト ID を指定してそのコマンドを再実行し、承認してください。リモート Gateway または明示的な認証情報を使用する場合は、プレビュー時と承認時に同じオプションを渡します。
adapterConfig.devicePrivateKeyPem を設定します。
openclaw devices list を実行して保留中リクエストが存在することを確認してください。