개발자를 위한 Clash TUN 설정: Git·npm·AI 코딩 도구 연결 가이드

브라우저 프록시만으로 개발 도구가 연결되지 않는 이유

브라우저에서 웹사이트가 정상적으로 열리는데도 git clone, npm install, Docker 이미지 다운로드, IDE 확장 기능이 실패하는 상황은 흔합니다. 가장 큰 이유는 브라우저와 터미널 프로그램이 프록시 설정을 읽는 위치가 서로 다르기 때문입니다. Clash의 시스템 프록시를 켜면 운영체제의 HTTP·HTTPS 프록시 설정을 따르는 애플리케이션은 프록시를 사용할 수 있지만, 모든 프로그램이 이 설정을 자동으로 확인하는 것은 아닙니다.

Git은 자체 설정에 저장된 HTTP 프록시를 우선 사용하거나, 별도의 SSH 연결을 만들 수 있습니다. Node.js 패키지 매니저는 npm 설정, 환경 변수, 패키지 관리자별 설정을 조합하며, 일부 도구는 시스템 프록시를 전혀 참조하지 않습니다. Docker CLI도 Docker Desktop의 네트워크 경로와 호스트 셸의 프록시 설정이 분리될 수 있습니다. AI 코딩 도구 역시 IDE 내부 확장, 별도 로그인 프로세스, 로컬 에이전트가 각각 다른 연결을 만들 수 있습니다.

이때 TUN 모드는 애플리케이션별 프록시 지원 여부와 관계없이 운영체제에서 발생하는 IP 트래픽을 가상 네트워크 인터페이스로 받아 Clash 코어의 규칙에 전달합니다. 즉, 브라우저에 프록시를 수동으로 지정하는 방식이 아니라 시스템 네트워크 계층에서 트래픽을 처리하는 방식입니다. 다만 TUN이 켜졌다고 해서 모든 문제가 자동으로 해결되는 것은 아닙니다. DNS 처리, 라우팅 규칙, IPv6, 로컬 주소 예외, 개발 도구의 자체 인증 정책까지 함께 점검해야 안정적인 작업 환경을 만들 수 있습니다.

TUN을 켜기 전에 확인할 권한과 구성 요소

Clash Verge Rev, Clash Nyanpasu, FlClash 등 mihomo 코어를 사용하는 클라이언트는 운영체제에 따라 TUN을 구현하는 방식과 표시되는 메뉴 이름이 다를 수 있습니다. 설정에서 General, System, TUN, Service Mode와 비슷한 항목을 찾아야 합니다. 단순히 스위치가 보이는지보다 코어가 실제로 해당 기능을 지원하는지, 현재 프로파일이 TUN 설정을 포함하는지 확인하는 편이 정확합니다.

• Windows: 가상 네트워크 어댑터 설치와 라우팅 테이블 변경을 위해 관리자 권한 또는 서비스 모드가 필요할 수 있습니다. TUN을 켠 뒤 Windows 네트워크 어댑터 목록에 새 인터페이스가 생성되는지 확인합니다.
• macOS: 네트워크 확장 프로그램 또는 시스템 확장 프로그램 승인 단계가 필요합니다. 권한 승인 후 클라이언트를 재시작해야 TUN이 실제로 활성화되는 경우도 있습니다.
• Linux: 배포판과 실행 방식에 따라 /dev/net/tun 장치, 네트워크 권한, systemd 서비스 권한이 필요합니다. 컨테이너 안에서 실행한다면 호스트의 네트워크 권한과 장치 전달 여부도 별도로 확인해야 합니다.
• Android: TUN은 일반적으로 Android VPN 권한을 사용합니다. 다른 VPN 앱이 이미 실행 중이면 Clash가 VPN 인터페이스를 만들지 못하므로 기존 VPN 연결을 먼저 종료해야 합니다.

처음부터 모든 옵션을 한꺼번에 켜기보다, 먼저 코어를 실행하고 시스템 프록시를 끈 상태에서 TUN만 활성화해 연결 변화를 관찰하는 것이 좋습니다. TUN과 시스템 프록시를 동시에 켜면 일부 애플리케이션의 트래픽이 중복 처리되거나, 프록시 포트로 다시 돌아오는 루프가 생길 수 있습니다. 일반적인 사용에서는 TUN을 주 경로로 정하고 시스템 프록시는 필요한 경우에만 보조적으로 사용하는 구성이 관리하기 쉽습니다.

개발 작업에 맞는 기본 TUN과 DNS 설정

프로파일을 직접 편집할 수 있다면 아래와 같은 방향에서 시작할 수 있습니다. 실제 클라이언트가 요구하는 필드명이나 기본값은 코어 버전에 따라 달라질 수 있으므로, 이미 존재하는 프로파일의 구조를 유지하면서 필요한 항목만 추가해야 합니다.

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

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "localhost"
    - "+.internal"

auto-route는 시스템 라우팅을 TUN으로 연결하는 데 사용되고, auto-detect-interface는 현재 실제 인터넷에 연결된 인터페이스를 자동으로 찾도록 돕습니다. 노트북에서 Wi-Fi와 유선 네트워크를 자주 전환한다면 특히 유용합니다. strict-route는 운영체제의 기본 경로를 우회해 TUN을 통하지 않는 누수를 줄이는 데 도움이 되지만, 로컬 네트워크나 특수한 가상 어댑터와 충돌할 수 있으므로 문제가 생기면 일시적으로 끄고 원인을 분리해야 합니다.

DNS는 개발 도구 연결 실패의 주요 원인입니다. Fake-IP 모드에서는 도메인에 가상 주소를 반환하고 mihomo가 내부 매핑을 유지하므로 도메인 기반 규칙을 적용하기 쉽습니다. 그러나 *.local, 사내 도메인, NAS와 프린터 주소처럼 로컬 네트워크에서 실제 IP가 필요한 이름은 fake-ip-filter에 넣어야 합니다. 사내 DNS에서만 해석되는 도메인을 공용 DoH 서버에 보내면 이름이 존재하지 않는 것으로 처리될 수 있으므로, 업무망을 사용하는 경우에는 nameserver-policy나 별도 DNS 규칙을 함께 구성해야 합니다.

Git·npm·Docker를 단계별로 연결하는 방법

개발 환경은 한 번에 전체를 테스트하기보다 실제 작업 순서대로 확인하는 편이 좋습니다. 먼저 DNS와 일반 HTTPS 연결을 확인한 다음 저장소 복제, 의존성 설치, 컨테이너 이미지 다운로드 순서로 진행하면 어느 계층에서 문제가 생겼는지 빠르게 좁힐 수 있습니다.

1. 도메인 해석과 HTTPS 확인. 터미널에서 저장소 호스트의 도메인이 해석되는지 확인하고, 브라우저가 아닌 터미널 HTTPS 요청으로 같은 주소에 접근합니다. DNS는 되지만 HTTPS만 실패하면 규칙이나 TLS 경로를 확인해야 합니다.
2. Git HTTPS 연결 확인. git ls-remote https://example.com/team/project.git처럼 실제 원격 저장소의 메타데이터를 읽어봅니다. 이 단계가 성공하면 전체 저장소를 받기 전에 인증과 네트워크 경로를 분리해 확인할 수 있습니다.
3. Git SSH 연결 분리. 원격 주소가 git@host:team/project.git 형식이면 HTTPS 프록시 설정만으로는 충분하지 않을 수 있습니다. SSH는 일반적으로 TCP 22번 연결을 사용하므로 해당 호스트가 규칙상 올바른 프록시 그룹으로 향하는지, 서버가 다른 포트를 제공하는지 확인해야 합니다.
4. 패키지 매니저 확인. npm, pnpm, yarn은 각각 전역 또는 프로젝트 설정을 가질 수 있습니다. TUN이 정상이라면 별도 프록시를 중복 지정하지 않는 구성이 단순합니다. 사내 레지스트리를 사용하는 경우 공개 레지스트리와 같은 규칙으로 처리하지 말고 내부 도메인을 DIRECT 또는 지정된 업무망 경로로 분리합니다.
5. Docker 경로 확인. Docker Desktop은 호스트 프로세스와 별도의 VM 또는 백엔드 네트워크를 사용할 수 있습니다. 셸에서 docker pull이 실패하면 Clash 로그뿐 아니라 Docker Desktop의 프록시 설정, 이미지 레지스트리 주소, 인증 토큰 만료 여부를 함께 확인합니다.

# Git 설정 확인
git config --global --get-regexp 'http\..*proxy|https\..*proxy'

# npm 설정 확인
npm config get proxy
npm config get https-proxy

# 원격 저장소의 연결만 확인
git ls-remote https://example.com/team/project.git

환경 변수에 오래된 프록시 주소가 남아 있는 것도 자주 발생하는 문제입니다. HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY가 Git이나 패키지 매니저의 동작을 바꿀 수 있습니다. TUN을 주 경로로 사용할 때는 예전에 설정한 잘못된 포트의 프록시 변수를 제거하고, 로컬 주소와 사내 도메인은 NO_PROXY에 넣어 불필요한 우회를 막는 것이 좋습니다. 반대로 TUN이 아닌 명시적 프록시 방식이 필요한 환경이라면 Clash의 HTTP 또는 SOCKS 포트와 주소를 정확히 지정해야 하며, 존재하지 않는 포트를 추측해서 입력하면 연결 실패 원인을 찾기 어렵습니다.

IDE와 AI 코딩 도구의 로그인·인증 문제를 줄이는 방법

IDE에서 확장 기능이 설치되지 않거나 AI 코딩 도구의 로그인 화면은 열리는데 인증 완료 후 연결이 끊기는 경우, 브라우저와 IDE가 같은 경로를 사용한다고 가정하면 안 됩니다. 로그인은 브라우저에서 시작되더라도 최종 토큰 교환은 IDE 확장 프로세스나 로컬 에이전트가 수행할 수 있습니다. 이 프로세스가 시스템 프록시를 무시하면 브라우저 인증만 성공하고 IDE 연결은 실패합니다.

먼저 Clash 로그에서 해당 시간대의 도메인 요청을 확인합니다. 요청 자체가 로그에 없다면 TUN이 해당 프로세스의 트래픽을 받지 못했거나, 애플리케이션이 특수한 로컬 IPC·QUIC·직접 소켓 방식을 사용하고 있을 가능성이 있습니다. 로그에 요청이 있지만 timeout, connection reset, tls handshake 같은 오류가 보이면 도메인 규칙, 선택된 프록시 그룹, IPv6 경로, 원격 서비스의 인증 정책을 순서대로 확인합니다.

• IDE 확장 설치 실패: 확장 저장소 도메인이 규칙상 DIRECT로 빠지는지 확인하고, 확장 호스트 프로세스가 별도의 프록시 설정을 갖는지 살펴봅니다.
• 브라우저 로그인 후 IDE가 대기: 리디렉션 주소가 로컬호스트 포트를 사용하는지 확인합니다. 127.0.0.1과 localhost는 외부 프록시가 아니라 로컬 예외로 처리해야 합니다.
• AI 요청만 반복 실패: HTTPS뿐 아니라 WebSocket이나 HTTP/2 연결이 사용될 수 있습니다. 특정 도메인만 임의로 DIRECT 처리하기보다 로그에서 실제 요청 유형과 연결 종료 원인을 확인합니다.
• 인증 토큰 오류: 네트워크 문제처럼 보여도 시스템 시간이 틀렸거나, 회사 보안 소프트웨어가 TLS 연결을 검사하거나, 이전 토큰이 만료된 경우가 있습니다. TUN 설정을 바꾸기 전에 계정 세션과 시스템 시간을 함께 점검합니다.

AI 서비스의 도메인 목록을 무작정 모두 프록시로 보내는 방식은 유지보수가 어렵습니다. 실제 로그에서 확인한 호스트를 규칙에 추가하고, 인증 서버·API 서버·콘텐츠 서버가 서로 다른 도메인을 사용한다면 각각의 요청을 구분해 기록합니다. 서비스 제공자가 정책상 자동화 요청이나 특정 지역의 접속을 제한하는 경우에는 Clash 규칙으로 우회할 수 있는 문제가 아니므로, 정상적인 계정과 지원되는 접속 환경을 사용해야 합니다.

규칙 설계와 장애 발생 시 점검 순서

개발용 프로파일은 목적지에 따라 최소한 공개 코드 호스팅, 패키지 저장소, 컨테이너 레지스트리, 사내 서비스, 로컬 네트워크를 분리하는 것이 좋습니다. 도메인 suffix 규칙을 사용하면 관련 하위 도메인을 함께 처리할 수 있지만, 너무 넓은 키워드 규칙은 사내 서비스나 일반 사이트까지 잘못 잡을 수 있습니다. 구체적인 도메인 규칙을 앞에 두고 넓은 규칙과 MATCH는 뒤에 배치해야 예상하지 못한 우회를 줄일 수 있습니다.

점검 순서는 다음처럼 고정하면 됩니다. 첫째, TUN 스위치와 권한 상태를 확인합니다. 둘째, Clash 로그에서 해당 도메인 요청이 보이는지 확인합니다. 셋째, DNS가 올바른 주소를 반환하는지 확인합니다. 넷째, 요청이 어느 프록시 그룹 또는 DIRECT로 분기되었는지 확인합니다. 다섯째, 문제가 되는 프로그램의 자체 프록시·환경 변수·인증 설정을 확인합니다. 이 순서를 지키면 규칙을 무작정 늘리거나 모든 트래픽을 한 그룹으로 보내는 임시 처방을 피할 수 있습니다.

재현 가능한 개발 환경으로 마무리하기

개인 작업용 프로파일과 회사 네트워크용 프로파일을 분리하면 규칙을 수정할 때 발생하는 부작용을 줄일 수 있습니다. 개인 프로파일에는 공개 저장소와 패키지 레지스트리 규칙을 두고, 업무 프로파일에는 사내 DNS와 내부 도메인, VPN 예외, 로컬 서비스 규칙을 별도로 관리합니다. 프로파일을 바꾼 뒤에는 현재 모드가 Rule인지, 실제로 사용 중인 프록시 그룹이 무엇인지, TUN과 DNS가 함께 활성화되어 있는지를 확인해야 합니다.

설정이 안정화되면 다음 네 가지 테스트를 기록해두는 것이 좋습니다. 공개 Git 저장소의 git ls-remote, 패키지 레지스트리의 메타데이터 조회, Docker의 테스트 이미지 다운로드, IDE 또는 AI 코딩 도구의 로그인과 간단한 요청입니다. 네트워크 환경이나 Clash 코어를 업데이트한 뒤 같은 테스트를 다시 실행하면 변경으로 인해 어느 단계가 영향을 받았는지 비교할 수 있습니다.

TUN은 브라우저 프록시의 대체 스위치가 아니라 운영체제 트래픽을 다루는 라우팅 계층입니다. 따라서 권한, DNS, 규칙, 애플리케이션별 설정을 함께 설계해야 합니다. 기본 구성은 단순하게 유지하고, 연결 실패가 발생한 실제 도메인만 로그로 확인해 규칙과 예외를 추가하는 방식이 가장 관리하기 쉽습니다. 필요한 클라이언트와 설치 파일은 다운로드 페이지에서 확인하고, 플랫폼별 권한과 초기 설정은 사용 안내에서 이어서 점검할 수 있습니다.