Gemini CLI 연결 안 됨? v2rayN 터미널 프록시 설정법

Gemini CLI가 v2rayN을 자동으로 사용하지 않는 이유

v2rayN이 실행 중이라는 사실과 Gemini CLI가 프록시를 사용한다는 사실은 서로 다릅니다. v2rayN은 로컬 컴퓨터에 HTTP 또는 SOCKS 프록시 포트를 열고, 시스템 프록시를 변경하거나 TUN 가상 네트워크 인터페이스를 통해 트래픽을 넘길 수 있습니다. 반면 터미널에서 실행되는 Gemini CLI는 운영체제의 시스템 프록시 설정을 항상 읽는다고 보장할 수 없습니다. 사용하는 런타임, 라이브러리, 셸 환경에 따라 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 같은 환경 변수를 별도로 확인해야 합니다.

특히 브라우저에서 같은 계정 페이지가 정상적으로 열리는데 CLI의 API 요청만 실패한다면 노드 자체보다 프록시 전달 방식이 원인일 가능성이 큽니다. 브라우저는 v2rayN의 시스템 프록시 설정을 따라가지만, CLI 프로세스는 직접 연결을 시도할 수 있기 때문입니다. 먼저 v2rayN의 메인 화면에서 실제 활성 노드를 선택하고, 코어가 실행 중인지 확인한 뒤 로컬 포트 번호를 기록하세요. 일반적인 예시로 HTTP와 SOCKS를 함께 처리하는 혼합 포트가 10808 또는 10809일 수 있지만, 설치 환경과 설정에 따라 달라집니다.

• v2rayN: 노드와 Xray 코어를 실행하고 로컬 프록시 또는 TUN 진입점을 제공합니다.
• 터미널 셸: 현재 창에서 실행되는 프로그램에 프록시 주소와 포트를 전달해야 합니다.
• Gemini CLI: 인증, API 요청, DNS 확인, TLS 연결을 모두 별도로 수행하므로 브라우저와 결과가 다를 수 있습니다.
• 운영체제: Windows PowerShell, 명령 프롬프트, macOS·Linux 셸마다 환경 변수 설정 문법이 다릅니다.

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

환경 변수보다 먼저 v2rayN 쪽의 기본 연결을 확인해야 합니다. 메인 화면에서 노드 하나를 선택하고 실제 연결 지연 테스트를 실행하세요. ICMP ping이 낮게 표시되어도 TLS, VLESS 또는 VMess 핸드셰이크와 프록시 출구 연결이 성공한다는 뜻은 아닙니다. 브라우저나 다른 HTTP 도구로 같은 노드를 사용해 HTTPS 사이트에 접속할 수 있는지 확인하면 노드 문제와 CLI 문제를 나누는 데 도움이 됩니다.

v2rayN의 「설정」→「매개변수 설정」에서 로컬 프록시 관련 항목을 찾습니다. 버전에 따라 메뉴 이름이나 표시 순서는 조금 다를 수 있지만, HTTP 포트, SOCKS 포트, 혼합 포트 또는 로컬 수신 포트가 표시됩니다. 예를 들어 혼합 포트가 10808이면 HTTP 프록시 주소는 http://127.0.0.1:10808로 지정할 수 있습니다. SOCKS 전용 포트만 있다면 socks5://127.0.0.1:포트 형식을 사용해야 하며, HTTP 프록시 변수에 SOCKS 주소를 무작정 넣으면 라이브러리가 연결하지 못할 수 있습니다.

1. 활성 노드 선택

   v2rayN 메인 화면에서 사용할 노드를 선택하고 활성 서버로 지정합니다. 만료되었거나 지연 테스트에 실패한 노드는 CLI 점검에서 제외하세요.

2. 코어 상태 확인

   하단 상태 표시와 로그에서 Xray 코어가 실행 중인지 확인합니다. 일반적인 VLESS, VMess, Trojan 노드는 구독이 지정한 코어 유형과 실제 설정이 일치해야 합니다.

3. 포트 기록

   「설정」→「매개변수 설정」에서 HTTP, SOCKS 또는 혼합 포트를 기록합니다. 이 글의 10808은 예시이며 실제 값으로 바꿔야 합니다.

4. 브라우저 비교

   시스템 프록시를 활성화한 뒤 HTTPS 페이지를 열어 봅니다. 브라우저도 실패하면 환경 변수보다 노드, DNS, 라우팅을 먼저 점검합니다.

환경 변수로 Gemini CLI에 프록시 전달하기

가장 먼저 시도할 방법은 현재 터미널 세션에 프록시 환경 변수를 설정하는 것입니다. 보통 HTTPS API 요청에는 HTTPS_PROXY를 사용하고, 일부 의존성이나 인증 요청까지 포괄하려면 HTTP_PROXY와 ALL_PROXY를 함께 지정합니다. 변수 이름은 대문자와 소문자를 모두 확인하는 프로그램이 있으므로 호환성을 위해 두 형태를 함께 설정할 수 있습니다. 단, 사용 중인 CLI 버전이나 네트워크 라이브러리가 특정 변수를 지원하는지는 실제 로그로 확인해야 합니다.

# Windows PowerShell
$env:HTTP_PROXY = "http://127.0.0.1:10808"
$env:HTTPS_PROXY = "http://127.0.0.1:10808"
$env:ALL_PROXY = "http://127.0.0.1:10808"
$env:NO_PROXY = "localhost,127.0.0.1"
gemini

PowerShell에서 $env:로 지정한 값은 현재 창과 그 창에서 실행한 자식 프로세스에 적용됩니다. 새 PowerShell을 열면 사라지므로, 일회성 테스트에는 이 방식이 안전합니다. 저장형 설정이 필요하면 사용자 환경 변수로 등록할 수 있지만, 먼저 임시 세션에서 연결을 확인하는 편이 좋습니다. 기존에 잘못된 프록시 값이 등록되어 있다면 Remove-Item Env:HTTP_PROXY처럼 삭제한 뒤 다시 지정하세요.

# Windows 명령 프롬프트
set HTTP_PROXY=http://127.0.0.1:10808
set HTTPS_PROXY=http://127.0.0.1:10808
set ALL_PROXY=http://127.0.0.1:10808
set NO_PROXY=localhost,127.0.0.1
gemini

# macOS 또는 Linux 셸
export http_proxy="http://127.0.0.1:10808"
export https_proxy="http://127.0.0.1:10808"
export HTTP_PROXY="http://127.0.0.1:10808"
export HTTPS_PROXY="http://127.0.0.1:10808"
export ALL_PROXY="http://127.0.0.1:10808"
export NO_PROXY="localhost,127.0.0.1"
gemini

프록시가 적용되었는지 확인하려면 같은 터미널에서 환경 변수 값을 출력합니다. PowerShell에서는 Get-ChildItem Env:HTTP_PROXY, macOS·Linux에서는 printenv HTTPS_PROXY를 사용할 수 있습니다. 값이 비어 있거나 다른 포트를 가리키면 Gemini CLI를 다시 실행해도 결과는 바뀌지 않습니다. 회사 네트워크나 별도 보안 도구가 이미 프록시 변수를 주입하고 있다면, 새 값이 실제로 덮어써졌는지도 확인하세요.

DNS와 라우팅 문제를 프록시 전달 문제와 분리하기

환경 변수를 정확히 넣었는데도 ENOTFOUND, getaddrinfo, ECONNRESET 같은 오류가 계속되면 DNS와 라우팅을 점검해야 합니다. CLI가 도메인 이름을 직접 해석하는지, 프록시가 원격에서 해석하는지는 프록시 종류와 라이브러리 구현에 따라 달라집니다. 로컬 DNS가 특정 API 도메인을 해석하지 못하면 브라우저는 우회 DNS를 사용하면서 CLI만 실패하는 상황도 생길 수 있습니다.

v2rayN에서 「설정」→「DNS 설정」을 열어 현재 모드와 서버 주소를 확인합니다. 처음부터 복잡한 규칙을 많이 추가하기보다는 기본 모드로 되돌린 뒤 재현 여부를 확인하세요. 「라우팅 설정」에서는 현재 모드가 전역 프록시인지, 규칙 모드인지, 직접 연결 우선인지 살펴봅니다. API 도메인이 규칙에 의해 DIRECT로 처리되면 브라우저와 CLI가 서로 다른 경로를 사용하게 됩니다.

• 도메인 해석 실패라면 DNS 서버, DNS 모드, 로컬 보안 프로그램의 차단 기록을 확인합니다.
• 연결 시간이 지나서 실패한다면 활성 노드의 출구 회선과 원격 API 경로를 다른 노드와 비교합니다.
• 즉시 연결이 거부되면 로컬 포트가 열려 있는지, 다른 프로그램이 해당 포트를 점유하지 않았는지 확인합니다.
• 특정 명령만 실패하면 인증 토큰, CLI 버전, 요청 대상 도메인과 셸에 남은 오래된 변수를 함께 점검합니다.

로그와 오류 메시지로 원인 좁히기

오류 문구를 모두 같은 네트워크 장애로 해석하지 마세요. v2rayN 로그에는 코어가 로컬 포트에서 수신 대기하는지, DNS 요청이 실패하는지, TLS 핸드셰이크가 중단되는지에 대한 단서가 남을 수 있습니다. Gemini CLI의 출력에는 인증 실패와 네트워크 실패가 함께 표시될 수 있으므로, 오류가 발생한 시각과 선택한 노드, 사용한 포트, 실행한 환경 변수를 기록하면 재현이 쉬워집니다.

PowerShell에서 curl 동작을 확인할 때는 명령이 실제 curl이 아니라 별칭으로 처리될 수 있으므로 curl.exe를 명시하는 편이 안전합니다. 예를 들어 로컬 HTTP 프록시가 10808일 때 다음처럼 실행할 수 있습니다.

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

이 테스트가 성공하면 로컬 포트와 기본 HTTPS 프록시 경로는 동작하는 것입니다. 테스트가 실패하면 Gemini CLI를 반복 실행해도 같은 결과가 나올 가능성이 높습니다. 반대로 curl은 성공하지만 CLI만 실패한다면 변수 이름 인식, CLI 런타임의 프록시 지원, 인증 단계 또는 CLI 자체 설정을 집중적으로 확인하세요.

Tun 모드로 전환할 때의 조건과 주의점

환경 변수를 설정해도 Gemini CLI가 계속 직접 연결을 시도한다면 v2rayN의 Tun 모드를 대안으로 사용할 수 있습니다. Tun 모드는 애플리케이션이 프록시 변수를 읽는지에 의존하지 않고, 운영체제의 네트워크 트래픽을 가상 인터페이스에서 받아 라우팅합니다. 따라서 프록시를 지원하지 않는 터미널 도구나 별도 런타임을 사용하는 프로그램에도 적용 범위가 넓습니다.

다만 Tun 모드는 단순한 버튼 하나로 끝나는 기능이 아닙니다. Windows에서는 관리자 권한, 가상 네트워크 드라이버, 방화벽 허용이 필요할 수 있습니다. DNS를 가상 인터페이스에서 처리할지, 시스템 DNS를 사용할지에 따라 도메인 해석 결과가 달라질 수 있습니다. 기존 VPN, 다른 네트워크 필터, 가상 머신 네트워크가 함께 실행 중이면 라우팅 우선순위가 충돌할 수 있으므로 처음에는 다른 터널 프로그램을 종료하고 테스트하세요.

1. v2rayN에서 현재 설정과 노드 정보를 백업하고, 먼저 환경 변수 방식이 실패했는지 확인합니다.
2. 「설정」→「Tun 모드」 또는 버전에 해당하는 네트워크 설정을 열고 가상 인터페이스 사용을 활성화합니다.
3. 관리자 권한 요청과 네트워크 드라이버 설치 안내가 나타나면 내용을 확인한 뒤 승인합니다.
4. 라우팅은 처음에 전역 또는 명확한 프록시 우선 모드로 두고 Gemini CLI 명령을 한 번만 실행합니다.
5. 연결이 확인된 뒤 필요한 도메인만 프록시로 보내도록 규칙 모드와 DNS 정책을 세분화합니다.

재발을 막는 최종 점검 순서

문제가 해결된 뒤에는 어떤 변경이 효과가 있었는지 정리해야 다음 업데이트나 노드 교체 때 같은 작업을 반복하지 않습니다. 가장 안정적인 구성은 v2rayN의 노드와 코어 버전, 로컬 포트, Gemini CLI 실행 방식, 셸 환경 변수를 짧은 메모로 남기는 것입니다. 예를 들어 Windows 11 24H2, v2rayN 7.x, Xray-core 25.x, 혼합 포트 10808, PowerShell의 HTTPS_PROXY 사용처럼 기록하면 재현 조건이 분명해집니다.

• v2rayN에서 활성 노드가 실제 연결 테스트를 통과했는지 확인합니다.
• HTTP, SOCKS, 혼합 포트 중 어떤 포트를 사용했는지 기록하고 원격 443 포트와 구분합니다.
• 새 터미널에서 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 값을 출력해 오타를 확인합니다.
• NO_PROXY에는 localhost,127.0.0.1만 우선 넣고, API 도메인을 실수로 직접 연결 목록에 추가하지 않습니다.
• curl과 Gemini CLI를 같은 터미널에서 비교해 로컬 프록시 문제와 CLI 자체 문제를 분리합니다.
• Tun 모드를 사용할 때는 환경 변수 프록시를 끄고 DNS 및 라우팅 결과를 다시 확인합니다.
• 인증 오류가 발생하면 네트워크 설정을 계속 변경하지 말고 CLI 계정 인증과 권한을 점검합니다.