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-hant/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 日。