排错

Claude Code 报 Unable to connect to API：ECONNREFUSED、ECONNRESET、ENOTFOUND 和超时怎么解决

Q: Claude Code 报 API Error: Unable to connect to API (ConnectionRefused) 是什么意思？

连接被主动拒绝了。Claude Code 提示可能是防火墙或代理挡住了。检查在同一个 shell 里 curl -I 能不能连到该主机，HTTPS_PROXY 里的端口对不对，以及 ANTHROPIC_BASE_URL 是不是还指向一个没有在运行的本地代理或网关。

Q: Unable to connect to API (ECONNRESET) 是什么意思？

Claude Code 显示为 Connection dropped (ECONNRESET)。按 Node.js 的说法，是对端强行关闭了连接。看看你和 API 之间有什么：代理、网关，或者不稳定的 VPN。如果在网关后面每个请求都这样结束，Anthropic 建议检查网关及其上游是否接受 Claude Code 发送的 tool search 字段。

Q: Unable to connect to API (ENOTFOUND) 是什么意思？

DNS 查询失败。Claude Code 的提示是 Can't reach the API server — check your internet or DNS。检查网络连接和解析器；在 Linux 和 WSL 上，/etc/resolv.conf 可能指向了连不上的 DNS 服务器。

Q: Claude Code 怎么设置代理？

在启动 claude 之前设置 HTTPS_PROXY（需要时再加 HTTP_PROXY），必须绕开代理的主机用 NO_PROXY。Claude Code 不支持 SOCKS 代理。想长期生效，就把变量写进 settings.json 的 env 块，再用 /status 的 Proxy 一行确认。

发布于 2026 年 11 月 5 日 · 最后核对 2026 年 11 月 5 日

Unable to connect to API 的意思是：Claude Code 到 API 主机的连接失败，或者根本没建立起来。原因几乎都在网络链路上，和你的提示词无关。括号里的错误码告诉你是怎么失败的。这篇讲每个错误码的含义、最快定位原因的检查步骤，以及怎么设置代理、自定义 CA 和超时变量。内容依据 Anthropic 的 Error reference 和 Enterprise network configuration，2026 年 11 月 5 日核对。

要点

这个报错表示到 API 的 TCP 连接失败或没有建完。Anthropic 文档列出的常见原因：没有网络、VPN 挡住了 api.anthropic.com，或者必须经过的公司代理没有配置。
先在同一个 shell 里运行 curl -I https://api.anthropic.com。curl 能通而 Claude Code 不通时，检查 ANTHROPIC_BASE_URL 是不是留着一个指向已停止的网关或本地代理的旧值。
在代理后面时，启动 Claude Code 之前设置 HTTPS_PROXY。Claude Code 不支持 SOCKS 代理。自定义 CA 用 NODE_EXTRA_CA_CERTS。
代理或网关响应慢导致每次请求都超时，可以调大 API_TIMEOUT_MS。

各个错误码是什么意思

Claude Code 把错误码留在括号里，方便你区分失败的类型。Anthropic 列出的消息如下：

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) 这样的旧格式，所以在搜索结果和 issue 里还能看到它。Connection refused 可能带 ConnectionRefused 或 ECONNREFUSED，Can't reach the API server 可能带 ENOTFOUND 或 FailedToOpenSocket。

这些错误码是 Node.js 的标准系统错误，定义见 Node.js 错误文档：

错误码	Node.js 的说明	先看哪里
`ECONNREFUSED`	连接被拒绝：目标机器主动拒绝了连接，通常是对方主机的那个端口上没有服务在监听。	防火墙或代理挡住了该主机；代理地址的端口写错；`ANTHROPIC_BASE_URL` 留着一个已经没在运行的地址。
`ECONNRESET`	连接被对端重置：连接被对端强行关闭，通常是远端套接字因超时或重启而断开。	代理或网关主动断开连接；VPN 或网络不稳定。
`ENOTFOUND`	DNS 查询失败。	DNS 或解析器；主机名拼写错误。Node.js 注明这不是标准的 POSIX 错误。
`ETIMEDOUT`	操作超时：连接或发送请求失败，因为对方在一段时间内没有正确响应。	线路很慢或被过滤；代理一直不应答。

右边一列只是起点，不是诊断结论。同一个错误码可能有多种原因，所以下一节先查网络链路，再改设置。

先检查网络链路

Anthropic 给的第一步，是在运行 Claude Code 的同一个 shell 里确认能不能连到 API 主机：

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

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

PowerShell 里要用 curl.exe，避免被内置的 Invoke-WebRequest 别名接管。如果 Claude Code 走的是中转或网关，对它的地址做同样的检查：curl -I <你的 base URL>。然后按结果判断：

curl 也失败。问题在网络，不在 Claude Code。检查网络、VPN、DNS 和防火墙。Anthropic 要求放行的主机列表见 Network access requirements。
curl 能通，Claude Code 仍然失败。Anthropic 说这时原因通常出在运行时和网络之间。检查下面几项。

检查有没有残留的 ANTHROPIC_BASE_URL

设置了 ANTHROPIC_BASE_URL 后，Claude Code 会把模型请求发到这个地址，而不是 api.anthropic.com。如果残留的值指向一个已经不再运行的本地代理或网关，即使 curl 能连上 API，也会报 Connection refused。用 echo $ANTHROPIC_BASE_URL 检查（PowerShell 用 echo $env:ANTHROPIC_BASE_URL），同时看设置文件里的 env 块。在 Claude Code 里运行 /status，可以看到它实际使用的 Base URL。把过期的值从 shell 配置或设置文件里删掉，再开一个新终端启动 Claude Code。

Anthropic 列出的其他本地原因

Linux 和 WSL 上，/etc/resolv.conf 里有连不上的 DNS 服务器。WSL 尤其容易从宿主机继承一个坏掉的解析器。
macOS 上，断开或卸载的 VPN 客户端可能留下隧道接口或路由规则。用 ifconfig 看有没有残留的 utun 接口。
Docker Desktop 一类的容器运行时可能拦截出站流量。退出它们再试一次，用来排除这个原因。

偶发的失败会被自动重试，一次抖动不用处理。

设置代理、CA 和 mTLS

Claude Code 读取标准的代理环境变量。在启动 Claude Code 之前设好；已经在运行的会话不会读取之后对 shell 环境的修改。这些变量也都可以写进 settings.json 的 env 块。

# HTTPS 代理（推荐）
export HTTPS_PROXY=https://proxy.example.com:8080

# HTTP 代理（没有 HTTPS 代理时）
export HTTP_PROXY=http://proxy.example.com:8080

# 指定主机不走代理
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"

小写的变量也有效；Claude Code 按 https_proxy、HTTPS_PROXY、http_proxy、HTTP_PROXY 的顺序取第一个设置了的。NO_PROXY 可以用空格或逗号分隔，写 * 表示所有请求都不走代理。代理需要基本认证时，把账号密码写进 URL，例如 http://username:password@proxy.example.com:8080，不要把密码硬编码在脚本里。Claude Code 不支持 SOCKS 代理，所以只提供 SOCKS 的代理软件，需要另开一个 HTTP 代理端口，或者让 Claude Code 绕开它。

代理 URL 解析不了时（例如缺少 http:// 前缀），Claude Code 会在启动时报错并指出是哪个变量。主机或端口写错，要到下一次请求才会发现，这时你看到的就是 ECONNREFUSED 或 ERR_PROXY_TUNNEL。

公司自签 CA 的情况，用 Node 的变量指向证书文件。默认情况下，Claude Code 信任自带的 Mozilla CA 证书和操作系统的证书库：

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

需要客户端证书认证时，Anthropic 文档里的变量是 CLAUDE_CODE_CLIENT_CERT、CLAUDE_CODE_CLIENT_KEY，私钥加密时再加 CLAUDE_CODE_CLIENT_KEY_PASSPHRASE。这是企业环境用的，多数人只需要上面的代理变量。

确认设置已经生效

在交互会话里运行 /status。Proxy 一行显示当前生效的代理 URL，解析不了的值会标成无效并被忽略；Additional CA cert(s) 一行显示 NODE_EXTRA_CA_CERTS 的路径，但不检查文件是否真的加载成功。想看更多信息，用 claude --debug 启动。日志写在 ~/.claude/debug/<session-id>.txt，文件加载成功时会有 CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS 这样的行。

超时和 No response from API

有两种消息说的是等待，不是连接：

Request timed out。API 没有在连接期限内响应。默认是 10 分钟。Anthropic 的建议：重试；如果是网络或代理慢，调大 API_TIMEOUT_MS。
No response from API。Claude Code 发出了流式请求，但在首字节期限内没有收到响应头。Claude Code 会重发，重试同样没有响应时，这一轮以这条消息结束。Anthropic 的建议是再发一次消息；反复出现就按网络或代理问题处理。如果你网络上的代理或网关会一直扣住响应、直到生成完毕才放行，调大 API_TIMEOUT_MS，让重试等得更久。

API_TIMEOUT_MS 是每次请求尝试等待响应头的毫秒数，默认 600000。响应头到达之后，它不限制流式响应能跑多久。只对当前会话设置：

export API_TIMEOUT_MS=1200000
claude

$env:API_TIMEOUT_MS = "1200000"
claude

调大超时只对“响应太慢”有用。连接本身失败时，调它没有任何效果。

首次启动：Unable to connect to Anthropic services

这是另一条消息。首次启动时，Claude Code 会先检查能否连到 api.anthropic.com 和 platform.claude.com，通过之后才显示登录步骤。任何一项检查失败，它会打印原因并退出，例如 Failed to connect to api.anthropic.com: ECONNREFUSED 或 Connection to api.anthropic.com timed out after 10 seconds。这项检查和 API 请求走同一套代理配置，失败的探测经过代理时，消息里会指出是哪个变量，例如 HTTPS_PROXY。Anthropic 的建议是：确认代理的值正确，再做上面的 curl 测试，另外 Claude Code 可能不在你所在的国家提供。

如果你用的是中转，首次启动的这项检查和中转无关：引导流程会去连 Anthropic 官方服务，国内网络常常连不上。CoreCode 的做法是跳过引导：

用编辑器打开 ~/.claude.json（Windows 是 %USERPROFILE%\.claude.json）。
在最外层加上 "hasCompletedOnboarding": true，保存。
重新运行 claude。

步骤与 CoreCode 报错排查和常见问题一致。

用 CoreCode 时：让中转直连

CoreCode 是由官方 Claude 账号应答的中转。Claude Code 用 ANTHROPIC_BASE_URL=https://corecode.live 指向它，密钥放在 ANTHROPIC_AUTH_TOKEN，写法见 Claude Code 接入。运行 /status，确认 Base URL 是 https://corecode.live；如果不是，请求发往的是官方主机，那边的连接报错和中转无关。

开着代理或 VPN 时，我们的建议是：corecode.live 在国内可以直连，全局代理只会让请求绕一圈，变慢，偶尔还会断流。在代理软件的规则里把 corecode.live 设为直连（DIRECT）；报错排查和国内怎么用 Claude Code也是这个说法。如果你所在的公司网络要求所有流量都走公司代理，则按上文设置 HTTPS_PROXY。

连接报错持续出现时，先看服务状态，再按反馈与联系联系我们。我们不承诺可用性。

常见问题

Claude Code 报 API Error: Unable to connect to API (ConnectionRefused) 是什么意思？

连接被主动拒绝了。Claude Code 提示可能是防火墙或代理挡住了。检查在同一个 shell 里 curl -I 能不能连到该主机，HTTPS_PROXY 里的端口对不对，以及 ANTHROPIC_BASE_URL 是不是还指向一个没有在运行的本地代理或网关。

Unable to connect to API (ECONNRESET) 是什么意思？

Claude Code 显示为 Connection dropped (ECONNRESET)。按 Node.js 的说法，是对端强行关闭了连接。看看你和 API 之间有什么：代理、网关，或者不稳定的 VPN。如果在网关后面每个请求都这样结束，Anthropic 建议检查网关及其上游是否接受 Claude Code 发送的 tool search 字段。

Unable to connect to API (ENOTFOUND) 是什么意思？

DNS 查询失败。Claude Code 的提示是 Can't reach the API server — check your internet or DNS。检查网络连接和解析器；在 Linux 和 WSL 上，/etc/resolv.conf 可能指向了连不上的 DNS 服务器。

Claude Code 报 The operation timed out 或 No response from API 怎么办？

API 或它前面的代理没有及时应答。再发一次消息。反复出现就按网络或代理问题处理；如果是代理或网关扣住响应直到生成完毕，调大 API_TIMEOUT_MS。

Claude Code 怎么设置代理？

在启动 claude 之前设置 HTTPS_PROXY（需要时再加 HTTP_PROXY），必须绕开代理的主机用 NO_PROXY。Claude Code 不支持 SOCKS 代理。想长期生效，就把变量写进 settings.json 的 env 块，再用 /status 的 Proxy 一行确认。

Anthropic SDK 用的代理设置和 Claude Code 一样吗？

这篇只讲 Claude Code，上面的代理变量也只是按 Claude Code 的文档写的。SDK 自己的代理选项请看 SDK 的文档，不要假设和这里一致。

来源

Claude Code：Error reference（Unable to connect to API、Unable to connect to Anthropic services、Request timed out、No response from API，2026 年 11 月 5 日核对）
Claude Code：Enterprise network configuration（HTTPS_PROXY、HTTP_PROXY、NO_PROXY、不支持 SOCKS、NODE_EXTRA_CA_CERTS、mTLS 变量、/status 和 --debug，2026 年 11 月 5 日核对）
Claude Code：Environment variables（API_TIMEOUT_MS，2026 年 11 月 5 日核对）
Node.js：Common system errors（ECONNREFUSED、ECONNRESET、ENOTFOUND、ETIMEDOUT，2026 年 11 月 5 日核对）