Claude Code 토큰 사용량 줄이기: Context Mode와 Headroom

Claude Code의 토큰 사용량을 줄이려면 무엇이 컨텍스트를 채우는지 확인하고, 불필요한 도구 출력이 대화에 들어오지 않게 하세요. 먼저 Claude Code의 기본 기능을 조정한 다음, 필요한 데이터만 처리하고 컨텍스트 축약 뒤에도 작업을 이어가려면 Context Mode를, 로컬 프록시를 거치는 압축이 필요하면 Headroom을 사용해 보세요. 추론과 반복되는 실패가 사용량의 대부분을 차지한다면 두 도구를 추가하기 전에 작업 범위와 모델 선택부터 개선하는 편이 낫습니다.

2026-10-21 기준 Claude Code의 현재 릴리스는 2.1.306입니다. 아래 Headroom 설치 명령은 버전을 0.41.0으로 고정합니다.

Claude Code는 어디에 토큰을 쓰는가?

컨텍스트 점유량의 원인은 /context로 진단하고, 사용량과 예상 비용은 /usage로 확인하세요. 두 명령은 서로 다른 질문에 답하므로 각각의 수치를 구분해서 읽어야 합니다.

확인할 내용	확인 방법	알 수 있는 정보
왜 대화의 컨텍스트가 가득 차는가?	/context	지시 사항, 메시지, 도구 및 기타 컨텍스트가 차지하는 공간
이번 세션에서 얼마나 사용했는가?	/usage	토큰 유형별 사용량과 세션의 예상 비용
구독 플랜의 사용 한도에 가까워졌는가?	/usage의 플랜 정보	API 청구와 구분되는 플랜 사용량
실제로 얼마가 청구되었는가?	요금을 청구하는 제공업체의 사용 내역	해당 업체의 요율과 과금 규칙을 적용한 청구 금액

현재 Claude Code에서 /cost는 /usage의 별칭입니다. 표시되는 달러 금액은 추정치이며, Pro 또는 Max에 포함된 요청을 보낼 때마다 그만큼의 요금이 추가로 발생한다는 뜻은 아닙니다. 이 구분은 Claude Code 비용 문서에서 확인할 수 있습니다.

큰 로그, 브라우저 스냅샷, 의존성 파일, 반복되는 도구 결과는 컨텍스트의 상당 부분을 차지할 수 있습니다. 이전 메시지도 후속 요청에 포함되지만, 프롬프트 캐싱을 활용하면 재사용하는 입력이 새로운 입력보다 저렴해질 수 있습니다. 따라서 눈에 보이는 콘텐츠를 50% 줄였다고 해서 청구 금액도 자동으로 50% 줄어드는 것은 아닙니다.

압축 도구를 추가하기 전에 기본 기능부터 조정하기

낭비가 생기는 원인에 맞춰 기능을 선택하세요. 불필요한 출력이 많다면 조회 범위를 좁히고, 무관한 작업으로 넘어갈 때는 새 대화를 시작하며, 긴 작업을 계속해야 할 때는 컨텍스트를 축약하는 방식이 적합합니다.

Claude에게 정확한 파일 경로, 실패한 테스트 이름, 결과를 검증할 구체적인 명령을 전달하세요. 작은 변경을 위해 저장소 전체를 이해하도록 요청하는 것보다, 문제가 발생한 모듈 하나를 살펴보게 하는 편이 대체로 불필요한 작업을 덜 만듭니다.

서로 관련 없는 작업 사이에서는 필요한 사용량 수치를 먼저 기록한 뒤 /clear를 실행하세요. 같은 작업을 이어갈 때는 무엇을 남길지 지정해 /compact를 사용합니다. 예를 들면 다음과 같습니다.

/compact Preserve the current goal, modified files, failing test names, exact errors, and the next verification command.

이 방법은 문서에 안내된 컨텍스트 관리 방식입니다. 다만 컨텍스트 축약은 요약을 만드는 과정이므로, 모든 내용을 정확히 보존하는 기록 보관 수단으로 볼 수는 없습니다. 중요한 완료 조건은 계속 참조할 수 있는 프로젝트 지침이나 작업 메모에 남겨 두세요.

대화를 주고받을 때마다 축약하지는 마세요. 축약 과정에서는 요약 요청이 발생하고 메시지 기록이 교체되므로, 다음 요청은 더 짧아진 접두부를 새로 캐시에 저장해야 합니다. 축약을 너무 자주 하면 컨텍스트 공간은 줄어도 요약 작업과 캐시 재구축에 드는 비용이 늘어날 수 있습니다.

추론 강도 조절을 지원하는 모델로 단순한 작업을 할 때는 /effort low를 시도해 보세요. 낮은 추론 강도는 추론에 드는 작업량을 줄일 수 있지만, 도구가 이미 반환한 로그의 길이를 줄여 주지는 않습니다. 명령으로 바꾼 추론 강도는 선택한 모델에 계속 적용되므로, 비교가 끝나면 원래 선호하던 설정으로 되돌리세요. 지원되는 제어 방식과 모델 별칭은 모델 설정 문서에 나와 있습니다.

서브에이전트도 기본 기능만으로 컨텍스트를 분리하는 방법입니다. 별도의 컨텍스트에서 작업하고 요약을 반환하므로 상위 대화의 컨텍스트를 보호할 수 있습니다. 하지만 서브에이전트가 보내는 요청 역시 토큰을 사용하므로 전체 소비량에서 제외하면 안 됩니다.

Context Mode와 Headroom 중 무엇부터 써야 할까?

Claude에 데이터를 돌려주기 전에 필요한 부분만 남길 수 있다면 Context Mode를 선택하세요. 기존 도구 호출을 유지하면서 그 결과가 압축 계층을 거치게 하고 싶다면 Headroom부터 시험하는 편이 맞습니다.

현재의 병목	먼저 시도할 방법	달라지는 점
로컬에서 조회하거나 처리할 수 있는 큰 파일 또는 로그	Context Mode	Claude가 실행·검색 도구를 사용해 선별된 결과만 받음
컨텍스트 축약 후 작업 상태의 일부를 잃어버림	Context Mode	수명 주기 훅이 이벤트를 기록하고 작업을 이어갈 정보를 복원함
기존 도구 작업에서 지나치게 긴 출력이 발생함	Headroom	로컬 프록시가 요청을 전달하기 전에 압축 대상인 도구 콘텐츠를 줄임
짧은 작업에서 추론이나 재시도가 사용량의 대부분을 차지함	기본 기능의 작업 범위, 추론 강도, 모델 설정	구성 요소를 추가하기 전에 수행하는 작업 자체를 줄임

어떤 변경이 결과에 영향을 주었는지 알 수 있도록 도구는 한 번에 하나씩 시험하세요. 두 도구를 동시에 도입하면 컨텍스트와 비용 변화의 원인을 구분하기 어려워집니다.

공개된 절감 비율을 그대로 비교해서는 안 됩니다. Context Mode의 벤치마크 자료는 선별된 예제에서 출력 바이트 수를 측정합니다. Headroom의 21%–57% 수치는 시드값을 고정한 오프라인 도구 출력 워크로드에서 나온 결과입니다. 어느 쪽도 실제 Claude Code 전체 청구액의 감소율을 입증하지 않으며, 압축 후에도 작업이 올바르게 완료되는지 확인하는 과정을 대신하지 않습니다.

Context Mode: 파일 전체 대신 필요한 결과만 반환하기

Context Mode는 입력 전체를 Claude의 대화에 넣지 않고도 로컬 처리만으로 답을 얻을 수 있을 때 유용합니다. 플러그인은 선택된 세션 이벤트를 SQLite에 기록하며, 훅을 사용해 컨텍스트 축약 뒤 작업을 이어가는 데 필요한 정보를 복원합니다.

현재 패키지는 Node.js 22.5.0 이상을 요구합니다. Bash에서 설치된 버전을 확인하세요.

claude --version
node --version

Claude Code 안에서 프로젝트 문서의 마켓플레이스 설치 방법을 사용합니다.

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

Claude Code를 재시작한 뒤 다음을 실행하세요.

/context-mode:ctx-doctor

진단 명령은 런타임 지원, 플러그인 등록, 훅, SQLite 검색 지원 등의 구성 요소를 확인합니다. 플러그인이 정상 작동한다고 판단하기 전에 관련 실패 항목을 해결하세요. MCP 서버만 설치하면 플러그인과 동일한 수명 주기 훅 연동까지 제공되는 것은 아닙니다.

구체적으로 확인하려면 버전 2 또는 버전 3의 package-lock.json이 이미 있는 npm 프로젝트를 여세요. Claude에게 path: "package-lock.json"과 language: "javascript"를 지정해 ctx_execute_file을 호출하고, 다음 코드를 실행하도록 요청합니다.

const lock = JSON.parse(FILE_CONTENT);
if (!lock.packages) {
  console.log("This example requires an npm v2/v3 lockfile.");
} else {
  const rows = Object.entries(lock.packages).filter(([path]) => path !== "");
  console.log(JSON.stringify({
    lockfileVersion: lock.lockfileVersion,
    packageEntries: rows.length,
    entriesMarkedDev: rows.filter(([, pkg]) => pkg.dev === true).length
  }, null, 2));
}

이 도구는 FILE_CONTENT를 통해 파일 내용을 코드에 전달합니다. 예상 결과는 전체 잠금 파일이 아니라, 요청한 세 필드가 담긴 작은 JSON 객체입니다. 실제 숫자는 프로젝트에 따라 달라지며, 여기서 세는 대상은 고유한 패키지 이름이 아닌 잠금 파일의 항목입니다.

이어서 다음을 실행하세요.

/context-mode:ctx-stats

통계 명령에 Context Mode 활동이 표시되는지 확인합니다. 호출이 없다고 나온다면 요청한 실행 경로로 처리되었다는 사실을 아직 확인하지 못한 것입니다. 여기 표시되는 출력 감소량을 실제 청구액 계산으로 해석해서는 안 됩니다.

로그에도 같은 방식을 적용할 수 있습니다. 개수는 로컬에서 계산하고, 관련 오류를 선별한 뒤 원본 위치와 함께 정확한 발췌문을 반환하게 하세요. Claude가 정확한 코드를 봐야 하는 작은 소스 파일에는 직접 읽기를 유지하는 편이 좋습니다.

Context Mode는 Elastic License 2.0을 사용합니다. 실행 환경을 격리하지만, 운영체제 수준의 완전한 보안 샌드박스는 아니며 실행 도구가 파일시스템 접근 권한을 상속할 수 있습니다. 에이전트가 명령을 실행할 때 평소 적용하던 권한 및 샌드박스 제어는 그대로 유지하세요.

Headroom: 압축 대상 도구 출력을 로컬 프록시로 보내기

Headroom은 일반적인 Claude Code 도구를 계속 사용하면서 프록시가 압축 가능한 출력을 줄이도록 하는 작업에 적합합니다. 코딩 작업에 맞춘 기본 동작은 캐시의 안정성도 고려하며, 모든 소스 파일이나 모든 요청을 압축한다고 보장하지는 않습니다.

이 예제에서는 Anthropic Console API 키를 사용하므로 Claude 구독과 별도로 API 요금이 발생합니다. uv와 Claude Code가 설치되어 있고, 이미 실행 중인 Headroom 프록시가 없으며, 충돌하는 사용자 지정 게이트웨이나 클라우드 제공업체 설정도 활성화되어 있지 않다고 가정합니다. 조직의 기존 게이트웨이를 사용한다면 그 구성에 맞는 별도 연동 방법이 필요합니다.

Headroom의 설치 안내에 따라 Bash에서 버전을 지정한 프록시 패키지를 설치하세요.

uv tool install --python 3.13 "headroom-ai[proxy]==0.41.0"
headroom --version

버전 확인 결과에는 0.41.0이 표시되어야 합니다. 아래 명령으로 키를 화면에 표시하지 않고 입력한 다음 Enter를 누르고, 래퍼를 시작하세요.

read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
HEADROOM_TELEMETRY=on HEADROOM_BEACON=off headroom wrap claude --code-memory none

Claude가 사용자 지정 API 키 사용을 물으면 승인하고, /status에서 활성 인증 정보와 모델을 확인하세요. 이전에 해당 키를 거절했다면 인증 문서에 설명된 /config의 “Use custom API key” 설정을 확인합니다.

래퍼는 로컬 프록시를 시작하거나 재사용하고, Claude를 프록시를 통해 실행하며, Headroom의 원본 재조회용 MCP 서버를 Claude Code 설정에 등록합니다. --code-memory none은 추가 Serena 연동만 건너뛰므로 Headroom의 재조회 기능은 계속 사용할 수 있습니다. 이 절차에 --no-mcp를 추가하면 압축 콘텐츠의 표시자와 연결된 재조회 경로가 사라지므로 추가하지 마세요. 각 옵션은 0.41.0 래퍼 구현에 정의되어 있습니다.

환경 변수는 로컬 텔레메트리 수집을 켜고, 선택적으로 수집 정보를 업로드하는 비콘을 끕니다. 비콘을 꺼도 모델 요청은 설정된 모델 제공업체로 전송됩니다.

시작할 때 출력되는 프록시 주소를 기록하세요. 일반적인 포트는 8787이지만 래퍼가 다른 사용 가능한 포트를 선택할 수도 있습니다. 두 번째 Bash 터미널에서 다음을 실행하되, 필요하면 실제 포트 번호로 바꾸세요.

curl -fsS http://127.0.0.1:8787/health
curl -fsS http://127.0.0.1:8787/stats

이제 래퍼로 실행한 Claude에 기존의 충분히 큰 test.log를 대상으로 범위가 제한된 작업을 맡기세요. 파일은 수정하지 않고, 실패한 테스트를 중복 없이 나열하며 각 테스트의 첫 번째 오류를 원문 그대로 인용하도록 요청합니다. 작업이 끝나면 /stats를 다시 조회하세요.

상태 확인 엔드포인트가 정상 응답하면 프록시가 실행 중임을 알 수 있습니다. requests.total의 증가는 완료된 요청이 프록시의 집계 경로에 도달했음을 보여 주며, requests.failed와 requests.rate_limited는 따로 확인해야 합니다. 필드의 의미는 메트릭 문서에 설명되어 있습니다. 짧은 출력이나 압축하지 않도록 보호된 데이터에서 절감량이 0이라고 해서 라우팅 실패가 입증되는 것은 아닙니다.

인증이 실패하면 재시도하기 전에 ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL 및 제공업체 설정 사이에 충돌이 있는지 살펴보세요. 요청이 전혀 나타나지 않는다면 출력된 포트와 실제로 실행한 세션의 요청 경로를 확인합니다.

Headroom의 압축·캐시·재조회 메커니즘은 Claude가 생략된 세부 정보가 필요할 때 보관된 원본을 다시 가져올 수 있습니다. 재조회에는 추가 작업이 들고 원본 보관 기간도 유한합니다. 원본을 더 이상 가져올 수 없다면 소스 파일을 직접 확인하거나 해당 명령을 다시 실행하세요.

래퍼로 실행한 Claude를 종료한 뒤, 원래 터미널의 같은 프로젝트에서 시험용 설정을 정리합니다. 이때도 실제 사용한 포트 번호를 지정하세요.

headroom unwrap claude --port 8787
unset ANTHROPIC_API_KEY

설정 해제 명령은 Headroom이 관리하는 설정을 제거하고 해당 프록시의 중지를 시도합니다. 환경 변수 해제는 이번 시험을 위해 내보낸 API 인증 정보를 제거하는 동작입니다. 평소의 인증 방식으로 돌아가기 전에 /status를 확인하세요.

범위가 명확한 하위 작업에 저렴한 모델 사용하기

제공된 로그에서 실패 내용을 추출하는 작업처럼 결과를 적은 노력으로 검증할 수 있다면 더 저렴한 모델을 사용하세요. 이 방법은 작업의 단가를 바꾸지만, 사용하는 토큰 수까지 줄어든다고 보장하지는 않습니다.

기본 기능만 사용하는 비교 기준을 만들려면 .claude/agents/log-summary.md를 생성합니다.

---
name: log-summary
description: Summarize supplied test logs and identify failing tests.
model: haiku
tools: Read, Grep, Glob
maxTurns: 6
---

Read only the log paths supplied in the task.
Return failing test names, exact error excerpts, and file or line references.
Report uncertainty and missing evidence.
Do not modify files.

에이전트 디렉터리를 만든 뒤 Claude Code를 재시작하고, 기존 로그를 대상으로 작업자를 호출하세요.

Use log-summary to inspect ./test.log and return the first failing test and its exact error. Stop after the summary.

실행 중에 /tasks를 열어 작업자가 실제 사용하는 모델을 확인하고, 반환된 발췌문을 원본 로그와 대조하세요. maxTurns는 턴 수를 제한하며, 금액이나 토큰 수의 상한은 아닙니다. 이 한도에 도달하면 결과가 일부만 완성된 상태로 끝날 수 있습니다. 각 설정 필드와 수명 주기 관련 내용은 서브에이전트 문서에 설명되어 있습니다.

haiku는 별칭이므로 실제 모델은 제공업체 설정에 따라 결정됩니다. 어려운 설계 결정이나 원인이 모호한 디버깅은 이를 안정적으로 해결하는 모델에 맡기세요. 저렴한 작업자라도 반복해서 수정 지시를 내려야 한다면 전체 비용은 오히려 커질 수 있습니다.

BetterToken을 통해 사용량 기반으로 모델을 이용한다면 Claude Code 설정 안내를 따르세요. Anthropic 호환 기본 URL은 https://bettertoken.ai이며 /v1을 붙이지 않습니다. ANTHROPIC_DEFAULT_HAIKU_MODEL을 비롯한 별칭 매핑을 확인하세요. 모든 별칭에 같은 모델 ID를 지정했다면 haiku를 선택해도 다른 저렴한 모델로 바뀌지 않습니다. 지원되는 ID를 의도에 맞게 선택하고, 현재 모델 및 캐시 요율을 비교한 뒤 기록된 모델과 청구 금액을 확인하세요. BetterToken API 요금은 Claude 구독과 별개입니다. 이 제공업체 설정은 앞서 Anthropic에 직접 연결한 Headroom 시험과 구분해서 적용해야 합니다.

작업 전체의 비용과 정확성으로 판단하기

캐시의 영향, 서브에이전트, 원본 재조회, 재시도까지 포함했을 때 완료된 작업의 결과가 개선되는 경우에만 압축 도구를 계속 사용하세요. 출력이 짧아졌다는 사실만으로 실제 작업 비용이나 정확성이 좋아졌다고 판단해서는 안 됩니다.

비교할 때는 저장소 상태, 프롬프트, 실제 모델, 추론 강도, 검증 명령을 같게 맞추세요. 각 실행이 재사용할 캐시가 있는 상태에서 시작했는지, 없는 상태에서 시작했는지도 기록해야 합니다. 이 조건을 섞으면 결과가 왜곡될 수 있습니다. 최종 패치나 답변뿐 아니라 그 결과가 인용하는 정확한 근거까지 확인하세요.

Anthropic API의 사용량 집계에서 input_tokens, cache_creation_input_tokens, cache_read_input_tokens는 서로 다른 항목입니다. input_tokens만으로 전체 입력량을 알 수 없으며, 출력 토큰도 계산에 포함해야 합니다. 요율이 백만 토큰 기준으로 제시된다면 모든 요청에 대해 sum(token_count × category_rate / 1,000,000)을 계산하세요. 캐시 보관 시간에 따라 쓰기 요율이 다르다면 해당 쓰기 사용량을 나누어 계산하고, 토큰 외에 반드시 내야 하는 요금도 더해야 합니다.

Claude Code에서 기본 대화의 캐시 정보를 표시하려면 버전 2.1.251 이상이 필요하며, 이 표시에는 서브에이전트가 포함되지 않습니다. 프록시의 절감량 카운터는 진단에 유용하지만, 지출을 비교할 때는 실제 요금을 청구하는 제공업체의 기록을 기준으로 삼으세요.

생략된 오류 때문에 다시 조사하게 되거나, 작업자를 반복해서 도와줘야 하거나, 재조회 과정에서 원래의 컨텍스트 양이 그대로 되살아난다면 압축 수준을 낮추거나 작업 범위를 바꾸세요. 목표는 전체 유료 작업량을 줄이면서 올바른 결과를 얻는 것입니다.