openclaw/docs

Fork 0

openclaw-docs-i18n[bot] 4521f5a24a chore(i18n): refresh it translations

2026-04-24 09:12:03 +00:00

14 KiB

Raw Blame History

read_when

summary

title

x-i18n

Ti serve una panoramica del logging adatta ai principianti

Vuoi configurare livelli o formati dei log

Stai facendo troubleshooting e devi trovare rapidamente i log

Panoramica del logging: log su file, output della console, tailing dalla CLI e Control UI

Panoramica del logging

generated_at	model	provider	source_hash	source_path	workflow
2026-04-24T08:47:51Z	gpt-5.4	openai	9b6f274600bcb9f5597c91aa6c30512871105a3e0de446773394abbe27276058	logging.md	15

Logging

OpenClaw ha due principali superfici di log:

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

La scheda Logs della Control UI esegue il tail del file di log del gateway. Questa pagina spiega dove si trovano i log, come leggerli e come configurare livelli e formati dei log.

Dove si trovano i log

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

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

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

Puoi sovrascriverlo in ~/.openclaw/openclaw.json:

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

Come leggere i log

CLI: tail live (consigliato)

Usa la CLI per eseguire il tail del file di log del gateway tramite RPC:

openclaw logs --follow

Opzioni utili attuali:

--local-time: renderizza 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 per RPC supportate da agente (accettato qui tramite il layer client condiviso)

Modalità di output:

Sessioni TTY: righe di log strutturate, leggibili e colorate.
Sessioni non TTY: testo semplice.
--json: JSON delimitato per riga (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 ambiente; includi tu stesso --token se il Gateway di destinazione richiede autenticazione.

In modalità JSON, la CLI emette oggetti con tag type:

meta: metadati dello stream (file, cursore, dimensione)
log: voce di log parsata
notice: suggerimenti di troncamento / rotazione
raw: riga di log non parsata

Se il Gateway locale su loopback richiede l'abbinamento, openclaw logs usa il fallback automatico al file di log locale configurato. I target --url espliciti non usano questo fallback.

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

openclaw doctor

Control UI (web)

La scheda Logs della Control UI esegue il tail dello stesso file usando logs.tail. Vedi /web/control-ui per sapere come aprirla.

Log solo canale

Per filtrare l'attività del canale (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 Control UI parsano queste voci per renderizzare output strutturato (ora, livello, sottosistema, messaggio).

Output della console

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

Prefissi di sottosistema (ad es. gateway/channels/whatsapp)
Colorazione per livello (info/warn/error)
Modalità compatta o JSON facoltativa

La formattazione della console è controllata da logging.consoleStyle.

Log WebSocket del Gateway

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

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

Esempi:

openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw 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: verbosità della console.

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

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

Stili della console

logging.consoleStyle:

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

Redazione

I riepiloghi degli strumenti possono redigere token sensibili prima che raggiungano la console:

logging.redactSensitive: off | tools (predefinito: tools)
logging.redactPatterns: elenco di stringhe regex per sovrascrivere l'insieme predefinito

La redazione influisce solo sull'output della console e non altera i log su file.

Diagnostica + OpenTelemetry

La diagnostica consiste in eventi strutturati, leggibili dalla macchina, per le esecuzioni del modello e per la telemetria del flusso dei messaggi (webhook, accodamento, stato della sessione). Non sostituiscono i log; esistono per alimentare metriche, trace e altri esportatori.

Gli eventi diagnostici vengono emessi in-process, ma gli esportatori si collegano solo quando sono abilitati la diagnostica + il plugin esportatore.

OpenTelemetry vs OTLP

OpenTelemetry (OTel): il modello dati + SDK per trace, metriche e log.
OTLP: il protocollo wire usato per esportare i dati OTel verso un collector/backend.
OpenClaw oggi esporta tramite OTLP/HTTP (protobuf).

Segnali esportati

Metriche: contatori + istogrammi (uso dei token, flusso dei messaggi, accodamento).
Trace: span per uso del modello + elaborazione di webhook/messaggi.
Log: esportati tramite OTLP quando diagnostics.otel.logs è abilitato. Il volume dei log può essere alto; tieni presenti logging.level e i filtri dell'esportatore.

Catalogo degli eventi diagnostici

Uso del modello:

model.usage: token, costo, durata, contesto, provider/modello/canale, ID sessione.

Flusso dei messaggi:

webhook.received: ingresso webhook per canale.
webhook.processed: webhook gestito + durata.
webhook.error: errori del gestore webhook.
message.queued: messaggio accodato per l'elaborazione.
message.processed: esito + durata + errore facoltativo.

Coda + sessione:

queue.lane.enqueue: enqueue della lane della coda dei comandi + profondità.
queue.lane.dequeue: dequeue della lane della coda dei comandi + tempo di attesa.
session.state: transizione di stato della sessione + motivo.
session.stuck: avviso di sessione bloccata + età.
run.attempt: metadati di retry/tentativo dell'esecuzione.
diagnostic.heartbeat: contatori aggregati (webhook/coda/sessione).

Abilitare la diagnostica (senza esportatore)

Usa questo se vuoi che gli eventi diagnostici siano disponibili per plugin o sink personalizzati:

{
  "diagnostics": {
    "enabled": true
  }
}

Flag di diagnostica (log mirati)

Usa i flag per attivare log di debug extra e mirati senza aumentare logging.level. I flag non fanno distinzione tra maiuscole e minuscole e supportano wildcard (ad es. telegram.* o *).

{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}

Sovrascrittura env (one-off):

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Note:

I log dei flag vanno nel file di log standard (lo stesso di logging.file).
L'output continua a essere redatto secondo logging.redactSensitive.
Guida completa: /diagnostics/flags.

Esportare verso OpenTelemetry

La diagnostica può essere esportata tramite il plugin diagnostics-otel (OTLP/HTTP). Questo funziona con qualsiasi collector/backend OpenTelemetry che accetti OTLP/HTTP.

{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "protocol": "http/protobuf",
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}