Debugging in OpenClaw

Kennst du das? Du arbeitest an einer Integration und der Stream verhält sich merkwürdig. Manchmal mischt der Provider Reasoning-Inhalte direkt in den Text oder die Verbindung bricht ohne klare Fehlermeldung ab. Die Fehlersuche in Echtzeit-Streams ist oft frustrierend, wenn du nicht genau siehst, was unter der Haube passiert.

Wenn du versuchst, obscure Konfigurationsfehler zu finden, ohne ständig Dateien manuell zu editieren, brauchst du direkten Zugriff auf die Interna. Hier erfährst du, wie du den Datenstrom zerlegst und isolierte Umgebungen für Tests nutzt.

Voraussetzungen

• Installiertes pnpm
• openclaw CLI
• Zugriff auf deine openclaw.json
• Ein aktives Gateway-Setup

Schnellstart

Hier ist der schnellste Weg, um mit dem Debugging zu starten:

1. Debug-Befehle erlauben: Setze commands.debug: true in deiner Config.
2. Watch-Mode starten: Nutze pnpm gateway:watch --force für automatische Restarts.
3. Live-Anpassung: Nutze /debug set direkt im Chat für temporäre Änderungen.
4. Rohdaten prüfen: Starte das Gateway mit --raw-stream, um den ungefilterten Output zu sehen.

Runtime Debug Overrides

Mit dem Befehl /debug im Chat kannst du Konfigurationen ändern, die nur im Arbeitsspeicher existieren. Das ist ideal, um Einstellungen zu testen, ohne die openclaw.json auf der Festplatte zu verändern. Beachte, dass dies standardmäßig deaktiviert ist.

Beispiele für die Nutzung:

/debug show
/debug set messages.responsePrefix="[openclaw]"
/debug unset messages.responsePrefix
/debug reset

Der Befehl /debug reset löscht alle temporären Overrides und kehrt zur Konfiguration auf der Festplatte zurück.

Gateway Watch Mode

Für schnelle Iterationen kannst du das Gateway mit einem File-Watcher ausführen. Jede Änderung am Code löst einen Neustart aus:

pnpm gateway:watch --force

Das entspricht intern diesem Befehl:

tsx watch src/entry.ts gateway --force

Alle CLI-Flags, die du nach gateway:watch anfügst, werden bei jedem Neustart an das Gateway durchgereicht.

Dev-Profil und Dev-Gateway (—dev)

Nutze das Dev-Profil, um den Status zu isolieren und ein sicheres Setup zum Experimentieren aufzubauen. Es gibt zwei verschiedene --dev Flags:

• Globales --dev (Profil): Isoliert den Status unter ~/.openclaw-dev und setzt den Gateway-Port auf 19001.
• gateway --dev: Weist das Gateway an, eine Standard-Config und einen Workspace automatisch zu erstellen, falls diese fehlen.

Der empfohlene Workflow für eine isolierte Umgebung:

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

Das bewirkt Folgendes:

1. Profil-Isolation: Nutzt ~/.openclaw-dev/openclaw.json und setzt OPENCLAW_GATEWAY_PORT=19001.
2. Dev-Bootstrap: Erstellt eine Minimal-Config (gateway.mode=local) und überspringt die BOOTSTRAP.md.
3. Workspace-Files: Erzeugt Dateien wie AGENTS.md, SOUL.md, TOOLS.md und USER.md automatisch.
4. Standard-Identität: Setzt die Identität auf C3-PO (Protokolldroide).

Falls du komplett neu starten willst, löscht dieser Befehl die Config, Credentials und Sessions (via trash):

pnpm gateway:dev:reset

Raw Stream Logging

Um zu sehen, ob das Reasoning als Plain Text oder in speziellen Thinking-Blocks ankommt, kannst du den Raw Assistant Stream loggen. Dies geschieht, bevor Filter oder Formatierungen angewendet werden.

Aktivierung via CLI:

pnpm gateway:watch --force --raw-stream

Optional kannst du den Pfad anpassen:

pnpm gateway:watch --force --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl

Die Standarddatei findest du unter ~/.openclaw/logs/raw-stream.jsonl.

Raw Chunk Logging (pi-mono)

Wenn du die rohen OpenAI-kompatiblen Chunks sehen willst, bevor sie in Blöcke geparst werden, nutzt du den Logger von pi-mono:

PI_RAW_STREAM=1

Der Standardpfad dafür ist ~/.pi-mono/logs/raw-openai-completions.jsonl. Dies funktioniert nur bei Prozessen, die den openai-completions Provider von pi-mono nutzen.

Fehlerbehebung

• Gateway blockiert: Wenn ein Nicht-Dev-Gateway bereits läuft (z. B. via systemd), stoppe es zuerst mit openclaw gateway stop.
• Flag wird ignoriert: Manche Runner verschlucken das --dev Flag. Nutze in diesem Fall die Umgebungsvariable: OPENCLAW_PROFILE=dev openclaw gateway --dev --reset.
• Sicherheit: Raw Logs enthalten vollständige Prompts, Tool-Outputs und User-Daten.
• Datenhygiene: Lösche Logs nach dem Debugging und entferne Secrets oder PII, bevor du Logs teilst.

AI Setup Assistant

Nächste Schritte

• Gateway Configuration
• CLI Reference