IPv6 Happy-Eyeballs 미대응으로 인한 Claude Code API ConnectionRefused

증상

claude 실행 시 Unable to connect to API (ConnectionRefused) 에러로 재시도 루프에 빠짐. claude doctor는 이상 없음으로 보고 (설치/설정 문제 아님).

진단 과정

1. ANTHROPIC_BASE_URL, HTTP(S)_PROXY 확인 → 모두 비어있음 (커스텀 엔드포인트 문제 아님)
2. tailscale status 확인 → exit node 비활성 (Tailscale 라우팅 문제 아님)
3. curl -v https://api.anthropic.com/v1/messages 실행 → 원인 확인:

* IPv6: 2607:6bc0::10
* IPv4: 160.79.104.10
*   Trying [2607:6bc0::10]:443...
* Immediate connect fail for 2607:6bc0::10: 네트워크가 접근 불가능합니다
*   Trying 160.79.104.10:443...
* Connected to api.anthropic.com (160.79.104.10) port 443

근본 원인

DNS가 api.anthropic.com에 대해 IPv6/IPv4 주소를 모두 반환하는데, 로컬 네트워크는 IPv6를 실제로 라우팅하지 못함. curl은 Happy Eyeballs 방식으로 IPv6 실패 시 자동으로 IPv4로 폴백하여 정상 응답(HTTP 405 — GET 메서드라 당연한 응답)을 받았지만, Claude Code(Node.js 기반)는 이 폴백이 충분히 관대하지 않아 IPv6 연결 시도 단계에서 멈추고 재시도만 반복함.

해결책

Node가 DNS 조회 시 IPv4를 우선하도록 강제:

export NODE_OPTIONS="--dns-result-order=ipv4first"

~/.bashrc 또는 ~/.zshrc에 추가 후 새 터미널에서 claude 재실행.

비고

• Node 18+ 에서 지원되는 옵션.
• 근본적 해결은 로컬 네트워크/라우터의 IPv6 라우팅 설정 점검이지만, 즉시 조치로는 위 환경변수 하나로 충분.
• 동일 증상(ConnectionRefused + doctor 정상)이 재발하면 먼저 curl -v로 IPv6 fallback 로그부터 확인할 것.