OpenClawでデバイス管理を効率化する：ペアリングとトークンの操作ガイド

新しいデバイスをセットアップする際、ペアリングの手順やトークンの管理で迷ったことはありませんか？「承認待ちの要求はどこで確認するのか」「古いデバイスのアクセス権をどう整理するか」といった操作は、開発の現場で頻繁に発生します。

今回は、デバイスのペアリング要求やデバイススコープのトークンを効率的に管理するための openclaw devices コマンドについて解説します。

`openclaw devices`

デバイスのペアリング要求とデバイススコープのトークンを管理します。

コマンド

`openclaw devices list`

保留中のペアリング要求と、ペアリング済みのデバイスを一覧表示します。

openclaw devices list
openclaw devices list --json

保留中の要求の出力には、要求されたロールとスコープが含まれます。承認を行う前に、内容をしっかりと確認できるようになっています。

`openclaw devices remove <deviceId>`

ペアリング済みデバイスのエントリを1つ削除します。

ペアリング済みデバイスのトークンを使用して認証している場合、管理者以外の呼び出し元は自分自身のデバイスエントリのみを削除できます。他のデバイスを削除するには operator.admin 権限が必要です。

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

`openclaw devices clear --yes [--pending]`

ペアリング済みデバイスを一括で消去します。

openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json

`openclaw devices approve [requestId] [--latest]`

保留中のデバイスペアリング要求を、正確な requestId を指定して承認します。requestId を省略するか --latest を渡すと、OpenClaw は選択された保留中の要求を表示して終了します。詳細を確認した後、正確な要求 ID を指定して承認を再実行してください。

注意：デバイスが認証詳細（ロール、スコープ、公開鍵）を変更してペアリングを再試行した場合、OpenClaw は以前の保留エントリを上書きし、新しい requestId を発行します。承認の直前に openclaw devices list を実行して、最新の ID を使用するようにしてください。

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

`openclaw devices reject <requestId>`

保留中のデバイスペアリング要求を拒否します。

openclaw devices reject <requestId>

`openclaw devices rotate --device <id> --role <role> [--scope <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 出力（スクリプトでの利用を推奨）。

注意：--url を設定した場合、CLI は設定ファイルや環境変数の認証情報を使用しません。--token または --password を明示的に渡してください。明示的な認証情報がない場合はエラーになります。

注意事項

トークンのローテーションを実行すると、新しいトークンが返されます（機密情報です）。秘密鍵と同様に扱ってください。
これらのコマンドには operator.pairing（または operator.admin）スコープが必要です。
トークンのローテーションは、そのデバイスに対して承認されたペアリングロールのセット、および承認されたスコープの基準内にとどまります。迷い込んだキャッシュトークンのエントリによって、新しいローテーション対象が許可されることはありません。
ペアリング済みデバイスのトークンセッションにおいて、デバイスをまたがる管理操作は管理者専用です。remove、rotate、revoke は、呼び出し元が operator.admin を持っていない限り、自分自身に対してのみ実行可能です。
devices clear は、意図的に --yes フラグによって保護されています。
ローカルループバックでペアリングスコープが利用できず、かつ --url が明示的に渡されていない場合、list や approve はローカルペアリングのフォールバックを使用できます。
devices approve は、トークンを発行する前に明示的な要求 ID を必要とします。requestId を省略したり --latest を渡したりした場合は、最新の保留中の要求をプレビューするだけです。

トークンの不整合（ドリフト）を解消するためのチェックリスト

Control UI や他のクライアントで AUTH_TOKEN_MISMATCH または AUTH_DEVICE_TOKEN_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 list
openclaw devices approve <requestId>

現在の共有トークンまたはパスワードを使用して、クライアント接続を再試行します。

補足：

通常の再接続時の認証優先順位は、まず明示的な共有トークン/パスワード、次に明示的な deviceToken、その次に保存済みのデバイス・トークン、最後にブートストラップ・トークンの順となります。
信頼された AUTH_TOKEN_MISMATCH リカバリでは、1回限りのリトライとして、共有トークンと保存済みのデバイス・トークンの両方を一時的に送信することができます。

SEO キーワード

次のステップ

AI Setup Assistant

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。