OpenClaw Debugging Guide

Du kennst das: Dein Code läuft ohne Fehlermeldung durch, aber das Ergebnis im Chat ist völlig unbrauchbar. Du fragst dich, ob das Model halluziniert oder ob deine Filter die Antwort verfälschen. Statt blind Parameter zu ändern, musst du sehen, was im Hintergrund wirklich passiert.

Wenn etwas kaputtgeht, brauchst du Fakten über den tatsächlichen Datenfluss, nicht Vermutungen darüber, was passieren sollte. Diese Tools helfen dir, den Raw Model Output zu inspizieren und schnelle Iterationszyklen aufzubauen, ohne deine Produktionsumgebung zu gefährden.

Voraussetzungen

• commands.debug: true in deiner Config
• pnpm als Paketmanager

Schnellstart

1. Nutze /debug show im Chat, um deine aktuellen Overrides zu prüfen.
2. Starte den Gateway mit pnpm gateway:watch --force, damit er bei jeder Dateiänderung automatisch neu lädt.

Runtime Debug Overrides

Mit dem /debug Befehl im Chat änderst du Konfigurationen sofort, ohne Dateien anzupassen. Das ist perfekt, um schnell verschiedene Präfixe oder Einstellungen zu testen.

/debug show                                    # Aktuelle Overrides anzeigen
/debug set messages.responsePrefix="[test]"    # Wert setzen
/debug unset messages.responsePrefix           # Override entfernen
/debug reset                                   # Alle Overrides löschen

Diese Einstellungen bleiben nur im Arbeitsspeicher und werden nicht dauerhaft gespeichert. Du musst dafür commands.debug: true in deiner Config aktiviert haben.

Gateway Watch Mode

Für eine schnelle Entwicklung empfehle ich den Watch Mode. Der Gateway startet automatisch neu, sobald du eine Datei speicherst:

pnpm gateway:watch --force

Das entspricht diesem Befehl:

tsx watch src/entry.ts gateway --force

Dev Profile (Isolierter Status)

Nutze ein Dev Profile, um deine Debugging-Sessions strikt von deinem Produktionsstatus zu trennen. Das verhindert, dass Testdaten deine echten Datenbanken oder Configs verschmutzen.

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

Das Dev Profile bewirkt folgendes:

• State-Verzeichnis wird auf ~/.openclaw-dev gesetzt
• Gateway nutzt Port 19001
• BOOTSTRAP.md wird übersprungen
• Eine minimale Standard-Config wird erstellt
• Standard-Identität ist C3-PO (Protocol Droid)
• Channel Provider werden übersprungen

Falls du komplett von vorne anfangen willst, setzt dieser Befehl alles zurück:

pnpm gateway:dev:reset

Dabei werden Dev-Config, Credentials und Sessions gelöscht (nutzt trash, nicht rm).

Raw Stream Logging

Wenn du wissen willst, ob Reasoning-Inhalte in den normalen Text-Output leaken, ist Raw Stream Logging der beste Weg. Du siehst exakt, was das Model zurückgibt, bevor Filter greifen:

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

Standardmäßig findest du die Logs hier: ~/.openclaw/logs/raw-stream.jsonl. Du kannst aber auch einen eigenen Pfad definieren:

pnpm gateway:watch --force --raw-stream --raw-stream-path /custom/path.jsonl

Alternativ nutzt du Umgebungsvariablen:

OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

Raw Chunk Logging (pi-mono)

Um OpenAI-kompatible Chunks vor dem Parsing abzufangen, nutzt du diese Variablen:

PI_RAW_STREAM=1
PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl

Environment Variable Reference

Variable	Beschreibung
OPENCLAW_PROFILE=dev	Nutzt das Dev Profile
OPENCLAW_STATE_DIR=~/.openclaw-dev	Überschreibt das State-Verzeichnis
OPENCLAW_GATEWAY_PORT=19001	Überschreibt den Gateway Port
OPENCLAW_RAW_STREAM=1	Aktiviert Raw Stream Logging
OPENCLAW_SKIP_CHANNELS=1	Überspringt Channel Provider

Fehlerbehebung

• Sicherheit: Raw Stream Logs können Prompts, Tool-Outputs und Nutzerdaten enthalten.
• Speicherort: Speichere Logs nur lokal und lösche sie nach dem Debugging.
• Datenschutz: Entferne Secrets und PII (persönlich identifizierbare Informationen), bevor du Logs teilst.

Du kommst nicht weiter? Unser AI Setup Assistant hilft dir beim Debugging deines Setups.

Nächste Schritte

• Logging → — File-Logs und Console-Output
• Testing → — Test-Suites und Live-Testing
• Gateway Configuration → — Vollständige Config-Referenz