Claude Code Unable to connect to API：ECONNREFUSED、ECONNRESET 与代理错误排查

Claude Code 显示 Unable to connect to API，表示它没有完成到当前 API 路线的 TCP 连接。这和服务器已经返回 401、429、500 或 529 不是一类问题。先查看实时 Claude Status，再从启动 Claude Code 的同一个终端执行：

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

如果 curl 也无法连接，优先查 DNS、防火墙、VPN、代理或 TLS；如果 curl 能收到 HTTP 响应，但 Claude Code 仍失败，就查 /status、终端继承的代理与 CA、WSL/macOS/Docker 网络，以及 ANTHROPIC_BASE_URL 指向的实际 host。

不要同时重装 Claude Code、换 Key、开关 VPN、改 DNS、换模型和切中转。即使碰巧恢复，也无法知道真正修好了什么。

先确认它确实是连接错误

Anthropic 当前的 Claude Code 错误参考把 Unable to connect to API、ECONNREFUSED、ECONNRESET、ETIMEDOUT、fetch failed 以及带网络/代理提示的 timeout 放在网络错误分支。判断重点不是中文怎么翻译，而是终端有没有收到 HTTP 响应。

• 没有状态码、响应体和 request ID：继续查连接路径。
• 已返回 401 或 invalid key：转到认证路线，不要继续改 DNS。
• 已返回 429、500 或 529：API 或中转已经响应，按对应错误处理。
• 出现 Connection closed mid-response：Claude 已经开始输出，保留完整内容块，再从最后完成的位置继续；不要把它误判成从未连接。

Claude Code 会对多种临时网络和服务端错误自动指数退避重试。终端最终显示这条错误时，通常表示短暂故障没有在自动重试阶段消失。原样连续重试只会增加等待，不会增加诊断证据。

从启动 Claude Code 的同一个环境测试

“同一个环境”是排查是否有效的关键。浏览器能打开 claude.ai，不代表 WSL、SSH、VS Code Remote、容器或公司终端能访问 api.anthropic.com。

先运行 host 测试，再只查看与路线有关的变量：

bash
curl -I https://api.anthropic.com
env | grep -Ei '^(ANTHROPIC_BASE_URL|ANTHROPIC_API_KEY|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|NODE_EXTRA_CA_CERTS)='

如果输出中包含 Key 或代理密码，不要复制到工单、群聊或截图里。你只需要确认变量是否存在，以及它选择了哪个 host、代理或证书文件。

curl -I 成功只证明基础 host 可达，并不证明账号、完整 Messages 请求、模型或中转配置正确。它的价值是把问题切成两半。

curl 也失败：修 DNS、防火墙、VPN 或出口

先看实时状态页，但状态绿色不等于每个地区、运营商和企业出口都正常。然后只改变一个网络条件：

1. 用另一条可信网络做同一条 curl 测试，例如手机热点、家庭网络或组织批准的备用出口。
2. 如果 VPN 正在运行，断开后只测一次；如果组织规定必须走 VPN，则让网络管理员验证 allowlist，不要绕过安全策略。
3. 确认防火墙允许 Anthropic 网络访问要求列出的目标，至少要能访问当前实际使用的 API host。
4. Linux 或 WSL 中检查 /etc/resolv.conf 是否引用了不可达 nameserver。Windows 浏览器正常，不代表 WSL resolver 正常。
5. DNS 能解析但 443 超时，就查防火墙、路由器、代理和出口，不要先换 API Key。

ECONNREFUSED 常见于实际目标或本地代理端口拒绝连接；此时要确认是否真的直连 Anthropic，还是 ANTHROPIC_BASE_URL 或代理把请求发到了别处。ECONNRESET 表示连接曾建立后被重置，更应该对照 VPN、TLS 检查设备、网络稳定性和长连接策略。

企业代理与自定义 CA 要一起验证

Claude Code 在启动时读取标准代理变量：

bash
export HTTPS_PROXY=https://proxy.example.com:8080
export NO_PROXY=".example.internal"
claude

代理 scheme、host 和端口必须使用组织提供的真实值。Claude Code 不支持 SOCKS proxy。如果公司代理会做 TLS inspection，应使用组织批准的 CA bundle：

bash
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
claude

不要设置 NODE_TLS_REJECT_UNAUTHORIZED=0 来“解决”证书错误，这会关闭 TLS 校验。也不要把带用户名和密码的代理 URL 写进仓库脚本。完整的变量、CA store、Desktop 与后台进程范围差异见官方 企业网络配置。

注意，Claude Code 启动后再 export 变量，正在运行的进程不会自动拾取。修改代理或 CA 后要重启。Desktop 管理的会话、云端会话和后台 supervisor 还可能不读取当前 shell 的变量；用 /status 和 debug log 验证实际加载结果。

curl 成功但 Claude Code 失败：查真实路线

在 Claude Code 内运行 /status，确认当前凭据、provider、proxy 与 endpoint 是否符合预期，然后逐项隔离：

• 意外的 Key 路线：环境里的 ANTHROPIC_API_KEY 可能让会话使用 API Key，而不是你以为的订阅登录。只确认变量存在，不要打印 Key。
• 意外的中转路线：ANTHROPIC_BASE_URL 会改变目标 host。官方直连与第三方中转是两个系统，应在合规前提下分别验证。
• WSL 或远程 IDE：分别在 Windows/macOS host、WSL 与实际 VS Code Remote shell 运行同一条 curl；它们可能有不同的 DNS、代理和证书库。
• macOS 残留 VPN 路线：卸载或断开 VPN 后仍可能留下 utun interface 或 network extension。先在系统设置核对，不要删除不理解的路由。
• Docker Desktop 或其他 runtime：它们可能拦截出站流量。在不影响工作数据的前提下退出一次做对照。
• 后台进程：长期运行的 supervisor 可能继承了另一个 shell 的旧环境。把必要的网络变量放到官方支持的用户或 managed settings 范围。

如果不知道哪个认证或 provider 正在生效，先用 Claude Code API 配置指南梳理优先级，再修改配置。

用最小请求验证恢复

每次只改一个条件，重启 Claude Code，然后发送一个不含敏感内容的小请求。以下三项同时成立，才算修复：

1. 同一个 shell 仍能从官方 host 或组织批准的网关收到 HTTP 响应。
2. /status 显示预期认证与路线。
3. Claude Code 能完成新请求，不再出现相同连接错误。

如果错误变成 HTTP 状态，这是有效进展，说明传输路线已经到达 API 层。按实际返回跳到 Claude Code API Error 500、Claude API 529 overloaded或 Claude API 限流错误。既然服务器已经返回分类错误，就不要继续无目的切换网络。

仍失败时只提交脱敏证据

记录时间与时区、操作系统、Claude Code 版本、完整错误后缀、路线类型、curl -I 是否收到 HTTP 响应、当时状态页结果，以及只改变一个网络/代理条件后的结果。只有在不涉及私有地址时，才记录 ANTHROPIC_BASE_URL 的 host。

不要提交 API Key、OAuth token、代理密码、私有 prompt、客户数据或完整环境变量。官方路线可通过 Help Center 或可用时的 /feedback 升级；企业网络或中转路线则把同一份脱敏材料发给实际平台 owner。

最终判断规则只有三句：同终端 curl 失败，修到 host 的路径；curl 成功但 Claude Code 失败，修进程实际加载的环境；拿到 HTTP 错误后，离开连接分支处理返回状态。