彻底避坑指南：通过 CC Switch 将 OpenRouter 完美接入 Codex Desktop

最详尽的本地路由、网络排障及多模型切换教程

作为一名 AI 开发者 and 效率狂热者，Codex Desktop 凭借其出色的本地工作区管理和强大的插件生态，成为了我日常编写代码不可或缺的工具。然而，由于 Codex 官方默认只支持 OpenAI 官方的模型，若想使用第三方模型API（如通过 OpenRouter 接入 DeepSeek 或最新的 Claude 模型），常常会遇到重重阻碍。

直接修改 Codex 的 config.toml 将 base_url 指向 OpenRouter 官方端点是行不通的，因为 Codex 会验证 API 签名并严格检查 Provider 协议类型。经过多日摸索和反复实践，我终于找到了一条完美解决此问题的路径——利用 CC Switch 进行本地路由与协议翻译，配合 TUN 模式（虚拟网卡）代理，彻底打通了 Codex 与 OpenRouter 之间的通道。本教程将毫无保留地分享我的完整避坑配置指南，确保你能够一键成功！

第一阶段：网络与代理配置（最关键的避坑点，解决 502 错误）

很多同学在配置好 CC Switch 和 Codex 之后，向 Codex 发起请求时会直接遇到 502 Bad Gateway 错误。这是大家最容易踩的第一个大坑。

【病因分析】：当你在电脑上运行 Clash Verge 或其他代理软件并开启了“系统代理（System Proxy）”时，代理软件会劫持系统中所有的 HTTP/HTTPS 流量，包括 Codex 向本地回环地址 127.0.0.1:15721（CC Switch 本地服务端口）发起的流量。代理软件无法处理该本地协议，进而将其抛弃，导致连接断开并报出 502 错误。

【彻底解决办法（核心网络拓扑）】：以下是两种可行的解决方案，按推荐顺序排列：

• 步骤 A（推荐，首选方案）：在代理软件中，关闭系统代理 (System Proxy) 开关，同时开启 TUN 模式（虚拟网卡 / Virtual NIC）。这样，发送给本地 127.0.0.1 的流量会直接在本地直连，而 CC Switch 转发给 OpenRouter 的外网请求则会通过虚拟网卡正常代理出海。
• 步骤 B（备用方案）：如果由于工作习惯必须开启系统代理，请务必在代理软件的 Bypass（绕过）配置中加入 127.0.0.1, localhost ；或者在 Windows 系统环境变量中添加用户变量 NO_PROXY ，其值设定为127.0.0.1,localhost 。

第二阶段：CC Switch 图形界面配置

CC Switch 是一键接入本地路由的关键。首先，我们需要在 CC Switch 中开启本地路由服务并配置 OpenRouter 账户：

1. 开启本地路由总开关

进入 CC Switch 的“本地路由”配置板块，将“在主页面显示本地路由开关”、“路由总开关”全部开启。并在“路由启用”列表里勾选 Codex，以允许 CC Switch 劫持和重定向 Codex 的 API 请求。此时，本地路由状态会变更为“运行中”。

图 1：CC Switch 本地路由服务配置界面（显示为“运行中”）

2. 配置 OpenRouter 提供商及模型映射

在 CC Switch 中进入 OpenRouter 的配置页：

• 输入你在 OpenRouter 官网获取的 API Key；
• API 请求地址设置为：https://openrouter.ai/api/v1；
• 开启“需要本地路由映射”开关（这是因为 Codex 仅原生支持 OpenAI Responses 协议，CC Switch 会代理该端口并自动翻译协议）；
• 在底部的“模型映射”中添加你想调用的模型。比如我们映射了 deepseek/deepseek-v4-flash、openai/gpt-5.5 以及 openrouter/free 三个菜单项。

图 2：CC Switch 中 OpenRouter 设置与模型列表映射

【关于 model_catalog_json 的大坑排查】：CC Switch 开启后会自动生成一个名为 cc-switch-model-catalog.json 的模型目录配置文件，通常位于 .codex 根目录。但是，这个文件很容易变得过于臃肿（含有大量的system instructions，大小可达 140KB），导致 Codex 在初始化时因超时或内存解析失败而只显示一个默认模型。

解决方案：在 CC Switch 中移除未使用的无用模型，或者手动打开该 JSON 文件进行内容精简，只保留你正在映射的模型段，并在 config.toml 中重新设置 model_catalog_json 的文件名（使用相对路径即可）。

3. 确认插件安装

为了让代码协作、浏览器控制等功能正常运行，确保你勾选启用了 Codex 的核心插件（如 Documents, Spreadsheets, Chrome, Computer Use 等）：

图 3：Codex Desktop 插件管理与已安装的核心插件

第三阶段：启动与验证测试

全部配置完成后，请重新启动 Codex Desktop 客户端。

开启一个新对话，向 Codex 提问：“你是谁？你能做什么？” 检查其响应。如果能够正常输出，说明数据已经成功通过 CC Switch -> OpenRouter 获取回执。

图 4：接入 OpenRouter 模型后，Codex 的实际对话测试界面

附录：故障排查与速查表