개발자를 위한 Clash 설정: Git·SSH·Homebrew 프록시 활용법

개발 트래픽을 먼저 구분하기

GitHub 저장소를 여는 속도가 느리거나 git clone이 중단될 때는 브라우저 프록시만 확인해서는 충분하지 않습니다. 개발 도구마다 프록시를 읽는 방식이 다르기 때문입니다. 브라우저는 운영체제 시스템 프록시를 따르는 경우가 많지만, Git은 자체 설정을 우선할 수 있고, SSH는 HTTP 프록시 환경 변수를 자동으로 사용하지 않습니다. Homebrew와 npm은 환경 변수 또는 각자의 설정 파일을 읽으며, Docker 이미지는 명령을 실행하는 셸이 아니라 Docker 데몬의 네트워크를 사용합니다.

먼저 FlClash에서 mihomo 코어가 실행 중인지 확인하고, 현재 혼합 포트를 기록하세요. 일반적인 값은 127.0.0.1:7890이지만 실제 포트는 설정의 mixed-port를 기준으로 해야 합니다. 외부 컨트롤 포트인 9090은 API 통신용이므로 Git이나 Homebrew의 프록시 주소로 입력하면 안 됩니다.

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

Git HTTPS 프록시 설정

HTTPS 방식의 Git 원격 저장소는 일반적인 웹 요청과 비슷하게 동작하므로 HTTP 또는 SOCKS 프록시를 적용하기 쉽습니다. 현재 설정을 확인하려면 다음 명령을 사용합니다.

git config --global --get http.proxy
git config --global --get https.proxy
git remote -v

FlClash의 혼합 포트가 HTTP CONNECT와 SOCKS5를 모두 제공한다면 다음처럼 Git 전역 프록시를 지정할 수 있습니다.

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

이 설정은 모든 Git HTTPS 원격에 적용됩니다. 업무용 Git 서버나 사내 저장소까지 같은 프록시로 보내고 싶지 않다면 전역 설정 대신 저장소 단위로 지정하세요.

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

일회성 테스트에는 환경 변수가 편리합니다. 설정 파일을 변경하지 않고 한 번만 연결 경로를 시험할 수 있습니다.

HTTPS_PROXY=http://127.0.0.1:7890 \
HTTP_PROXY=http://127.0.0.1:7890 \
git ls-remote https://example.invalid/team/project.git

공용 저장소와 사내 저장소의 정책이 다르다면 url.*.insteadOf보다 원격 URL별 프록시 설정을 먼저 고려하세요. 잘못된 치환 규칙은 저장소 주소 자체를 바꾸어 인증 실패를 일으킬 수 있습니다. 사용하지 않는 프록시를 제거할 때는 다음 명령을 실행합니다.

git config --global --unset http.proxy
git config --global --unset https.proxy

HTTPS 인증 및 오류 점검

Could not resolve host가 표시되면 Git이 프록시에 도달하기 전에 DNS 또는 연결 경로에서 실패한 것입니다. Failed to connect나 Connection refused는 로컬 포트가 틀렸거나 mihomo가 중지된 경우가 많습니다. 407 Proxy Authentication Required는 로컬 프록시가 인증을 요구한다는 뜻이며, 일반적인 로컬 FlClash 포트에서는 발생하지 않아야 합니다. 토큰이나 비밀번호를 URL에 직접 넣을 때는 셸 기록과 Git 설정 파일에 자격 증명이 남을 수 있으므로 주의해야 합니다.

Git의 자세한 전송 로그가 필요하면 민감한 원격 URL을 공개하지 않는 환경에서 다음과 같이 실행하세요.

GIT_CURL_VERBOSE=1 \
git ls-remote https://example.invalid/team/project.git

SSH 프록시와 포트 443 연결

SSH는 HTTP_PROXY나 HTTPS_PROXY만 설정해도 자동으로 Clash를 사용하지 않습니다. SSH는 기본적으로 대상 서버의 TCP 포트에 직접 연결하기 때문입니다. 로컬 SOCKS5 포트를 통해 SSH를 전달하려면 SSH 설정의 ProxyCommand에 SOCKS5를 이해하는 프로그램을 지정해야 합니다.

macOS와 일부 Linux 환경에 포함된 nc가 SOCKS5 클라이언트를 지원한다면 ~/.ssh/config에 다음과 같이 추가할 수 있습니다.

Host github-work
    HostName example.invalid
    User git
    Port 22
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
    ProxyCommand nc -x 127.0.0.1:7890 -X 5 %h %p

위 예시의 github-work는 SSH 별칭입니다. 실제 저장소 주소를 별칭에 맞춰 사용해야 합니다.

git clone git@github-work:team/project.git
ssh -T github-work

배포 환경이나 네트워크에서 TCP 22번이 차단되면 SSH 서버가 제공하는 443번 대체 포트를 사용할 수 있습니다. 이 기능은 서버 측에서 지원해야 하며, 대상 호스트와 포트가 실제 서비스 정책과 일치해야 합니다.

Host github-ssh-443
    HostName ssh.example.invalid
    User git
    Port 443
    IdentityFile ~/.ssh/id_ed25519
    IdentitiesOnly yes
    ProxyCommand nc -x 127.0.0.1:7890 -X 5 %h %p

nc와 ncat의 차이

모든 nc 구현이 같은 옵션을 지원하지는 않습니다. macOS 기본 netcat, OpenBSD netcat, GNU ncat은 옵션 이름과 SOCKS 처리 방식이 다를 수 있습니다. nc -h로 -x와 -X 지원 여부를 먼저 확인하세요. 명령이 “illegal option”으로 끝나면 Clash 문제가 아니라 SSH가 호출한 보조 프로그램의 문법 차이일 가능성이 큽니다.

SSH가 프록시를 거치는지 확인할 때는 상세 로그를 사용합니다.

ssh -vvv github-work

• 직접 연결 로그: 대상 호스트의 22번 포트에 바로 연결을 시도하는지 확인합니다.
• ProxyCommand 로그: 로컬 nc 프로세스가 실행되었는지 확인합니다.
• 인증 실패: 네트워크 연결은 성공했지만 키, 사용자 이름 또는 서버 권한이 잘못된 상태입니다.
• 타임아웃: 프록시 노드, 대상 포트, 서버 측 방화벽 또는 규칙 매칭 결과를 확인합니다.

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

Homebrew와 셸 환경 변수

Homebrew는 패키지 자체뿐 아니라 Git, curl, 압축 파일 다운로드 도구를 함께 사용합니다. 현재 셸에서만 프록시를 적용하려면 다음처럼 대문자와 소문자 변수를 함께 지정하는 편이 안전합니다.

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5h://127.0.0.1:7890
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"

brew update
brew install jq

socks5h의 h는 호스트 이름 해석을 SOCKS 프록시 쪽에서 처리하도록 요청합니다. DNS가 직접 노출되거나 로컬에서 특정 도메인을 해석하지 못하는 환경에서는 socks5보다 적합할 수 있습니다. 다만 각각의 도구가 모든 프록시 변수를 동일하게 해석하는 것은 아니므로, 실패하면 HTTP 기반의 HTTP_PROXY와 HTTPS_PROXY부터 테스트하세요.

프록시 없이 Homebrew를 사용해야 할 때는 현재 셸에서 변수를 제거합니다.

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
unset http_proxy https_proxy all_proxy

npm 레지스트리와 프록시 설정

npm은 전역 또는 사용자 설정에 프록시가 남아 있을 수 있습니다. 먼저 현재 값을 확인하세요.

npm config get proxy
npm config get https-proxy
npm config get registry

필요한 경우 HTTP 프록시를 명시적으로 설정합니다.

npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
npm ping

회사 내부 레지스트리나 프록시 인증을 사용하는 경우에는 프로젝트의 .npmrc와 사용자 홈의 ~/.npmrc를 모두 확인해야 합니다. 토큰이 포함된 레지스트리 주소를 커밋하지 말고, 잘못된 프록시 설정을 초기화할 때는 다음 명령을 사용하세요.

npm config delete proxy
npm config delete https-proxy

Docker는 데몬을 별도로 설정하기

Docker 명령에 셸 프록시를 지정했다고 해서 이미지 레이어 다운로드가 항상 프록시를 통과하는 것은 아닙니다. docker pull은 Docker Desktop의 백엔드 또는 Linux의 Docker 데몬이 원격 레지스트리에 연결합니다. 따라서 Docker Desktop을 사용한다면 애플리케이션의 네트워크 또는 프록시 설정 화면에서 프록시를 지정하고 데몬을 재시작해야 합니다. Linux에서는 systemd 환경 설정에 Docker 서비스용 프록시를 추가한 뒤 데몬을 다시 로드합니다.

컨테이너 내부의 패키지 설치와 이미지 자체의 다운로드는 서로 다른 문제입니다. docker build 중 실행되는 apt, npm, pip는 빌드 컨테이너의 환경 변수를 사용하지만, 기본 이미지 레이어를 가져오는 작업은 데몬 프록시를 사용합니다. 이 둘을 분리해서 설정해야 “빌드는 되지만 pull이 실패하는” 상황을 피할 수 있습니다.

TUN과 개발자 트래픽 분기 규칙

시스템 프록시를 지원하지 않는 SSH 도구, Docker 백엔드, 일부 IDE와 백그라운드 서비스까지 일관되게 처리하려면 mihomo의 TUN 모드를 고려할 수 있습니다. TUN은 가상 네트워크 인터페이스를 만들고 운영체제의 IP 트래픽을 코어로 전달합니다. 편리하지만 네트워크 확장 권한, 자동 라우팅, DNS 하이재킹이 함께 작동하므로 시스템 프록시보다 영향 범위가 넓습니다.

먼저 Git, 패키지 레지스트리, 컨테이너 레지스트리처럼 프록시가 필요한 도메인을 규칙으로 분리하세요. 실제 규칙 순서는 설정 전체에 따라 달라지므로 아래 항목은 구조를 이해하기 위한 예시입니다.

rules:
  - DOMAIN-SUFFIX,example.invalid,PROXY
  - DOMAIN-SUFFIX,npmjs.org,PROXY
  - DOMAIN-SUFFIX,docker.io,PROXY
  - DOMAIN-SUFFIX,registry-1.docker.io,PROXY
  - DOMAIN-SUFFIX,company.internal,DIRECT
  - GEOIP,LAN,DIRECT
  - MATCH,DIRECT

특정 서비스가 여러 도메인과 CDN을 사용한다면 한 도메인만 추가해서는 부족할 수 있습니다. 연결 로그에서 실제로 매칭된 호스트 이름과 선택된 정책을 확인하고, 필요한 범위만 규칙에 추가하세요. 모든 트래픽을 무조건 프록시로 보내는 MATCH,PROXY는 사내망, 프린터, 로컬 개발 서버까지 우회시킬 수 있으므로 마지막 수단으로 사용하는 편이 좋습니다.

• GitHub 또는 외부 저장소: HTTPS와 SSH의 실제 대상 도메인을 각각 확인합니다.
• 사내 Git과 레지스트리: 사설 IP, 내부 DNS, .internal 도메인은 대개 DIRECT가 적합합니다.
• Docker: 레지스트리 도메인과 인증 서버 도메인이 서로 다를 수 있습니다.
• DNS: TUN에서 DNS 모드를 바꾼 뒤 내부 도메인 해석이 깨지지 않는지 확인합니다.

반복 장애를 줄이는 점검 순서

1. FlClash의 코어 상태와 실제 mixed-port를 확인합니다.
2. curl -x http://127.0.0.1:7890 https://example.invalid처럼 로컬 HTTP 프록시의 기본 동작을 테스트합니다.
3. Git HTTPS는 git config --show-origin --get-regexp 'http.*proxy'로 적용 출처를 확인합니다.
4. SSH는 ssh -vvv에서 ProxyCommand가 실행되는지 확인합니다.
5. Homebrew와 npm은 환경 변수와 사용자별 설정 파일에 오래된 포트가 남아 있지 않은지 점검합니다.
6. Docker는 클라이언트 셸이 아니라 Desktop 또는 Docker 데몬의 프록시를 확인합니다.
7. 마지막으로 Clash 연결 로그에서 도메인, 규칙, 정책 그룹과 실패 시점을 대조합니다.

프록시 포트를 바꾼 뒤에는 Git 설정, SSH 설정, 셸 프로필, npm 설정, Docker Desktop 설정에 이전 포트가 남아 있지 않은지 확인하세요. 특히 셸 프로필에 오래된 ALL_PROXY가 남아 있으면 특정 명령만 예상하지 못한 SOCKS 포트로 연결될 수 있습니다. 테스트가 끝난 후에는 필요한 범위만 영구 설정으로 남기고, 공용 노트북이나 팀 저장소에 토큰과 인증서 정보를 기록하지 않는 것이 안전합니다.

자주 묻는 질문