Log-Analyse & Debugging

Wenn ein Agent unerwartetes Verhalten zeigt, müssen Sie schnell die Ursache finden. OpenClaw bietet dafür einen Trace Explorer mit Step-by-Step-Replay — Sie sehen exakt, was der Agent in jedem Schritt gedacht und entschieden hat.

Trace Explorer

Der Trace Explorer ist das Herzstück des Debugging-Workflows:

Waterfall-Ansicht

Zeigt jeden Span chronologisch mit Timing:

[12:04:01.000] Trace Start: order-processing-agent
[12:04:01.012] ├── intent-classification       12ms   ✅
[12:04:01.024] ├── order-lookup                 89ms   ✅
[12:04:01.113] ├── inventory-check              45ms   ✅
[12:04:01.158] ├── price-calculation            23ms   ✅
[12:04:01.181] ├── llm-response-generation    1,203ms  ⚠️ (slow)
[12:04:02.384] ├── guardrail-check             140ms   ❌ (blocked)
[12:04:02.524] └── fallback-response             8ms   ✅

Prompt/Response-Inspektion

Für jeden LLM-Call können Sie einsehen:

System Prompt — Welche Anweisungen hatte der Agent?
User Input — Was war die Eingabe?
Context — Welche Dokumente/Daten waren im Kontext?
Raw Response — Was hat das LLM geantwortet?
Parsed Output — Wie hat der Agent die Antwort interpretiert?
Token-Zählung — Input/Output/Total mit Kosten

Step-by-Step Replay

Die Replay-Funktion lässt Sie eine Agent-Interaktion Schritt für Schritt nachvollziehen:

Klicken Sie auf einen Trace im Explorer
Wählen Sie "Replay" in der Toolbar
Navigieren Sie mit Vor/Zurück durch jeden Span
Sehen Sie den Zustand des Agents zu jedem Zeitpunkt (Memory, Context, Entscheidung)

Error Root Cause Analysis

OpenClaw kategorisiert Fehler automatisch:

Fehlertyp	Beschreibung	Häufige Ursache
LLM Timeout	API-Antwort nicht rechtzeitig	Überlastung, große Prompts
Rate Limit	API-Limit erreicht	Zu viele parallele Anfragen
Hallucination	Faktenprüfung fehlgeschlagen	Unzureichender Kontext
Guardrail Block	Ausgabe durch Policy blockiert	Toxischer/unsicherer Inhalt
Tool Failure	Externer Tool-Aufruf fehlgeschlagen	API down, falsche Parameter
Loop Detected	Agent in Endlosschleife	Fehlende Abbruchbedingung
Alignment Drift	Score unter Schwellenwert	Prompt-Degradation über Zeit

Automatische Korrelation

OpenClaw korreliert Fehler automatisch:

Zeitlich: Welche Fehler treten gehäuft auf?
Kausal: Welcher Span hat den Fehler ausgelöst?
Agent-übergreifend: Betrifft der Fehler mehrere Agents?

Debugging-Workflow

Der empfohlene Debugging-Ablauf:

Alert erhalten — OpenClaw meldet anomales Verhalten
Trace identifizieren — Betroffene Traces über Filter finden
Waterfall analysieren — Wo im Ablauf tritt das Problem auf?
Prompt inspizieren — Was sieht der Agent? Was antwortet das LLM?
Root Cause bestimmen — Kontext-Problem? Prompt-Problem? Tool-Problem?
Fix deployen — Prompt anpassen, Tool reparieren, Guardrail aktualisieren

Praxis-Tipp: Nutzen Sie die Bookmark-Funktion, um interessante Traces zu speichern. So bauen Sie über die Zeit eine Bibliothek typischer Fehlermuster auf, die neuen Team-Mitgliedern beim Onboarding hilft.