Claude Code v2rayN 설정법과 터미널 접속 문제 해결 가이드

Claude Code 터미널 프록시의 기본 구조

Claude Code는 터미널에서 명령을 실행하고 계정 인증 또는 API 요청을 처리하는 개발 도구입니다. 이때 Claude Code 자체에 v2rayN 노드를 직접 입력하는 것이 아니라, v2rayN이 제공하는 로컬 프록시 포트를 터미널 프로세스가 사용하도록 지정합니다. v2rayN은 원격 노드와 연결하고, Claude Code는 HTTP_PROXY, HTTPS_PROXY 또는 ALL_PROXY 같은 환경 변수를 통해 로컬 주소로 요청을 보냅니다.

구조를 단순하게 표현하면 Claude Code의 HTTPS 요청이 먼저 127.0.0.1의 로컬 포트로 전달되고, v2rayN의 Xray 코어가 해당 요청을 선택한 노드로 중계합니다. 따라서 문제를 진단할 때는 Claude Code 로그인 상태, 터미널 환경 변수, v2rayN 로컬 포트, 선택한 노드의 연결 상태를 서로 분리해서 확인해야 합니다. 네 단계 중 하나만 잘못되어도 “로그인 실패” 또는 “연결할 수 없음”처럼 비슷한 메시지가 나타날 수 있습니다.

이 글에서는 v2rayN 7.x 계열의 일반적인 메뉴 구성을 기준으로 설명합니다. 버전에 따라 메뉴 이름이나 기본 포트는 달라질 수 있으므로 숫자를 무조건 고정하지 말고 v2rayN의 설정 화면에서 현재 값을 확인하세요. 일반적인 HTTP 포트는 10809, SOCKS 포트는 10808이지만 다른 프로그램이 이미 사용 중이면 자동으로 변경되었을 수 있습니다.

v2rayN에 구독을 추가하고 노드 확인하기

먼저 Claude Code의 환경 변수를 설정하기 전에 v2rayN에서 노드 하나가 정상적으로 연결되는지 확인해야 합니다. 프록시와 Claude Code를 동시에 처음 설정하면 어느 단계에서 실패했는지 알기 어렵습니다. 구독이 이미 있다면 업데이트 후 지연 시간이 낮고 최근까지 사용 가능한 노드를 하나 선택하세요. 노드 이름에 특정 지역이나 속도가 표시되어 있어도 실제 품질은 시간대, 손실률, 서버 부하에 따라 달라집니다.

1. 설치 파일 준비

   설치 패키지 확인 페이지에서 현재 운영체제에 맞는 v2rayN 패키지를 받고 별도 폴더에 압축을 풉니다. 기존 설정 폴더를 덮어쓰기 전에 구독 주소와 로컬 포트 값을 따로 기록하세요.

2. 구독 그룹 추가

   v2rayN을 실행한 뒤 ‘구독 그룹’ 또는 ‘Subscription Group’ 메뉴에서 새 항목을 추가하고 구독 URL을 붙여 넣습니다. 주소 앞뒤의 공백과 메신저가 삽입한 줄바꿈을 제거한 뒤 저장하세요.

3. 노드 업데이트

   구독 그룹 목록에서 방금 만든 그룹을 선택하고 ‘업데이트’ 또는 ‘Update subscription’을 실행합니다. 노드 수가 0개이면 Claude Code 설정을 진행하지 말고 구독 응답과 링크 만료 여부부터 확인하세요.

4. 연결 테스트

   서버 목록에서 한 노드를 선택하고 ‘속도 테스트’ 또는 실제 연결을 실행합니다. 연결 중 v2rayN 상태가 활성화되고 로그에 반복적인 timeout이 없는지 확인한 다음 시스템 프록시를 잠시 켜 웹 접속도 테스트합니다.

5. 로컬 포트 기록

   ‘설정’ → ‘파라미터 설정’ 또는 ‘Settings’ → ‘Parameters’에서 HTTP 프록시와 SOCKS 포트 값을 확인합니다. 이 값은 아래 환경 변수에 입력할 값이므로 기본값이라고 추측하지 말고 현재 화면의 숫자를 사용하세요.

구독 URL은 계정 접근 권한과 연결되어 있으므로 터미널 로그, 화면 캡처, 공개 게시물에 그대로 남기지 마세요. 또한 노드 테스트가 실패한 상태에서 환경 변수만 반복해서 바꾸면 원격 서버 문제를 로컬 프록시 문제로 오해할 수 있습니다. 먼저 브라우저나 일반 명령줄 요청이 v2rayN을 통해 전달되는지 확인한 후 Claude Code를 실행하는 순서가 안전합니다.

프록시 모드와 로컬 포트 선택

Claude Code만 프록시를 사용하게 하려면 시스템 전체 프록시보다 터미널 세션에만 환경 변수를 적용하는 방법이 적합합니다. 시스템 프록시는 다른 개발 도구, 패키지 관리자, 브라우저까지 함께 영향을 받으므로 인증서 다운로드나 사내 서비스 접속에 예상하지 못한 문제가 생길 수 있습니다. 반대로 Claude Code가 별도 프로세스로 실행되고 환경 변수를 상속받지 않는 구조라면 실행 셸의 설정을 다시 확인해야 합니다.

HTTP 프록시를 사용할 때는 보통 HTTPS_PROXY=http://127.0.0.1:10809처럼 지정합니다. 변수 이름은 운영체제와 라이브러리에 따라 대문자를 권장하며, 일부 명령줄 도구는 소문자 변수도 확인하므로 대문자와 소문자를 함께 설정해 호환성을 높일 수 있습니다. 다만 이미 회사 네트워크에서 프록시 변수를 제공하고 있다면 기존 값을 덮어쓰기 전에 기록해 두세요.

# 현재 터미널 세션에서만 적용하는 예시
export HTTP_PROXY=http://127.0.0.1:10809
export HTTPS_PROXY=http://127.0.0.1:10809
export NO_PROXY=localhost,127.0.0.1

# 값이 적용되었는지 확인
env | grep -i proxy

NO_PROXY에 localhost와 127.0.0.1을 넣는 이유는 로컬 관리 화면이나 로컬 개발 서버가 다시 프록시로 들어가는 루프를 줄이기 위해서입니다. 다만 내부 도메인이나 사내 주소를 직접 연결해야 한다면 해당 도메인 suffix를 환경에 맞게 추가하세요. 무조건 NO_PROXY=*로 설정하면 Claude Code 요청까지 우회될 수 있으므로 사용 목적을 확인해야 합니다.

Claude Code 실행 환경 변수 설정

환경 변수는 Claude Code가 실행되는 같은 터미널 세션에서 설정해야 합니다. 별도의 터미널에서 export를 실행한 뒤 새 창에서 Claude Code를 열면 값이 상속되지 않습니다. Windows PowerShell은 $env:, Windows 명령 프롬프트는 set, macOS와 Linux의 일반 셸은 export 문법을 사용합니다.

# PowerShell
$env:HTTP_PROXY="http://127.0.0.1:10809"
$env:HTTPS_PROXY="http://127.0.0.1:10809"
$env:NO_PROXY="localhost,127.0.0.1"

# macOS 또는 Linux
export HTTP_PROXY="http://127.0.0.1:10809"
export HTTPS_PROXY="http://127.0.0.1:10809"
export NO_PROXY="localhost,127.0.0.1"

Claude Code의 인증 방식은 설치 버전과 계정 유형, 사용 중인 서비스 정책에 따라 달라질 수 있습니다. 공식 로그인 흐름을 사용하는 경우에는 프록시 변수만 설정하고 Claude Code가 안내하는 브라우저 인증 또는 터미널 인증 절차를 진행하세요. API 키를 사용하는 환경이라면 키를 명령줄 인자로 직접 노출하지 말고 운영체제의 안전한 환경 변수나 비밀 저장소를 사용해야 합니다.

특히 ANTHROPIC_BASE_URL은 로컬 프록시 주소와 같은 의미가 아닙니다. 이 변수는 API 호환 게이트웨이나 별도의 API 엔드포인트를 사용할 때 지정하는 주소이며, 단순히 v2rayN을 통해 공식 API로 접속하려는 목적이라면 임의로 http://127.0.0.1:10809로 설정하면 안 됩니다. 로컬 HTTP 포트는 프록시 주소이고 API의 기본 주소가 아니므로 두 개념을 혼동하지 마세요.

터미널에서 프록시 적용 여부 확인하기

Claude Code를 바로 실행하기 전에 간단한 HTTPS 요청으로 환경 변수가 작동하는지 확인하는 것이 좋습니다. 테스트 명령의 성공 여부는 API 인증 성공과 다르지만, 적어도 DNS, TCP 연결, TLS 협상과 로컬 포트 전달이 가능한지 분리해서 볼 수 있습니다. 테스트 결과가 실패하면 Claude Code 설정을 바꾸기보다 v2rayN 노드와 포트부터 점검하세요.

# HTTP 프록시를 명시한 연결 테스트 예시
curl -I -x http://127.0.0.1:10809 https://api.anthropic.com/

# 현재 셸의 변수를 사용해 테스트
curl -I https://api.anthropic.com/

응답 상태 코드가 401 또는 인증 관련 오류라고 해도 네트워크 경로 자체는 도달했을 가능성이 있습니다. 반대로 Could not resolve host, Connection refused, Failed to connect가 나타나면 인증 이전 단계의 문제일 수 있습니다. curl이 프록시를 사용했는지 확실하지 않다면 -v 옵션으로 연결 대상이 127.0.0.1:10809인지 확인하세요.

로그인과 API 연결 오류별 해결 방법

로그인 브라우저가 열리지 않는 경우에는 터미널 환경 변수 자체보다 인증 흐름이 사용할 브라우저와 콜백 주소가 영향을 받을 수 있습니다. 기본 브라우저가 열리는지, 로컬 콜백 포트가 방화벽에 의해 차단되지 않았는지 확인하세요. 인증 페이지는 열리지만 완료 후 터미널로 돌아오지 않는다면 프록시가 로컬 주소를 원격으로 전달하고 있지 않은지 NO_PROXY 설정을 확인합니다.

안정적인 일상 사용을 위한 점검 순서

설정을 마친 뒤에는 매번 모든 값을 바꾸기보다 고정된 확인 순서를 사용하는 것이 좋습니다. 먼저 v2rayN이 실행되어 있고 선택한 노드가 연결 상태인지 확인합니다. 다음으로 터미널에서 echo $HTTPS_PROXY 또는 PowerShell의 $env:HTTPS_PROXY를 확인합니다. 그 후 짧은 HTTPS 요청을 실행하고, 마지막으로 Claude Code를 새 프로세스로 시작합니다. 이 순서를 지키면 노드 만료와 환경 변수 누락을 빠르게 구분할 수 있습니다.

• v2rayN에서 구독을 업데이트하고 노드 수가 1개 이상인지 확인합니다.
• 속도 테스트가 통과한 노드를 선택하고 코어 로그에 연속 재연결이 없는지 봅니다.
• HTTP 포트와 SOCKS 포트를 혼동하지 않고 현재 설정 화면의 값을 사용합니다.
• 환경 변수에 불필요한 따옴표, 한글 공백, 끝부분 줄바꿈이 들어가지 않았는지 확인합니다.
• 공식 API 주소를 사용하는 경우 ANTHROPIC_BASE_URL을 임의의 로컬 프록시 주소로 덮어쓰지 않습니다.
• 작업이 끝난 뒤 공유 컴퓨터나 공용 터미널에 API 키와 프록시 URL이 남아 있지 않은지 삭제합니다.

연결이 갑자기 끊기면 가장 먼저 다른 노드로 바꾸기보다 같은 노드에서 터미널 HTTPS 테스트를 반복해 보세요. 테스트 자체가 실패하면 v2rayN, DNS, 원격 노드의 문제이고 테스트는 성공하지만 Claude Code만 실패하면 인증 정보, API 엔드포인트, 셸 상속 또는 프로그램 버전의 문제일 가능성이 높습니다. 이처럼 단계별로 범위를 줄여야 설정을 불필요하게 초기화하지 않고 원인을 찾을 수 있습니다.