Claude Code 로그인: 구독과 API 키 차이점

Claude Code 세션은 어떤 자격 증명을 사용합니까?

Claude Code 로그인은 두 가지 방식 중 하나로 작동합니다. claude.ai의 Claude 구독 계정으로 로그인하거나, Anthropic Console 조직을 통해 인증하는 방식입니다. 후자의 경우 모든 토큰이 해당 조직의 API(애플리케이션 프로그래밍 인터페이스) 잔액에서 차감됩니다. 실행 중인 세션에서 /status를 실행하면 현재 활성화된 자격 증명을 확인할 수 있습니다. 상태(Status) 탭에는 로그인한 계정에 대한 Login method 행이 표시되며, API 키가 자격 증명을 제공하는 경우에는 추가로 API key 행이 나타납니다.

해당 도구가 사용자의 플랜에 포함되는지 여부는 별개의 문제이며, Claude Code가 Claude Pro 구독에 포함되는지 여부에서 확인할 수 있습니다. Claude API 키의 작동 원리는 Claude API 인증 작동 방식에서 다룹니다. 이어지는 내용은 위 두 문서에서 다루지 않는 부분으로, 세션이 실제로 어떤 자격 증명을 선택했는지와 이를 변경하는 방법에 관한 것입니다.

아래의 동작 방식은 2026년 8월 31일에 확인한 Anthropic의 Claude Code 인증 문서를 기준으로 합니다. Claude Code는 자주 릴리스되며, 이러한 동작 중 일부는 최소 버전을 요구하므로 기기에 문제가 있다고 판단하기 전에 claude --version을 실행하십시오.

하나의 이메일 주소를 공유할 수 있는 두 계정

claude.ai 계정과 platform.claude.com의 Claude Console 계정은 서로 다른 계정입니다. 동일한 이메일 주소를 사용할 수 있지만, 각각 별도의 조직에 속하며 별도의 잔액을 가진 독립적인 로그인 계정으로 유지됩니다. 한쪽을 생성한다고 해서 다른 쪽이 자동으로 생성되지는 않습니다. Max 플랜을 결제해도 Console 조직에 크레딧이 충전되지 않으며, Console 조직에 잔액을 충전해도 플랜에 아무런 영향을 주지 않습니다.

두 계정의 잔액이 다른 이유는 과금 모델이 다르기 때문입니다. 구독형 로그인은 플랜의 사용량 한도를 차감하며, 이 한도는 5시간 단위의 롤링 윈도우와 주간 단위로 초기화되고 웹상의 Claude와 공유됩니다. 반면 Console 자격 증명은 조직 단위로 토큰당 비용이 청구되며, 정확한 수치는 Console 사용량 페이지에서 확인할 수 있습니다. 실제 업무 환경에서 이러한 차이가 발생하는 비용에 대해서는 구독 결제와 토큰당 결제 비교에서 다룹니다.

특정 계정 유형은 구독 방식을 전혀 사용할 수 없습니다. Anthropic은 Pro 또는 Max 구독, Claude for Teams 또는 Enterprise 좌석, Claude Console 계정, 클라우드 제공업체 계정을 로그인 가능한 계정으로 명시합니다. 무료 claude.ai 계정은 이 목록에 포함되지 않으므로, 무료 플랜 사용자는 로그인에 사용할 수 있는 구독 자격 증명이 없으며 무료 Claude 티어의 포함 범위와 제한 사항은 명령줄 도구까지 확장되지 않습니다. 남은 유일한 경로는 API 크레딧을 사용하는 Console 조직이며, 이는 형태가 다른 유료 계정입니다.

경로 1: Claude 구독으로 로그인

프로젝트 디렉터리에서 claude을 실행합니다. 처음 실행하면 플랜이 포함된 claude.ai 계정으로 로그인할 수 있도록 브라우저 창이 열립니다.

claude

서버 환경에서는 두 가지가 다르게 동작합니다. 브라우저가 열리지 않으면 c를 눌러 로그인 URL을 클립보드로 복사한 뒤, 로컬 머신의 브라우저에 붙여넣으십시오. 만약 브라우저가 터미널로 돌아오는 대신 로그인 코드를 표시한다면, 해당 코드를 복사하여 터미널의 입력 프롬프트에 붙여넣으십시오. SSH(secure shell), WSL2, 컨테이너 내부에서는 브라우저가 원격 머신에서 Claude Code가 시작한 로컬 콜백 서버에 접근할 수 없으므로 이 과정은 정상입니다.

로그인이 완료되면 성공 여부를 확인하십시오. 세션을 시작하고 /status을 실행합니다. Status 탭에는 저장된 로그인 방식과 조직, 이메일 주소가 표시됩니다. /login은 다른 계정으로 로그인 과정을 다시 수행하며, /logout는 저장된 자격 증명을 삭제합니다. 로그아웃하면 최초 실행 설정 상태도 초기화되므로, 다음 claude 실행 시 온보딩 과정을 다시 진행하게 됩니다.

서버를 재구축하거나 인계할 때 자격 증명이 저장되는 위치를 아는 것은 중요합니다.

• Linux: ~/.claude/.credentials.json, 파일 모드 0600.
• macOS: 암호화된 Keychain. SSH 세션에서 잠겨 있는 경우처럼 Keychain이 쓰기를 거부하면, Claude Code는 동일한 0600 파일로 대체합니다.
• Windows: %USERPROFILE%\.claude\.credentials.json, 프로필 디렉터리의 자체 접근 제어에 의해 사용자별로 제한됩니다.
• CLAUDE_CONFIG_DIR이 설정된 모든 플랫폼: 파일이 해당 디렉터리 아래로 이동하며, macOS Keychain 항목도 이에 맞춰 키가 지정되므로 다른 CLAUDE_CONFIG_DIR로 시작한 세션은 다른 자격 증명을 읽습니다.

Claude Code는 /login 및 /logout을 통해 해당 파일을 관리합니다. 수동으로 파일을 편집하여 계정을 전환하는 방식은 지원하지 않습니다.

경로 2: Console 조직을 통한 인증

Console 접근은 관리자로부터 시작됩니다. 관리자가 Console의 Settings, Members, Invite 메뉴를 통해 귀하를 초대합니다. 이때 역할을 할당하는데, Claude Code 역할은 Claude Code API 키만 생성할 수 있고, Developer 역할은 모든 키를 생성할 수 있습니다. 이후 /login 프롬프트에서 Anthropic Console 계정을 선택합니다.

Claude Code v2.1.242 버전부터는 두 가지 Console 경로가 존재하며, 각각 저장하는 정보가 다릅니다. Console 계정으로 로그인하면 해당 브라우저 로그인에서 얻은 OAuth(open authorisation) 토큰을 Anthropic 프로필로 저장하며, API 키는 생성하지 않습니다. Claude Code는 이 로그인을 자체적으로 갱신하며, 갱신에 실패하면 다시 로그인할 때까지 요청이 실패합니다. 프롬프트에서 레거시(legacy)로 표시되는 API 키를 생성하면 Console 키가 발급되어 다른 자격 증명과 함께 저장됩니다. 정적 키는 갱신되지 않으므로 누군가 취소하기 전까지 계속 작동합니다. 이는 빌드 서버에는 유용하지만, 노트북에서는 보안상 위험 요소가 될 수 있습니다.

키 없는(keyless) Console 로그인을 시작하기 전에 ANTHROPIC_API_KEY을 설정 해제하십시오. 해당 변수가 설정되어 있으면 Claude Code는 로그인 프롬프트를 완전히 건너뛰고 발견된 키를 승인하라는 메시지만 표시합니다.

항상 선택권이 주어지는 것은 아닙니다. 세션이 클라우드 공급자 환경에서 실행되거나, 설정 파일에서 forceLoginOrgUUID를 설정했거나, forceLoginMethod를 "claudeai" 또는 "console"로 고정한 경우, 혹은 시스템에 관리형 설정 소스가 존재하지만 Claude Code가 이를 읽을 수 없는 경우 Claude Code는 묻지 않고 키를 생성합니다. 이는 관리자의 결정 사항이므로, 키 없는 옵션이 나타나지 않는다면 관리자에게 문의하십시오. /status을 사용하면 세션이 로드한 모든 설정 파일을 나열하는 Setting sources 줄이 출력되며, 관리형 설정 소스가 적용된 경우 해당 소스 이름도 표시됩니다.

Claude Code를 Console 조직에 처음 인증하면, Console은 이를 위한 "Claude Code"라는 작업 공간을 생성합니다. 이 작업 공간은 Claude Code의 사용량을 한곳에서 추적하기 위해 존재하며, 해당 공간 내에서는 API 키를 생성할 수 없습니다.

로그인 후에도 ANTHROPIC_API_KEY가 우선순위를 갖는 이유

Claude Code는 어떤 자격 증명을 사용할지 사용자에게 묻지 않습니다. 고정된 순서에 따라 소스를 확인하며, 가장 먼저 발견된 것을 사용합니다. 2026년 8월 문서화된 확인 순서는 다음과 같습니다.

1. CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX 또는 CLAUDE_CODE_USE_FOUNDRY가 설정된 경우의 클라우드 공급자 자격 증명.
2. Bearer 토큰으로 인증하는 게이트웨이를 위한 Authorization: Bearer 헤더로 전송되는 ANTHROPIC_AUTH_TOKEN.
3. X-Api-Key 헤더로 전송되는 ANTHROPIC_API_KEY.
4. 설정 파일에 명시된 apiKeyHelper 스크립트의 출력값.
5. claude setup-token에서 생성된 장기 토큰인 CLAUDE_CODE_OAUTH_TOKEN.
6. Anthropic 프로필 및 연합 자격 증명.
7. /login에 의해 기록된 구독 자격 증명.

구독 로그인은 가장 마지막 순위입니다. 따라서 프로세스 환경 어디에서든 ANTHROPIC_API_KEY이 export되어 있다면, 로그인한 계정보다 우선순위가 높아집니다. 이 경우 사용자는 자신의 플랜을 사용 중이라고 생각하지만, 실제 세션 비용은 Console 조직으로 청구됩니다. 이는 오류가 아닙니다. 문서화된 순서대로 동작하고 있을 뿐이며, 별도의 경고가 없는 이유도 이 때문입니다.

이 사실을 놓치기 쉬운 두 가지 세부 사항이 있습니다. 대화형 세션에서 Claude Code는 발견된 키를 사용할지 한 번만 묻고 그 답변을 기억합니다. 따라서 한 달 전에 내린 선택이 오늘까지도 적용됩니다. -p를 사용하는 비대화형 모드에서는 프롬프트가 전혀 나타나지 않으며, 키가 존재하면 항상 해당 키가 사용됩니다. -p은 cron 작업이나 CI(지속적 통합) 단계가 실행되는 모드이므로, 자동화된 작업에서 잘못된 자격 증명이 가장 오랫동안 발견되지 않습니다.

세션 내에서 빠르게 시각적으로 확인할 방법이 있습니다. ANTHROPIC_API_KEY가 설정되어 있는 동안에는 /config에 "Use custom API key" 토글이 표시됩니다. 이 토글은 변수가 설정되어 있을 때만 존재하므로, 토글이 보이지 않는다면 환경이 깨끗한 상태임을 의미합니다.

서버에서 유실된 키 찾기

내보낸 키는 셸 프로필 외에도 여러 곳에 남아 있을 수 있습니다.

• ~/.bashrc, ~/.bash_profile, ~/.profile 또는 ~/.zshrc: 모든 새로운 로그인 셸이 읽어 들입니다.
• systemd 유닛: Environment= 또는 EnvironmentFile=을 통해 서비스로 실행하는 모든 항목에 적용됩니다.
• tmux 서버: 시작 시점의 환경 변수 복사본을 유지합니다. 오늘 연 창(pane)은 지난주에 프로필에서 삭제한 변수를 상속받을 수 있는데, 이는 서버가 편집 이전부터 계속 실행 중이기 때문입니다.
• 컨테이너 이미지 또는 CI 작업 정의: 셸 내부에서 읽을 수 있는 파일 외부에서 변수가 설정됩니다.
• Claude Code 설정 파일의 env 블록: 일반적인 설정 키이며 표준 설정 우선순위를 따릅니다.

다른 작업을 수행하기 전에 다음을 확인하십시오.

[ -n "$ANTHROPIC_API_KEY" ] && echo "ANTHROPIC_API_KEY is set" || echo "not set"
env | grep -E '^(ANTHROPIC_|CLAUDE_CODE_)' | cut -d= -f1
grep -n 'ANTHROPIC_API_KEY' ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc 2>/dev/null
tmux show-environment 2>/dev/null | grep ANTHROPIC
grep -n 'ANTHROPIC_API_KEY\|apiKeyHelper' ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null

두 번째 명령어는 의도적으로 cut을 거치도록 파이프 처리되어 있습니다. 이는 공유 중이거나 녹화 중인 화면에 비밀 값이 출력되지 않도록 변수 이름만 출력하기 위함입니다. 첫 번째 명령어는 변수 설정 여부를 결정합니다. 만약 변수가 설정되었다고 나오면, 이 셸에서 시작하는 다음 claude는 해당 키를 사용합니다. 다섯 가지 항목 모두에서 아무런 반응이 없다면 환경 자격 증명이 존재하지 않는 것이며, 이 세션에서 시작된 작업은 /login 자격 증명을 사용하게 됩니다.

유닛 파일은 자체 환경을 설정하며 셸 프로필을 읽지 않으므로, Claude Code를 실행하는 모든 서비스에는 systemctl cat your-unit.service | grep -i environment을 추가하십시오.

한 자격 증명에서 다른 자격 증명으로 세션 전환하기

구독 계정으로 돌아가려면 다음을 수행합니다.

unset ANTHROPIC_API_KEY
[ -n "$ANTHROPIC_API_KEY" ] && echo "still set" || echo "clear"
claude

clear이 나타나는지 확인한 다음, 새 세션에서 /status을 실행하고 API key 행이 사라졌는지 확인합니다. 셸에서 환경 변수를 설정 해제해도 이미 실행 중인 Claude Code 프로세스에는 아무런 영향을 주지 않습니다. 프로세스는 시작될 때의 환경을 그대로 유지하기 때문입니다. 세션을 재시작하십시오.

그 후 해당 변수를 설정했던 파일에서 export 문을 삭제하십시오. 그렇지 않으면 다음 로그인 셸에서 다시 설정됩니다. tmux 내부에서는 tmux set-environment -u ANTHROPIC_API_KEY을 실행하면 그 이후에 열리는 창에서는 변수가 제거되지만, 이미 열려 있는 창은 기존 복사본을 그대로 유지합니다.

반대 방향으로 전환하려면 환경에서 ANTHROPIC_API_KEY을 설정하거나, /login를 실행하여 Console 계정을 선택하십시오. 저장된 로그인을 완전히 삭제하려면 /logout을 실행합니다. 키가 필요 없는 Console 로그인을 수행한 후에는 /logout를 사용하여 해당 로그인 과정에서 생성된 자격 증명을 제거하고 취소할 수 있습니다.

만약 /status의 결과가 여전히 예상과 다르다면 claude doctor을 실행하십시오. 이 명령은 Claude Code가 거부한 설정 항목들을 나열합니다. 이를 통해 구문 분석에 실패하여 전혀 적용되지 않은 설정 파일을 찾아낼 수 있습니다.

브라우저가 없는 환경에서의 인증

claude setup-token은 /login과 동일한 브라우저 인증 흐름을 시작하며, 1년 동안 유효한 OAuth 토큰을 터미널에 출력합니다.

claude setup-token

토큰은 어디에도 저장되지 않으므로 화면에 나타나면 즉시 복사하십시오. 토큰이 필요한 장비에서 CLAUDE_CODE_OAUTH_TOKEN 환경 변수로 설정하십시오. 이 토큰은 구독 계정을 인증하는 용도이므로 Pro, Max, Team 또는 Enterprise 플랜이 필요하며, 모델 요청을 수행하는 데만 사용할 수 있습니다. Bare 모드에서는 이 토큰을 읽지 않으므로, --bare을 전달하는 스크립트에는 ANTHROPIC_API_KEY 또는 apiKeyHelper가 대신 필요합니다.

여기서도 우선순위 문제가 발생합니다. CLAUDE_CODE_OAUTH_TOKEN이 셸 프로필에 설정되어 있다면, /login를 실행하여 현재 세션을 새 로그인으로 전환하더라도, 해당 변수를 제거하기 전까지는 모든 새 세션이 이전 변수 값을 다시 읽어 들입니다.

조직에서 Amazon Bedrock, Google Cloud 또는 Microsoft Foundry를 통해 추론을 실행하는 경우, 해당 자격 증명이 우선순위 최상단에 위치하므로 브라우저 로그인이 전혀 발생하지 않습니다. 해당 설정은 별도의 작업이며, Bedrock 또는 Vertex에서 Claude Code 실행하기에서 다룹니다.

VPS(가상 사설 서버)에서의 장기 세션은 이러한 문제가 집중되는 곳입니다. 세션을 시작한 셸이 몇 달 전에 구성된 후 한 번도 재시작되지 않았을 수 있기 때문입니다. tmux 내부에서 Claude Code 실행하기에서 해당 설정의 세션 관련 내용을 다룹니다.

각 자격 증명이 실제로 사용한 비용 확인하기

구독 계정으로 로그인하면 /usage에서 플랜 사용량 막대 그래프와 소비 항목별 내역을 확인할 수 있습니다. 세션 블록에 표시된 금액은 토큰 수를 정가 기준으로 계산한 로컬 추정치이므로, 실제 청구서가 아닌 API 사용자를 위한 참고용 수치로 보아야 합니다. 구독자는 금액이 아닌 막대 그래프를 확인해야 합니다.

Console 자격 증명의 경우, 중요한 수치는 Console에서 확인해야 합니다. 비용은 사용량 페이지에서, 멤버별 수치는 Claude Code 대시보드에서 확인하십시오. 터미널에 출력되는 내용은 청구와 관련하여 공식적인 효력이 없습니다.

작업 중에도 플랜 막대 그래프가 전혀 움직이지 않는다면, 환경 변수에 설정된 자격 증명이 우선 적용되고 있는 것입니다. 이 현상은 잘못된 자격 증명이 사용되고 있다는 가장 확실한 징후이며, Claude Code 세션 비용 추적하기에서 이를 측정하는 방법을 자세히 다룹니다. 막대 그래프가 움직이다가 멈춘다면 플랜 한도에 도달한 것이며, 이에 대해서는 Claude 사용량 제한 및 초기화 주기 작동 방식에서 설명합니다.

실패 유형 및 확인 사항

모든 것이 정상 작동하지만 플랜 사용량이 전혀 변하지 않는 경우. 환경 변수 자격 증명이 적용된 상태입니다. /status 명령을 실행하면 API key 행이 표시되며, 위에서 설명한 셸 확인 절차를 통해 해당 변수를 확인할 수 있습니다.

구독 상태가 정상임에도 요청이 실패하는 경우. 비활성화되었거나 만료된 Console 조직의 키가 로그인 정보보다 우선순위를 점유하고 있습니다. unset ANTHROPIC_API_KEY을 실행하고 새 세션을 시작한 뒤, /status를 다시 확인하십시오.

시작 시 로그인 만료 경고가 발생하는 경우. 최신 버전에서는 /login 자격 증명의 만료일이 3일 이내로 남았을 때 경고를 표시하며, /status 명령을 실행하면 로그인 행이 만료 상태로 표시되고 저장된 조직 정보와 이메일이 나타납니다. 갱신하려면 /login를 실행하십시오. 이 경고는 요청을 차단하지 않으므로, 무인 세션이 작동을 멈출 때까지 간과하기 쉽습니다.

apiKeyHelper이 느리거나 실패하는 경우. Claude Code는 기본적으로 5분마다 헬퍼를 재실행하며, 이는 CLAUDE_CODE_API_KEY_HELPER_TTL_MS를 통해 조정할 수 있습니다. 실행 시간이 10초를 초과하면 프롬프트 바에 알림이 표시됩니다. 오류가 발생했든 시간 초과가 되었든 키를 반환하지 않는 헬퍼는 3회 시도 내에 요청 실패를 유발합니다.

올바른 자격 증명이나 잘못된 조직으로 연결된 경우. 하나의 이메일 주소가 두 개의 조직에 속할 수 있습니다. /status는 인증된 조직의 이름을 명시하므로, 본인이 어떤 조직에 접속했는지 추측하지 말고 해당 줄을 직접 확인하십시오.

FAQ

현재 Claude Code가 어떤 계정을 사용 중인지 어떻게 확인합니까?

세션 내에서 /status을 실행합니다. 상태(Status) 탭에는 로그인한 계정에 대한 Login method 행이 표시되며, API 키가 자격 증명을 제공하는 경우 API key 행이 추가됩니다. Anthropic 프로필이나 페더레이션 자격 증명이 선택된 경우에는 로그인 행 대신 Profile 행이 표시됩니다. 세션 외부에서는 셸에서 ANTHROPIC_API_KEY이 설정되어 있는지 확인하여 로그인보다 우선순위가 높은 환경 자격 증명이 존재하는지 알 수 있습니다.

왜 제 Claude Pro 또는 Max 구독이 무시됩니까?

환경 자격 증명이 구독보다 우선순위가 높기 때문입니다. Claude Code는 고정된 순서에 따라 처음 발견된 자격 증명을 사용하며, /login 구독 자격 증명은 클라우드 제공업체 변수인 ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN보다 낮은 마지막 순위입니다. unset ANTHROPIC_API_KEY을 실행하고 새 세션을 시작한 뒤 /status로 확인하십시오. 그 후 해당 변수를 설정한 셸 프로필, systemd 유닛, tmux 환경 또는 컨테이너 정의에서 export 명령을 제거하십시오. 그렇지 않으면 다음 로그인 셸에서 다시 설정됩니다.

무료 Claude 계정으로 Claude Code를 사용할 수 있습니까?

아니요. Anthropic이 로그인용으로 명시한 계정 유형은 Pro 또는 Max 구독, Claude for Teams 또는 Enterprise 좌석, Claude Console 계정, 그리고 클라우드 제공업체입니다. 무료 claude.ai 계정은 여기에 포함되지 않으므로 저장할 구독 자격 증명이 없습니다. 구독 대신 사용할 수 있는 유료 대안은 토큰당 과금되는 API 크레딧이 포함된 Claude Console 조직이며, 이는 동일한 이메일 주소를 사용하더라도 별도의 계정입니다.

제 claude.ai 계정과 Console 계정은 잔액을 공유합니까?

아니요. 동일한 이메일 주소를 사용하더라도 청구 방식이 다른 별도의 계정입니다. 구독 사용량은 웹상의 Claude와 공유되는 플랜 허용량에서 차감되며, 5시간 단위 및 주간 단위로 초기화됩니다. Console 사용량은 조직에 토큰당 과금되며 Console 사용량 페이지에 표시됩니다. 한쪽에 크레딧을 추가해도 다른 쪽에는 아무런 영향을 주지 않습니다.

헤드리스 서버에서 Claude Code를 어떻게 인증합니까?

두 가지 방법이 있습니다. SSH를 통해 claude을 실행하고 본인의 컴퓨터에서 브라우저 로그인을 완료하십시오. c를 눌러 URL을 복사하고 로그인한 뒤, 브라우저가 리다이렉트 대신 코드를 표시하면 해당 코드를 터미널에 붙여넣으십시오. 또는 브라우저가 있는 컴퓨터에서 claude setup-token을 실행하여 출력되는 1년 유효 토큰을 복사한 후, 서버에서 CLAUDE_CODE_OAUTH_TOKEN로 설정하십시오. 해당 토큰은 Pro, Max, Team 또는 Enterprise 플랜이 필요하며 모델 요청만 수행할 수 있으므로, --bare를 사용하는 스크립트에는 API 키나 apiKeyHelper이 필요합니다.