Tailscale (Gateway-Dashboard)

OpenClaw kann Tailscale Serve (Tailnet) oder Funnel (öffentlich) automatisch für das Gateway-Dashboard und den WebSocket-Port konfigurieren. Dabei bleibt das Gateway an Loopback gebunden, während Tailscale HTTPS, Routing und (bei Serve) Identity-Header bereitstellt.

Modi

  • serve: Tailnet-only Serve via tailscale serve. Das Gateway bleibt auf 127.0.0.1.
  • funnel: Öffentliches HTTPS via tailscale funnel. OpenClaw erfordert ein gemeinsames Passwort.
  • off: Standard (keine Tailscale-Automatisierung).

Auth

Setze gateway.auth.mode zur Steuerung des Handshakes:

  • token (Standard wenn OPENCLAW_GATEWAY_TOKEN gesetzt ist)
  • password (gemeinsames Geheimnis via OPENCLAW_GATEWAY_PASSWORD oder Konfiguration)

Wenn tailscale.mode = "serve" und gateway.auth.allowTailscale auf true steht, kann die Control-UI/WebSocket-Auth Tailscale-Identity-Header (tailscale-user-login) verwenden, ohne ein Token/Passwort anzugeben. OpenClaw verifiziert die Identität, indem es die x-forwarded-for-Adresse über den lokalen Tailscale-Daemon (tailscale whois) auflöst und mit dem Header abgleicht. OpenClaw behandelt eine Anfrage nur dann als Serve, wenn sie von Loopback mit Tailscales x-forwarded-for-, x-forwarded-proto- und x-forwarded-host-Headern kommt. HTTP-API-Endpunkte (z. B. /v1/*, /tools/invoke und /api/channels/*) erfordern weiterhin Token-/Passwort-Auth. Dieser tokenlose Flow setzt voraus, dass der Gateway-Host vertrauenswürdig ist. Falls nicht vertrauenswürdiger lokaler Code auf demselben Host laufen könnte, deaktiviere gateway.auth.allowTailscale und erzwinge stattdessen Token-/Passwort-Auth. Um explizite Credentials zu erzwingen, setze gateway.auth.allowTailscale: false oder erzwinge gateway.auth.mode: "password".

Konfigurationsbeispiele

Tailnet-only (Serve)

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}

Öffne: https://<magicdns>/ (oder dein konfigurierter gateway.controlUi.basePath)

Tailnet-only (direkt an Tailnet-IP binden)

Verwende dies, wenn das Gateway direkt auf der Tailnet-IP lauschen soll (kein Serve/Funnel).

{
  gateway: {
    bind: "tailnet",
    auth: { mode: "token", token: "your-token" },
  },
}

Verbinde dich von einem anderen Tailnet-Gerät:

  • Control UI: http://<tailscale-ip>:18789/
  • WebSocket: ws://<tailscale-ip>:18789

Hinweis: Loopback (http://127.0.0.1:18789) funktioniert in diesem Modus nicht.

Öffentliches Internet (Funnel + gemeinsames Passwort)

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password", password: "replace-me" },
  },
}

Bevorzuge OPENCLAW_GATEWAY_PASSWORD gegenüber dem Speichern eines Passworts auf der Festplatte.

CLI-Beispiele

openclaw gateway --tailscale serve
openclaw gateway --tailscale funnel --auth password

Hinweise

  • Tailscale Serve/Funnel erfordert, dass die tailscale-CLI installiert und angemeldet ist.
  • tailscale.mode: "funnel" verweigert den Start, wenn der Auth-Modus nicht password ist, um öffentliche Exposition zu vermeiden.
  • Setze gateway.tailscale.resetOnExit, wenn OpenClaw die tailscale serve- oder tailscale funnel-Konfiguration beim Herunterfahren rückgängig machen soll.
  • gateway.bind: "tailnet" ist ein direkter Tailnet-Bind (kein HTTPS, kein Serve/Funnel).
  • gateway.bind: "auto" bevorzugt Loopback; verwende tailnet, wenn du Tailnet-only willst.
  • Serve/Funnel stellen nur die Gateway Control-UI + WS bereit. Nodes verbinden sich über denselben Gateway-WS-Endpunkt, sodass Serve auch für Node-Zugriff funktioniert.

Browser-Kontrolle (Remote-Gateway + lokaler Browser)

Wenn du das Gateway auf einem Rechner betreibst, aber einen Browser auf einem anderen steuern willst, betreibe einen Node-Host auf dem Browser-Rechner und halte beide im selben Tailnet. Das Gateway leitet Browser-Aktionen an den Node weiter; kein separater Control-Server oder Serve-URL nötig.

Vermeide Funnel für Browser-Kontrolle; behandle Node-Pairing wie Operator-Zugriff.

Tailscale-Voraussetzungen + Limits

  • Serve erfordert, dass HTTPS für dein Tailnet aktiviert ist; die CLI fragt nach, wenn es fehlt.
  • Serve injiziert Tailscale-Identity-Header; Funnel tut dies nicht.
  • Funnel erfordert Tailscale v1.38.3+, MagicDNS, HTTPS aktiviert und ein Funnel-Node-Attribut.
  • Funnel unterstützt nur die Ports 443, 8443 und 10000 über TLS.
  • Funnel auf macOS erfordert die Open-Source-Tailscale-App-Variante.

Mehr erfahren

arrow_back
Zurück
Remote Gateway Readme
Weiter
Formal Verification
arrow_forward