如果你手头同时有 DeepSeek 的 API Key又装好了 Codex CLI大概率会遇到同一个问题两边各自为战切来切去非常别扭。我一度在手动改config.toml和重新配置环境变量之间反复折腾后来拿到 CC-Switch 这个开源切换工具才算理顺。这篇文章就是一份完整的实操记录主题集聚在一条主线上CC-Switch 下载安装、把 DeepSeek 渠道配进去、让 Codex 真正吃到 DeepSeek 的模型并配齐我在实际使用中碰到的排错经历。整个过程不复杂但有几个坑文档里往往不会提我会一并说透。先说结论这个组合解决的是API 渠道管理和 Codex 模型接入两类问题。合适的使用者包括三类人——主力是 DeepSeek 用户但想体验 Codex 交互式编码的开发者手头有多个大模型 API Key、想用一个工具统一切换的人还有正在做本地模型部署、希望 Codex 也能调用本地推理服务的折腾党。下面按我从零到跑通的顺序写。1. 先把三个工具的分工搞清楚CC-Switch、DeepSeek、Codex 各管哪一段1.1 Codex 的模型提供方机制是整个集成的地基很多人在第一步就卡住了是因为没理解 Codex CLI 本质上是个客户端套壳。Codex CLI 本身不绑定任何单一模型它读~/.codex/config.toml里的model_providers配置。这个配置项里可以声明一个或多个模型提供方provider每个 provider 有独立的base_url、env_key、wire_api等字段。你指定model xxx/yyy这种格式时Codex 就会去xxx这个 provider 定义的地址发起请求。这意味着什么意味着只要某个服务提供了兼容 OpenAI 的 HTTP 接口你都能把它作为一个 provider 塞进 Codex。DeepSeek 的 API 恰好就是这种兼容格式所以接入的本质不是破解也不是魔改而是正确地声明一个 provider 并指向 DeepSeek 的端点。理解这一点后后面所有的配置都不会再看不懂。1.2 CC-Switch 不产生模型它只生产切换动作CC-Switch 的作用是让你不用每次手动去改~/.codex/config.toml。这个工具最早解决的是多账号、多渠道、多模型之间的切换痛点。你可以在里面预置好多个渠道比如 DeepSeek、OpenAI、本地部署的模型服务每个渠道包含地址、Key、模型列表等整套配置。需要切到哪个渠道执行一下切换它就把当前生效配置写进 Codex 和 Cursor 等工具对应的配置文件里。我用下来的直观感受是它像是给配置加了一个总闸负责的是调度层DeepSeek 提供弹药Codex 充当前线执行工具。三者不冲突各管一段理解这个分工以后排错时就不会跑偏——配置没生效先查 CC-Switch 有没有写入成功模型报错则要回看 Codex 的 provider 定义和 DeepSeek 的实际返回。2. 落地前的三件套安装 CC-Switch、拿到 DeepSeek Key、备好 Codex2.1 CC-Switch 下载安装选择你平台对应的安装包CC-Switch 的官方发布渠道是 GitHub 仓库的 Releases 页面。我建议直接去仓库的 releases 区域找对应压缩包不要从第三方站点下开源工具从源头拿最稳妥。Windows 用户找带windows字样的压缩包解压后通常得到一个可执行文件放在一个固定目录下比如D:\Tools\cc-switch再把目录加入系统 PATH 环境变量。macOS 用户选darwin版本解压后建议移动到/usr/local/bin或~/bin方便终端直接调用。Linux 用户同理选对应的架构包解压后记得chmod x赋予执行权限。装完后打开终端输入cc-switch看到交互式菜单界面就说明安装成功了。这个工具是 TUI 界面键盘上下键选择、回车确认不需要记一堆命令参数对命令行新手比较友好。2.2 申请 DeepSeek API Key一个 Key 走天下DeepSeek 的 API Key 申请在它的开放平台控制台流程比很多国内厂商简单注册账号进入 API Keys 页面创建一个新 Key复制保存。这个 Key 就是 Codex 访问 DeepSeek 的凭证建议存在本地密码管理器里不要直接写进配置文件的明文位置。需要说明的是DeepSeek 的 API 地址习惯上写https://api.deepseek.com或https://api.deepseek.com/v1两种写法在多数兼容场景下都能通。Codex 配置里我建议统一使用带/v1的格式兼容匹配度更高后面第三、四节会分别演示在 CC-Switch 里和 Codex 配置里怎么填。2.3 安装并登录 Codex CLIWindows 用户多留一个心眼Codex CLI 的安装路径有两条一条是 npm 全局安装openai/codex另一条是从官方发布页拿桌面版安装包。我最早用的是 npm 路线在终端执行安装命令后把登录流程走一遍。登录这一环是很多新人栽跟头的地方。Codex CLI 依赖 OpenAI 平台的 OAuth 登录会弹出浏览器让你授权如果长时间停在登录不上或无法加载组织设置先检查是不是本地有残留的旧配置或代理变量污染了网络栈。把~/.codex目录下的旧配置备份后清掉再重试多数能解决。Windows 用户尤其要注意Codex CLI 在 Windows 下强烈依赖 WSL 环境直接在 CMD 或 PowerShell 里跑经常会冒出Windows 设置未完成之类的提示。我的做法是在 WSL 里装 Node.js 和 npm再在 WSL 内部安装 Codex这样环境最稳。3. 在 CC-Switch 里添加 DeepSeek 渠道并完成切换3.1 添加 Provider把 DeepSeek 的信息喂给 CC-Switch启动cc-switch进入交互界面后找到 Provider 管理相关的菜单项选择新增 Provider按提示依次填入名称起一个容易认的名字我习惯叫DeepSeek或DeepSeek-APIBase URL填写https://api.deepseek.com/v1API Key粘贴刚才申请的 DeepSeek Key模型列表这个步骤取决于你用的版本有的版本会让你选择模型类型DeepSeek 官方有两个核心模型一个是通用对话模型deepseek-chat一个是推理增强模型deepseek-reasoner建议两个都加进列表后面在 Codex 里想换随时换wire_api 类型这一步很关键选chat而不是responses。DeepSeek 官方 API 目前走的是 OpenAI 兼容的 chat completions 协议并不提供/responses端点选了responses后面必报错这个细节我先记账第五节展开说填完保存CC-Switch 会把这条渠道记录在它自己的配置目录里。它并不会立刻改动 Codex 的配置只是先记住这条渠道。3.2 切换渠道并验证看配置是否真正落地回到主菜单应该能看到刚才新增的 DeepSeek 渠道选择切换到该渠道或类似的指令。此时 CC-Switch 会做两件事一是把当前选中的模型提供方信息写入 Codex 的config.toml二是把 API Key 对应的环境变量名和值同步到你的 shell 环境配置里。切换完成后不要急着直接开跑先手动检查配置文件。在终端里执行codex命令的配置查看指令或者直接打开~/.codex/config.toml确认里面已经出现 DeepSeek 相关的 provider 定义。我踩过的坑是切完配置发现 Codex 还在用旧的模型名原因就是 CC-Switch 确实写了 provider但model字段还指向旧配置里的模型没有跟着变。这时候在配置文件里手动把model改成类似deepseek/deepseek-chat的格式即可。3.3 第一次连线让 Codex 真正发出请求配置验证通过后我建议先跑一个最小测试而不是直接丢大任务。进入 Codex 交互界面随便问一句你好用一句话说明你现在能正常工作如果 DeepSeek 渠道配通了你会看到模型正常返回并且回复速度明显不同于本地模拟。如果这里就报错回看第五节的排查清单大概率能命中。4. 不依赖 CC-Switch 的手动配置法直接在 Codex 里把 DeepSeek 写成 Provider4.1 一份能直接用的config.toml配置模板CC-Switch 帮你做的事本质上就是生成下面这段配置。自己手动改也完全可行而且好处是你能看清楚每一个字段的含义。打开~/.codex/config.toml在合适的位置加入以下内容model_providers { deepseek { name DeepSeek API base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat } } model deepseek/deepseek-chat字段逐一说一下model_providers是顶层配置里面可以挂多个 provider每个 provider 用花括号包裹。name只是显示名用来在日志和界面里区分。base_url是 API 端点注意必须包含/v1路径写错就 404。env_key告诉 Codex 去读取哪个环境变量获取 API Key这比直接把密钥写进 toml 要安全得多。wire_api是请求协议类型DeepSeek 用chat也就是走/chat/completions这一点在前面强调过。等号后面的model deepseek/deepseek-chat是当前生效的模型。斜杠左边是 provider 名斜杠右边是模型名。如果你在 provider 里叫它deepseek就按上面的写如果你叫别的名字对应用户要一起改。4.2 环境变量别忘配配置里写了env_key DEEPSEEK_API_KEY那么你的 shell 环境里必须存在这个变量且值是你申请的 DeepSeek Key。macOS / Linux 用户在~/.bashrc或~/.zshrc里追加export DEEPSEEK_API_KEYsk-xxxx然后source ~/.bashrc或重开终端。Windows WSL 用户在 WSL 的~/.bashrc里同样操作。配完可以先echo $DEEPSEEK_API_KEY验证变量是否能看到看到再启动 Codex。4.3 Codex 是怎么把请求发出去的理解这个流程对排查为什么改了没反应特别有帮助。当你在 Codex 里输入一句话它会先读取配置找到model指定的 provider 名字然后拼接出一个完整的请求地址。比如base_url是https://api.deepseek.com/v1wire_api是chatCodex 就会请求https://api.deepseek.com/v1/chat/completions在请求头里带上Authorization: Bearer $DEEPSEEK_API_KEY请求体里带上对话历史和模型名。整个过程和 OpenAI 客户端调用自定义接口是同一套逻辑。如果你抓包或看日志能看到 Codex 在发起请求前会先确认 provider 是否存在、环境变量是否可读、模型名和接口路径是否匹配。大多数连接失败都是这三步里的某一环出了问题。5. 高频问题排查从 local proxy failed 到上下文丢失5.1 local proxy failed while handling codex endpoint /responses 的根因和处理方案这个问题在网络热词里反复出现原因是配置走到了错误的协议分支。Codex 在部分版本里默认或倾向于使用 OpenAI 的/responses端点但 DeepSeek 的兼容层只实现了/chat/completions。当 CC-Switch 配置渠道时没有把wire_api明确设为chat时Codex 就会拿 provider 的地址去请求/responsesDeepSeek 那侧根本没有这个路由于是报出处理 codex endpoint /responses 时本地代理失败之类的错误。解决分两步打开~/.codex/config.toml检查 DeepSeek provider 定义里有没有wire_api chat没有就补上。确认base_url后面不要多斜杠、不要漏掉/v1。常见错法是写成https://api.deepseek.com//v1多出一个斜杠会让请求路径拼成/v1//chat/completions部分网关会拒绝。改完保存重启 Codex。如果还报错看是不是 CC-Switch 里定义渠道时选了错误的 wire_api 类型回 3.1 检查。5.2 当前模型不支持gpt-5.6-sol 这类残留模型名哪来的the gpt-5.6-sol model is not supported when using codex with a...这类报错经常出现在用了 CC-Switch 切换账号之后。原因不复杂Codex 配置里model字段还指向你上一个渠道的模型名。CC-Switch 帮你切换了 provider但有时为了兼容多模型会保留原model字符串导致 provider 是 DeepSeek、模型名却是 GPT 系列两边对不上。处理方案是直接改model字段为 DeepSeek 支持的模型名。如果你加了deepseek-reasoner到 provider 的模型列表想用推理模型也可以model deepseek/deepseek-reasoner另外部分版本的 Codex 会把模型列表缓存在model_providers对应 provider 的models字段里如果列表里只写了 GPT 系列没写 DeepSeek也会报不支持。手动维护时记得把列表补成[deepseek-chat, deepseek-reasoner]。CC-Switch 的用户则在渠道配置里把模型列表重新选一遍保存后再次切换。5.3 Windows 下设置未完成、登录不上这类环境问题Windows 桌面版和 WSL 版的 Codex我实测下来差异不小。Windows 桌面版安装快但登录和组织设置加载经常出问题常见表现是启动后无限转圈或提示无法加载组织设置。这多半是网络栈和本地缓存的组合问题。我的建议很直接Windows 用户优先在 WSL 里使用 CLI 版桌面版适合已经装好并能正常登录的人不适合作为新手的首选。如果在 WSL 里也登录不上先检查~/.codex/auth.json是否存在且内容非空存在但失效就删除后重新登录同时确认终端内没有残留的HTTP_PROXY、HTTPS_PROXY环境变量指向已经失效的地址。代理变量这个东西很坑看起来和登录无关实则会把 OAuth 回调带到错误地址去导致浏览器和 CLI 互相等待。5.4 切换账号后之前的对话上下文加载不了这个问题在网络热词里也有明确记录“我用 CC-Switch 切账号之前对话的上下文不能加载”。先说结论这是正常现象不是故障。Codex 的会话历史按会话 ID 存放在本地每个会话绑定的是当时发起对话时使用的模型和账号上下文。CC-Switch 切换渠道只是改了当前模型提供方并不会迁移或重建旧会话的映射。你在旧账号会话里聊过的内容不会自动出现在新渠道的对话中。想要接着上一次的对话继续正确做法是用 Codex 自带的会话恢复功能在终端里找到历史会话列表选择对应会话恢复。CC-Switch 不负责这层逻辑这是 Codex 自己的会话管理范围。如果 DeepSeek 渠道下你希望新对话承接上一段内容可以把之前的上下文导出成摘要粘贴进新对话作为背景或者直接用会话恢复功能而不是开新会话。5.5 一个容易忽视的 Key 环境变量写入问题CC-Switch 在切换渠道时有时会把 Key 写进 shell 配置文件的末尾。问题是如果你同时装了多个终端工具比如 zsh 和 bash 混用它写入的配置文件可能和你当前 Codex 实际读取的不是同一个。表现就是 CC-Switch 显示切换成功Codex 却一直报鉴权失败。排查方法在终端里echo $DEEPSEEK_API_KEY如果输出为空说明环境变量没进到你当前 shell。手动在~/.bashrc或~/.zshrc把 export 语句补上再source一次即可。6. 进阶使用与实际体会从能跑到好用6.1 把本地部署的 DeepSeek 也加进 CC-Switch如果你已经在折腾本地部署比如用 vLLM 拉起 DeepSeek 模型宿主机的推理服务往往监听http://127.0.0.1:8000/v1。这种本地服务同样能被 Codex 当 provider 使用在config.toml里加一段model_providers { deepseek_local { name Local DeepSeek (vLLM) base_url http://127.0.0.1:8000/v1 env_key LOCAL_API_KEY wire_api chat } }本地服务一般不需要真正的鉴权LOCAL_API_KEY可以设成一个任意占位字符串只要能通过 Codex 的环境变量检查即可。这样你在同一套 Codex 交互界面里既能用云端 DeepSeek也能一键切到本地推理白嫖自己显卡。CC-Switch 那边同理新增一个渠道Base URL 写本地地址Key 填占位值切换逻辑完全一致。6.2 成本敏感场景下的用法DeepSeek 的 API 成本比主流闭源模型低一截这是很多团队把它接进 Codex 的第一动力。实际使用有一个省钱技巧把deepseek-chat作为日常编码的主模型把deepseek-reasoner作为复杂问题的第二梯队。在 Codex 里遇到普通重构、补测试、写注释这类任务用deepseek-chat足够涉及复杂 bug 定位、架构方案讨论时再切deepseek-reasoner不要一个模型打天下。6.3 我在实际操作中的几条心得版本升级后重新检查wire_api。CC-Switch 和 Codex 都在快速迭代某次升级后兼容行为可能变化出现怪异错误时先回滚版本再对比比盲目改配置快得多。不要把 Key 直接写进config.toml。一旦你要分享配置片段Key 就跟着泄了。用env_key引用环境变量是更稳妥的习惯。CC-Switch 管理多个渠道后我养成了每次切换后立刻看config.toml的习惯确认model和model_providers都符合预期再开工。多花十秒能省下后面半小时的排错时间。会话恢复功能是你在多渠道之间切换时的救命稻草别只用new session一条路走到黑。最后再提一个容易被忽略的小技巧CC-Switch 写了配置后不要立刻质疑工具没生效而反复切换先确认当前 shell 是不是还残留着旧环境变量。很多时候要做的只是source一次配置或者重开一个终端窗口让环境变量重新加载。这个小动作能解决一大半切换了但没变化的困惑。