Claude Code 国内使用：连不上、慢、安装失败怎么办

结论先行

• 装不上：是安装源的问题，和 API 无关。原生安装器从 downloads.claude.ai 下载，npm 安装走 npm 源，先测这两处通不通。
• 连不上：先用 curl 直接请求 $ANTHROPIC_BASE_URL/v1/messages。curl 通而 Claude Code 不通，问题多半在本机配置。
• 很慢：用 curl 的 time_* 拆出 DNS、TLS、首字节几段，慢在哪段就改哪段。
• 用一会儿就断：看断开的时间点是否固定。固定就是某一层的超时，随机才怀疑链路。
• Base URL：ANTHROPIC_BASE_URL 只填网关根地址，不带 /v1。用 GPTZZZ 时填 https://gptzzz.ai。

先分清是哪一类问题

「Claude Code 连不上」底下其实混着四种故障，先看下表是哪一种。

第一类和后三类没关系。装不上只需换安装方式或安装源，跟用不用网关是两件事。

下面每一节都有通过标准。过了就往下走，不过就停在那一层解决。

装不上：先查安装源

官方推荐用原生安装器，它从 downloads.claude.ai 下载。先确认能不能连上这个地址：

curl -sI https://downloads.claude.ai/claude-code-releases/latest

Windows PowerShell 里要写成 curl.exe。官方排查文档对结果的解释：

运行安装命令时报 syntax error near unexpected token `<'，说明安装地址返回的是 HTML 页面，不是脚本。页面写着 App unavailable in region 时，表示所在地区不提供 Claude Code。地区政策的细节见国内用户常见难点：地区与支付。

官方也提供 npm 安装。它从 npm 源下载，安装时不需要访问 downloads.claude.ai。npm 安装要求 Node.js 22 或更高版本。

npm config get registry   # 当前用的 npm 源
npm ping                  # 超时说明这个源不通
npm install -g @anthropic-ai/claude-code

npm ping 超时，就换一个能访问的 npm 镜像源再装。注意两点：

• 镜像源要同步 @anthropic-ai/claude-code 和它的 8 个平台包。缺平台包时，运行 claude 会报 claude native binary not installed。
• 不要用 sudo npm install -g。官方文档提醒，这会带来权限问题和安全风险。

装完验证：

claude --version
claude doctor

claude --version 打印出版本号，安装这一层就通了。claude doctor 会检查安装状态和 settings 文件错误，不会启动会话。

提示 command not found: claude，通常是安装目录不在 PATH 里。macOS 和 Linux 上，原生安装器把它放在 ~/.local/bin/claude。先看这个目录在不在 PATH 里：

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

没有输出，就把它加进 shell 配置，再开一个新终端。下面是 zsh 的写法；Linux 上的 bash 改成 ~/.bashrc，macOS 上的 bash 改成 ~/.bash_profile：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

装好以后再出问题，就不是安装的事，不要回头折腾安装源。

连不上：先用 curl 测端点

装好后一发消息就报错，多半是端点或 Key 的问题。Claude Code 用官方支持的环境变量接网关：

export GPTZZZ_API_KEY="YOUR_GPTZZZ_API_KEY"
export ANTHROPIC_BASE_URL="https://gptzzz.ai"
export ANTHROPIC_AUTH_TOKEN="$GPTZZZ_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet-5"

用别的网关时，把地址和 Key 换成它给你的值。最常见的坑有两个。

第一，Base URL 不带 /v1。Claude Code 会自己在后面拼 /v1/messages。写成 https://gptzzz.ai/v1，实际路径就变成 /v1/v1/messages，请求会失败。

第二，鉴权头要和网关对上。ANTHROPIC_AUTH_TOKEN 发 Authorization: Bearer，ANTHROPIC_API_KEY 发 x-api-key。网关只认其中一种时，放错变量会返回 401。GPTZZZ 两种都接受，任选其一。

配完先用 curl 直接测端点，再启动 Claude Code：

curl -sS -w '\n%{http_code} %{time_total}s\n' \
  -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'

返回以 {"id":"msg_ 开头的 JSON、状态码 200，端点这一层就通了。返回 401，是 Key 或鉴权头不对。报模型名错误，通常说明地址和 Key 已经通了，换成网关支持的模型 ID 即可。

这一步把「网关的问题」和「本机配置的问题」分开。curl 能通而 Claude Code 不通，问题多半在本机配置。Claude Code 里常见的报错：

按报错原文逐条处理，见按报错原文查。

很慢：先测基线，再找慢在哪段

端点通了还是慢，不要直接换网关。先测五次，记下基线：

for i in 1 2 3 4 5; do
  curl -s -o /dev/null \
    -w "DNS %{time_namelookup}  连接 %{time_connect}  TLS %{time_appconnect}  首字节 %{time_starttransfer}  总计 %{time_total}\n" \
    -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
    -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{"model":"claude-sonnet-5","max_tokens":16,"stream":true,"messages":[{"role":"user","content":"hi"}]}'
done

这几个值是累计的，后一个减前一个才是这一段的耗时。取五次的中位数，不要取最好的那次。最好的那次可能刚好碰上网络或上游空闲，代表不了平时的体感。

请求体里带了 "stream":true。不带的话，响应通常要等生成完才返回，首字节就包含了全部生成时间，拆不出输出速度。

抖动比绝对值更重要。平均 1.5 秒但偶尔 15 秒的链路，体验比稳定 3 秒差得多。五次结果偏离中位数超过一半，就算抖动大。

首字节时间最值得单独看。它包含网关到上游的链路和模型排队时间。DNS 和 TLS 只在新建连接时明显，连接复用后基本归零。

推理型模型的首字节可能很快，总时长却很长，因为它在思考。这不是网络问题，换网关没用。简单任务可以换推理档位低的模型。不同模型支持的推理档位不一样，配置前先确认。

把基线记在文件里，每次改配置后重跑对比。系统化的做法见中转站稳定性基准测试。

用一会儿就断：先看超时

Claude Code 的回复是流式的，依赖长连接。中途断开，靠断开的规律就能分清原因：

Claude Code 自己的超时很宽。单次 API 请求默认 10 分钟（API_TIMEOUT_MS）。经网关的流式响应，要连续几分钟收不到任何数据才会被中断。

所以几十秒就断，先查本机代理软件和公司代理的超时，这一层的问题换网关没用。排除它们后仍是长回复断、短回复正常，再怀疑网关的流式超时。

网络慢或经过代理时，可以调大 API_TIMEOUT_MS（单位毫秒）。代理用 HTTPS_PROXY 设置；官方说明 Claude Code 不支持 SOCKS 代理。

测长流式是否稳定，直接发一个要求长输出的请求：

curl -N -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":2000,"stream":true,
       "messages":[{"role":"user","content":"写一篇 1500 字的技术说明"}]}' \
  | tail -5

正常应以 message_stop 事件结束。中途无声中断，说明连接被掐了。再看断开时间点是否固定，就能分清是代理超时还是网关的问题。

429 等错误码的处理见API 中转站错误码对照；流式事件的完整性判断见流式响应与工具调用兼容性。

重试和并发：别在外面再叠一层

Claude Code 自己会重试失败的 API 请求，默认最多重试 10 次。次数可用 CLAUDE_CODE_MAX_RETRIES 调整。再在代理或脚本里加一层自动重试，次数会成倍叠加，网关拥塞时反而更慢。

自己写脚本调接口时，还有个特殊风险：带工具调用的请求重试，可能让副作用执行两次。比如写文件的工具已经执行，但响应超时，重试会再写一次。

流式已经产出的部分是计过费的。重发整个请求，等于为同一段输出付两次钱。

并发也一样。网关有速率限制，超了返回 429，重试又加重拥塞。先串行跑通，再逐步提高并发，看总吞吐是否还在线性增长。不再增长的那个点就是上限。

退避和熔断的完整策略见中转站重试与故障回退；长期盯住延迟和 429 比例，见中转站可观测性。

「Claude Code 镜像站」到底指什么

官方安装文档里没有「镜像站」这一项。官方给的安装方式是原生安装器、Homebrew、WinGet、Linux 包管理器和 npm。中文里说的「镜像站」，通常指三种不同的东西：

要在终端里用 Claude Code 写代码，需要的是第一种。看对方给你的是什么：

• 给 Base URL 加 Key：第一种，按端点检查一节配置。
• 给 网页登录入口：第二种。它读不到你本地的文件，也执行不了命令。
• 给 一行 npm 源配置：第三种。只解决安装，不解决连接。

有的站同时提供网页版和 API，两者的额度和计费往往是分开的。买了网页版套餐，不等于有 API 额度。

不想靠宣传页判断，就拿对方给的地址和 Key 发一条最小请求：

curl -sS -w '\n%{http_code}\n' -X POST "https://候选站点/v1/messages" \
  -H "Authorization: Bearer 你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"对方的模型ID","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

返回以 {"id":"msg_ 开头的 JSON，是 Messages 兼容网关；返回 404 或一段 HTML，多半是网页套壳站。对方只认 x-api-key 时，把鉴权头换成 x-api-key: 你的密钥 再试。

能连上只是第一关。协议、工具调用、计费这些怎么比，见 Claude Code 中转站怎么选。

把配置写进 settings，用 /status 核对

只在 shell 里 export 的变量有两个问题：开新终端就没了；从程序坞或开始菜单打开的编辑器读不到。官方文档也提醒，在后台运行的 Claude Code 会话（background agents）不一定能拿到 shell 里的变量。

curl 测通以后，把同样的值写进 ~/.claude/settings.json 的 env：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gptzzz.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_GPTZZZ_API_KEY",
    "ANTHROPIC_MODEL": "claude-sonnet-5"
  }
}

不要把 Key 写进项目里的 .claude/settings.json，这个文件会提交到仓库。只对一个项目生效时，用 .claude/settings.local.json；手动创建时，先把它加进 .gitignore。

启动 Claude Code 后运行 /status：

/status

Anthropic base URL 一行显示网关地址，说明请求走的是网关。Auth token 或 API key 一行写着你设的变量名，说明用的是网关凭据，不是之前保存的登录。

settings 文件的 env 会覆盖 shell 里的同名变量。两处都配了且值不同，生效的是 settings 文件里的那个。

另一个可靠的确认方式是看网关控制台的用量记录。有对应时间的调用，说明请求确实走了网关。

按顺序排查一遍

遇到问题按这个顺序走，一层一层排除，不要跳步：

在第几步断，问题就在那一层。第 3 到 5 步只用 curl，不依赖 Claude Code 本身，能把客户端排除在外。

跳过前几步直接改 Claude Code 配置，是最浪费时间的做法。配置改来改去，问题其实在 DNS 上。带着一个 60 秒超时的代理去换网关，换几家都一样。

官方资料

• Claude Code：安装与系统要求
• Claude Code：安装与登录排查
• Claude Code：连接 LLM gateway
• Claude Code：网络、代理与超时配置
• Claude Code：环境变量

常见问题

继续阅读