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

> 从启动 Claude Code 的同一个终端测试 API host，再根据结果只修 DNS、代理、证书、环境或中转中的一个故障分支。

- URL: https://blog.laozhang.ai/zh/posts/claude-api-error-connection-error
- Published: 2026-08-04
- Updated: 2026-08-04
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: Claude Code
- Tags: Claude Code, Unable to connect to API, ECONNRESET, 代理, 故障排查

---
Claude Code 显示 `Unable to connect to API`，表示它没有完成到当前 API 路线的 TCP 连接。这和服务器已经返回 `401`、`429`、`500` 或 `529` 不是一类问题。先查看实时 [Claude Status](https://status.claude.com/)，再从启动 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。

| 终端后缀 | 更可能的故障边界 | 第一动作 |
| --- | --- | --- |
| `ECONNREFUSED` | 目标 host 或本地代理明确拒绝连接 | 核对实际 endpoint 和代理地址 |
| `ECONNRESET` | 已建立的连接被网络设备、VPN、代理或远端重置 | 用另一条可信网络做一次对照 |
| `ETIMEDOUT` | 连接未在期限内完成 | 检查 DNS、防火墙、代理与出口延迟 |
| `fetch failed` | 上层网络请求失败，尚未拿到 API 响应 | 继续看下一行原因并做同终端测试 |
| 证书或 self-signed certificate | 企业 TLS 检查或缺少受信 CA | 安装组织批准的 CA bundle |
| 已有 HTTP 状态与 JSON 错误体 | 请求已经到达某个 API 层 | 离开连接分支，按返回状态处理 |

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

## 先确认它确实是连接错误

![Claude Code 与 curl 结果的诊断矩阵](https://blog.laozhang.ai/posts/zh/claude-api-error-connection-error/img/route-matrix.webp)

Anthropic 当前的 [Claude Code 错误参考](https://code.claude.com/docs/zh-CN/errors)把 `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`（v2.1.227 起显示为 `Connection lost mid-response`）：Claude 已经开始输出，保留完整内容块，再从最后完成的位置继续；不要把它误判成从未连接。这条提示保留了什么、怎么按日志判断原因，见 [Claude Code 报错 Connection closed mid-response](https://blog.laozhang.ai/zh/posts/claude-code-connection-closed-mid-response)。

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 结果 | Claude Code 结果 | 优先检查 |
| --- | --- | --- |
| 无法解析 host | 同样失败 | DNS 或 WSL resolver |
| 443 端口超时/无法连接 | 同样失败 | 防火墙、VPN、代理或出口路线 |
| 证书校验失败 | 同样失败 | 企业 TLS inspection 与 CA trust |
| 能收到任意 HTTP 响应 | 仍显示连接错误 | Claude Code 进程环境、配置范围或中转 |
| 能收到响应 | 返回 401/429/500/529 | 已不是纯连接错误 |

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

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

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

1. 用另一条可信网络做同一条 curl 测试，例如手机热点、家庭网络或组织批准的备用出口。
2. 如果 VPN 正在运行，断开后只测一次；如果组织规定必须走 VPN，则让网络管理员验证 allowlist，不要绕过安全策略。
3. 确认防火墙允许 Anthropic [网络访问要求](https://code.claude.com/docs/zh-CN/network-config#network-access-requirements)列出的目标，至少要能访问当前实际使用的 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 经过企业代理和自定义 CA 的信任路径](https://blog.laozhang.ai/posts/zh/claude-api-error-connection-error/img/proxy-ca-path.webp)

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 与后台进程范围差异见官方 [企业网络配置](https://code.claude.com/docs/zh-CN/network-config)。

注意，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 配置指南](https://blog.laozhang.ai/zh/posts/claude-code-api-configuration)梳理优先级，再修改配置。

## 用最小请求验证恢复

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

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

如果错误变成 HTTP 状态，这是有效进展，说明传输路线已经到达 API 层。按实际返回跳到 [Claude Code API Error 500](https://blog.laozhang.ai/zh/posts/claude-code-500-529-rate-limit)、[Claude API 529 overloaded](https://blog.laozhang.ai/zh/posts/claude-api-error-529-overloaded)或 [Claude API 限流错误](https://blog.laozhang.ai/zh/posts/claude-rate-exceeded-error)。既然服务器已经返回分类错误，就不要继续无目的切换网络。

## 仍失败时只提交脱敏证据

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

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

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

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-08-04。

- [Claude Status](https://status.claude.com/) (status.claude.com)
- [Claude Code 错误参考](https://code.claude.com/docs/zh-CN/errors) (code.claude.com)
- [网络访问要求](https://code.claude.com/docs/zh-CN/network-config) (code.claude.com)