diff --git a/docs/gateway/bonjour.md b/docs/gateway/bonjour.md
index 0a3582f27be..98a367269ed 100644
--- a/docs/gateway/bonjour.md
+++ b/docs/gateway/bonjour.md
@@ -152,6 +152,85 @@ To capture logs:
 
 The log includes browser state transitions and result‑set changes.
 
+## When to disable Bonjour
+
+Disable Bonjour only when LAN multicast advertising is unavailable or harmful.
+The common case is a Gateway running behind Docker bridge networking, WSL, or a
+network policy that drops mDNS multicast. In those environments the Gateway is
+still reachable through its published URL, SSH, Tailnet, or wide-area DNS-SD,
+but LAN auto-discovery is not reliable.
+
+Prefer the existing environment override when the problem is deployment-scoped:
+
+```bash
+OPENCLAW_DISABLE_BONJOUR=1
+```
+
+That disables LAN multicast advertising without changing plugin configuration.
+It is safe for Docker images, service files, launch scripts, and one-off
+debugging because the setting disappears when the environment does.
+
+Use plugin configuration only when you intentionally want to turn off the
+bundled LAN discovery plugin for that OpenClaw config:
+
+```bash
+openclaw plugins disable bonjour
+```
+
+## Docker gotchas
+
+Bundled Docker Compose sets `OPENCLAW_DISABLE_BONJOUR=1` for the Gateway service
+by default. Docker bridge networks usually do not forward mDNS multicast
+(`224.0.0.251:5353`) between the container and the LAN, so leaving Bonjour on can
+produce repeated ciao `probing` or `announcing` failures without making discovery
+work.
+
+Important gotchas:
+
+- Disabling Bonjour does not stop the Gateway. It only stops LAN multicast
+  advertising.
+- Disabling Bonjour does not change `gateway.bind`; Docker still defaults to
+  `OPENCLAW_GATEWAY_BIND=lan` so the published host port can work.
+- Disabling Bonjour does not disable wide-area DNS-SD. Use wide-area discovery
+  or Tailnet when the Gateway and node are not on the same LAN.
+- Reusing the same `OPENCLAW_CONFIG_DIR` outside Docker does not inherit the
+  Compose default unless the environment still sets `OPENCLAW_DISABLE_BONJOUR`.
+- Set `OPENCLAW_DISABLE_BONJOUR=0` only for host networking, macvlan, or another
+  network where mDNS multicast is known to pass.
+
+## Troubleshooting disabled Bonjour
+
+If a node no longer auto-discovers the Gateway after Docker setup:
+
+1. Confirm whether the Gateway is intentionally suppressing LAN advertising:
+
+   ```bash
+   docker compose config | grep OPENCLAW_DISABLE_BONJOUR
+   ```
+
+2. Confirm the Gateway itself is reachable through the published port:
+
+   ```bash
+   curl -fsS http://127.0.0.1:18789/healthz
+   ```
+
+3. Use a direct target when Bonjour is disabled:
+   - Control UI or local tools: `http://127.0.0.1:18789`
+   - LAN clients: `http://<gateway-host>:18789`
+   - Cross-network clients: Tailnet MagicDNS, Tailnet IP, SSH tunnel, or
+     wide-area DNS-SD
+
+4. If you deliberately enabled Bonjour in Docker with
+   `OPENCLAW_DISABLE_BONJOUR=0`, test multicast from the host:
+
+   ```bash
+   dns-sd -B _openclaw-gw._tcp local.
+   ```
+
+   If browsing is empty or the Gateway logs show repeated ciao watchdog
+   cancellations, restore `OPENCLAW_DISABLE_BONJOUR=1` and use a direct or
+   Tailnet route.
+
 ## Common failure modes
 
 - **Bonjour doesn’t cross networks**: use Tailnet or SSH.
diff --git a/docs/install/docker.md b/docs/install/docker.md
index 741d8a05bcd..e025cf2a4df 100644
--- a/docs/install/docker.md
+++ b/docs/install/docker.md
@@ -177,6 +177,8 @@ Use the published Gateway URL, Tailscale, or wide-area DNS-SD for Docker hosts.
 Set `OPENCLAW_DISABLE_BONJOUR=0` only when running with host networking, macvlan,
 or another network where mDNS multicast is known to work.
 
+For gotchas and troubleshooting, see [Bonjour discovery](/gateway/bonjour).
+
 ### Storage and persistence
 
 Docker Compose bind-mounts `OPENCLAW_CONFIG_DIR` to `/home/node/.openclaw` and