【Bug已解决】Maximum recursion depth exceeded / Infinite tool loop — Claude Code 工具无限循环解决方案1. 问题描述在 Claude Code 中执行任务时Claude Code 反复调用同一个工具陷入无限循环终端不断滚动相同的操作 重构这个函数 # Claude Code 调用 Read 工具读取文件 Read file: src/index.js # 然后又调用 Read 读取同一个文件 Read file: src/index.js # 反复循环... Read file: src/index.js # ...持续 20 次 Error: Maximum recursion depth exceeded Tool call limit reached: 25 consecutive tool calls这个问题在以下场景中特别常见文件内容超出 Claude 的理解范围反复读取修改文件后验证失败反复修改和验证MCP 工具返回空结果Claude 反复调用搜索操作没有找到结果反复搜索Auto 模式下 Claude 自主循环调用工具# 典型复现过程 $ claude 搜索项目中所有使用 deprecated API 的地方 # Claude 反复搜索... search_content: deprecated → 0 results search_content: deprecated → 0 results search_content: deprecated → 0 results # ... 20 次 Tool call limit reached2. 原因分析核心原理拆解Claude Code 调用工具 → 结果不满足预期 ↓ Claude 认为需要重新调用 → 再次调用相同工具 ↓ 结果仍然不满足 → 继续调用 ↓ 达到工具调用上限 → Maximum recursion depth exceeded原因分类表原因分类具体表现占比搜索无结果反复搜索找不到内容约 35%修改-验证循环修改后验证失败反复修改约 25%空结果循环MCP 工具返回空反复调用约 20%上下文丢失之前的结果被压缩后遗忘约 10%Auto 模式失控自动模式无限制调用约 10%3. 解决方案方案一按 Escape 中断循环最推荐# 步骤 1按 Escape 或 CtrlC 中断当前操作 # Claude Code 会停止工具调用 # 步骤 2提供更明确的指令 搜索已经完成了没有找到结果。请改用其他方式查找 # 步骤 3提供具体方向 不用再搜索了直接在 src/api/ 目录下查找方案二使用 /compact 打断循环# 步骤 1中断后执行 /compact /compact # 压缩上下文清除循环状态 # 步骤 2重新提供明确指令 不要重复搜索。以下是具体要求: [详细描述] # 步骤 3如果 /compact 也卡住 /clear 重新开始: [详细描述]方案三提供更明确的指令# 模糊指令容易导致循环: 找到所有需要优化的代码 # 明确指令: 在 src/api/ 目录下找到所有超过 50 行的函数 列出所有包含 TODO 注释的文件 检查 src/database.js 中是否有 SQL 注入风险 # 提供搜索范围和具体标准方案四分步执行避免循环# 不要一次性给出复杂任务: 找到所有 bug 并修复 # 分步执行: 步骤 1: 列出 src/ 下所有文件 # 查看结果 步骤 2: 读取 src/auth.js 的内容 # 查看结果 步骤 3: 检查其中的认证逻辑 # 逐步推进方案五限制连续工具调用次数# 步骤 1在 settings.json 中限制 cat ~/.claude/settings.json EOF { maxConsecutiveToolCalls: 10, maxToolCallsPerTurn: 15 } EOF # 步骤 2重启 Claude Code claude # 超过限制后会自动停止并等待用户指令方案六避免 Auto 模式下的失控# 步骤 1不使用 Auto 模式处理复杂任务 claude # 不加 --auto # 步骤 2手动审批每个工具调用 # 当发现循环趋势时拒绝调用并重新指导 # 步骤 3如果必须用 Auto 模式 # 在 settings.json 中限制: { maxConsecutiveToolCalls: 5, autoApprove: true }4. 各方案对比总结方案适用场景推荐指数难度方案一Escape 中断即时止损⭐⭐⭐⭐⭐低方案二/compact清除循环状态⭐⭐⭐⭐⭐低方案三明确指令预防循环⭐⭐⭐⭐⭐低方案四分步执行复杂任务⭐⭐⭐⭐低方案五限制调用数长期预防⭐⭐⭐⭐低方案六避免 Auto防止失控⭐⭐⭐低5. 常见问题 FAQ5.1 工具调用上限是多少默认连续工具调用上限为 25 次。可以在 settings.json 中通过maxConsecutiveToolCalls调整。5.2 为什么 Claude 会反复读取同一个文件可能是文件内容复杂Claude 读取后未能完全理解。或者是上下文压缩后之前的读取结果丢失Claude 忘记已经读过了。5.3 中断后如何恢复工作中断后使用/compact清除循环状态然后提供新的明确指令继续工作。不需要/clear除非上下文已经非常混乱。5.4 修改-验证循环如何避免在指令中明确告诉 Claude 何时停止验证 修改这个函数修改后运行一次测试即可不要反复修改5.5 MCP 工具返回空结果导致循环MCP 工具可能因参数错误返回空。告诉 Claude 结果为空并更换策略 搜索没有结果请改用 grep 命令搜索5.6 Auto 模式下循环消耗大量 TokenAuto 模式下的循环会快速消耗配额。在 settings.json 中限制maxConsecutiveToolCalls为 5-10 次避免失控。5.7 能否完全禁止循环可以设置maxConsecutiveToolCalls: 1每次只允许一个工具调用。但这会严重影响效率不推荐。5.8 上下文压缩后导致的循环/compact可能丢失之前的工具调用结果。如果 Claude 反复调用工具因为忘记了结果使用/clear后手动提供关键信息。5.9 CI/CD 中出现循环CI/CD 中无法手动中断。设置严格的maxConsecutiveToolCalls限制并使用--print模式避免交互式循环。5.10 排查清单速查表□ 1. 按 Escape 或 CtrlC 中断循环 □ 2. 执行 /compact 清除循环状态 □ 3. 提供更明确的指令指定范围和标准 □ 4. 复杂任务分步执行 □ 5. 在 settings.json 中设置 maxConsecutiveToolCalls □ 6. Auto 模式下设置更低的限制5-10 □ 7. 搜索无结果时更换策略 □ 8. 修改-验证循环时明确只验证一次 □ 9. CI/CD 中使用 --print 模式 □ 10. /compact 后检查是否丢失了关键结果6. 总结根本原因工具无限循环最常见原因是搜索无结果反复调用35%和修改-验证循环25%Claude Code 在结果不满足预期时缺乏退出条件最佳实践按 Escape 立即中断循环然后执行/compact清除循环状态提供更明确的指令重新开始预防措施在settings.json中设置maxConsecutiveToolCalls: 10防止失控循环消耗大量 Token指令优化提供明确的搜索范围和标准如在 src/api/ 下找超过 50 行的函数避免模糊指令导致反复尝试最佳实践建议使用 Auto 模式时设置更低的连续调用限制5-10 次并避免在 Auto 模式下执行需要反复搜索的探索性任务故障排查流程图flowchart TD A[工具无限循环] -- B[按 Escape 中断] B -- C[执行 /compact] C -- D{上下文是否清晰?} D --|是| E[提供更明确的指令] D --|否| F[执行 /clear] F -- G[手动提供关键上下文] E -- H[分步执行任务] G -- H H -- I{循环是否再现?} I --|否| J[✅ 问题解决] I --|是| K[在 settings.json 设置限制] K -- L[maxConsecutiveToolCalls: 10] L -- M[重启 Claude Code] M -- N[避免 Auto 模式] N -- J
【Bug已解决】Maximum recursion depth exceeded / Infinite tool loop — Claude Code 工具无限循环解决方案
发布时间：2026/7/7 22:30:28
【Bug已解决】Maximum recursion depth exceeded / Infinite tool loop — Claude Code 工具无限循环解决方案1. 问题描述在 Claude Code 中执行任务时Claude Code 反复调用同一个工具陷入无限循环终端不断滚动相同的操作 重构这个函数 # Claude Code 调用 Read 工具读取文件 Read file: src/index.js # 然后又调用 Read 读取同一个文件 Read file: src/index.js # 反复循环... Read file: src/index.js # ...持续 20 次 Error: Maximum recursion depth exceeded Tool call limit reached: 25 consecutive tool calls这个问题在以下场景中特别常见文件内容超出 Claude 的理解范围反复读取修改文件后验证失败反复修改和验证MCP 工具返回空结果Claude 反复调用搜索操作没有找到结果反复搜索Auto 模式下 Claude 自主循环调用工具# 典型复现过程 $ claude 搜索项目中所有使用 deprecated API 的地方 # Claude 反复搜索... search_content: deprecated → 0 results search_content: deprecated → 0 results search_content: deprecated → 0 results # ... 20 次 Tool call limit reached2. 原因分析核心原理拆解Claude Code 调用工具 → 结果不满足预期 ↓ Claude 认为需要重新调用 → 再次调用相同工具 ↓ 结果仍然不满足 → 继续调用 ↓ 达到工具调用上限 → Maximum recursion depth exceeded原因分类表原因分类具体表现占比搜索无结果反复搜索找不到内容约 35%修改-验证循环修改后验证失败反复修改约 25%空结果循环MCP 工具返回空反复调用约 20%上下文丢失之前的结果被压缩后遗忘约 10%Auto 模式失控自动模式无限制调用约 10%3. 解决方案方案一按 Escape 中断循环最推荐# 步骤 1按 Escape 或 CtrlC 中断当前操作 # Claude Code 会停止工具调用 # 步骤 2提供更明确的指令 搜索已经完成了没有找到结果。请改用其他方式查找 # 步骤 3提供具体方向 不用再搜索了直接在 src/api/ 目录下查找方案二使用 /compact 打断循环# 步骤 1中断后执行 /compact /compact # 压缩上下文清除循环状态 # 步骤 2重新提供明确指令 不要重复搜索。以下是具体要求: [详细描述] # 步骤 3如果 /compact 也卡住 /clear 重新开始: [详细描述]方案三提供更明确的指令# 模糊指令容易导致循环: 找到所有需要优化的代码 # 明确指令: 在 src/api/ 目录下找到所有超过 50 行的函数 列出所有包含 TODO 注释的文件 检查 src/database.js 中是否有 SQL 注入风险 # 提供搜索范围和具体标准方案四分步执行避免循环# 不要一次性给出复杂任务: 找到所有 bug 并修复 # 分步执行: 步骤 1: 列出 src/ 下所有文件 # 查看结果 步骤 2: 读取 src/auth.js 的内容 # 查看结果 步骤 3: 检查其中的认证逻辑 # 逐步推进方案五限制连续工具调用次数# 步骤 1在 settings.json 中限制 cat ~/.claude/settings.json EOF { maxConsecutiveToolCalls: 10, maxToolCallsPerTurn: 15 } EOF # 步骤 2重启 Claude Code claude # 超过限制后会自动停止并等待用户指令方案六避免 Auto 模式下的失控# 步骤 1不使用 Auto 模式处理复杂任务 claude # 不加 --auto # 步骤 2手动审批每个工具调用 # 当发现循环趋势时拒绝调用并重新指导 # 步骤 3如果必须用 Auto 模式 # 在 settings.json 中限制: { maxConsecutiveToolCalls: 5, autoApprove: true }4. 各方案对比总结方案适用场景推荐指数难度方案一Escape 中断即时止损⭐⭐⭐⭐⭐低方案二/compact清除循环状态⭐⭐⭐⭐⭐低方案三明确指令预防循环⭐⭐⭐⭐⭐低方案四分步执行复杂任务⭐⭐⭐⭐低方案五限制调用数长期预防⭐⭐⭐⭐低方案六避免 Auto防止失控⭐⭐⭐低5. 常见问题 FAQ5.1 工具调用上限是多少默认连续工具调用上限为 25 次。可以在 settings.json 中通过maxConsecutiveToolCalls调整。5.2 为什么 Claude 会反复读取同一个文件可能是文件内容复杂Claude 读取后未能完全理解。或者是上下文压缩后之前的读取结果丢失Claude 忘记已经读过了。5.3 中断后如何恢复工作中断后使用/compact清除循环状态然后提供新的明确指令继续工作。不需要/clear除非上下文已经非常混乱。5.4 修改-验证循环如何避免在指令中明确告诉 Claude 何时停止验证 修改这个函数修改后运行一次测试即可不要反复修改5.5 MCP 工具返回空结果导致循环MCP 工具可能因参数错误返回空。告诉 Claude 结果为空并更换策略 搜索没有结果请改用 grep 命令搜索5.6 Auto 模式下循环消耗大量 TokenAuto 模式下的循环会快速消耗配额。在 settings.json 中限制maxConsecutiveToolCalls为 5-10 次避免失控。5.7 能否完全禁止循环可以设置maxConsecutiveToolCalls: 1每次只允许一个工具调用。但这会严重影响效率不推荐。5.8 上下文压缩后导致的循环/compact可能丢失之前的工具调用结果。如果 Claude 反复调用工具因为忘记了结果使用/clear后手动提供关键信息。5.9 CI/CD 中出现循环CI/CD 中无法手动中断。设置严格的maxConsecutiveToolCalls限制并使用--print模式避免交互式循环。5.10 排查清单速查表□ 1. 按 Escape 或 CtrlC 中断循环 □ 2. 执行 /compact 清除循环状态 □ 3. 提供更明确的指令指定范围和标准 □ 4. 复杂任务分步执行 □ 5. 在 settings.json 中设置 maxConsecutiveToolCalls □ 6. Auto 模式下设置更低的限制5-10 □ 7. 搜索无结果时更换策略 □ 8. 修改-验证循环时明确只验证一次 □ 9. CI/CD 中使用 --print 模式 □ 10. /compact 后检查是否丢失了关键结果6. 总结根本原因工具无限循环最常见原因是搜索无结果反复调用35%和修改-验证循环25%Claude Code 在结果不满足预期时缺乏退出条件最佳实践按 Escape 立即中断循环然后执行/compact清除循环状态提供更明确的指令重新开始预防措施在settings.json中设置maxConsecutiveToolCalls: 10防止失控循环消耗大量 Token指令优化提供明确的搜索范围和标准如在 src/api/ 下找超过 50 行的函数避免模糊指令导致反复尝试最佳实践建议使用 Auto 模式时设置更低的连续调用限制5-10 次并避免在 Auto 模式下执行需要反复搜索的探索性任务故障排查流程图flowchart TD A[工具无限循环] -- B[按 Escape 中断] B -- C[执行 /compact] C -- D{上下文是否清晰?} D --|是| E[提供更明确的指令] D --|否| F[执行 /clear] F -- G[手动提供关键上下文] E -- H[分步执行任务] G -- H H -- I{循环是否再现?} I --|否| J[✅ 问题解决] I --|是| K[在 settings.json 设置限制] K -- L[maxConsecutiveToolCalls: 10] L -- M[重启 Claude Code] M -- N[避免 Auto 模式] N -- J
 获取与实战)
