Claude Code 연결 실패? Clash 타임아웃 해결 방법

Claude Code만 연결에 실패하는 이유: 브라우저와 CLI의 경로가 다르다

Claude 웹페이지가 브라우저에서 정상적으로 열리는데도 Claude Code가 로그인되지 않거나 요청 중 timeout을 반환하는 경우가 있습니다. 두 프로그램이 같은 컴퓨터에서 실행되더라도 네트워크를 사용하는 방식은 같지 않습니다. 브라우저는 운영체제의 시스템 프록시 설정을 비교적 잘 상속하지만, 터미널에서 실행되는 Claude Code는 셸 환경 변수, Node 런타임, 자체 HTTPS 클라이언트, 인증 콜백을 각각 다른 경로로 사용할 수 있습니다.

Clash에서 시스템 프록시를 켰다는 사실만으로 모든 CLI 요청이 프록시를 통과한다고 보기는 어렵습니다. HTTP_PROXY, HTTPS_PROXY, ALL_PROXY가 비어 있거나 잘못된 포트를 가리키면 웹 브라우저는 연결되지만 Claude Code만 직접 연결을 시도할 수 있습니다. 반대로 환경 변수는 올바르지만 Clash 규칙이 인증 서버와 API 서버를 서로 다른 정책으로 보내면 로그인은 성공하고 실제 코드 요청만 멈추는 패턴도 나타납니다.

따라서 처음부터 노드를 무작정 교체하기보다 증상을 설치·업데이트, 로그인과 인증, 모델 API 스트리밍, 도구 호출 단계로 나누어야 합니다. 각 단계에서 Clash 연결 로그의 호스트, 정책 그룹, 연결 결과, 소요 시간을 함께 확인하면 원인이 프록시 모드인지 DNS인지 노드 품질인지 빠르게 좁힐 수 있습니다.

증상별로 보는 Claude Code Clash 연결 오류

Claude Code의 오류 문구는 실제 원인보다 단순하게 표시되는 경우가 많습니다. “Request timed out”은 원격 API의 응답 지연뿐 아니라 DNS 조회 실패, TLS 협상 지연, 잘못된 프록시 포트, 스트리밍 연결 종료까지 포함할 수 있습니다. 아래처럼 마지막으로 성공한 단계와 실패한 시점을 기록하면 불필요한 설정 변경을 줄일 수 있습니다.

특히 긴 코드 생성 중 멈추는 문제는 단순한 “핑이 높다”와 다릅니다. 일반적인 속도 테스트는 짧은 HTTP 요청을 측정하지만 Claude Code는 한 연결을 오래 유지하면서 토큰을 스트리밍합니다. 순간적인 패킷 손실이나 프록시의 유휴 연결 정리 정책이 있으면 평균 속도는 좋아도 실제 세션은 끊길 수 있습니다.

Clash 모드와 터미널 프록시 환경 변수 맞추기

먼저 Clash의 현재 모드를 확인합니다. Rule 모드는 도메인과 규칙에 따라 연결을 나누므로 일반적인 사용에 적합하지만, Claude Code에 필요한 호스트가 규칙 목록에 없으면 DIRECT로 빠질 수 있습니다. Global 모드는 원인 분리에 유용한 임시 테스트 방법입니다. Global에서만 Claude Code가 정상이라면 노드 자체보다는 Rule 모드의 매칭 순서나 누락된 도메인이 문제일 가능성이 큽니다. 반대로 Global에서도 계속 실패하면 환경 변수, DNS, 노드 품질을 이어서 확인해야 합니다.

터미널 프로그램은 Clash의 시스템 프록시를 자동으로 읽지 않을 수 있습니다. 사용하는 클라이언트에서 mixed-port 또는 SOCKS 포트가 실제로 열려 있는지 확인하고, 해당 포트를 가리키는 환경 변수를 현재 셸에 적용합니다. 포트 번호는 설치 예시를 그대로 복사하지 말고 Clash의 포트 설정 화면에서 실제 값을 확인해야 합니다. 다른 VPN이나 로컬 프록시가 동시에 실행 중이면 같은 변수 이름이 다른 프로그램의 포트를 가리킬 수 있으므로 초기 진단에서는 하나만 남기는 편이 안전합니다.

echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $ALL_PROXY

Windows PowerShell, macOS·Linux 셸, IDE 통합 터미널은 환경 변수의 적용 시점이 다릅니다. Clash를 켠 뒤 새 터미널을 열었는데도 값이 비어 있다면 셸 프로파일을 다시 읽거나 새 세션을 시작해야 합니다. 반대로 이전에 설정한 잘못된 값이 남아 있으면 Clash를 종료해도 CLI가 해당 주소로 계속 접속하려고 하므로, Claude Code를 실행하는 동일한 터미널에서 값을 확인하는 것이 중요합니다.

테스트할 때는 모든 설정을 한 번에 바꾸지 마세요. 첫 번째는 Rule 모드와 현재 노드, 두 번째는 Global 모드와 같은 노드, 세 번째는 다른 노드와 같은 모드처럼 한 번에 한 변수만 변경합니다. 이렇게 해야 “Global이라서 해결된 것인지”, “노드를 바꿔서 해결된 것인지”, “새 터미널이 환경 변수를 읽어서 해결된 것인지”를 구분할 수 있습니다.

DNS, 규칙 순서, 노드 품질을 분리해서 점검하기

DNS 문제는 Claude Code 타임아웃의 흔한 원인입니다. 도메인 이름이 잘못된 주소로 해석되거나, 로컬 네트워크의 DNS가 특정 응답을 지연시키면 프록시가 정상이어도 연결 시작 전에 시간이 소진됩니다. Clash의 DNS 모드와 함께 실제 연결 로그에 표시되는 목적지 주소를 확인하세요. fake-ip와 redir-host를 번갈아 바꾸기보다 현재 클라이언트와 코어가 권장하는 모드를 유지하고, 한 번 변경한 뒤 캐시를 비운 상태에서 다시 재현하는 편이 정확합니다.

규칙은 위에서 아래로 평가되는 경우가 많습니다. 넓은 GEOIP, MATCH, 특정 지역의 FINAL 규칙이 Claude 관련 도메인보다 먼저 있으면 의도한 정책 그룹에 도달하지 못합니다. 반대로 DOMAIN-SUFFIX를 지나치게 넓게 추가하면 업무용 서비스와 저장소까지 같은 노드로 보내 관리가 어려워질 수 있습니다. 실제 로그에서 확인한 호스트만 최소 범위로 추가하고, 규칙을 바꾼 뒤에는 프로필을 다시 로드해야 합니다.

• 인증 단계: 로그인 페이지, 토큰 교환, 콜백 관련 연결이 모두 완료되는지 확인합니다.
• API 단계: Claude 모델 요청이 같은 정책 그룹을 사용하는지 확인합니다.
• 스트리밍 단계: 응답 중 연결 재설정이나 유휴 시간 초과가 발생하는지 확인합니다.
• 도구 단계: 저장소, 패키지 레지스트리, 외부 문서처럼 추가로 호출되는 호스트를 구분합니다.

모든 호스트가 같은 정책을 사용한다고 해서 모든 노드가 좋은 것은 아닙니다. 무료 또는 과도하게 공유된 노드는 TLS 연결은 성립해도 장시간 스트리밍에서 패킷 손실과 재전송이 늘어날 수 있습니다. 노드를 평가할 때는 짧은 지연 시간만 보지 말고, 동일한 프롬프트로 로그인·짧은 응답·긴 응답을 각각 실행해 성공률과 연결 유지 시간을 기록하세요. 특정 노드에서만 긴 응답이 실패한다면 규칙보다 노드 품질 또는 해당 리전과의 경로를 의심하는 것이 합리적입니다.

실전 해결 순서: 로그부터 재현까지

이제 실제로 설정을 수정하는 순서입니다. 작업 전 현재 프로필을 복사해 두고, 구독 갱신으로 로컬 규칙이 덮어써질 가능성도 확인하세요. 화면 이름은 Clash Verge, Clash Verge Rev, Mihomo Party 등에 따라 다를 수 있지만, 핵심은 모드·포트·DNS·연결 로그를 차례로 확인하는 것입니다.

1. Clash 코어 상태 확인: 대시보드에서 코어가 실행 중인지, 활성 프로필이 예상한 구성인지 확인합니다. 노드 목록이 비어 있거나 프로필 오류가 있으면 Claude Code보다 먼저 구독과 YAML 파싱 문제를 해결해야 합니다.
2. 포트 확인: mixed-port 또는 SOCKS 포트가 실제로 열려 있는지 확인합니다. 터미널에 설정한 포트와 Clash 화면의 포트가 다르면 모든 요청이 즉시 실패하거나 다른 서비스로 전달될 수 있습니다.
3. 환경 변수 확인: Claude Code를 실행하는 동일한 셸에서 프록시 변수를 출력합니다. 오래된 포트, 오타, 잘못된 프로토콜 접두사가 있으면 임시로 정리한 뒤 새 터미널에서 다시 시도합니다.
4. Global 모드로 비교: 같은 노드를 유지한 채 잠시 Global 모드로 로그인과 짧은 요청을 실행합니다. 이 단계는 영구 운영 설정이 아니라 Rule 매칭 문제를 분리하기 위한 진단입니다.
5. 연결 로그 필터링: 실패 시각에 나타난 인증·API 호스트를 기록하고, 각각의 정책명과 연결 결과를 비교합니다. 누락된 호스트만 최소 규칙으로 보강하고 넓은 도메인 규칙은 피합니다.
6. DNS와 노드 교차 테스트: DNS 모드를 한 번만 변경해 재시도하고, 같은 설정에서 다른 품질의 노드도 시험합니다. 두 변경을 동시에 하면 원인을 확인할 수 없으므로 반드시 순서를 나눕니다.
7. 긴 세션 검증: 짧은 질문뿐 아니라 여러 파일을 읽고 수정하는 작업을 실행합니다. 짧은 요청은 성공하지만 장시간 스트림만 끊기면 노드의 연결 유지 성능이나 프록시 타임아웃을 별도로 기록해야 합니다.

중요: 인증 토큰이나 API 키를 연결 로그, 스크린샷, 공개 이슈에 그대로 올리지 마세요. 로그를 공유해야 한다면 계정 식별자, Authorization 헤더, 프로젝트 경로와 개인 정보가 포함된 줄을 먼저 가린 뒤 호스트와 정책명만 남기는 것이 안전합니다.

설정이 정상화된 뒤에는 Global 모드를 계속 유지하기보다 Rule 모드로 돌아가 최소 규칙만 남기는 것을 권장합니다. 모든 트래픽을 하나의 해외 노드로 보내면 개발 도구, 사내 서비스, 패키지 저장소의 지연이 함께 증가할 수 있습니다. Claude Code에 필요한 연결과 일반 업무 트래픽을 구분하되, API와 인증 경로가 서로 다른 노드로 흩어지지 않도록 정책 그룹의 안정성을 우선하세요.

자주 묻는 질문

브라우저 Claude는 되는데 Claude Code만 실패하는 이유는 무엇인가요?

브라우저는 시스템 프록시를 상속하지만 터미널은 환경 변수나 자체 네트워크 라이브러리를 사용할 수 있기 때문입니다. Claude Code를 실행하는 셸에서 프록시 주소와 포트를 확인하고, Clash 연결 로그에 실제 요청이 나타나는지 먼저 비교하세요.

Global 모드에서는 되는데 Rule 모드에서는 왜 실패하나요?

Rule 모드에서 인증 또는 API 도메인이 누락되었거나 상위 규칙이 먼저 매칭되었을 가능성이 높습니다. 실패 시각의 로그에서 실제 호스트를 확인한 뒤 필요한 도메인만 같은 정책 그룹으로 보내고, 넓은 접미 규칙은 피하세요.

노드를 바꾸면 잠시 해결되지만 다시 타임아웃이 납니다. 어떻게 해야 하나요?

노드 혼잡이나 장시간 스트리밍 품질 문제가 원인일 수 있습니다. 짧은 핑보다 긴 응답의 성공률, 연결 유지 시간, 재설정 횟수를 비교하고 안정적인 노드를 기본 그룹에 두세요. 여러 노드를 자동 선택할 때도 테스트 기준이 지나치게 짧으면 실제 API 세션에 약한 노드가 선택될 수 있습니다.

DNS를 바꾸면 반드시 해결되나요?

DNS가 원인일 때는 효과가 있지만 모든 타임아웃을 해결하지는 않습니다. 연결 로그에서 이름 해석 단계부터 지연되는지, TLS 이후 스트리밍 중 끊기는지를 구분해야 합니다. DNS 변경 후에는 캐시와 프로필 상태를 정리하고 동일한 테스트를 반복하세요.

Claude Code 문제를 해결할 때 단순한 시스템 프록시 토글만 제공하는 일부 경량 클라이언트는 터미널 환경 변수, 규칙 우선순위, DNS 상태, 장시간 스트리밍을 한 화면에서 확인하기 어렵고, 오래된 GUI는 최신 Mihomo 코어의 로그와 정책 동작을 충분히 보여 주지 못할 수 있습니다. Clash V.CORE는 프록시 모드와 정책 그룹, 연결 로그, DNS 및 TUN 관련 상태를 한 흐름에서 점검할 수 있어 Claude Code처럼 인증과 API 스트리밍을 함께 사용하는 개발 환경에 더 실용적입니다. 이번 글의 순서대로 원인을 재현하고 안정적인 노드를 찾았다면, 여러 클라이언트 사이를 오가기보다 Clash V.CORE를 내려받아 일관된 설정으로 관리해 보세요.