Gestione delle sessioni

OpenClaw instrada ogni messaggio in entrata verso una sessione in base alla sua provenienza: messaggi diretti, chat di gruppo, processi Cron, ecc. L'intero stato della sessione è gestito dal Gateway; i client dell'interfaccia utente interrogano il Gateway per ottenere i dati della sessione.

Come vengono instradati i messaggi

Isolamento dei messaggi diretti

Per impostazione predefinita, tutti i messaggi diretti condividono una sessione per garantire la continuità, soluzione adatta alle configurazioni con un solo utente.

{  session: {    dmScope: "per-channel-peer", // isola per canale + mittente  },}

Opzioni di session.dmScope:

Ancoraggio dei canali collegati

I comandi di ancoraggio spostano il percorso di risposta della sessione corrente della chat diretta verso un altro canale collegato senza avviare una nuova sessione. Consultare Ancoraggio dei canali per esempi, configurazione e risoluzione dei problemi.

Verificare la configurazione con openclaw security audit.

Ciclo di vita della sessione

Le sessioni vengono riutilizzate finché non scadono in base a session.reset:

• Reimpostazione giornaliera (mode: "daily" per impostazione predefinita) - nuova sessione a un'ora locale configurata (session.reset.atHour, valore predefinito 4, 0-23) sull'host del Gateway. La validità giornaliera si basa sul momento in cui è iniziato l'sessionId corrente, non sulle successive scritture dei metadati.
• Reimpostazione per inattività (mode: "idle") - nuova sessione dopo session.reset.idleMinutes di inattività. La validità per inattività si basa sull'ultima interazione effettiva dell'utente o del canale, quindi gli eventi di sistema Heartbeat, Cron ed exec non mantengono attiva la sessione.
• Reimpostazione manuale - digitare /new o /reset nella chat. /new <model> cambia anche il modello.

Quando sono configurate sia la reimpostazione giornaliera sia quella per inattività, prevale quella che scade per prima. Le interazioni di Heartbeat, Cron, exec e di altri eventi di sistema possono scrivere metadati della sessione, ma tali scritture non prolungano la validità della reimpostazione giornaliera o per inattività. Quando una reimpostazione rinnova la sessione, le notifiche degli eventi di sistema in coda per la sessione precedente vengono eliminate, in modo che gli aggiornamenti obsoleti in background non vengano anteposti al primo prompt della nuova sessione.

Le sessioni con una sessione CLI attiva gestita dal provider non vengono interrotte dall'impostazione giornaliera predefinita implicita. Utilizzare /reset o configurare esplicitamente session.reset quando tali sessioni devono scadere in base a un timer.

Sostituire l'impostazione predefinita per tipo di chat o per canale:

{  session: {    reset: { mode: "daily", atHour: 4 },    resetByType: {      group: { mode: "idle", idleMinutes: 120 },      thread: { mode: "daily", atHour: 6 },    },    resetByChannel: {      discord: { mode: "idle", idleMinutes: 10080 },    },  },}

resetByType supporta direct (alias legacy dm), group e thread. Il valore legacy di primo livello session.idleMinutes continua a funzionare come alias di compatibilità per un'impostazione predefinita in modalità inattività quando non è definito alcun blocco session.reset/resetByType.

Dove risiede lo stato

• Righe delle sessioni di runtime: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• File delle trascrizioni archiviate: ~/.openclaw/agents/<agentId>/sessions/
• Origine della migrazione delle righe legacy: ~/.openclaw/agents/<agentId>/sessions/sessions.json

Le righe delle sessioni nel database SQLite di ciascun agente conservano timestamp distinti del ciclo di vita:

• sessionStartedAt: momento in cui è iniziato l'sessionId corrente; viene utilizzato dalla reimpostazione giornaliera.
• lastInteractionAt: ultima interazione dell'utente o del canale che prolunga la durata per inattività.
• updatedAt: ultima modifica della riga nell'archivio; utile per elenchi ed eliminazioni, ma non determinante per la validità della reimpostazione giornaliera o per inattività.

Durante la migrazione da installazioni precedenti, l'avvio del Gateway e openclaw doctor --fix importano automaticamente in SQLite le righe legacy sessions.json e la cronologia attiva delle trascrizioni JSONL. Le righe prive di sessionStartedAt vengono risolte dall'intestazione della sessione nella trascrizione JSONL legacy, quando disponibile. Se una riga precedente è priva anche di lastInteractionAt, la validità per inattività utilizza come ripiego l'ora di inizio della sessione, non le successive scritture amministrative. Utilizzare openclaw doctor --session-sqlite inspect --session-sqlite-all-agents e la Sequenza di migrazione di Doctor quando si desiderano prove esplicite di ispezione o convalida.

Manutenzione delle sessioni

OpenClaw limita nel tempo l'archiviazione delle sessioni tramite session.maintenance; di seguito sono riportati i valori predefiniti:

{  session: {    maintenance: {      mode: "enforce", // "enforce" applica la pulizia; "warn" genera solo un rapporto      pruneAfter: "30d",      maxEntries: 500,    },  },}

Per limiti maxEntries adatti ad ambienti di produzione, le scritture del runtime del Gateway utilizzano un piccolo buffer di soglia massima ed eseguono la pulizia in batch fino al limite configurato. Le letture dell'archivio delle sessioni non eliminano né limitano le voci durante l'avvio del Gateway, quindi l'avvio e le sessioni Cron isolate non sostengono il costo di una pulizia completa dell'archivio. openclaw sessions cleanup --enforce applica immediatamente il limite.

Le sessioni di controllo delle esecuzioni del modello del Gateway hanno per impostazione predefinita una durata breve. Le righe corrispondenti a agent:*:explicit:model-run-<uuid> utilizzano una conservazione fissa di 24h, ma la pulizia è vincolata alla pressione: rimuove le righe di controllo obsolete solo quando viene raggiunta la pressione dovuta alla manutenzione o al limite delle voci di sessione e viene eseguita prima del più ampio limite temporale per le voci obsolete e del limite delle voci. Le normali sessioni dirette, di gruppo, thread, Cron, hook, Heartbeat, ACP e dei sotto-agenti non ereditano questa conservazione di 24h.

La manutenzione conserva i riferimenti durevoli alle conversazioni esterne, incluse le sessioni di gruppo e le sessioni di chat circoscritte ai thread, consentendo comunque alle voci sintetiche di Cron, hook, Heartbeat, ACP e dei sotto-agenti di scadere.

Se in precedenza era utilizzato l'isolamento dei messaggi diretti e in seguito session.dmScope è stato riportato a main, visualizzare in anteprima le righe obsolete dei messaggi diretti indicizzate per peer con openclaw sessions cleanup --dry-run --fix-dm-scope. L'applicazione dello stesso flag ritira tali vecchie righe dei messaggi diretti e conserva le relative trascrizioni come archivi eliminati.

Visualizzare in anteprima qualsiasi esecuzione di manutenzione con openclaw sessions cleanup --dry-run.

Ispezione delle sessioni

Ulteriori letture

• Ricerca nelle sessioni - ricerca full-text nelle trascrizioni precedenti
• Eliminazione dei dati delle sessioni - riduzione dei risultati degli strumenti
• Compaction - riepilogo delle conversazioni lunghe
• Strumenti per le sessioni - strumenti dell'agente per operazioni tra sessioni
• Approfondimento sulla gestione delle sessioni - schema dell'archivio, trascrizioni, criteri di invio, metadati di origine e configurazione avanzata
• Multi-agente - instradamento e isolamento delle sessioni tra agenti
• Attività in background - come il lavoro separato crea record di attività con riferimenti alle sessioni
• Instradamento dei canali - come i messaggi in entrata vengono instradati verso le sessioni

Contenuti correlati

• Eliminazione dei dati delle sessioni
• Strumenti per le sessioni
• Coda dei comandi