Headroom 프록시로 Claude Code 토큰 사용량 24% 절감하기

github.com

GitHub - headroomlabs-ai/headroom: Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 60-95% fewer tokens, same answers. Library, proxy, MCP server.↗

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 60-95% fewer tokens, same answers. Library, proxy, MCP server. - headroomlabs-ai/headroom

ai 의 토큰 사용량을 최적화하는 방향을 항상 고민하게 된다. Headroom 이라는 도구가 있는데, 로컬 프록시 도구다. Claude Code와 Anthropic API 사이에 위치하면서 요청을 가로채 압축한 뒤 전달하는 방식으로 동작한다. 한 달가량 사용해 본 결과 약 24%의 비용 절감 효과를 확인했고, 설치 방법과 함께 내부 절감 방식을 정리한다.

프록시 하나만 띄우면 기존 워크플로우를 전혀 바꾸지 않고도 토큰 사용량을 줄일 수 있다는 점이 매력적이다. 압축효과와 프롬프트 캐시 정렬로 인한 간접 절감까지 더하면 체감 효과는 더 크다.

설치 및 프록시 실행

pip install "headroom-ai[code][proxy]" anthropic
headroom proxy --port 15555

Headroom은 Python 패키지로 배포되므로 Python이 설치되어 있어야 한다. pip로 설치한 뒤 프록시 서버를 구동한다.

export ANTHROPIC_BASE_URL=http://127.0.0.1:15555
claude

프록시가 15555 포트에서 실행되면, Claude Code가 Anthropic API 대신 이 프록시를 바라보도록 환경 변수를 지정하고 실행한다.

매번 환경 변수 입력이 번거롭다면

nano ~/.zshrc
 
# 맨 아래줄에 다음 내용 추가 후 저장 (Ctrl+O 엔터, Ctrl+X 종료)
export ANTHROPIC_BASE_URL=http://127.0.0.1:15555
 
source ~/.zshrc

터미널을 열 때마다 export 명령을 입력하고 싶지 않다면 셸 설정 파일에 등록해 두면 된다. 이후에는 claude 명령만 입력해도 항상 프록시를 경유해서 실행된다.

절감 효과 집계 확인

프록시를 띄운 포트의 /stats 경로로 접근하면 지금까지의 사용 통계를 확인할 수 있다.

http://127.0.0.1:15555/stats

응답은 가공되지 않은 JSON 형태라서 그 자체로 가시화되지는 않는다. 다만 AI에게 그대로 던져주고 분석을 시키면 알아서 잘 정리해 준다. 실제로 한 달가량 사용한 뒤의 통계 일부는 다음과 같다.

"summary": {
    "mode": "token",
    "api_requests": 584,
    "primary_model": "claude-opus-4-8",
    "compression": {
        "requests_compressed": 533,
        "avg_compression_pct": 20.8,
        "best_compression_pct": 65.5,
        "best_detail": "33,971 → 11,724 tokens",
        "total_tokens_removed": 13078430,
        "total_tokens_saved_with_rtk": 13078430,
        "total_tokens_before_with_rtk": 64728531
    },
    "cost": {
        "without_headroom_usd": 234.92,
        "with_headroom_usd": 177.86,
        "total_saved_usd": 57.06,
        "savings_pct": 24.3,
        "breakdown": {
            "cache_savings_usd": 292.48,
            "compression_savings_usd": 57.06
        }
    }
}

주요 지표를 해석하면 다음과 같다.

• total_tokens_before_with_rtk가 압축 전 총 사용 토큰, total_tokens_saved_with_rtk가 절약된 토큰이다. 약 6,470만 토큰 중 1,300만 토큰을 줄여 24.3%의 비용을 절감했다.
• 평균 압축률은 20.8%이고, 가장 압축이 잘 된 요청은 33,971 토큰을 11,724 토큰으로 줄여 65.5%까지 압축됐다.
• CacheAligner 덕분에 Anthropic 자체 프롬프트 캐시 적중률이 73% 수준으로 유지됐고, 이로 인한 간접 절약 가치는 약 300달러(cache_savings_usd)에 달한다.

압축 과정에서 처리 오버헤드가 2% 정도 늘어난 것으로 집계되지만, 절감 폭에 비하면 유의미한 수치는 아니다.

대시보드를 사용하면 훨씬 한눈에 파악하기 좋다. /dashboard 경로로 접속하면 된다.

Headroom의 절감 방식

통계에 나타나는 각 전략이 실제로 어떤 방식으로 토큰을 줄이는지 살펴본다.

SmartCrusher (json_bloat)

에이전트가 파일 목록을 읽거나 API 결과를 받아올 때 데이터는 주로 JSON으로 오간다. 여기에는 중괄호와 따옴표 같은 구조 부호, 그리고 id, createdAt 같은 반복 필드가 대량으로 포함된다. SmartCrusher는 의미 전달에 기여하지 않는 이 노이즈를 쳐내서 토큰을 절약한다.

Kompress (compressions_by_strategy)

ModernBERT 기반의 텍스트 압축 방식이다. 주석이나 문서, 로그처럼 자연어가 섞인 텍스트를 처리할 때 사용된다. 가벼운 AI 모델이 의미는 유지하면서 토큰을 덜 소비하는 구조로 문장을 고쳐서 Claude에게 전달한다.

Code-Aware (code_aware)

코드를 AST(추상 구문 트리)로 분석해서 노이즈와 보일러플레이트를 제거한 뒤 전달한다. 단순 문자열 치환이 아니라 구문 구조를 이해한 상태에서 압축하므로 코드의 의미가 손상되지 않는다.

CCR

압축률을 높이다 보면 정보 손실률이 함께 높아질 수 있다. CCR은 이를 대비해 원본 데이터를 로컬 컴퓨터에 해시로 보관해 둔다. 압축된 텍스트를 보내면서, 모델이 더 자세한 정보가 필요하다고 판단하면 해시된 원본 데이터를 호출할 수 있도록 뒷배를 마련해 두는 구조다.

CacheAligner (prefix_cache)

Anthropic API에는 이전에 보낸 프롬프트와 동일한 내용이 앞부분에 있으면 해당 구간 비용을 90% 할인해 주는 프롬프트 캐싱 기능이 있다. 문제는 대화가 길어지면서 컨텍스트가 조금씩 바뀌면 캐시가 깨지기 쉽다는 점이다. CacheAligner는 변하지 않는 내용을 앞쪽에 고정하고 가변 내용을 뒤에 배치하는 방식으로 프롬프트를 정렬해서, 캐시 적중률을 높게 유지해 준다.