Windows 版 Codex Desktop 配合 APINebula 中转站配置指南（非 CLI）

本文针对 Codex Desktop（桌面客户端），不是 Codex CLI（命令行版本）。
本文针对 Windows 系统，Mac 用户的配置文件路径和部分操作不同，请勿直接套用。

目前网上能找到的 Codex 第三方 API 配置教程，绝大多数针对的是 CLI 命令行版本或 Mac 系统。专门讲解 Windows 桌面版 + APINebula 的完整配置说明还很少，尤其是关于 auth.json 删除、api_key 与 env_key 区别、以及 Codex 自动回写配置等关键细节——本文会把这些都讲清楚。

前置准备

1. 注册 APINebula 获取 API Key
   👉 https://apinebula.com/mDydKv

   • 注册后在后台创建 API Key，格式为 sk-xxx，复制备用

2. 下载安装 Codex Desktop

   • 从 OpenAI Codex 官方页面 下载 Windows 版安装包（.exe 文件），双击安装即可
   • ⚠️ 注意：是下载 Desktop App，不是通过 npm 安装 CLI 命令行版本

---

一、配置文件在哪里？

Codex Desktop 安装后，所有配置都存储在这个目录下：

C:\Users\你的Windows用户名\.codex\

核心文件是 config.toml。Codex Desktop 首次启动后，会自动在这个文件里生成一组默认配置。我们需要修改这个文件，让 Codex 走 APINebula 中转而不是 OpenAI 官方接口。

Mac 用户请注意：Mac 版 Codex Desktop 的配置目录是 ~/.codex/（即 /Users/你的用户名/.codex/），路径不同，本文以 Windows 为准。

---

二、最终可用配置（直接复制使用）

打开 C:\Users\你的Windows用户名\.codex\config.toml，全选删除所有原有内容，粘贴以下配置：

# ========== 全局模型配置 ==========
model = "gpt-5.5"                    # 换成你在 APINebula 上实际可用的模型
model_provider = "apinebula"          # 指定使用自定义 provider
model_reasoning_effort = "medium"     # 推理力度：minimal | low | medium | high | xhigh

# ========== Windows 沙盒配置 ==========
[windows]
sandbox = "elevated"                  # Windows 下沙盒以提升权限运行

# ========== 项目信任配置（根据你的实际项目路径修改）==========
[projects.'c:\users\你的Windows用户名\documents\codex\2026-05-22\gitee']
trust_level = "trusted"

# ========== APINebula 中转提供商配置（核心！）==========
[model_providers.apinebula]
name = "apinebula"
base_url = "https://apinebula.com/v1"   # 中转站地址，末尾必须带 /v1
wire_api = "responses"                   # 必须是 responses，不能是 chat
api_key = "sk-你的APINebula密钥"          # 直接写密钥，不要用 env_key

你只需要改两处：

1. model — 换成你在 APINebula 上实际使用的模型名称
2. api_key — 换成你自己的 APINebula API Key

---

三、修改配置后的必要操作

Codex Desktop 关闭窗口 ≠ 退出程序，它仍旧在系统托盘中运行，旧配置在内存中不会刷新。请严格按以下步骤操作：

第一步：退出进程

• 右下角系统托盘 → 右键 Codex 图标 → 退出

第二步：确认进程已彻底结束

• 按 Ctrl + Shift + Esc 打开任务管理器
• 找到 Codex Desktop 进程 → 如仍在运行则手动 结束任务

第三步：删除冲突文件

进入 C:\Users\你的Windows用户名\.codex\，删除以下文件/文件夹（如果存在）：

• auth.json — 理由见下文第四节
• .cache 文件夹 — 缓存旧配置
• .tmp 文件夹 — 临时运行时文件

第四步：重新打开 Codex Desktop

• 从开始菜单或桌面快捷方式重新启动

💡 重要提示：Codex Desktop 重新启动后，会自动回写 [marketplaces] 和 [plugins] 配置到 config.toml 中。这是正常行为，不用担心——这些自动回写的配置不会影响你的中转站连接，只要 [model_providers.apinebula] 中的核心三要素（base_url、wire_api、api_key）正确，请求就会走 APINebula。详见下文第四节第 1、2 点的说明。

---

四、默认配置项详解——Codex 自动生成了什么？为什么可以简化？

首次启动 Codex Desktop 后，config.toml 会被自动写入大量配置项。下面逐个解释它们是干什么的，以及能不能去掉、去掉后有什么影响。

---

1. [marketplaces.openai-primary-runtime] 和 [marketplaces.openai-bundled]

[marketplaces.openai-primary-runtime]
last_updated = "2026-05-22T01:26:51Z"
source_type = "local"
source = '\\?\C:\Users\用户名\.cache\codex-runtimes\...\openai-primary-runtime'

[marketplaces.openai-bundled]
last_updated = "2026-05-22T01:51:24Z"
source_type = "local"
source = '\\?\C:\Users\用户名\.codex\.tmp\bundled-marketplaces\openai-bundled'

是什么： Codex 的插件市场注册信息。openai-primary-runtime 是主运行时插件集（包含文档、表格、PPT 等功能），openai-bundled 是内置捆绑插件集（包含浏览器等工具）。这两个配置告诉 Codex 从本地哪个路径加载这些插件的代码。

能不能去掉： 去掉也没用——Codex Desktop 每次启动都会自动检测本机环境，将 marketplaces 配置回写到 config.toml 中。 你删掉后再打开 Codex，它们又会出现，时间戳会更新为最新。这是 Codex 的正常行为。

会不会影响中转站连接： 不会。 这些配置控制的是插件功能的加载来源，与 API 请求发往哪个地址无关。只要 [model_providers.apinebula] 中的 base_url、wire_api、api_key 配置正确，请求就会走 APINebula，marketplaces 的存在不会产生干扰。

---

2. [plugins."documents@openai-primary-runtime"] 等启用开关

[plugins."documents@openai-primary-runtime"]
enabled = true

[plugins."spreadsheets@openai-primary-runtime"]
enabled = true

[plugins."presentations@openai-primary-runtime"]
enabled = true

[plugins."browser-use@openai-bundled"]
enabled = true

是什么： 与上面的插件市场配套，是每个具体插件的启用/禁用开关。documents 是文档工具、spreadsheets 是表格工具、presentations 是 PPT 工具、browser-use 是浏览器自动化工具。

能不能去掉： 同样，去掉后 Codex 会自动回写回来。这些插件本身是本地运行的 MCP 工具，不依赖 OpenAI API 接口。

会不会影响中转站连接： 不会。 这些工具是本地执行的，与模型 API 的请求地址无关。

如果确实不想用某些插件： 可以将 enabled 改为 false，而不是删除整个配置块：

[plugins."documents@openai-primary-runtime"]
enabled = false

---

3. [mcp_servers.pencil]

[mcp_servers.pencil]
command = "C:\\Program Files\\Pencil\\resources\\app.asar.unpacked\\out\\mcp-server-windows-x64.exe"
args = [ "--app", "desktop" ]

是什么： Pencil 绘图工具的 MCP（Model Context Protocol）服务器配置。Pencil 是一个独立安装的图表绘制应用，如果安装了它，Codex 可以通过这个配置调用 Pencil 来生成和编辑流程图、架构图等。MCP 是 Codex 与外部工具通信的标准协议，官方文档详见：https://developers.openai.com/codex/mcp

能不能去掉： 可以。如果你没有安装 Pencil，这个配置完全不生效。它是 Codex 检测到本机安装了 Pencil 后自动添加的。

去掉后的影响： AI 无法调用 Pencil 绘图功能。大部分用户并没有安装 Pencil，所以去掉没有任何影响。

---

4. auth.json 文件（必须删除）

是什么： 位于 C:\Users\你的Windows用户名\.codex\auth.json，它是 Codex 通过 OAuth 登录 OpenAI 官方账号后生成的认证令牌文件。根据 Codex 官方配置文档，默认的认证存储方式就是 cli_auth_credentials_store = "file"，认证信息就保存在这个文件里。

为什么必须删除： 这个文件的存在，会让 Codex 认为"用户已经通过 OpenAI 官方认证"，从而优先使用官方认证信息发起请求。即使你在 config.toml 里明确指定了 base_url = "https://apinebula.com/v1"，Codex 仍然会忽略它，直接请求 api.openai.com。这就是导致下面这个经典错误的根本原因——明明配了中转地址，请求却去了 api.openai.com，然后拿 APINebula 的密钥去访问 OpenAI 官方，自然返回 401：

unexpected status 401 Unauthorized: Incorrect API key provided: sk-xxx
url: https://api.openai.com/v1/responses

删除后的影响： 无任何负面影响。使用中转站不需要也不应该走 OpenAI 官方登录认证。删除后 Codex 会完全依赖 config.toml 中你写的中转站配置。

---

5. api_key vs env_key（为什么不能混用）

很多中转站教程会教你这样写：

# ⚠️ 不要这样写！
[model_providers.apinebula]
name = "apinebula"
base_url = "https://apinebula.com/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"    # ← 这是坑！

然后在系统环境变量里设置 OPENAI_API_KEY = "sk-xxx"。

为什么不能这样写： Codex 内部对 OPENAI_API_KEY 这个环境变量名有硬编码逻辑——当它检测到密钥来源于这个环境变量时，会默认将 API 请求发往 OpenAI 官方地址 api.openai.com，覆盖你在 base_url 中写的中转地址。所以表现就是：你配了中转站，但请求全去了 OpenAI 官方，401 报错。

正确写法： 直接在 config.toml 中用 api_key 明文写密钥，不用环境变量：

# ✅ 正确写法
api_key = "sk-你的APINebula密钥"

这样 Codex 就会老老实实遵循你指定的 base_url，把请求发到 APINebula。

---

6. wire_api = "responses"（为什么不能写 "chat"）

wire_api 指定 Codex 与模型 API 通信时使用的协议格式：

值	对应接口	当前状态
"chat"	/chat/completions	❌ 已废弃
"responses"	/responses	✅ 唯一可用

Codex 在 2025 年 12 月正式宣布废弃 wire_api = "chat"，2026 年 2 月起已转为硬性报错。如果写 "chat"，启动会直接报错：

failed to load configuration: `wire_api = "chat"` is no longer supported.
How to fix: set `wire_api = "responses"` in your provider config.
More info: https://github.com/openai/codex/discussions/7782

这是 Codex 的硬性要求，没有回旋余地。OpenAI 官方的说明是：chat/completions API 起源于 GPT-3.5 时代，不适合当今的 agentic 编码和推理场景，维护兼容性增加了复杂度并引入了回归问题。

参考： Codex 官方讨论 #7782 — Deprecating chat/completions support in Codex

---

7. .cache 和 .tmp 文件夹（为什么建议删除）

是什么： Codex 运行时自动生成的缓存和临时文件目录。里面可能包含：

• 旧配置文件的缓存副本
• 下载的运行时组件（如 codex-primary-runtime）
• 插件市场的本地文件（如 bundled-marketplaces）

为什么建议删除： 修改 config.toml 后，如果 .cache 中有缓存的旧 provider 配置，Codex 可能不会立即读取新配置，导致你以为改好了但实际没生效。删除后 Codex 会在下次启动时基于新的 config.toml 重新生成缓存。

删除后的影响： 首次重新启动会稍慢（需要重新生成缓存和下载运行时组件），但之后就正常了。不会丢失任何数据，配置完全以 config.toml 为准。

---

五、配置速查表

配置项	✅ 正确写法	❌ 错误写法	说明
wire_api	"responses"	"chat"	2026 年 2 月起已硬性报错
密钥方式	api_key = "sk-xxx"	env_key = "OPENAI_API_KEY"	env_key 会导致请求走 OpenAI 官方接口
base_url	"https://apinebula.com/v1"	不填或填错路径	末尾必须带 /v1
auth.json	删除	保留	保留会劫持请求到 api.openai.com
.cache / .tmp	删除	保留	缓存旧配置可能导致修改不生效
[marketplaces] / [plugins]	可删可不删	—	删了也会自动回写，不影响中转连接
Codex 版本	Desktop App	CLI（npm 安装）	本文针对桌面客户端，CLI 的操作方式不同
操作系统	Windows	Mac / Linux	路径和操作均有差异

---

参考资源

• Codex 官方 wire_api 废弃说明：https://github.com/openai/codex/discussions/7782
• Codex 官方高级配置文档：https://developers.openai.com/codex/config-advanced
• Codex 官方配置参考：https://developers.openai.com/codex/config-reference
• Codex 官方示例配置：https://developers.openai.com/codex/config-sample
• APINebula 中转站注册：https://apinebula.com/mDydKv

---

写在最后

目前网上能找到的 Codex 配置教程，绝大多数讲的是 CLI 命令行版本，或者针对 Mac 系统。专门讲解 Codex Desktop Windows 桌面版 + APINebula 的完整配置教程还非常少，而关于 auth.json 删除、api_key / env_key 区别、以及 Codex 自动回写配置行为这些细节的详细解释更是稀缺。

本文是我在 Windows 上亲自调试后整理出来的，希望能帮到同样使用 Windows + Codex Desktop + APINebula 的朋友，一步到位配置成功。

转载请注明出处。

如果觉得有用，欢迎通过我的邀请链接注册 APINebula 👇

🔗 https://apinebula.com/mDydKv

有问题欢迎在评论区交流！