{
  "title": "Discovery & transports",
  "content": "OpenClaw has two distinct problems that look similar on the surface:\n\n1. **Operator remote control**: the macOS menu bar app controlling a gateway running elsewhere.\n2. **Node pairing**: iOS/Android (and future nodes) finding a gateway and pairing securely.\n\nThe design goal is to keep all network discovery/advertising in the **Node Gateway** (`openclaw gateway`) and keep clients (mac app, iOS) as consumers.\n\n* **Gateway**: a single long-running gateway process that owns state (sessions, pairing, node registry) and runs channels. Most setups use one per host; isolated multi-gateway setups are possible.\n* **Gateway WS (control plane)**: the WebSocket endpoint on `127.0.0.1:18789` by default; can be bound to LAN/tailnet via `gateway.bind`.\n* **Direct WS transport**: a LAN/tailnet-facing Gateway WS endpoint (no SSH).\n* **SSH transport (fallback)**: remote control by forwarding `127.0.0.1:18789` over SSH.\n* **Legacy TCP bridge (deprecated/removed)**: older node transport (see [Bridge protocol](/gateway/bridge-protocol)); no longer advertised for discovery.\n\n* [Gateway protocol](/gateway/protocol)\n* [Bridge protocol (legacy)](/gateway/bridge-protocol)\n\n## Why we keep both “direct” and SSH\n\n* **Direct WS** is the best UX on the same network and within a tailnet:\n  * auto-discovery on LAN via Bonjour\n  * pairing tokens + ACLs owned by the gateway\n  * no shell access required; protocol surface can stay tight and auditable\n* **SSH** remains the universal fallback:\n  * works anywhere you have SSH access (even across unrelated networks)\n  * survives multicast/mDNS issues\n  * requires no new inbound ports besides SSH\n\n## Discovery inputs (how clients learn where the gateway is)\n\n### 1) Bonjour / mDNS (LAN only)\n\nBonjour is best-effort and does not cross networks. It is only used for “same LAN” convenience.\n\n* The **gateway** advertises its WS endpoint via Bonjour.\n* Clients browse and show a “pick a gateway” list, then store the chosen endpoint.\n\nTroubleshooting and beacon details: [Bonjour](/gateway/bonjour).\n\n#### Service beacon details\n\n* Service types:\n  * `_openclaw-gw._tcp` (gateway transport beacon)\n* TXT keys (non-secret):\n  * `role=gateway`\n  * `lanHost=<hostname>.local`\n  * `sshPort=22` (or whatever is advertised)\n  * `gatewayPort=18789` (Gateway WS + HTTP)\n  * `gatewayTls=1` (only when TLS is enabled)\n  * `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)\n  * `canvasPort=18793` (default canvas host port; serves `/__openclaw__/canvas/`)\n  * `cliPath=<path>` (optional; absolute path to a runnable `openclaw` entrypoint or binary)\n  * `tailnetDns=<magicdns>` (optional hint; auto-detected when Tailscale is available)\n\n* `OPENCLAW_DISABLE_BONJOUR=1` disables advertising.\n* `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode.\n* `OPENCLAW_SSH_PORT` overrides the SSH port advertised in TXT (defaults to 22).\n* `OPENCLAW_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS).\n* `OPENCLAW_CLI_PATH` overrides the advertised CLI path.\n\n### 2) Tailnet (cross-network)\n\nFor London/Vienna style setups, Bonjour won’t help. The recommended “direct” target is:\n\n* Tailscale MagicDNS name (preferred) or a stable tailnet IP.\n\nIf the gateway can detect it is running under Tailscale, it publishes `tailnetDns` as an optional hint for clients (including wide-area beacons).\n\n### 3) Manual / SSH target\n\nWhen there is no direct route (or direct is disabled), clients can always connect via SSH by forwarding the loopback gateway port.\n\nSee [Remote access](/gateway/remote).\n\n## Transport selection (client policy)\n\nRecommended client behavior:\n\n1. If a paired direct endpoint is configured and reachable, use it.\n2. Else, if Bonjour finds a gateway on LAN, offer a one-tap “Use this gateway” choice and save it as the direct endpoint.\n3. Else, if a tailnet DNS/IP is configured, try direct.\n4. Else, fall back to SSH.\n\n## Pairing + auth (direct transport)\n\nThe gateway is the source of truth for node/client admission.\n\n* Pairing requests are created/approved/rejected in the gateway (see [Gateway pairing](/gateway/pairing)).\n* The gateway enforces:\n  * auth (token / keypair)\n  * scopes/ACLs (the gateway is not a raw proxy to every method)\n  * rate limits\n\n## Responsibilities by component\n\n* **Gateway**: advertises discovery beacons, owns pairing decisions, and hosts the WS endpoint.\n* **macOS app**: helps you pick a gateway, shows pairing prompts, and uses SSH only as a fallback.\n* **iOS/Android nodes**: browse Bonjour as a convenience and connect to the paired Gateway WS.",
  "code_samples": [],
  "headings": [
    {
      "level": "h2",
      "text": "Terms",
      "id": "terms"
    },
    {
      "level": "h2",
      "text": "Why we keep both “direct” and SSH",
      "id": "why-we-keep-both-“direct”-and-ssh"
    },
    {
      "level": "h2",
      "text": "Discovery inputs (how clients learn where the gateway is)",
      "id": "discovery-inputs-(how-clients-learn-where-the-gateway-is)"
    },
    {
      "level": "h3",
      "text": "1) Bonjour / mDNS (LAN only)",
      "id": "1)-bonjour-/-mdns-(lan-only)"
    },
    {
      "level": "h3",
      "text": "2) Tailnet (cross-network)",
      "id": "2)-tailnet-(cross-network)"
    },
    {
      "level": "h3",
      "text": "3) Manual / SSH target",
      "id": "3)-manual-/-ssh-target"
    },
    {
      "level": "h2",
      "text": "Transport selection (client policy)",
      "id": "transport-selection-(client-policy)"
    },
    {
      "level": "h2",
      "text": "Pairing + auth (direct transport)",
      "id": "pairing-+-auth-(direct-transport)"
    },
    {
      "level": "h2",
      "text": "Responsibilities by component",
      "id": "responsibilities-by-component"
    }
  ],
  "url": "llms-txt#discovery-&-transports",
  "links": []
}