段开头引入。写的时候注意不要出现随着...的发展等套话。现在正式写。注意开头那段引言不算在“从二级标题开始”的冲突里因为和要求“不需要主标题直接从二级标题开始”不矛盾——我只是没有用标题直接把引言括起来而是直接写段落。这是常见的博客开头方式。需要保证全文至少有4个H2实际我有5个H2合格。开始。 如果你是那种习惯在终端里干活的人最近大概率没少刷到 Codex 和 DeepSeek 这两个词。Codex 是 OpenAI 推出的命令行编程智能体能直接读你项目里的代码、改文件、跑测试相当于把 AI 程序员塞进了终端DeepSeek 则是目前性价比相当凶的大模型 API编程理解力强、上下文窗口大、价格却比同档次的海外模型低一大截。把这两个接起来这件事本身不难真正烦人的是来回改配置文件、管理 API Key、在不同供应商之间切换。CC-Switch 就是为了解决这个麻烦而生的开源小工具它把 Codex、Claude Code、Cursor 这类客户端工具要连的目标模型统一管理起来点一下就能在 DeepSeek 和其他供应商之间切换。这篇文章会把 Windows、macOS、Linux 三个平台的下载安装、配置接入、验证流程完整走一遍顺手把我在实际使用中踩过的坑和一张故障速查表一并放出来给正在折腾 Codex 接入 DeepSeek 的朋友做个参考。1. 这套组合到底解决什么问题1.1 三个工具分别是什么先说 Codex。它不是聊天网页而是一个跑在命令行的 AI 编程助手。你可以在项目目录里直接输入codex 帮我修一下这个 bug它会自己读取相关文件、定位问题、修改代码甚至执行命令验证结果。默认情况下它走 OpenAI 官方模型但你完全可以通过配置把它指向任意兼容接口的模型服务。这也是它能接 DeepSeek 的前提接口长得很像换掉 base_url 和 key 就能跑。再说 DeepSeek。它对外提供的是 OpenAI 兼容的 API意味着凡是支持自定义 base_url 的客户端理论上都能接进来。编程场景下我会优先用 deepseek-chat日常对话理解和代码生成都稳如果要做复杂推理deepseek-reasoner 的表现也会更好。最关键的是价格同样级别的任务成本可能只是海外主流模型的十分之一左右适合高频使用。最后是 CC-Switch。它是一个开源的供应商切换器核心用途是把多个 AI 服务的配置集中管理。你可以在里面录入很多套供应商配置比如一套 DeepSeek、一套 OpenAI、一套本地部署的模型然后一键切换目标工具的配置。它支持 Codex、Claude Code、Cursor 等多种客户端这也是我推荐它的原因。1.2 为什么不用手动改配置没有 CC-Switch 之前我切换供应商是这么干的先打开~/.codex/config.toml把model_provider从 openai 改成 deepseek再新增一个[model_providers.deepseek]段落填上 base_url 和 env_key最后还要去 shell 里重新 export 对应的 API Key。一次两次还行次数多了就容易出问题。最常翻车的两个点一是 TOML 语法写错少了一个空格或者引号配对错误Codex 直接读不出配置二是环境变量残留之前 export 的 key 没清干净切换后 Codex 可能还是会拿着旧 key 去请求。CC-Switch 做的事情就是把这两步固化下来你只管在界面上选中某套配置它负责把配置文件写对或者通过本地代理转发请求。省掉的不只是时间还有那些毫无技术含量的低级错误。1.3 这套玩法适合谁、不适合谁适合的人群很明确想在 Codex 上低成本使用 DeepSeek 的开发者需要频繁在不同模型供应商之间切换、做对比测试的人以及团队里想让多人统一一份配置、少在环境变量上扯皮的场景。CC-Switch 的配置可以导出大家复制同一份就能保持一致。不适合的人也有。如果你就用一套固定配置装完就不会再改了那直接手写 config.toml 反而更轻快。另外如果你压根不想装图形界面工具想保持纯 CLI 工作流CC-Switch 桌面版确实不太搭你可以试试它的命令行模式但本文主要讲桌面版流程。2. 实操前的准备与核心原理2.1 需要准备的东西开始之前把这几样备齐能省掉很多中途卡壳的麻烦。项目要求说明操作系统Windows 10/11、macOS 12、主流 Linux 发行版三平台流程基本一致差异集中在安装细节Node.js18 或更高版本Codex 是 npm 包必须依赖 Node 环境终端系统自带即可Windows 建议用 PowerShellmacOS/Linux 用自带终端DeepSeek 账号开放平台注册并创建 API Key需要一点余额按量付费CC-Switch 安装包从官方 GitHub Releases 页面下载认准官方仓库别用来路不明的打包版本这里要特别提醒一句CC-Switch 的安装包虽然也可以从一些站点下载但我个人只建议从 GitHub Releases 拿。开源项目的发布机制比较透明你能看到版本号和校验信息出问题也好追溯。当然如果你所在的网络环境访问 GitHub 不太顺畅就挑一个相对空闲的时间段下载或者拜托身边朋友帮忙传一下千万别去碰那些来历不明的“加速版”“汉化版”安装包。2.2 Codex 的 provider 机制Codex 之所以能接 DeepSeek靠的是配置里的model_providers段。你不需要懂太多只要知道 Codex 允许你定义一个“模型供应商”然后告诉它用这个供应商作为默认模型来源。# ~/.codex/config.toml model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat这段配置的含义很直白model_provider指定默认使用 deepseek 这套供应商base_url告诉 Codex 请求该发到哪里env_key表示 API Key 从哪个环境变量读取wire_api则声明走 OpenAI 的 chat 格式。理解这个结构之后你就明白 CC-Switch 在背后做了什么——它只是帮你把这些内容填得又快又准。DeepSeek 的接口地址有讲究。官方文档里通常说https://api.deepseek.com或者https://api.deepseek.com/v1都行因为服务端做了兼容处理。但在 Codex 这类工具里我习惯填带/v1的版本路径语义更清晰也方便排查问题。模型名不要写错以开放平台文档为准当前主流是deepseek-chat和deepseek-reasoner。2.3 CC-Switch 的两种工作模式CC-Switch 在切换供应商时有两种工作模式搞清楚它们的区别后面出问题你才知道往哪儿排查。模式 A直接写入配置文件。选中你要用的供应商后CC-Switch 直接修改 Codex 的 config.toml把 provider 信息和默认模型都写进去。这种模式的优点是简单直接切换完就生效即使 CC-Switch 退出也不影响 Codex 正常运行。缺点是每次切换都会改动磁盘上的配置文件如果你自己也在手动调整 config.toml可能出现互相覆盖的情况。模式 B本地代理。CC-Switch 在本地启动一个小服务Codex 的配置被指向http://127.0.0.1:xxxxCC-Switch 再把请求转发给你选中的真实供应商。这种模式的好处是不管你怎么切换供应商Codex 的配置文件变动的部分很小切换动作几乎不碰配置。坏处也很明显CC-Switch 必须一直保持运行一旦它退出或崩溃Codex 会立刻报错。对比项直接写入配置本地代理是否需要常驻不需要需要切换速度秒级秒级对配置文件的影响会改写基本不改适用场景日常固定使用频繁切换供应商对比我个人的建议是日常用 DeepSeek 固定干活就选模式 A只有在需要频繁切换多家供应商横向对比时才临时开模式 B。3. 全平台安装教程3.1 Windows安装 Codex 与 CC-SwitchWindows 上的流程稍微长一点但每一步都不复杂。先装 Node.js从官网下载 LTS 版本安装包安装界面里记得勾选“Add to PATH”。这一步很多朋友会忽略装完发现命令行敲node没反应八成就是没加 PATH。Node.js 就绪后打开 PowerShell执行npm install -g openai/codex装完运行codex --version能输出版本号就说明成功了。如果提示“不是内部或外部命令”去检查一下 npm 的全局目录有没有在 PATH 里。Windows 下通常是在C:\Users\你的用户名\AppData\Roaming\npm把这个路径加进系统环境变量即可。接着装 CC-Switch。去官方 GitHub Releases 页面下载 Windows 安装包一般是-setup.exe结尾的文件双击运行按提示完成安装。打开后界面会比较简洁左侧是支持的客户端类型中间是供应商配置列表。如果你下载到的是免安装的压缩包解压后直接运行可执行文件也可以。3.2 macOS安装与 Gatekeeper 处理macOS 下我习惯先装 Homebrew然后一条命令装 Nodebrew install node npm install -g openai/codexcodex --version验证一下。CC-Switch 下载 dmg 文件双击打开把应用拖到 Applications 目录。这里有个 macOS 特有的坑第一次打开 CC-Switch 时系统大概率会提示“无法验证开发者”或者“来自已损坏的磁盘”。别慌这不是文件损坏而是 Gatekeeper 在拦截未公证的第三方应用。解决办法也很简单在终端执行sudo xattr -dr com.apple.quarantine /Applications/CC-Switch.app执行完再打开就正常了。如果你不想用命令行也可以在“系统设置 - 隐私与安全性”里选择“仍要打开”不过每次升级版本都要重复一次不如 xattr 命令干净。另外macOS 下 Codex 的配置文件位于/Users/你的用户名/.codex/config.toml后续配置和验证都以这个路径为准。建议把 API Key 写进~/.zshrcexport DEEPSEEK_API_KEYsk-你的key然后source ~/.zshrc让它生效。3.3 LinuxAppImage 与无桌面环境Linux 的流程取决于发行版。先装 Node.jsUbuntu/Debian 系可以sudo apt install nodejs npm但系统源里的 Node 版本可能偏老。如果node -v低于 18我建议用 nvm 安装新版避免 Codex 运行时报版本不兼容。Codex 依然是全局 npm 安装npm install -g openai/codexCC-Switch 在 Linux 下一般提供 AppImage 和 deb 包两种格式。AppImage 直接下载后给执行权限就能跑chmod x cc-switch-版本号-x86_64.AppImage ./cc-switch-版本号-x86_64.AppImage如果执行时报 FUSE 相关错误说明系统缺少 libfuse2sudo apt install libfuse2装完再跑。还有一种更稳的办法用./cc-switch-版本号.AppImage --appimage-extract-and-run参数运行相当于把 AppImage 先解压再执行能绕开大部分 FUSE 环境问题。如果你是跑在服务器上的无桌面环境桌面版 CC-Switch 用不了这时候要么在本地开发机上用图形界面操作后把配置同步到服务器要么用 CC-Switch 的命令行模式。注意服务器环境下 Codex 的.codex目录同样在用户主目录下配置管理的方式和桌面版没有本质区别。3.4 获取 DeepSeek API Key这是所有步骤里最简单但也最容易出错的一步。打开 DeepSeek 开放平台注册或者登录账号进入“API Keys”页面点击创建 Key。创建成功后会弹出一串以sk-开头的字符串这个 Key 只在创建时显示一次页面关闭后就再也看不到了所以一定要当场复制保存好。接下来往账号里充一点余额。DeepSeek 按量计费价格本身不高测试阶段充个几十块就够用很久。充值后到“用量”页面确认余额正常再到“模型”页面看一眼当前支持的模型标识和上下文长度。注意如果你在别处看到了什么“hermes”“harness”之类的名字别急着填进去那些不一定是你当前平台可用的模型一切以官方开放平台展示的信息为准。创建好 Key 后把它记下来后面在 CC-Switch 里配置时要填。同时也建议在 shell 配置文件里 export 一份双保险避免某个环节读不到环境变量导致莫名报错。4. 在 CC-Switch 中配置 DeepSeek 并接入 Codex4.1 新建 DeepSeek 供应商配置打开 CC-Switch进入供应商管理页面。点击“新增”或“添加配置”按钮会弹出一个表单几个关键字段要认真填。平台类型要选 Codex因为我们要给 Codex 提供配置。供应商别名可以随便填我习惯叫它DeepSeek_Prod这样在切换时一眼能认出来。BaseURL 填https://api.deepseek.com/v1注意不要带多余的空格或斜杠结尾。API Key 填刚才保存的那串sk-开头的字符串。模型名称可以留空不填也可以填deepseek-chat具体取决于你希望 CC-Switch 是否替你锁定默认模型。保存之后这组配置会出现在供应商列表里。你可以再新建一套别的供应商配置比如 OpenAI 官方或者本地模型服务这样就能在同一个界面里完成多套配置的统一管理。4.2 一键切换的底层动作配置录入后点击“应用”或“切换”按钮CC-Switch 会自动把当前选中的配置写入 Codex 的 config.toml。此时你可以手动打开配置文件确认写入结果cat ~/.codex/config.toml正常情况下会看到model_provider deepseek_prod [model_providers.deepseek_prod] name DeepSeek_Prod base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat注意env_key 默认是DEEPSEEK_API_KEY所以你在 shell 里配置的环境变量必须叫这个名字。如果你改成别的名字Codex 会根据你填的字段去寻找对应环境变量就不一定能读到了。如果 CC-Switch 用的是本地代理模式config.toml 里会有所不同base_url 变成类似http://127.0.0.1:1589的地址指向 CC-Switch 自己。这种情况下你需要确保 CC-Switch 保持运行并且选中了你想要的供应商。这时候别急着测先把 CC-Switch 的日志窗口打开方便后面排错。4.3 首次联调验证配置写好后打开一个新的终端窗口让环境变量生效然后运行codex 请介绍一下你自己并告诉我当前配置的模型名称如果一切正常Codex 会返回一段自我介绍并且中间会提到 deepseek-chat 之类的模型标识。这一步说明 Codex 已经成功通过 DeepSeek API 完成了对话。如果没有任何输出、报错或者卡住不动先别慌这里常见的情况是环境变量没有加载。重启终端再试一次或者手动执行export DEEPSEEK_API_KEYsk-你的key后重新运行。如果还是不行就去下一章的故障速查表里找对应的问题逐条排查。验证通过后你还可以试一个真实编程任务比如让 Codex 在一个临时项目里创建一个 Python 脚本读取 CSV 并统计行数。这样能确认它在实际工作负载下是否稳定毕竟光聊天没问题不代表改代码也利索。5. 故障速查表与常见问题实录5.1 高频报错对照表我把自己这段时间遇到过的、以及身边朋友问过最多的几只坑整理成了一张表。你按照提示信息去匹配大概率能直接定位问题。报错 / 现象可能原因处理方式local proxy failed while handling codex endpoint /responses. provider ...CC-Switch 本地代理模式异常、代理没启动或端口被占用检查 CC-Switch 是否仍在运行重启代理换端口必要时切到直连模式401 unauthorizedAPI Key 错误、环境变量未生效或 Key 余额不足重新复制 Key确认echo $DEEPSEEK_API_KEY有输出登录开放平台看余额model not found模型名填错用了不存在的标识以官方开放平台文档为准改成deepseek-chat或deepseek-reasonerconnection timeout/connect timed out网络无法访问 api.deepseek.com本地代理端口不通先确认直连模式能否正常代理模式下检查lsof -i:端口看监听状态codex 不是内部或外部命令npm 全局目录不在 PATH 里把 npm 全局路径加入 PATHWindows 重启终端macOS 提示“已损坏”Gatekeeper 隔离属性未清除sudo xattr -dr com.apple.quarantine /Applications/CC-Switch.appAppImage 双击无反应缺少 FUSE 运行库sudo apt install libfuse2或加--appimage-extract-and-run参数关于第一行那个local proxy failed的大坑我多说两句。这个报错之所以坑是因为前半句看起来像是 Codex 出了问题实际根源却在 CC-Switch 的代理进程上。我遇到过好几次都是因为 CC-Switch 后台崩了但界面还挂在桌面上Codex 请求发过去没人处理于是给出这个模糊的错误信息。排查思路很简单先去 CC-Switch 看日志确认代理有没有启动监听再用netstat或lsof看端口是否被占用最后在设置里换个端口重试。如果还是不行直接放弃代理模式改用直写配置稳定得多。5.2 切换供应商后旧对话上下文加载不上这个问题在热词里也经常出现通过 CC-Switch 切换账号或供应商后之前对话的上下文没法加载。原因在于 Codex 的会话文件是绑定具体模型和供应商的你切到 DeepSeek 后新会话不会自动带上旧会话的上下文。我的处理办法是在切换之前把旧对话里的关键信息手动拷贝到一段摘要里新对话开始时就着这段摘要作为起始提示。比如“之前的分析结论是 X当前项目状态是 Y我们现在继续处理 Z”。这样虽然不如代码库扫描来得全面但至少能保证核心上下文不断层。如果某些版本支持--resume参数恢复指定会话你可以先查看会话列表找到之前的会话 ID再尝试带参恢复。但跨供应商恢复并不保证每次都能成功所以最可靠的做法还是做好摘要存档。5.3 对话到达上限后如何承接上一个对话Codex 工作一段时间后上下文窗口会被撑满。这时候开新对话很容易“失忆”前面聊过的方案、改过的文件它都记不得了。有人会问有没有办法让新对话自动承接旧对话。我常用的折中方案是把“任务状态”写进一个文件。比如让 Codex 在完成每个阶段后把当前进度、待办事项、关键路径写入PROGRESS.md。新对话开始时第一句话就是“先读一下 PROGRESS.md然后继续”。这个做法在长任务里特别实用等于让模型自己给自己做笔记。另外注意如果 DeepSeek 在同一个会话里触发了上下文上限你也可以在 Codex 里使用自动压缩功能如果版本支持的话。但这种压缩会丢失部分细节重要信息还是建议靠外部文件保留一份。5.4 进阶玩法接上本地部署的 DeepSeek最后顺便说一个进阶方向。如果你用 vLLM 等方案在本地部署了 DeepSeek 模型服务通常会监听类似http://127.0.0.1:8000/v1的地址。你完全可以把这套本地服务也当成一个供应商录进 CC-Switch。操作上新增一个供应商配置平台类型还是 CodexBaseURL 填本地服务的地址API Key 随便填一个占位符即可本地服务不一定鉴权模型名填你部署时注册的模型名。切换后Codex 就会走本地推理请求延迟低数据不出本机适合敏感项目或者在外面调试模型用。我自己在 Jetson Orin 这类设备上尝试过本地部署速度和云端没办法比但用来做一些小范围代码理解任务完全够用。如果你有闲置算力这个玩法值得一试。踩过几次坑之后我自己现在的使用习惯是日常主力用直写配置模式供应商固定选 DeepSeek只有在需要横向对比多个模型时才开本地代理。Key 的备份也养成了习惯CC-Switch 里一份shell 环境变量一份两边保持一致。这套流程跑顺之后切换模型就是点两下的事我已经很久没手动改过 config.toml 了。文章里写的每个步骤都是实际验证过的你按顺序走一遍遇到问题先对速查表应该会比当年的我顺利得多。