
| "토큰을 줄여 준다는데, 내 클로드 사용량은 얼마나 줄어들까?"
이 레터에서 다루는 것:
- 압축이 일어나는 방식
- 입력 종류별로 줄어든 정도와 거의 줄지 않는 경우
- 프록시를 끼우면 함께 바뀌는 4가지
Headroom은 보내기 전에 입력을 줄이는 프록시입니다
클로드와 서버 사이에서 도구 출력을 줄입니다
토큰은 클로드가 글의 양을 세는 단위이고 프록시는 내 컴퓨터와 서버 사이에서 요청을 대신 전달하는 중간 프로그램입니다. Headroom은 그 자리에서 클로드 코드가 파일을 읽거나 명령을 실행해 받은 도구 출력, 로그, JSON을 서버로 보내기 전에 줄입니다. JSON은 상품 목록처럼 항목이 중괄호와 대괄호로 짜인 데이터 형식입니다.
쓰는 방법은 라이브러리, 프록시, MCP, headroom wrap claude로 나뉩니다.[2] 프록시 방식은 터미널 하나에서 headroom proxy --port 8787을 켜고 다른 터미널에서 ENABLE_TOOL_SEARCH=true ANTHROPIC_BASE_URL=http://localhost:8787 claude로 클로드 코드를 실행합니다.[3]

반복되는 줄은 대표만 남기고 오류는 유지합니다

핵심은 반복 정리입니다. 같은 모양의 항목이 수천 개 이어지는 로그나 JSON 목록에서 대표 항목만 남기고, 공식 문서에 따르면 error, failed 같은 단어가 든 항목과 평균에서 크게 벗어난 값은 줄이는 대상에서 빠집니다.[4]
압축 전 원문은 따로 저장되고 클로드가 필요하면 되돌려 받습니다. Headroom은 이 구조를 CCR(Compress-Cache-Retrieve)이라고 부릅니다.[5]
줄어드는 양은 항목이 얼마나 반복되느냐에 비례하며 공식 README도 같은 설명을 합니다.[6] 저희는 이 성질을 반복도라고 부르겠습니다.
공식 수치는 자사 측정입니다

공식 발표 기준으로 README는 코드 검색 21%, 코드 탐색 42%, 이슈 분류 30%, 장애 디버깅 57% 절감을 제시합니다. 독립 검증은 확인하지 못했습니다. Limitations 문서도 자신의 압축률 표를 "합성 페이로드 단일 샘플 측정"이라 밝히고 직접 재 보라고 안내합니다.[7]
어디서 크게 줄고 어디서 거의 줄지 않을까
우리 측정: 같은 로그가 JSON이면 71%, 평문이면 0%
저희는 클로드를 호출하지 않고 Headroom의 compress() 함수로 압축만 따로 쟀습니다. 2026년 10월 23일 v0.41.0에서 공개 데이터와 직접 쓴 짧은 대화, 입력 7종을 입력별 1회씩 측정했고 토큰은 GPT-4o 토크나이저 기준입니다. 아래 비율은 클로드 사용량이 줄어든 비율이 아닙니다.

로그 2,000줄을 JSON 배열로 넣으면 64,559토큰이 18,403토큰이 되어 71%가 줄었고 GitHub 커밋 30건 JSON은 48%, 이슈 30건 JSON은 31%였습니다.
같은 로그를 평문 그대로 넣으면 64,557토큰이 그대로였고 소스 코드(7,429토큰)와 짧은 대화(95토큰)도 0%였습니다. 공식 문서는 평문 압축에 선택 기능인 ML 모델(Kompress)이 필요하다고 적지만 저희 환경에서는 내려받지 못해 쓰지 못했습니다. v0.42.0에서는 재측정하지 않았습니다.
거의 줄지 않는 입력은 공식 문서에도 적혀 있습니다

공식 Limitations 문서가 압축하지 않는 대상으로 꼽는 입력은 저희의 0% 결과와 맞습니다.[8]
저희가 2026년 10월 22일 프록시를 거쳐 클로드 코드로 요청 9건을 처리했을 때는 858,953토큰 중 2,758토큰이 줄었습니다(1% 미만). 요청 대부분이 클로드 코드 자체의 기본 컨텍스트였고 큰 JSON·로그 출력이 적었기 때문으로 보입니다. 공식 Troubleshooting도 기본 설정에서는 새 턴만 압축해 절감이 작게 보일 수 있다고 설명합니다.[9]
많이 줄었다고 안전한 것은 아닙니다
저희 측정에서 변경기록 문서(40KB)는 94%가 줄었습니다. Headroom이 문서를 로그로 잘못 판단해 37개 버전 중 7개만 남긴 결과로, 원문은 복원할 수 있지만 안전한 절감은 아닙니다.
제3자 보고도 있습니다. 공개 이슈 #600에서 한 사용자가 2026년 6월 14일 Windows의 개발 중 빌드(표기 버전 0.25.0)로 JSON 로그를 압축했더니 심어 둔 오류 문장(payment gateway error PG-5523 …)이 결과에서 빠졌다고 보고했습니다.[10] 저희는 재현하지 않았습니다. 저희 로그 측정에서는 고유한 오류 줄 378개가 모두 유지됐지만 1회 결과여서 범용 보장은 아닙니다.
프록시를 끼우면 함께 바뀌는 것

Remote Control 메뉴가 사라집니다
Claude Code v2.1.196 이상은 ANTHROPIC_BASE_URL의 주소가 api.anthropic.com이 아니면 Remote Control을 제공하지 않습니다. 클라이언트 쪽 판정이라 Headroom이 되살릴 수 없으며 필요한 세션은 프록시 없이 실행하라고 공식 Troubleshooting이 안내합니다.[11]
압축 전 원문이 암호화 없이 저장됩니다
프록시는 대화와 도구 결과를 평문으로 읽습니다. 되돌리기용 원문은 ~/.headroom/ccr_store.db에 암호화 없이 기본 30분 저장되고 만료된 항목은 다음 조회 때 지워지므로 그 뒤에도 남을 수 있습니다.[12]
도구 결과에 비밀번호나 고객 정보가 있었다면 그 값이 그동안 디스크에 있는 셈입니다. HEADROOM_CCR_BACKEND=memory headroom proxy --port 8787로 실행하면 디스크에 남기지 않습니다.
익명 통계 전송이 기본으로 켜져 있습니다
압축 비율, 토큰 합계, 모델 이름, 운영체제 종류와 설치별 무작위 ID를 보내며 프롬프트·코드·파일 경로는 보내지 않는다고 공식 문서가 설명합니다.[13] 끄려면 HEADROOM_BEACON=off나 DO_NOT_TRACK=1을 설정합니다. HEADROOM_OFFLINE=1은 모든 외부 통신을 막습니다. v0.42.0부터는 HEADROOM_TELEMETRY=off도 이 전송을 함께 끕니다.[14]
잘못된 값을 적으면 전송이 꺼지지 않으므로 안내된 값을 정확히 써야 합니다. 구독 로그인을 쓰면 5분마다 구독 사용량을 조회하며 로그인 토큰이 Anthropic으로 전달되고 HEADROOM_NO_SUBSCRIPTION_TRACKING=1로 끕니다.[15]
wrap은 설정 파일까지 바꿉니다
headroom wrap claude는 설정 파일에 구성을 넣고 CLAUDE.md·AGENTS.md를 수정하거나 MCP 서버를 설치할 수 있습니다. 되돌리는 headroom unwrap이 있지만 완전한 제거는 여러 명령으로 나뉘고 통합 headroom uninstall 제안은 이슈 #748에서 열려 있습니다.
셀러라면 이렇게
저희가 잰 입력은 공개 데이터였고 주문·상품 목록은 측정하지 않아 셀러의 데이터에서 얼마나 줄지는 말씀드릴 수 없습니다. 다만 주문·상품 목록처럼 같은 모양의 항목이 길게 반복되는 JSON을 클로드에 자주 넘기신다면, 먼저 자신의 입력으로 줄어드는지 재 보시면 좋습니다. 프록시를 켠 상태에서 headroom dashboard로 줄어든 양을 볼 수 있고, 쌓인 기록은 headroom savings 명령으로 확인합니다.[16] 상품 설명 글이나 짧은 질문 위주라면 얻을 것이 적습니다. 고객 정보가 섞이는 작업이라면 원문의 30분 로컬 저장부터 확인하시기 바랍니다.
🔑 핵심
다음 발행에서 또 인사드리겠습니다.
swimmingcode 드림.
궁금한 점이 있으시면 답장으로 알려주세요. 확인해서 답해드립니다.
각주
- [1] GitHub README·v0.42.0 릴리스 노트 — https://github.com/headroomlabs-ai/headroom
- [2] GitHub README·v0.42.0 릴리스 노트 — https://github.com/headroomlabs-ai/headroom
- [3] 공식 문서 Troubleshooting — https://docs.headroomlabs.ai/docs/troubleshooting
- [4] 공식 문서 Limitations — https://docs.headroomlabs.ai/docs/limitations
- [5] 공식 문서 Security Model — https://docs.headroomlabs.ai/docs/security-model
- [6] GitHub README·v0.42.0 릴리스 노트 — https://github.com/headroomlabs-ai/headroom
- [7] 공식 문서 Limitations — https://docs.headroomlabs.ai/docs/limitations
- [8] 공식 문서 Limitations — https://docs.headroomlabs.ai/docs/limitations
- [9] 공식 문서 Troubleshooting — https://docs.headroomlabs.ai/docs/troubleshooting
- [10] Headroom 이슈 #600 댓글(2026년 6월 14일) — https://github.com/headroomlabs-ai/headroom/issues/600#issuecomment-4702244284
- [11] 공식 문서 Troubleshooting — https://docs.headroomlabs.ai/docs/troubleshooting
- [12] 공식 문서 Security Model — https://docs.headroomlabs.ai/docs/security-model
- [13] 공식 문서 Security Model — https://docs.headroomlabs.ai/docs/security-model
- [14] GitHub README·v0.42.0 릴리스 노트 — https://github.com/headroomlabs-ai/headroom
- [15] 공식 문서 Security Model — https://docs.headroomlabs.ai/docs/security-model
- [16] GitHub README·v0.42.0 릴리스 노트 — https://github.com/headroomlabs-ai/headroom
의견을 남겨주세요