ENABLE_PROMPT_CACHING_1H 환경변수로 캐시 TTL 1시간으로 늘리기

긴 컨텍스트를 자주 넘기는 세션이라면 이 설정이 꽤 체감돼요. 기본 캐시 TTL이 5분이라 조금만 작업이 늘어지면 캐시가 만료되고, 같은 프롬프트를 다시 토큰으로 태워야 해요. Claude Code v2.1.108에서 ENABLE_PROMPT_CACHING_1H 환경변수가 추가됐고, 이걸 켜면 TTL이 1시간으로 늘어나요. API 키 환경은 물론 Bedrock, Vertex에서도 동작해요.

준비물

• Claude Code v2.1.108 이상
• API 키 / Bedrock / Vertex 중 하나의 환경
• 터미널 접근 가능

스텝

1. 환경변수 설정

현재 셸 세션에 바로 적용하려면 이렇게 해요. 이 변수가 없으면 Claude Code는 기본 5분 TTL로 동작해요.

export ENABLE_PROMPT_CACHING_1H=1

세션이 끊겨도 유지하고 싶다면 셸 설정 파일에 넣어두는 게 편해요.

# ~/.zshrc 또는 ~/.bashrc 에 추가
export ENABLE_PROMPT_CACHING_1H=1

변경 후엔 셸을 다시 불러와요.

source ~/.zshrc

2. Claude Code 실행

환경변수가 잡힌 상태에서 Claude Code를 시작하면 돼요. 별도 플래그는 필요 없어요.

claude

Bedrock을 쓴다면 기존에 ENABLE_PROMPT_CACHING_1H_BEDROCK을 쓰던 분도 있을 텐데, 이 변수는 deprecated 처리됐어요. 아직 동작은 하지만 새로 설정할 땐 통합된 변수 하나로 쓰는 게 맞아요.

확인 방법

환경변수가 제대로 잡혔는지 확인하는 건 간단해요.

echo $ENABLE_PROMPT_CACHING_1H
# 출력: 1

실제 캐시 히트 여부는 API 응답의 cache_read_input_tokens 필드로 확인할 수 있어요. Claude Code 내부에서 직접 수치를 보기는 어렵지만, 긴 세션에서 같은 컨텍스트를 반복 전송할 때 비용 대시보드 숫자가 달라지는 걸 볼 수 있어요.

응용

반대로 테스트 목적으로 5분 TTL을 강제하고 싶다면 FORCE_PROMPT_CACHING_5M을 쓸 수 있어요. 캐시 만료 시나리오를 재현할 때 유용해요.

export FORCE_PROMPT_CACHING_5M=1

두 변수를 동시에 설정하면 어떻게 되는지는 시도 안 해봤는데, 굳이 같이 쓸 이유는 없어요.

트러블슈팅

환경변수를 설정했는데도 비용이 줄지 않는 것 같다면, Claude Code를 실행한 터미널에서 echo $ENABLE_PROMPT_CACHING_1H로 변수가 실제로 잡혀 있는지 확인해요. IDE 플러그인이나 별도 프로세스로 Claude Code를 띄우는 경우엔 해당 프로세스의 환경에 변수가 전달되지 않을 수 있어요. 그럴 땐 .env 파일이나 실행 스크립트에 직접 넣는 게 확실해요.

이 설정 하나로 긴 페어 프로그래밍 세션에서 같은 컨텍스트를 반복 전송하는 비용을 꽤 아낄 수 있게 돼요.