​

Almacenamiento en caché de prompts

• Almacenamiento en caché de prompts de Anthropic: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• Almacenamiento en caché de prompts de OpenAI: https://developers.openai.com/api/docs/guides/prompt-caching
• Encabezados de API e ID de solicitud de OpenAI: https://developers.openai.com/api/reference/overview
• ID de solicitud y errores de Anthropic: https://platform.claude.com/docs/en/api/errors

​

Controles principales

​

cacheRetention (valor predeterminado global, modelo y por agente)

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

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

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

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

​

contextPruning.mode: "cache-ttl"

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

​

Heartbeat keep-warm

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

​

Comportamiento del proveedor

​

Anthropic (API directa)

• cacheRetention es compatible.
• Con perfiles de autenticación mediante API key de Anthropic, OpenClaw inicializa cacheRetention: "short" para referencias de modelos de Anthropic cuando no está definido.
• Las respuestas nativas de Messages de Anthropic exponen tanto cache_read_input_tokens como cache_creation_input_tokens, por lo que OpenClaw puede mostrar tanto cacheRead como cacheWrite.
• Para solicitudes nativas de Anthropic, cacheRetention: "short" se asigna a la caché efímera predeterminada de 5 minutos, y cacheRetention: "long" amplía al TTL de 1 hora solo en hosts directos api.anthropic.com.

​

OpenAI (API directa)

• El almacenamiento en caché de prompts es automático en los modelos recientes compatibles. OpenClaw no necesita inyectar marcadores de caché a nivel de bloque.
• OpenClaw usa prompt_cache_key para mantener estable el enrutamiento de caché entre turnos y usa prompt_cache_retention: "24h" solo cuando cacheRetention: "long" está seleccionado en hosts directos de OpenAI.
• Las respuestas de OpenAI exponen los tokens de prompt almacenados en caché mediante usage.prompt_tokens_details.cached_tokens (o input_tokens_details.cached_tokens en eventos de la Responses API). OpenClaw asigna eso a cacheRead.
• OpenAI no expone un contador separado de tokens de escritura en caché, por lo que cacheWrite permanece en 0 en rutas de OpenAI incluso cuando el proveedor está calentando una caché.
• OpenAI devuelve encabezados útiles de trazabilidad y límites de tasa como x-request-id, openai-processing-ms y x-ratelimit-*, pero el cálculo de aciertos de caché debe provenir de la carga útil de uso, no de los encabezados.
• En la práctica, OpenAI suele comportarse como una caché de prefijo inicial en lugar de una reutilización móvil de historial completo al estilo Anthropic. Los turnos de texto largo con prefijo estable pueden llegar a una meseta cercana a 4864 tokens almacenados en caché en las pruebas en vivo actuales, mientras que las transcripciones con muchas herramientas o de estilo MCP suelen estabilizarse cerca de 4608 tokens almacenados en caché incluso en repeticiones exactas.

​

Anthropic Vertex

• Los modelos de Anthropic en Vertex AI (anthropic-vertex/*) admiten cacheRetention de la misma manera que Anthropic directo.
• cacheRetention: "long" se asigna al TTL real de caché de prompts de 1 hora en endpoints de Vertex AI.
• La retención de caché predeterminada para anthropic-vertex coincide con los valores predeterminados directos de Anthropic.
• Las solicitudes de Vertex se enrutan mediante modelado de caché consciente de límites para que la reutilización de caché se mantenga alineada con lo que los proveedores realmente reciben.

​

Amazon Bedrock

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

​

Modelos Anthropic en OpenRouter

​

Otros proveedores

​

API directa de Google Gemini

• El transporte directo de Gemini (api: "google-generative-ai") informa los aciertos de caché mediante cachedContentTokenCount upstream; OpenClaw lo asigna a cacheRead.
• Cuando cacheRetention está establecido en un modelo directo de Gemini, OpenClaw crea, reutiliza y actualiza automáticamente recursos cachedContents para prompts del sistema en ejecuciones de Google AI Studio. Esto significa que ya no necesitas crear previamente un identificador de contenido en caché manualmente.
• Aun así puedes pasar un identificador existente de contenido en caché de Gemini como params.cachedContent (o el heredado params.cached_content) en el modelo configurado.
• Esto es independiente del almacenamiento en caché de prefijos de prompt de Anthropic/OpenAI. Para Gemini, OpenClaw administra un recurso cachedContents nativo del proveedor en lugar de inyectar marcadores de caché en la solicitud.

​

Uso JSON de CLI de Gemini

• La salida JSON de la CLI de Gemini también puede mostrar aciertos de caché mediante stats.cached; OpenClaw lo asigna a cacheRead.
• Si la CLI omite un valor directo stats.input, OpenClaw deriva los tokens de entrada a partir de stats.input_tokens - stats.cached.
• Esto es solo normalización de uso. No significa que OpenClaw esté creando marcadores de caché de prompts al estilo Anthropic/OpenAI para la CLI de Gemini.

​

Límite de caché del prompt del sistema

• Los archivos estables de contexto del proyecto del espacio de trabajo se ordenan antes de HEARTBEAT.md para que el cambio frecuente de heartbeat no invalide el prefijo estable.
• El límite se aplica en el modelado de caché de la familia Anthropic, la familia OpenAI, Google y el transporte de CLI, para que todos los proveedores compatibles se beneficien de la misma estabilidad de prefijo.
• Las solicitudes de Codex Responses y Anthropic Vertex se enrutan mediante modelado de caché consciente de límites para que la reutilización de caché se mantenga alineada con lo que los proveedores realmente reciben.
• Las huellas del prompt del sistema se normalizan (espacios en blanco, finales de línea, contexto añadido por hooks, orden de capacidades en tiempo de ejecución) para que los prompts semánticamente sin cambios compartan KV/caché entre turnos.

​

Protecciones de estabilidad de caché de OpenClaw

• Los catálogos agrupados de herramientas MCP se ordenan de forma determinista antes del registro de herramientas, para que los cambios en el orden de listTools() no alteren el bloque de herramientas ni invaliden los prefijos de caché de prompts.
• Las sesiones heredadas con bloques de imágenes persistidos mantienen intactos los 3 turnos completados más recientes; los bloques de imágenes antiguos ya procesados pueden sustituirse por un marcador para que los seguimientos con muchas imágenes no sigan reenviando cargas útiles grandes obsoletas.

​

Patrones de ajuste

​

Tráfico mixto (valor predeterminado recomendado)

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 orientada al costo

• Establece una base con cacheRetention: "short".
• Activa contextPruning.mode: "cache-ttl".
• Mantén el heartbeat por debajo de tu TTL solo para los agentes que se benefician de cachés activas.

​

Diagnóstico de caché

​

Pruebas de regresión en vivo

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

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

​

Expectativas en vivo de Anthropic

• Espera escrituras de calentamiento explícitas mediante cacheWrite.
• Espera una reutilización de casi todo el historial en turnos repetidos porque el control de caché de Anthropic adelanta el punto de corte de caché a lo largo de la conversación.
• Las aserciones en vivo actuales siguen usando umbrales altos de tasa de aciertos para rutas estables, con herramientas e imágenes.

​

Expectativas en vivo de OpenAI

• Espera solo cacheRead. cacheWrite permanece en 0.
• Trata la reutilización de caché en turnos repetidos como una meseta específica del proveedor, no como una reutilización móvil de historial al estilo Anthropic.
• Las aserciones en vivo actuales usan comprobaciones de umbral mínimo conservadoras derivadas del comportamiento observado en vivo en gpt-5.4-mini:
  • prefijo estable: cacheRead >= 4608, tasa de aciertos >= 0.90
  • transcripción de herramientas: cacheRead >= 4096, tasa de aciertos >= 0.85
  • transcripción de imágenes: cacheRead >= 3840, tasa de aciertos >= 0.82
  • transcripción de estilo MCP: cacheRead >= 4096, tasa de aciertos >= 0.85

• prefijo estable: cacheRead=4864, tasa de aciertos 0.966
• transcripción de herramientas: cacheRead=4608, tasa de aciertos 0.896
• transcripción de imágenes: cacheRead=4864, tasa de aciertos 0.954
• transcripción de estilo MCP: cacheRead=4608, tasa de aciertos 0.891

• Anthropic expone puntos de corte de caché explícitos y reutilización móvil del historial de conversación.
• El almacenamiento en caché de prompts de OpenAI sigue siendo sensible al prefijo exacto, pero el prefijo reutilizable efectivo en tráfico vivo de Responses puede estabilizarse antes que el prompt completo.
• Debido a eso, comparar Anthropic y OpenAI con un único umbral porcentual entre proveedores genera regresiones falsas.

​

Configuración de diagnostics.cacheTrace

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

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

​

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 activa o desactiva la captura de la carga útil completa de mensajes.
• OPENCLAW_CACHE_TRACE_PROMPT=0|1 activa o desactiva la captura del texto del prompt.
• OPENCLAW_CACHE_TRACE_SYSTEM=0|1 activa o desactiva la captura del prompt del sistema.

​

Qué inspeccionar

• Los eventos de rastreo de caché están en JSONL e incluyen instantáneas por etapas como session:loaded, prompt:before, stream:context y session:after.
• El impacto por turno de tokens de caché es visible en las superficies normales de uso mediante cacheRead y cacheWrite (por ejemplo /usage full y resúmenes de uso de sesión).
• Para Anthropic, espera tanto cacheRead como cacheWrite cuando el almacenamiento en caché esté activo.
• Para OpenAI, espera cacheRead en aciertos de caché y que cacheWrite permanezca en 0; OpenAI no publica un campo separado de tokens de escritura en caché.
• Si necesitas trazabilidad de solicitudes, registra por separado los ID de solicitud y los encabezados de límite de tasa de las métricas de caché. La salida actual de rastreo de caché de OpenClaw se centra en la forma del prompt/sesión y en el uso normalizado de tokens, en lugar de en encabezados sin procesar de respuestas del proveedor.

​

Solución rápida de problemas

• cacheWrite alto en la mayoría de los turnos: comprueba si hay entradas volátiles en el prompt del sistema y verifica que el modelo/proveedor admita tu configuración de caché.
• cacheWrite alto en Anthropic: a menudo significa que el punto de corte de caché está cayendo sobre contenido que cambia en cada solicitud.
• cacheRead bajo en OpenAI: verifica que el prefijo estable esté al principio, que el prefijo repetido tenga al menos 1024 tokens y que se reutilice la misma prompt_cache_key en los turnos que deberían compartir una caché.
• Sin efecto de cacheRetention: confirma que la clave del modelo coincida con agents.defaults.models["provider/model"].
• Solicitudes de Bedrock Nova/Mistral con configuración de caché: es esperado que en tiempo de ejecución se fuerce a none.

• Anthropic
• Uso de tokens y costos
• Poda de sesiones
• Referencia de configuración de Gateway