写在前面：为什么会有这篇教程
事情的起因很朴素：我搞到了一个超酷的自定义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...
- gpt-5.6-sol (current) Frontier model for complex coding...
- 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的朋友们，动动手指在评论区告诉我你在用什么系统吧！ 你们的反馈决定了下一期教程的优先级 🔥
写在最后：这次配置让我悟出的道理
这次配置过程让我深刻体会到：
Codex的配置不是填表，而是一场推理游戏。它的报错信息永远只告诉你“缺什么”，从不告诉你“为什么”。但只要理解了它的模型加载逻辑——model_catalog_json > models_cache.json > config.toml里的models，你就能反过来掌握主动权。
复制永远比手写快。直接从models_cache.json里复制一个完整条目再改，比手写一个少10个字段要省事得多。
路径要用绝对路径。这个坑我踩了两次，每次都是因为偷懒用了~。
cc-switch不是万能药。它能帮你切换密钥，但不能帮你填JSON字段。
评论区是宝藏。我解决最后几个报错的关键线索，就是在GitHub Issue和论坛的评论区里翻到的。所以，如果你在配置过程中遇到了我文中没提到的问题，先翻评论区，再提问。
最后最后：希望这篇教程能帮你少摔几个跟头。如果还有报错，欢迎截图砸过来——我已经和这些错误打过太多交道了，闭着眼睛都能猜出下一个缺什么字段了。
祝大家配置顺利，自由切换！ 🚀
附：文中所有路径均为macOS示例，Linux/Windows用户请参考第四章预告，并在评论区留下你的需求。如果报错信息中包含“os error 2”或“No such file”，大概率是路径问题，先去检查你的model_catalog_json指向的文件到底存不存在——我发誓这是我最后一次提这件事了。
