Claude Code 터미널 연결 오류, Clash 프록시 설정으로 점검하는 방법
Claude Code 설정과 Clash 설정을 구분하기
Claude Code가 터미널에서 연결되지 않을 때는 먼저 어느 단계에서 문제가 발생하는지 나누어 확인하세요. Clash는 로컬 프록시 포트를 열고 규칙에 따라 연결을 전달하는 역할을 합니다. Claude Code는 터미널 환경 변수나 실행 환경에서 프록시 주소를 읽어 네트워크 요청을 보냅니다. 따라서 Clash에서 시스템 프록시를 켰다고 해서 모든 터미널 프로그램이 자동으로 해당 프록시를 사용하는 것은 아닙니다.
특히 브라우저 로그인이 성공했는데 Claude Code만 실패한다면 브라우저와 터미널의 네트워크 경로가 다를 수 있습니다. 브라우저가 운영체제 프록시를 따르더라도 셸에서 실행한 Node.js 프로그램은 별도 프록시 설정이 필요할 수 있습니다. 반대로 Claude Code가 로그인 과정에서 브라우저를 열었다면, 브라우저 인증은 성공했지만 터미널의 후속 API 연결은 실패하는 상황도 가능합니다.
먼저 Clash 클라이언트에서 실제 실행 중인 코어가 정상인지 확인하고, 현재 사용 중인 로컬 HTTP 또는 혼합 프록시 포트를 확인하세요. 많은 설정에서 포트가 7890이지만, 클라이언트 설정이나 구독 프로필에 따라 다를 수 있으므로 숫자를 그대로 가정하면 안 됩니다. 또한 구독 YAML을 직접 수정하기 전에 어떤 설정이 구독에서 내려오고 어떤 항목이 클라이언트 오버라이드인지 확인하세요. 구독 업데이트로 직접 수정한 값이 덮어써질 수 있습니다.
Clash 프록시 포트와 연결 상태 확인
Clash의 설정 화면에서 HTTP 포트 또는 mixed-port를 확인합니다. 혼합 포트는 HTTP 프록시와 SOCKS 프록시 요청을 하나의 포트에서 받도록 구성할 수 있지만, 환경 변수에는 일반적으로 HTTP 프록시 주소를 지정하는 편이 호환성 확인에 유용합니다. 다음 예시에서 7890은 예시 포트이므로 실제 클라이언트에 표시된 번호로 바꾸세요.
mixed-port: 7890
allow-lan: false
mode: rule
설정 파일에 포트 번호가 적혀 있어도 해당 포트가 실제로 열려 있다는 뜻은 아닙니다. 코어가 시작되지 않았거나 다른 프로그램이 포트를 선점했을 수 있습니다. 운영체제별 명령으로 리스닝 상태를 확인할 수 있습니다.
netstat -ano | findstr 7890
lsof -nP -iTCP:7890 -sTCP:LISTEN
ss -lntp | grep 7890
Windows에서는 첫 번째 명령을 PowerShell 또는 명령 프롬프트에서 실행할 수 있고, macOS에서는 두 번째 명령, Linux에서는 세 번째 명령을 사용할 수 있습니다. 결과가 없으면 Claude Code의 환경 변수를 바꾸기 전에 Clash 코어 상태, 실행 로그, 포트 충돌을 먼저 해결하세요. 연결이 거부되면 대체로 주소나 포트가 틀렸거나 해당 포트에서 프록시가 수신하지 않는 것입니다.
프록시를 명시한 curl 요청으로 로컬 포트와 Clash의 외부 연결을 함께 시험할 수 있습니다.
curl -I -x http://127.0.0.1:7890 https://api.anthropic.com
응답 코드가 인증이 필요한 API 요청을 나타내거나, 경로에 따라 404 또는 405를 반환하더라도 TLS 연결이 성립했다면 네트워크 경로 자체는 열려 있을 수 있습니다. 반면 시간 초과가 발생하면 Clash 연결 기록에서 요청이 보이는지 확인하세요. 기록이 없다면 로컬 포트 주소나 명령 실행 환경을, 기록에 요청이 있지만 연결이 실패한다면 노드와 규칙을 점검합니다.
터미널 세션에 프록시 환경 변수 설정
Claude Code를 실행하는 셸에서 HTTPS_PROXY와 HTTP_PROXY를 설정하세요. 일부 도구는 소문자 변수명을 확인하므로 대문자와 소문자를 함께 지정해 호환성을 확인할 수 있습니다. 다음 설정은 현재 터미널 세션에만 적용되며, 터미널을 닫으면 사라집니다.
# macOS 또는 Linux: bash, zsh
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
claude
PowerShell에서는 같은 터미널 창에서 다음과 같이 설정한 뒤 Claude Code를 실행합니다.
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:http_proxy = $env:HTTP_PROXY
$env:https_proxy = $env:HTTPS_PROXY
claude
변수를 영구 저장하기 전에 임시 세션에서 먼저 시험하는 것이 좋습니다. 영구 환경 변수로 설정하면 다른 개발 도구나 내부 서비스 요청까지 같은 프록시를 통과할 수 있습니다. 또한 이미 열려 있던 터미널이나 IDE는 환경 변수를 자동으로 다시 읽지 않을 수 있습니다. VS Code 같은 편집기 내장 터미널에서 Claude Code를 실행한다면 편집기를 완전히 종료하고 다시 연 뒤 확인하세요.
현재 셸에 변수가 반영되었는지는 아래 명령으로 확인합니다. 출력된 프록시 주소에 사용자 이름이나 비밀번호가 포함되어 있다면 로그나 화면을 공유할 때 값을 가리세요.
echo "$HTTPS_PROXY"
printf '%s\n' "$HTTPS_PROXY"
규칙 모드와 대상 도메인의 라우팅 확인
환경 변수를 올바르게 설정했는데도 연결되지 않는다면 Clash의 연결 기록을 확인합니다. Claude Code를 실행한 직후 기록을 새로고침하고, 요청이 나타나는지, 어떤 규칙과 정책 그룹을 거쳤는지 살펴보세요. 요청이 DIRECT로 처리되거나 예상과 다른 그룹에 배정되면 현재 모드가 규칙 모드인지 확인하고, 규칙 목록에서 대상 도메인과 적용 순서를 점검합니다.
규칙은 일반적으로 위에서 아래로 검사되며 처음 일치한 규칙이 적용됩니다. 넓은 범위의 직접 연결 규칙이 구체적인 프록시 규칙보다 위에 있으면 뒤쪽 규칙은 선택되지 않을 수 있습니다. 반대로 모든 연결을 전역 프록시로 보내도록 바꾸면 문제 원인을 가리거나 필요한 내부 주소까지 우회시킬 수 있습니다. 문제를 확인하는 동안에는 규칙 전체를 무작정 바꾸기보다, 해당 연결의 기록에 표시된 도메인과 최종 정책부터 확인하는 편이 안전합니다.
Claude Code의 인증 및 API 요청은 구성과 기능에 따라 서로 다른 서비스 도메인에 연결될 수 있습니다. 특정 도메인 하나만 허용하는 규칙을 추가할 때는 실제 연결 기록에서 확인한 이름을 기준으로 하세요. 추측한 도메인을 규칙에 넣으면 로그인은 되지만 다른 요청이 실패하거나, 서비스 변경 후 다시 연결이 끊길 수 있습니다. 규칙을 수정했다면 구독 갱신이나 설정 재로드 후에도 사용자 지정 규칙이 유지되는지 확인해야 합니다.
시스템 프록시와 터미널 환경 변수, TUN을 동시에 켜 두면 동일한 연결이 어떤 경로를 거치는지 혼란스러울 수 있습니다. 처음에는 터미널 변수와 Clash 연결 기록으로 명시적인 경로를 확인한 다음, 필요할 때만 시스템 프록시나 TUN을 별도로 시험하세요. TUN은 애플리케이션이 프록시 변수를 지원하지 않을 때 유용할 수 있지만, 관리자 권한, 가상 네트워크 인터페이스와 DNS 동작에 영향을 받으므로 단순한 터미널 프록시 테스트의 필수 조건은 아닙니다.
DNS, 인증 흐름과 오류 메시지 점검
도메인 조회 문제와 프록시 연결 문제를 구분하려면 프록시를 명시한 curl 테스트와 Clash의 DNS 및 연결 로그를 함께 봅니다. SOCKS 프록시를 사용할 수 있는 환경에서는 socks5h처럼 프록시 측에서 도메인을 조회하도록 요청하는 방식도 비교에 도움이 됩니다. 다만 Claude Code 자체가 특정 SOCKS 설정을 지원한다고 가정하지 말고, 우선 HTTP 프록시 환경 변수로 동작을 확인하세요.
curl -I --proxy socks5h://127.0.0.1:7891 https://api.anthropic.com
socks5h 요청은 SOCKS 포트가 실제로 설정된 경우에만 사용합니다. HTTP 요청은 성공하지만 도메인 이름 오류가 반복되면 Clash DNS 설정, 로컬 DNS와 규칙의 도메인 매칭을 확인하세요. 반대로 DNS 조회는 되지만 TLS 연결에서 멈춘다면 노드 연결, 시간 설정, 인증서 검사 도구 또는 네트워크 중간 장비의 영향을 살펴볼 필요가 있습니다.
로그인 실패는 네트워크 외의 원인도 포함할 수 있습니다. 터미널에 표시된 오류가 타임아웃인지, 연결 거부인지, HTTP 인증 오류인지 확인하고, 브라우저 인증을 사용했다면 브라우저가 완료 화면을 표시한 뒤에도 터미널로 돌아와 후속 절차를 끝냈는지 확인하세요. 터미널과 브라우저가 서로 다른 프록시를 사용하는 경우 인증 단계가 중간에 끊길 수 있으므로, 테스트 중에는 두 경로와 Clash 연결 기록을 비교합니다.
재현 가능한 순서로 원인 좁히기
설정을 여러 군데 동시에 바꾸면 어떤 변경이 효과가 있었는지 알기 어렵습니다. 아래 순서대로 한 단계씩 확인하고, 각 단계의 결과를 기록하면 문제를 더 빠르게 좁힐 수 있습니다.
- Clash 코어를 확인합니다. 클라이언트에서 코어가 실행 중인지, 적용 설정과 로컬 HTTP 또는 혼합 포트 번호가 무엇인지 확인합니다.
- 포트 연결을 시험합니다. 리스닝 상태를 확인한 뒤 curl에 프록시 주소를 명시해 API 도메인에 연결하고, 실패 종류를 기록합니다.
- 셸 환경 변수를 설정합니다. Claude Code를 실제로 실행하는 터미널에서
HTTP_PROXY와HTTPS_PROXY를 지정하고 같은 셸에서 실행합니다. - Clash 연결 기록을 비교합니다. 요청이 기록되는지, 어떤 규칙과 정책 그룹이 선택되는지 확인하고 직접 연결이나 차단 여부를 살핍니다.
- DNS와 인증 단계를 분리합니다. 도메인 조회 실패, TLS 연결 실패, 로그인 오류를 같은 문제로 취급하지 말고 오류 문구와 로그 시점을 비교합니다.
- 마지막에 영구 설정을 적용합니다. 임시 세션에서 해결이 확인된 뒤 셸 시작 파일이나 운영체제 환경 변수에 필요한 값만 저장합니다.
정상화된 뒤에도 Claude Code가 시작될 때마다 실패한다면 터미널이 다른 포트를 가리키는지, IDE가 오래된 환경 변수를 유지하는지, 셸 시작 파일에서 변수가 덮어써지는지 확인하세요. 구독 업데이트 후에만 문제가 생긴다면 프록시 포트 변경이나 규칙 병합 위치도 비교해야 합니다. 원인을 확인한 뒤에는 디버그 로그를 끄고 임시 환경 변수와 불필요한 규칙을 정리해 평소 설정을 단순하게 유지하는 것이 좋습니다.