CC Switch 本地路由指南：让 Codex 用 DeepSeek 等 Chat Completions 服务商

本文基于 CC Switch 官方指南 Codex × DeepSeek 路由指南（适用于 CC Switch 3.19.1 及以上版本），完整覆盖"如何判断自己是否需要本地路由、如何配置上游格式、如何启用路由接管"的全部操作步骤，并结合仓库中预设定义（codexProviderPresets.ts）与 Rust 端转发器源码（forwarder.rs）展开讲解底层协议转换链路。读完后你能够：独立判断某 Codex 提供商是否需要路由接管，为 DeepSeek、Kimi、智谱 GLM 等 Chat 格式服务商完成端到端配置，并理解请求在本地路由内部的改写过程。

一、先判断：你的提供商是否还需要这份指南

CC Switch 3.19.1 起，DeepSeek 预设改为直连原生 Responses API，不再需要本地路由。但路由转换链路并没有废弃——它仍是使用 deepseek-v4-pro 的唯一途径，对 3.19.1 之前保存的旧提供商依然生效，也是 Kimi、智谱 GLM 等 Chat 格式服务商的必经之路。

唯一可靠的判断方法：查看 Codex 提供商卡片上的 Needs Routing 徽标。

• 有 Needs Routing 徽标 → 该提供商是 Chat 格式，整份指南适用；
• 无徽标 → 已直连原生 Responses，路由步骤对它没有意义，直接使用即可；
• 有 No Routing Support 徽标 → 这是官方提供商，CC Switch 会阻止其走本地路由（详见文末 FAQ）。

徽标由保存提供商时记录的 API 格式（meta.apiFormat）驱动，因此升级 CC Switch 不会改变已有提供商的行为。就 DeepSeek 而言，升级到 3.19.1 后共有三种情况：

你的情况	是否需要路由	说明
3.19.1 之前保存的 DeepSeek 提供商	需要，徽标仍显示	预设变更只影响新建提供商；已保存的配置保持不变。迁移到直连见下文"转换既有 DeepSeek 提供商"
3.19.1 之后由预设创建的 DeepSeek 提供商	不需要	直连 api.deepseek.com，并获取 DeepSeek 官方模型目录
想使用 deepseek-v4-pro	需要	DeepSeek 尚未对该模型开放 Codex 集成，直连会失败，必须走 Chat + 路由

除 DeepSeek 外，Kimi、智谱 GLM、SiliconFlow、ModelScope 等大量服务商仍是 Chat 格式，本指南对它们同样完整适用——把下文出现的 DeepSeek 替换成对应预设即可。

从源码结构看，Needs Routing 徽标的判定逻辑集中在 ProviderCard.tsx，而 constants.ts 还维护了一份托管 OAuth 提供商类型清单（codex_oauth、xai_oauth 等）：这类提供商的真实凭据由本地代理按请求注入，无论上游是否需要格式转换，都必须开启路由接管才能通过认证。新增此类预设时只需把 providerType 加入该数组，needsRouting 判定即自动覆盖。

二、为什么需要本地路由

新版 Codex CLI 面向 OpenAI Responses API 发起请求，而许多提供商暴露的是 OpenAI Chat Completions 形态（通常是 /chat/completions）。两种协议在请求体、流式事件、响应结构上各不相同。把 Chat 端点直接写进 Codex 配置，常见后果是模型列表错误、404/400 请求，或 Codex 无法正确解析的流式响应。

CC Switch 的解法是：让 Codex 始终与本地路由通信、继续发送 Responses API 请求。路由检测到活动提供商是 Chat 格式后，将请求改写为 Chat Completions 发给上游，再把 Chat 响应（JSON 或 SSE 流）转回 Responses 形态供 Codex 消费。整条链路共四步：

1. 开启 Codex 路由后，本地配置被写入 http://127.0.0.1:15721/v1，同时保留 wire_api = "responses"；
2. 提供商的 meta.apiFormat = "openai_chat" 告知路由：真实上游是 Chat Completions；
3. 路由把 /responses 或 /v1/responses 改写为 /chat/completions，并把 Responses 请求体转换为 Chat 请求体；
4. 上游响应后，路由把 Chat JSON/SSE 流转回 Responses JSON/SSE。

对于原生 Responses 提供商（如当前版本的 DeepSeek 预设），第 2～4 步完全不会发生：请求不做任何格式改写，直达上游。

这一链路在 Rust 后端有直接对应。forwarder.rs 中通过 should_convert_codex_responses_to_chat 判定是否需要转换，命中后在 L1536 附近调用 transform_codex_chat::responses_to_chat_completions_with_reasoning 完成请求体改写；handlers.rs 的 handle_chat_completions 则处理 Chat 上游返回后的反向转换。若上游 base URL 已写成完整端点（base_url_is_full_endpoint 检查，见 forwarder.rs#L1474），路由会做相应归一化——这也是 FAQ 中"base URL 不要带 /chat/completions"这一要求能生效的原因。

三、前置条件

准备以下三样东西：

• 已安装并能正常启动的 CC Switch；
• 已安装并至少运行过一次 Codex CLI，使 ~/.codex/config.toml 目录结构存在；
• 目标提供商的 API key。

以 DeepSeek 为例，其官方文档列出的 OpenAI 兼容 base URL 为 https://api.deepseek.com（其他提供商常用带 /v1 后缀或更长路径的 base URL，例如智谱 GLM 使用 https://open.bigmodel.cn/api/coding/paas/v4），Chat API 路径为 /chat/completions。CC Switch 的预设已内置这些细节，因此优先使用预设，不要手工拼端点路径。仓库中 DeepSeek 预设的完整定义见 codexProviderPresets.ts#L1105-L1142：

• apiFormat: "openai_responses"——预设直连原生 Responses，无需路由转换；
• 模型目录包含 deepseek-v4-flash 与 deepseek-v4-pro 两行，contextWindow 均为 1048576，reasoningLevels 为 ["low", "high", "max"]；
• 预设注释明确说明：后端按 deepseek.com host 直接镜像官方 models.json（含 freeform apply_patch、GPT-5 harness 与 low/high/max 思考档），要求 Codex CLI 0.144.0 及以上。

四、Step 1：添加 Codex 提供商

打开 CC Switch，切换到顶层 Codex 标签页，点击右上角加号按钮添加提供商。

使用预设（推荐）

在预设列表中选择提供商，填入 API key，保存。预设已携带请求 base URL、默认模型和模型菜单，并替你设置好上游格式；保存 Chat 格式预设后，其卡片上会出现 Needs Routing 徽标。思考/推理参数由预设预配置，无需手动填写。

使用自定义配置

填入提供商文档给出的 API key 与 base URL，然后展开表单底部的 Advanced Options，把 Upstream Format 设为 Chat Completions (routing required)。下拉框共三个选项：

选项	含义
Responses (native)	上游原生支持 Responses API；直连，无转换、无路由
Chat Completions (routing required)	本指南覆盖的情况；上游只暴露 /chat/completions
Anthropic Messages (routing required)	上游仅提供原生 Anthropic 协议，路由同样会做转换

只有 Responses (native) 可以在没有路由接管的情况下工作，其余两项都必须开启路由。对自定义提供商，CC Switch 会从提供商名称和地址推断思考参数；只有推断错误时才需要展开 Reasoning Capability 手动覆盖。

转换既有的 DeepSeek 提供商

从 Chat 迁移到直连：只需把 Upstream Format 改为 Responses (native)，无需删除重建。下次切换到该提供商时，CC Switch 识别 deepseek.com 地址并应用 DeepSeek 官方模型目录，freeform apply_patch、GPT-5 harness、low/high/max 推理档与 web_search 均照常生效。

一个小差异：提供商自身保存的模型行优先于官方目录，3.19.1 之前存储的 1000000 上下文窗口会覆盖官方声明的 1048576，让你少用 4 万多 token。介意的话，打开 Advanced Options → Model Mapping，把该行 Context Window 改为 1048576；或者直接从预设新建一个提供商。

反过来，要使用 deepseek-v4-pro，则把 Upstream Format 改回 Chat Completions (routing required)。

另注意：直连所用的官方模型目录要求 Codex CLI 0.144.0 及以上（其携带的 freeform apply_patch 注册需要该版本），CC Switch 不会替你校验这一点。生成的目录文件会增大到约 75 KB，因为包含完整的 GPT-5 harness 文本。

五、Step 2：启用本地路由并接管 Codex

进入设置中的 Routing 页面，展开 Local Routing，完成两个开关：

1. 打开 Routing Master Switch 启动本地服务，默认地址为 127.0.0.1:15721；
2. 打开 Routing Enabled 下的 Codex。如果只希望 Codex 走本地路由，可以保持 Claude 和 Gemini 关闭。

路由启用后，CC Switch 把 Codex 的活动配置指向本地路由，并用占位符管理认证。真实 API key 保留在 CC Switch 提供商配置中，由本地路由在转发时注入，因此你不需要在 Codex 活动配置中暴露密钥。

六、Step 3：切换提供商并重启 Codex

回到 Codex 提供商列表，点击目标提供商的 Enable。如果它带有 Needs Routing 标记而路由服务未运行，CC Switch 会弹出提示说明需要先启动路由服务。

切换后重启当前 Codex 终端会话。之所以推荐重启，因为：

• Codex 进程可能已读取旧的 config.toml；
• model_catalog_json 生成后，/model 菜单通常需要新进程才会刷新。

在 Codex 内用 /model 确认当前模型来自对应预设，再发一条小测试提示词，确认路由面板中请求数增加，或使用/请求日志中出现了对应的 Codex 请求。

七、直连后用量归因方式会变化

单独强调这一点：一旦提供商直连，其请求不再经过本地路由，按请求计的代理用量统计就无法看到它们。

用量本身不会丢失——Codex 会话日志导入仍会记录——但该路径不携带提供商身份：所有未走本地代理的 Codex 用量会被归入同一条名为 Codex (Session) 的条目。要区分它们，看模型：每条用量记录保留各自的模型 id，用量面板的 Model Stats 表按模型列出，成本与 token 数字分开统计。

如果确实需要按提供商对账（例如对比同一模型在多个聚合商上的表现），就把 Upstream Format 保持在 Chat，并保留路由接管开启。

八、常见问题（FAQ）

Codex 报 404 或找不到 /responses 通常是 Codex 路由未启用，或把上游 Chat base URL 手动直接写进了 Codex。检查 ~/.codex/config.toml 是否指向 http://127.0.0.1:15721/v1。

上游报 404 使用内置预设时，先确认活动提供商确实来自预设、且 Codex 路由已启用。只有自定义提供商需要额外检查 base URL：它应是提供商文档给出的服务端点，而不是带 /chat/completions 的完整端点路径。

切换到 deepseek-v4-pro 上游失败 DeepSeek 尚未对该模型开放 Codex 集成。把该提供商的 Upstream Format 改回 Chat Completions (routing required) 并启用路由接管——这正是 3.19.1 之前 DeepSeek 的通行路径，路由的 Responses-to-Chat 转换会像往常一样服务 pro。或者改用 deepseek-v4-flash，它是预设默认且不受影响。

/model 不显示提供商的模型 保存提供商后重启 Codex。CC Switch 会生成 cc-switch-model-catalog.json 并将其路径写入 model_catalog_json，但运行中的 Codex 进程可能不会热加载模型目录。另外，Codex 应用当前不支持多模型选择，默认使用第一个配置的模型。

路由已启用，但请求仍去了错误的提供商 确认三处状态一致：Codex 标签页下的当前提供商正确；本地路由服务正在运行；Routing Enabled 下的 Codex 开关已打开。

能否通过本地路由使用官方 OpenAI Codex 账号？ 不推荐。本地路由接管启用期间，CC Switch 会阻止切换到官方提供商，因为通过代理访问官方 API 可能产生账号风险。路由主要面向第三方、聚合商或协议转换场景。

九、延伸阅读

• CC Switch 用户手册：添加提供商
• CC Switch 用户手册：代理服务
• CC Switch 用户手册：应用路由
• 同系列指南：Codex × Claude 路由、Codex × Kimi 路由、Codex 官方账号保留指南