Support-Agent

Der Support-Agent ist ein zyklischer Agent, der wie ein First-Level-Support arbeitet: Er ruft alle 5 Minuten ungelesene E-Mails über IMAP ab, sucht die Antwort über die ProcessCube®-CLI (pc knowledge) und legt eine begründete Antwort standardmäßig als E-Mail-Entwurf zur Freigabe ab. Mit MAIL_SEND_MODE=send versendet er sie nach Prüfung der Wissensbasis direkt über SMTP. Findet er keine belastbare Antwort, startet er mit der Anfrage den Eskalations-Prozess in der Engine.

Der Support-Agent baut — wie die Coding-Agenten — auf der Agent Runtime auf und nutzt dasselbe Agenten-Image (Dockerfile.agents, FROM ${RUNTIME_IMAGE}). Es erbt das komplette OpenClaw-Setup (OpenClaw, Bun, Node, gh, pc, Claude, Codex, Volumes, Gateway-CMD); ergänzt werden nur Support-spezifische Teile: jq, der .processcube-Mountpoint, der knowledge-Skill, die Agent-Dateien, Cron und die Mail-Dependencies. Registriert wird über PC_INSTALL_AGENTS=support-agent nur der Support-Agent.

Antwort-Gate

Ohne ausreichend belegende Knowledge-Treffer antwortet der Agent nicht inhaltlich, sondern nennt die Dokumentationslücke — statt Details zu ergänzen oder eine Integration zu erfinden. Das gilt auch für normale Chatfragen an den Agenten.

Nur der E-Mail-Polling-Workflow ({ "_poll": true }) startet bei fehlender Antwort zusätzlich die Eskalation. Nach erfolgreichem Prozessstart legt der Agent eine Bestätigung an, dass die Anfrage an den Human-Support übergeben wurde — im Standardmodus ebenfalls als Entwurf.

Ablauf je Zyklus

1. mail.ts fetch — ungelesene Mails aus $INPUT_MAILBOX (IMAP, peek)
2. 2–4 Stichworte extrahieren → pc knowledge search --rerank -o json (cwd = $KNOWLEDGE_DIR); ohne --source werden alle konfigurierten Quellen durchsucht
3. Gate: keine brauchbaren Treffer → eskalieren. Lokale Treffer werden an der bm25-Rausch-Grenze (KNOWLEDGE_RANK_THRESHOLD) gemessen und mit pc knowledge show inhaltlich geprüft; Remote-Treffer lädt der Agent per pc knowledge show <id> --source <source> vollständig nach. source_errors einzelner Quellen gelten nicht als Fehlschlag der ganzen Suche.
4. Antwort: je nach MAIL_SEND_MODE via mail.ts draft oder mail.ts send (Betreff Antwort zu <Betreff>, Signatur „Viele Grüße / Ihr Support-Team”) → mail.ts move nach $DONE_MAILBOX
5. Keine Antwort: pc engine start-process-model Support-Escalation_Process startEskalation → mail.ts move nach $ESCALATED_MAILBOX

Der Agent liest nicht die INBOX, sondern nur den unter INPUT_MAILBOX konfigurierten Ordner — sonst würde er auf jede beliebige Mail (Newsletter, Benachrichtigungen …) reagieren. Bearbeitete Mails wandern nach $DONE_MAILBOX bzw. $ESCALATED_MAILBOX — das ist Audit-Trail und De-Dup zugleich.

Mail-Server-Setup (einmalig)

Der Transport ist für standardkonforme IMAP4-/SMTP-Server mit direktem TLS oder STARTTLS ausgelegt. Bei Gmail ist INPUT_MAILBOX typischerweise ein dediziertes Label, bei anderen IMAP-Servern ein normaler Ordner.

Die Ziel-Ordner aus DONE_MAILBOX und ESCALATED_MAILBOX müssen nicht vorab existieren — mail.ts move legt sie bei Bedarf an.

Start (lokales Compose)

Das Agenten-Image setzt auf dem Runtime-Image auf. Per Default zieht docker compose das veröffentlichte ghcr.io/processcube-io/agent-runtime:latest; alternativ einmalig lokal bauen:

docker compose build          # baut/taggt ghcr.io/processcube-io/agent-runtime:latest

Dann den Support-Agenten starten:

docker network create pc-shared          # einmalig (geteilt mit Engine/LowCode)
# .env: OPENCLAW_GATEWAY_TOKEN, MAIL_USER, MAIL_PASSWORD, ENGINE_URL …
docker compose -f docker-compose.support.yml up -d --build
docker compose -f docker-compose.support.yml exec support-agent bash
 
# Im Container, einmalig:
pc-runtime setup                          # AI-Backend (Claude-Subscription) anmelden
pc engine login "$ENGINE_URL" --root      # PoC: anonymer Root-Login

Die Agenten-Registrierung (pc-runtime agents install) legt den 5-Minuten-Cron support-agent-poll an.

Erste Freigabe & manuelles Auslösen

Beim ersten openclaw-CLI-Aufruf im Container fragt das Gateway eine Geräte-Freigabe an (Scope-Upgrade). Einmalig genehmigen, dann neu starten, damit das frische Auth-/Codex-Profil greift:

docker compose -f docker-compose.support.yml exec support-agent bash -lc '
  openclaw devices list                 # zeigt die pending Request-ID
  openclaw devices approve <request-id> # genehmigen
'
docker compose -f docker-compose.support.yml restart
docker compose -f docker-compose.support.yml exec support-agent pc-runtime doctor --smoke

Der Agent läuft alle 5 Minuten automatisch. Sofort auslösen (z. B. nach einer Test-Mail):

docker compose -f docker-compose.support.yml exec support-agent \
  openclaw cron run support-agent-poll

Liefert das {"reason":"already-running"}, läuft gerade noch ein Zyklus — kurz warten und erneut auslösen.

Control-UI freigeben

Bei einem frischen OpenClaw-Volume muss der lokale Browser-Origin einmalig freigegeben werden:

docker compose -f docker-compose.support.yml exec support-agent \
  openclaw config set gateway.controlUi.allowedOrigins \
  '["http://localhost:18790","http://127.0.0.1:18790"]' --strict-json
docker compose -f docker-compose.support.yml restart

Danach die UI mit dem Token aus der .env öffnen: http://localhost:18790/#token=<OPENCLAW_GATEWAY_TOKEN>.

Lokaler Test ohne Container

# im support-agent/-Ordner, einmalig:
bun install
# einen einzelnen Zyklus triggern (so wie der Cron):
node start.mjs

E2E-Test mit lokaler Engine

Für den Eskalationstest gibt es ein Compose-Overlay mit eigener Engine. Es seedet processes/Support-Escalation.bpmn und stellt die Engine dem Agenten unter http://support-engine:8000 bereit — vom Host zusätzlich unter http://localhost:8001:

docker network inspect pc-shared >/dev/null 2>&1 || docker network create pc-shared
docker compose -f docker-compose.support.yml \
  -f docker-compose.support-engine.yml up -d --build

Statt anonymem Root-Zugriff kann ein expliziter Token verwendet werden — er muss in der .env des Compose-Projekts stehen, damit Engine (iam__rootAccessToken) und Agent denselben Wert nutzen:

export ENGINE_ROOT_ACCESS_TOKEN="$(pc engine generate-root-access-token)"
export ENGINE_ALLOW_ANONYMOUS_ROOT_ACCESS=false
docker compose -f docker-compose.support.yml \
  -f docker-compose.support-engine.yml up -d --no-build

Für einen einzelnen Poll-Zyklus mit Warten auf das Endergebnis:

docker compose -f docker-compose.support.yml \
  -f docker-compose.support-engine.yml exec -T support-agent \
  openclaw cron run support-agent-poll --expect-final --timeout 120000

Prozessmodelle und Instanzen lassen sich aus dem Agent-Container prüfen:

docker compose -f docker-compose.support.yml \
  -f docker-compose.support-engine.yml exec -T support-agent \
  pc engine list-process-models
 
docker compose -f docker-compose.support.yml \
  -f docker-compose.support-engine.yml exec -T support-agent \
  pc engine list-process-instances

Eskalations-Start-Token

Prozessmodell-ID, Start-Event-ID und die Form des Start-Tokens richten sich nach dem Ziel-Prozessmodell. Die Feldnamen sind nicht fest verdrahtet: Der Start-Token entsteht aus dem jq-Ausdruck in ESCALATION_START_TOKEN_JQ, dem die Anfrage als Variablen $from, $subject, $body, $messageId und $receivedAt übergeben wird.

# Default — entspricht dem mitgelieferten processes/Support-Escalation.bpmn
ESCALATION_START_TOKEN_JQ={from:$from, subject:$subject, body:$body, messageId:$messageId, receivedAt:$receivedAt}

# Eigenes Prozessmodell mit anderen Feldnamen
ESCALATION_START_TOKEN_JQ={sender:$from, title:$subject, text:$body, channel:"mail"}

So lassen sich Felder umbenennen, verschachteln, weglassen oder um Konstanten ergänzen. Der Default entspricht dem bisherigen Verhalten.

Konfigurationsprüfung bei der Installation

pc-runtime agents install --from-repo . support-agent prüft vor der Registrierung die gesamte Konfiguration des Agenten — ohne Netzwerkzugriff, allein aus der Umgebung:

• Mail-Zugang inklusive GMAIL_*-Fallback
• IMAP-/SMTP-Ports mit ihrer TLS-/STARTTLS-Kombination
• MAIL_SEND_MODE samt der beim Versand nötigen Zugangsdaten und Absenderauflösung
• die Ordner aus INPUT_MAILBOX, DONE_MAILBOX, ESCALATED_MAILBOX
• die Wissensbasis: knowledge.config.json und die dort per --token-env referenzierten Umgebungsvariablen
• Engine sowie Eskalations-Prozess, Start-Event und Start-Token-Ausdruck (letzterer wird per jq probeweise ausgeführt)
• DOCS_BASE_URL

Befunde werden gemeldet, brechen die Installation aber nicht ab — eine Fehlkonfiguration soll die Registrierung nicht verhindern:

pc-runtime agents install --from-repo . support-agent                           # prüfen und melden
pc-runtime agents install --from-repo . support-agent --require-support-config   # bei Problemen abbrechen
pc-runtime agents install --from-repo . support-agent --skip-support-config      # Prüfung überspringen

Cron-Läufe einsehen

Jeder Cron-Lauf ist eine OpenClaw-Session. Die Control-UI zeigt die Sessions und Gesprächsverläufe, aber keine eigene Cron-Run-Tabelle — dafür ist die CLI die verlässliche Ansicht:

docker compose -f docker-compose.support.yml exec -T support-agent \
  openclaw cron runs --id support-agent-poll --limit 20 --json
 
docker compose -f docker-compose.support.yml exec -T support-agent \
  openclaw sessions list --agent support-agent --json

Mail-Werkzeug (lib/mail.ts)

Umgebungsvariablen

Mail

Ordner

Knowledge und Engine

Für Quellenlinks in E-Mails etwa DOCS_BASE_URL=https://docs.processcube.io setzen — produktiv gehört dort die für Kunden erreichbare Docs-URL hin.

Weiterführend

• Knowledge-Anbindung — mehrere lokale, Web- und API-/MCP-Quellen für den Agenten konfigurieren
• Knowledge-Befehle der CLI — pc knowledge im Detail
• Docker und Kubernetes / k3s — Betrieb