ディスカバリーとトランスポート

OpenClawには、一見似ているが異なる2つの課題があります：

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

設計目標は、すべてのネットワークディスカバリー/アドバタイズをノードGateway（openclaw gateway）に集約し、クライアント（Macアプリ、iOS）はコンシューマーとして機能させることです。

用語

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

プロトコルの詳細：

「ダイレクト」とSSHの両方を維持する理由

  • ダイレクトWSは同一ネットワークおよびTailnet内で最良のUXを提供します：
    • LAN上のBonjourによる自動検出
    • ゲートウェイが管理するペアリングトークン＋ACL
    • シェルアクセス不要。プロトコルサーフェスを狭く監査可能に保てる
  • SSHはユニバーサルなフォールバックとして残ります：
    • SSHアクセスがあればどこでも動作（無関係なネットワーク間でも）
    • マルチキャスト/mDNSの問題を回避
    • SSH以外に新しいインバウンドポートが不要

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

1) Bonjour / mDNS（LAN限定）

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

方向性：

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

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

サービスビーコンの詳細

  • サービスタイプ：
    • _openclaw-gw._tcp（ゲートウェイトランスポートビーコン）
  • TXTキー（非機密）：
    • role=gateway
    • lanHost=<ホスト名>.local
    • sshPort=22（またはアドバタイズされた値）
    • gatewayPort=18789（Gateway WS + HTTP）
    • gatewayTls=1（TLS有効時のみ）
    • gatewayTlsSha256=<sha256>（TLS有効でフィンガープリント利用可能時のみ）
    • canvasPort=<ポート>（キャンバスホスト有効時。現在はgatewayPortと同じ）
    • cliPath=<パス>（オプション。実行可能なopenclawエントリポイントまたはバイナリの絶対パス）
    • tailnetDns=<magicdns>（オプションヒント。Tailscale利用可能時に自動検出）

セキュリティに関する注意：

  • Bonjour/mDNS TXTレコードは認証されていません。クライアントはTXT値をUXヒントとしてのみ扱うべきです。
  • ルーティング（ホスト/ポート）は、TXTで提供されるlanHost、tailnetDns、gatewayPortよりも、解決済みのサービスエンドポイント（SRV + A/AAAA）を優先すべきです。
  • TLSピンニングでは、アドバタイズされたgatewayTlsSha256が以前に保存されたピンを上書きすることを許可してはいけません。
  • iOS/Androidノードは、ディスカバリーベースの直接接続をTLS必須として扱い、初回ピンの保存前に明示的な「このフィンガープリントを信頼する」確認を求めるべきです（帯域外検証）。

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

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

2) Tailnet（ネットワーク横断）

ロンドン/ウィーンのようなセットアップでは、Bonjourは機能しません。推奨される「ダイレクト」ターゲットは：

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

ゲートウェイがTailscale配下で動作していることを検出できる場合、クライアント向けのオプションヒントとしてtailnetDnsを公開します（wide-areaビーコンを含む）。

3) 手動 / SSHターゲット

ダイレクトルートがない場合（またはダイレクトが無効化されている場合）、クライアントはループバックゲートウェイポートのSSH転送で常に接続できます。

リモートアクセスを参照してください。

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

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

  1. ペアリング済みのダイレクトエンドポイントが設定されていて到達可能な場合、それを使用。
  2. BonjourがLAN上でゲートウェイを検出した場合、ワンタップの「このゲートウェイを使用」選択を提示し、ダイレクトエンドポイントとして保存。
  3. Tailnet DNS/IPが設定されている場合、ダイレクトを試行。
  4. それ以外の場合、SSHにフォールバック。

ペアリング＋認証（ダイレクトトランスポート）

ゲートウェイがノード/クライアントの受け入れに関する信頼の源です。

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

コンポーネント別の責務

  • Gateway：ディスカバリービーコンをアドバタイズし、ペアリング判断を管理し、WSエンドポイントをホスト。
  • macOSアプリ：ゲートウェイの選択を支援し、ペアリングプロンプトを表示し、SSHはフォールバックとしてのみ使用。
  • iOS/Androidノード：利便性としてBonjourをブラウズし、ペアリング済みのGateway WSに接続。
arrow_back
前へ
Pairing
次へ
Bonjour
arrow_forward