OpenClaw Nodes Referenz

Diese Referenz dokumentiert die Nodes des Pakets @5minds/node-red-contrib-processcube-openclaw. Mit ihnen lassen sich KI-Agenten eines OpenClaw -Gateways direkt aus Node-RED-Flows ansprechen — Nachricht senden, auf das Ergebnis warten, Antwort weiterverarbeiten.

Die Nodes erscheinen in der Palette unter der Kategorie ProcessCube OpenClaw und uebernehmen das vollstaendige Challenge-Response-Handshake-Protokoll des Gateways (Protocol v4) — handgeschriebener WebSocket-Code ist nicht noetig.

Das typische Setup (OpenClaw auf dem Host, LowCode im Docker-Container) inkl. Gateway-Konfiguration, socat-Tunnel und Beispiel-Flows ist im Blog-Beitrag OpenClaw-Agenten aus ProcessCube® LowCode ansprechen ausfuehrlich beschrieben.

openclaw-gateway-config

Kategorie: Konfiguration

Die zentrale Konfigurationsnode fuer die Verbindung zum OpenClaw-Gateway. Sie wird von openclaw-message-send und openclaw-agent-wait referenziert.

Eigenschaft	Typ	Beschreibung
Name	String	Bezeichnung der Konfiguration (z.B. `OpenClaw localhost`)
Gateway URL	`str` / `env` / `cred`	WebSocket-URL des Gateways. Default `ws://127.0.0.1:18789`. In Docker ueber `host.docker.internal`, z.B. `ws://host.docker.internal:18790` (via socat-Tunnel)
Token	`str` / `env` / `cred`	Shared-Secret aus `~/.openclaw/openclaw.json` unter `gateway.auth.token`
Device-Pairing (LAN)	Boolean	Opt-in fuer direkten LAN-/Remote-Zugriff (`bind: lan`). Fuer Loopback/socat nicht noetig. Default aus

Gateway-URL und Token sind als TypedInput ausgefuehrt: str (fester Wert), env (Umgebungsvariable, z.B. OPENCLAW_GATEWAY_URL / OPENCLAW_GATEWAY_TOKEN) oder cred (verschluesseltes Credential).

Device-Pairing fuer LAN-/Remote-Zugriff

Bei Loopback-Verbindungen (auch via socat-Tunnel) sieht der Gateway eine 127.0.0.1-Verbindung und gibt die Operator-Scopes automatisch frei — Pairing ist dann nicht noetig. Lauscht der Gateway dagegen mit bind: lan auf einer privaten IP, verlangt er eine gepairte Geraete-Identitaet; sonst kommt missing scope: operator.write.

Mit aktiviertem Device-Pairing:

Der Node erzeugt einmalig ein Ed25519-Schluesselpaar (persistent im Node-RED-userDir, Datei openclaw-device-<nodeId>.json) und signiert damit den Handshake.
Beim ersten Verbindungsversuch meldet der Gateway NOT_PAIRED; Fehlermeldung und Node-Log nennen die deviceId.
Auf dem Gateway-Host einmalig bestaetigen: openclaw devices list → openclaw devices approve <requestId>.
Danach verbindet sich der Node dauerhaft ohne weitere Bestaetigung.

ws:// zu privaten IPs (inkl. host.docker.internal, Tailnet) ist erlaubt; fuer verschluesselten Transport ueber unsichere Netze wss:// (TLS via Reverse-Proxy/Tailscale) verwenden.

openclaw-message-send

Kategorie: ProcessCube OpenClaw

Sendet msg.payload als Nachricht an einen OpenClaw-Agenten und liefert optional den Antworttext zurueck.

Konfiguration:

Eigenschaft	Typ	Default	Beschreibung
Gateway	Config	—	Referenz auf `openclaw-gateway-config` (Pflicht)
Agent ID	String	`main`	ID des angesprochenen Agenten
Thinking	Auswahl	`medium`	Denk-Intensitaet: `off`, `low`, `medium`, `high`
Wait for result	Boolean	aktiv	Wenn aktiv, wartet der Node bis der Agent fertig ist und liefert den Antworttext. Fuer asynchrone Flows deaktivieren und `openclaw-agent-wait` nutzen

Input (msg):

Property	Typ	Beschreibung
`msg.payload`	String \| any	Nachricht an den Agenten. Strings werden direkt uebergeben, andere Typen per `JSON.stringify` serialisiert
`msg.sessionKey`	String	(optional) Session-Key zum Fortfuehren einer Konversation. Standard: `agent:<agentId>:main`

Output (msg):

Property	Typ	Beschreibung
`msg.payload`	String	Antworttext des Agenten. `null` wenn Wait for result deaktiviert
`msg.sessionKey`	String	Verwendeter Session-Key, z.B. `agent:main:main`
`msg.runId`	String	Run-ID des gestarteten Laufs. Wird immer gesetzt — auch bei deaktiviertem Wait for result — und kann an `openclaw-agent-wait` weitergereicht werden

Der Session-Key folgt dem Format agent:<agentId>:main. Dieser „Main-Session-Key” legt bei Bedarf automatisch eine neue Session an. Ein zufaelliger Schluessel wuerde mit session not found quittiert.

openclaw-agent-wait

Kategorie: ProcessCube OpenClaw

Wartet auf den Abschluss eines OpenClaw-Agenten-Runs und liefert den Antworttext. Typischer Einsatz: openclaw-message-send startet den Agenten mit deaktiviertem Wait for result, dieser Node wartet spaeter asynchron auf das Ergebnis (z.B. in Human-in-the-Loop-Szenarien).

Konfiguration:

Eigenschaft	Typ	Beschreibung
Gateway	Config	Referenz auf `openclaw-gateway-config` (Pflicht)

Input (msg):

Property	Typ	Beschreibung
`msg.runId`	String	Run-ID des laufenden Agenten (Pflicht). Wird von `openclaw-message-send` automatisch gesetzt
`msg.sessionKey`	String	(optional) Session-Key zum Abrufen der Antwort. Wird von `openclaw-message-send` automatisch durchgereicht

Output (msg):

Property	Typ	Beschreibung
`msg.payload`	String	Antworttext des Agenten. `null` wenn kein `sessionKey` vorhanden
`msg.sessionKey`	String	Unveraenderter Session-Key

Allgemeine Hinweise

Gateway-Konfiguration

Alle OpenClaw Nodes verwenden die openclaw-gateway-config Node, um die Verbindung zum Gateway herzustellen. Konfigurieren Sie diese einmal und waehlen Sie sie in den Flow-Nodes aus.

Loopback statt Pairing

Verbindungen, die der Gateway als von 127.0.0.1 kommend sieht, werden automatisch mit den Operator-Scopes freigegeben (kein Geraete-Pairing). In Docker erreicht man das ueber einen socat-Tunnel auf den Loopback-Gateway — siehe Blog-Beitrag.

Fehlerbehandlung

Alle Nodes unterstuetzen die Standard-Node-RED-Fehlerbehandlung ueber Catch Nodes. Im Fehlerfall (z.B. WebSocket error, missing scope: operator.write, session not found) wird der Fehler ueber done(err) gemeldet.