Potatura della sessione

La potatura della sessione riduce i risultati meno recenti degli strumenti nel contesto prima di ogni chiamata al modello LLM. Limita l'espansione del contesto causata dall'accumulo degli output degli strumenti (risultati di esecuzione, letture di file, risultati di ricerca) senza riscrivere il normale testo della conversazione.

Perché è importante

Le sessioni lunghe accumulano output degli strumenti che ampliano la finestra di contesto. Ciò aumenta i costi e può rendere necessaria la Compaction prima del previsto.

La potatura è particolarmente utile per la memorizzazione nella cache dei prompt di Anthropic. Dopo la scadenza del TTL della cache, la richiesta successiva memorizza nuovamente nella cache l'intero prompt. La potatura riduce le dimensioni dei dati scritti nella cache, abbassando direttamente i costi.

Come funziona

La potatura viene eseguita in modalità cache-ttl ed è subordinata sia a un controllo temporale sia a un controllo delle dimensioni del contesto:

1. Attende la scadenza del TTL della cache (valore predefinito di 5 minuti quando impostato manualmente; per il valore predefinito automatico di Anthropic, vedere Valori predefiniti intelligenti). Prima che il TTL sia trascorso, la potatura viene completamente ignorata per preservare il riutilizzo della cache dei prompt nei turni ravvicinati.
2. Una volta trascorso il TTL, stima le dimensioni totali del contesto rispetto alla finestra di contesto del modello. Se il rapporto è inferiore a softTrimRatio (valore predefinito 0,3), ignora la potatura e lascia attivo il conteggio del TTL.
3. Riduce parzialmente i risultati degli strumenti sovradimensionati che superano il rapporto: conserva l'inizio e la fine (per impostazione predefinita 1.500 caratteri ciascuno, con un limite complessivo di 4.000 caratteri) e inserisce ... tra le due parti.
4. Se il rapporto è ancora pari o superiore a hardClearRatio (valore predefinito 0,5) e rimangono almeno minPrunableToolChars (valore predefinito 50.000) caratteri di contenuto degli strumenti eliminabile, cancella completamente tali risultati: ne sostituisce il contenuto con un segnaposto (valore predefinito [Contenuto del risultato precedente dello strumento cancellato]).
5. Azzera il conteggio del TTL solo quando la potatura ha effettivamente modificato il contesto, in modo che le richieste successive riutilizzino la cache appena creata.

Indipendentemente dalle soglie, si applicano due regole di sicurezza: i keepLastAssistants turni più recenti dell'assistente (valore predefinito 3) non vengono mai potati e nulla di quanto precede il primo messaggio dell'utente nella sessione viene mai potato (ciò protegge le letture di inizializzazione come SOUL.md/USER.md).

Solo i messaggi toolResult sono idonei; il normale testo della conversazione non viene modificato. Usa agents.defaults.contextPruning.tools.{allow,deny} per definire quali nomi di strumenti possono essere potati.

Pulizia delle immagini obsolete

OpenClaw crea inoltre una vista di riproduzione separata e idempotente per le sessioni che conservano nella cronologia blocchi di immagini non elaborati o marcatori multimediali per l'inizializzazione dei prompt.

• Conserva i 3 turni completati più recenti byte per byte, affinché i prefissi della cache dei prompt rimangano stabili per le richieste successive recenti. Il conteggio include tutti i turni completati, non solo quelli contenenti immagini, quindi anche i turni di solo testo occupano la finestra.
• Nella vista di riproduzione, i blocchi di immagini meno recenti e già elaborati nella cronologia di user o toolResult vengono sostituiti con [dati dell'immagine rimossi - già elaborati dal modello].
• I riferimenti testuali meno recenti ai contenuti multimediali, come [contenuto multimediale allegato: ...], [Immagine: origine: ...] e media://inbound/..., vengono sostituiti con [riferimento al contenuto multimediale rimosso - già elaborato dal modello]. I marcatori degli allegati del turno corrente rimangono intatti, affinché i modelli visivi possano ancora caricare le nuove immagini.
• La trascrizione non elaborata della sessione non viene riscritta, quindi i visualizzatori della cronologia possono continuare a mostrare le voci originali dei messaggi e le relative immagini.
• Questa operazione è distinta dalla normale potatura basata sul TTL della cache descritta sopra. Serve a impedire che payload di immagini ripetuti o riferimenti multimediali obsoleti invalidino le cache dei prompt nei turni successivi.

Valori predefiniti intelligenti

Il Plugin Anthropic incluso configura automaticamente la potatura e la frequenza dell'Heartbeat la prima volta che risolve un profilo di autenticazione Anthropic (o Claude CLI), ma solo per i campi che non sono già stati impostati esplicitamente:

Se imposti autonomamente agents.defaults.contextPruning.mode o agents.defaults.heartbeat.every, OpenClaw non li sovrascrive. Questo valore predefinito automatico si applica solo all'autenticazione della famiglia Anthropic; per gli altri fornitori la potatura è off, a meno che non venga configurata.

Attivazione o disattivazione

La potatura è disattivata per impostazione predefinita per i fornitori diversi da Anthropic. Per attivarla:

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

Per disattivarla: imposta mode: "off".

Potatura e Compaction

Si completano a vicenda: la potatura mantiene snelli gli output degli strumenti tra un ciclo di Compaction e l'altro.

Ulteriori letture

• Compaction: riduzione del contesto basata sulla sintesi
• Configurazione del Gateway: tutte le opzioni di configurazione della potatura (contextPruning.*)

Contenuti correlati

• Gestione delle sessioni
• Strumenti di sessione
• Motore del contesto