--- read_when: - Stai collegando le superfici di utilizzo/quota del provider - Devi spiegare il comportamento del monitoraggio dell'utilizzo o i requisiti di autenticazione summary: Superfici di monitoraggio dell'utilizzo e requisiti delle credenziali title: Monitoraggio dell'utilizzo x-i18n: generated_at: "2026-07-01T18:14:07Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: fa9b2b0b19ca0b4beeea40bfd50b07a92155178d5ec0e1877013843e0caba4fb source_path: concepts/usage-tracking.md workflow: 16 --- ## Che cos'è - Recupera l'utilizzo/la quota dei provider direttamente dai loro endpoint di utilizzo. - Nessun costo stimato; solo finestre di quota riportate dal provider o riepiloghi dello stato dell'account. - L'output di stato della finestra di quota leggibile dalle persone è normalizzato in `X% left`, anche quando un'API upstream segnala quota consumata, quota rimanente o solo conteggi grezzi. I provider senza finestre di quota reimpostabili possono invece mostrare testo riepilogativo del provider, ad esempio un saldo. - `/status` a livello di sessione e `session_status` possono ripiegare sull'ultima voce di utilizzo della trascrizione quando lo snapshot della sessione live è scarso. Questo fallback completa i contatori mancanti di token/cache, può recuperare l'etichetta del modello runtime attivo e preferisce il totale più grande orientato al prompt quando i metadati di sessione sono mancanti o inferiori. I valori live esistenti diversi da zero hanno comunque la precedenza. ## Dove compare - `/status` nelle chat: scheda di stato ricca di emoji con token di sessione + costo stimato (solo chiave API). L'utilizzo del provider viene mostrato per il **provider del modello corrente** quando disponibile, come finestra `X% left` normalizzata o testo riepilogativo del provider. - `/usage off|tokens|full` nelle chat: piè di pagina di utilizzo per risposta. - `/usage cost` nelle chat: riepilogo dei costi locali aggregato dai log di sessione OpenClaw. - CLI: `openclaw status --usage` stampa una ripartizione completa per provider. - CLI: `openclaw channels list` stampa lo stesso snapshot di utilizzo insieme alla configurazione del provider (usa `--no-usage` per saltarlo). - Barra dei menu macOS: sezione "Utilizzo" sotto Context (solo se disponibile). ## Modalità predefinita del piè di pagina di utilizzo `/usage off|tokens|full` imposta il piè di pagina per una sessione e viene ricordato per quella sessione. `messages.responseUsage` inizializza quella modalità per le sessioni che non ne hanno scelta una, così il piè di pagina può essere attivo per impostazione predefinita senza digitare `/usage` ogni volta. Imposta una modalità per ogni canale, oppure una mappa per canale con un fallback `default`: ```jsonc { "messages": { "responseUsage": "tokens", // or: { "default": "off", "discord": "full" } }, } ``` ### Tre stati di sessione distinti Il campo `responseUsage` di una sessione ha tre stati rappresentabili, ciascuno con semantiche diverse: | Stato | Valore salvato | Modalità effettiva | | ------------------------ | ------------------------------- | ------------------------------------------------------------------------- | | **Non impostato / eredita** | `undefined` (assente) | Ricade sul valore predefinito di configurazione `messages.responseUsage`, poi `off`. | | **Disattivato esplicito** | `"off"` (salvato) | Sempre disattivato: un valore predefinito di configurazione diverso da off non può riabilitare il piè di pagina. | | **Attivato esplicito** | `"tokens"` o `"full"` (salvato) | Quella modalità, indipendentemente dal valore predefinito di configurazione. | ### Precedenza Modalità effettiva = override di sessione → voce di configurazione del canale → `default` → `off`. Un `/usage off` esplicito viene **persistito** come valore letterale `"off"` nella sessione, non è equivalente a "non impostato". Questo significa che un valore predefinito `messages.responseUsage` diverso da off non può riattivare il piè di pagina dopo che l'utente lo ha disabilitato esplicitamente. ### Reimpostare vs disattivare - `/usage off` — forza la disattivazione del piè di pagina e persiste quella scelta. Un valore predefinito configurato diverso da off non può sovrascriverla. - `/usage reset` (alias: `inherit`, `clear`, `default`) — cancella l'override di sessione. La sessione quindi **eredita** il valore predefinito effettivo della configurazione (`messages.responseUsage`). Se non è configurato alcun valore predefinito, il piè di pagina è disattivato (invariato rispetto a prima). Usalo per "tornare al valore predefinito" senza attivare esplicitamente il piè di pagina. - Un reset completo della sessione (`/reset` o `/new`) o un rollover della sessione **preserva** la preferenza esplicita della modalità di utilizzo, così la scelta di visualizzazione dell'utente sopravvive ai rollover di sessione. Solo `/usage reset` (e i suoi alias) cancella davvero l'override. ### Comportamento di commutazione `/usage` senza argomenti cicla: off → tokens → full → off. Il punto di partenza del ciclo è la modalità corrente **effettiva** (override di sessione che ricade sul valore predefinito di configurazione quando non impostato), quindi il ciclo è sempre coerente con ciò che l'utente vede nel piè di pagina. ### Configurazione Senza configurazione, il comportamento precedente rimane valido (piè di pagina disattivato fino a `/usage`). Usa `/usage reset` per cancellare un override di sessione e tornare a ereditare il valore predefinito configurato. ## Piè di pagina `/usage full` personalizzato `/usage full` mostra un piè di pagina compatto integrato con modello, reasoning, veloce/lento, finestra di contesto e costo quando questi campi sono disponibili. I campi token e cache restano disponibili per i template personalizzati. Non è richiesto alcun file template. `messages.usageTemplate` è solo per layout personalizzati avanzati. Il valore è un percorso di file JSON (supporta `~`) o un oggetto inline, e sostituisce il piè di pagina integrato quando valido: ```json { "messages": { "usageTemplate": "~/.openclaw/usage-footer.json" } } ``` I template mancanti o vuoti ricadono silenziosamente sul piè di pagina integrato. Anche i template configurati non leggibili o non validi ricadono sul piè di pagina integrato ed emettono un avviso per l'operatore. Parti dalla forma integrata per i template personalizzati, poi modifica le parti che vuoi cambiare: ```jsonc { "schema": "openclaw.usageBar.v1", "scales": { "braille": "⠐⡀⡄⡆⡇⣇⣧⣷⣿", "block": "░▏▎▍▌▋▊▉█", "shade": "░▒▓█", "moon": "🌑🌘🌗🌖🌕", "level": "▁▂▃▄▅▆▇█", "weather": ["🥶", "☁️", "🌥", "⛅️", "🌤", "☀️"], "plants": ["🪾", "🍂", "🌱", "☘️", "🍀", "🌿"], "moons6": ["🌑", "🌚", "🌘", "🌗", "🌖", "🌝"], }, "aliases": { "models": { "claude-opus-4-6": "opus46", "claude-opus-4-8": "opus48", "claude-sonnet-4-6": "sonnet46", "claude-haiku-4-5": "haiku45", "gpt-5.5": "gpt5.5", }, "reasoning": { "off": "🌑", "minimal": "🌚", "low": "🌘", "medium": "🌗", "high": "🌕", "xhigh": "🌝", }, }, "output": { "sep": "", "default": [ { "text": "{model.provider}{identity.emoji|🤖}{model.display_name|alias:models}" }, { "map": "model.is_fallback", "cases": { "true": "🔄" } }, { "map": "model.is_override", "cases": { "true": "📌" } }, { "when": "model.reasoning", "text": "{model.reasoning|alias:reasoning}" }, { "map": "state.fast_mode", "cases": { "true": "⚡️", "false": "🐌" } }, { "when": "context.max_tokens", "text": "\u00A0| 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}", }, { "when": "cost.turn_usd", "text": "\u00A0💰{cost.turn_usd|fixed:4}" }, ], "surfaces": { "discord": [ { "text": "-# -\n" }, { "text": "-# {model.provider}{identity.emoji|🤖}{model.display_name|alias:models}" }, { "map": "model.is_fallback", "cases": { "true": "🔄" } }, { "map": "model.is_override", "cases": { "true": "📌" } }, { "when": "model.reasoning", "text": "{model.reasoning|alias:reasoning}" }, { "map": "state.fast_mode", "cases": { "true": "⚡️", "false": "🐌" } }, { "when": "context.max_tokens", "text": "\u00A0| 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}", }, { "when": "cost.turn_usd", "text": "\u00A0💰{cost.turn_usd|fixed:4}" }, ], }, }, } ``` ### Forma ```jsonc { "schema": "openclaw.usageBar.v1", "scales": { "": "low-to-high glyphs" }, // string (1 glyph/char) or array "aliases": { "": { "": "