発見とトランスポート
ノードの発見とトランスポート（Bonjour、Tailscale、SSH）：Gateway の見つけ方。
OpenClaw には「似ているようで」本質的に異なる 2 つの問題があります：
1. オペレーターのリモート制御：macOS メニューバーアプリが別のマシンで実行されている gateway を制御する。
2. ノードのペアリング：iOS/Android（および将来のノード）が gateway を発見し、安全にペアリングを完了する。
設計目標：すべてのネットワーク発見/ブロードキャストを ''Node Gateway''（''openclaw gateway''）に配置し、クライアント（mac app、iOS）は消費者のみとする。
Terms
- Gateway：状態（sessions、pairing、node registry）を持ち、チャネルを実行する長期稼働の単一 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 ブリッジ（非推奨/削除済み）''：初期のノードトランスポート（''Bridge protocol'' を参照）。発見広告には使用されなくなった。
プロトコルの詳細：
「直接」と SSH の両方を維持する理由
- 直接 WS は同じネットワークまたは同じ tailnet 内で最もよく機能します：
- LAN 内で Bonjour 経由で自動的に発見可能
- ペアリングトークンと ACL は gateway によって一元管理
- シェルアクセス不要。プロトコル面をより集中化・監査可能に維持
- SSH は普遍的なフォールバックとして残ります：
- SSH があればどこでも機能（完全に無関係なネットワーク間でも）
- マルチキャスト/mDNS の様々な問題を回避
- 新しいインバウンドポートを追加する必要なし（SSH 以外）
発見入力（クライアントが gateway の場所を知る方法）
#
1）Bonjour / mDNS（LAN のみ）
Bonjour はベストエフォートであり、ネットワークを越えられません。主に「同じローカルネットワーク」での利便性のために使用されます。
目標の方向：
- gateway が Bonjour 経由で WS エンドポイントをブロードキャスト。
- クライアントがスキャンし、「gateway を選択」リストを表示し、選択したエンドポイントを直接接続ターゲットとして永続化。
トラブルシューティングとビーコンの詳細については、''Bonjour'' を参照してください。
##
サービスビーコンの詳細
- サービスタイプ：
- ''_openclaw-gw._tcp''（gateway トランスポートビーコン）
- 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'' 内の ''~/.openclaw/openclaw.json'' で Gateway バインドモードを制御。
- ''OPENCLAW_SSH_PORT'' で TXT 内の広告された SSH ポートをオーバーライド（デフォルト 22）。
- ''OPENCLAW_TAILNET_DNS'' で ''tailnetDns'' ヒントを公開（MagicDNS）。
- ''OPENCLAW_CLI_PATH'' で広告された CLI パスをオーバーライド。
#
2）Tailnet（クロスネットワーク）
London/Vienna のようなクロスネットワークデプロイでは、Bonjour は機能しません。推奨される直接接続ターゲット：
- Tailscale MagicDNS 名（優先）または安定した tailnet IP。
gateway が Tailscale 下で実行されていることを検出すると、''tailnetDns'' をオプションヒントとして公開（広域ビーコンに含まれる）。
#
3）手動 / SSH ターゲット
直接パスがない場合（または直接接続が無効な場合）、クライアントは常に SSH を使用できます：ループバックの gateway ポートをローカルマシンに転送。
See ''Remote access''.
トランスポート選択（クライアント戦略）
推奨されるクライアントの動作：
1. ペアリングされた直接エンドポイントが設定されており到達可能な場合、直接接続を優先。
2. それ以外の場合、Bonjour が LAN で gateway を見つけた場合、ワンクリックで「この gateway を使用」し、直接エンドポイントとして保存。
3. それ以外の場合、tailnet DNS/IP が設定されている場合、直接接続を試行。
4. それ以外の場合、SSH にフォールバック。
ペアリング + 認証（直接トランスポート）
gateway はノード/クライアントのアクセス制御の単一の真実のソースです：
- ペアリングリクエストは gateway によって作成/承認/拒否されます（''Gateway pairing'' を参照）。
- gateway は以下を強制します：
- 認証（トークン / キーペア）
- スコープ/ACL（gateway はすべてのメソッドをそのままプロキシしません）
- レート制限
コンポーネントの責任分担
- Gateway：発見ビーコンをブロードキャストし、ペアリング決定を所有し、WS エンドポイントをホスト。
- macOS app：gateway の選択を支援し、ペアリングプロンプトを表示。SSH はフォールバックのみ。
- iOS/Android nodes：Bonjour を便利なエントリポイントとして使用し、最終的にペアリングされた Gateway WS に接続。