Claude Code에서 로그인, 코드 분석, 파일 수정 요청이 멈추거나 터미널에 연결 오류가 표시되면 먼저 Clash 노드의 속도만 확인하기보다 터미널이 프록시를 실제로 사용하고 있는지부터 점검해야 합니다. 데스크톱 앱에서 시스템 프록시를 켰더라도 터미널 프로세스가 그 설정을 자동으로 읽는 것은 아닙니다. 이 글에서는 Clash 프로필과 규칙, 터미널 환경 변수, 연결 테스트를 차례로 확인하는 방법을 정리합니다. 메뉴 이름과 지원 기능은 Clash 클라이언트 및 버전에 따라 다를 수 있으며, 서비스 이용 가능 여부와 조건은 지역, 계정 및 네트워크에 따라 달라질 수 있습니다.
먼저 연결 경로와 오류 범위 확인
문제를 해결하기 전에 오류가 발생하는 위치를 좁히세요. 브라우저에서도 관련 서비스가 열리지 않는다면 로컬 네트워크, 프로필 또는 노드 문제일 수 있습니다. 브라우저는 정상인데 Claude Code만 실패한다면 터미널의 프록시 환경 변수, 실행 셸, 또는 Clash 규칙을 우선 확인하는 편이 효율적입니다. 반대로 로그인 화면은 열리지만 요청 전송이나 응답 수신에서 실패한다면 특정 도메인의 분기 규칙, DNS 해석, 연결 시간 제한 등이 관련될 수 있습니다.
오류 메시지는 가능한 한 원문 그대로 기록하고, 발생 시각과 실행한 명령, 사용 중인 Clash 클라이언트, 활성 프로필과 노드를 함께 메모해 두세요. 인증 문제와 네트워크 문제를 구분하는 데 특히 유용합니다. 예를 들어 응답 코드가 표시되면 인증이나 계정 상태를 점검해야 할 수도 있지만, 이름 해석 실패, 연결 거부, 시간 초과라면 네트워크 경로를 먼저 조사할 만합니다. 오류 문구만으로 원인을 단정하지 말고, 같은 조건에서 재현되는지 확인하세요.
Clash 프로필과 분기 규칙 점검
먼저 Clash에서 사용할 프로필이 정상적으로 가져와졌는지 확인하고, 업데이트나 파싱 과정에서 오류가 발생하지 않았는지 살펴봅니다. 프로필이 유효하더라도 선택된 노드가 응답하지 않거나 프록시 그룹이 끊어진 노드를 가리키면 터미널 연결은 실패할 수 있습니다. Clash Verge 또는 Clash Verge Rev에서는 해당 버전의 인터페이스에서 프로필 업데이트 상태와 현재 선택된 그룹·노드를 확인하세요. Mihomo를 사용하는 환경에서는 연결 화면이나 로그에서 목적지와 최종 선택된 규칙 및 프록시 그룹을 살펴보면 도움이 됩니다.
다음으로 Claude Code 요청이 어떤 규칙에 매칭되는지 확인합니다. 도메인 규칙이 있다면 실제 로그에 나타난 목적지와 규칙 목록을 대조하세요. 아래는 구조를 보여 주는 예시이며, Proxy라는 그룹 이름은 사용하는 프로필의 실제 이름으로 바꿔야 합니다. 서비스의 도메인과 연결 방식은 바뀔 수 있으므로 아래 도메인을 모든 환경에 적용되는 완전한 목록으로 간주하지 마세요. 프로필을 수정할 때는 기존 규칙을 덮어쓰지 말고, 현재 설정의 규칙 형식과 그룹 이름에 맞춰 필요한 항목만 추가해야 합니다.
rules: - DOMAIN,api.anthropic.com,Proxy - DOMAIN-SUFFIX,anthropic.com,Proxy # 필요한 경우 실제 로그에서 확인한 도메인만 추가 - MATCH,기존-최종-규칙
이 예시는 기존 rules 목록에 그대로 붙여 넣는 완성 프로필이 아닙니다. 실제 설정에서는 구체적인 규칙을 일반 규칙보다 앞에 두어야 하며, 마지막 규칙은 기존 프로필의 정책을 유지해야 합니다. MATCH는 대개 마지막에 배치되므로 예시의 자리 표시자를 실제 프로필에 그대로 복사하지 마세요. 또한 특정 목적지를 프록시로 보내는 것이 네트워크나 서비스의 정책에 맞는지 확인하고, 필요한 도메인만 대상으로 제한하는 것이 좋습니다.
터미널에 프록시 환경 변수 설정
시스템 프록시 설정과 터미널의 환경 변수는 별개일 수 있습니다. 특히 GUI에서 시작한 앱과 셸에서 실행한 CLI는 서로 다른 환경을 가질 수 있습니다. Clash의 HTTP 혼합 포트 또는 HTTP 포트 번호를 확인한 뒤, 해당 주소를 터미널 환경 변수에 지정하세요. 포트는 클라이언트와 설정에 따라 다르므로 아래의 7890을 그대로 사용하지 말고 Clash 화면이나 설정 파일에서 실제 값을 확인해야 합니다. 로컬에서만 사용하는 프록시라면 일반적으로 루프백 주소를 사용합니다.
| 환경 | 임시 설정 예시 | 확인할 점 |
|---|---|---|
| macOS / Linux 셸 | export HTTPS_PROXY=http://127.0.0.1:7890 | 실제 HTTP 포트와 현재 셸 확인 |
| Windows PowerShell | $env:HTTPS_PROXY="http://127.0.0.1:7890" | 현재 PowerShell 창에만 적용 |
| HTTP 요청도 필요한 경우 | HTTP_PROXY도 같은 주소로 지정 | HTTPS와 HTTP 변수를 각각 확인 |
| 프록시 예외 대상 | NO_PROXY 또는 no_proxy | 불필요한 도메인을 예외 처리하지 않기 |
macOS 또는 Linux에서 현재 셸에 임시로 설정하려면 다음과 같이 입력할 수 있습니다. 7890은 예시 포트이며, 실제 포트로 바꾸세요. 이 방식은 새 터미널 창을 열거나 셸을 다시 시작하면 사라질 수 있습니다.
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" # 설정값 확인 env | grep -i proxy
Windows PowerShell에서는 다음처럼 현재 창에 적용할 수 있습니다. 환경 변수를 설정한 뒤에는 같은 창에서 Claude Code를 실행해야 합니다. 다른 터미널이나 IDE 내장 터미널을 사용한다면 해당 프로세스에도 변수가 전달되는지 별도로 확인하세요.
$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 # 설정값 확인 Get-ChildItem Env:*proxy*
환경 변수를 영구적으로 등록하기 전에 임시 설정으로 동작을 확인하는 것을 권장합니다. 셸 시작 파일이나 시스템 환경 변수에 저장하면 다른 개발 도구까지 프록시를 사용하게 될 수 있습니다. 테스트가 끝난 뒤 변수를 제거하려면 macOS·Linux에서는 unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy, PowerShell에서는 Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:http_proxy, Env:https_proxy를 사용할 수 있습니다. 시스템에 이미 프록시 변수가 지정되어 있다면 값이 예상한 포트와 주소인지 확인하고, 자격 증명이 포함된 URL을 로그나 공개된 설정에 노출하지 마세요.
연결 테스트와 로그 읽기
환경 변수를 지정한 뒤에는 곧바로 장시간 작업을 시작하기보다 작은 요청으로 연결 경로를 확인하세요. 아래 명령은 로컬 포트에서 프록시 연결이 가능한지 살펴보는 예시입니다. 응답 코드나 동작은 네트워크와 대상 서비스의 상태에 따라 달라질 수 있습니다. 이 테스트가 성공해도 Claude Code의 모든 요청이 정상이라는 뜻은 아니며, 반대로 테스트 URL의 응답이 예상과 다르다고 해서 곧바로 Clash 설정 오류라고 단정할 수도 없습니다.
curl -I --proxy http://127.0.0.1:7890 https://api.anthropic.com
테스트가 실패하면 다음 순서로 확인합니다. 첫째, Clash가 실행 중이고 해당 포트에서 HTTP 프록시 연결을 받는지 확인합니다. 둘째, 노드와 프록시 그룹이 실제로 선택되어 있는지 확인합니다. 셋째, Clash 로그에서 요청이 기록되는지 살펴봅니다. 요청이 전혀 보이지 않는다면 터미널 변수가 적용되지 않았거나 다른 실행 환경을 사용하고 있을 가능성이 있습니다. 요청이 기록되지만 연결이 실패한다면 로그에 표시된 규칙, 대상 도메인, 노드 상태를 각각 점검하세요.
- 브라우저 등 다른 앱에서도 같은 목적지 연결이 실패하는지 비교합니다.
- 터미널에서 환경 변수 값과 Clash의 실제 HTTP 포트를 대조합니다.
- Clash 로그에서 해당 요청이 관찰되는지, 어떤 규칙이 선택됐는지 확인합니다.
- 필요하면 다른 정상 노드로 한 번만 바꾸어 결과를 비교한 뒤 원래 설정으로 복구합니다.
- 연결은 되지만 인증 또는 계정 관련 오류가 남으면 네트워크 설정과 별도로 서비스 계정 상태를 확인합니다.
로그를 공유해야 한다면 토큰, 인증 헤더, 사용자 이름, 로컬 파일 경로와 같은 민감한 내용을 먼저 가리세요. 진단 목적으로 API 키를 터미널 명령, 프로필, 공개 저장소에 직접 넣지 말고, 공식 클라이언트의 인증 흐름을 사용하세요. 또한 오류를 해결하려고 인증서 검증을 무조건 끄거나 확인되지 않은 주소로 API 요청을 재전송하지 마세요. 보안 설정을 약화시키기보다 원인에 맞는 최소한의 규칙과 프록시 설정을 적용하는 편이 안전합니다.
재현 가능한 설정으로 마무리
문제가 해결되면 어떤 변경이 효과가 있었는지 간단히 기록하세요. 예를 들어 “PowerShell에서 HTTPS_PROXY를 실제 Clash 포트로 지정한 뒤 연결 성공”처럼 운영체제, 셸, 포트, 변경한 규칙을 적어 두면 다음에 같은 현상이 생겼을 때 비교하기 쉽습니다. 장기간 사용할 설정은 개인 셸이나 개발 환경에만 적용하고, 다른 앱의 네트워크 동작에 영향을 주는 전역 설정은 꼭 필요한 경우에만 유지하세요. Clash 프로필을 업데이트한 뒤에는 규칙이 보존됐는지 다시 확인하는 것이 좋습니다.
정리하면, Claude Code 터미널 연결 문제는 대개 Clash 프로필과 노드 확인 → 규칙 매칭 확인 → 터미널 환경 변수 설정 → 로그와 요청 테스트 순서로 원인을 좁힐 수 있습니다. 먼저 임시 변수로 경로를 검증하고, 꼭 필요한 설정만 남기면 문제를 되풀이할 가능성도 줄어듭니다. 사용 중인 클라이언트의 프로필을 아직 준비하지 않았다면 신뢰할 수 있는 설정을 불러온 뒤, 해당 환경과 서비스 조건에 맞는 범위에서 연결을 점검해 보세요.