Claude Code를 Clash로 쓰는 법｜터미널 연결 설정 가이드

Claude Code와 Clash를 함께 사용하는 이유

Claude Code는 터미널에서 파일을 읽고, 코드를 수정하고, 테스트 명령을 실행하며, Git 작업까지 수행하는 AI 코딩 도구입니다. 브라우저에서만 사용하는 AI 서비스와 달리 실제 개발 환경의 명령줄 프로그램이 네트워크에 직접 접근하므로, 로그인 과정과 모델 API 호출뿐 아니라 패키지 저장소, Git 원격 저장소, 문서 사이트까지 여러 연결이 동시에 필요할 수 있습니다.

이때 Clash를 터미널의 프록시로 연결하면 필요한 트래픽을 규칙에 따라 분리할 수 있습니다. 예를 들어 회사 내부 Git 서버나 국내 패키지 미러는 직접 연결하고, Claude 서비스와 해외 저장소는 프록시를 통과하게 구성할 수 있습니다. 모든 트래픽을 무조건 우회하는 것보다 지연과 오류를 줄이기 쉽고, 어떤 요청이 프록시를 사용했는지도 Clash 로그에서 확인할 수 있다는 장점이 있습니다.

다만 Clash의 데스크톱 앱이 실행 중이라는 사실만으로 모든 터미널 프로그램이 자동으로 프록시를 사용하는 것은 아닙니다. 브라우저는 시스템 프록시를 따르더라도 curl, npm, pnpm, git, Claude Code가 사용하는 런타임은 별도의 환경 변수를 요구할 수 있습니다. 따라서 이 글에서는 로컬 포트 확인, 셸 환경 변수 설정, 규칙 점검, 연결 테스트 순서로 문제를 분리합니다.

1단계: Clash의 로컬 프록시 포트 확인

먼저 Clash Verge, Clash Verge Rev, Mihomo 계열 클라이언트에서 현재 로컬 프록시 포트를 확인하세요. 메뉴 이름은 클라이언트마다 다르지만 보통 General, Settings, 포트 또는 외부 컨트롤 주변에서 찾을 수 있습니다. 일반적인 주소는 127.0.0.1이며, HTTP와 SOCKS5를 함께 처리하는 mixed-port가 7890으로 설정된 경우가 많습니다. 하지만 포트 번호를 추측하지 말고 실제 화면에 표시된 값을 기준으로 해야 합니다.

9090과 같은 외부 컨트롤 포트를 터미널 프록시 주소로 잘못 입력하면 Claude Code가 연결되지 않습니다. 프록시 포트와 API 포트는 역할이 다르므로 구분하세요. 또한 다른 VPN, 네트워크 가속기, 개발용 프록시가 같은 포트를 사용하고 있으면 Clash가 시작되지 않거나 요청이 엉뚱한 프로그램으로 전달될 수 있습니다.

2단계: 터미널에 HTTP와 SOCKS5 프록시 연결

Claude Code를 실행하는 셸에 프록시 환경 변수를 설정하면 대부분의 명령줄 도구가 같은 연결을 재사용할 수 있습니다. mixed-port가 HTTP 프록시도 지원한다면 아래처럼 설정합니다. 포트가 다르면 자신의 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

macOS와 Linux에서 위 명령은 현재 터미널 세션에만 적용됩니다. 매번 입력하기 번거롭다면 사용하는 셸에 맞춰 ~/.zshrc 또는 ~/.bashrc에 추가한 뒤 새 터미널을 열거나 source ~/.zshrc를 실행하세요. Windows PowerShell에서는 다음과 같이 현재 세션의 환경 변수를 설정할 수 있습니다.

$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"

모든 프로그램이 모든 변수를 동일하게 해석하는 것은 아닙니다. curl과 많은 패키지 도구는 HTTP_PROXY와 HTTPS_PROXY를 잘 따르지만, 일부 Node.js 프로그램이나 Git 설정은 자체 옵션을 우선할 수 있습니다. Git에만 프록시를 적용하려면 다음처럼 별도로 설정할 수 있습니다.

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

반대로 회사 저장소나 로컬 개발 서버가 프록시를 거치면 안 되는 경우에는 NO_PROXY에 도메인과 주소를 추가하세요. 예를 들어 사설 Git 서버가 git.internal.example이라면 NO_PROXY=localhost,127.0.0.1,git.internal.example처럼 구성할 수 있습니다. 불필요하게 전체 환경을 바꾸기보다 프로젝트별 실행 스크립트로 프록시 변수를 관리하면 협업 환경에서 설정 차이도 줄어듭니다.

3단계: Claude 관련 도메인과 개발 트래픽 라우팅

터미널 프록시를 켰는데도 로그인 또는 모델 호출이 실패한다면 Clash의 규칙이 요청을 직접 연결로 보내고 있을 가능성이 있습니다. 규칙 모드에서는 도메인, IP, 프로세스, 지역 정보에 따라 연결 방식이 결정됩니다. Claude Code가 사용하는 모든 호스트를 임의로 추측하기보다는 Clash의 Connections와 Logs 화면에서 실제 요청 도메인을 확인한 뒤 필요한 범위만 추가하는 방식이 안전합니다.

일반적으로는 AI 서비스 도메인, 인증에 사용되는 도메인, 패키지 저장소, Git 호스트가 각각 다른 규칙에 걸릴 수 있습니다. 한 도메인만 프록시로 보내고 인증 도메인을 직접 연결하면 로그인은 되지만 토큰 검증이나 모델 호출에서 다시 실패할 수 있습니다. 반대로 npm 레지스트리나 사내 Git까지 전부 프록시로 보내면 속도가 느려지거나 접근 정책에 걸릴 수 있으므로 서비스별 목적을 나누어 생각해야 합니다.

설정 파일을 직접 편집한다면 규칙의 순서가 중요합니다. 위에 있는 규칙이 먼저 적용되므로 넓은 MATCH,DIRECT 규칙을 너무 일찍 배치하면 뒤에 추가한 프록시 규칙이 실행되지 않습니다. 도메인 전용 규칙을 먼저 두고 마지막에 기본 동작을 배치하는 것이 일반적입니다.

rules:
  - DOMAIN-SUFFIX,example-ai.com,PROXY
  - DOMAIN-SUFFIX,github.com,PROXY
  - DOMAIN-SUFFIX,npmjs.org,DIRECT
  - DOMAIN-SUFFIX,internal.example,DIRECT
  - MATCH,DIRECT

위 주소는 구조를 설명하기 위한 예시이므로 실제 서비스 도메인으로 대체해야 합니다. 구독 프로파일이 자동으로 규칙을 관리한다면 로컬 YAML을 무작정 덮어쓰기보다 제공업체의 규칙 그룹, 모듈, 또는 로컬 오버라이드 기능을 사용하는 편이 업데이트 충돌을 줄입니다.

4단계: 연결 테스트와 오류 해결

Claude Code 자체부터 반복 실행하기보다 작은 테스트를 먼저 진행하세요. 프록시를 명시한 curl 요청이 성공하면 Clash 포트와 기본적인 외부 연결은 정상일 가능성이 높습니다. 이후 같은 셸에서 Claude Code를 실행해 애플리케이션 계층의 문제인지 규칙 계층의 문제인지 좁힐 수 있습니다.

curl -I -x http://127.0.0.1:7890 https://example.com
curl --proxy socks5h://127.0.0.1:7891 https://example.com
env | grep -i proxy

첫 번째 테스트는 HTTP 프록시를 사용하고, 두 번째 테스트의 socks5h는 DNS 해석까지 SOCKS 프록시 쪽에서 수행하도록 요청합니다. SOCKS5는 연결되지만 일반 HTTP 프록시가 실패한다면 포트 종류를 잘못 선택했거나 애플리케이션이 프록시 인증 방식을 다르게 처리하는 상황을 의심할 수 있습니다. 두 테스트 모두 실패하면 노드 상태, Clash 프로파일, 로컬 방화벽, 포트 점유부터 확인하세요.

• Connection refused: Clash가 실행되지 않았거나 주소·포트가 잘못되었을 가능성이 큽니다.
• Timeout: 선택한 노드가 불안정하거나 해당 도메인이 현재 규칙에서 잘못된 경로로 나갔을 수 있습니다.
• 407 Proxy Authentication Required: 로컬 포트가 인증을 요구하는지, URL에 사용자 정보가 필요한지 확인합니다.
• SSL 또는 인증 오류: 시스템 시간이 틀렸거나 중간 인증서 검사, 패키지의 인증서 저장소 설정이 원인일 수 있습니다.
• 로그인은 되지만 모델 호출 실패: 인증 호스트와 API 호스트가 서로 다른 규칙을 적용받는지 확인합니다.
• 패키지 설치만 실패: npm, pip, pnpm의 자체 프록시 설정과 인증서 정책이 셸 환경 변수와 일치하는지 살펴봅니다.

다른 터미널 창에서 실행한 Claude Code가 설정을 인식하지 못한다면 셸 초기화 파일이 실제 실행 환경에 적용됐는지 확인하세요. IDE 내장 터미널, 원격 SSH 세션, Dev Container, WSL은 서로 다른 운영체제와 환경 변수를 사용할 수 있습니다. 호스트의 127.0.0.1이 컨테이너 내부에서는 컨테이너 자신을 가리킬 수도 있으므로, 컨테이너에서 Clash를 사용하려면 호스트 게이트웨이 주소, 네트워크 모드, 방화벽 허용 범위를 별도로 점검해야 합니다.

브라우저 중심의 프록시 도구는 터미널 프로세스나 컨테이너의 요청을 놓치기 쉽고, 단순 VPN은 국내외 트래픽을 세밀하게 나누기 어렵습니다. Clash는 로컬 HTTP·SOCKS5 포트, 규칙 기반 라우팅, 실시간 연결 로그, TUN 모드를 함께 제공해 Claude Code와 Git·패키지 매니저를 한 흐름에서 관리할 수 있습니다. 터미널 개발 환경을 안정적으로 정리하고 싶다면 자신의 플랫폼에 맞는 Clash 다운로드 후, 이 글의 포트 확인과 최소 규칙 설정부터 적용해 보세요.