@@ -8,11 +8,12 @@ title: "Bonjour discovery"
8899# Bonjour / mDNS discovery
101011-OpenClaw uses Bonjour (mDNS / DNS‑SD) to discover an active Gateway (WebSocket endpoint).
11+OpenClaw can use Bonjour (mDNS / DNS-SD) to discover an active Gateway (WebSocket endpoint).
1212Multicast `local.` browsing is a **LAN-only convenience**. The bundled `bonjour`
13-plugin owns LAN advertising and is enabled by default. For cross-network discovery,
14-the same beacon can also be published through a configured wide-area DNS-SD domain.
15-Discovery is still best-effort and does **not** replace SSH or Tailnet-based connectivity.
13+plugin owns LAN advertising. It auto-starts on macOS hosts and is opt-in on
14+Linux, Windows, and containerized Gateway deployments. For cross-network discovery, the same
15+beacon can also be published through a configured wide-area DNS-SD domain. Discovery
16+is still best-effort and does **not** replace SSH or Tailnet-based connectivity.
16171718## Wide-area Bonjour (Unicast DNS-SD) over Tailscale
1819@@ -81,8 +82,8 @@ For tailnet‑only setups:
8182## What advertises
82838384Only the Gateway advertises `_openclaw-gw._tcp`. LAN multicast advertising is
84-provided by the bundled `bonjour` plugin; wide-area DNS-SD publishing remains
85-Gateway-owned.
85+provided by the bundled `bonjour` plugin when the plugin is enabled; wide-area
86+DNS-SD publishing remains Gateway-owned.
86878788## Service types
8889@@ -159,13 +160,30 @@ To capture logs:
159160160161The log includes browser state transitions and result‑set changes.
161162163+## When to enable Bonjour
164+165+Bonjour auto-starts for empty-config Gateway startup on macOS hosts because the
166+local app and nearby iOS/Android nodes commonly rely on same-LAN discovery.
167+168+Enable Bonjour explicitly when same-LAN auto-discovery is useful on Linux,
169+Windows, or another non-macOS host:
170+171+```bash
172+openclaw plugins enable bonjour
173+```
174+175+When enabled, Bonjour uses `discovery.mdns.mode` to decide how much TXT metadata
176+to publish. The default mode is `minimal`; use `full` only when local clients need
177+`cliPath` or `sshPort` hints, and use `off` to suppress LAN multicast without
178+changing plugin enablement.
179+162180## When to disable Bonjour
163181164-Disable Bonjour only when LAN multicast advertising is unavailable or harmful.
165-The common case is a Gateway running behind Docker bridge networking, WSL, or a
166-network policy that drops mDNS multicast. In those environments the Gateway is
167-still reachable through its published URL, SSH, Tailnet, or wide-area DNS-SD,
168-but LAN auto-discovery is not reliable.
182+Leave Bonjour disabled when LAN multicast advertising is unnecessary, unavailable,
183+or harmful. The common cases are non-macOS servers, Docker bridge networking,
184+WSL, or a network policy that drops mDNS multicast. In those environments the
185+Gateway is still reachable through its published URL, SSH, Tailnet, or wide-area
186+DNS-SD, but LAN auto-discovery is not reliable.
169187170188Prefer the existing environment override when the problem is deployment-scoped:
171189@@ -177,8 +195,8 @@ That disables LAN multicast advertising without changing plugin configuration.
177195It is safe for Docker images, service files, launch scripts, and one-off
178196debugging because the setting disappears when the environment does.
179197180-Use plugin configuration only when you intentionally want to turn off the
181-bundled LAN discovery plugin for that OpenClaw config:
198+Use plugin configuration when you intentionally want to turn off the bundled LAN
199+discovery plugin for that OpenClaw config:
182200183201```bash
184202openclaw plugins disable bonjour
@@ -193,8 +211,8 @@ and the LAN, so advertising from the container rarely makes discovery work.
193211194212Important gotchas:
195213196-- Disabling Bonjour does not stop the Gateway. It only stops LAN multicast
197- advertising.
214+- Bonjour auto-starts on macOS hosts and is opt-in elsewhere. Leaving it
215+disabled does not stop the Gateway; it only skips LAN multicast advertising.
198216- Disabling Bonjour does not change `gateway.bind`; Docker still defaults to
199217`OPENCLAW_GATEWAY_BIND=lan` so the published host port can work.
200218- Disabling Bonjour does not disable wide-area DNS-SD. Use wide-area discovery
@@ -226,8 +244,8 @@ If a node no longer auto-discovers the Gateway after Docker setup:
226244- Cross-network clients: Tailnet MagicDNS, Tailnet IP, SSH tunnel, or
227245 wide-area DNS-SD
228246229-4. If you deliberately enabled Bonjour in Docker with
230-`OPENCLAW_DISABLE_BONJOUR=0`, test multicast from the host:
247+4. If you deliberately enabled the Bonjour plugin in Docker and forced advertising
248+with `OPENCLAW_DISABLE_BONJOUR=0`, test multicast from the host:
231249232250```bash
233251 dns-sd -B _openclaw-gw._tcp local.
@@ -261,13 +279,14 @@ sequences (e.g. spaces become `\032`).
261279- This is normal at the protocol level.
262280- UIs should decode for display (iOS uses `BonjourEscapes.decode`).
263281264-## Disabling / configuration
282+## Enabling / disabling / configuration
265283284+- macOS hosts auto-start the bundled LAN discovery plugin by default.
285+- `openclaw plugins enable bonjour` enables the bundled LAN discovery plugin on hosts where it is not default-enabled.
266286- `openclaw plugins disable bonjour` disables LAN multicast advertising by disabling the bundled plugin.
267-- `openclaw plugins enable bonjour` restores the default LAN discovery plugin.
268287- `OPENCLAW_DISABLE_BONJOUR=1` disables LAN multicast advertising without changing plugin config; accepted truthy values are `1`, `true`, `yes`, and `on` (legacy: `OPENCLAW_DISABLE_BONJOUR`).
269288- `OPENCLAW_DISABLE_BONJOUR=0` forces LAN multicast advertising on, including inside detected containers; accepted falsy values are `0`, `false`, `no`, and `off`.
270-- When `OPENCLAW_DISABLE_BONJOUR` is unset, Bonjour advertises on normal hosts and auto-disables inside detected containers.
289+- When the Bonjour plugin is enabled and `OPENCLAW_DISABLE_BONJOUR` is unset, Bonjour advertises on normal hosts and auto-disables inside detected containers.
271290- `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode.
272291- `OPENCLAW_SSH_PORT` overrides the SSH port when `sshPort` is advertised (legacy: `OPENCLAW_SSH_PORT`).
273292- `OPENCLAW_TAILNET_DNS` publishes a MagicDNS hint in TXT when mDNS full mode is enabled (legacy: `OPENCLAW_TAILNET_DNS`).
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。