🦞 15. OpenClaw 캐싱 완전 가이드

이 문서는 슬래시페이지 원문 **「OpenClaw 캐싱 완전 가이드」**를 기준으로, 핵심 주장과 설정값·운영 팁을 누락 없이 실무형으로 재정리한 버전이다.
핵심 메시지: OpenClaw는 반복되는 시스템 컨텍스트 비중이 큰 구조라, 캐싱 전략이 곧 비용 전략이다.

0) 전체 구조 한 장 요약

mindmap
  root((OpenClaw 캐싱 운영))
    왜 중요한가
      시스템 프롬프트 반복
      히스토리 누적
      heartbeat cron 대화 반복 호출
    핵심 설정
      cacheRetention long
      contextPruning cache-ttl
      heartbeat TTL 직전 호출
    절감 메커니즘
      첫 구간 cacheWrite
      반복 구간 cacheRead
      TTL 이후 첫 요청 재캐시 비용 완화
    운영 전략
      cron isolated 분리
      지시 파일 경량화
      모델 역할 분리
      컨텍스트 상한 관리

1) 캐싱이란 무엇인가

1-1. 기본 개념

• Claude API는 요청할 때마다 전체 컨텍스트를 다시 읽는다.
• Prompt Caching은 반복되는 블록을 저장하고 재사용한다.

원문 예시:

• 캐싱 없음: [System 10k] + [History 60k] + [새 메시지] = 70k 토큰 과금
• 캐싱 있음: [cacheRead 69k] + [새 메시지 1k] 중심 과금

1-2. 토큰 요금 비교(원문 제시값, Sonnet 4.5 기준)

종류	요금 (per 1M tokens)	비율
일반 Input	$3.00	100%
Cache Write	$3.75	125%
Cache Read	$0.30	10%
Output	$15.00	500%

요지:

• Write는 비싸지만 상대적으로 드물고,
• Read는 매우 저렴해 반복 요청에서 절감 효과가 커진다.

2) OpenClaw에서 캐싱이 특히 중요한 이유

2-1. 매 요청마다 큰 시스템 컨텍스트가 포함됨

원문에서 강조한 OpenClaw 포함 요소:

• SOUL.md, USER.md, AGENTS.md, MEMORY.md, HEARTBEAT.md, IDENTITY.md
• 도구/스킬 목록

공식 docs 관점으로 보면:

• OpenClaw는 매 호출에 시스템 프롬프트를 재조립한다.
• 워크스페이스 핵심 파일 + 런타임 메타 + 도구/스킬 메타가 포함된다.

2-2. 캐싱이 없으면 반복 비용이 그대로 누적됨

원문 시나리오:

• 아침 cron, heartbeat, 일반 대화가 반복될 때
• 같은 시스템 블록 과금이 계속 발생

2-3. 정적(static) 블록은 캐싱 효율이 높음

원문 포인트:

• 자주 바뀌지 않는 파일이 캐시 히트에 유리
• 반복 구조가 유지될수록 Read 비중이 커짐
• (원문 언급) Anthropic 캐싱은 큰 블록 반복 시 효과가 크며, 최소 토큰 조건을 만족해야 함

3) 실제 비용 데이터(원문 사례)

3-1. 호출별 패턴(원문 표 재구성)

호출	cacheRead	cacheWrite	실제 비용	캐싱 없었다면(원문)
1	8,590	11,772	$0.047	~$0.094
2	8,590	12,045	$0.049	~$0.094
3	20,635	6,395	$0.036	~$0.162
4	27,468	266	$0.011	~$0.207
5	27,734	838	$0.013	~$0.210
16	69,836	455	$0.025	~$0.527
17	70,291	1,126	$0.032	~$0.531

3-2. 원문 핵심 인사이트

• cacheRead 69,836 규모 호출은 일반 input 대비 큰 절감 구간
• 대화가 길어질수록 절감률이 상승
  • 초반: 약 50%
  • 중반: 약 70%
  • 후반: 약 87%

flowchart LR
A[초기: cacheWrite 비중 큼] --> B[중반: cacheRead 증가]
B --> C[후반: cacheRead 우세]
C --> D[반복 호출 구간에서 절감 극대화]

4) 캐싱 설정 방법 (원문 + OpenClaw 문법 정리)

4-1. cacheRetention 설정 (핵심)

{
  "agents": {
    "defaults": {
      "models": {
        "anthropic/claude-sonnet-4-5-20250929": {
          "params": { "cacheRetention": "long" }
        },
        "anthropic/claude-haiku-4-5": {
          "alias": "haiku",
          "params": { "cacheRetention": "long" }
        }
      }
    }
  }
}

• none: 캐싱 끔
• short: 5분
• long: 1시간

공식 docs 보강:

• Anthropic API key 인증의 기본값은 short
• 명시 설정으로 long 오버라이드 가능
• 구버전 cacheControlTtl도 호환(5m↔short, 1h↔long)

4-2. 캐시 트레이스 진단(선택)

{
  "diagnostics": {
    "cacheTrace": {
      "enabled": true,
      "includeSystem": true,
      "includeMessages": false,
      "includePrompt": false
    }
  }
}

원문 로그 예시 경로:

• <OPENCLAW_HOME>/logs/cache-trace.jsonl

4-3. contextPruning 연계

{
  "agents": {
    "defaults": {
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "1h"
      }
    }
  }
}

원문 설명:

• 캐시 만료 타이밍과 맞춰 오래된 히스토리/도구결과를 정리해
• TTL 지난 뒤 첫 요청의 재캐시 비용을 완화

공식 docs 보강:

• pruning은 온디스크 이력 삭제가 아니라 요청 직전 인메모리 컨텍스트 정리
• Anthropic 계열 호출에서 TTL 기반으로 동작

4-4. 설정 적용

• 설정 파일 반영 후 재시작
• openclaw gateway restart
• 또는 에이전트에게 config.patch 요청

5) 1시간 캐싱 vs 5분 캐싱 비교

5-1. 원문 시나리오(10k system prompt, 하루 50회 호출)

• 캐싱 없음: 약 $1.50/일 → 월 $45
• 5분 캐싱(short): 월 $20 수준(원문 추정)
• 1시간 캐싱(long): 월 $5 수준(원문 추정)

5-2. 원문 핵심 팁: heartbeat를 TTL보다 살짝 짧게

원문은 59m 전략을 제안한다.

{
  "heartbeat": {
    "every": "59m"
  }
}

논리:

• TTL 60분 전에 호출이 들어오면 캐시 유지/갱신에 유리

공식 docs 보강:

• token-use 문서에서는 55m 예시도 제시
• 실무에선 네트워크 지연/실행 편차를 고려해 55~59분 범위에서 운영

5-3. 원문의 OpenClaw 패턴 비교 요지

• heartbeat/cron/자리비움 후 복귀처럼 간헐적 호출이 많은 환경에서
• 긴 TTL 캐싱의 체감 효과가 커진다.

6) 비용을 줄이는 전략 (원문 5가지, 누락 없이)

Strategy 1. 페르소나/정적 블록 최적화

원문 DO:

• 정적 규칙 블록을 앞부분에 두고, 자주 안 바꾸기
• 동적 데이터(시간/실시간 상태)는 뒤쪽으로 분리

원문 DON’T:

• 요청마다 큰 메모리 블록을 재작성해 캐시 무효화
• 프롬프트 앞부분에 자주 바뀌는 값 삽입

Strategy 2. Cron 세션 분리 (isolated)

{
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "CRON.md의 '아침 인사' 섹션을 따라 실행"
  }
}

효과:

• Main 세션 누적 이력과 분리되어 초기 컨텍스트가 가벼워짐

Strategy 3. CRON 지시 파일 분리/소형화

원문 비교:

• Bad: 큰 워크플로우 파일 통째로 읽기
• Good: 짧은 CRON.md의 필요한 섹션만 읽기

Strategy 4. 컨텍스트 상한 관리

원문 포인트:

• 컨텍스트가 과도하게 커지면
  • cacheWrite 비용 급증
  • 토큰 한도 위험
  • 캐시 효율 저하
• 따라서 세션 분기/컴팩션/정리 루틴이 필요

Strategy 5. 모델 선택 최적화

원문 취지:

• 반복 루틴(heartbeat/cron 요약)은 저비용 모델
• 복잡 분석/코딩은 고성능 모델

7) 캐싱 작동 여부 확인법

7-1. 세션 JSONL에서 usage 확인

원문 기준 판단:

• cacheRead > 0 → 히트
• cacheRead = 0 → 미스
• cacheWrite 급증 → 새 캐시 작성/갱신 구간

7-2. 원문 grep 예시(의도 유지)

grep "cacheRead\|cacheWrite" <session>.jsonl | python3 -c "
import sys, json
for line in sys.stdin:
    d = json.loads(line)
    if d.get('type') == 'message':
        u = d['message'].get('usage', {})
        if u.get('cacheRead', 0) > 0:
            print(f\"히트: {u['cacheRead']:,} tok read, {u['cacheWrite']:,} tok write\")
"

7-3. 원문 빠른 절감 추정 예시(의도)

• cacheRead 총량에 단가 차이를 곱해 대략 절감액 추정

8) 원문 요약 체크리스트 (그대로 반영)

• cacheRetention: "long" 설정
• contextPruning.mode: "cache-ttl" + ttl 정합성
• cron job은 isolated 우선
• cron 지시 파일은 짧게 유지
• 컨텍스트 과대화 방지
• 단순 반복 작업은 경량 모델 사용
• diagnostics.cacheTrace 또는 usage 로그로 모니터링

9) 운영 시 주의(검증 보강)

• 비용 숫자는 모델 가격표/인증 방식/API 정책에 따라 달라진다.
• long 캐싱은 Anthropic API 경로에서 유효하며, 인증 방식별 기본값 차이가 있다.
• pruning은 “기록 삭제”가 아니라 “요청 직전 전송 컨텍스트 정리”다.

AI 활용 고지

이 문서는 외부 공개 글(슬래시페이지)을 기반으로 생성형 AI가 초안을 재구성했고, OpenClaw 공식 문서 기준으로 항목/표현을 교정해 정리했다.

📚 다음 읽기

• 🦞 07. Quota — 사용량 한도 관리
• 🦞 31. Quota 리셋 안됨 해결 — 할당량 리셋 트러블슈팅
• 🦞 20. 운영아키텍처 규칙총정리 — 전체 운영 기준