Cursor SDK와 Clash 분기 규칙이 왜 같이 나옵니까

Cursor SDK(TypeScript 기반 공식 패키지)는 IDE 창 없이도 에이전트 루프를 돌리게 해 주며, 로컬 스크립트·내부 대시보드·CI 파이프라인까지 확장하는 데 쓰입니다. 그런데 한 작업 안에서 동시에 열리는 호출이 여럿입니다. 토큰·세션을 주고받는 Cursor 백엔드 계열, 선택한 모델 API(자체 호스트·프록시·멀티 벤더), MCP로 연결한 브라우저·DB·내부 API, 그리고 가끔은 패키지 레지스트리·아티팩트 URL까지입니다.

사용자 입장에선 “에이전트 전체가 타임아웃”처럼 보이지만 실제로는 한 호스트 줄만 잘못된 출구로 빠졌거나, 셸에 남은 HTTP_PROXY와 Clash mixed-port가 서로 다른 경로를 가리키는 경우가 많습니다. 범용 VPN은 전체를 한 방향으로 밀어 넣어 원인 호스트를 좁히기 어렵고, YAML 규칙으로 도메인 단위 분기를 명시해 두면 재현과 롤백이 빨라집니다. IDE 창 위주 설정은 Cursor IDE Clash 분기 글과 겹치니, 여기서는 SDK·자동 실행 환경에 초점을 둡니다.

2026년 즈음에는 팀에서 에이전트 자동화와 MCP 도구 체인을 동시에 켜는 사례가 늘고, 클라우드 전용 게이트웨이와 로컬 개발망이 섞인 레포도 흔합니다. 같은 머신이라도 “브라우저 로그인은 되는데 스크립트만 실패”가 나오면 프로세스별 프록시 적용 여부를 먼저 의심하는 편이 시간을 아낍니다.

흔한 증상 패턴

아래에 해당하면 코어가 rule 모드인지·규칙 순서가 맞는지·환경 변수가 중복인지부터 보는 것이 이득입니다.

  • 같은 API 키로 curl·브라우저 테스트는 성공하는데 SDK만 장시간 대기 후 끊깁니다.
  • 첫 툴 호출까지는 되는데 특정 MCP 엔드포인트나 스트리밍 구간에서만 반복 타임아웃이 납니다.
  • 로컬에서는 되는데 GitHub Actions·자체 러너에서는 같은 코드가 실패합니다.
  • 노드를 바꿔도 증상이 비슷해 보이나, 연결 로그를 보면 호스트 이름만 바뀌고 출구 패턴은 그대로입니다.
  • 회사 ZTNA나 다른 VPN과 Clash를 동시에 올린 뒤부터 간헐 실패가 늘었습니다.

이때 목표는 속도 테스트 1위 노드가 아니라 로그에 찍힌 호스트 문자열 목록을 모으고, 각각 그룹에 태그를 붙인 다음 전략 그룹에 매핑하는 것입니다.

어떤 호스트 묶음부터 잡을지

제품과 리전·테넌트에 따라 DNS가 달라질 수 있으므로 아래는 출발점이며 반드시 본인 환경 로그로 확인하세요.

  • Cursor·세션·클라우드 백엔드: 앱이 붙는 API 호스트 줄기. IDE 글에서 다룬 패턴과 겹치는 경우가 많습니다.
  • 모델 제공자: OpenAI 호환 게이트웨이, 자체 프록시, Azure·Anthropic 등 선택·우회형 호스트가 한 실행 안에 여럿일 수 있습니다. AI SaaS 분기 참고가 되는 경우가 있습니다.
  • MCP: 원격 HTTP MCP라면 URL의 호스트가 별도입니다. 로컬 소켓만 쓰는 MCP는 프록시 규칙 밖일 수 있어 증상이 갈립니다.
  • 패키지·빌드: CI에서 SDK와 함께 npm·컨테이너 레지스트리를 당기면 별도 도메인이 섞입니다. “에이전트만” 보려면 스텝을 나눠 재현하세요.

처음부터 지나치게 넴비게이션용으로 넓은 DOMAIN-KEYWORD만 늘리면 의도치 않은 트래픽까지 같은 출구로 밀립니다. 로그에 실제로 찍힌 FQDN부터 한 줄씩 추가하고, 안정되면 RULE-PROVIDER 묶음으로 정리하는 흐름이 안전합니다. YAML 공통 구조는 YAML 구성 가이드와 맞춰 두면 이후 확장이 쉽습니다.

팁

어떤 프로세스가 어떤 호스트를 여는지 빠르게 보고 싶다면 코어 UI의 PROCESS-NAME·SRC-IP류 규칙으로 Node·러너 바이너리 행만 걸러 낸 뒤 로그를 모으면 분석이 빨라집니다.

전략 그룹 설계

에이전트 작업은 스톨이 긴 스트림과 짧은 툴 HTTP가 섞입니다. 지연 테스트 상위노드라도 자동 전환 전략이 과하면 TLS 세션이 잘려 “응답 도중 멈춤”형 타임아웃이 날 수 있으니, 검증용으로는 수동 선택형 Selector에 안정 출구를 두고 시작하는 편이 좋습니다. 예시 이름은 PROXY_CURSOR_DEV처럼 팀에서 통일해 두면 레포 문서에 적기 쉽습니다.

브라우저 기반 로그인이나 OAuth 리디렉트가 같은 머신에서 돌아가면 SSO 호스트와 API 호스트를 처음엔 같은 전략에 묶어도 됩니다. 순환·쿠키 문제가 분명해지면 SSO 전용 그룹을 쪼개세요. AWS 쪽과 동시에 쓰는 경우 Bedrock·Agent Toolkit 분기와 호스트 목록이 겹칠 수 있으므로 규칙만 중복 없이 정리합니다.

규칙 예시와 순서

아래는 개념 스케치입니다. 전략 이름·노드·도메인은 환경에 맞게 바꾸고, 실제 FQDN으로 좁혀 가세요.

# Conceptual excerpt — replace groups/domains with your verified hosts
proxy-groups:
  - name: PROXY_CURSOR_DEV
    type: select
    proxies:
      - NODE_LONG_SESSION_A
      - NODE_LONG_SESSION_B
      - PROXY_DEFAULT

rules:
  - DOMAIN-SUFFIX,cursor.sh,PROXY_CURSOR_DEV
  - DOMAIN-SUFFIX,api.openai.com,PROXY_CURSOR_DEV
  - DOMAIN-KEYWORD,your-mcp-host,PROXY_CURSOR_DEV
  - GEOIP,KR,DIRECT
  - MATCH,PROXY_DEFAULT

DOMAIN-SUFFIX,cursor.sh 한 줄이 실제 환경의 모든 API 호스트를 덮는지는 반드시 로그로 검증하세요. 하위 서비스가 다른 접미를 쓰면 줄을 추가합니다. 에이전트 관련 규칙 묶음이 GEOIP나 MATCH보다 위에 있는지 매번 확인합니다. 아래에 남으면 “가끔만” 실패하는 패턴이 자주 납니다.

주의

이 글은 조직 보안·이용 약관을 위반하는 경로 우회를 돕지 않습니다. 허용된 네트워크 안에서 출구 일관성을 맞추는 설정만 다룹니다. 시크릿·API 키는 로그와 스크린샷에 남기지 마세요.

로컬과 CI에서 프록시 맞추기

Node 런타임은 브라우저만큼 OS PAC·시스템 프록시를 자동으로 따르지 않을 때가 많습니다. 셸에 남은 HTTP_PROXY·HTTPS_PROXY·ALL_PROXY가 Clash mixed-port와 불일치하면 같은 호스트라도 프로그램마다 출구가 갈라집니다. 재현할 때는 변수를 한 종류씩만 바꾸고, 의도한 포트만 켜 두세요.

  • TUN 모드를 쓰면 대부분의 프로세스가 같은 터널을 타게 만들 수 있으나, 러너 OS·권한 정책과 충돌할 수 있어 CI에서는 헤드리스 리스닝 포트 방식이 흔합니다.
  • GitHub Actions 등 공용 러너는 프록시 유무가 로컬과 다릅니다. 회사 자체 러너를 쓴다면 로컬과 동일한 Clash 게이트웨이를 두거나, 스텝에 동일한 프록시 변수를 주입해 한 출구로 맞춥니다.
  • WSL·컨테이너 안에서 SDK를 돌리면 호스트망과 DNS가 달라집니다. 게스트에서 보이는 게이트웨이와 mixed-port 매핑을 따로 점검하세요.
  • fake-ip DNS를 쓰는 프로필이라면 일부 인증 리디렉트가 이상하게 보일 수 있어 DNS 모드와 예외 목록을 함께 봅니다.

개발용 Git·npm까지 한 프로필에서 묶어야 한다면 mixed-port 정리가 Windows mixed-port 글에 예시로 있습니다. 크로스 플랫폼은 개념만 가져와 동일하게 적용하면 됩니다.

MCP·모델 API를 같이 쓸 때

MCP는 도구 정의만 공통일 뿐 실제 네트워크는 URL마다 다릅니다. 원격 MCP가 회사망 안의 내부 API를 부르면 Clash 규칙으로 밖으로 나가 버리면 안 되는지, 반대로 특정 SAS URL만 허용 출구가 필요한지 정책부터 나눕니다. 모델 쪽은 게이트웨이 한 대가 여러 백엔드를 감싸는 구성이 많아 바깥에서 보이는 호스트 하나로는 부족할 때가 있습니다. 응답 헤더·에이전트 로그에 찍힌 최종 요청 URL을 기준으로 규칙을 추가하세요.

장시간 스트리밍이 있는 모델 API는 중간 프록시의 유휴 타임아웃에 걸리기도 합니다. 이때는 노드 교체보다 안정적인 장세션 출구와 업스트림 제한을 먼저 보는 편이 낫습니다.

점검 순서 요약

  1. 코어가 rule 모드인지, 최근 프로필 저장 후 재시작 이슈가 없는지 확인합니다.
  2. SDK를 재현하는 동안 연결 로그에서 호스트 문자열을 시간 순으로 적습니다.
  3. 각 호스트를 Cursor·모델·MCP·기타로 태깅해 PROXY_CURSOR_DEV 같은 그룹에 매핑합니다.
  4. 해당 규칙 행이 GEOIP·MATCH보다 위인지, 과대한 KEYWORD가 없는지 검토합니다.
  5. 셸·CI·Docker의 프록시 환경 변수와 TUN·mixed-port 설정이 서로 어긋나지 않았는지 확인합니다.
  6. 증상이 남으면 스텝을 분리해 설치·에이전트·MCP 중 어느 구간인지 좁힙니다.

자주 묻는 질문

MCP 서버 호스트도 규칙에 넣어야 하나요?

원격 MCP라면 네. 로그에 찍힌 MCP URL의 호스트를 IDE·모델 API와 같은 전략 그룹에 두거나, 정책상 분리가 필요하면 인접 그룹으로 나눕니다. 로컬 IPC만 쓰는 MCP는 프록시 바깥에 있을 수 있어 증상이 없을 수도 있습니다.

CI 러너에서는 Clash를 어떻게 붙이나요?

자체 호스트 러너라면 로컬과 같이 헤드리스 바이너리를 띄우고 mixed-port를 스텝 환경에 주입하거나, 조직 표준 게이트웨이를 쓰는 방식이 흔합니다. 공용 클라우드 러너는 아웃바운드가 제한적일 수 있으니 조직 정책·허용 목록을 먼저 확인하세요.

정리

Cursor SDK로 AI 에이전트를 자동화할 때는 단일 “에이전트 타임아웃”이 아니라 호스트별 분기 불일치를 의심하는 편이 빠릅니다. 연결 로그로 문자열을 모으고 전략 그룹에 출구를 고정한 뒤, 규칙 순서를 넓은 매치보다 위로 올리고, CI·셸의 프록시 환경을 Clash와 맞추면 간헐 실패가 줄어듭니다. MCP와 모델 API를 같이 쓰는 팀은 도메인을 한 번에 덮지 말고 로그 기반으로 좁혀 가세요.

일부 일회성 VPN 앱은 트래픽을 통째로 밀어 넣어 개발 호스트 단위 원인을 찾기 어렵고, 규칙 파일을 매번 손으로 갈아끼우는 방식은 실수 여지가 큽니다. Clash·mihomo처럼 한 프로필에서 구독·전략·규칙을 일관되게 다루면 SDK·IDE·CI를 같은 언어로 정리할 수 있습니다. 데스크톱·모바일 클라이언트는 Clash 다운로드 페이지에서 골라 설치할 수 있으며, 프로필을 맞춘 뒤 무료로 내려받아 에이전트 전용 전략 그룹부터 적용해 보시길 권합니다.