서론: Claude Code가 터미널에서 연결되지 않는 이유
Claude Code는 터미널에서 실행되는 AI 코딩 도구이므로, 브라우저에서 웹사이트가 잘 열린다고 해서 터미널 연결까지 자동으로 정상화되는 것은 아닙니다. Clash Verge나 Mihomo에서 시스템 프록시를 켰더라도 터미널의 셸, Node.js 프로세스 또는 Claude Code가 해당 프록시 설정을 이어받지 못하면 로그인이나 API 요청이 실패할 수 있습니다. 반대로 프록시 주소와 포트가 잘못되었거나, 관련 도메인이 DIRECT로 분기되어도 연결 오류가 발생합니다.
이 문제를 해결할 때는 먼저 Clash가 실제로 실행 중인지, 선택한 노드가 정상인지 확인하고, 그다음 터미널에 프록시 환경 변수를 설정해야 합니다. 이후 Claude Code가 사용하는 트래픽이 Clash의 프록시 그룹으로 전달되는지 확인하면 원인을 단계적으로 좁힐 수 있습니다. 이 과정은 모든 트래픽을 무조건 프록시로 보내는 대신 필요한 연결만 분리해 관리하는 데도 도움이 됩니다.
핵심 요약
Clash의 시스템 프록시와 터미널 프록시 환경 변수는 서로 다른 설정입니다. 터미널에서 Claude Code를 실행한다면 Clash의 실제 포트와 노드 상태를 확인한 뒤 HTTP_PROXY, HTTPS_PROXY를 직접 설정하는 것이 가장 빠른 진단 방법입니다.
이 안내는 Clash Verge, Clash Verge Rev, Mihomo 기반 클라이언트에서 공통으로 적용할 수 있는 원칙을 다룹니다. 메뉴 이름이나 기본 포트는 클라이언트 버전과 사용자 설정에 따라 다를 수 있으므로, 예시 값을 그대로 복사하기보다 자신의 설정 화면과 대조하세요. 또한 프록시 사용 가능 여부는 네트워크 환경과 서비스 정책에 따라 달라질 수 있습니다. 지역 제한이나 계정 관련 문제가 있는 경우에는 프록시 설정만으로 해결되지 않을 수 있습니다.
1Clash 포트와 노드 상태 확인
먼저 Clash 클라이언트에서 프로필이 정상적으로 적용되었는지 확인합니다. 대시보드에 노드 목록이 보이고 프록시가 활성화되어 있어도, 현재 선택된 노드의 연결이 끊겼거나 규칙 그룹이 다른 노드를 가리키면 실제 요청은 실패할 수 있습니다. Claude Code의 문제를 진단하기 전, 클라이언트에서 일반적인 프록시 연결이 되는지 확인하세요.
- 프로필 확인: Clash Verge 또는 Clash Verge Rev에서 사용할 프로필이 활성화되어 있는지 확인합니다. 설정을 수정했다면 변경 사항이 실제 실행 중인 프로필에 반영되었는지도 살펴봅니다.
- 노드 선택: 프록시 그룹에서 연결 가능한 노드를 선택합니다. 자동 선택 그룹을 사용한다면 지연 시간 검사 결과가 정상인지 확인하고, 진단 중에는 결과를 알 수 있는 특정 노드를 잠시 직접 선택해 보세요.
- 포트 확인: 클라이언트의 포트 설정에서 HTTP 혼합 포트 또는 HTTP 프록시 포트를 확인합니다. 많은 설치 환경에서
7890이 사용되지만, 이는 고정된 규칙이 아닙니다. SOCKS 포트가 별도로 설정되어 있다면 보통7891처럼 다른 값일 수 있습니다. - 모드 확인: 규칙 모드에서는 도메인 규칙과 정책 그룹에 따라 연결 경로가 달라집니다. 연결 진단을 위해 전역 모드를 잠시 사용할 수 있지만, 테스트가 끝나면 평소 사용할 모드로 되돌리고 규칙을 점검하세요.
터미널 도구가 어떤 프록시 프로토콜을 지원하는지에 따라 주소 형식을 선택합니다. 아래 포트는 예시이므로 Clash 설정 화면에 표시된 값으로 바꾸세요.
- HTTP 혼합 포트: 일반적인 환경 변수 설정에 사용하기 쉽습니다. 예:
http://127.0.0.1:7890 - SOCKS 포트: 도구가 SOCKS 프록시를 지원할 때 사용할 수 있습니다. 예:
socks5h://127.0.0.1:7891 - 로컬 주소:
127.0.0.1은 같은 컴퓨터에서 실행 중인 Clash를 가리킵니다. Clash가 다른 컴퓨터나 가상 머신에서 실행 중이라면 이 주소를 그대로 사용할 수 없습니다.
※ 우선 HTTP 혼합 포트로 시험하고, SOCKS를 사용할 때는 Claude Code와 함께 사용하는 도구가 해당 프로토콜을 지원하는지 확인하세요.
포트를 추측하지 마세요
다른 프로그램이 같은 기본 포트를 사용하거나 Clash에서 포트를 변경했을 수 있습니다. 환경 변수에 잘못된 포트를 입력하면 브라우저는 연결되는데 터미널만 실패하는 것처럼 보일 수 있습니다.
Clash의 연결 로그도 유용한 진단 자료입니다. Claude Code를 실행한 직후 로그에 관련 도메인 요청이 나타나는지 확인하세요. 요청이 전혀 보이지 않는다면 셸이 프록시 주소를 전달하지 못했거나, 앱이 다른 네트워크 경로를 사용하는 상황일 수 있습니다. 요청은 보이지만 실패한다면 선택된 노드, 규칙 분기 또는 원격 서버의 응답을 추가로 살펴봅니다.
2터미널에 프록시 환경 변수 설정
터미널 프로그램은 운영체제의 시스템 프록시 설정을 항상 자동으로 사용하지 않습니다. Claude Code를 실행하는 셸에 프록시 환경 변수를 지정하면 해당 셸에서 시작한 프로세스가 프록시 주소를 전달받을 수 있습니다. 우선 아래 명령으로 현재 터미널 세션에만 적용해 연결을 시험하는 것을 권장합니다.
아래 예시의 7890을 Clash에 표시된 HTTP 포트로 바꿉니다. 환경 변수 이름은 대문자와 소문자 버전을 함께 설정해 도구별 차이를 줄일 수 있습니다.
테스트가 끝난 뒤 현재 셸에서만 변수를 지우려면 다음 명령을 사용합니다. 이 작업은 이미 실행 중인 Claude Code 프로세스의 설정을 바꾸지 않으므로, 종료한 다음 다시 실행해야 합니다.
PowerShell에서는 현재 창에 적용할 변수를 다음처럼 지정합니다. 다른 포트를 사용하는 경우 주소의 포트 번호를 수정하세요.
현재 창에서만 설정을 해제하려면 값을 비웁니다. 새 PowerShell 창을 열면 임시 설정은 이어지지 않습니다.
연결이 확인된 뒤 매번 입력하지 않도록 셸 설정 파일에 변수를 추가할 수 있습니다. macOS와 많은 Linux 배포판에서 Bash는 보통 ~/.bashrc, Zsh는 ~/.zshrc를 사용합니다. 파일에 같은 변수가 이미 있다면 중복으로 추가하기보다 기존 값을 수정하세요. 저장 후 새 터미널을 열거나 해당 설정 파일을 다시 불러와야 변경 사항이 적용됩니다. Windows에서 영구 설정을 사용하려면 사용자 환경 변수 또는 PowerShell 프로필을 이용할 수 있지만, 먼저 임시 설정으로 정상 동작을 확인하는 편이 안전합니다.
Claude Code 실행 방식에 유의
환경 변수를 설정한 터미널에서 claude를 실행해야 설정이 전달됩니다. IDE의 내장 터미널, 별도 작업 자동화 도구, GUI 런처에서 실행하는 경우에는 그 프로세스가 같은 환경 변수를 받는지 따로 확인해야 합니다.
3도메인 규칙 점검과 오류 해결
환경 변수를 설정했는데도 연결되지 않는다면 Clash의 규칙이 해당 요청을 어느 그룹으로 보내는지 확인합니다. 규칙 모드에서는 앞에 배치된 규칙이 먼저 적용될 수 있으므로, 관련 도메인이 의도치 않게 DIRECT 또는 사용할 수 없는 그룹으로 분기되는지 살펴보세요. 구체적인 도메인 목록은 서비스 기능과 버전에 따라 달라질 수 있으므로, 로그에서 실제 요청된 호스트를 확인해 필요한 규칙만 추가하는 것이 좋습니다.
다음 예시는 규칙의 형태를 보여 주기 위한 것입니다. AI-Proxy는 사용 중인 설정에 이미 존재하는 프록시 그룹 이름으로 바꿔야 합니다. 존재하지 않는 그룹 이름을 지정하면 설정 적용 오류가 나거나 원하는 노드로 연결되지 않습니다.
프로필이 원격 구독에서 관리된다면 원본 파일을 직접 수정해도 다음 업데이트 때 덮어써질 수 있습니다. 클라이언트가 제공하는 규칙 추가 기능이나 지원되는 오버라이드 방식을 사용하고, YAML을 수정한 뒤에는 문법 검사와 프로필 적용 상태를 확인하세요.
오류를 찾을 때는 한 번에 여러 설정을 바꾸지 말고 아래 순서로 하나씩 시험하면 원인을 구분하기 쉽습니다.
- 프록시 포트에 연결되는지 확인: Clash가 실행 중이고 설정한 로컬 포트가 활성화되어 있는지 확인합니다. 포트가 열려 있어도 원격 노드가 정상이라는 뜻은 아니므로 다음 단계도 진행합니다.
- 간단한 요청으로 환경 변수 시험: 해당 시스템에 설치된
curl을 사용할 수 있다면, 예를 들어curl -I -x http://127.0.0.1:7890 https://api.anthropic.com처럼 요청해 봅니다. HTTP 응답 코드가 표시되는 것은 네트워크 경로가 응답했다는 뜻일 수 있지만, Claude Code의 로그인이나 인증이 성공했다는 의미는 아닙니다. - Clash 로그 확인: 요청이 로그에 나타나는지, 어떤 정책 그룹이 선택되는지, 연결이 시간 초과되는지 확인합니다. 로그에 요청이 없으면 터미널 환경 변수나 실행 경로를 먼저 점검합니다.
- 노드와 규칙을 분리해 시험: 노드를 바꾸거나 테스트용으로 규칙을 단순화한 뒤 결과를 비교합니다. 시험 후에는 평소 정책으로 되돌리고, 필요 이상의 전체 트래픽 프록시는 피하세요.
| 증상 | 가능한 원인 | 확인할 항목 |
|---|---|---|
| 터미널에서 연결 시간 초과 | 잘못된 포트, 노드 장애, 셸이 프록시를 사용하지 않음 | Clash 포트와 노드, 환경 변수, 로그 |
| 브라우저는 되지만 Claude Code는 실패 | 시스템 프록시만 설정되고 터미널 변수는 없음 | Claude Code를 실행한 셸의 환경 변수 |
| 요청은 보이지만 잘못된 경로로 연결 | 규칙 순서 또는 정책 그룹 설정 문제 | 로그에 표시된 도메인과 선택 그룹 |
| 로그인이나 인증 단계에서 거부 | 계정, 인증 상태, 서비스 정책 또는 시간 문제 | 오류 메시지와 공식 계정 상태, 시스템 시각 |
일부 앱이나 터미널 도구는 환경 변수만으로 모든 연결을 처리하지 않을 수 있습니다. 그런 경우 Clash Verge의 TUN 모드가 대안이 될 수 있습니다. TUN은 지원되는 트래픽을 시스템 수준에서 가로채므로, 시스템 프록시를 무시하는 프로그램을 진단할 때 도움이 됩니다. 다만 관리자 권한이 필요할 수 있고, DNS 처리나 다른 VPN·보안 프로그램과 충돌할 수도 있습니다. 먼저 환경 변수 방식을 확인하고, TUN을 켠다면 Clash 로그에서 Claude Code 요청이 실제로 포착되는지 검증하세요.
프록시 인증 정보 보호
프록시 주소에 사용자 이름이나 비밀번호를 포함했다면 명령 기록과 셸 설정 파일에 자격 증명이 남을 수 있습니다. 민감한 정보를 공개 저장소에 커밋하지 말고, 공유 컴퓨터에서는 임시 환경 변수를 사용한 뒤 세션을 정리하세요.
설정이 안정적으로 동작하면 재부팅이나 새 터미널에서도 재현되는지 확인하고, Clash 프로필 업데이트 후에도 프록시 그룹 이름과 규칙이 유지되는지 점검합니다. 문제 발생 시에는 먼저 이전에 성공했던 설정으로 되돌릴 수 있도록 변경 내용을 기록해 두세요. 원인을 추적할 때는 오류 전문, 사용 중인 운영체제, 실제 HTTP 포트, Clash 로그의 관련 부분을 함께 확인하되 토큰이나 계정 정보는 공유하지 않는 것이 안전합니다.