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

# Cursor 설정 가이드

> Cursor에서 Crazyrouter에 연동하고, BYOK 모드에서의 사용 가능 범위, 제한사항, 문제 해결 방법을 알아봅니다

> 업데이트: 2026-06-06

Cursor는 Crazyrouter를 일상적인 코딩 워크플로에 연결하여 채팅, 코드 설명, 리팩터링 제안, 일반 편집 보조에 사용하기 적합합니다.

## 개요

Cursor의 BYOK(Bring Your Own Key) 기능을 통해 일부 채팅 모델 요청을 Crazyrouter로 전환하고 자신의 토큰으로 비용을 청구할 수 있습니다.

* 권장 연동 방식: OpenAI 호환 모드
* Crazyrouter Base URL: `https://api.crazyrouter.com/v1`
* 인증 방식: `sk-...` 토큰
* 가장 먼저 연동하기 적합한 기능: Chat, Ask, 일반 편집 대화

<Warning>
  Cursor 공식 문서에 따르면 `Custom API keys only work with standard chat models`이며, Tab Completion처럼 전용 모델에 의존하는 기능은 계속 Cursor 내장 모델을 사용합니다. 이 제한은 Cursor 자체에서 오는 것이며 Crazyrouter의 제한이 아닙니다.
</Warning>

## 이런 분에게 적합합니다

* Cursor에서 Crazyrouter 토큰을 통합적으로 사용하려는 개발자
* 모델 선택, 비용, 할당량을 관리하려는 분
* Cursor의 채팅 기능을 Crazyrouter에 연결하려는 팀
* 서로 다른 IDE / CLI를 별도로 청구하고 제한하려는 분

## 사용 프로토콜

권장 프로토콜: `OpenAI-compatible API`

Cursor에서 Crazyrouter와 연동할 때는 OpenAI 호환 베이스 주소를 사용하세요.

```text theme={null}
https://api.crazyrouter.com/v1
```

다음과 같이 입력하지 마세요.

* `https://api.crazyrouter.com`
* `https://api.crazyrouter.com/v1/chat/completions`

## 사전 조건

| 항목             | 설명                                                    |
| -------------- | ----------------------------------------------------- |
| Crazyrouter 계정 | 먼저 [crazyrouter.com](https://crazyrouter.com)에서 가입하세요 |
| Crazyrouter 토큰 | Cursor 전용 `sk-...` 토큰을 별도로 만드는 것을 권장합니다               |
| Cursor 데스크톱 앱  | 설정 전에 현재 안정 버전으로 업그레이드하는 것을 권장합니다                     |
| 사용 가능한 모델      | 토큰에 최소 1\~2개의 OpenAI 호환 채팅 모델이 허용되어 있어야 합니다           |

먼저 다음 중 하나의 모델을 허용하는 것을 권장합니다.

* `gpt-5.5`
* `claude-opus-4-8`
* `gemini-3.1-pro`

<Tip>
  이후 Claude Code, Codex, Cline도 설정할 계획이라면 Cursor와 같은 토큰을 공유하지 마세요. 토큰을 따로 나누면 문제 해결과 비용 관리가 더 편리해집니다.
</Tip>

## 5분 빠른 시작

<Steps>
  <Step title="Cursor 전용 토큰 생성">
    Crazyrouter 관리 페이지에서 새 토큰을 만드세요. 이름은 `cursor`로 지정하는 것을 권장합니다. 먼저 소수의 모델 화이트리스트를 활성화하세요. 예: `gpt-5.5`와 `claude-opus-4-8`.
  </Step>

  <Step title="Cursor 설정 열기">
    Cursor를 열고 `Cursor Settings` → `Models`로 이동합니다.
  </Step>

  <Step title="OpenAI 연동 정보 입력">
    OpenAI 관련 설정 영역에서 다음을 입력합니다.

    * `OpenAI API Key`: 본인의 `sk-...`
    * `Override OpenAI Base URL`: `https://api.crazyrouter.com/v1`

    사용 중인 Cursor 버전에서 `Override OpenAI Base URL`이 보이지 않는다면, 현재 버전의 커스텀 OpenAI 호환 엔드포인트 지원이 불완전하다는 의미이므로 Cursor를 업그레이드하거나 Cursor 측이 해당 기능을 더 개선할 때까지 기다려야 합니다.
  </Step>

  <Step title="키 검증 및 모델 선택">
    `Verify`를 클릭합니다. 통과하면 먼저 모델 하나를 활성화하여 첫 검증을 수행하세요. 처음에는 `gpt-5.5`를 선택하는 것을 권장합니다.
  </Step>

  <Step title="첫 테스트 완료">
    Cursor의 채팅 패널을 열고 간단한 요청을 보내세요. 예: `Reply with only OK`. 정상적으로 응답이 반환되면 Crazyrouter 연동이 성공했음을 의미합니다.
  </Step>
</Steps>

## 권장 모델 설정

| 사용 시나리오      | 권장 모델             | 이유                                                           |
| ------------ | ----------------- | ------------------------------------------------------------ |
| 기본 주력        | `gpt-5.5`         | 2026년 3월 23일 프로덕션 환경에서 실측 성공했으며 Cursor OpenAI 호환 기본 기준선으로 적합 |
| 고품질 코드 및 장문  | `claude-opus-4-8` | 복잡한 설명, 요약, 코드 보조에 더 적합                                      |
| Gemini 대체 옵션 | `gemini-3.1-pro`  | 두 번째 호환성 검증 경로로 적합                                           |

권장 순서: 먼저 `gpt-5.5`로 정상 동작을 확인한 후, `claude-opus-4-8`과 `gemini-3.1-pro`를 순차적으로 시도하세요.

## 토큰 설정 모범 사례

| 설정         | 권장         | 설명                                                              |
| ---------- | ---------- | --------------------------------------------------------------- |
| 전용 토큰      | 필수         | Cursor는 별도의 토큰을 사용하여 다른 도구와 혼용하지 마세요                            |
| 모델 화이트리스트  | 활성화 권장     | Cursor에서 실제로 사용할 모델만 허용하세요                                      |
| IP 제한      | 상황에 따라 활성화 | 개인 PC의 출구 IP가 고정되지 않은 경우 보통 권장하지 않으며, 고정된 사무실 네트워크라면 고려할 수 있습니다 |
| 할당량 상한     | 강력 권장      | Cursor에 별도 예산을 설정하여 전체 할당량을 한 번에 소진하지 않도록 하세요                   |
| 개발/프로덕션 분리 | 권장         | 개인 기기, 팀 기기, CI 머신에서 각각 다른 토큰을 사용하세요                            |
| 교체 빈도      | 정기적 교체 권장  | 스크린샷, 화면 녹화, 설정 동기화 등으로 토큰이 유출될 가능성이 있다면 즉시 재설정하세요              |

## 검증 체크리스트

* [ ] `Cursor Settings` → `Models`에서 키가 `Verify`를 통과함
* [ ] `Override OpenAI Base URL`이 `https://api.crazyrouter.com/v1`로 올바르게 설정됨
* [ ] 최소 하나의 Crazyrouter 모델을 성공적으로 선택함
* [ ] 채팅 패널의 첫 요청이 성공적으로 반환됨
* [ ] Crazyrouter 관리 페이지 로그에서 해당 요청을 확인할 수 있음
* [ ] 토큰 할당량과 모델 화이트리스트가 예상과 일치함
* [ ] Tab Completion 등 전용 기능은 Crazyrouter를 거치지 않을 수 있음을 알고 있음

## 자주 발생하는 오류와 해결 방법

| 현상                                    | 일반적인 원인                               | 해결 방법                                             |
| ------------------------------------- | ------------------------------------- | ------------------------------------------------- |
| `Verify` 실패                           | API Key가 잘못되었거나 Base URL이 잘못 입력됨      | `sk-...`와 `https://api.crazyrouter.com/v1`을 다시 확인 |
| 401 unauthorized                      | 토큰이 유효하지 않거나 만료되었거나 복사 시 공백이 포함됨      | 토큰을 재발급하고 순수한 값을 붙여넣기                             |
| 403 / model not allowed               | 현재 모델이 토큰 화이트리스트에 없음                  | Crazyrouter 토큰 설정에서 해당 모델을 허용                     |
| 404                                   | Base URL이 루트 도메인이나 구체적인 인터페이스 경로로 입력됨 | `https://api.crazyrouter.com/v1`로 통일하여 수정         |
| 모델 목록이 잘못되었거나 모델이 없음                  | Cursor BYOK 새로고침 실패, 또는 버전 호환성 문제     | Cursor를 재시작하고 다시 Verify하며, 필요하면 최신 안정 버전으로 업그레이드  |
| 채팅은 되지만 Tab 자동완성이 Crazyrouter를 거치지 않음 | Cursor 공식 제한: 전용 기능은 여전히 내장 모델을 사용    | 이는 예상된 동작이며 Crazyrouter의 오류가 아님                   |
| 커스텀 모델을 사용할 수 없음                      | Cursor의 커스텀 OpenAI 호환 엔드포인트 지원이 불안정함  | 먼저 `gpt-5.5`로 정상 동작을 확인한 후 다른 모델을 순차적으로 시도        |
| 비용이 이상하게 증가함                          | 여러 기능이 같은 토큰을 공유하거나 화이트리스트가 너무 넓음     | 모델 범위를 좁히고 Cursor에 별도의 할당량을 설정                    |

## 성능 및 비용 권장사항

* 1단계에서는 `gpt-5.5`만 활성화
* 복잡한 코드 설명, 요약, 리팩터링은 `gpt-5.5`를 우선 사용
* 다중 공급자 검증이 필요하면 `claude-opus-4-8`과 `gemini-3.1-pro`를 추가
* Claude Code / Codex를 동시에 사용 중이라면 반드시 토큰을 분리하여 비용을 집계
* 의심스러운 고소비가 발견되면 먼저 Crazyrouter 로그를 확인하여 Cursor의 다회차 컨텍스트가 원인인지 확인

## FAQ

### Cursor에서는 어떤 Base URL을 입력해야 하나요?

입력값: `https://api.crazyrouter.com/v1`

### 키를 입력했는데 왜 일부 기능은 여전히 Crazyrouter를 거치지 않나요?

Cursor 공식 설명에 따르면 커스텀 API 키는 표준 채팅 모델만 적용되며, Tab Completion 같은 전용 기능은 여전히 Cursor 자체 모델을 사용하기 때문입니다.

### 처음에는 어떤 모델을 권장하나요?

먼저 `gpt-5.5`를 사용하세요. 현재 실측으로 성공한 가장 최신 OpenAI 호환 기준선입니다.

### Claude나 다른 모델을 바로 사용할 수 있나요?

시도해볼 수는 있지만, 먼저 OpenAI 호환 경로의 기본 검증을 완료하는 것을 권장합니다. 특정 커스텀 모델이 현재 Cursor 버전에서 순조롭게 작동하는지는 Cursor의 호환성 구현에 따라 달라집니다.

### 채팅은 정상인데 모델 선택이 계속 흐트러지면 어떻게 하나요?

먼저 Cursor를 재시작한 후 다시 Verify하세요. 문제가 계속되면 실측으로 성공이 확인된 `gpt-5.5` 같은 기준 모델로 우선 되돌리세요.

<Note>
  Crazyrouter를 안정적인 코딩 워크플로에 주로 사용하려면, Claude Code, Codex, Cline이 Cursor의 커스텀 엔드포인트 경로보다 대체로 더 직접적이고 관리하기 쉽습니다. Cursor는 채팅과 일반 편집 보조를 먼저 연동하기에 더 적합합니다.
</Note>