IronClaw 上下文預算超限：四種錯誤，一個寫死在程式碼中的數值

「Context budget exceeded」在 IronClaw 中並非單一錯誤。共有四種不同的錯誤變體帶有這段文字，但其中沒有任何一種是模型的 context window；任何設定檔、環境變數或 CLI 旗標都無法改變它們背後的數值。該預算是編譯時內建的 128,000 個 tokens，另保留 20,000 個 tokens；擠壓這項預算的三條通道——身分檔案、技能片段與工具 schema——是在這項額度之上組裝，而不是包含在其中。這是 IronClaw 自己公開的缺陷報告，不是本頁的推測。

先釐清名稱，因為這個名稱容易混淆。這裡指的是 github.com/nearai/ironclaw，NEAR AI 以 Rust 撰寫的代理執行環境——不是商業搜尋中以此名稱佔主導地位的 Corsair 電競滑鼠，也不是位於 ironclaw.tech、同樣銷售代理軟體且同樣拿自己與 OpenClaw 比較的無關公司。IronClaw 與 OpenClaw 比較會完整說明這項區別。以下所有原始碼層級數值，都是透過 GitHub 內容 API，於 2026 年 9 月 21 日從 main 的 commit b0b999d（2026 年 9 月 10 日提交）讀取。該 commit 比 2026 年 8 月 28 日發布的 ironclaw-v1.4.0 版本標籤更晚。2026 年 10 月 1 日，較新的 ironclaw-v1.4.1 發行版二進位執行檔（2026 年 9 月 29 日發布，是針對 Google OAuth 與 Wasmtime 的修補，版本說明未提及預算變更）對本機測試端點執行測試；它的行為記錄如下，適用範圍限於該版本，而原始碼數值則限於該 commit。

你看到的是哪一種「context budget exceeded」

這些是 Rust thiserror 顯示字串，也就是實際出現在日誌與錯誤詳細資訊中的文字。閱讀精確措辭即可判斷哪條通道失敗。

實際的 model 溢出所呈現給使用者的內容，不包含上述任何字詞。由 host 撰寫的固定失敗訊息是「The run failed because the model context was too large. Retry with a shorter request or start a new thread.」；model gateway 映射的 provider 錯誤則是「model request exceeded its context budget」。有兩點需要注意。本頁沒有追蹤端到端執行，因此技能通道失敗最終會映射成哪一則面向使用者的句子，尚未在此確定。此外，廣泛流傳的字串「Model request context exceeds the available input budget」在 nearai/ironclaw 中完全不存在；它屬於另一個 agent 專案，不應用來診斷這個專案。

你無法設定的 128,000

PromptContextTokenBudget 提供三個常數：128,000-token 的 context limit、20,000-token 的 reserve，以及 main loop 的 max-output 數值 0。可見 transcript 是該 limit 減去後兩者中較大者，因此為 108,000 tokens——這是根據預設值計算的結果，不是檔案中的字面值。第三項只在測試中被賦值，因此 reserve 永遠固定為 20,000。儲存庫中所有非測試建構都是一般的 PromptContextTokenBudget::default()——一個位於 compaction strategy，另一個是 loop driver host 的 TextOnlyLoopHostConfig 預設值；所有帶有不同數值的 ::new(…) 呼叫都位於 #[cfg(test)] 模組內。

IronClaw 自己的議題 #5739 在標題中就說明了這點——「實際上下文預算寫死為 128K，忽略模型的 context_length，且無法透過設定覆寫」——自 2026 年 7 月 6 日開啟，至 2026 年 9 月 21 日仍未關閉。由此會產生三個陷阱：

• budget.* keys 不是這個。 IronClaw 的設定頁面在標題為「budget — cost controls」的章節下，記錄了 budget.user_daily_usd、budget.pause_at 及其同類項目，並描述為限制 agent 支出的設定。它們是金錢設定（其中兩個——budget.overestimate_factor 與 budget.default_tz——是乘數與時區，而不是美元金額）。任何層級的 key 都無法設定 context limit、reserve、identity ceiling 或 skill budget；而已發布的優先順序為「compiled defaults < config.toml < environment variables < CLI flags」，因此不存在的 key 在所有地方都不存在。
• PR #5790 是錯誤線索。它的標題提出「透過主機工廠覆寫提示上下文預算」。API 顯示它已於 2026 年 8 月 27 日關閉，狀態為 merged: false。
• 這些修正全都只是提案。 #8053 提議採用模型宣告的上下文視窗大小的 90%，並保留相同的 20,000 預留量；它與 #7976、#5435 在檢查時都仍未關閉。

對第三方端點而言，還有一個步驟，而且它是決定性的。ModelMetadata.context_length 是一個 Option，LlmProvider 特徵的預設實作會回傳 None——「預設會回傳模型名稱，不含大小資訊」——而通用的 OpenAI 相容轉接器沒有定義覆寫，因此會繼承該預設實作。所以自訂端點完全不會宣告上下文視窗大小。無論你的模型能容納 100 萬還是 32,000 個 token，IronClaw 都會以 108,000 個轉錄 token 為規劃基準，而 #8053 要讀取的正是這條路徑從未設定的欄位。端點設定方式請參閱 IronClaw 自訂 API 設定；本頁聚焦於預算。

填入 prompt 卻不觸及預算的通道

IronClaw 尚未關閉的功能增強議題 #8057 於 2026 年 9 月 3 日提出，檢查時仍未關閉；它用供應商自己的話說明了機制：提示預算「只計算轉錄的大小」，而身分內容、技能與記憶片段、頻道上下文及工具結構描述「會在轉錄配額之上組裝，不會扣減該配額，因此供應商收到的請求可能超過迴圈認為自己遵守的預算」。這是缺陷報告，而非已發布版本行為的說明文件——但它解釋了為何每個部分各自看似遵守限制，執行仍可能因大小而失敗。

工具部分可以測量，而 IronClaw 確實會測量。它已提交的基準測試使用含 93 個工具的合成測試資料，記錄了在宣告 22 個工具時，結構描述的估算 token 數從 21,355 降至 3,843——降幅為 82.0%；儲存庫內以 2.0 個百分點的漂移容許度與 50.0% 的降幅下限進行檢查。這些數字是從測試檔案讀取的，並非在此執行測試所得——已發布二進位執行檔的實測請求內容位於上方章節，其組成不同：是預設工具集，而不是含 93 個工具的測試資料。請將這些數字視為 IronClaw 對測試資料進行的內部字元數估算，不要視為你的工具提示，也不要視為供應商 token 分詞器的計數。忠實的解讀在於整體組成：漸進式揭露移除了大部分結構描述，但仍留下數千個 token 的最低用量，沒有任何設定能移除它，因為 27 個核心工具名稱在每種揭露模式下都會宣告。

已發布的 1.4.1 binary 做了什麼

2026 年 10 月 1 日，經校驗和驗證的 ironclaw-v1.4.1 發行版二進位執行檔在一次性容器中執行；其 [llm.default] 設定區塊使用 openai_compatible 供應商，並指向會記錄每個請求的本機測試伺服器。每次執行都透過 ironclaw repl 傳送一則短訊息：

因此，在已發布的 build 中，下限是真實存在的：任何揭露模式傳送的 schema 都不少於 26 個；按 IronClaw 自己每 token 四個字元的估算，35,703 bytes 約等於 8,900 tokens，且尚未包含你的任何一個字。系統與身分訊息還會額外增加約 24,000 bytes。這是對 bytes 的算術，不是 provider token count。下方描述的拼字錯誤風險已獲確認，而非推測：true 產生的 payload 恰好與 off 相同，使 tool prompt 幾乎加倍，畫面上卻沒有任何提示。

硬性預算如原始碼所述確實被觸發。一則約 380,000 個字元的訊息被送往端點；一則約 460,000 個字元的訊息——按每 token 四個字元計算，已超過 108,000 tokens——則從未離開機器。REPL 只印出警告日誌行，標示 stage Prompt、kind BudgetExceeded 以及摘要 accepted task exceeds the prompt context token budget。在設定或環境中都沒有找到能移動這條界線的設定。技能通道錯誤、真實模型的溢出，以及任何經由 Kunavo 發出的 request 都未執行。

重試不是修正方法，而一個拼字錯誤會讓情況更糟

預設 recovery strategy 會在 iteration scope 中對 context overflow 恰好重試一次，使用 ShrinkContext 變更，然後中止；供應商自己的測試名稱是 model_context_overflow_compacts_once_then_aborts 與 second_model_context_overflow_aborts_without_another_compaction。因此，對同一個超大 request 觸發重試不可能成功。作為規模比較，同一策略的預設值允許 max_model_availability_attempts: 12 與 max_attempts_per_class: 2；此類別只會取得一次 ShrinkContext 嘗試。

上下文壓縮也不會更早解救你：其觸發閾值就是同一個 108,000，因此在轉錄達到該值之前，沒有任何機制會強制執行壓縮。強制壓縮與復原壓縮確實會繞過斷路器，而這是迴圈在重試前縮小過大提示的唯一方式。至於替代策略，有一點需要注意：自 2026 年 7 月 3 日起一直未關閉的議題 #5582 回報，ActiveTaskPreservingCompactionStrategy 從未讀取溢位旗標。這裡沒有追蹤各個部署選用哪一種策略。

在其他操作前，值得先檢查一項設定風險。漸進式工具揭露從 REBORN_TOOL_DISCLOSURE 讀取，接受 off | compact | signatures | namespaces | bridged；未設定或為空時，預設為 namespaces。任何其他非空值——拼字錯誤、過時的 true 或 on——都會靜默解析為 Off；同一檔案將其記錄為「對照組：宣告每個已授權的結構描述」。非 UTF-8 值也會得到相同結果。唯一的訊號是 tracing::debug! 行，而效果是工具提示顯著變大。請取消設定該變數，不要猜測其拼法。

今天實際可以改變的內容

目前沒有任何已發布的 IronClaw 文件頁面涵蓋 context budget、compaction 或這四種錯誤，因此下列可調整項目是文件與原始碼共同支援的內容，而不是供應商認可的解決方案。

唯一有文件記載、能降低 skill-context 壓力的調整項目是 config flag，而不是環境變數。IronClaw 的skills 頁面指出應在 [skills] 下設定，並註明 keyword 與 tag activation，以及明確的 $my-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

另外三項，以及其限制如下。根據同一文件頁面，技能的 max_context_tokens frontmatter 欄位預設為 2000，但在那裡寫入較小數值並不會縮小大型技能：當 body 的估算值超過宣告值兩倍時，selector 會記錄「using actual estimate」，並按測得的大小計費。Reactive routine 可透過 allowed_tools 縮小其工具範圍；這只套用於該 routine，不套用於互動回合。除非設定 ALLOW_LOCAL_TOOLS=true，file tools 都會關閉：IronClaw 的 file-tools 文件指出，預設停用它們是「為了防止在託管或共用環境中意外存取檔案系統」，因此保持關閉就能少一組 prompt 中的 schema。這三項都不會觸及 128,000。

最後，不要依賴已過時的數字。議題 #7485 回報，對 ASCII 內容而言，108,000 個 token 的預算「實際上約為 54,000 個真正的 token」，且上下文壓縮「大約提早 2 倍」觸發。原因是兩個 token 估算器其中之一重複計數。PR #7502 統一了兩者，並於 2026 年 8 月 11 日合併；GitHub 的比較 API 顯示其合併 commit 包含於 v1.3.0 與 v1.4.0 版本標籤中，也包含於 main 中。相對於 v1.2.0 與 v1.1.0，比較結果為「diverged」，因此包含該修正的最早發行版本尚未確定——請表述為 v1.3.0 及更新版本。目前唯一的估算器以每個 token 4 個字元計算 ASCII，並以每個 3 位元組的非 ASCII 字元約 1.5 個 token 計算，這表示以中日韓文字為主的轉錄會比英文轉錄快得多地填滿 108,000 的額度。

每回合的上限成本，以及哪條路徑勝出

這是說明性的 token 算術，不是測得的工作成本，也不是帳單上限。假設一個負載達到最大值的回合：transcript 達到 108,000-token 上限、8,000 個 identity tokens、4,000 個 skill context tokens（selector 的預設預算；使用 6,000 的 composed runtime 會提高此數值），以及上方記錄 benchmark 中 3,843 個宣告工具 schema tokens——123,843 個估算 input tokens——再加上 2,000 個 output tokens。這些是 IronClaw 對合成 fixture 的自身估算，因此真實 provider tokenizer 會有不同結果。費率是即時的，每百萬 tokens 的 Kunavo catalog 價格。

本節的重點在最後一欄。拼錯的 REBORN_TOOL_DISCLOSURE 會在每個回合增加 17,512 個估算 input tokens——在 Claude Sonnet 4.6 上，這代表每回合增加 $0.037，其他因素尚未改變，而長時間運作的 agent 一天會執行許多回合。第二個解讀是：付費使用長 context 模型來避開這個問題並不可行。IronClaw 無論如何都會組裝到自己的數值，因此額外的 window 沒有帶來任何收益，卻會按較高費率對全部 123,843 tokens 計費。在把任何數字當成預算前，請乘上你每天自己的回合數。

2026 年 9 月 21 日從 ironclaw.com 讀取的託管方案內容；ironclaw.com/pricing 回傳 HTTP 404，因此方案資訊位於首頁。三張卡片上方的標題寫著「Spin up to 5 agents in a Trusted Execution Environment with up to 130M tokens per month」——五個代理是 Pro+ 的最大值，因此該標題陳述的是最高階方案的上限，而不是任何單一卡片的上限；1.3 億個 token 的數值也完全沒有出現在任何卡片上。內含額度可換算成多少 token，以及額度用完後會發生什麼事，都未公開，本頁也不對此猜測。

Kunavo 不提供 embedding、text-to-speech 或 speech-to-text 模型，因此你設定中的任何 retrieval 或 voice 步驟都必須呼叫外部供應商。

先試用，再閱讀費用

如果你將 IronClaw 路由至與 OpenAI 相容的閘道，Kunavo 的 chat-completions 端點 就符合 openai_compatible 提供者識別碼所預期的格式。這是根據雙方文件確認的通訊協定相符——上方 10 月 1 日的執行使用的是本機測試伺服器，而不是 Kunavo，因此 Kunavo 不作相容性聲明。請保留一條可用的路由，執行一項範圍有限的任務，並與帳戶記錄的用量核對，而不是與 IronClaw 顯示的成本核對，因為後者是它自行計算的結果。Kunavo 的目錄金額是計費下限，而不是上限：當上游回報其費用時，帳單金額會取目錄成本與上游成本乘以適用加成兩者中的較大者。最低儲值金額為$10 的預付額度——這是最低入金額，不是任務費用或訂閱；請參閱計費詳細資訊，準備為 API 金鑰儲值時再建立帳戶。關於相關選擇，AI 成本最佳化說明如何衡量每項完成任務的成本，而 PicoClaw 與 ZeroClaw 則介紹兩個同類的執行環境，其迴圈長度同樣是調整成本的槓桿。

常見問題

2026 年 10 月 1 日執行：以 ironclaw-v1.4.1 發行版執行檔對本機測試伺服器執行——結果見上方的揭露表與預算探測；#5739、#8053、#8057、#7976 和 #5435 的議題狀態於同日重新檢查，全部仍為開啟。2026 年 9 月 21 日檢查。原始碼常數、錯誤字串、復原策略、token 估算器、揭露模式與基準測試基線，都是透過 GitHub contents API 從提交版本 b0b999d 的 nearai/ironclaw main 讀取；議題與提取要求的狀態則透過 GitHub issues API 讀取；docs.ironclaw.com 上的技能、設定、儲存與檔案工具頁面，以及 ironclaw.com 上的方案卡片，皆以直接擷取取得。未簽出 v1.4.0 發行標籤，未執行任何 IronClaw 執行個體，未執行儲存庫中的任何測試，四種錯誤均未重現觸發，Kunavo 也未對 IronClaw 進行執行時測試。Kunavo 的 token 費率來自即時目錄，所有美元數字都是用於說明的 token 費用計算。