Caché de prompts

Caché de prompts significa que el proveedor del modelo puede reutilizar prefijos de prompt sin cambios (generalmente instrucciones de sistema/desarrollador y otro contexto estable) entre turnos en lugar de reprocesarlos cada vez. La primera solicitud que coincide escribe tokens de caché (cacheWrite), y las solicitudes posteriores que coincidan pueden leerlos de vuelta (cacheRead).

Por qué importa: menor costo de tokens, respuestas más rápidas y rendimiento más predecible para sesiones de larga duración.

Configuraciones principales

`cacheRetention` (modelo y por agente)

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

Legacy `cacheControlTtl`

Los valores legacy todavía se aceptan y se mapean: 5m -> short, 1h -> long.

`contextPruning.mode: "cache-ttl"`

Poda el contexto viejo de resultados de herramientas después de las ventanas de TTL de caché.

Heartbeat keep-warm

El heartbeat puede mantener las ventanas de caché activas y reducir escrituras de caché repetidas después de períodos de inactividad.

Comportamiento del proveedor

Anthropic (API directa)

cacheRetention soportado.

Amazon Bedrock

Los modelos Claude de Anthropic soportan pass-through explícito de cacheRetention.
Los modelos Bedrock que no son de Anthropic se fuerzan a cacheRetention: "none" en runtime.

Modelos Anthropic de OpenRouter

Para refs de modelo openrouter/anthropic/*, OpenClaw inyecta cache_control de Anthropic en los bloques de prompt sistema/desarrollador.

Patrones de ajuste

Tráfico mixto (por defecto recomendado)

Mantén una línea base de larga duración en tu agente principal, desactiva el caché en agentes de notificación con ráfagas.

Línea base orientada a costos

Configura cacheRetention: "short" como línea base.
Habilita contextPruning.mode: "cache-ttl".
Mantén el heartbeat por debajo de tu TTL solo para agentes que se beneficien de cachés calientes.

Diagnósticos de caché

OpenClaw expone diagnósticos dedicados de trace de caché para ejecuciones de agentes embebidos.

Configuración: diagnostics.cacheTrace.enabled: true
Variables de entorno: OPENCLAW_CACHE_TRACE=1

Solución rápida de problemas

Alto cacheWrite en la mayoría de turnos: verifica entradas volátiles del system-prompt.
Sin efecto de cacheRetention: confirma que la clave del modelo coincide con agents.defaults.models["provider/model"].

Documentación relacionada: