서론: 개발 환경에서 프록시가 필요한 이유
개발자는 브라우저만 사용하는 것이 아니라 터미널, Git, SSH, 패키지 관리자, 컨테이너 도구와 원격 저장소를 매일 함께 사용합니다. 따라서 브라우저에서 웹사이트가 정상적으로 열리더라도 git clone이 실패하거나, ssh 연결이 멈추거나, brew update가 오랫동안 응답하지 않는 상황이 발생할 수 있습니다. 이런 문제는 단순한 인터넷 속도 저하가 아니라 DNS 조회, TLS 연결, 특정 해외 도메인으로의 라우팅, 방화벽 정책이 서로 얽혀 나타나는 경우가 많습니다.
Clash를 개발 도구와 연결하면 애플리케이션별로 프록시 경로를 나누고, 국내 저장소나 사내 서버는 DIRECT로 유지하면서 GitHub, Docker Hub, Homebrew 저장소처럼 외부 연결이 필요한 대상만 안정적인 노드로 보낼 수 있습니다. 모든 트래픽을 무조건 우회하는 방식보다 필요한 요청만 분기하므로 속도와 호환성을 함께 관리하기 쉽습니다.
이 글의 목표
Clash의 로컬 포트와 환경 변수를 활용해 Git, SSH, Homebrew, Docker 작업을 연결하고, 문제가 생겼을 때 원인을 단계적으로 확인하는 방법을 안내합니다.
이 글은 Clash Verge, Clash Verge Rev, Mihomo 기반 클라이언트처럼 HTTP 및 SOCKS5 로컬 프록시를 제공하는 환경을 기준으로 설명합니다. 메뉴 이름은 클라이언트에 따라 조금 다를 수 있지만, 원리는 대부분 동일합니다.
1Clash 로컬 프록시와 환경 변수 이해하기
Clash를 실행하면 일반적으로 로컬 컴퓨터에 두 종류의 프록시 포트가 열립니다. HTTP 프록시는 웹 요청과 많은 CLI 도구에서 사용하기 쉽고, SOCKS5 프록시는 TCP 기반 애플리케이션을 폭넓게 전달할 수 있습니다. 예를 들어 로컬 HTTP 포트가 7890, SOCKS5 포트가 7891이라면 실제 포트 번호는 사용 중인 프로필과 클라이언트 설정 화면에서 확인해야 합니다.
- HTTP 프록시:
curl, 일부 Git 전송, Homebrew 다운로드처럼 HTTP 또는 HTTPS 요청을 처리하는 도구에 적합합니다. - SOCKS5 프록시: 다양한 TCP 연결을 전달할 수 있어 SSH의 보조 경로, 개발 서버 접속, 프록시 인식이 가능한 도구에 유용합니다.
- 시스템 프록시: GUI 프로그램과 브라우저에는 편리하지만 모든 터미널 프로세스가 자동으로 따르는 것은 아닙니다.
- TUN 모드: 환경 변수를 지원하지 않는 애플리케이션까지 시스템 수준에서 처리할 수 있지만, 사내망과 로컬 장치 접근에 예외 규칙이 필요합니다.
터미널 도구는 보통 HTTP_PROXY, HTTPS_PROXY, ALL_PROXY 같은 환경 변수를 읽습니다. 다만 모든 프로그램이 동일하게 동작하지는 않습니다. 변수 이름의 대소문자를 구분하거나, 이미 저장된 Git 전역 설정을 우선 적용하는 프로그램도 있으므로 설정 후 반드시 실제 요청으로 확인해야 합니다.
아래 포트는 예시입니다. Clash의 현재 HTTP 또는 SOCKS5 포트에 맞게 바꾸세요.
비밀번호가 포함된 프록시 주소는 셸 기록이나 프로세스 목록에 남을 수 있으므로 공유 컴퓨터에서는 사용에 주의하세요.
일시적으로만 사용하려면 위 변수를 셸에 직접 입력하고, 자주 사용한다면 macOS·Linux의 ~/.zshrc 또는 ~/.bashrc에 추가할 수 있습니다. Windows PowerShell에서는 $env:HTTPS_PROXY 형식을 사용합니다. 회사 네트워크와 개인 네트워크를 번갈아 사용한다면 영구 등록보다 별도의 셸 함수나 스크립트로 켜고 끄는 편이 안전합니다.
2GitHub와 Git 저장소 프록시 설정
Git은 저장소 주소에 따라 연결 방식이 달라집니다. https://github.com/... 주소는 HTTPS 프록시 설정을 적용하기 쉽지만, [email protected]:... 형식은 SSH 프로토콜을 사용하므로 HTTP 프록시 변수만으로는 해결되지 않습니다. 먼저 자신이 사용하는 원격 주소를 확인하세요.
HTTPS 저장소를 주로 사용한다면 Git 전역 설정에 Clash HTTP 포트를 등록할 수 있습니다. 이 설정은 현재 사용자 계정의 모든 저장소에 적용되므로, 사내 Git 서버나 로컬 GitLab까지 같은 프록시로 보내도 되는지 먼저 확인해야 합니다.
특정 저장소만 프록시를 사용하려면 전역 설정 대신 해당 저장소 디렉터리에서 --local 옵션을 사용하세요. 반대로 인증서 오류나 연결 실패가 프록시를 거친 뒤에만 발생한다면 설정을 제거하고 원인을 비교하는 것이 좋습니다.
git remote -v로 원격 저장소가 HTTPS인지 SSH인지 확인합니다.- Clash의 연결 로그에서
github.com요청이 표시되는지 확인합니다. - 노드 그룹을 바꾼 뒤
git ls-remote origin으로 인증 전 저장소 조회를 테스트합니다. - 성공하면 작은 브랜치나 테스트 저장소에서
git fetch와git push를 차례로 확인합니다.
프록시 설정을 해제해야 할 때는 다음 명령을 사용합니다. 문제를 해결한 뒤에도 불필요한 전역 프록시가 남아 있으면 다른 저장소의 연결을 방해할 수 있으므로 작업 환경에 맞게 정리하세요.
3SSH push를 안정화하는 방법
SSH 방식의 Git은 일반적인 HTTP 프록시 변수만으로 연결되지 않습니다. 기본적으로 원격 서버의 22번 포트에 직접 TCP 연결을 시도하기 때문입니다. 이 포트가 네트워크에서 제한되어 있거나 경로가 불안정하다면 SSH 연결이 멈추고, Connection timed out 또는 kex_exchange_identification 같은 오류가 나타날 수 있습니다.
가장 간단한 방법은 GitHub가 제공하는 SSH over HTTPS 포트를 사용하는 것입니다. 다만 모든 Git 서버가 같은 포트를 제공하는 것은 아니며, 서버 운영 정책에 따라 기본 SSH 포트만 허용될 수도 있습니다. 따라서 아래 설정을 적용하기 전에 해당 서비스의 공식 SSH 포트 지원 여부를 확인하세요.
~/.ssh/config에 호스트별 설정을 추가하면 GitHub 연결만 별도로 관리할 수 있습니다.
이 방식은 SSH를 HTTPS 프록시로 바꾸는 것이 아니라, SSH 서버가 제공하는 대체 포트로 연결하는 방식입니다. Clash가 시스템 트래픽 또는 해당 연결을 처리할 수 있도록 TUN 모드를 사용하거나, 네트워크 환경에 맞는 라우팅 규칙을 선택하세요.
연결 상태는 다음 명령으로 확인할 수 있습니다. 출력에 실제로 어떤 주소와 포트로 연결하는지 나타나므로, 오류 메시지를 추측하기보다 로그를 먼저 확인하는 습관이 중요합니다.
보안 주의
SSH 키의 개인 키 파일을 프록시 설정이나 저장소에 넣지 마세요. 개인 키는 로컬에 보관하고 권한을 macOS·Linux에서 chmod 600 ~/.ssh/id_ed25519로 제한하는 것이 좋습니다.
SOCKS5 프록시를 SSH에 직접 연결해야 하는 환경에서는 OpenSSH의 ProxyCommand와 nc 또는 connect-proxy 같은 보조 도구를 사용할 수 있습니다. 그러나 도구별 옵션과 설치 상태가 달라 오류가 복잡해질 수 있으므로, 먼저 대체 포트 방식과 Clash TUN 모드를 시도하는 것이 관리하기 쉽습니다.
4실전 적용: Homebrew와 Docker 테스트
이제 Clash를 켠 상태에서 개발 도구를 순서대로 점검해 보겠습니다. 이 과정은 글 중간에서 바로 따라 할 수 있는 최소 작업 흐름입니다. 한 번에 여러 설정을 바꾸지 말고, 각 단계가 성공했는지 확인한 뒤 다음 단계로 넘어가야 어느 설정이 효과를 냈는지 알 수 있습니다.
- Clash에서 현재 노드의 지연 시간과 연결 상태를 확인하고, 지나치게 혼잡한 노드는 피합니다.
- 터미널에서
curl -I https://github.com을 실행해 HTTPS 요청이 응답하는지 확인합니다. - Git 저장소에서
git ls-remote origin을 실행하고, Clash 로그에 GitHub 요청이 기록되는지 확인합니다. - SSH 저장소라면
ssh -vT [email protected]또는 대체 포트 설정으로 인증 단계까지 도달하는지 확인합니다. - 마지막으로 패키지 관리자와 컨테이너 레지스트리를 테스트합니다.
Homebrew는 Git 저장소와 바이너리 다운로드를 모두 사용할 수 있으므로 HTTPS 환경 변수를 먼저 적용하는 편이 간단합니다.
HOMEBREW_NO_AUTO_UPDATE는 명령마다 자동 업데이트가 실행되는 것을 잠시 막는 옵션입니다. 영구적인 해결책은 아니지만, 네트워크 문제와 패키지 작업을 분리해 확인할 때 유용합니다. 실제 사용하는 저장소와 미러 주소는 지역 및 운영 정책에 따라 달라질 수 있으므로 신뢰할 수 있는 공식 안내를 우선하세요.
Docker CLI가 프록시를 인식하지 못한다면 셸 변수만으로는 부족할 수 있습니다. Docker Desktop의 프록시 설정이나 Linux Docker 데몬의 systemd 환경 설정을 별도로 확인해야 합니다.
이미지 다운로드가 실패하면 Docker Desktop 프록시 설정, 인증서, 레지스트리 주소, Clash 로그를 차례로 확인하세요. 로컬 레지스트리와 사내 레지스트리는 DIRECT로 예외 처리해야 내부 개발 흐름이 느려지거나 인증이 실패하는 것을 줄일 수 있습니다.
성공 기준
Git 조회, SSH 인증, Homebrew 메타데이터 갱신, Docker 테스트 이미지 다운로드가 모두 완료되고 Clash 로그에 의도한 노드와 규칙이 표시되면 기본 연결 구성이 정상입니다.
5문제 해결과 운영 시 주의사항
개발 도구의 연결 문제는 프록시 포트, 규칙, DNS, 인증이라는 네 가지 층으로 나누어 확인하면 빠르게 좁힐 수 있습니다. 먼저 Clash가 실행 중인지, 로컬 포트가 실제로 열려 있는지 확인하세요. 포트가 다르면 환경 변수를 아무리 정확히 입력해도 연결되지 않습니다.
- 연결 거부:
127.0.0.1:7890포트가 현재 Clash 포트와 일치하는지 확인합니다. - DNS 오류: 도메인은 해석되지만 연결이 실패한다면 Clash DNS 모드와 시스템 DNS 설정을 함께 점검합니다.
- Git만 실패:
git config --show-origin --get-regexp 'http.*proxy'로 숨겨진 전역 또는 저장소별 설정을 찾습니다. - SSH만 실패: 원격 주소, SSH 포트, 키 권한,
~/.ssh/config의 호스트명이 일치하는지 확인합니다. - Docker만 실패: CLI가 아니라 Docker 데몬 또는 Desktop이 별도의 네트워크 환경에서 실행되는지 확인합니다.
- 사내 서비스 실패: 사내 도메인, 사설 IP 대역, 로컬호스트를 프록시에서 제외하고
DIRECT규칙을 우선 적용합니다.
규칙 순서도 매우 중요합니다. 넓은 GEOIP 또는 기본 프록시 규칙이 GitHub·사내 Git 서버 전용 규칙보다 위에 있으면 원하는 분기가 실행되지 않을 수 있습니다. 구체적인 DOMAIN-SUFFIX 규칙을 위에 배치하고, 마지막에 기본 규칙을 두는 방식이 일반적으로 관리하기 쉽습니다.
마지막으로 프록시를 켠 상태에서 무조건 가장 빠른 노드가 좋은 것은 아닙니다. Git push는 안정적인 TCP 연결과 인증 성공이 중요하고, Docker 이미지는 지속적인 다운로드 속도와 재시도 안정성이 중요합니다. 여러 노드를 번갈아 사용하기보다 개발 업무용 그룹을 정해 지연 시간, 패킷 손실, 연결 지속성을 기준으로 주기적으로 점검하세요.
Clash는 개발자의 네트워크 문제를 자동으로 모두 해결하는 도구가 아니라, 트래픽 경로를 관찰하고 통제하게 해 주는 도구입니다. 포트와 환경 변수를 명확히 관리하고, HTTPS·SSH·TUN 방식을 목적에 맞게 선택하면 저장소 동기화와 패키지 업데이트의 예측 가능성을 크게 높일 수 있습니다.