Gateway 管理のペアリング

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 分 後に自動的に期限切れになります。

# 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 protocol）

イベント:

• node.pair.requested - 新しい保留中のリクエストが作成されたときに発行されます。
• node.pair.resolved - リクエストが承認/拒否/期限切れになったときに発行されます。

メソッド:

• node.pair.request - 保留中のリクエストを作成または再利用します。
• node.pair.list - 保留中 + ペアリング済みノードを一覧表示します（operator.pairing）。
• node.pair.approve - 保留中のリクエストを承認します（トークンを発行）。
• node.pair.reject - 保留中のリクエストを拒否します。
• node.pair.remove - 古くなったペアリング済みノードのエントリを削除します。
• node.pair.verify - { nodeId, token } を検証します。

メモ:

• node.pair.request はノードごとにべき等です。繰り返し呼び出すと同じ保留中のリクエストが返されます。
• 同じ保留中ノードへの繰り返しリクエストでは、保存済みのノードメタデータと、オペレーターの可視性のために許可リスト化された最新の宣言済みコマンドスナップショットも更新されます。
• 承認では 常に 新しいトークンが生成されます。node.pair.request からトークンが返されることはありません。
• オペレータースコープレベルと承認時チェックの概要は オペレータースコープ にあります。
• リクエストには、自動承認フローのヒントとして silent: true を含めることができます。
• node.pair.approve は保留中リクエストの宣言済みコマンドを使用して、追加の承認スコープを強制します:
  • コマンドなしリクエスト: operator.pairing
  • 非 exec コマンドリクエスト: operator.pairing + operator.write
  • system.run / system.run.prepare / system.which リクエスト: operator.pairing + operator.admin

# ノードコマンドの制御（2026.3.31+）

ノードが初めて接続すると、ペアリングが自動的に要求されます。ペアリングリクエストが承認されるまで、そのノードからの保留中のノードコマンドはすべてフィルタリングされ、実行されません。ペアリング承認によって信頼が確立されると、ノードの宣言済みコマンドは通常のコマンドポリシーに従って利用可能になります。

これは次のことを意味します:

• 以前はコマンド公開をデバイスペアリングだけに依存していたノードは、今後ノードペアリングを完了する必要があります。
• ペアリング承認前にキューに入れられたコマンドは、延期されずに破棄されます。

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

ノード由来のサマリーと関連するセッションイベントは、意図された信頼済みサーフェスに制限されます。通知駆動またはノードトリガーのフローで、以前はより広いホストまたはセッションツールアクセスに依存していたものは、調整が必要になる場合があります。この強化により、ノードイベントがノードの信頼境界で許可される範囲を超えてホストレベルのツールアクセスへ昇格できないようになります。

永続的なノードプレゼンス更新も同じ ID 境界に従います。node.presence.alive イベントは、認証済みのノードデバイスセッションからのみ受け入れられ、デバイス/ノード ID がすでにペアリング済みの場合にのみペアリングメタデータを更新します。自己宣言された client.id 値だけでは、最終確認状態を書き込むには不十分です。

# 自動承認（macOS アプリ）

macOS アプリは、次の場合に任意で サイレント承認 を試行できます:

• リクエストが silent としてマークされていること、および
• アプリが同じユーザーを使用して Gateway ホストへの SSH 接続を検証できること。

サイレント承認が失敗した場合は、通常の「承認/拒否」プロンプトにフォールバックします。

# 信頼済み CIDR によるデバイス自動承認

role: node の WS デバイスペアリングは、既定では引き続き手動です。Gateway がすでにネットワーク経路を信頼しているプライベートノードネットワークでは、オペレーターが明示的な CIDR または正確な IP でオプトインできます:

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

セキュリティ境界:

• gateway.nodes.pairing.autoApproveCidrs が未設定の場合は無効です。
• LAN 全体またはプライベートネットワーク全体を自動承認するモードはありません。
• 要求されたスコープがない、新規の role: node デバイスペアリングのみが対象です。
• オペレーター、ブラウザー、Control UI、WebChat クライアントは手動のままです。
• ロール、スコープ、メタデータ、公開鍵のアップグレードは手動のままです。
• 同一ホストのループバック trusted-proxy ヘッダー経路は対象外です。この経路はローカル呼び出し元によってなりすまし可能なためです。

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

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

# QR ペアリングヘルパー

/pair qr は、モバイルおよびブラウザークライアントが直接スキャンできるように、ペアリングペイロードを構造化メディアとしてレンダリングします。

デバイスを削除すると、そのデバイス ID に対する古い保留中のペアリングリクエストも掃除されるため、取り消し後に nodes pending に孤立した行は表示されません。

# ローカリティと転送ヘッダー

Gateway ペアリングは、raw ソケットと上流プロキシの証拠の両方が一致する場合にのみ、接続をループバックとして扱います。リクエストがループバックで到着しても、非ローカルの送信元を指す X-Forwarded-For / X-Forwarded-Host / X-Forwarded-Proto ヘッダーを含む場合、その転送ヘッダーの証拠により、ループバックローカリティの主張は不適格になります。その場合、ペアリング経路は、リクエストを同一ホスト接続としてサイレントに扱うのではなく、明示的な承認を要求します。オペレーター認証における同等のルールについては、信頼済みプロキシ認証 を参照してください。

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

ペアリング状態は Gateway 状態ディレクトリ（既定は ~/.openclaw）配下に保存されます:

• ~/.openclaw/nodes/paired.json
• ~/.openclaw/nodes/pending.json

OPENCLAW_STATE_DIR を上書きした場合、nodes/ フォルダーもそれに合わせて移動します。

セキュリティメモ:

• トークンはシークレットです。paired.json は機密として扱ってください。
• トークンのローテーションには再承認（またはノードエントリの削除）が必要です。

# トランスポートの動作

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

# 関連

• チャンネルペアリング
• ノード
• デバイス CLI