Limitare i token di Codex CLI e Claude Code: /goal, budget e comandi

🔍 Perché mettere un tetto ai token

Il problema non è il costo del singolo turno, è la coda lunga: sessioni mai chiuse, contesto gonfio che viene ripagato a ogni messaggio, loop agentici che riprovano all'infinito. Un budget in token trasforma una spesa imprevedibile in una spesa con un limite noto: quando il tetto si avvicina, l'agente chiude il lavoro in modo ordinato invece di continuare a consumare.

I due strumenti ragionano in modo diverso: Codex CLI mette il budget sul task (un obiettivo con un tetto di token), Claude Code lavora sulla sessione e sulla finestra di contesto (vedere cosa consuma, tagliare, limitare pensiero e output). Qui sotto la cheat sheet completa; nei prossimi paragrafi la smonto pezzo per pezzo.

I comandi e le chiavi di configurazione dell'articolo, in una pagina sola.

🎯 /goal di Codex: un obiettivo con il suo budget

Il comando /goal (Codex CLI 0.128.0, aprile 2026) cambia il modello di esecuzione: invece del botta e risposta, l'agente insegue un obiettivo persistente finché non lo completa, non si blocca o non esaurisce il token budget configurato. L'obiettivo sopravvive a compattazioni, crash del terminale e riavvii: con /goal pause e /goal resume lo controllo io, non il modello.

Il budget è la parte che mi interessa qui: è un soft stop. Quando i token si avvicinano al tetto, l'agente smette di fare modifiche nuove e produce un riepilogo di cosa è fatto e cosa resta. Attenzione a una cosa: non è un tetto di fatturazione — un singolo turno costoso può sforare prima che scatti il limite. La feature va abilitata in config.toml (paragrafo successivo).

# dentro la TUI
/goal Migra il modulo auth a JWT, aggiorna i test
/goal            # stato e riepilogo
/goal pause      # sospende, conserva il contesto
/goal resume     # riprende da dove era
/goal clear      # torna al comportamento normale

# da riga di comando, con budget esplicito
codex goal "Refactor del modulo auth" --token-budget 500000

⚙️ config.toml: rollout_budget e auto-compact

In ~/.codex/config.toml vivono le chiavi che contano. Prima cosa: /goal è dietro un feature flag — senza goals = true il comando semplicemente non esiste, e l'errore è silenzioso. Poi c'è features.rollout_budget, il meccanismo documentato per il tetto di token: enabled lo accende, limit_tokens è obbligatorio ed è il budget vero e proprio, reminder_interval_tokens decide ogni quanti token l'agente riceve un promemoria del budget residuo (default: 10% del limite).

Completano il quadro model_auto_compact_token_limit, la soglia che anticipa la compattazione automatica della cronologia, e la possibilità di mettere un config.toml dentro il repository (in .codex/): Codex lo legge camminando dalla radice del progetto, così ogni progetto può avere il suo budget. Nota onesta: in giro si leggono chiavi come max_tokens_per_session o model_max_output_tokens — nella reference ufficiale il meccanismo di budget documentato oggi è rollout_budget.

[features]
goals = true                        # abilita /goal

[features.rollout_budget]
enabled = true
limit_tokens = 500000               # tetto in token (obbligatorio)
reminder_interval_tokens = 50000    # promemoria ogni 50k

# compatta la cronologia prima del limite del modello
model_auto_compact_token_limit = 200000

📊 Claude Code: /usage, /context e /compact

Claude Code non ha (ancora) un budget per task: la sua filosofia è vedere e tagliare. /usage mostra i token della sessione e, sugli abbonamenti, quanto sto consumando dei limiti del piano, con il dettaglio di cosa pesa — skill, subagent, server MCP. /context dice cosa sta riempiendo la finestra. Sono i due comandi che lancio prima di chiedermi «perché va piano e costa tanto».

Il taglio lo fanno /clear, che azzera il contesto tra un task e l'altro (contesto stantio = token ripagati a ogni messaggio), e /compact, che riassume la cronologia e accetta istruzioni su cosa conservare. Con /model ed /effort abbasso modello e sforzo quando il task non merita Opus, e /usage-credits imposta un limite di spesa mensile sull'account. In più, lo status line può mostrare l'uso della finestra in tempo reale.

/usage                    # token di sessione + limiti del piano
/context                  # cosa riempie la finestra
/compact Tieni i sample di codice e le API usate
/clear                    # reset tra task non correlati
/model                    # modello più economico per il task
/effort low               # meno reasoning, meno token
/usage-credits            # limite di spesa mensile

🔧 settings.json: limitare pensiero e output

Le leve permanenti stanno in settings.json, nel blocco env. MAX_THINKING_TOKENS taglia il budget di extended thinking sui modelli a budget fisso: i thinking token sono fatturati come output e di default possono essere decine di migliaia per richiesta — per task semplici 8000 bastano. CLAUDE_CODE_MAX_OUTPUT_TOKENS limita l'output massimo per richiesta; occhio che alzarlo riduce la finestra utile prima dell'auto-compact, quindi va dosato, non massimizzato.

Due trucchi complementari che usano la stessa logica «meno contesto, meno spesa»: delegare le operazioni verbose ai subagent, così l'output enorme resta nel loro contesto e a me torna un riassunto, e usare gli hook per pre-filtrare — un hook che filtra l'output dei test a sole failure trasforma decine di migliaia di token in centinaia.

{
  "env": {
    "MAX_THINKING_TOKENS": "8000",
    "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "32000"
  }
}

⚠️ Errori da evitare

Il primo errore l'ho già anticipato: trattare i budget come tetti di fatturazione. Sia il token budget di /goal sia limit_tokens sono meccanismi runtime: fermano il loop, non la carta di credito. Per un tetto di spesa vero servono /usage-credits (abbonamenti) o gli spend limit del workspace sulla Console API. Il secondo: dimenticare il feature flag — /goal senza goals = true non dà errore, semplicemente non appare.

Terzo errore: budget monolitici. Un obiettivo enorme con un budget enorme perde i guardrail dopo le compattazioni di contesto; funziona meglio spezzare in goal piccoli con budget stretti (100–500k per un fix mirato, 500k–2M per un refactoring multi-file). Ultimo: alzare CLAUDE_CODE_MAX_OUTPUT_TOKENS «per sicurezza» — si paga in finestra di contesto e si finisce in auto-compact prima.

✅ Checklist finale

La mia configurazione minima è questa: budget attivi di default, misura prima di tagliare, limiti di spesa a monte. Cinque minuti di setup che si ripagano alla prima sessione lasciata aperta per sbaglio.

Altri articoli del blog