VS Code에서 Claude Code 사용하기

VS Code에 Claude Code 확장을 설치하고 AI in IDE API 키 하나로 연결합니다.

Anthropic 구독은 필요 없습니다. 몇 분 안에 첫 요청까지 확인할 수 있습니다. 설정은 확장 하나, 키 하나, JSON 한 블록이 전부입니다. Anthropic에 카드를 등록할 일도, 인원수만큼 플랜을 살 일도 없습니다.

이 문서는 VS Code 자체를 다룹니다. Cursor는 같은 확장과 같은 설정을 쓰므로, 주 작업 환경이 Cursor라면 Cursor에서 Claude Code 사용하기가 더 짧습니다. JetBrains는 구조가 완전히 다릅니다. 플러그인이 CLI를 내장하지 않으므로 JetBrains에서 Claude Code 사용하기를 보세요.

버전과 사전 준비

확장의 버전 번호는 그 확장이 내장한 Claude Code 버전과 같습니다. 확장 2.1.286에는 Claude Code 2.1.286이 들어 있습니다. 확장을 설치해도 claude가 PATH에 추가되지는 않습니다. 그건 별도 CLI(npm install -g @anthropic-ai/claude-code)가 필요합니다. CLI는 터미널 세션이나 claude mcp add를 쓸 때만 필요하고, 채팅 패널은 CLI 없이도 동작합니다.

확장 설치

• 바로 설치: Install for VS Code. 게시자가 지정된 상태로 확장 보기가 열리지만, 설치 확정은 직접 해야 합니다.
• 직접: Cmd+Shift+X(macOS) 또는 Ctrl+Shift+X(Windows/Linux)로 Claude Code를 검색하고 설치.
• 마켓플레이스가 막힌 환경: Visual Studio Marketplace에서 VSIX를 받아 **VSIX에서 설치…**를 사용합니다.

설치 후 패널이 보이지 않으면 명령 팔레트에서 Developer: Reload Window를 실행하세요. 확장 마켓플레이스는 서드파티 소프트웨어이며, 새로 설치할 때는 항상 확인을 요구합니다.

API 키 만들고 복사하기

1. 요금 페이지에서 플랜을 고릅니다. 하나의 계정에서 Claude, GPT, Gemini용 키를 각각 만들 수 있으며 각 키는 선택한 채널의 모델에 사용됩니다.
2. 대시보드에서 API Keys를 열고 키를 만듭니다.
3. 채널은 AWSQ 또는 CCMAX를 고릅니다. Claude Code용 채널은 이 둘뿐이고, Codex나 Gemini 키는 여기서 거부됩니다.
4. 나중에도 API Keys 목록에서 전체 키를 확인하거나 복사할 수 있습니다.

아래 모든 예시의 YOUR_DASHBOARD_API_KEY를 이 값으로 바꾸세요.

설정

설정은 두 층으로 나뉘고, 대부분 여기서 막힙니다. Dock이나 시작 메뉴로 띄운 VS Code는 셸 프로필을 물려받지 않습니다. 그래서 ~/.zshrc의 export ANTHROPIC_BASE_URL=...는 통합 터미널에서는 동작하지만 채팅 패널에는 닿지 않습니다. 값을 Claude Code 설정 파일에 적으세요. 확장과 CLI가 모두 이 파일을 읽습니다.

1. Claude Code 설정 파일

macOS와 Linux는 ~/.claude/settings.json, Windows는 C:/Users/<UserName>/.claude/settings.json입니다. 파일이나 디렉터리가 없으면 만드세요.

Copy
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를 스스로 붙이므로 https://api.aiinide.com/v1로 쓰면 /v1/v1/messages 요청이 되어 404이 납니다. 이미 settings.json이 있다면 파일을 통째로 갈아엎지 말고 env 객체를 병합하세요. 그러지 않으면 권한 규칙과 훅이 사라집니다.

2. Anthropic 로그인 화면 끄기

패널은 claude.ai 계정을 전제로 만들어져 첫 실행에 로그인 화면을 보여 줍니다. 필요 없다고 알려 줍니다.

Copy
1
"claudeCode.disableLoginPrompt": true

VS Code 사용자 settings.json(Cmd+, / Ctrl+, → "Claude Code login" 검색)에 넣거나, 확장 섹션의 Claude Code 아래에서 설정합니다.

3. 선택 사항: 모델과 타임아웃 고정

Copy
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
}

model을 빼면 확장의 기본 선택을 쓰고, 세션 중에 /model로 바꿀 수 있습니다.

4. 환경 변수를 쓰고 싶다면

셸 프로필은 터미널 세션에서 여전히 유효하고, code .로 터미널에서 편집기를 띄울 때 특히 쓸모 있습니다. macOS 또는 Linux:

Copy
1
export ANTHROPIC_BASE_URL='https://api.aiinide.com'
2
export ANTHROPIC_AUTH_TOKEN="YOUR_DASHBOARD_API_KEY"
3
export API_TIMEOUT_MS=600000
4
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

Windows는 setx ANTHROPIC_BASE_URL "https://api.aiinide.com"를 나머지 셋에도 실행한 뒤 VS Code를 다시 시작합니다. 우선순위를 조심하세요. 셸에서 export한 ANTHROPIC_AUTH_TOKEN이 설정 파일보다 우선합니다. 정보 출처는 하나만 두세요.

확인

먼저 모델 목록을 조회해 키와 Claude 채널을 확인하세요. 이 요청은 할당량을 사용하지 않습니다.

Copy
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를 입력하세요.

1. Spark 아이콘. 파일을 열고 편집기 오른쪽 위 Spark 아이콘, 또는 오른쪽 아래 상태 표시줄의 ✻ Claude Code를 클릭합니다. 로그인 화면이 나오면 안 됩니다.
2. /status. 입력창에서 /status를 실행하면 확장의 Claude Code 버전과 현재 모델이 나옵니다.
3. 편집기에서 짧은 질문을 보낸 뒤 대시보드에서 해당 키의 사용량을 확인하세요.
4. 검증한 키로 모델을 직접 호출하세요.

Copy
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}'

1. 사용량. 사용량 페이지를 열면 성공한 프롬프트가 그 키의 토큰 사용으로 잡힙니다.

문제 해결

GET /v1/models가 돌려준 정확한 ID를 사용하세요. claude-* 이름을 잘못 입력하면 설정된 기본 Claude 모델로 전달되어 해당 모델 요금이 부과될 수 있습니다.

API Error: 404

ANTHROPIC_BASE_URL을 https://api.aiinide.com으로 설정하세요. /v1을 덧붙이면 요청이 /v1/v1/messages로 전송되어 404가 반환됩니다.

API Error: 400: 잘못된 요청

• 채널 오류. Codex와 Gemini 키는 다른 경로로 인증하므로 여기서는 400이 납니다. AWSQ나 CCMAX로 키를 다시 만드세요.
• 깨진 settings.json. 쉼표가 하나 남거나 값이 잘못된 계층에 들어가면 파일을 해석하지 못하고 확장이 기본값으로 돌아갑니다. $schema 줄이 있으면 VS Code가 즉시 오류를 표시하니 내용을 검증하세요.

API 키 인증 확인

키를 진단할 때는 GET /v1/models의 상태 코드를 확인하세요. 네이티브 POST /v1/messages는 키가 없거나 유효하지 않아도 HTTP 200을 반환하고 content에 인증 오류를 표시할 수 있습니다.

• 토큰을 읽지 못함. 패널 프로세스가 settings.json을 읽지 않았습니다. 저장한 뒤 Developer: Reload Window를 실행하고, 확실하게 하려면 VS Code를 완전히 다시 시작하세요.
• ANTHROPIC_API_KEY가 우선. 셸에서 ANTHROPIC_API_KEY도 export하고 있으면 오래된 Anthropic 키가 ANTHROPIC_AUTH_TOKEN보다 우선할 수 있습니다. 해제하세요.
• 만료된 키. 만료일을 지정해 만든 키는 조용히 멈춥니다. 대시보드에서 날짜를 확인하고 교체하세요.

네트워크, TLS, 타임아웃

창별 문제

• 제한 모드. 신뢰하지 않은 워크스페이스에서는 확장이 비활성화됩니다. 폴더를 신뢰한 뒤 다시 로드하세요.
• Remote SSH, WSL, Dev Container. 설정은 원격 호스트, 즉 그 환경 안의 ~/.claude/settings.json에 있어야 합니다. 로컬 파일을 고쳐도 원격 세션에는 영향이 없습니다.
• 통합 터미널의 claude: command not found. 정상입니다. 확장은 CLI를 설치하지 않습니다. 필요하면 전역 설치하거나 채팅 패널을 계속 쓰세요.
• Spark 아이콘이 없음. 파일이 열려 있어야 합니다. 다음으로 버전(1.94.0 이상)을 확인하고, 같은 툴바 자리를 쓰는 다른 AI 확장을 잠시 끄세요.

모델과 가격

Opus 5.5 기본 요율은 100만 토큰당 입력 $4, 캐시 읽기 $0.20, 출력 $20입니다. 쿼터 소모는 AWSQ가 0.8배, CCMAX가 2배라서 같은 키라도 채널에 따라 처리할 수 있는 작업량이 다릅니다. 업스트림이 Fast 모드로 응답하면 기본·캐시 요율이 두 배가 되고, 과금은 usage.speed를 따릅니다.

• 현재 플랜과 가격: 요금
• 채널과 쿼터 관리: API Keys
• 프로토콜과 요율 세부: 설정
• Fast 모드 공식 가격: Anthropic 문서
• 공식 모델 설정 레퍼런스: code.claude.com

자주 묻는 질문

Anthropic 구독도 필요한가요? 아닙니다. 이 구성의 핵심은 ANTHROPIC_AUTH_TOKEN과 베이스 URL로 claude.ai 로그인을 대체하고, claudeCode.disableLoginPrompt로 확장이 로그인을 요구하지 못하게 하는 것입니다.

같은 키를 Cursor에서도 쓸 수 있나요? 됩니다. Cursor는 같은 확장을 돌리므로 같은 settings.json과 claudeCode.* 설정이 그대로 적용됩니다. Cursor에서 Claude Code 사용하기를 보세요.

확장이 워크스페이스 settings.json을 읽나요? 초기 권한 모드 같은 일부 설정은 사용자 범위만 봅니다. 연결 설정은 ~/.claude/settings.json에 두어 모든 워크스페이스와 창에서 같게 동작하도록 하세요.