Nodes

Ein Node ist ein Begleitgerät (macOS/iOS/Android/headless), das sich per WebSocket mit dem Gateway verbindet (gleicher Port wie Operatoren) mit role: "node" und eine Befehlsoberfläche (z. B. canvas.*, camera.*, device.*, notifications.*, 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 Gateways und stellt ihre lokalen Canvas-/Kamerabefehle als Node bereit (sodass openclaw nodes … gegen diesen Mac funktioniert).

Hinweise:

Nodes sind Peripheriegeräte, keine Gateways. Sie betreiben nicht den Gateway-Dienst.
Telegram/WhatsApp/etc. Nachrichten landen auf dem Gateway, nicht auf Nodes.
Fehlerbehebungs-Runbook: /nodes/troubleshooting

Kopplung und Status

WS-Nodes verwenden Gerätekopplung. Nodes präsentieren beim connect eine Geräteidentität; das Gateway erstellt eine Gerätekopplungsanfrage für role: node. Genehmige sie über die Geräte-CLI (oder UI).

Schnelle CLI:

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 gekoppelt, wenn seine Gerätekopplungsrolle node enthält.
node.pair.* (CLI: openclaw nodes pending/approve/reject) ist ein separater, Gateway-eigener Node-Kopplungsspeicher; er kontrolliert nicht den WS-connect-Handshake.

Remote-Node-Host (system.run)

Verwende einen Node-Host, wenn dein Gateway auf einem Rechner läuft und du Befehle auf einem 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 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.
Genehmigungen: werden auf dem Node-Host über ~/.openclaw/exec-approvals.json durchgesetzt.

Hinweis zu Genehmigungen:

Genehmigungs-gestützte Node-Runs binden exakten Anfrage-Kontext.
Für direkte Shell-/Runtime-Dateiausführungen bindet OpenClaw nach bestem Bemühen auch einen konkreten lokalen Dateioperanden und verweigert den Run, wenn sich diese Datei vor der Ausführung ändert.
Wenn OpenClaw für einen Interpreter-/Runtime-Befehl nicht genau eine konkrete lokale Datei identifizieren kann, wird die genehmigungs-gestützte Ausführung verweigert, anstatt volle Runtime-Abdeckung vorzutäuschen. Nutze Sandboxing, separate Hosts oder eine explizite vertrauenswürdige Allowlist/vollständigen Workflow für breitere Interpreter-Semantik.

Einen Node-Host starten (Vordergrund)

Auf der Node-Maschine:

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

Remote-Gateway über SSH-Tunnel (Loopback-Bind)

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

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

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

# Terminal B: Gateway-Token exportieren und durch den Tunnel verbinden
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-Prioritätsregeln zulässig.
Wenn aktive lokale gateway.auth.* SecretRefs konfiguriert, aber nicht aufgelöst sind, schlägt die Node-Host-Authentifizierung geschlossen fehl.
Legacy-CLAWDBOT_GATEWAY_*-Umgebungsvariablen werden von der Node-Host-Auth-Auflösung absichtlich ignoriert.

Einen Node-Host starten (Dienst)

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

Koppeln und benennen

Auf dem Gateway-Host:

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

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

Allowlist der Befehle

Exec-Genehmigungen sind 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"

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

Exec auf den Node richten

Standardwerte konfigurieren (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 Sitzung:

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

Einmal gesetzt, läuft jeder exec-Aufruf mit host=node auf dem Node-Host (gemäß der Node-Allowlist/Genehmigungen).

Verwandte Themen:

Befehle ausführen

Low-Level (rohes RPC):

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

Für die gängigen „gib dem Agent einen MEDIA-Anhang”-Workflows gibt es übergeordnete Helfer.

Screenshots (Canvas-Snapshots)

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

CLI-Helfer (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 --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 Richtungen (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 im Vordergrund sein für canvas.* und camera.* (Hintergrundaufrufe geben NODE_BACKGROUND_UNAVAILABLE zurück).
Clip-Dauer ist begrenzt (aktuell <= 60s), um überdimensionierte Base64-Payloads zu vermeiden.
Android fragt wenn möglich nach CAMERA/RECORD_AUDIO-Berechtigungen; verweigerte Berechtigungen schlagen mit *_PERMISSION_REQUIRED fehl.

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:

screen.record-Verfügbarkeit hängt von der Node-Plattform ab.
Bildschirmaufnahmen sind auf <= 60s begrenzt.
--no-audio deaktiviert die Mikrofonaufnahme auf unterstützten Plattformen.
Verwende --screen <index>, um bei mehreren Bildschirmen einen Display auszuwählen.

Standort (Nodes)

Nodes bieten location.get an, 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 aus.
„Immer” erfordert eine Systemberechtigung; Hintergrund-Abruf erfolgt nach bestem Bemühen.
Die Antwort enthält Breite/Länge, Genauigkeit (Meter) und Zeitstempel.

SMS (Android-Nodes)

Android-Nodes können sms.send anbieten, wenn der Benutzer 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 Berechtigungsabfrage muss auf dem Android-Gerät akzeptiert werden, bevor die Fähigkeit angeboten wird.
Reine WLAN-Geräte ohne Telefonie bieten sms.send nicht an.

Android-Geräte- und persönliche Datenbefehle

Android-Nodes können zusätzliche Befehlsfamilien anbieten, wenn die entsprechenden Fähigkeiten aktiviert sind.

Verfügbare Familien:

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

Beispiel-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-Befehle sind durch verfügbare Sensoren beschränkt.

Systembefehle (Node-Host / Mac-Node)

Der macOS-Node bietet system.run, system.notify und system.execApprovals.get/set an. Der Headless-Node-Host bietet system.run, system.which und system.execApprovals.get/set an.

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.
Nicht erkannte Node-platform-/deviceFamily-Metadaten verwenden eine konservative Standard-Allowlist, die system.run und system.which ausschließt. Wenn du diese Befehle für eine unbekannte Plattform benötigst, füge sie explizit über gateway.nodes.allowCommands hinzu.
system.run unterstützt --cwd, --env KEY=VAL, --command-timeout und --needs-screen-recording.
Für Shell-Wrapper (bash|sh|zsh ... -c/-lc) werden anfragespezifische --env-Werte auf eine explizite Allowlist reduziert (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
Bei Allow-Always-Entscheidungen im Allowlist-Modus persistieren bekannte Dispatch-Wrapper (env, nice, nohup, stdbuf, timeout) die inneren ausführbaren Pfade statt Wrapper-Pfade. Wenn das Unwrapping nicht sicher ist, wird kein Allowlist-Eintrag automatisch persistiert.
Auf Windows-Node-Hosts im Allowlist-Modus erfordern Shell-Wrapper-Runs über cmd.exe /c eine Genehmigung (Allowlist-Eintrag allein erlaubt die Wrapper-Form nicht automatisch).
system.notify unterstützt --priority <passive|active|timeSensitive> und --delivery <system|overlay|auto>.
Node-Hosts ignorieren PATH-Überschreibungen und entfernen gefährliche Startup-/Shell-Schlüssel (DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4). Wenn du zusätzliche PATH-Einträge brauchst, konfiguriere die Node-Host-Dienstumgebung (oder installiere Tools an Standardorten), statt PATH über --env zu übergeben.
Im macOS-Node-Modus wird system.run durch Exec-Genehmigungen in der macOS-App geschützt (Einstellungen → Exec-Genehmigungen). Ask/Allowlist/Full verhalten sich wie beim Headless-Node-Host; abgelehnte Eingabeaufforderungen geben SYSTEM_RUN_DENIED zurück.
Auf dem Headless-Node-Host wird system.run durch Exec-Genehmigungen geschützt (~/.openclaw/exec-approvals.json).

Exec-Node-Bindung

Wenn mehrere Nodes verfügbar sind, kannst du Exec an einen bestimmten Node binden. Dies 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 zuzulassen:

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

Berechtigungsübersicht

Nodes können eine permissions-Map in node.list / node.describe enthalten, nach Berechtigungsname geordnet (z. B. screenRecording, accessibility) mit booleschen Werten (true = erteilt).

Headless-Node-Host (plattformübergreifend)

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

Starten:

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

Hinweise:

Kopplung ist weiterhin erforderlich (das Gateway zeigt eine Gerätekopplungsabfrage an).
Der Node-Host speichert seine Node-ID, Token, Anzeigename und Gateway-Verbindungsinfo in ~/.openclaw/node.json.
Exec-Genehmigungen werden lokal über ~/.openclaw/exec-approvals.json durchgesetzt (siehe Exec-Genehmigungen).
Auf 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 Begleit-App zu routen; füge OPENCLAW_NODE_EXEC_FALLBACK=0 hinzu, um den App-Host zu erzwingen und bei Nichtverfügbarkeit geschlossen fehlzuschlagen.
Füge --tls / --tls-fingerprint hinzu, wenn das Gateway-WS TLS verwendet.

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.