外观
Claude 5.x 在 OpenAI 兼容中转上返回 400:一条规则表的修法
结论先说
报错不是账号问题、不是网络问题、也不是"思考等级"开关没关。
真正的原因:桌面端内置的模型目录里,有一条对所有 OpenAI 兼容渠道生效的通用规则,把思考等级翻译成 thinking.type = "enabled";而新模型只接受 adaptive 或干脆不带 thinking。
修法是往规则表末尾追加一条优先级更高的规则,把这几个模型的映射改成 thinking.type = adaptive + output_config.effort。不用改代码、不用改密钥。
错误原文
text
status_code=400
claude-opus-5-5 requires adaptive thinking; omit thinking
or use thinking.type=adaptive and output_config.effort
(request id: 2026...)上下文:
| 项目 | 值 |
|---|---|
| 请求模型 | claude-fable-5.1(中转侧实际落到 claude-opus-5-5) |
| 端点 | /v1/chat/completions |
| 渠道类型 | openai-chat-completions |
| 同渠道可用 | claude-opus-4.6、claude-fable-5 |
同渠道旧模型正常、新模型 400,基本就把范围缩小到"请求形状"而不是"账号/额度/网络"。
工具与源码
- GitHub 仓库(图形化工具 + 命令行脚本 + 规则原文 + 单元测试):https://github.com/Dongmingyue-loss/zcode-claude-thinking-fix
- v1.0.0 Release(含 zip 包):https://github.com/Dongmingyue-loss/zcode-claude-thinking-fix/releases/tag/v1.0.0
第一步:把真实请求体拿出来
桌面端会把每次模型请求落盘(模型调用轨迹),格式是 JSONL,一条记录里带 request.body:
text
<应用数据目录>/cli/rollout/model-io-sess_<id>.jsonl从里面能直接看到出事时发出的字段:
json
{
"thinking": { "type": "enabled" },
"enable_thinking": true,
"reasoning_effort": "max",
"reasoning": { "effort": "max" }
}对照上游要求,问题就明确了:type 应该是 adaptive,而不是 enabled;effort 应该放在 output_config 里。
这一步很重要——它把"猜"变成了"读"。后面所有验证都以这份请求体为准。
第二步:排除三个常见误判
排查时先后试过、并且都无效的做法:
| 尝试 | 为什么无效 |
|---|---|
改 ZCODE_STORAGE_DIR | 它只影响 cli/exec、剪贴板等零散目录,与请求体无关 |
改桌面数据根 dataBaseDir | 只管桌面配置/任务索引,不参与模型请求 |
| 反复重启、换 key、关思考 | 请求体形状不变,400 依旧 |
真正决定字段的是模型目录里的推理等级映射,属于数据,不在设置里。
第三步:找到规则表
text
<安装目录>/resources/glm/provider/zcode-builtin.json结构大致是:
json
{
"config": {
"modelConfigRules": {
"modelApiRules": [
{ "modelMatch": ".*", "apiTypeMatch": "openai-chat-completions",
"config": { "optionSpecs": { "reasoningLevel": { "map": "..." } } } }
]
}
}
}那条 modelMatch: ".*" 的通用规则就是元凶,它的 map 把等级翻译成:
json
{
"thinking": { "type": "enabled" },
"enable_thinking": true,
"reasoning_effort": "<level>",
"reasoning": { "effort": "<level>" }
}关键机制:规则按数组顺序加载并逐层 overlay,后出现的规则会覆盖前面同名字段。所以不需要动内置规则,只要在末尾追加一条更窄的规则。
第四步:追加覆盖规则
json
{
"modelMatch": ".*(?:claude-fable-5[.\\-][1-9]|claude-opus-5(?:[.\\-]\\d)?)(?:[.\\-:/\\[].*)?",
"apiTypeMatch": "openai-chat-completions",
"config": {
"optionSpecs": {
"reasoningLevel": {
"map": "reasoningLevel == \"disabled\" ? {} : { \"thinking\": { \"type\": \"adaptive\" }, \"output_config\": { \"effort\": reasoningLevel == \"enabled\" ? \"high\" : reasoningLevel } }"
}
}
}
}三条设计取舍:
- 正则只圈新模型。
claude-fable-5(无.1)、claude-opus-4.6、gemini-*、deepseek-*都不命中,避免把能用的渠道改坏。 disabled返回{}。上游明确说"omit thinking"是合法写法,关思考时不发字段最稳。- 保留
adaptive+output_config.effort。这样思考等级还能用,不是靠"关掉功能"绕过错误。
第五步:验证
改完至少做三层验证,缺一层都可能白折腾:
text
1) 正则范围:只命中 claude-fable-5.1 / claude-opus-5,不命中 4.6 和 gemini
2) 表达式可编译:用 Node 把 map 求值三种等级,得到预期对象
3) 落盘后再解析一遍 JSON,确认文件没写坏映射结果:
| 等级 | 请求体新增字段 |
|---|---|
enabled | thinking:{type:"adaptive"}、output_config:{effort:"high"} |
low/medium/high/max | thinking:{type:"adaptive"}、output_config:{effort:"<原值>"} |
disabled | 无 |
然后重启应用(catalog 只在启动时读),再发一次请求,回到"第一步"看落盘请求体是否变化。以落盘为准,不以界面显示为准。
兜底
如果中转站不认 output_config(表现为未知字段错误),把 map 换成:
json
{}也就是彻底不带 thinking。这是上游错误信息里给出的另一条合法路径,代价是这次请求没有扩展思考。
可复现的最小操作
图形化:
bat
start-gui.cmd命令行:
bat
python fix_catalog.py status
python fix_catalog.py apply adaptive
python fix_catalog.py apply omit REM 兜底
python fix_catalog.py revert REM 回滚所有写操作都会先备份成 zcode-builtin.json.bak-<时间戳>;revert 用最近一份备份覆盖回来。应用升级可能重置这个文件,升级后重跑一次即可。
经验总结
- 先拿真实请求体,再谈原因。 有落盘记录就不用猜;没有的话优先找请求日志或抓包。
- 区分"配置"和"数据"。 环境变量、设置项、规则表三层各自管什么,改错层再多次重启也没用。
- 优先追加覆盖,不改内置。 覆盖规则可以回滚、可以按模型收窄,改内置则要和版本升级赛跑。
- 用正则收窄影响面。 同一条通用规则服务所有渠道,修复必须只对目标模型生效。
- 验证要以"发出去的字节"为准。 界面上思考开关亮着,不代表请求体里字段对。
边界
本方法针对带外部 catalog 的桌面版。单文件打包的 13 MB 版本把同样的映射编进了 bundle,没有外部 catalog,需要另行打补丁;原理相同,只是要改的是代码而不是 JSON。