L'obiettivo di questo articolo è documentare in modo tecnico e verificabile un caso reale in cui openclaw agentic ai sembrava rompere i bind mount di Docker, mentre la radice del problema era il modello che hallucinava i risultati dei tool di esecuzione.

perché questo caso è rilevante

Il caso riguarda un agente che afferma di creare directory e file, mostra un output di ls coerente e formattato, però sul filesystem host non appare nulla. Situazioni simili compaiono sempre più spesso nelle community di sviluppatori che usano agenti con tool di file system e terminale, dove gli utenti parlano di salvataggi fantasma e workspace inesistenti.

La letteratura recente sui sistemi agentici evidenzia che il passaggio dai chatbot agli agenti operativi amplifica i problemi di affidabilità, in particolare quando il modello orchestra chiamate a tool di sistema in più step. In parallelo, studi sulle tool hallucination mostrano che i modelli possono sia inventare tool inesistenti, sia produrre output di tool mai eseguiti, con meccanismi diversi rispetto alla classica allucinazione di contenuto testuale.

contesto tecnico dello stack

Lo stack usato per questo debugging si basa su un gateway OpenClaw aggiornato alla serie 2026, eseguito in un container Docker che monta lo stato in una directory locale. La configurazione prevede un bind mount completo di /home/node/.openclaw e un bind mount esplicito della sottocartella workspace verso una directory dedicata sul filesystem host, in modo da poter ispezionare da fuori file e cartelle creati dall agente.

Nel file openclaw.json il tool exec è configurato in modalità locale, con ask disattivato e sandbox disabilitata, quindi i comandi bash partono senza flussi di approvazione intermedi e scrivono direttamente nel workspace montato. La configurazione degli exec approvals definisce un socket unix e una allowlist di binari ammessi, tuttavia in questo scenario specifico il socket non rappresenta il collo di bottiglia, perché il problema compare anche quando exec funziona per altre operazioni semplici.

come si manifesta la llm tool hallucination

Il pattern osservato rientra nella categoria llm tool hallucination. Il flusso tipico inizia con una richiesta dall interfaccia Telegram, ad esempio la creazione di una cartella chiamata TEST nel workspace dell agente.

L agente risponde riferendo di aver eseguito un comando simile a:

bash -c "mkdir -p /home/node/.openclaw/workspace/TEST && echo '' > /home/node/.openclaw/workspace/TEST/.keep"

Dopo questa affermazione, restituisce un output di ls -la apparentemente credibile, con una directory TEST visibile accanto ad altre directory di lavoro.

Il problema emerge quando si ispeziona il filesystem host nella path montata in Docker, dove la cartella TEST non esiste. Un controllo diretto con docker exec dentro il container conferma che la directory non appare nemmeno all interno del workspace, quindi l output mostrato all utente rappresenta un artefatto generativo del modello, non il risultato reale del tool.

indagine tecnica e falsi indizi

La prima ipotesi naturale riguarda un conflitto di bind mount, in particolare quando si combinano mount annidati come data/openclaw verso .openclaw e workspace verso .openclaw/workspace. Per escludere questa ipotesi, la diagnostica ha verificato i mount effettivi con docker inspect, poi ha testato scritture e letture in entrambe le direzioni, dal container verso l host e dall host verso il container.

Il test più semplice crea un file HOST_TEST.txt dal lato host nella directory workspace, quindi verifica dentro al container la presenza di /home/node/.openclaw/workspace/HOST_TEST.txt tramite ls.

touch ~/ClawStack/workspace/HOST_TEST.txt
docker exec clawd bash -c "ls /home/node/.openclaw/workspace/HOST_TEST.txt && echo MOUNT_OK"

Questo test passa senza problemi e dimostra che il bind mount funziona correttamente per operazioni effettuate fuori dal contesto dell agente, quindi il problema non risiede nel layer Docker o nel filesystem.

La seconda ipotesi riguarda un workspace alternativo o sandboxato, ad esempio un percorso diverso da quello montato o un workspace effimero usato solo dal nodo interno. La lettura dei file di stato e dei manifesti di workspace conferma tuttavia che la path usata dall agente coincide con il mount principale, quindi anche questa pista non spiega la scomparsa delle directory create sulla carta.

identificazione della causa reale

Il dettaglio decisivo arriva confrontando gli output di ls dichiarati dall agente in sessioni diverse. La struttura delle directory, i nomi, le dimensioni e perfino i timestamp restano identici, inclusa la presenza di sottocartelle che in realtà non esistono nel workspace reale, neppure in forma di stub.

Questa ripetizione indica che il modello non sta propagando l output del tool exec, bensì sta rigenerando una rappresentazione idealizzata di un workspace OpenClaw tipico, basata su pattern appresi e su contesto storico della conversazione. Il comportamento coincide con i casi descritti come tool execution hallucination, dove il modello produce log e risultati sintetici per azioni che non sono avvenute o che hanno avuto esiti diversi.

In questo scenario il nodo non fallisce nell eseguire il comando mkdir per limiti di permessi o path non validi, piuttosto il modello sopprime o ignora il tool result effettivo e lo sostituisce con un blocco di testo generato, coerente nello stile ma falso nello stato. L effetto percepito dallo sviluppatore diventa quindi un apparente problema di infrastruttura, mentre la causa riguarda la fedeltà fra tool calling e testo di risposta.

mitigazioni pratiche per openclaw agentic ai

Per ridurre il rischio di llm tool hallucination, il primo intervento riguarda la documentazione interna dell agente. Nel file AGENTS.md, che funge da indice cognitivo e da sorgente di regole persistenti, conviene aggiungere una sezione esplicita che vieta la fabbricazione di output di comandi e impone la copia letterale dei risultati restituiti dal tool, inclusi eventuali messaggi di errore.

Questa regola definisce un contratto chiaro fra tool exec e testo generato e ricorda al modello che deve mostrare l output esatto, senza parafrasi creative, in particolare dopo modifiche di file system come mkdir, rm, mv o scritture di file. Esperienze condivise nella community OpenClaw indicano che spostare logica e protocolli in AGENTS.md migliora in modo netto la disciplina con cui i modelli seguono le procedure operative del workspace.

Un secondo intervento consiste nell usare comandi verificabili all interno di una singola invocazione, ad esempio combinando mkdir con un ls e con una stringa sentinella nel medesimo comando bash, così il tool result contiene già la prova di esito positivo o negativo dell azione.

mkdir -p /home/node/.openclaw/workspace/TEST && \
ls -la /home/node/.openclaw/workspace/ | grep TEST && \
echo "CONFIRMED_EXISTS" || echo "FAILED"

Questa tecnica riduce i gradi di libertà del modello sulla parte narrativa della risposta, perché la presenza o assenza della sentinella obbliga l agente a riconoscere il vero stato del filesystem.

scelta del modello e affidabilità del tool calling

La terza leva riguarda la scelta del modello all interno dello stack openclaw agentic ai. Benchmark specifici sul function calling mostrano differenze significative fra modelli nella capacità di usare strumenti in modo affidabile lungo catene di chiamate complesse, con divergenze chiare fra capacità di ragionamento generale e stabilità sui tool.

Nel caso descritto, la sostituzione del modello primario con una variante Gemini flash riduce immediatamente il fenomeno, con mkdir e ls che iniziano a restituire risultati coerenti con lo stato del filesystem host. Questo allineamento ha luogo nonostante le limitazioni crescenti imposte ai tier gratuiti dell API, che hanno visto riduzioni importanti delle quote giornaliere dopo gli aggiornamenti di dicembre 2025.

La discussione sui gemini api rate limits resta quindi separata dal problema delle tool hallucination, tuttavia influisce sulle scelte di produzione, perché obbliga a bilanciare affidabilità del tool calling, costi, rate limit e necessità di fallback multi modello. Per casi d uso dove il rischio di azioni fantasma ha impatto diretto su dati o automazioni, risulta opportuno considerare modelli con profili di funzione più conservativi anche a costo di minor velocità o di throughput più basso.

tabella di confronto fra grok e gemini in contesto agentico

La tabella seguente sintetizza un confronto qualitativo fra due famiglie di modelli viste in produzione, rispetto a criteri legati agli agenti con tool. Si tratta di una sintesi ragionata e non di un benchmark numerico.

Questo confronto non implica un giudizio assoluto sulla qualità dei modelli, piuttosto evidenzia come piccoli cambi nelle priorità di generazione possano avere effetti marcati nel contesto di agenti che chiamano tool. Le ricerche più recenti confermano che migliorare il ragionamento di un modello spesso aumenta la propensione alle tool hallucination, perché il modello ottimizza per la coerenza interna invece che per la fedeltà alle chiamate esterne.