English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Technical reference

Uso dei token e costi

OpenClaw tiene traccia dei token, non dei 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 Skills (solo metadati; le istruzioni vengono caricate su richiesta con read). Il blocco Skills compatto è limitato da skills.limits.maxSkillsPromptChars, con override opzionale per agente in agents.list[].skillsLimits.maxSkillsPromptChars.
  • Istruzioni di auto-aggiornamento
  • File di workspace + bootstrap (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md quando nuovo, più MEMORY.md quando presente). Il file root minuscolo memory.md non viene iniettato; è input legacy di riparazione per openclaw doctor --fix quando abbinato a MEMORY.md. I file grandi vengono troncati da agents.defaults.bootstrapMaxChars (predefinito: 12000), e l’iniezione bootstrap totale è limitata da agents.defaults.bootstrapTotalMaxChars (predefinito: 60000). I file giornalieri memory/*.md non fanno parte del normale prompt 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 di contesto di avvio una tantum con memoria giornaliera recente per quel primo turno. I comandi chat semplici /new e /reset vengono riconosciuti senza invocare il modello. Il preambolo di avvio è controllato da agents.defaults.startupContext.
  • Ora (UTC + fuso orario dell’utente)
  • Tag di risposta + comportamento Heartbeat
  • Metadati runtime (host/OS/modello/thinking)

Vedi la scomposizione completa in Prompt di sistema.

Cosa conta nella finestra di contesto

Tutto ciò che il modello riceve conta nel 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. Queste manopole sono per estratti runtime limitati e blocchi iniettati posseduti dal runtime. Sono separate dai limiti bootstrap, dai limiti del contesto di avvio e dai limiti del prompt Skills.

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ù dettaglio visivo 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 comandi in chat:

  • /status → scheda di stato ricca di emoji con il modello della sessione, uso del contesto, token di input/output dell’ultima risposta e costo stimato (solo chiave API).
  • /usage off|tokens|full → aggiunge un footer di uso per risposta a ogni risposta.
    • Persiste per sessione (memorizzato come responseUsage).
    • L’autenticazione OAuth nasconde il costo (solo token).
  • /usage cost → mostra un riepilogo locale dei costi dai log di sessione OpenClaw.

Altre superfici:

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

Le superfici di uso normalizzano gli alias di campo nativi comuni dei provider prima della visualizzazione. Per il traffico Responses della famiglia OpenAI, questo 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 JSON di Gemini CLI viene normalizzato: il testo della risposta viene da response, e stats.cached viene mappato a cacheRead con stats.input_tokens - stats.cached usato quando la CLI omette un campo stats.input esplicito. Per il traffico Responses nativo della famiglia OpenAI, gli alias d’uso WebSocket/SSE vengono normalizzati allo stesso modo, e i totali ricadono 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 runtime attivo dal log d’uso della trascrizione più recente. I valori live non zero esistenti hanno comunque precedenza sui valori di fallback della trascrizione, e i totali della trascrizione più grandi orientati al prompt possono prevalere quando i totali memorizzati mancano o sono più piccoli. L’autenticazione d’uso per le finestre quota provider proviene dagli hook specifici del provider quando disponibili; altrimenti OpenClaw ricade sulle credenziali OAuth/chiave API corrispondenti da profili di autenticazione, env o config. Le voci di trascrizione dell’assistente persistono la stessa forma d’uso normalizzata, incluso usage.cost quando il modello attivo ha prezzi configurati e il provider restituisce metadati d’uso. Questo fornisce a /usage cost e allo stato sessione basato su trascrizione una sorgente stabile anche dopo che lo stato runtime live non esiste più.

OpenClaw mantiene la contabilizzazione dell’uso del provider separata dallo snapshot di contesto corrente. usage.total del provider può includere input in cache, output e più chiamate al modello nel ciclo strumenti, quindi è utile per costi e telemetria ma può sovrastimare la finestra di contesto live. Le visualizzazioni e le diagnostiche del contesto 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 vengono stimati dalla tua configurazione prezzi del modello:

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

Questi sono USD per 1M token per input, output, cacheRead e cacheWrite. Se i prezzi mancano, OpenClaw mostra solo i token. I token OAuth non mostrano mai il costo in dollari.

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

TTL cache e impatto della potatura

La cache del prompt del provider si applica solo entro la finestra TTL della cache. OpenClaw può facoltativamente eseguire la potatura cache-ttl: pota la sessione una volta scaduto il TTL della cache, poi reimposta la finestra cache in modo che le richieste successive possano 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 sessione.

Heartbeat può mantenere la cache calda durante gli intervalli di inattività. Se il TTL 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 cache per agente con agents.list[].params.cacheRetention.

Per una guida completa manopola per manopola, vedi Cache del prompt.

Per i prezzi 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 della cache del prompt di Anthropic per le tariffe e i moltiplicatori TTL più recenti: https://docs.anthropic.com/docs/build-with-claude/prompt-caching

Esempio: mantenere calda la cache 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 viene unito sopra i params del modello selezionato, quindi puoi sovrascrivere solo cacheRetention ed ereditare gli altri valori predefiniti del modello invariati.

Esempio: abilitare l’intestazione beta Anthropic per contesto 1M

La finestra di contesto 1M di Anthropic è attualmente protetta da beta. OpenClaw può iniettare il valore anthropic-beta richiesto quando abiliti context1m su modelli Opus o Sonnet supportati.

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          context1m: true

Questo viene mappato all’intestazione beta context-1m-2025-08-07 di Anthropic.

Si applica solo quando context1m: true è impostato su quella voce modello.

Requisito: la credenziale deve essere idonea all’uso di contesto lungo. In caso contrario, Anthropic risponde con un errore di rate limit lato provider per quella richiesta.

Se autentichi Anthropic con token OAuth/abbonamento (sk-ant-oat-*), OpenClaw salta l’intestazione beta context-1m-* perché Anthropic attualmente rifiuta quella combinazione con HTTP 401.

Suggerimenti per ridurre la pressione sui token

  • Usa /compact per riepilogare sessioni lunghe.
  • Riduci gli output grandi degli strumenti nei tuoi workflow.
  • Abbassa agents.defaults.imageMaxDimensionPx per sessioni ricche di screenshot.
  • Mantieni brevi le descrizioni Skills (l’elenco Skills viene iniettato nel prompt).
  • Preferisci modelli più piccoli per lavoro verboso ed esplorativo.

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

Correlati