Claude Code 터미널 연결 문제, v2rayN V2Ray 프록시 설정으로 해결하기

브라우저에서는 사이트가 열리는데 Claude Code의 로그인이나 요청은 실패한다면, 브라우저가 사용하는 프록시와 터미널 프로그램이 사용하는 프록시가 다를 수 있습니다. v2rayN에서 노드를 선택하고 시스템 프록시를 켜는 것만으로는 터미널에서 시작한 모든 프로그램의 연결이 프록시를 거친다고 보장할 수 없습니다. Claude Code를 실행하는 셸에 프록시 환경 변수를 설정하고, 같은 셸에서 연결을 확인해야 합니다.

이 글의 핵심

v2rayN을 사용하지만 Claude Code 로그인, API 요청 또는 업데이트가 시간 초과되는 경우를 위한 안내입니다. v2rayN의 로컬 HTTP 수신 포트를 확인하고, Claude Code를 실행하는 PowerShell이나 셸에 HTTP_PROXY와 HTTPS_PROXY를 설정하는 순서로 점검합니다. 포트 값은 예시가 아니라 현재 클라이언트에서 확인해야 할 설정이며, 브라우저 연결과 터미널 연결을 별도로 테스트하는 방법도 다룹니다.

1. 브라우저와 터미널의 프록시 경로 구분하기

v2rayN은 구독과 노드를 관리하고 로컬 프록시 수신점을 제공하는 클라이언트입니다. 브라우저가 Windows 시스템 프록시 설정을 따르더라도 터미널에서 실행한 프로그램이 같은 설정을 자동으로 따르는 것은 아닙니다. Claude Code는 명령줄 프로그램이므로 실행된 프로세스의 환경 변수와 네트워크 라이브러리가 프록시를 사용할 수 있는지가 중요합니다.

Claude Code 요청 셸 환경 변수 v2rayN 로컬 포트 선택한 노드 Anthropic 서비스

이 경로에서 한 단계라도 빠지면 브라우저만 접속되고 터미널 요청은 실패할 수 있습니다. 예를 들어 시스템 프록시가 켜져 있어도 셸에 프록시 변수가 설정되지 않았거나, 변수에 SOCKS 포트를 잘못 지정했거나, v2rayN 코어가 해당 포트에서 수신하지 않으면 Claude Code가 프록시를 이용하지 못할 수 있습니다. 반대로 환경 변수가 올바르더라도 선택한 노드가 중단되었거나 라우팅 규칙에서 목적지 요청을 직접 연결하도록 처리하면 기대한 결과가 나오지 않습니다.

브라우저만 성공: 브라우저의 프록시 설정과 v2rayN 시스템 프록시는 정상일 수 있지만, Claude Code를 실행하는 셸의 환경 변수는 별도로 확인해야 합니다.
터미널의 모든 HTTPS 요청이 실패: 프록시 주소·포트, 노드 연결, DNS, 방화벽 순으로 범위를 좁혀 확인합니다.
로그인은 되지만 특정 작업만 실패: Claude Code의 오류 내용과 v2rayN 로그의 같은 시간대 기록을 함께 비교합니다. 한 번의 성공만으로 모든 목적지에 대한 연결을 보장할 수는 없습니다.

문제를 재현할 때는 Claude Code를 실행한 터미널의 종류, v2rayN에서 선택한 노드, 오류가 발생한 시각을 기록하세요. 구독 주소, 인증 토큰, 계정 정보, 개인 서버 주소가 포함된 로그는 공개하지 마세요.

2. v2rayN 노드와 로컬 HTTP 포트 확인하기

먼저 v2rayN에서 사용할 노드를 활성 서버로 설정하고 코어가 실행 중인지 확인합니다. 노드 목록에 항목이 보이는 것과 실제로 연결되는 것은 별개입니다. 선택한 노드의 실제 연결 테스트를 실행하거나, v2rayN을 통해 열리는 웹페이지를 확인한 뒤 터미널 테스트를 진행하세요. 테스트가 실패하면 환경 변수 설정을 바꾸기 전에 노드와 코어 로그부터 확인하는 편이 효율적입니다.

활성 노드 선택

v2rayN에서 사용 가능한 노드를 선택하고 활성 서버로 설정합니다. 코어 실행 오류나 노드 연결 실패가 표시되지 않는지 로그를 확인하세요.
수신 포트 확인

「설정」→「매개변수 설정」에서 로컬 HTTP 또는 혼합 수신 포트를 확인합니다. 메뉴 이름과 포트는 버전에 따라 다를 수 있으므로 실제 화면의 값을 기준으로 합니다.
프록시 방식 구분

환경 변수에는 HTTP 프록시로 접속할 수 있는 수신점을 지정합니다. SOCKS 전용 포트인지 HTTP와 SOCKS를 함께 받는 혼합 포트인지 확인하고, HTTP 접속을 지원하지 않는 포트를 그대로 사용하지 마세요.
로컬 수신 확인

설정이 저장되고 코어가 실행된 뒤 지정한 주소와 포트에서 연결을 받을 수 있는지 확인합니다. 포트 변경 후에는 셸에 이미 입력한 값도 새 포트로 갱신해야 합니다.

환경 변수에 입력할 주소는 일반적으로 http://127.0.0.1:포트 형식입니다. 여기서 127.0.0.1은 Claude Code와 v2rayN이 같은 컴퓨터에서 실행될 때 사용하는 루프백 주소입니다. 예를 들어 화면에서 확인한 HTTP 포트가 10808이라면 주소 형식은 http://127.0.0.1:10808이지만, 10808을 모든 설치의 기본 포트라고 간주해서는 안 됩니다. 포트가 다르면 실제 값으로 바꾸세요.

v2rayN에서 확인할 항목

활성 서버: 실제로 사용할 노드
코어 상태: 실행 중이며 설정 오류가 없는지
수신 유형: HTTP 또는 HTTP 지원 혼합 포트
수신 주소: 같은 컴퓨터라면 보통 127.0.0.1

클라이언트 버전과 설정에 따라 메뉴 이름, 포트, 수신 유형이 다를 수 있습니다.

셸에 설정할 항목

HTTP_PROXY: 확인한 HTTP 프록시 주소
HTTPS_PROXY: 같은 HTTP 프록시 주소
주소 형식: http://127.0.0.1:포트
적용 범위: 변수를 설정한 셸과 그 자식 프로세스

HTTPS_PROXY 값이 https://로 시작해야 한다고 단정하지 마세요. 일반적인 HTTP 프록시는 HTTPS 목적지에 CONNECT 터널을 제공합니다.

3. Claude Code를 실행하는 셸에 프록시 설정하기

환경 변수는 Claude Code가 시작되기 전에 설정해야 합니다. 이미 열린 터미널에서 나중에 변수를 설정해도 기존 Claude Code 프로세스에 자동으로 전달되지는 않습니다. 새 터미널을 열거나 현재 실행을 종료한 뒤, 변수를 설정한 같은 터미널에서 Claude Code를 다시 시작하세요. v2rayN과 Claude Code가 서로 다른 컴퓨터에서 실행되는 경우에는 루프백 주소가 아니라 해당 컴퓨터에서 접근할 수 있는 프록시 주소를 사용해야 하며, LAN 공개 범위와 방화벽도 별도로 제한해야 합니다.

PowerShell에서 설정

PowerShell을 사용한다면 아래 명령에서 10808을 v2rayN 화면에 표시된 HTTP 수신 포트로 바꾸세요. 설정은 현재 PowerShell 창과 여기에서 실행하는 자식 프로그램에 적용됩니다. 이 창을 닫으면 현재 세션의 값은 사라집니다.

$proxy = "http://127.0.0.1:10808"
$env:HTTP_PROXY = $proxy
$env:HTTPS_PROXY = $proxy
$env:NO_PROXY = "localhost,127.0.0.1"
claude

claude 명령이 해당 환경에서 사용되지 않는다면 설치 방식에 맞는 Claude Code 실행 명령을 사용하세요. 환경 변수를 설정한 창과 실제 Claude Code를 실행하는 창이 다르면 값이 전달되지 않을 수 있습니다. 현재 적용된 값을 보려면 다음 명령을 실행합니다.

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

Bash 또는 Zsh에서 설정

Linux나 macOS의 Bash·Zsh에서는 다음과 같이 지정할 수 있습니다. 포트는 실제 v2rayN 설정에 맞춰 바꾸고, 명령을 실행한 동일한 셸에서 Claude Code를 시작하세요. 이 방식은 현재 셸 세션에만 적용됩니다.

export HTTP_PROXY="http://127.0.0.1:10808"
export HTTPS_PROXY="$HTTP_PROXY"
export NO_PROXY="localhost,127.0.0.1"
claude

매번 입력하지 않으려고 셸 설정 파일에 변수를 추가할 수도 있지만, 파일에 넣은 값은 새 터미널을 시작하거나 설정 파일을 다시 불러온 뒤 적용됩니다. 공용 계정이나 여러 사용자가 접근할 수 있는 환경에 프록시 인증 정보가 포함된 주소를 저장하지 마세요. 로그나 화면 공유에 환경 변수 전체가 노출되지 않도록 주의해야 합니다.

4. 터미널에서 프록시 연결과 실제 적용 여부 테스트하기

Claude Code를 다시 실행하기 전에 같은 셸에서 먼저 프록시 주소로 HTTPS 요청을 보내면 설정 오류를 더 쉽게 분리할 수 있습니다. curl이 설치되어 있다면 아래 예시를 사용하세요. 응답이 돌아오는 것은 해당 요청이 성공했다는 뜻이지, 모든 Claude Code 기능이나 모든 네트워크 목적지가 정상이라는 보장은 아닙니다.

curl -I --proxy "$HTTP_PROXY" https://example.com

PowerShell에서 환경 변수를 설정했다면 같은 방식으로 확인할 수 있습니다.

curl.exe -I --proxy $env:HTTP_PROXY https://example.com

테스트가 실패하면 오류 종류를 나눠 보세요. 연결 거부는 대개 주소·포트가 틀렸거나 해당 포트에서 수신하지 않는 경우입니다. 이름 확인 오류는 DNS나 네트워크 경로 문제일 수 있습니다. TLS 또는 원격 서버 오류는 프록시 연결 이후의 목적지 통신 문제일 수도 있습니다. curl과 Claude Code는 서로 다른 네트워크 라이브러리나 인증 흐름을 사용할 수 있으므로 curl 성공만으로 Claude Code의 프록시 적용을 확정하지 마세요.

판단 기준: 브라우저가 아니라 같은 셸에서 확인하세요

브라우저에서 접속되는지만 확인하지 말고, 환경 변수를 설정한 터미널에서 curl을 실행한 뒤 그 터미널에서 Claude Code를 시작하세요. 두 테스트가 같은 프록시 주소와 포트를 사용하도록 맞추면 문제 범위를 v2rayN 수신, 셸 설정, Claude Code 실행 단계로 나누기 쉽습니다.

Claude Code가 로그인이나 요청 중 실패하면 오류 시각과 v2rayN 로그를 대조하세요. 같은 시각에 코어가 종료되거나 원격 연결 오류가 반복되는지 확인합니다. 프록시를 거치지 않는 직접 연결과 프록시 경유 연결을 무작정 번갈아 시도하기보다, 한 번에 변수 하나만 바꾸고 결과를 기록해야 원인을 찾기 쉽습니다. 회사나 기관 네트워크에서 관리 정책을 사용하는 경우에는 프록시 사용이 허용되는지 관리자에게 확인하세요.

5. 로그인 실패와 요청 시간 초과 점검하기

오류 메시지는 원인을 확정하는 진단 결과라기보다 조사 방향을 정하는 단서입니다. 아래 항목을 위에서부터 확인하고, 각 단계가 끝난 뒤 같은 요청을 다시 시도하세요. 여러 설정을 한꺼번에 변경하면 어떤 조치가 영향을 줬는지 알기 어렵습니다.

연결 거부 또는 로컬 프록시 연결 실패: v2rayN 코어가 실행 중인지, 선택한 HTTP 수신 포트가 맞는지, 환경 변수의 주소에 오타가 없는지 확인합니다. 프록시 주소 앞의 http://와 포트 앞의 콜론도 점검하세요.
요청 시간 초과: 먼저 v2rayN에서 활성 노드의 연결 상태와 같은 시간대의 로그를 확인합니다. 노드를 바꿔 재시험할 때는 같은 터미널 변수와 같은 요청을 유지해 비교하세요. 대상 서비스가 해당 네트워크에서 접근 가능한지도 별도로 확인해야 합니다.
브라우저는 되지만 터미널만 실패: Claude Code가 실행되는 셸에서 HTTP_PROXY와 HTTPS_PROXY를 조회합니다. 다른 터미널, IDE 내장 터미널, 작업 자동화 환경은 별도의 환경을 가질 수 있습니다.
인증이나 로그인 과정에서 실패: 변수 설정 오류와 계정 인증 오류를 구분합니다. 시스템 시각이 맞는지, 네트워크 연결이 안정적인지, 로그인 오류가 재현되는지 확인하세요. 액세스 토큰이나 인증 헤더를 로그와 함께 공유하지 마세요.
일부 요청만 실패: v2rayN 라우팅 규칙, DNS 설정, 목적지별 연결 가능성을 확인합니다. 프록시가 모든 도메인에 동일하게 적용된다고 가정하지 말고, 클라이언트 로그에서 해당 요청이 직접 연결 또는 프록시 연결 중 어느 경로로 처리되었는지 살펴보세요.

환경 변수에 HTTPS_PROXY를 설정했는데도 작동하지 않는다면, 값을 임의로 https://로 바꾸기 전에 v2rayN 수신 포트가 HTTP 프록시인지 확인하세요. 변수 이름의 HTTPS는 보통 HTTPS 목적지 요청에 사용할 프록시를 가리키며, 프록시 서버 자체가 TLS로 감싸져 있다는 뜻은 아닙니다. 환경에 따라 소문자 변수인 http_proxy나 https_proxy를 참조하는 도구도 있으므로, 사용 중인 실행 환경에서 대소문자 처리 차이가 의심될 때만 소문자 변수도 같은 값으로 설정해 비교합니다.

6. 자주 묻는 질문

시스템 프록시를 켰는데 Claude Code는 왜 연결되지 않나요?

시스템 프록시 설정이 모든 명령줄 프로그램에 전달되는 것은 아닙니다. Claude Code를 실행할 PowerShell이나 셸에서 HTTP_PROXY와 HTTPS_PROXY를 설정한 다음, 같은 창에서 Claude Code를 다시 시작하세요.

환경 변수에는 어떤 v2rayN 포트를 넣어야 하나요?

「설정」→「매개변수 설정」에서 실제 HTTP 또는 HTTP 지원 혼합 수신 포트를 확인하세요. SOCKS 전용 포트를 임의로 지정하지 말고, 현재 포트에 맞춰 http://127.0.0.1:포트 형식으로 입력합니다.

curl은 성공하는데 Claude Code 로그인은 실패합니다. 무엇을 확인하나요?

curl과 Claude Code가 같은 셸에서 실행됐는지, Claude Code가 같은 프록시 변수를 받았는지 확인하세요. 이어서 v2rayN 로그의 실패 시각, 노드 연결, 시스템 시각과 인증 단계의 오류를 비교합니다. 인증 정보를 로그에 복사하지 마세요.

터미널을 다시 열면 프록시 설정이 사라지는 이유는 무엇인가요?

PowerShell의 $env: 설정과 Bash·Zsh의 export는 일반적으로 현재 세션에 적용됩니다. 매번 설정하려면 셸 시작 설정 파일을 사용할 수 있지만, 프록시 인증 정보가 포함된 값은 파일 권한과 공유 범위를 확인해 안전하게 보관하세요.

마지막으로 v2rayN의 활성 노드와 코어 상태, HTTP 수신 포트, Claude Code를 시작한 셸의 환경 변수, 같은 셸에서 실행한 연결 테스트 결과를 함께 기록해 두면 재발 시 비교가 쉽습니다. 설정을 원래대로 돌릴 때는 세션 환경 변수만 지우거나 셸 설정 파일에서 추가한 줄을 제거하세요. 필요한 항목을 다시 확인하려면 사용 가이드 보기 또는 다운로드 센터를 이용할 수 있습니다。