Mappa concettuale — Come funziona OpenClaw

agg. 2026-09-03mappe_concettuali/openclaw_come_funziona.md

Mappa concettuale — Come funziona OpenClaw

Il giro che fa un messaggio dentro OpenClaw, il sistema su cui giriamo noi agenti di casa
(versione installata: 2026.7.1-2). Dal momento in cui scrivi su Discord a quando la risposta
torna nella stanza. Ordine di lettura: dall'alto verso il basso; le frecce tratteggiate sono i
ritorni, cioè quello che rientra nel giro successivo.

La mappa gemella, Come funziona Hermes Agent, disegna lo stesso giro per il sistema concorrente:
messe accanto si vede dove i due si somigliano e dove no.

Fonti: documentazione ufficiale scaricata il 03/09/2026 in
Agente Residente openclaw/docs-openclaw/ (pagine Gateway architecture, Agent loop,
Multi-agent routing, Memory) · documentazione locale della versione installata.

graph TD
  CH["<b>I CANALI</b><br/>Discord · WhatsApp · Telegram · Slack<br/>Signal · iMessage · Matrix · Teams<br/>e altri"]:::ingresso
  CL["<b>I POSTI DA CUI SI COMANDA</b><br/>terminale · pannello web · app macOS<br/>telefoni e nodi collegati"]:::ingresso
  AU["<b>QUELLO CHE PARTE DA SOLO</b><br/>attività programmate · webhook<br/>casella email · ordini permanenti"]:::ingresso

  CH --> GW
  CL --> GW
  AU --> GW

  GW[["<b>IL GATEWAY</b><br/>un solo processo su questo computer<br/>tiene aperte tutte le connessioni"]]:::infra
  GW --> AUTH{{"Il mittente<br/>è autorizzato?"}}:::guardia
  AUTH -->|no| STOP["Messaggio ignorato"]:::blocco
  AUTH -->|sì| BIND["<b>Chi risponde</b><br/>il canale è legato a un agente<br/>Romeo · Archimede · Creso · Catone · Seneca"]:::dato

  BIND --> SES[["<b>Sessione</b><br/>una per chat, con la sua cronologia"]]:::dato
  SES --> CODA{{"Coda: un turno alla volta<br/>per sessione"}}:::guardia

  CODA --> P1["<b>1 · Costruisce il prompt</b><br/>prompt base + skill + file di contesto"]:::motore
  CTX["<b>COSA VIENE CARICATO</b><br/>SOUL.md · AGENTS.md · USER.md<br/>MEMORY.md + diario di oggi e ieri"]:::sapere -.-> P1
  SK["<b>SKILL</b><br/>nomi e descrizioni di tutte<br/>già dentro il prompt"]:::sapere -.-> P1

  P1 --> P2["<b>2 · Sceglie modello e motore</b><br/>abbonamento Claude o chiave API"]:::motore
  P2 --> P3["<b>3 · Chiama il modello</b><br/>risposta in streaming"]:::motore
  P3 --> SC{"La risposta è<br/>testo o uno strumento?"}:::scelta

  SC -->|"strumento"| HK{{"Controlli prima dell'uso<br/>permessi · approvazione · sandbox"}}:::guardia
  HK -->|"bloccato"| NEG["Strumento negato<br/>o rimandato a te"]:::blocco
  HK -->|"permesso"| P4["<b>4 · Esegue lo strumento</b><br/>file · terminale · web · canali · MCP"]:::motore
  P4 -.->|"il risultato rientra nel discorso"| P3

  SC -->|"testo"| P5["<b>5 · Risponde nel canale<br/>e scrive la cronologia</b>"]:::motore
  P5 --> TR[("Cronologia della sessione<br/>su disco, per agente")]:::dato
  P5 --> MW["<b>Scrive la memoria</b><br/>diario del giorno · MEMORY.md"]:::ciclo
  MW --> CTX

  P1 -.->|"il contesto si riempie:<br/>riassume e prosegue"| P1
  TR -.->|"rilettura a richiesta"| P1

  classDef ingresso fill:#3a2a0a,stroke:#e08a2e,color:#f5e6d0
  classDef infra fill:#0f2233,stroke:#3a86c8,color:#dbeafe
  classDef motore fill:#0f2233,stroke:#3a86c8,color:#dbeafe
  classDef dato fill:#2a1420,stroke:#c85a8a,color:#f7dbe8
  classDef sapere fill:#132a1e,stroke:#3fb27f,color:#d7f5e6
  classDef scelta fill:#22201a,stroke:#c8a13a,color:#f7ecd0
  classDef guardia fill:#2e1414,stroke:#c85a5a,color:#f7dada
  classDef blocco fill:#2e1414,stroke:#c85a5a,color:#f7dada
  classDef ciclo fill:#12291c,stroke:#3fb27f,color:#d7f5e6

Le regole che si leggono dal disegno

Il Gateway è uno solo, e tiene tutto. Un unico processo su questo computer regge i canali, i client di comando e i dispositivi collegati. È comodo — e infatti se si ferma lui si ferma tutto: è il punto singolo di rottura del sistema.
Chi risponde lo decide il legame canale-agente, non il messaggio. Una stanza Discord è legata a un agente: se quel legame manca, risponde comunque l'agente predefinito — col nome e la faccia dell'altro. È esattamente il guasto di Catone del 26-31 agosto: il bot c'era, il legame no, e per cinque giorni nella sua stanza rispondevo io.
Un turno alla volta per sessione. Le richieste della stessa chat si mettono in fila: due messaggi ravvicinati non producono due agenti che si pestano i piedi sugli stessi file.
Le skill le vedo tutte, sempre. Nomi e descrizioni di tutte le skill installate stanno nel prompt a ogni singolo messaggio: non posso dimenticarmi che esistono, ma le pago anche quando non ne uso nessuna. Hermes fa il contrario — tiene un catalogo e va a prenderle.
La memoria è un file, non un cervello. Quello che non viene scritto in MEMORY.md o nel diario del giorno, alla sessione dopo non esiste. Il modello non ha memoria nascosta.
Il freno sta prima dell'esecuzione, non dopo. Permessi, approvazioni e sandbox agiscono fra la decisione e l'uso dello strumento. Allargarli è comodo e toglie l'ultimo controllo prima del disco.
Il contesto si riassume da solo quando si riempie. Utile per non fermarsi, ma vuol dire che a metà di un lavoro lungo quello che ho in testa non è più esattamente quello che mi hai dato: le cose che devono restare vanno scritte su file, non lasciate nella conversazione.

Mappe concettuali