Claude Code API 연결 안 될 때 체크리스트 — SSL 인증서·프록시·QUIC까지

claude 실행했는데 Unable to connect to API (ETIMEDOUT)이나 fetch failed만 뜨고 아무것도 안 되는 상황, 회사 네트워크에서 특히 자주 겪습니다. 근데 이 에러 하나에 원인이 최소 서너 가지 섞여 있어서, 검색해서 나오는 해결법을 그대로 따라 해도 안 먹히는 경우가 많아요. 이 글은 Claude Code 공식 에러 레퍼런스와 네트워크 설정 문서를 기준으로, 실제로 자주 나오는 원인부터 순서대로 짚어봅니다. 마지막에는 드물지만 실제 보고된 QUIC 차단 케이스도 다룹니다.

 

Claude Code API 연결 안 될 때, 뭐부터 봐야 할까

공식 문서(code.claude.com/docs/en/errors)는 이 계열 에러의 원인을 "보통 로컬 네트워크, 프록시, 방화벽, 혹은 클라우드 환경의 네트워크 정책에서 시작된다"고 명시합니다. Claude Help Center도 비슷하게 "방화벽, 네트워크, VPN 문제일 가능성이 높다"고 안내하고요.

정리하면 우선순위는 이렇습니다. 1) SSL 인증서 검증 실패, 2) 프록시 미설정, 3) VPN 잔여 문제. 이 세 가지가 공식 문서에 명시된 흔한 원인이고, QUIC/UDP 443 차단은 GitHub에 실제 보고는 있지만 공식 문서 어디에도 등장하지 않는 비주류 케이스입니다. 순서대로 확인해보죠.

 

SSL 인증서 오류 — UNABLE_TO_GET_ISSUER_CERT_LOCALLY

회사 방화벽이나 Zscaler, CrowdStrike Falcon 같은 TLS 검사 프록시를 쓰는 환경에서 가장 흔하게 보는 에러입니다. 실제 GitHub 이슈(#43050)에 보고된 메시지 원문은 이렇습니다.

Failed to connect to api.anthropic.com: UNABLE_TO_GET_ISSUER_CERT_LOCALLY

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 /doctor for details.

원인은 회사 프록시가 TLS 트래픽을 가로채면서 자체 인증서로 갈아끼우는데, 그 인증서 체인을 Claude Code가 신뢰하지 못하는 겁니다. 공식 해결법은 조직 CA 번들을 지정하는 것.

export NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem

Claude Code는 기본적으로 번들된 Mozilla CA 인증서와 OS 인증서 저장소를 함께 신뢰합니다. CLAUDE_CODE_CERT_STORE 환경변수로 어느 쪽을 쓸지 조정할 수도 있어요.

export CLAUDE_CODE_CERT_STORE=bundled   # 번들 CA만 신뢰
export CLAUDE_CODE_CERT_STORE=system    # OS 신뢰 저장소만 신뢰

여기서 하나 주의할 게 있는데, NODE_TLS_REJECT_UNAUTHORIZED=0으로 인증서 검증을 아예 꺼버리는 방법은 공식 문서가 명시적으로 하지 말라고 경고합니다. 검증을 끄면 중간자 공격에 그대로 노출되니까요. 참고로 v2.1.199부터는 인증서 검증 실패가 재시도 없이 첫 시도에서 바로 표시됩니다. 예전 버전에서는 재시도 예산을 다 쓴 뒤에야 에러가 나서 원인 파악이 더 오래 걸렸다고 하네요.

 

프록시 미설정 — HTTPS_PROXY 확인하기

인증서 에러가 아니라 그냥 타임아웃(ETIMEDOUT)이나 연결 거부(ECONNREFUSED)만 뜬다면 프록시 설정 자체가 안 돼 있을 가능성이 높습니다. 회사 네트워크는 대부분 프록시를 거쳐야 외부로 나가는데, Claude Code는 표준 프록시 환경변수를 그대로 존중합니다.

export HTTPS_PROXY=https://proxy.example.com:8080   # 권장
export HTTP_PROXY=http://proxy.example.com:8080      # HTTPS 프록시 불가 시
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"

프록시에 기본 인증이 필요하면 URL 안에 자격증명을 넣으면 됩니다(http://username:password@proxy.example.com:8080). 다만 비밀번호를 스크립트에 그대로 박아두는 건 피하는 게 좋습니다. NTLM이나 Kerberos 같은 고급 인증 방식이 필요한 환경이면, 이걸 지원하는 LLM 게이트웨이 서비스를 쓰라고 공식 문서가 권장하고 있어요.

한 가지 알아둘 점은, Claude Code는 SOCKS 프록시를 지원하지 않는다는 겁니다. 회사에서 SOCKS5 프록시만 제공한다면 이 부분부터 IT팀과 확인해야 합니다.

 

VPN이 원인일 수도 있습니다

VPN 클라이언트를 껐다 켰다 하는 과정에서 라우팅 테이블이나 네트워크 인터페이스가 지저분하게 남는 경우가 있습니다. 공식 문서가 언급하는 macOS 사례를 보면, 연결 해제되었거나 이미 제거된 VPN 클라이언트가 터널 인터페이스를 그대로 남겨두는 일이 있다고 합니다. ifconfig로 오래된 utun 인터페이스가 남아있는지 확인하고, 시스템 설정에서 해당 VPN의 네트워크 확장을 지우는 게 공식 대응법입니다.

Claude Help Center는 더 간단하게, 요청 실행 시 VPN을 아예 꺼보라고 안내합니다. VPN을 끈 상태에서 정상 작동한다면 VPN 쪽 문제로 좁혀지는 거죠. Docker Desktop 같은 컨테이너 런타임도 아웃바운드 트래픽을 가로챌 수 있으니, 종료하고 재시도해보는 것도 공식 문서가 제시하는 체크 항목입니다.

 

curl로 먼저 확인하기 — 공식 대응 절차

원인을 하나씩 추측하기 전에, 같은 셸에서 curl로 API 호스트에 도달하는지부터 확인하는 게 순서입니다.

curl -I https://api.anthropic.com

Windows PowerShell에서는 내장 curl 별칭(사실은 Invoke-WebRequest)이 아니라 curl.exe -I https://api.anthropic.com로 실제 curl 바이너리를 호출해야 합니다. 이게 성공하는데 Claude Code만 실패한다면, 리졸버 설정 문제일 수 있습니다. 특히 WSL 환경은 /etc/resolv.conf에 호스트로부터 물려받은 깨진 네임서버가 남아있는 경우가 있다고 공식 문서가 짚고 있어요.

방화벽이 필요한 호스트를 다 허용하고 있는지도 확인해야 합니다. Claude Code가 접근해야 하는 URL은 api.anthropic.com(API 요청), claude.ai(계정 인증), downloads.claude.ai(설치·업데이트) 등입니다. LLM 게이트웨이나 릴레이를 쓰고 있다면 ANTHROPIC_BASE_URL을 해당 주소로 지정해야 하고요.

 

드문 케이스 — QUIC/UDP 443이 막힌 네트워크

여기까지 다 확인했는데도 원인을 못 찾겠다면, 조금 특이한 케이스도 하나 알아두면 좋습니다. GitHub 이슈 #49761에 보고된 사례인데, Claude Code(2.1.112, macOS)가 로그인 과정에서 이런 에러를 냈습니다.

OAuth error: The socket connection was closed unexpectedly. For more information, pass `verbose: true` in the second argument to fetch()

보고자가 tcpdump로 트래픽을 직접 캡처해보니, Claude Code가 api.anthropic.com 연결 시 QUIC(UDP 443)만 시도하고 TCP SYN 패킷은 아예 보내지 않았다고 합니다. 같은 네트워크에서 curl https://api.anthropic.com은 TCP HTTPS로 멀쩡히 작동했는데도요. 이슈 설명 원문을 그대로 옮기면 이렇습니다.

"The underlying Bun runtime appears to prefer QUIC/HTTP/3 and does not fall back to TCP HTTPS when QUIC fails, unlike curl and mainstream browsers which implement fallback behaviour."

즉 Claude Code가 쓰는 Bun 런타임이 QUIC을 우선 시도하는데, 이 경로가 막힌 네트워크에서는 curl이나 브라우저와 달리 TCP로 자동 폴백하지 않는다는 겁니다. 보고자는 macOS 방화벽(pf)으로 UDP 443을 강제로 차단해서 TCP 폴백을 유도하는 방식으로 우회했습니다.

echo "block out proto udp from any to 160.79.104.0/24 port 443" | \
  sudo tee /etc/pf.anchors/blockquic
sudo pfctl -a blockquic -f /etc/pf.anchors/blockquic
sudo pfctl -e

다만 이 이슈는 "Closed as not planned"로 종료됐고, Anthropic 공식 문서 어디에도 QUIC이나 HTTP/3이라는 단어가 등장하지 않습니다. 공식 수정 계획도 없는 상태고요. 회사 방화벽이 이미 UDP 443을 막고 있는 환경이라면 이론상 비슷한 효과가 날 수 있지만, 실제로는 UDP 443이 "일부만 손상"된 애매한 상태라 패킷이 조용히 드롭되면서 타임아웃만 반복되는 경우도 보고돼 있습니다. 프록시(HTTPS_PROXY)를 거치면 프록시가 보통 TCP만 처리하니 QUIC 자체를 우회하는 부수 효과가 있을 거라는 추론도 있는데, 이 부분은 Claude Code에서 실제로 검증된 사례를 찾지는 못했습니다. 앞의 프록시/인증서/VPN 체크를 다 해본 다음에야 고려할 만한 옵션으로 보는 게 맞습니다.

 

그래도 간헐적으로 끊긴다면 — 재시도 환경변수

원인을 찾았는데도 연결이 가끔 불안정하다면 재시도·타임아웃 관련 환경변수로 임시 대응할 수 있습니다.

변수	기본값	효과
CLAUDE_CODE_MAX_RETRIES	10	재시도 횟수
CLAUDE_CODE_RETRY_WATCHDOG	unset	1로 설정하면 429/529 용량 에러를 무한 재시도, v2.1.199부터는 다른 일시적 에러도 최대 300회까지 재시도
API_TIMEOUT_MS	600000	요청당 타임아웃(ms), 느린 프록시 환경에서는 상향 조정

단, TLS 인증서 검증 실패는 재시도 대상이 아닙니다. 인증서 문제면 재시도 횟수를 아무리 늘려도 소용없고, 위에서 다룬 NODE_EXTRA_CA_CERTS 설정으로 바로 해결해야 합니다.

 

자주 묻는 질문

Q. claude doctor는 정상인데 실행할 때만 에러가 나요.
GitHub 이슈 #43050 보고자도 같은 증상을 겪었습니다. doctor 명령의 점검 로직과 실제 API 요청 시 인증서 검증 로직이 완전히 같은 경로를 타지 않는 것으로 보이니, doctor 결과만 믿지 말고 curl -I https://api.anthropic.com으로 직접 확인하는 게 낫습니다.

Q. HTTPS_PROXY를 설정했는데도 안 됩니다.
프록시가 SOCKS 방식인지 먼저 확인하세요. Claude Code는 SOCKS 프록시를 지원하지 않습니다. NTLM/Kerberos 인증이 필요한 프록시도 별도 게이트웨이 없이는 안 됩니다.

Q. Amazon Bedrock이나 Google Cloud 쪽 게이트웨이를 쓰는데도 이 에러가 나요.
모델 트래픽과 인증은 해당 게이트웨이로 가지만, WebFetch 도구는 도메인 안전성 검사 때문에 skipWebFetchPreflight: true를 설정하지 않는 한 여전히 api.anthropic.com을 호출합니다. 이 부분이 막혀 있으면 게이트웨이 설정과는 별개로 에러가 날 수 있습니다.

이 정도만 순서대로 체크해봐도 대부분의 "API 연결 안 됨" 문제는 원인이 좁혀집니다. EACCES 계열 설치 오류를 따로 겪고 있다면 Claude Code EACCES 오류 해결법 글도 참고하면 되고, 컨텍스트 압축 루프처럼 연결과는 다른 종류의 먹통 증상이라면 Autocompact is thrashing 해결법에서 다룬 적이 있습니다. sandbox 권한 설정까지 손봐야 하는 상황이라면 Claude Code sandbox.credentials 설정 글도 도움이 될 겁니다.