개발자 Clash TUN 설정: Git·npm·Docker 터미널 프록시 한 번에 해결

TUN과 터미널 프록시의 역할부터 구분하기

Git clone은 되는데 npm 설치가 멈추거나, 브라우저에서는 GitHub가 열려도 터미널에서는 연결이 실패하는 경우가 있습니다. 원인은 터미널 앱이 시스템 프록시 설정을 따르지 않거나, 패키지 도구와 Docker 데몬이 서로 다른 네트워크 경로를 사용하기 때문일 수 있습니다. 먼저 어떤 트래픽을 어디서 처리할지 구분하면 같은 프록시 주소를 여러 도구에 반복 설정하는 일을 줄일 수 있습니다.

시스템 프록시는 앱이 해당 설정을 읽고 프록시 연결을 요청할 때 작동합니다. 반면 TUN은 가상 네트워크 인터페이스를 이용해 운영체제에서 전달되는 트래픽을 코어로 보내는 방식입니다. 셸에서 실행되는 모든 프로그램이 HTTP 프록시 환경 변수를 읽는 것은 아니므로, 이를 따르지 않는 TCP 연결을 포착해야 할 때 TUN이 유용합니다. 다만 TUN을 켠다고 모든 앱·프로토콜·컨테이너의 통신이 자동으로 프록시를 통과하는 것은 아닙니다.

TUN: 시스템의 네트워크 트래픽을 코어로 전달하는 진입 경로입니다.
규칙: 코어에 들어온 연결을 직결, 프록시 또는 차단 중 어디로 보낼지 결정합니다.
환경 변수와 앱별 설정: 프로그램이 명시적 프록시를 지원할 때 연결 경로를 지정합니다. TUN과 함께 사용하면 이중 프록시가 되지 않는지 확인해야 합니다.

설정 메뉴의 위치는 Clash Verge, Clash Verge Rev, Clash for Windows 등 클라이언트마다 다릅니다. 메뉴 이름만 따라가기보다 실제로 실행 중인 코어와 최종 적용 설정을 확인하세요. TUN 설정 필드는 코어 버전에 따라 지원 여부와 세부 동작이 다를 수 있으므로, 설정을 적용하기 전에 코어의 버전과 시작 로그를 확인하는 편이 안전합니다.

mihomo TUN 기본 설정과 적용 순서

아래는 mihomo 계열 코어에서 자주 사용하는 TUN 설정의 예시입니다. 기존 전체 설정을 대체하는 파일이 아니라, 현재 설정에 병합할 조각입니다. 이미 tun, dns, rules 항목이 있다면 중복으로 만들지 말고 기존 값을 검토해 수정하세요. 특히 구독이 설정을 다시 생성하는 클라이언트에서는 편집한 값이 다음 업데이트 때 덮어써질 수 있습니다.

mixed-port: 7890
mode: rule
log-level: info

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

rules:
  - DOMAIN-SUFFIX,github.com,개발 프록시
  - DOMAIN-SUFFIX,githubusercontent.com,개발 프록시
  - DOMAIN-SUFFIX,npmjs.org,개발 프록시
  - DOMAIN-SUFFIX,pypi.org,개발 프록시
  - DOMAIN-SUFFIX,docker.io,개발 프록시
  - MATCH,DIRECT

7890은 예시 포트일 뿐입니다. 기존 클라이언트의 혼합 포트를 쓰고 있다면 실제 값을 유지하세요. 개발 프록시도 코어의 내장 이름이 아니라 예시 정책 그룹입니다. 현재 설정에 실제로 존재하는 프록시 그룹 이름으로 바꾸거나, 해당 이름의 그룹을 구성해야 합니다. 규칙이 그룹과 일치해도 그룹에서 DIRECT를 선택했다면 연결은 직결됩니다.

현재 설정을 백업하고 코어 버전, 클라이언트 버전, 운영체제를 기록합니다.
클라이언트의 TUN 사용 설정을 켭니다. YAML을 직접 관리한다면 해당 코어가 위 필드를 지원하는지 확인합니다.
Windows에서는 관리자 권한 또는 클라이언트가 제공하는 서비스 권한이 필요한지 확인합니다. macOS에서는 네트워크 확장 또는 VPN 구성 허용 요청이 표시될 수 있습니다.
코어를 다시 시작한 뒤 시작 로그에서 TUN 인터페이스가 생성되었는지, 설정 오류나 권한 오류가 없는지 확인합니다.
GitHub 같은 대상에 한 번만 접속하고 연결 목록에서 도메인, 매칭 규칙, 선택된 정책을 확인합니다.

Git·npm·PyPI 규칙과 셸 프록시

도메인 규칙은 해당 도메인으로 향하는 연결에 적용됩니다. GitHub 저장소의 코드 다운로드에는 github.com뿐 아니라 콘텐츠 전달용 도메인이 관여할 수 있고, npm 패키지 다운로드는 레지스트리 외부의 저장소나 CDN을 사용할 수도 있습니다. PyPI도 프로젝트 파일이 별도 호스트에서 제공될 수 있습니다. 접속이 일부 단계에서만 실패한다면 규칙을 무작정 넓히기보다 연결 목록에서 실패한 실제 도메인을 확인한 뒤 필요한 범위만 추가하세요.

예시의 DOMAIN-SUFFIX 규칙은 해당 도메인과 하위 도메인에 매칭됩니다. 목록에 없는 관련 도메인은 MATCH가 처리합니다. 개발 도구 트래픽만 프록시로 보내고 나머지는 직결하려면 마지막 규칙을 유지할 수 있지만, 모든 미분류 트래픽도 프록시로 보내려면 현재 정책에 맞게 최종 규칙을 바꿔야 합니다. 규칙은 위에서부터 평가되므로 일반 규칙보다 예외를 앞에 두세요.

TUN을 사용하지 않거나 특정 프로그램에 명시적 프록시를 지정해야 한다면 셸 환경 변수를 활용할 수 있습니다. 아래 주소와 포트는 예시이므로 실제 혼합 포트로 바꾸세요. Unix 계열 셸 예시이며, PowerShell에서는 환경 변수 지정 문법이 다릅니다.

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"
export NO_PROXY=localhost,127.0.0.1,.local

프록시를 지정했는데 요청이 실패하면 해당 프로그램이 환경 변수를 읽는지, 혼합 포트가 HTTP 요청을 받는지, 루프백 주소에 코어가 실제로 수신 대기 중인지 확인하세요. 환경 변수는 현재 셸과 그 자식 프로세스에만 적용되며, 별도로 실행되는 GUI 앱이나 서비스 데몬에 자동 전달되지 않습니다. 작업이 끝난 뒤 설정을 해제하려면 unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY NO_PROXY를 실행할 수 있습니다.

대상	우선 확인할 방법	실패 시 확인할 점
Git	TUN 또는 Git의 HTTP 프록시 설정	저장소 호스트, HTTPS 연결, Git 전용 설정이 환경 변수와 충돌하는지 확인
npm	TUN 또는 npm의 프록시 설정	현재 레지스트리 주소, 패키지 파일 호스트, 인증 설정 확인
PyPI	TUN 또는 셸 환경 변수	인덱스 URL과 실제 배포 파일 호스트를 구분
Docker	데몬 또는 Docker Desktop의 프록시 설정	셸 프록시가 데몬에 전달되는지, 컨테이너 내부 DNS와 별개인지 확인

Git에만 프록시를 지정하려면 git config --global http.proxy http://127.0.0.1:7890을 사용할 수 있습니다. 해제할 때는 git config --global --unset http.proxy를 실행합니다. 전역 설정은 이후 모든 저장소에 영향을 주므로, 회사 저장소나 내부 서버까지 같은 프록시로 보내도 되는지 확인하세요. npm도 버전과 설정에 따라 자체 프록시 값을 저장할 수 있으므로, TUN만 사용할 계획이라면 기존 프록시 설정이 남아 있지 않은지 살펴보세요.

Docker는 터미널·데몬·컨테이너를 따로 점검하기

docker pull 명령을 터미널에서 실행하더라도 이미지 다운로드를 실제로 수행하는 주체는 Docker 데몬입니다. 따라서 셸에서 https_proxy를 설정했다고 해서 데몬이 같은 값을 사용한다고 볼 수 없습니다. Linux의 Docker Engine은 데몬 서비스에 프록시를 설정해야 할 수 있고, Docker Desktop은 앱의 프록시 설정과 자체 가상화 네트워크 경로를 사용합니다. 메뉴와 적용 방식은 제품 버전에 따라 확인하세요.

또한 이미지 빌드 중 실행되는 RUN npm install은 컨테이너의 빌드 네트워크에서 실행됩니다. 호스트의 TUN이 해당 연결을 처리하는지, 빌드 도구에 프록시 변수를 전달해야 하는지는 운영체제와 Docker 설정에 따라 다릅니다. 컨테이너에 전달한 프록시 환경 변수는 이미지 레이어나 빌드 로그에 남을 수 있으므로 인증 토큰이나 비밀번호를 평문으로 넣지 마세요. 필요한 경우 Docker가 제공하는 빌드 시크릿 기능을 검토하세요.

docker pull만 실패하는지, 컨테이너 내부의 패키지 설치도 실패하는지 분리해 재현합니다.
이미지 레지스트리 주소와 코어 연결 목록의 실제 목적지 도메인을 비교합니다. 인증 요청, 토큰 발급, 이미지 레이어 전달이 서로 다른 호스트를 거칠 수 있습니다.
Docker Desktop에서는 호스트의 시스템 프록시와 앱의 프록시 설정, VPN/TUN 상태를 각각 확인합니다. 설정을 바꾼 뒤 데몬 또는 Desktop을 재시작해야 적용되는 경우가 있습니다.
Linux 데몬을 별도로 설정했다면 서비스 재시작 후 데몬 로그와 연결 목록을 확인합니다. 컨테이너의 DNS 문제를 호스트 TUN 문제로 단정하지 마세요.

레지스트리의 도메인 목록은 환경과 이미지 출처에 따라 달라집니다. 특정 호스트를 근거 없이 규칙에 추가하기보다, 실패한 요청을 재현해 실제 대상과 매칭 정책을 확인하세요. 로컬 레지스트리나 사내 미러를 사용하는 경우에는 해당 주소를 직결 예외로 두는 것이 외부 레지스트리 규칙보다 적절할 수 있습니다.

Windows·macOS에서 자주 겪는 문제 해결

Windows: 권한, 가상 어댑터, 라우팅

Windows에서 TUN 시작이 실패하면 클라이언트의 관리자 권한, 가상 어댑터 생성 상태, 보안 프로그램의 차단 여부를 순서대로 확인하세요. TUN을 켠 직후 네트워크가 끊기면 연결 목록에서 트래픽이 들어오는지 확인한 다음 기본 규칙과 정책 그룹을 점검합니다. auto-route가 켜져 있어도 해당 코어가 사용할 인터페이스나 시스템 라우팅이 충돌하면 예상한 경로가 만들어지지 않을 수 있습니다. 회사 VPN과 Clash TUN을 동시에 사용 중이라면 서로의 라우팅 우선순위도 확인해야 합니다.

macOS: 네트워크 권한과 VPN 경로

macOS에서는 네트워크 확장 또는 VPN 구성 추가 권한을 거부하면 TUN 인터페이스가 정상적으로 준비되지 않을 수 있습니다. 시스템 설정에서 앱 권한을 확인하고, 클라이언트가 실행한 코어가 최신 변경 설정을 읽었는지 시작 로그로 확인하세요. 다른 VPN 앱이나 보안 도구가 동시에 기본 경로를 변경하면 연결이 불안정해질 수 있습니다. 먼저 한쪽을 끄고 동일한 요청을 재현해 충돌 여부를 좁혀 보세요.

두 운영체제 모두 진단을 위해 전체 설정을 한 번에 바꾸지 않는 것이 좋습니다. 먼저 TUN을 켠 상태에서 대상 연결이 코어에 나타나는지 확인하고, 다음으로 규칙 매칭 결과와 정책 그룹을 살펴보세요. 연결 자체가 보이지 않으면 규칙을 추가해도 해결되지 않습니다. 반대로 연결이 표시되지만 시간 초과가 발생하면 선택된 프록시 노드, DNS 응답, 원격 호스트 연결을 구분해 점검해야 합니다.

자주 묻는 질문

TUN과 환경 변수를 동시에 사용해야 하나요?

항상 필요한 것은 아닙니다. TUN이 필요한 트래픽을 처리하고 있다면 환경 변수는 추가하지 않아도 됩니다. 특정 도구만 별도 프록시를 요구하거나 TUN이 포착하지 않는 경로를 사용하는 경우에만 앱별 설정을 검토하세요. 두 방식이 동시에 적용되면 프록시 요청이 다시 프록시로 전달되는 루프가 생기는지 확인해야 합니다.

브라우저는 되는데 Git만 실패하는 이유는 무엇인가요?

브라우저가 시스템 프록시를 따르더라도 Git 실행 환경은 같은 설정을 사용하지 않을 수 있습니다. TUN 연결 목록에 Git의 목적지가 나타나는지 확인하세요. 나타나지 않는다면 TUN 권한과 라우팅을, 나타나지만 직결로 선택된다면 규칙과 순서를, 프록시로 선택된 뒤 실패한다면 노드와 연결 오류를 점검합니다.

Docker pull만 실패하면 어디를 확인하나요?

Docker 데몬 또는 Docker Desktop의 프록시 설정을 확인하고, 셸에서 설정한 변수와 별개로 동작하는지 살펴보세요. 이어서 연결 목록에서 레지스트리 인증과 이미지 전달에 사용된 실제 도메인을 확인합니다. 컨테이너 내부 패키지 설치까지 실패한다면 데몬 경로와 컨테이너 빌드 네트워크를 각각 점검해야 합니다.

TUN을 켜면 모든 트래픽이 프록시로 가나요?

아닙니다. TUN은 트래픽을 코어로 전달하는 수단이고 최종 경로는 규칙, 모드, 정책 그룹, 프로세스별 제외 설정 등에 따라 달라집니다. 연결 목록에서 매칭된 규칙과 최종 아웃바운드를 확인하고, 필요한 목적지만 의도한 정책으로 보내도록 설정하세요.

개발 작업에 사용할 클라이언트와 설치 파일은 운영체제에 맞춰 선택해야 합니다. 다운로드에서 Windows 또는 macOS용 항목을 확인하고, 설치 후에는 현재 코어가 사용하는 설정과 지원 필드를 먼저 검증하세요.