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复制备用下载安装 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你只需要改两处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配置正确请求就会走 APINebulamarketplaces 的存在不会产生干扰。2.[plugins.documentsopenai-primary-runtime]等启用开关[plugins.documentsopenai-primary-runtime] enabled true [plugins.spreadsheetsopenai-primary-runtime] enabled true [plugins.presentationsopenai-primary-runtime] enabled true [plugins.browser-useopenai-bundled] enabled true是什么与上面的插件市场配套是每个具体插件的启用/禁用开关。documents是文档工具、spreadsheets是表格工具、presentations是 PPT 工具、browser-use是浏览器自动化工具。能不能去掉同样去掉后 Codex 会自动回写回来。这些插件本身是本地运行的 MCP 工具不依赖 OpenAI API 接口。会不会影响中转站连接不会。这些工具是本地执行的与模型 API 的请求地址无关。如果确实不想用某些插件可以将enabled改为false而不是删除整个配置块[plugins.documentsopenai-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 绘图工具的 MCPModel 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/v1Codex 仍然会忽略它直接请求api.openai.com。这就是导致下面这个经典错误的根本原因——明明配了中转地址请求却去了api.openai.com然后拿 APINebula 的密钥去访问 OpenAI 官方自然返回 401unexpected 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为什么不能写chatwire_api指定 Codex 与模型 API 通信时使用的协议格式值对应接口当前状态chat/chat/completions❌ 已废弃responses/responses✅ 唯一可用Codex 在 2025 年 12 月正式宣布废弃wire_api chat2026 年 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 Codex7..cache和.tmp文件夹为什么建议删除是什么Codex 运行时自动生成的缓存和临时文件目录。里面可能包含旧配置文件的缓存副本下载的运行时组件如codex-primary-runtime插件市场的本地文件如bundled-marketplaces为什么建议删除修改config.toml后如果.cache中有缓存的旧 provider 配置Codex 可能不会立即读取新配置导致你以为改好了但实际没生效。删除后 Codex 会在下次启动时基于新的config.toml重新生成缓存。删除后的影响首次重新启动会稍慢需要重新生成缓存和下载运行时组件但之后就正常了。不会丢失任何数据配置完全以config.toml为准。五、配置速查表配置项✅ 正确写法❌ 错误写法说明wire_apiresponseschat2026 年 2 月起已硬性报错密钥方式api_key sk-xxxenv_key OPENAI_API_KEYenv_key 会导致请求走 OpenAI 官方接口base_urlhttps://apinebula.com/v1不填或填错路径末尾必须带/v1auth.json删除保留保留会劫持请求到api.openai.com.cache/.tmp删除保留缓存旧配置可能导致修改不生效[marketplaces]/[plugins]可删可不删—删了也会自动回写不影响中转连接Codex 版本Desktop AppCLInpm 安装本文针对桌面客户端CLI 的操作方式不同操作系统WindowsMac / Linux路径和操作均有差异参考资源Codex 官方wire_api废弃说明https://github.com/openai/codex/discussions/7782Codex 官方高级配置文档https://developers.openai.com/codex/config-advancedCodex 官方配置参考https://developers.openai.com/codex/config-referenceCodex 官方示例配置https://developers.openai.com/codex/config-sampleAPINebula 中转站注册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有问题欢迎在评论区交流
Windows 版 Codex Desktop 配合 APINebula 中转站配置指南（非 CLI）
发布时间：2026/5/23 14:39:01
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复制备用下载安装 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你只需要改两处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配置正确请求就会走 APINebulamarketplaces 的存在不会产生干扰。2.[plugins.documentsopenai-primary-runtime]等启用开关[plugins.documentsopenai-primary-runtime] enabled true [plugins.spreadsheetsopenai-primary-runtime] enabled true [plugins.presentationsopenai-primary-runtime] enabled true [plugins.browser-useopenai-bundled] enabled true是什么与上面的插件市场配套是每个具体插件的启用/禁用开关。documents是文档工具、spreadsheets是表格工具、presentations是 PPT 工具、browser-use是浏览器自动化工具。能不能去掉同样去掉后 Codex 会自动回写回来。这些插件本身是本地运行的 MCP 工具不依赖 OpenAI API 接口。会不会影响中转站连接不会。这些工具是本地执行的与模型 API 的请求地址无关。如果确实不想用某些插件可以将enabled改为false而不是删除整个配置块[plugins.documentsopenai-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 绘图工具的 MCPModel 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/v1Codex 仍然会忽略它直接请求api.openai.com。这就是导致下面这个经典错误的根本原因——明明配了中转地址请求却去了api.openai.com然后拿 APINebula 的密钥去访问 OpenAI 官方自然返回 401unexpected 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为什么不能写chatwire_api指定 Codex 与模型 API 通信时使用的协议格式值对应接口当前状态chat/chat/completions❌ 已废弃responses/responses✅ 唯一可用Codex 在 2025 年 12 月正式宣布废弃wire_api chat2026 年 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 Codex7..cache和.tmp文件夹为什么建议删除是什么Codex 运行时自动生成的缓存和临时文件目录。里面可能包含旧配置文件的缓存副本下载的运行时组件如codex-primary-runtime插件市场的本地文件如bundled-marketplaces为什么建议删除修改config.toml后如果.cache中有缓存的旧 provider 配置Codex 可能不会立即读取新配置导致你以为改好了但实际没生效。删除后 Codex 会在下次启动时基于新的config.toml重新生成缓存。删除后的影响首次重新启动会稍慢需要重新生成缓存和下载运行时组件但之后就正常了。不会丢失任何数据配置完全以config.toml为准。五、配置速查表配置项✅ 正确写法❌ 错误写法说明wire_apiresponseschat2026 年 2 月起已硬性报错密钥方式api_key sk-xxxenv_key OPENAI_API_KEYenv_key 会导致请求走 OpenAI 官方接口base_urlhttps://apinebula.com/v1不填或填错路径末尾必须带/v1auth.json删除保留保留会劫持请求到api.openai.com.cache/.tmp删除保留缓存旧配置可能导致修改不生效[marketplaces]/[plugins]可删可不删—删了也会自动回写不影响中转连接Codex 版本Desktop AppCLInpm 安装本文针对桌面客户端CLI 的操作方式不同操作系统WindowsMac / Linux路径和操作均有差异参考资源Codex 官方wire_api废弃说明https://github.com/openai/codex/discussions/7782Codex 官方高级配置文档https://developers.openai.com/codex/config-advancedCodex 官方配置参考https://developers.openai.com/codex/config-referenceCodex 官方示例配置https://developers.openai.com/codex/config-sampleAPINebula 中转站注册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有问题欢迎在评论区交流
