目录
在公司电脑上或通过 VPN 使用 Claude Code 时，是否遇到过类似下面这些错误而连不上的情况？
Unable to connect to API. Check your internet connection
Unable to connect to API (ECONNREFUSED)
Unable to connect to API: SSL certificate verification failed.
Check your proxy or corporate SSL certificates
fetch failed这些都是网络类错误，意思是 「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 确认「到底能不能到达」——这是排查的起点。
请求根本没到达服务器
— 在哪里停住，就决定了怎么修
HTTPS_PROXYNODE_EXTRA_CA_CERTS
先运行 curl -I https://api.anthropic.com 确认 能否到达。
一旦弄清在哪里停住（代理 / TLS / 防火墙），要应用的设置就确定了。
1. 这个错误到底在告诉你什么
Unable to connect to API、fetch failed、ECONNREFUSED / ETIMEDOUT 的意思是 「请求没有到达 Anthropic 的服务器」＝在 TCP/TLS/DNS 的某个环节失败了。这正是它与其他错误的决定性区别：认证（401/403）、服务器（529/500）、速率（429）都是「到达服务器之后」的响应，而网络类错误意味着 请求根本没到。
在企业网络中，典型的阻断点分为三层。（1）代理——无法直接外联，必须经过未配置好的企业代理。（2）TLS 检查（证书）——像 Zscaler 这样的检查代理会替换证书，因此必须 信任企业根 CA。（3）防火墙——所需域名没有被放行。首先要做的就是 用 curl -I https://api.anthropic.com 确认「能否到达」——单凭这一项检查，就能把「网络问题」和「其他一切」区分开来。
在哪里停住＝应用哪个设置
ECONNREFUSED/ETIMEDOUT/fetch failed。必须经过企业代理 → 设置 HTTPS_PROXY。SSL certificate verification failed/self-signed → 把企业 CA 放进 NODE_EXTRA_CA_CERTS。绝不要关闭验证。Could not resolve host/ENOTFOUND。DNS 不通、VPN 残留，或 Docker 拦截流量。
如果 curl -I https://api.anthropic.com 成功，问题就缩小到 Claude Code 与网络之间。
2. 代理设置（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 指向它。此外，如果你使用 MCP 服务器，必须 在每个服务器的 env 中显式设置 HTTPS_PROXY 和 NODE_EXTRA_CA_CERTS（它们不会从父进程继承）。这些变量也可以写在 settings.json 的 env 块中。
3. TLS 与企业 CA 证书（最重要，安全地处理）
企业网络中最常见的阻断，是 TLS 检查代理（Zscaler、Netskope、Palo Alto 等）替换证书 所导致的证书错误。典型消息是 unable to get local issuer certificate 和 SELF_SIGNED_CERT_IN_CHAIN。
需要说明的是，近期的 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。
4. 防火墙允许的域名
如果你的防火墙限制了访问目标，请 通过 HTTPS（443）放行以下域名（依据官方的网络要求）。
| 域名 | 用途 |
|---|---|
api.anthropic.com | Claude API 请求（必需） |
claude.ai | claude.ai 账户认证 |
platform.claude.com | Console 账户认证 |
downloads.claude.ai | 安装程序、自动更新、插件 |
raw.githubusercontent.com | 发布说明、市场 |
遥测（statsig.anthropic.com）和错误上报（*.sentry.io）是 可选的，可以禁用（无需把它们加入必需的允许列表）。如果你通过 npm 自行管理安装，可能不需要 downloads.claude.ai。具体的域名和 IP 范围可能会被修订，因此请 在官方的网络配置页面确认最新内容。
5. 排查工作流
连不上时，请自上而下逐步排查。第一条 curl 基本就能确定方向。
自上而下逐层定位
curl -I https://api.anthropic.com（Windows 用 curl.exe）测试可达性。如果通过，问题就在你这一侧。/doctor（若无法启动则用 claude doctor），并检查 代理环境变量。NODE_EXTRA_CA_CERTS；未设置代理 → 应用 HTTPS_PROXY。curl 通过但 Claude Code 失败，怀疑是 DNS（WSL 的 resolv.conf）、VPN 残留，或 Docker 拦截了流量。
铁则：「先测试可达性（curl），再为停住的那一层应用对应设置」。
证书用 NODE_EXTRA_CA_CERTS 处理。绝不关闭验证。
6. 与相似错误的区分
「停住了」也可能不是网络问题。最大的分界是 「请求是否到达了服务器？」
| 症状 | 真正的问题 | 主要对策 |
|---|---|---|
| Unable to connect / fetch failed / 证书错误 | 本文＝网络（没有到达服务器） | HTTPS_PROXY / NODE_EXTRA_CA_CERTS / 防火墙放行 |
| 401 / 403 / Invalid API key | 认证（已到达，但凭据有问题） | 认证 / 登录错误 |
| 529 / 500 | 服务器端（已到达，但过载 / 内部错误） | 529/500 错误 |
| 429 Request rejected | 速率限制（已到达，但流量过大） | 放慢、等待 |
记忆要诀：网络类错误意味着「请求没有到达服务器」（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 检查和防火墙。
对策如下：（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. 出现「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 和 platform.claude.com（认证）、downloads.claude.ai（安装程序/更新）以及 raw.githubusercontent.com。遥测（statsig）和错误上报（sentry）是可选的。具体的域名/IP 可能会被修订，因此请在官方的网络配置页面确认最新内容。
Q. curl 能通，但只有 Claude Code 连不上。
A. 原因常在 Claude Code 与操作系统之间。常见情形：WSL 的 /etc/resolv.conf 指向了一个失效的 DNS、VPN 残留（例如 macOS 上旧的 utun 接口），或 像 Docker 这样的常驻工具拦截了流量。请按以下顺序排查：关闭 VPN 直连、停掉常驻工具、检查 DNS。另外请注意，临时性的 5xx 错误最多会自动重试 10 次，所以当 curl 成功而你却看到错误时，重试次数其实已经用尽了。
