Poda de sesión

La poda de sesión recorta resultados antiguos de herramientas del contexto en memoria justo antes de cada llamada LLM. No reescribe el historial de sesión en disco (*.jsonl).

Cuándo se ejecuta

• Cuando mode: "cache-ttl" está habilitado y la última llamada de Anthropic para la sesión es más antigua que ttl.
• Solo afecta los mensajes enviados al modelo para esa solicitud.
• Solo está activo para llamadas a la API de Anthropic (y modelos de Anthropic a través de OpenRouter).
• Para mejores resultados, haz coincidir ttl con tu política de cacheRetention del modelo (short = 5m, long = 1h).
• Después de una poda, la ventana TTL se reinicia para que las solicitudes siguientes mantengan la caché hasta que ttl expire de nuevo.

Valores inteligentes por defecto (Anthropic)

• Perfiles OAuth o setup-token: habilitan la poda cache-ttl y configuran heartbeat a 1h.
• Perfiles de clave API: habilitan la poda cache-ttl, configuran heartbeat a 30m y establecen cacheRetention: "short" por defecto en modelos de Anthropic.
• Si configuras cualquiera de estos valores explícitamente, OpenClaw no los sobreescribe.

Qué mejora esto (costo + comportamiento de caché)

• Por qué podar: el caché de prompt de Anthropic solo aplica dentro del TTL. Si una sesión queda inactiva pasado el TTL, la siguiente solicitud re-cachea el prompt completo a menos que lo recortes primero.
• Qué se abarata: la poda reduce el tamaño de cacheWrite para esa primera solicitud después de que expire el TTL.
• Por qué importa el reinicio del TTL: una vez que la poda se ejecuta, la ventana de caché se reinicia, así que las solicitudes de seguimiento pueden reusar el prompt recién cacheado en lugar de re-cachear todo el historial de nuevo.
• Lo que no hace: la poda no agrega tokens ni “duplica” costos; solo cambia qué se cachea en esa primera solicitud post-TTL.

Qué se puede podar

• Solo mensajes toolResult.
• Los mensajes de usuario + asistente nunca se modifican.
• Los últimos keepLastAssistants mensajes del asistente están protegidos; los resultados de herramientas después de ese corte no se podan.
• Si no hay suficientes mensajes de asistente para establecer el corte, la poda se omite.
• Los resultados de herramientas que contienen bloques de imagen se omiten (nunca se recortan/limpian).

Estimación de la ventana de contexto

La poda usa una estimación de la ventana de contexto (chars ≈ tokens × 4). La ventana base se resuelve en este orden:

1. Sobreescritura de models.providers.*.models[].contextWindow.
2. contextWindow de la definición del modelo (del registro de modelos).
3. Por defecto 200000 tokens.

Si agents.defaults.contextTokens está configurado, se trata como un tope (mínimo) sobre la ventana resuelta.

Modo

cache-ttl

• La poda solo se ejecuta si la última llamada de Anthropic es más antigua que ttl (por defecto 5m).
• Cuando se ejecuta: mismo comportamiento de soft-trim + hard-clear que antes.

Poda suave vs. dura

• Soft-trim: solo para resultados de herramientas sobredimensionados.
  • Conserva cabeza + cola, inserta ... y agrega una nota con el tamaño original.
  • Omite resultados con bloques de imagen.
• Hard-clear: reemplaza el resultado completo de la herramienta con hardClear.placeholder.

Selección de herramientas

• tools.allow / tools.deny soportan comodines *.
• Deny gana.
• La coincidencia no distingue mayúsculas de minúsculas.
• Lista allow vacía => todas las herramientas permitidas.

Interacción con otros límites

• Las herramientas integradas ya truncan su propia salida; la poda de sesión es una capa adicional que evita que los chats de larga duración acumulen demasiada salida de herramientas en el contexto del modelo.
• La compactación es algo separado: la compactación resume y persiste, la poda es transitoria por solicitud. Ver /concepts/compaction.

Valores por defecto (cuando está habilitado)

• ttl: "5m"
• keepLastAssistants: 3
• softTrimRatio: 0.3
• hardClearRatio: 0.5
• minPrunableToolChars: 50000
• softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 }
• hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }

Ejemplos

Desactivado (por defecto):

{
  agents: { defaults: { contextPruning: { mode: "off" } } },
}

Habilitar poda con reconocimiento de TTL:

{
  agents: { defaults: { contextPruning: { mode: "cache-ttl", ttl: "5m" } } },
}

Restringir la poda a herramientas específicas:

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl",
        tools: { allow: ["exec", "read"], deny: ["*image*"] },
      },
    },
  },
}

Consulta la referencia de configuración: Gateway Configuration