Claude Code 터미널 연결, Clash로 설정하고 오류까지 해결하기

연결 흐름부터 확인: 터미널 요청과 Clash 프록시는 별개입니다

Claude Code가 터미널에서 응답하지 않을 때는 먼저 요청이 어디까지 도달하는지 나눠 확인하세요. 일반적으로 터미널에서 실행한 Claude Code가 네트워크 요청을 만들고, 환경 변수에 지정된 HTTP 프록시가 요청을 로컬 Clash 포트로 전달합니다. Clash는 연결을 받아 규칙에 따라 직접 연결하거나 선택된 프록시 노드로 보냅니다. 따라서 앱이 프록시 환경 변수를 읽지 않는 문제, Clash가 포트를 열지 않은 문제, 규칙이나 노드에서 연결이 실패한 문제를 구분해야 합니다.

브라우저에서 웹사이트가 열리는 것만으로 터미널 연결까지 확인된 것은 아닙니다. 브라우저는 운영체제의 시스템 프록시를 따르지만 터미널 프로그램은 별도의 환경 변수를 읽을 수 있습니다. 반대로 시스템 프록시를 켜지 않았더라도 터미널에 올바른 HTTPS_PROXY 값이 설정되어 있으면 명령줄 요청이 Clash를 통과할 수 있습니다.

확인 지점	정상일 때	이상 징후
Clash 로컬 포트	설정된 HTTP 또는 혼합 포트가 연결을 수신	연결 거부, 포트가 열려 있지 않음
터미널 환경 변수	Claude Code를 실행한 셸에 프록시 주소가 설정됨	브라우저만 연결되고 CLI는 시간 초과
Clash 연결 기록	요청이 표시되고 예상한 정책으로 전달	기록이 없거나 직접 연결·차단으로 처리
인증 단계	로그인과 콜백이 모두 완료됨	브라우저 로그인 후 CLI가 기다리거나 오류 표시

명령줄 프록시 설정: 셸별로 실행한 뒤 연결 확인

Clash에서 시스템 프록시를 켜는 것은 브라우저와 일부 데스크톱 앱에 편리하지만, 터미널에 실행한 프로그램이 그 설정을 자동으로 사용하는지는 별도 문제입니다. Claude Code를 실행하는 셸에 HTTP 프록시 주소를 전달하는 방식으로 확인해 보세요. 아래의 7890은 예시이므로 현재 클라이언트가 실제로 사용하는 포트로 바꿔야 합니다. Clash 혼합 포트는 보통 HTTP 프록시 요청과 SOCKS 요청을 모두 받을 수 있지만, HTTP_PROXY와 HTTPS_PROXY에는 우선 HTTP 형식의 주소를 사용합니다.

Windows PowerShell

PowerShell에서 아래 명령을 실행한 뒤, 같은 창에서 Claude Code를 시작하세요. 환경 변수는 현재 PowerShell 프로세스와 여기서 실행한 자식 프로세스에 적용됩니다. 새 터미널 창을 열면 다시 설정해야 합니다.

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

사용을 마친 뒤 프록시 변수를 지우려면 다음처럼 실행할 수 있습니다. 시스템 전체 환경 변수로 영구 등록하기 전에 먼저 현재 창에서 동작을 검증하는 편이 안전합니다.

Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue

macOS 및 Linux 셸

zsh, bash 등 터미널 셸에서는 변수를 내보낸 다음 같은 셸에서 프로그램을 실행합니다. 셸 프로필에 영구 저장하면 이후 해당 셸에서 시작하는 다른 명령줄 프로그램에도 적용될 수 있으므로, 먼저 일회성 설정으로 확인하세요.

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
claude

프록시가 필요한 작업을 마친 뒤 환경을 원래대로 되돌리려면 다음 명령을 사용합니다. 대소문자를 구분하는 도구도 있으므로 문제가 계속되면 사용하는 프로그램의 안내에 맞춰 대문자 또는 소문자 변수 이름을 확인하세요.

unset HTTP_PROXY
unset HTTPS_PROXY

환경 변수가 실제로 설정됐는지는 Windows에서 Get-ChildItem Env:HTTP_PROXY, Env:HTTPS_PROXY, macOS와 Linux에서 env | grep -i proxy로 확인할 수 있습니다. 출력에 주소가 보이는 것은 설정 확인일 뿐 연결 성공을 뜻하지 않습니다. 주소와 포트가 맞는지, Clash가 실행 중인지, 해당 터미널에서 테스트했는지를 함께 점검하세요.

Clash에서 경로 확인: 연결 기록과 규칙 모드 점검

환경 변수를 설정한 후 Claude Code를 실행하고 Clash의 연결 화면에서 새 요청이 나타나는지 확인하세요. 연결이 표시되면 도메인, 프로세스 정보가 제공되는 경우 해당 정보, 적용된 규칙, 최종 정책을 살펴봅니다. 연결 기록이 전혀 없다면 Claude Code가 변수를 읽지 않았거나, 다른 포트로 연결했거나, 현재 명령이 네트워크 요청을 만들지 않았을 수 있습니다. 이때 바로 규칙을 전부 바꾸기보다 로컬 포트부터 확인하는 것이 좋습니다.

요청이 기록되지만 실패한다면 선택된 정책과 노드 상태를 확인합니다. 규칙 모드에서는 도메인 규칙에 따라 DIRECT, 특정 프록시 그룹 또는 차단 정책이 적용될 수 있습니다. 전역 모드로 잠깐 비교할 때에도 전역 정책에서 실제 프록시 노드를 선택했는지 확인하세요. 전역 모드라는 표시만으로 프록시 출구가 자동 선택되는 것은 아닙니다. 테스트 후에는 일상적으로 사용하던 규칙 모드와 정책으로 되돌리세요.

포트와 HTTP 프록시 응답 검사

PowerShell에서는 포트 연결을 다음처럼 검사할 수 있습니다. TcpTestSucceeded가 True가 아니면 포트 번호, Clash 실행 상태, 다른 프로그램과의 포트 충돌을 확인하세요.

Test-NetConnection 127.0.0.1 -Port 7890

macOS 또는 Linux에서는 아래처럼 포트가 열려 있는지 검사할 수 있습니다. 응답이 없거나 연결 거부가 표시되면 설정 화면에 표시된 포트와 명령의 포트가 같은지 대조하세요.

nc -vz 127.0.0.1 7890

포트 연결이 성공한 뒤에는 환경 변수와 같은 로컬 프록시를 지정해 HTTPS 요청이 처리되는지 확인할 수 있습니다. 아래 요청은 연결 경로를 확인하기 위한 예시이며, 특정 서비스의 로그인 성공이나 Claude Code 인증 상태를 보장하지는 않습니다.

curl -I -x http://127.0.0.1:7890 https://api.anthropic.com/

응답이 돌아오면 TCP 연결과 프록시 경유가 동작하는지 판단하는 데 도움이 됩니다. 인증되지 않은 API 경로가 정상적인 API 응답 대신 오류 코드를 반환할 수도 있으므로, 이 결과만으로 계정이나 API 키의 유효성을 판단하지 마세요. 중요한 확인 지점은 요청이 Clash에 도달했는지, 시간 초과 없이 응답이 왔는지입니다.

Claude Code의 브라우저 로그인과 터미널의 네트워크 요청은 서로 다른 과정입니다. 브라우저가 열려 로그인 화면이 표시되더라도, 터미널에서 실행한 CLI가 로그인 완료 정보를 받지 못할 수 있습니다. 로그인 후 터미널이 계속 대기하거나 콜백 오류가 발생하면 브라우저와 CLI가 모두 같은 네트워크 조건에서 동작하는지 확인하세요. 브라우저만 시스템 프록시를 사용하고 셸은 프록시 변수를 사용하지 않는 구성이라면 두 경로가 달라질 수 있습니다.

증상	우선 확인할 항목	다음 조치
연결이 즉시 거부됨	프록시 포트, Clash 실행 여부, 포트 충돌	현재 HTTP 또는 혼합 포트를 확인하고 다시 검사
오래 기다린 뒤 시간 초과	Clash 연결 기록, 규칙 결과, 선택된 노드	다른 정상 정책으로 비교하고 DNS·네트워크 상태 확인
브라우저 로그인 후 CLI에서 실패	터미널 변수, 브라우저와 CLI의 연결 경로	같은 셸에서 변수를 확인하고 로그인 절차 재시도
인증 오류 또는 권한 오류	계정 로그인 상태, 사용 권한, 응답 내용	연결 오류와 인증 오류를 구분해 계정 안내 확인
설정 변경 뒤에도 이전 증상 지속	기존 터미널에 남은 변수와 실행 중인 프로세스	CLI를 종료하고 새 셸에서 현재 설정으로 재검증

ANTHROPIC_BASE_URL은 별도의 API 호환 게이트웨이를 사용할 때 지정하는 주소이며, Clash 로컬 프록시 주소를 대신 넣는 항목이 아닙니다. 일반적인 Clash 연결을 위해 이 값을 임의로 http://127.0.0.1:7890으로 설정하지 마세요. 잘못 지정하면 요청 대상 자체가 바뀌거나 API 경로가 맞지 않아 별도의 오류가 생길 수 있습니다. 프록시 연결은 HTTP_PROXY와 HTTPS_PROXY처럼 프록시 환경 변수로 설정하고, 다른 API 주소가 필요한 경우에는 해당 서비스가 제공한 정확한 설정을 사용하세요.

안정적으로 쓰기: 필요한 범위에서만 프록시 적용

매번 터미널에서 변수를 입력하는 방식이 번거롭다면 사용하는 셸의 프로필이나 프로젝트별 실행 스크립트에 설정할 수 있습니다. 다만 셸 프로필에 저장한 프록시 주소는 이후 실행하는 다른 명령줄 프로그램에도 전달될 수 있습니다. 업무 네트워크, 로컬 개발 서버, 직접 연결해야 하는 주소에 영향을 줄 수 있으므로 모든 터미널에 무조건 적용하기보다 필요할 때만 설정하거나 작업별로 적용하는 방식을 고려하세요.

Clash의 규칙도 최소한의 범위에서 조정하세요. Claude Code의 연결이 어떤 도메인과 정책으로 처리되는지 연결 화면에서 확인한 뒤, 필요한 경우 해당 도메인에 적용되는 규칙과 프록시 그룹을 점검합니다. 광범위한 규칙을 추가하거나 전체 트래픽을 전역 모드로 바꾸면 다른 앱의 연결까지 달라질 수 있습니다. 규칙을 수정하기 전에는 현재 설정을 백업하고, 구독 업데이트가 로컬 변경 사항을 덮어쓸 수 있는지도 확인하세요.

Clash가 실행 중이고 설정된 HTTP 또는 혼합 포트가 수신 중인지 확인합니다.
Claude Code를 실행할 터미널에서 프록시 환경 변수를 설정하고 주소가 올바른지 확인합니다.
포트 연결과 HTTPS 프록시 요청을 각각 검사해 장애가 난 단계를 구분합니다.
Claude Code를 실행한 뒤 Clash 연결 기록에서 요청과 최종 정책을 확인합니다.
로그인·인증 단계와 네트워크 시간 초과를 별도로 판단하고, 테스트가 끝나면 임시 환경 변수나 모드를 원래대로 되돌립니다.

이 순서대로 점검하면 단순한 포트 불일치부터 규칙 선택과 로그인 경로 문제까지 원인을 좁힐 수 있습니다. 프록시를 켰다는 사실이나 브라우저 접속 성공만으로 CLI 연결을 단정하지 말고, 터미널 변수, Clash 기록, 실제 응답을 함께 확인하는 것이 핵심입니다.