老实说我一开始对“在 Windows 上用 Claude Code”这件事是有点抗拒的。这类终端编程助手总是默认你用的是 macOS 或者 Linux很多教程上来就是 brew install、apt installWindows 用户只能自己慢慢摸索。但真在 Windows 上跑通一次之后我发现链路比想象中短装 Node.js执行 npm 安装命令再用 CC Switch 把 DeepSeek V4 Pro 的接口接到 Claude Code 上整个过程熟悉的话半小时内就能搞定。这篇内容不搬运官方文档我从一个普通开发者的角度把这套 Windows 落地方案从头到尾拆开讲包括每一步背后的原因以及我实际踩过的坑你照着做就能少走弯路。如果你完全没接触过 Claude Code也能跟着走通如果只是为了接 DeepSeek V4 Pro 而来可以直接跳到第 4 节遇到报错再看第 5 节。1. 链路拆解这三样东西到底怎么配合工作的1.1 谁负责交互谁负责路由谁负责推理先明确一个基本认识Claude Code、CC Switch、DeepSeek V4 Pro 是三个完全不同层面的东西但它们能组成一条看起来“无缝”的链路。Claude Code 是 Anthropic 出的命令行编程助手它负责的是“交互层”。你在终端里让它写代码、改 bug、跑命令、读仓库它把指令组织成对话上下文然后发出请求。它本身不产生模型能力真正的聪明劲在背后的模型服务上。DeepSeek V4 Pro 在这里就是扮演“推理后端”的角色也就是实际干活的模型。它通过 API 提供文本生成能力你发请求过去它把答案返回回来。用户选择它多半是因为它在代码任务上的表现不错而且在成本上比很多前沿模型要友好。这类模型通常走的是 OpenAI 兼容接口也就是说它的接口协议和 OpenAI 那套很接近。问题就在这里Claude Code 默认只会说 Anthropic 的“语言”也就是 Anthropic Messages API 那套协议而 DeepSeek V4 Pro 这类第三方服务通常提供的是 OpenAI 兼容协议。两边协议不一致直接对接会失败。这时候需要有人居中“翻译”把 Anthropic 格式的请求转成 OpenAI 格式再把 OpenAI 格式的响应转回给 Claude Code。干这个活的就是 CC Switch。1.2 协议兼容是整条链路成立的核心我把这个关系说得更直白一点。Claude Code 向模型服务发请求的时候报文结构、鉴权方式、接口路径都是有固定约定的。第三方的 DeepSeek V4 Pro 不一定认这套约定但它认 OpenAI 那套约定。CC Switch 的做法是在本机起一个轻量的转换层监听一个本地端口Claude Code 的请求先发到本地端口再由这个转换层把报文改写成 OpenAI 兼容格式转发给 DeepSeek 的接口。DeepSeek 返回结果后它再把响应改写回 Claude Code 期望的格式。整个过程对用户是透明的你在终端里看到的还是 Claude Code 的交互界面但背后算力已经换成了 DeepSeek V4 Pro。理解这一点对后面排查错误很有帮助。比如你看到报错信息里出现 codex endpoint /responses 这种字眼就知道是 CC Switch 在处理某一个具体接口路径时出了问题而不是 Claude Code 本身崩溃了。后面第 5 节我会专门讲这些错误现在先把这条链路记住就好。1.3 这个组合适合谁不适合谁如果你手头的机器就是 Windows日常开发大量时间在终端里度过并且不想被单一模型服务绑死那这套组合非常适合你。CC Switch 带来的最大好处是切换成本低想用 Claude 官方模型就切回官方想用 DeepSeek 就切到 DeepSeek不需要你手动去改一堆 JSON 和 TOML 配置文件。但也要说清楚这个组合不适合不想折腾的人。虽然我会尽量把步骤写细致但这个方案天然涉及少量配置工作。另外如果你的公司对数据出境、模型供应商选择有严格合规要求那么请务必先确认 DeepSeek API 的使用符合内部规定再落地这套方案。技术可行不等于业务上一定被允许这个判断只能由你自己来做。2. Windows 环境下安装 Claude Code2.1 先确认 Node.js 环境没问题Claude Code 官方推荐通过 npm 全局安装而 npm 是 Node.js 自带的包管理器所以第一步其实是把 Node.js 装好或者说确认它没问题。去 Node.js 官网下载 LTS 长期支持版本就好版本号建议选当前 LTS 或更新一档的不要选那种已经停止维护的很老的版本。Claude Code 对 Node 版本有最低要求我用 Node 20 跑起来完全没问题Node 18 在早期版本上也行但为了少踩坑建议直接用 LTS 里较新的版本。安装 Node.js 的时候有个小细节安装向导里会有一个 Add to PATH 的选项默认是勾选的保持勾选。装完之后一定要新开一个终端窗口再检查。旧窗口里 PATH 环境变量不会自动刷新你输入 node -v 可能还是提示找不到命令这不是装失败了只是终端没读到新配置。node -v npm -v两条命令能正常输出版本号说明 Node 环境没问题。如果你平时习惯用 nvm-windows 这类版本管理器来管理多个 Node 版本那也没问题核心要求是当前 Node 满足 Claude Code 的要求即可。2.2 用 npm 安装并验证命令可用打开 Windows Terminal 或 PowerShell执行这条命令全局安装 Claude Codenpm install -g anthropic-ai/claude-code这里解释两个关键点。第一install 是安装-g 代表全局安装意思是把它装到全局目录而不是某个项目下的 node_modules 里。只有全局安装你才能在任意目录直接执行 claude 命令。第二包名是 anthropic-ai/claude-code这个作用域前缀 anthropic-ai 是 npm 组织包的标准写法一个字母都不能错。装完后验证claude --version如果这条命令返回一个版本号安装就完成了。如果终端提示 claude 不是内部或外部命令最常见的原因是 npm 的全局目录没有在 PATH 里。你可以先执行下面命令看看全局目录在哪npm config get prefix比如输出了C:\Users\你的用户名\AppData\Roaming\npm那就把这个目录手动加到系统环境变量的 Path 里然后重新打开终端再试。这个操作本身不复杂但很多第一次用 npm 全局包的 Windows 用户都会卡在这一步。2.3 第一次启动和接入方式说明装好之后随便进一个项目目录或者新建一个空目录在里面执行claude第一次启动通常需要做认证。Claude Code 有两个官方接入路径一个是用 Claude 账号登录另一个是用 Anthropic API Key。如果你打算沿用官方服务就按交互提示登录或填 Key。但如果你后续要用 CC Switch 接 DeepSeek V4 Pro其实可以在 CC Switch 配置完成后再启动 Claude Code。原因是 CC Switch 会把接口地址和鉴权信息写进 Claude Code 的配置目录Claude Code 启动时会优先读取这些配置请求直接被引导到本地路由服务。这种情况下官方订阅并不是必须的只要你在配置里给了本地路由一个可用的 API KeyClaude Code 会把本地路由当作模型服务来对接。这里有一个容易绕晕的概念CC Switch 里填的那个 API Key并不是 Claude 官方发的而是你在 DeepSeek 开放平台申请的。Claude Code 并不关心这个 Key 是从哪里来的它只负责把 Key 随请求发出去至于路由层怎么处理、转发给谁它管不着。2.4 PowerShell 执行策略等 Windows 专属注意事项Windows 上跑 Claude Code还有几个和系统环境强相关的点要提醒。PowerShell 的执行策略问题。Claude Code 会自带一些脚本如果你用 PowerShell 启动它时遇到类似“禁止运行脚本”的提示说明当前执行策略把脚本拦了。你可以用下面命令查看当前策略Get-ExecutionPolicy如果返回的是 Restricted那就需要放开当前用户的执行策略Set-ExecutionPolicy -Scope CurrentUser RemoteSignedRemoteSigned 的意思是本地创建的脚本可以运行从网上下载的脚本需要有签名这是相对安全的一个档位。改完再启动 claude 就不会被拦了。另外一个常见问题是终端编码。如果 Claude Code 输出中文乱码或者你输入中文提示词时出现异常先检查终端代码页。在 Windows Terminal 里通常默认 UTF-8问题不大如果你用的是老旧的 cmd 窗口可以尝试执行chcp 65001这会把当前代码页切到 UTF-8很多显示乱码的问题都能解决。3. CC Switch 的安装与基础配置3.1 从官方发布渠道获取 Windows 版本CC Switch 是一个开源工具它和其他桌面软件不一样没有哪家官方应用商店给你一键安装装之前你得先会找靠谱的下载源。正规途径是去它的 GitHub 仓库 Releases 页面下载 Windows 安装包。你会在发布列表里看到多个平台的文件Windows 用户主要认两种一种是带 setup 字样的安装包另一种是 zip 格式的便携版。我个人的建议是优先选 zip 便携版解压后直接运行 exe 就能用。原因很简单安装版会往系统里写注册表、装启动项在某些权限受限的开发机上可能会遇到安装权限问题便携版则完全没有这些烦恼解压到任意目录双击运行想换机器了拷走整个目录就行。下载前记得看发布说明里写的系统要求Windows 10 和 Windows 11 基本都是支持的。下载完先别急着双击灰产的伪装安装包挺多解压前用杀毒软件扫一遍这是 Windows 上装任何工具的必备习惯。3.2 认识核心界面提供商、配置项、切换动作CC Switch 首次运行的界面通常不复杂核心是提供商列表和一个大致的切换按钮。你在界面上会看到默认预置的一些提供商比如 Anthropic 官方、OpenAI 这类这些都是内置模板直接改或者新建都可以。它最核心的操作模式是新建提供商、填写参数、点切换到目标应用。所谓“目标应用”通常就是 Claude Code 或 Codex。你切到 Claude Code它会修改 Claude Code 的配置切到 Codex它会修改 Codex 的配置。注意CC Switch 不是像测试工具那样直接发请求的它做的是配置管理分发真正的模型调用还是由 Claude Code 发起的。参数上最核心的是三样Base URL、API Key、模型名称。Base URL 是模型服务的接口根地址API Key 是鉴权凭证模型名称是你要调的那个具体模型标识。这三个参数只要填对链路基本就通了一半。我看到很多报错最后追根溯源都指向这仨没填对后面我会逐个说清楚。3.3 看一把配置文件CC Switch 到底在背后做了什么如果你好奇 CC Switch 切换的一瞬间发生了什么直接去看配置文件是最直观的。以 Claude Code 为例它的配置通常存在用户目录下的.claude文件夹里其中 settings.json 里有一段和网络服务相关的配置大致长这样{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:2024, ANTHROPIC_AUTH_TOKEN: sk-你的密钥, ANTHROPIC_MODEL: deepseek-v4-pro, ANTHROPIC_SMALL_FAST_MODEL: deepseek-v4-pro } }当你点切换按钮后CC Switch 就是把这些配置改写成一个可用的组合。Base URL 指向本地路由服务Auth Token 换成你在对应提供商填写的 API Key模型名换成你指定的模型。这样一来Claude Code 启动时加载配置就知道该往哪里发请求、用什么凭证、报哪个模型名了。看明白这个机制之后你在排查问题时就能多一条思路如果某个配置一直不生效可以直接打开配置文件看 CC Switch 有没有真的把数据写进去。很多“我明明配置了但 Claude Code 还是连官方”的情况本质上就是切换没写入成功或者写到了另一个版本的应用配置目录里。4. 在 CC Switch 中接入 DeepSeek V4 Pro 并让 Claude Code 生效4.1 获取 API Key 的几个安全注意点要接 DeepSeek V4 Pro你肯定得先有一个能用的 API Key。去 DeepSeek 开放平台注册账号之后在控制台里找到 API Keys 管理创建一个新的 Key。创建时会要求你给 Key 起个名字建议写清楚用途比如 claude-code-win这样将来在多个 Key 之间能分辨出来。这里有几条安全原则我必须讲细一点。第一API Key 本质上就是钱它按 token 计费泄露出去等于别人拿你的余额跑任务。第二不要把 Key 硬编码进项目代码里更不要提交到 git 仓库。第三CC Switch 这类工具会把 Key 写进配置文件你要确保这个文件不会因为同步工具被传到公开仓库。另外需要说明一个很实际的问题模型名称有可能在平台侧改名。你现在看到的 DeepSeek V4 Pro 在官方控制台里叫什么请务必以控制台显示的标识为准。我在下文的配置示例里会按最常见的写法填入 deepseek-v4-pro但如果控制台显示的是别的名称你得把配置里的模型名同步改过来否则会出现 404 一类的报错。4.2 添加 DeepSeek 提供商的具体参数在 CC Switch 界面里找到“添加提供商”或类似按钮新建一个配置。参数可以按下面这套来填配置项建议值说明提供商名称DeepSeek V4 Pro自由命名方便识别即可Base URLhttps://api.deepseek.com/v1以官方接口文档为准注意结尾的 /v1 别漏API Keysk-xxxxx你刚在控制台创建的 Key模型名称deepseek-v4-pro以控制台显示的名字为准为什么 Base URL 结尾要带 /v1因为 DeepSeek 的接口兼容的是 OpenAI 那套 API 风格OpenAI 兼容接口通常在根路径下面加 /v1 作为版本前缀很多服务都沿用了这个习惯。如果你漏掉了 /v1请求路径就会拼错CC Switch 转发时很容易得到 404。保存之后在提供商列表里选中这条配置然后点应用到 Claude Code。此时 CC Switch 会执行写入动作把上节的那些环境参数写进 Claude Code 的配置文件里。如果界面提示失败最常见的检查方向是配置文件路径不可写或者 Claude Code 正在运行导致文件被占用。4.3 应用配置到 Claude Code 并完成第一次对话配置写好后重新打开一个终端进入你的项目目录执行claude启动后你先随便问一个和当前项目相关的简单问题观察回复内容。如果模型真的通过 DeepSeek V4 Pro 在回答你会从回复质量和模型署名上看出来也可以通过 CC Switch 界面上的请求日志确认。CC Switch 通常会把请求记录展示出来你能看到请求从本地端口进来、发往了哪个上游地址、返回状态码是多少。这是一个非常有用的验证方式强烈建议你养成看日志的习惯。如果回复正常出现说明整条链路已经通了。这时你可以顺手测一个稍微复杂点的编程任务比如让 Claude Code 读一下当前目录下的某个文件并重构它的一个函数。这么做是为了验证上下文发送是否正常毕竟对话类工具的核心玩法不只是单条问答还要能处理整个项目的代码结构。4.4 如果你同时用 Codex补齐 base_url 配置很多人的开发流里不止 Claude Code还有 OpenAI 的 Codex CLI。CC Switch 对这两者都支持但两者的配置结构和界面入口不同。这里要特别提一个高频报错就是“codex provider 缺少 base_url 配置”。Codex 的配置文件是 .codex/config.toml里面会声明用哪个 provider、连哪个地址。CC Switch 切换到 Codex 时会去改这个文件。如果你只配置了模型名和 API Key但没把 base_url 填进去Codex 启动后会不知道往哪里发请求就会报“缺少 base_url 配置”的错误。正确配置里至少要包含 provider、base_url、api_key 和模型名大致结构如下model deepseek-v4-pro provider deepseek [providers.deepseek] name DeepSeek V4 Pro base_url https://api.deepseek.com/v1 api_key sk-xxxxx如果你发现 CC Switch 的 Codex 配置页面里没有 base_url 输入框或者填了没生效可以手动检查并编辑 config.toml把上面这几行补齐。要强调的是CC Switch 只是一个配置管理工具它不该成为你和配置文件之间的屏障。你自己能看懂它、能手工修这比什么都重要。5. Windows 下高频报错排查手册5.1 codex provider 缺少 base_url 配置这个错误我在第 4.4 节已经提到过这里把它归到排查手册里再强调一次。它的完整报错形态类似于“配置错误codex provider 缺少 base_url 配置”多数出现在切入点 CC Switch 路由服务后、调用 responses 端点的场景。处理步骤按下述顺序来打开 CC Switch 的 Codex 配置页确认 provider 设置里 base_url 是否为空。打开 .codex/config.toml看 [providers.deepseek] 这类 provider 段落里有没有 base_url 行。如果缺失手工补上 https://api.deepseek.com/v1。保存后重启 CC Switch 的本地路由服务再重新发起请求。要提醒的是改完配置文件后最好彻底退出终端会话再重开。Windows 下很多进程会把配置读取缓存住你不重启它改半天也看不到效果。5.2 401 / 404 / 502 / 503 状态码速查表在 CC Switch 的日志里你会看到各种 HTTP 状态码。我这里把最常见的四个码归纳成一张表每个码对应一种典型因果链排查时先对号入座再往下钻。状态码英文含义大概率原因优先排查动作401UnauthorizedAPI Key 无效、过期、或没传对位置核对 CC Switch 里填的 Key与控制台最新 Key 对比404Not FoundBase URL 路径错、模型名不存在检查 URL 末尾的 /v1核对模型名与官方控制台一致502Bad Gateway上游服务连接异常网关层转发失败确认 DeepSeek 平台服务状态稍后重试503Service Unavailable上游过载、限流或本地路由服务没起来检查 CC Switch 是否在运行检查接口限流配额这四个码不是每次都精确指向单一原因但排查方向是明确的。你可能还会遇到 429 配额超限处理方法一般是等一会儿或者去控制台看额度。不管遇到哪个状态码我建议你第一时间去看 CC Switch 的请求日志因为日志里不但有状态码还有完整的请求路径和上游返回信息这些细节比任何容错猜测都更可靠。5.3 端口占用和防火墙拦截怎么处理CC Switch 的本地路由服务是要监听一个端口的比如 2024。如果这个端口被其他程序占用了服务起不来Claude Code 发出去的请求就会一直失败。在 Windows 上排查端口占用我通常先用这条命令netstat -ano | findstr :2024输出里会有一列 PID那就是占用端口的进程标识。接着可以用任务管理器去查这个 PID 对应的进程确认是不是别的服务占了端口。确认无误后要么结束那个进程要么在 CC Switch 设置里改监听端口。结束进程的命令也可以直接在终端完成taskkill /PID 12345 /F把 12345 换成实际 PID 即可。防火墙的问题也很常见尤其当你第一次启动 CC Switch 时Windows Defender 防火墙会弹窗询问是否允许该程序通信。这时要确认是允许在本机监听端口也就是只允许回环地址 127.0.0.1 访问不要漫无目的地开放公网访问。CC Switch 这类本地路由服务只需要本机访问你根本不需要给外部设备开权限。5.4 CC Switch 升级后配置丢失或路径变化怎么办工具升级是把双刃剑新功能往往伴随着配置结构变化。我遇到过几次 CC Switch 升级后之前配置的提供商列表还在但应用到 Claude Code 的配置路径变了导致点切换后没反应。遇到这种情况不要慌也不要去翻旧版本。先看新版的数据目录在哪通常是用户目录下的某个配置文件夹或者便携版同目录下的数据文件夹。找到后和旧配置目录比对把有用的信息迁过去。更稳妥的做法是养成备份习惯。我在 Claude Code 接入第三方服务跑通之后就会把配置文件备份一份到安全的地方。备份范围包括 .codex/config.toml 和 .claude 里的关键配置。注意备份前把 Key 做脱敏处理或者用环境变量引用不然将来这个备份文件一旦泄露就麻烦大了。6. 这套组合用得顺手的几条经验6.1 建立自己的多环境切换工作流配置好 DeepSeek V4 Pro 之后别急着把所有鸡蛋放一个篮子里。我建议你在 CC Switch 里把用到的提供商都建好比如官方 Claude、DeepSeek V4 Pro甚至你们公司内部如果自建了模型服务网关也可以作为另一个 provider 加进去。这样一来你就拥有了一套非常丝滑的多环境切换能力。日常写业务代码可以用 DeepSeek 降低成本遇到需要更强的长上下文理解任务时切回官方模型搞集成测试时切到公司内部环境。每一个切换动作都只是点一下按钮再加重开一次终端不需要手动改任何配置也不容易出现改坏了对线崩了的尴尬局面。我踩过的坑是有些项目会通过环境变量覆盖配置。比如你在系统环境变量里设置了 ANTHROPIC_MODEL那 Claude Code 读配置时环境变量优先级会高过配置文件结果你一帧地切换但模型名不变。遇到这种诡异现象先检查系统环境变量里有没有 Claude Code 相关的设置。6.2 会话恢复和日常使用习惯终端型编程助手的用法和 GUI 工具有点不一样不是打开一个窗口就完事。Claude Code 支持会话恢复你上次跑了一半的任务中途关掉终端下次再进可以用恢复参数接着聊。具体参数在不同版本里略有差异但核心思路是它会把历史会话保存下来按需重新加载。我在日常开发里养成的习惯是每天开工先恢复昨天的会话把遗留问题接着处理完再做新任务。这样上下文是连续的模型不需要反复理解前因后果回答的准确度会明显更好。另外一个习惯是每完成一个阶段任务就主动把结论总结给模型并让它清理临时上下文防止对话太长导致后续响应变慢。在 Windows 上如果你要用多个项目目录一定要在对应的项目目录里启动 Claude Code。Claude Code 很多操作是依赖当前目录的你不在项目目录下它读到的是别的文件修改也可能落到错误的地方。这一点看似基础但实际上很多人忽略。6.3 把配置纳入版本管理但要避开密钥最后分享一个比较进阶的实操建议把配置模板纳入版本管理但千万别把真实 Key 提交进去。你可以把 .codex/config.toml 和 .claude/settings.json 的敏感字段替换成占位符提交一个模板版本到仓库里。这样团队成员拉取代码后复制一份模板填入自己的 Key就能快速跑通同样一套环境。对于团队协作来说这是把踩坑经验沉淀下来的好办法。我在实际操作中有个体会这类工具的组合方案最大的风险永远不是报错本身而是出了问题以后没有日志、没有配置备份、不知道刚刚动过什么。所以哪怕你只是在本地单机使用也强烈建议你保持两个习惯启用日志定期备份配置。真出问题时这两样东西能救你半天时间。最后再分享一个小技巧。在 Windows 上配置完这套链路后我一般会对 CC Switch 做一次冒烟测试专门用一个临时空目录跑会话让它处理一个十行以内的脚本编写任务。因为这个任务非常轻量如果整条链路有问题它会很快暴露出来而不会浪费你下游的时间和 token。等你确认这锅水烧开了再把它引入真实项目体验就会顺畅很多。