프롬프트 캐싱

프롬프트 캐싱은 모델 프로바이더가 변경되지 않은 프롬프트 접두사(보통 시스템/개발자 지시사항 및 기타 안정적인 컨텍스트)를 매번 재처리하는 대신 턴 간에 재사용할 수 있음을 의미합니다. 첫 번째 매칭 요청이 캐시 토큰을 기록하고(cacheWrite), 이후 매칭 요청이 이를 읽어옵니다(cacheRead).

이것이 중요한 이유: 더 낮은 토큰 비용, 더 빠른 응답, 장기 실행 세션에서 더 예측 가능한 성능. 캐싱 없이는 반복되는 프롬프트가 대부분의 입력이 변경되지 않았더라도 매 턴마다 전체 프롬프트 비용을 지불합니다.

주요 설정

`cacheRetention` (모델 및 에이전트별)

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "short" # none | short | long

`contextPruning.mode: "cache-ttl"`

캐시 TTL 창 이후 오래된 도구 결과 컨텍스트를 정리합니다.

하트비트 캐시 워밍

하트비트가 캐시 창을 따뜻하게 유지하여 유휴 갭 후 반복적인 캐시 쓰기를 줄일 수 있습니다.

프로바이더 동작

Anthropic (직접 API): cacheRetention 지원. Anthropic API 키 인증 프로필에서 미설정 시 cacheRetention: "short" 시드.
Amazon Bedrock: Anthropic Claude 모델 ref에 대한 명시적 cacheRetention 전달 지원. 비 Anthropic 모델은 cacheRetention: "none"으로 강제.
OpenRouter Anthropic 모델: 프롬프트 캐시 재사용 개선을 위해 시스템/개발자 프롬프트 블록에 Anthropic cache_control 주입.
기타 프로바이더: 캐시 모드를 지원하지 않으면 cacheRetention은 효과 없음.

캐시 진단

OpenClaw은 내장 에이전트 실행을 위한 전용 캐시 추적 진단을 노출합니다.