Gemini CLI Clash Verge 설정법과 안정적인 터미널 접속 가이드

Gemini CLI와 Clash Verge의 역할부터 구분하기

Gemini CLI는 터미널에서 자연어 명령을 입력하고, 현재 작업 디렉터리의 파일을 읽거나 코드를 분석하며, 승인된 작업을 수행할 수 있는 개발 도구입니다. 실제 요청은 브라우저 화면이 아니라 명령줄 프로세스에서 발생하므로, 브라우저에만 적용된 프록시 설정으로는 충분하지 않을 수 있습니다. Windows의 시스템 프록시를 사용하지 않는 터미널, 별도 런타임으로 실행되는 Node.js 프로세스, 컨테이너 안의 명령은 각각 다른 네트워크 경로를 사용할 수 있습니다.

Clash Verge는 이 요청을 대신 전달하는 GUI 클라이언트입니다. 구체적으로는 구독에서 내려받은 프록시 노드와 프록시 그룹을 mihomo 코어에 전달하고, 시스템 프록시·TUN·DNS·규칙 모드를 조정합니다. 따라서 Gemini CLI 설치 자체가 실패했을 때는 패키지 관리자나 Node.js 문제를 먼저 확인하고, 로그인 페이지가 열리지 않거나 인증 요청이 시간 초과될 때는 Clash의 연결 경로와 규칙을 점검해야 합니다.

두 구성 요소를 한꺼번에 바꾸면 원인을 찾기 어렵습니다. 먼저 Clash Verge에서 일반 웹 요청이 정상적으로 통과하는지 확인한 다음 Gemini CLI를 설치하고, 마지막으로 인증과 API 요청을 분리해서 검사하는 순서가 좋습니다. 특히 "브라우저는 접속되는데 터미널만 실패한다"면 노드 자체보다 터미널 프로세스가 프록시를 인식하지 못하는 상황일 가능성이 큽니다.

Clash Verge에서 프로필과 코어를 먼저 준비하기

처음에는 최신 기능이 필요한지보다 현재 사용하는 프로필이 Clash 형식과 mihomo 코어에 맞는지를 확인하는 것이 중요합니다. Clash Verge 또는 Clash Verge Rev를 실행한 뒤 프로필 페이지에서 제공받은 구독 URL을 추가하고, 내려받은 설정을 활성 프로필로 선택합니다. 구독이 정상적으로 로드되면 프록시 그룹과 노드 목록이 표시되어야 하며, 노드가 하나도 나타나지 않으면 Gemini CLI 설정으로 넘어가기 전에 구독 형식부터 해결해야 합니다.

1. Clash Verge를 실행하고 Profiles 또는 프로필 관리 화면을 엽니다.
2. 구독 URL을 추가한 뒤 새 프로필을 업데이트하고, YAML 파싱 오류나 빈 노드 목록이 없는지 확인합니다.
3. 가져온 프로필을 활성 프로필로 지정하고, 프록시 페이지에서 실제로 사용할 그룹을 선택합니다.
4. 노드 하나를 직접 선택한 뒤 일반적인 HTTPS 웹사이트에 접속해 연결과 DNS 처리가 정상인지 확인합니다.
5. 처음부터 자동 선택 그룹만 사용하지 말고, 문제가 생겼을 때 비교할 수 있도록 응답이 안정적인 노드를 하나 기록해 둡니다.

Clash Verge의 설정 화면에서 코어가 실행 중인지도 확인해야 합니다. 프로필은 정상적으로 보이지만 mihomo 코어가 시작되지 않았다면 시스템 프록시를 켜도 실제 요청을 처리할 프로세스가 없습니다. 로그 페이지에 포트 점유, 설정 필드 오류, TUN 초기화 실패가 표시되는지 살펴보세요. 다른 프록시 프로그램이 이미 같은 포트를 사용하고 있다면 Clash의 HTTP 포트와 SOCKS 포트를 변경하거나 충돌 중인 프로그램을 종료해야 합니다.

시스템 프록시와 TUN 모드 중 무엇을 선택할까

Gemini CLI만 프록시로 연결하려면 우선 시스템 프록시 또는 터미널 환경 변수 방식부터 시도하는 편이 안전합니다. 시스템 프록시는 운영체제의 HTTP·HTTPS 프록시 설정을 읽는 애플리케이션에 적용됩니다. 브라우저와 일부 개발 도구에는 편리하지만, 모든 CLI 프로그램이 이 설정을 읽는 것은 아닙니다. 애플리케이션이 자체적으로 소켓을 열거나 시스템 프록시 API를 사용하지 않으면 요청이 직접 나갈 수 있습니다.

TUN 모드는 가상 네트워크 인터페이스를 만들어 시스템의 더 넓은 범위의 트래픽을 Clash가 처리하도록 하는 방식입니다. 환경 변수 설정을 이해하지 못하는 도구나 시스템 프록시를 무시하는 프로세스까지 포함하기 쉽다는 장점이 있지만, DNS 처리와 로컬 네트워크 접근에 영향을 줄 수 있습니다. Windows에서는 관리자 권한이 필요할 수 있고, macOS에서는 네트워크 확장 프로그램 승인이 필요할 수 있습니다.

권장 순서는 시스템 프록시와 환경 변수를 먼저 시험하고, 그래도 Gemini CLI 요청이 직접 연결되거나 인증 단계가 반복해서 실패할 때 TUN을 검토하는 것입니다. TUN을 켠 뒤 문제가 생기면 무조건 더 강한 모드가 필요하다고 판단하지 말고, 로컬 주소와 DNS 예외가 함께 바뀌었는지 확인해야 합니다.

터미널에 프록시를 연결하는 실전 설정

Clash Verge의 HTTP 포트가 기본값인 7890이라고 가정하면, 터미널에서는 보통 다음과 같이 프록시 변수를 설정할 수 있습니다. 실제 포트는 Clash Verge의 설정 화면에 표시된 값을 사용해야 합니다. SOCKS 포트만 열려 있다면 http:// 대신 프로그램이 지원하는 SOCKS 형식을 사용해야 하지만, 호환성 측면에서는 먼저 Clash의 HTTP 프록시 포트를 사용하는 편이 간단합니다.

# macOS / Linux: 현재 셸 세션에만 적용
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=http://127.0.0.1:7890

# 프록시를 거치지 않을 로컬 주소
export NO_PROXY=127.0.0.1,localhost,::1

# 현재 설정 확인
env | grep -i proxy

Windows PowerShell에서는 다음처럼 입력합니다.

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="http://127.0.0.1:7890"
$env:NO_PROXY="127.0.0.1,localhost,::1"

Get-ChildItem Env:*proxy*

이 환경 변수는 해당 셸에서 실행한 하위 프로세스에 전달됩니다. 따라서 변수를 설정한 뒤 같은 터미널에서 Gemini CLI를 실행해야 하며, 새 터미널을 열면 다시 사라질 수 있습니다. 셸 초기화 파일에 영구적으로 넣는 방법도 있지만, 회사 네트워크나 집 네트워크를 오갈 때 프록시가 없는 환경에서 명령이 실패할 수 있으므로 처음에는 세션 단위로 시험하는 것이 좋습니다.

1. Clash Verge에서 사용할 노드와 그룹을 선택하고 시스템 프록시 또는 로컬 HTTP 포트를 확인합니다.
2. 새 터미널을 열고 운영체제에 맞는 환경 변수를 설정합니다.
3. env 또는 PowerShell의 환경 변수 조회 명령으로 오타와 포트 번호를 확인합니다.
4. 간단한 HTTPS 요청으로 터미널 프로세스가 프록시를 사용하는지 시험합니다.
5. 확인 후 같은 터미널에서 Gemini CLI 설치와 로그인 명령을 실행합니다.

프록시 주소를 localhost로 설정했는데 연결되지 않는다면 127.0.0.1로 바꿔 비교해 보세요. 일부 런타임에서는 IPv6 우선 처리나 로컬 호스트 이름 해석 때문에 예상과 다른 주소로 연결할 수 있습니다. 반대로 Clash Verge를 다른 컴퓨터에서 실행하고 있다면 루프백 주소가 아니라 해당 컴퓨터의 사설 IP와 허용된 포트를 사용해야 합니다. 이때 외부 네트워크에 프록시 포트를 무방비로 노출하지 않도록 방화벽과 컨트롤 포트 접근 설정을 반드시 확인해야 합니다.

Gemini CLI 설치와 Google 인증 흐름

Gemini CLI 설치 전에 Node.js가 지원되는 버전인지 확인하고, 패키지 관리자를 통해 설치합니다. 설치 명령은 배포 방식과 현재 프로젝트의 문서에 따라 달라질 수 있으므로, 패키지 이름과 최신 명령은 공식 사용 안내를 기준으로 확인하세요. 일반적으로 전역 설치를 선택하면 어느 디렉터리에서든 CLI 명령을 호출할 수 있고, 프로젝트별 설치를 선택하면 팀 단위로 버전을 고정하기 쉽습니다.

# 설치 예시
npm install -g @google/gemini-cli

# 설치된 명령 확인
gemini --version

# 도움말 확인
gemini --help

인증 방식은 실행 시 표시되는 선택지에 따라 진행합니다. Google 계정 브라우저 로그인을 선택하면 CLI가 인증용 URL을 열거나 코드를 표시하고, 브라우저에서 계정 승인을 마친 뒤 터미널로 결과를 전달합니다. 이 과정에서 브라우저 페이지가 열리지 않는 문제와 CLI가 인증 완료를 감지하지 못하는 문제는 서로 다릅니다. 브라우저는 접속되는데 터미널이 멈춘다면 로컬 콜백 주소, 방화벽, 터미널 프로세스의 프록시 설정을 따로 확인해야 합니다.

인증 요청에는 로그인 페이지뿐 아니라 Google 계정 인증과 개발자 서비스 API에 관련된 여러 HTTPS 도메인이 관여할 수 있습니다. 대표적으로 accounts.google.com, oauth2.googleapis.com, generativelanguage.googleapis.com 등이 있으며, 실제 사용 경로는 CLI 버전과 인증 방식, Google Cloud 프로젝트 사용 여부에 따라 달라질 수 있습니다. 특정 도메인 목록을 영구적으로 고정하기보다 Clash 로그에서 실제 요청이 어떤 주소로 나가는지 확인하고, 필요한 도메인만 규칙에 반영하는 것이 안전합니다.

Gemini 관련 도메인만 분리하는 Clash 규칙

모든 트래픽을 하나의 프록시 그룹으로 보내면 문제를 빠르게 피할 수 있지만, 개발 환경에서는 패키지 저장소, 사내 Git 서버, 로컬 서비스까지 같은 경로로 보내는 부작용이 생길 수 있습니다. Clash의 규칙 모드에서는 도메인 접미사와 전체 도메인을 기준으로 Gemini 관련 요청만 특정 그룹에 전달하도록 구성할 수 있습니다.

rules:
  - DOMAIN-SUFFIX,google.com,Gemini
  - DOMAIN-SUFFIX,googleapis.com,Gemini
  - DOMAIN-SUFFIX,gstatic.com,Gemini
  - DOMAIN-SUFFIX,googleusercontent.com,Gemini
  - MATCH,DIRECT

위 예시는 구조를 이해하기 위한 기본 형태입니다. google.com이나 googleapis.com 전체를 프록시로 보내면 Gemini CLI 외의 Google 서비스도 같은 그룹으로 처리될 수 있습니다. 더 좁은 범위를 원한다면 Clash Verge에서 실제 로그를 관찰한 뒤 DOMAIN 또는 더 구체적인 DOMAIN-SUFFIX 규칙을 사용하세요. 단, 인증과 API 요청에 필요한 도메인을 지나치게 좁히면 로그인은 성공했지만 모델 요청만 실패하는 상황이 발생할 수 있습니다.

규칙의 순서도 중요합니다. Clash는 일반적으로 위에서 아래로 규칙을 평가하므로, 앞쪽에 광범위한 DOMAIN-SUFFIX,google.com,DIRECT가 있으면 뒤에 추가한 Gemini 규칙은 도달하지 못합니다. 기존 프로필이 규칙 제공 서비스에서 내려온 것이라면 직접 수정한 내용이 다음 업데이트 때 사라질 수 있으므로, 프리미엄 규칙이나 오버라이드 기능을 지원하는지 확인하고 사용자 규칙을 별도 영역에 두는 편이 좋습니다.

DOMAIN-KEYWORD는 이름에 특정 문자열이 들어간 모든 도메인을 잡을 수 있어 편리하지만, 예상하지 않은 호스트까지 포함할 수 있습니다. 처음에는 로그 분석용으로 사용하고, 안정화한 뒤에는 실제로 필요한 호스트를 DOMAIN 또는 DOMAIN-SUFFIX로 좁히는 방법이 좋습니다.

DNS, TUN, 인증 실패를 함께 점검하기

Gemini CLI가 "네트워크 오류", "fetch failed", "socket timeout"처럼 포괄적인 메시지만 출력한다면 DNS와 프록시 경로를 분리해서 확인해야 합니다. TUN을 사용하는 경우 Clash의 DNS 모드가 시스템 DNS와 충돌하지 않는지 확인하고, Fake-IP를 사용하는 프로필이라면 로컬 개발 도메인과 사설망 주소가 예외 처리되어 있는지 살펴보세요. 로컬호스트 콜백을 인증에 사용하는 경우에는 127.0.0.1, localhost, ::1을 프록시에서 제외하는 것이 일반적입니다.

DNS가 프록시를 거치지 않으면 도메인은 해석되더라도 실제 연결 단계에서 다른 경로가 선택될 수 있습니다. 반대로 DNS 요청은 정상인데 API 연결만 실패한다면 특정 노드의 TLS 처리, 대상 서비스와의 경로 품질, 규칙에서 선택한 그룹을 의심해야 합니다. Clash 로그에서 DNS 조회 기록과 연결 기록을 시간 순서대로 비교하면 어느 단계에서 멈췄는지 파악하기 쉽습니다.

1. Clash Verge 로그에서 인증을 시작한 시각의 요청을 찾고, accounts.google.com 또는 API 관련 호스트가 기록되는지 확인합니다.
2. 요청이 DIRECT로 표시되면 규칙 순서와 터미널의 프록시 변수 적용 여부를 확인합니다.
3. 요청이 프록시 그룹으로 갔지만 시간 초과되면 다른 노드를 선택해 같은 명령을 반복합니다.
4. TUN 사용 중에 로컬 콜백이 실패하면 NO_PROXY와 Fake-IP 예외 설정을 확인합니다.
5. 브라우저 인증만 반복되면 기존 인증 세션이나 캐시를 지우기 전에 CLI가 요구하는 로그아웃·재인증 절차를 먼저 따릅니다.

노드 테스트 결과가 계속 달라진다면 자동 선택 그룹의 URL Test 결과만 보고 판단하지 마세요. 짧은 테스트 요청의 지연 시간이 낮아도 API 요청에서 패킷 손실이나 TLS 재전송이 발생할 수 있습니다. 같은 노드로 인증 페이지, 짧은 API 요청, 실제 코드 생성 요청을 각각 실행해 결과를 비교하면 단순 지연과 실제 사용 품질을 구분할 수 있습니다.

안정적인 AI 개발 환경을 유지하는 운영 방법

설정이 끝난 뒤에도 매번 전체 네트워크를 무작정 프록시로 보내기보다는, 목적에 따라 구성을 나누는 것이 관리하기 쉽습니다. 개인 프로젝트에서는 터미널 세션에만 환경 변수를 적용하고, 브라우저나 다른 도구는 시스템 프록시를 사용하게 둘 수 있습니다. 여러 프로젝트에서 같은 설정을 쓴다면 셸 스크립트나 프로젝트별 실행 명령으로 프록시 변수를 묶되, 토큰과 비밀 키는 파일에 포함하지 않아야 합니다.

프로필 업데이트 후에는 사용자 규칙이 유지되는지 확인하세요. 구독 제공자가 전체 YAML을 교체하는 방식이면 수동 편집 내용이 사라질 수 있습니다. 이때는 Clash Verge가 제공하는 오버라이드·스크립트·확장 설정 기능을 사용하거나, 규칙을 재적용하기 쉬운 별도 템플릿으로 관리합니다. 설정을 변경할 때마다 한 번에 여러 항목을 바꾸지 말고, 시스템 프록시, TUN, DNS, 규칙을 하나씩 조정해야 원인 추적이 가능합니다.

터미널에서 사용할 최소 점검 목록은 다음과 같습니다.

• Clash Verge의 mihomo 코어가 실행 중이고 활성 프로필이 선택되어 있는가
• 선택한 노드가 HTTPS 연결을 반복해서 처리할 수 있는가
• 현재 터미널에 HTTP_PROXY와 HTTPS_PROXY가 올바른 포트로 설정되어 있는가
• NO_PROXY에 로컬호스트와 필요한 사설 주소가 포함되어 있는가
• Gemini 관련 요청이 Clash 로그에서 의도한 그룹으로 분류되는가
• 프로필 업데이트 뒤 사용자 규칙과 DNS 설정이 유지되는가

마지막으로 인증 성공을 곧바로 모든 기능의 정상 동작으로 해석해서는 안 됩니다. 로그인은 계정 도메인에 대한 연결만 확인할 수 있고, 실제 모델 요청에는 별도의 API 호스트와 권한 검사가 필요합니다. 인증 후 간단한 프롬프트와 작업 디렉터리 접근 테스트를 각각 실행하고, 실패 시 로그의 호스트·规则 결과·선택 노드를 함께 기록하면 다음 문제를 훨씬 빠르게 해결할 수 있습니다.