OpenHands: un agente sviluppatore basato su un modello locale

#Cosa fa, concretamente

Descrivi un'attività in francese. L'agente esamina il repository, prepara un piano, poi agisce in un ciclo: eseguire un comando, leggere il risultato, modificare un file, rieseguire i test, leggere l'esito negativo, correggere. Questo ciclo è il prodotto. È più simile a uno stagista con un terminale che a un completamento automatico.

Ne derivano queste conseguenze. Ogni iterazione è una generazione completa su un contesto che cresce: un'attività in dieci passaggi costa dieci prompt lunghi. E poiché l'agente agisce invece di suggerire, il suo raggio d'azione comprende tutto ciò che può raggiungere — ecco perché la sandbox fa parte della progettazione e non delle impostazioni.

#Il progetto nel 2026: Agent Canvas

OpenHands si chiamava OpenDevin al suo lancio, prima di assumere il nome attuale. Il repository, mantenuto da All Hands AI, è pubblicato sotto licenza MIT e supera le 89.000 stelle su GitHub nell'estate 2026. Il progetto si è anche ampliato: non si presenta più solo come un agente autonomo isolato, ma come «il centro di controllo ospitato in proprio per gli agenti di programmazione e le automazioni», in grado di gestire OpenHands, Claude Code, Codex o Gemini da una sola interfaccia.

In concreto, l'offerta si è articolata in diversi componenti: Agent Canvas (l'interfaccia di controllo), un Software Agent SDK per creare i propri agenti, un Agent Server e un server di automazione per le attività pianificate. La precedente interfaccia locale autonoma è stata deprecata a favore di questa architettura modulare; il principio rimane lo stesso per l'uso locale descritto qui — un agente che opera in una sandbox containerizzata — ma i nomi dei componenti e il comando di avvio possono variare da una vecchia documentazione all'altra, compresa quella che troverai ancora talvolta indicizzata con il nome OpenDevin.

#I requisiti del modello, senza giri di parole

Due capacità contano più dei punteggi dei benchmark: la chiamata di strumenti nel formato esatto previsto e la stabilità con un contesto lungo, poiché l'agente rilegge una cronologia sempre più lunga a ogni passaggio. Un modello eccellente nello scrivere una funzione a partire da un prompt può essere inutilizzabile in un ciclo. In questo esercizio, i modelli orientati al codice superano generalmente i modelli conversazionali della stessa dimensione.

La documentazione ufficiale del progetto ha cambiato raccomandazione nel corso del 2026: ora consiglia Qwen3.6-35B-A3B come primo modello locale da provare, un modello MoE (miscela di esperti) progettato per la programmazione agentica, con un contesto ampio e disponibile tramite LM Studio, Ollama, vLLM e SGLang. Il vantaggio di un MoE in questo caso è immediato: vengono attivati soltanto 3 miliardi di parametri per token, nonostante i 35 miliardi di pesi totali, il che rende la generazione nettamente più veloce rispetto a un modello denso di dimensioni comparabili, con un fabbisogno di VRAM più vicino a quello di un modello 14B che a quello di un 35B denso.

#Eseguirlo in locale

1. 01
   Esporre un modello come servizio

   Su un endpoint compatibile con OpenAI, con la variabile OLLAMA_CONTEXT_LENGTH aumentata ad almeno 22.000 (32.768 consigliato) se usi Ollama. È il passaggio che si salta, e saltarlo produce agenti che dimenticano il proprio piano.
2. 02
   Avviare l'applicazione nella sua configurazione containerizzata

   Ha bisogno di un motore per container (Docker Desktop o Docker Engine): la shell dell'agente viene eseguita lì, non sul tuo host.
3. 03
   Configuralo per usare il tuo endpoint locale

   Con una chiave API fittizia (ad esempio local-llm) e un URL di base raggiungibile dal container — con Docker Desktop, http://host.docker.internal:PORT/v1 anziché localhost, che indicherebbe il container stesso. Dichiara il supporto per le chiamate agli strumenti solo se il modello ne è realmente capace.
4. 04
   Montare un singolo repository

   Idealmente un clone temporaneo, su un branch che puoi eliminare senza remore.
5. 05
   Iniziare con un'attività piccola e verificabile

   Correggi questo test che fallisce, aggiungi questo parametro, aggiorna questa configurazione. Poi leggi di nuovo il diff.

• Mettere a disposizione un modello con un contesto lungo
• Far revisionare il codice a un modello locale
• Cline: l'agente di programmazione integrato nell'editor
• Il kit QuelLLM per costruire un agente locale
• Documentazione ufficiale: modelli locali con OpenHands
• Repository ufficiale OpenHands su GitHub
• Recensione indipendente di OpenHands (2026)

#Il costo reale di un'attività

Un'attività svolta da un agente non richiede una sola chiamata al modello, ma una serie di chiamate, ciascuna su un contesto più lungo del precedente perché la cronologia si accumula. Per un'attività che richiede dieci iterazioni, se ogni passaggio aggiunge in media 800 token alla cronologia, la decima chiamata rilegge già diverse migliaia di token di contesto prima ancora di produrre la risposta. Nel calcolo locale, il tempo di lettura del prompt (il « prefill ») si aggiunge al tempo di generazione a ogni turno: questo spiega perché, con un agente locale basato su un modello da 32 miliardi di parametri, il tempo per attività si misura in minuti, e non in secondi come per un normale completamento.

È il prezzo da pagare per non avere una fattura API: il costo non scompare, si sposta sulla tua scheda grafica e sul tempo di attesa. Quando un compito definito male genera venti iterazioni perché l'agente continua a girare a vuoto, questo costo trasferito diventa rapidamente superiore, in termini di elettricità e tempo, a quello di una chiamata API equivalente.

#Un esempio concreto, per chiarire le idee

Prendiamo un compito realistico: « il test test_export_csv fallisce dall’ultimo commit, correggilo ». Con un modello della classe da 32 miliardi, la sequenza tipica richiede da cinque a otto iterazioni: lettura del test e del messaggio di errore, apertura del file sorgente interessato, ipotesi sulla causa, modifica, nuova esecuzione del test, lettura del nuovo risultato, eventuale aggiustamento. Ogni iterazione rilegge l’intera cronologia delle precedenti, il che rende la finestra di contesto decisiva: con soli 8.000 token, l’agente perde il filo dopo tre o quattro passaggi e ricomincia a formulare ipotesi già scartate.

Con un modello da 7 a 8 miliardi di parametri, la stessa attività fallisce più spesso in modo diverso: il test viene identificato correttamente, ma il comando per rieseguirlo è formulato male, oppure il modello modifica un file vicino con un nome simile. Non si tratta di errori di configurazione: è il limite delle capacità del modello nel rispettare il formato rigoroso richiesto dal ciclo strumento-risultato-decisione, indipendentemente dalla qualità del prompt di sistema. È anche per questo che i punteggi pubblicati nei benchmark di completamento del codice hanno scarso valore predittivo in questo caso: un modello che ottiene un punteggio elevato nella generazione di una funzione isolata può comunque essere incapace di eseguire in sequenza dieci chiamate coerenti agli strumenti senza perdere il filo, perché queste due competenze non sono correlate allo stesso modo a seconda di come è stato addestrato il modello.

#La sicurezza non è opzionale

Nessun segreto nell'ambiente

L'agente legge il proprio ambiente e può mostrarlo.

Un branch usa e getta e un clone di lavoro

Mai una tua copia di lavoro con modifiche non validate.

Accesso alla rete limitato

Un agente che può contattare qualsiasi destinazione può esfiltrare tutto ciò che ha letto.

Ogni contenuto recuperato è ostile per impostazione predefinita

La descrizione di un ticket o un file README possono contenere istruzioni rivolte all'agente: il meccanismo è illustrato nella nostra guida sull'iniezione di prompt.

Rileggere ogni diff

« I test passano » significa che i test passano, non che la modifica sia corretta.

#Quando un assistente è meglio di un agente

In sintesi, OpenHands in locale non è un gadget né un sostituto universale: è uno strumento da riservare alle macchine che possono realmente ospitare un modello da almeno 27 miliardi di parametri con un contesto di 32.000 token, e a compiti abbastanza circoscritti da poter valutare il risultato con un test automatizzato o una rapida revisione. Al di sotto di questa soglia hardware, un assistente conversazionale classico con il file aperto rimane più veloce e più affidabile di un agente che continua a ripetere il ciclo senza mai convergere.

#FAQ