
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. 运行配置向导（无需安装）：

```bash
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`：

```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 配置到该环境变量：

```bash
# ~/.zshrc 或 ~/.bashrc
export QINIU_API_KEY="你的七牛 API Key"
```

### 第二步：启动与切换

```bash
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` 顶层加一行：

```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 永远只进环境变量。


---


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 接入第三方模型完整教程：CLI 与桌面端通用配置

Codex 接入第三方模型的核心原理是：在 ~/.codex/config.toml 中定义自定义 model_providers，把请求指向兼容 OpenAI Responses API 的第三方端点。由于 Codex 桌面端（Codex App）与 CLI、IDE 扩展共享同一份 config.toml（官方文档原文："agents in the app inherit the same co

编程语言

开发工具

人工智能

Codex接入第三方模型的核心原理是通过修改~/.codex/config.toml配置文件，定义自定义model_providers并指向兼容OpenAI ResponsesAPI的第三方端点。七牛云AI大模型服务提供自动配置向导和手动TOML配置两种方式，支持Codex桌面端、CLI和IDE扩展三端共享配置。关键点包括：使用Responses兼容端点、正确设置环境变量存储APIKey、遵循0.134.0+版本的独立profile文件规范。

代码解释

服务器

DeepSeek

ChatGPT

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

Codex接入第三方模型的核心原理是通过修改~/.codex/config.toml配置文件，定义自定义model_providers并指向兼容OpenAI ResponsesAPI的第三方端点。七牛云AI大模型服务提供自动配置向导和手动TOML配置两种方式，支持Codex桌面端、CLI和IDE扩展三端共享配置。关键点...

Codex 接入第三方模型完整教程：CLI 与桌面端通用配置-腾讯云开发者社区-腾讯云

Codex 接入第三方模型完整教程：CLI 与桌面端通用配置

Codex 接入第三方模型完整教程：CLI 与桌面端通用配置

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐