Claude Code v2rayN 터미널 설정

Claude Code는 터미널에서 파일을 읽고 수정하거나 명령을 실행하며 코딩 작업을 돕는 도구입니다. 그러나 브라우저처럼 운영체제의 시스템 프록시 설정을 항상 자동으로 사용하는 것은 아닙니다. v2rayN이 연결되어 있고 브라우저도 정상적으로 열리더라도, Claude Code 프로세스에서는 인증 페이지 접속 실패, 모델 요청 시간 초과, TLS 연결 오류가 나타날 수 있습니다.

이 문제는 대개 노드 자체보다 터미널 프로세스가 사용하는 프록시 환경 변수, v2rayN의 로컬 수신 포트, 분할 라우팅 규칙과 DNS 처리의 조합에서 발생합니다. 따라서 노드를 무작정 교체하기보다 v2rayN의 로컬 HTTP 또는 SOCKS 포트를 확인하고, Claude Code를 실행하는 같은 터미널 세션에 프록시를 명시적으로 적용한 뒤 단계별로 연결을 검증하는 편이 빠릅니다.

이 글 한눈에 보기

Claude Code에서 로그인 화면이 열리지 않거나 API 요청이 시간 초과되는 사용자를 위해 v2rayN 프로필 확인, Xray 코어 선택, 시스템 프록시와 터미널 프록시의 차이, Windows PowerShell 환경 변수 설정, 분할 라우팅 점검과 원상 복구 방법을 정리합니다. 기본 예시는 v2rayN 7.x, Xray 코어, HTTP 포트 10809와 SOCKS 포트 10808입니다.

Claude Code 요청이 v2rayN을 거치지 않는 이유

브라우저에서 웹페이지가 열린다는 사실만으로 Claude Code의 요청도 같은 경로를 사용한다고 판단하면 안 됩니다. 브라우저는 Windows 시스템 프록시를 읽거나 자체 프록시 설정을 적용할 수 있지만, 터미널에서 실행된 Node.js 기반 CLI는 환경 변수에 지정된 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY를 우선적으로 확인하는 경우가 많습니다. 이 값이 비어 있으면 프로세스는 직접 연결을 시도할 수 있습니다.

Claude Code의 인증과 모델 요청은 일반적으로 HTTPS 연결을 사용하므로 HTTP 프록시를 지정할 때도 주소는 http://127.0.0.1:10809처럼 작성합니다. 여기서 앞의 http://는 최종 목적지의 통신 방식이 아니라 로컬 HTTP 프록시와 통신하는 방식입니다. v2rayN이 제공하는 HTTP 프록시가 HTTPS의 CONNECT 요청을 처리하면 원격 HTTPS 세션은 프록시 터널 안에서 연결됩니다.

Claude 요청 생성 환경 변수 확인 v2rayN 포트 접수 라우팅 규칙 매칭 원격 HTTPS 연결

브라우저만 정상: 브라우저가 시스템 프록시를 사용하지만 터미널에는 프록시 변수가 없을 가능성이 큽니다.
인증만 실패: 로그인 과정의 브라우저 호출 또는 인증 도메인이 분할 라우팅에서 직접 연결로 빠질 수 있습니다.
인증 후 모델 요청만 실패: API 대상 도메인, TLS 연결, 프록시 인증 또는 터미널 세션의 환경 변수를 확인해야 합니다.
모든 요청이 즉시 실패: v2rayN이 실행되지 않았거나 10809 포트가 변경되었거나 다른 프로세스가 해당 포트를 점유했을 수 있습니다.

10809

v2rayN 기본 HTTP 프록시 포트

10808

v2rayN 기본 SOCKS 포트

HTTPS

인증과 모델 요청의 주요 전송 방식

3단계

포트·변수·라우팅 확인 순서

v2rayN 프로필과 코어 상태 먼저 확인하기

Claude Code 설정을 바꾸기 전에 v2rayN 자체가 정상적으로 노드에 연결되는지 확인하세요. 트레이 아이콘에서 v2rayN을 열고 구독 업데이트가 완료되었는지 확인한 다음, 응답이 안정적인 노드를 선택합니다. 구독을 갱신할 때 시간 초과가 반복되면 현재 노드가 실제로 통신 가능한 상태인지 먼저 브라우저나 간단한 HTTPS 요청으로 점검해야 합니다.

v2rayN 기본 진입점

기준 클라이언트: v2rayN 7.x
권장 코어: Xray
HTTP 포트: 127.0.0.1:10809
SOCKS 포트: 127.0.0.1:10808
확인 메뉴: 설정 → 매개변수 설정

실제 포트는 설치 환경이나 사용자가 변경한 값에 따라 다르므로 화면에 표시된 값을 우선 사용하세요.

Claude Code 실행 조건

프로세스: 같은 터미널 세션
프록시 변수: HTTPS_PROXY 또는 ALL_PROXY
예외 변수: NO_PROXY
라우팅 초기값: 규칙 기반
검증 순서: 포트 → HTTPS → CLI

시스템 프록시가 켜져 있어도 환경 변수에 잘못된 주소가 있으면 Claude Code가 다른 경로를 사용할 수 있습니다.

v2rayN의 시스템 프록시 전환은 브라우저나 운영체제 프록시를 사용하는 애플리케이션에 유용하지만, 터미널 도구에 대한 보장은 아닙니다. 특히 여러 터미널을 열어 둔 상태에서 한 창은 오래된 환경 변수를 가지고 있고 다른 창은 새 값을 가지고 있을 수 있습니다. 환경 변수를 바꾼 뒤에는 기존 터미널을 닫고 새로 열어 적용 여부를 확인하는 것이 안전합니다.

Windows 터미널에 프록시 환경 변수 적용하기

Windows에서는 Claude Code를 실행할 터미널의 종류에 따라 환경 변수 명령이 달라집니다. 아래 예시는 v2rayN의 HTTP 포트가 10809인 경우입니다. 포트를 직접 수정했다면 모든 예시의 숫자를 현재 포트로 바꾸세요. 먼저 v2rayN에서 노드를 연결하고 시스템 프록시를 켠 다음, 터미널에서 로컬 프록시 응답을 확인합니다.

curl.exe -I -x http://127.0.0.1:10809 https://example.com

응답에 HTTP/ 상태 줄이 표시되면 로컬 HTTP 프록시가 요청을 접수한 것입니다. 목적지 응답이 200, 301 또는 403 중 무엇이든 프록시 경로 자체가 열렸다는 판단에는 도움이 됩니다. 반대로 “Failed to connect”가 나오면 Claude Code를 다시 설치하기 전에 v2rayN 실행 상태, 포트 번호와 Windows 방화벽을 확인하세요.

노드 연결 확인

v2rayN에서 구독을 업데이트하고 정상 응답이 확인된 노드를 선택합니다. 상태 표시가 연결됨이어도 로그에서 코어가 반복 재시작하지 않는지 확인하세요.
로컬 포트 확인

「설정」→「매개변수 설정」에서 HTTP 프록시 포트를 확인합니다. 기본값은 10809이며, Claude Code에는 노드의 원격 포트가 아니라 이 로컬 포트를 사용합니다.
HTTPS 변수 지정

PowerShell에서 $env:HTTPS_PROXY="http://127.0.0.1:10809"를 실행합니다. HTTP 요청도 같은 경로로 보내려면 $env:HTTP_PROXY="http://127.0.0.1:10809"를 함께 지정하세요.
연결 테스트

curl.exe -I https://example.com을 실행해 응답을 확인합니다. 프록시 지정 전후의 결과와 v2rayN 로그에 기록된 새 연결을 비교하면 변수 적용 여부를 판단하기 쉽습니다.
Claude 실행

같은 PowerShell 창에서 Claude Code를 실행하고 인증을 진행합니다. 새 터미널에서 실행할 경우 환경 변수를 다시 지정하거나 사용자 환경 변수로 저장해야 합니다.

PowerShell에서 현재 값은 다음과 같이 확인할 수 있습니다.

Get-ChildItem Env:HTTP_PROXY
Get-ChildItem Env:HTTPS_PROXY
Get-ChildItem Env:ALL_PROXY
Get-ChildItem Env:NO_PROXY

명령 프롬프트에서는 문법이 다릅니다. 현재 창에만 적용하려면 다음처럼 입력합니다.

set HTTP_PROXY=http://127.0.0.1:10809
set HTTPS_PROXY=http://127.0.0.1:10809
set ALL_PROXY=http://127.0.0.1:10809
claude

SOCKS 포트를 사용해야 하는 CLI 환경이라면 ALL_PROXY=socks5://127.0.0.1:10808 형식을 고려할 수 있습니다. 다만 모든 Node.js 패키지나 종속 라이브러리가 SOCKS 프록시를 동일하게 처리한다고 단정할 수 없으므로, 우선 v2rayN의 HTTP 포트 10809을 사용하는 편이 문제 범위를 줄이기 쉽습니다. 이미 다른 프록시 변수가 등록되어 있다면 새 값을 덮어쓴 뒤 다시 테스트하세요.

분할 라우팅과 DNS 설정 점검하기

프록시 환경 변수가 올바른데도 특정 요청만 실패한다면 v2rayN의 라우팅 규칙을 확인해야 합니다. 규칙 기반 라우팅은 요청의 도메인, IP, 포트 또는 지리적 목록에 따라 프록시와 직접 연결을 나눕니다. 이때 인증에 사용되는 도메인과 모델 요청에 사용되는 도메인이 서로 다른 그룹으로 처리될 수 있습니다. 한쪽은 프록시로 나가고 다른 쪽은 직접 연결로 빠지면 로그인은 성공했지만 모델 호출이 실패하는 형태가 나타납니다.

모드 확인: 처음 진단할 때는 복잡한 사용자 지정 규칙보다 규칙 기반 또는 전체 프록시 모드로 변수를 줄입니다.
직접 연결 목록 확인: Claude Code가 요청하는 도메인이 국내 도메인 또는 허용 목록으로 잘못 분류되지 않았는지 확인합니다.
DNS 경로 확인: 도메인 조회가 로컬 DNS로만 처리되면 올바른 주소를 얻지 못하거나 예상과 다른 IP로 연결될 수 있습니다.
IPv6 비교: IPv4에서는 연결되지만 IPv6에서 시간 초과가 발생하면 테스트 단계에서 IPv6 우선 경로를 잠시 제외해 차이를 확인합니다.

결론: 먼저 전체 프록시로 원인을 좁히기

분할 라우팅의 장점은 유지하되, 최초 진단에서는 전체 프록시로 인증과 모델 요청을 테스트하세요. 전체 프록시에서 정상 작동한다면 노드보다 도메인 분류, DNS 또는 직접 연결 규칙에 원인이 있을 가능성이 높습니다.

DNS를 변경한다고 해서 모든 HTTPS 트래픽이 자동으로 프록시를 통과하는 것은 아닙니다. DNS는 이름을 주소로 바꾸는 단계이고, 실제 HTTPS 연결의 출구를 선택하는 것은 라우팅과 아웃바운드 설정입니다. v2rayN 로그에서 도메인 조회 실패와 TLS 핸드셰이크 실패를 구분해 보세요. dial tcp, timeout, no such host는 서로 다른 조치가 필요한 메시지입니다.

인증 및 터미널 오류를 단계별로 해석하기

Claude Code의 인증 절차에서 브라우저가 열리지 않는다면 터미널 자체가 인증 URL을 호출하지 못했거나, 브라우저 호출은 성공했지만 인증 후 돌아오는 로컬 콜백이 차단되었을 수 있습니다. 먼저 터미널에 표시된 URL을 복사해 브라우저에서 열어 보되, 브라우저만 정상이고 CLI가 계속 실패하면 해당 터미널 세션의 프록시 변수와 실행 권한을 다시 확인하세요.

오류: connect ETIMEDOUT

원인과 해결: 대상 연결이 시간 초과된 상태입니다. v2rayN이 실행 중인지 확인하고 HTTP 포트 10809을 명시한 뒤, 전체 프록시 모드에서 동일 요청을 재검증하세요.

오류: ECONNREFUSED 127.0.0.1:10809

원인과 해결: 해당 로컬 포트에서 수신 중인 프로세스가 없습니다. v2rayN의 실제 HTTP 포트를 확인하거나 클라이언트를 다시 시작한 뒤 환경 변수 값을 맞추세요.

오류: unable to verify the first certificate

원인과 해결: TLS 인증서 검증 경로에 문제가 있을 수 있습니다. 시스템 시간, 보안 프로그램의 HTTPS 검사와 잘못된 중간 프록시를 점검하고 인증서 검증을 무조건 끄지 마세요.

오류: 407 Proxy Authentication Required

원인과 해결: 지정한 프록시가 인증을 요구하고 있습니다. v2rayN 로컬 포트에 원격 계정 정보를 넣지 말고, 프록시 주소 형식과 실제 수신 포트를 다시 확인하세요.

오류가 발생한 시각을 기록하고 v2rayN 로그에서 같은 시각의 인바운드와 아웃바운드 기록을 비교하세요. 터미널에서 요청을 보냈는데 v2rayN 로그에 아무 흔적도 없다면 환경 변수 미적용, 잘못된 포트 또는 애플리케이션이 프록시 변수를 무시하는 문제가 우선입니다. 로그에는 기록이 있지만 원격 연결이 실패한다면 노드 품질, 라우팅, DNS와 TLS 순서로 좁혀 갈 수 있습니다.

자주 겪는 설정 상황 빠르게 정리하기

시스템 프록시를 켰는데 Claude Code는 왜 직접 연결하나요?

터미널 프로그램이 Windows 시스템 프록시를 읽는다는 보장은 없습니다. PowerShell에서 HTTPS_PROXY를 10809로 지정한 뒤 새 프로세스로 Claude Code를 실행하세요.

HTTP_PROXY와 HTTPS_PROXY를 둘 다 지정해야 하나요?

HTTPS 모델 요청이 중심이어도 두 변수를 같은 로컬 HTTP 포트로 지정하면 도구별 인식 차이를 줄일 수 있습니다. 이미 설정된 값이 있으면 현재 창에서 덮어쓰고 다시 테스트하세요.

로그인 후 모델 요청만 시간 초과되면 무엇을 보나요?

인증 도메인과 모델 API 도메인이 서로 다른 라우팅 규칙을 타는지 확인하세요. 전체 프록시로 바꿔 정상화되는지 비교하면 분할 라우팅 문제를 빠르게 구분할 수 있습니다.

프록시 설정을 원래대로 되돌리려면 어떻게 하나요?

PowerShell에서 Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:ALL_PROXY를 실행하고 새 터미널을 엽니다. 사용자 환경 변수에 저장했다면 Windows 환경 변수 설정에서도 해당 항목을 삭제해야 합니다.

변경 후 최종 검증과 안전한 원상 복구

설정 변경이 끝나면 한 번에 많은 항목을 바꾸지 말고 순서대로 확인하세요. 첫째, v2rayN에서 선택한 노드가 안정적으로 연결되는지 봅니다. 둘째, curl.exe로 10809 HTTP 프록시를 통한 HTTPS 응답을 확인합니다. 셋째, 같은 터미널에서 환경 변수 값을 출력합니다. 넷째, Claude Code를 새 프로세스로 실행해 인증과 간단한 모델 요청을 각각 테스트합니다.

v2rayN 연결을 끊었을 때 curl.exe 요청이 실패하거나 결과가 달라지는지 비교합니다.
v2rayN 로그에 터미널 테스트와 Claude Code 요청이 각각 기록되는지 확인합니다.
전체 프록시에서 성공한 뒤 규칙 기반 라우팅으로 되돌려 같은 명령을 반복합니다.
정상화되면 사용하지 않는 ALL_PROXY를 제거하고 필요한 변수만 유지합니다.
업무용 터미널을 닫기 전에 환경 변수와 인증 토큰이 화면이나 로그에 노출되지 않았는지 확인합니다.

최종적으로는 “v2rayN이 연결됨”, “브라우저가 열림”, “Claude Code가 프록시를 사용함”을 서로 다른 검증 결과로 기록해야 합니다. 세 조건이 모두 충족되어야 터미널 프록시 구성이 완료된 것입니다. 이후 노드를 바꾸거나 v2rayN 포트를 수정하면 해당 터미널의 환경 변수도 함께 갱신하고, 변경 전후의 curl 결과와 코어 로그를 비교하면 같은 오류가 재발했을 때 원인을 더 빠르게 찾을 수 있습니다.