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

Claude Code가 터미널에서 로그인되지 않거나 요청 시간이 초과될 때는 노드부터 바꾸기보다, 터미널이 v2rayN의 로컬 프록시에 연결하는지 먼저 확인하는 편이 좋습니다. v2rayN에서 노드가 선택되어 있어도 터미널 프로그램이 자동으로 프록시를 사용하는 것은 아닙니다. 이 글은 Windows 터미널을 중심으로 로컬 포트, 셸 환경 변수, 라우팅과 로그인 문제를 단계별로 점검하는 방법을 설명합니다.

이 글 빠르게 보기

터미널 앱은 브라우저와 프록시 설정을 공유하지 않을 수 있습니다. v2rayN에서 실제 HTTP 프록시 포트를 확인하고, Claude Code를 실행하는 셸에 HTTPS_PROXY와 HTTP_PROXY를 지정한 뒤 요청 경로를 시험하세요. 오류가 계속되면 로컬 포트, 프록시 노드, 도메인 라우팅, 계정 인증 순서로 범위를 좁힙니다. 프록시를 설정했는데 로그인만 실패하거나 시간 초과가 반복되는 상황을 점검하려는 사용자에게 적합합니다.

터미널 프록시와 시스템 프록시 구분하기

v2rayN은 노드 설정을 관리하고 로컬 프록시를 제공하는 클라이언트입니다. Claude Code는 터미널에서 실행되는 별도의 프로그램이므로, Windows의 시스템 프록시를 켰다고 해서 항상 해당 로컬 프록시를 이용하는 것은 아닙니다. 특히 브라우저에서는 페이지가 열리지만 터미널 요청은 시간 초과되는 경우, 시스템 프록시와 터미널의 프록시 설정이 서로 다를 수 있습니다.

먼저 v2rayN에서 노드를 선택하고 코어가 실행 중인지 확인하세요. 이어서 설정 화면에서 로컬 프록시의 HTTP 수신 주소와 포트를 확인합니다. 일부 설치에서는 SOCKS 포트가 10808, HTTP 포트가 10809인 경우가 있지만, 이 값은 예시일 뿐입니다. 설정이 다르면 실제 화면에 표시된 값을 사용해야 합니다. SOCKS 포트에 HTTP 프록시 주소를 지정하면 연결이 거부되거나 프로토콜 오류가 날 수 있습니다.

127.0.0.1

보통 로컬 프록시가 수신하는 주소입니다. 실제 바인딩 주소를 확인하세요.

10809

HTTP 포트 예시이며, 사용 중인 v2rayN 설정과 다를 수 있습니다.

2개 변수

HTTP_PROXY와 HTTPS_PROXY를 우선 확인합니다.

노드 선택: v2rayN에서 사용할 서버 구성을 활성화합니다. 목록에서 항목을 선택한 것과 실제 활성 서버로 설정한 것은 다를 수 있으므로 상태를 확인하세요.
로컬 프록시: 터미널이 접속할 주소와 포트입니다. 원격 서버의 주소나 포트와 혼동하지 마세요.
셸 변수: Claude Code를 실행하는 터미널 프로세스가 읽는 프록시 설정입니다. 새 터미널 창을 열면 기존 창에서 설정한 임시 값은 이어지지 않을 수 있습니다.

셸에 HTTP 프록시 환경 변수 설정하기

아래 예시는 v2rayN의 HTTP 프록시가 127.0.0.1:10809에서 동작한다고 가정합니다. 먼저 v2rayN에서 이 주소와 포트를 확인하고, 값이 다르면 명령의 포트를 바꾸세요. 프록시 주소에는 로컬 HTTP 수신 포트를 넣어야 합니다. 노드의 서버 주소를 넣는 설정이 아닙니다.

PowerShell에서는 현재 창에서만 적용되는 환경 변수를 다음과 같이 지정할 수 있습니다. Claude Code도 같은 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의 셸에서는 다음 형식을 사용할 수 있습니다. v2rayN이 아닌 다른 클라이언트를 사용한다면 그 클라이언트가 제공하는 로컬 HTTP 프록시 주소와 포트로 바꿔야 합니다.

export HTTP_PROXY="http://127.0.0.1:10809"
export HTTPS_PROXY="http://127.0.0.1:10809"
claude

현재 창에서만 설정

적용 범위: 현재 셸과 그 셸에서 시작한 프로그램
변수: HTTP_PROXY, HTTPS_PROXY
장점: 시험 후 창을 닫으면 설정이 사라짐

처음 연결을 확인하거나 오류 원인을 분리할 때 권장합니다.

셸 프로필에 저장

적용 범위: 프로필을 불러오는 새 셸
변수: 동일한 프록시 변수
주의: 포트 변경 후 프로필도 수정해야 함

한 번의 시험에서 정상 동작을 확인한 뒤 필요할 때만 저장하세요.

환경 변수 이름의 대소문자 처리 방식은 프로그램과 라이브러리에 따라 다를 수 있습니다. 먼저 위와 같이 일반적으로 사용하는 대문자 이름을 설정하고, Claude Code의 현재 버전 안내와 셸에서 실제로 값이 설정됐는지 확인하세요. 인증 정보나 구독 주소를 변수에 추가할 필요는 없습니다. 프록시를 사용하지 않을 대상으로 NO_PROXY를 지정했다면, 대상 도메인이 예외 목록에 포함되어 프록시를 우회하지 않는지도 점검하세요.

Claude Code 실행 전 프록시 경로 시험하기

Claude Code를 재설치하거나 로그인 정보를 지우기 전에 로컬 프록시가 실제 요청을 전달하는지 확인하세요. PowerShell에서 curl이 별칭으로 동작할 수 있으므로, 아래 예시는 Windows에 포함된 실행 파일을 명시해 curl.exe를 사용합니다.

curl.exe -I --proxy http://127.0.0.1:10809 https://api.anthropic.com

주소나 포트가 다르면 명령의 프록시 주소를 수정하세요. 이 시험에서 응답 코드가 401, 404 또는 405로 표시될 수 있습니다. 이는 해당 요청 경로에서 서버 응답을 받았다는 뜻일 수 있으며, 계정 로그인이나 Claude Code 사용 권한까지 확인한 결과는 아닙니다. 반대로 연결 거부나 시간 초과가 발생하면 인증보다 먼저 로컬 프록시와 네트워크 경로를 확인해야 합니다.

노드 활성화

v2rayN에서 사용할 노드를 활성화하고 코어가 실행 중인지 확인하세요. 코어 로그에 로컬 포트 바인딩 실패가 보이면 먼저 해당 오류를 해결합니다.
포트 확인

설정 화면에서 HTTP 프록시 수신 주소와 포트를 확인하세요. SOCKS 포트와 HTTP 포트를 구분하고, 이 글의 예시 포트와 다르면 명령과 환경 변수를 모두 수정합니다.
요청 시험

curl.exe 명령으로 프록시를 명시해 요청합니다. 응답을 받으면 터미널에서 프록시를 거쳐 대상 서버까지 도달하는 기본 경로가 확인된 것입니다.
같은 창에서 실행

시험에 사용한 셸에서 환경 변수를 설정하고 Claude Code를 실행하세요. 다른 터미널 창이나 시작 메뉴에서 실행하면 해당 변수 없이 시작될 수 있습니다.
기본값 복구

시험이 끝난 뒤 임시 설정을 해제하려면 PowerShell에서 Remove-Item Env:HTTP_PROXY와 Remove-Item Env:HTTPS_PROXY를 실행하세요. CMD에서는 각각 set HTTP_PROXY=, set HTTPS_PROXY=를 사용합니다.

시간 초과와 라우팅 문제 좁히기

프록시를 지정했는데 요청이 계속 멈춘다면, 실패가 발생한 위치를 나눠 보세요. 로컬 연결이 즉시 거부되는 경우는 대체로 주소나 포트가 틀렸거나 해당 포트에서 수신하지 않는 상황입니다. 요청이 오래 기다린 뒤 시간 초과되면 노드의 원격 연결, DNS, 라우팅 규칙 또는 네트워크 차단 등 여러 원인이 가능합니다. 오류 문구만 보고 원인을 하나로 단정하지 말고, v2rayN 로그와 터미널 결과를 같은 시각 기준으로 비교하세요.

오류: connect ECONNREFUSED 127.0.0.1:10809

원인과 해결: 로컬 주소와 포트에 연결할 수 없습니다. v2rayN이 실행 중인지, 실제 HTTP 포트가 10809인지, 포트가 다른 프로그램에 의해 점유되었는지 확인하세요. 포트를 바꾸었다면 환경 변수에도 같은 값을 사용해야 합니다.

오류: ETIMEDOUT 또는 요청 시간 초과

원인과 해결: 연결 과정에서 응답이 오지 않았다는 의미이며, 원격 서버나 라우팅 문제일 수 있습니다. 먼저 위의 명시적 프록시 요청을 시험하고, 실패하면 활성 노드와 v2rayN 로그를 확인하세요. 프록시 시험은 성공하지만 Claude Code만 실패하면 셸 변수와 프로그램 버전별 프록시 지원을 점검합니다.

오류: 인증 또는 로그인 페이지로 돌아감

원인과 해결: HTTPS 연결이 일부 된다고 해서 로그인 절차 전체가 완료된 것은 아닙니다. 브라우저와 터미널이 서로 다른 프록시를 사용할 수 있으므로, 브라우저에서 열린 인증 페이지와 Claude Code를 시작한 셸의 경로를 각각 확인하세요. 조직 네트워크의 로그인 정책이나 계정 상태도 점검 대상입니다.

노드와 경로 비교: v2rayN의 같은 노드로 브라우저는 되지만 터미널만 실패한다면, 터미널 환경 변수 또는 프로그램의 프록시 처리 방식을 우선 확인하세요.
라우팅 규칙 확인: 목적지 도메인이 직접 연결 규칙에 걸리면 로컬 프록시를 거쳐도 해당 요청이 서버로 전달되지 않을 수 있습니다. 로그에서 실제 접속 도메인과 선택된 outbound를 확인하고, 필요한 경우 해당 도메인에 적용되는 규칙을 검토하세요.
규칙을 과도하게 넓히지 않기: 모든 트래픽을 무조건 프록시로 보내는 설정은 다른 앱의 연결까지 바꿀 수 있습니다. 먼저 실제 로그에 나타난 목적지를 기준으로 제한된 규칙을 시험하고, 변경 전의 설정을 기록해 두세요.
DNS와 시간 확인: 도메인 조회 실패가 로그에 나타나는지 살펴보고, 시스템 시간이 크게 어긋나 있지 않은지도 확인하세요. 인증서 검증이나 로그인 과정은 시간 설정의 영향을 받을 수 있습니다.

Claude Code의 로그인은 터미널 요청뿐 아니라 브라우저 인증과 계정 상태에도 영향을 받을 수 있습니다. 브라우저가 열리지 않는 경우와 브라우저에서 인증을 마친 뒤 터미널이 완료 상태를 받지 못하는 경우는 점검 지점이 다릅니다. 먼저 화면에 표시된 오류와 실패 시각을 기록하고, 민감한 인증 코드나 토큰은 공유하지 마세요.

브라우저가 열리지 않음: 기본 브라우저 실행 여부와 인증 페이지가 로드되는지 확인하세요. 터미널의 프록시 변수는 브라우저에 자동 적용되지 않을 수 있으므로, 브라우저의 네트워크 설정도 따로 확인해야 합니다.
인증 후 터미널이 대기함: Claude Code를 실행한 동일한 셸에서 환경 변수가 유지되는지 확인하고, 인증이 완료된 뒤 터미널에 돌아와 안내가 갱신되는지 살펴보세요. 다른 창에서 시작한 세션을 보고 있지 않은지도 확인합니다.
권한 또는 계정 오류: 프록시 연결이 성공했더라도 계정에 필요한 접근 권한이 없거나 인증 상태가 만료되었을 수 있습니다. 계정에 맞는 로그인 방식을 확인하고, 조직 계정이라면 관리자 정책을 확인하세요.
명령을 찾을 수 없음: 이는 네트워크 연결과 별개로 실행 파일이나 PATH 설정 문제일 수 있습니다. Claude Code가 설치된 셸에서 claude --version을 실행해 명령을 찾을 수 있는지 먼저 확인하세요.
설정을 바꾼 뒤에도 이전 증상이 남음: 실행 중인 Claude Code를 종료하고, 환경 변수를 설정한 새 셸에서 다시 시작하세요. 오래된 프로세스는 새 셸의 값을 자동으로 받지 않습니다.

브라우저는 되는데 Claude Code만 실패해요. 왜 그런가요?

브라우저가 시스템 프록시를 쓰더라도 터미널은 별도 설정이 필요할 수 있습니다. v2rayN의 HTTP 포트를 확인하고, Claude Code를 실행하는 셸에 HTTP_PROXY와 HTTPS_PROXY를 설정한 뒤 같은 창에서 실행하세요.

SOCKS 포트인 10808을 변수에 넣어도 되나요?

이 글의 환경 변수 예시는 HTTP 프록시 주소를 사용합니다. 10808이 SOCKS 포트라면 HTTP 포트와 혼동하지 마세요. 클라이언트가 제공하는 HTTP 수신 포트를 사용하거나, 사용하는 프로그램의 문서에서 SOCKS 프록시 지원 방식을 확인하세요.

HTTP 요청이 401로 끝나면 프록시 설정이 틀린 건가요?

반드시 그렇지는 않습니다. 대상 서버에서 HTTP 응답을 받았다는 의미일 수 있지만, 로그인과 계정 접근까지 확인한 결과는 아닙니다. 요청 경로 확인과 Claude Code 인증 상태 확인을 별도로 진행하세요.

매번 환경 변수를 입력하지 않으려면 어떻게 하나요?

임시 설정으로 연결을 먼저 검증한 뒤 필요한 경우 사용하는 셸의 프로필에 값을 저장하세요. 로컬 포트를 변경하면 프로필의 변수도 수정하고, 공용 컴퓨터에서는 다른 사용자가 접근할 수 있는 전역 설정을 피하는 편이 안전합니다.