클로드 코드 토큰 아끼는 헤드룸 설치법, 명령어 두 줄이면 끝
클로드 코드가 토큰을 이렇게 많이 쓰는 이유
클로드 코드는 대화가 길어질수록 매 턴 전체 대화 기록을 다시 API로 보냅니다. 파일을 읽고, 검색 결과를 받고, 툴 출력이 쌓일수록 그 전부가 다음 요청에도 그대로 딸려 갑니다. 프롬프트 캐싱이 있어도 오래된 툴 출력이나 지나간 파일 내용까지 매번 다시 계산에 들어가는 건 막지 못합니다.
헤드룸(Headroom)은 이 지점에 로컬 프록시를 하나 끼워 넣습니다. 클로드 코드와 Anthropic API 사이에서 오래된 메시지를 압축하고, 캐시를 재사용하고, 지나간 툴 출력을 정리해서 넘기는 방식입니다. 설치 자체는 pip install headroom-ai 한 줄, 클로드 코드에 붙이는 것도 명령어 한 줄이면 끝납니다.
이 글에서는 헤드룸을 설치하고 클로드 코드에 연결하는 방법, 연결이 제대로 됐는지 확인하는 법, 압축 강도를 조절하는 설정값, 그리고 원래대로 되돌리는 방법까지 실제로 실행해 본 명령어 기준으로 정리했습니다.
헤드룸(Headroom)이 하는 일, 구조부터 보면
헤드룸은 별도 API를 새로 쓰는 게 아니라, 기존에 클로드 코드가 Anthropic API로 보내던 요청 경로 중간에 자기 자신을 끼워 넣습니다. 클로드 코드의 ANTHROPIC_BASE_URL 환경변수를 로컬 주소(http://127.0.0.1:8787)로 바꾸는 방식입니다.
클로드 코드 요청은 헤드룸 프록시를 거친 뒤에야 Anthropic API에 도달합니다
요청이 프록시를 지나가는 동안 헤드룸이 하는 일은 크게 세 가지입니다.
- 오래된 툴 출력 압축 : 몇 턴 전에 읽은 파일 내용이나 검색 결과처럼, 지금 당장 필요하지 않은 부분을 줄여서 보냅니다.
- 캐시 재사용 : 이미 계산된 프롬프트 캐시를 최대한 다시 활용합니다.
- 메모리 관리 :
--memory옵션을 켜면 세션이 끝나도 남겨둘 내용을 별도로 저장합니다.
여기서 중요한 건, 압축은 원본을 버리는 게 아니라 요약해서 보내는 쪽에 가깝다는 점입니다. 뒤에서 다룰 정확도 관련 설정값이 있는 이유도 이 때문입니다.
설치, pip 한 줄
헤드룸은 PyPI에 headroom-ai라는 이름으로 올라와 있습니다.
pip install headroom-ai
headroom --version
버전이 출력되면 설치는 끝난 겁니다. 이 글을 쓰는 시점 기준 최신 버전은 0.36.3입니다.
클로드 코드에 붙이는 두 가지 방법 : wrap과 init
헤드룸을 클로드 코드에 연결하는 방법은 두 가지고, 둘은 지속되는 범위가 다릅니다.
| 구분 | headroom wrap claude |
headroom init --global claude |
|---|---|---|
| 적용 범위 | 그 명령으로 띄운 세션 한 번 | 이후 실행하는 claude 전부 |
| 프록시 실행 | 명령 실행 시 자동으로 기동 | 훅으로 등록, 별도 기동 필요 |
| 되돌리기 | 세션 종료 시 자연히 끝남 | headroom unwrap claude 필요 |
| 적합한 경우 | 일단 한번 테스트해볼 때 | 계속 켜두고 쓸 때 |
한 번만 테스트해보고 싶다면 이렇게 실행합니다. 이 명령 하나로 프록시가 뜨고, 환경변수가 설정되고, 클로드 코드가 그 상태로 실행됩니다.
headroom wrap claude
세션 중에 지속적인 메모리 기능까지 쓰고 싶다면 --memory 옵션을 붙입니다.
headroom wrap claude --memory
매번 이렇게 실행하기 귀찮다면, 사용자 계정 전체에 영구 등록합니다. --global 플래그는 init 뒤, claude 서브커맨드 앞에 옵니다.
headroom init --global claude
이 명령은 클로드 코드 설정에 훅과 라우팅 정보를 심어 두는 방식이라, 이후에는 그냥 claude라고만 쳐도 헤드룸을 거칩니다. 다만 프록시 자체는 별도로 떠 있어야 하므로, 상시로 쓸 계획이면 뒤에서 다룰 headroom install apply까지 같이 설정하는 게 낫습니다.
제대로 붙었는지 확인, headroom doctor
연결이 실제로 됐는지는 감으로 판단하지 말고 headroom doctor로 확인합니다.
headroom doctor
이 명령은 표 형태로 여러 항목을 점검해 각각 통과, 경고, 실패 상태를 보여줍니다. 눈여겨볼 항목은 이렇습니다.
- proxy :
127.0.0.1:8787에 프록시가 실제로 응답하는지. 실패면 아직wrap이나install apply로 프록시를 띄우지 않은 상태입니다. - claude : 클로드 코드 설정에
ANTHROPIC_BASE_URL라우팅이 등록됐는지. - wrap_marker :
wrap또는init으로 남긴 등록 흔적이 있는지. - shell env : 지금 이 셸에서
ANTHROPIC_BASE_URL이 실제로 잡혀 있는지. 훅으로 등록만 해두고 새 셸을 안 열면 이 항목이 경고로 뜹니다.
네 항목이 전부 통과로 나와야 클로드 코드가 실제로 헤드룸을 거쳐 요청을 보내고 있다는 뜻입니다. 하나라도 실패나 경고면, 그 요청은 압축 없이 그냥 Anthropic API로 직행하고 있는 겁니다.
압축 강도 조절하기
헤드룸이 얼마나 세게 압축할지는 환경변수로 조절합니다. 어떤 값들이 있는지는 아래 명령으로 한 번에 볼 수 있습니다.
headroom agent-savings
기본 제공되는 agent-90 프로파일을 기준으로, 실제로 손대볼 만한 값은 이 정도입니다.
HEADROOM_SAVINGS_TARGET: 목표 절감 비율. 기본값이 0.9면 최대한 압축하겠다는 뜻입니다.HEADROOM_PROTECT_RECENT: 최근 몇 개 메시지는 압축 대상에서 아예 제외할지.HEADROOM_MIN_TOKENS: 이보다 작은 메시지는 압축해도 이득이 없으니 건드리지 않는 기준값.HEADROOM_ACCURACY_GUARD:strict로 두면 압축 과정에서 정확도가 떨어질 소지가 있는 케이스를 더 보수적으로 걸러냅니다.
목표 절감 비율을 올릴수록 압축은 세지지만, 그만큼 모델이 받는 맥락에서 빠지는 정보도 늘어납니다. 처음에는 기본 프로파일 그대로 쓰다가, 결과물 품질에 문제가 없는지 보면서 값을 조정하는 순서를 권합니다.
API 없이 구독제로 쓴다면, MCP 연동
API 키 없이 클로드 코드 구독으로만 쓰는 경우에는 프록시로 전체 트래픽을 압축하는 대신, MCP 서버를 통해 필요할 때만 압축된 내용을 불러오는 방식도 있습니다.
headroom mcp install
이 명령은 감지되는 코딩 에이전트(기본은 클로드 코드)에 headroom_retrieve 도구를 등록합니다. 클로드 코드가 필요할 때 이 도구를 호출해서 압축된 내용을 다시 가져오는, 문서에서 CCR(Compress-Cache-Retrieve)이라고 부르는 방식입니다. 등록을 해제할 때는 반대로 실행합니다.
headroom mcp uninstall
상시로 켜두고 싶다면
세션마다 wrap을 치는 대신 프록시를 백그라운드 서비스로 계속 띄워두고 싶다면 install apply를 씁니다.
headroom install apply
기본값은 persistent-service 프리셋에 --scope user, --providers auto로, 이 시스템에서 감지되는 도구에 자동으로 라우팅을 걸어줍니다. 상태 확인과 중지는 각각 이렇게 합니다.
headroom install status
headroom install stop
알아둬야 할 한계
- 손실 압축이라는 점 : 헤드룸이 하는 압축은 오래된 내용을 요약해서 줄이는 방식이라, 아주 드물게 나중에 다시 필요해진 세부 내용이 요약 과정에서 빠질 수 있습니다.
ACCURACY_GUARD가 있는 이유도 이 리스크를 관리하기 위해서입니다. - 프록시가 꺼져 있으면 압축 효과가 전혀 없다는 점 :
wrap없이 그냥claude를 실행하거나,init으로 등록만 해두고 프록시를 안 띄웠다면 압축은 일어나지 않습니다.headroom doctor로 주기적으로 확인하는 게 좋습니다. - 클로드 코드 전용 도구가 아니라는 점 :
headroom wrap은 코덱스, 코파일럿, 에이더, 커서, 구스 등 열아홉 종에 가까운 도구를 지원합니다. 여러 CLI 도구를 같이 쓴다면 각각 붙일 수 있습니다.
원래대로 되돌리기
init으로 영구 등록했던 걸 되돌리려면 이렇게 실행합니다.
headroom unwrap claude
이 명령은 기본적으로 프록시도 같이 중지하고 MCP 등록도 제거합니다. 프록시는 계속 띄워두고 클로드 코드 라우팅만 해제하고 싶다면 --no-stop-proxy를, MCP 등록은 남기고 싶다면 --keep-mcp를 붙입니다.
headroom unwrap claude --no-stop-proxy --keep-mcp
설치와 설정은 여기까지입니다. 실제로 얼마나 절감되는지는 환경마다, 대화 패턴마다 다르므로 직접 headroom doctor와 headroom savings로 본인 환경 수치를 확인해보는 걸 권합니다. 더 자세한 옵션은 공식 문서와 깃허브 저장소에 정리돼 있습니다.
Leave a comment