中文
所有文章
AIClaude

Claude Code Unable to connect to API 是什么意思？别慌，实测 5 个解决办法

Claude Code Unable to connect to API 表示到 API 的连接没建立起来。多数时候网络没坏，是残留的 ANTHROPIC_BASE_URL、指向已关闭代理的变量、VPN 或 DNS 把请求发错了地方。我们用 Claude Code 2.1.312 实测复现，按官方报错文档整理了排查顺序。

约 6 分钟阅读
Claude Code Unable to connect to API：两只浅蓝色黏土传声筒，中间的绿色绳子打了个结，柔和自然光和树叶影子
其他语言EspañolEnglish

先说结论：Claude Code Unable to connect to API 的意思是 Claude Code 到 API 的 TCP 连接没建立起来。大多数时候网络本身没坏，是本机把请求发错了地方：残留的 ANTHROPIC_BASE_URL、指向已经关掉的代理软件的代理变量、VPN，或者 DNS 坏了。第一步在报错的同一个终端里跑 curl -I https://api.anthropic.com。curl 能拿到任何 HTTP 状态码、Claude Code 还是报错，就先查 ANTHROPIC_BASE_URL 和代理变量。我们在测试机上用 Claude Code 2.1.312 复现了这个报错，下面贴的是真实输出。报错原文和处理办法按Claude Code 官方报错文档整理，2026 年 10 月 29 日核对。

Claude Code Unable to connect to API 有哪几种写法

Claude Code Unable to connect to API 的几种报错：Connection refused、ENOTFOUND、EHOSTUNREACH、ERR_PROXY_TUNNEL、ECONNRESET 和超时，各自原因和先查什么

从 v2.1.227 开始，报错会写明是哪种失败，括号里保留错误码。官方文档列出的写法如下：

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

v2.1.227 之前是老写法，比如 Unable to connect to API (ECONNREFUSED)，网上很多帖子贴的就是这种。另外，官方文档写明 Claude Code 遇到连接失败会自动重试，最多 10 次，所以你看到报错时，重试已经用完了。

实测：Base URL 或代理指向没在运行的端口，就是 Connection refused

Claude Code Unable to connect to API 实测：curl 返回 HTTP/2 404，ANTHROPIC_BASE_URL 或 HTTPS_PROXY 指向死端口就报 Connection refused，unset 后恢复

测试环境是一台 Linux 机器，Claude Code 2.1.312，用的是假 API key。为了让报错立刻出来、不等重试，设了 CLAUDE_CODE_MAX_RETRIES=0。结果：

  • curl -sI https://api.anthropic.com 返回 HTTP/2 404。这里 404 是正常的，说明域名能连上。
  • 设 ANTHROPIC_BASE_URL=http://127.0.0.1:9（这个端口上没有任何程序），claude -p hi 报 API Error: Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED)。
  • 改成设 HTTPS_PROXY=http://127.0.0.1:9，报的是同一行 Connection refused。
  • 执行 unset ANTHROPIC_BASE_URL HTTPS_PROXY 以后再跑，返回 Invalid API key · Fix external API key。key 是故意写的假 key，这说明请求又能到 API 了。

所以 Claude Code Unable to connect to API 最常见的一种情况是 curl 通、Claude Code 不通，因为 Claude Code 会读 curl 不读的那些设置。还有一个结果：把 ANTHROPIC_BASE_URL 设成不存在的域名 https://api.anthropic.invalid，我们这台机器报的是 Connection dropped (ECONNRESET)，不是 ENOTFOUND，原因是测试机出网要经过一层代理。普通家庭网络下更可能看到 ENOTFOUND。括号里是哪个错误码，取决于你和 API 之间隔着什么。

国内用户常见的两种情况

这两种都有公开记录，不是我们猜的：

  • Clash 等代理软件关了，系统代理还开着。 Cherry Studio 的 issue #16016 里，一位用户在 macOS 上关掉 Clash 后，系统代理里还留着 127.0.0.1:7890。Cherry Studio 把它当成 HTTP_PROXY/HTTPS_PROXY 传给 Claude Code，结果所有请求都报 Unable to connect to API (ECONNREFUSED)。这和我们上面用死端口代理测出的结果一致。处理办法是关掉系统代理开关，或者把代理软件重新打开。
  • 用中转或国产模型时设过 ANTHROPIC_BASE_URL。 很多人为了接中转服务或 DeepSeek、Kimi、GLM 这类国产模型，在 shell 配置或 settings.json 里写过 ANTHROPIC_BASE_URL。换回官方账号时忘了删，Claude Code 就一直往旧地址发。中转服务停了，就是 Connection refused 或 Connection dropped。

还要知道一点：Anthropic 官方支持的国家和地区列表里没有中国大陆和香港。官方文档在 Unable to connect to Anthropic services 这条下面也写了，网络没问题还连不上，可能是所在地区不支持。

Claude Code Unable to connect to API 排查顺序

Claude Code Unable to connect to API 排查步骤：curl 测 API、查 ANTHROPIC_BASE_URL、查代理变量、VPN、DNS 和 Docker，网关再试 ENABLE_TOOL_SEARCH=false

在报错的终端里按顺序执行：

curl -I https://api.anthropic.com
echo $ANTHROPIC_BASE_URL
env | grep -i proxy
  • curl 也不通。 是网络本身的问题：Wi-Fi、防火墙、VPN 或公司代理。Windows PowerShell 要用 curl.exe -I https://api.anthropic.com，不然会调到 Invoke-WebRequest。需要走代理的，启动 Claude Code 前设好 HTTPS_PROXY，写法见官方网络配置文档。
  • curl 通，ANTHROPIC_BASE_URL 有值。 确认这个地址还能用。不用了就从 shell 配置里删掉，再查 ~/.claude/settings.json 和项目里 .claude/settings.local.json 的 env 块（位置见 settings.json 在哪），然后开一个新终端。
  • 代理变量指向已经关掉的软件。 执行 unset HTTPS_PROXY HTTP_PROXY 再试。
  • WSL 或 Linux。 看 /etc/resolv.conf 里的 nameserver 能不能用，WSL 可能从 Windows 继承了坏掉的 DNS。
  • macOS 卸过 VPN。 用 ifconfig 看有没有残留的 utun 网卡，到系统设置里删掉 VPN 的网络扩展。
  • Docker Desktop。 先退出再试，排除它拦截流量。
  • 走网关，每次都 Connection dropped。 设 ENABLE_TOOL_SEARCH=false 再试。官方文档说有些网关会拒绝 Claude Code 默认发送的 tool search 字段。

GitHub 上的真实案例

Claude Code 官方仓库的 issue #74120 里，提问者一开始怀疑是 macOS 升级导致的，最后查出来是项目里的 .claude/settings.local.json 写了 ANTHROPIC_BASE_URL: http://127.0.0.1:8787，而这个端口上什么都没运行。只有在这个项目里启动的会话报错，删掉 env 块就好了。

issue #84211 是 Windows 上的情况：2.1.220 正常，2.1.221 和 2.1.222 报 ECONNRESET。提问者查到是一个已卸载的网络加速器留下的 Winsock LSP，删掉后恢复。这是提问者自己的结论，Anthropic 在帖子里没有确认。

其他 Claude Code 报错可以查 Claude Code 报错速查总页。

  • Unable to connect to Anthropic services。 首次启动时出现，Claude Code 会在登录前检查能不能连上 api.anthropic.com 和 platform.claude.com。排查方法一样。
  • 529 Overloaded。 连接是通的，是服务器忙，见 Claude Code 529 Overloaded。
  • 429。 连接是通的，是触发了限流，见 Claude Code 429 报错。

常见问题

为什么 curl 能通，Claude Code 还是报 Unable to connect to API？

Claude Code 会读 ANTHROPIC_BASE_URL、代理变量和 settings 文件里的 env，curl 不读。我们实测时，Base URL 指向死端口就报 Connection refused，同时 curl 能正常连上 API。

报错前 Claude Code 会自动重试吗？

会。官方文档写的是最多重试 10 次，间隔逐渐拉长。可以用 CLAUDE_CODE_MAX_RETRIES 调低次数。

curl -I https://api.anthropic.com 返回 404 有问题吗？

没问题。我们在网络正常时拿到的就是 HTTP/2 404，只要有 HTTP 状态码就说明连上了。

要不要重装 Claude Code？

一般不用。重装不会清掉环境变量和 settings 文件。想从头装一遍可以看 Claude Code 安装教程。

留下你的想法

你的邮箱不会公开。