Dépassement du budget de contexte d’IronClaw : quatre erreurs, un nombre codé en dur

« Context budget exceeded » n’est pas une seule erreur dans IronClaw. Quatre variantes d’erreur distinctes portent cette formulation ; aucune ne correspond à la fenêtre de contexte de votre modèle, et aucun fichier de configuration, aucune variable d’environnement ni aucune option CLI ne modifie le nombre associé à chacune d’elles. Le budget est de 128 000 jetons, intégré à la compilation, avec une réserve de 20 000 jetons, et les trois canaux qui l’encombrent — fichiers d’identité, extraits de compétences et schémas d’outils — sont assemblés en plus de cette allocation plutôt qu’à l’intérieur de celle-ci. Ce fait est signalé dans un rapport de défaut d’IronClaw encore ouvert ; il ne s’agit pas d’une théorie de cette page.

Une précision s’impose, car le nom est très utilisé. Il s’agit de github.com/nearai/ironclaw, le runtime d’agent Rust de NEAR AI — pas de la souris gaming Corsair qui domine les recherches commerciales sur ce terme, ni de l’entreprise sans lien ironclaw.tech, qui vend également des logiciels d’agent et se compare également à OpenClaw. IronClaw vs OpenClaw établit cette distinction en détail. Chaque chiffre provenant du code source ci-dessous a été lu dans main au commit b0b999d (commis le 10 septembre 2026), le 21 septembre 2026, via l’API de contenu GitHub. Ce commit est ultérieur à la balise de version ironclaw-v1.4.0 publiée le 28 août 2026. Le 1er octobre 2026, le binaire de la version plus récente ironclaw-v1.4.1 (publié le 29 septembre 2026, correctif pour Google OAuth et Wasmtime sans modification du budget dans ses notes) a été exécuté contre un endpoint de test local ; son comportement est décrit ci-dessous et limité à cette version, tandis que les chiffres du code source restent limités au commit.

Quel « budget de contexte dépassé » examinez-vous ?

Il s’agit de chaînes d’affichage Rust thiserror, telles qu’elles apparaissent dans les journaux et les détails d’erreur. La formulation exacte permet de déterminer quel canal a échoué.

Ce que voit un utilisateur lors d’un dépassement réel du modèle ne contient aucun de ces mots. La projection d’échec produite par l’hôte est la phrase fixe « The run failed because the model context was too large. Retry with a shorter request or start a new thread. », et l’erreur mappée par le fournisseur depuis la passerelle du modèle est « model request exceeded its context budget ». Deux précautions. Cette page n’a pas suivi une exécution de bout en bout ; la phrase destinée à l’utilisateur vers laquelle un échec du canal des compétences est finalement projeté n’est donc pas établie ici. Par ailleurs, une chaîne souvent répétée, « Model request context exceeds the available input budget », n’apparaît nulle part dans nearai/ironclaw — elle appartient à un autre projet d’agent et ne doit pas servir à diagnostiquer celui-ci.

Les 128 000 que vous ne pouvez pas configurer

PromptContextTokenBudget fournit trois constantes : une limite de contexte de 128 000 jetons, une réserve de 20 000 jetons et une valeur maximale de sortie de la boucle principale égale à 0. La transcription visible correspond à la limite moins la plus grande des deux dernières valeurs, soit 108 000 jetons — un calcul dérivé des valeurs par défaut, et non une valeur littérale du fichier. Le troisième terme n’est jamais défini en dehors des tests ; la réserve reste donc toujours fixée à 20 000. Et toutes les constructions hors tests du dépôt utilisent le simple PromptContextTokenBudget::default() — l’une dans la stratégie de compactage, l’autre dans la valeur par défaut de TextOnlyLoopHostConfig de l’hôte du pilote de boucle ; chaque appel ::new(…) avec des nombres différents se trouve dans un module #[cfg(test)].

L’issue #5739 d’IronClaw le dit dans son titre — « Effective context budget is a hardcoded 128K that ignores the model's context_length and has no config override » — ouverte depuis le 6 juillet 2026 et toujours ouverte le 21 septembre 2026. Trois pièges en découlent :

• Les clés budget.* ne sont pas concernées. La page de configuration d’IronClaw documente budget.user_daily_usd, budget.pause_at et leurs équivalents sous une section intitulée « budget — cost controls », qui y est décrite comme plafonnant les dépenses de l’agent. Il s’agit de paramètres financiers (deux d’entre eux, budget.overestimate_factor et budget.default_tz, sont un multiplicateur et un fuseau horaire plutôt que des montants en dollars). Aucune clé, à quelque niveau que ce soit, ne définit une limite de contexte, une réserve, le plafond d’identité ou le budget des compétences — et l’ordre de priorité publié est « compiled defaults < config.toml < environment variables < CLI flags », de sorte qu’une clé absente est absente partout.
• La PR #5790 est une fausse piste. Son titre propose une « prompt-context budget override through host factory ». L’API indique qu’elle a été fermée le 27 août 2026 avec merged: false.
• Les correctifs sont tous des propositions. #8053, qui utiliserait 90 % de la fenêtre annoncée d’un modèle avec la même réserve de 20 000, ainsi que #7976 et #5435, étaient tous ouverts au moment de la vérification.

Pour un endpoint tiers, une étape supplémentaire est décisive. ModelMetadata.context_length est un Option, l’implémentation par défaut du trait LlmProvider renvoie None — « Par défaut, renvoie le nom du modèle sans information sur sa taille » — et l’adaptateur générique compatible OpenAI ne définit aucune surcharge ; il hérite donc de cette implémentation par défaut. Un endpoint personnalisé n’annonce par conséquent jamais de fenêtre. IronClaw prévoit 108 000 jetons de transcription, que votre modèle puisse en contenir un million ou 32 000, et #8053 lirait précisément le champ que ce chemin ne renseigne jamais. Consultez Configuration de l’API personnalisée d’IronClaw pour savoir comment configurer cet endpoint ; cette page reste centrée sur le budget.

Les canaux qui remplissent l’invite sans toucher au budget

L’issue d’amélioration ouverte d’IronClaw #8057, déposée le 3 septembre 2026 et toujours ouverte lors de la vérification, décrit le mécanisme avec les propres termes du fournisseur : le budget de l’invite « dimensionne uniquement la transcription », tandis que le contenu d’identité, les extraits de compétences et de mémoire, le contexte du canal et les schémas d’outils « sont assemblés en plus de l’allocation de transcription sans la réduire ; la requête reçue par le fournisseur peut donc dépasser le budget que la boucle pense respecter ». Il s’agit d’un rapport de défaut, et non d’une documentation d’un comportement livré — mais c’est la raison pour laquelle une exécution peut échouer en raison de sa taille alors que chaque canal pris séparément semble respecter les limites.

La voie des outils est mesurable, et IronClaw la mesure. Son benchmark enregistré dans le dépôt, réalisé sur un jeu de données synthétique de 93 outils, enregistre une réduction de 21 355 à 3 843 jetons de schéma estimés avec 22 outils annoncés — 82,0 %, encadrée dans le dépôt par une tolérance de dérive de 2,0 points et un plancher de 50,0 %. Ces nombres ont été lus dans le fichier de test, et non produits en l’exécutant ici — la charge utile mesurée du binaire publié se trouve dans la section ci-dessus, et sa forme est différente : l’ensemble d’outils par défaut, et non un jeu de données de 93 outils. Considérez-les comme les estimations internes d’IronClaw fondées sur le comptage des caractères d’un jeu de données de test, et non comme votre prompt d’outils ni comme des comptages du tokenizer du fournisseur. La lecture honnête porte sur la structure : la divulgation progressive supprime la majeure partie du schéma tout en laissant un plancher de quelques milliers de jetons qu’aucun réglage ne supprime, car les 27 noms de base sont annoncés dans tous les modes de divulgation.

Ce qu'a fait le binaire publié 1.4.1

Le 1er octobre 2026, le binaire publié ironclaw-v1.4.1, dont la somme de contrôle a été vérifiée, a été exécuté dans un conteneur jetable avec un emplacement [llm.default] sur le fournisseur openai_compatible dirigé vers un serveur de test local qui enregistrait chaque requête. Un court message par exécution via ironclaw repl :

Le plancher est donc bien réel dans le build publié : aucun mode de divulgation n'a envoyé moins de 26 schémas et, selon l'estimation d'IronClaw de quatre caractères par jeton, 35,703 octets représentent environ 8,900 jetons avant le moindre de vos mots — les messages système et d'identité ajoutant environ 24,000 octets supplémentaires. Il s'agit d'une arithmétique sur les octets, et non d'un comptage de jetons du fournisseur. Le risque de faute de frappe décrit ci-dessous est confirmé, et non déduit : true a produit exactement la charge utile off, doublant presque l'invite d'outils, sans aucun affichage à l'écran pour le signaler.

Le budget strict s'est déclenché comme l'indique la source. Un message d'environ 380,000 caractères a été envoyé au point de terminaison ; un message d'environ 460,000 caractères — au-delà de 108,000 jetons à raison de quatre caractères par jeton — n'a jamais quitté la machine. La REPL n'a affiché que des lignes de journal d'avertissement indiquant l'étape Prompt, le type BudgetExceeded et le résumé accepted task exceeds the prompt context token budget. Aucun réglage, dans la configuration ou l'environnement, n'a été trouvé pour modifier ce comportement. Les erreurs de la voie des compétences, le dépassement de capacité d'un véritable modèle et toute requête via Kunavo n'ont pas été exécutés.

Réessayer n'est pas une correction, et une faute de frappe aggrave la situation

La stratégie de récupération par défaut réessaie un dépassement de contexte exactement une fois, à l'échelle de l'itération, avec une modification ShrinkContext, puis abandonne — les noms des tests du fournisseur sont model_context_overflow_compacts_once_then_aborts et second_model_context_overflow_aborts_without_another_compaction. Ainsi, réessayer la même requête trop volumineuse ne peut pas réussir. À titre d'échelle, les valeurs par défaut de cette même stratégie autorisent max_model_availability_attempts: 12 et max_attempts_per_class: 2 ; cette classe bénéficie de la seule tentative ShrinkContext.

La compaction ne vous sauvera pas non plus plus tôt : son seuil de déclenchement est le même 108,000, donc rien ne force une compaction avant que la transcription ne l'atteigne. Les compactions forcées et de récupération contournent bien le disjoncteur, qui est le seul moyen dont dispose la boucle pour réduire une invite trop volumineuse avant une nouvelle tentative. Réserve concernant la stratégie alternative : le ticket #5582, ouvert depuis le 3 juillet 2026, indique que ActiveTaskPreservingCompactionStrategy ne lit jamais l'indicateur de dépassement. La stratégie sélectionnée par un déploiement donné n'a pas été retracée ici.

Un risque de configuration mérite d’être vérifié avant toute autre chose. La divulgation progressive des outils est lue depuis REBORN_TOOL_DISCLOSURE, accepte off | compact | signatures | namespaces | bridged et prend par défaut namespaces lorsque la variable est absente ou vide. Toute autre valeur non vide — une faute de frappe, un ancien true ou on — est silencieusement résolue en Off, décrit dans le même fichier comme le « mode témoin : annoncer tous les schémas autorisés ». Une valeur qui n’est pas en UTF-8 produit le même résultat. Le seul signal est une ligne tracing::debug!, et l’effet est un prompt d’outils nettement plus volumineux. Supprimez la variable plutôt que de deviner son orthographe.

Ce que vous pouvez réellement modifier aujourd'hui

Il n'existe aucune page de documentation IronClaw publiée couvrant le budget de contexte, la compaction ou l'une de ces quatre erreurs ; les leviers ci-dessous sont donc ceux que les documents et le code permettent conjointement — et non un remède approuvé par le fournisseur.

Le seul levier documenté qui réduit la pression du contexte des compétences est un indicateur de configuration, et non une variable d'environnement. La page des compétences d'IronClaw indique de le définir sous [skills] et précise que l'activation par mots-clés et balises, ainsi que les mentions explicites de $my-skill, injectent toujours les compétences :

[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

Trois autres leviers, avec leurs limites. Le champ frontmatter max_context_tokens d'une compétence vaut par défaut 2000 selon la même page de documentation, mais y écrire un petit nombre ne réduit pas une compétence volumineuse : lorsque le corps est estimé à plus de deux fois la valeur déclarée, le sélecteur journalise « using actual estimate » et facture la taille mesurée. Une routine réactive peut réduire sa surface d'outils via allowed_tools, ce qui est limité à cette routine et non aux tours interactifs. Enfin, les outils de fichiers sont désactivés sauf si ALLOW_LOCAL_TOOLS=true : la documentation des outils de fichiers d'IronClaw indique qu'ils sont désactivés par défaut « to prevent accidental filesystem access in hosted or shared environments », les laisser désactivés constitue donc un ensemble de schémas en moins dans l'invite. Aucun de ces trois leviers ne touche aux 128,000.

Enfin, ne planifiez pas en fonction d'un nombre obsolète. Le ticket #7485 signalait que le budget de 108,000 jetons représentait « effectively ~54k real tokens » pour le contenu ASCII et que la compaction se déclenchait « roughly 2× early ». Il s'agissait d'un double comptage dans l'un des deux estimateurs de jetons. La PR #7502 les a unifiés et a été fusionnée le 11 août 2026 ; l'API de comparaison de GitHub place le commit de fusion à l'intérieur des balises v1.3.0 et v1.4.0, ainsi qu'à l'intérieur de main. Par rapport à v1.2.0 et v1.1.0, la comparaison renvoie « diverged » ; la première version qui l'inclut n'est donc pas établie — dites v1.3.0 et les versions ultérieures. L'unique estimateur actuel facture l'ASCII à raison de 4 caractères par jeton et environ 1.5 jeton par caractère non ASCII de 3 octets, ce qui signifie qu'une transcription riche en caractères CJK remplit 108,000 bien plus vite qu'une transcription anglaise.

Ce que coûte le plafond par tour, et quelle voie l'emporte

Il s'agit d'une arithmétique illustrative des jetons, et non d'un coût de tâche mesuré ni d'un plafond de facturation. Supposons un tour chargé au maximum : la transcription à son plafond de 108,000 jetons, 8,000 jetons d'identité, 4,000 de contexte de compétence (le budget par défaut du sélecteur ; un runtime composé le configurant à 6,000 l'augmenterait) et 3,843 de schéma d'outils annoncé provenant du benchmark enregistré ci-dessus — 123,843 jetons d'entrée estimés — plus 2,000 jetons de sortie. Il s'agit des propres estimations d'IronClaw sur un dispositif synthétique ; un tokenizer réel de fournisseur donnera donc un résultat différent. Les tarifs sont les prix actuels du catalogue Kunavo par million de jetons.

La dernière colonne est le point central de la section. Une faute de frappe dans REBORN_TOOL_DISCLOSURE ajoute 17,512 jetons d'entrée estimés à chaque tour — sur Claude Sonnet 4.6, cela représente $0.037 par tour avant tout autre changement, et un agent toujours actif effectue de nombreux tours par jour. La seconde conclusion est que payer un modèle à long contexte pour contourner ce problème ne fonctionne pas : IronClaw assemble toujours jusqu'à son propre nombre, donc la fenêtre supplémentaire n'apporte rien tandis que le tarif plus élevé est appliqué à l'ensemble des 123,843 jetons. Multipliez par votre propre nombre de tours quotidien avant d'en faire un budget.

Les offres hébergées ont été relevées sur ironclaw.com le 21 septembre 2026 ; ironclaw.com/pricing renvoie HTTP 404, les offres résident donc sur la page d'accueil. Le titre au-dessus des trois cartes indique « Spin up to 5 agents in a Trusted Execution Environment with up to 130M tokens per month » — cinq agents est le maximum de Pro+, ce titre énonce donc le plafond de l'offre supérieure plutôt que celui d'une carte particulière, et le chiffre de 130M jetons n'apparaît sur aucune carte. La conversion des crédits inclus en jetons et ce qui se passe lorsqu'ils sont épuisés ne sont pas publiés et ne font l'objet d'aucune supposition ici.

Kunavo ne propose aucun modèle d'embedding, de synthèse vocale ou de reconnaissance vocale ; toute étape de recherche ou de traitement vocal dans votre configuration doit donc appeler un fournisseur externe.

Essayez-le, puis lisez le montant facturé

Si vous acheminez IronClaw vers une passerelle compatible OpenAI, l'endpoint de chat-completions de Kunavo correspond à la forme attendue par l'identifiant de fournisseur openai_compatible. Il s'agit d'une correspondance de protocole déduite de la documentation des deux côtés — l'exécution du 1er octobre ci-dessus utilisait un serveur de test local, et non Kunavo ; Kunavo ne revendique donc aucune compatibilité. Conservez une voie fonctionnelle, exécutez une tâche limitée et rapprochez le résultat de l'utilisation enregistrée par votre compte, plutôt que du coût affiché par IronClaw, qui repose sur sa propre arithmétique. Le montant du catalogue Kunavo constitue un plancher de facturation et non un plafond : lorsque l'amont communique son coût, la facture correspond au montant le plus élevé entre le coût du catalogue et le coût amont multiplié par la majoration applicable. Le rechargement minimal est de $10 de crédit prépayé — un minimum de financement, et non des frais de tâche ni un abonnement ; consultez les détails de facturation et créez un compte lorsque vous êtes prêt à financer une clé. Pour les choix connexes, l'optimisation des coûts de l'IA couvre la mesure du coût par tâche terminée, tandis que PicoClaw et ZeroClaw couvrent deux runtimes apparentés dont la longueur de boucle constitue un levier de coût de la même manière.

Questions fréquentes

Exécution le 1er octobre 2026 : le binaire publié ironclaw-v1.4.1 contre un serveur de test local — le tableau de divulgation et la sonde de budget ci-dessus ; les états des tickets #5739, #8053, #8057, #7976 et #5435 ont été revérifiés le même jour et étaient tous encore ouverts. Vérification effectuée le 21 septembre 2026. Les constantes sources, chaînes d'erreur, stratégie de récupération, estimateur de jetons, modes de divulgation et référence du benchmark ont été lus dans main de nearai/ironclaw au commit b0b999d via l'API de contenu GitHub ; les états des tickets et pull requests via l'API des tickets GitHub ; les pages relatives aux compétences, à la configuration, au stockage et aux outils de fichiers sur docs.ironclaw.com, ainsi que les cartes d'offres sur ironclaw.com, par récupération directe. La balise de version v1.4.0 n'a pas été extraite, aucune instance IronClaw n'a été exécutée, aucun test du dépôt n'a été lancé, aucune des quatre erreurs n'a été reproduite en conditions réelles et Kunavo n'a pas testé IronClaw en runtime. Les tarifs des jetons Kunavo proviennent du catalogue actuel, et chaque montant en dollars constitue une arithmétique illustrative des jetons.