1. 从零安装 ClaudeCode 并接入 DeepSeek 的完整场景拆解
ClaudeCode 是 Anthropic 推出的命令行编程助手，能在终端里直接读写项目文件、跑命令、改代码。它默认走 Anthropic 官方通道，但很多人手里已经有 DeepSeek 的 API Key，想把两者接起来用——毕竟 DeepSeek 在代码补全和长上下文任务上性价比不错。问题在于：ClaudeCode 本身不提供图形化的多模型切换界面，每次换供应商都要手改配置文件，容易改错、容易忘备份。
这篇教程解决的就是这个场景：在 Windows 和 macOS 上，用 nvm 装好 Node.js，全局安装 ClaudeCode，再用 CC Switch 这个配置管理工具把 DeepSeek 接进去，最后发一次真实对话请求验证链路通不通。适合谁？适合刚接触命令行 AI 编程工具、又不想被复杂配置劝退的开发者。全程命令可复制，配置文件骨架直接给，踩坑点单独列一节。
我试过在 Windows 11 和 macOS Sonoma 上各跑一遍，流程基本一致，差异只在 nvm 的安装方式。下面按「环境准备 → 装 ClaudeCode → CC Switch 配置 → 验证 → 排障」的顺序走，你可以跟着做。
核心检索词先明确：ClaudeCode 安装、DeepSeek 接入、nvm 管理 Node.js、CC Switch 多模型配置。这四个词贯穿全文，遇到报错时回来看对应章节即可。
2. 前置环境：nvm 安装 Node.js 与版本锁定实操
ClaudeCode 依赖 Node.js 运行，官方建议 Node 18 以上。直接装 Node 也能用，但后面如果遇到版本冲突（比如某个全局包只支持 Node 20），卸载重装很麻烦。nvm（Node Version Manager）就是解决这个的：一台机器装多个 Node 版本，一条命令切换。
2.1 Windows 下安装 nvm-windows
Windows 用 nvm-windows，下载地址在 GitHub 的 coreybutler/nvm-windows 仓库 releases 页，选nvm-setup.exe。安装时注意两点：安装路径不要有空格和中文；它会问你是否把 nvm 的 symlink 指向现有 Node，如果之前装过 Node，建议先卸载干净再装 nvm，避免路径打架。
装完打开 PowerShell（建议管理员身份），验证：
nvm version能输出版本号就说明装好了。接着换国内镜像，不然nvm install拉 Node 包会很慢：
nvm node_mirror https://npmmirror.com/mirrors/node/ nvm npm_mirror https://npmmirror.com/mirrors/node/查看可安装版本：
nvm list available输出里会列出 LTS 和 Current 两栏。ClaudeCode 用 LTS 就够，选 20.x 或 22.x。安装指定版本：
nvm install 20.18.0装完查看已安装列表：
nvm list切换到这个版本：
nvm use 20.18.0验证 Node 和 npm：
node -v npm -v两条都出版本号，环境就通了。最后把 npm 源也换成国内镜像，后面全局装包快很多：
npm config set registry https://registry.npmmirror.com/2.2 macOS 下安装 nvm
macOS 用官方 nvm 脚本，先确认有没有~/.zshrc（Catalina 之后默认 zsh）。执行安装脚本：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash装完把下面两行加到~/.zshrc末尾（脚本一般会自动加，没加就手动补）：
export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"然后source ~/.zshrc让配置生效。验证：
nvm --version安装 Node 20 LTS：
nvm install 20.18.0 nvm use 20.18.0 node -v npm -vmacOS 下 npm 镜像同样建议换：
npm config set registry https://registry.npmmirror.com/2.3 版本锁定建议
nvm 默认不会记住你上次use的版本，新开终端可能回到系统默认。可以在项目根目录放一个.nvmrc文件，内容写20.18.0，之后进目录执行nvm use就会自动读这个文件。Windows 的 nvm-windows 对.nvmrc支持有限，建议直接在系统环境变量里把默认版本设好，或者每次开终端手动nvm use 20.18.0。
Node 版本别选太新的 Current 版，有些全局包的 native 依赖还没跟上，装 ClaudeCode 时可能报编译错误。LTS 是稳妥选择。
3. 安装 ClaudeCode 与 CC Switch 的可复制配置
环境好了，接下来装两个东西：ClaudeCode 本体，和用来管理多模型配置的 CC Switch。
3.1 全局安装 ClaudeCode
一条命令：
npm install -g @anthropic-ai/claude-code装完验证：
claude --version能输出版本号就成功。第一次直接输claude会进入引导流程，要求登录 Anthropic 账号。如果你只想用 DeepSeek，不想走官方登录，可以跳过这一步：找到用户目录下的.claude.json文件（Windows 在C:\Users\你的用户名\.claude.json，macOS 在~/.claude.json），用编辑器打开，把hasCompletedOnboarding字段改成true。如果没有这个字段就手动加：
{ "hasCompletedOnboarding": true }保存后再输claude，它会问你是否信任当前目录，选 Yes 就进入交互界面了。这一步只是跳过官方登录引导，不影响后面接 DeepSeek。
3.2 安装 CC Switch
CC Switch 是一个开源的 ClaudeCode 配置切换工具，GitHub 仓库 farion1231/cc-switch，去 releases 页下载对应平台的安装包。Windows 是.exe，macOS 是.dmg。装完打开，界面左侧是供应商列表，右侧是配置编辑区。
它的作用是帮你管理~/.claude/settings.json和~/.claude/config.toml这类配置文件，切换供应商时不用手动改文件。对多模型用户来说，比手改配置安全得多。
3.3 CC Switch 中配置 DeepSeek 的 config.toml 骨架
在 CC Switch 里点「添加供应商」，选 DeepSeek。它会让你填 API Key——去 DeepSeek 开放平台创建，复制出来粘进去。然后重点看配置文件。
ClaudeCode 的配置分两块：settings.json管环境变量和模型映射，config.toml管供应商和模型定义。CC Switch 里 DeepSeek 的config.toml骨架大致如下（路径以 macOS 为例，Windows 把~换成C:\Users\你的用户名）：
[providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com" api_key = "sk-你的DeepSeekKey" models = ["deepseek-chat", "deepseek-reasoner"] [providers.deepseek.model_mapping] "claude-3-5-sonnet" = "deepseek-chat" "claude-3-opus" = "deepseek-reasoner"base_url是 DeepSeek 的 API 地址，api_key填你创建的 Key。models列出你要用的模型，deepseek-chat是通用对话，deepseek-reasoner是推理模型。model_mapping把 ClaudeCode 内部请求的 Claude 模型名映射到 DeepSeek 模型名，这样 ClaudeCode 发claude-3-5-sonnet请求时，实际打到 DeepSeek 的deepseek-chat。
3.4 settings.json 关键字段
settings.json里要配的是环境变量，让 ClaudeCode 知道走哪个 base_url 和 key：
{ "env": { "ANTHROPIC_BASE_URL": "https://api.deepseek.com", "ANTHROPIC_API_KEY": "sk-你的DeepSeekKey", "ANTHROPIC_MODEL": "deepseek-chat" } }三个字段缺一不可：ANTHROPIC_BASE_URL指向 DeepSeek 的接口地址，ANTHROPIC_API_KEY是鉴权 Key，ANTHROPIC_MODEL指定默认模型。CC Switch 切换供应商时，会自动改写这三个字段，所以你不用手动改。
如果你用的是 TaoToken 这类聚合通道，Base URL 换成https://taotoken.net/api，Key 换成对应平台的 Key，Model ID 按平台文档填。三件套（Base URL + Key + Model ID）必须同时正确，缺一个就会 401 或模型找不到。
配置保存后，CC Switch 会提示你重启 ClaudeCode 让配置生效。关掉终端重新开，或者退出claude再进。
4. 验证请求：发一次对话确认 DeepSeek 接入生效
配置写完不算完，得发一次真实请求确认链路通。这一步很多人跳过，结果后面遇到问题不知道是配置错还是网络错。
4.1 启动 ClaudeCode 并查看模型
在终端输：
claude进入交互界面后，输/model查看当前模型。如果配置正确，应该能看到deepseek-chat或你在model_mapping里映射的名字。如果还显示claude-3-5-sonnet，说明settings.json的ANTHROPIC_MODEL没生效，回 CC Switch 检查配置有没有保存。
4.2 发一条测试请求
直接输入：
用 Python 写一个快速排序函数，并解释时间复杂度回车后观察输出。如果 DeepSeek 接入成功，你会看到它流式返回代码和解释。响应速度取决于 DeepSeek 当时的负载，一般几秒内开始出字。
4.3 用 curl 单独验证 API 链路
如果 ClaudeCode 里没反应，先用 curl 直接打 DeepSeek 接口，排除是 ClaudeCode 的问题还是 API 的问题：
curl https://api.deepseek.com/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的DeepSeekKey" \ -d '{ "model": "deepseek-chat", "messages": [{"role": "user", "content": "你好"}], "stream": false }'如果返回 JSON 里有choices字段和内容，说明 API Key 和网络都没问题，问题出在 ClaudeCode 配置上。如果返回 401，Key 错了；返回 404，base_url 或路径错了。
4.4 成功结果长什么样
正常返回类似：
{ "id": "chatcmpl-xxx", "object": "chat.completion", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "你好！有什么可以帮你的？" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 5, "completion_tokens": 10, "total_tokens": 15 } }看到choices[0].message.content有内容，就说明整条链路通了。ClaudeCode 里也应该能正常对话。
5. 本篇常见报错排查：401、local proxy failed、reading choices
配置过程中最容易卡在几个固定报错上，逐个拆。
5.1 401 Unauthorized
最常见。原因就三类：Key 填错、Key 过期、Key 没权限。先检查settings.json里的ANTHROPIC_API_KEY和config.toml里的api_key是否一致，有没有多余空格。然后去 DeepSeek 平台确认 Key 状态，有没有欠费或禁用。如果用的是聚合通道，确认 Key 对应的平台和 Base URL 匹配——Key 和 URL 不配套也会 401。
5.2 local proxy failed
这个报错通常出现在 ClaudeCode 启动时，提示本地代理失败。原因是ANTHROPIC_BASE_URL指向了一个 ClaudeCode 无法访问的地址，或者地址格式不对。检查两点：URL 有没有带https://前缀；URL 末尾有没有多余的斜杠。正确格式是https://api.deepseek.com，不要写成https://api.deepseek.com/或api.deepseek.com。
如果确认 URL 没问题还报这个，检查系统环境变量里有没有残留的HTTP_PROXY或HTTPS_PROXY指向失效地址。有的话清掉再试。
5.3 reading choices 报错
完整报错类似error reading choices: unexpected end of JSON input。这是 ClaudeCode 解析 DeepSeek 返回时格式对不上。原因通常是model_mapping没配好，ClaudeCode 请求的模型名 DeepSeek 不认识，返回了错误结构。检查config.toml里的model_mapping，确保 ClaudeCode 内部用的模型名都有对应映射。另外确认ANTHROPIC_MODEL填的是 DeepSeek 支持的模型名，别填claude-3-5-sonnet这种 Claude 专有名。
5.4 OAuth 相关报错
如果没改.claude.json的hasCompletedOnboarding，启动时会走 OAuth 登录流程，报OAuth error或一直卡在登录页。解决办法就是前面说的，把hasCompletedOnboarding设为true。如果已经设了还报，检查文件路径对不对，Windows 是C:\Users\你的用户名\.claude.json，注意用户名别写错。
5.5 模型找不到 / model not found
ANTHROPIC_MODEL或model_mapping里的模型名拼错，或者 DeepSeek 那边没有这个模型。DeepSeek 目前常用的是deepseek-chat和deepseek-reasoner，别写成deepseek-coder之类不存在的名字。去 DeepSeek 文档确认当前可用模型列表。
5.6 配置改了不生效
CC Switch 改完配置后，ClaudeCode 不会自动重载。必须完全退出claude进程再重新启动。如果还不行，检查 CC Switch 有没有真正写入~/.claude/settings.json，手动打开文件看一眼内容对不对。有时候 CC Switch 的「保存」和「应用」是两个按钮，只保存没应用，配置不会写进去。
6. 多模型切换与长期使用的配置建议
配置跑通之后，日常使用还有几个点值得注意。
CC Switch 的核心价值是多供应商管理。你可以在里面同时配 DeepSeek、TaoToken 聚合通道、其他兼容 Anthropic 接口的服务，切换时点一下就行，不用手改 JSON。每个供应商的配置独立保存，切换时 CC Switch 会重写settings.json的三个关键字段。建议给每个供应商起个清晰的名字，比如「DeepSeek-直连」「TaoToken-聚合」，避免切错。
如果你需要长期跑编码任务或 Agent 类工作流，可以考虑用 Coding Plan 这类按量套餐，比单次调用更划算。验证模型能力时，用模型对话页面快速试几个 prompt，确认响应质量再接到 ClaudeCode 里。API Key 的管理在控制台的 API Keys 页面，建议给不同用途创建不同的 Key，方便排查和吊销。
配置文件建议纳入版本管理。把~/.claude/settings.json和config.toml备份到私有仓库，换机器时直接拉下来改 Key 就能用。注意别把真实 Key 提交到公开仓库，用环境变量或本地覆盖文件的方式管理敏感信息。
Node 版本方面，如果后面 ClaudeCode 升级要求更高版本，用 nvm 直接nvm install 22.x && nvm use 22.x就行，不用卸载重装。这就是当初用 nvm 而不是直接装 Node 的好处。
最后提醒一点：DeepSeek 的 API 有速率限制，ClaudeCode 在跑大项目时可能短时间内发很多请求，遇到 429 报错就等几秒重试，或者在 CC Switch 里调低并发。具体限制看 DeepSeek 平台文档。
整套流程走下来，从装 nvm 到验证对话，顺利的话半小时内能搞定。卡住的地方大概率在配置文件格式和模型名映射上，对照第 5 节逐个排查即可。
