【Bug已解决】Claude: "response truncated" / Output cut off mid-sentence — Claude 响应被截断解决方案

1. 问题描述

Claude 的响应在输出过程中被截断，内容不完整：

# 响应截断 $ claude "生成一段长代码" # 输出到一半突然停止 # "...function process() { const da" # 没有完整结束 # 或 max_tokens 不足 $ claude --print "详细分析这段代码" # 输出: "这段代码的主要功能是..." # 然后突然停止，没有结论 # 或流式中断 $ claude "长篇分析" # 流式输出到一半断开 Error: Response truncated due to max_tokens. # 或 JSON 输出不完整 $ claude --print --output-format json "task" # {"result": "partial... # JSON 不完整，无法解析

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

• max_tokens 设置过小
• 流式连接中断
• 长任务输出过多
• 系统提示占用过多
• 模型生成过长
• CI/CD 中超时

2. 原因分析

原因分类表

3. 解决方案

方案一：增加 max_tokens（最推荐）

# 步骤 1：增加 max_tokens claude --max-tokens 8192 "task" # 步骤 2：或设置更大值 claude --max-tokens 16384 "task" # 步骤 3：在配置中设置 cat > ~/.claude/settings.json << 'EOF' { "maxTokens": 16384 } EOF # 步骤 4：验证 claude --print --max-tokens 8192 "生成详细代码"

方案二：使用 --no-stream

# 步骤 1：非流式模式 claude --no-stream --max-tokens 8192 "task" # 步骤 2：或 --print --no-stream claude --print --no-stream --max-tokens 8192 "task" --max-turns 10 # 步骤 3：CI/CD 中 claude --print --no-stream --max-tokens 8192 "task" --max-turns 10 2>&1 # 步骤 4：验证 claude --print --no-stream "hello"

方案三：分步执行

# 步骤 1：拆分长任务 claude --print "生成 src/index.js 前 100 行" --max-turns 5 claude --print "继续生成 src/index.js 后 100 行" --max-turns 5 # 步骤 2：减少 --max-turns claude --print "task" --max-turns 5 # 步骤 3：精简提示 # 错误: claude "详细分析整个项目" # 正确: claude "分析 src/index.js" # 步骤 4：验证 claude --print "hello"

方案四：检查 stop_reason

# 步骤 1：使用 --debug 查看停止原因 claude --print --debug "task" --max-turns 10 2>&1 | grep -i "stop\|truncat\|token" # 步骤 2：如果 stop_reason: max_tokens # 说明 max_tokens 不足，需要增加 # 步骤 3：如果 stop_reason: end_turn # 说明正常结束 # 步骤 4：增加 max_tokens claude --print --max-tokens 16384 "task" --max-turns 10

方案五：精简系统提示

# 步骤 1：检查系统提示大小 wc -c system-prompt.txt # 步骤 2：精简到 < 4000 tokens # 只保留核心指令 # 步骤 3：使用简短提示 claude --system-prompt "代码助手" --max-tokens 8192 "task" # 步骤 4：验证 claude --print --max-tokens 8192 "hello"

方案六：增加超时

# 步骤 1：增加请求超时 export CLAUDE_REQUEST_TIMEOUT=120000 # 120 秒 # 步骤 2：永久设置 echo 'export CLAUDE_REQUEST_TIMEOUT=120000' >> ~/.zshrc source ~/.zshrc # 步骤 3：CI/CD 中 claude --print --no-stream --max-tokens 8192 "task" --max-turns 10 2>&1 # 步骤 4：验证 claude --print "hello"

4. 各方案对比总结

5. 常见问题 FAQ

5.1 max_tokens 默认多少

通常 4096。可能不够长任务使用。

5.2 如何增加 max_tokens

claude --max-tokens 8192 "task" # 或 settings.json: {"maxTokens": 16384}

5.3 stop_reason 是什么

• end_turn: 正常结束
• max_tokens: 因 Token 限制被截断
• stop_sequence: 遇到停止序列

5.4 如何检查截断原因

claude --print --debug "task" 2>&1 | grep -i "stop\|truncat"

5.5 --no-stream 有帮助吗

是的。非流式模式减少流式中断导致的截断。

5.6 如何分步执行

拆分长任务为多个短任务，每步使用--max-turns 5。

5.7 系统提示占多少

500-5000 tokens。过长会挤占输出空间。

5.8 max_tokens 最大多少

取决于模型，通常 8192-16384。检查模型文档。

5.9 CI/CD 中如何避免截断

--max-tokens 16384+--no-stream+CLAUDE_REQUEST_TIMEOUT=120000。

5.10 排查清单速查表

□ 1. --max-tokens 8192 增加 Token □ 2. settings.json: maxTokens 16384 □ 3. --no-stream 非流式 □ 4. --print --no-stream CI/CD □ 5. --debug | grep stop 检查原因 □ 6. stop_reason: max_tokens 需增加 □ 7. 分步执行长任务 □ 8. --max-turns 5 减少轮次 □ 9. 精简系统提示 < 4000 tokens □ 10. CLAUDE_REQUEST_TIMEOUT=120000

6. 总结

1. 根本原因：响应截断最常见原因是 max_tokens 不足（40%）和流式中断（25%）
2. 最佳实践：使用claude --max-tokens 8192 "task"增加 Token 限制
3. --no-stream：非流式模式减少流式中断导致的截断
4. 检查 stop_reason：使用--debug查看stop_reason: max_tokens确认截断原因
5. 最佳实践建议：配置maxTokens: 16384，CI/CD 中使用--print --no-stream --max-tokens 16384

故障排查流程图

flowchart TD A[响应截断] --> B[claude --debug | grep stop] B --> C{stop_reason?} C -->|max_tokens| D[增加 --max-tokens] C -->|end_turn| E[正常结束] C -->|stream| F[使用 --no-stream] D --> G[--max-tokens 8192 或 16384] G --> H[claude 验证] F --> I[claude --no-stream "task"] I --> H H --> j{完整?} j -->|是| K[✅ 问题解决] j -->|否| L[分步执行] L --> M[拆分长任务] M --> N[每步 --max-turns 5] N --> H j -->|否| O[精简系统提示] O --> P[wc -c 检查大小] P --> Q[精简到 < 4000 tokens] Q --> H j -->|否| R[增加超时] R --> S[CLAUDE_REQUEST_TIMEOUT=120000] S --> H H --> T{成功?} T -->|是| K T -->|否| U[使用 --continue 继续] U --> V[claude --continue --max-tokens 8192] V --> K K --> W[长期: maxTokens 16384 + --no-stream] W --> X[✅ 长期方案]