Summary

• Problem: On Android/Termux (and other platforms without multicast networking), the Gateway's Bonjour/mDNS advertiser cannot broadcast. The watchdog fires every ~60 s emitting noisy log spam, and a Wi-Fi disconnect can trigger an assertion that crashes the process.
• Why it matters: Users running OpenClaw on Android/Termux have no config-based way to suppress mDNS — the only escape hatch is the undiscoverable OPENCLAW_DISABLE_BONJOUR=1 env var, and the crash risk makes the Gateway unusable on those platforms.
• What changed: Added gateway.mdns.enabled (boolean, default true) as a first-class config key with full schema validation, Zod schema, help text, UI labels, and docs. Setting it to false forces mdnsMode: "off" in the discovery runtime, preventing both the advertiser and watchdog from starting.
• What did NOT change (scope boundary): The existing discovery.mdns.mode enum ("off"/"minimal"/"full") is untouched. No changes to the Bonjour advertiser itself, watchdog logic, or any channel/auth/tool code. OPENCLAW_DISABLE_BONJOUR=1 retains its highest-priority override semantics.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• 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 Feature Request: Option to disable mDNS/Bonjour (critical for Android/Termux) #28174

User-visible / Behavior Changes

• New optional config key gateway.mdns.enabled (boolean). Omitting it keeps current behavior (mDNS on).
• Setting gateway.mdns.enabled: false disables the Bonjour advertiser and its 60-second watchdog timer entirely — no more log spam on platforms without multicast.
• docs/gateway/bonjour.md "Disabling / configuration" section now documents the new config key with a JSON5 example and clarifies priority order: OPENCLAW_DISABLE_BONJOUR=1 > gateway.mdns.enabled: false > discovery.mdns.mode: "off".

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: Android (Termux) / any platform without multicast support
• Runtime/container: Node 22 / Bun
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted):

  { gateway: { mdns: { enabled: false } } }

Steps

1. Add gateway: { mdns: { enabled: false } } to ~/.openclaw/openclaw.json.
2. Start the Gateway: openclaw gateway run.
3. Wait 60+ seconds and observe logs.

Expected

• No bonjour: log lines appear (advertiser never starts, watchdog never fires).
• Gateway starts and operates normally for all channel and API functions.

Actual (before this fix)

• No config key exists; schema rejects any attempt to add gateway.mdns.* with an unknown-key error. Only the env var path works, and it is not surfaced in the UI or config docs.

Evidence

• Failing test/log before + passing after

4 new schema validation tests in src/config/config.gateway-mdns.test.ts — all pass:

✓ accepts gateway.mdns.enabled: false
✓ accepts gateway.mdns.enabled: true
✓ accepts gateway.mdns as empty object
✓ rejects unknown keys inside gateway.mdns

schema.help.quality.test.ts (20 tests) and all other touched test files continue to pass. pnpm check (lint + format + typecheck) passes clean.

Human Verification (required)

• Verified scenarios: Schema accepts { gateway: { mdns: { enabled: false } } } and rejects { gateway: { mdns: { unknown: true } } }. pnpm check passes. All touched test files pass.
• Edge cases checked: gateway.mdns omitted entirely (no regression); gateway.mdns.enabled: true (no-op, identical to default); discovery.mdns.mode: "off" still works independently of the new key.
• What you did not verify: Live runtime on a real Android/Termux device; interaction with the macOS menubar app restart flow.

Compatibility / Migration

• Backward compatible? Yes — enabled defaults to true; omitting the key is identical to current behavior.
• Config/env changes? Yes — new optional key gateway.mdns.enabled.
• Migration needed? No

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: Remove gateway.mdns from ~/.openclaw/openclaw.json, or set OPENCLAW_DISABLE_BONJOUR=1 to suppress mDNS via the pre-existing env path.
• Files/config to restore: src/config/types.gateway.ts, src/config/zod-schema.ts, src/gateway/server.impl.ts (one-line change each).
• Known bad symptoms reviewers should watch for: Gateway refusing to start with a schema validation error on gateway.mdns (Zod .strict() object not updated); Bonjour watchdog still firing when enabled: false (override in server.impl.ts not reached).

Risks and Mitigations

• Risk: Two overlapping ways to disable mDNS (gateway.mdns.enabled vs discovery.mdns.mode) may confuse users.
  • Mitigation: gateway.mdns.enabled is the simple boolean convenience path for the Android/Termux use case; discovery.mdns.mode handles finer-grained control. Priority order is documented in bonjour.md.
• Risk: gateway.mdns.enabled: false silently overrides discovery.mdns.mode when both are set.
  • Mitigation: The override only activates when enabled === false; all other combinations respect discovery.mdns.mode unchanged. Documented explicitly.