증상 — 문서는 따라 했는데 uvx·npm만 멈출 때
공식 가이드의 uvx 한 줄이나 npx google-agents-cli 같은 예시는 정상 네트워크에선 곧바로 통과합니다. 그러나 기업망·지역 회선·불안정한 출구를 쓰면 첫 화면은 뜨는데 wheels·tarballs를 받아오는 PyPI 단계만 지연되거나, npm 메타데이터는 열리는데 실제 tarball 호스트만 다른 지역으로 돌려져 끊기는 패턴이 흔합니다. 또 브라우저로 시작한 OAuth 흐름 뒤 토큰 교환 호출이 회사 정책상 직통으로만 나가면 CLI 쪽 검증 단계만 실패합니다. 에러 문자열에는 ECONNRESET·timed out·TLS 핑거프린트 관련 단서가 함께 찍히는데, 동일 문구라도 근본 원인은 레지스트리 경로 두세 갈래가 한 번에 흔들릴 때가 많습니다.
HTTP/3(QUIC) 우선 순위 때문에 UDP가 규칙 밖 DIRECT로 새는 환경에서는 파일 다운로드만 간헐적으로 느려진 것처럼 보이기도 합니다. 이 경우 TUN이 꺼져 있거나 UDP가 프록시 그룹을 타지 않으면 체감 타임아웃이 커집니다. 활성화 절차는 Clash Verge Rev TUN 가이드를 기준으로 하되, 스택 선택은 gvisor·system 비교 글을 참고해 OS·보안 제품과의 충돌이 적은 쪽을 고르세요.
왜 터미널은 TUN이 기본 답에 가깝나
uv는 Rust 기반으로 자체 TLS·HTTP 스택을 가져가고, Node·npm도 시스템 프록시를 읽는 방식이 플랫폼마다 다릅니다. macOS Keychain·Windows WPAD·Linux 데스크톱 환경 변수가 섞이면 “브라우저만 프록시를 탄다”는 착시가 생깁니다. 세션마다 HTTP_PROXY를 수동으로 맞추는 방법도 있지만 IDE·작업 스케줄러·CI용 셸이 서로 다른 프로파일을 읽으면 재현이 깨집니다. TUN은 커널이 가상 인터페이스로 패킷을 넘기므로 애플리케이션이 프록시를 “알아야 할” 부담이 줄고, 긴 다운로드·리다이렉트 연쇄에 유리합니다. 회사 정책으로 가상 어댑터 설치가 막히면 예외이니 허용 범위 안에서만 적용하세요.
이 글이 다루는 범위
에이전트 런타임 명령·모델 선택·청구 같은 제품 기능은 공식 릴리스 노트와 문서를 따릅니다. 여기서는 외부 지연 표면만 다룹니다. 즉 어떤 FQDN이 로그에 찍히는지, 규칙 트리에서 어디에 첫 매칭되는지, DNS 모드와 fake-ip-filter·스니퍼가 같은 방향을 보는지에 집중합니다. 패키지 인덱스 URL·CDN 호스트 문자열은 시점에 따라 바뀔 수 있으니 아래 YAML·명령은 패턴 예시로만 두고 실제 문자열은 본인 로그 기준으로 바꿉니다.
1로그·curl로 레지스트리 호스트 관측
실패 줄에 나오는 호스트 이름을 그대로 모읍니다. uv는 PyPI 단순 패턴 외에 files.pythonhosted.org·메타 간접 레이어도 거칩니다. npm은 registry.npmjs.org와 실제 패키지 tarball이 놓인 registry.npmmirror.com 대체 레지스트리나 CDN 하위 호스트가 갈라집니다. Google 로그인·토큰이 섞인다면 oauth2.googleapis.com·accounts.google.com 같은 묶음이 추가됩니다. 터미널 재현 직후 Clash 연결 패널에서 첫 매칭 규칙과 타임스탬프를 맞춰 보세요. 아래는 TLS 핸드셰이크만 빠르게 보는 예시입니다.
# Example — replace hosts; increase -m if your path is slow
curl -v -m 25 https://registry.npmjs.org/
curl -v -m 25 https://pypi.org/simple/
curl -v -m 25 https://files.pythonhosted.org/단계별 초를 적어 두면 이후에 DNS만 손댔는지 규칙만 손댔는지 분리할 수 있습니다. 연결 리셋 로그 읽기는 연결 리셋 글을 참고하세요.
2TUN 켜기와 예외 범위
클라이언트 UI에서 TUN을 켠 뒤 사내 VPN·제로 트러스트 에이전트와 기본 라우트가 이중으로 잡히지 않는지 확인합니다. 사내만 허용된 npm 미러·사설 PyPI는 fake-ip-filter·직통 규칙으로 먼저 고정하고, 루프백·LAN 대역은 위쪽에 둡니다. Windows 초기 설치가 필요하면 Windows Clash 설치 튜토리얼부터 정리한 뒤 TUN을 켜면 변수가 줄어듭니다.
3분류 규칙 초안 — npm·PyPI·Google 묶음
실제 프로파일에는 거대 RULE-SET·GEOIP 블록이 이미 있으므로 사용자 전용 조각을 Mixin으로 덧붙이는 방식이 안전합니다. 핵심은 관측한 호스트 전부를 같은 정책 그룹으로 보내 첫 프레임부터 출구가 흔들리지 않게 하는 것입니다.
# Illustration — replace PROXY_DEV; keep order above catch-all GEOIP/MATCH
rules:
- DOMAIN-SUFFIX,registry.npmjs.org,PROXY_DEV
- DOMAIN-SUFFIX,npmjs.org,PROXY_DEV
- DOMAIN-SUFFIX,pypi.org,PROXY_DEV
- DOMAIN-SUFFIX,pythonhosted.org,PROXY_DEV
- DOMAIN-SUFFIX,googleapis.com,PROXY_DEV
- DOMAIN-SUFFIX,google.com,PROXY_DEV
# Add exact hosts from your logs (OAuth, CDN, regional mirrors)
- MATCH,DIRECT참고: 대체 레지스트리를 쓰면 tarball 호스트가 공식 문서 예시와 다릅니다. 팀에서 고정한 미러가 있다면 그 FQDN을 목록 맨 앞에 두고, 업데이트 때마다 로그로 검증하세요. 규칙은 위에서 아래로 첫 매칭이 승리합니다.
npm·uv 환경 변수와 TUN의 관계
npm config set proxy·HTTPS_PROXY만으로도 동작하는 경우가 있지만, uv는 UV_HTTP_TIMEOUT·인덱스 URL·TLS 검증 옵션이 추가로 얽힙니다. TUN이 켜진 상태에서는 환경 변수를 비우고도 동일 경로로 나가는지 먼저 비교해 보는 것이 디버깅에 유리합니다. 반대로 회사 정책상 코어가 직통이어야 하는 호스트가 섞이면 변수 기반 분리가 필요할 수 있습니다. 일반적인 Git·npm 혼합 시나리오는 WSL2·Git·npm 연계 글과 함께 보는 편이 빠릅니다.
4DNS·FakeIP·스니퍼 정합성
브라우저 Secure DNS와 코어 DNS가 동시에 켜져 있으면 이름만 같아도 연결 패널의 대상 표기가 달라져 규칙이 헛도는 것처럼 보입니다. fake-ip-filter 범위와 스니퍼를 함께 맞추고, 변경은 한 번에 한 축만 움직이세요. 세부는 DNS 유출 방지 가이드와 HTTPS 스니퍼 글을 참고합니다.
5정책 그룹 고정과 설치 재시도
대용량 패키지를 받을 때 url-test가 공격적으로 노드를 바꾸면 세션이 끊긴 것처럼 보입니다. 디버깅 동안에는 selector로 단일 노드를 고정한 뒤 uvx·npm을 다시 실행하세요. 자동 장애조치 패턴은 url-test·fallback 글을 따릅니다. 안정성이 확인되면 자동 그룹을 되살립니다.
WSL2·원격 개발 환경
Windows에서 Docker·WSL 안의 uv·Node까지 같은 경로로 맞추려면 호스트 게이트웨이·포워딩이 추가로 필요합니다. 호스트 OS의 TUN만으로 게스트 브리지가 자동 연결되지는 않습니다. 절차는 WSL2·Git·npm 연계 글을 우선 적용하세요.
설치 안정성 간이 체크리스트
- 오류 줄에 등장한 모든 호스트 이름을 목록화했는가.
- 그 목록이 규칙 트리 어디에서 첫 매칭되는지 연결 패널과 시간축이 일치하는가.
- TUN ON/OFF에 따라 증상이 근본적으로 바뀌는가, 바뀐다면 앱 레벨 프록시에 남은 패스는 없는가.
- 브라우저 DoH·OS DNS·코어 DNS가 서로 덮어쓰지 않는가.
- 한 번에 한 가지 설정만 바꿨는가(동시에 여러 스위치를 움직이면 원인 분리가 어려움).
자주 묻는 질문
npm 레지스트리만 프록시에 넣으면 되지 않나요
메타데이터와 tarball이 서로 다른 호스트로 갈라지면 부분 최적화가 됩니다. google-agents-cli 설치는 PyPI와 Google 인증 계열까지 동시에 붙는 경우가 많아 한 호스트만 프록시에 넣기 어렵습니다.
사내 npm·PyPI 미러를 쓰는 경우
미러 FQDN을 관측 목록 최상단에 두고, 미러가 내부 CA를 쓰면 TLS 검증 실패가 별도로 생깁니다. 이 경우 프록시 문제와 인증서 신뢰 문제를 분리해 기록하세요.
정책·약관 준수
조직 네트워크 규정과 클라우드 데이터 처리 지침을 지키세요. 토큰·샘플 응답은 공개 채널에 올리지 말고, 공식 문서의 엔드포인트 변경을 수시로 확인합니다.
준수: 회사 보안·로깅 정책을 위반하지 마세요. 진단 중 수집한 URL·키는 로컬에만 보관하고 불필요한 전송을 줄입니다.
맺음말
Google Agents CLI 설치는 짧은 재시도만 반복돼도 전체가 “환경이 망가졌다”처럼 느껴집니다. 브라우저와 달리 npm·uv 런타임은 프록시 인식이 들쭉날쭉하므로 TUN으로 트래픽을 한 파이프에 올린 뒤, 관측 기반으로 레지스트리·Google 묶음을 분류 규칙에 고정하고 DNS·FakeIP를 같은 축에서 맞추는 세트가 가장 재현성이 높습니다. 이미 다른 CLI 글에서 익힌 패턴을 그대로 이식하되, 패키지 인덱스와 인증 호스트 목록만 최신 로그로 갱신하면 이후 에이전트 도구에도 그대로 적용할 수 있습니다.
한편 범용 프록시 유틸리티는 여전히 긴 설정 파일을 손으로 맞추거나 터미널마다 환경 변수를 중복 정의해야 해 실수 여지가 큽니다. Clash 계열은 GUI에서 프로파일과 규칙 트리를 바로 열어보고 Meta 코어의 DNS·TUN·프로세스 분기까지 한 제품군에서 실험할 수 있어 에이전트 CLI를 자주 갱신하는 개발자에게 시간을 아껴 줍니다. 아직 쓰지 않았다면 Clash 클라이언트를 무료로 받아 본문 순서대로 uvx·npm 설치를 다시 실행해 보고, 동일 명령이 안정적으로 끝까지 도달하는지 직접 비교해 보시길 권합니다.