DeepSeek 驱动 Claude Code这个组合在 Windows 上到底怎么搭很多朋友第一反应是“装个 npm 包不就行了”真上手就会发现Node.js 环境、npm 全局目录权限、API 端点格式、settings.json 里的模型映射任何一环出错都会让命令行直接罢工。这篇文章不适合零基础看热闹但只要你准备操作就值得把整套流程一次吃透。我会把 Windows 上从安装 Claude Code、拿到 DeepSeek API 密钥到最终在 settings.json 里把两者绑定在一起的完整过程拆开讲清楚每一步为什么这么做以及我实际踩过哪些坑。1. 开工前Windows 上的 Node.js 环境准备1.1 为什么 Claude Code 必须先装 Node.js很多人以为 Claude Code 是个独立安装包双击 exe 就能用。实际上 Claude Code 是一个以 npm 包形式分发的命令行工具它跑在 Node.js 运行时之上。你可以把它理解成Node.js 是“发动机”npm 是“扳手”Claude Code 是“改装件”。发动机没装好后面全白搭。Windows 下的 Node.js 版本选择也需要注意。Claude Code 官方要求 Node.js 18 以上但我建议直接上 20 LTS 或 22 LTS。长期支持版本稳定性好npm 生态兼容性也广避免装完出现一些莫名其妙的模块加载报错。另外安装完 Node.js 之后一定要重新打开终端让 PATH 环境变量生效。这一点听起来像废话但我见过太多人装完不重开终端直接敲node -v报“不是内部或外部命令”然后以为安装失败反复重装。1.2 安装 Node.js 的推荐方式和目录规划去 Node.js 官网下载 Windows Installer.msi 格式安装时注意勾选“Add to PATH”。这个选项默认是开着的但有些精简版安装包或者企业安全策略可能把它关了。安装完成后在 PowerShell 或 CMD 里分别执行node -v npm -v如果两个命令都能输出版本号说明基础环境没问题。如果 node 能跑但 npm 不行大概率是 PATH 里只有 Node 主目录没有 npm 的全局执行目录。继续往下看我会给出明确处理办法。还有个容易踩的坑安装目录选择。如果默认装到C:\Program Files\nodejs后面npm install -g全局安装包时会因为 Windows 的权限体系导致 EPERM 或 EACCES 错误。我更推荐在安装时把 Node.js 装到用户目录下比如C:\Users\你的用户名\nodejs或者干脆安装完成后把 npm 全局目录改到用户目录这个在 1.3 里细说。1.3 配置 npm 全局目录和镜像源先检查当前 npm 全局目录在哪npm config get prefix npm config get registry如果prefix显示的是C:\Program Files\nodejs这种系统保护目录建议改成用户目录npm config set prefix $env:APPDATA\npm在 CMD 里则是npm config set prefix C:\Users\你的用户名\AppData\Roaming\npm这样设置之后npm 全局安装的包都会放到这个目录下不再需要 Administrator 权限。Windows 系统下这是最稳的做法尤其适合公司电脑或开启了 UAC 的机器。registry是 npm 下载源。国内网络环境有时候直接访问官方源会慢得让人怀疑人生甚至出现ETIMEDOUT。我一般会切到 npmmirror 加速npm config set registry https://registry.npmmirror.com切换完成后npm config get registry应该返回 npmmirror 的地址。这个镜像源对anthropic-ai/claude-code同样有效后面安装时能省下不少时间。注意npm 源切到镜像后如果以后要发布自己的 npm 包记得切回官方源。日常使用影响不大但发布流程上容易踩坑。2. 安装 Claude Codenpm 一条命令后的 Windows 坑2.1 执行全局安装环境准备好之后安装 Claude Code 其实就一条命令npm install -g anthropic-ai/claude-code-g表示全局安装也就是说你可以在任意目录下直接使用claude命令。如果不加-g包只会装进当前项目的node_modules那每次都要用npx才能启动极其麻烦。安装过程中npm 会从 registry 拉取包文件。如果卡了很久没动静大概率是网络问题可以先检查 registry 配置也可以试试下面这条命令确认包的远程最新版本npm view anthropic-ai/claude-code version能输出版本号说明源是通的不能输出就去排查 1.3 提到的 registry 设置。安装完成后命令行末尾会显示安装成功的提示。如果你在 1.3 配置了用户目录作为 npm 全局目录那么claude.cmd这个启动脚本会被写到C:\Users\你的用户名\AppData\Roaming\npm下。接下来要做的是验证。2.2 验证安装并修复 PATH在任意新开的终端里执行claude --version如果能看到类似1.x.x的版本号恭喜你CLI 已经装好了。如果提示“claude 不是内部或外部命令”说明npm prefix -g配置的目录没有进入 PATH。先查一下实际目录npm prefix -g然后把输出结果目录追加到系统环境变量 PATH 里。Windows 11 的操作路径是设置 → 系统 → 系统信息 → 高级系统设置 → 环境变量 → 在“用户变量”中找到 Path → 编辑 → 新建 → 把目录粘贴进去。修改完记得重新打开终端。也有的人会在 PATH 里同时出现C:\Program Files\nodejs和用户 npm 目录导致冲突。我个人的习惯是只保留一个 npm 全局目录避免claude命令被旧目录里的同名脚本覆盖。这种“明明装了但版本不对”的问题大多就是 PATH 顺序或者重复目录引起的。2.3 Windows 下的权限与重装问题安装过程中遇到权限问题的典型表现是npm ERR! code EPERM npm ERR! syscall mkdir这个报错的根源几乎都是我前面提到的npm 把全局包写到了受系统保护的位置。解决办法不是去管理员终端里死磕而是把prefix改到用户目录然后重装npm uninstall -g anthropic-ai/claude-code卸载完成后再执行一次全局安装。如果之前安装了一部分残留文件npm cache clean --force可以稍微帮忙但我不建议一上来就清缓存先检查目录权限更高效。还有一类问题是启动闪退。你在 PowerShell 里敲claude窗口一闪而过或者直接退出没有任何报错。这种情况经常和终端代码页有关可以先执行。chcp 65001把代码页切成 UTF-8再运行claude。Windows 终端里中文路径、中文提示符有时候会和 CLI 的渲染逻辑打架切到 UTF-8 基本能缓解。经验不要一报错就重装系统或者换 Linux。Windows 下跑 Node 系 CLI90% 的安装问题集中在 PATH、npm 目录权限、终端编码这三个点上。3. DeepSeek API 密钥与 Anthropic 兼容端点3.1 注册 DeepSeek 开放平台并创建密钥Claude Code 本身是个客户端它需要有一个模型后端来响应代码生成、工具调用这些请求。DeepSeek 因为价格便宜、推理能力强成了很多人拿来替代官方 Claude API 的选择。先去 DeepSeek 开放平台注册账号进入控制台后找到 API Keys 页面创建一个新的密钥。密钥格式是sk-开头的一串字符和 OpenAI 的格式长得有点像。创建之后要立刻保存到自己的密码管理器里因为很多平台只显示一次刷新页面之后就不给你看完整原文了。DeepSeek API 是预付费模式也就是说账户里需要先充值才能调用。别充太多按我实际使用的量来看日常写代码、改 bug、做点小项目几十块能用很久。具体价格文档变动比较快以平台显示为准。3.2 为什么需要“兼容端点”这里有一个核心概念需要讲清楚Claude Code 用的是 Anthropic 官方 Messages API 协议请求的路径、请求体格式、鉴权头发送方式都是 Anthropic 风格。而 DeepSeek 原生 API 是 OpenAI 风格的 Chat Completions 协议。两边协议不一致直接填 API Key 进去是不行的。要打通链路就得让 Claude Code 发出的 Anthropic 格式请求到达一个能“翻译”成 DeepSeek 格式的端点。目前最简单的做法是使用 DeepSeek 官方提供的 Anthropic 兼容入口base URL 是https://api.deepseek.com/anthropic这个地址的作用是接收 Anthropic 协议请求然后在网关层转换成 DeepSeek 模型需要的格式最后把响应再翻译回 Claude Code 能读懂的格式。如果不用官方兼容端点也可以自建网关比如用 new-api 或 one-api 这类开源网关做协议转换。这样做灵活性更高还能把多个模型接入统一管理但对个人开发者来说维护成本不小。我自己的建议是能直接用官方兼容端点就不折腾网关除非你要同时接多个模型或者有团队共享需求。3.3 选择 deepseek-chat 还是 deepseek-reasonerDeepSeek 提供了两个主要模型参数deepseek-chat和deepseek-reasoner。deepseek-chat对应的是通用的对话模型速度快、价格低适合日常代码补全、解释、重构、写测试这些场景。我用 Claude Code 跑常规任务时基本都选它。deepseek-reasoner对应的是推理增强模型处理复杂架构设计、多步骤调试、数学逻辑类问题表现更好但响应时间和成本都会更高。如果你要让 Claude Code 解决一个特别绕的 bug或者让它设计一个独立的模块可以临时切到deepseek-reasoner。Claude Code 默认会请求 Sonnet、Haiku 这些 Anthropic 模型名如果不做映射直接让它跑 DeepSeek 后端就会得到“模型不存在”之类的 404 错误。所以 4.2 里的模型映射配置才是整个流程的关键别跳过。提示第一次配置建议先老老实实用deepseek-chat跑通链路再考虑切换到deepseek-reasoner。否则一旦遇到问题你很难判断是模型能力问题还是配置问题。4. settings.json 配置全解析核心章节4.1 Claude Code 的配置文件优先级Claude Code 在 Windows 下的配置目录默认在用户主目录下C:\Users\你的用户名\.claude\settings.json这就是“用户级”配置文件对所有项目生效。除了用户级还有项目级和本地级用户级C:\Users\你的用户名\.claude\settings.json项目级项目根目录\.claude\settings.json本地级项目根目录\.claude\settings.local.json三个配置文件的加载顺序是用户级 → 项目级 → 本地级后面的覆盖前面的同名配置项。也就是说你可以在全局配置好 DeepSeek 端点在具体项目里再用本地配置调整模型或权限。我一般这样分配API 密钥和 base URL 这类敏感信息放用户级模型映射放用户级项目级只放权限规则settings.local.json 放在.gitignore里不提交到版本库。这样既保证开箱即用又不会把密钥泄露给团队其他人。4.2 核心 env 字段Base URL、Token、模型映射这是整个配置里最核心的部分。下面是一份可以直接套用的 settings.json 示例{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: sk-你的DeepSeek密钥, ANTHROPIC_MODEL: deepseek-chat, ANTHROPIC_SMALL_FAST_MODEL: deepseek-chat, ANTHROPIC_DEFAULT_HAIKU_MODEL: deepseek-chat, ANTHROPIC_DEFAULT_SONNET_MODEL: deepseek-chat, ANTHROPIC_DEFAULT_OPUS_MODEL: deepseek-chat }, permissions: { allow: [ Read, Edit, Write, Glob, Bash(npm install), Bash(npm run dev) ] } }逐项说。ANTHROPIC_BASE_URL决定 Claude Code 内部所有 API 请求发到哪个地址。这里必须写成https://api.deepseek.com/anthropic而不是https://api.deepseek.com。因为后者只有 OpenAI 格式接口Claude Code 发出去的 Anthropic 格式请求会被当成非法请求。ANTHROPIC_AUTH_TOKEN是 Bearer TokenClaude Code 会将这个值放到请求头的Authorization: Bearer token里。为什么不用ANTHROPIC_API_KEY因为ANTHROPIC_API_KEY会触发 Claude Code 发送 Anthropic 官方习惯的x-api-key头某些兼容网关上并不认这个头容易 401。如果你看到 401 错误把ANTHROPIC_API_KEY改成ANTHROPIC_AUTH_TOKEN是一个很有效的排查动作。然后是模型映射。ANTHROPIC_MODEL是默认主模型ANTHROPIC_SMALL_FAST_MODEL是轻量快模型Claude Code 会在某些场景下用它来做分类、摘要之类的辅助任务。ANTHROPIC_DEFAULT_HAIKU_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL则是覆盖官方默认的 Haiku、Sonnet、Opus 请求。这些字段全部指向deepseek-chat核心目的是不管 Claude Code 内部想调什么名字的 Claude 模型最终到 DeepSeek 网关都会被替换成deepseek-chat。只要有一个字段没覆盖就可能出现某个功能请求claude-3-5-haiku之类的模型名然后返回 404。4.3 用 claude config set 命令替代手改 JSON很多读者看到 JSON 就头大其实 Claude Code 提供了命令行配置工具可以不动文件就完成设置claude config set --global env.ANTHROPIC_BASE_URL https://api.deepseek.com/anthropic claude config set --global env.ANTHROPIC_AUTH_TOKEN sk-你的DeepSeek密钥 claude config set --global env.ANTHROPIC_MODEL deepseek-chat执行后 Cloude Code 会把配置写进用户级 settings.json。这个方法适合远程排查、快速修改但它有一个明显的缺点命令行历史里会留下明文密钥。如果你在共享机器上操作或者担心终端记录泄露我更推荐手动编辑文件不要用命令去写 Token。实际上我现在的习惯是敏感字段全部走系统环境变量settings.json 里只做引用说明。Windows 下可以用setx设置setx ANTHROPIC_AUTH_TOKEN sk-你的DeepSeek密钥设置完必须新开终端让进程读取到新的环境变量。然后 settings.json 里就不写 Token 字段。这样即使配置文件被同步到网盘或提交到 Git敏感信息也不会跟着跑。4.4 权限、Hooks 与本地覆盖Claude Code 默认会针对命令执行做确认弹窗。如果你不想每次都手动点头可以通过permissions.allow白名单放行一些安全操作。我习惯放行Read、Edit、Write、Glob这类文件操作以及npm install、npm run dev这类无破坏性的项目命令。对于危险命令比如rm -rf、taskkill应该进denypermissions: { deny: [ Bash(rm -rf /d), Bash(taskkill /F *) ] }注意 Windows 下/d参数和路径处理跟 Linux 不太一样但 Claude Code 识别的是命令字符串本身所以你必须写清楚到底禁谁。Hooks 是 Claude Code 另一个高级能力它允许你在工具调用前后触发外部脚本。比如我想让每次 Bash 命令执行前先写入日志就可以加hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: node D:/scripts/pre-bash.js } ] } ] }这个功能适合给团队加审计、限制敏感命令、或者做自定义规则。个人使用频率不高但知道存在就行后面真需要时能省不少搜文档的时间。5. 实操演示从首次启动到跑通一次代码任务5.1 创建全局配置并检查 JSON 是否合法先把配置文件的目录建出来。在资源管理器地址栏输入%USERPROFILE%\.claude如果不存在就新建一个.claude文件夹然后在里面新建settings.json用编辑器打开并粘贴 4.2 的示例。需要注意一定要用英文引号别用输入法自动补全成中文引号。这一步出错的人特别多JSON 解析器可不认识中文标点。粘贴完保存后可以用 Node.js 快速验证 JSON 是否合法node -e const fsrequire(fs);const pprocess.env.USERPROFILE/.claude/settings.json;console.log(JSON.parse(fs.readFileSync(p,utf8)));如果终端输出了配置对象而不是报错说明 JSON 语法没问题。也可以直接让 Claude Code 自己验证claude config get --global env如果返回了 env 对象说明 CLI 已经能读取到全局配置。5.2 启动 Claude Code 并确认请求地址配置完成后在项目目录打开终端输入claude首次启动应该会出现欢迎界面。这时候先输入/status检查当前模型信息。如果显示的是deepseek-chat之类的名字说明模型映射已经生效。我更推荐加--debug启动一次claude --debug--debug模式会把每次 API 请求的详细信息打印到终端包括请求 URL、状态码、耗时。你要找的关键信息是请求地址是否包含https://api.deepseek.com/anthropic。如果看到了这个地址而且状态码是 200说明整条链路已经完全打通。如果看不到请求地址或者报 404、401不要急着改配置先把日志文件翻出来。日志目录一般在这里%USERPROFILE%\.claude\logs里面按日期存放着运行日志搜索ANTHROPIC_BASE_URL或者ERROR关键字能更快定位问题。5.3 一个实际任务示例链路通了之后找一个纯文本项目或随便一个测试目录做真实任务。比如我先创建一个空目录放两个零散文件project-demo/ tools/ calc.py README.md然后在目录里启动claude输入请读取当前目录结构然后帮我在 README.md 里写一段项目介绍内容包括 tools/calc.py 这个文件名可以透露的功能。Claude Code 的正常反应应该是先触发工具调用读取目录和文件然后生成文本再调用 Write 工具写入 README.md。整个过程中你会看到顶部工具调用列表不断变化比如 Glob、Read、Write 出现最终有一条“完成”的提示。如果模型响应很快但工具调用迟迟不执行或者工具调用一直失败很可能是兼容层对工具调用协议转换不完整。先升级 Claude Code 到最新版本再看问题是否复现。通常这类问题会伴随tool_call相关的报错我放在第 6 部分一起分析。额外说一句如果你不是在全空目录测试而是在真实项目里用建议先开一个分支或者使用测试目录跑通一次再投入日常使用。原因是 Claude Code 的 Write 权限默认对当前目录内文件生效一旦涉及修改真实业务文件失误成本比学习成本高得多。6. 常见问题排查与 Windows 环境避坑6.1 高频报错速查表下面这张表是我在 Windows 上配置 Claude Code DeepSeek 时遇到频率最高的几类问题基本能覆盖 80% 的启动失败场景。现象可能原因处理方式claude不是内部或外部命令npm 全局目录不在 PATH执行npm prefix -g把结果目录加入用户 PATH重开终端启动报Cannot find moduleNode 版本过旧或安装损坏升级 Node 到 20重新执行npm install -g anthropic-ai/claude-code请求返回 401 UnauthorizedToken 写错或鉴权头不对确认ANTHROPIC_AUTH_TOKEN是sk-开头尝试用环境变量而不是文件请求返回 404 model not found模型名没映射检查ANTHROPIC_MODEL和ANTHROPIC_DEFAULT_*_MODEL是否指向deepseek-chat请求超时或连接中断网络策略或系统代理拦截检查代理配置确认localhost和 API 域名是否走了错误代理工具调用频繁失败Claude Code 版本过旧或兼容层问题升级 Claude Code测试时优先用deepseek-chat终端中文乱码代码页不是 UTF-8先执行chcp 65001或在 Windows Terminal 设置默认 UTF-86.2 Windows 特有的端口、乱码和权限问题Windows 上还容易出现一个比较隐蔽的坑系统端口被占用导致本地调试服务起不来。比如 Claude Code 生成的代码尝试启动某个开发服务器默认端口是 8080但已经有别的进程占用了这时候开发服务器会崩Claude Code 误以为代码写错了。排查命令如下netstat -ano | findstr :8080输出结果里最后一列就是占用端口的进程 PID。如果要结束它taskkill /PID 进程号 /F注意一定要确认进程身份别乱杀。如果发现是系统关键进程建议救火改代码里的端口配置而不是强行结束进程。乱码问题在 Windows Terminal 下经常表现为中文划痕、方框。修改方法有两个第一是在终端窗口标题栏右键 → 属性 → 字体/编码切换成 UTF-8第二是每次启动前执行chcp 65001。Claude Code 的交互界面里如果有中文统一使用 UTF-8 能大幅减少渲染异常。还有一个权限问题容易被忽略如果你用 Visual Studio Code 的集成终端启动claude但 VSCode 本身是以管理员身份打开的那么 Cloude Code 创建文件和执行命令的权限范围会变得很宽松。这不是 bug但容易让不熟悉 Windows 权限的人产生困惑。我建议普通开发尽量用非管理员模式打开 VSCode权限隔离更安全。6.3 我实际的配置习惯与最后提醒说了这么多分享一下我目前在 Windows 上的最终配置习惯。全局 settings.json 里只写这些{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: ${ANTHROPIC_AUTH_TOKEN}, ANTHROPIC_MODEL: deepseek-chat, ANTHROPIC_SMALL_FAST_MODEL: deepseek-chat, ANTHROPIC_DEFAULT_HAIKU_MODEL: deepseek-chat, ANTHROPIC_DEFAULT_SONNET_MODEL: deepseek-chat, ANTHROPIC_DEFAULT_OPUS_MODEL: deepseek-chat } }密钥通过系统环境变量注入不在配置文件里出现明文字符串。需要切换思考模型的时候我很少去改全局配置而是在项目文件夹下新建一个.claude/settings.local.json临时覆盖主模型{ env: { ANTHROPIC_MODEL: deepseek-reasoner } }用完就删不影响其他项目。这个方式比改全局文件干净得多也不怕把个人偏好带到团队项目里。我正式跑通之后还发现一个规律如果某个任务在 DeepSeek 后端上表现不稳定先检查是不是模型名映射没生效再检查是否工具调用格式被网关转换出问题。不要一上来就质疑 DeepSeek 模型的能力。模型在普通 API 调用上表现很好但 Claude Code 这种强 Agent 场景对协议转换层的要求更高优先保证 Claude Code 和网关版本都更新到最新。最后还有一点Windows 上的 Node.js 生态比 Linux 稍敏感但只要安装阶段把 PATH、prefix、registry 三件事理顺后面 Claude Code 的体验不会比 macOS 差太多。这个组合的价值在于你不需要持有昂贵的 Claude API 额度也能体验到 Claude Code 的 Agent 式交互同时还能享受 DeepSeek 的性价比。对我而言这个搭配已经成为日常写代码的默认选择了。