Discovery & transports（ディスカバリーとトランスポート）

OpenClaw には、表面的には似ているように見える 2 つの異なる問題があります：

  1. オペレーターリモートコントロール：別の場所で実行されているゲートウェイを macOS メニューバーアプリが制御する。
  2. ノードペアリング：iOS/Android（および将来のノード）がゲートウェイを見つけて安全にペアリングする。

設計目標は、すべてのネットワークディスカバリー/アドバタイズを Node Gateway（openclaw gateway）に保持し、クライアント（mac アプリ、iOS）をコンシューマーとして保つことです。

用語

  • Gateway（ゲートウェイ）：状態（セッション、ペアリング、ノードレジストリ）を所有し、チャンネルを実行する単一の長時間実行されるゲートウェイプロセス。ほとんどのセットアップではホストごとに 1 つを使用します。隔離されたマルチゲートウェイセットアップも可能です。
  • Gateway WS（コントロールプレーン）：デフォルトで 127.0.0.1:18789 上の WebSocket エンドポイント；gateway.bind 経由で LAN/Tailnet にバインドできます。
  • Direct WS トランスポート：LAN/Tailnet に面した Gateway WS エンドポイント（SSH なし）。
  • SSH トランスポート（フォールバック）：SSH 経由で 127.0.0.1:18789 を転送することによるリモートコントロール。
  • レガシー TCP ブリッジ（非推奨/削除済み）：古いノードトランスポート（Bridge protocol を参照）；ディスカバリー用にアドバタイズされなくなりました。

プロトコルの詳細：

なぜ「direct」と SSH の両方を保持するのか

  • Direct WS は、同じネットワークおよび Tailnet 内で最高の UX を提供します：
    • Bonjour 経由での LAN 上の自動ディスカバリー
    • ゲートウェイが所有するペアリングトークン + ACL
    • シェルアクセスは不要；プロトコルサーフェスを厳格で監査可能な状態に保つことができます
  • SSH は普遍的なフォールバックのままです：
    • SSH アクセスがあればどこでも動作します（無関係なネットワーク間でも）
    • マルチキャスト/mDNS の問題を乗り越えます
    • SSH 以外の新しいインバウンドポートは不要

ディスカバリー入力（クライアントがゲートウェイの場所を学習する方法）

1) Bonjour / mDNS（LAN のみ）

Bonjour はベストエフォートであり、ネットワークを越えません。「同じ LAN」の利便性のためにのみ使用されます。

ターゲット方向：

  • ゲートウェイ が Bonjour 経由で WS エンドポイントをアドバタイズします。
  • クライアントは検索して「ゲートウェイを選択」リストを表示し、選択したエンドポイントを保存します。

トラブルシューティングとビーコンの詳細：Bonjour。

サービスビーコンの詳細

  • サービスタイプ：
    • _openclaw-gw._tcp（ゲートウェイトランスポートビーコン）
  • TXT キー（非シークレット）：
    • role=gateway
    • lanHost=<hostname>.local
    • sshPort=22（またはアドバタイズされているもの）
    • gatewayPort=18789（Gateway WS + HTTP）
    • gatewayTls=1（TLS が有効な場合のみ）
    • gatewayTlsSha256=<sha256>（TLS が有効でフィンガープリントが利用可能な場合のみ）
    • canvasPort=18793（デフォルトの Canvas ホストポート；/__openclaw__/canvas/ を提供）
    • cliPath=<path>（オプション；実行可能な openclaw エントリーポイントまたはバイナリへの絶対パス）
    • tailnetDns=<magicdns>（オプションヒント；Tailscale が利用可能な場合に自動検出）

無効化/オーバーライド：

  • OPENCLAW_DISABLE_BONJOUR=1 はアドバタイズを無効にします。
  • ~/.openclaw/openclaw.json の gateway.bind はゲートウェイのバインドモードを制御します。
  • OPENCLAW_SSH_PORT は TXT でアドバタイズされる SSH ポートをオーバーライドします（デフォルトは 22）。
  • OPENCLAW_TAILNET_DNS は tailnetDns ヒント（MagicDNS）を公開します。
  • OPENCLAW_CLI_PATH はアドバタイズされる CLI パスをオーバーライドします。

2) Tailnet（ネットワーク間）

London/Vienna スタイルのセットアップでは、Bonjour は役に立ちません。推奨される「direct」ターゲットは：

  • Tailscale MagicDNS 名（推奨）または安定した Tailnet IP。

ゲートウェイが Tailscale で実行されていることを検出できる場合、クライアント（広域ビーコンを含む）のオプションヒントとして tailnetDns を公開します。

3) 手動 / SSH ターゲット

直接ルートがない場合（または直接が無効な場合）、クライアントはループバックゲートウェイポートを転送することで、常に SSH 経由で接続できます。

Remote access を参照してください。

トランスポート選択（クライアントポリシー）

推奨されるクライアントの動作：

  1. ペアリングされた直接エンドポイントが設定され、到達可能な場合は、それを使用します。
  2. そうでない場合、Bonjour が LAN 上でゲートウェイを見つけた場合は、ワンタップの「このゲートウェイを使用」選択肢を提供し、直接エンドポイントとして保存します。
  3. そうでない場合、Tailnet DNS/IP が設定されている場合は、直接を試します。
  4. そうでない場合は、SSH にフォールバックします。

ペアリング + 認証（直接トランスポート）

ゲートウェイはノード/クライアントの受け入れの信頼できる情報源です。

  • ペアリングリクエストはゲートウェイで作成/承認/拒否されます（Gateway pairing を参照）。
  • ゲートウェイは以下を実施します：
    • 認証（トークン / 鍵ペア）
    • スコープ/ACL（ゲートウェイはすべてのメソッドへの生のプロキシではありません）
    • レート制限

コンポーネントごとの責任

  • ゲートウェイ：ディスカバリービーコンをアドバタイズし、ペアリング決定を所有し、WS エンドポイントをホストします。
  • macOS アプリ：ゲートウェイの選択を支援し、ペアリングプロンプトを表示し、フォールバックとしてのみ SSH を使用します。
  • iOS/Android ノード：利便性として Bonjour を検索し、ペアリングされた Gateway WS に接続します。
← ドキュメントに戻る