2026년 Gemini CLI가 터미널에서만 깨지는 이유

2026년 현재 Gemini CLI(@google/gemini-cli)는 무료 터미널 AI 에이전트로 빠르게 퍼지고 있습니다. npm install -g @google/gemini-cli로 설치한 뒤 OAuth 로그인, API 키 검증, 첫 모델 요청까지 한 번에 성공하는 경우도 많지만, 국내·회사망 개발 환경에서는 “브라우저 Gemini·AI Studio는 되는데 CLI만 멈춘다”는 패턴이 자주 보고됩니다.

겉보기 증상은 모두 Gemini CLI 타임아웃이지만, 실제 원인은 세 갈래로 나뉩니다. 첫째, npm 설치 단계에서 registry.npmjs.org·tarball CDN이 느리거나 DIRECT로 새는 경우입니다. 둘째, 터미널 OAuth가 accounts.google.com·oauth2.googleapis.com을 치는데, 이 호스트만 다른 프록시 그룹으로 갈라지면 인증 URL이 열리지 않거나 콜백이 끊깁니다. 셋째, 모델 호출이 generativelanguage.googleapis.com으로 가는데 CLI 프로세스가 Clash를 타지 않아 Google API 규칙이 적용되지 않는 경우입니다. 브라우저 중심 정리는 Gemini·AI Studio 분할 가이드에, 기업용 GCP·Vertex 축은 Gemini Enterprise 분할 가이드에 모아 두었습니다. 본문은 터미널 AI 프록시 관점에서 CLI만 집중합니다.

전제: 이 글은 합법적으로 프록시를 사용할 수 있는 환경에서 Clash·Mihomo 기술 설정을 다룹니다. 서비스 약관·회사 보안 정책을 위반하는 우회는 권장하지 않습니다.

npm 설치부터 막히는 경우: TOOLCHAIN 축

npm install -g @google/gemini-cli 실행 직후 ETIMEDOUT·ECONNRESET이 뜨면, 아직 Google API 문제가 아닐 수 있습니다. CLI 바이너리와 의존 패키지는 registry.npmjs.org·npmjs.org에서 내려받고, 일부 바이너리는 github.com·objects.githubusercontent.com 릴리스 CDN을 거칩니다. 구독 YAML에 GEOIP,KR,DIRECT가 넓게 깔려 있으면 메타데이터는 통과해도 tarball만 해외 노드로 가야 하는데 DIRECT에 묶이는 전형적인 npm 패턴이 그대로 재현됩니다.

이 구간은 npm 레지스트리·CDN 분할 글과 동일한 대응이 필요합니다. TOOLCHAIN 같은 전용 그룹을 두고 npm·GitHub 호스트를 API 축과 분리하면, “설치는 됐는데 gemini 명령만 실패”와 “설치 자체가 안 됨”을 빠르게 가릴 수 있습니다. 설치가 끝난 뒤에도 npm update -g @google/gemini-cli가 같은 경로를 쓰므로, TOOLCHAIN 규칙은 장기적으로 유지하는 편이 낫습니다.

호스트 묶음: OAuth·API·측정

설치 이후 Gemini CLI 세션에서 Clash 로그로 자주 보이는 축은 다음과 같습니다. API 호출의 중심은 generativelanguage.googleapis.com입니다. 공식 REST·SDK와 동일한 엔드포인트를 CLI가 사용하므로, AI Studio 분할 가이드의 API 줄을 그대로 차용할 수 있습니다. OAuth·브라우저 연동형 로그인에는 accounts.google.com·oauth2.googleapis.com·필요 시 www.googleapis.com 메타 요청이 붙습니다. 이 셋이 서로 다른 정책으로 나가면 “로그인 창은 떴는데 터미널로 돌아오지 않음”이 발생합니다.

API 키 모드(GEMINI_API_KEY 또는 GOOGLE_API_KEY)를 쓰는 경우에도 키 유효성 검증·모델 목록 조회는 동일 API 호스트로 향합니다. 추가로 CLI가 붙이는 측정·기능 플래그·문서 링크용 호스트는 버전마다 달라질 수 있으니, 한 번 성공한 세션 직후 로그를 캡처해 DOMAIN 한 줄씩 보강하는 습관이 중요합니다. DOMAIN-KEYWORD,google처럼 과하게 넓히면 YouTube·Drive 등 무관 트래픽까지 끌려와 디버깅이 어려워집니다.

모델 API: generativelanguage.googleapis.com
OAuth·계정: accounts.google.com, oauth2.googleapis.com, 필요 시 www.googleapis.com
문서·도움말: ai.google.dev, developers.google.com 일부 경로
패키지·업데이트: registry.npmjs.org, npmjs.org, github.com, githubusercontent.com

프록시 그룹: GEMINI_API·OAUTH·TOOLCHAIN

가장 단순한 모델은 GEMINI_API 하나에 Google API 트래픽을 몰아넣는 것입니다. 그러나 OAuth 브라우저 창과 장시간 스트리밍 응답, npm 대용량 다운로드는 요구 특성이 달라 세 그룹 분리가 실무에서 더 안정적입니다. GEMINI_API에는 지연이 낮은 노드만, OAUTH에는 로그인 세션과 동일 리전에 가까운 노드, TOOLCHAIN에는 대역이 넉넉한 노드를 배치하는 식입니다.

url-test의 프로브 URL은 https://generativelanguage.googleapis.com 또는 https://www.gstatic.com/generate_204처럼 실제 경로와 가까운 것을 고르세요. 헬스 체크만 통과하고 모델 호출만 끊기면, 프로브와 API가 다른 회선을 타는지 로그로 확인합니다. 그룹 이름은 구독 YAML에 실제 존재해야 하며, 규칙 튜닝의 기본기는 규칙 분할 가이드와 같습니다. 첫 일치 원칙을 잊지 말고, GEOIP,KR,DIRECT·거대 RULE-SET이 Gemini용 DOMAIN 줄보다 위에 있으면 의도가 무너집니다.

YAML 스케치: Gemini CLI용 규칙 발췌

아래는 개념 예시입니다. proxies 목록은 생략했으니 자기 구독에 맞게 채우고, 로그에 보인 호스트를 덧붙이세요.

YAMLproxy-groups:
  - name: "GEMINI_API"
    type: url-test
    url: "https://generativelanguage.googleapis.com"
    interval: 120
    tolerance: 40
    proxies:
      - DIRECT
      # ... 저지연 해외 노드 ...

  - name: "OAUTH"
    type: select
    proxies:
      - DIRECT
      # ... 로그인 세션에 맞는 노드 ...

  - name: "TOOLCHAIN"
    type: select
    proxies:
      - DIRECT
      # ... npm·GitHub용 안정 회선 ...

rules:
  - DOMAIN,generativelanguage.googleapis.com,GEMINI_API
  - DOMAIN,oauth2.googleapis.com,OAUTH
  - DOMAIN,accounts.google.com,OAUTH
  - DOMAIN-SUFFIX,ai.google.dev,GEMINI_API
  - DOMAIN-SUFFIX,npmjs.org,TOOLCHAIN
  - DOMAIN-SUFFIX,github.com,TOOLCHAIN
  - DOMAIN-SUFFIX,githubusercontent.com,TOOLCHAIN
  # ... GEOIP·MATCH 등 기존 프로필 순서 ...

운영을 단순화하려면 OAUTH와 GEMINI_API를 하나의 Gemini-All 그룹으로 합칠 수 있습니다. 다만 OAuth만 다른 노드로 실험하고 싶을 때는 분리가 유리합니다. DOMAIN-SUFFIX,googleapis.com 한 줄로 모든 Google API를 몰아넣는 방법도 있지만, 사내에서 BigQuery·Drive 등 다른 Google API를 국내 회선으로 두고 싶다면 CLI용 FQDN만 좁게 두는 편이 안전합니다.

터미널 프록시: 환경 변수·TUN·시스템 프록시

Gemini CLI Clash 조합에서 가장 흔한 실수는 “규칙은 맞는데 터미널이 안 탄다”입니다. macOS·Linux 터미널의 Node.js 프로세스는 시스템 프록시를 자동으로 물려 받지 않는 경우가 많습니다. Clash Verge Rev 등이 제공하는 터미널 환경 변수 주입을 쓰거나, 혼합 포트(예: 7890)에 맞춰 셸 프로필에 export HTTPS_PROXY=http://127.0.0.1:7890·export HTTP_PROXY=http://127.0.0.1:7890·export ALL_PROXY=socks5://127.0.0.1:7891를 넣습니다. NO_PROXY에 사내망·localhost 대역을 빼 두는 것도 잊지 마세요.

환경 변수만으로 빈틈이 남으면 TUN 모드가 다음 단계입니다. TUN은 애플리케이션이 프록시를 몰라도 커널 경로에서 잡아 오므로, 도메인 규칙 + DNS가 함께 맞을 때 CLI 재현성이 좋아집니다. Windows 11에서 WSL2 터미널에 CLI를 설치했다면, WSL 내부 프록시·호스트 IP·WSL2 라우팅까지 한 세트로 봐야 합니다. Docker 컨테이너 안에서 gemini를 돌리는 경우도 마찬가지로 컨테이너 네트워크가 Clash DNS·TUN 바깥에 있으면 동일 증상이 납니다.

DNS는 enhanced-mode: fake-ip에서 특히 중요합니다. 해석이 Clash 밖에서 끝나면 IP 기반 규칙만 남고, 사용자는 “Clash Google API 분할 규칙을 썼는데 안 먹는다”고 느낍니다. OAuth 콜백 URL이 로컬 루프백을 쓰는 경우도 있으니, fake-ip-filter에 필요한 호스트만 최소 추가하세요.

OAuth vs API 키: 증상별 분기

OAuth 로그인 실패는 대개 브라우저가 열리기 전·콜백 수신 전에 타임아웃됩니다. 터미널에서 gemini auth login(또는 제품 버전에 맞는 auth 하위 명령)을 실행할 때 Clash 로그에 accounts.google.com·oauth2.googleapis.com이 같은 OAUTH 그룹으로 나가는지 확인하세요. 브라우저는 시스템 프록시를 타고 CLI는 직접 연결하면, 화면에서는 로그인됐는데 터미널만 대기하는 불일치가 생깁니다.

API 키 모드는 OAuth 호스트 없이 generativelanguage.googleapis.com만 치는 경우가 많습니다. “Invalid API key”가 아니라 연결 타임아웃이라면 프록시 미적용·노드 불안정·DNS 경로 문제를 우선 의심합니다. 같은 터미널에서 curl -v --proxy http://127.0.0.1:7890 https://generativelanguage.googleapis.com로 TLS 핸드셰이크가 되는지, 프록시 없이는 실패하는지 대조하면 원인 축이 빨리 좁혀집니다. Claude Code·Cursor 등 다른 터미널 AI 도구와 규칙을 공유한다면 Claude Code 터미널 분할처럼 API 레인과 TOOLCHAIN 레인을 파일 단위로 나눠 관리하면 실험이 쉽습니다.

노드·리전 선택: Google API 실측

Google 쪽 서비스는 계정·모델·정책에 따라 “해당 리전에서 사용할 수 없음” 메시지가 나올 수 있습니다. GEMINI_API 그룹만 미국·일본·싱가포르 등으로 바꿔 가며 동일 프롬프트를 반복하고, HTTP 상태 코드와 응답 본문을 기록하세요. url-test가 통과해도 스트리밍 중간에 끊기면 tolerance·interval을 보수적으로 잡거나, fallback 그룹을 두어 불량 노드를 건너뛰게 합니다.

회사망 SSL 검사·HTTP/2 중간 프록시가 있으면 Clash 규칙만으로는 해결되지 않을 수 있습니다. 이 경우 네트워크 팀 예외 정책을 Clash 분할과 별도로 검토해야 합니다. 가정·개발 PC에서는 노드 품질 문제인 경우가 더 흔하므로, 먼저 로그·curl·규칙 순서를 정리한 뒤 노드를 바꾸는 순서를 권합니다.

현장 점검 순서

npm install -g @google/gemini-cli가 TOOLCHAIN 그룹 경로로 성공하는지 확인합니다. 실패하면 npm·GitHub 규칙부터 고칩니다.
Clash 로그에서 generativelanguage.googleapis.com·OAuth 호스트가 어느 그룹으로 나갔는지 봅니다. 기대와 다르면 규칙 순서를 조정합니다.
터미널에 HTTP_PROXY·HTTPS_PROXY가 Clash 혼합 포트와 일치하는지, 또는 TUN이 켜져 있는지 확인합니다.
OAuth와 API 키 모드를 각각 시험해, 실패 구간이 인증인지 API인지 분리합니다.
환경 변수·TUN·DNS 중 무엇을 바꿨을 때 증상이 같이 움직이는지 메모해, 원인 후보를 한 번에 줄입니다.

주의: 출처 불명 rule-set은 악성 라우팅이나 잘못된 GeoIP 매핑을 실어 올 수 있습니다. API 키·OAuth 토큰을 다루는 개발 기기라도 검증된 구독과 로컬 화이트리스트를 우선하세요.

자주 묻는 질문

Q. gemini 명령은 있는데 첫 대화만 ETIMEDOUT입니다. A. 설치는 TOOLCHAIN으로 됐지만 API 호출만 DIRECT인 패턴입니다. 터미널 프록시·TUN·generativelanguage.googleapis.com 규칙 세 가지를 동시에 점검하세요.

Q. AI Studio 웹 규칙을 복사했는데 OAuth만 실패합니다. A. 웹은 브라우저가 시스템 프록시를 따르고, CLI OAuth는 터미널·로컬 콜백 경로가 추가됩니다. accounts.google.com·oauth2.googleapis.com을 API와 같은 그룹으로 맞추고 터미널 환경 변수를 주입하세요.

Q. Gemini Enterprise 콘솔 규칙과 충돌합니다. A. 기업용은 console.cloud.google.com·aiplatform.googleapis.com 등 호스트가 다릅니다. 소비자 CLI용 GEMINI_API 블록과 GCP 블록을 YAML 섹션으로 나누어 관리하세요.

마무리

2026년 Gemini CLI는 브라우저 AI Studio·기업 Gemini Enterprise와 API를 공유하지만, 네트워크 경로는 npm 설치·터미널 OAuth·직접 TLS 때문에 겹치지 않습니다. Gemini CLI 타임아웃을 줄이려면 Clash Google API 분할 규칙만 맞추는 것으로는 부족하고, 터미널 AI 프록시·DNS·TUN을 같은 체크리스트에서 다뤄야 합니다.

반면 일부 상용 VPN이나 단일 글로벌 토글형 클라이언트는 호스트 단위 튜닝이 거의 불가능하고, npm CDN과 Google API를 한 회선에 억지로 묶다 보면 “설치는 됐는데 auth만 실패” 같은 증상을 추적하기 어렵습니다. Clash 공식 사이트는 구독·프로필 편집·연결 로그 확인 흐름이 개발자 워크플로에 맞게 정리되어 있어, 본문의 GEMINI_API·OAUTH·TOOLCHAIN 패턴을 그대로 이식하기 수월합니다. 문서 허브는 docs를 참고하시고, 동일한 분할 실험을 시작하려면 Clash 공식 사이트 클라이언트를 무료로 내려받아 프로필에 규칙 블록만 맞춰 보시길 권합니다. 터미널에서 OAuth·API 키·모델 호출이 한 번에 통과할 때, Gemini CLI 에이전트 루프가 비로소 끊기지 않고 돌아갑니다.