PR #71881: fix(docker): default OPENCLAW_DISABLE_BONJOUR for bridge installs

• Repository: openclaw/openclaw
• Author: gbballpack
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/71881

Description (problem / solution / changelog)

Summary

• Problem: Docker's default bridge network generally does not forward mDNS multicast (224.0.0.251:5353), but the bundled Compose setup still starts the Bonjour gateway discovery plugin by default.
• Why it matters: in a 2026.4.24 Docker deploy, the gateway reached ready and then crash-looped with @homebridge/ciao cancellation rejections during Bonjour probing/announcement.
• What changed: default Docker Compose/setup to OPENCLAW_DISABLE_BONJOUR=1, persist that default into .env, print the resulting setting during setup, and document how/when to opt back in.
• What did NOT change (scope boundary): non-Docker installs keep their existing Bonjour behavior; Docker users can still opt in with OPENCLAW_DISABLE_BONJOUR=0 when using host/macvlan networking or another mDNS-capable network.

Files changed

• docker-compose.yml — sets OPENCLAW_DISABLE_BONJOUR: ${OPENCLAW_DISABLE_BONJOUR:-1} for the gateway service.
• scripts/docker/setup.sh — persists the Docker default into .env and prints whether Bonjour/mDNS advertising is enabled or disabled.
• docs/install/docker.md — documents Docker bridge networking as unsuitable for Bonjour/mDNS and describes the host/macvlan opt-in path.
• docs/gateway/bonjour.md — adds Docker bridge networking to common Bonjour failure modes.
• docs/gateway/discovery.md — cross-links the Docker discovery guidance.
• CHANGELOG.md — adds the Docker/Bonjour fix entry.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #71879
• Related #30183
• Related #28174
• Related #65838
• Related #67578
• Related #48523
• This PR fixes a bug or regression

Root Cause (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: Docker bridge networking is a poor default environment for Bonjour/mDNS. The default bridge usually drops the IPv4 multicast traffic (224.0.0.251:5353) that @homebridge/ciao needs for DNS-SD probing and announcing, while the Docker Compose gateway still enabled Bonjour by default.
• Missing detection / guardrail: Docker setup did not default the optional local-discovery plugin off or clearly document that bridge networking is not a reliable mDNS transport.
• Contributing context (if known): a 2026.4.24 Docker deploy installed @homebridge/ciao 1.3.6 in the staged runtime deps, reached ready, then produced repeated stability snapshots for unhandled rejections containing CIAO PROBING CANCELLED / CIAO ANNOUNCEMENT CANCELLED during the failed startup window. Version verification: the staged runtime deps package.json reports 1.3.6, and public npm lists @homebridge/ciao 1.3.6.
• Regression window: unclear. This may be a latent Docker/Bonjour bridge-networking issue that surfaced during the 2026.4.24 container rebuild/restart, or it may have been amplified by 2026.4.24 Bonjour/plugin-runtime changes.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/server-discovery-runtime.test.ts already covers truthy OPENCLAW_DISABLE_BONJOUR values; this PR changes Docker defaults/docs rather than discovery runtime semantics.
• Scenario the test should lock in: with OPENCLAW_DISABLE_BONJOUR=1, local discovery services are skipped.
• Why this is the smallest reliable guardrail: the issue is Docker default configuration, not the env-var implementation.
• Existing test that already covers this (if any): skips local discovery services for truthy OPENCLAW_DISABLE_BONJOUR values.
• If no new test is added, why not: the patch is limited to Compose defaults, setup-script env persistence/output, docs, and changelog. I verified the shell script parses and the compose/default env wiring is present.
• Ideal CI coverage to add later: a Docker Compose bridge-network smoke test that starts the gateway with OPENCLAW_DISABLE_BONJOUR=1, waits for /readyz, and asserts the gateway remains up for at least 60 seconds. A manual positive-control retry on the affected deployment now shows 2026.4.24 healthy with Bonjour disabled.

User-visible / Behavior Changes

List user-visible changes (including defaults/config).
If none, write None.

Docker Compose installs now disable Bonjour/mDNS gateway advertising by default. Docker users who intentionally run an mDNS-capable network can set:

OPENCLAW_DISABLE_BONJOUR=0

For normal bridge-networked Docker installs, users should rely on the published gateway URL, configured public/tailnet URL, Tailscale, or Wide-Area DNS-SD instead of LAN multicast discovery.

Diagram (if applicable)

For UI changes or non-trivial logic flows, include a small ASCII diagram reviewers can scan quickly. Otherwise write N/A.

Before:
Docker bridge gateway
  -> Bonjour advertiser enabled
  -> mDNS multicast dropped
  -> ciao probing/announcement cancellation
  -> unhandled rejection
  -> Node exits / Docker restarts gateway
  -> repeat

After:
Docker bridge gateway
  -> OPENCLAW_DISABLE_BONJOUR=1
  -> Bonjour advertiser skipped
  -> gateway uses published URL/tailnet/manual discovery
  -> no mDNS watchdog/cancellation loop

Security Impact (required)

• New permissions/capabilities? (Yes/No): No
• Secrets/tokens handling changed? (Yes/No): No
• New/changed network calls? (Yes/No): No new calls; Docker default removes mDNS advertising calls.
• Command/tool execution surface changed? (Yes/No): No
• Data access scope changed? (Yes/No): No
• If any Yes, explain risk + mitigation: N/A

This also reduces local-network metadata exposure for Docker installs because the gateway no longer emits Bonjour TXT records by default, but that is an incidental benefit rather than the main security claim.

Repro + Verification

Environment

• OS: Ubuntu 24.04 Docker host (observed deploy)
• Runtime/container: OpenClaw Docker Compose gateway
• Model/provider: N/A
• Integration/channel (if any): Gateway startup + bundled Bonjour discovery plugin
• Relevant config (redacted): Docker Compose with default bridge networking; device-pair.publicUrl configured; Bonjour/mDNS not required for the deployment.

Steps

1. Run/upgrade an OpenClaw Docker Compose gateway to 2026.4.24 on Docker's default bridge network.
2. Let the gateway start with the bundled Bonjour discovery plugin enabled.
3. Observe the gateway reach ready, then crash-loop/restart during Bonjour probing/announcement.

Expected

Optional LAN discovery failures should degrade locally. Docker bridge networking should not be able to crash-loop the gateway, especially when other configured access paths are available.

Actual

Observed 2026.4.24 gateway reached ready and then crash-looped. Logs/stability snapshots showed repeated unhandled rejection events around the failed startup window with CIAO PROBING CANCELLED / CIAO ANNOUNCEMENT CANCELLED from the Bonjour/ciao path.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Evidence from the affected deployment:

• Last known safe state after rollback: OpenClaw 2026.4.23.
• First observed bad deploy: OpenClaw 2026.4.24.
• Failed runtime deps path: /home/node/.openclaw/plugin-runtime-deps/openclaw-2026.4.24-f53b52ad6d21.
• @homebridge/ciao version observed in staged deps: 1.3.6.
• Failure window: approximately 16:01-16:05 CDT on 2026-04-25, with four unhandled_rejection stability snapshots.
• Error signatures: CIAO PROBING CANCELLED and CIAO ANNOUNCEMENT CANCELLED.
• Operational workaround verified: set OPENCLAW_DISABLE_BONJOUR=1 or disable the bonjour plugin.

Local verification for this PR:

git diff --check
bash -n scripts/docker/setup.sh
python3 - <<'PY'
from pathlib import Path
compose = Path('docker-compose.yml').read_text()
setup = Path('scripts/docker/setup.sh').read_text()
assert 'OPENCLAW_DISABLE_BONJOUR: ${OPENCLAW_DISABLE_BONJOUR:-1}' in compose
assert 'export OPENCLAW_DISABLE_BONJOUR="${OPENCLAW_DISABLE_BONJOUR:-1}"' in setup
assert 'OPENCLAW_DISABLE_BONJOUR \\' in setup
assert 'Bonjour/mDNS advertising: disabled for Docker bridge networking' in setup
print('verification ok')
PY

Positive control now observed on the affected Docker deployment: after adding OPENCLAW_DISABLE_BONJOUR=1 and restarting on 2026.4.24, the gateway stayed up and healthy. Live checks showed /app/package.json version 2026.4.24, /healthz returned {"ok":true,"status":"live"}, /readyz returned {"ready":true,"failing":[]}, and the running gateway process environment included OPENCLAW_DISABLE_BONJOUR=1.

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • Docker Compose now renders/presents OPENCLAW_DISABLE_BONJOUR: ${OPENCLAW_DISABLE_BONJOUR:-1} by default.
  • scripts/docker/setup.sh persists OPENCLAW_DISABLE_BONJOUR into .env and prints whether Bonjour is enabled/disabled.
  • Docs now state Docker bridge networking is not a reliable mDNS transport and describe host/macvlan opt-in.
  • The observed staged runtime deps path reports @homebridge/ciao 1.3.6, and public npm lists that version.
• Edge cases checked:
  • OPENCLAW_DISABLE_BONJOUR=0 remains an explicit opt-in override.
  • Existing runtime test coverage already covers truthy disable values.
• What you did not verify:
  • I did not rerun the full Docker upgrade path or intentionally reproduce the crash-loop because that requires a slow/interruptive deploy cycle.
  • I did not run an automated CI-style 60s Compose smoke test, but I did verify the affected Docker deployment is healthy on 2026.4.24 with OPENCLAW_DISABLE_BONJOUR=1.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No): Yes, with a Docker-default behavior change.
• Config/env changes? (Yes/No): Yes. Docker setup now writes OPENCLAW_DISABLE_BONJOUR=1 by default.
• Migration needed? (Yes/No): No.
• If yes, exact upgrade steps: Docker users who need LAN Bonjour discovery should set OPENCLAW_DISABLE_BONJOUR=0 and use host/macvlan or another network mode that passes mDNS multicast.

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: A Docker user relying on LAN Bonjour discovery loses automatic discovery after updating.
  • Mitigation: Docker bridge does not reliably support that path anyway; docs include OPENCLAW_DISABLE_BONJOUR=0 opt-in guidance for host/macvlan/mDNS-capable networking.
• Risk: Users confuse gateway.bind=lan with mDNS availability.
  • Mitigation: Docker docs now separate published gateway access from Bonjour/mDNS transport.

Changed files

• CHANGELOG.md (modified, +3/-0)
• docker-compose.yml (modified, +5/-0)
• docs/gateway/bonjour.md (modified, +6/-1)
• docs/gateway/discovery.md (modified, +6/-0)
• docs/install/docker.md (modified, +18/-0)
• scripts/docker/setup.sh (modified, +7/-0)