【Bug已解决】Claude Code context length exceeded / token limit reached — Claude Code 上下文窗口超限解决方案1. 问题描述Claude Code 在多轮对话或处理大型代码库时报出上下文窗口 Token 超限错误# 多轮对话后突然报错 $ claude 帮我重构这个项目的所有 API 接口 # 对话进行到一半时报错 Error: Context length exceeded Your request has reached the maximum context window size (200000 tokens). Please reduce the conversation length or start a new session. # 或表现为 API 返回 400 错误 $ claude 继续分析上一个模块 Error: BadRequestError: 400 Bad Request { error: { type: invalid_request_error, message: This request exceeds the maximum context length. } } # 或 Claude Code 自动提示 ⚠️ Context window is 95% full. Consider starting a new conversation to maintain optimal performance. # 或工具调用结果被截断 $ claude 读取 package.json 并分析依赖 Error: Tool output truncated due to context length limit有时表现为多轮对话累积后无法继续提问读取大文件后 Token 计数溢出工具调用结果被自动截断Claude 回复质量明显下降上下文丢失系统提示上下文窗口已满这个问题在以下场景中特别常见单次会话超过 20 轮对话分析超过 10000 行的代码文件一次性粘贴大量代码到对话中读取大型 JSON/CSV/日志文件历史上下文未被自动压缩工具调用返回大量数据未截断2. 原因分析核心原理拆解用户输入 文件内容 工具结果 系统提示 → 拼接为完整请求 ↓ 所有内容转换为 Token 计数 ↓ Token 总数超过模型上下文窗口上限200K ↓ API 拒绝请求返回 400 错误Token 计算规则约 1 Token ≈ 4 个英文字符 ≈ 0.75 个英文单词 约 1 Token ≈ 1-2 个中文字符 约 1 行代码 ≈ 5-15 Tokens 约 1000 行代码 ≈ 5000-15000 Tokens原因分类表原因分类具体表现占比对话历史累积多轮对话消息全量保留约 40%大文件全量读取一次性读取超过 5000 行的文件约 25%工具输出过大grep/find 返回海量结果约 15%粘贴大段代码用户直接粘贴 1000 行代码约 10%系统提示占用系统提示工具定义占用固定 Token约 5%自动压缩失效上下文压缩机制未生效约 5%3. 解决方案方案一清理对话历史最推荐# 步骤 1在 Claude Code 中使用 /clear 命令 claude /clear # 清除所有历史对话释放上下文窗口 # 步骤 2使用 /compact 压缩上下文保留摘要 claude /compact # Claude Code 会将历史对话压缩为摘要释放 Token # 步骤 3开启新会话继续工作 claude 基于之前的分析继续处理 auth 模块的优化 # 步骤 4养成习惯每完成一个子任务就清理 claude 完成 API 重构 /compact 继续处理数据库迁移方案二分批读取大文件# 步骤 1不要让 Claude 一次读取整个大文件 # 错误做法 claude 读取 src/database/huge-orm.ts 并分析 # 正确做法指定行范围 claude 读取 src/database/huge-orm.ts 第 1-200 行并分析 # 步骤 2使用外部工具预处理 wc -l src/database/huge-orm.ts # 假设 12000 行 # 步骤 3按模块拆分 grep -n ^class\|^function\|^export src/database/huge-orm.ts # 找到各个模块的起始行 # 步骤 4分批让 Claude 分析 claude 分析 src/database/huge-orm.ts 第 1-500 行的 Model 基类 # 分析完后 /compact 分析第 501-1000 行的 Query Builder方案三过滤工具输出# 步骤 1避免让 Claude 执行返回大量结果的命令 # 错误做法 claude 运行 grep -r import src/ 并分析所有导入 # 正确做法限制返回行数 claude 运行 grep -r import src/ | head -50 并分析 # 步骤 2使用更精确的搜索 claude 运行 grep -rn import.*Database src/ --include*.ts | head -30 # 步骤 3将大结果保存到文件按需读取 grep -r import src/ /tmp/imports.txt claude 读取 /tmp/imports.txt 第 1-50 行并分析方案四配置上下文窗口策略# 步骤 1在 settings.json 中配置自动压缩 cat ~/.claude/settings.json EOF { contextWindow: { autoCompact: true, compactThreshold: 0.8, maxFileSize: 50000 } } EOF # 步骤 2配置文件大小限制 # maxFileSize 单位为字符数50000 约 12500 Tokens # 超过此大小的文件 Claude 会提示分批读取 # 步骤 3重启 Claude Code claude # 步骤 4验证配置生效 claude --debug 21 | grep -i context # 应看到 autoCompact enabled方案五使用外部摘要预处理# 步骤 1先用简单工具生成文件摘要 # 提取函数签名 grep -n ^export\|^function\|^class\|^interface src/large-module.ts /tmp/summary.txt # 步骤 2提取关键注释 grep -B1 -A1 /** src/large-module.ts /tmp/summary.txt # 步骤 3让 Claude 基于摘要分析 claude 读取 /tmp/summary.txt 并分析模块结构 # 步骤 4针对感兴趣的函数再深入 claude 读取 src/large-module.ts 第 150-200 行的 handleRequest 函数方案六拆分会话为子任务# 步骤 1将大型任务拆分为多个子任务 # 不要在一个会话中完成所有工作 # 会话 1分析项目结构 claude 列出 src 目录下所有文件的路径 /clear # 会话 2分析核心模块 claude 分析 src/core/engine.ts 的架构设计 /clear # 会话 3分析 API 层 claude 分析 src/api/routes.ts 的接口定义 /clear # 会话 4整合分析 claude 基于各模块的分析结果设计重构方案4. 各方案对比总结方案适用场景推荐指数难度方案一清理历史对话过长⭐⭐⭐⭐⭐低方案二分批读取大文件⭐⭐⭐⭐⭐中方案三过滤输出工具输出大⭐⭐⭐⭐低方案四自动压缩长期使用⭐⭐⭐⭐低方案五外部摘要超大文件⭐⭐⭐⭐中方案六拆分会话大型任务⭐⭐⭐⭐⭐低5. 常见问题 FAQ5.1 Claude Code 的上下文窗口有多大Claude 3.5 Sonnet / Claude 4200,000 Tokens约 150,000 个英文单词实际可用约 180,000 Tokens系统提示和工具定义占用约 20,000中文约 100,000-150,000 字符5.2 /clear 和 /compact 的区别/clear完全清除对话历史上下文从零开始/compact将历史对话压缩为摘要保留释放大量 Token 但保持上下文连续性优先使用/compact需要完全重置时用/clear5.3 如何估算当前消耗的 Token 数# 方法 1Claude Code 内置提示 # 注意底部状态栏的上下文使用百分比 # 方法 2使用 tiktoken 估算 pip install tiktoken python3 -c import tiktoken enc tiktoken.encoding_for_model(gpt-4) with open(src/large-file.ts) as f: tokens enc.encode(f.read()) print(fToken count: {len(tokens)}) # 方法 3粗略估算 # 英文字符数 / 4 ≈ Token 数 # 中文字符数 / 1.5 ≈ Token 数 # 代码行数 * 10 ≈ Token 数5.4 为什么工具输出会导致超限Claude Code 的工具调用结果会完整保留在对话历史中。如果grep -r返回 5000 行结果每行约 10 Tokens就消耗 50,000 Tokens占总窗口的 25%。5.5 settings.json 中 maxFileSize 设多少建议设为 50000字符数约 12,500 Tokens最大不超过 100000约 25,000 Tokens超过此大小 Claude 会提示分批读取而非直接加载5.6 自动压缩什么时候触发当上下文使用达到compactThreshold默认 0.8 80%时自动触发自动压缩会将早期对话总结为摘要压缩后 Token 数会降低约 60-70%5.7 多轮对话每轮大约消耗多少 Token每轮对话用户输入 Claude 回复 工具调用约消耗 2,000-10,000 Tokens20 轮对话约消耗 40,000-200,000 Tokens超过 15 轮建议使用/compact5.8 读取整个目录树会消耗多少 Token# 一个中型项目 find src -type f | wc -l # 500 个文件 # 每个文件路径约 20-50 Tokens # 500 * 30 15,000 Tokens 仅路径 # 如果读取内容总计可能超过 500,000 Tokens5.9 上下文超限和速率限制的区别上下文超限单次请求的 Token 数超过模型上限返回 400 错误速率限制单位时间内的请求数或 Token 总量超过配额返回 429 错误两者完全不同解决方案也不同5.10 排查清单速查表□ 1. 对话超过 15 轮时使用 /compact □ 2. 完成子任务后使用 /clear 重置 □ 3. 大文件按 200-500 行分批读取 □ 4. grep/find 结果用 head -50 限制 □ 5. settings.json 设置 autoCompact: true □ 6. maxFileSize 设为 50000 □ 7. 不要一次性粘贴超过 500 行代码 □ 8. 大任务拆分为多个独立会话 □ 9. 用 grep 提取函数签名作为摘要 □ 10. 关注状态栏的上下文使用百分比6. 总结根本原因上下文超限最常见原因是多轮对话历史全量累积40%和大文件一次性读取25%导致总 Token 数超过 200K 上限最佳实践每完成一个子任务后使用/compact压缩上下文保持上下文使用率在 80% 以下文件读取策略大文件按 200-500 行分批读取使用grep提取函数签名作为导航索引工具输出控制所有grep/find/cat命令都加head -50限制返回行数避免工具结果撑爆上下文最佳实践建议在settings.json中启用autoCompact并设置compactThreshold: 0.8将大型任务拆分为多个独立会话分别处理故障排查流程图flowchart TD A[上下文窗口超限] -- B[使用 /compact 压缩历史] B -- C{是否仍超限?} C --|否| D[✅ 问题解决] C --|是| E[使用 /clear 完全重置] E -- F[开启新会话] F -- G{单文件过大?} G --|是| H[分批读取: 每次 200-500 行] G --|否| I{工具输出过大?} I --|是| J[grep/find 加 head -50] I --|否| K{粘贴代码过多?} K --|是| L[缩减到关键片段] K --|否| M[检查 autoCompact 配置] H -- N[重启 claude 验证] J -- N L -- N M -- O[settings.json: autoCompacttrue] O -- N N -- P{是否稳定?} P --|是| D P --|否| Q[拆分为多个独立会话] Q -- R[每会话处理一个子任务] R -- D