헤드룸 프록시로 클로드코드 컨텍스트 아끼기, 지금 써도 안전한가

클코단 방에서는 헤드룸(Headroom)이라는 프록시를 쓰는지 여부에 따라 클로드코드 컨텍스트가 차는 속도 체감이 크게 갈린다는 이야기가 나왔다. 동시에 헤드룸 프록시가 HTTP 응답 프레이밍 규칙과 충돌하는 헤더를 캐싱해 본문을 읽을 수 없는 HTTP 200 응답을 돌려주는 문제도 있다. 개발자가 이를 고치는 중이라는 현황도 함께 공유됐다. 압축 프록시 하나 끼워 넣는 걸로 컨텍스트가 정말 오래 가는지, 지금 붙여 써도 안전한지를 확인해본다.

헤드룸이 컨텍스트 창에서 하는 일

헤드룸은 클로드코드나 코덱스 같은 코딩 에이전트와 모델 API 사이에 끼어드는 로컬 프록시이자 MCP 서버다. 깃허브 저장소 설명에 따르면 도구 실행 결과, 로그, RAG 청크, 파일 내용이 모델에 도달하기 전에 압축을 거친다. JSON 구조화 데이터는 SmartCrusher로, 코드는 트리시터 기반 AST 압축기인 CodeCompressor로 줄인다. 원본은 버리지 않고 CCR이라는 가역 압축 방식으로 캐시해 뒀다가 모델이 필요할 때 다시 꺼내 쓰게 하는 구조다. 클로드코드 외에도 코덱스, 그록 CLI, 커서, 에이더, 코파일럿 CLI 등 여러 코딩 도구를 같은 방식으로 감싸는 걸 목표로 하는 오픈소스 프로젝트로, 라이선스는 아파치 2.0이다.

압축률은 트래픽 성격에 따라 크게 갈린다. 프로젝트 쪽이 제시한 사례 중에는 SRE 디버깅 로그를 65,694토큰에서 5,118토큰으로 줄인 경우도 있었다. 다만 일반적인 코딩 에이전트 대화에서는 이 정도 폭은 아니고 15~20% 절감 수준이라고 안내한다. 클로드코드 CLI와 IDE 확장에서는 동작하지만 클로드 데스크톱 앱은 대상이 아니다.

컨텍스트가 오래 간다는 체감, 어디까지 맞나

방에서 나온 "헤드룸을 쓰면 컨텍스트 소모 속도가 확 달라진다"는 체감은 바깥 사용기와도 방향이 겹친다. 써본 사람들 사이에서는 같은 200K 창 안에서 세션이 30분 만에 끝나던 게 3시간 넘게 이어졌다는 반응도 있었다.

설치가 5분이면 끝나고 별다른 설정 손질이 필요 없다는 평도 나왔다.

다만 이 절감은 대화 구성에 따라 비대칭적이다. 프로젝트 문서는 도구 출력이나 로그 입력 비중이 높을 때 효과가 크다고 말한다. 짧은 잡담형 대화에서는 체감할 만한 절감이 나오지 않는다고도 못 박아 둔다. 방의 체감이 사실이라면 그 팀의 작업이 도구 호출과 로그가 많은 유형이었을 가능성이 크다. 압축기는 만능이 아니라 편식한다.

압축기가 거꾸로 컨텍스트를 깎아먹는 경우도 있다

문제는 헤드룸을 쓰려면 클로드코드의 ANTHROPIC_BASE_URL을 헤드룸 프록시 주소로 바꿔야 한다는 점이다. 이 우회로 자체가 부작용을 만든다. 깃허브 이슈에 보고된 사례로는, 클로드코드가 평소 도구 이름만 보내고 전체 스키마는 서버에서 필요할 때 불러오는 방식(디퍼드 툴/툴서치)을 쓴다. 다만 베이스 URL만 수동으로 커스텀 호스트로 바꾸면 이 기능이 빠지면서 모든 시스템·MCP 도구 정의를 한꺼번에 컨텍스트에 욱여넣어 약 2만 4700토큰이 늘어날 수 있다.

별도 1M 설정이 없으면 1M 컨텍스트 창을 쓸 수 있는 계정도 커스텀 베이스 URL 뒤에서는 관련 베타 헤더가 전송되지 않아 20만 토큰으로 제한될 수 있다. 클로드코드 v2.1.196부터는 리모트 컨트롤 기능도 api.anthropic.com이 아닌 주소에서는 비활성화된다. 압축으로 아낀 토큰을, 우회로 자체가 만드는 오버헤드가 갉아먹는 구도다. 방에서 느낀 절감 체감과 이 부작용이 동시에 사실일 수 있다는 점이 헤드룸을 평가하기 까다롭게 만드는 지점이다.

캐시가 이전 턴의 통신 프레임을 그대로 재생하는 버그

방에서 언급된 응답 문제는 헤드룸 저장소의 이슈 #3019, 수정 PR #3024로 추적되는 버그와 맞아떨어진다. 헤드룸이 스트리밍 요청을 비스트리밍으로 바꿔 상류 서버에 보낸 뒤 그 응답을 캐시에 저장하는데, 이때 상류가 붙인 transfer-encoding: chunked 같은 전송 프레이밍 헤더까지 그대로 저장해 버린다. RFC 9112 6.1절은 Transfer-Encoding이 있으면 Content-Length를 무시하도록 정하고 있다. 나중에 이 캐시를 그대로 재생하면 클라이언트가 JSON 본문을 청크 프레임으로 잘못 해석해 파싱에 실패한다.

증상은 HTTP 200이 찍히는데 본문이 비어 있거나 깨져서 클로드코드가 "빈 응답 또는 손상된 응답"이라는 오류를 내는 식이다. 프록시 쪽 로그에는 에러가 남지 않아 원인 추적이 까다롭다는 게 이슈에 적힌 특징이다. 도구 목록에 헤드룸의 검색 도구가 포함되고 메시지 수가 일정 수준을 넘는 대화에서만 재현된다는 보고도 있다. 작은 대화에서는 아예 나타나지 않는다는 점도 특이하다. 이 글을 쓰는 시점 기준 수정 PR은 다른 메인테이너 두 명의 리뷰를 기다리는 중으로, 아직 main에 병합되지 않았다.

지금 붙여 써도 되나

당장 급한 사용자에게는 헤드룸 쪽 대응이 스트리밍 요청에서 나온 응답은 캐시에 저장하지 않고 전송 프레이밍 헤더를 벗겨내는 방향으로 잡혀 있다는 점이 위안이 될 만하다. 병합 전까지는 이슈 스레드에서 제보자가 임시방편으로 제시한 --lossless 옵션을 켜서 문제가 발생하는 CCR 경로를 우회하는 정도가 현실적인 대안이다. 프록시를 완전히 끄고 원래 API로 잠깐 되돌리는 것도 방법이다.

개인 개발자나 소규모 팀이라면 판단 기준은 단순하다. 로그 분석이나 대량 도구 출력을 반복해서 모델에 밀어 넣는 작업이면 압축 효과가 청구액과 세션 길이 양쪽에서 체감될 가능성이 높다. 반대로 짧은 대화 위주라면 절감은 미미한데 별도 설정 없이 1M 컨텍스트를 잃거나 리모트 컨트롤이 비활성화되는 손실이 더 크게 다가올 수 있다. 리모트 컨트롤까지 동시에 만족시키는 설정은 없다. 지금은 어느 쪽 트래픽을 프록시에 태울지부터 정하는 게 먼저다.