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 mit installierter OpenClaw-CLI für den Node,
• administrativen Zugriff auf den Gateway,
• einen gültigen Setup-Code oder eine oc-pair-URL aus dem Pairing-Ablauf des Gateways,
• für Tailscale eine installierte und angemeldete Tailscale-CLI auf beiden Geräten,
• aktiviertes HTTPS im Tailnet, wenn du Tailscale Serve verwendest.

Der Setup-Code beziehungsweise die oc-pair-URL ist für die initiale Kopplung bestimmt. Übergib diesen Wert nur an den erwarteten Node-Host und veröffentliche ihn nicht in gemeinsam genutzten Skripten oder Protokollen. Der Serienartikel OpenClaw SecretRef richtig einsetzen erläutert den sicheren Umgang mit dauerhaft gespeicherten Zugangsdaten.

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 einem bislang ungekoppelten Node-Host:

openclaw node run \
  --host <magicdns-host> \
  --port 443 \
  --display-name "Build Node" \
  --pair '<setup-code-or-oc-pair-url>'

Die installierte CLI belegt für openclaw node run die Optionen --host und --port. Ohne --no-tls verwendet der Node für diesen HTTPS-Endpunkt TLS. --pair akzeptiert laut aktueller CLI-Hilfe einen Setup-Code oder eine oc-pair-URL. Explizite Gateway-Optionen wie --host und --port haben Vorrang vor den Verbindungsangaben aus dem Pairing-Wert. Enthält deine Serve-URL einen Gateway-Kontextpfad, ergänze außerdem --context-path <pfad>.

Der Prozess bleibt im Vordergrund. Bei erreichbarem Gateway und gültigem Pairing-Wert sollte nun ein ausstehender Geräteantrag erscheinen. Bleibt er aus, prüfe tailscale status, tailscale serve status, Hostnamen, Port und gegebenenfalls den Kontextpfad.

Tailscale Serve hält den Endpunkt im Tailnet. Funnel ist für diesen privaten Aufbau nicht erforderlich: Es macht den HTTPS-Endpunkt öffentlich erreichbar und verlangt deshalb eine separate 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 einem bislang ungekoppelten Node-Host:

openclaw node run \
  --host 127.0.0.1 \
  --port 18790 \
  --no-tls \
  --display-name "Build Node" \
  --pair '<setup-code-or-oc-pair-url>'

Die Optionen --host, --port und --no-tls sind in der aktuellen Hilfe von openclaw node run ausdrücklich vorhanden. --no-tls ist hier erforderlich, weil der Node zunächst eine unverschlüsselte lokale WebSocket-Verbindung zum SSH-Tunnel aufbaut. SSH schützt den Transport zwischen Node-Host und Gateway-Host. Bei gültigem Pairing-Wert sollte diese Variante einen ausstehenden Geräteantrag am Gateway erzeugen.

Eine abgelehnte Verbindung spricht an dieser Stelle für einen geschlossenen Tunnel, einen nicht laufenden Gateway, einen falschen Port oder einen ungültigen Pairing-Wert. Sie ist noch kein Hinweis auf eine fehlende Node-Capability.

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>

Alternativ akzeptiert die aktuelle CLI openclaw devices approve --latest. Verwende diese Kurzform nur, wenn du unmittelbar zuvor geprüft hast, dass der zuletzt eingegangene Antrag tatsächlich zu deinem Node gehört.

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 und Pairing. Fehlt nur eine bestimmte Capability, helfen zusätzliche Exec-Freigaben nicht: Der Node stellt diese Fähigkeit dann nicht bereit.

Nach erfolgreicher Kopplung kannst du spätere Vordergrundstarts mit einem gespeicherten Geräte-Token ausführen. Soll nur bei fehlendem Token neu gekoppelt werden, bietet die CLI dafür --pair-if-needed <setup-code-or-oc-pair-url> an.

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 einen Systembefehl muss das konkrete Gerät gekoppelt und verbunden sein. Der Node muss außerdem system.run anbieten. Danach greifen die Exec-Einstellungen des Gateways und die Approvals auf dem Node-Host.

Die von nodes describe gemeldete Capability ist eine technische Voraussetzung, aber keine Ausführungsfreigabe. Ein Node kann system.run anbieten und einen konkreten Programmpfad trotzdem ablehnen, wenn dessen Approval fehlt.

Beschränke die Ausführung deshalb über tools.exec und eine kleine Allowlist auf dem Node. Das aktuelle Runtime-Schema belegt für diesen Ablauf tools.exec.host, tools.exec.mode und tools.exec.node. Dabei wählt tools.exec.host: "node" den Node als Ausführungsziel, tools.exec.mode: "allowlist" die restriktive Exec-Policy und tools.exec.node das konkrete Gerät. Die nicht im Runtime-Schema vorhandenen flachen Felder gateway.nodes.allowCommands und gateway.nodes.denyCommands werden dafür nicht verwendet.

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"

Die Beschreibung muss den Node als verbunden ausweisen und system.run unterstützen. Fehlt diese Capability, stoppe den Test an dieser Stelle.

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" richtet OpenClaw den Exec-Aufruf an einen Node. tools.exec.node: "Build Node" bindet ihn an dieses konkrete Gerät. 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 Aufruf system.run?
• 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 pending
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>

Die allgemeinen Befehle prüfen Installation und Gateway. nodes pending zeigt ausstehende Kopplungen. Die weiteren Node-Befehle grenzen den Fehler 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 selben Node und verwende exakt das beim Hinzufügen angegebene Pattern:

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

Der Remove-Aufruf erhält /usr/bin/uname als Positionsargument. Die anschließende Ausgabe darf für „Build Node“ keinen Allowlist-Eintrag mit diesem Pattern mehr zeigen. Falls du den Eintrag mit einem zusätzlichen --agent <id> angelegt hast, verwende beim Entfernen denselben Agent-Geltungsbereich.

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 ungekoppelter CLI-Node verwendet für beide Wege --pair mit einem gültigen Setup-Code oder einer oc-pair-URL. Die belegten Verbindungsoptionen --host und --port wählen das Ziel. Beim lokalen Ende eines SSH-Tunnels deaktiviert --no-tls TLS für diese lokale Verbindung.

Ein erfolgreicher Verbindungsstatus reicht für Toolaufrufe nicht aus. Das Gerät muss gekoppelt sein, die benötigte Capability anbieten und die Exec-Approvals des Node-Hosts erfüllen. Für die dauerhafte Weiterleitung von Exec-Aufrufen an das Gerät ist tools.exec.host: "node" der schema-konforme Ausführungspfad; tools.exec.node wählt bei mehreren Geräten das Ziel. Bei NODE_BACKGROUND_UNAVAILABLE, *_PERMISSION_REQUIRED und SYSTEM_RUN_DENIED führen deshalb unterschiedliche 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.