报错排查 · 工具调用

工具调用失败:三种原因占九成

代理类客户端(Cline、Roo、Open Interpreter)全靠工具调用驱动。失败通常是模型不支持、参数不合法、消息序列不对这三类。

三类原因

  1. 模型不支持 tools:模型返回普通文本,客户端以为它「不干活」。低价兼容模型常见;
  2. 参数 JSON 不合法:模型输出的 arguments 不是合法 JSON,客户端解析失败;
  3. 消息序列错误:tool 结果必须紧跟对应的 assistant tool_calls,顺序错了就 400。

最小复现

带一个工具的请求bash
curl https://hardysapi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-5","messages":[{"role":"user","content":"北京天气"}],
       "tools":[{"type":"function","function":{"name":"get_weather","description":"查天气",
       "parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}}]}'

返回里出现 tool_calls 数组,说明该模型与链路支持工具调用;返回纯文本则是不支持。

strict 模式

strict: true 要求模型严格遵守 JSON Schema,兼容层实现程度不一。报 400 时先去掉 strict, 改用提示词约束格式,再在代码里校验 JSON。

客户端侧建议

  • Cline / Roo Code 遇到「模型不调用工具」,换 claude-sonnet-4-5、gpt-5.5 这类完整支持的模型;
  • 长任务中途报 400,检查是否有工具结果缺失(请求被中断导致的半截消息);
  • 并发工具调用(并行 tool_calls)部分模型只支持单个,关掉并行可规避。

常见问题

模型不返回 tool_calls 怎么办?

该模型大概率不支持工具调用,换用完整支持 function calling 的模型,如 claude-sonnet-4-5、gpt-5.5。

工具调用 400 错误常见原因是什么?

messages 里 tool 消息没有对应的 assistant tool_calls,或顺序被打乱;按「assistant(tool_calls) → tool 结果」成对出现即可。