Claude Code 접속 문제, Clash Verge로 안정화하는 설정 가이드

Claude Code가 설치됐는데 접속이 불안정한 이유

Claude Code를 설치한 뒤 브라우저에서 Claude는 정상적으로 열리는데 터미널에서는 인증이 실패하거나, 로그인 페이지로 이동한 뒤 콜백이 끝나지 않거나, 첫 요청에서 연결 시간이 초과되는 경우가 있습니다. 특히 npm install -g @anthropic-ai/claude-code는 완료됐지만 claude 명령을 실행하면 authentication failed, ETIMEDOUT, ECONNRESET 같은 메시지가 반복되는 패턴이 흔합니다.

이 문제를 단순히 “Claude Code가 고장 났다”라고 보면 해결 순서를 놓치기 쉽습니다. Claude Code는 설치 단계의 패키지 다운로드, 브라우저 기반 인증, 인증 토큰 교환, 모델 API 요청, 업데이트 확인을 각각 다른 호스트와 연결 방식으로 처리합니다. 따라서 브라우저에는 프록시가 적용되지만 터미널 프로세스에는 적용되지 않거나, 인증 호스트와 API 호스트가 서로 다른 규칙을 타면 로그인은 성공한 것처럼 보여도 실제 코드 요청에서 멈출 수 있습니다.

Clash Verge는 구독 프로필, 프록시 그룹, 시스템 프록시, TUN 모드, 연결 로그를 한 화면에서 확인할 수 있어 이런 CLI 접속 문제를 단계적으로 진단하기에 적합합니다. 다만 클라이언트만 설치한다고 모든 터미널 트래픽이 자동으로 프록시를 통과하는 것은 아닙니다. 이 글에서는 Clash Verge에 구독을 추가하고, Claude Code가 사용하는 터미널 환경에 맞춰 프록시 모드를 선택한 뒤, 로그를 보면서 최소한의 규칙을 검증하는 순서를 설명합니다.

사용 전 확인: 이 글은 합법적으로 이용할 수 있는 네트워크와 유효한 Claude 계정을 전제로 합니다. 회사·학교의 보안 정책이나 서비스 이용 약관을 우회하는 방법은 다루지 않으며, 계정 토큰과 구독 URL은 다른 사람에게 공유하지 마세요.

설정 전에 확인할 터미널과 네트워크 환경

먼저 Claude Code가 어떤 방식으로 설치됐는지 확인합니다. Node.js 기반으로 설치했다면 node --version, npm --version, claude --version을 차례로 실행해 명령 자체가 정상적으로 인식되는지 봅니다. 명령을 찾을 수 없다는 오류는 네트워크 문제가 아니라 PATH 또는 설치 위치 문제일 가능성이 큽니다. 반대로 버전이 출력되고 로그인 단계에서만 실패한다면 프록시와 인증 경로를 우선 점검해야 합니다.

운영체제의 시스템 프록시와 터미널의 프록시 환경 변수는 서로 다른 층입니다. Windows에서는 Clash Verge의 시스템 프록시를 켜도 일부 PowerShell·WSL·개발 도구가 이를 자동으로 따르지 않을 수 있습니다. macOS와 Linux에서도 셸 세션에 오래된 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 값이 남아 있으면 Clash Verge의 현재 포트와 충돌할 수 있습니다. 특히 예전에 사용하던 VPN이나 다른 프록시 클라이언트가 종료된 뒤에도 환경 변수가 남아 있으면, 브라우저와 Claude Code가 서로 다른 출구를 사용하게 됩니다.

설치 오류: npm 레지스트리나 패키지 CDN에서 다운로드가 멈추는지 확인합니다.
인증 오류: 브라우저 로그인은 열리지만 토큰 교환 또는 터미널 복귀 단계에서 실패하는지 확인합니다.
요청 오류: 로그인은 완료됐지만 모델 요청에서 타임아웃이나 4xx·5xx 응답이 발생하는지 확인합니다.
간헐적 끊김: 같은 명령이 어떤 때는 성공하고 어떤 때는 실패한다면 노드 품질, DNS, 프록시 그룹 자동 선택을 의심합니다.

문제 재현 전에 다른 Clash 클라이언트, 시스템 VPN, 기업용 보안 터널을 잠시 확인하는 것도 좋습니다. 여러 프로그램이 같은 HTTP 혼합 포트나 DNS 포트를 차지하면 Clash Verge가 실행돼 있어도 실제 연결은 다른 서비스로 전달될 수 있습니다. 먼저 하나의 클라이언트만 남기고, Claude Code를 실행하는 터미널을 새로 열어 테스트해야 결과가 섞이지 않습니다.

Clash Verge에 구독을 추가하고 프록시 그룹 준비하기

Clash Verge를 설치한 뒤에는 사용할 수 있는 Clash 또는 Mihomo 구독 URL이 필요합니다. 구독 URL은 보통 https://로 시작하며, URL 안에 개인 식별 토큰이 포함될 수 있으므로 채팅창이나 공개 이슈에 붙여 넣지 않는 것이 안전합니다. 제공업체가 여러 형식을 지원한다면 Mihomo 또는 Clash Meta 호환 형식을 우선 선택하세요. 구독을 가져온 뒤에도 프로필이 자동으로 활성화되지 않는 클라이언트가 있으므로, 가져오기와 적용 상태를 각각 확인해야 합니다.

Clash Verge를 실행하고 사이드바에서 Profiles 또는 프로필 메뉴를 엽니다.
구독 URL 입력란에 발급받은 주소를 붙여 넣은 뒤 Import 또는 가져오기 버튼을 누릅니다.
프로필 목록에 새 YAML 프로필이 나타나면 해당 프로필을 선택하고 활성화 또는 적용 버튼을 누릅니다.
Proxies 메뉴에서 프록시 그룹을 열고 지연 시간 테스트를 실행한 다음, 우선 사용할 노드를 수동으로 선택합니다.
그룹이 DIRECT 또는 사용할 수 없는 노드로 고정되어 있지 않은지 확인하고, Claude Code 테스트가 끝날 때까지 자동 선택을 잠시 끕니다.

노드 선택에서는 단순히 가장 낮은 숫자의 지연 시간만 보지 않는 편이 좋습니다. Claude Code는 짧은 요청을 여러 번 보내고 인증 과정에서 연결이 연속으로 이어질 수 있으므로, 한 번의 핑보다 반복 테스트에서 안정적인 노드가 더 적합합니다. 특정 노드에서 첫 응답은 빠르지만 몇 분 뒤 연결이 끊긴다면, 다른 노드로 바꾼 후 동일한 명령을 다시 실행해 비교하세요.

처음에는 단순하게: 복잡한 사용자 규칙을 한꺼번에 추가하지 말고, 하나의 활성 프로필과 하나의 고정 노드로 인증을 먼저 성공시키세요. 기본 연결이 확인된 뒤 필요한 호스트만 규칙에 보강하는 편이 원인 파악이 빠릅니다.

Claude Code에 맞는 프록시 모드와 기본 분기 설정

Clash Verge의 프록시 적용 방식은 크게 시스템 프록시와 TUN 모드로 나눠 생각할 수 있습니다. 시스템 프록시는 HTTP·HTTPS 프록시를 따르는 브라우저와 일부 개발 도구에 간단히 적용할 수 있습니다. 반면 터미널 프로그램이나 Node.js 프로세스가 시스템 프록시를 무시하면 Claude Code에는 아무런 변화가 없을 수 있습니다. 이 경우 환경 변수 설정 또는 TUN 모드가 필요합니다.

먼저 부담이 적은 시스템 프록시 방식부터 테스트합니다. Clash Verge의 설정에서 HTTP 혼합 포트를 확인하고 시스템 프록시를 활성화한 다음 새 터미널을 열어 Claude Code를 실행합니다. 셸에서 직접 프록시를 지정해야 하는 환경이라면 현재 포트에 맞춰 다음처럼 설정할 수 있습니다.

# Windows PowerShell 예시
$env:HTTP_PROXY="http://127.0.0.1:7897"
$env:HTTPS_PROXY="http://127.0.0.1:7897"

# macOS·Linux 셸 예시
export HTTP_PROXY="http://127.0.0.1:7897"
export HTTPS_PROXY="http://127.0.0.1:7897"
export ALL_PROXY="http://127.0.0.1:7897"

위 포트는 예시일 뿐이며 실제 값은 Clash Verge의 현재 설정에서 확인해야 합니다. 포트가 다르면 연결되지 않고, SOCKS 포트만 열려 있는데 HTTP 주소를 넣으면 TLS나 인증 요청이 실패할 수 있습니다. 테스트가 끝난 뒤에는 환경 변수에 남은 이전 프록시 값을 확인하세요. 잘못된 주소가 저장돼 있으면 Clash Verge를 켜도 Claude Code가 종료된 프록시를 계속 찾게 됩니다.

시스템 프록시와 환경 변수로도 터미널 요청이 로그에 나타나지 않는다면 TUN 모드를 고려할 수 있습니다. TUN은 가상 네트워크 인터페이스를 통해 애플리케이션 트래픽을 Clash로 전달하므로, 프록시 환경 변수를 지원하지 않는 CLI와 개발 도구를 확인하는 데 유리합니다. 다만 DNS 처리, 관리자 권한, 운영체제 네트워크 확장 승인 등이 함께 필요하므로 처음부터 무조건 켜기보다 기본 방식이 실패했을 때 사용하는 것이 좋습니다.

Clash Verge 설정에서 TUN 또는 Service Mode 메뉴를 찾고 필요한 권한을 승인합니다.
TUN 모드를 켠 뒤 DNS 모드와 스택 설정은 우선 기본값으로 두고, 복잡한 옵션은 변경하지 않습니다.
Claude Code를 실행하는 터미널을 완전히 종료한 뒤 새 창을 열어 인증 또는 간단한 모델 요청을 재현합니다.
Clash Verge의 Connections 또는 연결 로그에서 인증과 API 요청이 실제로 보이는지 확인합니다.
요청이 보이지 않으면 TUN 권한, 방화벽, 가상 어댑터 상태를 점검하고 시스템 프록시와 중복 적용되지 않았는지 확인합니다.

규칙을 직접 편집할 때는 도메인을 지나치게 넓게 잡지 않는 것이 중요합니다. Claude Code의 정확한 호스트 목록은 버전, 인증 방식, 지역, 기능에 따라 달라질 수 있으므로 특정 제품명을 포함한 모든 도메인을 무조건 프록시로 보내기보다 연결 로그를 기준으로 확인해야 합니다. 인증 시점에는 로그인·계정 관련 호스트와 API 호스트가 함께 나타날 수 있으며, 한쪽만 DIRECT로 빠지면 브라우저 인증은 끝났는데 CLI가 토큰을 받지 못하는 상황이 생깁니다.

호스트별 정책 확인: 연결 로그에서 실제 FQDN, 매칭된 규칙, 사용된 프록시 그룹을 함께 기록합니다.
DNS 결과 확인: fake-ip 또는 호스트명 매핑이 특정 서비스와 충돌하지 않는지 살펴봅니다.
인증과 API를 같은 기준으로 테스트: 로그인 단계와 첫 모델 요청이 서로 다른 노드로 분리되지 않게 합니다.
규칙 변경 후 프로필 재적용: YAML을 수정했다면 저장만 하지 말고 프로필을 다시 적용하거나 Clash Verge를 새로고침합니다.

토큰과 로그 주의: Claude Code 인증 과정의 로그에는 계정 정보나 요청 주소가 포함될 수 있습니다. 문제를 공유할 때는 액세스 토큰, 구독 URL, 개인 경로, 프로젝트 이름을 먼저 가리고 필요한 오류 코드만 남기세요.

인증 오류와 타임아웃을 증상별로 해결하기

브라우저 로그인 화면 자체가 열리지 않으면 먼저 Clash Verge 연결 로그에 해당 요청이 나타나는지 봅니다. 로그가 없다면 터미널이 프록시를 타지 않는 것이고, 로그는 있지만 실패한다면 선택한 노드나 규칙의 문제일 가능성이 큽니다. 브라우저에서 인증을 완료한 뒤 터미널로 돌아오지 않는 경우에는 로컬 콜백 포트 차단, 브라우저와 CLI의 출구 불일치, 기존 세션 정보 충돌을 차례로 확인합니다. 이때 여러 번 로그인 버튼을 누르기보다 실패한 세션을 종료하고 새 터미널에서 한 번만 재현하는 편이 좋습니다.

ETIMEDOUT은 대상 호스트에 연결하거나 응답을 기다리는 동안 시간이 초과했다는 뜻입니다. 노드가 실제로 연결 가능한지, DNS가 올바른 주소를 반환하는지, API 요청이 반복해서 같은 프록시 그룹을 타는지 확인하세요. ECONNRESET은 중간 연결이 강제로 끊긴 경우가 많으므로 다른 노드로 바꾸고, TUN과 환경 변수의 중복 적용을 해제한 뒤 비교하는 것이 유용합니다. 401이나 403이 반복된다면 프록시보다는 계정 인증 상태, 환경 변수에 저장된 API 키, 조직 정책 또는 서비스 권한을 먼저 확인해야 합니다.

설치 단계에서만 실패한다면 Claude API 규칙을 수정하기보다 npm 경로를 따로 확인해야 합니다. 패키지 레지스트리와 릴리스 CDN이 서로 다른 도메인을 사용할 수 있기 때문에, 레지스트리 요청 하나만 성공했다고 설치 전체가 끝나는 것은 아닙니다. 설치가 끝난 후에는 같은 방식으로 업데이트가 실행될 수 있으므로, 연결 로그에서 실제로 접근한 호스트를 기록해 두면 다음 장애를 훨씬 빠르게 해결할 수 있습니다.

마지막으로 설정을 한 번에 여러 개 바꾸지 마세요. 먼저 고정 노드와 시스템 프록시만으로 로그인하고, 다음에 TUN을 켜고, 마지막으로 필요한 규칙을 추가하는 순서가 안전합니다. 각 단계에서 claude --version, 로그인, 짧은 테스트 요청을 나눠 실행하면 문제가 설치·인증·API·노드 중 어디에 있는지 명확해집니다. 문제가 해결된 뒤에는 사용하지 않는 프록시 환경 변수를 정리하고, 프로필과 규칙의 백업본을 보관해 두면 업데이트 후에도 같은 구성을 재현하기 쉽습니다.

일반적인 VPN이나 단순 브라우저 확장 방식은 터미널·Node.js·TUN이 서로 다르게 동작하고, 메뉴가 복잡한 일부 프록시 도구는 구독 갱신과 연결 로그를 한곳에서 확인하기 어렵다는 한계가 있습니다. 반면 Clash Verge는 프로필 적용, 프록시 그룹 선택, 시스템 프록시와 TUN 전환, 연결 로그 확인을 단계별로 나눠 Claude Code 접속 문제를 진단하기 편합니다. 설정을 과하게 자동화하지 않고 실제 요청이 어느 규칙을 타는지 확인할 수 있다는 점도 초보자에게 유용합니다. 위 순서대로 기본 연결부터 점검해 보고, 아직 Clash 클라이언트가 없다면 Clash 다운로드에서 환경에 맞는 버전을 받아 시작해 보세요.