Nodes

Ein Node ist ein Begleitgerät (macOS/iOS/Android/headless), das sich mit dem Gateway WebSocket (gleicher Port wie Operators) verbindet, dabei role: "node" verwendet und eine Befehlsoberfläche (z. B. canvas.*, camera.*, system.*) über node.invoke bereitstellt. Protokolldetails: Gateway-Protokoll.

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

macOS kann auch im Node-Modus laufen: Die Menüleisten-App verbindet sich mit dem WS-Server des Gateway und stellt ihre lokalen Canvas/Kamera-Befehle als Node bereit (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 Nodes.

Pairing + Status

WS-Nodes nutzen Device-Pairing. Nodes präsentieren während connect eine Geräteidentität; das Gateway erstellt eine Device-Pairing-Anfrage für role: node. Genehmige sie über die Devices-CLI (oder UI).

Schnelle CLI-Befehle:

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

Hinweise:

  • nodes status markiert einen Node als paired, wenn seine Device-Pairing-Rolle node enthält.
  • node.pair.* (CLI: openclaw nodes pending/approve/reject) ist ein separater, vom Gateway verwalteter Node-Pairing-Store; er blockiert nicht den WS-connect-Handshake.

Remote Node Host (system.run)

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

Was läuft wo

  • 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.
  • Approvals: werden auf dem Node Host über ~/.openclaw/exec-approvals.json durchgesetzt.

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-Bind)

Wenn das Gateway an Loopback bindet (gateway.bind=loopback, Standard im Local-Modus), können Remote-Node-Hosts nicht direkt verbinden. Erstelle einen SSH-Tunnel und richte den Node Host auf das lokale Ende des Tunnels aus.

Beispiel (Node Host → Gateway Host):

# Terminal A (laufen lassen): leite lokalen Port 18790 weiter → Gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: exportiere das Gateway-Token und verbinde durch den Tunnel
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

Hinweise:

  • Das Token ist gateway.auth.token aus der Gateway-Config (~/.openclaw/openclaw.json auf dem Gateway Host).
  • openclaw node run liest OPENCLAW_GATEWAY_TOKEN für die Authentifizierung.

Node Host starten (Service)

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

Pairing + Benennung

Auf dem Gateway Host:

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes list

Benennungsoptionen:

  • --display-name bei openclaw node run / openclaw node install (wird 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-Approvals gelten pro Node Host. Füge Allowlist-Einträge vom Gateway aus hinzu:

openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"

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

Exec auf den Node ausrichten

Konfiguriere Standardwerte (Gateway-Config):

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 gesetzt, läuft jeder exec-Aufruf mit host=node auf dem Node Host (unterliegt der Node-Allowlist/Approvals).

Verwandte Themen:

Befehle aufrufen

Low-Level (Raw RPC):

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

Höhere Helfer existieren für die gängigen “gib dem Agent ein MEDIA-Attachment”-Workflows.

Screenshots (Canvas Snapshots)

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

CLI-Helfer (schreibt in eine Temp-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 --x/--y/--width/--height für die Positionierung.
  • canvas eval akzeptiert Inline-JS (--js) oder ein positionelles 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:

  • Nur A2UI v0.8 JSONL wird unterstützt (v0.9/createSurface wird abgelehnt).

Fotos + Videos (Node-Kamera)

Fotos (jpg):

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # Standard: beide Ausrichtungen (2 MEDIA-Zeilen)
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 für canvas.* und camera.* im Vordergrund sein (Hintergrundaufrufe geben NODE_BACKGROUND_UNAVAILABLE zurück).
  • Die Clip-Dauer ist begrenzt (aktuell <= 60s), um überdimensionierte Base64-Payloads zu vermeiden.
  • Android fordert bei Bedarf CAMERA/RECORD_AUDIO-Berechtigungen an; verweigerte Berechtigungen schlagen mit *_PERMISSION_REQUIRED fehl.

Bildschirmaufnahmen (Nodes)

Nodes stellen screen.record (mp4) bereit. Beispiel:

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

Hinweise:

  • screen.record erfordert, dass die Node-App im Vordergrund ist.
  • Android zeigt vor der Aufnahme die System-Bildschirmaufnahme-Aufforderung an.
  • Bildschirmaufnahmen sind auf <= 60s begrenzt.
  • --no-audio deaktiviert die Mikrofonaufnahme (unterstützt auf iOS/Android; macOS nutzt System-Capture-Audio).
  • Nutze --screen <index>, um ein Display auszuwählen, wenn mehrere Bildschirme verfügbar sind.

Standort (Nodes)

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

CLI-Helfer:

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

Hinweise:

  • Standort ist standardmäßig deaktiviert.
  • “Immer” erfordert Systemberechtigung; Hintergrund-Fetch ist Best-Effort.
  • Die Antwort enthält Lat/Lon, Genauigkeit (Meter) und Zeitstempel.

SMS (Android Nodes)

Android Nodes können sms.send bereitstellen, wenn der Nutzer die SMS-Berechtigung erteilt und das Gerät Telefonie unterstützt.

Low-Level-Invoke:

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

Hinweise:

  • Die Berechtigungsaufforderung muss auf dem Android-Gerät akzeptiert werden, bevor die Fähigkeit angekündigt wird.
  • Nur-WLAN-Geräte ohne Telefonie kündigen sms.send nicht an.

Systembefehle (Node Host / Mac Node)

Der macOS Node stellt system.run, system.notify und system.execApprovals.get/set bereit. Der Headless Node Host stellt system.run, system.which und system.execApprovals.get/set bereit.

Beispiele:

openclaw nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"

Hinweise:

  • system.run gibt stdout/stderr/Exit-Code im Payload zurück.
  • system.notify respektiert den Benachrichtigungsberechtigungsstatus in der macOS-App.
  • system.run unterstützt --cwd, --env KEY=VAL, --command-timeout und --needs-screen-recording.
  • system.notify unterstützt --priority <passive|active|timeSensitive> und --delivery <system|overlay|auto>.
  • macOS Nodes verwerfen PATH-Overrides; Headless Node Hosts akzeptieren PATH nur, wenn es dem Node Host PATH vorangestellt wird.
  • Im macOS Node-Modus wird system.run durch Exec-Approvals in der macOS-App gesteuert (Einstellungen → Exec Approvals). Ask/Allowlist/Full verhalten sich wie beim Headless Node Host; abgelehnte Prompts geben SYSTEM_RUN_DENIED zurück.
  • Beim Headless Node Host wird system.run durch Exec-Approvals (~/.openclaw/exec-approvals.json) gesteuert.

Exec Node Binding

Wenn mehrere Nodes verfügbar sind, kannst du Exec an einen bestimmten Node binden. Das setzt den Standard-Node für exec host=node (und kann pro Agent überschrieben werden).

Globaler Standard:

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

Pro-Agent-Override:

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

Zurücksetzen, um jeden 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 / node.describe enthalten, mit Berechtigungsnamen als Schlüssel (z. B. screenRecording, accessibility) und booleschen Werten (true = erteilt).

Headless Node Host (plattformübergreifend)

OpenClaw kann einen Headless Node Host (ohne UI) ausführen, der sich mit dem Gateway WebSocket verbindet und system.run / system.which bereitstellt. Das ist nützlich auf Linux/Windows oder zum Betrieb eines minimalen Node neben einem Server.

Starten:

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

Hinweise:

  • Pairing ist weiterhin erforderlich (das Gateway zeigt eine Node-Approval-Aufforderung an).
  • Der Node Host speichert seine Node-ID, Token, Display-Name und Gateway-Verbindungsinfo in ~/.openclaw/node.json.
  • Exec-Approvals werden lokal über ~/.openclaw/exec-approvals.json durchgesetzt (siehe Exec Approvals).
  • Auf macOS bevorzugt der Headless Node Host den Companion-App-Exec-Host, wenn erreichbar, und fällt auf lokale Ausführung zurück, wenn die App nicht verfügbar ist. Setze OPENCLAW_NODE_EXEC_HOST=app, um die App zu erfordern, oder OPENCLAW_NODE_EXEC_FALLBACK=0, um Fallback zu deaktivieren.
  • Füge --tls / --tls-fingerprint hinzu, wenn das Gateway WS TLS nutzt.

Mac Node-Modus

  • Die macOS-Menüleisten-App verbindet sich mit dem Gateway WS-Server als Node (sodass openclaw nodes … gegen diesen Mac funktioniert).
  • Im Remote-Modus öffnet die App einen SSH-Tunnel für den Gateway-Port und verbindet sich mit localhost.