Compaction

Ogni modello ha una finestra di contesto: il numero massimo di token che può elaborare. Quando una conversazione si avvicina a quel limite, OpenClaw esegue la Compaction dei messaggi meno recenti in un riepilogo, così la chat può continuare.

Come funziona

1. I turni meno recenti della conversazione vengono riassunti in una voce compatta.
2. Il riepilogo viene salvato nella trascrizione della sessione.
3. I messaggi recenti vengono mantenuti intatti.

Quando OpenClaw suddivide la cronologia in blocchi di Compaction, mantiene le chiamate agli strumenti dell'assistente abbinate alle rispettive voci toolResult. Se un punto di divisione cade all'interno di un blocco strumento, OpenClaw sposta il confine in modo che la coppia resti insieme e la coda corrente non riassunta venga preservata.

La cronologia completa della conversazione resta su disco. La Compaction cambia solo ciò che il modello vede al turno successivo.

Compaction automatica

La Compaction automatica è attiva per impostazione predefinita. Viene eseguita quando la sessione si avvicina al limite di contesto, oppure quando il modello restituisce un errore di overflow del contesto (in tal caso OpenClaw esegue la Compaction e riprova).

Vedrai:

• embedded run auto-compaction start / complete nei normali log del Gateway.
• 🧹 Auto-compaction complete in modalità dettagliata.
• /status che mostra 🧹 Compactions: <count>.

Compaction manuale

Digita /compact in qualsiasi chat per forzare una Compaction. Aggiungi istruzioni per guidare il riepilogo:

/compact Focus on the API design decisions

Quando agents.defaults.compaction.keepRecentTokens è impostato, la Compaction manuale rispetta quel punto di taglio di OpenClaw e mantiene la coda recente nel contesto ricostruito. Senza un budget di mantenimento esplicito, la Compaction manuale si comporta come un checkpoint rigido e continua solo dal nuovo riepilogo.

Configurazione

Configura la Compaction sotto agents.defaults.compaction nel tuo openclaw.json. Le opzioni più comuni sono elencate di seguito; per il riferimento completo, vedi Approfondimento sulla gestione della sessione.

Usare un modello diverso

Per impostazione predefinita, la Compaction usa il modello principale dell'agente. Imposta agents.defaults.compaction.model per delegare la sintesi a un modello più capace o specializzato. L'override accetta una stringa provider/model-id o un alias semplice configurato sotto agents.defaults.models:

{  "agents": {    "defaults": {      "compaction": {        "model": "openrouter/anthropic/claude-sonnet-4-6"      }    }  }}

Gli alias semplici configurati vengono risolti nel rispettivo provider e modello canonici prima dell'avvio della Compaction. Se un valore semplice corrisponde sia a un alias sia a un ID modello letterale configurato, vince l'ID modello letterale. Un valore semplice senza corrispondenza resta un ID modello sul provider attivo.

Funziona anche con modelli locali, ad esempio un secondo modello Ollama dedicato alla sintesi:

{  "agents": {    "defaults": {      "compaction": {        "model": "ollama/llama3.1:8b"      }    }  }}

Quando non è impostata, la Compaction parte dal modello della sessione attiva. Se la sintesi fallisce con un errore del provider idoneo al fallback del modello, OpenClaw ritenta quel tentativo di Compaction tramite la catena di fallback dei modelli esistente della sessione. La scelta di fallback è temporanea e non viene riscritta nello stato della sessione. Un override esplicito agents.defaults.compaction.model resta esatto e non eredita la catena di fallback della sessione.

Preservazione degli identificatori

La sintesi della Compaction preserva per impostazione predefinita gli identificatori opachi (identifierPolicy: "strict"). Esegui l'override con identifierPolicy: "off" per disabilitarla, oppure con identifierPolicy: "custom" più identifierInstructions per indicazioni personalizzate.

Protezione dei byte della trascrizione attiva

Quando agents.defaults.compaction.maxActiveTranscriptBytes è impostato, OpenClaw attiva la normale Compaction locale prima di un'esecuzione se il JSONL attivo raggiunge quella dimensione. Questo è utile per sessioni di lunga durata in cui la gestione del contesto lato provider può mantenere sano il contesto del modello mentre la trascrizione locale continua a crescere. Non divide i byte JSONL grezzi; chiede alla normale pipeline di Compaction di creare un riepilogo semantico.

Trascrizioni successive

Quando agents.defaults.compaction.truncateAfterCompaction è abilitato, OpenClaw non riscrive sul posto la trascrizione esistente. Crea una nuova trascrizione successiva attiva dal riepilogo della Compaction, dallo stato preservato e dalla coda non riassunta, quindi registra metadati di checkpoint che indirizzano i flussi di branch/ripristino verso quel successore compattato. Le trascrizioni successive eliminano anche i turni utente lunghi esattamente duplicati che arrivano entro una breve finestra di ritentativo, così le tempeste di retry del canale non vengono portate nella successiva trascrizione attiva dopo la Compaction.

OpenClaw non scrive più copie separate .checkpoint.*.jsonl per le nuove Compaction. I file checkpoint legacy esistenti possono ancora essere usati finché referenziati e vengono eliminati dalla normale pulizia della sessione.

Avvisi di Compaction

Per impostazione predefinita, la Compaction viene eseguita silenziosamente. Imposta notifyUser per mostrare brevi messaggi di stato quando la Compaction inizia e si completa:

{  agents: {    defaults: {      compaction: {        notifyUser: true,      },    },  },}

Flush della memoria

Prima della Compaction, OpenClaw può eseguire un turno di flush silenzioso della memoria per archiviare note durevoli su disco. Imposta agents.defaults.compaction.memoryFlush.model quando questo turno di housekeeping deve usare un modello locale invece del modello della conversazione attiva:

{  "agents": {    "defaults": {      "compaction": {        "memoryFlush": {          "model": "ollama/qwen3:8b"        }      }    }  }}

L'override del modello di flush della memoria è esatto e non eredita la catena di fallback della sessione attiva. Vedi Memoria per dettagli e configurazione.

Provider di Compaction collegabili

I Plugin possono registrare un provider di Compaction personalizzato tramite registerCompactionProvider() nell'API del Plugin. Quando un provider è registrato e configurato, OpenClaw delega la sintesi a esso invece che alla pipeline LLM integrata.

Per usare un provider registrato, imposta il suo ID nella configurazione:

{  "agents": {    "defaults": {      "compaction": {        "provider": "my-provider"      }    }  }}

Impostare un provider forza automaticamente mode: "safeguard". I provider ricevono le stesse istruzioni di Compaction e la stessa policy di preservazione degli identificatori del percorso integrato, e OpenClaw preserva comunque il contesto di suffisso dei turni recenti e dei turni divisi dopo l'output del provider.

Compaction e pruning

Il pruning della sessione è un complemento più leggero che taglia l'output degli strumenti senza riassumerlo.

Risoluzione dei problemi

La Compaction avviene troppo spesso? La finestra di contesto del modello potrebbe essere piccola, oppure gli output degli strumenti potrebbero essere grandi. Prova ad abilitare il pruning della sessione.

Il contesto sembra obsoleto dopo la Compaction? Usa /compact Focus on <topic> per guidare il riepilogo, oppure abilita il flush della memoria così le note sopravvivono.

Serve una situazione pulita? /new avvia una nuova sessione senza eseguire la Compaction.

Per la configurazione avanzata (token di riserva, preservazione degli identificatori, motori di contesto personalizzati, Compaction lato server OpenAI), vedi l'approfondimento sulla gestione della sessione.

Correlati

• Sessione: gestione e ciclo di vita della sessione.
• Pruning della sessione: taglio dei risultati degli strumenti.
• Contesto: come viene costruito il contesto per i turni dell'agente.
• Hook: hook del ciclo di vita della Compaction (before_compaction, after_compaction).