Claude Code 常见排障合集（中国网络环境）

本 skill 帮助在中国大陆或受限网络下使用 Claude Code 终端 CLI 的用户，按"先定位、再修复"的顺序解决常见问题。面向非技术用户：解释要用大白话、给出可直接复制粘贴的命令、一次只让用户做一两步、多让用户截图确认现状。

核心心智模型（务必先理解，否则会反复绕圈）

绝大多数 Claude Code 在中国网络下的问题，根源都是同一件事：

终端 / Electron 应用不会自动继承系统代理。
浏览器能打开 claude.ai ≠ 终端也走了代理。

由此衍生出几乎所有症状：

• 终端请求绕过代理 → 撞上区域限制 → 403 Request not allowed
• 登录授权回调那一秒走不通 → OAuth error / "克洛德很快就会回来"中断页
• 代理只在当前窗口的 export 里 → 一关窗口就失效 → 新窗口又 403 → 以为"要重新登录"

因此排障的黄金顺序永远是：先确认终端是否真的走了代理，再谈登录。 不要一上来就反复 /login，那只会浪费时间。

触发时的第一步：先做"体检"，不要急着操作

当用户报告任何登录 / 403 / 授权问题时，先让 TA 在终端跑这一行（不要先 /login）：

echo "代理变量:" && echo "$HTTPS_PROXY" && curl -s -o /dev/null -w "直连状态码: %{http_code}\n" https://api.anthropic.com/v1/models

根据输出判断走哪条分支：

代理变量	状态码	含义	去哪修
空	403	终端没走代理，被区域挡	→ A. 配置代理
有值	401 或 200	代理通了（401 是正常的，只是没带凭证）	→ B. 登录
有值	403	节点不对 / 代理没真生效	→ A. 检查节点和全局模式
任意	000 / 卡住	端口错或代理没开	→ A. 查端口、开代理

关键认知：401 = 好消息（代理已通），403 = 被挡（代理没生效或区域不对）。很多用户会被 401 吓到，要主动安抚。

详细的分模块步骤见下面，以及 references/ 目录里的专题文档。

---

A. 代理配置问题（最常见的根因）

详见 references/proxy-setup.md。要点速览：

1. 节点要选支持地区：美国 / 香港 / 日本 / 新加坡。绝不要用中国大陆节点——那是 403 的根源。
2. 必须开"系统代理 / 全局模式"：只开代理 App 本身不够，浏览器和终端不会自动走。规则模式可能把 claude 域名分流走直连，反复失败时切到全局模式往往一次解决。
3. 查到代理端口（Clash 常见 7890，小云朵常见 7892，以实际为准）。查不到就让用户在代理工具的"端口设置 / 基本配置"里找，或用脚本探测（见 reference）。
4. 在当前终端窗口设代理（端口换成用户实际的）：

   export HTTPS_PROXY=http://127.0.0.1:7892
   export HTTP_PROXY=http://127.0.0.1:7892

5. 当场验证：

   curl -s -o /dev/null -w "走代理状态码: %{http_code}\n" https://api.anthropic.com/v1/models

   出现 401 / 200 → 通了，去登录。还是 403 → 切全局模式 / 换节点再试。

注意：Claude Code 只支持 HTTP/HTTPS 代理，不支持 SOCKS。改完环境变量要在同一个窗口继续操作，不要换窗口、不要关窗口。

---

B. 登录与授权问题

详见 references/login-oauth.md。要点速览：

1. 确认代理已通（A 做完）后，再在同一窗口：claude → /login → 选 第 1 个 Claude account with subscription（Pro/Max/Team/Enterprise）。
   • 第 2 个是 API 按量付费（要充钱），第 3 个是云平台，订阅用户都不选。
2. 授权页长这样：标题"Claude Code 想连接您的 Claude 聊天账户"，底部一个黑色「授权」按钮。没有侧边栏、不要充钱。看到要充钱 / 有侧边栏就是走错地方了（那是 Console 后台或账户设置页）。
3. 授权页只能由终端那条 oauth 链接打开，靠浏览器点菜单永远到不了授权页。
4. OAuth error: Invalid code = 验证码没复制全 → 优先用"复制按钮"或三击整段选中。
5. 授权回调跳"服务中断"页 = 那一秒代理没走通 → 切全局模式 + 换稳节点再走一遍，必要时用全局模式而非无痕窗口（无痕仍用同一套分流规则，不解决问题）。
6. 判断"是不是其实已经登好了"：/status 看显示 Claude Pro Account（已登好）还是 Claude API Account（被顶掉/没登好）。

安全提醒：那条 https://claude.com/cai/oauth/... 链接是用户账号的专属登录凭证，绝不能发给别人或贴到公开处。

---

C. 模型不可用

症状：There's an issue with the selected model (...). It may not exist or you may not have access to it.

• 如果是带 [1m] 的模型（如 claude-opus-4-8[1m]）：那是 100 万超长上下文特殊版，订阅可能未开放 → /model 换成普通 Sonnet 或普通 Opus（不带 [1m]）。
• 如果两个标准模型（如 Sonnet 和 Opus）都报同样的"无权访问"：这几乎不可能是模型问题，真正原因通常是网络又掉了或凭证失效——请求其实没发出去，被含糊报成"模型无权访问"。回到 A 重新确认代理，并用 /status 看是否还是 Pro 登录。

---

D. "每次退出终端又要重新登录"

根因不是登录没保存（凭证存在 ~/.claude，跨窗口保留），而是代理只在窗口里的 export 里，一关就没。新窗口没代理 → 403 → 被迫重登。

解决：把代理永久写进 shell 配置（zsh 为例，端口换成用户的）：

echo 'export HTTPS_PROXY=http://127.0.0.1:7892' >> ~/.zshrc
echo 'export HTTP_PROXY=http://127.0.0.1:7892' >> ~/.zshrc
source ~/.zshrc

验证（新开一个窗口跑）：

echo $HTTPS_PROXY

显示出 http://127.0.0.1:7892 即成功，以后任何新窗口自动带代理。

前提（否则仍会掉）：

1. 代理工具要开着，且在支持节点；
2. 端口要和配置里写的一致（代理换端口要同步改）；
3. 若用过 cc Switch 等切换配置的工具，确认它没把订阅登录顶成 API 模式。

---

E. 第三方配置工具（cc Switch 等）的干扰

如果用户用了 cc Switch / 改过 ~/.claude 或环境变量里的 ANTHROPIC_*：

• 这类工具可能把端点或 API key 指向别处，覆盖掉订阅登录，表现为"刚登好又不行 / 换什么模型都报错"。
• 排查：echo $ANTHROPIC_API_KEY（有值且本意是用订阅 → unset 后重登）、/status 看是不是变回了 API Account。
• 彻底重置登录状态：rm -rf ~/.claude 后重新 /login（注意这会清掉登录记录，需重新授权，但不删项目文件）。

---

与用户沟通的风格要求

• 大白话，少术语；用到术语先一句话解释。
• 一次一两步，给可直接复制的命令，多请用户截图确认现状再给下一步。
• 不要被中间的 401 / "看起来像报错"的提示吓到——先判断它到底是好消息还是坏消息再回应。
• 反复失败时，换打法（切全局模式、换节点、设备码登录），不要让用户一遍遍重试同一个动作。
• 涉及 登出 / 删除账户 / 从所有设备登出 等危险按钮，主动提醒别点。
• 永远不要让用户把 oauth 专属链接发给第三方。