Utilizzo dei token e costi

OpenClaw traccia i token, non i caratteri. I token sono specifici del modello, ma la maggior parte dei modelli in stile OpenAI ha una media di circa 4 caratteri per token per il testo in inglese.

Come viene costruito il prompt di sistema

OpenClaw assembla il proprio prompt di sistema a ogni esecuzione. Include:

• Elenco degli strumenti + brevi descrizioni
• Elenco delle Skills (solo metadati; le istruzioni vengono caricate su richiesta con read). I turni nativi di Codex ricevono il blocco compatto delle Skills come istruzioni di collaborazione per sviluppatori limitate al turno; gli altri harness lo ricevono nella normale superficie del prompt. È limitato da skills.limits.maxSkillsPromptChars, con override facoltativo per agente in agents.list[].skillsLimits.maxSkillsPromptChars.
• Istruzioni di autoaggiornamento
• Workspace + file di bootstrap (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md quando nuovo, più MEMORY.md quando presente). I turni nativi di Codex non incollano il MEMORY.md grezzo dal workspace dell'agente configurato quando gli strumenti di memoria sono disponibili per quel workspace; includono un piccolo puntatore alla memoria nelle istruzioni di collaborazione per sviluppatori limitate al turno e usano gli strumenti di memoria su richiesta. Se gli strumenti sono disabilitati, la ricerca in memoria non è disponibile, o il workspace attivo differisce dal workspace di memoria dell'agente, MEMORY.md usa il normale percorso limitato del contesto di turno. La radice minuscola memory.md non viene iniettata; è input di riparazione legacy per openclaw doctor --fix quando abbinato a MEMORY.md. I file iniettati di grandi dimensioni sono troncati da agents.defaults.bootstrapMaxChars (predefinito: 20000), e l'iniezione bootstrap totale è limitata da agents.defaults.bootstrapTotalMaxChars (predefinito: 60000). I file giornalieri memory/*.md non fanno parte del normale prompt di bootstrap; restano disponibili su richiesta tramite gli strumenti di memoria nei turni ordinari, ma le esecuzioni del modello di reset/avvio possono anteporre un blocco una tantum di contesto di avvio con la memoria giornaliera recente per quel primo turno. I comandi chat semplici /new e /reset vengono riconosciuti senza invocare il modello. Il preludio di avvio è controllato da agents.defaults.startupContext. Gli estratti di AGENTS.md post-Compaction sono separati e richiedono l'opt-in esplicito di agents.defaults.compaction.postCompactionSections.
• Ora (UTC + fuso orario dell'utente)
• Tag di risposta + comportamento Heartbeat
• Metadati di runtime (host/OS/model/thinking)

Vedi la scomposizione completa in Prompt di sistema.

Quando documenti credenziali o frammenti di autenticazione, usa le Convenzioni per i segnaposto dei segreti per evitare falsi positivi degli scanner di segreti nelle modifiche solo documentali.

Cosa conta nella finestra di contesto

Tutto ciò che il modello riceve conta verso il limite di contesto:

• Prompt di sistema (tutte le sezioni elencate sopra)
• Cronologia della conversazione (messaggi utente + assistente)
• Chiamate agli strumenti e risultati degli strumenti
• Allegati/trascrizioni (immagini, audio, file)
• Riepiloghi di Compaction e artefatti di potatura
• Wrapper del provider o intestazioni di sicurezza (non visibili, ma comunque conteggiati)

Alcune superfici pesanti a runtime hanno i propri limiti espliciti:

• agents.defaults.contextLimits.memoryGetMaxChars
• agents.defaults.contextLimits.memoryGetDefaultLines
• agents.defaults.contextLimits.toolResultMaxChars
• agents.defaults.contextLimits.postCompactionMaxChars

Gli override per agente si trovano sotto agents.list[].contextLimits. Questi controlli sono per estratti di runtime limitati e blocchi iniettati di proprietà del runtime. Sono separati dai limiti di bootstrap, dai limiti del contesto di avvio e dai limiti del prompt delle Skills.

toolResultMaxChars è un limite avanzato (fino a 1000000 caratteri). Quando non è impostato, OpenClaw sceglie il limite live dei risultati degli strumenti dalla finestra di contesto effettiva del modello: 16000 caratteri sotto 100K token, 32000 caratteri a 100K+ token e 64000 caratteri a 200K+ token, comunque limitati dalla protezione di quota del contesto di runtime.

Per le immagini, OpenClaw ridimensiona verso il basso i payload immagine di trascrizione/strumento prima delle chiamate al provider. Usa agents.defaults.imageMaxDimensionPx (predefinito: 1200) per regolarlo:

• Valori più bassi di solito riducono l'uso di token visivi e la dimensione del payload.
• Valori più alti preservano più dettagli visivi per screenshot ricchi di OCR/UI.

Per una scomposizione pratica (per file iniettato, strumenti, Skills e dimensione del prompt di sistema), usa /context list o /context detail. Vedi Contesto.

Come vedere l'uso corrente dei token

Usa questi in chat:

• /status → scheda di stato ricca di emoji con il modello della sessione, l'uso del contesto, i token di input/output dell'ultima risposta e il costo stimato quando il prezzo locale è configurato per il modello attivo.
• /usage off|tokens|full → aggiunge un piè di pagina di uso per risposta a ogni risposta.
  • Persiste per sessione (memorizzato come responseUsage).
  • /usage reset (alias: inherit, clear, default) — cancella l'override della sessione così la sessione eredita di nuovo il valore predefinito configurato.
  • /usage tokens mostra i dettagli dei token/cache del turno.
  • /usage full mostra dettagli compatti su modello/contesto/costo; il costo stimato appare solo quando OpenClaw ha metadati di uso e prezzi locali per il modello attivo. I layout personalizzati messages.usageTemplate possono includere campi token/cache.
• /usage cost → mostra un riepilogo dei costi locali dai log di sessione di OpenClaw.

Altre superfici:

• TUI/Web TUI: /status + /usage sono supportati.
• CLI: openclaw status --usage e openclaw channels list mostrano finestre di quota provider normalizzate (X% left, non costi per risposta). Provider correnti con finestra di uso: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi e z.ai.

Le superfici di uso normalizzano gli alias comuni dei campi nativi del provider prima della visualizzazione. Per il traffico Responses della famiglia OpenAI, ciò include sia input_tokens / output_tokens sia prompt_tokens / completion_tokens, quindi i nomi dei campi specifici del trasporto non cambiano /status, /usage o i riepiloghi di sessione. Anche l'uso di Gemini CLI viene normalizzato: il parser predefinito stream-json legge gli eventi message dell'assistente, e stats.cached viene mappato a cacheRead con stats.input_tokens - stats.cached usato quando la CLI omette un campo esplicito stats.input. Gli override JSON legacy leggono ancora il testo della risposta da response. Per il traffico Responses nativo della famiglia OpenAI, gli alias di uso WebSocket/SSE vengono normalizzati allo stesso modo, e i totali ripiegano su input + output normalizzati quando total_tokens manca o è 0. Quando lo snapshot della sessione corrente è scarno, /status e session_status possono anche recuperare contatori token/cache e l'etichetta del modello di runtime attivo dal log di uso della trascrizione più recente. I valori live non zero esistenti hanno comunque precedenza sui valori di fallback della trascrizione, e totali di trascrizione più grandi orientati al prompt possono prevalere quando i totali memorizzati mancano o sono inferiori. L'autenticazione dell'uso per le finestre di quota provider proviene da hook specifici del provider quando disponibili; altrimenti OpenClaw ripiega sulle credenziali OAuth/API-key corrispondenti da profili di autenticazione, env o configurazione. Le voci della trascrizione dell'assistente persistono la stessa forma di uso normalizzata, incluso usage.cost quando il modello attivo ha prezzi configurati e il provider restituisce metadati di uso. Questo offre a /usage cost e allo stato di sessione basato su trascrizione una fonte stabile anche dopo che lo stato live del runtime non c'è più.

OpenClaw mantiene la contabilizzazione dell'uso del provider separata dallo snapshot del contesto corrente. usage.total del provider può includere input in cache, output e più chiamate modello del ciclo strumenti, quindi è utile per costi e telemetria ma può sovrastimare la finestra di contesto live. Le visualizzazioni del contesto e la diagnostica usano lo snapshot del prompt più recente (promptTokens, o l'ultima chiamata al modello quando non è disponibile alcuno snapshot del prompt) per context.used.

Stima dei costi (quando mostrata)

I costi sono stimati dalla configurazione dei prezzi del tuo modello:

models.providers.<provider>.models[].cost

Questi sono USD per 1M token per input, output, cacheRead e cacheWrite. Se i prezzi mancano, /usage full omette il costo; usa /usage tokens o un messages.usageTemplate personalizzato quando hai bisogno dei dettagli token/cache in ogni risposta. La visualizzazione del costo non è limitata all'autenticazione API-key: provider non API-key come aws-sdk possono mostrare il costo stimato quando la voce del modello configurata include prezzi locali e il provider restituisce metadati di uso.

Dopo che sidecar e canali raggiungono il percorso Gateway pronto, OpenClaw avvia un bootstrap facoltativo dei prezzi in background per i riferimenti modello configurati che non hanno già prezzi locali. Quel bootstrap recupera cataloghi remoti dei prezzi OpenRouter e LiteLLM. Imposta models.pricing.enabled: false per saltare quei recuperi di catalogo su reti offline o ristrette; le voci esplicite models.providers.*.models[].cost continuano a guidare le stime dei costi locali.

TTL della cache e impatto della potatura

La cache dei prompt del provider si applica solo entro la finestra TTL della cache. OpenClaw può eseguire facoltativamente la potatura cache-ttl: pota la sessione una volta che il TTL della cache è scaduto, quindi reimposta la finestra della cache così le richieste successive possono riutilizzare il contesto appena messo in cache invece di rimettere in cache l'intera cronologia. Questo mantiene più bassi i costi di scrittura cache quando una sessione resta inattiva oltre il TTL.

Configuralo in Configurazione Gateway e vedi i dettagli del comportamento in Potatura della sessione.

Heartbeat può mantenere la cache calda tra intervalli di inattività. Se il TTL della cache del tuo modello è 1h, impostare l'intervallo Heartbeat appena sotto quel valore (ad esempio 55m) può evitare di rimettere in cache l'intero prompt, riducendo i costi di scrittura cache.

Nelle configurazioni multi-agente, puoi mantenere una configurazione modello condivisa e regolare il comportamento della cache per agente con agents.list[].params.cacheRetention.

Per una guida completa controllo per controllo, vedi Caching dei prompt.

Per i prezzi dell'API Anthropic, le letture cache sono significativamente più economiche dei token di input, mentre le scritture cache vengono fatturate con un moltiplicatore più alto. Vedi i prezzi del prompt caching di Anthropic per le tariffe e i moltiplicatori TTL più recenti: https://docs.anthropic.com/docs/build-with-claude/prompt-caching

Esempio: mantenere calda una cache da 1h con Heartbeat

agents:  defaults:    model:      primary: "anthropic/claude-opus-4-6"    models:      "anthropic/claude-opus-4-6":        params:          cacheRetention: "long"    heartbeat:      every: "55m"

Esempio: traffico misto con strategia cache per agente

agents:  defaults:    model:      primary: "anthropic/claude-opus-4-6"    models:      "anthropic/claude-opus-4-6":        params:          cacheRetention: "long" # default baseline for most agents  list:    - id: "research"      default: true      heartbeat:        every: "55m" # keep long cache warm for deep sessions    - id: "alerts"      params:        cacheRetention: "none" # avoid cache writes for bursty notifications

agents.list[].params si fonde sopra i params del modello selezionato, quindi puoi sovrascrivere solo cacheRetention ed ereditare gli altri valori predefiniti del modello invariati.

Contesto Anthropic 1M

OpenClaw dimensiona i modelli Claude 4.x compatibili con GA, come Opus 4.8, Opus 4.7, Opus 4.6 e Sonnet 4.6, con la finestra di contesto 1M di Anthropic. Non hai bisogno di params.context1m: true per quei modelli.

agents:  defaults:    models:      "anthropic/claude-opus-4-6":        alias: opus

Le configurazioni più vecchie possono mantenere context1m: true, ma OpenClaw non invia più l'header beta ritirato di Anthropic context-1m-2025-08-07 per questa impostazione e non espande a 1M i modelli Claude più vecchi non supportati.

Requisito: la credenziale deve essere idonea all'uso del contesto lungo. In caso contrario, Anthropic risponde con un errore di limite di frequenza lato provider per quella richiesta.

Se autentichi Anthropic con token OAuth/abbonamento (sk-ant-oat-*), OpenClaw preserva gli header beta Anthropic richiesti da OAuth rimuovendo al contempo la beta ritirata context-1m-* se rimane in una configurazione più vecchia.

Suggerimenti per ridurre la pressione sui token

• Usa /compact per riepilogare sessioni lunghe.
• Riduci gli output estesi degli strumenti nei tuoi workflow.
• Abbassa agents.defaults.imageMaxDimensionPx per le sessioni con molti screenshot.
• Mantieni brevi le descrizioni delle skill (l’elenco delle skill viene inserito nel prompt).
• Preferisci modelli più piccoli per lavori prolissi ed esplorativi.

Vedi Skills per la formula esatta dell’overhead dell’elenco delle skill.

Correlati

• Utilizzo e costi dell’API
• Prompt caching
• Monitoraggio dell’utilizzo