【Bug已解决】Claude: tool_use error / Tool execution failed — Claude 工具调用失败解决方案1. 问题描述Claude 在调用工具时出现错误或工具执行失败# 工具调用失败 $ claude 读取 src/index.js Error: tool_use failed Tool Read execution error: File not found. # 或工具结果无效 $ claude 运行 npm test Error: Invalid tool result Tool Bash returned invalid output. # 或工具超时 $ claude 运行 build Error: Tool timeout Tool Bash exceeded 30000ms timeout. # 或工具权限被拒绝 $ claude 删除 src/old.js Error: Tool permission denied Tool Bash was not approved.这个问题在以下场景中特别常见文件路径错误命令执行超时工具权限未授予工具结果格式错误工具不存在沙箱限制2. 原因分析原因分类表原因分类具体表现占比路径错误文件不存在约 30%超时Bash 超时约 25%权限未授予审批拒绝约 20%结果无效格式错误约 10%沙箱限制禁止操作约 10%工具不存在版本旧约 5%3. 解决方案方案一检查文件路径最推荐# 步骤 1确认文件存在 ls -la src/index.js # 步骤 2使用正确路径 claude 读取 ./src/index.js # 步骤 3或使用绝对路径 claude 读取 /project/src/index.js # 步骤 4验证 claude 运行 ls -la src/方案二增加超时# 步骤 1设置 Bash 超时 export CLAUDE_BASH_TIMEOUT120000 # 120 秒 claude 运行 npm test # 步骤 2或在配置中 cat ~/.claude/settings.json EOF { toolTimeout: 120000 } EOF # 步骤 3长命令拆分 claude 运行 npm run build:step1 claude 运行 npm run build:step2 # 步骤 4验证 claude 运行 echo hello方案三使用 --allowedTools# 步骤 1允许特定工具 claude --allowedTools Read,Write,Bash task # 步骤 2或 --dangerously-skip-permissions不推荐 claude --dangerously-skip-permissions task # 步骤 3在配置中设置 cat ~/.claude/settings.json EOF { allowedTools: [Read, Write, Bash, Edit] } EOF # 步骤 4验证 claude --allowedTools Bash 运行 echo hello方案四使用 --auto-approve# 步骤 1自动审批工具调用 claude --auto-approve task # 步骤 2或 --print --auto-approve claude --print --auto-approve task --max-turns 10 # 步骤 3CI/CD 中 claude --print --auto-approve 运行 npm test --max-turns 10 # 步骤 4验证 claude --auto-approve 运行 echo hello方案五检查沙箱配置# 步骤 1检查沙箱 cat ~/.claude/settings.json | grep -A5 sandbox # 步骤 2放宽沙箱 cat ~/.claude/settings.json EOF { sandbox: { enabled: true, allowedDirectories: [./src, ./tests, ./node_modules] } } EOF # 步骤 3或禁用沙箱 claude --no-sandbox task # 步骤 4验证 claude --auto-approve 运行 ls src/方案六更新 Claude Code# 步骤 1检查版本 claude --version # 步骤 2更新 npm update -g anthropic-ai/claude-code # 步骤 3验证工具支持 claude --help | grep -i tool # 步骤 4测试 claude --print 运行 echo hello --max-turns 54. 各方案对比总结方案适用场景推荐指数难度方案一检查路径文件不存在⭐⭐⭐⭐⭐低方案二增加超时超时⭐⭐⭐⭐⭐低方案三--allowedTools权限⭐⭐⭐⭐⭐低方案四--auto-approve审批⭐⭐⭐⭐⭐低方案五沙箱限制⭐⭐⭐⭐低方案六更新版本⭐⭐⭐低5. 常见问题 FAQ5.1 Claude 有哪些工具Read: 读取文件Write: 写入文件Edit: 编辑文件Bash: 执行命令Search: 搜索文件等等5.2 如何允许工具claude --allowedTools Read,Write,Bash task # 或 --auto-approve5.3 工具超时怎么办设置CLAUDE_BASH_TIMEOUT120000120 秒。5.4 --dangerously-skip-permissions 是什么跳过所有权限审批。不推荐在生产环境使用。5.5 工具调用失败常见原因文件不存在、命令超时、权限未授予、沙箱限制。5.6 如何查看工具调用日志claude --verbose task 21 | grep -i tool5.7 沙箱限制什么限制 Claude 可以读取/修改的目录和执行的命令。5.8 --auto-approve 和 --allowedTools 的区别--allowedTools: 指定允许的工具列表--auto-approve: 自动审批所有工具调用5.9 CI/CD 中如何使用工具claude --print --auto-approve 运行 npm test --max-turns 105.10 排查清单速查表□ 1. ls -la 确认文件存在 □ 2. 使用正确路径 □ 3. CLAUDE_BASH_TIMEOUT120000 □ 4. --allowedTools Read,Write,Bash □ 5. --auto-approve 自动审批 □ 6. --print --auto-approve CI/CD □ 7. sandbox.allowedDirectories 放宽 □ 8. --no-sandbox 临时禁用 □ 9. --verbose 查看工具日志 □ 10. npm update 更新 Claude Code6. 总结根本原因工具调用失败最常见原因是文件路径错误30%和超时25%最佳实践确认文件路径使用--allowedTools Read,Write,Bash授予权限超时设置CLAUDE_BASH_TIMEOUT120000增加 Bash 工具超时到 120 秒自动审批使用--auto-approve或--print --auto-approve自动审批工具调用最佳实践建议CI/CD 中使用claude --print --auto-approve task --max-turns 10配置sandbox.allowedDirectories故障排查流程图flowchart TD A[工具调用失败] -- B{是文件问题?} B --|是| C[ls -la 确认路径] B --|否| D{是超时?} C -- E[使用正确路径] E -- F[claude 验证] D --|是| G[增加 CLAUDE_BASH_TIMEOUT] D --|否| H{是权限?} G -- I[或拆分长命令] I -- F H --|是| j[--allowedTools 授权] H --|否| K{是沙箱?} j -- L[或 --auto-approve] L -- F K --|是| M[放宽 allowedDirectories] K --|否| N[更新版本] M -- O[或 --no-sandbox] O -- F N -- P[npm update -g claude-code] P -- F F -- Q{成功?} Q --|是| R[✅ 问题解决] Q --|否| S[使用 --verbose] S -- T[查看工具日志] T -- U[根据日志修复] U -- F R -- V[长期: allowedTools timeout sandbox] V -- W[✅ 长期方案]