Come Usare AI OpenHands: Una Guida Pratica a Configurazione, Prompt e Workflow Reali
Se hai mai desiderato di poter programmare in coppia con un bravo sviluppatore 24 ore su 24, 7 giorni su 7, AI OpenHands ci si avvicina in modo sorprendente. È un "ingegnere AI" open-source che può leggere il tuo repository, scrivere codice, eseguire terminali, consultare documentazione e iterare, proprio come uno sviluppatore junior che impara velocemente e lavora instancabilmente. Ma la sua potenza si rivela solo quando lo configuri correttamente e impari a guidarlo.
Questa guida ti accompagna passo dopo passo nell'uso di AI OpenHands, dall'installazione ai workflow avanzati, in modo da poter rilasciare più velocemente con sicurezza.
- Opzioni di installazione e avvio rapido
- Esecuzione di OpenHands localmente o con modelli cloud
- Best practice per prompt, repository e task
- Workflow comprovati per feature, debugging, test e documentazione
- Misure di sicurezza, privacy e collaborazione
Vale la pena notare: OpenHands è attivamente sviluppato dal team di All Hands e dalla comunità. La documentazione ufficiale è la tua stella polare per istruzioni e suggerimenti aggiornati. Puoi anche seguire guide pratiche all'installazione da professionisti che hanno documentato configurazioni locali e su VM. Per l'esecuzione con modelli locali, la documentazione include anche indicazioni specifiche.
Cos'è AI OpenHands e perché usarlo?
Pensa ad AI OpenHands come a un compagno di squadra AI con una tastiera. A differenza degli assistenti basati solo sulla chat, OpenHands può:
- Aprire e leggere file di progetto
- Utilizzare un terminale per eseguire comandi, test e linters
- Modificare il codice in file e directory
- Navigare sul web (a seconda della configurazione)
- Proporre e applicare piani passo dopo passo
Questo lo rende ideale per task come implementare feature, correggere bug, scrivere test, creare documentazione, refactoring e modernizzare codebase. Invece di destreggiarti tra prompt e copia/incolla, dai a OpenHands un obiettivo e lascialo iterare, supervisionando le sue mosse.
Avvio Rapido: Il Modo Più Veloce per Usare OpenHands
Ci sono diversi modi per iniziare. La tua scelta dipende dal fatto che tu voglia utilizzare un LLM cloud o eseguire tutto localmente.
Opzione A: Usa un LLM Cloud (più facile)
- Segui la documentazione ufficiale "Start Building" e "Getting Started" per installare ed eseguire l'app. In genere dovrai:
- Installare i prerequisiti (Docker, Node, Python, Git a seconda del percorso)
- Fornire una chiave API per un modello cloud supportato (ad esempio, OpenAI, Anthropic o altri supportati dal progetto al momento)
- Avviare l'interfaccia di OpenHands e connettere il tuo repository
Questo percorso ti permette di essere produttivo rapidamente con un overhead di calcolo minimo.
Opzione B: Esegui OpenHands con un LLM Locale
- Se preferisci mantenere il codice e i prompt fuori dal cloud o vuoi evitare i costi delle API, usa la guida Local LLMs nella documentazione ufficiale.
- Configurare un modello locale compatibile (tramite Ollama o altri backend supportati al momento)
- Configurare gli endpoint del modello e i limiti di contesto
- Assicurarti che la tua macchina abbia VRAM/CPU e spazio su disco adeguati
Opzione C: Distribuisci su una VM
- Se hai bisogno di un ambiente dedicato, i professionisti hanno documentato come avviare OpenHands su una VM e creare un'app in pochi minuti. Questo è utile per i team che desiderano un'istanza di ingegnere AI stabile e condivisa.
Prima Esecuzione: Configurazione del Progetto e Definizione del Task
OpenHands eccelle quando può vedere il tuo codice. Inizia con:
- Aprire il repository su cui vuoi che lavori.
- Eseguire o indicizzare il progetto in modo che OpenHands possa mappare la struttura.
- Dargli un obiettivo chiaro con dei vincoli.
Buon esempio di definizione del task:
- "Aggiungi la reimpostazione della password utente al servizio
auth utilizzando link e-mail basati su token. Utilizza il modulo mailer esistente. Aggiungi unit test per la generazione e la scadenza del token. Non modificare lo schema dei dati utente."
Perché funziona:
- Definisce il componente, l'ambito, le dipendenze e i confini. Più sei chiaro, meglio OpenHands pianifica ed esegue.
Come Scrivere Prompt Efficaci per OpenHands
Pensa ai prompt come a dei ticket concisi. I migliori:
- Definiscono il risultato: "Implementa X con vincoli Y"
- Fanno riferimento a file, moduli o test: "Vedi
auth/routes.py e tests/test_auth.py"
- Stabiliscono dei vincoli: "Nessuna modifica allo schema DB; mantieni le interfacce esistenti"
- Includono criteri di accettazione: "I test dovrebbero passare:
pytest -k password_reset"
Template che puoi riutilizzare:
Obiettivo: <Cosa vuoi che sia costruito o corretto>
Contesto: <File rilevanti, vincoli noti, servizi esterni>
Accettazione: <Come appare il successo: test, endpoint, metriche>
Confini: <Cosa non cambiare o approcci da evitare>
Strumenti: <Comandi che può eseguire, script o origini dati>
Workflow Principale: Pianifica → Esegui → Verifica → Affina
OpenHands di solito propone un piano in più fasi. Ecco come guidarlo:
- Approva o modifica il suo piano in anticipo. Incoraggialo a eseguire prima i test per definire le baseline dei fallimenti.
- Chiedigli di creare o aggiornare un test per definire il successo, quindi implementare il codice.
- Fagli eseguire frequentemente la suite di test e i linters.
- Se si blocca, aggiungi più contesto: nomi di file, stack trace o log.
Suggerimento da professionista: Incoraggia piccole modifiche delle dimensioni di una PR invece di modifiche monolitiche. Questo aiuta con la revisionabilità e il rollback.
Esempi di Workflow Che Puoi Copiare
1) Implementazione di Feature
- Prompt: "Aggiungi l'esportazione CSV alla pagina
orders. Utilizza la paginazione lato server, trasmetti i risultati in streaming tramite text/csv. Aggiungi il pulsante Export in OrdersTable.jsx e l'endpoint in routes/orders.ts. Includi test per la paginazione e gli header."
- Scansiona il repository; elabora la bozza del piano
- Aggiunge l'endpoint e il pulsante client
- Scrive i test e li esegue
- Tu supervisioni, approvi le modifiche e fai il merge una volta che è tutto verde.
2) Debug di una Build Fallita
- Prompt: "La CI sta fallendo su Node 20. Correggi gli errori di importazione ESM/CJS in
build.mjs. Mantieni i plugin rollup esistenti; aggiorna la configurazione e il codice per superare la CI."
- Fornisci i log o il link agli artefatti della CI.
- Chiedi a OpenHands di replicare localmente (
npm run build) e proponi diff minimali.
3) Copertura dei Test e Rafforzamento
- Prompt: "Aumenta la copertura per
payments/service.py dal 62% all'85%+. Aggiungi unit test per retry_charge, refund, webhook_signature. Non modificare la logica di business a meno che il test non esponga un bug."
- Lascia che OpenHands generi i test, li esegua e li affini.
4) Documentazione ed Esperienza dello Sviluppatore
- Prompt: "Crea un file
CONTRIBUTING.md e DEVELOPMENT.md per questo repository. Includi la configurazione dell'ambiente, gli script, i comandi di test e le linee guida per le PR."
- Fagli verificare i comandi eseguendoli effettivamente.
Misure di Sicurezza: Mantieni OpenHands Utile e Sicuro
- Ambito della directory: Indicalo a un repository o directory specifica per evitare modifiche accidentali altrove.
- Protezione dei file: Contrassegna i file di configurazione o l'infrastruttura critica come di sola lettura, ove possibile.
- Audit dei comandi: Richiedi l'approvazione per i comandi distruttivi (ad esempio,
rm -rf, reset del database).
- Igiene dei segreti: Non incollare mai le chiavi API nei prompt. Utilizza variabili d'ambiente e log mascherati.
- Accesso alla rete: Se la navigazione è abilitata, crea una sandbox e registra le chiamate in uscita.
Modelli Locali vs Cloud: Scegliere Ciò Che È Giusto Per Te
- Pro: Forte ragionamento/codifica, configurazione minima, iterazione rapida
- Contro: Costo continuo, considerazioni sulla governance dei dati
- Pro: Privacy, controllo, prevedibilità dei costi
- Contro: Richieste hardware, la qualità del modello varia, è necessaria più ottimizzazione
Consulta le istruzioni ufficiali Local LLMs per configurare i backend del modello e i limiti di memoria.
Gioco di Squadra: Usare OpenHands in un Flusso Collaborativo
- Workflow branch-first: Fai creare a OpenHands un branch di feature e invia le modifiche per la revisione della PR.
- Igiene dei commit: Chiedigli di produrre commit atomici con messaggi chiari e fare riferimento ai numeri di issue.
- Template PR: Genera e applica template PR in modo che i revisori sappiano cosa è cambiato e perché.
- Code owner: Combina con CODEOWNERS per indirizzare le PR generate dall'AI ai revisori giusti.
Risoluzione dei Problemi Comuni
- Si blocca o va in loop: Riduci l'ambito. Chiedigli di spiegare il suo prossimo passo. Fornisci un test fallito.
- Diff disordinate: Richiedi un piano più piccolo e graduale: prima i test, poi modifiche minime al codice.
- Modifiche di file errate: Specifica i percorsi esatti e ricordagli i confini.
- Supera i test localmente ma fallisce nella CI: Condividi i dettagli dell'ambiente CI e i log; fagli replicare con un container.
Suggerimenti sulle Performance e Mosse Avanzate
- Contesto di warm-start: Chiedigli di leggere prima i file chiave (
README, package.json, file di servizio principali).
- Forniscigli script: Fornisci un
make test o npm run verify in modo che possa convalidare rapidamente.
- Insegna il dominio: Offri una breve panoramica architetturale; ripaga con meno errori logici.
- Applica lo stile: Indica le configurazioni
.eslintrc, .prettierrc, black/ruff in modo che formatti correttamente.
- Usa checkpoint: Dopo ogni milestone, chiedi un riepilogo e i prossimi passi per mantenerlo in carreggiata.
Scenario Reale: Dal Bug Report alla Patch in un'Ora
- Situazione: Un bug di produzione rilascia 500 non gestiti su payload JSON malformati nell'API
orders.
- Il tuo prompt: "Riproduci il 500 su JSON malformato in
orders POST. Aggiungi la validazione dello schema e restituisci 400 con i dettagli dell'errore. Aggiorna i test per coprire i payload malformati."
- Esegue l'API localmente, riproduce l'errore
- Aggiunge un livello di validazione e un gestore di errori
- Aggiorna i test e garantisce che la CI passi
- Produce una PR compatta con una voce di changelog
Tempo risparmiato: Ti sei concentrato sull'analisi dell'impatto e sul rollout, mentre OpenHands ha gestito l'impalcatura.
Integrazioni Che Sovralimentano OpenHands
- Test runner: pytest, Jest, Vitest, JUnit
- Strumenti di build: Vite, Webpack, Rollup, Babel
- Package manager: npm, pnpm, yarn, pip/poetry
- Linters/formatter: ESLint, Prettier, black, ruff
- Container: Docker Compose per la parità locale con la CI
Standardizzando questi strumenti, OpenHands può ragionare sul tuo stack in modo più affidabile e automatizzare più del dev loop.
A Proposito: Usare Sider.AI Insieme a OpenHands
Punteggio di rilevanza: 8/10. Se stai usando OpenHands come tuo ingegnere AI, vale la pena abbinarlo a un copilot di ricerca e stesura per specifiche, descrizioni PR e documentazione. A proposito, Sider.AI può aiutarti a redigere rapidamente specifiche tecniche, riassumere RFC o trasformare i log di esecuzione di OpenHands in changelog puliti e note di rilascio. La combinazione riduce il context-switching: OpenHands gestisce le azioni del codice mentre Sider.AI trasforma i risultati in documenti puliti e rivolti all'utente.
Checklist di Sicurezza, Privacy e Conformità
- Conserva i segreti nelle variabili d'ambiente; non incorporare mai le chiavi nei prompt
- Rivedi ogni modifica generata dall'AI come faresti con la PR di uno sviluppatore junior
- Registra comandi e azioni per l'auditabilità
- Blocca le versioni della toolchain; evita aggiornamenti accidentali nei lockfile
- Se utilizzi LLM cloud, allineati alle tue policy di conservazione dei dati
Quando Non Usare OpenHands
- Progettazione di algoritmi nuovi senza una solida impalcatura di test o specifiche
- Codebase altamente regolamentati senza un robusto processo di revisione
- Script usa e getta una tantum in cui la codifica manuale è più veloce
I Tuoi Primi 60 Minuti con OpenHands: Un Mini Playbook
- Minuto 0–10: Installa e avvia utilizzando l'Avvio Rapido ufficiale
- Minuto 10–20: Connetti il tuo repository; chiedigli di mappare la struttura del progetto
- Minuto 20–35: Definisci un obiettivo piccolo e testabile; approva il suo piano
- Minuto 35–50: Lascia che implementi ed esegua i test; spingi se necessario
- Minuto 50–60: Rivedi le diff, affina e fai il merge in un branch di feature
Link Chiave e Prossimi Passi
- Documentazione ufficiale "Start Building" e sull'utilizzo di OpenHands: suggerimenti, avvio rapido e best practice.
- Guida alla configurazione di LLM locale: configura ed esegui OpenHands interamente sulla tua macchina.
- Installazione guidata dalla comunità su una VM: passaggi di installazione reali e un progetto demo rapido.
Punti Chiave
- Definisci i task come ticket con criteri di accettazione chiari.
- Mantieni le iterazioni piccole; testa presto e spesso.
- Usa misure di sicurezza e rivedi le modifiche: trattalo come un compagno di squadra junior.
- Scegli il cloud per comodità, i modelli locali per la privacy.
- Abbina a strumenti di documentazione (ad esempio, Sider.AI) per accelerare specifiche e note di rilascio.
FAQ
Q1: Come posso installare e iniziare a usare AI OpenHands rapidamente?
Utilizza l'avvio rapido ufficiale per installare i prerequisiti, collega un LLM supportato (cloud o locale) e avvia l'interfaccia utente per connettere il tuo repository. La documentazione "Start Building" fornisce istruzioni passo passo con suggerimenti per la configurazione.
Q2: Posso eseguire OpenHands con un LLM locale invece di un modello cloud?
Sì. Segui la guida Local LLMs per configurare un backend del modello locale e regolare le impostazioni di contesto. Questo è ideale per progetti sensibili alla privacy o per evitare i costi delle API.
Q3: Qual è il modo migliore per richiedere a OpenHands attività di codifica?
Scrivi prompt come ticket concisi: definisci l'obiettivo, fai riferimento a file specifici, imposta i confini e includi i criteri di accettazione. Chiedigli di creare o eseguire test per convalidare i progressi.
Q4: AI OpenHands è sicuro da usare sul codice di produzione?
Trattalo come uno sviluppatore junior: utilizza protezioni del branch, revisione del codice e CI per convalidare le modifiche. Aggiungi misure di sicurezza per i comandi e mantieni i segreti fuori dai prompt.
Q5: Come si confronta OpenHands con un tradizionale assistente di codice?
A differenza degli strumenti basati solo sulla chat, OpenHands può eseguire comandi, modificare file e iterare autonomamente all'interno del tuo repository. È progettato per attività end-to-end come feature, debugging e test.
