# Cursor

Cursor의 채팅과 에이전트는 사용자 자신의 OpenAI 호환 서비스로 동작시킬 수 있습니다. 키와 기본 URL을 입력한 뒤 모델 이름을 직접 추가하세요.

> https://nezhagate.com/ko/docs/integrations/cursor

작성 기준 버전: Cursor 3.22

## 시작하기 전에

- Cursor 유료 플랜(Pro 이상)이 필요합니다. 무료 플랜에서는 자신의 키로 채팅과 에이전트를 실행할 수 없습니다.

- 팀 플랜에서는 관리자가 개인 API 키 사용을 허용해야 합니다.

- Cursor는 자체 서버에서 요청을 보내므로 NezhaGate의 공개 주소를 그대로 쓸 수 있습니다.

## 설정 단계

1. **Cursor Settings**(`Ctrl/Cmd + Shift + J`) → **Models**를 열고 맨 아래로 스크롤해 **API Keys**를 펼치세요.

2. **OpenAI API Key** 항목에 NezhaGate 키를 붙여넣고 **Use OpenAI API Key**를 켜세요(서로 다른 두 단계이며 둘 다 필요합니다).

3. **Override OpenAI Base URL**을 켜고 `https://nezhagate.com/v1`을 입력하세요.

4. 모델 검색창에 정확한 모델 이름을 입력하고(예: 아래 목록에 있는 모델) **Add Custom Model**을 클릭하세요.

5. Cursor를 다시 시작하고 새 채팅을 열어 추가한 모델을 선택하세요.

Base URL`https://nezhagate.com/v1`

## 어떤 모델을 추가할까요

Cursor에 추가할 수 있는 NezhaGate의 판매 중인 채팅 모델:

`gpt-5.6-sol` · `gpt-5.6-terra` · `gpt-5.6-luna` · `gpt-6-astra` · `gpt-6.1-sol` · `gpt-6-sol` · `gpt-6-luna` · `deepseek-v4.1-flash` · `deepseek-v4-flash-0731` · `glm-5.3` · `glm-5.3-flash` · `kimi-k3` · `qwen3.7-max` · `qwen3.8-max` · `qwen3.8-max-0902` · `qwen3.8-flash` · `doubao-seed-2-1-pro` · `doubao-seed-2-1-turbo` · `grok-4.7`

- 이름이 `claude-`로 시작하는 모델은 Cursor가 자체 Anthropic 키로 보내며, 이 항목은 기본 URL 재지정이 없어 NezhaGate의 Claude 모델은 Cursor에서 쓸 수 없습니다. `gemini-`로 시작하는 이름도 사용자 지정 주소를 쓴다는 보장이 없어 위 목록에서 뺐습니다. Claude는 [Claude Code](https://nezhagate.com/ko/docs/integrations/claude-code)를 쓰세요.

- Cursor에 이미 있는 모델과 이름이 같으면(예: `gpt-5.5`) 추가할 수 없습니다. 다른 모델을 고르세요.

- 이미지를 보내려면 이미지 입력을 지원하는 모델을 고르세요(각 모델의 API 문서 참고).

## 알아둘 제약 사항

- Tab 자동 완성은 사용자의 키를 쓰지 않습니다. 채팅과 에이전트만 NezhaGate를 거칩니다.

- 이 설정은 OpenAI 계열 모델 전체에 적용됩니다. 켜져 있는 동안에는 Cursor 자체 모델 일부가 사용자 지정 키를 지원하지 않는다고 표시됩니다. 다시 쓰려면 **Use OpenAI API Key**를 끄세요.

- Cursor에는 사용자 지정 키를 검증하는 버튼이 없고, 저장한 뒤에는 키 입력란에 값이 표시되지도 않습니다. 메시지를 하나 보내 보는 것이 가장 좋은 확인 방법입니다.

## 테스트

새 채팅을 열고 추가한 모델을 선택한 뒤 Reply with exactly: ok를 보내세요. 응답이 오면 콘솔의 호출 로그에서 이 요청을 확인할 수 있습니다.

## 자주 나오는 오류

**Model name is not valid / AI Model Not Found**

**Use OpenAI API Key**가 꺼져 있어 키가 전송되지 않았거나, 모델 이름이 `claude-`로 시작하는 경우입니다.

**This model does not support custom API keys**

Cursor 자체 모델이 선택되어 있습니다. 추가한 모델을 고르거나, Cursor 자체 모델을 쓰려면 **Use OpenAI API Key**를 끄세요.

**Invalid API key / Unauthorized User API key**

키가 잘못되었습니다. 전체 키를 다시 붙여넣으세요(입력란에는 이전 값이 보이지 않으니 그냥 덮어쓰면 됩니다).

**「Planning next moves」에 멈춰 있다가 결국 요청 제한이나 서비스 불가 오류가 뜰 때**

대개 무료 플랜이라 사용자 지정 키가 동작하지 않거나, 기본 URL이 잘못된 경우입니다. 플랜을 확인하고 주소가 `https://nezhagate.com/v1`인지 확인하세요.