Mac Claude Code의 “Unable to connect to API”

Claude Code는 요청이 api.anthropic.com에 도달하지 못하면 Unable to connect to API를 출력합니다. Claude Code 문서는 인터넷에 접속되지 않음, 호스트를 차단하는 VPN, 설정하지 않은 기업 프록시를 흔한 원인으로 꼽습니다.

에이전트로 해결하기Claude Code, Codex 또는 터미널을 쓸 수 있는 에이전트용 프롬프트를 복사합니다.

제 Mac에 이런 문제가 있습니다: Mac Claude Code의 “Unable to connect to API”. https://kilobat.app/ko/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 같은 코드가 붙을 수 있습니다.
  • 요청은 실패하지만 다른 앱은 작동할 수 있습니다.

가능한 원인

  • 인터넷 접속 없음. Mac이 오프라인이거나 DNS가 없습니다.
  • API 호스트를 차단하는 VPN. Claude Code 문서는 이를 흔한 원인으로 꼽습니다.
  • 설정하지 않은 프록시. 필요한 기업 프록시는 실행하기 전에 HTTPS_PROXY이 필요합니다.
  • 터널을 거부하는 프록시. ERR_PROXY_TUNNEL은 프록시가 터널을 거부했다는 뜻입니다. 자격 증명과 이 호스트를 허용하는지 확인하세요.

확인 방법

  1. 같은 셸에서 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를 다시 시작해야 하나요?

네. 네트워크 구성 페이지에 따르면 실행 중인 세션은 이후의 셸 변경 사항을 반영하지 않습니다.

출처

2026년 10월 29일 확인했습니다.