로그인·API 키 설정

💡 이 챕터에서 배우는 것: 내게 맞는 인증 방식 고르기, 구독 로그인, API 키 발급, 이중 과금 함정 피하기

전제 지식

설치 가이드를 먼저 완료해야 합니다.

먼저: 나는 어느 쪽인가?

가장 많이 하는 오해가 **"Claude Code를 쓰려면 API 키부터 발급받아야 한다"**는 것입니다. 아닙니다.

내 상황	인증 방식	API 키
Claude 유료 구독 중 (Pro·Max·Team·Enterprise)	브라우저 로그인	불필요
구독 없이 사용량만큼 내고 싶다	Claude Console API 키	필요
회사가 Bedrock·Vertex·Foundry 사용	클라우드 프로바이더 자격증명	별도 경로

구독자라면 여기서 끝

Pro든 Max든 구독이 있으면 API 키를 만들 필요가 없습니다. 아래 "구독으로 로그인하기"만 읽고 넘어가세요. 콘솔 가입도, 카드 등록도, 크레딧 충전도 필요 없습니다.

무료 플랜은 불가

공식 문서 기준 Claude Code는 Pro·Max·Team·Enterprise·Console 계정에서 동작합니다. 무료 Claude.ai 플랜에는 Claude Code 사용이 포함되지 않습니다.

방법 1: 구독으로 로그인하기 (권장)

첫 실행

설치 후 터미널에서 실행하면 브라우저 창이 열립니다.

claude

브라우저에서 Claude 계정으로 로그인하면 끝입니다. 자격증명이 저장되므로 매번 로그인할 필요는 없습니다.

브라우저가 안 열릴 때

WSL2, SSH 원격 접속, 컨테이너 환경에서는 브라우저가 자동으로 열리지 않을 수 있습니다.

c를 눌러 로그인 URL을 복사
브라우저에 붙여넣어 로그인
브라우저가 보여주는 로그인 코드를 터미널의 Paste code here if prompted에 붙여넣기

이때 붙여넣는 것은 로그인 코드이지 API 키가 아닙니다.

계정 전환·로그아웃

/login    # 계정 전환 또는 재인증
/logout   # 로그아웃
/status   # 현재 어떤 방식으로 인증돼 있는지 확인

브라우저를 쓸 수 없는 환경 (CI 등)

CI·자동화 스크립트처럼 브라우저 로그인이 불가능한 환경에서도, API 키 대신 구독 기반 장기 토큰을 쓸 수 있습니다.

claude setup-token

1년짜리 토큰이 발급되며 CLAUDE_CODE_OAUTH_TOKEN 환경변수로 사용합니다. Pro·Max·Team·Enterprise 플랜이 필요합니다.

🔴 구독자가 가장 많이 당하는 함정

구독이 있는데 ANTHROPIC_API_KEY도 설정해뒀다면, API 키가 이깁니다.

공식 문서에 명시된 인증 우선순위는 다음과 같습니다. 위쪽이 이깁니다.

순위	인증 방식
1	클라우드 프로바이더 자격증명 (Bedrock·Vertex·Foundry 설정 시)
2	`ANTHROPIC_AUTH_TOKEN`
3	`ANTHROPIC_API_KEY`
4	`apiKeyHelper` 스크립트
5	`CLAUDE_CODE_OAUTH_TOKEN`
6	구독 로그인 (`/login`) ← 가장 낮음

즉 구독료를 내고 있어도, 예전에 넣어둔 API 키가 환경변수에 남아 있으면 그쪽으로 과금됩니다. 구독 사용량은 그대로 남아 있는데 토큰당 요금이 따로 청구되는 것입니다.

확인하고 되돌리는 방법

/status

Login method 행이 보이면 → 구독으로 사용 중 (정상)
API key 행이 보이면 → API 키로 과금 중

키를 쓰고 싶지 않다면 환경변수를 지웁니다.

unset ANTHROPIC_API_KEY          # macOS/Linux (현재 세션)

.zshrc·.bashrc·Windows 사용자 환경변수에 영구 저장해뒀다면 그 줄도 지워야 합니다.

대화형 모드의 동작

대화형 모드에서는 환경변수에 키가 있을 때 사용 여부를 한 번 묻고 선택을 기억합니다. 나중에 /config의 "Use custom API key" 토글로 바꿀 수 있습니다(환경변수가 설정돼 있을 때만 표시). 단 비대화형 -p 모드에서는 키가 있으면 항상 사용됩니다.

방법 2: API 키 발급 (구독이 없을 때)

구독 없이 사용한 만큼만 결제하려면 API 키를 발급합니다.

1단계: Claude Console 접속

platform.claude.com 접속 → 계정 생성 또는 로그인

2단계: API 키 생성

API Keys 메뉴 → Create Key → 키 이름 입력 (예: claude-code-personal) → 생성

3단계: 키 복사·보관

생성된 키(sk-ant-api03-...)를 복사합니다. 이 화면을 벗어나면 다시 볼 수 없으니 안전한 곳에 보관하세요.

4단계: 환경변수로 설정

export ANTHROPIC_API_KEY="sk-ant-api03-..."
claude

셸 설정 파일에 영구 저장하려면:

# macOS (zsh, 기본 셸)
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.zshrc && source ~/.zshrc

# macOS/Linux (bash)
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-..."' >> ~/.bashrc && source ~/.bashrc

# Windows PowerShell
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-...", "User")

구독자는 위 설정을 하지 마세요

구독이 있는데 ANTHROPIC_API_KEY를 영구 저장하면 앞서 설명한 대로 구독 대신 API 종량 과금으로 넘어갑니다.

요금 이해하기

구독으로 쓸 때

플랜 사용량 한도 안에서 추가 과금이 없습니다. 세션 비용 숫자는 청구와 무관합니다.

한도는 5시간 롤링 창 + 주간 창 2중 구조이며, 모든 모델이 공유합니다. 모델을 바꿔도 한도가 회복되지 않습니다.
Opus는 별도 한도가 추가로 있습니다. Opus 한도에만 걸린 경우 /model로 다른 모델로 바꾸면 작업을 이어갈 수 있습니다.
Claude Code 사용량은 claude.ai 웹·Desktop과 같은 한도를 공유합니다.
한도를 다 쓴 뒤에도 계속하고 싶다면 /usage-credits로 사용 크레딧을 켜서 표준 API 요금으로 이어서 쓸 수 있습니다(월 지출 한도·자동충전 설정 가능).

플랜별 구체적 한도 수치

Pro·Max의 정확한 주간 한도 수치는 공식 문서에 공개돼 있지 않습니다. 플랜 가격은 claude.com/pricing에서 확인하세요.

API 키로 쓸 때 (토큰당 과금)

모델	입력 (/MTok)	출력 (/MTok)
Haiku 4.5	$1	$5
Sonnet 5	$2 (2026-08-31까지 도입가)	$10
Sonnet 5 (2026-09-01~)	$3	$15
Opus 4.8	$5	$25
Fable 5	$10	$50

토큰 계산이 달라졌습니다

Opus 4.7 이후 모델(Sonnet 5·Fable 5 포함)은 새 토크나이저를 사용해, 같은 글이 약 30% 더 많은 토큰으로 계산됩니다. 이전 모델과 비용을 비교할 때 감안해야 합니다.

공식 문서가 제시하는 실사용 참고치는 개발자 1인당 활동일 기준 약 $13, 월 $150~250이며, 사용자의 90%가 활동일당 $30 미만입니다(기업 환경 기준).

프롬프트 캐싱

같은 컨텍스트를 반복해서 보낼 때 비용을 줄여줍니다.

캐시 읽기: 기본 입력 단가의 0.1배 (입력 토큰 기준 90% 저렴)
캐시 쓰기: 1.25배(5분 캐시) / 2배(1시간 캐시)

쓰기 비용이 먼저 들기 때문에 5분 캐시는 1회 읽기, 1시간 캐시는 2회 읽기부터 이득입니다. 출력 토큰에는 적용되지 않습니다.

비용 관리

지출 한도 설정 — Console에서 월 사용 한도 지정
가벼운 작업은 Haiku로 — /model haiku
/usage로 사용량 확인 — /cost는 같은 기능의 별칭입니다

보안 모범 사례

.gitignore에 반드시 추가:

.env
*.env

절대 하지 말아야 할 것:

API 키를 코드에 하드코딩
GitHub 등 공개 저장소에 키 업로드

키가 유출됐다면:

즉시 Console → API Keys → 해당 키 비활성화
새 키 발급
모든 환경에서 키 교체

핵심 정리

구독자(Pro·Max·Team·Enterprise)는 API 키가 필요 없습니다. claude 실행 → 브라우저 로그인이면 끝
첫 실행은 API 키 입력창이 아니라 브라우저 로그인입니다. 계정 전환은 /login
🔴 구독이 있는데 ANTHROPIC_API_KEY가 설정돼 있으면 키가 우선해서 이중 과금됩니다. /status로 확인하고, 필요 없으면 환경변수를 지우세요
구독 한도는 5시간 + 주간 2중 구조이고 claude.ai 웹과 공유합니다. Opus만 별도 한도
API 키 방식은 토큰당 과금 — 새 토크나이저로 같은 글이 약 30% 더 많은 토큰으로 계산됩니다

📬 Claude Code tips, delivered

설정부터 실전 워크플로우까지 — 실제 사용 경험을 정리해서 보내드립니다. 무료 구독 →

이 페이지에 오류가 있나요? 오류 제보하기 →

먼저: 나는 어느 쪽인가?​

방법 1: 구독으로 로그인하기 (권장)​

첫 실행​

계정 전환·로그아웃​

브라우저를 쓸 수 없는 환경 (CI 등)​

🔴 구독자가 가장 많이 당하는 함정​

확인하고 되돌리는 방법​

방법 2: API 키 발급 (구독이 없을 때)​

1단계: Claude Console 접속​

2단계: API 키 생성​

3단계: 키 복사·보관​

4단계: 환경변수로 설정​

요금 이해하기​

구독으로 쓸 때​

API 키로 쓸 때 (토큰당 과금)​

프롬프트 캐싱​

비용 관리​

보안 모범 사례​

핵심 정리​