Debuggen

Debughulpen voor streaminguitvoer, vooral wanneer een provider redenering mengt in normale tekst.

Runtime-debug-overschrijvingen

Gebruik /debug in chat om alleen-runtime config-overschrijvingen in te stellen (geheugen, niet schijf). /debug is standaard uitgeschakeld; schakel het in met commands.debug: true. Dit is handig wanneer je obscure instellingen moet omschakelen zonder openclaw.json te bewerken.

Voorbeelden:

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

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

Sessietrace-uitvoer

Gebruik /trace wanneer je Plugin-eigen trace-/debugregels in één sessie wilt zien zonder de volledige verbose-modus in te schakelen.

Voorbeelden:

/trace/trace on/trace off

Gebruik /trace voor Plugin-diagnostiek zoals Active Memory-debugsamenvattingen. Blijf /verbose gebruiken voor normale verbose-status-/tooluitvoer, en blijf /debug gebruiken voor alleen-runtime config-overschrijvingen.

Trace van Plugin-levenscyclus

Gebruik OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 wanneer Plugin-levenscycluscommando's traag aanvoelen en je een ingebouwde fase-uitsplitsing nodig hebt voor Plugin-metadata, ontdekking, register, runtime-mirror, config-mutatie en refresh-werk. De trace is opt-in en schrijft naar stderr, zodat JSON-commando-uitvoer parseerbaar blijft.

Voorbeeld:

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

Voorbeelduitvoer:

[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 voor onderzoek naar de Plugin-levenscyclus voordat je een CPU-profiler gebruikt. Als het commando vanuit een source-checkout wordt uitgevoerd, meet dan bij voorkeur de gebouwde runtime met node dist/entry.js ... na pnpm build; pnpm openclaw ... meet ook overhead van de source-runner.

CLI-opstart en commandoprofilering

Gebruik de ingecheckte opstartbenchmark wanneer een commando traag aanvoelt:

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

Voor eenmalige profilering via de normale source-runner stel je OPENCLAW_RUN_NODE_CPU_PROF_DIR in:

OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

De source-runner voegt Node CPU-profielvlaggen toe en schrijft een .cpuprofile voor het commando. Gebruik dit voordat je tijdelijke instrumentatie toevoegt aan commandocode.

Voor opstartvertragingen die lijken op synchroon bestandssysteem- of module-loaderwerk, voeg je Node's tracevlag voor sync-I/O toe via de source-runner:

OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch laat deze vlag standaard uitgeschakeld voor het bewaakte Gateway-childproces. Stel OPENCLAW_TRACE_SYNC_IO=1 in wanneer je expliciet Node sync-I/O-trace-uitvoer wilt in watch-modus.

Gateway-watchmodus

Voor snelle iteratie draai je de gateway onder de file watcher:

pnpm gateway:watch

Standaard start of herstart dit een tmux-sessie met de naam openclaw-gateway-watch-main (of een profiel-/poortspecifieke variant zoals openclaw-gateway-watch-dev-19001) en koppelt het automatisch aan vanuit interactieve terminals. Niet-interactieve shells, CI en agent-exec-aanroepen blijven losgekoppeld en drukken in plaats daarvan koppelingsinstructies af. Koppel handmatig wanneer nodig:

tmux attach -t openclaw-gateway-watch-main

Het tmux-paneel voert de ruwe watcher uit:

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

Gebruik foreground-modus wanneer tmux niet gewenst is:

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

Schakel automatisch koppelen uit terwijl tmux-beheer behouden blijft:

OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

Profileer bewaakte Gateway-CPU-tijd wanneer je opstart-/runtime-hotspots debugt:

pnpm gateway:watch --benchmark

De watch-wrapper verbruikt --benchmark voordat de Gateway wordt aangeroepen en schrijft één V8 .cpuprofile per beëindiging van een Gateway-childproces 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

Gebruik --benchmark-dir <path> wanneer je profielen ergens anders wilt hebben. Gebruik --benchmark-no-force wanneer je wilt dat het gebenchmarkte childproces de standaard --force-poortopruiming overslaat en snel faalt als de Gateway-poort al in gebruik is. Benchmarkmodus onderdrukt standaard sync-I/O-trace-spam. Stel OPENCLAW_TRACE_SYNC_IO=1 in met --benchmark wanneer je expliciet zowel CPU- profielen als Node sync-I/O-stacktraces wilt. In benchmarkmodus worden die traceblokken geschreven naar gateway-watch-output.log onder de benchmarkdirectory en uit het terminalpaneel gefilterd; normale Gateway-logs blijven zichtbaar.

De tmux-wrapper neemt algemene niet-geheime runtime-selectors zoals OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT en OPENCLAW_SKIP_CHANNELS mee naar het paneel. Zet providerreferenties in je normale profiel/config, of gebruik ruwe foreground-modus voor eenmalige vluchtige secrets. Als de bewaakte Gateway tijdens het opstarten afsluit, voert de watcher openclaw doctor --fix --non-interactive één keer uit en herstart het Gateway-childproces. Gebruik OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 wanneer je de oorspronkelijke opstartfout wilt zonder de alleen-voor-dev reparatiepass. Het beheerde tmux-paneel gebruikt ook standaard gekleurde Gateway-logs voor leesbaarheid; stel FORCE_COLOR=0 in bij het starten van pnpm gateway:watch om ANSI-uitvoer uit te schakelen.

De watcher herstart bij build-relevante bestanden onder src/, extension-bronbestanden, extension-package.json en openclaw.plugin.json-metadata, tsconfig.json, package.json en tsdown.config.ts. Wijzigingen in extension-metadata herstarten de gateway zonder een tsdown-rebuild te forceren; bron- en configwijzigingen bouwen nog steeds eerst dist opnieuw.

Voeg eventuele gateway-CLI-vlaggen toe na gateway:watch en ze worden bij elke herstart doorgegeven. Het opnieuw uitvoeren van hetzelfde watch-commando respawnt het genoemde tmux-paneel, en de ruwe watcher behoudt nog steeds zijn single-watcher-lock zodat dubbele watcher-parents worden vervangen in plaats van zich op te stapelen.

Dev-profiel + dev-gateway (--dev)

Gebruik het dev-profiel om state te isoleren en een veilige, wegwerpbare setup op te zetten voor debuggen. Er zijn twee --dev-vlaggen:

• Globale --dev (profiel): isoleert state onder ~/.openclaw-dev en stelt de gateway-poort standaard in op 19001 (afgeleide poorten verschuiven mee).
• gateway --dev: vertelt de Gateway om automatisch een standaardconfiguratie + workspace aan te maken wanneer die ontbreekt (en BOOTSTRAP.md over te slaan).

Aanbevolen flow (dev-profiel + dev-bootstrap):

pnpm gateway:devOPENCLAW_PROFILE=dev openclaw tui

Als je nog geen globale installatie hebt, voer de CLI dan 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/canvas verschuiven overeenkomstig)

2. Dev-bootstrap (gateway --dev)

   • Schrijft een minimale config als die ontbreekt (gateway.mode=local, bind loopback).
   • Stelt agent.workspace in op de dev-workspace.
   • Stelt agent.skipBootstrap=true in (geen BOOTSTRAP.md).
   • Seedt de workspacebestanden als die ontbreken: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md.
   • Standaardidentiteit: C3-PO (protocol-droid).
   • Slaat kanaalproviders over in dev-modus (OPENCLAW_SKIP_CHANNELS=1).

Reset-flow (verse start):

pnpm gateway:dev:reset

--reset wist config, credentials, sessies en de dev-workspace (met trash, niet rm) en maakt daarna de standaard dev-setup opnieuw aan.

Ruwe streamlogging (OpenClaw)

OpenClaw kan de ruwe assistant-stream loggen vóór filtering/opmaak. Dit is de beste manier om te zien of redenering binnenkomt als platte tekstdelta's (of als afzonderlijke thinking-blokken).

Schakel dit in via de CLI:

pnpm gateway:watch --raw-stream

Optionele padoverschrijving:

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

Equivalente env vars:

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

Standaardbestand:

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

Ruwe chunklogging (pi-mono)

Om ruwe OpenAI-compat chunks vast te leggen voordat ze naar blokken worden geparsed, biedt pi-mono een aparte logger:

PI_RAW_STREAM=1

Optioneel pad:

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

Standaardbestand:

~/.pi-mono/logs/raw-openai-completions.jsonl

Opmerking: dit wordt alleen uitgegeven door processen die pi-mono's openai-completions-provider gebruiken.

Veiligheidsnotities

• Ruwe streamlogs kunnen volledige prompts, tooluitvoer en gebruikersgegevens bevatten.
• Houd logs lokaal en verwijder ze na het debuggen.
• Als je logs deelt, verwijder dan eerst secrets en PII.

Debuggen in VSCode

Sourcemaps zijn vereist om debuggen in VSCode-gebaseerde IDE's mogelijk te maken, omdat veel van de gegenereerde bestanden als onderdeel van het buildproces gehashte namen krijgen. De meegeleverde launch.json-configuraties richten zich op de Gateway-service, maar kunnen snel voor andere doeleinden worden aangepast:

1. Gateway opnieuw bouwen en debuggen - Debugt de Gateway-service na het maken van een nieuwe build
2. Gateway debuggen - Debugt de Gateway-service van een bestaande build

Setup

De standaardconfiguratie Gateway opnieuw bouwen en debuggen is compleet uitgerust; deze verwijdert automatisch de map /dist en bouwt het project opnieuw met debuggen ingeschakeld:

1. Open het paneel Uitvoeren en debuggen vanuit de Activity Bar of druk op Ctrl+Shift+D
2. Zorg er in de IDE voor dat Gateway opnieuw bouwen en debuggen is geselecteerd in de configuratiekeuzelijst en druk daarna op de knop Debuggen starten

Als alternatief - als je de build- en debugprocessen liever handmatig beheert:

1. Open een terminal en schakel sourcemaps in:
   • Linux/macOS: export OUTPUT_SOURCE_MAPS=1
   • Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
   • Windows (CMD): set OUTPUT_SOURCE_MAPS=1
2. Bouw in dezelfde terminal het project opnieuw: pnpm clean:dist && pnpm build
3. Selecteer in de IDE de optie Gateway debuggen in de configuratiekeuzelijst Uitvoeren en debuggen en druk daarna op de knop Debuggen starten

Je kunt nu breakpoints zetten in je TypeScript-bronbestanden (src/-directory) en de debugger zal breakpoints correct via sourcemaps koppelen aan de gecompileerde JavaScript. Je kunt variabelen inspecteren, stap voor stap door code gaan en call stacks bekijken zoals verwacht.

Notities

• Als je de optie "Gateway opnieuw bouwen en debuggen" gebruikt: elke keer dat de debugger wordt gestart, wordt de map /dist volledig verwijderd en wordt een volledige pnpm build uitgevoerd met sourcemaps ingeschakeld voordat de Gateway start
• Als je de optie "Gateway debuggen" gebruikt: debugsessies kunnen op elk moment worden gestart en gestopt zonder de map /dist te beïnvloeden, maar je moet een apart terminalproces gebruiken om zowel debuggen in te schakelen als de buildcyclus te beheren
• Pas de launch.json-instellingen voor args aan om andere delen van het project te debuggen
• Als je de gebouwde OpenClaw-CLI voor andere taken moet gebruiken (bijv. dashboard --no-open als je debugsessie een nieuw auth-token spawnt), kun je die in een andere terminal uitvoeren als node ./openclaw.mjs of een shellalias maken zoals alias openclaw-build="node $(pwd)/openclaw.mjs"

Gerelateerd

• Probleemoplossing
• FAQ