Gemini CLI npm 분기법

1. 브라우저 Gemini 글과 CLI 시나리오 차이

이 사이트의 Gemini 웹·QUIC 분기 글은 주로 크롬·엣지가 HTTP/3로 우회하면서 패킷 출구와 지역 신호가 흔들릴 때를 다룹니다. 반면 Gemini CLI는 Node·Python 래퍼·쉘 alias가 같은 프로세스 트리에서 HTTPS 스트림을 길게 열어 두고, 옆에서는 npx가 npm 메타데이터와 tarball을 순차적으로 긁습니다. 즉 검색 의도 자체가 「브라우저만 열어도 되는지」보다 「개발 명령줄에서 패키지·플러그인 다운로드까지 한 번에 막히지 않게」에 가깝습니다.

Claude Code나 MCP 도구 연동 글과 결이 비슷하지만, Google 측은 OAuth·토큰 엔드포인트와 generativelanguage·CLI 배포 페이지가 교차하기도 하므로 레퍼런스 세트에서 Anthropic 버전 글 그대로를 복사해 붙이면 오탐이 늘 수 있습니다. 항상 라이브 로그로 호스트 접두사를 줄여 가며 맞춥니다.

2. 터미널에서 나타나는 단계별 증상 패턴

사용자가 검색 창에 타임아웃만 입력해 들어오는 경우가 많은데, 실제로는 TLS 핸드셰이크 초반에서 끊기는 경우와 패키지 tar 스트림 중간에서 대역폭 없이 헤더만 도는 경우가 다릅니다. 전자는 종종 노드 품질·SNI 처리·중간 회선과 연관되고, 후자는 레지스트리와 CDN 출구 불일치, 혹은 npm 쪽 중복 프록시가 겹치는 경우가 많습니다.

DNS 관점에서는 시스템이 IPv6 우선이라 AAAA 레코드를 먼저 시도했다가 회사 방화벽 구간에서 막히는 패턴도 흔합니다. 이때는 Clash 규칙만 손본다고 해결되지 않고, 호스트 이름 그대로 다른 경로에서 해석된다는 신호까지 같이 봐야 합니다. 따라서 증상을 한 줄로 단정하지 말고 로그 줄에 적힌 목적 호스트명을 먼저 확정합니다.

메모

Gemini CLI는 모델 API와 패키지 인덱스를 동시에 건드리므로, 단일 GEOIP 규칙으로는 한쪽만 들어맞는 체감이 생기기 쉽습니다. 문제 구간별로 규칙 조각을 쌓는 편이 낫습니다.

3. 규칙 후보: Google AI·npm·패키지 CDN

Google 계열 이름은 업데이트될 때마다 전면이 바뀌므로 여기 목록은 시작점입니다. 실제 라이브 구성에서는 OAuth·토큰·문서 페이지가 같은 정책 그룹에 있어야 CLI가 깨지지 않는지 교차 검증해야 합니다. 일반적으로 *.googleapis.com, oauth2.googleapis.com, accounts.google.com, generative API가 붙는 generativelanguage.googleapis.com, 그리고 CLI 배포·문서 호스트까지 로그에서 한 번 더 읽어보세요.

npm 레이어에서는 최소한 registry.npmjs.org를 포함하고, tarball이 다른 접미사(npmjs.org 패밀리)를 쓸 때는 해당 접미사를 DOMAIN-SUFFIX로 따라갑니다. 사내 레지스트리 미러나 지역 거울(registry.npmmirror.com 등)을 쓴다면 그 호스트만 별도 정책으로 분리해 범위를 좁히는 편이 오탐을 줄입니다. Windows npm 프록시 글의 npm config list 절차와도 맞물립니다.

Google AI API

인증 교환과 실제 호출이 다른 호스트에 흩어질 수 있습니다. 규칙을 한 그룹에 묶더라도 로그 줄에서 순서 확인이 필요합니다.

npm registry

npm config get registry 값이 기본이 아니라면 그 URL의 호스트를 최우선으로 규칙에 포함하세요.

4. 환경 변수·npm 레지스트리와의 정렬

macOS·Linux·Windows WSL에서는 HTTP_PROXY·HTTPS_PROXY를 Clash의 mixed-port에 맞추는 패턴이 가장 많이 씁니다. PowerShell처럼 네이티브 윈도 셸이라면 회사 네트워크 스택이 별도로 TLS 가로채기를 하는지도 확인하세요. npm config set proxy를 수동으로 건드린 기록이 있으면, CLI 전용 새 셸에서 기본 상태로 초기화한 뒤 대조 실험을 하는 것이 좋습니다.

TUN 모드로 전송층부터 잡아 올리면 환경 변수 의존도는 줄지만, 게임처럼 UWP나 루프백 예외가 필요한 앱에서는 여전히 예외 처리가 들어갑니다. 같은 이유로 Docker Hub 레지스트리 글처럼 대용량 pull을 다룰 때 등장했던 교훈, 즉 “규칙은 맞는데 애플리케이션이 다른 출구를 탄다”는 문제를 CLI에서도 재확인하는 것이 중요합니다.

5. mihomo rules 스니펫과 우선순위

예시 그룹명을 🔷 Gemini-Dev-Google-Npm으로 두었습니다. 구독에 맞게 바꾸고, MATCH보다 반드시 위쪽에 둡니다. 세부 순서 고민은 고급 라우팅을 함께 보세요.

rules:
  # Gemini CLI-ish: widen from live logs, avoid over-broad keywords
  - DOMAIN-SUFFIX,googleapis.com,🔷 Gemini-Dev-Google-Npm
  - DOMAIN-SUFFIX,clients6.google.com,🔷 Gemini-Dev-Google-Npm
  - DOMAIN-SUFFIX,accounts.google.com,🔷 Gemini-Dev-Google-Npm
  - DOMAIN-SUFFIX,registry.npmjs.org,🔷 Gemini-Dev-Google-Npm
  - DOMAIN-SUFFIX,npmjs.org,🔷 Gemini-Dev-Google-Npm
  - DOMAIN-SUFFIX,google.com,🔷 Gemini-Dev-Google-Npm
  # Optional: oauth/docs hosts seen in traces — add explicitly

  # ... LAN / CN direct paths, then GEOIP/MATCH fallbacks ...
  - GEOIP,PRIVATE,DIRECT
  - MATCH,🔰 Proxy

google.com 접미 규칙은 범위가 넓습니다. 일반 브라우징까지 같은 그룹으로 끌고 가고 싶지 않으면 더 구체적인 FQDN을 로그 기반으로 쪼개고, 이 줄은 테스트 후 제거합니다. 패턴 복사는 항상 “로그 확정 호스트부터”입니다.

6. DNS·Fake-IP·보안 DNS 충돌 줄이기

Clash Meta의 fake-ip는 규칙 매칭을 단순하게 만들지만, 터미널 실행 파일이 systemd-resolved 같은 로컬 스텁과 직접 대화하면 코어 바깥에서 먼저 응답을 받습니다. 결과적으로 DOMAIN 규칙이 존재해도 실제 패킷은 다른 ASN으로 나가는 착시가 생길 수 있습니다. fake-ip와 redir-host 비교 글로 모드를 한 번 재점검하세요.

# Sketch — choose resolvers compliant with your org policy
dns:
  nameserver-policy:
    "+.googleapis.com":
      - https://dns.google/dns-query
    "+.npmjs.org":
      - tls://dns.quad9.net

브라우저 보안 DNS·기업 에이전트가 동시에 켜져 있으면, 이중 해석 때문에 CLI만 지연처럼 보일 수 있습니다. 윈도우 보안 DNS 가이드를 함께 보고 테스트 창에서는 잠시 비교 실험을 해도 됩니다.

참고: 업스트림 DNS 주소는 감사·필터 정책에 맞게 고르세요. 예시 블록은 형식 안내일 뿐 하드코딩용이 아닙니다.

7. 정책 그룹: 노드 흔들림과 장시간 세션

Gemini CLI처럼 응답을 스트리밍 받는 명령은 짧은 지연마다 url-test가 노드를 바꾸면 중간 재연결 비용이 눈에 띄게 커질 수 있습니다. 전용 그룹 안에서는 지연 자동 테스트보다 사용자 지정 순서형 fallback 또는 수동 선택을 함께 검토합니다. 패턴 선택은 지연 테스트·fallback 글을 참고하세요.

동시에 레지스트리는 대량의 작은 HTTPS 요청이 연속 발생합니다. API와 같은 노드 이름을 공유하면 한쪽 회선 차단이 다른 쪽 체감까지 끌고 올 수 있으니, 트래픽 성격이 완전히 다르면 그룹을 쪼개는 것도 방법입니다. 다만 그룹이 너무 많아지면 유지보수 비용이 커지므로 로그에서 실제 병목 호스트를 본 뒤 결정합니다.

8. 로그 기반 실측 체크리스트

첫째, 문제가 나는 서브커맨드를 동일 인자로 재현하고 mihomo 로그에서 실패 줄의 도메인과 아웃바운드 이름이 기대한 정책 그룹인지 확인합니다. 둘째, Proxies 탭에서 그룹이 실제로 어떤 노드를 가리키는지 스냅샷을 남깁니다. 셋째, 동일 셸에서 env | grep -i proxy류 명령으로 프록시 변수만 바꿔 A/B 비교합니다. 넷째, DNS 모드·TUN on/off·IPv6 on/off를 한 번씩만 바꿔 증상이 따라오는지 봅니다.

TLS 단계에서 멈출 때

SNI·중간 인증서·회사 SSL 검사 장비를 의심하고, 순수 브라우저와 같은 호스트명을 openssl s_client로 재현합니다.

다운로드 중간 멈춤

패키지 본체가 다른 접미 호스트면 메타 규칙만 맞았다고 끝나지 않습니다. tarball 줄까지 로그에 찍히는지 확인합니다.

전반적인 분기 개념을 다시 보고 싶다면 Clash 개요를 참고하면 흐름이 정리됩니다.

9. 자주 묻는 질문

브라우저 Gemini는 되는데 터미널 Gemini CLI만 느릴 때는?

브라우저는 시스템 프록시·HTTP/3(QUIC) 경로와 별개로 종료되고, 터미널은 HTTP_PROXY 미설정·IPv6 우선·레지스트리 직결 등으로 같은 정책 그룹을 타지 않을 수 있습니다. 터미널 프록시 변수와 mihomo 연결 로그를 함께 보세요.

npm install만 멈추고 Gemini API는 살아 있을 때는?

registry 메타 요청과 tarball CDN 호스트가 서로 다른 정책 그룹으로 나가면 패키지 수만 건 단계 중간에서 끊긴 것처럼 보입니다. npm config get registry 실제 호스트와 로그 도메인을 맞춰 규칙을 나눕니다.

Fake-IP를 쓰면 왜 규칙이 안 먹는 것처럼 보이나요?

앱이나 OS가 코어 바깥에서 먼저 DNS를 해석하면 Clash 규칙과 실제 접속 목적지가 어긋날 수 있습니다. redir-host·nameserver-policy·브라우저 보안 DNS를 함께 점검하세요.

VPN만 켠 채 브라우저만 보호하는 타입과 달리, Clash·mihomo 계열은 Gemini CLI처럼 호스트가 수십 줄로 찢어진 개발 워크플로에 특히 유리합니다. 호스트별 정책을 YAML로 명시할 수 없거나 GUI에서 로그·DNS·토글을 묶어보기 어렵다면, 레지스트리와 Google AI를 동시에 맞추는 반복 수정이 피곤해집니다. 반면 규칙 우선순위·패널 하나로 실패 줄을 따라가며 조각 규칙을 쌓을 수 있는 제품이라면 증상이 나뉘어 보이던 TLS·패키지 지연도 같은 테이블에서 정리됩니다.

→ Clash를 무료로 받아 최신 클라이언트와 함께 Google·npm 두 축을 동시에 점검하고, 명령줄 타임아웃을 줄이는 규칙 세트를 천천히 다듬어 보세요.