1. 从一次工具调用全线报错说起如果你最近在折腾 Codex 这类命令行 AI 编程助手并且把模型切到了 gpt5.6 或者 6 系列大概率遇到过下面这种让人抓狂的场景对话能正常进行模型也能流畅地跟你聊天但只要它一尝试调用工具——读文件、写文件、执行命令、搜索代码——就直接卡死或者返回一段莫名其妙的错误。更气人的是换成别的模型一切正常唯独 gpt5.6、6 这两个版本一调工具就翻车。我前后在三个不同的环境里复现过这个问题Windows 桌面版、Linux 服务器、还有一台国产麒麟系统的机器。表现略有差异但根因高度一致。这篇就把我完整的排查链路、修复方法、以及几个容易踩的坑一次性讲清楚。核心关键词包括gpt5.6、codex、models-custom.json、ccswitch、use_responses_lite如果你正在用 ccswitch 做本地代理来接入 Codex那这篇基本就是为你写的。先说结论省得你着急绝大多数 gpt5.6/6 调用工具失败不是模型本身的问题而是请求协议和工具调用格式没对齐。Codex 走的是 responses 风格的接口而很多中转层默认按 chat completions 的老格式转发工具调用的字段结构对不上模型返回的 tool call 解析不了于是就调用失败。修复的核心就两件事把use_responses_lite这个开关配对以及把models-custom.json里的模型能力声明写对。下面我按问题现象 → 根因定位 → 具体修复 → 验证 → 避坑的顺序展开每一步都给你可复制的配置和命令。2. gpt5.6/6 工具调用失败的典型症状与误判2.1 三种最常见的报错表现在动手修之前先确认你遇到的是不是同一类问题。我整理了自己和群里朋友反馈最多的三种症状症状 A对话正常工具静默失败。模型回复里明明说我来读取这个文件但界面上没有任何工具执行记录或者执行记录一闪而过显示失败然后模型继续用一段编造的内容往下答。这种最坑因为它不报错你以为它在工作其实它在瞎编。症状 B直接抛协议错误。终端里出现类似model is not supported when using codex with a...或者local proxy failed while handling codex endpoint /responses的提示。这类相对好办至少它告诉你是协议层的问题。症状 C工具调用参数为空。模型确实发起了工具调用但参数是空的或者格式错乱比如本该传{path: src/main.py}结果传成了{path: null}导致工具执行器直接拒绝。这三种症状看着不一样但往下挖基本都指向同一个地方请求在转发过程中工具调用的 schema 被改写了。2.2 为什么大家第一反应都修错了方向我见过太多人一遇到这个问题就去折腾模型版本、换 API key、甚至重装 Codex。这些操作偶尔看起来有效其实是因为重装过程中顺带更新了配置文件把某个字段重置了属于误打误撞。真正的误判点在于大家默认对话能用就说明链路是通的。但对话和工具调用走的是两条不同的数据通路。对话只需要文本进出工具调用需要额外的结构化字段tools 定义、tool_choice、以及返回的 tool_calls 数组。中转层如果只做了文本透传没做工具字段的映射就会出现聊天丝滑、工具全废的诡异现象。提示判断是不是协议层问题有个一秒钟的方法——把模型换成 gpt5.5 或更早的版本如果工具调用立刻恢复正常那基本可以锁定是 gpt5.6/6 的新工具调用格式没被中转层正确识别。2.3 先做一次最小化复现在改任何配置之前建议先做一次干净的复现避免把环境问题和新版本问题混在一起。我的做法是新建一个空目录放一个测试文件hello.txt内容随便写一行。启动 Codex只发一条指令读取 hello.txt 的内容并告诉我。观察是否有工具执行记录以及终端有没有协议报错。如果这一步就失败那问题很纯粹直接进下一章。如果这一步成功但复杂任务失败那可能是工具数量或参数复杂度触发了 schema 问题后面会单独讲。3. 根因拆解responses 协议与工具调用格式的错位3.1 Codex 走的是 responses 而不是 chat completions这是整个问题的地基必须讲透。早期的 AI 编程工具大多基于 chat completions 接口请求体长这样一个messages数组里面区分 system、user、assistant 角色工具调用通过tools字段声明模型返回tool_calls。这套格式大家都很熟。但 Codex 这类新一代工具为了支持更复杂的多轮工具编排、流式工具结果回传转向了responses 风格的接口。它的请求结构不一样不再是简单的 messages 数组而是有input、instructions、以及专门的工具结果回传通道。工具调用的生命周期被拆得更细一次工具执行可能对应多个事件。问题就出在这很多本地代理和中转层包括 ccswitch 的某些默认配置仍然按 chat completions 的逻辑去解析和转发。它看到 responses 格式的请求不知道该怎么映射工具字段于是要么丢弃工具定义要么把工具调用结果塞进错误的位置。gpt5.6/6 恰好对工具调用的格式要求更严格老版本模型可能容忍了这种错位新版本直接拒绝。3.2 use_responses_lite 到底控制什么use_responses_lite这个开关是 ccswitch 这类工具里用来控制用哪种 responses 兼容模式的关键参数。名字里的 lite 不是简化版功能的意思而是指轻量级的 responses 协议适配层。它的作用可以这样理解完整的 responses 协议实现起来很重需要处理大量事件类型和状态机。而 lite 模式只实现工具调用最核心的那部分映射——把 responses 格式的工具请求翻译成后端模型能懂的格式再把模型的工具返回翻译回 responses 事件。对于 gpt5.6/6 这种工具调用频繁的场景必须开启 lite 模式否则中转层会退回默认的 chat completions 透传工具字段直接丢失。我实测下来use_responses_lite关闭时gpt5.6 的工具调用成功率几乎是 0开启后稳定在正常水平。这个开关就是本篇修复的第一把钥匙。3.3 models-custom.json 里的能力声明为什么关键第二个关键点是models-custom.json。这个文件用来告诉 Codex我通过中转接入的这些模型各自支持什么能力。很多人从别处抄了一份配置模型名字改成了 gpt5.6但能力字段还是老的比如没声明tool_calls支持、或者context_window写小了。Codex 在发起工具调用前会读这个文件判断这个模型能不能调工具。如果声明里没有工具能力它可能压根不发工具请求或者发了但用降级格式。gpt5.6/6 的工具调用对声明字段尤其敏感因为它们的工具 schema 更复杂。一个常见的错误配置是这样的{ models: [ { name: gpt-5.6, provider: custom, supports_tools: false } ] }supports_tools写成 false工具调用自然全废。正确写法后面会给完整示例。4. 修复实操从配置到验证的完整链路4.1 第一步确认并开启 use_responses_lite先找到你的 ccswitch 配置文件。不同安装方式位置不一样常见的有Windows 桌面版一般在用户目录下的.ccswitch/config.json或安装目录的config文件夹。Linux/麒麟系统通常在~/.config/ccswitch/config.json。通过命令行安装的可以用ccswitch config path之类的命令直接打印配置路径。打开配置后找到 responses 相关的段落确保use_responses_lite为true{ responses: { use_responses_lite: true, endpoint: /responses } }如果这个字段不存在手动加上。改完保存重启 ccswitch 服务。这一步做完先别急着测复杂任务用第 2.3 节的最小化复现跑一遍看工具调用是否恢复。注意有些版本的 ccswitch 把这个开关放在experimental或compat节点下字段名可能略有差异。如果找不到用grep -r responses_lite ~/.config/ccswitch/全局搜一下别凭记忆瞎改。4.2 第二步重写 models-custom.json 的模型声明这是修复的重头戏。下面是我实测可用的 gpt5.6/6 配置模板字段含义我逐条注释{ models: [ { name: gpt-5.6, display_name: GPT 5.6, provider: custom, supports_tools: true, supports_streaming: true, supports_vision: false, context_window: 200000, max_output_tokens: 16384, tool_call_format: responses, api_style: responses }, { name: gpt-6, display_name: GPT 6, provider: custom, supports_tools: true, supports_streaming: true, supports_vision: false, context_window: 200000, max_output_tokens: 16384, tool_call_format: responses, api_style: responses } ] }几个字段必须重点说supports_tools必须是true这是工具调用的总开关。tool_call_format和api_style都设成responses和上一步的 lite 模式呼应。如果这里写成chat_completions中转层会按老格式处理工具调用照样失败。context_window别写太小。gpt5.6/6 的工具定义本身就很占 token如果窗口设成 8k光工具 schema 就塞满了模型没空间思考工具调用会变得极不稳定。我建议至少 128k稳妥起见写 200k。max_output_tokens也别太小工具调用的参数可能很长输出被截断会导致参数不完整。4.3 第三步检查工具定义有没有被中转层改写配置改完还失败的话就要看请求实际发出去长什么样了。ccswitch 一般有日志功能开启 debug 日志ccswitch --log-level debug或者在配置里加{ logging: { level: debug, log_tool_calls: true } }然后复现一次工具调用去日志里找/responses相关的请求体。重点看两处一是tools数组是否完整传出去了二是模型返回的 tool call 事件有没有被正确解析。如果日志里tools是空的说明工具定义在某一层被吞了通常是supports_tools没生效或者中转层有额外的过滤规则。我遇到过一次日志显示工具定义传出去了但返回的事件类型是chat.completion.chunk而不是 responses 的事件类型。这就是典型的请求走了 responses返回按 chat 解析根因还是 lite 模式没开全。把use_responses_lite和api_style两处都对齐后解决。4.4 第四步分场景验证修复效果修完不能只测一个场景就完事。我一般按下面这张表逐项验证确保工具调用的各个维度都正常验证场景操作预期结果单文件读取让模型读一个文件有工具执行记录内容正确多文件批量读让模型读三个文件并汇总三次工具调用都成功写文件让模型创建新文件文件真实生成内容正确执行命令让模型跑一条简单命令命令执行输出回传连续工具链读文件→改文件→再读多轮工具调用不中断长上下文工具大文件读取后继续调工具不因 token 超限失败这六项全过基本可以确认修复到位。如果某一项失败回到对应章节排查单文件失败看协议多文件失败看并发或 schema连续工具链失败看状态机。5. 那些让我多花了两小时的坑5.1 配置文件改了但没生效这是最高频的坑。ccswitch 有些版本会缓存配置改完文件不重启服务读的还是旧配置。更隐蔽的是某些安装方式存在两份配置——一份在安装目录一份在用户目录你改了 A程序读的是 B。我的排查习惯是改完配置后用ccswitch config show或类似命令打印当前生效的配置确认改动真的被加载了。如果没有这个命令就去看启动日志里打印的配置路径顺着路径找。5.2 模型名字大小写和连字符不一致gpt-5.6和gpt5.6、GPT-5.6在中转层眼里可能是三个不同的模型。models-custom.json里声明的name必须和你在 Codex 里选择的模型名、以及中转层路由的模型名完全一致。我踩过一次配置里写gpt-5.6Codex 里选的是gpt5.6结果路由不到工具调用直接失败但对话因为走了默认模型所以正常排查了半天。5.3 工具数量过多触发 schema 超限gpt5.6/6 对工具 schema 的总大小有隐性限制。如果你挂了几十个工具每个工具的参数描述又写得很长schema 可能超出模型能接受的范围表现就是工具调用随机失败。解决办法是精简工具描述或者按需动态加载工具别一次性全塞进去。5.4 麒麟系统上的额外注意点在国产麒麟系统上装 ccswitch有两个额外坑。一是依赖库版本某些系统自带的库版本偏老ccswitch 启动时可能报链接错误需要手动补依赖。二是文件权限麒麟系统对用户目录权限管得严配置文件如果权限不对程序读不到表现就是配置明明写了却不生效。用ls -l检查配置文件权限确保当前用户可读。6. 修复之后还能做的几件事工具调用修好只是第一步。如果你想让 gpt5.6/6 在 Codex 里跑得更顺还有几个可以顺手做的优化。第一给工具调用加超时和重试。工具执行偶尔会因为网络或文件锁失败配置里加个重试次数能显著提升连续工具链的成功率。第二把常用工具的描述写得更精确模型选工具的准确率会明显上升尤其是读文件和搜索这类容易混淆的工具。第三定期检查models-custom.json模型能力更新后及时同步别让过时的声明拖后腿。我个人在实际操作中的体会是gpt5.6/6 的工具调用问题九成以上都能靠对齐协议 写对声明解决剩下的一成多半是环境或权限问题。与其反复重装不如静下心把use_responses_lite和models-custom.json这两处吃透后面再遇到类似问题基本能自己定位。最后分享一个小技巧把每次成功的配置存一份带日期的备份下次环境出问题直接对比配置差异比从头排查快得多。
1. 从一次工具调用全线报错说起如果你最近在折腾 Codex 这类命令行 AI 编程助手并且把模型切到了 gpt5.6 或者 6 系列大概率遇到过下面这种让人抓狂的场景对话能正常进行模型也能流畅地跟你聊天但只要它一尝试调用工具——读文件、写文件、执行命令、搜索代码——就直接卡死或者返回一段莫名其妙的错误。更气人的是换成别的模型一切正常唯独 gpt5.6、6 这两个版本一调工具就翻车。我前后在三个不同的环境里复现过这个问题Windows 桌面版、Linux 服务器、还有一台国产麒麟系统的机器。表现略有差异但根因高度一致。这篇就把我完整的排查链路、修复方法、以及几个容易踩的坑一次性讲清楚。核心关键词包括gpt5.6、codex、models-custom.json、ccswitch、use_responses_lite如果你正在用 ccswitch 做本地代理来接入 Codex那这篇基本就是为你写的。先说结论省得你着急绝大多数 gpt5.6/6 调用工具失败不是模型本身的问题而是请求协议和工具调用格式没对齐。Codex 走的是 responses 风格的接口而很多中转层默认按 chat completions 的老格式转发工具调用的字段结构对不上模型返回的 tool call 解析不了于是就调用失败。修复的核心就两件事把use_responses_lite这个开关配对以及把models-custom.json里的模型能力声明写对。下面我按问题现象 → 根因定位 → 具体修复 → 验证 → 避坑的顺序展开每一步都给你可复制的配置和命令。2. gpt5.6/6 工具调用失败的典型症状与误判2.1 三种最常见的报错表现在动手修之前先确认你遇到的是不是同一类问题。我整理了自己和群里朋友反馈最多的三种症状症状 A对话正常工具静默失败。模型回复里明明说我来读取这个文件但界面上没有任何工具执行记录或者执行记录一闪而过显示失败然后模型继续用一段编造的内容往下答。这种最坑因为它不报错你以为它在工作其实它在瞎编。症状 B直接抛协议错误。终端里出现类似model is not supported when using codex with a...或者local proxy failed while handling codex endpoint /responses的提示。这类相对好办至少它告诉你是协议层的问题。症状 C工具调用参数为空。模型确实发起了工具调用但参数是空的或者格式错乱比如本该传{path: src/main.py}结果传成了{path: null}导致工具执行器直接拒绝。这三种症状看着不一样但往下挖基本都指向同一个地方请求在转发过程中工具调用的 schema 被改写了。2.2 为什么大家第一反应都修错了方向我见过太多人一遇到这个问题就去折腾模型版本、换 API key、甚至重装 Codex。这些操作偶尔看起来有效其实是因为重装过程中顺带更新了配置文件把某个字段重置了属于误打误撞。真正的误判点在于大家默认对话能用就说明链路是通的。但对话和工具调用走的是两条不同的数据通路。对话只需要文本进出工具调用需要额外的结构化字段tools 定义、tool_choice、以及返回的 tool_calls 数组。中转层如果只做了文本透传没做工具字段的映射就会出现聊天丝滑、工具全废的诡异现象。提示判断是不是协议层问题有个一秒钟的方法——把模型换成 gpt5.5 或更早的版本如果工具调用立刻恢复正常那基本可以锁定是 gpt5.6/6 的新工具调用格式没被中转层正确识别。2.3 先做一次最小化复现在改任何配置之前建议先做一次干净的复现避免把环境问题和新版本问题混在一起。我的做法是新建一个空目录放一个测试文件hello.txt内容随便写一行。启动 Codex只发一条指令读取 hello.txt 的内容并告诉我。观察是否有工具执行记录以及终端有没有协议报错。如果这一步就失败那问题很纯粹直接进下一章。如果这一步成功但复杂任务失败那可能是工具数量或参数复杂度触发了 schema 问题后面会单独讲。3. 根因拆解responses 协议与工具调用格式的错位3.1 Codex 走的是 responses 而不是 chat completions这是整个问题的地基必须讲透。早期的 AI 编程工具大多基于 chat completions 接口请求体长这样一个messages数组里面区分 system、user、assistant 角色工具调用通过tools字段声明模型返回tool_calls。这套格式大家都很熟。但 Codex 这类新一代工具为了支持更复杂的多轮工具编排、流式工具结果回传转向了responses 风格的接口。它的请求结构不一样不再是简单的 messages 数组而是有input、instructions、以及专门的工具结果回传通道。工具调用的生命周期被拆得更细一次工具执行可能对应多个事件。问题就出在这很多本地代理和中转层包括 ccswitch 的某些默认配置仍然按 chat completions 的逻辑去解析和转发。它看到 responses 格式的请求不知道该怎么映射工具字段于是要么丢弃工具定义要么把工具调用结果塞进错误的位置。gpt5.6/6 恰好对工具调用的格式要求更严格老版本模型可能容忍了这种错位新版本直接拒绝。3.2 use_responses_lite 到底控制什么use_responses_lite这个开关是 ccswitch 这类工具里用来控制用哪种 responses 兼容模式的关键参数。名字里的 lite 不是简化版功能的意思而是指轻量级的 responses 协议适配层。它的作用可以这样理解完整的 responses 协议实现起来很重需要处理大量事件类型和状态机。而 lite 模式只实现工具调用最核心的那部分映射——把 responses 格式的工具请求翻译成后端模型能懂的格式再把模型的工具返回翻译回 responses 事件。对于 gpt5.6/6 这种工具调用频繁的场景必须开启 lite 模式否则中转层会退回默认的 chat completions 透传工具字段直接丢失。我实测下来use_responses_lite关闭时gpt5.6 的工具调用成功率几乎是 0开启后稳定在正常水平。这个开关就是本篇修复的第一把钥匙。3.3 models-custom.json 里的能力声明为什么关键第二个关键点是models-custom.json。这个文件用来告诉 Codex我通过中转接入的这些模型各自支持什么能力。很多人从别处抄了一份配置模型名字改成了 gpt5.6但能力字段还是老的比如没声明tool_calls支持、或者context_window写小了。Codex 在发起工具调用前会读这个文件判断这个模型能不能调工具。如果声明里没有工具能力它可能压根不发工具请求或者发了但用降级格式。gpt5.6/6 的工具调用对声明字段尤其敏感因为它们的工具 schema 更复杂。一个常见的错误配置是这样的{ models: [ { name: gpt-5.6, provider: custom, supports_tools: false } ] }supports_tools写成 false工具调用自然全废。正确写法后面会给完整示例。4. 修复实操从配置到验证的完整链路4.1 第一步确认并开启 use_responses_lite先找到你的 ccswitch 配置文件。不同安装方式位置不一样常见的有Windows 桌面版一般在用户目录下的.ccswitch/config.json或安装目录的config文件夹。Linux/麒麟系统通常在~/.config/ccswitch/config.json。通过命令行安装的可以用ccswitch config path之类的命令直接打印配置路径。打开配置后找到 responses 相关的段落确保use_responses_lite为true{ responses: { use_responses_lite: true, endpoint: /responses } }如果这个字段不存在手动加上。改完保存重启 ccswitch 服务。这一步做完先别急着测复杂任务用第 2.3 节的最小化复现跑一遍看工具调用是否恢复。注意有些版本的 ccswitch 把这个开关放在experimental或compat节点下字段名可能略有差异。如果找不到用grep -r responses_lite ~/.config/ccswitch/全局搜一下别凭记忆瞎改。4.2 第二步重写 models-custom.json 的模型声明这是修复的重头戏。下面是我实测可用的 gpt5.6/6 配置模板字段含义我逐条注释{ models: [ { name: gpt-5.6, display_name: GPT 5.6, provider: custom, supports_tools: true, supports_streaming: true, supports_vision: false, context_window: 200000, max_output_tokens: 16384, tool_call_format: responses, api_style: responses }, { name: gpt-6, display_name: GPT 6, provider: custom, supports_tools: true, supports_streaming: true, supports_vision: false, context_window: 200000, max_output_tokens: 16384, tool_call_format: responses, api_style: responses } ] }几个字段必须重点说supports_tools必须是true这是工具调用的总开关。tool_call_format和api_style都设成responses和上一步的 lite 模式呼应。如果这里写成chat_completions中转层会按老格式处理工具调用照样失败。context_window别写太小。gpt5.6/6 的工具定义本身就很占 token如果窗口设成 8k光工具 schema 就塞满了模型没空间思考工具调用会变得极不稳定。我建议至少 128k稳妥起见写 200k。max_output_tokens也别太小工具调用的参数可能很长输出被截断会导致参数不完整。4.3 第三步检查工具定义有没有被中转层改写配置改完还失败的话就要看请求实际发出去长什么样了。ccswitch 一般有日志功能开启 debug 日志ccswitch --log-level debug或者在配置里加{ logging: { level: debug, log_tool_calls: true } }然后复现一次工具调用去日志里找/responses相关的请求体。重点看两处一是tools数组是否完整传出去了二是模型返回的 tool call 事件有没有被正确解析。如果日志里tools是空的说明工具定义在某一层被吞了通常是supports_tools没生效或者中转层有额外的过滤规则。我遇到过一次日志显示工具定义传出去了但返回的事件类型是chat.completion.chunk而不是 responses 的事件类型。这就是典型的请求走了 responses返回按 chat 解析根因还是 lite 模式没开全。把use_responses_lite和api_style两处都对齐后解决。4.4 第四步分场景验证修复效果修完不能只测一个场景就完事。我一般按下面这张表逐项验证确保工具调用的各个维度都正常验证场景操作预期结果单文件读取让模型读一个文件有工具执行记录内容正确多文件批量读让模型读三个文件并汇总三次工具调用都成功写文件让模型创建新文件文件真实生成内容正确执行命令让模型跑一条简单命令命令执行输出回传连续工具链读文件→改文件→再读多轮工具调用不中断长上下文工具大文件读取后继续调工具不因 token 超限失败这六项全过基本可以确认修复到位。如果某一项失败回到对应章节排查单文件失败看协议多文件失败看并发或 schema连续工具链失败看状态机。5. 那些让我多花了两小时的坑5.1 配置文件改了但没生效这是最高频的坑。ccswitch 有些版本会缓存配置改完文件不重启服务读的还是旧配置。更隐蔽的是某些安装方式存在两份配置——一份在安装目录一份在用户目录你改了 A程序读的是 B。我的排查习惯是改完配置后用ccswitch config show或类似命令打印当前生效的配置确认改动真的被加载了。如果没有这个命令就去看启动日志里打印的配置路径顺着路径找。5.2 模型名字大小写和连字符不一致gpt-5.6和gpt5.6、GPT-5.6在中转层眼里可能是三个不同的模型。models-custom.json里声明的name必须和你在 Codex 里选择的模型名、以及中转层路由的模型名完全一致。我踩过一次配置里写gpt-5.6Codex 里选的是gpt5.6结果路由不到工具调用直接失败但对话因为走了默认模型所以正常排查了半天。5.3 工具数量过多触发 schema 超限gpt5.6/6 对工具 schema 的总大小有隐性限制。如果你挂了几十个工具每个工具的参数描述又写得很长schema 可能超出模型能接受的范围表现就是工具调用随机失败。解决办法是精简工具描述或者按需动态加载工具别一次性全塞进去。5.4 麒麟系统上的额外注意点在国产麒麟系统上装 ccswitch有两个额外坑。一是依赖库版本某些系统自带的库版本偏老ccswitch 启动时可能报链接错误需要手动补依赖。二是文件权限麒麟系统对用户目录权限管得严配置文件如果权限不对程序读不到表现就是配置明明写了却不生效。用ls -l检查配置文件权限确保当前用户可读。6. 修复之后还能做的几件事工具调用修好只是第一步。如果你想让 gpt5.6/6 在 Codex 里跑得更顺还有几个可以顺手做的优化。第一给工具调用加超时和重试。工具执行偶尔会因为网络或文件锁失败配置里加个重试次数能显著提升连续工具链的成功率。第二把常用工具的描述写得更精确模型选工具的准确率会明显上升尤其是读文件和搜索这类容易混淆的工具。第三定期检查models-custom.json模型能力更新后及时同步别让过时的声明拖后腿。我个人在实际操作中的体会是gpt5.6/6 的工具调用问题九成以上都能靠对齐协议 写对声明解决剩下的一成多半是环境或权限问题。与其反复重装不如静下心把use_responses_lite和models-custom.json这两处吃透后面再遇到类似问题基本能自己定位。最后分享一个小技巧把每次成功的配置存一份带日期的备份下次环境出问题直接对比配置差异比从头排查快得多。
