Foutopsporing

Hulpmiddelen voor foutopsporing bij streaminguitvoer, Gateway-iteratie en profilering van het opstarten.

Overschrijvingen voor runtimefoutopsporing

/debug stelt uitsluitend voor de runtime geldende configuratieoverschrijvingen in (in het geheugen, niet op schijf). Standaard uitgeschakeld; schakel dit in met commands.debug: true.

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

/debug reset wist alle overschrijvingen en keert terug naar de configuratie op schijf.

Uitvoer van sessietraces

/trace toont trace-/foutopsporingsregels die eigendom zijn van een plugin voor één sessie, zonder de volledig uitgebreide modus in te schakelen. Gebruik dit voor plugindiagnostiek, zoals foutopsporingsoverzichten van Active Memory; gebruik /verbose voor normale status-/tooluitvoer.

/trace/trace on/trace off

Trace van de levenscyclus van plugins

Stel OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 in voor een uitsplitsing per fase van pluginmetadata, detectie, register, runtimespiegeling, configuratiewijziging en vernieuwingswerk. Schrijft naar stderr, zodat JSON-opdrachtuitvoer parseerbaar blijft.

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"

Gebruik dit voordat u naar een CPU-profiler grijpt. Meet vanuit een broncodecheckout de gebouwde runtime met node dist/entry.js ... na pnpm build; pnpm openclaw ... meet ook de overhead van de broncoderunner.

Profilering van CLI-opstart en opdrachten

In de repository opgenomen opstartbenchmarks:

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

Stel voor eenmalige profilering via de normale broncoderunner OPENCLAW_RUN_NODE_CPU_PROF_DIR in:

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

De broncoderunner voegt CPU-profielvlaggen van Node toe en schrijft een .cpuprofile voor de opdracht. Gebruik dit voordat u tijdelijke instrumentatie aan opdrachtcode toevoegt.

Voeg bij vastlopers tijdens het opstarten die op synchrone bestandssysteem- of moduleloaderactiviteit lijken, de traceringsvlag voor synchrone I/O van Node toe via de broncoderunner:

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch laat deze vlag standaard uitgeschakeld voor het bewaakte onderliggende Gateway-proces; stel OPENCLAW_TRACE_SYNC_IO=1 in als u ook in de bewakingsmodus trace-uitvoer voor synchrone I/O wilt.

Gateway-bewakingsmodus

pnpm gateway:watch

Standaard start of herstart dit een tmux-sessie met de naam openclaw-gateway-watch-<profile> (bijvoorbeeld openclaw-gateway-watch-main), waarbij alleen een poortsuffix zoals openclaw-gateway-watch-dev-19001 wordt toegevoegd als OPENCLAW_GATEWAY_PORT afwijkt van de standaardpoort 18789. Vanuit interactieve terminals wordt automatisch verbinding gemaakt; niet-interactieve shells, CI en agent-uitvoeraanroepen blijven losgekoppeld en tonen in plaats daarvan instructies om verbinding te maken:

tmux attach -t openclaw-gateway-watch-main

Het tmux-deelvenster voert de onbewerkte watcher uit:

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

Stop een geïnstalleerde Gateway-service voordat u dezelfde poort bewaakt:

pnpm openclaw gateway stop

De --force van de watcher ruimt de huidige luisterende instantie op, maar schakelt een bewaakte service niet uit. Een launchd-, systemd- of Scheduled Task-service kan anders opnieuw worden gestart en de bewaakte Gateway vervangen.

Voorgrondmodus zonder tmux:

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

Behoud tmux-beheer, maar schakel automatisch verbinden uit:

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

Profileer de CPU-tijd van de bewaakte Gateway bij het opsporen van knelpunten tijdens het opstarten of uitvoeren:

pnpm gateway:watch --benchmark

De bewakingswrapper verwerkt --benchmark voordat de Gateway wordt aangeroepen en schrijft bij elke afsluiting van een onderliggend Gateway-proces één V8-.cpuprofile onder .artifacts/gateway-watch-profiles/. Stop of herstart de bewaakte Gateway om het huidige profiel weg te schrijven en open het daarna met Chrome DevTools of Speedscope:

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

• --benchmark-dir <path>: schrijf profielen naar een andere locatie.
• --benchmark-no-force: sla de standaardopschoning van de poort met --force over en stop direct met een fout als de Gateway-poort al in gebruik is.

De benchmarkmodus onderdrukt standaard de overvloedige trace-uitvoer voor synchrone I/O. Stel OPENCLAW_TRACE_SYNC_IO=1 in met --benchmark om zowel CPU-profielen als stacktraces voor synchrone I/O te krijgen; in de benchmarkmodus worden die traceblokken naar gateway-watch-output.log in de benchmarkmap geschreven (en uit het terminalvenster gefilterd), terwijl normale Gateway-logboeken zichtbaar blijven.

De tmux-wrapper geeft veelgebruikte niet-geheime runtimeselectoren door aan het deelvenster, waaronder OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT en OPENCLAW_SKIP_CHANNELS. Plaats providerreferenties in uw normale profiel/configuratie, of gebruik de onbewerkte voorgrondmodus voor eenmalige tijdelijke geheimen.

Als de bewaakte Gateway tijdens het opstarten afsluit, voert de watcher eenmaal openclaw doctor --fix --non-interactive uit en herstart deze het onderliggende Gateway-proces. Stel OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 in om de oorspronkelijke opstartfout te zien zonder de uitsluitend voor ontwikkeling bedoelde herstelstap.

Het beheerde tmux-deelvenster gebruikt standaard gekleurde Gateway-logboeken; stel FORCE_COLOR=0 in wanneer u pnpm gateway:watch start om ANSI-uitvoer uit te schakelen.

De watcher herstart bij wijzigingen in buildrelevante bestanden onder src/, bronbestanden van extensies, de metadata in package.json en openclaw.plugin.json van extensies, tsconfig.json, package.json en tsdown.config.ts. Wijzigingen in extensiemetadata herstarten de Gateway zonder een rebuild af te dwingen; wijzigingen in broncode en configuratie bouwen nog steeds eerst dist opnieuw.

Voeg CLI-vlaggen voor de Gateway toe na gateway:watch; ze worden bij elke herstart doorgegeven. Als dezelfde bewakingsopdracht opnieuw wordt uitgevoerd, wordt het tmux-deelvenster met die naam opnieuw gestart; de onbewerkte watcher gebruikt een vergrendeling voor één watcher, zodat dubbele bovenliggende watcherprocessen worden vervangen in plaats van zich op te stapelen.

Ontwikkelprofiel + ontwikkel-Gateway (--dev)

Twee afzonderlijke --dev-vlaggen:

• Globale --dev (profiel): isoleert statusgegevens onder ~/.openclaw-dev en stelt de Gateway-poort standaard in op 19001 (afgeleide poorten verschuiven mee).
• gateway --dev: geeft de Gateway opdracht automatisch een standaardconfiguratie en werkruimte aan te maken wanneer deze ontbreken (en bootstrap over te slaan).

Aanbevolen werkwijze (ontwikkelprofiel + ontwikkelbootstrap):

pnpm gateway:devOPENCLAW_PROFILE=dev openclaw tui

Voer zonder globale installatie de CLI uit via pnpm openclaw ....

Wat dit doet:

1. Profielisolatie (globale --dev)

   • OPENCLAW_PROFILE=dev
   • OPENCLAW_STATE_DIR=~/.openclaw-dev
   • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
   • OPENCLAW_GATEWAY_PORT=19001 (browser-/canvaspoorten verschuiven overeenkomstig)

2. Ontwikkelbootstrap (gateway --dev)

   • Schrijft een minimale configuratie als die ontbreekt (gateway.mode=local, binding aan local loopback).
   • Stelt agents.defaults.workspace in op de ontwikkelwerkruimte en agents.defaults.skipBootstrap=true.
   • Maakt ontbrekende werkruimtebestanden aan: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md.
   • Standaardidentiteit: C3-PO (protocol-droid).
   • pnpm gateway:dev stelt ook OPENCLAW_SKIP_CHANNELS=1 in om kanaalproviders over te slaan.

Herstelprocedure (schone start):

pnpm gateway:dev:reset

--reset wist configuratie, referenties, sessies en de ontwikkelwerkruimte (verplaatst naar de prullenbak, niet verwijderd) en maakt daarna de standaardontwikkelomgeving opnieuw aan.

Logboekregistratie van de onbewerkte stream

OpenClaw kan de onbewerkte assistentstream vastleggen voordat filtering of opmaak plaatsvindt. Dit is de beste manier om te zien of redeneringen binnenkomen als plattetekstdelta's (of als afzonderlijke denkblokken).

Schakel dit in via de CLI:

pnpm gateway:watch --raw-stream

Optionele overschrijving van het pad:

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

Overeenkomstige omgevingsvariabelen:

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

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

Veiligheidsopmerkingen

• Logboeken van onbewerkte streams kunnen volledige prompts, tooluitvoer en gebruikersgegevens bevatten.
• Bewaar logboeken lokaal en verwijder ze na het foutopsporen.
• Verwijder eerst geheimen en persoonsgegevens als u logboeken deelt.

Foutopsporing in VSCode

Bronmappen zijn vereist omdat de build gegenereerde bestandsnamen hasht. De meegeleverde launch.json is gericht op de Gateway-service:

1. Rebuild and Debug Gateway - verwijdert /dist en bouwt opnieuw met foutopsporing ingeschakeld voordat de Gateway wordt gestart.
2. Debug Gateway - spoort fouten op in een bestaande build zonder /dist te wijzigen.

Instellen

1. Open Run and Debug (Activity Bar of Ctrl+Shift+D).
2. Selecteer Rebuild and Debug Gateway en druk op Start Debugging.

U kunt de build-/foutopsporingscyclus ook als volgt handmatig beheren:

1. Schakel bronmappen in een terminal in:
   • Linux/macOS: export OUTPUT_SOURCE_MAPS=1
   • Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
   • Windows (CMD): set OUTPUT_SOURCE_MAPS=1
2. Bouw opnieuw: pnpm clean:dist && pnpm build
3. Selecteer Debug Gateway en druk op Start Debugging.

Stel breekpunten in TypeScript-bestanden onder src/ in; de debugger koppelt ze via bronmappen aan de gecompileerde JavaScript-code.

Opmerkingen

• Rebuild and Debug Gateway verwijdert /dist en voert bij elke start een volledige pnpm build uit met bronmappen.
• Debug Gateway kan starten en stoppen zonder /dist te beïnvloeden, maar u beheert de buildcyclus in een afzonderlijke terminal.
• Bewerk de args in launch.json om andere CLI-subopdrachten te debuggen.
• Als u de gebouwde CLI voor andere taken wilt gebruiken (bijvoorbeeld dashboard --no-open als uw foutopsporingssessie een nieuw authenticatietoken aanmaakt), voert u deze uit vanuit een andere terminal: node ./openclaw.mjs of een alias zoals alias openclaw-build="node $(pwd)/openclaw.mjs".

Gerelateerd

• Probleemoplossing
• Veelgestelde vragen