openclaw - 💡(How to fix) Fix Gateway crashes ~39ms after 'ready' on os.networkInterfaces() in restricted sandboxes (mDNS sidecar @homebridge/ciao) [1 comments, 1 participants]

In plain English: when the gateway boots inside a sandbox that restricts os.networkInterfaces() (such as a NemoClaw / OpenShell pod), it crashes ~39ms after announcing "ready" because its mDNS sidecar (the @homebridge/ciao channel-discovery component) calls that syscall and gets a SystemError. The unhandled promise rejection kills the gateway. There's no recovery path baked in. The workaround is to set discovery.mdns.mode=off in openclaw.json — but most users won't know that setting exists or that mDNS is the cause until they read source.

Problem

The gateway starts cleanly inside a restricted sandbox, logs ready (6 plugins, 2.0s) with HTTP server listening on :18789, then ~39ms later crashes with:

[openclaw] Unhandled promise rejection: SystemError: A system error occurred:
  uv_interface_addresses returned Unknown system error 1
    at Object.networkInterfaces (node:os:218:16)
    at Function.assumeNetworkInterfaceNames (/usr/local/lib/node_modules/openclaw/node_modules/@homebridge/ciao/src/NetworkManager.ts:527:23)
    at NetworkManager.getCurrentNetworkInterfaces (...)

Source: @homebridge/ciao (mDNS sidecar used for channel discovery via Bonjour) calls Node's os.networkInterfaces(). The sandbox restricts that syscall — uv_interface_addresses returns Unknown system error 1. Promise rejection bubbles up; gateway exits.

Reproducer

Tested-against: OpenClaw v2026.4.9 inside a NemoClaw v0.0.26 sandbox (k3s pod with restricted syscalls).

openshell sandbox exec -n <sandbox> -- /usr/local/bin/openclaw gateway
# Gateway starts, logs "ready", then dies ~39ms later with the trace above.

Repro outside NemoClaw: any container that filters getrandom()/uv_interface_addresses syscalls (some hardened seccomp profiles, restricted Kubernetes pod security contexts) hits the same crash.

Workarounds

Runtime workaround (used in our test):

"discovery": { "mdns": { "mode": "off" } }

in openclaw.json. Default is "minimal", options are off|minimal|full. Found via grep cfg.discovery?.mdns?.mode in dist/audit-D8YFKksP.js — the option is real and works, but it's not documented anywhere visible.

Failed workaround: NODE_OPTIONS="--unhandled-rejections=warn" does NOT prevent the crash. The SystemError-class rejection mode flag may not catch this specific rejection type, or the gateway's signal handlers run before the --unhandled-rejections policy applies.

Proposed fix

Two complementary improvements:

1. Defensive try/catch around the ciao initialization.

networkInterfaces() can legitimately fail on restricted hosts (Landlock, seccomp, gVisor, Kata, Firecracker, etc.). The current code treats the failure as fatal; it should treat it as "no mDNS available, run without channel discovery."

// In gateway startup, where ciao is initialized:
try {
  await initChannelDiscovery();
} catch (err) {
  log.warn(`[gateway] mDNS / channel discovery unavailable in this environment, continuing without: ${err}`);
}

2. Detect "we're in a restricted sandbox" at startup and skip ciao entirely.

Heuristics that work:

• Presence of /sandbox/.openclaw-data (NemoClaw signal).
• os.networkInterfaces() returns empty / throws on probe.
• An explicit OPENCLAW_DISABLE_MDNS=1 env var or discovery.mdns.mode=off config.

Pick one (config-based is most explicit) or all three (defense in depth).

3. Document discovery.mdns.mode in the user-facing config schema.

It's a real, working option — just not visible.

Alternatives considered

• Patch upstream @homebridge/ciao to handle EAI errors gracefully. Out of scope for this repo and may take time to land. The defensive try/catch is the right shape regardless.
• Replace ciao with a different mDNS library that handles restricted hosts. Too invasive for a scenario where mDNS isn't critical (channel discovery has fallbacks via explicit config).

Test plan

• Unit: assert initChannelDiscovery() failure is caught and logged as WARN, gateway continues startup.
• Integration: start gateway in a Linux container with seccomp filter blocking socket() for AF_NETLINK (effectively breaks networkInterfaces()); confirm gateway stays up.
• Regression: gateway with mDNS available continues to work as before.

Risk / blast radius

• Loses mDNS-based channel discovery in restricted environments. Acceptable because (a) mDNS doesn't work in those environments anyway, (b) explicit channel config via openclaw.json already works there.
• No code-path change in non-restricted environments. Try/catch is around the init; if init succeeds (the common case), nothing changes.

Open questions

1. Is discovery.mdns.mode=off the canonical way to disable mDNS, or is there a different / preferred mechanism the maintainers would prefer to expose?
2. Should the gateway also skip mDNS automatically when running under known sandbox runtimes (NemoClaw/OpenShell, gVisor, Firecracker, etc.), or stick with explicit config?
3. Is there appetite for a --no-mdns CLI flag mirroring the config option?

This is one of a small batch of gateway-lifecycle / plugin-install findings from a recent end-to-end test of the deep-observability plugin under NemoClaw. Sibling issues being filed for openclaw plugins install <path> rejecting valid paths, plugin async register() silently truncated, openclaw gateway stop no-op, and double plugin-load timing.