メインコンテンツへスキップ
Gateway 所有のペアリングでは、どのノードが参加できるかについての信頼できる情報源は Gateway です。UI（macOS アプリ、将来のクライアント）は、保留中のリクエストを承認または拒否するためのフロントエンドにすぎません。 重要: WS ノードは connect 中に デバイスペアリング（ロール node）を使用します。node.pair.* は別個のレガシーペアリングストアであり、WS ハンドシェイクをゲートしません。このフローを使用するのは、node.pair.* を明示的に呼び出すクライアントだけです。

​
概念

  • 保留中のリクエスト: ノードが参加を要求した状態。承認が必要です。
  • ペアリング済みノード: 発行済みの認証トークンを持つ、承認済みノード。
  • トランスポート: Gateway WS エンドポイントはリクエストを転送しますが、メンバーシップは決定しません。レガシー TCP ブリッジのサポートは削除されました。

​
ペアリングの仕組み

  1. ノードが Gateway WS に接続し、ペアリングを要求します。
  2. Gateway は 保留中のリクエスト を保存し、node.pair.requested を発行します。
  3. リクエストを承認または拒否します（CLI または UI）。
  4. 承認時に、Gateway は 新しいトークン を発行します（再ペアリング時にトークンはローテーションされます）。
  5. ノードはそのトークンを使って再接続し、ペアリング済みになります。
保留中のリクエストは、ノードの最後の再試行から 5 分後 に自動的に期限切れになります。アクティブに再接続しているノードは、試行ごとに新しいリクエスト（および承認プロンプト）を生成するのではなく、1 つの保留中リクエストを維持します。

​
CLI ワークフロー（ヘッドレス向け）

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes remove --node <id|name|ip>
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
nodes status は、ペアリング済みまたは接続済みのノードとその機能を表示します。

​
API サーフェス（Gateway プロトコル）

イベント:
  • node.pair.requested - 新しい保留中リクエストが作成されたときに発行されます。
  • node.pair.resolved - リクエストが承認、拒否、または期限切れになったときに発行されます。
メソッド:
  • node.pair.request - 保留中リクエストを作成または再利用します。
  • node.pair.list - 保留中およびペアリング済みのノードを一覧表示します（operator.pairing）。
  • node.pair.approve - 保留中リクエストを承認します（トークンを発行します）。
  • node.pair.reject - 保留中リクエストを拒否します。
  • node.pair.remove - ペアリング済みノードを削除します。デバイスに基づくペアリングの場合、これはデバイスの node ロールを取り消します。つまり、devices/paired.json を変更し、そのデバイスの node ロールのセッションを無効化または切断します。複数ロール のデバイス（たとえば operator も保持しているデバイス）は行を保持し、node ロールだけを失います。node 専用デバイスの行は削除されます。また、一致するレガシーの Gateway 所有ノードペアリングエントリもクリアします。認可: operator.pairing は非 operator ノード行を削除できます。複数ロールデバイス上の 自分自身の node ロールを取り消すデバイストークン呼び出し元には、追加で operator.admin が必要です。
  • node.pair.verify - { nodeId, token } を検証します。
注意:
  • node.pair.request はノードごとに冪等です。繰り返し呼び出すと同じ保留中リクエストが返されます。
  • 同じ保留中ノードに対する繰り返しのリクエストは、保存済みのノードメタデータと、operator が確認できる最新の allowlist 済み宣言コマンドスナップショットを更新します。
  • 承認は 常に 新しいトークンを生成します。node.pair.request がトークンを返すことはありません。
  • operator スコープレベルと承認時チェックは、Operator scopes にまとめられています。
  • リクエストには、自動承認フロー向けのヒントとして silent: true を含めることができます。
  • node.pair.approve は、保留中リクエストの宣言コマンドを使用して追加の承認スコープを適用します:
    • コマンドなしのリクエスト: operator.pairing
    • 非 exec コマンドのリクエスト: operator.pairing + operator.write
    • system.run / system.run.prepare / system.which リクエスト: operator.pairing + operator.admin
ノードペアリングは、信頼と ID のフローに加えてトークン発行を行うものです。ノードごとのライブノードコマンドサーフェスを固定するものでは ありません。
  • ライブノードコマンドは、ノードが接続時に宣言する内容から取得され、Gateway のグローバルノードコマンドポリシー（gateway.nodes.allowCommands と denyCommands）でフィルタリングされます。
  • ノードごとの system.run allow および ask ポリシーは、ペアリングレコードではなく、ノード上の exec.approvals.node.* にあります。

​
ノードコマンドのゲート（2026.3.31+）

破壊的変更: 2026.3.31 以降、ノードペアリングが承認されるまでノードコマンドは無効です。デバイスペアリングだけでは、宣言済みノードコマンドを公開するのに十分ではなくなりました。
ノードが初めて接続すると、ペアリングが自動的に要求されます。そのリクエストが承認されるまで、そのノードからの保留中ノードコマンドはすべてフィルタリングされ、実行されません。ペアリングが承認されると、通常のコマンドポリシーに従って、ノードの宣言済みコマンドが利用可能になります。 これは次を意味します:
  • 以前、コマンド公開をデバイスペアリングだけに依存していたノードは、今後はノードペアリングも完了する必要があります。
  • ペアリング承認前にキューに入れられたコマンドは延期されず、破棄されます。

​
ノードイベントの信頼境界（2026.3.31+）

破壊的変更: ノード由来の実行は、縮小された信頼済みサーフェス上に留まるようになりました。
ノード由来の要約と関連するセッションイベントは、意図された信頼済みサーフェスに制限されます。以前、より広いホストまたはセッションツールアクセスに依存していた通知駆動またはノードトリガーのフローは、調整が必要になる場合があります。この強化により、ノードイベントがノードの信頼境界で許可される範囲を超えてホストレベルのツールアクセスへ昇格することを防ぎます。 永続的なノードプレゼンス更新も同じ ID 境界に従います。node.presence.alive イベントは、認証済みのノードデバイスセッションからのみ受け付けられ、デバイス/ノード ID がすでにペアリング済みの場合にのみペアリングメタデータを更新します。自己宣言の client.id 値だけでは、最終確認時刻の状態を書き込むには不十分です。

​
自動承認（macOS アプリ）

macOS アプリは、次の場合に サイレント承認 を試行できます:
  • リクエストに silent が付いている。
  • アプリが同じユーザーを使用して Gateway ホストへの SSH 接続を検証できる。
サイレント承認に失敗した場合は、通常の承認/拒否プロンプトにフォールバックします。

​
信頼済み CIDR デバイス自動承認

role: node の WS デバイスペアリングは、既定では手動のままです。Gateway がすでにネットワーク経路を信頼しているプライベートノードネットワークでは、operator が明示的な CIDR または正確な IP でオプトインできます: 
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}
セキュリティ境界:
  • gateway.nodes.pairing.autoApproveCidrs が未設定の場合は無効です。
  • 包括的な LAN またはプライベートネットワーク自動承認モードは存在しません。
  • 要求スコープがない新しい role: node デバイスペアリングリクエストのみが対象です。
  • operator、ブラウザー、Control UI、WebChat クライアントは手動のままです。
  • ロール、スコープ、メタデータ、公開鍵のアップグレードは手動のままです。
  • 同一ホストのループバック信頼済みプロキシヘッダーパスは対象外です。この経路はローカル呼び出し元によってなりすまされる可能性があるためです。

​
メタデータアップグレードの自動承認

すでにペアリング済みのデバイスが、機密性の低いメタデータ変更（たとえば表示名やクライアントプラットフォームのヒント）だけを伴って再接続した場合、OpenClaw はそれを metadata-upgrade として扱います。サイレント自動承認の範囲は狭く、ローカルまたは共有認証情報の所持をすでに証明済みの、信頼済み非ブラウザーローカル再接続にのみ適用されます。これには、OS バージョンメタデータ変更後の同一ホストネイティブアプリ再接続が含まれます。ブラウザー/Control UI クライアントとリモートクライアントは、引き続き明示的な再承認フローを使用します。スコープアップグレード（read から write/admin）と公開鍵の変更は、metadata-upgrade 自動承認の対象 ではありません。これらは明示的な再承認リクエストのままです。

​
QR ペアリングヘルパー

/pair qr は、モバイルクライアントやブラウザークライアントが直接スキャンできるように、ペアリングペイロードを構造化メディアとしてレンダリングします。 デバイスを削除すると、そのデバイス ID に対する古い保留中ペアリングリクエストも掃除されるため、取り消し後に nodes pending が孤立した行を表示することはありません。

​
局所性と転送ヘッダー

Gateway ペアリングは、生のソケットとアップストリームプロキシの証拠がどちらも一致する場合にのみ、接続をループバックとして扱います。リクエストがループバックで到着していても、Forwarded、任意の X-Forwarded-*、または X-Real-IP ヘッダーの証拠を含む場合、その転送ヘッダーの証拠によってループバック局所性の主張は無効になり、ペアリング経路はリクエストを同一ホスト接続としてサイレントに扱うのではなく、明示的な承認を要求します。operator 認証における同等のルールについては、Trusted Proxy Auth を参照してください。

​
ストレージ（ローカル、プライベート）

ペアリング状態は Gateway 状態ディレクトリ（既定では ~/.openclaw）の下に保存されます:
  • ~/.openclaw/nodes/paired.json
  • ~/.openclaw/nodes/pending.json
OPENCLAW_STATE_DIR を上書きすると、nodes/ フォルダーもそれに合わせて移動します。 セキュリティ上の注意:
  • トークンはシークレットです。paired.json は機密として扱ってください。
  • トークンをローテーションするには、再承認（またはノードエントリの削除）が必要です。

​
トランスポートの挙動

  • トランスポートは ステートレス です。メンバーシップは保存しません。
  • Gateway がオフラインの場合、またはペアリングが無効な場合、ノードはペアリングできません。
  • リモートモードでは、リモート Gateway のストアに対してペアリングが行われます。

​
関連