브라우저는 되는데 npm·pip는 실패하는 이유
브라우저에서는 웹사이트가 열리는데 터미널에서 npm install이나 pip install을 실행하면 시간 초과, 연결 거부, 이름 해석 오류가 발생하는 경우가 있습니다. 이는 인터넷 전체가 끊긴 것이 아니라 브라우저와 터미널의 네트워크 경로가 다를 수 있기 때문입니다. 브라우저는 시스템 프록시 설정을 따르는 반면, 일부 명령줄 도구와 개발 환경은 해당 설정을 자동으로 읽지 않습니다.
Clash의 시스템 프록시 모드만으로 모든 앱의 연결을 보장하기는 어렵습니다. 터미널에서 실행되는 패키지 관리자, Git, IDE의 확장 프로그램, 컨테이너 도구는 각기 다른 네트워크 동작을 할 수 있습니다. TUN 모드는 가상 네트워크 인터페이스를 통해 시스템 트래픽을 Clash로 전달하므로, 앱별 프록시 설정을 적용하기 어려운 환경에서 유용합니다. 다만 TUN을 켰다고 해서 모든 연결 오류가 자동으로 해결되는 것은 아닙니다. DNS, 권한, 규칙, 패키지 저장소 상태를 함께 확인해야 합니다.
이 가이드의 범위
Clash Verge, Clash Verge Rev 및 Mihomo 기반 데스크톱 환경을 중심으로 TUN 설정, 패키지 관리자 연결 확인, 오류 진단 순서를 설명합니다. 메뉴 이름은 클라이언트와 버전에 따라 다를 수 있습니다.
1TUN 모드가 터미널 연결에 도움이 되는 원리
일반적인 시스템 프록시는 앱이 프록시 주소를 인식하고 이를 사용해야 동작합니다. 따라서 브라우저는 프록시를 이용하더라도 터미널에서 실행한 Node.js나 Python 프로세스는 직접 연결을 시도할 수 있습니다. 반면 TUN은 운영체제의 라우팅 경로에 가상 인터페이스를 추가하여, 앱이 별도로 프록시 주소를 지정하지 않아도 네트워크 트래픽을 Clash 코어로 넘길 수 있게 합니다.
Clash에 도착한 트래픽은 설정의 DNS와 규칙을 거쳐 DIRECT 또는 선택한 프록시 그룹으로 전달됩니다. 그러므로 TUN은 트래픽을 Clash까지 가져오는 역할이고, 실제 목적지로 연결할 경로는 규칙과 노드가 결정합니다. 저장소 도메인이 잘못된 규칙에 걸리거나 선택한 노드가 해당 주소에 연결할 수 없다면 TUN을 켜도 설치는 실패할 수 있습니다.
| 방식 | 터미널 도구에서의 특징 | 확인할 점 |
|---|---|---|
| 시스템 프록시 | 프록시 설정을 따르는 앱에는 편리하지만 모든 CLI 도구가 이를 자동으로 사용하는 것은 아닙니다. | 앱별 환경 변수나 프록시 설정이 필요한지 확인합니다. |
| TUN 모드 | 프록시를 별도로 지원하지 않는 앱의 트래픽도 Clash 규칙으로 처리할 수 있습니다. | 가상 네트워크 인터페이스, DNS, 권한 및 규칙이 정상인지 확인합니다. |
| 명령줄 프록시 변수 | 특정 세션이나 도구만 프록시로 보내고 싶을 때 유용합니다. | TUN과 함께 설정하면 이중 프록시나 예상치 못한 경로가 생길 수 있습니다. |
먼저 확인하세요
TUN은 네트워크 경로를 바꾸는 기능입니다. 회사나 학교 네트워크 정책, 저장소 이용 약관, 관리 장치의 보안 규칙을 우회하는 용도로 사용하지 말고 해당 환경의 정책을 먼저 확인하세요.
2Clash에서 TUN 모드와 DNS 설정하기
설정을 바꾸기 전에는 구독이나 현재 프로필을 백업하고, Clash 코어가 Mihomo인지 확인하세요. 메뉴 명칭은 앱 버전에 따라 다르지만 보통 설정 화면에서 TUN Mode, Service Mode 또는 네트워크 관련 항목을 찾을 수 있습니다. 관리자 권한이 필요한 기능을 켤 때는 운영체제의 권한 요청을 승인해야 합니다.
- Clash Verge 또는 Clash Verge Rev에서 Mihomo 코어를 선택하고 프로필이 정상적으로 로드되는지 확인합니다.
- 설정에서 TUN 모드를 켭니다. 서비스 설치나 관리자 권한 승인을 요구하면 클라이언트가 안내하는 절차를 따릅니다.
- 모드가 Rule인지 확인하고, 테스트할 패키지 저장소 도메인이 원하는 프록시 그룹으로 연결되는지 규칙을 점검합니다.
- DNS 설정에서 사용 중인 프로필의 DNS 기능과 TUN 연동 상태를 확인한 뒤 Clash를 다시 시작합니다.
- 클라이언트에서 지원하는 코어와 TUN 기능을 확인합니다. 운영체제에서 네트워크 확장 또는 VPN 구성을 허용해야 할 수 있습니다.
- TUN을 켜고 권한 요청을 승인한 뒤, 앱 화면에서 인터페이스가 활성화되었는지 확인합니다.
- 터미널을 새로 열어 테스트합니다. 기존 셸에 남아 있는 프록시 환경 변수는 새 연결에도 영향을 줄 수 있습니다.
DNS는 도메인 이름을 IP 주소로 바꾸는 과정입니다. 웹사이트가 열려도 패키지 저장소 도메인의 조회가 실패하면 npm이나 pip는 연결을 시작하지 못합니다. Clash의 DNS 설정에서 현재 프로필이 지정한 서버를 사용하고 있는지, TUN 사용 시 DNS 요청이 Clash를 통과하는지 확인하세요. DNS 서버 주소를 무작정 여러 개 추가하기보다, 프로필의 기존 설정과 클라이언트 문서를 기준으로 한 번에 하나씩 변경하는 편이 원인 파악에 좋습니다.
규칙을 바꿀 때
도메인 규칙은 일반적으로 더 넓은 규칙이나 최종 규칙보다 앞에 두어야 원하는 그룹에 먼저 일치합니다. 실제로 어떤 규칙이 적용되었는지는 Clash의 연결 기록에서 목적지와 매칭된 규칙을 함께 확인하세요.
3npm·pip 연결을 명령줄에서 검증하기
TUN을 켠 뒤에는 곧바로 전체 프로젝트 설치를 다시 실행하기보다, DNS 조회와 HTTPS 연결을 차례로 확인하세요. 아래 명령은 연결 상태를 진단하기 위한 예시입니다. 셸이나 운영체제에 따라 사용할 수 있는 명령이 다를 수 있으며, 오류 메시지에는 사설 저장소 주소나 인증 정보가 포함되지 않도록 주의해야 합니다.
DNS 조회 결과가 나오지 않으면 우선 Clash의 DNS 상태와 TUN 인터페이스를 확인합니다. DNS는 성공하지만 curl이 시간 초과되면 선택한 노드, 규칙, 방화벽 또는 저장소 접근 가능성을 점검하세요. HTTP 상태 코드가 반환되면 서버까지 연결된 것입니다. 다만 인증 오류, 권한 오류, 저장소의 일시적 장애는 네트워크 경로 문제와 별도로 해결해야 합니다.
패키지 관리자 프록시 설정 확인
TUN이 정상적으로 동작한다면 npm이나 pip에 별도의 프록시를 추가하지 않고 먼저 테스트하는 것이 좋습니다. 이전에 수동 프록시를 설정한 적이 있다면 현재 값이 남아 TUN과 충돌할 수 있습니다. 사용 중인 프록시가 로컬에서 실제로 열려 있고 해당 포트가 올바른지 모르는 상태에서 임의의 주소를 복사하지 마세요.
명령이 실패하면 전체 오류 중 첫 번째 네트워크 관련 메시지를 확인하세요. ENOTFOUND나 이름 해석 오류는 DNS, ECONNREFUSED는 잘못된 주소나 포트, 시간 초과는 경로 또는 노드 품질을 먼저 의심할 수 있습니다. TLS 인증서 오류가 발생했을 때 인증서 검증을 끄는 방법으로 해결하려 하지 말고, 시스템 시간과 인증서 저장소, 검사 프록시 여부를 확인하세요.
검증 기준
DNS 조회, HTTPS 응답, 패키지 메타데이터 조회가 각각 성공하면 기본 경로가 정상일 가능성이 높습니다. 마지막으로 실제 프로젝트에서 잠금 파일과 기존 패키지 버전을 유지한 채 설치를 확인하세요.
4자주 발생하는 문제와 점검 방법
문제가 계속되면 설정을 한꺼번에 바꾸지 말고, TUN 상태 → DNS → 규칙과 연결 기록 → 명령줄 환경 변수 → 패키지 관리자 설정 순으로 확인합니다. 한 항목을 바꿀 때마다 같은 테스트를 반복하면 어떤 변경이 효과가 있었는지 알기 쉽습니다. Clash 연결 기록에서 설치 시도 시각의 요청을 찾아 목적지, 규칙, 선택된 노드를 비교하는 것도 좋은 방법입니다.
- 브라우저만 연결됨: 시스템 프록시만 켜져 있는지 확인하고, CLI 트래픽이 TUN을 통과하는지 테스트합니다.
- 모든 도메인이 조회되지 않음: DNS 설정과 TUN 인터페이스 상태를 확인하고, 최근 변경한 DNS 항목을 되돌려 비교합니다.
- 특정 저장소만 실패함: 해당 저장소의 접속 가능 여부와 Clash에서 매칭된 규칙, 노드 연결을 확인합니다.
- 설치 중 연결이 반복해서 끊김: 안정적인 노드로 바꿔 재현 여부를 확인하고, 저장소 서버 장애나 패키지 크기도 고려합니다.
TUN을 켰는데 관리자 권한 오류가 납니다
일부 운영체제에서 가상 네트워크 인터페이스나 시스템 라우팅을 변경하려면 별도의 서비스 또는 권한 승인이 필요합니다. 오류 메시지에 표시된 기능을 클라이언트 설정에서 활성화하고, 운영체제의 보안 확인 창이 차단되지 않았는지 확인하세요. 알 수 없는 스크립트나 출처가 불분명한 관리자 명령을 실행하지 말고, 사용 중인 클라이언트의 공식 배포 및 문서를 이용하세요.
TUN을 사용하면 HTTP_PROXY도 설정해야 하나요?
대부분의 경우 먼저 TUN만 켠 상태로 확인하면 됩니다. HTTP_PROXY, HTTPS_PROXY, ALL_PROXY가 이미 설정되어 있다면 CLI가 TUN 경로 대신 해당 프록시를 이용하거나 연결을 두 번 우회할 수 있습니다. 현재 셸에서 값을 확인하고, 용도를 모르는 설정은 무작정 덮어쓰기보다 설정한 프로그램이나 셸 초기화 파일에서 출처를 찾으세요.
pip에서 인증서 오류가 나면 검증을 꺼도 되나요?
아니요. 인증서 검증을 비활성화하면 중간자 공격에 취약해질 수 있습니다. 시스템 날짜와 시간, Python의 인증서 저장소, 기업 네트워크의 TLS 검사 정책을 확인하고 필요한 인증서는 관리자나 저장소 운영자가 제공한 신뢰 가능한 경로로 설치해야 합니다.
TUN이 켜져 있는데 npm install이 계속 실패합니다
Clash 연결 기록에서 패키지 저장소 요청이 보이는지 먼저 확인하세요. 기록이 없다면 CLI가 다른 네트워크 경로를 사용하거나 로컬 환경에서 요청이 차단되었을 수 있습니다. 요청은 보이지만 실패한다면 매칭된 규칙, 노드 상태, DNS 결과를 살펴보세요. 네트워크가 정상인데도 실패하면 프로젝트의 인증 정보, 레지스트리 설정, 잠금 파일과 패키지 호환성을 별도로 점검해야 합니다.
Clash 설정을 마친 후에도 특정 도구에서만 문제가 생기면 TUN을 끄고 켜는 작업을 반복하기보다, 도구별 로그와 Clash 연결 기록을 같은 시각 기준으로 비교하세요. 이렇게 하면 DNS 문제, 잘못된 프록시 변수, 노드 장애, 저장소 오류를 구분해 불필요한 설정 변경을 줄일 수 있습니다.