Prompt caching

기준일: 2026-07-26
공식 기준: Prompt caching

Prompt caching 문서는 OpenClaw 공식 문서(reference/prompt-caching)를 한국어로 정리한 가이드입니다. Prompt caching knobs, merge order, provider behavior, and tuning patterns 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Prompt caching knobs, merge order, provider behavior, and tuning patterns

한국어 가이드 범위: reference/prompt-caching 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Primary knobs
• cacheRetention
• contextPruning.mode: "cache-ttl"
• Heartbeat keep-warm
• Provider behavior
• Anthropic (direct API and Vertex AI)
• OpenAI (direct API)
• Amazon Bedrock
• OpenRouter
• Google Gemini (direct API)
• CLI-harness providers (Claude Code, Gemini CLI)
• Other providers
• System-prompt cache boundary
• Tuning patterns
• Mixed traffic (recommended default)
• Cost-first baseline
• Live regression tests
• Anthropic live expectations
• OpenAI live expectations
• diagnostics.cacheTrace config
• Env toggles (one-off debugging)
• What to inspect
• Quick troubleshooting
• 관련 문서

상세 내용

본문

Prompt caching lets a model provider reuse an unchanged prompt prefix (system/developer instructions, tool definitions, other stable context) across turns instead of reprocessing it every request. This cuts token cost and latency on long-running sessions with repeated context.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Anthropic prompt caching
• OpenAI prompt caching

Primary knobs

이 섹션의 세부 항목은 공식 문서 Primary knobs를 참고하세요.

cacheRetention

Values: "none" | "short" | "long". Configurable as a global default, per model, and per agent. "standard" is not an alias; use "short" for the provider's default cache window. Invalid values are ignored with a warning.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• id: "alerts"

agents:
  defaults:
    params:
      cacheRetention: "long" # none | short | long
    models:
      "anthropic/claude-opus-4":
        params:
          cacheRetention: "short" # overrides the global default for this model
  list:
    - id: "alerts"
      params:
        cacheRetention: "none" # overrides both defaults for this agent

contextPruning.mode: "cache-ttl"

Prunes old tool-result context after the cache TTL window elapses, so a post-idle request does not re-cache oversized history.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

Heartbeat keep-warm

Heartbeat can keep cache windows warm and reduce repeated cache writes after idle gaps. Configurable globally (agents.defaults.heartbeat) or per agent (agents.entries.*.heartbeat).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

Provider behavior

이 섹션의 세부 항목은 공식 문서 Provider behavior를 참고하세요.

Anthropic (direct API and Vertex AI)

Source: packages/ai/src/transports/anthropic-payload-policy.ts (resolveAnthropicEphemeralCacheControl, isLongTtlEligibleEndpoint).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• cacheRetention is supported for anthropic and anthropic-vertex providers, and for Claude models on amazon-bedrock and custom anthropic-messages-compatible endpoints when cacheRetention is set explicitly.
• When unset, OpenClaw seeds cacheRetention: "short" for direct Anthropic (anthropic and anthropic-vertex providers only; other Anthropic-family routes require an explicit value).
• Native Anthropic Messages responses expose cache_read_input_tokens and cache_creation_input_tokens, mapped to cacheRead and cacheWrite.
• cacheRetention: "short" maps to the default 5-minute ephemeral cache. cacheRetention: "long" requests the 1-hour TTL (cache_control: { type: "ephemeral", ttl: "1h" }) when set explicitly. An implicit/env-driven long retention (OPENCLAW_CACHE_RETENTION=long with no explicit cacheRetention) only upgrades to the 1-hour TTL on api.anthropic.com or Vertex AI (aiplatform.googleapis.com / *-aiplatform.googleapis.com) hosts; other hosts keep the 5-minute cache.

OpenAI (direct API)

주요 항목:

• Prompt caching is automatic on supported recent models; OpenClaw does not inject block-level cache markers.
• OpenClaw sends prompt_cache_key to keep cache routing stable across turns. Direct api.openai.com hosts get this automatically. OpenAI-compatible proxies (oMLX, llama.cpp, custom endpoints) need compat.supportsPromptCacheKey: true in model config to opt in - this is never auto-detected for a proxy.
• prompt_cache_retention: "24h" is added only when cacheRetention: "long" is selected and the resolved endpoint supports both the cache key and long retention (compat.supportsLongCacheRetention, true by default; Together AI and Cloudflare compat profiles disable it). cacheRetention: "none" suppresses both fields.
• Cache hits surface via usage.prompt_tokens_details.cached_tokens (Chat Completions) or input_tokens_details.cached_tokens (Responses API), mapped to cacheRead.
• Responses API payloads can also expose input_tokens_details.cache_write_tokens, mapped to cacheWrite and priced at the model's cache-write rate; Responses payloads that omit the field keep cacheWrite at 0. OpenAI's Chat Completions API does not document or emit a cache_write_tokens counter, but OpenClaw still reads prompt_tokens_details.cache_write_tokens there for OpenRouter-compatible and DeepSeek-style proxies that report a separate write count.
• In practice, OpenAI behaves more like an initial-prefix cache than Anthropic's moving full-history reuse - see OpenAI live expectations below.

Amazon Bedrock

주요 항목:

• Anthropic Claude model refs (amazon-bedrock/*anthropic.claude*, plus AWS system inference profile prefixes us./eu./global.anthropic.claude*) support explicit cacheRetention pass-through.
• Non-Anthropic Bedrock models (for example amazon.nova-*) resolve to no cache retention at runtime, regardless of any configured cacheRetention value.
• Opaque Bedrock application inference profile ARNs (profile IDs that do not contain claude) also resolve to no cache retention unless cacheRetention is set explicitly, since the model family cannot be inferred from the ARN alone.

OpenRouter

For openrouter/anthropic/* model refs, OpenClaw injects Anthropic cache_control markers on system/developer prompt blocks, but only when the request still targets a verified OpenRouter route (openrouter on its default endpoint, or any provider/base URL that resolves to openrouter.ai). Repointing the model at an arbitrary OpenAI-compatible proxy URL stops this injection.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Google Gemini (direct API)

Source: src/agents/embedded-agent-runner/google-prompt-cache.ts.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Direct Gemini transport (api: "google-generative-ai") reports cache hits through upstream cachedContentTokenCount, mapped to cacheRead.
• Eligible model families: gemini-2.5* and gemini-3* (excludes Live/preview variants outside that prefix match, for example gemini-live-2.5-flash-preview).
• When cacheRetention is set on an eligible model, OpenClaw automatically creates, reuses, and refreshes a cachedContents resource for the system prompt - no manual cached-content handle needed. TTL is 300s for cacheRetention: "short" and 3600s for "long".
• You can still pass a pre-existing Gemini cached-content handle through as params.cachedContent (or legacy params.cached_content); an explicit handle skips the automatic cache-management path entirely.
• This is separate from Anthropic/OpenAI prompt-prefix caching: OpenClaw manages a provider-native cachedContents resource for Gemini instead of injecting inline cache markers.

CLI-harness providers (Claude Code, Gemini CLI)

CLI backends that emit JSONL usage events (jsonlDialect: "claude-stream-json" or "gemini-stream-json") go through a shared usage parser that recognizes several field-name variants, including a plain cached counter mapped to cacheRead. When the CLI's JSON payload omits a direct input-token field, OpenClaw derives it as input_tokens - cached. This is usage normalization only - it does not create Anthropic/OpenAI-style prompt-cache markers for these CLI-driven models.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Other providers

If a provider does not support any of the above cache modes, cacheRetention has no effect.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

System-prompt cache boundary

OpenClaw splits the system prompt into a stable prefix and a volatile suffix at an internal cache-prefix boundary. Content above the boundary (tool definitions, skills metadata, workspace files) is ordered to stay byte-identical across turns. Content below the boundary (for example HEARTBEAT.md, runtime timestamps, other per-turn metadata) can change without invalidating the cached prefix.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Stable workspace project-context files are ordered before HEARTBEAT.md so heartbeat churn does not bust the stable prefix.
• The boundary applies across Anthropic-family, OpenAI-family, Google, and CLI transport shaping, so all supported providers benefit from the same prefix stability.
• Codex Responses and Anthropic Vertex requests are routed through boundary-aware cache shaping so cache reuse stays aligned with what providers actually receive.
• System-prompt fingerprints are normalized (whitespace, line endings, hook-added context, runtime capability ordering) so semantically unchanged prompts share cache across turns.

OpenClaw cache-stability guards

주요 항목:

• Bundled MCP tool catalogs are sorted deterministically (by server name, then tool name) before tool registration, so listTools() order changes do not churn the tools block and bust prompt-cache prefixes.
• Legacy sessions with persisted image blocks keep the 3 most recent completed turns intact (counting all completed turns, not just image-bearing ones). Older already-processed image blocks are replaced with a text marker so image-heavy follow-ups do not keep re-sending large stale payloads.

Tuning patterns

이 섹션의 세부 항목은 공식 문서 Tuning patterns를 참고하세요.

Mixed traffic (recommended default)

Keep a long-lived baseline on your main agent, disable caching on bursty notifier agents:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• id: "research"
• id: "alerts"

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

Cost-first baseline

주요 항목:

• Set baseline cacheRetention: "short".
• Enable contextPruning.mode: "cache-ttl".
• Keep heartbeat below your TTL only for agents that benefit from warm caches.

Live regression tests

OpenClaw runs one combined live cache regression gate covering repeated prefixes, tool turns, image turns, MCP-style tool transcripts, and an Anthropic no-cache control.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• src/agents/live-cache-regression.live.test.ts
• src/agents/live-cache-regression-runner.ts
• src/agents/live-cache-regression-baseline.ts

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache

Anthropic live expectations

주요 항목:

• Expect explicit warmup writes via cacheWrite.
• Expect near-full history reuse on repeated turns, because Anthropic's cache control advances the cache breakpoint through the conversation.
• Baseline floors for stable, tool, image, and MCP-style lanes are hard regression gates.

OpenAI live expectations

The most recently observed baseline numbers (from live-cache-regression-baseline.ts) landed at: stable prefix cacheRead=4864, hit rate 0.966; tool transcript cacheRead=4608, hit rate 0.896; image transcript cacheRead=4864, hit rate 0.954; MCP-style transcript cacheRead=4608, hit rate 0.891.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Expect cacheRead only; cacheWrite stays 0 on Chat Completions.
• Treat repeated-turn cache reuse as a provider-specific plateau, not Anthropic-style moving full-history reuse.
• Floors are watch-only (a miss is logged as a warning, not a test failure), derived from observed live behavior on gpt-5.4-mini:

Scenario	cacheRead floor	Hit-rate floor
Stable prefix	4,608	0.90
Tool transcript	4,096	0.85
Image transcript	3,840	0.82
MCP-style transcript	4,096	0.85

diagnostics.cacheTrace config

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

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

Env toggles (one-off debugging)

Variable	Effect
OPENCLAW_CACHE_TRACE=1	Enables cache tracing
OPENCLAW_CACHE_TRACE_FILE=path	Overrides output path
OPENCLAW_CACHE_TRACE_MESSAGES=0|1	Toggles full message payload capture
OPENCLAW_CACHE_TRACE_PROMPT=0|1	Toggles prompt text capture
OPENCLAW_CACHE_TRACE_SYSTEM=0|1	Toggles system prompt capture

What to inspect

주요 항목:

• Cache trace events are JSONL with staged snapshots like session:loaded, prompt:before, stream:context, and session:after.
• Per-turn cache token impact is visible in normal usage surfaces: cacheRead and cacheWrite show up in /usage tokens, /status, session usage summaries, and custom messages.usageTemplate layouts.
• For Anthropic, expect both cacheRead and cacheWrite when caching is active.
• For OpenAI, expect cacheRead on cache hits; cacheWrite is populated only on Responses API payloads that include it (see OpenAI above).
• OpenAI also returns tracing and rate-limit headers such as x-request-id, openai-processing-ms, and x-ratelimit-*; use those for request tracing, but cache-hit accounting should still come from the usage payload, not from headers.

Quick troubleshooting

주요 항목:

• High cacheWrite on most turns: check for volatile system-prompt inputs; verify the model/provider supports your cache settings.
• High cacheWrite on Anthropic: often means the cache breakpoint is landing on content that changes every request.
• Low OpenAI cacheRead: verify the stable prefix is at the front, the repeated prefix is at least 1024 tokens, and the same prompt_cache_key is reused for turns that should share a cache.
• No effect from cacheRetention: confirm the model key matches agents.defaults.models["provider/model"].
• Bedrock Nova requests with cache settings: expected - these resolve to no cache retention at runtime.
• Anthropic
• Token use and costs
• Session pruning
• Gateway configuration reference

관련 문서

주요 항목:

• Token use and costs
• API usage and costs

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/reference/prompt-caching
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

agents:
  defaults:
    params:
      cacheRetention: "long" # none | short | long
    models:
      "anthropic/claude-opus-4":
        params:
          cacheRetention: "short" # overrides the global default for this model
  list:
    - id: "alerts"
      params:
        cacheRetention: "none" # overrides both defaults for this agent

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

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

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

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache

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

관련 링크

• 공식 원문: reference/prompt-caching
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.