Claude Code 报 API Error: Connection error（Unable to connect to API）怎么解决

同一个问题的其他写法

• API Error (Connection error.) · Retrying in 1 seconds… (attempt 1/10)
• Couldn't connect through your proxy (ECONNREFUSED)
• TypeError (fetch failed)
• Unable to connect to Anthropic services · Failed to connect to api.anthropic.com: ERR_BAD_REQUEST

这类报错说明什么

Connection error、fetch failed、Unable to connect to API (...) 这些报错，和 401、429、503 有本质区别：后者是 CCSub 返回的 HTTP 错误，说明请求到了；前者是请求根本没能建立连接，CCSub 的日志里不会有任何记录。所以排查方向完全在你本机：网络、代理、防火墙、DNS。

新版 Claude Code 会把底层错误码写在括号里，旧版则显示 API Error (Connection error.) 并附带 TypeError (fetch failed)，同时自动重试最多 10 次。括号里的错误码含义：

• ECONNREFUSED：目标拒绝连接。最常见的原因是代理变量指向了一个没在运行的本地代理端口。
• ENOTFOUND：域名解析不到。检查 ANTHROPIC_BASE_URL 是否拼错，应为 https://www.ccsub.net。
• ETIMEDOUT：连接超时。网络不通，或者代理、防火墙把这条路堵住了。
• Couldn't connect through your proxy：Claude Code 明确是在连代理时失败的，直接去看代理设置。

最常见的原因：代理变量残留

很多人为了访问海外网站，在 ~/.zshrc 里写过 export https_proxy=http://127.0.0.1:7890，或者用代理软件的「复制终端代理命令」设置过。之后关掉了代理软件，但新开的终端仍然会带着这些变量，Claude Code 就会把每个请求都发到 7890 端口，然后得到 ECONNREFUSED。

Claude Code 会读取标准的代理变量，优先顺序是 https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY，而且不支持 SOCKS 代理。排查步骤：

# 1. 看看当前终端里有哪些代理变量
env | grep -i proxy

# 2. 临时去掉（只对当前终端有效）
unset https_proxy HTTPS_PROXY http_proxy HTTP_PROXY all_proxy ALL_PROXY

# 3. 或者保留代理，只让 CCSub 直连
export NO_PROXY="www.ccsub.net,ccsub.net"

要永久生效，把 shell 配置文件里对应的 export 删掉或补上 NO_PROXY。另外检查 ~/.claude/settings.json 的 env 字段里有没有写死代理地址，Claude Code 的 /status 页面也会显示当前生效的 Proxy。

如果代理软件开着「TUN 模式」或「全局模式」，即使没有环境变量，流量也会被接管。可以在代理软件的规则里给 ccsub.net 加一条直连规则（Clash 类软件的写法是 DOMAIN-SUFFIX,ccsub.net,DIRECT），或者用 CCSub 时先关掉全局模式。CCSub 在国内可以直连，不需要经过代理。

用 curl 判断是不是网络问题

在启动 Claude Code 的同一个终端里执行：

curl -sS -X POST https://www.ccsub.net/v1/messages -o /dev/null -w '%{http_code}\n'

curl 也会读取同样的代理变量，所以它的结果能代表 Claude Code 的网络环境。输出 401 说明已经连到 CCSub（没带 Key 才是 401），网络没问题，回头检查 Claude Code 的配置；如果卡住、报 Could not resolve host 或 Connection refused，就是本机网络或代理的问题。

首次启动报 Unable to connect to Anthropic services

第一次运行 claude 时，新手引导会先检查能否访问 api.anthropic.com，这一步不走你配置的 ANTHROPIC_BASE_URL。在国内网络下它通常会失败，报 Unable to connect to Anthropic services。Claude Code 的 GitHub 上已经有对应的问题报告，目前的通用做法是跳过引导：打开 ~/.claude.json（注意是家目录下的这个文件，不是 ~/.claude/ 文件夹），在最外层的 JSON 里加上：

"hasCompletedOnboarding": true

保存后重新运行 claude。如果文件不存在，就新建一个，内容写成 {"hasCompletedOnboarding": true}。

公司网络和证书报错

如果报错是 SSL certificate verification failed 或 unable to get local issuer certificate，通常是公司网络的 TLS 检查代理替换了证书。按官方文档，把公司根证书的路径设到 NODE_EXTRA_CA_CERTS 再启动 Claude Code。

常见问题

相关报错

• stream disconnected before completion: stream closed before response.completed流在结束前断了。确认 base_url 是 https://www.ccsub.net/api/v1，去掉干扰终端的代理，过长的单轮任务调低推理强度或拆小，并在 provider 里调大 stream_max_retries。
• API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"Invalid or disabled API key"}}Key 没带上或带错了。用 /status 看 Claude Code 实际用的是哪个变量，到 /keys 重新复制完整 Key，删掉多余的 ANTHROPIC_API_KEY 后重开终端。
• API Error: 504 {"type":"error","error":{"type":"timeout_error","message":"Upstream timed out"}}等上游的时间超过上限了。自己调用时改成流式（stream: true），上下文太长就 /compact，长输出拆成几次；偶发一次直接重试即可，不计费。