How to Use OpenClaw Gateway Discovery

OpenClaw gateway discovery helps clients and nodes find the gateway without hardcoding every address. The docs separate two problems: operator remote control, where a macOS menu bar app controls a gateway elsewhere, and node pairing, where iOS, Android, or future nodes find and pair with a gateway securely. Discovery is intentionally owned by the node gateway process so clients can consume hints without each app inventing its own network behavior.

Use direct WebSocket when the route is private

The gateway control plane is the WebSocket endpoint on 127.0.0.1:18789 by default. It can be bound to LAN or tailnet addresses through gateway config. Direct WebSocket is the best UX on the same network or inside a tailnet because it avoids shell access and lets the gateway own pairing tokens and ACLs. SSH remains the universal fallback when multicast, routing, or direct network access is unavailable.

Understand Bonjour hints

Bonjour/DNS-SD discovery advertises the _openclaw-gw._tcp service type. TXT keys can include role, transport, display name, local host, gateway port, TLS flag, TLS fingerprint, canvas port, tailnet DNS hint, SSH port, and CLI path. These values are not secrets. The docs say clients should prefer the resolved service endpoint over TXT-provided host and port hints, and TLS pinning must never allow an advertised fingerprint to override a previously stored pin.

Use Tailscale for cross-network setups

Bonjour does not cross normal network boundaries. For remote setups, the recommended direct target is a Tailscale MagicDNS name or stable tailnet IP. If the gateway detects Tailscale, it can publish a tailnetDns hint. The macOS app prefers MagicDNS names over raw tailnet IPs because names survive IP changes better. For mobile pairing, discovery hints do not weaken transport security: tailnet or public routes still need a secure first-time path such as WSS or Tailscale Serve/Funnel.

Know the toggles

OPENCLAW_DISABLE_BONJOUR=1 disables advertising. When it is unset, Bonjour advertises on normal hosts and auto-disables inside detected containers. gateway.bind controls the gateway bind mode. OPENCLAW_SSH_PORT, OPENCLAW_TAILNET_DNS, and OPENCLAW_CLI_PATH can influence advertised hints. Use these deliberately, especially on hosts with multiple gateways or containers, where a misleading discovery record can waste time.

Operator checklist

Decide the primary route, test local discovery, test tailnet reachability, and verify SSH fallback. For mobile nodes, confirm the secure first-time pairing path and any fingerprint prompts. The OpenClaw Playbook encourages writing a simple network map: gateway host, bind mode, discovery on/off, tailnet name, SSH fallback, and pairing rules. Discovery should make connection easier; it should never become a shortcut around gateway trust.

Do not confuse discovery with authorization

Discovery helps a client find a gateway. It does not decide whether that client should be trusted. Pairing, auth, TLS, and stored pins still decide trust. That distinction is why the docs treat Bonjour TXT records as hints and warn against letting advertised values override stored security decisions. In a home or lab network, discovery can feel magical; in a company network, it should still be treated as an untrusted announcement until the secure connection and pairing process complete. If you keep that boundary clear, discovery improves UX without weakening the gateway.

Final verification

Before calling How to Use OpenClaw Gateway Discovery finished, perform one direct test, one failure test, and one rollback check. The direct test proves the happy path works. The failure test proves the documented guardrail is real, not just assumed. The rollback check tells the next operator how to undo the change without improvising. Save those notes beside the channel, node, or gateway config you changed. OpenClaw gets powerful when agents can act, but it stays trustworthy when every new surface has a small, repeatable verification habit attached to it.