<!-- title: 第三方模型跑通Claude Code -->

## 概述

本教程面向**第一次接触 Claude Code、但不想被绑死在 Anthropic 官方计费上**的开发者。你将学到：如何用原生安装器装好 Claude Code、用 `ANTHROPIC_BASE_URL` 把请求流量"换底座"指向第三方模型端点、绕开"协议不兼容"这个最大的坑，并最终让 GLM/DeepSeek 等第三方模型驱动 Claude Code 完成你的**第一个真实可运行项目**——一个命令行中文锦囊工具 `fortune-zh`。全程零基础友好，每一步都给到可直接复制的命令与排查手段。预计阅读 12 分钟、动手 40 分钟即可跑通。

---

## 前置条件

| 项 | 要求 | 说明 |
|---|---|---|
| 操作系统 | macOS / Linux / Windows(WSL2) | 三平台均可，本教程命令以 macOS/Linux 为例 |
| 终端 | 任一 POSIX Shell | `bash`/`zsh` 均可 |
| 网络 | 能访问第三方模型供应商的 API 域名 | 国内网络访问 GLM/DeepSeek 直连即可 |
| 账号密钥 | 一个第三方模型 API Key | 如智谱 GLM、DeepSeek、Kimi、OpenRouter 任选其一 |
| Node.js（可选） | 18 及以上 | 仅在选择 npm 安装方式或跑示例项目时需要 |

> 不需要 Claude Pro/Max 订阅，也不需要 Anthropic 官方 API Key。这正是"换底座"的最大价值——Claude Code 的协议层是开放的，驱动它的模型**可替换**。

---

## 一、为什么 Claude Code 能"换底座"：先懂原理

很多人把 Claude Code 当成一个"只能用 Claude 模型"的封闭产品。这其实是个误解。Claude Code 本质是一个 **Anthropic Messages API 协议的客户端**：它把你的指令、文件、工具调用打包成 `/v1/messages` 格式的请求，发往某个后端地址，再把流式返回渲染成交互界面。

关键在于——**这个"后端地址"是由环境变量决定的**，而不是写死在程序里。官方文档对此的描述非常精准：

> `ANTHROPIC_BASE_URL` 改变的是**请求发送到哪里**，而不是哪个模型来回答。要路由到不同模型，需要走 **LLM 网关**。

也就是说，设对了 `ANTHROPIC_BASE_URL`，Claude Code 就会把所有流量打到你指定的端点。设错了，你能调一晚上。

理解下面这张"请求路径"心智图，后面所有配置都不会迷路：

```mermaid
flowchart LR
    U([你敲下指令]) --> CC[Claude Code 客户端]
    CC -- "读取环境变量<br/>BASE_URL / AUTH_TOKEN / MODEL" --> DEC{后端协议?}

    DEC -- "原生 Anthropic 格式<br/>/v1/messages" --> NAT[Anthropic 兼容网关<br/>或自建代理]
    DEC -- "OpenAI 格式<br/>/v1/chat/completions" --> CCR[claude-code-router<br/>协议翻译层]

    NAT --> M1[(GLM / Claude<br/>兼容端点)]
    CCR --> M2[(DeepSeek / Kimi<br/>OpenAI 格式端点)]

    M1 -- SSE 流式返回 --> CC
    M2 -- SSE 流式返回 --> CC
    CC --> R([渲染输出])
```

这张图揭示了一个核心判断：**你选的第三方供应商是"Anthropic 协议"还是"OpenAI 协议"，决定了你要不要多加一个翻译层**。这是本教程踩坑密度最高的一环，先记住它。

控制"换底座"的核心环境变量只有五个，记住这张表你就掌握了 80%：

| 环境变量 | 作用 | 取值示例 |
|---|---|---|
| `ANTHROPIC_BASE_URL` | 请求发往的**后端基址**（不带 `/v1`） | `http://localhost:3456` |
| `ANTHROPIC_AUTH_TOKEN` | 网关/代理常用的**Bearer 鉴权**（推荐） | `sk-xxxxxxxx` |
| `ANTHROPIC_API_KEY` | 官方 **x-api-key** 头鉴权 | `sk-ant-xxxx` |
| `ANTHROPIC_MODEL` | 主模型名（填到请求体 `model` 字段） | `glm-4.6` |
| `ANTHROPIC_SMALL_FAST_MODEL` | 背景小任务模型（标题、补全等） | `glm-4.5-air` |

> 鉴权小贴士：第三方网关几乎都用 `ANTHROPIC_AUTH_TOKEN`（走 `Authorization: Bearer`）。`ANTHROPIC_API_KEY` 是 Anthropic 原生的 `x-api-key` 头，少数网关也兼容。**两者不要同时设**，否则容易互相覆盖。

---

## 二、第一步：安装 Claude Code

推荐**原生安装器**（不依赖 Node 版本，自动管理升级）。打开终端，执行：

**macOS / Linux：**

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

**Windows（PowerShell）：**

```powershell
irm https://claude.ai/install.ps1 | iex
```

如果你机器上已经有 Node.js 18+，也可以走 npm（适合需要全局锁版本的同学）：

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

装完验证：

```bash
claude --version
```

**预期结果：** 打印一串版本号（如 `2.x.x`），说明 CLI 已进入 PATH。

**常见问题：**
- *`command not found: claude`*：原生安装器通常装到 `~/.local/bin` 或 `~/.claude/local`，把它加入 PATH：

  ```bash
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
  ```
- *npm 报权限错误（EACCES）*：改用原生安装器，或 `npm` 配合 `--prefix` 装到用户目录，避免 `sudo`。

---

## 三、第二步：理解两种配置方式

`ANTHROPIC_BASE_URL` 有两种生效方式，各有取舍（这是 buzzai 完整指南反复强调的点）：

**方式 A：Shell 临时/持久导出**——适合"先试一把"或多供应商切换。

```bash
export ANTHROPIC_BASE_URL="http://localhost:3456"
export ANTHROPIC_AUTH_TOKEN="sk-your-gateway-key"
export ANTHROPIC_MODEL="glm-4.6"
export ANTHROPIC_SMALL_FAST_MODEL="glm-4.5-air"
claude
```

想持久化就把前四行写进 `~/.zshrc` 或 `~/.bashrc`。想一次性验证可以用内联：

```bash
ANTHROPIC_BASE_URL=http://localhost:3456 claude
```

**方式 B：`settings.json` 的 `env` 字段**——适合"固定下来，团队共享"。

Claude Code 启动时会读取 `~/.claude/settings.json` 里的 `env` 字段并注入运行时。编辑它：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:3456",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-gateway-key",
    "ANTHROPIC_MODEL": "glm-4.6",
    "ANTHROPIC_SMALL_FAST_MODEL": "glm-4.5-air"
  }
}
```

**取舍：** 方式 A 灵活、可隔离不同项目（项目级 `.claude/settings.json` 更精细）；方式 B 一劳永逸、适合做成团队统一基线。**两者会叠加，命令行变量优先级更高**，调试时若改了 JSON 没生效，多半是 Shell 里残留了旧导出。

---

## 四、第三步：选定你的"底座"路径

这是决定成败的分岔口。先搞清你手上供应商说哪种协议：

| 供应商 | 原生协议 | 走 Claude Code 的方式 |
|---|---|---|
| 智谱 GLM（open.bigmodel.cn） | OpenAI 格式 | **需路由器**（CCR）或兼容网关 |
| DeepSeek（api.deepseek.com） | OpenAI 格式 | **需路由器** |
| Kimi / 通义 / OpenAI 系 | OpenAI 格式 | **需路由器** |
| OpenRouter（`/v1/messages` 端点） | Anthropic 格式 | **直连**，无需路由器 |
| 自建 LiteLLM / Cloudflare AI Gateway | 可配成 Anthropic 格式 | **直连** |
| Anthropic 官方 | Anthropic 格式 | 默认，无需配置 |

**判断准则一句话**：供应商文档里给的调用示例如果带 `/v1/messages`，多半能直连；如果是 `/v1/chat/completions`，就一定要加翻译层。

---

## 五、第四步：配置第三方端点（两条路径实操）

### 路径 A：供应商提供 Anthropic 兼容端点（最省事）

以某 Anthropic 兼容网关 `https://gateway.example.com` 为例（OpenRouter 的 Anthropic 端点、自建 LiteLLM 都属此类）：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-gateway-key",
    "ANTHROPIC_MODEL": "glm-4.6",
    "ANTHROPIC_SMALL_FAST_MODEL": "glm-4.5-air"
  }
}
```

> 注意：Anthropic 协议的 Base URL **通常不带 `/v1` 后缀**，Claude Code 会自己拼 `/v1/messages`；而 OpenAI 协议通常带 `/v1`。以你所用端点的文档为准。

### 路径 B：OpenAI 格式供应商 + claude-code-router（最通用）

GLM、DeepSeek 等都是 OpenAI 格式，必须加一个翻译层。社区最成熟的是 **claude-code-router（CCR）**：它在本地起一个小服务（如 `:3456`），把 Claude Code 发来的 Anthropic 请求翻译成目标供应商的 OpenAI 格式，再把响应翻回来。

安装 CCR：

```bash
npm install -g @musistudio/claude-code-router
```

编辑 CCR 配置 `~/.claude-code-router/config.json`（以接 GLM 为例）：

```json
{
  "Providers": [
    {
      "name": "glm",
      "api_base_url": "https://open.bigmodel.cn/api/paas/v4/chat/completions",
      "api_key": "你的GLM-API-KEY",
      "models": ["glm-4.6", "glm-4.5-air", "glm-4.6-air"]
    }
  ],
  "Router": {
    "default": "glm,glm-4.6",
    "background": "glm,glm-4.5-air",
    "think": "glm,glm-4.6",
    "longContext": "glm,glm-4.6"
  }
}
```

`Router` 字段把 Claude Code 内部的"默认/后台/思考/长上下文"四种场景，分别映射到具体模型，这是 CCR 的灵魂。

启动 CCR，并让 Claude Code 指向它：

```bash
ccr start                                  # 本地监听 :3456
export ANTHROPIC_BASE_URL="http://localhost:3456"
export ANTHROPIC_AUTH_TOKEN="any-non-empty-string"   # CCR 不校验，但不能为空
claude
```

**预期结果：** Claude Code 启动后**不再弹出 Anthropic OAuth 登录**（因为 `ANTHROPIC_AUTH_TOKEN` 已就位），直接进入交互界面，背后已是 GLM 在回答。

---

## 六、第五步：验证连通（5 秒自检清单）

进入 Claude Code 交互界面后，按顺序做三件事：

1. **看状态**：输入 `/status`，确认 `API endpoint` 指向你的自定义地址、`Model` 是你设的名字。
2. **看模型**：输入 `/model`，确认当前模型与 `ANTHROPIC_MODEL` 一致。
3. **发个炮仗**：输入一句简单中文，如"用一句话解释什么是环境变量"。若几秒内流式返回正常中文，**整条链路即通**。

若卡住，对照这张"5 大常见错误"排查（buzzai 指南同款）：

| 现象 | 根因 | 处方 |
|---|---|---|
| 一直转圈、最后超时 | `BASE_URL` 写错或拼了 `/v1` | 去掉多余 `/v1`，核对域名可达 |
| 401 / 鉴权失败 | Token 变量名/头不匹配 | 网关用 `AUTH_TOKEN`；确认未同时设 `API_KEY` |
| 工具调用全乱、不读文件 | 供应商**不支持 Anthropic 工具协议** | 必须加 CCR 翻译层，别直连 OpenAI 端点 |
| 报"模型不存在" | `ANTHROPIC_MODEL` 名字写错 | 用 `/model` 或供应商文档核准模型 ID |
| 主对话正常、标题生成报错 | `ANTHROPIC_SMALL_FAST_MODEL` 未设或非法 | 设成一个真实存在的便宜小模型 |

---

## 七、第六步：第一个项目——`fortune-zh` 中文锦囊 CLI

链路通了，现在用一个**真实可运行的小项目**验证第三方模型的编码能力。目标：让 GLM 驱动的 Claude Code 从零生成一个单文件 Node.js 工具 `fortune-zh`，运行后随机打印一条带边框的中式格言。

在 Claude Code 里直接输入（一句话即可，让它自己规划）：

```
在当前目录新建一个 Node.js 单文件项目 fortune-zh：
1. 创建 fortune-zh/index.js，内嵌一个 8 条以上的中文格言数组（带作者）。
2. 每次运行 node index.js 随机输出一条，用 ASCII 边框包裹，自动对齐中英文宽度。
3. 支持 node index.js --all 列出全部。
4. 不要任何外部依赖。完成后自己 node index.js 跑一遍给我看。
```

**预期结果：** Claude Code 会自己 `mkdir`、写 `index.js`、运行验证。你随后执行：

```bash
node fortune-zh/index.js
```

将看到类似输出：

```
┌──────────────────────────────────────┐
│  千里之行，始于足下。                    │
│                          —— 《老子》   │
└──────────────────────────────────────┘
```

这一步成功，意味着**第三方模型不仅能聊天，还能在你的项目里读写文件、执行命令、自我验证**——Claude Code 的 Agent 能力已完整跑通。这就是"第一个项目"的真正含义：不是你写代码，而是你用自然语言指挥模型完成从创建到验证的闭环。

---

## 八、实战小结：可复用的四步心法

1. **先判协议**：Anthropic 直连，OpenAI 加 CCR。
2. **最小配置**：`BASE_URL` + `AUTH_TOKEN` + `MODEL` 三件套先跑通，再补 `SMALL_FAST_MODEL`。
3. **`/status` 当探针**：改完配置先 `/status` 再 `/model`，别急着提问。
4. **Shell 优先级最高**：JSON 没生效，先查 Shell 残留导出。

---

## 延伸阅读

- **Claude Code 官方·模型配置**：`code.claude.com/docs/zh-CN/model-config`——`ANTHROPIC_BASE_URL` 与 LLM 网关的权威定义。
- **claude-code-router（CCR）仓库**：`github.com/musistudio/claude-code-router`——`Providers`/`Router` 完整字段与 transformer 插件机制。
- **LiteLLM 作为 Anthropic 网关**：`docs.litellm.ai`——自建统一网关、统一计费与限流的工业级方案。
- **多供应商一键切换**：搜索"CC Switch Claude Code"——图形化切换不同 BASE_URL 的辅助工具。

---

## 训练营适用性评估

| 维度 | 评估 |
|---|---|
| 适合训练营类型 | **AI 编程入门营 / 成本敏感型团队内训 / 国产生态开发者日** |
| 学员基础 | 零编程经验可跟上安装与配置部分；示例项目建议有 Node.js 基础 |
| 预计教学时长 | **45 分钟讲解 + 30 分钟动手**（含 CCR 接入与排障） |
| 难点 | 协议判别（Anthropic vs OpenAI）、`SMALL_FAST_MODEL` 缺失引发的隐性报错 |
| 可量化验收 | 学员能在自己机器 `/status` 显示自定义端点，并跑通 `node fortune-zh/index.js` |
| 衍生课题 | 第二轮可接"用 CCR 做按场景路由的多模型策略"，第三轮可接"把这套配置固化成团队 Plugin" |

---

## 参考来源

1. [模型配置 - Claude Code 官方文档](https://code.claude.com/docs/zh-CN/model-config) — Anthropic 官方对 `ANTHROPIC_BASE_URL` 与 LLM 网关的权威定义，"改变请求发送位置而非回答模型"的原文出处。
2. [ANTHROPIC_BASE_URL 完整指南：Claude Code 切换自定义端点（BUZZ AI Gateway）](https://buzzai.cc/blog/zh/anthropic-base-url-claude-code-guide) — 两种配置方式取舍、全平台步骤与 5 大常见错误的系统梳理（2026-05）。
3. [Claude Code 第三方 API 设置：2026 年分步指南（AtlasCloud）](https://www.atlascloud.ai/zh/blog/guides/claude-code-third-party-api-setup) — 标准 API 重度用户日均 $13 成本背景下的 GLM/Kimi/DeepSeek 替换实践。
4. [Claude Code 国内环境实战：安装、第三方 Provider 配置与多模型切换（ClaudeCN）](https://claudecn.com/blog/claude-code-install-and-provider-switching/) — 从 Node 安装到 CLI 安装、兼容接口配置与 VS Code 联动的全流程教程。
5. [claude-code-router（GitHub · musistudio）](https://github.com/musistudio/claude-code-router) — Anthropic↔OpenAI 协议翻译层的开源实现，`Providers`/`Router` 配置与 transformer 插件机制。

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)