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.ai 구독 또는 다른 Console 계정으로 Claude Code에 로그인되어 있어도 발생합니다.
모범 사례
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 (영구): 시스템 환경 변수 설정에서 변수를 삭제하세요.
피해야 할 일반적인 문제
셸 구성 파일에 환경 변수를 설정하고 잊어버리는 경우.
환경 변수를 변경한 후 터미널을 재시작하지 않는 경우.
환경에 API 키가 구성되어 있는데 구독을 사용하고