Qwen Code: l'agente di codice da terminale con Ollama

#Che cos'è Qwen Code e perché eseguirlo in locale

Qwen Code è un fork di Gemini CLI, l'agente da terminale open source di Google, che il team Qwen ha adattato ai suoi modelli Qwen3-Coder. Il progetto è pubblicato con licenza Apache 2.0 su GitHub (QwenLM/qwen-code), si installa tramite npm e si usa con il comando qwen. Riprende la meccanica dei moderni agenti di coding: un modello riceve la tua richiesta, dispone di strumenti (lettura e scrittura di file, ricerca nel repository, esecuzione shell, richieste web, server MCP) e continua a usare questi strumenti finché non produce un risultato verificabile.

Per impostazione predefinita, Qwen Code indirizza verso una connessione « Qwen OAuth »: accedi con un account Qwen e le richieste vengono inviate ai server di Alibaba Cloud. Questo percorso offre un piano gratuito, ma le quote possono cambiare e dipendono dalla regione. Perciò non indichiamo alcuna cifra: la pagina di autenticazione della documentazione ufficiale è l'unica fonte aggiornata. Ciò che non cambia è l'altra modalità, detta « OpenAI-compatible »: Qwen Code accetta qualsiasi server che esponga l'API OpenAI, tra cui Ollama e LM Studio sulla tua macchina.

Privacy

In modalità locale, il codice sorgente, i comandi eseguiti e i relativi output non lasciano mai il computer. È l'argomento decisivo per il codice dei clienti o soggetto a un accordo di riservatezza.

Costo

Nessuna quota, nessuna fattura per token. L'unico costo è l'elettricità e l'hardware già acquistato.

Disponibilità

Nessuna interruzione del servizio, nessuna coda nelle ore di punta. L'agente risponde finché la GPU è in funzione.

Svantaggio

Un modello da 7 a 30 miliardi di parametri con quantizzazione Q4 non è all'altezza di un modello cloud da diverse centinaia di miliardi. Bisogna suddividere i compiti più finemente e rileggere di più.

#Prerequisiti

Node.js 20 o più recente

Qwen Code è un pacchetto npm. Verificate con node --version. Su Linux e macOS, nvm o fnm evitano i problemi di autorizzazioni durante l'installazione globale.

Ollama installato e funzionante

Il daemon è in ascolto su http://localhost:11434. Un ollama list deve rispondere senza errori. In caso contrario, inizia dalla guida all'installazione di Ollama.

Un modello che gestisce le chiamate agli strumenti

È imprescindibile: un agente di codice concatena chiamate a strumenti strutturati. I modelli della famiglia Qwen3-Coder e Qwen2.5-Coder, così come Devstral, li supportano in Ollama. Un modello senza supporto per i tools produrrà testo al posto delle azioni e l'agente resterà bloccato.

Memoria GPU

Riferimenti in Q4_K_M: un 7B occupa circa 5 GB di VRAM, un 14B circa 9 GB, un 32B circa 19 GB, senza contare il contesto. Il contesto lungo richiesto da un agente aggiunge diversi gigabyte: fai una stima abbondante.

Un repository Git

Non è obbligatorio, ma fortemente consigliato. L'agente modifica i file; git diff e git checkout sono la tua rete di sicurezza.

#1. Installare Qwen Code

L'installazione consigliata dal repository passa da npm globale. Su macOS viene pubblicato anche un pacchetto Homebrew. Il binario si chiama qwen.

npm install -g @qwen-code/qwen-code@latest
qwen --version

brew install qwen-code
qwen --version

Al primo avvio di qwen senza configurazione, lo strumento propone di scegliere un metodo di autenticazione. Non scegliere Qwen OAuth se il tuo obiettivo è l'uso locale: seleziona l'opzione OpenAI oppure, meglio ancora, esci e prepara prima la configurazione descritta nel passaggio successivo. Potrai sempre cambiare metodo più avanti con il comando /auth in una sessione.

#2. Collegare Qwen Code a Ollama

Ollama espone un'API compatibile con OpenAI sul percorso /v1 della porta 11434. Qwen Code legge tre variabili d'ambiente per questa modalità: l'URL di base, una chiave API e il nome del modello. Ollama non richiede una chiave, ma Qwen Code rifiuta un valore vuoto, quindi inseriamo una stringa qualsiasi.

1. 01
   Scaricare un modello di codice compatibile con gli strumenti

   Esempio con Qwen3-Coder 30B-A3B, un modello a esperti (MoE) da 30 miliardi di parametri, di cui 3 miliardi sono attivi a ogni token, il che lo rende veloce per le sue dimensioni. Occupa circa 19 GB in Q4: servono 24 GB di VRAM, oppure una macchina Apple Silicon con almeno 32 GB unificati, per mantenerlo interamente sulla GPU. Su una scheda da 12 GB, scegli piuttosto qwen2.5-coder:7b o un modello da 14B.
2. 02
   Verificare che l'API OpenAI di Ollama risponda

   Una richiesta a /v1/models dovrebbe elencare i tuoi modelli. Se fallisce, Ollama non è avviato o ascolta su un altro indirizzo.
3. 03
   Creare il file .env nella radice del progetto

   Qwen Code carica automaticamente un file .env presente nella cartella corrente, in una sottocartella .qwen del progetto o in ~/.qwen per una configurazione globale. Ha la precedenza il file più vicino alla cartella di lavoro.
4. 04
   Avviare qwen nel progetto

   In fondo alla finestra viene mostrato il modello attivo. Se vedi il nome del tuo modello Ollama, il collegamento è configurato. Digita una prima richiesta semplice, ad esempio riassumere la struttura del repository, per verificare che gli strumenti di lettura funzionino.

ollama pull qwen3-coder:30b
curl http://localhost:11434/v1/models

OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3-coder:30b

cd mon-projet
qwen

Gli stessi parametri possono essere passati come opzioni dalla riga di comando per una sessione occasionale, senza toccare il file .env. È utile per provare un secondo modello senza compromettere la configurazione funzionante.

qwen --openai-api-key ollama \
  --openai-base-url http://localhost:11434/v1 \
  --model qwen2.5-coder:14b

#3. Variante: LM Studio come server

Se preferisci LM Studio, il principio è identico. Carica un modello di coding nell'applicazione, apri la scheda Developer e avvia il server locale: ascolta per impostazione predefinita sulla porta 1234 ed espone la stessa API compatibile con OpenAI. Ricordati di attivare il supporto alle chiamate agli strumenti nelle opzioni del server, se non è già selezionato, e di impostare la lunghezza del contesto del modello nell'interfaccia (vedi il passaggio successivo).

OPENAI_API_KEY=lm-studio
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen2.5-coder-14b-instruct

Il nome del modello da indicare è l'identificatore mostrato da LM Studio nell'elenco dei modelli caricati oppure restituito da una richiesta a http://localhost:1234/v1/models. È diverso dai nomi Ollama.

#4. Regolare la finestra di contesto: il passaggio che tutti saltano

È la causa numero uno dei problemi di Qwen Code in locale. Un agente di coding invia a ogni turno un lungo prompt di sistema (descrizione degli strumenti, regole di comportamento, contenuto del file QWEN.md), poi la cronologia della sessione e infine i file letti. Già nei primi scambi si superano i 10.000 token. Ollama invece apre per impostazione predefinita una finestra breve (4.096 token nelle versioni recenti): tutto ciò che supera il limite viene troncato silenziosamente, il modello «dimentica» le istruzioni sugli strumenti e inizia a rispondere in prosa invece di agire, oppure ripete la stessa azione in un loop.

Devi quindi imporre un contesto di almeno 32.000 token. Due metodi con Ollama: una variabile d'ambiente globale sul daemon oppure un Modelfile che imposta num_ctx per un modello specifico.

sudo systemctl edit ollama
# Ajouter dans le bloc [Service] :
# Environment="OLLAMA_CONTEXT_LENGTH=32768"
sudo systemctl restart ollama

launchctl setenv OLLAMA_CONTEXT_LENGTH 32768
# puis relancer l'application Ollama

cat > Modelfile.qwen-code <<'EOF'
FROM qwen3-coder:30b
PARAMETER num_ctx 32768
EOF
ollama create qwen3-coder-32k -f Modelfile.qwen-code
# puis OPENAI_MODEL=qwen3-coder-32k dans le .env

Il secondo metodo è più pulito: non tocca gli altri modelli e il nome del modello derivato ricorda la sua impostazione. Il costo è la memoria: la cache chiave-valore cresce insieme al contesto. Per un modello 7B in Q4, 32.000 token di contesto aggiungono approssimativamente da 2 a 4 GB, a seconda dell'architettura e della quantizzazione della cache. Se il modello non entra più nella GPU, Ollama sposta parte dei layer sulla CPU e la velocità crolla: controlla la colonna PROCESSOR di ollama ps, che deve mostrare 100 % GPU.

Anche sul lato Qwen Code esiste un limite di sessione. L'impostazione sessionTokenLimit nel file delle impostazioni limita il numero complessivo di token di una conversazione; una volta raggiunto, lo strumento invita a comprimere la cronologia con /compress o a ripartire da zero con /clear. Allinea questo valore a ciò che il tuo modello supporta realmente: un limite di 32 000 per un modello servito con num_ctx 32768 evita i troncamenti silenziosi sul lato Ollama.

#5. File delle impostazioni e QWEN.md

Qwen Code legge un file settings.json a due livelli: ~/.qwen/settings.json per l'utente e .qwen/settings.json nel progetto, che ha la precedenza. Le chiavi più utili per l'uso locale sono il limite della sessione, la modalità di approvazione delle azioni e i server MCP. I nomi esatti sono cambiati tra le versioni; l'esempio seguente segue la documentazione pubblica e deve essere confrontato con la pagina Settings della tua versione.

{
  "sessionTokenLimit": 32000,
  "contextFileName": "QWEN.md",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/moi/mon-projet"]
    }
  }
}

Il file QWEN.md svolge lo stesso ruolo di CLAUDE.md per Claude Code o AGENTS.md per altri agenti: è il promemoria permanente inserito in ogni sessione. Descrivici lo stack, i comandi di build e test, le convenzioni di denominazione e ciò che l'agente non deve mai toccare. Il comando /init ne genera una prima versione a partire dal repository; /memory show mostra ciò che l'agente ha realmente caricato.

# Projet API Facturation

- Python 3.12, FastAPI, tests avec pytest (`make test`).
- Ne jamais modifier les migrations existantes dans alembic/versions/.
- Toute nouvelle route doit avoir un test dans tests/api/.
- Style : ruff, lignes de 100 caractères max.

La modalità di approvazione controlla ciò che l'agente può fare senza chiedervelo. Per impostazione predefinita, ogni scrittura di file e ogni comando shell attendono la vostra convalida. L'opzione --approval-mode auto-edit lascia passare le modifiche ai file ma non i comandi; --yolo elimina ogni conferma. Con un modello locale che sbaglia più spesso di un modello cloud, mantenete la modalità predefinita finché non avete acquisito fiducia e riservate --yolo a un repository pulito e con commit.

#6. Prima sessione di lavoro

Una sessione di Qwen Code si controlla in linguaggio naturale, con alcune scorciatoie. Il prefisso @ inserisce un file o una cartella nella richiesta (@src/api/routes.py), il prefisso! esegue un comando shell senza passare dal modello e i comandi che iniziano con / controllano direttamente lo strumento.

/help

Elenco dei comandi disponibili nella tua versione.

/auth

Cambia il metodo di autenticazione, utile per passare dall'uso locale al cloud e viceversa.

/model

Mostra o cambia il modello durante la sessione.

/stats

Token consumati e durata della sessione: il primo riflesso quando le risposte peggiorano.

/compress

Riassumi la cronologia per liberare contesto senza perdere il filo.

/clear

Riparte da una conversazione vuota; QWEN.md resta caricato.

/init et /memory

Genera e poi ispeziona il file di contesto del progetto.

/mcp

Stato dei server MCP configurati e strumenti che espongono.

/quit

Esce dalla sessione.

Un flusso che funziona bene con un modello locale: chiedere prima una lettura («spiega come viene gestita l'autenticazione in @src/auth/»), poi una modifica circoscritta («aggiungi un controllo della scadenza del token in verify_token e un test corrispondente»), quindi la verifica («esegui make test e correggi ciò che si rompe»). Ogni passaggio occupa poche migliaia di token e il modello mantiene il filo. Le richieste del tipo «rifattorizza l'intero modulo» vanno oltre ciò che i modelli da 7 a 30B riescono a gestire in modo affidabile.

Per l'automazione, la modalità non interattiva accetta una richiesta come argomento e restituisce il controllo una volta terminata. Si integra in uno script o in un hook Git.

qwen -p "Relis le diff de git diff --cached et liste les problèmes potentiels, sans modifier de fichier"

#Limiti di Qwen Code in locale

Qwen Code è progettato attorno ai modelli Qwen3-Coder forniti da Alibaba Cloud, e lo si nota subito quando lo si esegue su un modello locale più piccolo. Ecco cosa devi accettare.

Prompt di sistema pesante

Lo strumento invia una lunga descrizione degli strumenti a ogni turno. Su un modello 7B, questa sola istruzione occupa una parte del contesto e dell'attenzione del modello, che rispetta meno bene il formato delle chiamate agli strumenti rispetto ai modelli più grandi. I loop e le risposte in prosa invece delle azioni sono più frequenti che con OpenCode o Aider, che hanno prompt più compatti.

Visione riservata al cloud

Il supporto alle immagini (screenshot, mockup) si basa su modelli di visione forniti online. In locale funziona solo se il tuo server espone un modello multimodale compatibile, cosa che non vale per la maggior parte dei modelli di coding.

Nessuna gestione nativa dei modelli locali

A differenza di OpenCode, che elenca i modelli Ollama in un menu, Qwen Code richiede di inserire il nome del modello e l'URL in un file o come opzione. Cambiare modello implica modificare il file .env o riavviare con --model.

Formato di configurazione mutevole

Il progetto è giovane e il suo file settings.json ha cambiato struttura nel corso delle versioni. Un esempio trovato su un forum potrebbe non essere più valido. Fa fede la documentazione ufficiale alla data della consultazione.

Modifica tramite riscrittura

Come Gemini CLI da cui deriva, Qwen Code modifica i file sostituendo blocchi. Aider, invece, applica diff unificati e registra automaticamente ogni modifica, rendendo la cronologia più leggibile. Se vuoi un commit per modifica, Aider resta più adatto.

In compenso, Qwen Code offre un supporto MCP completo, comandi maturi per la gestione delle sessioni ereditati da Gemini CLI, una modalità non interattiva ben realizzata e un'integrazione che si estende agli IDE tramite estensione. È una scelta pertinente se usi già i modelli Qwen e vuoi un solo strumento per passare dal cloud Alibaba alla tua GPU. Se l'obiettivo è esclusivamente l'uso locale, OpenCode o Aider richiedono meno configurazione per ottenere lo stesso risultato. Non pubblichiamo un confronto numerico: la qualità dipende innanzitutto dal modello scelto, non dall'agente.

#Risoluzione dei problemi

L'agente risponde in testo invece di eseguire azioni

O il modello non gestisce le chiamate agli strumenti (verifica la sua scheda Ollama), oppure il contesto è troppo breve e la descrizione degli strumenti è stata troncata. Applica il passaggio 4 e verifica con ollama ps che il modello sia caricato correttamente con il num_ctx giusto.

Errore 404 o « model not found »

Il nome in OPENAI_MODEL non corrisponde esattamente a ollama list. Copiate e incollate il nome insieme al relativo tag.

Errore di connessione su localhost:11434

Ollama non è avviato oppure è in ascolto su un'altra interfaccia (OLLAMA_HOST). Verifica con curl http://localhost:11434/v1/models.

Risposte molto lente dopo alcuni scambi

Il contesto è aumentato e il modello non entra più nella GPU. ollama ps mostra una parte sulla CPU. Riduci num_ctx, passa a un modello più piccolo oppure esegui /compress prima nella sessione.

Qwen Code richiede nuovamente un'autenticazione OAuth

Le variabili d'ambiente non vengono lette: il file .env non si trova nella cartella corrente né in ~/.qwen. Avvia /auth nella sessione e scegli l'opzione OpenAI, oppure passa i parametri dalla riga di comando per isolare il problema.

Il modello ignora QWEN.md

Verifica con /memory show che il file sia caricato. Se contextFileName è stato modificato in settings.json, il nome deve corrispondere.

Installazione npm che fallisce con EACCES

Autorizzazioni insufficienti sulla directory globale di npm. Installate Node tramite nvm o fnm anziché tramite il pacchetto di sistema, quindi riavviate l'installazione.

#Per approfondire

Qwen Code è solo uno degli agenti da terminale che accettano un server locale. Le guide successive trattano le alternative e la scelta del modello, aspetti che questo articolo lascia volutamente da parte.

• OpenCode + Ollama: un agente di programmazione nel tuo terminale
• Aider + Ollama: programmare nel terminale con un agente al 100% locale
• Goose (Block): l'agente IA locale nel tuo terminale
• Miglior LLM locale per la programmazione: Devstral, Qwen3-Coder

Guida redatta l'11 ottobre 2026; i riferimenti sono il repository GitHub e la documentazione di Qwen Code, nonché la documentazione Ollama. Per questo articolo non sono state effettuate misurazioni di velocità o qualità; i riferimenti alla memoria sono ordini di grandezza. I comandi e i nomi delle chiavi cambiano con le versioni: verificateli nelle pagine sottostanti prima di copiarli.

• Repository GitHub QwenLM/qwen-code (README, installazione, licenza)
• Documentazione ufficiale di Qwen Code (autenticazione, settings, comandi)
• Documentazione Ollama (API compatibile con OpenAI, variabili d'ambiente)