Installazione e configurazione di Claude Code per Ollama, llama.cpp e tariffe.

Coding agenzionale, ora con backend di modelli locali.

Indice

Claude Code non è un sistema di completamento automatico con un marketing migliore. È uno strumento di programmazione agentico: legge la tua codebase, modifica i file, esegue comandi e si integra con i tuoi strumenti di sviluppo.

Questa differenza è importante perché l’unità di lavoro smette di essere “una riga di codice” e diventa “un task con uno stato finale”.

Anthropic delimita chiaramente la distinzione: il completamento del codice suggerisce la riga successiva mentre digiti, mentre Claude Code opera a livello di progetto, pianifica attraverso più file, esegue modifiche, lancia test e itera sugli errori. Nella pratica, questo lo rende simile a un ingegnere junior nativo del terminale che può eseguire compiti veloci, ma ha ancora bisogno di revisione.

Questa tensione tra velocità e supervisione è ciò che molte persone raggruppano sotto il termine “vibe coding”; Che cos’è il Vibe Coding? analizza il termine, le sue origini e come si manifestano l’efficienza e il rischio nella pratica.

laptop-homeresver-claude-code-coffee-books

Un dettaglio facile da perdere scorrendo la documentazione: il CLI del terminale (e l’interfaccia di VS Code) può essere configurato per utilizzare provider di terze parti. È qui che entrano in gioco Ollama e llama.cpp.

Una volta che Claude Code punta a un endpoint HTTP locale, i compromessi relativi al runtime, all’hardware e all’hosting rimangono fuori dal client; questo confronto sull’hosting LLM nel 2026 allinea Ollama, stack di inferenza dedicati e opzioni cloud in un unico punto.

Per vedere come Claude Code si inserisce accanto ad altri flussi di lavoro di coding assistito da AI e delivery, questa guida agli strumenti per sviluppatori AI riunisce assistenti in stile Copilot, automazione e pattern degli editor in un unico punto.

Per una panoramica strumento per strumento degli assistenti di coding nella stessa categoria, Confronto Assistenti di Coding AI analizza Cursor, Copilot, Cline e gli altri a un livello più alto rispetto a questa guida di installazione.

Installazione e avvio rapido di Claude Code

Opzioni di installazione e implicazioni

Esistono diversi percorsi di installazione, e non sono equivalenti:

  • Gli script di installazione nativi sono l’opzione “sempre aggiornata” perché si auto-aggiornano.
  • Homebrew e WinGet sono l’opzione “cambiamento controllato” perché aggiorni esplicitamente.

Comandi di installazione (avvio rapido ufficiale):

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

:: Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Quindi avvia una sessione interattiva all’interno di una cartella del progetto:

cd /path/to/your/project
claude

Login e tipi di account

Claude Code ha bisogno di un account per funzionare in modalità first-party. Il flusso di avvio rapido supporta il login tramite un abbonamento Claude (Pro, Max, Team, Enterprise), un account Console (crediti API) o provider cloud supportati. Una nota operativa utile: al primo login nella Console, viene creato uno spazio di lavoro “Claude Code” per il tracciamento centralizzato dei costi.

Configurazione di Claude Code: settings.json e variabili d’ambiente

Se Claude Code sembra magico quando funziona, spesso sembra “misterioso” quando non funziona. La cura è capire la sua stratificazione di configurazione e le poche variabili d’ambiente che contano davvero.

File di configurazione e precedenza

Le impostazioni di Claude Code sono gerarchiche, con tre file rivolti agli sviluppatori:

  • Ambito utente, si applica ovunque: ~/.claude/settings.json
  • Ambito progetto, condiviso in un repo: .claude/settings.json
  • Ambito locale, override per macchina: .claude/settings.local.json (ignorato da git)

La precedenza è (dalla più alta alla più bassa): policy gestita, flag CLI, locale, progetto, utente. Questo ordine spiega diversi momenti di “perché la mia configurazione è ignorata”.

Puoi gestire le impostazioni in modo interattivo tramite il comando /config, che apre un’interfaccia di impostazioni all’interno del REPL.

Variabili d’ambiente che controllano il routing del provider

Claude Code può essere guidato a runtime tramite variabili d’ambiente. Due stranezze comportamentali meritano di essere trattate come vincoli di design:

  1. Se ANTHROPIC_API_KEY è impostato, Claude Code userà la chiave invece di un abbonamento Claude, anche se sei loggato. In modalità print (-p) la chiave è sempre utilizzata se presente.

  2. Se ANTHROPIC_BASE_URL punta a un host non first-party (un proxy, gateway o server locale), alcune funzionalità sono intenzionalmente conservative. Ad esempio, la ricerca di strumenti MCP è disabilitata di default a meno che tu non la riabiliti esplicitamente.

Un pattern minimale “usa un gateway” è questo:

export ANTHROPIC_BASE_URL=https://your-gateway.example
export ANTHROPIC_API_KEY=sk-your-key

Nota sul gateway: Claude Code si aspetta determinati formati API. Per il formato Anthropic Messages, il gateway deve esporre /v1/messages e /v1/messages/count_tokens e deve inoltrare gli header anthropic-beta e anthropic-version. Se un gateway rifiuta quegli header, esiste un’opzione dedicata per rimuovere i beta sperimentali.

Selezione del modello in Claude Code quando non si usa Anthropic direttamente

Claude Code ha il concetto di alias (opus, sonnet, haiku) e supporta anche il fissaggio di ID di modello specifici. Esiste anche un allowlist che può limitare ciò che gli utenti possono selezionare nel selettore del modello, anche quando instradati tramite provider di terze parti.

Un pattern pragmatico è impostare un modello iniziale e limitare il selettore, quindi fissare ciò che “default” risolve tramite env:

{
  "model": "claude-sonnet-4-5",
  "availableModels": ["claude-sonnet-4-5", "haiku"],
  "env": {
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-5"
  }
}

Esecuzione di LLM self-hosted tramite Ollama

Ollama è attualmente il modo a minore attrito per far funzionare Claude Code su modelli non-Anthropic, perché espone un’API compatibile con Anthropic a cui Claude Code può parlare.

Configurazione rapida con ollama launch

Se hai Ollama installato e in esecuzione, il percorso veloce è:

ollama launch claude

O specifica un modello all’avvio:

ollama launch claude --model glm-4.7-flash

Configurazione manuale con variabili d’ambiente esplicite

La documentazione sull’integrazione Ollama descrive un cablaggio manuale semplice dove Claude Code parla a Ollama tramite l’endpoint API compatibile con Anthropic:

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434

claude --model qwen3.5

Questo pattern è opinato in un modo utile: tratta il “routing del provider” come una preoccupazione ambientale, non qualcosa che clicchi in una GUI.

Verifica della realtà della finestra di contesto

Il coding agentico è affamato di contesto. Ollama lo sottolinea bruscamente: Claude Code richiede una finestra di contesto ampia e consiglia almeno 64k token. Se il tuo modello locale si ferma a 8k o 16k, Claude Code funzionerà comunque, ma la promessa “a livello di progetto” diventa fragile.

Per un comportamento pratico su modelli locali in una configurazione simile di agente terminale (Ollama e llama.cpp, task di coding e note oneste sui fallimenti), Migliori LLM per OpenCode - Testati Localmente è un utile cross-check quando stai creando una shortlist di tag GGUF o Ollama per Claude Code.

Esecuzione di LLM self-hosted tramite llama.cpp

llama.cpp è attraente per il motivo opposto: non cerca di essere una piattaforma. È un server veloce e leggero che può esporre sia rotte compatibili con OpenAI che una rotta compatibile con l’API Anthropic Messages.

Per i percorsi di installazione, il comportamento di llama-cli e llama-server oltre ai snippet qui sotto, Avvio rapido llama.cpp con CLI e Server è il riferimento end-to-end.

Cosa eseguire sul lato server

Il server HTTP llama.cpp (llama-server) supporta un’API Messages compatibile con Anthropic a POST /v1/messages, con streaming tramite SSE. Offre anche count_tokens a /v1/messages/count_tokens.

Due dettagli contano per Claude Code:

  • Il server non fa esplicitamente affermazioni forti sulla piena compatibilità con la specifica dell’API Anthropic, ma afferma che funziona abbastanza bene per molte app.
  • L’uso degli strumenti richiede l’avvio di llama-server con il flag –jinja. Se lo perdi, Claude Code si comporterà come se avesse improvvisamente dimenticato come essere un agente.

Un’esecuzione locale minimale è questa:

# Compila o scarica llama-server, poi esegui con un modello GGUF
./llama-server -m /models/your-model.gguf --jinja --host 127.0.0.1 --port 8080

Se vuoi un confine di autenticazione rigido, llama-server può essere configurato con una chiave API:

./llama-server -m /models/your-model.gguf --jinja --api-key my-local-key --host 127.0.0.1 --port 8080

Punta Claude Code verso llama-server

Con il server in esecuzione, il lato Claude Code è per lo più un override dell’URL base:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8080
export ANTHROPIC_API_KEY=my-local-key   # solo se hai abilitato --api-key su llama-server

claude --model your-model-alias

Se non imposti una chiave API o un token di autenticazione, Claude Code potrebbe cercare di tornare al login dell’abbonamento, che è la fonte di molti reclami sul “perché sta aprendo un browser”.

Controlli di salute e primo triage dei fallimenti

llama-server espone un semplice endpoint di salute che restituisce “loading model” finché il modello non è pronto, e “ok” quando è utilizzabile. Quando Claude Code sembra bloccarsi sulla prima richiesta, controllare /health è un modo rapido per distinguere un “bug di configurazione client” da “server ancora in caricamento”.

Prezzi e modello di costo

Il pricing di Claude Code è meno legato all’“acquisto di un CLI” e più a “quale rail di fatturazione supporta i token”.

I piani di abbonamento includono Claude Code

Anthropic include Claude Code nei livelli di abbonamento a pagamento Claude. A partire da aprile 2026, la lista dei prezzi pubblicata indica:

  • Pro a $17 al mese con uno sconto annuale ($200 fatturati in anticipo), o $20 fatturati mensilmente, e include Claude Code.
  • Piani Max a partire da $100 al mese.
  • Piani Team con prezzo per posto, con un posto standard a $20 per posto al mese fatturato annualmente ($25 mensile) e un posto premium a $100 per posto al mese fatturato annualmente ($125 mensile).

Pricing per token API

Se usi Claude Code tramite fatturazione API, i costi seguono i tassi per token. Anthropic pubblica prezzi per milione di token (MTok) per modelli come:

  • Haiku 4.5 a $1/MTok input e $5/MTok output.
  • Sonnet 4.5 a $3/MTok input e $15/MTok output.
  • Opus 4.5 a $5/MTok input e $25/MTok output.

Controlli dei costi nel CLI

La modalità print (-p) supporta cap budget diretti come –max-budget-usd, che è utile quando stai scriptizzando task e vuoi una spesa prevedibile.

All’interno delle sessioni interattive, /cost mostra le statistiche di utilizzo dei token.

I backend locali cambiano la fatturazione, non la fisica

Instradare Claude Code verso Ollama o llama.cpp può rimuovere le fatture API per token, ma non rende il lavoro gratuito. Stai scambiando i costi cloud con compute locale, memoria e “qualcuno possiede l’uptime”. Per alcune squadre, questo compromesso è l’intero punto.

Flusso di lavoro tipico: dal piano alla PR

Il mio pregiudizio è che Claude Code è più forte quando lo tratti come un motore di workflow, non come un chatbot. Gli strumenti suggeriscono questo.

Inizia con il modello di permessi, non con il prompt

Claude Code è gated per design. La documentazione descrive un modello a livelli: le operazioni di sola lettura come letture di file e grep sono consentite, mentre i comandi bash e le modifiche ai file richiedono approvazione.

Le modalità di permesso esistono per gestire l’attrito. Nel CLI puoi ciclare le modalità con Shift+Tab (default -> acceptEdits -> plan). La modalità Plan legge e propone modifiche ma non modifica. La modalità acceptEdits permette a Claude Code di creare e modificare file nella tua directory di lavoro senza chiedere conferma, pur chiedendo ancora conferma per comandi con effetti collaterali fuori dalla sua lista sicura.

La modalità Auto è un’opzione più recente che riduce i prompt delegando le approvazioni a un classificatore, posizionato come un percorso intermedio più sicuro tra prompt costanti e disabilitare completamente i prompt. Richiede una versione minima di Claude Code e requisiti specifici di piano e modello.

Usa i comandi integrati per mantenere le sessioni oneste

Alcuni comandi trasformano Claude Code da “assistente” a “strumento”:

  • /init genera una guida di progetto CLAUDE.md, che è un modo leggero per alimentare contesto coerente.
  • /diff offre una vista interattiva delle modifiche, inclusi diff per turno.
  • /rewind ti permette di fare rewind alla conversazione e/o codice a un punto precedente, usando checkpoint.
  • /debug abilita il log di debug a metà sessione.
  • /doctor diagnostica e verifica la tua installazione e impostazioni.

Questi non sono gimmick; sono le barriere di sicurezza su cui ti appoggi quando un agente modifica più di quanto ti aspettavi.

Quando passare a non-interattivo

Per task one-shot (spiegare, riassumere, generare un piano di patch), la modalità print è un buon adattamento:

claude -p "Riassumi l'architettura del repository e elenca i moduli più rischiosi"

Esce dopo la risposta, il che funziona bene negli script e nella CI.

Checklist di risoluzione dei problemi

La maggior parte dei problemi con Claude Code sono problemi di configurazione in maschera. Ecco una checklist che mappa i sintomi comuni al meccanismo sottostante.

Claude Code continua a chiedere di accedere mentre si usa un server locale

Questo tipicamente significa che Claude Code sta ancora cercando di usare l’autenticazione first-party dell’abbonamento. Assicurati di impostare una modalità di autenticazione esplicita per il proxy:

  • Imposta ANTHROPIC_API_KEY per i gateway che si aspettano X-Api-Key.
  • Oppure imposta ANTHROPIC_AUTH_TOKEN per i gateway che usano Authorization Bearer.

Ricorda che ANTHROPIC_API_KEY sovrascrive l’uso dell’abbonamento anche se sei loggato, e in modalità interattiva potresti dover approvare quella sovrascrittura una volta.

Il gateway genera errori sugli header anthropic-beta

Alcuni gateway rifiutano header sconosciuti o campi beta. Esiste una variabile d’ambiente progettata proprio per questa modalità di fallimento:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

La documentazione del gateway LLM nota inoltre che potresti averne bisogno quando usi il formato Anthropic Messages con Bedrock o Vertex.

Le chiamate agli strumenti non funzionano su llama.cpp

Controlla due volte i flag del server. llama-server documenta che l’uso degli strumenti richiede il flag –jinja. Senza di esso, il server può rispondere, ma il loop dell’agente si degraderà.

I prompt di permesso interrompono ogni comando

Questo può essere normale, a seconda della modalità e delle regole di permesso. Le opzioni includono:

  • Passare temporaneamente a acceptEdits (le modifiche ai file scorrono più velocemente).
  • Scrivere regole di permesso esplicite per comandi bash noti sicuri in settings.json.
  • Usare /sandbox per isolare lo strumento bash riducendo i prompt.
  • Valutare la modalità auto se il tuo piano e versione lo supportano, come un compromesso.

Qualcosa sembra strano e hai bisogno di osservabilità

Usa gli strumenti integrati:

  • /doctor per validare installazione e impostazioni.
  • /debug per iniziare a catturare i log da quel punto in poi.
  • Se sei in modalità print, considera un budget massimo stretto e un numero massimo di turni per mantenere gli esperimenti limitati.