近年来围绕 Codex CLI 的玩法越来越热闹但很多人在 Windows 下卡在了环境配置这一步。我也算是在终端里折腾 AI 工具比较早的一批用户从 ChatGPT 官方订阅到各类中转 API 都试过最后在 Windows 上稳定跑起来的组合是 Codex CLI CC Switch DeepSeek API。这篇文章就把我自己的完整配置过程、踩过的坑、还有那些看得人头皮发麻的报错信息一次性讲透。不管你是刚听说 Codex CLI 的新手还是已经被各种 local proxy 报错折磨半天的老哥这篇教程应该都能给你省下不少时间。1. 整体思路为什么要用 CC Switch 中转 DeepSeek API 来驱动 Codex CLI先把这个组合的逻辑理清楚。Codex CLI 本身是 OpenAI 出的终端编程助手设计上默认对接的是 OpenAI 官方接口。但在实际使用中你有两个绕不开的现实问题一是官方 API 的计费模式和模型版本未必符合所有人的预算与需求二是总有一些场景需要切换不同的模型供应商来做对比比如我想从 ChatGPT 的模型切到 DeepSeek 的模型如果每次都去改 Codex CLI 的配置文件麻烦得很。CC Switch 解决的就是这个切换的痛点它本质是一个本地代理工具在终端工具和 API 服务之间加了一层中转让你可以随时切换 Provider 而不用反复修改 Codex CLI 的配置。简单来说数据流向是这样的你在 Codex CLI 里输指令Codex CLI 按配置发给本地代理CC Switch 起的服务CC Switch 根据你当前选中的 Provider 配置把请求转发给对应的远程 API 服务商也就是 DeepSeek 的接口。对 Codex CLI 而言它只认本地这个代理地址完全不知道自己背后连的到底是谁。这个思路的好处很明显Codex CLI 不用动配置只写一次后续想换模型就在 CC Switch 的界面里点一下就好。我最初在 Windows 上折腾的时候其实也想过更直接的办法比如把 DeepSeek 的 API Key 直接写进 Codex CLI 的配置文件。但后来发现 DeepSeek 的接口路径和 OpenAI 能完全对齐的部分有限某些请求格式和鉴权方式存在差异。直接用替代方案容易遇到鉴权失败或者模型名对不上的问题。而 CC Switch 这类工具已经帮你把这些差异处理好了它模拟出一个与 OpenAI 兼容的接口格式内部再做协议转换这样一来 Codex CLI 就无需任何感知。这也是我为什么强烈建议你这么组合的原因——不是不能直连而是直连的坑远比你想象的多。用生活化的方式理解的话Codex CLI 是一个只吃西餐的客人DeepSeek API 是一个只做中餐的厨房CC Switch 就是那个两端都懂的翻译兼外卖员。它把西餐菜单翻译给中餐厨房又把做好的菜按西餐礼仪端上桌。没有这个中间层你硬把中餐塞给客人客人不是觉得餐具不对就是觉得上菜流程有问题。我花了很长时间才彻底想明白这一层逻辑想明白之后很多配置上的疑惑就迎刃而解了。在 Windows 下这个方案还有一个额外的好处CC Switch 提供了安装版和便携版两种形态便携版不用装服务、不写注册表对系统环境影响最小。对于经常要在不同机器上折腾开发环境的人而言便携版真的很友好。我自己的主力机用的是安装版备用笔记本用便携版两者在使用体验上几乎没有差别只是安装版的右键菜单和文件关联更顺手一些。2. 环境准备Windows 下这块拼图到底需要哪些组件动手之前先把需要的组件列清楚。这个方案的完整技术栈包括Node.js 运行时、Codex CLI 本体、CC Switch 工具、DeepSeek API Key。四样东西缺一不可而且它们的安装顺序也有讲究装反了容易出各种莫名其妙的问题。2.1 Node.js 环境的安装细节Codex CLI 官方推荐通过 npm 全局安装而 npm 是 Node.js 自带的包管理器所以第一步一定是装 Node.js。Windows 下我建议直接去 Node.js 官网下载 LTS 版本的安装包不要选 Current 版本。Current 版本功能新但某些依赖在 Windows 下可能存在兼容性问题而 LTS 版本经过了更充分的测试稳定压倒一切。安装的时候一路 Next 就行但有一个细节值得注意安装向导里有一个Add to PATH的选项默认是勾选的千万别取消否则后面在终端里执行 npm 命令会提示找不到命令。装完之后验证是否成功打开 PowerShell 或者 CMD输入node -v npm -v如果能看到版本号输出说明 Node.js 环境已经就绪。我遇到过不少人在这一步卡住后来发现是系统里有旧版本的 Node.js 残留PATH 环境变量里指到了旧的安装目录。如果出现这种情况最简单的处理方式是彻底卸载 Node.js 后再重装而不是手动去改 PATH手动改容易越改越乱。2.2 Codex CLI 的安装方式对比Codex CLI 的安装有几种途径我重点说两种npm 全局安装和桌面版安装。npm 安装的命令很简单npm install -g openai/codex装完执行codex --version验证。如果在终端里能正确输出版本号说明安装成功。桌面版则是 OpenAI 官方提供的图形界面版本适合不喜欢在终端里操作的人。但桌面版在 Windows 下的表现目前还是不如终端版稳定某些界面交互偶尔会有渲染问题。我的建议是如果你本身就是开发者经常用终端直接上 npm 版如果你只是想体验一下不打算重度使用桌面版也够用。不过后面配置代理的方式略有不同教程里我会以终端版为主来演示。安装完后Codex CLI 会在用户目录下生成配置目录默认位置是C:\Users\你的用户名\.codex。这个目录下有一个config.toml文件这是 Codex CLI 的核心配置文件。后面我们配置本地代理地址改的就是这个文件。2.3 CC Switch 的下载与安装选型CC Switch 的获取渠道这里要提醒一句不要去搜索引擎随便搜一个下载站那些第三方站点捆绑的风险比较高。最好去它的 GitHub Releases 页面找官方发布的压缩包。下载的时候会看到两个版本安装版Setup和便携版Portable。安装版会写注册表、创建快捷方式优点是干净省心便携版是免安装的解压就能用适合放在移动硬盘里随身携带。我自己实际用下来两个版本的核心功能完全一致只是便携版第一次启动时 Windows Defender 可能会多问一句毕竟没有签名信息的 exe 文件经常会被安全软件扫描。遇到这种情况确认是从官方渠道下载的放行就好。启动 CC Switch 后它会在系统托盘区显示一个小图标主界面是一个简洁的控制台。第一次启动时它会自动在本地起一个代理服务默认端口一般是 1081 或某个随机高位端口具体可以在设置里看。记住这个端口号后面配置 Codex CLI 的时候要用到所以启动后第一件事就是去设置里确认一下端口避免后面搞混。2.4 DeepSeek API Key 的申请流程DeepSeek 的 API Key 申请是在 DeepSeek 开放平台上完成的。注册账号、实名认证之后在控制台的API Keys页面创建一个新的 Key。创建的时候可以给 Key 起个名字方便区分用途。创建成功后页面会显示一次完整的 Key 字符串务必马上复制保存到本地因为关掉页面之后就看不到了只能重新创建新的 Key。这里还有一个费用相关的问题。DeepSeek API 是按 token 计费的新用户一般会有一定额度的免费赠送用完之后需要充值才能继续调用。我个人的经验是如果只是日常写点脚本、做代码补全消耗量不大充小额就够用很久。不要一上来就充大额先用完免费的额度实测一下自己的用量再说。3. 核心原理CC Switch 的本地代理机制与 Codex CLI 的对接方式很多人在配置过程中失败就是因为不理解本地代理的工作原理。这里我详细拆解一下理解了原理后面那些报错信息在你眼里就不再是乱码了。3.1 本地代理的工作机制CC Switch 启动后在你的机器上监听一个本地端口比如http://127.0.0.1:1081。Codex CLI 配置里的base_url指到这个地址那么 Codex CLI 发出的所有 API 请求都会先到这个本地代理。CC Switch 接收到请求后根据你当前选中的 Provider 配置决定把请求转发到哪里。如果你选的是 DeepSeek那就转发到https://api.deepseek.com如果你切回 OpenAI那就转发到 OpenAI 的接口地址。这个机制最大的价值在于Codex CLI 完全不需要知道自己到底在跟谁通信它只认本地代理这一个 endpoint。所以你可以随时在 CC Switch 里切换 ProviderCodex CLI 那边不用做任何修改也不需要重启终端。我试过在同一个对话过程中切换 Provider后续请求就发到新的服务商了体验相当顺滑。3.2 Provider 配置的几个关键参数在 CC Switch 里添加 Provider 时通常需要填写这几个字段Provider 名称、API 基础地址、API Key、模型名称。针对 DeepSeek 而言API 基础地址填https://api.deepseek.com也有的地方需要填成https://api.deepseek.com/v1这个要看你用的 CC Switch 版本对路径的处理方式。如果填了不带 v1 的地址后报 404可以试着把 v1 加上。API Key 填你在 DeepSeek 平台上申请到的那个 Key。模型名称填 DeepSeek 的模型标识比如deepseek-chat或者deepseek-reasoner取决于你想用对话模型还是推理模型。有一个参数容易被忽略就是是否启用 Stream 流式输出。Codex CLI 默认是要求流式响应的如果 CC Switch 的 Provider 配置里没有开启流式兼容可能会导致终端界面卡住或者输出不及时。我用的 CC Switch 版本默认是开启的但如果你发现终端输出是等全部生成完才一次性显示多半就是这个参数的问题。3.3 Codex CLI 的配置文件修改要点Codex CLI 的config.toml文件Windows 下默认路径是C:\Users\你的用户名\.codex\config.toml。里面需要修改的关键配置项是model_provider和base_url。一个典型的配置片段如下model deepseek-chat model_provider cc-switch [model_providers.cc-switch] name CC Switch base_url http://127.0.0.1:1081/v1 env_key OPENAI_API_KEY wire_api chat这里解释几个关键点base_url必须指向 CC Switch 的本地代理地址注意端口要跟你实际的一致env_key表示 Codex CLI 会从环境变量OPENAI_API_KEY读取 API Key这个 Key 其实是 CC Switch 自己生成的一个随意字符串因为实际的鉴权由 CC Switch 在转发请求时完成Codex CLI 只需要有一个 Key 能通过就行但格式上必须有否则可能报 401。wire_api设为chat表示走 chat completions 接口格式DeepSeek 的兼容性在这里是没问题的。修改完配置文件后建议重启一次终端让 Codex CLI 重新读取配置。如果不想重启也可以执行codex命令时加-c参数重新指定配置文件但正常重启终端更省事。我在实际操作中发现Codex CLI 对配置文件的读取时机是启动时加载中途改配置不会自动生效所以改完配置记得重启。4. 完整实操从零开始一步步跑通 Codex CLI这部分我会把实际操作过程完整走一遍从环境准备到最终在终端里跟 Codex CLI 对话每一步都给出具体的命令和注意事项你照着做就能跑起来。4.1 安装 Codex CLI前提是 Node.js 环境已经就绪。打开 PowerShell执行npm install -g openai/codex安装过程可能会需要一两分钟网络状况不好时可能会卡住。如果等了很久没反应可以用镜像源重试。我个人建议直接配置 npm 镜像加速命令如下npm config set registry https://registry.npmmirror.com设置完成后重新执行安装命令即可。镜像是国内节点速度会快很多。这个镜像地址是公开的第三方 npm 镜像安全方面没有问题。安装完成后验证版本codex --version如果提示无法识别codex命令先检查 npm 全局安装的路径有没有加入 PATH。npm 全局模块的路径一般在C:\Users\你的用户名\AppData\Roaming\npm确认一下这个目录在系统 PATH 里。我遇到过有人装完 Node.js 后 PATH 没刷新重启终端就正常了。4.2 启动并配置 CC Switch解压或安装好 CC Switch 后双击运行。托盘区会出现图标右键可以打开主界面。在主界面里找到 Providers 设置点击添加新的 Provider。按照前面说的参数填入 DeepSeek 的配置保存后选中这个 Provider 作为当前生效配置。启动后建议到设置里确认本地代理的端口号。我用的版本默认是 1081但不同版本可能不同。确认后把端口记下来下一步配置 Codex CLI 时要用到。这里有个小技巧如果点击测试连接按钮CC Switch 会发一个测试请求到配置的 API 地址能返回成功说明你的 API Key 没问题。4.3 修改 Codex CLI 配置文件用文本编辑器打开C:\Users\你的用户名\.codex\config.toml按前面给出的配置片段修改。如果文件原本是空的直接把全部内容粘贴进去即可。修改时注意base_url中的端口号要和 CC Switch 设置里显示的一致。这里还有一个容易踩坑的细节如果你的config.toml里原本有model_provider openai这样的内容记得改成cc-switch或者干脆删除model_provider行让 Codex CLI 使用我们在[model_providers.cc-switch]里声明的 provider。配置文件的解析逻辑是model_provider指定的名字必须与[model_providers.xxx]节的名字对应对不上就会报错找不到 provider。4.4 设置环境变量Codex CLI 需要读取OPENAI_API_KEY环境变量。在这里我建议直接通过命令行设置当前会话的变量$env:OPENAI_API_KEY sk-cc-switch-placeholder注意这个值不需要填真正的 DeepSeek API Key填一个 CC Switch 能接受的占位符字符串即可。实际请求时CC Switch 会用自己的逻辑替换成真正的 Key。如果这里填了错误的 Key可能反而会干扰 CC Switch 的正常转发我测试过填占位符是最稳妥的。如果你希望每次打开终端都自动生效可以用setx命令设置用户级别的环境变量setx OPENAI_API_KEY sk-cc-switch-placeholder但setx设置的变量只对之后新开的终端窗口生效当前窗口需要重启一下。个人建议用$env:临时设置即可毕竟这个方案的核心本来就是通过 CC Switch 管理 Key不必在环境变量层面做持久化。4.5 首次运行验证在终端里执行codex如果一切正常codex 会进入交互模式等待你输入指令。随便输入一个简单的问题比如写一个 Python 函数计算斐波那契数列回车后观察输出。如果能看到流式输出说明整条链路已经打通。如果在这个环节遇到了报错别急下一节我会把常见错误的排查方法整理成一个速查表按表排查即可。5. 常见问题排查与踩坑实录这一节我整理了在实际使用中遇到过的、以及在社区里看到的高频问题结合搜索热词中反复出现的报错信息逐条分析原因并给出解决方案。这些问题如果只看报错文本会觉得很绝望但理解原理之后其实非常简单。5.1 CC Switch 报 local proxy failed while handling codex endpoint这是搜索热度最高的报错之一。完整的报错通常是cc switch local proxy failed while handling codex endpoint /responses.或者类似的变体。这个报错说明了什么问题呢/responses是 OpenAI 较新的 Responses API 接口路径而 CC Switch 或 DeepSeek 的兼容层可能没有实现这个接口。Codex CLI 某些版本默认走的是 Responses API而不是传统的 Chat Completions API。当请求路径是/responses而你的 Provider 配置走的是 Chat 接口时本地代理就会处理失败。解决办法分两步。第一在 Codex CLI 的配置里把wire_api强制指定为chat让它走聊天补全接口而不是 Responses 接口。第二确保 CC Switch 的 DeepSeek Provider 配置使用的是正确的 API 路径拼接方式。如果第一步改完还报类似错误检查一下配置里base_url末尾是否带/v1有的代理工具对路径拼接非常敏感。5.2 401 Unauthorized 错误的多种可能报错信息形式是unexpected status 401 unauthorized: cc switch local proxy failed while handling...。401 的本质是鉴权失败也就是服务器不认你的 Key但在 CC Switch 的场景下这个 Key 可能是三层中的任何一层出了问题。第一层是 Codex CLI 传给 CC Switch 的 Key也就是我们设置的OPENAI_API_KEY环境变量。如果 Codex CLI 认为这个 Key 为空或者无效它可能压根不会发请求。第二层是 CC Switch 配置里保存的 DeepSeek API Key如果这个 Key 填错了或者过期了CC Switch 转发到 DeepSeek 时就会被拒。第三层是模型名称DeepSeek 的 API 如果收到一个不存在的模型名有时也会以 401 的形式回报。排查顺序建议是先打开 CC Switch 的测试连接确认 Provider 配置没问题再到 Codex CLI 端把model和model_provider配置检查一遍最后看环境变量是不是正确写入。大部分人的问题都是出在第二步模型名称写错了比如把deepseek-chat写成了deepseek-chat-v3之类的错误标识。5.3 404 Not Found 与路径拼接的关系404报错比较有意思它一般指向请求的 URL 路径不存在。如果是在配置初期出现的 404十有八九是base_url的路径问题。DeepSeek 的接口地址有两种写法不带/v1的根地址和带/v1的完整地址取决于服务端对路径的兼容策略。CC Switch 在转发时会做一次路径拼接如果拼接后变成https://api.deepseek.com/v1/chat/completions而 DeepSeek 实际接受的路径可能是https://api.deepseek.com/chat/completions就会产生 404。解决办法很简单在 CC Switch 的 Provider 配置里把 API 基础地址从https://api.deepseek.com/v1改成https://api.deepseek.com或者反过来试一下。这两种写法我在不同版本的 CC Switch 里都遇到过验证方法就是看测试连接的返回结果。测试通过就锁定这个配置。5.4 502 Bad Gateway 与 503 Service Unavailable这两个报错都指向代理层与上游服务之间的连接问题。502 Bad Gateway的常见原因有DeepSeek 服务暂时不可用、网络无法访问 DeepSeek 接口、或者 CC Switch 本地代理与 Codex CLI 之间的超时设置过短。503 Service Unavailable则常见于 CC Switch 的本地代理服务未完全启动或者端口被占用。排查方法也类似先确认 CC Switch 当前确实处于已启动状态托盘图标是不是正常的。再检查是否设置了系统代理某些第三方的代理工具可能干扰本地回环地址的访问。然后在终端里手动 ping 一下 DeepSeek 接口比如用curl发一个简单请求看返回是否正常。curl 如果不通说明问题出在网络上curl 如果通那就重点检查 CC Switch 的转发日志。这里我想多提醒一句502 报错有时候是因为频繁请求触发了服务端的限流。DeepSeek 的免费额度有速率限制短时间内大量调用就会触发。如果遇到这种问题歇几秒再试通常就好了。如果你在脚本或自动化流程中遇到 502可以考虑在代码里加入重试机制退避几秒再请求。5.5 无法定位 Codex CLI 二进制或运行时组件报错unable to locate the codex cli binary or required runtime components通常出现在桌面版 Codex 试图调用底层二进制时无法找到目标文件。这往往是因为 npm 安装的 codex 路径和桌面版预期的路径不一致。如果你同时也装了桌面版和 npm 版可能出现版本冲突。解决办法是二选一要么把 npm 版的安装路径加入桌面版可识别的查找范围要么卸载其中一个避免两边拉扯。我的做法是只用 npm 版桌面版只在特殊情况临时启一下。5.6 切换模型后原对话不停跳闪这个现象我在 CC Switch 切换模型后也遇到过。表现是对话窗口里的内容不停跳动刷新像卡了循环一样。原因通常是流式输出和本地代理之间的缓冲处理出现了竞态。切换 Provider 后旧连接没有完全关闭新请求已经进来了两个流在界面上打架。解决办法很直接切换 Provider 之后重启一次 Codex CLI 会话不要在一个已经处于活跃状态的会话里直接切换。初期我觉得这样做很麻烦后来养成了习惯就好多了。你可以在需要切换模型时先退出 codex切好 Provider 再重新启动整个过程不到十秒但是体验稳定了不止一个档次。5.7 CC Switch 与官方账号是否冲突这个问题我直接说结论不冲突。CC Switch 的本地代理和你在浏览器里登录的 ChatGPT 网页版或官方 App 是两套完全独立的东西。CC Switch 做的事情只是在你本机起一个 API 代理服务影响范围仅限于走这个代理的终端工具。它不会修改你的系统网络设置除非你手动开全局代理模式不会劫持你的浏览器流量更不会影响官方网页版的登录状态。我可以放心地同时开着一个 ChatGPT 网页版标签页又用 Codex CLI 走 DeepSeek两边互不干扰。唯一需要注意的是如果你在 CC Switch 里配置了 OpenAI 官方的 Provider 并打算用它那么请求会消耗你 OpenAI 账号的 API 额度这个和 ChatGPT Plus 订阅是两回事走的是 API 计费。但这条路我不常用毕竟 DeepSeek 的性价比摆在那里。6. 使用心得与配置建议这篇教程写到这里核心内容基本都覆盖了。最后分享几个我个人在实际使用中沉淀下来的经验希望能帮你避开一些不必要的折腾。关于模型选择如果你的主要场景是代码补全和脚本编写deepseek-chat完全够用响应速度也快如果要做复杂的逻辑推理或者长文本分析deepseek-reasoner虽然思考时间更长但在深度任务上的表现确实更好。我在日常开发中基本是两者混用简单任务走 chat复杂任务切到 reasonerCC Switch 的存在让这种切换变得成本极低。关于 CC Switch 的更新这个工具迭代频率挺高的每次更新都会修复一些兼容性问题或者增加新功能。我建议你偶尔关注一下 GitHub Releases看到新版本就手动更新一次。早期版本在处理某些流式响应时确实存在内存占用偏高的现象新版本改善了不少。当然更新之前最好备份一下配置文件或者至少记下当前的 Provider 配置防止更新后配置被重置。还有一个很多人没注意到的小技巧如果你的终端是 Windows Terminal建议把 Codex CLI 的动作绑定到一个独立的 Profile这样可以让 codex 会话不和其他终端任务混在一起切换起来干净利落。我用这个方式管理了很长时间体验比直接在默认终端里开要好得多。最后如果你在配置过程中遇到本教程没有覆盖的报错不妨先想想数据流的三层结构Codex CLI 到本地代理这一段本地代理到 DeepSeek 这一段以及 DeepSeek 服务端本身的情况。几乎所有问题都可以归到这叄层中的某一层按层排查思路就清晰了。希望这篇教程能帮你在 Windows 上顺利跑通这个组合少走一些弯路。
Windows下Codex CLI+CC Switch+DeepSeek API配置教程
近年来围绕 Codex CLI 的玩法越来越热闹但很多人在 Windows 下卡在了环境配置这一步。我也算是在终端里折腾 AI 工具比较早的一批用户从 ChatGPT 官方订阅到各类中转 API 都试过最后在 Windows 上稳定跑起来的组合是 Codex CLI CC Switch DeepSeek API。这篇文章就把我自己的完整配置过程、踩过的坑、还有那些看得人头皮发麻的报错信息一次性讲透。不管你是刚听说 Codex CLI 的新手还是已经被各种 local proxy 报错折磨半天的老哥这篇教程应该都能给你省下不少时间。1. 整体思路为什么要用 CC Switch 中转 DeepSeek API 来驱动 Codex CLI先把这个组合的逻辑理清楚。Codex CLI 本身是 OpenAI 出的终端编程助手设计上默认对接的是 OpenAI 官方接口。但在实际使用中你有两个绕不开的现实问题一是官方 API 的计费模式和模型版本未必符合所有人的预算与需求二是总有一些场景需要切换不同的模型供应商来做对比比如我想从 ChatGPT 的模型切到 DeepSeek 的模型如果每次都去改 Codex CLI 的配置文件麻烦得很。CC Switch 解决的就是这个切换的痛点它本质是一个本地代理工具在终端工具和 API 服务之间加了一层中转让你可以随时切换 Provider 而不用反复修改 Codex CLI 的配置。简单来说数据流向是这样的你在 Codex CLI 里输指令Codex CLI 按配置发给本地代理CC Switch 起的服务CC Switch 根据你当前选中的 Provider 配置把请求转发给对应的远程 API 服务商也就是 DeepSeek 的接口。对 Codex CLI 而言它只认本地这个代理地址完全不知道自己背后连的到底是谁。这个思路的好处很明显Codex CLI 不用动配置只写一次后续想换模型就在 CC Switch 的界面里点一下就好。我最初在 Windows 上折腾的时候其实也想过更直接的办法比如把 DeepSeek 的 API Key 直接写进 Codex CLI 的配置文件。但后来发现 DeepSeek 的接口路径和 OpenAI 能完全对齐的部分有限某些请求格式和鉴权方式存在差异。直接用替代方案容易遇到鉴权失败或者模型名对不上的问题。而 CC Switch 这类工具已经帮你把这些差异处理好了它模拟出一个与 OpenAI 兼容的接口格式内部再做协议转换这样一来 Codex CLI 就无需任何感知。这也是我为什么强烈建议你这么组合的原因——不是不能直连而是直连的坑远比你想象的多。用生活化的方式理解的话Codex CLI 是一个只吃西餐的客人DeepSeek API 是一个只做中餐的厨房CC Switch 就是那个两端都懂的翻译兼外卖员。它把西餐菜单翻译给中餐厨房又把做好的菜按西餐礼仪端上桌。没有这个中间层你硬把中餐塞给客人客人不是觉得餐具不对就是觉得上菜流程有问题。我花了很长时间才彻底想明白这一层逻辑想明白之后很多配置上的疑惑就迎刃而解了。在 Windows 下这个方案还有一个额外的好处CC Switch 提供了安装版和便携版两种形态便携版不用装服务、不写注册表对系统环境影响最小。对于经常要在不同机器上折腾开发环境的人而言便携版真的很友好。我自己的主力机用的是安装版备用笔记本用便携版两者在使用体验上几乎没有差别只是安装版的右键菜单和文件关联更顺手一些。2. 环境准备Windows 下这块拼图到底需要哪些组件动手之前先把需要的组件列清楚。这个方案的完整技术栈包括Node.js 运行时、Codex CLI 本体、CC Switch 工具、DeepSeek API Key。四样东西缺一不可而且它们的安装顺序也有讲究装反了容易出各种莫名其妙的问题。2.1 Node.js 环境的安装细节Codex CLI 官方推荐通过 npm 全局安装而 npm 是 Node.js 自带的包管理器所以第一步一定是装 Node.js。Windows 下我建议直接去 Node.js 官网下载 LTS 版本的安装包不要选 Current 版本。Current 版本功能新但某些依赖在 Windows 下可能存在兼容性问题而 LTS 版本经过了更充分的测试稳定压倒一切。安装的时候一路 Next 就行但有一个细节值得注意安装向导里有一个Add to PATH的选项默认是勾选的千万别取消否则后面在终端里执行 npm 命令会提示找不到命令。装完之后验证是否成功打开 PowerShell 或者 CMD输入node -v npm -v如果能看到版本号输出说明 Node.js 环境已经就绪。我遇到过不少人在这一步卡住后来发现是系统里有旧版本的 Node.js 残留PATH 环境变量里指到了旧的安装目录。如果出现这种情况最简单的处理方式是彻底卸载 Node.js 后再重装而不是手动去改 PATH手动改容易越改越乱。2.2 Codex CLI 的安装方式对比Codex CLI 的安装有几种途径我重点说两种npm 全局安装和桌面版安装。npm 安装的命令很简单npm install -g openai/codex装完执行codex --version验证。如果在终端里能正确输出版本号说明安装成功。桌面版则是 OpenAI 官方提供的图形界面版本适合不喜欢在终端里操作的人。但桌面版在 Windows 下的表现目前还是不如终端版稳定某些界面交互偶尔会有渲染问题。我的建议是如果你本身就是开发者经常用终端直接上 npm 版如果你只是想体验一下不打算重度使用桌面版也够用。不过后面配置代理的方式略有不同教程里我会以终端版为主来演示。安装完后Codex CLI 会在用户目录下生成配置目录默认位置是C:\Users\你的用户名\.codex。这个目录下有一个config.toml文件这是 Codex CLI 的核心配置文件。后面我们配置本地代理地址改的就是这个文件。2.3 CC Switch 的下载与安装选型CC Switch 的获取渠道这里要提醒一句不要去搜索引擎随便搜一个下载站那些第三方站点捆绑的风险比较高。最好去它的 GitHub Releases 页面找官方发布的压缩包。下载的时候会看到两个版本安装版Setup和便携版Portable。安装版会写注册表、创建快捷方式优点是干净省心便携版是免安装的解压就能用适合放在移动硬盘里随身携带。我自己实际用下来两个版本的核心功能完全一致只是便携版第一次启动时 Windows Defender 可能会多问一句毕竟没有签名信息的 exe 文件经常会被安全软件扫描。遇到这种情况确认是从官方渠道下载的放行就好。启动 CC Switch 后它会在系统托盘区显示一个小图标主界面是一个简洁的控制台。第一次启动时它会自动在本地起一个代理服务默认端口一般是 1081 或某个随机高位端口具体可以在设置里看。记住这个端口号后面配置 Codex CLI 的时候要用到所以启动后第一件事就是去设置里确认一下端口避免后面搞混。2.4 DeepSeek API Key 的申请流程DeepSeek 的 API Key 申请是在 DeepSeek 开放平台上完成的。注册账号、实名认证之后在控制台的API Keys页面创建一个新的 Key。创建的时候可以给 Key 起个名字方便区分用途。创建成功后页面会显示一次完整的 Key 字符串务必马上复制保存到本地因为关掉页面之后就看不到了只能重新创建新的 Key。这里还有一个费用相关的问题。DeepSeek API 是按 token 计费的新用户一般会有一定额度的免费赠送用完之后需要充值才能继续调用。我个人的经验是如果只是日常写点脚本、做代码补全消耗量不大充小额就够用很久。不要一上来就充大额先用完免费的额度实测一下自己的用量再说。3. 核心原理CC Switch 的本地代理机制与 Codex CLI 的对接方式很多人在配置过程中失败就是因为不理解本地代理的工作原理。这里我详细拆解一下理解了原理后面那些报错信息在你眼里就不再是乱码了。3.1 本地代理的工作机制CC Switch 启动后在你的机器上监听一个本地端口比如http://127.0.0.1:1081。Codex CLI 配置里的base_url指到这个地址那么 Codex CLI 发出的所有 API 请求都会先到这个本地代理。CC Switch 接收到请求后根据你当前选中的 Provider 配置决定把请求转发到哪里。如果你选的是 DeepSeek那就转发到https://api.deepseek.com如果你切回 OpenAI那就转发到 OpenAI 的接口地址。这个机制最大的价值在于Codex CLI 完全不需要知道自己到底在跟谁通信它只认本地代理这一个 endpoint。所以你可以随时在 CC Switch 里切换 ProviderCodex CLI 那边不用做任何修改也不需要重启终端。我试过在同一个对话过程中切换 Provider后续请求就发到新的服务商了体验相当顺滑。3.2 Provider 配置的几个关键参数在 CC Switch 里添加 Provider 时通常需要填写这几个字段Provider 名称、API 基础地址、API Key、模型名称。针对 DeepSeek 而言API 基础地址填https://api.deepseek.com也有的地方需要填成https://api.deepseek.com/v1这个要看你用的 CC Switch 版本对路径的处理方式。如果填了不带 v1 的地址后报 404可以试着把 v1 加上。API Key 填你在 DeepSeek 平台上申请到的那个 Key。模型名称填 DeepSeek 的模型标识比如deepseek-chat或者deepseek-reasoner取决于你想用对话模型还是推理模型。有一个参数容易被忽略就是是否启用 Stream 流式输出。Codex CLI 默认是要求流式响应的如果 CC Switch 的 Provider 配置里没有开启流式兼容可能会导致终端界面卡住或者输出不及时。我用的 CC Switch 版本默认是开启的但如果你发现终端输出是等全部生成完才一次性显示多半就是这个参数的问题。3.3 Codex CLI 的配置文件修改要点Codex CLI 的config.toml文件Windows 下默认路径是C:\Users\你的用户名\.codex\config.toml。里面需要修改的关键配置项是model_provider和base_url。一个典型的配置片段如下model deepseek-chat model_provider cc-switch [model_providers.cc-switch] name CC Switch base_url http://127.0.0.1:1081/v1 env_key OPENAI_API_KEY wire_api chat这里解释几个关键点base_url必须指向 CC Switch 的本地代理地址注意端口要跟你实际的一致env_key表示 Codex CLI 会从环境变量OPENAI_API_KEY读取 API Key这个 Key 其实是 CC Switch 自己生成的一个随意字符串因为实际的鉴权由 CC Switch 在转发请求时完成Codex CLI 只需要有一个 Key 能通过就行但格式上必须有否则可能报 401。wire_api设为chat表示走 chat completions 接口格式DeepSeek 的兼容性在这里是没问题的。修改完配置文件后建议重启一次终端让 Codex CLI 重新读取配置。如果不想重启也可以执行codex命令时加-c参数重新指定配置文件但正常重启终端更省事。我在实际操作中发现Codex CLI 对配置文件的读取时机是启动时加载中途改配置不会自动生效所以改完配置记得重启。4. 完整实操从零开始一步步跑通 Codex CLI这部分我会把实际操作过程完整走一遍从环境准备到最终在终端里跟 Codex CLI 对话每一步都给出具体的命令和注意事项你照着做就能跑起来。4.1 安装 Codex CLI前提是 Node.js 环境已经就绪。打开 PowerShell执行npm install -g openai/codex安装过程可能会需要一两分钟网络状况不好时可能会卡住。如果等了很久没反应可以用镜像源重试。我个人建议直接配置 npm 镜像加速命令如下npm config set registry https://registry.npmmirror.com设置完成后重新执行安装命令即可。镜像是国内节点速度会快很多。这个镜像地址是公开的第三方 npm 镜像安全方面没有问题。安装完成后验证版本codex --version如果提示无法识别codex命令先检查 npm 全局安装的路径有没有加入 PATH。npm 全局模块的路径一般在C:\Users\你的用户名\AppData\Roaming\npm确认一下这个目录在系统 PATH 里。我遇到过有人装完 Node.js 后 PATH 没刷新重启终端就正常了。4.2 启动并配置 CC Switch解压或安装好 CC Switch 后双击运行。托盘区会出现图标右键可以打开主界面。在主界面里找到 Providers 设置点击添加新的 Provider。按照前面说的参数填入 DeepSeek 的配置保存后选中这个 Provider 作为当前生效配置。启动后建议到设置里确认本地代理的端口号。我用的版本默认是 1081但不同版本可能不同。确认后把端口记下来下一步配置 Codex CLI 时要用到。这里有个小技巧如果点击测试连接按钮CC Switch 会发一个测试请求到配置的 API 地址能返回成功说明你的 API Key 没问题。4.3 修改 Codex CLI 配置文件用文本编辑器打开C:\Users\你的用户名\.codex\config.toml按前面给出的配置片段修改。如果文件原本是空的直接把全部内容粘贴进去即可。修改时注意base_url中的端口号要和 CC Switch 设置里显示的一致。这里还有一个容易踩坑的细节如果你的config.toml里原本有model_provider openai这样的内容记得改成cc-switch或者干脆删除model_provider行让 Codex CLI 使用我们在[model_providers.cc-switch]里声明的 provider。配置文件的解析逻辑是model_provider指定的名字必须与[model_providers.xxx]节的名字对应对不上就会报错找不到 provider。4.4 设置环境变量Codex CLI 需要读取OPENAI_API_KEY环境变量。在这里我建议直接通过命令行设置当前会话的变量$env:OPENAI_API_KEY sk-cc-switch-placeholder注意这个值不需要填真正的 DeepSeek API Key填一个 CC Switch 能接受的占位符字符串即可。实际请求时CC Switch 会用自己的逻辑替换成真正的 Key。如果这里填了错误的 Key可能反而会干扰 CC Switch 的正常转发我测试过填占位符是最稳妥的。如果你希望每次打开终端都自动生效可以用setx命令设置用户级别的环境变量setx OPENAI_API_KEY sk-cc-switch-placeholder但setx设置的变量只对之后新开的终端窗口生效当前窗口需要重启一下。个人建议用$env:临时设置即可毕竟这个方案的核心本来就是通过 CC Switch 管理 Key不必在环境变量层面做持久化。4.5 首次运行验证在终端里执行codex如果一切正常codex 会进入交互模式等待你输入指令。随便输入一个简单的问题比如写一个 Python 函数计算斐波那契数列回车后观察输出。如果能看到流式输出说明整条链路已经打通。如果在这个环节遇到了报错别急下一节我会把常见错误的排查方法整理成一个速查表按表排查即可。5. 常见问题排查与踩坑实录这一节我整理了在实际使用中遇到过的、以及在社区里看到的高频问题结合搜索热词中反复出现的报错信息逐条分析原因并给出解决方案。这些问题如果只看报错文本会觉得很绝望但理解原理之后其实非常简单。5.1 CC Switch 报 local proxy failed while handling codex endpoint这是搜索热度最高的报错之一。完整的报错通常是cc switch local proxy failed while handling codex endpoint /responses.或者类似的变体。这个报错说明了什么问题呢/responses是 OpenAI 较新的 Responses API 接口路径而 CC Switch 或 DeepSeek 的兼容层可能没有实现这个接口。Codex CLI 某些版本默认走的是 Responses API而不是传统的 Chat Completions API。当请求路径是/responses而你的 Provider 配置走的是 Chat 接口时本地代理就会处理失败。解决办法分两步。第一在 Codex CLI 的配置里把wire_api强制指定为chat让它走聊天补全接口而不是 Responses 接口。第二确保 CC Switch 的 DeepSeek Provider 配置使用的是正确的 API 路径拼接方式。如果第一步改完还报类似错误检查一下配置里base_url末尾是否带/v1有的代理工具对路径拼接非常敏感。5.2 401 Unauthorized 错误的多种可能报错信息形式是unexpected status 401 unauthorized: cc switch local proxy failed while handling...。401 的本质是鉴权失败也就是服务器不认你的 Key但在 CC Switch 的场景下这个 Key 可能是三层中的任何一层出了问题。第一层是 Codex CLI 传给 CC Switch 的 Key也就是我们设置的OPENAI_API_KEY环境变量。如果 Codex CLI 认为这个 Key 为空或者无效它可能压根不会发请求。第二层是 CC Switch 配置里保存的 DeepSeek API Key如果这个 Key 填错了或者过期了CC Switch 转发到 DeepSeek 时就会被拒。第三层是模型名称DeepSeek 的 API 如果收到一个不存在的模型名有时也会以 401 的形式回报。排查顺序建议是先打开 CC Switch 的测试连接确认 Provider 配置没问题再到 Codex CLI 端把model和model_provider配置检查一遍最后看环境变量是不是正确写入。大部分人的问题都是出在第二步模型名称写错了比如把deepseek-chat写成了deepseek-chat-v3之类的错误标识。5.3 404 Not Found 与路径拼接的关系404报错比较有意思它一般指向请求的 URL 路径不存在。如果是在配置初期出现的 404十有八九是base_url的路径问题。DeepSeek 的接口地址有两种写法不带/v1的根地址和带/v1的完整地址取决于服务端对路径的兼容策略。CC Switch 在转发时会做一次路径拼接如果拼接后变成https://api.deepseek.com/v1/chat/completions而 DeepSeek 实际接受的路径可能是https://api.deepseek.com/chat/completions就会产生 404。解决办法很简单在 CC Switch 的 Provider 配置里把 API 基础地址从https://api.deepseek.com/v1改成https://api.deepseek.com或者反过来试一下。这两种写法我在不同版本的 CC Switch 里都遇到过验证方法就是看测试连接的返回结果。测试通过就锁定这个配置。5.4 502 Bad Gateway 与 503 Service Unavailable这两个报错都指向代理层与上游服务之间的连接问题。502 Bad Gateway的常见原因有DeepSeek 服务暂时不可用、网络无法访问 DeepSeek 接口、或者 CC Switch 本地代理与 Codex CLI 之间的超时设置过短。503 Service Unavailable则常见于 CC Switch 的本地代理服务未完全启动或者端口被占用。排查方法也类似先确认 CC Switch 当前确实处于已启动状态托盘图标是不是正常的。再检查是否设置了系统代理某些第三方的代理工具可能干扰本地回环地址的访问。然后在终端里手动 ping 一下 DeepSeek 接口比如用curl发一个简单请求看返回是否正常。curl 如果不通说明问题出在网络上curl 如果通那就重点检查 CC Switch 的转发日志。这里我想多提醒一句502 报错有时候是因为频繁请求触发了服务端的限流。DeepSeek 的免费额度有速率限制短时间内大量调用就会触发。如果遇到这种问题歇几秒再试通常就好了。如果你在脚本或自动化流程中遇到 502可以考虑在代码里加入重试机制退避几秒再请求。5.5 无法定位 Codex CLI 二进制或运行时组件报错unable to locate the codex cli binary or required runtime components通常出现在桌面版 Codex 试图调用底层二进制时无法找到目标文件。这往往是因为 npm 安装的 codex 路径和桌面版预期的路径不一致。如果你同时也装了桌面版和 npm 版可能出现版本冲突。解决办法是二选一要么把 npm 版的安装路径加入桌面版可识别的查找范围要么卸载其中一个避免两边拉扯。我的做法是只用 npm 版桌面版只在特殊情况临时启一下。5.6 切换模型后原对话不停跳闪这个现象我在 CC Switch 切换模型后也遇到过。表现是对话窗口里的内容不停跳动刷新像卡了循环一样。原因通常是流式输出和本地代理之间的缓冲处理出现了竞态。切换 Provider 后旧连接没有完全关闭新请求已经进来了两个流在界面上打架。解决办法很直接切换 Provider 之后重启一次 Codex CLI 会话不要在一个已经处于活跃状态的会话里直接切换。初期我觉得这样做很麻烦后来养成了习惯就好多了。你可以在需要切换模型时先退出 codex切好 Provider 再重新启动整个过程不到十秒但是体验稳定了不止一个档次。5.7 CC Switch 与官方账号是否冲突这个问题我直接说结论不冲突。CC Switch 的本地代理和你在浏览器里登录的 ChatGPT 网页版或官方 App 是两套完全独立的东西。CC Switch 做的事情只是在你本机起一个 API 代理服务影响范围仅限于走这个代理的终端工具。它不会修改你的系统网络设置除非你手动开全局代理模式不会劫持你的浏览器流量更不会影响官方网页版的登录状态。我可以放心地同时开着一个 ChatGPT 网页版标签页又用 Codex CLI 走 DeepSeek两边互不干扰。唯一需要注意的是如果你在 CC Switch 里配置了 OpenAI 官方的 Provider 并打算用它那么请求会消耗你 OpenAI 账号的 API 额度这个和 ChatGPT Plus 订阅是两回事走的是 API 计费。但这条路我不常用毕竟 DeepSeek 的性价比摆在那里。6. 使用心得与配置建议这篇教程写到这里核心内容基本都覆盖了。最后分享几个我个人在实际使用中沉淀下来的经验希望能帮你避开一些不必要的折腾。关于模型选择如果你的主要场景是代码补全和脚本编写deepseek-chat完全够用响应速度也快如果要做复杂的逻辑推理或者长文本分析deepseek-reasoner虽然思考时间更长但在深度任务上的表现确实更好。我在日常开发中基本是两者混用简单任务走 chat复杂任务切到 reasonerCC Switch 的存在让这种切换变得成本极低。关于 CC Switch 的更新这个工具迭代频率挺高的每次更新都会修复一些兼容性问题或者增加新功能。我建议你偶尔关注一下 GitHub Releases看到新版本就手动更新一次。早期版本在处理某些流式响应时确实存在内存占用偏高的现象新版本改善了不少。当然更新之前最好备份一下配置文件或者至少记下当前的 Provider 配置防止更新后配置被重置。还有一个很多人没注意到的小技巧如果你的终端是 Windows Terminal建议把 Codex CLI 的动作绑定到一个独立的 Profile这样可以让 codex 会话不和其他终端任务混在一起切换起来干净利落。我用这个方式管理了很长时间体验比直接在默认终端里开要好得多。最后如果你在配置过程中遇到本教程没有覆盖的报错不妨先想想数据流的三层结构Codex CLI 到本地代理这一段本地代理到 DeepSeek 这一段以及 DeepSeek 服务端本身的情况。几乎所有问题都可以归到这叄层中的某一层按层排查思路就清晰了。希望这篇教程能帮你在 Windows 上顺利跑通这个组合少走一些弯路。