이 글이 필요한 개발 환경
Git, SSH, npm, pip, Homebrew, Docker를 한 컴퓨터에서 함께 사용하는 개발자는 도구마다 프록시 설정을 따로 넣다가 누락을 만들기 쉽습니다. 브라우저는 정상적으로 열리는데 git clone만 멈추거나, npm 패키지는 내려받아지는데 Docker 이미지가 타임아웃되는 식의 문제는 대개 서비스 장애보다 프로세스별 네트워크 경로가 서로 다르기 때문입니다.
이 글에서는 Clash Verge Rev 또는 Mihomo 계열 클라이언트를 기준으로, TUN 모드로 운영체제의 다양한 연결을 하나의 라우팅 계층에 모으는 방법을 설명합니다. 단순히 모든 트래픽을 글로벌 프록시로 보내는 것이 아니라, 외부 Git 호스팅·패키지 저장소·컨테이너 레지스트리는 프록시 그룹으로 보내고, 사내 GitLab·개발 서버·로컬 네트워크는 DIRECT로 남기는 구성을 목표로 합니다.
TUN은 만능 해결책이 아닙니다. 가상 네트워크 인터페이스와 DNS 처리 권한이 필요하고, 회사 보안 프로그램이나 VPN과 충돌할 수 있습니다. 따라서 먼저 현재 증상을 확인하고, 프로필·DNS·라우팅 규칙·터미널 환경 변수 순서로 점검해야 설정을 안정적으로 유지할 수 있습니다.
TUN 모드를 켜기 전 확인할 항목
TUN 모드는 애플리케이션이 프록시를 지원하는지와 관계없이 시스템 트래픽을 Clash 코어로 넘기는 방식입니다. 브라우저처럼 시스템 프록시를 잘 따르는 프로그램뿐 아니라, 프록시 옵션이 제한적인 일부 CLI와 백그라운드 런타임도 같은 정책을 적용받을 수 있다는 점이 가장 큰 장점입니다. 반면 관리자 권한, 네트워크 확장 허용, 가상 인터페이스 생성 권한이 필요할 수 있습니다.
먼저 Clash 클라이언트에서 활성 프로필과 코어 상태를 확인합니다. 구독을 가져온 뒤 프로필이 선택되지 않았거나 코어가 재시작을 반복하면 TUN을 켜도 정상적인 라우팅이 이루어지지 않습니다. 모드가 Rule인지, 혼합 포트가 어떤 번호로 열려 있는지, DNS 모드가 현재 코어와 호환되는지도 기록해 두세요. 나중에 터미널 변수와 로그를 비교할 때 이 정보가 기준점이 됩니다.
- 프로필: 실제로 사용 중인 구독과 규칙 세트가 선택되어 있어야 합니다.
- 모드: 개발 환경에서는 보통 Rule 모드가 적합합니다. 사내망과 외부 서비스를 분리하기 쉽습니다.
- TUN 권한: Windows의 관리자 권한, macOS의 네트워크 확장 허용 등 운영체제별 승인 절차를 완료합니다.
- DNS: 도메인 규칙을 사용한다면 DNS 요청도 의도한 경로로 처리되는지 확인합니다.
- 충돌 요소: 회사 VPN, WSL 네트워크, Docker Desktop, 다른 VPN 클라이언트가 가상 인터페이스를 동시에 만들고 있지 않은지 살핍니다.
TUN이 켜졌다고 모든 연결이 자동으로 프록시를 타는 것은 아닙니다. 규칙이 해당 도메인을 DIRECT로 선택하면 직접 연결되고, DNS 결과가 IP 주소로 먼저 고정되면 도메인 기반 규칙이 기대와 다르게 동작할 수도 있습니다. 따라서 상태 화면의 TUN 스위치만 보지 말고, 연결 로그에서 실제 호스트와 정책 그룹을 함께 확인해야 합니다.
외부 서비스와 사내망을 분리하는 규칙 설계
개발용 프로필에서 가장 중요한 것은 “개발 관련 도메인은 전부 프록시”라는 식의 넓은 규칙을 피하는 것입니다. GitHub를 프록시로 보내야 한다고 해서 사내 GitLab이나 내부 패키지 레지스트리까지 같은 그룹으로 보내면 인증 지연과 내부 DNS 오류가 발생할 수 있습니다. 먼저 업무망을 두 범주로 나누고, 예외를 더 구체적인 순서로 배치하는 편이 안전합니다.
- 사내망과 로컬 주소: 사내 도메인, 사설 IP 대역,
localhost,127.0.0.1, Docker 내부 주소는 직접 연결하거나 조직 정책에 맞는 경로로 둡니다. - 외부 개발 서비스: GitHub, GitLab SaaS, npm, PyPI, Homebrew 저장소, Docker Hub 등 실제로 프록시가 필요한 호스트를 그룹화합니다.
- 기타 트래픽: 명시되지 않은 일반 웹과 운영체제 서비스는 기본 정책을 정해 예측 가능하게 만듭니다.
규칙은 일반적으로 위에서 아래로 평가되므로, 사내 예외를 외부 서비스보다 위에 둬야 합니다. 예를 들어 사내 GitLab이 git.company.example 아래에 있다면 해당 DOMAIN-SUFFIX 규칙을 GitLab 전체 규칙보다 먼저 배치합니다. 내부 패키지 저장소가 npm.company.example처럼 별도 호스트를 사용한다면 npm이라는 키워드만 보고 프록시로 보내지 말고 정확한 도메인을 예외로 선언하세요.
외부 서비스 규칙도 실제 사용 호스트를 기준으로 작성해야 합니다. GitHub의 웹 페이지와 Git 전송 호스트가 다를 수 있고, npm이나 Docker가 인증·리디렉션·CDN을 위해 여러 도메인을 호출할 수 있습니다. 처음부터 지나치게 많은 도메인을 추측해 넣기보다는, 실패 직후 Clash 연결 로그에서 Host 또는 SNI를 확인해 필요한 범위만 추가하는 방법이 좋습니다. 규칙을 수정한 뒤에는 프로필을 다시 적용하고 코어를 재시작해 이전 캐시의 영향을 줄입니다.
Git·npm·pip·Homebrew의 터미널 연결 맞추기
TUN 모드가 CLI 트래픽을 덮더라도, 도구별 프록시 변수를 명시하면 동작을 더 예측하기 쉬운 경우가 많습니다. 특히 TUN을 사용할 수 없는 원격 SSH 세션이나 CI 환경에서는 환경 변수 설정이 여전히 필요합니다. Clash의 mixed-port가 HTTP 프록시를 제공한다면 보통 http://127.0.0.1:포트 형식으로 지정합니다. 실제 포트 번호는 클라이언트 화면과 일치해야 하며, 예시 값을 그대로 복사하면 안 됩니다.
- HTTP 기반 도구:
HTTP_PROXY,HTTPS_PROXY,ALL_PROXY를 사용하는지 도구 문서에서 확인합니다. - 예외 목록:
NO_PROXY에 사내 GitLab, 내부 레지스트리,localhost,127.0.0.1을 넣어 불필요한 우회를 막습니다. - 셸 세션:
~/.zshrc,~/.bashrc, PowerShell 프로필 중 실제 터미널이 읽는 파일에만 설정합니다. - IDE 터미널: VS Code나 JetBrains를 이미 실행한 뒤 프로필을 수정했다면 IDE를 다시 시작해 새 환경 변수를 상속시킵니다.
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,.internal.example위 예시는 형식만 보여 주는 것이며 포트와 내부 도메인은 자신의 환경에 맞게 바꿔야 합니다. Git은 일반 HTTPS 저장소와 SSH 저장소가 서로 다른 경로를 사용합니다. https://github.com/...를 clone할 때는 Git의 HTTP 프록시나 환경 변수가 영향을 주지만, [email protected]:... 형식의 SSH는 별도 설정이 필요합니다. SSH를 프록시로 보내야 한다면 OpenSSH의 ProxyCommand와 Clash가 제공하는 SOCKS 포트 조합을 검토하되, 회사 정책과 키 보안 요구를 먼저 확인하세요.
npm과 pip는 전역 설정을 저장할 수도 있지만, 개인 토큰이나 사내 레지스트리 주소가 설정 파일에 평문으로 남을 수 있습니다. 팀 저장소에 설정 파일을 커밋하지 말고, 공개 패키지와 사내 패키지의 레지스트리를 구분하세요. Homebrew는 저장소 접근과 Git 기반 업데이트가 각각 다른 호스트를 사용할 수 있으므로, 한 번의 다운로드 성공만으로 전체 구성이 끝났다고 판단하면 안 됩니다.
SSH·Docker에서 자주 생기는 경로 불일치
로컬 셸에서 curl과 Git이 성공하는데 Docker 컨테이너 안의 npm install이 실패한다면, 컨테이너는 호스트와 다른 네트워크 네임스페이스에 있기 때문일 수 있습니다. TUN이 호스트의 트래픽을 처리하더라도 Docker Desktop의 VM, WSL2, Linux bridge가 별도의 DNS와 라우팅을 사용할 수 있습니다. 이때는 컨테이너 내부에서 DNS가 해석되는지, 기본 게이트웨이가 어디인지, 프록시 환경 변수가 전달됐는지를 각각 확인해야 합니다.
Docker build 단계에서는 실행 중인 셸의 환경 변수가 자동으로 이미지 빌드에 들어가지 않을 수 있습니다. 반대로 무심코 ENV HTTPS_PROXY=...를 이미지에 넣으면 프록시 주소가 레이어와 이미지 검사 결과에 남을 수 있어 보안상 위험합니다. 빌드 전용 인자나 BuildKit의 시크릿 기능을 활용하고, 최종 이미지에는 프록시와 인증 정보를 남기지 않는 구성을 우선하세요.
원격 개발 서버에 SSH로 접속하는 경우에는 로컬 Clash TUN이 원격 호스트의 outbound 트래픽까지 대신 처리하지 않습니다. SSH 연결 자체는 로컬에서 프록시를 타더라도, 원격 서버에서 실행한 git pull, npm install, Docker 빌드는 원격 서버의 네트워크를 사용합니다. 원격 서버에도 합법적인 시스템 프록시나 별도 Clash 인스턴스가 필요한지 확인하고, 로컬 설정이 원격 작업까지 자동으로 적용된다고 가정하지 마세요.
로그와 테스트 명령으로 최종 검증하기
설정이 끝난 뒤에는 “브라우저가 열린다”보다 실제 개발 명령의 결과를 기준으로 판단해야 합니다. 먼저 Clash 연결 로그를 열고 테스트를 실행합니다. 외부 Git 호스팅에 대한 DNS 조회와 HTTPS 요청이 기대한 프록시 그룹으로 잡히는지 확인하고, 사내 GitLab과 로컬 개발 서버는 DIRECT 또는 조직에서 정한 내부 그룹으로 기록되는지 비교합니다.
- DNS 확인: 운영체제와 컨테이너에서 같은 도메인이 해석되는지 비교합니다.
- HTTPS 확인:
curl -I로 헤더 응답과 리디렉션을 확인하되, 토큰을 명령줄에 직접 넣지 않습니다. - Git 확인: 작은 공개 저장소를 clone하거나 fetch해 DNS, TLS, 인증 단계를 분리해 봅니다.
- 패키지 확인: npm과 pip에서 공개 저장소·사내 저장소를 각각 테스트합니다.
- 컨테이너 확인: 호스트와 컨테이너 내부에서 같은 외부 도메인을 조회해 네트워크 경로 차이를 확인합니다.
407 Proxy Authentication Required가 보이면 포트나 정책보다 프록시 인증 형식을 먼저 확인해야 합니다. ENOTFOUND는 DNS 또는 컨테이너의 resolver 문제일 수 있고, ETIMEDOUT은 잘못된 DIRECT 분기, 불안정한 노드, MTU, 방화벽을 함께 살펴야 합니다. TLS 인증서 오류가 발생하면 인증서 검증을 무조건 끄지 말고, 중간자 프록시나 회사 보안 장비가 인증서를 교체하는 환경인지 IT 정책을 확인하세요.
문제가 해결된 뒤에는 설정을 그대로 복사해 여러 장치에 배포하기보다, 개인 토큰과 사내 도메인을 분리한 템플릿을 관리하는 편이 좋습니다. 프로필 변경 날짜, TUN 권한 상태, mixed-port, 예외 도메인을 짧은 문서로 기록하면 팀원이 노트북을 교체하거나 IDE를 바꿀 때 재현 시간이 크게 줄어듭니다. 또한 프록시를 사용하면 연결 로그에 호스트 정보가 남을 수 있으므로, 민감한 저장소 URL·토큰·소스 코드가 로그에 포함되지 않는지도 정기적으로 점검하세요.
도구별 확장 기능에만 의존하는 방식은 Git은 되지만 npm이 빠지고, 로컬 터미널은 되지만 Docker가 빠지는 식의 누락을 만들기 쉽습니다. 반대로 모든 트래픽을 글로벌로 보내면 사내망과 내부 레지스트리까지 우회해 지연과 정책 충돌이 생길 수 있습니다. 이 글처럼 Clash TUN을 공통 기반으로 두고, 외부 서비스는 규칙 그룹으로 묶고, 사내망은 NO_PROXY와 구체적인 예외 규칙으로 분리하면 개발 흐름을 유지하면서도 경로를 로그로 확인할 수 있습니다. 여러 플랫폼의 CLI와 컨테이너를 한 번에 관리할 클라이언트를 찾고 있다면, 지원 환경에 맞는 Clash 빌드를 내려받아 같은 원칙으로 구성해 보세요.