AI 도구·트렌드

Headroom 토큰 압축, 효과 큰 입력과 거의 없는 입력

우리 측정에선 로그 JSON 71%, 코드와 짧은 대화는 0%였습니다

| 조회 18 |
0
|
Headroom 토큰 압축 대표 이미지
Headroom 토큰 압축 대표 이미지

안녕하세요, swimmingcode입니다.

클로드에 보내기 전에 도구 출력·로그·JSON을 내 컴퓨터에서 줄여 주는 오픈소스 프록시 Headroom은 GitHub 별이 7만 8천 개를 넘었습니다. 이 글은 v0.42.0(2026년 10월 26일 공개)[1] 기준으로, 공식 문서(2026년 11월 5일 확인)와 저희가 직접 잰 압축량으로 효과가 큰 곳과 작은 곳을 정리했습니다.

| "토큰을 줄여 준다는데, 내 클로드 사용량은 얼마나 줄어들까?"

이 레터에서 다루는 것:

  • 압축이 일어나는 방식
  • 입력 종류별로 줄어든 정도와 거의 줄지 않는 경우
  • 프록시를 끼우면 함께 바뀌는 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]

Headroom 공식 데모 — 클로드 코드를 띄우고 브라우저 대시보드로 절감 현황을 확인하는 화면
Headroom 공식 데모 — 클로드 코드를 띄우고 브라우저 대시보드로 절감 현황을 확인하는 화면

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

압축 원리 도식
압축 원리 도식

핵심은 반복 정리입니다. 같은 모양의 항목이 수천 개 이어지는 로그나 JSON 목록에서 대표 항목만 남기고, 공식 문서에 따르면 error, failed 같은 단어가 든 항목과 평균에서 크게 벗어난 값은 줄이는 대상에서 빠집니다.[4]

압축 전 원문은 따로 저장되고 클로드가 필요하면 되돌려 받습니다. Headroom은 이 구조를 CCR(Compress-Cache-Retrieve)이라고 부릅니다.[5]

줄어드는 양은 항목이 얼마나 반복되느냐에 비례하며 공식 README도 같은 설명을 합니다.[6] 저희는 이 성질을 반복도라고 부르겠습니다.

공식 수치는 자사 측정입니다

Headroom 공식 README 도식 — 55,957토큰이 24,340토큰으로 줄었다는 공식 발표 예시
Headroom 공식 README 도식 — 55,957토큰이 24,340토큰으로 줄었다는 공식 발표 예시

공식 발표 기준으로 README는 코드 검색 21%, 코드 탐색 42%, 이슈 분류 30%, 장애 디버깅 57% 절감을 제시합니다. 독립 검증은 확인하지 못했습니다. Limitations 문서도 자신의 압축률 표를 "합성 페이로드 단일 샘플 측정"이라 밝히고 직접 재 보라고 안내합니다.[7]


어디서 크게 줄고 어디서 거의 줄지 않을까

우리 측정: 같은 로그가 JSON이면 71%, 평문이면 0%

저희는 클로드를 호출하지 않고 Headroom의 compress() 함수로 압축만 따로 쟀습니다. 2026년 10월 23일 v0.41.0에서 공개 데이터와 직접 쓴 짧은 대화, 입력 7종을 입력별 1회씩 측정했고 토큰은 GPT-4o 토크나이저 기준입니다. 아래 비율은 클로드 사용량이 줄어든 비율이 아닙니다.

우리 측정 — 입력 7종의 압축 전후 토큰 막대 비교
우리 측정 — 입력 7종의 압축 전후 토큰 막대 비교

로그 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 기준
효과가 큰 입력과 거의 없는 입력 비교 — 공식 Limitations 기준

공식 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회 결과여서 범용 보장은 아닙니다.


프록시를 끼우면 함께 바뀌는 것

프록시를 끼우면 바뀌는 4가지
프록시를 끼우면 바뀌는 4가지

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분 로컬 저장부터 확인하시기 바랍니다.


🔑 핵심

Headroom은 도구 출력·로그·JSON을 서버로 보내기 전에 내 컴퓨터에서 줄이는 프록시이며 같은 모양이 반복될수록 많이 줄고 소스 코드·짧은 메시지·검색 결과는 줄지 않습니다.

저희 1회 측정(클로드 호출 없이 압축만)에서는 JSON 로그 71%, 커밋 JSON 48%, 이슈 JSON 31%가 줄었고 평문 로그·코드·짧은 대화는 0%였습니다. 프록시를 끼우면 Remote Control이 사라지고 원문이 로컬에 저장되며 익명 통계가 기본으로 전송됩니다.


다음 발행에서 또 인사드리겠습니다.

swimmingcode 드림.

궁금한 점이 있으시면 답장으로 알려주세요. 확인해서 답해드립니다.

https://tally.so/r/GxXxWo

각주

  1. [1] GitHub README·v0.42.0 릴리스 노트 — https://github.com/headroomlabs-ai/headroom
  2. [2] GitHub README·v0.42.0 릴리스 노트 — https://github.com/headroomlabs-ai/headroom
  3. [3] 공식 문서 Troubleshooting — https://docs.headroomlabs.ai/docs/troubleshooting
  4. [4] 공식 문서 Limitations — https://docs.headroomlabs.ai/docs/limitations
  5. [5] 공식 문서 Security Model — https://docs.headroomlabs.ai/docs/security-model
  6. [6] GitHub README·v0.42.0 릴리스 노트 — https://github.com/headroomlabs-ai/headroom
  7. [7] 공식 문서 Limitations — https://docs.headroomlabs.ai/docs/limitations
  8. [8] 공식 문서 Limitations — https://docs.headroomlabs.ai/docs/limitations
  9. [9] 공식 문서 Troubleshooting — https://docs.headroomlabs.ai/docs/troubleshooting
  10. [10] Headroom 이슈 #600 댓글(2026년 6월 14일) — https://github.com/headroomlabs-ai/headroom/issues/600#issuecomment-4702244284
  11. [11] 공식 문서 Troubleshooting — https://docs.headroomlabs.ai/docs/troubleshooting
  12. [12] 공식 문서 Security Model — https://docs.headroomlabs.ai/docs/security-model
  13. [13] 공식 문서 Security Model — https://docs.headroomlabs.ai/docs/security-model
  14. [14] GitHub README·v0.42.0 릴리스 노트 — https://github.com/headroomlabs-ai/headroom
  15. [15] 공식 문서 Security Model — https://docs.headroomlabs.ai/docs/security-model
  16. [16] GitHub README·v0.42.0 릴리스 노트 — https://github.com/headroomlabs-ai/headroom

👇 스위밍코드 유튜브 채널

 

👇 스위밍코드 인스타그램

 

👇 스위밍코드 스레드

 

👇 스위밍코드 네이버 블로그

 

다가올 뉴스레터가 궁금하신가요?

지금 구독해서 새로운 레터를 받아보세요

✉️

이번 뉴스레터 어떠셨나요?

스위밍코드 님에게 ☕️ 커피와 ✉️ 쪽지를 보내보세요!

댓글

의견을 남겨주세요

확인
의견이 있으신가요? 제일 먼저 댓글을 달아보세요 !

다른 뉴스레터

이웃 뉴스레터 Beta

비슷한 이야기를 하는 다른 뉴스레터의 글이에요.

© 2026 스위밍코드

2019년부터 온라인 쇼핑몰을 운영하는 사장이 상세페이지·CS·재고 정리에 직접 써본 AI 활용법

메일리 로고

도움말 오류 및 기능 관련 제보

서비스 이용 문의admin@team.maily.so 채팅으로 문의하기

메일리 사업자 정보

메일리 (대표자: 이한결) | 대표번호: 070-8027-1409 | 사업자번호: 717-47-00705 | 서울특별시 송파구 위례광장로 199, 5층 501-2-31호

이용약관 | 개인정보처리방침 | 정기결제 이용약관 | 라이선스