Claude Code 헤드리스 모드와 Agent SDK 과금 분리 대응

자동화 호출이 구독 사용량에서 빠진다

Anthropic은 2026년 6월 15일부터 Claude Code의 claude -p 헤드리스 모드와 Claude Agent SDK를 통한 API 호출을 Pro·Max·Team·Enterprise 구독 한도에서 분리한다. 자동화 파이프라인과 대화형 세션이 하나의 사용량 풀을 공유하던 구조가 끝나고, 헤드리스·에이전트 사용량에는 별도 달러 크레딧 종량제가 적용된다.

Claude Code 출시 이후 Pro·Max 플랜 사용자는 구독 한도 안에서 헤드리스 모드를 활용해 왔다. 에이전트 자동화가 확산되면서 소수의 CI/CD 헤비유저가 구독 사용량 대부분을 소진하는 불균형이 커졌고, Anthropic은 사용 패턴이 다른 대화형 세션과 자동화 워크플로를 별도로 관리하는 방향을 택했다.

달러 크레딧은 월별로 소진되며 롤오버되지 않는다. 크레딧을 이월할 경우 사용량 예측과 인프라 부하 평준화가 복잡해지므로, AWS나 GCP와 협상할 때 사용하는 커밋 기반 선불 모델 대신 단순한 월별 소진 구조를 적용한 것이다.

호출 방식에 따라 달라지는 미터

변경 이후에는 사람의 실시간 개입 여부가 과금 경로를 가른다. 사용자가 대화에 참여하는 세션은 구독 한도에서 차감되고, 스크립트나 파이프라인이 실행하는 호출은 달러 크레딧에서 차감된다.

구분	적용 범위	과금 방식	롤오버
대화형 세션	claude CLI 대화, IDE 통합, 웹 인터페이스	구독 한도 내 포함	없음
헤드리스 모드	`claude -p` 플래그, 비인터랙티브 스크립트	달러 크레딧 종량제	없음
Agent SDK	`anthropic` Python/JS SDK 직접 호출	달러 크레딧 종량제	없음
Batch API	대량 비동기 처리	달러 크레딧 종량제 (50% 할인)	없음
Max 플랜 보너스	Max 구독자 월별 크레딧 포함량	크레딧 차감 후 초과분 과금	없음

⤢✕

Claude Code는 실행 환경에 터미널(TTY)이 연결됐는지 감지해 사용할 미터를 선택한다. TTY가 없는 CI 환경은 헤드리스로 분류된다. 로컬에서 -p 플래그 없이 실행하고 TTY가 연결돼 있다면 대화형 사용으로 처리된다.

과금 경로가 나뉘어도 호출 엔드포인트까지 따로 관리할 필요는 없다. 백엔드가 과금 대상을 구분하고, 요청이 끝나면 토큰 사용량을 해당 미터에 반영한다. 대화형 세션 사용량과 헤드리스 크레딧은 서로 영향을 주지 않는다.

CI/CD 비용 기준선을 다시 잡는 법

먼저 GitHub Actions, Jenkins, GitLab CI에서 claude -p 또는 Agent SDK를 호출하는 지점을 모두 찾는다. 이어 Anthropic 대시보드나 로그에서 호출별 평균 입력·출력 토큰을 추출해야 한다. 이 값이 기존 자동화 비용을 월별 달러 비용으로 바꾸는 기준선이다.

월별 예상 비용 = Σ (호출 수 × 평균 입력 토큰 × 입력 단가 + 평균 출력 토큰 × 출력 단가)

Claude Sonnet 4의 입력 $3/MTok, 출력 $15/MTok를 적용하면 PR당 평균 4,000 입력·1,000 출력 토큰을 쓰는 코드 리뷰 봇은 월 500 PR 기준 약 $7.5/월의 추가 비용이 발생한다.

비용 모델을 만든 뒤에는 사용량에 따라 자동화 범위를 조절할 장치가 필요하다. 크레딧의 70%를 소진하면 Slack이나 Email로 알리고, 90%에 도달하면 문서 생성이나 린팅 봇 같은 비핵심 태스크를 일시 정지한다. 예산을 넘지 않도록 최대 크레딧 상한도 함께 설정한다.

다른 에이전트 과금 모델과 비교할 때 볼 항목

항목	Anthropic (Claude)	OpenAI (GPT)
구독-API 통합	Pro/Max 구독 + 별도 크레딧 분리	ChatGPT Plus와 API 완전 분리
에이전트 전용 티어	없음 (크레딧 종량제)	Codex API 별도 티어
롤오버	없음	없음
배치 처리 할인	50%	50%
캐싱 할인	프롬프트 캐싱 90% (5분 내 재사용)	프롬프트 캐싱 50%
사용량 모니터링	API 대시보드 + 웹훅(예정)	API 대시보드 + 웹훅
엔터프라이즈 커밋	선불 크레딧 구매	선불 크레딧 구매
에이전트 API 안정성	Claude Agent SDK GA	Agents SDK GA

비용 차이를 크게 만드는 지점은 프롬프트 캐싱이다. Anthropic은 5분 이내 같은 프롬프트를 재사용하면 입력 비용을 90% 절감한다. 동일한 시스템 프롬프트를 반복하는 CI/CD 파이프라인에서는 이 조건이 실제 비용 부담에 직접 영향을 준다.

팀 규모에 따라 달라지는 TCO

개발자 5인, 월 100 PR을 처리하는 소규모 팀은 이전에 Max 구독 $100/월 안에서 모든 사용량을 처리했다. 변경 후에는 Max 구독 $100/월에 헤드리스 크레딧 약 $1.5/월이 더해져 1.5% 증가한다.

개발자 20인, 월 500 PR과 일일 배포 파이프라인을 운영하는 중규모 팀은 Team 플랜 구독 안에서 자동화를 사용하면서 일부 속도 제한을 경험했다. 분리 이후에는 Team 구독과 함께 약 $15-30/월의 헤드리스 크레딧이 필요하므로 비용 증가를 관리할 거버넌스가 필요하다.

개발자 200인과 수백 개의 자동화 파이프라인을 보유한 대규모 엔터프라이즈는 협상 가격의 Enterprise 라이선스 정액 구조에서 Enterprise 구독과 대규모 크레딧 커밋 계약을 결합한 구조로 옮겨간다. 이 경우 Anthropic과 별도의 볼륨 할인을 협상해야 한다.

비용이 추가되는 대신 서비스별·파이프라인별 사용량을 추적하기는 쉬워진다. 구독 한도에 섞여 있던 자동화 비용을 크레딧 기반 미터링으로 분리하면 각 파이프라인이 소비하는 비용을 따로 볼 수 있다.

실행 전에 예산을 확인하는 비용 게이트

헤드리스 호출을 운영하는 환경에서는 에이전트 작업을 시작하기 전에 잔여 크레딧을 확인하는 비용 게이트를 둘 수 있다.

# 비용 게이트 패턴 예시 (Python)
import anthropic

client = anthropic.Anthropic()

def get_remaining_credits() -> float:
    # Anthropic Usage API 호출 (2026년 GA 예정)
    usage = client.usage.get_monthly()
    return usage.credits_remaining

def run_agent_task(task: str, budget_threshold: float = 0.1):
    remaining = get_remaining_credits()
    total = get_total_credits()
    
    if remaining / total < budget_threshold:
        raise RuntimeError(f"크레딧 잔액 부족: {remaining:.2f} USD 남음")
    
    # 실제 에이전트 호출
    response = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": task}]
    )
    return response

마이그레이션 범위를 점검할 때는 다음 항목을 빠뜨리지 않아야 한다.

모든 claude -p 호출 위치 인벤토리 작성
Agent SDK 직접 호출 코드베이스 전수 조사
과거 3개월 토큰 사용량 로그 분석
월별 예상 크레딧 소비량 모델 수립
크레딧 알림 웹훅 설정 (70%/90%/100%)
비상 정지(circuit breaker) 로직 구현
부서별 크레딧 예산 배분 정책 수립

자동화 비용을 운영 지표로 다루기

Claude Code의 구독-크레딧 하이브리드 구조는 종량제와 구독제를 결합한 SaaS 과금 모델이다. 이를 기업 환경에 적용하려면 IT 서비스 비용 배분과 차지백, 사용량 기반 계약, FinOps 거버넌스, API 미터링, 에이전트 AI의 TCO를 하나의 운영 체계로 묶어야 한다.

당장은 CI/CD 파이프라인의 비용을 다시 계산하고 크레딧 통제 정책을 세우는 작업이 필요하다. 프롬프트 캐싱 최적화와 Batch API를 함께 활용하면 실질 비용을 30-50% 절감할 수 있다. 장기적으로는 자동화 투자 대비 효과를 파이프라인 단위로 측정하고, 그 결과를 예산 배분에 반영하는 운영 역량이 중요해진다.