Skip to main content
Strumenti di supporto al debug per l’output in streaming, l’iterazione del Gateway e la profilazione dell’avvio.

​
Override di debug in fase di esecuzione

/debug imposta override di configurazione solo in fase di esecuzione (in memoria, non su disco). È disabilitato per impostazione predefinita; abilitalo con commands.debug: true.
/debug reset cancella tutti gli override e ripristina la configurazione su disco.

​
Output di traccia della sessione

/trace mostra le righe di traccia/debug gestite dal plugin per una singola sessione senza abilitare la modalità completamente dettagliata. Usalo per la diagnostica dei plugin, ad esempio i riepiloghi di debug di Active Memory; usa /verbose per il normale output di stato/degli strumenti.

​
Traccia del ciclo di vita dei plugin

Imposta OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 per ottenere una suddivisione fase per fase delle operazioni relative a metadati dei plugin, rilevamento, registro, mirror di runtime, modifica della configurazione e aggiornamento. Scrive su stderr, così l’output JSON dei comandi rimane analizzabile.
Usalo prima di ricorrere a un profiler della CPU. Da un checkout del sorgente, misura il runtime compilato con node dist/entry.js ... dopo pnpm build; anche pnpm openclaw ... misura l’overhead dell’esecutore del sorgente.

​
Profilazione dell’avvio e dei comandi della CLI

Benchmark di avvio inclusi nel repository:
Per una profilazione una tantum tramite il normale esecutore del sorgente, imposta OPENCLAW_RUN_NODE_CPU_PROF_DIR:
L’esecutore del sorgente aggiunge i flag del profilo CPU di Node e scrive un file .cpuprofile per il comando. Usalo prima di aggiungere strumentazione temporanea al codice del comando. Per blocchi durante l’avvio che sembrano dovuti a operazioni sincrone del file system o del caricatore di moduli, aggiungi il flag di traccia I/O sincrono di Node tramite l’esecutore del sorgente:
pnpm gateway:watch lascia questo flag disabilitato per impostazione predefinita per il processo figlio Gateway monitorato; imposta OPENCLAW_TRACE_SYNC_IO=1 quando vuoi l’output della traccia I/O sincrono anche in modalità di monitoraggio.

​
Modalità di monitoraggio del Gateway

Per impostazione predefinita, questo comando avvia o riavvia una sessione tmux denominata openclaw-gateway-watch-<profile> (ad esempio openclaw-gateway-watch-main), con un suffisso della porta come openclaw-gateway-watch-dev-19001 aggiunto solo quando OPENCLAW_GATEWAY_PORT differisce dalla porta predefinita 18789. Si collega automaticamente dai terminali interattivi; le shell non interattive, la CI e le chiamate di esecuzione degli agenti rimangono scollegate e mostrano invece le istruzioni per il collegamento:
Il riquadro tmux esegue direttamente il processo di monitoraggio:
Arresta un servizio Gateway installato prima di monitorare la stessa porta:
L’opzione --force del processo di monitoraggio rimuove il listener corrente, ma non disabilita un servizio supervisionato. In caso contrario, un servizio launchd, systemd o Scheduled Task può riavviarsi e sostituire il Gateway monitorato. Modalità in primo piano senza tmux:
Mantieni la gestione tramite tmux ma disabilita il collegamento automatico:
Profila il tempo CPU del Gateway monitorato durante il debug dei punti critici di avvio/runtime:
Il wrapper di monitoraggio elabora --benchmark prima di invocare il Gateway e scrive un file V8 .cpuprofile per ogni terminazione del processo figlio Gateway in .artifacts/gateway-watch-profiles/. Arresta o riavvia il Gateway monitorato per completare il profilo corrente, quindi aprilo con Chrome DevTools o Speedscope:
  • --benchmark-dir <path>: scrive i profili in un’altra posizione.
  • --benchmark-no-force: evita la pulizia predefinita della porta tramite --force e termina immediatamente con un errore se la porta del Gateway è già in uso.
Per impostazione predefinita, la modalità benchmark elimina l’eccesso di messaggi della traccia I/O sincrono. Imposta OPENCLAW_TRACE_SYNC_IO=1 insieme a --benchmark per ottenere sia i profili CPU sia le tracce dello stack dell’I/O sincrono; in modalità benchmark, questi blocchi di traccia vengono scritti in gateway-watch-output.log nella directory del benchmark (e filtrati dal riquadro del terminale), mentre i normali log del Gateway rimangono visibili. Il wrapper tmux trasferisce nel riquadro i comuni selettori di runtime non segreti, inclusi OPENCLAW_PROFILE, OPENCLAW_CONFIG_PATH, OPENCLAW_STATE_DIR, OPENCLAW_GATEWAY_PORT e OPENCLAW_SKIP_CHANNELS. Inserisci le credenziali del provider nel normale profilo/nella configurazione oppure usa la modalità raw in primo piano per segreti temporanei una tantum. Se il Gateway monitorato termina durante l’avvio, il processo di monitoraggio esegue una volta openclaw doctor --fix --non-interactive e riavvia il processo figlio Gateway. Imposta OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 per visualizzare l’errore di avvio originale senza il passaggio di riparazione riservato allo sviluppo. Il riquadro tmux gestito usa per impostazione predefinita log colorati del Gateway; imposta FORCE_COLOR=0 all’avvio di pnpm gateway:watch per disabilitare l’output ANSI. Il processo di monitoraggio si riavvia quando cambiano i file rilevanti per la compilazione in src/, i file sorgente delle estensioni, i metadati package.json e openclaw.plugin.json delle estensioni, tsconfig.json, package.json e tsdown.config.ts. Le modifiche ai metadati delle estensioni riavviano il Gateway senza forzare una ricompilazione; le modifiche al sorgente e alla configurazione continuano invece a ricompilare prima dist. Aggiungi i flag della CLI del Gateway dopo gateway:watch: verranno trasmessi a ogni riavvio. La riesecuzione dello stesso comando di monitoraggio rigenera il riquadro tmux denominato; il processo di monitoraggio raw mantiene un blocco per una singola istanza, così i processi di monitoraggio principali duplicati vengono sostituiti anziché accumularsi.

​
Profilo di sviluppo + Gateway di sviluppo (—dev)

Due flag --dev distinti:
  • --dev globale (profilo): isola lo stato in ~/.openclaw-dev e imposta per impostazione predefinita la porta del Gateway su 19001 (le porte derivate cambiano di conseguenza).
  • gateway --dev: indica al Gateway di creare automaticamente una configurazione e uno spazio di lavoro predefiniti quando mancanti (e di saltare il bootstrap).
Flusso consigliato (profilo di sviluppo + bootstrap di sviluppo):
Senza un’installazione globale, esegui la CLI tramite pnpm openclaw .... Cosa comporta:
  1. Isolamento del profilo (--dev globale)
    • OPENCLAW_PROFILE=dev
    • OPENCLAW_STATE_DIR=~/.openclaw-dev
    • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
    • OPENCLAW_GATEWAY_PORT=19001 (le porte del browser/canvas cambiano di conseguenza)
  2. Bootstrap di sviluppo (gateway --dev)
    • Scrive una configurazione minima se mancante (gateway.mode=local, associazione a local loopback).
    • Imposta agents.defaults.workspace sullo spazio di lavoro di sviluppo e agents.defaults.skipBootstrap=true.
    • Inizializza i file dello spazio di lavoro se mancanti: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md.
    • Identità predefinita: C3-PO (droide protocollare).
    • pnpm gateway:dev imposta inoltre OPENCLAW_SKIP_CHANNELS=1 per ignorare i provider dei canali.
Flusso di reimpostazione (nuovo avvio):
--dev è un flag di profilo globale e viene intercettato da alcuni esecutori. Se devi specificarlo esplicitamente, usa la forma con variabile d’ambiente:
--reset cancella configurazione, credenziali, sessioni e spazio di lavoro di sviluppo (spostandoli nel cestino, senza eliminarli), quindi ricrea la configurazione di sviluppo predefinita.
Se è già in esecuzione un Gateway non di sviluppo (launchd o systemd), arrestalo prima:

​
Registrazione dello stream raw

OpenClaw può registrare lo stream raw dell’assistente prima di qualsiasi filtro/formattazione. È il modo migliore per verificare se il ragionamento arriva come delta di testo normale oppure come blocchi di pensiero separati. Abilitalo tramite la CLI:
Override facoltativo del percorso:
Variabili d’ambiente equivalenti:
File predefinito: ~/.openclaw/logs/raw-stream.jsonl

​
Note sulla sicurezza

  • I log dello stream raw possono includere prompt completi, output degli strumenti e dati degli utenti.
  • Mantieni i log in locale ed eliminali al termine del debug.
  • Se condividi i log, rimuovi prima i segreti e i dati personali identificabili.

​
Debug in VSCode

Le mappe del sorgente sono necessarie perché la compilazione genera nomi di file con hash. Il file launch.json incluso è configurato per il servizio Gateway:
  1. Rebuild and Debug Gateway - elimina /dist e ricompila con il debug abilitato prima di avviare il Gateway.
  2. Debug Gateway - esegue il debug di una compilazione esistente senza modificare /dist.

​
Configurazione

  1. Apri Run and Debug (nella barra delle attività oppure con Ctrl+Shift+D).
  2. Seleziona Rebuild and Debug Gateway e premi Start Debugging.
In alternativa, per gestire manualmente il ciclo di compilazione/debug:
  1. Abilita le mappe del sorgente in un terminale:
    • Linux/macOS: export OUTPUT_SOURCE_MAPS=1
    • Windows (PowerShell): $env:OUTPUT_SOURCE_MAPS="1"
    • Windows (CMD): set OUTPUT_SOURCE_MAPS=1
  2. Ricompila: pnpm clean:dist && pnpm build
  3. Seleziona Debug Gateway e premi Start Debugging.
Imposta i punti di interruzione nei file TypeScript in src/; il debugger li associa al codice JavaScript compilato tramite le mappe del sorgente.

​
Note

  • Rebuild and Debug Gateway elimina /dist ed esegue una compilazione completa con pnpm build e mappe del sorgente a ogni avvio.
  • Debug Gateway può essere avviato/arrestato senza influire su /dist, ma devi gestire il ciclo di compilazione in un terminale separato.
  • Modifica args in launch.json per eseguire il debug di altri sottocomandi della CLI.
  • Per usare la CLI compilata per altre attività (ad esempio dashboard --no-open se la sessione di debug genera un nuovo token di autenticazione), eseguila da un altro terminale: node ./openclaw.mjs oppure usa un alias come alias openclaw-build="node $(pwd)/openclaw.mjs".

​
Contenuti correlati