Cursor는 널리 쓰이는 AI 코드 편집기입니다. 기본 제공 모델 한도 외에도 자체 API Key와 Base URL을 입력할 수 있습니다. 국내 팀이 Cursor를 통합 OpenAI 호환 게이트웨이에 연결하면 접속 경로를 고정하고 청구서를 한곳에서 관리하며 모델 간 전환도 쉬워집니다.

이 글은 실제 작업 순서에 따라 준비, 설정, 검증, 제한, 팀 적용을 설명합니다. 버전마다 메뉴 이름이 다를 수 있으므로 현재 설치된 Cursor Settings를 기준으로 하세요.

안내: Cursor는 Anysphere, Inc.의 상표입니다. 이 글은 기술 설명 목적으로만 작성되었으며 Cursor/Anysphere와 제휴 또는 대리 관계가 없습니다. 인터페이스, 요금제, 과금 규칙은 Cursor 공식 페이지를 기준으로 합니다.

1. 먼저 두 가지 "Cursor API"를 구분하자

첫 번째는 Cursor 플랫폼이 자체적으로 제공하는 API입니다. Cloud Agents와 관리 인터페이스가 여기에 해당하며, Key는 Cursor 계정에서 만들어 Cursor 서비스를 호출하는 데 사용합니다. 두 번째는 "모델 Key 직접 사용(BYOK)"입니다. Cursor에 모델 공급자의 Key를 입력해 편집기가 사용자의 계정으로 모델을 호출하게 합니다. 이 글은 두 번째 방식을 다룹니다.

놓치기 쉬운 전제가 하나 있습니다. Cursor의 모델 요청은 사용자 PC에서 직접 나가는 것이 아니라 Cursor 서버를 거쳐 전달됩니다. 따라서 Base URL은 공인 인터넷에서 접근 가능한 주소여야 합니다. 사내망에서만 도달 가능한 게이트웨이는 Cursor 쪽에서 보통 타임아웃됩니다. ZSQH AI Gateway는 공인 서비스이므로 일반적으로 이 제약을 받지 않습니다.

2. Key, Base URL, 모델 이름 준비하기

시작 전에 세 가지를 준비합니다. API Key 하나, 호환 주소 하나, 정확한 모델 ID 하나입니다.

  1. ZSQH AI Gateway 등록 페이지를 열고 가입한 뒤 콘솔에 로그인합니다.
  2. "API 키"로 이동해 새 키를 만들고 이름에 용도를 분명히 적습니다. 예: cursor-업무용-PC.
  3. 한도 상한과 만료 시간을 설정합니다. 개인 계정도 이상 소비를 막기 위해 설정하는 편이 좋습니다.
  4. Key를 복사해 비밀번호 관리자에 저장합니다. 콘솔은 보통 전체 값을 한 번만 보여 줍니다.
  5. 모델 가격을 열어 사용할 모델 ID를 확인합니다. 가격과 모델은 조정될 수 있으므로 페이지에 현재 표시된 값을 기준으로 합니다.

세 가지 설정의 작성 예시는 다음과 같습니다.

Base URL: https://ai.zhongshangqihang.com/v1
API Key:  sk-... (콘솔에서 생성, 비밀번호 관리자에만 보관)
Model:    "모델 가격" 페이지에 현재 표시된 모델 ID 기준

Base URL은 OpenAI 호환 주소를 사용하며 끝이 /v1입니다. Anthropic의 루트 주소를 넣거나 /chat/completions를 직접 덧붙이지 마세요. 경로가 중복되기 쉽습니다.

3. Cursor에서 설정 입력하기

일반적인 경로는 Cursor Settings → Models → API Keys입니다. 버전에 따라 항목이 늘거나 줄 수 있지만 핵심 단계는 비슷합니다.

  1. Cursor Settings를 엽니다. 단축키는 보통 Cmd/Ctrl + ,입니다.
  2. Models로 이동해 API Keys 영역을 펼칩니다.
  3. OpenAI API Key를 열고 방금 만든 Key를 붙여 넣은 뒤 Save를 누릅니다.
  4. Override OpenAI Base URL을 열고 https://ai.zhongshangqihang.com/v1을 입력합니다.
  5. + Add Custom Model(일부 버전은 + Add model)을 눌러 가격 페이지의 모델 ID를 입력하고 해당 모델을 활성화합니다.
  6. 대화의 모델 선택기에서 이 모델을 고르고 간단한 요청을 보냅니다.

Override OpenAI Base URL 항목이 없다면 현재 버전이나 요금제가 OpenAI 호환 트래픽을 사용자 지정 주소로 보내는 기능을 지원하지 않는 것입니다. 이때는 반복해서 시도하지 말고 버전을 올리거나 해당 스위치를 지원하는 설치 패키지로 바꾸세요.

모델 이름은 설명이 아니라 라우팅 식별자입니다. 대소문자, 하이픈, 버전 접미사까지 게이트웨이와 일치해야 합니다. 잘못 입력하면 보통 모델 없음, 404, 또는 요청 거부로 나타납니다.

4. 모델은 어떻게 고를까

Cursor에는 여러 사용자 지정 모델을 추가할 수 있지만, 요청 성공 여부는 게이트웨이가 같은 이름의 모델을 제공하는지, 해당 호출 방식을 지원하는지에 달려 있습니다.

사용 상황 권장 등급 입력 방법 주의 사항
일상 질의, 작은 수정 경량 고속 모델 가격 페이지의 모델 ID 복사 지연이 낮지만 복잡한 리팩터링 능력은 제한적
다중 파일 수정, Agent 주력 코드 모델 가격 페이지의 모델 ID 복사 도구 호출 지원 필요
아키텍처 설계, 난제 분석 고성능 모델 가격 페이지의 모델 ID 복사 비용이 높으므로 필요할 때만 사용
Tab 자동 완성 Cursor 내장 모델 사용자 지정 Key를 거치지 않음 BYOK는 자동 완성을 대체하지 않음

Agent 모드는 Responses API나 도구 호출에 의존할 수 있습니다. 게이트웨이가 Chat Completions만 호환한다면 일부 Agent 기능이 실패합니다. 이 경우 먼저 일반 대화에서 검증한 뒤 모델 문제인지 기능 비호환인지 판단하세요.

또한 Auto, Composer, Tab 자동 완성이 항상 사용자의 Key를 쓰는 것은 아닙니다. Cursor 도움말에 따르면 Tab 자동 완성은 항상 내장 모델을 사용하며, Auto 모드도 Cursor가 자체적으로 라우팅할 수 있습니다. 사용자 지정 모델은 "명시적으로 선택했을 때만 적용되는 통로"로 이해하는 편이 실제와 맞습니다.

5. 설정이 적용됐는지 검증하기

Cursor가 답변했는지만 보는 것으로는 부족합니다. 답변이 내장 경로에서 나왔을 수 있기 때문입니다. 다음 순서로 검증하세요.

  1. 이전 컨텍스트의 간섭을 피하기 위해 빈 대화를 새로 엽니다.
  2. 모델 선택기에서 Auto가 아니라 사용자 지정 모델을 분명히 선택합니다.
  3. 짧은 요청을 보냅니다. 예를 들어 열 줄 이내의 코드를 설명하게 합니다.
  4. 게이트웨이 콘솔의 사용량 또는 요청 로그를 열어 같은 시각, 같은 모델, 같은 Key의 기록이 있는지 확인합니다.
  5. 검증 결과를 기록합니다. 로그에 기록이 없다면 요청이 게이트웨이에 도달하지 않은 것이므로 Base URL과 스위치를 다시 확인합니다.

흔한 오류는 다음과 같이 대조할 수 있습니다.

  • 401 또는 403: Key가 틀렸거나 비활성화됐거나 한도를 모두 사용했습니다.
  • 404: Base URL 경로가 잘못됐거나 모델 이름이 존재하지 않습니다.
  • 429: 속도 제한에 걸렸거나 Key 한도 상한에 도달했습니다.
  • 타임아웃: 엔드포인트에 도달할 수 없거나 네트워크 경로에 문제가 있습니다.
  • Agent만 실패: 인터페이스 기능이 맞지 않을 수 있으며 Key 문제가 아닐 수 있습니다.

6. 반드시 알아야 할 제한

  • BYOK는 주로 채팅 모델을 대상으로 하며, Tab 자동 완성은 여전히 Cursor 내장 모델을 사용합니다.
  • 버전마다 OpenAI Key 지원 범위가 다릅니다. Cursor 도움말에 따르면 OpenAI 직접 Key는 추론 기능이 없는 표준 채팅 모델만 지원하며, 추론 모델과 일부 신기능은 사용할 수 없을 수 있습니다.
  • 요청이 Cursor 서버를 거쳐 전달되므로 사용자 지정 엔드포인트는 공인 인터넷에서 접근 가능해야 합니다.
  • 직접 Key를 쓰는 요청이 Cursor의 무데이터 보존 정책을 항상 적용받는 것은 아닙니다. 데이터 처리는 모델 공급자와 게이트웨이에 따라 달라집니다. 데이터 보존 요건이 엄격한 팀은 먼저 평가해야 합니다.
  • 팀 요금제와 기업 요금제는 직접 Key를 쓰더라도 Cursor 규칙에 따라 플랫폼 비용이 부과될 수 있습니다. 구체적인 내용은 Cursor 과금 페이지를 기준으로 합니다.
  • Cursor는 업데이트가 빠르므로 메뉴 이름, 지원 모델, 과금 규칙이 바뀔 수 있습니다.

7. 팀 적용 단계

  • 먼저 소규모 시범 운영을 합니다. 개발자 3~5명을 선정하고 주력 모델 하나로 일주일간 운영합니다.
  • 세 가지 데이터를 기록합니다. 요청 성공률, 평균 지연, 1인당 일일 소비입니다.
  • 게이트웨이에서 구성원마다 별도 Key를 만들고 사람별로 한도를 설정합니다. 공용 Key는 쓰지 않습니다.
  • 모델 매핑 표를 유지합니다. Cursor에 무엇을 입력하고, 게이트웨이에서 무엇에 대응하며, 실패 시 무엇으로 전환할지 적습니다.
  • 설정을 내부 문서에 기록합니다. Base URL, 모델 ID, 흔한 오류 처리를 포함합니다.
  • 비용을 관찰한 뒤 어떤 구성원은 직접 Key를, 어떤 구성원은 요금제 한도를 계속 쓸지 결정합니다. 가격은 모델 가격을 기준으로 합니다.
  • 퇴사, 기기 교체, 프로젝트 종료 시 당일 해당 Key를 비활성화합니다.

8. 보안 체크리스트

  • 용도마다 Key를 하나씩 두고 기기 간에 재사용하지 않습니다.
  • 한도 상한과 만료 시간을 설정합니다.
  • Key를 코드, .env, 스크린샷, 티켓에 남기지 않습니다.
  • 공용 PC에 Key를 장기간 저장하지 않습니다.
  • 정기적으로 교체하고, 유출이 의심되면 먼저 비활성화한 뒤 조사합니다.
  • 팀은 게이트웨이를 통해 통합하고 요청 로그를 남겨 감사에 대비합니다.
  • 민감한 저장소는 데이터가 기기를 떠나는지, 어느 서비스로 흐르는지 먼저 확인합니다.

9. 자주 묻는 질문

Cursor는 모든 OpenAI 호환 인터페이스를 지원하나요?

반드시 그렇지는 않습니다. Cursor 버전에 Override OpenAI Base URL 기능이 있는지, 인터페이스가 실제 호출 경로와 파라미터를 호환하는지에 따라 달라집니다. 먼저 일반 대화에서 검증한 뒤 Agent 기능을 시험하세요.

직접 Key를 입력했는데 왜 구독이 필요하다고 나오나요?

직접 Key를 쓴다고 모든 기능이 열리는 것은 아닙니다. 일부 편집기 기능, 팀 관리, 내장 모델은 여전히 요금제 제한을 받습니다. Cursor의 현재 요금제 규칙을 기준으로 하세요.

Tab 자동 완성이 왜 제 Key를 소비하지 않나요?

Cursor 도움말에 따르면 Tab 자동 완성은 항상 Cursor 내장 모델을 사용하며 직접 Key를 거치지 않습니다. 이는 설정 오류가 아니라 제품 설계입니다.

Base URL에는 루트 주소와 /v1 중 무엇을 넣어야 하나요?

OpenAI 호환 프로토콜을 쓸 때는 /v1까지 입력합니다. /chat/completions는 붙이지 마세요. 경로가 중복되어 404가 발생하기 쉽습니다.

팀이 Key 하나를 공유해도 되나요?

기술적으로는 가능하지만 권장하지 않습니다. 공용 Key는 구성원별 사용량을 구분할 수 없고 유출 시 추적도 어렵습니다. 구성원마다 Key를 두고 한도와 로그를 함께 운영하는 편이 안전합니다.

다음 단계

먼저 ZSQH AI Gateway에 등록하고 Cursor 전용 Key를 만든 뒤 이 글에 따라 Base URL과 모델을 입력하세요. 일반 대화가 정상 동작하면 모델 가격을 보고 주력 모델과 한도를 조정하세요.

관련 글: