Discovery and Transports

OpenClaw tackles two related but separate discovery challenges:

Operator remote control: the macOS menu bar app connecting to a gateway that runs on a different machine.
Node pairing: iOS/Android (and future nodes) locating a gateway and establishing a secure pairing.

All network discovery and advertising logic resides in the Node Gateway (openclaw gateway); clients (mac app, iOS) act purely as consumers.

Terms

Gateway: a single long-lived process responsible for state (sessions, pairing, node registry) and channel execution. Typically one runs per host; isolated multi-gateway configurations are feasible.
Gateway WS (control plane): the WebSocket endpoint that listens on 127.0.0.1:18789 by default; you can bind it to LAN/tailnet using gateway.bind.
Direct WS transport: a Gateway WS endpoint exposed to LAN/tailnet (no SSH involved).
SSH transport (fallback): remote control achieved by tunneling 127.0.0.1:18789 over SSH.
Legacy TCP bridge (removed): the previous node transport (see Bridge protocol); it is no longer advertised for discovery and has been dropped from current builds.

For protocol specifics: Gateway protocol, Bridge protocol (legacy).

Why direct and SSH both exist

Direct WS delivers the smoothest experience on a shared network or tailnet: LAN auto-discovery through Bonjour, pairing tokens and ACLs managed by the gateway, and no shell access needed.
SSH serves as the universal fallback: it functions anywhere SSH is reachable, even across separate networks, tolerates multicast/mDNS failures, and requires no additional inbound port beyond SSH itself.

Discovery inputs

1) Bonjour / DNS-SD

Multicast Bonjour operates on a best-effort basis and never crosses network boundaries. OpenClaw also lets you browse the same gateway beacon through a configured wide-area DNS-SD domain, so discovery can span both local. on the local LAN and a configured unicast DNS-SD domain for cross-network scenarios.

The gateway broadcasts its WS endpoint via Bonjour when the bundled bonjour plugin is active; clients browse and present a "pick a gateway" list, then persist the selected endpoint.

For troubleshooting and beacon specifics: Bonjour.

Service beacon details

Service type: _openclaw-gw._tcp (gateway transport beacon).

TXT keys (non-secret):

Key	Notes
`role=gateway`	Always present.
`transport=gateway`	Always present.
`displayName=<name>`	Operator-set display name.
`lanHost=<hostname>.local`	LAN mDNS advertiser only; not written by wide-area DNS-SD.
`gatewayPort=18789`	Gateway WS + HTTP port.
`gatewayTls=1`	Only when TLS is enabled.
`gatewayTlsSha256=<sha256>`	Only when TLS is enabled and a fingerprint is available.
`tailnetDns=<magicdns>`	Optional hint; auto-detected when Tailscale is present.
`sshPort=<port>`	Present only when `discovery.mdns.mode="full"`; omitted (SSH defaults to `22`) in the default `"minimal"` mode, on both the LAN advertiser and wide-area DNS-SD.
`cliPath=<path>`	Same `discovery.mdns.mode="full"` gate as `sshPort`; a remote-install hint for the CLI path.

Security notes:

Bonjour/mDNS TXT records carry no authentication. Clients should treat TXT values as UX hints only.
Routing (host/port) should favor the resolved service endpoint (SRV + A/AAAA) over TXT-provided lanHost, tailnetDns, or gatewayPort.
TLS pinning must never let an advertised gatewayTlsSha256 override a previously stored pin.
iOS/Android nodes should demand an explicit "trust this fingerprint" confirmation before saving a first-time pin (out-of-band verification) whenever the chosen route is secure/TLS-based.

Enable, disable, and override:

openclaw plugins enable bonjour turns on LAN multicast advertising.
discovery.mdns.mode in openclaw.json governs mDNS broadcast: "minimal" (default), "full" (adds cliPath/sshPort to both the LAN beacon and any wide-area DNS-SD zone), or "off" (turns off mDNS).
OPENCLAW_DISABLE_BONJOUR=1 force-disables advertising; discovery.mdns.mode="off" disables it on its own. OPENCLAW_DISABLE_BONJOUR=0 is an explicit opt-in that overrides the plugin's auto-disable inside a detected container (Docker, containerd, Kubernetes, LXC); it does not override discovery.mdns.mode="off". The bundled bonjour plugin auto-starts on macOS hosts (enabledByDefaultOnPlatforms: ["darwin"]) and auto-disables inside detected containers; Linux, Windows, and other containerized deployments need explicit plugins enable bonjour.
gateway.bind in ~/.openclaw/openclaw.json controls the Gateway bind mode.
OPENCLAW_SSH_PORT overrides the advertised SSH port (only takes effect when discovery.mdns.mode="full").
OPENCLAW_TAILNET_DNS publishes a tailnetDns hint (MagicDNS).
OPENCLAW_CLI_PATH overrides the advertised CLI path.

2) Tailnet (cross-network)

For gateways sitting on different physical networks, Bonjour will not assist. The recommended direct target is a Tailscale MagicDNS name (preferred) or a stable tailnet IP.

When the gateway detects it runs under Tailscale, it publishes tailnetDns as an optional hint for clients (including wide-area beacons). The macOS app favors MagicDNS names over raw Tailscale IPs for gateway discovery, which remains reliable when tailnet IPs shift (node restarts, CGNAT reassignment) since MagicDNS automatically resolves to the current IP.

For mobile node pairing, discovery hints never relax transport security on tailnet/public routes:

On iOS and Android, a secure first-time connection through a tailnet or public endpoint remains mandatory (wss:// or Tailscale Serve/Funnel).
A raw tailnet IP found via discovery acts as a routing hint only, not as authorization for unencrypted remote ws://.
Direct-connect over a private LAN via ws:// is still supported.
For the simplest Tailscale setup on mobile nodes, rely on Tailscale Serve so both discovery and configuration point to the same secure MagicDNS endpoint.

3) Manual / SSH target

If no direct route exists, or direct is turned off, clients can always fall back to SSH by forwarding the loopback gateway port. Refer to Remote access for details.

Transport selection (client policy)

When a paired direct endpoint is set and reachable, prefer it.
Otherwise, if discovery locates a gateway on local. or the configured wide-area domain, present a one-tap "Use this gateway" option and store it as the direct endpoint.
Otherwise, if a tailnet DNS/IP is configured, attempt direct. On mobile nodes using tailnet/public routes, direct means a secure endpoint, never plaintext remote ws://.
Otherwise, fall back to SSH.

Pairing and auth (direct transport)

The gateway serves as the authoritative source for node and client admission:

Pairing requests are created, approved, or rejected at the gateway (see Gateway pairing).
The gateway enforces authentication (token/keypair), scopes/ACLs (it does not act as a raw proxy to every method), and rate limits.

Responsibilities by component

Gateway: broadcasts discovery beacons, controls pairing decisions, and hosts the WS endpoint.
macOS app: assists in gateway selection, displays pairing prompts, and uses SSH only as a fallback.
iOS/Android nodes: use Bonjour browsing as a convenience and connect to the paired Gateway WS.