증상 정리 — 문서 순서만 따라 했는데 npm만 헛도는 패턴
GitHub Releases나 README의 npm 설치 명령 한 줄(npx 예시 포함)은 정상 경로에서는 곧 종료되는데, 본 문서가 말하는 정확히 그 명령이 조직 회선에서는 멈춥니다. 흔한 표면 패턴으로는 패키지 인덱스 JSON은 받아오지만 실제 tarball이 있는 CDN 호스트까지 가는 구간만 느린 경우, 또는 npm 메타 패키지는 통과했다가 토큰 교환 브랜치가 DIRECT로 새어 Gemini 응답만 없는 경우가 있습니다. 둘 다 콘솔에는 조용한 대기 상태로 남거나 네트워크 오류 요약 줄 하나만 출력되기 때문에 원인 분리가 어렵습니다. 여기까지는 패키지를 건드릴 필요가 없으며, 라우팅과 DNS가 무엇을 가리켰는지부터 되짚는 편이 비용 대비 빠릅니다.
HTTP/3(QUIC)가 선호되어 UDP가 규칙에서 빠지면 다운로드만 간헐적으로 느려지는 현상처럼 보입니다. 이 경우 브라우저는 다른 스택 우선 순위와 내부 폴백으로 넘어가도, Node 런타임의 패치 다운로드는 동일 패턴으로 반복 타임아웃을 만들 수 있습니다. TUN이 꺼져 있거나 QUIC 경로만 예외 처리된 프로파일이면 해당 차이가 큽니다. 활성 순서와 스택 선택은 Clash Verge Rev TUN 가이드와 gvisor·system TUN 비교 글을 교차 검토하면 벤더/OS 조합별로 깔끔합니다.
왜 Gemini CLI처럼 터미널 중심 워크플로에서는 TUN이 기본 책임에 가까운가
npm과 Node는 운영체제마다 시스템 프록시 읽기 신뢰도가 크게 다르고 macOS(Keychain)·Windows(WPAD)·원격 세션에서는 동일 변수라도 결과가 나뉩니다. IDE 통합 터미널은 별도 셀 프로파일을 읽으며, 패키지 관리 작업 일부는 심지어 하위 프로세스로 다시 변수를 무시하기도 해서 사용자가 같은 창이라고 믿던 세션끼리 경로가 갈립니다. GUI에서 켠 Mixed 포트만 신뢰하면 터미널 패치 다운로드가 반쯤 직통인 착각이 재현되기 어렵지 않습니다. TUN은 커널이 가상 인터페이스로 트래픽을 받아 들이므로 애플리케이션 계층이 프록시를 안다는 전제 없이 같은 출구 규칙을 공유하게 되며, 패키지 캐시를 비우거나 버전 업 시 반복되는 대용량 패치에 특히 안정적인 편입니다. 다만 회사 장비 정책으로 가상 NIC 설치 자체가 막혀 있는 경우에는 보안 허용 범위 안에서 한정적으로만 적용해야 합니다.
Gemini CLI 특유의 사용자 경험은 인증 과정까지 한 파이프에 태워야 한다는 데 있습니다. 즉 패키지 registry 경로 외에 accounts.google.com처럼 브라우저가 직통으로 처리하는 패밀과, 터미널이 교환해야 하는 oauth2.googleapis.com·generativelanguage.googleapis.com 계열 같은 API 패밀이 서로 다른 DNS 응답을 받으며 출구 노드까지 갈라지면 결과만 보면 인증 버튼이 아무 문제 없는데도 CLI가 무한 재시도에 빠져 보입니다. 이럴 때 레이어 하나를 아래부터 정렬해야 하므로 TUN 활성 상태에서 동일 테스트를 재현하는 순서가 가장 설명 가능합니다.
글의 범위와 비범위
Gemini 모델 제공 방식과 청구, CLI 하위 명령 옵션, 프롬프트 템플릿 같은 기능 문서 내용 자체를 대체하지 않습니다. 이 글 역시 구체 파라미터를 공식 채널보다 신뢰할 수 있는 출처라고 단정하지 않습니다. 우리가 다루는 것은 FQDN 문자열 목록 확보 방법, 해당 문자열들이 규칙 트리의 어디에서 첫 매칭되는지, Fake IP와 스니퍼가 같은 문자열 세트를 보는지처럼 클래시 레이어 디버깅에 한정합니다. 예시 규칙과 curl 호스트 문자열은 시점별로 업데이트될 수 있으니 문자열 고정이라기보다 기록 패턴으로만 활용해야 합니다.
패키지 범위 이름도 릴리스마다 변경됩니다. 따라서 사용자가 따라 붙여야 하는 정확한 scope 문자열 대신 패키지 README를 그대로 복사한 토큰이 있다면 해당 이름을 레지스트리 조회 과정 로그와 같이 놓고 봐야 하며 본 글에서는 패키지 품질 검증 방법을 전제하지 않습니다. 기능적 오류 진단에는 공식 버그 트래커가 우선해야 합니다.
1오류·연결 패널·curl을 맞춰 호스트 문자열 만들기
첫 디버깅 루프는 문자열 채굴입니다. npm의 경우 registry.npmjs.org 본류 외에도 tarball이 놓인 패키지 전용 버킷 패밀 또는 팀 거버넌스 미러 문자열(npmmirror.com 등)까지 한 번의 설치 과정 안에서 동시에 등장합니다. CLI가 패치를 추가로 받거나 스크립트가 외부 URL을 참조하면 그 도메인이 따로 들어오기 때문에 실패 줄에 찍히는 문자열 하나라도 놓치지 말 것을 권합니다. Gemini 경로에서는 Google API 후보 패밀로 aistudio.google.com·보조 정적 자원 패밀이 함께 붙습니다. 문자열 목록 확보 후 Clash 로그 패널에서 해당 시각 줄과 첫 규칙 매칭을 정렬해야 합니다. 아래 명령은 TLS 핸드셰이크 수준 검증 예시입니다.
# Example — replace URLs; widen -m on slow exits
curl -v -m 25 https://registry.npmjs.org/@google/%2fgemini-cli
curl -v -m 25 https://generativelanguage.googleapis.com/
curl -v -m 25 https://oauth2.googleapis.com/각 테스트를 연속으로 두 번 돌리면 DNS 캐시에 의존했는지, 노드 교체에 따라 지연이 흔들리는지가 분리되어 이후 수정이 한 변수씩 줄어듭니다. 패킷이 중간 장비에서 끊기는 로그 패턴 해석에는 연결 리셋 글 예시 표현식을 활용하면 좋습니다.
2TUN 켜기와 LAN·직장 VPN 예외 처리
사용자 인터페이스에서 TUN을 켠 뒤 기본 라우트가 회사 전용 어댑터와 이중 매핑되어 있지 않은지 빠르게 확인합니다. 사내 npm 미러처럼 허브에서만 허용된 주소대는 규칙 트리 상단에 DIRECT나 내부 전용 노드로 명시해야 하고 LAN 대역·루프백은 패턴 레퍼런스마다 이름이 미묘하게 달라 새는 경우가 많으므로 사전에 명시되어 있는지 검토해야 합니다. Windows 환경이면 윈도우 설치 초기화 튜토리얼을 끝내고 예외 허브를 줄이면 변수가 줄어듭니다. Apple Silicon이라면 해당 전용 패키지에 맞춰 드라이버 충돌 정도까지 한 번 확인하는 편이 안전합니다.
회사 장비에서는 제로 트러스트 에이전트가 가상 어댑터와 충돌하는 사례가 있으므로 충돌 시점을 정확히 기록해 보안 또는 인프라 팀에게 공유해야 합니다. 본 글에서는 승인 받은 디바이스를 전제합니다.
3분류 초안 예시로 npm 패밀과 Google 패밀을 한 그룹에 묶기
실무 프로파일에는 이미 거대 RULE-SET이 있어 직수정이 무섭습니다. 따라서 사용자 조각 프로파일을 Mixin으로 삽입하면 베이스 YAML을 깨트리기 어렵습니다. 핵심은 패널 로그와 일치하게 추출한 문자열 세트 전체를 같은 프록시 정책 그룹 이름으로 향하게 하여 첫 프레임부터 출구 노드가 바뀌지 않도록 하는 일입니다.
# Illustration — replace PROXY_AI; narrow catch-all GEOIP/MATCH 위에 배치
rules:
- DOMAIN-SUFFIX,npmjs.org,PROXY_AI
- DOMAIN-SUFFIX,google.com,PROXY_AI
- DOMAIN-SUFFIX,googleapis.com,PROXY_AI
- DOMAIN-KEYWORD,nodejs,PROXY_AI
# 브라우저 캡처·OAuth·패치 스크립트가 찍히는 문자열 추가
- MATCH,DIRECT참고: Gemini CLI가 바라보는 패키지 scope와 설치 이름은 릴리스마다 달라질 수 있습니다. 문자열 패턴 고정이라기보다 자신에게 찍히는 문자열 목록 최상단에 두고 테스트하는 순서가 중요합니다. 규칙은 위에서 아래로 매칭됩니다.
npm config proxy와 Mixed 포트 단독 사용의 함정
조직에서는 npm config set proxy http://127.0.0.1:포트 형태만으로 레지스트리 대역을 채워도 충분하다고 믿지만, 패키지 postinstall 스텝 혹은 앱이 다른 모듈로 넘긴 하위 패치까지 동일 변수를 따라가야 합니다. 누군가 NODE_TLS_REJECT_UNAUTHORIZED 같은 비권장 환경을 섞거나 사내 CA가 개입했을 때 증상이 프록시가 아니라 인증 레이어라며 혼합됩니다. TUN이 켠 상태에서 변수를 빈 값으로 줄인 뒤 동일 테스트를 하는 비교 플립은 원인 레이블을 분리하기에 특히 간단합니다. 반대로 사내에서는 특정 패밀이 반드시 직통이어야 하므로 이 경우 변수 기반으로만 분리하는 방식 유지 여부를 선택해야 하는데 편차가 큽니다. Git 레이어나 패키지를 동시에 쓰면 WSL Git npm 연계 글과 같이 검토 속도가 빨라집니다.
4DNS·Fake IP·HTTPS 스니퍼를 같은 축으로
브라우저 Secure DNS와 코어 DNS 설정이 각각 존재하면 표면상 이름이 같지만 실제 흐르는 패킷 패밀 차이로 규칙 첫 줄이 헛바퀴됩니다. 수정은 한 변수씩에 집중하세요: 먼저 resolver 모드, 두 번째 fake-ip 필터, 세 번째 스니퍼 옵션. 자세히는 DNS 유출 방지 가이드, HTTPS 스니퍼 설명 순으로 읽는 편을 권합니다. 도메인 앞머리 문자열 교정이라도 서로 다른 모듈이 서로 다른 룰 집합을 보고 있다면 교정이 소용 없습니다.
5디버깅에서는 selector 고정 후 npm 재시도하기
url-test가 공격적인 프로파일이면 대량 tarball 수신 세션이 교체되며 끊긴 것처럼 오해할 여지가 큽니다. 문제 격리 기간에는 selector 하나로 노드를 고정하고 다시 패키지를 설치하거나 npx 캐시를 비운 뒤 실행해 보세요. 자동 헬스체인과 역할 교체 패턴 재도입에는 fallback 글 가이드를 우선 따라가 한 번에 많은 변수를 회전하지 않도록 합니다. 마지막으로 CLI 초기 명령이 실제 API 호출까지 이어졌을 때도 동일 패널 줄에 나타나는지 확인해야 합니다. 일부 패키지는 첫 패치까지는 성공했다가 초기 채널 테스트에서 시간을 잡아먹으므로 기록 순서까지 스냅샷으로 두는 게 좋습니다.
WSL2·컨테이너·원격 셀에서 같은 트릭이 통하지 않을 때
Windows 호스트 위 WSL 또는 컨테이너에서는 호스트 라우팅 표가 공유되지 않아 GUI에서 켠 TUN 결과가 즉시 내려오지 않을 수 있습니다. 이 경우 브리지 라우팅이나 명시 게이트웨이 같은 추가 조정이 들어가야 하므로 해당 환경일 때는 호스트 패턴과 게스트 패턴을 따로 기록해야 합니다. 절차는 WSL 안내와 섞어보면 덜 헤맵니다. 동일 패턴이 다른 Linux 배포판에도 반복된다면 해당 배포판의 nftables 또는 firewalld 정책이 Clash 패킷을 다시 라우팅하는지 검토합니다.
빠른 자가 진단 목록
- Gemini CLI 설치 과정 각 단계 줄에 이름이 들어있는 문자열 목록 전체 기록했는가.
- 그 문자열 각각이 사용자 프로파일에서 첫 줄 어느 규칙에 걸렸고 어떤 정책 그룹을 탔는가.
- TUN 상태 flip 시 문제가 바뀌는가 바뀌지 않으면 변수가 프록시가 아니라 패키지·인증서일 가능성이 있는가.
- resolver와 브라우저 DNS가 교차 덮어쓰고 있지는 않은가 한 번 하나만 바꾸었는가.
- 설치 테스트와 API 호출 테스트를 분리 재현했고 로그 줄 시각 순서까지 맞았는가.
FAQ
npm 레지스트리 문자열만 프록시에 넣어도 충분한가요
패키지 JSON과 패치 tarball이 같은 호스트 문자열이라는 보장은 없으며 Gemini 흐름은 Google 계열 문자열까지 동시에 붙습니다. 한 호스트만 리스트 업하면 패치가 새는 구간 또는 인증 줄이 새는 구간 때문에 전체 과정만 실패한 것처럼 보입니다. 관측 기반 목록 업을 권장합니다.
사내 레지스트리 미러에서는 어디부터 손댄가요
미러 문자열 목록 최상단에 두고 패치가 회사 고정 레이턴시를 넘었는데도 TLS 레이어만 흔든다면 CA 신뢰 문제일 수 있으므로 프록시 이슈와 분리해야 합니다. 로그 줄을 동시 라인 타임라인 기록 형태로 남길 가능성까지 열어 두세요.
정책·토큰 취급
회사 규정·클라우드 데이터 처리 규약을 지키세요. 인증 줄은 공유 채팅실에 반입하지 마시고 테스트용 토큰은 만료 시간을 명시해서 로컬에만 두며 외부에 전송 줄을 줄입니다.
준수: 조직 장비에서는 보안팀 허용 범위만큼 패킷 캡처와 드라이버 활성 작업을 수행하세요. 불필요한 네트워크 추적 줄은 공유하지 않도록 합니다.
맺음말
google-gemini/gemini-cli는 2026년에도 활발하게 릴리스가 진행되어 CLI 기반 업무 속도 향상에 자주 따라붙지만, 패키지 품질과 별개로 조직 회선이라는 외연 조건이 붙었을 때 npm·Gemini 문자열 패밀이 갈라지며 체험 한 번만으로 신뢰를 잃기 쉽습니다. 패킷 레벨을 TUN 아래 같은 축으로 옮기고 문자열 각각마다 명시된 첫 줄 규칙을 패널 줄과 일치하게 정리한 뒤 DNS·Fake IP를 동시 수정하지 않는 습관이 가장 설명 가능한 순서였습니다.
많은 일반 목적 클라이언트는 YAML을 손 직 편집해야 하거나 터미널마다 환경 변수를 새로 깔아야 해 실수 레이블이 많습니다. Clash 계열 클라이언트는 패널 하나에서 DNS·분류 규칙·TUN·프로파일 교체까지 실험이 가능해서 이런 수요에 덜 깨지만 동일 가치입니다. 따라서 아직 쓰지 않았다면 Clash 앱 무료 다운로드로 설치해서 본문 순서를 그대로 밟으며 동일 테스트를 비교하면 설치 과정 줄이 줄어든 모습 확인에 도움이 됩니다.