Bonjour / mDNS discovery（Bonjour / mDNS ディスカバリー）

OpenClaw は、アクティブな Gateway（WebSocket エンドポイント）を発見するための LAN 専用の利便機能 として Bonjour（mDNS / DNS‑SD）を使用します。これはベストエフォートであり、SSH や Tailnet ベースの接続性を 置き換えるものではありません。

Tailscale 経由の広域 Bonjour（ユニキャスト DNS‑SD）

ノードとゲートウェイが異なるネットワーク上にある場合、マルチキャスト mDNS は境界を越えられません。Tailscale 経由で ユニキャスト DNS‑SD（「広域 Bonjour」）に切り替えることで、同じディスカバリー UX を維持できます。

大まかな手順：

  1. ゲートウェイホスト上で DNS サーバーを実行します（Tailnet 経由でアクセス可能）。
  2. 専用ゾーン配下で _openclaw-gw._tcp の DNS‑SD レコードを公開します（例：openclaw.internal.）。
  3. Tailscale スプリット DNS を設定して、選択したドメインがクライアント（iOS を含む）に対してその DNS サーバー経由で解決されるようにします。

OpenClaw は任意のディスカバリードメインをサポートしています。openclaw.internal. は単なる例です。iOS/Android ノードは local. と設定された広域ドメインの両方を検索します。

Gateway 設定（推奨）

{
  gateway: { bind: "tailnet" }, // tailnet 専用（推奨）
  discovery: { wideArea: { enabled: true } } // 広域 DNS-SD パブリッシングを有効化
}

1回限りの DNS サーバーセットアップ（ゲートウェイホスト）

openclaw dns setup --apply

これにより CoreDNS がインストールされ、以下のように設定されます：

  • ゲートウェイの Tailscale インターフェースのみでポート 53 をリッスン
  • 選択したドメイン（例：openclaw.internal.）を ~/.openclaw/dns/<domain>.db から提供

Tailnet 接続されたマシンから検証：

dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

Tailscale DNS 設定

Tailscale 管理コンソールで：

  • ゲートウェイの Tailnet IP を指すネームサーバーを追加します（UDP/TCP 53）。
  • ディスカバリードメインがそのネームサーバーを使用するようにスプリット DNS を追加します。

クライアントが Tailnet DNS を受け入れると、iOS ノードは マルチキャストなしでディスカバリードメイン内の _openclaw-gw._tcp を検索できます。

Gateway リスナーセキュリティ（推奨）

Gateway WS ポート（デフォルト 18789）は、デフォルトでループバックにバインドされます。LAN/Tailnet アクセスの場合は、明示的にバインドし、認証を有効にしたままにしてください。

Tailnet 専用セットアップの場合：

  • ~/.openclaw/openclaw.json で gateway.bind: "tailnet" を設定します。
  • ゲートウェイを再起動します（または macOS メニューバーアプリを再起動します）。

アドバタイズするもの

_openclaw-gw._tcp をアドバタイズするのはゲートウェイのみです。

サービスタイプ

  • _openclaw-gw._tcp — ゲートウェイトランスポートビーコン（macOS/iOS/Android ノードで使用）。

TXT キー（非シークレットヒント）

ゲートウェイは、UI フローを便利にするために小さな非シークレットヒントをアドバタイズします：

  • role=gateway
  • displayName=<friendly name>
  • lanHost=<hostname>.local
  • gatewayPort=<port>（Gateway WS + HTTP）
  • gatewayTls=1（TLS が有効な場合のみ）
  • gatewayTlsSha256=<sha256>（TLS が有効でフィンガープリントが利用可能な場合のみ）
  • canvasPort=<port>（Canvas ホストが有効な場合のみ；デフォルト 18793）
  • sshPort=<port>（オーバーライドされていない場合はデフォルトで 22）
  • transport=gateway
  • cliPath=<path>（オプション；実行可能な openclaw エントリーポイントへの絶対パス）
  • tailnetDns=<magicdns>（オプションヒント；Tailnet が利用可能な場合）

macOS でのデバッグ

便利な組み込みツール：

  • インスタンスを検索： 
    dns-sd -B _openclaw-gw._tcp local.
  • 1つのインスタンスを解決（<instance> を置き換え）： 
    dns-sd -L "<instance>" _openclaw-gw._tcp local.

検索は動作するが解決が失敗する場合、通常は LAN ポリシーまたは mDNS リゾルバーの問題です。

Gateway ログでのデバッグ

ゲートウェイはローリングログファイルを書き込みます（起動時に gateway log file: ... として表示されます）。特に以下の bonjour: 行を探してください：

  • bonjour: advertise failed ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
  • bonjour: watchdog detected non-announced service ...

iOS ノードでのデバッグ

iOS ノードは NWBrowser を使用して _openclaw-gw._tcp を発見します。

ログをキャプチャするには：

  • 設定 → Gateway → Advanced → Discovery Debug Logs
  • 設定 → Gateway → Advanced → Discovery Logs → 再現 → Copy

ログにはブラウザの状態遷移と結果セットの変更が含まれます。

一般的な障害モード

  • Bonjour はネットワークを越えられません：Tailnet または SSH を使用してください。
  • マルチキャストがブロックされている：一部の Wi-Fi ネットワークは mDNS を無効にしています。
  • スリープ / インターフェースの変動：macOS は一時的に mDNS 結果を削除する場合があります；再試行してください。
  • 検索は動作するが解決が失敗：マシン名をシンプルに保ち（絵文字や句読点を避ける）、ゲートウェイを再起動してください。サービスインスタンス名はホスト名から派生するため、過度に複雑な名前は一部のリゾルバーを混乱させる可能性があります。

エスケープされたインスタンス名（\032）

Bonjour/DNS‑SD は、サービスインスタンス名のバイトを 10 進数の \DDD シーケンスとしてエスケープすることがよくあります（例：スペースは \032 になります）。

  • これはプロトコルレベルでは正常です。
  • UI は表示用にデコードする必要があります（iOS は BonjourEscapes.decode を使用）。

無効化 / 設定

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

関連ドキュメント

  • ディスカバリーポリシーとトランスポート選択：Discovery
  • ノードペアリング + 承認：Gateway pairing
← ドキュメントに戻る