Claude Code 2.1.323:未知模型 1M 上下文报错与网关修复

Claude Code 2.1.323 将未识别模型 ID 的默认上下文窗口从 200K 提高到 1M token。如果第三方模型或网关的实际窗口更小,长会话可能因为自动压缩触发过晚而连续失败。本文说明 2.1.325 的后续修复、CLAUDE_CODE_MAX_CONTEXT_TOKENS 和 CLAUDE_CODE_DISABLE_1M_CONTEXT 的适用条件、/autocompact 的优先级,以及 BetterToken 接入 DeepSeek、Kimi 的配置示例和故障会话恢复步骤。

本文内容
Claude Code 2.1.323:未知模型 1M 上下文报错与网关修复

Claude Code 2.1.323 将未识别模型 ID 的默认上下文窗口从 200K 提高到了 1M token。如果第三方模型或 API 网关实际只能接收更少的 token,Claude Code 可能迟迟不压缩对话,直到请求开始每轮报错。先升级到 Claude Code 2.1.325 或更高版本,再按模型的真实上下文窗口设置限制,或提前触发自动压缩。

具体怎么修,要看模型和网关实际允许的上下文长度。不要把所有 DeepSeek、GLM、Kimi 会话都直接限制到 200K。有些模型本身支持 1M token,不必要地缩小窗口,会让 Claude Code 过早压缩仍然有用的项目上下文。

下面依次说明 2.1.323 至 2.1.325 的变化、哪些模型 ID 可能受影响、三种修复方式,以及已经连续失败的会话如何恢复。

Claude Code 2.1.323、2.1.324 和 2.1.325 分别改了什么?

2.1.323 引入了未知模型默认按 1M 计算的行为。随后发布的 2.1.324 和 2.1.325,又针对模型 ID 判断和网关上下文错误进行了修复。

Claude Code 官方 CHANGELOG记录了以下变化:

版本与上下文相关的变化建议操作
2.1.323未识别模型 ID 的假定上下文窗口由 200K 改为 1M token。开始长会话前,确认模型的真实限制。
2.1.323使用上下文窗口较小的其他厂商模型时,历史填满后可能每一轮都失败,直到执行 /clear。在历史填满前配置正确的窗口。
2.1.324CLAUDE_CODE_MAX_CONTEXT_TOKENS 也能应用于以 claude- 开头的未知模型 ID。如果网关使用这种未知别名,先更新客户端。
2.1.325修复了许多第三方网关及 Foundry 部署中,会话不执行压缩、反而每轮返回上下文长度错误的问题。先尝试升级,再考虑其他变通方案。

截至 2026-11-15,npm 上 @anthropic-ai/claude-code 的 latest 标签对应 2.1.325,stable 标签对应 2.1.311。

stable 版本 2.1.311 尚未引入 2.1.323 的默认值变化,但也不包含后续修复。

先在终端检查当前安装的版本:

claude --version

如果通过原生安装程序安装了 Claude Code,可以使用官方提供的更新命令:

claude update
claude --version

如果你有意使用 stable 渠道,不要因为 latest 发布了新版本,就认定现有客户端也采用了新行为。调整设置前,应先确认实际运行的版本。

另外,2.1.325 的 CHANGELOG 只说修复了许多网关上的重复错误,并没有保证所有网关都能恢复,也不代表客户端能自动识别上游部署的实际上下文上限。

为什么未知模型 ID 会让长会话连续失败?

Claude Code 会根据自己认识的模型及本地配置,判断何时压缩对话历史。

自动压缩会将较早的消息整理成摘要,让下一次请求能够放进模型的上下文窗口。如果网关提供的是自定义模型 ID,Claude Code 可能无法识别背后的实际模型。

假设某个网关提供 my-coding-model,但这条 API 路由实际只能接受 200,000 token。

在 2.1.323 之前,Claude Code 会为这个未知 ID 假定 200K 上下文。从 2.1.323 开始,只要没有其他配置覆盖,就会假定 1M。

模型和网关本身并没有获得更大的容量,变化的只是 Claude Code 对窗口大小的估计。

当对话历史超过网关实际允许的长度时,API 可能拒绝请求。失败后,过长的历史仍留在当前会话中。下一轮继续使用这些历史,就可能再次触发同样的错误。

Anthropic 在 2.1.323 的更新日志中明确描述了这个问题。2.1.325 改善了许多网关的恢复行为,但对于实际窗口较小的路由,仍然需要配置正确的限制。

哪些模型 ID 可能受到影响?

关键条件不是模型名称是否陌生,而是 Claude Code 假定的上下文窗口是否大于这条 API 路由实际能够接收的窗口。

需要检查的常见情况包括:

  • 非 Claude 模型 ID,例如 deepseek-v4.1-flash-1017 或 kimi-k3.1-pro,前提是 Claude Code 不认识这些 ID。
  • 网关自定义别名,例如 my-coding-model。即使上游实际使用的是 Claude 模型,也可能被视为未知 ID。
  • 以 claude- 开头但未被识别的 ID,例如 claude-sonnet-latest。2.1.324 改变了此类 ID 的窗口覆盖规则。
  • 带有 [1m] 后缀的 ID。这类名称需要遵守单独的覆盖规则。

模型 ID 未被识别,并不等于上下文一定配置错误。

如果模型及其 API 路由确实支持 1M token,新默认值可能完全合适。只有模型、网关或实际部署施加了更低的限制,才会出现窗口不匹配的问题。

还要区分未知别名与可识别的 Claude 模型 ID。有时 Claude Code 能从第三方提供的复合 ID 中识别出 Anthropic 模型名称。环境变量的生效方式取决于它最终如何解析该 ID。

不要只看名称前缀就决定设置。请先参考 Anthropic 的网关与自定义模型 ID 上下文配置文档。

应该选择哪种上下文窗口修复方式?

如果已确认网关的真实上限,并且模型 ID 允许覆盖,优先使用 CLAUDE_CODE_MAX_CONTEXT_TOKENS。如果只是想快速恢复 200K 限制,可以使用 CLAUDE_CODE_DISABLE_1M_CONTEXT=1。如果希望在触及上限前留出余量,则应提前触发自动压缩。

修复方式适用场景限制或代价
CLAUDE_CODE_DISABLE_1M_CONTEXT=1模型或网关实际窗口至少为 200K,希望快速恢复旧限制。会把某些真正支持 1M 的模型也限制到 200K。对于小于 200K 的窗口,单独设置它还不够。
CLAUDE_CODE_MAX_CONTEXT_TOKENS已确认未知模型或网关别名的实际上下文窗口。是否生效取决于模型 ID 的识别结果、客户端版本和 [1m] 后缀。
/autocompact、--autocompact 或 CLAUDE_CODE_AUTO_COMPACT_WINDOW希望在到达假定窗口上限前,提前压缩对话。文档规定的可配置范围从 100K 开始,必须选择符合上游真实限制的阈值。

这三类设置不能完全互相替代。第一类施加 200K 限制,第二类改变 Claude Code 假定的模型容量,第三类决定自动压缩何时触发。

方法 1:恢复 200K 限制

如果模型或网关实际至少支持 200K token,可以在 Bash 中设置变量后启动 Claude Code:

export CLAUDE_CODE_DISABLE_1M_CONTEXT=1
claude

这正是 Anthropic 在 2.1.323 CHANGELOG 中提出的临时解决办法。

如果希望设置在后续启动时继续生效,可以将变量写入 ~/.claude/settings.json 的 env 字段:

{
  "env": {
    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1"
  }
}

开启该设置后,Claude Code 还会从模型选择器中移除 [1m] 变体。

对于原生支持 1M 窗口的模型,开启自动压缩后,Claude Code 会把会话限制在 200K 边界。如果关闭自动压缩,达到相应边界时则会报上下文限制错误,而不是压缩历史。

但未知模型 ID 存在例外:其他设置可能使 200K 限制无法真正执行。

如果看到以下警告:

CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced for <model>, so this session can grow past it.

需要检查是否把 CLAUDE_CODE_MAX_CONTEXT_TOKENS 提高到了 200K 以上,或者关闭了未知模型的窗口限制机制。

Anthropic 的错误处理文档建议:如果必须在 200K 边界执行压缩,可以设置 CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000。

如果网关实际只能接受不到 200K token,就不能只依赖 CLAUDE_CODE_DISABLE_1M_CONTEXT=1。

方法 2:通过 CLAUDE_CODE_MAX_CONTEXT_TOKENS 设置真实窗口

当网关的实际上下文限制已知时,直接告诉 Claude Code 这个值通常更准确。

假设网关管理员确认,某条自定义模型路由最多接受 200,000 token。可以在启动 Claude Code 的 Bash 环境中执行:

export CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000
claude

这里的 200,000 只是用于说明设置方式的假设值,并不是适用于所有模型的推荐限制,也不是 DeepSeek、GLM 或 Kimi 的通用上限。

对于不以 claude- 开头、也没有 [1m] 后缀的未知 ID,该变量可以直接生效。Claude Code 仍会根据声明的窗口进行提前自动压缩。

Anthropic 的上下文覆盖适用规则还说明了两种特殊情况:

  • 如果未知 ID 包含 [1m],要将其修正为更小的窗口并保留提前自动压缩,还需要同时设置 CLAUDE_CODE_DISABLE_1M_CONTEXT=1。
  • 如果 ID 最终被解析为 Claude Code 已认识的 Claude 模型,只有同时设置 DISABLE_COMPACT,窗口覆盖才会生效。但 DISABLE_COMPACT 会完全关闭压缩,因此不适合作为普通长会话的首选修复方式。

从 2.1.324 开始,以 claude- 开头的未知 ID 也支持直接覆盖上下文窗口。更旧的版本可能采用不同的处理方式。

如果网关只是给真正的 Claude 模型起了另一个名字,可以使用文档中的 modelOverrides 或 modelPicker.behavesAs,将网关别名映射到已识别的 Claude 模型。

不要为了消除未知模型警告,就把真正的非 Claude 模型伪装成 Claude。

这里最重要的是当前所选 API 路由的实际有效上限,包括网关额外施加的较小限制。如果代理只允许更短的上下文,就不能直接照搬模型宣传资料中的最大窗口。

方法 3:使用 /autocompact 提前压缩

将自动压缩阈值设得更低,可以让 Claude Code 在网关拒绝请求前有机会整理对话历史。

对于已确认真实窗口为 200K 的路由,可以参考下面这个留有余量的示例:

/autocompact 150k

在 Claude Code 会话内部执行该命令。正常情况下,它会把当前模型的阈值保存到 modelSettings,并立即应用到当前会话。

执行后一定要查看 /autocompact 的回复,确认当前实际使用的阈值。 如果存在更高优先级的配置,例如管理员统一管理的设置,即使命令保存了你指定的值,当前会话仍可能继续使用另一阈值。Claude Code 会在命令回复中说明这种覆盖情况。

如果管理员设置阻止了新阈值生效,可以请管理员检查相关策略。根据 Anthropic 的自动压缩配置文档,单次启动使用的 --autocompact 参数不会被管理员设置覆盖。

只想对一次启动生效,可以使用:

claude --autocompact 150k

如果在脚本、容器或其他自动化环境中,更适合通过环境变量统一设置,可以使用:

export CLAUDE_CODE_AUTO_COMPACT_WINDOW=150000
claude

/autocompact 命令和 --autocompact 参数接受 100K–1M token 的窗口值。环境变量 CLAUDE_CODE_AUTO_COMPACT_WINDOW 接受 100000 到 1000000 的数值。

只要该环境变量的值有效且未被 Claude Code 忽略,它的优先级就高于会话命令、启动参数和已保存设置。此时执行 /autocompact,客户端会报告环境变量覆盖,而不会保存新的阈值。

如果希望为所有模型设置通用阈值,可以在 ~/.claude/settings.json 中使用 autoCompactWindow。不过,在同一配置作用域内,通过 /autocompact 为某个模型保存的值会优先于这个通用字段。

150k 只是针对真实上限为 200K 的网关提供的安全余量示例,不能推断它适合窗口更小的模型。

文档规定的最小可配置值是 100K。如果模型窗口小于 100K,应进一步检查模型 ID 的覆盖规则和客户端的实际行为,不要假定 /autocompact 50k 受到支持。

BetterToken 示例:在 Claude Code 中接入 DeepSeek 或 Kimi

BetterToken 为支持的模型提供 Anthropic 兼容 API,基础地址是 https://bettertoken.ai。用于 Claude Code 的 ANTHROPIC_BASE_URL 不需要添加 /v1。

这里必须区分 BetterToken 的第三方接入说明与 Anthropic 的官方支持范围。Anthropic 在LLM 网关文档中明确表示,不支持通过任何网关将 Claude Code 路由到非 Claude 模型。

BetterToken 有自己的第三方接入文档,但这不代表 Anthropic 官方支持 Claude Code 使用 DeepSeek 或 Kimi。需要分别验证所选路由的模型兼容性、工具调用行为和网关限制。

根据 2026-11-15 核对的 BetterToken 模型记录及文档,可以作出以下区分:

BetterToken Model ID公布的模型上下文窗口Anthropic Messages 路由
deepseek-v4.1-flash-10171M token已列出
kimi-k3.1-pro1M token已列出
glm-5.31M token该模型未列出;当时的结构化记录列有 OpenAI 兼容接入
qwen3.8-max1,000,000 token该模型未列出;当时的结构化记录列有 OpenAI 兼容接入

这些模型公布的上下文窗口并不一定小于 Claude Code 新的 1M 假定值。不过,实际有效窗口仍可能因提供商和 API 路由而不同。

模型出现在 BetterToken 目录中,也不意味着它支持所有 API 协议。为 Claude Code 选择路由前,应检查当前模型目录。

下面的 Bash 示例使用已列出 Anthropic 兼容路由的 DeepSeek 模型 ID,配置方式参考 BetterToken 的Claude Code 接入指南。

先安装 Claude Code,并在 BetterToken 控制台创建自己的 API Key。然后在单独的 Bash shell 中运行:

read -rs BETTERTOKEN_API_KEY && export BETTERTOKEN_API_KEY

export ANTHROPIC_BASE_URL="https://bettertoken.ai"
export ANTHROPIC_AUTH_TOKEN="$BETTERTOKEN_API_KEY"
export ANTHROPIC_MODEL="deepseek-v4.1-flash-1017"

export ANTHROPIC_DEFAULT_HAIKU_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$ANTHROPIC_MODEL"

unset CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT

claude -p "Reply with only: OK"
claude

第一条命令等待输入时,粘贴刚在 BetterToken 控制台创建的 API Key,然后按 Enter。密钥不会显示在屏幕上,也没有直接写进命令行字符串或 shell 历史。

ANTHROPIC_AUTH_TOKEN 用于向 Claude Code 提供认证信息。三个 ANTHROPIC_DEFAULT_*_MODEL 变量把内置的 Haiku、Sonnet 和 Opus 角色都映射到选定的 BetterToken 模型。以后也可以为不同角色指定其他受支持的模型。

如果想改用 Kimi,应该在执行三个角色变量的 export 之前,就把 ANTHROPIC_MODEL 设为 kimi-k3.1-pro。

如果你已经运行了上面的 DeepSeek 配置,需要在同一个 Bash shell 中重新执行下面全部四条命令,然后再启动新的 Claude Code 进程:

export ANTHROPIC_MODEL="kimi-k3.1-pro"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$ANTHROPIC_MODEL"

只修改 ANTHROPIC_MODEL,不会自动更新之前已导出的三个角色变量。它们仍然会指向 DeepSeek。BetterToken 的Kimi K3.1 Pro 文档说明了这个模型 ID 及其 Claude Code 接入方式。

对于没有 [1m] 的未知 ID,还可以明确设置已经核实的上下文窗口。如果所选路由确实接受 1,000,000 token,可以使用:

export CLAUDE_CODE_MAX_CONTEXT_TOKENS=1000000

要在启动 Claude Code 之前设置该变量。如果网关的实际上限更低,就把 1000000 换成经过确认的限制。必要时还可以提前触发自动压缩。

不要把下面这个示例不加验证地直接用于 DeepSeek 或 Kimi:

# Example only: the gateway's verified limit is 200000 tokens.
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000
export CLAUDE_CODE_AUTO_COMPACT_WINDOW=150000

第一条设置假定的有效上下文窗口,第二条让自动压缩提前执行,留出一定余量。换成其他网关时,需要分别确认这两个值。

如何验证模型和网关请求路由?

启动 Claude Code 后,执行:

/status

检查 Anthropic base URL 是否显示 https://bettertoken.ai,并确认认证来源是 ANTHROPIC_AUTH_TOKEN,而不是之前保存的 claude.ai 账号登录状态。

接着检查当前启用的模型。必要时,可以使用 /model 选择目标 ID。如果刚修改了模型角色变量,需要重新启动 Claude Code,让新进程读取更新后的环境变量。

前面执行的 claude -p "Reply with only: OK" 用于检查基本网络连接和模型访问权限。收到正常回复,说明短请求已经成功,但不能证明这条路由支持长上下文,更不能证明它能处理完整的 1M token。

要做更贴近编程任务的检查,可以让 Claude Code 读取仓库中的一个小文件,并在不修改文件的前提下解释某个具体函数。随后核对回复是否引用了正确的文件。

如果短请求就出现连接或认证错误,应先单独解决这类问题。Claude Code 网关 403 错误排查指南介绍了另一类故障的诊断方法。

如果需要更完整的 DeepSeek 配置及模型选择检查,可以参考Claude Code 接入 DeepSeek Flash 或 Pro 指南。Kimi 的特定行为可参考Kimi K3.1 Pro 编程指南。

如果当前会话已经每轮报错,该怎么恢复?

先判断网关是否因为上下文过长而拒绝请求。2.1.323 的 CHANGELOG 描述了连续失败的问题,但没有给出适用于所有网关的统一错误字符串。

不同网关可能返回不同的报错格式。Anthropic 的网关故障排查文档列出了这样的例子:

ContextWindowExceededError

以及:

prompt token count of N exceeds the limit of M

这些都是网关侧可能出现的错误文本,并不代表 2.1.323 引发的问题一定会返回这些字符串。

建议按照尽量保留现有工作的顺序尝试恢复:

  1. 如果当前会话内容还能查看,先把任务状态保存到对话之外。记录已经修改的文件、测试结果和下一步计划。
  2. 将 Claude Code 更新到 2.1.325 或更高版本,并确认当前实际安装的版本。
  3. 核实网关的真实上下文限制。在重新启动前设置 CLAUDE_CODE_MAX_CONTEXT_TOKENS 或合适的自动压缩阈值。
  4. 如果当前会话仍能接受命令,尝试手动运行 /compact。
  5. 如果既无法压缩,也无法继续对话,再执行 /clear,然后根据之前保存的任务状态恢复工作。

如果网关把上游的上下文超限错误改写成 Claude Code 无法识别的文本,客户端可能不会自动执行压缩和重试。

2.1.325 修复了许多这类重复失败问题,但 CHANGELOG 没有列出所有已支持的网关和路由。

如果手动压缩也失败,可以进一步参考Claude Code 与 DeepSeek 输入长度超限恢复指南。

不要把 CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 当成通用修复办法。Anthropic 文档说明,这个变量会让未知模型 ID 跳过提前自动压缩,转而等待一个客户端能够识别的 API 错误。如果网关改写了错误格式,恢复可能反而更不可靠。

为什么有些旧文档还说未知模型使用 200K?

这是因为相关文档在版本发布期间发生过更新。

2026-11-13 获取的模型配置说明仍写着:未知模型 ID 默认按 200K 计算。但在 2026-11-15 检查在线模型配置文档时,其中的未知模型警告已经变成了 context assumed to be 1m tokens。

因此,不要再把旧文档中的 200K 提示当成当前行为的依据。应该检查本机实际安装的 Claude Code 版本、当前会话真正显示的警告,以及最终生效的环境变量和设置。

如果模型已经被识别,或者 Claude Code 接受了你声明的上下文窗口,未知模型警告可能消失。这只能说明客户端配置已生效,不能证明网关确实能处理达到该长度的请求。

不同场景下推荐怎么配置?

如果未知模型通过网关接入,而网关的实际窗口小于 1M,建议使用 Claude Code 2.1.325 或更高版本,并明确设置已核实的上下文上限。如果需要为模型输出预留空间,再设置更早的自动压缩阈值。

如果网关明确限制为 200K,CLAUDE_CODE_DISABLE_1M_CONTEXT=1 可以作为快速变通方案。若希望控制得更准确,最好分别声明真实窗口和提前压缩的阈值。

如果模型与所选 API 路由确实支持 1M,就不必无故缩小窗口。只有希望缩短会话历史,或者网关施加了更低限制时,才需要主动降低。

如果未知 ID 带有 [1m] 后缀,或者 ID 被识别为已知 Claude 模型,应遵循 Anthropic 文档中的单独规则。不能认为只设置 CLAUDE_CODE_MAX_CONTEXT_TOKENS 就能覆盖所有 ID。

最终要匹配的是实际 API 路由能够接受的上下文长度,而不是 Claude Code 对模型容量的默认估计。

BetterToken · 企业采购
企业专属价
支持开发票对公转账 / 支付宝 / 微信支付全系列文本 / 编程、图像、视频模型
文本 / 编程
图像
视频
专属技术支持领取企业折扣价目表 →