环境安装手册

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

Mac 安装全流程视频（约 9 分 40 秒）。Skills 扩展包请按本页第 8 节的最新步骤安装。

装什么，按什么顺序

顺序有讲究：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」），同意协议并等待完成。下载大小、所需空间和等待时间以安装器提示为准。提示「已安装」就直接下一步。

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

Homebrew

Homebrew 用来安装和管理 macOS 软件。2026-10-14 国内网络实测（Apple 芯片 Mac）：首选中科大 brew Git 镜像，搭配清华的 core、API 和预编译软件包镜像；安装脚本从 Homebrew 官方地址下载。

先把下面命令逐行复制到终端执行：

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/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"
curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh -o ~/Downloads/homebrew-install-official.sh
/bin/bash ~/Downloads/homebrew-install-official.sh

出现密码提示时输入 Mac 开机密码；屏幕不会显示字符，输完按回车。按安装器提示继续，看到安装成功再做下一步。

这步下载不通时，可用原来的清华安装脚本镜像作为备选：git clone --depth=1 https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/install.git brew-install，再运行 /bin/bash brew-install/install.sh。brew Git 的备用地址为 https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git，替换上面的 HOMEBREW_BREW_GIT_REMOTE 即可；若已写入下面的配置，也同步替换那一行。

Apple 芯片 Mac 接着执行以下命令，把 brew 加入终端路径，并保存国内镜像设置（只做一次）：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
echo 'export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/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

不知道自己用什么芯片：打开左上角 Apple 菜单 → 关于本机。Intel Mac 按安装器的 Next steps 设置 brew 路径，不照抄 /opt/homebrew。

验证版本和当前镜像：

brew --version
printf '%s\n' "$HOMEBREW_BREW_GIT_REMOTE" "$HOMEBREW_API_DOMAIN" "$HOMEBREW_BOTTLE_DOMAIN"

看到 Homebrew 版本号，以及中科大 brew 地址、清华 API 和 bottle 地址即可。实测版本为 7.0.9，不要求与示例版本完全相同。镜像缺少个别软件包时，安装器可能从官方地址下载；设置了镜像不代表每个文件都来自镜像。

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 之类的版本号就成功了。

macOS 的 brew install node 不锁定 v24；2026-10-14 国内网络实测为 Node v26.11.1、npm 11.20.0。能正常输出版本号即可，不要为了匹配上面的 Windows 示例降级。

换国内源

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 记录文件的每一次修改，改坏了能退回去。

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 即可。装好后不需要额外配置。

4. Claude Code

macOS 用户使用下面这条完整命令（2026-10-14 国内网络实测）：

npm install -g @anthropic-ai/claude-code --allow-scripts=@anthropic-ai/claude-code

--allow-scripts 后写完整包名，不只写 @anthropic-ai/。安装时若提示该包的安装脚本被阻止，用这条命令重装，再检查 claude --version。

Windows 用 npm 全局安装：

npm install -g @anthropic-ai/claude-code --allow-scripts=@anthropic-ai/

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

后面的 --allow-scripts=@anthropic-ai/ 不能省。npm 从 12 版起默认不运行安装包自带的安装脚本，Claude Code 要靠它完成安装；少了这个参数，安装命令不报错，装完运行 claude 却会出错。旧版本 npm 可能提示不认识这个参数，不影响安装。

🔧 故障排除

• 卡在下载不动：确认第 2 节的换源做了，npm config get registry 应显示淘宝地址。
• Windows 报错提到 x86：你打开的是 PowerShell (x86)，关掉，开始菜单里找不带 (x86) 的那个。
• 装完运行 claude 报错：多半是安装时少了 --allow-scripts=@anthropic-ai/。用上面的完整命令重装一次，关掉终端重新打开再试。
• 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 里把密钥填进去。

想用千问 AI 平台 Token Plan 的，装好 CC Switch 后照《千问接入教程》添加供应商。

A. 注册 DeepSeek 并创建 API 密钥

注册与实名

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

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

💡 操作提示

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

充值

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

本课使用 DeepSeek Flash，API 模型名为 deepseek-flash，当前对应 DeepSeek-V4.1-Flash。价格如下（元 / 百万 token，2026 年 10 月 14 日核对官方模型与价格页）：

高峰时段是北京时间周一至周五（不含中国法定节假日）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. 把模型字段改成 DeepSeek Flash：ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL 都填 deepseek-flash[1m]；ANTHROPIC_DEFAULT_HAIKU_MODEL 和 CLAUDE_CODE_SUBAGENT_MODEL 都填 deepseek-flash（按官方示例，这两项不带后缀）。界面中未显示的字段可对照本节 E 的 settings.json 示例补齐

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

💡 操作提示

第 4 步请对照DeepSeek 官方 Claude Code 接入文档：前三个模型字段写 deepseek-flash[1m]，Haiku 和子代理字段写 deepseek-flash。[1m] 是 Claude Code 的 1M 上下文后缀，不是另一款 DeepSeek 模型；API 正式模型名仍是 deepseek-flash，官方标注的模型上下文长度为 1M。不要把“能连通、能对话”当作配置已核对的依据。

顺带记住一条原则：工具的默认值不等于最优配置，拿到预设先回官方文档核对一遍。

CC Switch 的按钮名称可能随版本变化。本文按 v3.20.1 描述，以你看到的界面为准。

🔧 故障排除

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

macOS 配置核对（2026-10-14 国内网络实测）：启用供应商后，打开 ~/.claude/settings.json，确认 env 中的 ANTHROPIC_BASE_URL 为 https://api.deepseek.com/anthropic；主模型、Opus、Sonnet 三项均为 deepseek-flash[1m]，Haiku 和 CLAUDE_CODE_SUBAGENT_MODEL 均为 deepseek-flash。以这组字段为准，不沿用预设模型。若 1M 选项写成 [1M]，将这三项的后缀统一为小写 [1m]，保留密钥及其他设置；再次启用或切换供应商后重新核对。不要把含密钥的配置文件截图分享。

D. 验证接通

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

cd ~/agent-lab
claude

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

启动后做两个验证：

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

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

回答里应当出现 DeepSeek。

macOS 验收提示：能收到完整回复才说明对话已接通；回答自称 Claude 不能单独判定接错模型。请结合上一节的有效端点、模型字段与平台用量核对，不把自报身份当作唯一依据。

第二，回平台看用量。 打开 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 官方说明指出，Anthropic 兼容端点会把不支持的模型名自动映射到 deepseek-flash；这不是请求失败，也不能据此判断配置正确。本课本来就使用 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-flash[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-flash[1m]",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-flash[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-flash",
    "CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-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 install pandoc
pandoc --version
brew install --cask miniconda
conda init zsh

关闭终端，重新打开，再验证：

conda --version
python --version

看到各自版本号即可。conda init zsh 用于让新终端加载 Conda；安装完成后不要省略重开终端。

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

Skills 扩展包

从本院维护的 sysu-awesome-cc / skills 下载，不再使用教材旧的 Skills 包安装方式。

macOS 在终端依次运行：

cd ~/agent-lab
git clone --depth=1 https://github.com/ai-lingnan/sysu-awesome-cc.git
mkdir -p ~/.claude/skills
cp -Rn sysu-awesome-cc/skills/. ~/.claude/skills/

复制后，每个技能应位于 ~/.claude/skills/技能名/SKILL.md，不要多套一层 skills 文件夹。命令不会覆盖已有同名文件；已有旧版技能时，先备份对应目录，再更新，不要混用两套内容。退出 Claude Code 后重新启动。

下载不通时，打开仓库首页，点 Code → Download ZIP；解压后，把 skills 文件夹里的各个技能目录复制到 ~/.claude/skills/（Finder 中按 Cmd+Shift+G 可输入此路径）。

技能数量以仓库当前内容为准。复制完成只代表技能文件已安装；某些技能还需要自己的依赖或服务凭据，使用时按对应 SKILL.md 提示配置。

9. 验收

回到《环境验收清单》逐条打勾。第 7、9、10 条要在 DeepSeek 账号注册好之后才能验。

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