OpenClaw v2026.3.13 adiciona configuração de cacheRetention por agente para economia de custos com tokens da OpenAI.

O que mudou na v2026.3.13

A versão 2026.3.13 do OpenClaw adicionou validação de configuração adequada para params.cacheRetention em entradas por agente. Isso permite que você defina a retenção de cache de forma declarativa no seu arquivo de configuração openclaw.json.

O problema com o comportamento padrão do cache

A OpenAI suporta retenção estendida de cache de prompt (24 horas) via prompt_cache_retention: "24h" em sua API, que mantém o prefixo do seu prompt em cache por 24 horas em vez dos 5-10 minutos padrão. Tokens de entrada em cache são cobrados com 50% de desconto.

Se você está executando agentes em ciclos de heartbeat maiores que 10 minutos (que a fonte observa ser "basicamente todo mundo"), seu cache fica completamente frio entre cada turno. Isso significa que você está pagando preço cheio por todo o contexto de entrada em cada heartbeat.

A fonte descreve uma configuração com 15 agentes no GPT-5.2 com heartbeats a cada 60-90 minutos onde cada heartbeat era um início frio garantido. O prompt do sistema, contexto de inicialização, HEARTBEAT.md, AGENTS.md, SOUL.md, definições de ferramentas — tudo isso era reenviado a preço cheio a cada ciclo porque o cache expirava no intervalo entre os heartbeats.

Como configurar

Agora você pode definir a retenção de cache no seu openclaw.json:

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

O valor "long" mapeia para o prompt_cache_retention: "24h" da OpenAI através da biblioteca pi-ai.

Observação importante: patch de runtime necessário

A função resolveCacheRetention() do OpenClaw tem uma cláusula de proteção que bloqueia provedores da OpenAI por padrão. Ela só permite Anthropic e Bedrock. Então, mesmo com a configuração definida, o valor é filtrado antes de chegar à API.

Você precisa do patch de runtime do issue #27515 para fazer funcionar. O patch adiciona a OpenAI à lista de provedores permitidos na cláusula de proteção. Sem tanto a configuração QUANTO o patch, nada acontece.

O autor da fonte observa que tinha o patch aplicado por semanas mas nunca definiu o valor da configuração — significando que o patch estava verificando extraParams?.cacheRetention !== void 0, obtendo undefined, e ainda bloqueando a OpenAI. O patch não estava fazendo nada sem a configuração.

Potencial de economia de custos

Com 15 agentes fazendo heartbeats, cada um enviando ~128K-170K tokens de entrada por turno:

• Sem cache de 24h: 100% dos tokens de entrada a preço cheio, a cada turno. O cache morre no intervalo de ~60-90 min entre heartbeats.
• Com cache de 24h: O prefixo estável (prompt do sistema, configuração do agente, definições de ferramentas — tipicamente 80-90% da entrada) permanece em cache entre heartbeats. Esses tokens são cobrados com metade do preço.

Em um sistema executando 15 agentes durante um dia de trabalho completo, são centenas de ciclos de heartbeat por dia onde a maior parte dos tokens de entrada muda de preço cheio para metade do preço. A redução de custo de entrada se acumula rapidamente.