Claude Code v2rayN 설정법과 터미널 프록시 연결 팁

Claude Code를 터미널 중심으로 사용하려면 먼저 v2rayN이 정상적으로 실행되고 있는지, 그리고 터미널 프로세스가 어떤 프록시 주소와 포트를 사용해야 하는지 확인해야 합니다. v2rayN에서 노드를 선택했다고 해서 모든 명령줄 프로그램이 자동으로 프록시를 사용하는 것은 아닙니다. Windows 시스템 프록시를 따르는 프로그램과 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 같은 환경 변수를 읽는 프로그램은 동작 방식이 다르기 때문입니다. 이 글에서는 v2rayN의 노드 선택부터 터미널 환경 변수 적용, 연결 테스트와 원상 복구까지 순서대로 정리합니다.

v2rayN과 터미널 프록시의 연결 구조

v2rayN은 서버 노드와 직접 통신하는 프로그램이 아니라 컴퓨터에 로컬 프록시 포트를 열고, 애플리케이션의 요청을 선택한 노드를 통해 전달하는 클라이언트입니다. 따라서 Claude Code가 프록시를 사용하려면 “Claude Code가 접속하는 로컬 포트”와 “v2rayN이 실제로 열어 둔 포트”가 일치해야 합니다. 일반적으로 v2rayN의 로컬 포트는 10808, HTTP 포트는 10809처럼 구성되지만 사용자가 변경했거나 다른 프로그램과 충돌해 값이 달라질 수 있습니다.

프록시 주소는 보통 127.0.0.1 또는 localhost입니다. 127.0.0.1은 현재 컴퓨터 자신을 가리키므로 외부 서버 주소가 아닙니다. v2rayN이 로컬에서 HTTP 프록시를 열었다면 http://127.0.0.1:10809처럼 입력하고, SOCKS5 포트를 사용한다면 socks5://127.0.0.1:10808처럼 스킴을 명시합니다. 애플리케이션이 SOCKS5 환경 변수를 제대로 해석하지 못하는 경우에는 v2rayN의 HTTP 포트나 혼합 포트를 먼저 사용하는 편이 확인하기 쉽습니다.

v2rayN에서 노드와 로컬 포트 확인하기

Claude Code 설정을 시작하기 전에 v2rayN에서 실제로 사용할 노드를 선택합니다. 구독을 방금 추가했다면 먼저 메인 화면의 「구독 그룹」 메뉴에서 해당 그룹을 선택하고 「업데이트」 또는 「현재 그룹 업데이트」를 실행합니다. 업데이트가 끝난 뒤 목록에서 노드를 선택하고 마우스 오른쪽 버튼 메뉴의 지연 시간 테스트를 실행하면 응답이 빠른 노드를 고르는 데 도움이 됩니다. 지연 시간 숫자만으로 최종 품질을 판단할 수는 없지만, 연결되지 않는 노드를 초기에 걸러낼 수 있습니다.

1. 노드 선택

   v2rayN 메인 화면에서 사용할 구독 그룹을 고르고, 연결 가능한 노드를 하나 선택합니다. 노드 이름에 표시된 프로토콜보다 실제 테스트 결과와 안정성을 우선하세요.

2. 코어 확인

   「설정」→「매개변수 설정」에서 현재 Core 유형을 확인합니다. VLESS의 REALITY나 Vision 같은 매개변수가 있다면 해당 설정을 해석할 수 있는 Xray 코어를 사용해야 합니다.

3. 포트 확인

   「설정」→「매개변수 설정」→「인바운드」 또는 로컬 프록시 관련 항목에서 SOCKS와 HTTP 포트를 기록합니다. 화면에 표시된 값을 기준으로 사용하고 숫자를 추측하지 마세요.

4. 시스템 프록시 구분

   메인 화면의 시스템 프록시 메뉴는 운영체제 프록시 설정을 바꾸는 기능입니다. 터미널이 이 설정을 읽는다는 보장은 없으므로, 별도로 환경 변수를 적용해 확인합니다.

5. 코어 시작

   선택한 노드로 연결을 시작하고 v2rayN 상태 표시가 실행 중인지 확인합니다. 포트가 열리지 않으면 다른 프록시 프로그램을 잠시 종료한 뒤 다시 테스트하세요.

v2rayN의 시스템 프록시를 켜는 것은 브라우저나 운영체제 프록시 설정을 따르는 일부 프로그램에는 유용합니다. 그러나 터미널 명령은 별도의 세션 환경을 사용하고, Node.js 기반 도구나 자체 네트워크 라이브러리는 시스템 프록시를 무시할 수 있습니다. 그러므로 시스템 프록시를 켠 뒤에도 Claude Code의 요청이 실패한다면 터미널에 명시적인 환경 변수를 설정하는 것이 다음 단계입니다.

HTTP·SOCKS5·혼합 포트 중 무엇을 선택할까

v2rayN에 여러 로컬 포트가 표시된다면 먼저 Claude Code와 함께 실행되는 구성 요소가 어떤 프록시 형식을 지원하는지 확인해야 합니다. HTTP 프록시는 웹 요청과 명령줄 패키지 도구에서 호환성이 좋은 편이며, SOCKS5는 TCP 연결을 폭넓게 전달할 수 있습니다. 혼합 포트는 HTTP와 SOCKS 요청을 하나의 포트에서 처리하도록 구성된 경우에 편리하지만, 클라이언트 코어와 v2rayN 버전에 따라 메뉴 명칭과 지원 범위가 달라질 수 있습니다.

터미널에 환경 변수 적용하는 방법

환경 변수는 현재 열려 있는 터미널 세션에만 적용할 수도 있고, 사용자 계정에 영구적으로 저장할 수도 있습니다. 먼저 일회성 적용으로 테스트하는 것이 안전합니다. 값이 틀렸을 때 기존 개발 도구 전체에 영향을 주지 않고 창을 닫아 원상 복구할 수 있기 때문입니다. 아래 예시에서 10809는 설명용 HTTP 포트이므로, v2rayN 화면에 표시된 실제 포트가 다르면 그 숫자로 바꿔야 합니다.

Windows PowerShell

$env:HTTP_PROXY = "http://127.0.0.1:10809"
$env:HTTPS_PROXY = "http://127.0.0.1:10809"
$env:ALL_PROXY = "socks5://127.0.0.1:10808"
$env:NO_PROXY = "localhost,127.0.0.1"
claude

PowerShell에서 $env:로 설정한 값은 현재 창과 그 창에서 새로 시작하는 프로세스에 전달됩니다. 이미 실행 중인 Claude Code 프로세스에는 소급 적용되지 않으므로 기존 세션을 종료하고 새로 실행해야 합니다. 적용 여부는 다음 명령으로 확인할 수 있습니다.

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

macOS·Linux 셸

export HTTP_PROXY="http://127.0.0.1:10809"
export HTTPS_PROXY="http://127.0.0.1:10809"
export ALL_PROXY="socks5://127.0.0.1:10808"
export NO_PROXY="localhost,127.0.0.1"
claude

Bash 또는 Zsh에서 export로 설정한 값도 현재 셸과 하위 프로세스에만 전달됩니다. 매번 입력하기 번거롭다면 셸 설정 파일에 추가할 수 있지만, 여러 프로젝트에서 항상 프록시를 쓰게 될 수 있으므로 처음부터 영구 적용하는 것은 권하지 않습니다. 프로젝트별로 필요한 경우에는 작업을 시작할 때 별도의 셸 스크립트를 실행하고, 작업이 끝난 뒤 환경 변수를 지우는 방식이 관리하기 쉽습니다.

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY

변수 이름은 도구마다 대소문자를 다르게 읽을 수 있습니다. 일부 네트워크 라이브러리는 대문자만 확인하고, 일부는 소문자 이름도 지원합니다. 요청이 계속 직접 연결되는 것처럼 보이면 다음처럼 소문자 변수도 함께 지정해 볼 수 있습니다. 같은 이름에 서로 다른 포트를 입력하면 혼란이 생기므로 모든 값은 동일한 로컬 프록시 구성을 가리키게 유지하세요.

export http_proxy="http://127.0.0.1:10809"
export https_proxy="http://127.0.0.1:10809"
export all_proxy="socks5://127.0.0.1:10808"

Claude Code 실행 전 연결 테스트

Claude Code를 바로 재실행하기보다 먼저 터미널 자체에서 프록시 연결을 확인하면 진단 시간이 줄어듭니다. 테스트 대상은 공개적으로 접근 가능한 HTTPS 주소처럼 현재 환경에서 허용된 주소를 사용하세요. PowerShell에서는 curl.exe를 명시하면 PowerShell 별칭과 실제 cURL 명령의 차이를 피할 수 있습니다. 연결 결과가 HTTP 응답 코드로 돌아오면 적어도 터미널 프로세스가 프록시 포트까지 접근하고 있다는 뜻입니다.

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

macOS와 Linux에서는 다음과 같이 테스트할 수 있습니다.

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

이 테스트에서 “Failed to connect to 127.0.0.1 port 10809”가 표시되면 원격 노드의 문제보다 로컬 포트, v2rayN 실행 상태 또는 방화벽을 먼저 확인해야 합니다. “Connection timed out”이 나타나면 v2rayN은 포트를 열었지만 선택한 노드, DNS, 서버 상태 또는 네트워크 경로에 문제가 있을 수 있습니다. 테스트는 성공하지만 Claude Code만 실패한다면 환경 변수 전달 여부, 도구 자체의 프록시 지원과 인증 요청 차이를 확인해야 합니다.

실행 안정성을 높이는 Claude Code 설정 팁

프록시가 연결되더라도 모든 요청이 같은 방식으로 처리되는 것은 아닙니다. Claude Code 실행 파일 자체의 요청, 로그인 또는 인증 흐름, 프로젝트에서 사용하는 패키지 관리자와 버전 관리 도구가 각각 다른 라이브러리를 사용할 수 있습니다. 따라서 한 번의 웹 요청이 성공했다는 결과만으로 모든 기능이 정상이라고 단정하지 말고, 실제 작업에 필요한 명령을 작은 범위에서 확인해야 합니다.

• Claude Code를 실행하는 터미널과 환경 변수를 입력한 터미널이 같은 창인지 확인합니다.
• v2rayN에서 노드를 바꿨다면 기존 Claude Code 세션을 종료하고 새 세션을 시작합니다.
• 프로젝트의 패키지 설치 명령이 별도 셸이나 IDE 터미널에서 실행되는지 확인합니다.
• 내부망 주소와 로컬 개발 서버는 NO_PROXY에 추가해 불필요하게 외부 노드로 보내지 않도록 합니다.
• 인증 토큰이나 구독 주소를 명령 기록, 화면 공유 자료와 로그에 그대로 남기지 않습니다.

프록시 사용 범위는 필요한 작업에 맞춰 최소화하는 것이 좋습니다. 모든 명령을 무조건 프록시로 보내면 내부 저장소, 로컬 API, 사설 네트워크에 접근할 때 오히려 지연이나 인증 문제가 생길 수 있습니다. 반대로 Claude Code가 외부 서비스에 요청해야 하는데 특정 도메인을 NO_PROXY에 넣으면 연결이 직접 전환되어 실패할 수 있습니다. 예외 목록은 한 번에 크게 작성하기보다 실제 오류가 발생한 주소만 추가하며 관리하세요.

연결 실패 시 점검 순서

문제가 생겼을 때 노드, 포트, 환경 변수를 동시에 바꾸면 원인을 찾기 어렵습니다. 다음 순서로 한 단계씩 확인하면 설정 변경을 최소화할 수 있습니다. 먼저 v2rayN 메인 화면에서 코어가 실행 중인지 확인하고, 그다음 로컬 포트에 연결되는지 테스트합니다. 로컬 연결이 성공한 뒤에만 원격 주소와 Claude Code 동작을 확인해야 합니다.

1. v2rayN에서 선택한 노드가 실제로 연결 가능한지 지연 시간과 코어 상태를 확인합니다.
2. 「설정」→「매개변수 설정」에서 HTTP 포트와 SOCKS 포트를 다시 기록합니다.
3. 터미널의 HTTP_PROXY와 HTTPS_PROXY가 같은 HTTP 포트를 가리키는지 확인합니다.
4. curl로 HTTPS 요청을 보내 로컬 프록시와 외부 연결을 분리해 테스트합니다.
5. 테스트가 성공하면 새 터미널 세션에서 Claude Code를 실행하고, 실패하면 v2rayN 코어 로그의 시간 초과와 TLS 오류를 확인합니다.
6. 노드 변경, 포트 변경, 환경 변수 변경 중 한 가지씩만 적용한 뒤 같은 요청을 반복합니다.

포트가 이미 사용 중이라는 메시지가 나오면 다른 프록시 클라이언트, 개발용 로컬 서버 또는 이전에 종료되지 않은 코어 프로세스가 해당 포트를 점유하고 있을 수 있습니다. 이때 무작정 포트를 바꾸기보다 점유 프로세스를 확인하고, v2rayN에서 새 포트를 지정한 뒤 모든 환경 변수를 새 값으로 함께 수정해야 합니다. Windows에서는 netstat -ano | findstr :10809로 점유 상태를 확인할 수 있고, macOS·Linux에서는 lsof -i :10809를 사용할 수 있습니다.