증상: Gemini CLI에서 무엇이 동시에 끊기나
터미널에서 Gemini CLI를 돌리다 보면 증상이 “한 덩어리 타임아웃”처럼 보이지만, 실제로는 여러 TLS SNI가 같은 세션에 겹쳐 있습니다. 첫째, 초기 설치나 업데이트 때 큰 아티팩트나 구성을 받아 오는 모델·런타임 다운로드 축이 있고, 둘째, 계정을 열 때 뜨는 OAuth·브라우저 콜백 축이 있으며, 셋째, 프롬프트 이후 토큰을 스트리밍하는 Google AI API 축이 있습니다. 여기에 개발자 워크플로가 섞이면 넷째로 npm install·corepack 같은 npm 레지스트리 축, 다섯째로 git fetch·릴리스 자산을 받는 GitHub CDN 축이 같은 창에서 동시에 열립니다.
사용자 입장에서는 “어제는 됐는데 오늘은 중간에 멈춘다”처럼 보여 원인 설명이 어렵습니다. 그러나 네트워크 관점에서는 한 줄짜리 전역 프록시 설정이 모든 호스트에 같은 RTT·세션 한도를 강제하지 못하는 경우가 많습니다. 특히 Google AI API 분류와 패키지 레지스트리, git 호스트는 실패 패턴이 달라서 Gemini CLI 프록시 문제라고 한마디로 묶기 어렵습니다.
이미 사내 HTTP 프록시, ZTNA, 분할 터널 VPN이 있는 노트북이라면 Clash 경로와 충돌할 수 있습니다. 그런 환경에서도 손댈 수 있는 레이어는 보통 규칙 스택 상단의 광역 DIRECT·GEOIP, DNS 모드, 그리고 rule hit 로그입니다. 본문은 관할법·고용 계약·조직 보안 정책·Google·GitHub·npm 약관을 지키는 범위에서만 적용한다는 전제를 둡니다.
왜 Google AI·npm·GitHub를 한 줄에 못 묶나
HTTPS_PROXY 하나로 모든 서브프로세스를 밀어 넣는 방식은 빠른 실험에는 편하지만, Gemini CLI는 서로 다른 상호작용 패턴을 동시에 만듭니다. OAuth 단계는 짧은 브스트가 많고, 스트리밍 API는 긴 연결과 주기적 ping에 민감하며, npm은 수백 개의 작은 객체 GET과 리다이렉트 체인을 밟습니다. GitHub는 github.com, api.github.com, raw.githubusercontent.com, 릴리스 첨부가 놓인 객체 스토리지 호스트까지 갈라집니다.
범용 VPN이나 전역 토글만 있는 클라이언트는 호스트 단위 설명이 부족해 “빠른 노드로 바꿨는데도 npm만 실패” 같은 표현을 남깁니다. 반면 Mihomo·Clash 계열은 proxy-group과 DOMAIN 규칙으로 출구를 분리해 Gemini CLI Clash 검색으로 들어온 사용자가 기대하는 수준의 세부 제어를 코드로 남길 수 있습니다. 에디터형 에이전트에 익숙하다면 Cursor 3 API 분리 글의 “모델·툴체인 출구 나누기”와 병렬로 읽어도 사고방식이 이어집니다. 터미널 러너 전반이 궁금하다면 OpenClaw·Verge Rev 분류 글의 단계적 디버깅 순서를 함께 참고하세요.
멀티 프로바이더 API를 한꺼번에 쓰는 팀이라면 OpenRouter 분리 글의 “API·CDN·툴체인” 축 개념을 MODEL 레이어 레퍼런스로 가져올 수 있습니다. 다만 Gemini 전용 호스트 문자열은 릴리스와 리전에 따라 달라지므로, 예시 YAML을 그대로 복사하지 말고 본인 Clash Verge Rev 연결 목록의 Host를 기준으로 다시 써야 합니다.
축 설계: GOOGLE-AI-GEMINI·NPM·GITHUB-CDN
정책 이름은 팀 컨벤션을 따르되, 로그에 그대로 노출될 문자열이 읽히게 세 덩어리로 시작하는 것이 좋습니다.
- GOOGLE-AI-GEMINI(OAuth·API·아티팩트): 브라우저 기반 인증, Generative Language API나 Vertex를 향하는 엔드포인트, 큰 바이너리나 구성을 받는 호스트가 한 묶음으로 보일 수 있어 Verge Rev에서 먼저 Host 샘플을 모읍니다.
googleapis.com,google.dev, 계정·쿠키와 붙는google.com계열이 섞일 수 있습니다. - NPM-REGISTRY(패키지·미러·GitHub Packages):
registry.npmjs.org, 사내 Verdaccio, 스코프 미러,npm.pkg.github.com처럼 lockfile이 바뀔 때마다 달라지는 이름까지 포함합니다. - GITHUB-CDN(git·API·raw·릴리스): 저장소 HTML, REST, Raw, release asset이 서로 다른 접미사를 가질 수 있으니 실패 시각의 Host를 규칙에 직접 옮깁니다.
DOMAIN-KEYWORD,google처럼 지나치게 넓은 한 줄은 사내 문서·모니터링까지 끌어와 오탐을 키웁니다. 초기에는 DOMAIN-SUFFIX를 쓰고, 반복적으로 보이는 접미사만 덧붙이세요. Rule Provider 병합 순서가 있는 팀 레포라면 상단에 로컬 덮어쓰기 블록을 두는지도 함께 확인합니다.
코워킹 공간에서 GitHub·npm를 동시에 쓰는 패턴은 Anthropic Cowork 분리 글과 겹치는 부분이 많습니다. 재사용할 때도 호스트 목록은 반드시 최신 연결 로그로 다시 검증해야 합니다.
YAML 출발점: proxy-group과 규칙 예시
아래는 교육용 스켈레톤입니다. 프로필 하단의 넓은 MATCH, 상단의 GEOIP·국내 직결 블록보다 먼저 오는지, 사용자 정의 줄이 실제로 호출되는지 rule hit로 증명하세요.
# Example — replace suffixes with hosts captured in Verge Rev logs
proxy-groups:
- name: GOOGLE-AI-GEMINI
type: select
proxies:
- ♻️ Auto
- 🇸🇬 Low-latency
- DIRECT
- name: NPM-REGISTRY
type: select
proxies:
- 🌐 Global-egress
- ♻️ Auto
- DIRECT
- name: GITHUB-CDN
type: select
proxies:
- 🌐 Global-egress
- ♻️ Auto
- DIRECT
rules:
- DOMAIN-SUFFIX,googleapis.com,GOOGLE-AI-GEMINI
- DOMAIN-SUFFIX,google.dev,GOOGLE-AI-GEMINI
- DOMAIN-SUFFIX,registry.npmjs.org,NPM-REGISTRY
- DOMAIN-SUFFIX,npm.pkg.github.com,NPM-REGISTRY
- DOMAIN-SUFFIX,github.com,GITHUB-CDN
- DOMAIN-SUFFIX,api.github.com,GITHUB-CDN
- DOMAIN-SUFFIX,raw.githubusercontent.com,GITHUB-CDN
# Append OAuth/callback hosts you observed above broad DIRECT / GEOIP blocks
# Add object storage hosts for GitHub releases if your log shows separate SNIs
실제 CLI 릴리스가 붙는 이름은 업데이트 때마다 달라질 수 있습니다. 스테이징 프로필에서 안정적으로 rule hit가 찍히는 패턴을 찾은 뒤 일상 프로필로 옮기면 업무 네트워크를 덜 흔듭니다.
규칙 우선순위와 DIRECT 오매칭
Gemini CLI 증상이 간헐적이라면 실패한 순간의 rule hit 한 줄이 출발점입니다. “국내 도메인 전부 DIRECT” 같은 초광역 규칙이 위에 있으면 방금 추가한 GOOGLE-AI 줄이 아예 실행되지 않습니다. 반대로 모든 HTTPS를 한 노드에 몰면 패키지와 릴리스 CDN까지 먼 경로를 돌아 지연만 커질 수 있어, npm GitHub CDN Clash 튜토리얼을 찾는 사람들이 흔히 겪는 후자 문제도 동시에 피해야 합니다.
우선순위를 손볼 때는 이름을 길게 늘리는 대신 로그로 매칭 순서를 증명하는 습관이 중요합니다. 팀마다 GEOIP 블록 위치가 다르면 같은 YAML이라도 결과가 달라집니다.
환경 변수·셸 세션과 npm
Node·npm은 HTTP_PROXY·HTTPS_PROXY·ALL_PROXY 해석이 버전·번들러에 따라 미묘하게 다릅니다. Clash TUN이 애플리케이션 트래픽을 잡더라도 일부 서브프로세스는 환경 변수를 따로 읽습니다. 동일 창에서 npm config get proxy와 셸 변수를 동시에 점검하고, 회사 레지스트리로 고정하는 .npmrc가 다른 출구를 강제하지 않는지 확인하세요.
스트리밍 API와 패키지 다운로드는 RTT와 패킷 손실에 반응이 다릅니다. 짧은 타임아웃을 CLI 쪽 옵션으로 두었다면 네트워크만 바꿔서는 재발할 수 있어, 우선 Clash 정책에서 축이 섞이지 않았는지 먼저 고정하는 편이 빠릅니다.
DNS·fake-ip·TUN/시스템 프록시 교차점
fake-ip 프로필에서 코어가 돌려 준 주소와 OS가 본 주소가 어긋나면 같은 터미널 탭이라도 하위 프로세스마다 출구가 갈라집니다. redir-host로 바꿨을 때 재현이 사라지는지, fake-ip-filter에 레지스트리·Git 호스트를 넣어야 하는지 단계적으로 비교하세요.
TUN과 시스템 프록시를 동시에 켜면 경로가 이중으로 겹칠 수 있습니다. 장시간 세션을 유지하는 CLI는 그 차이가 터미널에만 드러나는 경우도 있어, 초기 설치 절차는 Windows 11 Verge Rev 설치 글의 시스템 프록시 설명과 함께 읽으면 전체 그림이 잡힙니다. 트래픽 패널 사용법은 Verge Rev 통계 글과 연결됩니다.
브라우저 OAuth 창은 스트리밍 파이프와 DNS 캐시가 다른 레이어일 수 있습니다. 모델 호출은 되는데 로그인만 실패한다면 브라우저 프로세스가 붙은 정책 이름을 별도로 확인하세요.
자가 점검 절차
아래 순서를 이슈 템플릿에 붙여 두면 “CLI만 끊긴다”는 모호한 제목이 Host·정책 문자열이 적힌 로그로 바뀝니다.
- 타임아웃 직전 터미널에 찍힌 명령과 시각을 저장하고, Verge Rev 연결 목록에서 대응하는 Host 문자열을 내보냅니다.
- 같은 시각 rule hit 한 줄로 어떤 정책 그룹에 매칭됐는지 확인합니다.
GOOGLE-AI-GEMINI·NPM-REGISTRY·GITHUB-CDN에 서로 다른 노드를 임시로 지정해 증상이 어느 축에서 줄어드는지 봅니다.- DNS 모드·업스트림 DoH·
fake-ip-filter를 바꿔 재현이 유지되는지 비교합니다. - 사내 프록시·SSL 가시성·분할 VPN과 Clash가 동시에 개입하지 않는지 OS 설정을 확인합니다.
- 인터페이스·라우팅 테이블에서 의도치 않은 IPv6 또는 스플릿 예외가 없는지 봅니다.
한 번 맞춰 둔 규칙을 영구 신뢰하지 말고, 분기 릴리스마다 연결 로그 샘플을 다시 모으세요. SaaS CLI는 호스트 문자열이 조용히 바뀌기도 합니다.
자주 묻는 질문
Q. 터미널 전역 HTTPS_PROXY만 켜면 Gemini CLI가 한 번에 해결되지 않나요?
A. 환경 변수 한 줄은 출발점이지만, Google OAuth·브라우저 콜백, gRPC/긴 스트림, npm·Git은 서로 다른 호스트·ALPN·타임아웃 성격을 가집니다. Clash 규칙으로 축을 나눠야 rule hit로 원인을 읽을 수 있습니다.
Q. Google AI API는 되는데 npm install만 느리면 무엇부터 보나요?
A. npm은 registry.npmjs.org 외에 기업 미러·GitHub Packages·tarball 리다이렉트까지 갈라집니다. 실패 시각의 Host를 연결 로그에서 복사해 NPM-REGISTRY 그룹에 붙였는지 확인하세요.
Q. Clash Verge Rev 없이 코어 YAML만으로 충분하지 않나요?
A. YAML만으로도 동작하지만, CLI 디버깅은 실시간 연결과 규칙 적중을 짧은 주기로 봐야 해서 Verge Rev가 피드백 루프를 줄여 줍니다.
정리
일부 범용 VPN이나 단일 토글 위주 클라이언트는 호스트 단위 정책과 장시간 스트림·다수 소용량 GET을 동시에 설명하기 어렵습니다. 그 결과 터미널에서 Gemini CLI를 돌릴 때 “노드만 갈아탄다”는 반복에 시간을 쓰게 되고, 실제로는 특정 npm GitHub CDN 경로만 DIRECT에 붙어 있던 사례를 놓치기 쉽습니다.
반면 Clash·Mihomo 계열은 proxy-group과 DOMAIN 규칙으로 Google AI API 분류와 패키지·git 축을 분리한 채 같은 로그 스트림에서 DNS와 rule hit까지 연속 점검할 수 있습니다. Clash Verge Rev를 함께 쓰면 연결·규칙 패널에서 반복 비교가 빨라져, 스트리밍 API와 OAuth, npm 패치가 한 세션에 섞인 복합 증상을 재현 가능한 Host 목록으로 바꾸기 쉽습니다.
클라이언트 출처를 먼저 정리한 뒤 이 글의 규칙을 얹고 싶다면 본 사이트 클라이언트 다운로드 페이지에서 플랫폼별 패키지를 확인해 주세요. 개념을 넓히려면 문서 허브의 고급 설정 파트를 이어 읽으면 흐름이 연결됩니다.
우선 경험부터 맞추고 싶다면 본 사이트 다운로드 페이지에서 클라를 받은 뒤, 위 절차로 Gemini 전용 프로필을 따로 두고 Verge Rev 로그와 함께 점검해 보시기 바랍니다.
→ 지금 무료로 Clash를 받아 Gemini CLI와 Google AI·npm·GitHub CDN 출구를 안정적으로 맞춰 보기