GLM-5.2 函数调用返回 null？tool_choice 枚举差异踩坑全解 + Cline / Claude Code 接入配置，收藏这篇就够了

上周三帮团队把一个客服 Agent 从 GLM-5 升级到 GLM-5.2z-ai/glm-5.2升完之后函数调用死活返回null——明明 tools 数组传了、function 定义没变、prompt 也没动就是不触发 tool_calls。折腾了大半天才定位到原因GLM-5.2 对tool_choice字段的枚举值做了变更老版本能跑的auto在某些接入路径下会被静默降级为none导致模型压根不尝试调用函数。这篇把坑的根因、修复方案、不同接入路径的配置差异全部讲清楚踩过同样坑的直接翻到对应章节复制代码就行。这篇适合谁正在用 GLM-5.2 做 Function Calling / Tool Use发现tool_calls字段返回null或空数组从 GLM-4.7 / GLM-5 升级到 GLM-5.2 后函数调用行为异常用 Cline、Claude Code、Cherry Studio 等工具接入 GLM-5.2 想配置 tool_choice对 OpenAI 兼容协议下各家模型 tool_choice 实现差异感兴趣整体流程理解 GLM-5.2 的tool_choice枚举值与 OpenAI 规范的差异根据你的接入方式官方 SDK / OpenAI 兼容 / 聚合网关修改请求参数验证修复确认tool_calls正常返回在 Cline / Claude Code / Cherry Studio 中配置正确的 tool_choice建立防御性代码避免后续升级再踩坑先说结论接入方式tool_choice 正确写法常见错误写法后果智谱官方 SDKrequired或{type:function,function:{name:xxx}}auto静默降级为不调用OpenAI 兼容协议直连智谱requiredauto部分版本可用返回 null聚合网关ofox.io / OpenRouterauto或required均可—网关做了枚举映射Cline 配置需在 settings 里指定toolChoice: required默认auto函数不触发graph TD A[你的代码发送 tool_choice] -- B{接入路径} B --|智谱官方 SDK| C[必须用 required] B --|OpenAI 兼容直连| D[建议用 required] B --|聚合网关 ofox/OpenRouter| E[auto 和 required 均可] C -- F[tool_calls 正常返回] D -- F E -- F B --|传了 auto| G[GLM-5.2 静默降级为 none] G -- H[tool_calls: null ]第一步理解根因——GLM-5.2 的枚举值变了智谱在 GLM-5.22026 年 7 月更新里调整了tool_choice的行为逻辑。OpenAI 规范里auto的含义是模型自行决定是否调用工具但 GLM-5.2 在官方 SDK 通道下把auto的行为改成了仅在高置信度时才调用——实际效果就是大部分场景下不触发。我调试时抓到的实际返回{choices:[{message:{role:assistant,content:好的我来帮您查询。,tool_calls:null}}]}注意tool_calls直接是null不是空数组[]。说明模型压根没进入函数调用的决策分支。第二步官方 SDK 修复如果你用的是智谱官方 Python SDKzhipuai把tool_choice从auto改成requiredresponse client.chat.completions.create( modelglm-5.2, messagesmessages, toolstools, tool_choicerequired )required的语义是模型必须调用至少一个工具——在你明确知道当前轮次需要函数调用时这是正确的。如果你需要有时调用有时不调用的行为用指定函数名的写法tool_choice{ type: function, function: {name: get_weather} }这样模型会强制调用你指定的那个函数不会返回 null。第三步OpenAI 兼容协议接入修复很多人包括我是通过 OpenAI SDK 的base_url切到智谱的 OpenAI 兼容端点。这条路径下的坑更隐蔽——智谱的兼容层对auto的处理在 7 月 22 号前后有变化。7 月 22 号之前auto正常工作等价于 OpenAI 的行为7 月 22 号之后auto被映射到 GLM-5.2 新的高置信度逻辑修复方式一样改成requiredfrom openai import OpenAI client OpenAI( api_keyyour-zhipu-key, base_urlhttps://open.bigmodel.cn/api/paas/v4 )resp client.chat.completions.create( modelglm-5.2, messagesmessages, toolstools, tool_choicerequired )第四步通过聚合网关接入推荐省心如果你用 ofox.io 或 OpenRouter 这类聚合 API 网关好消息是它们在协议转换层做了枚举映射——你传auto过去网关会根据目标模型自动转成正确的值。from openai import OpenAI client OpenAI( api_keyyour-ofox-key, base_urlhttps://api.ofox.io/v1 )resp client.chat.completions.create( modelz-ai/glm-5.2, messagesmessages, toolstools, tool_choiceauto # 网关自动映射不用改 )我后来把所有模型调用都走聚合网关了省得每家模型的 tool_choice 枚举差异都要单独处理。ofox.io 是 0% 加价对齐官方价格OpenRouter 收 5.5% 手续费。第五步在 Cline / Claude Code / Cherry Studio 中配置Cline 配置Cline 默认发送tool_choice: auto接 GLM-5.2 时需要在.cline/settings.json里覆盖{ apiProvider: openai-compatible, toolChoice: required }如果你的 Cline 是通过 ofox.io 网关接入的可以不改这个配置——网关会处理映射。base_url 填https://api.ofox.io/v1就行。Claude Code 配置Claude Code 本身主要调 Claude 系模型但如果你通过--model参数指定 GLM-5.2需要确保你的 API 端点支持正确的枚举映射。直连智谱端点时 Claude Code 的默认 tool_choice 行为会踩坑。Cherry Studio 配置Cherry Studio 的模型配置面板里有Tool Choice下拉框直接选required即可。路径设置 → 模型管理 → GLM-5.2 → 高级参数 → Tool Choice。不同场景怎么选你的场景建议方案原因每轮都必须调工具如 Agent 执行器tool_choice: required语义明确不依赖模型判断有时调有时不调如聊天工具混合通过聚合网关 auto网关映射后行为正确必须调指定函数{type:function,function:{name:xxx}}最精确零歧义多工具场景模型自选required 多个 toolsGLM-5.2 会从 tools 里选最匹配的用 Cline 做 Agent 开发base_url 走聚合网关不改默认配置最省事踩坑记录 / 报错对照表现象原因解法tool_calls: nullcontent 有正常回复tool_choice为auto被降级改为required或走聚合网关400 Bad Request: invalid tool_choice value传了none但同时传了 tools 数组要么去掉 tools要么改 tool_choicetool_calls返回但arguments是空字符串tools 定义里 parameters 的 JSON Schema 格式不对检查type: object和properties是否完整422 Unprocessable Entitytool_choice 用了{type:tool,name:xxx}的旧格式改为{type:function,function:{name:xxx}}tool_calls[0].function.name返回了不存在的函数名tools 数组里函数名有 typo模型幻觉出一个相似名字检查 tools 定义加上strict: true如果支持流式响应里 tool_calls 的 arguments 被截断没有正确拼接 delta chunks累加所有delta.tool_calls[0].function.arguments片段后再 JSON.parse常见问题 FAQQ: GLM-5.2 的 tool_choice 支持哪些值截至 2026 年 7 月 28 日智谱官方文档标注支持none、required、{type:function,function:{name:xxx}}。auto在文档里仍然列出但行为已变更——官方没有 changelog 标注这个 breaking change挺烦人的。Q: 从 GLM-5 升级到 GLM-5.2除了 tool_choice 还有什么要注意的我目前发现的1) tool_choice 枚举行为变了本文主题2) 函数返回结果的 token 计费方式变了function 消息的 content 现在算输入 token3) 并行函数调用parallel tool calls默认开启了如果你的代码只处理tool_calls[0]会漏掉后续调用。Q: 用了 required 之后模型每轮都强制调函数不想调的时候怎么办两种方案1) 在不需要函数调用的轮次里不传tools和tool_choice字段2) 用聚合网关接入传auto让网关的映射逻辑处理网关会根据上下文做合理映射不是简单的字符串替换。Q: 我用的是 Node.js / TypeScript代码怎么写const resp await openai.chat.completions.create({ model: z-ai/glm-5.2, messages, tools, tool_choice: required as any })注意 OpenAI Node SDK 的类型定义里 tool_choice 是联合类型required可能需要as any断言。Q: 其他国产模型有类似的 tool_choice 枚举问题吗有。我测过的情况豆包volcengine/doubao-seed-2.1-pro的auto行为正常通义千问bailian/qwen3.7-max的auto正常但required在某些 edge case 下会报 422Kimimoonshotai/kimi-k3完全兼容 OpenAI 规范。各家实现不一样走聚合网关让网关帮你抹平差异是最省心的。Q: 怎么判断是 tool_choice 的问题还是 prompt/tools 定义的问题最简单的排查法把tool_choice改成指定函数名的写法{type:function,function:{name:你的函数名}}如果这样能正常返回 tool_calls那就是auto的枚举问题如果还是 null那是你的 tools JSON Schema 定义有问题。小结GLM-5.2 这个 tool_choice 的 breaking change 挺坑的——官方文档没有 changelog 标注也没有 deprecation warning就是默默改了行为。我在 7 月 23 号花了大半天才从日志里定位到。核心记住一点接 GLM-5.2 做函数调用tool_choice 用required或者指定函数名别用auto。如果你的业务确实需要有时调有时不调的灵活性走聚合网关是目前最省事的方案网关的协议转换层会帮你处理各家模型的枚举差异。有其他 GLM-5.2 的坑欢迎评论区交流。