Gemini CLI v2rayN 설정법｜중국에서 안정적으로 접속하기

Gemini CLI는 터미널에서 자연어로 코드를 분석하고, 프로젝트 파일을 읽고, 명령 실행 계획을 세울 수 있는 개발자용 도구입니다. 그러나 중국 본토 네트워크에서 실행할 때는 웹브라우저만 프록시를 사용하는 상태로는 충분하지 않을 수 있습니다. v2rayN이 정상적으로 실행 중이어도 터미널 프로세스가 로컬 프록시 주소를 모르면 설치 요청, 로그인 페이지, API 호출이 각각 직접 연결을 시도하기 때문입니다.

이 글에서는 Windows의 v2rayN을 중심으로 Gemini CLI를 준비하는 순서를 설명합니다. 구독을 추가하고 Xray 코어와 노드를 활성화한 뒤, v2rayN의 로컬 HTTP 또는 SOCKS 포트를 확인하고, PowerShell이나 다른 터미널 세션에 프록시 변수를 적용합니다. 이후 설치, 인증, 간단한 요청 테스트를 단계별로 실행하면서 로그인 실패와 시간 초과를 서로 다른 문제로 구분하는 방법까지 살펴봅니다. macOS와 Linux에서도 같은 원리로 환경 변수를 설정할 수 있도록 명령 예시를 함께 제공합니다.

Gemini CLI가 v2rayN을 사용하는 방식

Gemini CLI와 v2rayN은 서로 다른 역할을 담당합니다. v2rayN은 Xray 또는 선택한 코어를 실행하고 로컬 컴퓨터에 HTTP, SOCKS 또는 TUN 방식의 진입점을 제공합니다. Gemini CLI는 이 진입점의 주소를 자동으로 알아내는 프로그램이 아니라, 운영체제의 환경 변수나 자체 설정을 통해 프록시를 전달받는 터미널 애플리케이션입니다. 따라서 v2rayN 창에 연결 상태가 표시된다는 사실만으로 Gemini CLI의 통신도 자동으로 프록시를 통과한다고 판단해서는 안 됩니다.

Windows에서 v2rayN의 로컬 포트는 설치 버전, 모드와 사용자가 수정한 설정에 따라 달라질 수 있습니다. 많은 환경에서 HTTP 포트는 127.0.0.1:10809, SOCKS 포트는 127.0.0.1:10808로 보이지만, 반드시 자신의 화면에서 실제 값을 확인해야 합니다. v2rayN의 「설정」 또는 「参数设置」에 해당하는 로컬 프록시 항목에서 HTTP 포트와 SOCKS 포트를 확인하고, 다른 프로그램이 사용하는 포트와 충돌하지 않는지도 살펴보세요.

프록시 종류도 구분해야 합니다. HTTP_PROXY와 HTTPS_PROXY에는 일반적으로 HTTP 프록시 URL을 넣습니다. 반면 ALL_PROXY에는 SOCKS5 URL을 사용할 수 있지만, 모든 CLI와 런타임이 이 변수를 같은 방식으로 처리하는 것은 아닙니다. 먼저 HTTP 포트를 사용해 단순한 연결을 확인하고, 필요한 경우에만 SOCKS5 설정을 추가하는 편이 문제 범위를 줄이기 쉽습니다.

v2rayN에서 구독과 노드를 먼저 준비하기

Gemini CLI 설정을 시작하기 전에 v2rayN 자체에서 웹 요청을 처리할 수 있는 노드를 준비해야 합니다. 구독 링크를 추가할 때는 출처가 분명하고 현재 사용 권한이 유효한 주소를 사용하세요. 구독 주소를 공개 문서, 명령 기록 또는 화면 공유에 그대로 붙여 넣으면 인증 정보가 노출될 수 있습니다. 구독 업데이트가 성공했더라도 모든 노드가 작동한다는 의미는 아니므로, 업데이트 후 실제로 사용할 노드를 선택하고 활성화해야 합니다.

1. 구독 추가

   v2rayN 메인 화면의 「订阅分组」 영역에서 새 그룹을 만들고 구독 URL을 입력합니다. 저장 후 업데이트 결과에 노드 수와 갱신 시간이 표시되는지 확인하세요.

2. 노드 선택

   업데이트된 그룹에서 노드를 선택하고 「활성 서버로 설정」에 해당하는 명령을 실행합니다. 단순히 행을 클릭하는 것과 실제 활성 서버로 지정하는 것은 다를 수 있습니다.

3. 코어 실행

   Xray 또는 선택한 코어를 시작하고 로그에 인바운드 포트가 열렸다는 내용과 치명적인 오류가 없는지 확인합니다. 프로토콜, TLS, SNI, flow가 서버 설정과 일치해야 합니다.

4. 포트 확인

   v2rayN의 로컬 프록시 설정에서 HTTP와 SOCKS 포트를 기록합니다. 이 글의 명령에서 10809와 10808을 그대로 사용하지 말고 자신의 값으로 바꾸세요.

노드 테스트는 한 가지 결과만 보고 판단하지 않는 것이 좋습니다. 지연 시간이 낮아도 HTTPS 요청이 통과하지 않을 수 있고, 포트 연결이 가능해도 VLESS 또는 VMess 매개변수가 틀리면 핸드셰이크가 실패할 수 있습니다. 먼저 브라우저나 v2rayN의 연결 테스트로 프록시가 기본적으로 작동하는지 확인한 뒤 Gemini CLI를 실행하세요. 여러 노드를 동시에 바꾸면 어떤 설정이 문제를 해결했는지 알기 어려우므로 한 노드에서 설치와 인증을 차례로 검증하는 편이 안전합니다.

터미널에 프록시를 적용하고 Gemini CLI 설치하기

v2rayN을 준비했다면 이제 같은 컴퓨터의 터미널 프로세스에 프록시 주소를 전달합니다. PowerShell에서 설정한 환경 변수는 보통 현재 창과 그 창에서 새로 실행한 프로그램에 적용됩니다. 이미 열려 있던 터미널, IDE 통합 터미널 또는 별도의 관리자 권한 창에는 전달되지 않을 수 있으므로, 설정 후 같은 창에서 설치 명령을 실행하세요.

$env:HTTP_PROXY="http://127.0.0.1:10809"
$env:HTTPS_PROXY="http://127.0.0.1:10809"
$env:NO_PROXY="127.0.0.1,localhost"
npm install -g @google/gemini-cli

위 예시에서 HTTP 포트가 다른 값이면 두 줄의 포트를 모두 바꿉니다. NO_PROXY는 로컬 주소가 다시 외부 프록시로 전달되는 것을 막기 위한 예외입니다. 프록시 URL에 사용자 이름이나 비밀번호가 필요하지 않은 일반적인 로컬 포트라면 위와 같이 작성하면 됩니다. 설치가 끝난 뒤에는 gemini --version 또는 해당 버전 확인 명령으로 실행 파일이 PATH에 등록되었는지 확인하세요.

macOS와 Linux의 Bash 또는 Zsh에서는 다음처럼 현재 셸에 변수를 설정할 수 있습니다.

export HTTP_PROXY="http://127.0.0.1:10809"
export HTTPS_PROXY="http://127.0.0.1:10809"
export NO_PROXY="127.0.0.1,localhost"
npm install -g @google/gemini-cli

터미널 프록시를 항상 적용하고 싶다면 셸 프로필에 추가할 수 있지만, 공유 컴퓨터나 여러 네트워크를 오가는 노트북에서는 고정 설정이 오히려 혼란을 만들 수 있습니다. 사내 네트워크나 로컬 개발 서버까지 외부 프록시를 통과시키고 싶지 않다면 NO_PROXY에 내부 도메인과 사설 주소를 추가하세요. 설정이 끝난 뒤에는 새 터미널에서 변수가 실제로 보이는지 확인할 수 있습니다.

echo $env:HTTPS_PROXY
# macOS / Linux
echo $HTTPS_PROXY

Node.js 기반 도구의 모든 네트워크 라이브러리가 환경 변수를 동일하게 처리한다고 단정할 수는 없습니다. 환경 변수 설정 후에도 설치 요청이 직접 연결되는 것처럼 보이면 먼저 v2rayN 로그에 해당 시간의 연결 기록이 나타나는지 확인하세요. 로그가 전혀 없다면 CLI가 다른 프록시 설정을 요구하거나, 명령을 실행한 터미널에 변수가 전달되지 않은 경우가 많습니다.

로그인과 API 요청을 분리해서 검증하기

Gemini CLI의 인증 방식은 사용 중인 CLI 버전과 계정 환경에 따라 달라질 수 있습니다. 브라우저 기반 로그인을 선택하면 터미널에서 인증 명령을 실행한 뒤 브라우저 인증 페이지가 열리거나 인증 URL이 표시될 수 있습니다. 이때 브라우저만 프록시를 사용하고 CLI 프로세스는 직접 연결을 시도하면, 브라우저 인증은 완료된 것처럼 보여도 CLI가 토큰을 교환하는 단계에서 실패할 수 있습니다.

인증을 시작하기 전에 v2rayN 노드와 터미널 변수를 먼저 고정하세요. 인증 중간에 노드를 바꾸거나 HTTP와 SOCKS 설정을 동시에 수정하면 실패 원인을 구분하기 어렵습니다. API 키를 사용하는 방식이라면 키를 명령줄에 직접 붙여 넣어 셸 기록이나 프로세스 목록에 남기지 말고, CLI가 안내하는 안전한 환경 변수 또는 인증 저장 방식을 사용하세요. 키와 OAuth 토큰은 구독 주소와 마찬가지로 공개하면 안 됩니다.

기본 인증이 끝난 뒤에는 짧은 프롬프트로 API 응답을 확인하세요. 처음부터 큰 프로젝트 디렉터리를 스캔하거나 파일 수정 권한을 허용하면 네트워크 문제와 권한 문제를 동시에 만들 수 있습니다. 현재 작업 디렉터리를 비어 있는 테스트 폴더로 정하고, “간단한 연결 확인”처럼 짧은 요청을 보낸 다음 응답 시간과 v2rayN 로그를 함께 기록하는 방식이 좋습니다.

로그인 실패와 시간 초과를 구분해 점검하기

로그인 실패는 네트워크가 전혀 연결되지 않은 경우에만 발생하지 않습니다. 계정 인증 만료, 잘못된 인증 저장 상태, 브라우저와 CLI가 서로 다른 계정을 사용한 경우, 시스템 시간이 크게 어긋난 경우에도 인증이 거절될 수 있습니다. 반대로 시간 초과는 DNS 해석, 프록시 포트, 노드 원격 포트, 방화벽, TLS 핸드셰이크 또는 CLI의 프록시 미지원이 원인일 수 있습니다. 오류 문구 하나만 보고 노드를 바로 삭제하지 말고, 어느 단계에서 멈췄는지 기록하세요.

브라우저에서는 열리지만 Gemini CLI만 시간 초과되는 경우에는 먼저 현재 터미널의 환경 변수를 확인합니다. 변수가 비어 있거나 오타가 있거나, 터미널을 설정 전에 열어 둔 상태일 수 있습니다. 다음으로 v2rayN 로그에 CLI 요청 시각의 연결이 생성되는지 살펴보세요. 연결 기록이 없다면 CLI가 변수를 읽지 않았을 가능성이 높고, 기록은 있지만 원격 연결이 실패한다면 노드나 DNS, TLS 설정을 점검할 차례입니다.

반대로 로그인은 되지만 프로젝트 요청이 실패한다면 인증과 데이터 전송 경로를 분리해 보세요. 짧은 요청은 성공하고 큰 요청만 시간 초과된다면 회선 품질, 요청 크기, 서버 응답 지연 또는 터미널 프로그램의 자체 제한을 의심할 수 있습니다. 모든 요청이 즉시 인증 오류로 끝나면 프록시보다 계정과 키 상태를 우선 확인하세요. 연속으로 인증 요청을 반복하면 보안 시스템의 추가 제한이 생길 수 있으므로, 오류를 기록한 뒤 한 번에 한 항목만 수정하는 것이 좋습니다.

장기간 사용할 때의 보안과 재현성

터미널 프록시는 현재 셸에만 적용할 수도 있고 사용자 프로필에 영구 등록할 수도 있습니다. 개발 PC를 여러 네트워크에서 사용한다면 영구 등록보다 필요할 때 실행하는 스크립트나 별도 터미널 프로필이 관리하기 쉽습니다. 사무실, 집, 공용 네트워크에서 동일한 로컬 포트가 항상 열려 있다고 가정하지 말고, 작업 전에 v2rayN의 활성 상태와 포트를 확인하세요.

API 키와 인증 토큰은 소스 코드, 프로젝트의 .env 파일, 명령 기록, 화면 캡처에 남기지 않아야 합니다. 환경 변수를 사용하더라도 다른 프로그램이 프로세스 환경을 읽을 수 있는 공유 환경에서는 주의가 필요합니다. 키가 노출되었다고 의심되면 단순히 파일에서 삭제하는 것으로 끝내지 말고 해당 키를 폐기하고 새 자격 증명을 발급하세요. 구독 URL 역시 접근 권한을 포함할 수 있으므로 로그를 외부에 전달할 때 주소를 마스킹해야 합니다.

마지막으로 설정을 재현할 수 있도록 실제 사용한 값을 문서화하세요. v2rayN 버전, 선택한 코어, 노드 프로토콜, 로컬 HTTP 포트, 터미널 종류, 프록시 변수와 인증 방식을 기록하면 다른 컴퓨터에서 같은 문제를 빠르게 비교할 수 있습니다. 다만 비밀번호, API 키, 전체 구독 주소는 기록에서 제외하세요. Gemini CLI와 v2rayN은 각각 업데이트될 수 있으므로 메뉴 이름이나 기본 포트가 변경되면 예시를 그대로 복사하지 말고 현재 화면과 로그를 기준으로 다시 확인해야 합니다.