Ubuntu 上配置 Claude Code 接入 DeepSeek API 完整指南

1. 为什么要在 Ubuntu 上折腾 Claude Code 加 DeepSeek

先把话说在前头：这套组合不是给所有人准备的。如果你平时写代码就是打开 IDE 敲两行、跑个测试就完事，那确实没必要折腾。但如果你属于下面这几类人，这套方案值得花一个下午搞明白。

第一类是日常在 Linux 环境下干活的开发者。Ubuntu 作为主力开发机的人都知道，终端里能直接调用一个懂代码的 AI 助手，和切到浏览器里复制粘贴，效率完全不是一个量级。Claude Code 这类工具的核心价值就在于它活在终端里，能直接读你的项目文件、执行命令、改代码，不用来回切换窗口。

第二类是对模型调用成本敏感的人。Claude 官方模型能力确实强，但按量计费下来，重度使用一个月账单不好看。DeepSeek 系列模型在代码任务上的表现这两年进步非常明显，关键是价格友好得多。把 Claude Code 这个客户端接到 DeepSeek 的接口上，等于用更低的成本拿到接近的体验。

第三类是喜欢自己掌控工具链的人。市面上的 AI 编程助手大多是闭源 SaaS，你的代码要传到别人服务器上，配置也没法改。Claude Code 支持自定义 API 端点，这意味着你可以把它指向任何兼容的接口，包括国内可直连的服务。数据流向、模型选择、调用频率，全在自己手里。

需要提前说清楚的是，这套方案涉及几个核心概念：Node.js 运行时、npm 包管理、环境变量配置、API 兼容层。如果你对这几个词完全陌生，建议先花半小时补一下基础，否则后面每一步都会卡。但也不用怕，我会把每个环节拆到能直接抄的程度。

提示：本文所有操作基于 Ubuntu 22.04 LTS 桌面版和服务器版通用，其他版本如 20.04、24.04 命令基本一致，个别差异我会标注。

2. 动手前的环境盘点与依赖梳理

2.1 先搞清楚你的 Ubuntu 是什么状态

很多人一上来就复制粘贴安装命令，结果报一堆错，根本原因是没确认系统底子。打开终端，先跑这几条命令看看情况。

# 查看系统版本 lsb_release -a # 查看内核版本 uname -r # 查看当前用户是否有 sudo 权限 sudo -v # 查看磁盘剩余空间 df -h /

lsb_release -a会输出类似Ubuntu 22.04.4 LTS的信息。为什么要看这个？因为不同 Ubuntu 版本自带的软件源里，Node.js 的版本差别很大。22.04 默认源里的 Node.js 是 12.x，这个版本太老了，跑不了 Claude Code，必须手动升级。

df -h /看根分区剩余空间，建议至少留 5GB。Node.js 加上 npm 全局包，再加上 Claude Code 本身，装下来差不多 1GB 出头，但后续 npm 缓存会膨胀，留足空间省得后面清理。

2.2 Node.js 版本这道坎必须过

Claude Code 对 Node.js 版本有硬性要求，官方推荐Node.js 18 或更高版本。我实测下来，18.20.4 LTS 这个版本最稳，20.x 也没问题，但 21.x 这种奇数版本偶尔会有兼容性小毛病。

为什么版本这么关键？因为 Claude Code 底层用了不少较新的 JavaScript 语法和 Node API，老版本 Node 直接报SyntaxError或者模块找不到。这就像你拿十年前的浏览器打开现在的网页，一堆特性不支持。

检查当前版本：

node -v npm -v

如果输出是v12.x或者命令直接不存在，那就得装。装 Node.js 有好几种路子，我一个个说清楚利弊。

方案一：用 NodeSource 官方源装（推荐）

这是最省心的方式，NodeSource 维护了各版本的 apt 源，装完能用apt upgrade统一管理。

# 先装必要工具 sudo apt update sudo apt install -y curl ca-certificates gnupg # 添加 NodeSource 的 18.x 源 curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - # 安装 Node.js sudo apt install -y nodejs # 验证 node -v npm -v

这里有个坑要提醒：curl | sudo -E bash -这种管道执行脚本的方式，本质是把远程脚本直接跑在你系统上。NodeSource 是可信源，但如果你在公司内网或者对安全要求高的环境，建议先把脚本下载下来看一眼再执行。

方案二：用 nvm 管理多版本

如果你机器上已经有别的项目依赖特定 Node 版本，用 nvm 更灵活，可以随时切换。

# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装并使用 Node 18 nvm install 18 nvm use 18 nvm alias default 18

nvm 的好处是版本隔离，坏处是它只对当前用户生效，而且每次新开终端要确保 nvm 被加载。如果你用 zsh，记得改~/.zshrc。

方案三：直接下二进制包

去 Node.js 官网下载 Linux x64 的 tar.xz 包，解压后手动配 PATH。这种方式最干净，不污染系统包管理，但升级要手动来。适合不想动系统源的人。

我个人推荐方案一，因为 Ubuntu 上 apt 管理最省事，出问题也好排查。

2.3 npm 源的问题别忽视

装完 Node.js 后，npm 默认走的是国外源，国内下载包经常卡住或者超时。换国内镜像能快很多。

# 查看当前源 npm config get registry # 换成国内镜像 npm config set registry https://registry.npmmirror.com # 验证 npm config get registry

这一步不是必须的，但如果你发现npm install卡在sill fetch半天不动，八成就是源的问题。换完镜像再装，速度能差十倍。

注意：有些公司内网有自己的 npm 私服，换源前先问清楚，别把公司配置覆盖了。

3. Claude Code 的安装与验证

3.1 全局安装 Claude Code

环境准备好之后，装 Claude Code 本身其实就一条命令：

npm install -g @anthropic-ai/claude-code

-g表示全局安装，这样在任何目录下都能直接敲claude命令调用。装完之后验证一下：

claude --version

如果输出版本号，说明装成功了。如果报command not found，大概率是 npm 全局 bin 目录没在 PATH 里。查一下：

npm config get prefix

这个命令会输出一个路径，比如/usr/local或者/home/你的用户名/.npm-global。确保这个路径下的bin目录在 PATH 里。检查方法：

echo $PATH

如果没包含，编辑~/.bashrc，在末尾加一行：

export PATH="$PATH:$(npm config get prefix)/bin"

然后source ~/.bashrc生效。

3.2 权限报错怎么处理

用sudo npm install -g装包是很多人的习惯，但这会带来权限问题。npm 官方其实不建议用 sudo 装全局包，因为装出来的文件属主是 root，后续普通用户操作会各种 permission denied。

如果你已经用 sudo 装过了，出现EACCES错误，有两个解法。

解法一是改 npm 全局目录到用户目录：

mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' export PATH="$PATH:$HOME/.npm-global/bin"

把最后一行加到~/.bashrc里，然后重新装一遍 Claude Code，这次不加 sudo。

解法二是修复已有目录权限：

sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

这个命令把 npm 相关目录的属主改成当前用户，之后就能正常操作了。

3.3 首次运行会碰到什么

第一次敲claude命令，它会引导你做初始配置。默认情况下它想连 Anthropic 官方服务，需要登录账号或者填 API Key。但我们这次的目标是接 DeepSeek，所以先别急着按它的引导走。

你可以先按 Ctrl+C 退出，或者跳过登录，直接进入配置环节。Claude Code 的配置主要通过环境变量和配置文件两个途径，下面详细说。

4. 接入 DeepSeek 的核心配置

4.1 理解 API 兼容层这件事

这里要讲清楚一个关键原理，不然配置起来会一头雾水。

Claude Code 这个客户端，原本是设计来跟 Anthropic 的 Claude 模型对话的。它发送的请求格式、认证方式，都是按 Anthropic 的 API 规范来的。而 DeepSeek 提供的是另一套 API，虽然功能类似，但请求格式、字段名、认证头都不一样。

那怎么让它们对上话？答案是兼容层。DeepSeek 官方提供了兼容 Anthropic API 格式的端点，也就是说，你可以把 Claude Code 的请求直接发到 DeepSeek 的服务器，它会按 Anthropic 的格式解析并返回。这就是整个方案能成立的技术基础。

具体来说，需要配置两个核心环境变量：

• ANTHROPIC_BASE_URL：告诉 Claude Code 把请求发到哪个地址，默认是 Anthropic 官方，我们要改成 DeepSeek 的兼容端点。
• ANTHROPIC_API_KEY：认证用的密钥，填你在 DeepSeek 平台申请的 API Key。

4.2 申请 DeepSeek API Key

去 DeepSeek 开放平台注册账号，在控制台里找到 API Keys 页面，创建一个新的 Key。创建时会显示一次完整密钥，务必立刻复制保存，关掉页面就再也看不到了。

Key 的格式通常是一串以sk-开头的长字符串。拿到之后先别急着填，我们分两种方式来配置。

4.3 方式一：临时环境变量（适合测试）

如果你只是想先试试能不能通，用临时环境变量最快：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_API_KEY="sk-你的密钥" claude

这种方式只在当前终端会话有效，关掉终端就没了。适合验证阶段，确认能跑通再写进配置文件。

4.4 方式二：写进 shell 配置（长期使用）

确认能用之后，把这两行加到~/.bashrc末尾：

export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_API_KEY="sk-你的密钥"

然后source ~/.bashrc。这样每次开终端都自动生效。

但这里有个安全问题：API Key 明文写在.bashrc里，如果这台机器多人共用，或者你不小心把配置文件传到网上，Key 就泄露了。更稳妥的做法是单独放一个文件，权限设成只有自己能读：

# 创建密钥文件 echo 'export ANTHROPIC_API_KEY="sk-你的密钥"' > ~/.claude_env chmod 600 ~/.claude_env # 在 .bashrc 里引用 echo 'source ~/.claude_env' >> ~/.bashrc

chmod 600保证只有文件属主能读写，其他用户连看都看不到。

4.5 指定模型名称

DeepSeek 的兼容端点支持多个模型，你可以在配置里指定用哪个。Claude Code 通过ANTHROPIC_MODEL环境变量来指定模型名。

export ANTHROPIC_MODEL="deepseek-chat"

具体模型名以 DeepSeek 平台文档为准，不同时期可能有调整。如果你不指定，它会用默认模型。我建议显式指定，避免默认值变化导致行为不一致。

4.6 配置验证与连通性测试

配置完之后，怎么确认真的连上了 DeepSeek 而不是还在走 Anthropic？

最直接的方法是看响应。启动claude后随便问一个问题，比如"你好，你是什么模型"。如果返回的内容风格、响应速度跟 DeepSeek 一致，基本就对了。

更严谨的做法是抓包或者看日志。Claude Code 支持调试模式：

claude --debug

调试输出里会显示实际请求的 URL，如果看到api.deepseek.com就说明配置生效了。

还有一个验证点：如果你填的 API Key 是错的，请求会返回 401 认证失败。如果 Base URL 填错，会返回 404 或者连接超时。根据报错类型能快速定位是哪一步出了问题。

提示：DeepSeek 的兼容端点地址可能随版本更新变化，配置前建议去官方文档确认最新的 Base URL，别照搬旧教程里的地址。

5. 实操全流程与关键环节拆解

5.1 从零到跑通的完整命令序列

把前面所有步骤串起来，一个全新 Ubuntu 系统从零到能用，完整流程如下。我按顺序列出来，你可以直接照着敲。

# 第一步：更新系统包索引 sudo apt update && sudo apt upgrade -y # 第二步：安装基础工具 sudo apt install -y curl ca-certificates gnupg build-essential # 第三步：添加 NodeSource 源并安装 Node.js 18 curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt install -y nodejs # 第四步：验证 Node.js node -v # 应输出 v18.x.x npm -v # 应输出 9.x 或 10.x # 第五步：换 npm 国内镜像（可选但推荐） npm config set registry https://registry.npmmirror.com # 第六步：全局安装 Claude Code npm install -g @anthropic-ai/claude-code # 第七步：验证安装 claude --version # 第八步：配置 DeepSeek 接入 echo 'export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic"' >> ~/.bashrc echo 'export ANTHROPIC_API_KEY="sk-你的密钥"' >> ~/.bashrc echo 'export ANTHROPIC_MODEL="deepseek-chat"' >> ~/.bashrc source ~/.bashrc # 第九步：启动测试 claude

这套流程我在三台不同配置的机器上跑过，只要网络正常，基本不会出问题。唯一需要注意的是第三步，NodeSource 脚本执行时会联网下载，网络不好的话可能失败，重试一次通常就好。

5.2 为什么用 build-essential

上面第二步装了build-essential，这个不是必须的，但强烈建议装。原因是 npm 在安装某些包时，如果找不到预编译的二进制版本，会尝试从源码编译，这时候就需要 gcc、make 这些工具。不装的话会报gyp ERR!之类的编译错误。

build-essential是个元包，一次性把 gcc、g++、make、libc 开发库都装上，省得一个个装。Ubuntu 上装 gcc 失败通常是因为源没更新或者依赖冲突，先sudo apt update再装基本能解决。

5.3 环境变量配置的常见错误

环境变量这块是新手最容易翻车的地方，我见过好几种典型错误。

错误一：引号问题。写export ANTHROPIC_API_KEY=sk-xxx不加引号，如果 Key 里恰好有特殊字符（虽然一般没有），会被 shell 解释。养成加引号的习惯。

错误二：等号两边加空格。export KEY = "value"这种写法是错的，shell 会把KEY当成命令。正确写法是等号两边不能有空格。

错误三：改了 .bashrc 没 source。改完配置文件必须source ~/.bashrc或者重开终端，否则当前会话不生效。很多人改完直接测试，发现没变化，以为配置错了，其实是没加载。

错误四：用了 zsh 却改 bashrc。如果你默认 shell 是 zsh，改~/.bashrc没用，要改~/.zshrc。用echo $SHELL确认当前 shell。

错误五：多个配置文件冲突。有些系统里.bash_profile和.bashrc都会加载，如果两处都设了同名变量，后加载的会覆盖前面的。排查时用echo $ANTHROPIC_BASE_URL看实际生效的值。

5.4 在 VS Code 里用起来

Claude Code 是终端工具，但很多人主力编辑器是 VS Code。两者可以配合使用。

最直接的方式是在 VS Code 里打开集成终端，直接敲claude。这样 Claude Code 能访问当前项目目录，改代码、跑命令都方便。

如果你想让 Claude Code 和 VS Code 的编辑器功能联动，可以装一些辅助插件，但核心还是终端里的claude命令。VS Code 的终端会自动继承系统的环境变量，所以前面配好的 DeepSeek 接入在 VS Code 终端里同样生效。

有个小技巧：在 VS Code 里按Ctrl+``打开终端，默认就在当前项目根目录，直接claude启动，它就能读到整个项目结构，比在别的目录启动再cd过去方便。

6. 常见问题排查与避坑实录

6.1 安装阶段的问题

问题：npm install -g报 EACCES 权限错误。

这是最常见的。原因是用 sudo 装过东西，或者 npm 全局目录属主不对。解法参考 3.2 节，把 npm prefix 改到用户目录，或者修复目录权限。别用sudo npm install -g硬刚，治标不治本。

问题：Node.js 版本太低，Claude Code 装不上。

报错信息通常是Unsupported engine或者语法错误。用node -v确认版本，低于 18 就按第 2 节的方法升级。注意升级后要确认which node指向的是新版本，有时候系统里存在多个 Node，PATH 顺序不对会用回旧的。

问题：npm 下载卡住或者超时。

先换国内镜像。如果换了还不行，检查网络代理设置。有些环境需要配npm config set proxy和https-proxy，但如果你不清楚公司网络策略，别乱配，问运维。

问题：claude: command not found。

npm 全局 bin 目录不在 PATH 里。用npm config get prefix找到路径，把bin子目录加进 PATH。改完记得 source。

6.2 运行阶段的问题

问题：启动后提示认证失败 401。

API Key 错了或者过期了。去 DeepSeek 平台重新生成一个，注意复制完整，别漏字符。另外确认 Key 没有多余的空格或换行。

问题：请求超时或者连接被拒。

Base URL 填错了。确认地址是 DeepSeek 官方文档里给的兼容端点，注意结尾不要多加斜杠。有些教程里的地址是旧的，以官方最新文档为准。

问题：能连上但返回内容不对，或者模型行为异常。

可能是模型名指定错了。检查ANTHROPIC_MODEL的值是否是 DeepSeek 支持的模型名。不指定的话用默认模型，但默认模型可能不是你想要的。

问题：响应特别慢。

DeepSeek 服务端负载高的时候会慢，这是服务端问题，本地没法解决。可以错峰使用，或者检查自己的网络出口是否拥堵。

6.3 排查速查表

6.4 几个我踩过的坑

第一个坑是环境变量作用域。我一开始把配置写在了~/.profile里，结果发现图形界面终端不加载这个文件，只有登录 shell 才读。后来统一写到~/.bashrc才稳定。Ubuntu 桌面版的终端默认是非登录 shell，读的是.bashrc不是.profile，这个区别要记住。

第二个坑是多版本 Node 冲突。我机器上之前用 apt 装过一个 Node，后来又用 nvm 装了一个，结果which node指向 nvm 的，但sudo node用的是 apt 的。因为 sudo 会重置 PATH，用的是系统默认。如果你需要用 sudo 跑 node 相关命令，要么用sudo -E保留环境变量，要么干脆别用 sudo。

第三个坑是API Key 泄露风险。我有次把.bashrc截图发到群里问问题，忘了打码，Key 直接暴露。虽然马上删了重新生成，但这是个教训。涉及密钥的文件，截图、分享、提交 git 之前一定要检查。

第四个坑是DeepSeek 端点变更。早期教程里的 Base URL 和现在的不一样，我照着旧教程配了半天连不上，后来去官方文档一看地址早换了。这类第三方兼容端点的地址不是永久固定的，配置前务必查最新文档。

7. 性能调优与进阶玩法

7.1 让响应更快一点

DeepSeek 的响应速度受服务端影响大，但本地也有能优化的地方。

一是减少上下文长度。Claude Code 会把当前项目的一些文件内容作为上下文发给模型，项目越大，发的越多，响应越慢。你可以在启动时限制它读取的范围，或者把不相关的大文件排除掉。

二是合理设置超时。默认超时可能偏短，网络波动时容易断。可以通过环境变量调整，具体参数名看 Claude Code 文档。

三是错峰使用。国内访问 DeepSeek 服务，晚高峰时段响应会慢一些，如果任务不急，可以放到非高峰时段跑。

7.2 多模型切换的思路

如果你同时有多个模型的 API，想在不同场景用不同模型，可以通过切换环境变量实现。写几个小脚本，比如use-deepseek.sh、use-other.sh，每个脚本里 export 对应的配置，用的时候 source 一下就行。

# use-deepseek.sh export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_API_KEY="sk-deepseek的key" export ANTHROPIC_MODEL="deepseek-chat" echo "已切换到 DeepSeek"

这样比手动改.bashrc灵活，适合需要频繁切换的人。

7.3 结合项目工作流

Claude Code 最大的价值是能读项目、改代码。你可以把它用在几个典型场景：

代码审查时，让它读一遍改动，指出潜在问题。写新功能时，让它根据现有代码风格生成骨架。排查 bug 时，把报错信息贴给它，让它分析可能原因。写文档时，让它根据代码生成注释和说明。

这些场景的共同点是：需要模型理解你的项目上下文，而不是泛泛地回答问题。这也是为什么要在终端里用，而不是开个网页聊天窗口。

7.4 关于成本和用量

DeepSeek 的计费是按 token 算的，输入和输出分别计价。Claude Code 每次交互都会发送上下文，项目大的话输入 token 消耗快。建议定期去平台看用量，设置预算提醒，避免月底账单超预期。

如果只是偶尔用，成本很低。如果是重度使用，可以考虑充值套餐或者关注平台的优惠活动。具体价格以官方为准，这里不展开。

8. 一些个人体会

这套方案我从去年开始用，中间换过几次配置，也踩了不少坑。最大的感受是：工具链的自主可控比想象中重要。当你把客户端和模型解耦之后，模型可以换、端点可以换、成本可以控，不再被单一服务商绑定。

另一个体会是，环境配置这件事，一次搞明白胜过十次复制粘贴。很多人装软件就是搜个教程照着敲，出错了再搜，来回折腾。其实花点时间理解每一步在干什么，后面遇到变体就能自己推理。比如你搞懂了 PATH 的作用，command not found这类问题就再也不会卡住你。

最后说个实际的：DeepSeek 在代码任务上的表现，日常够用，但复杂推理和长上下文场景跟顶级模型还有差距。把它当成一个高性价比的日常助手，而不是万能神器，预期就对了。真遇到硬骨头，该用强模型还是得用，工具是拿来解决问题的，不是拿来省钱的。

配置过程中如果遇到本文没覆盖的问题，建议先看 Claude Code 和 DeepSeek 的官方文档，那里的信息最准。社区教程时效性参差不齐，以官方为准。