【Bug已解决】Context window exceeded / Token limit reached — Claude Code 上下文窗口超限解决方案1. 问题描述在 Claude Code 长会话中发送请求时突然弹出上下文超限错误Error: Context window exceeded Your message would exceed the maximum context length (200,000 tokens). Current context: 195,000 tokens. Please use /compact or /clear.或者Error: Request too large Input tokens: 210,000 exceeds maximum of 200,000有时表现为 API 返回 400 错误Error: 400 Bad Request {type:error,error:{type:invalid_request_error,message:prompt is too long: 210000 tokens 200000 maximum}}这个问题在以下场景中特别常见长时间编码会话积累了大量对话历史读取了多个大文件每个 10K tokensMCP 工具返回了大量数据搜索结果包含大量匹配项/compact 后仍然超过限制2. 原因分析核心原理拆解对话历史 文件内容 工具结果 → 持续累积 ↓ 总 Token 数超过模型上下文窗口上限200K ↓ API 拒绝请求 (400 Bad Request) ↓ 报错 Context window exceeded原因分类表原因分类具体表现占比对话历史过长长会话累积约 40%大文件读取读取多个大文件约 30%工具结果过大MCP/搜索返回大量数据约 15%/compact 无效压缩后仍超限约 10%系统提示过长CLAUDE.md MCP 描述约 5%3. 解决方案方案一使用 /clear 清空上下文最推荐# 步骤 1将关键信息保存到文件 将我们讨论的架构设计保存到 docs/architecture.md # 步骤 2清空上下文 /clear # 立即释放所有上下文空间 # 步骤 3在新上下文中继续 参考 docs/architecture.md 继续方案二使用 /compact 压缩上下文# 步骤 1压缩上下文 /compact # 将对话历史压缩为摘要 # 步骤 2检查压缩后的 Token 数 /context # 查看当前 Token 使用量 # 步骤 3如果压缩后仍然超限 # 使用 /clear 代替 /clear方案三切换到更大上下文的模型# 步骤 1切换到支持更大上下文的模型 /model sonnet # Sonnet 支持 200K 上下文 # 步骤 2如果使用 Opus上下文更小 # 切换到 Sonnet 增加可用空间 /model sonnet # 步骤 3使用 /context 确认 /context方案四避免读取大文件# 步骤 1不要一次性读取整个大文件 # 错误: 读取 src/huge-file.js50K tokens # 步骤 2使用搜索定位关键部分 搜索 src/huge-file.js 中的 authenticate 函数 # 步骤 3只读取相关部分 只读取 src/huge-file.js 的第 100-150 行方案五限制工具返回数据量# 步骤 1搜索时限制结果数量 搜索 deprecated 但只显示前 10 个结果 # 步骤 2MCP 工具调用时限制输出 使用 playwright 截图但不要提取整个页面内容 # 步骤 3使用 .claudeignore 排除大文件 cat .claudeignore EOF *.min.js *.map node_modules/ dist/ *.lock EOF方案六分会话处理大型任务# 步骤 1将会话 1 的成果保存到文件 将分析结果保存到 docs/analysis.md /exit # 步骤 2会话 2 基于文件继续 claude 参考 docs/analysis.md实现其中的方案 A # 步骤 3会话 3 继续后续工作 /exit claude 参考 docs/analysis.md实现方案 B4. 各方案对比总结方案适用场景推荐指数难度方案一/clear立即解决⭐⭐⭐⭐⭐低方案二/compact保留历史⭐⭐⭐⭐⭐低方案三切换模型Opus 超限⭐⭐⭐⭐低方案四避免大文件预防⭐⭐⭐⭐⭐低方案五限制工具预防⭐⭐⭐⭐低方案六分会话大型任务⭐⭐⭐⭐⭐低5. 常见问题 FAQ5.1 上下文窗口有多大Sonnet200,000 tokens约 150K 英文单词Opus200,000 tokensHaiku200,000 tokens上下文窗口 系统提示 对话历史 工具结果 输出5.2 /compact 和 /clear 的区别/compact压缩对话历史为摘要保留关键信息消耗 API/clear完全清空上下文本地操作不消耗 API5.3 一个 Token 大约多少字符英文约 4 个字符 1 token中文约 2 个汉字 1 token代码约 3-4 个字符 1 token5.4 如何监控 Token 使用量# 使用 /context 查看当前 Token 数 /context # 显示: 95,000 / 200,000 tokens used # 使用 /status 查看配额使用 /status5.5 CLAUDE.md 占用多少 Token取决于内容长度。2000 字的 CLAUDE.md 约占用 1000-1500 tokens。建议控制在 1000 字以内。5.6 读取大文件占用多少 Token一个 1000 行的代码文件约占用 5000-10000 tokens。读取多个大文件会快速消耗上下文空间。5.7 /compact 后 Token 为什么没减少可能压缩效果不好。检查/context确认实际 Token 数。如果压缩后仍超限使用/clear。5.8 MCP 工具描述占用 Token每个 MCP 工具的描述和 schema 都会计入系统提示。减少 MCP Server 数量可以释放空间。5.9 CI/CD 中如何避免超限使用--print模式每次是新会话不会积累上下文claude --print 分析 src/index.js --max-turns 55.10 排查清单速查表□ 1. 使用 /context 查看当前 Token 使用量 □ 2. Token 80% 时执行 /compact □ 3. Token 95% 时执行 /clear □ 4. 避免一次性读取大文件 500 行 □ 5. 搜索定位后只读取相关部分 □ 6. .claudeignore 排除 .min.js/.map/dist □ 7. 限制 MCP 工具返回数据量 □ 8. CLAUDE.md 控制在 1000 字以内 □ 9. 大型任务分会话处理 □ 10. CI/CD 使用 --print 避免积累6. 总结根本原因上下文超限最常见原因是长会话累积40%和大文件读取30%总 Token 超过 200K 上限最佳实践使用/context定期监控 Token 使用量80% 时执行/compact95% 时执行/clear文件读取避免一次性读取大文件使用搜索定位后只读取相关行——1000 行代码约 5000-10000 tokens预防措施配置.claudeignore排除 .min.js、.map、dist/ 等大文件减少 MCP Server 数量释放系统提示空间最佳实践建议养成主动管理上下文的习惯——每 30 分钟检查/context将重要成果写入文件而非依赖会话历史大型任务拆分到多个会话故障排查流程图flowchart TD A[Context window exceeded] -- B[/context 查看 Token 数] B -- C{Token 95%?} C --|是| D[保存关键信息到文件] C --|否, 80-95%| E[执行 /compact] D -- F[执行 /clear] E -- G{/compact 后 Token 80%?} G --|是| H[✅ 继续工作] G --|否| F F -- I[新上下文引用文件继续] I -- H H -- J[预防: 定期 /context 检查] J -- K[80% 时 /compact] K -- L[避免读取大文件] L -- M[.claudeignore 排除大文件] M -- N[✅ 预防完成]