Gateway 管理型ペアリング（オプション B）

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 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 — 保留中 + ペアリング済みノードの一覧表示。
  • node.pair.approve — 保留リクエストの承認（トークン発行）。
  • node.pair.reject — 保留リクエストの拒否。
  • node.pair.verify — { nodeId, token } の検証。

注意事項：

  • node.pair.request はノードごとに冪等です。繰り返し呼び出しても同じ保留リクエストが返されます。
  • 承認時には常に新しいトークンが生成されます。node.pair.request からトークンが返されることはありません。
  • リクエストに silent: true を含めると、自動承認フローのヒントとして使えます。

自動承認（macOS アプリ）

macOS アプリは以下の条件でサイレント承認を試みることができます：

  • リクエストが silent とマークされている
  • アプリが同じユーザーで Gateway ホストへの SSH 接続を検証できる

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

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

ペアリング状態は Gateway ステートディレクトリ（デフォルト ~/.openclaw）に保存されます：

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

OPENCLAW_STATE_DIR を上書きしている場合、nodes/ フォルダもそれに従います。

セキュリティ上の注意：

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

トランスポートの動作

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