最近总有人私信问我“Claude Code 是不是只能在官方模型下跑我这台 Windows 机器到底能不能用上它”其实早在 DeepSeek 官方开放 Anthropic 兼容接口之后这事就变得非常简单了——Claude Code 的项目管理和 Agent 能力能直接用 DeepSeek 的模型来驱动而且整个接入路径不需要任何额外网络通道国内服务器直连就行。这篇文章我就在 Windows 上把完整流程走一遍从装 Node、装 Claude Code到手工写好 settings.json 文件、把模型指向 DeepSeek再到常见的报错怎么排全部按实操记录来写。看过我旧文的朋友知道我平时不怎么爱写“纯安装教程”因为这类文章两三个月就过期。但这个主题不一样Claude Code 的配置机制很稳定DeepSeek 的兼容接口又是官方功能你只要理解清楚“环境变量 → settings.json → 模型请求”这条链路哪怕以后版本升级、字段改名你也能自己跟上。这篇文章适合刚接触 Claude Code 的新手也适合已经装过、但不知道怎么切模型的 Windows 用户。我会把为什么这么配、字段背后的含义、以及我在 Windows 上踩过的坑都讲明白。1. 先搞清楚原理为什么 DeepSeek 能让 Claude Code 跑起来如果只照着教程敲命令出问题你还是不知道怎么修。所以我先花几百字把背后的机制讲透这部分理解了后面每一步都是顺理成章的事。1.1 Claude Code 的通路设计Claude Code 是 Anthropic 推出的命令行编程助手本质是一个 Node.js 写的 Agent 客户端。它负责接收你的自然语言指令、规划任务、读取文件、执行终端命令然后基于“模型返回的文本”继续推进工作。问题在于Claude Code 官方默认只走 Anthropic 自家 API。这意味着你需要一个有效的 Anthropic API Key还要能访问它的接口地址。对国内用户来说这两个条件都不太友好。但 Claude Code 的设计留了个后门它允许通过环境变量ANTHROPIC_BASE_URL来改写请求要发往的 API 地址。只要目标服务实现了 Anthropic Messages API 兼容协议客户端就能透明地把流量转过去。这正是 DeepSeek 能驱动 Claude Code 的根本原因——DeepSeek 官方提供了https://api.deepseek.com/anthropic这个兼容端点专门给 Claude Code、Cline 这类 Anthropic 生态工具使用。1.2 DeepSeek 的兼容端点与 OpenAI 端点有什么区别很多人容易混淆DeepSeek 不是有 OpenAI 兼容接口吗那我直接把ANTHROPIC_BASE_URL指到https://api.deepseek.com/v1行不行答案是行不通的或者说不建议。原因是两边协议不同。OpenAI 兼容接口用的是/chat/completions这个路径请求体结构是messages数组、max_tokens这些字段。而 Claude Code 发出去的是/v1/messages请求体里带的是system、model、max_tokens响应里返回的是content块数组。你把 OpenAI 端点塞给 Claude Code请求格式对不上轻则报 404重则返回一堆解析错误。DeepSeek 的 Anthropic 兼容接口专门做了协议转换它能把 Anthropic 风格的请求翻译给自家模型再把结果转成 Anthropic 风格的响应。简单理解就是Claude Code 只会说“Claude 语”DeepSeek 官方给翻译了。1.3 这种方案的收益与代价用 DeepSeek 驱动 Claude Code最直接的好处有两个一是成本DeepSeek 的定价比 Claude 官方 API 便宜一个数量级日常重构、写测试、批量改代码跑起来不心疼二是便利DeepSeek 在国内就能直连注册、充值、调用都没有账号门槛不需要额外折腾支付方式和网络通道。代价也得说清楚。DeepSeek 模型和 Claude 模型在代码生成风格上确实有差异Claude Code 里很多针对 Claude 优化过的提示词模板换到 DeepSeek 上不一定发挥出 100% 的效果。我的实测感受是日常任务足够用复杂架构设计还是官方模型更稳。另外DeepSeek 兼容端点对某些高级功能如工具调用的细节处理偶尔会出现不稳定所以生产环境大规模使用前建议先小范围测试。2. Windows 环境准备与安装部署原理讲完开始动手。整个安装链路是Node.js → npm → Claude Code CLI → 配置环境变量 → 运行验证。Windows 上这一步有几个地方和 macOS 不一样我会重点标注。2.1 安装 Node.js 与 npmClaude Code 是 npm 包所以第一件事是装 Node.js。官方要求 Node 版本 18 以上我建议直接装最新的 LTS 版本写这篇文章时是 20.x / 22.x避免老版本出现兼容问题。到 nodejs.org 下载 Windows Installer.msi一路下一步即可。这里有个小坑安装时默认会把 npm 全局目录放在C:\Users\你的用户名\AppData\Roaming\npm而不是直接塞进 Node 安装目录。装完以后务必打开 PowerShell 验证一下node -v npm -v如果提示“node 不是内部或外部命令”大概率是安装时没把 Node 加进 PATH或者你用了绿色版。重装一次勾选 “Add to PATH” 即可。2.2 用 npm 安装 Claude Code打开 PowerShell建议用 Windows Terminal后面会说为什么执行npm install -g anthropic-ai/claude-code国内网络环境下npm 直装大包经常超时。如果你卡在下载阶段先把 npm 镜像切换到淘宝源npm config set registry https://registry.npmmirror.com再重新安装。装完验证claude --version能打出版本号就说明安装成功。如果提示 “claude 不是内部或外部命令”去检查%APPDATA%\npm是否在系统 PATH 里。PowerShell 里可以用$env:Path查看缺了就手动补上。2.3 首次启动与登录通道选择安装完成后直接输入claude会进入交互界面。首次运行通常会出现登录引导让你用 Anthropic 账号授权或输入 API Key。这一步你可以直接跳过因为我们后面要用ANTHROPIC_BASE_URL把流量转到 DeepSeek根本不走 Anthropic 官方通道。注意Claude Code 的登录状态和 API Key 是两套机制。如果你是纯 API Key 模式一般会看到类似 “API key:” 的输入提示如果没看到可以直接退出先去配置环境变量再回来启动。2.4 用命令行验证联通性配置环境变量之前我习惯先用一个最小请求验证 DeepSeek 的 Anthropic 接口到底能不能通。在 PowerShell 里执行$env:ANTHROPIC_BASE_URL https://api.deepseek.com/anthropic $env:ANTHROPIC_AUTH_TOKEN sk-你的DeepSeek密钥 $env:ANTHROPIC_MODEL deepseek-chat claude进入交互界面后随便问一句 “你好请输出一行 hello world 的 Python 代码”。如果模型正常回复说明整条链路已经通了。接下来真正的工作是让这些配置固化下来而不是每次启动都重新敲一遍——这就轮到 settings.json 出场了。3. settings.json 配置详解核心章节前面能跑通只是临时的PowerShell 窗口一关环境变量就没了。要让每次打开 Claude Code 都自动走 DeepSeek必须把配置写进 settings.json 里或者写进 Windows 系统环境变量。这章是全文的重头戏。3.1 配置文件在哪、优先级是怎样的Claude Code 的配置文件采用多级继承机制。它会在几个固定位置寻找 settings.json优先级从高到低大致是优先级配置来源路径Windows1项目级配置项目目录\.claude\settings.json2用户级配置%USERPROFILE%\.claude\settings.json3系统环境变量Windows 环境变量面板 / PowerShell $env高优先级会覆盖低优先级里的同名配置项。我的建议是把 DeepSeek 的 API 地址和 TOKEN 写在用户级配置里也就是C:\Users\你的用户名\.claude\settings.json这样所有项目都自动生效如果某个项目需要临时切换模型再在项目目录里放一个.claude\settings.json覆盖它。创建用户级配置文件有两种方式。一种是让 Claude Code 自己生成启动后输入/config它会打开编辑器并创建默认配置。另一种是手动创建notepad $env:USERPROFILE\.claude\settings.json如果提示文件不存在选择“是”新建即可。Windows 上我用 notepad 是因为它默认支持 UTF-8 编码避免中午乱码问题。3.2 关键字段逐项拆解settings.json 本质是一个 JSON 对象常用字段包括env、permissions、model、apiKeyHelper、hooks等。这里我只拆解和 DeepSeek 接入强相关的几个。第一个是env。这个字段是环境变量注入区Claude Code 在启动子进程、发起 API 请求时都会读取这里。我们最需要配的就是它内部的ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL。第二个是顶层model字段。它可以直接指定默认模型老版本尤其管用。它的作用范围和env.ANTHROPIC_MODEL基本一致但优先级略低一些。我推荐只在env里配ANTHROPIC_MODEL因为更贴近 Claude Code 官方的配置习惯也方便和系统环境变量保持同一种格式。第三个是permissions。这个字段控制 Claude Code 在什么情况下需要向你申请权限可以填allow和deny数组用的是正则表达式来匹配请求类型。配置得当可以减少大量的人工确认配置不当也可能带来风险后面我会展开。至于apiKeyHelper、hooks这类字段DeepSeek 接入场景基本用不上先不多讲。3.3 最小可用配置示例下面是一份我实测可用的用户级 settings.json直接复制到%USERPROFILE%\.claude\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 }, permissions: { allow: [ Read(.*), Write(.*), Bash(git *), Bash(npm *), Bash(node *) ], deny: [ Bash(rm -rf *) ] } }逐个解释一下ANTHROPIC_BASE_URL请求地址必须是https://api.deepseek.com/anthropic注意结尾不要加斜杠也不要写成/v1。ANTHROPIC_AUTH_TOKENDeepSeek 开放平台的 API Key格式是sk-开头。ANTHROPIC_MODEL主模型deepseek-chat对应 DeepSeek-V3日常编码用它性价比最高。ANTHROPIC_SMALL_FAST_MODEL小模型Claude Code 会用它处理标题生成、对话摘要等轻量任务。如果不设置它默认去找claude-...开头的模型那肯定会失败所以这个字段务必配上。permissions允许自动执行读取、写入、git、npm、node 命令禁止rm -rf这类危险命令。保存文件后完全退出 Claude Code重新启动配置才会重新加载。3.4 Windows 特有的环境变量坑我在 Windows 上配置时踩过三个坑值得单独说明。第一个是 PowerShell 里的$env:只对当前窗口生效。你在这个窗口设了变量开新窗口又没了容易让人误以为配置没生效。跨会话持久化可以用setx命令但注意setx对变量值有一定截断风险密钥较长时偶尔会写入不完整而且setx设置完不会立刻反映到当前窗口要新开一个终端才有效。第二个是中文用户名问题。如果 Windows 用户名是中文%USERPROFILE%展开后路径里带中文某些工具可能解析异常。好在 Claude Code 对这个场景兼容得不错但如果你遇到奇怪的路径报错优先检查这一点。第三个是换行符和编码。PowerShell 里写$env:ANTHROPIC_AUTH_TOKEN sk-你的密钥时如果密钥复制进去带了隐藏换行所有请求都会 401。我习惯先把密钥粘到记事本里看一眼再粘贴到终端或 JSON 里。3.5 权限模型与自动审批规则很多新手不知道permissions参数怎么写就干脆不写。结果 Claude Code 每次要读文件、跑命令都会弹确认框非常打断心流。它的匹配规则其实是“请求类型 正则”。Claude Code 内部会把一次操作描述成Read(具体路径)、Write(具体路径)、Bash(具体命令)、Edit(具体路径)等格式然后拿你的正则去匹配。比如Read(.*)就是允许读取任意路径Bash(git *)就是允许所有 git 开头的命令。我的建议是个人开发机可以适当放宽读写权限但命令权限要收窄。永远不要把Bash(.*)放进 allow尤其别用 DeepSeek 这类外部模型配合全放开模式——模型生成命令偶尔会抽风万一写出个rm -rf D:\你就哭了。4. 从安装到跑通完整实操记录设置文件讲透了我按一次真实的 Windows 实操流程把从零到能用的全过程再过一遍。你照着做基本不会出岔子。4.1 第一步申请 DeepSeek API Key去 DeepSeek 开放平台注册账号进入“API Keys”页面新建一个密钥。密钥创建后只显示一次务必立刻复制保存。创建后记得在“计费管理”里充一点钱哪怕几块钱也行DeepSeek 是预付费模式余额为零时所有 API 请求都会失败报错还不太明显。Key 的格式是sk-开头的一长串字符。拿到后先放一边后面配置用。4.2 第二步配置环境变量两套方案任选方案 A只改系统环境变量适合你希望 Claude Code 之外的其他工具也读取到这些变量的场景。右键“此电脑 → 属性 → 高级系统设置 → 环境变量”在“用户变量”里新建三个变量变量名变量值ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropicANTHROPIC_AUTH_TOKENsk-你的DeepSeek密钥ANTHROPIC_MODELdeepseek-chat保存后要么重启控制台要么在新开的终端里验证。方案 B只写 settings.json这是我最推荐的方式。因为配置跟着.claude目录走以后迁移、重装、换电脑把整个目录拷走即可。正文已经在第三章给出完整 JSON不再重复。两个方案也可以同时用以 settings.json 为准因为用户级配置的优先级高于环境变量里同名项目。4.3 第三步启动并验证无论哪个方案配置完成后都这样验证claude进入交互界面后输入/status注意看输出的模型名如果显示deepseek-chat而不是claude-...说明配置生效了。再输入/model可以确认当前可用的模型列表正常情况下会显示deepseek-chat和deepseek-reasoner两个选项。如果只显示一个说明ANTHROPIC_SMALL_FAST_MODEL可能没配全。然后直接让 Claude Code 做一个实际任务比如让它扫描当前目录并写一份 README。这个过程会验证工具调用是否正常。我的经验是能正常读写文件能执行git status才算彻底跑通。4.4 第四步日常使用中的模型选择DeepSeek 目前对外提供两个模型deepseek-chatV3和deepseek-reasonerR1。它们都可以通过同一个 Anthropic 兼容端点访问区别在于deepseek-chat快速、便宜、响应稳定适合日常写代码、改 bug、生成测试、解释代码。deepseek-reasoner推理能力更强处理复杂架构设计、跨文件重构、疑难问题定位时效果更好但延迟明显更高价格也更贵。我日常默认用deepseek-chat遇到单次任务特别复杂时通过claude界面里的/model命令临时切到deepseek-reasoner任务结束再切回来。这样既省钱又省时间。注意只有你把ANTHROPIC_MODEL设成deepseek-reasoner时会话才会持续使用推理模型否则它只是被当作普通模型调用不会触发完整推理链。5. 常见问题排查与避坑实录配置完成后最让人头疼的就是各种报错。下面是我汇总的 Windows 环境下高频问题按现象、原因、解法整理成速查表。现象可能原因解法启动报AuthenticationError/ HTTP 401ANTHROPIC_AUTH_TOKEN没配或密钥错误检查 settings.json 里密钥是否完整粘贴时有没有带换行到 DeepSeek 平台重新复制报 403 /Access Denied账户余额不足或接口权限未开通去开放平台确认余额充值后再试报model not found/not_found没设置ANTHROPIC_MODELClaude Code 默认请求claude-3-5-sonnet等不存在的模型在 env 或环境变量里显式设置deepseek-chat小任务报错大任务正常ANTHROPIC_SMALL_FAST_MODEL没配置在 env 里加ANTHROPIC_SMALL_FAST_MODEL: deepseek-chatclaude不是内部或外部命令npm 全局目录不在 PATH把%APPDATA%\npm加入 PATH重开终端安装时 npm 超时网络问题或 registry 默认源慢npm config set registry https://registry.npmmirror.com后重装claude启动后黑屏或中文乱码Windows 终端编码问题改用 Windows Terminal或运行chcp 65001切 UTF-8settings.json 改了但没生效修改期间 Claude Code 正在运行或 JSON 语法错误完全退出进程重启用记事本另存为 UTF-8 格式检查大括号和逗号频繁报 429 / 限流DeepSeek 账户并发限制或余额不足降低任务并发检查计费临时换deepseek-chat降低负载5.1 认证 401 / 403 的排查思路认证问题 90% 都出在ANTHROPIC_AUTH_TOKEN上。首先确认你这个字段的拼写对不对很多人会顺手写成ANTHROPIC_API_KEY那是另一个变量Claude Code 走外部兼容端点时只认AUTH_TOKEN。其次把 settings.json 里的值复制出来在 PowerShell 里手动拼一个请求测试$headers { x-api-key sk-你的DeepSeek密钥 anthropic-version 2023-06-01 content-type application/json } $body {model:deepseek-chat,max_tokens:50,messages:[{role:user,content:ping}]} Invoke-RestMethod -Uri https://api.deepseek.com/anthropic/v1/messages -Method Post -Headers $headers -Body $body能返回消息就说明 Key 和接口都没问题问题出在 Claude Code 配置上返回 401说明 Key 本身有问题。5.2 模型不存在的坑这是切换到 DeepSeek 后最常见的报错文字里通常带model_not_found或not_found。原因很简单Claude Code 默认把自己惯用的claude-3-5-sonnet-20241022或类似名称放进请求DeepSeek 端不认识这个模型名。解决办法就是显式声明模型。我建议不只在上层env里配置也顺手在 settings.json 顶部加一行model: deepseek-chat双保险。某些旧版本对顶层 model 支持更稳定而新版本更认env.ANTHROPIC_MODEL。两个一起写不会冲突后者生效。5.3 启动速度慢或卡在欢迎界面如果你配置没问题但claude进入交互界面特别慢大概率是网络请求超时。Claude Code 启动时会做一些预检和远程配置拉取默认指向 Anthropic 官方服务。虽然我们把主 API 请求转到了 DeepSeek但部分版本仍有独立的遥测和更新检查请求这些请求在国内可能不通。处理方式有两种。一是离线使用启动时加--offline参数跳过一切远程检查。二是接受警告如果你只是看到卡顿但最终能进界面也可以忽略。我个人倾向于claude --offline开静默模式稳定且快。5.4 中文乱码和交互异常Windows 的经典毛病。claude输出中文偶尔变成方块是因为当前代码页不是 UTF-8。Windows Terminal 一般没问题传统 conhost 需要手动执行chcp 65001之后再启动claude。如果你用的是 Windows PowerShell 5.1还有一个隐藏坑它的默认输出编码可能是 GBK会把 UTF-8 内容拦一道。建议直接安装 PowerShell 7 或改用 Windows Terminal这两个问题都能规避。5.5 settings.json 未生效的隐性问题很多人改了 JSON 却感觉没变先怀疑是不是缓存其实大多数情况是 JSON 解析静默失败。Claude Code 遇到非法的 JSON 配置时不一定会红字报错它可能直接忽略整个文件。我的排查顺序是先打开文件看有没有中文引号或全角符号再确认文件编码是 UTF-8 无 BOM然后确认没有注释JSON 不支持注释最后从根目录到用户目录检查有没有其他 settings.json 在“抢配置”。Windows 上项目级.claude\settings.json会因为你在不同目录启动 claude 而意外覆盖用户级配置这是最常见的“未生效”原因。5.6 API 限流与计费提醒DeepSeek 开放平台有按并发或分钟频率的限流策略高并发大批量任务时容易触发 429。Claude Code 大部分场景是单会话逐个请求一般不会撞上但你同时开多个会话、或频繁触发大文件操作时要留意。计费方面DeepSeek 按 token 计费deepseek-reasoner明显比deepseek-chat贵。我建议在 claude 配置文件里把主模型设为deepseek-chat把钱包成本压在可控范围内只在真正需要重推理时才手动切换deepseek-reasoner。另外DeepSeek 平台的余额阈值可以预设低于阈值会有通知建议开一下避免任务跑到一半因欠费断开。最后再分享一个小技巧。我实际用下来这套配置最舒服的使用方式是用户级 settings.json 里只写 DeepSeek 的通用接入信息base_url、token、默认 chat 模型然后在不同的项目目录里放一个.claude\settings.json用env字段覆盖成deepseek-reasoner或其他自定义组合。比如做算法原型、写复杂脚本时我就切到推理模型日常 CRUD 代码切回 chat 模型。这样你不必频繁改全局配置也不会出现“这个项目用的是哪个模型”的混乱感。Windows 上配置文件路径和 Linux 不太一样但只要抓住“用户级配置是默认项目级配置是覆盖”这个核心逻辑就不会出错。