브라우저는 되는데 Git·npm 터미널만 실패하는 이유
브라우저에서 GitHub 저장소와 패키지 페이지가 열려도 터미널의 git clone, npm install, docker pull까지 같은 방식으로 연결된다는 뜻은 아닙니다. 브라우저는 운영체제의 시스템 프록시 설정을 따르는 경우가 많지만, CLI 프로그램은 자체 네트워크 라이브러리를 사용하거나 셸 환경 변수에 지정된 프록시만 읽을 수 있습니다. 그래서 Clash에서 시스템 프록시를 켰는데도 브라우저만 정상이고 개발 도구는 연결 시간 초과를 내는 상황이 생깁니다.
TUN 모드는 애플리케이션이 프록시를 지원하는지와 별개로, 가상 네트워크 인터페이스를 통해 운영체제의 IP 트래픽을 받아 처리하는 방식입니다. CLI가 일반적인 TCP 연결을 만들면 해당 패킷이 TUN 경로에 들어오고, Mihomo가 설정된 규칙에 따라 직접 연결하거나 프록시 그룹으로 보냅니다. 따라서 각 도구에 프록시 주소를 하나씩 설정하는 대신, 터미널·Git·패키지 관리자·컨테이너 트래픽을 공통 정책으로 다룰 수 있습니다.
다만 TUN을 켰다고 모든 연결이 자동으로 해결되지는 않습니다. 코어가 지원하는 기능인지, 운영체제가 가상 인터페이스와 경로 변경을 허용하는지, 도메인 규칙이 실제 요청과 일치하는지 확인해야 합니다. 회사 네트워크나 관리형 기기에서는 터널 사용이 정책 위반일 수 있으므로 먼저 허용 범위를 확인하세요.
TUN을 켜기 전 확인할 코어와 네트워크 권한
먼저 사용 중인 앱의 이름보다 실제로 실행되는 코어를 확인합니다. Clash Verge Rev, Mihomo Party 등은 그래픽 인터페이스와 네트워크 처리 코어가 분리되어 있을 수 있습니다. TUN 메뉴가 보이더라도 구형 코어나 다른 계열의 코어가 선택되어 있으면 해당 옵션이 동작하지 않거나 일부 필드가 무시될 수 있습니다. 앱의 코어 정보와 로그에서 Mihomo 계열 코어가 정상 실행 중인지 확인하고, 기능을 지원하는 안정 버전을 사용하세요.
다음으로 권한과 기존 네트워크 구성의 충돌을 살펴봅니다. Windows에서는 가상 어댑터 설치와 경로 변경에 관리자 승인이 필요할 수 있고, macOS에서는 네트워크 확장 승인이나 시스템 설정 변경이 요구될 수 있습니다. Linux에서는 TUN 장치와 라우팅을 설정할 권한이 필요합니다. 다른 VPN, 가상 머신 네트워크, Docker의 자체 네트워크, 기업 보안 에이전트가 동시에 경로를 바꾸면 트래픽이 한쪽으로만 흐르거나 연결이 순환할 수 있으므로 첫 시험에서는 중복 터널을 잠시 끄는 것이 좋습니다.
현재 프로필도 백업해 두세요. 원격 구독 프로필을 직접 편집하면 다음 업데이트 때 변경 내용이 덮어써질 수 있습니다. 앱에서 TUN 설정을 제공한다면 우선 GUI 설정을 사용하고, 사용자 정의 YAML을 추가할 때는 현재 코어의 구성 문법과 설정 병합 방식을 확인하세요. 잘못된 들여쓰기나 지원되지 않는 키는 프로필 전체의 로드를 막을 수 있습니다.
- 코어 상태: 앱 화면이나 로그에서 코어가 실행 중인지, 프로필이 오류 없이 적용됐는지 확인합니다.
- 권한 승인: 운영체제가 요구하는 네트워크 확장·가상 어댑터·관리자 권한 요청을 승인했는지 확인합니다.
- 경로 충돌: 다른 VPN이나 터널을 동시에 사용 중인지, 테스트 중 불필요한 네트워크 필터가 활성화됐는지 살펴봅니다.
- 복구 수단: 설정 변경 전 프로필을 복사해 두고, 연결이 끊길 경우 TUN을 끄거나 백업 프로필로 되돌릴 방법을 준비합니다.
Clash TUN 모드 활성화와 기본 검증
메뉴 이름은 클라이언트와 버전에 따라 다르지만 보통 설정의 네트워크 또는 TUN 항목에서 모드를 켭니다. 일부 GUI는 관리자 권한으로 헬퍼를 설치하거나 시스템 확장을 승인한 뒤 재시작해야 실제 인터페이스를 만들 수 있습니다. 화면의 토글이 켜져 있다는 사실만으로 성공을 판단하지 말고, 상태 표시와 코어 로그에서 TUN 장치 초기화 및 경로 설정이 완료됐는지 확인하세요. 오류가 남아 있으면 반복해서 토글을 누르기보다 오류 문구와 권한 상태를 먼저 살펴봅니다.
처음에는 운영체제의 네트워크 전체를 복잡한 사용자 규칙으로 나누지 말고, 최소 설정으로 동작 여부를 확인합니다. TUN 인터페이스가 올라왔는지, DNS 요청이 의도한 경로를 타는지, 테스트 연결이 Clash 로그에 나타나는지 순서대로 봅니다. DNS 가로채기 옵션은 도메인 규칙과 이름 해석에 영향을 줄 수 있으므로, 기존에 별도 DNS 정책을 쓰고 있다면 설정을 바꾸기 전 현재 값을 기록해 두세요. DNS 기능을 켰는데 특정 사내 도메인만 실패한다면 해당 도메인의 내부 DNS 처리 방식과 분할 DNS 정책을 확인해야 합니다.
검증은 한 번에 여러 도구를 실행하지 말고 단계를 나누는 편이 좋습니다. 먼저 브라우저에서 일반 사이트가 열리는지 확인한 다음, 셸에서 DNS 조회와 HTTPS 요청을 시험하고, 마지막으로 Git이나 npm 명령을 실행합니다. 각 테스트 직후 연결 로그에서 도메인 또는 원격 주소, 적용된 규칙, 선택된 정책 그룹을 확인하면 실패 지점을 좁힐 수 있습니다. 주소가 IP로만 표시되거나 기대한 도메인 규칙이 적용되지 않으면 DNS 응답과 도메인 판별 기능을 함께 점검하세요.
curl -I https://github.com
git ls-remote https://github.com/OWNER/REPOSITORY.git
npm ping위 명령은 기본 연결 점검 예시입니다. 저장소 주소의 소유자와 이름은 실제 테스트 대상에 맞게 바꾸고, 회사에서 승인되지 않은 외부 주소를 시험에 사용하지 마세요. 특정 도구 하나만 실패한다면 그 프로그램이 별도의 프록시 설정을 갖고 있는지 먼저 확인합니다. 반대로 여러 CLI와 운영체제 서비스가 동시에 실패한다면 애플리케이션별 설정을 고치기 전에 TUN 인터페이스, 경로, DNS를 점검하는 것이 효율적입니다.
Git·SSH·npm·pip의 프록시 설정 점검
TUN이 정상적으로 작동해도 프로그램 자체의 프록시 설정이 연결을 다른 곳으로 보낼 수 있습니다. 셸 초기화 파일이나 IDE 설정에 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY가 남아 있으면 요청이 TUN을 통과하기 전에 명시된 프록시로 전달될 수 있습니다. 이 프록시가 꺼져 있거나 잘못된 포트를 가리키면 브라우저는 정상인데 명령줄만 실패할 수 있습니다. 현재 셸에서 관련 변수가 설정돼 있는지 확인하고, TUN 경로만 시험할 때는 기존 변수의 영향을 분리해 비교하세요.
env | grep -i proxy
git config --show-origin --get-regexp 'http.*proxy'
npm config get proxy
npm config get https-proxy
Git은 전역 설정과 저장소별 설정을 모두 가질 수 있습니다. 과거에 특정 프록시를 지정했다면 셸 변수만 지워도 계속 그 값을 사용할 수 있으므로 git config --show-origin으로 어느 설정 파일에서 읽었는지 확인합니다. HTTPS 방식의 저장소 복제와 SSH 방식의 복제는 연결 경로가 다릅니다. SSH는 보통 22번 포트를 사용하며, 네트워크에서 해당 포트가 차단되면 TUN만으로 해결되지 않을 수 있습니다. 조직에서 허용한 SSH 대체 경로나 HTTPS 복제를 사용하고, 인증 실패와 네트워크 시간 초과를 구분하세요.
npm은 메타데이터 서버와 패키지 파일을 내려받는 호스트가 서로 다를 수 있습니다. 따라서 npm ping은 성공하지만 설치가 중간에 멈춘다면 실패한 시각의 Clash 로그에서 실제 요청 호스트를 찾습니다. 처음부터 넓은 도메인 규칙을 추가하기보다 확인한 호스트를 기준으로 필요한 정책을 지정하세요. 사내 레지스트리나 패키지 미러를 이용한다면 공개 레지스트리 규칙과 별도로 해당 주소가 올바른 내부 경로를 사용하도록 해야 합니다.
Python의 pip도 인덱스 주소, 인증 서버, 파일 호스팅 주소가 다를 수 있습니다. pip config list와 환경 변수를 확인해 고정 프록시나 사내 미러가 설정되어 있는지 살펴보세요. Homebrew는 저장소와 릴리스 파일을 서로 다른 호스트에서 받을 수 있으며, GitHub를 쓰는 구성에서는 Git 연결과 바이너리 다운로드가 다른 시점에 실패하기도 합니다. 한 프로그램의 성공을 전체 CLI 경로의 성공으로 간주하지 말고, 실제 실패 명령을 기준으로 관측하는 것이 중요합니다.
주의: 프록시 환경 변수를 무조건 영구 삭제하지 마세요. 개발 환경이나 회사 빌드 서버에서 그 값이 의도된 설정일 수 있습니다. 현재 터미널에서만 임시로 비활성화해 비교한 뒤, 원인이 확인되면 셸 설정·도구 설정·Clash 정책 중 어느 계층을 유지할지 결정합니다. 자격 증명이 포함된 프록시 URL을 로그나 공개 저장소에 붙여 넣지 않도록 주의하세요.
Docker·규칙 매칭·연결 로그로 원인 좁히기
Docker는 개발자 환경에서 별도로 살펴야 합니다. 호스트의 터미널 명령은 TUN을 통과해도 Docker 데몬이 이미지 레이어를 내려받는 연결은 데몬의 실행 환경과 네트워크 네임스페이스를 따를 수 있습니다. 특히 Linux에서는 Docker 데몬이 사용자 셸의 프록시 환경 변수를 자동으로 상속한다고 가정하면 안 됩니다. 이미지 다운로드만 실패한다면 Docker 데몬의 프록시 설정, 사내 레지스트리, 인증 정보를 확인하고, 컨테이너 내부에서 발생하는 요청과 호스트에서 발생하는 요청을 구분하세요.
규칙은 구체적인 항목이 일반적인 항목보다 먼저 평가되는지 확인해야 합니다. 광범위한 DOMAIN-SUFFIX나 GEOIP 규칙이 예상과 다르게 먼저 적용되면, GitHub나 패키지 레지스트리 요청이 의도한 개발 도구 그룹을 거치지 않을 수 있습니다. 연결 로그에서 실제 매칭 규칙을 확인한 뒤 필요한 경우 좁은 범위의 도메인 규칙을 일반 규칙보다 앞에 배치합니다. 특정 노드로 보내야 하는 업무용 서비스와 직접 연결해야 하는 내부 서비스가 섞여 있다면, 기능별 그룹과 규칙을 분리해 변경 영향을 줄이는 편이 낫습니다.
| 증상 | 먼저 확인할 항목 | 다음 조치 |
|---|---|---|
| 브라우저는 되지만 모든 CLI가 실패함 | TUN 상태, 권한, 가상 인터페이스, 기본 경로 | Clash 로그에 테스트 요청이 나타나는지 확인 |
| Git은 되지만 npm 설치가 멈춤 | npm 프록시 설정, 레지스트리와 파일 호스트 | 실패 시점의 연결 로그에서 차단된 호스트 확인 |
| HTTPS 복제는 되지만 SSH 복제는 실패함 | SSH 설정, 인증, 네트워크의 SSH 포트 제한 | 승인된 HTTPS 또는 SSH 경로로 비교 테스트 |
| Docker 이미지 다운로드만 실패함 | Docker 데몬의 프록시와 레지스트리 설정 | 호스트 CLI와 데몬 트래픽을 분리해 진단 |
| 연결 로그에 요청이 전혀 보이지 않음 | TUN 권한, 인터페이스 초기화, 다른 터널과의 충돌 | 코어 로그와 운영체제 경로 상태를 확인 |
연결 로그를 볼 때는 실패한 명령을 실행한 정확한 시간과 호스트를 기록하세요. 요청이 로그에 있지만 DIRECT로 나가 차단된다면 규칙이나 정책 그룹을 검토하고, 프록시 정책으로 분류됐지만 연결이 끊기면 선택된 노드와 TLS 오류를 확인합니다. 요청이 보이지 않는 경우에는 도메인 규칙을 더 추가하는 것보다 패킷이 TUN으로 들어오는지부터 살펴야 합니다. 설정을 한 번에 여러 개 바꾸면 어떤 변경이 해결했는지 알기 어려우므로, 한 항목을 수정할 때마다 같은 명령을 다시 실행하는 방식으로 진행하세요.
자주 묻는 질문
시스템 프록시를 켰는데도 TUN이 필요한가요?
시스템 프록시는 이를 지원하는 애플리케이션에 프록시 주소를 알려주는 방식입니다. 모든 CLI와 백그라운드 서비스가 그 설정을 따르지는 않습니다. 반면 TUN은 운영체제의 IP 트래픽 경로를 다루므로 프록시 설정을 읽지 않는 프로그램도 처리할 수 있습니다. 다만 특정 도구에 이미 별도 프록시가 설정돼 있다면 그 설정이 우선할 수 있으므로 함께 점검하세요.
TUN을 켰는데 Clash 연결 로그가 비어 있는 이유는 무엇인가요?
관리자 권한이나 시스템 확장 승인이 완료되지 않았거나, 코어가 TUN을 초기화하지 못했거나, 다른 네트워크 터널과 충돌했을 수 있습니다. 클라이언트의 토글 상태만 보지 말고 코어 로그의 초기화 결과와 운영체제의 가상 인터페이스 상태를 확인하세요. 로그에 요청이 없다는 것은 규칙이 잘못됐다는 증거가 아니라, 요청이 Clash까지 도달하지 않았을 가능성을 시사합니다.
TUN을 사용할 때 HTTP_PROXY 환경 변수는 지워야 하나요?
항상 지워야 하는 것은 아닙니다. 환경 변수는 도구가 지정된 프록시 서버로 직접 연결하도록 만들 수 있어 TUN 경로와 중복될 수 있지만, 회사 환경이나 빌드 시스템에서는 필요한 설정일 수도 있습니다. 현재 셸에서만 변수를 임시로 제거해 비교하고, 결과에 따라 셸·도구·Clash 중 어느 계층이 프록시를 맡을지 정하세요.
개발 중 TUN 설정에서 보안상 주의할 점은 무엇인가요?
구독 주소, 인증 토큰, 프록시 자격 증명이 들어간 환경 변수와 로그를 공유하지 마세요. 업무 네트워크에서는 조직의 터널 사용 규정을 확인하고, 내부 레지스트리나 사내 도메인이 공개 프록시로 나가지 않도록 정책을 검토해야 합니다. 문제 해결 후에는 임시 진단 규칙과 불필요하게 넓은 예외를 정리하는 것이 좋습니다.
애플리케이션마다 프록시를 따로 지정하는 방식은 SSH, npm, pip, Docker 데몬처럼 설정 위치가 갈라질수록 누락이 생기기 쉽고, 오래된 CLI는 환경 변수를 일관되게 처리하지 않을 수도 있습니다. 반대로 Clash TUN은 운영체제 경로와 규칙을 함께 확인해야 하므로 초기 권한 설정과 로그 점검이 필요하지만, 트래픽을 한곳에서 관찰하고 정책을 재사용할 수 있다는 장점이 있습니다. 개발 도구별 설정을 계속 추측하기보다 Mihomo 코어와 TUN 상태를 확인하며 차근차근 구성하고 싶다면 Clash V.CORE를 다운로드해 현재 프로필에 맞는 연결을 점검해 보세요.