← 목록으로

Claude Code는 각 에이전트의 대화 기록을 약 30초마다 해당 모델에 전송함

요약
  • Claude Code는 에이전트 패널의 상태 요약을 위해 약 30초마다 대화 기록을 모델에 전송하며, 이 과정에서 전체 토큰의 15~20%를 소모하는 것으로 분석되었습니다.
  • 이를 해결하기 위해 바이너리 수정 없이 요약용 타이머를 차단하는 Bun 사전 로드 스크립트가 제공됩니다.
  • 클로드 코드가 에이전트 패널의 3~5단어 상태 요약을 생성하는 호출에 전체 토큰의 약 15~20%를 소모한다는 분석. 끄기 위해서는 요약용 타이머를 차단해야함
  • 백그라운드 에이전트의 전체 대화 기록을 해당 에이전트 모델에 약 30초마다 전송하며, 결과는 작업을 진행하는 대화에는 들어가지 않고 패널 상태 줄만 갱신함
  • 호출의 약 98%가 프롬프트 캐시를 활용해도 비용이 누적되며, 디스크의 세션 로그에는 기록되지 않아 로그 기반 비용 도구로는 확인하기 어려움
  • 요약만 끄는 사용자 설정이 없어, 바이너리를 수정하지 않고 요약용 타이머를 차단하는 Bun 사전 로드 스크립트를 제공함. 테스트에서는 에이전트 실행을 유지하면서 요약 호출이 사라짐
  • 적용하면 패널의 상태 요약 갱신이 중단되며, 내부 소스 문자열에 의존하므로 Claude Code 업데이트 후 재검증이 필요함
짧은 상태 요약에 반복되는 모델 호출
  • Claude Code는 백그라운드 에이전트의 전체 대화 기록을 해당 에이전트가 사용하는 모델, 보통 Opus에 보내 “가장 최근 행동을 3~5단어로 설명하라” 고 요청함
  • 응답은 에이전트 패널의 상태 줄에만 표시되며, 작업을 진행하는 대화나 모델의 문맥에 추가되지 않음
  • 대화형 백그라운드 에이전트에서는 2.1.232, 2026년 8월 13일부터 기본 활성화됨
  • 기본 호출 간격은 약 30초이며, 모델 계열별 서버 설정으로 30~240초 범위에서 조절됨
  • claude -p 같은 헤드리스 실행에서는 기본적으로 요약 타이머가 활성화되지 않음. 포크 서브에이전트와 포크된 스킬은 별도 경로로 요약될 수 있음
측정된 비용과 사용량
  • Flamerix AI는 OpenTelemetry의 claude_code.api_request 이벤트를 query_source별로 분석해 agent_summary 호출을 확인함
  • 차단 적용 전 일주일간 측정 결과는 다음과 같음
    • 전체 추정 비용의 16.4% 로, 주 대화의 15.7%보다 높았음
    • 전체 API 요청의 19.7% 를 차지함
    • 요약 호출 비용의 96%가 Opus에서 발생함
    • 출력 토큰 1개당 입력 토큰은 약 9,000개였음
  • 원문 제목은 이를 ‘토큰의 약 15~20%’로 표현하지만, 위 비용 수치는 실제 청구서가 아닌 Claude Code의 요청별 cost_usd 추정치임
  • 구독 이용자에게는 추가 청구보다는 사용량 한도의 소모로 나타남
  • 관련 이슈 #86879에도 18~26%를 기록한 독립 측정 4건이 모여 있음
캐시와 비용 도구만으로 해결되지 않는 이유
  • 호출의 약 98%는 프롬프트 캐시에서 대화 기록을 다시 읽지만, 반복 호출에 따른 비용은 남음
  • 캐시에 적중하지 않은 약 2%의 호출이 이 기능 비용의 3분의 1 이상을 차지함
  • 이 요청들은 디스크의 세션 로그에 기록되지 않아, 대화 기록을 읽는 비용 도구에서는 보이지 않음
  • 요청 출처와 비용을 확인하려면 OpenTelemetry 내보내기 데이터를 분석해야 함
요약용 타이머만 차단하는 방법
  • 제공되는 no-agent-summary.js는 Bun 사전 로드 스크립트로, Claude Code 바이너리를 수정하지 않음
  • 현재 v3는 전역 setTimeout을 감싸고, 콜백 소스에 [AgentSummary] Timer fired 같은 식별 문자열이 있으면 해당 타이머를 비활성화함
  • 나머지 타이머는 그대로 실행하며, Claude Code 프로세스에서만 훅이 설치되도록 실행 환경을 확인함
  • BUN_OPTIONS에 --preload=/절대/경로/no-agent-summary.js 를 지정해 적용함
    • --preload와 경로 사이를 공백으로 구분하면 다른 Bun 명령이 깨질 수 있어 = 형식을 사용해야 함
    • 기존 데몬과 세션은 이전 환경을 유지하므로 claude daemon stop --any 실행 후 세션도 재시작해야 함
  • CC_AGENT_SUMMARY_MODE=off는 요약 타이머를 차단하고, pass는 훅을 로드하되 차단하지 않아 비교 검증에 사용할 수 있음
효과와 검증 범위
  • Flamerix AI의 환경에서는 적용 후 이틀간 agent_summary의 비용과 요청 비중이 모두 0% 였으며, 다른 부수 요청이 대신 증가하지 않았음
  • 서브에이전트, 백그라운드 에이전트, 포크된 스킬과 세션은 정상 실행되고 상태 요약 갱신만 중단됨
  • SDK의 task_progress 이벤트에서도 summary가 빠짐
  • Linux의 여러 버전에서 차단 효과를 검증했으며, 현재 v3도 2.1.301과 2.1.312에서 재검증함
  • macOS에서는 다른 사용자의 작동 보고가 추가됐으며, 댓글에는 Windows용 실행 환경 확인 조건을 수정한 뒤 성공했다는 보고도 있음
끄기 설정과 업데이트 시 주의점
  • SDK의 agentProgressSummaries와 환경 변수 CLAUDE_CODE_AGENT_PROGRESS_SUMMARIES는 요약을 활성화할 수만 있고, 이미 활성화된 요약을 끄지는 못함
  • 일부 우회 설정은 요약뿐 아니라 백그라운드 에이전트나 포크 기능까지 함께 중단함
  • 2.1.310에는 전체 대화 대신 약 2,000토큰의 메모를 사용하는 저렴한 short 모드가 추가됐지만, 원문 분석 시점에는 기본 비활성 상태이며 서버 플래그로 제어됨
  • 차단 스크립트는 내부 소스 문자열에 의존하므로, 업데이트로 구현이 바뀌면 경고 없이 요약 호출이 재개될 수 있음
  • 업데이트 후에는 차단 로그와 함께 OpenTelemetry의 query_source = agent_summary가 0으로 유지되는지 확인해야 함
그냥 목록으로
원문 보기 ↗