Mac 上 Claude Code 中的“Unable to connect to API”

请求无法到达 api.anthropic.com 时,Claude Code 会打印 Unable to connect to API。Claude Code 文档列出的常见原因有:没有联网、VPN 阻止了该主机,或者没有设置企业代理。

让你的智能体来解决拷贝一条提示词,适用于 Claude Code、Codex 或任何能使用终端的智能体。

我的 Mac 出现了这个问题:Mac 上 Claude Code 中的“Unable to connect to API”。请阅读 https://kilobat.app/zh-hans/guides/claude-code-unable-to-connect-to-api.md,并和我一起逐步处理。如果缺少 Kilobat CLI,请安装:brew install seifip/kilobat/kilobat。请你自己运行指南中的终端和 kilobat 检查,并告诉我发现了什么。列出只有我才能完成的步骤。更改任何设置之前先问我。

适用于:所有当前 macOS 版本上终端里的 Claude Code。核查日期:2026年10月29日

症状

  • Claude Code 打印 Unable to connect to API. Check your internet connection。
  • 消息末尾可能带有代码,例如 ENOTFOUND、EHOSTUNREACH 或 ECONNRESET。
  • 请求失败,但其他 App 可能正常。

可能的原因

  • 没有联网。Mac 处于离线状态,或者没有 DNS。
  • VPN 阻止了 API 主机。Claude Code 文档把它列为常见原因。
  • 没有设置代理。必须使用企业代理时,需要在启动前设置 HTTPS_PROXY。
  • 代理拒绝了隧道。ERR_PROXY_TUNNEL 表示代理拒绝了隧道。请检查它的凭据,以及它是否允许访问这个主机。

如何检查

  1. 在同一个 shell 中测试 API 主机。

    curl -I https://api.anthropic.com
  2. 显示代理环境变量。

    env | grep -i proxy
  3. 在 Claude Code 内运行检查。

    /doctor
  4. 通过 macOS 测试主机名。

    dscacheutil -q host -a name api.anthropic.com

如何修复

  1. 如果 DNS 失败,请先修复。参见Mac 上 DNS 无法解析。

  2. 如果在企业代理之后,请在启动前设置它。

    export HTTPS_PROXY=http://proxy.example.com:8080
  3. 如果你使用网关,请把 ANTHROPIC_BASE_URL 设为它的地址。

  4. 为了测试,暂时关闭 VPN,之后再打开。

使用 Kilobat

  1. Kilobat 的连接诊断会逐层测试 API 主机:网络、代理、DNS、规则、IPv4、IPv6、TLS 和服务器。

    kilobat why https://api.anthropic.com
  2. Kilobat 的这些检查都是免费的。AI 智能体可以通过 MCP 用 diagnose_connection 和 diagnose_network 运行它们。请参阅找出某个网站或 API 连不上的原因。

常见问题

括号里的代码重要吗?

重要。ENOTFOUND 指向 DNS,EHOSTUNREACH 指向路由,ECONNRESET 指向连接被重置,ERR_PROXY_TUNNEL 指向代理。

设置变量后需要重启 Claude Code 吗?

需要。网络配置页面说明,正在运行的会话不会读取之后对 shell 所做的更改。

参考资料

核查日期:2026 年 10 月 29 日。