Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Strumenti disponibili

StrumentoCosa fa
sessions_listElenca le sessioni con filtri opzionali (tipo, etichetta, agente, recenza, anteprima)
sessions_historyLegge la trascrizione di una sessione specifica
sessions_sendInvia un messaggio a un’altra sessione e, facoltativamente, attende
sessions_spawnAvvia una sessione di sotto-agente isolata per lavoro in background
sessions_yieldTermina il turno corrente e attende risultati successivi dai sotto-agenti
subagentsElenca, guida o termina i sotto-agenti avviati per questa sessione
session_statusMostra una scheda in stile /status e, facoltativamente, imposta un override del modello per sessione
Questi strumenti sono comunque soggetti al profilo strumenti attivo e alla policy di autorizzazione/negazione. tools.profile: "coding" include l’intero set di orchestrazione delle sessioni, inclusi sessions_spawn, sessions_yield e subagents. tools.profile: "messaging" include strumenti di messaggistica tra sessioni (sessions_list, sessions_history, sessions_send, session_status) ma non include l’avvio di sotto-agenti. Per mantenere un profilo di messaggistica e consentire comunque la delega nativa, aggiungi: 
{
  tools: {
    profile: "messaging",
    alsoAllow: ["sessions_spawn", "sessions_yield", "subagents"],
  },
}
Le policy di gruppo, provider, sandbox e per agente possono comunque rimuovere questi strumenti dopo la fase del profilo. Usa /tools dalla sessione interessata per ispezionare l’elenco effettivo degli strumenti.

​
Elencare e leggere le sessioni

sessions_list restituisce le sessioni con la loro chiave, agentId, tipo, canale, modello, conteggi dei token e timestamp. Filtra per tipo (main, group, cron, hook, node), label esatta, agentId esatto, testo di ricerca o recenza (activeMinutes). Quando serve un triage in stile casella di posta, può anche richiedere un titolo derivato con visibilità limitata, uno snippet di anteprima dell’ultimo messaggio o messaggi recenti limitati per ogni riga. I titoli derivati e le anteprime vengono prodotti solo per le sessioni che il chiamante può già vedere secondo la policy di visibilità configurata per gli 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 recupero:
    • i tag di ragionamento vengono rimossi
    • i blocchi di scaffolding <relevant-memories> / <relevant_memories> vengono rimossi
    • i blocchi payload XML di chiamate strumento 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 declassato di chiamate/risultati strumento come [Tool Call: ...], [Tool Result ...] e [Historical context ...] viene rimosso
    • i token di controllo del modello trapelati come <|assistant|>, altri token ASCII <|...|> e le varianti a larghezza piena <｜...｜> vengono rimossi
    • XML di chiamata strumento MiniMax malformato come <invoke ...> / </minimax:tool_call> viene rimosso
  • il testo simile a credenziali/token viene oscurato prima di essere restituito
  • i blocchi di testo lunghi vengono troncati
  • cronologie molto grandi possono eliminare righe più vecchie o sostituire una riga sovradimensionata con [sessions_history omitted: message too large]
  • lo strumento riporta flag di riepilogo come truncated, droppedMessages, contentTruncated, contentRedacted e bytes
Entrambi gli strumenti accettano una chiave di sessione (come "main") o un ID sessione da una chiamata di elenco precedente. Se ti serve la 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:
  • Invio senza attesa: imposta timeoutSeconds: 0 per accodare e restituire immediatamente.
  • Attesa della risposta: imposta un timeout e ottieni la risposta inline.
Le sessioni di chat con ambito di thread, come chiavi Slack o Discord che terminano con :thread:<id>, non sono destinazioni sessions_send valide. Usa la chiave di sessione del canale padre per il coordinamento tra agenti, così i messaggi instradati tramite strumento non compaiono dentro un thread attivo rivolto a utenti umani. I messaggi e le risposte successive A2A sono marcati come dati tra sessioni nel prompt ricevente ([Inter-session message ... isUser=false]) e nella provenienza della trascrizione. L’agente ricevente dovrebbe trattarli come dati instradati tramite strumento, non come un’istruzione scritta direttamente dall’utente finale. Dopo che la destinazione risponde, OpenClaw può eseguire un ciclo di risposta di ritorno in cui gli agenti alternano i messaggi (fino a session.agentToAgent.maxPingPongTurns, intervallo 0-20, valore predefinito 5). L’agente di destinazione può rispondere REPLY_SKIP per interrompere 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 uso, ora, stato del modello/runtime e contesto dei task in background collegati quando presente. Come /status, può retrocompilare contatori di token/cache sparsi dall’ultima voce di utilizzo della trascrizione, e model=default cancella un override per sessione. Usa sessionKey="current" per la sessione corrente del chiamante; le etichette client visibili come openclaw-tui non sono chiavi di sessione. sessions_yield termina intenzionalmente il turno corrente così il messaggio successivo può essere l’evento di follow-up che stai attendendo. Usalo dopo l’avvio di sotto-agenti quando vuoi che i risultati di completamento arrivino come messaggio successivo invece di costruire cicli di polling. subagents è l’helper del piano di controllo per sotto-agenti OpenClaw già avviati. Supporta:
  • action: "list" per ispezionare esecuzioni attive/recenti
  • action: "steer" per inviare indicazioni successive a un figlio in esecuzione
  • action: "kill" per arrestare un figlio o all

​
Avviare sotto-agenti

sessions_spawn crea per impostazione predefinita una sessione isolata per un task in background. È sempre non bloccante: restituisce immediatamente un runId e una childSessionKey. Opzioni principali:
  • runtime: "subagent" (valore predefinito) o "acp" per agenti di harness esterni.
  • Override di model e thinking per la sessione figlia.
  • thread: true per associare l’avvio a un thread di chat (Discord, Slack, ecc.).
  • sandbox: "require" per imporre il sandboxing al figlio.
  • context: "fork" per sotto-agenti nativi quando il figlio ha bisogno della trascrizione corrente del richiedente; omettilo o usa context: "isolated" per un figlio pulito. I sotto-agenti nativi vincolati a thread usano context: "fork" per impostazione predefinita, salvo diversa indicazione di threadBindings.defaultSpawnContext.
I sotto-agenti foglia predefiniti non ricevono strumenti di sessione. Quando maxSpawnDepth >= 2, i sotto-agenti orchestratori di profondità 1 ricevono inoltre sessions_spawn, subagents, sessions_list e sessions_history così possono gestire i propri figli. Le esecuzioni foglia non ricevono comunque strumenti di orchestrazione ricorsiva. Dopo il completamento, un passaggio di annuncio pubblica il risultato nel canale del richiedente. La consegna del completamento preserva il routing di thread/argomento associato quando disponibile e, se l’origine del completamento identifica solo un canale, OpenClaw può comunque riutilizzare la route memorizzata della sessione del richiedente (lastChannel / lastTo) per la consegna diretta. Per il comportamento specifico di ACP, vedi Agenti ACP.

​
Visibilità

Gli strumenti di sessione hanno ambito limitato per restringere ciò che l’agente può vedere:
LivelloAmbito
selfSolo la sessione corrente
treeSessione corrente + sotto-agenti avviati
agentTutte le sessioni per questo agente
allTutte le sessioni (tra agenti se configurato)
Il valore predefinito è tree. Le sessioni in sandbox sono limitate a tree indipendentemente dalla configurazione.

​
Ulteriori letture

​
Correlati