CoreCode문서

CoreCode를 더 알뜰하게

캐싱과 과금

최종 업데이트:

Claude Code는 매 턴마다 시스템 프롬프트, 도구 정의, 지금까지의 대화 전체를 다시 보냅니다. 이 내용이 프롬프트 캐시에 적중하면 캐시 읽기로 과금되며, 가격은 일반 입력 가격의 2.5~10%이고 Opus 5.5와 Sonnet 5.5에서는 5%입니다. 그래서 캐시 적중률이 지출을 사실상 좌우합니다. 캐싱 외에 요금을 줄이는 방법은 Claude Code 요금 저렴하게 쓰기에 있습니다.

적중률이 낮다면 먼저 auto 모드를 확인하세요Claude Code의 auto 권한 모드를 켜고 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS를 설정하면, 도구를 호출할 때마다 캐시에 거의 적중하지 않는 검사 요청이 추가로 나갑니다. 사용 로그에는 Non-stream으로 표시되며, 전체 지출의 절반을 넘기도 합니다. auto 모드의 비용을 참고하세요.

캐시 과금 방식

Anthropic의 프롬프트 캐시는 접두사(prefix)로 일치 여부를 판단합니다. 요청의 앞부분이 이전에 캐시된 내용과 같아야 캐시를 읽습니다. 요청의 입력은 세 부분으로 나뉘어 과금됩니다.

구분의미입력 가격 대비
캐시 읽기캐시된 접두사와 같은 부분Opus 5.5와 Sonnet 5.5는 0.05배, Haiku 5.5는 0.1배, Fable 5.1은 0.025배
캐시 쓰기캐시에 새로 기록되는 부분. 5분 항목과 1시간 항목의 가격이 다릅니다5분은 약 1.25배, 1시간은 2배
입력캐시되지 않은 부분. Claude Code에서는 보통 토큰 몇 개입니다1배

단가는 요금 페이지에 있습니다. 평소 Claude Code 세션에서는 매 턴 새 토큰 수백~수천 개만 쓰고, 나머지 수십만 토큰은 캐시 읽기입니다. 접두사가 바뀌면 컨텍스트 전체가 쓰기 가격으로 다시 기록되며, 한 번에 수십만 토큰이 되는 경우도 많습니다.

CoreCode가 하는 일

캐시가 깨지는 시점은 클라이언트가 무엇을 보내는지에 달려 있습니다. 아래 사례는 Claude Code 자체의 동작이며, 어떤 릴레이를 거치든 Anthropic에 직접 연결하든 똑같습니다.

auto 모드의 비용

Claude Code의 auto 권한 모드는 매번 사용자에게 묻지 않고 작업 실행 여부를 스스로 판단합니다. 검사 대상 작업마다 판단이 필요합니다. v2.1.278부터는 게이트웨이나 프록시를 거치는 경우 Claude Code가 먼저 일반 모델 요청 안에서 서버에 작업 검토를 맡기며, 별도 요청이 나가지 않습니다. CoreCode는 이런 요청과 검토 결과를 그대로 전달합니다. 2026년 10월 30일 테스트에서 Opus 5.5와 Sonnet 5.5의 auto 모드는 서버가 검토했고, 메인 대화의 요청만 있었으며 추가 비용은 없었습니다.

서버가 검토하지 않으면 Claude Code는 예전 방식으로 돌아갑니다. 도구를 호출하기 전에 대화 기록 일부와 대기 중인 작업을 담아 모델에 별도의 분류기 요청을 보내 허용 여부를 판단하게 합니다. 공식 문서에 따르면 API 키나 릴레이에서는 이 분류기 요청도 토큰 사용량에 포함됩니다. CoreCode에서 이렇게 되돌아가는 세션은 거의 모두 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS를 설정한 세션이며, 이 변수는 서버 검토도 함께 끕니다. CLAUDE_CODE_AUTO_MODE_SERVER=0을 설정해도 같습니다.

이 검사는 거부될 수도 있습니다. 검사는 모델에 대화 기록 일부를 주고 판정 전에 추론 과정을 적게 합니다. CoreCode에서는 Anthropic의 안전 분류기가 이런 요청을 추론 추출(reasoning_extraction)로 보고 거부하는 일이 반복해서 관찰되었습니다. 거부되는 것은 Claude Code 자체의 검사이지 사용자가 쓴 내용이 아니며, CoreCode가 이 때문에 계정에 불이익을 주지는 않습니다. 다만 같은 검사는 다시 전달되지 않고 재전송도 차단됩니다(403 참고). CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS를 지우고 서버가 검토하게 하면 이런 별도 검사가 사라집니다.

되돌아갔을 때 분류기가 쓰는 모델: Anthropic의 기본값은 Claude Sonnet 5입니다. CoreCode는 Sonnet 5가 아니라 Sonnet 5.5, Opus 5.5, Haiku 5.5, Fable 5.1을 제공하므로, Anthropic의 규칙에 따라 Claude Code는 세션의 모델을 대신 사용합니다. 그래서 Opus로 코딩하면 모든 검사도 Opus 요금으로 청구됩니다.

별도의 분류기 요청으로 되돌아가면 비용은 이렇게 됩니다.

문제는 이 검사에서 맨 앞의 작은 부분만 캐시에 적중한다는 점입니다. 나머지 수만 토큰은 매번 다시 기록되고, 다음 검사는 이번 검사가 기록한 내용을 쓰지 못합니다. 실제 사례는 다음과 같습니다.

알아보는 방법

auto 모드가 켜져 있는지 확인하는 방법

해결 방법

  1. CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 제거: ~/.claude/settings.json의 env 블록, 프로젝트의 .claude/settings.json, 셸 프로필을 확인해 지우세요. CLAUDE_CODE_AUTO_MODE_SERVER=0도 함께 지웁니다. CoreCode에는 둘 다 필요 없습니다. 새 세션을 시작하면 auto 모드를 서버가 검토하며 별도 검사가 나가지 않습니다. /status에서 Auto mode server가 Enabled로 표시되면 확인된 것입니다.
  2. 자리를 비우고 맡길 필요가 없다면 auto 끄기: Shift+Tab을 눌러 Manual 또는 accept-edits 모드로 바꾸면 검사가 멈춥니다. 모든 세션을 Manual로 시작하려면 ~/.claude/settings.json에 다음을 넣으세요.
    {
  "permissions": {
    "defaultMode": "default"
  }
}
    accept-edits로 시작하려면 default 대신 acceptEdits를 쓰세요.
  3. 더 저렴한 분류기 모델 사용: Claude Code v2.1.302부터 환경 변수 CLAUDE_CODE_AUTO_MODE_MODEL로 분류기 모델을 지정할 수 있으며, 전체 모델 ID를 넣어야 합니다. Opus로 코딩할 때 claude-sonnet-5-5로 설정하면 검사가 Sonnet 요금으로 청구됩니다.
    {
  "env": {
    "CLAUDE_CODE_AUTO_MODE_MODEL": "claude-sonnet-5-5"
  }
}
    분류기는 작업이 안전한지 판단하는 역할이고 작은 모델은 판단이 덜 정확하므로, 득실은 직접 따져 보세요.
  4. 비용을 감수하기: auto 모드의 이점은 작업마다 확인하지 않아도 된다는 것입니다. 필요하다면 이 지출은 예상된 것이며 릴레이의 문제가 아닙니다.

그 밖의 미적중 원인

다음은 Claude Code가 보내는 접두사를 바꾸므로, 다음 턴에 캐시 전체가 다시 기록됩니다.

상황설명
세션 도중 모델 전환캐시는 모델별이므로 다른 모델은 처음부터 시작합니다. 다시 돌아오면 원래 모델의 캐시가 만료되었을 수 있습니다.
사고 노력 수준 또는 /fast 변경노력 수준과 fast 모드도 요청을 바꾸어 캐시를 깨뜨립니다.
5분 넘게 멈춤기본 캐시는 5분만 유지됩니다. 커피 한 잔 하고 오면 첫 턴이 전부 다시 기록됩니다. 자주 쉬는 편이라면 1시간 캐시를 참고하세요.
MCP 서버 연결 또는 해제도구 정의는 요청의 맨 앞에 오므로 도구 목록이 바뀌면 접두사 전체가 바뀝니다. Claude Code 기본값인 MCP 도구 검색을 켜 두면 피할 수 있으니 ENABLE_TOOL_SEARCH=false는 설정하지 마세요.
플러그인 켜기 또는 끄기MCP 서버를 가져오는 플러그인은 바로 위 항목과 같은 영향을 줍니다.
/compact압축하면 기록이 다시 쓰이므로 직후 첫 턴은 다시 기록됩니다. 그 뒤에는 세션이 짧아져 더 저렴해집니다.
Claude Code 업그레이드새 버전은 시스템 프롬프트가 다르므로 업그레이드 후 첫 턴은 다시 기록됩니다.
새 세션, /clear, 오랜만의 --resume새 세션은 캐시를 처음부터 씁니다. 오래된 세션을 재개하면 캐시가 이미 만료되었을 가능성이 높습니다.

CLAUDE.md를 고쳐도 캐시가 바로 깨지지는 않지만 바로 적용되지도 않습니다. /clear, /compact 또는 재시작을 기다립니다. 잘 쓰는 방법은 CLAUDE.md 작성법에 있습니다.

캐시에 더 많이 적중시키려면, 가능하면 한 세션에서 작업을 끝내고 도중에 모델이나 사고 노력 수준을 바꾸지 마세요. 컨텍스트가 길어지면 새 세션을 열어 컨텍스트를 다시 쌓지 말고 /compact로 압축하세요.

1시간 캐시

5분에서 60분 정도 생각하다가 다시 이어서 작업하는 일이 잦다면 Claude Code가 1시간 캐시 항목을 쓰게 하세요. ~/.claude/settings.json의 env에 한 줄을 추가합니다(Claude Code v2.1.242 이상 필요).

"CLAUDE_CODE_PROMPT_CACHE_TTL": "1h"

1시간 캐시 쓰기는 입력 가격의 약 2배, 5분 쓰기는 약 1.25배입니다. 쉬는 일이 적으면 쓸 때마다 더 비싸고, 쉬는 일이 많으면 피하게 되는 전체 재기록으로 훨씬 많이 절약됩니다. CoreCode는 1시간 캐시에 필요한 헤더를 그대로 전달하므로 따로 설정할 것이 없습니다.

로그로 원인 찾기

사용 로그를 열어 한 세션의 연속된 요청을 시간순으로 읽어 보세요.

Claude Code에서는 /usage(또는 /cost)로 이 세션의 토큰 사용량과 비용을, /context로 컨텍스트를 무엇이 채우고 있는지 볼 수 있습니다.

로그로도 설명되지 않으면 사용 로그에서 해당 요청들의 시각을 보내 주세요. 업스트림 계정과 라우팅을 확인해 드립니다.

청구서에 나타나는 다른 모델

Opus로만 코딩해도 청구서에 Haiku나 Sonnet이 나타날 수 있으며, 보통 다음 이유 때문입니다.

사용 로그에서 시각으로 해당 기록을 찾으면 각 요청이 어떤 모델을 썼고 얼마가 들었는지 볼 수 있습니다.