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 die Claude-CLI dateibasiert angemeldet und OpenClaw daran gebunden („CLI reuse”). Das nutzt deine Subscription (nicht „extra usage”); der Login persistiert in ~/.claude/.credentials.json (Volume pc_claude) und übersteht Neustarts.

# 1) Claude-CLI anmelden (URL öffnen, anmelden, Code einfügen):
claude auth login
 
# 2) OpenClaw an die Claude-CLI binden und als Default setzen:
openclaw models auth login --provider anthropic --method cli --set-default

Prüfen:

claude auth status                          # loggedIn: true
openclaw models list --provider anthropic   # claude-Modelle sichtbar
pc-runtime doctor --smoke

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