# Ubuntu 20.04 手动配置 Claude Code 接入 MiniMax M2.5 完整指南

> **前置知识**：本文详细介绍如何在 Ubuntu 20.04 系统上手动安装 Claude Code，并通过环境变量配置接入 MiniMax M2.5 模型，实现 AI 编程助手的本地使用。同时深入解析背后的原理，帮助读者彻底理解配置过程。

---

## 📑 目录

- [一、前言](#一前言)
- [二、安装 Claude Code](#二安装-claude-code)
  - [1. 安装 Node.js 18+](#1-安装-nodejs-18)
  - [2. 使用 npm 全局安装 Claude Code](#2-使用-npm-全局安装-claude-code)
  - [3. 验证安装](#3-验证安装)
  - [4. 常见问题及解决](#4-常见问题及解决)
- [三、配置 MiniMax M2.5 接入](#三配置-minimax-m25-接入)
  - [1. 清理旧配置](#1-清理旧配置)
  - [2. 在 .bashrc 中设置环境变量](#2-在-bashrc-中设置环境变量)
  - [3. 使环境变量生效](#3-使环境变量生效)
  - [4. 清除认证缓存](#4-清除认证缓存)
  - [5. 启动并验证](#5-启动并验证)
- [四、核心原理详解](#四核心原理详解)
  - [1. 环境变量 vs 配置文件](#1-环境变量-vs-配置文件)
  - [2. ~/.bashrc 的作用](#2-bashrc-的作用)
  - [3. 命令查找机制与 PATH](#3-命令查找机制与-path)
  - [4. 切换模型的通用公式](#4-切换模型的通用公式)
  - [5. 常见错误原因](#5-常见错误原因)
- [五、总结](#五总结)

---

## 一、前言

Claude Code 是 Anthropic 推出的 AI 编程助手，支持通过 API 调用不同的模型。MiniMax 提供了与 Anthropic 兼容的 API 接口，因此我们可以将 Claude Code 配置为使用 **MiniMax M2.5 模型**，享受国内服务的低延迟和便利。

本文将带你一步步完成从零开始的安装与配置，并深入解释背后的原理，让你不仅知其然，更知其所以然。

> **💡 提示**：如果你是第一次配置，建议按照目录顺序依次执行，不要跳过任何步骤。

---

## 二、安装 Claude Code

### 1. 安装 Node.js 18+

Claude Code 基于 Node.js 运行，要求 **Node.js 18.0 或更高版本**。如果你的系统未安装或版本过低，请先升级。

**检查当前 Node.js 版本：**

```bash
node --version
```

如果输出低于 v18.0.0，则需安装最新 LTS 版本。

**安装 Node.js 18+：**

```bash
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
```

**验证安装：**

```bash
node --version   # 应显示 v18.x 或更高
npm --version
```

---

### 2. 使用 npm 全局安装 Claude Code

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

> ⚠️ **注意**：**不要使用 sudo 执行此命令**，以免引发权限问题。如果遇到权限错误（EACCES），请按照下面「常见问题」中的方法配置用户级 npm 目录。

---

### 3. 验证安装

```bash
claude --version
```

若显示版本号（例如 2.1.7），则安装成功。

---

### 4. 常见问题及解决

#### 问题 1：claude: command not found

| 原因 | 解决 |
|------|------|
| npm 全局安装目录未在 PATH 中 | 找到 npm 全局 bin 目录，并添加到 PATH |

```bash
npm config get prefix   # 输出全局安装前缀，例如 /home/用户名/.npm-global
echo 'export PATH=该目录/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

---

#### 问题 2：安装过程中卡住或速度慢

| 原因 | 解决 |
|------|------|
| 网络问题，可尝试使用国内镜像 | 临时使用淘宝镜像安装 |

```bash
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com
```

---

#### 问题 3：Node.js 版本过低

| 原因 | 解决 |
|------|------|
| 系统自带 Node.js 可能较旧 | 按上述步骤安装官方源的最新 LTS 版本 |

---

## 三、配置 MiniMax M2.5 接入

### 1. 清理旧配置

为避免旧配置文件干扰，先删除可能存在的 Claude Code 配置文件：

```bash
rm -f ~/.claude/settings.json ~/.claude.json
```

---

### 2. 在 .bashrc 中设置环境变量

编辑 `~/.bashrc` 文件：

```bash
nano ~/.bashrc
```

在文件末尾添加以下内容（**请将 `你的真实MiniMax_API_Key` 替换为你的 MiniMax API Key**）：

```bash
# MiniMax + Claude Code 配置
export ANTHROPIC_BASE_URL="https://api.minimaxi.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="你的真实MiniMax_API_Key"
export API_TIMEOUT_MS="3000000"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# 将所有模型指向 MiniMax-M2.5
export ANTHROPIC_MODEL="MiniMax-M2.5"
export ANTHROPIC_SMALL_FAST_MODEL="MiniMax-M2.5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="MiniMax-M2.5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="MiniMax-M2.5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="MiniMax-M2.5"
```

> 📝 **保存并退出**：Ctrl+O，回车，Ctrl+X

---

### 3. 使环境变量生效

执行以下命令重新加载 `.bashrc`，或直接关闭当前终端并打开新终端：

```bash
source ~/.bashrc
```

**验证环境变量是否设置成功：**

```bash
echo $ANTHROPIC_BASE_URL   # 应输出 https://api.minimaxi.com/anthropic
echo $ANTHROPIC_AUTH_TOKEN # 应显示你的 API Key（为安全起见可只显示前几位）
```

---

### 4. 清除认证缓存

如果之前曾登录过 Anthropic 账号，Claude Code 可能缓存了会话，建议清除：

```bash
rm -rf ~/.config/claude ~/.local/share/claude
```

---

### 5. 启动并验证

进入你的工作目录（例如 `cd ~/myproject`），运行：

```bash
claude
```

若配置正确，将直接进入对话界面，不再要求登录 Anthropic。你可以尝试提问，例如「你好，请介绍一下自己」，观察回复是否正常。

> ✅ **验证成功标志**：不再弹出登录界面，直接进入对话模式

---

## 四、核心原理详解

### 1. 环境变量 vs 配置文件

| 方式 | 说明 |
|------|------|
| **环境变量** | 操作系统中的键值对，任何程序都可读取。它们只在当前 Shell 会话中有效，但可通过写入 Shell 启动文件实现永久化 |
| **配置文件** | 程序自己保存的持久化设置文件（如 `~/.claude/settings.json`） |

> **优先级**：`Claude Code` 启动时遵循 **环境变量 > 配置文件 > 程序默认值** 的顺序。这意味着，只要环境变量设置正确，配置文件即使存在也不会覆盖环境变量。

---

### 2. ~/.bashrc 的作用

- `~/.bashrc` 是 **Bash 的启动脚本**，每次打开新的终端窗口时自动执行其中的命令
- 将 `export` 命令写入 `~/.bashrc`，可以确保每次新终端启动时自动设置环境变量，从而实现「永久生效」

---

### 3. 命令查找机制与 PATH

当你在终端输入命令（如 `claude`），Shell 会：

1. 先检查是否为**内置命令**（如 `cd`、`echo`）
2. 若不是，则在 **PATH 环境变量** 列出的目录中依次查找同名可执行文件
3. 若所有目录都找不到，则报错 `command not found`

> 💡 **小知识**：PATH 本身也是一个环境变量，可以在 `~/.bashrc` 中修改，例如添加 Homebrew 或 npm 的 bin 目录。

---

### 4. 切换模型的通用公式

任何与 Anthropic API 兼容的服务，只需修改**三个关键环境变量**即可切换：

```bash
export ANTHROPIC_BASE_URL="新服务地址"
export ANTHROPIC_AUTH_TOKEN="新服务密钥"
export ANTHROPIC_MODEL="新模型名称"
```

> 📌 **温馨提示**：其他模型别名（如 `ANTHROPIC_SMALL_FAST_MODEL`）建议同步修改，避免回退到默认值。

---

### 5. 常见错误原因

| 错误类型 | 说明 |
|----------|------|
| **变量名错误** | Claude Code 使用 `ANTHROPIC_AUTH_TOKEN`，而非 `ANTHROPIC_API_KEY` |
| **Base URL 格式错误** | 不应加 `/v1`，程序会自动拼接，多写会导致 404 |
| **旧配置文件干扰** | 若 `~/.claude/settings.json` 中存在旧配置，可能覆盖环境变量 |

---

## 五、总结

通过本文的步骤，你成功在 **Ubuntu 20.04** 上安装了 **Claude Code**，并配置其使用 **MiniMax M2.5 模型**。整个过程不依赖任何第三方配置工具（如 cc-switch），仅通过环境变量实现，干净且易于维护。

理解背后的原理后，你可以轻松切换任何兼容 Anthropic API 的服务，只需修改 `.bashrc` 中的**三行变量**即可。

---

> 🎉 **以上就是全部内容！** 如果对你有帮助，欢迎**点赞**、**收藏**、**关注**，如有任何问题，欢迎在评论区留言交流。

---

**📌 本文声明**
- 欢迎大家关注我的博客，获取更多技术干货

---