🔧 Tool Execution：工具执行

AI说"我要用锤子"，你得告诉它锤子在哪、怎么拿、砸不砸到手指

📅 2026-04-28 🏷️ 核心机制 ⏱️ 阅读约10分钟 ⚡ 执行流程

什么是 Tool Execution？

凌晨3点17分，Agent说它要搜索天气。2秒后，它告诉我明天有雨。这中间发生的事，就叫Tool Execution——工具执行。

想象你是个木匠，客户让你做个柜子。你说"我要锯子"，助手把锯子递给你；你说"我要钉子"，助手把钉子递给你；你锯错了，助手没拦你——这就是工具执行的三个维度：工具调用、参数传递、错误处理。

在Agent世界里，AI是木匠，Tools是工具箱，Execution是整个干活的过程。AI说"搜索天气"（调用）→系统传入"北京"（参数）→天气API返回结果（执行）→AI告诉你带伞（应用）。

执行流程全景图

1️⃣ Tool Selection - AI决定用哪个工具
2️⃣ Parameter Binding - AI生成调用参数
3️⃣ Execution - 系统实际执行工具
4️⃣ Result Processing - 处理返回结果
5️⃣ Observation - AI观察结果并决策

关键概念

Tool Call：AI发起的工具调用请求，包含工具名和参数

Tool Result：工具执行后的返回结果，可能是成功数据或错误信息

Tool Round：一次完整的调用-执行-返回循环

Multi-turn Execution：AI可能多次调用工具来完成复杂任务

执行模式对比

🐦 Sequential - 顺序执行

# 一个接一个，像排队买奶茶
Step 1: search_weather("北京") → 返回: 晴
Step 2: search_clothes("晴天") → 返回: T恤
Step 3: generate_response() → 输出: 穿T恤吧

🚀 Parallel - 并行执行

# 同时开干，像多条流水线
Parallel:
  - search_weather("北京")
  - search_clothes("晴天")
  - search_traffic("北京")
Wait: all completed
Merge: results → 输出综合建议

🔄 Retry - 重试机制

# 失败了就再来，像倔强的程序员
Attempt 1: API调用 → Timeout
Attempt 2: API调用 → Error 500
Attempt 3: API调用 → Success!
Max retries: 3
OpenClaw默认使用智能调度：独立工具并行执行，依赖工具顺序执行。你配置的dependencies字段决定了工具间的依赖关系。

OpenClaw 实战配置

工具执行配置

# TOOLS.md - 工具执行参数配置

execution:
  mode: auto  # auto | sequential | parallel
  timeout: 30000  # 单工具超时30秒
  max_retries: 3
  retry_delay: 1000  # 重试间隔1秒
  
error_handling:
  on_fail: continue  # continue | stop | ask_user
  log_errors: true
  fallback: "工具暂时不可用，请稍后重试"

并行执行示例

tools:
  - name: search_news
    parallel: true  # 可与其他工具并行
    
  - name: analyze_sentiment
    parallel: true
    depends_on: []  # 无依赖
    
  - name: generate_report
    parallel: false
    depends_on: [search_news, analyze_sentiment]

权限控制

# 敏感工具需要审批
tools:
  - name: delete_files
    approval: required  # 需要用户确认
    approval_timeout: 60000
    
  - name: send_email
    approval: optional  # 用户可选确认
踩坑：有次我没设timeout，Agent调API等了5分钟没反应——那API早就崩了。教训：每个工具都要设timeout，尤其是外部API调用。

错误处理策略

常见错误类型

# 1. 工具不存在
Error: Tool 'weather_search' not found
→ 检查工具名拼写，确认工具已注册

# 2. 参数错误
Error: Missing required parameter 'location'
→ AI生成的参数不完整，检查工具描述

# 3. 执行超时
Error: Tool execution timeout after 30000ms
→ 工具执行太慢，考虑增加timeout或异步处理

# 4. 权限不足
Error: Permission denied for tool 'delete_files'
→ 需要用户审批或检查权限配置

# 5. 外部服务错误
Error: API returned 500 Internal Server Error
→ 第三方服务问题，考虑重试或fallback

错误处理配置

error_handling:
  strategies:
    timeout: retry
    not_found: ask_model  # 让AI选择替代工具
    permission: request_approval
    external_error: fallback

执行监控与调试

执行日志示例

[04:17:32] 🔧 Tool Selected: search_weather
[04:17:32] 📝 Parameters: {"location": "北京"}
[04:17:33] ✅ Execution Started
[04:17:35] 📨 Result: {"temp": 25, "condition": "晴"}
[04:17:35] 🔄 Round 1 Complete (2.3s)

调试技巧

1. 启用详细日志：设置 log_level: debug

2. 单步执行：设置 execution_mode: manual

3. 模拟执行：设置 dry_run: true 测试流程

4. 断点调试：在关键工具后插入pause

最佳实践清单

✅ 设置合理的timeout（API调用30秒，本地操作10秒）

✅ 敏感工具必须approval_required

✅ 为每个工具配置fallback错误提示

✅ 并行执行前检查依赖关系

✅ 记录执行日志用于调试和审计

✅ 定期检查工具执行成功率

✅ 外部API调用加重试机制

✅ 复杂任务拆分成多个工具步骤

另一个坑：工具返回结果太大（比如整个数据库），把上下文撑爆了。解决方案：工具应该返回摘要，不是原始数据；或者用pagination分批返回。

相关链接

Tool Calling详解 工具使用模式 并行执行指南 错误处理最佳实践

📚 相关页面