OpenClaw Remote Nodes sicher einrichten: Tailscale, Pairing und Fehlersuche

Ein Remote Node kann verbunden sein, obwohl ein Systembefehl weiterhin abgewiesen wird. Ebenso kann eine Kamera als Capability erscheinen, aber wegen fehlender Betriebssystemrechte oder einer App im Hintergrund nicht reagieren. Das sind unterschiedliche Fehlerklassen. Wer sie getrennt prüft, findet die Ursache schneller.

OpenClaw betreibt einen Gateway als Zentrale. Dort liegen Sitzungen, Authentifizierung, Nachrichtenkanäle und Zustand. Ein Node ist dagegen ein angebundenes Gerät, das lokale Fähigkeiten wie Kamera, Bildschirm, Benachrichtigungen oder Systembefehle bereitstellt. Nachrichten aus Telegram, WhatsApp oder anderen Kanälen landen weiterhin am Gateway, nicht am Node.

Dieses Tutorial richtet wahlweise einen privaten Tailscale- oder SSH-Pfad ein, koppelt einen Node und prüft anschließend eine bewusst eng begrenzte Aktion.

Voraussetzungen

Du brauchst:

• einen laufenden OpenClaw Gateway auf einem erreichbaren Rechner,
• ein zweites Gerät für den Node,
• administrativen Zugriff auf den Gateway,
• ein Gateway-Token oder Gateway-Passwort für den Node,
• für Tailscale eine installierte und angemeldete Tailscale-CLI auf beiden Geräten,
• aktiviertes HTTPS im Tailnet, wenn du Tailscale Serve verwendest.

Bewahre Gateway-Token und Passwörter in einer geschützten Umgebungs- oder Secret-Verwaltung auf. Trage echte Zugangsdaten weder in Shell-Beispiele noch in gemeinsam genutzte Konfigurationsdateien ein. Der Serienartikel OpenClaw SecretRef richtig einsetzen zeigt, wie du Zugangsdaten referenzierst und rotierst.

Prüfe auf dem Gateway-Host:

openclaw status
openclaw gateway status

Erwartet wird ein laufender Gateway mit erfolgreicher Verbindungssonde. Falls bereits dieser Schritt fehlschlägt, behebe den Gateway, bevor du Tailscale, einen Tunnel oder das Node Pairing untersuchst.

Variante A: Node über Tailscale Serve verbinden

Tailscale Serve stellt die Control UI und den Gateway-WebSocket im Tailnet über HTTPS bereit. Der OpenClaw-Prozess bleibt dabei an Loopback gebunden.

Setze auf dem Gateway-Host:

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

Wenn du die Struktur der openclaw.json noch nicht kennst, erklärt Gateway-Konfiguration: openclaw.json verständlich erklärt Ablage und Syntax.

Starte den Gateway neu und prüfe beide Dienste:

openclaw gateway restart
openclaw gateway status
tailscale status
tailscale serve status

tailscale serve status sollte eine HTTPS-Adresse im Tailnet anzeigen. Öffne diese Adresse von einem zweiten Gerät im selben Tailnet. Die Control UI muss erreichbar sein. Ein Gerät außerhalb des Tailnets darf über Serve keinen Zugriff erhalten.

Übernimm den Hostnamen aus dieser HTTPS-Adresse. Zeigt die Ausgabe beispielsweise https://gateway-name.example.ts.net, ist gateway-name.example.ts.net der Host für den folgenden Aufruf.

Starte auf dem Node-Host:

export OPENCLAW_GATEWAY_TOKEN='<gateway-token>'
openclaw node run --host <magicdns-host> --port 443 --tls --display-name "Build Node"

Verwendet dein Gateway Passwort- statt Token-Authentifizierung, setze entsprechend OPENCLAW_GATEWAY_PASSWORD. Setze nicht beide Werte auf Verdacht.

Der Prozess bleibt im Vordergrund und sollte am Gateway einen Pairing-Antrag erzeugen. Falls die Serve-URL einen abweichenden Port oder einen konfigurierten Gateway-Kontextpfad enthält, übernimm diese Angaben und ergänze bei Bedarf --context-path.

gateway.tailscale.mode: "serve" ersetzt nicht jede Gateway-Authentifizierung. Native Clients und Nodes arbeiten weiterhin mit den für den Gateway konfigurierten Zugangsdaten. gateway.auth.allowTailscale ist keine pauschale Freigabe für beliebige Gateway-Endpunkte.

Funnel ist für diesen privaten Aufbau nicht erforderlich. Es macht den HTTPS-Endpunkt öffentlich erreichbar und verlangt deshalb eine eigene Authentifizierungs- und Risikoentscheidung.

Variante B: SSH-Tunnel verwenden

Wenn Serve nicht verfügbar ist, leite den Loopback-Port des Gateways über SSH weiter.

Führe auf dem Node-Host aus:

ssh -N -L 18790:127.0.0.1:18789 <user>@<gateway-host>

Dieses Terminal bleibt geöffnet. Der lokale Port 18790 zeigt nun durch den Tunnel auf 127.0.0.1:18789 des Gateway-Hosts.

Starte in einem zweiten Terminal auf dem Node-Host:

export OPENCLAW_GATEWAY_TOKEN='<gateway-token>'
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

Bei Passwort-Authentifizierung verwendest du OPENCLAW_GATEWAY_PASSWORD. Eine abgelehnte Verbindung an dieser Stelle spricht eher für falsche Zugangsdaten, einen geschlossenen Tunnel oder einen nicht laufenden Gateway als für ein Capability-Problem.

Node koppeln und Zustand prüfen

Die folgenden Befehle laufen auf dem Gateway-Host oder auf einem administrativen Client, der mit dem Gateway verbunden ist:

openclaw devices list

Suche den ausstehenden Antrag des neuen Geräts und prüfe Namen sowie Metadaten. Genehmige nur den erwarteten Antrag:

openclaw devices approve <requestId>

Pending Node-Pairing-Anträge laufen fünf Minuten nach dem letzten Verbindungsversuch ab. Ein Node, der weiter versucht, sich zu verbinden, hält seinen bestehenden Antrag aktiv.

Prüfe anschließend:

openclaw nodes status
openclaw nodes describe --node "Build Node"

Erwartet wird ein verbundener und gekoppelter Node mit seinen Capabilities und unterstützten Aufrufen. Fehlt der Node vollständig, untersuche Transport, Zugangsdaten und Pairing. Fehlt nur eine bestimmte Capability, helfen zusätzliche Exec-Freigaben nicht: Der Node stellt diese Fähigkeit dann nicht bereit.

Auf einem Mac mit laufender OpenClaw-Menüleisten-App darfst du nicht parallel einen zweiten CLI-Node starten. Die App betreibt den Node-Host bereits intern und bleibt die einzige Node-Identität dieses Macs.

Sicherheitsgrenzen für Node-Aktionen

Für eine ausführbare Node-Aktion sind drei Freigabeebenen relevant:

1. Das konkrete Gerät ist per Device Pairing als Node zugelassen.
2. Die Gateway-Command-Policy lässt den betreffenden Node-Command zu.
3. Der Zielhost erlaubt den konkreten lokalen Prozess entsprechend Exec-Modus und Allowlist.

Die von nodes describe gemeldete Capability ist zusätzlich eine technische Voraussetzung, aber keine weitere Freigabe. Ein Gerät kann korrekt gekoppelt sein und einen Systemaufruf trotzdem nicht anbieten oder nicht ausführen dürfen.

Das Runtime-Schema verwendet für die Gateway-Policy diese Felder:

{
  gateway: {
    nodes: {
      allowCommands: ["system.run"],
      denyCommands: []
    }
  }
}

Nimm gefährliche Commands nur dann in gateway.nodes.allowCommands auf, wenn du sie tatsächlich brauchst. Ein passender Eintrag in gateway.nodes.denyCommands blockiert den Aufruf. Die Gateway-Policy ersetzt keine Exec-Approval auf dem Node-Host.

Nach einer Policy-Änderung startest du den Gateway neu und prüfst den Node:

openclaw gateway restart
openclaw nodes describe --node "Build Node"

Einen eng begrenzten Systembefehl testen

Route Exec-Aufrufe ausdrücklich zum gekoppelten Node und verwende den Allowlist-Modus:

{
  tools: {
    exec: {
      host: "node",
      mode: "allowlist",
      node: "Build Node"
    }
  }
}

Starte den Gateway nach der Änderung neu und kontrolliere den Node:

openclaw gateway restart
openclaw nodes describe --node "Build Node"

Prüfe den aktuellen Approval-Zustand:

openclaw approvals get --node "Build Node"

Erlaube für den Test ausschließlich den absoluten Programmpfad von uname:

openclaw approvals allowlist add --node "Build Node" "/usr/bin/uname"
openclaw approvals get --node "Build Node"

Die zweite Ausgabe muss /usr/bin/uname in der Allowlist des Nodes zeigen. Sende deinem OpenClaw-Agenten anschließend diesen eindeutigen Auftrag:

Führe auf dem konfigurierten Node exakt /usr/bin/uname ohne Argumente aus. Verwende keinen anderen Befehl.

Mit tools.exec.host: "node" und tools.exec.node: "Build Node" richtet OpenClaw den Exec-Aufruf an diesen Node. tools.exec.mode: "allowlist" begrenzt ihn auf freigegebene Programme. Erwartet wird ein Aufruf von /usr/bin/uname auf „Build Node“ und als Ergebnis beispielsweise Linux oder Darwin.

Kontrolliere bei diesem Test zusätzlich:

openclaw logs --follow

Im Log müssen der adressierte Node und /usr/bin/uname zum Test passen. Bricht der Agent den Auftrag ab oder schlägt einen anderen Befehl vor, führe diesen nicht ersatzweise aus.

Scheitert der Aufruf mit SYSTEM_RUN_DENIED, prüfe in dieser Reihenfolge:

• Meldet openclaw nodes describe --node "Build Node" den benötigten Systemaufruf?
• Blockiert gateway.nodes.denyCommands den Command?
• Erlaubt gateway.nodes.allowCommands den Command, falls du eine explizite Allowlist verwendest?
• Zeigt openclaw approvals get --node "Build Node" den Allowlist-Modus und /usr/bin/uname?
• Stehen tools.exec.host, tools.exec.mode und tools.exec.node auf den gezeigten Werten?
• Verwendet der Werkzeugaufruf exakt den freigegebenen absoluten Programmpfad?

Erweitere die Allowlist nicht pauschal auf eine Shell oder ein ganzes Verzeichnis. Dadurch würde aus einer einzelnen Diagnoseaktion eine wesentlich breitere Ausführungsfläche. Weitere Beispiele findest du in OpenClaw Approvals erklärt.

Kamera, Bildschirm und Vordergrundstatus diagnostizieren

Beginne bei Toolfehlern mit:

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw logs --follow

camera.* und screen.* sind auf iOS- und Android-Nodes an den Vordergrund gebunden. Meldet ein Aufruf NODE_BACKGROUND_UNAVAILABLE, öffne die Node-App sichtbar und wiederhole denselben Aufruf.

Ein Fehler wie CAMERA_PERMISSION_REQUIRED, SCREEN_PERMISSION_REQUIRED oder ein anderer *_PERMISSION_REQUIRED verweist dagegen auf lokale Betriebssystemrechte. Erteile am Node-Gerät nur die für die betroffene Capability erforderliche Berechtigung und teste denselben Aufruf erneut. Ein neuer Tunnel oder erneutes Pairing ändert diese Rechte nicht.

Wenn ein Linux-Node nach dem SSH-Logout verschwindet

openclaw node install richtet unter Linux einen benutzerbezogenen systemd-Dienst ein. Ohne Lingering kann dieser Dienst enden, sobald die letzte Login-Sitzung geschlossen wird.

Prüfe auf dem Linux-Node:

loginctl show-user "$USER" -p Linger

Lautet die Ausgabe Linger=no, aktiviere Lingering und starte den Node neu:

sudo loginctl enable-linger "$USER"
openclaw node restart

Melde dich anschließend ab und prüfe von einem anderen Rechner:

openclaw nodes status

Der Node sollte weiterhin verbunden sein. Betreibe nicht gleichzeitig einen benutzerbezogenen und einen systemweiten Dienst für dieselbe Node-Instanz.

Diagnoseleiter für weitere Fehler

Arbeite vom Gateway zum konkreten Aufruf:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>

Die allgemeinen Befehle prüfen Installation und Gateway. Die Node-Befehle grenzen den Fehler anschließend auf Verbindung, Capability oder Exec-Approval ein.

Halte Erwartung und tatsächliches Ergebnis getrennt fest: Der Node sollte beispielsweise camera.snap melden und einen Snapshot liefern. Fehlt schon camera.snap, liegt das Problem vor der Betriebssystemfreigabe. Ist die Capability vorhanden, aber der Aufruf meldet CAMERA_PERMISSION_REQUIRED, musst du am Gerät selbst weiterarbeiten.

Testaufbau zurückbauen

Entferne den Testeintrag vom Node:

openclaw approvals allowlist remove --node "Build Node" "/usr/bin/uname"
openclaw approvals get --node "Build Node"

Das Pattern /usr/bin/uname steht dabei als letztes Positionsargument und muss exakt dem beim add-Aufruf verwendeten Wert entsprechen. --node "Build Node" bindet den Rückbau an denselben Node; --agent <id> ist optional und wirkt ohne Angabe auf alle Agents (Standard *). Hast du den Eintrag zuvor gezielt für eine bestimmte Agent-ID angelegt, gib beim Entfernen dieselbe ID mit --agent <id> an. Die zweite Ausgabe darf /usr/bin/uname nicht mehr in der Allowlist des Nodes zeigen.

Falls du tools.exec nur für diesen Test auf „Build Node“ geroutet hast, stelle deine vorherige Exec-Konfiguration wieder her und starte den Gateway neu.

Beende einen interaktiv gestarteten CLI-Node mit Ctrl-C. Bei der SSH-Variante beendest du anschließend auch den Tunnel mit Ctrl-C.

Wenn du Tailscale Serve nicht weiter verwendest, setze den Modus auf off:

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

openclaw gateway restart
tailscale serve status

tailscale serve status darf danach keine von OpenClaw verwaltete Serve-Freigabe für den Gateway mehr zeigen. Der Tailscale-Dienst selbst kann weiterhin laufen, weil mode: "off" nur OpenClaws Serve- beziehungsweise Funnel-Verwaltung beendet.

Kernpunkte

Ein Remote Node erweitert einen zentralen Gateway um Fähigkeiten eines anderen Geräts. Tailscale Serve hält den Zugriff im Tailnet; ein SSH-Tunnel leitet den Loopback-Port gezielt weiter.

Ein erfolgreicher Verbindungsstatus reicht für Toolaufrufe nicht aus. Das Gerät muss gekoppelt sein, die Capability anbieten und die Gateway- sowie Exec-Freigaben erfüllen. Bei NODE_BACKGROUND_UNAVAILABLE, *_PERMISSION_REQUIRED und SYSTEM_RUN_DENIED führen deshalb jeweils andere Reparaturschritte zum Ziel.

Nach dem Test gehören Tunnel, nicht mehr benötigtes Serve und temporäre Allowlist-Einträge zurückgebaut. So bleibt der Node erreichbar, ohne daraus eine breit freigegebene Remote-Shell zu machen.