Esportazione della diagnostica

OpenClaw può creare uno zip diagnostico locale per le segnalazioni di bug. Combina stato, integrità, log, forma della configurazione ed eventi recenti di stabilità privi di payload del Gateway, tutti sanificati.

Tratta i bundle diagnostici come segreti finché non li hai esaminati. Sono progettati per omettere o oscurare payload e credenziali, ma riassumono comunque i log locali del Gateway e lo stato di runtime a livello host.

# Avvio rapido

openclaw gateway diagnostics export

Il comando stampa il percorso dello zip scritto. Per scegliere un percorso:

openclaw gateway diagnostics export --output openclaw-diagnostics.zip

Per l'automazione:

openclaw gateway diagnostics export --json

# Comando chat

I proprietari possono usare /diagnostics [note] in chat per richiedere un'esportazione locale del Gateway. Usalo quando il bug si è verificato in una conversazione reale e vuoi un report copiabile e incollabile per il supporto:

1. Invia /diagnostics nella conversazione in cui hai notato il problema. Aggiungi una breve nota se utile, per esempio /diagnostics bad tool choice.
2. OpenClaw invia il preambolo diagnostico e chiede un'approvazione exec esplicita. L'approvazione esegue openclaw gateway diagnostics export --json. Non approvare la diagnostica tramite una regola allow-all.
3. Dopo l'approvazione, OpenClaw risponde con un report incollabile che contiene il percorso del bundle locale, il riepilogo del manifest, le note sulla privacy e gli id di sessione pertinenti.

Nelle chat di gruppo, un proprietario può comunque eseguire /diagnostics, ma OpenClaw non pubblica i dettagli diagnostici nella chat condivisa. Invia il preambolo, le richieste di approvazione, il risultato dell'esportazione del Gateway e la scomposizione di sessione/thread Codex al proprietario tramite il percorso di approvazione privato. Il gruppo riceve solo un breve avviso che il flusso diagnostico è stato inviato privatamente. Se OpenClaw non riesce a trovare un percorso privato verso il proprietario, il comando fallisce in modo chiuso e chiede al proprietario di eseguirlo da un DM.

Quando la sessione OpenClaw attiva usa l'harness OpenAI Codex nativo, la stessa approvazione exec copre anche un caricamento di feedback OpenAI per i thread di runtime Codex che OpenClaw conosce. Quel caricamento è separato dallo zip locale del Gateway e compare solo per le sessioni con harness Codex. Prima dell'approvazione, il prompt spiega che approvare la diagnostica invierà anche feedback Codex, ma non elenca gli id di sessione o thread Codex. Dopo l'approvazione, la risposta in chat elenca i canali, gli id di sessione OpenClaw, gli id di thread Codex e i comandi di ripresa locali per i thread inviati ai server OpenAI. Se neghi o ignori l'approvazione, OpenClaw non esegue l'esportazione, non invia feedback Codex e non stampa gli id Codex.

Questo rende breve il ciclo comune di debug Codex: nota il comportamento errato in Telegram, Discord o un altro canale, esegui /diagnostics, approva una volta, condividi il report con il supporto, quindi esegui localmente il comando stampato codex resume <thread-id> se vuoi ispezionare di persona il thread Codex nativo. Vedi harness Codex per quel flusso di ispezione.

# Cosa contiene l'esportazione

Lo zip include:

• summary.md: panoramica leggibile da persone per il supporto.
• diagnostics.json: riepilogo leggibile da macchina di configurazione, log, stato, integrità e dati di stabilità.
• manifest.json: metadati dell'esportazione ed elenco dei file.
• Forma della configurazione sanificata e dettagli di configurazione non segreti.
• Riepiloghi dei log sanificati e righe di log recenti oscurate.
• Snapshot best-effort dello stato e dell'integrità del Gateway.
• stability/latest.json: bundle di stabilità persistito più recente, quando disponibile.

L'esportazione è utile anche quando il Gateway non è integro. Se il Gateway non può rispondere alle richieste di stato o integrità, vengono comunque raccolti i log locali, la forma della configurazione e il bundle di stabilità più recente, quando disponibili.

# Modello di privacy

La diagnostica è progettata per essere condivisibile. L'esportazione conserva dati operativi utili al debug, come:

• nomi dei sottosistemi, id dei plugin, id dei provider, id dei canali e modalità configurate
• codici di stato, durate, conteggi di byte, stato della coda e letture della memoria
• metadati dei log sanificati e messaggi operativi oscurati
• forma della configurazione e impostazioni di funzionalità non segrete

L'esportazione omette o oscura:

• testo delle chat, prompt, istruzioni, corpi Webhook e output degli strumenti
• credenziali, chiavi API, token, cookie e valori segreti
• corpi grezzi di richieste o risposte
• id degli account, id dei messaggi, id grezzi delle sessioni, hostname e nomi utente locali

Quando un messaggio di log sembra testo di payload utente, chat, prompt o strumento, l'esportazione conserva solo l'informazione che un messaggio è stato omesso e il conteggio dei byte.

# Registratore di stabilità

Il Gateway registra per impostazione predefinita uno stream di stabilità limitato e privo di payload quando la diagnostica è abilitata. È destinato a fatti operativi, non ai contenuti.

Lo stesso heartbeat diagnostico registra campioni di vitalità quando il Gateway continua a funzionare ma l'event loop Node.js o la CPU sembrano saturi. Questi eventi diagnostic.liveness.warning includono ritardo dell'event loop, utilizzo dell'event loop, rapporto CPU-core, conteggi di sessioni attive/in attesa/in coda, la fase corrente di avvio/runtime quando nota, intervalli di fase recenti ed etichette limitate per lavori attivi/in coda. I campioni inattivi restano nella telemetria a livello info. I campioni di vitalità diventano avvisi del Gateway solo quando un lavoro è in attesa o in coda, oppure quando lavoro attivo si sovrappone a un ritardo sostenuto dell'event loop. Picchi transitori di ritardo massimo durante lavoro in background altrimenti sano restano nei log di debug. Da soli non riavviano il Gateway.

Le fasi di avvio emettono anche eventi diagnostic.phase.completed con tempi wall-clock e CPU. La diagnostica di embedded-run bloccata marca terminalProgressStale=true quando l'ultimo progresso del bridge sembrava terminale, come un elemento di risposta grezzo o un evento di completamento della risposta, ma il Gateway considera ancora attiva l'esecuzione incorporata.

Ispeziona il registratore live:

openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --json

Ispeziona il bundle di stabilità persistito più recente dopo un'uscita fatale, un timeout di arresto o un errore di avvio al riavvio:

openclaw gateway stability --bundle latest

Crea uno zip diagnostico dal bundle persistito più recente:

openclaw gateway stability --bundle latest --export

I bundle persistiti risiedono in ~/.openclaw/logs/stability/ quando esistono eventi.

# Opzioni utili

openclaw gateway diagnostics export \
  --output openclaw-diagnostics.zip \
  --log-lines 5000 \
  --log-bytes 1000000

• --output <path>: scrivi in uno specifico percorso zip.
• --log-lines <count>: numero massimo di righe di log sanificate da includere.
• --log-bytes <bytes>: numero massimo di byte di log da ispezionare.
• --url <url>: URL WebSocket del Gateway per snapshot di stato e integrità.
• --token <token>: token del Gateway per snapshot di stato e integrità.
• --password <password>: password del Gateway per snapshot di stato e integrità.
• --timeout <ms>: timeout degli snapshot di stato e integrità.
• --no-stability-bundle: salta la ricerca del bundle di stabilità persistito.
• --json: stampa metadati di esportazione leggibili da macchina.

# Disabilitare la diagnostica

La diagnostica è abilitata per impostazione predefinita. Per disabilitare il registratore di stabilità e la raccolta di eventi diagnostici:

{
  diagnostics: {
    enabled: false,
  },
}

Disabilitare la diagnostica riduce il dettaglio delle segnalazioni di bug. Non influisce sul normale logging del Gateway.

# Correlati

• Controlli di integrità
• CLI Gateway
• Protocollo Gateway
• Logging
• Esportazione OpenTelemetry — flusso separato per inviare diagnostica in streaming a un collector