1. 项目概述：为什么要在Ubuntu上折腾Claude Code和DeepSeek？

最近在开发者圈子里，Claude Code和DeepSeek的组合讨论度挺高的。简单来说，Claude Code是Anthropic推出的一个命令行AI编程助手，而DeepSeek则提供了强大的开源模型API。把这两者结合起来，你就能在本地终端里，用一个相对低成本且高性能的模型来辅助写代码、调试、重构，甚至进行联网搜索。听起来是不是比在网页上反复切换标签页要高效得多？

我最初也是被这个想法吸引的。作为一个常年泡在Ubuntu终端里的开发者，我受够了在IDE、浏览器和文档之间来回跳转的割裂感。Claude Code承诺能直接在项目根目录下运行，理解整个代码库的上下文，这简直是“终端原教旨主义者”的福音。而DeepSeek-v4系列模型在代码生成和理解上的表现，经过我实测，确实非常能打，性价比突出。所以，今天这篇内容，我就来手把手带你走一遍在Ubuntu系统上，从零开始安装Claude Code，并将其后端配置为使用DeepSeek API的完整流程。这不仅仅是把几个命令敲进去，我会把每一步背后的原理、可能遇到的坑，以及我调试了半天的经验都分享出来，让你一次成功，少走弯路。

2. 核心需求解析与方案选型

2.1 我们到底需要什么？

在开始动手之前，我们先明确一下核心目标。我们不是简单地在Ubuntu上装个软件，而是要搭建一个 本地可用的、高性价比的AI编程工作流 。拆解开来，主要有三个需求：

  1. 一个本地的、上下文感知的编程助手 ：它需要能读取我当前项目的文件，理解项目结构，并基于此给出准确的代码建议或回答技术问题。Claude Code正是为此而生，它通过分析你运行命令时所在的目录来获取上下文。
  2. 一个强大且经济的AI模型后端 ：Claude Code本身只是一个客户端，它需要调用AI模型API。直接使用官方的Claude API价格不菲。而DeepSeek API提供了对Anthropic API格式的兼容，并且其 deepseek-v4-pro 和 deepseek-v4-flash 模型在代码任务上表现优异，价格更具优势，这成为了我们的理想后端。
  3. 一个无缝的终端集成体验 ：整个工具链需要稳定地运行在Ubuntu终端环境中，安装和配置过程不能过于复杂，最好能通过脚本或环境变量一次性搞定，避免每次使用都要进行繁琐的初始化。

2.2 为什么是Claude Code + DeepSeek API？

市面上类似的工具不少，比如GitHub Copilot CLI、Cursor等。选择这个组合，我主要基于以下几点考量：

  • 成本可控 ：DeepSeek API的定价策略对于个人开发者和小团队非常友好。你可以按需使用，没有强制性的高额月费。这对于需要频繁调用AI辅助，但又对成本敏感的场景来说是关键。
  • 性能与功能平衡 ： deepseek-v4-pro 对标的是Claude 3.5 Sonnet甚至Opus级别的复杂代码推理能力，适合深度设计、重构和调试。而 deepseek-v4-flash 则速度极快，适合日常的代码补全、解释和简单查询。Claude Code允许我们通过环境变量灵活指定不同场景下使用的模型。
  • 对开源和本地化的友好性 ：虽然最终调用的是云端API，但整个配置过程是透明、可掌控的。你不依赖于某个闭源IDE的特定插件，配置信息掌握在自己手里。未来如果DeepSeek推出本地化部署方案，迁移路径也会更清晰。
  • 终端原生，心无旁骛 ：对于习惯使用Vim、Emacs或纯终端编辑的开发者，或者那些在服务器上进行开发调试的情况，一个终端内的助手能最大程度减少上下文切换，提升专注度。

基于这些分析，我们的技术方案就明确了：在Ubuntu上安装Node.js环境 → 通过npm全局安装Claude Code → 配置环境变量指向DeepSeek API → 验证并使用。

3. 详细安装与配置实操指南

3.1 基础环境准备：Node.js的安装与版本管理

Claude Code是一个Node.js包，所以第一步是确保你的Ubuntu系统有合适的Node.js环境。这里我强烈推荐使用 nvm （Node Version Manager）来管理Node.js，而不是直接安装系统包。原因很简单：不同项目对Node版本可能有要求， nvm 可以让你轻松切换版本，并且安装过程避免了权限问题。

步骤1：安装nvm 打开你的终端，执行以下命令下载并安装nvm。这个命令会从GitHub获取最新的安装脚本。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

安装完成后，你需要重新加载你的shell配置文件（比如 .bashrc 或 .zshrc ），或者直接新开一个终端窗口。

步骤2：安装指定版本的Node.js Claude Code要求Node.js版本在18及以上。我们安装一个长期支持版，比如18.x的最新版，这样兼容性和稳定性都有保障。

# 首先，重新加载shell配置以使nvm生效
source ~/.bashrc  # 如果你用的是bash
# 或者 source ~/.zshrc   # 如果你用的是zsh

# 安装Node.js 18
nvm install 18

# 将刚安装的18版本设置为默认版本
nvm alias default 18

# 验证安装
node --version
npm --version

你应该能看到类似 v18.20.2 和 10.5.2 的输出。这就对了。

注意 ：如果你在公司内网或者网络环境特殊， curl 下载 nvm 安装脚本可能会失败。这时你可以尝试直接浏览器下载安装脚本，或者使用代理。但请记住，我们这里讨论的是合法的开发工具安装，所有操作均在常规网络环境下进行。

3.2 安装Claude Code

有了Node.js环境，安装Claude Code就非常简单了，一行npm命令搞定。

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

这里的 -g 参数代表全局安装，这样你才能在终端的任何位置直接运行 claude 命令。

安装完成后，立刻验证一下是否成功：

claude --version

如果安装成功，终端会打印出Claude Code的版本号，例如 claude-code/1.1.0 。如果提示“命令未找到”，通常是因为全局npm包的安装路径没有加入到系统的 PATH 环境变量中。你可以通过 npm config get prefix 查看全局安装路径，然后手动将其下的 bin 目录添加到 PATH 中。

3.3 获取并配置DeepSeek API密钥

这是最关键的一步，我们需要让Claude Code知道去调用谁家的服务。

步骤1：获取DeepSeek API Key

  1. 访问DeepSeek平台官网（这里假设你通过常规搜索引擎可以找到其官方网站）。
  2. 注册并登录你的账户。
  3. 在控制台界面，你应该能找到“API Keys”或类似的管理页面。
  4. 创建一个新的API密钥，并妥善保存。这个密钥就像你的密码，一旦生成，页面上只会显示一次。

步骤2：配置环境变量 Claude Code通过一系列环境变量来配置其行为。我们需要设置API端点、密钥和默认模型。根据DeepSeek官方文档的说明，配置如下：

打开你的shell配置文件，通常是 ~/.bashrc （Bash用户）或 ~/.zshrc （Zsh用户）。使用你喜欢的文本编辑器，比如 nano 或 vim 。

nano ~/.bashrc

在文件的末尾，添加以下内容。请务必将 <your DeepSeek API Key> 替换为你刚才复制的真实密钥。

# DeepSeek API Configuration for Claude Code
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=sk-your-actual-api-key-here
export ANTHROPIC_MODEL=deepseek-v4-pro
export ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-v4-pro
export ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-v4-pro
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flash
export CLAUDE_CODE_SUBAGENT_MODEL=deepseek-v4-flash
export CLAUDE_CODE_EFFORT_LEVEL=max

逐行解释一下这些变量：

  • ANTHROPIC_BASE_URL : 告诉Claude Code，Anthropic格式的API请求应该发送到DeepSeek的兼容端点。
  • ANTHROPIC_AUTH_TOKEN : 你的DeepSeek API密钥，用于身份验证。
  • ANTHROPIC_MODEL : 默认使用的模型。
  • ANTHROPIC_DEFAULT_OPUS/SONNET/HAIKU_MODEL : 这些是为了兼容Claude原有的模型命名体系。当Claude Code内部试图调用 claude-3-5-sonnet 等模型时，会被映射到我们指定的DeepSeek模型。这里我们把“大模型”请求都指向 deepseek-v4-pro ，把“小模型”请求指向 deepseek-v4-flash 。
  • CLAUDE_CODE_SUBAGENT_MODEL : Claude Code内部有时会启用“子代理”来处理特定任务，我们指定它用更快的Flash模型。
  • CLAUDE_CODE_EFFORT_LEVEL : 设置为 max ，让Claude Code在解决问题时投入最大努力，思考更深入。

保存并关闭编辑器（在nano中是 Ctrl+X ，然后按 Y 确认，再按回车）。然后让配置生效：

source ~/.bashrc

现在，你可以通过 echo $ANTHROPIC_AUTH_TOKEN （不显示具体内容）或 echo $ANTHROPIC_BASE_URL 来检查环境变量是否设置成功。

3.4 首次运行与验证

所有配置完成后，让我们进行一次实战测试。

  1. 进入一个项目目录 ：找一个你正在开发的项目，或者新建一个测试目录。 
    mkdir ~/test-claude-code && cd ~/test-claude-code
echo "// test.js" > test.js
  2. 启动Claude Code ：直接在终端输入 claude 。 
    claude
  3. 进行交互 ：启动后，你会看到 Claude> 提示符。你可以开始问问题了。例如，输入： 
    请帮我分析一下当前目录下有什么文件，并为一个简单的Node.js HTTP服务器生成代码。
    如果配置一切正常，Claude Code会先列出当前目录下的 test.js 文件，然后生成一段创建HTTP服务器的代码。你可能会注意到它的“思考”过程，最后给出答案。

成功的标志 ：你能正常收到来自AI的、连贯的、符合上下文的回答，并且回答的质量感觉不错。如果出现错误，请继续看下一章的故障排查部分。

4. 核心功能使用详解与高级配置

4.1 Claude Code的基本工作模式

Claude Code启动后，有两种主要的交互模式：

  • 聊天模式 ：在 Claude> 提示符下直接输入问题。它能够读取当前目录（你启动 claude 命令时所在的目录）下的文件作为上下文。你可以让它解释代码、生成新代码、重构、写测试、调试等。
  • 管道模式 ：你可以通过管道将内容传递给Claude Code。例如： 
    cat buggy_script.py | claude --fix
    这个命令会将 buggy_script.py 的内容发送给Claude，并指示它尝试修复其中的错误。 --fix 是一个很有用的预设指令。

4.2 模型选择与成本优化策略

我们在环境变量里设置了默认模型映射。但你知道如何根据任务手动选择模型以优化成本和速度吗？

虽然Claude Code的界面不直接提供切换模型的按钮，但我们可以通过 临时环境变量 来为单次会话指定模型。比如，当你需要一个快速答案，不需要深度推理时：

ANTHROPIC_MODEL=deepseek-v4-flash claude

这样启动的Claude Code会话就会使用速度更快、单价更低的Flash模型。相反，当你需要设计一个复杂系统或进行深度代码审查时，再使用默认的Pro模型。

成本估算小贴士 ：DeepSeek API按Token计费。一个简单的代码补全可能只需几百个Token，而分析一个大型代码库可能会消耗数万Token。建议在DeepSeek平台的控制台里定期查看用量，了解自己的使用模式。对于日常辅助，Flash模型通常足够，且能节省大量成本。

4.3 启用联网搜索功能

DeepSeek API原生支持Claude Code的联网搜索功能。这是一个非常强大的特性。当你的问题涉及最新的技术动态、文档或错误信息时，Claude Code可以自主决定去搜索网络。

这个功能是 自动触发 的。你不需要额外配置。当你在聊天中提出诸如“最新的React 19有什么新特性？”或“帮我找一下‘Connection reset by peer’这个错误的解决方案”这类问题时，Claude Code可能会回复说：“我需要搜索网络来获取最新信息”，然后开始搜索并总结结果。

重要提示 ：联网搜索会产生额外的API调用（因为需要调用另一个LLM来总结搜索结果），因此会产生额外的Token费用。DeepSeek的计费包含了这部分成本。所以，对于能在本地代码库中找到答案的问题，尽量提供足够的上下文，避免不必要的搜索。

4.4 项目上下文与文件操作

Claude Code的强大之处在于它对项目上下文的理解。它不仅能读取当前目录的文件，还能理解文件之间的关系。

  • 指定文件 ：你可以直接在问题中提及文件名。例如：“请查看 src/utils/helper.js 文件，并优化其中的 formatDate 函数。”
  • 代码变更 ：你可以要求Claude Code直接修改文件。 但请注意 ，它不会未经确认直接覆盖你的文件。通常它会给出修改建议或差异对比（diff），你需要审核后再决定是否应用。对于重要文件，手动复制粘贴它的建议更安全。
  • 理解项目结构 ：你可以问：“基于当前的 package.json 和目录结构，这是一个什么类型的项目？” 它能很好地识别出是React、Vue、Node.js后端还是其他类型。

5. 常见问题与故障排查实录

在实际配置和使用过程中，你几乎一定会遇到一些问题。下面是我踩过坑后总结的排查清单。

5.1 安装与启动问题

问题1： npm install -g 命令报权限错误。

  • 现象 ： EACCES: permission denied
  • 原因 ：你正在尝试向系统全局目录（如 /usr/local/lib ）写入，需要 sudo 权限，但用 sudo 安装npm包又会带来新的权限混乱问题。
  • 解决 ： 永远不要用 sudo 安装全局npm包！ 正确的做法是更改npm的全局安装目录所有权，或者使用 nvm （它已经帮我们解决了这个问题）。如果你没用nvm，可以执行： 
    mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
    然后将 ~/.npm-global/bin 添加到你的 PATH 环境变量中（编辑 ~/.bashrc ，添加 export PATH=$PATH:~/.npm-global/bin ）。

问题2：运行 claude 命令提示“未找到命令”（command not found）。

  • 现象 ：安装成功，但 claude 命令无法识别。
  • 原因 ：全局npm包的 bin 目录不在系统的 PATH 中。
  • 解决 ：
    1. 找出npm的全局安装路径： npm config get prefix 。假设输出是 /home/yourname/.nvm/versions/node/v18.20.2 。
    2. 确保 /home/yourname/.nvm/versions/node/v18.20.2/bin 这个目录在你的 PATH 里。如果你使用了 nvm ，它通常会自动帮你管理。检查你的 ~/.bashrc 或 ~/.zshrc ，确保有nvm的初始化脚本（通常安装nvm时会自动添加）。然后执行 source ~/.bashrc 。

问题3：Claude Code启动后立即退出或报错。

  • 现象 ：输入 claude 后，提示符一闪而过，或显示网络错误、认证错误。
  • 排查步骤 ：
    1. 检查环境变量 ： echo $ANTHROPIC_AUTH_TOKEN ，确保密钥正确无误，没有多余的空格或换行。 echo $ANTHROPIC_BASE_URL ，确保URL正确。
    2. 检查网络连接 ：尝试用 curl 测试API端点是否可达（注意，直接curl可能会返回405 Method Not Allowed，这是正常的，说明端点存在但要求POST请求）。更简单的方法是 ping api.deepseek.com 。
    3. 检查API密钥余额与权限 ：登录DeepSeek平台，确认API密钥有效，且有足够的余额或未超出速率限制。
    4. 查看详细日志 ：尝试以调试模式运行： CLAUDE_CODE_LOG_LEVEL=debug claude 。这可能会输出更详细的错误信息，例如具体的HTTP状态码和错误消息。

5.2 API调用与模型相关错误

问题4：错误提示 API error: 400 The supported API model names are deepseek-v4-pro or deepseek...

  • 现象 ：这是最可能遇到的错误之一，说明你请求的模型名称不被DeepSeek API支持。
  • 原因 ：Claude Code内部可能尝试调用了一个DeepSeek不认识的Claude原生模型名，而我们的环境变量映射没有完全覆盖到。
  • 解决 ：仔细核对你在 ~/.bashrc 中设置的所有 ANTHROPIC_DEFAULT_*_MODEL 环境变量。确保它们都被正确设置为 deepseek-v4-pro 或 deepseek-v4-flash 。 特别注意 ，根据DeepSeek文档，模型名就是 deepseek-v4-pro ，不要加任何后缀或版本号（除非官方明确说明）。设置完成后，务必 source ~/.bashrc 并重启终端或Claude Code会话。

问题5：响应速度慢，或经常超时。

  • 现象 ：问题发出后要等待很久才有回复，有时甚至超时。
  • 原因 ：
    • 网络延迟高。
    • 使用了 deepseek-v4-pro 模型处理简单问题，该模型本身推理速度就比Flash模型慢。
    • 问题过于复杂，或上传的上下文（代码文件）太大，导致模型需要很长的处理时间。
  • 解决 ：
    1. 对于简单查询，尝试用 ANTHROPIC_MODEL=deepseek-v4-flash claude 启动会话。
    2. 控制输入上下文的规模。不要一次性让Claude Code分析整个庞大的代码库。可以先让它分析核心的几个文件。
    3. 如果网络是瓶颈，考虑优化本地网络环境。

5.3 使用技巧与优化建议

技巧1：编写清晰的提示词（Prompt） Claude Code虽然能理解代码上下文，但清晰的指令能极大提升效率。比如：

  • 不好的提问 ：“这个函数有问题。”
  • 好的提问 ：“请检查 src/api/user.js 中的 fetchUserProfile 函数。当传入的 userId 为 null 时，它抛出了一个未处理的类型错误。请修复这个边界情况，并添加相应的错误处理逻辑。”

技巧2：利用好“系统提示”能力 虽然Claude Code没有直接的图形界面来设置系统提示，但你可以通过对话来“设定角色”。在会话开始时，你可以说：“从现在开始，你是一个经验丰富的Node.js后端架构师，擅长设计和优化高并发RESTful API。请用中文回答我的问题。” 这能在一定程度上引导它的回答风格和深度。

技巧3：结合版本控制 在让Claude Code进行大规模代码重构前， 务必先提交你当前的代码到Git 。这样，如果AI给出的修改不符合预期，你可以轻松地回退到之前的状态。永远不要在没有备份的情况下让AI直接修改核心业务逻辑文件。

技巧4：分步解决复杂问题 对于复杂任务，不要指望AI一步到位。采用“分步拆解，逐步验证”的策略。例如：

  1. “请为这个数据模型设计一个数据库Schema。”
  2. “基于上面的Schema，生成对应的Sequelize模型定义。”
  3. “现在，为这个模型编写CRUD操作的Service层代码。”
  4. “最后，为这些Service函数编写单元测试。” 每一步都基于上一步的结果，并进行人工审核，确保方向正确。
Logo
MCP技术社区

欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！

更多推荐

Page Agent：用自然语言控制网页界面的 JavaScript 内页 GUI 智能体

Page Agent 是阿里巴巴开源的一款，只需在网页内嵌入一段 JS，即可通过自然语言指令控制网页界面。它将 AI Agent 的能力直接"活在"网页中，极大降低了 Web AI Copilot 的集成门槛。

avatar MCP技术社区
cover

阿里云 AI 产品全览：百炼大模型、通义系列、PAI 与 AI 服务选型指南

avatar MCP技术社区
cover

AI Agent时代，老板最大的对手不是AI，是自己

avatar MCP技术社区