Optimiza OpenClaw: Configura Prompt Caching y reduce costos

¿Alguna vez has sentido que estás desperdiciando dinero cada vez que envías el mismo contexto gigante a una API? Es frustrante pagar una y otra vez por esas instrucciones del sistema que no cambian. El prompt caching llega para solucionar esto, haciendo que tus aplicaciones sean más rápidas y baratas.

Prompt caching significa que el proveedor del modelo puede reutilizar prefijos de prompts que no han cambiado (normalmente instrucciones del sistema o de desarrollador y otro contexto estable) en lugar de procesarlos en cada turno. La primera solicitud que coincide escribe los tokens en el caché (cacheWrite), y las siguientes solicitudes que coincidan pueden leerlos (cacheRead).

Esto es importante por varias razones: menor costo de tokens, respuestas más rápidas, rendimiento predecible en sesiones largas y mayor eficiencia operativa. Sin el caching, los prompts repetidos pagan el costo total en cada turno, incluso si la mayor parte de la entrada no ha cambiado.

Esta página cubre todos los controles relacionados con el caché que afectan la reutilización de prompts y el costo de tokens.

Para detalles de precios de Anthropic, consulta: https://docs.anthropic.com/docs/build-with-claude/prompt-caching

Controles principales

cacheRetention (global por defecto, por modelo y por agente)

Configura la retención del caché como un valor global por defecto para todos los modelos:

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

Sobrescribir por modelo:

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

Sobrescribir por agente:

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

Orden de fusión de la configuración:

1. agents.defaults.params (global por defecto — se aplica a todos los modelos)
2. agents.defaults.models["provider/model"].params (sobrescritura por modelo)
3. agents.list[].params (coincidencia por id de agente; sobrescribe por clave)

Legacy cacheControlTtl

Los valores antiguos todavía se aceptan y se mapean de la siguiente forma:

• 5m -> short
• 1h -> long

Es preferible usar cacheRetention para configuraciones nuevas.

contextPruning.mode: "cache-ttl"

Recorta el contexto antiguo de resultados de herramientas después de las ventanas de TTL del caché para que las solicitudes tras un periodo de inactividad no vuelvan a cachear un historial excesivo.

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

Consulta Session Pruning para conocer el comportamiento completo.

Heartbeat para mantener el calor

El Heartbeat puede mantener activas las ventanas de caché y reducir las escrituras repetidas tras periodos de inactividad.

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

El Heartbeat por agente es compatible en agents.list[].heartbeat.

Comportamiento de los proveedores

Anthropic (API directa)

• cacheRetention es compatible.
• Con los perfiles de autenticación de Anthropic API-key, OpenClaw establece cacheRetention: "short" para las referencias de modelos de Anthropic cuando no está definido.

Amazon Bedrock

• Las referencias de modelos Anthropic Claude (amazon-bedrock/*anthropic.claude*) admiten el paso directo de cacheRetention.
• Los modelos de Bedrock que no son de Anthropic se fuerzan a cacheRetention: "none" en tiempo de ejecución.

Modelos de Anthropic en OpenRouter

Para las referencias de modelo openrouter/anthropic/*, OpenClaw inyecta el cache_control de Anthropic en los bloques de prompt del sistema o del desarrollador para mejorar la reutilización del prompt-cache.

Otros proveedores

Si el proveedor no admite este modo de caché, cacheRetention no tiene ningún efecto.

Patrones de optimización

Tráfico mixto (recomendado por defecto)

Mantén una base de larga duración en tu agente principal y desactiva el caching en agentes de notificación que funcionan por ráfagas:

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"

Base enfocada en el costo

• Configura la base cacheRetention: "short".
• Activa contextPruning.mode: "cache-ttl".
• Mantén el heartbeat por debajo de tu TTL solo para los agentes que se beneficien de cachés calientes.

Diagnóstico del caché

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

Configuración de diagnostics.cacheTrace

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

Valores por defecto:

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

Interruptores por variables de entorno (depuración puntual)

• OPENCLAW_CACHE_TRACE=1 activa el rastreo de caché.
• OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl sobrescribe la ruta de salida.
• OPENCLAW_CACHE_TRACE_MESSAGES=0|1 alterna la captura del payload completo de los mensajes.
• OPENCLAW_CACHE_TRACE_PROMPT=0|1 alterna la captura del texto del prompt.
• OPENCLAW_CACHE_TRACE_SYSTEM=0|1 alterna la captura del prompt del sistema.

Qué inspeccionar

• Los eventos de rastreo de caché están en formato JSONL e incluyen instantáneas como session:loaded, prompt:before, stream:context y session:after.
• El impacto de los tokens de caché por turno es visible en las interfaces de uso habituales mediante cacheRead y cacheWrite (por ejemplo, con /usage full y los resúmenes de uso de sesión).

Solución rápida de problemas

• cacheWrite elevado en la mayoría de los turnos: revisa si hay entradas volátiles en el prompt del sistema y verifica que el modelo o proveedor admita tus ajustes de caché.
• cacheRetention no tiene efecto: confirma que la clave del modelo coincida con agents.defaults.models["provider/model"].
• Solicitudes de Bedrock Nova/Mistral con ajustes de caché: es normal que se fuercen a none en tiempo de ejecución.

Documentación relacionada:

• Anthropic
• Uso de tokens y costos
• Session Pruning
• Referencia de configuración del Gateway

Siguientes pasos

• Configura tu primer agente con caching siguiendo la Referencia de configuración del Gateway.
• Aprende más sobre cómo ahorrar tokens en Uso de tokens y costos.

AI Setup Assistant