Budget del contesto IronClaw superato: quattro errori, un numero hardcoded

«Context budget exceeded» non è un unico errore in IronClaw. Quattro varianti di errore distinte contengono quella formulazione, nessuna corrisponde alla finestra di contesto del tuo modello e nessun file di configurazione, variabile d'ambiente o flag CLI modifica il numero alla base di una di esse. Il budget è di 128.000 token incorporati nella compilazione, con una riserva di 20.000 token, e i tre percorsi che lo riempiono — file di identità, snippet di skill e schemi degli strumenti — vengono assemblati al di sopra di tale disponibilità anziché al suo interno; si tratta di una segnalazione di difetto aperta da IronClaw, non di una teoria di questa pagina.

Un chiarimento, perché il nome è ambiguo. Si tratta di github.com/nearai/ironclaw, il runtime per agenti Rust di NEAR AI — non del mouse da gaming Corsair che domina le ricerche commerciali per questo termine e non dell'azienda non correlata ironclaw.tech, che vende anch'essa software per agenti e si confronta anch'essa con OpenClaw. IronClaw vs OpenClaw traccia questa distinzione nel dettaglio. Ogni dato a livello di codice sorgente riportato di seguito è stato letto da main al commit b0b999d (effettuato il 10 settembre 2026), il 21 settembre 2026, tramite l'API dei contenuti di GitHub. Quel commit è successivo al tag di rilascio ironclaw-v1.4.0 pubblicato il 28 agosto 2026. Il 1° ottobre 2026 il binario della versione ironclaw-v1.4.1 più recente (pubblicato il 29 settembre 2026, una patch per Google OAuth e Wasmtime senza modifiche al budget nelle note di rilascio) è stato eseguito contro un endpoint di test locale; ciò che ha fatto è riportato di seguito ed è circoscritto a quella versione, mentre i dati del codice sorgente restano circoscritti al commit.

Quale «context budget exceeded» stai guardando

Queste sono stringhe di visualizzazione Rust thiserror, ovvero ciò che compare nei log e nei dettagli dell'errore. Leggere la formulazione esatta indica quale percorso ha avuto esito negativo.

Ciò che un utente vede per un overflow effettivo del modello non contiene nessuna di quelle parole. La proiezione dell'errore generata dall'host è la frase fissa «The run failed because the model context was too large. Retry with a shorter request or start a new thread.» e l'errore mappato dal provider del gateway del modello è «model request exceeded its context budget». Due avvertenze. Questa pagina non ha tracciato un'esecuzione end-to-end, quindi non è stabilito quale frase rivolta all'utente produca alla fine un errore del percorso delle skill. Inoltre, una stringa ampiamente ripetuta, «Model request context exceeds the available input budget», non compare in alcun punto di nearai/ironclaw: appartiene a un altro progetto di agenti e non deve essere utilizzata per diagnosticare questo.

I 128.000 token che non puoi configurare

PromptContextTokenBudget fornisce tre costanti: un limite di contesto di 128.000 token, una riserva di 20.000 token e un valore max-output del ciclo principale pari a 0. La trascrizione visibile è il limite meno il maggiore tra gli ultimi due valori, quindi 108.000 token: un calcolo basato sui valori predefiniti, non un valore letterale presente nel file. Il terzo termine non viene mai assegnato al di fuori dei test, quindi la riserva è sempre pari a 20.000. Inoltre, ogni costruzione non di test nel repository usa il semplice PromptContextTokenBudget::default(): una nella strategia di compattazione e una nel valore predefinito TextOnlyLoopHostConfig dell'host del driver del ciclo; ogni chiamata ::new(…) con numeri diversi si trova all'interno di un modulo #[cfg(test)].

La stessa issue di IronClaw #5739 lo afferma nel titolo: «Effective context budget is a hardcoded 128K that ignores the model's context_length and has no config override» — aperta dal 6 luglio 2026 e ancora aperta il 21 settembre 2026. Ne derivano tre possibili equivoci:

• Le chiavi budget.* non riguardano questo. La pagina di configurazione di IronClaw documenta budget.user_daily_usd, budget.pause_at e le chiavi correlate in una sezione intitolata «budget — cost controls», descritta come un limite alla spesa dell'agente. Sono impostazioni monetarie (due di esse, budget.overestimate_factor e budget.default_tz, sono un moltiplicatore e un fuso orario anziché importi in dollari). Nessuna chiave, a qualsiasi livello, imposta un limite di contesto, una riserva, il limite dell'identità o il budget delle skill; inoltre, l'ordine di precedenza pubblicato è «compiled defaults < config.toml < environment variables < CLI flags», quindi una chiave assente è assente ovunque.
• La PR #5790 è una falsa pista. Il suo titolo propone un «prompt-context budget override through host factory». L'API indica che è stata chiusa il 27 agosto 2026 con merged: false.
• Le correzioni sono tutte proposte. La #8053, che utilizzerebbe il 90% della finestra pubblicizzata di un modello mantenendo la stessa riserva di 20.000 token, e le #7976 e #5435 risultavano tutte ancora aperte al momento della verifica.

Per un endpoint di terze parti esiste un ulteriore passaggio, ed è quello decisivo. ModelMetadata.context_length è un Option, l'implementazione predefinita del trait LlmProvider restituisce None — «L'implementazione predefinita restituisce il nome del modello senza informazioni sulla dimensione» — e l'adapter generico compatibile con OpenAI non definisce alcuna sovrascrittura, quindi eredita quell'implementazione predefinita. Un endpoint personalizzato non pubblicizza pertanto mai una finestra. IronClaw pianifica 108.000 token di trascrizione sia che il tuo modello ne supporti un milione sia che ne supporti 32.000, e #8053 leggerebbe esattamente il campo che questo percorso non imposta. Consulta Configurazione dell'API personalizzata di IronClaw per sapere come configurare quell'endpoint; questa pagina rimane incentrata sul budget.

I percorsi che riempiono il prompt senza toccare il budget

L'issue di miglioramento aperta di IronClaw #8057, presentata il 3 settembre 2026 e ancora aperta al momento della verifica, descrive il meccanismo con le parole del vendor: il budget del prompt «dimensiona solo la trascrizione», mentre il contenuto dell'identità, gli snippet di skill e memoria, il contesto del canale e gli schemi degli strumenti «vengono assemblati al di sopra della disponibilità della trascrizione senza ridurla, quindi la richiesta ricevuta dal provider può superare il budget che il ciclo ritiene di rispettare». Si tratta di una segnalazione di difetto, non di una descrizione del comportamento distribuito, ma spiega perché un'esecuzione possa fallire per le dimensioni mentre ogni singolo percorso appare conforme.

La corsia degli strumenti è misurabile e IronClaw la misura. Il benchmark committato su un fixture sintetico di 93 strumenti registra una riduzione da 21.355 a 3.843 token di schema stimati con 22 strumenti pubblicizzati — 82,0%, protetto nel repository da una tolleranza al drift di 2,0 punti e da una soglia minima del 50,0%. Questi numeri sono stati letti dal file di test, non prodotti eseguendolo qui — il payload misurato del binario rilasciato si trova nella sezione precedente e ha una forma diversa: il set di strumenti predefinito, non un fixture di 93 strumenti. Considerali stime interne di IronClaw basate sul conteggio dei caratteri su un fixture, non il prompt degli strumenti e non conteggi del tokenizer del provider. La lettura corretta riguarda la forma: la divulgazione progressiva rimuove la maggior parte dello schema, ma lascia comunque una soglia minima di alcune migliaia di token che nessuna impostazione elimina, perché i 27 nomi principali sono pubblicizzati in ogni modalità di divulgazione.

Cosa ha fatto il binario rilasciato 1.4.1

Il 1° ottobre 2026, il binario rilasciato ironclaw-v1.4.1, verificato tramite checksum, è stato eseguito in un container temporaneo con uno slot [llm.default] sul provider openai_compatible puntato a un server di test locale che registrava ogni richiesta. Un messaggio breve per esecuzione tramite ironclaw repl:

Quindi la soglia minima è reale nella build rilasciata: nessuna modalità di divulgazione ha inviato meno di 26 schemi e, secondo la stima di IronClaw di quattro caratteri per token, 35.703 byte equivalgono approssimativamente a 8.900 token prima ancora di una sola parola dell'utente — mentre i messaggi di sistema e di identità aggiungono circa altri 24.000 byte. Si tratta di un calcolo sui byte, non di un conteggio dei token del provider. Il rischio di refuso descritto sotto è confermato, non dedotto: true ha prodotto esattamente il payload off, quasi raddoppiando il prompt degli strumenti, senza alcuna indicazione a schermo.

Il budget rigido è scattato come indicato dal testo sorgente. È stato inviato all'endpoint un messaggio di circa 380.000 caratteri; uno di circa 460.000 caratteri — oltre 108.000 token a quattro caratteri per token — non ha mai lasciato la macchina. La REPL ha stampato solo righe di log di avviso con il nome dello stage Prompt, il tipo BudgetExceeded e il riepilogo accepted task exceeds the prompt context token budget. Non è stata trovata alcuna impostazione, nella configurazione o nell'ambiente, in grado di spostare quella soglia. Gli errori della corsia delle skill, l'overflow di un modello reale e qualsiasi richiesta tramite Kunavo non sono stati eseguiti.

Riprovare non risolve il problema e un refuso lo peggiora

La strategia di recupero predefinita riprova un overflow del contesto esattamente una volta, a livello di iterazione, con una modifica ShrinkContext, quindi interrompe l'esecuzione — i nomi nei test del vendor sono model_context_overflow_compacts_once_then_aborts e second_model_context_overflow_aborts_without_another_compaction. Pertanto, riprovare la stessa richiesta sovradimensionata non può avere successo. Per riferimento, i valori predefiniti della stessa strategia consentono max_model_availability_attempts: 12 e max_attempts_per_class: 2; questa classe riceve il singolo tentativo ShrinkContext.

La compattazione non ti salverà nemmeno prima: la soglia di attivazione è la stessa, 108.000, quindi nulla forza una compattazione prima che la trascrizione la raggiunga. Le compattazioni forzate e di recupero bypassano il circuit breaker; questo è l'unico modo a disposizione del loop per ridurre un prompt sovradimensionato prima di un nuovo tentativo. Una nota sulla strategia alternativa: il problema #5582, aperto dal 3 luglio 2026, segnala che ActiveTaskPreservingCompactionStrategy non legge mai il flag di overflow. Qui non è stato tracciato quale strategia selezioni una determinata distribuzione.

Vale la pena verificare innanzitutto un rischio di configurazione. La divulgazione progressiva degli strumenti viene letta da REBORN_TOOL_DISCLOSURE, accetta off | compact | signatures | namespaces | bridged e, quando il valore non è impostato o è vuoto, usa per impostazione predefinita namespaces. Qualsiasi altro valore non vuoto — un refuso, un true obsoleto o on — viene risolto silenziosamente in Off, documentato nello stesso file come «Braccio di controllo: pubblicizza ogni schema autorizzato». Un valore non UTF-8 produce lo stesso risultato. L'unico segnale è una riga tracing::debug! e l'effetto è un prompt degli strumenti sostanzialmente più grande. Rimuovi la variabile invece di indovinarne l'ortografia.

Cosa puoi effettivamente modificare oggi

Non esiste una pagina della documentazione pubblicata di IronClaw che tratti il budget del contesto, la compattazione o uno qualsiasi di questi quattro errori; pertanto, le leve riportate sotto sono quelle supportate congiuntamente dalla documentazione e dal codice — non un rimedio approvato dal vendor.

L'unica leva documentata che riduce la pressione del contesto delle skill è un flag di configurazione, non una variabile d'ambiente. La pagina delle skill di IronClaw indica di impostarlo sotto [skills] e precisa che l'attivazione tramite parole chiave e tag, oltre alle menzioni esplicite di $my-skill, continua a iniettare le skill:

[skills]
# Documented lever: stops regex auto-activation from loading full skill
# context. Keyword/tag activation and $my-skill mentions still inject skills.
regex_activation_enabled = false

Ce ne sono altre tre, con i relativi limiti. Il campo frontmatter max_context_tokens di una skill ha un valore predefinito di 2000 secondo la stessa pagina della documentazione, ma indicare lì un numero piccolo non riduce una skill grande: quando la stima per il corpo supera il doppio del valore dichiarato, il selettore registra "using actual estimate" e conteggia la dimensione misurata ai fini del budget. Una routine reattiva può restringere la propria superficie degli strumenti tramite allowed_tools, con ambito limitato a quella routine e non ai turni interattivi. Inoltre, gli strumenti per i file sono disattivati a meno che non sia impostato ALLOW_LOCAL_TOOLS=true: la documentazione degli strumenti per i file di IronClaw afferma che sono disabilitati per impostazione predefinita «per impedire l'accesso accidentale al filesystem in ambienti ospitati o condivisi», quindi lasciarli disattivati significa avere un insieme di schemi in meno nel prompt. Nessuna di queste tre opzioni influisce sui 128.000.

Infine, non basare il piano su un numero obsoleto. Il problema #7485 riportava che il budget di 108.000 token equivaleva "di fatto a circa 54.000 token reali" per contenuti ASCII e che la compattazione scattava "circa due volte prima del dovuto". Si trattava di un doppio conteggio in uno dei due stimatori di token. La PR #7502 li ha unificati ed è stata integrata l'11 agosto 2026; l'API compare di GitHub colloca il commit di merge all'interno dei tag v1.3.0 e v1.4.0, nonché all'interno di main. Rispetto a v1.2.0 e v1.1.0, il confronto restituisce "diverged", quindi la prima release che lo contiene non è stabilita — indica v1.3.0 e successive. L'unico stimatore attuale addebita 4 caratteri ASCII per token e circa 1,5 token per ogni carattere non ASCII di 3 byte, il che significa che una trascrizione ricca di CJK riempie 108.000 molto più rapidamente di una in inglese.

Quanto costa il limite massimo per turno e quale percorso conviene

Questa è aritmetica illustrativa dei token, non un costo misurato dell'attività e non un tetto di spesa. Supponi un turno caricato al massimo: la trascrizione al suo limite di 108.000 token, 8.000 di identità, 4.000 di contesto delle skill (il budget predefinito del selettore; un runtime composto che collega 6.000 lo aumenterebbe) e 3.843 di schema degli strumenti pubblicizzati dal benchmark registrato sopra — 123.843 token di input stimati — più 2.000 token di output. Queste sono stime proprie di IronClaw su un fixture sintetico, quindi il tokenizer di un provider reale non coinciderà. Le tariffe sono i prezzi attuali del catalogo Kunavo per milione di token.

L'ultima colonna è il punto della sezione. Un REBORN_TOOL_DISCLOSURE digitato erroneamente aggiunge 17.512 token di input stimati a ogni turno — su Claude Sonnet 4.6 ciò equivale a $0,037 per turno prima di qualsiasi altra modifica, e un agente sempre attivo esegue molti turni al giorno. La seconda conclusione è che pagare un modello con contesto lungo per evitare questo problema non funziona: IronClaw assembla comunque fino al proprio numero, quindi la finestra aggiuntiva non offre alcun vantaggio mentre la tariffa più alta viene applicata a tutti i 123.843 token. Moltiplica per i tuoi turni giornalieri prima di considerare una qualsiasi di queste cifre come un budget.

Le descrizioni dei piani hosted sono state lette da ironclaw.com il 21 settembre 2026; ironclaw.com/pricing restituisce HTTP 404, quindi i piani risiedono nella home page. L'intestazione sopra tutte e tre le schede riporta "Spin up to 5 agents in a Trusted Execution Environment with up to 130M tokens per month" — cinque agenti è il massimo di Pro+, quindi l'intestazione indica il limite massimo del piano superiore e non quello di una singola scheda, mentre la cifra di 130M token non appare su nessuna scheda. Non è pubblicato in quanti token si convertano i crediti inclusi né cosa accada quando si esauriscono, e qui non viene fatta alcuna supposizione.

Kunavo non offre alcun modello di embedding, text-to-speech o speech-to-text, quindi qualsiasi fase di retrieval o voce nella tua configurazione deve chiamare un provider esterno.

Provalo, poi leggi l'addebito

Se indirizzi IronClaw verso un gateway compatibile con OpenAI, l'endpoint chat-completions di Kunavo ha la forma prevista dall'identificatore del provider openai_compatible. Si tratta di una corrispondenza di protocollo ricavata dalla documentazione di entrambe le parti — l'esecuzione del 1° ottobre descritta sopra ha utilizzato un server di test locale, non Kunavo, quindi Kunavo non dichiara alcuna compatibilità. Mantieni disponibile un percorso funzionante, esegui un'attività delimitata e riconcilia il risultato con l'utilizzo registrato dal tuo account, non con il costo visualizzato da IronClaw, che è un suo calcolo. L'importo del catalogo Kunavo è un limite minimo di fatturazione, non un tetto massimo: quando l'upstream comunica il proprio addebito, la fattura è il maggiore tra il costo del catalogo e il costo upstream moltiplicato per il markup applicabile. Il top-up minimo è di $10 in credito prepagato — un minimo di finanziamento, non una tariffa per attività o un abbonamento; consulta i dettagli di fatturazione e crea un account quando sei pronto a finanziare una chiave. Per le scelte correlate, AI cost optimization tratta la misurazione del costo per attività completata, mentre PicoClaw e ZeroClaw trattano due runtime affini la cui lunghezza del loop è una leva di costo allo stesso modo.

Domande frequenti

Eseguito il 1° ottobre 2026: il binario rilasciato ironclaw-v1.4.1 contro un server di test locale — la tabella della divulgazione e la verifica del budget sopra; gli stati dei problemi #5739, #8053, #8057, #7976 e #5435 sono stati ricontrollati lo stesso giorno ed erano ancora tutti aperti. Verificato il 21 settembre 2026. Le costanti sorgente, le stringhe di errore, la strategia di recupero, lo stimatore dei token, le modalità di divulgazione e la baseline del benchmark sono state lette da nearai/ironclaw main al commit b0b999d tramite l'API dei contenuti di GitHub; gli stati dei problemi e delle pull request tramite l'API dei problemi di GitHub; le pagine su skill, configurazione, storage e strumenti per i file su docs.ironclaw.com e le schede dei piani su ironclaw.com tramite fetch diretto. Il tag della release v1.4.0 non è stato estratto, non è stata eseguita alcuna istanza di IronClaw, nessun test nel repository è stato eseguito, nessuno dei quattro errori è stato riprodotto in esecuzione e Kunavo non ha testato IronClaw a runtime. Le tariffe dei token Kunavo provengono dal catalogo attuale e ogni cifra in dollari è aritmetica illustrativa dei token.