1. 思路先理顺Claude Code 为什么能接 DeepSeek API最近在 Ubuntu 上折腾 Claude Code花了一个晚上才把环境理顺过程中踩的坑基本都是 API 配置和环境变量导致的。这篇文章就把我实际跑通的完整流程写出来从 Node 环境、Claude Code 安装到 DeepSeek API 配置一步一步拆开讲顺便把最容易翻车的地方标出来。Claude Code 是 Anthropic 发布的命令行 AI 编程工具装了它之后可以直接在终端里对话式写代码、改代码、执行命令而 DeepSeek API 是深度求索开放平台提供的模型服务它有一个专门兼容 Anthropic 协议的端点所以我们完全可以把 Claude Code 的后端指向 DeepSeek用 DeepSeek 的模型来做 AI 编程助手。这套方案适合理清 Linux 基础操作、想低成本体验 AI 编程助手的开发者也适合本来就在用 DeepSeek API、希望把它接到 Claude Code 生态里的朋友。1.1 Claude Code 到底是什么Claude Code 本质上是一个基于 Node.js 的命令行程序装完之后终端里敲claude就能进入一个交互式会话。它和我平时用的聊天气泡式 AI 不一样它会把你当前项目目录整个当成上下文可以读文件、改文件、跑 shell 命令、执行测试甚至能把报错信息捞出来自己先排查一轮。简单说它不是“帮你写一段代码”的工具而是“陪你完成一个开发任务”的搭档。实际使用中我主要拿它做这几类事情快速生成项目骨架省掉手写目录结构的时间批量重构比如把某个接口的调用方式统一改掉解释老项目里看不懂的历史代码让它先把数据流捋清楚写单元测试体量不大但很耗时的工作交给它很合适。和同类工具 Codex CLI 相比Claude Code 的生态更完整一些支持 plan 模式、自定义斜杠命令、Skills 技能体系在项目里的可玩性和扩展性都更强。装好之后进入会话输入/help可以看所有命令/status看当前模型和上下文状态退出直接/exit。这些命令不用背进去之后随时可以查。有一点要提前说明Claude Code 本身是 Anthropic 官方的工具但它连模型的方式并不是锁死的。它默认走后端 API 时用的是 Anthropic Messages API 这套协议只要某个服务端实现了这套协议Claude Code 就能把请求发过去。这就是所有第三方 API 能接入 Claude Code 的底层原理。1.2 把 API 后端换成 DeepSeek 的关键点DeepSeek 开放平台除了提供标准的 OpenAI 兼容接口之外还专门提供了一个 Anthropic 协议兼容端点。对用户来说这意味着不需要改 Claude Code 的安装方式只要在环境变量里把 API 地址、密钥、模型名指到 DeepSeek 那边Claude Code 就能把 DeepSeek 的模型当成后端来用整个过程不需要 Anthropic 官方账号登录也不用买 Anthropic 的订阅。打个比方插头规格一样的情况下你完全可以把台灯的插座从 A 品牌换成 B 品牌灯照样亮。协议兼容就是那个“统一插头”。不过协议兼容不代表每个细节都 100% 等价实际操作里有两件事必须注意一是模型名要显式告诉 Claude Code否则它默认发的是 Claude 系列模型名DeepSeek 端点不认就会报 404二是 Claude Code 内部有些“小任务”会调用一个轻量模型这个模型名同样需要指定。这两件事就是整篇文章最核心的避坑点后面我会一步步拆开讲。2. Ubuntu 环境准备Node.js 装好才能跑 Claude Code2.1 先检查系统版本和基础依赖不管你是 Ubuntu 22.04 还是 24.04或者刚装好的虚拟机系统第一步都建议先把软件源和系统软件包更新一遍避免依赖版本太旧导致后面各种莫名其妙的问题sudo apt update sudo apt upgrade -y然后确认系统信息没问题cat /etc/os-releaseClaude Code 的 Linux 版在运行时会调用一些系统库和命令建议提前装好构建工具链和 Python3。虽然不装某些情况下也能跑但遇到编译原生模块或者执行脚本的场景就会缺东西sudo apt install -y build-essential python3 libstdc6build-essential里面包含 gcc、g、make 这些常用工具Ubuntu 上很多软件源码编译都依赖它装好之后能少踩很多坑。如果你的服务器是精简安装可能连 curl 都没有顺手装一下sudo apt install -y curl wget git这里多说一句如果apt update报源失效或者拉取速度特别慢不要急着继续先检查一下/etc/apt/sources.list里的软件源配置把源修好再往下走。否则后面安装任何东西都会牵连出错。2.2 推荐用 nvm 安装 Node.js而不是直接 apt 装Claude Code 是基于 Node.js 的所以先要把 Node 环境搞定。这里有个很多新手都会踩的坑直接用sudo apt install nodejs npm虽然很快但 Ubuntu 软件源里的 Node 版本往往偏旧而且用 apt 全局安装 npm 包很容易遇到权限问题典型报错是EACCES: permission denied。我的建议是用 nvm 装 Node好处有三个不需要 sudo、可以随意切换 Node 版本、npm 全局包会装到用户目录权限干干净净。nvm 安装很简单执行官方安装脚本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash脚本执行完需要重新加载 shell 配置。Ubuntu 默认用的 bash执行source ~/.bashrc验证 nvm 是否装好nvm --version接着安装最新的 LTS 版本 Nodenvm install --lts node -v npm -v这里有个容易忽略的点nvm 安装完成后会往.bashrc里追加一段初始化脚本但当前已经打开的终端窗口不会自动生效必须source或重新开窗口。如果你用 zsh对应的文件是~/.zshrc操作同理。Claude Code 对 Node 版本的最低要求是 18但实际用下来我建议至少 20 或以上LTS 版本最稳。nvm 安装的 Node 会把 npm 全局目录放到用户主目录下后面全局安装 Claude Code 就不用加 sudo非常省心。再配合nvm alias default lts/*可以保证之后新开的终端都默认使用 LTS 版本避免“终端一重启 node 就没了”的错觉。2.3 apt 安装 Node 的替代方案如果你不喜欢 nvm或者服务器已经有现成的 Node 环境也可以用 apt 直接装sudo apt install -y nodejs npm但我必须提醒一句apt 源里的 Node 版本通常比较保守装完后先执行node -v确认版本。如果低于 18就得再想办法升级一个常见的方式是通过n这个工具切换版本sudo npm install -g n sudo n ltsapt 方式有个隐患npm 全局安装包的位置在系统目录下普通用户安装会报权限错误很多人图省事直接sudo npm install -g虽然能用但后面 npm 缓存和全局包的权限会越来越乱。所以除非是临时测试环境我还是建议老老实实用 nvm。另外如果你在 Windows 上折腾 PowerShell 安装大部分报错本质也是 Node 版本太旧、npm 全局 bin 不在 PATH、或者权限不够解决思路和 Ubuntu 是一样的装一个最新的 Node LTS用管理员身份重新打开终端再执行全局安装。3. 安装 Claude Codenpm 全局安装与官方脚本怎么选3.1 npm 全局安装 Claude CodeNode 环境准备好之后安装 Claude Code 本身其实就是一条命令npm install -g anthropic-ai/claude-code安装过程会下载不少依赖包需要耐心等一会儿。装完以后验证一下claude --version如果能看到类似1.0.x的版本号输出说明安装成功了。这里有个细节因为我们是 nvm 装的 Node全局 bin 目录已经在 PATH 里所以claude命令可以直接敲如果你是用 apt 装的 Node可能会遇到command not found: claude那就要检查 npm 全局 bin 目录是否已经加入到 PATH执行npm prefix -g看看全局路径然后把对应的bin目录加进去。npm 方式更新 Claude Code 也很方便直接重新执行一次npm update -g anthropic-ai/claude-code如果发现新版本有问题想回退到指定版本可以这样npm install -g anthropic-ai/claude-code1.0.10版本号按你自己需要的填回滚前最好先看一眼当前配置别把自定义设置覆盖丢了。3.2 官方脚本安装作为备选除了 npmAnthropic 官方也提供了一个安装脚本适合不想折腾 npm 全局包的同学curl -fsSL https://claude.ai/install.sh | bash这个脚本会把 Claude Code 装到用户目录下不需要 sudo通用性更强。装完同样用claude --version验证。这两种方式怎么选我的实际感受是如果你已经用 nvm 管理 Nodenpm install -g是最顺手的升级回滚都方便如果你是临时环境、或者 Node 版本管理比较乱官方脚本更省事。两个方式不冲突但没必要同时装否则会出现两个claude可执行文件后面排查问题反而麻烦。有一点必须提醒从网上复制curl ... | bash这类命令之前最好先把脚本内容下载下来看一眼确认安装路径和要执行的操作符合预期。这算一个基本的安全习惯尤其是涉及全局安装、修改 shell 配置的操作多一步审查能避免很多风险。3.3 安装完成后的目录和文件用 nvm npm 方式安装后Claude Code 主要落在两个地方可执行文件在 npm 全局 bin 目录下也就是$NVM_DIR/.../bin/claude配置和缓存目录在用户主目录下主要是~/.claude/~/.claude/这个目录以后会比较重要项目的全局设置文件、历史会话记录、一些缓存都在里面。如果你要换机器或者备份配置把~/.claude/settings.json保存好就能带走大部分自定义内容。这一点平常不太会注意到等真正需要迁移环境时才发现很有用。4. DeepSeek API 配置3 个环境变量接管 Claude Code4.1 注册 DeepSeek 开放平台并创建 API Key在配置环境变量之前先去 DeepSeek 开放平台注册账号进入控制台之后创建一个 API Key。DeepSeek 的 Key 通常是sk-开头的一长串字符创建之后只会完整显示一次要立刻复制保存好。如果 Key 泄露了可以在控制台里删除重建不要留着隐患。DeepSeek API 是预付费模式账户里要有余额才能调用成功。我见过不少朋友配完环境变量后一直报错折腾半天才发现是账户余额为 0。所以做好 Key 之后记得先确认账户已经充值或有可用额度。充值的时候看清楚计费说明DeepSeek 的价格还是比较便宜的尤其deepseek-chat的日常对话和代码生成成本比很多同类服务低不少。模型选择方面DeepSeek 开放平台目前常用的有两个模型deepseek-chat和deepseek-reasoner。前者是通用对话模型响应快、价格低日常写代码用它最合适后者是推理模型适合复杂逻辑、数学、深度分析这类任务但响应更慢、费用更高。在 Claude Code 里日常使用我会优先推荐deepseek-chat只有遇到特别烧脑的问题才临时切到deepseek-reasoner。4.2 四个环境变量的作用和推荐配置Claude Code 启动时会读取一组和 Anthropic 相关的环境变量。我们把其中几个关键变量指到 DeepSeek就能完成后端切换环境变量作用推荐值ANTHROPIC_BASE_URLAPI 请求地址https://api.deepseek.com/anthropicANTHROPIC_AUTH_TOKEN鉴权密钥你的 DeepSeek API KeyANTHROPIC_MODEL主模型名deepseek-chatANTHROPIC_SMALL_FAST_MODEL后台轻量任务模型名deepseek-chat第一个变量的作用是把请求地址从 Anthropic 官方换成 DeepSeek 的 Anthropic 兼容端点。注意这里一定要用/anthropic这个路径很多人直接写https://api.deepseek.com或者https://api.deepseek.com/v1结果请求协议对不上Claude Code 会一直报deepseek api request to https://api.deepseek.com failed。第二个变量放你的 DeepSeek API Key。理论上也可以用ANTHROPIC_API_KEY这个变量但我实际测试下来ANTHROPIC_AUTH_TOKEN的优先级更高两个都设置时以 token 为准。为了避免混淆建议统一用ANTHROPIC_AUTH_TOKEN不要同时设两个。第三个和第四个变量是重点避坑项。你不指定模型名时Claude Code 默认会发claude-sonnet-4-xxx这类 Claude 系列模型名过去DeepSeek 兼容端点收到这种模型名大概率直接返回 404或者告诉你 model not found。设成deepseek-chat之后才能真正用上 DeepSeek 的模型。第四个小模型变量也是一样的道理Claude Code 内部做标题生成、上下文摘要这类轻量任务时会调用一个小而快的模型这个模型名如果不指定同样会报错所以也要一并设置。4.3 配置写到 shell 还是 settings.json最简单的方案是把环境变量写进~/.bashrc执行下面的命令替换成你自己的 Keycat ~/.bashrc EOF export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKENsk-你的DeepSeekKey export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_SMALL_FAST_MODELdeepseek-chat EOF source ~/.bashrc然后检查一下是否生效env | grep ANTHROPIC如果你不想把 Key 写进全局 shell 配置也可以放到 Claude Code 的 settings.json 里。Claude Code 支持用户级配置文件和项目级配置文件分别在~/.claude/settings.json和项目根目录的.claude/settings.json。里面的env字段可以直接注入环境变量{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: sk-你的DeepSeekKey, ANTHROPIC_MODEL: deepseek-chat, ANTHROPIC_SMALL_FAST_MODEL: deepseek-chat } }两种方式效果类似。我个人的习惯是个人开发环境用.bashrc方便全局生效多项目开发或团队协作时用项目级settings.json不同项目可以指定不同模型。不管用哪种都要注意不要把 Key 提交到 git 仓库尤其是项目级 settings.json 里放了 Key 的话记得在.gitignore里把它忽略掉或者干脆只在本地用环境变量注入。5. 实操验证从启动 Claude Code 到真正跑通5.1 启动前的最终检查清单配置完了别急着开心先做一个两分钟的检查能帮你省下后面排查报错的时间node -v claude --version env | grep ANTHROPIC curl -I https://api.deepseek.com第一项确认 Node 版本在 18 以上第二项确认 Claude Code 装好第三项确认四个环境变量都在第四项用 curl 探测一下 DeepSeek API 的网络连通性能看到 HTTP 响应头说明网络没问题如果这里都不通后面就不用折腾 Claude Code 了先解决网络问题再说。这里说的“网络问题”包括服务器出网策略是否允许访问api.deepseek.com、DNS 能不能正常解析、防火墙有没有拦截。在 Ubuntu 上可以再执行一次curl -v https://api.deepseek.com看详细握手过程定位到具体哪一步卡住比盲目改代码有效得多。注意curl -I发的是 HEAD 请求不会消耗 API 额度可以放心用。5.2 启动交互界面并做一次真实测试一切就绪后在项目目录下直接运行claude首次进入会有一个欢迎界面和简短的初始化说明。这个阶段它不会要求你用浏览器登录账号因为我们已经通过ANTHROPIC_AUTH_TOKEN指定了鉴权方式它直接拿这个 Key 去访问 DeepSeek 端点了。进入交互会话之后可以先用/status命令查看当前使用的模型信息确认显示的模型名是deepseek-chat。然后随便扔一个实际任务过去比如帮我在当前目录创建一个 Python 文件实现一个快速排序函数并附上两个单元测试用例。如果它正常开始读目录、创建文件、写代码说明整条链路已经通了。你也可以用非交互方式快速测试claude 用三句话解释什么是闭包并用 Python 举例想要让输出直接打到标准输出适合在脚本里调用可以加--print参数claude --print 列出当前目录下所有文件的大小需要提醒的是DeepSeek API 是按 token 计费的测试时不要一次扔一个超大任务进去先小成本确认通了再上量。5.3 在 VS Code 里集成使用很多人习惯在 IDE 里干活Claude Code 同样可以塞进 VS Code。最简单的用法是打开 VS Code 的集成终端直接运行claude它就能读取当前打开的文件夹内容和你在终端里用效果一样。想体验更好一点可以到 VS Code 扩展市场搜“Claude Code”官方扩展安装后可以直接在侧边栏操作界面更现代还能看到会话历史和文件变更预览。如果你已经习惯了终端工作流那可以不用装扩展直接在 VS Code 的集成终端里跑才是最顺手的。Claude Code 对路径的理解就是“当前工作目录”所以不管在哪个终端里启动记得先确认pwd是不是你想让它操作的目录。有一次我就是在项目根目录下启动了 claude后来才发现终端停在别的路径白白折腾了一轮。5.4 第一次跑通后的两个小建议第一建议把模型从deepseek-chat切到deepseek-reasoner体验一次对比复杂任务下的回答质量日常写代码再切回deepseek-chat省 token 也快。切换可以在会话里通过/model命令完成不用改环境变量重启。第二跑通之后去 DeepSeek 开放平台的用量统计页看一眼对一次编码会话大概消耗多少 token 心里有个数后面做成本评估和预算控制就有底了。我自己一次常规的“写一个工具函数 跑一下测试”的会话消耗很有限但如果你让它一次处理整个仓库的大规模重构token 消耗会明显上涨建议分步骤、分任务地提问既省钱又不容易把上下文顶爆。6. 踩坑实录这些报错我基本都遇到过6.1 高频问题排查顺序我把实际踩过的坑和社区里高频出现的问题整理成了一张表按这个顺序排查基本能覆盖 90% 的情况报错症状可能原因解决办法command not found: claudenpm 全局 bin 不在 PATH用 nvm 重装 Node或执行npm prefix -g后把 bin 目录加入 PATH安装时报EACCES: permission deniednpm 全局目录权限不足不要 sudo npm改用 nvm 安装 Node全局包会装到用户目录Authentication error/ 401API Key 错误或未生效检查ANTHROPIC_AUTH_TOKEN是否设置了正确的 DeepSeek Keyenvdeepseek api request to https://api.deepseek.com failed网络不通或 BASE_URL 写错先用 curl 测连通性确认 BASE_URL 是https://api.deepseek.com/anthropicmodel not found/ 404模型名不对设置ANTHROPIC_MODELdeepseek-chat并确认名称大小写rate limit/ 429账户余额不足或并发超限检查 DeepSeek 账户余额降低请求频率或稍等重试your organization has disabled claude subscription access for claude code没有走第三方 API 鉴权Claude Code 尝试用官方账号登录确认ANTHROPIC_AUTH_TOKEN已设置并重新启动 claude表格之外单独说一句 401 的问题。很多朋友在~/.bashrc里写了 Key也source了却依然 401。这时候先别怀疑 Key 错了执行env | grep ANTHROPIC看环境变量有没有真的进到当前 shell。如果输出里没有大概率是source ~/.bashrc没成功或者 Key 里带了多余的空格和引号粘贴的时候稍微检查一下。6.2 三个容易被忽略的细节第一个细节是环境变量优先级。如果同时设置了ANTHROPIC_API_KEY和ANTHROPIC_AUTH_TOKENClaude Code 会优先用 token而 token 默认情况下可能还是旧的或者错的。我建议只保留ANTHROPIC_AUTH_TOKEN一个变量干净又省心。第二个细节是项目里可能存在的.claude/settings.json。有时候你在终端里配好了.bashrc但进入某些项目后行为却不对很可能是项目级 settings.json 里的env覆盖了全局变量。遇到诡异问题先看一眼项目里有没有这个文件反客为主的往往就是它。第三个细节是 DeepSeek 模型名的确切写法。不同版本、不同文档里看到的模型名可能不一样比如deepseek-v3、deepseek-r1这些叫法实际在 API 里的取值要以 DeepSeek 开放平台文档为准。我在配置时用的是deepseek-chat和deepseek-reasoner如果你换了模型名之后一直报 404去查一下官方文档别凭记忆猜。6.3 升级、回滚和卸载Claude Code 更新比较频繁遇到行为变化不要慌先看版本。升级命令是npm update -g anthropic-ai/claude-code官方脚本安装的就重新跑一遍脚本。如果升级后反而有问题可以用npm install -g anthropic-ai/claude-code版本号回退到之前能用的版本。回滚前最好把自己的配置文件备份一下尤其是settings.json里的自定义内容。卸载和安装一样一条命令的事npm uninstall -g anthropic-ai/claude-code如果想连配置、历史会话一起清掉手动删除~/.claude/目录即可。卸载前确认没有正在运行的任务另外如果项目里有.claude/目录那是项目配置不会因为卸载全局包而消失需要单独处理。最后再说一个实操体会整套流程里最容易出问题的不是安装而是环境变量。我见过太多人卡在model not found或者render to https://api.deepseek.com failed上一查原因要么是 BASE_URL 少了/anthropic要么是模型名没指定。建议第一次配置时严格按照env | grep ANTHROPIC这条命令把四个变量逐一确认一遍再启动 claude可以省掉大量无意义的排错时间。还有一个小习惯每次改完.bashrc或配置文件先source再开新的 claude 会话避免旧进程里还是老配置。这里的坑我在第一次配置时基本都踩过写出来就是希望你能一次跑通。