OpenClawのネットワーク設定：ゲートウェイ接続と検出を最適化

リモート環境にあるデバイスを操作したり、ローカルネットワーク内のサービスを連携させたりするのは、意外と手間がかかるものです。「設定が複雑すぎて繋がらない」「ネットワークを越えると見失ってしまう」といった経験はありませんか？

OpenClawでは、こうした接続の煩わしさを解消し、スムーズな連携を実現するための仕組みを整えています。この記事では、OpenClawがどのようにしてGatewayを検出し、安全な通信経路を確立しているのか、その舞台裏を解説します。

用語解説

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

Operator remote control: 別の場所で動作しているGatewayを、macOSのメニューバーアプリから操作すること。
Node pairing: iOS/Android（および将来のNode）がGatewayを見つけ、安全にペアリングすること。

設計のゴールは、ネットワークの検出やアドバタイズに関するすべての処理を Node Gateway (openclaw gateway) に集約し、クライアント（macOSアプリ、iOS）はそれを利用する側に徹することです。

Gateway: 状態（セッション、ペアリング、Nodeレジストリ）を保持し、チャネルを実行する単一の常駐プロセスです。通常はホストごとに1つ使用しますが、分離されたマルチGateway構成も可能です。
Gateway WS (control plane): デフォルトで 127.0.0.1:18789 で動作するWebSocketエンドポイントです。gateway.bind を介してLANやtailnetにバインドできます。
Direct WS transport: SSHを経由しない、LANやtailnet向けのGateway WSエンドポイントです。
SSH transport (fallback): 127.0.0.1:18789 をSSH経由でフォワーディングしてリモート操作を行う方法です。
Legacy TCP bridge (deprecated/removed): 古いNodeトランスポートです（Bridge protocol を参照）。現在は検出用のアドバタイズは行われません。

プロトコルの詳細は以下を確認してください。

なぜ「直接接続」と「SSH」の両方を維持するのか

OpenClawが2つの方法をサポートしているのには理由があります。

Direct WS は、同一ネットワーク内やtailnet内において最高のUXを提供します。
- BonjourによるLAN上の自動検出が可能です。
- ペアリングトークンとACLはGatewayによって管理されます。
- シェルアクセスが不要なため、プロトコルの範囲を限定し、監査しやすい状態に保てます。
SSH は、あらゆる場面で使える万能なフォールバック手段です。
- SSHアクセスさえあれば、異なるネットワーク間でも動作します。
- マルチキャストやmDNSの問題に左右されません。
- SSH以外の新しいインバウンドポートを開放する必要がありません。

ディスカバリ入力（クライアントがGatewayを特定する方法）

1) Bonjour / mDNS (LANのみ)

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

動作の方向性：

Gateway は、自身のWSエンドポイントをBonjour経由でアドバタイズします。
クライアントはそれをブラウズして「Gateway選択リスト」を表示し、選択されたエンドポイントを保存します。

トラブルシューティングとビーコンの詳細は Bonjour を参照してください。

サービスビーコンの詳細

サービスタイプ:
- _openclaw-gw._tcp (gateway transport beacon)
TXTキー（非公開情報ではありません）:
- role=gateway
- transport=gateway
- displayName=<friendly name> (設定された表示名)
- lanHost=<hostname>.local
- sshPort=22 (またはアドバタイズされたポート)
- gatewayPort=18789 (Gateway WS + HTTP)
- gatewayTls=1 (TLS有効時のみ)
- gatewayTlsSha256=<sha256> (TLS有効でフィンガープリントが利用可能な場合のみ)
- canvasPort=<port> (canvasホストのポート。現在は gatewayPort と同じ)
- cliPath=<path> (任意。実行可能な openclaw バイナリへの絶対パス)
- tailnetDns=<magicdns> (任意。Tailscaleが利用可能な場合に自動検出)

セキュリティ上の注意点：

Bonjour/mDNSのTXTレコードは 認証されていません。クライアントはTXTの値をUX上のヒントとしてのみ扱う必要があります。
ルーティング（ホスト/ポート）は、TXT内の lanHost や tailnetDns よりも、解決されたサービスエンドポイント (SRV + A/AAAA) を優先すべきです。
TLSピン留めにおいて、アドバタイズされた gatewayTlsSha256 で既存のピンを上書きしてはいけません。
iOS/Androidノードは、検出ベースの直接接続を TLS限定 として扱い、初回保存前に「このフィンガープリントを信頼する」という明示的な確認（アウトオブバンド検証）を求める必要があります。

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

OPENCLAW_DISABLE_BONJOUR=1 でアドバタイズを無効にします。
~/.openclaw/openclaw.json の gateway.bind でバインドモードを制御します。
OPENCLAW_SSH_PORT でアドバタイズするSSHポートを上書きします（デフォルトは22）。
OPENCLAW_TAILNET_DNS で tailnetDns ヒント (MagicDNS) を公開します。
OPENCLAW_CLI_PATH でアドバタイズするCLIパスを上書きします。

2) Tailnet (ネットワークを越えた接続)

離れた場所にある拠点同士のようなセットアップでは、Bonjourは機能しません。その場合の推奨される接続先は以下の通りです。

Tailscale MagicDNS名（推奨）、または固定のtailnet IP。

Gatewayは、自身がTailscale下で動作していることを検出すると、クライアント向けのヒントとして tailnetDns を公開します。

macOSアプリでは、Gateway検出において生のTailscale IPよりもMagicDNS名を優先するようになりました。MagicDNS名はIPアドレスが変更（ノードの再起動やCGNATの再割り当てなど）されても自動的に現在のIPを解決するため、信頼性が向上します。

3) 手動 / SSHターゲット

直接のルートがない場合や直接接続が無効な場合、クライアントはループバックのGatewayポートをフォワーディングすることで、いつでもSSH経由で接続できます。

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

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

推奨されるクライアントの動作フローは以下の通りです。

ペアリング済みの直接接続エンドポイントが設定されており、到達可能な場合はそれを使用する。
そうでない場合、BonjourがLAN上でGatewayを見つけたら「このGatewayを使用する」という選択肢を提示し、直接接続エンドポイントとして保存する。
そうでない場合、tailnetのDNS/IPが設定されていれば直接接続を試みる。
それ以外の場合は、SSHにフォールバックする。

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

Gatewayは、Nodeやクライアントの受け入れに関する信頼できる情報源（Source of Truth）となります。

ペアリング要求の作成、承認、拒否はGateway内で行われます（Gateway pairing を参照）。
Gatewayは以下の要素を強制します：
- 認証（トークン / キーペア）
- スコープとACL（Gatewayはすべてのメソッドへの単純なプロキシではありません）
- レート制限
- 接続ログの管理

コンポーネントごとの役割

Gateway: ディスカバリビーコンのアドバタイズ、ペアリングの判定、WSエンドポイントのホストを担当します。
macOS app: Gatewayの選択を補助し、ペアリングのプロンプトを表示します。SSHはフォールバックとしてのみ使用します。
iOS/Android nodes: 利便性のためにBonjourをブラウズし、ペアリング済みのGateway WSに接続します。

AI Setup Assistant

次のステップ

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。