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

터미널 연결과 TUN 모드의 관계부터 확인하기

Git 저장소 복제나 npm install이 멈출 때는 먼저 브라우저와 터미널이 같은 프록시 경로를 사용하는지 확인하세요. Clash의 시스템 프록시 기능은 운영체제 프록시 설정을 참고하는 앱에 주로 적용되며, 모든 명령줄 도구가 이를 따르는 것은 아닙니다. 반면 TUN 모드는 가상 네트워크 인터페이스를 통해 앱의 IP 트래픽을 처리하므로, 앱에 프록시를 따로 지정하지 않아도 연결을 라우팅할 수 있습니다.

다만 TUN이 켜져 있다고 해서 Git, npm, DNS가 모두 정상이라는 뜻은 아닙니다. 클라이언트의 연결 화면에서 TUN 상태를 확인하고, 로그에서 테스트 시각의 연결 기록이 생성되는지 살펴보세요. 기록이 없다면 요청이 TUN에 도달하지 않았을 수 있고, 기록은 있지만 실패한다면 DNS, 규칙, 노드 또는 대상 서버 응답을 점검해야 합니다.

사용 중인 클라이언트와 코어가 mihomo를 지원하는지, 현재 실행 중인 코어 버전이 무엇인지 확인합니다.
설정 파일을 백업하고 클라이언트 하나만 실행합니다. 다른 VPN이나 TUN 기반 네트워크 도구는 테스트하는 동안 잠시 종료합니다.
현재 선택된 설정과 프록시 그룹을 확인하고, 웹 요청이 성공하는 노드를 선택합니다.
TUN을 켠 뒤 터미널에서 도메인 조회와 HTTPS 연결을 각각 테스트합니다.

TUN 활성화와 운영체제 권한·라우팅 확인

Clash Verge 또는 Clash Verge Rev에서는 설정 화면에서 TUN 모드를 찾아 활성화하고, 시스템에서 권한 요청이 나오면 승인하세요. 메뉴 이름과 위치는 버전에 따라 달라질 수 있습니다. Windows에서는 관리자 권한, macOS에서는 시스템 네트워크 확장 관련 승인, Linux에서는 네트워크 인터페이스와 라우팅을 설정할 권한이 필요할 수 있습니다. 권한을 승인하지 못하면 스위치가 켜진 것처럼 보이더라도 인터페이스를 만들지 못하거나 연결이 끊길 수 있습니다.

처음에는 TUN의 자동 경로 처리와 DNS 가로채기 등 필요한 기본 기능만 켜고, 설정을 적용한 뒤 로그를 확인하세요. 기존 설정에 tun: 항목을 추가하는 경우 최상위 항목을 중복해서 만들지 말고 현재 클라이언트가 생성하는 설정과 합쳐야 합니다. 다음 YAML은 동작 원리를 보여 주는 예시이며 모든 버전에서 그대로 적용되는 완성 설정은 아닙니다.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true

auto-route는 시스템 경로를 설정해 트래픽을 TUN으로 보내는 기능과 관련됩니다. auto-detect-interface는 사용할 실제 네트워크 인터페이스를 찾는 데 도움을 줍니다. 인터페이스를 수동으로 지정해야 하는 환경에서는 Wi-Fi와 유선 네트워크 전환 후 설정이 맞지 않을 수 있습니다. 특정 앱만 연결되지 않는다면 먼저 로그의 대상 도메인, 선택된 규칙, 최종 아웃바운드를 확인하세요. 테스트 편의를 위해 전체 트래픽을 무조건 프록시로 보내는 모드로 바꾸기보다 해당 도메인에 적용된 규칙부터 확인하는 편이 안전합니다.

VPN, 보안 프로그램, 컨테이너 네트워크, 다른 프록시 클라이언트가 이미 가상 인터페이스나 경로를 만들고 있다면 충돌 가능성이 있습니다. TUN을 켠 직후 모든 네트워크가 끊기면 클라이언트를 종료하거나 TUN을 끄고 인터넷 연결을 복구한 다음, 다른 VPN을 종료하고 다시 시험하세요. 연결 복구를 확인하기 전에는 기본 경로나 DNS를 수동으로 여러 번 변경하지 마세요.

Git·npm 프록시 설정과 환경 변수 점검

TUN이 정상이어도 터미널에 지정된 프록시 설정이 연결을 다른 주소로 보내거나, 존재하지 않는 로컬 포트를 가리킬 수 있습니다. 클라이언트가 실제로 제공하는 HTTP 또는 혼합 포트가 7890이라면 아래처럼 명령 단위로 연결을 시험할 수 있습니다. 7890은 예시이므로 현재 설정 화면의 수신 포트로 바꾸세요. 제어 API 포트와 프록시 포트는 서로 다른 용도입니다.

curl -v --connect-timeout 5 --max-time 15 \
  --proxy http://127.0.0.1:7890 https://registry.npmjs.org/ -o /dev/null

Windows PowerShell에서는 저장 장치 옵션을 다음과 같이 바꿔 실행할 수 있습니다.

curl.exe -v --connect-timeout 5 --max-time 15 `
  --proxy http://127.0.0.1:7890 https://registry.npmjs.org/ -o NUL

이 요청이 성공하면 로컬 프록시 수신과 대상 HTTPS 연결은 적어도 한 경로에서 작동합니다. 연결이 거부되면 포트와 클라이언트 상태를 확인하세요. 시간 초과라면 노드, 규칙, DNS 또는 네트워크 제한을 살펴봅니다. 응답 코드가 401, 403 등으로 반환되면 서버가 응답한 것이므로 단순한 네트워크 시간 초과와 구분해야 합니다.

대상	확인 명령	확인할 내용
현재 셸 환경 변수	`env \| grep -i proxy`	`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` 값과 포트
Git 전역 프록시	`git config --global --get-regexp 'http.*proxy'`	예전 프록시 주소나 사용할 수 없는 포트가 저장됐는지
npm 프록시 설정	`npm config get proxy` `npm config get https-proxy`	npm 설정 파일에 별도 주소가 남아 있는지
레지스트리 주소	`npm config get registry`	접근 가능한 레지스트리를 사용하고 있는지

터미널에서 프록시를 직접 지정해 시험한 뒤 해당 설정을 유지할지 결정하세요. 셸 세션에만 적용하는 예시는 다음과 같습니다. 이 방식은 TUN을 시험하는 것과 별개로 명령줄 프록시 경로를 명시적으로 지정합니다.

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export NO_PROXY=localhost,127.0.0.1

Windows PowerShell에서는 현재 창에만 적용하려면 $env:HTTPS_PROXY="http://127.0.0.1:7890"처럼 설정할 수 있습니다. 프록시 없이 TUN만 시험하려면 현재 셸의 관련 환경 변수와 Git·npm의 개별 프록시 설정이 요청에 영향을 주지 않는지 확인해야 합니다. 프록시 주소에 사용자 이름이나 암호를 넣는 경우 명령 기록, 로그, 공유 화면에 인증 정보가 남지 않도록 주의하세요.

Git 설정을 지울 때는 실제로 설정이 있는지 먼저 확인하세요. 불필요한 전역 프록시가 발견되면 git config --global --unset http.proxy 또는 해당 키에 맞는 명령으로 제거할 수 있습니다. npm도 npm config delete proxy와 npm config delete https-proxy로 저장된 값을 제거할 수 있습니다. 조직에서 관리하는 설정을 무심코 삭제하지 말고, 변경 전 값을 기록해 필요하면 되돌릴 수 있게 하세요.

DNS, SSH 복제와 흔한 오류 분리

npm install에서 ENOTFOUND 또는 getaddrinfo 오류가 나오면 노드 연결부터 바꾸기보다 도메인 이름을 확인하세요. macOS와 Linux에서는 nslookup registry.npmjs.org 또는 dig registry.npmjs.org를, Windows에서는 nslookup registry.npmjs.org를 사용할 수 있습니다. DNS 응답이 없거나 예상과 다르면 TUN의 DNS 가로채기 상태, 클라이언트 DNS 로그, 현재 네트워크의 DNS를 순서대로 확인하세요. 브라우저에서 사이트가 열리는 것만으로 터미널의 DNS 요청도 같은 경로를 쓴다고 단정할 수 없습니다.

Git 주소가 https://로 시작하는지 git@로 시작하는지 확인하는 것도 중요합니다. HTTPS 복제는 일반적으로 HTTP 프록시 설정이나 TUN 경로를 사용할 수 있지만, SSH 복제는 별도의 SSH 연결이며 보통 TCP 22번 포트를 사용합니다. HTTP 프록시가 설정됐다고 SSH 연결이 자동으로 같은 방식으로 전달되지는 않습니다. SSH에서만 실패한다면 TUN 로그에 대상 연결이 기록되는지, 네트워크가 해당 포트를 제한하는지, 저장소 주소와 키 인증이 올바른지 살펴보세요. 원인을 확인하지 않은 채 SSH 설정 파일에 프록시 명령을 추가하지 마세요.

connection refused: 지정한 로컬 프록시 포트에서 수신 중인지, 포트를 다른 프로그램이 사용하거나 바꾸지 않았는지 확인합니다.
ETIMEDOUT 또는 시간 초과: 연결 로그에서 규칙과 노드를 확인하고, 다른 노드나 네트워크에서 같은 요청을 비교합니다.
ECONNRESET: 서버나 중간 네트워크가 연결을 끊었을 수 있습니다. 반복 재시도 전에 요청 대상과 프록시 경로를 확인합니다.
TLS 인증서 오류: 시스템 날짜와 시간을 동기화하고 HTTPS 검사 프록시나 조직 인증서 정책의 영향을 확인합니다. 인증서 검증을 끄는 방식은 일반적인 해결책으로 사용하지 마세요.
브라우저만 되고 터미널은 실패: 터미널 환경 변수, Git·npm 설정, SSH와 HTTPS의 차이를 확인합니다.

npm에서 특정 패키지만 실패한다면 패키지 이름과 잠금 파일을 먼저 확인하고, 오류가 가리키는 호스트가 registry.npmjs.org인지 별도 다운로드 서버인지 살펴보세요. 사내 레지스트리나 패키지 설치 스크립트가 추가 도메인을 요청할 수 있습니다. 필요한 도메인이 프록시 제외 목록인 NO_PROXY에 들어 있으면 직접 연결될 수 있으므로, 제외 목록은 꼭 필요한 로컬 주소와 내부 도메인만 포함하도록 관리하세요.

자주 묻는 질문

시스템 프록시가 켜져 있는데도 Git 복제가 실패하는 이유는 무엇인가요?

터미널과 Git이 시스템 프록시를 따르지 않거나, Git 전역 설정이 다른 프록시 주소를 지정했을 수 있습니다. 환경 변수와 git config 결과를 확인한 뒤, HTTPS 복제인지 SSH 복제인지 구분해 테스트하세요.

TUN만 켜고 Git·npm의 프록시 설정은 비워 두어도 되나요?

가능합니다. TUN이 해당 앱의 트래픽을 가로채고 규칙과 DNS가 정상이라면 별도 앱 프록시 설정 없이 작동할 수 있습니다. 다만 실제 경로는 운영체제, 클라이언트, 권한, 다른 네트워크 도구에 따라 달라지므로 로그와 명령줄 테스트로 확인해야 합니다.

npm의 프록시 주소에 HTTPS를 입력해야 하나요?

프록시 서버 자체의 주소와 접속 대상의 HTTPS는 서로 다른 개념입니다. 로컬에서 HTTP 혼합 포트를 제공한다면 예시처럼 프록시 주소는 http://127.0.0.1:7890으로 두고 HTTPS 사이트에 연결할 수 있습니다. 실제 포트와 지원 프로토콜은 클라이언트 설정을 따르세요.

TUN을 켜면 DNS 오류도 자동으로 해결되나요?

아닙니다. TUN은 트래픽 경로를 처리하는 기능이며, 잘못된 DNS 서버 주소나 브라우저·앱 자체 DNS 설정까지 자동으로 바로잡지는 않습니다. DNS 조회 결과, 클라이언트 로그, 연결 규칙을 따로 확인하세요.