OpenClaw Nodes einrichten: Geräte in 5 Minuten verbinden

Ein Node ist ein Begleitgerät (macOS/iOS/Android/headless), das sich mit dem Gateway-WebSocket (gleicher Port wie Operatoren) über role: "node" verbindet und eine Befehlsoberfläche (z. B. canvas.*, camera.*, device.*, notifications.*, system.*) via node.invoke bereitstellt. Details zum Protokoll findest du hier: Gateway protocol.

Legacy-Transport: Bridge protocol (TCP JSONL; für aktuelle Nodes veraltet/entfernt).

macOS kann auch im Node-Modus laufen: Die Menüleisten-App verbindet sich mit dem WS-Server des Gateways und stellt ihre lokalen Canvas-/Kamera-Befehle als Node zur Verfügung (sodass openclaw nodes … gegen diesen Mac funktioniert).

Hinweise:

Nodes sind Peripheriegeräte, keine Gateways. Sie führen den Gateway-Service nicht aus.
Telegram/WhatsApp/etc. Nachrichten landen auf dem Gateway, nicht auf den Nodes.
Troubleshooting-Runbook: /nodes/troubleshooting

Kopplung + Status

WS-Nodes nutzen Device-Pairing. Nodes präsentieren beim connect eine Geräte-Identität; das Gateway erstellt eine Pairing-Anfrage für role: node. Du kannst diese über das CLI (oder die UI) bestätigen.

Schnelles CLI:

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

Wenn ein Node den Versuch mit geänderten Auth-Details (Rolle/Scopes/Public Key) wiederholt, wird die vorherige ausstehende Anfrage ersetzt und eine neue requestId erstellt. Führe openclaw devices list erneut aus, bevor du die Freigabe erteilst.

Hinweise:

nodes status markiert einen Node als gekoppelt, wenn seine Device-Pairing-Rolle node enthält.
node.pair.* (CLI: openclaw nodes pending/approve/reject) ist ein separater, Gateway-eigener Speicher für Node-Kopplungen; er blockiert den WS-connect-Handshake nicht.

Remote Node Host (system.run)

Nutze einen Node Host, wenn dein Gateway auf einer Maschine läuft und du möchtest, dass Befehle auf einer anderen ausgeführt werden. Das Modell kommuniziert weiterhin mit dem Gateway; das Gateway leitet exec-Aufrufe an den Node Host weiter, wenn host=node ausgewählt ist.

Was wo läuft

Gateway-Host: Empfängt Nachrichten, führt das Modell aus, routet Tool-Aufrufe.
Node-Host: Führt system.run/system.which auf der Node-Maschine aus.
Freigaben: Werden auf dem Node-Host über ~/.openclaw/exec-approvals.json erzwungen.

Hinweis zur Freigabe:

Freigabebasierte Node-Ausführungen binden den exakten Kontext der Anfrage.
Bei direkten Shell- oder Runtime-Dateiausführungen versucht OpenClaw zudem, einen konkreten lokalen Datei-Operanden zu binden und verweigert die Ausführung, falls sich diese Datei vor der Ausführung ändert.
Wenn OpenClaw nicht genau eine konkrete lokale Datei für einen Interpreter- oder Runtime-Befehl identifizieren kann, wird die freigabebasierte Ausführung abgelehnt, anstatt eine vollständige Runtime-Abdeckung vorzutäuschen. Nutze Sandboxing, separate Hosts oder eine explizite Trusted-Allowlist für umfassendere Interpreter-Semantiken.

Einen Node Host starten (Vordergrund)

Auf der Node-Maschine:

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

Remote Gateway via SSH-Tunnel (Loopback-Bindung)

Wenn das Gateway an Loopback gebunden ist (gateway.bind=loopback, Standard im lokalen Modus), können Remote Node Hosts keine direkte Verbindung herstellen. Erstelle einen SSH-Tunnel und richte den Node Host auf das lokale Ende des Tunnels aus.

Beispiel (Node-Host -> Gateway-Host):

# Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: export the gateway token and connect through the tunnel
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

Hinweise:

openclaw node run unterstützt Token- oder Passwort-Authentifizierung.
Umgebungsvariablen werden bevorzugt: OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD.
Config-Fallback ist gateway.auth.token / gateway.auth.password.
Im lokalen Modus ignoriert der Node Host absichtlich gateway.remote.token / gateway.remote.password.
Im Remote-Modus sind gateway.remote.token / gateway.remote.password gemäß den Remote-Präzedenzregeln zulässig.
Wenn aktive lokale gateway.auth.* SecretRefs konfiguriert, aber nicht aufgelöst sind, schlägt die Node-Host-Auth fehl.
Die Auth-Auflösung des Node Hosts berücksichtigt nur OPENCLAW_GATEWAY_* Umgebungsvariablen.

Einen Node Host starten (Service)

openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node restart

Koppeln + Benennen

Auf dem Gateway-Host:

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

Falls der Node den Versuch mit geänderten Auth-Details wiederholt, führe openclaw devices list erneut aus und bestätige die aktuelle requestId.

Optionen zur Benennung:

--display-name bei openclaw node run / openclaw node install (bleibt in ~/.openclaw/node.json auf dem Node gespeichert).
openclaw nodes rename --node <id|name|ip> --name "Build Node" (Gateway-Override).

Befehle auf die Allowlist setzen

Exec-Freigaben gelten pro Node Host. Füge Allowlist-Einträge vom Gateway aus hinzu:

openclaw approvals allowlist add --node &lt;id|name|ip&gt; "/usr/bin/uname"
openclaw approvals allowlist add --node &lt;id|name|ip&gt; "/usr/bin/sw_vers"

Die Freigaben liegen auf dem Node Host unter ~/.openclaw/exec-approvals.json.

Exec auf den Node ausrichten

Standardwerte konfigurieren (Gateway-Konfiguration):

openclaw config set tools.exec.host node
openclaw config set tools.exec.security allowlist
openclaw config set tools.exec.node "<id-or-name>"

Oder pro Session:

/exec host=node security=allowlist node=<id-or-name>

Sobald dies eingestellt ist, wird jeder exec-Aufruf mit host=node auf dem Node Host ausgeführt (vorbehaltlich der Node-Allowlist/Freigaben).

Verwandte Themen:

Befehle aufrufen

Low-Level (Raw RPC):

openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'

Es gibt High-Level-Helper für die gängigen Workflows, um dem Agenten einen MEDIA-Anhang zu übergeben.

Screenshots (Canvas Snapshots)

Wenn der Node den Canvas (WebView) anzeigt, gibt canvas.snapshot das Format und base64 zurück: { format, base64 }.

CLI-Helper (schreibt in eine temporäre Datei und gibt MEDIA:<path> aus):

openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

Canvas-Steuerung

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com
openclaw nodes canvas hide --node <idOrNameOrIp>
openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>
openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"

Hinweise:

canvas present akzeptiert URLs oder lokale Dateipfade (--target), plus optionale Parameter --x/--y/--width/--height für die Positionierung.
canvas eval akzeptiert Inline-JS (--js) oder ein positionales Argument.

A2UI (Canvas)

openclaw nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
openclaw nodes canvas a2ui reset --node <idOrNameOrIp>

Hinweise:

Es wird nur A2UI v0.8 JSONL unterstützt (v0.9/createSurface wird abgelehnt).

AI Setup Assistant

Fotos + Videos (Node-Kamera)

Fotos (jpg):

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # default: both facings (2 MEDIA lines)
openclaw nodes camera snap --node <idOrNameOrIp> --facing front

Videoclips (mp4):

openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

Hinweise:

Der Node muss im Vordergrund (foregrounded) sein für canvas.* und camera.* (Hintergrund-Aufrufe geben NODE_BACKGROUND_UNAVAILABLE zurück).
Die Clip-Dauer ist begrenzt (aktuell <= 60s), um zu große base64-Payloads zu vermeiden.
Android fragt nach CAMERA/RECORD_AUDIO Berechtigungen; abgelehnte Berechtigungen führen zu *_PERMISSION_REQUIRED.
Stelle sicher, dass die Hardware-Kamera nicht von einer anderen App blockiert wird, damit der Zugriff reibungslos funktioniert.

Bildschirmaufnahmen (Nodes)

Unterstützte Nodes bieten screen.record (mp4) an. Beispiel:

openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

Hinweise:

Die Verfügbarkeit von screen.record hängt von der jeweiligen Node-Plattform ab.
Bildschirmaufnahmen sind auf eine Dauer von <= 60s begrenzt.
--no-audio deaktiviert die Mikrofonaufnahme auf unterstützten Plattformen.
Nutze --screen <index>, um ein Display auszuwählen, falls mehrere Bildschirme vorhanden sind.

Standort (Nodes)

Nodes stellen location.get bereit, wenn der Standort in den Einstellungen aktiviert ist.

CLI-Helper:

openclaw nodes location get --node <idOrNameOrIp>
openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

Hinweise:

Standortdaten sind standardmäßig deaktiviert.
Die Option „Immer erlauben“ erfordert Systemberechtigungen; Abrufe im Hintergrund erfolgen nach dem Best-Effort-Prinzip.
Die Antwort enthält lat/lon, die Genauigkeit in Metern sowie einen Zeitstempel.
Nutze --location-timeout, um unnötige Wartezeiten bei schlechtem GPS-Signal zu verhindern.

SMS (Android-Nodes)

Android-Nodes können sms.send anbieten, wenn du die SMS-Berechtigung erteilst und das Gerät Telefonie unterstützt.

Low-Level-Aufruf:

openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'

Hinweise:

Die Berechtigungsanfrage muss auf dem Android-Gerät akzeptiert werden, bevor die Funktion vom System beworben wird.
Reine Wi-Fi-Geräte ohne Telefonie-Hardware bieten sms.send nicht an.

AI Setup Assistant

Android-Geräte + Befehle für persönliche Daten

Android-Nodes können zusätzliche Command-Families bereitstellen, sobald du die entsprechenden Capabilities aktivierst.

Diese Families sind verfügbar:

device.status, device.info, device.permissions, device.health
notifications.list, notifications.actions
photos.latest
contacts.search, contacts.add
calendar.events, calendar.add
callLog.search
sms.search
motion.activity, motion.pedometer

Beispiele für Invokes:

openclaw nodes invoke --node <idOrNameOrIp> --command device.status --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command notifications.list --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command photos.latest --params '{"limit":1}'

Hinweise:

Motion-Commands sind durch die jeweils verfügbaren Sensoren eingeschränkt.

Systembefehle (Node Host / Mac Node)

Der macOS-Node stellt system.run, system.notify sowie die Befehle system.execApprovals.get und system.execApprovals.set bereit. Der Headless Node Host bietet system.run, system.which sowie system.execApprovals.get und system.execApprovals.set an.

Beispiele:

openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"name":"git"}'

Hinweise:

system.run gibt den exit code zusammen mit den Streams stdout und stderr im Payload zurück.
Die Shell-Ausführung läuft jetzt über das exec Tool mit host=node. nodes bleibt die direkte RPC-Oberfläche für explizite Node-Befehle.
nodes invoke stellt weder system.run noch system.run.prepare bereit; diese Funktionen bleiben exklusiv auf dem Exec-Pfad.
system.notify berücksichtigt den Status der Benachrichtigungsberechtigungen in der macOS-App.
Unbekannte Metadaten für platform oder deviceFamily nutzen eine konservative Standard-Allowlist. Diese schließt system.run und system.which aus. Wenn du diese Befehle für eine unbekannte Plattform brauchst, füge sie explizit über gateway.nodes.allowCommands hinzu.
system.run unterstützt die Flags --cwd, --env KEY=VAL, --command-timeout und --needs-screen-recording.
Für Shell-Wrapper (wie bash oder zsh) mit den Flags -c oder -lc werden --env Werte

Exec-Node binden

Wenn du mehrere Nodes zur Verfügung hast, kannst du Exec fest an eine bestimmte Node binden. Das ist der beste Weg, um die Standard-Node für exec host=node festzulegen. Falls nötig, kannst du diese Einstellung für jeden Agent individuell überschreiben.

Globaler Standard:

openclaw config set tools.exec.node "node-id-or-name"

Überschreiben pro Agent:

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

Bindung aufheben, um jede Node zu erlauben:

openclaw config unset tools.exec.node
openclaw config unset agents.list[0].tools.exec.node

Permissions-Map

Nodes können eine permissions Map in node.list oder node.describe enthalten. Diese ist nach dem Namen der Berechtigung sortiert (z. B. screenRecording oder accessibility) und nutzt Boolean-Werte, wobei true für eine erteilte Berechtigung steht.

Headless Node-Host (plattformübergreifend)

Du kannst OpenClaw als Headless Node-Host ohne grafische Oberfläche betreiben. Dieser verbindet sich mit dem Gateway WebSocket und stellt die Funktionen system.run sowie system.which bereit. Das ist besonders nützlich für Linux- oder Windows-Systeme oder wenn du einen minimalen Node neben einem Server laufen lassen möchtest.

Starte den Host so:

openclaw node run --host <gateway-host> --port 18789

Hinweise:

Das Pairing ist weiterhin erforderlich (das Gateway zeigt eine Aufforderung zum Koppeln des Geräts an).
Der Node-Host speichert seine Node-ID, das Token, den Anzeigenamen und die Gateway-Verbindungsinfos in ~/.openclaw/node.json.
Freigaben für die Ausführung werden lokal über ~/.openclaw/exec-approvals.json gesteuert (siehe Exec approvals).
Unter macOS führt der Headless Node-Host system.run standardmäßig lokal aus. Setze OPENCLAW_NODE_EXEC_HOST=app, um system.run über den Exec-Host der Companion-App zu leiten. Mit OPENCLAW_NODE_EXEC_FALLBACK=0 erzwingst du den App-Host; die Ausführung schlägt dann fehl, falls dieser nicht verfügbar ist.
Nutze --tls / --tls-fingerprint, wenn der Gateway WS TLS verwendet.

Mac Node-Modus

Die macOS Menüleisten-App verbindet sich als Node mit dem Gateway WS-Server. Dadurch funktionieren Befehle wie openclaw nodes … direkt mit diesem Mac.
Im Remote-Modus öffnet die App einen SSH-Tunnel für den Gateway-Port und verbindet sich über localhost.

Nächste Schritte

AI Setup Assistant

OpenClaw Expert

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.