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 Code：npm 一条命令后的 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 系 CLI，90% 的安装问题集中在 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-reasoner

DeepSeek 提供了两个主要模型参数：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 Token，Claude 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，应该进deny：

"permissions": { "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 fs=require('fs');const p=process.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% 的启动失败场景。

6.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 的性价比。对我而言，这个搭配已经成为日常写代码的默认选择了。