OpenCode + Ollama: un agente di programmazione nel tuo terminal

#OpenCode con Ollama: chi fa cosa

OpenCode è un agente di programmazione open source che si esegue nel terminale: legge il tuo progetto, modifica file ed esegue comandi. Non fornisce un modello di per sé. Ollama, invece, scarica ed esegue modelli sulla tua macchina ed espone un'API locale. I due si completano: OpenCode invia le sue richieste a Ollama, che risponde con un modello locale. La domanda «OpenCode o Ollama» quindi non si pone: si usano entrambi.

L'interesse per l'esecuzione in locale non è ideologico. Un agente di programmazione vede tutto: la struttura delle directory, i file di configurazione, la logica applicativa. Con un modello locale, questo contesto rimane sulla macchina, senza fatturazione per token né dipendenza dalla rete. Il prezzo da pagare è la capacità: un modello locale di qualche decina di miliardi di parametri non eguaglia i più grandi modelli ospitati, e le attività lunghe si svolgono più lentamente.

#Prerequisiti: macchina, terminale e Ollama

Ollama in esecuzione

Verifica che un modello risponda prima di configurare qualsiasi cosa: ollama list, poi ollama run con un modello per il codice. Se funziona, rimane solo la configurazione di OpenCode.

Un terminale moderno

La documentazione di OpenCode cita WezTerm, Alacritty, Ghostty e Kitty. Su Windows, raccomanda di usare WSL per prestazioni migliori e una compatibilità completa.

Memoria per il contesto

Un agente legge file e accumula la cronologia. Ollama indica che OpenCode richiede una lunghezza del contesto di almeno 64.000 token, il che aumenta la memoria necessaria oltre a quella occupata dai pesi del modello.

Un repository git

Non obbligatorio, ma consigliato: un git diff o un git restore annulla correttamente una sessione fallita.

#Installare OpenCode e collegarlo a Ollama

OpenCode si installa con uno script o con i gestori di pacchetti. La documentazione elenca lo script ufficiale, npm, bun, pnpm, yarn, Homebrew, Arch, Chocolatey, Scoop, Mise e Docker. Per macOS e Linux con Homebrew, consiglia il tap ufficiale piuttosto che la formula base, che viene aggiornata meno spesso.

curl -fsSL https://opencode.ai/install | bash

npm install -g opencode-ai

brew install anomalyco/tap/opencode

choco install opencode
scoop install opencode

#Metodo veloce: ollama launch opencode

Ollama può avviare OpenCode con un modello scelto. Il comando ollama launch opencode avvia OpenCode con una configurazione fornita inline, senza sovrascrivere il tuo file ~/.config/opencode/opencode.json; le tue impostazioni esistenti di OpenCode continuano ad applicarsi. Con l'opzione --config, Ollama configura OpenCode senza aprire una sessione interattiva. I modelli definiti solo in opencode.json non appaiono nel selettore di ollama launch.

ollama launch opencode

#Metodo manuale: dichiarare Ollama come fornitore

Se preferisci mantenere il controllo, aggiungi un provider al file opencode.json globale (~/.config/opencode/opencode.json) oppure a quello nella radice del progetto. L'endpoint di Ollama compatibile con OpenAI è http://localhost:11434/v1. Ogni chiave sotto models deve riportare esattamente il nome del modello così come appare in ollama list.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": {
        "qwen3-coder:30b": { "name": "Qwen3-Coder 30B" },
        "devstral-small-2:24b": { "name": "Devstral Small 2" }
      }
    }
  }
}

Riavvia OpenCode: il selettore del modello propone i modelli dichiarati nella configurazione del provider Ollama.

#La trappola numero uno: la lunghezza del contesto

Molti primi tentativi falliscono perché il contesto è troppo breve: l'agente perde l'inizio del compito, ripete la lettura dei file o produce modifiche incoerenti. Ollama non stabilisce una dimensione unica del contesto: la documentazione indica 4k token sotto i 24 GB di VRAM, 32k tra 24 e 48 GB e 256k a partire da 48 GB. Precisa che, per le attività che richiedono un contesto ampio, come gli agenti e gli strumenti di programmazione, il contesto deve essere impostato ad almeno 64.000 token.

Per modificare il valore, esistono due metodi. Nell'applicazione Ollama, un cursore nelle impostazioni regola il contesto. Da riga di comando, la variabile OLLAMA_CONTEXT_LENGTH si applica all'avvio del server. Un contesto più grande consuma più memoria: verifica con ollama ps che il modello rientri interamente nella memoria della GPU, perché un modello eseguito in parte sulla CPU diventa molto lento.

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

#Quale modello locale per un agente di programmazione

Un agente deve chiamare gli strumenti in modo affidabile: leggere, scrivere, eseguire. Scegli un modello che riporti la capacità tools nella libreria Ollama. Ecco alcuni candidati i cui tag e dimensioni sono stati rilevati su ollama.com.

Queste dimensioni riguardano i file; aggiungi la cache del contesto, che cresce con i 64.000 token richiesti. Il modello da 15 GB (Devstral Small 2) è il più accessibile su una macchina da 24 GB; quello da 19 GB (Qwen3-Coder 30B) richiede un margine maggiore. Su una macchina più modesta, un modello più piccolo esegue compiti semplici e mirati, ma perde più rapidamente efficacia quando il refactoring coinvolge più file.

#Un workflow reale: aggiungere una route e il suo test

Caso concreto: aggiungere una route GET /health a una piccola API Express e coprirla con un test. La documentazione di OpenCode consiglia di iniziare con /init, che analizza il progetto e crea un file AGENTS.md alla radice, da committere in git per aiutare l'agente a capire la struttura.

1. 01
   Aprire il progetto

   Posizionati alla radice del repository, avvia opencode, poi esegui /init per la prima volta. Verifica in basso che il modello selezionato sia effettivamente un modello Ollama.
2. 02
   Passare alla modalità Plan

   Il tasto Tab permette di passare tra le modalità Plan e Build. La modalità Plan disattiva le modifiche: l'agente propone soltanto come procederebbe. Chiedigli un piano prima di qualsiasi cambiamento.
3. 03
   Descrivere il compito

   Fornisci il contesto come faresti con uno sviluppatore junior: «Aggiungi una route GET /health in src/server.js che restituisca status ok, poi un test in test/health.test.js». Il carattere @ permette di cercare un file nel progetto.
4. 04
   Passare in modalità Build

   Quando il piano ti soddisfa, premi nuovamente il tasto Tab e chiedi di applicare le modifiche.
5. 05
   Eseguire e iterare

   L'agente può eseguire npm test, leggere l'output e apportare correzioni. Questo ciclo di esecuzione, osservazione e correzione è il cuore del funzionamento degli agenti IA.
6. 06
   Verificare e creare un commit

   Rileggi l'output di git diff prima di fare un commit. Se la sessione è andata fuori controllo, git restore riporta i file allo stato precedente.

Con un modello locale, ogni passaggio è più lento rispetto a un modello ospitato, e un'istruzione ambigua richiede a volte una riformulazione. Il vantaggio è il controllo: il codice e il contesto rimangono sulla tua macchina, e scegli il modello, la sua quantizzazione e la dimensione del contesto in base al tuo hardware.

#Permessi: cosa può fare l'agente senza chiederti il permesso

Un'idea comune è che l'agente non modifichi nulla senza il tuo accordo. Questo non è il comportamento predefinito. La documentazione di OpenCode indica che, senza configurazione, la maggior parte dei permessi è impostata su allow, cioè le relative azioni vengono eseguite senza chiedere; solo alcuni, come external_directory e doom_loop, sono impostati su ask. La lettura dei file .env è negata per impostazione predefinita, tranne quella di .env.example.

Per un agente che gestisce un modello locale meno affidabile, è prudente adottare impostazioni più restrittive. Il file opencode.json accetta una sezione permission in cui ogni azione può assumere il valore allow, ask o deny, anche con una regola globale * impostata su ask.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": { "*": "ask" }
}

#OpenCode, Cline o Aider: quale scegliere

Tutti e tre utilizzano l'API di Ollama; provare i due più vicini alle tue abitudini richiede un'ora ed è più utile di un confronto. Se cerchi il completamento inline anziché un agente, dai un'occhiata a Tabby.

#Risoluzione dei problemi

Il modello non appare

Il nome nel file opencode.json non corrisponde a ollama list. Copia il nome esatto, incluso il tag. Con ollama launch, un modello definito solo in opencode.json non appare nel suo selettore.

L'agente dimentica ciò che ha appena letto

Il contesto è troppo breve: passa a 64.000 token (OLLAMA_CONTEXT_LENGTH) e verifica con ollama ps.

Connessione rifiutata

Il server Ollama non è in esecuzione o non è in ascolto sulla porta predefinita 11434. Prova ollama list, poi l'URL di baseURL.

Chiamate agli strumenti che falliscono

Il modello non gestisce bene gli strumenti. Usa un modello contrassegnato tools nella libreria Ollama.

Risposte molto lente

Il modello e il suo contesto superano la capacità della VRAM e una parte viene eseguita sul processore. Riduci il contesto, la dimensione del modello o la quantizzazione.

#Per approfondire

• Cline + Ollama in VS Code
• Aider + Ollama nel terminale
• Tabby: autocompletamento locale del codice
• Scegliere la quantizzazione
• Comprendere la finestra di contesto
• Installare Ollama in 5 minuti

• Fonte: Ollama, integrazione OpenCode
• Fonte: Ollama, lunghezza del contesto
• Fonte: documentazione OpenCode
• Fonte: permessi OpenCode