目录

在公司电脑上或通过 VPN 使用 Claude Code 时，是否遇到过类似下面这些错误而连不上的情况？

# 现在的显示（示例）
Can't reach the API server — check your internet or DNS (ENOTFOUND)
Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)
Unable to connect to API. Check your internet connection
Unable to connect to Anthropic services
fetch failed

# 旧版本的显示
Unable to connect to API (ECONNREFUSED)
Unable to connect to API: SSL certificate verification failed.
  Check your proxy or corporate SSL certificates

显示的文案因版本而异。从 v2.1.227 起，以前只在后面附上代码的消息（如 Unable to connect to API (ECONNREFUSED)），改为先说明失败类型，如 Connection refused — 或 Can't reach the API server —（对照表见 §2）。无论看到哪种文案，发生的事情和解决方法都一样。

这些都是网络类错误，意思是 “Claude Code 无法到达 Anthropic 的服务器（api.anthropic.com）”。它们 既不是认证问题（401/403），也不是服务器过载（529/500），更不是速率限制（429）——请求 根本就没有到达服务器。常见原因是 企业代理、TLS 检查（证书）以及防火墙，因此在企业网络中尤其容易出现。本文将基于官方信息，整理 代理设置、企业 CA 证书、需要放行的域名以及排查步骤。

先说要点。（1）在代理后面时，设置 HTTPS_PROXY。（2）如果是 TLS 检查（Zscaler 等）导致的证书错误，把 NODE_EXTRA_CA_CERTS 指向企业 CA——并且 绝对不要用 NODE_TLS_REJECT_UNAUTHORIZED=0 关闭验证（这会让所有流量暴露在被拦截的风险下）。（3）首先运行 curl -I https://api.anthropic.com 确认“到底能不能到达”——这是排查的起点。

CLAUDE CODE · NETWORK / PROXY

请求根本没到达服务器

— 在哪里停住，就决定了怎么修

Claude Code
请求
→✗
代理 / TLS / 防火墙
常在这里被阻断
→
api.anthropic.com
代理
HTTPS_PROXY
TLS 证书
NODE_EXTRA_CA_CERTS
防火墙
api.anthropic.com 等

先运行 curl -I https://api.anthropic.com 确认 能否到达。
一旦弄清在哪里停住（代理 / TLS / 防火墙），要应用的设置就确定了。

1. 这个错误到底在告诉你什么

Unable to connect to API、fetch failed、ECONNREFUSED / ETIMEDOUT（v2.1.227 起改为 Connection refused — 等文案，见 §2） 的意思是 “请求没有到达 Anthropic 的服务器”=在 TCP/TLS/DNS 的某个环节失败了。这正是它与其他错误的决定性区别：认证（401/403）、服务器（529/500）、速率（429）都是“到达服务器之后”的响应，而网络类错误意味着 请求根本没到。

在企业网络中，典型的阻断点分为三层。（1）代理——无法直接外联，必须经过未配置好的企业代理。（2）TLS 检查（证书）——像 Zscaler 这样的检查代理会替换证书，因此必须 信任企业根 CA。（3）防火墙——所需域名没有被放行。首先要做的就是 用 curl -I https://api.anthropic.com 确认“能否到达”——单凭这一项检查，就能把“网络问题”和“其他一切”区分开来。

3 LAYERS

在哪里停住=应用哪个设置

1）未设置代理
ECONNREFUSED/ETIMEDOUT/fetch failed。必须经过企业代理 → 设置 HTTPS_PROXY。
2）TLS 检查导致证书错误
SSL certificate verification failed/self-signed → 把企业 CA 放进 NODE_EXTRA_CA_CERTS。绝不要关闭验证。
3）防火墙阻断域名
所需域名未放行 → 放行 api.anthropic.com 等（§5）。
4）DNS / VPN / 本地工具
Could not resolve host/ENOTFOUND。DNS 不通、VPN 残留，或 Docker 拦截流量。

如果 curl -I https://api.anthropic.com 成功，问题就缩小到 Claude Code 与网络之间。

2. 各条消息的含义（v2.1.227 起的文案）

根据官方的错误参考，这一类消息表示 与 API 的 TCP 连接失败或未能完成。对于常见的错误代码，消息会 用文字说明失败类型，并把代码保留在括号里。现在的显示如下：

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)
fetch failed
Request timed out. Check your internet connection and proxy settings

在 v2.1.227 之前，这些带代码的消息都是 Unable to connect to API 加代码（例如 Unable to connect to API (ECONNREFUSED)）。Claude Code 不认识的代码，现在仍以这种形式显示。另外，同一条消息可能带不同的代码：Connection refused 会显示 ConnectionRefused 或 ECONNREFUSED，Can't reach the API server 会显示 ENOTFOUND 或 FailedToOpenSocket。

消息开头消息表示什么先检查什么
Connection refused —连接被拒绝，可能是防火墙或代理在拦截允许列表（§5）和 HTTPS_PROXY（§3）
Can't reach the API server —无法到达 API 服务器，怀疑网络连接或 DNSDNS 和 VPN；WSL 下检查 /etc/resolv.conf（§6）
No internet route —没有到达目标的路由线路和 VPN 的连接状态
Couldn't connect through your proxy代理拒绝建立隧道代理的凭据，以及是否放行目标主机
Connection dropped连接被重置（ECONNRESET）代理与网络的稳定性

无论出现哪条消息，临时性故障都会自动重试，所以它显示在屏幕上时，重试已经用完了。如果反复出现，原因就在你本地的网络。官方列举的常见原因有：无法访问互联网、VPN 拦截了 api.anthropic.com、必需的企业代理没有配置。解决方法见 §3–§6。

Unable to connect to Anthropic services（首次设置）

首次启动的设置中，Claude Code 会在显示登录步骤之前，检查能否到达 api.anthropic.com 和 platform.claude.com。任何一项检查失败，都会显示原因并退出。官方示例：

Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ECONNREFUSED
Connection to api.anthropic.com timed out after 10 seconds
A proxy is configured via HTTPS_PROXY. Check that it allows connections to the host above.

这项检查与 API 请求走同一套代理配置，每次探测限时 10 秒。如果失败的探测经过了代理，消息会写出配置该代理的环境变量名（如 HTTPS_PROXY）。处理方法：

  • 确认所显示的变量指向正确的代理，并请网络管理员允许经由它访问消息中主机的 HTTPS 连接（允许列表见 §5）
  • 在同一个 shell 中用 §6 的 curl 做可达性检查
  • 如果在以 https:// 开头的代理 URL 下一直停在 Checking connectivity...，可能是 v2.1.222 之前的缺陷（检查走的路径与 API 请求不同，而且没有超时）。请更新
  • 如果你的组织通过云网关（Claude apps gateway）登录，却在首次启动时出现此错误，请更新到 v2.1.247 或更高版本

如果网络是通的而故障仍在，官方指出 Claude Code 可能在你所在的国家或地区不可用。请查看 支持的国家和地区列表。

Streaming response ended before any complete data was received

Streaming response ended before any complete data was received. Retrying without streaming. If this keeps happening, check any proxy or gateway between Claude Code and your model provider.

这条警告 不是“没有到达”，而是“中间的设备改动了响应”。模型提供商的流式响应在没有交付任何可用数据的情况下就结束了，所以 Claude Code 改用非流式方式重新发送请求，以完成这一轮。每个受影响的请求会发送 两次：空的流式尝试和重发。根据官方说明，常见原因是代理或网关在途中消耗或转换了流式响应的正文，解决方法是把 Claude Code 与模型提供商之间的代理或网关配置为 原样透传流式响应的正文和响应头。这条警告只在交互式会话中出现，每个会话一次。在 v2.1.239 之前，Claude Code 会不作提示地改用非流式重试。

3. 代理设置（HTTPS_PROXY）

当必须经过企业代理时，请设置 标准代理环境变量。Claude Code 会遵循它们。

# 推荐：HTTPS 代理
export HTTPS_PROXY=http://proxy.example.com:8080
# 如果没有 HTTPS，使用 HTTP_PROXY
export HTTP_PROXY=http://proxy.example.com:8080
# 绕过代理的目标（用空格或逗号分隔）
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

# 带认证的代理（避免硬编码密码）
export HTTPS_PROXY=http://username:password@proxy.example.com:8080

注意事项：不支持 SOCKS 代理。对于 NTLM / Kerberos 认证的代理，官方推荐的做法是在中间架设一个 LLM gateway，并把 ANTHROPIC_BASE_URL 指向它。这些变量也可以写在 settings.json 的 env 块中。

4. TLS 与企业 CA 证书（最重要，安全地处理）

企业网络中最常见的阻断，是 TLS 检查代理（Zscaler、Netskope、Palo Alto 等）替换证书 所导致的证书错误。典型消息是 unable to get local issuer certificate 和 SELF_SIGNED_CERT_IN_CHAIN。

从 v2.1.273 起，Claude Code 自己的消息会包含错误代码和解决方法。会话中的 API 请求会显示：

Unable to connect to API: SSL certificate verification failed (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config
Unable to connect to API: Self-signed certificate detected (SELF_SIGNED_CERT_IN_CHAIN). The certificate comes from an authority Claude Code doesn't trust, usually a TLS-inspecting corporate proxy or a gateway signed by a private CA: set NODE_EXTRA_CA_CERTS to that CA bundle, or add it to the system certificate store · see https://code.claude.com/docs/en/network-config

在 /login 过程中以及启动时的连接检查中，同样的失败会显示为另一种文案：

SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run `claude doctor` for details.

在 v2.1.273 之前，前两条消息都以 Check your proxy or corporate SSL certificates 结尾，没有代码，也没有 NODE_EXTRA_CA_CERTS 的提示（即文章开头的旧显示）。另外，从 v2.1.199 起，证书验证失败不再自动重试，错误会 在第一次尝试时 就显示（更早的版本会先重试几分钟）。握手超时这类临时性的 TLS 故障，现在仍会重试。

需要说明的是，近期的 Claude Code 会同时信任“自带的 CA 集合”和“操作系统的信任库”。所以 如果企业根 CA 已经在操作系统的证书存储中，往往无需额外配置即可工作（不同版本行为可能不同，请确认最新情况）。如果它不在操作系统存储中，把 NODE_EXTRA_CA_CERTS 指向 IT 部门给你的 CA 包（PEM）：

# 正确、安全的做法：信任企业 CA
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

# 如果代理要求客户端证书（mTLS）
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem

⚠️ 绝对不要：关闭 TLS 验证

用 NODE_TLS_REJECT_UNAUTHORIZED=0 关闭证书验证看似能“修好”，但 绝对不要这么做。它会让整个进程的 TLS 验证失效，于是 所有流量——包括发往 api.anthropic.com 的——都会暴露在中间人攻击（窃听、篡改）之下。这有泄露凭据和代码的风险。正确答案永远是 “通过 NODE_EXTRA_CA_CERTS 正确地信任企业 CA”。

如果在安装阶段（二进制文件还不存在时）就遇到证书错误，可以把 CA 传给 curl：curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash。

OAuth error: SSL certificate error (CERT_HAS_EXPIRED)

在登录（/login 的 OAuth 步骤）途中，可能会出现下面的提示并停住。以下是用户在 GitHub issue 中报告的原文：

OAuth error: SSL certificate error (CERT_HAS_EXPIRED). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run /doctor for details.

这条提示不在官方的错误列表中。官方 SSL certificate errors 一节举例的代码只有 UNABLE_TO_GET_ISSUER_CERT_LOCALLY 和 SELF_SIGNED_CERT_IN_CHAIN；过期证书只在自动重试的说明里作为“证书校验失败”的一个例子被顺带提到。上面的文字来自 GitHub issue #71708 和 #71727（均为2026年6月）中用户的报告。

CERT_HAS_EXPIRED 的含义：这是 Node.js 的 TLS 返回的证书错误代码之一，Node.js 官方文档将其描述为“Certificate has expired”（证书已过期）。也就是说，对从服务器收到的证书进行校验后，判定它已超过有效期。有效期是拿本机的时钟来比对的。

报告的内容：两个 issue 的报告者都写道，没有使用代理或 VPN，而且用 curl 访问同一主机没有问题（#71708 的报告者还确认了电脑时钟是正确的）。也就是说，在提示本身所说的“企业代理、TLS 检查”都不适用的环境里，它也会出现。报告者怀疑是 Claude Code 内置的运行时的问题，有多条评论说退回旧版本后就好了。但两个 issue 里都没有 Anthropic 的答复，且都因长期无动静而被关闭。原因并未得到官方确认。截至2026年9月30日，官方 CHANGELOG 中也找不到明确写着修复了这一症状的条目。

按顺序检查：

  1. 电脑时钟：日期、时间、时区是否正确。时钟偏差很大时，即使证书有效也可能被判定为过期。
  2. 公司代理的证书：如果流量经过会做 TLS 检查的代理或安全产品，请向 IT 部门确认它插入的证书（包括企业 CA）是否已过期。
  3. NODE_EXTRA_CA_CERTS：如果需要信任企业 CA，请按官方网络配置页面的说明，用 NODE_EXTRA_CA_CERTS 指定 IT 部门提供的 CA 证书包（上文的步骤）。是否已加载，可以在 claude --debug 日志中找 CA certs: Appended extra certificates from NODE_EXTRA_CA_CERTS 这一行来确认。
  4. 仍然出现时：如果时钟正确、没有代理，且 curl -I https://platform.claude.com 能通，那可能和上面 GitHub 的报告是同一种情况。先把 Claude Code 更新到最新，再查看 issue 的讨论和更新日志。issue 里也有人说用 NODE_TLS_REJECT_UNAUTHORIZED=0 就能通过，但如上方提示框所述，这会彻底关闭校验，不要使用。

5. 防火墙允许的域名

如果你的防火墙限制了访问目标，请 通过 HTTPS（443）放行以下主要域名（依据官方的网络要求；如果使用 MCP 连接器、插件等，还需要官方列表中的其他主机）。

域名用途
api.anthropic.comClaude API 请求（必需）
claude.aiclaude.ai 账户认证
claude.com用 claude.ai 账户登录时浏览器打开的页面（会跳转到 claude.ai）
platform.claude.comConsole 账户认证；claude.ai 账户也用它来签发和刷新令牌（首次设置连接检查的对象）
downloads.claude.ai安装程序、自动更新、插件
raw.githubusercontent.com/release-notes 的更新日志

运行遥测和错误上报的目标主机（http-intake.logs.us5.datadoghq.com 和 browser-intake-us5-datadoghq.com）是 可选的，用 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 可以同时关闭两者（无需加入必需的允许列表）。如果通过 npm 安装，就不需要 downloads.claude.ai 中安装程序和自动更新的用途，但需要软件包仓库 registry.npmjs.org。具体的域名和 IP 范围可能会被修订，因此请 在官方的网络配置页面确认最新内容。

6. 排查工作流

连不上时，请自上而下逐步排查。第一条 curl 基本就能确定方向。

DIAGNOSE

自上而下逐层定位

1
用 curl -I https://api.anthropic.com（Windows 用 curl.exe）测试可达性。如果通过，问题就在你这一侧。
2
运行 /doctor（若无法启动则用 claude doctor），并检查 代理环境变量。
3
证书错误 → 应用 NODE_EXTRA_CA_CERTS；未设置代理 → 应用 HTTPS_PROXY。
4
尝试 直连（关闭 VPN/代理） 以确认代理是否为原因。向 IT 部门索取代理 URL 和 CA。
5
如果 curl 通过但 Claude Code 失败，怀疑是 DNS（WSL 的 resolv.conf）、VPN 残留，或 Docker 拦截了流量。

铁则：“先测试可达性（curl），再为停住的那一层应用对应设置”。
证书用 NODE_EXTRA_CA_CERTS 处理。绝不关闭验证。

7. 与相似错误的区分

“停住了”也可能不是网络问题。最大的分界是 “请求是否到达了服务器？”

症状真正的问题主要对策
Unable to connect / Connection refused / Can't reach the API server / fetch failed / 证书错误本文=网络（没有到达服务器）HTTPS_PROXY / NODE_EXTRA_CA_CERTS / 防火墙放行
401 / 403 / Invalid API key认证（已到达，但凭据有问题）认证 / 登录错误
529 / 500服务器端（已到达，但过载 / 内部错误）529/500 错误
429 Request rejected速率限制（已到达，但流量过大）放慢、等待
Connection lost mid-response（v2.1.227 之前为 Connection closed mid-response）流传输中被切断（已连上、响应也开始传输之后连接才关闭）回答中途被切断的错误（旧文案的文章）

记忆要诀：网络类错误意味着“请求没有到达服务器”（TCP/TLS/DNS），而 HTTPS_PROXY 或 NODE_EXTRA_CA_CERTS 只在这一层起作用。相比之下，401/403、529/500、429 都是“到达之后的响应”，所以调整代理或 CA 也修不好。curl 是否成功，是区分这两类的最佳信号。其他常见错误，请参见 错误汇总。

总结

Claude Code 的 网络/代理错误（Unable to connect / fetch failed / SSL certificate verification failed 等）意味着 请求根本没有到达服务器=TCP/TLS/DNS 失败。它们 与认证（401/403）、服务器（529/500）、速率（429）是不同的问题，常见祸首是企业网络的 代理、TLS 检查和防火墙。从 v2.1.227 起，它们改为先说明失败类型的文案，如 Connection refused — 或 Can't reach the API server —；首次设置时则以 Unable to connect to Anthropic services 退出。

对策如下：（1）在代理后面时，设置 HTTPS_PROXY（不支持 SOCKS；NTLM/Kerberos 通过 gateway）；（2）证书错误时，把企业 CA 放进 NODE_EXTRA_CA_CERTS——绝不要用 NODE_TLS_REJECT_UNAUTHORIZED=0；（3）在防火墙中放行 api.anthropic.com 等。 排查顺序：先用 curl -I https://api.anthropic.com 测试可达性 -> /doctor 并检查代理 -> 证书/代理设置 -> 直连确认 -> DNS/VPN/Docker。 关键在于 用“请求是否到达了服务器？”把网络问题与认证/服务器/速率问题区分开。相关：认证 / 登录错误、529/500 错误、Claude Code 错误汇总。

FAQ

Q. 在公司电脑上出现“Unable to connect to API”，无法连接。
A. 通常是 必须经过企业代理却没有配置好。先用 curl -I https://api.anthropic.com 检查可达性；如果失败，就像 export HTTPS_PROXY=http://proxy.example.com:8080 这样设置代理（带认证的代理加上 user:password@）。注意 不支持 SOCKS，对于 NTLM/Kerberos 代理，官方推荐通过 LLM gateway。

Q. “Can't reach the API server”“Connection refused”和以前的“Unable to connect to API”是不同的错误吗？
A. 属于同一类，只是在 v2.1.227 改了文案。以前只是附上代码，如 Unable to connect to API (ECONNREFUSED)；现在会先说明失败类型，如 Connection refused — a firewall or proxy may be blocking it (ConnectionRefused) 或 Can't reach the API server — check your internet or DNS (ENOTFOUND)。括号里的代码能提示原因，请在 §2 的表中查看对应的检查项。

Q. 首次启动时出现“Unable to connect to Anthropic services”，然后就退出了。
A. 它在登录前检查与 api.anthropic.com 和 platform.claude.com 连接的步骤中失败了。如果消息里写出了代理变量名（如 HTTPS_PROXY），请与网络管理员确认它的值，以及是否允许连接消息中的主机。也可以用 curl -I https://api.anthropic.com 检查可达性。如果网络是通的而问题仍在，官方指出 Claude Code 可能在你所在的国家或地区不可用，可以对照官方的支持国家列表确认。

Q. 出现“SSL certificate verification failed”。
A. 这通常是 企业 TLS 检查代理（例如 Zscaler）替换了证书。向 IT 部门索取 企业根 CA（PEM），并设置 export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem。如果企业 CA 已经在操作系统的证书存储中，可能无需配置即可工作。绝不要用 NODE_TLS_REJECT_UNAUTHORIZED=0 关闭验证——那会让所有流量暴露在被拦截的风险下。

Q. 设置 NODE_TLS_REJECT_UNAUTHORIZED=0 后修好了，这样可以吗？
A. 不行——请立刻还原。 它会 对整个进程关闭 TLS 证书验证，让所有流量——包括发往 api.anthropic.com 的——在中间人攻击（窃听、篡改）面前毫无防备。这是会泄露凭据和源代码的严重安全风险。唯一正确的修法是 通过 NODE_EXTRA_CA_CERTS 正确地信任企业 CA。

Q. 防火墙里应该放行哪些域名？
A. 通过 HTTPS（443），至少放行 api.anthropic.com（API）、claude.ai、claude.com 和 platform.claude.com（认证）、downloads.claude.ai（安装程序/更新）以及 raw.githubusercontent.com（更新日志）。运行遥测和错误上报（Datadog）是可选的。具体的域名/IP 可能会被修订，因此请在官方的网络配置页面确认最新内容。

Q. curl 能通，但只有 Claude Code 连不上。
A. 原因常在 Claude Code 与操作系统之间。常见情形：WSL 的 /etc/resolv.conf 指向了一个失效的 DNS、VPN 残留（例如 macOS 上旧的 utun 接口），或 像 Docker 这样的常驻工具拦截了流量。请按以下顺序排查：关闭 VPN 直连、停掉常驻工具、检查 DNS。另外请注意，临时性的 5xx 错误最多会自动重试 10 次，所以当 curl 成功而你却看到错误时，重试次数其实已经用尽了。

在将 Claude 以外的模型（DeepSeek、GLM、Kimi 等）的端点指向 ANTHROPIC_BASE_URL 时的设置、费用和注意事项，请参阅 在 Claude Code 中使用 DeepSeek、GLM、Kimi 的方法。