개발자를 위한 Clash 프록시 설정: Git·SSH·Homebrew 연결 최적화

개발 환경에서 Clash를 사용하는 이유

개발 작업에서 프록시는 브라우저만을 위한 기능이 아닙니다. Git 저장소를 복제하거나 원격 브랜치를 가져올 때, Homebrew로 패키지를 설치할 때, npm과 pip가 외부 레지스트리에 접속할 때도 각각 네트워크 연결이 발생합니다. 브라우저에서 웹페이지가 정상적으로 열리더라도 터미널 프로그램은 시스템 프록시를 무시하거나 별도의 환경 변수를 사용하기 때문에 git clone, brew install, npm install 중 하나만 실패하는 상황이 자주 발생합니다.

이 문제를 안정적으로 해결하려면 먼저 Clash의 포트와 프록시 유형을 확인해야 합니다. Clash Verge Rev나 Mihomo 기반 클라이언트의 일반적인 로컬 포트는 HTTP와 SOCKS5를 함께 제공하며, 예시는 HTTP 7890, SOCKS5 7891입니다. 하지만 설치 환경이나 사용 중인 프로필에 따라 포트가 달라질 수 있으므로 클라이언트의 설정 화면 또는 YAML의 mixed-port, port, socks-port 값을 먼저 확인하세요.

• HTTP 프록시: Git의 HTTPS 원격 주소, Homebrew, npm, pip처럼 HTTP CONNECT를 지원하는 도구에 적합합니다.
• SOCKS5 프록시: SSH 또는 특정 개발 도구처럼 SOCKS5를 직접 지정할 수 있는 프로그램에 적합합니다.
• TUN 모드: 환경 변수를 지원하지 않는 프로그램까지 가상 네트워크 인터페이스를 통해 처리하는 방식입니다.
• 분할 라우팅: 코드 호스팅과 패키지 저장소만 프록시로 보내고 사내망, 로컬 장비, 국내 서비스는 직결로 남기는 방식입니다.

터미널 공통 설정: HTTP와 SOCKS5 환경 변수

가장 빠른 방법은 현재 셸에 프록시 환경 변수를 적용하는 것입니다. macOS와 Linux의 zsh 또는 bash에서는 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY를 사용할 수 있습니다. HTTPS 사이트에 접속하더라도 프록시 주소 자체는 보통 http://로 작성합니다. 이는 목적지 연결을 HTTP CONNECT 방식으로 터널링한다는 의미이며, 프록시 서버가 TLS를 해제한다는 뜻이 아닙니다.

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7891
export NO_PROXY=localhost,127.0.0.1,::1,.local,192.168.0.0/16,10.0.0.0/8

Windows PowerShell에서는 현재 터미널에만 적용되는 $env: 형식을 사용합니다. 영구 설정을 원하면 시스템 환경 변수에 등록할 수 있지만, 회사 네트워크나 다른 장소에서 노트북을 사용할 때 프록시 주소가 남아 문제를 만들 수 있으므로 먼저 일회성 설정으로 테스트하는 편이 안전합니다.

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5://127.0.0.1:7891"
$env:NO_PROXY="localhost,127.0.0.1,::1,.local,192.168.0.0/16,10.0.0.0/8"

연결 테스트는 인증이 필요하지 않은 일반 도메인과 실제 개발 대상 도메인을 나누어 실행하세요. curl -I가 성공하면 프록시 포트와 기본 HTTP 경로가 동작한다는 뜻입니다. 이후 Git이나 패키지 관리자의 테스트 명령을 별도로 실행해야 해당 프로그램이 환경 변수를 읽는지도 확인할 수 있습니다.

curl -I https://example.com
curl -I https://registry.npmjs.org
python -m pip --version

Git 연결 최적화: HTTPS와 SSH를 구분하기

Git 원격 저장소는 크게 HTTPS 주소와 SSH 주소로 나뉩니다. 예를 들어 https://code.example.test/team/app.git는 일반적으로 Git의 HTTP 프록시 설정을 사용하고, [email protected]:team/app.git는 SSH 프로토콜을 사용합니다. 두 주소는 같은 저장소를 가리킬 수 있지만 프록시 설정 위치가 다르므로 HTTPS만 설정한 뒤 SSH도 자동으로 프록시를 사용할 것이라고 기대하면 안 됩니다.

HTTPS 원격 저장소 설정

HTTPS 방식은 Git 전역 설정에 HTTP 프록시를 지정하는 것이 가장 명확합니다. 다음 명령은 모든 저장소에 적용됩니다. 특정 저장소에만 적용하려면 해당 저장소 디렉터리에서 --local 옵션을 사용하세요.

git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
git config --global --get-regexp 'http\..*proxy|https\..*proxy'

git ls-remote https://code.example.test/team/app.git

직결이 더 빠른 사내 Git 서버가 있다면 호스트별 예외를 둘 수 있습니다. 환경 변수의 NO_PROXY만으로 충분하지 않은 Git 버전이나 실행 환경에서는 Git 설정에서 해당 주소를 비워 주는 방식이 편리합니다.

git config --global http.https://code.example.test.proxy http://127.0.0.1:7890
git config --global http.https://git.intra.example.test.proxy ""
git config --global https.https://git.intra.example.test.proxy ""

SSH 원격 저장소 설정

SSH는 기본적으로 TCP 22번 포트에 직접 연결하므로 HTTP 프록시 설정만으로는 동작하지 않습니다. Mihomo의 로컬 SOCKS5 포트와 OpenSSH의 ProxyCommand를 연결하면 SSH도 Clash를 통과시킬 수 있습니다. macOS와 Linux에는 보통 nc가 포함되어 있지만, SOCKS5를 지원하지 않는 구현도 있으므로 connect 또는 ncat의 지원 여부를 확인하세요.

# ~/.ssh/config
Host code.example.test
  HostName code.example.test
  User git
  Port 22
  IdentityFile ~/.ssh/id_ed25519
  ProxyCommand nc -x 127.0.0.1:7891 -X 5 %h %p

Windows에서는 OpenSSH와 함께 제공되는 ssh가 SOCKS5 옵션을 지원하지 않을 수 있습니다. 이때는 Clash의 HTTP 포트에 맞는 별도 CONNECT 도구를 사용하거나, SSH 서비스가 제공하는 대체 포트가 있는지 확인하세요. SSH 설정을 바꾼 뒤에는 저장소 전체를 내려받기보다 먼저 상세 로그로 핸드셰이크를 확인하는 것이 좋습니다.

ssh -Tv [email protected]
git ls-remote [email protected]:team/app.git

SSH 키 인증 실패와 프록시 연결 실패는 로그가 다르게 나타납니다. Connection refused나 SOCKS5 연결 오류가 먼저 보이면 로컬 포트 또는 ProxyCommand 문제이고, 서버까지 도달한 뒤 Permission denied (publickey)가 나오면 네트워크는 통과했지만 키 등록이나 IdentityFile이 잘못된 것입니다.

Homebrew·npm·pip에 프록시 적용하기

패키지 관리자는 여러 주소에 접속합니다. 메인 저장소뿐 아니라 메타데이터 서버, 압축 파일 저장소, 의존성의 추가 URL에도 연결할 수 있으므로 한 주소만 브라우저에서 열리는지 확인해서는 충분하지 않습니다. 먼저 환경 변수로 한 번 테스트하고, 반복적으로 사용할 때만 각 도구의 설정 파일에 저장하세요.

Homebrew

Homebrew는 macOS와 Linux에서 Git, curl, Ruby, 시스템 환경 변수의 영향을 함께 받을 수 있습니다. 다음처럼 프록시를 지정한 뒤 저장소 정보 갱신과 실제 패키지 검색을 각각 실행합니다. Homebrew가 사용하는 Git 저장소와 바이너리 병의 다운로드 경로가 서로 다를 수 있으므로 둘 다 확인해야 합니다.

export ALL_PROXY=socks5://127.0.0.1:7891
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

brew update
brew info wget

설정이 꼬였을 때는 기존 셸 변수를 잠시 제거하고 직접 연결 테스트를 해보세요. 사내 미러를 사용하는 환경이라면 해당 미러 도메인을 NO_PROXY에 넣어 불필요하게 외부 노드로 보내지 않는 것이 좋습니다.

npm과 pip

npm은 자체적으로 HTTP와 HTTPS 프록시 항목을 제공합니다. 전역으로 등록하면 모든 프로젝트에 영향을 주므로, 회사 프로젝트와 개인 프로젝트의 레지스트리가 다를 때는 프로젝트별 .npmrc를 우선 고려하세요.

npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
npm config get proxy
npm ping --registry=https://registry.example.test

npm 설정에 프록시 인증 비밀번호를 평문으로 넣는 방식은 피하세요. 설정 파일이 백업되거나 팀 환경으로 복사될 수 있기 때문입니다. 더 이상 사용하지 않을 때는 다음 명령으로 삭제할 수 있습니다.

npm config delete proxy
npm config delete https-proxy

pip는 환경 변수 또는 pip 설정 파일을 사용할 수 있습니다. 테스트 시에는 명령 한 번에만 --proxy를 붙이는 방법이 가장 안전합니다. SOCKS5를 사용하려면 Python 환경에 관련 지원 패키지가 필요할 수 있으므로, 우선 HTTP 포트로 연결을 확인하세요.

python -m pip install --proxy http://127.0.0.1:7890 requests
python -m pip config set global.proxy http://127.0.0.1:7890
python -m pip config get global.proxy

TUN 모드와 개발 트래픽 분할 라우팅

환경 변수를 설정하지 않는 IDE 플러그인, GUI 기반 개발 도구, 자체 런타임을 사용하는 빌드 프로그램까지 처리하려면 TUN 모드가 편리합니다. TUN은 가상 네트워크 인터페이스를 만들고 운영체제의 IP 트래픽을 Clash로 넘깁니다. Mihomo에서는 일반적으로 auto-route: true, auto-detect-interface: true, dns-hijack을 함께 사용하며, 클라이언트에서 관리자 권한이나 VPN 구성 허용을 요구할 수 있습니다.

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

다만 TUN을 켜면 모든 트래픽이 자동으로 원하는 노드로 가는 것은 아닙니다. 최종 방향은 rules의 순서와 정책 그룹이 결정합니다. 개발 환경에서는 로컬 네트워크와 사내 도메인을 먼저 직결하고, 코드 호스팅 및 패키지 저장소를 프록시로 보낸 뒤 마지막에 기본 규칙을 배치하는 구조가 관리하기 쉽습니다.

rules:
  - DOMAIN-SUFFIX,localhost,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - DOMAIN-SUFFIX,git.intra.example.test,DIRECT
  - DOMAIN-SUFFIX,code.example.test,Developer-Proxy
  - DOMAIN-SUFFIX,registry.example.test,Developer-Proxy
  - DOMAIN-SUFFIX,pypi.example.test,Developer-Proxy
  - MATCH,Developer-Proxy

실제 공개 서비스는 여러 하위 도메인과 CDN을 사용할 수 있으므로 단순히 메인 도메인 하나만 추가하면 다운로드가 직결로 빠질 수 있습니다. 먼저 Clash 로그에서 Git, npm, pip, Homebrew 실행 중 나타나는 실제 도메인을 확인하고, 필요한 범위만 DOMAIN-SUFFIX로 추가하세요. 지나치게 넓은 DOMAIN-KEYWORD는 사내 서비스나 국내 사이트를 잘못 프록시로 보내는 원인이 될 수 있습니다.

실패할 때의 진단 순서

개발 도구의 오류 메시지는 “네트워크 오류”라는 한 문장으로 뭉뚱그려지는 경우가 많습니다. 노드부터 바꾸기보다 로컬 포트, DNS, 규칙, 애플리케이션 설정 순서로 좁혀 가면 불필요한 변경을 줄일 수 있습니다.

1. Clash 상태 확인—현재 프로필이 적용되어 있고 선택된 정책 그룹에 실제 노드가 있는지 확인합니다. 노드 지연 시간이 모두 실패하면 Git 설정을 바꿔도 해결되지 않습니다.
2. 포트 확인—curl -x http://127.0.0.1:7890 -I https://example.com으로 HTTP 포트를 테스트하고, SSH는 ssh -Tv 로그에서 ProxyCommand가 실행되는지 확인합니다.
3. DNS 확인—TUN과 DNS 모듈을 함께 사용하는 경우 도메인이 올바르게 해석되는지 확인합니다. fake-ip 주소가 반환되더라도 애플리케이션이 IP 직접 연결을 강제하면 도메인 규칙이 예상과 다르게 적용될 수 있습니다.
4. 규칙 로그 확인—개발 도메인이 DIRECT로 매칭되는지, 사내 도메인이 엉뚱한 프록시 그룹으로 가는지 확인합니다. Clash의 연결 목록에서 목적지와策略 그룹을 함께 보세요.
5. 도구별 설정 제거—환경 변수, Git 전역 설정, npm 설정이 서로 다른 포트를 가리키면 결과가 혼란스러워집니다. 테스트가 끝난 뒤 중복된 설정을 정리하고 한 가지 관리 방식을 선택하세요.

• Git의 407 오류: HTTP 프록시 인증이 필요한데 인증 정보가 없거나 잘못된 경우입니다. 로컬 Clash 포트에 별도 인증이 설정되어 있는지도 확인하세요.
• SSH의 timeout: TCP 22번이 차단되었거나 ProxyCommand가 실행되지 않은 경우입니다. SOCKS5 포트와 호스트명을 먼저 점검하세요.
• npm의 ETIMEDOUT: 레지스트리 주소가 프록시 정책에 매칭되지 않았거나 프록시 포트가 응답하지 않는 경우가 많습니다.
• pip의 CERTIFICATE_VERIFY_FAILED: 프록시를 거친다는 이유로 인증서 검증을 끄지 마세요. 시스템 시간, CA 인증서, 사내 TLS 검사 정책을 먼저 확인해야 합니다.
• Homebrew의 fetch 실패: 저장소는 Git으로 연결되지만 병 파일 CDN은 다른 도메인을 사용할 수 있습니다. 실패한 URL을 로그에서 찾아 별도 규칙을 추가하세요.

자주 묻는 질문