OpenClaw v2026.3.13 agrega configuración de cacheRetention por agente para ahorrar costos de tokens de OpenAI.

¿Qué cambió en v2026.3.13

La versión 2026.3.13 de OpenClaw añadió validación de configuración adecuada para params.cacheRetention en las entradas por agente. Esto te permite configurar la retención de caché de manera declarativa en tu archivo de configuración openclaw.json.

El problema con el comportamiento de caché predeterminado

OpenAI admite retención extendida de caché de prompts (24 horas) mediante prompt_cache_retention: "24h" en su API, lo que mantiene el prefijo de tu prompt en caché durante 24 horas en lugar de los 5-10 minutos predeterminados. Los tokens de entrada en caché se facturan con un 50% de descuento.

Si ejecutas agentes en ciclos de latido superiores a 10 minutos (lo que la fuente señala que es "básicamente todos"), tu caché se enfría por completo entre cada turno. Esto significa que pagas el precio completo por todo el contexto de entrada en cada latido.

La fuente describe una configuración con 15 agentes en GPT-5.2 con latidos cada 60-90 minutos donde cada latido era un inicio en frío garantizado. El prompt del sistema, el contexto de arranque, HEARTBEAT.md, AGENTS.md, SOUL.md, las definiciones de herramientas — todo se reenviaba a precio completo en cada ciclo porque la caché expiraba en el intervalo entre latidos.

Cómo configurarlo

Ahora puedes configurar la retención de caché en tu openclaw.json:

{
  "agents": {
    "list": [
      {
        "agentId": "my-agent",
        "params": {
          "cacheRetention": "long"
        }
      }
    ]
  }
}

El valor "long" se asigna a prompt_cache_retention: "24h" de OpenAI a través de la biblioteca pi-ai.

Advertencia importante: se requiere parche de tiempo de ejecución

La función resolveCacheRetention() de OpenClaw tiene una cláusula de protección que bloquea a los proveedores de OpenAI por defecto. Solo permite pasar a Anthropic y Bedrock. Así que incluso con la configuración establecida, el valor se filtra antes de llegar a la API.

Necesitas el parche de tiempo de ejecución del issue #27515 para que funcione. El parche añade OpenAI a la lista de proveedores permitidos en la cláusula de protección. Sin tanto la configuración COMO el parche, no sucede nada.

El autor de la fuente señala que tuvo el parche aplicado durante semanas pero nunca estableció el valor de configuración — lo que significa que el parche estaba verificando extraParams?.cacheRetention !== void 0, obteniendo undefined, y aún así bloqueando a OpenAI. El parche no hacía nada sin la configuración.

Potencial de ahorro de costos

Con 15 agentes realizando latidos, cada uno enviando ~128K-170K tokens de entrada por turno:

• Sin caché de 24h: 100% de los tokens de entrada a precio completo, en cada turno. La caché muere en el intervalo de ~60-90 minutos entre latidos.
• Con caché de 24h: El prefijo estable (prompt del sistema, configuración del agente, definiciones de herramientas — típicamente 80-90% de la entrada) permanece en caché entre latidos. Esos tokens se facturan a mitad de precio.

En un sistema que ejecuta 15 agentes durante un día laboral completo, eso son cientos de ciclos de latido por día donde la mayor parte de los tokens de entrada pasan de precio completo a mitad de precio. La reducción del costo de entrada se acumula rápidamente.