Configure OpenClaw Discovery: Bonjour and SSH Setup

Ever felt the frustration of trying to get your mobile app to talk to a workstation on your local network, only to realize you have no idea what the IP address is? Or worse, you’re trying to connect over a remote link and everything just breaks. We’ve all been there, and it’s exactly why OpenClaw handles discovery and transports the way it does.

OpenClaw deals with two main connection challenges: letting the macOS menu bar app control a remote gateway, and helping mobile nodes find and pair with that gateway securely. The goal is to keep all the heavy lifting—like advertising and discovery—inside the Node Gateway (openclaw gateway), so your clients can just focus on using the data.

Terms

Before we get into the details, here are the core concepts you should know:

• Gateway: This is the single, long-running process that owns your sessions, pairing data, and node registry. Usually, you’ll run one per host.
• Gateway WS (control plane): The WebSocket endpoint. It defaults to 127.0.0.1:18789, but you can bind it to your LAN or tailnet using gateway.bind.
• Direct WS transport: A WebSocket endpoint that faces your LAN or tailnet directly without needing SSH.
• SSH transport (fallback): A way to control the gateway by forwarding the local port over an SSH connection.
• Legacy TCP bridge (deprecated/removed): An older transport method that we don’t use for discovery anymore. You can find more info in the Bridge protocol.

If you want to look at the low-level specs, check out these links:

• Gateway protocol
• Bridge protocol (legacy)

Why we keep both “direct” and SSH

You might wonder why we don’t just pick one. Each method solves a different problem.

Direct WS offers the best experience when you’re on the same network or using a tailnet:

• It uses Bonjour for auto-discovery on your LAN and keeps pairing tokens and ACLs managed directly by the gateway.
• It doesn’t require shell access, which keeps the protocol surface tight and easy to audit.

SSH is our universal fallback for a few reasons:

• It works anywhere you have SSH access, even across totally unrelated networks.
• It survives issues with multicast or mDNS and doesn’t require you to open any new inbound ports.

Discovery inputs (how clients learn where the gateway is)

Clients need to know where to look. Here is how they find the gateway across different environments.

1) Bonjour / mDNS (LAN only)

Bonjour is great for “same LAN” convenience, though it doesn’t cross between different networks. The gateway advertises its WebSocket endpoint, and you can just pick it from a list in your app.

For more on troubleshooting and beacons, see Bonjour.

Service beacon details

• Service types:
  • _openclaw-gw._tcp (gateway transport beacon)
• TXT keys (non-secret):
  • role=gateway
  • transport=gateway
  • displayName=<friendly name> (operator-configured display name)
  • lanHost=<hostname>.local
  • sshPort=22 (or whatever is advertised)
  • gatewayPort=18789 (Gateway WS + HTTP)
  • gatewayTls=1 (only when TLS is enabled)
  • gatewayTlsSha256=<sha256> (only when TLS is enabled and fingerprint is available)
  • canvasPort=<port> (canvas host port; currently the same as gatewayPort when the canvas host is enabled)
  • cliPath=<path> (optional; absolute path to a runnable openclaw entrypoint or binary)
  • tailnetDns=<magicdns> (optional hint; auto-detected when Tailscale is available)

Security is important here. Bonjour TXT records are unauthenticated, so clients treat them as hints. You should always prefer the resolved service endpoint over the TXT values. Also, iOS and Android nodes treat these as TLS-only and will ask you to confirm the fingerprint before saving it.

2) Tailnet (cross-network)

If you’re working across different cities, Bonjour won’t help. In this case, we recommend using a Tailscale MagicDNS name or a stable tailnet IP. If the gateway detects it’s on Tailscale, it will publish a tailnetDns hint. The macOS app prefers MagicDNS names because they stay reliable even if IPs change after a restart.

3) Manual / SSH target

When there is no direct route available, you can always connect via SSH by forwarding the loopback gateway port. You can find more details in the Remote access guide.

4) Configuration Overrides

If you need to tweak how discovery works, you can use these environment variables and settings:

• OPENCLAW_DISABLE_BONJOUR=1 disables advertising.
• gateway.bind in ~/.openclaw/openclaw.json controls the Gateway bind mode.
• OPENCLAW_SSH_PORT overrides the SSH port advertised in TXT (defaults to 22).
• OPENCLAW_TAILNET_DNS publishes a tailnetDns hint (MagicDNS).
• OPENCLAW_CLI_PATH overrides the advertised CLI path.

Transport selection (client policy)

To keep things simple, clients follow a specific order when trying to connect:

1. If you have a paired direct endpoint configured and it’s reachable, use it.
2. If Bonjour finds a gateway on the LAN, the app will offer a “Use this gateway” option and save it.
3. If a tailnet DNS or IP is set up, the client tries a direct connection.
4. If all else fails, it falls back to SSH.

Pairing + auth (direct transport)

The gateway is the boss when it comes to who gets in. It handles all the pairing requests and security checks.

• You create, approve, or reject pairing requests directly in the gateway (see Gateway pairing).
• The gateway handles authentication via tokens or keypairs and manages scope-based ACLs.
• It also manages rate limits to keep the connection stable.

Responsibilities by component

To keep the system organized, each part has a specific job:

• Gateway: This component advertises discovery beacons, makes pairing decisions, and hosts the WebSocket endpoint.
• macOS app: This helps you pick a gateway from a list and shows pairing prompts.
• iOS/Android nodes: These browse Bonjour for convenience and connect to the paired Gateway WS.
• Protocol Layer: This ensures that all communication between the gateway and clients remains secure and consistent.

Next Steps

• Learn more about Gateway pairing
• Set up Remote access
• Check the Bonjour troubleshooting guide

Still have questions? Check out the AI Setup Assistant.