터미널 연결만 실패할 때 확인할 것
브라우저에서는 웹사이트가 잘 열리는데 Git clone, npm install, pip install 또는 Docker 이미지 다운로드만 멈춘다면, 먼저 해당 프로그램이 브라우저와 같은 프록시 경로를 쓰는지 확인해야 합니다. 브라우저는 운영체제의 시스템 프록시를 따르는 경우가 많지만, 터미널 프로그램은 셸 환경 변수나 자체 프록시 설정을 사용합니다. 따라서 Clash에서 시스템 프록시를 켰다는 사실만으로 모든 CLI 도구가 자동으로 같은 경로를 탄다고 가정하기는 어렵습니다.
대표적인 증상은 ETIMEDOUT, ECONNRESET, TLS 핸드셰이크 실패, 저장소 연결 대기처럼 나타납니다. 반면 HTTP 401·403은 계정 인증이나 접근 권한 문제일 수 있고, 429는 요청 제한과 관련될 수 있습니다. 오류 문구를 먼저 구분하면 프록시 설정을 무작정 바꾸는 일을 줄일 수 있습니다. 특히 사내 Git 서버나 로컬 패키지 레지스트리까지 외부 프록시로 보내면 인증 실패나 내부 DNS 오류가 추가로 생길 수 있습니다.
이 가이드는 Clash Verge Rev와 Mihomo 계열 클라이언트를 예로 들어, TUN 모드와 터미널 프록시 환경 변수를 함께 점검하는 순서를 설명합니다. 메뉴 이름과 설정 위치는 클라이언트 버전마다 다를 수 있으므로, 화면의 표기보다 실제 포트 번호와 연결 로그를 기준으로 확인하세요. 구독 프로필의 노드 이름이나 규칙 구성은 제공자마다 다르므로 특정 이름에 의존하지 않는 방식으로 정리했습니다.
TUN 모드와 환경 변수는 역할이 다릅니다
TUN 모드는 가상 네트워크 인터페이스와 라우팅을 이용해 운영체제 수준의 트래픽을 처리합니다. 애플리케이션이 프록시 환경 변수를 읽지 않아도 트래픽을 포착할 수 있다는 장점이 있지만, 권한 승인, DNS 처리, 라우팅 예외, 네트워크 어댑터 충돌을 함께 고려해야 합니다. VPN이나 보안 에이전트가 이미 가상 어댑터를 사용 중이라면 TUN을 켠 뒤 경로가 바뀌거나 연결이 불안정해질 수 있습니다.
HTTP_PROXY와 HTTPS_PROXY는 프로그램이 지원하는 경우 요청을 지정한 프록시 주소로 보내도록 안내하는 환경 변수입니다. 설정 범위가 셸 세션이나 특정 프로세스에 비교적 명확하게 한정되므로, 하나의 CLI 도구만 시험할 때 유용합니다. 다만 모든 프로그램이 이 변수를 읽는 것은 아닙니다. Git은 자체 설정을 사용할 수 있고, Docker 데몬은 터미널에서 실행한 Docker CLI와 다른 프로세스이므로 별도의 프록시 설정이 필요할 수 있습니다.
실무에서는 두 방식을 경쟁 관계로 보기보다 보완적으로 사용하는 편이 편리합니다. TUN은 환경 변수를 무시하는 애플리케이션이나 일반적인 시스템 트래픽을 처리하고, 환경 변수는 지원하는 CLI에 명시적인 경로를 전달합니다. 단, 같은 연결을 TUN과 애플리케이션 프록시가 모두 처리하면 이중 프록시처럼 동작할 수 있습니다. 테스트할 때는 한 번에 하나의 경로만 바꾸고, Clash 연결 로그에 실제 요청이 나타나는지 확인하세요.
mixed-port를 확인하세요. 예시의 7890은 흔히 쓰이는 값일 뿐이며, 내 클라이언트의 포트와 다르면 연결되지 않습니다.
Clash에서 먼저 맞출 기본 설정
먼저 프로필이 활성화되어 있고 코어가 정상 실행 중인지 확인합니다. 구독을 갱신한 직후라면 프록시 그룹이나 규칙 프로바이더가 바뀌어 특정 도메인의 경로가 달라졌을 수 있습니다. 연결 모드는 우선 규칙 모드로 두고, Git 호스트나 패키지 레지스트리 요청이 어떤 규칙에 매칭되는지 로그에서 살펴보세요. 전체 트래픽을 한 노드로 보내는 글로벌 모드는 짧은 진단에는 편하지만, 내부 서비스와 지역 CDN까지 같은 출구로 보낼 수 있어 상시 설정으로는 적절하지 않을 수 있습니다.
다음으로 클라이언트의 포트 설정에서 혼합 포트 또는 HTTP·SOCKS 포트가 활성화되어 있는지 확인합니다. 혼합 포트는 일반적으로 HTTP 프록시 요청과 SOCKS 연결을 함께 받을 수 있지만, 실제 지원 범위와 주소는 사용 중인 코어 설정을 확인해야 합니다. 로컬에서 사용할 때는 보통 루프백 주소인 127.0.0.1을 사용합니다. LAN 공유 기능을 켜지 않았다면 다른 기기에서 같은 주소로 접속할 수 없으며, 외부에 프록시 포트를 공개할 필요가 없다면 LAN 접근을 활성화하지 않는 것이 안전합니다.
터미널에서 포트가 열려 있는지 확인한 뒤 작은 요청으로 연결을 검증합니다. 연결 여부만으로 원하는 노드가 선택됐다고 단정하지 말고, Clash의 연결 기록에서 대상 호스트와 정책 그룹을 확인해야 합니다. TUN을 사용할 때는 운영체제의 네트워크 권한 요청을 승인하고, DNS 설정 및 자동 라우트 옵션을 확인합니다. 이미 다른 VPN을 사용 중이라면 충돌 여부를 분리해서 시험하고, 문제가 생기면 TUN을 끈 상태에서 환경 변수 방식으로 재현해 원인을 좁힙니다.
셸에 프록시를 설정하고 Git·npm·pip 확인하기
아래는 POSIX 셸에서 현재 터미널 세션에만 프록시를 적용하는 예입니다. 자신의 Clash 포트로 바꿔 실행하고, 성공 여부를 확인한 뒤 필요하면 셸 설정 파일이나 프로젝트별 환경 관리 도구에 옮기세요. 처음부터 모든 터미널에 영구 적용하면 사내망이나 직접 연결이 필요한 프로젝트에서 예상하지 못한 문제가 생겼을 때 원인을 찾기 어려워집니다.
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,.internal.example"
각 변수는 도구마다 다르게 해석될 수 있습니다. 어떤 클라이언트는 소문자 http_proxy와 https_proxy만 읽고, 다른 클라이언트는 대문자 변수만 읽거나 두 형식을 모두 지원합니다. 동작이 불분명하면 잠시 대소문자 변수를 함께 설정해 비교하되, 시스템 전체의 영구 설정으로 중복 등록하지는 마세요. 프록시 URL은 Clash가 실제로 제공하는 프로토콜과 포트에 맞춰야 합니다. HTTP 포트에 socks5://를 지정하거나 SOCKS 포트에 http://를 지정하면 연결 실패가 날 수 있습니다.
- Git: 환경 변수를 읽는지 확인하고, 별도 설정이 있다면
git config --get http.proxy로 현재 값을 살펴봅니다. Git 설정에 저장된 오래된 프록시가 환경 변수보다 우선하거나 서로 다른 경로를 만들 수 있습니다. 저장소별 예외가 필요하다면 전역 설정 대신 해당 저장소의 설정 범위를 고려하세요. - npm:
npm config get proxy와npm config get https-proxy로 npm 자체 설정을 확인합니다. 레지스트리 주소가 사내 미러라면 외부 프록시보다 내부 네트워크로 직접 연결해야 할 수도 있습니다. 인증 토큰이 들어 있는 설정 파일을 진단 목적으로 공유하거나 저장소에 커밋하지 마세요. - pip: 환경 변수 또는 pip 설정 파일의 프록시 항목이 사용될 수 있습니다. 사내 패키지 인덱스를 쓰는 경우에는 공개 PyPI와 내부 인덱스의 주소 및 인증 방식을 분리해 확인합니다. 인증 정보가 포함된 프록시 URL은 셸 기록이나 로그에 남지 않도록 주의하세요.
오류를 재현할 때는 한 번에 하나의 클라이언트만 실행하고, 같은 시각의 Clash 로그와 프로그램 출력을 비교합니다. 요청이 로그에 전혀 없다면 해당 앱이 다른 네트워크 경로를 쓰거나 프록시 환경 변수를 읽지 않을 가능성이 있습니다. 로그에는 대상 도메인이 있지만 DIRECT로 표시된다면 규칙 매칭을 확인하고, 기대한 프록시 그룹이 표시되는데 실패한다면 노드 상태, DNS 응답, TLS 오류를 각각 살펴보세요.
Docker·컨테이너와 내부 주소 우회
Docker는 특히 경로를 혼동하기 쉽습니다. 터미널에서 실행한 Docker 클라이언트와 이미지를 내려받는 Docker 데몬은 서로 다른 역할을 합니다. 셸에 HTTPS_PROXY를 설정해도 데몬의 이미지 다운로드가 같은 변수 설정을 자동으로 사용하는 것은 아닙니다. 또한 컨테이너 안에서 127.0.0.1은 기본적으로 컨테이너 자신을 가리키며, 호스트에서 실행 중인 Clash를 의미하지 않습니다. 컨테이너 네트워크 모드와 운영체제에 따라 호스트로 연결하는 주소가 달라질 수 있으므로, 임의의 주소를 그대로 복사하지 말고 해당 환경의 Docker 문서를 확인하세요.
이미지 내려받기만 실패한다면 먼저 Docker 데몬의 프록시 설정과 재시작 여부를 확인합니다. 컨테이너 내부 애플리케이션의 요청만 실패한다면 Compose나 실행 환경에 필요한 변수를 전달할 수 있지만, 이미지 다운로드용 설정과 컨테이너 내부 요청용 설정은 별개로 점검해야 합니다. 프록시 URL에 사용자 이름이나 비밀번호가 포함되는 경우 환경 출력 명령이나 진단 로그에 비밀 값이 찍힐 수 있으므로, 공유 전에 반드시 가리세요.
NO_PROXY에는 프록시를 거치지 않아야 하는 주소를 최소 범위로 넣습니다. 보통 localhost, 127.0.0.1, IPv6 루프백 주소, 사내 도메인 접미사, 내부 레지스트리 주소가 후보입니다. 도구마다 와일드카드나 도메인 접미사를 처리하는 방식이 다르므로 실제 프로그램에서 확인해야 합니다. 너무 넓은 주소 범위를 지정하면 외부 서비스가 의도치 않게 직접 연결로 빠질 수 있고, 반대로 내부 도메인을 누락하면 사내 DNS 이름이 외부 프록시로 전달되어 실패할 수 있습니다.
로컬 개발 서버, 데이터베이스, Kubernetes API처럼 내부 주소에 연결하는 워크플로에서는 우회 규칙을 먼저 정리하는 것이 좋습니다. Clash의 규칙과 NO_PROXY는 서로 다른 계층에서 작동하므로 어느 한쪽만 설정했다고 전체 경로가 보장되지는 않습니다. 내부 호스트가 Clash 연결 로그에 나타나는지, 컨테이너에서 해당 이름이 올바른 IP로 해석되는지, 직접 연결이 필요한 서비스가 실제로 직접 나가는지를 각각 검증하세요.
단계별 검증과 자주 놓치는 원인
안정적인 설정을 만들려면 연결 테스트를 작은 단위로 나누세요. 먼저 Clash 코어와 로컬 포트를 확인하고, 다음으로 호스트 셸에서 프록시를 지정한 요청을 실행합니다. 이어 Git 또는 npm처럼 문제가 난 도구 하나를 테스트한 뒤, 마지막으로 Docker 데몬이나 컨테이너를 별도로 검증합니다. 각 단계에서 성공한 상태를 기록하면 어디서 경로가 달라졌는지 빠르게 찾을 수 있습니다. 브라우저 한 곳에서만 성공하는 결과는 CLI나 컨테이너가 같은 프록시를 사용한다는 증거가 아닙니다.
로그를 볼 때는 시간, 대상 호스트, 정책 결과, 연결 종료 사유를 함께 기록합니다. DNS 실패라면 프록시 노드만 바꾸기 전에 시스템 DNS와 Clash DNS 설정을 비교하고, TLS 오류라면 시스템 시계, 인증서 검사, 중간 프록시 여부를 점검합니다. 연결이 일정 시간 뒤 끊긴다면 노드의 안정성이나 긴 응답 스트림 처리도 살펴볼 수 있습니다. 반대로 응답이 401·403이라면 API 토큰이나 저장소 권한 문제를 먼저 확인해야 합니다.
셸 변수를 바꾼 뒤에는 이미 실행 중인 IDE를 재시작해야 할 때도 있습니다. IDE 통합 터미널은 IDE가 시작될 당시의 환경을 물려받을 수 있기 때문입니다. 셸 프로필을 수정했는데도 새 터미널에서 값이 달라 보인다면 로그인 셸과 비로그인 셸의 설정 파일, direnv 같은 프로젝트별 환경 도구를 확인하세요. 테스트가 끝나면 임시 변수를 제거하거나 원래 값으로 되돌려, 다음 프로젝트에서 의도하지 않은 프록시가 계속 적용되지 않게 합니다.
자주 묻는 질문
TUN 모드를 켰는데도 Git이 직접 연결되는 이유는 무엇인가요?
TUN이 활성화되어도 라우팅 예외, 규칙의 DIRECT 판정, 네트워크 확장 권한 또는 실행 환경의 네트워크 경로에 따라 연결 결과가 달라질 수 있습니다. Clash 연결 로그에서 Git 서버 호스트가 나타나는지 확인하고, 나타난다면 어떤 규칙과 정책 그룹이 선택됐는지 살펴보세요. 로그에 없다면 Git의 자체 프록시 설정이나 터미널이 실행된 네트워크 환경을 확인하는 것이 좋습니다.
프록시 환경 변수는 셸 설정 파일에 영구 저장해도 되나요?
가능하지만 모든 프로젝트가 같은 프록시를 필요로 하는 것은 아닙니다. 우선 현재 셸에서 시험하고, 사내망과 로컬 주소의 예외가 정확한지 확인한 뒤 적용 범위를 결정하세요. 프로젝트별 설정 도구를 사용하면 개인 작업 환경과 저장소 설정을 분리하기 쉽습니다. 프록시 인증 정보를 평문으로 저장하거나 공유 저장소에 올리지 않도록 주의해야 합니다.
터미널 프록시는 되는데 Docker 이미지 다운로드만 실패합니다. 무엇을 봐야 하나요?
이미지 다운로드는 보통 Docker 데몬이 처리하므로 터미널 셸의 환경 변수만으로 해결되지 않을 수 있습니다. 데몬의 프록시 설정, 서비스 재시작 여부, DNS 해석, 레지스트리 접근 정책을 확인하세요. 컨테이너 내부 애플리케이션의 프록시 설정과 이미지 다운로드 경로를 같은 문제로 취급하지 않는 것이 중요합니다.
NO_PROXY에는 무엇을 넣어야 하나요?
로컬 루프백 주소와 실제로 직접 연결해야 하는 사내 도메인 또는 내부 레지스트리만 넣는 것이 기본입니다. 지원 문법은 Git, npm, pip, Docker 등 프로그램마다 다를 수 있으므로 하나의 형식이 모든 도구에서 동일하게 작동한다고 가정하지 마세요. 설정 후 내부 서비스와 외부 서비스 양쪽을 시험해 우회 범위가 너무 넓거나 좁지 않은지 확인합니다.
개발용 프록시 프로그램마다 환경 변수 지원 범위가 다르고, 일부는 시스템 프록시만 제공해 컨테이너나 CLI에서 별도 설정을 요구하기도 합니다. Clash는 규칙 기반 분기, TUN 라우팅, 로컬 혼합 포트와 연결 로그를 조합할 수 있어 Git·npm·pip·Docker의 경로를 단계별로 확인하기 편리합니다. 특정 도구의 전용 프록시 설정에만 의존하기보다 시스템 경로와 애플리케이션 설정을 함께 점검하고 싶다면, 사용 중인 운영체제에 맞는 클라이언트를 선택해 같은 절차를 적용해 보세요.