IronClaw context budget exceeded: four errors, one hardcoded number

"Context budget exceeded" is not one error in IronClaw. Four distinct error variants carry that wording, none of them is your model's context window, and no configuration file, environment variable or CLI flag changes the number behind any of them. The budget is a compiled-in 128,000 tokens with a 20,000-token reserve, and the three lanes that crowd it — identity files, skill snippets and tool schemas — are assembled on top of that allowance rather than inside it, which is IronClaw's own open defect report rather than this page's theory.

One disambiguation, because the name is crowded. This is github.com/nearai/ironclaw, the Rust agent runtime from NEAR AI — not the Corsair gaming mouse that dominates commercial searches for the word, and not the unrelated company at ironclaw.tech that also sells agent software and also compares itself to OpenClaw. IronClaw vs OpenClaw draws that line in full. Every source-level figure below was read from main at commit b0b999d (committed September 10, 2026) on September 21, 2026, through the GitHub contents API. That commit is later than the ironclaw-v1.4.0 release tag published August 28, 2026, and the released binary was not checked out — so nothing here is scoped to a version number.

Which "context budget exceeded" you are looking at

These are Rust thiserror display strings, which is what lands in logs and error detail. Reading the exact wording tells you which lane failed.

What a user sees for an actual model overflow contains none of those words. The host-authored failure projection is the fixed sentence "The run failed because the model context was too large. Retry with a shorter request or start a new thread.", and the provider-mapped error from the model gateway is "model request exceeded its context budget". Two cautions. This page did not trace an end-to-end run, so which user-facing sentence a skill-lane failure ultimately projects to is not established here. And a widely repeated string, "Model request context exceeds the available input budget", appears nowhere in nearai/ironclaw — it belongs to a different agent project and should not be used to diagnose this one.

The 128,000 you cannot configure

PromptContextTokenBudget ships three constants: a 128,000-token context limit, a 20,000-token reserve, and a main-loop max-output figure of 0. Visible transcript is the limit minus the larger of the last two, so 108,000 tokens — arithmetic from the defaults, not a literal in the file. The third term is never assigned outside tests, so the reserve is always the flat 20,000. And every non-test construction in the repository is the plain PromptContextTokenBudget::default() — one in the compaction strategy, one in the loop driver host's TextOnlyLoopHostConfig default; every ::new(…) call carrying different numbers sits inside a #[cfg(test)] module.

IronClaw's own issue #5739 says it in the title — "Effective context budget is a hardcoded 128K that ignores the model's context_length and has no config override" — open since July 6, 2026 and still open on September 21, 2026. Three traps follow from that:

• The budget.* keys are not this. IronClaw's configuration page documents budget.user_daily_usd, budget.pause_at and siblings under a section headed "budget — cost controls", described there as capping agent spend. They are money settings (two of them, budget.overestimate_factor and budget.default_tz, are a multiplier and a timezone rather than dollar amounts). No key at any level sets a context limit, a reserve, the identity ceiling or the skill budget — and the published precedence order is "compiled defaults < config.toml < environment variables < CLI flags", so an absent key is absent everywhere.
• PR #5790 is a false lead. Its title offers a "prompt-context budget override through host factory". The API reports it closed on August 27, 2026 with merged: false.
• The fixes are all proposals. #8053, which would take 90% of a model's advertised window with the same 20,000 reserve, plus #7976 and #5435, were all open when checked.

For a third-party endpoint there is a further step, and it is the decisive one. ModelMetadata.context_length is an Option, the LlmProvider trait default returns None — "Default returns the model name with no size info" — and the generic OpenAI-compatible adapter defines no override, so it inherits that default. A custom endpoint therefore never advertises a window at all. IronClaw plans for 108,000 transcript tokens whether your model holds a million or 32,000, and #8053 would read exactly the field this path never sets. See IronClaw custom API setup for how that endpoint is configured; this page stays on the budget.

The lanes that fill the prompt without touching the budget

IronClaw's open enhancement issue #8057, filed September 3, 2026 and still open when checked, states the mechanism in the vendor's own words: the prompt budget "sizes only the transcript", while identity content, skill and memory snippets, channel context and tool schemas "are assembled on top of the transcript allowance without reducing it, so the request the provider receives can exceed the budget the loop believes it is honoring." That is a defect report, not shipped-behaviour documentation — but it is why a run can fail on size while every individual lane looks obedient.

The tool lane is measurable, and IronClaw measures it. Its committed benchmark over a synthetic 93-tool fixture records a reduction from 21,355 to 3,843 estimated schema tokens with 22 tools advertised — 82.0%, guarded in-repo by a 2.0-point drift tolerance and a 50.0% floor. Those numbers were read from the test file, not produced by running it here. Treat them as IronClaw's internal character-count estimates over a fixture, not as your tool prompt and not as provider-tokenizer counts. The honest reading is the shape: progressive disclosure removes most of the schema and still leaves a floor of a few thousand tokens that no setting removes, because the 27 core names are advertised in every disclosure mode.

Retrying is not a fix, and one typo makes it worse

The default recovery strategy retries a context overflow exactly once, at iteration scope, with a ShrinkContext alteration, then aborts — the vendor's own test names are model_context_overflow_compacts_once_then_aborts and second_model_context_overflow_aborts_without_another_compaction. So hitting retry on the same oversized request cannot succeed. For scale, the same strategy's defaults allow max_model_availability_attempts: 12 and max_attempts_per_class: 2; this class gets the single ShrinkContext attempt.

Compaction will not save you earlier either: its trigger threshold is the same 108,000, so nothing forces a compaction before the transcript reaches it. Forced and recovery compactions do bypass the circuit breaker, which is the loop's only way to shrink an oversized prompt before a retry. A caveat on the alternative strategy: issue #5582, open since July 3, 2026, reports that ActiveTaskPreservingCompactionStrategy never reads the overflow flag. Which strategy a given deployment selects was not traced here.

One configuration hazard is worth checking before anything else. Progressive tool disclosure is read from REBORN_TOOL_DISCLOSURE, accepts off | compact | signatures | namespaces | bridged, and defaults to namespaces when unset or empty. Any other non-empty value — a typo, a stale true or on — silently resolves to Off, documented in the same file as the "Control arm: advertise every authorized schema." A non-UTF-8 value does the same. The only signal is a tracing::debug! line, and the effect is a materially larger tool prompt. Unset the variable rather than guessing at its spelling.

What you can actually change today

There is no published IronClaw documentation page covering the context budget, compaction or any of these four errors, so the levers below are what the docs and the code jointly support — not a vendor-blessed remedy.

The one documented lever that reduces skill-context pressure is a config flag, not an environment variable. IronClaw's skills page says to set it under [skills], and notes that keyword and tag activation plus explicit $my-skill mentions still inject skills:

[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

Three more, with their limits stated. A skill's max_context_tokens frontmatter field defaults to 2000 per the same documentation page, but writing a small number there does not shrink a large skill: when the body estimates at more than twice the declared value, the selector logs that it is "using actual estimate" and charges the measured size. A reactive routine can narrow its tool surface through allowed_tools, which is scoped to that routine and not to interactive turns. And file tools are off unless ALLOW_LOCAL_TOOLS=true: IronClaw's file-tools documentation says they are disabled by default "to prevent accidental filesystem access in hosted or shared environments", so leaving them off is one fewer set of schemas in the prompt. None of these three touches the 128,000.

Finally, do not plan around an obsolete number. Issue #7485 reported that the 108,000-token budget was "effectively ~54k real tokens" for ASCII content and that compaction fired "roughly 2× early". That was a double-count in one of two token estimators. PR #7502 unified them and merged on August 11, 2026; GitHub's compare API puts the merge commit inside the v1.3.0 and v1.4.0 tags and inside main. Against v1.2.0 and v1.1.0 the comparison returns "diverged", so the earliest release containing it is not established — say v1.3.0 and later. The single current estimator charges ASCII at 4 characters per token and roughly 1.5 tokens per 3-byte non-ASCII character, which means a CJK-heavy transcript fills 108,000 far faster than an English one.

What the ceiling costs per turn, and which route wins

This is illustrative token arithmetic, not a measured task cost and not a bill ceiling. Assume one maximally loaded turn: the transcript at its 108,000-token ceiling, 8,000 of identity, 4,000 of skill context (the selector's default budget; a composed runtime wiring 6,000 would raise this) and 3,843 of advertised tool schema from the recorded benchmark above — 123,843 estimated input tokens — plus 2,000 output tokens. Those are IronClaw's own estimates over a synthetic fixture, so a real provider tokenizer will disagree. Rates are live Kunavo catalog prices per million tokens.

The last column is the point of the section. A mistyped REBORN_TOOL_DISCLOSURE adds 17,512 estimated input tokens to every turn — on Claude Sonnet 4.6 that is $0.021 per turn before anything else changes, and an always-on agent takes many turns a day. The second reading is that paying for a long-context model to escape this does not work: IronClaw assembles to its own number regardless, so the extra window buys nothing while the higher rate bills on all 123,843 tokens. Multiply by your own turns per day before treating any of it as a budget.

Hosted plan lines read from ironclaw.com on September 21, 2026; ironclaw.com/pricing returns HTTP 404, so the plans live on the home page. The heading above all three cards reads "Spin up to 5 agents in a Trusted Execution Environment with up to 130M tokens per month" — five agents is the Pro+ maximum, so that heading states the top plan's ceiling rather than any one card's, and the 130M-token figure appears on no card at all. What the included credits convert to in tokens, and what happens when they run out, is not published and is not guessed at here.

Kunavo serves no embedding, text-to-speech or speech-to-text model, so any retrieval or voice step in your setup has to call an outside provider.

Try it, then read the charge

If you route IronClaw at an OpenAI-compatible gateway, Kunavo's chat-completions endpoint is the shape the openai_compatible provider id expects. That is a protocol match read from both sides' documentation — Kunavo has not runtime-tested IronClaw and makes no compatibility claim. Keep a working route available, run one bounded task, and reconcile against the usage your account recorded rather than against IronClaw's displayed cost, which is its own arithmetic. Kunavo's catalog amount is a billing floor rather than a cap: when the upstream reports its charge, the bill is the greater of catalog cost and upstream cost times the applicable markup. The minimum top-up is $10 in prepaid credit — a funding minimum, not a task fee or a subscription; see billing details, and create an account when you are ready to fund a key. For the surrounding choices, AI cost optimization covers measuring cost per finished task, and PicoClaw and ZeroClaw cover two sibling runtimes whose loop length is a cost lever in the same way.

FAQ

Checked September 21, 2026. Source constants, error strings, the recovery strategy, the token estimator, the disclosure modes and the benchmark baseline were read from nearai/ironclaw main at commit b0b999d through the GitHub contents API; issue and pull-request states through the GitHub issues API; the skills, configuration, storage and file-tools pages on docs.ironclaw.com and the plan cards on ironclaw.com by direct fetch. The v1.4.0 release tag was not checked out, no IronClaw instance was run, no test in the repository was executed, none of the four errors was reproduced firing, and Kunavo has not runtime-tested IronClaw. Kunavo token rates come from the live catalog, and every dollar figure is illustrative token arithmetic.