OpenClaw-Agenten aus ProcessCube® LowCode ansprechen

Mit dem Package @5minds/node-red-contrib-processcube-openclaw lassen sich KI-Agenten eines OpenClaw -Gateways direkt aus LowCode-Flows ansprechen: Nachricht an einen Agenten schicken, auf das Ergebnis warten, Antwort weiterverarbeiten. Dieser Artikel beschreibt das typische Setup OpenClaw auf dem Host, LowCode im Docker-Container — inklusive der Konfiguration von OpenClaw, Docker, Docker Compose und den Nodes selbst.

Architektur

Der OpenClaw-Gateway läuft als WebSocket-Server auf dem Host. LowCode (Node-RED) läuft im Container und verbindet sich als Client. Die Herausforderung: Der Gateway lauscht standardmäßig nur auf dem Loopback-Interface (127.0.0.1:18789), das aus dem Container heraus nicht direkt erreichbar ist.

Voraussetzungen

• OpenClaw installiert und konfiguriert auf dem Host (Installation )
• Docker und Docker Compose auf demselben Host
• socat auf dem Host (für die empfohlene Loopback-Variante): brew install socat (macOS) bzw. apt install socat (Linux)
• Das Package @5minds/node-red-contrib-processcube-openclaw im LowCode-Image

Die drei Nodes

Die Nodes übernehmen das vollständige Challenge-Response-Handshake-Protokoll des Gateways (Protocol v4) — es ist also kein selbstgebauter WebSocket-Code nötig.

1. OpenClaw-Gateway konfigurieren

Die Konfiguration liegt in ~/.openclaw/openclaw.json. Entscheidend sind Port, Bind-Modus und Auth-Token.

{
  gateway: {
    mode: "local",
    bind: "loopback",          // Default; sicher, nur lokal erreichbar
    port: 18789,
    auth: {
      token: "<dein-gateway-token>"
    }
  }
}

Das Token wird beim Onboarding automatisch generiert und steht unter gateway.auth.token. Es wird gleich in der Node-Config benötigt.

Nach Änderungen an Bind oder Port den Gateway neu starten:

openclaw gateway restart

2. Verbindung Container → Host herstellen

Hier gibt es drei Wege. Die Loopback-Variante mit socat ist die empfohlene — sie funktioniert auf macOS und Linux und vermeidet den Pairing-Aufwand.

# Auf dem Host starten — leitet 0.0.0.0:18790 auf den Loopback-Gateway weiter
socat TCP-LISTEN:18790,bind=0.0.0.0,reuseaddr,fork TCP:127.0.0.1:18789 &

services:
  lowcode:
    image: marketplace.processcube.io/processcube-io/processcube_lowcode:latest
    network_mode: host

# 1. Flow deployen — erster Connect meldet NOT_PAIRED
#    (deviceId steht in Fehlermeldung + Node-Log)
# 2. Auf dem Gateway-Host einmalig bestätigen:
openclaw devices list              # Anfrage steht auf "pending"
openclaw devices approve <requestId>

3. Docker Compose für LowCode

Für das Beispiel reicht ein schlankes Compose-Setup. Wichtig ist nur, dass der Container host.docker.internal auflösen kann.

services:
  lowcode:
    image: marketplace.processcube.io/processcube-io/processcube_lowcode:latest
    ports:
      - "1880:1880"
    environment:
      - NODERED_PORT=1880
      - NODERED_NAME=ProcessCube LowCode
      - NODERED_AUTH_DISABLED=true
    # Unter Linux nötig, damit host.docker.internal aufgelöst wird:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - lowcode_data:/data
 
volumes:
  lowcode_data:

Anschließend den Stack starten:

docker compose up -d

Der Editor ist unter http://localhost:1880 erreichbar.

4. Nodes konfigurieren

Gateway-Config

Lege zunächst eine Gateway-Konfiguration an (z.B. über den openclaw-message-send-Node beim Hinzufügen des Gateways):

Gateway URL und Token sind als TypedInput ausgeführt — neben dem festen Wert (str) lassen sie sich auch aus einer Umgebungsvariable (env, z.B. OPENCLAW_GATEWAY_URL / OPENCLAW_GATEWAY_TOKEN) oder einem verschlüsselten Credential (cred) beziehen. Gerade das Token gehört in Produktion nicht als Klartext in den Flow, sondern als env oder cred.

openclaw-message-send

Sendet msg.payload als Nachricht an einen Agenten.

Eingang:

• msg.payload (string | any) — die Nachricht an den Agenten. Strings werden direkt übergeben, andere Typen per JSON.stringify serialisiert.
• msg.sessionKey (optional) — zum Fortführen einer Konversation. Standard: agent:<agentId>:main.

Ausgang:

• msg.payload (string) — der Antworttext des Agenten (null bei deaktiviertem Wait for result)
• msg.sessionKey (string) — verwendeter Session-Key, z.B. agent:main:main
• msg.runId (string) — Run-ID des gestarteten Laufs; wird immer gesetzt

openclaw-agent-wait

Für asynchrone Flows: openclaw-message-send startet den Agenten mit deaktiviertem Wait for result, dieser Node wartet später auf das Ergebnis.

Eingang:

• msg.runId (string, Pflicht) — wird von openclaw-message-send automatisch gesetzt
• msg.sessionKey (optional) — zum Abrufen der Antwort; wird ebenfalls automatisch durchgereicht

Ausgang:

• msg.payload (string) — der Antworttext des Agenten

5. Beispiel-Flow

Der einfachste Flow schickt eine Frage an den Agenten und gibt die Antwort im Debug-Fenster aus:

[inject: "Wie ist die aktuelle Zeit?"]
  → [openclaw message-send: Agent=main, Wait for result=an]
  → [debug: msg.payload]

Soll der Agent asynchron arbeiten (z.B. in Human-in-the-Loop-Szenarien), trennt man Senden und Warten:

[inject: Aufgabe]
  → [openclaw message-send: Wait for result=aus]   // setzt msg.runId + msg.sessionKey
  → [... andere Verarbeitung ...]
  → [openclaw agent-wait]                           // wartet auf das Ergebnis
  → [debug: msg.payload]

6. Konkretes Beispiel: einen Coding-Agenten aus LowCode auslösen

Das Hello-World oben spricht den generischen main-Agenten an. Spannend wird es, wenn man fertige, spezialisierte Agenten ansteuert. Genau dafür gibt es das Paket ProcessCube Agents  (@processcube-io/agents): eine Sammlung von OpenClaw-Agenten für automatisiertes Coding via Pull Request. Der zentrale Agent heißt coding-agent und arbeitet als Orchestrator:

1. Er legt für die Aufgabe einen Draft-PR an (GitHub oder Azure DevOps — automatisch erkannt),
2. antwortet sofort mit sessionId und prUrl,
3. und startet im Hintergrund zwei Sub-Agenten: einen Worker, der den Task im Worktree implementiert, und einen PR-Watcher, der Review-Kommentare am PR abholt und an den Worker weiterleitet.

Das Schöne aus LowCode-Sicht: Es sind dieselben drei Nodes. Statt main adressiert man die Agent ID coding-agent und schickt statt einer Frage einen strukturierten Task.

Voraussetzungen

• Die ProcessCube-Agenten sind auf dem Gateway installiert. Am einfachsten über das fertige Image ghcr.io/processcube-io/agents, das alle Agenten inkl. gh, az, bun und der Coding-CLIs vorinstalliert mitbringt.
• gh (für GitHub) bzw. az (für Azure DevOps) sind auf dem Gateway authentifiziert.

Der Task-Payload

Der coding-agent erwartet ein JSON-Objekt. In LowCode baut man es z.B. in einem function-Node und legt es auf msg.payload — der openclaw-message-send-Node serialisiert Objekte automatisch per JSON.stringify:

// function-Node: Task für den coding-agent zusammenbauen
msg.payload = {
    schemaVersion: "0.1",
    task: {
        title: "Tippfehler im README beheben",
        description: "Im README.md steht 'Instalation' statt 'Installation'. Bitte korrigieren.",
    },
    repoUrl: "https://github.com/meine-org/mein-repo",
    reviewer: "mm@processcube.io",   // optional
};
return msg;

Der Flow

[inject / form: Task-Daten]
  → [function: Task-Payload bauen]
  → [openclaw message-send: Agent=coding-agent, Wait for result=an]
  → [json: msg.payload parsen]      // Antwort ist JSON-Text
  → [debug: msg.payload.prUrl]

Mit Wait for result = an wartet der Node nur auf die sofortige Antwort des Orchestrators — also auf { sessionId, prUrl }, sobald der Draft-PR steht. Das geht schnell. Die eigentliche Implementierung läuft danach unabhängig im Worker weiter; der PR-Watcher pollt den PR und reagiert auf Review-Kommentare, solange er offen ist. Der LowCode-Flow ist zu diesem Zeitpunkt also längst fertig und hat die PR-URL — z.B. zum Posten in einen Chat oder zum Fortführen eines BPMN-Prozesses.

Antwort verarbeiten

msg.payload enthält den Antworttext des Agenten als JSON-String:

{
  "sessionId": "5f3c…",
  "prUrl": "https://github.com/meine-org/mein-repo/pull/42"
}

Nach einem json-Node steht die PR-URL unter msg.payload.prUrl bereit — fertig für Benachrichtigung, Logging oder die nächste Flow-Node.

Stolperstein: Der Handshake

Der Gateway-WebSocket ist kein nackter Socket. Nach dem Verbindungsaufbau sendet der Gateway ein connect.challenge-Event; der Client muss daraufhin als erstes ein connect-Frame mit Protokollversion, Rolle, Scopes und Auth-Token senden. Erst danach folgt das hello-ok.

Die Nodes erledigen das intern und melden sich dabei mit der Client-Identität gateway-client / backend an — das ist genau die Identität, für die der Gateway bei Loopback-Verbindungen die Operator-Scopes erhält. Ein handgeschriebener WebSocket-Node würde hier am Handshake scheitern.

Troubleshooting

Fazit

Mit dem socat-Tunnel auf dem Loopback-Gateway entsteht ein robustes, sicheres Setup ohne Geräte-Pairing: Der Gateway bleibt auf 127.0.0.1 gebunden, der Container erreicht ihn über host.docker.internal, und die Nodes übernehmen Handshake und Authentifizierung. Damit lassen sich OpenClaw-Agenten als ganz normale Bausteine in LowCode-Flows einsetzen — von der einfachen Frage-Antwort bis zu asynchronen, prozessgesteuerten Agenten-Aufrufen. Und weil immer dieselben drei Nodes zum Einsatz kommen, ist der Sprung vom Hello-World zu einem spezialisierten Agenten wie dem coding-agent aus ProcessCube Agents  klein: andere Agent ID, strukturierter Payload — fertig.

Weiterführend

• OpenClaw Nodes Referenz — alle Felder, Ein- und Ausgänge der drei Nodes
• Was ist LowCode? — Einführung in die ProcessCube® LowCode-Plattform
• Starten mit Docker Compose — LowCode-Setup-Varianten
• Eigene Nodes entwickeln — Aufbau von Node-RED-Nodes
• ProcessCube Agents  — fertige Coding-Agenten (coding-agent, Worker, PR-Watcher) für GitHub und Azure DevOps
• OpenClaw Documentation  — Gateway, Auth und Bind-Modi