서론: 브라우저는 되는데 Claude Code는 왜 안 될까요?
브라우저에서는 웹사이트가 잘 열리는데 터미널에서 Claude Code를 실행하면 연결 시간이 초과되거나 로그인에 실패하는 경우가 있습니다. 이런 현상은 Clash가 꺼져 있어서라기보다, 브라우저와 명령줄 프로그램이 서로 다른 방식으로 네트워크에 연결하기 때문에 생길 수 있습니다. 브라우저는 운영체제의 시스템 프록시 설정을 자동으로 따르는 경우가 많지만, 터미널에서 실행한 CLI 프로그램은 프록시 주소를 별도로 전달받아야 할 수 있습니다.
따라서 브라우저가 프록시를 통해 접속된다는 사실만으로 Claude Code의 트래픽도 같은 경로를 사용한다고 단정할 수는 없습니다. Clash의 시스템 프록시가 켜져 있어도 터미널 환경 변수에 프록시가 지정되지 않았거나, Clash 규칙이 해당 도메인을 DIRECT로 보내면 요청이 우회될 수 있습니다. 반대로 환경 변수는 올바른데 선택한 노드가 불안정하거나 DNS 응답이 막혀도 시간 초과가 발생합니다.
먼저 확인할 점
Clash의 HTTP 또는 mixed 포트, Claude Code를 실행하는 터미널의 프록시 환경 변수, 요청 도메인에 적용된 규칙, 현재 선택한 프록시 노드를 순서대로 확인하면 원인을 빠르게 좁힐 수 있습니다.
이 가이드는 Clash Verge Rev, Clash Verge, Mihomo 기반 클라이언트에서 공통으로 적용할 수 있는 점검 절차를 설명합니다. 메뉴 이름은 버전과 운영체제에 따라 다를 수 있으므로, 특정 메뉴의 명칭보다 실제 포트 번호와 연결 로그를 기준으로 확인하세요. 또한 조직의 네트워크 정책이나 서비스 제공 조건을 준수하고, 계정 자격 증명이나 API 키를 공개 로그에 붙여 넣지 않도록 주의해야 합니다.
1Clash 프록시 포트와 연결 상태 확인
먼저 Clash가 실행 중이고 프록시 포트를 열어 두었는지 확인합니다. 일반적으로 클라이언트의 설정 또는 포트 표시 영역에서 mixed-port, HTTP 포트, SOCKS 포트를 확인할 수 있습니다. 포트 번호는 설치 환경이나 사용자가 바꾼 설정에 따라 다르므로, 예시에서 흔히 보이는 7890을 자신의 값이라고 가정하지 마세요. Claude Code에서 사용할 주소는 보통 같은 컴퓨터의 127.0.0.1과 실제 HTTP 또는 mixed 포트의 조합입니다.
- Clash 상태: 클라이언트가 실행 중인지, 프로필이 정상적으로 적용되었는지 확인합니다. 시스템 프록시 스위치만 켜져 있고 코어가 중지된 상태라면 요청을 처리할 수 없습니다.
- 포트 유형: 환경 변수의
HTTP_PROXY에는 HTTP 프록시 포트 또는 HTTP 요청을 처리하는 mixed 포트를 사용합니다. SOCKS 전용 포트라면 주소에socks5://를 지정해야 합니다. - 노드 상태: 현재 선택한 노드가 지연 검사에 응답하는지 확인하고, 문제가 의심되면 다른 정상 노드로 바꿔 비교합니다.
- 허용 주소: 터미널과 Clash가 같은 기기에서 실행되는 일반적인 구성이라면 로컬 주소인
127.0.0.1을 사용합니다. 다른 기기에서 접속하도록 포트를 외부에 열 때에는 인증과 방화벽 등 보안 설정을 별도로 검토해야 합니다.
Clash 대시보드에 연결 로그가 표시된다면 Claude Code를 실행하면서 로그를 함께 확인하세요. 요청이 전혀 나타나지 않으면 프록시 환경 변수가 적용되지 않았거나, 프로그램이 다른 프록시 설정을 사용하고 있을 가능성이 있습니다. 요청이 나타나지만 DIRECT로 표시된다면 규칙 또는 규칙 순서를 살펴보세요. 프록시 그룹에 연결되었는데도 실패한다면 노드, DNS, 원격 서버 응답을 차례로 점검해야 합니다.
포트가 열려 있는지 확인하세요
존재하지 않는 포트를 환경 변수에 넣으면 연결 거부 오류가 발생합니다. 클라이언트 화면이나 현재 적용된 Mihomo 설정에서 실제 포트 값을 확인하고, 포트가 바뀌었다면 기존 터미널의 환경 변수도 함께 수정하세요.
2터미널에 프록시 환경 변수 설정하기
Claude Code가 실행되는 프로세스에 프록시 주소를 전달하는 가장 간단한 방법은 환경 변수를 설정하는 것입니다. 아래 예시의 7890은 자리 표시자이므로 반드시 Clash에서 확인한 HTTP 또는 mixed 포트로 바꾸세요. HTTP 프록시를 사용하는 예시이며, SOCKS 전용 포트를 쓸 때는 http:// 대신 해당 포트에서 지원하는 socks5:// 주소를 사용합니다. 사용하는 클라이언트나 도구가 특정 프록시 형식을 지원하는지는 별도로 확인하세요.
현재 PowerShell 창에서만 적용하려면 다음 명령을 실행한 뒤 같은 창에서 Claude Code를 시작합니다. 환경 변수는 새 터미널 창으로 자동 전달되지 않으므로, 다른 셸을 열었다면 다시 설정해야 합니다.
※ ALL_PROXY가 꼭 필요한 것은 아닙니다. 문제가 계속되면 실제 포트와 프록시 형식을 먼저 확인하고, HTTP_PROXY와 HTTPS_PROXY만으로 비교해 보세요.
현재 셸에 변수를 설정하는 예시입니다. 환경 변수 이름은 도구에 따라 대문자 또는 소문자 형식을 확인할 필요가 있지만, 우선 대문자 형식으로 시험할 수 있습니다.
매번 입력하지 않으려면 사용 중인 셸의 시작 파일에 설정을 추가할 수 있습니다. 예를 들어 Zsh는 일반적으로 ~/.zshrc, Bash는 환경에 따라 ~/.bashrc 또는 ~/.bash_profile을 사용합니다. 파일을 수정한 뒤 새 터미널을 열거나 source ~/.zshrc처럼 해당 파일을 다시 읽어야 합니다. 공유 컴퓨터에서 프록시 주소나 인증 정보를 저장할 때는 파일 권한과 노출 가능성도 고려하세요.
설정 여부는 터미널에서 echo $HTTPS_PROXY 같은 명령으로 확인할 수 있습니다. Windows PowerShell에서는 $env:HTTPS_PROXY를 입력합니다. 값이 비어 있거나 예상한 포트와 다르면 Claude Code를 실행하는 셸에 설정이 적용되지 않은 것입니다. VS Code의 통합 터미널, 원격 개발 환경, 컨테이너, WSL은 별도의 환경으로 동작할 수 있으므로, 그 안에서 Claude Code를 실행한다면 해당 환경에도 Clash에 도달할 수 있는 프록시 주소와 경로가 설정되어야 합니다.
macOS의 응용 프로그램 런처나 작업 스케줄러에서 터미널을 열지 않고 Claude Code를 실행하는 경우에도 차이가 생길 수 있습니다. 셸 시작 파일에 넣은 값이 GUI 앱의 프로세스에 전달된다고 보장할 수 없기 때문입니다. 문제 재현 시에는 우선 변수를 직접 입력한 터미널에서 실행하여, 셸 환경 문제와 Clash 규칙 문제를 분리하는 것이 좋습니다.
3규칙을 확인하고 단계별로 원인 좁히기
환경 변수가 올바르게 설정되어 있어도 Clash의 규칙이 요청을 직접 연결로 보내면 기대한 경로로 접속되지 않을 수 있습니다. Claude Code와 관련된 서비스 도메인은 제품 구성이나 기능에 따라 달라질 수 있으므로, 하나의 도메인만 추가하면 모든 연결이 해결된다고 단정하지 마세요. 연결 로그에 실제로 나타나는 요청 도메인을 확인하고, 사용하는 규칙 제공자의 정책과 충돌하지 않도록 조정합니다.
직접 규칙을 관리한다면 사용 중인 프록시 그룹 이름을 확인한 뒤, 필요한 도메인 규칙을 일반적인 광범위 규칙보다 앞에 배치할 수 있습니다. 아래에서 Proxy는 예시 이름입니다. 실제 YAML의 프록시 그룹 이름과 다르면 적용되지 않으므로 반드시 자신의 설정에 맞게 바꾸세요.
규칙을 바꾼 뒤에는 설정 파일의 들여쓰기와 문법을 확인하고, 클라이언트에서 설정을 다시 적용합니다. 구독 프로필이 자동으로 갱신되는 경우 직접 수정한 규칙이 사라질 수 있으므로, 클라이언트가 제공하는 규칙 오버라이드나 사용자 규칙 기능을 이용하는 편이 안전합니다. 서비스 트래픽 전체를 무조건 프록시로 보내기보다, 연결 로그에서 확인한 도메인에 필요한 규칙만 적용하면 예상치 못한 부작용을 줄일 수 있습니다.
문제가 이어지면 다음 순서로 한 번에 한 가지씩 확인합니다. 먼저 HTTP_PROXY와 HTTPS_PROXY가 Claude Code를 실행하는 터미널에 실제로 존재하는지 확인합니다. 다음으로 Clash 로그에서 요청이 보이는지, 어떤 규칙과 노드가 선택되었는지 살펴봅니다. 로그에 요청이 있다면 다른 노드를 선택해 재시도하고, DNS 관련 오류가 나타나는지 확인합니다. 마지막으로 프록시를 통하지 않는 연결과 비교하여 문제가 Clash 경로, 로컬 셸, 원격 서비스 중 어디에서 발생하는지 분리합니다.
| 증상 | 가능성이 높은 원인 | 우선 확인할 항목 |
|---|---|---|
| 즉시 연결 거부 | 잘못된 포트 또는 코어 중지 | Clash의 실제 포트 번호와 실행 상태 |
| 오래 기다린 뒤 시간 초과 | 노드 응답 불량, 규칙 경로 또는 DNS 문제 | 연결 로그, 선택 노드, 다른 노드에서의 재시도 |
| 브라우저만 정상 작동 | 터미널 프로세스에 환경 변수가 없음 | Claude Code를 실행한 동일한 셸의 변수 값 |
| 일부 기능만 실패 | 요청 도메인별 규칙 또는 추가 연결의 차이 | 실패 시점의 로그와 실제 요청 도메인 |
연결 확인 팁
프록시를 지정한 상태에서 curl -v https://api.anthropic.com를 실행하면 TLS 연결 과정과 프록시 응답을 살펴볼 수 있습니다. API 인증이 없는 요청은 정상적인 서비스 응답 대신 오류 상태 코드를 반환할 수도 있으므로, 이 시험에서는 응답 내용보다 프록시 연결과 TLS 핸드셰이크가 진행되는지에 주목하세요.
모든 점검이 끝난 뒤에는 Claude Code를 완전히 종료하고, 환경 변수가 적용된 터미널에서 다시 실행하세요. 이전에 실행한 프로세스는 새로 설정한 환경 변수를 자동으로 읽지 않습니다. 그래도 실패한다면 오류 메시지의 시간 초과, DNS 실패, 인증 오류를 구분하고, 계정 상태나 서비스 측 문제도 확인해야 합니다. 프록시 설정만으로 계정 인증 또는 원격 서비스의 모든 오류가 해결되는 것은 아닙니다.
Clash 로그나 지원 요청에 정보를 공유할 때에는 API 키, 인증 토큰, 계정 식별 정보와 민감한 요청 내용을 삭제하세요. 오류 시각, 운영체제, 클라이언트와 코어 버전, 사용한 프록시 포트 유형, 연결 로그의 규칙 이름 정도만으로도 네트워크 경로를 진단하는 데 도움이 됩니다.