이 글이 맞는 증상

2026년 기준으로 Cursor Agent API나 @cursor/sdk 류 패키지, 혹은 터미널·CI에서 도는 스크립트로 클라우드 에이전트를 실행할 때, 데스크톱 앱에서의 채팅·보완은 대체로 되는데 HTTP 루프만 ETIMEDOUT·ECONNRESET·긴 대기 후 실패로 끝나는 패턴을 자주 봅니다. 같은 맥에서 npm·git·다른 SaaS API는 통과하는데 특정 호스트 묶음에서만 지터가 나거나, 회선·구독 규칙을 바꾼 직후부터 SDK 쪽만 불안정해지기도 합니다.

이 문서는 Clash Verge Rev(이하 CVR)를 전제로, 프록시 분기로 Agent 트래픽이 의도한 업스트림을 타게 만들고, 자식 프로세스에 HTTPS_PROXY 등을 주입해 브라우저·IDE와 터미널 출구를 맞추는 순서를 정리했습니다. MCP(Model Context Protocol)를 쓰는 경우 전송 계층이 stdio인지 원격 SSE인지에 따라 프록시 이슈 여부가 갈리므로, 그 구분도 함께 다룹니다.

왜 데스크톱 Cursor는 되는데 SDK·CLI만 더 잘 깨질까

Electron 기반 IDE는 운영체제의 시스템 프록시 설정을 상당 부분 따릅니다. 반면 Node·Python·Go 등으로 돌아가는 SDK·CLI는 환경 변수나 런타임별 훅이 없으면 기본적으로 직접 DNS 조회와 TCP 연결을 시도합니다. 그 결과 HTTPS_PROXY가 비어 있으면 CVR의 mixed-port를 전혀 거치지 않고 나가거나, 반대로 규칙 때문에 DIRECT로 떨어져 차단 구간을 그대로 박는 경우가 생깁니다.

두 번째 축은 규칙 세트의 우선순위입니다. GEOSITE 묶음이 특정 서픽스를 덮어쓰면, 사용자가 기대한 노드 대신 다른 그룹으로 보내지거나 차단됩니다. 클라우드 에이전트는 롱폴링·스트리밍 응답이 많아 패킷 손실·불안정한 업스트림에서 브라우저의 짧은 요청보다 먼저 타임아웃이 드러나기도 합니다.

Agent API 트래픽과 MCP는 어디가 다른가

Agent API는 일반적으로 HTTPS 기반 REST·스트리밍 엔드포인트로, 퍼블릭 문서에 안내된 베이스 URL과 인증 헤더를 씁니다. 여기는 CVR 연결 로그에서 도메인만 잡혀도 DOMAIN-SUFFIX 규칙으로 정책 그룹을 지정하기 비교적 쉽습니다.

MCP는 서버 구현에 따라 로컬 stdio로 도구를 붙는 경우와 원격 HTTP/SSE로 이벤트를 받는 경우가 섞입니다. 전자는 프록시보다 localhost 포트·유닛 소켓 경로·방화벽을 먼저 의심하고, 후자는 Agent API와 같은 층에서 호스트 단위 분기를 점검합니다. 팀에서 게이트웨이 역할을 하는 중간 서버를 두었다면 그 도메인까지 규칙·NO_PROXY에 포함해야 루프가 끊기지 않습니다.

규칙 분기와 TUN, 무엇부터 맞출까

TUN/글로벌 턴은 한 번에 OS 트래픽을 덮어 개발 PC에서 빠르게 검증하기 좋지만, 다른 VPN·NAC·보안 에이전트와 라우팅 충돌이 잦습니다. CVR만 켠 상태에서도 회사 정책 때문에 가상 어댑터 생성이 막히는 환경이 있습니다.

반면 규칙 + mixed-port + 환경 변수 축은 어떤 요청이 어느 체인으로 갔는지 로그에 남기 쉬워, SDK 타임아웃을 회선 품질 문제인지 경로 설정 문제인지로 빠르게 쪼갤 수 있습니다. 실무에서는 (1) 코어와 포트, (2) 실제 SNI, (3) 터미널 HTTPS_PROXY, (4) 필요 시 TUN 순으로 두는 편이 재현성이 높습니다.

팁: Node 계열 HTTP 클라이언트는 HTTP_PROXY와 HTTPS_PROXY를 모두 읽는 경우가 많습니다. 한쪽만 비어 있으면 즉시 오류 대신 묵시적 대기로 보일 수 있으니 셸에서 env | grep -i proxy로 잔여 값을 함께 확인하세요.

1단계: Clash Verge Rev 기본 상태와 mixed-port

CVR을 켠 뒤 활성 프로필과 코어 기동 여부를 확인합니다. 구독이 갱신되며 커뮤니티 규칙이 바뀌면 예전에 통과하던 Cursor 관련 서픽스가 다른 정책으로 옮겨가는 일이 있으니, 업데이트 시각을 메모해 두면 원인 추적에 도움이 됩니다.

mixed-port 숫자를 적어 둡니다. 시스템 프록시 연동이 이 포트를 가리키도록 맞춰 두었다면, 터미널의 프록시 URL도 같은 로컬 입구를 써야 동일한 규칙 엔진을 공유합니다. 다른 앱이 포트를 선점해 번호가 바뀌면 환경 변수만 고쳐서는 증상이 남는 전형적인 함정입니다.

2단계: 연결 로그로 호스트를 확정한 뒤 규칙 반영

Cursor는 제품 업데이트에 따라 엔드포인트 이름이 달라질 수 있으므로, 인터넷에 떠도는 예시 목록만 복사해 붙이기보다 자신의 클라이언트 버전에서 실제로 붙는 호스트를 한 번 확인하는 편이 안전합니다. CVR 연결 화면에서 실패 직후의 레코드를 열어 도메인·정책 이름·체인을 적습니다.

YAML이나 Verge 규칙 편집기에서 해당 서픽스를 지연이 낮고 정책적으로 허용된 프록시 그룹에 매핑합니다. 상위의 GEOSITE나 사용자 정의 줄이 DIRECT로 덮어쓰지 않는지, 반대로 불안정한 업스트림 한 줄에만 묶이지 않았는지 대조하세요. 팀 레포라면 규칙 옆에 왜 넣었는지 짧은 주석을 남기면 온보딩 비용이 줄어듭니다.

3단계: SDK·CLI가 상속할 HTTPS_PROXY·NO_PROXY

많은 HTTP 스택이 아래 변수를 읽습니다.

  • HTTPS_PROXY / HTTP_PROXY — TLS·일반 HTTP의 프록시 URL
  • ALL_PROXY — 일부 런타임에서 통합 키로 쓰이는 경우
  • NO_PROXY — 127.0.0.1, localhost, 사내망, 로컬 MCP 게이트웨이 예외

계정 전역에 항상 export하기보다 CVR이 실제로 떠 있을 때만 적용하는 조건문을 ~/.zshrc 등에 두거나, 레포마다 정책이 다르면 direnv로 디렉터리 단 주입을 쓰면 실수로 공용 프록시를 들고 다니는 위험이 줄어듭니다.

이미 띄운 터미널은 부모 프로세스가 바뀌기 전까지 옛 환경을 유지하므로, IDE 통합 터미널을 쓰면 변수 수정 후 창을 닫았다가 다시 열었는지 확인해야 합니다. CI 러너에서는 시크릿에 프록시 URL을 넣되 명령 로그에 토큰이 노출되지 않게 주의합니다.

프록시 URL 스키마와 SOCKS

CVR의 mixed-port가 HTTP와 SOCKS를 함께 제공한다면 SDK에는 보통 http://127.0.0.1:<port> 형식을 먼저 시도합니다. 특정 MCP 브리지나 오래된 클라이언트가 SOCKS만 요구하면 socks5://127.0.0.1:<port>처럼 스키마를 분명히 적습니다. 오타는 즉시 거절 대신 장시간 대기로 보이는 경우가 많습니다.

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

macOS·Windows에서 시스템 프록시를 CVR과 연동했다면 브라우저가 가리키는 포트와 SDK가 쓰는 127.0.0.1 경로가 일치하는지 다시 봅니다. TUN만 단독으로 쓸 때는 터미널 트래픽이 실제로 가상 인터페이스를 통해 나가는지 라우팅·방화벽 로그로 교차 검증합니다.

회사 Always-On VPN과 CVR TUN을 동시에 켜 두면 핸드셰이크가 이중으로 감싸이거나 루프가 나기 쉽습니다. 테스트 때는 한쪽만 켠 상태에서 같은 SDK 명령을 비교하면 원인 후보를 빠르게 줄일 수 있습니다.

주의: HTTPS_PROXY를 넓게 켜 두면 그 세션의 패키지 매니저·컨테이너 풀·내부 API까지 예기치 않게 우회 경로를 탈 수 있습니다. NO_PROXY 목록을 팀 표준과 맞추고, 로그에 자격 증명 문자열이 남지 않게 레벨을 조절하세요.

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

  1. 같은 시각 브라우저에서 동일 호스트 HTTPS 접속이 되는지 비교합니다.
  2. CVR 로그에서 해당 요청이 어느 규칙·어느 체인인지 확인합니다.
  3. 에이전트를 띄운 셸에서 프록시 관련 환경 변수가 의도와 다른 잔여 값을 갖는지 봅니다.
  4. DNS가 시스템 resolver·DoH·fake-ip 정책과 엇갈려 누설이 없는지 점검합니다.
  5. 구독 이슈가 아니라 MTU·간헐적 패킷 로스인지 간단한 반복 측정으로 구분합니다.

SDK·에이전트 런처에서 자주 쓰는 패턴

로컬에서 짧은 스크립트로 Agent를 돌릴 때는 셸 한 줄에 변수를 붙이거나 .env 로더로 주입하는 방식이 흔합니다. 모노레포에서 여러 버전의 런타임이 공존하면 각 패키지 매니저가 spawn하는 자식이 같은 환경을 물려받는지 확인하세요. dockerized 러너라면 호스트의 127.0.0.1이 컨테이너 안에서 다르게 해석되므로 호스트 게이트웨이 주소나 허용된 HTTP 프록시 컨테이너를 별도로 두는 편이 안전합니다.

자주 묻는 질문

Q. Cursor 마켓플레이스 글에서 이미 Clash 룰을 맞췄는데 SDK만 달라요.
A. IDE 확장은 Electron 네트워크 스택을 타고, SDK는 터미널 런타임 변수에 더 의존합니다. 마켓 글에서 다룬 도메인 목록을 그대로 복사하되, 실패 로그의 SNI가 추가로 있는지 확인하고 HTTPS_PROXY 유무를 맞추세요.

Q. 자체 호스트된 MCP 프록시를 쓰는데 루프가 납니다.
A. 게이트웨이가 다시 공용 인터넷으로 나갈 때 같은 프록시를 두 번 타면 타임아웃이 날 수 있습니다. 내부 허브는 NO_PROXY에 두거나 DIRECT 규칙으로 고정하는지 검토합니다.

Q. 회사에서 터미널 프록시가 금지됐습니다.
A. 정책을 우회하지 말고 IT에 허용된 egress와 인증 프록시 형식을 요청하세요. 이 문서는 합법적인 개발 환경을 전제로 합니다.

정리: 단일 VPN 앱 대신 규칙·환경 변수를 맞추는 이유

상용 VPN 하나만 켜는 방식은 초기 설정은 단순하지만, 스플릿 터널이나 세션 정책이 바뀔 때 어떤 프로세스가 어떤 인터페이스로 나가는지 가시성이 떨어집니다. Electron IDE는 되는데 Node SDK만 깨지는 상황처럼 층이 다른 증상을 좁히기 어렵습니다.

반면 Clash·Mihomo·CVR 계열은 호스트 단위 규칙과 연결 로그가 한 화면에 모여, Agent API·MCP 출구를 의도한 정책 그룹에 고정하고 필요한 세션에만 HTTPS_PROXY를 얹는 방식으로 제어할 수 있습니다. Cursor AI 마켓 로딩이나 Codex·Claude Code 터미널 글에서 이미 분기 경험이 있다면, 같은 스택에 프로그래매틱 Agent용 호스트와 환경 변수만 추가하면 운영 표면이 크게 늘지 않습니다.

여행·스트리밍 중 빠른 우회에는 종합 VPN이 편하지만, 패키지 레지스트리·퍼블릭 API·사내망을 한 PC에서 같이 쓰는 개발자에게는 예외 목록이 거칠면 CLI 도구만 따로 끊기는 일이 잦습니다. CVR로 프록시 분기를 유지한 채 SDK 세션만 환경 변수로 정렬하면, 타임아웃 원인을 회선이 아닌 경로 설정으로 좁히는 데 걸리는 시간을 줄일 수 있습니다.

Clash 호환 클라이언트를 받아 SDK·브라우저 출구를 같은 규칙으로 맞추기 →