Bonjour / mDNS ディスカバリー

OpenClawはBonjour（mDNS / DNS-SD）をLAN内限定の利便機能として使用し、稼働中のGateway（WebSocketエンドポイント）を検出します。ベストエフォートであり、SSHやTailnetベースの接続の代替にはなりません。

Wide-Area Bonjour（ユニキャストDNS-SD）over Tailscale

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

大まかな手順：

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

OpenClawは任意のディスカバリードメインをサポートしており、openclaw.internal.は一例に過ぎません。iOS/Androidノードはlocal.と設定済みのwide-areaドメインの両方をブラウズします。

Gatewayの設定（推奨）

{
  gateway: { bind: "tailnet" }, // tailnet限定（推奨）
  discovery: { wideArea: { enabled: true } }, // wide-area DNS-SD公開を有効化
}

ワンタイムDNSサーバーセットアップ（ゲートウェイホスト）

openclaw dns setup --apply

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

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

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"を設定
Gatewayを再起動（またはmacOSメニューバーアプリを再起動）

アドバタイズの主体

Gatewayのみが_openclaw-gw._tcpをアドバタイズします。

サービスタイプ

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

TXTキー（非機密ヒント）

GatewayはUIフローを便利にするための小さな非機密ヒントをアドバタイズします：

role=gateway
displayName=<フレンドリー名>
lanHost=<ホスト名>.local
gatewayPort=<ポート>（Gateway WS + HTTP）
gatewayTls=1（TLS有効時のみ）
gatewayTlsSha256=<sha256>（TLS有効でフィンガープリント利用可能時のみ）
canvasPort=<ポート>（キャンバスホスト有効時のみ、現在はgatewayPortと同じ）
sshPort=<ポート>（オーバーライドされない場合デフォルト22）
transport=gateway
cliPath=<パス>（オプション、実行可能なopenclawエントリポイントの絶対パス）
tailnetDns=<magicdns>（Tailnet利用可能時のオプションヒント）

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

Bonjour/mDNS TXTレコードは認証されていません。クライアントはTXTを権威あるルーティング情報として扱ってはいけません。
クライアントは解決済みのサービスエンドポイント（SRV + A/AAAA）を使用してルーティングすべきです。lanHost、tailnetDns、gatewayPort、gatewayTlsSha256はヒントとしてのみ扱ってください。
TLSピンニングでは、アドバタイズされたgatewayTlsSha256が以前に保存されたピンを上書きすることを許可してはいけません。
iOS/Androidノードは、ディスカバリーベースの直接接続をTLS必須として扱い、初回のフィンガープリントを信頼する前に明示的なユーザー確認を求めるべきです。

macOSでのデバッグ

便利な組み込みツール：

インスタンスのブラウズ：
```
dns-sd -B _openclaw-gw._tcp local.
```
インスタンスの解決（<instance>を置き換え）：
```
dns-sd -L "<instance>" _openclaw-gw._tcp local.
```

ブラウズは成功するが解決が失敗する場合、通常はLANポリシーまたはmDNSリゾルバーの問題です。

Gatewayログでのデバッグ

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結果を一時的にドロップする場合があります。リトライしてください。
ブラウズは成功するが解決が失敗する：マシン名をシンプルに保ち（絵文字や句読点を避ける）、Gatewayを再起動してください。サービスインスタンス名はホスト名から導出されるため、過度に複雑な名前は一部のリゾルバーを混乱させます。

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

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

プロトコルレベルでは正常な動作です。
UIは表示時にデコードすべきです（iOSはBonjourEscapes.decodeを使用）。

無効化/設定

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