Naar hoofdinhoud gaan

​
Detectie & transportlagen

OpenClaw heeft twee afzonderlijke problemen die aan de oppervlakte op elkaar lijken:
  1. Externe bediening door de operator: de macOS-menubalkapp die een Gateway bestuurt die elders draait.
  2. Node-pairing: iOS/Android (en toekomstige nodes) die een Gateway vinden en veilig pairen.
Het ontwerpdoel is om alle netwerk-discovery/-advertising in de Node Gateway (openclaw gateway) te houden en clients (mac-app, iOS) als consumenten te laten fungeren.

​
Termen

  • Gateway: één langlopende Gateway-proces dat de state bezit (sessies, pairing, node-register) en kanalen draait. De meeste setups gebruiken er één per host; geïsoleerde multi-Gateway-setup zijn mogelijk.
  • Gateway WS (control plane): het WebSocket-eindpunt op 127.0.0.1:18789 standaard; kan aan LAN/tailnet worden gebonden via gateway.bind.
  • Direct WS transport: een LAN-/tailnet-gericht Gateway WS-eindpunt (zonder SSH).
  • SSH transport (fallback): externe bediening door het forwarden van 127.0.0.1:18789 via SSH.
  • Legacy TCP bridge (verouderd/verwijderd): ouder node-transport (zie Bridge protocol); niet langer geadverteerd voor discovery.
Protocoldetails:

​
Waarom we zowel “direct” als SSH behouden

  • Direct WS biedt de beste UX op hetzelfde netwerk en binnen een tailnet:
    • auto-discovery op LAN via Bonjour
    • pairing-tokens + ACL’s in beheer van de Gateway
    • geen shell-toegang vereist; het protocoloppervlak kan strak en auditbaar blijven
  • SSH blijft de universele fallback:
    • werkt overal waar je SSH-toegang hebt (zelfs over niet-verwante netwerken)
    • overleeft multicast/mDNS-problemen
    • vereist geen nieuwe inkomende poorten naast SSH

​
Discovery-inputs (hoe clients leren waar de Gateway is)

​
1. Bonjour / mDNS (alleen LAN)

Bonjour is best-effort en gaat niet over netwerken heen. Het wordt alleen gebruikt voor gemak binnen “hetzelfde LAN”. Doel richting:
  • De Gateway adverteert zijn WS-eindpunt via Bonjour.
  • Clients browsen en tonen een lijst “kies een Gateway”, en slaan daarna het gekozen eindpunt op.
Problemen oplossen en beacon-details: Bonjour.

​
Service-beacon-details

  • Servicetypen:
    • _openclaw-gw._tcp (Gateway-transportbeacon)
  • TXT-sleutels (niet-geheim):
    • role=gateway
    • lanHost=<hostname>.local
    • sshPort=22 (of wat er ook geadverteerd wordt)
    • gatewayPort=18789 (Gateway WS + HTTP)
    • gatewayTls=1 (alleen wanneer TLS is ingeschakeld)
    • gatewayTlsSha256=<sha256> (alleen wanneer TLS is ingeschakeld en een fingerprint beschikbaar is)
    • canvasPort=18793 (standaard canvas-hostpoort; bedient /__openclaw__/canvas/)
    • cliPath=<path> (optioneel; absoluut pad naar een uitvoerbaar openclaw-entrypoint of binaire)
    • tailnetDns=<magicdns> (optionele hint; automatisch gedetecteerd wanneer Tailscale beschikbaar is)
Beveiligingsopmerkingen:
  • Bonjour/mDNS TXT-records zijn niet-geauthenticeerd. Clients moeten TXT-waarden uitsluitend als UX-hints behandelen.
  • Routing (host/poort) moet de voorkeur geven aan het opgeloste service-endpoint (SRV + A/AAAA) boven via TXT opgegeven lanHost, tailnetDns of gatewayPort.
  • TLS-pinning mag nooit toestaan dat een geadverteerde gatewayTlsSha256 een eerder opgeslagen pin overschrijft.
  • iOS/Android-nodes moeten discovery-gebaseerde directe verbindingen behandelen als alleen-TLS en een expliciete “vertrouw deze fingerprint”-bevestiging vereisen voordat een eerste pin wordt opgeslagen (out-of-band verificatie).
Uitschakelen/overschrijven:
  • OPENCLAW_DISABLE_BONJOUR=1 schakelt adverteren uit.
  • gateway.bind in ~/.openclaw/openclaw.json bepaalt de Gateway-bindmodus.
  • OPENCLAW_SSH_PORT overschrijft de SSH-poort die in TXT wordt geadverteerd (standaard 22).
  • OPENCLAW_TAILNET_DNS publiceert een tailnetDns-hint (MagicDNS).
  • OPENCLAW_CLI_PATH overschrijft het geadverteerde CLI-pad.

​
2. Tailnet (cross-network)

Voor London/Vienna-achtige setups helpt Bonjour niet. Het aanbevolen “directe” doel is:
  • Tailscale MagicDNS-naam (bij voorkeur) of een stabiel tailnet-IP-adres.
Als de Gateway kan detecteren dat hij onder Tailscale draait, publiceert hij tailnetDns als optionele hint voor clients (inclusief wide-area beacons).

​
3. Handmatig / SSH-doel

Wanneer er geen directe route is (of direct is uitgeschakeld), kunnen clients altijd via SSH verbinden door de local loopback Gateway-poort te forwarden. Zie Remote access.

​
Transportselectie (clientbeleid)

Aanbevolen clientgedrag:
  1. Als een gepaird direct eindpunt is geconfigureerd en bereikbaar, gebruik dit.
  2. Anders, als Bonjour een Gateway op LAN vindt, bied een een-tik-keuze “Gebruik deze Gateway” aan en sla deze op als het directe eindpunt.
  3. Anders, als een tailnet-DNS/IP is geconfigureerd, probeer direct.
  4. Anders, val terug op SSH.

​
Pairing + auth (direct transport)

De Gateway is de bron van waarheid voor toelating van nodes/clients.
  • Pairing-verzoeken worden aangemaakt/goedgekeurd/afgewezen in de Gateway (zie Gateway pairing).
  • De Gateway handhaaft:
    • authenticatie (token / sleutelpaar)
    • scopes/ACL’s (de Gateway is geen ruwe proxy naar elke methode)
    • rate limits

​
Verantwoordelijkheden per component

  • Gateway: adverteert discovery-beacons, beheert pairing-beslissingen en host het WS-eindpunt.
  • macOS-app: helpt je een Gateway te kiezen, toont pairing-prompts en gebruikt SSH alleen als fallback.
  • iOS/Android-nodes: browsen Bonjour als gemak en verbinden met de gepairde Gateway WS.