Claude Code 연결 오류 해결, Clash Verge로 터미널 프록시 설정하기

먼저 오류가 발생하는 단계 구분하기

Claude Code가 터미널에서 로그인되지 않거나 요청 도중 연결이 끊긴다고 해서 곧바로 구독이나 Clash 설정을 초기화할 필요는 없습니다. 터미널 프로그램은 Clash Verge의 시스템 프록시 설정을 자동으로 따르지 않을 수 있습니다. 브라우저는 열리는데 Claude Code만 연결되지 않는다면, 터미널 프로세스에 프록시 환경 변수가 전달됐는지부터 확인하세요.

문제는 크게 세 단계로 나눠 볼 수 있습니다. 첫째는 로컬 프록시 포트에 연결하는 단계, 둘째는 Clash 규칙이 Claude 서비스 연결을 올바른 정책으로 보내는 단계, 셋째는 서비스 인증과 API 응답 단계입니다. 오류 메시지와 발생 시점을 기록하면 불필요하게 DNS, 노드, 로그인 정보를 한꺼번에 바꾸지 않아도 됩니다.

Clash Verge에서 현재 선택한 프로필과 커널이 실행 중인지 확인합니다. 시스템 프록시가 켜져 있는지만 보지 말고, 커널 상태와 현재 HTTP 또는 혼합 포트도 확인하세요.
터미널에서 Claude Code를 실행한 뒤 접속이 실패하는 시각을 기록합니다. 가능하면 실패 직후 Clash Verge의 로그에서 같은 시각의 연결 기록을 확인하세요.
오류가 로컬 주소의 연결 거부인지, 원격 연결 시간 초과인지, 인증 거부인지 구분합니다. 각각 확인해야 할 설정이 다릅니다.

Clash Verge에서 터미널용 프록시 포트 확인하기

Clash Verge에서 프로필을 불러오고 커널이 정상 실행 중인지 확인한 다음 설정 화면에서 포트 값을 찾으세요. HTTP 프록시 포트 또는 혼합 포트가 터미널에서 사용할 주소입니다. 설치 상태나 설정에 따라 값이 다를 수 있으므로 7890이나 7897을 그대로 복사하지 말고, 현재 화면에 표시된 포트를 기준으로 하세요. 예를 들어 혼합 포트가 7897이고 로컬에서 수신 중이라면 주소는 127.0.0.1:7897입니다.

혼합 포트는 보통 HTTP와 SOCKS 프록시 요청을 함께 받지만, 환경 변수에 지정할 때는 HTTP 프록시 형식인 http://를 사용하는 구성이 일반적입니다. HTTPS 연결도 HTTP 프록시를 통해 CONNECT 방식으로 전달할 수 있습니다. 여기서 https://를 무조건 붙이는 것이 아니라, 실제 프록시 서버가 TLS 연결을 제공하는지에 맞춰 주소 형식을 선택해야 합니다.

http://127.0.0.1:7897

위 주소는 예시입니다. Clash Verge에서 포트를 변경했다면 예시의 숫자도 함께 바꾸세요. 로그에 connect: connection refused와 함께 127.0.0.1 주소가 나오면 원격 서비스보다 로컬 포트가 열려 있는지 먼저 점검해야 합니다. 커널이 중지됐거나 포트 번호가 틀렸거나, 다른 애플리케이션이 포트를 점유했을 수 있습니다.

시스템 프록시 설정은 주로 운영체제 프록시 설정을 이용하는 앱에 적용됩니다. 터미널에서 실행한 CLI가 그 설정을 자동으로 읽는다고 보장할 수 없으므로, 환경 변수로 프록시를 명시하는 편이 진단에 유용합니다. 프록시를 직접 설정하는 경우 시스템 프록시를 함께 켜도 되지만, 두 설정은 별개라는 점을 기억하세요.

터미널에 HTTP_PROXY와 HTTPS_PROXY 설정하기

환경 변수는 Claude Code를 실행하는 터미널 세션에 적용됩니다. 아래 예시는 포트가 7897인 경우입니다. 포트가 다르면 두 주소를 모두 현재 포트로 바꾸세요. 변수 이름은 일부 프로그램이나 실행 환경에서 대문자와 소문자를 다르게 처리할 수 있어 대소문자 두 형식을 함께 지정하는 방식이 호환성 점검에 도움이 됩니다.

macOS와 Linux

현재 터미널 창에만 적용하려면 다음 명령을 실행하고, 같은 창에서 Claude Code를 시작합니다.

export HTTP_PROXY=http://127.0.0.1:7897
export HTTPS_PROXY=http://127.0.0.1:7897
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
claude

이 설정은 현재 셸 세션에만 유효합니다. 새 터미널을 열면 다시 설정해야 합니다. 매번 설정하는 것이 번거롭다면 사용 중인 셸의 시작 파일에 넣을 수 있지만, 공용 컴퓨터에서는 프록시 설정을 영구 저장하기 전에 보안과 네트워크 정책을 확인하세요. 테스트가 끝난 뒤 현재 세션의 변수만 지우려면 다음과 같이 실행합니다.

unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy

Windows PowerShell

PowerShell에서는 다음처럼 설정한 뒤 같은 창에서 Claude Code를 실행하세요.

$env:HTTP_PROXY = "http://127.0.0.1:7897"
$env:HTTPS_PROXY = "http://127.0.0.1:7897"
$env:http_proxy = $env:HTTP_PROXY
$env:https_proxy = $env:HTTPS_PROXY
claude

PowerShell 창을 닫으면 이 환경 변수는 해당 세션에서 사라집니다. Windows 명령 프롬프트를 사용한다면 문법이 다르므로 PowerShell 명령을 그대로 붙여 넣지 마세요. Claude Code를 IDE, 작업 스케줄러 또는 다른 앱에서 실행한다면 그 실행 환경에도 변수가 전달되는지 확인해야 합니다. 터미널에서 성공했지만 IDE 내 터미널에서 실패한다면 IDE를 완전히 종료한 뒤 다시 열어 환경 변수를 새로 읽게 하세요.

규칙 모드에서 Claude 연결 경로 확인하기

Clash Verge의 모드가 규칙(Rule)이라면 Claude Code의 요청도 설정의 규칙 순서에 따라 처리됩니다. 시스템 프록시 또는 환경 변수를 설정했다고 해서 모든 도메인이 자동으로 프록시 노드로 가는 것은 아닙니다. 규칙이 해당 도메인을 DIRECT로 보내거나, 의도하지 않은 정책 그룹으로 보내면 연결 결과가 달라질 수 있습니다.

아래는 기존 규칙에 도메인 예외를 추가하는 형태의 예시입니다. PROXY는 모든 설정에 존재하는 고정 이름이 아닙니다. 실제 설정에 있는 프록시 정책 그룹 이름으로 바꾸세요. 이미 다른 곳에 rules: 목록이 있다면 새 rules: 키를 만들지 말고 기존 목록의 적절한 위치에 항목을 병합해야 합니다.

rules:
  - DOMAIN-SUFFIX,anthropic.com,PROXY
  - DOMAIN-SUFFIX,claude.ai,PROXY
  - MATCH,DIRECT

이 규칙은 예시일 뿐이며, 실제 연결에 필요한 도메인은 서비스의 현재 요구 사항이나 연결 로그에 따라 달라질 수 있습니다. 특히 MATCH는 뒤에 오는 규칙을 모두 포괄하므로 항상 목록 마지막에 두세요. 위 예시의 기본 출구가 DIRECT인 것도 모든 환경에 맞는다는 뜻은 아닙니다. 기존 설정의 마지막 규칙을 보존하고, Claude 관련 예외만 실제 프록시 그룹으로 전달하도록 수정하세요.

규칙 모드에서 연결 기록을 확인할 때는 요청 도메인, 매칭된 규칙, 선택된 정책 그룹과 실제 출구를 함께 보세요. 그룹 이름이 프록시를 뜻하는 것처럼 보여도 그룹 안에서 DIRECT가 선택돼 있을 수 있습니다. 반대로 연결 기록에 원하는 노드가 표시되더라도 원격 서버 연결이나 인증이 성공했다는 뜻은 아닙니다.

오류 메시지별로 원인 좁히기

환경 변수를 설정한 뒤에도 실패하면 모든 항목을 한꺼번에 바꾸기보다 한 단계씩 확인하세요. 터미널에서 요청이 Clash로 들어오는지, 규칙이 어떤 출구를 선택하는지, 마지막으로 Claude Code 인증이 유효한지 순서대로 점검하면 원인을 좁힐 수 있습니다.

오류 단서	먼저 확인할 항목	다음 조치
`127.0.0.1:7897 connection refused`	커널 실행 상태와 프록시 포트	Clash Verge에 표시된 현재 포트로 환경 변수를 수정하세요
`i/o timeout` 또는 요청 시간 초과	규칙 매칭, 선택한 노드, 네트워크 상태	로그에서 실제 출구를 확인하고 다른 정상 노드 하나로 비교하세요
`407 Proxy Authentication Required`	프록시가 인증을 요구하는지 여부	주소에 임의의 사용자 이름이나 비밀번호를 넣지 말고 프록시 설정을 확인하세요
`401` 또는 로그인 오류	Claude Code 계정 인증과 로그인 세션	프록시 연결 성공 여부와 별도로 로그인 상태를 확인하세요
인증서 또는 TLS 오류	시스템 시간, TLS 검사, 신뢰할 수 있는 인증서	인증서 검증을 끄지 말고 네트워크 관리자나 서비스 제공 측 설정을 확인하세요

네트워크 경로만 확인하려면 인증 정보를 넣지 않은 요청으로 프록시 포트가 동작하는지 시험할 수 있습니다. 예를 들어 다음 명령은 연결 응답을 확인하는 용도입니다. 서비스가 인증을 요구하면 401, 404 같은 HTTP 상태가 반환될 수 있으며, 그것만으로 프록시 연결이 실패했다고 단정하지 마세요.

curl -I -x http://127.0.0.1:7897 https://api.anthropic.com

명령이 로컬 프록시 연결 단계에서 실패하면 포트 또는 커널부터 고치세요. 응답이 돌아오지만 Claude Code만 로그인되지 않는다면 Claude Code의 로그인 세션과 계정 상태를 확인합니다. 인증 헤더나 API 키를 명령줄에 직접 넣어 테스트하지 마세요. 터미널 기록이나 프로세스 정보에 민감한 값이 남을 수 있습니다.

환경 변수 이름이나 전달 여부를 확인할 때도 값을 통째로 출력해 화면을 공유하지 마세요. 프록시 주소가 로컬 주소더라도 인증 정보가 주소에 포함될 수 있습니다. 현재 프록시 설정을 바꾸기 전에 기존 환경 변수와 Clash 프로필을 기록해 두고, 한 번에 하나씩 수정하면 되돌리기 쉽습니다.

자주 묻는 질문

시스템 프록시를 켰는데 브라우저만 되고 Claude Code는 실패합니다

브라우저가 운영체제 프록시 설정을 따르더라도 터미널에서 실행한 CLI는 해당 설정을 읽지 않을 수 있습니다. 같은 터미널 세션에 HTTP_PROXY와 HTTPS_PROXY를 설정한 다음 Claude Code를 실행하세요. 터미널에서만 성공한다면 IDE나 다른 실행 앱에 환경 변수가 전달되지 않는 문제일 수 있습니다.

HTTPS_PROXY에도 https 주소를 써야 하나요?

꼭 그렇지는 않습니다. HTTPS_PROXY는 HTTPS 대상 요청에 적용할 프록시를 가리키는 환경 변수이며, 값은 흔히 로컬 HTTP 프록시를 나타내는 http://127.0.0.1:포트 형식입니다. 프록시 자체가 TLS 연결을 제공하는 환경이 아니라면 임의로 https://로 바꾸지 마세요.

규칙 모드와 전역 모드 중 무엇을 사용해야 하나요?

일반적인 도메인별 분기를 유지하려면 규칙 모드에서 필요한 연결만 올바른 프록시 그룹으로 보내는 구성이 적합합니다. 전역 모드는 모든 요청의 처리 경로를 바꾸므로 진단을 위한 짧은 비교에는 쓸 수 있지만, 규칙 설정이 정상인지 확인하는 최종 방법은 아닙니다. 테스트 뒤에는 원래 모드로 복구하세요.

프록시 연결은 성공했는데 로그인만 실패합니다

프록시 연결 성공은 계정 인증 성공을 보장하지 않습니다. Claude Code의 로그인 세션, 브라우저 인증 완료 여부, 계정 접근 상태를 별도로 확인하세요. 문제가 계속되면 오류 시각과 민감 정보를 가린 오류 문구를 기록하고, 토큰이나 구독 URL을 공개하지 않은 상태로 지원 절차를 진행하세요.

핵심은 Clash Verge의 시스템 프록시와 터미널 환경 변수를 같은 설정으로 취급하지 않는 것입니다. 먼저 실제 포트를 확인하고 터미널에 프록시 변수를 지정한 뒤, 규칙 로그에서 Claude 연결이 의도한 그룹과 노드를 사용하는지 점검하세요. 인증 오류는 네트워크 오류와 분리해 확인하면 불필요한 설정 변경을 줄일 수 있습니다.