<!-- title: 国产模型驱动Claude首跑 -->

# 用国产模型驱动 Claude Code：零基础跑通首个项目全实战

## 概述

本教程面向**完全零基础**、且身处国内网络环境的开发者：你不需要 Anthropic 官方账号、不需要科学上网、也不需要昂贵的海外 API 余额，就能把 Claude Code 这套强大的终端 AI 编程助手**真正跑起来，并完成第一个可运行项目**。学完你将掌握：环境搭建、Claude Code 安装、用智谱 GLM（Anthropic 兼容端点）直连配置、首次启动验证、以及让 AI 现场生成并运行一个单文件 Web 小工具的全流程。适用人群：从未用过 Claude Code、想低成本体验 AI 编程的初学者、在校生、转岗开发者。

## 前置条件

| 项目 | 要求 | 说明 |
|------|------|------|
| 操作系统 | Windows / macOS / Linux 任一 | 本教程命令以通用 shell 为主，Windows 用 PowerShell、Mac/Linux 用终端 |
| Node.js | ≥ 18（推荐 20 LTS） | Claude Code 运行依赖；版本过低会报错 |
| npm | 随 Node.js 自带 | 用于全局安装 |
| Git | 建议安装 | Claude Code 在项目中会结合 Git 流程工作 |
| 模型 API Key | **智谱 GLM** 一个 Key 即可 | 在 [bigmodel.cn](https://bigmodel.cn) 注册免费领取，新用户有免费额度 |
| 终端基础 | 会 `cd`、`mkdir`、复制粘贴 | 仅此而已 |

> **为什么选 GLM？** 智谱开放平台提供了 **Anthropic 协议兼容端点**，Claude Code 无需任何中间代理就能直连，配置最简单、最稳定，是新手首选。DeepSeek、Qwen 等仅提供 OpenAI 兼容端点，需要额外的路由代理（本文末尾进阶部分讲解）。

---

## 第一步：理解"国产模型直连"的原理

Claude Code 默认把请求发往 `https://api.anthropic.com`，这也是国内用户"卡在第一步"的根源。但它内置了一个"逃生舱"——只要通过环境变量把**基础地址**和**鉴权令牌**改掉，它的请求就会发往你指定的任何 Anthropic 兼容端点。

核心机制只有四个变量：

```bash
ANTHROPIC_BASE_URL         # 改成国产模型的兼容端点
ANTHROPIC_AUTH_TOKEN       # 你的国产模型 API Key
ANTHROPIC_MODEL            # 主模型（负责写代码、推理）
ANTHROPIC_SMALL_FAST_MODEL # 轻量模型（负责后台小任务，如生成提交信息）
```

下面这张图说明了改造前后的差异：

```mermaid
flowchart LR
    subgraph 默认["默认路径（国内不通）"]
        A1[Claude Code] -->|api.anthropic.com| A2[❌ 超时/不支持区域]
    end
    subgraph 改造["本教程路径（直连）"]
        B1[Claude Code] -->|读取 settings.json| B2[环境变量覆盖]
        B2 -->|ANTHROPIC_BASE_URL| B3["open.bigmodel.cn<br/>/api/anthropic"]
        B3 --> B4[✅ 智谱 GLM 模型]
    end
```

理解了这张图，后面的每一步都只是在"填表"。

---

## 第二步：搭建 Node.js 运行环境

### 2.1 检查是否已安装

打开终端（Windows 按 `Win+R` 输入 `powershell`；Mac/Linux 打开"终端"），执行：

```bash
node -v
npm -v
```

**预期结果：** 返回类似 `v20.11.0` 和 `10.2.4` 的版本号。

- 如果 `node -v` 报"命令未找到"，说明未安装或未加入环境变量，继续 2.2。
- 如果版本 < 18，建议升级到 20 LTS。

### 2.2 安装 Node.js

去 [nodejs.org](https://nodejs.org) 下载 **20 LTS** 的安装包，一路"下一步"即可。Windows 安装时务必勾选 **Add to PATH**。

### 2.3 （国内强烈推荐）切换 npm 镜像源

国内访问默认 npm 源很慢，先换成淘宝镜像：

```bash
npm config set registry https://registry.npmmirror.com
npm config get registry   # 验证：应输出 npmmirror 地址
```

**常见问题：** 切换后 `npm install` 仍很慢？多半是公司内网代理拦截，可临时设置 `npm config set proxy http://你的代理:端口`，装完再 `npm config delete proxy`。

---

## 第三步：安装 Claude Code

执行全局安装：

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

安装完成后验证：

```bash
claude --version
```

**预期结果：** 输出类似 `2.x.x` 的版本号，说明安装成功。

> **替代方案（原生安装器）：** 官方也提供不依赖 npm 的原生安装器——macOS/Linux 执行 `curl -fsSL https://claude.ai/install.sh | bash`，Windows PowerShell 执行 `irm https://claude.ai/install.ps1 | iex`。两条路线功能一致，新手用 npm 最简单。

**常见问题：**

| 现象 | 原因 | 解决 |
|------|------|------|
| `claude: command not found` | 全局 bin 目录不在 PATH | Windows 重开终端；Mac/Linux 在 `~/.zshrc` 加 `export PATH="$PATH:$(npm bin -g)"` |
| `EACCES permission denied` | 全局安装权限不足 | Mac/Linux 改用 `sudo`，或配置 npm 全局目录到用户家目录 |
| 卡住不动 | npm 源问题 | 回到 2.3 确认镜像源 |

---

## 第四步：申请智谱 GLM API Key

1. 浏览器打开 [bigmodel.cn](https://bigmodel.cn)，手机号注册并实名（个人实名即可，几分钟完成）。
2. 进入控制台 → **API Keys** → 点击"添加新的 API Key"→ 复制保存。
3. 记下你要用的模型 ID，当前推荐：
   - 主模型：`glm-4.6`（或更新版本的 `glm-5.1`，视账号开放情况）
   - 轻量模型：`glm-4.5-air`（速度快、便宜，适合后台小任务）

> Key 只在创建时完整显示一次，务必先复制到本地记事本。泄露后可在控制台一键禁用。

---

## 第五步：配置 Claude Code 直连 GLM（核心步骤）

Claude Code 的配置文件位于用户家目录的 `.claude/settings.json`：

- **Windows：** `C:\Users\你的用户名\.claude\settings.json`
- **macOS / Linux：** `~/.claude/settings.json`

如果该文件不存在，手动创建（连 `.claude` 文件夹一起）。写入以下内容：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "你刚才复制的GLM-API-Key",
    "ANTHROPIC_MODEL": "glm-4.6",
    "ANTHROPIC_SMALL_FAST_MODEL": "glm-4.5-air",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}
```

**逐行解释：**

- `ANTHROPIC_BASE_URL`：智谱的 Anthropic 兼容端点，末尾 `/api/anthropic` 不能少。
- `ANTHROPIC_AUTH_TOKEN`：用 `AUTH_TOKEN` 而非 `API_KEY`，可避免 Claude Code 触发官方 Key 校验逻辑，第三方接入更稳。
- `ANTHROPIC_MODEL` / `ANTHROPIC_SMALL_FAST_MODEL`：分别指定主力模型和后台小模型。后台小模型若不指定，Claude Code 会默认调一个可能不存在的型号导致报错，**务必指定**。
- `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`：关闭遥测等非必要请求，减少无关流量与潜在报错。

> **重要：** 配置文件是标准 JSON，**不能有注释、不能有多余逗号**，否则 Claude Code 会启动失败。保存后**重启终端**让环境变量生效。

---

## 第六步：首次启动与验证

### 6.1 启动

在终端任意目录输入：

```bash
claude
```

由于已设置 `ANTHROPIC_AUTH_TOKEN`，Claude Code 会直接读取它，**通常不再要求 OAuth 登录**。若弹出登录引导，选择跳过/手动（因为第三方 Key 不走官方登录）。

### 6.2 健康检查

进入交互界面后，先做三件事确认连通：

1. **看模型：** 在输入框输入 `/model` 回车，确认显示的是你配置的 `glm-4.6`。
2. **看配置：** 输入 `/config` 查看 settings 是否被正确加载。
3. **冒烟测试：** 直接发送一句：

   ```
   用一句话介绍你自己，并告诉我你是哪个模型
   ```

**预期结果：** 模型正常返回一段中文自我介绍。如果几秒内返回正常，说明整条链路（终端 → Claude Code → 智谱端点 → GLM）已经打通 🎉。

**常见问题：**

| 现象 | 排查 |
|------|------|
| `401 Unauthorized` | Key 填错 / Key 前后有空格 / Key 已禁用 |
| `404 Not Found` | `ANTHROPIC_BASE_URL` 拼写错误，尤其漏了 `/api/anthropic` |
| `model not found` | `ANTHROPIC_MODEL` 写的型号账号不可用，去控制台核对可用模型列表 |
| 一直转圈无响应 | 网络/代理问题；公司网络需放行 `open.bigmodel.cn` |
| 仍要求登录 | 终端未重启；或把 env 写成了 shell 的 `export` 但未 `source` |

---

## 第七步：第一个项目——让 AI 现场生成一个 Web 小工具

理论验证完毕，现在做点"看得见"的东西。我们让 Claude Code **从零生成**一个单文件 HTML 小工具：**「随机励志语生成器」**，浏览器双击即可运行，零依赖、即时出效果。

### 7.1 创建项目目录

```bash
mkdir my-first-ai-project
cd my-first-ai-project
```

> 没有用 `git init` 也没关系，新手先聚焦"跑起来"。后续可随时 `git init` 接入版本管理。

### 7.2 启动并下达任务

在该目录下启动 `claude`，输入以下提示词（直接复制）：

```
在当前目录创建一个单文件 index.html：点击按钮随机显示一句中文励志语，
配渐变色背景和优雅的中文字体（用系统字体即可），加一个"已读 N 句"计数器。
要求所有 HTML/CSS/JS 写在同一个 index.html 里，不依赖任何外部库。
```

**预期结果：** Claude Code 会规划步骤、调用工具创建 `index.html`，并显示创建过程。完成后你会看到类似提示：

```
✓ Created index.html
```

### 7.3 运行项目

无需任何启动命令，直接双击 `index.html` 用浏览器打开（或在终端执行）：

- **macOS：** `open index.html`
- **Windows：** `start index.html`
- **Linux：** `xdg-open index.html`

**预期结果：** 浏览器打开一个带渐变背景的页面，点击"换一句"按钮即可刷新励志语，计数器累加。这就是你的第一个由 AI 编写的项目！

### 7.4 持续迭代（体验 AI 编程的核心价值）

不要停在第一版，继续在对话里提需求，体验"自然语言即编程"：

```
把背景渐变改成紫色系，再加一个"收藏"按钮，点收藏把当前句子存到 localStorage，
页面底部用一个小列表展示已收藏的句子。
```

Claude Code 会读取并修改现有 `index.html`，增量实现新功能。多轮迭代后，你会直观感受到：**你只描述"想要什么"，Claude Code 负责"怎么写"**。

---

## 进阶：接入 DeepSeek / Qwen 等纯 OpenAI 兼容模型

DeepSeek、通义 Qwen 等只提供 OpenAI 协议端点，与 Claude Code 的 Anthropic 协议不兼容，需要一个**协议转换路由**。社区主流方案是开源工具 **claude-code-router（CCR）**：

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

然后在 `~/.claude-code-router/config.json` 中配置默认路由指向 DeepSeek/Qwen 的端点与 Key，再用 `ccr code`（而非 `claude`）启动，CCR 会在本地拦截请求并做 Anthropic↔OpenAI 协议转换。

> 新手建议**先用 GLM 直连跑通**，熟悉后再尝试 CCR 接入更多模型。两种路线的取舍：直连零中间件、最稳；CCR 灵活可路由多家模型，但多一层依赖需维护。

---

## 整体工作流程图

```mermaid
flowchart TD
    S1[1. 安装 Node.js ≥18 + 换 npmmirror 源] --> S2[2. npm 全局安装 Claude Code]
    S2 --> S3[3. 注册智谱 bigmodel.cn 领取 GLM Key]
    S3 --> S4[4. 写 ~/.claude/settings.json<br/>覆盖 BASE_URL / TOKEN / MODEL]
    S4 --> S5[5. claude 启动 → /model 冒烟测试]
    S5 -->|连通| S6[6. 新建项目目录 下达任务]
    S5 -->|报错| F[查常见问题表<br/>核对 Key/URL/型号]
    S6 --> S7[7. AI 生成文件 → 浏览器打开验证]
    S7 --> S8[8. 自然语言迭代新功能]
    S8 --> S9[9. 进阶: CCR 接入 DeepSeek/Qwen]
```

---

## 常见问题速查表（汇总）

| 报错 / 现象 | 根因 | 一句话解决 |
|------|------|------|
| `claude: command not found` | PATH 未生效 | 重开终端 / 配置 PATH |
| 安装时 `EACCES` | 权限不足 | 配置 npm 全局目录或用 sudo |
| `npm install` 极慢 | 默认源 / 代理 | 换 npmmirror、放行网络 |
| 启动后要求 OAuth 登录 | 未读到第三方 Token | 确认 settings.json 已写、已重启终端 |
| `401` / `403` | Key 无效 | 重新生成 Key，去前后空格 |
| `404` | 端点路径错 | 确保含 `/api/anthropic` |
| `model not found` | 型号不可用 | 控制台核对，改 `ANTHROPIC_MODEL` |
| 后台任务报错 | 未设小模型 | 补 `ANTHROPIC_SMALL_FAST_MODEL` |
| settings 启动崩溃 | JSON 非法 | 去掉注释 / 多余逗号，用 JSON 校验器检查 |

---

## 延伸阅读

- **Anthropic 官方 Claude Code 文档**：`https://docs.anthropic.com/en/docs/claude-code` —— 了解全部设置项、模型配置、命令参考。
- **智谱开放平台文档**：`https://open.bigmodel.cn/dev/api` —— 核对可用模型 ID 与 Anthropic 兼容端点最新说明。
- **claude-code-router 项目**：GitHub 搜索 `claude-code-router` —— 进阶接入 DeepSeek/Qwen/Kimi 的多模型路由方案。
- **菜鸟教程 Claude Code 章节**：`https://www.runoob.com/claude-code/claude-code-install.html` —— 命令速查与入门补充。

---

## 训练营适用性评估

- **适合类型：** 高校 AI 编程入门训练营、企业新员工技术启蒙营、社区开源体验工坊、K12/高职 AI 兴趣课。对"动手出成果、低门槛、低预算"导向的训练营尤为契合。
- **预计教学时长：** 讲解 + 跟做约 **90–120 分钟**（含环境排错缓冲）。其中环境与安装 30 分钟、配置直连 20 分钟、首个项目实战 40 分钟、答疑迭代 30 分钟。
- **学员产出：** 每人拥有一个本地可运行的 Claude Code + 国产模型环境，并带走一个自己迭代过的 Web 小项目。
- **进阶衔接：** 完成本课后，可顺次衔接"Skills 开发""MCP 服务器""Hooks 与自动化"等中阶主题，形成完整进阶路径。

---

## 参考来源

1. [Claude Code国内环境安装配置保姆级教程（亲测2026可用）](https://blog.csdn.net/m0_53581755/article/details/161009026) — CSDN，Windows 下从 Node.js 到 API 直连的完整图文流程。
2. [Claude Code 接入模型（DeepSeek、GLM）](https://www.cnblogs.com/starsAI/articles/19319025) — 博客园 stars-AI，逐步接入国产模型的环境变量与配置示例。
3. [Claude Code 接入四大国产编程模型全指南](https://developer.cloud.tencent.com/article/2685784) — 腾讯云开发者社区，DeepSeek/GLM/Qwen/Kimi 多模型横向配置对比。
4. [Claude Code 配置 DeepSeek 教程：从安装到模型接入](https://fxdirection.github.io/2026/05/04/Claude-Code-%E9%85%8D%E7%BD%AE-DeepSeek-%E6%95%99%E7%A8%8B/index.html) — 个人技术博客，一份较完整的 Claude Code + 第三方模型配置实录。
5. [Anthropic Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code) — 官方设置项、模型环境变量与命令参考的权威来源。

> [!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)