1. 为什么我要把 Claude Code 和 DeepSeek 接在一起用先说结论Claude Code 是目前我用过最顺手的终端 AI 编程助手之一但它的官方模型调用成本对国内开发者来说不算友好而且网络链路的稳定性也经常让人头疼。DeepSeek 的 API 价格便宜、中文理解强、代码能力这两年进步非常明显把它接到 Claude Code 里当后端模型是我实测下来性价比最高的组合方案。这套方案解决的核心问题有三个第一成本。Claude Code 官方模型按 token 计费重度使用一天下来账单很可观换成 DeepSeek 之后成本能压到原来的零头。第二可用性。国内直连 DeepSeek 的 API 端点延迟低、不需要额外折腾网络环境终端里敲命令等响应的时间明显缩短。第三中文场景适配。DeepSeek 对中文注释、中文需求描述的理解天然更好写业务代码时沟通成本更低。这篇文章适合谁看如果你满足下面任意一条那这篇内容就是写给你的刚听说 Claude Code 但不知道从哪下手的新手已经装了 Claude Code 但被官方模型费用劝退的人想在终端里用 AI 写代码、又不想折腾复杂配置的开发者以及手里已经有 DeepSeek API Key、想把它物尽其用的人。我会从 Homebrew 安装讲起一路讲到 API Key 配置、CC Switch 切换、跑通第一个任务中间踩过的坑全部摊开讲。需要提前说明的是Claude Code 本身是一个终端里的 AI 编程代理工具它通过读取你的项目文件、执行命令、修改代码来完成任务。它默认对接的是官方模型服务但社区里已经有不少方案可以把它指向兼容 OpenAI 接口协议的第三方模型服务DeepSeek 就是其中之一。整个链路的核心就是让 Claude Code 把请求发到 DeepSeek 的 API 端点而不是官方端点。理解了这一点后面所有配置你都能自己想明白。2. 环境准备Homebrew、Node 和 Claude Code 的安装2.1 先搞定 HomebrewMac 用户的包管理地基Homebrew 是 macOS 上最主流的包管理器你可以把它理解成命令行版的应用商店。装 Claude Code 之前先把 Homebrew 装好后面装 Node、装各种依赖都会省事很多。安装命令官方一直没变/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)这条命令会下载安装脚本并执行。装完之后Apple Silicon 芯片的机器需要手动把 Homebrew 加进 PATH脚本执行完会给你提示照着复制粘贴就行通常是这两行echo eval $(/opt/homebrew/bin/brew shellenv) ~/.zprofile eval $(/opt/homebrew/bin/brew shellenv)Intel 芯片的路径是/usr/local/bin/brew别搞混了。验证安装是否成功敲brew --version能打印出版本号就说明 OK。这里有个很多人踩过的坑Homebrew 已经取消了对 macOS 10.15 及更早版本的支持。如果你的系统还停留在 Catalina 或更早安装脚本会直接报错退出。解决办法只有升级系统没有别的捷径。我见过有人想通过改脚本绕过版本检查结果装出来的 brew 各种依赖报错最后还是要重装系统纯属浪费时间。另一个高频问题是Mac 安装 Homebrew 失败多数情况是网络问题导致脚本下载中断。表现是卡在Downloading and installing Homebrew...不动或者报Failed to connect。我的经验是换个时间段重试或者先确认自己的网络能正常访问脚本地址。如果之前装过又卸载不干净会出现Homebrew 卸载残留导致重装报错这时候需要手动清理/opt/homebrew或/usr/local/Homebrew目录再重装。2.2 Node.js 环境Claude Code 的运行底座Claude Code 是通过 npm 分发的所以必须先有 Node.js。用 Homebrew 装最省心brew install node装完验证一下node -v npm -v建议 Node 版本在 18 以上我实测 20 LTS 最稳。版本太低会出现各种奇怪的模块加载错误。如果你机器上已经有 Node 但是版本很老可以用brew upgrade node升级或者用 nvm 这类版本管理工具切换。提示不要用系统自带的 Node也不要混用多个来源安装的 Node否则 npm 全局包的路径会乱掉后面装 Claude Code 时会出现命令找不到的问题。2.3 安装 Claude Code 本体环境齐了就可以装 Claude Code 了npm install -g anthropic-ai/claude-code装完敲claude --version验证。如果提示command not found八成是 npm 全局 bin 目录没进 PATH。用npm config get prefix看看全局路径在哪然后把这个路径下的bin加进你的 shell 配置文件。Claude Code 在线升级最新版本也很简单重新跑一遍上面的 install 命令即可npm 会自动覆盖旧版本。或者用npm update -g anthropic-ai/claude-code。我一般习惯每隔一段时间手动升一次新版本对模型兼容性和工具调用的改进挺明显的。Ubuntu 用户热词里的 ubantu 是拼写错误正确是 Ubuntu流程基本一致只是 Homebrew 换成 aptsudo apt update sudo apt install nodejs npm sudo npm install -g anthropic-ai/claude-codeLinux 下如果 npm 全局安装报权限错误别直接sudo硬来更推荐配置 npm 的用户级全局目录避免污染系统目录。3. 核心思路拆解Claude Code 怎么接上 DeepSeek3.1 理解 Claude Code 的模型调用机制Claude Code 默认走的是官方模型服务但它支持通过环境变量覆盖 API 端点。核心就是两个变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY或对应的认证变量。把 BASE_URL 指向一个兼容 Anthropic 接口协议的中间层再把 KEY 换成 DeepSeek 的请求就会打到 DeepSeek 那边去。但这里有个现实问题DeepSeek 官方提供的是OpenAI 兼容接口不是 Anthropic 接口协议。两者请求体格式、字段名、响应结构都不一样。所以不能直接把 BASE_URL 改成 DeepSeek 地址就完事中间需要一个翻译层来做协议转换。这就是 CC Switch 这类工具存在的意义。3.2 CC Switch 是什么为什么需要它CC Switch 是一个模型配置切换工具它的作用是帮你管理 Claude Code 对接不同模型服务时的配置并在本地起一个代理层把 Claude Code 发出的 Anthropic 格式请求转换成目标模型能听懂的格式。你可以把它理解成一个协议翻译官 配置管家。为什么不用手写环境变量硬配因为一旦你要在多个模型之间切换比如今天用 DeepSeek明天想试试别的手动改环境变量非常麻烦而且容易改错。CC Switch 把这些配置集中管理切换就是点一下的事。热词里出现的cc switch local proxy failed while handling codex endpoint /responses和unexpected status 404 not found: cc switch local proxy failed while handling都是 CC Switch 本地代理转发时出的问题。前者通常是目标端点路径配错了后者多半是模型服务地址填错或者服务没起来。这两个错误我后面在排查章节会详细讲。3.3 方案选型的几个考量市面上把 Claude Code 接到第三方模型的方案不止一种我选 CC Switch 的理由有这么几条。第一配置可视化不用记一堆环境变量名。第二支持多模型并存DeepSeek、其他兼容模型可以同时配好随时切。第三本地代理稳定跑通之后基本不用管。第四社区活跃遇到问题搜得到答案。当然也有纯手工方案就是自己写个转换脚本或者用别的代理工具。那种方案灵活但维护成本高对新手不友好。如果你只是想快速跑通、稳定用起来CC Switch 是更省事的选择。需要强调的是无论用哪种方案API Key 都是必须自己准备的。DeepSeek 的 Key 要去它的开放平台申请充值后生成。热词里提到的llm-deepseek: no api key for provider route deepseek-official这个报错本质就是配置里声明了用 deepseek-official 这个 provider但没填对应的 Key或者 Key 填错了位置。这个错误的排查我放在第 5 章。4. 实操全流程从装 CC Switch 到跑通第一个任务4.1 获取并安装 CC SwitchCC Switch 有官网和对应的下载渠道去官网下载对应你系统的安装包即可。macOS 用户下载 dmg 拖进 Applications 就完事Windows 用户下载 exe 安装。装完打开界面很简洁主要就是模型配置列表和切换开关。第一次打开如果提示需要初始化配置目录点确认就行它会在你的用户目录下建一个配置文件夹所有模型配置都存在那里。这个目录建议记一下位置后面排查问题时可能要去看里面的配置文件。4.2 申请并配置 DeepSeek API Key去 DeepSeek 开放平台注册账号完成实名和充值最低充值额度不高先充一点点测试完全够用然后在 API Keys 页面创建一个新的 Key。创建后立刻复制保存因为页面刷新后就看不到完整 Key 了只能重新创建。拿到 Key 之后回到 CC Switch新建一个模型配置。关键字段这么填配置项填写内容说明配置名称deepseek-official自定义方便识别即可接口协议OpenAI 兼容DeepSeek 走的是这个协议Base URLhttps://api.deepseek.com官方端点注意不要多加路径API Key你申请到的 Key粘贴时注意别带空格模型名deepseek-chat对话和代码任务用这个模型名这块要留意DeepSeek 有deepseek-chat和deepseek-reasoner两个主要模型。前者通用对话和代码响应快、便宜后者是推理模型适合复杂逻辑但更贵更慢。日常写代码用deepseek-chat就够了。注意Base URL 千万别画蛇添足加/v1或者/chat/completions很多 404 错误就是这么来的。CC Switch 内部会拼接具体路径你只需要填到域名这一层。4.3 启动本地代理并切换配置保存后在 CC Switch 里选中这个 deepseek-official 配置点启用/切换。这时候它会启动本地代理服务通常监听在本机某个端口上。界面上一般会显示代理运行中之类的状态。代理起来之后CC Switch 会自动帮你把 Claude Code 需要的环境变量指向这个本地代理。有些版本需要你手动确认一下应用到 Claude Code或者类似的按钮。确认之后Claude Code 发出的请求就会先到本地代理代理转换成 OpenAI 格式再转发给 DeepSeek。4.4 验证 Claude Code 是否真的在用 DeepSeek这一步很多人会跳过结果用了一周才发现根本没切成功。验证方法很简单在终端里进一个测试项目目录启动 Claude Codecd ~/test-project claude然后随便问一个只有 DeepSeek 才知道答案的问题或者直接看 CC Switch 的代理日志有没有请求进来。最直接的办法是看代理的实时日志如果每次你在 Claude Code 里发消息代理日志都有对应的转发记录那就说明链路通了。另一个验证角度是看响应风格。DeepSeek 和官方模型在中文表达上有细微差别用几次就能感觉出来。当然最靠谱的还是看日志和账单——DeepSeek 后台的用量统计会实时更新用一会儿去刷新看看有没有消耗一目了然。4.5 跑通第一个真实任务配置验证完来跑个真实任务练手。我一般用这种小任务测试让 Claude Code 读一个现有文件然后做个小修改。比如读一下当前目录的 README.md把里面的安装步骤这一节改写成更口语化的表达改完给我看 diff。Claude Code 会去读文件、生成修改、展示差异。整个过程你能看到它调用了哪些工具、发了哪些请求。如果这一步顺利完成说明整套链路完全跑通了。再进阶一点可以试试多文件任务比如给这个项目加一个 utils 目录写一个日期格式化的函数并在主文件里引用它。这种任务会触发文件创建、内容写入、跨文件引用能更全面地验证模型能力。5. 常见报错与排查技巧实录5.1 报错速查表我把这套方案里最常遇到的报错整理成了一张表遇到问题先对号入座报错信息根本原因解决方向llm-deepseek: no api key for provider route deepseek-official配置里声明了 provider 但 Key 没填或填错位置检查 CC Switch 里该配置的 API Key 字段cc switch local proxy failed while handling codex endpoint /responses代理转发时目标端点路径不匹配检查 Base URL 是否多填了路径unexpected status 404 not found请求打到了不存在的地址核对 Base URL 和模型名command not found: claudenpm 全局 bin 没进 PATH配置 shell PATHHomebrew 安装卡住网络中断换时段重试代理显示运行但无请求Claude Code 环境变量没生效重启终端或重新应用配置5.2 关于 no api key 这个报错的深入排查llm-deepseek: no api key for provider route deepseek-official这个报错信息量其实很大。它告诉你三件事第一系统识别到了 deepseek 这个 provider第二路由名是 deepseek-official第三缺的是 api key。排查顺序是这样先确认 CC Switch 里 deepseek-official 这个配置的 API Key 字段确实填了值而且没有多余空格。然后确认这个配置是当前启用状态。再然后有些工具会把 Key 存在单独的配置文件里去配置目录看看那个文件里 Key 是不是空的。最后如果 Key 明明填了还报这个错可能是配置没保存或者代理没重启重启一下代理服务。我遇到过一次特别隐蔽的情况Key 填对了但配置名称里有个空格导致路由匹配失败。所以配置名称尽量用纯英文加连字符别用中文和空格。5.3 代理转发 404 的定位方法cc switch local proxy failed while handling codex endpoint /responses加上unexpected status 404 not found这组合基本锁定在路径问题上。CC Switch 的代理在转发时会把 Claude Code 的请求路径映射到目标服务的路径。如果映射规则和 DeepSeek 的实际接口对不上就会 404。我的排查步骤是先看 CC Switch 的日志找到它实际请求的完整 URL。然后拿这个 URL 去对照 DeepSeek 的接口文档看路径对不对。常见错误是 Base URL 填成了https://api.deepseek.com/v1然后代理又拼了一次/v1/chat/completions变成/v1/v1/...自然 404。把 Base URL 改回纯域名就好了。5.4 几个独家避坑经验第一Key 不要写进任何会提交到代码仓库的文件里。我见过有人把配置连同 Key 一起 commit 上去结果 Key 泄露被人刷爆。CC Switch 的配置目录一般在用户目录下不在项目里这点设计是合理的别自己手动往项目里拷。第二代理端口冲突。如果你本机已经跑了别的服务占用了 CC Switch 默认端口代理会起不来或者行为异常。遇到莫名其妙的连接错误先lsof -i :端口号看看端口被谁占了。第三切换模型后一定要重启 Claude Code 会话。环境变量是在进程启动时读取的你在 CC Switch 里切了模型但已经开着的 Claude Code 会话还是用的旧配置。退出重进一次就好。第四DeepSeek 的响应偶尔会慢。高峰期 API 延迟会上升Claude Code 那边看起来像卡住了。别急着 CtrlC多等几秒。如果经常超时可以在 CC Switch 里调大超时时间。第五模型名写错不会立刻报错。有些情况下模型名不对请求能发出去但返回空或者报奇怪的错。确认模型名和 DeepSeek 文档一致deepseek-chat别写成deepseek_chat或者DeepSeek-Chat。6. 进阶玩法与长期使用建议6.1 多模型配置并存按任务切换CC Switch 最大的价值就是能同时配好几个模型。我的习惯是配三个DeepSeek 的 chat 模型处理日常代码reasoner 模型处理复杂算法和调试再留一个备用配置以防某个服务临时不可用。切换成本几乎为零点一下就行。这种多配置策略在实战里很有用。比如写业务逻辑用便宜的 chat 模型遇到难缠的 bug 切到 reasoner 让它慢慢想。成本和质量之间自己找平衡点。6.2 把 Claude Code 用出效率的几个习惯在项目根目录放一个CLAUDE.md文件写上这个项目的技术栈、代码规范、常用命令。Claude Code 启动时会读这个文件相当于给它一份项目说明书后面它生成的代码会更贴合你的项目风格。这个习惯我强烈推荐能省掉大量它写的东西不符合我项目规范的返工。另外任务描述尽量具体。别说优化一下这个函数要说这个函数在处理空数组时会抛异常帮我加上边界检查并补个测试。描述越具体它一次做对的概率越高来回改的次数越少。6.3 关于成本和用量的监控DeepSeek 后台有用量统计建议每周看一眼。如果发现某天消耗异常高多半是某个任务触发了大量文件读取或者长对话。Claude Code 的上下文管理很重要长会话记得适时清理别让无关的历史把 token 撑爆。我个人实际用下来日常写代码、改 bug、写测试这些任务DeepSeek 的月度成本基本可以忽略不计比官方模型省太多了。只有在处理特别复杂的架构设计时我才会考虑切回更强的模型。6.4 后续可以扩展的方向这套链路跑通之后其实还能玩出很多花样。比如把 Claude Code 接到 CI 流程里做自动代码审查或者配合 git hook 在提交前自动检查。再比如给不同的项目配不同的模型配置前端项目用一个、后端项目用另一个。还有一个方向是本地部署 DeepSeek。热词里提到的本地部署适合对数据隐私要求极高的场景。不过本地部署对硬件要求不低推理速度也比 API 慢除非有硬性合规需求否则我还是推荐直接用 API省心。最后分享一个小技巧CC Switch 的配置文件是可以备份的。配好一套稳定的配置后把配置目录整个备份一份换电脑或者重装系统时直接恢复省得重新配一遍。这个习惯帮我省过好几次事。