メインコンテンツへスキップ

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

OpenClaw には、表面的には似ているものの、異なる 2 つの問題があります。
  1. オペレーターのリモート制御: 別の場所で稼働しているゲートウェイを制御する macOS メニューバーアプリ。
  2. ノードのペアリング: iOS／Android（および将来のノード）がゲートウェイを見つけ、安全にペアリングすること。
設計目標は、すべてのネットワークディスカバリー／アドバタイズを Node Gateway（openclaw gateway）に集約し、クライアント（mac アプリ、iOS）はコンシューマーとして扱うことです。

​
用語

  • Gateway: 状態（セッション、ペアリング、ノードレジストリ）を所有し、チャンネルを実行する、単一の長時間稼働するゲートウェイプロセス。多くの構成ではホストごとに 1 つを使用しますが、分離されたマルチゲートウェイ構成も可能です。 ほとんどのセットアップはホストごとに1つを使用します。孤立したマルチゲートウェイの設定は可能です。 ほとんどのセットアップはホストごとに1つを使用します。孤立したマルチゲートウェイの設定は可能です。
  • Gateway WS (control plane): 既定で 127.0.0.1:18789 にある WebSocket エンドポイント。gateway.bind により LAN／tailnet にバインドできます。
  • Direct WS transport: LAN／tailnet 向けの Gateway WS エンドポイント（SSH なし）。
  • SSH transport (fallback): SSH 経由で 127.0.0.1:18789 をフォワードするリモート制御。
  • Legacy TCP bridge (deprecated/removed): 旧来のノードトランスポート（Bridge protocol を参照）。ディスカバリーではもはやアドバタイズされません。
プロトコルの詳細:

​
「direct」と SSH の両方を維持する理由

  • Direct WS は、同一ネットワークおよび tailnet 内で最良の UX を提供します。
    • Bonjour による LAN 上の自動ディスカバリー
    • ゲートウェイが所有するペアリングトークンと ACL
    • シェルアクセス不要。プロトコルの表面を厳密かつ監査可能に保てます
  • SSH は汎用的なフォールバックとして残します。
    • SSH アクセスがあればどこでも動作します（無関係なネットワーク間でも可）
    • マルチキャスト／mDNS の問題に耐性があります
    • SSH 以外の新たなインバウンドポートを必要としません

​
Discovery inputs（クライアントがゲートウェイの所在を知る方法）

​
1. Bonjour / mDNS（LAN のみ）

Bonjourはベストエフォートであり、ネットワークを横断することはありません。 Bonjour はベストエフォートであり、ネットワークを越えません。「同一 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 が利用可能な場合は自動検出）
セキュリティに関する注意:
  • Bonjour/mDNS の TXT レコードは認証されていません。 クライアントは TXT の値を UX 上のヒントとしてのみ扱う必要があります。
  • ルーティング（host/port）は、TXT で提供される lanHost、tailnetDns、gatewayPort よりも、解決されたサービスエンドポイント（SRV + A/AAAA）を優先する必要があります。
  • TLS ピンニングでは、広告された gatewayTlsSha256 によって、以前に保存されたピンが上書きされることがあってはなりません。
  • iOS/Android ノードは、ディスカバリーベースの直接接続をTLS のみとして扱い、初回ピンを保存する前に明示的な「このフィンガープリントを信頼する」確認（アウトオブバンド検証）を必須とする必要があります。
無効化／上書き:
  • OPENCLAW_DISABLE_BONJOUR=1 はアドバタイズを無効化します。
  • gateway.bind を ~/.openclaw/openclaw.json に設定すると、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 を公開します（広域ビーコンを含む）。

​
3. 手動／SSH ターゲット

直接ルートがない場合（または直接接続が無効な場合）、クライアントはループバックのゲートウェイポートをフォワードすることで、常に SSH 経由で接続できます。 Remote access を参照してください。

​
Transport selection（クライアントのポリシー）

推奨されるクライアントの挙動:
  1. ペアリング済みの直接エンドポイントが設定され、到達可能であれば、それを使用します。
  2. そうでなければ、Bonjour が LAN 上のゲートウェイを検出した場合、「このゲートウェイを使用」のワンタップ選択肢を提示し、直接エンドポイントとして保存します。
  3. そうでない場合は、tailnet DNS/IP が設定されている場合は、直接試してみてください。
  4. 最後に、SSH にフォールバックします。

​
Pairing + auth（直接トランスポート）

ノード／クライアントの受け入れに関する信頼の源泉はゲートウェイです。
  • ペアリング要求はゲートウェイで作成／承認／拒否されます（Gateway pairing を参照）。
  • ゲートウェイは次を強制します。
    • 認証（トークン／鍵ペア）
    • スコープ／ACL（ゲートウェイは、すべてのメソッドへの生のプロキシではありません）
    • レート制限

​
Responsibilities by component

  • Gateway: ディスカバリー用ビーコンをアドバタイズし、ペアリングの意思決定を所有し、WS エンドポイントをホストします。
  • macOS app: ゲートウェイの選択を支援し、ペアリングのプロンプトを表示し、SSH はフォールバックとしてのみ使用します。
  • iOS／Android nodes: 利便性のために Bonjour を参照し、ペアリング済みの Gateway WS に接続します。