이 글이 맞는 증상

로컬 머신에서 Claude Code나 비슷한 터미널 에이전트를 실행할 때, 브라우저로는 문서·대시보드가 열리는데 Anthropic API 호출만 timeout·connection reset·긴 대기 끝의 실패로 끝나는 패턴이 있습니다. 한동안은 잘 되다가 회선·구독 규칙·DNS가 바뀐 직후부터만 터미널 쪽이 불안정해지기도 합니다. 이런 경우 단순히 API가 느리다로만 치부하기 전에, 프록시 스택이 브라우저와 터미널에 서로 다른 경로를 주고 있지 않은지를 먼저 확인하는 것이 시간을 아낍니다.

이 문서는 Clash Verge Rev(이하 CVR)를 전제로, 규칙 기반 분기와 HTTPS_PROXY 같은 환경 변수, 그리고 시스템 프록시 연동과 TUN 중 무엇을 골랐을 때 터미널 CLI가 안정적인지 실무 관점에서 순서를 정리했습니다. 특정 구독 파일이나 상용 노드 이름을 가정하지 않고, 패턴만 재사용할 수 있게 썼습니다.

왜 터미널의 Claude Code만 더 자주 깨질까

브라우저는 OS의 시스템 프록시를 잘 따르고, 확장이나 프로필별로 별도 PAC를 쓰기도 합니다. 반면 터미널에서 도는 Node·Go·Rust 기반 CLI는 기본적으로 프록시를 무시하고 직접 소켓을 여는 경우가 많습니다. Electron 기반 IDE 창은 시스템 설정을 일부 물려받지만, 통합 터미널 패널 안의 셸 세션은 부모 프로세스 환경 변수에 더 민감합니다.

또 다른 흔한 원인은 규칙 분기입니다. 구독 규칙이 DIRECT로 떨어지는 도메인 목록에 API 호스트가 포함되거나, 반대로 과도한 글로벌 프록시 때문에 사내 Git·패키지 레지스트리만 간헐적으로 막히는 식으로 증상이 갈립니다. 같은 PC에서도 패킷이 거치는 레이어가 브라우저와 터미널에서 다르면 겉으로 보이는 오류 메시지가 달라집니다.

규칙 분기 vs 글로벌 TUN: 무엇부터 맞출까

글로벌 TUN은 OS 트래픽을 넓게 덮어 우회 경로를 통일하기 좋지만, 다른 VPN·보안 에이전트·가상 스위치와 충돌하기 쉽고, 회사 정책 PC에서는 아예 비활성화되는 경우도 있습니다. 게다가 TUN을 켠 뒤에도 일부 런타임이 로컬 라우팅 테이블 변경을 따르지 않는 예외가 보고됩니다.

반면 규칙 분기 + 명시적 프록시 포트(CVR의 mixed-port 등)를 중심으로 두면, 어떤 호스트가 어떤 정책 그룹을 타는지 로그로 추적하기 쉽습니다. 브라우저는 시스템 프록시로 같은 포트를 향하게 하고, CLI는 HTTPS_PROXY=http://127.0.0.1:<mixed-port>처럼 같은 로컬 입구를 쓰게 맞추면 경로 불일치가 줄어듭니다.

실무에서는 (1) 우선 CVR 코어가 정상 바인드되어 있는지, (2) 메시지 API용 호스트가 의도한 노드를 타는지 규칙 패널에서 확인한 뒤, (3) 그다음 TUN이 꼭 필요한지 판단하는 순서가 디버깅 비용 대비 효율이 좋습니다.

팁: Rule·Global·Direct 표기는 클라이언트마다 화면 이름이 조금씩 다르지만, Mihomo·Clash 계열에서 말하는 모드 개념은 동일합니다. 헷갈리면 일시적으로 글로벌이 아닌 규칙 모드에서 시작해 로그로 한 호스트씩 검증하세요.

1단계: Clash Verge Rev 기본 상태 점검

CVR을 켠 상태에서 프로필이 활성인지, 코어 프로세스가 종료되지 않았는지부터 봅니다. 구독 동기화 직후 규칙 세트가 바뀌면 예전에 통과하던 API 호스트가 다른 그룹으로 튈 수 있으니, 업데이트 시각과 함께 기억해 두면 좋습니다.

mixed-port 숫자를 확인합니다. 브라우저의 시스템 프록시가 이 포트를 바라보게 되어 있다면, 터미널의 HTTPS_PROXY도 같은 번호여야 분기 정책을 공유합니다. 포트 충돌로 코어가 다른 번호로 올라간 경우가 흔한 함정입니다.

2단계: 규칙으로 Anthropic 관련 트래픽 분기 확인

실제 프로덕션에서는 엔드포인트가 버전·리전·계약에 따라 달라질 수 있으므로, 문서에 적힌 호스트만 맹신하지 말고 실패 직후의 접속 로그나 DNS 조회 결과를 한 번씩 대조하세요. 일반적인 공개 API 호스트는 검색과 공식 문서를 통해 확인할 수 있으며, 이 글에서는 이름 대신 규칙을 추가하는 방법에 초점을 맞춥니다.

CVR의 규칙 편집 화면 또는 YAML에서 해당 도메인 서픽스를 적절한 프록시 그룹에 매핑합니다. 이미 포함된 GEOSITE·GEOIP 묶음 때문에 DIRECT로 떨어지는지, 혹은 불안정한 업스트림으로만 붙는지 확인하세요. 테스트가 끝난 규칙은 주석이나 별도 파일로 버전 관리하면 팀 재현에 도움이 됩니다.

3단계: 터미널 환경 변수는 어디에 둘까

많은 HTTP 클라이언트는 아래 변수를 읽습니다.

  • HTTPS_PROXY / HTTP_PROXY — TLS·일반 HTTP 요청의 프록시 URL
  • ALL_PROXY — 일부 스택에서 둘을 대신하는 통합 키
  • NO_PROXY — 내부 호스트·localhost·사내 도메인 예외

어디에 적느냐는 OS와 셸 습관의 문제입니다. 지속적으로 쓸 계정 전체라면 ~/.zshrc·~/.bashrc(또는 해당 OS의 동등 파일)에 넣되, 조건문으로 CVR이 켜 졌을 때만 적용하게 두면 실수로 외부 네트워크에 프록시 주소를 들고 나가는 일을 줄일 수 있습니다.

레포마다 프록시 정책이 다르면 direnv처럼 디렉터리 단으로 환경 변수를 주입하는 도구가 깔끔합니다. VS Code·Cursor·JetBrains 계열은 터미널이 상위 앱의 환경을 상속하므로, IDE를 변수 export 이후에 재실행했는지도 확인하세요. 한 번 띄운 세션은 부모가 바뀌기 전까지 옛 값을 유지합니다.

프록시 URL 형식과 SOCKS 선택

CVR의 mixed-port가 HTTP와 SOCKS를 함께 제공한다면, Claude Code가 사용하는 HTTP 스택에 맞춰 http://127.0.0.1:<port> 형태를 우선 시도하는 것이 보통입니다. SOCKS가 필요한 도구는 socks5://127.0.0.1:<port>처럼 스키마를 분명히 적습니다. 잘못된 스키마는 즉시 거절되기보다 묵묵히 타임아웃으로 보일 때가 많습니다.

4단계: 시스템 프록시·TUN과의 정렬

macOS나 Windows에서 시스템 프록시를 CVR과 연동했다면, 브라우저 경로와 로컬 127.0.0.1 프록시 경로가 일치하는지 다시 확인합니다. TUN만 단독으로 사용 중이라면 터미널 트래픽이 실제로 가상 인터페이스를 통해 나가는지 라우팅 테이블·방화벽 규칙으로 교차 검증합니다.

이중 VPN(회사 Always-On VPN + CVR TUN 등)은 증상을 난해하게 만듭니다. 한쪽만 끈 상태에서 API 지연이 사라지는지 비교하면 원인 후보를 빠르게 줄일 수 있습니다.

주의: 터미널에 프록시 환경 변수를 넣으면 그 세션에서 실행되는 모든 호출에 영향을 줄 수 있습니다. 패키지 매니저·컨테이너 레지스트리·사내 API까지 우회 대상이 되지 않도록 NO_PROXY 목록을 신중히 유지하세요.

5단계: 여전히 타임아웃일 때의 좁히기 순서

  1. 같은 시각에 브라우저로 동일 호스트에 HTTPS가 열리는지 비교합니다.
  2. CVR 로그에서 해당 도메인이 어느 체인·어느 규칙으로 분류됐는지 확인합니다.
  3. 터미널에서 env | grep -i proxy(또는 동등 명령)로 의도와 다른 잔여 변수가 없는지 봅니다.
  4. DNS가 시스템 resolver와 DoH 정책이 엇갈려 누설 혹은 필터링이 나는지 검사합니다.
  5. 구독·노드 상태가 아니라 MTU·패킷 로스인지 간단한 연속 핑·트레이스로 구분합니다.

팀 환경에서의 문서화 팁

여러 명이 같은 레포에서 Claude Code를 쓰면, 왜 A의 터미널만 된다는 질문이 자주 나옵니다. 레포 루트에 선택적 예시 스크립트나 .env.example에 프록시 관련 키 이름만 적고 실제 값은 각자 로컬에 두는 패턴이 안전합니다. CI 러너와 로컬 변수명이 겹치지 않게 접두사를 나누는 것도 좋습니다.

자주 묻는 질문

Q. API 키를 프록시 로그에 남기지 않으려면?
A. 로그 레벨과 트레이스 기능을 제한하고, 공용 머신에서는 키 파일 권한과 셸 히스토리에 export 줄이 남지 않게 주의합니다. 가능하면 키는 환경 변수가 아닌 자격 증명 스토어를 사용하는 공식 권장 방식을 따르세요.

Q. WSL2와 Windows CVR을 동시에 쓸 때는?
A. 루프백 전달과 DNS가 달라 127.0.0.1이 WSL 안에서 Windows의 mixed-port와 연결되지 않을 수 있습니다. 이 경우 윈도우 측 LAN 주소를 향하게 하거나 mirrored networking 정책에 맞춰 주소를 바꿔야 할 수 있습니다.

Q. 회사에서 터미널 프록시가 금지라면?
A. 정책을 우회하려 하지 말고, IT에 허용된 egress와 인증 프록시 형식을 요청하는 것이 안전합니다. 이 문서는 합법적인 개발자 환경 전제입니다.

정리: 단일 글로벌 VPN 대신 규칙·터미널을 맞추는 쪽이 나은 이유

글로벌 VPN 앱만 켜 두고 끝내는 방식은 처음에는 단순하지만, 지역·세션·스플릿 터널링 정책이 바뀔 때 어떤 프로세스가 어떤 인터페이스를 쓰는지 가시성이 떨어집니다. 반면 Clash·Mihomo·CVR처럼 규칙과 로그가 한 화면에 모이는 스택은 호스트 단위로 문제를 찍고, 필요하면 터미널에만 HTTPS_PROXY를 얹는 등 층을 나눠 제어하기 쉽습니다. 이미 Cursor나 다른 IDE 확장용으로 프록시 분기를 손에 익었다면, 같은 원리를 Claude Code·Anthropic API 루프에 그대로 옮기되 터미널 환경 변수만 추가로 맞추면 재발 방지에 가깝게 운영할 수 있습니다.

상용 종합 VPN은 스트리밍·여행용으로는 편하지만, 여러 레지스트리·사내 Git·퍼블릭 API를 한꺼번에 쓰는 개발자 프록시 시나리오에서는 예외 목록이 거칠거나 CLI를 놓치기 쉽습니다. CVR로 규칙 분기를 유지한 채 필요한 세션에만 환경 변수를 주면, API 타임아웃의 원인을 회선이 아닌 경로로 좁히는 데 시간이 덜 듭니다.

Clash 호환 클라이언트를 받아 터미널·브라우저 경로를 같은 규칙으로 맞추기 →