1. 为什么要在 Windows 上折腾 Codex CLI 加 DeepSeek API 这套组合很多人第一次听到在终端里跑 AI 编程助手这件事第一反应是我直接用网页版不香吗我一开始也这么想直到我在一个没有图形界面的远程开发环境里需要让 AI 帮我批量重构十几个文件网页版那种复制粘贴代码块的方式直接把我逼疯了。终端方案的核心价值就在这儿——它能把 AI 能力直接嵌进你的命令行工作流读文件、改文件、跑命令一气呵成不用在浏览器和编辑器之间反复横跳。Codex CLI 就是干这个的。它是一个跑在终端里的 AI 编程代理能理解你的项目上下文帮你写代码、改 bug、执行命令。而 DeepSeek API 则是国内开发者比较容易接入的大模型服务价格友好、响应稳定中文理解能力也够用。把这两者接起来你就能在 Windows 的终端里拥有一个能读你整个项目的编程搭子。但问题来了Codex CLI 默认对接的是官方服务想换成 DeepSeek 的 API中间需要一个翻译层来做协议转换和请求转发。CC Switch 就是扮演这个角色的工具——它在本机起一个代理服务把 Codex CLI 发出来的请求转换成 DeepSeek API 能听懂的格式再把结果转回去。听起来简单实际配置的时候坑不少尤其是 Windows 环境下路径、环境变量、端口占用这些问题能把人折腾到怀疑人生。这篇内容适合三类人一是想在 Windows 上用终端 AI 编程助手但不知道从哪下手的开发者二是已经装了 Codex CLI 但卡在 API 接入环节的人三是用了一段时间想切换回官方服务、结果发现切不回去的倒霉蛋这个场景后面会专门讲。我会把整个安装配置流程拆开揉碎包括我踩过的坑和最后验证有效的解决方案。2. 动手前的环境盘点别急着敲命令2.1 确认你的 Windows 版本和终端环境Codex CLI 对系统版本有要求Windows 10 1809 及以上、Windows 11 都没问题。但真正影响体验的不是系统版本而是你用的终端。我强烈建议用Windows Terminal而不是老旧的 cmd 或者 PowerShell 独立窗口。原因很实际Codex CLI 的输出有大量格式化和颜色标记cmd 的渲染能力跟不上会出现乱码或者颜色丢失。Windows Terminal 对 ANSI 转义序列的支持完整显示效果和 Linux 终端基本一致。如果你还没装 Windows Terminal直接在 Microsoft Store 搜Windows Terminal安装就行免费且官方维护。装完之后把默认终端设为 Windows Terminal这样以后任何命令行调用都会自动用它打开。另外确认一下你的 PowerShell 版本。在终端里敲$PSVersionTable.PSVersion理想情况下应该是 5.1 或更高。如果是 7.x 更好性能和兼容性都更优。版本太低的话某些命令语法会不认后面配置环境变量的时候容易出问题。2.2 Node.js 运行时的安装与版本选择Codex CLI 是基于 Node.js 开发的所以 Node.js 是硬性依赖。这里有个关键点不要用太老的版本也不要用太新的奇数版本。我实测下来 Node.js 20 LTS 是最稳的选择18 LTS 也能跑但偶尔会有依赖警告22 虽然是最新版但某些 npm 包的兼容性还没跟上。安装方式我推荐两种第一种是去 Node.js 官网下载 LTS 版本的 Windows 安装包.msi双击一路下一步就行。安装的时候注意勾选Add to PATH这个选项它会自动把 node 和 npm 加到系统环境变量里。很多人装完发现命令行里敲node -v提示不是内部或外部命令就是因为这个选项没勾。第二种是用 winget 命令行安装适合喜欢干净利落的人winget install OpenJS.NodeJS.LTS装完之后必须重开一个终端窗口环境变量才会生效。然后在终端里验证node -v npm -v两个命令都能正常输出版本号说明 Node.js 环境就绪了。如果 npm 版本太老低于 9建议升级一下npm install -g npmlatest注意在 Windows 上用npm install -g全局安装包时有时候会遇到权限问题。如果报错提示 EPERM 或 permission denied不要用管理员身份硬跑而是先检查 npm 的全局安装路径是否在当前用户的可写目录下。可以用npm config get prefix查看如果是C:\Program Files\nodejs这种系统目录建议改成用户目录下的路径。2.3 网络环境的预先检查这一步很多人会忽略但它是后面报错的最大来源。Codex CLI 和 CC Switch 都需要访问外部 API 端点你得确保本机网络能正常连通 DeepSeek 的 API 地址。在终端里测试一下curl https://api.deepseek.com如果返回了任何 HTTP 响应哪怕是 401 未授权说明网络通路没问题。如果直接超时或者提示无法解析主机名那就要先排查 DNS 和网络连接。公司内网环境有时候会拦截外部 API 请求这种情况需要找网络管理员确认。另外检查一下本机端口占用情况。CC Switch 默认会在本地起一个代理服务通常监听某个特定端口。如果这个端口已经被其他程序占了代理就起不来。提前看一下netstat -ano | findstr LISTENING | findstr 你的端口号具体端口号后面配置 CC Switch 的时候会确定这里先有个意识就行。3. Codex CLI 的安装与首次运行验证3.1 全局安装 Codex CLINode.js 环境就绪之后安装 Codex CLI 就是一条命令的事npm install -g openai/codex等它跑完验证安装是否成功codex --version能输出版本号就说明安装成功了。如果提示codex 不是内部或外部命令大概率是 npm 全局路径没加到 PATH 里。用npm config get prefix看一下全局安装路径然后手动把这个路径加到系统环境变量的 Path 里。还有一种情况是安装过程中卡住不动这通常是 npm 源的问题。可以临时切换到国内镜像源加速npm install -g openai/codex --registryhttps://registry.npmmirror.com装完之后建议切回官方源避免后续安装其他包时出现版本不一致的问题npm config set registry https://registry.npmjs.org3.2 首次启动会遇到什么第一次在终端里敲codex命令它会引导你进行初始配置。默认流程是让你登录官方账号或者输入官方 API Key。但我们的目标是接入 DeepSeek所以这里先不要按它的引导走完直接 CtrlC 退出就行。等 CC Switch 配置好之后我们再通过代理的方式让它连上 DeepSeek。这里有个细节要注意Codex CLI 首次运行会在用户目录下生成配置文件夹Windows 上通常在C:\Users\你的用户名\.codex\这个路径。里面会有配置文件后面我们需要修改这个文件来指向本地代理。先确认这个目录存在ls $env:USERPROFILE\.codex如果目录不存在手动创建一下也行。这个目录是 Codex CLI 存放配置、缓存和会话记录的地方很重要。3.3 验证 Codex CLI 的基本功能在接入 DeepSeek 之前先确认 Codex CLI 本身能正常工作。随便找个项目目录在里面启动cd 你的项目目录 codex如果它能正常启动并显示交互界面说明 CLI 本身没问题。这时候它可能会提示你没有配置 API Key 或者登录状态这是正常的先不用管。我们的重点是让它通过 CC Switch 走 DeepSeek 的通道。实操心得如果你之前装过旧版本的 Codex CLI升级的时候建议先卸载再重装避免残留的配置文件导致奇怪的问题。卸载命令是npm uninstall -g openai/codex然后再重新安装。4. CC Switch 的部署与代理配置细节4.1 CC Switch 到底做了什么在讲安装之前先把这个工具的作用说清楚不然后面配置的时候你不知道每个参数是干嘛的。Codex CLI 和 DeepSeek API 之间的通信协议格式不一样——Codex CLI 发出来的请求结构是按照它自己的规范组织的而 DeepSeek API 有自己的一套请求格式。CC Switch 在本机起一个 HTTP 代理服务Codex CLI 把请求发给这个代理代理把请求翻译成 DeepSeek 能理解的格式转发出去拿到响应后再翻译回来给 Codex CLI。所以整个链路是这样的Codex CLI → 本地代理CC Switch→ DeepSeek API → 本地代理 → Codex CLI。理解了这个链路后面出问题的时候你就知道该在哪一环排查。4.2 获取和安装 CC SwitchCC Switch 是一个独立的工具需要单独下载。它的发布渠道通常是 GitHub Releases 页面下载对应 Windows 的版本。下载下来通常是一个可执行文件或者一个压缩包解压到你觉得合适的目录比如C:\Tools\cc-switch\。不建议放在桌面或者下载文件夹里因为这些目录容易被清理而且路径里如果有中文或空格某些工具会出问题。放在C:\Tools\这种纯英文、无空格的路径下最稳妥。下载完之后先别急着双击运行我们需要先准备好配置文件。CC Switch 需要一个配置文件来告诉它监听哪个端口、转发到哪个上游 API、用哪个 API Key。配置文件通常是 JSON 或者 YAML 格式具体看版本。4.3 配置文件的编写要点一个典型的 CC Switch 配置大概长这样以 JSON 为例{ listen_port: 8080, upstream: { base_url: https://api.deepseek.com, api_key: sk-你的DeepSeek密钥, model: deepseek-chat }, log_level: info }几个关键点解释一下listen_port本地代理监听的端口。选一个不常用的端口比如 8080、9090 这种。如果被占了就换一个。base_urlDeepSeek API 的基础地址。注意不要在后面加多余的路径CC Switch 会自己拼接。api_key你在 DeepSeek 平台申请的 API Key。这个 Key 要保管好不要泄露。model指定用哪个模型。DeepSeek 有多个模型可选编程场景一般用deepseek-chat或者deepseek-coder。注意API Key 不要直接写在会提交到 Git 仓库的文件里。如果这个配置文件放在项目目录下记得加到.gitignore里。更安全的做法是用环境变量来传 KeyCC Switch 支持从环境变量读取。4.4 启动代理并验证连通性配置文件写好之后启动 CC Switch.\cc-switch.exe --config .\config.json如果它正常启动终端里会显示类似Proxy listening on port 8080的日志。这时候先别关这个窗口另开一个终端测试代理是否工作curl http://localhost:8080/v1/models -H Authorization: Bearer 你的DeepSeek密钥如果返回了模型列表的 JSON 数据说明代理转发链路是通的。如果返回 401检查 API Key 是否正确如果返回 404检查 base_url 配置如果连接被拒绝说明代理没启动成功或者端口不对。这一步是整个配置过程中最关键的验证点。代理不通后面 Codex CLI 怎么配都没用。所以务必在这里确认链路通畅再往下走。5. 把 Codex CLI 指向本地代理的完整操作5.1 修改 Codex CLI 的配置文件前面提到 Codex CLI 的配置目录在C:\Users\你的用户名\.codex\。我们需要修改或者创建里面的配置文件让它把请求发到本地代理而不是官方服务。配置文件通常叫config.json或者config.toml具体看版本。核心配置项是 API 的 base URL 和 API Key。把它改成指向本地代理{ api_base: http://localhost:8080/v1, api_key: 任意非空字符串, model: deepseek-chat }这里有个容易困惑的点api_key为什么填任意字符串因为真正的 DeepSeek API Key 已经在 CC Switch 的配置里了Codex CLI 发给本地代理的请求不需要再带真实的 Key。但 Codex CLI 可能会检查这个字段是否为空所以随便填一个非空值就行。5.2 环境变量方式的配置推荐直接改配置文件的方式有个缺点每次切换服务都要改文件容易忘。更优雅的方式是用环境变量。Codex CLI 支持从环境变量读取 API 配置$env:OPENAI_API_BASE http://localhost:8080/v1 $env:OPENAI_API_KEY sk-local-proxy但这种方式只在当前终端会话有效关掉窗口就没了。要永久生效得写到系统环境变量里[System.Environment]::SetEnvironmentVariable(OPENAI_API_BASE, http://localhost:8080/v1, User) [System.Environment]::SetEnvironmentVariable(OPENAI_API_KEY, sk-local-proxy, User)设置完之后重开终端用echo $env:OPENAI_API_BASE验证一下是否生效。5.3 跑通第一个请求配置完成之后在项目目录里启动 Codex CLIcd 你的项目目录 codex然后随便问它一个问题比如帮我看看当前目录下有哪些文件。如果它能正常回复说明整条链路已经打通了。这时候你可以在 CC Switch 的日志窗口里看到请求转发的记录确认请求确实走了 DeepSeek 的通道。如果 Codex CLI 报错说连接失败按这个顺序排查CC Switch 是否还在运行窗口有没有被误关端口号是否一致Codex CLI 配置的端口和 CC Switch 监听的是否相同防火墙是否拦截了本地回环地址的请求Windows 防火墙有时候会拦截本地代理。API Key 是否有效在 DeepSeek 平台上确认 Key 的状态和余额。6. 那些让人抓狂的报错和我的排查实录6.1 local proxy failed while handling codex endpoint /responses这个报错我遇到过不止一次症状是 Codex CLI 能启动但一发请求就报这个错。字面意思是本地代理在处理/responses这个端点的时候失败了。根本原因通常是 CC Switch 的版本和 Codex CLI 的版本不匹配——Codex CLI 新版本改了 API 路径或者请求格式而 CC Switch 还没跟上。解决办法有两个一是升级 CC Switch 到最新版本开发者通常会跟进 Codex CLI 的更新二是如果最新版还没适配就降级 Codex CLI 到一个已知能用的版本npm install -g openai/codex特定版本号怎么知道哪个版本能用去 CC Switch 的文档或者 issue 区看看通常有人会反馈兼容的版本组合。6.2 unexpected status 401 unauthorized401 错误就是认证失败。在 CC Switch 这个场景下401 通常不是 Codex CLI 的问题而是 CC Switch 转发给 DeepSeek 的时候 Key 不对。排查步骤确认 CC Switch 配置文件里的 API Key 是完整的没有多余的空格或换行。确认 Key 没有过期或被禁用。登录 DeepSeek 平台看一下 Key 的状态。确认账户余额充足。余额不足的时候有些 API 会返回 401 而不是 402容易误导。我踩过的一个坑是从网页复制 API Key 的时候不小心把末尾的一个空格也复制进去了。配置文件里看起来没问题但实际发送的时候带了个空格服务端就认不出来。这种问题特别隐蔽建议复制之后在编辑器里检查一下。6.3 unexpected status 404 not found404 通常是路径拼接出了问题。CC Switch 的base_url配置和 Codex CLI 的api_base配置如果有一方多了或者少了一层路径就会导致最终请求的 URL 不对。比如 DeepSeek 的 API 路径是https://api.deepseek.com/v1/chat/completions如果 CC Switch 的 base_url 配成了https://api.deepseek.com/v1然后它又自己拼了一个/v1/chat/completions就变成了/v1/v1/chat/completions直接 404。解决方法是仔细看 CC Switch 的日志它会打印出实际请求的完整 URL。对照 DeepSeek 的 API 文档确认路径正确。6.4 unable to locate the codex cli binary or required runtime components这个报错说明系统找不到 Codex CLI 的可执行文件或者它依赖的运行时组件缺失。常见原因Node.js 没装好或者版本不对。重新验证node -v和npm -v。npm 全局安装路径不在 PATH 里。用npm config get prefix找到路径手动加到 PATH。安装过程中断了包不完整。卸载重装。在 Windows 上还有一种特殊情况如果你同时装了多个版本的 Node.js比如通过 nvm-windows 管理当前激活的版本可能和安装 Codex CLI 时的版本不一致。用nvm list看一下当前用的是哪个版本确保和安装时一致。6.5 从 DeepSeek 切回官方服务时切不回去这个场景在热词里出现了说明不少人遇到过。症状是用 CC Switch 接入 DeepSeek 用了一段时间想切回官方服务结果发现怎么都连不上官方 API 了。原因通常是环境变量或者配置文件还指向本地代理。Codex CLI 读取配置的优先级是环境变量 配置文件 默认值。如果你之前用环境变量设置了OPENAI_API_BASE指向本地代理即使你改了配置文件环境变量还是会覆盖它。解决办法是清除或者修改环境变量[System.Environment]::SetEnvironmentVariable(OPENAI_API_BASE, $null, User) [System.Environment]::SetEnvironmentVariable(OPENAI_API_KEY, $null, User)然后重开终端让 Codex CLI 回到默认的官方配置。如果配置文件里也改了记得一并改回来。实操心得我建议在切换服务的时候用一个简单的脚本来管理环境变量。比如写两个 PowerShell 脚本一个叫use-deepseek.ps1一个叫use-official.ps1分别设置对应的环境变量。切换的时候跑一下脚本就行不用手动改配置减少出错概率。7. 日常使用中的效率技巧和稳定性维护7.1 让 CC Switch 开机自启每次用之前手动启动 CC Switch 太麻烦。可以把它加到 Windows 的启动项里或者用任务计划程序设置开机自动运行。最简单的方式是创建一个快捷方式放到启动文件夹# 打开启动文件夹 shell:startup把 CC Switch 的快捷方式拖进去就行。但要注意如果 CC Switch 启动的时候配置文件路径是相对路径开机自启可能会因为工作目录不对而找不到配置文件。建议在快捷方式的目标里写绝对路径或者用批处理脚本包装一下echo off cd /d C:\Tools\cc-switch start cc-switch.exe --config C:\Tools\cc-switch\config.json7.2 日志排查的实用技巧CC Switch 的日志是排查问题的第一手资料。建议把日志级别设为debug这样能看到完整的请求和响应内容。但日常使用的时候设为info就行debug模式日志量太大时间长了占磁盘空间。日志里重点看几个东西请求的完整 URL、请求头里的认证信息Key 会被脱敏、响应状态码、响应时间。如果响应时间特别长超过 30 秒可能是网络问题或者 DeepSeek 服务端负载高可以考虑在 CC Switch 里配置超时重试。7.3 多模型切换的配置管理DeepSeek 有多个模型不同场景适合不同的模型。比如日常对话用deepseek-chat纯代码任务用deepseek-coder。如果频繁切换每次改配置文件很烦。可以在 CC Switch 里配置多个上游然后通过不同的本地端口暴露出来{ proxies: [ { listen_port: 8080, upstream: { base_url: https://api.deepseek.com, api_key: sk-xxx, model: deepseek-chat } }, { listen_port: 8081, upstream: { base_url: https://api.deepseek.com, api_key: sk-xxx, model: deepseek-coder } } ] }然后 Codex CLI 这边通过切换OPENAI_API_BASE的端口号来选择不同的模型。配合前面说的 PowerShell 脚本切换起来就是一条命令的事。7.4 性能优化的几个细节Codex CLI 在处理大项目的时候会把项目文件内容作为上下文发给模型。如果项目很大请求体可能非常庞大导致响应慢甚至超时。几个优化方向在项目根目录放一个.codexignore文件如果支持的话排除不需要 AI 读取的目录比如node_modules、.git、dist这些。调整 Codex CLI 的上下文窗口大小配置不要一次性发送太多文件。在 CC Switch 层面开启响应缓存对于相同的请求直接返回缓存结果减少对 DeepSeek API 的调用次数。7.5 安全方面的注意事项API Key 是敏感信息几个基本的安全习惯不要把 Key 硬编码在会提交到版本控制的文件里。定期轮换 Key尤其是在多人协作的环境里。CC Switch 的代理只监听本地回环地址127.0.0.1不要改成 0.0.0.0否则同网络下的其他机器也能访问你的代理可能被盗用 API 额度。如果怀疑 Key 泄露立即去 DeepSeek 平台吊销旧 Key 并生成新的。我在实际使用中最大的体会是这套组合的稳定性很大程度上取决于版本匹配。Codex CLI 更新频繁CC Switch 的适配有时候会滞后。所以我的建议是一旦跑通了一个可用的版本组合不要急着升级。先把当前版本号记下来等确认新版本兼容之后再升。盲目追新在这套工具链上很容易把自己搞崩溃。另外如果你只是偶尔用用 AI 编程助手其实没必要折腾这套终端方案网页版或者 IDE 插件可能更省心。但如果你像我一样日常工作流重度依赖命令行需要 AI 能直接操作文件系统、执行命令、批量处理那这套方案带来的效率提升是值得前期投入时间配置的。