Almacenamiento en caché de prompts

El almacenamiento en caché de prompts permite que un proveedor de modelos reutilice un prefijo de prompt sin cambios (instrucciones del sistema/desarrollador, definiciones de herramientas y otro contexto estable) entre turnos, en lugar de volver a procesarlo en cada solicitud. Esto reduce el coste de los tokens y la latencia en sesiones de larga duración con contexto repetido.

OpenClaw normaliza el uso del proveedor en cacheRead y cacheWrite siempre que la API ascendente exponga esos contadores. Los resúmenes de uso (/status y similares) recurren a la última entrada de uso de la transcripción cuando la instantánea de la sesión activa carece de contadores de caché; un valor activo distinto de cero siempre prevalece sobre el valor alternativo.

Referencias de proveedores:

• Almacenamiento en caché de prompts de Anthropic
• Almacenamiento en caché de prompts de OpenAI

Controles principales

cacheRetention

Valores: "none" | "short" | "long". Se puede configurar como valor predeterminado global, por modelo y por agente.

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

Orden de combinación (prevalece el último):

1. agents.defaults.params - valor predeterminado global para todos los modelos
2. agents.defaults.models["provider/model"].params - anulación por modelo
3. agents.list[].params - anulación por agente, asociada mediante el identificador del agente

Fuente: src/agents/embedded-agent-runner/extra-params.ts (resolveExtraParams).

contextPruning.mode: "cache-ttl"

Recorta el contexto antiguo de resultados de herramientas una vez transcurrida la ventana de TTL de la caché, para que una solicitud posterior a un periodo de inactividad no vuelva a almacenar en caché un historial sobredimensionado.

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

Consulta Recorte de sesiones para conocer el comportamiento completo.

Mantenimiento en caliente mediante Heartbeat

Heartbeat puede mantener activas las ventanas de caché y reducir las escrituras repetidas en caché tras periodos de inactividad. Se puede configurar globalmente (agents.defaults.heartbeat) o por agente (agents.list[].heartbeat).

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

Comportamiento de los proveedores

Anthropic (API directa y Vertex AI)

• cacheRetention es compatible con los proveedores anthropic y anthropic-vertex, así como con los modelos Claude en amazon-bedrock y los endpoints personalizados compatibles con anthropic-messages cuando cacheRetention se establece explícitamente.
• Cuando no se establece, OpenClaw inicializa cacheRetention: "short" para Anthropic directo (solo para los proveedores anthropic y anthropic-vertex; las demás rutas de la familia Anthropic requieren un valor explícito).
• Las respuestas nativas de Anthropic Messages exponen cache_read_input_tokens y cache_creation_input_tokens, que se asignan a cacheRead y cacheWrite.
• cacheRetention: "short" se asigna a la caché efímera predeterminada de 5 minutos. cacheRetention: "long" solicita el TTL de 1 hora (cache_control: { type: "ephemeral", ttl: "1h" }) cuando se establece explícitamente. Una retención larga implícita o controlada por el entorno (OPENCLAW_CACHE_RETENTION=long sin un cacheRetention explícito) solo amplía el TTL a 1 hora en hosts de api.anthropic.com o Vertex AI (aiplatform.googleapis.com / *-aiplatform.googleapis.com); los demás hosts conservan la caché de 5 minutos.

Fuente: src/agents/anthropic-payload-policy.ts (resolveAnthropicEphemeralCacheControl, isLongTtlEligibleEndpoint).

OpenAI (API directa)

• El almacenamiento en caché de prompts es automático en los modelos recientes compatibles; OpenClaw no inserta marcadores de caché por bloque.
• OpenClaw envía prompt_cache_key para mantener estable el enrutamiento de la caché entre turnos. Los hosts directos de api.openai.com lo reciben automáticamente. Los proxies compatibles con OpenAI (oMLX, llama.cpp y endpoints personalizados) deben incluir compat.supportsPromptCacheKey: true en la configuración del modelo para habilitarlo; esto nunca se detecta automáticamente en un proxy.
• prompt_cache_retention: "24h" solo se añade cuando se selecciona cacheRetention: "long" y el endpoint resuelto admite tanto la clave de caché como la retención larga (compat.supportsLongCacheRetention, true de forma predeterminada; los perfiles de compatibilidad de Together AI y Cloudflare la desactivan). cacheRetention: "none" suprime ambos campos.
• Los aciertos de caché aparecen mediante usage.prompt_tokens_details.cached_tokens (Chat Completions) o input_tokens_details.cached_tokens (Responses API), que se asignan a cacheRead.
• Las cargas útiles de Responses API también pueden exponer input_tokens_details.cache_write_tokens, que se asigna a cacheWrite y se factura según la tarifa de escritura en caché del modelo; las cargas útiles de Responses que omiten el campo mantienen cacheWrite en 0. La API Chat Completions de OpenAI no documenta ni emite un contador cache_write_tokens, pero OpenClaw aun así lee prompt_tokens_details.cache_write_tokens en ella para proxies compatibles con OpenRouter y de estilo DeepSeek que informan de un recuento de escrituras independiente.
• En la práctica, OpenAI se comporta más como una caché del prefijo inicial que como la reutilización móvil del historial completo de Anthropic; consulta Expectativas de OpenAI en producción más adelante.

Amazon Bedrock

• Las referencias de modelos Anthropic Claude (amazon-bedrock/*anthropic.claude*, además de los prefijos de perfiles de inferencia del sistema de AWS us./eu./global.anthropic.claude*) admiten el paso explícito de cacheRetention.
• Los modelos de Bedrock que no son de Anthropic (por ejemplo, amazon.nova-*) se resuelven sin retención de caché durante la ejecución, independientemente del valor configurado de cacheRetention.
• Los ARN opacos de perfiles de inferencia de aplicaciones de Bedrock (identificadores de perfil que no contienen claude) también se resuelven sin retención de caché, salvo que cacheRetention se establezca explícitamente, ya que la familia del modelo no puede inferirse únicamente a partir del ARN.

OpenRouter

Para las referencias de modelos openrouter/anthropic/*, OpenClaw inserta marcadores cache_control de Anthropic en los bloques de prompts del sistema/desarrollador, pero solo cuando la solicitud sigue dirigida a una ruta de OpenRouter verificada (openrouter en su endpoint predeterminado, o cualquier proveedor/URL base que se resuelva en openrouter.ai). Redirigir el modelo a una URL de proxy arbitraria compatible con OpenAI detiene esta inserción.

contextPruning.mode: "cache-ttl" está permitido para las referencias de modelos openrouter/anthropic/*, openrouter/deepseek/*, openrouter/moonshot/*, openrouter/moonshotai/* y openrouter/zai/*, porque estas rutas gestionan el almacenamiento en caché de prompts en el proveedor sin necesitar los marcadores insertados por OpenClaw.

Fuente: extensions/openrouter/index.ts (OPENROUTER_CACHE_TTL_MODEL_PREFIXES).

La creación de la caché de DeepSeek en OpenRouter se realiza con el mejor esfuerzo y puede tardar unos segundos; una solicitud de seguimiento inmediata puede seguir mostrando cached_tokens: 0. Verifícala con una solicitud repetida con el mismo prefijo tras una breve espera, usando usage.prompt_tokens_details.cached_tokens como señal de acierto de caché.

Google Gemini (API directa)

• El transporte directo de Gemini (api: "google-generative-ai") informa de los aciertos de caché mediante el valor ascendente cachedContentTokenCount, que se asigna a cacheRead.
• Familias de modelos aptas: gemini-2.5* y gemini-3* (se excluyen las variantes Live o de vista previa fuera de esa coincidencia de prefijo, por ejemplo, gemini-live-2.5-flash-preview).
• Cuando se establece cacheRetention en un modelo apto, OpenClaw crea, reutiliza y actualiza automáticamente un recurso cachedContents para el prompt del sistema; no se necesita ningún identificador manual de contenido almacenado en caché. El TTL es de 300s para cacheRetention: "short" y de 3600s para "long".
• También puedes pasar un identificador preexistente de contenido almacenado en caché de Gemini mediante params.cachedContent (o el formato heredado params.cached_content); un identificador explícito omite por completo la ruta de gestión automática de la caché.
• Esto es independiente del almacenamiento en caché de prefijos de prompts de Anthropic/OpenAI: OpenClaw gestiona un recurso cachedContents nativo del proveedor para Gemini, en lugar de insertar marcadores de caché en línea.

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

Proveedores con arnés de CLI (Claude Code, Gemini CLI)

Los backends de CLI que emiten eventos de uso JSONL (jsonlDialect: "claude-stream-json" o "gemini-stream-json") pasan por un analizador de uso compartido que reconoce varias variantes de nombres de campos, incluido un contador simple cached que se asigna a cacheRead. Cuando la carga útil JSON de la CLI omite un campo directo de tokens de entrada, OpenClaw lo calcula como input_tokens - cached. Esto solo normaliza el uso; no crea marcadores de caché de prompts al estilo de Anthropic/OpenAI para estos modelos controlados mediante CLI.

Fuente: src/agents/cli-output.ts (toCliUsage).

Otros proveedores

Si un proveedor no admite ninguno de los modos de caché anteriores, cacheRetention no tiene efecto.

Límite de caché del prompt del sistema

OpenClaw divide el prompt del sistema en un prefijo estable y un sufijo volátil mediante un límite interno del prefijo de caché. El contenido situado por encima del límite (definiciones de herramientas, metadatos de Skills y archivos del espacio de trabajo) se ordena para permanecer idéntico byte por byte entre turnos. El contenido situado por debajo del límite (por ejemplo, HEARTBEAT.md, marcas de tiempo de ejecución y otros metadatos de cada turno) puede cambiar sin invalidar el prefijo almacenado en caché.

Decisiones clave de diseño:

• Los archivos estables de contexto del proyecto del espacio de trabajo se ordenan antes de HEARTBEAT.md, de modo que los cambios de Heartbeat no invaliden el prefijo estable.
• El límite se aplica a la conformación del transporte de las familias Anthropic y OpenAI, Google y la CLI, por lo que todos los proveedores compatibles se benefician de la misma estabilidad del prefijo.
• Las solicitudes de Codex Responses y Anthropic Vertex se enrutan mediante una conformación de caché consciente del límite, para que la reutilización de la caché permanezca alineada con lo que realmente reciben los proveedores.
• Las huellas digitales del prompt del sistema se normalizan (espacios en blanco, finales de línea, contexto añadido por hooks y ordenación de capacidades de ejecución), de modo que los prompts semánticamente idénticos compartan caché entre turnos.

Si observas aumentos inesperados de cacheWrite después de un cambio de configuración o del espacio de trabajo, comprueba si el cambio queda por encima o por debajo del límite de caché. Mover el contenido volátil por debajo del límite (o estabilizarlo) suele resolver el problema.

Protecciones de estabilidad de caché de OpenClaw

• Los catálogos de herramientas MCP incluidos se ordenan de forma determinista (primero por nombre del servidor y después por nombre de la herramienta) antes de registrar las herramientas, de modo que los cambios en el orden de listTools() no modifiquen continuamente el bloque de herramientas ni invaliden los prefijos de la caché de prompts.
• Las sesiones heredadas con bloques de imágenes persistentes conservan intactos los 3 turnos completados más recientes (se cuentan todos los turnos completados, no solo los que contienen imágenes). Los bloques de imágenes más antiguos que ya se hayan procesado se sustituyen por un marcador de texto, para que los seguimientos con muchas imágenes no sigan reenviando cargas útiles obsoletas de gran tamaño.

Patrones de ajuste

Tráfico mixto (valor predeterminado recomendado)

Mantén una base de larga duración en tu agente principal y desactiva el almacenamiento en caché en los agentes de notificación con actividad en 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"

Configuración base centrada en el coste

• Establece cacheRetention: "short" como valor base.
• Habilita contextPruning.mode: "cache-ttl".
• Mantén Heartbeat por debajo del TTL solo para los agentes que se beneficien de las cachés activas.

Pruebas de regresión en producción

OpenClaw ejecuta una única comprobación combinada de regresión de caché en producción que abarca prefijos repetidos, turnos de herramientas, turnos de imágenes, transcripciones de herramientas de estilo MCP y un control sin caché de Anthropic.

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

Ejecútala con:

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

El archivo de referencia almacena las cifras observadas más recientemente en producción, además de los umbrales mínimos de regresión específicos de cada proveedor que comprueba la prueba. Cada ejecución usa identificadores de sesión y espacios de nombres de prompts nuevos, específicos de esa ejecución, para que el estado previo de la caché no contamine la muestra actual. Anthropic y OpenAI aplican criterios distintos: no alcanzar el umbral mínimo de Anthropic constituye una regresión grave (la prueba falla), mientras que no alcanzar el umbral mínimo de OpenAI solo se supervisa (se registra como advertencia y la ejecución no falla). No comparten un único umbral común entre proveedores.

Expectativas de Anthropic en producción

• Espere escrituras explícitas de calentamiento mediante cacheWrite.
• Espere una reutilización casi completa del historial en turnos repetidos, porque el control de caché de Anthropic desplaza el punto de interrupción de la caché a lo largo de la conversación.
• Los umbrales mínimos de referencia para las rutas estables, de herramientas, de imágenes y de estilo MCP son barreras estrictas contra regresiones.

Expectativas en vivo de OpenAI

• Espere solo cacheRead; cacheWrite permanece en 0 en Chat Completions.
• Trate la reutilización de la caché en turnos repetidos como una meseta específica del proveedor, no como la reutilización móvil de todo el historial al estilo de Anthropic.
• Los umbrales mínimos solo se supervisan (un incumplimiento se registra como advertencia, no como fallo de prueba) y se derivan del comportamiento en vivo observado en gpt-5.4-mini:

Las cifras de referencia observadas más recientemente (de live-cache-regression-baseline.ts) quedaron en: prefijo estable cacheRead=4864, tasa de aciertos 0.966; transcripción de herramienta cacheRead=4608, tasa de aciertos 0.896; transcripción de imagen cacheRead=4864, tasa de aciertos 0.954; transcripción de estilo MCP cacheRead=4608, tasa de aciertos 0.891.

Por qué difieren las aserciones: Anthropic expone puntos de interrupción explícitos de la caché y una reutilización móvil del historial de conversación, mientras que el prefijo reutilizable efectivo de OpenAI en el tráfico en vivo puede alcanzar una meseta antes de abarcar todo el prompt. Comparar ambos proveedores con un único umbral porcentual común genera falsas regresiones.

Configuración de diagnostics.cacheTrace

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

Valores predeterminados:

Variables de entorno (depuración puntual)

Qué inspeccionar

• Los eventos de seguimiento de la caché están en formato JSONL, con instantáneas por etapas como session:loaded, prompt:before, stream:context y session:after.
• El impacto de los tokens de caché por turno es visible en las superficies de uso habituales: cacheRead y cacheWrite aparecen en /usage tokens, /status, los resúmenes de uso de las sesiones y los diseños personalizados de messages.usageTemplate.
• Para Anthropic, espere tanto cacheRead como cacheWrite cuando el almacenamiento en caché esté activo.
• Para OpenAI, espere cacheRead cuando haya aciertos de caché; cacheWrite solo se rellena en las cargas útiles de Responses API que lo incluyan (consulte OpenAI más arriba).
• OpenAI también devuelve encabezados de seguimiento y límites de tasa, como x-request-id, openai-processing-ms y x-ratelimit-*; utilícelos para rastrear solicitudes, pero la contabilización de los aciertos de caché debe seguir obteniéndose de la carga útil de uso, no de los encabezados.

Solución rápida de problemas

• cacheWrite alto en la mayoría de los turnos: compruebe si hay entradas volátiles en el prompt del sistema; verifique que el modelo o proveedor admita su configuración de caché.
• cacheWrite alto en Anthropic: a menudo significa que el punto de interrupción de la caché está situado en contenido que cambia con cada solicitud.
• cacheRead bajo en OpenAI: verifique que el prefijo estable esté al principio, que el prefijo repetido tenga al menos 1024 tokens y que se reutilice el mismo prompt_cache_key en los turnos que deban compartir una caché.
• cacheRetention no tiene efecto: confirme que la clave del modelo coincida con agents.defaults.models["provider/model"].
• Solicitudes de Bedrock Nova con configuración de caché: es el comportamiento esperado; estas se resuelven sin retención de caché durante la ejecución.

Documentación relacionada:

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

Contenido relacionado

• Uso y costes de tokens
• Uso y costes de la API