IronClaw 上下文预算超限：四个错误，一个硬编码数字

“Context budget exceeded”在 IronClaw 中并非一种错误。四种截然不同的错误变体都包含这段措辞，但它们都不是模型的上下文窗口；任何配置文件、环境变量或 CLI 标志都无法改变其中任何一种错误背后的数值。该预算是编译时内置的 128,000 个令牌，并预留 20,000 个令牌；挤占预算的三个部分——身份文件、技能片段和工具架构——是在该配额之上组装的，而不是包含在其中。这是 IronClaw 自身公开缺陷报告中的描述，并非本页面的推测。

先澄清一个容易混淆的名称。这是 github.com/nearai/ironclaw，NEAR AI 用 Rust 编写的代理运行时——不是该词的商业搜索结果中占据主导地位的 Corsair 游戏鼠标，也不是位于 ironclaw.tech、同样销售代理软件并将自身与 OpenClaw 比较的无关公司。IronClaw 与 OpenClaw 的对比对此作了完整区分。以下所有源代码级数据均通过 GitHub contents API，于 2026 年 9 月 21 日从 main 分支的 b0b999d 提交（提交于 2026 年 9 月 10 日）读取。该提交晚于 2026 年 8 月 28 日发布的 ironclaw-v1.4.0 发行标签。2026 年 10 月 1 日，较新的 ironclaw-v1.4.1 发布版二进制文件针对本地测试端点运行（该版本发布于 2026 年 9 月 29 日，是针对 Google OAuth 和 Wasmtime 的补丁，其发行说明未提及预算变化）；其行为记录如下，并限定于该版本，而源代码数据仍限定于该提交。

你正在查看的是哪一种“context budget exceeded”

这些是 Rust thiserror 显示字符串，也就是最终写入日志和错误详情的内容。阅读确切措辞即可判断哪个部分失败。

实际发生 模型溢出时，用户看到的内容不包含上述任何措辞。主机编写的失败投影是固定句子“The run failed because the model context was too large. Retry with a shorter request or start a new thread.”，而模型网关映射的提供商错误是“model request exceeded its context budget”。需要注意两点。本文没有追踪端到端运行，因此技能部分失败最终会投影成哪条面向用户的句子，目前无法确定。此外，广泛流传的字符串“Model request context exceeds the available input budget”在 nearai/ironclaw 中完全不存在；它属于另一个代理项目，不应据此诊断本项目。

无法配置的 128,000

PromptContextTokenBudget提供了三个常量：128,000 个令牌的上下文限制、20,000 个令牌的预留量，以及主循环最大输出值 0。可见记录长度等于该限制减去后两者中的较大值，因此为108,000 个令牌——这是根据默认值计算得出的结果，而不是文件中的字面量。第三项在测试之外从未被赋值，因此预留量始终固定为 20,000。仓库中所有非测试构造都是普通的 PromptContextTokenBudget::default()：一个位于压缩策略中，另一个位于循环驱动主机的 TextOnlyLoopHostConfig默认值中；所有携带不同数字的 ::new(…)调用都位于 #[cfg(test)]模块内。

IronClaw 自身的议题 #5739 在标题中就说明了这一点——“Effective context budget is a hardcoded 128K that ignores the model's context_length and has no config override”——该议题自 2026 年 7 月 6 日起开放，截至 2026 年 9 月 21 日仍未关闭。由此会产生三个容易踩坑的地方：

• budget.*键并不是这个设置。IronClaw 的配置页面在“budget — cost controls”标题下记录了 budget.user_daily_usd、budget.pause_at及其同类设置，并将其描述为限制代理支出的选项。它们是金额设置（其中两个，即 budget.overestimate_factor和budget.default_tz，分别是乘数和时区，而不是美元金额）。没有任何层级的键可以设置上下文限制、预留量、身份上限或技能预算；公布的优先级顺序是“compiled defaults < config.toml < environment variables < CLI flags”，因此不存在的键在任何位置都不存在。
• PR #5790是一个误导项。其标题提出了“通过 host factory 覆盖 prompt-context budget”。API 显示该 PR 于 2026 年 8 月 27 日关闭，状态为 merged: false。
• 这些修复都只是提案。检查时，#8053（将使用模型声明窗口的 90%，同时保留 20,000 个令牌）以及 #7976 和 #5435 均处于开放状态。

对于第三方端点，还需进一步分析，而且这一步具有决定性作用。ModelMetadata.context_length 是一个 Option，LlmProvider trait 的默认实现返回 None——“Default returns the model name with no size info”——通用的 OpenAI 兼容适配器没有覆盖实现，因此继承该默认值。因此，自定义端点根本不会声明上下文窗口大小。无论你的模型能容纳一百万个 token 还是 32,000 个 token，IronClaw 都会按 108,000 个对话记录 token 进行规划；而 #8053 将读取的正是该路径从未设置的字段。有关如何配置该端点，请参阅 IronClaw 自定义 API 设置；本页面继续聚焦于预算。

填充提示词但不触及预算的部分

IronClaw 的公开增强议题 #8057 于 2026 年 9 月 3 日提交，检查时仍处于开放状态。该议题用供应商自己的话说明了机制：提示词预算“只计算记录”，而身份内容、技能和记忆片段、频道上下文以及工具架构“是在记录配额之上组装的，不会减少该配额，因此提供商收到的请求可能超过循环认为自己遵守的预算”。这是缺陷报告，而不是已发布行为的文档；但它解释了为什么一次运行可能因大小失败，即使每个独立部分看起来都没有超限。

工具部分可以测量，IronClaw 也确实进行了测量。其针对合成的 93 工具测试装置提交的基准记录显示，在声明 22 个工具时，估算架构令牌数从 21,355 降至 3,843，降幅为 82.0%；仓库内通过 2.0 个百分点的漂移容差和 50.0% 的下限进行保护。这些数字来自测试文件，而不是本次运行测试的结果；已发布二进制文件的实测负载见上面的部分，其形态不同：是默认工具集，而不是 93 工具测试装置。应将它们理解为 IronClaw 对测试装置进行的内部字符数估算，而不是你的工具提示词，也不是提供商分词器的计数。诚实的解读在于其形态：渐进式披露移除了大部分架构，但仍留下几千个令牌的下限；由于 27 个核心名称在每种披露模式下都会声明，因此没有任何设置可以移除这一部分。

已发布的 1.4.1 二进制文件做了什么

2026 年 10 月 1 日，经校验和验证的 ironclaw-v1.4.1 发布二进制文件在一次性容器中运行，使用 [llm.default] 插槽，通过 openai_compatible 提供商连接到记录每个请求的本地测试服务器。每次运行仅发送一条短消息，并通过 ironclaw repl执行：

因此，在已发布构建中，下限确实存在：没有任何披露模式发送少于 26 个架构；按 IronClaw 自身每个令牌四个字符的估算，35,703 个字节在你的任何文字之前就约等于 8,900 个令牌，而系统消息和身份消息还会额外增加约 24,000 个字节。这是基于字节的算术，而不是提供商令牌计数。下文所述的拼写错误风险已得到确认，而非推测：true产生的负载与off完全相同，使工具提示词大小几乎翻倍，但屏幕上没有任何提示。

硬预算限制按源代码所述触发了。一个约 380,000 个字符的消息被发送到端点；一个约 460,000 个字符的消息——按每个令牌四个字符计算，超过 108,000 个令牌——从未离开机器。REPL 只打印了警告日志行，其中标明阶段 Prompt、类型 BudgetExceeded，以及摘要 accepted task exceeds the prompt context token budget。无论配置还是环境中，都没有找到可以改变该行的设置。技能部分错误、真实模型的溢出，以及通过 Kunavo 发出的任何请求均未运行。

重试不是修复方案，而且一个拼写错误会让情况更糟

默认恢复策略会在迭代范围内对上下文溢出恰好重试一次，并进行 ShrinkContext 修改，然后中止；供应商自身的测试名称是 model_context_overflow_compacts_once_then_aborts 和 second_model_context_overflow_aborts_without_another_compaction。因此，对同一个超大请求点击重试不可能成功。作为规模参考，同一策略的默认值允许 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；同一文件将其记录为“Control arm: advertise every authorized schema”。非 UTF-8 值也会产生相同结果。唯一的信号是一行 tracing::debug!，其影响是工具提示词明显变大。与其猜测变量拼写，不如取消设置该变量。

今天你实际可以改变什么

IronClaw 没有发布任何涵盖上下文预算、压缩或这四种错误的文档页面，因此下面列出的手段是文档和代码共同支持的内容，而不是供应商认可的解决方案。

唯一有文档说明、可以降低技能上下文压力的手段是配置标志，而不是环境变量。IronClaw 的技能页面称应在 [skills]下设置该标志，并指出关键词和标签激活以及显式的 $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；但在那里填写较小的数字并不会缩小大型技能：当正文估算值超过声明值的两倍时，选择器会记录“using actual estimate”，并按实测大小计费。响应式例程可以通过 allowed_tools缩小其工具范围，但该设置仅适用于该例程，不适用于交互式轮次。文件工具除非设置 ALLOW_LOCAL_TOOLS=true，否则处于关闭状态：IronClaw 的文件工具文档称，默认禁用它们是“为了防止托管或共享环境中的意外文件系统访问”，因此保持关闭就能让提示词中少一组架构。这三项都不会触及 128,000。

最后，不要根据已经过时的数字进行规划。议题 #7485 报告称，对于 ASCII 内容，108,000 个令牌的预算“实际上约为 54k 个真实令牌”，并且压缩“提前约 2 倍”触发。这是两个令牌估算器之一发生重复计数造成的。PR #7502将两者统一，并于 2026 年 8 月 11 日合并；GitHub compare API 显示，v1.3.0和v1.4.0标签对应的版本以及 main均包含该合并提交。与 v1.2.0和v1.1.0的比较结果为“diverged”，因此尚无法确定包含该修复的最早发行版；可表述为 v1.3.0 及更高版本。当前唯一的估算器按每个令牌 4 个字符计算 ASCII，并按每个 3 字节非 ASCII 字符约 1.5 个令牌计算，这意味着以 CJK 为主的记录会比英文记录快得多地填满 108,000。

每轮上限的成本，以及哪条路线更划算

这是说明性令牌算术，不是实测任务成本，也不是账单上限。假设一轮达到最大负载：记录达到 108,000 个令牌上限，身份内容占 8,000，技能上下文占 4,000（选择器的默认预算；组合运行时连接 6,000 时会提高该值），以及上方记录基准中的 3,843 个已声明工具架构令牌——即 123,843个估算输入令牌——再加上 2,000个输出令牌。这些是 IronClaw 针对合成测试装置的自身估算，因此真实提供商分词器会得出不同结果。费率是实时的 Kunavo 目录每百万令牌价格。

最后一列是本节的重点。一个拼写错误的 REBORN_TOOL_DISCLOSURE会使每一轮增加 17,512个估算输入令牌——在 Claude Sonnet 4.6上，这意味着每轮增加 $0.037，还未计入其他变化；而始终运行的代理每天会进行许多轮。第二个结论是，付费使用长上下文模型并不能解决这一问题：无论如何，IronClaw 都会组装到自身的数值，因此额外的窗口没有带来收益，而更高的费率却会对全部 123,843个令牌计费。在将任何数字视为预算之前，请乘以你每天的轮数。

托管方案信息于 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”——5 个代理是 Pro+ 的上限，因此该标题说明的是最高方案的上限，而不是某一张卡片的上限；130M 个令牌的数字也没有出现在任何卡片上。包含的额度可以兑换多少令牌，以及用完后会发生什么，均未发布，本文也未对此进行猜测。

Kunavo 不提供嵌入、文本转语音或语音转文本模型，因此你设置中的任何检索或语音步骤都必须调用外部提供商。

先运行，再查看费用

如果你将 IronClaw 路由到 OpenAI 兼容网关，Kunavo 的 chat-completions 端点就是 openai_compatible提供商 ID 所要求的形态。这是根据双方文档得出的协议匹配；上方 10 月 1 日的运行使用的是本地测试服务器，而不是 Kunavo，因此 Kunavo 不作兼容性声明。保留一条可用路由，运行一个范围有限的任务，并根据你的账户记录的使用量进行核对，而不是根据 IronClaw 显示的成本；后者是它自己计算的。Kunavo 目录金额是计费下限，而不是上限：上游报告费用时，账单取目录成本与上游成本乘以适用加价系数后的金额中的较大者。最低充值金额是$10的预付额度——这是资金充值最低额，不是任务费用或订阅费用；请参阅账单详情，准备为密钥充值时创建账户。关于周边选择，AI 成本优化介绍如何衡量每个已完成任务的成本；PicoClaw和ZeroClaw介绍两个同类运行时，其循环长度同样是影响成本的杠杆。

常见问题

2026 年 10 月 1 日运行：使用 ironclaw-v1.4.1 发布二进制文件连接本地测试服务器，得到上方的披露表和预算探测结果；同日重新检查了 #5739、#8053、#8057、#7976 和 #5435 的议题状态，全部仍处于开放状态。检查日期为 2026 年 9 月 21 日。源代码常量、错误字符串、恢复策略、令牌估算器、披露模式和基准基线均通过 GitHub contents API 从 nearai/ironclaw 的 main 分支在提交 b0b999d处读取；议题和拉取请求状态通过 GitHub issues API 读取；技能、配置、存储和文件工具页面从 docs.ironclaw.com 直接获取，方案卡片从 ironclaw.com 直接获取。未检出 v1.4.0 发行标签，未运行 IronClaw 实例，未执行仓库中的任何测试，未复现四种错误中的任何一种触发，且 Kunavo 尚未对 IronClaw 进行运行时测试。Kunavo 令牌费率来自实时目录，每个美元金额均为用于说明的令牌成本计算。