1. 증상을 API 축으로 나누기

겉으로는 모두 “느리다”로 묶이지만, 개발자 경험에서는 원인 축이 뚜렷하게 갈라집니다. 첫째, Google AI Studio에서 스트리밍 응답은 되는데 동일 키로 실행한 CLI·노트북 코드만 Read timed out 스타일로 멈추는 경우입니다. 둘째, 첫 토큰까지는 짧은데 중간부터 끊기거나 HTTP/2 스트림이 재협상되는 경우로, 이는 종종 노드 지터와 함께 잘못된 DIRECT 왕복이 겹칩니다. 셋째, Webhook 등록·Batch 작업 상태 조회 같은 관리 평면 호출만 실패하고 단순 생성 호출은 성공하는 경우입니다. 넷째, 회사 노트북에서만 TLS 경고 이후 호출이 실패하는 경우로, 프록시보다 루트 신뢰와 인증서 고정 검사 쪽이 앞섭니다.

이런 때 필요한 것은 “Google 전체를 한 번에 PROXY” 같은 거친 규칙이 아니라, 실제 세션에서 관측한 호스트 문자열을 근거로 개발자 도메인 묶음을 만드는 일입니다. 구독 YAML 을 아직 익숙하게 다루지 않는다면 구독 가져오기로 프로필부터 안정화한 뒤 이 글의 분류 단계로 넘어오세요.

2. 꼭 같이 묶어야 하는 호스트 축

Gemini API 호출의 중심은 generativelanguage.googleapis.com 과 그 변형 접미사입니다. 반면 공식 문서·샘플 링크·일부 관리 UI는 ai.google.dev 아래에서 열리고, 콘솔에서 복사한 스니펫도 이 출처를 가리키는 경우가 많습니다. 로그인·토큰 교환은 accounts.google.com 과 OAuth 관련 호스트가 담당하므로, 이 셋이 서로 다른 정책 그룹으로 갈라지면 “키는 맞는데 응답만 없음” 같은 표현으로 관측됩니다.

Webhook이나 Batch를 쓸 때는 공급자 문서에 나오는 상태 조회·콜백 URL의 도메인까지 연결 목록에서 한 줄로 이어지는지 확인해야 합니다. 운영 환경마다 세부 호스트가 늘거나 줄 수 있으니, 인터넷에 떠도는 고정 목록만 복사해 붙여 넣기보다 본인 프로젝트의 실패한 요청부터 수집하는 편이 장기적으로 덜 깨집니다.

팁: 정책 그룹을 둘로 나누고 싶다면 GEMINI_API와 GOOGLE_ACCOUNT처럼 이름을 분리해 두되, 초기 디버깅 단계에서는 의도적으로 같은 그룹에 올려 출구를 맞춘 뒤에만 세분화하세요. 출구가 다르면 증상이 다시 갈라집니다.

3. 권장 점검 순서

  1. 지금 시스템 프록시만인지 TUN 모드까지 켰는지 기록하고, 문제를 일으키는 실행 환경(IDE 통합 터미널·순수 셸·컨테이너)을 구분합니다.
  2. Clash 연결 패널에서 generativelanguage.googleapis.com·ai.google.dev·계정·OAuth 접미사가 기대한 그룹으로 나가는지, DIRECT로 새는지 확인합니다.
  3. fake-ip 사용 시 해석과 실제 연결이 어긋나지 않는지, Google API 접미사에 별도 DNS 정책이 필요한지 봅니다.
  4. 수집한 호스트를 DOMAIN-SUFFIX 규칙으로 로컬 상단 블록에 올리고, 공급자 rule-providers와의 순서 충돌을 정리합니다.
  5. TLS 오류·신뢰 경고가 보이면 프록시보다 먼저 기업 인증서 검사·신뢰 저장소·바이패스 후보를 점검합니다.
  6. 노드 자체를 바꾸기 전에 동일 그룹에서 짧은 응답과 긴 스트림을 번갈아 재현해 지터·패킷 손실 여부를 확인합니다.

4. 시스템 프록시와 TUN: SDK가 빠지는 이유

많은 언어 런타임은 macOS·Windows의 시스템 프록시 테이블을 자동으로 따라가지 않습니다. 그 결과 브라우저로 연 Google AI Studio는 매끄러운데, 터미널에서 돌린 샘플만 상대적으로 느리거나 끊기는 패턴이 반복됩니다. 환경 변수 HTTPS_PROXY를 수동으로 맞추는 방법도 있지만, 팀마다 셸 프로파일이 달라 누락이 생기기 쉽습니다.

TUN은 라우팅 계층에서 잡아 주기 때문에 이런 “일부 프로세스만 DIRECT” 문제를 줄이는 데 유리합니다. 다만 다른 상시 VPN과 동시에 켜면 어댑터 충돌이 나므로, TUN 모드 가이드에 맞춰 켠 뒤 동일 스크립트를 다시 실행해 보세요. 컨테이너 안에서 호출한다면 호스트 네트워크와 게이트웨이가 Clash 쪽을 바라보는지 별도로 확인해야 합니다.

5. DNS·fake-ip: 규칙보다 먼저 흔들리는 부분

Clash 사용자에게 DNS는 “속도” 문제가 아니라 “판정 일관성” 문제로 돌아오는 경우가 많습니다. fake-ip는 체감 지연을 줄여 주지만, 특정 접미사에서만 실제 목적지와 해석 결과가 어긋나면 TLS 협상이 반복되고 SDK는 이를 긴 타임아웃으로 보고할 수 있습니다. Google 계열은 서브도메인마다 다른 엣지를 노리는 패턴이 흔해, API 전용 접미사를 일반 도메인과 같은 DNS 파이프라인에 두지 않는 편이 안전할 때가 있습니다.

실무에서는 generativelanguage.googleapis.com과 ai.google.dev를 테스트 해상에서 각각 조회해 보고, Clash 로그의 도메인 문자열과 비교해 규칙 매칭 전 단계에서 이미 갈라지지 않는지 확인합니다. 필드 이름은 Mihomo·Clash Meta 버전에 따라 다르므로, 최신 예제와 릴리스 노트를 함께 보는 것이 좋습니다.

주의: 광범위한 DOMAIN-SUFFIX,google.com 규칙은 검색·지도·기업 Workspace까지 한꺼번에 끌고 갈 수 있습니다. 로그에 실제로 보인 최소 단위로 올리고, “한 번에 끝나는 목록”이 아니라 운영 중에도 갱신하는 습관을 두세요.

6. 증거 수집: 연결 로그가 최우선

정적 목록에 의존하면 제품 개편이나 리전 차이 때문에 규칙이 쉽게 낡습니다. 대신 실패한 요청 시각 전후의 Clash 연결 기록을 캡처하고, 동일 시각에 브라우저 네트워크 탭이나 SDK 디버그 로그에 찍힌 호스트를 나란히 놓으세요. 실패한 줄의 색이 있는 요청부터 규칙에 올리면 체감 개선이 가장 큽니다.

Webhook과 Batch를 운영 중이라면, 백엔드에서 콜백 URL로 다시 나가는 트래픽까지 같은 기기에서 재현할 수 있는지도 확인합니다. 수신 서버의 방화벽 문제와 클라이언트 측 Clash 규칙 문제는 증상이 비슷해 보이므로, 최소 재현 커맨드와 Clash 필터 문자열을 짝으로 남기면 이후에도 추적이 쉬워집니다.

7. 규칙 예시와 rule-providers 정리

아래는 출발점 예시이며, 정책 그룹 이름은 본인 프로필에 맞게 바꿉니다.

# Example only — replace GEMINI_DEV with your policy group name
rules:
  - DOMAIN-SUFFIX,generativelanguage.googleapis.com,GEMINI_DEV
  - DOMAIN-SUFFIX,ai.google.dev,GEMINI_DEV
  - DOMAIN,accounts.google.com,GEMINI_DEV

개발자 도구에서 추가로 관측된 호스트는 DOMAIN-SUFFIX 또는 DOMAIN으로 하나씩 명시하세요. 공급자의 rule-providers가 넓은 DIRECT 규칙을 앞당겨 버리면 로컬에서 올린 줄이 뒤로 밀립니다. “Google AI 전용 블록”을 파일 상단에 두고, 구독이 갱신될 때마다 순서를 다시 확인하는 운영이 안전합니다.

Clash Meta 계열은 geodata·규칙 공급자 조합에 따라 판정 속도와 메모리 사용이 달라집니다. Gemini 3.1 Flash-Lite처럼 응답 패턴이 가벼운 모델을 대량 호출하는 워크로드에서는 규칙 판정 자체의 지터까지 합산될 수 있으니, 불필요하게 큰 공급자 세트를 중복 로드하지 않도록 프로필을 정리하세요.

운영 습관: 배포 파이프라인에서 쓰는 머신과 개인 노트북의 Clash 프로필을 완전히 동일하게 맞출 필요는 없지만, GEMINI_DEV 블록만큼은 공유해 두면 “한쪽만 실패” 이슈를 줄일 수 있습니다.

8. TLS·SNI·기업망 인증서

프록시는 TLS 종료를 바꾸지 않는 한 핸드셰이크의 SNI와 서버 인증서 체인을 그대로 노출합니다. 회사망에서 루트 신뢰가 추가된 중간 인증서로 재서명하는 환경이라면, 언어 런타임이나 gRPC 스택이 이를 허용하지 않아 빈 응답처럼 보일 수 있습니다. 이때는 노드를 바꾸기 전에 OS 신뢰 저장소·사내 프록시 바이패스 정책·Clash의 인증서 검증 관련 옵션을 함께 검토하세요.

반대로 과도한 바이패스는 보안 정책과 충돌하므로, 테스트 전용 프로필과 업무용 프로필을 분리하는 편이 덜 위험합니다. 어떤 선택이든 조직 규정을 벗어나지 않는 범위에서만 적용해야 합니다.

9. Webhook·Batch 호출을 분리해서 보지 않기

Webhook은 등록 시점의 도메인 검증과 이후 실제 전달 시점의 경로가 다를 수 있습니다. 등록만 성공하고 전달 로그가 비는 경우, 수신 서버 앞단의 WAF·지역 차단과 별개로 클라이언트 측에서 Google 관리 평면 호스트가 다른 출구로 새고 있지 않은지 확인하세요. Batch 작업은 상태 폴링 URL이 길게 유지되는 편이라, 중간 노드의 유휴 세션 타임아웃과 맞물리면 “가끔만 실패” 패턴이 나옵니다.

이 글의 관점에서는 이런 증상을 네트워크 스택 한 층에서 잡기보다, 먼저 Clash 연결 로그에 같은 호스트가 안정적으로 같은 그룹으로 찍히는지 확인하는 것이 비용 대비 효과가 큽니다. 그다음에야 노드 품질·지역·백오프 정책을 조정하세요.

10. 노드 선택: 순간 속도보다 지터

벤치마크 상위 노드라도 짧은 구간에서 패킷 지터가 크면 스트리밍 응답이 자주 끊깁니다. Gemini API는 첫 토큰과 이어지는 토큰 사이의 안정성이 같이 작동하므로, 규칙이 맞는지 확인한 뒤에는 손실이 적은 회선을 고정하거나 자동 페일오버 임계값을 완화하는 편이 낫습니다. 전송 특성 비교는 프로토콜 비교 글을 보조 근거로 쓸 수 있습니다.

11. GUI 워크플로: Clash Verge Rev

연결 패널에서 문자열 필터로 googleapis와 ai.google.dev를 동시에 좁히면 잘못된 DIRECT 류를 빠르게 찾을 수 있습니다. 첫 설치 흐름은 Clash Verge Rev 가이드를 따르세요. 규칙을 고친 뒤에는 DNS 캐시를 비우거나 터미널 세션을 완전히 새로 열어 이전 연결 상태가 남지 않게 하는 것도 재현성을 높입니다.

12. 짧은 FAQ로 남는 헷갈림

Q. 키 제한은 안 걸렸는데도 Flash-Lite만 느립니다. A. 모델 이름과 실제 라우팅된 엔드포인트가 항상 같은 리전을 가리키지는 않습니다. 호스트 문자열을 로그로 먼저 확정하세요. Q. 문서 사이트는 빠른데 API만 끊깁니다. A. 브라우저와 터미널의 프록시 경로가 다릅니다. TUN 또는 환경 변수로 맞춘 뒤 같은 호스트가 같은 그룹으로 나가는지 확인하세요. Q. 회사 맥에서만 TLS 오류입니다. A. 루트 신뢰와 중간 인증서를 점검하고, 사내 검사 정책과 충돌하지 않는 분리 프로필로 테스트하세요.

13. 다른 글과의 관계

이 글은 개발자 API와 Google AI Studio 문서 축을 연결하는 데 초점을 둡니다. gemini.google.com 중심의 웹 프런트·로그인 루프는 웹 전용 분류 글이 더 직접적입니다. Microsoft Foundry 등 다른 클라우드 제공자 SDK는 호스트 세트가 완전히 다르므로, Foundry 대응 글과 혼동하지 마세요. OpenAI 계열은 ChatGPT 분류를 참고하면 축이 분리됩니다.

14. 정리: 로그로 출구를 한 번에 맞추기

Gemini 3.1 Flash-Lite 같은 경량 모델이 GA돼도, 클라이언트 측에서는 여전히 generativelanguage.googleapis.com·ai.google.dev·계정 호스트가 서로 다른 출구로 갈라지며 타임아웃처럼 관측되는 경우가 많습니다. DNS·규칙 순서·프록시 모드를 순서대로 맞추고, Webhook·Batch까지 포함해 연결 로그로 교차 검증하면 불필요한 노드 순환을 줄일 수 있습니다.

범용 프록시 도구는 “한 스위치로 전부 해결”처럼 보이기 쉬운데, 실제 운영에서는 로그·프로필·업데이트가 분산돼 있으면 같은 증상을 반복합니다. 반면 구독·분류·연결 기록이 한 클라이언트에 모여 있으면 Google AI 개발자 트래픽처럼 호스트 수가 많은 축도 빠르게 좁힐 수 있습니다. 웹 전용 도구나 수동 환경 변수 조합만으로는 터미널·컨테이너·백그라운드 잡까지 동일 경로를 보장하기 어렵고, GUI가 없는 경량 프록시는 규칙 충돌을 찾는 데 시간이 더 걸리는 편입니다. → Clash 를 무료로 내려받아 Gemini API 호스트를 한 정책으로 묶고 OAuth까지 같은 출구에서 검증해 보세요