常见问题与排错

适用：《经济金融 AI 智能体设计与开源》第一次课现场装机 装机内容（按《手册_环境安装》顺序）：macOS 底座（Xcode 命令行工具 + Homebrew）、Node.js、Git、Claude Code（npm 安装）、DeepSeek API、CC Switch、VS Code 整理日期：2026-09-07。网络数据为当天在广州国内网络实测，校园网可能不同。

怎么用这份文档

1. 先搜报错原文。按 Ctrl+F（Mac 是 Cmd+F），把终端里报错的关键词粘进去搜，例如 not recognized、401、Retrying、粘贴。每条都尽量抄了报错原文，方便你对上号。
2. 看星号。★ 越多越常见。卡住时先看 ★★★★ 以上的条目。
3. 可以先问 AI 辅助排查。把终端里从命令到报错的整段文字复制下来，删去密钥和个人信息后，发给能使用的 AI。逐步检查建议，每一步把新的输出再发回去。
4. 复制文字，不要截图。课上接入的 DeepSeek V4-Pro 是纯文本模型，看不见图片（见 7.8）。文字比截图有效得多。
5. 部分系统或界面可能与示例不同；文中注明未实测或需要助教协助的步骤，请先联系助教确认。
6. 章节顺序与《手册_环境安装》一致：0 通用 → 1 macOS 底座（Windows 跳过）→ 2 Node.js → 3 Git → 4 Claude Code → 5 DeepSeek → 6 CC Switch → 7 接通后 → 8 VS Code。

提问模板（复制即用）

我在装 Claude Code 课程环境时遇到问题，请帮我逐步排查。
【环境】Windows 11 / macOS（版本）；Node v__；Claude Code v__；用 CC Switch 接 DeepSeek
【我想做什么】（一句话）
【报错原文】（把终端从命令到报错的整段粘在这里；先删去密钥和个人信息）
【已试过】（列出）
请：①判断是网络、权限、版本还是配置问题；②给出可直接复制的命令，分步骤；③每步可能再报错的话提前说明。

装机顺序与自检：每装完一项就在终端验证，能出版本号或进入对话框就是成功。

---

0 通用：终端、PowerShell、粘贴、重开

0.1 ★★★★★ 怎么打开终端

Windows：按 Win+X，在菜单里选「Windows PowerShell」或「终端」；或在开始菜单搜 PowerShell。开始菜单里若有两个 PowerShell，选不带 (x86) 的那个。 macOS：按 Cmd+空格，输入 Terminal，回车。

0.2 ★★★★★ 分不清 PowerShell 和 CMD，命令报 'irm' is not recognized / The token '&&' is not a valid statement separator / A parameter cannot be found that matches parameter name 'fsSL' / 'bash' is not recognized

症状：Windows 上两个黑框看着一样，粘一条命令进去就报上面某一条。 原因：复制了另一个 shell 的命令。看提示符：开头是 PS C:\Users\你的名字> 是 PowerShell；开头没有 PS、直接是 C:\Users\你的名字> 是 CMD。curl -fsSL ...、bash 是 macOS/Linux 命令，在 Windows 上都不能用。 解决：本课程 Windows 一律用 PowerShell。关掉当前窗口，按 0.1 重新打开，确认提示符带 PS 再粘命令。本手册给 Windows 的命令都是 PowerShell 写法。

0.3 ★★★★ 关掉终端重开（PATH 未生效）

症状：刚装完 Node 或 Claude Code，终端里 node -v / claude --version 提示找不到命令。 原因：安装程序已经把命令加进 PATH，但当前这个终端窗口是装之前开的，没有重新读取。 解决：关掉所有终端窗口，重新开一个再试。这是必要步骤，不是可选动作。VS Code 里的终端同理，要关掉 VS Code 重开。

0.4 ★★★★ PowerShell 里 Ctrl+V 粘不进去

症状：复制了命令或 API Key，在 PowerShell 里按 Ctrl+V 没反应。 原因：Win10 旧版 PowerShell（5.1 及更早）默认不支持 Ctrl+V。 解决：在窗口里点右键即粘贴；或用 Ctrl+Shift+V。装了 Windows Terminal（微软商店，https://apps.microsoft.com/detail/9n0dx20hk701）之后 Ctrl+V 可用。临时办法：右键标题栏 → 属性 → 选项 → 勾选「使用 Ctrl+Shift+C/V 作为复制/粘贴」。

0.5 ★★★ 输入命令后「没反应」

症状：输入 claude 回车，光标闪着不动，或者只显示了一行路径。 原因：多数时候是命令正在启动，或需要再按一次回车。 解决：先多按一次回车，等 5–10 秒。仍无反应就关掉终端重开（0.3）。

0.6 ★★★ Windows protected your PC / SmartScreen 拦截安装程序

症状：双击安装包弹出蓝色窗口「Windows 已保护你的电脑」。 原因：对未签名或不常见程序的常规提示，不是病毒。 解决：点「更多信息（More info）」→「仍要运行（Run anyway）」。

0.7 ★★ 误开了 Windows PowerShell (x86)：Claude Code does not support 32-bit Windows

症状：机器明明是 64 位，却报 32 位不支持。 原因：开始菜单里有两个 PowerShell，你开的是带 (x86) 的 32 位版本。 解决：在报错的窗口里运行 [Environment]::Is64BitOperatingSystem，返回 True 说明系统没问题。关掉这个窗口，打开不带 (x86) 的「Windows PowerShell」重来。

0.8 ★★ 安装路径或项目路径含中文

症状：各种说不清的报错，路径里有中文或空格。 原因：官方排错文档未提到中文路径会失败，缺少可靠复现依据。遇到涉及路径的报错时，需要结合具体命令排查。 解决：稳妥做法是把练习项目放在纯英文路径下，例如 C:\Users\你的英文用户名\projects\。Windows 用户名本身是中文的，暂时不用改，先装上再说，遇到问题再问助教。

0.9 ★★★ 开着代理/梯子

症状：DeepSeek 连不上、一直 Retrying、下载忽快忽慢。 原因：本次课全部走国内服务（npmmirror、DeepSeek），代理软件反而会把请求带到境外，或在长连接中途断掉（Connection closed mid-response）。 解决：装机和使用期间关掉代理软件，关掉后重开终端。

---

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

Windows 用户跳过本节。 本节命令与《手册_环境安装》第 1 节、教材 3.2 B–C 一致。

1.1 ★★★★ xcode-select --install 提示已经安装

症状：运行 xcode-select --install 后没有弹出安装对话框，而是提示命令行工具已安装（英文提示含 already installed）。 原因：这台电脑之前装过 Xcode 命令行工具。 解决：不用再装，直接进入下一步。运行 git --version，看到类似 git version 2.39.3 (Apple Git-146) 的输出就说明工具在。

1.2 ★★★ Xcode 命令行工具下载很慢或失败

症状：点「安装」后进度条长时间不动，或提示下载失败。 原因：安装包约 740 MB，从苹果服务器下载，正常要 5–20 分钟；校园网高峰期可能更慢。 解决：

1. 耐心等完 20 分钟再判断。中途不要点「获取 Xcode」，那是十几 GB 的完整 Xcode，本课程不需要。
2. 提示失败就关掉对话框，换网络（手机热点）后重新运行 xcode-select --install。
3. 卡在这一步时，先跳过去做第 5 节的 DeepSeek 注册，回头再装。

1.3 ★★★★ Homebrew 清华镜像安装脚本报错

症状：把手册里那整段（从 export HOMEBREW_BREW_GIT_REMOTE=... 到 rm -rf brew-install）粘进终端后，报 git: command not found、fatal: destination path 'brew-install' already exists，或 git clone 那一行长时间无进度。 原因：按可能性排序：

1. 还没装 Xcode 命令行工具，git clone 那行没有 git 可用。
2. 上次跑到一半中断，当前目录里留下了 brew-install 文件夹，再跑时 git clone 拒绝覆盖。
3. 复制时漏了前面几行 export，脚本没走镜像，退回去连 GitHub，国内慢。
4. 用的是官网命令 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"，它走 GitHub，课堂上多半超时。 解决：
5. 先运行 git --version 确认第 1.1 步已完成。
6. 运行 rm -rf brew-install 清掉残留。
7. 从手册重新复制整段命令（8 行都要），粘进终端一次执行。不要用官网那条 curl 命令。
8. 仍失败就把终端里从命令到报错的整段复制问 AI 或助教。

1.4 ★★★ 输密码时屏幕不显示任何字符

症状：装 Homebrew 中途要求输入密码，敲键盘却什么都不显示，以为键盘坏了。 原因：macOS 输密码时不显示星号也不显示小黑点，这是正常的安全设计。 解决：输入登录这台电脑的开机密码，敲完直接按回车。输错了会再问一次。安装软件时反复要密码也是正常的。

1.5 ★★★★★ Apple 芯片的 Mac 装完 Homebrew，brew 找不到命令：zsh: command not found: brew

症状：安装脚本已跑完，输入 brew --version 报 command not found。 原因：M1–M4 芯片的 Mac 上 Homebrew 装在 /opt/homebrew/，这个目录默认不在终端的 PATH 里。安装脚本结尾会提示要加两行配置，多数人没看到。不知道自己是什么芯片：左上角苹果图标 → 关于本机，看「芯片」一栏，显示 Apple M1/M2/M3/M4 就是 Apple 芯片。 解决：在终端运行手册里的这两行：

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

然后关掉终端重开，运行 brew --version，看到 Homebrew 4.x.x 即可。也可以运行 brew doctor，看到 Your system is ready to brew. 说明正常。Intel 芯片的 Mac 不需要这两行，找不到 brew 就先重开终端（0.3）。

1.6 ★★★ brew install 很慢或超时

症状：brew install node 或 brew install --cask visual-studio-code 卡在下载，速度只有几十 KB/s，或报连接超时。 原因：装 Homebrew 时用的镜像变量只在那一个终端窗口里有效。没把镜像写进 ~/.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

然后重跑安装命令。仍慢就检查是否开着代理（0.9）。详细说明见清华镜像帮助页 https://mirrors.tuna.tsinghua.edu.cn/help/homebrew/。

1.7 ★★ 打开下载的软件提示「无法验证开发者」/「已损坏」

症状：双击 .dmg 或应用图标，macOS 弹窗说无法打开。 原因：macOS 对非 App Store 应用的常规安全提示。 解决：打开「系统设置 → 隐私与安全性」，在「安全性」部分找到被拦截的那个应用，点「仍要打开」。CC Switch v3.20.1 已过苹果公证，一般不会弹；弹了也按这个办法处理（6.2）。

---

2 Node.js 与 npm 换源

2.1 ★★★★ Node.js 官网下载慢 / 装错版本

症状：nodejs.org 下载慢；或装成了 26.x 版本。 原因：官网在境外。当前 LTS 是 v24.20.0，Current 线是 26.x，不要装 26。 解决：用淘宝 npmmirror CDN（2026 年 9 月 7 日实测 5.2 MB/s）：

备选：中科大 https://mirrors.ustc.edu.cn/node/v24.20.0/node-v24.20.0-x64.msi。 不要用清华 TUNA：它的 Node 镜像已停止同步，v24.20.0 返回 404，网上旧教程推荐它的一律不照抄。 32 位 Windows 没有 Node 24 安装包；ARM 版 Windows 的 node-v24.20.0-arm64.msi 未经本课程实测，请联系助教确认适用版本。

2.2 ★★ Mac 要选 Intel 版还是 Apple Silicon 版

解决：不用选。Node 的 macOS .pkg 是通用包，一个文件两种芯片都能装。

2.3 ★★ 装完 Node 点 Finish 后自动弹窗装一堆东西

症状：安装最后一步之后，冒出一个窗口开始装 chocolatey、Build Tools 等。 原因：Node 安装向导可选的「自动安装必要工具」，本课程不需要。 解决：可以直接关掉那个窗口，不影响 node -v / npm -v。

2.4 ★★★★ node / npm 不是内部或外部命令，也不是可运行的程序

症状：node -v 报 'node' is not recognized ... 或「不是内部或外部命令」。 原因：多半是终端没重开（0.3）。少数是安装时没勾「Add to PATH」。 解决：

1. 关掉所有终端重开。
2. 仍不行：Windows 运行 where node（Mac 用 which node），为空说明没进 PATH，卸载 Node 重装，安装时留意 PATH 相关选项。
3. 复制报错问 AI：「帮我配置环境变量，让 node 和 npm 命令可在终端中使用」。

2.5 ★★★★★ npm 换成国内源（必做）

解决：装完 Node 后在终端运行：

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

验证：

npm config get registry

应输出 https://registry.npmmirror.com/。再跑一条同时验证网络和镜像：

npm view @anthropic-ai/claude-code version

能秒出版本号（2026 年 9 月 7 日为 2.1.263）说明通了。旧地址 registry.npm.taobao.org 早已废弃，不要用。

2.6 ★★★ npm 报 Unexpected token '<' / is not valid JSON / 一直转圈不动

症状：npm install 时报上面的错，或几分钟没有进度。 原因：npm 下载源出错，拿到的是网页而不是包信息；或源没换成功。 解决：

npm cache clean --force
npm config set registry https://registry.npmmirror.com

然后重跑安装命令。2026 年 9 月 7 日实测 registry.npmmirror.com 响应 0.10 秒，如果换源后仍卡，检查是否开着代理（0.9）。

2.7 ★★★ running scripts is disabled on this system（SecurityError / 无法加载文件 ... 因为在此系统上禁止运行脚本）

症状：PowerShell 里运行 npm 或 claude 报这条。 原因：PowerShell 执行策略拦截了 npm 生成的 .ps1 启动脚本。 解决：在 PowerShell 里运行：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

运行后没有任何输出是正常的，说明成功了。注意 RemoteSigned 和 -Scope 之间有空格，别拼成 Remotesiged。若弹出确认，输入 Y 回车。改不了策略时可改用 npm.cmd / claude.cmd 调用。

2.8 ★ 安装时出现 EBADENGINE 警告

症状：npm install -g @anthropic-ai/claude-code 过程中打印 npm WARN EBADENGINE。 原因：Claude Code 的 npm 包要求 Node 22 以上，你的 Node 低于 22。 解决：只是警告，安装照常完成，claude 照常运行。按 2.1 装 v24 就不会出现。

2.9 ★ macOS 报 EACCES: permission denied

症状：npm install -g 时报权限不足。 原因：npm 全局目录不可写。 解决：不要用 sudo npm install -g（官方明确不建议）。先把 npm config get prefix 的输出发给助教，由助教协助确认目录和 PATH 设置，再重开终端后重装。

---

3 Git

本节命令与《手册_环境安装》第 3 节、教材 3.3 C–D 一致。Git 第 3 周正式讲，今天装上就行。

3.1 ★★★★ Windows 装完 Git，'git' 不是内部或外部命令 / 'git' is not recognized

症状：安装向导已经 Finish，PowerShell 里 git --version 找不到命令。 原因：九成是 PowerShell 没重开，旧窗口没有重新读取 PATH（0.3）。少数是安装时 PATH 那一页选错了。 解决：

1. 关掉所有 PowerShell 窗口，重新开一个再输 git --version。是关掉重开，不是刷新。
2. 仍不行：重新运行安装程序，走到「Adjusting your PATH environment」那一页，确认选的是第二项「Git from the command line and also from 3rd-party software」。这一项是默认值，没改过就不会错。
3. 装完再次关掉 PowerShell 重开验证。

3.2 ★★★ 安装向导页太多，不知道该选什么

症状：Git 安装向导有十来页选项，编辑器、分支名、换行符……每页都不认识。 原因：这些选项面向开发者，本课程用默认值即可。 解决：所有选项保持默认，一路点 Next，最后 Install、Finish。弹出「用户账户控制」点「是」。唯一值得看一眼的是 PATH 那一页（3.1），默认已是正确选项。

3.3 ★★★ Git 官网下载慢或打不开

症状：git-scm.com 下载页打不开，或下载速度很慢。 原因：官网下载走境外服务器。 解决：用淘宝镜像的安装包（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

下载的文件名是 Git-2.55.0.5-64-bit.exe，双击安装（3.2）。官网 https://git-scm.com/downloads/win 能打开的话也可以用，版本号略有不同不影响。装完 git --version 显示 git version 2.5x.x 即可。

3.4 ★★★ macOS 输入 git --version 弹出对话框要求安装命令行工具

症状：Mac 上运行 git --version，没出版本号，而是弹出「需要安装命令行开发者工具」之类的对话框。 原因：macOS 的 git 由 Xcode 命令行工具提供，第 1 节没装或没装完就会弹这个。 解决：点「安装」，等它装完（5–20 分钟，见 1.2），再运行 git --version，看到类似 git version 2.39.3 (Apple Git-146) 即可。Mac 不需要单独下载 Git 安装包。

3.5 ★ 要不要现在配置 Git 用户名和邮箱

症状：网上教程说装完 Git 要先 git config，不确定今天要不要做。 解决：第 3 周之前不需要做任何配置。想先配也可以，在终端运行两条（引号里换成自己的）：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"

执行后没有输出就是成功。git config --global --list 能看到这两项。名字和邮箱中英文都行，邮箱建议用常用的，以后连 GitHub 会用到。

---

4 Claude Code 安装

4.1 ★★★★★ 不要用官方一键安装命令

症状：运行 irm https://claude.ai/install.ps1 | iex（Windows）或 curl -fsSL https://claude.ai/install.sh | bash（Mac）后：长时间无响应；Failed to fetch version from downloads.claude.ai；Could not resolve host；403；syntax error near unexpected token '<'；屏幕上出现 <!DOCTYPE html>、Just a moment...；「参数列表中缺少参量」。 原因：2026 年 9 月 7 日在广州国内网络实测，claude.ai/install.sh 与 downloads.claude.ai 不通，二进制下载源超时。这两条命令在课堂上会失败。官方文档也写明中国大陆不在支持地区名单内。 解决：不要再试这两条。改用 npm 安装（4.2）。

4.2 ★★★★★ 标准安装命令（唯一路径）

PowerShell（Windows）或终端（Mac）里运行：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

装完关掉终端重开（0.3），然后验证：

claude --version

打印形如 2.1.263 (Claude Code) 的版本号即成功。版本号迭代很快，只要是 2.1.x 就行。

网上有教程说「npm 方式已被官方废弃」「Windows 必须先装 Git Bash」，都是过时说法。npm 仍是官方列出的安装方式；Windows 上没有 Git 时 Claude Code 会改用 PowerShell 执行命令，两种都能用。

4.3 ★★★★ 'claude' is not recognized / command not found: claude

症状：装完后 claude --version 找不到命令。 原因：九成是终端没重开。少数是 npm 全局目录没进 PATH。 解决：

1. 关掉所有终端窗口重开。
2. Windows 仍不行：打开 C:\Users\<用户名>\AppData\Roaming\npm，确认里面有 claude.cmd。有的话把这个目录加入用户 PATH：此电脑 → 属性 → 高级系统设置 → 环境变量 → 用户变量 Path → 新建 → 粘贴路径。然后关闭所有 PowerShell 重开。
3. Mac 仍不行：把报错和 npm config get prefix 的输出一起发给助教，确认适合当前系统的修复步骤。
4. 如果你是 VS Code 扩展用户，见 8.4。

4.4 ★★★ 输入 claude 后要求登录 / 跳转到浏览器 / Not logged in. Please run /login

症状：第一次运行 claude，让你选主题之后要登录 Claude 账号，或跳出浏览器网页。 原因：这是 Claude 官方账号入口，本课程不走它。免费的 Claude.ai 账号不含 Claude Code 权限，付费订阅在国内也无法直接用。 解决：按 Ctrl+C 退出。先去第 5、6 节把 DeepSeek 和 CC Switch 配好，再回来运行 claude。配好后不会再弹登录；如果还弹，说明 CC Switch 没生效（6.7）。

4.5 ★★ 启动时卡在连接 api.anthropic.com 或登录校验

症状：DeepSeek 已配好，claude 启动时仍尝试连 api.anthropic.com 报错。 原因：部分接入配置涉及 ~/.claude.json（注意是家目录下的文件，不在 .claude/ 文件夹里）的 "hasCompletedOnboarding": true 设置。是否需要手动调整取决于当前安装状态，请由助教检查。 解决：先重开终端再试；仍不行找助教，助教会帮你改这个文件。不要自己动手改 JSON，改坏了 Claude Code 起不来（见 7.13）。

4.6 ★★★ Do you trust the files in this folder?

症状：进入对话前弹出这个问题。 原因：Claude Code 会读写当前文件夹里的文件，先问一次授权。 解决：确认当前文件夹是自己的课程工作区后，选「Yes, proceed」。如果再次出现，先核对文件夹路径，再决定是否授权。

4.7 ★★ claude 打开的是 Claude 桌面应用，不是终端程序

症状：输入 claude 弹出一个图形界面应用。 原因：旧版 Claude Desktop 在系统目录注册了一个 Claude.exe，PATH 优先级更高。 解决：把 Claude Desktop 更新到最新版，或先卸载它，本课程不需要桌面版。

4.8 ★ Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

症状：启动时报这条。 原因：PowerShell 和 Git Bash 都找不到。正常 Windows 10/11 自带 PowerShell，很少出现。 解决：按 0.1 用 PowerShell 启动；仍报错就复制报错问 AI。

4.9 ★★ 装到一半坏了，怎么从头重装

解决：Windows 以管理员身份打开 PowerShell，依次运行：

Get-Process claude,node -ErrorAction SilentlyContinue | Stop-Process -Force
npm uninstall -g @anthropic-ai/claude-code
Remove-Item "$env:APPDATA\npm\node_modules\@anthropic-ai\claude-code" -Recurse -Force -ErrorAction SilentlyContinue
npm cache clean --force
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

macOS 不运行上述 PowerShell 命令；如需重装，请联系助教确认适合当前安装方式的步骤。

4.10 ★ 安装路径报错

症状：安装或运行时报错，报错信息里出现带中文的路径。 解决：见 0.8。

---

5 DeepSeek 注册、充值、Key

5.1 ★★★★ 注册与实名

平台地址：https://platform.deepseek.com。 流程：按开放平台页面提供的方式注册或登录，并按提示完成实名认证。遇到困难可先完成软件安装，再处理账号。 打开页面报 429 / 请求过于频繁：同一网络出口短时间访问太多，等一两分钟，或用手机热点打开。

5.2 ★★★★ 我有 DeepSeek 网页版账号，还要 API Key 吗

要。网页版聊天和 API 是两套东西。Claude Code 用的是 API Key，按 token 计费，需要单独充值。会员或网页版余额不能用在这里。

5.3 ★★★ 充值多少、怎么付

解决：在平台充值页查看可选支付方式，按自己的预算小额充值，再根据平台显示的实际消耗补充。套餐与单价见《模型平台套餐与官方链接》。 最低充值金额和新用户赠送额度以账户页面为准，不要把赠送额度视为固定可用预算。 价格提醒：DeepSeek 按峰谷计价，北京时间周一至周五 9:00–12:00、14:00–18:00 是高峰，单价是其他时段的两倍。作业尽量放晚上或周末做。

5.4 ★★★★★ 创建 API Key，且它只显示一次

位置：https://platform.deepseek.com/api_keys。 步骤：进入「API keys」，按页面提示创建密钥；按钮名称以当前页面为准。 坑：Key 以 sk- 开头，只在创建时完整显示这一次，关掉窗口就再也看不到。 解决：先打开记事本，再点创建，立刻把 Key 粘到记事本里。丢了就删掉这个 Key 重新建一个，旧的作废。

5.5 ★★★ Key 粘不进 CC Switch 或终端

解决：在网页上点 Key 旁边的复制小图标，不要手动选中复制（容易少字符）。终端里粘贴见 0.4。粘完检查开头是 sk-、末尾没有多余空格。

5.6 ★★★ Key 保密

原因：Key 是明文存在 ~/.claude/settings.json 里的。谁拿到 Key 谁就能花你的钱。 解决：不要发到群里、不要截图发别人、不要提交到 GitHub。怀疑泄露就到平台删掉重建。有条件的话在平台开余额预警。

---

6 CC Switch

6.1 ★★★★★ 安装包从哪里拿：飞书群，不要自己去 GitHub

症状：GitHub Releases 页面下载几乎不动。 原因：2026 年 9 月 7 日实测 GitHub Release 下载只有 53 KB/s，100 人同时下会有人失败。 解决：老师在飞书群里发安装包。文件名：Windows 是 CC-Switch-v3.20.1-Windows.msi，Mac 是 CC-Switch-v3.20.1-macOS.dmg。

要自己下的话，只认两个官方入口：https://github.com/farion1231/cc-switch/releases 和 https://ccswitch.io。CC Switch 是免费开源软件，任何要你付费、充值或输入账号密码的「CC Switch」网站都是假冒。

6.2 ★★ 安装时被拦截

Windows：可能被 SmartScreen 拦一下，点「更多信息」→「仍要运行」（0.6）。 macOS：v3.20.1 已通过苹果签名和公证，双击即可打开。网上旧教程说会提示「未知开发者」是旧版本的情况。真弹了按 1.7 处理。

6.3 ★★★★★ 在 CC Switch 里接 DeepSeek 的步骤

按钮名称与位置可能随版本变化，以当前界面及课堂演示为准。操作流程：

1. 打开 CC Switch，顶部应用栏选 Claude Code。
2. 点右上角「+」（添加供应商），在预设供应商列表里选 DeepSeek。不要选 default。
3. 把你的 DeepSeek API Key（sk- 开头，见 5.4）粘进 API Key 框。
4. 把模型名改成带 [1m] 的版本（见 6.4，这一步预设是错的）。
5. 点「启用」。
6. 打开一个新终端，输入 claude，说「你好」，有回复且没让登录即成功。

6.4 ★★★★ 隐性坑：预设模型名缺 [1m]，上下文被砍短但不报错

症状：能正常对话，但很快提示上下文满、要压缩，或长任务做到一半忘了前面。不报任何错。 原因：CC Switch 内置 DeepSeek 预设写的模型名是 deepseek-v4-pro，DeepSeek 官方文档给 Claude Code 用的是 deepseek-v4-pro[1m]。[1m] 后缀表示请求 1M 上下文版本，不加就只有默认大小。 解决：在 CC Switch 的 DeepSeek 供应商配置里，把三个字段手动改成：

改完重新点「启用」，模型名以 DeepSeek 官方接入文档为准。

6.5 ★★ 模型名大小写

症状：CC Switch 启用后连接一直报错。 原因：从网页复制的模型名可能被改成全小写或多了空格，与服务端不匹配。 解决：逐字核对 deepseek-v4-pro[1m] 和 deepseek-v4-flash，重新生成 Key 再试一次。老版本 CC Switch 卸载后装 v3.20.1。

6.6 ★★ 点「打开终端」一直让选文件夹

解决：不需要通过 CC Switch 启动终端。配好并「启用」后，直接按 0.1 打开 PowerShell/终端输入 claude。CC Switch 只是配置管理器。

6.7 ★★★★ 启用了，但 claude 还是弹登录 / 还是连不上

症状：CC Switch 显示已启用 DeepSeek，终端里 claude 仍要求登录，或报 401。 原因：CC Switch 没写进配置，或者配置被别的东西覆盖了（7.2）。 解决：

1. 关掉终端重开再试。
2. 打开 ~/.claude/settings.json（Windows 在 C:\Users\<用户名>\.claude\settings.json），看 env 块里是否有 ANTHROPIC_BASE_URL 为 https://api.deepseek.com/anthropic、ANTHROPIC_AUTH_TOKEN 为你的 Key。没有就回 CC Switch 重新点「启用」。
3. 有 ANTHROPIC_API_KEY 这一项的话，见 7.2。
4. 在 claude 会话里输入 /status，看当前生效的 Base URL 和模型。

6.8 ★ 「未找到可用的模型列表端点，请检查 Base URL」

症状：保存供应商时弹这个警告。 原因：CC Switch 保存时会探测 /v1/models 接口，有些端点不提供。阿里云百炼文档明确说这个提示可以忽略；DeepSeek 预设自带模型列表地址，一般不出现。 解决：忽略，直接启用测试。

6.9 ★ CC Switch 到底改了什么

它把供应商配置写进 ~/.claude/settings.json 的 env 块，自己的数据存在 ~/.cc-switch/（数据库、自动备份）。不设系统环境变量。所以不装 CC Switch、手写这个文件也能达到同样效果——但对无编程基础的同学，点按钮比改 JSON 稳。

---

7 接通后的问题

7.1 ★★★★ 401 / Authentication Fails, Your api key: ****xxxx is invalid / authentication_error

症状：claude 里发消息后报 401。 原因：按可能性排序：Key 复制不全或有空格；Key 已在平台删除；填错字段（用了 ANTHROPIC_API_KEY 而不是 ANTHROPIC_AUTH_TOKEN）；旧配置残留把新配置盖掉了（7.2）。 解决：

1. 回 CC Switch 重新粘一遍 Key，点「启用」，重开终端。
2. 到 https://platform.deepseek.com/api_keys 确认这个 Key 还在。
3. 打开 ~/.claude/settings.json 检查 env 块，认证字段必须是 ANTHROPIC_AUTH_TOKEN。
4. 仍 401 就删 Key 重建。

7.2 ★★★★ 隐性坑：settings.json 里的 env 会覆盖终端设的变量；ANTHROPIC_API_KEY 压过一切

症状：照着教程在终端里 export 或 $env: 设了变量，claude 却像没看见一样；或者明明配了 DeepSeek，却在连别的地方。 原因：Claude Code 读配置的规则是：~/.claude/settings.json 的 env 块优先于终端环境变量，同名时以文件为准。另外只要设了 ANTHROPIC_API_KEY（不论在文件还是终端），它会压过其他认证方式。之前装过别的教程、用过别的模型的电脑，最容易留下这种残留。 解决：

1. 打开 ~/.claude/settings.json，env 块里只保留 CC Switch 写的 DeepSeek 那几项。看到 ANTHROPIC_API_KEY 就删掉这一行，认证字段用 ANTHROPIC_AUTH_TOKEN。
2. 改完重开终端，claude 里输入 /status 确认 Base URL 是 https://api.deepseek.com/anthropic。
3. 自己不敢改 JSON 的，让助教改；改坏了见 7.13。
4. 终端里之前 export 过的变量，文件里设成空字符串 "" 可以让它失效（无法通过文件直接删除终端变量）。

7.3 ★★★★ 隐性坑：昨天能用，今天打开又要登录 / 又连不上

症状：上次课配好了，重启电脑或换个终端窗口后 claude 又弹登录或报 401。 原因：如果上次是在 PowerShell 里用 $env:ANTHROPIC_BASE_URL=... 这类命令配的，$env: 只在当前窗口有效，关掉窗口配置就没了。Mac 的 export 同理。 解决：正解是把配置写进 ~/.claude/settings.json，这样每次启动都生效。CC Switch 干的就是这件事，所以本课程用 CC Switch 配，不在终端里手敲变量。已经在终端里设过的，去 CC Switch 点一次「启用」即可覆盖。

7.4 ★★★ 一直 Retrying... / 403 / Your API key has expired

解决：逐项排查：

1. 确认用的是自己创建的真实 Key（不是教程里的示例 Key），账户有余额。到 DeepSeek 平台看余额和用量。
2. 关掉代理/梯子，重开终端（0.9）。
3. 在 CC Switch 里核对 Key、Base URL、模型名。
4. 换网络（手机热点）试一次，排除校园网问题。

7.5 ★★ 429 / 限流 / 请求过于频繁

症状：发消息后报 429 或 rate limit 相关文字。 原因：可能触发并发或账户速率限制；具体额度与恢复时间以平台提示为准。 解决：等几十秒重试。反复出现就把主模型临时换成 deepseek-v4-flash（在 CC Switch 里改 ANTHROPIC_MODEL）。

7.6 ★★★ 模型名写错：deepseek-chat ... may not exist，或者「模型好笨」但不报错

症状：报模型不存在；或者没报错，但回答质量明显差。 原因：deepseek-chat 是已停用的旧名字。更隐蔽的是：DeepSeek 端点收到不认识的模型名时不报错，静默降级到 deepseek-v4-flash。 解决：模型名只有两个合法值：主模型 deepseek-v4-pro[1m]，Haiku 槽位与子智能体 deepseek-v4-flash。在 CC Switch 里逐字核对（6.4），在 claude 里输入 /status 查看当前模型。

7.7 ★★★ 上下文很快就满 / 频繁提示压缩

原因：最常见是缺 [1m] 后缀（6.4）。其次是对话太长。 解决：先按 6.4 改模型名。日常用法：换一个任务就输入 /clear 清空重来；同一任务想继续但快满了，用 /compact 压缩，它会保留关键信息和计划。上下文越长，每一轮重发的 token 越多，费用也越高，勤 /clear 省钱。

7.8 ★★★ 把截图发给它，它说看不见 / 回答文不对题

症状：粘贴截图或图片路径，模型回复像没收到图。 原因：DeepSeek V4-Pro 是纯文本模型，Claude Code 发图片时它只收到一个 [Image #1] 占位符。 解决：把报错文字复制进去，不要截图。要让 AI 看某个文件，直接告诉它文件路径让它自己读。

7.9 ★★ API Error 400 ... unknown variant 'system'

症状：发消息后报 400，报错里有 unknown variant 'system'。 原因：可能与模型端点和工具版本之间的消息格式兼容性有关，需要结合当前版本排查。 解决：先运行 claude --version 记下版本，把报错和版本号发给助教，确认后再调整版本。

7.10 ★★ 长任务超时 / Connection closed mid-response

原因：复杂任务响应时间长；代理软件会在中途掐断长连接。 解决：检查代理与网络设置（0.9）。把任务拆小、分阶段做；仍超时请联系助教。

7.11 ★★★ 每做一步都问我 Yes/No

症状：Claude Code 改文件、跑命令前都要我确认。 原因：第一次会话的默认权限模式，正常现象。每次都问是为了让你看到它在做什么。 解决：选 Yes 继续。按 Shift+Tab 可切换权限模式。不要用 --dangerously-skip-permissions 或 bypassPermissions 模式，零基础加绕过所有确认等于事故。

7.12 ★★ 我在用哪个模型、哪个 Key？怎么确认

解决：在 claude 会话里输入 /status，能看到当前的 Base URL、模型和加载了哪些设置文件。在普通终端（不是 claude 里面）运行 claude doctor，会列出安装健康状况和设置文件里被拒绝的配置项。

7.13 ★★ 改了 settings.json 之后 Claude Code 起不来 / Settings Error

症状：手改配置文件后启动报错。 原因：设置文件是严格 JSON：不能写 // 注释，最后一项后面不能有逗号，引号必须成对。 解决：先把 API Key 等敏感值替换为占位符，再把配置内容和报错发给 AI 检查 JSON 语法；不确定时请助教协助。也可以回 CC Switch 重新点「启用」，再检查配置是否恢复。

7.14 ★ 终端里中文乱码

解决：多数是终端窗口尺寸或字体渲染问题，拖大窗口或重开终端。反复出现的话装 Windows Terminal（0.4）。

7.15 ★ 报错手册里没有

按文档开头的提问模板问 AI。三轮之内还没解决，精简成一句话（系统 + 做什么 + 报什么错 + 已试什么）发群里或找助教。

---

8 VS Code

8.1 ★★★ 官网下载慢或打不开

症状：code.visualstudio.com 下载按钮点了没反应，或速度很慢。 原因：偶发。2026 年 9 月 7 日实测官方下载链路（vscode.download.prss.microsoft.com）在国内 23 MB/s，正常情况下不需要镜像。 解决：用下面的直链，它们永远指向最新稳定版：

网上流传的「把域名换成 vscode.cdn.azure.cn」技巧，在 2026 年 9 月 7 日实测已不可用，不要照抄。实在下不动，向老师要安装包。

8.2 ★★ 已经装过 VS Code，要不要重装

解决：不用删，直接升级：菜单「帮助 → 检查更新」。VS Code 通常会自动更新。

8.3 ★★ 扩展安装失败、一直转圈或超时

症状：扩展面板（Ctrl+Shift+X，Mac 是 Cmd+Shift+X）点 Install 后卡住。 原因：扩展市场在国内能连上但慢，100 人同时装同一个扩展容易超时。 解决：

1. 等一会儿再点一次；完整退出 VS Code 再开。
2. Windows 上右键 VS Code 图标 →「以管理员身份运行」再装。
3. 仍失败：进入 C:\Users\用户名\.vscode\extensions\，删除 .obsolete 文件和对应扩展的残留文件夹后重试。
4. 离线安装：向老师要 .vsix 文件，扩展面板右上角「…」→「Install from VSIX...」选文件；或在终端运行 code --install-extension 文件路径.vsix。 中文语言包直链：https://marketplace.visualstudio.com/_apis/public/gallery/publishers/MS-CEINTL/vsextensions/vscode-language-pack-zh-hans/latest/vspackage 注意：下载到的文件是 gzip 压缩过的，多数情况 VS Code 能直接装；报错的话需要先解压一次再改回 .vsix 后缀。

8.4 ★★★ 装了 VS Code 的 Claude Code 扩展，终端里却 claude 不存在

症状：扩展面板里能看到 Claude Code 聊天面板，但在终端输入 claude 报找不到命令。 原因：扩展自带一份私有 CLI 供聊天面板使用，不会加入 PATH。终端里要用 claude，必须另外用 npm 装 CLI（第 4 节）。 解决：按第 4 节装 CLI。两者共用同一份 ~/.claude/settings.json，所以 CC Switch 配好 DeepSeek 后扩展和终端都能用。

8.5 ★★ VS Code 里的 Claude Code 扩展一直要求登录

症状：终端里的 claude 已接上 DeepSeek，但 VS Code 扩展面板还是弹「Sign in」。 原因：扩展面板走的是 Claude 官方账号登录；本课程不登录官方账号。如果你是在终端里用 $env: 临时设的变量，VS Code 不会继承。 解决：本周只用终端里的 claude，不用扩展的聊天面板。配置写进 settings.json（CC Switch 干的就是这事）之后，两边共用；仍弹登录就从终端用 code . 启动 VS Code 再试。