문제 해결 예상 읽기 시간 15분

Claude Code 접속 오류 해결을 위한 Clash Verge 터미널 설정 가이드

터미널에서 Claude Code를 실행할 때 로그인 실패나 요청 시간 초과가 발생하나요? Clash Verge 프로필 가져오기부터 프록시 모드와 규칙 확인, DNS 및 셸 환경 변수 점검까지 연결 문제를 해결하는 기본 절차를 안내합니다. 실제 이용 가능 여부는 서비스 제공 지역,…

로그인 오류와 터미널 프록시 문제를 먼저 구분하세요

Claude Code가 로그인되지 않거나 요청 도중 끊긴다면 Clash Verge의 연결 상태만 보지 말고, 터미널 프로세스가 실제로 프록시를 사용하는지 확인하세요. Clash Verge에서 시스템 프록시를 켜도 모든 터미널 명령에 프록시가 적용되는 것은 아닙니다. macOS와 Linux의 셸, Windows PowerShell에서 실행한 CLI는 셸 환경 변수나 앱의 프록시 설정을 따를 수 있습니다.

먼저 오류가 발생하는 단계를 구분합니다. 브라우저 로그인 창이 열리지 않는 문제, 로그인 후 인증이 완료되지 않는 문제, 프롬프트를 보낸 뒤 응답이 끊기는 문제는 원인이 다를 수 있습니다. 같은 시각에 Clash Verge의 연결 목록과 로그에서 요청이 보이는지 확인하고, 오류 문구와 발생 시각을 기록하세요. 로그나 화면을 공유할 때는 구독 주소, 인증 코드, API 키, 로그인 토큰을 반드시 가려야 합니다.

증상 우선 확인할 항목 주의할 점
브라우저 로그인 페이지가 열리지 않음 터미널에서 프록시를 지정했는지, 로그인 URL에 접속되는지 시스템 프록시가 켜졌다는 사실만으로 CLI 적용을 단정하지 않기
로그인 창은 열리지만 인증 완료가 되지 않음 브라우저와 터미널의 네트워크 경로, 로컬 콜백 연결 브라우저만 프록시를 사용하거나 다른 네트워크로 나갈 수 있음
요청이 시간 초과되거나 중간에 끊김 선택한 노드, 프록시 포트, 연결 로그, 셸 변수 짧은 지연 시간 테스트 결과만으로 지속 안정성을 판단하지 않기
인증은 되었지만 API 오류가 표시됨 오류 코드, 계정 권한, 사용량 및 서비스 상태 모든 API 오류를 네트워크 문제로 간주하지 않기

여러 설정을 한꺼번에 바꾸면 원인을 찾기 어렵습니다. 현재 프로필과 선택 노드, Clash Verge 모드, 터미널에 지정된 프록시 주소를 기록해 두고 한 번에 한 항목씩 변경하세요. 클라이언트 메뉴명은 버전에 따라 달라질 수 있으므로 화면에서 현재 적용 중인 설정과 포트를 기준으로 확인합니다.

프로필·모드·규칙·포트 확인

먼저 Clash Verge가 실행 중이며 사용할 프로필이 선택되어 있는지 확인합니다. 구독 프로필을 갱신한 직후라면 노드 목록과 정책 그룹이 정상적으로 표시되는지도 살펴보세요. 프로필을 선택했더라도 그룹이 비어 있거나 노드가 모두 오류 상태라면 Claude Code가 사용할 수 있는 경로가 없을 수 있습니다.

  • 노드 선택: 현재 정책 그룹에서 실제로 연결 가능한 노드를 선택합니다. 자동 선택 그룹을 쓰는 경우 해당 그룹이 비어 있지 않고, 테스트 URL과 제한 시간이 적절한지도 확인하세요.
  • 프록시 모드: Rule 모드에서는 요청 도메인이 규칙과 정책 그룹에 따라 DIRECT 또는 프록시로 전달됩니다. Global 모드는 진단을 위해 잠시 비교할 수 있지만, 모든 트래픽을 같은 경로로 보내므로 평상시 설정으로 무조건 권장되는 것은 아닙니다.
  • 시스템 프록시와 TUN: 시스템 프록시는 이를 따르는 앱에 적용되고, TUN은 지원되는 환경에서 더 넓은 범위의 트래픽을 처리합니다. 어느 쪽도 터미널이 원하는 노드를 사용 중이라는 증거는 아니므로 연결 로그로 확인하세요.
  • 혼합 포트: 설정 화면이나 실행 중인 프로필에서 HTTP/SOCKS 프록시 포트를 확인합니다. 7890은 흔히 쓰이는 예시일 뿐이며, 실제 포트가 다르면 터미널 변수도 그 값에 맞춰야 합니다.

Clash Verge의 연결 또는 로그 화면에서 로그인과 API 요청 시각을 살펴보세요. 도메인이 기록되고 정책 그룹과 노드가 표시된다면 요청이 코어에 도달한 것입니다. 요청 자체가 보이지 않는다면 터미널 환경 변수, 다른 앱의 프록시 설정, 또는 TUN 경로부터 확인합니다. 요청이 보이지만 DIRECT로 나간다면 Rule 모드에서 해당 도메인에 적용되는 규칙과 정책 그룹을 점검하세요.

터미널에 프록시를 지정해 직접 재현하기

이 절에서는 로컬 HTTP 프록시 포트를 예시로 사용합니다. Clash Verge에서 확인한 실제 포트로 7890을 바꾸세요. 혼합 포트는 보통 HTTP와 SOCKS 연결을 함께 받을 수 있지만, 클라이언트 설정에 따라 다를 수 있습니다. 우선 터미널에서 HTTP 프록시를 명시해 테스트한 뒤 Claude Code를 실행하면 시스템 프록시와 셸 설정을 구분하는 데 도움이 됩니다.

macOS 및 Linux 셸

Bash나 Zsh에서 아래 명령을 실행하면 변수는 현재 터미널 세션에만 적용됩니다. 셸 시작 파일에 영구 저장하기 전에 이 방식으로 연결을 확인하세요.

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"

curl -I --connect-timeout 10 \
  --proxy "$HTTPS_PROXY" \
  https://api.anthropic.com/

claude

프록시를 통한 요청이 시간 초과 없이 HTTP 응답을 받으면 터미널에서 프록시 포트까지 연결되고 대상 서버에 도달한 것입니다. API 루트가 401, 404, 405 등을 반환할 수 있으며, 이 결과만으로 인증 성공 여부를 판단할 수는 없습니다. 중요한 것은 DNS 오류, 로컬 연결 거부, TLS 오류, 시간 초과가 발생하는지를 별도로 보는 것입니다. curl 명령이 성공해도 Claude Code의 로그인과 API 호출에 필요한 모든 경로가 정상이라는 뜻은 아닙니다.

Windows PowerShell

PowerShell에서는 현재 창에서 다음과 같이 지정할 수 있습니다. 다른 터미널을 열면 변수가 이어지지 않을 수 있으므로 Claude Code도 같은 창에서 실행하세요.

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:ALL_PROXY = "http://127.0.0.1:7890"

curl.exe -I --connect-timeout 10 `
  --proxy $env:HTTPS_PROXY `
  https://api.anthropic.com/

claude

Windows PowerShell에서 curl은 환경에 따라 별칭으로 해석될 수 있으므로 예시처럼 curl.exe를 사용하면 혼동을 줄일 수 있습니다. 프록시가 SOCKS 전용 포트라면 HTTP 프록시 주소로 적지 말고, 해당 포트가 지원하는 프로토콜을 확인해 클라이언트와 명령 양쪽에 맞춰야 합니다. 프로토콜을 모를 때는 추측으로 포트를 바꾸기보다 Clash Verge의 포트 설정을 먼저 확인하세요.

  1. Clash Verge에서 프로필, 정책 그룹, 노드가 정상인지 확인하고 현재 프록시 포트를 적어 둡니다.
  2. Rule 모드에서 연결 로그를 지켜볼 수 있도록 로그 화면을 엽니다. 필요하면 짧은 진단 동안만 다른 모드와 비교한 뒤 원래 설정으로 되돌립니다.
  3. 새 터미널 창에서 현재 세션에 프록시 환경 변수를 지정하고 curl로 api.anthropic.com 연결을 시험합니다.
  4. 테스트 시각에 Clash Verge 로그에서 요청이 보이는지, DIRECT인지 선택한 프록시 그룹을 통과하는지 확인합니다.
  5. 같은 터미널에서 Claude Code를 실행해 로그인 또는 요청을 재현하고, 성공 여부와 오류 시각을 기록합니다.

진단이 끝나면 임시 변수를 제거할 수 있습니다. macOS와 Linux에서는 unset HTTP_PROXY HTTPS_PROXY ALL_PROXY, PowerShell에서는 Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:ALL_PROXY를 실행하세요. 매번 사용할 설정이라면 먼저 현재 포트가 고정인지 확인한 후 셸 설정 파일에 기록합니다. 포트를 바꾸었는데 이전 값을 파일에 남겨 두면 나중에 잘못된 프록시 주소로 접속하게 됩니다.

규칙·DNS·로그인 콜백을 따로 점검

Rule 모드에서는 도메인별 규칙이 요청 경로를 결정합니다. API 요청이 로그에 나타나지만 DIRECT로 연결된다면 해당 요청이 프록시를 거치지 않는 이유를 확인하세요. 규칙은 보통 도메인, 도메인 접미사, IP 또는 정책 그룹을 기준으로 적용되며, 터미널에서 실행한 프로세스 이름만으로 모든 요청이 자동 분류되는 것은 아닙니다. 기존 구독 규칙을 충분히 확인하지 않은 채 임의의 규칙을 덧붙이면 다른 서비스의 경로까지 바뀔 수 있습니다.

DNS 문제는 로그에 no such host, 조회 시간 초과와 같은 오류가 있는지 살펴보세요. 프록시 모드와 TUN 모드, 시스템 DNS, 코어의 DNS 설정은 서로 다른 경로를 사용할 수 있습니다. 따라서 브라우저에서 사이트가 열린다는 이유만으로 터미널의 DNS 조회도 정상이라고 볼 수 없습니다. DNS 설정을 바꿀 때는 현재 설정을 기록하고 한 번에 하나만 변경한 뒤 같은 명령으로 재검사하세요.

로그인 과정에서는 브라우저가 인증 페이지를 열고, 인증이 끝난 뒤 로컬 애플리케이션으로 돌아오는 방식이 사용될 수 있습니다. 브라우저는 성공했지만 터미널로 돌아오지 않는다면 브라우저와 CLI가 서로 다른 프록시 경로를 쓰는지, 로컬 콜백 페이지가 열리는지 확인하세요. VPN, 보안 프로그램 또는 다른 프록시 도구가 로컬 연결을 막는 경우도 있으므로, 포트를 임의로 열거나 인증 절차를 우회하기보다 오류 메시지와 연결 기록을 비교하는 편이 안전합니다.

여러 도메인에 대한 요청이 필요할 수 있으므로 api.anthropic.com 한 곳의 테스트만으로 로그인 전체를 검증할 수는 없습니다. 실제 실패 시각에 Clash Verge 로그에서 어떤 도메인이 실패했는지 확인하고, 서비스 제공자가 안내하는 현재 접속 요구 사항과 계정 상태도 함께 살펴보세요. 전체 URL이나 요청 헤더에는 비밀 정보가 포함될 수 있으므로 로그를 외부에 붙여 넣지 마세요.

한 항목씩 비교하고 안전하게 원상 복구하기

원인이 여전히 불분명하면 같은 네트워크에서 짧은 비교 테스트를 진행합니다. 먼저 기존 프로필과 변수 값을 기록한 다음, 노드만 바꾸어 같은 명령을 반복하세요. 다른 노드에서 성공한다면 원래 노드의 연결 상태나 목적지별 경로가 원인일 가능성이 있습니다. 노드를 바꾸어도 실패한다면 포트, 규칙, DNS, 로그인 단계로 범위를 좁힙니다.

  • curl도 로컬 연결을 거부함: Clash Verge가 실행 중인지, 실제 리스닝 포트와 명령의 포트가 같은지 확인합니다.
  • curl이 연결되지만 시간 초과됨: 로그에서 원격 연결 단계와 선택 노드를 확인하고, 다른 노드에서 동일한 요청을 비교합니다.
  • curl은 응답하지만 Claude Code가 실패함: 같은 터미널에서 실행했는지, 로그인 단계의 브라우저 경로와 추가 요청 도메인이 다른지 확인합니다.
  • 인증 이후 권한 또는 사용량 오류가 남음: 네트워크 설정을 계속 변경하기보다 오류 코드, 계정 권한, 사용량 상태를 점검합니다.

원인을 찾은 뒤에는 진단 목적으로 바꾼 Global 모드나 임시 DNS 설정을 원래 상태로 돌리고, 필요한 셸 변수만 유지하세요. 프록시를 쓰지 않는 로컬 주소나 내부 개발 서버에는 NO_PROXY가 필요할 수 있지만, 범위를 지나치게 넓히면 의도한 요청이 프록시를 우회할 수 있습니다. 환경 변수가 셸 설정 파일과 운영체제 설정에 중복 등록되어 있지 않은지도 확인합니다.

마지막으로 Clash Verge의 프로필과 코어가 최신 상태인지 확인하되, 업데이트 전에는 현재 설정을 백업하세요. 클라이언트 업데이트는 코어 버전이나 기본 포트를 바꿀 수 있고, 구독 업데이트는 규칙과 노드 목록을 바꿀 수 있습니다. 설정 변경 전후의 포트, 모드, 노드, 로그 결과를 비교하면 다음 오류가 발생했을 때 같은 점검을 반복하지 않아도 됩니다.

Clash 다운로드