Gemini CLI v2rayN 설정법과 국내 접속 문제 해결 가이드

Gemini CLI가 v2rayN과 함께 필요한 이유

Gemini CLI는 브라우저가 아니라 터미널에서 인증과 API 요청을 처리하는 명령줄 도구입니다. 따라서 브라우저에서 Gemini 웹페이지가 열리더라도 터미널 프로세스가 같은 네트워크 경로를 사용한다는 보장은 없습니다. 브라우저는 운영체제 프록시를 따르지만 CLI는 직접 연결을 시도하거나, 별도의 프록시 환경 변수를 읽는 경우가 있기 때문입니다.

국내 네트워크에서 Gemini CLI 로그인 화면이 열리지 않거나, 인증은 끝났는데 API 요청에서 시간 초과가 발생한다면 먼저 v2rayN의 노드 상태와 프록시 모드를 분리해서 확인하세요. v2rayN이 실행 중이라는 사실만으로 모든 프로그램이 프록시를 사용하는 것은 아닙니다. 노드 연결, 운영체제 프록시, CLI 환경 변수는 서로 다른 단계입니다.

처음부터 복잡한 TUN 설정을 적용하기보다는 v2rayN에서 사용 가능한 노드를 선택하고 시스템 프록시를 켠 뒤, 브라우저에서 일반 HTTPS 사이트가 정상적으로 열리는지 확인하는 순서가 좋습니다. 이 기준선이 있어야 Gemini CLI 자체의 인증 오류와 네트워크 경로 오류를 구분할 수 있습니다.

v2rayN에서 먼저 확인할 설정

v2rayN을 열고 구독 또는 단일 노드가 정상적으로 가져와졌는지 확인하세요. 노드 목록이 비어 있거나 모든 항목의 지연 측정이 실패한다면 Gemini CLI 설정을 만지기 전에 구독 주소, 노드 만료 여부, 시스템 시간, 현재 네트워크를 점검해야 합니다. 노드가 실제로 사용할 수 있는지 확인되지 않은 상태에서 환경 변수만 추가하면 문제 원인이 더 복잡해집니다.

노드를 선택한 다음 초보자는 먼저 시스템 프록시를 사용하는 편이 좋습니다. Windows의 v2rayN에서 시스템 프록시를 켜면 운영체제 프록시 설정을 따르는 브라우저와 일부 개발 도구가 자동으로 프록시를 사용합니다. 다만 모든 CLI가 이 설정을 자동으로 읽는 것은 아니므로, 브라우저는 되는데 Gemini CLI만 실패한다면 다음 단계로 환경 변수를 확인하세요.

v2rayN의 로컬 포트는 설치 버전과 설정에 따라 다를 수 있습니다. 흔히 HTTP 프록시는 127.0.0.1:10809, SOCKS 프록시는 127.0.0.1:10808처럼 표시되지만, 이 값을 그대로 복사하지 말고 v2rayN의 실제 포트 화면에서 확인해야 합니다. HTTP 프록시 포트와 SOCKS 포트를 바꾸어 입력하면 연결 거부, TLS 오류, 요청 시간 초과가 나타날 수 있습니다.

터미널에 프록시 환경 변수 설정하기

Gemini CLI가 운영체제 프록시를 따르지 않는다면 터미널 세션에 프록시 환경 변수를 설정해 보세요. Windows PowerShell에서는 현재 창에서만 적용되도록 $env:HTTPS_PROXY="http://127.0.0.1:10809"와 $env:HTTP_PROXY="http://127.0.0.1:10809"를 입력할 수 있습니다. 실제 포트가 다르면 v2rayN에 표시된 포트로 바꾸세요. 대소문자 처리 방식은 프로그램마다 다를 수 있으므로 필요하면 https_proxy와 http_proxy도 함께 설정합니다.

macOS나 Linux의 셸에서는 export HTTPS_PROXY=http://127.0.0.1:10809, export HTTP_PROXY=http://127.0.0.1:10809와 같은 방식으로 설정합니다. 이 설정은 보통 현재 터미널 창과 그 안에서 실행하는 자식 프로세스에 적용됩니다. 터미널을 새로 열었는데 설정이 사라졌다면 정상적인 동작일 수 있으며, 매번 적용하려면 사용하는 셸의 환경 설정 파일에 추가하되 먼저 일회성 테스트로 성공 여부를 확인하세요.

프록시를 해제하고 직접 연결을 비교할 때는 현재 셸의 변수를 지우면 됩니다. PowerShell에서는 Remove-Item Env:HTTPS_PROXY와 Remove-Item Env:HTTP_PROXY, macOS와 Linux에서는 unset HTTPS_PROXY HTTP_PROXY를 사용할 수 있습니다. 직접 연결과 프록시 연결의 결과를 비교하면 v2rayN이 실제 원인인지 빠르게 판단할 수 있습니다.

환경 변수에 사용자 이름이나 비밀번호를 넣어야 하는 프록시는 인증 정보가 터미널 기록이나 프로세스 목록에 남을 수 있으므로 주의하세요. 로컬에서 v2rayN이 제공하는 프록시를 사용할 때는 보통 인증 정보를 추가하지 않습니다. 또한 ALL_PROXY만 설정하면 일부 프로그램은 SOCKS 형식을 기대하고, 다른 프로그램은 HTTP 프록시만 지원할 수 있으므로 처음에는 HTTP_PROXY와 HTTPS_PROXY를 명시하는 편이 안전합니다.

실제로 로그인과 API 연결 테스트하기

  1. v2rayN을 실행하고 사용 가능한 노드를 선택한 뒤 시스템 프록시를 켭니다.
  2. 브라우저에서 일반 HTTPS 페이지를 열어 노드와 로컬 프록시가 작동하는지 확인합니다.
  3. v2rayN에 표시된 HTTP 프록시 주소와 포트를 확인하고, 새 터미널에 HTTPS_PROXY와 HTTP_PROXY를 설정합니다.
  4. 같은 터미널에서 Gemini CLI를 실행해 로그인 또는 초기 인증 절차를 진행합니다.
  5. 로그인 후 간단한 요청을 보내고, 응답 지연과 오류 메시지를 기록합니다.

인증 과정에서 브라우저가 자동으로 열리는 경우 브라우저와 CLI가 서로 다른 환경에서 실행될 수 있습니다. 브라우저 인증이 성공했다면 해당 터미널로 돌아와 CLI가 인증 완료를 감지했는지 확인하세요. 인증 페이지가 계속 반복되면 계정 문제가 아니라 콜백 주소, 브라우저 차단, 기존 인증 캐시, 프록시 환경 변수 중 하나일 수 있습니다.

테스트는 짧고 단순한 요청부터 시작하세요. 처음부터 긴 프롬프트나 파일 분석을 실행하면 인증 실패, API 권한 부족, 응답 시간 초과를 구분하기 어렵습니다. 한 번 성공한 뒤에 프로젝트 디렉터리, 모델 선택, 출력 형식 같은 추가 옵션을 하나씩 적용하는 것이 좋습니다.

라우팅 규칙과 국내 접속 문제 점검

시스템 프록시와 환경 변수를 설정했는데도 Gemini CLI만 실패한다면 v2rayN의 라우팅 규칙을 확인하세요. 규칙 기반 모드에서 특정 Google 또는 Gemini 관련 도메인이 직결로 분류되면 브라우저 일부 요청은 성공해도 CLI API 요청만 실패할 수 있습니다. 반대로 모든 트래픽을 무조건 프록시로 보내면 속도와 안정성이 떨어질 수 있으므로, 먼저 어떤 도메인과 포트가 실패하는지 로그로 확인하는 것이 좋습니다.

로그에 도메인 확인 실패, TLS 협상 실패, 연결 시간 초과가 보이면 각각 접근 방법이 다릅니다. 도메인 확인 실패는 DNS 또는 네트워크 경로를, TLS 오류는 잘못된 프록시 형식·시간 설정·중간 인증서 간섭을, 시간 초과는 노드 품질·라우팅·방화벽을 의심할 수 있습니다. 시스템 날짜와 시간대가 틀리면 인증서 검증과 로그인 토큰 처리에도 영향을 줄 수 있으니 자동 시간 동기화를 켜 두세요.

회사나 학교 네트워크에서는 로컬 프록시 포트 자체가 차단되는 것이 아니라 외부 API 도메인이나 인증 콜백이 제한될 수 있습니다. 이때 휴대폰 핫스팟처럼 다른 네트워크에서 같은 v2rayN 설정을 시험해 보세요. 다른 네트워크에서는 성공한다면 클라이언트 재설치보다 현재 네트워크의 DNS, 방화벽, 웹 필터 정책을 확인하는 편이 합리적입니다.

국내 접속 문제를 해결한다는 이유로 임의의 인증서 설치, 출처가 불분명한 CLI 패치, 계정 토큰 공유 파일을 사용하지 마세요. 계정 정보와 API 키가 노출될 수 있고, 정상적인 인증 흐름을 오히려 망가뜨릴 수 있습니다. v2rayN과 Gemini CLI는 신뢰할 수 있는 공식 배포 경로에서 받고, 서비스 이용 약관과 관련 법규를 준수해야 합니다.

자주 나타나는 오류별 해결 순서

문제 해결 중에는 v2rayN 노드, 프록시 모드, 환경 변수, 라우팅 규칙을 한꺼번에 바꾸지 않는 것이 중요합니다. 한 번에 하나만 바꾸고 결과를 기록하면 어떤 설정이 영향을 주었는지 알 수 있습니다. 먼저 기본 노드와 시스템 프록시로 기준선을 만든 뒤, CLI 환경 변수와 규칙을 추가하는 순서가 가장 재현하기 쉽습니다.

Gemini CLI 사용을 마친 뒤에는 공용 컴퓨터에서 프록시 환경 변수와 인증 캐시가 남아 있지 않은지도 확인하세요. 특히 API 키나 계정 토큰을 명령줄에 직접 입력해 셸 기록에 남기는 방식은 피하는 것이 좋습니다. 연결이 안정된 뒤에도 v2rayN과 CLI를 최신 상태로 유지하고, 구독이 만료되지 않았는지 주기적으로 확인하면 같은 오류의 재발을 줄일 수 있습니다.