Gemini CLI v2rayN 설정법｜터미널 프록시 접속 문제 해결

Gemini CLI와 v2rayN을 함께 사용하는 이유

Gemini CLI는 브라우저 화면이 아니라 터미널에서 모델을 호출하고, 프로젝트 파일을 읽으며, 코드 작성과 설명을 보조하는 도구입니다. 개발자는 익숙한 셸에서 작업을 이어 갈 수 있고, 편집기와 버전 관리 도구 사이에서 창을 계속 전환하지 않아도 됩니다. 하지만 터미널 프로그램은 브라우저와 네트워크를 사용하는 방식이 다를 수 있습니다. 브라우저는 시스템 프록시를 자동으로 따르는데 CLI는 직접 연결을 시도하거나, 별도의 환경 변수를 읽거나, 인증 과정에서 다른 주소를 호출하는 경우가 있습니다.

이 때문에 v2rayN에서 노드가 연결되어 있고 웹사이트도 열리는데 Gemini CLI만 로그인에 실패하는 상황이 생깁니다. 이 문제를 클라이언트 고장으로 단정하기보다 노드 상태, 프록시 전달 방식, 인증 주소, 라우팅 규칙을 분리해서 확인해야 합니다. 한 번에 모든 설정을 바꾸면 어느 단계가 문제였는지 알 수 없으므로, 가장 단순한 연결부터 시작하는 것이 좋습니다.

설정 전에 준비할 항목

먼저 Windows, macOS, Linux 중 현재 사용하는 데스크톱 운영체제에 맞는 v2rayN을 설치합니다. v2rayN은 데스크톱용 클라이언트이므로 Android용 v2rayNG나 v2flyNG를 대신 받을 필요가 없습니다. 이미 설치했다면 버전을 확인하고, 오래된 버전이라면 다운로드 센터에서 최신 패키지를 확인하세요. 오래된 클라이언트는 구독 형식이나 최신 전송 옵션을 제대로 처리하지 못할 수 있습니다.

다음으로 서비스 제공자가 전달한 구독 주소 또는 단일 노드 링크를 준비합니다. 구독 주소는 일반적으로 여러 노드를 한 번에 가져와 주기적으로 갱신하는 URL이고, 단일 노드는 vmess://, vless://, trojan://, ss://처럼 하나의 연결 정보를 담은 문자열입니다. 두 종류를 서로 다른 입력 메뉴에 넣어야 하며, 주소를 복사할 때 앞뒤 공백이나 줄바꿈이 포함되지 않았는지도 확인하세요.

마지막으로 Gemini CLI의 설치와 인증 방법을 확인합니다. 이 글은 특정 운영체제의 설치 명령 자체보다, CLI가 v2rayN 프록시를 통과하도록 만드는 네트워크 점검에 초점을 둡니다. 계정, API 접근 권한, 서비스 지역 정책은 네트워크 프록시와 별개의 조건이므로 문제가 발생했을 때 각각 나누어 확인해야 합니다.

v2rayN에 구독 추가하기

v2rayN을 실행한 뒤 구독 관리 화면에서 새 구독 주소를 추가합니다. 이름은 나중에 알아보기 쉽게 서비스 이름이나 용도에 따라 정하면 됩니다. 주소를 붙여 넣은 뒤 저장하고 업데이트를 실행합니다. 정상적으로 가져왔다면 서버 목록에 여러 노드가 표시됩니다. 이때 곧바로 복잡한 라우팅을 설정하기보다, 지연 시간이 지나치게 높지 않고 최근에도 사용 가능한 노드 하나를 선택하세요.

업데이트가 실패하거나 노드 목록이 비어 있다면 Gemini CLI 설정으로 넘어가지 말고 구독 단계부터 해결해야 합니다. 주소 만료, 잘못된 복사, 현재 네트워크에서 구독 도메인에 접근할 수 없는 경우가 흔합니다. 시스템 시간이 크게 어긋나도 HTTPS 인증서 검증이 실패할 수 있습니다. 다른 네트워크나 휴대폰 핫스팟에서 갱신해 보고 결과가 달라지는지 확인하면 로컬 네트워크 문제인지 구독 자체의 문제인지 구분하기 쉽습니다.

단일 노드만 있다면 수동 가져오기로 먼저 등록할 수 있습니다. 이 방법은 구독 서버와 CLI를 동시에 의심하지 않고, 선택한 노드 자체가 작동하는지 빠르게 확인하는 데 유용합니다. 노드가 목록에 나타난 뒤 연결이 되지 않는다면 서버 만료, 인증 정보, 전송 설정을 확인하고, 목록 자체가 나타나지 않는다면 링크 형식과 가져오기 방식을 다시 살펴보세요.

처음에는 시스템 프록시로 검증하기

Gemini CLI를 처음 연결할 때는 v2rayN의 시스템 프록시 모드부터 시도하는 것이 좋습니다. 시스템 프록시는 운영체제의 HTTP 또는 SOCKS 프록시 설정을 v2rayN이 사용하도록 하는 방식입니다. 브라우저와 많은 개발 도구가 이 설정을 따르므로 구조가 단순하고, 연결 성공 여부를 판단하기 쉽습니다. 먼저 v2rayN에서 선택한 노드가 연결 상태인지 확인하고 시스템 프록시를 켠 다음, 브라우저와 터미널을 각각 테스트하세요.

브라우저는 정상인데 CLI만 실패한다면 시스템 프록시가 모든 프로그램에 자동으로 적용된다고 생각하면 안 됩니다. CLI가 프록시 환경 변수를 읽는지, 자체 설정에서 프록시를 무시하는지, 인증 과정에서 다른 도메인을 호출하는지 확인해야 합니다. 셸에서 사용하는 환경 변수 이름과 지원 형식은 프로그램 및 네트워크 라이브러리에 따라 다를 수 있으므로, Gemini CLI의 공식 문서에서 지원하는 항목을 우선 따르세요.

가능하다면 먼저 짧은 요청이나 로그인 화면 진입처럼 결과를 쉽게 확인할 수 있는 작업으로 테스트합니다. 요청이 오래 멈추는지, 즉시 네트워크 오류가 나오는지, 인증 페이지는 열리지만 콜백에서 실패하는지를 구분하면 다음 점검 방향이 달라집니다.

시스템 프록시로 부족할 때 TUN과 라우팅 확인

CLI가 시스템 프록시를 무시하거나 여러 관련 요청 중 일부만 직행한다면 TUN 모드를 고려할 수 있습니다. TUN은 가상 네트워크 인터페이스를 이용해 시스템 네트워크 계층에 더 가까운 위치에서 트래픽을 처리하므로, 일반 프록시 설정을 따르지 않는 프로그램을 포괄하는 데 도움이 됩니다. 다만 권한, DNS, 다른 VPN 프로그램과의 충돌 같은 변수가 늘어나므로 처음부터 TUN을 켜는 것은 권하지 않습니다.

TUN을 켜기 전에는 다른 VPN이나 프록시 프로그램을 종료하고, v2rayN이 필요한 네트워크 권한을 갖고 있는지 확인하세요. 켠 뒤에는 브라우저, 패키지 관리자, Gemini CLI를 순서대로 테스트합니다. 브라우저까지 모두 실패하면 TUN이 해결책이 아니라 새로운 충돌을 만든 것일 수 있습니다. 이 경우 TUN을 끄고 시스템 프록시에서 노드와 구독 상태를 다시 확인하세요.

라우팅은 목적지별로 직행 또는 프록시를 선택하는 규칙입니다. Gemini CLI가 연결할 수 있는 주소가 여러 개라면 로그인 서버, API 서버, 인증 콜백, 모델 요청 서버가 서로 다른 도메인을 사용할 수 있습니다. 일부 도메인만 직행으로 남아 있으면 로그인은 되지만 실제 요청에서 실패하거나, 요청은 시작되지만 응답이 매우 늦어질 수 있습니다. 처음에는 필요한 도메인을 임의로 많이 추가하기보다 기본 규칙으로 전체 흐름을 확인한 뒤, 로그에서 실제 실패한 주소를 기준으로 조정하세요.

로그인 실패를 단계별로 해결하기

로그인 실패는 여러 원인이 비슷한 오류로 표시될 수 있습니다. 첫째, 브라우저에서 인증 페이지가 정상적으로 열리는지 확인합니다. 둘째, CLI가 실행되는 같은 터미널 환경에서 프록시가 적용되는지 확인합니다. 셋째, 인증 후 돌아오는 콜백 주소나 토큰 교환 요청이 차단되지 않았는지 살펴봅니다. 브라우저 로그인만 성공했다고 해서 CLI의 인증 과정까지 완료된 것은 아닙니다.

1. v2rayN에서 선택한 노드가 실제로 연결 상태인지 확인합니다.
2. 시스템 프록시를 켜고 브라우저에서 기본 웹 접속을 테스트합니다.
3. Gemini CLI를 완전히 종료한 뒤 새 터미널에서 다시 실행합니다.
4. 프록시 환경 변수가 필요한 프로그램인지 공식 문서에서 확인합니다.
5. 로그인 주소와 인증 콜백이 라우팅 규칙에서 직행으로 빠지지 않는지 확인합니다.
6. 다른 VPN, 보안 프로그램, 회사 네트워크의 HTTPS 검사 기능을 잠시 점검합니다.

인증 창이 열리지 않는 경우와 인증 창은 열리지만 마지막에 실패하는 경우를 구분하세요. 전자는 CLI가 네트워크에 접근하지 못했거나 브라우저 호출이 막힌 경우가 많고, 후자는 콜백, 토큰 교환, 시간 동기화, 계정 권한 문제가 관련될 수 있습니다. 시스템 시간을 자동 동기화하고, 터미널과 브라우저의 계정이 동일한지 확인하는 것도 기본 점검에 포함해야 합니다.

요청 지연과 타임아웃 점검

로그인은 성공했지만 모델 요청이 느리다면 먼저 노드의 지연 시간과 실제 응답 안정성을 비교하세요. 핑이 낮은 노드가 항상 API 응답이 빠른 것은 아닙니다. 서버 위치, 혼잡도, TLS 연결, 장거리 경로에 따라 첫 연결은 빠르지만 긴 응답이 불안정할 수 있습니다. 같은 요청을 여러 노드에서 반복하기보다 짧은 요청으로 한 번씩 비교하고, 결과와 오류가 재현되는지 기록하는 편이 정확합니다.

요청이 일정 시간 뒤 끊긴다면 라우팅 누락, DNS 응답 지연, 네트워크의 장시간 연결 제한을 의심할 수 있습니다. v2rayN의 로그에서 연결 대상과 실패 시점을 확인하세요. 특정 도메인에서만 문제가 반복되면 해당 주소가 프록시 규칙에 포함되지 않았을 가능성이 있습니다. 반대로 모든 사이트와 CLI 요청이 느리다면 Gemini CLI보다 노드 또는 로컬 네트워크를 먼저 점검해야 합니다.

DNS 설정도 무시하지 마세요. 도메인은 조회되지만 잘못된 경로로 연결되거나, 로컬 DNS가 특정 주소를 반환해 요청이 지연될 수 있습니다. 다만 DNS와 라우팅을 동시에 크게 바꾸면 비교가 어려워집니다. 한 가지 설정을 바꾼 뒤 동일한 테스트를 반복하고, 이전 상태로 되돌릴 수 있도록 변경 내용을 간단히 기록하세요.

자주 하는 실수와 안전한 설정 순서

• 브라우저가 되면 CLI도 된다고 생각함: 프로그램마다 프록시 처리 방식이 다르므로 터미널 환경에서 별도로 확인해야 합니다.
• 처음부터 TUN과 여러 규칙을 동시에 사용함: 문제 변수가 많아지므로 시스템 프록시와 단순한 규칙부터 시작하세요.
• 구독 실패를 Gemini CLI 문제로 판단함: 노드가 목록에 생성되었는지 먼저 확인하고, 구독과 인증을 분리해서 점검하세요.
• 여러 프록시 도구를 동시에 실행함: 포트와 라우팅이 충돌할 수 있으므로 한 번에 하나의 주력 도구만 사용하세요.
• 오류가 날 때마다 노드를 계속 바꿈: 같은 조건에서 재현해야 원인을 찾을 수 있으므로 변경 폭을 줄이세요.

권장 순서는 명확합니다. v2rayN 설치, 구독 또는 단일 노드 추가, 노드 연결 확인, 시스템 프록시 테스트, Gemini CLI 인증, 실제 요청 테스트, 마지막으로 TUN과 라우팅 최적화 순서입니다. 이 순서를 지키면 “연결은 되지만 CLI만 안 됨”이라는 복합 문제를 작은 단계로 나누어 해결할 수 있습니다.

마무리: 기본 연결을 통과한 뒤 세부 설정하기

Gemini CLI와 v2rayN을 연결할 때 핵심은 특정 스위치를 무조건 켜는 것이 아닙니다. 먼저 구독과 노드가 정상인지 확인하고, 시스템 프록시로 가장 단순한 경로를 만든 뒤, CLI의 프록시 처리 방식과 인증 흐름을 점검해야 합니다. 로그인 실패는 인증 주소와 콜백을, 요청 지연은 노드 품질과 라우팅 및 DNS를 중심으로 나누어 살펴보세요.

시스템 프록시로 충분하지 않을 때만 TUN을 사용하고, 라우팅 규칙은 실제 로그와 재현 결과를 기준으로 조금씩 조정하는 것이 안전합니다. 설정을 바꿀 때마다 브라우저와 Gemini CLI를 같은 순서로 테스트하면 이전 상태와 비교하기도 쉽습니다. 개발 작업에 안정적인 터미널 프록시 환경이 필요하다면 최신 v2rayN을 설치하고, 사용하는 플랫폼과 네트워크 정책에 맞게 합법적으로 구성하세요.