왜 Gemini CLI는 터미널만 불안하게 느껴질까?

2026년 화면 속 코딩 어시스턴트부터 CI 스크립트까지 Gemini 계열 명령줄 클라이언트가 널려 있지만, 사용 경험이 “브라우저에서는 잘 된다 ↔ 터미널에서만 간헐 실패”로 갈라지는 패턴은 이미 흔한 서포트 장면입니다. HTTP 프록시를 잡은 브라우저가 시스템 레지스트리의 PAC를 읽거나 자체 경로 우회를 허용하는 반면, 터미널 쪽 라이브러리는 순수하게 OS 네임스페이스·DNS 캐시·자체 인증 플러그인만 보는 경우가 많습니다. 결과적으로 Gemini CLI처럼 짧은 REST·스트리밍 요청을 수십 회 연달아 보내는 프로그램은 TCP 초기 라운드 트립, TLS 핸드셰이크 시간, QUIC 폴백 여부에 따라 “가끔 전부 실패” 같은 체감을 줍니다.

이 글은 단일 페이지가 막히는 스타일의 개별 사례 분석이 아니라, Clash Verge Rev(Mihomo 코어 포함) 안에서 Gemini CLI 같은 터미널 세션 트래픽을 규칙 라우팅·TUN·DNS 세 축으로 맞춘 뒤 재현 가능한 점검 순서를 따라가도록 돕습니다. 이미 같은 시리즈의 구성 튜토리얼을 읽었다면 Profiles·Rule·TUN 토글 이름을 더 빠르게 찾을 수 있습니다.

메뉴 라벨은 앱 버전별로 표기가 바뀔 수 있어 본문은 영문 UI 기준 이름을 우선 적습니다. Subscriptions·Profiles·Proxies·Settings 등 사이드바 항목을 그대로 찾으면 됩니다.

증상 패턴 재정의하기

먼저 “불안”을 숫자로 바꿉니다. 간헐성은 환각으로 남아 있으면 튜닝이 도박처럼 느껴지기 때문입니다.

  • 증상 카탈로그: 응답 없음, 즉각적인 403/451, 무한 재시도, 혹은 WebSocket 업그레이드 실패처럼 CLI가 다른 문구를 남기나 실제 회선 상태는 같은지 확인합니다.
  • 동시 테스트: 같은 시각에 간단한 curl -I https://developers.google.com 같은 순수 명령이 성공하는지, Gemini CLI 디버그가 동시에 깨지는지 비교해 “브라우저 전용”과 “실제 인터페이스”를 나눕니다.
  • 배너링: 프록시를 끈다 → 시스템 프록시만 적용한다 → 완전 TUN이라는 순서로 단계별 경로 차이가 있는지 검토합니다.

패턴 표를 메모하면 공유하기도 편합니다. 예를 들면 “금요 저녁 19~21시 업스트림이 느린 노드 선택자가 자동 교체되면서 QUIC 경로 탐색 시간이 증가”처럼 시간대·네트워크 인터페이스·무선 채널을 함께 적어 두세요.

Gemini API 엔드포인트 이름은 제공 정책에 따라 업데이트될 수 있습니다. 아래 규칙 예시는 개념을 보여 주는 것일 뿐이며 실제 디버깅 때는 패킷 분석기나 활성 접속 패널에 나오는 현재 호스트 이름을 따라가야 합니다.

1단계: 증상 패키지 만들기와 비교 기준 세우기

설정을 만지기 전에 터미널 명령으로 최소 증명 세트를 남겨 두세요.

  1. CLI 명령에 디버그(가능하면 --verbose 계열 플래그)를 추가하고 동일 회선 한 번은 시스템 네임스페이스, 한 번은 VPN/TUN 상태에서 반복 실행합니다.
  2. 호스트명이 로그에서 보이록 하고, 접속 순서 상에서 먼저 조회되는 DNS 타입과 TLS SNI를 메모합니다.
  3. 패킷 캡처가 어렵다면 Clash Verge Rev의 활성 접속 카드 또는 코어 디버그에서 DEST 규칙 매칭 줄을 확인해 어떤 rule chain에 걸리는지 봅니다.
  4. 위 로그 번들과 함께 날짜·시간대·네트워크 유형 LAN/LTE)·노드를 한 줄 표로 만들어 블로커 패턴 추적표를 채워 보세요.

이 과정 없이 무작정 규칙을 던지면 새로 발생한 변수를 찾아내기가 어려워져 “어제는 된다가 오늘은 안 된다”는 말만 남습니다. 특히 업무 회선과 재택 회선을 오가는 사람은 인터페이스 우선순위 때문에 DIRECT와 PROXY 간 경로 차이만으로도 패턴을 만듭니다.

2단계: Rule 모드와 활성 프로필 고정

Clash 계열 라우팅의 기본 레일은 여전히 Rule입니다. Global은 단기 테스트에만 쓰고, Gemini CLI 디버깅도 실제 업무 상태를 반영해야 한다면 일상 상태인 Rule부터 고정해야 합니다.

  • Profiles 화면에서 실제 업데이트 주기와 Override 체인이 포함된 카드를 활성 상태로 선택합니다.
  • 헤더 또는 홈 카드 근처의 모드를 Rule로 돌린 뒤 Direct/Global을 섞어 쓸 일이 줄어들도록 UI에서 시각 확인합니다.
  • 복수 구독이 있다면 테스트 중에는 카드 전환 빈도를 줄이고, 카드 교체 순간에 생기는 캐시가 아닌 상태인지 명시적으로 리로드를 눌러 결과를 새로 받습니다.

Rule 상태에서도 일부 패킷은 DIRECT로 새지게 되어 있는데 이때 Gemini 관련 접속까지 DIRECT로 새면 간헐적 필터링이 그대로 남습니다. 다음 단계의 Override를 통해 Gemini 트래픽 명시적 분기 준비를 합니다.

3단계: Gemini 트래픽 명시 라우팅 Override

구독이 만든 규칙만으로 모든 AI SDK 조합을 처리하기 어려울 때 Override Merge로 조각을 더합니다.

  1. Settings 혹은 Profiles 하위 메뉴에서 Override를 엽니다.
  2. 새 파일을 만들고 종류를 Merge로 맞춥니다.
  3. 예시처럼 핵심 호스트 패턴과 실제 활성 Selector 이름으로 매핑합니다(아래 이름은 교체해야 합니다).
rules:
  - DOMAIN-SUFFIX,googleapis.com,AI-NODE-GROUP
  - DOMAIN-KEYWORD,generative,AI-NODE-GROUP
  - DOMAIN-SUFFIX,google.com,DIRECT # adjust if required

AI-NODE-GROUP 자리에는 현재 활성 Profiles YAML 안에 있는 진짜 그룹 문자열을 써야 합니다. 문자 하나라도 빗나가면 Fallback 기본 규칙으로 떨어지므로 Overrides 저장 후 Applies를 실행하고 디버그에서 실제 선택된 줄을 검증해야 합니다. 너무 광역한 패턴(*google*)을 던지면 국내 콘텐츠 같은 정상 회선까지 PROXY 타기 때문에 지연 패널티가 크니 디버깅 단계에서는 좁히고, 안정 패턴 확인 후 필요한 폭넓히기를 순차적으로 하는 편이 낫습니다.

GeoIP 또는 ASN 보조 라우팅

일부 패킷이 IP 레벨로만 전달된다면 규칙 세트 저장소(rule-providers)를 추가해 Gemini 경로 가능성이 높은 AS 범위를 잡도록 보강할 수 있습니다. 다만 업데이트 주기와 메모리 사용이 늘어날 수 있다는 현실적인 제약과 VAT 혹은 국내 필터링이 Geo 힌트로만 처리되면 오동작 가능성도 있으므로 테스트 환경에서만 반복해야 합니다.

4단계: TUN 활성화로 CLI 트래픽 포함

시스템 프록시를 따르지 않는 SDK 때문에 생기는 누출을 막으려면 TUN Mode가 현실적인 답변입니다.

  1. Settings로 이동해 TUN 토글을 켭니다.
  2. Windows는 고정 관리자 권한 또는 서비스 설치 메시지에 응해야 하고, macOS는 시스템 확장·비밀번호 프롬프트를 허용해야 어댑터가 활성입니다.
  3. 네트워크 스택 설정이 제공된다면 먼저 기본값(대개 Mixed)부터 유지합니다.
  4. 활성화 직후 curl이나 간단 스크립트로 동일 테스트를 재현해 DIRECT 기반과 비교 분석합니다.

TUN 자체가 만능은 아니고, 회사 VPN이 같은 계층에 가상 NIC를 깔아 두었다면 순서 때문에 오히려 순환 지연이 늘 수 있습니다. 이 경우 순간적으로 업무 게이트웨이를 끊고 단일 우세 NIC만 남기는 대조 실험이 필요합니다. 또 회사 디바이스 정책에서 TUN이 금지돼 있다면 정책 위반 업무를 지시하지 않으며, 허용된 모드에서는 시스템 프록시 + CLI 전용 라이브러리 환경 변수(HTTPS_PROXY 등, 지원해야 함) 같은 대안 레이어만 강구해야 합니다.

5단계: DNS 정렬(Fake-IP·업스트림)으로 일관 레이턴시

DNS 질문이 ISP 리졸버로 새면 패킷이 PROXY 타기 전에 이름조차 엇나갑니다.

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.google/dns-query
    - https://dns.cloudflare.com/dns-query
  fallback:
    - https://8.8.8.8/dns-query
  fake-ip-filter:
    - '+.lan'

Override 작성 후 Applies를 거쳐도 반영 안 되면 캐시된 Fake-IP를 비우거나 코어 재시작이 필요합니다. Fake-IP는 일부 스트림 앱 호환 과제라서 문제가 발생하면 Redir-Host로 스위치하되, 그 과정에서는 다시 디버깅 표를 새로 작성해야 변경 전후 결과를 놓치지 않습니다.

외부 테스트 페이지(browserleaks.com/dns 같은)보다 Gemini CLI 테스트 직전에 dig 혹은 kdig로 동일 업스트림이 지정되는지 확인하는 방법이 디버깅 친화적입니다. 테스트 전후로 기록 시간을 명시해야 야간 캐시 TTL 변화 때문에 생기는 혼선을 줄일 수 있습니다.

6단계: 터미널 명령으로 재측정

규칙을 넣어도 CLI가 여전히 실패하면 TLS 경로 차이 때문일 수 있습니다. 아래는 예시이며 사용자 환경에 맞는 엔드포인트 명을 넣습니다.

curl -w '%{http_code} %{time_connect} %{time_starttransfer}' -o /dev/null https://YOUR_DEBUG_HOST
openssl s_client -connect YOUR_DEBUG_HOST:443 -brief

동일 변수에서 연속 두 번 결과가 크게 들쭉날쭉하면 노드 교체 또는 스택 교체 테스트를 이어 가야 하고 반대로 시간은 안정인데 상태 코드만 흔들리면 업스트림 속도 리밋·인증 헤더 쪽 검토가 순서입니다. 중요한 점은 결과를 증상 패턴 표 한 행 안에 새 열을 추가해 패치 전후 시간과 숫자를 나란히 보는 연습입니다. 그래야 회고 때 “설정이라기보단 노드 품질 이슈” 같은 결론이 분명히 드러납니다.

여러 디바이스를 오가며 재현된다면 회선보다 라이브러리 캐시에 가까운 버그 가능성도 있으므로 패키지 관리 도구 업데이트 일자도 표에 포함하세요.

7단계: Proxies 패널에서 지연·그룹 정돈

설정 레이아웃까지 맞췄다면 선택된 노드 풀이 병목인지 검증 차례입니다.

  • Proxies에서 일괄 지연 테스트를 돌린 뒤 가장 안정적인 경로부터 Selector를 고정합니다.
  • 구독이 URL-Test·Fallback 라우프를 포함한다면 이를 테스트 모드 우선 순위로 활용합니다.
  • 장시간 대화 세션이 많다면 핑이 높더라도 지터가 적은 회선과 반대 조합까지 비교해 체감 혼합 점수를 만듭니다.

노드를 바꿀 때 Override 대상 패턴 이름이 같이 바뀌지 않았는지 점검해야 합니다. 자동 교체 과정 중 스크립트가 예전 이름을 들고 있는 경우 디버깅 표가 순간적으로 헷갈리기 쉽습니다.

8단계: 설정 스냅샷을 한 문서로 남겨 회귀와 구분하기

Overrides 파일 이름, 규칙 세트 태그, DNS 모드 문자열, 고정한 Proxies 그룹 이름, 성공 또는 실패에 대한 최소 curl 출력 줄을 시간과 함께 한 표에 적어 두면 며칠 뒤에도 동일한 비교 테스트를 재현하기 쉽습니다. 피크 타임 구간만 품질이 깨진다면 그 시간대까지 칸으로 표시해 플랫폼 측 과부하와 교체된 회선 결과를 헷갈리지 마세요.

Gemini CLI나 구독이 업그레이드된 뒤에도 같은 표의 행만 갱신하면 변인을 통제하면서 다음 원인 분기를 줄일 수 있습니다.

자주 묻는 질문

브라우저는 OK인데 터미널만 깨져요.

브라우저는 PAC·확장·자체 QUIC 스위치를 통해 프록시를 따르거나 우회하지만 순수 명령줄 라이브러리는 해당 경계를 무시합니다. TUN 레이어나 SDK가 지원하는 프록시 환경변수를 통해 동일 회선 묶음을 보장해야 합니다.

어떤 DOMAIN을 넣어야 할 모르겠습니다.

우선 디버깅 또는 활성 접속 카드에서 실제 연결 문자열을 복사하세요. 가짜 문자열 패턴 라이브러리를 깔기보다 회사 정책에서 허용하는 관측 수단부터 사용해야 합니다.

TUN과 회사 게이트웨이 VPN이 함께 켜지면 전부 블랙홀처럼 느껴집니다.

가상 어댑터 우선 순위 또는 같은 주소 대역이 겹칠 때 발생합니다. 어느 한 축만 남긴 테스트에서 성공 패턴을 찾고, 허용 정책상 동시 활성 레이어를 유지해야 한다면 IT 가이드를 따르거나 분업 시간대별 프로필 두 벌 같은 운영을 고려해야 합니다.

먼저 터미널 에러 로그와 Clash 패널 중 어디를 봐야 하나요?

패널 규칙 매칭 열과 연결 상태를 우선 확인한 뒤 같은 시각 재현 패키지의 curl 결과와 맞춥니다. 패널에서는 PROXY로 보이지만 터미널이 서로 다른 셸이면 변수 주입 상태를 재점검하세요.

운영 레벨 마무리

터미널 AI CLI 같은 도구들은 속도 높게 반복 접속해야 하므로 작은 패킷 지터도 곧바로 “불안”으로 체감됩니다. 시스템 프록시에만 의존하는 간단 브라우저 확장이나 단발성 VPN처럼 한 번 켠 뒤 끝내는 패턴은 상태가 새로 깔릴 때마다 새로 디버깅해야 해서 업무 패널티가 크고, 제공사가 속도 SLA를 깍아도 사용자가 교정할 레버가 거의 없습니다. 반대로 Clash Verge Rev는 Overrides·rule-providers·TUN 레이어별 디버깅 포인트를 모두 제공하므로, 노드 교체라는 변수 대신 회선 상태를 패턴표로 줄 수 있는 장점이 있습니다.

다만 GUI가 영어라 메뉴 찾기에 시간 들고, 회사 디바이스 정책과 겹치는 경우가 많다는 현실적인 한계와 프리픽 패키지만으로는 학습 시간이 존재합니다. 업무 허용 환경에서 단일 패키지만으로 속도 SLA를 높여야 하는 팀이라면 프리셋이 정비된 공식 라인과 비교해야 하고, Gemini CLI처럼 터미널 디버깅이 핵심인 개인 사용자라면 같은 Mihomo 레이블을 활용하면서 학습 깊이를 조절하는 편이 이득입니다. 따라서 회선 디버깅을 스스로 패턴화해야 한다면 Clash 공식 배포판으로 정리된 기본 경험부터 옮겨 타는 것도 과도한 초기 커브를 줄이는 합리적 선택입니다.

플랫폼별 Clash 무료 다운로드 — Gemini CLI 테스트도 규칙 기반 회선부터 →