Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
针对最常见的工具使用错误的症状到修复方法表格。每个修复方法都交叉引用了拥有该功能的页面。
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| 您想要工具 B 时 Claude 调用了工具 A | 描述存在歧义 | 完善描述。通过"何时"使用工具来区分工具，而不仅仅是它们"做什么"。请参阅定义工具。 |
| Claude 从不调用您的工具 | 工具名称冲突或模式过于通用 | 检查工具列表中是否存在重复名称。添加 input_examples 以使预期用途更具体。 |
| Claude 使用错误的参数类型进行调用 | 模型对模糊的模式进行猜测 | 添加 strict: true（如果您的模式在支持的子集中）或添加 input_examples。 |
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| 您的模式中不存在的参数 | 未启用严格模式时模型过度生成 | 如果您的模式在支持的子集中，请添加 strict: true。 |
| 参数值超出您的枚举范围 | 缺少严格模式或枚举过大 | 缩小枚举范围或添加 input_examples 来展示有效选项。 |
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| 在并行更好的情况下 Claude 仍按顺序调用工具 | 消息历史格式问题 | 在一条用户消息中发送多个 tool_result 块，而不是每轮发送一个。请参阅并行工具使用。 |
disable_parallel_tool_use 似乎被忽略 | 在对话中设置得太晚 | 必须在返回 tool_use 的请求上设置。在后续请求上设置它对之前的工具调用没有影响。 |
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| 每个请求都是缓存未命中 | tool_choice、思考配置或 output_config.effort 在请求之间发生变化 | 保持 tool_choice 稳定，或将 cache_control 断点放在变化点之前；在缓存对话的整个生命周期内保持思考配置和努力级别不变。请参阅工具使用与提示缓存和思考与提示缓存。 |
| 在对话中途添加工具会破坏缓存 | 工具被添加到工具数组的开头 | 使用 defer_loading: true 配合工具搜索来内联追加工具，而不是修改数组头部。 |
| 错误 | 原因 | 修复方法 |
|---|---|---|
tool_use ids were found without tool_result blocks immediately after | 某些 tool_use id 缺少 tool_result，或者 tool_result 不是用户消息中的第一个内容块 | 为助手响应中的每个 tool_use 块返回一个 tool_result。将 tool_result 块放在任何文本之前。请参阅处理工具调用和并行工具使用。 |
was found without a corresponding <name>_tool_result block | 前一个助手轮次有一个没有结果块的 server_tool_use 块（最常见的情况是 Claude 将其与客户端工具一起调用），并且要么您的下一条用户消息结束了该轮次（例如，在 tool_result 块之后有文本），要么恢复请求不再定义该服务器工具（此时消息以 but no <name> tool was provided 结尾） | 发送一条仅包含客户端 tool_use id 的 tool_result 块的用户消息，并保持相同的 tools 数组。请参阅停止原因和回退。 |
Input schema is not compatible with strict mode: string patterns are not supported | 将 pattern 与 strict: true 一起使用 | 移除 pattern 或删除 strict: true。pattern 关键字尚不在支持的 JSON Schema 子集中。 |
All tools have defer_loading: true | 模型看不到任何工具 | 至少必须有一个工具被立即加载。工具搜索工具本身绝不能设置 defer_loading: true。 |
如果在工具调用后继续对话时，请求失败并返回 400 invalid_request_error，其消息包含 `thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified，则说明您的应用程序在将助手的思考块发送回去之前对其进行了修改。请将整个助手消息原封不动地发送回去，然后追加您的 tool_result。
请参阅思考块无法被修改了解完整的错误信息和修复步骤。
| 症状 | 可能原因 | 修复方法 |
|---|---|---|
| Claude 拒绝根据工具结果采取行动，或要求用户确认来自工具结果的指令 | 您自己的指令被放在了 tool_result 内容中传递 | Claude 经过训练，会将工具结果中的指令视为可能不可信的第三方内容。将您的指令移出工具结果：在 tool_result 块之后的 user 轮次中发送它们，或者在支持的模型上，使用对话中途系统消息。让工具结果只包含数据。请参阅缓解越狱和提示注入。 |
| 症状 | 原因 | 修复方法 |
|---|---|---|
| 在较新的模型上对工具输入进行字符串比较失败 | Unicode 和正斜杠转义在不同模型版本之间有所不同 | 使用 json.loads() 或 JSON.parse() 进行解析。切勿对序列化的输入进行原始字符串匹配。 |
Was this page helpful?