튜토리얼 2026년 9월 26일

Claude Code 터미널 연결 안 될 때 Clash Verge 프록시 설정 방법

Claude Code가 터미널에서 연결되지 않을 때는 앱의 프록시 설정과 셸 환경 변수가 모두 맞는지 살펴봐야 합니다. Clash Verge에서 모드와 라우팅 규칙을 확인하고 연결을 테스트하는 방법을 단계별로 정리해 처음 사용하는 사람도 원인을 좁힐 수 있도록 돕습니다.

공항 선택 Clash 구독 보안 가이드

Claude Code가 연결되지 않을 때 먼저 볼 것

터미널에서 Claude Code를 실행했는데 로그인 화면이 반복되거나, 요청을 보낸 뒤 응답 없이 멈추거나, 연결 오류가 뜬다면 곧바로 노드를 바꾸기보다 어느 단계에서 연결이 끊겼는지부터 나눠 보는 편이 빠릅니다. 브라우저에서 Claude 웹페이지는 열리는데 CLI만 실패한다면 Clash Verge의 전체 연결보다 터미널 프로세스가 프록시를 전달받았는지가 우선 점검 대상입니다. 반대로 브라우저와 터미널이 모두 실패하면 활성 프로필, 모드, 규칙, 프록시 노드 상태를 먼저 확인해야 합니다.

Claude Code는 터미널에서 실행되는 프로그램이므로 브라우저와 같은 방식으로 시스템 프록시를 자동 사용한다고 단정할 수 없습니다. 셸 환경 변수, 실행한 터미널 앱의 환경, Clash Verge의 시스템 프록시 설정, Mihomo 규칙 중 한 곳이라도 맞지 않으면 같은 컴퓨터에서도 브라우저는 되고 CLI는 안 되는 상황이 생길 수 있습니다. 특히 IDE 내장 터미널은 로그인 셸과 다른 환경을 물려받거나, GUI 앱을 연 시점의 환경 변수를 그대로 유지할 수 있습니다.

진단은 다음 순서로 진행하세요. 먼저 Clash Verge가 실행 중이고 노드가 실제로 연결되는지 확인합니다. 다음으로 시스템 프록시 또는 TUN 중 현재 사용하는 경로를 확인하고, 셸의 프록시 주소와 포트가 Clash Verge의 포트와 일치하는지 비교합니다. 마지막으로 Claude Code를 다시 실행하면서 Verge의 연결 로그에서 요청이 보이는지 살펴봅니다. 로그에 요청이 전혀 없다면 규칙을 더 추가하기 전에 터미널 쪽 프록시 전달부터 확인하는 것이 좋습니다.

Clash Verge의 모드와 혼합 포트 확인

Clash Verge를 열어 현재 사용 중인 프로필이 활성 상태인지 확인합니다. 구독 프로필을 편집했더라도 다른 프로필이 활성화되어 있다면 수정한 규칙은 실제 연결에 적용되지 않습니다. 설정을 바꾼 뒤에는 프로필을 다시 적용하거나 코어를 재시작하고, 연결 목록에서 트래픽이 발생하는지 확인하세요. UI 문구는 버전에 따라 조금씩 달라질 수 있지만, 핵심은 편집한 설정과 실행 중인 Mihomo 설정이 같은지입니다.

혼합 포트는 HTTP와 SOCKS 연결을 함께 받을 수 있도록 설정된 로컬 포트입니다. Clash Verge의 설정 화면에서 혼합 포트 또는 프록시 포트 값을 확인하고, 예시 숫자를 그대로 복사하지 말고 현재 표시된 값을 사용하세요. 기본값을 변경했거나 다른 프로그램이 같은 포트를 쓰는 환경에서는 문서의 포트와 실제 포트가 다를 수 있습니다. 포트가 열려 있는지 확인하지 않은 채 환경 변수만 넣으면 CLI는 존재하지 않는 프록시 서버에 연결을 시도하게 됩니다.

터미널에 프록시 환경 변수 설정

시스템 프록시를 켰는데도 CLI만 실패한다면 셸이 읽는 프록시 환경 변수를 확인합니다. macOS와 Linux의 zsh 또는 bash에서는 아래처럼 현재 터미널 세션에 변수를 넣어 시험할 수 있습니다. 7897은 예시이므로 Clash Verge에 표시된 혼합 포트로 바꾸세요. 이 주소는 자신의 컴퓨터에서만 사용하는 로컬 주소이며, 다른 장치의 주소를 임의로 넣으면 안 됩니다.

export HTTP_PROXY=http://127.0.0.1:7897
export HTTPS_PROXY=http://127.0.0.1:7897
export ALL_PROXY=socks5://127.0.0.1:7897

혼합 포트가 HTTP 프록시 요청도 받는 설정이라면 HTTP 및 HTTPS 변수에 해당 포트를 사용할 수 있습니다. SOCKS 연결을 별도로 제공하는 경우에는 Clash Verge에 표시된 SOCKS 포트를 확인하고, 그 포트를 ALL_PROXY에 넣어 시험하세요. 여러 프록시 변수를 한꺼번에 설정했을 때 결과가 달라진다면 하나씩 해제해 원인을 분리합니다. 또한 같은 셸에서 env | grep -i proxy를 실행해 값이 실제로 설정됐는지 확인할 수 있습니다.

Windows PowerShell에서는 현재 세션에 다음과 같이 설정할 수 있습니다. 포트 숫자는 실제 값으로 바꿔야 합니다. 이 명령은 현재 PowerShell 창에만 적용되므로 새 창을 열면 다시 설정해야 할 수 있습니다.

$env:HTTP_PROXY = "http://127.0.0.1:7897"
$env:HTTPS_PROXY = "http://127.0.0.1:7897"
$env:ALL_PROXY = "socks5://127.0.0.1:7897"

Claude Code를 VS Code 같은 IDE의 내장 터미널에서 실행한다면, IDE를 완전히 종료한 뒤 다시 열어 같은 명령을 실행해 보세요. IDE가 Clash Verge보다 먼저 실행되어 이전 환경을 유지하고 있을 수 있습니다. 셸 설정 파일에 변수를 영구 저장하기 전에는 현재 세션에서 성공하는지 먼저 확인하는 것이 안전합니다. 업무용 네트워크에서 프록시 변수를 저장할 때에는 조직의 보안 정책도 확인하세요.

규칙과 연결 로그로 실제 경로 추적

환경 변수 설정 후에도 연결되지 않는다면 Clash Verge의 연결 또는 코어 로그를 열고 Claude Code를 다시 실행합니다. 요청이 나타나면 해당 항목의 도메인, 매칭된 규칙, 최종 프록시 그룹을 확인합니다. 원하는 그룹이 아니라 DIRECT나 다른 그룹으로 연결됐다면 활성 프로필의 규칙 순서와 기본 규칙을 점검하세요. Mihomo 규칙은 위에서부터 평가되므로, 넓은 도메인 규칙이나 최종 규칙이 사용자 지정 줄보다 먼저 요청을 처리하면 아래쪽 규칙은 적용되지 않습니다.

Claude Code가 사용하는 호스트는 기능, 로그인 흐름, 앱 버전에 따라 달라질 수 있습니다. 예를 들어 API 요청과 계정 인증은 같은 호스트로만 처리된다고 가정하지 마세요. api.anthropic.com이나 claude.ai를 참고 출발점으로 삼을 수는 있지만, 모든 환경의 완전한 호스트 목록으로 보아서는 안 됩니다. 실패 시점에 로그에 기록된 실제 호스트를 기준으로 좁혀 가고, 모르는 도메인을 무작정 넓은 키워드 규칙에 넣지 않는 편이 관리하기 쉽습니다.

rules:
  - DOMAIN-SUFFIX,api.anthropic.com,AI-OUT
  - DOMAIN-SUFFIX,claude.ai,AI-OUT
  - MATCH,GLOBAL

위 YAML은 개념 예시입니다. AI-OUT은 실제 프로필에 존재하는 프록시 그룹 이름으로 바꾸고, 규칙은 사용자가 관찰한 연결 로그와 기존 구독 규칙 구조에 맞춰 추가해야 합니다. 구독에서 가져온 규칙 세트를 사용하는 경우에는 사용자 규칙이 그 세트보다 먼저 평가되는지 확인하세요. 또한 모든 Claude 관련 트래픽을 한 줄로 묶기보다, 실제로 실패한 요청만 한 번에 한두 개씩 시험하면 부작용을 줄이고 결과를 비교하기 쉽습니다.

로그에 요청이 보이지 않으면 규칙을 고치는 것만으로는 해결되지 않을 수 있습니다. 터미널이 프록시 환경 변수를 읽는지, 로컬 프록시 포트에 연결할 수 있는지, TUN이 켜져 있다면 다른 네트워크 도구와 충돌하지 않는지 확인하세요. 로그에는 요청이 있지만 연결이 실패한다면 선택한 노드의 상태, DNS 응답, TLS 연결 오류를 차례로 확인합니다. 노드를 바꾸기 전후에 같은 명령으로 시험하고 시각과 결과를 기록하면 원인 비교가 훨씬 쉬워집니다.

연결 테스트와 흔한 오류 대응

먼저 Claude Code를 실행한 것과 같은 터미널에서 프록시 변수 값을 확인하고, Clash Verge의 연결 목록을 함께 엽니다. 그다음 접속이 필요한 주소에 대한 HTTPS 연결을 테스트합니다. 다음 명령은 서버가 특정 경로에 응답하는지 확인하는 용도가 아니라, 프록시를 거친 TLS 연결이 성립하는지 살펴보는 기본 점검입니다. 서버가 인증 없이 API 사용을 허용한다는 뜻은 아니며, 테스트 결과와 Claude Code의 실제 인증 결과는 구분해야 합니다.

curl -Iv https://api.anthropic.com/

curl이 연결되지 않으면 출력에서 프록시 연결 단계, 이름 해석, TLS 핸드셰이크 중 어디에서 멈췄는지 확인합니다. curl은 성공하지만 Claude Code만 실패한다면 실행 프로세스가 다른 환경 변수를 받는지, 앱이 프록시 설정을 지원하는지, Claude Code의 로그인 및 계정 상태가 정상인지 살펴보세요. 응답 코드가 표시되더라도 그 자체만으로 API 인증이나 계정 권한까지 정상이라는 뜻은 아닙니다.

문제를 해결한 뒤에는 임시 전역 모드나 불필요한 환경 변수를 정리하고, 작동한 최소 설정만 남기는 것이 좋습니다. 프록시를 변경해도 계정 접근 정책, 구독 상태, 서비스 장애와 같은 문제는 그대로 남을 수 있습니다. 연결 경로와 계정 상태를 각각 확인하면 네트워크 설정을 반복해서 바꾸는 일을 줄일 수 있습니다.

자주 묻는 질문

Clash Verge에서 시스템 프록시를 켜면 Claude Code도 자동으로 프록시를 사용하나요?
항상 그렇지는 않습니다. 브라우저가 시스템 프록시를 사용하더라도 CLI는 별도의 환경 변수나 네트워크 설정을 요구할 수 있습니다. 같은 터미널에서 프록시 변수를 확인하고 Verge 연결 로그에 요청이 표시되는지 함께 살펴보세요.

HTTP_PROXY와 HTTPS_PROXY에는 어떤 주소를 넣어야 하나요?
Clash Verge 설정에서 현재 사용 중인 혼합 포트 또는 HTTP 포트를 확인해 로컬 주소와 함께 입력합니다. 예시 포트 번호를 그대로 쓰지 말고, 본인의 설정값이 실제로 수신 중인지 먼저 확인하세요.

규칙 모드와 전역 모드 중 무엇을 계속 사용해야 하나요?
전역 모드는 짧은 진단에 유용하지만 모든 연결을 같은 출구로 보내므로 평소 사용에 항상 적합한 것은 아닙니다. 전역 모드에서만 성공한다면 로그로 필요한 호스트와 규칙을 찾은 뒤 규칙 모드에서 다시 확인하는 방법이 유지 관리에 유리합니다.

TUN을 켜야만 해결되는 경우도 있나요?
시스템 프록시와 환경 변수를 읽지 않는 프로그램은 TUN에서 정상화될 수 있습니다. 다만 다른 VPN이나 보안 소프트웨어와 충돌할 수 있으므로, 프록시 변수와 포트 설정을 먼저 확인한 뒤 필요한 경우에만 시험하세요.

일부 CLI 도구는 프록시 설정이 앱 안에만 있거나, 실패한 호스트를 확인할 로그가 제한적이어서 원인을 찾기 어렵습니다. Clash Verge는 모드와 그룹을 전환하고 연결 로그에서 실제 경로를 확인할 수 있어, 브라우저와 터미널의 차이를 단계적으로 좁히는 데 도움이 됩니다. 규칙을 직접 관찰한 도메인에 맞춰 관리하고 싶다면 아래에서 사용 환경에 맞는 클라이언트를 확인할 수 있습니다.

Clash 다운로드하기

지금 설정을 시작해 보세요

Clash Verge에서 프록시와 규칙을 확인하고 터미널 연결을 점검해 보세요.