OpenClaw 캐싱 완전 가이드

Claude API 비용을 최대 90% 줄이는 방법 — 설정부터 전략까지

1. 캐싱이란 무엇인가

기본 개념

Claude API는 매 요청마다 전체 대화 맥락(context)을 처음부터 읽는다. 대화가 길어질수록, 시스템 프롬프트가 클수록 매번 같은 내용을 반복해서 처리하게 된다.

Prompt Caching은 Anthropic이 제공하는 기능으로, 자주 반복되는 부분을 서버 메모리에 저장해두고 다음 요청 때 재활용하는 방식이다.

캐싱 없음:  [System 10k] + [History 60k] + [새 메시지] = 70k 토큰 과금
캐싱 있음:  [캐시 히트 69k] + [새 메시지 1k] = 1k 토큰 과금 (나머지는 캐시 요금)

토큰 요금 비교 (Claude 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)는 90% 저렴하다.

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

2-1. OpenClaw는 매 메시지마다 거대한 System Prompt를 보낸다

OpenClaw는 AI 어시스턴트가 일관된 페르소나와 컨텍스트를 유지하도록, 매 API 요청에 아래 파일들을 통째로 System Prompt에 포함한다:

SOUL.md        — 페르소나/성격 정의
USER.md        — 사용자 프로필 (이름, 직책, 배경)
AGENTS.md      — 행동 규칙 및 지침
MEMORY.md      — 장기 기억 (학습한 것들)
HEARTBEAT.md   — 주기적 체크리스트
IDENTITY.md    — 어시스턴트 정체성
도구 목록      — 사용 가능한 skill 목록

이 파일들의 총 크기는 보통 8,000~15,000 토큰이다. 대화가 쌓이면 히스토리까지 합쳐 70,000 토큰이 훌쩍 넘는다.

2-2. 캐싱 없으면 매 메시지마다 이 비용이 반복된다

아침 인사 cron      → System Prompt 10k 토큰
10분 후 heartbeat  → 또 10k 토큰
20분 후 대화       → 또 10k 토큰 (히스토리 포함 50k+)

하루 50번 API 호출이면:

•

캐싱 없음: 50 × 10,000 = 500,000 토큰 = $1.50/일

•

캐싱 있음: 첫 요청만 Write, 나머지는 Read = $0.20/일 이하

2-3. 페르소나 파일이 변경되지 않는 한 완벽한 캐싱 대상이다

SOUL.md, USER.md, AGENTS.md는 매일 바뀌지 않는다. 이런 정적(static) 콘텐츠는 캐싱의 최적 대상이다.

Anthropic의 캐싱 조건:

•

최소 1,024 토큰 이상인 블록만 캐싱 가능

•

동일한 내용이 반복될 때 캐시 히트 발생

•

OpenClaw는 System Prompt에 cache_control: ephemeral 마크를 자동으로 붙여준다

3. 실제 비용 데이터 분석

아래는 실제 세션(2026-02-17)에서 측정된 데이터다.

3-1. 세션 시작부터 대화 진행에 따른 캐시 패턴

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

3-2. 핵심 인사이트

캐시 히트 69,836 토큰 = 일반 Input이었다면 $0.21 비용
실제 지불: $0.021 (캐시 Read 요금)
→ 해당 호출에서만 90% 절약

대화가 길어질수록 절약 비율이 증가한다:

초반 (8k 캐시): 절약률 ~50%
중반 (28k 캐시): 절약률 ~70%
후반 (70k 캐시): 절약률 ~87%

4. 캐싱 설정 방법

4-1. openclaw.json 설정 (핵심)

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

cacheRetention 옵션:

•

"short" — 약 5분 캐시 유지 (Anthropic 기본값)

•

"long" — 약 1시간 캐시 유지 ⭐ 권장

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

캐싱이 실제로 작동하는지 로그로 확인하려면:

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

로그 위치: /Users/myhome/.openclaw/logs/cache-trace.jsonl

4-3. contextPruning 설정 (캐싱과 연계)

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

cache-ttl 모드: 캐시 만료 시점에 맞춰 오래된 히스토리를 정리한다. long 캐싱(1시간)과 맞춰 ttl: "1h"로 설정하면 캐시가 살아있는 동안 히스토리가 유지된다.

4-4. 설정 적용

# 설정 파일 직접 편집 후
openclaw gateway restart

# 또는 OpenClaw에게 요청
"config.patch로 cacheRetention: long 적용해줘"

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

5-1. Anthropic의 캐시 TTL

Anthropic은 공식적으로 5분 캐시 TTL을 기본 제공한다.
OpenClaw의 cacheRetention: "long"은 캐시를 더 오래 유지하기 위해 **주기적으로 캐시를 갱신(재작성)**하는 전략을 사용한다.

5-2. 시나리오별 비교

시나리오: System Prompt 10,000 토큰, 하루 50번 API 호출

캐싱 없음

50회 × 10,000 토큰 × $3.00/1M = $1.50/일
월간: ~$45

5분 캐싱 (short)

대화가 5분 이상 끊기면 캐시 만료
Heartbeat가 1시간마다 → 매번 새 캐시 Write
Write 비용 포함 시 절약 효과 제한적
월간: ~$20 (약 55% 절약)

1시간 캐싱 (long)

1시간 동안 모든 호출이 캐시 히트
Heartbeat, cron, 대화 모두 혜택
Write는 1시간에 1~2번만 발생
월간: ~$5 (약 89% 절약)

5-3. 💡 핵심 팁: Heartbeat를 59분으로 설정하라

1시간 캐싱을 사용한다면 Heartbeat 간격을 59분으로 맞추는 것이 최적이다.

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

왜 59분인가?

•

캐시 TTL: 1시간 (60분)

•

Heartbeat가 59분마다 호출 → 캐시 만료 직전에 시스템이 API 호출

•

이 호출이 캐시를 갱신(re-write)해줌 → 캐시가 끊기지 않고 계속 살아있음

•

60분 간격이면 캐시 만료 후 호출 → 캐시 미스 발생

캐시 만료선: ─────────────────────────────[60분]
Heartbeat:  ──[59분]──[118분]──[177분]──
                ↑ 캐시 갱신   ↑ 갱신    ↑ 갱신
→ 캐시가 절대 만료되지 않음 ✅

5-4. OpenClaw 특화 이유

패턴	5분 캐싱	1시간 캐싱
Heartbeat (59분마다)	❌ 매번 캐시 미스	✅ 캐시 히트
Cron job (야간 리서치)	⚠️ 실행 간격 따라 다름	✅ 안정적 히트
빠른 연속 대화	✅ 히트	✅ 히트
30분 자리 비운 후 재개	❌ 캐시 미스	✅ 캐시 히트
아침 cron → 점심 대화	❌ 미스	✅ 히트 (1시간 내)

결론: OpenClaw처럼 비연속적, 간헐적 호출 패턴에서는 59분 캐싱이 압도적으로 유리하다.

6. 비용을 줄이는 전략

Strategy 1: 페르소나 파일 최적화

캐싱은 1,024 토큰 이상 블록에 적용된다. System Prompt의 첫 번째 큰 블록이 캐싱된다.

DO:

SOUL.md + USER.md + AGENTS.md → 앞부분에 배치 (캐싱 대상)
동적 컨텐츠(오늘 날짜, 실시간 데이터) → 뒷부분에 배치

DON'T:

매 요청마다 MEMORY.md를 완전히 새로 생성 → 캐시 무효화
System Prompt 앞부분에 타임스탬프 넣기 → 캐시 미스 유발

Strategy 2: Cron 세션 분리 (Isolated Session)

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

Isolated session은 Main session과 히스토리를 공유하지 않아 컨텍스트가 작게 시작된다 → 캐시 Write 비용 절감.

Strategy 3: CRON.md 분리 전략

❌ Bad: "Read workflows/WORKFLOW_MORNING_GREETING.md (350줄) and execute"
✅ Good: "Read CRON.md의 '아침 인사' 섹션을 따라 실행" (CRON.md = 30줄)

Cron이 읽는 파일을 작게 유지하면 Isolated session의 System Prompt 크기가 줄어들어 캐시 Write 비용이 감소한다.

Strategy 4: 컨텍스트 180k 관리

컨텍스트 180k 도달 시 → 새 세션 시작

컨텍스트가 너무 크면:

•

캐시 Write 비용이 급증

•

토큰 한도 초과 위험

•

캐시 효율성 저하 (자주 변하는 메시지가 캐시 블록 크기를 키움)

Strategy 5: 모델 선택 최적화

작업	권장 모델	이유
복잡한 분석	Sonnet 4.5	품질 필요
Heartbeat 체크	Haiku 4.5	단순 작업, 훨씬 저렴
Cron 요약	Haiku 4.5	반복 작업, 비용 절감
코딩/디버깅	Sonnet 4.5	정확도 필요

Haiku는 Sonnet 대비 Input $0.80/1M (Sonnet의 27%) — 캐시와 함께 쓰면 더욱 절감.

7. 캐싱 작동 여부 확인 방법

7-1. 세션 JSONL 파일에서 확인

# 현재 세션 ID 확인 (OpenClaw webchat에서)
# 세션 파일 경로:
/Users/myhome/.openclaw/agents/main/sessions/<session-id>.jsonl

# cacheRead/cacheWrite 필터링
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-2. 캐시 히트 판단 기준

cacheRead > 0    → ✅ 캐시 히트 (절약 발생)
cacheRead = 0    → ❌ 캐시 미스 (전체 input 비용 발생)
cacheWrite 급증  → 새 캐시 생성 (첫 요청 또는 캐시 갱신)

7-3. 정상 패턴 예시

요청 1: cacheRead=8,590  cacheWrite=11,772  ← 첫 요청, Write 비쌈
요청 2: cacheRead=8,590  cacheWrite=12,045  ← 캐시 히트!
요청 3: cacheRead=27,468 cacheWrite=266     ← 대부분 히트, 소폭 Write
...
요청 16: cacheRead=69,836 cacheWrite=455    ← 92% 절약 구간

7-4. 빠른 체크 명령어

# 오늘의 캐시 절약 금액 추정
grep -a "cacheRead" ~/.openclaw/agents/main/sessions/<id>.jsonl | \
python3 -c "
import sys, json
total_saved = 0
for line in sys.stdin:
    try:
        d = json.loads(line)
        u = d.get('message', {}).get('usage', {})
        cr = u.get('cacheRead', 0)
        # 캐시 Read vs 일반 Input 차이: $3.00 - $0.30 = $2.70/1M
        saved = cr * 2.70 / 1_000_000
        total_saved += saved
    except: pass
print(f'절약 금액: \${total_saved:.4f}')
"

요약 체크리스트

✅ openclaw.json에 cacheRetention: "long" 설정
✅ contextPruning mode: "cache-ttl", ttl: "1h" 설정
✅ Cron job은 isolated session으로 실행
✅ 워크플로우 파일을 짧게 유지 (CRON.md 분리 전략)
✅ 컨텍스트 180k 도달 시 새 세션 시작
✅ 단순 반복 작업은 Haiku 모델 사용
✅ diagnostics.cacheTrace 활성화로 주기적 모니터링

참고

•

Anthropic Prompt Caching 공식 문서

•

OpenClaw 공식 문서

•

이 문서의 비용 데이터는 2026-02-17 실제 세션 기반으로 측정됨

Made with Slashpage