这阵子不少人在问GPT 5.6/6调用工具失败怎么修。我自己也踩过一轮，从最初的崩溃式排查到后来找到规律，前后折腾了三天。如果你现在正被"模型返回了一堆废话就是不调用工具"或者"调是调了，参数却全是错的"这类问题折磨，这篇文章应该能帮你省下不少时间。

先说清楚这篇文章的定位：它是一份基于真实排障过程的修复笔记，覆盖了工具调用失败的类型识别、复现方法、工具定义写法、多轮调用和超时问题，以及上线后的兜底方案。适合正在做Agent应用、写function calling代码、或者刚把模型版本升级到新系列的开发者参考，不需要你有很深的底层基础，按着章节走即可。

1. 别急着改代码，先给失败分个类

很多人一看到工具调用失败就冲进代码里改参数，结果改来改去问题还在。我自己的经验是，先花半小时把报错分类，方向对了，修复才有意义。这版模型暴露出来的失败，大部分可以归成四类。

1.1 超时型失败：模型迟迟不吐调用

超时型失败最迷惑人。现象是请求发过去之后，整个对话像卡住了一样，最后等来一个超时报错。你以为是网络问题，实际上是因为模型在内部推理"该调哪个工具、参数怎么填"的时候，消耗的时间超出了服务端或客户端的等待阈值。

这类失败有个特征：日志里能看到请求发起时间，但响应时间远超正常值，而且没有正常的工具调用结构返回。我遇到的一次情况是，某些复杂查询场景下模型生成tool_call的平均耗时是普通对话的三倍，原本设置的20秒客户端超时直接被打满。后面把超时阈值拉长，再对部分场景加了流式输出，肉眼可见成功率就上来了。

1.2 格式解析型失败：模型不按JSON Schema出牌

格式解析型失败是这版模型里最普遍的坑。模型生成了工具调用的意图，但返回的参数字段类型不对、少了必填字段，或者多了一些Schema里没定义的字段。最常见的报错是类似Invalid parameter: messages[1].tool_calls[0].function.arguments。

究其原因，是模型在生成结构化参数时产生了"幻觉字段"。比如我的Schema里只定义了city和date两个字符串字段，它却自己脑补出一个temperature或者把date写成了数组。这一类问题靠改代码往往很难根治，因为模型对Schema的理解取决于描述文本的清晰程度，后面我会专门讲怎么调整描述。

1.3 匹配错位型失败：tool_call_id和函数名对不上

匹配错位型失败通常发生在多轮工具调用场景。模型第一轮请求了一个工具，你执行完工具之后要把结果回传给模型，这个回传消息中必须带对tool_call_id。如果你回传时用了错误的ID，或者把工具结果放到了错误的消息顺序里，API会直接报错。

还有一种情况是函数名对不上。比如你在tools里定义的是get_weather，但模型返回的工具调用名称是getWeather，或者干脆是类似weather_info这样臆造出来的名字。这类问题多发生在函数名太长、大小写混合、命名语义不够清晰的时候。模型没记住你的函数名，本质上还是定义阶段的问题。

1.4 策略放弃型失败：模型选择不调用工具

策略放弃型失败最隐蔽，因为程序没有报错，一切看起来都正常，但模型就是回复了一段文本而不是调用工具。比如用户问"帮我查一下北京明天的天气"，按逻辑应该触发天气工具，但模型却回复"好的，请问您想查询哪里的天气呢"。

这种情况在新版模型里出现得尤其多，因为这些模型更强调对话能力，反而容易"忘记"什么时候该动用工具。要解决它，除了在系统提示词里加重工具调用规则，还可以用后面要讲的tool_choice参数做强制引导。

把失败归类之后，你再看手里的报错，思路会清晰很多。下一章我详细说一下我当时的完整排查链路，这套链路对上述四类问题基本都能定位到具体环节。

2. 把排查链路完整复现一遍

排查工具调用失败，最忌讳上来就改线上代码。我的做法是先剥离外层封装，做一个极简复现脚本，再逐步把环境加回去。这样能保证变量可控，也方便把锅精准甩给模型还是甩给代码。

2.1 最小复现：把外层封装全剥掉

我当时写了一个几十行的Python脚本，只保留最核心的动作：组装消息、调用模型、解析返回。没有Agent框架，没有中间层缓存，也没有业务拦截器。效果出奇地好，很多在完整系统里难以定位的报错，在极简脚本里几秒钟就能复现。

from openai import OpenAI client = OpenAI() tools = [ { "type": "function", "function": { "name": "get_weather", "description": "根据城市名和日期查询天气", "parameters": { "type": "object", "properties": { "city": {"type": "string", "description": "城市名，如北京"}, "date": {"type": "string", "description": "日期，格式YYYY-MM-DD"} }, "required": ["city", "date"] } } } ] resp = client.chat.completions.create( model="gpt-5.6", messages=[ {"role": "user", "content": "北京明天天气怎么样？"} ], tools=tools ) print(resp.choices[0].message)

这段脚本看起来简单，但它能帮你确认两件事：第一，模型到底有没有返回tool_calls字段；第二，如果返回了，里面的函数名和参数长什么样。如果在这个最小环境里都失败，说明问题不是你的业务代码造成的，而是模型配置、提示词或者工具定义本身。

2.2 全量日志：请求和响应，一个字段都不能丢

排查工具调用问题时，日志记录必须完整。很多开发者只记录最终结果，忽略中间字段，导致定位问题时无从下手。

我建议至少把以下几类信息完整记录：

• 发出去的messages数组全量内容，包括system提示词
• tools参数原始JSON
• 返回消息中的finish_reason、tool_calls、content字段
• 每次请求的耗时、重试次数和模型名称
• 工具真实执行后的结果以及回传给模型的tool消息

有个小技巧值得分享：给每次请求分配一个统一格式的请求ID，同时在日志里加上前端的trace标记，这样能把一次失败的完整链路串起来。当时我们排查一个偶发性的工具参数错误，就是靠这种全量日志锁定了是模型在生成arguments时偶尔会把日期字段截断，而不是我们的解析代码有问题。

2.3 定位到层：是模型没调，还是API不认

当你拿到一份完整的失败现场，就需要做一个三段式判断，把问题归到具体某一层：

第一段，看模型输出。如果finish_reason是tool_calls，说明模型确实调用了工具，问题出在后面；如果finish_reason是stop，且content里是对话文本，那就是模型压根没想调工具，属于策略放弃型失败。

第二段，看tool_calls里的函数名和参数是否与定义一致。如果不一致，是格式解析型或匹配错位型失败；如果完全一致，那问题就在你后面的工具执行和回传逻辑上。

第三段，看工具执行完之后的回传消息。确认role是否为tool，tool_call_id是否对得上，内容是否过大。这里最常见的问题是把工具结果返回放在了错误的对话顺序里，或者忘了带tool_call_id。

做完这三段判断，问题的层级基本就清楚了。我遇到的大部分"调用工具失败"，最后都落在前两段，也就是模型生成阶段，这说明修复重心应该放在工具定义和提示词上。

3. 动手修复：工具定义和强制调用的正确写法

这一章进入核心修复环节。我会拿一个实际例子展开，说明JSON Schema怎么改、tool_choice怎么设置、以及工具结果怎么正确回传。不管你是用OpenAI SDK还是兼容接口，这套思路都适用。

3.1 JSON Schema是给模型看的说明书

很多开发者写工具定义的时候，把大部分精力花在数据结构上，却忽略了description字段的重要性。在新版模型上，description一句话的差别，会让工具调用成功率有明显变化。

以天气查询工具为例。一个含糊的定义是这样的：

{ "name": "get_weather", "description": "查询天气", "parameters": { "type": "object", "properties": { "city": {"type": "string"}, "date": {"type": "string"} } } }

这种定义下，模型经常纠结date应该传"明天"、"2025-01-15"还是"2025/01/15"。而我把描述改成下面这样之后，参数规范化程度立刻改善：

{ "name": "get_weather", "description": "根据城市名和日期查询实时天气信息。仅当用户明确表达查询天气意图时调用。日期格式必须为YYYY-MM-DD。", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市中文名，例如北京、上海、广州" }, "date": { "type": "string", "description": "查询日期，格式YYYY-MM-DD，不传时默认当天" } }, "required": ["city", "date"] } }

改动点主要有三个：补充了触发条件，规定了日期格式，用示例约束了枚举范围。这些看似不起眼的说明，对模型来说是重要的上下文信息。我还试过在enum里显式列出支持的城市列表，效果也不错，模型完全不会填出列表之外的城市名。

另外要注意，不要在Schema里塞太多可选字段。字段一多，模型容易犹豫，反而影响生成稳定性。能合并的字段尽量合并，能让模型少一个选择就少一个选择。

3.2 tool_choice的差异：为什么模型就是不听你的

如果你已经在描述里写清楚触发条件，模型依然在必须调工具的时候选择了纯文本回复，那就轮到tool_choice上场了。

在新版模型的工具调用参数里，tool_choice通常支持三种设置：

• "auto"：模型自行判断是否需要调用工具
• "none"：禁止调用任何工具
• "required"：强制模型必须调用一个工具

实操中发现，在"必查天气"这类场景下，将tool_choice设为"required"能显著降低策略放弃型失败。不过要小心，强制模式会让模型在无法理解用户问题时也强行调用，容易出现参数质量下降。更稳妥的做法是结合意图识别做一个简单分流，比如先用轻量规则判断用户是否真的需要查询，再决定是否设置required。

resp = client.chat.completions.create( model="gpt-5.6", messages=messages, tools=tools, tool_choice="required" # 或者 "auto" )

另外还有一些接口对tool_choice的写法不同，有的place支持传入具体某个函数名，例如{"type": "function", "function": {"name": "get_weather"}}，这种精确指定比全局required更可控。当你明确知道用户就是要用某个工具时，强烈推荐这种方式。

3.3 工具结果的回传：决定下一轮能不能顺利调用

工具调用成功之后，真正的考验才刚开始。你把工具执行结果回传给模型时，消息结构必须严格符合API要求。一次标准的多轮调用，消息顺序是这样的：

# 第一轮：用户提问，模型返回工具调用 messages = [ {"role": "user", "content": "北京明天天气怎么样？"} ] # 模型返回了 tool_calls，其中 tool_call_id 为 "call_abc123" # 第二轮：附加工具执行结果，回传给模型 messages = [ {"role": "user", "content": "北京明天天气怎么样？"}, { "role": "assistant", "tool_calls": [ { "id": "call_abc123", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\": \"北京\", \"date\": \"2025-01-15\"}" } } ], "content": None }, { "role": "tool", "tool_call_id": "call_abc123", "content": "晴，-3~8℃" } ]

这里有几个细节值得注意。第一，assistant消息里的content必须为None，如果你在这里补了一段文本，有些API会报错。第二，tool_call_id必须与模型返回的一致，不能用自己生成的随机ID。第三，如果你同时调用了多个工具，需要按顺序返回对应的多条tool消息，并用各自独立的tool_call_id。

有一个隐藏很深的坑是：工具结果内容不能太大。如果你把整个数据库查询结果的JSON原样塞进content里，下一轮模型就可能因为上下文过长而响应缓慢，甚至产生截断。后面第四章我会专门说上下文问题，这里先记住一个原则：回传给模型的永远是"加工后的摘要"，不是原始数据。

4. 三个隐藏最深的坑：多轮调用、超时预算和上下文膨胀

前几章解决的是"能不能调起来"的问题，这一章解决的是"调起来之后能不能稳定跑"的问题。很多人的工具调用在单轮测试时一切正常，一上多轮对话就开始翻车，原因基本都在这一章里。

4.1 多轮调用中的幽灵参数

所谓幽灵参数，是指上一轮工具调用的参数被模型错误地沿用到了后一轮。举个例子，用户先问"北京的天气"，过一会儿又问"那上海呢"，模型却仍然把city填成北京。

这个问题的根因不完全在模型本身，更多在于你没有把工具结果和上下文语义同步更新。市面上很多Agent框架处理多轮对话时，只是简单地把历史消息一股脑塞回去，模型无法判断"当前意图"和"历史参数"之间的覆盖关系。

我的建议是，在把历史消息送入模型之前，先做一轮上下文裁剪。把已经过期的工具调用对（assistant请求和tool结果）压缩成一句话摘要，比如把北京天气：晴，-3~8℃写成一个短句，保留语义，去掉冗长的工具调用结构。这样既节省token，又大幅减少模型沿用旧参数的概率。

如果你用的是带线程管理的接口，也要注意线程中的历史消息是否因为过长而触发了自动截断，截断策略不对同样会造成参数混乱。

4.2 超时预算：一次调用要拆成两段计时

很多人给工具调用只设了一个总超时，比如30秒。但一次完整的工具调用其实包含两段耗时：第一段是模型生成tool_calls的时间，第二段是你的业务代码实际执行工具的时间。这两段的时间特性完全不同，应该分别设置超时时间。

模型生成阶段通常需要更长的预算，尤其在工具多、描述复杂的情况下，模型可能要经过内部多步推理。实测中，工具数量超过5个时，模型生成阶段耗时比2个工具时高出50%到一倍。我建议模型生成阶段预留30到60秒，工具执行阶段单独设置超时，比如大多数外部API控制在10秒以内。

还有一个小技巧是配合流式输出。如果接口支持stream=True，你可以在流式返回中提前拿到工具调用参数，在完整返回前就判断参数格式是否正确，发现问题能提前中断重试，而不是傻等超时。

resp = client.chat.completions.create( model="gpt-5.6", messages=messages, tools=tools, stream=True # 流式输出，及时感知调用情况 )

4.3 工具返回结果太长，上下文窗口被塞满

第三个隐藏坑是上下文窗口。新版模型的窗口虽然大，但也架不住多轮工具调用不断堆叠。比如一轮查询返回了2000字的JSON，五轮之后光工具返回结果就占了一万多token，模型处理速度明显变慢，甚至开始"遗忘"最早对话中的关键指令。

处理办法是制定工具结果的摘要策略。具体来说，在把工具结果回传给模型前，先用一个裁剪函数把内容压到几十到几百字。比如天气查询结果可以压缩成"晴，-3~8℃，北风3级"，不需要把原始JSON的每个字段都保留。如果业务上确实需要完整数据，那就把完整数据放在应用层缓存里，只把摘要和必要的引用信息传给模型。

这里再提一个容易被忽视的点：如果工具返回的内容包含表格、长文本列表，建议在摘要中保留核心数字和关键词，同时给模型一个"查询入口"。比如告诉模型"完整数据已缓存，如需更多字段请调用get_detail工具"，这样模型需要细节时会主动再调工具，而不是从被塞满的上下文里胡乱猜测。

5. 让工具调用稳定下来的兜底策略与回归验证

修复完上面这些点，工具调用的成功率应该能恢复到一个可用状态。但线上环境不会让你轻轻松松躺平，偶发失败依然存在。所以最后这部分，我要说的是稳定运行层面的经验：重试策略、降级预案，以及怎么用灰度数据验证自己真的修好了。

5.1 哪些错误值得重试，哪些不值得

工具调用失败后的重试，不能无脑重试。很多团队看到失败就重发请求，结果只是把限流触发得更严重了。正确的做法是先分清楚错误类型和重试的关系。

指数退避的间隔我通常用1秒、3秒、9秒这个倍数关系，最多重试两到三次。每次重试可以给tools参数加一点扰动，比如调整系统提示词中的口头禅，虽然听起来有点偏门，但实测中确实能降低模型重复犯同一个格式错误的概率。

另外，重试时应重新生成一个请求ID，方便日志追踪。不要复用上一次的上下文和tool_call_id，否则可能带着错误状态再跑一轮。

5.2 失败降级预案：不能让流程卡死

工具调用失败最怕的不是失败本身，而是失败后整个流程卡死。用户等了几十秒，最后只看到一句"服务开小差了"，这种体验是不可接受的。我建议在任何依赖工具调用的流程后面都挂一个降级预案。

降级预案分三层：第一层是重新询问，当模型没有调用工具时，可以让对话引导用户换个说法再试一次；第二层是规则兜底，比如天气查询直接用固定参数拼一个请求地址，绕过模型直接拿到结果；第三层是人工兜底，把失败的上下文记录下来，转入工单或人工客服系统。

这三层不必每层都做得很重，但至少要有一层。我最常用的是规则兜底，因为对一个确定性的工具来说，规则脚本完全可以在模型失败时接管核心流程。这样既保证服务不中断，也给模型留出了修复缓冲时间。

5.3 灰度切换与回归验证：拿数据说话

修复过程需要数据验证，尤其在多个模型版本并存的情况下，不能凭感觉说"好像修好了"。我自己的做法是跑一个为期几天的灰度回归，比较新旧版本在相同场景下的工具调用成功率。

需要盯的核心指标有三项：工具调用触发率、工具参数合法率、完整链路成功率。触发率看模型到底调没调；合法率看调出来的参数能不能通过Schema校验；完整链路成功率看从用户提问到工具结果落地的整体完成情况。三者组合起来，能精准反映问题出在哪个环节。

我习惯用一张表格记录灰度数据，每天滚动更新：

只有当三项指标连续三天保持在一个可接受区间，我才会把修复策略推广到全量流量。Cooking之外，还要记录每次失败的请求样本，比如哪类问题占比最高、哪类错误分布在哪段时间，这些数据在下一次模型升级时会是非常宝贵的参照。

最后再分享一个小技巧。排查工具调用问题时，我会在每个工具函数入口和出口各打一条日志，加上统一的trace_id。这个字段会和模型请求ID一一对应，一旦用户侧或业务侧反馈失败，我可以从头到尾拉出整条链路。相比在失败后盲目调参，这个习惯帮我省掉了大量重复排查时间。