# Configurar la caché

> Fija el nivel de caché, el TTL de caché del navegador, el modo desarrollo, la armadura anti-engaño, el contenido caducado y el tamaño máximo de objeto.

Todos los ajustes de caché están en `cache`, dentro de los ajustes del borde de la zona. Cada uno se puede fijar para toda la zona o para un nombre: en el panel con **Ámbito**, en la CLI con `--host`, en la API en `hosts.<nombre>.cache` y en MCP con `host`. Un nombre hereda todos los ajustes que no fija él mismo. Consulta [Ajustes por nombre](https://developers.openwaf.dev/es/rules/per-name-settings/).

En el panel, todo lo de esta página está en **Caché**; guarda con **Guardar cambios** y un motivo.

## Activar o desactivar la caché

`cache.enabled` (**Caché en el borde**), desactivada por defecto. Al desactivarla, todas las peticiones pasan a ser `DYNAMIC` desde la siguiente configuración.

## Nivel de caché

`cache.query.mode`, `cache.query.params` y `cache.query.sort` deciden cómo entra la cadena de consulta en la clave de caché: entera (por defecto), nada, solo algunos parámetros o todos salvo algunos. Consulta [Claves de caché](https://developers.openwaf.dev/es/cache/cache-keys/#query-string).

```sh
openwaf-cloud ctl zones set example.com cache.query.mode=exclude 'cache.query.params:=["utm_*","fbclid","gclid"]' --reason "sin parámetros de anuncios"
```

## TTL de caché del navegador

`cache.browser_ttl`, en segundos. `0` (**Respetar los encabezados existentes**, el valor por defecto) reenvía la `Cache-Control` de tu origen sin tocarla. Un valor mayor que `0` **sube** el `max-age` que reciben los navegadores hasta al menos ese valor; un `max-age` mayor del origen sigue ganando, y las respuestas que el navegador no debe guardar (`no-store`, `private`…) no se tocan. El panel ofrece duraciones de 30 minutos a 1 año.

## Modo desarrollo

`cache.dev_mode_until` es una fecha y hora (RFC 3339) hasta la que se omite la caché: todas las peticiones van a tu origen y se marcan como `DYNAMIC`, así ves los cambios al instante. No se borra nada; purga si los visitantes también deben ver el cambio.

**Panel**

Activa **Modo desarrollo** y guarda: se desactiva solo a las 3 horas.

**CLI**

```sh
openwaf-cloud ctl zones set example.com cache.dev_mode_until=2026-10-27T18:00:00Z --reason "rediseño"
openwaf-cloud ctl zones set example.com cache.dev_mode_until:=null --reason "terminado"
```

**API**

```json
{"cache": {"dev_mode_until": "2026-10-27T18:00:00Z"}}
```

`{"cache": {"dev_mode_until": null}}` lo desactiva.

**MCP**

`update_settings` con `{"settings": {"cache": {"dev_mode_until": "2026-10-27T18:00:00Z"}}}`, o `null` para desactivarlo.


Un nombre puede desactivar un modo desarrollo activo en toda la zona fijando su propio valor en el pasado (en el panel, desactívalo dentro del ámbito del nombre).

## Armadura anti-engaño de caché

`cache.deception_armor`, activada por defecto. No guarda una respuesta cuyo tipo de contenido contradice la extensión de la URL, como una página HTML en `/profile/x.css`. Consulta [Comportamiento por defecto](https://developers.openwaf.dev/es/cache/default-behavior/#deception-armor).

> **Peligro**
>
> Con la armadura desactivada, una página personal pedida como `/account.php/x.css` podría guardarse y servirse a otros visitantes. Mantenla activada salvo que tengas la seguridad de que todas las URL estáticas del sitio devuelven su tipo real.


## Contenido caducado

| Ajuste | Panel | Por defecto | Efecto |
|---|---|---|---|
| `cache.serve_stale.while_revalidate` | Servir caducado mientras se revalida | `true` | Respeta el `stale-while-revalidate` del origen: sirve la copia caducada mientras se actualiza en segundo plano. |
| `cache.serve_stale.on_error_max_s` | Servir caducado si el origen falla | `86400` (24 h) | Cuánto tiempo después de caducar se puede seguir sirviendo una copia si el origen está caído o responde `500`/`502`/`503`/`504` y no envió `stale-if-error`. `0` = nunca; como mucho 30 días. |

## Tamaño máximo de objeto

`cache.max_object_mb`, de `1` a `512`, por defecto `100`. Las respuestas más grandes llegan al visitante sin guardarse.

```sh
openwaf-cloud ctl zones set example.com --host videos.example.com cache.max_object_mb=512 --reason "vídeos grandes"
```

## Volver a los valores por defecto

En la API, `"cache": null` devuelve todos los ajustes de caché de la zona a su valor por defecto. Para un nombre, `openwaf-cloud ctl zones set example.com --host www.example.com --unset cache --reason "hereda de la zona"` hace que vuelva a seguir a la zona.

## Comprobar el resultado

La configuración efectiva de un nombre muestra la caché que recibe de verdad, tras combinar los ajustes de la zona y los del nombre:

```sh
openwaf-cloud ctl zones effective example.com www.example.com
```

Consulta [Configuración efectiva](https://developers.openwaf.dev/es/rules/effective-config/).