Bonjour（mDNS）由发现

OpenClaw uses Bonjour (mDNS / DNS‑SD) as a **LAN‑only convenience** to discover an active Gateway (WebSocket endpoint). It is best‑effort and does **not** replace SSH or Tailnet-based connectivity.

如果节点和网关位于不同的网络，多播 mDNS 将无法跨越边界。您可以通过 Tailscale 切换到**单播 DNS‑SD**（「广域 Bonjour」）来保持相同的发现体验。

概要手順：

1. Run a DNS server on the gateway host (reachable over Tailnet).
2. Publish DNS-SD records for _openclaw-gw._tcp under a dedicated zone (example: openclaw.internal.).
3. Configure Tailscale **split DNS** so your chosen domain resolves via that DNS server for clients (including iOS).

OpenClaw supports any discovery domain; openclaw.internal. is just an example.

iOS/Android nodes browse both local. and your configured wide‑area domain.

openclaw dns setup --apply

This installs CoreDNS and configures it to:

• listen on port 53 only on the gateway's Tailscale interfaces
• ~/.openclaw/dns/<domain>.db to serve a chosen domain (e.g., openclaw.internal.)

tailnet 连接済见机器从验证：

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

In the Tailscale admin console:

• 添加一个指向网关 tailnet IP 的名称服务器（UDP/TCP 53）。
• Add split DNS so your discovery domain uses that nameserver.

一旦客户端接受 tailnet DNS，iOS 节点就可以在您的发现域中浏览 _openclaw-gw._tcp，无需多播。

The Gateway WS port (default 18789) binds to loopback by default. For LAN/tailnet access, bind explicitly and keep auth enabled.

tailnet 专用配置的場合：

• gateway.bind: "tailnet" 在 ~/.openclaw/openclaw.json 设置执行。
• Restart the Gateway (or restart the macOS menubar app).

Only the Gateway advertises _openclaw-gw._tcp.

• _openclaw-gw._tcp — Gateway 的传输端口信标（macOS/iOS/Android 节点在使用）。

The Gateway advertises small non‑secret hints to make UI flows convenient:

• role=gateway
• <code>displayName=<friendly name>'</code>
• <code>lanHost=<hostname>.local</code>
• <code>gatewayPort=<port>'</code>（Gateway WS + HTTP）
• gatewayTls=1（TLS 启用時仅）
• <code>gatewayTlsSha256=<sha256>'</code> (only when TLS is enabled and fingerprint is available)
• <code>canvasPort=<port>'</code>（canvas host 启用時仅。默认 <code>18793</code>）
• <code>sshPort=<port>'</code> (defaults to 22 when not overridden)
• transport=gateway
• <code>cliPath=<path>'</code>（任意。运行可能那 <code>openclaw</code> 条目积分钟的绝对路径）
• <code>tailnetDns=<magicdns>'</code>（tailnet 利用時的任意提示）

便利那組见入见工具：

Browse instances:

dns-sd -B _openclaw-gw._tcp local.

实示例解决（<instance> 替换）：

dns-sd -L "<instance>" _openclaw-gw._tcp local.

如果浏览正常但解析失败，通常是由于 LAN 策略或 mDNS 解析器问题。

The Gateway writes a rolling log file (printed on startup as gateway log file: ...). Look for bonjour: lines, especially:

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

The iOS node uses NWBrowser to discover _openclaw-gw._tcp.

日志获取：

• 设置 → Gateway → 详情 → 发现调试日志
• 设置 → Gateway → 详情 → 发现日志 → 重现 → 复制

日志包括浏览器状态转换和结果集更改。

• Bonjour doesn't cross networks: use Tailnet or SSH.
• Multicast blocked: some Wi-Fi networks disable mDNS.
• Sleep / interface churn: macOS may temporarily drop mDNS results; retry.
• Browse works but resolve fails: keep machine names simple (avoid emojis or punctuation), then restart the Gateway. The service instance name derives from the host name, so overly complex names can confuse some resolvers.

Bonjour/DNS-SD often escapes bytes in service instance names as decimal \DDD sequences (e.g. spaces become \032).

• 这在协议级别是正常的。
• 显示用在 UI 側在解码请（iOS 是 BonjourEscapes.decode 使用）。

• OPENCLAW_DISABLE_BONJOUR=1 disables advertising.
• gateway.bind in ~/.openclaw/openclaw.json controls the Gateway bind mode.
• OPENCLAW_SSH_PORT 在 TXT 在公开执行 SSH 端口上写机执行。
• OPENCLAW_TAILNET_DNS 在 TXT 在 MagicDNS 提示公开执行。
• OPENCLAW_CLI_PATH 在公开执行 CLI 路径上写机执行。

• 发现策略和传输端口选择：Discovery
• 节点的配对和批准：Gateway pairing