--- read_when: - Stai collegando le interfacce 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-12T07:01:06Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: c413dcbe838d94c57ba3f6ef9609331e139de6d0abbdb3860753a519bd490314 source_path: concepts/usage-tracking.md workflow: 16 --- ## Che cos'è - Recupera l'utilizzo e le quote del provider direttamente dall'endpoint di utilizzo di ciascun provider. Nessuna stima della fatturazione del provider; solo nomi dei piani, finestre delle quote, saldi, spesa, budget, cronologia dei costi giornalieri, attribuzione di token/modelli o riepiloghi dello stato dell'account comunicati dal provider. - L'output leggibile delle finestre delle quote viene normalizzato nel formato `X% rimanente`, anche quando un provider comunica la quota consumata, la quota rimanente o soltanto conteggi grezzi. I provider privi di finestre delle quote reimpostabili mostrano invece un testo riepilogativo del provider, ad esempio un saldo. - Il comando `/status` a livello di sessione e lo strumento `session_status` usano come ripiego il registro della trascrizione della sessione quando nell'istantanea della sessione attiva mancano i dati sui token o sul modello. Questo ripiego completa i contatori mancanti di token e cache, può recuperare l'etichetta del modello di runtime attivo e preferisce il totale maggiore relativo al prompt quando i metadati della sessione sono mancanti o inferiori (`totalTokensFresh !== true`, zero o sotto il valore ricavato dalla trascrizione). I valori attivi diversi da zero hanno sempre la precedenza sul ripiego. ## Dove compare - `/status` nelle chat: scheda di stato con i token della sessione e il costo stimato (solo per i modelli con chiave API). Quando disponibile, mostra l'utilizzo del provider per il **provider del modello corrente**, come finestra normalizzata `X% rimanente` o testo riepilogativo del provider. - `/usage off|tokens|full` nelle chat: piè di pagina con l'utilizzo per ogni risposta. - `/usage cost` nelle chat: riepilogo locale dei costi aggregato dai registri delle sessioni di OpenClaw. - CLI: `openclaw status --usage` stampa una suddivisione completa dell'utilizzo e delle quote per provider. - CLI: `openclaw models status` elenca i profili di autenticazione OAuth/token e mostra un riepilogo delle finestre di utilizzo accanto a ogni provider che ne dispone. - Interfaccia di controllo: **Utilizzo** mostra le schede relative al piano e alla fatturazione del provider sopra l'analisi dei token e dei costi stimati derivata dalle sessioni di OpenClaw. Le credenziali API amministrative di Anthropic e OpenAI aggiungono la spesa comunicata dal provider per oggi, 7 giorni e 30 giorni, le tendenze giornaliere, i totali dei token, i modelli principali e le categorie di costo. - Interfaccia di controllo: il popover dell'anello di contesto nell'editor della chat mostra l'**utilizzo del piano** per i provider in abbonamento: barre per ciascuna finestra (5 ore, settimanale, limitata al modello) con gli orari di reimpostazione, il piano del provider quando noto, ad esempio `Max (20x)`, e i crediti per l'utilizzo aggiuntivo. Le sessioni fatturate tramite un piano nascondono le stime in dollari per token; le sessioni fatturate tramite API mantengono `Costo stimato` e la suddivisione dei costi per tipo. Le configurazioni della CLI di Claude Code (`claude-cli`) riutilizzano lo stesso utilizzo dell'abbonamento Anthropic. - Barra dei menu di macOS: quando sono disponibili istantanee dell'utilizzo del provider, sotto Contesto compare una sezione principale "Utilizzo". Consulta [Barra dei menu](/it/platforms/mac/menu-bar). `openclaw channels list` non stampa più l'utilizzo del provider; indirizza invece gli utenti a `openclaw status` o `openclaw models list`. ## Cronologia dei costi di Anthropic e OpenAI La quota dell'abbonamento e la fatturazione API sono superfici distinte del provider: - Le credenziali di abbonamento/configurazione di Anthropic continuano a mostrare le finestre delle quote di Claude e i budget facoltativi per l'utilizzo aggiuntivo. Imposta `ANTHROPIC_ADMIN_KEY` o `ANTHROPIC_ADMIN_API_KEY` per mostrare invece la cronologia delle API di utilizzo e costo dell'organizzazione. Una credenziale del provider Anthropic che inizia con `sk-ant-admin` viene rilevata automaticamente. - OAuth di OpenAI ChatGPT/Codex continua a mostrare il piano, le finestre delle quote e il saldo dei crediti. Imposta `OPENAI_ADMIN_KEY` per mostrare invece la cronologia dei costi e dell'utilizzo dei completamenti dell'organizzazione; facoltativamente, imposta `OPENAI_PROJECT_ID` per limitarla a un singolo progetto. OpenClaw non invia mai alle API dell'organizzazione le credenziali di inferenza provenienti da `OPENAI_API_KEY`, dalla configurazione del provider o dai profili di autenticazione, perché tali chiavi potrebbero appartenere a endpoint personalizzati. Le credenziali amministrative hanno la precedenza perché forniscono la fatturazione effettiva dell'organizzazione. OpenClaw non combina questi totali comunicati dal provider con le proprie stime locali delle sessioni; le due sezioni rispondono intenzionalmente a domande diverse. ## Modalità predefinita del piè di pagina dell'utilizzo `/usage off|tokens|full` imposta il piè di pagina per una sessione e la scelta viene memorizzata per tale sessione. `messages.responseUsage` definisce inizialmente questa modalità per le sessioni che non ne hanno scelta una, in modo che il piè di pagina possa essere attivo per impostazione predefinita senza digitare `/usage` ogni volta. Imposta una modalità per ogni canale oppure una mappa per canale con `default` come ripiego: ```jsonc { "messages": { "responseUsage": "tokens", // oppure: { "default": "off", "discord": "full" } }, } ``` Valori accettati: `"off"`, `"tokens"`, `"full"` e l'alias precedente `"on"` (trattato come `"tokens"`). ### Tre stati distinti della sessione Il campo `responseUsage` di una sessione può rappresentare tre stati, ciascuno con una semantica diversa: | Stato | Valore memorizzato | Modalità effettiva | | ----------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------- | | **Non impostato / ereditato** | `undefined` (assente) | Usa il valore predefinito di configurazione `messages.responseUsage`, quindi `off`. | | **Disattivazione esplicita** | `"off"` (memorizzato) | Sempre disattivato; un valore predefinito diverso da off non può riattivare il piè di pagina. | | **Attivazione esplicita** | `"tokens"` o `"full"` (memorizzato) | Tale modalità, indipendentemente dal valore predefinito di configurazione. | ### Precedenza Modalità effettiva = sostituzione della sessione → voce di configurazione del canale → `default` → `off`. Un comando esplicito `/usage off` viene **mantenuto** nella sessione come valore letterale `"off"` e non equivale a "non impostato". Un valore predefinito `messages.responseUsage` diverso da `off` non può riattivare il piè di pagina dopo che l'utente lo ha disabilitato esplicitamente. ### Reimpostazione e disattivazione - `/usage off` disattiva forzatamente il piè di pagina e mantiene questa scelta. Un valore predefinito configurato diverso da `off` non può sostituirla. - `/usage reset` (alias: `default`, `inherit`, `inherited`, `clear`, `unpin`) cancella la sostituzione della sessione. La sessione **eredita** quindi il valore predefinito effettivo della configurazione (`messages.responseUsage`). Se non è configurato alcun valore predefinito, il piè di pagina resta disattivato. - Una reimpostazione completa della sessione (`/reset` o `/new`) o il passaggio a una nuova sessione **mantiene** la preferenza esplicita della modalità di utilizzo, affinché la scelta di visualizzazione dell'utente sopravviva ai passaggi di sessione. Solo `/usage reset` (e i relativi alias) cancella la sostituzione. ### Comportamento ciclico `/usage` senza argomenti alterna ciclicamente: off → tokens → full → off. Il punto iniziale del ciclo è la modalità corrente **effettiva** (la sostituzione della sessione, oppure il valore predefinito della configurazione quando non è impostata), quindi il ciclo corrisponde sempre a ciò che l'utente vede attualmente nel piè di pagina. ### Configurazione Senza configurazione, viene mantenuto il comportamento precedente (piè di pagina disattivato finché non si usa `/usage`). Usa `/usage reset` per cancellare una sostituzione della sessione ed ereditare nuovamente il valore predefinito configurato. ## Piè di pagina personalizzato di `/usage full` `/usage tokens` visualizza sempre una semplice riga `Utilizzo: X in entrata / Y in uscita` (oltre ai suffissi relativi alla cache e al costo stimato, quando disponibili). Solo `/usage full` visualizza il piè di pagina più dettagliato descritto di seguito. `/usage full` mostra un piè di pagina compatto integrato con modello, ragionamento, modalità veloce/lenta, finestra di contesto e costo, quando questi campi sono disponibili. Per il piè di pagina integrato non è necessario alcun file di modello. `messages.usageTemplate` è destinato esclusivamente ai layout personalizzati avanzati. Il valore è un percorso di file JSON (supporta `~`) o un oggetto inline e, quando è valido, sostituisce il piè di pagina integrato. Un percorso di file viene monitorato e ricaricato in tempo reale quando cambia. ```json { "messages": { "usageTemplate": "~/.openclaw/usage-footer.json" } } ``` I modelli mancanti o vuoti usano automaticamente il piè di pagina integrato senza avvisi. Anche i modelli configurati illeggibili o non validi (JSON errato o struttura priva di elementi visualizzabili) usano il piè di pagina integrato ed emettono un avviso per l'operatore. Crea i modelli personalizzati partendo dalla struttura integrata, quindi modifica le parti che desideri 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": " | 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}", }, { "when": "cost.turn_usd", "text": " 💰{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": " | 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}", }, { "when": "cost.turn_usd", "text": " 💰{cost.turn_usd|fixed:4}" }, ], }, }, } ``` ### Struttura ```jsonc { "schema": "openclaw.usageBar.v1", "scales": { "": "low-to-high glyphs" }, // string (1 glyph/char) or array "aliases": { "": { "": "