环境安装手册

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

本页分三部分：第一部分 Windows，第二部分 macOS，各自从头装到尾，只看自己系统的那一部分；第三部分是两个系统相同的步骤（接入 DeepSeek、验证接通、在 VS Code 里用 Claude Code、Skills 检查、验收），装完自己系统的部分后接着做。两段安装视频分别放在各自系统的部分里。

装什么，按什么顺序

顺序有讲究：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 下。

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

开始之前

加入课程群

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

终端

后面所有命令都在终端里敲，怎么打开终端见自己系统那一部分的第 1 步。

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

第一部分 · Windows

Windows 安装全流程视频（约 22 分 40 秒），Miniconda、Pandoc、Skills 也演示了一遍。视频里接入 DeepSeek 的操作紧跟在 CC Switch 安装之后，对应本页第三部分 A–D。命令以本页文字为准，从页面复制。下表的时间点会打开视频对应位置，不是同页播放器内跳转。

1. 打开 PowerShell，建工作文件夹

开始菜单搜 PowerShell，打开。不要用 CMD（命令提示符），也不要用 PowerShell (x86)。看到 PS C:\Users\你的名字> 就对了。

以后这门课的东西都放一个地方。

先看提示符里的路径。如果显示的是 PS C:\WINDOWS\system32> 而不是 PS C:\Users\你的名字>，先运行这一条回到自己的用户目录：

cd $HOME

然后在终端里：

mkdir agent-lab

它建在 C:\Users\你的名字\agent-lab。

2. Node.js 和 npm

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

安装

从淘宝镜像下载（当前长期支持版 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。

验证

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

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

从淘宝镜像下载安装包（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（页数多，别改任何一项）。

验证

关掉终端重新打开：

git --version

看到 git version 2.5x.x 即可。装好后不需要额外配置。

4. Claude Code

在 PowerShell 里用 npm 全局安装：

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

一两分钟。看到一堆滚动的输出最后没有红字 ERR、回到 PS 提示符，就是装好了。

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

🔧 故障排除

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

验证

再次关掉终端重新打开：

claude --version

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

5. CC Switch

安装包在课程群里，Windows 是 CC-Switch-v3.20.1-Windows.msi（12.9 MB）。CC Switch 是什么、拿不到群里的安装包时从哪下载、怎样识别假冒站点，见第三部分 B。

双击 .msi。欢迎页 Next，安装位置保留默认再 Next，点 Install；Windows 询问是否允许更改时点「是」。完成页保留启动 CC Switch 的勾，点 Finish，软件会打开。以后从开始菜单里找 CC Switch。

6. VS Code

官网 https://code.visualstudio.com 点 Download for Windows，下载完双击安装包。

1. 许可协议选「我同意此协议」，下一步；安装位置、开始菜单文件夹保留默认。
2. 「选择附加任务」页：两项「将"通过 Code 打开"操作添加到 Windows 资源管理器……上下文菜单」都勾上；「将 Code 注册为受支持的文件类型的编辑器」和「添加到 PATH」保持勾选；桌面快捷方式随意。
3. 新版多一页 GitHub Copilot CLI，选 Don't add the copilot command（本课用 Claude Code），下一步。
4. 点安装，完成后保留运行 VS Code 的勾，点完成。
5. 欢迎页邀请登录 Copilot 时，点 Continue without Signing In，不用登录；主题随意，点 Get Started。

以后在 VS Code 里打开 agent-lab 时（用法见第三部分 F），顶部可能出现 Restricted Mode（受限模式）提示条：点提示条里的 Manage，核对路径是自己刚建的文件夹，点 Trust，终端才能正常使用。别人发来的项目先检查内容再决定是否信任。窗口较窄、菜单栏放不下时，Terminal 菜单收在菜单栏末尾的 … 里。

7. Miniconda

Python 环境。教材 3.3 有截图。

下载：打开 https://www.anaconda.com/download（教材里的旧文档网址现在会跳到新的介绍页，从那里点下载链接也是到这一页），在 Anaconda Distribution 那张卡片下点小字 Skip to download，跳过注册进入下载页。在 Windows 标签下看右边的 Miniconda，点 Windows 64-Bit (x86_64) Graphical Installer。

官方下载太慢时换清华镜像：打开 https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/，按 Ctrl+F 搜索并下载 Miniconda3-latest-Windows-x86_64.exe。不要选成 ARM、32 位（x86 不带 _64）或 Linux、MacOSX 的文件。

中文 Windows 的编码设置：中文系统上安装器可能因为编码问题报错（报错里常见 encoding、codec、gbk 等字样）。可以安装前先做这一步，也可以报错后再做，然后重新双击安装包：

1. 开始菜单搜索「环境变量」，点 编辑帐户的环境变量。
2. 在上方「用户变量」里点 新建，变量名填 PYTHONUTF8（全大写、无空格），变量值填 1。
3. 点确定，再点确定保存。

这是当前用户的设置，此后这个用户运行的 Python 默认用 UTF-8 读写文件。

安装向导：双击安装包。

1. 欢迎页 Next，许可协议点 I Agree。
2. 安装范围选 Just Me，Next。
3. 安装位置保留默认的 C:\Users\你的名字\miniconda3，Next。
4. Advanced Installation Options 页：不勾 Add installation to my PATH environment variable；Create shortcuts 保持勾选；勾上 Register Miniconda3 as my default Python；Clear the package cache 保留默认不勾。点 Install。
5. 完成页取消两个打开网页的勾，点 Finish。

首次初始化：因为没有加入 PATH，第一次直接输入 conda init 会找不到命令，要写出程序的完整位置。在 PowerShell 里整行复制运行（开头的 & 保留）：

& "$HOME\miniconda3\Scripts\conda.exe" init powershell

等它输出完、回到 PS 提示符，再关掉终端重新打开，验证：

conda --version
python --version

两个都有版本号就装好了。新终端若提示「禁止运行脚本」，按第 2 步故障排除里的 Set-ExecutionPolicy 处理后再重开。

8. Pandoc

文档转换。教材 3.3 有截图。

下载：打开官方安装页 https://pandoc.org/installing.html，在 Windows 一段点下载链接，会跳到 GitHub 发布页；选 Windows 64 位的 .msi 安装包（如 pandoc-3.13-windows-x86_64.msi，约 40 MB，版本号以发布页为准）。

GitHub 下载很慢时，可以用下载加速页：在 .msi 链接上点右键选「复制链接」，打开 https://ghfast.top，把链接粘贴进输入框，点「下载」。这是第三方加速服务，地址可能失效；打不开就回到官方链接等它下完，或在课程群里要安装包。

安装：双击 .msi。新版向导把选项集中在一页：勾选 I accept the terms in the License Agreement；不勾 Install for all users of this machine（给当前用户安装，不需要管理员权限）；点 Install，完成后点 Finish。没有逐页 Next 和选安装位置的步骤。

关掉旧终端，打开新的 PowerShell 验证：

pandoc --version

9. Skills 扩展包

技能来源与装好后的检查见第三部分 G。

用 ZIP 和资源管理器安装：

1. 打开仓库首页 https://github.com/ai-lingnan/sysu-awesome-cc，点 Code → Download ZIP。
2. 在下载文件夹里右键压缩包，选「全部解压缩」，位置保留默认，「完成时显示提取的文件」保持勾选，点「提取」。
3. 进入解压出的 sysu-awesome-cc-main 文件夹（里面可能还有一层同名文件夹），打开 skills。按 Ctrl+A 全选里面的各个技能目录，Ctrl+C 复制。
4. 按 Ctrl+N 另开一个资源管理器窗口，在地址栏输入 %USERPROFILE%\.claude，回车。
5. 这里还没有 skills 文件夹时，按 Ctrl+Shift+N 新建一个，名字填 skills。
6. 打开这个 skills，按 Ctrl+V 粘贴。

完成后的层级是 C:\Users\你的名字\.claude\skills\技能名\SKILL.md，不要把整个 skills 文件夹再套进去；已有同名技能时先备份再更新。

Windows 部分到这里装完。接着做第三部分：接入 DeepSeek、验证接通、验收。

第二部分 · macOS

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

1. 打开终端，建工作文件夹

启动台搜 终端（Terminal），打开。看到 你的名字@MacBook ~ % 就对了。

以后这门课的东西都放一个地方。

终端里：

mkdir agent-lab

它建在 /Users/你的名字/agent-lab。

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

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，不要求与示例版本完全相同。镜像缺少个别软件包时，安装器可能从官方地址下载；设置了镜像不代表每个文件都来自镜像。

3. Node.js 和 npm

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

安装

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。能正常输出版本号即可，不要为了匹配上面的示例版本降级。

换国内源

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，装的时候看清那个勾。

4. Git

Git 记录文件的每一次修改，改坏了能退回去。

第 2 步装 Xcode 命令行工具时已经装好了，不用另装。

验证

关掉终端重新打开：

git --version

看到 git version 2.5x.x 即可。装好后不需要额外配置。

5. Claude Code

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

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

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

🔧 故障排除

• 卡在下载不动：确认第 3 步的换源做了，npm config get registry 应显示淘宝地址。
• 装完运行 claude 报错：多半是安装时少了 --allow-scripts=@anthropic-ai/claude-code。用上面的完整命令重装一次，关掉终端重新打开再试。
• macOS 报 EACCES: permission denied：用 brew 装的 Node 一般不会出现；出现了按《常见问题》2.9 处理，不要加 sudo。

验证

再次关掉终端重新打开：

claude --version

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

6. CC Switch

安装包在课程群里，macOS 是 CC-Switch-v3.20.1-macOS.dmg（26.8 MB）。CC Switch 是什么、拿不到群里的安装包时从哪下载、怎样识别假冒站点，见第三部分 B。

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

🔧 故障排除

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

7. VS Code

brew install --cask visual-studio-code

8. Pandoc 与 Miniconda

Pandoc 做文档转换，Miniconda 管 Python 环境。教材 3.2 D 有说明。

按下面顺序安装：

brew install pandoc
pandoc --version
brew install --cask miniconda
conda init zsh

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

conda --version
python --version

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

9. Skills 扩展包

技能来源与装好后的检查见第三部分 G。

在终端依次运行：

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 文件夹。命令不会覆盖已有同名文件；已有旧版技能时，先备份对应目录，再更新，不要混用两套内容。

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

macOS 部分到这里装完。接着做第三部分：接入 DeepSeek、验证接通、验收。

第三部分 · 两个系统共同的步骤

前两部分装完后从这里接着做。下面的操作两个系统相同；配置核对的命令不同，在 C 里分 Windows、macOS 两小段。

接入 DeepSeek：为什么、分几步

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 日发布），课程群里发的也是这一版：

官网首页现在展示的是 4.0 系列，界面和本手册不同。拿不到群里的安装包、要自己下载时，打开 v3.20.1 的官方发布页 https://github.com/farion1231/cc-switch/releases/tag/v3.20.1，在 Assets（下载文件列表）里选上表对应的文件；Windows 选 .msi，不要点成 ARM 版、便携版或源代码。

⚠️ 安全提示

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

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 示例补齐。v3.20.1 里这一步在「模型映射」表：左边是显示名称，右边一列「实际请求模型」才是发给 DeepSeek 的模型名，改右列。Sonnet、Opus、Haiku、Subagent 和下方的「默认兜底模型」都改成 Flash，表里多出的 Fable 一行也统一用 Flash。这个界面不一定保留粘贴进去的 [1m] 后缀，启用后按下面的「Windows 配置核对」或「macOS 配置核对」看生效文件，缺了就补上

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]，保留密钥及其他设置；再次启用或切换供应商后重新核对。不要把含密钥的配置文件截图分享。

Windows 配置核对：启用供应商后打开 PowerShell，逐行运行下面三条，读出生效配置里的地址和模型字段（文件里有密钥，不要用 Get-Content 把全文打印出来）：

$p = "$HOME\.claude\settings.json"
$c = Get-Content $p -Raw -Encoding UTF8 | ConvertFrom-Json
$c.env | Select-Object ANTHROPIC_BASE_URL,ANTHROPIC_MODEL,ANTHROPIC_DEFAULT_OPUS_MODEL,ANTHROPIC_DEFAULT_SONNET_MODEL,ANTHROPIC_DEFAULT_HAIKU_MODEL,CLAUDE_CODE_SUBAGENT_MODEL

应当看到地址 https://api.deepseek.com/anthropic；ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_SONNET_MODEL 三项为 deepseek-flash[1m]，Haiku 和 CLAUDE_CODE_SUBAGENT_MODEL 为 deepseek-flash。前三项缺 [1m] 后缀时，在同一个窗口接着运行（m 是小写，每条整行复制）：

$c.env.ANTHROPIC_MODEL = 'deepseek-flash[1m]'
$c.env.ANTHROPIC_DEFAULT_OPUS_MODEL = 'deepseek-flash[1m]'
$c.env.ANTHROPIC_DEFAULT_SONNET_MODEL = 'deepseek-flash[1m]'
$json = $c | ConvertTo-Json -Depth 20
[IO.File]::WriteAllText($p,$json,[Text.UTF8Encoding]::new($false))

最后一条把修改写回原文件，密钥和其他设置保留。再运行一次上面第二、三条命令，从文件重新读取核对。改某一项时若提示找不到该属性，说明这个字段没写进文件，改用 VS Code 打开 C:\Users\你的名字\.claude\settings.json，对照本部分 E 的示例补齐。以后在 CC Switch 里切换或重新启用供应商，它会重写这个文件，需要再核对一次。

D. 验证接通

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

cd ~/agent-lab
claude

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

第一次启动时，Claude Code 会先让你选界面主题、看安全说明，再问是否信任当前文件夹。核对显示的路径是自己的 agent-lab，选 Yes 继续。

启动后做两个验证：

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

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

能收到完整回复，说明对话已接通。回答可能自称 DeepSeek，也可能自称 Claude，自报身份不能用来判断接没接对：Windows 和 macOS 都要结合上一节核对过的生效端点、模型字段，以及下面的平台用量一起看。

第二，回平台看用量。 打开 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 每次点「启用」时在做什么。两种方式底层是同一件事。

F. 在 VS Code 里用 Claude Code

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

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

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

G. Skills 扩展包：来源与检查

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

按自己系统那一部分的第 9 步复制好技能文件后，退出 Claude Code，在 agent-lab 里重新运行 claude，输入 /skills 回车，能看到技能列表就装好了。

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

H. 验收

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

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