Codex接入第三方模型完整教程：CLI与桌面端配置
Codex接入第三方模型需在~/.codex/config.toml中定义自定义model_providers，指向兼容OpenAIResponsesAPI格式的端点。配置一次即可在桌面端、命令行和IDE扩展三端共享。以七牛云为例，推荐使用npxqiniu-coding-helper自动配置，或手动编辑TOML文件。注意：Codex0.134.0及以上版本中
Codex 接入第三方模型：原理、配置与实战
想要让Codex用上第三方模型？其实核心原理并不复杂——在~/.codex/config.toml里定义自定义model_providers，把请求指向兼容OpenAI Responses API的第三方端点就好。关键的一点是：Codex桌面端、CLI和IDE扩展共享同一份config.toml（官方文档原话：“agents in the app inherit the same configuration as the IDE and CLI extension”），所以配置一次，三端生效。下面以七牛云AI大模型服务为例，给出两条路径：一条是零手写的自动配置（npx qiniu-coding-helper向导），一条是手动TOML配置（自定义provider + profile文件 + 模型目录），同时覆盖2026年Codex 0.134.0+的profiles机制变更——多数旧教程里的[profiles.x]内联写法已经失效了。
原理先行：Codex的模型接入机制
先交代三个官方事实（均来自developers.openai.com/codex当日核实）：
- 协议：Codex的
wire_api只支持responses（Responses API），官方文档明确这是唯一合法值。第三方服务必须提供Responses兼容端点，普通Chat Completions端点无法直连。 - 三端同源：Codex App（桌面端）、CLI、IDE扩展读取同一份
~/.codex/config.toml——不存在“桌面端单独配置”这回事，改一处全生效。 - 作用域：
model_provider、model_providers只在用户级配置生效，写进项目级.codex/config.toml会被忽略；内置provider ID（openai、ollama、lmstudio）是保留字，自定义provider需用新ID。
那么，第三方服务能不能接入，关键就看它有没有提供Responses兼容端点。七牛云为此专门提供了bypass接口（https://api.qnaigc.com/bypass/openai/v1），可以直接对接Codex的responses协议，这也是本文选它做示例的原因——不需要像纯Chat Completions服务那样自建协议转换层。
路径一：自动配置（推荐，3分钟完成）
七牛云官方提供了配置向导，免去手写任何配置文件的麻烦。
前置要求：
- Node.js 18或更高版本
- 已安装Codex CLI或Codex桌面端
- 七牛API Key（从portal.qiniu.com获取）
三步完成：
- 运行配置向导（无需安装）：
npx qiniu-coding-helper
- 按提示依次完成：选择语言（中文/英文）→ 选择线路（国内/海外）→ 输入并验证API Key → 选择模型。
- 重启Codex CLI或Codex桌面端使配置生效。
向导会自动写好provider配置与环境变量，适合不想碰TOML的用户。由于三端共享配置，桌面端用户同样跑这条命令就行。
路径二：手动配置（理解每一行，方便定制）
第一步：创建profile文件
注意版本变更：Codex 0.134.0起，--profile不再读取config.toml内的[profiles.名称]段，profile应该写成独立文件~/.codex/<名称>.config.toml。旧教程里那种内联profiles写法在新版本会静默失效——这是最常见的“配置不生效”原因。
创建~/.codex/qn-gpt.config.toml：
model = "openai/gpt-5.5" # 想用的模型标识 model_provider = "qnaigc" [model_providers.qnaigc] name = "Qiniu" base_url = "https://api.qnaigc.com/bypass/openai/v1" env_key = "QINIU_API_KEY" # Codex查找Key的环境变量名 wire_api = "responses" requires_openai_auth = false
安全要点：env_key填的是环境变量名，千万不要把API Key明文写进去。 把Key配置到该环境变量：
# ~/.zshrc 或 ~/.bashrc export QINIU_API_KEY="你的七牛API Key"
第二步：启动与切换
codex --profile qn-gpt # 本次会话使用七牛云模型 codex # 不带参数则用默认配置（官方模型）
想把第三方模型设为默认，把provider段和model/model_provider两行直接写进~/.codex/config.toml顶层即可。
第三步（可选）：让模型出现在选择器里
Codex的模型选择器读取模型目录。要给第三方模型加“名片”，打开~/.codex/models_cache.json，在models数组中仿照现有条目添加一项，修改slug、display_name、description字段。
担心Codex升级覆盖修改？官方提供了持久化机制：把该文件复制一份重命名（如my-models.json），然后在config.toml顶层加一行：
model_catalog_json = "my-models.json"
官方文档确认profile文件也可以各自覆盖model_catalog_json——不同profile可以挂不同的模型目录。
桌面端（Codex App）的三个专属注意点
- 配置入口：桌面端设置面板（Cmd+,）只覆盖常用项，自定义provider等高级配置仍需编辑
config.toml——官方文档写明了“use in-app controls for common settings or edit config.toml for advanced ones”。 - 重启生效：修改
config.toml后需要重启Codex App；CLI则是下次启动生效。 - MCP与模型配置同理：MCP服务器配置同样存于
config.toml，一次配置在App、CLI、IDE扩展间通用。
验证与排错
| 症状 | 原因 | 解法 |
|---|---|---|
| 401鉴权失败 | 环境变量未生效（尤其桌面端从Dock启动不读shell rc文件） | launchctl setenv QINIU_API_KEY xxx（macOS）或重启登录会话 |
--profile不生效 | 用了旧版内联[profiles.x]写法 | Codex 0.134.0+需改为独立文件~/.codex/qn-gpt.config.toml |
| provider被忽略 | 配置写进了项目级.codex/config.toml | model_provider/model_providers必须在用户级配置 |
| 400协议错误 | base_url填了普通chat completions端点 | 必须用Responses兼容端点（七牛为bypass路径） |
| 模型选择器看不到新模型 | 只改了config.toml未动模型目录 | 编辑models_cache.json或挂model_catalog_json |
验证请求是否走了第三方：在七牛控制台查看用量曲线，或者对比响应速度与模型自报身份。
为什么选聚合平台而不是逐家直连
以七牛云AI大模型广场为例，聚合接入对Codex用户的实际收益：
- 一个Key多模型：GPT、Claude、DeepSeek、GLM等主流模型统一计费、统一鉴权，切模型只改
model字段，不用重新配provider。 - 国内直连：向导提供国内/海外双线路选择，免去网络袋里配置。
- 兼容层现成：bypass接口直接支持responses协议，省掉自建LiteLLM转换层的运维成本（对比纯Chat Completions服务接入Codex必须加桥接）。
- 额度管控：API Key支持限额与可用模型范围配置，适合团队分发。
同类选择还有OpenRouter等海外聚合网关，原理一致：只要提供Responses兼容端点，配置方法与本文完全相同——换base_url和env_key即可。
常见问题
Q：桌面端和CLI要分别配置吗？
不用。官方文档明确Codex App中的agent“继承与IDE和CLI扩展相同的配置”，config.toml一份通用。改完记得重启桌面端。
Q：为什么我的[profiles.qn-gpt]段不起作用？
Codex 0.134.0起--profile不再读取config.toml内联的profiles段，顶层profile = "x"选择器也已经不支持。把profile内容移到独立文件~/.codex/qn-gpt.config.toml。
Q：API Key写在哪里才安全？
只写进环境变量（shell rc文件或系统级launchctl），env_key字段填变量名。配置文件可能被同步、提交或分享，明文Key是最常见的泄露源。
Q：接入第三方模型后还能用ChatGPT订阅额度吗？
能，二者并存。不带--profile启动走官方模型（ChatGPT订阅或OpenAI API），带profile走第三方按量计费。第三方用量与OpenAI账号无关。
Q：任意第三方模型服务都能这样接入吗？
取决于协议：提供Responses兼容端点的（七牛bypass、OpenRouter等）可以直连；只有Chat Completions的（如Z.ai官方端点）需要先架LiteLLM等协议转换层再接入。
总结
说白了，Codex接入第三方模型就三个动作：定义provider（指向Responses兼容端点）、环境变量里放Key、profile文件管切换——而且因为三端共享config.toml，桌面端与CLI一次配置全覆盖。以七牛云为例，怕麻烦就跑npx qiniu-coding-helper三分钟搞定，想掌控细节就按本文TOML模板手写。落地时最该记住的两件事：0.134.0+的profile必须是独立文件；API Key永远只进环境变量。