증상 패턴과 왜 브라우저 가이드를 그대로 쓸 수 없나

2026년 기준 사용자는 Google AI 스튜디오나 맥 Gemini 앱에서 접하는 경험만으로 규칙을 짜 놓았다가, Gemini CLI로 넘어가면 다시 헤맵니다. 터미널에서는 애플리케이션이 네이티브 TLS 스택을 직접 열거나, 패키지 설치 과정과 런타임이 다른 프로세스로 나뉘어 있어 브라우저가 자동 처리하던 이름 해석 순서와 다릅니다. 동일 노드를 썼는데 브라우저만 된다면, 첫 확인은 속도 테스트가 아니라 호스트별 정책 적중입니다.

흔한 로그 줄은 크게 세 종류입니다. 첫째, Upstream timeout 형태인데 라우팅이 섞였을 때 종료 지점까지 왕복이 길어지며 발생합니다. 둘째, Unauthorized나 비어 있는 토큰이 찍히는데, 브라우저가 열렸다고 생각했는데 실제로는 교환 페이지가 회사 차단 페이지로 리다이렉트되어 토큰만 비어 있는 패턴입니다. 셋째, CLI 인스펙션 자체는 성공했는데 CDN 번들 받는 단계만 느려져 초기 명령이 멈추는 경우입니다.

따라서 Gemini CLI 전용이라는 새 프로필을 만들기보다, 기존 Google 이름 공간을 다시 읽지만 터미널에 보이지 않던 호스트까지 규칙 테이블에 편입해야 합니다. 시작점으로 연결 로그의 타임아웃·TLS 글과 규칙 매칭 순서 모범 사례를 곁에 두면 원인 분기가 빨라집니다.

ℹ 가설 세우기보다 라이브 연결부터: 실패 즉시 Clash 패널을 열고 googleapis.com·gstatic.com 등을 필터링하세요. 이중 하나가 DIRECT로 남으면 사용자는 노드 교체부터 시도하게 되지만, 실제 패치는 간단히 DOMAIN 규칙 한 줄로 끝나는 경우가 많습니다.

터미널에서 자주 두드리는 Google이름 공간

아래 목록은 운영자가 패턴 학습하기 위한 시작 축입니다. 실제 회선에서는 AB 테스트와 지역 엣지 때문에 한두 글자씩 다른 하위 이름이 새로 등장합니다. 새 호스트가 뜰 때마다 날짜와 함께 YAML 상단 주석으로 남기면 팀 간 공유가 쉽습니다.

웹 사용자라면 동일 패밀리를 다룬 Google AI Studio 분류 글을 따라가지만, 여기에서는 터미널 변수·설치 과정 때문에 위 호스트 순서와 비중이 달라질 수 있습니다. 따라서 Gemini CLI에서는 세션 한 번 재현 후의 로그 순서가 정답이라고 여기세요.

프록시 그룹 설계: GOOGLE_CLI 한 덩어리 vs CDN 분리

한 번에 묶는 설계

가장 간단하게는 관측된 Google 트래픽을 GOOGLE_CLI 하나에 두고 뒷단은 장시간 TCP 우회 레이턴시가 낮은 노드로 두는 접근입니다. 단점은 Google 전체 접미 목록까지 함께 끌고 가는 실수입니다. 과도하게 넓은 DOMAIN-SUFFIX,google.com처럼 잡으면 업무 브라우징까지 같은 출구로 몰립니다.

CDN과 API 분리 설계

GOOGLE_CLI_API와 GOOGLE_CLI_CDN으로 나누면 디버깅은 쉬워지나, 레이턴시 SLA가 크게 다른 노드를 붙여 두었다가는 스트리밍형 응답에서 다시 줄이 서지거나 TLS 세션이 교차 전환되어 끊길 수 있습니다. 분리한 경우 두 그룹이 동일 레지언스의 안정 채널을 타도록 운영 가이드를 문서에 적어 두세요. 그룹이 늘면 GEOIP,KR,DIRECT나 국내 합법망 패턴처럼 GeoIP 우선순위도 함께 살피게 됩니다.

화면 안정성 차원에서 같은 제품 패밀리를 다루는 다른 글처럼, macOS에서는 시스템 확장이 겹칠 때 증상이 오해되므로 macOS TUN·프록시 충돌 페이지를 병렬로 책갈피 두는 편이 좋습니다.

디바이스 로그인·OAuth가 멈추는 조건

디바이스 코드나 브라우저 팝업이 열린 뒤에도 스피너가 돌 때는 종종 회사 차단 페이지가 교환 결과를 교체했기 때문입니다. 이때 사용자는 회사 차단이라기보다 네트워크 오류라고 레이블링합니다. Clash에서는 계정 교환 이름 공간까지 동일 노드 또는 동일 속도등급 채널로 모으고, 회사 레이어별 차단이라면 라우팅으로 해결할 수 없음을 명시해야 합니다.

터미널 변수로 HTTPS_PROXY나 혼합 포트를 줄 때는 패키지가 상속하는지 버전별로 확인하세요. Docker나 혼합 포트 안내가 있는 것처럼, 컨테이너에서 호스트 브리지를 거칠 때는 프록시 환경이 비어 있는 경우가 허다합니다.

최소 YAML 조각과 운영상 주의

아래 단편은 설명 목적 예시입니다. 실제 이름은 사용자 환경의 라이브 로그를 따라가야 하며, 공용 RULE-SET이 넓은 카테고리 규칙으로 수동 줄을 덮어쓰지 않았는지 diff가 필요합니다. 설치 과정까지 포괄하려면 패키지 소스 이름도 포함하세요.

Illustrative YAML fragment

rules:
  - DOMAIN-SUFFIX,googleapis.com,GOOGLE_CLI
  - DOMAIN-SUFFIX,gstatic.com,GOOGLE_CLI
  - DOMAIN-SUFFIX,googleusercontent.com,GOOGLE_CLI
  - DOMAIN,accounts.google.com,GOOGLE_CLI
  - DOMAIN,oauth2.googleapis.com,GOOGLE_CLI
  - GEOIP,KR,DIRECT
  - MATCH,DIRECT

RULE-SET을 끌어다 쓰면 갱신 URL 자체도 안정된 출구를 요구합니다. 구독 품질과 연동 레이턴시는 노드·구독 유지보수에서 다룹니다.

TUN과 Meta DNS, 터미널 변수 정렬

터미널 프로그램이 시스템 설정을 존중하지 않는 경우 TUN 계층까지 올려 전체 소켓을 동일 라우팅 스택 아래 놓습니다. 다음으로 DNS를 맞춥니다. 이름은 Cloudflare DoH 같은 외부 권위로 빨리 풀린 것처럼 보여도 규칙 적중 순서만 엇나가면 API와 CDN이 다른 IP 대역으로 떠서 다시 꼬입니다. 따라서 가능하면 장치 안에서 유일한 권위 DNS를 정하고 나머지는 끕니다.

더 깊게는 Meta DNS 레이아웃 안에서 fallback과 fake-ip 필터 순서까지 정리해야 합니다. DNS nameserver·fallback·fake-ip 가이드를 읽되, 적용 후에는 터미널 세션을 완전히 닫았다 다시 여는 과정까지 포함하세요.

종료 플로에서 시스템 프록시가 남으면 증상이 비슷해 보입니다. Clash 종료 후 네트워크 회복 가이드와 같이 교차 검증해야 CLI 문제와 헷갈리지 않습니다.

검증 순서와 체크포인트

아래 순서로 고정 시나리오를 반복 실행하면 교차 영향 줄이며 빠르게 좁습니다.

  1. CLI를 새로 깐 기기라면 패키지 다운로드 단계부터 로깅 시작 — 설치 과정에서 이미 회사 레이블 또는 지역 회선 때문에 실패했다면 사용자 공간 들어오기 전에 막히는 경우가 있습니다.
  2. 라이브 연결 목록으로 googleapis.com과 gstatic.com의 정책 이름 출력이 동일한지 비교합니다. 한쪽이라도 다른 출력이 보이면 DOMAIN 규칙을 채워 넣은 뒤 프로필 우선 순위 재정렬 여부 확인.
  3. 브라우저 OAuth 대화함을 열더라도 교환 결과가 회사 페이지로 교체되지 않았는지 눈 검사 후 CLI로 재시도합니다.
  4. 규칙 세트 업데이트 직후에만 문제가 발생하면 세트가 수동 줄을 숨겼거나 광차단 목록이 Google 호스트를 가로막았는지 diff합니다.
  5. 노드 지연이 남았다면 TLS 경고 줄을 다시 확인해 패킷 패스가 회사 레이블인지 순수 지연인지 구분합니다.

GUI에서 속도 좋지만 터미널 불안이라면 실행 중인 로그 패널이 있는지부터 확인합니다. 사용자 경험이 좋게 정리되어 있는지는 클라이언트 선택 페이지에서 교차 검토할 만합니다.

자주 묻는 질문

Gemini CLI는 브라우저처럼 시스템 프록시를 따라가나요?

런타임마다 상이합니다. 환경 변수를 상속했는지, macOS에서는 시스템 프로파일 레벨 차이가 있는지도 영향 있습니다. 따라서 시스템 설정만 신뢰하지 말고 TUN으로 패스를 검증해야 합니다.

API 규칙만 넣었는데 브라우저 OAuth 페이지는 회사 페이지로 바뀌진 않았어요.

OAuth가 완료됐더라도 토큰 저장 경로 접근 또는 후속 패치 다운로드가 CDN 이름으로 이어져 실패 문자열이 간결하게만 보일 수 있습니다. CDN까지 동일 채널로 모으거나 최소 레이턴시 프로필을 맞춥니다.

Windows와 macOS 결과가 다른데 무엇부터 맞춰야 하나요?

OS별로 시스템 프록시 누름과 TUN 처리 경로 다릅니다. 한 운영체제에서 패턴 재현했다면 해당 OS에서 DNS hijack 상태와 회사 레이블 VPN 충돌 여부부터 다시 줄 세우세요.

준수와 한계

⚠ 준수 알림: 현지 규제, Google 이용약관, 고용 계약 또는 학내 정책을 따르세요. 본 글은 합법망 라우팅 위생 차원의 기술 가이드를 제공하며, 통제 회피를 조언하지 않습니다.

Zero Trust 레이블이 회사 디바이스에 걸린 경우 사용자 조정만으로 교환 패스 자체가 거부되는 일이 많습니다. 이 경우 라우팅 패치보다 IT 승인이 선행되어야 안전합니다.

맺음말

Gemini CLI나 Google AI CLI가 터미널에서 멈추는 일은 종종 단일 종단 장애가 아니라 CDN·API·OAuth가 서로 다른 출구 속도를 타거나 DNS와 TCP 경로만 엇나가서 생깁니다. Clash로 이를 명시적으로 적으려면 이름 공간별 도메인 분류와 규칙 세트 업데이트 루프를 짧게 유지하는 것이 핵심입니다. 브라우저·맥 앱 가이드를 그대로 복사해 붙이기보다, 터미널 라이브 로그 한 줄 줄이 패치 레퍼런스가 됩니다.

일부 초경량 브라우저형 프록시나 단일 채널 VPN은 CLI용 세션 스플릿·DNS 교차 검증 기능이 빈약해서 문제가 장시간 같은 출구 속에서만 발생할 때 디버깅이 더 힘든 편입니다. 레이블 기반 차단 회사에서는 아예 교환 패스가 막히기도 해서 기능 자체 한계와 네트워크 한계를 구별해야 하고 그때 규칙 문서보다 규정을 우선해야 합니다. 여기까지 맥락이 맞다면 사용자는 Clash Meta 계열처럼 세밀 라우팅, TUN 레이어, 라이브 연결 디버깅을 한 패널 안에서 제공하는 게이트웨이를 택했을 때 복구 루프가 짧아집니다. Clash V.CORE는 이런 멀티스트림 시나리오를 전제로 UI와 프로필 갱신 루프를 정리했기 때문에 Gemini CLI처럼 조용하게 실패하는 툴 조합에서 시간을 덜 허비할 수 있습니다. 아래 버튼에서 바이너리를 받아 터미널 패스를 실제 라이브 연결 숫자로 확인해 보세요.

→ Clash를 무료로 다운로드해서 Google AI 터미널용 규칙을 프로필에 반영하면 됩니다.