【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_MODEL=gpt-4o codex # 步骤 2：或 export CODEX_MODEL=gpt-4o-mini codex # 步骤 3：永久设置 echo 'export OPENAI_MODEL=gpt-4o' >> ~/.zshrc source ~/.zshrc方案六：更新 CodeX CLI 版本
# 步骤 1：检查版本 codex --version # 步骤 2：更新到最新版 npm update -g @openai/codex # 步骤 3：新版本可能支持更多模型 codex --list-models4. 各方案对比总结
| 方案 | 适用场景 | 推荐指数 | 难度 |
|---|---|---|---|
| 方案一：正确名称 | 名称错误 | ⭐⭐⭐⭐⭐ | 低 |
| 方案二：检查 Tier | 权限不足 | ⭐⭐⭐⭐⭐ | 低 |
| 方案三：替换弃用 | 旧模型 | ⭐⭐⭐⭐⭐ | 低 |
| 方案四：修复配置 | 配置错误 | ⭐⭐⭐⭐ | 低 |
| 方案五：环境变量 | 持久设置 | ⭐⭐⭐⭐ | 低 |
| 方案六：更新版本 | 版本旧 | ⭐⭐⭐ | 低 |
5. 常见问题 FAQ
5.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_MODEL=gpt-4o。
5.7 o1 模型和 gpt-4o 的区别
o1 是推理模型，擅长数学、编程、逻辑推理，但响应慢且价格高。gpt-4o 是通用模型，速度快。
5.8 CI/CD 中指定模型
OPENAI_MODEL=gpt-4o-mini codex "task"5.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-4o） - Tier 权限：在 https://platform.openai.com/account/billing 查看 Tier，充值升级获取更多模型访问权
- 模型替换：
gpt-3.5-turbo→gpt-4o-mini，gpt-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
