【Bug已解决】Output too large / Response truncated — Claude Code 响应截断解决方案

1. 问题描述

在 Claude Code 中请求生成大量代码或长文本时，输出在未完成时突然中断，终端显示：

# 输出在中间突然停止 ... function processAuth(token) { const decoded = jwt.ve

使用--debug模式查看 API 响应时，可以看到：

{ "stop_reason": "max_tokens", "content": [ {"type": "text", "text": "...(被截断的内容)"} ] }

这个问题在以下场景中特别常见：

• 让 Claude Code 生成超过 4096 tokens 的长代码
• 一次性请求生成多个文件
• 让 Claude Code 编写长文档或报告
• 上下文已经很大，剩余输出空间不足
• max_tokens 设置过小

# 典型复现过程 $ claude > 生成一个完整的 Express.js 项目，包含路由、中间件、数据库连接和错误处理 # Claude 开始生成代码... # 在写到第三个文件时突然停止 # stop_reason: max_tokens

2. 原因分析

核心原理拆解

Claude Code 发送请求 → 指定 max_tokens 限制 ↓ Claude 模型生成输出 → 达到 max_tokens 上限 ↓ 输出被强制截断 → stop_reason: max_tokens ↓ 内容不完整

原因分类表

3. 解决方案

方案一：使用 "continue" 继续生成（最推荐）

# 步骤 1：当输出被截断时 > 继续 # Claude Code 会从截断处继续生成 # 可能需要多次 "继续" 才能完成 # 步骤 2：如果 "继续" 不生效 > 从刚才中断的地方继续生成代码 # 步骤 3：使用 /compact 后继续 /compact > 继续

方案二：增加 max_tokens 设置

# 步骤 1：通过环境变量增加 export CLAUDE_MAX_TOKENS=16384 # 步骤 2：或在 settings.json 中配置 cat > ~/.claude/settings.json << 'EOF' { "maxTokens": 16384 } EOF # 步骤 3：永久生效 echo 'export CLAUDE_MAX_TOKENS=16384' >> ~/.zshrc source ~/.zshrc # 步骤 4：重启 Claude Code claude

方案三：分步请求生成

# 不要一次性请求生成所有内容: > 生成完整的 Express 项目（5 个文件） # 分步请求: > 步骤 1: 生成 app.js 主文件 # 完成后 > 步骤 2: 生成 routes/ 目录下的路由文件 # 完成后 > 步骤 3: 生成 middleware/ 目录下的中间件 # 逐步完成

方案四：压缩上下文后生成

# 步骤 1：压缩上下文释放空间 /compact # 这会减少输入 Token，为输出留出更多空间 # 步骤 2：重新请求 > 生成 Express 项目的错误处理中间件

方案五：指定输出长度限制

# 在请求中明确限制范围: > 生成一个简洁的 Express 服务器（不超过 100 行） > 只生成核心路由逻辑，不要包含配置和工具函数 > 先生成函数签名和注释，后续再补充实现

方案六：使用 /clear 后重新请求

# 如果上下文太大占满了窗口 /clear # 新会话中输入更简洁的请求 > 创建一个 Express.js 服务器，包含 /api/users 路由 # 简洁的请求 + 空的上下文 = 更多的输出空间

4. 各方案对比总结

5. 常见问题 FAQ

5.1 max_tokens 默认值是多少

Claude Code 默认 max_tokens 通常为 4096 或 8192。具体取决于版本和配置。可以通过 settings.json 或环境变量调整。

5.2 stop_reason=max_tokens 和 stop_reason=end_turn 的区别

• max_tokens：输出达到了 Token 上限被强制截断，内容不完整
• end_turn：模型自然完成回答，内容完整
• tool_use：模型请求调用工具

5.3 最大可以设置多少 max_tokens

取决于模型：

• Sonnet：最大 8192 tokens（部分版本支持 16384）
• Opus：最大 4096 tokens
• Haiku：最大 8192 tokens
• 超过模型限制的设置不会生效

5.4 "继续" 不起作用怎么办

可能上下文已满。使用/compact压缩后继续，或/clear后重新请求。

5.5 生成代码被截断后如何拼接

# 步骤 1：先保存已生成的部分 > 将已生成的代码保存到文件 # 步骤 2：继续生成 > 继续 # 步骤 3：将后续生成的内容追加到同一文件

5.6 上下文窗口和 max_tokens 的关系

上下文窗口 = 输入 Token + 输出 Token。如果输入占用了 100K tokens（200K 窗口），输出最多只有 100K tokens。压缩上下文可以为输出释放空间。

5.7 CI/CD 中如何避免截断

在自动化流程中分步执行，每步生成一个文件：

files = ["app.js", "routes/users.js", "middleware/auth.js"] for f in files: response = call_claude(f"生成文件 {f} 的代码") save_to_file(f, response)

5.8 流式响应下是否会被截断

是的。即使是流式响应，达到 max_tokens 后也会停止。流式只是逐步显示输出，不增加总输出量。

5.9 如何检测输出是否被截断

检查 stop_reason：

# 使用 --debug 模式 claude --debug # 查看响应中的 stop_reason # 如果是 max_tokens，说明被截断

5.10 排查清单速查表

□ 1. 检查 stop_reason 是否为 max_tokens □ 2. 输入 "继续" 从截断处恢复 □ 3. 增加 CLAUDE_MAX_TOKENS 到 16384 □ 4. 使用 /compact 压缩上下文释放空间 □ 5. 多文件任务分步请求 □ 6. 限制每次请求的输出范围 □ 7. /clear 后用简洁请求重新开始 □ 8. 注意模型的 max_tokens 上限 □ 9. CI/CD 中分步生成每个文件 □ 10. 流式响应也会被 max_tokens 截断

6. 总结

1. 根本原因：响应截断是因为输出达到了max_tokens上限（stop_reason=max_tokens），最常见原因是默认 Token 限制过小（40%）和上下文占用过大（30%）
2. 最佳实践：输出截断时输入"继续"从中断处恢复生成，可能需要多次"继续"才能完成长输出
3. 预防措施：在settings.json中设置maxTokens: 16384，并使用/compact压缩上下文为输出释放空间
4. 分步策略：将多文件生成任务拆分为单文件请求，每次只生成一个文件，避免单次输出过长
5. 最佳实践建议：养成分步请求的习惯——先让 Claude Code 生成文件骨架和函数签名，再逐步补充实现，既能避免截断又能更好地控制代码质量

故障排查流程图

flowchart TD A[输出被截断] --> B[检查 stop_reason] B --> C{是 max_tokens?} C -->|否| D[其他原因排查] C -->|是| E[输入 "继续" 恢复] E --> F{输出完整?} F -->|是| G[✅ 问题解决] F -->|否| H{上下文是否过大?} H -->|是| I[/compact 压缩上下文] H -->|否| J[增加 maxTokens 设置] I --> E J --> K[settings.json: maxTokens 16384] K --> L[重启 Claude Code] L --> E F -->|否, 多次截断| M[分步请求] M --> N[每次只生成一个文件/函数] N --> G D --> O{stop_reason?} O -->|end_turn| P[输出已完整] O -->|tool_use| Q[工具调用, 非截断] P --> G Q --> G