이 글이 맞는 연결 증상
Claude Code를 설치한 뒤 로그인이나 첫 프롬프트 전송 단계에서 멈추고, 터미널에 ETIMEDOUT·ECONNRESET·fetch failed·socket hang up 같은 메시지가 나타난다면 단순히 API 키가 잘못된 경우만은 아닙니다. 브라우저에서 Claude 웹사이트는 정상적으로 열리는데 Claude Code만 연결 시간 초과가 발생한다면, 브라우저와 터미널이 서로 다른 프록시 경로를 사용하고 있을 가능성이 큽니다.
이 문제는 대체로 네 가지 원인으로 좁혀집니다. 첫째, Clash에서 Anthropic 관련 도메인이 DIRECT로 빠져 차단된 회선을 그대로 사용하는 경우입니다. 둘째, 선택한 노드의 지연 시간이나 패킷 손실이 커서 TLS 연결 또는 긴 스트리밍 응답을 유지하지 못하는 경우입니다. 셋째, Clash Verge Rev의 mixed-port와 터미널의 HTTPS_PROXY 포트가 서로 다르게 설정된 경우입니다. 넷째, 터미널은 프록시를 사용하지만 DNS·인증·콜백 트래픽 일부가 다른 경로로 빠지는 경우입니다.
따라서 처음부터 TUN 모드를 무조건 켜기보다는, 실제 호스트 확인 → Clash 규칙 확인 → 셸 환경 변수 확인 → 필요한 경우 TUN 적용 순서로 점검하는 것이 효율적입니다. 이 순서를 지키면 노드 문제와 로컬 설정 문제를 구분할 수 있고, 정상 작동하던 다른 개발 도구까지 불필요하게 변경하는 일도 줄어듭니다.
Claude Code가 사용하는 연결 경로 이해하기
Claude Code는 터미널에서 실행되지만 내부적으로는 일반적인 웹 요청만 보내지 않습니다. 로그인 과정에서는 인증 페이지와 토큰 교환이 필요하고, 실제 코딩 요청에서는 Anthropic API로 HTTPS 연결을 열어 응답을 스트리밍합니다. 프로젝트 상태 확인, 업데이트 확인, 오류 보고 또는 추가 기능에 따라 연결 대상이 더 늘어날 수도 있습니다. 그러므로 웹 브라우저에서 claude.ai가 열린다는 사실만으로 API 경로까지 정상이라고 판단하면 안 됩니다.
가장 먼저 확인할 대표 호스트는 api.anthropic.com입니다. 다만 Claude Code의 버전, 로그인 방식, 조직 정책, 사용 중인 중계 서버에 따라 인증 또는 부가 요청의 호스트가 달라질 수 있습니다. 설정 파일에 인터넷에서 찾은 도메인 목록을 무작정 추가하기보다는, Claude Code를 실행한 직후 Clash의 연결 로그를 열어 실제로 요청된 Host 또는 SNI를 확인하는 편이 안전합니다.
| 관찰되는 증상 | 우선 의심할 원인 | 확인할 위치 |
|---|---|---|
| 브라우저는 정상, 터미널만 시간 초과 | HTTPS_PROXY 누락 또는 잘못된 포트 |
셸 환경 변수, IDE 통합 터미널 |
| 모든 요청이 오래 걸린 뒤 실패 | 불안정한 노드, TLS 또는 DNS 경로 문제 | Clash 노드 지연·错误 로그와 연결 기록 |
| 로그인만 실패하고 일반 요청은 성공 | 인증 호스트 규칙 누락, 콜백 차단 | 로그인 직전과 직후의 도메인 기록 |
| 짧은 명령은 되지만 긴 답변에서 끊김 | 스트리밍 유지 불량, 패킷 손실, 노드 혼잡 | 장시간 연결의 반복 결과와 노드 변경 여부 |
연결 로그에서 대상 호스트가 보이지 않는다면 로그 필터가 너무 좁게 설정되어 있거나, Claude Code가 Clash를 통하지 않고 직접 연결하는 상태일 수 있습니다. 이때는 실패 시간과 로그 시간을 맞춰 보세요. 오류가 발생한 시각에 DIRECT 또는 REJECT가 반복된다면 규칙 문제일 가능성이 높고, 프록시 그룹 이름이 표시되는데도 연결이 끊긴다면 노드 품질이나 프록시 호환성을 더 의심해야 합니다.
1단계: Clash Verge Rev 기본 상태부터 확인하기
먼저 Clash Verge Rev 또는 사용 중인 Mihomo 클라이언트를 열고 현재 프로필이 실제로 활성화되어 있는지 확인합니다. 구독을 새로 갱신한 직후에는 프로필 이름은 그대로지만 내부 규칙, 프록시 그룹, mixed-port 값이 바뀌는 일이 있습니다. 화면에 프로필이 보인다는 것과 해당 프로필이 실행 중이라는 것은 다를 수 있으므로, 코어 상태가 실행 중인지와 최근 오류가 없는지를 함께 확인해야 합니다.
그다음 현재 모드를 기록합니다. 규칙 모드에서는 도메인별로 DIRECT·REJECT·프록시 그룹이 나뉘고, 글로벌 모드에서는 대부분의 트래픽이 선택한 하나의 그룹으로 이동합니다. 원인 분석 단계에서는 규칙 모드를 유지하는 편이 좋습니다. 글로벌 모드로 잠시 전환했을 때 Claude Code가 정상화된다면 노드 자체보다 규칙 매칭이 문제일 가능성이 커지기 때문입니다. 반대로 글로벌 모드에서도 같은 시간 초과가 발생하면 노드, 포트, 셸 변수 또는 TUN 상태를 차례로 봐야 합니다.
Clash의 mixed-port 번호도 반드시 메모하세요. 예를 들어 Clash가 7890 포트에서 HTTP와 SOCKS 요청을 함께 받도록 설정되어 있는데 터미널에는 예전 포트인 7891이 남아 있으면, 브라우저는 정상이어도 Claude Code는 연결할 수 없습니다. 시스템 프록시를 켰다는 표시만 보지 말고 실제 포트 번호와 프로토콜이 일치하는지 확인해야 합니다.
- 활성 프로필의 이름과 마지막 갱신 시간을 확인합니다.
- Mihomo 코어가 실행 중이며 재시작을 반복하지 않는지 봅니다.
- 현재 모드와 mixed-port 번호를 메모합니다.
- 프록시 그룹에서 지연이 지나치게 크거나 오류가 반복되는 노드를 제외합니다.
- Claude Code를 한 번 실행하면서 연결 로그를 새로고침합니다.
노드 선택은 단순히 가장 낮은 핑 하나만 보고 결정하지 않는 것이 좋습니다. ICMP 핑이 빠른 노드라도 실제 HTTPS 연결이나 장시간 스트리밍에는 약할 수 있습니다. 여러 노드에서 같은 요청을 짧게 반복하고, 연결 수립 시간·첫 응답 시간·응답 중간 끊김을 함께 비교하세요. Claude Code는 짧은 테스트보다 긴 응답에서 문제가 더 잘 드러나므로 한 번 성공했다고 바로 안정 노드로 확정하지 않는 편이 안전합니다.
2단계: Anthropic 트래픽을 올바른 규칙으로 보내기
연결 로그에서 api.anthropic.com 또는 실제로 확인한 Anthropic 관련 호스트를 찾았다면, 해당 요청이 어떤 규칙에 매칭되었는지 확인합니다. DIRECT로 표시된다면 차단 또는 제한된 기본 회선을 사용하고 있을 수 있습니다. REJECT라면 규칙 프로바이더나 광고 차단 목록이 API 도메인을 잘못 분류했을 가능성이 있습니다. 프록시 그룹으로 보내고 있는데도 실패한다면 선택된 그룹의 노드 상태를 비교합니다.
개인 설정 파일을 직접 수정할 수 있는 환경이라면 Anthropic API 호스트를 전용 프록시 그룹에 명시적으로 배치할 수 있습니다. 예시는 다음과 같은 구조를 사용하지만, 실제 그룹명은 자신의 프로필에 맞게 바꿔야 합니다.
rules:
- DOMAIN,api.anthropic.com,Claude-Proxy
- DOMAIN-SUFFIX,anthropic.com,Claude-Proxy
- MATCH,DIRECT여기서 DOMAIN-SUFFIX,anthropic.com은 편리하지만 범위가 넓습니다. 조직 내부 도메인, 웹사이트, 다운로드 서버까지 같은 그룹으로 보낼 수 있으므로 연결 로그에서 실제 사용 호스트를 확인한 뒤 필요한 범위만 남기는 것이 좋습니다. 구독 프로필이 자동 생성되는 구조라면 원본 YAML을 직접 편집해도 다음 업데이트 때 덮어써질 수 있습니다. 이 경우에는 Clash Verge Rev의 로컬 확장 규칙, 프리미엄 규칙, 또는 구독 제공자가 지원하는 사용자 규칙 기능을 활용해야 합니다.
규칙 순서도 중요합니다. 넓은 GEOSITE 또는 GEOIP 규칙이 Anthropic 전용 규칙보다 위에 있으면, 직접 작성한 도메인 규칙에 도달하기 전에 다른 그룹으로 빠질 수 있습니다. 전용 규칙을 추가했다면 일반적인 지역 규칙보다 위에 배치하고, 저장 후 코어를 다시 시작해 실제 매칭 결과를 확인하세요. 규칙을 바꾼 뒤에는 캐시된 기존 연결이 남아 있을 수 있으므로 Claude Code를 완전히 종료한 다음 새 셸에서 다시 실행하는 것이 좋습니다.
글로벌 모드는 진단용으로만 잠시 사용할 수 있습니다. 글로벌 모드에서 성공한 뒤 규칙 모드에서 실패한다면 글로벌 모드를 계속 유지하기보다, 로그에서 확인한 호스트를 규칙에 추가해 원인을 해결하는 편이 낫습니다. 그래야 npm, Git, 사내 서버처럼 직접 연결이 더 적합한 트래픽까지 불필요하게 프록시로 보내지 않습니다.
3단계: 터미널과 IDE의 프록시 환경 변수 맞추기
Claude Code가 실행되는 터미널은 Clash의 시스템 프록시 설정을 자동으로 사용하지 않을 수 있습니다. 특히 macOS·Linux의 셸, Windows PowerShell, VS Code의 통합 터미널, JetBrains 내장 터미널은 각각 시작 시점과 환경 변수 상속 방식이 다릅니다. 따라서 먼저 현재 셸이 어떤 값을 보고 있는지 확인합니다.
HTTP_PROXY와HTTPS_PROXY는 일반적으로http://127.0.0.1:<mixed-port>형식입니다.ALL_PROXY는 일부 런타임에서 SOCKS 프록시로 사용되므로 HTTP 포트와 혼동하지 않습니다.NO_PROXY에는localhost,127.0.0.1, 사내 Git 또는 로컬 개발 서버를 넣을 수 있습니다.- 프록시 URL에 인증 정보가 필요하다면 셸 기록과 프로세스 목록에 비밀 값이 노출되지 않는지 확인합니다.
macOS 또는 Linux의 현재 셸에서 환경 변수를 확인하려면 다음과 같이 실행할 수 있습니다.
env | grep -i proxy
echo "$HTTPS_PROXY"일시적으로 테스트할 때는 현재 Clash의 mixed-port에 맞춰 변수를 지정합니다.
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export ALL_PROXY="http://127.0.0.1:7890"Windows PowerShell에서는 같은 목적의 변수를 다음처럼 설정할 수 있습니다.
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="http://127.0.0.1:7890"이 설정은 현재 터미널 세션에만 적용됩니다. 테스트 결과가 좋다면 셸 프로필에 영구 적용할 수 있지만, 공용 네트워크나 회사 환경에서는 모든 명령에 프록시가 적용되어 Git 저장소·패키지 레지스트리·내부 주소까지 우회할 수 있습니다. 영구 등록 전에는 NO_PROXY 예외를 검토하고, 더 이상 사용하지 않는 낡은 프록시 변수를 제거하세요.
IDE 통합 터미널에서만 실패한다면 IDE를 완전히 종료한 뒤 Clash를 먼저 실행하고, 프록시 환경 변수가 준비된 상태에서 IDE를 다시 시작합니다. 이미 실행 중인 IDE는 이전 셸 환경을 계속 보유할 수 있습니다. 반대로 터미널에서는 되지만 Claude Code 확장이나 작업 러너에서 실패한다면, 해당 확장 프로세스가 별도의 런타임 환경을 사용하는지와 확장 설정의 프록시 옵션을 확인해야 합니다.
4단계: 필요할 때 TUN 모드로 누락된 트래픽 보완하기
mixed-port와 환경 변수로도 연결이 안정되지 않거나, Claude Code가 프록시 변수를 읽지 않는다면 TUN 모드를 검토할 수 있습니다. TUN은 운영체제에 가상 네트워크 인터페이스를 만들어 애플리케이션이 별도의 프록시 설정을 지원하지 않아도 트래픽을 Clash로 넘기는 방식입니다. 따라서 터미널 프로그램, 일부 런타임, 백그라운드 작업까지 같은 규칙을 적용하기 쉽다는 장점이 있습니다.
다만 TUN은 만능 해결책이 아닙니다. 관리자 권한, 네트워크 확장 승인, 시스템 방화벽 예외가 필요할 수 있고, 기존 VPN·Docker·가상 머신·보안 프로그램과 충돌할 수 있습니다. TUN을 켜기 전에는 현재 설정을 내보내거나 스크린샷으로 기록하고, 문제가 생겼을 때 즉시 끌 수 있는 메뉴 위치를 알아 두세요. Windows에서는 다른 VPN 어댑터와 라우팅 우선순위를, macOS에서는 네트워크 확장 승인과 방화벽 팝업을 특히 주의해야 합니다.
- Clash 설정에서 TUN 기능을 켜고 필요한 권한을 승인합니다.
- 자동 라우트와 DNS 처리 옵션이 활성화되어 있는지 확인합니다.
- 기존 VPN 또는 다른 투명 프록시를 잠시 종료합니다.
- Claude Code를 완전히 종료하고 새 터미널에서 다시 실행합니다.
- 연결 로그에서 API 호스트가 원하는 프록시 그룹을 타는지 확인합니다.
TUN을 적용한 뒤에는 DNS 모드도 함께 점검해야 합니다. 운영체제 DNS가 차단된 주소를 반환하거나, DNS 요청만 DIRECT로 빠지면 프록시가 정상이어도 연결이 지연될 수 있습니다. 반대로 DNS를 과도하게 강제하면 사내 도메인이나 로컬 장치 이름이 해석되지 않을 수 있습니다. Claude Code만 테스트하는 단계에서는 기존 네트워크 구성을 크게 바꾸기보다, Clash 로그에서 API 호스트의 해석 결과와 연결 경로가 일관적인지 확인하는 것이 안전합니다.
최종 검증은 한 번의 성공보다 반복 결과를 기준으로 하세요. 같은 노드에서 Claude Code를 여러 번 시작하고, 짧은 질문과 긴 코드 분석 요청을 각각 보내 보며, 응답 중간에 멈추지 않는지 관찰합니다. 한 노드에서만 성공하고 다른 노드에서 반복 실패한다면 규칙보다 노드 품질 문제에 가깝습니다. 모든 노드에서 실패한다면 환경 변수, TUN 라우팅, 인증 호스트 규칙을 다시 확인해야 합니다. 오류 메시지에 401·403·429가 나타난다면 연결 시간 초과와는 다른 인증·권한·사용량 문제이므로 프록시 설정만 계속 바꾸지 마세요.
HTTPS_PROXY를 맞추세요. 그래도 애플리케이션 트래픽이 누락될 때만 TUN을 적용하면 불필요한 라우팅 충돌을 줄일 수 있습니다.
같은 문제가 다시 생기지 않게 관리하는 방법
구독 프로필이 갱신될 때마다 규칙 프로바이더와 프록시 그룹이 바뀔 수 있으므로, 정상화한 뒤 현재 설정을 간단히 문서화해 두는 것이 좋습니다. mixed-port 번호, Claude 관련 규칙, 사용할 프록시 그룹, TUN 사용 여부를 기록하면 다음 장애 때 처음부터 모든 항목을 다시 찾지 않아도 됩니다. 단, 구독 URL·API 키·프록시 인증 정보는 문서나 저장소에 평문으로 남기지 마세요.
노드도 하나만 고정하지 말고 최소 두세 개의 대체 경로를 확인하세요. 매일 바꿀 필요는 없지만, 장시간 응답에서 안정적인 노드와 단순 핑만 빠른 노드를 구분해 두면 장애 대응이 빨라집니다. Claude Code가 작업 중 연결을 자주 재사용하는 환경에서는 순간적인 최고 속도보다 TLS 연결 유지, 스트리밍 안정성, 재연결 성공률이 더 중요합니다.
또한 Claude Code, Node.js 런타임, Clash Verge Rev, Mihomo 코어를 한꺼번에 업데이트한 직후 문제가 생겼다면 변경 시점을 기록하세요. 특정 버전의 프록시 변수 처리 방식이나 HTTP/2·HTTP/3 동작이 달라졌을 수 있기 때문입니다. 업데이트 직전에는 정상 작동했는지, 업데이트 후에는 같은 노드와 같은 셸에서 실패하는지 비교하면 원인을 빠르게 좁힐 수 있습니다.
일부 동료의 설정 파일을 그대로 복사하는 것도 주의해야 합니다. 다른 사람의 mixed-port, SOCKS 전용 포트, DNS 모드, 운영체제 권한 상태가 자신의 환경과 다를 수 있기 때문입니다. 특히 NO_PROXY=*처럼 넓은 예외가 들어 있으면 모든 요청이 프록시를 우회할 수 있고, 반대로 너무 넓은 TUN 규칙은 로컬 개발 서버와 회사 시스템을 끊을 수 있습니다. 설정은 작게 바꾸고 매번 한 항목씩 검증하는 것이 가장 안전합니다.
일반적인 확장 프로그램이나 단순 시스템 프록시는 터미널 앱마다 적용 범위가 달라지고, 긴 스트리밍 요청에서 예외 처리가 부족할 수 있습니다. 반면 Clash는 연결 로그로 실제 호스트와 규칙 결과를 확인하고, 도메인별 프록시 분기와 mixed-port·TUN을 상황에 맞게 선택할 수 있다는 장점이 있습니다. 특히 Claude Code처럼 브라우저와 터미널의 네트워크 경로가 달라지기 쉬운 작업에서는 이런 가시성과 세밀한 라우팅이 문제 재현과 해결을 단순하게 만들어 줍니다.