装了三个客户端、配过两个网关之后，我的 Claude Code 连不上了

先给结论：「连不上」几乎从来不是一个原因。它至少横跨四层——本机环境变量、配置文件、网络协议栈、端点本身——而这四层互相独立，任何一层出问题，表现出来都是同一句「连不上」。

所以排查的第一步不是改配置，是先确定卡在哪一层。顺序错了，你会在最后一层上耗掉一下午，而问题其实在第一层。

下面这套分层诊断，每一层都给可直接复制的命令和明确的判读依据。

一、先说这个环境是怎么乱起来的

如果你只装过一个客户端、只配过一个端点，大概率不会遇到这些问题。麻烦的是下面这种很常见的路径：

1. 先用 npm 装了 claude，后来看到 native 安装更好，又装了一遍
2. 试过 A 网关，环境变量写进了 .bashrc
3. 后来换 B 网关，在当前终端 export 了新值
4. 中间为了下载模型配过一次代理，用完忘了摘
5. 又装了 Codex CLI，它在 ~/.codex/ 下写了自己的配置

每一步单看都合理，叠在一起就变成：同一个变量有三个来源，同一个命令有两个二进制，同一个请求要先撞一次死代理。

这时候报错信息基本没有参考价值——因为报错发生的位置，和原因所在的位置，压根不是一个地方。

二、四层是哪四层

从①往④查，因为越靠近自己的层越容易验证，也越容易被忽略。

三、① 本机环境变量：最容易忘、最容易背锅

env | grep -iE "proxy|PROXY"
env | grep -i anthropic

代理变量一旦指向一个当前环境里已经不存在的地址，每个请求都要先撞一次超时才失败。现象是「什么都慢、什么都失败」，但你单独用 curl 测端点却是好的——因为你可能在另一个终端测的。

unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
claude --version

自己写脚本调 API 时，最好在程序里直接把这几个变量摘掉。你要测的是端点，不是本机的网络配置：

import os
for k in ("http_proxy", "https_proxy", "HTTP_PROXY", "HTTPS_PROXY",
          "all_proxy", "ALL_PROXY"):
    os.environ.pop(k, None)

WSL 用户额外注意一条

WSL 和 Windows 是两套独立的网络栈。 .bashrc 里写的 127.0.0.1:某端口，在 WSL 里指的是 WSL 自己的回环地址，不是 Windows 侧的同名端口。如果那个代理只在 Windows 上监听，WSL 里就是连不通的：

curl -sI --max-time 3 http://127.0.0.1:端口号 || echo "该端口在 WSL 内不可用"

四、② 配置写进去了 ≠ 当前 shell 生效

这一条制造的困惑最多，因为它的表现是「我明明改了，怎么还是旧的」。

env | grep -i anthropic                                # 当前 shell 里实际是什么
grep -rn "ANTHROPIC" ~/.bashrc ~/.zshrc 2>/dev/null    # 配置文件里写的是什么

两者不一致时，以当前 shell 里的为准。 命令行 export 过的值优先级高于配置文件，而且 source ~/.bashrc 也覆盖不回来——因为 source 只是再执行一遍，而当前 shell 里那个值已经存在了。

解法：开个新终端，或者手动重新 export 一次。

装了两个客户端时，先确认在跑哪一个

which claude
ls -la $(which claude)

指向 ~/.local/share/claude/versions/... 是 native 版，指向 node_modules 是 npm 版。两个都装过的话，PATH 顺序决定实际调用哪个——你以为在调新装的，其实调的是老的。建议只留一个。

五、③ 网络协议栈：两个最难自己想到的

前两层排掉之后，剩下的问题往往在这一层。这两个我认为是整套排查里最难靠直觉想到的。

5.1 小请求正常，一发长内容就卡死 —— MTU 黑洞

典型表现：

• claude --version 正常
• curl 打个 hi 正常返回
• 一旦贴进去几百行代码、或者对话轮次多了，请求挂在那里不动，最后超时
• 重试还是同一个位置卡住，看起来像「服务端处理不过来」

原因是链路上某一跳的 MTU 比你本机小，而路径 MTU 发现所依赖的 ICMP 报文被中间设备丢弃了。小包能过，超过阈值的大包直接进黑洞，两边都不会收到任何错误——所以表现是「卡住」而不是「报错」。VPN、部分家用路由、某些隧道网络都可能造成。

判别方法是用逐步增大的包探测，找断点：

for s in 1200 1300 1400 1472; do
  printf "%5d: " $s
  ping -c1 -W2 -M do -s $s api.anthropic.com >/dev/null 2>&1 \
    && echo ok || echo "FAIL ← 超过这个尺寸就不通了"
done

1200 通、1400 不通，说明路径 MTU 在两者之间。正常以太网是 1500（负载 1472 + 28 字节头），PPPoE 常见 1492，各类隧道再减 20～80 不等。

处理是把接口 MTU 调到安全值以下：

sudo ip link set dev eth0 mtu 1400

⚠️ 这会影响这台机器的所有流量，先用上面的探测确认真是 MTU 问题再动，别当成万能解药。

5.2 IPv6 路由不通，但系统优先走 IPv6

表现是「时通时不通」或者「慢得离谱，但别人都正常」。

多数系统在同时拿到 A 和 AAAA 记录时优先尝试 IPv6。如果本地有 IPv6 地址但那条路由实际不通，每个请求都要先等 IPv6 超时才回退到 IPv4。

curl -4 -sI -m 10 https://api.anthropic.com/v1/messages | head -1   # 强制 IPv4
curl -6 -sI -m 10 https://api.anthropic.com/v1/messages | head -1   # 强制 IPv6

-4 通而 -6 超时，就是这个问题。Linux 上可以改 /etc/gai.conf 让 IPv4 优先：

# 取消这一行的注释即可
# precedence ::ffff:0:0/96  100

六、④ 端点本身：看响应体，不要只看状态码

到这一层才该怀疑端点。别直接开客户端试，用 curl 单独打——报错信息清楚得多，而且能立刻区分「端点问题」和「客户端问题」：

curl -sS -w '\nHTTP %{http_code}\n' "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-sonnet-5","max_tokens":8,
       "messages":[{"role":"user","content":"hi"}]}'

403 有三种完全不同的来源

纯文本 error code: 1010，或一整页 HTML   → WAF / CDN 拦的，跟密钥无关
{"error":{"type":"authentication_error"}} → 鉴权真的失败了
{"error":{"type":"permission_error"}}     → 密钥有效但没这个权限

第一种在自己写脚本时特别常见：urllib 默认发 Python-urllib/3.x、requests 默认发 python-requests/2.x，CDN 的 WAF 会直接拒掉这类特征明显的客户端签名。同一个密钥，curl 通、脚本 403，就是这个原因。显式设置一个正常的 UA 即可。

404 通常是 base_url 多写了一段

# ❌ 客户端会自己补 /v1/messages，实际变成 /v1/messages/v1/messages
export ANTHROPIC_BASE_URL="https://example.com/v1/messages"
# ✅ 写到域名为止
export ANTHROPIC_BASE_URL="https://example.com"

判别方法是看客户端最后拼出来的完整 URL，不是看你配了什么。

七、两个通用对照组

上面四层的共同点是——故障现象出现的位置，和故障原因所在的位置，不是同一个地方。

所以动手改任何东西之前，先建两个对照组：

第二条最被低估：

curl -sS -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H 'content-type: application/json' -d '{}'

一个请求同时告诉你三件事——端点是活的、它的错误响应是不是标准 JSON 结构、它接受哪些鉴权头（通常直接写在报错里）。

其中第二点是关键：如果这个端点拒绝请求时返回结构化 JSON，那你收到的那个非 JSON 的 403，就不是它发出来的。

八、把这套检查固化下来

上面这些命令的价值在于你不依赖任何工具也能查清楚，换到任何端点、任何环境都成立。

建议把它们按层写成一个脚本，出问题时一次跑完，比每次现想快得多。

完整的分层手册我整理在 claude-code-cn-setup（MIT），

按安装 / 配置 / 排错 / 网络四份文档拆开，每份能脱离其他独立看。

小结

先分层，再动手。 四层里每一层的验证成本都不到一分钟，而猜错方向的成本是一下午。