Hoppa till huvudinnehåll

​
Discovery & transporter

OpenClaw har två skilda problem som ser likadana ut på ytan:
  1. Operatörens fjärrstyrning: macOS-menyradsappen som styr en gateway som körs någon annanstans.
  2. Nodparning: iOS/Android (och framtida noder) som hittar en gateway och parar säkert.
Designmålet är att hålla all nätverksupptäckt/annonsering i Node Gateway (openclaw gateway) och låta klienter (mac-app, iOS) vara konsumenter.

​
Termer

  • Gateway: en enda långvarig gateway-process som äger tillstånd (sessioner, parning, nodregistret) och kör kanaler. De flesta inställningar använder en per värd, isolerade multi-gateway-inställningar är möjliga.
  • Gateway WS (kontrollplan): WebSocket-ändpunkten på 127.0.0.1:18789 som standard; kan bindas till LAN/tailnet via gateway.bind.
  • Direkt WS-transport: en LAN-/tailnet-exponerad Gateway WS-ändpunkt (ingen SSH).
  • SSH-transport (fallback): fjärrstyrning genom att vidarebefordra 127.0.0.1:18789 över SSH.
  • Legacy TCP-brygga (föråldrad/borttagen): äldre nodtransport (se Bridge protocol); annonseras inte längre för upptäckt.
Protokolldetaljer:

​
Varför vi behåller både ”direkt” och SSH

  • Direkt WS ger bäst UX på samma nätverk och inom ett tailnet:
    • automatisk upptäckt på LAN via Bonjour
    • parningstoken + ACL:er ägs av gatewayn
    • ingen shell-åtkomst krävs; protokollytan kan hållas snäv och granskningsbar
  • SSH förblir den universella fallbacken:
    • fungerar överallt där du har SSH-åtkomst (även över orelaterade nätverk)
    • överlever multicast/mDNS-problem
    • kräver inga nya inkommande portar utöver SSH

​
Discovery-indata (hur klienter får veta var gatewayn finns)

​
1. Bonjour / mDNS (endast LAN)

Bonjour är bäst och korsar inte nätverk. Det används bara för “samma LAN” bekvämlighet. Målriktning:
  • Gatewayn annonserar sin WS-ändpunkt via Bonjour.
  • Klienter bläddrar och visar en lista ”välj en gateway”, och lagrar sedan den valda ändpunkten.
Felsökning och beacon-detaljer: Bonjour.

​
Service beacon-detaljer

  • Tjänsttyper:
    • _openclaw-gw._tcp (gateway-transportbeacon)
  • TXT-nycklar (icke-hemliga):
    • role=gateway
    • lanHost=<hostname>.local
    • sshPort=22 (eller vad som än annonseras)
    • gatewayPort=18789 (Gateway WS + HTTP)
    • gatewayTls=1 (endast när TLS är aktiverat)
    • gatewayTlsSha256=<sha256> (endast när TLS är aktiverat och fingeravtryck är tillgängligt)
    • canvasPort=18793 (standardport för canvas-värd; serverar /__openclaw__/canvas/)
    • cliPath=<path> (valfri; absolut sökväg till en körbar openclaw-entrypoint eller binär)
    • tailnetDns=<magicdns> (valfritt tips; auto-detekteras när Tailscale är tillgängligt)
Inaktivera/åsidosätt:
  • Bonjour/mDNS TXT‑poster är oautentiserade. Klienter måste endast behandla TXT‑värden som UX‑ledtrådar.
  • gateway.bind i ~/.openclaw/openclaw.json styr Gatewayns bindningsläge.
  • OPENCLAW_SSH_PORT åsidosätter SSH-porten som annonseras i TXT (standard är 22).
  • OPENCLAW_TAILNET_DNS publicerar ett tailnetDns-tips (MagicDNS).
Inaktivera/åsidosätt:
  • OPENCLAW_DISABLE_BONJOUR=1 inaktiverar annonsering.
  • gateway.bind i ~/.openclaw/openclaw.json styr Gatewayns bindningsläge.
  • OPENCLAW_SSH_PORT åsidosätter SSH-porten som annonseras i TXT (standard är 22).
  • OPENCLAW_TAILNET_DNS publicerar ett tailnetDns-tips (MagicDNS).
  • OPENCLAW_CLI_PATH åsidosätter den annonserade CLI-sökvägen.

​
2. Tailnet (över nätverk)

För London/Wien stil uppsättningar kommer Bonjour inte att hjälpa. Det rekommenderade ”direkt” målet är:
  • Tailscale MagicDNS-namn (föredras) eller en stabil tailnet-IP.
När det inte finns någon direkt rutt (eller direkt är inaktiverat) kan klienter alltid ansluta via SSH genom att vidarebefordra loopback-gatewayporten.

​
3. Manuell / SSH-mål

När det inte finns någon direkt rutt (eller direkt är inaktiverat) kan klienter alltid ansluta via SSH genom att vidarebefordra loopback-gatewayporten. Rekommenderat klientbeteende:

​
Transportval (klientpolicy)

Rekommenderat klientbeteende:
  1. Om en parad direkt-ändpunkt är konfigurerad och nåbar, använd den.
  2. Annars, om Bonjour hittar en gateway på LAN, erbjud ett ett-trycks-val ”Använd denna gateway” och spara den som direkt-ändpunkt.
  3. Annars, om ett tailnet-DNS/IP är konfigurerat, prova direkt.
  4. Annars, fall tillbaka till SSH.

​
Parning + autentisering (direkt transport)

Gatewayn är sanningskällan för nod-/klientantagning.
  • Gateway: annonserar discovery-beacons, äger parningsbeslut och är värd för WS-ändpunkten.
  • macOS-app: hjälper dig att välja en gateway, visar parningsuppmaningar och använder SSH endast som fallback.
    • autentisering (token / nyckelpar)
    • scopes/ACL:er (gatewayn är inte en rå proxy till varje metod)
    • hastighetsbegränsningar

​
Ansvar per komponent

  • Gateway: annonserar discovery-beacons, äger parningsbeslut och är värd för WS-ändpunkten.
  • macOS-app: hjälper dig att välja en gateway, visar parningsuppmaningar och använder SSH endast som fallback.
  • iOS/Android-noder: bläddrar i Bonjour som en bekvämlighet och ansluter till den parade Gateway WS.