Erste Einrichtung

Diese Anleitung führt durch die erste Einrichtung der ProcessCube Agent Runtime. Der Primärweg ist Subscription-basiert — API-Keys dienen nur als Fallback.

Voraussetzungen

• Docker und Docker Compose
• Zugriff auf das Runtime-Image
• ChatGPT-/OpenAI-Account für Codex, falls Codex genutzt wird
• Claude-Account für Claude Code, falls Claude genutzt wird
• GitHub-Account, falls Repositories bearbeitet werden sollen

1. Runtime starten

docker network create pc-shared

sed "s|^OPENCLAW_GATEWAY_TOKEN=.*|OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)|" .env.example > .env

docker compose up -d
docker compose exec openclaw-runtime bash

2. Versionen prüfen

pc-runtime version

Alternativ manuell: openclaw, bun, node, gh, codex, claude, pc, python3, uv jeweils mit --version.

3. Setup starten

pc-runtime setup

Das Setup fragt nach dem gewünschten Backend (mindestens eines ist Pflicht): Claude, Codex oder Hybrid. pc-runtime setup stößt die nötigen Logins an, setzt das Default-Modell von Agent main auf das gewählte Backend und ruft main am Ende real auf.

Die folgenden Abschnitte beschreiben, was dabei im Detail passiert bzw. wie es sich manuell nachvollziehen lässt.

Codex / OpenAI (Subscription)

openclaw models auth login --provider openai --set-default
openclaw models auth list
openclaw models status --plain

Claude (Subscription)

claude                          # interaktiven Login abschließen
openclaw models list            # passende anthropic/...-Modell-ID ermitteln
openclaw models set anthropic/<modell>

API-Key-Fallback (optional)

export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...

Für Docker Compose besser über .env oder Docker Secrets einbinden. Subscription bleibt der Primärweg.

GitHub anmelden

gh auth login
gh auth status

Gateway prüfen

openclaw doctor
openclaw devices list

Bei scope upgrade pending approval einmalig freigeben:

openclaw devices approve <request-id>

4. Doctor mit Smoke-Test

pc-runtime doctor --smoke

Zielzustand:

OK   : OpenClaw CLI
OK   : Gateway-Token
OK   : Gateway erreichbar
OK   : OpenClaw Auth-Profile lesbar
OK   : AI-Backend: Subscription aktiv
OK   : Workspace beschreibbar (/workspace)
OK   : Persistente Volumes vorhanden
OK   : Agent 'main' vorhanden
OK   : Smoke-Test Agent 'main'

Ein reiner API-Key-Fallback (ohne Subscription) erscheint als WARN : AI-Backend: nur API-Key-Fallback — kein Fehler, nur ein Hinweis.

5. Direkter Smoke-Test

Am einfachsten über pc-runtime doctor --smoke (führt den Aufruf gegen Agent main aus). Oder manuell:

openclaw agent \
  --agent main \
  --message "Antworte mit einem kurzen OK und nenne das aktive Modell." \
  --session-key "agent:main:smoke-test-001"

6. Test aus LowCode

In ProcessCube® LowCode mit dem openclaw-message-send-Node:

Test-Payload: { "message": "Antworte mit OK aus der ProcessCube Agent Runtime." }

Details zu Gateway-Config und Nodes: OpenClaw-Agenten aus ProcessCube® LowCode ansprechen.

ProcessCube-Engine anbinden

Die Engine (LowCode) ist nicht Teil der Runtime — sie ist der Consumer und verbindet sich von außen gegen die Gateway. Zwei Wege:

Weg 1 — veröffentlichter Host-Port (einfachster)

Die Runtime published 18789:

• vom Host: ws://localhost:18789
• aus einem Container in einem anderen Compose-Projekt (Docker Desktop): ws://host.docker.internal:18789

Kein gemeinsames Netz nötig; als Connect-Token den Wert aus OPENCLAW_GATEWAY_TOKEN verwenden.

Weg 2 — gemeinsames Docker-Netz (Container ↔ Container)

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.

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

Die Gateway bindet via --bind lan auf alle Interfaces und ist damit auch unter Service-Name/Container-IP erreichbar — der Host-Port wird hierfür nicht benötigt.

Mit dem Agenten chatten (Control UI / TUI)

Neben dem einmaligen openclaw agent-Aufruf lässt sich interaktiv mit Agent main chatten.

Control UI (Browser)

Die Gateway liefert die Control UI auf demselben Port aus:

http://localhost:<port>/#token=<OPENCLAW_GATEWAY_TOKEN>

Der #token=…-Anhang authentifiziert über den Gateway-Token. pc-runtime setup gibt diese URL am Ende fertig aus. Die Origins http://localhost:<port> und http://127.0.0.1:<port> werden beim Containerstart automatisch freigegeben. Für Zugriff von einem anderen Host dessen Origin ergänzen und die Gateway neu starten:

openclaw config set gateway.controlUi.allowedOrigins \
  '["http://localhost:<port>","http://<remote-host>:<port>"]' --strict-json

Terminal-UI

docker compose exec -it openclaw-runtime openclaw tui

Erster Connect: Device-Pairing freigeben

Interaktive Clients (TUI/Control UI) fordern beim ersten Connect erweiterte Scopes an und brechen zunächst ab (pairing required: …). Einmalig freigeben, dann den Client neu verbinden:

openclaw devices list
openclaw devices approve <request-id>

Typische Fehler