개발자를 위한 Clash 설정: GitHub·Git·SSH 작업 흐름 최적화

개발 환경에서 Clash를 따로 설정해야 하는 이유

브라우저에서 GitHub 페이지가 열리는 것만으로는 개발 환경의 네트워크가 모두 정상이라고 판단하기 어렵습니다. 브라우저는 운영체제의 시스템 프록시를 자동으로 읽을 수 있지만, Git, OpenSSH, npm, pnpm, Docker, IDE 확장 기능은 각자 다른 프록시 설정과 인증 방식을 사용합니다. 따라서 GitHub 웹페이지는 열리는데 git clone이 멈추거나, 저장소는 내려받았지만 npm install에서 패키지 다운로드가 실패하는 상황이 발생할 수 있습니다.

Clash 클라이언트에서 시스템 프록시를 켜면 일반적인 HTTP 및 HTTPS 애플리케이션은 로컬 프록시 포트로 요청을 보낼 수 있습니다. 그러나 터미널 프로그램은 운영체제의 프록시 스위치를 반드시 따르지 않습니다. Git은 자체 설정 또는 환경 변수를 확인하고, SSH는 기본적으로 프록시를 사용하지 않은 채 TCP 22번 포트로 직접 연결합니다. 개발자 업무 흐름을 안정적으로 만들려면 그래픽 클라이언트, 셸 환경, Git 전송 방식, SSH 연결을 각각 확인해야 합니다.

Clash에서 먼저 확인할 로컬 포트와 규칙 모드

Clash Verge, Clash Verge Rev, Clash for Windows, ClashX, Mihomo 기반 클라이언트는 화면 구성과 기본값이 서로 다를 수 있습니다. 설정 화면에서 mixed-port, HTTP 포트, SOCKS 포트 또는 외부 컨트롤러 포트를 구분해 확인하세요. Git과 npm을 함께 설정할 때는 HTTP와 SOCKS 요청을 모두 처리할 수 있는 mixed-port가 편리합니다. 예를 들어 로컬 주소가 127.0.0.1:7890이라면 HTTP 프록시 URL은 http://127.0.0.1:7890처럼 작성할 수 있습니다.

포트 번호는 예시일 뿐이며 모든 클라이언트에서 동일하지 않습니다. 실제 포트를 확인하지 않고 7890이나 7897을 무조건 입력하면 연결 거부, timeout 또는 다른 프로그램과의 포트 충돌이 발생합니다. Windows에서는 Clash 로그와 설정 화면을 확인하고, macOS와 Linux에서는 로컬 포트가 실제로 열려 있는지 터미널에서 점검할 수 있습니다.

curl -I -x http://127.0.0.1:7890 https://github.com
curl -I -x http://127.0.0.1:7890 https://registry.npmjs.org

첫 번째 요청은 GitHub 도메인에 대한 HTTPS 프록시 연결을, 두 번째 요청은 npm 기본 레지스트리 접근을 확인하는 예시입니다. 응답이 돌아오면 로컬 포트와 기본 프록시 경로가 적어도 작동하는 것입니다. 응답이 없으면 노드 선택, 규칙 모드, 방화벽, 포트 번호를 순서대로 확인하세요. 로그에서 대상 도메인이 어떤 규칙에 매칭되었는지도 함께 살펴보면 프록시 문제와 규칙 문제를 구분할 수 있습니다.

개발 트래픽에 적합한 모드 선택

브라우저와 Git HTTPS만 사용할 때는 시스템 프록시와 명시적인 Git 프록시 설정만으로 충분한 경우가 많습니다. 반면 SSH, Docker, 일부 IDE 확장 기능처럼 시스템 프록시를 무시하는 프로그램까지 같은 경로로 보내야 한다면 TUN 모드를 고려할 수 있습니다. TUN은 프록시 프로토콜이 아니라 가상 네트워크 인터페이스를 통해 IP 트래픽을 Clash 코어에 전달하는 방식입니다. 관리자 권한, 라우팅, DNS, 방화벽이 추가 변수로 들어오므로 처음부터 TUN을 켜기보다 일반 프록시 경로를 먼저 검증하는 편이 안전합니다.

Git HTTPS 연결 설정: clone, fetch, push를 같은 기준으로 맞추기

GitHub 저장소를 HTTPS 주소로 사용하는 경우 Git은 웹 브라우저와 별도로 프록시를 설정해야 할 수 있습니다. 가장 명확한 방법은 Git 전역 설정에 Clash의 HTTP 프록시 주소를 등록하는 것입니다. 아래 명령에서 포트는 실제 Clash 설정에 맞게 바꾸세요.

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 http.proxy
git config --global --get https.proxy

HTTPS 저장소 주소에 접근할 때 Git의 https.proxy가 주로 사용되지만, 리다이렉션이나 부가 요청이 섞일 수 있으므로 두 항목을 같은 로컬 포트로 맞추면 예측하기 쉽습니다. SOCKS 포트만 사용하려면 Git과 버전에 따라 SOCKS URL을 사용할 수 있지만, 조직 환경과 인증서 검사 방식에 따라 동작 차이가 생길 수 있습니다. 가능하면 Clash의 HTTP 또는 mixed-port를 우선 사용하고, 실제 명령으로 검증하세요.

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

GIT_CURL_VERBOSE=1은 Git의 HTTP 전송 과정을 확인하는 데 유용합니다. 로그에 로컬 프록시 주소로 연결하는 흔적이 있는지, TLS 협상이 시작되는지, 원격 서버가 인증을 요구하는지 구분할 수 있습니다. 운영체제나 Git 배포판에 따라 환경 변수 이름과 로그 형식이 조금 다를 수 있으므로, 로그에 토큰이나 비밀번호가 노출되지 않도록 결과를 다른 사람에게 공유하기 전 민감한 값을 지우세요.

환경 변수로 일시적인 프록시 적용

전역 Git 설정을 변경하고 싶지 않다면 현재 셸 세션에만 환경 변수를 지정할 수 있습니다. CI 스크립트나 임시 네트워크에서 특히 편리하지만, 셸을 닫거나 변수를 해제하면 사라집니다.

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

git clone https://github.com/example/project.git

Windows PowerShell에서는 다음처럼 작성할 수 있습니다.

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
git clone https://github.com/example/project.git

더 이상 프록시를 사용하지 않을 때는 Git 설정과 환경 변수를 정리해야 합니다. 전역 설정을 남겨 두면 Clash를 종료한 뒤에도 모든 Git 요청이 닫힌 로컬 포트로 향할 수 있습니다.

git config --global --unset http.proxy
git config --global --unset https.proxy
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

Git SSH 설정: OpenSSH가 Clash를 통과하도록 구성하기

SSH 방식의 GitHub 주소는 보통 [email protected]:owner/repository.git 형태입니다. SSH는 HTTP 프록시 URL을 그대로 읽지 않으므로 Git에 http.proxy를 등록해도 SSH 연결에는 적용되지 않습니다. 이때는 SSH 클라이언트의 ProxyCommand를 이용해 로컬 SOCKS 또는 HTTP 프록시를 통해 원격 SSH 연결을 전달해야 합니다.

먼저 SSH 키 자체가 정상인지 확인하세요. 프록시를 설정하기 전에 직접 연결이 가능한 환경에서 다음 명령을 실행하면 키 권한과 GitHub 계정 연결 문제를 분리할 수 있습니다.

ssh -T [email protected]

Clash가 SOCKS 포트를 제공하고, 시스템에 nc 또는 SOCKS를 지원하는 netcat 구현이 설치되어 있다면 사용자 SSH 설정 파일에 다음과 같은 구조를 사용할 수 있습니다.

Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519
    ProxyCommand nc -x 127.0.0.1:7891 -X 5 %h %p

여기서 7891은 SOCKS 포트 예시이며 실제 값으로 교체해야 합니다. 모든 netcat 구현이 -x와 -X 5 옵션을 지원하는 것은 아닙니다. 명령이 “invalid option”을 반환한다면 다른 netcat 패키지를 설치하거나, 현재 환경에서 사용할 수 있는 SOCKS 전달 도구의 문법을 확인해야 합니다. Windows에서는 OpenSSH가 설치되어 있어도 포함된 netcat이 없는 경우가 많으므로, SSH 설정만 복사한다고 즉시 작동하지 않을 수 있습니다.

SSH 포트 443 대안과 주의점

네트워크에서 TCP 22번 포트가 차단된 경우 GitHub가 제공하는 SSH over HTTPS 엔드포인트를 사용할 수 있습니다. SSH 설정에서 호스트를 443번 포트로 지정하는 방식입니다.

Host github.com
    HostName ssh.github.com
    Port 443
    User git
    IdentityFile ~/.ssh/id_ed25519
    ProxyCommand nc -x 127.0.0.1:7891 -X 5 %h %p

이 설정은 GitHub의 SSH 서비스가 443번 포트에서 제공되는 환경을 전제로 합니다. 일반 HTTPS 프록시 포트와 SSH 포트는 서로 다른 역할을 하므로, HTTP 프록시 주소를 ProxyCommand에 그대로 넣으면 실패할 수 있습니다. SSH 연결이 계속 끊긴다면 포트, 호스트 이름, 키 파일, SSH 에이전트, Clash 로그의 규칙 매칭을 각각 확인하세요.

실전 설정 순서: 로컬 포트부터 npm 설치까지

한 번에 모든 개발 도구를 바꾸지 말고 다음 순서로 진행하면 원인 추적이 쉽습니다. 이 과정에서는 Clash의 포트와 노드가 이미 정상적으로 동작한다고 가정합니다.

1. Clash 포트 확인: 설정 화면에서 HTTP, SOCKS 또는 mixed-port의 실제 값을 기록합니다. 현재 정책 그룹에서 사용할 노드를 하나 고정해 자동 선택 변수를 줄입니다.
2. 기본 HTTPS 테스트: curl -I -x 명령으로 GitHub와 npm 레지스트리에 각각 요청합니다. 두 요청 중 하나만 실패하면 규칙 또는 대상 네트워크를 비교합니다.
3. Git HTTPS 설정: 전역 설정 또는 현재 셸의 HTTPS_PROXY를 사용해 git ls-remote를 실행합니다. clone 전체보다 작은 메타데이터 요청이 진단에 적합합니다.
4. SSH 별도 구성: SSH 키 인증을 확인한 뒤 ~/.ssh/config에 ProxyCommand를 추가합니다. ssh -vT [email protected]으로 프록시 명령 실행 여부를 확인합니다.
5. 패키지 관리자 설정: npm의 registry와 proxy 설정을 확인한 다음 작은 패키지 설치 또는 메타데이터 조회를 실행합니다.
6. IDE와 CI 확인: IDE가 셸 환경 변수를 상속하는지, CI 러너가 같은 Clash 인스턴스에 접근할 수 있는지 확인합니다. 로컬 설정이 원격 실행 환경에 자동으로 복사되지는 않습니다.

npm은 다음처럼 현재 설정을 조회하고 프록시를 등록할 수 있습니다.

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

npm view npm version
npm install

사내 레지스트리나 별도의 패키지 미러를 사용하는 프로젝트라면 무조건 npm 기본 레지스트리로 바꾸지 마세요. 프로젝트의 .npmrc, 조직 인증서, 토큰 정책이 우선입니다. npm 설정에 인증 정보가 포함된 경우 셸 기록, 공유 화면과 로그에 토큰이 남지 않도록 주의해야 합니다. 테스트가 끝난 뒤 프록시를 해제하려면 설정 파일의 적용 범위를 확인하고 다음 명령을 사용할 수 있습니다.

npm config delete proxy
npm config delete https-proxy

pnpm과 Yarn도 npm과 유사한 환경 변수를 읽을 수 있지만 세부 설정 키와 인증 저장 방식은 버전에 따라 다릅니다. 같은 명령을 무조건 복사하기보다 해당 도구의 현재 설정을 먼저 조회하세요. Git, npm, SSH가 각각 성공했다면 마지막으로 실제 프로젝트의 clone, 의존성 설치, 테스트 명령을 순서대로 실행해 개발 업무 전체가 안정적인지 확인합니다.

GitHub Copilot과 IDE 연결을 점검하는 방법

GitHub Copilot과 IDE 확장 기능은 Git 저장소의 HTTPS 또는 SSH 연결과 동일한 경로를 사용한다고 단정할 수 없습니다. 확장 기능은 IDE의 네트워크 계층, 운영체제 프록시, 자체 프록시 옵션, 로그인 토큰 저장소를 별도로 사용할 수 있습니다. 따라서 git pull이 성공해도 Copilot 로그인이나 제안 생성이 실패할 수 있고, 반대로 IDE는 연결되지만 터미널의 Git이 실패할 수도 있습니다.

먼저 IDE의 네트워크 또는 프록시 설정을 확인하세요. 시스템 프록시 사용, 수동 HTTP 프록시, 인증서 검증, 프록시 예외 목록이 서로 충돌하지 않는지 봅니다. Clash 로그에서는 로그인과 확장 기능이 요청하는 도메인이 실제로 기록되는지 확인하되, 특정 도메인을 임의로 차단 해제하거나 모든 트래픽을 무조건 프록시로 보내기보다 서비스 정책과 조직 네트워크 규칙을 따라야 합니다.

로그인 창이 반복해서 나타난다면 네트워크만의 문제는 아닐 수 있습니다. 브라우저 인증 세션, 만료된 토큰, 조직 계정 권한, 시스템 시간 오류도 확인해야 합니다. 제안 요청이 timeout 되는 경우에는 Clash에서 해당 연결의 최종策略와 노드를 확인하고, 같은 시간대에 다른 HTTPS 요청도 느린지 비교하세요. GitHub 관련 도메인만 실패하면 규칙 또는 노드의 대상 경로를, 모든 HTTPS 서비스가 느리면 로컬 포트와 노드 상태를 우선 점검합니다.

자주 발생하는 오류와 계층별 해결 방법

GitHub 웹페이지는 열리지만 clone이 timeout 되는 경우

브라우저만 시스템 프록시를 사용하고 Git은 직접 연결 중일 가능성이 큽니다. git config --global --get-regexp 'http.*proxy'로 Git 설정을 조회하고, 셸 환경 변수와 Clash 로그를 함께 확인하세요. HTTPS clone이라면 Git 프록시를 설정한 뒤 git ls-remote로 작은 요청을 먼저 테스트합니다.

fatal: unable to access 또는 407 오류가 표시되는 경우

프록시 서버가 인증을 요구하거나 잘못된 프록시 URL이 등록된 경우입니다. 로컬 Clash 포트에 일반적인 프록시 인증을 임의로 추가하지 말고, 프록시 주소와 포트가 정확한지 확인하세요. 회사 프록시를 거치는 환경이라면 Clash의 상위 프록시 설정과 인증 정책이 별도로 필요할 수 있습니다.

SSH는 connection refused 또는 connection timed out을 반환하는 경우

SSH는 Git HTTPS 설정을 사용하지 않습니다. ssh -vT 로그에서 ProxyCommand가 실행되는지 보고, netcat 옵션, SOCKS 포트, 대상 호스트와 포트를 확인하세요. ProxyCommand가 없으면 SSH가 직접 22번 포트로 연결하고 있을 가능성이 높습니다.

npm install에서 인증서 또는 레지스트리 오류가 발생하는 경우

프록시를 끄고도 같은 오류가 난다면 registry, 패키지 잠금 파일, 사내 인증서와 인증 토큰을 먼저 확인합니다. HTTPS 검증을 끄는 방식으로 문제를 해결하려고 하지 마세요. TLS 검증을 약화하면 중간자 공격에 취약해지고, 원인이 단순한 레지스트리 주소 오류일 때도 보안 설정만 나빠질 수 있습니다.

FAQ: 개발자용 Clash 설정 질문