环境安装手册

本手册对应教材第 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 要先装两样底座。

⚠️ 网络提示

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. 准备工作

加入课程群

手机或电脑装飞书，扫老师投影的二维码入群。群里已有本手册、《环境验收清单》、《常见问题》和各安装包。

认识终端

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

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

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

一个工作文件夹

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

mkdir agent-lab

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

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

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

Xcode 命令行工具

终端输入：

xcode-select --install

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

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

Homebrew

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

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：

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

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

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

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

验证：

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：

brew install node

验证

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

node -v
npm -v

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

换国内源

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

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

验证：

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 命令行工具时已经装好了，跳过。

验证

关掉终端重新打开：

git --version

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

4. Claude Code

用 npm 全局安装：

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

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

🔧 故障排除

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

验证

再次关掉终端重新打开：

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 月官方定价）：

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

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

📘 知识卡片

「缓存命中」指请求里和上一次重复的那部分内容。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 日发布）：

⚠️ 安全提示

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：

cd ~/agent-lab
claude

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

启动后做两个验证：

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

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

回答里应当出现 DeepSeek。

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

📘 知识卡片

网络通不通，可以不进 Claude Code 直接测。在终端运行：

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（不存在就新建），写入：

{
  "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：

brew install --cask visual-studio-code

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

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

8. 自行尝试：其余工具

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

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

教材的详细安装说明与截图见第 3 章。

9. 验收

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

装好之后去做《课堂任务》。