从零安装 ClaudeCode 并接入 DeepSeek：用 CC Switch 管理多模型配置

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卸载重装很麻烦。nvmNode Version Manager就是解决这个的一台机器装多个 Node 版本一条命令切换。2.1 Windows 下安装 nvm-windowsWindows 用 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 和 npmnode -v npm -v两条都出版本号环境就通了。最后把 npm 源也换成国内镜像后面全局装包快很多npm config set registry https://registry.npmmirror.com/2.2 macOS 下安装 nvmmacOS 用官方 nvm 脚本先确认有没有~/.zshrcCatalina 之后默认 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 LTSnvm 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.jsonmacOS 在~/.claude.json用编辑器打开把hasCompletedOnboarding字段改成true。如果没有这个字段就手动加{ hasCompletedOnboarding: true }保存后再输claude它会问你是否信任当前目录选 Yes 就进入交互界面了。这一步只是跳过官方登录引导不影响后面接 DeepSeek。3.2 安装 CC SwitchCC Switch 是一个开源的 ClaudeCode 配置切换工具GitHub 仓库 farion1231/cc-switch去 releases 页下载对应平台的安装包。Windows 是.exemacOS 是.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-reasonerbase_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是鉴权 KeyANTHROPIC_MODEL指定默认模型。CC Switch 切换供应商时会自动改写这三个字段所以你不用手动改。如果你用的是 TaoToken 这类聚合通道Base URL 换成https://taotoken.net/apiKey 换成对应平台的 KeyModel 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 配置上。如果返回 401Key 错了返回 404base_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 foundANTHROPIC_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 节逐个排查即可。