Agent Runtime

Die ProcessCube Agent Runtime ist ein generisches OpenClaw-Runtime-Image. Ein Entwickler aktiviert darin in ca. 15 Minuten ein AI-Backend per Subscription und kann anschließend aus ProcessCube® LowCode den Agenten main aufrufen — ohne lokale Installation.

Subscription statt Provider-API-Key: Das KI-Backend wird über den Subscription-Login (Claude- bzw. ChatGPT-Account) aktiviert — ein eigener Anthropic-/OpenAI-API-Key ist nicht nötig (nur optionaler Fallback). Davon unabhängig ist der OPENCLAW_GATEWAY_TOKEN — er sichert die Gateway-Verbindung, ist aber kein KI-Provider-Key.

In Entwicklung. Die Agent Runtime ist Teil der Preview-Phase (1.1.0-develop.x). Schnittstellen, Image-Tags und Verhalten können sich vor dem ersten Stable-Release noch ändern.

Die Coding-Agenten bauen auf genau diesem Runtime-Image auf (Dockerfile.agents) — die Runtime ist also die Grundlage, nicht ein separates Produkt.

Quick Start

Gemeinsames Docker-Netz anlegen

Die Compose referenziert pc-shared als externes Netz — ohne dieses Netz wird der Start abgelehnt:


docker network create pc-shared

`.env` mit echtem Token anlegen


# Platzhalter durch einen echten Zufalls-Token ersetzen:
sed "s|^OPENCLAW_GATEWAY_TOKEN=.*|OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)|" .env.example > .env

Container starten


docker compose up -d

Runtime einrichten und prüfen


docker compose exec openclaw-runtime bash
pc-runtime setup            # AI-Backend wählen, einloggen, Agent main konfigurieren
pc-runtime doctor --smoke   # kompletter Weg: Gateway + Auth + Backend + Agent main

Danach lässt sich aus LowCode per openclaw-message-send gegen Agent main an ws://<host>:18789 eine Antwort abrufen — mit demselben OPENCLAW_GATEWAY_TOKEN als Connect-Token.

Die ausführliche, geführte Einrichtung (inkl. Backend-Login, GitHub, Device-Pairing, Control-UI/TUI und typischen Fehlern) steht unter Erste Einrichtung.

Die Gateway bindet ans LAN und erzwingt Token-Auth. Ohne OPENCLAW_GATEWAY_TOKEN startet der Container nicht — und pc-runtime bricht bewusst ab, wenn der Platzhalter aus .env.example unverändert übernommen wurde.

`pc-runtime` — die eine CLI

Alle Runtime-Aufgaben laufen über pc-runtime (Bun-Single-Binary; bündelt auch den BPMN-zu-OpenClaw-Generator). Die Befehle sind in Gruppen organisiert:

Runtime & Setup

Befehl	Zweck
`pc-runtime setup`	AI-Backend wählen (Claude / Codex / Hybrid), Logins durchführen, Default-Modell von Agent `main` setzen — und am Ende `main` real aufrufen
`pc-runtime doctor`	Gesamtdiagnose (Gateway, Backends, Agenten, Engine-Plugin, Builder-Home)
`pc-runtime doctor --smoke`	Wie `doctor`, prüft zusätzlich den kompletten Weg mit einem echten Aufruf von Agent `main` (Gateway + Auth + Backend)
`pc-runtime version`	Versionen aller enthaltenen Werkzeuge

Builder (BPMN-zu-OpenClaw-Generator)

Befehl	Zweck
`pc-runtime builder install`	Builder-Agent in OpenClaw registrieren
`pc-runtime builder analyze <bpmn>`	Builder-Vorschlag + Bericht erzeugen (ohne Installation)
`pc-runtime builder create <bpmn>`	Volle Pipeline: analysieren + Lane-Agenten installieren

Agenten (die Quelle bestimmt den Pfad)

Befehl	Zweck
`pc-runtime agents install --from-repo <dir> [--all \| <agent>…]`	Repo-Agenten registrieren
`pc-runtime agents install <bpmn> --from-proposal <file>`	Lane-Agenten aus einem Builder-Proposal installieren
`pc-runtime agents update\|reinstall\|uninstall\|render\|show <bpmn>`	BPMN-Lane-Lebenszyklus
`pc-runtime agents uninstall <agent>…`	Repo-Agenten entfernen
`pc-runtime agents list`	Registrierte Agenten auflisten

Werkzeuge

Befehl	Zweck
`pc-runtime validate`	Schemas, Tool-Inventar und Proposals prüfen
`pc-runtime skills sync`	`<home>/tool-inventar/master.json` aktualisieren

Globale Flags: --output text\|json (bei doctor, version, plugin status), --dry-run, -q/--quiet, -v/--verbose, --home <pfad>, --skills-dir <pfad>. Exit-Codes: 0 = ok, 1 = fehlgeschlagen, 2 = Bedienfehler.

Engine-Plugin

Das ProcessCube-Engine-Plugin (@processcube/openclaw-engine-plugin) steckt bereits im Runtime-Image und wird bei jedem Container-Start automatisch registriert (ExternalTask-Worker + Engine-Events). Verbunden wird die Engine per plugin bind:


pc-runtime plugin bind --engine-url http://engine:10560 --token <root-access-token>
docker compose restart
pc-runtime plugin status       # erwartet: registriert + geladen + gebunden

Befehl	Zweck
`pc-runtime plugin install <pfad>`	Plugin registrieren (macht der Entrypoint automatisch)
`pc-runtime plugin bind --engine-url <url> [--token <t>]`	Engine-Verbindung setzen
`pc-runtime plugin status`	Registrierung + Laufzeit-Status

Die Prozess-Ebene (ExternalTask-Topics, Agent-Bindings, Event-Subscriptions) entsteht pro BPMN-Prozess über pc-runtime builder create <bpmn> bzw. pc-runtime agents install <bpmn>.

Konfiguration

Env-Variable	Pflicht	Beschreibung
`OPENCLAW_GATEWAY_TOKEN`	ja	Connect-Token der Gateway; denselben Wert gibt LowCode beim Connect mit
`GATEWAY_PORT`	nein	Host-Port der Gateway (Default `18789`; Container-intern bleibt `18789`). Setzen, wenn `18789` auf dem Host schon belegt ist
`GATEWAY_BIND_ADDR`	nein	Publish-Adresse des Ports (Default `0.0.0.0`); für reinen Lokalzugriff sicherer `127.0.0.1`
`OPENAI_API_KEY`	nein	API-Key-Fallback (Subscription bleibt der Primärweg)
`ANTHROPIC_API_KEY`	nein	API-Key-Fallback (Subscription bleibt der Primärweg)

Enthaltene Werkzeuge

OpenClaw (fester Release-Tag), Bun, Node, Git, GitHub CLI (gh), Claude Code, OpenAI Codex, ProcessCube CLI (pc), Python und uv.

Persistente Volumes

Subscription-Logins und OpenClaw-State bleiben über Neustarts erhalten — Secrets liegen ausschließlich in den Volumes, nie im Image:


/home/node/.openclaw   /home/node/.claude   /home/node/.codex
/home/node/.config/gh  /workspace

Anbindung aus einem eigenen Compose-Projekt

Eine ProcessCube-Engine in einem separaten Compose-Stack ist der Consumer und erreicht die Runtime auf zwei Wegen:

Veröffentlichter Port (18789): vom Host ws://localhost:18789, aus einem anderen Compose-Projekt (Docker Desktop) ws://host.docker.internal:18789 — kein gemeinsames Netz nötig.
Gemeinsames Docker-Netz pc-shared: Die Runtime-Compose hängt bereits am externen Netz pc-shared. Die Engine ans selbe Netz hängen, dann per Service-Namen erreichbar: ws://openclaw-runtime:18789.

docker-compose.yml (Engine-Stack)


services:
  engine:                 # bzw. node-red / der Service, der OpenClaw aufruft
    networks: [default, pc-shared]
networks:
  pc-shared:
    external: true

Als Connect-Token in beiden Fällen den Wert aus OPENCLAW_GATEWAY_TOKEN verwenden. Details siehe Erste Einrichtung.

Wie der Aufruf aus einem LowCode-Flow konkret aussieht (Gateway-Config, Token, openclaw-message-send), zeigt der Blog-Beitrag OpenClaw-Agenten aus ProcessCube® LowCode ansprechen.