Claude Code 报 exceeded the 32000 output token maximum 怎么解决
让 Claude Code 实现一个稍微大点的功能，跑了一会儿，蹦出这么一句：
API Error: Claude's response exceeded the 32000 output token maximum.
活干到一半停了，前面的思考也白费了。GitHub 上 issue #24055（仍开放）就是这条。
这篇讲清楚三件事：这个 32000 是什么、怎么调、以及为什么调高它不一定是你想要的答案。
一、32000 是单次响应的输出上限
先分清两个容易混的概念：
- 上下文窗口：一次请求里，输入 + 输出总共能占多少
- 输出上限：单次响应最多能生成多少 token
这条报错说的是后者。你的上下文可能还很空，照样能撞上——因为它限制的是「这一次它能一口气写多长」，不是「一共装得下多少」。
所以最典型的触发场景是：让它一次性生成一个大文件。几百行的完整实现、一整份配置、一个长文档，写着写着就超了。
二、可以调，但有上限和代价
相关的环境变量是 CLAUDE_CODE_MAX_OUTPUT_TOKENS。按 issue #24055 评论区引用的官方设置文档：
- 默认值：32,000
- 最大值：64,000
- 代价：调高这个值会减少自动压缩触发前的可用上下文窗口
第三条是重点，也是很多人调完之后才发现的。这不是一个免费的旋钮。
道理不难理解：一次请求的总容量是有限的，你给输出预留得多，留给输入（也就是你的对话历史、文件内容、工具结果）的就少。调到 64000，等于把 32000 的空间从输入那边划过来——结果就是你更早触发自动压缩。
于是你可能从「写大文件会断」换成「聊几轮就要压缩一次」。换了一种难受法。
三、调高之前，先想想是不是该换个写法
在动那个变量之前，值得先问一句：这个文件真的需要一次生成完吗？
issue #24055 评论区里有一条观察很有代表性——有人指出，模型在撞上这个上限时的表现是反复尝试再反复失败，而不是自动切成小块写。这意味着：它不会替你解决这个问题，得你来。
几个通常更划算的做法：
按结构拆分。 一个大文件通常有天然的切分点——按类、按模块、按功能区。让它先写骨架（函数签名、类型定义、TODO 注释），再一块一块填。每一块都在上限之内，而且中间可以检查。
先写计划再写代码。 让它先输出一份实现计划（这个短），你确认之后再按计划分步实现。这样每一步的输出都可控，还多了一次纠偏机会。
用 Edit 而不是重写。 如果是改已有文件，让它做局部编辑而不是整文件重写——输出量差一个数量级。
大文件工作交给子代理。 子代理有独立的上下文窗口，让它在那边啃，只把结果带回来。
四、什么情况下确实该调高
也不是说这个变量不该动。下面几种情况调它是合理的：
- 确实需要一次性产出长内容，比如生成一份完整的数据文件、一大段结构化配置，没法自然拆分
- 你的会话本来就短，上下文压力不大，把空间划给输出不心疼
- 非交互模式的一次性任务（
-p），跑完就结束，不存在「后面还要聊很多轮」的问题
第三种最适合。一次性脚本任务里，把 CLAUDE_CODE_MAX_OUTPUT_TOKENS 调到 64000 几乎没有副作用——反正也没有长对话要维护。
反过来，交互式的长会话里调高它，副作用最明显，因为你会更频繁地撞上压缩。
五、关于评论区那些说法
issue #24055 的评论区里有一些流传较广的说法，比如「历史上限从 128K 降到 64K 又降到 32K」之类。
这些属于用户叙述，本文不作为事实引用。 需要确认当前的默认值和上限，请以官方设置文档为准——本文引用的「默认 32,000、最大 64,000」也是评论区引用官方文档的部分，你在动手前最好自己再核一次，因为这类数字是会变的。
评论区还有关于「降低 thinking effort 能绕过」的讨论和不满。降低思考强度确实会影响输出行为，但它不是针对这条报错的官方解法，而且会改变模型的工作方式。本文不推荐把它当作解决办法。
六、怎么改这个变量
两种方式：
shell 环境变量：
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
或者写进 settings.json 的 env 块：
{
"env": {
"CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000"
}
}
第二种更持久，也更适合按项目区分——某个项目确实需要长输出，就只在那个项目的设置里开。
改完之后建议观察一件事：是不是开始更频繁地看到自动压缩了。 如果是，说明代价已经显现，考虑调回来、改用拆分写法。
七、跟它容易混的几条
Claude Code 里几条都跟「太长了」有关，但治法完全不同：
| 报错 | 说的是 | 处理方向 |
|---|---|---|
exceeded the 32000 output token maximum | 单次输出太长 | 拆分生成，或调 CLAUDE_CODE_MAX_OUTPUT_TOKENS（上限 64000） |
Prompt is too long | 对话 + 附加内容超过上下文窗口 | /compact 或 /clear；/context 看构成；/mcp disable <name>；精简 CLAUDE.md |
Context exceeds the token limit | 对话已经超过上下文窗口 | /compact 或 /clear |
Request too large | 原始请求体超过 API 的 32MB 限制 | /compact；两次 Esc 回退到贴入超大内容那一轮；按路径引用大文件而不是粘贴内容 |
注意最后一条那个 32MB——它是请求体的字节大小，不是 token 数，跟前三条不是一个维度。触发它的通常是贴了超大的文本或数据。
四条里有三条的解法都指向同一件事：别把大内容塞进对话，让它按路径去读。 这条习惯能一次性避开其中三条。
八、子代理撞上它的时候
如果你把大文件的活交给了子代理（这本身是官方推荐的做法之一），子代理同样可能撞上输出上限。这时你看到的报错是另一条：
Agent terminated early due to an API error
官方给的处理是两步：
- 把错误详情对到错误参考页里相应的那一节——也就是说，先搞清楚子代理到底撞的是什么错，可能是输出上限，也可能是别的
- 基础错误解决之后，要求 Claude 重试那个任务或者恢复子代理
第一步是关键，也容易被跳过。Agent terminated early 本身不是一个独立的故障类型，它是一个转发的信封——真正的错误在里面。你要做的是拆开看，然后按真正那条错误的办法处理。
如果拆开发现确实是输出上限，那对子代理来说解法和主会话一样：让它分块产出，或者把 CLAUDE_CODE_MAX_OUTPUT_TOKENS 调高。好消息是子代理场景通常更适合调高这个值——子代理往往是一次性的、专项的任务，不需要维护很长的对话，把上下文空间划给输出的代价小。
第二步那句「恢复子代理」值得记住：不一定要从头再来。 底层错误解决之后，可以让它接着做，而不是重新派一次任务。
九、总结
- 32000 是单次输出上限，跟上下文剩多少无关。
- 可以调，变量是
CLAUDE_CODE_MAX_OUTPUT_TOKENS，默认 32,000、最大 64,000。 - 调高有代价：压缩前的可用上下文变少，你会更早撞上自动压缩。
- 交互式长会话里不建议调高；一次性的非交互任务里调高最划算。
- 更常见的正解是换写法——拆分生成、先计划后实现、用编辑代替重写、大文件交给子代理。
- 评论区里关于历史上限变化和降低思考强度的说法，本文不作为事实引用。
本文引用的环境变量默认值与上限，来自 issue #24055（anthropics/claude-code，仍为开放状态）评论中对官方设置文档的引用，核对日 2026-08-08。这类数值会随版本调整，动手前请以官方设置文档为准。