Registrazione

OpenClaw ha due superfici di log principali:

• Log su file (righe JSON) scritti dal Gateway.
• Output della console mostrato nei terminali e nella UI di debug del Gateway.

La scheda Log della UI di controllo segue in tempo reale il log su file del gateway. Questa pagina spiega dove si trovano i log, come leggerli e come configurare livelli e formati di log.

Dove si trovano i log

Per impostazione predefinita, il Gateway scrive un file di log a rotazione in:

/tmp/openclaw/openclaw-YYYY-MM-DD.log

La data usa il fuso orario locale dell'host del gateway.

Ogni file ruota quando raggiunge logging.maxFileBytes (predefinito: 100 MB). OpenClaw conserva fino a cinque archivi numerati accanto al file attivo, come openclaw-YYYY-MM-DD.1.log, e continua a scrivere in un nuovo log attivo invece di sopprimere la diagnostica.

Puoi sovrascrivere questa impostazione in ~/.openclaw/openclaw.json:

{  "logging": {    "file": "/path/to/openclaw.log"  }}

Come leggere i log

CLI: tail live (consigliato)

Usa la CLI per seguire in tempo reale il file di log del gateway tramite RPC:

openclaw logs --follow

Opzioni correnti utili:

• --local-time: visualizza i timestamp nel tuo fuso orario locale
• --url <url> / --token <token> / --timeout <ms>: flag RPC standard del Gateway
• --expect-final: flag di attesa della risposta finale RPC supportata da agente (accettato qui tramite il livello client condiviso)

Modalità di output:

• Sessioni TTY: righe di log strutturate, leggibili e colorate.
• Sessioni non TTY: testo semplice.
• --json: JSON delimitato da righe (un evento di log per riga).
• --plain: forza il testo semplice nelle sessioni TTY.
• --no-color: disabilita i colori ANSI.

Quando passi un --url esplicito, la CLI non applica automaticamente le credenziali di configurazione o di ambiente; includi tu --token se il Gateway di destinazione richiede autenticazione.

In modalità JSON, la CLI emette oggetti contrassegnati da type:

• meta: metadati del flusso (file, cursore, dimensione)
• log: voce di log analizzata
• notice: suggerimenti di troncamento / rotazione
• raw: riga di log non analizzata

Se il Gateway local loopback implicito richiede l'abbinamento, chiude durante la connessione o va in timeout prima che logs.tail risponda, openclaw logs ripiega automaticamente sul log su file del Gateway configurato. Le destinazioni --url esplicite non usano questo fallback. openclaw logs --follow è più rigoroso: su Linux usa il journal Gateway user-systemd attivo per PID quando disponibile, altrimenti continua a ritentare il Gateway live invece di seguire un file affiancato potenzialmente obsoleto.

Se il Gateway non è raggiungibile, la CLI stampa un breve suggerimento per eseguire:

openclaw doctor

UI di controllo (web)

La scheda Log della UI di controllo segue in tempo reale lo stesso file usando logs.tail. Vedi UI di controllo per sapere come aprirla.

Log solo canale

Per filtrare l'attività dei canali (WhatsApp/Telegram/ecc.), usa:

openclaw channels logs --channel whatsapp

Formati dei log

Log su file (JSONL)

Ogni riga nel file di log è un oggetto JSON. La CLI e la UI di controllo analizzano queste voci per visualizzare un output strutturato (ora, livello, sottosistema, messaggio).

I record JSONL dei log su file includono anche campi di primo livello filtrabili dalla macchina quando disponibili:

• hostname: nome host del gateway.
• message: testo del messaggio di log appiattito per la ricerca full-text.
• agent_id: id dell'agente attivo quando la chiamata di log trasporta il contesto dell'agente.
• session_id: id/chiave della sessione attiva quando la chiamata di log trasporta il contesto della sessione.
• channel: canale attivo quando la chiamata di log trasporta il contesto del canale.

OpenClaw preserva gli argomenti originali del log strutturato accanto a questi campi così i parser esistenti che leggono le chiavi numerate degli argomenti tslog continuano a funzionare.

Le attività di conversazione, voce in tempo reale e stanze gestite emettono record di log di ciclo di vita limitati attraverso questa stessa pipeline di log su file. Questi record includono tipo di evento, modalità, trasporto, provider e misure di dimensione/temporizzazione quando disponibili, ma omettono testo della trascrizione, payload audio, id dei turni, id delle chiamate e id degli elementi del provider.

Output della console

I log della console sono consapevoli del TTY e formattati per la leggibilità:

• Prefissi dei sottosistemi (ad es. gateway/channels/whatsapp)
• Colorazione del livello (info/warn/error)
• Modalità compatta o JSON opzionale

La formattazione della console è controllata da logging.consoleStyle.

Log WebSocket del Gateway

openclaw gateway dispone anche di logging del protocollo WebSocket per il traffico RPC:

• modalità normale: solo risultati interessanti (errori, errori di analisi, chiamate lente)
• --verbose: tutto il traffico richiesta/risposta
• --ws-log auto|compact|full: sceglie lo stile di rendering dettagliato
• --compact: alias di --ws-log compact

Esempi:

openclaw gatewayopenclaw gateway --verbose --ws-log compactopenclaw gateway --verbose --ws-log full

Configurare il logging

Tutta la configurazione del logging si trova sotto logging in ~/.openclaw/openclaw.json.

{  "logging": {    "level": "info",    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",    "consoleLevel": "info",    "consoleStyle": "pretty",    "redactSensitive": "tools",    "redactPatterns": ["sk-.*"]  }}

Livelli di log

• logging.level: livello dei log su file (JSONL).
• logging.consoleLevel: livello di verbosità della console.

Puoi sovrascriverli entrambi tramite la variabile di ambiente OPENCLAW_LOG_LEVEL (ad es. OPENCLAW_LOG_LEVEL=debug). La variabile di ambiente ha precedenza sul file di configurazione, quindi puoi aumentare la verbosità per una singola esecuzione senza modificare openclaw.json. Puoi anche passare l'opzione globale della CLI --log-level <level> (per esempio, openclaw --log-level debug gateway run), che sovrascrive la variabile di ambiente per quel comando.

--verbose influisce solo sull'output della console e sulla verbosità dei log WS; non modifica i livelli dei log su file.

Diagnostica mirata del trasporto del modello

Quando esegui il debug delle chiamate ai provider, usa flag di ambiente mirati invece di impostare tutti i log su debug:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gatewayOPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway

Flag disponibili:

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1: emette avvio richiesta, risposta fetch, intestazioni SDK, primo evento di streaming, completamento dello stream ed errori di trasporto al livello info.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: include un riepilogo limitato del payload della richiesta nei log delle richieste al modello.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: include tutti i nomi degli strumenti visibili al modello nel riepilogo del payload.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: include uno snapshot JSON redatto e limitato del payload. Usalo solo durante il debug; i segreti vengono redatti ma prompt e testo dei messaggi potrebbero essere ancora presenti.
• OPENCLAW_DEBUG_SSE=events: emette le tempistiche del primo evento e del completamento dello stream.
• OPENCLAW_DEBUG_SSE=peek: emette anche i primi cinque payload degli eventi SSE redatti, limitati per evento.
• OPENCLAW_DEBUG_CODE_MODE=1: emette diagnostica della superficie del modello in modalità codice, incluso quando gli strumenti nativi del provider sono nascosti perché la modalità codice possiede la superficie degli strumenti.

Questi flag scrivono tramite il normale logging di OpenClaw, quindi openclaw logs --follow e la scheda Log della UI di controllo li mostrano. Senza i flag, la stessa diagnostica rimane disponibile al livello debug.

I metadati di avvio e risposta [model-fetch] (provider, API, modello, stato, latenza e campi della richiesta come metodo, URL, timeout, proxy e policy) sono sempre emessi al livello info indipendentemente da OPENCLAW_DEBUG_MODEL_TRANSPORT, quindi l'igiene di base del trasporto del modello è visibile senza flag di debug.

Correlazione delle tracce

I log su file sono JSONL. Quando una chiamata di log trasporta un contesto di traccia diagnostica valido, OpenClaw scrive i campi di traccia come chiavi JSON di primo livello (traceId, spanId, parentSpanId, traceFlags) così i processori di log esterni possono correlare la riga con span OTEL e propagazione traceparent del provider.

Le richieste HTTP del Gateway e i frame WebSocket del Gateway stabiliscono un ambito di traccia richiesta interno. I log e gli eventi diagnostici emessi dentro quell'ambito async ereditano la traccia della richiesta quando non passano un contesto di traccia esplicito. Le tracce di esecuzione agente e di chiamata modello diventano figlie della traccia richiesta attiva, così log locali, snapshot diagnostici, span OTEL e intestazioni traceparent del provider attendibili possono essere uniti tramite traceId senza registrare contenuto grezzo della richiesta o del modello.

Anche i record di log del ciclo di vita delle conversazioni fluiscono all'esportazione log diagnostics-otel quando l'esportazione log OpenTelemetry è abilitata, usando gli stessi attributi limitati dei log su file. Configura diagnostics.otel.logsExporter per scegliere OTLP, stdout JSONL o entrambi i sink.

Dimensione e temporizzazione delle chiamate al modello

La diagnostica delle chiamate al modello registra misure limitate di richiesta/risposta senza catturare contenuto grezzo del prompt o della risposta:

• requestPayloadBytes: dimensione in byte UTF-8 del payload finale della richiesta al modello
• responseStreamBytes: dimensione in byte UTF-8 dei payload dei chunk di risposta del modello in streaming. Gli eventi ad alta frequenza di testo, ragionamento e delta delle chiamate agli strumenti contano solo i byte incrementali delta invece degli snapshot partial completi.
• timeToFirstByteMs: tempo trascorso prima del primo evento di risposta in streaming
• durationMs: durata totale della chiamata al modello

Questi campi sono disponibili per snapshot diagnostici, hook Plugin delle chiamate al modello e span/metriche OTEL delle chiamate al modello quando l'esportazione diagnostica è abilitata.

Stili della console

logging.consoleStyle:

• pretty: leggibile per gli esseri umani, colorato, con timestamp.
• compact: output più conciso (ideale per sessioni lunghe).
• json: JSON per riga (per processori di log).

Redazione

OpenClaw può redigere token sensibili prima che raggiungano l'output della console, i log su file, i record di log OTLP, il testo persistito delle trascrizioni di sessione o i payload degli eventi strumento della UI di controllo (argomenti di avvio strumento, payload di risultato parziale/finale, output exec derivato e riepiloghi delle patch):

• logging.redactSensitive: off | tools (predefinito: tools)
• logging.redactPatterns: elenco di stringhe regex per sovrascrivere l'insieme predefinito. I pattern personalizzati si applicano sopra i valori predefiniti integrati per i payload degli strumenti della UI di controllo, quindi aggiungere un pattern non indebolisce mai la redazione dei valori già intercettati dai predefiniti.

I log su file e le trascrizioni di sessione restano JSONL, ma i valori segreti corrispondenti vengono mascherati prima che la riga o il messaggio venga scritto su disco. La redazione è best-effort: si applica ai contenuti dei messaggi che portano testo e alle stringhe di log, non a ogni identificatore o campo di payload binario.

I valori predefiniti integrati coprono credenziali API comuni e nomi di campi di credenziali di pagamento come numero di carta, CVC/CVV, token di pagamento condiviso e credenziale di pagamento quando appaiono come campi JSON, parametri URL, flag CLI o assegnazioni.

logging.redactSensitive: "off" disabilita solo questa policy generale di log/trascrizione. OpenClaw redige comunque i payload del perimetro di sicurezza che possono essere mostrati a client UI, bundle di supporto, osservatori diagnostici, prompt di approvazione o strumenti agente. Esempi includono eventi di chiamata strumento della UI di controllo, output sessions_history, esportazioni di supporto diagnostico, osservazioni di errori dei provider, visualizzazione dei comandi di approvazione exec e log del protocollo WebSocket del Gateway. logging.redactPatterns personalizzati possono comunque aggiungere pattern specifici del progetto su quelle superfici.

Diagnostica e OpenTelemetry

La diagnostica è composta da eventi strutturati e leggibili dalla macchina per esecuzioni di modelli e telemetria del flusso dei messaggi (webhook, accodamento, stato della sessione). Non sostituisce i log: alimenta metriche, tracce ed esportatori. Gli eventi sono emessi in-process indipendentemente dal fatto che tu li esporti o meno.

Due superfici adiacenti:

• Esportazione OpenTelemetry — invia metriche, tracce e log tramite OTLP/HTTP a qualsiasi collector o backend compatibile con OpenTelemetry (Grafana, Datadog, Honeycomb, New Relic, Tempo, ecc.). La configurazione completa, il catalogo dei segnali, i nomi di metriche/span, le variabili di ambiente e il modello di privacy sono su una pagina dedicata: Esportazione OpenTelemetry.
• Flag di diagnostica — flag di log di debug mirati che instradano log extra a logging.file senza aumentare logging.level. I flag non distinguono tra maiuscole e minuscole e supportano caratteri jolly (telegram.*, *). Configura in diagnostics.flags o tramite l'override env OPENCLAW_DIAGNOSTICS=.... Guida completa: Flag di diagnostica.

Per abilitare gli eventi diagnostici per Plugin o sink personalizzati senza esportazione OTLP:

{  diagnostics: { enabled: true },}

Per l’esportazione OTLP verso un collector, vedi esportazione OpenTelemetry.

Suggerimenti per la risoluzione dei problemi

• Gateway non raggiungibile? Esegui prima openclaw doctor.
• Log vuoti? Controlla che il Gateway sia in esecuzione e stia scrivendo nel percorso file in logging.file.
• Serve più dettaglio? Imposta logging.level su debug o trace e riprova.

Correlati

• Esportazione OpenTelemetry — esportazione OTLP/HTTP, catalogo di metriche/span, modello di privacy
• Flag di diagnostica — flag mirati per log di debug
• Interni di logging del Gateway — stili di log WS, prefissi dei sottosistemi e acquisizione della console
• Riferimento della configurazione — riferimento completo dei campi diagnostics.*