인증 설정
기준일: 2026-06-07
난이도: 초급
공식 기준: Authentication, Overview
Claude Code 인증은 이제 API 키만의 문제가 아닙니다. 개인은 claude 첫 실행 시 브라우저 로그인으로 시작하고, 팀은 Claude for Teams/Enterprise, Claude Console, Amazon Bedrock, Google Vertex AI, Microsoft Foundry 중 하나로 인증 방식을 정합니다.
핵심 개념
| 인증 방식 | 적합한 상황 | 확인 포인트 |
|---|---|---|
| Claude.ai 브라우저 로그인 | Pro, Max, Team, Enterprise 사용자의 일반 CLI 사용 | claude 실행 후 브라우저 OAuth |
| Claude Console API 키 | API 기반 과금과 Console 멤버 관리를 쓰는 조직 | ANTHROPIC_API_KEY 우선순위 |
| Cloud provider 인증 | Bedrock, Vertex AI, Microsoft Foundry를 쓰는 조직 | provider별 환경 변수와 정책 |
apiKeyHelper |
Vault나 단기 토큰을 동적으로 가져오는 조직 | helper TTL, 401 재시도 |
CLAUDE_CODE_OAUTH_TOKEN |
CI, 스크립트, 브라우저 없는 환경 | claude setup-token으로 생성 |
자격 증명은 macOS Keychain, Linux/Windows의 사용자별 .claude 자격 증명 파일, 또는 환경 변수/credential helper를 통해 관리됩니다. 여러 자격 증명이 동시에 있을 때는 cloud provider, bearer token, API key, helper, long-lived OAuth token, subscription OAuth 순으로 선택될 수 있으므로 /status로 실제 활성 방식을 확인합니다.
선택 기준
| 상황 | 추천 |
|---|---|
| 개인 개발자가 처음 시작 | claude 실행 후 Claude.ai 로그인 |
| 팀이 중앙 청구와 계정 관리를 원함 | Claude for Teams 또는 Enterprise |
| Console 멤버와 API 키로 운영 | Claude Console 인증 |
| 조직이 Bedrock/Vertex/Foundry를 표준으로 사용 | cloud provider 인증 |
CI에서 claude -p 또는 Agent SDK 실행 |
claude setup-token 또는 안전하게 주입한 API 키 |
| 프록시/게이트웨이를 거쳐야 함 | ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, apiKeyHelper 검토 |
실습
첫 로그인:
cd your-project
claude
브라우저가 자동으로 열리지 않으면 터미널에서 로그인 URL을 복사해 브라우저에 붙여 넣습니다. WSL2, SSH, 컨테이너처럼 로컬 callback이 닿지 않는 환경에서는 브라우저에 표시된 코드를 터미널 프롬프트에 붙여 넣는 흐름을 사용합니다.
현재 인증 상태 확인:
/status
다시 로그인해야 할 때:
/logout
CI 또는 headless 환경용 장기 토큰:
claude setup-token
export CLAUDE_CODE_OAUTH_TOKEN="your-token"
claude -p "테스트 실패 원인을 요약해줘"
API 키 기반 실행이 필요한 경우:
export ANTHROPIC_API_KEY="sk-ant-..."
claude -p "현재 프로젝트의 테스트 명령을 찾아 실행 계획을 세워줘"
게이트웨이 또는 bearer-token 프록시를 쓰는 경우:
export ANTHROPIC_AUTH_TOKEN="your-bearer-token"
export ANTHROPIC_BASE_URL="https://gateway.example.com"
도구에 입력할 프롬프트
내 Claude Code 인증 상태를 점검해줘.
/status 기준으로 활성 인증 방식, 환경 변수 충돌 가능성,
CI에서 필요한 토큰 방식, API 키가 subscription 로그인을 덮어쓸 위험을 분리해서 알려줘.
토큰 값은 출력하지 말고 변수명과 확인 명령만 제안해줘.
체크리스트
- 첫 실행 명령이
claude인지 확인했다. - 개인 사용과 팀/조직 인증 방식을 구분했다.
-
ANTHROPIC_API_KEY가 subscription OAuth를 의도치 않게 덮어쓰지 않는지 확인했다. - CI에는
CLAUDE_CODE_OAUTH_TOKEN또는 안전하게 주입한 API 키만 쓴다. - credential helper를 쓸 경우 TTL, 실패 시 동작, 실행 시간을 점검했다.
- 프록시/게이트웨이 환경에서는
ANTHROPIC_BASE_URL과 bearer token 방식을 문서화했다. - 인증 오류가 나면
/status,/logout, 환경 변수 해제 순서로 확인한다.
다음 단계
- 빠른 시작에서 첫 프로젝트 흐름을 실행합니다.
- 설치 및 설정에서 Native Install과 업데이트 경로를 확인합니다.
- 헤드리스 모드에서
claude -p, Agent SDK, CI 실행 방식을 정리합니다. - 트러블슈팅에서 인증과 네트워크 문제를 분리합니다.
인증 설정에 문제가 있나요?
- Claude Code 인증 공식 문서를 먼저 확인하세요.
- 인증 트러블슈팅을 확인하세요.
- GitHub Issues로 재현 가능한 문제를 신고하세요.