Claude Code API 설정은 키를 먼저 붙여 넣는 일이 아닙니다. 이번 세션을 구독 로그인, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL 게이트웨이, apiKeyHelper, Bedrock, Vertex, Foundry 중 어느 경로로 돌릴지 먼저 정해야 합니다.
순서는 경로, 설정 범위, 모델, 검증입니다. /status, /config, /model을 보기 전에는 설정이 맞다고 가정하지 마세요.
| 목표 | 설정 위치 | 첫 확인 |
|---|---|---|
| 일반 대화형 사용 | 구독 로그인과 사용자/프로젝트 설정 | /status |
| 직접 API 키 | 로컬 shell의 ANTHROPIC_API_KEY | 환경 변수와 경로 |
| 호환 게이트웨이 | ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL | host, 모델명, 신뢰 경계 |
| Bedrock, Vertex, Foundry | 제공자 credentials와 route variables | 제공자, region, model |
활성 경로부터 정하기
Claude Code는 하나의 CLI처럼 보이지만 실제 세션은 여러 계약 중 하나로 움직입니다. 사람이 터미널에서 코드를 읽고 수정한다면 구독 로그인이 자연스럽습니다. CI, SDK, 자동화, Console 사용량 추적이 필요하면 API 키 경로가 맞습니다. 게이트웨이는 별도 신뢰 경계가 있을 때만 안전합니다.
설치가 아직이면 Claude Code 설치를 먼저 보세요. API 키가 과금 주체를 바꾸는지 궁금하다면 API key와 구독 과금으로 분리하세요.
credentials 우선순위
2026년 4월 21일 공식 문서 확인 기준으로 우선순위는 cloud provider credentials, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, OAuth token, /login 순서입니다. 예전에 남은 환경 변수가 새 settings보다 강할 수 있습니다.
bashtest -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY is set" test -n "$ANTHROPIC_AUTH_TOKEN" && echo "ANTHROPIC_AUTH_TOKEN is set" printenv ANTHROPIC_BASE_URL
settings.json 범위
~/.claude/settings.json은 개인 기본값, .claude/settings.json은 공유 프로젝트 규칙, .claude/settings.local.json은 로컬 전용 override에 가깝습니다. 공유 settings에는 API 키나 bearer token을 넣지 마세요.
| 범위 | 용도 | 피해야 할 것 |
|---|---|---|
| user settings | 개인 기본 동작 | 팀 강제 정책 |
| shared project settings | 권한, 명령 허용 목록 | secrets |
| local project settings | 개인 머신 override | commit 대상 값 |
| shell / CI | credentials, route flags | 추적 안 되는 팀 기본값 |
API 키와 게이트웨이
직접 Anthropic API 경로는 ANTHROPIC_API_KEY입니다.
bashexport ANTHROPIC_API_KEY="$YOUR_ANTHROPIC_API_KEY" claude /status
게이트웨이는 token과 base URL을 함께 봅니다.
bashexport ANTHROPIC_AUTH_TOKEN="$YOUR_GATEWAY_TOKEN" export ANTHROPIC_BASE_URL="https://gateway.example.com" claude /status
게이트웨이는 direct Anthropic API와 같은 계약이 아닙니다. API shape, version/beta header, 모델명, 로그, 데이터 경계를 확인하세요. 게이트웨이 선택은 Claude gateway에서 따로 판단합니다.
모델과 제공자 경로
모델 우선순위는 /model, --model, ANTHROPIC_MODEL, settings의 model입니다. Bedrock은 CLAUDE_CODE_USE_BEDROCK=1과 AWS_REGION, Vertex는 CLAUDE_CODE_USE_VERTEX=1과 GCP credentials가 핵심입니다.
검증 루프
Claude Code 안에서 다음을 확인합니다.
text/status /config /model
shell에서는 secret 값을 출력하지 말고 존재 여부만 확인하세요. 예상과 다른 경로라면 우선순위가 높은 env var부터 제거하고 새 터미널에서 다시 시작합니다.
보안과 다음 선택
실제 key, token, private URL, cloud credentials를 commit하지 마세요. 변경 전 git diff -- .claude/settings.json .claude/settings.local.json으로 공유 설정에 secret이 섞였는지 봅니다.
관련 판단은 설치, API key와 구독 과금, Claude API key free tier, 사용량 제한으로 나눠 확인하세요.
자주 묻는 질문
Claude Code에 API 키가 꼭 필요한가요?
아닙니다. 일반 대화형 사용은 구독 로그인으로 충분한 경우가 많습니다. API 키는 API 경로, CI, 자동화에 씁니다.
ANTHROPIC_AUTH_TOKEN은 무엇인가요?
Bearer token입니다. 보통 ANTHROPIC_BASE_URL과 함께 호환 게이트웨이를 사용할 때 등장합니다.
설정이 맞는지 어떻게 확인하나요?
/status, /config, /model을 실행하고, shell에서는 환경 변수 존재 여부만 확인합니다.