---
read_when:
    - Vuoi capire quali strumenti di sessione ha l'agente
    - Vuoi configurare l'accesso tra sessioni o la generazione di sottoagenti
    - Vuoi ispezionare lo stato o controllare i sottoagenti generati
summary: Strumenti dell'agente per stato tra sessioni, richiamo, messaggistica e orchestrazione di sottoagenti
title: Strumenti di sessione
x-i18n:
    generated_at: "2026-04-23T08:28:07Z"
    model: gpt-5.4
    provider: openai
    source_hash: cd8b545429726d0880e6086ba7190497861bf3f3e1e88d53cb38ef9e5e4468c6
    source_path: concepts/session-tool.md
    workflow: 15
---

# Strumenti di sessione

OpenClaw fornisce agli agenti strumenti per lavorare tra sessioni, ispezionare lo stato e
orchestrare sottoagenti.

## Strumenti disponibili

| Strumento          | Cosa fa                                                                    |
| ------------------ | -------------------------------------------------------------------------- |
| `sessions_list`    | Elenca le sessioni con filtri facoltativi (tipo, etichetta, agente, recenza, anteprima) |
| `sessions_history` | Legge la trascrizione di una sessione specifica                            |
| `sessions_send`    | Invia un messaggio a un'altra sessione e facoltativamente attende          |
| `sessions_spawn`   | Genera una sessione isolata di sottoagente per lavoro in background        |
| `sessions_yield`   | Termina il turno corrente e attende risultati di follow-up dei sottoagenti |
| `subagents`        | Elenca, dirige o termina i sottoagenti generati per questa sessione        |
| `session_status`   | Mostra una scheda in stile `/status` e facoltativamente imposta una sovrascrittura di modello per sessione |

## Elencare e leggere le sessioni

`sessions_list` restituisce sessioni con chiave, agentId, tipo, canale, modello,
conteggi di token e timestamp. Filtra per tipo (`main`, `group`, `cron`, `hook`,
`node`), `label` esatta, `agentId` esatto, testo di ricerca o recenza
(`activeMinutes`). Quando hai bisogno di un triage in stile mailbox, può anche richiedere un
titolo derivato con ambito di visibilità, un frammento di anteprima dell'ultimo messaggio o
messaggi recenti limitati su ogni riga. I titoli derivati e le anteprime vengono prodotti solo per
le sessioni che il chiamante può già vedere in base alla policy di visibilità configurata
degli strumenti di sessione, quindi le sessioni non correlate restano nascoste.

`sessions_history` recupera la trascrizione della conversazione per una sessione specifica.
Per impostazione predefinita, i risultati degli strumenti sono esclusi — passa `includeTools: true` per vederli.
La vista restituita è intenzionalmente limitata e filtrata per sicurezza:

- il testo dell'assistente viene normalizzato prima del richiamo:
  - i tag di ragionamento vengono rimossi
  - i blocchi di scaffolding `<relevant-memories>` / `<relevant_memories>` vengono rimossi
  - i blocchi payload XML di chiamata strumenti in testo semplice come `<tool_call>...</tool_call>`,
    `<function_call>...</function_call>`, `<tool_calls>...</tool_calls>` e
    `<function_calls>...</function_calls>` vengono rimossi, inclusi i payload
    troncati che non si chiudono correttamente
  - lo scaffolding degradato di chiamata/risultato strumento come `[Tool Call: ...]`,
    `[Tool Result ...]` e `[Historical context ...]` viene rimosso
  - i token di controllo del modello trapelati come `<|assistant|>`, altri token ASCII
    `<|...|>` e varianti full-width `<｜...｜>` vengono rimossi
  - XML di chiamata strumenti MiniMax malformato come `<invoke ...>` /
    `</minimax:tool_call>` viene rimosso
- il testo simile a credenziali/token viene redatto prima di essere restituito
- i blocchi di testo lunghi vengono troncati
- cronologie molto grandi possono eliminare righe più vecchie o sostituire una riga troppo grande con
  `[sessions_history omitted: message too large]`
- lo strumento riporta flag di riepilogo come `truncated`, `droppedMessages`,
  `contentTruncated`, `contentRedacted` e `bytes`

Entrambi gli strumenti accettano sia una **chiave di sessione** (come `"main"`) sia un **ID sessione**
da una precedente chiamata list.

Se hai bisogno della trascrizione esatta byte per byte, ispeziona il file della trascrizione su
disco invece di trattare `sessions_history` come un dump grezzo.

## Inviare messaggi tra sessioni

`sessions_send` consegna un messaggio a un'altra sessione e facoltativamente attende la
risposta:

- **Fire-and-forget:** imposta `timeoutSeconds: 0` per accodare e restituire
  immediatamente.
- **Attendere la risposta:** imposta un timeout e ottieni la risposta inline.

Dopo che la destinazione risponde, OpenClaw può eseguire un **ciclo di risposta reciproca** in cui gli
agenti alternano messaggi (fino a 5 turni). L'agente di destinazione può rispondere
`REPLY_SKIP` per fermarsi in anticipo.

## Helper di stato e orchestrazione

`session_status` è lo strumento leggero equivalente a `/status` per la sessione corrente
o per un'altra sessione visibile. Riporta utilizzo, tempo, stato del modello/runtime e
contesto collegato delle attività in background quando presente. Come `/status`, può riempire
retroattivamente contatori sparsi di token/cache dall'ultima voce di utilizzo della trascrizione, e
`model=default` cancella una sovrascrittura per sessione.

`sessions_yield` termina intenzionalmente il turno corrente in modo che il messaggio successivo possa essere
l'evento di follow-up che stai aspettando. Usalo dopo aver generato sottoagenti quando
vuoi che i risultati di completamento arrivino come messaggio successivo invece di costruire loop di polling.

`subagents` è l'helper del piano di controllo per sottoagenti OpenClaw già generati.
Supporta:

- `action: "list"` per ispezionare esecuzioni attive/recenti
- `action: "steer"` per inviare guida di follow-up a un figlio in esecuzione
- `action: "kill"` per fermare un figlio o `all`

## Generare sottoagenti

`sessions_spawn` crea una sessione isolata per un'attività in background. È sempre
non bloccante — restituisce immediatamente con un `runId` e una `childSessionKey`.

Opzioni principali:

- `runtime: "subagent"` (predefinito) oppure `"acp"` per agenti con harness esterno.
- Sovrascritture `model` e `thinking` per la sessione figlia.
- `thread: true` per collegare la generazione a un thread di chat (Discord, Slack, ecc.).
- `sandbox: "require"` per imporre la sandbox sul figlio.

I sottoagenti foglia predefiniti non ricevono strumenti di sessione. Quando
`maxSpawnDepth >= 2`, i sottoagenti orchestratori di profondità 1 ricevono inoltre
`sessions_spawn`, `subagents`, `sessions_list` e `sessions_history` così
possono gestire i propri figli. Le esecuzioni foglia continuano a non ricevere strumenti di
orchestrazione ricorsiva.

Dopo il completamento, un passaggio di annuncio pubblica il risultato sul canale del richiedente.
La consegna del completamento preserva l'instradamento legato a thread/topic quando disponibile, e se
l'origine del completamento identifica solo un canale OpenClaw può comunque riusare il percorso memorizzato della sessione richiedente (`lastChannel` / `lastTo`) per una consegna
diretta.

Per il comportamento specifico ACP, vedi [ACP Agents](/it/tools/acp-agents).

## Visibilità

Gli strumenti di sessione sono limitati per ridurre ciò che l'agente può vedere:

| Livello | Ambito                                   |
| ------- | ---------------------------------------- |
| `self`  | Solo la sessione corrente                |
| `tree`  | Sessione corrente + sottoagenti generati |
| `agent` | Tutte le sessioni per questo agente      |
| `all`   | Tutte le sessioni (cross-agent se configurato) |

Il valore predefinito è `tree`. Le sessioni in sandbox sono limitate a `tree` indipendentemente dalla
configurazione.

## Ulteriori letture

- [Gestione delle sessioni](/it/concepts/session) -- instradamento, ciclo di vita, manutenzione
- [ACP Agents](/it/tools/acp-agents) -- generazione con harness esterno
- [Multi-agent](/it/concepts/multi-agent) -- architettura multi-agente
- [Configurazione del Gateway](/it/gateway/configuration) -- manopole di configurazione degli strumenti di sessione
