개발자 Clash TUN 설정: Git·npm·Docker 터미널 프록시 구성하기

시스템 프록시를 켰는데 터미널 연결은 실패하는 이유

Clash 클라이언트에서 시스템 프록시를 활성화해도 Git, npm, Docker가 모두 자동으로 프록시를 사용하는 것은 아닙니다. 시스템 프록시는 보통 운영체제의 프록시 설정을 참고하는 앱에 적용되지만, 명령줄 도구는 자체 설정이나 환경 변수를 우선할 수 있습니다. Docker는 명령을 실행하는 터미널이 아니라 별도의 데몬이 이미지를 다운로드하는 경우가 많아, 셸에 프록시 변수를 설정한 것만으로 해결되지 않을 수 있습니다.

먼저 클라이언트가 mihomo 코어를 사용하는지 확인하세요. 이 문서의 TUN 예시는 mihomo 기준이며, 구형 코어나 일부 모바일 클라이언트에서는 같은 필드를 지원하지 않을 수 있습니다. 현재 설정을 백업한 뒤 클라이언트의 커널 정보와 로그에서 TUN 시작 오류를 확인하세요. 메뉴 이름은 버전에 따라 다를 수 있지만, Clash Verge Rev에서는 보통 「설정」의 「TUN 모드」 또는 「서비스 모드」 관련 항목에서 설정합니다.

증상	우선 확인할 항목	권장 접근
브라우저는 되지만 Git만 실패	Git의 proxy 설정과 저장소 주소	Git에 명시적 프록시를 지정하거나 TUN 경로 확인
npm에서 시간 초과 발생	레지스트리 주소, npm proxy 설정	현재 레지스트리와 연결 로그를 대조
Docker 이미지 다운로드 실패	Docker 데몬의 프록시 설정	데몬 설정을 별도로 점검하고 재시작
모든 CLI 도구가 실패	TUN 상태, 기본 경로, DNS, 방화벽	시스템 프록시와 TUN을 분리해 한 단계씩 테스트

TUN과 명시적 프록시 중 사용할 방식을 선택

TUN은 가상 네트워크 인터페이스를 통해 시스템 트래픽을 mihomo로 전달하는 방식입니다. 도구별 프록시 옵션을 설정하지 않아도 연결이 라우팅될 수 있지만, 모든 앱과 데몬이 같은 경로를 사용한다고 보장하지는 않습니다. 권한, 라우팅 테이블, 방화벽, IPv6, 컨테이너 네트워크가 영향을 줍니다. 반면 명시적 프록시는 앱에 프록시 주소를 직접 알려 주므로 한 도구만 시험하거나 TUN을 사용할 수 없는 환경에서 유용합니다.

문제를 분리하려면 먼저 브라우저나 명시적 프록시 요청으로 mihomo의 로컬 포트가 응답하는지 확인하세요. 그다음 TUN을 켜고 같은 대상에 다시 요청합니다. 둘 다 실패하면 코어, 포트, 노드 또는 규칙을 살펴보고, 명시적 프록시만 성공하면 TUN의 라우팅이나 권한 쪽을 우선 조사할 수 있습니다.

mihomo 설정을 직접 관리하는 경우 아래는 TUN 항목의 형태를 보여 주는 예시입니다. 기존 설정에 이미 tun이 있다면 항목을 중복 추가하지 말고 필요한 필드만 병합하세요. 클라이언트가 설정을 생성하거나 덮어쓰는 구조라면 GUI에서 설정하는 편이 안전합니다.

tun:
  enable: true
  stack: mixed
  auto-route: true
  strict-route: true

stack 지원 값과 기본값은 mihomo 버전에 따라 달라질 수 있습니다. auto-route는 경로 설정을 자동화하고 strict-route는 일부 환경에서 TUN을 우회하는 트래픽을 제한하는 데 사용됩니다. 이를 켠 뒤 사내 네트워크, 프린터, 원격 접속이 끊기면 임의로 방화벽을 해제하지 말고 로그와 라우팅을 확인한 다음 필요한 로컬 네트워크 예외만 검토하세요. TUN 실행에 관리자 권한이나 클라이언트의 서비스 모드가 필요한 운영체제도 있습니다.

터미널에서 연결과 DNS를 먼저 검증

프록시 설정을 바꾸기 전에 현재 상태를 기록하세요. 시스템 프록시만 켠 상태에서 실패한 명령과 오류 메시지, 현재 선택한 정책 그룹, 연결 패널에 표시된 규칙을 확인합니다. 같은 명령을 TUN 활성화 후 다시 실행하면 변경 효과를 비교하기 쉽습니다. 터미널이 새로 시작된 뒤에도 환경 변수가 유지되는지 확인하고, 다른 VPN이나 프록시 프로그램이 기본 경로를 함께 변경하고 있지 않은지도 살펴보세요.

명시적 프록시 테스트는 아래처럼 실행할 수 있습니다. curl이 설치되어 있어야 하며, 주소와 포트는 실제 HTTP 프록시 수신값으로 바꾸세요.

curl -I --proxy http://127.0.0.1:7890 https://example.com
curl -I https://example.com

첫 번째 요청은 프록시를 명시하고, 두 번째 요청은 기본 연결 경로를 사용합니다. 첫 번째만 성공하면 앱별 프록시 설정 또는 TUN 경로를 점검하세요. 두 번째가 성공해도 대상 서비스의 모든 도메인과 다운로드 서버가 같은 규칙으로 처리된다는 뜻은 아니므로, Clash 연결 패널에서 해당 요청의 도메인, 일치 규칙, 최종 출구를 확인합니다.

Windows PowerShell에서는 Get-ChildItem Env:HTTP_PROXY와 Get-ChildItem Env:HTTPS_PROXY로 변수 상태를 확인할 수 있습니다.
macOS와 Linux의 셸에서는 env | grep -i proxy로 현재 터미널의 프록시 환경 변수를 확인할 수 있습니다.
DNS 오류가 함께 나타나면 nslookup 또는 운영체제의 DNS 점검 도구로 이름 해석 결과를 확인하고, 연결 로그와 DNS 설정을 대조하세요. 연결 거부와 이름 해석 실패는 원인이 다릅니다.
오류가 난 요청의 대상 주소와 시간을 기록하세요. 연결 패널에서 같은 시각의 요청을 찾으면 규칙이 적용됐는지 구분하기 쉽습니다.

Git과 npm에 프록시를 적용하는 방법

Git은 설정값과 저장소별 예외를 확인

Git은 시스템 프록시를 자동으로 따르지 않을 수 있습니다. TUN으로 Git 트래픽이 정상적으로 라우팅된다면 별도 설정은 필요하지 않습니다. 명시적 프록시를 사용하려면 다음처럼 HTTP 프록시를 지정할 수 있습니다. 이 설정은 Git이 사용하는 HTTP 및 HTTPS 전송에 적용되며, SSH 주소 형식의 저장소 연결에는 그대로 적용되지 않습니다.

git config --global http.proxy http://127.0.0.1:7890
git config --global --get http.proxy

SOCKS5 수신 포트를 사용하는 환경이라면 실제 포트에 맞춰 socks5h://127.0.0.1:포트 형식을 사용할 수 있습니다. 프록시에서 DNS 이름을 해석하도록 하는 socks5h와 로컬에서 이름을 해석하는 socks5는 동작이 다릅니다. 설정된 프록시가 모든 저장소에 영향을 주는 것이 부담스럽다면 저장소별 설정을 사용하거나 문제가 해결된 뒤 전역 값을 지우세요.

git config --global --unset http.proxy

저장소가 SSH URL을 사용한다면 Git의 http.proxy 설정은 해당 연결을 바꾸지 않습니다. TUN 경로가 SSH 연결을 처리하는지 확인하거나, 조직에서 허용하는 SSH 프록시 방식을 별도로 검토하세요. 접속 포트 변경이나 SSH 설정을 적용할 때는 회사 네트워크 정책을 우선해야 합니다.

npm은 레지스트리와 환경 변수를 함께 확인

npm 설치 실패는 프록시뿐 아니라 레지스트리 선택, 인증, 패키지 저장소 접근 제한 때문에도 발생합니다. 먼저 현재 설정을 확인하세요.

npm config get registry
npm config get proxy
npm config get https-proxy

명시적 프록시를 사용한다면 현재 포트에 맞게 설정하고, 테스트 후 필요하면 제거하세요. 조직에서 관리하는 레지스트리나 인증 프록시가 있다면 개인용 예시 주소로 덮어쓰지 마세요.

npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
npm config delete proxy
npm config delete https-proxy

설정값이 사용자 전역 파일, 프로젝트의 .npmrc, 환경 변수에서 각각 지정될 수 있습니다. 명령으로 설정했는데도 효과가 없으면 프로젝트 디렉터리에 별도 설정이 있는지 확인하세요. TLS 인증서 검증을 끄는 방식으로 연결 문제를 우회하지 마세요. 인증서 오류가 나타나면 시스템 시간, 기업용 인증서 구성, 프록시의 TLS 검사 정책을 관리자와 확인합니다.

Docker 데몬과 운영체제별 점검 순서

Docker CLI는 데몬에 명령을 전달하고, 이미지를 내려받는 작업은 보통 Docker 데몬이 수행합니다. 따라서 터미널에 HTTP_PROXY를 설정해도 데몬의 네트워크 연결에는 반영되지 않을 수 있습니다. Docker Desktop은 가상화된 환경을 사용하므로 호스트의 TUN 경로와 컨테이너의 브리지 경로가 서로 다를 수 있습니다. 원격 Docker 컨텍스트를 사용한다면 다운로드 요청은 로컬 PC가 아니라 원격 데몬에서 발생합니다.

먼저 docker context show로 현재 대상이 로컬인지 확인하고, docker pull의 오류가 인증, DNS, 시간 초과 중 무엇인지 구분하세요. 연결이 시간 초과되면 Docker Desktop의 프록시 설정이나 Linux 데몬의 서비스 설정을 확인해야 할 수 있습니다. 데몬 설정을 바꾼 뒤에는 해당 서비스를 계획적으로 재시작하세요. 운영 중인 컨테이너가 중단될 수 있으므로 작업 시간을 고려하고 설정 파일을 백업합니다.

환경	우선 확인	주의 사항
Windows	클라이언트의 TUN 스위치와 서비스 권한	Docker Desktop 사용 시 데몬과 가상 네트워크 경로도 점검
macOS	TUN 인터페이스 권한과 클라이언트 로그	Docker Desktop의 프록시 설정은 호스트 설정과 별도일 수 있음
Linux	관리자 권한, 경로, 방화벽과 서비스 상태	rootless Docker는 일반 데몬과 네트워크 동작이 다를 수 있음
원격 Docker	현재 컨텍스트와 원격 호스트의 프록시	로컬 터미널의 TUN만으로 원격 다운로드를 처리하지 못함

Windows에서는 「설정」→「네트워크 및 인터넷」→「프록시」에서 시스템 프록시 주소를 확인한 뒤, Clash 클라이언트에서 TUN 상태와 서비스 시작 여부를 점검하세요. 관리자 권한이 필요한 작업은 신뢰할 수 있는 클라이언트에서만 실행합니다. macOS에서는 클라이언트가 가상 인터페이스를 만들 수 있도록 요청한 권한을 확인하고, TUN을 껐다 켤 때 연결이 복구되는지 확인하세요. Linux에서는 ip route로 기본 경로를 확인하고, 배포판의 방화벽 및 네트워크 관리 서비스가 TUN 경로를 덮어쓰지 않는지 점검합니다.

자주 묻는 질문

TUN을 켜면 Git 설정도 반드시 추가해야 하나요?

아닙니다. TUN이 Git 연결을 정상적으로 받아 처리한다면 Git의 별도 프록시 설정은 필요하지 않습니다. 다만 Git의 전송 방식, SSH 연결, 운영체제의 라우팅 정책에 따라 결과가 달라질 수 있으므로 실제 연결 로그로 확인하세요. TUN과 Git 프록시를 동시에 설정해 연결이 중복되거나 예상과 다른 경로를 타면 한쪽 설정을 잠시 제거해 비교합니다.

터미널에 HTTP_PROXY를 설정했는데 왜 적용되지 않나요?

명령을 실행하는 프로세스가 환경 변수를 읽지 않거나, HTTPS_PROXY만 별도로 확인할 수 있습니다. 이미 실행 중인 IDE나 터미널은 변수를 상속하지 않았을 수도 있습니다. 새 터미널에서 값을 확인하고, Git·npm의 자체 설정과 프로젝트별 설정이 우선하는지 함께 살펴보세요. Docker 데몬처럼 별도 서비스로 실행되는 프로세스에는 셸의 변수가 전달되지 않을 수 있습니다.

Docker 이미지 다운로드가 실패하면 컨테이너에도 프록시를 설정해야 하나요?

이미지를 가져오는 단계와 컨테이너 내부 앱의 연결은 별개의 작업입니다. 이미지 다운로드는 데몬의 프록시 및 네트워크 경로를 확인하고, 컨테이너 안에서 실행되는 앱이 외부로 나가지 못할 때는 컨테이너 환경 변수, 네트워크, DNS를 따로 점검하세요. 원격 컨텍스트라면 원격 데몬의 설정이 기준입니다.

TUN과 명시적 프록시를 함께 사용해도 되나요?

기술적으로 가능하지만, 한 요청이 명시적 프록시와 TUN을 모두 통과하면 이중 라우팅이나 연결 실패가 생길 수 있습니다. 먼저 TUN만으로 시험하고 필요한 도구에만 명시적 프록시를 적용하세요. 문제가 해결된 뒤에는 사용하지 않는 전역 프록시 값과 임시 환경 변수를 정리하고, localhost와 사내 주소가 의도치 않게 외부 노드로 전달되지 않는지 확인합니다.