개발자 Git·npm 연결 문제를 줄이는 Clash TUN 터미널 설정 가이드

Git·npm 연결에 TUN을 쓰는 이유와 적용 범위

터미널에서 git clone은 실패하지만 브라우저는 열리거나, npm 패키지 설치가 특정 네트워크에서만 멈추는 경우가 있습니다. 브라우저는 운영체제 시스템 프록시를 따르더라도 Git, Node.js, 패키지 관리 도구는 각자 프록시 환경 변수나 설정 파일을 확인할 수 있습니다. 도구별 설정이 서로 다르면 어떤 요청은 프록시를 거치고 다른 요청은 직접 연결을 시도해 결과를 예측하기 어렵습니다.

Clash TUN은 가상 네트워크 인터페이스를 통해 운영체제의 IP 트래픽을 받아 Clash 또는 mihomo 코어의 규칙에 따라 처리합니다. 따라서 시스템 프록시를 따르지 않는 일부 터미널 프로그램도 규칙 기반으로 분기할 수 있습니다. 다만 TUN이 Git이나 npm의 자체 프록시 설정을 지우거나, 모든 앱을 자동으로 프록시 노드에 연결해 주는 것은 아닙니다. TUN, DNS 처리, 라우팅 규칙, 앱의 프록시 설정이 함께 작동하는 구조입니다.

• 시스템 프록시: 주로 HTTP 프록시 설정을 읽는 앱에 적용됩니다. 터미널 프로그램이 이를 따르는지는 프로그램과 실행 환경에 따라 다릅니다.
• TUN: 가상 인터페이스를 통해 IP 연결을 처리합니다. 규칙에 따라 프록시, 직접 연결 또는 차단으로 나눌 수 있습니다.
• 환경 변수: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 등으로 CLI가 별도의 로컬 프록시에 접속하게 할 수 있습니다. TUN을 켜도 이 값은 자동으로 초기화되지 않습니다.

TUN을 켜기 전에 확인할 항목

예시는 mihomo 코어를 사용하는 클라이언트 기준입니다. 메뉴 이름과 TUN 구현은 Clash Verge Rev, Clash Verge 등 클라이언트 버전에 따라 다를 수 있으므로, 앱 이름만 보고 특정 메뉴가 있다고 단정하지 마세요. 설정 화면에서 실제 코어와 버전을 확인하고, 클라이언트가 제공하는 TUN 설정 및 실행 로그를 기준으로 적용 상태를 판단합니다.

1. Clash 설정을 백업하고 현재 사용 중인 모드, 노드 그룹, DNS 설정을 기록합니다. 구독 설정을 직접 편집하면 다음 업데이트에 덮어써질 수 있으므로 클라이언트의 오버라이드나 병합 기능을 우선 사용하세요.
2. 다른 VPN, 가상 네트워크 어댑터, 게임 가속기, 패킷 필터 프로그램을 잠시 종료합니다. 여러 프로그램이 라우팅이나 DNS를 동시에 변경하면 TUN 문제와 충돌 문제를 구분하기 어렵습니다.
3. 관리자 권한이 필요한지 확인합니다. Windows에서는 UAC 승인이 필요할 수 있고, macOS에서는 네트워크 확장 또는 VPN 연결 권한을 허용해야 할 수 있습니다. Linux는 배포판과 실행 방식에 따라 네트워크 인터페이스 권한 구성이 달라집니다.
4. CLI에서 기존 프록시 설정을 확인합니다. 셸 환경 변수뿐 아니라 Git 전역 설정, 저장소별 설정, npm 설정에 별도 프록시가 등록됐는지도 살펴보세요.

가령 git config --show-origin --get-regexp 'http\..*proxy|https\..*proxy'는 적용 중인 Git 프록시 설정과 설정 파일 출처를 찾는 데 도움이 됩니다. 결과가 없으면 해당 패턴에 맞는 Git 프록시 항목이 없다는 뜻이지, 모든 네트워크 설정이 비어 있다는 뜻은 아닙니다. npm에서는 npm config get proxy와 npm config get https-proxy를 확인하고, 현재 셸의 환경 변수는 운영체제에 맞는 명령으로 확인하세요. 민감한 인증 정보가 포함된 출력은 다른 사람에게 그대로 공유하지 마세요.

운영체제별 TUN 설정 흐름

TUN 설정 항목은 클라이언트와 코어 버전에 따라 달라집니다. 다음은 메뉴 이름을 고정하지 않은 공통 흐름입니다. 토글이 켜졌는지만 보지 말고 가상 인터페이스 생성, 기본 경로, DNS 처리, 실제 연결 로그까지 확인해야 합니다.

설정에 TUN의 자동 경로 추가와 인터페이스 자동 감지 옵션이 있다면 처음에는 클라이언트의 기본값을 유지하고, 연결이 확인된 뒤 필요한 항목만 조정하는 편이 안전합니다. 수동 경로와 자동 경로를 동시에 추가하면 기본 경로가 예상과 달라질 수 있습니다. Linux 서버나 원격 개발 장비에서 기본 경로를 잘못 바꾸면 SSH 연결이 끊길 수 있으므로, 콘솔 접근이나 되돌리기 방법을 확보하지 않은 상태에서는 원격으로 라우팅을 변경하지 마세요.

DNS 하이재킹이나 DNS 서버 주소를 바꾸는 옵션도 무작정 추가하지 마세요. TUN이 연결을 처리하더라도 DNS가 운영체제, 브라우저의 보안 DNS, Clash 코어 중 어디에서 처리되는지에 따라 결과가 달라집니다. 먼저 TUN 로그와 실제 DNS 설정을 확인하고, 필요할 때만 코어의 지원 버전에 맞는 설정을 사용합니다.

Git·npm 트래픽을 규칙으로 분기하기

도메인 기반 규칙을 쓰려면 요청의 도메인을 코어가 확인할 수 있어야 합니다. 앱이 IP 주소로 직접 연결하거나, DNS와 연결 정보가 분리되어 도메인 식별이 되지 않으면 예상한 규칙 대신 IP 규칙이나 기본 규칙이 적용될 수 있습니다. 클라이언트의 연결 페이지에서 실제 요청의 도메인, 매칭된 규칙, 선택된 정책 그룹을 함께 확인하세요.

아래는 규칙의 형태를 보여 주는 예시입니다. Developer라는 정책 그룹은 실제 설정의 proxy-groups에 정의되어 있어야 하며, 사용 중인 그룹 이름과 노드 구성에 맞춰야 합니다. 기존 규칙을 지우고 통째로 붙여 넣는 설정이 아닙니다.

rules:
  - DOMAIN-SUFFIX,github.com,Developer
  - DOMAIN-SUFFIX,githubusercontent.com,Developer
  - DOMAIN-SUFFIX,gitlab.com,Developer
  - DOMAIN-SUFFIX,npmjs.org,Developer
  - DOMAIN-SUFFIX,registry.npmjs.org,Developer
  # 기존의 나머지 규칙을 여기에 유지
  # 기존 기본 규칙보다 앞에 개발 서비스 규칙을 배치

규칙은 위에서 아래 순서로 평가되므로, 앞쪽의 넓은 규칙이 먼저 요청을 처리하면 아래의 개발 서비스 규칙까지 도달하지 않습니다. 예를 들어 앞에 있는 DOMAIN-SUFFIX,github.com,DIRECT는 뒤에 추가한 GitHub 프록시 규칙을 가립니다. 구독이 규칙을 생성하는 경우에는 업데이트 때 변경 사항이 유지되는지 확인하고, 지원되는 로컬 오버라이드 기능을 이용하세요.

• Git: 저장소 주소가 HTTPS인지 SSH인지 먼저 확인합니다. HTTPS 연결은 GitHub나 GitLab 도메인 규칙의 영향을 받지만, SSH는 일반적으로 22번 포트 등 별도 경로를 사용합니다. SSH가 실패한다고 HTTPS 규칙이 잘못됐다고 단정하지 마세요.
• npm: 기본 레지스트리 주소가 registry.npmjs.org인지, 프로젝트나 조직에서 별도 레지스트리를 지정했는지 확인합니다. 사설 레지스트리는 필요한 도메인만 별도로 분기해야 할 수 있습니다.
• 추가 다운로드 호스트: 패키지 설치나 릴리스 다운로드 과정에서 다른 도메인으로 이동할 수 있습니다. 실패한 요청의 실제 도메인을 연결 로그에서 확인한 뒤 필요한 규칙만 추가하세요.

규칙이 맞는데도 터미널 연결이 실패한다면 환경 변수에 http://127.0.0.1:7890 같은 프록시가 남아 있는지 확인합니다. 포트는 예시일 뿐이며 실제 포트는 클라이언트 설정에 표시된 값을 사용해야 합니다. TUN만 사용할 계획이라면 테스트용 터미널에서 해당 변수를 임시로 제거하고 다시 시도할 수 있습니다. 기존 셸 설정 파일이나 CI 환경의 값을 지우기 전에는 다른 작업이 이를 사용하는지 확인하세요.

연결을 검증하고 문제를 단계별로 좁히기

설정 변경 후에는 브라우저가 열리는지만으로 성공을 판단하지 마세요. TUN이 활성화된 상태에서 Git과 npm을 각각 실행하고, Clash 연결 로그에서 요청이 들어왔는지와 어떤 규칙이 적용됐는지를 확인합니다. 같은 명령을 여러 번 빠르게 실행하기보다, 노드와 네트워크 조건을 유지한 채 한 번에 한 항목씩 바꾸면 원인을 찾기 쉽습니다.

1. Git 저장소 주소와 npm 레지스트리 주소가 올바른지 확인하고, 해당 도메인의 연결 기록을 찾습니다.
2. 기록이 없다면 TUN 인터페이스, 운영체제 권한, 다른 VPN과의 충돌을 먼저 확인합니다. 프로그램이 터널에 트래픽을 전달하지 못한 단계일 수 있습니다.
3. 요청 기록은 있지만 직접 연결로 처리됐다면 규칙 순서와 매칭 결과를 확인합니다. 규칙을 수정한 뒤 클라이언트가 새 설정을 적용했는지도 확인하세요.
4. 프록시 정책으로 처리되는데 연결이 실패한다면 노드 상태, 인증 오류, 대상 서비스의 응답, DNS 조회 결과를 나누어 점검합니다. 한 번에 노드와 DNS와 규칙을 모두 바꾸지 마세요.
5. 터미널만 실패하면 셸 환경 변수, Git 및 npm의 별도 프록시 설정을 확인합니다. 브라우저만 실패하면 브라우저 보안 DNS나 앱 자체 프록시 설정도 별도로 살펴봅니다.

오류 메시지의 구분도 중요합니다. Could not resolve host는 이름 해석 문제를 의심할 단서이고, 연결 시간 초과는 라우팅, 방화벽, 대상 서버 응답 등 여러 원인이 가능합니다. TLS 인증서 오류가 난다면 시스템 시간, 기업용 TLS 검사 프록시, 인증서 저장소를 확인하세요. 인증서 검증을 끄는 방식으로 해결하려 하면 연결 보안이 약해지므로 권장하지 않습니다.

자주 묻는 질문