Gemini CLI 국내 사용법과 Clash Verge 프록시 설정 가이드
Gemini CLI는 터미널에서 자연어로 코딩 작업을 요청하고, 현재 프로젝트의 파일을 읽어 구조를 파악하며, 코드 작성·수정·테스트 실행을 지원하는 명령줄 AI 도구입니다. 브라우저에서 별도 채팅 화면을 열지 않고도 개발 흐름을 이어 갈 수 있다는 점이 장점입니다. 특히 저장소 분석, 오류 원인 추적, 반복적인 코드 정리처럼 여러 파일을 함께 확인해야 하는 작업에서 편리합니다.
다만 Gemini CLI의 인증 화면이나 API 요청이 정상적으로 완료되려면 Google 서비스에 접근할 수 있는 네트워크 경로가 필요합니다. 브라우저에서 일반 웹사이트가 열린다고 해서 터미널의 Node.js 프로세스와 Gemini CLI 요청까지 같은 프록시를 사용하는 것은 아닙니다. 이 글에서는 Clash Verge를 기준으로 로컬 프록시 포트를 확인하고, Gemini CLI에 프록시를 연결하며, 필요한 도메인만 분할 라우팅하는 방법을 단계별로 설명합니다.
Gemini CLI의 설치와 인증 흐름 이해하기
Gemini CLI는 일반적으로 Node.js 환경에서 설치하고 터미널 명령으로 실행합니다. 설치 전에 Node.js가 지원되는 버전인지 확인하고, 운영체제의 패키지 관리자나 Node.js 공식 배포 경로를 이용해 준비하는 것이 좋습니다. 설치 명령은 배포 방식이 바뀔 수 있으므로 현재 배포 페이지의 안내를 우선해야 하지만, npm을 사용하는 환경에서는 다음과 같은 형태로 설치할 수 있습니다.
node --version
npm --version
npm install -g @google/gemini-cli
gemini
처음 실행하면 Google 계정으로 브라우저 인증을 진행하거나 API 키를 환경 변수로 지정하는 선택지가 나타날 수 있습니다. 브라우저 인증은 터미널에서 인증 URL을 열고, 브라우저에서 로그인과 권한 승인을 완료한 뒤 CLI로 돌아오는 방식입니다. 이때 브라우저만 Clash Verge를 사용하고 터미널은 직접 연결하는 상태라면 인증 콜백이나 토큰 교환 단계에서 실패할 수 있습니다.
API 키 방식은 키를 명령줄에 직접 입력하기보다 운영체제의 환경 변수나 안전한 비밀 저장 기능을 사용하는 편이 낫습니다. 셸 기록에 키가 남을 수 있는 명령, 프로젝트의 .env 파일을 그대로 커밋하는 방식, 동료에게 키가 보이는 화면 캡처는 피해야 합니다. 키가 노출되었다고 판단되면 해당 키를 폐기하고 새 키를 발급해야 합니다.
| 인증 방식 | 특징 | 주요 점검 항목 |
|---|---|---|
| 브라우저 로그인 | Google 계정과 권한 승인 화면을 사용합니다. | 브라우저와 CLI가 동일한 프록시 경로를 사용하는지 확인합니다. |
| API 키 | 환경 변수나 도구 설정을 통해 API 요청을 인증합니다. | 키 이름, 프로젝트 권한, 할당량과 노출 여부를 확인합니다. |
| 조직 계정 | 회사나 학교 정책에 따라 추가 제한이 적용될 수 있습니다. | 관리자 정책, 계정 지역, 서비스 접근 권한을 확인합니다. |
Clash Verge에서 로컬 프록시 포트 확인
Clash Verge를 실행한 뒤 먼저 현재 프로필이 정상적으로 로드되었는지 확인하세요. 화면에 프로필이 보이더라도 코어가 실행되지 않았거나 설정 파싱에 실패하면 프록시 포트가 열리지 않을 수 있습니다. 일반적으로 데스크톱 Clash 클라이언트는 HTTP와 SOCKS 요청을 함께 처리할 수 있는 mixed 포트를 사용하지만, 포트 번호는 사용자가 변경했거나 가져온 설정에 의해 달라질 수 있습니다.
Clash Verge의 설정 화면에서 포트, mixed-port 또는 포트 관련 항목을 찾고 실제 값을 기록합니다. 예를 들어 다음과 같은 설정이라면 HTTP와 SOCKS5 요청을 모두 7890으로 보낼 수 있습니다.
mixed-port: 7890
allow-lan: false
mode: rule
allow-lan: false는 같은 컴퓨터에서만 사용할 때의 일반적인 선택입니다. Gemini CLI를 실행하는 컴퓨터와 Clash Verge가 실행되는 컴퓨터가 다르다면 LAN 접근, 방화벽, 바인딩 주소를 별도로 구성해야 합니다. 외부 접근을 허용할 때는 신뢰할 수 있는 네트워크에서만 사용하고, 프록시 포트를 공용 인터넷에 직접 노출하지 마세요.
포트가 실제로 열려 있는지도 확인할 수 있습니다. Windows에서는 PowerShell이나 netstat를 사용하고, macOS와 Linux에서는 lsof 또는 ss 명령을 사용할 수 있습니다.
netstat -ano | findstr 7890
lsof -nP -iTCP:7890 -sTCP:LISTEN
ss -lntp | grep 7890
리스닝 프로세스가 없으면 Gemini CLI의 환경 변수를 수정하기 전에 Clash Verge의 코어 상태와 로그를 확인해야 합니다. 반대로 포트가 열려 있는데 요청이 실패한다면 노드 상태, 규칙 매칭 결과, DNS 처리와 인증 도메인 접근성을 순서대로 점검합니다.
직접 프록시를 지정해 Gemini CLI 연결 테스트하기
이제 중간 점검을 진행합니다. 환경 변수를 한꺼번에 등록하기 전에 curl로 Clash Verge의 로컬 포트와 외부 연결이 모두 작동하는지 확인하세요. 다음 명령에서 7890은 실제 Clash Verge 포트로 바꿔야 합니다.
curl -I -x http://127.0.0.1:7890 https://example.com
curl -I --proxy socks5h://127.0.0.1:7890 https://example.com
첫 번째 명령은 HTTP 프록시 형식으로 요청하고, 두 번째 명령은 SOCKS5 프록시를 사용합니다. socks5h의 h는 대상 도메인의 해석을 프록시 측에서 처리하도록 요청하는 표기입니다. 로컬 DNS가 특정 도메인을 해석하지 못하는 상황과 프록시 자체의 연결 실패를 구분할 때 유용합니다.
터미널 프로그램이 지원하는 경우에는 다음처럼 프록시 환경 변수를 임시로 지정해 테스트할 수 있습니다.
# macOS 또는 Linux
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5h://127.0.0.1:7890
gemini
# Windows PowerShell
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5h://127.0.0.1:7890"
gemini
모든 Node.js 도구가 모든 환경 변수와 프록시 형식을 동일하게 처리하는 것은 아닙니다. HTTP_PROXY와 HTTPS_PROXY를 읽는 라이브러리가 있는 반면, 애플리케이션이 자체 네트워크 클라이언트를 사용해 운영체제 프록시나 ALL_PROXY를 무시할 수도 있습니다. 따라서 변수 등록 후에도 CLI 로그와 Clash Verge의 연결 기록에 실제 요청이 나타나는지 확인해야 합니다.
- Clash Verge를 실행합니다. 프로필을 선택하고 코어가 실행 중인지 확인합니다.
- 실제 포트를 기록합니다. 기본값을 추측하지 말고 설정 화면의 mixed-port 또는 HTTP 포트를 확인합니다.
- curl로 외부 연결을 시험합니다. 로컬 포트에서 거부되는지, 외부 연결 단계에서 타임아웃이 발생하는지 구분합니다.
- 프록시 변수를 현재 셸에만 등록합니다. 먼저 임시 설정으로 Gemini CLI를 실행해 영구 설정 오류를 피합니다.
- 연결 기록을 확인합니다. 요청 도메인, 적용 규칙, 선택된 정책 그룹과 오류 메시지를 함께 확인합니다.
- 정상 동작 후 영구 설정합니다. 셸 프로필에 추가할 때는 키와 토큰을 함께 기록하지 않도록 주의합니다.
Gemini CLI 트래픽을 Clash 규칙으로 분할 라우팅하기
모든 트래픽을 무조건 프록시로 보내는 전역 모드는 원인 파악에는 편리하지만, 개발 환경 전체의 연결 경로를 바꾸므로 장기 사용에는 적합하지 않을 수 있습니다. 국내 서비스, 사내 저장소, 패키지 미러처럼 직접 연결이 더 안정적인 대상까지 같은 노드로 보내면 속도가 느려지거나 인증 정책에 걸릴 수 있습니다. 일반적인 사용에서는 규칙 모드에서 Gemini CLI와 관련된 도메인만 필요한 정책 그룹으로 보내는 방식을 고려할 수 있습니다.
다만 Gemini CLI가 실제로 요청하는 도메인은 인증 방식, 모델 서비스, 계정 환경과 버전에 따라 달라질 수 있습니다. 특정 도메인 목록을 무조건 복사하기보다 Clash Verge의 연결 기록에서 실패한 요청을 확인하고, 해당 서비스의 공식 안내와 대조해 규칙을 작성하세요. 너무 넓은 DOMAIN-SUFFIX 규칙은 관계없는 Google 서비스까지 같은 경로로 보낼 수 있습니다.
rules:
- DOMAIN-SUFFIX,googleapis.com,AI-Proxy
- DOMAIN-SUFFIX,google.com,AI-Proxy
- DOMAIN-SUFFIX,googleusercontent.com,AI-Proxy
- MATCH,DIRECT
위 예시는 구조를 설명하기 위한 예시입니다. 실제 환경에서는 사용하는 서비스의 도메인과 정책 그룹 이름에 맞게 수정해야 하며, AI-Proxy라는 그룹이 proxy-groups에 먼저 정의되어 있어야 합니다. 규칙은 위에서 아래로 평가되므로, 더 구체적인 도메인 규칙을 넓은 규칙보다 위에 배치해야 합니다. 마지막의 MATCH는 앞에서 처리되지 않은 연결을 위한 최종 규칙이므로 그 뒤에 추가한 규칙은 적용되지 않습니다.
인증 브라우저와 터미널이 서로 다른 경로를 사용하면 로그인은 완료된 것처럼 보여도 CLI의 토큰 교환이 실패할 수 있습니다. 이 경우 인증 단계에서 사용하는 브라우저도 Clash Verge의 시스템 프록시를 사용하게 하거나, 인증 기간 동안 전역 모드로 일시 테스트한 뒤 연결 기록을 바탕으로 규칙 모드로 좁혀 가세요. TUN 모드는 시스템 프록시를 무시하는 프로그램까지 처리하는 데 도움이 되지만, 가상 인터페이스 권한과 DNS 설정에 영향을 주므로 먼저 일반 로컬 프록시 방식으로 확인하는 것이 좋습니다.
DNS와 인증 콜백 문제 점검하기
Gemini CLI 연결 실패가 항상 노드 문제인 것은 아닙니다. 도메인 이름을 IP 주소로 바꾸는 DNS 과정이 로컬 네트워크에서 차단되거나, DNS 결과와 실제 프록시 연결 경로가 서로 맞지 않으면 요청이 시작되기 전에 실패할 수 있습니다. Clash Verge에서 DNS 모드와 연결 로그를 확인하고, 도메인 규칙에 no-resolve를 추가했는지 여부도 살펴보세요. 이 옵션은 규칙 매칭을 위해 도메인을 해석하지 않도록 하므로 GeoIP 기반 판단이 필요한 규칙과 함께 사용할 때 결과가 달라질 수 있습니다.
브라우저 인증이 열리지 않는다면 첫째로 기본 브라우저가 올바르게 실행되는지, 둘째로 인증 URL이 중간에 잘리지 않았는지, 셋째로 브라우저와 CLI가 동일한 계정으로 로그인되어 있는지 확인하세요. 인증 창이 열리지만 승인 후 터미널에 완료 신호가 전달되지 않는다면 로컬 콜백 주소가 다른 프로그램에 의해 차단되거나, 보안 소프트웨어가 임시 로컬 포트를 차단하는 경우도 있습니다.
API 키 인증에서 401 또는 403이 발생하면 먼저 키 값의 앞뒤 공백, 환경 변수 이름, 계정 권한과 API 사용 설정을 확인합니다. 429는 대개 요청 한도나 일시적인 할당량 문제를 의미하므로 노드를 반복해서 변경하기보다 사용량과 재시도 간격을 확인해야 합니다. 5xx 응답이나 긴 타임아웃은 서비스 측 일시 장애, 프록시 노드 품질, 규칙에서의 잘못된 출구 선택을 함께 점검해야 합니다.
자주 발생하는 오류와 해결 순서
| 증상 | 가능한 원인 | 권장 확인 순서 |
|---|---|---|
| connection refused | 잘못된 포트, 코어 중지, 포트 충돌 | Clash Verge의 실제 포트와 운영체제 리스닝 상태를 확인합니다. |
| timeout | 노드 불안정, 방화벽, DNS 또는 잘못된 규칙 | 연결 기록의 정책 그룹과 대상 도메인을 확인하고 다른 정상 노드로 비교합니다. |
| 인증 페이지 미표시 | 브라우저 프록시 불일치, URL 차단, 기본 브라우저 문제 | 브라우저와 CLI의 경로를 맞추고 인증 URL을 다시 생성합니다. |
| 401 또는 403 | 잘못된 키, 권한 부족, 계정 정책 | 키 이름과 권한을 확인한 뒤 노드 변경과 분리해 테스트합니다. |
| 429 | 요청량 또는 사용량 한도 초과 | API 사용량과 할당량을 확인하고 짧은 시간에 반복 요청하지 않습니다. |
| 브라우저만 정상 | 터미널이 시스템 프록시를 읽지 않음 | 환경 변수를 임시 지정하고 Clash 기록에 CLI 요청이 나타나는지 확인합니다. |
문제를 해결할 때는 한 번에 여러 요소를 바꾸지 않는 것이 중요합니다. 먼저 Clash Verge를 전역 모드로 전환해 연결 자체를 확인하고, 다음에는 환경 변수를 명시한 상태에서 Gemini CLI를 실행합니다. 이 단계가 성공하면 규칙 모드로 돌아가 필요한 도메인만 분할 라우팅합니다. 마지막으로 TUN을 추가해야 한다면 TUN을 켜기 전후의 연결 기록과 DNS 동작을 비교하세요. 그래야 노드 문제와 모드 변경으로 생긴 문제를 구분할 수 있습니다.
안전하고 안정적인 일상 사용을 위한 설정
Gemini CLI는 프로젝트 파일을 읽고 명령 실행을 제안하거나 실제로 실행할 수 있으므로, 프록시 연결이 된다는 이유만으로 모든 작업을 자동 승인해서는 안 됩니다. 처음 사용하는 저장소에서는 현재 디렉터리를 확인하고, 민감한 환경 변수와 비밀 파일이 포함되어 있는지 살펴보세요. API 키, 클라우드 인증 파일, SSH 개인 키, 사내 설정 파일은 AI 도구에 전달하거나 변경 대상으로 포함하지 않도록 프로젝트 규칙과 무시 목록을 정리하는 편이 좋습니다.
개발용 프록시 설정은 공유 네트워크에서의 보안도 고려해야 합니다. allow-lan을 불필요하게 활성화하지 말고, 외부 컨트롤러 주소와 비밀 키를 기본값으로 방치하지 마세요. Clash Verge의 시스템 프록시를 끈 뒤에도 터미널 환경 변수는 남아 있을 수 있으므로, 네트워크를 직접 사용해야 하는 작업에서는 현재 셸의 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 값을 확인해야 합니다.
작업이 끝난 뒤에는 임시 프록시 변수를 해제할 수 있습니다.
# macOS 또는 Linux
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
unset http_proxy https_proxy all_proxy
# Windows PowerShell
Remove-Item Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:ALL_PROXY
정리하면 Gemini CLI 문제는 “Clash Verge가 켜져 있는가”만으로 판단할 수 없습니다. 실제 포트가 열려 있는지, CLI가 해당 포트를 사용하는지, 요청이 Clash 연결 기록에 나타나는지, DNS와 규칙이 올바른지, 마지막으로 인증 계정과 사용량 제한이 정상인지 순서대로 확인해야 합니다. 이 흐름을 지키면 전역 모드에 의존하지 않고도 필요한 AI 코딩 트래픽만 안정적으로 프록시 처리할 수 있습니다.