Skip to Content
👋 Willkommen bei HowToUseOpenClaw Schnellstart
GatewayDiscovery

Discovery & transports

OpenClaw has two distinct problems that look similar on the surface:

  1. Operator remote control: the macOS menu bar app controlling a gateway running elsewhere.
  2. Node pairing: iOS/Android (and future nodes) finding a gateway and pairing securely.

The design goal is to keep all network discovery/advertising in the Node Gateway (clawd / openclaw gateway) and keep clients (mac app, iOS) as consumers.

Terms

  • 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.
  • Gateway WS (control plane): the WebSocket endpoint on 127.0.0.1:18789 by default; can be bound to LAN/tailnet via gateway.bind.
  • Direct WS transport: a LAN/tailnet-facing Gateway WS endpoint (no SSH ausführt) hinterlegen.
  • SSH transport (fallback): remote control by forwarding 127.0.0.1:18789 over SSH.
  • Legacy TCP bridge (deprecated/removed): older node transport (see Bridge protocol); no longer advertised for discovery.

Protokoll details:

Why we keep both “direct” and SSH

  • Direct WSis the best UX on the same network and within a tailnet:

    • auto-discovery on LAN via Bonjour
    • pairing tokens + ACLs owned by the gateway
    • no shell access required; protocol surface can stay tight and auditable

  • SSHremains the universal fallback:

    • works anywhere you have SSH access (even across unrelated networks)
    • survives multicast/mDNS issues
    • requires no new inbound ports besides SSH

Discovery inputs (how clients learn where the gateway is)

1) Bonjour / mDNS (LAN only)

Bonjour is best-effort and does not cross networks. It is only used for “same LAN” convenience.Target direction:

  • The gateway advertises its WS endpoint via Bonjour.
  • Clients browse and show a “pick a gateway” list, then store the chosen endpoint.

Fehlerbehebung and beacon details: [Bonjour](/de/gateway/bonjour ausführt) hinterlegen.

Service beacon details

  • Service types:
    • _openclaw-gw._tcp (gateway transport beacon)
  • TXT keys (non-secret):
    • role=gateway
    • 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=18793 (default canvas host port; serves /__openclaw__/canvas/)
    • cliPath=<path> (optional; absolute path to a runnable openclaw entrypoint or binary)
    • tailnetDns=<magicdns> (optional hint; auto-detected when Tailscale is available)

Disable/override:

  • CLAWDBOT_DISABLE_BONJOUR=1 disables advertising.
  • gateway.bind in ~/.clawdbot/openclaw.json controls the Gateway bind mode.
  • CLAWDBOT_SSH_PORT overrides the SSH port advertised in TXT (defaults to 22 ausführt) hinterlegen.
  • CLAWDBOT_TAILNET_DNS publishes a tailnetDns hint (MagicDNS ausführt) hinterlegen.
  • CLAWDBOT_CLI_PATH overrides the advertised CLI path.

2) Tailnet (cross-network)

For London/Vienna style setups, Bonjour won’t help. The recommended “direct” target is:

  • Tailscale MagicDNS name (preferred) or a stable tailnet IP.

If the gateway can detect it is running under Tailscale, it publishes tailnetDns as an optional hint for clients (including wide-area beacons ausführt) hinterlegen.

3) Manual / SSH target

When there is no direct route (or direct is disabled), clients can always connect via SSH by forwarding the loopback gateway port.Siehe [Remote access](/de/gateway/remote ausführt) hinterlegen.

Transport selection (client policy)

Recommended client behavior:

  1. If a paired direct endpoint is configured and reachable, use it.
  2. Else, if Bonjour finds a gateway on LAN, offer a one-tap “Use this gateway” choice and save it as the direct endpoint.
  3. Else, if a tailnet DNS/IP is configured, try direct.
  4. Else, fall back to SSH.

Pairing + auth (direct transport)

The gateway is the source of truth for node/client admission.

  • Pairing requests are created/approved/rejected in the gateway (see Gateway pairing ausführt) hinterlegen.
  • The gateway enforces:
    • auth (token / keypair)
    • scopes/ACLs (the gateway is not a raw proxy to every method)
    • rate limits

Responsibilities by component

  • Gateway: advertises discovery beacons, owns pairing decisions, and hosts the WS endpoint.
  • macOS app: helps you pick a gateway, shows pairing prompts, and uses SSH only as a fallback.
  • iOS/Android nodes: browse Bonjour as a convenience and connect to the paired Gateway WS.
Zuletzt aktualisiert am:
KonfigurationDoctor