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 state ディレクトリ（デフォルト ~/.openclaw）に保存されます：

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

OPENCLAW_STATE_DIR をオーバーライドすると、nodes/ フォルダもそれに従って移動します。

セキュリティ注意事項：

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

トランスポート動作

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