Claude Code의 인증 우선순위 이해하기
Claude Code를 사용할 때, 예상치 못한 API 요금 청구를 피하고 의도한 계정을 사용하고 있는지 확인하기 위해 인증 방법의 우선순위를 이해하는 것이 중요합니다.
중요: 시스템에 ANTHROPIC_API_KEY 환경 변수가 설정되어 있으면, Claude Code는 Claude.ai 구독(Pro, Max, Team 또는 Enterprise) 대신 이 API 키를 인증에 사용하므로, 구독에 포함된 사용량 대신 API 사용 요금이 청구됩니다.
인증 작동 방식
Claude Code는 인증된 구독보다 환경 변수 API 키를 우선시합니다.
이는 인증 방법 선택에 유연성을 제공하도록 설계된 의도적인 동작입니다.
API 키가 환경 변수로 설정되면, 해당 키와 연결된 API 계정을 사용하여 API 종량제 요금으로 청구됩니다.
이는 Claude Code에 claude.ai 구독이나 다른 Console 계정으로 로그인되어 있어도 발생합니다.
모범 사례
Claude 구독으로 Claude Code를 사용하려면: ANTHROPIC_API_KEY 환경 변수를 설정하지 않은 상태로 유지하세요.
이는 예상치 못한 API 요금 청구를 방지하고 구독에 포함된 사용량을 사용하도록 보장합니다.
특정 API 키를 가끔 사용해야 하는 경우, 필요할 때만 임시로 설정하세요.
Claude Code에서 /status를 주기적으로 실행하여 현재 인증 방법을 확인하세요.
인증 충돌 경고
Claude Code는 인증된 구독과 환경 변수 API 키 간에 충돌이 있을 때 알려줍니다:
초기 설정 중에 환경 변수에서 API 키가 감지되면, Claude Code는 사용할 인증 방법을 확인하도록 요청합니다
성공적으로 로그인한 후, 두 자격증명이 모두 활성화되어 있으면 알림이 표시되어 예상치 못한 API 요금 청구의 가능성을 경고합니다
현재 구성 확인
API 키가 환경 변수로 설정되어 있는지 확인하려면 Claude Code에서 /status를 실행하세요. 이는 현재 활성화된 인증 방법을 표시합니다.
환경 변수를 직접 확인하려면 터미널(Claude Code 외부)에서 다음 명령 중 하나를 실행하세요:
macOS/Linux:
echo $ANTHROPIC_API_KEY
Windows CMD:
echo %ANTHROPIC_API_KEY%
Windows PowerShell:
echo $env:ANTHROPIC_API_KEY
API 키를 임시로 설정
현재 터미널 세션에만 API 키를 사용해야 하는 경우:
macOS/Linux:
export ANTHROPIC_API_KEY='your-api-key-here'
Windows CMD:
set ANTHROPIC_API_KEY=your-api-key-here
Windows PowerShell:
$env:ANTHROPIC_API_KEY="your-api-key-here"
API 키 환경 변수를 영구적으로 설정
macOS/Linux:
zsh의 경우 (macOS의 기본값):
bash
# 셸 구성 파일에 추가
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.zshrc
# 변경 사항 적용
source ~/.zshrc
bash의 경우:
bash
# 셸 구성 파일에 추가
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bash_profile
# 변경 사항 적용
source ~/.bash_profile
Windows:
시스템 속성 → 고급 → 환경 변수 열기
"사용자 변수" 아래에서 "새로 만들기" 클릭
변수 이름: ANTHROPIC_API_KEY
변수 값: your-api-key-here
확인을 클릭하고 터미널을 다시 시작하세요
API 키 환경 변수 제거
macOS/Linux (임시):
unset ANTHROPIC_API_KEY
macOS (영구):
# 구성 파일에서 제거
sed -i '' '/ANTHROPIC_API_KEY/d' ~/.zshrc
source ~/.zshrc
Linux (영구)
sed -i '/ANTHROPIC_API_KEY/d' ~/.zshrc
Windows CMD:
set ANTHROPIC_API_KEY=
Windows PowerShell:
Remove-Item Env:ANTHROPIC_API_KEY
Windows (영구): 시스템 환경 변수 설정에서 변수를 삭제하세요.