----
## 写在前面：为什么会有这篇教程

事情的起因很朴素：我搞到了一个超酷的自定义API（叫CUMOB），想在Codex里直接用。按照我多年“改个配置就能用”的朴素世界观，我打开了`~/.codex/config.toml`，优雅地加了几行配置，然后敲下`codex`。
迎接我的不是掌声，而是Codex无情的报错。
更惨的是，这不是我第一次栽在Codex配置上。从**cc-switch**的环境变量陷阱，到**ChatGPT**的模型切换迷思，再到**Codex**的`model_catalog_json`玄学——我几乎把所有坑都踩了一遍。这篇教程，就是我用头发换来的经验合集。
>**本文目标**：让你在10分钟内搞定Codex自定义模型配置，顺便摸清ChatGPT和cc-switch的联动玩法，不用像我一样在JSON的海洋里溺水。


----
## 第一章：为什么“改个配置”不起作用了？

### 1.1 新版Codex的“包办婚姻”逻辑

在旧版Codex中，你可以在`config.toml`里直接写`models = ["my-model"]`，然后它就乖乖出现了。但新版Codex学聪明了（或者说学坏了），它引入了**两层模型来源**：


|来源|作用|可编辑性|
|:-:|:-:|:-:|
|**服务端缓存**（`models_cache.json`）|Codex自动从官方拉取的模型列表|❌ 会被覆盖，不要手动改|
|**用户自定义**（`model_catalog_json`）|你自己定义的模型列表|✅ 你想怎么改就怎么改|
简单来说：**新版Codex默认只认官方模型，你要用自己的模型，得单独给它开个“小灶”。**
### 1.2 ChatGPT和cc-switch在里面扮演什么角色？

- **ChatGPT**：如果你用的是ChatGPT的模型（比如`gpt-5.6-sol`），Codex默认就能识别，不需要额外配置。
- **cc-switch**：这是一个在多个AI服务之间快速切换的命令行工具。它本身不参与Codex的模型加载，但如果你在用cc-switch管理API密钥，记得把`OPENAI_API_KEY`环境变量设置对——否则Codex会找不到认证信息。

>**一句话总结**：Codex负责模型下拉菜单，ChatGPT提供模型API，cc-switch帮你管理密钥切换——各司其职，互不干扰，但只要一个环节错了，你就得和我一样在报错信息里泡澡。


----
## 第二章：实战！从报错到成功的完整流程

### 2.1 第一步：别碰`config.toml`里的`models`字段

我最初的配置是这样的（**错误示范**）：
toml
```
[model_providers.custom]
name = "CUMOB API"
base_url = "https://api.cumob.com/v1"
models = ["claude-fable-5"]  # ❌ 新版已废弃，写了等于白写
```
然后我收到了第一个报错：
text
```
Error loading configuration: No such file or directory (os error 2)
```
这其实是Codex在说：“你提到的那个文件路径，我找不到啊。”
**正确姿势**：`models`字段在新版Codex中基本被无视了，真正起作用的，是`model_catalog_json`。


----
### 2.2 第二步：创建你的“小灶”——`model_catalog_json`

bash
```
# 创建目录
mkdir -p ~/.codex/model-catalogs

# 创建自定义模型文件
touch ~/.codex/model-catalogs/cumob-models.json
```
然后在`config.toml`里指向它：
toml
```
model_catalog_json = "/Users/你的用户名/.codex/model-catalogs/cumob-models.json"
```
>**坑点预警**：路径必须是**绝对路径**，不要用`~`缩写，否则Codex会翻脸。


----
### 2.3 第三步：填JSON字段——一场“查漏补缺”的马拉松

当我第一次填好`cumob-models.json`并重启Codex时，迎接我的是一连串报错：
text
```
missing field `base_instructions` at line 23 column 5
```
我补上`base_instructions`，重启：
text
```
missing field `supports_reasoning_summaries` at line 24 column 5
```
我补上，重启：
text
```
missing field `xxx` at line 25 column 5
```
那一刻我感觉自己像个流水线工人，反复做着同样的事。Codex就像一个严格的面试官，每轮只问一个问题，你回答完了它才问下一个。
**血的教训**：与其被Codex一个一个地挤牙膏，不如**直接从`models_cache.json`里复制一个完整的模型条目**，然后修改`slug`和`display_name`。这样所有字段都齐全，一次过关。


----
### 2.4 第四步：完整模型条目模板（保命版）

json
```
{
  "slug": "你的模型ID",
  "display_name": "下拉菜单显示的名称",
  "description": "简短描述（可选）",
  "default_reasoning_level": "high",
  "supported_reasoning_levels": [
    { "effort": "low", "description": "Fast responses with lighter reasoning" },
    { "effort": "medium", "description": "Balances speed and reasoning depth" },
    { "effort": "high", "description": "Greater reasoning depth" },
    { "effort": "xhigh", "description": "Maximum reasoning depth" }
  ],
  "shell_type": "shell_command",
  "visibility": "list",                    // ⚠️ 关键：必须为"list"才会出现在下拉菜单
  "supported_in_api": true,
  "priority": 7,
  "base_instructions": "你的系统提示词（必填）",
  "supports_reasoning_summaries": true,
  "default_reasoning_summary": "none",
  "support_verbosity": true,
  "default_verbosity": "low",
  "apply_patch_tool_type": "freeform",
  "web_search_tool_type": "text_and_image",
  "truncation_policy": { "mode": "tokens", "limit": 10000 },
  "supports_parallel_tool_calls": true,
  "supports_image_detail_original": true,
  "context_window": 272000,
  "max_context_window": 272000,
  "input_modalities": ["text", "image"],
  "supports_search_tool": true,
  "use_responses_lite": false
}
```
>**我花了多久踩这个坑？** 整整两个晚上，因为`visibility`我写成了`"hidden"`，然后疯狂重启Codex，以为是自己JSON格式错了。


----
### 2.5 第五步：设置环境变量（cc-switch用户注意）

bash
```
export OPENAI_API_KEY="你的API密钥"
```
如果你在用**cc-switch**管理多个API密钥，只需要在切换时保证`OPENAI_API_KEY`指向正确的服务即可。Codex只认这个环境变量，不管背后是谁的API。


----
### 2.6 第六步：重启，收工！

bash
```
codex
```
如果一切顺利，你会看到类似这样的画面：
text
```
Select Model and Effort
› 1. claude-fable-5 (default)  Frontier model for complex coding...
  2. gpt-5.6-sol (current)     Frontier model for complex coding...
  3. gpt-5.5                   Frontier model for complex coding...
```
🎉 **你的自定义模型成功出现在下拉菜单里了！**


----
## 第三章：如果还是报错——常见问题速查


|报错信息|可能原因|解决方案|
|:-:|:-:|:-:|
|`No such file or directory`|`model_catalog_json`路径不对|改用**绝对路径**，检查文件是否存在|
|`missing field xxx`|JSON缺少必填字段|用上面的模板补全所有字段|
|`visibility`设置了但没出现|`visibility`不是`"list"`|改为`"list"`|
|模型选了但API调用失败|环境变量或API地址有误|检查`OPENAI_API_KEY`和`base_url`|
|MCP相关报错（如`node_repl`）|Codex自带服务启动失败|可以忽略，不影响模型切换功能|


----
## 第四章：Linux/Windows用户专区（预告篇）

由于我目前是在macOS上完成的这篇教程，**Linux和Windows的具体操作步骤我还没能在真实环境中完整验证**。
但根据我的研究和社区反馈，核心原理是一致的，只有路径和部分命令有差异：
- **Linux**：`~/.codex/`路径规则相同，但可能需要留意文件权限（`chmod`）和软件包安装方式（如AppImage或deb包）。
- **Windows**：路径变为`%USERPROFILE%\.codex\`（或`C:\Users\你的用户名\.codex\`），命令行工具需使用WSL或PowerShell。且Codex在Windows上可能通过WSL运行更稳定。


----
## 📢 关于Linux/Windows版本的后续计划

>**如果你在Linux或Windows上成功配置了Codex自定义模型，欢迎在评论区分享你的经验！**

如果这篇教程的评论区里，Linux和Windows用户的需求足够多（比如留言超过30条或点赞过百），我会**专门出一期Linux/Windows版的完整教程**，覆盖：
- ✅ Linux下的路径、权限和常见报错处理
- ✅ Windows下的WSL vs 原生CMD差异
- ✅ 各平台特有的坑点和解决方案
- ✅ 社区贡献的实战案例汇总

所以，**Linux/Windows的朋友们，动动手指在评论区告诉我你在用什么系统吧！** 你们的反馈决定了下一期教程的优先级 🔥


----
## 写在最后：这次配置让我悟出的道理

这次配置过程让我深刻体会到：
1. **Codex的配置不是填表，而是一场推理游戏**。它的报错信息永远只告诉你“缺什么”，从不告诉你“为什么”。但只要理解了它的模型加载逻辑——`model_catalog_json` > `models_cache.json` > `config.toml`里的`models`，你就能反过来掌握主动权。
2. **复制永远比手写快**。直接从`models_cache.json`里复制一个完整条目再改，比手写一个少10个字段要省事得多。
3. **路径要用绝对路径**。这个坑我踩了两次，每次都是因为偷懒用了`~`。
4. **cc-switch不是万能药**。它能帮你切换密钥，但不能帮你填JSON字段。
5. **评论区是宝藏**。我解决最后几个报错的关键线索，就是在GitHub Issue和论坛的评论区里翻到的。所以，如果你在配置过程中遇到了我文中没提到的问题，**先翻评论区，再提问**。


----
**最后最后**：希望这篇教程能帮你少摔几个跟头。如果还有报错，欢迎截图砸过来——我已经和这些错误打过太多交道了，闭着眼睛都能猜出下一个缺什么字段了。
**祝大家配置顺利，自由切换！** 🚀


----
附：文中所有路径均为macOS示例，Linux/Windows用户请参考第四章预告，并在评论区留下你的需求。如果报错信息中包含“os error 2”或“No such file”，大概率是路径问题，先去检查你的`model_catalog_json`指向的文件到底存不存在——这是我最后一次提这件事了。


事情的起因很朴素：我搞到了一个超酷的自定义API（叫CUMOB），想在Codex里直接用。按照我多年“改个配置就能用”的朴素世界观，我打开了~/.codex/config.toml，优雅地加了几行配置，然后敲下codex。迎接我的不是掌声，而是Codex无情的报错。更惨的是，这不是我第一次栽在Codex配置上。从cc-switch的环境变量陷阱，到ChatGPT的模型切换迷思，再到Codex的model_catalog_json玄学——我几乎把所有坑都踩了一遍。这篇教程，就是我用头发换来的经验合集。

最新版Codex/ChatGPT/cc-switch完全上手教程：我与Codex的“包办婚姻”——从报错拒见到自定义模型自由

事情的起因很朴素：我搞到了一个超酷的自定义API（叫CUMOB），想在Codex里直接用。按照我多年“改个配置就能用”的朴素世界观，我打开了~/.codex/config.toml，优雅地加了几行配置，然后敲下codex。迎接我的不是掌声，而是Codex无情的报错。更惨的是，这不是我第一次栽在Codex配置上。从cc-switch的环境变量陷阱，到ChatGPT的模型切换迷思，再到Codex的mo

开发工具

编程语言

人工智能

Codex自定义模型配置教程：详解新版Codex模型加载机制，提供完整JSON模板和配置步骤，解决常见报错问题。涵盖macOS/Linux/Windows多平台配置要点，帮助开发者10分钟内完成自定义API接入，避免踩坑。

命令行工具

代码解释

ChatGPT

Windows

Linux

JSON

2026上云采购 | AI焕新·智启新局

apigw

腾讯云大模型Token Plan个人版28元/月起

tokenhub

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

最新版Codex/ChatGPT/cc-switch完全上手教程：我与Codex的“包办婚姻”——从报错拒见到自定义模型自由-腾讯云开发者社区-腾讯云

最新版Codex/ChatGPT/cc-switch完全上手教程：我与Codex的“包办婚姻”——从报错拒见到自定义模型自由

最新版Codex/ChatGPT/cc-switch完全上手教程：我与Codex的“包办婚姻”——从报错拒见到自定义模型自由

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐