Claude Code API 키 발급부터 VS Code 연결까지

API 키란 무엇이고 왜 필요한가

Claude Code를 VS Code에서 사용하려면 API 키(API Key)가 필요합니다. API 키는 쉽게 말해 내가 정당한 사용자임을 증명하는 비밀번호 같은 것입니다. 카페에서 와이파이 비밀번호를 입력해야 인터넷을 쓸 수 있듯이, Claude Code도 API 키가 있어야 Anthropic 서버와 통신할 수 있습니다.

API는 Application Programming Interface의 약자입니다. 프로그램끼리 대화하는 통로라고 생각하면 됩니다. VS Code의 Claude Code 확장 프로그램이 Anthropic 서버에 질문을 보내고 답변을 받는 과정, 이 전체가 API를 통해 이루어집니다. API 키가 없으면 서버가 요청을 거부하므로, Claude Code가 아무런 응답도 하지 못합니다.

한 가지 중요한 점은 API 키 사용에는 비용이 발생한다는 것입니다. Anthropic은 사용량 기반 요금제를 적용하고 있습니다. 처음 가입하면 소액의 무료 크레딧을 제공하는 경우도 있습니다. 과금 구조는 토큰(token, AI가 텍스트를 처리하는 단위) 기반으로 계산됩니다. 한글 한 글자가 보통 2~3개의 토큰에 해당하구요, 긴 대화를 많이 할수록 비용이 늘어납니다. 다만 짧은 질문 몇 번 하는 정도로는 비용이 거의 들지 않으니, 처음 시작할 때 부담을 느낄 필요는 없습니다.

API 키와 관련해서 한 가지 더 알아야 할 것이 있습니다. API 키와 Claude.ai 웹사이트의 로그인 계정은 별개입니다. Claude.ai에서 월 20달러 Pro 구독을 하더라도, API 키를 사용하는 Claude Code에는 별도의 API 크레딧이 필요합니다. 둘은 같은 Anthropic 제품이지만 과금 체계가 분리되어 있으므로 혼동하지 않는 것이 좋습니다.

제가 직접 처음 API 키를 발급받았을 때 가장 헷갈렸던 부분이 "이걸 어디에 입력하지?"였습니다. 발급 자체는 간단한데 연결 과정에서 막히는 분이 많을 겁니다. 아래에서 하나씩 따라가 보겠습니다.

 

Anthropic 콘솔에 가입하고 API 키를 발급받는 방법

먼저 Anthropic 콘솔에 접속합니다. 웹 브라우저에서 console.anthropic.com으로 이동하면 됩니다. 구글 계정이나 이메일로 가입할 수 있습니다. 가입 절차는 일반적인 웹 서비스와 동일합니다. 이메일 인증을 완료하면 대시보드 화면이 나타납니다.

대시보드에서 왼쪽 메뉴를 보면 여러 항목이 있습니다. 이 중에서 API Keys 항목을 클릭합니다. 이 페이지에서 새로운 API 키를 생성할 수 있습니다.

 

 

Create Key 버튼을 누르면 키 이름을 입력하는 창이 뜹니다. 이름은 본인이 알아볼 수 있는 것으로 자유롭게 지으면 됩니다. "vscode-claude"처럼 용도를 적어두면 나중에 여러 키를 관리할 때 편합니다. 개인 프로젝트용, 회사 프로젝트용처럼 용도별로 키를 분리해서 만들면 비용 추적이 쉬워집니다.

생성 버튼을 누르면 sk-ant-로 시작하는 긴 문자열이 화면에 표시됩니다. 이 문자열이 바로 API 키입니다. 이 키는 생성 직후 단 한 번만 표시됩니다. 페이지를 닫거나 다른 페이지로 이동하면 다시 확인할 수 없으므로, 반드시 안전한 곳에 복사해 두어야 합니다. 메모장이나 비밀번호 관리 프로그램에 저장해 두는 것을 권장합니다.

 

 

API 키를 발급받은 후에는 결제 수단도 등록해야 합니다. 콘솔의 Billing 페이지에서 신용카드 정보를 입력합니다. 무료 크레딧이 있더라도 결제 수단이 등록되어 있지 않으면 API 호출이 거부되는 경우가 있습니다. 결제 수단을 등록했다고 바로 큰 금액이 청구되는 것은 아니니 걱정하지 않으셔도 됩니다. 사용한 만큼만 청구되며, 월 사용 한도를 직접 설정할 수도 있습니다.

제가 처음 발급받을 때 키를 복사하지 않고 창을 닫아버린 적이 있습니다. 결국 키를 삭제하고 새로 만들었습니다. 큰 문제는 아니지만 번거로우니, 처음에 바로 복사하는 습관을 들이는 것이 좋습니다.

 

VS Code에서 Claude Code API 키를 연결하는 방법

VS Code에 Claude Code 확장 프로그램이 이미 설치되어 있다는 전제로 진행합니다. 확장이 아직 없다면 VS Code 마켓플레이스에서 "Claude Code"를 검색해서 먼저 설치해 주세요.

API 키를 연결하는 방법은 크게 두 가지입니다. 환경변수 설정 방식과 VS Code 설정에서 직접 입력하는 방식입니다.

방법 1: 환경변수 설정 (권장)

환경변수는 운영체제 전체에서 사용할 수 있는 설정값입니다. 한 번 등록해두면 VS Code뿐 아니라 터미널에서 Claude Code를 직접 실행할 때도 자동으로 키를 인식합니다.

Windows에서 환경변수를 설정하는 방법은 다음과 같습니다.

1. Windows 검색창에 "환경 변수"를 입력합니다.

2. "시스템 환경 변수 편집"을 엽니다.

3. 아래쪽 "환경 변수" 버튼을 클릭합니다.

4. 사용자 변수에서 "새로 만들기"를 선택합니다.

5. 변수 이름에 ANTHROPIC_API_KEY를 입력합니다.

6. 변수 값에 복사해 둔 API 키를 붙여넣습니다.

7. 확인을 누르고 VS Code를 재시작합니다.

macOS나 Linux에서는 터미널 설정 파일에 추가합니다.

# bash 사용자
echo 'export ANTHROPIC_API_KEY="sk-ant-여기에키입력"' >> ~/.bashrc
source ~/.bashrc

# zsh 사용자
echo 'export ANTHROPIC_API_KEY="sk-ant-여기에키입력"' >> ~/.zshrc
source ~/.zshrc

 

 

방법 2: VS Code 설정에서 직접 입력

VS Code에서 Ctrl + ,(macOS는 Cmd + ,)을 눌러 설정 화면을 엽니다. 검색창에 "claude code"를 입력하면 관련 설정 항목이 나타납니다. "API Key" 입력란에 키를 직접 붙여넣으면 됩니다.

두 방법 모두 결과는 같습니다. 다만 환경변수 방식이 더 안전합니다. VS Code 설정 파일은 프로젝트의 .vscode/settings.json에 저장될 수 있는데, 이 파일이 Git 저장소에 포함되면 API 키가 다른 사람에게 노출될 수 있습니다. API 키가 타인에게 노출되면 내 계정으로 요금이 청구될 수 있으니, 환경변수 방식을 추천합니다.

만약 Git을 사용하고 있다면 .gitignore 파일에 .vscode/settings.json을 추가하거나, API 키를 환경변수로 관리하는 것이 안전합니다. 보안 사고는 대부분 "설마 이런 일이"하는 순간에 발생하므로, 처음부터 안전한 방식으로 설정해 두는 것을 권장합니다.

 

Claude Code API 키 연결 후 확인해야 할 것들

설정을 마쳤으면 제대로 연결되었는지 확인해야 합니다. VS Code에서 Claude Code 패널을 열고 간단한 질문을 입력해 보면 됩니다. "안녕하세요"라고 보냈을 때 응답이 돌아오면 연결에 성공한 것입니다.

만약 오류가 발생한다면 아래 표를 참고해서 원인을 파악할 수 있습니다.

| 에러 메시지 | 원인 | 해결 방법 |

|-------------|------|-----------|

| Invalid API Key | 키 값이 잘못됨 | 공백 없이 정확히 재입력 |

| Authentication failed | 인증 실패 | 키를 삭제하고 새로 발급 |

| Insufficient credits | 크레딧 부족 | Billing 페이지에서 결제 수단 등록 |

| Connection refused | 네트워크 문제 | 방화벽/프록시 설정 확인 |

가장 흔한 오류는 "Invalid API Key"입니다. 키를 복사할 때 앞뒤에 공백이나 줄바꿈 문자가 들어가는 경우가 많습니다. 키를 다시 붙여넣을 때 공백 없이 정확하게 입력했는지 점검해 보면 대부분 해결됩니다.

"Insufficient credits" 에러는 결제 수단이 등록되지 않았거나 크레딧이 부족할 때 발생합니다. Anthropic 콘솔의 Billing 페이지에서 결제 정보를 확인하면 됩니다. 사용 한도를 설정하는 기능도 있으니, 예상치 못한 과금이 걱정된다면 월별 한도를 미리 설정해 두는 것이 좋습니다.

 

 

API 키 관리에서 한 가지 더 알아둘 점이 있습니다. 사용하지 않는 키는 콘솔에서 비활성화하거나 삭제하는 것이 안전합니다. 키가 유출되었다고 의심되면 즉시 삭제하고 새로 발급받으면 됩니다. 기존 키를 삭제해도 새 키를 만들어 다시 연결하면 되니 부담 없이 관리하면 됩니다.

제가 전체 과정을 처음부터 끝까지 진행해본 결과, 가입부터 연결 확인까지 걸리는 시간은 10분 정도입니다. 환경변수 설정이 처음에는 낯설게 느껴질 수 있지만, 한 번 해두면 이후 프로젝트에서 매번 키를 입력할 필요가 없어서 훨씬 편리합니다. VS Code를 열면 바로 Claude Code를 사용할 수 있는 환경이 갖춰집니다.