Skip to main content
Debugging-Hilfen für Streaming-Ausgabe, Gateway-Iteration und Startprofilierung.

​
Laufzeit-Debug-Überschreibungen

/debug legt Konfigurationsüberschreibungen nur für die Laufzeit fest (im Arbeitsspeicher, nicht auf dem Datenträger). Standardmäßig deaktiviert; aktivieren Sie sie mit commands.debug: true.
/debug reset löscht alle Überschreibungen und kehrt zur Konfiguration auf dem Datenträger zurück.

​
Ausgabe der Sitzungsablaufverfolgung

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

​
Ablaufverfolgung des Plugin-Lebenszyklus

Setzen Sie OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1, um eine phasenweise Aufschlüsselung der Arbeiten an Plugin-Metadaten, Erkennung, Registry, Laufzeitspiegelung, Konfigurationsänderung und Aktualisierung zu erhalten. Die Ausgabe erfolgt nach stderr, sodass die JSON-Befehlsausgabe weiterhin analysierbar bleibt. Fehler beim Laden von Plugins enthalten ihren Stacktrace, solange diese Ablaufverfolgung aktiviert ist.
Verwenden Sie dies, bevor Sie zu einem CPU-Profiler greifen. Messen Sie aus einem Quellcode-Checkout die gebaute Laufzeit mit node dist/entry.js ... nach pnpm build; pnpm openclaw ... misst zusätzlich den Overhead des Quellcode-Runners. Verwenden Sie für Zeitmessungen beim synchronen Laden von Modulen die gemeinsame Diagnoseoberfläche statt eines separaten, ausschließlich für Plugins vorgesehenen Umgebungsschalters:

​
Profilierung des CLI-Starts und der Befehle

Eingecheckte Start-Benchmarks:
Setzen Sie für eine einmalige Profilierung über den normalen Quellcode-Runner OPENCLAW_RUN_NODE_CPU_PROF_DIR:
Der Quellcode-Runner fügt Node-CPU-Profil-Flags hinzu und schreibt für den Befehl eine .cpuprofile. Verwenden Sie dies, bevor Sie dem Befehlscode eine temporäre Instrumentierung hinzufügen. Fügen Sie bei Startblockaden, die nach synchroner Dateisystem- oder Modulladerarbeit aussehen, das Node-Flag zur Ablaufverfolgung synchroner E/A über den Quellcode-Runner hinzu:
pnpm gateway:watch lässt dieses Flag für den überwachten Gateway-Unterprozess standardmäßig deaktiviert; setzen Sie OPENCLAW_TRACE_SYNC_IO=1, wenn Sie die Ausgabe der synchronen E/A-Ablaufverfolgung auch im Überwachungsmodus wünschen.

​
Gateway-Überwachungsmodus

Standardmäßig startet oder startet dies eine tmux-Sitzung namens openclaw-gateway-watch-<profile> neu (zum Beispiel openclaw-gateway-watch-main), wobei ein Portsuffix wie openclaw-gateway-watch-dev-19001 nur hinzugefügt wird, wenn OPENCLAW_GATEWAY_PORT vom Standardport 18789 abweicht. Von 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:
Der Bereich verwendet tmux remain-on-exit, sodass Startfehler zum Anhängen oder Erfassen verfügbar bleiben, statt die Sitzung zu löschen. Eine erneute Ausführung von pnpm gateway:watch startet diesen Bereich neu. Im tmux-Bereich wird der unverarbeitete Watcher ausgeführt:
Vor der Überwachung des konfigurierten/standardmäßigen Ports stoppt der tmux-Wrapper den installierten Gateway-Dienst des aktiven Profils. Dadurch wird der Port an den Quellcode-Watcher übergeben, ohne dass launchd, systemd oder eine geplante Aufgabe den Dienst neu startet und ersetzt. Der Dienst bleibt installiert; stellen Sie ihn nach der Überwachungssitzung wieder her mit:
Wenn ein explizites --port oder OPENCLAW_GATEWAY_PORT vom effektiven Port des installierten Dienstes abweicht, lässt der Wrapper den Dienst weiterlaufen, sodass beide Gateways parallel ausgeführt werden können. Vordergrundmodus ohne tmux:
Der unverarbeitete Modus verwaltet den installierten Dienst nicht. Führen Sie zuerst pnpm openclaw gateway stop aus, wenn dieser denselben Port verwendet. Behalten Sie die tmux-Verwaltung bei, deaktivieren Sie jedoch das automatische Anhängen:
Profilieren Sie die CPU-Zeit des überwachten Gateways, wenn Sie Engpässe beim Start oder zur Laufzeit debuggen:
Der Überwachungs-Wrapper verarbeitet --benchmark, bevor er das Gateway aufruft, und schreibt bei jedem Beenden eines Gateway-Unterprozesses ein V8-.cpuprofile unter .artifacts/gateway-watch-profiles/. Stoppen oder starten Sie das überwachte Gateway neu, um das aktuelle Profil zu schreiben, und öffnen Sie es anschließend mit Chrome DevTools oder Speedscope:
  • --benchmark-dir <path>: Profile an einem anderen Ort schreiben.
  • --benchmark-no-force: Die standardmäßige Portbereinigung für --force überspringen und sofort fehlschlagen, wenn der Gateway-Port bereits verwendet wird.
Der Benchmark-Modus unterdrückt standardmäßig Meldungen der synchronen E/A-Ablaufverfolgung. Setzen Sie OPENCLAW_TRACE_SYNC_IO=1 zusammen mit --benchmark, um sowohl CPU-Profile als auch Stacktraces synchroner E/A zu erhalten; im Benchmark-Modus werden diese Ablaufverfolgungsblöcke unter gateway-watch-output.log im Benchmark-Verzeichnis gespeichert (und aus dem Terminalbereich herausgefiltert), während normale Gateway-Protokolle sichtbar bleiben. Der tmux-Wrapper übernimmt gängige, nicht geheime Laufzeitselektoren 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/Ihrer normalen Konfiguration oder verwenden Sie für einmalige flüchtige Geheimnisse den unverarbeiteten Vordergrundmodus. Wenn das überwachte Gateway während des Starts beendet wird, führt der Watcher einmal openclaw doctor --fix --non-interactive aus und startet den Gateway-Unterprozess neu. Setzen Sie OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0, um den ursprünglichen Startfehler ohne den ausschließlich für die Entwicklung vorgesehenen Reparaturdurchlauf zu sehen. Der verwaltete tmux-Bereich verwendet standardmäßig farbige Gateway-Protokolle; setzen Sie beim Starten von pnpm gateway:watch die Option FORCE_COLOR=0, um die ANSI-Ausgabe 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 das Gateway neu, ohne einen Neubau zu erzwingen; bei Änderungen an Quellcode und Konfiguration wird weiterhin zuerst dist neu gebaut. Fügen Sie Gateway-CLI-Flags nach gateway:watch hinzu; sie werden bei jedem Neustart weitergereicht. Eine erneute Ausführung desselben Überwachungsbefehls startet den benannten tmux-Bereich neu; der unverarbeitete Watcher verwendet eine Sperre für einen einzelnen Watcher, sodass doppelte Watcher-Elternprozesse 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 werden entsprechend verschoben).
  • gateway --dev: weist das Gateway an, bei Bedarf automatisch eine Standardkonfiguration und einen Workspace zu erstellen (und den Bootstrap zu überspringen).
Empfohlener Ablauf (Entwicklungsprofil + Entwicklungs-Bootstrap):
Führen Sie die CLI ohne globale Installation über pnpm openclaw ... aus. Auswirkungen:
  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 werden entsprechend verschoben)
  2. Entwicklungs-Bootstrap (gateway --dev)
    • Schreibt eine minimale Konfiguration, falls keine vorhanden ist (gateway.mode=local, Bindung an Loopback).
    • Setzt agents.defaults.workspace auf den Entwicklungs-Workspace und agents.defaults.skipBootstrap=true.
    • Legt bei Bedarf die Workspace-Dateien 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.
Entwicklungs-Gateways ignorieren standardmäßig implizite Auslöser aus Kanal-Umgebungsvariablen, sodass von Ihrer Shell übernommene Anmeldedaten die Entwicklungsinstanz nicht mit echten Kanaldiensten verbinden. Eine explizite channels.<id>-Konfiguration funktioniert weiterhin. Übergeben Sie --dev-ambient-channels zusammen mit --dev, um für diese Ausführung die automatische Kanalkonfiguration aus Umgebungsvariablen wiederherzustellen. Zurücksetzungsablauf (Neustart mit frischem Zustand):
--dev ist ein globales Profil-Flag und wird von einigen Runnern verarbeitet. Wenn Sie es ausdrücklich angeben müssen, verwenden Sie die Form als Umgebungsvariable:
--reset löscht Konfiguration, Anmeldedaten, Sitzungen und den Entwicklungs-Workspace (in den Papierkorb verschoben, nicht gelöscht) und erstellt anschließend die standardmäßige Entwicklungsumgebung neu.
Wenn bereits ein Nicht-Entwicklungs-Gateway ausgeführt wird (launchd oder systemd), stoppen Sie es zuerst:

​
Protokollierung des unverarbeiteten Streams

OpenClaw kann den unverarbeiteten Assistenten-Stream vor jeglicher Filterung/Formatierung protokollieren. Dies ist die beste Möglichkeit, um festzustellen, ob Reasoning als Klartext-Deltas (oder als separate Denkblöcke) eintrifft. Aktivieren Sie dies über die CLI:
Optionale Pfadüberschreibung:
Entsprechende Umgebungsvariablen:
Standarddatei: ~/.openclaw/logs/raw-stream.jsonl

​
Sicherheitshinweise

  • Protokolle des unverarbeiteten Streams 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 zuerst Geheimnisse und personenbezogene Daten.

​
Debugging in VSCode

Source Maps sind erforderlich, da der Build generierte Dateinamen hasht. Die enthaltene launch.json ist auf den Gateway-Dienst ausgerichtet:
  1. Rebuild and Debug Gateway – löscht /dist und baut mit aktiviertem Debugging neu, bevor das Gateway gestartet wird.
  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 stattdessen den Build-/Debug-Zyklus 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 bauen: pnpm clean:dist && pnpm build
  3. Wählen Sie Debug Gateway aus und drücken Sie Start Debugging.
Setzen Sie Haltepunkte in den src/-TypeScript-Dateien; 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 gestoppt werden, ohne /dist zu beeinflussen; den Build-Zyklus verwalten Sie jedoch in einem separaten Terminal.
  • Bearbeiten Sie launch.json args, 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