이 글이 맞는 증상

2026년에는 Claude Code나 OpenAI Codex CLI와 마찬가지로 구글이 공개해 둔 Gemini CLI 형태의 터미널 에이전트가 개발 플로우에 자주 논의됩니다. 로컬 셸에서 실행하면 내부적으로 Google AI API 끝단—대표적으로 generativelanguage.googleapis.com—으로 HTTPS가 이어져야 하는데, 브라우저에서는 Google AI 스튜디오나 문서 페이지가 정상적으로 열리는데 CLI만 context deadline exceeded류의 타임아웃, 간헐적 연결 재설정, 혹은 토큰·OAuth 단계에서 흐름이 끊기는 패턴이 나옵니다.

이 문서는 Clash Verge Rev(이하 CVR)를 기준으로, 규칙 기반 분기로 Google API 패킷을 의도한 노드에 태우는 방법과, 터미널 세션에서 HTTPS_PROXY 계열 변수를 어디에 두는지, 마지막으로 로그 타임스탬프와 대조하는 검증 순서를 정리했습니다. 특정 구독 제공자 이름이나 상용 노드 라벨에 의존하지 않고 패턴만 재사용할 수 있도록 썼습니다.

왜 브라우저는 되는데 Gemini CLI 터미널만 불안정할까

브라우저는 보통 운영체제의 시스템 프록시를 따르고, 프로필별 PAC·프로필 격리·확장에 따라 경로가 갈립니다. 반면 Gemini CLI처럼 터미널에서 돌아가는 Go·Node 계열 프로그램은 기본값이 직접 연결에 가까운 소켓이라, 시스템 레벨 TUN만 켜져 있어도 같은 머신 안에서 브라우저와 다른 인터페이스를 탈 수 있습니다. 통합 개발환경 안의 터미널은 부모 IDE가 받은 환경 변수 묶음을 그대로 물려받기 때문에 export 시점과 IDE 재시작 순서까지 포함해 원인 분석해야 합니다.

두 번째 축은 규칙 오판입니다. 대형 GEOSITE 묶음이나 지역 라우팅 규칙 때문에 *.googleapis.com 접두 일부만 DIRECT로 빠져 차단 회선으로 나가거나, 반대로 혼잡한 단일 업스트림에만 매달려 지연만 길게 늘어나는 경우가 많습니다. API 키를 올바르게 넣었는데도 401보다 타임아웃이 우선이라면 회선 때문이 아니라 경로 레이턴시·MTU·핸드셰이크 중단을 의심하는 편이 낫습니다.

세 번째는 인증 채널 분리입니다. Google 계정 브라우저 로그인을 동반하는 플로우가 있으면 accounts.google.com, oauth2.googleapis.com 등 다른 호스트가 중간에 끼며, 브라우저는 시스템 설정으로 한 경로를 타고 CLI 트래픽만 제자리 로컬에서 빠져나가면 사용자 체감으로는 같은 오류 문자열이라도 근본 원인이 완전히 다릅니다.

어떤 도메인을 한 묶음으로 볼까

운영에서는 먼저 CVR 접속 기록 또는 외부 캡처로 실패 직전의 호스트 문자열을 모읍니다. 많은 퍼블릭 클라이언트가 Gemini REST 호출에 generativelanguage.googleapis.com을 쓰므로 규칙 예시에서 자주 이름이 오르지만, Vertex AI·조직 정책·리전 접두 규칙이 있으면 *.googleapis.com 패턴 안에서 접두 하나만 다른 서브도메인으로 달라지기도 하고 완전히 다른 호스트가 추가되기도 합니다. 따라서 문서 목록만 복사해 붙이기보다 로그에서 검증된 서픽스를 YAML에 명시적으로 추가하는 접근이 낫습니다.

브라우저 보조 플로우까지 통일하고 싶다면 같은 로그 채널에서 OAuth·쿠키에 관련된 호스트들이 같은 정책 그룹을 타는지도 함께 봅니다. 과도하게 넓은 와일드카드 규칙은 다른 Google 트래픽까지 같은 노드로 몰아 의도하지 않은 대역폭 문제를 만들 수 있으니, 테스트 단계에서는 좁히고 안정 확인 후 필요한 접두만 늘리는 편이 운영에 유리합니다.

규칙 분기 vs 글로벌 TUN: 무엇부터 맞출까

글로벌 TUN 모드는 OS 전체 패킷을 한 번에 잡아 간단하게 보일 수 있지만, 회사 노트북의 MDM·다른 상용 VPN·보안 에이전트와 경로 충돌을 일으키기 쉽습니다. 게다가 TUN을 활성화해도 일부 프로그램이 가상 라우팅 테이블을 따르지 않는 보고가 간헐적으로 있습니다.

반대로 규칙 모드와 로컬 mixed-port를 표준 입구로 쓰면, 어떤 호스트 이름이 어떤 정책 그룹·체인에 붙었는지 CVR UI에서 따라가며 증상별 재현을 남길 수 있습니다. 브라우저에는 시스템 프록시로 같은 127.0.0.1:<mixed-port>를 가리키게 하고, CLI에는 HTTPS_PROXY=http://127.0.0.1:<mixed-port>처럼 동일한 로컬 프런트를 쓰도록 맞추면 브라우저·터미널 출구 불일치를 크게 줄일 수 있습니다.

실무에선 코어 상태와 포트 확인 → 해당 API 호스트의 규칙 매칭 → 필요 시에만 TUN 보강이라는 순서가 디버깅 비용 대비 균형이 좋습니다.

팁: Mihomo·Clash 계열에서 Rule·Global 같은 표기는 클라마다 레이블이 조금 다르지만 개념은 같습니다. 혼선이 크면 글로벌이 아니라 규칙 모드에서 시작해 로그 패널에 찍히는 매칭 이유를 한 줄씩 확인하세요.

1단계: Clash Verge Rev 기본 상태 점검

프로필이 활성이고 코어 프로세스가 예기치 않게 종료되지 않았는지 확인합니다. 구독이나 원격 규칙 목록을 갱신한 직후에는 예전에 통과했던 패턴이 다른 정책 그룹으로 이동하는 경우가 많아, 업데이트 타임스탬프와 함께 메모하는 습관이 재발 원인 규명에 도움이 됩니다.

mixed-port 실제 번호를 메모합니다. 다른 애플리케이션이 해당 포트를 선점했다가 코어가 자동 대체 번호를 쓴 경우가 흔한데, 브라우저 시스템 프록시는 옛 번호를 가리키고 터미널 변수만 새 값이라면 겉보기 무한 대기가 계속됩니다.

2단계: 규칙으로 Google AI·Gemini 호스트 분기 확인

앞 단계에서 수집한 호스트 문자열을 기준으로, CVR 프로필의 rules: 섹션이나 UI 규칙 편집기에서 필요한 순서와 결합(MATCH 이전)을 정돈합니다. DIRECT로 떨어지도록 설계된 광역 중국 라우팅 세트 안에 해당 서픽스가 포함돼 있지 않은지, 포함돼 있다면 본인 환경에 맞춰 우선 순위 높은 예외 줄을 추가합니다.

여러 업스트림이 있는 정책 그룹이면 API 전용 줄을 하나 더 두어 지연 테스트·폴백이 적용되게 할 수 있습니다. 이때 그룹 이름은 팀 규약에 맞추되 장기적으로 Gemini 또는 Google_AI_API처럼 용도가 드러나게 남겨 두면 회고할 때 시간이 줄어듭니다.

3단계: 터미널 환경 변수는 어디에 둘까

많은 HTTP 클라이언트가 다음 키를 읽습니다.

  • HTTPS_PROXY / HTTP_PROXY — TLS 포함 요청과 일반 HTTP를 각각 지정할 때
  • ALL_PROXY — 구현체에 따라 두 값을 하나로 줄 때
  • NO_PROXY — localhost, RFC1918 대역 일부, 사내 Git·패키지 레지스트리 등 우회해서는 안 되는 내부 호스트 목록

계정 전역에 무조건 export 해두기보다는 CVR 실행 여부나 프로젝트 폴더에 따라 조건을 타는 형태(direnv, 선택적 함수 래핑 등)가 실수 노출 면적을 줄입니다. IDE를 이미 연 상태에서 변수만 수정했다면 통합 터미널은 옛 세션 값을 들고 계속 실행하므로, 중요 변경 뒤에는 IDE 자체를 종료했다가 다시 띄우는 편이 확실합니다.

Gemini CLI가 디버그 스위치를 제공한다면 활성 로그 시간과 동시각의 CVR 흐름을 맞춰 보면, 변수가 무시되는지 아니면 핸드셰이크까지 갔는지 구분하기 쉬워집니다.

프록시 URL 형식과 SOCKS 선택

mixed-port에서 HTTP CONNECT와 SOCKS를 함께 받는 설정이 많으므로, CLI 스택부터 http://127.0.0.1:<port>를 우선 검증합니다. SOCKS가 명시적으로 필요하면 socks5://127.0.0.1:<port>처럼 스키마 자체가 틀리지 않게 적습니다. 잘못된 스키마는 즉석에서 거부되기보다 수십 초짜리 대기처럼 보이는 패턴과 겹치기 때문에 의심스러우면 -v급 출력을 즉시 켭니다.

4단계: 시스템 프록시·TUN과의 정렬

macOS와 Windows에서는 CVR이 시스템 프록시로 연결해 주는 기능을 활용할 때, 실제 활성 상태인지 헤더 패널에서 한 번 더 토글 상태를 교차 검증합니다. TUN 단독 사용이라면 라우팅 테이블에 가상 어댑터가 올려졌는지, 방화벽이 해당 인터페이스를 허용하는지 순서대로 확인합니다.

이중 VPN·Always-On 회사 VPN과 CVR TUN을 겹치면 핸드셰이크 레이턴시만 불필요하게 커져 타임아웃으로 표시되는 경우가 있습니다. 각각 분리 테스트해 시간대가 줄어드는지 비교하면 범위를 빠르게 좁을 수 있습니다.

주의: 터미널 블록 안에서 프록시를 켠 채 패키지 다운로드·컨테이너 풀 등을 실행하면 예상 외 업스트림을 탈 수 있습니다. NO_PROXY를 지속 업데이트하고, 회사 허용 범위 밖 회선 우회 요구가 있다면 거버넌스 팀 지침을 먼저 확인하세요.

5단계: 여전히 타임아웃·인증 에러일 때 좁히기

  1. 동일 호스트와 유사 패스에 브라우저·curl(프록시 옵션 유무 교차)로 응답 시간을 나란히 봅니다.
  2. CVR 로그에서 어떤 규칙 인덱스에 매치됐고 최종 업스트림이 무엇이었는지 확인합니다.
  3. env | grep -i proxy로 예전 세션 변수 잔류가 있는지 검사합니다.
  4. CLI에서 짧은 타임아웃을 줄 수 있는 옵션을 잠깐 줄여 패킷 초기 레이턴시와 서버 레이턴시를 분리 관찰합니다.
  5. 브라우저 OAuth와 CLI가 같은 Google 계정·같은 정책 환경을 가정하는지, 기업 SSO나 조건부 액세스가 브라우저에만 매달려 있지 않은지 확인합니다.

로그와 인증 상태를 교차 검증하는 법

네트워크만 보면 모두 같은 실패로 포장되는 경우가 많으니, Gemini CLI 또는 Google 공식 디버깅 채널에서 나오는 타임스탬프와 CVR 연결 시작 시각을 초 단위로 맞춰 같은 TCP 세션인지 검증합니다. 인증 문자열에는 민감 정보가 섞일 수 있으니 공유 전에 레벨을 낮추고, 회사 채널에는 호스트 이름과 결정 결과만 빼내는 버릇이 안전합니다.

401·403처럼 HTTP 레벨 명확한 코드가 바로 안 보이더라도, TLS 레이어만 깨져 중간 라우팅에 걸린 경우 종료 문자열은 비슷하게 보입니다. 따라서 TCP 레벨 패킷 캡처는 최후 단계까지 미루고, 프록시·규칙·환경 변수 정렬 같은 저비용 순서부터 소모하는 편이 팀 업무 속도 면에서 낫습니다.

팀 환경에서의 문서화 팁

여러 사람이 Gemini CLI 모델을 공유 레포 안에서 실행하면 셀 환경이 제각각입니다. 선택적 실행 스크립트나 레포 안 .env.example에 변수 이름과 예상 포맷만 명시하고 실제 값과 포트 번호는 개인 레이어에서 관리합시다. CI와 로컬 프록시 키를 구분하기 위한 접두사 규약도 함께 두면 헷갈림이 줄어듭니다.

자주 묻는 질문

Q. API 키가 프록시 로그나 히스토리에 새지 않게 하려면?
A. 프록시 상세 트레이스를 과도하게 켠 채 장시간 놓아두지 말고, 공용 장비에서는 셸 히스토리 정리 습관을 유지합니다. Google이 권장하는 자격 증명 보관 채널을 따르는 편이 가장 안전합니다.

Q. WSL2와 Windows CVR을 동시에 쓸 때는?
A. 리눅스 쪽에서 바라본 127.0.0.1과 Windows 호스트 리스너가 다른 경우가 있어 주소 교정이 필요할 수 있습니다. Windows 측 IPv4 브리지 주소로 맞추거나 WSL 버전별 네트워킹 가이드를 따르세요.

Q. 회사 네트워크에서 우회 설정이 허용되지 않아요.
A. 이 문서는 합법적 범위 내 egress 제어 환경을 전제합니다. 정책을 어긴 우회는 위험하므로 허용된 방법으로 헬프데스크에 문의해야 합니다.

정리: 상용 VPN 단일 스택보다 규칙·터미널을 함께 맞추는 이유

상용 종합 VPN 하나만 의존하는 방식은 처음엔 단순합니다만, 회선 상태가 바뀌거나 스플릿 터널링이 조용히 바뀌면 어떤 프로세스가 어디로 나가는지 가시화가 어렵습니다. 반대로 Clash 계열 계통과 CVR에서는 호스트 문자열 하나를 찍어도 곧바로 규칙 줄과 업스트림이 보이므로 Gemini와 같은 고지연 회선에서는 원인 규명이 빠릅니다.

Cursor나 다른 IDE 플러그인용 분기 패턴을 이미 익혔다면, 대상 호스트 이름만 Google AI 쪽 패턴(Gemini CLI, Google AI API, 필요 시 OAuth 호스트까지)으로 조정하면 됩니다. npm·패키지 레지스트리·컨테이너 허브를 동시에 쓰는 개발자 거버넌스에서 상용 방화벽이나 순수 브라우저 전용 VPN은 종종 CLI 레이어만 놓치는데, CVR로 규칙을 유지한 채 HTTPS_PROXY 같은 소규모 터미널 훅만 얹으면 디버깅 부담이 크게 줄어듭니다. 스트리밍용 대역 우선 순위까지 섞여 있는 일반 묶음 노드 구독 단독에서는 그런 레이어링이 어려운 편이라, 같은 작업이라도 회선 교체 하나에 전체 레포가 깨져 버리기 쉽습니다.

그 결과 Gemini CLI로 자동 패치 후보 분석이나 테스트 보조 같은 워크플로를 매일 의존하더라도, API 단계 레이턴시가 순간적으로 들쭉날쭉해지더라도 먼저 회선이라고 단정하기 전에 규칙과 환경 변수·로그로 출구 불일치를 걷어내면 2026년 시점의 현업 생산성에 직결되는 안정 폭 자체가 확보됩니다.

Clash 호환 클라이언트를 받아 터미널과 브라우저 출구를 동일 규칙으로 맞추기 →