发布日期：2026-07-02 ｜ 数据来源：OpenAI Codex 官方文档（developers.openai.com/codex）、七牛开发者中心、七牛云 Codex 配置指南（2026-07-02/03 实时核实）

Codex 接入第三方模型的核心原理是：在 ~/.codex/config.toml 中定义自定义 model_providers，把请求指向兼容 OpenAI Responses API 的第三方端点。由于 Codex 桌面端（Codex App）与 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 当日核实）：

1. 协议：Codex 的 wire_api 仅支持 responses（Responses API），官方文档明确这是唯一合法值。第三方服务必须提供 Responses 兼容端点，普通 Chat Completions 端点无法直连
2. 三端同源：Codex App（桌面端）、CLI、IDE 扩展读取同一份 ~/.codex/config.toml——不存在"桌面端单独配置"这回事，改一处全生效
3. 作用域：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 获取）

三步完成：

1. 运行配置向导（无需安装）：

npx qiniu-coding-helper

2. 按提示依次完成：选择语言（中文/英文）→ 选择线路（国内/海外）→ 输入并验证 API Key → 选择模型

3. 重启 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）的三个专属注意点

1. 配置入口：桌面端设置面板（Cmd+,）只覆盖常用项，自定义 provider 等高级配置仍需编辑 config.toml——官方文档写明"use in-app controls for common settings or edit config.toml for advanced ones"
2. 重启生效：修改 config.toml 后需重启 Codex App；CLI 则是下次启动生效
3. 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 永远只进环境变量。