> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor

> Cursor와 CC Switch를 함께 사용해 로컬 프록시로 여러 모델 공급자를 통합 관리하고 원클릭으로 전환하는 가이드

> 이 문서는 AI 코드 에디터 **Cursor**와 오픈소스 설정 관리 도구 **CC Switch**를 함께 사용해 여러 모델 공급자를 통합 관리하고 원클릭으로 전환하는 방법을 소개합니다.

## 1. Cursor란

Cursor는 AI 프로그래밍을 위한 코드 에디터입니다. Cursor로 다음 작업을 할 수 있습니다:

* 코드 자동 완성
* 코드 생성
* 코드 수정
* 코드 설명
* 프로젝트 분석
* 버그 진단
* 에이전트 코딩

## 2. CC Switch란

CC Switch는 **오픈소스 로컬 GUI 기반 AI 서비스 설정 관리 및 리버스 프록시 도구**입니다.

주로 두 가지 문제를 해결합니다:

1. **설정 통합**: Claude Code, Cursor, OpenCode 등 여러 AI 코딩 도구에 흩어져 있는 API Key와 Base URL을 한곳에서 관리해 설정 파일 간 충돌을 방지합니다.
2. **프로토콜 중계**: 특정 네이티브 프로토콜만 지원하던 앱(예: Cursor의 Codex 플러그인)도 표준 인터페이스를 통해 더 많은 서드파티 호환 API를 호출할 수 있게 합니다.

Cursor를 CC Switch에 연결하면 전체 흐름은 다음과 같습니다:

```text theme={null}
Cursor
   ↓
CC Switch API
   ↓
사용 가능한 모델
   ↓
AI 응답
   ↓
Cursor
```

## 3. Cursor와 CC Switch를 함께 쓰는 이유

일상적인 개발에서는 공식 Anthropic API, 각종 중계 서비스, 자체 구축 게이트웨이 등 여러 모델 공급자 사이를 오가야 할 때가 많습니다. 기존 방식에서는 전환할 때마다 각 도구의 설정 파일을 직접 수정해야 해서 번거롭고 실수하기 쉽습니다.

CC Switch의 장점은 다음과 같습니다:

* **한 번 설정하면 어디서나 적용**: 데스크톱에서 공급자 설정을 한 벌 유지하면 Cursor 등 도구가 자동으로 따라갑니다.
* **원클릭 전환**: 공급자 전환은 보통 10초 이내에 끝나며 Key를 다시 입력할 필요가 없습니다.
* **자원 재사용, 마이그레이션 불필요**: Claude 크레딧이 소진되면 Codex, DeepSeek 등으로 매끄럽게 전환할 수 있고 프로젝트 파일은 그대로 둡니다.
* **설정 격리**: 프로젝트별, 컴플라이언스 요건별로 독립된 설정을 만들 수 있습니다.

## 4. 사전 준비

* 사용 중인 컴퓨터에 Cursor와 CC Switch 설치 완료
* [GravitexAI 콘솔](https://maas.gravitex.ai/#/api-keys)에서 API Key 발급 완료(형식: `sk-xxxxxxxxxx`)

## 5. Cursor와 CC Switch 설치

<Tabs>
  <Tab title="Cursor 설치">
    [https://cursor.com/download](https://cursor.com/download) 에서 다운로드합니다. macOS와 Windows를 지원합니다.
  </Tab>

  <Tab title="CC Switch 설치">
    본 플랫폼의 [CC Switch 가이드](/ko/integrations/cc-switch)를 참고하세요.
  </Tab>
</Tabs>

## 6. Cursor에서 CC Switch 설정하기

### 1단계: CC Switch에서 공급자 설정

1. CC Switch에서 공급자를 설정합니다(API Key + Base URL).
2. CC Switch를 실행하고 **설정 → 라우팅**으로 이동해 라우팅 메인 스위치를 켜고 라우팅할 앱을 선택합니다.
3. 로컬 프록시가 수신 중인지 확인한 뒤 하단의 "서비스 주소"를 복사합니다(포트는 앱 화면에 표시된 값을 기준으로 하며, 예: `http://127.0.0.1:15721`).

<Frame>
  <img src="https://mintcdn.com/gravitexai/YCzYS8JUSvjzZQaq/images/cursor1.png?fit=max&auto=format&n=YCzYS8JUSvjzZQaq&q=85&s=fcc803b138f0f45f36c5d69560bc9fa3" alt="CC Switch 로컬 라우팅 및 서비스 주소" width="2275" height="1280" data-path="images/cursor1.png" />
</Frame>

### 2단계: Cursor에서 설정

1. Cursor를 열고 **Cmd + ,**(macOS) 또는 **Ctrl + ,**(Windows / Linux)로 Settings에 진입합니다. 좌측 하단의 톱니바퀴 아이콘 ⚙️을 클릭한 뒤 Models를 선택해도 됩니다.
2. 왼쪽 내비게이션에서 **Models** 패널로 이동합니다.
3. **OpenAI API Key** 필드에 GravitexAI 키를 입력합니다.
4. **OpenAI API** 관련 설정 영역을 찾습니다:
   * **Override OpenAI Base URL** 스위치를 켭니다.
   * CC Switch가 제공하는 로컬 엔드포인트 URL을 입력합니다. 예: `http://127.0.0.1:15721/v1` (`/v1`은 필수이며 끝에 슬래시를 붙이지 않습니다).

### 3단계: 모델 ID 추가

1. Models 목록 상단의 **Add or search model** 입력창에 사용할 모델 ID를 입력합니다.
2. 모델 ID는 CC Switch에 설정한 공급자의 규칙을 따릅니다. 예: `gemini-3-flash-preview`, `seed-2-1-turbo-260628`, `claude-sonnet-4-6`.

<Frame>
  <img src="https://mintcdn.com/gravitexai/YCzYS8JUSvjzZQaq/images/cursor2.png?fit=max&auto=format&n=YCzYS8JUSvjzZQaq&q=85&s=fa6f0ac7183c14aee806dcaa37f59682" alt="Cursor Models 패널에서 API Key와 Base URL 설정" width="2704" height="1696" data-path="images/cursor2.png" />
</Frame>

<Warning>
  중요 안내: Cursor 공식 정책상 서드파티 API Key(GravitexAI 포함)를 사용하려면 다음 조건을 충족해야 합니다:

  * **Pro Plan**(유료 구독)을 사용 중이어야 합니다. Free Plan에서는 서드파티 API Key를 사용할 수 없습니다
  * 서드파티 API 서비스에 안정적으로 접속하려면 VPN/프록시 설정이 필요합니다
</Warning>

## 7. 지원 모델

GravitexAI를 통해 Cursor는 OpenAI, Google Gemini, Claude, DeepSeek, 중국 주요 모델 등 100+ 주류 AI 모델을 지원합니다.

<Card title="현재 인기 모델 추천 보기" icon="star" href="https://maas.gravitex.ai/#/api-models">
  최신 모델 추천, 성능 비교, 시나리오별 사용 제안을 확인하세요. 텍스트 창작, 프로그래밍 개발, 빠른 응답, 이미지 생성, 영상 생성 등 전 영역을 다룹니다.
</Card>

<Info>
  **왜 구체적인 모델을 여기에 나열하지 않나요?**

  AI 모델은 매우 빠르게 업데이트됩니다. 가장 정확한 정보를 제공하기 위해 최신 모델 목록, 성능 데이터, 사용 제안은 [모델 추천 페이지](https://maas.gravitex.ai/#/api-models)에서 통합 관리합니다.
</Info>

## 8. 자주 발생하는 설정 문제

<AccordionGroup>
  <Accordion title="API Key 입력 오류">
    다음과 같은 오류가 발생하면:

    ```text theme={null}
    401 Unauthorized
    ```

    우선 아래를 확인하세요:

    1. API Key가 정확한가
    2. 불필요한 공백이 함께 복사되지 않았는가
    3. API Key가 이미 만료되지 않았는가
    4. 다른 플랫폼의 API Key를 잘못 사용하지 않았는가
  </Accordion>

  <Accordion title="Model이 존재하지 않음">
    다음과 유사한 오류가 발생하면:

    ```text theme={null}
    Model not found
    ```

    모델 이름을 확인하세요. 흔한 원인:

    * 모델 이름 오타
    * 현재 Key에 해당 모델 권한이 없음
    * 모델이 종료되었거나 변경됨
    * 다른 사용자의 모델 이름을 사용함
  </Accordion>

  <Accordion title="API는 호출되지만 Cursor에서 정상 동작하지 않음">
    이 경우 보통 API 호환성을 확인해야 합니다.

    Cursor가 보내는 요청은 CC Switch가 지원하는 API 프로토콜과 일치해야 합니다. 요청 형식, 모델 이름, 응답 구조가 클라이언트의 기대와 다르면 다음이 발생할 수 있습니다:

    * 요청은 성공했지만 내용이 없음
    * 모델이 정상적으로 응답하지 않음
    * Cursor가 응답을 파싱하지 못함
    * 대화가 중간에 끊김

    이런 문제가 생기면 먼저 `curl` 등 API 도구로 API가 정상 응답하는지 테스트하세요.
  </Accordion>

  <Accordion title="Cursor AI가 응답하지 않거나 로딩이 계속됨">
    1. CC Switch 노드 연결이 끊겼는지 확인하고 지연이 낮은 노드로 재연결합니다;
    2. `settings.json`의 프록시 설정이 저장되었고 포트가 정확한지 확인합니다;
    3. Cursor를 백그라운드까지 완전히 종료한 뒤 재시작합니다;
    4. 엄격한 SSL 검증을 끄고 안정적인 해외 노드로 전환합니다.
  </Accordion>

  <Accordion title="간헐적인 모델 호출 타임아웃">
    노드 네트워크 변동이 원인인 경우가 많습니다. 예비 노드로 전환하거나 CC Switch를 재시작해 다시 연결하면 됩니다.
  </Accordion>
</AccordionGroup>

<Info>
  **추가 도움**: 기술 지원은 [bd@gravitex.ai](mailto:bd@gravitex.ai) 로 문의하거나 13603055233 으로 전화 주세요.
</Info>