Claude Code 연결 오류 해결: v2rayN으로 터미널 프록시 설정하기

Claude Code를 실행했을 때 로그인 화면이 멈추거나 요청이 시간 초과된다면, 먼저 터미널 프로그램이 v2rayN의 로컬 프록시를 사용하고 있는지 확인하세요. v2rayN에서 시스템 프록시를 켜도 터미널이 그 설정을 자동으로 따르는 것은 아닙니다. 이 글에서는 로컬 리스너 포트 확인, 셸 환경 변수 설정, 연결 테스트, 라우팅과 인증 문제 구분까지 순서대로 점검합니다.

이 글의 핵심

Claude Code의 연결 문제를 점검할 때는 터미널의 프록시 환경 변수와 v2rayN의 로컬 리스너, 코어 라우팅을 각각 확인해야 합니다. 예시 포트는 실제 설정에 맞게 바꾸고, 프록시를 명시한 연결 테스트와 Claude Code 실행 결과를 비교하면 문제가 어느 단계에서 발생하는지 좁힐 수 있습니다.

1. 시스템 프록시와 터미널 프록시는 별개입니다

v2rayN의 시스템 프록시 기능은 운영체제의 프록시 설정을 바꾸는 기능입니다. 브라우저처럼 시스템 설정을 따르는 앱도 있지만, 터미널에서 실행한 CLI 도구는 자체 설정이나 환경 변수를 기준으로 연결하는 경우가 많습니다. 따라서 브라우저에서 웹사이트가 열린다는 사실만으로 Claude Code도 프록시를 사용하고 있다고 볼 수는 없습니다.

Claude Code 요청 프록시 환경 변수 v2rayN 로컬 리스너 라우팅 규칙 원격 서비스

연결은 여러 단계로 나뉩니다. 터미널 프로그램이 프록시 주소를 사용해 로컬 리스너에 접속하고, v2rayN의 코어가 요청을 받은 다음 라우팅 규칙에 따라 프록시 또는 직접 연결을 선택합니다. 어느 한 단계라도 설정이 맞지 않으면 터미널에서만 연결이 실패할 수 있습니다.

로컬 연결 실패: 환경 변수의 주소나 포트가 틀렸거나, 해당 포트에서 프록시 리스너가 실행 중이 아닐 수 있습니다.
원격 연결 실패: 로컬 프록시는 요청을 받았지만 노드, DNS, 전송 설정 또는 대상 서비스와의 연결에 문제가 있을 수 있습니다.
인증 단계 실패: 네트워크 연결은 되었지만 계정 인증, 권한 또는 서비스 측 제한에서 거부됐을 수 있습니다.

이 구분을 해 두면 구독을 반복해서 가져오거나 노드 정보를 무작정 바꾸는 일을 줄일 수 있습니다. 우선 Claude Code를 실행하는 바로 그 터미널에서 프록시를 명시한 연결 테스트를 해 보세요.

2. v2rayN의 로컬 프록시 포트 확인

환경 변수에 입력할 주소는 원격 노드 주소가 아니라 PC에서 실행 중인 v2rayN의 로컬 리스너 주소입니다. 일반적인 예시로 127.0.0.1:10809를 들 수 있지만, 이는 모든 설치 환경의 기본값이라는 뜻은 아닙니다. SOCKS와 HTTP 리스너 포트가 서로 다를 수 있고, 사용자가 변경했거나 배포 설정에 따라 값이 달라질 수 있습니다.

HTTP 프록시 예시

주소: 127.0.0.1
예시 포트: 10809
환경 변수: HTTP_PROXY, HTTPS_PROXY

현재 v2rayN에서 HTTP를 지원하는 리스너 주소와 포트를 확인하세요.

SOCKS 프록시 예시

주소: 127.0.0.1
예시 포트: 10808
테스트 표기: socks5h://

SOCKS 리스너가 실제로 열려 있을 때만 해당 포트를 사용하세요.

v2rayN에서 ‘설정’ → ‘매개변수 설정’으로 이동해 로컬 리스너 관련 항목을 확인합니다. 메뉴 이름과 위치는 버전에 따라 다를 수 있으므로 화면에 표시된 실제 설정을 기준으로 하세요. 확인할 때는 리스너 종류, 포트, 수신 주소를 함께 기록합니다. 127.0.0.1은 같은 PC에서만 접근하는 로컬 주소이므로, 원격 컴퓨터에서 실행하는 Claude Code에는 그대로 사용할 수 없습니다.

HTTP 리스너와 SOCKS 리스너를 혼동하지 않는 것도 중요합니다. HTTP 리스너에는 http://를, SOCKS 테스트에는 지원되는 경우 socks5h://를 사용합니다. 주소와 포트가 맞아도 프로토콜 표기가 틀리면 연결 테스트가 실패하거나 DNS 처리 방식이 예상과 달라질 수 있습니다.

3. Claude Code를 실행하기 전에 프록시 테스트

먼저 Claude Code와 같은 터미널에서 프록시를 지정한 요청을 보내 보세요. 아래 명령의 포트는 예시입니다. v2rayN에서 확인한 HTTP 리스너 포트로 바꾸고, 운영체제에 맞는 명령만 실행합니다.

# Windows PowerShell: HTTP 프록시 리스너 예시
curl.exe -v --proxy http://127.0.0.1:10809 --connect-timeout 5 --max-time 15 https://example.com/ -o NUL

# macOS 또는 Linux: HTTP 프록시 리스너 예시
curl -v --proxy http://127.0.0.1:10809 --connect-timeout 5 --max-time 15 https://example.com/ -o /dev/null

# 해당 포트가 SOCKS5를 지원할 때만 사용
curl -v --proxy socks5h://127.0.0.1:10808 --connect-timeout 5 --max-time 15 https://example.com/ -o /dev/null

상세 출력에서 먼저 로컬 주소에 연결하는지 확인하고, 그다음 HTTPS 연결이 진행되는지 살펴봅니다. HTTP 프록시로 HTTPS 사이트에 접속하면 CONNECT 요청이 표시될 수 있습니다. example.com은 테스트용 주소이므로 실제 확인할 수 있는 HTTPS 사이트로 바꿔도 됩니다. 이 테스트는 프록시 경로를 확인하는 용도이지 Claude Code의 계정 인증을 검증하는 테스트는 아닙니다.

테스트가 로컬 포트 연결 단계에서 실패하면 먼저 v2rayN이 실행 중인지, 선택한 리스너가 활성화되어 있는지, 포트 번호가 일치하는지 확인하세요. 로컬 연결은 성공했지만 원격 요청이 시간 초과되면 v2rayN 로그에서 테스트 시각과 대상 주소를 찾아 노드 연결과 라우팅 결과를 확인합니다.

4. 셸 환경 변수 설정 후 Claude Code 실행

Claude Code를 시작하기 전에 현재 터미널 세션에 프록시 환경 변수를 설정합니다. 아래 예시에서는 HTTP 리스너를 127.0.0.1:10809로 가정합니다. 실제 포트를 확인한 뒤 바꾸세요. 터미널을 새로 열거나 값을 삭제하면 임시 설정은 사라지므로, 먼저 이 방식으로 연결을 검증하는 편이 안전합니다.

포트 확인

v2rayN에서 HTTP 리스너의 주소와 포트를 확인합니다. 아래 명령의 10809를 실제 값으로 바꾸세요.
변수 설정

Claude Code를 실행할 터미널에 HTTP_PROXY와 HTTPS_PROXY를 설정합니다. 설정한 셸과 실행할 셸이 같은지 확인하세요.
값 확인

환경 변수의 주소와 포트에 오타가 없는지 확인합니다. 다른 프록시 값이나 우회 목록이 남아 있다면 테스트 중에는 함께 점검하세요.
실행 비교

같은 터미널에서 Claude Code를 실행하고 오류가 달라지는지 확인합니다. 실행 전후 시각을 기록하면 v2rayN 로그와 대조하기 쉽습니다.

# Windows PowerShell: 현재 창에만 적용
$env:HTTP_PROXY = "http://127.0.0.1:10809"
$env:HTTPS_PROXY = "http://127.0.0.1:10809"
claude

# Windows 명령 프롬프트: 현재 창에만 적용
set HTTP_PROXY=http://127.0.0.1:10809
set HTTPS_PROXY=http://127.0.0.1:10809
claude

# macOS 또는 Linux: 현재 셸에만 적용
export HTTP_PROXY="http://127.0.0.1:10809"
export HTTPS_PROXY="http://127.0.0.1:10809"
claude

환경 변수는 운영체제 전체에 한 번 설정했다고 모든 실행 환경에 전달되는 값이 아닙니다. VS Code 통합 터미널, Windows Terminal, 원격 셸처럼 Claude Code를 실행하는 위치마다 부모 프로세스와 셸 설정이 다를 수 있습니다. 환경 변수를 지정한 터미널에서 직접 claude를 실행해 비교하세요. 필요하지 않은 프록시 변수는 다른 네트워크 작업에 영향을 줄 수 있으므로 문제 해결 후 제거하거나 원하는 범위에만 적용합니다.

5. 연결 로그와 라우팅으로 실패 지점 찾기

프록시를 지정한 curl 테스트가 성공하지만 Claude Code만 실패한다면, 먼저 Claude Code를 실행한 터미널의 환경 변수를 확인하세요. 변수가 올바른데도 차이가 있으면 터미널의 출력과 v2rayN 로그를 같은 시각 기준으로 비교합니다. v2rayN에서 요청이 기록되지 않았다면 환경 변수 전달이나 앱의 프록시 처리 단계부터 살펴보고, 요청이 기록됐다면 코어의 라우팅과 원격 연결을 확인합니다.

관찰한 증상	가능성이 높은 단계	다음 확인
로컬 포트 연결 거부	리스너 또는 포트 설정	v2rayN 실행 상태와 HTTP/SOCKS 포트 일치 여부
curl은 성공하지만 Claude Code는 실패	환경 변수 전달 또는 앱 동작	같은 셸에서 변수를 확인하고 Claude Code를 다시 실행
v2rayN 로그에 요청이 보이고 시간 초과	라우팅 또는 원격 연결	선택된 아웃바운드, 노드 연결, DNS와 코어 오류 로그
서비스가 인증 또는 권한 오류를 반환	서비스 계정 단계	계정 로그인 상태와 서비스 안내를 별도로 확인

사용자 지정 라우팅을 쓰고 있다면 터미널 연결이 예상한 아웃바운드로 처리되는지도 확인합니다. 로컬 프록시가 요청을 받았다는 사실만으로 반드시 원격 프록시 노드를 거친다는 뜻은 아닙니다. 규칙에 따라 직접 연결되는 경우도 있으므로, 요청 대상과 일치하는 규칙의 순서 및 outboundTag를 살펴보세요. 특정 도메인 목록을 검증되지 않은 채 통째로 추가하기보다 실제 로그에 나온 대상과 현재 코어의 규칙 형식을 기준으로 조정합니다.

결론: 성공한 단계는 그대로 두고 다음 단계만 점검하세요

로컬 프록시 테스트가 통과했다면 포트를 반복 변경하지 말고 환경 변수와 Claude Code 실행 환경을 확인하세요. v2rayN에 요청이 기록되면 그때 라우팅과 원격 연결을 살펴보면 원인을 더 빠르게 좁힐 수 있습니다.

6. 자주 놓치는 설정과 안전한 정리

프록시 환경 변수를 설정한 뒤에도 오류가 계속되면 모든 항목을 한꺼번에 바꾸지 말고, 아래 항목을 하나씩 확인하세요. 특히 NO_PROXY 또는 no_proxy에 넓은 범위의 값이 들어 있으면 일부 요청이 프록시를 우회할 수 있습니다. 연결 테스트와 실제 실행의 결과가 다른 경우에는 셸별 환경 변수와 우회 목록을 비교합니다.

시스템 프록시를 켰는데도 터미널에서 실패해요.

Claude Code를 실행하는 터미널에 HTTP_PROXY와 HTTPS_PROXY를 설정한 뒤, 같은 창에서 프록시 지정 연결 테스트를 실행하세요.

v2rayN 포트를 그대로 입력했는데 연결이 거부돼요.

그 포트가 HTTP 리스너인지 SOCKS 리스너인지 확인하고, v2rayN 화면의 현재 포트와 명령의 포트를 대조하세요. 다른 PC에서 실행 중이라면 127.0.0.1은 대상 PC 자신을 가리킨다는 점도 확인합니다.

curl은 되는데 Claude Code만 연결되지 않아요.

성공한 curl과 Claude Code를 같은 셸에서 실행했는지 확인하고, 환경 변수가 전달된 터미널인지 점검하세요. 그다음 Claude Code의 오류 문구가 네트워크 시간 초과인지 인증·권한 문제인지 구분합니다.

환경 변수에 토큰이나 계정 정보를 넣어야 하나요?

이 글의 프록시 변수에는 로컬 프록시 주소만 입력합니다. 구독 링크, 인증 토큰, 계정 비밀번호를 프록시 주소에 붙이거나 로그와 명령 기록에 노출하지 마세요.

문제 해결이 끝나면 임시 설정을 정리합니다. PowerShell에서는 Remove-Item Env:HTTP_PROXY와 Remove-Item Env:HTTPS_PROXY를 실행할 수 있고, macOS나 Linux에서는 unset HTTP_PROXY HTTPS_PROXY를 사용합니다. 영구 설정 파일을 수정했다면 그 파일에서도 해당 줄을 삭제하거나 필요한 값으로 되돌리세요. 마지막으로 같은 터미널에서 기본 연결과 프록시 연결을 각각 시험해 변경 결과가 의도한 범위에만 적용됐는지 확인합니다.