Claude Code 提示「Unable to connect to API」：ConnectionRefused、ECONNRESET 和代理问题怎么解决

一句话答案

Unable to connect to API 的意思是：Claude Code 没能和它发送模型请求的那个地址建立连接，或者连接中途断了。括号里的代码告诉你是哪一环出了问题：没有程序应答（ConnectionRefused）、域名解析不了（ENOTFOUND）、连接被切断（ECONNRESET），或者证书不被信任。

按这个顺序排查：

1. 找到地址。 运行 /status，看 Anthropic base URL 这一行。没设置过的话就是 api.anthropic.com。再运行一下 echo $ANTHROPIC_BASE_URL。
2. 在同一个终端里用 curl 测这个地址。 curl 也失败，问题在网络、VPN、防火墙或代理；curl 能通，问题在 Claude Code 读到的东西：它的环境变量和配置文件。
3. 检查有没有残留的 ANTHROPIC_BASE_URL。 如果它指向一个已经不在运行的本地代理或切换工具，就会报 Connection refused，哪怕 api.anthropic.com 本身完全能连上。

Claude Code 显示这个错误之前已经自动重试过了，所以不改任何东西、直接再发一次，一般没用。

报错长什么样

从 v2.1.227 起，提示会写明失败类型，并把代码放在括号里。按 Claude Code 错误说明：

Unable to connect to API. Check your internet connection
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Can't reach the API server — check your internet or DNS (ENOTFOUND)
No internet route — check your connection or VPN (EHOSTUNREACH)
Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host
Connection dropped (ECONNRESET)
Request timed out. Check your internet connection and proxy settings

老版本显示的是 Unable to connect to API 后面跟代码。重试期间转圈的地方会倒计时，比如 anthropics/claude-code#84782：

Unable to connect to API (ConnectionRefused) · Retrying in Ns · attempt N/10

时好时坏的断连是这样（#83399）：

API Error: Unable to connect to API (ECONNRESET)

证书问题也是同样的开头。新版本会附上 OpenSSL 错误码和 NODE_EXTRA_CA_CERTS 的提示，老版本是 #74369 里这样：

API Error: Unable to connect to API: Self-signed certificate detected. Check your proxy or corporate SSL certificates

每个代码是什么意思

怎么解决

1. 看 Claude Code 连的是哪个地址

运行 /status。Anthropic base URL 一行是请求发往的地址，Proxy 一行是当前生效的代理（解析不了的值会标成无效）。然后检查 Base URL 可能来自的地方：

echo $ANTHROPIC_BASE_URL
env | grep -i -E 'anthropic|proxy'

PowerShell 用 echo $env:ANTHROPIC_BASE_URL 和 Get-ChildItem Env:*PROXY*。再打开 ~/.claude/settings.json 和项目里的 .claude/settings.local.json，看 env 块。配置文件里的值会覆盖终端里 export 的值。

2. 用 curl 测同一个地址

默认地址的话，错误说明建议：

curl -I https://api.anthropic.com

Windows PowerShell 里要输 curl.exe，避免用到内置的 Invoke-WebRequest 别名。如果用的是网关，就带上你的 Key 测网关地址。网关接入文档 用的是一个只要 1 个 token 的请求：

curl -sS -w '\n%{http_code}\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": 1, "messages": [{"role": "user", "content": "."}]}'

只要拿到任何 HTTP 状态码——哪怕是 401 或模型不存在——都说明网络是通的。curl 报连接错误，说明网络不通，先把网络问题解决，再去动 Claude Code 的配置。

3. curl 也失败：修网络链路

• VPN。 断开重连，或者关掉试试。macOS 上，断开或卸载过的 VPN 可能留下失效的 utun 网卡（用 ifconfig 看）或系统设置里的网络扩展。
• 公司代理。 启动 Claude Code 之前设置 HTTPS_PROXY，要带协议头：export HTTPS_PROXY=http://proxy.example.com:8080。Claude Code 不支持 SOCKS 代理；代理地址解析不了时，它会直接停止启动。
• 防火墙。 确认放行了 Base URL 里的主机。Claude Code 需要访问的主机列在 网络访问要求 里。
• DNS。 Linux 和 WSL 上，检查 /etc/resolv.conf 里有没有连不上的 nameserver。

4. curl 能通，Claude Code 不行：改 Claude Code 读到的配置

• 删掉过期的 Base URL。 错误说明里专门提到：残留的 ANTHROPIC_BASE_URL 指向已经停掉的本地代理或网关，会报 Connection refused，而 curl https://api.anthropic.com 是成功的。把它从 shell 配置文件和各个 env 块里删掉，再开一个新终端。
• 让 Claude Code 拿到同样的代理设置。 在某个终端里 export 的代理，到不了从程序坞或开始菜单打开的编辑器，也到不了后台会话。把 HTTPS_PROXY 和 NO_PROXY 写进 ~/.claude/settings.json 的 env 块，所有会话都会生效。
• 排除 Docker Desktop。 容器运行时可能拦截出站流量，先退出它再试。
• 升级 Claude Code。 运行 claude update。最近几个版本修过好几个连接相关的问题。

5. 证书错误：信任正确的 CA

做 TLS 检查的代理、用私有 CA 签名的网关，出示的证书 Claude Code 不认。把 CA 证书包告诉它：

export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem

不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0，那会彻底关掉证书校验。从 v2.1.199 起证书错误不再重试，所以第一次请求就会报出来。

用了网关时

设置了 ANTHROPIC_BASE_URL 后，所有模型请求都发往这个地址，所以「Unable to connect」说的是到网关的链路，不是到 Anthropic 的链路。

• 检查 URL 格式。 严格按网关文档填写 Base URL。TeamoRouter 是 https://api.teamorouter.com，后面不加 /v1，路径由 Claude Code 自己拼。
• 本地切换工具和代理。 把 Claude Code 指向 http://127.0.0.1:<端口> 的工具，只有那个本地进程在运行时才能用。不用这个工具了，就把它留下的变量删掉。
• 401 不是连接错误。 curl 能连到网关但返回 401，说明网络没问题，是凭证的问题。

另一条提示 Unable to connect to Anthropic services，来自首次启动设置时、登录之前的连通性检查。这项检查在什么情况下运行，见 错误说明。

把 Claude Code 接到 TeamoRouter

TeamoRouter 是一个 API 网关，一个 Key 可以调 Claude、GPT、Gemini、DeepSeek。Claude 走原生 Anthropic 协议（/v1/messages），Claude Code 只需要一个 Base URL 和一个 Key。没有订阅，按用量付费。

1. 在 TeamoRouter 控制台 创建 API Key，Key 以 sk-teamo- 开头。
2. 充值，最低 $5。 充值弹窗支持银行卡；也可以点 「USDT支付」，用 USDT、USDC 或 ETH，从任意交易所 App 转账——收银台会按金额显示可用网络（BEP20 从 $5 起就能用）。步骤见 用 USDT 充值。
3. 在准备运行 Claude Code 的终端里，测一下链路和 Key：

curl https://api.teamorouter.com/v1/models \
  -H "Authorization: Bearer sk-teamo-..."

返回模型列表，说明网络链路和 Key 都没问题。报连接错误，说明到 api.teamorouter.com 的网络链路有问题，回到上面第 3 步。

4. 设置两个环境变量，在同一个终端里启动 Claude Code：

export ANTHROPIC_BASE_URL=https://api.teamorouter.com
export ANTHROPIC_AUTH_TOKEN="你的 TeamoRouter API Key"
claude

运行 /status 确认 Base URL。Windows 命令和配置文件写法见 安装与配置 Claude Code。

常见问题

为什么 claude -p 能用，交互式会话却不行？ 先确认两者的运行环境一样：脚本或另一个终端里的变量可能不同。如果环境确实一样，多半是 bug。在 #84782 里，只有交互式会话失败，提问者的各项网络检查都正常。情况相同的话，升级 Claude Code 并关注这个 issue。

重装 Claude Code 能解决吗？ 很少能。地址、代理和证书设置都在你的环境变量和配置文件里，重装不会动它们。

ECONNRESET 是我这边的问题吗？ 常常是你和服务器之间有东西掐断了长连接：代理、VPN 或防火墙。Claude Code 会自动重试断开的连接；如果每次请求都这样，关掉 VPN 或代理测一下。

Unable to connect to API 是 Key 不对吗？ 不是。Key 不对会收到响应，一般是 401。这个错误的意思是根本没有拿到可用的响应。

延伸阅读

• Claude Code 提示「Request too large (max 32MB)」怎么办
• Claude API 报 529 overloaded_error 怎么办
• 安装与配置 Claude Code
• 用 USDT 充值 Claude API