【Bug已解决】openclaw: "tool call timeout" / Function execution exceeded limit — OpenClaw 工具调用超时解决方案
1. 问题描述
OpenClaw 在执行工具调用时超时：
# 工具调用超时 $ openclaw --auto-approve "运行 npm install" Error: Tool call timeout 'npm install' exceeded 30000ms limit. # 或命令执行超时 $ openclaw --auto-approve "运行测试" Error: Command timeout 'npm test' exceeded 60000ms. # 或文件操作超时 $ openclaw --auto-approve "分析大文件" Error: File operation timeout Reading large_file.js exceeded 30000ms. # 或 MCP 工具超时 $ openclaw "使用搜索工具" Error: MCP tool timeout Tool 'code_search' did not respond in 30000ms.这个问题在以下场景中特别常见：
- 命令执行时间过长（npm install、测试）
- 大文件读取
- 网络请求慢
- MCP 工具响应慢
- 默认超时过小
- 系统资源不足
2. 原因分析
原因分类表
| 原因分类 | 具体表现 | 占比 |
|---|---|---|
| 命令执行长 | npm install | 约 35% |
| 大文件读取 | > 10MB | 约 25% |
| 默认超时小 | 30s | 约 20% |
| MCP 慢 | 工具 | 约 10% |
| 网络请求 | 慢 | 约 5% |
| 资源不足 | CPU/内存 | 约 5% |
3. 解决方案
方案一：增加超时（最推荐）
# 步骤 1：增加工具超时 export OPENCLAW_TOOL_TIMEOUT=120000 # 120 秒 # 步骤 2：永久设置 echo 'export OPENCLAW_TOOL_TIMEOUT=120000' >> ~/.bashrc source ~/.bashrc # 步骤 3：或在配置中设置 cat > .openclaw/config.json << 'EOF' { "toolTimeout": 120000 } EOF # 步骤 4：验证 openclaw --auto-approve "运行 npm install"方案二：分步执行长命令
# 步骤 1：拆分长命令 openclaw --auto-approve "运行 npm install --prefer-offline" # 步骤 2：或先安装依赖 npm install # 手动先执行 openclaw --auto-approve "运行 npm test" # 步骤 3：使用更快命令 openclaw --auto-approve "运行 npm test -- --bail" # 步骤 4：验证 openclaw --auto-approve "运行 echo hello"方案三：预处理大文件
# 步骤 1：分块读取 head -n 200 large_file.js > /tmp/preview.js openclaw --auto-approve "分析 /tmp/preview.js" # 步骤 2：使用 grep 过滤 grep "function" large_file.js > /tmp/functions.txt openclaw --auto-approve "分析 /tmp/functions.txt" # 步骤 3：使用 wc 检查大小 wc -l large_file.js # 步骤 4：验证 openclaw --auto-approve "分析 /tmp/preview.js"方案四：使用 --max-turns 控制
# 步骤 1：限制轮次 openclaw --auto-approve --max-turns 5 "task" # 步骤 2：分步执行 openclaw --auto-approve --max-turns 3 "第一步" openclaw --auto-approve --max-turns 3 "第二步" # 步骤 3：避免长任务 # 不要让 OpenClaw 执行可能很长的命令 # 步骤 4：验证 openclaw --auto-approve --max-turns 1 "echo hello"方案五：增加 MCP 超时
# 步骤 1：增加 MCP 超时 cat > .openclaw/mcp_config.json << 'EOF' { "servers": { "code-search": { "timeout": 60000 } } } EOF # 步骤 2：或环境变量 export OPENCLAW_MCP_TIMEOUT=60000 # 步骤 3：验证 python3 -m json.tool .openclaw/mcp_config.json openclaw "使用搜索工具" # 步骤 4：验证 openclaw --mcp-status方案六：手动执行命令
# 步骤 1：手动执行长命令 npm install # 手动执行 npm test # 手动执行 # 步骤 2：让 OpenClaw 分析结果 openclaw --print "分析 npm test 的输出: $(cat test-results.txt)" # 步骤 3：或让 OpenClaw 只做分析 openclaw "分析 test-results.txt" # 步骤 4：验证 openclaw --print "hello"4. 各方案对比总结
| 方案 | 适用场景 | 推荐指数 | 难度 |
|---|---|---|---|
| 方案一：增加超时 | 通用 | ⭐⭐⭐⭐⭐ | 低 |
| 方案二：分步命令 | 长命令 | ⭐⭐⭐⭐⭐ | 低 |
| 方案三：预处理 | 大文件 | ⭐⭐⭐⭐⭐ | 低 |
| 方案四：--max-turns | 控制 | ⭐⭐⭐⭐ | 低 |
| 方案五：MCP 超时 | MCP | ⭐⭐⭐⭐ | 低 |
| 方案六：手动执行 | 长任务 | ⭐⭐⭐⭐⭐ | 低 |
5. 常见问题 FAQ
5.1 默认工具超时多少
通常 30 秒。通过OPENCLAW_TOOL_TIMEOUT调整。
5.2 如何增加超时
export OPENCLAW_TOOL_TIMEOUT=120000 # 120 秒5.3 npm install 超时
增加超时或手动执行npm install。
5.4 大文件读取超时
使用head -n 200或grep预处理。
5.5 MCP 工具超时
在 mcp_config.json 中设置timeout: 60000。
5.6 如何分步执行
拆分长任务为多个小任务，使用--max-turns 5。
5.7 --max-turns 有什么用
限制工具调用轮次，避免长时间执行。
5.8 手动执行命令
先手动执行长命令，让 OpenClaw 只分析结果。
5.9 如何在配置中设置
{"toolTimeout": 120000}5.10 排查清单速查表
□ 1. OPENCLAW_TOOL_TIMEOUT=120000 □ 2. config.json: toolTimeout 120000 □ 3. 分步执行长命令 □ 4. npm install 手动执行 □ 5. head -n 200 预处理大文件 □ 6. grep 过滤大文件 □ 7. --max-turns 5 限制轮次 □ 8. OPENCLAW_MCP_TIMEOUT=60000 □ 9. mcp_config.json: timeout 60000 □ 10. 手动执行 + 分析结果6. 总结
- 根本原因：工具调用超时最常见原因是命令执行过长（35%）和大文件读取（25%）
- 最佳实践：使用
export OPENCLAW_TOOL_TIMEOUT=120000增加超时 - 分步执行：拆分长命令，使用
--max-turns 5限制轮次 - 预处理大文件：
head -n 200或grep过滤后再读取 - 最佳实践建议：手动执行长命令（npm install），让 OpenClaw 只分析结果
故障排查流程图
flowchart TD A[工具调用超时] --> B[增加超时] B --> C[OPENCLAW_TOOL_TIMEOUT=120000] C --> D[openclaw 验证] D --> E{成功?} E -->|是| F[✅ 问题解决] E -->|否| G{是命令超时?} G -->|是| H[分步执行] G -->|否| I{是大文件?} H --> j[手动执行长命令] j --> K[openclaw 分析结果] K --> F I -->|是| L[预处理文件] L --> M[head -n 200 过滤] M --> N[openclaw 分析 /tmp/preview] N --> F I -->|否| O{是 MCP?} O -->|是| P[增加 MCP 超时] P --> Q[OPENCLAW_MCP_TIMEOUT=60000] Q --> D O -->|否| R[使用 --max-turns] R --> S[--max-turns 5 限制轮次] S --> D D --> T{成功?} T -->|是| F T -->|否| U[在配置中设置] U --> V[config.json: toolTimeout 120000] V --> D F --> W[长期: 超时 + 分步 + 预处理] W --> X[✅ 长期方案]
