Git clone이 중간에 멈추거나, npm 설치가 오래 걸리거나, Docker 이미지 다운로드가 반복해서 시간 초과된다면 먼저 각 도구의 설정을 바꾸기보다 트래픽이 어떤 경로로 나가는지 확인하세요. 브라우저에서 웹사이트가 열린다는 사실만으로 터미널과 Docker 데몬도 같은 프록시를 사용한다고 볼 수는 없습니다. Clash TUN은 가상 네트워크 인터페이스를 통해 시스템 트래픽을 받아 규칙에 따라 처리하므로, 애플리케이션마다 프록시를 따로 설정하지 않아도 되는 경우가 많습니다.

개발자를 위한 Clash TUN 설정: Git·npm·Docker 터미널 프록시 실전 가이드

TUN이 터미널 트래픽을 처리하는 방식

TUN은 가상 네트워크 인터페이스를 만들어 운영체제의 IP 트래픽을 프록시 커널로 전달합니다. 시스템 프록시는 주로 앱이 HTTP 프록시 설정을 따를 때 작동하지만, TUN은 앱이 프록시 환경 변수를 지원하지 않아도 네트워크 연결을 받아 처리할 수 있습니다. 다만 관리자 권한, 가상 어댑터, 라우팅 경로가 필요할 수 있으며, 운영체제와 클라이언트에 따라 권한 요청 방식은 다릅니다.

Clash Verge, Clash Verge Rev, Clash for Windows 등의 이름은 클라이언트 인터페이스를 가리킵니다. 실제 TUN과 규칙 동작은 해당 클라이언트가 사용하는 커널과 버전에 좌우됩니다. 설정을 바꾸기 전에 클라이언트의 정보 화면에서 커널이 mihomo인지, TUN 기능을 지원하는 버전인지 확인하세요. 오래된 설정 예시를 그대로 붙여 넣기보다 현재 커널이 인식하는 필드인지 먼저 확인하는 편이 안전합니다.

시스템 프록시: 애플리케이션이 운영체제의 HTTP 프록시 설정을 사용해야 요청이 전달됩니다.
터미널 환경 변수: HTTP_PROXY, HTTPS_PROXY 등을 읽는 프로그램에 적용되며, 프로그램별로 지원 방식이 다릅니다.
TUN: 운영체제 라우팅을 통해 IP 트래픽을 커널로 전달합니다. 규칙과 DNS가 올바르게 적용되어야 원하는 경로로 연결됩니다.

세 방식을 동시에 켜면 같은 요청이 중복 프록시를 거치거나, 특정 프로그램만 예상과 다른 경로를 사용할 수 있습니다. 먼저 TUN만 사용해 테스트하고, 결과를 확인한 뒤 환경 변수나 앱별 프록시를 추가하세요.

TUN을 안전하게 켜고 기본 설정 확인하기

클라이언트에서 현재 프로필을 선택한 뒤 TUN 기능을 켜고, 권한 승인 요청이 나타나면 운영체제와 클라이언트의 안내에 따라 허용하세요. Windows에서는 가상 네트워크 어댑터 설치나 관리자 권한이 필요할 수 있고, macOS에서는 네트워크 확장 권한을 요청할 수 있습니다. Linux에서는 라우팅과 가상 인터페이스 설정에 필요한 권한이 제한될 수 있습니다. 메뉴 이름은 버전에 따라 다르므로 ‘TUN’, ‘가상 네트워크’ 또는 커널 설정을 찾아보세요.

mihomo 설정을 직접 관리하는 경우 다음은 구조를 확인하기 위한 예시입니다. 이미 같은 최상위 항목이 있다면 두 번째 tun:을 추가하지 말고 기존 항목을 수정하세요. 구독에서 내려받는 설정은 업데이트로 덮어써질 수 있으므로 원본을 먼저 백업하고, 가능하면 클라이언트의 오버라이드 기능을 사용하세요.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

auto-route는 시스템 라우팅을 설정해 트래픽을 TUN으로 보내는 데 사용되고, auto-detect-interface는 나가는 인터페이스를 감지하는 데 도움을 줍니다. 이 항목의 지원 여부와 세부 동작은 커널 버전에 따라 다를 수 있습니다. 설정을 저장한 뒤 프로필을 다시 불러오고, 로그에 설정 파싱 오류나 인터페이스 생성 실패가 없는지 확인하세요.

DNS와 규칙이 개발자 연결을 막지 않는지 확인하기

도메인 이름을 IP 주소로 바꾸는 DNS 요청이 TUN 경로와 일치하지 않으면, github.com이나 패키지 레지스트리의 주소를 해석하지 못할 수 있습니다. 클라이언트의 DNS 기능이 켜져 있는지, mihomo 로그에 DNS 오류가 있는지 확인하세요. dns-hijack을 사용할 때는 로컬 네트워크나 다른 DNS 프로그램과 충돌하지 않는지도 살펴보세요. 네트워크 정책에 따라 공용 DNS 서버에 직접 연결할 수 없는 환경도 있으므로 임의로 DNS 주소를 바꾸기보다 현재 프로필에서 제공하는 DNS 설정을 먼저 점검해야 합니다.

규칙 모드에서는 규칙이 위에서부터 평가되고, 먼저 일치한 규칙의 정책이 연결 경로를 결정합니다. 저장소나 레지스트리 도메인이 직접 연결 규칙에 먼저 걸리면 TUN이 켜져 있어도 프록시를 사용하지 않습니다. 클라이언트의 연결 기록에서 요청 도메인과 선택된 정책 그룹을 확인한 다음, 해당 도메인이 어떤 규칙에 매칭되는지 살펴보세요. 모든 트래픽을 무조건 프록시로 보내기보다 개발에 필요한 도메인만 적절한 그룹으로 보내는 편이 원인 파악과 로컬 네트워크 접근에 유리합니다.

작업	요청을 만드는 구성 요소	먼저 확인할 항목
Git HTTPS clone	Git 프로세스	TUN 연결 기록, Git 프록시 설정, 도메인 규칙
npm install	Node.js 프로세스	registry 주소, DNS, npm의 별도 프록시 설정
Docker pull	Docker 데몬 또는 Docker Desktop의 가상 환경	데몬의 네트워크 경로, 레지스트리 연결 기록, 이미지 이름
SSH를 이용한 Git	Git의 SSH 프로세스	대상 서버와 포트 22의 연결 정책, 네트워크에서 SSH가 허용되는지

Git과 npm을 재현 가능한 명령으로 테스트하기

먼저 브라우저 대신 터미널에서 도메인 연결과 도구별 동작을 각각 확인하세요. 아래 명령은 연결 테스트 예시이며, 실제 저장소 주소와 패키지 이름은 본인의 작업에 맞게 바꿔야 합니다.

curl -I --connect-timeout 10 https://github.com
git ls-remote https://github.com/git/git.git HEAD
npm ping

curl이 실패하면 DNS, TUN 경로, 규칙을 먼저 살펴보세요. curl은 성공하지만 Git만 실패한다면 저장소 주소, 인증, Git에 저장된 프록시 옵션을 확인합니다. Git 설정은 다음처럼 조회할 수 있습니다.

git config --show-origin --get-regexp 'http\..*proxy|https\..*proxy'
npm config get registry
npm config get proxy
npm config get https-proxy

결과에 프록시가 표시되면 현재 TUN 경로와 함께 사용해야 하는지 판단하세요. 사용하지 않는 오래된 프록시 주소가 남아 있으면 연결이 잘못된 로컬 포트로 향할 수 있습니다. 설정을 지우기 전에는 출처를 확인하고, 회사나 개발 환경에서 관리하는 값은 임의로 제거하지 마세요.

npm의 레지스트리가 기본 주소가 아닌 사내 미러로 지정되어 있다면 그 주소에 대한 DNS와 규칙도 확인해야 합니다. 한 패키지만 실패할 때는 네트워크 전체 문제라고 단정하지 말고, 패키지 이름과 버전, lock 파일, 레지스트리 응답을 함께 확인하세요. 터미널에 프록시 환경 변수를 지정해 둔 경우에는 TUN 단독 테스트와 환경 변수 사용 테스트를 나눠 비교하면 중복 설정 여부를 찾기 쉽습니다.

Docker 이미지 다운로드는 데몬 경로를 따로 점검하기

Docker 명령을 실행하는 터미널과 이미지를 실제로 내려받는 구성 요소는 다를 수 있습니다. Linux에서는 일반적으로 Docker 데몬이 레지스트리에 연결합니다. Docker Desktop은 가상화된 환경을 사용하므로, 호스트의 TUN이 터미널 앱을 처리하는 것과 같은 방식으로 데몬 트래픽까지 처리한다고 보장할 수 없습니다. 다음 명령으로 오류를 재현하고, 같은 시각의 Docker 및 Clash 연결 기록을 비교하세요.

docker pull alpine:latest
docker info

docker pull만 실패한다면 터미널의 HTTP_PROXY 값을 바꾸는 것만으로 해결되지 않을 수 있습니다. Docker 데몬의 프록시 설정, Docker Desktop의 네트워크 설정, 사용 중인 가상 네트워크와 TUN의 경로를 확인하세요. Linux에서 데몬 설정을 변경했다면 적용 전에 기존 설정을 백업하고, 재시작이 필요한지 해당 배포판과 설치 방식에 맞춰 확인합니다. 운영 환경의 데몬을 즉시 재시작하면 실행 중인 서비스에 영향을 줄 수 있습니다.

로그에 레지스트리의 인증 실패가 표시되면 네트워크가 아니라 로그인이나 접근 권한 문제일 수 있습니다. 시간 초과와 DNS 오류는 연결 경로를 우선 확인하고, unauthorized 또는 denied 같은 응답은 이미지 경로와 인증 정보를 점검하세요. 오류 메시지의 첫 원인을 기록하면 같은 이미지를 반복해서 받으며 원인을 추측하는 일을 줄일 수 있습니다.

자주 묻는 질문

TUN을 켜면 시스템 프록시도 꺼야 하나요?

항상 꺼야 하는 것은 아니지만, 문제를 진단할 때는 TUN만 활성화해 비교하는 것이 좋습니다. 시스템 프록시를 따르는 앱과 TUN으로 라우팅되는 앱이 다를 수 있으며, 두 방식을 함께 쓰면 중복 경로가 생길 수 있습니다. 기존 설정을 기록하고 한 번에 한 항목씩 바꾸세요.

GitHub SSH 연결은 왜 HTTPS clone과 다르게 실패하나요?

SSH 연결은 보통 TCP 포트 22를 사용하며, HTTP 프록시 설정을 자동으로 따르지 않습니다. 연결 기록에서 해당 서버와 포트가 어떻게 처리되는지 확인하고, 사용 중인 네트워크가 SSH를 허용하는지도 점검하세요. 네트워크 정책이 허용한다면 HTTPS 주소로 테스트해 두 경로의 차이를 좁힐 수 있습니다.

브라우저는 되는데 Docker pull만 실패하면 무엇부터 보나요?

Docker Desktop 또는 Linux 데몬이 호스트 앱과 같은 경로를 사용하는지부터 확인하세요. TUN 연결 기록에 레지스트리 요청이 나타나는지 비교하고, 이어서 데몬 프록시, DNS, 인증 오류를 구분합니다. Docker 데몬에 환경 변수를 설정해도 이미 실행 중인 데몬에 바로 적용되지 않을 수 있습니다.

TUN을 끈 뒤에도 인터넷 연결이 안 되면 어떻게 하나요?

클라이언트에서 TUN을 정상적으로 비활성화한 뒤 시스템 프록시와 네트워크 상태를 확인하세요. 운영체제의 프록시 설정이 클라이언트 종료 후에도 남아 있거나, 다른 VPN·가상 네트워크 어댑터가 기본 경로를 잡고 있을 수 있습니다. 설정을 변경하기 전 값을 기록하고, 조직에서 관리하는 네트워크 설정은 관리자에게 문의하세요.