Cursor를 OpenRouter에 연결하는 방법: 설정, 기능 경계 및 오류 해결
Cursor를 OpenRouter에 설정하고 Activity로 경로를 증명하는 방법, Chat·Agent·Tab·tools를 개별 검증하는 절차, endpoint·모델·크레딧·제한 오류의 해결법을 정리합니다.
목차
핵심부터 말하면, Cursor에서 답변이 왔다고 해서 모든 기능이 OpenRouter를 사용한다는 뜻은 아닙니다. 2026년 10월 4일 기준 OpenRouter는 Cursor 통합을 Beta로 표시하며 전용 Base URL https://openrouter.ai/api/v1/cursor 사용을 요구합니다. OpenRouter 모델을 수동으로 선택하면 Chat과 Agent의 모델 요청은 이 경로를 사용할 수 있습니다. 반면 Tab Completion은 사용자 API Key를 사용하지 않으며, tool calling은 전용 endpoint와 선택한 모델의 tools 지원이 모두 필요합니다.
따라서 올바른 검수는 “Key를 넣고 답변을 받았다”가 아니라 설정 확인 → 모델 수동 선택 → 최소 요청 → OpenRouter Activity의 일치 기록 → Agent와 tools 개별 확인이라는 증거 흐름입니다. 이 글은 현재 공식 문서를 바탕으로 하며, 특정 계정·API Key·요청 로그·Cursor 빌드에서 전체 경로를 실측했다고 주장하지 않습니다.
어떤 기능이 사용자 Key를 사용하는가
| Cursor 기능 | 예상 OpenRouter 경로 | 중요한 경계 | 가장 좋은 확인 방법 |
|---|---|---|---|
| Chat 또는 Ask에서 수동 선택한 모델 | 일반적으로 사용 | OpenRouter의 OpenAI-compatible 경로에서 제공되는 모델이어야 함 | 최소 프롬프트를 보내고 Activity에서 시간과 모델을 대조 |
| Agent에서 수동 선택한 모델 | 모델 호출은 보통 사용하지만 모든 내부 동작은 증명되지 않음 | 공식 가이드는 Agent 모델 선택을 설명하지만 모든 보조 요청은 설명하지 않음 | Activity 기록과 Cursor의 도구 동작을 각각 확인 |
| Tab Completion | 사용하지 않음 | Cursor 내장 모델을 계속 사용 | Tab 제안을 OpenRouter 활성화 증거로 사용하지 않기 |
| Agent의 tool calling | 조건부 | /cursor endpoint와 tools 지원 모델이 필요 | Chat 검증 후 읽기 전용 Agent 작업으로 확인 |
| 자동 모델 선택 | 검수 증거로 부적합 | 다른 모델이나 경로를 선택할 수 있음 | Auto를 끄고 추가한 모델을 명시적으로 선택 |
여기서 모델 요청과 도구 실행을 구분해야 합니다. OpenRouter tool calling 문서에 따르면 모델은 도구 호출을 제안하고, 클라이언트가 도구를 실행한 뒤 결과를 모델에 돌려줍니다. Activity 기록은 모델 요청이 OpenRouter를 통과했다는 증거가 될 수 있지만, 파일 읽기나 로컬 명령 자체가 OpenRouter에서 실행됐다는 증거는 아닙니다.
설정 전에 준비할 것
Cursor Settings→Models→API Keys를 열 수 있는 최신 Cursor.- 본인의 OpenRouter API Key. 채팅, 저장소, 스크린샷, 지원 메시지에 붙여 넣지 마세요.
- 현재 OpenRouter 카탈로그에서 복사한 정확한 Model ID.
- Agent tools를 시험할 경우 tools 지원 모델 필터에서 확인한 모델.
Cursor 버전에 따라 버튼은 활성화, 저장, 확인, 검증으로 다르게 보일 수 있습니다. 하지만 관계는 같습니다. OpenRouter Key는 OpenAI API Key, 전용 주소는 Override OpenAI Base URL, 모델은 전체 OpenRouter ID를 사용합니다.
올바른 순서로 Cursor 설정하기
1. API Key 설정 열기
Cursor Settings → Models로 이동하고 API Keys를 펼친 뒤 OpenAI API Key와 Override OpenAI Base URL을 찾습니다.
2. OpenRouter Key 입력하기
OpenRouter 계정에서 만든 Key를 OpenAI API Key에 붙여 넣습니다. Cursor 설정 화면에만 입력하고 현재 클라이언트가 표시하는 저장·활성화·검증 단계를 완료합니다.
3. Cursor 전용 endpoint 사용하기
Override OpenAI Base URL을 켜고 다음 값을 입력합니다.
https://openrouter.ai/api/v1/cursor
일반 주소 https://openrouter.ai/api/v1로 바꾸거나 /chat/completions를 덧붙이지 마세요. 전용 /cursor endpoint는 Cursor 요청 형식을 정규화합니다. 일반 endpoint에서는 tool calls와 일부 요청 형식이 실패할 수 있습니다.
4. 정확한 Model ID 추가하기
Models에서 + Add model을 선택하고 현재 모델 페이지의 전체 ID를 복사합니다. Router alias를 쓰는 경우도 표시된 전체 문법을 그대로 복사하세요. 마케팅 이름, 약칭, 오래된 가이드의 ID를 추측해 사용하지 마세요.
5. 모델을 수동으로 선택하기
Chat 또는 Agent로 돌아가 추가한 모델을 명시적으로 선택합니다. 첫 검수에서는 자동 선택을 사용하지 마세요. 답변만으로는 어느 경로가 처리했는지 알 수 없습니다.
설정이 실제로 적용됐음을 증명하는 방법
코드나 비밀 정보를 포함하지 않는 최소 Chat 요청을 보냅니다. 예를 들어 고정된 짧은 문장만 반환하도록 요청합니다. 곧바로 OpenRouter Activity를 열고 확인합니다.
- 시간이 테스트와 일치하는가.
- 기록된 모델이 Cursor에서 선택한 Model ID와 일치하는가.
- 요청이 성공했고 usage 정보가 있는가.
- 내부 검수 기록에 API Key, 전체 Prompt, 민감 코드가 없는가.
Cursor 답변은 약한 증거이고, 일치하는 Activity 기록이 더 강한 라우팅 증거입니다. 답변은 있지만 기록이 없으면 경로를 “미확인”으로 표시하세요.
팀 검수에서는 시간, 모델, 상태, 필요한 Request ID, Cursor 버전, 테스트 모드만 보관합니다. Beta 동작이 바뀌었을 때 동일한 검사를 반복하기 쉽습니다.
Chat, Agent, Tab, tools를 따로 검증하기
Chat: 먼저 기준선 만들기
OpenRouter 모델을 수동 선택하고 짧고 결정적인 프롬프트를 보냅니다. 일치하는 Activity 기록이 나타나야 Chat 통과입니다. 이 단계가 실패하면 Agent로 넘어가지 마세요. Agent는 컨텍스트, 권한, 도구라는 변수를 더합니다.
Agent: 모델 경로와 오케스트레이션 분리하기
버릴 수 있거나 쉽게 복구할 수 있는 테스트 저장소를 사용합니다. 먼저 README를 읽고 개선점을 제안하는 식의 저위험 작업을 요청하고, 파일 쓰기나 위험한 명령은 허용하지 않습니다. 두 신호를 별도로 확인합니다.
- OpenRouter Activity에 모델 요청이 있다.
- Cursor가 예상한 파일 읽기 또는 다른 도구 동작을 표시한다.
첫 번째는 모델 라우팅, 두 번째는 Cursor Agent 오케스트레이션을 증명합니다. 공식 자료는 Agent의 모든 백그라운드 보조 요청이 항상 같은 사용자 Key를 쓴다고 증명하지 않습니다. 한 번의 성공을 전체 내부 트래픽으로 확대 해석하지 마세요.
Tab: Activity에 없는 것이 정상
Tab 제안은 Cursor의 Tab Completion만 시험합니다. 공식 문서는 사용자 Key가 chat models에 적용되고 Tab은 내장 모델을 사용한다고 설명합니다. “Chat은 Activity에 있고 Tab은 없다”가 정상입니다.
Tools: endpoint와 모델 기능을 함께 확인하기
Chat 통과 후 카탈로그에서 tools 지원이 명시된 모델을 선택합니다. 테스트 저장소에서 파일 목록 보기나 작은 파일 읽기 같은 읽기 전용 작업을 요청합니다. Text Chat은 되는데 tools가 실패하면 다음을 순서대로 확인하세요.
- Base URL이 정확히
https://openrouter.ai/api/v1/cursor인가. - 선택 모델이
tools를 명시적으로 지원하는가. - Cursor가 다른 모델로 자동 전환하지 않았는가.
- Cursor에서 도구 권한을 거부하지 않았는가.
- 다른 확인된 tool-capable 모델에서도 같은 문제가 재현되는가.
증상별 문제 해결
| 증상 | 가능성 높은 원인 | 가장 저렴한 첫 확인 | 수정 후 재시험 |
|---|---|---|---|
| Key 거부·인증 실패 | 무효·폐기 Key, 공백, 다른 provider의 Key와 endpoint 혼합 | 활성 Key를 다시 복사하고 provider를 확인 | 세션 재시작 후 최소 Chat과 Activity 확인 |
| Model not found / 404 | 잘못된 ID, 불완전한 alias, 호환 경로에서 미제공 | 현재 카탈로그에서 전체 ID 복사 | 수동 선택 후 같은 Prompt 반복 |
| Chat은 되지만 Agent tools 실패 | 일반 /api/v1 또는 tools 미지원 모델 | /cursor와 supported_parameters=tools 확인 | 읽기 전용 작업 후 Activity 확인 |
| Chat은 되지만 Tab 기록 없음 | Tab은 사용자 Key를 쓰지 않음 | Key나 endpoint를 바꾸지 않기 | Chat과 Tab을 별도 기능으로 검수 |
| 402 응답 | 크레딧, Key 한도, in-flight budget 부족 | Key/credit 화면과 error metadata 확인 | 대기, 요청 축소, 크레딧 추가 후 재시도 |
| 429 응답 | OpenRouter 또는 upstream provider 제한 | Retry-After와 rate-limit headers 확인, 즉시 재전송 금지 | Exponential backoff 후 재시도 또는 다른 경로 선택 |
| Cursor 답변은 있으나 Activity 없음 | 내장 모델, Auto, 설정 미적용 | 추가 모델을 수동 선택하고 Key와 URL 재확인 | 세션 재시작 후 최소 요청 반복 |
| 설정 항목이 없음 | Cursor 버전, 플랜, UI 변경 | Cursor 업데이트와 최신 BYOK 문서 확인 | 현재 UI에서 같은 필드 관계를 구성해 재시험 |
429에서는 OpenRouter limits 문서를 따라 Retry-After를 지키고 exponential backoff를 사용하세요. Key를 더 만드는 것은 전체 용량 제한을 우회하는 확실한 방법이 아닙니다. Tools 문제는 고급 Agent 설정을 바꾸기 전에 endpoint와 모델 기능부터 고치세요.
BYOK는 Cursor에서 OpenRouter로 직접 연결하는 방식이 아니다
Cursor BYOK 문서에 따르면 최종 Prompt 구성을 위해 요청은 Cursor backend를 거칩니다. 민감한 코드를 다루는 팀은 Cursor와 선택 provider의 데이터 처리 방식을 모두 검토해야 합니다. 문제 해결 스크린샷에 실제 Key, 고객 데이터, 비공개 코드를 넣지 말고 정리된 최소 재현을 사용하세요.
플랜, 과금, UI는 바뀔 수 있습니다. Production 적용 전 공식 페이지를 다시 열어 해당 날짜의 동작을 확인하세요.
BetterToken은 별도의 설정 경로다
OpenRouter가 아니라 다른 OpenAI-compatible gateway가 필요하다면 BetterToken의 별도 Cursor 설정 문서를 사용할 수 있습니다. Base URL은 https://www.bettertoken.ai/v1이며 BetterToken API Key와 Model ID를 함께 사용해야 합니다.
OpenRouter Key를 BetterToken endpoint와 조합하거나 BetterToken Key를 https://openrouter.ai/api/v1/cursor와 조합하지 마세요. Provider를 바꾸면 최소 Chat 테스트와 해당 dashboard의 usage 확인을 다시 수행합니다.
최종 검수 순서
모델 하나 설정 → 수동 선택 → 최소 Chat 요청 → Activity 기록 확인 → Agent와 tools 시험 → Tab은 별도 내장 기능으로 검수 순서가 가장 안정적입니다. 이렇게 하면 오류를 endpoint, Key, 모델, tools, credit, rate limit 중 명확한 계층으로 좁힐 수 있습니다.
