Fehlerbehebung

Debugging-Hilfen für Streaming-Ausgabe, Gateway-Iterationen und Startprofilierung.

Laufzeit-Debug-Überschreibungen

/debug legt ausschließlich zur Laufzeit geltende Konfigurationsüberschreibungen fest (im Arbeitsspeicher, nicht auf dem Datenträger). Standardmäßig deaktiviert; aktivieren Sie sie mit commands.debug: true.

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

/debug reset löscht alle Überschreibungen und kehrt zur Konfiguration auf dem Datenträger zurück.

Sitzungs-Trace-Ausgabe

/trace zeigt Plugin-eigene Trace-/Debug-Zeilen für eine Sitzung an, ohne den vollständigen ausführlichen Modus zu aktivieren. Verwenden Sie dies für Plugin-Diagnosen wie Debug-Zusammenfassungen von Active Memory; verwenden Sie /verbose für normale Status-/Werkzeugausgaben.

/trace/trace on/trace off

Plugin-Lebenszyklus-Trace

Setzen Sie OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1, um eine phasenweise Aufschlüsselung von Plugin-Metadaten, Erkennung, Registry, Laufzeitspiegelung, Konfigurationsänderungen und Aktualisierungsvorgängen zu erhalten. Die Ausgabe erfolgt auf stderr, damit JSON-Befehlsausgaben weiterhin geparst werden können.

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"

Verwenden Sie dies, bevor Sie einen CPU-Profiler einsetzen. Messen Sie aus einem Quellcode-Checkout nach pnpm build die gebaute Laufzeit mit node dist/entry.js ...; pnpm openclaw ... misst zusätzlich den Overhead des Quellcode-Runners.

CLI-Start- und Befehlsprofilierung

Eingecheckte Start-Benchmarks:

pnpm test:startup:bench:smokepnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

Setzen Sie für eine einmalige Profilierung über den normalen Quellcode-Runner OPENCLAW_RUN_NODE_CPU_PROF_DIR:

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

Der Quellcode-Runner fügt Node-Flags für CPU-Profile hinzu und schreibt eine .cpuprofile-Datei für den Befehl. Verwenden Sie dies, bevor Sie dem Befehlscode temporäre Instrumentierung hinzufügen.

Fügen Sie bei Startblockaden, die wie synchrone Dateisystem- oder Modullader-Vorgänge aussehen, das Node-Trace-Flag für synchrone E/A über den Quellcode-Runner hinzu:

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch lässt dieses Flag für den überwachten untergeordneten Gateway-Prozess standardmäßig deaktiviert; setzen Sie OPENCLAW_TRACE_SYNC_IO=1, wenn Sie die Trace-Ausgabe für synchrone E/A auch im Überwachungsmodus benötigen.

Gateway-Überwachungsmodus

pnpm gateway:watch

Standardmäßig startet oder startet dies eine tmux-Sitzung namens openclaw-gateway-watch-<profile> neu (zum Beispiel openclaw-gateway-watch-main), wobei ein Port-Suffix wie openclaw-gateway-watch-dev-19001 nur hinzugefügt wird, wenn OPENCLAW_GATEWAY_PORT vom Standardport 18789 abweicht. Bei interaktiven Terminals wird die Sitzung automatisch angehängt; nicht interaktive Shells, CI und Agent-Ausführungsaufrufe bleiben getrennt und geben stattdessen Anweisungen zum Anhängen aus:

tmux attach -t openclaw-gateway-watch-main

Der tmux-Bereich führt den direkten Watcher aus:

node scripts/watch-node.mjs gateway --force

Beenden Sie einen installierten Gateway-Dienst, bevor Sie denselben Port überwachen:

pnpm openclaw gateway stop

Das --force des Watchers entfernt den aktuellen Listener, deaktiviert jedoch keinen überwachten Dienst. Ein launchd-, systemd- oder Scheduled Task-Dienst kann andernfalls erneut gestartet werden und den überwachten Gateway ersetzen.

Vordergrundmodus ohne tmux:

pnpm gateway:watch:raw# oderOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

Behalten Sie die tmux-Verwaltung bei, deaktivieren Sie jedoch das automatische Anhängen:

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

Profilieren Sie die CPU-Zeit des überwachten Gateways, wenn Sie Start-/Laufzeit-Hotspots debuggen:

pnpm gateway:watch --benchmark

Der Überwachungs-Wrapper verarbeitet --benchmark, bevor er den Gateway aufruft, und schreibt beim Beenden jedes untergeordneten Gateway-Prozesses ein V8-.cpuprofile unter .artifacts/gateway-watch-profiles/. Beenden oder starten Sie den überwachten Gateway neu, um das aktuelle Profil zu schreiben, und öffnen Sie es anschließend mit Chrome DevTools oder Speedscope:

npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile

• --benchmark-dir <path>: Profile an einem anderen Ort schreiben.
• --benchmark-no-force: Die standardmäßige Port-Bereinigung mit --force überspringen und sofort fehlschlagen, wenn der Gateway-Port bereits verwendet wird.

Der Benchmark-Modus unterdrückt standardmäßig die Flut von Trace-Ausgaben für synchrone E/A. Setzen Sie OPENCLAW_TRACE_SYNC_IO=1 zusammen mit --benchmark, um sowohl CPU-Profile als auch Stack-Traces für synchrone E/A zu erhalten; im Benchmark-Modus werden diese Trace-Blöcke in gateway-watch-output.log im Benchmark-Verzeichnis geschrieben (und aus dem Terminalbereich herausgefiltert), während normale Gateway-Protokolle sichtbar bleiben.

Der tmux-Wrapper überträgt gängige, nicht geheime Laufzeitauswahlen in den Bereich, darunter OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT und OPENCLAW_SKIP_CHANNELS. Speichern Sie Provider-Anmeldedaten in Ihrem normalen Profil bzw. Ihrer normalen Konfiguration oder verwenden Sie den direkten Vordergrundmodus für einmalige kurzlebige Geheimnisse.

Wenn der überwachte Gateway während des Starts beendet wird, führt der Watcher einmal openclaw doctor --fix --non-interactive aus und startet den untergeordneten Gateway-Prozess neu. Setzen Sie OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0, um den ursprünglichen Startfehler ohne den ausschließlich für die Entwicklung vorgesehenen Reparaturdurchlauf anzuzeigen.

Der verwaltete tmux-Bereich verwendet standardmäßig farbige Gateway-Protokolle; setzen Sie beim Starten von pnpm gateway:watch FORCE_COLOR=0, um ANSI-Ausgaben zu deaktivieren.

Der Watcher startet bei buildrelevanten Dateien unter src/, Quelldateien von Erweiterungen, den Metadaten package.json und openclaw.plugin.json von Erweiterungen, tsconfig.json, package.json und tsdown.config.ts neu. Änderungen an Erweiterungsmetadaten starten den Gateway neu, ohne einen Rebuild zu erzwingen; Quellcode- und Konfigurationsänderungen bauen weiterhin zuerst dist neu.

Fügen Sie Gateway-CLI-Flags nach gateway:watch hinzu; sie werden bei jedem Neustart durchgereicht. Das erneute Ausführen desselben Überwachungsbefehls startet den benannten tmux-Bereich neu; der direkte Watcher verwendet eine Sperre für einen einzelnen Watcher, sodass doppelte übergeordnete Watcher ersetzt werden, statt sich anzusammeln.

Entwicklungsprofil + Entwicklungs-Gateway (--dev)

Zwei separate --dev-Flags:

• Globales --dev (Profil): isoliert den Zustand unter ~/.openclaw-dev und setzt den Gateway-Port standardmäßig auf 19001 (abgeleitete Ports verschieben sich entsprechend).
• gateway --dev: weist den Gateway an, bei fehlender Konfiguration automatisch eine Standardkonfiguration und einen Arbeitsbereich zu erstellen (und den Bootstrap zu überspringen).

Empfohlener Ablauf (Entwicklungsprofil + Entwicklungs-Bootstrap):

pnpm gateway:devOPENCLAW_PROFILE=dev openclaw tui

Führen Sie die CLI ohne globale Installation über pnpm openclaw ... aus.

Dies bewirkt Folgendes:

1. Profilisolierung (globales --dev)

   • OPENCLAW_PROFILE=dev
   • OPENCLAW_STATE_DIR=~/.openclaw-dev
   • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
   • OPENCLAW_GATEWAY_PORT=19001 (Browser-/Canvas-Ports verschieben sich entsprechend)

2. Entwicklungs-Bootstrap (gateway --dev)

   • Schreibt bei Bedarf eine minimale Konfiguration (gateway.mode=local, Bindung an Loopback).
   • Setzt agents.defaults.workspace auf den Entwicklungsarbeitsbereich und agents.defaults.skipBootstrap=true.
   • Legt bei Bedarf die Arbeitsbereichsdateien an: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md.
   • Standardidentität: C3-PO (Protokolldroide).
   • pnpm gateway:dev setzt außerdem OPENCLAW_SKIP_CHANNELS=1, um Kanal-Provider zu überspringen.

Zurücksetzungsablauf (Neustart mit leerem Zustand):

pnpm gateway:dev:reset

--reset entfernt Konfiguration, Anmeldedaten, Sitzungen und den Entwicklungsarbeitsbereich (in den Papierkorb verschoben, nicht gelöscht) und erstellt anschließend die standardmäßige Entwicklungsumgebung neu.

Protokollierung des Rohdatenstreams

OpenClaw kann den unverarbeiteten Assistentenstream vor jeglicher Filterung/Formatierung protokollieren. Damit lässt sich am besten erkennen, ob Reasoning als einfache Text-Deltas (oder als separate Denkblöcke) eintrifft.

Über die CLI aktivieren:

pnpm gateway:watch --raw-stream

Optionale Pfadüberschreibung:

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

Entsprechende Umgebungsvariablen:

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

Standarddatei: ~/.openclaw/logs/raw-stream.jsonl

Sicherheitshinweise

• Rohdatenstream-Protokolle können vollständige Prompts, Werkzeugausgaben und Benutzerdaten enthalten.
• Bewahren Sie Protokolle lokal auf und löschen Sie sie nach dem Debugging.
• Wenn Sie Protokolle weitergeben, entfernen Sie vorher Geheimnisse und personenbezogene Daten.

Debugging in VSCode

Source Maps sind erforderlich, da der Build generierte Dateinamen mit Hashes versieht. Die enthaltene launch.json ist auf den Gateway-Dienst ausgerichtet:

1. Rebuild and Debug Gateway - löscht /dist und erstellt vor dem Starten des Gateways einen neuen Build mit aktiviertem Debugging.
2. Debug Gateway - debuggt einen vorhandenen Build, ohne /dist zu verändern.

Einrichtung

1. Öffnen Sie Run and Debug (Aktivitätsleiste oder Ctrl+Shift+D).
2. Wählen Sie Rebuild and Debug Gateway aus und drücken Sie Start Debugging.

So verwalten Sie den Build-/Debug-Zyklus stattdessen manuell:

1. Aktivieren Sie Source Maps in einem Terminal:
   • Linux/macOS: export OUTPUT_SOURCE_MAPS=1
   • Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
   • Windows (CMD): set OUTPUT_SOURCE_MAPS=1
2. Neu erstellen: pnpm clean:dist && pnpm build
3. Wählen Sie Debug Gateway aus und drücken Sie Start Debugging.

Setzen Sie Haltepunkte in TypeScript-Dateien unter src/; der Debugger ordnet sie über Source Maps dem kompilierten JavaScript zu.

Hinweise

• Rebuild and Debug Gateway löscht /dist und führt bei jedem Start einen vollständigen pnpm build mit Source Maps aus.
• Debug Gateway kann gestartet und beendet werden, ohne /dist zu beeinflussen; den Build-Zyklus verwalten Sie jedoch in einem separaten Terminal.
• Bearbeiten Sie die args in launch.json, um andere CLI-Unterbefehle zu debuggen.
• Um die gebaute CLI für andere Aufgaben zu verwenden (zum Beispiel dashboard --no-open, wenn Ihre Debug-Sitzung ein neues Authentifizierungstoken erzeugt), führen Sie sie in einem anderen Terminal aus: node ./openclaw.mjs oder über einen Alias wie alias openclaw-build="node $(pwd)/openclaw.mjs".

Verwandte Themen

• Fehlerbehebung
• Häufig gestellte Fragen