1. 为什么要在本地跑 ClaudeCode DeepSeek 这套组合ClaudeCode 是 Anthropic 推出的终端 AI 编程助手能读代码库、执行命令、改文件跟开发工具链贴得很紧。但官方 Claude 模型对国内用户来说有两个现实门槛一是订阅成本Claude Pro 每月 20 美元二是网络访问的稳定性官方 API 端点在国内直连经常超时。DeepSeek 提供了 Anthropic 兼容端点模型能力强、按量计费成本低而且国内可以直连这就让「ClaudeCode 客户端 DeepSeek 模型」成为很多开发者的替代方案。这套组合适合谁适合已经习惯在终端里干活、想让 AI 直接读写项目文件的开发者适合不想每月付订阅费、希望按实际用量付费的人也适合想用 ccswitch 这类配置管理工具在不同模型供应商之间快速切换的人。整个链路的核心是三件事装好 Node.js 和 Git 这两个基础依赖装好 ClaudeCode 本体再用 ccswitch 把 DeepSeek 的 API 信息写进配置。我试过从零在一台干净的 Windows 机器上走完整流程踩过的坑主要集中在环境变量没刷新、npm 下载慢、以及 API Key 字段名写错导致 401。下面把每一步的命令、配置片段和验证方法都写清楚你照着做基本能一次跑通。全文覆盖 Windows、macOS、Linux 三个平台命令会标注差异。在开始之前先明确一个概念ClaudeCode 本身是个客户端它默认连 Anthropic 官方端点。我们要做的是通过配置把它的请求指向 DeepSeek 的兼容端点。ccswitch 就是帮你管理这份配置的工具它把 API Key、Base URL、Model ID 这些字段可视化避免你手动去改 JSON 文件改错。理解了这个逻辑后面的步骤就顺了。2. 环境准备Node.js 与 Git 的安装和版本校验ClaudeCode 运行依赖 Node.js官方要求版本不低于 18.0推荐用 LTS 20 或更高。Node.js 自带 npm后面装 ClaudeCode 就靠它。Git 则是 ClaudeCode 读取项目历史、生成 diff 的必要工具建议 2.23 以上。这两个装不好后面一定报错所以先把版本校验做扎实。2.1 安装 Node.js 并验证去 Node.js 官网下载 LTS 安装包Windows 选 .msimacOS 选 .pkgLinux 可以用包管理器。装完后必须新开一个终端再验证因为环境变量在旧终端里不会刷新。执行node -v npm -v正常会输出类似v20.11.1和10.2.4。如果提示node 不是内部或外部命令Windows或command not foundmacOS/Linux说明 PATH 没生效。Windows 可以重启终端甚至重启系统macOS/Linux 检查~/.bashrc或~/.zshrc里有没有把 Node 的 bin 目录加进 PATH。Linux 用户如果不想手动配可以用 nvm 管理版本命令更干净curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20npm 下载慢是高频问题建议直接切国内镜像npm config set registry https://registry.npmmirror.com npm config get registry最后一条命令应该回显https://registry.npmmirror.com说明镜像生效。2.2 安装 Git 并验证Git 官网下载对应平台安装包一路默认即可。装完同样新开终端验证git --version输出git version 2.43.0这类信息就对了。如果 ClaudeCode 报「git not found」多半是安装时没勾选「Add to PATH」重新跑一遍安装程序勾上即可。macOS 用户如果装了 Xcode Command Line ToolsGit 通常已经自带git --version会提示你安装跟着走就行。这里有个细节ClaudeCode 在执行某些操作时会调用git diff、git log如果你的项目目录不是 Git 仓库部分功能会受限。建议在你要用 ClaudeCode 操作的项目根目录先git init一下哪怕不提交也能让 diff 类功能正常工作。cd your-project git init git add . git commit -m init环境这一步做完可以用一条命令快速自检两个依赖是否都就位node -v npm -v git --version三条版本号都打出来就可以进入下一步装 ClaudeCode 了。3. 安装 ClaudeCode 与 ccswitch 并写入 DeepSeek 配置这一节是整篇的核心包含可复制的配置片段。先装 ClaudeCode 本体再装 ccswitch然后用 ccswitch 把 DeepSeek 的接入信息写进去。3.1 安装 ClaudeCode推荐用 npm 全局安装配合前面的国内镜像速度会快很多npm install -g anthropic-ai/claude-code装完验证claude --version能输出版本号就说明装好了。如果这一步卡住或报网络错误先确认 npm 镜像已切换再执行npm cache clean --force清缓存后重试。首次启动 ClaudeCode 会引导登录。如果你只想用 DeepSeek不想登录 Anthropic 账号可以在用户目录下找到~/.claude.jsonWindows 是C:\Users\你的用户名\.claude.json在里面加上一行跳过引导{ hasCompletedOnboarding: true }保存后重新运行claude就不会再强制走登录流程。3.2 安装 ccswitchccswitchCC Switch是开源的跨平台配置管理工具图形界面和命令行都支持。去它的 GitHub Releases 页面下载对应系统的安装包Windows 是 .exemacOS 是 .dmgLinux 有 AppImage 或 deb。装完打开能看到主界面就成功了。它的作用是管理 ClaudeCode 的 API 配置。ClaudeCode 读取的配置字段包括 Base URL、API Key、Model ID手动改容易写错字段名ccswitch 把这些做成表单还能一键切换不同供应商。3.3 用 ccswitch 写入 DeepSeek 配置在 ccswitch 里选择 Claude Code点「」新建配置供应商选 DeepSeek然后把下面三件套填进去。这三件套是接入任何 Anthropic 兼容端点的通用结构字段值说明Base URLhttps://api.deepseek.com/anthropicDeepSeek 的 Anthropic 兼容端点API Key你的 DeepSeek Key在 DeepSeek 平台创建Model IDdeepseek-chat具体可用模型以官方文档为准如果你更习惯直接改配置文件ClaudeCode 的配置本质是一份 JSON结构大致如下路径以 ccswitch 实际写入位置为准通常在用户目录的.claude相关配置里{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: sk-你的DeepSeekKey, ANTHROPIC_MODEL: deepseek-chat } }注意字段名是ANTHROPIC_AUTH_TOKEN而不是ANTHROPIC_API_KEY这是很多人 401 的根源。填完在 ccswitch 里点添加回到主页确认这条配置处于启用状态。如果你用的是 TaoToken 这类聚合接入服务配置结构完全一样只是把 Base URL 换成对应的兼容端点、Key 换成平台签发的 Key。TaoToken 的 API 地址是https://taotoken.net/api模型对话、Coding Plan、API Keys 管理都可以在控制台完成接入文档里有各客户端的字段对照。它的好处是一个 Key 可以切换多个模型省去反复改配置的麻烦。配置写完后完全退出当前 ClaudeCode 进程CtrlC再重新启动让新配置生效。这一步不做ClaudeCode 可能还在用旧配置。4. 连通性验证确认 ClaudeCode 真的在调 DeepSeek配置写完不代表接通必须验证。验证分两层先确认 ClaudeCode 能启动并读到配置再确认请求真的打到了 DeepSeek。4.1 启动并查看当前模型重新打开终端进入你的项目目录运行claude进入交互界面后输入斜杠命令查看当前模型/model如果配置生效这里应该显示deepseek-chat或你填的 Model ID而不是 Claude 官方模型名。这一步能过说明配置被正确读取了。4.2 发一条真实请求验证在交互界面里直接输入一个简单任务比如帮我看一下当前目录下有哪些文件并解释 package.json 的作用如果 ClaudeCode 能正常读取文件、返回解释说明整条链路通了。你也可以用非交互模式快速验证claude -p 用一句话说明这个项目是做什么的-p是 print 模式直接输出结果不进入交互适合脚本化验证。返回正常文本就说明 DeepSeek 端点连通、鉴权通过、模型可用。4.3 用 curl 单独验证端点如果 ClaudeCode 里报错但你不确定是客户端问题还是端点问题可以绕过客户端直接测端点curl https://api.deepseek.com/anthropic/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -d { model: deepseek-chat, max_tokens: 64, messages: [{role: user, content: ping}] }返回带content字段的 JSON 就说明端点和 Key 都没问题问题在客户端配置如果这里就报 401那就是 Key 或字段名的问题。这个分层排查法能帮你快速定位故障点。验证通过后你就可以在日常项目里用 ClaudeCode 配合 DeepSeek 干活了。建议先在测试项目里跑几天确认稳定后再用到主力仓库。5. 高频报错排查401、local proxy failed 与模型不生效这一节按真实报错来对照遇到问题直接查表。报错一401 Unauthorized / invalid api key最常见。原因通常是三个Key 复制时带了空格或换行字段名写成了ANTHROPIC_API_KEY而不是ANTHROPIC_AUTH_TOKEN或者 DeepSeek 账号余额不足。排查顺序是先重新复制 Key再检查配置字段名最后登录 DeepSeek 平台看余额。用上一节的 curl 命令能直接判断是 Key 问题还是客户端问题。报错二local proxy failed / connection refused这个报错通常出现在你配置了本地代理端口但代理没启动或者 Base URL 写成了localhost但本地没有对应服务。检查配置里的 Base URL 是不是https://api.deepseek.com/anthropic不要带多余路径或端口。如果你之前配过其他工具的代理确认没有残留的环境变量干扰比如HTTP_PROXY、HTTPS_PROXY可以临时清掉再试unset HTTP_PROXY HTTPS_PROXY报错三reading choices / unexpected response format这个报错说明客户端收到了响应但解析失败通常是 Base URL 指向了 OpenAI 格式的端点而不是 Anthropic 格式。DeepSeek 的 Anthropic 兼容端点是/anthropic结尾如果你漏了这段请求会打到 OpenAI 格式接口返回结构对不上就报这个错。检查 Base URL 拼写。报错四OAuth / 登录循环如果你没跳过引导ClaudeCode 会一直要求登录 Anthropic 账号。解决办法就是前面说的在~/.claude.json里加hasCompletedOnboarding: true。如果加了还循环检查文件是不是合法 JSON逗号、引号别写错可以用cat ~/.claude.json看一眼内容。报错五切换配置后仍用旧模型ccswitch 改了配置但 ClaudeCode 没重启进程还持有旧配置。完全退出CtrlC 或关掉终端再启动。另外确认 ccswitch 里那条 DeepSeek 配置是「启用」状态有些版本需要手动点一下激活。报错六Windows 下环境不兼容部分 Windows 用户直接跑会报路径或权限问题。推荐装 WSL 2 Ubuntu在 WSL 里重新走一遍 Node.js、Git、ClaudeCode 的安装流程兼容性最好。WSL 里访问 Windows 文件用/mnt/c/...路径。排查时记住一个原则先用 curl 测端点端点通了再查客户端配置客户端配置对了再查进程是否重启。按这个顺序绝大多数问题十分钟内能定位。6. 把配置固化下来多项目、多模型切换的实用做法跑通一次之后建议把配置固化避免每次换项目重新折腾。ccswitch 支持保存多套配置你可以为 DeepSeek、其他兼容模型各存一份需要时一键切换不用手动改 JSON。如果你用 TaoToken 这类聚合平台一个 Key 就能覆盖多个模型切换时只改 Model ID 即可配置管理更省事。它的 Coding Plan 适合长期编码场景API Keys 页面可以管理多个 Key 做额度隔离接入文档里有 ClaudeCode、Cline、Codex 等客户端的字段对照表照着填不会错。模型对话页面还能先验证模型是否可用再去配客户端减少来回试错。日常使用有几个小技巧把常用项目的启动命令写成 alias比如alias cccd ~/work/proj claude在项目根目录放一个.claude配置覆盖全局设置团队协作时统一模型定期检查 DeepSeek 余额避免跑到一半 401。最后提醒一点ClaudeCode 会执行命令和改文件第一次在重要仓库用之前先确保代码已提交出问题能git checkout回滚。配置文件和 API Key 不要提交到 Git加到.gitignore里。这套组合跑顺之后终端里的编码效率会有明显提升剩下的就是按你的工作流慢慢调优了。