고급 설정 예상 읽기 시간 21분

개발자를 위한 Clash 설정법｜TUN으로 Git·npm·AI 코딩 안정화

GitHub clone 오류, npm 패키지 설치 지연, Docker Hub 접속 실패, Cursor와 GitHub Copilot 연결 문제를 겪는 개발자를 위한 Clash 실전 가이드입니다. TUN 모드로 터미널과 IDE 트래픽을 통합하고, Git·SSH·pip·컨테이너 작업에…

브라우저가 되더라도 개발 도구는 별도로 점검해야 합니다

브라우저에서 웹사이트가 정상적으로 열리는 것만으로 Git, npm, Docker, Cursor 또는 GitHub Copilot의 연결까지 정상이라고 판단할 수는 없습니다. 브라우저는 운영체제의 시스템 프록시를 읽거나 프록시 확장 프로그램을 사용할 수 있지만, 명령줄 도구와 개발 애플리케이션은 자체 네트워크 라이브러리, 환경 변수, 인증서 저장소 또는 별도의 프록시 설정을 사용합니다. 따라서 브라우저는 접속되는데 git clone이 멈추거나 npm install에서 레지스트리 연결이 실패하는 상황은 흔히 발생합니다.

개발 환경을 구성할 때는 먼저 어떤 트래픽을 어떤 방식으로 Clash에 전달할지 정해야 합니다. 시스템 프록시는 해당 설정을 따르는 애플리케이션에 편리하지만 모든 TCP·UDP 패킷을 강제로 가로채지는 않습니다. 반면 TUN 모드는 가상 네트워크 인터페이스를 만들고 운영체제의 라우팅 경로에 개입하므로, 프록시 설정을 읽지 않는 앱이나 일부 UDP 기반 연결까지 더 넓게 처리할 수 있습니다. 다만 TUN이 켜졌다고 모든 트래픽이 자동으로 원하는 노드를 통과하는 것은 아니며, 규칙과 DNS 설정이 함께 맞아야 합니다.

방식 주요 적용 범위 개발 환경에서의 역할 주의할 점
시스템 프록시 운영체제 설정을 읽는 앱 브라우저, 일부 GUI 도구 Git과 Docker가 무시할 수 있음
환경 변수 현재 셸과 하위 프로세스 curl, Git, 패키지 관리자 새 터미널에는 다시 설정해야 할 수 있음
앱별 프록시 특정 프로그램 Git, npm, IDE 확장 기능 잘못된 이전 포트가 남을 수 있음
TUN 모드 라우팅되는 더 넓은 네트워크 트래픽 프록시를 모르는 앱, 일부 UDP 연결 권한, DNS, 라우팅 충돌을 확인해야 함

mihomo 기반 Clash에서 TUN 모드 구성하기

Clash Verge Rev, Clash Nyanpasu 등 mihomo 계열 코어를 사용하는 클라이언트에서는 설정 화면에서 TUN 모드를 활성화할 수 있습니다. 메뉴 이름은 버전에 따라 「설정」→「TUN」, 「설정」→「서비스 모드」 또는 「네트워크」와 같이 다르게 표시될 수 있습니다. 핵심은 TUN 기능을 켜는 것뿐 아니라 mihomo 코어가 가상 인터페이스를 만들 권한을 갖는지 확인하는 것입니다. Windows에서는 관리자 권한이나 서비스 모드가 필요할 수 있고, Linux에서는 root 권한 또는 네트워크 관리 권한이 필요합니다.

설정을 직접 관리한다면 다음과 같은 형태를 기본 출발점으로 사용할 수 있습니다. 실제 옵션 지원 여부와 이름은 사용 중인 mihomo 버전에 따라 확인해야 하며, 기존 설정에 이미 dns, tun, listeners 항목이 있다면 중복으로 추가하지 마세요.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

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

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  fake-ip-filter:
    - "*.lan"
    - "*.local"

mixed-port: 7890은 HTTP와 SOCKS5 요청을 받을 수 있는 로컬 진입점입니다. TUN을 사용하더라도 이 포트는 curl이나 앱별 설정을 검증할 때 유용합니다. auto-route는 운영체제 라우팅 테이블에 TUN 경로를 추가하고, auto-detect-interface는 현재 사용하는 물리 네트워크 인터페이스를 감지합니다. 여러 VPN, 가상 머신, Docker 네트워크가 동시에 존재하면 자동 감지가 예상과 다를 수 있으므로 실제 인터페이스와 라우팅 테이블을 확인해야 합니다.

TUN을 켠 뒤 확인할 항목

TUN 문제를 확인할 때는 바로 모든 규칙을 복잡하게 만들지 않는 것이 좋습니다. 먼저 일반적인 외부 도메인 하나와 GitHub 도메인 하나를 대상으로 연결 상태를 비교하세요. Clash의 연결 목록에서 프로세스 이름, 목적지 도메인, 적용된 규칙, 선택된 정책 그룹, 실제 노드를 확인하면 트래픽이 TUN을 통과했는지 추정할 수 있습니다. 연결 목록에 요청이 전혀 나타나지 않는다면 TUN 라우팅 또는 앱이 별도 네트워크 네임스페이스를 사용하는지부터 확인해야 합니다.

Git과 GitHub 연결을 안정적으로 설정하기

Git은 시스템 프록시를 항상 자동으로 따르는 프로그램이 아닙니다. 가장 재현하기 쉬운 방법은 먼저 Clash의 혼합 포트에 직접 연결해 GitHub HTTPS 요청을 확인하는 것입니다. 아래 명령의 포트는 실제 Clash 화면에 표시된 값으로 바꾸세요.

curl -I -x http://127.0.0.1:7890 https://github.com
curl -I --proxy socks5h://127.0.0.1:7890 https://github.com

두 요청 중 하나가 정상적인 HTTP 응답을 반환하면 로컬 포트와 기본 프록시 경로는 작동하는 것입니다. 그다음 Git에 프록시를 지정할 수 있습니다. HTTP 프록시를 사용할 때는 http.proxy에 주소를 넣고, SOCKS5를 사용할 때는 도메인 DNS 해석까지 프록시 측에서 처리하도록 socks5h를 사용하는 편이 문제 분리에 유리합니다.

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

# SOCKS5를 사용할 경우
git config --global --unset http.proxy
git config --global --unset https.proxy
git config --global http.proxy socks5h://127.0.0.1:7890
git config --global https.proxy socks5h://127.0.0.1:7890

git config --global --get-regexp 'http\..*proxy|https\..*proxy'

설정 후 다음처럼 실제 Git 작업을 수행합니다.

git ls-remote https://github.com/example/project.git
git clone https://github.com/example/project.git

GitHub HTTPS 작업은 성공하지만 SSH 주소인 [email protected]:example/project.git가 실패한다면 이는 Git의 HTTP 프록시 설정으로 해결되지 않을 수 있습니다. SSH는 별도의 TCP 연결과 포트를 사용하기 때문입니다. 개발 환경에서는 우선 HTTPS 원격 저장소를 사용해 경로를 단순화하고, SSH가 반드시 필요하다면 SSH 클라이언트의 별도 프록시 방식이나 TUN 규칙을 검토해야 합니다. 단순히 Git의 https.proxy를 설정하고 SSH도 같은 방식으로 연결될 것이라고 기대해서는 안 됩니다.

자주 보이는 Git 오류 구분하기

작업이 끝난 뒤 다른 네트워크에서 프록시 없이 Git을 사용해야 한다면 전역 설정이 남아 있는지 확인하세요. 필요할 때는 git config --global --unset http.proxy와 git config --global --unset https.proxy로 제거할 수 있습니다. 전역 프록시와 TUN을 동시에 사용할 경우 연결이 두 번 프록시화되거나, 특정 저장소의 설정이 전역 설정을 덮어쓸 수 있으므로 git config --show-origin --get-regexp 'proxy'로 출처까지 확인하는 것이 좋습니다.

npm과 Docker의 서로 다른 프록시 경로 다루기

npm은 레지스트리 주소와 프록시 설정을 별도로 가질 수 있습니다. TUN이 정상이라면 npm도 라우팅을 통해 연결될 수 있지만, 조직 환경이나 특정 Node.js 버전에서는 명시적인 설정이 문제를 재현하는 데 도움이 됩니다. 먼저 현재 레지스트리와 프록시 설정을 확인하세요.

npm config get registry
npm config get proxy
npm config get https-proxy
npm ping --registry=https://registry.npmjs.org/

공개 npm 레지스트리를 사용할 때 HTTP 프록시를 지정하는 예시는 다음과 같습니다. 사설 레지스트리를 사용하는 프로젝트라면 프로젝트의 .npmrc와 조직 정책을 우선해야 하며, 토큰이 포함된 설정 파일을 명령줄 출력이나 로그에 노출하지 마세요.

npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
npm config set registry https://registry.npmjs.org/

npm view typescript version
npm install

npm install은 레지스트리 접속 외에도 패키지의 tarball URL, Git 저장소, 선택적 의존성의 플랫폼별 다운로드 주소에 연결할 수 있습니다. 따라서 npm ping은 성공했는데 설치가 실패한다면 실패한 URL과 패키지 이름을 확인해야 합니다. 한 번의 성공적인 ping이 모든 의존성 서버에 대한 접근을 보장하지는 않습니다. 캐시 오류처럼 보이는 경우에는 먼저 네트워크를 확인하고, 무조건 캐시를 삭제하기보다 npm cache verify로 상태를 확인하세요.

Docker는 클라이언트와 데몬을 구분해야 합니다. 호스트의 셸에서 HTTP_PROXY를 설정해도 Docker 데몬이 이미지를 가져오는 경로에는 자동으로 적용되지 않을 수 있습니다. Docker Desktop은 자체 가상 머신과 네트워크 계층을 사용할 수 있으므로, 호스트의 127.0.0.1은 컨테이너나 데몬 내부에서 같은 호스트를 의미하지 않습니다.

docker info
docker pull node:22-alpine
docker run --rm node:22-alpine node --version

이미지 pull이 실패하면 Docker Desktop의 프록시 설정, 데몬 설정, 방화벽과 레지스트리 주소를 별도로 확인하세요. 컨테이너 내부에서 호스트의 Clash 포트에 접근해야 하는 경우에는 환경에 따라 host.docker.internal을 사용할 수 있지만, Clash가 127.0.0.1에만 바인딩되어 있으면 컨테이너에서 접근할 수 없습니다. 이때 무작정 allow-lan: true를 켜기보다 필요한 인터페이스에만 바인딩하고 방화벽으로 접근 범위를 제한해야 합니다.

Cursor와 Copilot은 애플리케이션 전체 경로로 확인하기

Cursor와 GitHub Copilot은 에디터 화면에서 동작하지만 실제 연결은 확장 프로세스, 로그인 창, 업데이트 모듈, 인증 서비스, 모델 API 등 여러 목적지로 나뉠 수 있습니다. 브라우저에서 GitHub에 로그인할 수 있어도 에디터 내부의 인증 토큰 갱신이나 모델 요청이 실패할 수 있습니다. 특히 회사 보안 솔루션이 TLS를 검사하거나, 시스템 프록시와 에디터의 내장 프록시 설정이 서로 다른 경우에 이런 차이가 발생합니다.

먼저 TUN을 켠 상태에서 에디터를 완전히 종료한 뒤 다시 실행하세요. 창만 닫고 백그라운드 프로세스가 남아 있으면 이전 DNS 결과나 프록시 환경을 계속 사용할 수 있습니다. Clash의 연결 목록에서 에디터 본체와 확장 호스트 프로세스가 실제로 표시되는지 확인하고, 다음 항목을 기록합니다.

에디터에 HTTP 프록시 설정이 있다면 Clash의 실제 혼합 포트와 일치하는지 확인합니다. 반대로 TUN을 주 경로로 사용할 때는 여러 계층에 서로 다른 프록시를 동시에 입력하지 않는 편이 안전합니다. 프록시를 끈 상태에서도 TUN을 통해 연결되는지 확인한 뒤, 앱별 프록시가 필요한 경우에만 추가하세요. 환경 변수로 실행된 에디터와 GUI에서 직접 실행된 에디터는 상속받는 설정이 다를 수 있으므로, 터미널에서 실행한 결과와 메뉴 아이콘으로 실행한 결과를 구분해야 합니다.

재현 가능한 최종 점검 순서

개발 환경에서 안정성을 확인할 때는 “웹페이지가 열린다”보다 실제 작업을 짧은 단계로 나누어 검증하는 것이 정확합니다. 각 단계에서 노드나 모드를 동시에 바꾸지 말고, 성공한 상태의 포트와 정책을 기록해 두세요.

  1. Clash 코어가 실행 중인지 확인하고 현재 mixed-port, 모드, 선택된 정책 그룹을 기록합니다.
  2. curl -I -x http://127.0.0.1:7890 https://github.com으로 로컬 프록시 포트와 HTTPS 터널을 테스트합니다.
  3. TUN을 활성화하고 가상 어댑터, 자동 라우팅, DNS 로그에 오류가 없는지 확인합니다.
  4. git ls-remote로 저장소 메타데이터를 조회한 뒤 실제 clone 또는 fetch를 실행합니다.
  5. npm ping, npm view, 작은 패키지 설치 순서로 레지스트리와 tarball 다운로드를 분리합니다.
  6. Docker에서 이미지 조회와 컨테이너 내부 DNS를 별도로 테스트하고, 데몬 프록시 설정을 확인합니다.
  7. Cursor와 Copilot을 재시작한 뒤 에디터 로그와 Clash 연결 목록의 목적지를 대조합니다.

문제가 해결된 뒤에는 사용하지 않는 전역 프록시 설정을 정리하고, 민감한 토큰이 포함된 npm 설정이나 셸 기록을 점검하세요. TUN은 편리하지만 네트워크 범위를 넓게 바꾸는 기능이므로 공용 Wi-Fi, 회사 네트워크, 다른 VPN과 함께 사용할 때는 특히 주의해야 합니다. 개발용 정책 그룹과 일반 브라우징 정책 그룹을 분리하면 GitHub와 레지스트리 테스트 중 노드가 자동으로 바뀌는 일을 줄일 수 있습니다. 최종 목표는 무조건 모든 트래픽을 프록시로 보내는 것이 아니라, 필요한 개발 도구가 예상한 규칙과 노드를 통해 안정적으로 연결되도록 경로를 명확하게 만드는 것입니다.

Clash 클라이언트 다운로드 운영체제에 맞는 설치 파일 선택