Browse documentation
Cursor에서 Claude Code 사용하기
Cursor 안에서 Claude Code 확장을 AI in IDE API 키 하나로 실행합니다.
Cursor는 VS Code 포크이므로 공식 확장이 그대로 설치되고 동작도 같습니다. 다만 Cursor는 자체 AI 기능, 자체 확장 레지스트리, 자체 설정 동기화를 갖고 있고, 이 세 가지가 트러블슈팅의 내용을 바꿉니다.
순정 VS Code를 쓴다면 VS Code에서 Claude Code 사용하기를 읽으세요. 설정 블록이 동일하고 일반적인 경우는 그쪽에서 다룹니다. 이 문서는 Cursor 내부의 차이에 집중합니다.
버전과 사전 준비
| 항목 | 요구 사항 | 비고 |
|---|---|---|
| Cursor | VS Code 1.94.0 이상 기반 빌드 | Cursor → About Cursor에 VS Code 기반 버전이 나옵니다 |
| Claude Code 확장 | Open VSX 또는 내장 마켓의 최신 빌드 | 버전은 내장 CLI를 따릅니다 |
| AI in IDE 키 | AWSQ 또는 CCMAX 채널 | 대시보드 |
| Anthropic 계정 | 불필요 | API 키가 로그인을 대체 |
Cursor도 확장도 claude를 PATH에 넣지 않습니다. 터미널 세션이나 claude mcp add를 쓸 때만 CLI를 따로 설치하세요.
확장 설치
- 바로 설치: Install for Cursor. Cursor가 확장 ID를 해석한 뒤 평소의 확인 단계를 보여 줍니다.
- 직접:
Cmd+Shift+X/Ctrl+Shift+X로 Claude Code를 검색하고 설치. - 검색해도 안 나오면 Cursor의 마켓 보기가 필터링되어 있을 수 있습니다. Open VSX Registry에서 설치하세요. Visual Studio Marketplace를 쓸 수 없는 포크용으로 배포된 같은 빌드입니다.
설치 후 Spark 아이콘이 보이지 않으면 Developer: Reload Window를 실행하세요. 아이콘은 파일이 열려 있을 때만 나타나고, 폴더만 연 상태로는 나오지 않습니다.
API 키 만들고 복사하기
API Keys를 열어 키를 만들고 채널에서 AWSQ 또는 CCMAX를 고릅니다. Claude Code용 채널은 이 둘이고, Codex나 Gemini 키는 다른 엔드포인트로 인증하기 때문에 여기서 실패합니다. 나중에도 API Keys 목록에서 전체 키를 확인하거나 복사할 수 있습니다.
아래 예시에서 YOUR_DASHBOARD_API_KEY는 그 값의 자리표시자입니다.
설정
1. 연결 설정
~/.claude/settings.json(macOS/Linux) 또는 C:/Users/<UserName>/.claude/settings.json(Windows)을 만들거나 기존 내용에 병합합니다.
1 {2 "$schema": "https://json.schemastore.org/claude-code-settings.json",3 "env": {4 "ANTHROPIC_BASE_URL": "https://api.aiinide.com",5 "ANTHROPIC_AUTH_TOKEN": "YOUR_DASHBOARD_API_KEY",6 "API_TIMEOUT_MS": "600000",7 "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"8 }9 }
ANTHROPIC_BASE_URL은 호스트 이름에서 끝냅니다. Claude Code가 /v1/messages를 직접 붙이므로 여기에 /v1을 더하면 /v1/v1/messages가 됩니다.
이 파일은 확장과 CLI가 공유합니다. 그래서 프록시 구성을 두기에 맞는 자리입니다. Cursor 업데이트, 프로필 전환, 창 재로드를 거쳐도 남습니다.
2. 로그인 화면 끄기
확장은 claude.ai 계정을 전제로 합니다. Cursor 사용자 settings.json(Cmd+, / Ctrl+,)에 추가하세요.
1 "claudeCode.disableLoginPrompt": true
이게 없으면 패널을 처음 열 때 Sign in이 뜨고 확장이 베이스 URL까지 가지 못합니다.
3. Cursor 자체 AI와 섞지 않기
Cursor 내장 채팅과 Tab 완성은 별개 제품이고 이 키를 공유하지 않습니다. 실무적으로 두 가지 결과가 있습니다.
- 패널 두 개, 과금 경로 두 개. Cursor 자체 Claude 접근은 Cursor가 과금하고, Claude Code 패널은 AI in IDE가 키 쿼터에서 과금합니다. 작업마다 한쪽으로 통일하지 않으면 두 대시보드의 사용량이 모두 이상해 보입니다.
settings.json충돌. Cursor는 확장 설정을 자체 프로필에 저장하므로 프로필을 바꾸면claudeCode.*값이 조용히 사라질 수 있습니다. 전환 후 반드시 확인하세요.
4. 선택 사항: 모델과 셸 일치
1 {2 "model": "claude-sonnet-5-5",3 "env": {4 "ANTHROPIC_BASE_URL": "https://api.aiinide.com",5 "ANTHROPIC_AUTH_TOKEN": "YOUR_DASHBOARD_API_KEY"6 }7 }
macOS에서 Dock으로 띄운 Cursor는 셸 프로필이 아니라 시스템 환경을 물려받습니다. ~/.zshrc의 export는 통합 터미널에는 닿지만 채팅 패널에는 닿지 않습니다. 위 파일이 그 해법입니다. 셸 export에 의존하려면 터미널에서 cursor .로 실행하면 상속됩니다.
확인
먼저 모델 목록을 조회해 키와 Claude 채널을 확인하세요. 이 요청은 할당량을 사용하지 않습니다.
1 curl --globoff -i 'https://api.aiinide.com/v1/models' \2 -H "x-api-key: YOUR_DASHBOARD_API_KEY" \3 -H "anthropic-version: 2023-06-01"
HTTP 200이면 모델 목록이 반환됩니다. 401은 키 누락, 무효 또는 만료를, 400은 채널 불일치를 뜻합니다. 아래 Messages 예시에는 목록에 있는 모델 ID를 입력하세요.
- 로그인 없이 패널이 열림. Spark 아이콘으로 패널을 엽니다. 여기서 로그인을 요구하면
disableLoginPrompt가 사용자 설정에 없는 것입니다. - 입력창에서 **
/status**를 실행해 버전과 모델을 확인합니다. - 편집기에서 짧은 질문을 보낸 뒤 대시보드에서 해당 키의 사용량을 확인하세요.
- 검증한 키로 모델을 직접 호출하세요.
1 curl --globoff 'https://api.aiinide.com/v1/messages' \2 -H "x-api-key: YOUR_DASHBOARD_API_KEY" \3 -H "anthropic-version: 2023-06-01" \4 -H "Content-Type: application/json" \5 -d '{"model":"MODEL_ID_FROM_LIST","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'
- 사용량. 프롬프트가 성공하면 사용량 페이지에서 그 키의 수치가 올라갑니다.
문제 해결
GET /v1/models가 돌려준 정확한 ID를 사용하세요. claude-* 이름을 잘못 입력하면 설정된 기본 Claude 모델로 전달되어 해당 모델 요금이 부과될 수 있습니다.
API Error: 404
ANTHROPIC_BASE_URL을 https://api.aiinide.com으로 설정하세요. /v1을 덧붙이면 요청이 /v1/v1/messages로 전송되어 404가 반환됩니다.
API Error: 400
- Cursor에 오래된 빌드가 설치됨. 포크 전용 레지스트리에서 온 확장은 뒤처질 수 있습니다. 확장 보기에서 업데이트하고 다시 로드하세요.
settings.json형식 오류. Cursor는 파일이 깨졌다고 알려 주지 않고 그냥 무시합니다. Cursor에서 열어 보세요.$schema줄이 있으면 검증 오류가 바로 표시됩니다.
API 키 인증 확인
키를 진단할 때는 GET /v1/models의 상태 코드를 확인하세요. 네이티브 POST /v1/messages는 키가 없거나 유효하지 않아도 HTTP 200을 반환하고 content에 인증 오류를 표시할 수 있습니다.
- 로그인이 남아 있음. 이전에 Claude 계정으로 로그인했다면
/logout하고disableLoginPrompt를 설정한 뒤 다시 로드하세요. - 환경에 다른
ANTHROPIC_AUTH_TOKEN이 있음. Cursor의 환경은 셸, 프로필, 실행 에이전트에서 올 수 있습니다. Cursor 통합 터미널에서echo $ANTHROPIC_AUTH_TOKEN을 실행해 옛 값이 나오면 그게 우선입니다. - 키 만료 또는 채널 변경. CCMAX에서 Codex로 바꾼 키는 여기서 반드시 실패합니다. 채널을 고치지 말고 새로 만드세요.
Cursor 특유의 네트워크 문제
| 증상 | 원인 | 해결 |
|---|---|---|
| 패널은 되는데 Tab 완성이 실패(또는 반대) | 두 AI 클라이언트 중 하나만 프록시 설정됨 | Cursor의 HTTP 프록시와 HTTPS_PROXY는 별개입니다. 둘 다 설정하세요 |
| Cursor 업데이트 후 확장이 사라짐 | 프로필 초기화 | 확장 보기에서 다시 설치하고 claudeCode.* 설정도 복구 |
| 첫 응답만 매우 느리고 이후 정상 | Cursor 인덱서가 CPU와 네트워크를 점유 | 인덱싱이 끝날 때까지 기다리거나 큰 디렉터리를 제외 |
Cursor에서만 Certificate is not trusted | TLS를 검사하는 프록시 CA를 Cursor가 신뢰하지 않음 | settings.json의 env에 NODE_EXTRA_CA_CERTS를 넣고 프록시 루트 CA 지정 |
| Remote-SSH 창에서 타임아웃까지 멈춤 | 설정이 로컬에 남아 있음 | 원격 호스트의 ~/.claude/settings.json을 수정 |
다른 확장과의 충돌
Cursor 환경에는 AI 확장이 여러 개 깔려 있는 경우가 많습니다. 채팅 패널이나 같은 단축키를 등록하는 두 확장은 서로 자리를 다툽니다. Cmd+Esc가 Claude Code 대신 Cursor 자체 채팅을 열거나, 툴바 Spark 아이콘이 가려질 수 있습니다. 먼저 상대를 잠시 끄고 원인을 확인한 뒤, 하나만 남기거나 키보드 단축키 편집기에서 다시 바인딩하세요.
모델과 가격
| 모델 | 채널 | 용도 |
|---|---|---|
claude-opus-5-5 / claude-opus-5.5 | AWSQ, CCMAX | 복잡한 리팩터링, 긴 자율 실행 |
claude-sonnet-5-5 / claude-sonnet-5.5 | AWSQ, CCMAX | 일상 기본값 |
claude-haiku-4-5-20251001 | AWSQ, CCMAX | 빠른 수정, 저렴한 확인 |
Opus 5.5 표시 요율은 100만 토큰당 입력 $4, 캐시 읽기 $0.20, 출력 $20입니다. 쿼터 소모는 AWSQ가 0.8배, CCMAX가 2배입니다. 업스트림이 Fast 모드로 처리하면 기본·캐시 요율이 두 배가 됩니다.
- 플랜과 쿼터: 요금
- 키 관리: API Keys
- 엔드포인트와 요율: 설정
- 공식 확장 레퍼런스: code.claude.com VS Code (Cursor 지원도 같은 페이지에 있음)
자주 묻는 질문
Cursor가 공식 지원 대상인가요? Anthropic은 확장을 Visual Studio Marketplace와 Open VSX에 배포하고 문서에서 Cursor를 설치 대상으로 안내합니다. Anthropic 입장에서 마켓플레이스는 자사가 운영하지 않는 서드파티 소프트웨어입니다.
Cursor 자체 Claude 접근과 이 확장을 함께 설치해야 하나요? 두 과금 경로를 동시에 쓰고 싶을 때만 그렇습니다. 사용량을 일관되게 보려면 하나로 통일하세요.
키를 동료와 공유해도 되나요? 개인 키를 공유하기보다 키의 쿼터와 만료 필드로 배분하고, 사용량 페이지에서 키별로 확인하세요.