---
title: "第 1 周手册：搭建 AI 工作台"
---

# 🧰 第 1 周手册：搭建 AI 工作台

本手册对应教材第 3 章《智能体框架安装与配置》（<https://ai.lingnan.top/book/chapters/chapter-3/index.html>），按本学期的课堂配置（Claude Code + DeepSeek + CC Switch）重排。教材里有每一步的截图，本手册只给最短路径；卡住时去教材对应小节看图。

## 今天装什么，按什么顺序

顺序有讲究：Claude Code 依赖 Node.js 和 Git，所以先装这两个；CC Switch 给 Claude Code 接模型；VS Code 最后装，它只是个编辑器，不影响前面任何一步。macOS 要先装两样底座。

| 序 | 软件 | 作用 | 预计 |
|---|---|---|---|
| 0 | 飞书 | 课程群，发材料、交作业 | 5 分钟 |
| 1（仅 macOS） | Xcode 命令行工具 + Homebrew | macOS 装其他软件的底座 | 15–30 分钟 |
| 2 | Node.js + npm | Claude Code 的运行基础 | 10 分钟 |
| 3 | Git | 版本控制，Claude Code 工作时会用；第 3 周正式讲 | 5 分钟 |
| 4 | Claude Code | 本课主力智能体工具 | 10 分钟 |
| 5–6 | DeepSeek 密钥 + CC Switch | 给 Claude Code 接上模型 | 15 分钟 + 注册 |
| 7 | VS Code | 编辑器，看文件、开终端 | 5 分钟 |
| 8 | Miniconda、Pandoc、Skills 扩展包 | 自行尝试，第 2–4 周用到 | 课后 |

> **⚠️ 网络提示**
>
> 2026 年 9 月 7 日在广州国内网络测试时：
> - Claude Code 官网的一键安装脚本（`irm https://claude.ai/install.ps1 | iex` 或 `curl -fsSL https://claude.ai/install.sh | bash`）**下载不到安装文件**。本手册不用它，走 npm。
> - Node.js、Git 用淘宝镜像下载，速度正常。网上教程里的清华 Node 镜像已失效，别照抄。
> - CC Switch 的安装包从课程群里拿，不要去 GitHub 现场下。

## 0. 准备工作

### 加入课程群

手机或电脑装飞书，扫老师投影的二维码入群。群里已有本手册、[《环境验收清单》](/materials/2026-autumn/w01/checklist)、[《常见问题》](/materials/2026-autumn/w01/faq)和各安装包。

### 认识终端

后面所有命令都在终端里敲。

- **Windows**：开始菜单搜 **PowerShell**，打开。不要用 CMD（命令提示符），也不要用 PowerShell (x86)。看到 `PS C:\Users\你的名字>` 就对了。
- **macOS**：启动台搜 **终端**（Terminal），打开。看到 `你的名字@MacBook ~ %` 就对了。

三条规矩：命令一行一行敲，敲完按回车；从网页复制命令后用右键粘贴（Windows）或 Cmd+V（macOS）；**装完任何软件都要关掉终端重新打开**，否则新命令找不到。

### 一个工作文件夹

以后这门课的东西都放一个地方。终端里：

```bash
mkdir agent-lab
```

Windows 下它建在 `C:\Users\你的名字\agent-lab`，macOS 在 `/Users/你的名字/agent-lab`。

## 1. macOS 底座：Xcode 命令行工具与 Homebrew

**Windows 用户跳过本节，直接到第 2 节。**

### Xcode 命令行工具

终端输入：

```bash
xcode-select --install
```

弹出对话框点**安装**（不要点「获取 Xcode」），同意协议，等 5–20 分钟。装的是约 740 MB 的命令行工具，不是十几 GB 的 Xcode。提示「已安装」就直接下一步。

验证：`git --version` 有输出。这一步顺便把 Git 装好了。

### Homebrew

Homebrew 是 macOS 的命令行软件管理器，装好之后 Node.js、VS Code 都是一行命令。官方安装脚本走 GitHub，国内慢，用清华镜像装。把下面整段复制进终端，回车：

```bash
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
export HOMEBREW_INSTALL_FROM_API=1
export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
git clone --depth=1 https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/install.git brew-install
/bin/bash brew-install/install.sh
rm -rf brew-install
```

中途要输开机密码，输入时屏幕不显示任何字符，敲完回车。5–15 分钟。

**Apple 芯片（M1–M4）的 Mac** 装完再执行两行，让终端找得到 brew：

```bash
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
source ~/.zprofile
```

不知道自己是什么芯片：左上角  → 关于本机，看「芯片」一栏。

让以后每次 `brew install` 都走国内源（只做一次）：

```bash
echo 'export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"' >> ~/.zprofile
echo 'export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"' >> ~/.zprofile
echo 'export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"' >> ~/.zprofile
echo 'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"' >> ~/.zprofile
source ~/.zprofile
```

验证：

```bash
brew --version
```

看到 `Homebrew 4.x.x`。详细截图见教材 3.2 B–C。

## 2. Node.js 和 npm

Node.js 是 Claude Code 的运行环境，装它会顺带装上 npm（用来安装 Claude Code）。

### 安装

**Windows**：从淘宝镜像下载（当前长期支持版 v24.20.0）：

<https://cdn.npmmirror.com/binaries/node/v24.20.0/node-v24.20.0-x64.msi>

双击 `.msi`，一路 Next。「Custom Setup」那页保持默认，确认 **Add to PATH** 是勾上的。最后一页问要不要装「Tools for Native Modules」，**不勾**，Finish。

**macOS**：

```bash
brew install node
```

### 验证

**关掉终端，重新打开**，输入：

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

分别看到 `v24.x.x` 和一个 `11.x.x` 之类的版本号就成功了。

### 换国内源

npm 默认从境外下载软件包，慢且容易断。换成淘宝源：

```bash
npm config set registry https://registry.npmmirror.com
```

验证：

```bash
npm config get registry
```

应显示 <https://registry.npmmirror.com/>。

> **🔧 故障排除**
>
> - `node` 不是内部或外部命令 / command not found：没重开终端，或安装时没勾 Add to PATH。先重开终端；不行就重装 Node，装的时候看清那个勾。
> - Windows 弹出「无法加载文件…因为在此系统上禁止运行脚本」：在 PowerShell 里运行 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`，回答 Y。见教材 3.3 B。

## 3. Git

Git 记录文件的每一次修改，改坏了能退回去。第 3 周正式讲，今天先装上。

**Windows**：从淘宝镜像下载安装包（v2.55.0，约 65 MB）：

<https://cdn.npmmirror.com/binaries/git-for-windows/v2.55.0.windows.5/Git-2.55.0.5-64-bit.exe>

双击安装，**所有选项保持默认**，一路 Next 到 Finish（页数多，别改任何一项）。

**macOS**：第 1 节装 Xcode 命令行工具时已经装好了，跳过。

### 验证

关掉终端重新打开：

```bash
git --version
```

看到 `git version 2.5x.x` 即可。第 3 周之前不需要做任何配置。

## 4. Claude Code

用 npm 全局安装：

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

一两分钟。看到一堆滚动的输出最后没有红字 ERR 就是装好了。

> **🔧 故障排除**
>
> - **卡在下载不动**：确认第 2 节的换源做了，`npm config get registry` 应显示淘宝地址。
> - **Windows 报错提到 `x86`**：你打开的是 PowerShell (x86)，关掉，开始菜单里找不带 (x86) 的那个。
> - **macOS 报 `EACCES: permission denied`**：用 brew 装的 Node 一般不会出现；出现了按[《常见问题》](/materials/2026-autumn/w01/faq)2.9 处理，不要加 `sudo`。

### 验证

再次关掉终端重新打开：

```bash
claude --version
```

看到 `2.1.xxx (Claude Code)` 即可。**先别运行 `claude`**——它现在还没接模型，启动会要求登录 Anthropic 账号，国内登不上。下一步接上 DeepSeek 再启动。

---

## 5–6. 接入 DeepSeek：API 密钥与 CC Switch

Claude Code 自己不带模型。它把你的指令打包成请求发给一个模型服务，再把返回的结果落实成文件读写和命令执行。所以装好 Claude Code 之后，还要给它接一个模型。

本课选 DeepSeek 作为课堂主力，原因有三条：国内直接访问，不需要代理；按量计费，人民币充值，没有套餐门槛；官方提供 Anthropic 兼容端点，并且专门写了接入 Claude Code 的文档。

接入分三步：在 DeepSeek 平台拿到 API 密钥，安装 CC Switch，在 CC Switch 里把密钥填进去。

### A. 注册 DeepSeek 并创建 API 密钥

#### 注册与实名

打开浏览器，访问 DeepSeek 开放平台：**<https://platform.deepseek.com>**


按开放平台页面提供的方式注册或登录，并按提示完成实名认证。遇到困难可先完成软件安装，再处理账号。

> **💡 操作提示**
>
> 以上是 2026 年 9 月的流程。平台页面会改版，以登录后页面上的实际提示为准。如果实名这一步卡住，先完成后面的软件安装，回头再处理。

#### 充值

API 按用量计费，用多少扣多少。在平台充值页查看可选金额，按自己的预算小额充值；后续根据实际用量补充。


DeepSeek 目前提供两个模型，价格如下（元 / 百万 token，2026 年 9 月官方定价）：

| | deepseek-v4-flash | deepseek-v4-pro |
|------|------|------|
| 输入（缓存未命中）空闲 / 高峰 | 1.5 / 3.0 | 4.5 / 9.0 |
| 输入（缓存命中）空闲 / 高峰 | 0.05 / 0.10 | 0.15 / 0.30 |
| 输出 空闲 / 高峰 | 4.5 / 9.0 | 13.5 / 27.0 |
| 上下文长度 | 1M | 1M |

高峰时段是北京时间周一至周五 9:00–12:00 和 14:00–18:00，其余时间按空闲价计，是高峰价的一半。

费用取决于模型、上下文长度、调用轮数与重试次数。先完成一个练习，再到平台用量页查看实际消耗；套餐与单价见[《模型平台套餐与官方链接》](/materials/2026-autumn/w01/model-plans)。

> **📘 知识卡片**
>
> 「缓存命中」指请求里和上一次重复的那部分内容。Claude Code 每轮对话都会把之前的上下文一起发过去，重复部分按命中价计，只有新增部分按未命中价计。这就是为什么一段长对话的成本远低于把每一轮的 token 简单相加。

#### 创建 API 密钥

密钥是你访问 API 的凭证，相当于账号密码。

1. 左侧菜单点 **API keys**，或直接访问 <https://platform.deepseek.com/api_keys>
2. 点右上角 **创建 API key**
3. 输入一个名字，方便自己识别，比如 `claude-code-课程`
4. 弹窗显示完整密钥，以 `sk-` 开头


**密钥只在这个弹窗里完整显示一次。** 关掉之后再也看不到，只能删掉重建。先打开记事本，再点创建，生成后立刻复制粘贴保存。


> **⚠️ 安全提示**
>
> 密钥不要发给他人，不要截图分享，不要上传到 GitHub 或写进任何会提交的文件。谁拿到密钥，谁就能花你的钱。如果怀疑泄露，回到 API keys 页删掉旧的，重新创建一个。

### B. 安装 CC Switch

#### 它是什么

CC Switch 是一个开源桌面工具（GitHub：`farion1231/cc-switch`，MIT 协议），用来管理 Claude Code 等工具接哪个模型服务。它把各家服务的配置存在自己的数据库里，你在界面上点一下，它就把对应配置写进 Claude Code 的配置文件。

不装 CC Switch 也能接 DeepSeek，直接手改配置文件即可（见本节 E）。装它的好处是：不用碰 JSON，切换模型服务只需点一下，日后 DeepSeek 出问题可以立刻换一家。

> **📘 知识卡片**
>
> CC Switch 改的是配置文件，不是环境变量。对 Claude Code，它写入 `~/.claude/settings.json`（Windows 下是 `C:\Users\你的用户名\.claude\settings.json`）。它自己的数据存在 `~/.cc-switch/cc-switch.db`，每次写入前会自动备份，保留最近 10 份。

#### 下载安装包

CC Switch 有两个官方下载入口：GitHub Releases 页 <https://github.com/farion1231/cc-switch/releases> 和官网 <https://ccswitch.io>。课堂上由教师把安装包发到课程群，不要自己去 GitHub 下——国内访问 GitHub 速度不稳定，几十人同时下载多半有人失败。


当前版本 v3.20.1（2026 年 8 月 28 日发布）：

| 系统 | 文件 | 大小 |
|------|------|------|
| Windows | `CC-Switch-v3.20.1-Windows.msi` | 12.9 MB |
| macOS | `CC-Switch-v3.20.1-macOS.dmg` | 26.8 MB |

> **⚠️ 安全提示**
>
> CC Switch 免费开源。网上有假冒站点以「CC Switch」名义收费、要求充值或索取账号密码，项目方已发过声明。只从上面两个入口下载，任何要你付钱的都是假的。

#### 安装

**Windows**：双击 `.msi`，一路 Next 到 Finish。安装完成后开始菜单里出现 CC Switch。

**macOS**：双击 `.dmg`，把 CC Switch 图标拖进 Applications 文件夹。从启动台或 Applications 里打开。

> **🔧 故障排除**
>
> macOS 首次打开如果提示「无法验证开发者」或「已损坏」，打开 **系统设置 → 隐私与安全性**，在页面下方找到被拦截的 CC Switch，点 **仍要打开**。这是 macOS 对非 App Store 应用的常规提示。

### C. 在 CC Switch 里配置 DeepSeek

打开 CC Switch，按下面顺序操作：

1. 顶部应用切换栏选 **Claude Code**


2. 点 **添加供应商**，在预设列表里找到 **DeepSeek**


3. 把你的 API 密钥粘贴进密钥栏
4. **把模型名改成带 `[1m]` 后缀的版本**：预设里三个模型字段（`ANTHROPIC_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`）默认填的是 `deepseek-v4-pro`，改成 `deepseek-v4-pro[1m]`。`ANTHROPIC_DEFAULT_HAIKU_MODEL` 保持 `deepseek-v4-flash` 不动


5. 保存，然后点 **启用**，让 DeepSeek 成为当前供应商


> **💡 操作提示**
>
> 第 4 步是这一节最容易漏的地方。DeepSeek 官方文档写的模型名是 `deepseek-v4-pro[1m]`，后缀 `[1m]` 表示请求 1M 上下文版本；CC Switch 的预设没带这个后缀。不改也能连通、能对话，但上下文窗口只有默认大小，任务稍大就会出现「前面说的它忘了」。这类不报错的失败最难排查。
>
> 顺带记住一条原则：工具的默认值不等于最优配置，拿到预设先回官方文档核对一遍。
>
> CC Switch 的按钮名称可能随版本变化。本文按 v3.20.1 描述，以你看到的界面为准。

> **🔧 故障排除**
>
> 保存供应商时如果弹出「未找到可用的模型列表端点」之类的警告，可以忽略。CC Switch 保存时会去探测服务商的模型列表接口，DeepSeek 的 Anthropic 端点不提供这个接口，探测失败不影响实际使用。

### D. 验证接通

打开终端，进入你的工作目录，启动 Claude Code：

```bash
cd ~/agent-lab
claude
```

Claude Code 支持热切换，CC Switch 里刚改的配置不用重启终端就能生效。如果不放心，关掉终端重开一次。

启动后做两个验证：

**第一，问它是谁。** 在对话框输入：

```txt
你是哪家公司的什么模型？
```

回答里应当出现 DeepSeek。


**第二，回平台看用量。** 打开 <https://platform.deepseek.com> 的用量页，刚才那一问应当已经产生了几百 token 的消耗。看到消耗，说明请求确实走到了 DeepSeek。

> **📘 知识卡片**
>
> 网络通不通，可以不进 Claude Code 直接测。在终端运行：
>
> ```bash
> curl -s -o /dev/null -w "%{http_code}\n" https://api.deepseek.com/anthropic/v1/messages
> ```
>
> 返回 `401` 就是通的——端点活着，只是没带密钥。返回 `000` 或长时间没反应，是网络问题，不是配置问题。

> **🔧 故障排除**
>
> **启动后仍要求登录 Anthropic 账号。** 说明 Claude Code 没读到 DeepSeek 配置。先在 CC Switch 里确认 DeepSeek 处于启用状态；再打开 `~/.claude/settings.json` 看 `env` 里有没有 `ANTHROPIC_BASE_URL`。如果都有但仍要求登录，在 `~/.claude.json` 里加一行 `"hasCompletedOnboarding": true`，让它跳过首次登录校验。
>
> **回答里报 `authentication_error` 或 401。** 密钥不对。常见原因是复制时多了空格或少了字符，回 DeepSeek 平台重新创建一个。
>
> **报 429。** 请求过于频繁，等一分钟再试。全班同时发请求时容易出现。
>
> **昨天能用，今天又要登录。** 多半是用环境变量方式配的，PowerShell 的 `$env:` 只在当前窗口有效。改用 CC Switch 或直接写 `settings.json`，配置就会保留。
>
> **觉得模型「变笨」了。** 检查模型名。传入不认识的模型名时 DeepSeek 不报错，会静默降级到 `deepseek-v4-flash`。

### E. 不装 CC Switch：直接写配置文件

CC Switch 做的事，手工也能做。用 VS Code 打开 `~/.claude/settings.json`（不存在就新建），写入：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥",
    "ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-flash",
    "API_TIMEOUT_MS": "600000"
  }
}
```

这套变量来自 DeepSeek 官方的 Claude Code 接入文档。认证字段是 `ANTHROPIC_AUTH_TOKEN`，不是 `ANTHROPIC_API_KEY`——后者是 Anthropic 官方 API 的字段，设了会干扰第三方接入。

> **📘 知识卡片**
>
> Claude Code 的配置有三层，优先级从高到低：项目目录下的 `.claude/settings.local.json`，项目目录下的 `.claude/settings.json`，用户目录下的 `~/.claude/settings.json`。上面写的是用户级配置，对所有项目生效。
>
> `settings.json` 里 `env` 块的值会覆盖终端里 `export` 的同名变量。如果你既在终端设了变量又在文件里写了，以文件为准。排查「配了但不生效」时，先看这个文件。

> **💡 选择哪种方式**
>
> 课堂上统一用 CC Switch，界面操作不容易错，切换服务商也方便。理解了 E 节的配置文件之后，你就知道 CC Switch 每次点「启用」时在做什么。两种方式底层是同一件事。

---

## 7. VS Code

编辑器。看文件、改文件、在同一个窗口里开终端跑 Claude Code，都在这里面。

**Windows**：官网 <https://code.visualstudio.com> 点 Download，安装时勾上「添加到 PATH」和「通过 Code 打开」。

**macOS**：

```bash
brew install --cask visual-studio-code
```

装完打开，菜单 Terminal → New Terminal，下方出现的就是终端，和你前面用的是同一个东西。以后在 VS Code 里打开 `agent-lab` 文件夹（File → Open Folder），在内置终端里运行 `claude`，上面看文件、下面跟它对话。

界面是英文的，可以先不管；想切中文见教材 3.5 D。

## 8. 自行尝试：其余工具

下面这些今天不必装完。上机时间有余或课后照教材装，每装一个回来在验收清单上补一笔。

| 软件 | 教材位置 | 一句话 |
|---|---|---|
| Miniconda | macOS：3.2 D；Windows：3.3 | Python 环境。装好后 `conda --version` |
| Pandoc | macOS：3.2 D；Windows：3.3 | 文档转换。装好后 `pandoc --version` |
| Skills 扩展包 | 3.4 A | 第 4 周讲 Skills 时统一装，想先试的可以照做 |

macOS 用 brew 一行搞定前两个：`brew install pandoc && brew install --cask miniconda`。

教材的详细安装说明与截图见[第 3 章](https://ai.lingnan.top/book/chapters/chapter-3/index.html)。

## 9. 验收

回到[《环境验收清单》](/materials/2026-autumn/w01/checklist)逐条打勾，截图发群。DeepSeek 账号课上没来得及注册的，周四（9 月 10 日）晚 22:00 前补交。

装好之后去做[《课堂任务》](/materials/2026-autumn/w01/class-task)。