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)

Die Anmeldung läuft über den Device-Code-Flow — den Code auf einem beliebigen Gerät eingeben; der Browser-OAuth-Callback funktioniert im Container nicht.

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

Claude (Subscription)

Für Anthropic gibt es keinen Device-Code wie bei Codex. Stattdessen wird ein Setup-Token (claude setup-token) als Auth-Profil in OpenClaw hinterlegt. Das nutzt deine Subscription (nicht „extra usage”), gilt rund ein Jahr und liegt im OpenClaw-State (Volume pc_openclaw) — übersteht also Neustarts.

# 1) Token erzeugen (öffnet den Claude-Login; Ausgabe: sk-ant-oat01-…):
claude setup-token
 
# 2) Token in OpenClaw hinterlegen und als Default setzen:
openclaw models auth login --provider anthropic --method setup-token --set-default

pc-runtime setup (Backend „Claude”/„Hybrid”) führt Schritt 2 interaktiv aus und fragt den Token ab.

Unbeaufsichtigt (Container, Secret)

Der Token kommt per Option oder Umgebungsvariable — ein TTY wird nicht gebraucht:

# Token per Option — alternativ ANTHROPIC_SETUP_TOKEN in der .env setzen:
pc-runtime setup --claude-token sk-ant-oat01-…
 
# Auth-Profil für jeden registrierten Agenten:
pc-runtime setup --all-agents --claude-token sk-ant-oat01-…

OpenClaw verwaltet Auth-Profile pro Agent. Ohne --agent <id> (mehrfach angebbar, Default main) bzw. --all-agents bricht der Login auf Images mit mehreren Agenten ab („Multiple agents are configured …”).

Danach die Gateway neu starten

Ein bereits laufender Agent sieht das frische Profil nicht und meldet sonst No API key found for provider "anthropic":

docker compose restart

Nach dem Neustart kurz warten, bis die Gateway lauscht — sonst meldet doctor FEHLER: Gateway erreichbar … ECONNREFUSED, obwohl nur der Start noch läuft:

until docker compose exec -T openclaw-runtime openclaw gateway probe >/dev/null 2>&1; do sleep 3; done

Prüfen (erst nach dem Neustart aussagekräftig):

openclaw models auth list                   # Profil 'anthropic:setup-token' mit 'expires …'
openclaw models status                      # Default: anthropic/claude-opus-5
pc-runtime doctor --smoke                   # echter Modellaufruf

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   : Registrierte Agenten (N)
OK   : Smoke-Test Agent 'main'

Registrierte Agenten (N) listet alle registrierten Agenten auf (nicht nur main) — fehlt ein erwarteter Agent, fällt das hier sofort auf. 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 (<port> = GATEWAY_PORT, Default 18789):

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

Der #token=…-Anhang authentifiziert über den Gateway-Token aus .env. pc-runtime setup gibt diese URL am Ende fertig aus.

openclaw config set gateway.controlUi.allowedOrigins \
  '["http://localhost:<port>","http://127.0.0.1:<port>"]' --strict-json
# Für Zugriff von einem anderen Host dessen Origin zusätzlich aufnehmen.
docker compose restart

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