Windows 版 Codex Desktop 配合 APINebula 中转站配置指南（非 CLI）
本文针对Codex Desktop（桌面客户端），不是 Codex CLI（命令行版本）。
本文针对Windows 系统，Mac 用户的配置文件路径和部分操作不同，请勿直接套用。目前网上能找到的 Codex 第三方 API 配置教程，绝大多数针对的是 CLI 命令行版本或 Mac 系统。专门讲解Windows 桌面版 + APINebula的完整配置说明还很少，尤其是关于
auth.json删除、api_key与env_key区别、以及 Codex 自动回写配置等关键细节——本文会把这些都讲清楚。
前置准备
注册 APINebula 获取 API Key
👉 https://apinebula.com/mDydKv- 注册后在后台创建 API Key，格式为
sk-xxx，复制备用
- 注册后在后台创建 API Key，格式为
下载安装 Codex Desktop
- 从 OpenAI Codex 官方页面 下载 Windows 版安装包（
.exe文件），双击安装即可 - ⚠️ 注意：是下载Desktop App，不是通过 npm 安装 CLI 命令行版本
- 从 OpenAI Codex 官方页面 下载 Windows 版安装包（
一、配置文件在哪里？
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你只需要改两处：
model— 换成你在 APINebula 上实际使用的模型名称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 = false3.[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_keyvsenv_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
有问题欢迎在评论区交流！
