【Bug已解决】codex: model not available / Invalid model specified — CodeX CLI 模型不可用错误解决方案1. 问题描述在 CodeX CLI 中指定模型时报模型不可用或无效错误# 模型不存在 $ codex --model gpt-5 Error: Invalid model specified: gpt-5 Available models: gpt-4o, gpt-4o-mini, o1, o3-mini # 或模型无权限 $ codex --model o1-preview Error: Model not available for your API tier Your API key does not have access to o1-preview # 或模型名称拼写错误 $ codex --model GPT-4o Error: Invalid model specified: GPT-4o # 大小写敏感 # 或旧模型已弃用 $ codex --model gpt-3.5-turbo Error: Model deprecated: gpt-3.5-turbo This model has been discontinued这个问题在以下场景中特别常见使用了不存在的模型名称API Key 的 Tier 不支持目标模型模型名称大小写错误使用了已弃用的旧模型模型名称拼写错误配置文件中的模型名称错误2. 原因分析核心原理拆解CodeX CLI → 指定模型 → 调用 API ↓ 模型不存在/无权限/已弃用/名称错误 ↓ API 返回错误原因分类表原因分类具体表现占比名称不存在gpt-5 等不存在约 35%权限不足Tier 不支持约 25%拼写错误GPT-4o vs gpt-4o约 20%模型弃用gpt-3.5-turbo约 10%配置错误config.json 中名称错约 5%版本问题旧版 CodeX 不支持新模型约 5%3. 解决方案方案一使用正确的模型名称最推荐# 步骤 1查看可用模型 codex --list-models # 或通过 API 查看 curl https://api.openai.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY | python3 -m json.tool # 步骤 2使用正确的名称全小写 codex --model gpt-4o codex --model gpt-4o-mini codex --model o1 codex --model o3-mini # 步骤 3验证 codex --model gpt-4o hello # 步骤 4注意大小写 # 正确: gpt-4o全小写 # 错误: GPT-4o, Gpt-4o, gpt-4O方案二检查 API Tier 权限# 步骤 1在 OpenAI Platform 查看 Tier # https://platform.openai.com/account/billing # 步骤 2不同 Tier 支持的模型 # Tier 1: gpt-4o, gpt-4o-mini # Tier 2: o1, o1-preview, o3-mini # 步骤 3如果 Tier 不够 # 充值到更高 Tier # 或使用 Tier 支持的模型 codex --model gpt-4o # Tier 1 可用方案三替换已弃用的模型# 步骤 1已弃用的模型和替代品 # gpt-3.5-turbo → gpt-4o-mini # gpt-4 → gpt-4o # gpt-4-0314 → gpt-4o # 步骤 2使用替代模型 codex --model gpt-4o-mini # 替代 gpt-3.5-turbo # 步骤 3验证 codex --model gpt-4o-mini hello方案四修复配置文件# 步骤 1检查配置文件中的模型 cat ~/.codex/config.json # 如果 model 是错误名称修复 # 步骤 2修复 cat ~/.codex/config.json EOF { model: gpt-4o, maxTokens: 4096 } EOF # 步骤 3验证 codex --model gpt-4o hello方案五使用环境变量指定模型# 步骤 1通过环境变量指定 export OPENAI_MODELgpt-4o codex # 步骤 2或 export CODEX_MODELgpt-4o-mini codex # 步骤 3永久设置 echo export OPENAI_MODELgpt-4o ~/.zshrc source ~/.zshrc方案六更新 CodeX CLI 版本# 步骤 1检查版本 codex --version # 步骤 2更新到最新版 npm update -g openai/codex # 步骤 3新版本可能支持更多模型 codex --list-models4. 各方案对比总结方案适用场景推荐指数难度方案一正确名称名称错误⭐⭐⭐⭐⭐低方案二检查 Tier权限不足⭐⭐⭐⭐⭐低方案三替换弃用旧模型⭐⭐⭐⭐⭐低方案四修复配置配置错误⭐⭐⭐⭐低方案五环境变量持久设置⭐⭐⭐⭐低方案六更新版本版本旧⭐⭐⭐低5. 常见问题 FAQ5.1 OpenAI 目前有哪些可用模型gpt-4o: 旗舰模型多模态gpt-4o-mini: 轻量版性价比高o1: 推理模型o1-preview: o1 预览版o3-mini: 轻量推理模型5.2 模型名称大小写敏感吗是的。必须全小写gpt-4o而非GPT-4o。5.3 如何查看 API Key 支持的模型curl https://api.openai.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY | python3 -m json.tool5.4 gpt-3.5-turbo 还能用吗已逐步弃用。使用gpt-4o-mini作为替代性能更好且价格更低。5.5 Tier 如何升级在 https://platform.openai.com/account/billing 充值。不同充值金额对应不同 Tier。5.6 如何设置默认模型在配置文件中设置{model: gpt-4o}或通过环境变量OPENAI_MODELgpt-4o。5.7 o1 模型和 gpt-4o 的区别o1 是推理模型擅长数学、编程、逻辑推理但响应慢且价格高。gpt-4o 是通用模型速度快。5.8 CI/CD 中指定模型OPENAI_MODELgpt-4o-mini codex task5.9 模型不可用但 API 返回的列表中有可能是 API Key 的 Tier 不足。查看 OpenAI Platform 的 Billing 页面确认 Tier。5.10 排查清单速查表□ 1. codex --list-models 查看可用模型 □ 2. 使用全小写名称: gpt-4o □ 3. curl API 查看 Key 支持的模型 □ 4. 检查 Tier 是否支持目标模型 □ 5. gpt-3.5-turbo → gpt-4o-mini □ 6. gpt-4 → gpt-4o □ 7. 检查 config.json 中的模型名称 □ 8. OPENAI_MODEL 环境变量指定 □ 9. 更新 CodeX CLI 到最新版本 □ 10. platform.openai.com/account/billing 查看 Tier6. 总结根本原因模型不可用最常见原因是名称不存在35%如 gpt-5和 API Tier 权限不足25%最佳实践使用codex --list-models查看可用模型使用全小写名称gpt-4o而非GPT-4oTier 权限在 https://platform.openai.com/account/billing 查看 Tier充值升级获取更多模型访问权模型替换gpt-3.5-turbo→gpt-4o-minigpt-4→gpt-4o使用新模型替代已弃用模型最佳实践建议在~/.codex/config.json中设置默认模型为gpt-4o通过--model参数临时切换避免每次手动指定故障排查流程图flowchart TD A[模型不可用] -- B[codex --list-models 查看可用模型] B -- C{目标模型在列表中?} C --|否| D[使用可用模型] C --|是| E[检查名称拼写] D -- F[使用 gpt-4o 或 gpt-4o-mini] E -- G{名称全小写?} G --|否| H[改为全小写: gpt-4o] G --|是| I[检查 API Tier] H -- j F -- j j -- J[codex --model gpt-4o hello] I -- K{Tier 足够?} K --|否| L[升级 Tier 或用可用模型] K --|是| M[检查模型是否弃用] L -- J M -- N{已弃用?} N --|是| O[使用替代模型] N --|否| P[更新 CodeX CLI] O -- J P -- J J -- Q{成功?} Q --|是| R[✅ 问题解决] Q --|否| S[检查 config.json] S -- T[修复模型名称] T -- J