Claude Code/API 비용 관리 가이드: 토큰 예산, 알림, 상한 설정

Claude Code를 매일 쓰기 시작하면 가장 먼저 필요한 것은 “이번 작업이 대략 얼마인지”를 설명하는 능력입니다. 비용은 모델 하나로 결정되지 않습니다. 읽힌 파일, 대화 이력, 출력 길이, 선택한 모델, 프롬프트 캐시 적중률, 그리고 Claude 구독 사용인지 Anthropic API 종량제인지에 따라 달라집니다.

이 글은 2026-06-03에 공식 문서인 Anthropic API pricing, Claude Code cost management, Prompt caching, Token counting, Usage and Cost API를 확인해 작성했습니다. 가격은 바뀔 수 있으므로 구매나 고객 견적 전에는 공식 페이지를 다시 확인하세요.

비용을 쉬운 말로 이해하기

용어	의미	비용 영향
토큰	Claude가 읽고 쓰는 단위	파일, 로그, 프롬프트, 생성 코드가 길수록 증가
컨텍스트	대화 이력, 읽은 파일, CLAUDE.md, 도구 정의	오래된 내용이 남으면 다음 요청에서도 다시 비용이 듦
프롬프트 캐시	같은 프롬프트 앞부분을 재사용하는 기능	적중하면 반복 입력 비용이 크게 감소
예산 가드	작업, 일, 사용자, 워크스페이스별 상한	예상 밖의 지출을 멈추는 장치

예상 비용 = 입력 토큰 * 입력 단가
        + 캐시 쓰기 토큰 * 캐시 쓰기 단가
        + 캐시 읽기 토큰 * 캐시 읽기 단가
        + 출력 토큰 * 출력 단가

2026-06-03 기준 공식 표에서 Sonnet 4.6은 입력 $3/MTok, 출력 $15/MTok입니다. Haiku 4.5는 입력 $1/MTok, 출력 $5/MTok이고, Opus 4.8/4.7/4.6은 입력 $5/MTok, 출력 $25/MTok입니다. 프롬프트 캐시 읽기는 기본 입력 단가의 10%, 5분 캐시 쓰기는 기본 입력 단가의 1.25배입니다.

초보자가 자주 놓치는 부분은 출력 비용입니다. “자세히 전부 설명해 줘” 대신 “심각도순 5개만, 각 2줄”처럼 출구를 정하면 비용과 리뷰 시간이 함께 줄어듭니다.

비용 제어 흐름

flowchart LR
  A["작업 정의"] --> B["입력 줄이기"]
  B --> C["모델 선택"]
  C --> D["토큰 예측"]
  D --> E{"예산 이내?"}
  E -- "예" --> F["Claude 실행"]
  E -- "아니오" --> B
  F --> G["usage 기록"]
  G --> H{"임계값 초과?"}
  H -- "예" --> I["중지, 알림, 모델 변경"]
  H -- "아니오" --> A

Claude Code에서는 먼저 /usage와 /context를 확인합니다. 관련 없는 작업으로 넘어갈 때는 /clear, 결정 사항만 남기고 싶을 때는 /compact를 사용합니다. /usage의 금액은 로컬 추정치이며, 최종 청구 확인은 Console과 조직용 Usage and Cost API에서 해야 합니다.

예제 1: 월 비용 빠르게 예측하기

API를 호출하지 않고 하루 MTok 사용량으로 월 비용을 계산하는 스크립트입니다.

// claude-cost-estimator.mjs
const RATES = {
  opus48: { input: 5, output: 25, cacheRead: 0.5 },
  sonnet46: { input: 3, output: 15, cacheRead: 0.3 },
  haiku45: { input: 1, output: 5, cacheRead: 0.1 },
};

const [model = "sonnet46", days = "22", input = "0.25", output = "0.06", cacheRead = "0.20"] =
  process.argv.slice(2);

if (!RATES[model]) {
  throw new Error(`Unknown model: ${model}`);
}

const rate = RATES[model];
const dailyUsd =
  Number(input) * rate.input +
  Number(output) * rate.output +
  Number(cacheRead) * rate.cacheRead;

console.log({
  model,
  workDays: Number(days),
  dailyUsd: Number(dailyUsd.toFixed(4)),
  monthlyUsd: Number((dailyUsd * Number(days)).toFixed(2)),
});

node claude-cost-estimator.mjs sonnet46 22 0.25 0.06 0.20
node claude-cost-estimator.mjs haiku45 22 0.25 0.06 0.20

이 계산은 완벽한 청구서가 아니라 의사결정용 눈금입니다. 도구 정의, 재시도, 긴 출력, 캐시 쓰기 비용을 감안해 20~30% 여유를 더해 잡는 편이 안전합니다.

예제 2: API 호출에 실패 안전장치 넣기

다음 예제는 Token Count API로 입력을 먼저 재고, 실행 후 실제 usage를 JSONL에 저장합니다. 그날 예산을 넘을 것으로 예상되면 요청을 보내지 않습니다.

npm init -y
npm i @anthropic-ai/sdk

// budgeted-message.mjs
import Anthropic from "@anthropic-ai/sdk";
import fs from "node:fs";

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const model = process.env.CLAUDE_MODEL ?? "claude-sonnet-4-6";
const maxTokens = Number(process.env.MAX_TOKENS ?? 700);
const dailyBudgetUsd = Number(process.env.DAILY_BUDGET_USD ?? 5);

const RATES = {
  "claude-opus-4-8": { input: 5, output: 25, cacheWrite5m: 6.25, cacheRead: 0.5 },
  "claude-sonnet-4-6": { input: 3, output: 15, cacheWrite5m: 3.75, cacheRead: 0.3 },
  "claude-haiku-4-5": { input: 1, output: 5, cacheWrite5m: 1.25, cacheRead: 0.1 },
};

function usdFromUsage(usage, rate) {
  return (
    (usage.input_tokens ?? 0) * rate.input +
    (usage.output_tokens ?? 0) * rate.output +
    (usage.cache_creation_input_tokens ?? 0) * rate.cacheWrite5m +
    (usage.cache_read_input_tokens ?? 0) * rate.cacheRead
  ) / 1_000_000;
}

function todayTotalUsd(path) {
  if (!fs.existsSync(path)) return 0;
  const today = new Date().toISOString().slice(0, 10);
  return fs.readFileSync(path, "utf8")
    .trim()
    .split("\n")
    .filter(Boolean)
    .map((line) => JSON.parse(line))
    .filter((row) => row.date === today)
    .reduce((sum, row) => sum + row.usd, 0);
}

const messages = [
  { role: "user", content: "List only the top three bug risks in this TypeScript function." },
];

const rate = RATES[model];
if (!rate) throw new Error(`No rate table for ${model}`);

const counted = await anthropic.messages.countTokens({ model, messages });
const worstCaseUsd = (counted.input_tokens * rate.input + maxTokens * rate.output) / 1_000_000;
const logPath = "claude-usage.jsonl";

if (todayTotalUsd(logPath) + worstCaseUsd > dailyBudgetUsd) {
  throw new Error(`Budget stop: projected daily spend exceeds $${dailyBudgetUsd}`);
}

const response = await anthropic.messages.create({
  model,
  max_tokens: maxTokens,
  cache_control: { type: "ephemeral" },
  system: "You are a concise senior code reviewer. Return only actionable findings.",
  messages,
});

const usd = usdFromUsage(response.usage, rate);
fs.appendFileSync(logPath, JSON.stringify({
  date: new Date().toISOString().slice(0, 10),
  model,
  usd: Number(usd.toFixed(6)),
  usage: response.usage,
}) + "\n");

console.log({ id: response.id, usd: Number(usd.toFixed(6)), usage: response.usage });

ANTHROPIC_API_KEY=sk-ant-...
DAILY_BUDGET_USD=5 node budgeted-message.mjs

팀원에게는 “보내기 전에 무게를 재고, 실행 후 영수증을 저장하고, 하루 한도에 가까우면 멈춘다”고 설명하면 됩니다.

예제 3: 팀 사용량 확인하기

조직 계정은 Admin Usage and Cost API로 일별 사용량을 조회할 수 있습니다. 개인 계정용 기능이 아니며 Admin API 키가 필요합니다.

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2026-06-01T00:00:00Z&\
ending_at=2026-06-08T00:00:00Z&\
group_by[]=model&\
bucket_width=1d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_ADMIN_KEY"

신호	위험	대응
Opus 비율	가벼운 작업도 고가 모델 사용	요약, 번역, 포맷팅은 Sonnet/Haiku로 라우팅
출력 토큰	기본 응답이 너무 김	항목 수, 줄 수, max_tokens 제한
캐시 읽기	cache_read_input_tokens가 낮음	캐시될 앞부분에서 시간값과 랜덤값 제거

실제 사용 사례 3가지

개인 개발자: Sonnet을 기본으로 쓰고, 설계 판단이나 어려운 디버깅에만 Opus를 씁니다. 작업이 바뀌면 /clear로 오래된 컨텍스트를 버립니다.

콘텐츠와 현지화: 스타일 가이드와 용어집을 안정적인 프롬프트 앞부분으로 두고 본문만 바꿉니다. 대량 비동기 작업이면 Batch API의 50% 할인을 검토합니다.

교육과 팀 도입: 교육일에는 동시 사용량이 평소보다 높습니다. 일 예산과 알림 기준을 먼저 정하고, 실패 로그는 마지막 몇십 줄만 넘기도록 훈련합니다. 팀 교육 자료가 필요하면 /training/을 참고하세요.

자주 나오는 실수

API 키가 과금 방식을 바꾼다. 공식 도움말은 ANTHROPIC_API_KEY가 있으면 Claude Code가 구독 사용량이 아니라 API 종량제 계정으로 동작할 수 있다고 설명합니다. /status로 인증 방식을 확인하세요.

캐시를 측정하지 않는다. 프롬프트 캐시는 같은 앞부분이 유지될 때만 효과가 있습니다. system prompt에 현재 시간이나 UUID를 넣으면 캐시가 깨질 수 있습니다.

출력을 제한하지 않는다. 리뷰는 최대 발견 수, 요약은 글자 수, 코드 생성은 파일 범위를 정합니다. 그래야 비용과 검토 시간이 함께 줄어듭니다.

오래된 가격을 복사한다. 모델명과 가격은 바뀝니다. 계산기나 고객 견적을 공개하기 전에는 공식 가격표를 다시 확인하세요.

비공식 저가 프록시를 쓴다. 모델 정체성, 로그 보관, 인증 정보 처리를 설명할 수 없는 서비스는 실제 절감이 아니라 위험 이전일 수 있습니다.

관련 글

• Claude Code token optimization
• Claude Code pricing guide
• Claude Code context management
• Claude Code permission budget loop

반복 사용할 예산표, 프롬프트 템플릿, 리뷰 체크리스트는 /products/에 정리해 두었습니다.

직접 적용해 본 결과

ClaudeCodeLab 콘텐츠 작업에 적용해 보니 가장 큰 효과는 기본 운영에서 나왔습니다. 공통 지침은 캐시하고, 번역과 포맷팅은 Haiku/Sonnet으로 보내고, Opus는 판단이 필요한 작업에만 쓰며, 모든 API usage를 JSONL로 남겼습니다. 먼저 넣을 장치는 80% 알림, 100% 중지, 작업 전환 시 컨텍스트 정리입니다.