【Bug已解决】Prompt is too long: 137500 tokens ＞ 135000 maximum — Claude Code 上下文超限解决方案

【Bug已解决】Prompt is too long: 137500 tokens 135000 maximum — Claude Code 上下文超限解决方案1. 问题描述在使用 Claude Code 进行长时间的代码开发会话后终端突然弹出以下报错信息所有后续操作全部被拒绝Prompt is too long: 137500 tokens 135000 maximum界面上的显示通常为Context limit reached · /compact or /clear to continue完整的 API 原始错误可能包含具体的 Token 数量对比{ type: error, error: { type: invalid_request_error, message: prompt is too long: 137500 tokens 135000 maximum } }这个问题在以下场景中特别常见长时间编码会话超过 2 小时对话历史不断累积一次性让 Claude Code 读取大型代码库或大文件使用 MCP 工具返回了大量数据填充到上下文中在会话中反复粘贴大段日志或错误堆栈从一个旧会话claude --continue恢复时历史过长许多开发者反映报错前没有任何预警Claude Code 突然拒绝所有请求。即使输入一个简单的 hello 也报 prompt is too long。在 GitHub Issues 中上下文超限是使用频率最高的问题之一因为它直接阻断了工作流。# 典型复现过程 $ claude 帮我分析这个项目的整体架构 # Claude 分析了 30 分钟的代码... 继续分析数据库模块 Prompt is too long: 137500 tokens 135000 maximum 什么 Prompt is too long: 137500 tokens 135000 maximum hello Prompt is too long: 137500 tokens 135000 maximum2. 原因分析核心原理拆解每次对话 → 对话历史保留在上下文中 ↓ 工具调用返回的数据也累积在上下文中 ↓ 总 Token 数超过模型上下文窗口上限 ↓ API 拒绝请求: prompt is too long ↓ Claude Code 显示 Context limit reached原因分类表原因分类具体表现占比长会话历史累积对话轮次过多历史 Token 不断增长约 45%大文件/大代码库读取一次性读取超大文件撑满上下文约 25%MCP 工具返回大量数据工具调用结果占用大量 Token约 15%重复粘贴大段内容日志、堆栈、配置反复粘贴约 10%.claudeignore 未配置冗余文件被读取进上下文约 5%深入说明Claude 模型有固定的上下文窗口大小限制Sonnet200K tokens约 15 万字中文Opus200K tokensHaiku200K tokens1M ContextSonnet1,000,000 tokens需要额外付费但 Claude Code 实际可用的上下文比模型窗口小因为它需要预留空间给系统提示词约 10K-15K tokensClaude Code 的内置系统指令工具定义约 5K-10K tokens所有可用工具的 schema 定义输出空间约 4K-8K tokens为模型响应预留的 Token因此实际可用于对话历史的空间约为 135K tokens对于 200K 窗口的模型这就是报错信息中 135000 maximum 的来源。Token 计算规则1 个英文单词 ≈ 1.3 tokens1 个中文字 ≈ 2-3 tokens1 个代码字符 ≈ 0.3-0.5 tokens1 行代码平均 40 字符≈ 15-20 tokens一个 5000 行的代码文件大约消耗 75K-100K tokens几乎占满了可用上下文的一半。3. 解决方案方案一使用 /compact 压缩上下文最推荐/compact命令会将当前对话历史压缩为摘要释放大量 Token 空间同时保留关键信息。# 步骤 1在 Claude Code 会话中执行 /compact # 步骤 2Claude Code 会自动总结之前的对话 # 输出类似: Compressed context from 137500 to 15000 tokens # 步骤 3验证可用空间 /status # 会显示当前 Token 使用量和剩余空间 # 步骤 4继续工作 继续分析数据库模块 # 这次应该能正常响应提示/compact会丢失部分对话细节但保留了关键上下文。建议在长会话中每 30-60 分钟主动执行一次/compact而不是等到报错才处理。方案二使用 /clear 清空对话历史如果不需要保留之前的对话内容直接清空是最彻底的解决方案。# 步骤 1清空所有对话历史 /clear # 步骤 2验证上下文已清空 /status # Token 使用量应该降到很低只剩系统提示和工具定义 # 步骤 3重新开始工作 帮我分析数据库模块 # 全新的会话充足的上下文空间 # 注意: /clear 会丢失所有之前的对话内容 # 如果需要保留先使用 /compact 而非 /clear方案三配置 .claudeignore 排除大文件从源头减少不必要的文件被读取进上下文。# 步骤 1在项目根目录创建 .claudeignore 文件 cat .claudeignore EOF # 依赖目录 node_modules/ vendor/ bower_components/ # 构建产物 dist/ build/ out/ .next/ .nuxt/ # 日志文件 *.log logs/ # 锁文件通常很大且不需要 Claude 分析 package-lock.json yarn.lock pnpm-lock.yaml # 压缩文件 *.zip *.tar.gz # 媒体文件 *.png *.jpg *.jpeg *.gif *.mp4 *.mp3 # 大型数据文件 *.csv *.json.gz *.sql # 覆盖率报告 coverage/ .nyc_output/ # 编译产物 *.min.js *.min.css *.map EOF # 步骤 2重启 Claude Code 使配置生效 # 或在当前会话中执行 /reload # 步骤 3验证 .claudeignore 是否生效 # 让 Claude Code 读取项目时被忽略的文件不会被加载方案四分模块/分文件提问避免一次性传入整个项目按模块分批处理。# 不要这样做容易撑爆上下文: 帮我重构整个项目的所有模块 # 应该这样做分模块处理: 帮我重构 src/auth/ 目录下的认证模块 # 完成后 /clear 帮我重构 src/api/ 目录下的 API 模块 # 完成后 /clear 帮我重构 src/utils/ 目录下的工具模块 # 对于大文件分段处理: 分析 src/database.js 的第 1-200 行 # 完成后 继续分析第 201-400 行方案五升级到 1M Context需要付费如果经常需要处理大型代码库可以启用 1M Context 窗口。# 步骤 1检查当前是否支持 1M Context # 需要 Anthropic API Tier 2 或 Max 订阅 # 步骤 2在 Claude Code 中切换 /model sonnet-1m # 或通过环境变量 export ANTHROPIC_MODELclaude-sonnet-4-1m # 步骤 3验证上下文窗口大小 /status # 应该显示 Context window: 1,000,000 tokens # 注意: 1M Context 的费用是标准 200K 的 2 倍 # 输入 Token: $6/MTok (标准 $3/MTok) # 输出 Token: $22.50/MTok (标准 $15/MTok)方案六使用 /context 监控上下文使用量主动监控上下文使用情况在超限前主动管理。# 步骤 1定期检查上下文使用量 /context # 输出类似: # Context usage: 85,000 / 135,000 tokens (63%) # Breakdown: # System prompt: 12,000 tokens # Tool definitions: 8,000 tokens # Conversation history: 65,000 tokens # 步骤 2当使用量超过 70% 时主动 /compact # 当使用量超过 50% 时考虑清理不必要的内容 # 步骤 3使用 /recap 生成会话摘要后 /clear /recap # Claude Code 会生成当前会话的摘要 # 你可以保存摘要然后 /clear 释放空间4. 各方案对比总结方案适用场景推荐指数难度方案一/compact 压缩长会话中途需保留上下文⭐⭐⭐⭐⭐低方案二/clear 清空不需要保留历史时⭐⭐⭐⭐⭐低方案三.claudeignore从源头减少 Token 消耗⭐⭐⭐⭐⭐低方案四分模块提问大型项目开发⭐⭐⭐⭐低方案五1M Context超大代码库分析⭐⭐⭐低方案六/context 监控主动管理上下文⭐⭐⭐⭐低5. 常见问题 FAQ5.1 /compact 后丢失了重要信息怎么办/compact会将对话历史压缩为摘要某些细节可能丢失。如果重要信息丢失在/compact前先使用/recap生成完整摘要并保存将关键信息写入文件而非依赖对话历史使用claude --continue恢复之前的会话如果进程未退出5.2 刚启动 Claude Code 就报 prompt is too long这说明系统提示 工具定义已经接近上限。可能原因配置了太多 MCP 工具工具定义占满了上下文使用了自定义系统提示且过长.claude/settings.json中配置了大量自定义指令解决方法# 减少不必要的 MCP 工具 claude mcp list claude mcp remove 不需要的server # 检查自定义系统提示 cat ~/.claude/CLAUDE.md # 如果过长精简内容5.3 使用 --continue 恢复会话时报 prompt is too long--continue会恢复上一个会话的完整历史。如果上次会话已经很长恢复时就会超限。解决方法不要使用--continue直接开新会话使用claude --resume选择特定的历史会话可能可以选择较短的会话在上一个会话退出前先执行/compact5.4 MCP 工具返回的数据占满了上下文某些 MCP 工具如文件搜索、数据库查询可能返回大量数据。解决方法在工具调用后立即执行/compact修改 MCP Server 限制返回数据量使用更精确的查询参数减少返回结果5.5 1M Context 是否值得升级如果你经常处理超过 200K tokens 的代码库1M Context 值得升级。但费用是标准的 2 倍。替代方案是使用/compact 分模块处理虽然不如 1M Context 方便但成本更低。5.6 为什么 /status 显示的 Token 数和报错中的不一致/status显示的是估算值实际 API 请求时的 Token 数可能略有不同因为系统提示和工具定义的精确 Token 数在客户端难以完全准确计算。建议在/status显示 80% 使用量时就执行/compact留出余量。5.7 .claudeignore 和 .gitignore 的区别.gitignore告诉 Git 哪些文件不追踪.claudeignore告诉 Claude Code 哪些文件不读取两者独立配置互不影响如果.claudeignore不存在Claude Code 会参考.gitignore但不完全依赖它5.8 频繁 /clear 会不会影响 Claude Code 的记忆/clear只清除当前会话的对话历史不影响~/.claude/CLAUDE.md中的持久记忆项目级的.claude/CLAUDE.md项目指令MCP 工具配置环境变量和 API Key但会影响当前会话的上下文连续性Claude 会忘记之前讨论的内容。5.9 如何估算一段代码消耗多少 Token粗略估算方法# 使用 Claude Code 的 /context 命令前后对比 /context # 记录当前 Token # 然后粘贴代码或读取文件 /context # 再次查看差值就是新增的 Token # 或使用 tiktoken (Python) 估算 pip install tiktoken python3 -c import tiktoken enc tiktoken.get_encoding(cl100k_base) code open(your_file.js).read() print(fTokens: {len(enc.encode(code))}) 5.10 排查清单速查表□ 1. 使用 /context 或 /status 查看当前 Token 使用量 □ 2. 使用 /compact 压缩上下文释放空间 □ 3. 使用 /clear 完全清空不需要的历史 □ 4. 创建 .claudeignore 排除大文件和依赖目录 □ 5. 将大任务拆分为小模块逐个处理 □ 6. 检查是否配置了过多 MCP 工具 □ 7. 避免在对话中反复粘贴大段内容 □ 8. 考虑升级到 1M Context付费 □ 9. 长会话中每 30-60 分钟主动 /compact □ 10. 使用 /recap 保存重要摘要后再 /clear6. 总结根本原因上下文超限是因为对话历史、工具返回数据和大文件读取不断累积总 Token 数超过了模型的上下文窗口限制200K 模型实际可用约 135K tokens最佳实践在长会话中每 30-60 分钟主动执行/compact而不是等到报错才处理配合.claudeignore从源头减少不必要的 Token 消耗快速恢复报错后立即执行/compact需保留历史或/clear不需保留历史90% 的情况可以立即恢复大项目策略将大型重构任务拆分为模块级小任务每个模块完成后/clear再处理下一个既避免超限也获得更精准的分析最佳实践建议养成使用/context监控上下文使用量的习惯当使用量超过 70% 时主动压缩避免在关键时刻被上下文超限打断工作流故障排查流程图flowchart TD A[出现 Prompt is too long] -- B{是否需保留对话历史?} B --|是| C[执行 /compact 压缩上下文] B --|否| D[执行 /clear 清空历史] C -- E{压缩后 Token 是否足够?} E --|是| F[继续工作] E --|否| G[检查 MCP 工具数量] D -- F G -- H{是否有不必要工具?} H --|是| I[移除多余 MCP Server] H --|否| J[检查 .claudeignore] I -- K[执行 /compact 释放空间] J -- L{.claudeignore 是否配置?} L --|否| M[创建 .claudeignore 排除大文件] L --|是| N[分模块处理大任务] M -- N K -- F N -- O[每个模块完成后 /clear] O -- F F -- P{是否频繁超限?} P --|是| Q[考虑升级 1M Context] P --|否| R[✅ 问题解决] Q -- R