OpenClaw 프롬프트 캐싱 설정: 비용 절감 및 응답 속도 최적화

긴 프롬프트를 매번 다시 보내느라 비용과 시간이 낭비되는 경험, 다들 한 번쯤 있으시죠? 특히 대화가 길어질수록 시스템 프롬프트나 고정된 컨텍스트를 계속 다시 처리하는 건 꽤 비효율적이에요. 이런 문제를 해결하기 위해 Prompt caching을 활용해 보세요.

Prompt caching은 모델 프로바이더가 변하지 않는 프롬프트 접두사(주로 시스템/개발자 지침이나 고정된 컨텍스트)를 매번 다시 처리하는 대신 재사용하는 기능이에요. 첫 번째 일치하는 요청이 캐시 토큰을 기록하고(cacheWrite), 이후의 요청은 이를 읽어와서 사용해요(cacheRead).

이 기능이 중요한 이유는 분명해요. 토큰 비용을 줄이고, 응답 속도를 높이며, 긴 세션에서도 일관된 성능을 유지할 수 있거든요. 캐싱이 없다면 입력 내용이 거의 바뀌지 않아도 매번 전체 프롬프트 비용을 지불해야 해요.

이 페이지에서는 프롬프트 재사용과 토큰 비용에 영향을 주는 모든 캐시 관련 설정들을 알아볼게요.

Anthropic의 상세 가격 정책은 다음 링크를 참고하세요: https://docs.anthropic.com/docs/build-with-claude/prompt-caching

주요 설정 항목

`cacheRetention` (전역 기본값, 모델 및 에이전트별 설정)

모든 모델에 적용할 전역 기본 캐시 유지 기간을 설정할 수 있어요:

agents:
  defaults:
    params:
      cacheRetention: "long" # none | short | long

모델별로 설정을 덮어쓸 수도 있어요:

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

에이전트별 개별 설정도 가능해요:

agents:
  list:
    - id: "alerts"
      params:
        cacheRetention: "none"

설정 병합 순서는 다음과 같아요:

agents.defaults.params (전역 기본값 — 모든 모델에 적용)
agents.defaults.models["provider/model"].params (모델별 덮어쓰기)
agents.list[].params (일치하는 에이전트 ID; 키 단위로 덮어쓰기)

레거시 `cacheControlTtl`

이전 버전의 값들도 여전히 허용되며 다음과 같이 매핑돼요:

5m -> short
1h -> long

새로운 설정을 작성할 때는 cacheRetention을 사용하는 것을 추천해요.

`contextPruning.mode: "cache-ttl"`

캐시 TTL 창이 지나면 오래된 tool-result 컨텍스트를 정리해요. 덕분에 유휴 시간 이후의 요청이 너무 큰 히스토리를 다시 캐싱하는 것을 방지할 수 있어요.

agents:
  defaults:
    contextPruning:
      mode: "cache-ttl"
      ttl: "1h"

전체 동작 방식은 Session Pruning 문서를 확인해 보세요.

Heartbeat keep-warm

Heartbeat 기능을 사용하면 캐시 창을 활성 상태로 유지해서 유휴 시간 이후에 캐시를 다시 기록하는 일을 줄일 수 있어요.

agents:
  defaults:
    heartbeat:
      every: "55m"

에이전트별 heartbeat 설정은 agents.list[].heartbeat에서 지원해요.

프로바이더별 동작

Anthropic (직접 API 연결)

cacheRetention을 지원해요.
Anthropic API 키 인증 프로필을 사용할 때, 설정값이 없으면 OpenClaw가 Anthropic 모델 참조에 cacheRetention: "short"를 자동으로 할당해요.

Amazon Bedrock

Anthropic Claude 모델 참조(amazon-bedrock/*anthropic.claude*)는 명시적인 cacheRetention 전달을 지원해요.
Anthropic이 아닌 Bedrock 모델들은 실행 시점에 강제로 cacheRetention: "none"으로 설정돼요.

OpenRouter Anthropic 모델

openrouter/anthropic/* 모델 참조의 경우, OpenClaw가 시스템/개발자 프롬프트 블록에 Anthropic의 cache_control을 주입해서 프롬프트 캐시 재사용률을 높여줘요.

기타 프로바이더

프로바이더가 이 캐시 모드를 지원하지 않는다면 cacheRetention 설정은 아무런 효과가 없어요.

튜닝 패턴

혼합 트래픽 (추천 기본 설정)

메인 에이전트에는 긴 유지 기간을 적용하고, 알림용 에이전트처럼 일시적인 경우에는 캐싱을 비활성화하는 방식이에요:

agents:
  defaults:
    model:
      primary: "anthropic/claude-opus-4-6"
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "long"
  list:
    - id: "research"
      default: true
      heartbeat:
        every: "55m"
    - id: "alerts"
      params:
        cacheRetention: "none"

비용 우선 기준 설정

기본 cacheRetention을 "short"로 설정하세요.
contextPruning.mode: "cache-ttl"을 활성화하세요.
캐시 유지가 꼭 필요한 에이전트에만 TTL보다 짧은 간격으로 heartbeat를 설정하세요.

캐시 진단

OpenClaw는 임베디드 에이전트 실행을 위한 전용 캐시 추적(cache-trace) 진단 기능을 제공해요.

`diagnostics.cacheTrace` 설정

diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl" # optional
    includeMessages: false # default true
    includePrompt: false # default true
    includeSystem: false # default true

기본값:

filePath: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl
includeMessages: true
includePrompt: true
includeSystem: true

환경 변수 토글 (일회성 디버깅)

OPENCLAW_CACHE_TRACE=1: 캐시 추적을 활성화해요.
OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl: 출력 경로를 변경해요.
OPENCLAW_CACHE_TRACE_MESSAGES=0|1: 전체 메시지 페이로드 캡처 여부를 설정해요.
OPENCLAW_CACHE_TRACE_PROMPT=0|1: 프롬프트 텍스트 캡처 여부를 설정해요.
OPENCLAW_CACHE_TRACE_SYSTEM=0|1: 시스템 프롬프트 캡처 여부를 설정해요.

점검 항목

캐시 추적 이벤트는 JSONL 형식이며 session:loaded, prompt:before, stream:context, session:after와 같은 단계별 스냅샷을 포함해요.
턴당 캐시 토큰 영향도는 /usage full이나 세션 사용량 요약의 cacheRead, cacheWrite 항목을 통해 확인할 수 있어요.

빠른 문제 해결

대부분의 턴에서 cacheWrite가 높게 나온다면: 시스템 프롬프트에 매번 변하는 입력값이 있는지 확인하고, 모델/프로바이더가 현재 캐시 설정을 지원하는지 체크해 보세요.
cacheRetention 효과가 없다면: 모델 키가 agents.defaults.models["provider/model"] 형식과 일치하는지 확인하세요.
Bedrock Nova/Mistral 요청에 캐시를 설정한 경우: 실행 시점에 none으로 강제 설정되는 것이 정상이에요.

다음 단계

AI Setup Assistant

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.