【Bug已解决】Codex CLI 报错 model not found / unsupported model 解决方案

【Bug已解决】Codex CLI 报错 model not found / unsupported model 解决方案1. 问题描述在 Codex CLI 中切换模型、或者接入第三方 API 中转服务后执行任务时突然收到模型不存在的报错Error: model not found {error: {message: The model gpt-5-codex-preview does not exist or you do not have access to it., type: invalid_request_error, code: model_not_found}}有时报错信息更简洁{detail: unsupported model}1.1 具体现象按照网上某篇教程配置了一个模型名称结果直接报模型不存在之前能用的模型名称某次官方更新后突然不能用了接入第三方 API 网关时网关支持的模型名称和官方原生模型名称不完全一致账号权限等级不够某些模型比如预览版/高级版模型不在当前账号可用范围内这个问题在手动编辑配置文件切换模型、以及接入非官方原生 API 端点这两种场景下特别常见本质是你请求的模型名称和服务端实际能识别/有权限调用的模型没有对上。2. 原因分析Codex CLI 在发起请求时会把配置文件里指定的model字段原样传递给对接的 API 服务端。服务端收到请求后会校验这个模型名称是否存在、当前账号是否有权限调用任何一个环节不匹配都会返回model not found类错误。常见的不匹配原因可以归纳为原因分类具体表现模型名称拼写/大小写错误手动敲写模型名时打错字符或大小写与官方定义不一致模型已被官方下线/改名AI 模型迭代速度快旧版本教程里的模型名称可能已经废弃账号权限等级不足某些高级/预览模型仅对特定订阅等级或邀测账号开放第三方网关的模型命名规则不同中转服务商为了区分上游来源会用自定义前缀重命名模型如provider/model-name地区/合规限制部分模型在特定地区或账号类型下不可用用一张流程图梳理请求校验流程Codex 发起请求携带配置中的 model 字段 ↓ 服务端接收请求解析模型名称 ↓ 该模型名称是否存在于服务端支持列表 ├─ 存在 → 继续校验账号权限 │ ↓ │ 账号是否有权限调用该模型 │ ├─ 有权限 → 正常处理请求 │ └─ 无权限 → 403/model access 类错误 └─ 不存在 → model not found / unsupported model3. 解决方案方案一确认官方当前支持的模型名称列表最直接不要凭记忆或旧教程里的名称直接使用先确认当前账号实际可用的模型# 部分版本提供列出可用模型的子命令 codex models list如果没有该子命令直接查阅官方最新文档中列出的模型名称逐字核对配置文件里的写法。方案二检查配置文件中的模型名称拼写与大小写# ~/.codex/config.toml # 错误示例多打了一个字符或者大小写不一致 model GPT-5-Codex # 正确写法与官方文档完全一致模型名称通常全小写 model gpt-5-codex方案三确认第三方 API 网关的实际模型命名规则如果通过第三方中转服务接入非官方端点需要单独查阅该服务商提供的模型名称清单而不是直接套用官方原生的模型名[model_providers.custom_gateway] name 自定义网关 base_url https://your-gateway.example.com/v1 # 有些网关要求带上游厂商前缀具体格式以该网关文档为准 model openai/gpt-5-codex方案四确认账号权限等级是否满足模型要求# 查看当前账号的订阅状态和权限等级 codex whoami --verbose如果确认某个模型确实需要更高等级的订阅或特殊的邀测资格评估是否需要升级订阅或者暂时切换到当前账号权限范围内可用的模型。方案五模型下线后及时切换到官方推荐的替代模型AI 模型的迭代/下线是常态遇到以前能用现在不能用的情况优先查看官方是否发布了模型迁移说明按推荐的替代模型名称更新配置而不是尝试各种旁门左道让旧模型名称复活# 官方公告中通常会给出明确的迁移路径例如 # model gpt-5 已被 model gpt-5.1 替代 model gpt-5.1-codex4. 各方案对比总结方案适用场景推荐指数确认官方模型列表所有场景的第一排查步骤⭐⭐⭐⭐⭐检查拼写大小写手动编辑配置文件后的常见笔误⭐⭐⭐⭐⭐确认第三方网关命名规则接入非官方 API 端点的场景⭐⭐⭐⭐确认账号权限等级怀疑是权限而非名称问题⭐⭐⭐⭐切换到替代模型模型已被官方下线/迭代⭐⭐⭐⭐5. 常见问题 FAQ5.1 报错信息里同时出现model not found和 401应该先查哪个建议先排查认证问题401确保账号本身能正常鉴权通过之后再单独排查模型名称是否正确。如果认证都没通过模型名称是否正确根本无法被服务端真正校验到。5.2 为什么同一个模型名称在 CLI 里能用在 IDE 插件里却报错CLI 和 IDE 插件有可能读取的是两份独立的配置文件一份是~/.codex/config.toml插件可能有自己独立的设置界面需要分别确认两处配置的模型名称是否一致。5.3 接入国产大模型的 OpenAI 兼容接口时模型名称应该怎么填需要查阅该模型服务商提供的 OpenAI 兼容文档通常会明确给出接口调用时应该填写的model参数值这个值不一定和模型的官方展示名称完全一致务必以接口文档为准。5.4 团队里配置模板发生了变化如何快速确认哪些机器还在用旧的模型名称可以写一个简单的批量检查脚本扫描团队内已知的配置文件路径输出当前各自使用的模型名称方便统一排查和更新grep -H ^model ~/.codex/config.toml 2/dev/null5.5 是否有办法让 Codex 在模型不可用时自动降级到备用模型需要确认当前版本是否支持配置备用模型/自动降级策略如果不支持可以在自己的调用脚本层面实现简单的重试降级逻辑先尝试首选模型捕获到model_not_found错误后自动切换到预设的备用模型重试一次。5.6 这个报错和网络连接问题有什么区别model not found通常发生在请求已经成功到达服务端、并且完成了基础认证之后是服务端在业务逻辑层返回的错误网络连接问题比如超时、DNS 解析失败发生在请求根本没能到达服务端的阶段两者的报错文案和触发阶段完全不同不要混淆排查方向。5.7 排查清单速查表□ 1. 确认官方当前支持的模型名称清单不要依赖旧教程 □ 2. 逐字核对配置文件中模型名称的拼写与大小写 □ 3. 第三方 API 网关场景下确认该网关自己的模型命名规则 □ 4. 检查账号订阅等级是否满足该模型的权限要求 □ 5. 确认是否是模型已被官方下线需要切换替代模型 □ 6. 区分清楚是认证问题还是模型名称问题 □ 7. 团队场景批量检查各机器的配置文件是否已同步更新6. 总结model not found/unsupported model报错的本质是请求中指定的模型名称在服务端的可用模型列表或当前账号的权限范围内找不到匹配项而不是 Codex CLI 本身出现故障。核心处理思路优先确认官方当前实际支持的模型名称清单不要依赖可能已经过时的旧教程或记忆仔细核对配置文件中的拼写、大小写这是手动编辑配置时最常见的笔误来源接入第三方 API 网关时务必单独确认该网关自己的模型命名规则不能直接套用官方原生名称。最佳实践建议把确认当前可用模型清单作为切换模型配置前的标准前置步骤而不是切换后遇到报错才去排查能大幅减少这类问题反复出现的概率。