Guida Rapida all'Assistente per la Codifica OpenHands: Installazione, Flag della CLI ed Esempi

Guida rapida OpenHands CLI in pochi minuti

Indice

OpenHands è una piattaforma open-source, agnostica rispetto al modello, per agenti di sviluppo software guidati dall’IA. Permette a un agente di comportarsi più come un partner di programmazione che come un semplice strumento di autocompletamento.

Può lavorare con i file, eseguire comandi in un ambiente sandboxato e utilizzare la navigazione web quando necessario.

Questa guida rapida si concentra sul CLI di OpenHands, perché è il modo più rapido per essere produttivi dal terminale e si adatta perfettamente a modelli di automazione come script ed esecuzioni CI. Per una visione più ampia del settore, consulta Strumenti per Sviluppatori AI: La Guida Completa allo Sviluppo Potenziato dall’IA.

openhands text user interface

Cos’è OpenHands e cosa fa in modo diverso

Un assistente di programmazione AI tipicamente ti aiuta a generare o modificare codice utilizzando un modello linguistico. OpenHands estende questa idea in un flusso di lavoro “agentico”: il sistema può pianificare in modo iterativo, compiere azioni (come scrivere file o eseguire test), osservare i risultati e continuare fino al completamento del compito.

OpenHands è anche ampiamente noto come il progetto precedentemente chiamato OpenDevin ed è diventato una piattaforma guidata dalla comunità con diversi modi per utilizzarlo: un CLI, un’interfaccia web locale (GUI), un’interfaccia ospitata nel cloud e un SDK.

Da una prospettiva ingegneristica, il differenziatore chiave è che OpenHands è costruito attorno a un ambiente di esecuzione (un sandbox) in modo che un agente possa eseguire comandi e strumenti in sicurezza, anziché produrre solo testo. Il paper di OpenHands descrive un ambiente runtime Docker-sandboxato con capacità shell e di navigazione, specificamente per supportare pattern di interazione realistici simili a quelli degli sviluppatori.

Installazione del CLI OpenHands

OpenHands supporta metodi di installazione multipli. Per la maggior parte degli sviluppatori, è meglio iniziare con un’installazione locale del CLI (iterazione rapida) e aggiungere opzionalmente flussi di lavoro basati su Docker in seguito, quando si desidera un’isolamento rigoroso dell’esecuzione.

Installazione con uv

La documentazione attuale del CLI OpenHands consiglia di installare con uv e richiede Python 3.12+.

uv tool install openhands --python 3.12
openhands

L’aggiornamento è altrettanto semplice.

uv tool upgrade openhands --python 3.12

Perché uv è importante nella pratica: uv offre un migliore isolamento dall’ambiente del tuo progetto corrente ed è richiesto per i server MCP predefiniti.

Installazione del binario CLI standalone

Se desideri un flusso di installazione “singolo comando”, OpenHands fornisce uno script di installazione.

curl -fsSL https://install.openhands.dev/install.sh | sh
openhands

Su macOS potrebbe essere necessario autorizzare esplicitamente il binario in Privacy & Sicurezza prima che venga eseguito.

Esecuzione tramite Docker per l’isolamento

Se preferisci mantenere l’installazione contenuta, la documentazione del CLI mostra anche un flusso basato su Docker. Questo approccio si basa sul montare un directory a cui OpenHands deve accedere e passare il tuo ID utente per evitare la creazione di file di proprietà root nel workspace montato.

export SANDBOX_VOLUMES="$PWD:/workspace"

docker run -it \
  --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.12.0-python \
  -e SANDBOX_USER_ID=$(id -u) \
  -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/root/.openhands \
  --add-host host.docker.internal:host-gateway \
  --name openhands-cli-$(date +%Y%m%d%H%M%S) \
  python:3.12-slim \
  bash -c "pip install uv && uv tool install openhands --python 3.12 && openhands"

Configurazione del primo avvio e posizione delle impostazioni

Al primo avvio, il CLI ti guida nella configurazione delle impostazioni LLM richieste e le memorizza per le sessioni future. La documentazione del CLI afferma che le impostazioni vengono salvate in ~/.openhands/settings.json e la cronologia delle conversazioni in ~/.openhands/conversations, ma quando ho installato OpenHands poco tempo fa, ha memorizzato la configurazione in ~/.openhands/agent_settings.json, quindi la documentazione potrebbe non essere del tutto corretta.

Per una configurazione più approfondita e l’integrazione degli strumenti, OpenHands documenta anche file di configurazione aggiuntivi come ~/.openhands/agent_settings.json (impostazioni dell’agente e LLM), ~/.openhands/cli_config.json (preferenze CLI) e ~/.openhands/mcp.json (server MCP).

Configurazione di OpenHands con Ollama locale e llama.cpp

OpenHands funziona con qualsiasi backend locale compatibile con OpenAI — Ollama, LocalAI, llama.cpp e altri. Se non sei sicuro di quale utilizzare, consulta Ollama vs vLLM vs LM Studio: Il Miglior Modo per Eseguire LLM Localmente per un confronto.

Quando avvii OpenHands per la prima volta, ti viene mostrata la pagina delle impostazioni. Una volta superata questa fase iniziale, puoi riaprire questa pagina digitando /settings e poi ctrl+j. Ora digita:

  • nel campo Custom Model: ollama/devstral-small-2:24b, o qual è il tuo modello locale preferito,
  • e nel campo Base Url: http://localhost:11434

openhands settings ollama mistral

Per un riferimento rapido sui comandi Ollama, consulta il Cheat sheet CLI Ollama: serve, run, ps e gestione modelli.

Per modificare manualmente il file di configurazione di OpenHands, ad esempio se non ti piace come appare la pagina delle impostazioni, esegui:

nano ~/.openhands/agent_settings.json

o se preferisci un editor con più interfaccia grafica:

gedit GUI ~/.openhands/agent_settings.json

La proprietà llm si trova in due luoghi, li ho impostati per avere queste sottoproprietà, tra le altre, per puntare a ollama:

"llm":{"model":"ollama/devstral-small-2:24b","api_key":"aaa","base_url":"http://localhost:11434"

Per puntare OpenHands a un’istanza locale di llama.cpp - lo stesso, in due luoghi:

"llm":{"model":"openai/devstral-small-2:24b","api_key":"aaa","base_url":"http://localhost:11434"

Per connettermi a llama.cpp ho configurato:

  • “model”:“openai/Qwen3.5-35B-A3B-UD-IQ3_S.gguf”
  • “base_url”:“http://localhost:8080/v1”

e ho avviato llama.cpp con il comando (vedi Quickstart llama.cpp con CLI e Server per i dettagli sui flag):

./llama.cpp/llama-server \
    -m /mnt/ggufs/Qwen3.5-35B-A3B-UD-IQ3_S.gguf \
    --ctx-size 70000 \
    -ngl 40 \
    --temp 0.6 \
    --top-p 0.95 \
    --top-k 20 \
    --min-p 0.00

OpenHands ha potuto connettersi ad esso e completare con successo la mia richiesta di test crea per me uno strumento CLI in Go, che chiamerà i endpoint indexnow di bing e altri motori di ricerca per notificare i cambiamenti sul mio sito - con codice sorgente, eseguibile e README.md.

Come funziona il CLI OpenHands nella pratica

Il comando predefinito openhands avvia un’esperienza terminale interattiva. OpenHands fornisce una palette di comandi e comandi in sessione in modo da poter guidare rapidamente l’agente mentre lavora.

I controlli interattivi utili da conoscere subito includono l’apertura della palette di comandi, la pausa dell’agente e l’uscita dall’app.

  • Ctrl+P apre la palette di comandi.
  • Esc mette in pausa l’agente in esecuzione.
  • Ctrl+Q o /exit esce dal CLI.

All’interno del CLI, OpenHands supporta anche comandi con prefisso slash come /help, /new e /condense, che è utile se desideri gestire conversazioni lunghe senza riavviare.

OpenHands non si ferma a un’interfaccia terminale. Il CLI include più interfacce che si adattano bene a diversi flussi di lavoro degli sviluppatori:

  • Modalità Headless per automazione e CI.
  • Interfaccia Web per eseguire l’esperienza CLI in un browser.
  • Server GUI per l’applicazione web locale completa, avviato tramite Docker.
  • Integrazione IDE tramite ACP per flussi di lavoro basati su editor.

I principali parametri della riga di comando che userai realmente

A un livello elevato, OpenHands CLI segue questa struttura:

openhands [OPZIONI] [COMANDO]

Ciò include opzioni globali (cose come task, riprendi, headless), più sottocomandi (serve, web, cloud, acp, mcp, login, logout).

Opzioni principali per il lavoro quotidiano

I globali più comunemente usati sono:

  • -t, --task per inizializzare la conversazione con un task iniziale.
  • -f, --file per inizializzare da un file, utile quando desideri che i task siano committati al controllo di versione.
  • --resume [ID] e --last per riprendere esecuzioni precedenti.
  • --headless per l’esecuzione non interattiva, tipicamente nell’automazione.
  • --json per trasmettere output JSONL in modalità headless per l’elaborazione macchina.

Sicurezza e approvazioni sono anche di primo piano:

  • --always-approve approva automaticamente le azioni senza richiedere conferma.
  • --llm-approve utilizza un analizzatore di sicurezza basato su LLM per l’approvazione delle azioni.

Configurazione del modello e del provider tramite variabili d’ambiente

OpenHands supporta variabili d’ambiente per la configurazione del modello:

  • LLM_API_KEY imposta la tua chiave API del provider.
  • LLM_MODEL e LLM_BASE_URL possono essere applicati come override quando esegui openhands --override-with-envs.

Esempio di flusso di override:

export LLM_MODEL="gpt-4o"
export LLM_API_KEY="your-api-key"
openhands --override-with-envs

OpenHands nota esplicitamente che gli override applicati con --override-with-envs non vengono persistiti.

Sottocomandi da conoscere

Non hai bisogno di ogni sottocomando fin dal primo giorno, ma questi sono quelli che emergono rapidamente:

  • openhands serve avvia il server GUI completo usando Docker, tipicamente raggiungibile su http://localhost:3000, con opzioni come --mount-cwd e --gpu.
  • openhands web avvia il CLI come applicazione web accessibile dal browser, con porta predefinita 12000.
  • openhands login autentica con OpenHands Cloud e recupera le tue impostazioni.
  • openhands cloud crea una nuova conversazione in OpenHands Cloud dal CLI.

Esempi da copiare e incollare che puoi usare immediatamente

Il modo più rapido per ottenere valore da OpenHands è trattarlo come un agente di coding guidato dai task. Mantieni i task concisi, includi i nomi dei file e chiedi test o verifiche quando appropriato.

Avvia una sessione di coding interattiva con un task iniziale

Questo è l’“esperienza sviluppatore predefinita” e uno dei pattern più comuni.

openhands -t "Correggi il bug in auth.py e aggiungi un test di regressione"

La documentazione del CLI OpenHands mostra esattamente questa idea per avviare una sessione con -t.

Inizializza un task da un file

Usare un file è utile quando desideri ripetibilità, revisione del team o riutilizzo CI.

cat > task.txt << 'EOF'
Rifattorizza il modulo di connessione al database.
Aggiungi test unitari e assicurati che la suite di test passi.
EOF

openhands -f task.txt

Il Quick Start del CLI supporta esplicitamente l’avvio da un file di task con -f.

Esegui in modalità headless per CI o automazione

La modalità headless esegue senza l’interfaccia interattiva ed è costruita per pipeline CI e scripting automatizzato.

openhands --headless -t "Aggiungi test unitari per auth.py ed eseguili"

Due importanti realtà ingegneristiche qui:

  • La modalità headless richiede --task o --file.
  • La modalità headless esegue sempre in modalità always-approve e non può essere cambiata, e --llm-approve non è disponibile in modalità headless. Trattala come automazione potente ed eseguila in un ambiente controllato.

Per integrare con l’analisi dei log o altri strumenti, abilita l’output JSONL:

openhands --headless --json -t "Crea una semplice app Flask con endpoint healthcheck" > openhands-output.jsonl

OpenHands documenta --json come streaming di eventi JSONL in modalità headless e mostra come reindirizzare l’output a un file.

Riprendi il lavoro senza perdere il contesto

Riprendere è critico una volta che inizi a usare OpenHands per cambiamenti non banali.

Elenca le conversazioni recenti:

openhands --resume

Riprendi l’ultima:

openhands --resume --last

O riprendi uno specifico ID di conversazione:

openhands --resume abc123def456

Questi flussi sono documentati nel riferimento dei comandi CLI e nella guida “Riprendi Conversazioni”.

Esegui il CLI in un browser quando necessario

openhands web avvia un CLI accessibile via web (porta predefinita 12000).

openhands web

Se stai eseguendo localmente, legarsi solo a localhost è un predefinito sensato:

openhands web --host 127.0.0.1 --port 12000

OpenHands avverte che esporre l’interfaccia web alla rete richiede misure di sicurezza appropriate, perché fornisce accesso completo alle funzionalità di OpenHands.

Sicurezza, risoluzione dei problemi e punti critici

Il leva di sicurezza più importante nel CLI OpenHands sono le approvazioni:

  • Il CLI interattivo può richiedere conferma prima di azioni sensibili e puoi configurare le impostazioni di conferma in sessione.
  • --always-approve rimuove l’attrito ma rimuove anche le salvaguardie.
  • --llm-approve aggiunge un analizzatore basato su LLM per le approvazioni.
  • La modalità headless approva sempre, quindi riservala per l’automazione in ambienti controllati.

Quando si lavora con codice locale, preferisci pattern di accesso espliciti e con privilegi minimi:

  • Per il server GUI, openhands serve --mount-cwd monta la tua directory corrente in /workspace in modo che l’agente possa leggere e modificare i file del tuo progetto.
  • Per le esecuzioni CLI basate su Docker, usa SANDBOX_VOLUMES per definire esattamente quali directory OpenHands può accedere.

Se hai directory di stato OpenHands più vecchie, OpenHands nota un percorso di migrazione da ~/.openhands-state a ~/.openhands nella documentazione di configurazione locale e guida alla risoluzione dei problemi.

Infine, se stai integrando OpenHands negli script, i codici di uscita sono documentati come:

  • 0 successo
  • 1 errore o task fallito
  • 2 argomenti non validi

La mia esperienza con OpenHands

Per me OpenHands ha funzionato bene, ma non sempre… Ho provato a farlo funzionare con Devstral-Small-2 ospitato su Ollama, e si fermava continuamente.

OpenHands con Ollama-hosted Devstral-Small-2.

Tuttavia, OpenHands ha funzionato bene con Qwen 3.5 35b ospitato localmente su llama.cpp. Finora per me OpenCode è molto più affidabile.