最近身边好几个朋友都在折腾同一个组合：CC-Switch加上DeepSeek，再把Codex接进去。我自己也花了一晚上把这条路完整走通了，过程中踩了几个坑，包括那个看着很唬人的Local Proxy failed报错，以及切换渠道后旧对话上下文不加载的问题。这篇教程就是我的完整实操记录，从下载安装CC-Switch开始，到配置DeepSeek渠道，再到让Codex通过本地转发服务正常对话，每一步都写清楚为什么要这么做。适合已经用过Codex但想自己控制模型后端的开发者，也适合手里有DeepSeek API密钥但不知道怎么接入AI编程工具的新手。
1. 为什么是CC-Switch：给Codex换模型后端的最短路径
1.1 Codex默认配置的约束与DeepSeek的价值
Codex默认连接的是官方模型端点，这一点用起来很方便，但如果你想把模型后端换成DeepSeek，问题就来了：Codex本身并没有提供一个“图形化切模型”的按钮，所有模型服务商的切换都要靠改配置文件和环境变量。一次两次还好，等你手里有多个API Key、想在不同的模型之间来回对比效果时，光靠手改配置就很容易出错——改错一个Base URL，或者漏改了一个模型名，服务就起不来。
DeepSeek之所以被大家盯上，主要是两个原因：一是API定价确实有吸引力，日常对话和代码生成的成本比很多主流模型低不少；二是它提供了兼容OpenAI接口风格的访问方式，这意味着理论上只要能配置Base URL和API Key的工具，都有机会接进去。Codex正好属于这类工具。
但直接改Codex配置去连DeepSeek，并没有大家想的那么省心。Codex有自己的一套配置结构，不同版本字段还不太一样，而且你改完之后想切回别的模型，又得把配置翻出来重改一遍。这时候CC-Switch的意义就体现出来了：它把“渠道”这个事单独拎出来管理，你只需要在CC-Switch里配好DeepSeek的信息，然后在Codex里指向CC-Switch的本地地址就够了。
1.2 本地转发服务是怎么工作的
CC-Switch的核心机制其实不复杂，它是一个本地转发服务。打个比方：你家里有一堆电器，插座位置却不够，于是你拉了一个插线板，把所有电器都插在插线板上，插线板背后再决定到底接通哪一路电。CC-Switch就是这个插线板。
具体到请求链路上是这样的：Codex启动后，按配置把请求发到本机某个端口，也就是CC-Switch启动的本地服务。CC-Switch收到请求后，根据你“当前激活”的渠道，把请求头里的密钥替换成对应渠道的API Key，再把请求转发给上游服务商的真实接口，比如DeepSeek的API。上游返回响应后，CC-Switch再原样把结果回传给Codex。
这个过程里，Codex完全感知不到后端换成了DeepSeek，它只知道自己连了一个长得像OpenAI接口的服务。这也是为什么CC-Switch能同时兼容Codex、Cursor这类工具——只要这些工具支持自定义接口地址，本质上都是同一个原理。理解了这个工作机制，后面遇到问题排查起来就清楚多了：请求不成功，要么是Codex没有正确指向本地端口，要么是CC-Switch没有把请求成功转发给DeepSeek，要么是DeepSeek上游拒绝了请求。就这三层，挨个查就行。
2. CC-Switch下载与安装：从Release到跑起来
2.1 各平台版本怎么选
下载CC-Switch最靠谱的渠道是它的GitHub Release页面，搜索项目名就能找到。Release页面会同时提供多个平台的压缩包，选的时候注意区分，别下错架构。
Windows平台一般会提供exe安装包和免安装的压缩包，建议优先选官方给的安装包，省去手动配置环境变量的麻烦。macOS平台要区分Intel和Apple Silicon两种版本，M系列芯片选arm64版，Intel老机器选x64版，下反了会提示无法执行或直接报错。Linux平台一般提供tar.gz压缩包，解压后直接运行可执行文件就行。
下载完成后先解压。macOS用户如果遇到“已损坏，无法打开”的提示，通常是因为应用没有开发者签名，这是很常见的情况，你需要右键点击应用图标选择“打开”，或者到系统设置的隐私与安全性里手动允许运行。不是程序本身有问题，放心继续。Windows用户如果提示“未知发布者”，同理，属于正常现象。
2.2 首次启动必须注意的两个地方
第一次打开CC-Switch，界面信息量不大，但有两个地方一定要留意。
第一个是本地服务开关。界面上会有一个明显的启动按钮，点击后才会开启本地转发服务。服务启动后，界面上会显示当前监听的端口号，常见的是33001，但不同版本可能有差异，以你界面上看到的为准。这个端口号后面配置Codex时要反复用到，建议记下来或者截个图。我当时就是没记，回头配置Codex时又翻了一遍界面。
第二个是日志面板。很多版本默认日志区显示得不明显，或者要手动展开。一定要把它打开。CC-Switch这类的工具，日志面板是排错时最直接的线索来源：请求有没有到达本地服务、被转发到了哪个上游地址、上游返回了什么状态码，全都写在这里。后面我会讲到那个Local Proxy failed报错，不打开日志的话，你基本只能靠猜。另外，如果启动时提示端口被占用，说明本机已经有程序占用了相同端口，要么是另一个CC-Switch实例没退出，要么是其他软件占用了。直接换一个空闲端口就行，但记得后续所有配置里都要改成新端口。
3. 配置DeepSeek渠道：密钥、Base URL与模型名别填错
3.1 申请API Key时的三个细节
在CC-Switch里建DeepSeek渠道之前，你得先有一个DeepSeek的API Key。去DeepSeek的开放平台注册账号，进入API密钥管理页面创建密钥就行，整个过程五分钟。
但有三个细节我建议你注意。
第一，API Key通常只在创建时完整显示一次，页面刷新之后就再也看不到了。创建完成后立刻复制保存到本地密码管理器里，别截图完就关页面，否则后面找不回原值，只能重新生成。
第二，创建完Key之后，检查一下账户余额。DeepSeek的API按量计费，账户没有余额时，请求会被上游拒绝，具体表现可能是401或402之类的错误码。很多人配置好CC-Switch之后发现请求失败，排查半天，最后发现不是配置问题，只是余额不足，这个情况我是见过的。
第三，复制Key的时候要小心别把前后空格也复制进去。这种错误非常隐蔽，因为视觉上看起来Key是对的，但HTTP请求头里的凭证就是不合法。填到CC-Switch里之后，可以多检查一遍开头结尾有没有多余字符。
3.2 新建渠道的具体填法
打开CC-Switch，找到渠道管理或供应商管理的入口，点击新增渠道。界面上一般会要求填几个字段：渠道名称、Base URL、API Key、模型名。
渠道名称是给你自己看的，建议写清楚用途，比如“DeepSeek对话主号”“DeepSeek推理备用”，这样后面渠道多了不至于混。Base URL填DeepSeek的接口地址，一般用https://api.deepseek.com或者带/v1的兼容地址都可以，具体看你使用的CC-Switch版本要求，通常填https://api.deepseek.com/v1更稳妥。API Key填你申请到的sk开头的密钥。模型名填deepseek-chat或deepseek-reasoner，前者适合日常对话和代码生成，后者适合复杂推理场景。
填完之后保存，然后在渠道列表里把新建的DeepSeek渠道设置为“当前激活”，再启动本地转发服务。这时候CC-Switch就已经处于待命状态了，任何发到本地端口的请求都会带上你配置的DeepSeek凭证转发出去。
如果保存后渠道状态显示异常，优先检查Base URL有没有写错，以及API Key末尾有没有多余空格。这两个是最高频的填错点。
3.3 “渠道”和“账号”到底有什么区别
使用CC-Switch时，有一个概念上的区分值得搞清楚，就是“渠道”和“账号”不是一回事。
渠道本质上是“一组请求配置”，包括上游接口地址、密钥、模型名这些参数。同一个DeepSeek账号下可以建多个渠道，比如你给deepseek-chat建一个渠道，给deepseek-reasoner建另一个渠道，虽然它们用的是同一个Key，但配置不同，算两个渠道。反过来，你还可以把不同账号的Key分别建成不同渠道，方便对比不同账户的额度和使用情况。
切换渠道，只是切换了CC-Switch转发时使用的那组配置，并不等于在DeepSeek服务端切换登录身份。这一点理解到位了，后面“切换渠道后上下文不加载”的问题也就好理解了——那本来就不是CC-Switch能负责的范畴。渠道切换是配置层面的操作，跟服务端会话状态没有关系，别指望切一个渠道就能带着旧对话历史无缝衔接。
4. 把Codex CLI接到CC-Switch：完整接入步骤
4.1 先确认Codex本身是好的
在动CC-Switch之前，先花一分钟确认Codex CLI本身能正常运行。打开终端，执行codex --version，能输出版本号就说明CLI装好了。如果提示找不到命令，先按Codex官方的安装步骤装好再说。
这一步看起来多余，但实际排错时非常关键。很多人配置完CC-Switch后一跑Codex发现报错，就以为是CC-Switch的问题，结果查了半天发现Codex本身就没装对，或者版本过旧导致命令行参数都不一致。先确认基础环境是好的，后面出了问题才能把范围缩到CC-Switch这一层。
如果你需要用配置文件而不是环境变量来指定后端，Codex的配置文件一般位于用户目录下，不同版本有差异，但核心配置思路是相通的。大致结构是这样的：
model = "deepseek-chat" [model_providers.deepseek] name = "DeepSeek" base_url = "http://127.0.0.1:33001/v1" env_key = "DEEPSEEK_API_KEY"这里把模型指定为deepseek-chat，把base_url指向CC-Switch的本地端口。注意，具体字段名在不同Codex版本里可能有细微差别，比如model_provider的写法，或者是否支持env_key，请以你当前版本支持的写法为准。核心思路就是把模型的接口地址指向本地，让CC-Switch去实际转发。
4.2 环境变量指向本地端口
如果你不想深度修改Codex配置文件，用环境变量也是一种很直接的方式。在终端里设置两个环境变量，然后启动Codex：
export OPENAI_BASE_URL=http://127.0.0.1:33001/v1 export OPENAI_API_KEY=sk-local-placeholder codex这里OPENAI_API_KEY随便填一个占位符就行，因为真正的DeepSeek密钥已经在CC-Switch的渠道配置里了，本地端点并不关心外部传入的Key是什么。OPENAI_BASE_URL则必须指向CC-Switch监听的那个端口，如果前面你换了端口，这里的地址要跟着改。
设置好之后，你在Codex里发起的请求就会先到CC-Switch的本地端口，然后由CC-Switch转发给DeepSeek。这一步成功的话，你会在CC-Switch的日志面板里看到请求记录。
有一点要提醒：环境变量的方式只在当前终端会话里生效。你关掉这个终端再开一个新的，环境变量就没了，Codex又会回到默认配置。想固定的话，就把环境变量写进Codex的配置文件里，或者在系统环境变量里永久配置。这个看个人习惯，我是更推荐配置文件的方式，一劳永逸。
4.3 用curl快速验证链路是否畅通
配置好一切之后，先别急着打开Codex聊天，先用curl直接测一下CC-Switch的本地端点，把整个链路分成两段来验证。
一段是“Codex到CC-Switch”，另一段是“CC-Switch到DeepSeek”。curl命令可以直接打本地端点：
curl http://127.0.0.1:33001/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"ping"}]}'如果CC-Switch转发正常，你会收到一个包含响应内容的JSON。如果这一层不通，说明问题出在CC-Switch本身或者DeepSeek上游，跟Codex没关系。如果这一层通了，但Codex里依然报错，那问题就集中在Codex的配置上——多半是环境变量没生效，或者配置文件里base_url指错了。
这个curl验证法我每次配置都会用，因为它能把“转发服务的问题”和“Codex配置的问题”清晰分开，排查效率翻倍。尤其是遇到那种比较笼统的报错信息时，先用curl确认本地转发是好的，你就知道不需要动CC-Switch了，安心去查Codex侧就行。
4.4 完整对话验证
最后一步，实际跟Codex对话一次。启动Codex后，输入一句简单的请求，比如“用一句话说明你是如何运行的”，然后观察CC-Switch的日志面板。
正常流程下，日志里会出现一条请求记录，显示请求被转发到DeepSeek的接口，并且返回状态码200。如果你能看到这个，说明整条链路已经通了：Codex到CC-Switch，CC-Switch到DeepSeek，全部正常。
如果Codex返回超时或者报错，但CC-Switch日志里完全没有记录，说明请求根本没到达本地端口，重点检查Codex的配置指向。如果CC-Switch日志里有记录但状态码是错误码，说明请求到了，但DeepSeek侧拒绝了，按下一节里的错误码对照表逐项排查。
5. 两个高频问题的排查全过程
5.1 Local Proxy failed while handling codex endpoint /responses 到底在说什么
这个报错可能是我最近被问到最多的一个。完整报错通常长得像这样：CC-Switch local proxy failed while handling codex endpoint /responses. provider...。第一次看到的时候，确实容易被长串英文唬住，但只要拆开看就清楚了。
这个报错的意思是：CC-Switch的本地转发模块在处理来自Codex的/responses接口请求时，内部处理失败了。注意这里的/responses是Codex新版本使用的接口路径，和早期的/chat/completions不太一样。所以这个报错本质上是“转发服务在处理新版接口时出了问题”。
我排查这个报错时一般按下面这个顺序走：
第一步，看CC-Switch日志。日志里通常会显示更具体的信息，比如转发到上游时返回的HTTP状态码。如果看到401或402，那就是DeepSeek的Key无效或余额不足，优先去平台查一下密钥和账户余额。如果看到404，一般就是Base URL或请求路径不对，检查一下渠道配置里有没有漏写/v1，或者填了一个不存在的接口路径。
第二步，升级CC-Switch版本。这个原因特别容易被忽略。不同CC-Switch版本对新版Codex的/responses接口支持程度不一样，老版本可能需要用/chat/completions路径，新版Codex默认发/responses，两者接不上就会报这个错。去Release页面看看有没有更新版本，升级完通常就好了。
第三步，用我前面说的curl法直连DeepSeek官方API。如果curl直接打DeepSeek的接口没问题，但打CC-Switch本地端口出问题，说明问题在CC-Switch的转换逻辑或配置里。如果连官方API都出错，问题就在上游，重点查Key和模型名。
第四步，检查模型名。确保Codex配置文件里的模型名是DeepSeek支持的deepseek-chat或deepseek-reasoner，别填什么别的名字。DeepSeek侧不认的模型名，上游会返回一个个明确的错误。
为了看着方便，我把常见的错误码和排查方向整理成了表格，排错时可以直接对照：
| 错误码或现象 | 对应原因 | 排查动作 |
|---|---|---|
| 401 Unauthorized | API Key无效或填写错误 | 确认Key没有多余空格，重新生成Key |
| 402 Payment Required | 账户余额不足 | 前往DeepSeek平台充值 |
| 404 Not Found | Base URL或路径不对 | 检查是否漏写/v1，确认接口地址正确 |
| 400 Bad Request | 模型名不支持或请求格式有误 | 确认模型名为deepseek-chat或deepseek-reasoner |
| 超时或连接拒绝 | 端口配置不一致或服务未启动 | 确认CC-Switch服务启动，Codex端口指向一致 |
| 版本兼容性问题 | CC-Switch版本过旧 | 升级到Release页面的最新版本 |
5.2 切换渠道后旧对话上下文不加载，有没有办法
这个问题也是高频提问，具体症状是：在CC-Switch里切换了渠道之后，回到Codex或者ChatGPT类的客户端，发现之前对话的上下文加载不出来，或者新会话完全接不上旧对话的内容。
先说结论：这其实是符合预期的表现，不是CC-Switch出了bug。
上下文不加载的原因要从两个层面看。第一个层面，Codex这类工具会把对话历史以会话记录的形式保存在本地，但会话记录和渠道配置往往是绑定的。也就是说，你切了渠道之后，客户端可能识别为“这是一个新会话”，自然不会再加载旧会话的上下文。第二个层面，模型服务端的上下文是跟着请求走的，每次请求带多少历史消息，由客户端在请求里携带。CC-Switch切换渠道只是改变了转发目标和密钥，它没有能力、也没有义务去迁移之前对话里的历史内容。
那有没有办法解决？我的建议是分为两种场景。
如果你只是临时对比不同渠道的效果，就不要频繁切换。一次性能对比完就对比完，切换之后就接受旧上下文丢失的现实。如果你确实需要延续同一个任务，切换前把当前对话里的关键信息复制出来，切换后作为新的输入粘贴回去，或者手动在新会话里把背景和需求重新描述一遍。这个方法不优雅，但很实用。
还有一个小提醒：如果你用CC-Switch切换的是同一个DeepSeek账号下的不同渠道，也就是同一个Key，旧会话能不能恢复取决于客户端的会话管理逻辑，不同工具有差异。如果工具把会话文件放在本地且不区分渠道，那么切回来后可能还能看到历史；如果它会按配置维度隔离会话，那新会话依然看不到旧历史。这个没办法一概而论，建议你固定用一个主要渠道做长对话，别依赖切换去延续上下文。
6. 多渠道维护与工具联动经验
6.1 多个渠道多组Key怎么管理不混乱
当CC-Switch里的渠道多起来之后，最怕的就是自己都分不清哪个渠道是干什么用的。我的经验是命名前缀，比如“DS-对话”“DS-推理”“DS-备胎”，一眼就能看清用途。别贪图方便直接叫“渠道1”“渠道2”，等你有三四个渠道的时候，这种名字基本等于没写。
另外，养成定期检查API额度的习惯。DeepSeek的余额消耗在日常使用中不算快，但长时间不管也可能悄悄用完。高频率使用Codex做代码生成的话，我建议每周看一眼账户余额和消费明细，别等到上游返回402了才手忙脚乱。CC-Switch本身不会帮你检查余额，这个工作是独立于渠道配置之外的。
还有一点，备份配置文件。CC-Switch的渠道配置一般保存在本地配置文件中，升级或迁移设备之前把配置文件复制一份出来。我遇到过升级后配置读取异常的情况，有备份的话恢复起来就是几分钟的事，没备份就得重新一个个填渠道，很烦。
6.2 CC-Switch接Cursor等其他工具的注意点
CC-Switch的本地转发服务兼容OpenAI风格的接口，所以理论上任何支持自定义Base URL的AI编程工具都能接，不只是Codex。Cursor这类工具一样可以在设置里填本地地址，然后把模型指向CC-Switch，实际效果和Codex接入是同一个套路。
但有两个注意点。第一，同一时间要确保只有一个CC-Switch实例在运行。如果你已经开了一个实例，又去启动第二个，第二个会报端口被占用。别同时开两个实例去接不同工具，这不会提升效率，反而会互相干扰。第二，多个工具可以共用同一个本地转发端口，这没问题，因为CC-Switch本身支持并发请求，处理多个客户端的请求是它的基本能力。前提是你的机器性能跟得上，以及你的DeepSeek账户额度够用。
另外，接Cursor时，模型名的填写要特别注意。Cursor有自己的模型选择逻辑，可能会把模型名包装成自己的一套命名。如果你在CC-Switch里配置了模型名，在Cursor侧要确保最终发出来的请求里带的模型名能对上，否则上游照样回400。这个问题的表现通常是“能连上但生成不了内容”，排查起来容易绕弯路，卡住时可以抓一下CC-Switch的日志，看看实际转发时带的是什么模型名，一眼就知道问题在哪。
6.3 日志常开，排错事半功倍
最后说一个我自己的小习惯：CC-Switch的日志面板保持常开状态，不要随手关掉。很多时候报错信息写得相当模糊，单看界面根本不知道问题出在哪个环节。但你打开日志就会发现，请求转发去了哪个地址、返回了什么状态码、耗时多少、错误详情是什么，全都一行行写得清清楚楚。
我最近几次排查，百分之八十是靠日志里那几行字定位的。先确认请求有没有到达本地端口，再确认上游返回了什么状态码，问题范围一下子就从“完全没头绪”缩小到“某一个具体配置项”。配置CC-Switch这类工具，日志不是可看可不看的辅助功能，它就是最重要的排错入口。别嫌它占界面，真正出问题的时候，你会感激这个面板的存在。
