最近在 Windows 上把 Claude Code 的模型后端换成了 DeepSeek从零走了一遍安装和配置。Claude Code 本身是一个在终端里运行的 AI 编程代理能让模型直接读写文件、执行命令、跑测试交互方式比普通聊天窗口高效很多。DeepSeek 的 API 开放了 Anthropic 兼容端点所以 Claude Code 只要配置好地址和密钥就能把请求发给 DeepSeek 的模型来处理。整个过程不算复杂但坑都在细节里环境变量名、settings.json 位置、模型名大小写任何一个不对启动就是各种报错。这篇文章把我实际操作过的步骤、配置文件和排错经验都记录下来想省事的可以直接照着抄。适合 Windows 上做开发、想用 DeepSeek 模型跑 Claude Code 的读者。1. 配置前需要搞清楚的三个问题1.1 为什么要把 Claude Code 接到 DeepSeek 上Claude Code 是 Anthropic 推出的命令行编程助手核心价值不只是聊天而是能“动手”它可以在你的项目目录里列出文件、读取代码、批量修改、运行命令、看报错再自动修复。这种 agent 形态的工作流很多人用下来是回不去的。但默认情况下它跟 Anthropic 官方 API 绑定用起来有一定成本门槛而且想换更经济的模型就要另想办法。DeepSeek 在模型推理上提供了两种常用模型deepseek-chat 走通用对话和代码生成deepseek-reasoner 走强化推理链路适合复杂问题拆解。关键是 DeepSeek API 提供了一个 Anthropic 兼容的接入路径让本来只认 Anthropic 协议的工具也能接进来。于是在 Claude Code 里只要把 base_url、auth_token、model 这几个参数指过去就可以用 DeepSeek 的模型干活。简单理解就是Claude Code 是一个遥控器DeepSeek 是电视信号源settings.json 做的事情就是切换频道。1.2 配置原理三个参数决定一切不管用环境变量还是 settings.json本质上 Claude Code 在启动时都会读取这几个关键配置ANTHROPIC_BASE_URL请求要发往的 API 地址。DeepSeek 的 Anthropic 兼容地址是https://api.deepseek.com/anthropic。ANTHROPIC_AUTH_TOKEN身份认证令牌也就是 DeepSeek 平台里创建的 API Key。ANTHROPIC_MODEL 和 ANTHROPIC_SMALL_FAST_MODEL指定用哪个模型。ANTHROPIC_SMALL_FAST_MODEL 通常用于对话中的摘要、压缩等轻量任务建议也指到同一个模型避免出现混合调用。另外还有一个 ANTHROPIC_API_KEY它和 ANTHROPIC_AUTH_TOKEN 属于同一类东西二选一即可。我的习惯是用 AUTH_TOKEN因为语义上更贴近自定义接入场景不容易和“必须用官方 Key”搞混。一句话总结Claude Code 不关心模型藏在哪个服务商后面它只知道按 base_url 发请求带上 token再把模型名填进去。这个抽象层就是整个配置方案能成立的关键。1.3 环境变量和 settings.json 怎么选配置可以写在系统环境变量里也可以写在 Claude Code 的 settings.json 里还可以两者混用。我给你的建议是配置方式优点缺点适用场景系统环境变量对命令行全局生效进程读取稳定修改后要重开终端多项目切换麻烦只想一次性配好用户级 settings.json管理集中打开文件就能改换 API Key 时要编辑文件个人电脑日常开发项目级 settings.json可以按项目走不同模型每个项目都要放一份多个项目用不同后端在实际使用中我会把 base_url 写在用户级 settings.json 的 env 段里API Key 也放里面这样换 Key 时只改一个文件。如果遇到疑难问题再用系统环境变量临时覆盖做对比测试。区别不大但思路要清晰settings.json 是“项目化的配置”系统环境变量是“进程级的兜底”。2. Windows 下安装 Claude Code 的完整步骤2.1 Node.js 环境准备Claude Code 是 npm 包所以第一步是保证 Windows 上有 Node.js。建议用 18 LTS 或更高版本20 LTS 更稳。检查方式很简单node -v npm -v如果提示命令不存在去 Node.js 官网下载 LTS 安装包一路下一步即可。装完记得重开 PowerShell。我见过不少朋友装完不重开终端然后报“node 不是内部或外部命令”其实不是没装上是终端没有刷新 PATH。如果你更喜欢命令行安装可以用 wingetwinget install OpenJS.NodeJS.LTS安装完后顺手把 npm 全局目录确认一下npm config get prefix这个路径后面排查“claude 命令找不到”时会用到。2.2 安装 Claude CodeNode.js 就绪后执行npm install -g anthropic-ai/claude-code安装过程会拉取包到 npm 全局目录。安装完成后验证版本claude --version如果能输出版本号说明安装成功。如果出现“无法加载文件因为在此系统上禁止运行脚本”之类的提示这是因为 Windows PowerShell 默认执行策略限制。解决办法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后重新打开终端。这里解释一下RemoteSigned 表示本地脚本可以运行从网络下载的脚本需要签名。npm 全局包生成的 .ps1 启动脚本通常会被限制改成这个策略就能跑。但不要改成 Unrestricted没必要把系统完全放开。日常升级 Claude Code 用npm update -g anthropic-ai/claude-code2.3 获取 DeepSeek API Key登录 DeepSeek 开放平台进入 API Keys 页面创建一个新的 Key。创建后字符串只显示这一次务必先复制保存好丢了只能重建。创建 Key 时有几个注意点Key 的权限标识是 sk- 开头实际请求时它就是令牌本身。平台账户里要有可用额度否则调用会直接失败。新账号通常有赠送额度可以先用小额任务验证链路。不要把 Key 写进任何会被提交到 Git 的文件里。如果 settings.json 存放在项目目录记得加入 .gitignore。密钥拿到后可以先不急着写进配置文件。先把安装和基础配置做完然后用 Claude Code 的一次实际请求来验证 Key 是否有效这样更直观。3. settings.json 配置全流程3.1 配置文件放在哪Claude Code 的配置分为用户级和项目级。用户级配置文件在C:\Users\你的用户名\.claude\settings.json项目级配置文件在项目根目录下.\.claude\settings.json如果目录不存在手动创建 .claude 文件夹和 settings.json 文件即可。注意项目级配置会覆盖用户级配置适合在不同项目里接不同模型后端。3.2 一份可以直接抄的 settings.json下面是我在 Windows 上实测可用的最小配置{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: sk-你的deepseek密钥, ANTHROPIC_MODEL: deepseek-chat, ANTHROPIC_SMALL_FAST_MODEL: deepseek-chat } }逐段解释一下env 段表示 Claude Code 启动时要写入进程环境的变量。这里面的键名不需要额外前缀Claude Code 内部会读取这些标准变量。ANTHROPIC_BASE_URL 不要漏掉末尾的 /anthropic。DeepSeek 的 Anthropic 兼容接口就是挂在这个路径下面的。AUTH_TOKEN 换成你自己的 Key。如果你之前设置了 ANTHROPIC_API_KEY二选一即可不要两个同时留下旧值否则可能因为优先级问题导致请求带错 Key。模型名默认填 deepseek-chat。它在日常代码任务中响应速度快价格也低。如果想要更强的推理改成 deepseek-reasoner 也行但速度会慢不少。3.3 模型参数与权限白名单除了 env 段settings.json 里还可以配置模型相关参数和权限。比如我想让 agent 只读某个目录下的文件可以加 permissions{ permissions: { allow: [ Read(C:\\work\\demo\\**), Bash(npm run *) ], deny: [ Write(C:\\work\\secret\\**) ] } }Windows 路径里的反斜杠记得写成双反斜杠否则 JSON 会被转义破坏。allow 里的规则命中后不会弹确认框开发效率高很多。deny 规则用来兜底防止它乱动敏感目录。如果你不需要这些控制保持最小配置就行。我建议先跑通最小配置再加权限规则。一上来就配置太多出问题时反而分不清是权限问题还是网络问题。3.4 用系统环境变量做兜底如果你不想动 settings.json也可以在 Windows 里设置用户级环境变量。PowerShell 执行[Environment]::SetEnvironmentVariable(ANTHROPIC_BASE_URL, https://api.deepseek.com/anthropic, User) [Environment]::SetEnvironmentVariable(ANTHROPIC_AUTH_TOKEN, sk-你的deepseek密钥, User) [Environment]::SetEnvironmentVariable(ANTHROPIC_MODEL, deepseek-chat, User)设置完必须重开终端变量才会加载。这个方式的好处是设置一次全局生效不好的地方是换项目、换模型时要去系统设置里改稍微麻烦。我通常把这种方式当作“兜底”或者测试用。当环境变量和 settings.json 里的 env 段同时存在时要特别注意终端进程里已经存在的环境变量启动后一般不会被 settings.json 直接覆盖。所以在排查问题时先跑一下$env:ANTHROPIC_BASE_URL $env:ANTHROPIC_AUTH_TOKEN看看到底是谁在起作用避免两个配置打架。4. 实操启动 Claude Code 并验证请求走向4.1 首次启动与基本检查在项目目录下打开 PowerShell 或 Windows Terminal输入claude首次启动如果本地没有登录态Claude Code 会走一段授权流程。因为我们接的是 DeepSeek 后端没有 Anthropic 账号登录需求只要配置里的 token 有效通常不会弹出登录界面。如果弹出了说明 base_url/token 没生效先 CtrlC 退出回到配置检查。进入交互界面后可以先用两条命令确认状态/status它会显示当前账户、模型、工作目录等信息。如果模型显示的是 deepseek-chat说明参数已经读到了。接着随便输入一个简单任务试试写一个 Python 函数判断一个字符串是不是回文。正常情况下 DeepSeek 会完成生成。看输出的风格就能感觉到不是走默认模型。4.2 带日志运行确认请求打到 DeepSeek想确认得更细就开启调试日志。在启动时带上环境变量$env:CLAUDE_CODE_DEBUG1 claude --debug这时 Claude Code 会在终端打印大量请求信息。重点关注请求 URL 里是不是 api.deepseek.com。也可以打开 DeepSeek 开放平台的用量页面等一两分钟后看有没有新的 token 消耗记录。这个方法最直接只要有调用控制台会显示 token 数、模型名和请求时间。我当时做过一次验证让 Claude Code 在一个空目录里生成一个 FastAPI 项目包括 main.py、requirements.txt 和 README。它先列出目录然后写文件再执行 Python 编译检查。整个过程里 DeepSeek 控制台能看到多轮请求模型名稳定显示 deepseek-chat。这说明在 Windows 上的链路是完全通的。4.3 在 VS Code 里跑 Claude CodeClaude Code 有官方 VS Code 扩展也可以直接在 VS Code 的集成终端里运行 claude这是我最常使用的方式。方法很简单打开 VS Code按 Ctrl 唤起终端确保终端默认是 PowerShell然后输入 claude。此时 Claude Code 的工作目录就是当前打开的项目目录它能直接读取资源管理器里看到的文件。如果想用官方扩展在扩展市场搜索 Claude Code for VS Code安装后侧边栏会出现专用面板。不过提醒一句扩展面板本质上还是在调用同一个命令行工具配置仍然是读取同一个 settings.json。所以不要出现“命令行能用、扩展不能用”的错觉大概率是扩展终端环境变量没刷新或登录状态不一致重启 VS Code 多能解决。4.4 任务执行中的工具调用Claude Code 之所以好用是因为它不只是“输出文字”它会通过工具调用操作文件、执行命令。接上 DeepSeek 后这部分逻辑仍然由 Claude Code 编排模型负责决策调用哪个工具。实际使用中deepseek-chat 对工具调用的理解比较直接简单任务很少出问题但遇到多步骤任务偶尔会出现“想用工具但没按正确格式传参”的情况表现为权限确认弹窗卡住或反复执行某个命令。遇到这类问题我会先把任务拆小或者切换到 deepseek-reasoner 再做一次。reasoner 的推理链路更擅长多步规划代价是思考时间长回答前会多花十几秒。这不是 bug是模型特性。在 Claude Code 中可以通过 /model 命令切换当前会话的模型具体列表取决于你配置里写的模型名。5. 排障手册我在 Windows 上踩过的坑5.1 claude 命令找不到症状PowerShell 执行 claude 提示“不是内部或外部命令”。原因npm 全局目录不在 PATH 里。执行npm config get prefix得到的路径通常是 C:\Users\你的用户名\AppData\Roaming\npm。打开系统环境变量设置把这个路径加到 Path 里重开终端。另一种潜在原因是 Node.js 没装成功先执行 node -v 确认。5.2 401 Unauthorized 或 403症状Claude Code 启动后报认证失败。原因优先级排序API Key 写错包括多了空格、复制了旧 Key。环境变量里同时存在 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN其中一个值是旧的。DeepSeek 账户余额不足或 Key 被删除。排查时在终端里执行$env:ANTHROPIC_AUTH_TOKEN确认显示的值是不是当前有效的 Key。如果显示为空说明 settings.json 的 env 段没被正确读取检查文件名是否是 settings.json路径是否是 C:\Users\你的用户名.claude\settings.json。5.3 404 或 model not found症状请求发出去了但返回模型不存在或路径 404。几乎都是 base_url 配错了。常见错误是写成了 https://api.deepseek.com少了 /anthropic 后缀。复制配置时把末尾空格带上了。在 JSON 里用了中文引号。检查这一项$env:ANTHROPIC_BASE_URL正常情况下应该是https://api.deepseek.com/anthropic没有斜杠、没有多余空格。5.4 请求超时或连接中断症状启动后长时间没有响应最后报 connection timeout。原因一般是网络到 API 服务不稳定或者一次请求上下文太长模型生成时间超过客户端默认等待时间。处理方式先确认网络能通。可以执行一个简单的请求测试看服务是否可达。我这里不展开具体命令用浏览器打开 API 域名看是否正常响应即可。减少当前会话上下文使用 /clear 清空历史重来或者用 /compact 压缩历史。把模型从 deepseek-reasoner 换回 deepseek-chat推理模型思考时间更长超时概率会高一些。在公网环境、办公网络后面可能遇到请求被网关拦截的情况表现也是超时。这时候先确认其他 HTTP 请求是否正常不要把问题都归结到 Claude Code 上。5.5 settings.json 没生效症状文件改了模型还是不变或配置还是旧的。常见原因文件编码不是 UTF-8。Windows 记事本默认可能保存为带 BOM 的 UTF-8部分解析器会读出错。推荐用 VS Code 编辑并另存为 UTF-8 without BOM。使用的配置文件层级不对。项目级 .claude/settings.json 会覆盖用户级如果你在项目目录里放了一个旧配置用户级配置即使改了也不生效。终端一直开着环境变量是旧值。改完配置后必须重启终端或者用下面的命令在当前会话里手动加载$env:ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic $env:ANTHROPIC_AUTH_TOKENsk-你的key $env:ANTHROPIC_MODELdeepseek-chat通过这种方式可以直接验证当前会话能不能跑通避免反复改文件。5.6 工具调用不稳定、任务执行中断最后一种情况不是报错而是“跑一半停下来”。Claude Code 在执行较长任务时可能在一次工具调用后等待用户确认也可能因为模型对工具返回结果理解不到位而重复循环。我的土办法是打开权限白名单把常用命令加进 allow减少确认打断。一次只给一个明确目标。比如“创建文件并写入以下代码”比“帮我搭一个项目”稳定得多。打开 debug 日志观察它卡在哪一步。如果总是卡在同一条命令考虑把那条命令换一个实现方式。这些都不是标准答案但很实用。毕竟跨模型接进来的组合没有官方 SLA出问题先看日志再缩小范围基本都能解决。6. 模型选择和使用技巧6.1 deepseek-chat 还是 deepseek-reasoner维度deepseek-chatdeepseek-reasoner定位通用对话/代码生成深度推理/复杂拆解响应速度快慢需要思考时间适合任务写函数、改 bug、生成配置架构设计、多文件改造、疑难问题主观体验轻快直接更谨慎但等待变长在 Claude Code 里我默认使用 deepseek-chat。日常 80% 的编程任务它都够用。只有遇到那种“改了很多处但问题依旧”的怪问题时我会用 /model 切到 reasoner 让它从头梳理一遍。6.2 上下文管理和成本控制Claude Code 会把整段对话历史作为上下文发送给模型所以聊得越久单次请求的 token 消耗越大费用也跟着涨。控制成本最有效的动作是每完成一个独立小任务就用 /clear 清空会话重新开始。需要保留上下文时用 /compact 让模型对历史做压缩之后再继续。在 DeepSeek 控制台设置账户余额预警避免跑任务花超预算。我自己的习惯让 Claude Code 先给我方案确认后再写代码。一次成型率远高于让它直接上手猛改。每一轮确认都能省下大量无效 token。6.3 这套配置思路能往哪迁移Claude Code 通过 base_url token model 三个参数切换后端的思路不只适用于 DeepSeek。其他提供 Anthropic 兼容接口的模型服务商基本都可以用同样的方式接入。甚至部分开源本地模型服务也可以通过兼容层接入只是性能和工具调用稳定性差异较大。如果你在 Windows 上还有其他 AI 编程客户端比如开源的 Cline、Continue 这类插件它们同样支持自定义模型端点。配置逻辑是相通的找到 API 地址、填密钥、指定模型名。所以一旦你把 Claude Code 配通了再玩其他工具会快很多。我个人更推荐先在 Claude Code 里跑熟这套链路因为它对 Anthropic 协议的支持最原生接口兼容度最高。跑通之后你就能理解“模型服务商和客户端解耦”这件事到底是怎么回事。以后不管模型服务商怎么换整套工具链都能平滑迁移。7. 进阶多后端切换与自动化7.1 用 PowerShell 脚本快速切换后端如果你手上有多个模型服务商或者想在 deepseek-chat 和 deepseek-reasoner 之间快速切换可以用一个简单的 PowerShell 脚本来管理变量。比如新建 switch-backend.ps1param([string]$Backend) if ($Backend -eq deepseek-chat) { $env:ANTHROPIC_BASE_URL https://api.deepseek.com/anthropic $env:ANTHROPIC_MODEL deepseek-chat $env:ANTHROPIC_SMALL_FAST_MODEL deepseek-chat } elseif ($Backend -eq deepseek-reasoner) { $env:ANTHROPIC_BASE_URL https://api.deepseek.com/anthropic $env:ANTHROPIC_MODEL deepseek-reasoner $env:ANTHROPIC_SMALL_FAST_MODEL deepseek-chat } else { Write-Host Unknown backend: $Backend }注意这个脚本只对当前终端会话有效不会污染系统环境变量。适合临时对比不同模型的表现。如果你想让它持久化可以在脚本里换成 SetEnvironmentVariable把变量写进用户环境。但这种用法要小心别在脚本里明文写下 API Key最好从另一个配置文件读取。7.2 用 hooks 记录本地调用记录Claude Code 的 settings.json 支持 hooks也就是在特定事件触发时执行外部脚本。比如我想把每次工具调用记录到本地日志文件可以加一个 PostToolUse hook。日志脚本不一定复杂在 Windows 下可以用 PowerShell 快速实现。这里给出一个思路在 .claude 目录下建一个 log-tool.ps1把事件类型、时间、当前路径写进日志文件然后在 settings.json 里挂上{ hooks: { PostToolUse: [ { matcher: *, hooks: [ { type: command, command: powershell -ExecutionPolicy Bypass -File C:\\Users\\你的用户名\\.claude\\log-tool.ps1 } ] } ] } }这个配置对日常调试很有用。当任务跑到一半出问题时我能直接从日志里看到最后一次工具调用是什么、发生在哪个目录不需要盯着终端历史翻。hooks 的 matcher 可以更精细比如只匹配 Read 和 Write但初学阶段用通配符最简单。7.3 定期轮换 Key 与安全注意用自定义 API 接入有个容易被忽略的点API Key 的轮换。DeepSeek 控制台可以随时创建多个 Key也可以单独禁用某一个。我的建议是至少准备两个 Key一个日常开发用一个跑批处理或测试用。一旦怀疑 Key 泄露直接禁用而不是删除全部保留操作日志能帮你判断泄露路径。此外settings.json 里的 env 段会明文存储 Key。如果是个人电脑还好如果是共享机器或团队项目务必把项目级 settings.json 加入 .gitignore。更稳妥的做法是不要把 Key 直接写在 settings.json 里而是在启动 claude 前从本地安全存储读取并写入环境变量。这样才能避免随仓库同步出去。最后说一点个人体会。Windows 上做这种自定义接入麻烦不在安装而在那些看不见的细节环境变量冲突、JSON 编码、路径斜杠、终端缓存。我把这套配置流程跑通之后最大的感受是 Claude Code 的交互体验和 DeepSeek 的模型性价比确实能共处。如果你也打算这么组合强烈建议第一次调试时把 debug 日志打开然后把排障顺序定为“看变量值、看请求地址、看控制台用量”。这套方法帮我省了大量时间希望你也能少踩几个坑。