vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 21:00:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: document automatic bonjour container policy

Browse Source
This commit is contained in:
Peter Steinberger
2026-04-26 23:59:48 +01:00
parent 6018f29dbf
commit 20d6daaeaa
2 changed files with 16 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
docs/gateway/bonjour.md
View File

@@ -179,11 +179,10 @@ openclaw plugins disable bonjour
## Docker gotchas ## Docker gotchas
Bundled Docker Compose sets `OPENCLAW_DISABLE_BONJOUR=1` for the Gateway service The bundled Bonjour plugin auto-disables LAN multicast advertising in detected
by default. Docker bridge networks usually do not forward mDNS multicast containers when `OPENCLAW_DISABLE_BONJOUR` is unset. Docker bridge networks
(`224.0.0.251:5353`) between the container and the LAN, so leaving Bonjour on can usually do not forward mDNS multicast (`224.0.0.251:5353`) between the container
produce repeated ciao `probing` or `announcing` failures without making discovery and the LAN, so advertising from the container rarely makes discovery work.
work.
Important gotchas: Important gotchas:
@@ -193,16 +192,16 @@ Important gotchas:
`OPENCLAW_GATEWAY_BIND=lan` so the published host port can work. `OPENCLAW_GATEWAY_BIND=lan` so the published host port can work.
- Disabling Bonjour does not disable wide-area DNS-SD. Use wide-area discovery - 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. 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 - Reusing the same `OPENCLAW_CONFIG_DIR` outside Docker does not persist the
Compose default unless the environment still sets `OPENCLAW_DISABLE_BONJOUR`. container auto-disable policy.
- Set `OPENCLAW_DISABLE_BONJOUR=0` only for host networking, macvlan, or another - Set `OPENCLAW_DISABLE_BONJOUR=0` only for host networking, macvlan, or another
network where mDNS multicast is known to pass. network where mDNS multicast is known to pass; set it to `1` to force-disable.
## Troubleshooting disabled Bonjour ## Troubleshooting disabled Bonjour
If a node no longer auto-discovers the Gateway after Docker setup: If a node no longer auto-discovers the Gateway after Docker setup:
1. Confirm whether the Gateway is intentionally suppressing LAN advertising: 1. Confirm whether the Gateway is running in auto, forced-on, or forced-off mode:
```bash ```bash
docker compose config | grep OPENCLAW_DISABLE_BONJOUR docker compose config | grep OPENCLAW_DISABLE_BONJOUR
@@ -239,9 +238,9 @@ If a node no longer auto-discovers the Gateway after Docker setup:
container bridges, WSL, or interface churn can leave the ciao advertiser in a container bridges, WSL, or interface churn can leave the ciao advertiser in a
non-announced state. OpenClaw retries a few times and then disables Bonjour non-announced state. OpenClaw retries a few times and then disables Bonjour
for the current Gateway process instead of restarting the advertiser forever. for the current Gateway process instead of restarting the advertiser forever.
- **Docker bridge networking**: bundled Docker Compose disables Bonjour by - **Docker bridge networking**: Bonjour auto-disables in detected containers.
default with `OPENCLAW_DISABLE_BONJOUR=1`. Set it to `0` only for host, Set `OPENCLAW_DISABLE_BONJOUR=0` only for host, macvlan, or another
macvlan, or another mDNS-capable network. mDNS-capable network.
- **Sleep / interface churn**: macOS may temporarily drop mDNS results; retry. - **Sleep / interface churn**: macOS may temporarily drop mDNS results; retry.
- **Browse works but resolve fails**: keep machine names simple (avoid emojis or - **Browse works but resolve fails**: keep machine names simple (avoid emojis or
punctuation), then restart the Gateway. The service instance name derives from punctuation), then restart the Gateway. The service instance name derives from
@@ -260,7 +259,8 @@ sequences (e.g. spaces become `\032`).
- `openclaw plugins disable bonjour` disables LAN multicast advertising by disabling the bundled plugin. - `openclaw plugins disable bonjour` disables LAN multicast advertising by disabling the bundled plugin.
- `openclaw plugins enable bonjour` restores the default LAN discovery plugin. - `openclaw plugins enable bonjour` restores the default LAN discovery plugin.
- `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`). - `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`).
- Docker Compose sets `OPENCLAW_DISABLE_BONJOUR=1` by default for bridge networking; override with `OPENCLAW_DISABLE_BONJOUR=0` only when mDNS multicast is available. - `OPENCLAW_DISABLE_BONJOUR=0` forces LAN multicast advertising on, including inside detected containers; accepted falsy values are `0`, `false`, `no`, and `off`.
- When `OPENCLAW_DISABLE_BONJOUR` is unset, Bonjour advertises on normal hosts and auto-disables inside detected containers.
- `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode. - `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode.
- `OPENCLAW_SSH_PORT` overrides the SSH port when `sshPort` is advertised (legacy: `OPENCLAW_SSH_PORT`). - `OPENCLAW_SSH_PORT` overrides the SSH port when `sshPort` is advertised (legacy: `OPENCLAW_SSH_PORT`).
- `OPENCLAW_TAILNET_DNS` publishes a MagicDNS hint in TXT when mDNS full mode is enabled (legacy: `OPENCLAW_TAILNET_DNS`). - `OPENCLAW_TAILNET_DNS` publishes a MagicDNS hint in TXT when mDNS full mode is enabled (legacy: `OPENCLAW_TAILNET_DNS`).

6
docs/gateway/discovery.md
View File

@@ -86,9 +86,9 @@ Security notes:
Disable/override: Disable/override:
- `OPENCLAW_DISABLE_BONJOUR=1` disables advertising. - `OPENCLAW_DISABLE_BONJOUR=1` disables advertising.
- Docker Compose defaults `OPENCLAW_DISABLE_BONJOUR=1` because bridge networks - When `OPENCLAW_DISABLE_BONJOUR` is unset, Bonjour advertises on normal hosts
usually do not carry mDNS multicast reliably; use `0` only on host, macvlan, and auto-disables inside detected containers. Use `0` only on host, macvlan,
or another mDNS-capable network. or another mDNS-capable network; use `1` to force-disable.
- `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode. - `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode.
- `OPENCLAW_SSH_PORT` overrides the SSH port advertised when `sshPort` is emitted. - `OPENCLAW_SSH_PORT` overrides the SSH port advertised when `sshPort` is emitted.
- `OPENCLAW_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS). - `OPENCLAW_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS).