Gemini CLI를 Clash로 안정적으로 쓰는 설정 가이드

Gemini CLI에서 Clash가 필요한 상황

Gemini CLI는 터미널에서 Google 계정으로 로그인하고, 명령어 실행이나 코드 분석 요청을 원격 API로 전송하는 개발 도구입니다. 브라우저에서는 서비스가 정상적으로 열리는데 터미널에서만 로그인에 실패하거나, 인증 화면이 끝없이 반복되거나, 요청 도중 타임아웃이 발생한다면 계정 자체보다 네트워크 경로를 먼저 확인하는 편이 효율적입니다. 특히 회사 네트워크, 공용 Wi-Fi, 제한적인 DNS 환경에서는 브라우저와 CLI가 서로 다른 프록시 설정을 사용해 결과가 달라질 수 있습니다.

Clash를 사용하면 Gemini CLI의 요청을 별도 프록시 그룹으로 보내고, 나머지 국내 사이트나 사내 시스템은 기존 경로로 유지할 수 있습니다. 이 방식은 전체 트래픽을 무조건 프록시로 보내는 전역 모드보다 원인 파악이 쉽고, 불필요한 노드 사용량도 줄여 줍니다. 다만 Gemini CLI의 모든 요청이 하나의 고정된 도메인으로만 나가는 것은 아닙니다. 로그인 단계에서는 계정·OAuth 관련 주소가 사용되고, 실제 모델 요청은 Gemini API나 Code Assist 관련 엔드포인트로 분리될 수 있으므로 규칙을 한 줄만 추가해서 해결된다고 단정하면 안 됩니다.

• 로그인 실패: 브라우저 인증은 완료됐지만 CLI가 토큰을 받지 못하거나, 인증 URL을 열어도 콜백 단계에서 멈추는 경우입니다.
• 요청 시간 초과: 로그인 후 명령은 실행되지만 모델 응답이 오지 않거나 긴 요청에서 연결이 끊기는 경우입니다.
• 간헐적인 403·429: 네트워크 경로, 계정 권한, 프로젝트·쿼터 문제가 섞여 있을 수 있으므로 Clash만 바꾸기 전에 응답 코드와 로그를 함께 확인해야 합니다.

먼저 정할 것: 전역 모드와 규칙 분리

초기 진단에서는 Clash의 전역 모드를 잠시 사용해 볼 수 있습니다. 전역 모드에서 Gemini CLI가 정상적으로 로그인되고 응답한다면, 노드와 기본 연결은 작동하고 있으며 기존 규칙에 관련 도메인이 빠졌을 가능성이 높습니다. 반대로 전역 모드에서도 같은 오류가 발생한다면 DNS, 인증 단계, 노드 품질 또는 계정 권한을 함께 조사해야 합니다.

평소 사용에는 규칙 분리가 적합합니다. Gemini CLI 전용 정책 그룹을 만들고, 계정 인증 및 API 관련 도메인을 이 그룹으로 보낸 뒤 마지막에는 기존 기본 정책을 유지합니다. 아래 표는 시작점으로 사용할 수 있는 분류입니다. 서비스의 엔드포인트는 버전과 로그인 방식에 따라 바뀔 수 있으므로, 실제 Clash 로그에 나타난 호스트를 기준으로 보완해야 합니다.

도메인 규칙은 IP 규칙보다 앞에 배치하는 것이 안전합니다. DOMAIN-SUFFIX,googleapis.com,Gemini-CLI처럼 넓은 규칙을 사용하면 관련 API를 빠르게 포함할 수 있지만, Google의 모든 서비스가 같은 정책으로 이동할 수 있습니다. 처음에는 로그에서 확인한 정확한 호스트를 DOMAIN으로 추가하고, 반복적으로 나타나는 하위 도메인만 DOMAIN-SUFFIX로 묶는 방식이 좋습니다.

Clash에 Gemini CLI 전용 정책 추가하기

아래 예시는 mihomo 계열 커널을 사용하는 Clash 클라이언트를 기준으로 한 기본 구조입니다. 실제 구독 프로필에 이미 같은 이름의 프록시 그룹이나 규칙이 있다면 이름을 바꾸고, 노드 이름은 자신의 구독에 표시되는 값으로 교체해야 합니다. 설정 파일 전체를 무작정 덮어쓰기보다 기존 proxy-groups와 rules의 위치를 확인한 뒤 필요한 부분만 추가하세요.

proxy-groups:
  - name: Gemini-CLI
    type: select
    proxies:
      - 자동选择
      - 节点名称
      - DIRECT

rules:
  - DOMAIN,accounts.google.com,Gemini-CLI
  - DOMAIN,oauth2.googleapis.com,Gemini-CLI
  - DOMAIN,generativelanguage.googleapis.com,Gemini-CLI
  - DOMAIN-SUFFIX,googleapis.com,Gemini-CLI
  - MATCH,기존 기본 정책

이 예시의 DIRECT는 진단용 선택지입니다. 로그인 단계가 프록시 없이도 정상이라면 계정 인증 도메인만 직접 연결하고 API 요청만 프록시로 보내는 구성을 시험할 수 있습니다. 반대로 로그인 페이지가 열리지 않거나 토큰 교환에서 실패한다면 인증 관련 도메인도 같은 정책 그룹으로 보내야 합니다. MATCH는 반드시 규칙 목록의 마지막에 두어야 하며, 그 아래에 규칙을 추가하면 해당 규칙은 실행되지 않습니다.

1. Clash Verge, Clash Verge Rev 또는 사용하는 클라이언트에서 현재 프로필을 백업합니다. 구독 갱신으로 수동 편집 내용이 사라질 수 있으므로, 가능하면 오버라이드 또는 확장 설정 기능을 사용합니다.
2. 정책 그룹에 Gemini-CLI를 추가하고, 연결이 안정적인 노드를 하나 선택합니다. 자동 테스트 그룹을 사용할 때는 지연시간만 낮고 실제 API 요청이 실패하는 노드가 선택되지 않는지 확인합니다.
3. 계정 로그인, OAuth 토큰, API 엔드포인트에 해당하는 규칙을 MATCH보다 위에 넣습니다. 구독 제공자가 이미 Google 관련 규칙을 제공한다면 중복 규칙의 위아래 순서를 먼저 확인합니다.
4. 프로필을 저장하고 적용한 뒤 시스템 프록시 또는 TUN을 켭니다. 터미널 프로그램은 시스템 프록시를 자동으로 따르지 않을 수 있으므로, TUN을 사용하는 편이 확인 절차에서는 더 단순합니다.
5. Clash의 로그를 열어 Gemini CLI를 실행하고, 실제로 어떤 호스트가 Gemini-CLI 그룹으로 매칭되는지 확인합니다. 로그에 나타난 호스트가 누락되었다면 그 호스트를 정확한 도메인 규칙으로 추가합니다.

DNS와 TUN을 함께 점검하는 방법

Gemini CLI의 로그인 실패는 프록시 노드 문제처럼 보이지만 실제로는 도메인 해석 실패에서 시작되는 경우가 많습니다. Clash의 로그에 연결 시도가 전혀 나타나지 않고 터미널에서 호스트를 찾을 수 없다는 메시지가 나온다면, 먼저 DNS가 Clash를 통과하는지 확인해야 합니다. 시스템 프록시만 켠 상태에서는 터미널 프로세스와 DNS 요청이 모두 프록시 설정을 따르지 않을 수 있습니다.

데스크톱에서는 TUN 모드를 켜고 auto-route와 dns-hijack이 활성화되어 있는지 확인하세요. TUN은 가상 네트워크 인터페이스로 애플리케이션의 연결을 인수하며, DNS 하이재킹은 시스템이 보내는 일반적인 53번 포트 질의를 Clash DNS로 넘기는 역할을 합니다. 운영체제 권한 요청을 거부했거나 다른 VPN 프로그램이 가상 인터페이스를 먼저 차지하면 TUN이 켜진 것처럼 보여도 실제 트래픽이 우회할 수 있습니다.

fake-ip 모드를 사용하는 경우 터미널에서 반환되는 주소가 198.18.0.0/16 대역일 수 있습니다. 이는 인터넷의 실제 서버 주소가 아니라 Clash가 도메인과 연결하기 위해 만든 가상 주소입니다. 애플리케이션이 이 주소로 접속할 때 Clash가 원래 도메인을 찾아 규칙을 적용하므로, fake-ip 결과만 보고 DNS 오류라고 판단하면 안 됩니다. 다만 특정 CLI 버전이나 인증 라이브러리가 fake-ip와 호환되지 않는다면 해당 도메인을 fake-ip-filter에 추가하거나 일시적으로 redir-host로 바꿔 비교할 수 있습니다.

• Windows에서는 nslookup accounts.google.com과 ipconfig /all로 DNS 응답과 적용된 서버를 확인합니다.
• macOS에서는 scutil --dns를 실행하고, Clash DNS 리스너와 시스템 DNS 우선순위를 비교합니다.
• Linux에서는 resolvectl status와 resolvectl query accounts.google.com으로 현재 해석 경로를 확인합니다.
• 모든 플랫폼에서 Clash 로그에 DNS 요청과 연결 요청이 기록되는지 함께 확인해야 합니다.

로그인 실패와 타임아웃을 나누어 해결하기

문제를 해결할 때는 한 번에 여러 설정을 바꾸지 말고, 같은 노드와 같은 명령으로 변경 전후를 비교하세요. 먼저 Clash를 완전히 끈 상태, 시스템 프록시만 켠 상태, TUN과 규칙 분리를 켠 상태를 각각 시험하면 어느 계층에서 실패하는지 좁힐 수 있습니다. 테스트 과정에서 계정 비밀번호나 인증 토큰이 포함된 명령 출력은 저장하거나 공유하지 마세요.

로그에 DIRECT로 표시되는 항목이 있다면 규칙 순서를 다시 보세요. 넓은 DOMAIN-SUFFIX,google.com,DIRECT 같은 규칙이 앞에 있으면 계정과 API 요청이 모두 직접 연결될 수 있습니다. 반대로 모든 Google 트래픽을 프록시로 보내면 검색, 동기화, 다른 개발 도구까지 같은 노드를 사용하게 되므로 필요한 호스트만 좁히는 것이 장기적으로 안정적입니다.

노드 변경은 마지막 비교 수단으로 사용하세요. 같은 노드에서 브라우저의 계정 로그인과 CLI의 API 요청이 모두 실패한다면 네트워크 또는 노드 문제일 가능성이 높고, 브라우저는 성공하지만 CLI만 실패한다면 CLI의 프록시 인식 방식, 로컬 콜백, 환경 변수, 인증 캐시를 확인해야 합니다. 반대로 API 요청은 성공하지만 특정 모델 호출만 거부된다면 Clash 규칙보다 계정 플랜이나 프로젝트 권한을 확인하는 편이 맞습니다.

업데이트 후에도 유지되는 관리 원칙

Gemini CLI와 mihomo 커널은 함께 고정된 제품이 아니므로 업데이트 후 요청 호스트, 인증 방식, 설정 항목이 달라질 수 있습니다. 구독 프로필을 갱신한 뒤 갑자기 로그인에 실패하면 먼저 수동 규칙이 사라졌는지, 정책 그룹 이름이 바뀌었는지, 새로운 호스트가 MATCH에 걸리는지 확인하세요. 클라이언트 정보 화면에서 커널이 원조 Clash인지 mihomo인지도 확인해야 합니다. GEOSITE, TUN, 최신 DNS 옵션은 커널에 따라 지원 범위가 다를 수 있습니다.

• 작동하는 프로필을 별도 이름으로 저장하고, 변경할 때마다 한 항목씩 수정합니다.
• 규칙은 MATCH보다 위에 두며, 넓은 Google 규칙이 앞에서 다른 서비스까지 가로채지 않는지 확인합니다.
• 로그에는 호스트와 정책 결과만 남기고, 인증 헤더·토큰·개인 이메일이 보이는 화면은 공유하지 않습니다.
• 전역 모드는 진단용으로만 사용하고, 정상 확인 후에는 Gemini CLI 관련 규칙 분리로 되돌립니다.
• TUN과 다른 VPN, 회사 보안 에이전트, 브라우저 내장 프록시를 동시에 사용하지 않아 경로 충돌을 줄입니다.

가장 안정적인 기본 순서는 계정과 OAuth 도메인을 먼저 확인하고, 실제 API 호스트를 로그에서 추가한 뒤, DNS와 TUN을 검증하고, 마지막으로 노드와 쿼터 문제를 분리하는 것입니다. 이 순서를 지키면 로그인 실패를 API 권한 문제로 오해하거나, 단순한 DNS 오류 때문에 프로필 전체를 다시 만드는 일을 줄일 수 있습니다.

준비가 끝났다면 다음 단계

Gemini CLI에 필요한 트래픽만 별도 정책으로 보내고 싶다면 먼저 현재 클라이언트의 로그와 커널 종류를 확인하세요. 그 다음 예시 규칙을 그대로 복사하기보다 실제로 나타난 호스트를 기준으로 최소 규칙을 구성하고, 짧은 요청과 긴 요청을 모두 시험하는 것이 좋습니다. Clash를 아직 설치하지 않았다면 다운로드 센터에서 사용하는 운영체제에 맞는 클라이언트를 선택한 뒤, 프로필 가져오기와 시스템 프록시·TUN 설정을 순서대로 진행할 수 있습니다.