Claude Pro나 Max로 Claude Code를 대화형으로 쓰는 일반적인 상황에서는 API 키가 필요하지 않습니다. 하지만 ANTHROPIC_API_KEY 가 설정되어 있으면 Claude Code가 그 키를 우선 사용하고, 사용량이 Claude Console의 API 결제로 잡힐 수 있습니다. 플랜 포함 사용량을 다 쓴 뒤 usage credits를 켜면 이후 사용량도 표준 API 요금으로 별도 과금됩니다. 핵심은 가입한 플랜 이름이 아니라 지금 세션의 실제 경로입니다.
가장 먼저 /status 를 확인하세요. 다음에는 /usage, 환경 변수, Console을 분리해서 봅니다. 사람이 터미널에서 코딩하는 흐름은 구독 로그인, SDK와 CI와 서버 자동화는 API 키, usage credits는 명시적으로 선택한 유료 계속 사용으로 구분하는 것이 안전합니다.
| 상황 | 권장 경로 | 결제 주체 | 첫 확인 |
|---|---|---|---|
| Pro 또는 Max로 로컬에서 대화형 코딩 | 구독 로그인 | Claude 플랜 사용량 | /status |
ANTHROPIC_API_KEY 가 있거나 자동화로 실행 | API 키 경로 | Claude Console API 사용량 | 환경 변수와 Console Usage |
| 플랜 한도 후 usage credits 사용 | usage-credit 계속 사용 | 표준 API 요금으로 별도 과금 | Settings > Usage와 Console Billing |
| 구독이 있는데 API 비용 발생 | 먼저 경로 진단 | API 키가 우선된 가능성 | /status 와 echo "$ANTHROPIC_API_KEY" |
먼저 현재 경로를 확인하기
Claude Code는 Claude 계정으로 로그인해 쓸 수도 있고, API 키를 통해 Console 쪽으로 연결될 수도 있습니다. 두 설정이 같은 컴퓨터에 있어도 결제 주체는 다릅니다. 구독 로그인은 Pro 또는 Max 플랜의 사용 한도와 연결되고, API 키는 Console 프로젝트와 API 사용량 장부로 연결됩니다.
로컬에서 저장소를 읽고, 코드를 고치고, 리팩터링하고, 에러를 설명받는 작업이라면 구독 로그인이 기본값입니다. 이 경우에는 플랜 한도와 세션 사용 패턴을 보면 됩니다.
API 키는 프로그램이 모델을 호출해야 할 때의 도구입니다. CI, headless 실행, 팀 자동화, backend agent, 평가 작업, 프로젝트별 예산 관리가 필요하면 API 키가 맞습니다. 다만 이 순간부터 결제 계약은 API 쪽으로 바뀝니다.
Usage credits는 또 다른 개념입니다. Pro, Max 5x, Max 20x 사용자가 포함 사용량 이후에도 계속 일할 수 있게 하지만, 이후 사용량은 표준 API 요금으로 별도 과금됩니다. Pro 또는 Max 안에 들어 있는 숨은 구독 잔액이 아니며 credit 전환은 명시적인 선택이어야 합니다.
구독이 있는데 API 결제가 생기는 이유
가장 흔한 원인은 ANTHROPIC_API_KEY 가 남아 있는 것입니다. 이 값은 .zshrc, .bashrc, .env, 터미널 profile, devcontainer, CI secret, 실행 스크립트에 들어갈 수 있습니다. 사용자는 구독으로 쓰고 있다고 생각하지만 Claude Code는 API 키를 보고 Console 계정으로 연결할 수 있습니다.
두 번째 원인은 자동화입니다. CI나 컨테이너는 개인 브라우저 로그인에 의존하기 어렵습니다. 이런 경우 API 키가 더 올바른 구조지만, 비용도 API 사용량으로 관리해야 합니다.
진단은 길 필요가 없습니다.
bashclaude /status echo "$ANTHROPIC_API_KEY"
/status 가 구독 로그인을 보여주면 플랜 한도 쪽을 봅니다. API 경로를 보여주면 환경 변수, Console project, Usage를 봅니다. 플랜을 바꾸거나 credits를 더 사기 전에 이 분기를 먼저 정해야 합니다.
/status, /usage, /cost, Console의 역할
/status 는 경로 확인 도구입니다. 지금 Claude Code가 어떤 계정과 결제 경로로 실행되는지 먼저 보여줍니다.
/usage 는 구독 사용자가 플랜 포함 사용량, usage-credit 소비, Claude Code 안의 사용 패턴을 보는 데 유용합니다. 설치 버전이나 팀 습관에서 /stats 라고 부르더라도 Console의 API 청구서가 아니라 사용 패턴 화면으로 읽어야 합니다.
/cost 또는 usage 출력의 달러 금액은 API 방식의 token 비용 추정으로 읽어야 합니다. Pro나 Max 구독 청구액 그 자체로 해석하면 안 됩니다. API 경로에서도 최종 확인은 Console Usage가 더 맞습니다.
Claude Settings > Usage는 포함 사용량과 usage-credit 소비를 구분하는 곳입니다. Console Billing과 Usage는 API route, auto-reload, API project, API 경로에서 발생한 Claude Code 비용을 확인하는 곳입니다. 팀에서 비용을 따질 때는 로컬 화면보다 Console 기록을 기준으로 삼아야 합니다.
팀 runbook에는 /status 의 경로와 Settings 또는 Console 장부를 함께 남기세요. 두 정보가 있어야 현재 실행 경로와 실제 결제 owner를 따로 증명할 수 있습니다.
API 키가 맞는 경우
API 키는 더 고급스럽게 보이려고 켜는 옵션이 아닙니다. 작업 자체가 API 운영에 가까울 때 쓰는 계약입니다.
다음 상황에서는 API 키가 자연스럽습니다.
- SDK나 backend가 Claude API를 직접 호출한다
- CI나 scheduled job이 사람의 로그인 없이 실행된다
- 팀이 Console project 단위로 비용을 보고 싶다
- agent나 batch 작업을 감사 가능한 장부로 남기고 싶다
- budget control과 Usage 기록이 필요하다
- 선택한 모델의 API 가격을 지불할 계획이 있다
반대로 로컬 대화형 코딩 중 한도 메시지가 문제라면 먼저 Claude Code Pro vs Max를 보세요. 플랜 용량 문제와 API 결제 경로 문제는 분리해야 합니다.
Usage credits와 가격 경계
Usage credits는 유료 Claude 플랜의 포함 사용량을 다 쓴 뒤 Claude와 Claude Code를 계속 쓰기 위한 유료 계속 사용입니다. 표준 API 요금으로 별도 과금됩니다. Console credits와 auto-reload는 API 경로 관리이며 Pro 또는 Max 월 구독료와 같은 잔액이 아닙니다.
2026년 5월 25일 기준 Anthropic 공개 가격 페이지는 모델별 input token과 output token 가격을 보여줍니다. 예를 들어 Claude Sonnet 4.6은 input 100만 token당 3달러, output 100만 token당 15달러로 표시되어 있고, Claude Opus 4.7은 각각 5달러와 25달러로 표시되어 있습니다. 이는 확인일이 있는 예시이며, 실제 예산은 최신 공식 가격 페이지와 Console에서 확인해야 합니다.
판단은 "API가 항상 싸다"가 아닙니다. 사람이 오래 대화형으로 코딩하면 구독 경로가 더 예측 가능할 수 있고, CI나 backend나 batch 작업은 API 경로가 더 관리하기 쉽습니다. 무료 API 여부가 궁금하면 Claude API key free tier guide처럼 별도 주제로 확인하는 편이 좋습니다.
구독 로그인으로 되돌리는 방법
구독으로 쓰려 했는데 API 비용이 보인다면 먼저 현재 shell에서 API 키 override를 제거합니다.
bashunset ANTHROPIC_API_KEY claude logout claude login claude /status
이 과정은 Claude Console의 API 키를 삭제하지 않습니다. 현재 shell에서 키가 전달되지 않도록 하고, Claude Code를 다시 로그인한 뒤, 다음 세션이 구독 경로로 돌아왔는지 확인하는 절차입니다.
새 터미널을 열 때마다 키가 다시 생긴다면 지속 설정이 남아 있는 것입니다. shell 설정, 프로젝트 .env, devcontainer, CI secret, IDE 실행 스크립트를 점검하세요. 팀에서는 로컬 대화형 작업은 구독, 자동화는 API 키, API 비용 확인은 Console이라는 규칙을 문서화하는 것이 좋습니다.
혼동하지 말아야 할 것
Claude Code에 로그인할 수 있다고 해서 일반 API 호출이 구독에 포함되는 것은 아닙니다. Pro나 Max는 Claude 계정으로 Claude Code를 쓰는 경로를 제공하지만, Claude API는 Console의 별도 계약입니다.
/cost 나 로컬 달러 추정을 구독 청구액으로 읽지 마세요. API식 비용 추정으로는 유용하지만, 구독 사용량, usage credits, API 청구는 확인 위치가 다릅니다.
실제 API 키를 티켓, 채팅, 스크린샷, 문제 해결 프롬프트에 붙여 넣지 마세요. 보여줄 것은 키 값이 아니라 변수가 존재하는지와 /status 가 어떤 경로를 말하는지입니다.
팀에서 정해 두면 좋은 운영 규칙
개인 노트북이라면 매번 /status 로 확인하고 판단해도 충분합니다. 하지만 팀에서 Claude Code를 쓰면 규칙을 짧게 문서화하는 편이 낫습니다. 로컬 대화형 코딩은 구독 로그인, CI와 scheduled job과 server-side agent는 API 키, 플랜 포함 사용량 이후의 계속 사용은 usage credits, API project 결제와 auto-reload는 Console에서 관리한다고 적어 두면 됩니다. 그러면 비용이 보였을 때 먼저 "어느 경로인가"를 묻게 되고, 바로 Max 업그레이드나 credit 구매로 뛰지 않게 됩니다.
특히 credits라는 단어는 혼동을 만듭니다. Paid-plan usage credits는 Pro나 Max의 포함 사용량을 다 쓴 뒤에도 계속 일하기 위해 명시적으로 켜는 유료 계속 사용입니다. 반면 Console API credits는 API, Workbench, API 경로의 Claude Code 사용에 연결된 계정 잔액입니다. 둘 다 비용을 만들 수 있지만 같은 예산 항목이 아닙니다. 팀 문서에는 usage credits는 개인 플랜의 추가 사용, API credits는 Console project의 API 예산, API 키는 자동화와 프로그램 호출의 credential이라고 분리해 쓰는 것이 좋습니다.
증거를 남기는 방식도 중요합니다. 공유해도 되는 정보는 /status 가 보여주는 계정과 경로, 같은 shell에서 ANTHROPIC_API_KEY 가 비어 있는지 여부, Settings > Usage의 포함 사용량과 credit 소비 구분, Console Usage의 project와 기간입니다. 공유하면 안 되는 정보는 실제 API 키, 전체 .env, 무관한 프로젝트가 보이는 Console 캡처, 청구 세부 화면 전체입니다. 결제 문제를 풀 때 필요한 것은 secret 값이 아니라, 어떤 계약이 현재 실행을 소유했는지입니다.
마지막으로, "더 써야 한다"는 요구를 세 가지로 나누세요. Max 업그레이드는 사람이 대화형으로 오래 작업할 때 중단 비용을 줄이는 선택입니다. API 키는 CI, backend, batch, agent처럼 프로그램이 실행 주체일 때 쓰는 선택입니다. Usage credits는 포함 사용량 이후에도 계속할지에 대한 선택입니다. 이 세 가지를 하나로 합치면 비용 owner도, 해결책도 쉽게 틀어집니다.
긴 작업을 시작하기 전에는 작은 preflight를 두는 것도 좋습니다. 큰 리팩터링, 여러 파일 review, release note 생성, 장시간 agent 실행 전에 /status, ANTHROPIC_API_KEY 존재 여부, 이번 비용 owner가 개인 플랜인지 Console project인지 적어 둡니다. 작업 메모에 이 세 가지가 있으면 나중에 /cost 나 Console 숫자를 봐도 어떤 계약으로 실행했는지 설명할 수 있습니다.
개인 사용자도 같은 기준을 쓰면 됩니다. Usage credits 안내가 보인다면 무료 추가 한도가 아니라 지금 계속하기 위한 유료 선택으로 읽으세요. 기다릴 수 있는 작업이면 reset을 기다리고, CI나 backend라면 API 예산으로 처리하고, 로컬 대화형 작업이라면 Pro/Max 플랜 차이를 검토하세요. 핵심은 결제 전에 경로를 확정하는 것입니다.
이 규칙은 절차를 늘리기 위한 것이 아닙니다. 경로만 먼저 확정하면 다음 행동이 갈립니다. 구독이면 플랜 창과 /usage, API 키면 Console project와 예산, usage credits면 표준 API 요금 수용 여부를 보면 됩니다. 이 순서가 없으면 서로 다른 세 문제를 모두 "Claude Code 비용"으로 뭉뚱그리게 됩니다.
확인한 공식 경로
위의 경로와 결제 구분은 2026년 5월 25일 Claude Help, Claude Code docs, Anthropic billing, Anthropic pricing을 확인한 내용에 기반합니다.
본인 계정에서도 같은 순서로 확인하세요. /status, ANTHROPIC_API_KEY, Settings > Usage 또는 Console Usage. 이 순서면 결제 결정을 하기 전에 현재 실행의 소유자를 먼저 알 수 있습니다.
자주 묻는 질문
Claude Code에 API 키가 꼭 필요한가요?
일반적인 대화형 사용에는 필요하지 않습니다. Pro나 Max의 Claude 계정으로 로그인해 쓸 수 있습니다. API 키는 SDK, CI, backend, 자동화, Console project 관리가 필요할 때 씁니다.
Pro나 Max가 있는데 API 결제가 생기는 이유는 무엇인가요?
Claude Code가 API 경로로 실행 중일 수 있습니다. /status 를 보고, 같은 실행 환경에서 ANTHROPIC_API_KEY 가 설정되어 있는지 확인하세요.
Usage credits는 구독 잔액인가요?
아닙니다. Usage credits는 포함 사용량 이후에도 계속 쓰기 위한 유료 계속 사용이며 표준 API 요금으로 별도 과금됩니다. Pro 또는 Max 구독 사용량과 별도입니다.
Max로 올리는 대신 API를 써야 하나요?
작업이 CI, SDK, backend, agent처럼 API형이면 검토할 수 있습니다. 로컬 대화형 코딩의 한도 문제가 핵심이면 먼저 Claude Code usage limit issues와 Pro/Max 차이를 확인하세요.
/cost는 구독 청구액을 보여주나요?
아닙니다. API식 token 비용 추정으로 보세요. 구독은 /status 와 /usage, API 청구는 Console Usage에서 확인합니다.
Claude Code가 API 키를 쓰지 않게 하려면 어떻게 하나요?
같은 shell에서 unset ANTHROPIC_API_KEY 를 실행하고, claude logout, claude login, /status 순서로 확인하세요. 키가 다시 돌아오면 shell 설정, .env, CI secret, container 설정을 정리해야 합니다.