Claude Code 접속 오류가 발생하는 이유

Claude Code를 터미널에서 실행했을 때 연결이 끊겼습니다, 응답 시간이 초과되었습니다, API 요청이 반복해서 실패합니다와 같은 메시지가 나타나는 경우가 있습니다. 명령어 자체가 잘못된 것처럼 보이지만, 실제 원인은 터미널 프로세스가 Clash 프록시를 사용하지 못하거나, Clash의 규칙이 해당 도메인을 직접 연결로 처리하는 데 있는 경우가 많습니다.

브라우저에서 웹사이트가 정상적으로 열리더라도 Claude Code가 반드시 같은 경로를 사용하는 것은 아닙니다. 브라우저는 운영체제의 시스템 프록시 설정을 따르지만, 터미널 프로그램은 환경 변수인 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY를 별도로 확인하는 방식이 일반적입니다. 또한 Node.js 기반 도구의 인증 요청, 업데이트 확인, API 통신이 서로 다른 도메인으로 나뉘어 있어 일부 요청만 실패할 수도 있습니다.

따라서 문제를 해결할 때는 “Clash가 실행 중인가”만 확인해서는 부족합니다. 먼저 노드와 구독이 정상인지 확인하고, 그다음 Clash Verge의 로컬 포트, 시스템 프록시 또는 TUN 모드, 마지막으로 터미널의 프록시 환경 변수를 순서대로 점검해야 원인을 빠르게 좁힐 수 있습니다.

시작 전에 확인할 항목

다음 항목을 미리 준비하세요.

Clash Verge 또는 Clash Verge Rev: 운영체제에 맞는 최신 클라이언트를 설치합니다.
Clash 호환 구독 URL: 제공업체에서 발급한 YAML 기반 구독 링크가 필요합니다. 일반적인 SS, VLESS 단일 링크와는 다를 수 있습니다.
터미널 접근 권한: Windows PowerShell, macOS Terminal, Linux 셸 중 사용 중인 환경을 확인합니다.
테스트할 노드: 지연 시간이 낮고 최근까지 연결된 노드를 하나 이상 선택합니다.

구독 링크에는 개인 인증 정보가 포함될 수 있으므로 다른 사람에게 그대로 공유하지 마세요. 설정 파일이나 터미널 로그를 게시할 때도 토큰, 사용자 식별자, 서버 주소 일부를 가리는 것이 안전합니다. 특히 Claude Code의 오류 로그에는 요청 URL이나 환경 정보가 함께 출력될 수 있으므로 전체 로그를 공개하기 전에 민감한 값을 먼저 확인해야 합니다.

또한 Clash Verge와 Clash for Windows를 동시에 실행하는 것은 피하는 것이 좋습니다. 두 클라이언트가 동일한 포트나 가상 네트워크 장치를 사용하면 시스템 프록시가 수시로 바뀌거나 TUN 인터페이스가 충돌해, 연결 상태가 불안정해질 수 있습니다.

1단계: Clash Verge에 구독 가져오기

Clash Verge를 설치했다면 먼저 Profiles 또는 프로파일 화면을 엽니다. 제공업체 대시보드에서 복사한 구독 URL을 입력란에 붙여 넣고 다운로드 또는 가져오기 버튼을 누릅니다. 프로파일 이름이 표시되고 다운로드가 완료되면 해당 항목을 선택해 활성화합니다.

제공업체 페이지에서 Clash 전용 구독 URL을 복사합니다.
Clash Verge의 프로파일 화면에 URL을 붙여 넣습니다.
다운로드가 끝날 때까지 기다린 뒤 새 프로파일을 선택합니다.
프록시 목록에 노드와 프록시 그룹이 표시되는지 확인합니다.
노드 지연 시간 테스트를 실행하고 응답하는 노드를 선택합니다.

프로파일 다운로드가 실패하면 Claude Code보다 구독 자체를 먼저 의심해야 합니다. 브라우저에서 URL을 열었을 때 로그인 화면이나 HTML 오류 페이지가 나타난다면 Clash가 읽을 수 있는 YAML 설정이 반환되지 않은 것입니다. 링크가 만료되었거나 사용량 제한에 도달한 경우에도 빈 파일이 내려올 수 있으므로, 제공업체 대시보드에서 URL을 새로 발급해 보세요.

주의

프로파일이 성공적으로 등록되었다고 해서 프록시 연결까지 정상이라는 뜻은 아닙니다. Proxies 화면에서 실제 노드를 선택하고 지연 시간 테스트를 실행한 다음, Logs 화면에 타임아웃이나 연결 거부 메시지가 없는지 확인하세요.

2단계: 로컬 포트와 TUN 모드 설정

Claude Code 같은 터미널 프로그램을 연결하려면 Clash Verge가 제공하는 로컬 프록시 포트를 알아야 합니다. 설정의 일반 또는 네트워크 화면에서 Mixed Port, HTTP Port, Socks Port를 확인하세요. 예를 들어 Mixed Port가 7890이라면 HTTP와 SOCKS 요청을 하나의 포트로 처리할 수 있습니다. 실제 포트 번호는 버전과 사용자 설정에 따라 다르므로 아래 예시를 그대로 사용하기보다 Clash Verge 화면에 표시된 값을 기준으로 해야 합니다.

항목	역할	확인할 내용
System Proxy	운영체제의 HTTP 프록시 설정 변경	브라우저와 일부 앱이 프록시를 사용하는지 확인
Mixed Port	HTTP 및 SOCKS 요청 수신	주소가 보통 `127.0.0.1`인지 확인
TUN Mode	프록시를 지원하지 않는 앱의 트래픽도 가상 인터페이스로 전달	서비스 권한과 다른 VPN 프로그램의 충돌 여부 확인
Mode	Direct, Rule, Global 방식으로 라우팅	문제 진단 시 잠시 Global로 비교

대부분의 환경에서는 먼저 Rule 모드와 시스템 프록시를 사용해 보는 것이 좋습니다. Rule 모드는 규칙에 따라 도메인별로 직접 연결과 프록시 연결을 나누므로 국내 서비스의 불필요한 우회를 줄일 수 있습니다. 다만 규칙에 Claude 관련 API 도메인이 포함되지 않았거나 잘못된 정책 그룹으로 연결되면 요청이 직접 나가 실패할 수 있습니다.

TUN 모드는 터미널 프로그램이 프록시 환경 변수를 무시하는 경우에 도움이 됩니다. 그러나 TUN을 켠 상태에서 다른 VPN, 기업 보안 에이전트, 가상 머신 네트워크를 함께 사용하면 라우팅 우선순위가 꼬일 수 있습니다. TUN을 활성화한 뒤 인터넷 전체가 끊긴다면 우선 TUN을 끄고 시스템 프록시 방식으로 되돌려 어느 단계에서 문제가 생겼는지 비교하세요.

3단계: 터미널에 프록시 연결하기

Clash Verge가 실행 중이어도 터미널 앱이 자동으로 로컬 포트를 사용하는 것은 아닙니다. 셸에서 프록시 환경 변수를 설정하면 Claude Code가 해당 연결을 이용하도록 만들 수 있습니다. Mixed Port가 7890인 예시는 다음과 같습니다.

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

위 명령은 현재 터미널 세션에만 적용됩니다. 먼저 임시 설정으로 연결을 시험하는 것이 안전합니다. 정상적으로 작동한 뒤 매번 입력하기 번거롭다면 macOS와 Linux에서는 셸 설정 파일에 추가할 수 있고, Windows PowerShell에서는 사용자 환경 변수나 프로필에 등록할 수 있습니다. 다만 회사 네트워크나 공유 컴퓨터에서는 프록시 주소를 전역으로 저장하지 않는 편이 좋습니다.

SOCKS 포트를 사용해야 하는 환경이라면 ALL_PROXY에 SOCKS 주소를 지정할 수 있습니다. 프로그램에 따라 SOCKS5의 DNS 처리 방식이 다르므로, 단순히 연결만 확인하지 말고 실제 API 요청이 성공하는지 함께 확인해야 합니다.

export ALL_PROXY=socks5://127.0.0.1:7891
curl -I https://example.com

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"

테스트 순서

Clash Verge의 Logs 화면을 열어 둡니다.
터미널에서 프록시 변수를 설정합니다.
curl -I https://example.com으로 요청을 보냅니다.
로그에 연결 기록이 나타나는지 확인합니다.
기록이 보이면 Claude Code를 다시 실행합니다.

curl 요청이 성공하고 로그에도 기록이 남는다면 로컬 포트와 기본 프록시 경로는 정상일 가능성이 높습니다. 반대로 터미널에서 요청이 멈추고 Clash 로그에 아무것도 없다면 환경 변수 이름이 틀렸거나, 현재 셸과 Claude Code가 서로 다른 실행 환경을 사용하고 있는지 확인해야 합니다.

4단계: 로그와 규칙으로 원인 좁히기

Claude Code가 여전히 연결되지 않는다면 오류 문구를 하나의 원인으로 단정하지 말고 Clash Verge 로그의 시간과 목적지 도메인을 함께 비교하세요. connection refused는 로컬 포트가 열려 있지 않거나 잘못된 포트를 지정했을 때 자주 나타납니다. i/o timeout이나 context deadline exceeded가 반복되면 선택한 노드, 네트워크 품질, 방화벽을 확인해야 합니다. TLS 또는 인증서 오류가 보이면 시스템 시간이 틀렸거나 중간 보안 장비가 HTTPS 연결을 검사하는 상황일 수 있습니다.

로그에 요청이 없음: 환경 변수, TUN, 터미널 프로세스의 우회 여부를 확인합니다.
요청은 있으나 Direct로 표시됨: Rule 모드의 도메인 규칙과 마지막 MATCH 정책을 확인합니다.
프록시 그룹에서 반복 실패: 다른 노드로 바꾸고 지연 시간과 지역을 비교합니다.
DNS 오류가 발생함: Clash DNS 설정, 운영체제 DNS, 브라우저의 보안 DNS를 함께 확인합니다.
인증만 실패함: 토큰 만료, 계정 권한, 환경 변수에 저장된 오래된 키를 확인합니다.

진단 중에는 잠시 Global 모드로 바꿔 같은 요청을 다시 실행해 볼 수 있습니다. Global에서 성공하고 Rule에서 실패한다면 노드 문제가 아니라 규칙 문제일 가능성이 큽니다. 반대로 두 모드 모두 실패하면 노드 상태, 로컬 포트, 네트워크 차단을 먼저 점검하세요. 테스트가 끝난 뒤에는 필요 이상으로 모든 트래픽을 프록시로 보내지 않도록 Rule 모드로 되돌리는 것을 권장합니다.

DNS 설정을 변경할 때는 여러 값을 한꺼번에 바꾸지 마세요. fake-ip와 redir-host는 앱 호환성과 규칙 매칭 방식에 영향을 줄 수 있으므로, 현재 구독 설정이 요구하는 값을 우선 유지하는 편이 안전합니다. 특정 도메인만 실패한다면 전체 DNS를 바꾸기보다 해당 도메인이 올바른 프록시 그룹으로 매칭되는지부터 확인하세요.

안정적인 개발 환경을 위한 운영 방법

Claude Code를 자주 사용한다면 매번 연결 오류를 처음부터 조사하지 않도록 기본 점검 순서를 정해 두는 것이 좋습니다. 작업을 시작하기 전에 Clash Verge가 실행 중인지, 활성 프로파일에 노드가 있는지, 선택한 노드의 지연 시간이 지나치게 높지 않은지 확인하세요. 그다음 짧은 HTTPS 요청으로 로컬 포트와 터미널 환경 변수를 시험하면 긴 작업 중 연결이 끊긴 뒤 원인을 찾는 시간을 줄일 수 있습니다.

구독은 정기적으로 업데이트하되, 업데이트 직후 모든 설정이 정상이라고 가정하지 마세요. 제공업체가 노드 이름이나 정책 그룹을 바꾸면 기존 규칙이 예상과 다르게 동작할 수 있습니다. 업데이트 후에는 대표적인 API 요청 하나를 테스트하고, 새 프로파일이 활성화되어 있는지 확인하는 습관이 유용합니다. 회사 네트워크에서는 보안 정책상 외부 프록시나 TUN 사용이 제한될 수 있으므로, 허용된 네트워크와 계정 정책도 함께 준수해야 합니다.

다른 프록시 도구는 기능이 단순한 대신 터미널별 환경 변수, DNS 처리, 규칙 확인 기능이 부족하거나 운영체제 업데이트 뒤 호환성 문제가 생기는 경우가 있습니다. Clash Verge는 프로파일, 노드, 규칙, 연결 로그와 TUN 모드를 한 화면 흐름에서 점검할 수 있고, 문제가 발생했을 때 어느 요청이 어떤 정책으로 처리됐는지 추적하기 쉽습니다. Claude Code처럼 개발 도구의 네트워크 경로를 세밀하게 관리해야 한다면, 앞서 설명한 설정을 적용한 뒤 Clash 무료 다운로드로 환경에 맞는 클라이언트를 준비해 보세요.

Claude Code 접속 오류 해결, Clash Verge 터미널 설정 가이드