Cursor Agent SDK 베타 × Clash: CI/CD에서 에이전트 API를 도메인 분류로 안정화하는 실측 (2026)

① 왜 사람이 에디터로 쓸 때와 CI에서만 증상이 갈라질까

@cursor/sdk는 Node 러너 안에서 패키지로 설치되어 헤드리스 에이전트를 호출합니다. 사용자는 결과 파일과 로그만 보기 때문에 「어느 엔드포인트까지 붙였는지」「재시도가 몇 회 겹쳤는지」가 가시적으로 남지 않는 경우가 많습니다. 사람이 같은 기기에서 GUI로 붙였을 때는 되는데, Nightly 회귀 같은 자동작업에서만 간헐적 API 타임아웃이 튄다면, 네 번 중 세 번은 트래픽 라우팅 층(규칙 미적중·직접 연결 회선)·DNS 응답 경로 교차·프록시 환경 변수 누락의 조합입니다.

Clash Meta(Mihomo)는 이럴 때 새 VPN을 까기보다, 이미 갖춘 Rule 기반 라우팅으로 에이전트 전용 블록을 추가하는 게 비용 대비 빠른 편입니다. 전반 그림은 Clash 입문 튜토리얼의 Rule·모드 차이부터 짚어두면 이후 단계가 덜 헷갈립니다.

② 로컬 Verge 레시피를 그대로 CI에 들고 오면 깨지는 지점

실무에서 많이 하는 실수 한 가지는 Cursor 3 + Verge 안에서 잘 되던 같은 YAML 세트를, 러너 디렉터리에 통째로 복사해서 끝내는 패턴입니다. 데스크톱은 TUN 또는 시스템 프록시로 전역 패턴을 잡아도 사용자가 즉석에서 교정했기에 통과했지만, Docker Compose나 systemd 실행 유닛 속 node dist/agent.js는 해당 경로와 무관한 경우가 흔합니다.

• 패턴 α: http_proxy 소문자를 기대하지만 빌더는 대문자 HTTP_PROXY만 허용해서 런타임이 회사 방화벽 밖 회선만 두드림.
• 패턴 β: GEOIP CN DIRECT와 GITHUB 관련 접미사를 한 그룹에 몰아넣어두고, 패키지가 .cursor.* 계열 새 호스트만 추가돼 순서 미스매치.
• 패턴 γ: fake-ip가 활성 상태인데, 인증 교환 과정 일부 호스트만 fallback DNS를 타도록 남아 TCP 연결 시작과 TLS SNI 간 지연이 엇갈림.

에디터·멀티 에이전트 쪽 가시화를 먼저 점검했다면 Cursor 3 + Verge Rev DNS 분류 글과 짝 지어 두고, 같은 프로필을 런너 헤드에서도 적중 검증 순서만 그대로 복사해 가려면 레이블을 맞춰야 합니다.

③ 데이터 수집: 추측 말고 실제 접속 문자열부터

정품 릴리스마다 새 엔드포인트 접미사가 붙거나 내부적으로 staging 호스트 이름이 교체될 수 있습니다. 따라서 고정 블록리스트 표를 외워 쓰기보다 아래 순서를 권합니다.

1. 문제 발생 시점에 @cursor/sdk 로그 레벨 또는 HTTP 클라 로그(NODE_DEBUG 등) 가운데 실제 문자열 형태 호스트 이름을 적습니다.
2. 동일 머신에서 에이전트 스크립트 앞후로 직접 curl -v https://예시 도메인을 동일 회선과 비교해 핸드셰이크 시간을 잽니다.
3. Mihomo 또는 Verge 로그 패널에서 RULE 줄을 열어, 목표 접미사가 어떤 프록시 그룹 이름으로 갔는지 캡처합니다.

패키지·아티팩트는 기본적으로 GitHub를 두드립니다. Cursor + GitHub 분류에서 제안했던 접미사를 그대로 @cursor/sdk 파이프라인에도 포함시키면, 릴리스 태깅 과정 중 github.com·objects.githubusercontent.com 줄이 새로 깨져도 빠르게 붙입니다.

④ 규칙 스케치: CURSOR_CLOUD 그룹을 따로 만들기

아래 블록은 개념 레이아웃으로, 이름은 실제 proxy-groups 항목과 일치해야 합니다. 새 호스트는 로그 근거로 순서 안쪽에 밀어넣고, 테스트가 끝나면 RULE-SET으로 승격해 CI 전용 패치와 운영용 패치 사이 간극을 줄입니다.

rules:
  - DOMAIN-SUFFIX,cursor.com,CURSOR_CLOUD
  - DOMAIN-SUFFIX,cursor.sh,CURSOR_CLOUD
  - DOMAIN-SUFFIX,npmjs.org,CURSOR_DEPS
  - DOMAIN-KEYWORD,registry.npmjs.org,CURSOR_DEPS
  - DOMAIN-SUFFIX,github.com,CURSOR_DEPS
  - DOMAIN-SUFFIX,githubusercontent.com,CURSOR_DEPS
  - GEOIP,CN,DIRECT
  - MATCH,DIRECT

CURSOR_CLOUD와 CURSOR_DEPS는 한 그룹으로 묶어도 되지만, 실패 지점 디버깅을 위해 이름을 나누어 두면 @cursor/sdk 패키지가 npm 메타 요청 때문에 막히는지, 실제 에이전트 채널만 막히는지 바로 분해됩니다. 문법 디테일은 사용자 정의 규칙 튜토리얼에서 중첩 순서까지 같이 교차 검증하세요.

⑤ DNS 분리: 에이전트만 짧은 간격으로 새 연결을 열 때

fake-ip 모드에서는 도메인이 프록시 쪽에게만 보이거나, 이름 해석이 로컬 캐시에 오래 묶입니다. 헤드리스에서는 재시도가 짧아서 사람이 브라우저를 새로고침한 것처럼 체감되지 않을 뿐, 실제 패킷 패턴은 훨씬 거칩니다. 이때 필요한 패턴은 (1) 증상 호스트별 nameserver 순서 검토, (2) GEOIP 레이블이 국내 광역 회선까지 덮었는지, (3) 클라우드가 강제로 끌어올리는 차단 규격과 겹치는지입니다.

Mixin으로 DNS 블록만 재정의해야 한다면 Windows 11 기준 Verge Mixin 안내를 따라 구독 본체는 손대지 않고 테스트할 수 있습니다. 데스크톱이 아니라 헤드리스에서도 패턴은 동일합니다.

⑥ 워커 레벨의 프록시 환경 변수 정렬

GitLab Runner·Jenkins 에이전트·GitHub Hosted Ubuntu 이미지는 각각 셸 시작 스크립트, Docker 레이어 캐시, 워크플로 step env에서 값이 우선 순위 충돌합니다. 검증 순서 예시입니다.

1. http_proxy/https_proxy/no_proxy/all_proxy 네 줄을 명시했는지 확인합니다(HTTPS와 WS 경로 포함).
2. 동일 패키지를 pnpm이나 yarn berry로 감싸 재현할 경우, 패키지 매니저가 기대하는 변수 이름 차이 여부 확인.
3. 자체 빌더가 Podman 네임스페이스로 격돼 있으면, 호스트 mihomo 게이트의 바인드 IP와 컨테이너 브리지가 일치하지 않았는지 ss -nlpt로 확인합니다.

대규모 모노레포에서 패키지만 프록시를 타야 한다면 프로세스 기반 패턴까지 합류하는 경우가 많습니다(Windows PROCESS-NAME 분류 글 참조). 헤드리스 Linux에서도 이름 기반 접근 가능 여부를 먼저 확인해 두세요.

⑦ 헤드리스 바이너리와 데스크톱 GUI를 같은 저장소 규격으로 두기

mihomo systemd 유닛이나 간단히 sing-box 호환 아님 주의 깃 자산을 같이 들고 간다면, 프록시 핵심은 “화면이 있느냐”보다 프로필 디렉터리를 Git으로 고정했다가 런너 시작 시 검증하는 패턴입니다. 이때는 팀 레포에 staging과 prod 두 YAML을 명시 분리해서, 운영 팀 변경이 테스트 전용 패치까지 덮어쓰지 않게 합니다.

러너를 직접 보유했다면 회사 규격상 Zero Trust 게이트가 끼어 있어 TUN 레이어가 중첩되는 경우도 있습니다. TUN 모드 심화 글처럼, 중첩 터널에서 DNS가 어느 NIC로 나가야 하는지 먼저 결정해야 합니다. 그 결정 없이 새 RULE만 덧대면 로그 라인 숫자만 늘고 원인 표면화는 어렵습니다.

⑧ 병렬 잡 간 연결 증폭과 백오프

하나의 머신에서 두 개 워크플로가 같은 분 단위 크론에 걸려 있거나, 테스트 스위트가 런치 패드 수십 장을 거는 경우 @cursor/sdk 초기 세션 교환이 겹치면 순간 초당 새 연결 수가 급등합니다. 이 경우 자체 회선 속도 문제가 아니라 서버 속도 상한선에 부딪혀 연속 간헐 429가 찍히기도 하므로, 동시성 제어(p-limit 등)·재시도 지수 함수·야간 회선 전환처럼 애플리케이션 층 손실을 먼저 줄인 뒤에도 패킷 패턴 이상 지속하면 다시 라우팅으로 돌아옵니다.

⑨ 체크리스트: 새 릴리스 직후 30분 디버깅 루틴

1. 프로파일 무결성: 활성 규칙 파일의 SHA가 CI 환경 변수와 일치하는지 확인합니다.
2. 증상 패턴 문자열 저장: 실패 빌드의 stderr에서 HTTPS 호스트를 그대로 복사합니다.
3. 규칙 적중 테스트: 동일 문자열 기준 로그 줄을 Replay 하도록 작은 테스트 잡 작성.
4. DNS A/B: 한 번은 fake-ip on, 다른 한 번은 테스트 전용 이름 해석 순서 교체.
5. 종단 비교: 동일 패킷 패턴을 회사 회선 바깥 테스트망만 남긴 상태에서 재현 가능한지.
6. 문서 업데이트: 팀 위키의 “에이전트 네트워크 경로 다이어그램”에 새 접미사를 반영합니다.

워크플로 실패 시간이 줄면 @cursor/sdk 패치 속도 역시 따라 올라갑니다. 스크린 없는 헤드리스 디버깅은 기록 디스플린과 직결됩니다.

⑩ 자주 묻는 질문

@cursor/sdk를 빌드 머신에서 실행할 때 GUI용 규칙 그대로 써도 되나요?

원칙적으로는 시작점으로는 충분하지만, 헤드리스는 사용자가 교정 버튼을 눌러 줄 수 없습니다. 패키지가 직접 undici.fetch 경로 등을 선택한다면 라우팅 축 검증 순서까지 같이 포함되어야 재현 가능합니다.

Hosted 러너에서 직접 프록시를 못 깔면 어떡하나요?

그때는 외부 안정 회선 브리지 VM을 두거나, 테스트 전용 VPC 라우팅을 구성해야 합니다. 패키지만 다시 패치한다고 속도 문제가 줄지는 않으며, 회선 책임과 앱 책임을 나누는 설계 회의부터 필요합니다.

패키지가 내부적으로 WebSocket 장시간 유지하면 연결이 헐거워질까?

그럴 경우 RULE-SET 업데이트 주기 중간 중간 새 호스트 줄이 깨져도 패치가 따라가지 않으면 간헐 끊김이 됩니다. mihomo 업데이터 주기 자체를 CI 전용 패치처럼 GitOps로 명시합시다.

⑪ 다른 CLI 자동화 사례로 교차 학습하기

비슷한 증상을 겪던 Claude Code, Gemini CLI, npm 기반 MCP 연동도 네 번 중 세 번은 동일 패턴입니다. 자동 재시도 루프가 헤더마다 새 연결을 강요하는 패키지에서는 네트워킹 축 디버깅이 언어별이 아니라 공통 과제였습니다.

반면 특정 종류의 폐쇄형 브라우저형 VPN 클라는 편하게 클릭만 하면 모든 트래픽을 같은 터널로 밀어넣을 수 있다는 장점이 있지만, @cursor/sdk처럼 스크립트가 서로 다른 DNS·패키지·Git 계층까지 동시에 두드릴 때는 세밀한 API 분류까지 손보기 어렵고 패치 버전 따라 호스트 문자열 바뀌면 다시 헷갈리기 쉽습니다. 반면 Clash 규격은 규칙을 텍스트로 남길 수 있어 팀 간 공유 부담이 적고, mihomo에서는 RULE-PROVIDER로 외부 리스트 업데이트도 자동화할 수 있어 헤드리스 CI처럼 눈에 안 보이는 실패 패턴까지 추적 가능합니다.

자동 에이전트 파이프라인을 장기적으로 가져간다면, 지금 회선 패턴 위에서 점진적으로 세그먼트를 나누는 방법이 새 상용 어댑터를 계속 교체하는 것보다 시간을 덜 빼앗깁니다. 워커 패치와 동시에 Clash 클라이언트를 내려받아 테스트 전용 간소 규격을 분리 적용하는 것부터 시작할 수 있습니다.